@wirecat/cli-base 0.51.0 → 0.52.0

package/CHANGELOG.md

@@ -8,6 +8,24 @@ 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.52.0 — 25.10.2026
+
+### Added
+
+- **`cli-dev audit --groups <file>`** compares the CLIs by the parity groups in that file instead of `PARITY_GROUPS`. The file is a JSON list in the shape `defineParityGroups` takes (`name`, `members`, `covers`, `differences`) and is checked the same way; a bad file stops the run with exit 2 and names the file. A CLI outside WireCatLabs keeps this file in its own repository and lists itself next to our CLIs, with no pull request here. `--differences` still adds to the groups in use, so with both flags it adds to the file's groups. Without the flag nothing changes.
+- **`cli-dev <command> --help`** prints the usage, as `cli-dev --help` does, instead of failing on an unknown option.
+
+- **A data-model page in the standards** (`WC-DATA-1` to `WC-DATA-7`, [Data model](docs/standards/data-model.md)). It says which records cli-core owns and which stay private to a CLI, keeps a source's records (a calendar entry, a Drive file, a mail contact) apart from the owner's entities (an event, a document, a person), puts every provider id in `external_id`, lists the standard field names, and makes every link record how it was made, with no link when two candidates tie. Nothing changes in code; older tables follow the rules when they next change.
+## 0.51.1 — 24.10.2026
+
+### Fixed
+
+- The shared vocabulary recognizes `--draft` as a switch that saves text for review without sending. Enabling an adapter’s draft capability no longer creates an unknown-option-role lint failure.
+
+### Removed
+
+- **No wait between releases and no weekly limit on breaking changes** (`WC-REL-8`, [Releases](docs/standards/releases.md)). A messenger CLI no longer waits two hours after its last version, and a shared library may ship a change that makes the CLIs change their code at any time. `WC-REL-9` is merged into `WC-REL-8`. The release lock stays. Nothing changes in code.
+
 ## 0.51.0 — 24.10.2026
 
 ### Added

package/dist/dev/main.js

@@ -14,7 +14,7 @@ import { changelogProblems, docsProblems, JOURNAL_IDS, markdownFiles, packageVer
 import { AUDIT_BLOCKS, defineParityGroups, PARITY_GROUPS, REQUIRED_ROOTS } from "../standards/audit.js";
 import { defineReasons } from "../standards/errors.js";
 import { baselineProblems, baselineSchema, LINT_RULES, OVERRIDE_BUDGET, OVERRIDE_RULE_REVIEW, overridesProblems, overridesSchema, rulesForReview, } from "../standards/lint.js";
-import { issuesOf } from "../standards/registry.js";
+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";
@@ -49,14 +49,17 @@ const USAGE = `usage: cli-dev <command> [options]
                                        lint/baseline/<rule>.json to today's violations. --schemas
                                        is a JSON object of the CLI's own JSON Schemas by name
   audit (--cli <bin> | --commands <file>)... [--schemas <cli>=<file>]... [--reasons <cli>=<file>]...
-        [--lint <cli>=<dir>]... [--capabilities <file>] [--complete] [--differences <file>] [--baseline <dir>] [--for <cli>] [--json] [--write-baseline]
+        [--lint <cli>=<dir>]... [--capabilities <file>] [--complete] [--groups <file>] [--differences <file>]
+        [--baseline <dir>] [--for <cli>] [--json] [--write-baseline]
                                        several CLIs against every lint rule and against each other:
                                        required roots, same path same contract, same flag same
                                        meaning, same entity same schema, same failure same reason.
                                        Prints the scorecard; fails on a new finding (one naming
                                        --for's CLI, when given). --lint judges that CLI's lint
                                        rules by its own lint/ folder; the rest by --baseline
-                                       (audit/baseline)`;
+                                       (audit/baseline). --groups replaces PARITY_GROUPS with the
+                                       JSON list of parity groups in that file; --differences adds
+                                       to the groups in use`;
 const load = async (cwd, path) => (await import(pathToFileURL(isAbsolute(path) ? path : join(cwd, path)).href));
 const report = (io, problems, ok) => {
     for (const problem of problems)
@@ -335,6 +338,7 @@ const auditRun = (args, io) => {
             capabilities: { type: "string" },
             complete: { type: "boolean", default: false },
             differences: { type: "string" },
+            groups: { type: "string" },
             reasons: { type: "string", multiple: true },
             lint: { type: "string", multiple: true },
             baseline: { type: "string", default: "audit/baseline" },
@@ -445,6 +449,16 @@ const auditRun = (args, io) => {
     const baselineDir = at(values.baseline);
     const baseline = readBaseline(baselineDir, values.baseline, problems);
     let groups = PARITY_GROUPS;
+    if (values.groups) {
+        try {
+            groups = defineParityGroups(readJson(at(values.groups)));
+        }
+        catch (error) {
+            if (error instanceof RegistryError)
+                throw new Error(`${values.groups}: ${error.problems.join("; ")}`);
+            throw error;
+        }
+    }
     if (values.differences) {
         const schema = v.array(v.strictObject({
             group: v.string(),
@@ -508,6 +522,10 @@ const auditRun = (args, io) => {
 };
 export const main = async (argv, io) => {
     const [command, ...args] = argv;
+    if (args.includes("--help")) {
+        io.out(USAGE);
+        return 0;
+    }
     switch (command) {
         case "slow-tests": {
             const [file = "coverage/tests.json", count = "20"] = args;

package/dist/standards/flags-how.js

@@ -291,6 +291,12 @@ export const HOW_FLAGS = [
         type: "duration",
         meaning: "how old a stored snapshot may be and still count as fresh",
     },
+    {
+        name: "--draft",
+        role: "mode",
+        type: "switch",
+        meaning: "save text for the owner to review and send, without sending a message",
+    },
     { name: "--md", role: "mode", type: "switch", meaning: "the text is the messenger's Markdown" },
     { name: "--no-backup", role: "mode", type: "switch", meaning: "do not back the file up before deleting it" },
     { name: "--no-input", role: "mode", type: "switch", meaning: "never prompt or open an interactive login" },

package/docs/standards/README.md

@@ -1,7 +1,7 @@
 # WireCat CLI standards
 
 This handbook holds the rules every WireCat CLI follows: tools, layout, commands, output, MCP, accounts,
-permissions, architecture, time, tests, security, documents, releases and CI. Read this page first. Then read the page
+permissions, architecture, the data model, time, tests, security, documents, releases and CI. Read this page first. Then read the page
 for the area you are about to change.
 
 It ships in the `@wirecat/cli-base` package. A CLI that depends on cli-base has it at
@@ -35,11 +35,12 @@ rules it keeps. A new CLI is ready for its first release when every check under
 | [Architecture](architecture.md) | `ARCH` | 16 | Layers, dependency direction, vendor types, what goes in which package |
 | [Lifecycle](lifecycle.md) | `LIFE` | 13 | Opening late, who closes, one-shot exits, long-running commands, the `serve` relay, resumable syncs |
 | [Store](store.md) | `STORE` | 14 | Store areas, account scope, migrations, test isolation |
+| [Data model](data-model.md) | `DATA` | 7 | Core entities, entities and source records, `external_id`, field names, links and duplicates |
 | [Testing](testing.md) | `TEST` | 17 | Sandbox, no network, no real waits, leak tests, coverage, contracts, test matrix, parity |
 | [Security](security.md) | `SECR` | 20 | Secrets, logs, keyring, argv, error text, untrusted text, scanners, workflow hardening, reporting |
 | [Documents](docs.md) | `DOC` | 20 | User pages and developer pages, generated pages, current facts, changelog |
 | [Comparisons](comparisons.md) | `CMP` | 11 | Which tools a comparison page lists, rows as user tasks, agents and safety, where others are better, proof of marks |
-| [Releases](releases.md) | `REL` | 16 | `bin/release`, the release lock, versions, release reports, trusted publishing |
+| [Releases](releases.md) | `REL` | 15 | `bin/release`, the release lock, versions, release reports, trusted publishing |
 | [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 |

package/docs/standards/data-model.md

@@ -0,0 +1,163 @@
+# Data model
+
+## Scope
+
+How records are modelled in the shared store: which entities cli-core owns, how a source's records relate to the
+owner's real things, where provider ids go, what fields are called, and how records are linked without making
+duplicates.
+
+Rule ids on this page are `WC-DATA-<n>`. How to read a rule, how ids work and which rule wins are in the
+[index](README.md).
+
+Related pages: the store itself, its areas and migrations are in [Store](store.md); UTC times and date-only values are
+in [Time](time.md); secrets that must never reach the store are in [Security](security.md).
+
+### Words used here
+
+- **Entity:** the real thing the owner means — a person, an event, a document. It carries no provider id. Tables:
+  `persons`, `events`, `event_series`, `documents`.
+- **Source record:** one source's copy of an entity — a mail contact, a Telegram user, a calendar entry, a Zoom
+  meeting, a Drive file, a local file. It carries the account or provider it came from and that provider's id.
+  Tables: `identities` (contacts), `calendar_entries`, `meetings`, `files`, `emails`, `messages`.
+- **Link:** the reference from a source record to its entity, with how it was made.
+- **Core entity:** an entity or source record whose table cli-core owns, because more than one tool may need it.
+
+### Who follows these rules today
+
+These rules are new. Older tables break some of them; a change to one of those tables follows the rule, and nothing
+is rewritten only to follow it:
+
+- Drive files are `documents` rows under a folder account, with Google's facts in `front_matter` JSON and the folder
+  tree in `metadata.catalog` (WC-DATA-3, WC-DATA-5).
+- Drive owners are linked by Google's user id under provider `google-drive`, mail senders by address under `email`,
+  and nothing joins the two (WC-DATA-6).
+- `events` rows made from Zoom meetings have no source record of their own besides the meeting (WC-DATA-2 holds:
+  `meetings` is that record).
+
+## Rules
+
+### WC-DATA-1 · A record more than one tool needs is a core entity in cli-core; a CLI's own tables stay private
+
+A core entity's table, model, store area and migration live in cli-core, and any CLI reads it through cli-core
+(memo is the general reader). A CLI may keep tables of its own — checkpoints, caches, provider bookkeeping — and no
+other CLI reads them. Transient state is never a core entity.
+
+- **Why:** every tool and memo can rely on the same people, events and documents, while a tool's internals stay free
+  to change.
+- **Enforced by:** review only.
+- **Example:** calendars, calendar entries, events, persons, contacts, documents and files are core; drive's sync
+  checkpoint is drive's own.
+- **Exceptions:** none. A CLI's own tables live in its own SQLite file next to the shared store, with its own
+  migrations, and refer to core rows by id only; no other CLI opens that file (NEED-1737). The shared store stays
+  cli-core's alone ([WC-STORE-5](store.md)).
+- **Applies to:** cli-core and every CLI. **Since:** cli-base 0.52.0. **Rulings:** NEED-1730, NEED-1737.
+
+### WC-DATA-2 · Keep a source's records apart from the owner's entities, and link them
+
+What a source returns is stored as a source record; the thing the owner means is an entity; the source record links
+to its entity. One entity may combine source records from several sources and accounts.
+
+- **Why:** the same meeting in two calendars and in Zoom is one event to the owner; the same document in Drive and on
+  disk is one document.
+- **Enforced by:** review only.
+- **Example:** a Google Calendar entry is a `calendar_entries` row with `event_id`; the Zoom recording of that meeting
+  is a `meetings` row with the same `event_id`.
+- **Exceptions:** an entity the owner makes has no source record; a source record may wait unlinked until matching
+  runs.
+- **Applies to:** cli-core. **Since:** cli-base 0.52.0. **Rulings:** NEED-1731.
+
+### WC-DATA-3 · A provider's id goes in `external_id`
+
+The id a provider gives a record is stored in `external_id`, unique with `account_id` (or with `provider` where the
+record has no account). Never in a column named after the provider (`google_id`, `file_id`) and never only in
+`metadata`. A second id the provider also uses gets a named column of its own (`ical_uid`).
+
+- **Why:** one place to look for every provider's id, and one unique key to update a record by.
+- **Enforced by:** review only.
+- **Example:** a Drive file: `files.external_id = '<Drive file id>'`; a Google calendar entry:
+  `calendar_entries.external_id = '<event id>'`, `ical_uid = '<iCalUID>'`.
+- **Exceptions:** a local file has no provider id; its `external_id` is its path relative to its folder root.
+- **Applies to:** cli-core. **Since:** cli-base 0.52.0. **Rulings:** NEED-1732.
+
+### WC-DATA-4 · Use the standard field names
+
+| Meaning | Name |
+|---|---|
+| Primary key; a reference | `id`; `<entity>_id` (`event_id`, `document_id`) |
+| Account, provider, provider's id | `account_id`, `provider`, `external_id` |
+| Subtype; state | `kind`; `status` |
+| Title of content (document, event, chat); name of a person, file or folder | `title`; `name` |
+| Main text; its search form | `body`; `normalized_text` |
+| Web link at the provider (never one that carries a secret) | `url` |
+| File facts | `mime`, `size` (bytes), `content_hash` (sha-256 hex), `path` |
+| Provider extras, front matter | `metadata` (JSON); front matter as `metadata.front_matter` |
+| Our row's times | `created_at`, `updated_at`, `deleted_at` |
+| The provider's times | `external_created_at`, `external_updated_at` |
+| A span; last sync that returned the record | `starts_at`, `ends_at` (exclusive); `seen_at` |
+| A date without a time | `<name>_date` (`YYYY-MM-DD`) |
+| A yes/no | integer 0/1, an adjective (`all_day`, `starred`) |
+| A link to any of several tables | `<noun>able_type`, `<noun>able_id` (`notable_type`) |
+| History; search queue; folded text for filters | `<table>_revisions`; `<entity>_index_pending`; `<field>_folded` |
+
+Times are UTC milliseconds ([Time](time.md)).
+
+- **Why:** a reader of any table knows what a field holds, and a new table does not invent a third name for "edited
+  at".
+- **Enforced by:** review only.
+- **Example:** `files.external_updated_at`, not `modified_at` or `modifiedAt` in JSON.
+- **Exceptions:** existing columns keep their names until their table changes for another reason.
+- **Applies to:** cli-core. **Since:** cli-base 0.52.0. **Rulings:** NEED-1732.
+
+### WC-DATA-5 · A field the store filters, sorts, joins or lists on is a column; the rest is allow-listed JSON
+
+- **Why:** columns can be indexed and checked; JSON keeps rare provider fields without a migration each.
+- **Enforced by:** review only.
+- **Example:** a Drive file's `mime`, `size` and `external_updated_at` are columns; its `sourceVersion` is
+  `metadata.version`.
+- **Exceptions:** none. `metadata` never holds secrets or a provider's raw payload ([Security](security.md)).
+- **Applies to:** cli-core. **Since:** cli-base 0.52.0. **Rulings:** NEED-1733.
+
+### WC-DATA-6 · Every link records how it was made; the owner's link wins; ambiguity makes no link
+
+A link from a source record to its entity records its `method` (the rule, or `owner`), `confidence`, `author` and
+time, and every change is logged. A rule never replaces an owner's link. When two candidates match equally well, no
+link is made and the pair goes to the owner's review list. Title or time overlap alone never links records.
+
+- **Why:** a wrong automatic merge is worse than a duplicate, and the owner must be able to see and undo it.
+- **Enforced by:** review only.
+- **Example:** `identity_links` and `identity_link_events` (contacts to persons); a Zoom meeting at 11:00 next to a
+  10–11 and an 11–12 event links to neither by time alone.
+- **Exceptions:** none.
+- **Applies to:** cli-core. **Since:** cli-base 0.52.0. **Rulings:** NEED-1731.
+
+### WC-DATA-7 · A source record the provider stops returning is soft-deleted; its entity and links stay
+
+- **Why:** a sync error or a revoked share must not erase what the owner linked, wrote or searched.
+- **Enforced by:** review only.
+- **Example:** a calendar sync whose token expired lists again and sets `deleted_at` on entries it did not see; their
+  events and meeting links stay.
+- **Exceptions:** an entity with no live source record and no owner link may be removed by an explicit owner command.
+- **Applies to:** cli-core. **Since:** cli-base 0.52.0. **Rulings:** none.
+
+## Planned — not built yet
+
+From the Wave 3 requirements (cli-private `plans/2026-10-24-open-cli-core-design.md`, under the owner's review):
+
+- a `files` table as the source record of `documents`: a materialised `path` plus `parent_id` to the folder's own
+  row, so a folder is found by path prefix and a document by part of its path (NEED-1739);
+- memo's vault files as documents; an Obsidian vault is provider `obsidian` with its own metadata (tags, aliases,
+  wiki links), a plain folder is `local`; `notes` are only the owner's notes on entities (NEED-1738);
+- a cli-core helper that opens a CLI's own SQLite file (NEED-1737);
+- `calendars`, `calendar_entries` and `calendar_attendees` on the `events` hub;
+- an `email` column on contacts, so one address joins one person across sources;
+- one link log for events and documents, and one review list for ambiguous pairs;
+- renaming `identities` to `contacts`.
+
+## Sources
+
+These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page
+holds.
+
+- [cli-core `ARCHITECTURE.md`, "The store"](https://github.com/WireCatLabs/cli-core/blob/main/docs/dev/ARCHITECTURE.md#the-store)
+- cli-private `plans/2026-10-24-open-cli-core-design.md` (private; the rulings NEED-1730 to NEED-1734 are summarised
+  above)

package/docs/standards/new-cli.md

@@ -92,8 +92,8 @@ whatsapp-cli is the worked example: it has every file below. Compare with it whe
 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 waits two
-   hours between releases and checks a signed release report (WC-REL-8, WC-REL-10). See [Releases](releases.md).
+   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`.
 
 ## Done when

package/docs/standards/releases.md

@@ -88,29 +88,17 @@ on the [CI](ci.md) page.
 - **Exceptions:** a pre-release version (`0.41.0-rc.1`) is chosen by hand.
 - **Applies to:** all CLIs and shared libraries. **Since:** cli-base 0.41.0. **Rulings:** none.
 
-### WC-REL-8 · A messenger CLI waits two hours between releases; a shared library does not wait
+### WC-REL-8 · Any package may release at any time
 
-- **Why:** a broken CLI release must be noticed before the next one lands on top of it. Every CLI waits for a library
-  release, so a gap there only delays them.
-- **Enforced by:** `<app>: bin/release`.
-- **Example:** tg-cli, max-cli and whatsapp-cli's `bin/release` refuse to start within two hours of the last version
-  on npm. cli-base and cli-core release one after another with no gap.
-- **Exceptions:** memo, drive and zoom have no gap in their `bin/release` today.
-- **Applies to:** messenger CLIs (gap); shared libraries (no gap). **Since:** cli-base 0.41.0. **Rulings:** NEED-854.
-
-### WC-REL-9 · A change to a stable shared-library export that makes a CLI change its code ships at most once a week
-
-- **Why:** the limit keeps the CLIs from chasing versions; a change that no CLI has to follow gives them nothing to
-  chase.
-- **Enforced by:** `cli-core: parity.yml` (it decides which changes count; review keeps the week).
-- **Example:** cli-core's parity jobs build tg-cli, max-cli and whatsapp-cli from their `main` against every pull
-  request. A change to a stable export counts unless all three jobs pass with each CLI's `main` unchanged; its
-  changelog still lists it under "Changed — may break callers" for outside users. It counts when a job fails, when it
-  passes only against a CLI branch made for the change, and when it compiles but changes behaviour that any CLI must
-  adapt to. Parity cannot see that last case, so when in doubt the change counts. Gather the changes that count into
-  one release a week, and bump the library in every CLI that uses it on the same day.
-- **Exceptions:** none.
-- **Applies to:** shared libraries. **Since:** cli-base 0.41.0. **Rulings:** NEED-473, NEED-1552.
+- **Why:** a wait between releases or a weekly limit on breaking changes only delays a fix; the owner removed both
+  limits on 2026-10-24.
+- **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.
+- **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)
 
 ### WC-REL-10 · A messenger CLI is released only with a release report the owner signed for that commit
 

package/package.json

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