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

package/dist/commands.js

@@ -1,56 +1,16 @@
 import { GreatwaitClientError, createGreatwaitClient, } from "@greatwait/api-client";
 import { isTerminalOccurrenceState, responseSchemaFor, } from "@greatwait/contracts";
-import { readFile } from "node:fs/promises";
-import { SECRET_ARGUMENT_ADVICE, parseDuration, } from "./args.js";
+import { parseDuration } from "./args.js";
+import { COMMAND_CATALOG, REQUESTED_SCOPES } from "./catalog.js";
+import { confirmChange } from "./confirm.js";
 import { directoryConcerns, originKey } from "./config.js";
 import { buildAuthorization, codeFrom, discover, exchangeCode, registerClient, revoke, } from "./oauth.js";
 import { redactSecret } from "./output.js";
 import { CliError, sleepOrAbort } from "./runtime.js";
 import { publishedWait, recoveryFor, renderJourney, STEP_COMMANDS, } from "./journey.js";
 import { anonymousClient, ENVIRONMENT_NAMES, openSession, resolveOrigin, storeFor, } from "./session.js";
-/**
- * The commands, each bounded and each useful on its own.
- *
- * **There is no `greatwait demo`.** The project specification excludes one by
- * name, and the reason is that a single command whose success proves everything
- * teaches nothing: somebody who ran it has watched a callback arrive and still
- * cannot make a second one. Every command here is a step somebody would take
- * again on their own work, and together they are the published first-value
- * journey — which `greatwait journey` renders rather than restates.
- */
-/**
- * The scopes `login` asks for.
- *
- * Exactly the ones the published journey's steps declare, taken from the
- * authorization server's own `scopes_supported` where it publishes a narrower
- * set. Asking for everything a server offers would be asking a person to grant
- * a command line permissions it has no code to use.
- */
-const REQUESTED_SCOPES = [
-    "endpoints:read",
-    "endpoints:write",
-    "occurrences:read",
-    "schedules:read",
-    "schedules:write",
-];
-function apiUrlOption(args) {
-    return args.options["--api-url"];
-}
-function expectNoExtraArguments(args, used, usage) {
-    if (args.command.length <= used)
-        return;
-    // **A refusal never names an argument when `--api-key` is on the line.**
-    // The parser refuses a value immediately after that flag, but it cannot
-    // refuse one further along — `greatwait --api-key login <secret>` parses
-    // `login` as the command and leaves the secret as a positional — and naming
-    // it here is how the credential reached standard error and the `--json`
-    // envelope in the first place. Two layers, because either alone leaves a
-    // spelling uncovered.
-    if (args.booleans.has("--api-key")) {
-        throw new CliError("unexpected argument after --api-key", "usage", SECRET_ARGUMENT_ADVICE);
-    }
-    throw new CliError(`unexpected argument ${args.command[used]}`, "usage", `Usage: ${usage}`);
-}
+import { OPERATE_COMMANDS, scheduleRequest } from "./operate.js";
+import { apiUrlOption, expectNoExtraArguments, parseResponse, positionals, } from "./support.js";
 /* -------------------------------------------------------------------------- */
 /* Signing in                                                                 */
 /* -------------------------------------------------------------------------- */
@@ -71,7 +31,7 @@ async function readApiKey(runtime) {
         if (fromEnvironment !== undefined && fromEnvironment !== "") {
             return fromEnvironment;
         }
-        throw new CliError("no credential was supplied and there is no terminal to ask on", "usage", `Pipe it in — printf %s "$KEY" | greatwait login --api-key — or export ${ENVIRONMENT_NAMES.apiKey}.`);
+        throw new CliError("no credential was supplied and there is no terminal to ask on", "usage", `Pipe it in — printf %s "$KEY" | ${runtime.programName} login --api-key — or export ${ENVIRONMENT_NAMES.apiKey}.`);
     }
     const typed = (await runtime.promptSecret("Paste the API credential (it will not echo): ")).trim();
     if (typed === "") {
@@ -80,7 +40,7 @@ async function readApiKey(runtime) {
     return typed;
 }
 const login = async (runtime, args) => {
-    expectNoExtraArguments(args, 0, "greatwait login [--api-url <origin>] [--api-key] [--no-browser]");
+    expectNoExtraArguments(args, 0, `${runtime.programName} login [--api-url <origin>] [--api-key] [--no-browser] [--scope <scopes>]`);
     const store = storeFor(runtime);
     const requested = apiUrlOption(args);
     const origin = requested === undefined
@@ -104,16 +64,43 @@ const login = async (runtime, args) => {
                 ? `Signed in to ${origin} with an API credential, in project ${described.context.project} (${described.context.environmentKind}).`
                 : `Stored an API credential for ${origin} without checking it.`,
             nextMove: described.known
-                ? "Next: greatwait journey — the published first-value sequence, with the command for each step."
-                : `${described.reason}\n\nNext: greatwait journey — the published first-value sequence, with the command for each step.`,
+                ? `Next: ${runtime.programName} journey — the published first-value sequence, with the command for each step.`
+                : `${described.reason}\n\nNext: ${runtime.programName} journey — the published first-value sequence, with the command for each step.`,
         };
     }
     const server = await discover(runtime, origin);
+    // **Asked for, then narrowed to what the server publishes.** The default is
+    // the union of every scope the commands can use, derived from the catalog
+    // rather than listed — so a command added for an operation needing a new
+    // permission widens this request instead of failing at the point of use with
+    // a `scope_missing` on a grant nobody can widen without signing in again.
+    const wanted = args.options["--scope"];
+    const asked = wanted === undefined
+        ? REQUESTED_SCOPES
+        : wanted.split(/[\s,]+/u).filter((scope) => scope !== "");
+    if (wanted !== undefined) {
+        // **An empty value is the caller's mistake, not the server's.** It arrives
+        // from an unset shell variable — `--scope "$SCOPES"` — and without this the
+        // filtered list is empty, which falls through to "this service grants none
+        // of the permissions this command needs" and blames the service for a
+        // request nobody made.
+        if (asked.length === 0) {
+            throw new CliError("--scope was given with no permissions in it", "usage", `Name the ones you want, separated by spaces, or leave --scope off to ask for all of: ${REQUESTED_SCOPES.join(", ")}.`);
+        }
+        const unknown = asked.filter((scope) => !REQUESTED_SCOPES.includes(scope));
+        if (unknown.length > 0) {
+            // Refused rather than passed through: a scope no command uses is either a
+            // typo or a permission this program has no code to exercise, and granting
+            // one to a command line that cannot use it is the opposite of least
+            // privilege.
+            throw new CliError(`no command uses ${unknown.join(", ")}`, "usage", `The permissions these commands can use are: ${REQUESTED_SCOPES.join(", ")}.`);
+        }
+    }
     const scopes = server.scopesSupported.length === 0
-        ? [...REQUESTED_SCOPES]
-        : REQUESTED_SCOPES.filter((scope) => server.scopesSupported.includes(scope));
+        ? [...asked]
+        : asked.filter((scope) => server.scopesSupported.includes(scope));
     if (scopes.length === 0) {
-        throw new CliError(`${origin} grants none of the permissions this command needs`, "authorization", "Sign in with an API credential instead: greatwait login --api-key");
+        throw new CliError(`${origin} grants none of the permissions this command needs`, "authorization", `Sign in with an API credential instead: ${runtime.programName} login --api-key`);
     }
     // Bound first: the redirect URI is matched exactly, port included, so the
     // port has to exist before the client is registered for it.
@@ -141,7 +128,7 @@ const login = async (runtime, args) => {
         // `xdg-open` there exits zero having opened nothing.
         runtime.stderr(`${opened ? "Opened your browser. If nothing appeared, open" : "Open"} this address to approve the request:\n\n  ${authorization.authorizationUrl}\n\nWaiting for the answer on ${listener.redirectUri} …\n`);
         const returned = await listener.received;
-        const code = codeFrom(returned, authorization.state);
+        const code = codeFrom(returned, authorization.state, runtime.programName);
         const tokens = await exchangeCode(runtime, server, {
             clientId,
             code,
@@ -193,8 +180,8 @@ const login = async (runtime, args) => {
                 ? `Signed in to ${origin}, in project ${described.context.project} (${described.context.environmentKind}).`
                 : `Signed in to ${origin}. The grant is real — the service issued it — but it cannot say what it reaches.`,
             nextMove: described.known
-                ? "Next: greatwait journey — the published first-value sequence, with the command for each step."
-                : `${described.reason}\n\nNext: greatwait journey — the published first-value sequence, with the command for each step.`,
+                ? `Next: ${runtime.programName} journey — the published first-value sequence, with the command for each step.`
+                : `${described.reason}\n\nNext: ${runtime.programName} journey — the published first-value sequence, with the command for each step.`,
         };
     }
     finally {
@@ -206,9 +193,9 @@ async function describeCredential(runtime, origin, credential) {
         baseUrl: origin,
         credential,
         fetch: runtime.fetch,
-    }), origin);
+    }), origin, runtime.programName);
 }
-async function describeThrough(client, origin) {
+async function describeThrough(client, origin, programName) {
     try {
         return {
             context: responseSchemaFor("context.read")?.parse(await client.request("context_read")),
@@ -216,7 +203,9 @@ async function describeThrough(client, origin) {
         };
     }
     catch (error) {
-        if (!(error instanceof GreatwaitClientError)) {
+        if (!(error instanceof GreatwaitClientError) || error.status === 0) {
+            // The SDK uses status 0 when its transport retries are exhausted; older
+            // adapters may still throw the original network error.
             // **A transport failure is not an answer about the credential.** The
             // request never reached the service — no DNS, no TLS, a reset — so it
             // says nothing about what was just issued, and it does not carry a
@@ -226,7 +215,7 @@ async function describeThrough(client, origin) {
             // avoid, skipped because the failure never reached the reasoning.
             return {
                 known: false,
-                reason: `${origin} could not be reached to ask what this credential acts in (${error instanceof Error ? error.message : String(error)}). Run greatwait whoami when it is back.`,
+                reason: `${origin} could not be reached to ask what this credential acts in (${error instanceof Error ? error.message : String(error)}). Run ${programName} whoami when it is back.`,
             };
         }
         // **Only a refusal of the credential itself is fatal.** That is the whole
@@ -248,12 +237,12 @@ async function describeThrough(client, origin) {
         // learned rather than claiming the sign-in failed.
         return {
             known: false,
-            reason: `${origin} answered ${String(error.status)} when asked what this credential reaches, so it cannot be described yet. Run greatwait whoami again in a moment.`,
+            reason: `${origin} answered ${String(error.status)} when asked what this credential reaches, so it cannot be described yet. Run ${programName} whoami again in a moment.`,
         };
     }
 }
 const logout = async (runtime, args) => {
-    expectNoExtraArguments(args, 0, "greatwait logout [--api-url <origin>]");
+    expectNoExtraArguments(args, 0, `${runtime.programName} logout [--api-url <origin>]`);
     const store = storeFor(runtime);
     const { origin } = await resolveOrigin(runtime, store, apiUrlOption(args));
     const stored = await store.read(origin);
@@ -323,9 +312,9 @@ const CREDENTIAL_LABELS = {
     oauth: "an OAuth grant",
 };
 const whoami = async (runtime, args) => {
-    expectNoExtraArguments(args, 0, "greatwait whoami [--api-url <origin>]");
+    expectNoExtraArguments(args, 0, `${runtime.programName} whoami [--api-url <origin>]`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
-    const described = await describeThrough(session.client, session.origin);
+    const described = await describeThrough(session.client, session.origin, runtime.programName);
     if (!described.known) {
         // **Reported rather than guessed at.** The values could be inferred from a
         // destination or a key the project already owns, and a project that owns
@@ -372,7 +361,7 @@ const whoami = async (runtime, args) => {
     };
 };
 const doctor = async (runtime, args) => {
-    expectNoExtraArguments(args, 0, "greatwait doctor [--api-url <origin>]");
+    expectNoExtraArguments(args, 0, `${runtime.programName} doctor [--api-url <origin>]`);
     const store = storeFor(runtime);
     const checks = [];
     let origin;
@@ -408,7 +397,7 @@ const doctor = async (runtime, args) => {
             checks.push({
                 detail: error instanceof Error
                     ? error.message
-                    : "the origin did not answer as a Greatwait API",
+                    : "the origin did not answer as a GreatWait API",
                 name: "reachable",
                 outcome: "failed",
             });
@@ -437,7 +426,7 @@ const doctor = async (runtime, args) => {
     else {
         try {
             const session = await openSession(runtime, { apiUrl: origin });
-            const described = await describeThrough(session.client, origin);
+            const described = await describeThrough(session.client, origin, runtime.programName);
             // **`skipped`, not `passed`, when the service cannot say.** A `404` from
             // `/v1/context` arrives before anything looks at the credential, so a
             // check that reported success from one would be reporting that a
@@ -505,7 +494,7 @@ const context = async (runtime, args) => {
         };
     }
     if (action === "list") {
-        expectNoExtraArguments(args, 1, "greatwait context list");
+        expectNoExtraArguments(args, 1, `${runtime.programName} context list`);
         const origins = await store.origins();
         const selected = await store.readSelection();
         return {
@@ -520,12 +509,12 @@ const context = async (runtime, args) => {
     if (action === "use") {
         const wanted = args.command[1];
         if (wanted === undefined) {
-            throw new CliError("greatwait context use needs an origin", "usage");
+            throw new CliError(`${runtime.programName} context use needs an origin`, "usage");
         }
-        expectNoExtraArguments(args, 2, "greatwait context use <origin>");
+        expectNoExtraArguments(args, 2, `${runtime.programName} context use <origin>`);
         const origin = originKey(wanted);
         if ((await store.read(origin)) === undefined) {
-            throw new CliError(`no credential is stored for ${origin}`, "usage", `Sign in to it first: greatwait login --api-url ${origin}`);
+            throw new CliError(`no credential is stored for ${origin}`, "usage", `Sign in to it first: ${runtime.programName} login --api-url ${origin}`);
         }
         await store.select(origin);
         return {
@@ -533,14 +522,14 @@ const context = async (runtime, args) => {
             human: `Commands now go to ${origin} unless --api-url says otherwise.`,
         };
     }
-    throw new CliError(`unknown context command ${action}`, "usage", "Usage: greatwait context [list | use <origin>]");
+    throw new CliError(`unknown context command ${action}`, "usage", `Usage: ${runtime.programName} context [list | use <origin>]`);
 };
 /* -------------------------------------------------------------------------- */
 /* The journey                                                                */
 /* -------------------------------------------------------------------------- */
 const journey = async (runtime, args) => {
-    expectNoExtraArguments(args, 0, "greatwait journey");
-    const rendered = renderJourney();
+    expectNoExtraArguments(args, 0, `${runtime.programName} journey`);
+    const rendered = renderJourney(runtime.programName);
     // Named where it is known, because the journey's own first step is "confirm
     // which service and environment you reached" and a reader following this
     // list should not have to go and find out separately. Not knowing is not a
@@ -580,7 +569,7 @@ const journey = async (runtime, args) => {
 const destinationsCreate = async (runtime, args) => {
     const url = args.options["--url"];
     if (url === undefined) {
-        throw new CliError("greatwait destinations create needs --url", "usage", "Usage: greatwait destinations create --url https://your-receiver.example.com/greatwait");
+        throw new CliError(`${runtime.programName} destinations create needs --url`, "usage", `Usage: ${runtime.programName} destinations create --url https://your-receiver.example.com/greatwait`);
     }
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
     const created = responseSchemaFor("endpoints.create")?.parse(await session.client.request("endpoints_create", { url }));
@@ -596,92 +585,68 @@ const destinationsCreate = async (runtime, args) => {
             ``,
             `Signing key  ${created.secret}`,
             ``,
-            `This key is shown once and is not recoverable. Store it now — your receiver`,
+            `This is the only call that returns the key. Store it now — your receiver`,
             `verifies every callback with it, and reading this destination back will show`,
-            `${redactSecret(created.secret)} instead.`,
+            `${redactSecret(created.secret)} instead. If you lose it, a signed-in member`,
+            `can read it again on this destination's page in the dashboard; no command`,
+            `here can, because the reveal accepts a member session and not a grant.`,
         ].join("\n"),
-        nextMove: `Next: greatwait schedules create --endpoint ${created.id} --in 30s`,
+        nextMove: `Next: ${runtime.programName} schedules create --endpoint ${created.id} --in 30s`,
+    };
+};
+const destinationsEnable = async (runtime, args) => {
+    const [id] = positionals(args, ["<destination>"], `${runtime.programName} destinations enable <destination>`);
+    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const enabled = parseResponse("endpoints.enable", await session.client.request("endpoints_enable", id));
+    return {
+        data: { id: enabled.id, status: enabled.status, url: enabled.url },
+        human: `Destination ${enabled.id} is ${enabled.status}. Schedules pointed at ${enabled.url} deliver again from their next occurrence.`,
     };
 };
 const destinationsDisable = async (runtime, args) => {
-    const id = args.command[0];
-    if (id === undefined) {
-        throw new CliError("greatwait destinations disable needs a destination", "usage", "Usage: greatwait destinations disable <destination>");
-    }
-    expectNoExtraArguments(args, 1, "greatwait destinations disable <destination>");
+    const [id] = positionals(args, ["<destination>"], `${runtime.programName} destinations disable <destination>`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
-    const disabled = responseSchemaFor("endpoints.disable")?.parse(await session.client.request("endpoints_disable", id));
+    // Read first, so the preview names the receiver that stops hearing from us
+    // rather than repeating back the identifier that was typed.
+    const current = parseResponse("endpoints.read", await session.client.request("endpoints_read", id));
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Disable destination ${id}.`,
+        effect: [
+            `receiver     ${current.url}`,
+            `status       ${current.status}`,
+            `Nothing further is delivered there. Schedules pointing at it deliver`,
+            `nothing until it is enabled again or they are moved.`,
+        ],
+    });
+    const disabled = parseResponse("endpoints.disable", await session.client.request("endpoints_disable", id));
     return {
-        data: { id: disabled.id, status: disabled.status },
-        human: `Destination ${disabled.id} is ${disabled.status}. Nothing further is delivered to it, and the attempts already recorded against it stay readable.`,
+        data: { confirmation, id: disabled.id, status: disabled.status },
+        human: `Destination ${disabled.id} is ${disabled.status}. Nothing further is delivered to it until it is enabled again, and the attempts already recorded against it stay readable.`,
     };
 };
 /* -------------------------------------------------------------------------- */
 /* Schedules                                                                  */
 /* -------------------------------------------------------------------------- */
-/** The payload, from an argument, a file, or standard input. */
-async function readPayload(runtime, value) {
-    if (value === undefined)
-        return undefined;
-    const text = value === "-"
-        ? await runtime.readStdin()
-        : value.startsWith("@")
-            ? await readFile(value.slice(1), "utf8")
-            : value;
-    try {
-        return JSON.parse(text);
-    }
-    catch {
-        throw new CliError("--data is not JSON", "usage", "Pass a JSON object, @a-file.json, or - to read it from standard input.");
-    }
-}
-/**
- * An instant, in the exact spelling the contract publishes.
- *
- * **Refused here rather than by the service, and normalised on the way.**
- * `--in` was already read before anything was sent and `--at` was not, so
- * `--at "next tuesday"` cost a round trip and came back as `invalid_request` —
- * which calls a mistake in the command line a fault in the request. And the
- * ordinary ISO spelling somebody types, `2030-01-01T00:00:00Z`, is refused by
- * the contract for having no milliseconds; that is a real instant written a
- * normal way, so it is formatted rather than rejected. Nothing is guessed: a
- * value `Date` cannot read is refused, and the refusal says what a good one
- * looks like.
- */
-function parseInstant(value) {
-    const parsed = Date.parse(value);
-    if (Number.isNaN(parsed)) {
-        throw new CliError(`${value} is not an instant`, "usage", "Write it as UTC, such as 2030-01-01T09:00:00.000Z. For a delay from now, use --in 30s instead.");
-    }
-    return new Date(parsed).toISOString();
-}
 const schedulesCreate = async (runtime, args) => {
-    const endpoint = args.options["--endpoint"];
-    if (endpoint === undefined) {
-        throw new CliError("greatwait schedules create needs --endpoint", "usage", "Usage: greatwait schedules create --endpoint <destination> --in 30s");
-    }
-    const inValue = args.options["--in"];
-    const atValue = args.options["--at"];
-    if ((inValue === undefined) === (atValue === undefined)) {
-        throw new CliError("give exactly one of --in and --at", "usage", "Either --in 30s, or --at 2026-09-04T09:00:00.000Z.");
+    const usage = `${runtime.programName} schedules create --endpoint <destination> (--in <duration> | --at <instant> | --every <duration> | --cron <expression>)`;
+    if (args.options["--endpoint"] === undefined) {
+        throw new CliError(`${runtime.programName} schedules create needs --endpoint`, "usage", `Usage: ${usage}`);
     }
+    expectNoExtraArguments(args, 0, usage);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
-    const data = await readPayload(runtime, args.options["--data"]);
+    // **The same builder `schedules replace` uses.** The two send the identical
+    // definition — a replace is a create with an identifier — and writing the
+    // recurrence rules out twice is how one of them comes to accept a cron
+    // expression the other does not.
+    const request = await scheduleRequest(runtime, args, usage);
     // **Generated when it is not given, and printed either way.** A create that
     // silently invented a fresh key on every run would make a retry a second
     // schedule, which is the failure the key exists to prevent; a create that
     // hid the key would leave the caller unable to make that retry at all.
     const idempotencyKey = args.options["--idempotency-key"] ??
         `greatwait-cli-${runtime.randomUuid()}`;
-    const request = {
-        ...(data === undefined ? {} : { data }),
-        ...(inValue === undefined
-            ? { at: parseInstant(atValue) }
-            : { delaySeconds: parseDuration(inValue) }),
-        endpoint,
-    };
     const answer = await session.client.requestDetailed("schedules_create", request, { "Idempotency-Key": idempotencyKey });
-    const created = responseSchemaFor("schedules.create")?.parse(answer.body);
+    const created = parseResponse("schedules.create", answer.body);
     const replayed = answer.headers["Idempotency-Replayed"] === "true";
     return {
         data: {
@@ -704,15 +669,15 @@ const schedulesCreate = async (runtime, args) => {
                 ]
                 : []),
         ].join("\n"),
-        nextMove: `Next: greatwait occurrences wait ${created.schedule.id} ${created.occurrence.id}`,
+        nextMove: `Next: ${runtime.programName} occurrences wait ${created.schedule.id} ${created.occurrence.id}`,
     };
 };
 const schedulesRead = async (runtime, args) => {
     const id = args.command[0];
     if (id === undefined) {
-        throw new CliError("greatwait schedules read needs a schedule", "usage", "Usage: greatwait schedules read <schedule>");
+        throw new CliError(`${runtime.programName} schedules read needs a schedule`, "usage", `Usage: ${runtime.programName} schedules read <schedule>`);
     }
-    expectNoExtraArguments(args, 1, "greatwait schedules read <schedule>");
+    expectNoExtraArguments(args, 1, `${runtime.programName} schedules read <schedule>`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
     const answer = await session.client.requestDetailed("schedules_read", id);
     const view = responseSchemaFor("schedules.read")?.parse(answer.body);
@@ -739,6 +704,66 @@ const schedulesRead = async (runtime, args) => {
             }),
     };
 };
+const exportsCreate = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, `${runtime.programName} exports create`);
+    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const view = parseResponse("exports.create", await session.client.request("exports_create", {}));
+    return {
+        data: view,
+        human: `Export ${view.id} is ${view.state}; its consistency cutoff is ${view.cutoffAt}.`,
+        nextMove: `Next: ${runtime.programName} exports read ${view.id}`,
+    };
+};
+const exportsRead = async (runtime, args) => {
+    const [exportId] = positionals(args, ["<export>"], `${runtime.programName} exports read <export>`);
+    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const view = parseResponse("exports.read", await session.client.request("exports_read", exportId));
+    return {
+        data: view,
+        human: `Export ${view.id} is ${view.state}; its consistency cutoff is ${view.cutoffAt}.`,
+        ...(view.state === "complete"
+            ? {
+                nextMove: `Save the first bounded part: ${runtime.programName} exports part ${view.id} > ${view.id}.ndjson`,
+            }
+            : {}),
+    };
+};
+const exportsPart = async (runtime, args) => {
+    const [exportId] = positionals(args, ["<export>"], `${runtime.programName} exports part <export> [--cursor <cursor>]`);
+    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const cursor = args.options["--cursor"];
+    const part = parseResponse("exports.part", await session.client.request("exports_part", exportId, cursor === undefined ? {} : { cursor }));
+    if (part.nextCursor !== undefined && !args.booleans.has("--json")) {
+        runtime.stderr(`More to export. Append the next bounded part with: ${runtime.programName} exports part ${exportId} --cursor '${part.nextCursor}' >> ${part.fileName}\n`);
+    }
+    return {
+        data: part,
+        // The human form is the exact bounded file bytes, so shell redirection is
+        // safe. Metadata remains available through --json without interpreting
+        // customer payload fields.
+        human: part.content.endsWith("\n")
+            ? part.content.slice(0, -1)
+            : part.content,
+    };
+};
+const exportsCancel = async (runtime, args) => {
+    const [exportId] = positionals(args, ["<export>"], `${runtime.programName} exports cancel <export> [--yes]`);
+    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const current = parseResponse("exports.read", await session.client.request("exports_read", exportId));
+    const confirmation = await confirmChange(runtime, args, {
+        action: `Cancel export ${current.id}.`,
+        effect: [
+            `state        ${current.state}`,
+            `cutoff       ${current.cutoffAt}`,
+            "No further file parts can be downloaded from this job.",
+        ],
+    });
+    const answer = parseResponse("exports.cancel", await session.client.request("exports_cancel", exportId));
+    return {
+        data: { ...answer, confirmation },
+        human: `Export ${answer.export.id} is ${answer.export.state}.`,
+    };
+};
 /* -------------------------------------------------------------------------- */
 /* Waiting                                                                    */
 /* -------------------------------------------------------------------------- */
@@ -746,9 +771,9 @@ const occurrencesWait = async (runtime, args) => {
     const schedule = args.command[0];
     const occurrence = args.command[1];
     if (schedule === undefined || occurrence === undefined) {
-        throw new CliError("greatwait occurrences wait needs a schedule and an occurrence", "usage", "Usage: greatwait occurrences wait <schedule> <occurrence>");
+        throw new CliError(`${runtime.programName} occurrences wait needs a schedule and an occurrence`, "usage", `Usage: ${runtime.programName} occurrences wait <schedule> <occurrence>`);
     }
-    expectNoExtraArguments(args, 2, "greatwait occurrences wait <schedule> <occurrence>");
+    expectNoExtraArguments(args, 2, `${runtime.programName} occurrences wait <schedule> <occurrence>`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
     // The interval and the deadline come from the published journey. A number
     // here would be a fourth answer to a question the website, the curl page and
@@ -776,7 +801,7 @@ const occurrencesWait = async (runtime, args) => {
                     states: seen,
                 },
                 human: `Occurrence ${occurrence} settled ${state} after ${String(view.occurrence.attemptCount)} ${view.occurrence.attemptCount === 1 ? "attempt" : "attempts"}.`,
-                nextMove: `Next: greatwait attempts list ${schedule} ${occurrence}`,
+                nextMove: `Next: ${runtime.programName} attempts list ${schedule} ${occurrence}`,
             };
         }
         if (runtime.now() >= deadline) {
@@ -789,9 +814,9 @@ const attemptsList = async (runtime, args) => {
     const schedule = args.command[0];
     const occurrence = args.command[1];
     if (schedule === undefined || occurrence === undefined) {
-        throw new CliError("greatwait attempts list needs a schedule and an occurrence", "usage", "Usage: greatwait attempts list <schedule> <occurrence>");
+        throw new CliError(`${runtime.programName} attempts list needs a schedule and an occurrence`, "usage", `Usage: ${runtime.programName} attempts list <schedule> <occurrence>`);
     }
-    expectNoExtraArguments(args, 2, "greatwait attempts list <schedule> <occurrence>");
+    expectNoExtraArguments(args, 2, `${runtime.programName} attempts list <schedule> <occurrence>`);
     const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
     const page = responseSchemaFor("attempts.list")?.parse(await session.client.request("attempts_list", schedule, occurrence));
     const failed = page.data.find((attempt) => attempt.state !== "succeeded");
@@ -819,13 +844,26 @@ const attemptsList = async (runtime, args) => {
 /* -------------------------------------------------------------------------- */
 /* Dispatch                                                                   */
 /* -------------------------------------------------------------------------- */
-/** Every command, keyed by the words that select it. */
-export const COMMANDS = {
+/**
+ * Every implementation, keyed by the words that select it.
+ *
+ * Not the dispatch table: that is built from the catalog below, so a command
+ * cannot be documented without existing and cannot exist without being
+ * documented. This half is the functions, and `packages/cli/src/catalog.ts` is
+ * what says they are the right set.
+ */
+const IMPLEMENTATIONS = {
+    ...OPERATE_COMMANDS,
     "attempts list": attemptsList,
     context,
     "destinations create": destinationsCreate,
     "destinations disable": destinationsDisable,
+    "destinations enable": destinationsEnable,
     doctor,
+    "exports cancel": exportsCancel,
+    "exports create": exportsCreate,
+    "exports part": exportsPart,
+    "exports read": exportsRead,
     journey,
     login,
     logout,
@@ -834,3 +872,24 @@ export const COMMANDS = {
     "schedules read": schedulesRead,
     whoami,
 };
+/**
+ * The dispatch table, assembled from the catalog.
+ *
+ * **A declaration with no function raises here, at import.** The alternative
+ * was a test that compared two lists, which is a check the published reference
+ * page can still contradict: the page is generated from the catalog, so a
+ * command documented and never implemented would ship as a promise the
+ * executable does not keep. Raising means the binary does not start.
+ *
+ * The other direction is a test rather than a raise — an implementation nobody
+ * declared is unreachable rather than dangerous, and `commands.test.ts` names
+ * it.
+ */
+export const COMMANDS = Object.fromEntries(COMMAND_CATALOG.map((declaration) => {
+    const implementation = IMPLEMENTATIONS[declaration.words];
+    if (implementation === undefined) {
+        throw new Error(`${declaration.words} is declared in the catalog and implemented nowhere`);
+    }
+    return [declaration.words, implementation];
+}));
+export { IMPLEMENTATIONS };

package/dist/confirm.d.ts

@@ -0,0 +1,33 @@
+import type { ParsedArguments } from "./args.js";
+import { type CliRuntime } from "./runtime.js";
+/**
+ * The one policy for "are you sure", so no command invents its own.
+ *
+ * **The preview is printed whichever way the answer comes.** A confirmation
+ * that only appears on a terminal leaves an automated run with no record of
+ * what it agreed to, and the first question after an unexpected cancellation is
+ * "what exactly did it act on". So the scope goes to standard error always, and
+ * only the *asking* depends on there being somebody to ask.
+ *
+ * Automation is served by `--yes` rather than by a terminal check alone. A
+ * command that simply skipped the prompt when standard input was not a terminal
+ * would be a command that behaves differently inside a pipeline than in front
+ * of a person, silently, in the destructive direction — which is the shape of
+ * every "it deleted everything in CI" story. Without a terminal and without the
+ * flag, this refuses.
+ */
+export interface ChangePreview {
+    /** One line naming the act: "Cancel schedule sch_01…". */
+    readonly action: string;
+    /**
+     * The exact scope, as a person needs to see it before agreeing.
+     *
+     * Read from the service immediately before asking wherever there is
+     * something to read: the point is to show what *this* object is now, not to
+     * restate the arguments back.
+     */
+    readonly effect: readonly string[];
+}
+/** How the change came to be agreed, for the machine shape. */
+export type Confirmation = "flag" | "prompt";
+export declare function confirmChange(runtime: CliRuntime, args: ParsedArguments, preview: ChangePreview): Promise<Confirmation>;

package/dist/confirm.js

@@ -0,0 +1,17 @@
+import { CliError } from "./runtime.js";
+export async function confirmChange(runtime, args, preview) {
+    runtime.stderr(`${[preview.action, ...preview.effect.map((line) => `  ${line}`)].join("\n")}\n`);
+    if (args.booleans.has("--yes"))
+        return "flag";
+    if (!runtime.interactive) {
+        throw new CliError("this changes something that already exists, and there is no terminal to confirm on", "usage", "Pass --yes to confirm it without being asked.");
+    }
+    const answer = (await runtime.promptLine("Continue? [y/N] ")).trim();
+    // **Anything but an explicit yes is a no.** A blank line is what somebody
+    // types when they meant to read the preview first, and a prompt that took it
+    // as agreement would be a prompt that exists to be dismissed.
+    if (answer !== "y" && answer !== "yes") {
+        throw new CliError("not confirmed, so nothing was changed", "interrupted", "Nothing was sent to the service.");
+    }
+    return "prompt";
+}