@wirecat/cli-base 0.59.0 → 0.61.0

package/CHANGELOG.md

@@ -8,6 +8,48 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.61.0 — 26.10.2026
+
+### Changed — may break callers
+
+- **A run record keeps the command line as typed**
+  ([Security](docs/standards/security.md#wc-secr-1--private-data-and-secrets-never-reach-a-log-a-fixture-or-a-committed-document)).
+  The handbook said a run record never holds message text; a run's `argv` now keeps the words typed, so the owner can
+  read back what was run. A secret stays hidden: an option or argument marked with cli-core's `secretInput(...)`, one
+  named for a token, password, secret, credential, cookie, authorization or API key, a password in a URL, a long
+  opaque string. `record_input: false` in a CLI's config masks as before. A CLI's tests that assert a typed marker is
+  absent from its run folder now look outside `argv` ([Testing](docs/standards/testing.md)), and a CLI's own document
+  that says its run log hides what was typed needs the same change.
+
+## 0.60.0 — 26.10.2026
+
+### Added
+
+- **`node-ci.yml` takes `test-shards` (2 to 8) to run `test:coverage` on that many runners.** The `check` job then
+  skips the tests; `test (i/n)` jobs each run one Vitest shard with the blob reporter, and a `coverage` job merges
+  them and enforces the coverage floor of the repository's Vitest config. Each shard runs with the floor at zero,
+  because one shard alone covers a fraction of the code. `coverage` fails, rather than being skipped, when a shard
+  fails, and when fewer reports than shards arrive. A repository that requires its tests to pass adds
+  `<job> / ci / coverage` to its required checks. With `cli: true`, `test:matrix:check` moves from `check` to
+  `coverage` and reads the shards' argv logs joined. Default 1: the tests stay in `check`, as before.
+- **Before 1.0.0, a release with a breaking change raises the minor version**
+  ([Releases](docs/standards/releases.md#wc-rel-7--versions-are-xyz-before-100-a-breaking-change-raises-the-minor)).
+  A section with an entry under "Changed — may break callers" or "Removed", or a new feature, raises the minor; only
+  fixes and document changes raise the patch. npm's `^0.x.y` takes every patch of that minor, so a patch must not
+  break anyone. The rule used to allow a breaking change in a patch release.
+
+### Fixed
+
+- **Handbook corrections from the cli-template 0.1.8 audit.**
+  [Kit surface](docs/standards/kit-surface.md) lists every cli-base and cli-core export the template uses, in `src/`
+  and `scripts/`, including `privateFiles` and `profileFree`, and the config files it extends.
+  [Toolchain](docs/standards/toolchain.md): the `engines` example is `^22.16.0 || >=24`, as cli-core and cli-template
+  pin it; `tsconfig.test.json` extends the shared test config last and sets no `exclude` of its own, since the shared
+  file already sets `"exclude": []`; the spell check covers `README.md` and every user page in `docs/`.
+  [Style](docs/standards/style.md): a cast may stay only if it was on `main` on 17.10.2026, when the rule against
+  casts came in. [CI](docs/standards/ci.md) says where an audit finds the shared workflows CI runs: at the commit
+  pinned in the repository's workflow files, not in the npm package.
+
 ## 0.59.0 — 26.10.2026
 
 ### Added

package/docs/standards/ci.md

@@ -66,8 +66,8 @@ cli-testing, cli-docs, plus community itself.
 
 - **Why:** a pull request that lowers coverage or breaks a contract must fail before it merges; once on `main` it
   blocks every other branch and the next release. It costs 2–3 minutes per pull request in the CLIs (measured: wa
-  2.9, tg 2.2, max 3.0) and about 8 in cli-core, where `test:coverage` alone takes 5m46s; splitting that job into
-  shards would need a new `node-ci.yml` input.
+  2.9, tg 2.2, max 3.0) and about 5 in cli-core, where `test:coverage` alone takes about 4; `node-ci.yml`'s
+  `test-shards` input splits it across runners.
 - **Enforced by:** `pr.yml:validation`.
 - **Example:** `pr.yml` runs on `pull_request` and calls the repository's own `ci.yml`, the same full validation as
   `main` (WC-CI-7): lint, typecheck, `test:coverage` with the coverage floor, build, the contracts, the test matrix,
@@ -133,6 +133,10 @@ cli-core's peer range holds the installed package back; in a repository made fro
 that apply are those of the handbook in the installed package. A newer `node-ci.yml` may run a step the repository
 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.
+
 - **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`.

package/docs/standards/kit-surface.md

@@ -12,18 +12,25 @@ This page is a reference, not a rule page: it assigns no rule ids. How to start
 
 ## What the template imports
 
-The list is what the template's `src/` imports today, type imports included.
+The list is what the template's `src/` and `scripts/` import today, type imports and re-exports included. `kit/` imports
+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-core/cli` | `AppIdentity`, `changesAuthorityAt`, `commandsCommand`, `configCommand`, `Configuration`, `createProgram`, `environmentOf`, `GlobalFlags`, `itemOf`, `LOCAL_READ`, `outputFor`, `ProgramDefinition`, `ProgramOptions`, `readOnlyLockOf`, `REMOTE_WRITE`, `renderAnswer`, `rootOf`, `run`, `RunOptions`, `runsCommand`, `settingsFor`, `skillCommand`, `upgradeCommand` |
+| `@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/sends` | `Level` |
 | `@wirecat/cli-core/update` | `appUpdate` |
 | `@wirecat/cli-core/testing` | `ARGV_LOG`, `argvLogSetup` |
 
+The template's config files also reach cli-base: `tsconfig.json` and `kit/tsconfig.json` extend
+`tsconfig.base.json`, `tsconfig.test.json` and `tsconfig.scripts.json` extend the files of those names, `vitest.config.ts`
+loads `@wirecat/cli-base/testing/setup`, and `.vale.ini` reads the styles in `config/vale`.
+
 ## When one of them changes
 
 A change that makes a CLI change its code for one of these exports ships with two things:

package/docs/standards/lifecycle.md

@@ -14,8 +14,8 @@ A "one-shot" command does one job and ends: most commands. A "long-running" comm
 `lifetime: "persistent"` (it runs until it is stopped, such as `serve` or `watch`) or `lifetime: "interactive"` (it
 waits for a person, such as a login).
 
-A "run" is one command's record: what it was, how it ended, and its events, never content. The rules on what a
-run's events may hold are [WC-SECR-1](security.md#wc-secr-1--private-data-and-secrets-never-reach-a-log-a-fixture-or-a-committed-document)
+A "run" is one command's record: what it was, as typed, how it ended, and its events, which never hold content. The
+rules on what a run may hold are [WC-SECR-1](security.md#wc-secr-1--private-data-and-secrets-never-reach-a-log-a-fixture-or-a-committed-document)
 and [WC-SECR-2](security.md#wc-secr-2--a-log-keeps-only-known-attribute-keys-and-hides-content-keys).
 
 ### Who follows these rules today
@@ -198,7 +198,10 @@ provider's limit as often as it ends. These three rules make the next run carry
 ### WC-LIFE-15 · Keep a run log through cli-core, and read it back with `runs`
 
 A failed command is always kept as a run, unless the person turned recording off with `--no-record` or
-`record: false` in the config. `--record` keeps every run of a command that does its work inside cli-core's run
+`record: false` in the config. A run keeps the command line as typed, secrets hidden; `record_input: false` masks
+every value that may be content
+([WC-SECR-1](security.md#wc-secr-1--private-data-and-secrets-never-reach-a-log-a-fixture-or-a-committed-document)).
+`--record` keeps every run of a command that does its work inside cli-core's run
 (`context.run`, or `startRecording` in a program of its own). A run is a folder `<state>/runs/<day>/<run_id>/` with
 `run.json` and `events.jsonl`, one log record per line. `runs list` and `runs show` read it.
 

package/docs/standards/releases.md

@@ -82,13 +82,14 @@ on the [CI](ci.md) page.
 - **Exceptions:** a shared library that prints no version has no `src/version.ts`.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
-### WC-REL-7 · Versions are `x.y.z`; before 1.0.0 the changelog, not the number, marks a breaking change
+### WC-REL-7 · Versions are `x.y.z`; before 1.0.0 a breaking change raises the minor
 
-- **Why:** before 1.0.0 any release may change the API, so a caller reads "Changed — may break callers" before an
-  upgrade.
+- **Why:** npm's `^0.40.4` takes every `0.40.x`, so a patch reaches callers who never read its changelog. It must not
+  break them.
 - **Enforced by:** review only.
-- **Example:** raise the minor (`0.40.4` to `0.41.0`) for a release with new features, and the patch for one with only
-  fixes. A breaking change, in either kind of release, has an entry under "Changed — may break callers".
+- **Example:** raise the minor (`0.40.4` to `0.41.0`) for a release with a new feature or with any entry under
+  "Changed — may break callers" or "Removed". Raise the patch (`0.40.4` to `0.40.5`) only when every entry is a fix
+  or a change to the documents.
 - **Exceptions:** a pre-release version (`0.41.0-rc.1`) is chosen by hand.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 

package/docs/standards/security.md

@@ -21,13 +21,27 @@ Rule ids on this page are `WC-SECR-<n>`. How to read a rule, how ids work and wh
 ### WC-SECR-1 · Private data and secrets never reach a log, a fixture or a committed document
 
 Command output is the only place where a message the owner asked to read may appear. A log, a run record, a test
-fixture, a document and a commit message never hold message text, a token or a phone number.
+fixture, a document and a commit message never hold message text, a token or a phone number — with one exception:
+a run record keeps the command line the person typed.
+
+A run record's `argv` keeps the words as typed by default, so the history of what was run can be read back. A secret
+in them is always `[redacted]`: the value of an option or argument the CLI marks with cli-core's `secretInput(...)`,
+one whose name says token, password, secret, credential, cookie, authorization or API key, a password inside a URL,
+and a long opaque string. `record_input: false` in the CLI's config masks every value that may be content, and a
+config that will not load masks the same way. A problem report sent to other people (`doctor reports create`) masks
+the typed words always.
 
 - **Why:** a log or a repository is copied and kept far longer than anyone remembers; private data in it is a leak.
 - **Enforced by:** `node-ci.yml:secrets`.
 - **Example:** a log line says `{ "event": "send", "outcome": "sent", "count": 1 }`, not the text that was sent.
-- **Exceptions:** none. The scanners catch secrets of known shapes; message text and names are caught only in review.
-- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
+  `tg messages send Mom "see you at 5"` is kept in its run as typed; `tg bot api set-webhook --body '{…}'` keeps
+  `--body [redacted]`, since cli-core marks `--body` with `secretInput`. A CLI's own option that takes a secret is
+  declared `secretInput(new Option("--pin <code>"))` — although under
+  [WC-SECR-5](#wc-secr-5--a-secret-is-never-taken-on-the-command-line) such an option should not exist.
+- **Exceptions:** a run record's `argv`, as above: messaging CLIs already keep every message in the store, so the
+  words typed are not hidden from the owner's own run log. The scanners catch secrets of known shapes; message text
+  and names elsewhere are caught only in review.
+- **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1829.
 
 ### WC-SECR-2 · A log keeps only known attribute keys, and hides content keys
 

package/docs/standards/style.md

@@ -57,7 +57,8 @@ formatting, so this page does not repeat it.
 - **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.
+  a comment on that line that says why. A cast already on `main` on 17.10.2026, the day cli-base 0.41.0 added this
+  rule, may stay until that code is changed; `git blame` shows the date of a line. A cast added later is a finding.
 - **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

package/docs/standards/testing.md

@@ -124,7 +124,8 @@ and which run after merge is in [CI](ci.md).
 - **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:
+  and the test asserts that the marker is absent from output, errors and run events (a run's `argv` keeps what was
+  typed, so a marker typed on the command line is looked for outside it), 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.

package/docs/standards/toolchain.md

@@ -67,10 +67,12 @@ cli-testing, cli-docs, plus community itself.
 - **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.
+- **Example:** `tsconfig.test.json` has `"extends": ["./tsconfig.json", "@wirecat/cli-base/tsconfig.test.json"]`, in
+  that order, and adds at most `rootDir` and an `include` for more folders. The shared file covers all of `src/`,
+  tests included, checks it with `noEmit` and sets `"exclude": []`, so it must come last and the repository's file sets
+  no `exclude` of its own. A file that sets the build's `exclude` again 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.
@@ -81,13 +83,14 @@ cli-testing, cli-docs, plus community itself.
   the other.
 - **Enforced by:** `pnpm smoke:bun` · `node-ci.yml:bun` · `node-ci.yml:platforms` (the unit suite on Windows and
   macOS).
-- **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
+- **Example:** `"engines": { "node": "^22.16.0 || >=24" }` in `package.json`, as cli-core and cli-template have it:
+  Node 22 from 22.16.0, then 24 and later. 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. The unit suite runs on Windows and macOS for tg, max and drive (`platforms: true`); zoom and
-  memo still fail tests there, so theirs is off.
+- **Exceptions:** cli-docs and community publish no runtime package. tg needs `^22.19.0`. memo, drive and cli-base
+  do not run Node 22 in any workflow yet, and cli-base's own `engines` is still `>=22`. The unit suite runs on Windows
+  and macOS for tg, max and drive (`platforms: true`); zoom and memo still fail tests there, so theirs is off.
 - **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
@@ -206,11 +209,14 @@ no-unbounded-spread ([WC-TOOL-12](#wc-tool-12--do-not-spread-a-list-of-user-data
 ### 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`.
+- **Enforced by:** `pnpm docs:spell` · `pnpm docs:check`.
 - **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.
+  WireCat word list) and adds only the project's own words. A repository checks `README.md` and every user page,
+  `docs/*.md`, in `docs:spell` or in `docs:check`. Generated pages (`docs/commands.md`), `docs/dev/` and
+  `CHANGELOG.md` may be left out. Code blocks and inline code are not checked.
+- **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.
 
 ### WC-TOOL-18 · Lint Markdown with `markdownlint-cli2` and the shared preset

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wirecat/cli-base",
-  "version": "0.59.0",
+  "version": "0.61.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",