Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
24 changes: 24 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,30 @@ Every entry says what changed as a caller sees it, why, and what to watch for
- **ydisk (`@wirecat/yandex-disk-cli`) joins the shared lists.** It is in `PARITY_GROUPS`' `shared-roots` group, beside
notion, so `cli-dev audit --family` installs its latest release and compares the root commands every CLI shares. Its
monthly run holds 03:04 UTC in WC-CI-9's table. Watch for: a CLI's `--family` audit now installs one more package.
- **The handbook has a rule for a provider token the owner pastes, WC-SECR-26.** Yandex Disk, for one, gives the
owner a token to copy instead of a sign-in a CLI can run. The rule says how `session start` reads it (hidden at a
terminal or from stdin, never an argument), checks it with the service before keeping it, keeps it in the keyring
through cli-core's `ProfileTokenStore`, and what `session status --check`, `doctor --online` and `session end` do.
Watch for: a CLI with such a sign-in checks its `session end` and docs against the "Revoked" line.
- **WC-MCP-9 covers the MCP Registry entry.** A `server.json` passes `--profiles` as a required argument with a
placeholder such as `personal`, never a fixed `all`, and leaves its versions to `release.yml`. Watch for: tg, max,
wa, zm, gcal, drive, notion, mail, pbx, b24, amo, hubspot and cli-template shipped `--profiles all`; each now passes the
required argument.

### Fixed

- **The New CLI page lists every shared list a new WireCat CLI joins, with the file and when.** It left out the family
audit's package map, `PACKAGES` in `src/dev/family.ts`, so a new CLI's neighbours never installed it for
`cli-dev audit --family`.
- **The Kit surface page no longer says that nothing checks the permission keys.** cli-core's `serviceApiCommand`
checks each operation's keys from 0.684.0; the page now says so, and that `--dry-run` shows them once the CLI merges
`serviceApiPermissions` into its `commandPermissions`. It also no longer says that cli-core cannot read every page:
`--all` does.
- **WC-CMD-29 says what it requires of a CLI's name: the `wcat-<name>` key.** A short name beside it, as every WireCat
CLI installs, is fine; the lint's warning about it is not a failure, and an override only silences it.
- **WC-ARCH-5 names a known gap:** drive's and ydisk's live `files` groups are hand-written in each CLI until cli-core
has a shared files domain.
- **Publishing no longer tells a CLI to pass `--profiles all` in `server.json`.**

## 0.116.0 — 17.11.2026

Expand Down
2 changes: 1 addition & 1 deletion cspell.json
Original file line number Diff line number Diff line change
Expand Up @@ -2,5 +2,5 @@
"version": "0.2",
"files": ["README.md", "docs/standards/**/*.md"],
"import": ["./config/wirecat/cspell.json"],
"words": ["bitrix", "gcal", "Glama", "RAML", "SECR", "upgrader", "wcat", "whatsapp"]
"words": ["bitrix", "gcal", "Glama", "hubspot", "RAML", "SECR", "upgrader", "wcat", "whatsapp", "ydisk"]
}
3 changes: 2 additions & 1 deletion docs/PUBLISHING.md
Original file line number Diff line number Diff line change
Expand Up @@ -162,7 +162,8 @@ The [official MCP Registry](https://registry.modelcontextprotocol.io) lists each
`dev.wirecat/<repo>`, run with `npx`.

**What the repository needs.** `server.json` at the root (schema 2025-12-11, `packages[0]` the npm package,
arguments `mcp serve --profiles all`), and `"mcpName": "dev.wirecat/<repo>"` in `package.json`: the registry reads it
arguments `mcp serve` and a required `--profiles` the installing client asks for, as
[WC-MCP-9](standards/mcp.md#wc-mcp-9--a-server-serves-the-profiles-it-is-told-with-one-connection-for-each) shows), and `"mcpName": "dev.wirecat/<repo>"` in `package.json`: the registry reads it
from npm's copy of that version, so npm comes first. The `version` in `server.json` is overwritten at publish time.

**Each release.** `mcp-registry-dry-run` runs `mcp-publisher validate`. `mcp-registry` (after `tag`) runs
Expand Down
2 changes: 1 addition & 1 deletion docs/standards/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ the four steps that need a person. A new CLI is ready for its first release when
| [Store](store.md) | `STORE` | 14 | Store areas, account scope, migrations, test isolation |
| [Data model](data-model.md) | `DATA` | 9 | Core entities, entities and source records, `external_id`, field names, links and duplicates, files, calendar entries |
| [Testing](testing.md) | `TEST` | 19 | Sandbox, no network, no real waits, one test time limit, leak tests, coverage, contracts, test matrix, parity, fakes as strict as the service |
| [Security](security.md) | `SECR` | 24 | Secrets, logs, keyring, argv, error text, untrusted text, scanners, workflow hardening, reporting, OAuth sign-in and which app it uses, meeting secrets, keyring in moved-folder runs |
| [Security](security.md) | `SECR` | 25 | Secrets, logs, keyring, argv, error text, untrusted text, scanners, workflow hardening, reporting, OAuth sign-in and which app it uses, a provider token the owner pastes, meeting secrets, keyring in moved-folder runs |
| [Documents](docs.md) | `DOC` | 24 | User pages and developer pages, generated pages, current facts, changelog, repository page |
| [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, the owner's yes, trusted publishing |
Expand Down
7 changes: 6 additions & 1 deletion docs/standards/architecture.md
Original file line number Diff line number Diff line change
Expand Up @@ -100,7 +100,12 @@ cli-core's entities, and the adapter behind cli-core's ports. CRM is the first d
Telegram's app registration, or gcal's generated `api` commands. Known gap, as of 2026-11-08: b24's `people`,
`organizations`, `products` and `users` are still its own commands, read live, with its own `people` and
`organizations` writes; they move to cli-core's when it has them. Deals, leads, pipelines, stages and `sync` are
cli-core's.
cli-core's. Known gap, as of 2026-11-17: cli-core has no shared files domain yet, so the live `files` group that
reads and changes the provider's files is hand-written in each file-storage CLI: drive's `files list`, `get`,
`copy`, `move`, `update`, `mkdir` and `upload` (`src/commands/remote.ts`), and ydisk's `files list`, `download`,
`upload`, `copy`, `move`, `delete` and `restore` (`src/commands/files.ts`). Their paths, flags and output may differ
until the group moves to cli-core; a third file-storage CLI waits for it or copies the nearer of the two, not a
third shape.
- **Applies to:** messenger CLIs (tg, max, wa), calendar CLIs (gcal) and CRM CLIs (b24). **Since:** cli-base 0.41.0
(CRM, and the shared domain built first: cli-base 0.80.1). **Rulings:** NEED-820, NEED-440, NEED-301, NEED-444,
NEED-2298.
Expand Down
13 changes: 9 additions & 4 deletions docs/standards/commands.md
Original file line number Diff line number Diff line change
Expand Up @@ -390,7 +390,11 @@ file shipped, `--wcat-describe` answers format 2: the format-1 keys with `"wcat_
and `manifest_sha256` of its bytes. Without it the answer stays format 1.

A new CLI joins from its first release: that release installs `wcat-<name>` (a `"bin"` key) and its bin calls
`wcatStart` first, so it answers `--wcat-describe`. The short name may stay beside it.
`wcatStart` first, so it answers `--wcat-describe`. That key is all the rule requires of the name. The short name
beside it, the command word people type (`ydisk`, `gcal`), is fine and is what WireCat CLIs do: the template writes
both keys, and tg, max, wa, zm, b24, gcal, drive, notion, memo, mail, pbx and ydisk each install `<name>` and
`wcat-<name>` from the same file. The short word is lower-case letters, digits and `-`, and a CLI outside WireCat
does not take a reserved one.

- **Why:** `wcat <name>` runs any `wcat-<name>` program on PATH, and `wcat --help` lists each one with what it says
about itself. A name WireCat reserves would be taken over by WireCat's own tool or by a `wcat` command. WireCat
Expand All @@ -406,9 +410,10 @@ A new CLI joins from its first release: that release installs `wcat-<name>` (a `
answer `--wcat-describe`. `cli-dev manifest --program dist/program.js --identity dist/wcat.js --check` fails when
`contracts/wirecat.json` is stale. `cli-dev release-pr` fails the pull request that raises the version from `0.0.0`,
the version `new` writes, when `package.json` has no `wcat-` `"bin"` key.
- **Exceptions:** a CLI keeps its short `"bin"` name beside `wcat-<name>` until callers have moved to the new name; the
warning stays until then. A CLI that keeps the short name for good says why in `lint/overrides.json` (`"rule":
"wcat-bin-name"`, the target as the warning prints it), which silences the warning and counts against the budget.
- **Exceptions:** `cli-dev lint` warns about every `"bin"` key without the prefix, the short name beside `wcat-<name>`
included. A CLI that keeps the short name says why in `lint/overrides.json` (`"rule": "wcat-bin-name"`, the target
as the warning prints it), which silences the warning and counts against the budget; gcal, pbx and beeline do,
and the other CLIs carry the warning. Either is allowed: the warning is not a failure.
An override covers the short name only, never a CLI with no `wcat-<name>`: `cli-dev release-pr` does not read
`lint/overrides.json`.
A WireCat CLI listed in Desktop's own catalog needs no manifest until Desktop reads one for it.
Expand Down
12 changes: 8 additions & 4 deletions docs/standards/kit-surface.md
Original file line number Diff line number Diff line change
Expand Up @@ -186,13 +186,17 @@ the coverage page after a spec sync.

### Limits

- **Nothing checks the permission keys yet.** cli-core does not read an operation's `permissions`, `servers` or
`securitySchemes` today. Until it does, a CLI adds the keys to its own `commandPermissions`, as notion-cli's
`src/config.ts` does.
- **cli-core checks the permission keys; the CLI still shows them.** From cli-core 0.684.0, `serviceApiCommand`
reads each operation's `permissions`, `servers` and `securitySchemes`: it sends the call to the operation's server
with the sign-in its scheme names, and checks `api.<operation>` and each manifest key that applies to the call
(`files.delete` when `permanently` is true) before it sends. That guard runs whatever the CLI declares. `--dry-run`
and permission discovery show those keys only when the CLI merges `serviceApiPermissions(...)` into its own
`commandPermissions`, field by field (`extra`, `alsoChecks`, `defaults`), as ydisk's `src/config.ts` does:
`alsoChecks: (path) => [...api.alsoChecks(path), ...own(path)]`.
- A merge joins every source's servers at the top, for every operation; sources on different hosts need a
`servers` entry per path, which the merge does not write.
- Pagination is found only from the names above; a service with its own names needs an override per operation.
cli-core reads every page by the manifest once its executor does.
`serviceApiCommand` gives a read that pages `--all`, which reads every page.
- Pagination is not found in an answer that is a union.
- The fake checks shapes, not behaviour: it does not page, filter or keep state. A scenario that needs that writes
it in `answers`. It checks neither header parameters nor RPC operations. A sample follows enums and limits but not
Expand Down
21 changes: 20 additions & 1 deletion docs/standards/mcp.md
Original file line number Diff line number Diff line change
Expand Up @@ -153,6 +153,24 @@ profile by default. The server opens one messenger connection for each profile i
profile shares it. When it serves more than one profile, each call names its profile; a call without one is refused
and lists the profiles served. Each call follows its own profile's permissions.

**The MCP Registry entry.** A `server.json` starts the server the same way: it passes `mcp serve` and a
`--profiles` that the person installing it fills in. That argument is `"type": "named"`, `"isRequired": true`, with
a `"placeholder"` such as `personal` and no `"value"`, so the client asks which profiles to serve. A fixed
`"value": "all"` is the default this rule forbids: every client installed from the registry would reach every
account on the computer. The person may still type `all`. memo, which has no profiles, passes `mcp serve` alone.
The two `version` fields in `server.json`, the server's and its package's, are not kept by hand: `release.yml` sets
both to the version it publishes, then runs `mcp-publisher validate`, so a new CLI leaves them at `0.0.0`.

```json
{
"type": "named",
"name": "--profiles",
"description": "The profiles this server serves: one name, a comma-separated list such as work,personal, or all for every profile on this computer",
"isRequired": true,
"placeholder": "personal"
}
```

- **Why:** which accounts an agent can reach is the owner's choice, written in the agent's config. A connection per
call would break the messenger's pace limits and look unlike the official client.
- **Enforced by:** review only.
Expand All @@ -164,7 +182,8 @@ and lists the profiles served. Each call follows its own profile's permissions.
it reads other CLIs' stores and selects their accounts with `--source email:<name>` or `--account telegram:1`
([cli-base#390](https://github.com/WireCatLabs/cli-base/issues/390), owner decision 2026-10-31). The audit declares
this once, as a difference of memo, not of the other CLIs.
- **Applies to:** messenger CLIs. **Since:** cli-base 0.41.0. **Rulings:** NEED-1881.
- **Applies to:** messenger CLIs; the MCP Registry entry above, every CLI that ships a `server.json`. **Since:**
cli-base 0.41.0; the registry entry since cli-base 0.117.0. **Rulings:** NEED-1881.

### WC-MCP-10 · A tool and its command give the same answer and the same error

Expand Down
21 changes: 16 additions & 5 deletions docs/standards/new-cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -161,11 +161,22 @@ installing that command; nothing else is registered anywhere.
[WC-CI-9](ci.md#wc-ci-9--run-full-validation-and-release-security-on-the-first-day-of-each-month-without-publishing)
and off the hour; a CLI outside WireCatLabs gets one between 04:01 and 05:59 UTC, after that window. Nothing to
change by hand.
4. **WireCat CLIs only: join the shared lists.** `new` prints the entries ready to paste. A pull request to cli-base
with the new minute in WC-CI-9's table and the CLI in `PARITY_GROUPS` (at least the `all` group, which compares the
shared root commands), a line in cli-core's `WIRECAT_TOOLS` and, after the first release, 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).
4. **WireCat CLIs only: join the shared lists.** Each list below names every WireCat CLI by hand, and nothing adds a
new one by itself. `new` prints the entries for the first three, ready to paste; add the others the same way.

| Where | The entry | When |
|---|---|---|
| cli-base `docs/standards/ci.md`, the table under [WC-CI-9](ci.md#wc-ci-9--run-full-validation-and-release-security-on-the-first-day-of-each-month-without-publishing) | the monthly cron minute `new` picked, and the repository | before the first release |
| cli-core `src/ports/wirecat-tools.ts`, `WIRECAT_TOOLS` | the command, `appName`, `envPrefix`, package and what it does | before the first release |
| cli-docs `tools.json` | the command, repository, package, language, summaries and `docsRef` | after the first release, since `docsRef` is its tag |
| cli-base `src/standards/audit.ts`, `PARITY_GROUPS` | the command in `all` when its tree matches the messengers' and memo's, else in `shared-roots`, which compares only the root commands every CLI shares (ydisk, notion, the CRM CLIs); and in its category's group where one exists (`crm`) | before the first release |
| cli-base `src/dev/family.ts`, `PACKAGES` | the command and its npm package, so `cli-dev audit --family` installs it for its neighbours | after the first release, since the audit installs it from npm |

The cli-base entries due before the first release go in one pull request. A command in `FIRST_PARTY_TOOLS`
(`src/wcat/names.ts`) reaches `PACKAGES` from there, and that list also reserves the name (`RESERVED_NAMES`) and
makes `wcat --help` offer to install it; add a CLI there only when `wcat` should offer it. A messenger also joins
cli-core's `parity.json`. A CLI outside WireCatLabs joins none of these: it keeps its parity groups in its own
repository and runs `cli-dev audit --groups <file>`. See [Testing](testing.md).

`cli-dev repo-check --cli <name>` checks steps 1, 3 and 4 on every pull request of a CLI made from cli-template
(`ci.yml:repo-setup`): the ruleset's four rules on `main` and the required checks of step 1 (`conformance` only where
Expand Down
Loading
Loading