Add tray quit action and package removal docs
This commit is contained in:
@@ -16,6 +16,17 @@ Each bounded iteration must:
|
||||
|
||||
## Privacy and data protection
|
||||
|
||||
- [ ] Replace plaintext SQLite with SQLCipher-backed storage unlocked by a
|
||||
manually entered passphrase; never persist the passphrase or database key.
|
||||
- [ ] Add first-run unlock, wrong-passphrase, locked-startup, and passphrase
|
||||
change flows with memory-conscious handling and no clipboard content in
|
||||
errors/logs.
|
||||
- [ ] Migrate existing plaintext history only after explicit user confirmation,
|
||||
verify encrypted output, and document that old copies/backups remain
|
||||
separately exposed until removed.
|
||||
- [ ] Add black-box checks proving a copied database cannot be opened without
|
||||
the passphrase and that the running app can read/write it after unlock.
|
||||
|
||||
- [x] Fail closed when configuration permissions cannot be restricted, and
|
||||
refuse file logging when the state directory or existing log permissions
|
||||
cannot be restricted (24 X11-feature tests and Docker GTK/X11/package build,
|
||||
@@ -137,6 +148,10 @@ Each bounded iteration must:
|
||||
- [x] Package contents and runtime dependencies are verified from a fresh Docker build (2026-09-10).
|
||||
- [ ] Manual Cinnamon/X11 acceptance run completed.
|
||||
- [ ] Automated smoke coverage exists for the primary copy → search → copy/paste flow.
|
||||
- [x] Tray menu includes a graceful Quit action that stops background capture
|
||||
(29 isolated X11-feature tests, GUI build, 2026-09-12).
|
||||
- [x] README separates source-build and `.deb` workflows, including exact
|
||||
install, uninstall, autostart-disable, and personal-data removal commands.
|
||||
|
||||
## Current evidence gaps
|
||||
|
||||
|
||||
61
README.md
61
README.md
@@ -4,7 +4,7 @@ Cliphoard is a small, local-only, keyboard-first clipboard history utility for L
|
||||
|
||||
The core is implemented in Rust with SQLite persistence and TOML configuration. The default build intentionally keeps the GTK/X11 desktop integration behind the `gui` feature so the data model and persistence tests can run on machines without GTK development libraries.
|
||||
|
||||
## Install from a checkout
|
||||
## Build and install from source
|
||||
|
||||
From the repository root, copy/paste this complete block:
|
||||
|
||||
@@ -14,9 +14,63 @@ sudo apt install cargo rustc dpkg-dev libgtk-4-dev libdbus-1-dev libx11-dev libx
|
||||
cargo build --release --features gui
|
||||
packaging/build-deb.sh
|
||||
sudo apt install ./target/cliphoard_0.1.0_amd64.deb
|
||||
cliphoard
|
||||
```
|
||||
|
||||
The last command installs the package. Start Cliphoard from the desktop menu,
|
||||
the tray, or with `cliphoard`.
|
||||
|
||||
## Install from a `.deb`
|
||||
|
||||
You can send `target/cliphoard_0.1.0_amd64.deb` to another Debian/Ubuntu/Mint
|
||||
user. They can install it with:
|
||||
|
||||
```bash
|
||||
sudo apt install ./cliphoard_0.1.0_amd64.deb
|
||||
```
|
||||
|
||||
If `apt` is unavailable, use:
|
||||
|
||||
```bash
|
||||
sudo dpkg -i ./cliphoard_0.1.0_amd64.deb
|
||||
sudo apt-get install -f
|
||||
```
|
||||
|
||||
The package installs the `cliphoard` command, desktop launcher, icon, and
|
||||
automatic startup entry. It does not install a system-wide daemon.
|
||||
|
||||
## Uninstall and disable autostart
|
||||
|
||||
For a package installed with `apt install ./cliphoard_*.deb` or `dpkg -i`,
|
||||
remove it with:
|
||||
|
||||
```bash
|
||||
sudo apt remove cliphoard
|
||||
```
|
||||
|
||||
If the package manager says it cannot find the package, check how the binary
|
||||
was installed and remove the registered Debian package directly:
|
||||
|
||||
```bash
|
||||
dpkg -S "$(command -v cliphoard)"
|
||||
sudo dpkg -r cliphoard
|
||||
```
|
||||
|
||||
To keep Cliphoard installed but disable automatic startup for your user:
|
||||
|
||||
```bash
|
||||
mkdir -p ~/.config/autostart
|
||||
printf '%s\n' '[Desktop Entry]' 'Hidden=true' > ~/.config/autostart/io.cliphoard.Cliphoard.desktop
|
||||
```
|
||||
|
||||
To remove the local history, configuration, and logs as well:
|
||||
|
||||
```bash
|
||||
rm -rf ~/.local/share/cliphoard ~/.config/cliphoard ~/.local/state/cliphoard
|
||||
```
|
||||
|
||||
The final command permanently deletes Cliphoard’s local data. Stop Cliphoard
|
||||
from the tray menu first.
|
||||
|
||||
## Development
|
||||
|
||||
```bash
|
||||
@@ -47,7 +101,8 @@ the package manager will resolve GTK/X11 runtime dependencies automatically.
|
||||
Once installed, Cliphoard runs as a background process. `Ctrl+Alt+V` opens the
|
||||
popup, and `cliphoard --show` requests it without keeping the invoking shell
|
||||
blocked. On Cinnamon, a StatusNotifier tray icon provides another way to open
|
||||
the popup when the desktop panel exposes tray icons.
|
||||
the popup when the desktop panel exposes tray icons. The tray menu also has
|
||||
`Quit Cliphoard`, which stops background recording and exits the process.
|
||||
|
||||
Runtime files follow XDG conventions:
|
||||
|
||||
|
||||
76
src/gui.rs
76
src/gui.rs
@@ -44,6 +44,7 @@ struct UiState {
|
||||
search_query: String,
|
||||
recording: bool,
|
||||
show_requested: Arc<AtomicBool>,
|
||||
quit_requested: Arc<AtomicBool>,
|
||||
}
|
||||
|
||||
struct PendingClipboardAction {
|
||||
@@ -115,6 +116,7 @@ pub fn run(
|
||||
search_query: String::new(),
|
||||
recording: true,
|
||||
show_requested: instance.show_requested(),
|
||||
quit_requested: instance.quit_requested(),
|
||||
}));
|
||||
let startup_config = config.clone();
|
||||
let startup_state = Rc::clone(&shared);
|
||||
@@ -595,8 +597,13 @@ fn build_window(
|
||||
let window_for_events = window.clone();
|
||||
let search_for_events = search_box.clone();
|
||||
let status_for_events = status.clone();
|
||||
let application_for_events = application.clone();
|
||||
glib::timeout_add_local(std::time::Duration::from_millis(250), move || {
|
||||
let mut state = state_for_watch.borrow_mut();
|
||||
if state.quit_requested.load(Ordering::Acquire) {
|
||||
application_for_events.quit();
|
||||
return glib::ControlFlow::Break;
|
||||
}
|
||||
if state.hotkey.as_ref().is_some_and(X11Hotkey::take_triggered) {
|
||||
if window_for_events.is_visible() {
|
||||
window_for_events.set_visible(false);
|
||||
@@ -919,40 +926,45 @@ fn show_text_dialog(window: &ApplicationWindow, title: &str, content: &str) {
|
||||
fn show_help(window: &ApplicationWindow, shortcut: &str) {
|
||||
let help = format!(
|
||||
"Cliphoard help\n\n\
|
||||
Features\n\
|
||||
• Records textual clipboard history locally.\n\
|
||||
• Search, copy, paste, pin/unpin, delete, and clear history.\n\
|
||||
• Double-click an entry to inspect its complete multiline contents.\n\
|
||||
• The popup stays above other windows and becomes translucent when inactive.\n\
|
||||
• Clipboard data stays local; the database is stored with restricted permissions.\n\n\
|
||||
Shortcuts\n\
|
||||
• {} — open or hide the popup.\n\
|
||||
• Ctrl+Alt+R — pause or resume recording.\n\
|
||||
• Up/Down — select an entry; Enter copies it; Ctrl+Enter pastes it.\n\
|
||||
• Ctrl+P — pin or unpin the selected entry.\n\
|
||||
• Delete — delete the selected entry after confirmation.\n\
|
||||
• Ctrl+Delete — clear unpinned history.\n\
|
||||
• Escape — hide the popup.\n\n\
|
||||
Search\n\
|
||||
Search is case-insensitive. Exact matches rank highest, then prefix matches,\n\
|
||||
substring matches, and finally fuzzy character matches. Pinned entries stay\n\
|
||||
above unpinned results. Matching text is highlighted in each result.\n\n\
|
||||
Install\n\
|
||||
Build dependencies: GTK4, D-Bus, X11, XFixes, XTest, pkg-config, Rust, and Cargo.\n\
|
||||
Copy/paste this from the repository root to build and install Cliphoard:\n\
|
||||
sudo apt update\n\
|
||||
sudo apt install cargo rustc dpkg-dev libgtk-4-dev libdbus-1-dev libx11-dev libxfixes-dev libxtst-dev pkg-config\n\
|
||||
cargo build --release --features gui\n\
|
||||
packaging/build-deb.sh\n\
|
||||
sudo apt install ./target/cliphoard_0.1.0_amd64.deb\n\n\
|
||||
Start it with: cliphoard\n\n\
|
||||
Uninstall\n\
|
||||
Copy/paste: sudo apt remove cliphoard\n\
|
||||
Optionally remove the local data directory shown by cliphoard --diagnostics\n\
|
||||
to delete history and logs.\n",
|
||||
Features\n\
|
||||
• Records textual clipboard history locally.\n\
|
||||
• Search, copy, paste, pin/unpin, delete, and clear history.\n\
|
||||
• Double-click an entry to inspect its complete multiline contents.\n\
|
||||
• The popup stays above other windows and becomes translucent when inactive.\n\
|
||||
• Clipboard data stays local; the database is stored with restricted permissions.\n\n\
|
||||
Shortcuts\n\
|
||||
• {} — open or hide the popup.\n\
|
||||
• Ctrl+Alt+R — pause or resume recording.\n\
|
||||
• Up/Down — select an entry; Enter copies it; Ctrl+Enter pastes it.\n\
|
||||
• Ctrl+P — pin or unpin the selected entry.\n\
|
||||
• Delete — delete the selected entry after confirmation.\n\
|
||||
• Ctrl+Delete — clear unpinned history.\n\
|
||||
• Escape — hide the popup.\n\n\
|
||||
Search\n\
|
||||
Search is case-insensitive. Exact matches rank highest, then prefix matches,\n\
|
||||
substring matches, and finally fuzzy character matches. Pinned entries stay\n\
|
||||
above unpinned results. Matching text is highlighted in each result.\n\n\
|
||||
Install\n\
|
||||
Build dependencies: GTK4, D-Bus, X11, XFixes, XTest, pkg-config, Rust, and Cargo.\n\
|
||||
Copy/paste this from the repository root to build and install Cliphoard:\n\
|
||||
sudo apt update\n\
|
||||
sudo apt install cargo rustc dpkg-dev libgtk-4-dev libdbus-1-dev libx11-dev libxfixes-dev libxtst-dev pkg-config\n\
|
||||
cargo build --release --features gui\n\
|
||||
packaging/build-deb.sh\n\
|
||||
sudo apt install ./target/cliphoard_0.1.0_amd64.deb\n\n\
|
||||
Start it with: cliphoard\n\
|
||||
The tray menu includes Quit Cliphoard to stop background recording.\n\n\
|
||||
Uninstall\n\
|
||||
Copy/paste: sudo apt remove cliphoard\n\
|
||||
If apt cannot find it: dpkg -S \"$(command -v cliphoard)\" then sudo dpkg -r cliphoard.\n\
|
||||
Disable autostart without uninstalling:\n\
|
||||
mkdir -p ~/.config/autostart\n\
|
||||
printf '%s\\n' '[Desktop Entry]' 'Hidden=true' > ~/.config/autostart/io.cliphoard.Cliphoard.desktop\n\
|
||||
Remove local history/config/logs after quitting Cliphoard:\n\
|
||||
rm -rf ~/.local/share/cliphoard ~/.config/cliphoard ~/.local/state/cliphoard\n",
|
||||
shortcut
|
||||
);
|
||||
show_text_dialog(window, "Clipb(h)oard help", &help);
|
||||
show_text_dialog(window, "Cliphoard help", &help);
|
||||
}
|
||||
|
||||
fn confirm_delete(
|
||||
|
||||
@@ -17,6 +17,7 @@ pub struct InstanceGuard {
|
||||
_file: File,
|
||||
path: PathBuf,
|
||||
show_requested: Arc<AtomicBool>,
|
||||
quit_requested: Arc<AtomicBool>,
|
||||
stop: Arc<AtomicBool>,
|
||||
listener_thread: Option<std::thread::JoinHandle<()>>,
|
||||
}
|
||||
@@ -55,8 +56,10 @@ impl InstanceGuard {
|
||||
.set_nonblocking(true)
|
||||
.context("failed to configure instance command socket")?;
|
||||
let show_requested = Arc::new(AtomicBool::new(false));
|
||||
let quit_requested = Arc::new(AtomicBool::new(false));
|
||||
let stop = Arc::new(AtomicBool::new(false));
|
||||
let signal = Arc::clone(&show_requested);
|
||||
let quit_signal = Arc::clone(&quit_requested);
|
||||
let should_stop = Arc::clone(&stop);
|
||||
let listener_thread = std::thread::Builder::new()
|
||||
.name("cliphoard-instance".into())
|
||||
@@ -67,8 +70,12 @@ impl InstanceGuard {
|
||||
let _ = stream
|
||||
.set_read_timeout(Some(std::time::Duration::from_millis(100)));
|
||||
let mut command = [0; 4];
|
||||
if stream.read_exact(&mut command).is_ok() && &command == b"show" {
|
||||
signal.store(true, Ordering::Release);
|
||||
if stream.read_exact(&mut command).is_ok() {
|
||||
match &command {
|
||||
b"show" => signal.store(true, Ordering::Release),
|
||||
b"quit" => quit_signal.store(true, Ordering::Release),
|
||||
_ => {}
|
||||
}
|
||||
}
|
||||
}
|
||||
Err(error) if error.kind() == std::io::ErrorKind::WouldBlock => {
|
||||
@@ -86,6 +93,7 @@ impl InstanceGuard {
|
||||
_file: file,
|
||||
path,
|
||||
show_requested,
|
||||
quit_requested,
|
||||
stop,
|
||||
listener_thread: Some(listener_thread),
|
||||
})
|
||||
@@ -99,12 +107,24 @@ impl InstanceGuard {
|
||||
Arc::clone(&self.show_requested)
|
||||
}
|
||||
|
||||
pub fn quit_requested(&self) -> Arc<AtomicBool> {
|
||||
Arc::clone(&self.quit_requested)
|
||||
}
|
||||
|
||||
pub fn signal_show() -> Result<()> {
|
||||
Self::signal_command(*b"show")
|
||||
}
|
||||
|
||||
pub fn signal_quit() -> Result<()> {
|
||||
Self::signal_command(*b"quit")
|
||||
}
|
||||
|
||||
fn signal_command(command: [u8; 4]) -> Result<()> {
|
||||
let mut stream = UnixStream::connect(socket_path())
|
||||
.context("could not contact the running Cliphoard instance")?;
|
||||
stream
|
||||
.write_all(b"show")
|
||||
.context("failed to request the running Cliphoard instance to show")?;
|
||||
.write_all(&command)
|
||||
.context("failed to send command to the running Cliphoard instance")?;
|
||||
Ok(())
|
||||
}
|
||||
|
||||
@@ -170,4 +190,18 @@ mod tests {
|
||||
drop(stream);
|
||||
assert!(!socket_path().exists());
|
||||
}
|
||||
|
||||
#[test]
|
||||
fn quit_command_sets_quit_request() {
|
||||
let _lock = runtime_test_lock();
|
||||
let guard = InstanceGuard::acquire().unwrap();
|
||||
InstanceGuard::signal_quit().unwrap();
|
||||
for _ in 0..20 {
|
||||
if guard.quit_requested().load(Ordering::Acquire) {
|
||||
return;
|
||||
}
|
||||
std::thread::sleep(std::time::Duration::from_millis(10));
|
||||
}
|
||||
panic!("quit command was not received");
|
||||
}
|
||||
}
|
||||
|
||||
35
src/tray.rs
35
src/tray.rs
@@ -63,17 +63,30 @@ impl ksni::Tray for CliphoardTray {
|
||||
|
||||
fn menu(&self) -> Vec<ksni::MenuItem<Self>> {
|
||||
use ksni::menu::StandardItem;
|
||||
vec![StandardItem {
|
||||
label: "Show Cliphoard".into(),
|
||||
icon_name: "edit-paste".into(),
|
||||
activate: Box::new(|_| {
|
||||
if let Err(error) = InstanceGuard::signal_show() {
|
||||
tracing::error!(%error, "failed to show popup from tray menu");
|
||||
}
|
||||
}),
|
||||
..Default::default()
|
||||
}
|
||||
.into()]
|
||||
vec![
|
||||
StandardItem {
|
||||
label: "Show Cliphoard".into(),
|
||||
icon_name: "edit-paste".into(),
|
||||
activate: Box::new(|_| {
|
||||
if let Err(error) = InstanceGuard::signal_show() {
|
||||
tracing::error!(%error, "failed to show popup from tray menu");
|
||||
}
|
||||
}),
|
||||
..Default::default()
|
||||
}
|
||||
.into(),
|
||||
StandardItem {
|
||||
label: "Quit Cliphoard".into(),
|
||||
icon_name: "application-exit".into(),
|
||||
activate: Box::new(|_| {
|
||||
if let Err(error) = InstanceGuard::signal_quit() {
|
||||
tracing::error!(%error, "failed to quit Cliphoard from tray menu");
|
||||
}
|
||||
}),
|
||||
..Default::default()
|
||||
}
|
||||
.into(),
|
||||
]
|
||||
}
|
||||
}
|
||||
|
||||
|
||||
Reference in New Issue
Block a user