Audit and condense docs and tests
This commit is contained in:
1699
.agents/BIBLE.md
1699
.agents/BIBLE.md
File diff suppressed because it is too large
Load Diff
@@ -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.
|
||||
|
||||
@@ -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.
|
||||
@@ -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
152
README.md
@@ -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/`.
|
||||
|
||||
@@ -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"
|
||||
|
||||
@@ -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.
|
||||
@@ -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] {
|
||||
|
||||
55
src/gui.rs
55
src/gui.rs
@@ -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);
|
||||
|
||||
@@ -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();
|
||||
|
||||
@@ -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);
|
||||
|
||||
Reference in New Issue
Block a user