@wirecat/cli-base 0.61.3 → 0.63.0

package/CHANGELOG.md

@@ -8,6 +8,36 @@ 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.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
+
+- **`describeAlone(command, known)` describes a command as if it had no parent, reusing what `known` already holds.**
+  The shared-command check uses it to describe each command once per pass. Keep `known` for one pass only: a map kept
+  longer returns descriptions of commands that have since changed.
+
+### Fixed
+
+- **The shared-command check describes each command once per pass, not once for itself and again for every group
+  above it.** It runs when a shared command is built and before each command runs, so every command of every CLI paid
+  for it: about 60% of tg's setup, even for `tg --version`. On tg's real program one check now takes about 5 ms
+  instead of 11, building the program about 35 ms instead of 46, and a warm `run(["--version"])` about 30 ms instead
+  of 47 ([measurement](https://github.com/WireCatLabs/cli-testing/blob/main/performance/cli/shared-contract-check/README.md)).
+  The check still covers every protected subcommand, with the same errors and overrides, and `sharedContracts` returns
+  the same contracts as before.
+
 ## 0.61.3 — 26.10.2026
 
 ### Fixed

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. Equal to `sha256` unless the file was normalized after download. */
+    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 byte for byte 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,288 @@
+/**
+ * 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");
+/**
+ * Downloads each Discovery document byte for byte 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 hash = sha256(raw);
+        downloaded[service] = raw;
+        provenance[service] = {
+            source,
+            revision: String(document.revision),
+            version: String(document.version),
+            sha256: hash,
+            sourceSha256: hash,
+            normalization: "none",
+        };
+    }
+    mkdirSync(options.dir, { recursive: true });
+    for (const [service, raw] of Object.entries(downloaded))
+        writeFileSync(join(options.dir, `${service}.json`), raw);
+    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,10 @@
 /**
  * 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.
+ * 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 { 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,10 @@
 /**
  * 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.
+ * 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 { coverageGenerator, definitionsGenerator, manifestGenerator, } from "./manifest.js";
 export { identifier, kebab } from "./names.js";
 export { adaptOpenApi, OpenApiError } from "./openapi.js";

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/contracts.js

@@ -1,25 +1,22 @@
 import { isDeepStrictEqual } from "node:util";
 import { Command } from "commander";
 import { CliError } from "../errors.js";
-import { describeProgram } from "./registry.js";
+import { describeAlone } from "./registry.js";
 const protectedCommands = new WeakMap();
 export const hasSharedContract = (command) => protectedCommands.has(command);
-const snapshot = (command, children) => {
-    const root = new Command("contract");
-    const parent = command.parent;
-    root.addCommand(command);
-    const described = describeProgram(root)[0];
-    command.parent = parent;
-    if (!described)
+const hidden = (command) => Boolean(command._hidden);
+/** Shares arrays with the live command and with `known`: clone it before keeping it past the pass. */
+const snapshot = (command, known = new Map(), children) => {
+    if (hidden(command))
         throw new Error("a hidden command cannot own a shared contract");
-    const { commands: _, usage: __, path: ___, ...contract } = described;
-    return structuredClone({
+    const { commands: _, usage: __, path: ___, ...contract } = describeAlone(command, known);
+    return {
         ...contract,
         aliases: [...command.aliases()],
         children: (children ?? protectedCommands.get(command)?.originalChildren ?? command.commands)
-            .filter((child) => command.commands.includes(child) && !child._hidden)
+            .filter((child) => command.commands.includes(child) && !hidden(child))
             .map((child) => child.name()),
-    });
+    };
 };
 const same = isDeepStrictEqual;
 const visit = (root, fn) => {
@@ -36,11 +33,12 @@ const pathOf = (command) => {
 const differences = (before, after) => [...new Set([...Object.keys(before), ...Object.keys(after)])].filter((field) => !same(before[field], after[field]));
 export const assertSharedContracts = (root) => {
     const changed = [];
+    const known = new Map();
     visit(root, (command) => {
         const protectedContract = protectedCommands.get(command);
         if (!protectedContract)
             return;
-        const fields = differences(protectedContract.contract, snapshot(command));
+        const fields = differences(protectedContract.contract, snapshot(command, known));
         if (fields.length)
             changed.push({ command: pathOf(command).join(" "), fields });
     });
@@ -55,9 +53,9 @@ export const overrideSharedContract = (command, reason, change) => {
     if (!protectedContract)
         throw new Error("only a core-owned command contract can be overridden");
     assertSharedContracts(command);
-    const before = snapshot(command);
+    const before = structuredClone(snapshot(command));
     change(command);
-    const after = snapshot(command);
+    const after = structuredClone(snapshot(command));
     const fields = differences(before, after);
     if (fields.length === 0)
         throw new Error("a shared contract override must change its named command");
@@ -119,14 +117,18 @@ export const sharedCommand = (factory) => (...args) => {
             if (!command.summary() && first.length > 80)
                 command.summary(`${first.slice(0, 77).replace(/\s+\S*$/, "")}…`);
         });
+        const known = new Map();
         visit(shared, (command) => {
-            if (!command._hidden && !protectedCommands.has(command))
-                protectedCommands.set(command, {
-                    contract: snapshot(command),
-                    reference: snapshot(command),
-                    overrides: [],
-                    originalChildren: [...command.commands],
-                });
+            if (hidden(command) || protectedCommands.has(command))
+                return;
+            // One object for both: `contract` is only ever replaced, and `reference` is cloned on the way out.
+            const contract = structuredClone(snapshot(command, known));
+            protectedCommands.set(command, {
+                contract,
+                reference: contract,
+                overrides: [],
+                originalChildren: [...command.commands],
+            });
         });
         shared.hook("preAction", () => {
             let root = shared;
@@ -147,6 +149,7 @@ export const customizeSharedCommand = (reference, reason, build, expectedOverrid
     const command = build();
     assertSharedContracts(command);
     const pending = [];
+    const known = new Map();
     const edits = [];
     const bindingPath = (own) => {
         const path = [own.name()];
@@ -163,7 +166,7 @@ export const customizeSharedCommand = (reference, reason, build, expectedOverrid
             return;
         if (!protectedCommands.has(own)) {
             const originalChildren = own.commands.filter((child) => inherited.reference.children.includes(child.name()));
-            const actual = snapshot(own, originalChildren);
+            const actual = structuredClone(snapshot(own, known, originalChildren));
             const overrides = differences(inherited.contract, actual).map((field) => ({
                 command: bindingPath(own),
                 field,

package/dist/commands/registry.d.ts

@@ -119,3 +119,8 @@ export declare const flatten: (commands: readonly CommandInfo[]) => CommandInfo[
  * in snake_case. Hand it to `stepOf` and `errorObjectOf` as `targets`.
  */
 export declare const stepTargets: (root: Command) => ((command: string) => StepTarget | undefined);
+/**
+ * The command as if it had no parent, so it inherits nothing, and its subcommands the same way. `known` holds what one
+ * pass has described already, so a whole tree costs one description per command; keep it no longer than that pass.
+ */
+export declare const describeAlone: (command: Command, known: Map<Command, CommandInfo>) => CommandInfo;

package/dist/commands/registry.js

@@ -40,7 +40,19 @@ export const stepTargets = (root) => {
         visit(child, [], root.options);
     return (command) => found.get(command);
 };
-const describe = (command, cli, parents, above) => {
+/**
+ * The command as if it had no parent, so it inherits nothing, and its subcommands the same way. `known` holds what one
+ * pass has described already, so a whole tree costs one description per command; keep it no longer than that pass.
+ */
+export const describeAlone = (command, known) => {
+    let found = known.get(command);
+    if (!found) {
+        found = describe(command, "", [], { offMcp: false, noOffline: false }, known);
+        known.set(command, found);
+    }
+    return found;
+};
+const describe = (command, cli, parents, above, known) => {
     const path = [...parents, command.name()];
     const args = command.registeredArguments.map(describeArgument);
     const options = describeOptions(command);
@@ -68,7 +80,7 @@ const describe = (command, cli, parents, above) => {
         ...(visible(command).length > 0 && hasAction(command) ? { runnable: true } : {}),
         arguments: args,
         options,
-        commands: visible(command).map((child) => describe(child, cli, path, here)),
+        commands: visible(command).map((child) => (known ? describeAlone(child, known) : describe(child, cli, path, here))),
     };
 };
 // Commander has no public getter for the action either; without one, a group prints its help.

package/package.json

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