@wirecat/cli-base 0.53.0 → 0.55.0

package/CHANGELOG.md

@@ -8,6 +8,47 @@ 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.55.0 — 25.10.2026
+
+### Added
+
+- **`WC-STORE-5` is checked** ([Store](docs/standards/store.md)): the shared `no-sqlite-driver` lint plugin, now in every repository's `config/wirecat/`, refuses a CLI's import of a SQLite driver or `drizzle-orm` outside tests and tooling scripts. cli-core turns it off. `WC-ARCH-21` now says it is in the handbook since 0.53.0, the first release that carried it.
+
+- **`cli-dev changelog restore --land` puts the newest release's notes back to what shipped**
+  ([releases standard](docs/standards/releases.md#wc-rel-15--fold-a-late-pending-section-into-the-unpublished-version-before-publishing)).
+  A pull request checked before a release and merged after it adds its entry to that release's section, though its
+  code ships only in the next one, and no pull request check can see it. The command compares the newest tagged
+  version's section with its text in the tag; when they differ, it restores the tag's text and moves each entry the
+  tag lacks to the unreleased section, through a `chore(release): restore …` pull request. A CLI runs it at the start
+  of `bin/release`, before the fold, so the entry lands in the version that ships it. Older sections are not
+  compared.
+
+### Changed — may break callers
+
+- **The changelog guard fails a pull request that adds a line to a dated section with no tag yet**
+  ([a released section is frozen](docs/standards/docs.md#wc-doc-20--a-released-section-is-frozen-and-a-new-entry-goes-under-an-existing-heading)),
+  unless its title has the `release` or `changelog` scope. Between the release pull request and the tag, a rebase onto
+  main puts a branch's new entries under the dated heading with no conflict, and when the release already runs
+  without that branch the note ships under the wrong version. Put the entry under the unreleased heading:
+  `bin/release` folds it into the dated version if it still publishes that commit (`chore(release): fold …`). A
+  repository picks this up when it moves its `changelog-guard.yml` pin to this version.
+
+### Fixed
+
+- **The kit surface page links the two cli-template jobs** (cli-base's `template.yml`, cli-core's `parity.yml`), and
+  the roadmap no longer lists "a new CLI from a template" as next: it is `npx @wirecat/cli-template new`.
+
+## 0.54.0 — 25.10.2026
+
+### Added
+
+- **A Kit surface page in the standards** ([Kit surface](docs/standards/kit-surface.md)) lists the cli-base and cli-core exports that `@wirecat/cli-template` is built on. A change that makes a CLI change its code for one of them ships with a migration note here and with the template already updated, so `npx @wirecat/cli-template upgrade` brings it. Nothing changes in code.
+- **The New CLI page starts with `npx @wirecat/cli-template new`** ([New CLI](docs/standards/new-cli.md)). It gives the command with every flag, the four steps that still need a person, and the same "Done when" checks. A CLI started by hand still passes the same checks.
+
+### Changed — may break callers
+
+- **The release lock is one per package, not one per machine** (`WC-REL-3`, [Releases](docs/standards/releases.md)). Two releases of the same package still never run at once on one machine, from any checkout or worktree; releases of different packages now run side by side. The lock is `leemour-release-<package>.lock`, named from `package.json`, so a `package.json` without a name refuses the release. A CLI picks this up by re-running community's `adopt-standards.py --only release-lock`; until then it keeps the old shared lock.
+
 ## 0.53.0 — 25.10.2026
 
 ### Added

package/config/wirecat/biome.base.json

@@ -120,6 +120,23 @@
         "!**/fixtures/**"
       ]
     },
+    {
+      "path": "./config/wirecat/no-sqlite-driver.grit",
+      "includes": [
+        "**",
+        "!**/*.test.*",
+        "!**/*.spec.*",
+        "!**/test/**",
+        "!**/tests/**",
+        "!**/__tests__/**",
+        "!**/fixtures/**",
+        "!**/testing/**",
+        "!**/scripts/**",
+        "!**/bench/**",
+        "!**/performance/**",
+        "!**/contracts/**"
+      ]
+    },
     {
       "path": "./config/wirecat/no-unbounded-spread.grit",
       "includes": [

package/config/wirecat/manifest.json

@@ -2,7 +2,7 @@
   "source": "https://github.com/WireCatLabs/community",
   "revision": "b22b7ede5931a4058fc763e0a7d6bfe0fbdb87c8",
   "files": {
-    "biome.base.json": "5d265b71896cdb0454260fa8d897bd517f61de512f16831e5d5273f29775f9f3",
+    "biome.base.json": "63760337a2e68522ad75e0ba163635785a01ec34dbd3cf338a09a4145932cf2a",
     "cspell.json": "8241122ed4d461976a838099b265ef8f2689a066608257b6fdc250d9b49b58aa",
     "lefthook.yml": "2f65a2e3103006d43f6d6f0a07ab333c132286157763222a59a5a22676acd391",
     "markdownlint.json": "5ed7d6980054c539f3f3c0e47a090f1a725b15be2c486a769a836bc6cd48ad2d",
@@ -12,9 +12,10 @@
     "no-shell-true.grit": "d3943cfa1d7ebbf7be0fa22c2aaf2b7d7aa9ff462f2eb14a7798632764e3875c",
     "no-unbounded-spread.grit": "f4178e5b74212fef58fec8916b6783d9f4f192ac618aa4ced041c4167bfbf81b",
     "release-lock-info.mjs": "4abab1f01ceee7d4c709222e923c9a6fc634bcf7b8b64d745a9ac495993310e0",
-    "release-lock.sh": "f3309e569daea423c35f2a7b51cd55aec24c28160428b67ee2ece05e67fab877",
+    "release-lock.sh": "bef364092c4ab595f3b9b4130e23570c8306223228cdfa3e9384230f3b7f4a49",
     "rumdl.toml": "048b929176f13234324f5825d1e811397f1491b9cb6684a1953e268e2c2ed863",
-    "check.mjs": "34b266411eaab7707030915f645308e86784b1574b21fa44ca974861a90c9ce1"
+    "check.mjs": "34b266411eaab7707030915f645308e86784b1574b21fa44ca974861a90c9ce1",
+    "no-sqlite-driver.grit": "19e1f510a88ddd9df44d6db43c1c9b603c3e5bbec03a3f65305b72eac7f09389"
   },
   "packageManager": "pnpm@11.20.0",
   "node": ">=22",
@@ -26,5 +27,11 @@
     "cspell": "10.3.6",
     "lefthook": "2.1.16",
     "markdownlint-cli2": "0.23.3"
+  },
+  "fileRevisions": {
+    "release-lock.sh": "49e630a99d758e3e113749bef2049b258c7262e3",
+    "release-lock-info.mjs": "49e630a99d758e3e113749bef2049b258c7262e3",
+    "biome.base.json": "06c612c609d870f0ba00010612e0413f65340408",
+    "no-sqlite-driver.grit": "06c612c609d870f0ba00010612e0413f65340408"
   }
 }

package/config/wirecat/no-sqlite-driver.grit

@@ -0,0 +1,15 @@
+language js
+
+or {
+  `import $_ from $source`,
+  `import $source`,
+  `export { $_ } from $source`,
+  `export * from $source`,
+  `export * as $_ from $source`,
+  `export type { $_ } from $source`,
+  `import($source)`,
+  `require($source)`
+} where {
+  $source <: r"^[\"'`](?:node:sqlite|bun:sqlite|better-sqlite3|drizzle-orm)(?:/.*)?[\"'`]$",
+  register_diagnostic(span=$source, message="The shared store belongs to cli-core (WC-STORE-5): a CLI opens no SQLite driver and writes no SQL against it. Ask cli-core for a store method.", severity="error")
+}

package/config/wirecat/release-lock.sh

@@ -8,7 +8,16 @@ wirecat_release_lock() {
     echo "release locking requires flock" >&2
     return 1
   }
-  _wirecat_release_lock="${XDG_RUNTIME_DIR:-/tmp}/leemour-release.lock"
+  # Keyed by package name, not folder: one package releases from several checkouts and worktrees.
+  _wirecat_release_key=$(node -e '
+    const { name } = JSON.parse(require("node:fs").readFileSync("package.json", "utf8"))
+    if (typeof name !== "string" || !name) throw Error("package.json has no name")
+    process.stdout.write(name.replace(/^@/, "").replace(/[^A-Za-z0-9._-]+/g, "-"))
+  ' 2>/dev/null) && [ -n "$_wirecat_release_key" ] || {
+    echo "release locking needs a package name in ./package.json" >&2
+    return 1
+  }
+  _wirecat_release_lock="${XDG_RUNTIME_DIR:-/tmp}/leemour-release-$_wirecat_release_key.lock"
   exec 9>>"$_wirecat_release_lock"
   if flock -E 75 -w "$_wirecat_release_wait" 9; then
     printf '%s pid %s since %s\n' "$(basename "$PWD")" "$$" "$(date -u +%Y-%m-%dT%H:%M:%SZ)" > "$_wirecat_release_lock.who"

package/dist/dev/land.d.ts

@@ -13,6 +13,8 @@ export type Change = {
     line: string;
 };
 export declare const changelogChange: (text: string, version: string, unreleased: string) => Change | undefined;
+/** Moves the entries that missed the newest tagged version to the unreleased section; see `restoreReleased`. */
+export declare const restoreChange: (text: string, tagText: string, version: string, unreleased: string) => Change | undefined;
 export interface LandOptions {
     file: string;
     version: string;
@@ -20,10 +22,27 @@ export interface LandOptions {
     shell: Shell;
     log: (text: string) => void;
 }
+/** Lands the changelog fold on `main` through a pull request; see `landChange`. */
+export declare const landFold: ({ file, version, unreleased, shell, log }: LandOptions) => string | undefined;
 /**
- * Lands the changelog fold on `main` through a pull request. Each attempt folds on a fresh
- * `origin/main`; a pull request that main has since moved under (another session folded first, or
- * merged a change to CHANGELOG.md) is closed and the fold redone once. Returns the line to print, or
- * `undefined` when there was nothing to fold. Throws when it cannot land.
+ * Lands a changelog change on `main` through a pull request. Each attempt computes it on a fresh
+ * `origin/main`; a pull request that main has since moved under (another session landed first, or
+ * merged a change to CHANGELOG.md) is closed and the change redone once. Returns the line to print, or
+ * `undefined` when there was nothing to change. Throws when it cannot land.
  */
-export declare const landFold: ({ file, version, unreleased, shell, log }: LandOptions) => string | undefined;
+export declare const landChange: ({ file, branch, change: changeOf, done, shell, log, }: {
+    file: string;
+    branch: string;
+    change: (text: string) => Change | undefined;
+    done: string;
+    shell: Shell;
+    log: (text: string) => void;
+}) => string | undefined;
+/**
+ * The newest `v<x.y.z>` tag in this commit's history and the changelog at it. Tags are fetched first: a clone made before the
+ * last release does not have its tag, and comparing against an older one would hide the newest drift.
+ */
+export declare const newestTag: (shell: Shell, path: string) => {
+    version: string;
+    text: string;
+};

package/dist/dev/land.js

@@ -1,6 +1,6 @@
 import { readFileSync, writeFileSync } from "node:fs";
 import spawn from "cross-spawn";
-import { foldUnreleased, mergeRepeatedHeadings } from "../release/index.js";
+import { foldUnreleased, mergeRepeatedHeadings, restoreReleased } from "../release/index.js";
 export const processShell = (cwd) => ({
     run: (command, args) => {
         const result = spawn.sync(command, [...args], { cwd, encoding: "utf8" });
@@ -28,14 +28,41 @@ export const changelogChange = (text, version, unreleased) => {
         line: `merged repeated headings in ${version}`,
     };
 };
+/** Moves the entries that missed the newest tagged version to the unreleased section; see `restoreReleased`. */
+export const restoreChange = (text, tagText, version, unreleased) => {
+    const restored = restoreReleased(text, tagText, version, unreleased);
+    if (!restored)
+        return undefined;
+    const moved = restored.moved.map((entry) => `\n${entry}`).join("");
+    return {
+        text: restored.text,
+        title: `chore(release): restore ${version}'s notes to its tag`,
+        body: `bin/release: CHANGELOG.md's ${version} section differed from the v${version} tag. It now matches the tag` +
+            (moved
+                ? `, and ${restored.moved.length} entr${restored.moved.length === 1 ? "y" : "ies"} that missed ${version} ` +
+                    `moved to ${unreleased}:${moved}`
+                : ".") +
+            "\nOnly CHANGELOG.md changes.",
+        line: `restored ${version}'s notes to its tag${moved ? `; moved to ${unreleased}:${moved}` : ""}`,
+    };
+};
 const ATTEMPTS = 2;
+/** Lands the changelog fold on `main` through a pull request; see `landChange`. */
+export const landFold = ({ file, version, unreleased, shell, log }) => landChange({
+    file,
+    branch: `release/fold-${version}`,
+    change: (text) => changelogChange(text, version, unreleased),
+    done: `main already has ${version}'s changelog folded`,
+    shell,
+    log,
+});
 /**
- * Lands the changelog fold on `main` through a pull request. Each attempt folds on a fresh
- * `origin/main`; a pull request that main has since moved under (another session folded first, or
- * merged a change to CHANGELOG.md) is closed and the fold redone once. Returns the line to print, or
- * `undefined` when there was nothing to fold. Throws when it cannot land.
+ * Lands a changelog change on `main` through a pull request. Each attempt computes it on a fresh
+ * `origin/main`; a pull request that main has since moved under (another session landed first, or
+ * merged a change to CHANGELOG.md) is closed and the change redone once. Returns the line to print, or
+ * `undefined` when there was nothing to change. Throws when it cannot land.
  */
-export const landFold = ({ file, version, unreleased, shell, log }) => {
+export const landChange = ({ file, branch, change: changeOf, done, shell, log, }) => {
     const must = (command, ...args) => {
         const result = shell.run(command, args);
         if (!result.ok)
@@ -51,7 +78,6 @@ export const landFold = ({ file, version, unreleased, shell, log }) => {
         }
         return "UNKNOWN";
     };
-    const branch = `release/fold-${version}`;
     const abandon = (pr) => {
         log(`${pr} no longer merges into main — closing it and folding again on the new main`);
         must("gh", "pr", "close", pr, "--delete-branch");
@@ -60,10 +86,10 @@ export const landFold = ({ file, version, unreleased, shell, log }) => {
     for (let attempt = 1; attempt <= ATTEMPTS; attempt++) {
         must("git", "fetch", "-q", "origin");
         must("git", "merge", "-q", "--ff-only", "origin/main");
-        const change = changelogChange(readFileSync(file, "utf8"), version, unreleased);
+        const change = changeOf(readFileSync(file, "utf8"));
         if (!change) {
             if (attempt > 1)
-                log(`main already has ${version}'s changelog folded — nothing to land`);
+                log(`${done} — nothing to land`);
             return undefined;
         }
         writeFileSync(file, change.text);
@@ -95,5 +121,29 @@ export const landFold = ({ file, version, unreleased, shell, log }) => {
         must("git", "merge", "-q", "--ff-only", "origin/main");
         return `${change.line} (${pr})`;
     }
-    throw new Error(`main moved under the fold twice — run bin/release again`);
+    throw new Error(`main moved under ${branch} twice — run bin/release again`);
+};
+/**
+ * The newest `v<x.y.z>` tag in this commit's history and the changelog at it. Tags are fetched first: a clone made before the
+ * last release does not have its tag, and comparing against an older one would hide the newest drift.
+ */
+export const newestTag = (shell, path) => {
+    const fetched = shell.run("git", ["fetch", "-q", "--tags", "origin"]);
+    if (!fetched.ok)
+        throw new Error(`git fetch --tags failed: ${fetched.out}`);
+    const [version] = shell
+        .run("git", ["tag", "--list", "v*", "--merged", "HEAD"])
+        .out.split("\n")
+        .map((tag) => /^v(\d+\.\d+\.\d+)$/.exec(tag.trim())?.[1])
+        .filter((found) => found !== undefined)
+        .sort((a, b) => {
+        const [x, y] = [a, b].map((found) => found.split(".").map(Number));
+        return (y?.[0] ?? 0) - (x?.[0] ?? 0) || (y?.[1] ?? 0) - (x?.[1] ?? 0) || (y?.[2] ?? 0) - (x?.[2] ?? 0);
+    });
+    if (!version)
+        throw new Error("no v<x.y.z> tag to compare the changelog with");
+    const shown = shell.run("git", ["show", `v${version}:${path}`]);
+    if (!shown.ok)
+        throw new Error(`git show v${version}:${path} failed: ${shown.out}`);
+    return { version, text: shown.out };
 };

package/dist/dev/main.js

@@ -4,7 +4,7 @@
  */
 import { randomUUID } from "node:crypto";
 import { existsSync, mkdirSync, readdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
-import { isAbsolute, join } from "node:path";
+import { isAbsolute, join, relative } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import spawn from "cross-spawn";
@@ -18,7 +18,7 @@ import { issuesOf, RegistryError } from "../standards/registry.js";
 import { VOCABULARY } from "../standards/vocabulary.js";
 import { auditClis, scorecardTable, snakeKeys } from "./audit.js";
 import { readCapabilities } from "./capabilities.js";
-import { changelogChange, landFold, processShell } from "./land.js";
+import { changelogChange, landChange, landFold, newestTag, processShell, restoreChange } from "./land.js";
 import { baselineOf, judge, lintCommands } from "./lint.js";
 import { nextVersion } from "./next-version.js";
 import { slowTests } from "./slow-tests.js";
@@ -36,6 +36,11 @@ const USAGE = `usage: cli-dev <command> [options]
                                        it changed the file, nothing otherwise. --land lands it on main
                                        through a pull request, folding again on the new main once if
                                        main moved under it. Run it only while that version is not on npm
+  changelog restore [--unreleased <title>] [--file <path>] [--land]
+                                       puts the newest tagged version's section back to its text in
+                                       the tag; an entry the tag lacks missed that release and moves
+                                       to the unreleased section. Prints a line when it changed the
+                                       file. --land lands it on main through a pull request
   docs-check [--rules <module>] [--ids <A,B>] [--pages]
                                        links, anchors and the changelog's shape; --pages also
                                        docs/ against docs/meta.json, the docs portal's structure
@@ -100,8 +105,8 @@ const docsCheck = async (args, io) => {
 };
 const changelog = (args, io) => {
     const [action, ...rest] = args;
-    if (action !== "fold") {
-        io.err(`cli-dev changelog: no action "${action ?? ""}" — the one there is: fold`);
+    if (action !== "fold" && action !== "restore") {
+        io.err(`cli-dev changelog: no action "${action ?? ""}" — the ones there are: fold, restore`);
         return 2;
     }
     const { values } = parseArgs({
@@ -114,8 +119,32 @@ const changelog = (args, io) => {
         },
     });
     const file = isAbsolute(values.file) ? values.file : join(io.cwd, values.file);
-    const version = values.version ?? packageVersion(io.cwd);
     try {
+        if (action === "restore") {
+            const shell = processShell(io.cwd);
+            const tag = newestTag(shell, relative(io.cwd, file));
+            const change = (text) => restoreChange(text, tag.text, tag.version, values.unreleased);
+            if (values.land) {
+                const landed = landChange({
+                    file,
+                    branch: `release/restore-${tag.version}`,
+                    change,
+                    done: `main already has ${tag.version}'s notes as tagged`,
+                    shell,
+                    log: io.err,
+                });
+                if (landed)
+                    io.out(landed);
+                return 0;
+            }
+            const restored = change(readFileSync(file, "utf8"));
+            if (!restored)
+                return 0;
+            writeFileSync(file, restored.text);
+            io.out(restored.line);
+            return 0;
+        }
+        const version = values.version ?? packageVersion(io.cwd);
         if (values.land) {
             const landed = landFold({
                 file,

package/dist/release/fold.d.ts

@@ -13,3 +13,14 @@ export declare const foldUnreleased: (text: string, version: string, unreleased?
  * when no heading repeats there. The caller makes sure the version is not on npm.
  */
 export declare const mergeRepeatedHeadings: (text: string, version: string) => string | undefined;
+/**
+ * Puts the section of `version`, the newest tagged one, back to its text in that tag. A pull request
+ * checked before the version was dated or tagged and merged after it adds its entry there with no
+ * guard to see it, though that code ships only in the next version: each such entry moves to the unreleased
+ * section, after its entries under the same `###` heading. `undefined` when the section matches the tag the
+ * way the changelog guard compares them.
+ */
+export declare const restoreReleased: (text: string, tagText: string, version: string, unreleased?: string) => {
+    text: string;
+    moved: string[];
+} | undefined;

package/dist/release/fold.js

@@ -66,3 +66,56 @@ export const mergeRepeatedHeadings = (text, version) => {
         return undefined;
     return [preamble, render(section.title, [section]), ...rest].join("\n");
 };
+const body = (block) => block
+    .split("\n")
+    .slice(1)
+    .map((line) => line.trimEnd())
+    .join("\n")
+    .trim();
+const entries = (section) => [...section.headings].flatMap(([heading, lines]) => {
+    const found = [];
+    for (const line of lines) {
+        if (!line.trim())
+            continue;
+        const last = found.at(-1);
+        if (line.startsWith("- ") || !last)
+            found.push({ heading, text: line });
+        else
+            last.text += `\n${line}`;
+    }
+    return found;
+});
+/**
+ * Puts the section of `version`, the newest tagged one, back to its text in that tag. A pull request
+ * checked before the version was dated or tagged and merged after it adds its entry there with no
+ * guard to see it, though that code ships only in the next version: each such entry moves to the unreleased
+ * section, after its entries under the same `###` heading. `undefined` when the section matches the tag the
+ * way the changelog guard compares them.
+ */
+export const restoreReleased = (text, tagText, version, unreleased = "Unreleased") => {
+    const dated = (block) => block.startsWith(`## ${version} — `);
+    const tagged = tagText.split(/\n(?=## )/).find(dated);
+    if (!tagged)
+        throw new Error(`the v${version} tag's changelog has no "## ${version} — " section`);
+    const blocks = text.split(/\n(?=## )/);
+    const index = blocks.findIndex(dated);
+    if (index < 0)
+        throw new Error(`no "## ${version} — " section to compare with the v${version} tag`);
+    const current = blocks[index] ?? "";
+    if (current.split("\n")[0]?.trimEnd() === tagged.split("\n")[0]?.trimEnd() && body(current) === body(tagged))
+        return undefined;
+    const shipped = new Set(entries(parseSection(tagged)).map((entry) => entry.text));
+    const missed = entries(parseSection(current)).filter((entry) => !shipped.has(entry.text));
+    blocks[index] = tagged.replace(/\n+$/, current.endsWith("\n") ? "\n" : "");
+    if (missed.length > 0) {
+        const headings = new Map();
+        for (const { heading, text: entry } of missed)
+            headings.set(heading, [...(headings.get(heading) ?? []), entry]);
+        const moved = { title: "", headings, repeated: false };
+        const top = blocks[1];
+        const open = top === `## ${unreleased}` || top?.startsWith(`## ${unreleased}\n`);
+        const section = render(`## ${unreleased}`, open && top ? [parseSection(top), moved] : [moved]);
+        blocks.splice(1, open ? 1 : 0, section);
+    }
+    return { text: blocks.join("\n"), moved: missed.map((entry) => entry.text.split("\n")[0] ?? "") };
+};

package/dist/release/index.d.ts

@@ -1,4 +1,4 @@
-export { foldUnreleased, mergeRepeatedHeadings } from "./fold.js";
+export { foldUnreleased, mergeRepeatedHeadings, restoreReleased } from "./fold.js";
 export { type ChangelogRules, changelogProblems, type DocsRules, docsProblems, idPattern, JOURNAL_IDS, markdownFiles, slug, } from "./markdown.js";
 export { REQUIRED_PAGES, type StructureRules, structureProblems } from "./structure.js";
 export type Check = {

package/dist/release/index.js

@@ -6,7 +6,7 @@
 import { spawnSync } from "node:child_process";
 import { readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
-export { foldUnreleased, mergeRepeatedHeadings } from "./fold.js";
+export { foldUnreleased, mergeRepeatedHeadings, restoreReleased } from "./fold.js";
 export { changelogProblems, docsProblems, idPattern, JOURNAL_IDS, markdownFiles, slug, } from "./markdown.js";
 export { REQUIRED_PAGES, structureProblems } from "./structure.js";
 /**

package/docs/standards/README.md

@@ -9,8 +9,8 @@ It ships in the `@wirecat/cli-base` package. A CLI that depends on cli-base has
 
 ## How to use this for a new CLI
 
-Start with the [New CLI](new-cli.md) checklist. Each step names the check that proves it and the area page whose
-rules it keeps. A new CLI is ready for its first release when every check under "Done when" passes.
+Start with the [New CLI](new-cli.md) page: `npx @wirecat/cli-template new` makes the repository, and the page lists
+the four steps that need a person. A new CLI is ready for its first release when every check under "Done when" passes.
 
 ## Which rule wins
 
@@ -44,7 +44,8 @@ rules it keeps. A new CLI is ready for its first release when every check under
 | [CI](ci.md) | `CI` | 12 | Hooks, the pull request budget, full validation, monthly runs |
 | [Time](time.md) | `TIME` | 6 | UTC in the store and in answers, the zone at input and display edges, date-only filters, tests in another zone |
 | [Style](style.md) | `STYLE` | 10 | Comments, TypeScript habits, commit messages |
-| [New CLI](new-cli.md) | — | — | The checklist for starting a new CLI |
+| [New CLI](new-cli.md) | — | — | Starting a new CLI from the template: the command, the four manual steps, the checks |
+| [Kit surface](kit-surface.md) | — | — | The cli-base and cli-core exports the template is built on, and how a change to one reaches you |
 
 Each count leaves out the ids that moved or merged (see "How ids work").
 

package/docs/standards/architecture.md

@@ -219,7 +219,7 @@ out of search and listed under `skipped`, with the hint to run that CLI once.
   `skipped` instead of reading their rows as messages.
 - **Exceptions:** the built-in providers of cli-core need no entry. Two entries that disagree on a kind are an error
   naming both.
-- **Applies to:** cli-core and every CLI with a provider of its own. **Since:** cli-base 0.53.1. **Rulings:** none
+- **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).
 
 ## Sources

package/docs/standards/docs.md

@@ -198,7 +198,11 @@ Rule ids on this page are `WC-DOC-<n>`. How to read a rule, how ids work and whi
 - **Enforced by:** `changelog-guard.yml`.
 - **Example:** the guard fails a change to a section whose `v<version>` tag exists, unless the change restores the
   exact text in that tag. It also fails a new repeated `###` heading in any section that has no tag yet.
-- **Exceptions:** a dated section with no tag is still open to fixes; a release is tagged only after npm has it.
+  A pull request whose title has no `release` or `changelog` scope also fails when it adds a line to a dated section
+  the base already had: a rebase onto a just-dated release moves its new entries there with no conflict.
+- **Exceptions:** a dated section with no tag is still open to fixes from a title with the `release` or `changelog`
+  scope (`chore(release): fold …`, `docs(changelog): …`); a release is tagged only after npm has it.
+  Sections that already differed from their tag on 25.10.2026 stay as they are, and nothing reports them.
 - **Applies to:** every repository that calls the changelog guard. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ## Sources

package/docs/standards/kit-surface.md

@@ -0,0 +1,53 @@
+# Kit surface
+
+## Scope
+
+These are the parts of cli-core and cli-base that the template is built on. A CLI started with
+`npx @wirecat/cli-template new` imports them from its first commit. When one of them changes in a way your code must
+follow, the changelog gives the steps, and the template is already updated, so `npx @wirecat/cli-template upgrade`
+brings the change into your CLI.
+
+This page is a reference, not a rule page: it assigns no rule ids. How to start a CLI from the template is on the
+[New CLI](new-cli.md) page. How a release is made is on the [Releases](releases.md) page.
+
+## What the template imports
+
+The list is what the template's `src/` imports today, type imports included.
+
+| 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`, `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` |
+
+## When one of them changes
+
+A change that makes a CLI change its code for one of these exports ships with two things:
+
+1. **A migration note in the changelog**, under "Changed — may break callers": what to change in your code, step by
+   step. See [Documents](docs.md) for the changelog's shape.
+2. **A green cli-template job before the pull request merges.** cli-base
+   ([`template.yml`](https://github.com/WireCatLabs/cli-base/blob/main/.github/workflows/template.yml)) and cli-core
+   (the `template` job in [`parity.yml`](https://github.com/WireCatLabs/cli-core/blob/main/.github/workflows/parity.yml))
+   build the template against each pull request, so the template is updated in the same change, and `upgrade` has
+   the new version to bring.
+
+## How your CLI stays current
+
+- **Exact versions.** The template depends on `@wirecat/cli-base` and `@wirecat/cli-core` at exact versions, the
+  normal setup for every WireCat CLI. A CLI made from it starts with the same pins.
+- **Dependabot.** The template's `dependabot.yml` checks `@wirecat/*` every day and opens one pull request for the
+  shared packages within a day of a release. Its CI shows whether anything else needs to change.
+- **`upgrade`.** In your CLI, with a clean git working tree:
+
+  ```sh
+  npx @wirecat/cli-template upgrade
+  ```
+
+  For each template file that changed since your version, it asks: apply (merge the change into your file, keeping
+  your edits), replace, skip or diff. Without a terminal, `--apply`, `--replace` or `--skip` answers for every file,
+  and `--dry-run` lists what each file would get. Then re-run community's `adopt-standards.py` for `config/wirecat/`.

package/docs/standards/new-cli.md

@@ -1,100 +1,81 @@
 # New CLI
 
-<!-- cspell:ignore rumdl whatsapp -->
-
 ## Scope
 
-The steps to start a new WireCat CLI and the checks that prove each step. Every item names the check that proves
-it, or the handbook page whose rules it keeps. A new CLI is done when every check in "Done when" passes.
+How to start a new WireCat CLI: one command that copies the template, the four steps that need a person, and the
+checks that prove the result. A new CLI is done when every check in "Done when" passes.
 
 This page is a checklist, not a rule page: it assigns no rule ids. The rules are on the area pages it links. How to
-read a rule and which rule wins are in the [index](README.md).
-
-whatsapp-cli is the worked example: it has every file below. Compare with it when a step is unclear.
-
-## Start from the shared standards
-
-1. **Create the repository** under `WireCatLabs`, with a `main` branch that takes changes only through pull requests.
-   Proved by: the repository ruleset. See [Releases](releases.md).
-2. **Install the community presets.** From a reviewed checkout of
-   [WireCatLabs/community](https://github.com/WireCatLabs/community):
-
-   ```sh
-   python3 scripts/adopt-standards.py ../whatsapp-cli
-   ```
-
-   This is the command that was run for whatsapp-cli; use your new repository's folder instead.
-
-   The installer copies the Biome base, the grit plugins, cspell, markdownlint, rumdl, lefthook and the release lock
-   helper into `config/wirecat/`, pins the tool versions, records the file hashes and writes the `standards.yml`
-   workflow. Commit the result with the lockfile. Proved by: `pnpm standards:check`, run by `standards.yml`.
-3. **Copy community's `monthly.yml` template** into `.github/workflows/`, and set its cron to a day no other
-   repository uses. Proved by: the workflow appears in the Actions tab. See [CI](ci.md).
-4. **Add `pr.yml`**, the pull request validation that calls `ci.yml` with platform suites skipped, as shown in
-   [WC-CI-5](ci.md#wc-ci-5--run-the-full-linux-validation-on-every-pull-request-and-keep-platform-suites-out).
-   Proved by: the `validation` check on the first pull request.
-
-## Toolchain
-
-1. **Depend on the shared packages at exact versions.** `@wirecat/cli-base` always, at 0.41.0 or later: it is the
-   first version that ships this handbook and the `cli-dev` lint and audit that the checks below run.
-   `@wirecat/cli-core` as well when the CLI is a messenger or uses the shared store, search, MCP server or send guard.
-   What cli-core already does, the new CLI does not do again. See [Architecture](architecture.md).
-2. **Extend the shared TypeScript configuration**: `@wirecat/cli-base/tsconfig.base.json` for `src/`,
-   `tsconfig.test.json` for tests and `tsconfig.scripts.json` for `scripts/`. Every directory with `.ts` files is in a
-   project the build checks. Proved by: `pnpm typecheck`.
-3. **Extend the community Biome base** (`./config/wirecat/biome.base.json`) in the root `biome.json`, and add the
-   project rules there: the 1,000-line file cap, import cycles and the layer imports. Proved by: `pnpm lint`. See
-   [Toolchain](toolchain.md) and [Layout](layout.md).
-4. **Add `ci:quick`**: typecheck, build and `cli-dev lint`. Proved by: the pull request CI. See [CI](ci.md).
-
-## Commands every CLI has
-
-1. **The required root commands.** `cli-dev audit` checks these six paths:
-   - `commands`: the command tree as JSON, which agents and the audit read.
-   - `doctor`: checks this machine and the profile, and says what to fix. `doctor --online` logs in once, never
-     retries, sends nothing and marks nothing read (ruling NEED-288).
-   - `skill show` and `skill install`: print and install the agent skill from `skills/<cli>/SKILL.md`, which the
-     package ships. A missing or older skill is suggested on stderr at most once a day (ruling NEED-797).
-   - `mcp`: the MCP server. Its tools are generated from the commands. See [MCP](mcp.md).
-   - `upgrade`: updates the CLI.
-
-   Proved by: `cli-dev audit --for <cli>`, rule `required-root`. A CLI on cli-core gets these from cli-core.
-2. **`config`, where the CLI has settings.** cli-core provides it. It is not a required root. See
-   [Accounts](accounts.md) for the profile, which is always explicit.
-3. **Every command declares its effects and its lifetime**, and has a summary, described arguments and options, and
-   examples. Proved by: `cli-dev lint`. See [Commands](commands.md), [Output](output.md) and
-   [Lifecycle](lifecycle.md).
-4. **Every write is gated by a permission.** See [Permissions](permissions.md).
-5. **Add the CLI to the `all` parity group** in cli-base's `PARITY_GROUPS`. That group compares the shared root
-   commands. Proved by: `cli-dev audit`, rule `same-path-contract`. A messenger also joins cli-core's `parity.json`,
-   which `pnpm parity:check` reads. See [Testing](testing.md).
-
-## Files to add
-
-1. **`CLAUDE.md`** (and `AGENTS.md`, if the repository has one): a short file. It links this handbook at
-   `node_modules/@wirecat/cli-base/docs/standards/README.md`, lists the CLI's "Local rules" below that link, and says
-   where the private working folder lives. It does not restate handbook rules. See [Documents](docs.md).
-2. **`lint/baseline/`** and `lint/overrides.json`: written once with `cli-dev lint --write-baseline`. The baseline only
-   shrinks, and at most 10 overrides are allowed. Proved by: `cli-dev lint`.
-3. **The test setup**: `vitest.config.ts` with a `setupFiles` line that points configuration, state, cache and the
-   store at a temporary directory, and coverage thresholds. Proved by: `pnpm test`. See [Testing](testing.md) and
-   [Store](store.md).
-4. **`contracts/plan.json`** and its reviewed snapshots for `cli-contract` (cli-testing): help, discovery JSON, MCP
-   tools and the no-leak check. Proved by: `pnpm contracts:check`. See [Testing](testing.md).
-5. **The test matrix**: `docs/dev/test-matrix.md`, built by `cli-dev test-matrix`. Proved by:
-   `cli-dev test-matrix --check`.
-6. **The user pages**: `README.md`, `docs/meta.json` and the shared page set, with `docs/commands.md` generated from
-   the program. Proved by: `cli-dev docs-check --pages` and the CLI's `generate:check`. See [Documents](docs.md).
-7. **`CHANGELOG.md`** with `## Unreleased` at the top and the shared headings, and
-   **`.github/workflows/changelog-guard.yml`** calling cli-base's `changelog-guard.yml` at a pinned commit. Proved by:
-   `cli-dev docs-check` and the guard on the first pull request. See [Documents](docs.md).
-8. **`SECURITY.md`**: how to report a vulnerability, linking cli-testing's security method. See
-   [Security](security.md).
-9. **`bin/release`**, **`release.yml`** and a release skill, copied from the nearest CLI. `bin/release` takes the
-   release lock (WC-REL-3) and npm's trusted publisher settings name `release.yml`. A messenger CLI also checks a signed
-   release report (WC-REL-10). See [Releases](releases.md).
-10. **`src/version.ts`** kept in step with `package.json`. Proved by: `pnpm version:check`.
+read a rule and which rule wins are in the [index](README.md). The parts of cli-base and cli-core the template is
+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 \
+  --category calendar --content-lang en,ru --sign-in oauth --api official-client --filters time,person,text \
+  --never-store tokens,secret-links --untrusted names,links
+```
+
+In a terminal, `new` asks for every answer you leave out. Without a terminal, a missing answer is an error that lists
+the choices. Nothing is guessed.
+
+| Flag | What it sets | Choices |
+|---|---|---|
+| `<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` |
+| `--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` |
+| `--sign-in` | how the CLI signs in | `oauth`, `token`, `session`, `none` |
+| `--api` | what the service offers | `official-client`, `official-docs`, `unofficial` |
+| `--filters` | how people narrow a list | a list of `time`, `person`, `container`, `text`, `status` |
+| `--never-store` | what the store must never keep | a list of `tokens`, `codes`, `secret-links`, `content` |
+| `--untrusted` | what text comes from other people | a list of `messages`, `files`, `links`, `names`, or `none` |
+
+Every choice question also takes `other:<your answer>`.
+
+`new` copies the template of its own package version into `<name>-cli/`, renames the command word everywhere, runs
+`git init`, records the template version in `template.json`, writes `docs/dev/DESIGN.md` from your answers and names
+a reference CLI for your category in `AGENTS.md`. It does not install packages, push, create the repository or
+publish. Then:
+
+```sh
+cd cal-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`.
+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`,
+`skill show`, `skill install`, `mcp`, `upgrade`) and `config` from cli-core, the MCP server with a tool for every
+command, writes included, the community presets in `config/wirecat/`, the TypeScript, Biome and vitest setup,
+`contracts/`, `lint/`, the test matrix, the user pages, `CHANGELOG.md`, `SECURITY.md`, `bin/release`, and the
+`pr.yml`, `ci.yml`, `main.yml`, `standards.yml`, `changelog-guard.yml`, `monthly.yml` and `release.yml` workflows.
+The rules they keep are on the area pages: [Commands](commands.md), [MCP](mcp.md), [Accounts](accounts.md),
+[Permissions](permissions.md), [Testing](testing.md), [Documents](docs.md), [Releases](releases.md) and [CI](ci.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).
+
+## Four steps that need a person
+
+`new` prints these at the end.
+
+1. **Create the repository** under the owner, with a ruleset on the default branch: no deletion, no force push,
+   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
+   [WC-REL-11](releases.md#wc-rel-11--publish-from-github-actions-with-npm-trusted-publishing).
+3. **Pick a monthly cron day** no other repository uses. `.github/workflows/monthly.yml` holds a placeholder that CI
+   rejects. See [CI](ci.md).
+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
+   in its own repository and runs `cli-dev audit --groups <file>`. See [Testing](testing.md).
 
 ## Done when
 

package/docs/standards/releases.md

@@ -32,9 +32,10 @@ on the [CI](ci.md) page.
 - **Exceptions:** none.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 
-### WC-REL-3 · `bin/release` takes the machine release lock before it builds or publishes
+### WC-REL-3 · `bin/release` takes its package's release lock before it builds or publishes
 
-- **Why:** two sessions published at the same time on one machine; one release at a time, across every package.
+- **Why:** two sessions published the same package at the same time on one machine. Different packages do not
+  conflict, so each package has its own lock and they release side by side.
 - **Enforced by:** `<app>: bin/release`.
 - **Example:**
 
@@ -44,9 +45,12 @@ on the [CI](ci.md) page.
   ```
 
   The helper comes from the community presets (`adopt-standards.py --only release-lock`). It holds
-  `${XDG_RUNTIME_DIR:-/tmp}/leemour-release.lock` with `flock` on file descriptor 9 until the release ends.
-- **Exceptions:** none. cli-testing still opens the lock with its own `flock` line and moves to the helper.
-- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-854.
+  `${XDG_RUNTIME_DIR:-/tmp}/leemour-release-<key>.lock` with `flock` on file descriptor 9 until the release ends.
+  `<key>` is the `name` in `package.json`, made safe for a file name: `@wirecat/cli-core` locks
+  `leemour-release-wirecat-cli-core.lock`. The key is the package, not the folder, so every checkout and worktree
+  of one package shares the lock. A `package.json` without a name refuses the release.
+- **Exceptions:** none.
+- **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-854, ASK-336.
 
 ### WC-REL-4 · Never break the release lock; wait for the holder and try again
 
@@ -95,7 +99,8 @@ on the [CI](ci.md) page.
 - **Enforced by:** review only.
 - **Example:** tg-cli can release an hour after its last version, and cli-core can ship a breaking change on the same
   day as the previous one. Bump the library in every CLI that uses it on the day it ships.
-- **Exceptions:** none. The release lock (WC-REL-3) still keeps two releases on one machine from running at once.
+- **Exceptions:** none. The release lock (WC-REL-3) still keeps two releases of one package on one machine from
+  running at once.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.52.0. **Rulings:** NEED-1741.
 
 ### WC-REL-9 · Merged into [WC-REL-8](#wc-rel-8--any-package-may-release-at-any-time)
@@ -162,9 +167,13 @@ on the [CI](ci.md) page.
 - **Why:** a pull request merged after the version was dated adds a pending section above it, and that change must
   ship in the version it lands in.
 - **Enforced by:** review only.
-- **Example:** `bin/release` runs `cli-dev changelog fold --land --version <x.y.z>` while npm does not have the version.
-  It folds the pending section into the dated one, and merges any repeated `###` heading, through a pull request.
-- **Exceptions:** none.
+- **Example:** `bin/release` first runs `cli-dev changelog restore --land`. It compares the newest tagged version's
+  section with its text in the tag: a pull request checked before that release and merged after it put its entry
+  there, though its code ships only now. The section goes back to the tag's text and the entry moves to the pending
+  section, through a pull request. Then, while npm does not have the version, `bin/release` runs
+  `cli-dev changelog fold --land --version <x.y.z>`. It folds the pending section into the dated one, and merges any
+  repeated `###` heading, through a pull request.
+- **Exceptions:** only the newest tag is compared; an older section that differs from its tag stays as it is.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-REL-16 · The package ships only the files it names

package/docs/standards/store.md

@@ -69,11 +69,12 @@ Related pages: which account a read covers, and how a read across accounts is as
 ### WC-STORE-5 · A CLI writes no SQL against the shared store
 
 - **Why:** the schema belongs to cli-core; SQL in a CLI breaks on the next migration.
-- **Enforced by:** review only.
+- **Enforced by:** `<app>: biome no-sqlite-driver`.
 - **Example:** a CLI that needs a new query asks cli-core for an area method, and the method lands in cli-core with
   its test. drive and zoom state "no SQL here" in their own architecture pages.
 - **Exceptions:** a provider engine's own file of keys and device state, outside `wirecat.db`
-  ([WC-STORE-13](#wc-store-13--keep-keys-and-device-state-out-of-the-shared-store)).
+  ([WC-STORE-13](#wc-store-13--keep-keys-and-device-state-out-of-the-shared-store)). The check skips tests and tooling
+  (`scripts/`, `bench/`, `performance/`, `contracts/`, `testing/`), and cli-core, which owns the store, turns it off.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-383.
 
 ### WC-STORE-6 · One store method is one whole operation, with no `await` inside a transaction
@@ -193,8 +194,6 @@ request that builds the helper.
 - **A CLI's own tables live in its own SQLite file**, next to the shared store, with its own migrations. They refer to
   core rows by id only, and no other CLI opens that file. A cli-core helper opens it (the path, the migrations, the
   same driver); it is built when the first CLI needs private tables.
-- **WC-STORE-5 gets a check:** a grit plugin, `no-sqlite-driver`, that refuses a CLI's import of a SQLite driver or
-  of `drizzle-orm`. cli-core, which owns the store, turns it off.
 
 ## Sources
 

package/package.json

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