@wirecat/cli-base 0.59.0 → 0.60.0

package/CHANGELOG.md

@@ -8,6 +8,35 @@ 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.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/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/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/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.60.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",