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

package/dist/operate.js

@@ -0,0 +1,1394 @@
+import { billingAutoTopUpApplyRequestSchema, billingAutoTopUpPreviewRequestSchema, billingAutoTopUpPreviewSchema, billingCeilingUpdateRequestSchema, billingFundingQuoteRequestSchema, billingFundingQuoteSchema, billingNotificationSettingsUpdateRequestSchema, billingRefundRequestCreateSchema, billingRefundResolutionRequestSchema, projectBillingQuoteSchema, projectBillingQuoteRequestSchema, } from "@greatwait/contracts";
+import { parseDuration } from "./args.js";
+import { confirmChange } from "./confirm.js";
+import { redactSecret } from "./output.js";
+import { CliError } from "./runtime.js";
+import { openSession } from "./session.js";
+import { apiUrlOption, conditionalHeaders, continuationNote, drainPages, freshnessNote, pageRequest, parseInstant, parseResponse, positionals, readJsonOption, table, } from "./support.js";
+/* -------------------------------------------------------------------------- */
+/* Shared plumbing                                                            */
+/* -------------------------------------------------------------------------- */
+async function session(runtime, args) {
+    return openSession(runtime, { apiUrl: apiUrlOption(args) });
+}
+/**
+ * A listing, from one page or from all of them, rendered the same way.
+ *
+ * The freshness of a projection is reported rather than dropped: a cross
+ * partition listing may lag, and the contract says so in every page. A command
+ * that showed the rows and not the age would present a stale answer as fact,
+ * which is the failure the field exists to prevent.
+ */
+async function listing(runtime, args, options) {
+    const drained = await drainPages(runtime, args, pageRequest(args), options.read);
+    const notes = [
+        continuationNote(drained, options.command),
+        freshnessNote(drained.freshness),
+    ].filter((note) => note !== undefined);
+    return {
+        data: {
+            ceilingReached: drained.ceilingReached,
+            freshness: drained.freshness,
+            ...(drained.nextCursor === undefined
+                ? {}
+                : { nextCursor: drained.nextCursor }),
+            pages: drained.pages,
+            rows: drained.rows,
+        },
+        human: table(options.columns, drained.rows.map(options.row), options.empty),
+        ...(notes.length === 0 ? {} : { nextMove: notes.join("\n") }),
+    };
+}
+/** A page read through the client, validated against the published shape. */
+async function page(operation, call) {
+    return parseResponse(operation, await call());
+}
+/** The freshness a single read reported, where it reports one. */
+function freshnessOf(view) {
+    return view.freshness ?? { kind: "authoritative" };
+}
+/**
+ * The idempotency key for a mutation, generated when it was not given.
+ *
+ * Printed either way. A create that silently invented a fresh key on every run
+ * would make a retry a second delivery, which is the failure the key exists to
+ * prevent; one that hid the key would leave the caller unable to make that
+ * retry at all.
+ */
+function idempotencyKey(runtime, args) {
+    return (args.options["--idempotency-key"] ?? `greatwait-cli-${runtime.randomUuid()}`);
+}
+/* -------------------------------------------------------------------------- */
+/* The schedule request, shared by create and replace                         */
+/* -------------------------------------------------------------------------- */
+/** The recurrence flags, exactly one of which must be given. */
+const RECURRENCE_FLAGS = ["--in", "--at", "--every", "--cron"];
+/**
+ * A schedule definition from the command line.
+ *
+ * **One recurrence, named explicitly.** The four spellings are the four the
+ * contract publishes, and giving none or giving two is refused here rather than
+ * sent: "you gave --in and --cron" is a sentence about the line somebody typed,
+ * and `invalid_request` a round trip later is not.
+ *
+ * `--time-zone` is what keeps daylight saving honest. A cron expression without
+ * one fires on a fixed offset, so "every weekday at 09:00" drifts an hour twice
+ * a year; with one, the service moves the instant and the local time stays put.
+ * The command line does not choose a default zone, because guessing the
+ * machine's would make the same expression mean different things on a laptop
+ * and on a build runner.
+ */
+async function scheduleRequest(runtime, args, usage) {
+    const given = RECURRENCE_FLAGS.filter((flag) => args.options[flag] !== undefined);
+    if (given.length !== 1) {
+        throw new CliError(given.length === 0
+            ? "give one of --in, --at, --every or --cron"
+            : `give one recurrence, not ${given.join(" and ")}`, "usage", `Usage: ${usage}`);
+    }
+    const only = given[0];
+    const value = args.options[only];
+    const timeZone = args.options["--time-zone"];
+    if (timeZone !== undefined && only !== "--cron") {
+        // Refused rather than ignored: somebody who passed a zone believes it is
+        // doing something, and on `--at` or `--in` there is no local time for it to
+        // mean anything about.
+        throw new CliError("--time-zone only means something with --cron", "usage", "An instant and a delay are absolute already; a cron expression is the one that names a local time.");
+    }
+    const recurrence = only === "--in"
+        ? { delaySeconds: parseDuration(value) }
+        : only === "--at"
+            ? { at: parseInstant(value) }
+            : only === "--every"
+                ? { everySeconds: parseDuration(value) }
+                : { cron: value };
+    const endpoint = args.options["--endpoint"];
+    const data = await readJsonOption(runtime, "--data", args.options["--data"]);
+    const latencyClass = args.options["--latency-class"];
+    const partitionKey = args.options["--partition-key"];
+    return {
+        ...(data === undefined ? {} : { data }),
+        ...(endpoint === undefined ? {} : { endpoint }),
+        ...(latencyClass === undefined ? {} : { latencyClass }),
+        ...(partitionKey === undefined ? {} : { partitionKey }),
+        ...(timeZone === undefined ? {} : { timeZone }),
+        ...recurrence,
+    };
+}
+/** How a schedule's recurrence reads in one column. */
+function recurrenceOf(schedule) {
+    return schedule.recurrence.kind;
+}
+/* -------------------------------------------------------------------------- */
+/* Destinations                                                               */
+/* -------------------------------------------------------------------------- */
+const destinationsList = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        columns: ["STATUS", "NAME", "URL", "DESTINATION"],
+        command: `${runtime.programName} destinations list`,
+        empty: "This project has no destinations yet.",
+        read: (request) => page("endpoints.list", () => active.client.request("endpoints_list", request)),
+        row: (endpoint) => [
+            endpoint.status,
+            endpoint.name ?? endpoint.url,
+            endpoint.url,
+            endpoint.id,
+        ],
+    });
+};
+/** One destination, rendered the way both read and the writes report it. */
+function endpointBlock(endpoint) {
+    return [
+        `Destination  ${endpoint.id}`,
+        `Status       ${endpoint.status}`,
+        `URL          ${endpoint.url}`,
+        `Version      ${String(endpoint.version)}`,
+        `Signing key  ${endpoint.signingKeys.current}`,
+        ...(endpoint.signingKeys.next === undefined
+            ? []
+            : [
+                `Next key     ${endpoint.signingKeys.next.id}, accepted alongside the current one until ${endpoint.signingKeys.next.overlapEndsAt}`,
+            ]),
+    ];
+}
+const destinationsRead = async (runtime, args) => {
+    const [id] = positionals(args, ["<destination>"], `${runtime.programName} destinations read <destination>`);
+    const active = await session(runtime, args);
+    const answer = await active.client.requestDetailed("endpoints_read", id);
+    const endpoint = parseResponse("endpoints.read", answer.body);
+    const etag = answer.headers["ETag"];
+    return {
+        data: { ...(etag === undefined ? {} : { etag }), endpoint },
+        human: [
+            ...endpointBlock(endpoint),
+            ...(etag === undefined ? [] : [`ETag         ${etag}`]),
+        ].join("\n"),
+        ...(etag === undefined
+            ? {}
+            : {
+                nextMove: "Pass that ETag as --if-match on a later update or rotation to be refused rather than overwrite a change somebody else made.",
+            }),
+    };
+};
+const destinationsUpdate = async (runtime, args) => {
+    const [id] = positionals(args, ["<destination>"], `${runtime.programName} destinations update <destination> --url <https url>`);
+    const url = args.options["--url"];
+    if (url === undefined) {
+        throw new CliError(`${runtime.programName} destinations update needs --url`, "usage", `Usage: ${runtime.programName} destinations update <destination> --url https://your-receiver.example.com/greatwait`);
+    }
+    const active = await session(runtime, args);
+    // Read first, so the preview is the destination as it stands rather than the
+    // arguments read back.
+    const current = parseResponse("endpoints.read", await active.client.request("endpoints_read", id));
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Point destination ${current.id} at a different receiver.`,
+        effect: [
+            `now      ${current.url}`,
+            `after    ${url}`,
+            `Deliveries in flight keep going to the receiver they started for.`,
+        ],
+    });
+    const updated = parseResponse("endpoints.update", await active.client.request("endpoints_update", id, { url }, conditionalHeaders(args)));
+    return {
+        data: { confirmation, endpoint: updated },
+        human: endpointBlock(updated).join("\n"),
+    };
+};
+const destinationsRotateKey = async (runtime, args) => {
+    const [id] = positionals(args, ["<destination>"], `${runtime.programName} destinations rotate-key <destination>`);
+    const active = await session(runtime, args);
+    const current = parseResponse("endpoints.read", await active.client.request("endpoints_read", id));
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Mint the next signing key for destination ${current.id}.`,
+        effect: [
+            `current key  ${current.signingKeys.current}`,
+            `The new secret is shown once here and cannot be recovered afterwards.`,
+            `Your receiver must accept both keys until the overlap ends, or it will`,
+            `reject callbacks signed with the new one.`,
+        ],
+    });
+    const rotated = parseResponse("endpoints.rotateSigningKey", await active.client.request("endpoints_rotateSigningKey", id, {}, conditionalHeaders(args)));
+    const overlapEndsAt = rotated.endpoint.signingKeys.next?.overlapEndsAt;
+    return {
+        // **The secret is here and in no later output.** The service returns it
+        // from this call and from no other, so printing it once with the warning is
+        // the only place it can honestly appear.
+        data: {
+            confirmation,
+            endpoint: rotated.endpoint,
+            keyId: rotated.keyId,
+            secret: rotated.secret,
+        },
+        human: [
+            `Destination  ${rotated.endpoint.id}`,
+            `New key      ${rotated.keyId}`,
+            ...(overlapEndsAt === undefined ? [] : [`Overlap ends ${overlapEndsAt}`]),
+            ``,
+            `Signing key  ${rotated.secret}`,
+            ``,
+            `This key is shown once and is not recoverable. Add it to your receiver's`,
+            `accepted set now, alongside the current one; reading this destination back`,
+            `will show ${redactSecret(rotated.secret)} instead.`,
+        ].join("\n"),
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Schedules                                                                  */
+/* -------------------------------------------------------------------------- */
+const schedulesList = async (runtime, args) => {
+    const active = await session(runtime, args);
+    const endpoint = args.options["--endpoint"];
+    return listing(runtime, args, {
+        columns: ["STATUS", "NAME", "RECURRENCE", "DELIVERS TO", "SCHEDULE"],
+        command: `${runtime.programName} schedules list${endpoint === undefined ? "" : ` --endpoint ${endpoint}`}`,
+        empty: endpoint === undefined
+            ? "This project has no schedules yet."
+            : "No schedule delivers to that destination.",
+        read: (request) => page("schedules.list", () => active.client.request("schedules_list", {
+            ...request,
+            ...(endpoint === undefined ? {} : { endpoint }),
+        })),
+        row: (schedule) => [
+            schedule.status,
+            schedule.name ?? "—",
+            recurrenceOf(schedule),
+            schedule.endpointUrl ?? schedule.endpoint ?? "—",
+            schedule.id,
+        ],
+    });
+};
+/**
+ * A schedule lifecycle change: read, preview where one is owed, act, report.
+ *
+ * The five that share this — replace, pause, resume, cancel, archive — differ
+ * only in what they send and what they say afterwards, and writing each one out
+ * separately is how two of them end up handling `If-Match` differently.
+ */
+async function scheduleChange(runtime, args, options) {
+    const active = await session(runtime, args);
+    let confirmation;
+    if (options.confirm !== undefined) {
+        const current = parseResponse("schedules.read", await active.client.request("schedules_read", options.id)).schedule;
+        confirmation = await confirmChange(runtime, args, options.confirm(current));
+    }
+    const answer = await options.act(active, options.id);
+    const view = parseResponse(options.operation, answer.body);
+    const nextMove = options.nextMove?.(view.schedule);
+    return {
+        data: {
+            ...(confirmation === undefined ? {} : { confirmation }),
+            ...(view.occurrence === undefined ? {} : { occurrence: view.occurrence }),
+            schedule: view.schedule,
+        },
+        human: [
+            `Schedule     ${view.schedule.id}`,
+            `Status       ${view.schedule.status}`,
+            `Recurrence   ${recurrenceOf(view.schedule)}`,
+            `Version      ${String(view.schedule.version)}`,
+            ...(view.occurrence === undefined
+                ? []
+                : [
+                    `Next         ${view.occurrence.id} planned for ${view.occurrence.plannedFor} (${view.occurrence.state})`,
+                ]),
+        ].join("\n"),
+        ...(nextMove === undefined ? {} : { nextMove }),
+    };
+}
+const schedulesReplace = async (runtime, args) => {
+    const usage = `${runtime.programName} schedules replace <schedule> --endpoint <destination> (--in <duration> | --at <instant> | --every <duration> | --cron <expression>)`;
+    const [id] = positionals(args, ["<schedule>"], usage);
+    const request = await scheduleRequest(runtime, args, usage);
+    return scheduleChange(runtime, args, {
+        act: (active, scheduleId) => active.client.requestDetailed("schedules_replace", scheduleId, request, conditionalHeaders(args)),
+        confirm: (current) => ({
+            action: `Replace the definition of schedule ${current.id}.`,
+            effect: [
+                `now      ${recurrenceOf(current)}, ${current.status}, version ${String(current.version)}`,
+                `after    the definition on this command line, and nothing of the old one`,
+                `Occurrences already planned under the old definition are discarded.`,
+            ],
+        }),
+        id: id,
+        nextMove: (schedule) => `Read it back with: ${runtime.programName} schedules read ${schedule.id}`,
+        operation: "schedules.replace",
+    });
+};
+const schedulesPause = async (runtime, args) => scheduleChange(runtime, args, {
+    act: (active, id) => active.client.requestDetailed("schedules_pause", id, conditionalHeaders(args)),
+    id: positionals(args, ["<schedule>"], `${runtime.programName} schedules pause <schedule>`)[0],
+    nextMove: (schedule) => `Nothing fires until it is resumed: ${runtime.programName} schedules resume ${schedule.id}`,
+    operation: "schedules.pause",
+});
+const schedulesResume = async (runtime, args) => scheduleChange(runtime, args, {
+    act: (active, id) => active.client.requestDetailed("schedules_resume", id, conditionalHeaders(args)),
+    id: positionals(args, ["<schedule>"], `${runtime.programName} schedules resume <schedule>`)[0],
+    operation: "schedules.resume",
+});
+const schedulesCancel = async (runtime, args) => scheduleChange(runtime, args, {
+    act: (active, id) => active.client.requestDetailed("schedules_cancel", id, conditionalHeaders(args)),
+    confirm: (current) => ({
+        action: `Cancel schedule ${current.id}.`,
+        effect: [
+            `recurrence   ${recurrenceOf(current)}`,
+            `status       ${current.status}`,
+            `Everything it had still to deliver is discarded. This cannot be undone;`,
+            `pause instead if you may want it back.`,
+        ],
+    }),
+    id: positionals(args, ["<schedule>"], `${runtime.programName} schedules cancel <schedule>`)[0],
+    nextMove: () => `Attempts already recorded stay readable: ${runtime.programName} occurrences list <schedule>`,
+    operation: "schedules.cancel",
+});
+const schedulesArchive = async (runtime, args) => scheduleChange(runtime, args, {
+    act: (active, id) => active.client.requestDetailed("schedules_archive", id, conditionalHeaders(args)),
+    id: positionals(args, ["<schedule>"], `${runtime.programName} schedules archive <schedule>`)[0],
+    operation: "schedules.archive",
+});
+/* -------------------------------------------------------------------------- */
+/* Occurrences and attempts                                                   */
+/* -------------------------------------------------------------------------- */
+const occurrencesList = async (runtime, args) => {
+    const [schedule] = positionals(args, ["<schedule>"], `${runtime.programName} occurrences list <schedule>`);
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        columns: ["STATE", "PLANNED FOR", "OCCURRENCE", "ATTEMPTS"],
+        command: `${runtime.programName} occurrences list ${schedule}`,
+        empty: "This schedule has no retained occurrences.",
+        read: (request) => page("occurrences.list", () => active.client.request("occurrences_list", schedule, {
+            ...request,
+            ...(args.booleans.has("--newest")
+                ? { order: "newest" }
+                : {}),
+        })),
+        row: (occurrence) => [
+            occurrence.state,
+            occurrence.plannedFor,
+            occurrence.id,
+            String(occurrence.attemptCount),
+        ],
+    });
+};
+const occurrencesRead = async (runtime, args) => {
+    const [schedule, occurrence] = positionals(args, ["<schedule>", "<occurrence>"], `${runtime.programName} occurrences read <schedule> <occurrence>`);
+    const active = await session(runtime, args);
+    const view = parseResponse("occurrences.read", await active.client.request("occurrences_read", schedule, occurrence));
+    return {
+        data: { freshness: freshnessOf(view), occurrence: view.occurrence },
+        human: [
+            `Occurrence   ${view.occurrence.id}`,
+            `State        ${view.occurrence.state}`,
+            `Planned for  ${view.occurrence.plannedFor}`,
+            `Attempts     ${String(view.occurrence.attemptCount)}`,
+            ...(view.occurrence.settledAt === undefined
+                ? []
+                : [`Settled      ${view.occurrence.settledAt}`]),
+        ].join("\n"),
+        nextMove: `See what happened: ${runtime.programName} attempts list ${schedule} ${occurrence}`,
+    };
+};
+const occurrencesRedeliver = async (runtime, args) => {
+    const [schedule, occurrence] = positionals(args, ["<schedule>", "<occurrence>"], `${runtime.programName} occurrences redeliver <schedule> <occurrence>`);
+    const active = await session(runtime, args);
+    const current = parseResponse("occurrences.read", await active.client.request("occurrences_read", schedule, occurrence)).occurrence;
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Deliver occurrence ${current.id} again.`,
+        effect: [
+            `state        ${current.state}`,
+            `attempts     ${String(current.attemptCount)} already made`,
+            `Your receiver gets this payload a second time. If the first attempt was`,
+            `ambiguous it may already have processed it, so redelivery is safe only`,
+            `where the receiver is idempotent.`,
+        ],
+    });
+    // **The key is required rather than optional here**, which is why it is
+    // generated when nobody supplied one: the contract declares it mandatory for
+    // redelivery precisely so a repeated call cannot become a third delivery.
+    const key = idempotencyKey(runtime, args);
+    const view = parseResponse("occurrences.redeliver", await active.client.request("occurrences_redeliver", schedule, occurrence, { "Idempotency-Key": key }));
+    return {
+        data: { attempt: view.attempt, confirmation, idempotencyKey: key },
+        human: [
+            `Attempt      ${view.attempt.id}`,
+            `Number       ${String(view.attempt.attemptNumber)}`,
+            `Started      ${view.attempt.startedAt}`,
+            `Retry key    ${key}`,
+        ].join("\n"),
+        nextMove: `Watch it settle: ${runtime.programName} occurrences wait ${schedule} ${occurrence}`,
+    };
+};
+const attemptsRead = async (runtime, args) => {
+    const [schedule, occurrence, attempt] = positionals(args, ["<schedule>", "<occurrence>", "<attempt>"], `${runtime.programName} attempts read <schedule> <occurrence> <attempt>`);
+    const active = await session(runtime, args);
+    const view = parseResponse("attempts.read", await active.client.request("attempts_read", schedule, occurrence, attempt));
+    const found = view.attempt;
+    return {
+        data: { attempt: found, freshness: freshnessOf(view) },
+        human: [
+            `Attempt      ${found.id}`,
+            `Number       ${String(found.attemptNumber)}`,
+            ...(found.state === undefined ? [] : [`State        ${found.state}`]),
+            `Trigger      ${found.trigger.kind}${found.trigger.sourceAttemptId === undefined ? "" : ` of ${found.trigger.sourceAttemptId}`}`,
+            `Started      ${found.startedAt}`,
+            ...(found.durationMs === undefined
+                ? []
+                : [`Took         ${String(found.durationMs)}ms`]),
+            ...(found.responseStatus === undefined
+                ? [`Response     none recorded`]
+                : [`Response     ${String(found.responseStatus)}`]),
+            ...(found.diagnostic === undefined
+                ? []
+                : [`Diagnosis    ${found.diagnostic}`]),
+            ...(found.remediation === undefined
+                ? []
+                : [`Remedy       ${found.remediation}`]),
+            `Delivery     ${found.delivery}`,
+        ].join("\n"),
+        ...(found.remediation === "review_before_redelivery"
+            ? {
+                nextMove: "This attempt was ambiguous: the receiver may have processed it even though Greatwait never saw an answer. Check the receiver before redelivering.",
+            }
+            : {}),
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Planning                                                                   */
+/* -------------------------------------------------------------------------- */
+/** The `--from` and `--to` window, normalised the way the contract spells it. */
+function window(args) {
+    const from = args.options["--from"];
+    const to = args.options["--to"];
+    return {
+        ...(from === undefined ? {} : { from: parseInstant(from, "--from") }),
+        ...(to === undefined ? {} : { to: parseInstant(to, "--to") }),
+    };
+}
+const forecast = async (runtime, args) => {
+    const active = await session(runtime, args);
+    const bucket = args.options["--bucket"];
+    const breakdown = args.options["--breakdown"];
+    const view = parseResponse("forecast.read", await active.client.request("forecast_read", {
+        ...(breakdown === undefined ? {} : { breakdown }),
+        ...(bucket === undefined ? {} : { bucketSeconds: Number(bucket) }),
+        ...window(args),
+    }));
+    const total = view.buckets.reduce((sum, bucket_) => sum + bucket_.count, 0);
+    return {
+        data: view,
+        human: [
+            `Window       ${view.window.from} to ${view.window.to}, in ${String(view.window.bucketSeconds)}s buckets`,
+            `Due          ${String(total)}`,
+            ``,
+            table(["FROM", "DUE", "FIRST FIRE"], view.buckets.map((bucket_) => [
+                bucket_.start,
+                String(bucket_.count),
+                String(bucket_.nextFireCount),
+            ]), "Nothing is due in this window."),
+        ].join("\n"),
+        // **The forecast is always a projection**, so its age is not an aside: a
+        // plan made from a number ninety seconds old is a different plan from one
+        // made from a number ninety minutes old, and only one of those is visible
+        // without this line.
+        ...(freshnessNote(view.freshness) === undefined
+            ? {}
+            : { nextMove: freshnessNote(view.freshness) }),
+    };
+};
+const usage = async (runtime, args) => {
+    const active = await session(runtime, args);
+    const view = parseResponse("usage.read", await active.client.request("usage_read", window(args)));
+    return {
+        data: view,
+        human: [
+            `Window       ${view.window.from} to ${view.window.to}`,
+            `Occurrences  ${String(view.totalBillableOccurrences)}`,
+            ``,
+            table(["DAY", "TERMINAL", "BY OUTCOME"], view.days.map((day) => [
+                day.start,
+                String(day.billableOccurrences),
+                Object.entries(day.byTerminalState)
+                    .map(([state, count]) => `${state} ${String(count)}`)
+                    .join(", "),
+            ]), "No terminal occurrences in this window."),
+        ].join("\n"),
+        ...(freshnessNote(view.freshness) === undefined
+            ? {}
+            : { nextMove: freshnessNote(view.freshness) }),
+    };
+};
+/** Exact fixed-scale rendering without converting ledger money to Number. */
+function money(amount) {
+    const value = BigInt(amount.microdollars);
+    const negative = value < 0n;
+    const absolute = negative ? -value : value;
+    const divisor = 10n ** BigInt(amount.scale);
+    return `${negative ? "-" : ""}$${String(absolute / divisor)}.${String(absolute % divisor).padStart(amount.scale, "0")}`;
+}
+const billing = async (runtime, args) => {
+    const active = await session(runtime, args);
+    const view = parseResponse("billing.summary", await active.client.request("billing_summary"));
+    return {
+        data: view,
+        human: [
+            `Available    ${money(view.credit.available)}`,
+            `Reserved     ${money(view.credit.reserved)}`,
+            `Consumed     ${money(view.credit.consumed)}`,
+            `Enforcement  ${view.activation.mode} from ${view.activation.boundary}`,
+            `Policy       desired r${String(view.desiredRevision)}, effective r${String(view.effectiveRevision)}${view.pending ? " (pending)" : ""}, ${view.priceVersion}`,
+            `Budget policy desired r${String(view.budgetPolicy.desiredRevision)}, effective r${String(view.budgetPolicy.effectiveRevision)}${view.budgetPolicy.pending ? " (pending)" : ""}`,
+            `Desired advisory ${view.budgetPolicy.desired.advisoryBudget === null ? "off" : money(view.budgetPolicy.desired.advisoryBudget)}`,
+            `Desired hard cap ${view.budgetPolicy.desired.hardCap === null ? "off" : money(view.budgetPolicy.desired.hardCap)}`,
+            ...(view.period === undefined
+                ? []
+                : [
+                    `Period       ${view.period.start} to ${view.period.end}`,
+                    `Period used  ${money(view.period.settledUsage)}`,
+                    `In flight    ${money(view.period.reservedUsage)}`,
+                    `Subscriptions ${money(view.period.subscribedProjectFees)}`,
+                ]),
+            ...(view.period?.hardCap === undefined
+                ? []
+                : [
+                    `Period cap   ${money(view.period.hardCap)}`,
+                    `Cap remaining ${money(view.period.remainingToHardCap)}`,
+                ]),
+            ...(view.period?.advisoryBudgetProgress === undefined
+                ? []
+                : [
+                    `Advisory     ${money(view.period.advisoryBudget)}`,
+                    `Advisory left ${money(view.period.advisoryBudgetProgress.remaining)}`,
+                ]),
+            ...(view.period === undefined
+                ? []
+                : [
+                    `Auto top-up  ${money(view.period.automaticExecutionTopUp.settled)} settled, ${money(view.period.automaticExecutionTopUp.pending)} pending`,
+                    ...(view.period.automaticExecutionTopUp.cap === undefined
+                        ? []
+                        : [
+                            `Auto cap     ${money(view.period.automaticExecutionTopUp.cap)}`,
+                            `Auto remaining ${money(view.period.automaticExecutionTopUp.remainingToCap)}`,
+                        ]),
+                ]),
+            ...(view.trialExpiresAt === undefined
+                ? []
+                : [`Trial ends   ${view.trialExpiresAt}`]),
+            ...(view.activation.mode === "shadow" || view.blockingReasons.length === 0
+                ? []
+                : [`Blocked      ${view.blockingReasons.join(", ")}`]),
+        ].join("\n"),
+        ...(view.budgetPolicy.pending
+            ? {
+                nextMove: 'Open the live workspace Overview and choose "Apply pending policy", or use the billing.reconcile MCP tool.',
+            }
+            : {}),
+    };
+};
+function fundingResult(view) {
+    const automatic = view.automaticExecutionTopUp;
+    const rule = automatic.rule;
+    const configuration = rule.desired ?? rule.effective;
+    return {
+        data: view,
+        human: [
+            `Available     ${money(view.credit.available)}`,
+            `Reserved      ${money(view.credit.reserved)}`,
+            `Amount owed   ${money(view.credit.amountOwed)}`,
+            `Subscriptions ${money(view.subscribedProjectFees)}`,
+            `Auto ceiling  ${automatic.ceiling === null ? "off" : money(automatic.ceiling)} (revision ${String(automatic.revision)})`,
+            `UTC period    ${automatic.currentPeriod.start} to ${automatic.currentPeriod.end}`,
+            `Auto settled  ${money(automatic.currentPeriod.settled)}`,
+            `Auto pending  ${money(automatic.currentPeriod.pending)}`,
+            `Auto remaining ${automatic.currentPeriod.remaining === null ? "off" : money(automatic.currentPeriod.remaining)}`,
+            `Auto rule     ${rule.state}`,
+            ...(configuration === null
+                ? []
+                : [
+                    `Auto trigger  below ${money(configuration.triggerBelow)} usable credit`,
+                    `Auto purchase ${money(configuration.credit)} fixed credit`,
+                ]),
+            ...(rule.suspension === null
+                ? []
+                : [
+                    `Auto suspended ${rule.suspension.reason} since ${rule.suspension.at}`,
+                ]),
+            ...(rule.cooldownUntil === null
+                ? []
+                : [`Auto cooldown until ${rule.cooldownUntil}`]),
+            ...(rule.setupUrl === undefined
+                ? []
+                : [`Payment setup ${rule.setupUrl}`]),
+            ...view.paymentOperations.map((operation) => `${operation.id}: ${operation.kind} ${operation.state}, credit ${money(operation.credit)}${operation.gross === null ? ", tax and gross calculated at checkout" : `, gross ${money(operation.gross)} including tax ${money(operation.tax)}`}${operation.reason === undefined ? "" : ` (${operation.reason})`}${(operation.receiptUrl ?? operation.paymentUrl) ? ` ${operation.receiptUrl ?? operation.paymentUrl}` : ""}`),
+        ].join("\n"),
+    };
+}
+const billingFunding = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return fundingResult(parseResponse("billing.funding", await active.client.request("billing_funding")));
+};
+const billingNotices = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        columns: [
+            "WHEN",
+            "SEVERITY",
+            "NOTICE",
+            "SCOPE",
+            "AMOUNTS",
+            "PAYMENT",
+            "EMAIL",
+            "RECOVERY",
+        ],
+        command: `${runtime.programName} billing notices`,
+        empty: "This organization has no billing notices.",
+        read: (request) => page("billing.notices", () => active.client.request("billing_notices", request)),
+        row: (notice) => [
+            notice.updatedAt,
+            notice.severity,
+            `${notice.title}: ${notice.detail}`,
+            notice.scope.kind === "organization"
+                ? "organization"
+                : `project ${notice.scope.project}`,
+            Object.entries(notice.amounts)
+                .flatMap(([name, amount]) => amount === undefined ? [] : [`${name} ${money(amount)}`])
+                .join("; "),
+            notice.payment === null
+                ? "none"
+                : `${notice.payment.operation}: ${notice.payment.state}`,
+            notice.email.state === "failed"
+                ? `failed (${notice.email.failureCode ?? "unknown"})`
+                : notice.email.state,
+            notice.recoveryPath,
+        ],
+    });
+};
+function notificationSettingsResult(settings) {
+    return {
+        data: settings,
+        human: [
+            `Low credit        ${money(settings.lowCreditThreshold)}`,
+            `Noncritical email ${settings.noncriticalEmail ? "on" : "off"}`,
+            "Critical email    mandatory",
+            "Recipients        owners and active billing-role members",
+            `Revision          ${String(settings.revision)}`,
+        ].join("\n"),
+    };
+}
+const billingNotificationSettings = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return notificationSettingsResult(parseResponse("billing.notificationsettings", await active.client.request("billing_notificationsettings")));
+};
+const billingNotificationSettingsUpdate = async (runtime, args) => {
+    const noncritical = args.options["--noncritical-email"];
+    const parsed = billingNotificationSettingsUpdateRequestSchema.safeParse({
+        expectedRevision: expectedRevision(args),
+        lowCreditThreshold: budgetMoney(args, "--low-credit"),
+        noncriticalEmail: noncritical === "on" ? true : noncritical === "off" ? false : undefined,
+    });
+    if (!parsed.success) {
+        throw new CliError("--low-credit must be a positive exact-cent USD amount and --noncritical-email must be on or off", "usage");
+    }
+    const confirmation = await confirmChange(runtime, args, {
+        action: "Replace this organization's billing notification settings.",
+        effect: [
+            `low-credit threshold ${money(parsed.data.lowCreditThreshold)}`,
+            `noncritical email ${parsed.data.noncriticalEmail ? "on" : "off"}`,
+            "Critical email remains mandatory for owners and active billing-role members.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    runtime.stderr(`Retry key ${key}; retain this key if the response is lost.\n`);
+    const settings = parseResponse("billing.notificationsettingsupdate", await active.client.request("billing_notificationsettingsupdate", parsed.data, { "Idempotency-Key": key }));
+    const result = notificationSettingsResult(settings);
+    return {
+        ...result,
+        data: { confirmation, idempotencyKey: key, ...settings },
+    };
+};
+const billingQuoteFunding = async (runtime, args) => {
+    const parsed = billingFundingQuoteRequestSchema.safeParse({
+        credit: budgetMoney(args, "--credit"),
+    });
+    if (!parsed.success) {
+        throw new CliError("--credit must be at least USD 10, in exact cents", "usage");
+    }
+    const active = await session(runtime, args);
+    const quote = parseResponse("billing.fundingquote", await active.client.request("billing_fundingquote", parsed.data));
+    return {
+        data: quote,
+        human: [
+            `Execution credit ${money(quote.credit)}`,
+            "Tax and gross are calculated in authenticated hosted checkout.",
+            `Funding revision r${String(quote.expectedRevision)}; quote expires ${quote.expiresAt}`,
+        ].join("\n"),
+        nextMove: "Confirm this exact object with billing purchase --quote, retaining the quote and idempotency key for retries.",
+    };
+};
+const billingPurchase = async (runtime, args) => {
+    const parsed = billingFundingQuoteSchema.safeParse(await readJsonOption(runtime, "--quote", args.options["--quote"]));
+    if (!parsed.success) {
+        throw new CliError("--quote must contain the exact object returned by billing quote-funding", "usage");
+    }
+    const quote = parsed.data;
+    const confirmation = await confirmChange(runtime, args, {
+        action: "Create this manual execution-credit purchase.",
+        effect: [
+            `execution credit ${money(quote.credit)}`,
+            "Tax and gross will be shown in authenticated hosted checkout.",
+            "This manual purchase does not consume automatic payment authority, and a redirect never grants credit.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    runtime.stderr(`Retry key ${key}; retain this key and quote if the response is lost.\n`);
+    const view = parseResponse("billing.purchase", await active.client.request("billing_purchase", {
+        confirmed: true,
+        expectedRevision: quote.expectedRevision,
+        quote: quote.quote,
+    }, { "Idempotency-Key": key }));
+    const result = fundingResult(view);
+    return {
+        ...result,
+        data: { confirmation, idempotencyKey: key, ...view },
+    };
+};
+function expectedRevision(args) {
+    const text = args.options["--expected-revision"];
+    const revision = Number(text);
+    if (text === undefined || !Number.isSafeInteger(revision) || revision < 0) {
+        throw new CliError("--expected-revision must be a nonnegative whole number", "usage");
+    }
+    return revision;
+}
+const billingCeiling = async (runtime, args) => {
+    const parsed = billingCeilingUpdateRequestSchema.safeParse({
+        automaticExecutionTopUpCeiling: budgetMoney(args, "--ceiling"),
+        expectedRevision: expectedRevision(args),
+    });
+    if (!parsed.success) {
+        throw new CliError("--ceiling must be a nonnegative exact-cent USD amount, or off", "usage");
+    }
+    const ceiling = parsed.data.automaticExecutionTopUpCeiling;
+    const confirmation = await confirmChange(runtime, args, {
+        action: "Replace this organization's automatic payment ceiling.",
+        effect: [
+            `UTC-month ceiling ${ceiling === null ? "off" : money(ceiling)}`,
+            `expected revision ${String(parsed.data.expectedRevision)}`,
+            "Pending gross payments and tax count; manual purchases and subscriptions remain separate; refunds do not restore authority.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    runtime.stderr(`Retry key ${key}; retain this key if the response is lost.\n`);
+    const view = parseResponse("billing.ceiling", await active.client.request("billing_ceiling", parsed.data, {
+        "Idempotency-Key": key,
+    }));
+    const result = fundingResult(view);
+    return {
+        ...result,
+        data: { confirmation, idempotencyKey: key, ...view },
+    };
+};
+function automaticTopUpConfiguration(value) {
+    return value === null
+        ? "off"
+        : `${money(value.credit)} fixed credit below ${money(value.triggerBelow)}, ${money(value.ceiling)} UTC-month gross ceiling`;
+}
+const billingAutoTopUpPreview = async (runtime, args) => {
+    const action = args.options["--action"];
+    const expected = expectedRevision(args);
+    if ((action === "disable" || action === "resume") &&
+        ["--ceiling", "--credit", "--trigger-below"].some((flag) => args.options[flag] !== undefined)) {
+        throw new CliError(`${action} does not accept --credit, --trigger-below or --ceiling`, "usage");
+    }
+    const candidate = action === "enable" || action === "edit"
+        ? {
+            action,
+            ceiling: budgetMoney(args, "--ceiling"),
+            credit: budgetMoney(args, "--credit"),
+            expectedRevision: expected,
+            triggerBelow: budgetMoney(args, "--trigger-below"),
+        }
+        : { action, expectedRevision: expected };
+    const parsed = billingAutoTopUpPreviewRequestSchema.safeParse(candidate);
+    if (!parsed.success) {
+        throw new CliError("--action must be enable, edit, disable or resume; enable/edit require positive exact-cent --credit, --trigger-below and --ceiling values", "usage");
+    }
+    const active = await session(runtime, args);
+    const preview = parseResponse("billing.autotopuppreview", await active.client.request("billing_autotopuppreview", parsed.data));
+    return {
+        data: preview,
+        human: [
+            `Action        ${preview.action}`,
+            `Current rule  ${automaticTopUpConfiguration(preview.before)}`,
+            `Proposed rule ${automaticTopUpConfiguration(preview.after)}`,
+            `Authority     ${preview.expandsAuthority ? "expands" : "does not expand"}`,
+            `UTC period    ${preview.currentPeriod.start} to ${preview.currentPeriod.end}`,
+            `Auto settled  ${money(preview.currentPeriod.settled)}`,
+            `Auto pending  ${money(preview.currentPeriod.pending)}`,
+            `Subscriptions ${money(preview.subscribedProjectFees)} separately authorized`,
+            `Expires       ${preview.expiresAt}`,
+        ].join("\n"),
+        nextMove: "Confirm this exact object with billing apply-topup --preview. Applying the rule does not create a payment; retain the preview and retry key if the response is lost.",
+    };
+};
+const billingAutoTopUpApply = async (runtime, args) => {
+    const parsed = billingAutoTopUpPreviewSchema.safeParse(await readJsonOption(runtime, "--preview", args.options["--preview"]));
+    if (!parsed.success) {
+        throw new CliError("--preview must contain the exact object returned by billing preview-topup", "usage");
+    }
+    const preview = parsed.data;
+    const request = billingAutoTopUpApplyRequestSchema.parse({
+        confirmed: true,
+        expectedRevision: preview.expectedRevision,
+        preview: preview.preview,
+    });
+    const confirmation = await confirmChange(runtime, args, {
+        action: `${preview.action[0]?.toUpperCase() ?? ""}${preview.action.slice(1)} this organization's automatic top-up rule.`,
+        effect: [
+            `current ${automaticTopUpConfiguration(preview.before)}`,
+            `proposed ${automaticTopUpConfiguration(preview.after)}`,
+            `${preview.expandsAuthority ? "This expands" : "This does not expand"} automatic payment authority.`,
+            "Tax and pending gross payments count against the UTC-month ceiling; subscriptions and manual purchases remain separate.",
+            preview.action === "disable"
+                ? "Queued unsubmitted automatic work is fenced; submitted payments remain visible until reconciled."
+                : "Applying this rule creates no payment. A later low-balance trigger remains single-flight and cooldown bounded.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    runtime.stderr(`Retry key ${key}; retain this key and preview if the response is lost.\n`);
+    const view = parseResponse("billing.autotopup", await active.client.request("billing_autotopup", request, {
+        "Idempotency-Key": key,
+    }));
+    const result = fundingResult(view);
+    return {
+        ...result,
+        data: { confirmation, idempotencyKey: key, ...view },
+    };
+};
+const billingRefundRequest = async (runtime, args) => {
+    const parsed = billingRefundRequestCreateSchema.safeParse({
+        amount: budgetMoney(args, "--amount"),
+        confirmed: true,
+        paymentOperation: args.options["--payment-operation"],
+        reason: args.options["--reason"],
+    });
+    if (!parsed.success) {
+        throw new CliError("Provide a positive exact-cent --amount, --payment-operation and --reason", "usage");
+    }
+    const confirmation = await confirmChange(runtime, args, {
+        action: "Record this unused-credit refund request for operator review.",
+        effect: [
+            `amount ${money(parsed.data.amount)}`,
+            `payment ${parsed.data.paymentOperation}`,
+            `reason ${parsed.data.reason}`,
+            "This records a request only. It does not submit a provider refund or cash out credit.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    const view = parseResponse("billing.refundrequest", await active.client.request("billing_refundrequest", parsed.data, {
+        "Idempotency-Key": key,
+    }));
+    return {
+        data: { confirmation, idempotencyKey: key, ...view },
+        human: [
+            `Request ${view.id}: ${view.state}`,
+            `Payment ${view.paymentOperation}; amount ${money(view.amount)}`,
+            `Requested ${view.requestedAt}`,
+            `Retry key ${key}`,
+        ].join("\n"),
+        nextMove: "An operator must review this request before any provider refund.",
+    };
+};
+const billingRefundResolution = async (runtime, args) => {
+    const refundRequest = args.options["--refund-request"];
+    if (refundRequest === undefined ||
+        refundRequest.length === 0 ||
+        refundRequest.length > 255) {
+        throw new CliError("Provide a bounded --refund-request", "usage");
+    }
+    const decision = args.options["--decision"];
+    const hasProviderFields = ["--provider-refund", "--gross", "--tax"].some((option) => args.options[option] !== undefined);
+    if (decision === "declined" && hasProviderFields) {
+        throw new CliError("A declined decision does not accept --provider-refund, --gross or --tax", "usage");
+    }
+    const parsed = billingRefundResolutionRequestSchema.safeParse(decision === "completed"
+        ? {
+            confirmed: true,
+            decision,
+            gross: budgetMoney(args, "--gross"),
+            providerRefund: args.options["--provider-refund"],
+            tax: budgetMoney(args, "--tax"),
+        }
+        : { confirmed: true, decision });
+    if (!parsed.success) {
+        throw new CliError("Use --decision completed with an existing --provider-refund and positive exact-cent --gross plus exact-cent --tax, or use --decision declined alone", "usage");
+    }
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Record this refund request as ${parsed.data.decision}.`,
+        effect: parsed.data.decision === "completed"
+            ? [
+                `request ${refundRequest}`,
+                `existing Stripe refund ${parsed.data.providerRefund ?? ""}`,
+                `gross ${money(parsed.data.gross)}, including tax ${money(parsed.data.tax)}`,
+                "This verifies and records an existing provider refund. It never creates one.",
+            ]
+            : [
+                `request ${refundRequest}`,
+                "Declining releases the reserved execution credit and does not contact the provider.",
+            ],
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    runtime.stderr(`Retry key ${key}; retain this key if the response is lost.\n`);
+    const view = parseResponse("billing.refundresolution", await active.client.request("billing_refundresolution", refundRequest, parsed.data, { "Idempotency-Key": key }));
+    const result = fundingResult(view);
+    return {
+        ...result,
+        data: { confirmation, idempotencyKey: key, ...view },
+    };
+};
+function projectBillingResult(view) {
+    return {
+        data: view,
+        human: [
+            `Monthly project fees ${money(view.recurringProjectFees)}`,
+            `Policy desired r${String(view.desiredRevision)}, effective r${String(view.effectiveRevision)}${view.pending ? " (pending)" : ""}`,
+            ...view.projects.map((project) => `${project.name} (${project.project}): ${project.access}${project.paidThroughAt ? `, paid through ${project.paidThroughAt}` : ""}${project.cancellationAt ? `, cancels ${project.cancellationAt}` : ""}${project.renewalGraceUntil ? `, renewal grace until ${project.renewalGraceUntil}` : ""}`),
+            ...view.pendingOperations.map((operation) => `${operation.project}: ${operation.state}${operation.reason ? ` (${operation.reason})` : ""}${operation.paymentUrl ? ` ${operation.paymentUrl}` : ""}`),
+        ].join("\n"),
+    };
+}
+const billingProjects = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return projectBillingResult(parseResponse("billing.projects", await active.client.request("billing_projects")));
+};
+function projectQuoteLines(quote) {
+    return [
+        `Project ${quote.project}${quote.fromProject ? `; former included ${quote.fromProject}` : ""}`,
+        `Charge ${money(quote.charge)}; monthly project fees ${money(quote.monthlyProjectFees)}`,
+        `Effective ${quote.effectiveAt}; quote expires ${quote.expiresAt}`,
+        ...(quote.formerIncludedWillBlock
+            ? [
+                "The former included project will lose included access; this does not subscribe it.",
+            ]
+            : []),
+        ...(quote.action === "cancel"
+            ? ["Paid-through access remains; there is no partial-period credit."]
+            : []),
+        "Project access changes only after payment and effective policy reconciliation where required.",
+    ];
+}
+const billingQuoteProject = async (runtime, args) => {
+    const parsed = projectBillingQuoteRequestSchema.safeParse({
+        action: args.options["--action"],
+        project: args.options["--target-project"],
+        ...(args.options["--from-project"]
+            ? { fromProject: args.options["--from-project"] }
+            : {}),
+    });
+    if (!parsed.success)
+        throw new CliError("Provide --action and a valid --target-project (and --from-project for an included transfer).", "usage");
+    const active = await session(runtime, args);
+    const quote = parseResponse("billing.quote", await active.client.request("billing_quote", parsed.data));
+    return {
+        data: quote,
+        human: [`Preview ${quote.action}`, ...projectQuoteLines(quote)].join("\n"),
+        nextMove: "Confirm the exact quote with billing change-project --quote, retaining the quote and idempotency key for retries.",
+    };
+};
+const billingChangeProject = async (runtime, args) => {
+    const parsed = projectBillingQuoteSchema.safeParse(await readJsonOption(runtime, "--quote", args.options["--quote"]));
+    if (!parsed.success)
+        throw new CliError("--quote must contain the exact quote object returned by billing quote-project.", "usage");
+    const quote = parsed.data;
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Confirm project billing ${quote.action}`,
+        effect: projectQuoteLines(quote),
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    runtime.stderr(`Retry key ${key}; retain this key and quote if the response is lost.\n`);
+    const view = parseResponse("billing.change", await active.client.request("billing_change", {
+        quote: quote.quote,
+        expectedRevision: quote.expectedRevision,
+        confirmed: true,
+    }, { "Idempotency-Key": key }));
+    return {
+        ...projectBillingResult(view),
+        data: { confirmation, idempotencyKey: key, ...view },
+    };
+};
+const billingPortal = async (runtime, args) => {
+    await confirmChange(runtime, args, {
+        action: "Create this organization's hosted billing recovery link.",
+        effect: [
+            "Manage payment methods and invoices. This does not purchase credit or grant project access.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const view = parseResponse("billing.portal", await active.client.request("billing_portal"));
+    return { data: view, human: view.url };
+};
+function budgetMoney(args, flag) {
+    const raw = args.options[flag];
+    if (raw === undefined) {
+        throw new CliError(`${flag} is required`, "usage");
+    }
+    if (raw === "off")
+        return null;
+    const match = /^(?<whole>0|[1-9]\d*)(?:\.(?<cents>\d{1,2}))?$/u.exec(raw);
+    if (match?.groups === undefined) {
+        throw new CliError(`${flag} must be a nonnegative USD amount with at most two decimal places, or off`, "usage");
+    }
+    const cents = BigInt(match.groups.whole) * 100n +
+        BigInt((match.groups.cents ?? "").padEnd(2, "0"));
+    return { currency: "USD", microdollars: String(cents * 10000n), scale: 6 };
+}
+const billingBudgets = async (runtime, args) => {
+    const revisionText = args.options["--expected-revision"];
+    const expectedRevision = Number(revisionText);
+    if (revisionText === undefined ||
+        !Number.isSafeInteger(expectedRevision) ||
+        expectedRevision < 0) {
+        throw new CliError("--expected-revision must be a nonnegative whole number", "usage");
+    }
+    const advisoryBudget = budgetMoney(args, "--advisory-budget");
+    const hardCap = budgetMoney(args, "--hard-cap");
+    const confirmation = await confirmChange(runtime, args, {
+        action: "Replace this organization's current UTC-month execution budgets.",
+        effect: [
+            `advisory     ${advisoryBudget === null ? "off" : money(advisoryBudget)}`,
+            `hard cap     ${hardCap === null ? "off" : money(hardCap)}`,
+            `expected     revision ${String(expectedRevision)}`,
+            "This does not change automatic top-up authority or purchase credit.",
+        ],
+    });
+    const active = await session(runtime, args);
+    const key = idempotencyKey(runtime, args);
+    const view = parseResponse("billing.budgets", await active.client.request("billing_budgets", { advisoryBudget, expectedRevision, hardCap }, { "Idempotency-Key": key }));
+    return {
+        data: { confirmation, idempotencyKey: key, ...view },
+        human: [
+            `Advisory     ${view.budgetPolicy.desired.advisoryBudget === null ? "off" : money(view.budgetPolicy.desired.advisoryBudget)}`,
+            `Hard cap     ${view.budgetPolicy.desired.hardCap === null ? "off" : money(view.budgetPolicy.desired.hardCap)}`,
+            `Policy       desired r${String(view.budgetPolicy.desiredRevision)}, effective r${String(view.budgetPolicy.effectiveRevision)}${view.budgetPolicy.pending ? " (pending)" : ""}`,
+            `Retry key    ${key}`,
+        ].join("\n"),
+        ...(view.budgetPolicy.pending
+            ? {
+                nextMove: "The desired budget is saved and awaits billing reconciliation.",
+            }
+            : {}),
+    };
+};
+const billingLedger = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        columns: ["SEQUENCE", "RECORDED", "KIND", "AMOUNT", "REFERENCE"],
+        command: `${runtime.programName} billing ledger`,
+        empty: "This organization has no billing entries.",
+        read: (request) => page("billing.ledger", () => active.client.request("billing_ledger", request)),
+        row: (entry) => [
+            entry.sequence,
+            entry.recordedAt,
+            entry.kind,
+            money(entry.amount),
+            entry.reference.attempt ??
+                entry.reference.creditLot ??
+                entry.reference.paymentOperation ??
+                entry.reference.event,
+        ],
+    });
+};
+const timing = async (runtime, args) => {
+    const active = await session(runtime, args);
+    const view = parseResponse("timing.summary", await active.client.request("timing_summary"));
+    return {
+        data: view,
+        human: [
+            `Window       ${view.windowStart} to ${view.windowEnd}`,
+            `Policy       ${view.policyVersion}`,
+            `Delivered    ${String(view.deliveredSampleCount)} samples`,
+            `Excluded     ${String(view.customerBlockedCount)} customer blocked, ${String(view.platformBlockedCount)} platform blocked, ${String(view.skippedCount)} skipped, ${String(view.missingEvidenceCount)} missing evidence`,
+            ...(view.p95LatenessMs === undefined
+                ? []
+                : [`Delivered p95  ${String(view.p95LatenessMs)}ms`]),
+            ...(view.p99LatenessMs === undefined
+                ? []
+                : [`Delivered p99  ${String(view.p99LatenessMs)}ms`]),
+            ``,
+            table(["TARGET", "VERDICT", "WITHIN", "BREACHES", "OUTSTANDING"], view.targets.map((target) => [
+                `${String(target.targetMs)}ms`,
+                target.verdict,
+                `${String(target.withinTargetCount)}/${String(target.maturedCount)}`,
+                String(target.breachCount),
+                String(target.eligibleOutstandingBreachCount),
+            ]), "No timing targets were reported."),
+        ].join("\n"),
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Credentials                                                                */
+/* -------------------------------------------------------------------------- */
+const credentialsList = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        columns: ["PREFIX", "CREDENTIAL", "SCOPES", "LAST USED"],
+        command: `${runtime.programName} credentials list`,
+        empty: "This project has no API credentials.",
+        read: (request) => page("credentials.list", () => active.client.request("credentials_list", request)),
+        // **The prefix and nothing else.** It is what the service publishes as the
+        // way to recognise a credential, and it is the whole of what this listing
+        // can honestly show: the secret half exists only in the answer to the call
+        // that minted it.
+        row: (credential) => [
+            credential.displayPrefix,
+            credential.id,
+            credential.scopes.join(" "),
+            credential.lastUsedAt ?? "never",
+        ],
+    });
+};
+const credentialsRotate = async (runtime, args) => {
+    const [id] = positionals(args, ["<credential>"], `${runtime.programName} credentials rotate <credential>`);
+    const active = await session(runtime, args);
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Rotate credential ${id}.`,
+        effect: [
+            `A replacement is minted and its secret is shown once, here.`,
+            `The current credential keeps working until the overlap ends, then stops.`,
+            `Anything still presenting the old secret after that is refused.`,
+        ],
+    });
+    const view = parseResponse("credentials.rotate", await active.client.request("credentials_rotate", id, {}));
+    const secret = view.credential.secret;
+    return {
+        data: { confirmation, credential: view.credential, retired: view.retired },
+        human: [
+            `Credential   ${view.credential.id}`,
+            `Prefix       ${view.credential.displayPrefix}`,
+            `Scopes       ${view.credential.scopes.join(", ")}`,
+            `Replaces     ${view.retired.id}, refused after ${view.retired.expiresAt ?? "the overlap ends"}`,
+            ...(secret === undefined
+                ? [
+                    ``,
+                    `The service did not return a secret with this rotation, so there is`,
+                    `nothing to copy. Read the credential list to see what it did do.`,
+                ]
+                : [
+                    ``,
+                    `Secret       ${secret}`,
+                    ``,
+                    `This is shown once and is not recoverable. Put it where the old one`,
+                    `was before the overlap ends; listing credentials will show`,
+                    `${redactSecret(secret)} instead.`,
+                ]),
+        ].join("\n"),
+    };
+};
+const credentialsRevoke = async (runtime, args) => {
+    const [id] = positionals(args, ["<credential>"], `${runtime.programName} credentials revoke <credential>`);
+    const active = await session(runtime, args);
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Revoke credential ${id}.`,
+        effect: [
+            `It stops working immediately and everywhere, with no overlap.`,
+            `Anything still using it starts failing to authenticate at once.`,
+            `Rotate instead if something is still presenting it.`,
+        ],
+    });
+    const view = parseResponse("credentials.revoke", await active.client.request("credentials_revoke", id));
+    return {
+        data: { confirmation, credential: view.credential },
+        human: [
+            `Credential   ${view.credential.id}`,
+            `Prefix       ${view.credential.displayPrefix}`,
+            `Revoked      ${view.credential.revokedAt ?? "now"}`,
+        ].join("\n"),
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Test sinks                                                                 */
+/* -------------------------------------------------------------------------- */
+function sinkBlock(sink) {
+    return [
+        `Sink         ${sink.id}`,
+        `Destination  ${sink.endpoint}`,
+        `URL          ${sink.url}`,
+        `Answering    ${sink.program.behavior}`,
+        `Received     ${String(sink.deliveryCount)}`,
+    ];
+}
+const sinksCreate = async (runtime, args) => {
+    const endpoint = args.options["--endpoint"];
+    if (endpoint === undefined) {
+        throw new CliError(`${runtime.programName} sinks create needs --endpoint`, "usage", `Usage: ${runtime.programName} sinks create --endpoint <destination>`);
+    }
+    const active = await session(runtime, args);
+    const program = await readJsonOption(runtime, "--program", args.options["--program"]);
+    const sink = parseResponse("testsinks.create", await active.client.request("testsinks_create", {
+        endpoint,
+        ...(program === undefined ? {} : { program }),
+    }));
+    return {
+        data: { sink },
+        human: sinkBlock(sink).join("\n"),
+        nextMove: `Point a schedule at that destination, then read what arrived: ${runtime.programName} sinks deliveries ${sink.id}`,
+    };
+};
+const sinksList = async (runtime, args) => {
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        columns: ["ANSWERING", "SINK", "DESTINATION", "RECEIVED"],
+        command: `${runtime.programName} sinks list`,
+        empty: "This project has no test sinks.",
+        read: (request) => page("testsinks.list", () => active.client.request("testsinks_list", request)),
+        row: (sink) => [
+            sink.program.behavior,
+            sink.id,
+            sink.endpoint,
+            String(sink.deliveryCount),
+        ],
+    });
+};
+const sinksRead = async (runtime, args) => {
+    const [id] = positionals(args, ["<sink>"], `${runtime.programName} sinks read <sink>`);
+    const active = await session(runtime, args);
+    const sink = parseResponse("testsinks.read", await active.client.request("testsinks_read", id));
+    return { data: { sink }, human: sinkBlock(sink).join("\n") };
+};
+const sinksConfigure = async (runtime, args) => {
+    const [id] = positionals(args, ["<sink>"], `${runtime.programName} sinks configure <sink> --program <json>`);
+    const program = await readJsonOption(runtime, "--program", args.options["--program"]);
+    if (program === undefined) {
+        throw new CliError(`${runtime.programName} sinks configure needs --program`, "usage", `Usage: ${runtime.programName} sinks configure <sink> --program '{"behavior":"timeout"}'`);
+    }
+    const active = await session(runtime, args);
+    const sink = parseResponse("testsinks.configure", await active.client.request("testsinks_configure", id, program));
+    return {
+        data: { sink },
+        human: sinkBlock(sink).join("\n"),
+        nextMove: "Deliveries from now on meet this behaviour. The ones already recorded are unchanged.",
+    };
+};
+const sinksDelete = async (runtime, args) => {
+    const [id] = positionals(args, ["<sink>"], `${runtime.programName} sinks delete <sink>`);
+    const active = await session(runtime, args);
+    const current = parseResponse("testsinks.read", await active.client.request("testsinks_read", id));
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Delete test sink ${current.id}.`,
+        effect: [
+            `received     ${String(current.deliveryCount)} deliveries, which go with it`,
+            `The recorded bodies are the only copy Greatwait keeps. Read anything you`,
+            `still need first.`,
+        ],
+    });
+    const sink = parseResponse("testsinks.delete", await active.client.request("testsinks_delete", id));
+    return {
+        data: { confirmation, sink },
+        human: `Test sink ${sink.id} is gone, with the ${String(current.deliveryCount)} deliveries recorded against it.`,
+    };
+};
+const sinksDeliveries = async (runtime, args) => {
+    const [id] = positionals(args, ["<sink>"], `${runtime.programName} sinks deliveries <sink>`);
+    const active = await session(runtime, args);
+    return listing(runtime, args, {
+        columns: ["ANSWERED", "DISPOSITION", "DELIVERY", "RECEIVED"],
+        command: `${runtime.programName} sinks deliveries ${id}`,
+        empty: "Nothing has arrived at this sink.",
+        read: (request) => page("sinkdeliveries.list", () => active.client.request("sinkdeliveries_list", id, request)),
+        row: (delivery) => [
+            delivery.respondedWith === undefined
+                ? "none"
+                : String(delivery.respondedWith),
+            delivery.disposition,
+            delivery.id,
+            delivery.receivedAt,
+        ],
+    });
+};
+const sinksDelivery = async (runtime, args) => {
+    const [id, delivery] = positionals(args, ["<sink>", "<delivery>"], `${runtime.programName} sinks delivery <sink> <delivery>`);
+    const active = await session(runtime, args);
+    const record = parseResponse("sinkdeliveries.read", await active.client.request("sinkdeliveries_read", id, delivery));
+    return {
+        data: { delivery: record },
+        human: [
+            `Delivery     ${record.id}`,
+            `Received     ${record.receivedAt}`,
+            `Answered     ${record.respondedWith === undefined ? "nothing" : String(record.respondedWith)}`,
+            `Disposition  ${record.disposition}`,
+            ...(record.occurrenceId === undefined
+                ? []
+                : [`Occurrence   ${record.occurrenceId}`]),
+            ...(record.signature === undefined
+                ? []
+                : [
+                    `Signature    ${record.signature}${record.keyId === undefined
+                        ? " — signed with no key this sink accepts"
+                        : ` (key ${record.keyId})`}`,
+                ]),
+            ...(record.body === undefined
+                ? []
+                : [
+                    ``,
+                    `Body${record.bodyTruncated === true ? ` (truncated; ${String(record.receivedBytes ?? 0)} bytes arrived)` : ""}`,
+                    record.body,
+                ]),
+        ].join("\n"),
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Dispatch                                                                   */
+/* -------------------------------------------------------------------------- */
+/** The operate-and-diagnose commands, keyed by the words that select them. */
+export const OPERATE_COMMANDS = {
+    "attempts read": attemptsRead,
+    billing,
+    "billing budgets": billingBudgets,
+    "billing apply-topup": billingAutoTopUpApply,
+    "billing ceiling": billingCeiling,
+    "billing funding": billingFunding,
+    "billing notices": billingNotices,
+    "billing notification-settings": billingNotificationSettings,
+    "billing update-notifications": billingNotificationSettingsUpdate,
+    "billing ledger": billingLedger,
+    "billing projects": billingProjects,
+    "billing purchase": billingPurchase,
+    "billing quote-funding": billingQuoteFunding,
+    "billing quote-project": billingQuoteProject,
+    "billing preview-topup": billingAutoTopUpPreview,
+    "billing refund-request": billingRefundRequest,
+    "billing resolve-refund": billingRefundResolution,
+    "billing change-project": billingChangeProject,
+    "billing portal": billingPortal,
+    timing,
+    "credentials list": credentialsList,
+    "credentials revoke": credentialsRevoke,
+    "credentials rotate": credentialsRotate,
+    "destinations list": destinationsList,
+    "destinations read": destinationsRead,
+    "destinations rotate-key": destinationsRotateKey,
+    "destinations update": destinationsUpdate,
+    forecast,
+    "occurrences list": occurrencesList,
+    "occurrences read": occurrencesRead,
+    "occurrences redeliver": occurrencesRedeliver,
+    "schedules archive": schedulesArchive,
+    "schedules cancel": schedulesCancel,
+    "schedules list": schedulesList,
+    "schedules pause": schedulesPause,
+    "schedules replace": schedulesReplace,
+    "schedules resume": schedulesResume,
+    "sinks configure": sinksConfigure,
+    "sinks create": sinksCreate,
+    "sinks deliveries": sinksDeliveries,
+    "sinks delivery": sinksDelivery,
+    "sinks delete": sinksDelete,
+    "sinks list": sinksList,
+    "sinks read": sinksRead,
+    usage,
+};
+export { scheduleRequest };