@greatwait/cli 0.1.0-alpha.3 → 0.1.0-alpha.4

package/dist/catalog.js

@@ -0,0 +1,1453 @@
+import { OPERATIONS } from "@greatwait/contracts";
+import { EXIT_CLASSES, EXIT_CLASS_MEANINGS } from "./exit.js";
+/**
+ * The name every written instruction uses.
+ *
+ * The package installs two executables — `greatwait` and `gw` — and each states
+ * its own name, so what a person is told to type next is what they just typed.
+ * The *published* reference, the quickstarts and the first-value journey use
+ * this one, because a written instruction has to be followable by somebody who
+ * installed either.
+ */
+export const CANONICAL_PROGRAM_NAME = "greatwait";
+/** The principals a command line can present. Never a browser session. */
+export const CLI_PRINCIPALS = ["api-credential", "oauth"];
+/* -------------------------------------------------------------------------- */
+/* Derived properties of a registry entry                                     */
+/* -------------------------------------------------------------------------- */
+/** Whether any principal this command line can hold may call it. */
+export function reachableByCli(operation) {
+    if (operation.principals.length === 0)
+        return true;
+    return operation.principals.some((principal) => CLI_PRINCIPALS.some((held) => held === principal));
+}
+/** Whether the API serves it at all, as opposed to the contract mock alone. */
+export function servedByApi(operation) {
+    return operation.surfaces.some((surface) => surface === "api");
+}
+/**
+ * Why a command covering this operation must confirm before acting, if it must.
+ *
+ * **Derived from the registry's own hints rather than from a list here**, so an
+ * operation that becomes destructive tomorrow makes a command that does not ask
+ * fail this gate rather than quietly keep shipping.
+ *
+ * Two grounds, and the second is the one that took a correction. Every
+ * externally visible call is *not* a confirmation: `schedules create` reaches a
+ * receiver by design and is the first thing anybody runs, so demanding a
+ * keystroke there would put a prompt in the middle of the published first-value
+ * journey. What separates it from `occurrences redeliver` — which does deserve
+ * one — is that redelivery acts on something that already exists and sends it
+ * again. So the ground is an outward-facing change to an *addressed* object,
+ * which is exactly an operation with a path parameter.
+ */
+export function confirmationGround(operation) {
+    if (operation.mcp.kind === "tool" && operation.mcp.destructive) {
+        return "destructive";
+    }
+    // **Not conditioned on `mutates`, and a review round is why.** Writing it as
+    // "changes stored state *and* reaches outward" conflates two questions: an
+    // operation that pings an addressed receiver without persisting anything
+    // would have been declared `mutates: false` and skipped the confirmation
+    // requirement entirely — while having exactly the character the requirement
+    // exists for, a real outbound request made on behalf of an object somebody
+    // else may be relying on. No operation in the registry is that shape today,
+    // which is precisely why the rule had to be written for the one that will be.
+    if (operation.mcp.kind === "tool" &&
+        operation.mcp.openWorld &&
+        operation.path.includes("{")) {
+        return "outward-facing-change";
+    }
+    return undefined;
+}
+/**
+ * The request headers the registry declares for an operation.
+ *
+ * Read off the schema's own shape rather than listed here, because the point of
+ * the rules below is that a header appearing or disappearing changes what the
+ * command line must offer. `endpoints.disable` is the case that makes it worth
+ * checking: every other endpoint write accepts `If-Match` and that one does
+ * not, so a command offering the flag there would document a guard the service
+ * ignores — which reads to somebody operating carefully as protection they do
+ * not have.
+ */
+export function declaredRequestHeaders(operation) {
+    const schema = operation.requestHeaders;
+    return schema?.shape === undefined ? [] : Object.keys(schema.shape);
+}
+/* -------------------------------------------------------------------------- */
+/* Shared option declarations                                                 */
+/* -------------------------------------------------------------------------- */
+const API_URL = {
+    flag: "--api-url",
+    summary: "The service to talk to, when it is not the selected one.",
+    value: "<origin>",
+};
+const PAGE_OPTIONS = [
+    {
+        flag: "--limit",
+        summary: "How many rows to ask for in one page.",
+        value: "<count>",
+    },
+    {
+        flag: "--cursor",
+        summary: "Continue from the cursor a previous page returned.",
+        value: "<cursor>",
+    },
+    {
+        flag: "--all",
+        summary: "Follow cursors until the collection ends, up to a published ceiling.",
+    },
+];
+const CONFIRM = {
+    flag: "--yes",
+    summary: "Confirm without being asked. Required when there is no terminal to ask on.",
+};
+const IF_MATCH = {
+    flag: "--if-match",
+    summary: "Refuse unless it is still at this version. Read it first to get the ETag.",
+    value: "<etag>",
+};
+const IDEMPOTENCY = {
+    flag: "--idempotency-key",
+    summary: "Make a repeat of this exact request a replay rather than a second.",
+    value: "<key>",
+};
+/* -------------------------------------------------------------------------- */
+/* The catalog                                                                */
+/* -------------------------------------------------------------------------- */
+/**
+ * Every command, in the order the reference and `--help` present them.
+ *
+ * Ordered by what somebody does rather than alphabetically: sign in, look
+ * around, set up a destination, schedule something, watch it, then recover from
+ * it. The groups are the headings.
+ */
+export const COMMAND_CATALOG = [
+    /* --- Session ---------------------------------------------------------- */
+    {
+        group: "Session",
+        operations: ["context.read"],
+        options: [
+            API_URL,
+            {
+                flag: "--api-key",
+                summary: "Sign in with a scoped API credential instead of a browser. Takes no value: paste it when asked, or pipe it in.",
+            },
+            {
+                flag: "--no-browser",
+                summary: "Print the authorization address instead of opening it.",
+            },
+            {
+                // **A way to ask for less than the whole command line can do.** The
+                // request is the union of every covered operation's scopes, which is
+                // honest — this command really can rotate a credential — but somebody
+                // whose only use is scheduling should not have to grant the rest to get
+                // there. Narrowing is safe in the direction that matters: a command
+                // outside the grant is refused by the service.
+                flag: "--scope",
+                summary: "Ask for these permissions instead of everything the commands can use, separated by spaces in one argument.",
+                value: "<scopes>",
+            },
+        ],
+        positionals: [],
+        summary: "Sign in to a Greatwait service and remember the credential.",
+        words: "login",
+    },
+    {
+        group: "Session",
+        operations: [],
+        options: [API_URL],
+        positionals: [],
+        summary: "Revoke the grant where possible and remove the local material.",
+        words: "logout",
+    },
+    {
+        group: "Session",
+        operations: ["context.read"],
+        options: [API_URL],
+        positionals: [],
+        summary: "Report which service, project and environment this acts in.",
+        words: "whoami",
+    },
+    {
+        group: "Session",
+        operations: ["meta.version", "context.read"],
+        options: [API_URL],
+        positionals: [],
+        summary: "Check the service, the stored configuration and the credential.",
+        words: "doctor",
+    },
+    {
+        group: "Session",
+        operations: [],
+        options: [API_URL],
+        positionals: [
+            {
+                name: "[list | use <origin>]",
+                optional: true,
+                summary: "Show the signed-in services, or select one.",
+            },
+        ],
+        summary: "Show or choose the service later commands go to.",
+        words: "context",
+    },
+    {
+        group: "Session",
+        operations: [],
+        options: [API_URL],
+        positionals: [],
+        summary: "Print the published first-value sequence and its commands.",
+        words: "journey",
+    },
+    /* --- Destinations ----------------------------------------------------- */
+    {
+        group: "Destinations",
+        operations: ["endpoints.list"],
+        options: [API_URL, ...PAGE_OPTIONS],
+        positionals: [],
+        summary: "List the destinations this project delivers to.",
+        words: "destinations list",
+    },
+    {
+        group: "Destinations",
+        operations: ["endpoints.read"],
+        options: [API_URL],
+        positionals: [
+            { name: "<destination>", summary: "The destination to read." },
+        ],
+        summary: "Read one destination, its status and its signing keys.",
+        words: "destinations read",
+    },
+    {
+        group: "Destinations",
+        operations: ["endpoints.create"],
+        options: [
+            API_URL,
+            {
+                flag: "--url",
+                summary: "The https receiver Greatwait will deliver to.",
+                value: "<https url>",
+            },
+        ],
+        positionals: [],
+        summary: "Create a destination and print its signing key once.",
+        words: "destinations create",
+    },
+    {
+        confirms: true,
+        group: "Destinations",
+        operations: ["endpoints.update"],
+        options: [
+            API_URL,
+            {
+                flag: "--url",
+                summary: "The new https receiver.",
+                value: "<https url>",
+            },
+            IF_MATCH,
+            CONFIRM,
+        ],
+        positionals: [
+            { name: "<destination>", summary: "The destination to change." },
+        ],
+        summary: "Point a destination at a different receiver.",
+        words: "destinations update",
+    },
+    {
+        // **Confirmed although the registry has no hint that says so.** Rotation is
+        // withheld from MCP precisely because it returns a one-time secret, so
+        // there is no `destructive` hint to derive from; a call whose answer is
+        // lost has rotated a key nobody holds, which is the harm the prompt exists
+        // for. The rule below permits a command to be more careful than the
+        // registry demands, and this is the one that is.
+        confirms: true,
+        group: "Destinations",
+        operations: ["endpoints.rotateSigningKey"],
+        options: [API_URL, IF_MATCH, CONFIRM],
+        positionals: [
+            { name: "<destination>", summary: "The destination to rotate." },
+        ],
+        summary: "Mint the next signing key, shown once, with a bounded overlap.",
+        words: "destinations rotate-key",
+    },
+    {
+        confirms: true,
+        group: "Destinations",
+        // **No `--if-match`, because the registry declares none for it.** Every
+        // other endpoint write accepts a conditional header and this one does not,
+        // so offering the flag here would document a guard the service ignores.
+        operations: ["endpoints.disable"],
+        options: [API_URL, CONFIRM],
+        positionals: [
+            { name: "<destination>", summary: "The destination to disable." },
+        ],
+        summary: "Stop delivering to a destination, keeping its history readable.",
+        words: "destinations disable",
+    },
+    {
+        group: "Destinations",
+        // No confirmation: enabling gives something back rather than taking it
+        // away, and a person who disabled the wrong destination wants it back in
+        // one line, not after a question.
+        operations: ["endpoints.enable"],
+        options: [API_URL],
+        positionals: [
+            { name: "<destination>", summary: "The destination to turn back on." },
+        ],
+        summary: "Resume delivering to a destination that was disabled.",
+        words: "destinations enable",
+    },
+    /* --- Schedules -------------------------------------------------------- */
+    {
+        group: "Schedules",
+        operations: ["schedules.list"],
+        options: [
+            API_URL,
+            {
+                flag: "--endpoint",
+                summary: "Only the schedules that deliver to this destination — everything pointed at it, in one listing.",
+                value: "<destination>",
+            },
+            ...PAGE_OPTIONS,
+        ],
+        positionals: [],
+        summary: "List this project's schedules, or those delivering to one destination.",
+        words: "schedules list",
+    },
+    {
+        group: "Schedules",
+        operations: ["schedules.read"],
+        options: [API_URL],
+        positionals: [{ name: "<schedule>", summary: "The schedule to read." }],
+        summary: "Read a schedule, its recurrence, its version and its ETag.",
+        words: "schedules read",
+    },
+    {
+        group: "Schedules",
+        operations: ["schedules.create"],
+        options: [
+            API_URL,
+            {
+                flag: "--endpoint",
+                summary: "The destination to deliver to.",
+                value: "<destination>",
+            },
+            {
+                flag: "--in",
+                summary: "Once, after a delay: 30s, 5m, 2h, 1d.",
+                value: "<duration>",
+            },
+            {
+                flag: "--at",
+                summary: "Once, at an instant in UTC.",
+                value: "<instant>",
+            },
+            {
+                flag: "--every",
+                summary: "Repeatedly, at this interval: 30s, 5m, 2h, 1d.",
+                value: "<duration>",
+            },
+            {
+                flag: "--cron",
+                summary: "Repeatedly, on a cron expression.",
+                value: "<expression>",
+            },
+            {
+                flag: "--time-zone",
+                summary: "The zone a cron expression is read in, so daylight saving moves the local time rather than the clock time. IANA names, such as Europe/London.",
+                value: "<zone>",
+            },
+            {
+                flag: "--partition-key",
+                summary: "The fairness partition this belongs to.",
+                value: "<key>",
+            },
+            {
+                flag: "--latency-class",
+                summary: "How promptly it must fire: realtime or bulk.",
+                value: "<class>",
+            },
+            {
+                flag: "--data",
+                summary: "The payload: JSON, @file.json, or - for standard input.",
+                value: "<json>",
+            },
+            IDEMPOTENCY,
+        ],
+        positionals: [],
+        summary: "Schedule a delivery, once or repeatedly, and print the first occurrence.",
+        words: "schedules create",
+    },
+    {
+        confirms: true,
+        group: "Schedules",
+        operations: ["schedules.replace"],
+        options: [
+            API_URL,
+            {
+                flag: "--endpoint",
+                summary: "The destination to deliver to.",
+                value: "<destination>",
+            },
+            {
+                flag: "--in",
+                summary: "Once, after a delay: 30s, 5m, 2h, 1d.",
+                value: "<duration>",
+            },
+            {
+                flag: "--at",
+                summary: "Once, at an instant in UTC.",
+                value: "<instant>",
+            },
+            {
+                flag: "--every",
+                summary: "Repeatedly, at this interval: 30s, 5m, 2h, 1d.",
+                value: "<duration>",
+            },
+            {
+                flag: "--cron",
+                summary: "Repeatedly, on a cron expression.",
+                value: "<expression>",
+            },
+            {
+                flag: "--time-zone",
+                summary: "The zone a cron expression is read in, so daylight saving moves the local time rather than the clock time. IANA names, such as Europe/London.",
+                value: "<zone>",
+            },
+            {
+                flag: "--partition-key",
+                summary: "The fairness partition this belongs to.",
+                value: "<key>",
+            },
+            {
+                flag: "--latency-class",
+                summary: "How promptly it must fire: realtime or bulk.",
+                value: "<class>",
+            },
+            {
+                flag: "--data",
+                summary: "The payload: JSON, @file.json, or - for standard input.",
+                value: "<json>",
+            },
+            IF_MATCH,
+            CONFIRM,
+        ],
+        positionals: [{ name: "<schedule>", summary: "The schedule to replace." }],
+        summary: "Replace a schedule's definition, discarding what it said before.",
+        words: "schedules replace",
+    },
+    {
+        group: "Schedules",
+        operations: ["schedules.pause"],
+        options: [API_URL, IF_MATCH],
+        positionals: [{ name: "<schedule>", summary: "The schedule to pause." }],
+        summary: "Stop firing a schedule without discarding it.",
+        words: "schedules pause",
+    },
+    {
+        group: "Schedules",
+        operations: ["schedules.resume"],
+        options: [API_URL, IF_MATCH],
+        positionals: [{ name: "<schedule>", summary: "The schedule to resume." }],
+        summary: "Start a paused schedule firing again.",
+        words: "schedules resume",
+    },
+    {
+        confirms: true,
+        group: "Schedules",
+        operations: ["schedules.cancel"],
+        options: [API_URL, IF_MATCH, CONFIRM],
+        positionals: [{ name: "<schedule>", summary: "The schedule to cancel." }],
+        summary: "Cancel a schedule and everything it had still to deliver.",
+        words: "schedules cancel",
+    },
+    {
+        group: "Schedules",
+        operations: ["schedules.archive"],
+        options: [API_URL, IF_MATCH],
+        positionals: [{ name: "<schedule>", summary: "The schedule to archive." }],
+        summary: "Move a settled schedule out of the working list.",
+        words: "schedules archive",
+    },
+    /* --- Data exports ---------------------------------------------------- */
+    {
+        group: "Data exports",
+        operations: ["exports.create"],
+        options: [API_URL],
+        positionals: [],
+        summary: "Start a bounded export for this project and environment.",
+        words: "exports create",
+    },
+    {
+        group: "Data exports",
+        operations: ["exports.read"],
+        options: [API_URL],
+        positionals: [{ name: "<export>", summary: "The export job to read." }],
+        summary: "Read an export job's progress and cutoff.",
+        words: "exports read",
+    },
+    {
+        group: "Data exports",
+        operations: ["exports.part"],
+        options: [API_URL, PAGE_OPTIONS[0]],
+        positionals: [{ name: "<export>", summary: "The export job to download." }],
+        summary: "Print one bounded NDJSON export part for safe redirection to a file.",
+        words: "exports part",
+    },
+    {
+        confirms: true,
+        group: "Data exports",
+        operations: ["exports.cancel"],
+        options: [API_URL, CONFIRM],
+        positionals: [{ name: "<export>", summary: "The export job to cancel." }],
+        summary: "Permanently cancel an export job.",
+        words: "exports cancel",
+    },
+    /* --- Occurrences and attempts ----------------------------------------- */
+    {
+        group: "Occurrences and attempts",
+        operations: ["occurrences.list"],
+        options: [
+            API_URL,
+            ...PAGE_OPTIONS,
+            {
+                flag: "--newest",
+                summary: "Newest first, which is what a person looking at a schedule wants. A cursor belongs to the order it was issued under.",
+            },
+        ],
+        positionals: [{ name: "<schedule>", summary: "The schedule to list." }],
+        summary: "List the retained occurrences of a schedule.",
+        words: "occurrences list",
+    },
+    {
+        group: "Occurrences and attempts",
+        operations: ["occurrences.read"],
+        options: [API_URL],
+        positionals: [
+            { name: "<schedule>", summary: "The schedule it belongs to." },
+            { name: "<occurrence>", summary: "The occurrence to read." },
+        ],
+        summary: "Read one occurrence and the state it is in.",
+        words: "occurrences read",
+    },
+    {
+        group: "Occurrences and attempts",
+        operations: ["occurrences.read"],
+        options: [
+            API_URL,
+            {
+                flag: "--timeout",
+                summary: "Give up after this long instead of the published deadline.",
+                value: "<duration>",
+            },
+        ],
+        positionals: [
+            { name: "<schedule>", summary: "The schedule it belongs to." },
+            { name: "<occurrence>", summary: "The occurrence to wait for." },
+        ],
+        summary: "Watch an occurrence until it settles, or until the deadline.",
+        words: "occurrences wait",
+    },
+    {
+        confirms: true,
+        group: "Occurrences and attempts",
+        operations: ["occurrences.redeliver"],
+        options: [API_URL, IDEMPOTENCY, CONFIRM],
+        positionals: [
+            { name: "<schedule>", summary: "The schedule it belongs to." },
+            { name: "<occurrence>", summary: "The occurrence to send again." },
+        ],
+        summary: "Deliver an occurrence again to the destination it belongs to.",
+        words: "occurrences redeliver",
+    },
+    {
+        group: "Occurrences and attempts",
+        operations: ["attempts.list"],
+        options: [API_URL, ...PAGE_OPTIONS],
+        positionals: [
+            { name: "<schedule>", summary: "The schedule it belongs to." },
+            { name: "<occurrence>", summary: "The occurrence to list attempts for." },
+        ],
+        summary: "List every delivery attempt, with its diagnosis.",
+        words: "attempts list",
+    },
+    {
+        group: "Occurrences and attempts",
+        operations: ["attempts.read"],
+        options: [API_URL],
+        positionals: [
+            { name: "<schedule>", summary: "The schedule it belongs to." },
+            { name: "<occurrence>", summary: "The occurrence it belongs to." },
+            { name: "<attempt>", summary: "The attempt to read." },
+        ],
+        summary: "Read one attempt in full, including what the receiver answered.",
+        words: "attempts read",
+    },
+    /* --- Planning --------------------------------------------------------- */
+    {
+        group: "Planning",
+        operations: ["forecast.read"],
+        options: [
+            API_URL,
+            {
+                flag: "--from",
+                summary: "The start of the window, in UTC.",
+                value: "<instant>",
+            },
+            {
+                flag: "--to",
+                summary: "The end of the window, in UTC.",
+                value: "<instant>",
+            },
+            {
+                flag: "--bucket",
+                summary: "Bucket width in seconds.",
+                value: "<seconds>",
+            },
+            {
+                flag: "--breakdown",
+                summary: "Group the counts by this dimension.",
+                value: "<dimension>",
+            },
+        ],
+        positionals: [],
+        summary: "Show what is due in a window, and how fresh the answer is.",
+        words: "forecast",
+    },
+    {
+        group: "Planning",
+        operations: ["usage.read"],
+        options: [
+            API_URL,
+            { flag: "--from", summary: "The first day, in UTC.", value: "<instant>" },
+            { flag: "--to", summary: "The last day, in UTC.", value: "<instant>" },
+        ],
+        positionals: [],
+        summary: "Show terminal occurrence volume by day.",
+        words: "usage",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.summary"],
+        options: [API_URL],
+        positionals: [],
+        summary: "Show exact execution credit and effective billing state.",
+        words: "billing",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.funding"],
+        options: [API_URL],
+        positionals: [],
+        summary: "Show execution funding, automatic payment authority and payment outcomes.",
+        words: "billing funding",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.notices"],
+        options: [API_URL, ...PAGE_OPTIONS],
+        positionals: [],
+        summary: "List persistent organization billing notices and delivery state.",
+        words: "billing notices",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.notificationsettings"],
+        options: [API_URL],
+        positionals: [],
+        summary: "Show billing notification policy and its revision.",
+        words: "billing notification-settings",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.notificationsettingsupdate"],
+        options: [
+            API_URL,
+            {
+                flag: "--low-credit",
+                summary: "Send the low-credit notice below this exact USD amount.",
+                value: "<dollars>",
+            },
+            {
+                flag: "--noncritical-email",
+                summary: "Enable or disable email for noncritical notices.",
+                value: "<on|off>",
+            },
+            {
+                flag: "--expected-revision",
+                summary: "Refuse if notification settings have changed.",
+                value: "<revision>",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [],
+        summary: "Update optional billing notifications with approval.",
+        words: "billing update-notifications",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.fundingquote"],
+        options: [
+            API_URL,
+            {
+                flag: "--credit",
+                summary: "Execution credit to buy in USD, at least 10.",
+                value: "<dollars>",
+            },
+        ],
+        positionals: [],
+        summary: "Preview manual execution funding before tax is calculated at checkout.",
+        words: "billing quote-funding",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.purchase"],
+        options: [
+            API_URL,
+            {
+                flag: "--quote",
+                summary: "The exact object returned by quote-funding (the data field in JSON output).",
+                value: "<json|@file|->",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [],
+        summary: "Confirm a manual execution-credit purchase with a stable retry key.",
+        words: "billing purchase",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.ceiling"],
+        options: [
+            API_URL,
+            {
+                flag: "--ceiling",
+                summary: "Set the UTC-month automatic payment ceiling in USD, or turn it off.",
+                value: "<dollars|off>",
+            },
+            {
+                flag: "--expected-revision",
+                summary: "Refuse if automatic payment authority has changed.",
+                value: "<revision>",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [],
+        summary: "Set exact automatic payment authority with approval.",
+        words: "billing ceiling",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.autotopuppreview"],
+        options: [
+            API_URL,
+            {
+                flag: "--action",
+                summary: "Preview enabling, editing, disabling or resuming the rule.",
+                value: "<enable|edit|disable|resume>",
+            },
+            {
+                flag: "--credit",
+                summary: "Fixed execution credit purchased by enable or edit, in USD.",
+                value: "<dollars>",
+            },
+            {
+                flag: "--trigger-below",
+                summary: "Trigger when usable execution credit is below this USD amount.",
+                value: "<dollars>",
+            },
+            {
+                flag: "--ceiling",
+                summary: "Gross automatic-payment ceiling per UTC month, in USD.",
+                value: "<dollars>",
+            },
+            {
+                flag: "--expected-revision",
+                summary: "Refuse if automatic payment authority has changed.",
+                value: "<revision>",
+            },
+        ],
+        positionals: [],
+        summary: "Preview one exact automatic top-up rule without enabling it.",
+        words: "billing preview-topup",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.autotopup"],
+        options: [
+            API_URL,
+            {
+                flag: "--preview",
+                summary: "The exact object returned by preview-topup (the data field in JSON output).",
+                value: "<json|@file|->",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [],
+        summary: "Confirm an automatic top-up preview with a stable retry key.",
+        words: "billing apply-topup",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.refundrequest"],
+        options: [
+            API_URL,
+            {
+                flag: "--payment-operation",
+                summary: "The paid funding operation to review.",
+                value: "<operation>",
+            },
+            {
+                flag: "--amount",
+                summary: "Unused purchased credit requested in USD.",
+                value: "<dollars>",
+            },
+            {
+                flag: "--reason",
+                summary: "Why an operator should review the request.",
+                value: "<text>",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [],
+        summary: "Record a request for operator-reviewed unused-credit refund.",
+        words: "billing refund-request",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.refundresolution"],
+        options: [
+            API_URL,
+            {
+                flag: "--refund-request",
+                summary: "The pending refund request an external operator reviewed.",
+                value: "<request>",
+            },
+            {
+                flag: "--decision",
+                summary: "Record the external review outcome.",
+                value: "<completed|declined>",
+            },
+            {
+                flag: "--provider-refund",
+                summary: "Existing Stripe refund ID required for completion.",
+                value: "<re_...>",
+            },
+            {
+                flag: "--gross",
+                summary: "Existing provider refund gross amount in USD.",
+                value: "<dollars>",
+            },
+            {
+                flag: "--tax",
+                summary: "Tax included in the existing provider refund in USD.",
+                value: "<dollars>",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [],
+        summary: "Record a completed or declined external refund review.",
+        words: "billing resolve-refund",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.budgets"],
+        options: [
+            API_URL,
+            {
+                flag: "--advisory-budget",
+                summary: "Set the monthly advisory amount in USD, or turn it off.",
+                value: "<dollars|off>",
+            },
+            {
+                flag: "--hard-cap",
+                summary: "Set the monthly hard cap in USD, or turn it off.",
+                value: "<dollars|off>",
+            },
+            {
+                flag: "--expected-revision",
+                summary: "Refuse if the budget policy has changed since this revision.",
+                value: "<revision>",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [],
+        summary: "Set exact monthly execution budgets with approval.",
+        words: "billing budgets",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.projects"],
+        options: [API_URL],
+        positionals: [],
+        summary: "Show named project access, payment recovery and monthly fees.",
+        words: "billing projects",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.quote"],
+        options: [
+            API_URL,
+            {
+                flag: "--action",
+                summary: "Preview an addition, cancellation or included transfer.",
+                value: "<add|cancel|transfer-included>",
+            },
+            {
+                flag: "--target-project",
+                summary: "The named project whose billing changes.",
+                value: "<project>",
+            },
+            {
+                flag: "--from-project",
+                summary: "The former included project for a transfer.",
+                value: "<project>",
+            },
+        ],
+        positionals: [],
+        summary: "Preview a named project billing change without authorizing payment.",
+        words: "billing quote-project",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.change"],
+        options: [
+            API_URL,
+            {
+                flag: "--quote",
+                summary: "The exact quote object returned by quote-project (the data field in JSON output).",
+                value: "<json|@file|->",
+            },
+            IDEMPOTENCY,
+            CONFIRM,
+        ],
+        positionals: [],
+        summary: "Confirm an exact project billing quote with a stable retry key.",
+        words: "billing change-project",
+    },
+    {
+        confirms: true,
+        group: "Planning",
+        operations: ["billing.portal"],
+        options: [API_URL, CONFIRM],
+        positionals: [],
+        summary: "Create a hosted payment-method and invoice recovery link.",
+        words: "billing portal",
+    },
+    {
+        group: "Planning",
+        operations: ["billing.ledger"],
+        options: [API_URL, ...PAGE_OPTIONS],
+        positionals: [],
+        summary: "List immutable execution-credit ledger entries.",
+        words: "billing ledger",
+    },
+    {
+        group: "Planning",
+        operations: ["timing.summary"],
+        options: [API_URL],
+        positionals: [],
+        summary: "Show the rolling 24-hour delivery timing cohort.",
+        words: "timing",
+    },
+    /* --- Credentials ------------------------------------------------------ */
+    {
+        group: "Credentials",
+        operations: ["credentials.list"],
+        options: [API_URL, ...PAGE_OPTIONS],
+        positionals: [],
+        summary: "List this project's API credentials, by prefix, never in full.",
+        words: "credentials list",
+    },
+    {
+        confirms: true,
+        group: "Credentials",
+        operations: ["credentials.rotate"],
+        options: [API_URL, CONFIRM],
+        positionals: [
+            { name: "<credential>", summary: "The credential to rotate." },
+        ],
+        summary: "Mint the replacement for a credential, shown once.",
+        words: "credentials rotate",
+    },
+    {
+        confirms: true,
+        group: "Credentials",
+        operations: ["credentials.revoke"],
+        options: [API_URL, CONFIRM],
+        positionals: [
+            { name: "<credential>", summary: "The credential to revoke." },
+        ],
+        summary: "Stop a credential working, everywhere, immediately.",
+        words: "credentials revoke",
+    },
+    /* --- Test sinks ------------------------------------------------------- */
+    {
+        group: "Test sinks",
+        operations: ["testsinks.create"],
+        options: [
+            API_URL,
+            {
+                flag: "--endpoint",
+                summary: "The destination whose deliveries this sink stands in for.",
+                value: "<destination>",
+            },
+            {
+                flag: "--program",
+                summary: "How it should answer from the start: JSON, @file.json, or - for standard input.",
+                value: "<json>",
+            },
+        ],
+        positionals: [],
+        summary: "Create a receiver Greatwait hosts, for a test environment only.",
+        words: "sinks create",
+    },
+    {
+        group: "Test sinks",
+        operations: ["testsinks.list"],
+        options: [API_URL, ...PAGE_OPTIONS],
+        positionals: [],
+        summary: "List the test sinks in this project.",
+        words: "sinks list",
+    },
+    {
+        group: "Test sinks",
+        operations: ["testsinks.read"],
+        options: [API_URL],
+        positionals: [{ name: "<sink>", summary: "The sink to read." }],
+        summary: "Read a test sink and the program it is running.",
+        words: "sinks read",
+    },
+    {
+        group: "Test sinks",
+        operations: ["testsinks.configure"],
+        options: [
+            API_URL,
+            {
+                flag: "--program",
+                summary: "The behaviour program: JSON, @file.json, or - for standard input.",
+                value: "<json>",
+            },
+        ],
+        positionals: [{ name: "<sink>", summary: "The sink to program." }],
+        summary: "Tell a test sink how to answer, so a failure can be reproduced.",
+        words: "sinks configure",
+    },
+    {
+        confirms: true,
+        group: "Test sinks",
+        operations: ["testsinks.delete"],
+        options: [API_URL, CONFIRM],
+        positionals: [{ name: "<sink>", summary: "The sink to delete." }],
+        summary: "Delete a test sink and the deliveries recorded against it.",
+        words: "sinks delete",
+    },
+    {
+        group: "Test sinks",
+        operations: ["sinkdeliveries.list"],
+        options: [API_URL, ...PAGE_OPTIONS],
+        positionals: [{ name: "<sink>", summary: "The sink to list." }],
+        summary: "List what a test sink received.",
+        words: "sinks deliveries",
+    },
+    {
+        group: "Test sinks",
+        operations: ["sinkdeliveries.read"],
+        options: [API_URL],
+        positionals: [
+            { name: "<sink>", summary: "The sink it arrived at." },
+            { name: "<delivery>", summary: "The recorded delivery to read." },
+        ],
+        summary: "Read one recorded delivery, including the bytes that arrived.",
+        words: "sinks delivery",
+    },
+];
+/**
+ * Every operation with no command, and why.
+ *
+ * The first six are the same fact stated six times: they need a browser
+ * session, and a command line holds an API credential or an OAuth grant. That
+ * is a property of the registry entry, so the rule checks it rather than
+ * believing this list — and it is also why the story says credential and grant
+ * operations appear "only where the current principal rules can support them
+ * honestly". Creating a credential from a credential is the escalation the
+ * control plane refuses on purpose.
+ */
+export const OPERATION_OMISSIONS = [
+    {
+        because: "Organization lifecycle authority belongs to a signed-in organization administrator in a browser session. A CLI credential is deliberately project-bound and cannot acquire or widen itself to organization authority.",
+        ground: "principal-unreachable",
+        operation: "organizations.lifecycle",
+    },
+    {
+        because: "Closing an organization requires the signed-in organization administrator session; allowing a project credential to close its parent would widen its authority.",
+        ground: "principal-unreachable",
+        operation: "organizations.close",
+    },
+    {
+        because: "Restoring an organization requires the same signed-in organization administrator session used by the browser recovery flow; project credentials have no organization-wide authority.",
+        ground: "principal-unreachable",
+        operation: "organizations.restore",
+    },
+    {
+        because: "The workspace execution-credit panel is the accepted human control for applying a pending policy; the MCP tool provides the approved automation path.",
+        ground: "declared",
+        operation: "billing.reconcile",
+    },
+    {
+        because: "The endpoint page is the accepted place to mark this human-observed server update done; adding a second interactive CLI design is outside this remediation.",
+        ground: "declared",
+        operation: "endpoints.acknowledgeSigningKeyRotation",
+    },
+    {
+        because: "Minting a credential needs a signed-in person. A command line holding one credential could otherwise mint another, which is the escalation the control plane refuses by declaring a session principal.",
+        ground: "principal-unreachable",
+        operation: "credentials.create",
+    },
+    {
+        because: "Reveals an endpoint's signing secret to a signed-in person on the endpoint's page. A command line holds a credential, and the create and the rotation already hand the secret to a credential once (FXO-2244).",
+        ground: "principal-unreachable",
+        operation: "endpoints.revealSigningSecret",
+    },
+    {
+        because: "Reads the connection detail of a credential for the dashboard, behind a browser session.",
+        ground: "principal-unreachable",
+        operation: "credentials.connection",
+    },
+    {
+        because: "Projects are chosen by a signed-in person; a credential already acts inside exactly one.",
+        ground: "principal-unreachable",
+        operation: "projects.list",
+    },
+    {
+        because: "Creating a project is an act of the account, not of a credential scoped to one.",
+        ground: "principal-unreachable",
+        operation: "projects.create",
+    },
+    {
+        because: "Project General is the accepted rename surface in this story. The generated SDK and MCP expose the operation to automation; adding a second interactive CLI design is outside it.",
+        ground: "declared",
+        operation: "projects.rename",
+    },
+    {
+        because: "Project General is the accepted archive surface in this story. The generated SDK and MCP expose the operation to automation; adding a second interactive CLI design is outside it.",
+        ground: "declared",
+        operation: "projects.archive",
+    },
+    {
+        because: "Permanent project deletion needs the counted confirmation Project General presents. The generated SDK and MCP expose it; a CLI confirmation design is not accepted in this story.",
+        ground: "declared",
+        operation: "projects.delete",
+    },
+    {
+        because: "The Executions page is the accepted project-wide history surface in this story. The generated SDK and MCP expose the operation to automation; adding a second interactive CLI design is outside it.",
+        ground: "declared",
+        operation: "executions.list",
+    },
+    {
+        because: "Grants are what a person gave to an application, and only that person may read them.",
+        ground: "principal-unreachable",
+        operation: "grants.list",
+    },
+    {
+        because: "Revoking a grant is the person's act. `greatwait logout` revokes this command line's own grant, which is the part it holds.",
+        ground: "principal-unreachable",
+        operation: "grants.revoke",
+    },
+    {
+        because: "The contract mock's control plane, not an API operation.",
+        ground: "not-on-the-api",
+        operation: "mock.listFixtures",
+    },
+    {
+        because: "The contract mock's control plane, not an API operation.",
+        ground: "not-on-the-api",
+        operation: "mock.getFixture",
+    },
+    {
+        because: "The contract mock's control plane, not an API operation.",
+        ground: "not-on-the-api",
+        operation: "mock.setScenario",
+    },
+    {
+        because: "Reports which workspace layer a service occupies, so the architecture boundary is observable at runtime. It answers a question about the build rather than about anything a person operates, and `greatwait doctor` already reports the build it reached.",
+        ground: "declared",
+        operation: "meta.scaffold",
+    },
+    {
+        because: "A transitional shape kept for one migrating consumer and scheduled for withdrawal. `greatwait forecast` reads the same data in the shape this product publishes, and a command line built on the shape being withdrawn would have to be rewritten when it goes.",
+        ground: "declared",
+        operation: "forecast.windows",
+    },
+];
+/* -------------------------------------------------------------------------- */
+/* Rendering                                                                  */
+/* -------------------------------------------------------------------------- */
+/**
+ * The one-line spelling of a command, used by `--help` and by the reference.
+ *
+ * **Rendered from the declaration in both places rather than written twice.**
+ * The story asks that the reference be generated or exhaustively checked
+ * against the executable; sharing the renderer is the version of that with
+ * nothing to check, because a page and a help screen produced by the same
+ * function cannot disagree about what a command takes.
+ */
+export function usageLine(command, programName = CANONICAL_PROGRAM_NAME) {
+    return [
+        programName,
+        command.words,
+        ...command.positionals.map((positional) => positional.optional === true && !positional.name.startsWith("[")
+            ? `[${positional.name}]`
+            : positional.name),
+        ...command.options.map((option) => option.value === undefined
+            ? `[${option.flag}]`
+            : `[${option.flag} ${option.value}]`),
+    ].join(" ");
+}
+/** The help for one command: what it does, what it takes, what each means. */
+export function commandHelp(command, programName = CANONICAL_PROGRAM_NAME) {
+    const width = Math.max(0, ...command.positionals.map((positional) => positional.name.length), ...command.options.map((option) => option.flag.length +
+        (option.value === undefined ? 0 : option.value.length + 1)));
+    const rows = [
+        ...command.positionals.map((positional) => [positional.name, positional.summary]),
+        ...command.options.map((option) => [
+            option.value === undefined
+                ? option.flag
+                : `${option.flag} ${option.value}`,
+            option.summary,
+        ]),
+    ];
+    return [
+        usageLine(command, programName),
+        ``,
+        command.summary,
+        ...(rows.length === 0 ? [] : [``]),
+        ...rows.map(([name, summary]) => `  ${name.padEnd(width)}  ${summary}`),
+    ].join("\n");
+}
+/** Every command, grouped, for the overview `--help` prints. */
+export function overview(commands = COMMAND_CATALOG) {
+    const groups = [];
+    const width = Math.max(...commands.map((command) => command.words.length));
+    for (const command of commands) {
+        if (groups[groups.length - 1] !== command.group)
+            groups.push(command.group);
+    }
+    return [...new Set(groups)]
+        .map((group) => [
+        `${group}`,
+        ...commands
+            .filter((command) => command.group === group)
+            .map((command) => `  ${command.words.padEnd(width)}  ${command.summary}`),
+    ].join("\n"))
+        .join("\n\n");
+}
+/**
+ * The scopes `login` asks a person to grant.
+ *
+ * **Derived from what the commands actually call.** A list maintained beside
+ * the catalog is a list that goes stale in the direction nobody notices: a
+ * command added for an operation needing a scope nobody requested fails at
+ * runtime with `scope_missing`, against a grant the person cannot widen without
+ * signing in again. Deriving it also means a widening shows up in the generated
+ * reference's diff, which is where a reviewer will see it.
+ */
+export function requestedScopes(inputs) {
+    const byId = new Map(inputs.operations.map((operation) => [operation.id, operation]));
+    const scopes = new Set();
+    for (const command of inputs.commands) {
+        for (const id of command.operations) {
+            for (const scope of byId.get(id)?.scopes ?? [])
+                scopes.add(scope);
+        }
+    }
+    return [...scopes].sort();
+}
+/**
+ * Everything wrong with the declarations, as sentences.
+ *
+ * A pure function of its inputs so the cases below can hand it a catalog that
+ * violates one rule at a time. Empty means the CLI, its reference and the
+ * registry agree.
+ */
+export function coverageProblems(inputs) {
+    const problems = [];
+    const byId = new Map(inputs.operations.map((operation) => [operation.id, operation]));
+    // **One flag cannot be valued on one command and bare on another.** The
+    // parser runs *before* the dispatcher picks a command — it has to, because a
+    // flag may precede the command words — so value-ness is a property of the
+    // name across the whole catalog rather than of the command. Two commands
+    // disagreeing about it would silently corrupt one of them: a bare flag would
+    // swallow the next token, or a valued one would drop its value into the
+    // positionals. Nothing else in the repository looks at this, and no command
+    // today gets it wrong, which is the moment to write the rule down.
+    const valueness = new Map();
+    for (const command of inputs.commands) {
+        for (const option of command.options) {
+            const takesValue = option.value !== undefined;
+            const seen = valueness.get(option.flag);
+            if (seen !== undefined && seen !== takesValue) {
+                problems.push(`${option.flag} takes a value on one command and not on another`);
+            }
+            valueness.set(option.flag, takesValue);
+        }
+    }
+    const seenWords = new Set();
+    for (const command of inputs.commands) {
+        const parts = command.words.split(" ");
+        if (parts.length < 1 || parts.length > 2) {
+            problems.push(`${command.words} is not one or two words, and the dispatcher looks up no more than two`);
+        }
+        if (seenWords.has(command.words)) {
+            problems.push(`two commands are declared as ${command.words}`);
+        }
+        seenWords.add(command.words);
+        const flags = new Set();
+        for (const option of command.options) {
+            if (!option.flag.startsWith("--")) {
+                problems.push(`${command.words} declares ${option.flag}, which is not an option`);
+            }
+            if (flags.has(option.flag)) {
+                problems.push(`${command.words} declares ${option.flag} twice`);
+            }
+            flags.add(option.flag);
+        }
+        // **A command that asks must publish the way to answer without a
+        // terminal.** Otherwise automation meets the prompt policy's refusal with
+        // no documented flag to satisfy it, and the reference page is where
+        // somebody looks for one.
+        if (command.confirms === true && !flags.has("--yes")) {
+            problems.push(`${command.words} confirms and does not declare --yes`);
+        }
+        for (const id of command.operations) {
+            const operation = byId.get(id);
+            if (operation === undefined) {
+                problems.push(`${command.words} covers ${id}, which the registry does not declare`);
+                continue;
+            }
+            if (!reachableByCli(operation)) {
+                problems.push(`${command.words} covers ${id}, which no principal a command line can hold may call`);
+            }
+            if (!servedByApi(operation)) {
+                problems.push(`${command.words} covers ${id}, which the API does not serve`);
+            }
+            const ground = confirmationGround(operation);
+            if (ground !== undefined && command.confirms !== true) {
+                problems.push(`${command.words} covers ${id}, which is ${ground}, and does not confirm`);
+            }
+            // **Both directions, because each is a different lie.** A command that
+            // covers a conditional operation and offers no `--if-match` flattens
+            // optimistic concurrency out of the surface: the only way to act on a
+            // schedule somebody else may have moved becomes last-writer-wins. And a
+            // required idempotency header the command line never lets anybody supply
+            // makes a safe retry impossible to spell.
+            const headers = declaredRequestHeaders(operation);
+            if (headers.includes("If-Match") && !flags.has("--if-match")) {
+                problems.push(`${command.words} covers ${id}, which takes If-Match, and does not offer --if-match`);
+            }
+            if (headers.includes("Idempotency-Key") &&
+                !flags.has("--idempotency-key")) {
+                problems.push(`${command.words} covers ${id}, which takes Idempotency-Key, and does not offer --idempotency-key`);
+            }
+        }
+        // The other way round: a flag with nothing behind it. An option documented
+        // on a command whose operations declare no such header is one somebody
+        // passes, watches be ignored, and reports as a bug in the service.
+        for (const [flag, header] of [
+            ["--if-match", "If-Match"],
+            ["--idempotency-key", "Idempotency-Key"],
+        ]) {
+            if (!flags.has(flag))
+                continue;
+            const supported = command.operations.some((id) => {
+                const operation = byId.get(id);
+                return (operation !== undefined &&
+                    declaredRequestHeaders(operation).includes(header));
+            });
+            if (!supported) {
+                problems.push(`${command.words} offers ${flag} and reaches no operation that takes ${header}`);
+            }
+        }
+    }
+    const covered = new Set(inputs.commands.flatMap((command) => command.operations));
+    const omitted = new Map();
+    for (const omission of inputs.omissions) {
+        const operation = byId.get(omission.operation);
+        if (operation === undefined) {
+            problems.push(`${omission.operation} is omitted, and the registry does not declare it`);
+            continue;
+        }
+        if (omitted.has(omission.operation)) {
+            problems.push(`${omission.operation} is omitted twice`);
+        }
+        omitted.set(omission.operation, omission);
+        if (covered.has(omission.operation)) {
+            problems.push(`${omission.operation} is both covered by a command and omitted`);
+        }
+        if (omission.because.trim().length < 20) {
+            problems.push(`${omission.operation} is omitted with no stated reason`);
+        }
+        // **The two derived grounds are checked, not believed.** A claim that an
+        // operation is out of reach stays true only while the registry says so, and
+        // the day a session-only operation gains an API-credential principal is the
+        // day this omission becomes a missing command nobody is looking for.
+        if (omission.ground === "principal-unreachable" &&
+            reachableByCli(operation)) {
+            problems.push(`${omission.operation} is omitted as principal-unreachable and a command line can call it`);
+        }
+        if (omission.ground === "not-on-the-api" && servedByApi(operation)) {
+            problems.push(`${omission.operation} is omitted as not-on-the-api and the API serves it`);
+        }
+        if (omission.ground === "declared" &&
+            (!reachableByCli(operation) || !servedByApi(operation))) {
+            problems.push(`${omission.operation} is omitted as a product decision and the registry already explains it — state the accurate ground`);
+        }
+    }
+    for (const operation of inputs.operations) {
+        if (covered.has(operation.id) || omitted.has(operation.id))
+            continue;
+        problems.push(`${operation.id} has no command and no stated reason for having none`);
+    }
+    return problems;
+}
+/** The declarations as they stand, against the real registry. */
+export function catalogInputs() {
+    return {
+        commands: COMMAND_CATALOG,
+        omissions: OPERATION_OMISSIONS,
+        operations: OPERATIONS,
+    };
+}
+/**
+ * The scopes `login` asks for, from what the commands call.
+ *
+ * Asking for everything the server offers would be asking a person to grant a
+ * command line permissions it has no code to use; asking for less than the
+ * commands need is a `scope_missing` on a grant they cannot widen without
+ * signing in again. Neither is a list anybody maintains: this is that union.
+ */
+export const REQUESTED_SCOPES = requestedScopes(catalogInputs());
+/**
+ * Re-exported so the reference generator has one import.
+ *
+ * The page publishes the exit numbers and what they mean, and both come from
+ * the module the runtime reads. A generator reaching into `./exit` separately
+ * would work; this keeps the catalog the single thing a projection depends on.
+ */
+export { EXIT_CLASSES, EXIT_CLASS_MEANINGS };