@wirecat/cli-base 0.62.0 → 0.64.0

package/CHANGELOG.md

@@ -8,6 +8,131 @@ 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.64.0 — 27.10.2026
+
+### Added
+
+- **`cli-dev bundle --bin dist/bin/<cli>.js` builds the published bin as an esbuild bundle, the way tg-cli 0.100.0
+  ships.** It moves tg's `scripts/bundle.ts` into cli-base so every CLI builds the same way: code splitting that keeps
+  each lazy `import()` lazy; `import.meta.url` and run-time package lookups that stay at the original module's place
+  in the CLI, cli-core and cli-base; CommonJS named exports for a dynamic `import("yaml")`; kept names; native and
+  by-name packages left outside. The bin becomes a loader that answers `--version`, turns the compile cache on and,
+  under `serve`, `watch` and `mcp`, preloads every chunk so a running server survives an in-place upgrade. The build
+  fails when a bundled module would look in the wrong place. Add `esbuild` (an optional peer, `^0.28.0`) as a
+  devDependency and name the CLI's own outside packages with `--external`. The rule is
+  [WC-LAY-10](docs/standards/layout.md#wc-lay-10--ship-the-bin-as-a-bundle-that-cli-dev-bundle-builds).
+- **WC-PERM-22 on the [Permissions](docs/standards/permissions.md) page: a CLI that is not a messenger declares its
+  own permission keys and defaults with cli-core's `commandPermissions`** (cli-core 0.450.0). It says how such a CLI
+  keys its commands, picks built-in defaults for what its writes do, and runs writes through the read-only lock and the
+  write guard. The example is a calendar: event writes ask, deleting a whole series and mailing attendees are denied
+  until the owner allows them. The page covered messenger CLIs only, and WC-PERM-6's "ask only before what cannot be
+  undone" read as if it applied to a calendar too; it now says it is the messengers' list. drive, zoom and memo do
+  not declare `commandPermissions` yet; the rule names them as known gaps.
+- **`cli-dev audit` compares gcal (`@wirecat/gcal-cli`, the Google Calendar CLI) in the `all` parity group**, next to
+  tg, max, memo, drive, zm and wa, so its shared root commands are held to the same options and summaries. A run
+  without gcal's command tree skips it, as before; the weekly audit adds it once gcal is published on npm.
+- **The command vocabulary has the words a calendar CLI needs.** Verbs `unsync` (stop syncing a thing; what is
+  stored stays), `review` (list what waits for the owner's decision) and `resolve` (settle one such thing with the
+  owner's choice); collections `calendars`, `events` and `people`. `events` was only a view word, so a command group
+  named `events` was reported by `unknown-resource`.
+- **The vocabulary has the flags and the verb of calendar writes** (cli-core's `events create | update | delete |
+  respond`). Flags `--end-time`, `--start-date`, `--end-date`, `--location`, `--attendee` (repeat it for more),
+  `--id` (the id a create is made with) as `value`; `--calendar` and `--series` as `target`; `--no-notify` as `mode`.
+  `--notify` now means telling the people a change concerns — a chat's members or an event's attendees. Verb
+  `respond` (answer an invitation). Without them `option-role` and `unknown-verb` reported every calendar CLI's
+  write commands.
+- **The vocabulary has the words of free/busy and repeating events** (cli-core's `calendars busy` and
+  `events create | update --repeat`). View `busy` (when calendars or people are taken, without what takes them);
+  flags `--repeat <rule>` (an RFC 5545 rule) as `value` and `--hours <from-to>` (the working hours to look in) as
+  `target`. gcal-cli overrides the four lint reports they cause until it takes this release.
+
+- **`requestSchema(operation, definitions)` in `@wirecat/cli-base/codegen` builds the JSON Schema of a generated
+  operation's request body**, every referenced definition under `$defs`, or returns `null` when the operation takes
+  no body. drive-cli and gcal-cli each kept an identical copy for `api show`. Pass a manifest operation and the
+  `definitions` that `definitionsGenerator` wrote.
+
+### Changed — may break callers
+
+- **A lint baseline entry or override for a word that is now in the vocabulary goes stale, and `cli-dev lint` fails
+  on it.** This release adds `unsync`, `review`, `resolve`, `calendars`, `events` and `people`. zoom-cli lists
+  `events` in `lint/baseline/unknown-resource.json`; gcal-cli lists `calendars`, `events`, `people`,
+  `calendars unsync`, `links review` and `links resolve` in its baseline; drive-cli overrides `unknown-verb` for
+  `comments resolve`, and cli-memo for `search people`, in `lint/overrides.json`. Remove those entries in the same
+  change that takes this version.
+- **The calendar write words make gcal-cli's write baseline stale too.** Its `lint/baseline/option-role.json` (20
+  entries under `events create | update | delete | respond`) and `events respond` in `unknown-verb.json` go stale
+  with this release; remove them when gcal takes it. No other CLI's baseline or overrides on `main` name these words.
+- **The free/busy and repeat words make four of gcal-cli's overrides stale.** `lint/overrides.json` names
+  `calendars busy` (`unknown-verb`), `calendars busy --hours` and `events create | update --repeat` (`option-role`);
+  remove them when gcal takes this release.
+
+- **`describeAlone` is no longer exported from `@wirecat/cli-base/commands`.** It was made public by accident in
+  0.62.0; it is a helper of the shared-command check and only works with a map kept for one check. No known caller
+  imports it. Describe a whole tree with `describeProgram` instead.
+
+### Fixed
+
+- **Handbook corrections from gcal-cli's first-release audit.**
+  - The Toolchain, CI, Security, Testing and Store pages listed "the ten repositories" and "the six CLIs" without
+    gcal. They now say "the WireCat repositories": every WireCat CLI, a new one from its first commit, and the shared
+    repositories. `gcal-cli` is a known repository name for "Enforced by".
+  - WC-SECR-4 said the keyring service is the command's name. It is the CLI's app name (`max-cli`, `gcal-cli`,
+    `cli-memo`), as cli-core passes it.
+  - WC-REL-16 says what a CLI's package `files` holds: `dist`, `skills`, `README.md`, `LICENSE` and what the CLI
+    reads or runs after install (`scenarios`, `install`, notices); `CHANGELOG.md` may ship. Never `src/`, tests,
+    scripts, workflows, `bin/release`, `config/`, `lint/`, `contracts/` or `template.json`.
+  - WC-REL-11 names its one exception: a package's first version, published by the owner with `bin/release --local`,
+    since npm sets a trusted publisher only for a package that exists. Step 2 of
+    [New CLI](docs/standards/new-cli.md) says the same.
+  - [New CLI](docs/standards/new-cli.md) says which copied files a CLI rewrites (seeds) and which it leaves to
+    cli-template (template-owned), and that a template-owned page wrong for the CLI is fixed in cli-template.
+  - "Done when" told authors to add a new CLI's shared audit findings to `audit/baseline`, which has not accepted
+    them since cli-base 0.51.0. It now says to fix each one, or declare an exact difference in the parity group.
+  - WC-CI-8 says the fresh-agent audit is given the pinned cli-base workflows.
+  - WC-TEST-12 has one exception: commands generated from an API description share one reason that names an
+    options-against-the-snapshot test and a test that drives a generated command through `run()`.
+
+- **`syncDiscovery` writes the same snapshot for the same revision of a Google API.** Google serves one revision with
+  its object keys in a different order on each download, so two syncs gave different files, hashes and generated
+  code. The snapshot is now the parsed document with its keys sorted and 2-space indentation; values and array order
+  are unchanged. `sha256` is stable; `sourceSha256` is still the hash of the bytes Google served, so it can change
+  between syncs. The first sync after upgrading rewrites each snapshot once, and `pnpm generate` then reorders the
+  generated types, schemas and manifest once.
+- **`skill show` now names every agent `skill install` serves: Claude Code, Codex, Gemini CLI, OpenClaw, and Hermes
+  on request.** Its help named only the first three, so OpenClaw and Hermes users could not tell the skill was meant
+  for them.
+- **The [CI](docs/standards/ci.md) page lists the monthly cron minutes WireCat repositories already use**, under
+  WC-CI-9, and [New CLI](docs/standards/new-cli.md) step 3 points to it. Finding a free minute meant reading
+  `monthly.yml` in every repository. A new CLI adds its minute to the list in the same pull request that joins the
+  parity groups.
+- **The [Kit surface](docs/standards/kit-surface.md) page lists every cli-core and cli-base export cli-template
+  0.7.0 imports**, among them the ones for MCP over HTTP: `mcpServerCommand`, `serveOverHttp`, `httpLockFile` and
+  the rest. The page left them out, so a change to them would not have been seen as one that reaches every new CLI.
+- **[New CLI](docs/standards/new-cli.md) lets the fresh audit agent read the cli-base workflow files a CLI's
+  workflows pin.** WC-CI-8 tells an audit to read them, but the audit was limited to the handbook and the
+  repository. A release audit prompt kept in a CLI repository needs the same change.
+- **WC-TEST-5 on the [Testing](docs/standards/testing.md) page says that a test may wait for a local process or
+  server it started**, polling with a timeout shorter than the test's own; a fixed sleep is still not allowed. It
+  was unclear whether such a wait counts as waiting for real time.
+- **WC-CMD-6 on the [Commands](docs/standards/commands.md) page names `mcp --revoke` as an exception.** The rule says
+  an option never turns a command into a different action, and `--revoke` does: it forgets every browser login
+  instead of starting a server. The owner kept it an option on `mcp` because it belongs with the HTTP server's login
+  state. No other option gets this exception.
+- **The handbook's examples start `gcal-cli` with the command `gcal`, not `cal`**, the system calendar program on macOS
+  and many Linux systems. A CLI named after it would shadow it.
+
+## 0.63.0 — 27.10.2026
+
+### Added
+
+- **`@wirecat/cli-base/codegen` reads Google Discovery documents: `adaptDiscovery`, `syncDiscovery` and
+  `readDiscovery`.** A Google CLI no longer keeps its own copy of the Discovery adapter and the `spec:sync` script.
+  `adaptDiscovery` takes `exclude` (method id → reason) for methods a CLI cannot serve, such as a `watch` that needs a
+  public webhook, and returns each service's `rootUrl` and `servicePath` for a CLI that calls Google with `fetch`.
+  Effects come from the HTTP verb only: correct a POST that reads, or a method that deletes, with `generate`'s
+  `overrides`. `syncDiscovery` writes the downloaded bytes unchanged and every provenance field, including
+  `sourceSha256` and `normalization`.
+
 ## 0.62.0 — 26.10.2026
 
 ### Added

package/dist/codegen/discovery.d.ts

@@ -0,0 +1,52 @@
+import type { ApiModel } from "./model.js";
+export interface DiscoveryMetadata {
+    /** OAuth scopes per method id, as the document lists them. */
+    scopes: Record<string, string[]>;
+    /** What the model leaves out, one line each, for a reviewer. */
+    omissions: string[];
+}
+/** Where a service's paths are relative to: a request goes to `rootUrl + servicePath + path`. */
+export interface DiscoveryService {
+    rootUrl: string;
+    servicePath: string;
+}
+export interface DiscoveryOptions {
+    sourceUrl?: string;
+    sourceRevision?: string;
+    /**
+     * Method ids left out of the model entirely, each with the reason, as for an override. An id that matches
+     * no method stops generation. For a method a CLI cannot serve, such as a `watch` that needs a public webhook.
+     */
+    exclude?: Readonly<Record<string, string>>;
+}
+export interface DiscoveryResult {
+    model: ApiModel;
+    metadata: DiscoveryMetadata;
+    services: Record<string, DiscoveryService>;
+}
+/** `documents` maps each service name to its parsed Discovery document; schema ids get the service as a prefix. */
+export declare const adaptDiscovery: (documents: Readonly<Record<string, unknown>>, options?: DiscoveryOptions) => DiscoveryResult;
+/** One service's entry in `provenance.json`. */
+export interface DiscoveryProvenance {
+    source: string;
+    revision: string;
+    version: string;
+    /** Of the committed file; `readDiscovery` refuses a snapshot that no longer matches it. */
+    sha256: string;
+    /** Of the bytes Google served. Google varies its key order, so this one can change while `sha256` does not. */
+    sourceSha256: string;
+    normalization: string;
+}
+export interface SyncDiscoveryOptions {
+    /** Where `<service>.json` and `provenance.json` are written. */
+    dir: string;
+    fetch?: typeof globalThis.fetch;
+}
+/**
+ * Downloads each Discovery document, sorts its object keys so the same revision always gives the same file, and
+ * records where it came from. Run by hand, then review the diff: the build never fetches. `provenance.json` keeps the order of `sources`, and that order is
+ * the order of the generated schemas.
+ */
+export declare const syncDiscovery: (sources: Readonly<Record<string, string>>, options: SyncDiscoveryOptions) => Promise<Record<string, DiscoveryProvenance>>;
+/** The snapshots `syncDiscovery` wrote, parsed, in `provenance.json` order. Throws if a file's hash changed. */
+export declare const readDiscovery: (dir: string) => Record<string, unknown>;

package/dist/codegen/discovery.js

@@ -0,0 +1,297 @@
+/**
+ * Google Discovery documents, already parsed → the format-neutral `ApiModel`, plus the offline
+ * snapshot those documents come from: `syncDiscovery` downloads them with their provenance, and
+ * `readDiscovery` loads them back only when every hash still matches.
+ *
+ * Strict like `adaptOpenApi`: an unknown schema keyword, format or parameter location stops generation.
+ * Effects come from the HTTP verb; a method the verb misjudges is corrected with `generate`'s `overrides`.
+ */
+import { createHash } from "node:crypto";
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { CodegenError } from "./pipeline.js";
+const object = (value) => !!value && typeof value === "object" && !Array.isArray(value);
+/** Discovery links point at developers.google.com without the host, which breaks them in generated Markdown. */
+const description = (value) => String(value ?? "").replace(/\]\((\/workspace\/[^)]+)\)/g, "](https://developers.google.com$1)");
+const DESCRIPTIVE = new Set([
+    "id",
+    "description",
+    "format",
+    "enumDescriptions",
+    "enumDeprecated",
+    "readOnly",
+    "deprecated",
+    "annotations",
+    "location",
+    "required",
+    "repeated",
+    "parameterName",
+]);
+const CONSTRAINTS = new Set([
+    "type",
+    "$ref",
+    "properties",
+    "items",
+    "additionalProperties",
+    "enum",
+    "default",
+    "minimum",
+    "maximum",
+    "pattern",
+    "minLength",
+    "maxLength",
+    "minItems",
+    "maxItems",
+    "nullable",
+]);
+const FORMATS = new Set([
+    "int32",
+    "int64",
+    "float",
+    "double",
+    "byte",
+    "date",
+    "date-time",
+    "google-datetime",
+    "google-fieldmask",
+]);
+const METHODS = new Set(["GET", "POST", "PUT", "PATCH", "DELETE", "HEAD"]);
+/** What the HTTP client sets itself; as flags they would only invite a second, wrong value. */
+const TRANSPORT_PARAMETERS = new Set(["key", "oauth_token", "access_token", "upload_protocol", "uploadType"]);
+/** `documents` maps each service name to its parsed Discovery document; schema ids get the service as a prefix. */
+export const adaptDiscovery = (documents, options = {}) => {
+    const exclude = options.exclude ?? {};
+    const excluded = new Set();
+    const schemas = [];
+    const operations = [];
+    const metadata = { scopes: {}, omissions: [] };
+    const services = {};
+    const fail = (problem) => {
+        throw new CodegenError([problem]);
+    };
+    const node = (value, service, where) => {
+        if (!object(value))
+            return fail(`${where}: expected a Discovery schema object`);
+        for (const key of Object.keys(value))
+            if (!DESCRIPTIVE.has(key) && !CONSTRAINTS.has(key))
+                fail(`${where}: unsupported schema keyword ${key}`);
+        if (value.format !== undefined && !FORMATS.has(String(value.format)))
+            fail(`${where}: unsupported format`);
+        const common = {
+            ...(typeof value.description === "string" ? { description: description(value.description) } : {}),
+            ...(value.nullable === true ? { nullable: true } : {}),
+            ...(value.deprecated === true ? { deprecated: true } : {}),
+            ...(value.default !== undefined ? { default: value.default } : {}),
+        };
+        if (typeof value.$ref === "string")
+            return { ...common, type: "ref", ref: `${service}_${value.$ref}` };
+        const bound = (key) => {
+            if (value[key] === undefined)
+                return {};
+            const n = Number(value[key]);
+            if (!Number.isFinite(n))
+                fail(`${where}: invalid numeric bound`);
+            return { [key]: n };
+        };
+        switch (value.type) {
+            case "any":
+                return { ...common, type: "unknown" };
+            case "string":
+                return {
+                    ...common,
+                    type: "string",
+                    ...(Array.isArray(value.enum) ? { enum: value.enum.map(String) } : {}),
+                    ...(typeof value.pattern === "string"
+                        ? { pattern: value.pattern }
+                        : value.format === "int64"
+                            ? { pattern: "^-?\\d+$" }
+                            : {}),
+                    ...bound("minLength"),
+                    ...bound("maxLength"),
+                };
+            case "integer":
+                return {
+                    ...common,
+                    type: "integer",
+                    ...(value.format === "int64" ? { format: "int64" } : { format: "int32" }),
+                    ...bound("minimum"),
+                    ...bound("maximum"),
+                    ...(Array.isArray(value.enum) ? { enum: value.enum.map(Number) } : {}),
+                };
+            case "number":
+                return { ...common, type: "number", ...bound("minimum"), ...bound("maximum") };
+            case "boolean":
+                return { ...common, type: "boolean" };
+            case "array":
+                return {
+                    ...common,
+                    type: "array",
+                    items: node(value.items, service, `${where}/items`),
+                    ...bound("minItems"),
+                    ...bound("maxItems"),
+                };
+            case "object": {
+                const properties = object(value.properties) ? value.properties : {};
+                return {
+                    ...common,
+                    type: "object",
+                    properties: Object.fromEntries(Object.entries(properties).map(([key, item]) => [key, node(item, service, `${where}/properties/${key}`)])),
+                    required: Array.isArray(value.required) ? value.required.map(String) : [],
+                    ...(object(value.additionalProperties)
+                        ? { additionalProperties: node(value.additionalProperties, service, `${where}/additionalProperties`) }
+                        : {}),
+                };
+            }
+            default:
+                return fail(`${where}: unsupported schema type`);
+        }
+    };
+    for (const [service, source] of Object.entries(documents)) {
+        if (!object(source) || source.name !== service || !object(source.schemas) || !object(source.resources))
+            fail(`invalid Discovery document: ${service}`);
+        const document = source;
+        if (typeof document.rootUrl !== "string" || typeof document.servicePath !== "string")
+            fail(`invalid Discovery document: ${service} has no rootUrl or servicePath`);
+        services[service] = { rootUrl: String(document.rootUrl), servicePath: String(document.servicePath) };
+        for (const [id, value] of Object.entries(document.schemas))
+            schemas.push({ id: `${service}_${id}`, schema: node(value, service, `/schemas/${id}`) });
+        const walk = (resources, path) => {
+            for (const [resource, value] of Object.entries(resources)) {
+                if (!object(value))
+                    fail(`invalid resource: ${resource}`);
+                const resourceValue = value;
+                const location = `${path}/${resource}`;
+                if (object(resourceValue.methods))
+                    for (const [name, raw] of Object.entries(resourceValue.methods)) {
+                        if (!object(raw) || typeof raw.id !== "string" || typeof raw.path !== "string")
+                            return fail(`invalid method at ${location}`);
+                        if (exclude[raw.id] !== undefined) {
+                            excluded.add(raw.id);
+                            metadata.omissions.push(`${raw.id}: excluded — ${exclude[raw.id]}`);
+                            continue;
+                        }
+                        const method = String(raw.httpMethod);
+                        if (!METHODS.has(method))
+                            fail(`unsupported HTTP method: ${raw.id}`);
+                        const effect = method === "GET" || method === "HEAD" ? "read" : method === "DELETE" ? "destructive" : "write";
+                        metadata.scopes[raw.id] = Array.isArray(raw.scopes) ? raw.scopes.map(String) : [];
+                        const common = object(document.parameters) ? document.parameters : {};
+                        const parameters = { ...common, ...(object(raw.parameters) ? raw.parameters : {}) };
+                        const safe = Object.entries(parameters).filter(([key]) => !TRANSPORT_PARAMETERS.has(key));
+                        const operation = {
+                            id: raw.id,
+                            binding: { kind: "http", method, path: raw.path },
+                            effect,
+                            summary: description(raw.description ?? raw.id).split("\n")[0],
+                            description: description(raw.description),
+                            tags: [service],
+                            parameters: safe.map(([key, value]) => {
+                                if (!object(value) || !["path", "query"].includes(String(value.location)))
+                                    return fail(`unsupported parameter: ${raw.id}/${key}`);
+                                const schema = node(value, service, `${location}/methods/${name}/parameters/${key}`);
+                                return {
+                                    name: key,
+                                    in: value.location,
+                                    required: value.required === true,
+                                    ...(typeof value.description === "string" ? { description: description(value.description) } : {}),
+                                    schema: value.repeated === true ? { type: "array", items: schema } : schema,
+                                };
+                            }),
+                            source: { location: `${service}${location}/methods/${name}` },
+                            ...(raw.deprecated === true ? { deprecated: true } : {}),
+                        };
+                        if (object(raw.request))
+                            operation.requestBody = {
+                                confidence: "contract",
+                                required: raw.request.required === true,
+                                schema: node(raw.request, service, `${location}/methods/${name}/request`),
+                            };
+                        if (object(raw.response))
+                            operation.response = {
+                                confidence: "contract",
+                                schema: node(raw.response, service, `${location}/methods/${name}/response`),
+                                required: false,
+                            };
+                        if (raw.supportsMediaUpload || raw.supportsMediaDownload)
+                            metadata.omissions.push(`${raw.id}: JSON endpoint only; media transport is not generated`);
+                        operations.push(operation);
+                    }
+                if (object(resourceValue.resources))
+                    walk(resourceValue.resources, `${location}/resources`);
+            }
+        };
+        walk(document.resources, "/resources");
+    }
+    const stale = Object.keys(exclude).filter((id) => !excluded.has(id));
+    if (stale.length > 0)
+        throw new CodegenError(stale.map((id) => `exclusion "${id}" matches no method — stale, or the id changed`));
+    return {
+        model: {
+            source: {
+                kind: "other",
+                sourceUrl: options.sourceUrl ?? "https://developers.google.com/discovery",
+                ...(options.sourceRevision !== undefined ? { sourceRevision: options.sourceRevision } : {}),
+            },
+            operations: operations.sort((a, b) => a.id.localeCompare(b.id)),
+            schemas,
+        },
+        metadata,
+        services,
+    };
+};
+const sha256 = (bytes) => createHash("sha256").update(bytes).digest("hex");
+/** Google serves the same revision with its keys in a different order each time; arrays keep theirs. */
+const sortKeys = (value) => Array.isArray(value)
+    ? value.map(sortKeys)
+    : object(value)
+        ? Object.fromEntries(Object.keys(value)
+            .sort()
+            .map((key) => [key, sortKeys(value[key])]))
+        : value;
+const NORMALIZATION = "object keys sorted, 2-space JSON; values and array order unchanged";
+/**
+ * Downloads each Discovery document, sorts its object keys so the same revision always gives the same file, and
+ * records where it came from. Run by hand, then review the diff: the build never fetches. `provenance.json` keeps the order of `sources`, and that order is
+ * the order of the generated schemas.
+ */
+export const syncDiscovery = async (sources, options) => {
+    const fetch = options.fetch ?? globalThis.fetch;
+    const provenance = {};
+    const downloaded = {};
+    for (const [service, source] of Object.entries(sources)) {
+        const response = await fetch(source, { signal: AbortSignal.timeout(30_000), redirect: "error" });
+        if (!response.ok)
+            throw new Error(`Google Discovery fetch failed for ${service}: HTTP ${response.status}`);
+        const raw = await response.text();
+        const document = JSON.parse(raw);
+        if (!object(document) || document.name !== service)
+            throw new Error(`${source} is not the Discovery document of ${service}`);
+        const written = `${JSON.stringify(sortKeys(document), null, 2)}\n`;
+        downloaded[service] = written;
+        provenance[service] = {
+            source,
+            revision: String(document.revision),
+            version: String(document.version),
+            sha256: sha256(written),
+            sourceSha256: sha256(raw),
+            normalization: NORMALIZATION,
+        };
+    }
+    mkdirSync(options.dir, { recursive: true });
+    for (const [service, text] of Object.entries(downloaded))
+        writeFileSync(join(options.dir, `${service}.json`), text);
+    writeFileSync(join(options.dir, "provenance.json"), `${JSON.stringify(provenance, null, 2)}\n`);
+    return provenance;
+};
+/** The snapshots `syncDiscovery` wrote, parsed, in `provenance.json` order. Throws if a file's hash changed. */
+export const readDiscovery = (dir) => {
+    const provenance = JSON.parse(readFileSync(join(dir, "provenance.json"), "utf8"));
+    const documents = {};
+    for (const [service, entry] of Object.entries(provenance)) {
+        const raw = readFileSync(join(dir, `${service}.json`));
+        if (sha256(raw) !== entry.sha256)
+            throw new CodegenError([`Discovery hash mismatch: ${service}`]);
+        documents[service] = JSON.parse(raw.toString("utf8"));
+    }
+    return documents;
+};

package/dist/codegen/index.d.ts

@@ -1,9 +1,12 @@
 /**
  * Turns an official API description into committed code: types, Valibot schemas, an operation
- * manifest and a coverage page. Build-time only, and format-neutral: it parses no file format and
- * adds no dependency. `adaptOpenApi` reads an OpenAPI document the consumer has parsed; an adapter from
- * Postman or anything else lives in the consumer.
+ * manifest and a coverage page. Build-time, apart from the small helpers a CLI reads the generated
+ * files with (`identifier`, `requestSchema`), and format-neutral: it parses no file format and
+ * adds no dependency. `adaptOpenApi` reads an OpenAPI document and `adaptDiscovery` Google Discovery
+ * documents the consumer has parsed; an adapter from Postman or anything else lives in the consumer.
  */
+export { adaptDiscovery, type DiscoveryMetadata, type DiscoveryOptions, type DiscoveryProvenance, type DiscoveryResult, type DiscoveryService, readDiscovery, type SyncDiscoveryOptions, syncDiscovery, } from "./discovery.js";
+export { requestSchema } from "./json-schema.js";
 export { type CoverageOptions, coverageGenerator, definitionsGenerator, type ManifestOperation, manifestGenerator, } from "./manifest.js";
 export type { ApiBody, ApiModel, ApiOperation, ApiParameter, ApiSchema, Binding, CodeGenerator, Confidence, Discriminator, Effect, GeneratedArtifact, HttpBinding, HttpMethod, Override, RpcBinding, SchemaNode, SourceInfo, SourceReference, } from "./model.js";
 export { identifier, kebab } from "./names.js";

package/dist/codegen/index.js

@@ -1,9 +1,12 @@
 /**
  * Turns an official API description into committed code: types, Valibot schemas, an operation
- * manifest and a coverage page. Build-time only, and format-neutral: it parses no file format and
- * adds no dependency. `adaptOpenApi` reads an OpenAPI document the consumer has parsed; an adapter from
- * Postman or anything else lives in the consumer.
+ * manifest and a coverage page. Build-time, apart from the small helpers a CLI reads the generated
+ * files with (`identifier`, `requestSchema`), and format-neutral: it parses no file format and
+ * adds no dependency. `adaptOpenApi` reads an OpenAPI document and `adaptDiscovery` Google Discovery
+ * documents the consumer has parsed; an adapter from Postman or anything else lives in the consumer.
  */
+export { adaptDiscovery, readDiscovery, syncDiscovery, } from "./discovery.js";
+export { requestSchema } from "./json-schema.js";
 export { coverageGenerator, definitionsGenerator, manifestGenerator, } from "./manifest.js";
 export { identifier, kebab } from "./names.js";
 export { adaptOpenApi, OpenApiError } from "./openapi.js";

package/dist/codegen/json-schema.d.ts

@@ -0,0 +1,8 @@
+import type { ManifestOperation } from "./manifest.js";
+import type { SchemaNode } from "./model.js";
+/**
+ * The JSON Schema (draft 2020-12) of an operation's request body, built from the `definitions` that
+ * `definitionsGenerator` wrote, with every referenced definition under `$defs`; `null` when the operation takes no
+ * body. For a CLI's `api show`, so an agent sees what to send before it calls.
+ */
+export declare const requestSchema: (operation: Pick<ManifestOperation, "request">, definitions: Readonly<Record<string, SchemaNode>>) => Record<string, unknown> | null;

package/dist/codegen/json-schema.js

@@ -0,0 +1,78 @@
+import { identifier } from "./names.js";
+/**
+ * The JSON Schema (draft 2020-12) of an operation's request body, built from the `definitions` that
+ * `definitionsGenerator` wrote, with every referenced definition under `$defs`; `null` when the operation takes no
+ * body. For a CLI's `api show`, so an agent sees what to send before it calls.
+ */
+export const requestSchema = (operation, definitions) => {
+    if (!operation.request?.schema)
+        return null;
+    const defs = {};
+    const visiting = new Set();
+    const node = (value) => {
+        const common = { ...(value.description ? { description: value.description } : {}) };
+        switch (value.type) {
+            case "ref": {
+                const name = identifier(value.ref);
+                add(name);
+                return { ...common, $ref: `#/$defs/${name}` };
+            }
+            case "unknown":
+                return common;
+            case "union":
+                return { ...common, anyOf: value.of.map(node) };
+            case "allOf":
+                return { ...common, allOf: value.of.map(node) };
+            case "object":
+                return {
+                    ...common,
+                    type: "object",
+                    properties: Object.fromEntries(Object.entries(value.properties).map(([key, item]) => [key, node(item)])),
+                    required: value.required,
+                    additionalProperties: value.additionalProperties ? node(value.additionalProperties) : true,
+                };
+            case "array":
+                return {
+                    ...common,
+                    type: "array",
+                    items: node(value.items),
+                    ...(value.minItems === undefined ? {} : { minItems: value.minItems }),
+                    ...(value.maxItems === undefined ? {} : { maxItems: value.maxItems }),
+                };
+            case "string":
+                return {
+                    ...common,
+                    type: "string",
+                    ...(value.enum ? { enum: value.enum } : {}),
+                    ...(value.pattern ? { pattern: value.pattern } : {}),
+                    ...(value.minLength === undefined ? {} : { minLength: value.minLength }),
+                    ...(value.maxLength === undefined ? {} : { maxLength: value.maxLength }),
+                };
+            case "boolean":
+                return { ...common, type: "boolean" };
+            case "integer":
+            case "number":
+                return {
+                    ...common,
+                    type: value.type,
+                    ...(value.minimum === undefined ? {} : { minimum: value.minimum }),
+                    ...(value.maximum === undefined ? {} : { maximum: value.maximum }),
+                };
+        }
+    };
+    const add = (name) => {
+        if (visiting.has(name))
+            return;
+        visiting.add(name);
+        const value = definitions[name];
+        if (!value)
+            throw new Error(`generated schema reference is missing: ${name}`);
+        defs[name] = node(value);
+    };
+    add(operation.request.schema);
+    return {
+        $schema: "https://json-schema.org/draft/2020-12/schema",
+        $ref: `#/$defs/${operation.request.schema}`,
+        $defs: defs,
+    };
+};

package/dist/codegen/model.d.ts

@@ -1,7 +1,8 @@
 /**
  * The model every generator reads, whatever the source was: an OpenAPI file, a Postman collection,
  * a scraped reference page. An adapter produces this from a document already parsed into plain
- * values: `adaptOpenApi` for OpenAPI here, the rest in the consumer. Nothing here reads YAML or a file.
+ * values: `adaptOpenApi` for OpenAPI and `adaptDiscovery` for Google Discovery here, the rest in the
+ * consumer. Nothing here reads YAML or a file.
  */
 export type HttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE" | "HEAD";
 /** How much the source promises. A Postman example is not a contract and must never become one. */

package/dist/codegen/model.js

@@ -1,6 +1,7 @@
 /**
  * The model every generator reads, whatever the source was: an OpenAPI file, a Postman collection,
  * a scraped reference page. An adapter produces this from a document already parsed into plain
- * values: `adaptOpenApi` for OpenAPI here, the rest in the consumer. Nothing here reads YAML or a file.
+ * values: `adaptOpenApi` for OpenAPI and `adaptDiscovery` for Google Discovery here, the rest in the
+ * consumer. Nothing here reads YAML or a file.
  */
 export {};

package/dist/commands/index.d.ts

@@ -12,7 +12,7 @@
 import type { Command } from "commander";
 export { type CommandsDocument, type CommandsDocumentAbout, commandsDocument, commandsDocumentJsonSchema, commandsDocumentSchema, parseCommandsDocument, } from "./document.js";
 export { COMMANDS_PAGE_LABELS, type CommandsPage, type CommandsPageLabels, type CommandsPageText, commandsPage, } from "./page.js";
-export * from "./registry.js";
+export { type ArgumentInfo, annotate, annotateOption, type CommandInfo, type CommandLifetime, type CommandMeta, type CommandOutput, type CommandReach, type CommandState, describeOptions, describeProgram, flatten, metaOf, type OptionInfo, type OptionMeta, type Origin, optionMetaOf, stepTargets, } from "./registry.js";
 /**
  * Refuses a command path that arrived as one argument — `"projects add" --help`, what a zsh loop over
  * `$c` passes. Commander settles `--help` for an unknown word before any hook runs and prints the root

package/dist/commands/index.js

@@ -1,7 +1,7 @@
 import { CliError } from "../errors.js";
 export { commandsDocument, commandsDocumentJsonSchema, commandsDocumentSchema, parseCommandsDocument, } from "./document.js";
 export { COMMANDS_PAGE_LABELS, commandsPage, } from "./page.js";
-export * from "./registry.js";
+export { annotate, annotateOption, describeOptions, describeProgram, flatten, metaOf, optionMetaOf, stepTargets, } from "./registry.js";
 /**
  * Refuses a command path that arrived as one argument — `"projects add" --help`, what a zsh loop over
  * `$c` passes. Commander settles `--help` for an unknown word before any hook runs and prints the root