Add tray quit action and package removal docs

This commit is contained in:
2026-09-12 16:52:10 +02:00
parent 6ade499301
commit 390619b818
5 changed files with 179 additions and 50 deletions

View File

@@ -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

View File

@@ -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:

View File

@@ -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(

View File

@@ -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");
}
}

View File

@@ -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(),
]
}
}