muutot/clipboard/clipboard-dev

Clipboard Desktop Development

Start every task

1. Read references/maintenance-workflow.md completely before changing the repository.
2. Inspect git status --short --branch, recent commits, TODO.md, and the exact source and tests in scope. Preserve unrelated user changes.
3. Select the relevant references from the routing table below and read each selected file completely before editing its subsystem.
4. Treat current source, tests, configuration, and rendered/runtime behavior as authoritative. References are navigation aids and must be corrected when evidence disagrees.
5. Define one independently verifiable feature, fix, audit, style pass, or documentation update for the next commit.

Non-negotiable principles

• Check a TODO only when direct implementation evidence and proportionate verification cover its full wording. A stub, setting, UI shell, similarly named symbol, or untested platform file is not completion.
• Preserve the approved main-page visual language. Do not redesign it unless the task explicitly requests a main-page redesign.
• Apply the settings style gate before any settings CSS or markup change. Reuse project-wide semantic variables and shared settings primitives.
• Protect local data first. Be conservative around migrations, cleanup, custom resource roots, self-trigger suppression, favorites, recycle-bin records, OCR, and derived search data.
• Keep parallel ownership non-overlapping. The primary agent owns shared integration files and final verification.
• Commit one verified minimal unit at a time; never mix unrelated cleanup into the same commit.

Mandatory documentation currency gate — every commit

Before every commit, inspect the staged diff and decide whether SKILL.md or any file under references/ must change. This gate is required even when the answer is “no documentation update needed.”

Update the matching reference in the same commit when the change affects any of these:

• routes, components, services, utilities, backend modules, or ownership boundaries;
• Tauri commands/events, TypeScript/Rust types, database/config schemas, defaults, or serialization;
• lifecycle, data-safety, search-cache, OCR, platform, or verification invariants;
• theme variables, project-wide styles, settings primitives, layout hierarchy, or an approved pattern;
• a recurring pitfall, workflow rule, or stable project preference.

Keep stable workflow and routing rules in SKILL.md. Put module-specific facts, signatures, examples, and style details in the relevant reference. Do not edit documentation merely to create churn, but never commit a known-stale skill or reference.

Pre-commit hooks

The repository ships Git hooks in .githooks/, enabled per clone by npm run hooks:install (npm install runs the same installer through prepare, and never fails an install). The hooks watch the mechanical rules below; they do not replace the judgement ones.

Blocking checks:

• commit-msg enforces the gitmoji contract in "Commit message format": one leading emoji, a

type from the mapping table, an emoji that maps to that type, a lowercase scope, and English-only text. Generated subjects (Merge, Revert, fixup!, squash!, amend!) are skipped.

• pre-commit rejects staged whitespace errors and conflict markers, Prettier violations in

staged files, cargo fmt drift when Rust files are staged, a version bump committed together with anything outside the release artifact list, and a new or removed source module that arrives without any skills/clipboard-dev/ change.

Advisory output (printed, never blocking): the references that probably need an update for the staged source files, and the pre-release gate commands when a version bump is staged. Set CLIPBOARD_DOC_GATE=none to waive the new-module documentation block for one commit.

git commit --no-verify bypasses both hooks and must stay a deliberate exception. TODO evidence, one verified unit per commit, the documentation decision itself, and rendered, runtime or platform verification remain human work.

Reference router

Also read the focused project document when relevant: docs/PITFALLS.md, docs/SEARCH.md, docs/OCR.md, or docs/DEFAULTS_AND_PRIVACY.md.

Cross-cutting change gates

• Tauri contract: keep command name, Rust arguments/result, frontend invoke, serde casing, error handling, and tests aligned.
• Settings contract: update TypeScript type, defaults, normalization/ranges, Rust config serde/defaults, UI, persistence, cross-window application, i18n, tests, and references as applicable.
• Async settings contract: a control bound to backend-loaded state must hydrate before it renders — a shared module-level store (generalSettings, windowConfig) or a load gate — never a placeholder default that the fetch later overwrites. Lazy settings panels are destroyed and recreated on every section switch, so a per-mount fetch makes the wrong value (and any toggle animation) flash on each visit. See settings-panels.md.
• Database contract: update schema/migration, row mapping, repository behavior, derived search/OCR cleanup, recovery expectations, and tests.
• i18n contract: update src/lib/i18n/locales/en.ts, zh-CN.ts, and src/lib/i18n/types.ts together unless the string is intentionally non-localized and documented.
• Worker/listener contract: retain stop signals, join handles, unlisten functions, and the unified shutdown path.
• Platform contract: separate shared behavior from per-platform implementation and degradation. Do not infer macOS/Linux completion from a compiled adapter or documentation scaffold. Code behind #[cfg(target_os = ...)] is not compiled by a local run on another OS, so its only gate is the matching CI job — see docs/PITFALLS.md.
• Visual contract: type/build checks do not prove appearance. Use structural comparison and, when available, rendered/runtime inspection at the target window size and theme.

Verification commands

npm run check
npm run test
npm run build
npm run test:rust
npm run lint:rust
npm run format:check
npm run verify

The local verify and ci:local gates include the frontend Vitest suite. The Rust format, test, and Clippy scripts cover every Cargo workspace member, including the Tauri-independent sync crate. During bug remediation, verify each minimal fix with only its relevant unit tests (UTs), including cross-layer fixes; do not run the full Vitest suite, Cargo workspace suite, or npm run verify between fixes. After all requested fixes are complete, run npm run verify once as the final integration gate. Keep the per-commit formatting, hooks and documentation currency gates. If an environment prevents a required runtime, visual, platform, packaging, or performance check, report the missing evidence and leave the corresponding TODO unverified.

The pre-release gate runs format + check + lint:rust and does not build locally (see skills/version-release/SKILL.md); building happens remotely in the GitHub Actions release.yml workflow on tag push, so the local build profile stays fast.

Local build and run model

Build profiles in src-tauri/Cargo.toml are split so local builds are fast and storage-light, and only the GitHub Actions release build applies extreme runtime optimization:

• npm run tauri dev — local dev run. [profile.dev] keeps dependencies unoptimized (opt-level 0, no debug symbols) with incremental + split-debuginfo = "unpacked", so the cached target is reused and rebuilds are as fast as possible.
• npm run tauri build — local packaging. [profile.release] is likewise tuned for build speed and minimal cache (opt-level 0, codegen-units = 256, no debug info, incremental = false).
• GitHub Actions release — the only place extreme runtime optimization is enabled. .github/workflows/release.yml sets CARGO_PROFILE_RELEASE_LTO=true, CARGO_PROFILE_RELEASE_CODEGEN_UNITS=1, CARGO_PROFILE_RELEASE_OPT_LEVEL=3 plus RUSTFLAGS (target-cpu=x86-64-v3 on Windows/Linux, intentionally empty on macOS because target-cpu=native panics at compile time with ring 0.17.x, -fuse-ld=mold on Linux). Local builds are unaffected.
• CI checks (ci.yml, release verify) build with --profile ci (deps at opt-level 0) and use sccache, mold on Linux, and cargo-nextest for tests.

Commit message format

Follow the gitmoji convention established by the earliest ~70 commits of this repository:

<gitmoji> <type>[<scope>]: <message>

• gitmoji: single emoji indicating the change category (see table below).
• type: lowercase change type matching the emoji (e.g., feat, fix, docs, refactor).
• scope: optional, lowercase, in square brackets (e.g., [storage], [settings], [search]).
• message: concise imperative description in English only. Chinese (or any non-English) descriptions are strictly forbidden — always write the message in English imperative (e.g., add pagination, fix vertical centering).

Gitmoji mapping