@wirecat/cli-base 0.63.0 → 0.64.0

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.63.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
     }