@wirecat/cli-base 0.54.0 → 0.55.0

package/CHANGELOG.md

@@ -8,6 +8,36 @@ 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

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/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

@@ -30,8 +30,11 @@ A change that makes a CLI change its code for one of these exports ships with tw
 
 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 and cli-core build the template against
-   each pull request, so the template is updated in the same change, and `upgrade` has the new version to bring.
+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
 

package/docs/standards/releases.md

@@ -167,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.54.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",