@wirecat/cli-base 0.51.1 → 0.52.0

package/CHANGELOG.md

@@ -8,6 +8,14 @@ Versions before 0.8.0 are in the [git tags](https://github.com/WireCatLabs/cli-b
 Every entry says what changed as a caller sees it, why, and what to watch for — the rules are
 [`docs/dev/CONVENTIONS.md`](docs/dev/CONVENTIONS.md#the-changelog).
 
+## 0.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

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/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,6 +35,7 @@ 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 |

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/package.json

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