@wirecat/cli-base 0.65.2 → 0.65.3

package/CHANGELOG.md

@@ -8,6 +8,14 @@ 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.65.3 — 30.10.2026
+
+### Added
+
+- **A rule against per-call state in the command tree** (`WC-ARCH-22`, [Architecture](docs/standards/architecture.md)):
+  the tree is built once per process and a call's state lives in a per-call context. cli-core's `run()` still
+  rebuilds the tree per call and is the named exception until that is reworked.
+
 ## 0.65.2 — 29.10.2026
 
 ### Fixed

package/docs/standards/README.md

@@ -34,7 +34,7 @@ the four steps that need a person. A new CLI is ready for its first release when
 | [MCP](mcp.md) | `MCP` | 13 | The MCP tools, how they come from commands, what each permission shows |
 | [Accounts](accounts.md) | `ACCT` | 12 | The explicit profile, reads across accounts, scope flags, linked identities, sign-in commands |
 | [Permissions](permissions.md) | `PERM` | 22 | Levels, keys, defaults, hard limits, the write guard and its journal |
-| [Architecture](architecture.md) | `ARCH` | 17 | Layers, dependency direction, vendor types, what goes in which package |
+| [Architecture](architecture.md) | `ARCH` | 18 | Layers, dependency direction, vendor types, what goes in which package, the command tree built once |
 | [Lifecycle](lifecycle.md) | `LIFE` | 15 | Opening late, who closes, deadlines, long-running commands, the `serve` relay, resumable syncs and their request budget, the run log |
 | [Store](store.md) | `STORE` | 14 | Store areas, account scope, migrations, test isolation |
 | [Data model](data-model.md) | `DATA` | 9 | Core entities, entities and source records, `external_id`, field names, links and duplicates, files, calendar entries |

package/docs/standards/architecture.md

@@ -230,6 +230,25 @@ out of search and listed under `skipped`, with the hint to run that CLI once.
 - **Applies to:** cli-core and every CLI with a provider of its own. **Since:** cli-base 0.53.0. **Rulings:** none
   (Wave 3 requirements 3.2).
 
+### WC-ARCH-22 · Build the command tree once; keep each call's state out of it
+
+The Commander tree — commands, options, help, actions — describes the CLI and is the same for every call, so it is
+built once per process. What belongs to one call (its streams, signal, deadline, environment, profile and parsed
+options, its hooks) lives in a per-call context that the action receives, never on the `Command` objects.
+
+- **Why:** state written into a shared tree leaks into the next call. Commander restores option values to what they
+  were before the *first* parse, so a profile set on the tree before parsing becomes every later call's starting
+  value, and a hook added per call runs once more each time. Building a fresh tree per call avoids the leak but costs
+  an MCP server ~16 ms per tool call for tg.
+- **Enforced by:** review only.
+- **Example:** a check that always gives the same answer for the same definition (`defineQuery`'s examples,
+  `assertSharedContracts`) runs once per definition, not per build. A new per-call value goes into the call's context,
+  not into `setOptionValue`, `hook` or `provide` on the tree.
+- **Exceptions:** cli-core's `run()` still builds a fresh tree per call, because it writes the call's environment,
+  a `preAction` hook and the profile into it; moving that to a per-call context is
+  [CORE-41](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/BACKLOG_LATER.md). New code does not add to it.
+- **Applies to:** cli-core's command skeleton and every CLI built on it. **Since:** cli-base 0.65.3. **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/package.json

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