@wirecat/cli-base 0.40.4 → 0.41.0

package/docs/standards/releases.md

@@ -0,0 +1,191 @@
+# Releases
+
+<!-- cspell:ignore flock lslocks OIDC whatsapp zizmor -->
+
+## Scope
+
+How a CLI is released: `bin/release`, the release lock, version numbers, the release report and trusted publishing.
+
+Rule ids on this page are `WC-REL-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). The changelog a release dates is on the [Documents](docs.md) page. The checks a release runs are
+on the [CI](ci.md) page.
+
+## Rules
+
+### WC-REL-1 · Release only with `bin/release`, from a clean `main` that matches `origin/main`
+
+- **Why:** the workflow publishes `origin/main`, so a local commit or a dirty tree would not ship what was checked.
+- **Enforced by:** `<app>: bin/release`.
+- **Example:** raise `version` in `package.json` and date the pending changelog section in a pull request. Merge it.
+  Then run `bin/release` on `main`. It refuses another branch, uncommitted changes and a `main` ahead of
+  `origin/main`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-2 · `main` changes only through a pull request, also during a release
+
+- **Why:** the repository ruleset requires it, and every change to `main` then passes the pull request checks.
+- **Enforced by:** review only.
+- **Example:** when `bin/release` renumbers the version or folds the changelog, it opens a pull request, waits for its
+  checks and merges it before it publishes. The merge rule itself is
+  [WC-CI-12](ci.md#wc-ci-12--merge-to-main-only-through-a-pull-request-whose-checks-all-passed).
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-3 · `bin/release` takes the machine release lock before it builds or publishes
+
+- **Why:** two sessions published at the same time on one machine; one release at a time, across every package.
+- **Enforced by:** `<app>: bin/release`.
+- **Example:**
+
+  ```sh
+  . ./config/wirecat/release-lock.sh
+  wirecat_release_lock
+  ```
+
+  The helper comes from the community presets (`adopt-standards.py --only release-lock`). It holds
+  `${XDG_RUNTIME_DIR:-/tmp}/leemour-release.lock` with `flock` on file descriptor 9 until the release ends.
+- **Exceptions:** none. cli-testing still opens the lock with its own `flock` line and moves to the helper.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-854.
+
+### WC-REL-4 · Never break the release lock; wait for the holder and try again
+
+- **Why:** a deleted lock file is a new file, so a second release can then run at the same time as the first.
+- **Enforced by:** review only.
+- **Example:** when the lock is held, the helper names the holder on stderr. Let that release finish, then run
+  `bin/release` again. Do not delete the lock file and do not kill the holder.
+- **Exceptions:** none. A missing `lslocks` or an old holder label does not allow a release; only `flock` decides.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-5 · One releaser per version: npm decides which number is free
+
+- **Why:** two sessions often prepare the same number; the second must not publish over the first or fail late.
+- **Enforced by:** `tg-cli: bin/release` · `max-cli: bin/release` · `whatsapp-cli: bin/release` ·
+  `cli-memo: bin/release`.
+- **Example:** before it publishes, `bin/release` asks npm. When npm already has the version, or a higher one, it
+  takes the next free number at the same level (after `x.y.0` the next minor, else the next patch). It lands that
+  number through a pull request and publishes it.
+- **Exceptions:** a pre-release version is chosen by hand. drive's and zoom's `bin/release` do not renumber yet: they
+  refuse a version npm already has.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-6 · `package.json` holds the version, and the program reads a synced copy
+
+- **Why:** a bundled command has no `package.json` to read, so `--version` reads a source file that must not drift.
+- **Enforced by:** `tg-cli: pnpm version:check` · `max-cli: pnpm version:check` · `whatsapp-cli: pnpm version:check`.
+- **Example:** edit only `package.json`, then run `pnpm version:sync` to update `src/version.ts`. `pnpm version:check`
+  fails when the two disagree.
+- **Exceptions:** a shared library that prints no version has no `src/version.ts`. Today tg, max and wa have
+  `version:check`; memo, drive and zoom do not.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-7 · Versions are `x.y.z`; before 1.0.0 the changelog, not the number, marks a breaking change
+
+- **Why:** before 1.0.0 any release may change the API, so a caller reads "Changed — may break callers" before an
+  upgrade.
+- **Enforced by:** review only.
+- **Example:** raise the minor (`0.40.4` to `0.41.0`) for a release with new features, and the patch for one with only
+  fixes. A breaking change, in either kind of release, has an entry under "Changed — may break callers".
+- **Exceptions:** a pre-release version (`0.41.0-rc.1`) is chosen by hand.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-8 · A messenger CLI waits two hours between releases; a shared library does not wait
+
+- **Why:** a broken CLI release must be noticed before the next one lands on top of it. Every CLI waits for a library
+  release, so a gap there only delays them.
+- **Enforced by:** `<app>: bin/release`.
+- **Example:** tg-cli, max-cli and whatsapp-cli's `bin/release` refuse to start within two hours of the last version
+  on npm. cli-base and cli-core release one after another with no gap.
+- **Exceptions:** memo, drive and zoom have no gap in their `bin/release` today.
+- **Applies to:** messenger CLIs (gap); shared libraries (no gap). **Since:** cli-base 0.41.0. **Rulings:** NEED-854.
+
+### WC-REL-9 · A breaking change to a stable shared-library export ships at most once a week
+
+- **Why:** each such change makes every CLI change too; batching them keeps the CLIs on one version.
+- **Enforced by:** review only.
+- **Example:** gather breaking export changes into one release a week. Bump the library in every CLI that uses it on
+  the same day.
+- **Exceptions:** none.
+- **Applies to:** shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-473.
+
+### WC-REL-10 · A messenger CLI is released only with a release report the owner signed for that commit
+
+- **Why:** the judgement half of a release (changelog wording, docs against the change, live checks) has no other
+  record that it ran for this exact commit.
+- **Enforced by:** `max-cli: bin/release`.
+- **Example:** max-cli's `bin/release` refuses unless the report has `Commit: <HEAD>` and `Signed off: <date>`. When
+  `bin/release` only renumbers or folds the changelog, it carries the report to the new commit. A fork passes its
+  own report with `bin/release --report <path>`.
+- **Exceptions:** none. Today only max-cli's `bin/release` checks the report. tg-cli and whatsapp-cli have the
+  release skill, but their `bin/release` does not check a report yet.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-11 · Publish from GitHub Actions with npm trusted publishing
+
+- **Why:** no npm token is stored in GitHub, and npm attaches provenance to the package.
+- **Enforced by:** `release.yml:publish`.
+- **Example:** `bin/release` starts `release.yml` and follows it. Only the `publish` job has the OIDC permission (the
+  short-lived identity npm trusts), and it runs no project code: it only runs `npm publish` on the validated file.
+- **Exceptions:** npm trusts the workflow by file name: renaming `release.yml` stops publishing until npm's trusted
+  publisher settings are updated.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-12 · Publish only after full validation and the release security checks pass
+
+- **Why:** pull request checks are bounded; the full suite and the heavy scanners run before anything reaches npm.
+- **Enforced by:** `release.yml` · `release-checks.yml`.
+- **Example:** `release.yml` runs full validation and `release-checks.yml` (dependency audit, workflow analysis with
+  zizmor, CodeQL). Validation packs the package once, and the `build` job checks that file's SHA-256 before it is
+  handed to `publish`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-13 · Tag `v<version>` only after npm shows that version
+
+- **Why:** a tag for a version npm does not have yet marks a release that may still fail.
+- **Enforced by:** `release.yml:tag`.
+- **Example:** the `publish` job waits until npm serves the new version; only then does the `tag` job push
+  `v<version>`. In the CLIs, the workflow also creates the GitHub release from that version's changelog section.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-14 · `bin/release --local` is the fallback, and it never prints the npm token
+
+- **Why:** a release must still be possible when GitHub Actions is down, without leaking the token.
+- **Enforced by:** `tg-cli: bin/release` · `max-cli: bin/release` · `whatsapp-cli: bin/release` ·
+  `cli-memo: bin/release`.
+- **Example:** `bin/release --local` runs the same checks on this machine and reads the npm token from the keyring
+  into the publish command's environment. Neither success nor an error prints it.
+- **Exceptions:** none. drive's and zoom's `bin/release` have no `--local` yet.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-15 · Fold a late pending section into the unpublished version before publishing
+
+- **Why:** a pull request merged after the version was dated adds a pending section above it, and that change must
+  ship in the version it lands in.
+- **Enforced by:** review only.
+- **Example:** `bin/release` runs `cli-dev changelog fold --land --version <x.y.z>` while npm does not have the version.
+  It folds the pending section into the dated one, and merges any repeated `###` heading, through a pull request.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-REL-16 · The package ships only the files it names
+
+- **Why:** a stray file in the package can leak local data and grows every install.
+- **Enforced by:** `tg-cli: pnpm release:check` · `max-cli: pnpm release:check` · `whatsapp-cli: pnpm release:check`.
+- **Example:** `package.json` `files` lists what ships. The CLI's `pnpm release:check` runs `packContents` from
+  `@wirecat/cli-base/release` and fails on any other path in `npm pack --dry-run`.
+- **Exceptions:** none. tg, max and wa run this check. memo's `release:check` has no package-contents step, drive and
+  zoom have no `release:check`, and zoom checks the packed file in a test instead.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+## Sources
+
+These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page
+holds.
+
+- [cli-base `RELEASING.md`](https://github.com/WireCatLabs/cli-base/blob/main/docs/dev/RELEASING.md), the step by step
+  for cli-base itself
+- [community standards, "Release locking"](https://github.com/WireCatLabs/community/blob/main/standards/README.md),
+  the how-to for installing the lock helper
+- each CLI's `bin/release` and its release skill, which carry out these rules

package/docs/standards/security.md

@@ -0,0 +1,260 @@
+# Security
+
+<!-- cspell:words zizmor -->
+
+## Scope
+
+How a CLI keeps secrets and private data safe: secrets never in logs, fixtures or argv, the keyring, error text that
+never repeats input, the scanners, workflow hardening, and how a vulnerability is reported.
+
+Two words used on this page:
+
+- A **secret** is anything that grants access: a session token, a bot token, an API key, a password, a 2FA code, a
+  proxy password.
+- **Private data** is what people wrote or who they are: message text, chat titles, names, phone numbers.
+
+Rule ids on this page are `WC-SECR-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+## Rules
+
+### WC-SECR-1 · Private data and secrets never reach a log, a fixture or a committed document
+
+Command output is the only place where a message the owner asked to read may appear. A log, a run record, a test
+fixture, a document and a commit message never hold message text, a token or a phone number.
+
+- **Why:** a log or a repository is copied and kept far longer than anyone remembers; private data in it is a leak.
+- **Enforced by:** `node-ci.yml:secrets`.
+- **Example:** a log line says `{ "event": "send", "outcome": "sent", "count": 1 }`, not the text that was sent.
+- **Exceptions:** none. The scanners catch secrets of known shapes; message text and names are caught only in review.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-SECR-2 · A log keeps only known attribute keys, and hides content keys
+
+A log record writes only the attribute keys in cli-base's list (`LOG_ATTRIBUTE_KEYS`) and the ones a CLI adds by
+name. Any other top-level key is written as `[not allowed]`. A key that names content or a secret (`text`, `title`,
+`token`, `phone`, `chatTitle`, `accessToken` …) is written as `[redacted]`, at any depth.
+
+- **Why:** redaction is the second line of defence; the first is never handing a secret to a logger.
+- **Enforced by:** `src/logging.test.ts`.
+- **Example:** `recordLog({ … redact: ["sessionKey"] })` adds a CLI's own secret field to the redacted list.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-SECR-3 · Merged into [WC-TEST-8](testing.md#wc-test-8--prove-that-content-does-not-leak-with-a-marker-and-visibly-fake-data)
+
+### WC-SECR-4 · Secrets come from the environment, then the OS keyring, then a private file
+
+cli-base's `Credentials` reads the environment variable first (for CI), then the OS keyring, then a file with mode
+`0600`. The keyring service is the command's name. When the config directory comes from the environment, the service
+name is scoped to that directory (`isolated: true`).
+
+- **Why:** the keyring is the safest store on the computer, and a throwaway config directory must not overwrite the
+  owner's real keyring entry.
+- **Enforced by:** `src/credentials.test.ts`.
+- **Example:** a bot token is read from `MAX_BOT_TOKEN`, then the keyring entry `bot:<profile>`, then the file.
+- **Exceptions:** `auto` storage tries the keyring and, when it fails, warns once on stderr and uses the file.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-295.
+
+### WC-SECR-5 · A secret is never taken on the command line
+
+A secret is typed at a terminal, without echo, or piped on stdin. A secret given on the command line is refused with
+`validation_error`. It is stored only after the remote side accepted it.
+
+- **Why:** the command line is visible to other processes and kept in shell history; a keyring entry cannot be read
+  back to check it.
+- **Enforced by:** review only.
+- **Example:** cli-core's `readSecret` reads one line from a terminal or a pipe, at most 64 KiB, and prompts on stderr.
+  `contacts import` reads phone numbers from stdin, never from the command line.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-203.
+
+### WC-SECR-6 · Error text never repeats a secret or what other people wrote
+
+An error message names what failed and the next step. It never quotes a secret, a parameter the caller passed that
+may hold private data, or text from the provider that can quote a chat title or a message. Provider errors are reduced
+to their error name, or replaced with fixed wording.
+
+- **Why:** errors reach logs, run records and agents' transcripts.
+- **Enforced by:** review only.
+- **Example:** tg's error mapper keeps only the provider's error name, and turns a name that tells a person nothing
+  into a fixed sentence with the next `tg …` command to run.
+- **Exceptions:** the owner's own input that holds no private data, such as a file path, may be named.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-SECR-7 · A token stays inside the transport
+
+The address that holds a token is built in one place and never reaches an error, a trace or a rethrown network error.
+Text that looks like a token is replaced with `[redacted]`. Attachments carry a file id, never a download address
+that contains the token. Proxy credentials are passed as options, never inside a proxy address.
+
+- **Why:** the token is the account or the bot; anything that prints it hands it away.
+- **Enforced by:** review only.
+- **Example:** a failed Bot API call reports the method and the API's own description with tokens replaced, never
+  the request address.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-SECR-8 · Phone numbers are masked unless the owner asks for the whole number
+
+Output shows the last four digits (`***1234`). `--show-phone` prints the whole number, on the command line only.
+
+- **Why:** a phone number identifies a person and is the login of a messenger account.
+- **Enforced by:** review only.
+- **Example:** `max work account show --show-phone`.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-209.
+
+### WC-SECR-9 · A command does not send the CLI's own secret files unless the owner says so
+
+A command that sends a local file refuses known credential files, browser profiles, the WireCat apps' own folders and
+the message store. The owner adds `--allow-any-file` to send one anyway.
+
+- **Why:** an agent talked into "send me your config" must not be able to send the session.
+- **Enforced by:** review only.
+- **Example:** `max work messages send @me --file ~/.config/max-cli/credentials.json` is refused.
+- **Exceptions:** ordinary hidden developer folders, such as `.cache` or `.worktrees`, are not refused.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-274.
+
+### WC-SECR-10 · Private files are written atomically with private modes
+
+A file that holds a secret or private state is written with `writeSecurely`: atomically, mode `0600`, in a directory
+created with mode `0700`. A temporary credential file, such as a login QR image, is `0600` and removed in `finally`.
+tg's `doctor` reports a wrong mode and prints the `chmod` fix without applying it.
+
+- **Why:** another user on the same computer must not read the session.
+- **Enforced by:** `src/config.test.ts`.
+- **Example:** `writeSecurely(path, JSON.stringify(state), 0o600)`.
+- **Exceptions:** Windows ignores both modes.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-SECR-11 · Text from outside is made safe before a terminal or an agent sees it
+
+Display text and agent text pass through cli-base's sanitizer. It escapes control characters, terminal escapes and
+the characters that reverse text direction.
+
+- **Why:** a chat title can hold `\x1b[2K` and overwrite what the tool already printed, or make `invoice‮fdp.exe`
+  look like a PDF.
+- **Enforced by:** `src/sanitize.test.ts`.
+- **Example:** a title with an escape sequence prints as visible `\x1b` text.
+- **Exceptions:** machine output (`--json`) keeps the original strings, as a contract with scripts.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-SECR-12 · Nothing goes to an outside model or service without explicit config
+
+Private data goes to an outside AI model only when the owner configured it, through cli-core's one model gateway. A
+feature that sends a chat's text asks once for consent and can be turned off per chat. Embeddings use the local model
+by default. Nothing is downloaded unasked either: attachment text is extracted from a remote file only with
+`--download`, and a meaning search with no model falls back to words and says `meaning: "unavailable"`.
+
+- **Why:** messages belong to the people who wrote them; sending them to a third party is the owner's decision.
+- **Enforced by:** review only.
+- **Example:** reply rewording is off until the profile turns it on, and asks once per profile.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-545, NEED-552, NEED-755, NEED-756, NEED-757, ss:10.
+
+### WC-SECR-13 · A CLI sends no telemetry
+
+- **Why:** the tool must not report on its owner; for a messenger CLI, extra traffic also stops it looking like the
+  official client.
+- **Enforced by:** review only.
+- **Example:** a pull request that adds a call to a WireCat server, or to an analytics service, is refused in review.
+- **Exceptions:** a messenger CLI may later copy what the official client reports, and nothing more.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-16.
+
+### WC-SECR-14 · Certificate checks stay on, and the computer's trust store is never changed
+
+A CLI never turns off TLS verification. A root certificate that a provider needs is trusted inside the process only.
+
+- **Why:** changing the computer's trust store weakens every other program on it.
+- **Enforced by:** review only.
+- **Example:** for its Bot API calls, max adds the root certificate it ships to that process alone.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-293, sc:5.
+
+### WC-SECR-15 · Security work keeps ordinary workflows working
+
+Prefer compatibility over guesses about attacks. Fix a confirmed critical issue at once. A new restriction that is not
+critical goes to the owner for review first.
+
+- **Why:** users run VPNs, proxies and unusual DNS; a speculative guard that breaks them gets switched off.
+- **Enforced by:** review only.
+- **Example:** attachment downloads use the configured transport and normal redirects, with no private-address block
+  list.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** sc:3, sc:5, sc:6, sc:8.
+
+### WC-SECR-16 · Keep the secret scanners on, and run each one with `--redact`
+
+- gitleaks, in the pre-commit hook on staged changes, in the pull request job on the new commits, and on the whole
+  history in full validation, at release and every month.
+- Biome's `noSecrets` rule, from the shared preset, off in tests only
+  ([WC-TOOL-10](toolchain.md#wc-tool-10--keep-the-secret-lint-on-and-suppress-a-finding-only-with-its-reason)).
+- At release and every month: a dependency audit, zizmor for workflows and CodeQL.
+- **Why:** a secret removed in a later commit is still a leaked secret; `--redact` keeps a finding from leaking it
+  again into the log.
+- **Enforced by:** `node-ci.yml:secrets` · `release-checks.yml` · `standards.yml:standards` · `pnpm standards:check`.
+- **Example:** `gitleaks git --staged --no-banner --redact .`. When each scanner runs is on the CI page:
+  [WC-CI-1](ci.md#wc-ci-1--run-only-staged-lint-and-a-staged-secret-scan-before-a-commit),
+  [WC-CI-3](ci.md#wc-ci-3--run-the-fast-standards-job-on-every-pull-request-and-every-push-to-main),
+  [WC-CI-7](ci.md#wc-ci-7--run-full-validation-once-on-each-merge-to-main-on-linux-without-publishing) and
+  [WC-CI-10](ci.md#wc-ci-10--run-heavy-security-checks-only-at-release-monthly-or-on-request).
+- **Exceptions:** the pre-commit hook warns, and does not block, when gitleaks is not installed; CI scans anyway.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-SECR-17 · A gitleaks rule covers each secret shape a CLI handles
+
+A CLI adds a gitleaks rule for each token, device id or personal identifier that the default rules do not know. An
+allowlist names synthetic values by value, never a whole file, so the file stays scanned.
+
+- **Why:** the default rules know AWS and GitHub keys, not a messenger's session token.
+- **Enforced by:** review only.
+- **Example:** max's `.gitleaks.toml` has `max-session-token`, `max-device-identity` and `phone-number-e164`, and
+  allows only `+71234567890` and other sanctioned fakes.
+- **Exceptions:** `pnpm-lock.yaml` may be allowed by path. Today only max and wa have a phone number rule.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-SECR-18 · Report a vulnerability privately
+
+Every repository has a `SECURITY.md`. It names `hello@wirecat.dev` and GitHub's private vulnerability reporting, and
+asks never to send a token, a session or anyone's messages.
+
+- **Why:** a public issue tells attackers before users can upgrade.
+- **Enforced by:** review only.
+- **Example:** [max-cli's `SECURITY.md`](https://github.com/WireCatLabs/max-cli/blob/main/SECURITY.md).
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-555.
+
+### WC-SECR-19 · Audit findings stay out of public places
+
+An audit follows the [cli-testing security method](https://github.com/WireCatLabs/cli-testing/tree/main/docs/security).
+Its results go to a private repository, not to a public backlog or issue. A fix is described in the changelog in
+general words.
+
+- **Why:** a public finding is a guide to attacking users who have not upgraded.
+- **Enforced by:** review only.
+- **Example:** "Fixed: an error could include part of a request" — not the steps to make it happen.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-271.
+
+### WC-SECR-20 · Pin each third-party action to a commit, and give each workflow read-only defaults
+
+- **Why:** a moved tag or a write token in a workflow is how an outside change reaches a release.
+- **Enforced by:** review only.
+- **Example:** `uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1` with
+  `persist-credentials: false`, and `permissions: contents: read` at the top of the workflow. A job that needs more
+  asks for it on that job only. The `zizmor` scan in `release-checks.yml` reports high findings at release, but does
+  not fail on them.
+- **Exceptions:** none.
+- **Applies to:** the ten repositories: the six CLIs, cli-base, cli-core, cli-testing, cli-docs and community.
+  **Since:** cli-base 0.41.0. **Rulings:** none.
+
+## Sources
+
+These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page
+holds. The audit procedure stays in cli-testing; this page links it and does not copy it.
+
+- [The security audit method](https://github.com/WireCatLabs/cli-testing/tree/main/docs/security): what an audit
+  checks, how a run is done, and where its results go.
+- [The organisation's security policy](https://github.com/WireCatLabs/.github/blob/main/SECURITY.md): how to report a
+  problem.

package/docs/standards/store.md

@@ -0,0 +1,177 @@
+# Store
+
+## Scope
+
+How local data is kept: one shared store, its areas, account scope, migrations and store versions, what a delete
+and a repair do to the data, and the rule that tests never touch the owner's store.
+
+Rule ids on this page are `WC-STORE-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+Related pages: which account a read covers, and how a read across accounts is asked for, is in
+[Accounts](accounts.md); the general test sandbox is in [Testing](testing.md); where secrets live is in
+[Security](security.md).
+
+### Words used here
+
+- **The store:** the one SQLite file that cli-core opens for every CLI, `wirecat.db`.
+- **Area:** one part of the store for one kind of record, such as `store.messages` or `store.chats`.
+- **Store version:** the number of the newest migration the file has run. It is the `version` field of `MANIFEST`
+  in cli-core's `src/store/sqlite/manifest.ts`.
+- **Tombstone:** the mark a deleted message keeps in place of its content.
+
+## Rules
+
+### WC-STORE-1 · Keep local data in the one shared store that cli-core opens
+
+- **Why:** one file for every messenger and account lets search, backup and export see everything in one place.
+- **Enforced by:** review only.
+- **Example:** `openStore` opens `wirecat.db` in the WireCat folder (`~/.local/share/WireCat/` on Linux,
+  `%LOCALAPPDATA%\WireCat\Data\` on Windows). Rows are keyed by provider and account. `storePath` is the only code
+  that reads `MESSAGING_STORE` and `WIRECAT_STATE_DIR`.
+- **Exceptions:** none. Older documents that name `messages.db` describe a store that is no longer used.
+- **Applies to:** CLIs that keep local data through cli-core (tg, max, wa, memo, drive, zoom). **Since:** cli-base 0.41.0.
+  **Rulings:** NEED-383.
+
+### WC-STORE-2 · Reach the data through its area, and add a new kind of record as a new area
+
+- **Why:** an area keeps one kind of record in one file, so the store does not grow back into one long interface.
+- **Enforced by:** `cli-core: biome noExcessiveLinesPerFile`.
+- **Example:** `store.chats.saveChats(key, …)`, `store.messages.find(…)`, `store.tasks`, `store.mail`. Each area is a
+  getter built on first use from its own file (`xStoreOver(context)`). `MessageStore` has no flat methods.
+- **Exceptions:** none. cli-core's `biome.json` caps `src/store/store.ts` at 438 lines so that it does not grow again.
+- **Applies to:** cli-core, and every CLI that calls the store. **Since:** cli-base 0.41.0 (store areas since
+  cli-core 0.307.0). **Rulings:** none.
+
+### WC-STORE-3 · A service of one account works through the store bound to that account
+
+- **Why:** when no call takes an account, a row of another account cannot be read or written by mistake.
+- **Enforced by:** `cli-core: src/services/account-isolation.test.ts`.
+- **Example:** `accountStore(deps)` returns `store.forAccount(key)`; then `.messages.messages(chatId, …)` takes no
+  account, and a row id of another account (an attachment, a mail thread, a meeting) is "not found". A read across
+  accounts on purpose asks for the whole store with `crossAccount(deps, reason)`; see [Accounts](accounts.md).
+- **Exceptions:** `forAccount` binds only the account areas (accounts, chats, sync, messages, attachments, roster,
+  people, conversations, vectors, counters, tags, mentions). The `chats`, `conversations` and `attachments` services
+  use the bound store; the other services still pair `deps.store()` with `deps.account()`. New code uses the bound
+  store.
+- **Applies to:** cli-core and every CLI that adds a service. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STORE-4 · Reach the store through its public module, never a table module
+
+- **Why:** the table modules are the SQL layer; a caller that imports them skips the transaction and the account
+  binding.
+- **Enforced by:** review only.
+- **Example:** in cli-core, `biome.json` is meant to refuse an import of `src/store/sqlite/*` from `src/services/`,
+  `src/sends/`, `src/mcp/` and `src/cli/`; today it does not, because a later override replaces that rule
+  ([WC-ARCH-1](architecture.md#wc-arch-1--call-only-the-layers-below-you-interface-then-service-then-port-then-adapter)). They import from `src/store/store.ts`, which re-exports what they need.
+- **Exceptions:** tests of a table module.
+- **Applies to:** cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STORE-5 · A CLI writes no SQL against the shared store
+
+- **Why:** the schema belongs to cli-core; SQL in a CLI breaks on the next migration.
+- **Enforced by:** review only.
+- **Example:** a CLI that needs a new query asks cli-core for an area method, and the method lands in cli-core with
+  its test. drive and zoom state "no SQL here" in their own architecture pages.
+- **Exceptions:** a provider engine's own file of keys and device state, outside `wirecat.db`
+  ([WC-STORE-13](#wc-store-13--keep-keys-and-device-state-out-of-the-shared-store)).
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-383.
+
+### WC-STORE-6 · One store method is one whole operation, with no `await` inside a transaction
+
+- **Why:** the driver is synchronous; an `await` inside a transaction lets the commit run before the awaited part.
+- **Enforced by:** review only.
+- **Example:** a write goes through `write` and a read of several queries through `read`
+  (`src/store/sqlite/transaction.ts`), never Drizzle's `transaction` or a hand-written `BEGIN`. A large write runs
+  in bounded batches, because it blocks the event loop while it runs.
+- **Exceptions:** `replaceConversations` writes a new build in several short transactions on purpose. Readers see
+  only the current build.
+- **Applies to:** cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STORE-7 · Migrations only go forward: add, never edit or rebuild
+
+- **Why:** a file that a newer build migrated must still open in the build already installed.
+- **Enforced by:** `cli-core: src/store/sqlite/manifest.test.ts`.
+- **Example:** a change is a new column that is nullable or has a default, or a new table. Triggers, full-text tables
+  and data fills go in a custom migration. A mistake in a released migration is fixed by the next version. cli-core's
+  manifest tests refuse a rebuilt base table, a gap in the versions and a bundle that differs from what drizzle-kit
+  wrote.
+- **Exceptions:** none.
+- **Applies to:** cli-core. **Since:** cli-base 0.41.0. **Rulings:** NEED-383.
+
+### WC-STORE-8 · Take the migration number before you write the migration
+
+- **Why:** two branches with the same number leave one migration unapplied on stores that ran the other.
+- **Enforced by:** review only.
+- **Example:** edit the "next free version" line in cli-core `docs/dev/COORDINATION.md` in a pull request of its
+  own, and wait for it to merge. Versions are the `version` field of `MANIFEST`; the initial migration is 1.
+- **Exceptions:** none.
+- **Applies to:** cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STORE-9 · Ship each migration with its schema spec, an upgrade test and a changelog line
+
+- **Why:** the schema page, the code and the files already on disk must agree after every version.
+- **Enforced by:** `cli-core: pnpm schema:check`.
+- **Example:** change `scripts/schema/spec.mjs` first, then `schema.ts` until `pnpm schema:check` passes, then
+  `pnpm db:generate` and `pnpm db:bundle`. Add a `src/store/version-<n>.test.ts` that opens a file at version n−1 and
+  reads what version n added. The changelog entry names the store version, as in "Chat members in the store (store
+  version 7)".
+- **Exceptions:** none.
+- **Applies to:** cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STORE-10 · An older build refuses a store it cannot read and says to upgrade
+
+- **Why:** an older build that reads a file it does not understand corrupts it or answers wrongly.
+- **Enforced by:** review only.
+- **Example:** each migration keeps `minCompatible`. An additive change leaves it as it is (1 today). A change that
+  drops what an older build reads raises it; that older build then refuses the file and asks to be upgraded.
+- **Exceptions:** raising `minCompatible` needs the owner's approval. It is a major version of cli-core, and the CLIs
+  ship their upgrade the same day.
+- **Applies to:** cli-core and the CLIs that use the store. **Since:** cli-base 0.41.0. **Rulings:** NEED-867.
+
+### WC-STORE-11 · A deleted message keeps a tombstone and loses its content
+
+- **Why:** a delete must remove what the owner wanted gone, while the history still shows that something was there.
+- **Enforced by:** review only.
+- **Example:** a delete keeps a mark in the message row. Triggers erase its text, revisions, transcript, file text and
+  tags, so a build that knows nothing about a newer table cannot leave content behind.
+- **Exceptions:** none.
+- **Applies to:** cli-core. **Since:** cli-base 0.41.0. **Rulings:** NEED-393.
+
+### WC-STORE-12 · A repair never deletes data
+
+- **Why:** the store is the owner's only copy of much of this data.
+- **Enforced by:** review only.
+- **Example:** `store repair` keeps a misshapen table as a copy, builds the correct one and copies the columns.
+- **Exceptions:** none.
+- **Applies to:** cli-core and the CLIs that expose `store repair`. **Since:** cli-base 0.41.0. **Rulings:** NEED-626.
+
+### WC-STORE-13 · Keep keys and device state out of the shared store
+
+- **Why:** a store that holds keys turns every backup and export into a secret.
+- **Enforced by:** review only.
+- **Example:** WhatsApp's linked-device keys live in a separate file per profile, `private.db`, which only the
+  provider engine writes. Tokens go to the keyring ([Security](security.md)).
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1395.
+
+### WC-STORE-14 · Tests never open the owner's store
+
+- **Why:** migrations only go forward; a test that opened the real file would migrate it, and nothing undoes that.
+- **Enforced by:** review only.
+- **Example:** the vitest `setupFiles` sandbox points `MESSAGING_STORE`, `WIRECAT_STATE_DIR` and each app's own
+  directory variables at a temporary directory before any test runs. A test that defines a new app prefix adds it to
+  the sandbox. A test that needs its own store is
+  [WC-TEST-9](testing.md#wc-test-9--give-each-test-its-own-profile-or-its-own-store). The rest of the sandbox is
+  [WC-TEST-1](testing.md#wc-test-1--point-every-path-a-test-could-write-at-a-temporary-directory).
+- **Exceptions:** none.
+- **Applies to:** all CLIs that use the store, and cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+## Sources
+
+These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page
+holds.
+
+- [cli-core `ARCHITECTURE.md`, "The store"](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/ARCHITECTURE.md#the-store)
+- [cli-core `COORDINATION.md`, "Store migrations"](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/COORDINATION.md#store-migrations)
+- [cli-core `TESTING.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/TESTING.md)