diff --git a/CHANGELOG.md b/CHANGELOG.md index 00613be..c3dad2a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -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-` 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 diff --git a/cspell.json b/cspell.json index 6f879de..cdbe815 100644 --- a/cspell.json +++ b/cspell.json @@ -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"] } diff --git a/docs/PUBLISHING.md b/docs/PUBLISHING.md index 4433218..2edbb18 100644 --- a/docs/PUBLISHING.md +++ b/docs/PUBLISHING.md @@ -162,7 +162,8 @@ The [official MCP Registry](https://registry.modelcontextprotocol.io) lists each `dev.wirecat/`, 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/"` 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/"` 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 diff --git a/docs/standards/README.md b/docs/standards/README.md index 73ca6d6..79c1bc0 100644 --- a/docs/standards/README.md +++ b/docs/standards/README.md @@ -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 | diff --git a/docs/standards/architecture.md b/docs/standards/architecture.md index ddfa2c1..5c51cd7 100644 --- a/docs/standards/architecture.md +++ b/docs/standards/architecture.md @@ -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. diff --git a/docs/standards/commands.md b/docs/standards/commands.md index 6e13437..8f7012f 100644 --- a/docs/standards/commands.md +++ b/docs/standards/commands.md @@ -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-` (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 `` and +`wcat-` 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 ` runs any `wcat-` 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 @@ -406,9 +410,10 @@ A new CLI joins from its first release: that release installs `wcat-` (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-` 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-` + 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-`: `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. diff --git a/docs/standards/kit-surface.md b/docs/standards/kit-surface.md index 1748abc..0619dff 100644 --- a/docs/standards/kit-surface.md +++ b/docs/standards/kit-surface.md @@ -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.` 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 diff --git a/docs/standards/mcp.md b/docs/standards/mcp.md index df36d6e..fa6b9b5 100644 --- a/docs/standards/mcp.md +++ b/docs/standards/mcp.md @@ -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. @@ -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:` 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 diff --git a/docs/standards/new-cli.md b/docs/standards/new-cli.md index 7cd442b..b3fd539 100644 --- a/docs/standards/new-cli.md +++ b/docs/standards/new-cli.md @@ -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 `. 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 `. See [Testing](testing.md). `cli-dev repo-check --cli ` 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 diff --git a/docs/standards/security.md b/docs/standards/security.md index 52b97e4..f4b2732 100644 --- a/docs/standards/security.md +++ b/docs/standards/security.md @@ -321,7 +321,8 @@ store and runs no search. A CLI declares its provider and may replace any step. - **Example:** new keyring entries are named `oauth::`. drive's and zm's entries from before the module are read and refreshed in the shape they were stored in, so nobody signs in again. - **Exceptions:** a CLI that replaces a step still keeps the explicit profile, the lock, and tokens that are never - printed. A CLI that signs in another way (a bot token, a session) does not use the module. + printed. A CLI that signs in another way (a bot token, a session) does not use the module; a provider token the + owner pastes follows [WC-SECR-26](#wc-secr-26--a-provider-token-the-owner-pastes-is-read-hidden-checked-with-the-service-then-kept-in-the-keyring). - **Applies to:** every CLI that signs in with OAuth. **Since:** cli-base 0.57.1. **Rulings:** NEED-1734. ### WC-SECR-23 · Meeting passcodes and the query of a join link never reach the store, the output or an agent @@ -418,6 +419,46 @@ cli-core's layer for Google and Microsoft, a tool's own layer for a provider onl - **Applies to:** every CLI that signs in with OAuth, and wirecat-desktop. **Since:** cli-base 0.76.1. **Rulings:** owner, 2026-11-04. +### WC-SECR-26 · A provider token the owner pastes is read hidden, checked with the service, then kept in the keyring + +Some providers hand the owner a token to copy instead of a sign-in the CLI can run itself: Yandex shows an OAuth token +in the browser ([Yandex ID's guide](https://yandex.ru/dev/id/doc/en/tokens/debug-token)), and an API key page does +the same. `session start` takes such a token, and the CLI keeps it the way it keeps any other secret. + +- **Read:** with cli-core's `readSecret`, typed at a terminal without echo or read as one line from stdin. Never as an + argument ([WC-SECR-5](#wc-secr-5--a-secret-is-never-taken-on-the-command-line)). `_TOKEN` in the environment + is read for CI ([WC-SECR-4](#wc-secr-4--secrets-come-from-the-environment-then-the-os-keyring-then-a-private-file)), + never written there and never printed, not in an answer, an error or a `--dry-run`. +- **Checked before it is kept:** `session start` asks the service whose token it is, and keeps the token only when the + service accepts it. The answer says `verified: true`, the user and where the token went (`stored_in`), never the + token. +- **Stored:** with cli-core's `ProfileTokenStore`, as `token:` under the CLI's app name: the keyring, a + `0600` file when no keyring works, and a temporary entry in a run with moved folders + ([WC-SECR-24](#wc-secr-24--a-run-with-moved-folders-shares-the-owners-keyring-entry-and-never-deletes-it)). +- **Checked later:** `session status` says where the token comes from (the environment, the keyring or a file); + `session status --check` and `doctor --online` ask the service whose token it is. +- **Revoked:** `session end` forgets the token on this computer. When the provider has a call that revokes such a + token, `session end` makes it first; when it has none, `session end` and the CLI's docs say that the token stays + valid at the provider and where the owner revokes it there. +- **The app.** The CLI runs no OAuth flow, so [WC-SECR-25](#wc-secr-25--sign-in-with-wirecats-app-by-default-and-let-the-owner-choose-their-own)'s + order does not apply to it. The docs name the app the token is issued for: WireCat's when there is one, or the + steps to register the owner's own, with the narrowest access the commands need. + +- **Why:** a pasted token opens the account like a password. Shell history, a process list or a log line would keep + it where other programs and people can read it, and a token kept before the service accepted it breaks the next + command with a confusing error. +- **Enforced by:** review only, check planned: a cli-core test that session start refuses a token given as an + argument and keeps none the service refused. +- **Example:** `ydisk personal session start` asks `Yandex Disk OAuth token:` without echo, or reads + `ydisk personal session start < token.txt`, asks the Disk whose token it is, and answers + `{ "profile": "personal", "state": "saved", "stored_in": "keyring", "verified": true, "user": { … } }`. +- **Exceptions:** a sign-in the CLI runs itself follows + [WC-SECR-22](#wc-secr-22--sign-in-with-oauth-through-cli-cores-sign-in-module). A bot token keeps its own entry, + `bot:` (WC-SECR-4). Known gap, as of 2026-11-17: ydisk's `session end` forgets the token and says it stays + valid at Yandex, but its docs do not yet say where to revoke it. +- **Applies to:** every CLI whose sign-in takes a token the owner pastes (ydisk today). **Since:** cli-base 0.117.0. + **Rulings:** none. + ## Sources These documents explain the rules on this page in more detail. Where one of them disagrees with this page, this page