From 69dc3891d1b42dc67fe57505b43948fee7c56286 Mon Sep 17 00:00:00 2001 From: haffel Date: Sat, 12 Sep 2026 17:54:26 +0200 Subject: [PATCH] Audit and condense docs and tests --- .agents/BIBLE.md | 1699 ---------------------- .agents/CLIPHOARD_HARDENING_CHECKLIST.md | 209 +-- .agents/SHIP_CHECKLIST.md | 45 - Dockerfile | 2 +- README.md | 152 +- packaging/build-deb.sh | 2 + packaging/cliphoard.service | 2 - src/config.rs | 4 +- src/gui.rs | 55 +- src/lifecycle.rs | 5 - src/platform/linux/x11_events.rs | 2 +- 11 files changed, 118 insertions(+), 2059 deletions(-) delete mode 100644 .agents/BIBLE.md delete mode 100644 .agents/SHIP_CHECKLIST.md delete mode 100644 packaging/cliphoard.service diff --git a/.agents/BIBLE.md b/.agents/BIBLE.md deleted file mode 100644 index c792e11..0000000 --- a/.agents/BIBLE.md +++ /dev/null @@ -1,1699 +0,0 @@ -# Cliphoard — Implementation Bible - -## 0. Mission - -Build **Cliphoard**, a tiny, extremely fast, keyboard-first clipboard history utility. - -Primary target: - -- Linux Mint / Cinnamon -- X11 first-class for v1 - -Future-friendly: - -- Linux Wayland -- Windows -- macOS - -But **do not compromise v1 simplicity to prematurely support every platform**. - -Cliphoard is intentionally small. - -The core workflow is: - -> **Copy normally → press global shortcut → type a few characters → select entry → copy or paste it.** - -The application must feel instantaneous, native, boringly reliable, easy to install, easy to debug, and almost invisible when not being used. - -This is **not** a clipboard productivity suite. - ---- - -# 1. Product Principles - -These principles override feature temptation. - -## 1.1 Minimal - -The application should consist conceptually of: - -- one background process -- one popup window -- one clipboard history -- one pinned collection -- one search box -- one SQLite database -- one config file -- simple logs - -Do not add abstractions, services, windows, menus, dependency layers, or frameworks without a concrete reason. - -## 1.2 Fast - -Expected experience: - -- negligible idle CPU usage -- low memory consumption -- popup appears perceptually instantly -- fuzzy search updates immediately -- clipboard monitoring has effectively no noticeable delay - -Performance should come primarily from simple architecture, not premature optimization. - -## 1.3 Reliable - -Prefer: - -- deterministic behavior -- explicit error handling -- transactions -- atomic state changes -- simple state machines -- clear logging -- graceful fallback behavior - -Avoid cleverness. - -## 1.4 Keyboard-first - -The complete primary workflow must work without a mouse. - -Mouse support is useful, but secondary. - -## 1.5 Local-only - -No: - -- network access -- cloud -- telemetry -- analytics -- accounts -- remote API -- online dependency - -All clipboard data stays on the machine. - -## 1.6 Debuggable - -When something fails, the cause should be discoverable from logs without recompiling the application. - -Avoid swallowing errors. - ---- - -# 2. Recommended Technology Stack - -Use: - -- **Rust** -- **GTK4** -- **SQLite** -- **TOML configuration** - -Linux/X11 platform functionality must be isolated behind backend interfaces. - -Suggested logical architecture: - -```text -src/ -├── main.rs -├── app/ -│ ├── state.rs -│ ├── commands.rs -│ └── lifecycle.rs -├── core/ -│ ├── entry.rs -│ ├── history.rs -│ ├── search.rs -│ └── limits.rs -├── storage/ -│ ├── sqlite.rs -│ └── migrations.rs -├── config/ -│ └── mod.rs -├── platform/ -│ ├── mod.rs -│ └── linux/ -│ ├── x11_clipboard.rs -│ ├── x11_hotkey.rs -│ ├── x11_input.rs -│ └── autostart.rs -├── ui/ -│ ├── window.rs -│ ├── search.rs -│ ├── entry_row.rs -│ └── settings.rs -└── logging.rs -``` - -Exact filenames may change. - -The separation of responsibilities should not. - ---- - -# 3. Platform Abstraction - -All OS-specific behavior must live behind explicit interfaces. - -Conceptually: - -```rust -trait ClipboardBackend { - fn read_text(&self) -> Result>; - fn write_text(&self, text: &str) -> Result<()>; - fn watch(&self, callback: ...) -> Result<()>; -} - -trait HotkeyBackend { - fn register(&self, shortcut: &Shortcut) -> Result<()>; - fn unregister(&self) -> Result<()>; -} - -trait InputBackend { - fn paste_into_active_window(&self) -> Result<()>; -} -``` - -Do not let X11-specific implementation details leak into history, storage, search, or UI logic. - -For v1: - -- implement Linux/X11 properly -- design Wayland/Windows/macOS backends for later -- do not build fake cross-platform abstractions that are never exercised - ---- - -# 4. Core Clipboard Behavior - -## 4.1 Capture - -Automatically capture textual clipboard contents whenever the clipboard changes. - -For v1: - -- text only -- ignore images -- ignore arbitrary binary clipboard formats -- files may be represented only if they naturally arrive as text - -Ignore: - -- empty strings -- zero-length clipboard data -- clipboard events generated internally when necessary - -Whitespace-only strings may be ignored. - -Do not silently modify copied text. - -Clipboard contents must be stored exactly as copied unless explicitly required for hashing/indexing. - ---- - -# 5. Deduplication - -Clipboard history must not accumulate exact duplicates. - -When text is copied: - -1. determine whether identical text already exists -2. if it exists: - - do not create another row - - update its `last_used_at` - - move it to the top of history -3. if it does not exist: - - create a new history entry - -Pinned status must survive deduplication. - -Example: - -```text -History: - -A -B -C -``` - -Copying `C` again becomes: - -```text -C -A -B -``` - -There must still be exactly one `C`. - -Use a content hash for efficient lookup if useful, but always protect against theoretical hash collisions by confirming content equality. - ---- - -# 6. Entries - -Minimum logical fields: - -```text -id -content -content_hash -created_at -last_used_at -pinned -``` - -Optional future-friendly fields are acceptable only if justified. - -Do not add metadata merely because it might someday be useful. - ---- - -# 7. Pinned Entries - -Any entry may be pinned or unpinned. - -Pinned entries: - -- persist indefinitely until manually unpinned/deleted -- are exempt from normal history cleanup -- remain searchable -- are visually distinguishable -- participate in deduplication - -Pinning does not duplicate the entry into another table unless there is a compelling architectural reason. - -Prefer one canonical entry with a `pinned` flag. - ---- - -# 8. Limits - -Provide separate configurable limits: - -```toml -history_limit = 100 -pinned_limit = 25 -``` - -These are independent. - -`history_limit` applies only to unpinned history entries. - -`pinned_limit` applies only to pinned entries. - -When normal history exceeds its limit: - -- remove oldest unpinned entries first - -Pinned entries must never be removed by normal history trimming. - -When pinning would exceed `pinned_limit`: - -- reject the pin operation cleanly -- show a small understandable error -- never silently unpin or delete something else - -Reasonable defaults: - -```toml -history_limit = 100 -pinned_limit = 25 -``` - ---- - -# 9. Maximum Clipboard Entry Size - -Prevent pathological clipboard contents from bloating storage. - -Provide: - -```toml -max_entry_bytes = 1048576 -``` - -Default: - -**1 MiB** - -Entries larger than the limit should not be stored. - -Do not crash. - -Log the event at an appropriate level. - -Optional unobtrusive user feedback is acceptable. - ---- - -# 10. Search - -Search must be fuzzy and effectively instantaneous. - -Search: - -- history -- pinned entries -- entire textual content - -Expected matching behavior: - -- exact matches rank very highly -- exact substring matches rank highly -- fuzzy matches rank beneath stronger matches -- recency breaks ties -- pinned status may provide a modest ranking bonus - -Possible ranking logic: - -```text -exact equality -→ prefix / substring strength -→ fuzzy score -→ pinned bonus -→ recency -``` - -Do not build a complex search index for a few hundred clipboard entries. - -Load lightweight entry data into memory. - -Search in memory. - -SQLite FTS is unnecessary for v1 unless testing demonstrates otherwise. - ---- - -# 11. Popup UI - -The main UI is a small popup. - -Conceptually: - -```text -┌──────────────────────────────────────────────┐ -│ Search clipboard… ⌕ │ -├──────────────────────────────────────────────┤ -│ 📌 ssh user@192.168.1.20 │ -│ 📌 docker compose up -d │ -│ https://example.com/document │ -│ const foo = calculateSomething(...) │ -│ sudo systemctl restart nginx │ -└──────────────────────────────────────────────┘ -``` - -Design principles: - -- minimal chrome -- compact rows -- no unnecessary toolbar -- no permanent sidebar -- no giant headings -- no decorative animation -- no card-heavy UI -- native-feeling GTK widgets -- fast rendering - -Each row should show enough text to identify the clipboard item. - -Long entries should be truncated visually. - -Full content remains stored. - ---- - -# 12. Popup Invocation - -The application runs in the background. - -A configurable global keyboard shortcut opens the popup from anywhere. - -Default suggestion: - -```text -Super+V -``` - -The shortcut must be configurable. - -When opened: - -1. popup appears -2. search field receives focus immediately -3. current entries appear -4. keyboard navigation works immediately - -Avoid requiring a second click. - ---- - -# 13. Popup Position - -Default: - -- center of active monitor - -Possible future setting: - -```toml -popup_position = "active-monitor-center" -``` - -Future options may include cursor position. - -Do not spend excessive v1 effort on advanced positioning. - -Correct multi-monitor behavior matters. - ---- - -# 14. Keyboard Controls - -At minimum: - -```text -Global shortcut - Open/toggle Cliphoard - -Escape - Close popup - -Arrow Up / Down - Move selection - -Enter - Copy selected entry to clipboard - -Ctrl+Enter - Paste selected entry into previously focused application - -Delete - Delete selected entry - -Ctrl+P - Pin/unpin selected entry -``` - -Exact secondary shortcuts may change if GTK/platform conflicts exist. - -The principles must remain: - -- obvious -- keyboard-first -- configurable where necessary -- documented - -Do not overload dozens of obscure shortcuts. - ---- - -# 15. Copy Action - -Selecting `Copy`: - -1. writes the selected entry to the system clipboard -2. marks it recently used -3. moves it to the top according to normal ordering -4. closes the popup by default - -The internal clipboard watcher must not accidentally create a duplicate event. - ---- - -# 16. Paste Action - -Selecting `Paste`: - -1. place selected content onto the clipboard -2. hide the popup -3. restore focus to the previously active application -4. invoke the platform paste action - -For X11, implement this reliably. - -The paste mechanism belongs to the `InputBackend`. - -Do not put input simulation logic in UI code. - -If paste injection fails: - -- leave the selected content on the clipboard -- show/log a useful error -- do not lose data - -This means the user can still manually press `Ctrl+V`. - ---- - -# 17. Clipboard Self-Change Suppression - -Cliphoard itself changes the clipboard when users restore entries. - -These changes must not produce broken behavior such as: - -```text -select old item -→ write clipboard -→ watcher sees clipboard -→ creates another history entry -→ duplicates / loops / reorder weirdness -``` - -Implement explicit self-change handling. - -This must be deterministic. - -Do not rely purely on arbitrary sleep timers. - -A short-lived expected-content marker/hash may be used. - ---- - -# 18. Delete - -Deleting an entry removes it from history and persistent storage. - -Deletion should be immediate. - -Normal individual deletion does not require a confirmation modal. - -Pinned entries may also be deleted deliberately. - ---- - -# 19. Clear History - -Provide: - -**Clear History** - -Meaning: - -> delete all unpinned entries while preserving pinned entries. - -This must be the normal bulk-clear action. - -An optional: - -**Clear Everything** - -may exist, but should require deliberate confirmation because it also deletes pinned entries. - ---- - -# 20. Persistence - -Use SQLite. - -Suggested location: - -```text -~/.local/share/cliphoard/cliphoard.db -``` - -Follow XDG directories where appropriate. - -Database operations must use transactions where multiple related state changes occur. - -SQLite settings should prioritize reliability while remaining lightweight. - -WAL mode may be used if justified. - -Do not keep the database connection architecture more complicated than necessary. - ---- - -# 21. Database Schema - -A reasonable starting schema: - -```sql -CREATE TABLE entries ( - id INTEGER PRIMARY KEY, - content TEXT NOT NULL, - content_hash TEXT NOT NULL, - created_at INTEGER NOT NULL, - last_used_at INTEGER NOT NULL, - pinned INTEGER NOT NULL DEFAULT 0 -); - -CREATE INDEX idx_entries_hash -ON entries(content_hash); - -CREATE INDEX idx_entries_last_used -ON entries(last_used_at DESC); - -CREATE INDEX idx_entries_pinned -ON entries(pinned); -``` - -This is a guideline, not sacred SQL. - -Schema migrations must exist from the start. - -Even migration `001_initial.sql` is enough initially. - -Never rely on deleting users' databases to handle schema changes during development. - ---- - -# 22. Configuration - -Use TOML. - -Suggested path: - -```text -~/.config/cliphoard/config.toml -``` - -Follow XDG configuration directories. - -Suggested v1 config: - -```toml -history_limit = 100 -pinned_limit = 25 -max_entry_bytes = 1048576 - -global_shortcut = "Super+V" - -autostart = true - -popup_position = "active-monitor-center" - -log_level = "info" -``` - -Provide robust defaults if the config file does not exist. - -Malformed config should: - -- not crash the entire application where avoidable -- report exactly what is invalid -- fall back carefully -- preserve the user's broken config for debugging - -Do not silently overwrite malformed user configuration. - ---- - -# 23. Settings UI - -Settings UI is optional but desirable. - -If implemented, it must remain tiny. - -Expose only useful settings: - -- global shortcut -- history limit -- pinned limit -- autostart -- maximum entry size -- popup position -- logging level, if useful - -Do not make a giant preferences application. - -The config file remains understandable and editable manually. - ---- - -# 24. Autostart - -Cliphoard should autostart with the user's graphical session. - -For Linux Mint/X11, use normal desktop autostart mechanisms. - -Prefer an XDG autostart `.desktop` entry. - -The app must also be able to run manually without autostart. - -Autostart behavior should be configurable. - ---- - -# 25. Single Instance - -Only one Cliphoard process may own clipboard monitoring at a time. - -Starting Cliphoard while it is already running should: - -- communicate with the existing instance if practical -- open/toggle the popup -- exit the new process - -At minimum, prevent duplicate background watchers. - -Do not allow two instances to race against the same clipboard/database. - ---- - -# 26. Logging - -Provide useful application logs. - -Suggested path: - -```text -~/.local/state/cliphoard/cliphoard.log -``` - -Respect XDG state directories. - -Supported levels: - -```text -error -warn -info -debug -trace -``` - -Normal default: - -```text -info -``` - -Logs should include: - -- application startup -- application version -- loaded backend -- database initialization/migration failures -- hotkey registration failures -- clipboard backend failures -- paste injection failures -- malformed configuration -- unexpected recoverable errors - -Do not log clipboard contents by default. - -That is a privacy requirement. - -Debug logging should still avoid dumping full clipboard contents unless explicitly enabled by a special developer option. - ---- - -# 27. Privacy - -Clipboard history is sensitive. - -Hard rules: - -- no telemetry -- no network requests -- no cloud sync -- no analytics -- no automatic external crash reporting -- no clipboard content in normal logs - -Provide: - -**Pause Recording** - -When paused: - -- do not store new clipboard changes -- existing history remains accessible - -A tray/menu action or minimal application action is sufficient. - ---- - -# 28. Sensitive Clipboard Support - -Design clipboard ingestion so sensitive entries can eventually be ignored based on platform/application hints. - -Do not over-engineer this in v1. - -If Linux clipboard protocols expose a reliable standard signal indicating secrecy/private content, respect it where practical. - -Password-manager compatibility is desirable. - -Never claim security guarantees the platform cannot provide. - ---- - -# 29. Tray / Background Presence - -If a tray icon is used, keep its menu minimal: - -```text -Open Cliphoard -Pause Recording -Clear History -Settings -Quit -``` - -The application should not require users to interact with the tray during normal use. - -If tray integration creates disproportionate platform complexity, v1 may omit it in favor of application actions accessible from the popup. - ---- - -# 30. Error Handling - -Cliphoard must not panic for ordinary runtime failures. - -Use idiomatic Rust error handling. - -Errors should have context. - -Bad: - -```text -Error: failed -``` - -Good: - -```text -Failed to register global shortcut 'Super+V': -X11 reported that the key combination is already grabbed by another application. -``` - -The user should understand: - -- what failed -- whether Cliphoard can continue -- what they can do about it - -Fatal errors should terminate cleanly with a useful message and log. - ---- - -# 31. Startup Behavior - -Startup sequence should approximately be: - -```text -initialize logging -→ load config -→ establish single-instance ownership -→ initialize database -→ run migrations -→ load clipboard entries -→ apply limits if necessary -→ initialize platform backend -→ register global shortcut -→ initialize GTK application -→ begin clipboard monitoring -→ remain idle -``` - -Exact ordering may differ where required by GTK. - -Failures in optional features should not unnecessarily kill the entire app. - -Example: - -If global shortcut registration fails, the app may remain running and expose an error rather than corrupting data or crashing. - ---- - -# 32. Shutdown Behavior - -On clean shutdown: - -- stop clipboard watcher -- unregister hotkey -- flush necessary state -- close database cleanly -- terminate background resources - -No complicated shutdown orchestration. - -SQLite already handles most persistence. - ---- - -# 33. Ordering - -Default visible ordering: - -1. pinned entries receive appropriate prominence -2. otherwise most recently used/copied first - -When no search query exists, likely show: - -```text -Pinned entries -then -Recent entries -``` - -or interleave them with a clear pinned indicator. - -Choose whichever produces the fastest keyboard workflow. - -Do not maintain entirely separate screens for pinned/history. - ---- - -# 34. Entry Preview - -Rows must efficiently represent: - -- short snippets -- multiline text -- URLs -- code -- commands -- long paragraphs - -Normalize only presentation. - -Do not alter stored content. - -Suggested display: - -- collapse line breaks to spaces for row preview -- truncate after reasonable width -- optionally show line count or character count for large entries - -No syntax highlighting in v1. - ---- - -# 35. Search Empty State - -When search returns nothing: - -```text -No matching clipboard entries -``` - -Do not create elaborate empty-state artwork. - ---- - -# 36. First Launch - -First launch should require no setup. - -Expected: - -1. install -2. launch -3. clipboard tracking starts -4. `Super+V` works - -If `Super+V` conflicts with the desktop environment, detect/report it clearly. - -The application should remain usable through another invocation mechanism. - ---- - -# 37. Packaging - -Primary Linux packaging: - -**`.deb`** - -Target: - -- Ubuntu -- Linux Mint -- Debian-compatible systems where dependencies permit - -Package should install: - -- executable -- application `.desktop` file -- icon -- metadata -- optional autostart entry - -Later packaging may include: - -- AppImage -- Flatpak - -Priority: - -```text -.deb -→ AppImage -→ Flatpak -``` - -Do not make Flatpak the main v1 distribution because sandbox restrictions complicate global clipboard monitoring and input simulation. - ---- - -# 38. Application Identity - -Use one consistent application ID. - -For example: - -```text -io.cliphoard.Cliphoard -``` - -or another sensible reverse-domain identifier. - -Keep: - -- package name -- executable name -- desktop ID -- config directory -- database directory - -consistent. - -Executable suggestion: - -```text -cliphoard -``` - -Display name: - -```text -Cliphoard -``` - ---- - -# 39. X11 First - -For v1, X11 is the reference backend. - -Must support reliably: - -- observing clipboard changes -- reading clipboard text -- setting clipboard text -- registering global shortcut -- determining correct foreground/focus behavior as required -- injecting paste into previously active application - -Test specifically on current Linux Mint/Cinnamon X11. - -Do not claim Wayland parity until implemented and tested. - ---- - -# 40. Wayland - -Wayland support is future work. - -Important architectural fact: - -Wayland intentionally restricts: - -- arbitrary input injection -- global keyboard hooks -- some clipboard behavior - -Future Wayland support may require: - -- compositor protocols -- desktop portals -- compositor-specific integrations - -Do not hack around Wayland security boundaries. - -Keep platform interfaces clean enough that a real Wayland backend can be added later. - ---- - -# 41. Windows/macOS Future Support - -The following must remain platform-independent: - -- history model -- deduplication -- pinning -- limits -- SQLite persistence -- search -- configuration semantics -- application commands - -Only platform interaction should require replacement. - -GTK cross-platform support is a secondary concern. - -If future Windows/macOS adoption becomes important, replacing only the UI layer should remain possible. - -Do not build a UI abstraction framework today merely to guarantee this. - ---- - -# 42. Testing Strategy - -Focus tests on behavior that could destroy, duplicate, or reorder user data incorrectly. - -Unit tests should cover: - -- insert new entry -- duplicate entry moves to top -- duplicate preserves pin state -- pin -- unpin -- history limit -- pinned limit -- clear history preserves pins -- delete -- search ranking -- oversized entry rejection -- malformed configuration -- self-generated clipboard event suppression - -Integration tests should cover: - -- SQLite persistence -- migrations -- startup/restart -- global shortcut where automatable -- clipboard watching -- copy behavior -- paste behavior - -Manual acceptance tests are acceptable for inherently desktop-specific interactions. - ---- - -# 43. Core Invariants - -These invariants must always hold. - -## Invariant 1 - -There is never more than one canonical stored entry for identical clipboard text. - -## Invariant 2 - -Pinned entries are never deleted by normal history cleanup. - -## Invariant 3 - -Clear History never deletes pinned entries. - -## Invariant 4 - -Restoring an entry must not create duplicate history pollution. - -## Invariant 5 - -Storage failures must not silently pretend success. - -## Invariant 6 - -Clipboard content must never be transmitted over the network. - -## Invariant 7 - -Clipboard content must not appear in ordinary logs. - -## Invariant 8 - -The UI is not the source of truth. - -The core state/database owns history. - -## Invariant 9 - -OS-specific clipboard/input logic never leaks into core history logic. - -## Invariant 10 - -The app must remain useful even if the direct-paste action fails: content should still be copied to the clipboard. - ---- - -# 44. Performance Targets - -Treat these as goals rather than premature hard guarantees. - -Aim for: - -- idle CPU effectively zero -- low tens of MB of memory -- popup visible within ~100 ms under normal conditions -- search response effectively instantaneous for normal configured history sizes -- clipboard events processed immediately -- no polling loops burning CPU - -Prefer event-driven clipboard monitoring. - -Avoid frequent timers. - ---- - -# 45. Dependency Philosophy - -Use dependencies where they eliminate substantial complexity. - -Do not reimplement: - -- SQLite -- TOML parser -- robust error handling infrastructure -- proven fuzzy matching - -But inspect dependency cost. - -Avoid enormous dependency trees for tiny conveniences. - -Before adding a crate, ask: - -> Does this substantially simplify or harden the application? - -If not, write the small amount of code locally. - ---- - -# 46. Async / Threads - -Do not introduce async Rust simply because it exists. - -The program has relatively simple concurrency: - -- GTK main thread -- clipboard events -- lightweight database operations -- platform communication - -Use the simplest concurrency model compatible with GTK/platform APIs. - -The UI must never freeze due to blocking clipboard/platform work. - -Do not create a distributed system inside a clipboard manager. - ---- - -# 47. Security - -Treat clipboard data as sensitive local information. - -Basic requirements: - -- database stored in user-owned directories -- files created with appropriate user-only permissions where practical -- no elevated privileges -- never run as root -- no shell invocation with clipboard content -- no evaluation/execution of clipboard contents -- parameterized SQL queries -- safe handling of arbitrary Unicode -- safe handling of massive/malformed clipboard text - -Clipboard contents are data. - -Never treat them as executable instructions. - ---- - -# 48. Unicode - -Clipboard content may contain arbitrary Unicode. - -Support it correctly. - -Do not: - -- assume ASCII -- truncate in the middle of invalid UTF-8 boundaries -- corrupt emoji -- corrupt combining characters unnecessarily - -Rust strings and GTK text handling should make this manageable. - ---- - -# 49. Configuration Reload - -Live configuration reload is not required for v1. - -Changing settings may require: - -- immediate application of simple limits -- re-registering hotkeys -- restart for uncommon settings if necessary - -Prefer immediate application where simple. - -Do not add filesystem watchers solely for configuration reload. - ---- - -# 50. Versioning - -Use semantic versioning. - -Begin with something like: - -```text -0.1.0 -``` - -Expose: - -```bash -cliphoard --version -``` - -Also provide: - -```bash -cliphoard --help -``` - -Useful CLI options may eventually include: - -```text ---version ---help ---show ---quit ---debug -``` - -Keep CLI scope small. - ---- - -# 51. Diagnostics - -Provide enough diagnostics to debug installations. - -Useful command eventually: - -```bash -cliphoard --diagnostics -``` - -Possible output: - -```text -Version: 0.1.0 -OS: Linux -Desktop: Cinnamon -Session: X11 -Database: OK -Config: OK -Clipboard backend: X11 -Hotkey backend: X11 -Registered hotkey: Super+V -Autostart: enabled -``` - -Never include clipboard contents. - -This is optional for earliest MVP, but highly desirable. - ---- - -# 52. Explicit Non-Goals for v1 - -Do **not** implement unless specifically requested later: - -- cloud sync -- accounts -- clipboard sync between computers -- AI features -- image clipboard history -- rich-text preview -- HTML preview -- file preview -- plugin ecosystem -- scripting -- macros -- transformations -- automatic translation -- OCR -- categories -- tags -- workspaces -- clipboard analytics -- themes beyond normal GTK/system appearance -- mobile companion -- browser extension -- collaboration -- clipboard sharing -- network server -- fuzzy-search configuration laboratory -- custom database engine - -Feature creep is a bug. - ---- - -# 53. MVP Completion Criteria - -The first real release is complete when all of these work reliably: - -1. application installs on Linux Mint using `.deb` -2. application launches at login -3. clipboard text changes are recorded -4. duplicate copies move existing entries to top -5. entries persist after reboot/restart -6. `Super+V` opens popup globally -7. popup search is fuzzy and instantaneous -8. arrow keys navigate -9. Enter copies selected entry -10. direct paste works into the previously focused X11 application -11. Delete removes entries -12. entries can be pinned/unpinned -13. Clear History preserves pins -14. history and pin limits are separately configurable -15. oversized clipboard entries are safely rejected -16. only one application instance runs -17. pause recording works -18. errors are logged -19. ordinary logs contain no clipboard data -20. the app remains low-resource and responsive - -Everything else is secondary. - ---- - -# 54. Implementation Order - -Implement in this sequence unless technical constraints require adjustment. - -## Phase 1 — Core - -Build and test: - -- entry model -- history ordering -- deduplication -- pin/unpin -- deletion -- clearing -- limits -- search - -No GUI necessary yet. - -## Phase 2 — Storage - -Implement: - -- SQLite database -- migrations -- repository layer -- persistence tests -- startup loading - -## Phase 3 — Linux/X11 Clipboard - -Implement: - -- read clipboard -- monitor clipboard -- write clipboard -- self-change suppression - -Test heavily. - -## Phase 4 — Minimal GTK UI - -Implement: - -- popup -- search box -- list -- selection -- keyboard navigation -- pin/delete actions - -Keep it ugly-but-functional initially. - -## Phase 5 — Global Hotkey - -Register default global shortcut. - -Popup should open correctly from arbitrary applications. - -## Phase 6 — Direct Paste - -Implement: - -```text -choose entry -→ set clipboard -→ close popup -→ focus previous app -→ paste -``` - -Handle failure safely. - -## Phase 7 — Config - -Add: - -- TOML -- limits -- shortcut -- autostart -- max entry size -- log level - -## Phase 8 — Reliability - -Add: - -- single-instance enforcement -- structured logging -- graceful recovery -- privacy behavior -- pause recording - -## Phase 9 — Packaging - -Produce `.deb`. - -Test: - -- clean install -- upgrade -- uninstall -- autostart -- config persistence -- database persistence - -## Phase 10 — Polish - -Only now improve: - -- spacing -- typography -- previews -- tiny settings UI -- icons -- diagnostics - -Do not polish unfinished architecture. - ---- - -# 55. Code Quality Rules - -The implementation agent should follow these rules. - -### Keep functions small. - -Prefer functions with one obvious responsibility. - -### Prefer explicit types for important domain concepts. - -Do not pass random booleans everywhere. - -### Do not use `unwrap()` in normal runtime paths. - -Tests and provably impossible invariants are exceptions. - -### Add context to errors. - -Use an idiomatic error strategy such as `thiserror` / `anyhow` where appropriate. - -### Avoid global mutable state. - -Use a clear application state owner. - -### Separate persistence from business logic. - -Core behavior should be testable without SQLite. - -### Separate UI from business logic. - -GTK callbacks should invoke application/core commands rather than implement history rules themselves. - -### Separate platform code. - -No X11 imports inside core modules. - -### Comment why, not what. - -Avoid comments explaining obvious Rust syntax. - -Document unusual platform constraints and invariants. - ---- - -# 56. Development Rule for AI Agents - -When implementing this project: - -**Do not expand scope without explicit instruction.** - -If a design decision is ambiguous: - -1. choose the simplest reliable option -2. preserve architecture boundaries -3. document the decision briefly -4. continue implementation - -Do not stop progress for trivial decisions. - -Do not redesign the application into a larger framework. - -Do not replace the agreed stack unless there is a concrete blocker. - -If proposing a dependency or architectural change, explain: - -```text -Problem -Current approach -Proposed change -Why it materially improves reliability/simplicity -Cost -``` - ---- - -# 57. Definition of Success - -Cliphoard succeeds if the user forgets it exists until they need something they copied earlier. - -Then: - -```text -Super+V -→ type -→ Enter -``` - -and it works. - -Every time. - -The best version of Cliphoard is not the version with the most features. - -It is the version where the core interaction is so fast and dependable that there is nothing left to think about. diff --git a/.agents/CLIPHOARD_HARDENING_CHECKLIST.md b/.agents/CLIPHOARD_HARDENING_CHECKLIST.md index 7cd02d1..d70b171 100644 --- a/.agents/CLIPHOARD_HARDENING_CHECKLIST.md +++ b/.agents/CLIPHOARD_HARDENING_CHECKLIST.md @@ -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. diff --git a/.agents/SHIP_CHECKLIST.md b/.agents/SHIP_CHECKLIST.md deleted file mode 100644 index 638b1ce..0000000 --- a/.agents/SHIP_CHECKLIST.md +++ /dev/null @@ -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. diff --git a/Dockerfile b/Dockerfile index ae9e10c..24af1a6 100644 --- a/Dockerfile +++ b/Dockerfile @@ -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 diff --git a/README.md b/README.md index 55abeb9..97a5dbd 100644 --- a/README.md +++ b/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/`. diff --git a/packaging/build-deb.sh b/packaging/build-deb.sh index 9863b02..b5e3b85 100755 --- a/packaging/build-deb.sh +++ b/packaging/build-deb.sh @@ -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" diff --git a/packaging/cliphoard.service b/packaging/cliphoard.service deleted file mode 100644 index 8ddb6c9..0000000 --- a/packaging/cliphoard.service +++ /dev/null @@ -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. diff --git a/src/config.rs b/src/config.rs index b7d3ef1..914c23f 100644 --- a/src/config.rs +++ b/src/config.rs @@ -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] { diff --git a/src/gui.rs b/src/gui.rs index 41f1891..a313feb 100644 --- a/src/gui.rs +++ b/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); diff --git a/src/lifecycle.rs b/src/lifecycle.rs index 6095304..10cf536 100644 --- a/src/lifecycle.rs +++ b/src/lifecycle.rs @@ -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(); diff --git a/src/platform/linux/x11_events.rs b/src/platform/linux/x11_events.rs index 28c09f1..715f9ba 100644 --- a/src/platform/linux/x11_events.rs +++ b/src/platform/linux/x11_events.rs @@ -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);