@wirecat/cli-base 0.40.4 → 0.42.0

package/docs/standards/architecture.md

@@ -0,0 +1,214 @@
+# Architecture
+
+## Scope
+
+How the code is split: the layers and the direction of dependencies, no vendor type above the adapter, and what
+belongs in cli-base, in cli-core or in the CLI itself.
+
+Rule ids on this page are `WC-ARCH-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+Related pages: file size, one job per file and how a large unit is split are in [Layout](layout.md); import cycles
+and the lint that holds the layers are in [Toolchain](toolchain.md); who opens and closes a resource, what may open
+at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's own rules are in [Store](store.md).
+
+### Words used here
+
+- **Adapter:** the code that talks to one provider (Telegram, MAX, WhatsApp, Google Drive, Zoom) and translates its
+  objects into our own types.
+- **Port:** an interface that says what a service needs, for example `MessengerAdapter` or a store area.
+- **Service:** a use case, written once, that both a command and an MCP tool call.
+- **Composition root:** the place in a CLI where real implementations are chosen and connected, usually
+  `program.ts` and the command context.
+- **Vendor type:** a type from a provider library, such as `@mtcute/*` or `ws`.
+
+## Rules
+
+### WC-ARCH-1 · Call only the layers below you: interface, then service, then port, then adapter
+
+- **Why:** when a command calls an adapter directly, the MCP tool for the same job does something different.
+- **Enforced by:** `cli-core: biome noRestrictedImports`.
+- **Example:** cli-core has five layers: domain (`src/domain/`), adapters, ports (`port.ts`, the store), services
+  (`src/services/`) and the interface (commands and MCP tools). Its `biome.json` refuses an import of
+  `commander` or of `src/cli/` from the services and the layers below them, and an import of a command file from
+  `src/mcp/`. What a
+  command and a service share lives below the command.
+- **Exceptions:** none. A new adapter method goes into a named group in `port.ts`, never into the domain. In Biome, a later
+  override that sets `noRestrictedImports` for the same file replaces the earlier one's options, so every block that
+  sets the rule carries the complete list for its paths.
+- **Applies to:** all CLIs. Each repository's `biome.json` holds its own import rules. **Since:** cli-base 0.41.0.
+  **Rulings:** none.
+
+### WC-ARCH-2 · Dependencies point one way: a CLI depends on cli-core, cli-core on cli-base, never back
+
+- **Why:** a shared package that imports an app cannot be shared.
+- **Enforced by:** `cli-core: biome noRestrictedImports`.
+- **Example:** cli-base has no dependency on cli-core or on any CLI. cli-core's `biome.json` refuses an import of a
+  messenger library or an adapter directory ("cli-core speaks no provider").
+- **Exceptions:** none.
+- **Applies to:** cli-base, cli-core and all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-3 · Only the adapter imports a vendor library; nothing above it sees a vendor type
+
+- **Why:** the provider library underneath must be replaceable, and the layers above must not change when it is.
+- **Enforced by:** `max-cli: biome noRestrictedImports` · `tg-cli: biome noRestrictedImports` ·
+  `whatsapp-cli: biome noRestrictedImports`.
+- **Example:** in max-cli, `biome.json` lets only `src/client.ts` and `src/client/` reach the protocol, and only
+  `src/adapter/` maps the client onto the shared messenger port. A field that only one provider has travels in
+  `providerMetadata`.
+- **Exceptions:** a bot slice that talks to an official HTTP API keeps its own transport, beside the personal
+  account's adapter, never above it.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-12.
+
+### WC-ARCH-4 · Put code in the lowest shared package that can hold it
+
+- **Why:** the CLIs keep to one standard by sharing code, not by copying text.
+- **Enforced by:** review only.
+- **Example:**
+  - cli-base: general CLI infrastructure that needs no domain knowledge. This includes the streams, the renderer,
+    errors and exit codes, the keyring, config and paths, clocks, retry, the command registry and format-neutral code
+    generation.
+  - cli-core: provider-neutral models, ports and use cases, even when only one CLI uses them today. Meeting discovery
+    is in cli-core although Zoom was its first user.
+  - The CLI: vendor translation, profile binding, resource lifetimes and rules that only make sense for that product.
+- **Exceptions:** share an invariant or a real capability. Lines that only look alike are not a reason for a new
+  shared abstraction.
+- **Applies to:** cli-base, cli-core and all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-292, NEED-440.
+
+### WC-ARCH-5 · Build a feature that another provider could have as a shared command behind a capability
+
+- **Why:** a command written once in cli-core gives every messenger the same path, flags and output.
+- **Enforced by:** review only.
+- **Example:** topics and polls are port groups and shared commands in cli-core. A messenger that lacks a capability
+  refuses the command; it does not silently do less. A bot is another messenger with fewer capabilities, and tg and
+  max share the bot code.
+- **Exceptions:** a feature stays in one CLI only when the other providers cannot have it, such as MAX's socket server
+  or Telegram's app registration.
+- **Applies to:** messenger CLIs (tg, max, wa). **Since:** cli-base 0.41.0. **Rulings:** NEED-820, NEED-440,
+  NEED-301, NEED-444.
+
+### WC-ARCH-6 · Replace a use case, not a command
+
+- **Why:** when a CLI replaces the service method, its command and its MCP tool both get the change.
+- **Enforced by:** review only.
+- **Example:** `Messenger.services` receives the shared services and returns only the ones it changes:
+  `services: (base) => ({ messages: { ...base.messages, list: maxList } })`. To add a subcommand, a CLI calls
+  `addCommand` on the command a factory returns.
+- **Exceptions:** none.
+- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-7 · Keep policy in the service; a command or MCP handler only parses input and presents the result
+
+- **Why:** two transports that each interpret a query or a write policy drift apart.
+- **Enforced by:** review only.
+- **Example:** query interpretation, cursor binding, evidence checks and write policy live in the service. Each
+  caller parses its own input, so an error names `--since` in a command and `since` in a tool, but both run the same
+  method and give the same error for the same input.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-8 · Cross a module boundary only through the module's entry point
+
+- **Why:** a deep import ties the caller to another module's internals.
+- **Enforced by:** `cli-core: biome noRestrictedImports` · `cli-memo: biome noRestrictedImports` ·
+  `drive-cli: biome noRestrictedImports` · `zoom-cli: biome noRestrictedImports`.
+- **Example:** in cli-core, `src/tasks/` and `src/meetings/` are entered only through their `index.ts`, `cli/`, `mcp/`
+  and `testing/` entries; its `biome.json` refuses the rest. memo, drive and zoom have a "public exports only" rule. A
+  package's own entry points are its `exports`
+  ([WC-LAY-5](layout.md#wc-lay-5--add-an-entry-point-as-an-exports-entry-built-from-srcindexts)).
+- **Exceptions:** a test inside a module may import what it tests; a test outside the module uses the entry point.
+- **Applies to:** all CLIs. tg, max and wa do not have the import rule yet. **Since:** cli-base 0.41.0.
+  **Rulings:** none.
+
+### WC-ARCH-9 · Pass the narrow port or callback a use case needs, not a whole store or container
+
+- **Why:** a narrow dependency shows what the use case touches and is easy to replace in a test.
+- **Enforced by:** review only.
+- **Example:** a service sees the messenger as `MessengerTraits`, only the fields it reads. The CLI's `Messenger`
+  adds how commands connect.
+- **Exceptions:** none. Add a factory, inheritance or a dependency-injection framework only for a concrete benefit.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-10 · Pass every effect on the machine as an argument, with the real one only as the default
+
+- **Why:** a test then replaces the clock, the keyring or the network, and never touches the real machine.
+- **Enforced by:** review only.
+- **Example:** clock, sleep, keyring, `env`, `fetch`, streams, stdin and the TTY check are parameters or fields of the
+  command environment. Production code uses `environment.sleep ?? realSleep`. A new effect gets a new field, not a
+  module mock.
+- **Exceptions:** none. Watch the defaults: `new Credentials({...})` without `keyring` is the owner's real keychain,
+  and `resolvePaths` without `env` reads `process.env`.
+- **Applies to:** all CLIs and the shared packages. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-11 · Keep one command environment per program, cli-core's
+
+- **Why:** two registries of the same environment must both be filled on every run, and one is always forgotten.
+- **Enforced by:** review only.
+- **Example:** a CLI extends `BaseEnvironment`, hands it to cli-core's `provide(program, environment)`, and its
+  commands read it with `environmentOf<Environment>(command)`, never with `process.*`.
+- **Exceptions:** a CLI that does not use cli-core's command skeleton keeps one environment of its own.
+- **Applies to:** CLIs built on cli-core's command skeleton. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-12 · Merged into [WC-LIFE-6](lifecycle.md#wc-life-6--open-nothing-until-an-action-needs-it)
+
+### WC-ARCH-13 · Merged into [WC-LIFE-1](lifecycle.md#wc-life-1--the-code-that-opens-a-resource-closes-it-so-a-one-shot-command-exits-when-it-has-answered)
+
+### WC-ARCH-14 · Merged into [WC-LIFE-11](lifecycle.md#wc-life-11--run-commands-through-serve-when-the-messenger-allows-one-connection-per-account)
+
+### WC-ARCH-15 · Each CLI runs its own background server, built on cli-core's process library
+
+- **Why:** a server shared between CLIs couples their releases and their failures.
+- **Enforced by:** review only.
+- **Example:** cli-core's `./background` export holds the lock per app and profile, the PID check and the systemd and
+  launchd units. `tg serve` and `max serve` are each built on it.
+- **Exceptions:** none.
+- **Applies to:** CLIs with a background process. **Since:** cli-base 0.41.0. **Rulings:** NEED-492.
+
+### WC-ARCH-16 · Layers below the commands never name a command
+
+- **Why:** an adapter that prints "check `tg polls show`" breaks when the command is renamed and cannot be shared.
+- **Enforced by:** review only.
+- **Example:** a tg adapter error carries a typed reason, such as `{ check: "polls.show" }`. The command layer turns
+  the reason into the words `tg polls show`.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-17 · Merged into [WC-LAY-8](layout.md#wc-lay-8--give-each-module-one-reason-to-change)
+
+### WC-ARCH-18 · An optional capability that is missing fails out loud
+
+- **Why:** a request that quietly becomes a smaller one gives the caller a wrong answer that looks right.
+- **Enforced by:** review only.
+- **Example:** a new adapter method is optional and reached with `capability()`. When it is absent, the command
+  refuses with a reason; it does not drop the filter or the scope it could not apply.
+- **Exceptions:** none.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-820.
+
+### WC-ARCH-19 · Shared packages print nothing and log nothing on their own
+
+- **Why:** what is written, and where, is the host's decision; a stray line breaks machine output.
+- **Enforced by:** review only.
+- **Example:** cli-base hands the host a `Logger` interface, a Pino adapter and a renderer. It never calls
+  `console.log`, nor `console.error`, which the lint allows elsewhere
+  ([WC-TOOL-9](toolchain.md#wc-tool-9--write-to-the-console-only-with-consoleerror-except-in-scripts)).
+- **Exceptions:** none.
+- **Applies to:** cli-base and cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-ARCH-20 · Keep HTTP out of cli-base's root export
+
+- **Why:** a CLI that only speaks a socket must not depend on an HTTP stack.
+- **Enforced by:** review only.
+- **Example:** a helper that reads a status code or a header goes to `@wirecat/cli-base/http`. How an entry point
+  is added is [WC-LAY-5](layout.md#wc-lay-5--add-an-entry-point-as-an-exports-entry-built-from-srcindexts).
+- **Exceptions:** none.
+- **Applies to:** cli-base. **Since:** cli-base 0.41.0. **Rulings:** NEED-15.
+
+## 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 `MODULARITY.md`](https://github.com/WireCatLabs/cli-base/blob/main/docs/dev/MODULARITY.md)
+- [cli-base `ARCHITECTURE.md`](https://github.com/WireCatLabs/cli-base/blob/main/docs/dev/ARCHITECTURE.md)
+- [cli-core `ARCHITECTURE.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/ARCHITECTURE.md)
+- [cli-core `ADAPTERS.md`](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/ADAPTERS.md)

package/docs/standards/ci.md

@@ -0,0 +1,159 @@
+# CI
+
+## Scope
+
+What runs where: the local hooks, the checks on every pull request and their time budget, full validation on each
+merge to `main`, and the monthly runs.
+
+Rule ids on this page are `WC-CI-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md). What each tool checks is on the [Toolchain page](toolchain.md); the release workflow is on the
+[Releases page](releases.md); which scanners must exist and how workflows are hardened is on the
+[Security page](security.md).
+
+"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-CI-1 · Run only staged lint and a staged secret scan before a commit
+
+- **Why:** a hook that takes more than a second makes people skip it, which is worse than a small hook.
+- **Enforced by:** `pnpm standards:check` · `standards.yml:standards`.
+- **Example:** the shared `lefthook` config runs, in parallel, Biome on the staged files and
+  `gitleaks git --staged --redact`. A clone without gitleaks gets a warning and can still commit; CI scans anyway.
+  The `prepare` script installs the hooks; `LEFTHOOK=0 git commit` skips them for one commit.
+- **Exceptions:** none.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-2 · Add no push hook, and no hook that installs, builds, checks types, generates or tests
+
+- **Why:** every check in a hook runs again in CI, so a slow hook only costs time and teaches people to bypass hooks.
+- **Enforced by:** review only.
+- **Example:** a repository's `lefthook.yml` holds only the `extends` line for `config/wirecat/lefthook.yml`. An agent
+  does not run `standards:check`, the full lint, spelling, a build or the test suite on each commit or push; it runs a
+  targeted check when it needs one.
+- **Exceptions:** none. cli-base `config/lefthook.yml` still has a pre-push typecheck, but no repository extends it.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-3 · Run the fast standards job on every pull request and every push to `main`
+
+- **Why:** it catches broken presets, lint, Markdown, types and new secrets in well under a minute, before review.
+- **Enforced by:** `standards.yml:standards`.
+- **Example:** the job does one cached install with lifecycle scripts off, then runs `pnpm standards:check`,
+  `pnpm lint`, `pnpm docs:lint`, `pnpm run --if-present ci:quick` and a gitleaks scan of the new commits only. A new
+  commit cancels the run it replaces. The job times out after five minutes, a ceiling for a stalled setup, not an
+  expected time.
+- **Exceptions:** none. Runner queues and cold downloads are outside the budget.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-4 · Keep `ci:quick` to early bug checks that finish within two minutes
+
+- **Why:** it is the only build-level check on a pull request, so it must stay fast enough that nobody wants it gone.
+- **Enforced by:** `standards.yml:standards` · `pnpm ci:quick`.
+- **Example:** what each repository runs today:
+  - tg, max, memo and wa: `pnpm typecheck && pnpm build && pnpm lint:commands`;
+  - drive: `pnpm typecheck && pnpm lint:commands`, which builds first;
+  - zoom, cli-base and cli-testing: `pnpm typecheck`;
+  - cli-core: `pnpm typecheck` and its command lint test;
+  - cli-docs: its unit tests, without the one that needs generated pages;
+  - community: its script tests.
+- **Exceptions:** never put live-account suites, agent suites, full tests, coverage or platform jobs here.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-5 · Keep full tests, builds of documents, parity and platform suites out of pull request CI
+
+- **Why:** pull request CI is the step people wait on; the heavy suites run once on `main`, where a failure still
+  shows within minutes of the merge.
+- **Enforced by:** review only.
+- **Example:** on a pull request, only the standards job, the changelog guard and small path-scoped jobs run. Coverage,
+  contracts, the test matrix, `docs:check`, parity, Windows and macOS run in full validation (WC-CI-7).
+- **Exceptions:** a path-scoped job that tests one platform-specific file may run on pull requests, such as cli-base
+  `macos.yml` for the path code. cli-docs and community run `security-pr.yml`, a new-commit secret scan. Third-party
+  security apps may post their own checks.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-6 · Run the changelog guard on every pull request
+
+- **Why:** the guard is the only check that reads the changelog on a pull request.
+- **Enforced by:** `changelog-guard.yml:guard`.
+- **Example:** each repository's `changelog-guard.yml` calls
+  `WireCatLabs/cli-base/.github/workflows/changelog-guard.yml` at a pinned commit, on `opened`, `edited`,
+  `synchronize` and `reopened`. The changelog rules it applies are on the [Documents page](docs.md).
+- **Exceptions:** cli-testing, cli-docs and community have no changelog guard yet.
+- **Applies to:** the CLIs, cli-base and cli-core. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-7 · Run full validation once on each merge to `main`, on Linux, without publishing
+
+- **Why:** a merge that breaks the full suite shows up the same hour, not at the next release.
+- **Enforced by:** `main.yml:validation` · `node-ci.yml:check` · `node-ci.yml:bun` · `node-ci.yml:secrets`.
+- **Example:** `main.yml` calls the repository's own `ci.yml`, which calls cli-base `node-ci.yml`. That runs
+  `pnpm lint`, `pnpm typecheck`, `pnpm test:coverage`, `pnpm build`, then the project's `checks` lines (for max:
+  contracts, the no-leak scan, the version check, `pnpm generate` and `git diff --exit-code`, the test matrix,
+  `docs:check` and parity), a Bun job, and a gitleaks scan of the whole history.
+- **Exceptions:** platform suites (Windows, macOS, install checks) are skipped here and run at release, monthly or on
+  request. Nothing in this run publishes or tags. cli-docs runs its full validation before each deployment and monthly
+  instead; community has no build to validate.
+- **Applies to:** the CLIs, cli-base, cli-core and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-8 · Call cli-base `node-ci.yml` from `ci.yml`, pinned to a tag or commit
+
+- **Why:** one shared workflow keeps the full suite the same everywhere, and a pin keeps a cli-base change from
+  breaking ten repositories at once.
+- **Enforced by:** `ci.yml:ci`.
+- **Example:** `uses: WireCatLabs/cli-base/.github/workflows/node-ci.yml@<commit> # v0.31.0`, with the project's own
+  checks in the `checks` input and `bun-run` for the Bun job. A job that only one repository needs stays beside it in
+  that repository's `ci.yml`.
+- **Exceptions:** never pin to `main`. cli-base itself calls `./.github/workflows/node-ci.yml`. cli-docs has its own
+  full workflow for the site, and community has none.
+- **Applies to:** the CLIs, cli-core and cli-testing. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-9 · Run full validation and release security on the first day of each month, without publishing
+
+- **Why:** a repository with no merges for weeks still meets new advisories, new runner images and expired pins.
+- **Enforced by:** `monthly.yml:validation` · `monthly.yml:security`.
+- **Example:** `monthly.yml`, from the community template, calls the repository's `ci.yml` and the pinned cli-base
+  `release-checks.yml`. Each repository has its own minute, between 02:17 and 03:21 UTC, so runs do not overlap.
+- **Exceptions:** community has no build, so it runs only the release security checks, at 03:47 UTC. A monthly run
+  never publishes a package or deploys the site.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+
+### WC-CI-10 · Run heavy security checks only at release, monthly or on request
+
+- **Why:** a pull request needs a fast secret check; source scanners take minutes and find nothing new on most
+  changes.
+- **Enforced by:** `release.yml:checks` · `monthly.yml:security`.
+- **Example:** cli-base `release-checks.yml` runs the production dependency audit, the workflow scan (`zizmor`),
+  CodeQL and a full-history gitleaks scan. A release depends on it. A pull request runs only the new-commit gitleaks
+  scan in the standards job.
+- **Exceptions:** none. Do not add a heavy scanner to an editor hook, a stop hook or an ordinary pull request job.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** sc:9.
+
+### WC-CI-11 · Moved to [WC-SECR-20](security.md#wc-secr-20--pin-each-third-party-action-to-a-commit-and-give-each-workflow-read-only-defaults)
+
+### WC-CI-12 · Merge to `main` only through a pull request whose checks all passed
+
+- **Why:** a red merge breaks `main` for every parallel branch, and an admin merge skips the only gate there is.
+- **Enforced by:** review only.
+- **Example:** `gh pr checks <number>` shows every line as pass before `gh pr merge`. Never merge with `--admin`. A
+  release changes `main` the same way
+  ([WC-REL-2](releases.md#wc-rel-2--main-changes-only-through-a-pull-request-also-during-a-release)).
+- **Exceptions:** none.
+- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** NEED-381.
+
+### WC-CI-13 · Start no live messenger or account test from a workflow
+
+- **Why:** a live test acts on a real account; only a person who chose to run it may start it.
+- **Enforced by:** review only.
+- **Example:** the offline contracts run in full validation. The live scenarios run only by hand, through the CLI's
+  live-test procedure, on test accounts.
+- **Exceptions:** none.
+- **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. The procedures stay in their own homes.
+
+- [community check schedule](https://github.com/WireCatLabs/community/blob/main/standards/CHECKS.md): the rough timings
+- [cli-testing CI folder](https://github.com/WireCatLabs/cli-testing/tree/main/docs/ci): the cross-project timing
+  table, the monthly runbook and the contract runner