@wirecat/cli-base 0.68.1 → 0.70.0

package/CHANGELOG.md

@@ -8,6 +8,45 @@ 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.70.0 — 01.11.2026
+
+### Added
+
+- **Mail words in the vocabulary: the `drafts` resource and `--cc`, `--bcc`, `--reply-all`.** mail-cli saves drafts
+  in a mailbox's Drafts folder (`mail <profile> drafts list|create|update|delete`) and addresses e-mail with copies;
+  the command lint reported each as a word it did not know.
+- **`--to` takes a chat or an e-mail address, `--subject` takes a reference or a subject line.** The owner ruled
+  that mail shares these two words with the messengers and notes instead of renaming them. `--to` is now
+  `<chat|address>`, a `string` (was an `id`); `--subject` is `<ref|text>`. The meaning per domain is in each flag's
+  text, so `flag-two-meanings` stops reporting mail's use. Mail-cli can drop its overrides for both.
+
+### Fixed
+
+- **mail is compared in its own parity group, `mail-shared`, which leaves out `search`.** mail's `search messages` is
+  cli-core's mail search, a different command from the messengers' under the same path, and `audit --complete` took
+  its twenty-odd differences as inherited. mail is compared on every other shared root, and moves back into `all`
+  once its search is aligned with the messengers' or renamed.
+
+## 0.69.0 — 01.11.2026
+
+### Added
+
+- **[Publishing](docs/PUBLISHING.md): where a CLI is published beyond npm, and how.** npm, ClawHub, the MCP Registry,
+  the Claude plugin marketplace, Hermes, Glama, GitHub and wirecat.dev: each one's setup, what a release does, how to
+  prove a publish happened (three jobs go green without publishing), the problems met with their fixes, a checklist
+  for a new CLI, and each CLI's status. `new-cli.md` points to the checklist.
+
+### Fixed
+
+- **`markdownFiles` passes over a worktree or clone inside the checkout** (a folder with its own `.git`, such as
+  `.worktrees/<topic>`). Its pages are another branch's, and their broken links failed cli-template's release check.
+  Every CLI's `docs:check` gets this through its own `docs-rules.ts`, with no change there.
+
+- **`cli-dev docs-check` reads a heading's anchor as GitHub does when it has `<…>` in code.** It dropped
+  `` `v<version>` `` as an HTML tag and wanted `tag-v-only`, where GitHub makes `tag-vversion-only`. So a working link
+  failed and a broken one passed. Two links in `architecture.md` were broken that way and are fixed. After this
+  release a CLI's `docs:check` may find links of its own that never worked on GitHub.
+
 ## 0.68.1 — 31.10.2026
 
 ### Added

package/README.md

@@ -22,6 +22,7 @@ the command tree as data — the parts every CLI needs and nobody should write t
 | [Architecture](docs/dev/ARCHITECTURE.md) | The entry points, the lines this package does not cross, who consumes what |
 | [API reference](docs/REFERENCE.md) | What each entry point holds, with examples |
 | [Shared tooling](docs/TOOLING.md) | The TypeScript, Biome, lefthook, docs and CI setup a CLI takes from here, and `cli-dev` |
+| [Publishing](docs/PUBLISHING.md) | Where a CLI is published beyond npm, how to prove it, and what has gone wrong |
 | [Testing](docs/dev/TESTING.md) | The checks, and what each one is for |
 | [Conventions](docs/dev/CONVENTIONS.md) | How code here is written |
 | [Standards handbook](docs/standards/README.md) | The rules every WireCat CLI follows, one page per area and a new-CLI checklist |

package/dist/release/markdown.d.ts

@@ -22,10 +22,16 @@ export declare const changelogProblems: (text: string, { version, release, headi
     version?: string;
     release: boolean;
 }) => string[];
-/** GitHub's heading anchor: lower case, only letters, digits, `-`, `_` and spaces kept, spaces to `-`. */
+/**
+ * GitHub's heading anchor: lower case, only letters, digits, `-`, `_` and spaces kept, spaces to `-`. An HTML tag is
+ * dropped, but `<…>` inside a code span is text: `v<version>` gives `vversion`.
+ */
 export declare const slug: (heading: string) => string;
 export declare const withoutCode: (text: string) => string;
-/** Every `.md` under `directory`, not descending into a directory named in `skip`. */
+/**
+ * Every `.md` under `directory`, not descending into a directory named in `skip`, nor into one with its own `.git`:
+ * a worktree or clone inside the checkout is another branch's files, and its broken links are not this one's.
+ */
 export declare const markdownFiles: (directory: string, skip?: ReadonlySet<string>) => string[];
 export type DocsRules = {
     /** Absolute paths; a missing one is passed over. */

package/dist/release/markdown.js

@@ -73,10 +73,15 @@ export const changelogProblems = (text, { version, release, headings, unreleased
         problems.push(`CHANGELOG.md: no section for ${version}`);
     return problems;
 };
-/** GitHub's heading anchor: lower case, only letters, digits, `-`, `_` and spaces kept, spaces to `-`. */
+/**
+ * GitHub's heading anchor: lower case, only letters, digits, `-`, `_` and spaces kept, spaces to `-`. An HTML tag is
+ * dropped, but `<…>` inside a code span is text: `v<version>` gives `vversion`.
+ */
 export const slug = (heading) => heading
     .replace(/!?\[([^\]]*)\]\([^)]*\)/g, "$1")
-    .replace(/<[^>]+>/g, "")
+    .split(/(`[^`]*`)/)
+    .map((part) => (part.startsWith("`") ? part : part.replace(/<[^>]+>/g, "")))
+    .join("")
     .toLowerCase()
     .replace(/[^\p{L}\p{M}\p{N}\-_ ]/gu, "")
     .replace(/ /g, "-");
@@ -105,7 +110,10 @@ const anchorsOf = (text) => {
         anchors.add(name);
     return anchors;
 };
-/** Every `.md` under `directory`, not descending into a directory named in `skip`. */
+/**
+ * Every `.md` under `directory`, not descending into a directory named in `skip`, nor into one with its own `.git`:
+ * a worktree or clone inside the checkout is another branch's files, and its broken links are not this one's.
+ */
 export const markdownFiles = (directory, skip = new Set()) => existsSync(directory)
     ? readdirSync(directory, { withFileTypes: true }).flatMap((entry) => {
         if (skip.has(entry.name))
@@ -115,7 +123,7 @@ export const markdownFiles = (directory, skip = new Set()) => existsSync(directo
         // like .claude/loop.md, and the directory listing still reports what lies underneath.
         const stats = statSync(path, { throwIfNoEntry: false });
         if (entry.isDirectory() && stats?.isDirectory())
-            return markdownFiles(path, skip);
+            return existsSync(join(path, ".git")) ? [] : markdownFiles(path, skip);
         return stats?.isFile() && entry.name.endsWith(".md") ? [path] : [];
     })
     : [];

package/dist/standards/audit.js

@@ -68,19 +68,35 @@ export const defineParityGroups = (input) => parseRegistry("parity groups", v.ar
             .map((entry) => `${group.name}: "${entry.target}" has \`absent\`, which measures the values itself; drop \`expected\``),
     ]),
 ]);
+const MEMO_HAS_NO_PROFILES = [
+    "mcp serve",
+    "mcp revoke",
+    "mcp server start",
+    "mcp server status",
+    "mcp server stop",
+].map((path) => ({
+    rule: "same-path-contract",
+    target: `${path} --profiles`,
+    absent: "memo",
+    reason: "memo has no profiles: it reads other CLIs' stores and selects their accounts with --source and --account " +
+        "(https://github.com/WireCatLabs/cli-base/issues/390)",
+}));
 export const PARITY_GROUPS = defineParityGroups([
     { name: "messengers", members: ["tg", "max"], covers: "tree", differences: [] },
     {
         name: "all",
-        members: ["tg", "max", "memo", "drive", "zm", "wa", "mail"],
+        members: ["tg", "max", "memo", "drive", "zm", "wa"],
         covers: ["commands", "doctor", "skill", "mcp", "upgrade", "search", "notes", "meetings"],
-        differences: ["mcp serve", "mcp revoke", "mcp server start", "mcp server status", "mcp server stop"].map((path) => ({
-            rule: "same-path-contract",
-            target: `${path} --profiles`,
-            absent: "memo",
-            reason: "memo has no profiles: it reads other CLIs' stores and selects their accounts with --source and --account " +
-                "(https://github.com/WireCatLabs/cli-base/issues/390)",
-        })),
+        differences: MEMO_HAS_NO_PROFILES,
+    },
+    // mail's `search messages` is cli-core's mail search, not the messengers' command: --complete took their 20-odd
+    // differences as inherited (https://github.com/WireCatLabs/cli-base/issues/390). mail is compared everywhere else
+    // and moves back into "all" once its search is aligned with the messengers' or renamed.
+    {
+        name: "mail-shared",
+        members: ["tg", "max", "memo", "drive", "zm", "wa", "mail"],
+        covers: ["commands", "doctor", "skill", "mcp", "upgrade", "notes", "meetings"],
+        differences: MEMO_HAS_NO_PROFILES,
     },
     // gcal is compared on what it already shares with every CLI; doctor, mcp, search and skill wait until the published
     // CLIs agree there (https://github.com/WireCatLabs/cli-base/issues/390), then gcal moves back into "all".

package/dist/standards/flags-mail.d.ts

@@ -0,0 +1,2 @@
+import type { VocabularyFlag } from "./vocabulary.js";
+export declare const MAIL_FLAGS: VocabularyFlag[];

package/dist/standards/flags-mail.js

@@ -0,0 +1,22 @@
+export const MAIL_FLAGS = [
+    {
+        name: "--cc",
+        value: "<address>",
+        role: "value",
+        type: "string",
+        meaning: "an e-mail address that gets a copy; repeat it for more",
+    },
+    {
+        name: "--bcc",
+        value: "<address>",
+        role: "value",
+        type: "string",
+        meaning: "an e-mail address that gets a blind copy; repeat it for more",
+    },
+    {
+        name: "--reply-all",
+        role: "value",
+        type: "switch",
+        meaning: "with --reply-to, an e-mail reply also goes to everyone the message went to",
+    },
+];

package/dist/standards/flags-what.js

@@ -442,7 +442,13 @@ export const WHAT_FLAGS = [
         meaning: "keep a token an operation returns only in this bot profile's keyring; never print it",
     },
     { name: "--task", value: "<id>", role: "target", type: "id", meaning: "a task, by id" },
-    { name: "--to", value: "<chat>", role: "target", type: "id", meaning: "the chat it goes to" },
+    {
+        name: "--to",
+        value: "<chat|address>",
+        role: "target",
+        type: "string",
+        meaning: "who it goes to: a chat in a messenger, an e-mail address in mail; repeat it for more addresses",
+    },
     {
         name: "--topic-name",
         value: "<name>",
@@ -889,10 +895,10 @@ export const WHAT_FLAGS = [
     { name: "--sticker", value: "<id>", role: "value", type: "id", meaning: "send this sticker, alone" },
     {
         name: "--subject",
-        value: "<ref>",
+        value: "<ref|text>",
         role: "value",
         type: "string",
-        meaning: "what it is about, as a reference",
+        meaning: "what it is about: a reference in a note or task, the subject line in mail",
         replaces: ["--about"],
     },
     {

package/dist/standards/vocabulary.js

@@ -1,6 +1,7 @@
 import * as v from "valibot";
 import { CALENDAR_FLAGS } from "./flags-calendar.js";
 import { HOW_FLAGS } from "./flags-how.js";
+import { MAIL_FLAGS } from "./flags-mail.js";
 import { WHAT_FLAGS } from "./flags-what.js";
 import { duplicates, parseRegistry, text, word } from "./registry.js";
 export const FLAG_TYPES = [
@@ -212,6 +213,7 @@ const collections = [
     ["chats", "conversations in a messenger"],
     ["contacts", "identities in a messenger's contact list"],
     ["messages", "posts in a messenger chat, or emails"],
+    ["drafts", "e-mails saved in a mailbox's Drafts folder, written and not sent"],
     ["polls", "polls in a chat"],
     ["reactions", "reactions to a message"],
     ["recipients", "who a message goes to"],
@@ -359,5 +361,5 @@ export const VOCABULARY = defineVocabulary({
     ],
     views: views.map(([entry, meaning]) => ({ word: entry, meaning })),
     roots: roots.map(([entry, meaning]) => ({ word: entry, meaning })),
-    flags: [...HOW_FLAGS, ...WHAT_FLAGS, ...CALENDAR_FLAGS],
+    flags: [...HOW_FLAGS, ...WHAT_FLAGS, ...CALENDAR_FLAGS, ...MAIL_FLAGS],
 });

package/docs/standards/architecture.md

@@ -121,7 +121,7 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
 - **Example:** in cli-core, `src/tasks/` and `src/meetings/` are entered only through their `index.ts`, `cli/`, `mcp/`
   and `testing/` entries; its `biome.json` refuses the rest. Every repository refuses `@wirecat/<package>/src/…` and `/dist/…` outside tests. A
   package's own entry points are its `exports`
-  ([WC-LAY-5](layout.md#wc-lay-5--add-an-entry-point-as-an-exports-entry-built-from-srcindexts)).
+  ([WC-LAY-5](layout.md#wc-lay-5--add-an-entry-point-as-an-exports-entry-built-from-srcnameindexts)).
 - **Exceptions:** a test inside a module may import what it tests; a test outside the module uses the entry point.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0.
   **Rulings:** none.
@@ -208,7 +208,7 @@ at start-up and the `serve` relay are in [Lifecycle](lifecycle.md); the store's
 - **Why:** a CLI that only speaks a socket must not depend on an HTTP stack.
 - **Enforced by:** review only.
 - **Example:** a helper that reads a status code or a header goes to `@wirecat/cli-base/http`. How an entry point
-  is added is [WC-LAY-5](layout.md#wc-lay-5--add-an-entry-point-as-an-exports-entry-built-from-srcindexts).
+  is added is [WC-LAY-5](layout.md#wc-lay-5--add-an-entry-point-as-an-exports-entry-built-from-srcnameindexts).
 - **Exceptions:** none.
 - **Applies to:** cli-base. **Since:** cli-base 0.41.0. **Rulings:** NEED-15.
 

package/docs/standards/commands.md

@@ -124,10 +124,10 @@ catalogue and parity manifest stay in cli-core
   `--max-output-bytes` the size of the answer. A budget changes how far the command gets, never which items one page
   of the answer holds. A retry after `outcome_unknown` is `--operation-id`: the attempt in the send journal. The
   calendar vocabulary's `--id <id>` is a different value: the provider's own id for a thing being created, chosen
-  before the create, so a retry finds it at the provider. A CLI whose provider takes such an id may offer both.
-- **Exceptions:** generated commands (`bot api`) are exempt from the naming rules. Known gap, as of 2026-10-27: gcal's
-  `events create` offers `--id` and no `--operation-id`, so its `outcome_unknown` names the event id instead of an
-  `operation_id` (WC-LIFE-9, WC-OUT-10).
+  before the create, so a retry finds it at the provider. A CLI whose provider takes such an id may offer both. gcal
+  offers only `--operation-id` (from gcal 0.9.0): its `operation_id` is also the event's id at Google, so one value
+  serves both.
+- **Exceptions:** generated commands (`bot api`) are exempt from the naming rules.
 - **Applies to:** all CLIs. **Since:** cli-base 0.41.0. **Rulings:** none.
 
 ### WC-CMD-11 · Name an option in plain words, with the kind of value in the name

package/docs/standards/lifecycle.md

@@ -210,8 +210,8 @@ before its deadline.
 - **Example:** `progressOf` from `@wirecat/cli-core/background` builds
   `{ job, profile, done, total, remaining, state, updated_at, cursor_age_ms }`, and `progressLine` prints it on one
   line in text. `state` is `partial` or `complete`; `total` and `remaining` are `null` when the source does not say how
-  much there is. memo's `mail status` answers with it, and the messenger CLIs' `store jobs show` answers with it as
-  `progress`.
+  much there is. The mail CLI's `mail <profile> status` answers with it, and the messenger CLIs' `store jobs show`
+  answers with it as `progress`.
 - **Exceptions:** none. drive and zm print no progress shape yet; that is a known gap. Whether the last scheduled run
   failed is a different question, answered by `recordRun` and `failingNotice` in cli-core's schedules.
 - **Applies to:** every CLI with a sync. **Since:** cli-base 0.43.0. **Rulings:** none.

package/docs/standards/new-cli.md

@@ -117,6 +117,9 @@ installing that command; nothing else is registered anywhere.
    `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).
 
+The listings beyond npm (ClawHub, the MCP Registry, the Claude plugin, the docs site, Glama) are a checklist in
+[Publishing](../PUBLISHING.md#a-new-cli).
+
 ## Done when
 
 All of these pass on `main`, before the first release:

package/package.json

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