Audit and condense docs and tests

This commit is contained in:
2026-09-12 17:54:26 +02:00
parent 224a048f85
commit 69dc3891d1
11 changed files with 118 additions and 2059 deletions

File diff suppressed because it is too large Load Diff

View File

@@ -1,182 +1,47 @@
# Cliphoard hardening and completion checklist
# Cliphoard hardening checklist
This is the persistent implementation checklist for the long-horizon audit goal.
Items are checked only after the live code has been built/tested and the relevant
behavior has evidence. Documentation and comments are not acceptance evidence.
This is the only persistent project checklist. Check an item only after live
code and an appropriate test or desktop/package observation support it.
## Iteration protocol
## Security and data
Each bounded iteration must:
- [x] SQLCipher storage with manually entered, non-persisted passphrase.
- [x] Wrong-passphrase rejection and encrypted round-trip coverage.
- [x] Explicit migration from legacy plaintext history.
- [x] Optional removal of retained plaintext migration backups.
- [x] User-only permissions for data, config, logs, lock, and socket.
- [x] Bounded clipboard reads and no clipboard contents in normal logs.
- [ ] Review and test crash, swap, and snapshot exposure of plaintext in memory.
1. make a small, reviewable change;
2. run the narrowest relevant tests plus the build/check needed for the change;
3. update this checklist with observed evidence;
4. commit the iteration;
5. re-enter Nova Emergent guidance before selecting the next iteration.
## Product behavior
## Privacy and data protection
- [x] Capture, deduplicate, search, copy, paste, pin, unpin, delete, clear,
pause, timestamps, multiline details, and pinned-row styling.
- [x] Mint-friendly `Ctrl+Alt+V` popup shortcut and `Ctrl+Alt+R` pause shortcut.
- [x] Tray popup, pause state, and graceful Quit action.
- [x] Single-instance lock and show/toggle command.
- [ ] Complete real Cinnamon/X11 acceptance of shortcut, focus/paste, tray,
opacity, pause, migration, and quit behavior.
- [x] Replace the production plaintext SQLite open path with SQLCipher-backed
storage unlocked by a manually entered passphrase; the passphrase/key is not
persisted (30 GUI-feature tests and GUI build, 2026-09-12).
- [ ] Add first-run unlock, wrong-passphrase, locked-startup, and passphrase
change flows with memory-conscious handling and no clipboard content in
errors/logs.
- [x] Migrate existing plaintext history only after explicit user confirmation,
verify encrypted output, and document that old copies/backups remain
separately exposed until removed (31 GUI-feature tests and GUI build,
2026-09-12).
- [ ] 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.
## Delivery
- [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,
2026-09-12).
- [x] Expire unpinned clipboard history older than the 30-day default at
startup, while preserving pinned entries (25 X11-feature tests and Docker
GTK/X11/package build, 2026-09-12).
- [x] Enforce `max_entry_bytes` in the asynchronous X11 reader before UTF-8
conversion and persistence (26 X11-feature tests and Docker GTK/X11/package
build, 2026-09-12).
- [x] Create database, log, config, lock, and runtime directories with private permissions (mode probe and Docker build, 2026-09-10).
- [x] Wrap the GUI passphrase in zeroizing memory and drop it after SQLCipher
unlock; reject symlinked database inspection/migration (32 GUI-feature tests
and GUI build, 2026-09-12).
- [x] Offer explicit cleanup of retained plaintext migration backups, while
warning that filesystem snapshots and external backups are outside its scope
(32 GUI-feature tests and GUI build, 2026-09-12).
- [x] Handle pre-existing overly-permissive database/log permissions safely (existing database and date-suffixed log regression tests, 17 tests and Docker build, 2026-09-10).
- [x] Add tests/probes for file modes under permissive umasks (database regression test plus runtime probe, 2026-09-10).
- [x] Confirm no normal log path emits clipboard contents (audited all `tracing` call sites; errors carry operation context only, 2026-09-10).
- [x] Add bounded daily log rotation with seven-file startup pruning (17 tests and Docker GTK/X11 build, 2026-09-10).
## Clipboard capture and X11 behavior
- [ ] Keep clipboard monitoring event-driven on the normal X11 path.
- [x] Replace the fallback 250 ms blocking clipboard poll with a safe degraded mode (capture disabled when XFixes is unavailable; 2026-09-10).
- [x] Move watcher-triggered clipboard reads off the GTK main thread (Docker GTK/X11 build and tests, 2026-09-10).
- [x] Route toolbar copy/paste through a persistent asynchronous X11 worker (Docker GTK/X11 build, 2026-09-10).
- [x] Route hotkey/show-triggered focus lookup through the X11 worker (Docker GTK/X11 build, 2026-09-10).
- [x] Move clipboard writes, focus lookup, and paste injection off the GTK main thread (worker-backed toolbar and keyboard paths; Docker GTK/X11 build, 2026-09-10).
- [x] Support `UTF8_STRING` with `STRING` fallback for textual X11 clipboard reads (X11-enabled tests and Docker GTK/X11 build, 2026-09-10).
- [x] Replace the high-level X11 clipboard transfer with a bounded protocol
read that checks advertised `INCR` sizes, limits property chunks, and uses a
deadline-aware event loop (27 X11-feature tests and Docker GTK/X11/package
build, 2026-09-12).
- [x] Make self-generated clipboard suppression deterministic and race-resistant (queued-write marker lifecycle and Docker GTK/X11 build, 2026-09-10).
- [x] Ensure failed internal clipboard writes cannot poison suppression state (worker reports write success separately; 17 tests and Docker build, 2026-09-10).
- [x] Add unit coverage for configured shortcut parsing and lock-state grab variants (17 tests and Docker GTK/X11 build, 2026-09-10).
- [ ] Verify global shortcut registration, cleanup, conflicts, and configured shortcuts (popup now presents immediately while target-focus capture completes asynchronously).
- [ ] Verify previous-focus capture and paste behavior against real X11 applications.
- [x] Refresh the paste destination while the visible popup is inactive so switching fields/apps does not reuse the original target (27 X11-feature tests and Docker GTK/X11/package build, 2026-09-12); live multi-field acceptance remains pending.
- [x] Preserve entry order after copy/paste and other non-pin actions by avoiding recency updates during clipboard actions; add local human-readable timestamps (`dd.mm.yyyy hh:mm`) to UI status messages (28 X11-feature tests and Docker GTK/X11/package build, 2026-09-12); live GUI acceptance remains pending.
- [x] Preserve readable textual clipboard contents after paste injection fails;
retain the selected entry only when the original clipboard cannot be read or
restored, and show the existing actionable failure status (27 X11-feature
tests and Docker GTK/X11/package build, 2026-09-12).
- [x] Keep the popup hidden after a successful paste so focus remains in the target application; reopen only on failure (Docker GTK/X11 build, 2026-09-10).
- [x] Keep the popup visible for explicit Paste actions while restoring target focus before XTest injection (Docker GTK/X11 build, 2026-09-12).
## UI and lifecycle
- [ ] Make popup close hide the window while the background process continues (code path added; desktop verification pending).
- [ ] Center the popup on the configured/active monitor.
- [x] Keep the X11 popup above other windows and apply 60% opacity while it is
inactive, returning to full opacity when focused; request `_NET_WM_STATE_ABOVE`
through the EWMH client-message protocol as well as the property, and repeat
the request after mapping (27 X11-feature tests and Docker
GTK/X11/package build, 2026-09-12); compositor behavior remains live desktop
evidence.
- [x] Preserve search query and surviving selection after refresh-triggering actions (17 core tests and Docker GTK/X11 build, 2026-09-10).
- [x] Make paused recording unmistakable: switch Pause/Resume button label and styling, add PAUSED to the window title, and expose paused state in the tray title while retaining the reliable normal tray icon; Resume uses a play symbol and keyboard/button transitions stay synchronized (28 X11-feature tests and Docker GTK/X11/package build, 2026-09-12); live tray/title/theme acceptance remains pending.
- [ ] Implement complete keyboard-first navigation and commands.
- [x] Make Escape hide the popup from the keyboard controller (24 X11-feature
tests and Docker GTK/X11/package build, 2026-09-12); live GUI acceptance is
still pending.
- [ ] Ensure copy, paste, pin, delete, clear, pause, and resume have consistent UI feedback.
- [x] Add icon-only copy, paste, and delete controls to every history row, with matching icon prefixes on toolbar actions (27 X11-feature tests, Docker GTK/X11/package build, 2026-09-12); live GUI acceptance remains pending.
- [x] Highlight authoritative case-insensitive substring and fuzzy search matches in result previews, with core-level range tests (28 X11-feature tests and Docker GTK/X11/package build, 2026-09-12); live GUI acceptance remains pending.
- [x] Add double-click-only full-content inspection for multiline entries (single selection does not open details) and confirmation before individual deletion from toolbar, row, or keyboard paths (28 X11-feature tests and Docker GTK/X11/package build, 2026-09-12); live GUI acceptance remains pending.
- [x] Add in-app Help documentation covering features, shortcuts, search ranking, installation, and uninstall/data removal (28 X11-feature tests and Docker GTK/X11/package build, 2026-09-12); content accuracy/live GUI acceptance remains pending.
- [x] Add state-specific icon-only pin/unpin controls on the left of every history row, routed through the existing pin-limit logic (27 X11-feature tests and Docker GTK/X11/package build, 2026-09-12); live GUI acceptance remains pending.
- [x] Give pinned history rows a subtle distinct background while preserving the compact row layout (28 tests and GUI check, 2026-09-12); live GUI acceptance remains pending.
- [x] Document a complete copy/paste installation command block in README and in-app Help (28 tests and GUI check, 2026-09-12).
- [x] Surface actionable status text for keyboard and toolbar action failures, including successful clipboard writes with failed history updates (Docker GTK/X11 build, 2026-09-10).
- [x] Replace the conflict-prone `Ctrl+R` pause shortcut with `Ctrl+Alt+R`, and expose the configured global shortcut in the window title/status (Docker GTK/X11 build; live tray/capture verified, 2026-09-10).
- [x] Use the Mint-friendly `Ctrl+Alt+V` as the default global popup shortcut;
existing config overrides remain supported (27 X11-feature tests and Docker
GTK/X11/package build, 2026-09-12).
- [ ] Verify tray activation/menu behavior and graceful tray unavailability.
- [x] Make the global shortcut and second-instance show request toggle the popup reliably without a delayed focus result reopening it (28 X11-feature tests and Docker GTK/X11/package build, 2026-09-12); live GUI acceptance remains pending.
- [x] Use standard theme icons for the live tray service and expose a standard pause overlay plus a paused primary icon fallback for hosts such as Cinnamon that ignore SNI overlays (28 tests and GUI check, 2026-09-12); live tray acceptance remains pending.
- [x] Keep cloned tray handles from shutting down the shared D-Bus service prematurely by making shutdown ownership reference-counted (D-Bus audit found the previous service disappeared after GTK activation; 28 tests and Docker GTK/X11/package build, 2026-09-12); live tray acceptance remains pending.
- [x] Make `--diagnostics` inspect the running installation without triggering a
show request, and report the log directory plus instance state (20 tests and
Docker GTK/X11/package build, 2026-09-12).
## Configuration and application state
- [x] Apply `log_level` from configuration, with `RUST_LOG` as an explicit override (2026-09-10).
- [x] Remove unreachable configuration persistence methods; configuration is
currently load-and-validate only, matching the actual application surface
(24 X11-feature tests and Docker GTK/X11/package build, 2026-09-12).
- [x] Remove the unimplemented `popup_position` setting (2026-09-10).
- [x] Validate zero/invalid limits and malformed shortcuts with actionable errors (16 core tests and Docker GTK/X11 build, 2026-09-10).
- [x] Ensure configured history, pinned, and byte limits are applied consistently (16 tests and Docker GTK/X11 build, 2026-09-10).
- [x] Remove or integrate the duplicate unused in-memory `History` implementation (SQLite is now the sole history model; 2026-09-10).
- [x] Make database mutations report missing rows and preserve UI state on failure (toggle-pinned and delete regressions; unused setter removed, 2026-09-10).
## Storage and migrations
- [x] Enforce deduplication at the database level with an appropriate constraint/index (migration and 16 core tests, Docker GTK/X11 build, 2026-09-10).
- [x] Add migration coverage and recovery behavior for schema failures (failed migration rolls back its version marker and a repaired schema retries successfully; 18 tests and Docker build, 2026-09-10).
- [x] Test persistence, trimming, pinning, deletion, and missing-row mutation failure paths (20 tests and Docker build, 2026-09-10).
- [ ] Confirm startup cleanup and shutdown cleanup under crashes and interrupted runs.
- [x] Retain a tray shutdown handle and stop the ksni service during normal
application teardown (20 tests and Docker GTK/X11/package build, 2026-09-12).
- [ ] Add interruptible shutdown/join handling for X11 clipboard and hotkey
event workers; do not regress to a blocking GTK-thread polling loop.
- [x] Join the instance listener, bound incomplete client reads, and remove its socket during normal guard shutdown (19 tests and Docker GTK/X11 build, 2026-09-10).
## Build, packaging, and acceptance evidence
- [x] Core tests pass: 20 tests observed after storage mutation failure coverage on 2026-09-10.
- [x] X11-feature tests pass: 24 tests, including rejection of `None` and
`PointerRoot` as paste targets (plus Docker GTK/X11/package build,
2026-09-12).
- [x] Reject symlinked config and database paths before reads, permission
changes, or SQLite opens (27 X11-feature tests and Docker GTK/X11/package
build, 2026-09-12).
- [x] Rust formatting check passes on 2026-09-10.
- [x] X11-only cargo check passes on 2026-09-10.
- [x] Full GTK/X11 build passes in the declared Docker environment (Docker build, 2026-09-10).
- [x] README contains only practical source-build, package-install,
uninstall, autostart, data-removal, and usage instructions.
- [x] Release `.deb` contains the executable, desktop entry, icon, XDG
autostart entry, and the canonical README.
- [x] Docker builds and tests the GUI feature set before packaging.
- [ ] Add automated dependency/security scanning when the toolchain provides it.
- [ ] Clippy passes with warnings treated as errors.
- [x] Release package contents and runtime dependencies are verified after the
SQLCipher/OpenSSL build; package includes the encrypted-storage binary,
launcher, icon, and autostart entry, with SQLite/OpenSSL bundled (2026-09-12).
- [ ] 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
## Test policy
- Full GTK/X11 checking is available through Docker; local GTK/GLib development
packages are still not installed.
- Clippy is unavailable in the current Rust toolchain.
- No GUI, X11, Cinnamon, or packaging integration tests are present in the tree.
- X11 paste now rejects non-concrete focus values before injecting keystrokes;
real application-target acceptance remains manual evidence.
- Bounded clipboard reads protect Clipb(h)oard's transfer and retained buffers;
X11 selection owners can still consume resources before responding, which is
outside the requesting client's control.
- Diagnostics previously printed a fixed log filename even though the rolling
logger creates date-suffixed files; this is now reported as the log directory.
- Path hardening rejects final-file symlinks; parent-directory symlink,
ownership, and no-follow atomic-open guarantees remain future hardening.
- The initial implementation is now committed; future work must keep the tree
clean at each checkpoint.
- [x] Audited the inline tests against current behavior; removed one path-shape
smoke test and stale documentation-coupled naming. The remaining 31 tests
cover data-loss, ordering, privacy, bounds, migration, lifecycle, or parsing
behavior; GUI/X11 acceptance remains manual where headless tests cannot prove
it.
- Unit tests must protect data-loss, ordering, privacy, bounds, migration,
lifecycle, or parsing behavior.
- GUI/X11 behavior that cannot be exercised headlessly remains explicitly
marked as manual acceptance, not represented by a green unit-test count.
- Passphrase rotation is intentionally out of scope for this goal.

View File

@@ -1,45 +0,0 @@
# Cliphoard shipping checklist
This checklist tracks the MVP completion criteria from `BIBLE.md`. Items are
checked only after implementation and an evidence-producing verification.
## Foundation
- [x] Rust core, SQLite migrations, TOML defaults, fuzzy search
- [x] Deduplication, pinning, limits, deletion, and clear-history semantics
- [x] Dockerized GTK/X11 build environment
- [x] `.deb` with runtime dependencies, desktop file, autostart file, and icon
## Desktop behavior
- [x] Background-only startup with popup show/toggle command (live Docker/X11 smoke test)
- [x] Single-instance lock and second-invocation show/toggle behavior (live Docker smoke test)
- [x] `--show` launcher returns while the owned background process continues
- [x] X11 global shortcut registration and clear conflict reporting (live Docker/X11 test)
- [x] Visible copy, paste, pin, delete, clear-history, and pause controls
- [x] Cinnamon-compatible StatusNotifier/D-Bus tray icon with popup activation
- [ ] X11 event-driven clipboard monitoring
- [ ] Deterministic self-generated clipboard suppression
- [ ] Popup centered on the active monitor
- [ ] Keyboard navigation, copy, delete, pin/unpin, and clear-history commands
- [ ] Pause Recording
- [ ] X11 paste into the previously focused application
- [ ] Paste failure leaves content on the clipboard and reports the error
## Reliability and privacy
- [ ] File-backed XDG logging without clipboard contents in normal logs
- [ ] Startup/shutdown cleanup and recoverable optional-feature failures
- [ ] Configurable shortcut and limits applied by the running application
- [ ] Autostart setting has real effect
- [ ] Diagnostics report actual backend and registration state
## Release acceptance
- [x] Docker tests and GUI release build pass
- [x] Package contents and dependency metadata validated
- [ ] Manual Cinnamon/X11 acceptance run completed
- [x] User-facing install/test instructions updated
Update this file as each item earns evidence; do not mark an item complete from
code inspection alone when it requires a live desktop check.

View File

@@ -14,7 +14,7 @@ RUN apt-get update \
WORKDIR /workspace
COPY . .
RUN cargo test --locked \
RUN cargo test --locked --all-features \
&& cargo build --release --locked --features gui
RUN packaging/build-deb.sh

152
README.md
View File

@@ -1,120 +1,80 @@
# Cliphoard
Cliphoard is a small, local-only, keyboard-first clipboard history utility for Linux/X11.
Local, keyboard-first clipboard history for Linux/X11. History is encrypted
with SQLCipher and unlocked with a passphrase that Cliphoard does not store.
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 a `.deb`
## Build and install from source
From the repository root, copy/paste this complete block:
```bash
sudo apt update
sudo apt install cargo rustc dpkg-dev libgtk-4-dev libdbus-1-dev libx11-dev libxfixes-dev libxtst-dev pkg-config
cargo build --release --features gui
packaging/build-deb.sh
sudo apt install ./target/cliphoard_0.1.0_amd64.deb
```
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:
Install the package on Debian, Ubuntu, or Mint:
```bash
sudo apt install ./cliphoard_0.1.0_amd64.deb
```
If `apt` is unavailable, use:
The package installs the `cliphoard` command, desktop launcher, tray icon,
autostart entry, and a copy of this README at
`/usr/share/doc/cliphoard/README.md`. Start it from the desktop menu, tray, or
with `cliphoard`.
On first start, enter a passphrase. An older plaintext database is migrated
only after confirmation; Cliphoard then offers to remove its retained backup.
## Build from source
Run this from the repository root:
```bash
sudo dpkg -i ./cliphoard_0.1.0_amd64.deb
sudo apt-get install -f
sudo apt update
sudo apt install cargo rustc dpkg-dev libgtk-4-dev libdbus-1-dev libx11-dev libxfixes-dev libxtst-dev pkg-config
cargo test --locked --all-features
cargo build --release --locked --features gui
packaging/build-deb.sh
sudo apt install ./target/cliphoard_0.1.0_amd64.deb
```
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
cargo test
cargo run -- --diagnostics
```
To build the desktop application on Debian/Ubuntu, install the native dependencies first:
```bash
sudo apt install cargo rustc libgtk-4-dev libpango1.0-dev libdbus-1-dev libx11-dev libxfixes-dev libxtst-dev pkg-config
cargo run --features gui
```
The repository also includes an isolated Docker build that installs all build
headers, runs tests, compiles the GTK/X11 backend, and creates an installable
`.deb`:
An isolated Docker build produces the same package:
```bash
docker build -t cliphoard-builder .
docker run --rm -v "$PWD/target:/out" cliphoard-builder
```
The resulting package declares its runtime libraries, so Debian/Ubuntu users
can install it with `sudo apt install ./target/cliphoard_0.1.0_amd64.deb` and
the package manager will resolve GTK/X11 runtime dependencies automatically.
## Use
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 tray menu also has
`Quit Cliphoard`, which stops background recording and exits the process.
- `Ctrl+Alt+V` opens or hides the popup.
- `Ctrl+Alt+R` pauses or resumes recording.
- Enter copies; `Ctrl+Enter` pastes; Escape hides the popup.
- Double-click an entry to inspect its full contents.
- The tray menu opens the popup or quits Cliphoard completely.
Runtime files follow XDG conventions:
## Remove or disable autostart
- database: `~/.local/share/cliphoard/cliphoard.db`
- configuration: `~/.config/cliphoard/config.toml`
- log state: `~/.local/state/cliphoard/`
Remove the package and its system autostart entry:
On first start, Cliphoard asks for a passphrase. The history database is
encrypted with SQLCipher and the passphrase is never stored. If an older
plaintext history is found, Cliphoard asks before migrating it and keeps the
original as a `.plaintext-backup`, then offers to remove that plaintext backup.
Removing it deletes the file entry; it cannot erase copies already made by
backups, snapshots, or the filesystem.
```bash
sudo apt remove cliphoard
```
The full product contract is in [.agents/BIBLE.md](.agents/BIBLE.md).
If it was installed with `dpkg` and `apt` cannot find it:
```bash
sudo dpkg -r cliphoard
```
Keep Cliphoard installed but disable autostart for your user:
```bash
mkdir -p ~/.config/autostart
printf '%s\n' '[Desktop Entry]' 'Hidden=true' > ~/.config/autostart/io.cliphoard.Cliphoard.desktop
```
Delete local history, configuration, logs, and migration backups after quitting:
```bash
rm -rf ~/.local/share/cliphoard ~/.config/cliphoard ~/.local/state/cliphoard
```
The last command is permanent. Backups and filesystem snapshots are outside
Cliphoard’s control.
Runtime paths are `~/.local/share/cliphoard/cliphoard.db`,
`~/.config/cliphoard/config.toml`, and `~/.local/state/cliphoard/`.

View File

@@ -7,6 +7,7 @@ rm -rf "$package_root"
mkdir -p "$package_root/DEBIAN" \
"$package_root/usr/bin" \
"$package_root/usr/share/applications" \
"$package_root/usr/share/doc/cliphoard" \
"$package_root/usr/share/icons/hicolor/scalable/apps" \
"$package_root/etc/xdg/autostart"
@@ -14,6 +15,7 @@ install -m 0755 target/release/cliphoard "$package_root/usr/bin/cliphoard"
install -m 0644 data/io.cliphoard.Cliphoard.desktop "$package_root/usr/share/applications/io.cliphoard.Cliphoard.desktop"
install -m 0644 data/io.cliphoard.Cliphoard.svg "$package_root/usr/share/icons/hicolor/scalable/apps/io.cliphoard.Cliphoard.svg"
install -m 0644 data/io.cliphoard.Cliphoard-autostart.desktop "$package_root/etc/xdg/autostart/io.cliphoard.Cliphoard.desktop"
install -m 0644 README.md "$package_root/usr/share/doc/cliphoard/README.md"
sed "s/^Version:.*/Version: ${version}/" packaging/debian/control > "$package_root/DEBIAN/control"
dpkg-deb --build --root-owner-group "$package_root" "target/cliphoard_${version}_amd64.deb"

View File

@@ -1,2 +0,0 @@
# Packaging note: the application uses XDG autostart rather than a system service.
# This file intentionally documents that boundary for downstream packagers.

View File

@@ -109,7 +109,7 @@ impl Config {
mod tests {
use super::*;
#[test]
fn defaults_match_bible() {
fn defaults_are_valid() {
let c = Config::default();
assert_eq!(c.history_limit, 100);
assert_eq!(c.pinned_limit, 25);
@@ -143,7 +143,7 @@ fn validate_shortcut(shortcut: &str) -> Result<()> {
let parts: Vec<_> = shortcut.split('+').map(str::trim).collect();
if parts.len() < 2 || parts.last().is_some_and(|key| key.chars().count() != 1) {
anyhow::bail!(
"global_shortcut must end with one key and include a modifier, for example Super+V"
"global_shortcut must end with one key and include a modifier, for example Ctrl+Alt+V"
)
}
for modifier in &parts[..parts.len() - 1] {

View File

@@ -1058,42 +1058,25 @@ 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\
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",
Features\n\
• Records textual clipboard history locally in an encrypted SQLCipher database.\n\
• Search, copy, paste, pin/unpin, delete, and clear history.\n\
• Double-click an entry to inspect its complete multiline contents.\n\n\
Shortcuts\n\
• {} — open or hide the popup.\n\
• Ctrl+Alt+R — pause or resume recording.\n\
• Up/Down — select; Enter copies; Ctrl+Enter pastes.\n\
• Ctrl+P — pin or unpin. Delete — delete after confirmation.\n\
• Ctrl+Delete — clear unpinned history. Escape — hide the popup.\n\n\
Search\n\
Search is case-insensitive and ranks exact, prefix, substring, then fuzzy matches.\n\
Pinned entries stay above unpinned results; matching text is highlighted.\n\n\
Security\n\
Enter the passphrase at startup. It is never stored. Legacy plaintext history is\n\
migrated only after confirmation, then its backup can be removed.\n\n\
Installation and removal\n\
See README.md for the exact source-build, .deb, uninstall, autostart, and data\n\
removal commands. The tray menu includes Quit Cliphoard.\n",
shortcut
);
show_text_dialog(window, "Cliphoard help", &help);

View File

@@ -167,11 +167,6 @@ mod tests {
LOCK.get_or_init(|| Mutex::new(())).lock().unwrap()
}
#[test]
fn runtime_path_is_scoped() {
assert!(runtime_dir().ends_with("cliphoard"));
}
#[test]
fn dropping_guard_removes_instance_socket() {
let _lock = runtime_test_lock();

View File

@@ -203,7 +203,7 @@ fn parse_shortcut(shortcut: &str) -> Result<(xproto::Keysym, xproto::ModMask)> {
let key = parts
.last()
.filter(|key| key.chars().count() == 1)
.context("global shortcut must end with one key, for example Super+V")?;
.context("global shortcut must end with one key, for example Ctrl+Alt+V")?;
let key_char = key.chars().next().unwrap().to_ascii_uppercase();
let keysym = key_char as u32;
let mut modifiers = xproto::ModMask::from(0u8);