@wirecat/cli-base 0.62.0 → 0.64.0

package/docs/standards/ci.md

@@ -10,8 +10,9 @@ Rule ids on this page are `WC-CI-<n>`. How to read a rule, how ids work and whic
 [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. cli-template follows every rule here as a CLI does
+"The WireCat repositories" on this page means every WireCat CLI (today tg, max, memo, drive, zoom, wa and gcal; a
+CLI made with `npx @wirecat/cli-template new` counts from its first commit), cli-base, cli-core, cli-testing, cli-docs,
+plus community itself. cli-template follows every rule here as a CLI does
 ([New CLI](new-cli.md#the-template-repository-itself)).
 
 ## Rules
@@ -24,7 +25,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   `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.
+- **Applies to:** the WireCat 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
 
@@ -34,7 +35,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   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.
+- **Applies to:** the WireCat 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`
 
@@ -45,7 +46,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-4 · Keep `ci:quick` to early bug checks that finish within two minutes
 
@@ -61,7 +62,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
 - **Exceptions:** never put live-account suites, agent suites or platform jobs here. Full tests and coverage run in
   the pull request validation job ([WC-CI-5](#wc-ci-5--run-the-full-linux-validation-on-every-pull-request-and-keep-platform-suites-out)),
   not in `ci:quick`.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-5 · Run the full Linux validation on every pull request, and keep platform suites out
 
@@ -139,10 +140,13 @@ cannot pass yet; the `skip` input names it.
 
 The shared workflows are not in the npm package, because CI runs the pinned commit, not the installed copy. To see
 what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/…@<commit>` lines in `ci.yml`,
-`release.yml` and `monthly.yml`, and opens each workflow file at that commit in cli-base.
+`release.yml` and `monthly.yml`, and opens each workflow file at that commit in cli-base. The fresh-agent audit on the
+[New CLI](new-cli.md#done-when) page is given these files for this reason, beside the handbook and the repository;
+its prompt in cli-template says so from cli-template 0.8.0. A CLI on an older template takes the prompt with
+`upgrade`.
 
 - **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.
+  breaking every repository at once.
 - **Enforced by:** `ci.yml:ci`.
 - **Example:** `uses: WireCatLabs/cli-base/.github/workflows/node-ci.yml@<commit> # v0.31.0`, with `cli: true` for
   the CLI steps (WC-CI-7), the project's extra checks in the `checks` input and `bun-run` for the Bun job. A job that only one repository needs stays beside it in
@@ -158,12 +162,29 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
 - **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:20 UTC, so runs do not overlap. No
   check compares the minutes across repositories; review keeps them apart. A CLI made from cli-template starts with
-  the template's own minute and changes it (see [New CLI](new-cli.md)).
+  the template's own minute and changes it (see [New CLI](new-cli.md)). Taken minutes, from each `monthly.yml` on
+  the default branch:
+
+  | UTC | Repository |
+  |---|---|
+  | 02:17 | cli-base |
+  | 02:24 | whatsapp-cli |
+  | 02:27 | gcal-cli |
+  | 02:31 | cli-memo |
+  | 02:38 | cli-core |
+  | 02:45 | drive-cli |
+  | 02:52 | cli-testing |
+  | 02:59 | max-cli |
+  | 03:02 | cli-template |
+  | 03:06 | tg-cli |
+  | 03:13 | zoom-cli |
+  | 03:20 | cli-docs |
+
 - **Exceptions:** cli-core also builds and probes its native packages in their own workflows, after the window:
   `onnx.yml` at 03:27 and `sqlite.yml` at 03:37 UTC. A scheduled run of either never publishes; only a manual run
   with `publish` does. 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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CI-10 · Run heavy security checks only at release, monthly or on request
 
@@ -177,7 +198,7 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
   job ([WC-CI-5](#wc-ci-5--run-the-full-linux-validation-on-every-pull-request-and-keep-platform-suites-out)); it
   takes seconds. The dependency audit, `zizmor` and CodeQL stay out. 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.
+- **Applies to:** the WireCat 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)
 
@@ -195,7 +216,7 @@ what CI runs, an audit reads the `uses: WireCatLabs/cli-base/.github/workflows/
   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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** NEED-381.
 
 ### WC-CI-13 · Start no live messenger or account test from a workflow
 

package/docs/standards/commands.md

@@ -77,8 +77,9 @@ catalogue and parity manifest stay in cli-core
 - **Example:** ranking is `stats messages top`, not a ranking mode on `search messages`. Options choose the scope,
   measure, order or format of the same action. No command both shows and changes something.
 - **Exceptions:** a documented preparatory fetch such as `--sync-first`. It keeps its own permissions and reports
-  its outcome.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+  its outcome. `mcp --revoke` forgets every login given to a browser app; it stays an option on `mcp` because it
+  belongs with the HTTP server's login state.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1864.
 
 ### WC-CMD-7 · Never let two commands overlap
 

package/docs/standards/kit-surface.md

@@ -18,11 +18,11 @@ nothing from either package.
 | Package and path | Exports |
 |---|---|
 | `@wirecat/cli-base` | `catchCrashes`, `CliError`, `configFilePath`, `mcpErrorResult`, `resolvePaths` |
-| `@wirecat/cli-base/commands` | `annotate`, `CommandInfo`, `describeProgram` |
+| `@wirecat/cli-base/commands` | `annotate`, `CommandInfo`, `COMMANDS_PAGE_LABELS` (in `scripts/`), `commandsPage` (in `scripts/`), `describeOptions` (in `scripts/`), `describeProgram` |
 | `@wirecat/cli-base/codegen` | `writeArtifacts` (in `scripts/`) |
 | `@wirecat/cli-base/release` | `DocsRules`, `JOURNAL_IDS`, `markdownFiles`, `packContents` (in `scripts/`) |
-| `@wirecat/cli-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `itemOf`, `LOCAL_READ`, `outputFor`, `privateFiles`, `profileFree`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `runsCommand`, `settingsFor`, `skillCommand`, `upgradeCommand` |
-| `@wirecat/cli-core/mcp` | `McpCommand`, `registerCommands`, `runCommandForAgent`, `toolsFromCommands` |
+| `@wirecat/cli-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandHelpMarkdown` (in `scripts/`), `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `httpTokenFile`, `itemOf`, `LOCAL_READ`, `MCP_HTTP_DEFAULT_PORT`, `mcpServerCommand`, `outputFor`, `privateFiles`, `profileFree`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `refuseUnderReadOnly`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `runsCommand`, `settingsFor`, `skillCommand`, `upgradeCommand` |
+| `@wirecat/cli-core/mcp` | `httpLockFile`, `MCP_PATH`, `McpCommand`, `portOf`, `publicUrlOf`, `registerCommands`, `runCommandForAgent`, `serveOverHttp`, `toolsFromCommands` |
 | `@wirecat/cli-core/sends` | `Level` |
 | `@wirecat/cli-core/update` | `appUpdate` |
 | `@wirecat/cli-core/testing` | `ARGV_LOG`, `argvLogSetup` |

package/docs/standards/layout.md

@@ -122,6 +122,38 @@ Rule ids on this page are `WC-LAY-<n>`. How to read a rule, how ids work and whi
 - **Exceptions:** none.
 - **Applies to:** all CLIs and libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 
+### WC-LAY-10 · Ship the bin as a bundle that `cli-dev bundle` builds
+
+A command that imports about a thousand module files spends most of its start resolving and reading them. tg's
+bundle halved `--help` and every other short command
+([measurements](https://github.com/WireCatLabs/cli-testing/blob/main/performance/startup/tg-bundle/README.md)).
+
+- **Why:** one shared build keeps what tg learned in one place: lazy imports stay lazy, files and packages are found
+  where they were installed, and a running server survives an in-place upgrade.
+- **Enforced by:** `<app>: pnpm build` · `<app>: pnpm smoke:node` · `<app>: pnpm smoke:bun`.
+- **Example:** `"build": "tsc --build --force && cli-dev bundle --bin dist/bin/tg.js --external '@mtcute/*' --external undici"`,
+  with `esbuild` as a devDependency in cli-base's peer range. `dist/bundle/` holds the bundle, split so every lazy
+  `import()` stays a chunk of its own; `dist/bin/tg.js` stays the path `"bin"` names and becomes a loader. What it
+  does and checks:
+  - The loader answers `--version` from the version built into it, turns the compile cache on, and imports the
+    bundle. Under `serve`, `watch` and `mcp` it loads every chunk 2 s after start and resolves imports between chunks
+    without looking on disk: an upgrade deletes the old chunks, whose names carry a hash.
+  - In the CLI's own modules and in cli-core's and cli-base's (`--anchor` adds a package), `import.meta.url` is the
+    module's place before bundling, so skills, fonts, scenarios, migrations and child scripts are found. A package
+    they load at run time resolves from that place too (a resolve hook under Node, `Bun.resolveSync` under Bun):
+    pnpm installs cli-core's dependencies beside cli-core.
+  - A dynamic import of CommonJS (`yaml`) keeps its named exports. Names are kept (`keepNames`), so `commands --json`
+    and errors read as before.
+  - Native modules, Bun's SQLite and the packages cli-core loads by name stay outside; `--external` adds the CLI's
+    own (`*` matches anything).
+  - The build fails when a bundled module would look for a file or package from the chunk's place, or when the loader
+    names a chunk that was not built. A third-party file read and found harmless is named with `--harmless`.
+  - The CLI's smoke test runs the built bin under Node and Bun and checks that the store opens and the document
+    readers resolve.
+- **Exceptions:** a CLI moves when its outputs are byte-identical before and after and its start gains 15% or more;
+  until then it ships `tsc`'s output. cli-base, cli-core and cli-testing ship libraries, not a bin.
+- **Applies to:** all CLIs. **Since:** cli-base 0.64.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

package/docs/standards/new-cli.md

@@ -12,7 +12,7 @@ built on are on the [Kit surface](kit-surface.md) page.
 ## Start with the template
 
 ```sh
-npx @wirecat/cli-template new cal-cli --command cal --package @wirecat/cal-cli --owner WireCatLabs \
+npx @wirecat/cli-template new gcal-cli --command gcal --package @wirecat/gcal-cli --owner WireCatLabs \
   --category calendar --content-lang en,ru --sign-in oauth --api official-client --filters time,person,text \
   --never-store tokens,secret-links --untrusted names,links
 ```
@@ -24,7 +24,7 @@ the choices. Nothing is guessed.
 |---|---|---|
 | `<name>-cli` | the repository folder | any name |
 | `--command` | the command word people type | one word |
-| `--package` | the npm package name | a scoped name, such as `@wirecat/cal-cli` |
+| `--package` | the npm package name | a scoped name, such as `@wirecat/gcal-cli` |
 | `--owner` | the GitHub owner of the repository | an owner |
 | `--category` | what the CLI reads | `messenger`, `mail`, `notes`, `files`, `calendar`, `meetings` |
 | `--content-lang` | the languages of the content | a list, such as `en,ru` |
@@ -42,11 +42,11 @@ a reference CLI for your category in `AGENTS.md`. It does not install packages,
 publish. Then:
 
 ```sh
-cd cal-cli && pnpm install && pnpm ci:quick
+cd gcal-cli && pnpm install && pnpm ci:quick
 git add -A && git commit -m "chore: start from @wirecat/cli-template"
 ```
 
-Give the agent `docs/dev/DESIGN.md` next. Every example passes a profile explicitly, such as `cal personal doctor`.
+Give the agent `docs/dev/DESIGN.md` next. Every example passes a profile explicitly, such as `gcal personal doctor`.
 The reference CLI is the one to compare with when a step is unclear.
 
 The copy already holds every file this handbook asks for: the required root commands (`commands`, `doctor`,
@@ -61,6 +61,15 @@ The rules they keep are on the area pages: [Commands](commands.md), [MCP](mcp.md
 Later template changes come in with `npx @wirecat/cli-template upgrade`, file by file: apply, replace, skip or diff.
 See [Kit surface](kit-surface.md#how-your-cli-stays-current).
 
+The template's `template.json` splits the copy in two. A **seed** (`DESIGN.md`, `CLAUDE.md`, `README.md`, the user
+pages, `src/`) is the CLI's own from the first commit: rewrite it freely. A **template-owned** file (`AGENTS.md`,
+`docs/dev/TESTING.md`, `docs/dev/reference-clis.md`, the skills under `docs/dev/skills/`, `.github/`) holds only what
+is true for every CLI made from the template. Do not rewrite one to fit this CLI: put the CLI's own facts in a seed.
+A template-owned page that is wrong for this CLI is a gap in cli-template, under
+[WC-DOC-3](docs.md#wc-doc-3--every-document-states-current-facts-rewrite-a-wrong-sentence-in-place) like any other
+wrong sentence: fix it there, and `upgrade` brings the fix. Change it in the CLI only where the CLI must differ for
+good; `upgrade` then asks before it touches the change.
+
 ## Four steps that need a person
 
 `new` prints these at the end.
@@ -69,12 +78,14 @@ See [Kit surface](kit-surface.md#how-your-cli-stays-current).
    changes only through a pull request, required status checks, and no bypass. Add the ruleset after the first
    commit is on `main`, since a pull request rule leaves an empty repository no way to get one, and the required
    check names exist only once CI has run. See [Releases](releases.md).
-2. **Set npm trusted publishing** for the new package, naming `release.yml`, and add any secrets the CI needs. See
+2. **Set npm trusted publishing** for the new package, naming `release.yml`, and add any secrets the CI needs. npm
+   offers this only once the package exists, so the owner publishes the first version with `bin/release --local`
+   and sets it right after. See
    [WC-REL-11](releases.md#wc-rel-11--publish-from-github-actions-with-npm-trusted-publishing).
-3. **Pick a monthly cron minute** between 02:17 and 03:20 UTC that no other repository uses. The copy of
-   `.github/workflows/monthly.yml` keeps the template's own minute, 03:02, and no check compares minutes across
-   repositories, so change it by hand. See
+3. **Pick a monthly cron minute** between 02:17 and 03:20 UTC that is not in the list of taken minutes under
    [WC-CI-9](ci.md#wc-ci-9--run-full-validation-and-release-security-on-the-first-day-of-each-month-without-publishing).
+   The copy of `.github/workflows/monthly.yml` keeps the template's own minute, 03:02, and no check compares minutes
+   across repositories, so change it by hand, and add the new minute to the list in the step 4 pull request.
 4. **WireCat CLIs only: join the shared lists.** A pull request to cli-base's `PARITY_GROUPS` (at least the `all`
    group, which compares the shared root commands), a line in cli-core's `WIRECAT_TOOLS` and a line in cli-docs'
    `tools.json`. A messenger also joins cli-core's `parity.json`. A CLI outside WireCatLabs keeps its parity groups
@@ -89,17 +100,20 @@ All of these pass on `main`, before the first release:
 - `cli-dev lint` against the built CLI. It also makes the CLI fail once in an empty home and checks that
   `runs list` shows the failed run
 - `cli-dev audit --for <cli> --lint <cli>=lint` with no new finding, run with the command trees of the CLIs in
-  the same parity groups. `--lint` judges the CLI's lint rules by its own `lint/` folder. What it shares with the
-  other CLIs is judged by cli-base's `audit/baseline`; the pull request that adds the CLI to a parity group adds its
-  shared findings there
+  the same parity groups (`pnpm audit:commands`). `--lint` judges the CLI's lint rules by its own `lint/` folder.
+  What it shares with the other CLIs has no baseline: `audit/baseline` does not accept a shared-contract finding
+  (cli-base 0.51.0). Fix each one, or, where the CLI must differ for good, the pull request that adds it to a parity
+  group declares the exact difference with its reason in that group's `differences`
 - `pnpm contracts:check`
 - `cli-dev test-matrix --check`
 - `pnpm docs:check`, with `--pages`, and the CLI's `generate:check`
 - the changelog guard on a pull request
 - `pnpm release:check`
 
-The last test is a fresh agent. Give it only this handbook's [index](README.md) and the new repository, and ask it to
-audit the CLI. Every gap it lists is either a gap in the CLI, to fix before the first release, or a hole in the
+The last test is a fresh agent. Give it only this handbook's [index](README.md), the new repository and the cli-base
+workflow files its own workflows pin
+([WC-CI-8](ci.md#wc-ci-8--call-cli-base-node-ciyml-from-ciyml-pinned-to-a-tag-or-commit)), and ask it to audit the
+CLI. Every gap it lists is either a gap in the CLI, to fix before the first release, or a hole in the
 handbook, to fix here.
 
 ## The template repository itself
@@ -118,7 +132,7 @@ upgrade, and no script or agent reads its answers.
 | [WC-DOC-12](docs.md#wc-doc-12--a-runnable-command-in-a-document-has-no-placeholder-in-it) | Exempt only for the placeholder names `clidev`, `clidev-cli`, `@wirecat/clidev-cli` and `WireCatLabs/clidev-cli`, and the upper-case prefix `CLIDEV_` (as in `CLIDEV_PROFILE`). | `new` replaces each of them with the CLI's own name. Any other placeholder is still a gap. |
 | [WC-DOC-17](docs.md#wc-doc-17--each-entry-says-what-changed-for-the-caller-why-and-what-to-watch-for) | A changelog entry may name a file path. | The template's readers are CLI authors, who edit those files or take them with `upgrade`; for them a path is what they see. |
 
-Every other rule that applies to all CLIs, or to the ten repositories, applies to cli-template as it is written,
+Every other rule that applies to all CLIs, or to the WireCat repositories, applies to cli-template as it is written,
 with one limit for the copy tool. It follows the rules for code and the repository: Toolchain, Layout, Style,
 Testing, Security and Documents. It has no profile, no machine mode, no MCP server, no store and no agent reading its
 answers, so the rules for a CLI's commands and runtime do not reach it: Commands, Output, MCP, Accounts, Permissions,

package/docs/standards/permissions.md

@@ -20,8 +20,9 @@ Rule ids on this page are `WC-PERM-<n>`. How to read a rule, how ids work and wh
 tg, max and wa use cli-core's permissions and write guard in full. memo uses them for the shared commands only. drive
 has its own policy and guard, with its own `--read-only` flag. zoom has per-profile `permissions` from zoom-cli 0.35.0,
 read with cli-core's `levelFor`; its writes change Zoom meetings, its built-in default is `remote-meetings: ask`, and
-it has no send journal or recipient list, since it sends no messages. Where this page says "every CLI that writes",
-drive is a known gap.
+it has no send journal or recipient list, since it sends no messages. gcal declares its own keys through cli-core's
+`commandPermissions` and runs its event writes through cli-core's write guard (WC-PERM-22). Where this page says
+"every CLI that writes", drive is a known gap.
 
 WC-PERM-10 and WC-PERM-11 need cli-core 0.321.0, which tg, max and wa pin. WC-PERM-12 as written needs cli-core
 0.337.0; before it, the lock let through some local writes that overwrite what the owner saved. A command other
@@ -114,7 +115,8 @@ A default is never made stricter without the owner's word.
 - **Exceptions:** where the messenger has replies, `replies.send` is `deny`: a reply rule writes to people with nobody
   typing a command, so it waits for the owner's own `allow`. A messenger with no `replies` group, such as wa, has no
   use for the key.
-- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-568.
+- **Applies to:** messenger CLIs. A CLI that is not a messenger sets its own defaults (WC-PERM-22). **Since:** cli-base
+  0.41.0. **Rulings:** NEED-568.
 
 ### WC-PERM-7 · A built-in default only ever tightens
 
@@ -310,6 +312,34 @@ Moderation rules use the same four levels for each kind of action (delete, remov
   looser than the profile's `chats.moderate`; the code does not check that yet.
 - **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-306, NEED-310.
 
+### WC-PERM-22 · A CLI that is not a messenger declares its own keys and defaults with `commandPermissions`
+
+A messenger's keys come from its resources (`messages`, `chats`). Any other CLI names its own with cli-core's
+`commandPermissions({ keyOf, extra, defaults })`, passed as `settingsFor(app, { permissions })` (cli-core 0.450.0):
+
+- **Keys.** Each command is checked against its own path (`events.create`), the default `keyOf`. Housekeeping has no
+  key (WC-PERM-5). `extra` adds the keys a command checks inside itself, such as one per generated API method
+  (`api.calendar.events.insert`). A key that names no command is refused when it is set or saved.
+- **Defaults.** `defaults` holds the CLI's built-in levels, beside cli-core's. They only ever tighten (WC-PERM-7). A
+  CLI picks them for what its writes do, not by WC-PERM-6's messenger list: they ask before a write people other
+  than the owner see or cannot easily undo, and deny what an agent must never do unasked.
+- **Read-only lock and guard.** `<PREFIX>_READ_ONLY` refuses every write to the service, as in WC-PERM-12. Every
+  write runs through cli-core's write guard with `permissionDefaults: configuration.permissions.defaults`
+  (cli-core 0.455.0), so `ask` is a y/N question at a terminal (WC-PERM-9) and every attempt goes into the send journal
+  (WC-PERM-17). A CLI that sends no messages has no recipient list or hourly limit to set.
+
+- **Why:** one permission model for every CLI; a CLI-own layer drifts from the shared one and is audited by nobody.
+- **Enforced by:** `cli-core: src/cli/command-permissions.test.ts` · `cli-core: src/calendar/cli/writes.test.ts`.
+- **Example:** a calendar CLI takes cli-core's `CALENDAR_WRITE_DEFAULTS` and `CALENDAR_WRITE_KEYS`
+  (`@wirecat/cli-core/calendar`, cli-core 0.458.0): `events create`, `update`, `respond` and `delete` ask, since each
+  changes a calendar other people may share or be invited from; `events.delete.series` (a whole repeating series) and
+  `events.notify` (mail the attendees) are `deny` until the owner allows them. gcal adds its own: a generated
+  `api <method>` that writes asks, and one that shares, empties or gives away a calendar is `deny`.
+- **Exceptions:** known gaps: drive keeps its own policy and `--read-only` flag, zoom reads its own
+  `remote-meetings` key with `levelFor`, and memo uses cli-core's permissions for the shared commands only. None of
+  them declares `commandPermissions` yet.
+- **Applies to:** every CLI that writes and is not a messenger. **Since:** cli-base 0.64.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

package/docs/standards/releases.md

@@ -125,7 +125,11 @@ on the [CI](ci.md) page.
 - **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.
+  publisher settings are updated. npm sets a trusted publisher on the package's settings page
+  ([npm docs](https://docs.npmjs.com/trusted-publishers)), which a package has only once it is published, so its
+  first version is published with `bin/release --local` by the owner, from a clean `main`. Right after it, the owner
+  adds the trusted publisher on npmjs.com (step 2 of [New CLI](new-cli.md#four-steps-that-need-a-person)), and every
+  later version goes through `release.yml`.
 - **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
@@ -181,12 +185,18 @@ on the [CI](ci.md) page.
 
 ### WC-REL-16 · The package ships only the files it names
 
+A CLI's `files` holds only what the installed CLI runs from or shows its user: `dist`, the agent skill (`skills`),
+`README.md`, `LICENSE`, and files its code reads or runs after install, such as `scenarios` for `guide`, an `install`
+script, third-party notices and licenses. `CHANGELOG.md` may ship too. It never holds `src/`, tests, fakes or
+fixtures, `scripts/`, `.github/`, `bin/release`, `config/`, `lint/`, `contracts/`, `docs/dev/` or `template.json`.
+
 - **Why:** a stray file in the package can leak local data and grows every install.
 - **Enforced by:** `node-ci.yml:check` · `<app>: pnpm package: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. Each CLI's `package:check` runs `packContents`; tg and max as
-  `release-check.ts --package-only`.
+- **Exceptions:** cli-template's own package ships the skeleton's sources and configs, since `new` copies them; the
+  `files` list `new` writes into a CLI follows this rule. Each CLI's `package:check` runs `packContents`; tg and max
+  as `release-check.ts --package-only`.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ## Sources

package/docs/standards/security.md

@@ -67,8 +67,9 @@ name. Any other top-level key is written as `[not allowed]`. A key that names co
 ### 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`).
+`0600`. The keyring service is the CLI's app name, `appName` in its identity (`max-cli`, `gcal-cli`, `cli-memo`), not
+the command word people type (`max`, `gcal`). 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.
@@ -274,7 +275,7 @@ general words.
   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; and
+- **Applies to:** the WireCat repositories: every CLI, cli-base, cli-core, cli-testing, cli-docs and community; and
   cli-template.
   **Since:** cli-base 0.41.0. **Rulings:** none.
 

package/docs/standards/store.md

@@ -30,7 +30,7 @@ Related pages: which account a read covers, and how a read across accounts is as
   `%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.
+- **Applies to:** CLIs that keep local data through cli-core (tg, max, wa, memo, drive, zoom, gcal). **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

package/docs/standards/testing.md

@@ -44,7 +44,7 @@ and which run after merge is in [CI](ci.md).
   file, listed after the shared one, adds only what is its own, such as a default profile.
 - **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. cli-base, cli-core, the six CLIs and cli-template load the shared
+- **Applies to:** all CLIs and the shared packages. cli-base, cli-core, every CLI and cli-template load the shared
   setup first in `setupFiles`; cli-testing does not use it yet. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TEST-2 · No test opens a real credential store
@@ -94,7 +94,9 @@ and which run after merge is in [CI](ci.md).
 - **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.
+  and the 10 slowest files. A test may wait for a local process or server it started, for example polling its
+  status with `vi.waitFor` and a timeout shorter than the test's own; that waits for an event, not for time. A
+  fixed sleep or `setTimeout` is still a wait for real time.
 - **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.
 
@@ -171,7 +173,11 @@ and which run after merge is in [CI](ci.md).
   `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.
+- **Exceptions:** commands generated from a service's API description, such as drive's and gcal's
+  `api <method>` from a Google Discovery snapshot, share one reason for the whole group (`api *` and its options).
+  It names two tests: one that checks every generated command's options against the snapshot, and one that drives a
+  generated command through `run()` into the executor every generated command shares. A hand-written command in the
+  same CLI still needs its own test or live scenario.
 - **Applies to:** all CLIs. memo's check fails only on a stale page, not yet on an option with no test.
   **Since:** cli-base 0.41.0. **Rulings:** NEED-359.
 

package/docs/standards/toolchain.md

@@ -15,22 +15,23 @@ The [community standards](https://github.com/WireCatLabs/community/blob/main/sta
 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. cli-template follows every rule here as a CLI does
+"The WireCat repositories" on this page means every WireCat CLI (today tg, max, memo, drive, zoom, wa and gcal; a
+CLI made with `npx @wirecat/cli-template new` counts from its first commit), cli-base, cli-core, cli-testing, cli-docs,
+plus community itself. cli-template follows every rule here as a CLI does
 ([New CLI](new-cli.md#the-template-repository-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.
+- **Why:** one reviewed set of presets keeps the 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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-2 · Make each root config extend its copy in `config/wirecat/`
 
@@ -41,7 +42,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   `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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-3 · Pin the tool versions that `toolchain.json` names
 
@@ -50,7 +51,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
 - **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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-4 · Extend the shared TypeScript config, and do not loosen it
 
@@ -101,7 +102,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
 - **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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-8 · Keep the shared Biome rules at error
 
@@ -111,7 +112,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-9 · Write to the console only with `console.error`, except in `scripts/`
 
@@ -122,7 +123,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
 - **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.
+- **Applies to:** the WireCat 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
 
@@ -132,7 +133,7 @@ cli-testing, cli-docs, plus community itself. cli-template follows every rule he
   `// 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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-11 · Keep the three grit plugins that block unsafe calls
 
@@ -149,7 +150,7 @@ no-unbounded-spread ([WC-TOOL-12](#wc-tool-12--do-not-spread-a-list-of-user-data
   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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-12 · Do not spread a list of user data into call arguments
 
@@ -159,7 +160,7 @@ no-unbounded-spread ([WC-TOOL-12](#wc-tool-12--do-not-spread-a-list-of-user-data
   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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-13 · Cap every file at 1,000 lines with Biome
 
@@ -172,7 +173,7 @@ no-unbounded-spread ([WC-TOOL-12](#wc-tool-12--do-not-spread-a-list-of-user-data
   `src/telegram/adapter.ts`; four files in cli-core). A smaller cap is allowed: zoom uses 500. cli-docs turns it off for
   stylesheets. Biome reads only JavaScript and TypeScript, so the cap does not cover
   code in another language, such as wa's Go engine; the review signals of WC-LAY-7 still apply to it.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-14 · Turn on the import cycle rule
 
@@ -180,7 +181,7 @@ no-unbounded-spread ([WC-TOOL-12](#wc-tool-12--do-not-spread-a-list-of-user-data
 - **Enforced by:** `pnpm lint` · `standards.yml:standards` (the shared Biome base, like WC-TOOL-8).
 - **Example:** the shared Biome base sets the suspicious rule noImportCycles to error.
 - **Exceptions:** none.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-15 · Declare layer boundaries as restricted imports in `biome.json`
 
@@ -218,7 +219,7 @@ no-unbounded-spread ([WC-TOOL-12](#wc-tool-12--do-not-spread-a-list-of-user-data
 - **Exceptions:** a general word goes into the community word list, not into each project. cli-base checks
   `README.md` and `docs/standards/`; cli-docs its site pages in `content/docs/`; community every Markdown file it
   publishes. cli-core, zoom and cli-testing check only `README.md` yet.
-- **Applies to:** the ten repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-18 · Lint Markdown with `markdownlint-cli2` and the shared preset
 
@@ -227,7 +228,7 @@ no-unbounded-spread ([WC-TOOL-12](#wc-tool-12--do-not-spread-a-list-of-user-data
 - **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.
+- **Applies to:** the WireCat repositories. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-TOOL-19 · Check user pages with `rumdl` and the shared `rumdl.toml`
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.62.0",
+  "version": "0.64.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",
@@ -135,6 +135,7 @@
     "@vitest/coverage-v8": "^5.0.5",
     "commander": "^15.0.0",
     "cspell": "10.4.0",
+    "esbuild": "0.28.2",
     "lefthook": "2.2.2",
     "markdownlint-cli2": "0.24.0",
     "typescript": "^7.0.2",
@@ -146,12 +147,16 @@
   },
   "peerDependencies": {
     "commander": ">=15",
+    "esbuild": "^0.28.0",
     "vitest": ">=5"
   },
   "peerDependenciesMeta": {
     "commander": {
       "optional": true
     },
+    "esbuild": {
+      "optional": true
+    },
     "vitest": {
       "optional": true
     }