@wirecat/cli-base 0.40.3 → 0.41.0

package/docs/standards/style.md

@@ -0,0 +1,119 @@
+# Style
+
+## Scope
+
+How code and history read: comments say why and only where needed, names, TypeScript habits, and commit messages.
+
+Rule ids on this page are `WC-STYLE-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). Formatting and the lint rules are on the [Toolchain page](toolchain.md); Biome decides
+formatting, so this page does not repeat it.
+
+## Rules
+
+### WC-STYLE-1 · Write a comment only where the code cannot say it, and say why
+
+- **Why:** a comment costs a reader's attention and goes stale silently, so it must carry what the code cannot.
+- **Enforced by:** review only.
+- **Example:** a comment records a decision, warns about a trap, or names a constraint that is not visible in the
+  file: `// A static import would load the whole program before ensureSqlite could swap it.`
+- **Exceptions:** none. When in doubt, leave it out; the commit message, the pull request and the tests carry the
+  story.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-2 · Do not restate the code, narrate a change or leave old code in comments
+
+- **Why:** these comments repeat what the code or git already says, and they turn false at the next edit.
+- **Enforced by:** review only.
+- **Example:** no `// increment the counter` above `count++`, no `// fixed the timeout bug`, no section banners, no
+  commented-out alternatives. A test gets a clear name, not a paragraph above it.
+- **Exceptions:** existing comments in a file you only pass through stay; this rule is for new comments.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-3 · Name files in kebab case, and name a test after what it tests
+
+- **Why:** one naming habit lets a reader and a glob find a module and its test without searching.
+- **Enforced by:** review only.
+- **Example:** `src/format-markdown.ts` and `src/format-markdown.test.ts`. A test that covers a behaviour across
+  modules is named after that behaviour, such as `src/every-failure.test.ts`.
+- **Exceptions:** none.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-4 · Write functions in the small, and a class only where identity matters
+
+- **Why:** a function that takes its inputs is easy to test and to reuse; a class earns its place by holding state
+  that must live together.
+- **Enforced by:** review only.
+- **Example:** a client that holds a connection and a session is a class. Parsing, mapping and formatting are plain
+  functions.
+- **Exceptions:** none.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-5 · Narrow a type instead of casting it with `as`
+
+- **Why:** a cast tells the compiler to stop checking, so a renamed field fails at run time instead of at build time.
+- **Enforced by:** review only.
+- **Example:** narrow with a type guard, `instanceof` or a shape check. A test fixture uses an honest type, such as
+  `Omit<T, "x"> & { x: string | null }`, not `as unknown as T`.
+- **Exceptions:** `as const` is allowed. A cast that cannot be avoided, because a library is typed too loosely, keeps
+  a comment on that line that says why. Existing casts are not yet removed; the rule holds for new code.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-6 · In a `catch`, narrow with `instanceof` and wrap anything else
+
+- **Why:** a caught value can be anything, and the error model needs a code and a cause to show the right message.
+- **Enforced by:** review only.
+- **Example:** `e instanceof CliError ? e : new CliError("provider_error", String(e), { cause: e })`. The error codes
+  and reasons are on the [Output page](output.md).
+- **Exceptions:** none.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-7 · Annotate exports and signatures, and let the rest infer
+
+- **Why:** a redundant annotation is noise, and a hand-written `x is T` is not checked against its body.
+- **Enforced by:** review only.
+- **Example:** `export function count(items: readonly Item[]): number` with `const total = items.length` inside. In
+  `.filter()`, let the callback narrow: `xs.filter((x) => x !== null)`. Write `x is T` only for a named, reused guard
+  or a check the compiler cannot follow.
+- **Exceptions:** none.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-8 · Inline a type used once, and keep a type beside the code that owns it
+
+- **Why:** a name for a one-off type sends the reader to another place for nothing, and a shared types file collects
+  types nobody owns.
+- **Enforced by:** review only.
+- **Example:** name a type when it is exported or used in three or more places. Keep it in the module that owns it. A
+  shared types file holds only a contract between several modules.
+- **Exceptions:** none.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-9 · Spread an optional field in, and build an object in one expression
+
+- **Why:** an object built once has one type that the compiler checks; a key added later widens it or fails to
+  compile.
+- **Enforced by:** review only.
+- **Example:** `{ id, ...(signal === undefined ? {} : { signal }) }`, never `{ id, signal: undefined }`. Use
+  `=== undefined` when a falsy value is valid. A small helper that returns the optional part is fine.
+- **Exceptions:** none. The shared TypeScript config leaves `exactOptionalPropertyTypes` off, so the compiler does not
+  force this.
+- **Applies to:** all repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-STYLE-10 · Write commit messages and pull request titles as conventional commits
+
+- **Why:** the type and scope tell a reader what changed before they open it, and `!` tells the changelog guard that a
+  caller may break.
+- **Enforced by:** review only.
+- **Example:** `feat(standards): add the verb scan`, `docs(standards): toolchain rules`,
+  `feat!: remove the --take alias`. The body says why. A title marked breaking needs a changelog line; the
+  changelog rules are on the [Documents page](docs.md).
+- **Exceptions:** none.
+- **Applies to:** all repositories. **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 `CONVENTIONS.md`, "Code"](https://github.com/WireCatLabs/cli-base/blob/main/docs/dev/CONVENTIONS.md#code)
+- [tg-cli TypeScript standards](https://github.com/WireCatLabs/tg-cli/tree/main/agent-os/standards/typescript): no casts,
+  inference and optional fields

package/docs/standards/testing.md

@@ -0,0 +1,222 @@
+# Testing
+
+## Scope
+
+How a CLI is tested: the sandbox, no network and no real waits in tests, what kind of test to write, coverage
+floors, offline contracts, the test matrix, parity between CLIs, and the live checks that are not tests.
+
+Rule ids on this page are `WC-TEST-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+Related pages: tests and the shared store are in [Store](store.md); secrets in logs are in [Security](security.md);
+typechecking the tests and the Bun smoke test are in [Toolchain](toolchain.md); which checks run on a pull request
+and which run after merge is in [CI](ci.md).
+
+### Words used here
+
+- **Sandbox:** a vitest `setupFiles` entry that runs before every test file and moves every path a test could write
+  into a temporary directory.
+- **Offline contract:** a check that runs the built CLI from outside, with no account and no network, and compares
+  its help, its `commands --json` and its MCP tool list with reviewed snapshots. The runner is `cli-contract` from
+  `@wirecat/cli-testing`.
+- **Test matrix:** the page that lists every command and option of a CLI, with the test that drove it or the reason
+  why no offline test can.
+- **Full validation:** the CI run on each merge to `main`, on a release and in the monthly run. It is not the pull
+  request run.
+
+## Rules
+
+### WC-TEST-1 · Point every path a test could write at a temporary directory
+
+- **Why:** one test that falls back to a default path writes into the owner's config, state, cache or store.
+- **Enforced by:** review only.
+- **Example:** `src/testing/sandbox.ts` is a vitest `setupFiles` entry, so it holds for every test file, including
+  the next one. It sets the CLI's config, state and cache directories, the store variables
+  ([WC-STORE-14](store.md#wc-store-14--tests-never-open-the-owners-store)) and `TMPDIR`, `TMP` and `TEMP` to a
+  directory of its own. It closes resources first, then removes that directory and restores the variables when the
+  file is done.
+- **Exceptions:** keep coverage reports and debug traces outside the sandbox, with bounded retention. Never clean
+  another session's scratch directory as test teardown.
+- **Applies to:** all CLIs and the shared packages. drive has no sandbox yet, and zoom's sandbox moves only the
+  temporary directory. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-2 · No test reaches the real keyring
+
+- **Why:** the owner's tokens live in the real keychain, and one test that forgets an option would write there.
+- **Enforced by:** `src/keyring.test.ts`.
+- **Example:** every test passes `memoryKeyring()` from `@wirecat/cli-base/testing`. cli-base's own sandbox also
+  replaces `@napi-rs/keyring` with a module that throws, so a forgotten option fails the test instead of reaching the
+  keychain, and `src/keyring.test.ts` asserts that `systemKeyring` throws under it.
+- **Exceptions:** none. The CLIs' sandboxes do not replace `@napi-rs/keyring` yet; tg and max only scope the keyring
+  entry through environment variables.
+- **Applies to:** all CLIs and the shared packages. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-3 · No test contacts a provider or the network
+
+- **Why:** a test that reaches the network is slow, flaky, and can act on a real account.
+- **Enforced by:** `max-cli: src/testing/unscripted.ts`.
+- **Example:** max-cli's `src/testing/mock-max.ts` scripts the service: an answer per request, a refusal, or silence
+  to test a timeout. A request with no scripted answer fails the test that sent it, through a second `setupFiles`
+  entry. tg's `scripted({...})` adapter does the same job.
+- **Exceptions:** none. No CLI has a global guard that refuses sockets and `fetch` in tests yet.
+- **Applies to:** all CLIs and the shared packages. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-4 · Give a command that must not connect an adapter that throws
+
+- **Why:** a command that swallows an adapter error would otherwise pass while it still connects.
+- **Enforced by:** review only.
+- **Example:** an `--offline` test passes an adapter that throws "--offline must never open Telegram". When the
+  adapter is shared across a file, it is a `vi.fn`, and `afterAll` checks `expect(refuse).not.toHaveBeenCalled()`.
+  The test leaves the provider credentials out of `env` to show that none are needed.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-5 · No test waits for real time
+
+- **Why:** a test that sleeps a real second crosses the time limit on a slow CI runner and fails at random.
+- **Enforced by:** review only.
+- **Example:** waits go through an injected `SleepLike`, and `fakeClock()` from `@wirecat/cli-base/testing` records
+  them without waiting. A test harness passes `sleep: async () => {}`. `pnpm test:slow` lists the 20 slowest tests
+  and the 10 slowest files.
+- **Exceptions:** none. A new wait in the code gets a seam, never a longer test timeout.
+- **Applies to:** all CLIs and the shared packages. **Since:** cli-base 0.41.0. **Rulings:** dev-process:4.
+
+### WC-TEST-6 · Test mostly through the command line, with `run()`
+
+- **Why:** a test that drives `run()` checks what a person or an agent types, from parsing to output.
+- **Enforced by:** review only.
+- **Example:** most tests call `run(["chats", "list", "--json"], environment)` with fake effects and check stdout,
+  stderr and the exit code. Unit tests cover pure logic with many cases. Adapter contract cases (cli-core
+  `./testing`) cover implementations that must behave the same.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-7 · Write the test that pins a promise someone could break
+
+- **Why:** a test that restates the code passes when the code is wrong; a test of a promise fails.
+- **Enforced by:** review only.
+- **Example:** reading history marks nothing read; a retried send reuses its id; a send with no answer is
+  `outcome_unknown`, never failed and never sent; an ambiguous chat name is refused, not guessed.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-8 · Prove that content does not leak, with a marker and visibly fake data
+
+- **Why:** "the output has no message text" only means something when the text was there to leak; a convention alone
+  proves nothing.
+- **Enforced by:** review only.
+- **Example:** test data is visibly fake: `synthetic text ${id}`, the phone number `+71234567890`, the device id
+  `00000000-0000-0000-0000-000000000001`, `your-token-here`. Content that must stay hidden carries a unique marker,
+  and the test asserts that the marker is absent from output, errors and run events, while the id is present:
+  `expect(err).not.toContain(token)`. The positive check stops the test from passing by recording nothing.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-9 · Give each test its own profile or its own store
+
+- **Why:** the sandbox is per file, so tests in one file share config, the send journal and the store.
+- **Enforced by:** review only.
+- **Example:** each test passes its own profile name first, or a file-level constant. A test that needs an empty
+  store makes a fresh directory and passes `MESSAGING_STORE`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-10 · A skip is not a pass: report the suite that ran and its counts
+
+- **Why:** a suite that ran nothing, or skipped what mattered, still exits 0.
+- **Enforced by:** review only.
+- **Example:** when you report work, name the suite that ran and give its counts: passed, failed and skipped. A
+  skipped test is counted as skipped, never as passed. That the tests are typechecked at all is
+  [WC-TOOL-5](toolchain.md#wc-tool-5--typecheck-every-typescript-file-source-tests-and-scripts).
+- **Exceptions:** none.
+- **Applies to:** all CLIs and the shared packages. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-11 · Keep a coverage floor, and raise it; never lower it
+
+- **Why:** a floor stops coverage from falling one pull request at a time.
+- **Enforced by:** `pnpm test:coverage` · `node-ci.yml:check`.
+- **Example:** `vitest.config.ts` holds thresholds for lines, statements, functions and branches over `src/`, a little
+  under what the suite reaches, and `perFile: { lines: 50 }`. A change that falls below gets a test, not a lower
+  number. Each excluded file has its reason written beside it.
+- **Exceptions:** generated code, types-only files, the entry point, and code that only runs under Bun or as a
+  separate process, each with its reason.
+- **Applies to:** all CLIs and the shared packages. memo has no thresholds yet; drive and zoom have no per-file
+  floor. **Since:** cli-base 0.41.0. **Rulings:** dev-process:4.
+
+### WC-TEST-12 · Every command and option has a test, or a written reason
+
+- **Why:** a flag that no test passes can break without anyone noticing.
+- **Enforced by:** `tg-cli: pnpm test:matrix` · `max-cli: pnpm test:matrix` · `whatsapp-cli: pnpm test:matrix` ·
+  `zoom-cli: pnpm test:matrix:check`.
+- **Example:** under vitest, `run()` appends each parsed command path and option name (never a value) to
+  `coverage/argv.jsonl`. `pnpm test:matrix` turns that into `docs/dev/test-matrix.md` and fails on a command or
+  option with neither a test nor a reason. A reason names the live scenario that covers it. A test that calls a
+  function directly does not count.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. tg, max, zoom and wa have the matrix; memo and drive do not yet. **Since:** cli-base
+  0.41.0. **Rulings:** NEED-359.
+
+### WC-TEST-13 · Keep offline contracts for help, discovery, errors and the MCP tool list
+
+- **Why:** agents depend on `commands --json` and the MCP tool list; a change to them must be seen and reviewed.
+- **Enforced by:** `tg-cli: pnpm contracts:check` · `max-cli: pnpm contracts:check` ·
+  `whatsapp-cli: pnpm contracts:check` · `drive-cli: pnpm contracts:check` · `zoom-cli: pnpm contracts:check`.
+- **Example:** `pnpm contracts:check` runs `cli-contract contracts/plan.json` against the built CLI. It checks the
+  help snapshot, that discovery is one JSON value on stdout with empty stderr, that a bad option gives the documented
+  exit code and one JSON error on stderr, and the MCP tool names, schemas and annotations. A change is accepted with
+  `pnpm exec cli-contract contracts/plan.json --update` and a reviewed diff.
+- **Exceptions:** the contracts run in full validation, not on pull requests.
+- **Applies to:** all CLIs. memo has no contracts yet. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-14 · Check the upgrade from the previous published version
+
+- **Why:** a release that cannot read what the previous one wrote loses the owner's data.
+- **Enforced by:** `tg-cli: pnpm contracts:upgrade` · `max-cli: pnpm contracts:upgrade` ·
+  `drive-cli: pnpm contracts:upgrade` · `zoom-cli: pnpm contracts:upgrade`.
+- **Example:** `pnpm contracts:upgrade` runs the previous published package and this build on the same synthetic
+  state and checks that the data survives. Each store migration also has its own upgrade test (WC-STORE-9).
+- **Exceptions:** a CLI with no local state.
+- **Applies to:** all CLIs with local state. memo and wa have no upgrade contract yet. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-15 · A refactor keeps `commands --json` and the MCP tool list as they were
+
+- **Why:** a change that is meant to move code must not change what agents see.
+- **Enforced by:** review only.
+- **Example:** capture `commands --json` and the MCP tool list from `main` before the first edit, and compare them
+  after the last. The offline contract snapshots (WC-TEST-13) do the same job in full validation.
+- **Exceptions:** a refactor that changes behaviour on purpose says so in its pull request.
+- **Applies to:** all CLIs and cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-16 · A messenger CLI matches its column of the parity manifest
+
+- **Why:** tg, max and wa promise the same commands and options where their messengers allow it.
+- **Enforced by:** `<app>: pnpm parity:check` · `cli-core: parity.yml` · `cli-core: src/parity/manifest.test.ts`.
+- **Example:** `pnpm parity:check` compares the CLI's `commands --json` with its column of `parity.json` from the
+  cli-core version it installed. cli-core's `parity.yml` builds tg, max and wa from `main` and runs the same check in
+  full validation.
+- **Exceptions:** a row marked `planned` passes whether the command exists or not.
+- **Applies to:** messenger CLIs (tg, max, wa). **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TEST-17 · Merged into [WC-TOOL-6](toolchain.md#wc-tool-6--support-node-22-and-later-and-bun-and-run-the-built-exports-under-bun)
+
+### WC-TEST-18 · Check the real service by hand, never in the test suite
+
+- **Why:** a check against a real account needs a live login and can send messages to people.
+- **Enforced by:** review only.
+- **Example:** live scenarios run by hand, by the owner or with the owner's yes, on test profiles and test chats
+  only. The cast lives in an ignored file, no profile is assumed, and the record keeps the shape of each answer,
+  never its content. When a scenario is run again, the sentence it supports is updated.
+- **Exceptions:** none.
+- **Applies to:** all CLIs that talk to a real account. **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 `TESTING.md`](https://github.com/WireCatLabs/cli-base/blob/main/docs/dev/TESTING.md)
+- [cli-core `TESTING.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/TESTING.md)
+- [max-cli `TESTING.md`](https://github.com/WireCatLabs/max-cli/blob/main/docs/dev/TESTING.md)
+- [cli-testing contracts guide](https://github.com/WireCatLabs/cli-testing/blob/main/docs/ci/CONTRACTS.md) and
+  [upgrade guide](https://github.com/WireCatLabs/cli-testing/blob/main/docs/ci/UPGRADES.md)
+- [cli-testing CI docs](https://github.com/WireCatLabs/cli-testing/tree/main/docs/ci)

package/docs/standards/toolchain.md

@@ -0,0 +1,232 @@
+# Toolchain
+
+## Scope
+
+How a repository is built and checked before review: the shared presets and `standards:check`, strict TypeScript,
+the shared Biome preset and its grit plugins, the file size cap, import cycles, layer boundaries as lint, the command
+lint, spelling and Markdown lint.
+
+Rule ids on this page are `WC-TOOL-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). What runs on which trigger is on the [CI page](ci.md).
+
+The [community standards](https://github.com/WireCatLabs/community/blob/main/standards/README.md) repository is the
+one source of the presets. Each repository holds a copy of them in `config/wirecat/`, installed by
+`adopt-standards.py`.
+
+"The ten repositories" on this page means the six CLIs (tg, max, memo, drive, zoom, wa), cli-base, cli-core,
+cli-testing, cli-docs, plus community itself.
+
+## Rules
+
+### WC-TOOL-1 · Install the shared presets with `adopt-standards.py`, and never edit the copies
+
+- **Why:** one reviewed set of presets keeps ten repositories alike; an edited copy drifts without anyone seeing it.
+- **Enforced by:** `pnpm standards:check` · `standards.yml:standards`.
+- **Example:** `python3 scripts/adopt-standards.py /path/to/project` from a community checkout, then commit
+  `config/wirecat/` and the lockfile. `standards:check` compares each file in `config/wirecat/` with the hash in
+  `config/wirecat/manifest.json`.
+- **Exceptions:** none. A general improvement goes to community and comes back through a new adoption. A
+  project-only setting goes in the root config (WC-TOOL-2).
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-2 · Make each root config extend its copy in `config/wirecat/`
+
+- **Why:** a root config that does not extend the preset runs none of the shared rules, and nothing else would say so.
+- **Enforced by:** `pnpm standards:check` · `standards.yml:standards`.
+- **Example:** `biome.json` has `"extends": ["./config/wirecat/biome.base.json"]`. `cspell.json` imports
+  `./config/wirecat/cspell.json`. `.markdownlint-cli2.jsonc` extends `./config/wirecat/markdownlint.json`.
+  `lefthook.yml` extends `config/wirecat/lefthook.yml`.
+- **Exceptions:** do not extend `@wirecat/cli-base/biome` or `@wirecat/cli-base/lefthook.yml`. No repository uses
+  them, and `standards:check` accepts only the paths above.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-3 · Pin the tool versions that `toolchain.json` names
+
+- **Why:** two Biome versions give two verdicts on the same file.
+- **Enforced by:** `pnpm standards:check` · `standards.yml:standards`.
+- **Example:** `package.json` has `"packageManager": "pnpm@11.20.0"` and exact `devDependencies` for
+  `@biomejs/biome`, `cspell` and its three dictionaries, `lefthook` and `markdownlint-cli2`, as in the manifest.
+- **Exceptions:** none.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-4 · Extend the shared TypeScript config, and do not loosen it
+
+- **Why:** strict options catch at build time what would otherwise fail on a user's machine.
+- **Enforced by:** review only.
+- **Example:** `tsconfig.json` has `"extends": "@wirecat/cli-base/tsconfig.base.json"` and adds only `rootDir`,
+  `outDir`, `include` and `exclude`. The base turns on `strict`, `noUncheckedIndexedAccess`, `noImplicitOverride`,
+  `noFallthroughCasesInSwitch`, `verbatimModuleSyntax` and `isolatedModules`.
+- **Exceptions:** cli-docs is a Next.js site with its own config. cli-testing reaches the same file through
+  `./node_modules/@wirecat/cli-base/config/tsconfig.base.json`. A repository may add stricter options.
+- **Applies to:** the CLIs, cli-core, cli-base and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-5 · Typecheck every TypeScript file: source, tests and scripts
+
+- **Why:** a folder that no `tsconfig` covers breaks without a sign, and a test that compares against a constant that
+  does not exist passes for any input while CI stays green.
+- **Enforced by:** `pnpm typecheck` · `pnpm ci:quick` · `node-ci.yml:check`.
+- **Example:** `tsconfig.test.json` extends `@wirecat/cli-base/tsconfig.test.json`, covers all of `src/`, tests
+  included, checks them with `noEmit` and carries `"exclude": []`. Without that line it inherits the build's
+  `exclude`, checks no test file and still passes. `tsconfig.scripts.json` extends
+  `@wirecat/cli-base/tsconfig.scripts.json` and covers `scripts/`. The `typecheck` script runs all three projects.
+- **Exceptions:** a new folder of TypeScript goes into one of these projects in the same pull request. memo has no
+  `tsconfig.scripts.json` yet.
+- **Applies to:** the CLIs, cli-core, cli-base and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-6 · Support Node 22 and later, and Bun, and run the built exports under Bun
+
+- **Why:** users install the CLIs with either runtime, and a static import of one runtime's module fails to load on
+  the other.
+- **Enforced by:** `pnpm smoke:bun` · `node-ci.yml:bun`.
+- **Example:** `"engines": { "node": ">=22" }` in `package.json`. Full validation runs on Node 24. `bun test` cannot
+  run the vitest suite, so `scripts/smoke.ts` runs the built exports with plain assertions, and the Bun job runs it
+  (`pnpm build && pnpm smoke:bun`). A new entry point gets a line there. Node 22 runs in the Windows install matrix of
+  tg, max and wa, in zoom's full validation and in cli-core's old-Node job.
+- **Exceptions:** cli-docs and community publish no runtime package. memo, drive and cli-base do not run Node 22 in
+  any workflow yet. memo has no Bun smoke test yet.
+- **Applies to:** the CLIs, cli-core and cli-base. **Since:** cli-base 0.41.0. **Rulings:** NEED-11.
+
+### WC-TOOL-7 · Let Biome format the code, and do not format by hand
+
+- **Why:** one formatter ends every argument about layout, and review reads only the change.
+- **Enforced by:** `pnpm lint` · `standards.yml:standards`.
+- **Example:** the shared preset sets 2 spaces, double quotes, semicolons only where needed, trailing commas, arrow
+  parentheses always and 120 columns. Run `pnpm lint:fix` to apply them.
+- **Exceptions:** none.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-8 · Keep the shared Biome rules at error
+
+- **Why:** each of these rules catches a real class of bug, and a warning gets ignored.
+- **Enforced by:** `pnpm lint` · `standards.yml:standards`.
+- **Example:** the preset turns on Biome's recommended rules and adds, as errors: useConst, noNonNullAssertion,
+  noUnusedImports, noUnusedVariables and noExplicitAny.
+- **Exceptions:** a repository may add rules or raise a level. It may not turn a shared rule off (index, "Which rule
+  wins").
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-9 · Write to the console only with `console.error`, except in `scripts/`
+
+- **Why:** stdout carries data only, so a stray `console.log` breaks every caller that parses it.
+- **Enforced by:** `pnpm lint` · `standards.yml:standards`.
+- **Example:** the preset sets noConsole to error and allows `error`. Command output goes through the renderer and the
+  streams of cli-base.
+- **Exceptions:** files under `scripts/` may print, because they are development tools. A shared package prints
+  nothing at all, not even with `console.error`
+  ([WC-ARCH-19](architecture.md#wc-arch-19--shared-packages-print-nothing-and-log-nothing-on-their-own)).
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-10 · Keep the secret lint on, and suppress a finding only with its reason
+
+- **Why:** a token caught at commit time never reaches the history; gitleaks is the second net.
+- **Enforced by:** `pnpm lint` · `standards.yml:standards`.
+- **Example:** noSecrets runs at error with an entropy threshold of 50. A reviewed site reads
+  `// biome-ignore lint/security/noSecrets: Crockford base32 alphabet, not a key`.
+- **Exceptions:** the rule is off in test files, `test/`, `tests/`, `__tests__/`, `fixtures/` and `generated/`,
+  because those hold fake credentials or cannot keep a suppression comment.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-11 · Keep the three grit plugins that block unsafe calls
+
+- **Why:** a shell or an evaluated string built from input is how a command line tool runs an attacker's code.
+- **Enforced by:** `pnpm lint` · `standards.yml:standards`.
+- **Example:** these plugins report at error. no-shell-true reports `shell: true` in `spawn`, `exec`, `execFile` or
+  `fork` and their `Sync` forms. no-exec-interpolation reports `exec` or `execSync` with a template literal or a `+`
+  concatenation. no-new-function reports `new Function(...)` and `Function(...)`.
+- **Exceptions:** a reviewed site may keep a `biome-ignore` comment with the reason, for example a Windows `.cmd` shim
+  with fixed arguments. The plugins read syntax, not data flow, so review and CodeQL at release cover the rest.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-12 · Do not spread a list of user data into call arguments
+
+- **Why:** V8 throws at about 125,000 arguments, so `push(...items)` fails on a large mailbox or chat.
+- **Enforced by:** `pnpm lint` · `standards.yml:standards`.
+- **Example:** write `for (const item of items) out.push(item)`, not `out.push(...items)`. The no-unbounded-spread
+  plugin reports `.push(...x)`, `Math.max(...x)` and `Math.min(...x)` as a warning.
+- **Exceptions:** a spread over a list that is small by construction may stay. The plugin skips tests, `testing/`,
+  `scripts/`, `bench/` and `performance/`.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-13 · Cap every file at 1,000 lines with Biome
+
+- **Why:** a file past 1,000 lines always holds more than one job; the cap stops it before review has to.
+- **Enforced by:** `<app>: biome noExcessiveLinesPerFile` · `cli-core: biome noExcessiveLinesPerFile`.
+- **Example:** `biome.json` sets the style rule noExcessiveLinesPerFile to error with `"maxLines": 1000`, and turns it
+  off for `**/*.test.ts`, `test/**` and `**/generated/**`. Below the cap, the review signals at 300 and 500 lines are
+  in [WC-LAY-7](layout.md#wc-lay-7--treat-300-and-500-lines-as-review-signals).
+- **Exceptions:** a file that is one cohesive unit may get its own override, listed by path in `biome.json` (tg
+  `src/telegram/adapter.ts`; four files in cli-core). A smaller cap is allowed: zoom uses 500. cli-base, cli-testing,
+  cli-docs and community have no cap yet.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-14 · Turn on the import cycle rule
+
+- **Why:** a cycle makes load order decide which value a module sees, and the failure shows only at run time.
+- **Enforced by:** `<app>: biome noImportCycles` · `cli-core: biome noImportCycles`.
+- **Example:** `biome.json` sets the suspicious rule noImportCycles to error.
+- **Exceptions:** cli-base, cli-testing, cli-docs and community do not have it yet.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-15 · Declare layer boundaries as restricted imports in `biome.json`
+
+- **Why:** a boundary that only a document states is crossed in the first busy week.
+- **Enforced by:** `<app>: biome noRestrictedImports` · `cli-testing: biome noRestrictedImports`.
+- **Example:** an override with `"includes": ["src/commands/**"]` sets the style rule noRestrictedImports with the
+  folders that layer may not import, and a `message` that says why, such as "commands speak the domain model; only
+  `src/client.ts` may reach the protocol". Which layers exist and which way they depend is on the
+  [Architecture page](architecture.md).
+- **Exceptions:** cli-base and cli-docs have no layer overrides. cli-core has them, but its last override replaces
+  the earlier ones today, so they catch nothing until it is fixed.
+- **Applies to:** the CLIs, cli-core and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-16 · Run the command lint on the built CLI, and let its baseline only shrink
+
+- **Why:** the command tree is what users and agents see; the lint holds it to the shared vocabulary on every pull
+  request.
+- **Enforced by:** `<app>: pnpm lint:commands`.
+- **Example:** `"lint:commands": "cli-dev lint --cli dist/bin/max.js"`, run by `ci:quick` after the build. Known
+  violations live in `lint/baseline/<rule-id>.json`; an entry with no violation left fails the run. A permanent
+  exception goes in `lint/overrides.json` with `rule`, `target`, `reason`, `owner` and `review_after`. More than 10
+  overrides fail the run, and so does one past its date. The rules themselves are on the
+  [Commands page](commands.md).
+- **Exceptions:** zoom runs `lint:commands` in full validation only. cli-core runs its own command lint test in
+  `ci:quick`. cli-base, cli-testing, cli-docs and community have no command tree.
+- **Applies to:** the CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-17 · Spell-check prose with the shared `cspell` config
+
+- **Why:** a typo in a page or a help text is the first thing a reader sees.
+- **Enforced by:** `pnpm docs:spell`.
+- **Example:** `cspell.json` imports `./config/wirecat/cspell.json` (English, British English, Russian, Spanish and the
+  WireCat word list) and adds only the project's own words. Code blocks and inline code are not checked.
+- **Exceptions:** a general word goes into the community word list, not into each project. In tg, max, wa, zoom and
+  cli-testing, `cspell` also runs inside `docs:check` in full validation.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-18 · Lint Markdown with `markdownlint-cli2` and the shared preset
+
+- **Why:** a code block with no language or an empty link breaks the docs site and agent readers alike.
+- **Enforced by:** `pnpm docs:lint` · `standards.yml:standards`.
+- **Example:** the preset turns on only: no tabs (MD010), at most two blank lines in a row (MD012), a language on
+  every fenced code block (MD040) and no empty links (MD042). `.markdownlint-cli2.jsonc` lists the files to check.
+- **Exceptions:** a repository may turn on more rules in its root config.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-TOOL-19 · Check user pages with `rumdl` and the shared `rumdl.toml`
+
+- **Why:** user pages feed the docs site, so their Markdown form is checked more closely than developer notes.
+- **Enforced by:** `tg-cli: pnpm docs:check` · `max-cli: pnpm docs:check` · `whatsapp-cli: pnpm docs:check` ·
+  `zoom-cli: pnpm docs:check` · `cli-testing: pnpm docs:check`.
+- **Example:** `rumdl check --config config/wirecat/rumdl.toml README.md docs/*.md`, inside `docs:check`. The preset
+  turns off line length (MD013), first-line heading (MD041) and relative links (MD057), because other checks cover
+  them.
+- **Exceptions:** memo, drive, cli-base and cli-core do not run `rumdl` yet.
+- **Applies to:** the CLIs and cli-testing. **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.
+
+- [community standards](https://github.com/WireCatLabs/community/blob/main/standards/README.md)
+- [cli-base `TOOLING.md`](https://github.com/WireCatLabs/cli-base/blob/main/docs/TOOLING.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.40.3",
+  "version": "0.41.0",
   "description": "The parts every command line tool needs: output modes, terminal rendering, error model, exit codes, credentials, clocks",
   "license": "Apache-2.0",
   "author": "Viacheslav Ptsarev",
@@ -16,6 +16,7 @@
   "files": [
     "dist",
     "config",
+    "docs/standards",
     "README.md",
     "LICENSE",
     "THIRD_PARTY_NOTICES"
@@ -88,7 +89,7 @@
     "typecheck": "tsc --build --force --emitDeclarationOnly && tsc -p tsconfig.test.json && tsc -p tsconfig.scripts.json",
     "lint": "biome check .",
     "lint:fix": "biome check --write .",
-    "docs:check": "pnpm build && node dist/dev/bin.js docs-check --ids CLI,MAX,OPS,CORE,SPEC,DOC",
+    "docs:check": "pnpm build && node dist/dev/bin.js docs-check --ids CLI,MAX,OPS,CORE,SPEC,DOC && node scripts/standards-ids.ts",
     "test": "vitest run",
     "test:watch": "vitest",
     "test:coverage": "vitest run --coverage",
@@ -99,7 +100,7 @@
     "prepublishOnly": "pnpm build",
     "standards:check": "node config/wirecat/check.mjs",
     "docs:lint": "markdownlint-cli2",
-    "docs:spell": "cspell lint --config cspell.json --no-progress README.md",
+    "docs:spell": "cspell lint --config cspell.json --no-progress README.md \"docs/standards/**/*.md\"",
     "ci:quick": "pnpm typecheck"
   },
   "dependencies": {