@greatwait/cli 0.1.0-alpha.3

package/dist/commands.js

@@ -0,0 +1,836 @@
+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 { 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}`);
+}
+/* -------------------------------------------------------------------------- */
+/* Signing in                                                                 */
+/* -------------------------------------------------------------------------- */
+/**
+ * Reads an API credential without letting it reach the command line.
+ *
+ * Three sources, in the order that keeps a secret out of a process listing:
+ * anything piped in, then a hidden prompt on a terminal, and — for automation
+ * that has already put the value in its environment — the journey's own
+ * variable. There is deliberately no fourth.
+ */
+async function readApiKey(runtime) {
+    if (!runtime.interactive) {
+        const piped = (await runtime.readStdin()).trim();
+        if (piped !== "")
+            return piped;
+        const fromEnvironment = runtime.env[ENVIRONMENT_NAMES.apiKey];
+        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}.`);
+    }
+    const typed = (await runtime.promptSecret("Paste the API credential (it will not echo): ")).trim();
+    if (typed === "") {
+        throw new CliError("no credential was entered", "usage");
+    }
+    return typed;
+}
+const login = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, "greatwait login [--api-url <origin>] [--api-key] [--no-browser]");
+    const store = storeFor(runtime);
+    const requested = apiUrlOption(args);
+    const origin = requested === undefined
+        ? (await resolveOrigin(runtime, store, undefined)).origin
+        : originKey(requested);
+    if (args.booleans.has("--api-key")) {
+        const secret = await readApiKey(runtime);
+        // **Proved before it is stored.** A credential written to disk and refused
+        // on the next command is a credential somebody has to debug; this way the
+        // refusal names the fault while the person is still looking at the prompt.
+        const described = await describeCredential(runtime, origin, secret);
+        await store.write(origin, { kind: "api-key", secret });
+        await store.select(origin);
+        return {
+            data: {
+                ...(described.known ? { context: described.context } : {}),
+                credential: "api-key",
+                origin,
+            },
+            human: described.known
+                ? `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.`,
+        };
+    }
+    const server = await discover(runtime, origin);
+    const scopes = server.scopesSupported.length === 0
+        ? [...REQUESTED_SCOPES]
+        : REQUESTED_SCOPES.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");
+    }
+    // Bound first: the redirect URI is matched exactly, port included, so the
+    // port has to exist before the client is registered for it.
+    const listener = await runtime.listen();
+    try {
+        const clientId = await registerClient(runtime, server, {
+            redirectUri: listener.redirectUri,
+            scopes,
+        });
+        const authorization = await buildAuthorization(runtime, server, {
+            clientId,
+            redirectUri: listener.redirectUri,
+            scopes,
+        });
+        const noBrowser = args.booleans.has("--no-browser");
+        let opened = false;
+        if (!noBrowser) {
+            opened = await runtime
+                .openBrowser(authorization.authorizationUrl)
+                .then(() => true)
+                .catch(() => false);
+        }
+        // **Printed whether or not the browser opened.** A URL shown only when
+        // launching failed is a URL nobody on a remote shell ever sees, because
+        // `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 tokens = await exchangeCode(runtime, server, {
+            clientId,
+            code,
+            redirectUri: listener.redirectUri,
+            verifier: authorization.verifier,
+        });
+        // **Described before it is stored, like the API-key branch.** It used to
+        // write and select first, so a `500` from the description probe reported a
+        // failed sign-in while a live, selected grant sat on the disk — and a
+        // person or script that read the refusal as "nothing happened" had no
+        // reason to run `logout`. Whatever this command says, the disk now
+        // matches: a grant it refuses is a grant it does not keep, and a grant it
+        // keeps is one it reported keeping.
+        const described = await describeCredential(runtime, origin, tokens.accessToken).catch(async (error) => {
+            // **Only a refusal, and the narrowing is the whole of it.** The
+            // credential was minted seconds ago by this very exchange, so a `401` or
+            // a `403` is not a stale token — it is a service that will not let this
+            // grant act, and keeping it would leave somebody holding something that
+            // authenticated once and never again. Anything else reaching here is a
+            // defect in this command rather than an answer about the grant, and
+            // revoking on it would cost a person another consent for a fault that
+            // was never theirs.
+            if (error instanceof GreatwaitClientError &&
+                (error.status === 401 || error.status === 403)) {
+                await revoke(runtime, server, {
+                    clientId,
+                    token: tokens.refreshToken,
+                });
+            }
+            throw error;
+        });
+        await store.write(origin, {
+            accessToken: tokens.accessToken,
+            clientId,
+            expiresAtMs: runtime.now() + tokens.expiresInSeconds * 1000,
+            kind: "oauth",
+            refreshToken: tokens.refreshToken,
+            scope: tokens.scope,
+        });
+        await store.select(origin);
+        return {
+            data: {
+                ...(described.known ? { context: described.context } : {}),
+                credential: "oauth",
+                origin,
+                scopes: tokens.scope.split(" ").filter((scope) => scope !== ""),
+            },
+            human: described.known
+                ? `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.`,
+        };
+    }
+    finally {
+        listener.close();
+    }
+};
+async function describeCredential(runtime, origin, credential) {
+    return describeThrough(createGreatwaitClient({
+        baseUrl: origin,
+        credential,
+        fetch: runtime.fetch,
+    }), origin);
+}
+async function describeThrough(client, origin) {
+    try {
+        return {
+            context: responseSchemaFor("context.read")?.parse(await client.request("context_read")),
+            known: true,
+        };
+    }
+    catch (error) {
+        if (!(error instanceof GreatwaitClientError)) {
+            // **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
+            // status to classify. It used to be rethrown, which sent it to the
+            // caller's revoke-on-refusal path and destroyed a perfectly good grant
+            // over a network blip: the exact harm the reasoning below exists to
+            // 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.`,
+            };
+        }
+        // **Only a refusal of the credential itself is fatal.** That is the whole
+        // reason to make this call at sign-in, and it is the one answer that means
+        // the thing being stored will never work.
+        if (error.status === 401 || error.status === 403)
+            throw error;
+        if (error.status === 404) {
+            return {
+                known: false,
+                reason: `${origin} does not publish GET /v1/context, so it cannot say which project this credential acts in. It is running a build from before that operation existed.`,
+            };
+        }
+        // **Anything else is the service having a moment, not a bad credential.**
+        // A `500` or a `503` from this one read says nothing about what was just
+        // issued, and throwing the credential away over it would cost a person
+        // another consent — or another visit to the dashboard — for a fault that
+        // has already passed. It is kept, and the report says what could not be
+        // 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.`,
+        };
+    }
+}
+const logout = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, "greatwait logout [--api-url <origin>]");
+    const store = storeFor(runtime);
+    const { origin } = await resolveOrigin(runtime, store, apiUrlOption(args));
+    const stored = await store.read(origin);
+    if (stored === undefined) {
+        return {
+            data: { origin, removed: false, revoked: false },
+            human: `Nothing was stored for ${origin}.`,
+        };
+    }
+    let revoked = false;
+    if (stored.kind === "oauth" &&
+        stored.refreshToken !== undefined &&
+        stored.clientId !== undefined) {
+        // Best effort, and the local material goes either way: a logout that kept
+        // a credential on disk because the network was down would be the opposite
+        // of what was asked for.
+        const server = await discover(runtime, origin).catch(() => undefined);
+        if (server !== undefined) {
+            revoked = await revoke(runtime, server, {
+                clientId: stored.clientId,
+                token: stored.refreshToken,
+            });
+        }
+    }
+    await store.forget(origin);
+    if ((await store.readSelection()) === origin) {
+        await store.select(undefined);
+    }
+    // **A signed-out shell that still authenticates is worth saying out loud.**
+    // The environment credential is the non-interactive path and `logout` cannot
+    // unset a variable in the caller's shell — so a person who signs out and
+    // finds the next command working has been given no reason for it. Found by
+    // this command's own hosted harness, which inherited the variable and
+    // therefore proved nothing when it checked that signing out had worked.
+    const fromEnvironment = runtime.env[ENVIRONMENT_NAMES.apiKey];
+    const environmentStillSignsIn = fromEnvironment !== undefined && fromEnvironment !== "";
+    return {
+        data: {
+            environmentCredentialRemains: environmentStillSignsIn,
+            origin,
+            removed: true,
+            revoked,
+        },
+        human: stored.kind === "oauth"
+            ? revoked
+                ? `Signed out of ${origin}. The grant was revoked and the local tokens are gone.`
+                : `Signed out of ${origin}. The local tokens are gone; the service did not confirm the grant was revoked.`
+            : `Signed out of ${origin}. The stored credential is gone — revoke it in the dashboard if it should stop working everywhere.`,
+        ...(environmentStillSignsIn
+            ? {
+                nextMove: `${ENVIRONMENT_NAMES.apiKey} is still set in this shell, so commands here will keep authenticating with it. Unset it if you meant to stop.`,
+            }
+            : stored.kind === "oauth" && !revoked
+                ? {
+                    nextMove: "Check the connected applications list in the dashboard if you meant to end the grant everywhere.",
+                }
+                : {}),
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Where am I, and is anything wrong                                          */
+/* -------------------------------------------------------------------------- */
+/** How each kind of credential is named in output a person reads. */
+const CREDENTIAL_LABELS = {
+    "api-key": "a stored API credential",
+    "environment-key": `an API credential from ${ENVIRONMENT_NAMES.apiKey}`,
+    oauth: "an OAuth grant",
+};
+const whoami = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, "greatwait whoami [--api-url <origin>]");
+    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const described = await describeThrough(session.client, session.origin);
+    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
+        // neither is exactly the one somebody has just made — so an inference would
+        // be absent when it is first wanted and confidently wrong the rest of the
+        // time.
+        return {
+            data: {
+                credential: session.credentialKind,
+                origin: session.origin,
+                projectKnown: false,
+            },
+            human: [
+                `Service      ${session.origin}`,
+                `Credential   ${CREDENTIAL_LABELS[session.credentialKind]}`,
+                `Project      not published by this service`,
+                `Environment  not published by this service`,
+            ].join("\n"),
+            nextMove: described.reason,
+        };
+    }
+    const context = described.context;
+    return {
+        data: {
+            credential: session.credentialKind,
+            environmentKind: context.environmentKind,
+            origin: session.origin,
+            principal: context.principal,
+            project: context.project,
+            scopes: context.scopes,
+        },
+        human: [
+            `Service      ${session.origin}`,
+            `Credential   ${CREDENTIAL_LABELS[session.credentialKind]}`,
+            `Project      ${context.project}`,
+            `Environment  ${context.environmentKind}`,
+            `Permissions  ${context.scopes.join(", ")}`,
+        ].join("\n"),
+        ...(context.environmentKind === "live"
+            ? {
+                nextMove: "This is the live environment: anything you create here is delivered for real.",
+            }
+            : {}),
+    };
+};
+const doctor = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, "greatwait doctor [--api-url <origin>]");
+    const store = storeFor(runtime);
+    const checks = [];
+    let origin;
+    try {
+        origin = (await resolveOrigin(runtime, store, apiUrlOption(args))).origin;
+        checks.push({
+            detail: origin,
+            name: "service",
+            outcome: "passed",
+        });
+    }
+    catch (error) {
+        checks.push({
+            detail: error instanceof Error ? error.message : String(error),
+            name: "service",
+            outcome: "failed",
+        });
+    }
+    // Reachability and identity, with no credential — the journey's own first
+    // step, and the check that separates "wrong URL" from "wrong key".
+    let environment;
+    if (origin !== undefined) {
+        try {
+            const version = await anonymousClient(runtime, origin).getVersion();
+            environment = version.environment;
+            checks.push({
+                detail: `${version.service} in ${version.environment}, build ${version.buildSha.slice(0, 12)}`,
+                name: "reachable",
+                outcome: "passed",
+            });
+        }
+        catch (error) {
+            checks.push({
+                detail: error instanceof Error
+                    ? error.message
+                    : "the origin did not answer as a Greatwait API",
+                name: "reachable",
+                outcome: "failed",
+            });
+        }
+    }
+    const locations = store.locations();
+    const concerns = await directoryConcerns(locations, runtime.uid);
+    checks.push(concerns.length === 0
+        ? {
+            detail: `${locations.directory} is readable by its owner only`,
+            name: "configuration",
+            outcome: "passed",
+        }
+        : {
+            detail: concerns.join("; "),
+            name: "configuration",
+            outcome: "failed",
+        });
+    if (origin === undefined) {
+        checks.push({
+            detail: "no service was chosen, so no credential was checked",
+            name: "credential",
+            outcome: "skipped",
+        });
+    }
+    else {
+        try {
+            const session = await openSession(runtime, { apiUrl: origin });
+            const described = await describeThrough(session.client, origin);
+            // **`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
+            // credential works on the evidence that a route does not exist.
+            checks.push(described.known
+                ? {
+                    detail: `${session.credentialKind} in project ${described.context.project} (${described.context.environmentKind}), holding ${described.context.scopes.join(", ")}`,
+                    name: "credential",
+                    outcome: "passed",
+                }
+                : {
+                    detail: `${CREDENTIAL_LABELS[session.credentialKind]} is stored and was not checked — ${described.reason}`,
+                    name: "credential",
+                    outcome: "skipped",
+                });
+        }
+        catch (error) {
+            checks.push({
+                detail: error instanceof GreatwaitClientError
+                    ? `${error.problem?.code ?? String(error.status)}: ${error.problem?.title ?? error.message}`
+                    : error instanceof Error
+                        ? error.message
+                        : String(error),
+                name: "credential",
+                outcome: "failed",
+            });
+        }
+    }
+    const failed = checks.filter((check) => check.outcome === "failed");
+    return {
+        data: {
+            checks,
+            ...(environment === undefined ? {} : { environment }),
+            ok: failed.length === 0,
+        },
+        // **A failing `doctor` is an answer, not a raised error.** Its machine
+        // shape is a check per name with an outcome, and that shape is the same
+        // whichever way the answer went; raising put the rendered table into an
+        // error message, so a script asking which check failed got a paragraph to
+        // parse.
+        ...(failed.length === 0 ? {} : { exit: "validation" }),
+        human: checks
+            .map((check) => `${check.outcome === "passed" ? "ok  " : check.outcome === "failed" ? "fail" : "skip"}  ${check.name.padEnd(14)}${check.detail}`)
+            .join("\n"),
+        ...(failed.length === 0
+            ? {}
+            : {
+                nextMove: `${String(failed.length)} of ${String(checks.length)} checks failed.`,
+            }),
+    };
+};
+const context = async (runtime, args) => {
+    const store = storeFor(runtime);
+    const action = args.command[0];
+    if (action === undefined) {
+        const { origin, source } = await resolveOrigin(runtime, store, apiUrlOption(args));
+        return {
+            data: { origin, source },
+            human: `${origin} (${{
+                argument: "from --api-url",
+                environment: `from ${ENVIRONMENT_NAMES.apiUrl}`,
+                selection: "selected",
+                sole: "the only one signed in",
+            }[source]})`,
+        };
+    }
+    if (action === "list") {
+        expectNoExtraArguments(args, 1, "greatwait context list");
+        const origins = await store.origins();
+        const selected = await store.readSelection();
+        return {
+            data: { origins, ...(selected === undefined ? {} : { selected }) },
+            human: origins.length === 0
+                ? "No service is signed in."
+                : origins
+                    .map((entry) => `${entry === selected ? "*" : " "} ${entry}`)
+                    .join("\n"),
+        };
+    }
+    if (action === "use") {
+        const wanted = args.command[1];
+        if (wanted === undefined) {
+            throw new CliError("greatwait context use needs an origin", "usage");
+        }
+        expectNoExtraArguments(args, 2, "greatwait 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}`);
+        }
+        await store.select(origin);
+        return {
+            data: { origin, selected: true },
+            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>]");
+};
+/* -------------------------------------------------------------------------- */
+/* The journey                                                                */
+/* -------------------------------------------------------------------------- */
+const journey = async (runtime, args) => {
+    expectNoExtraArguments(args, 0, "greatwait journey");
+    const rendered = renderJourney();
+    // 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
+    // failure here: the sequence is worth reading before signing in to anything.
+    const chosen = await resolveOrigin(runtime, storeFor(runtime), apiUrlOption(args)).then((resolved) => resolved.origin, () => undefined);
+    const lines = [
+        ...(chosen === undefined
+            ? ["No service is chosen yet. Sign in when you reach step 2."]
+            : [`Against ${chosen}.`]),
+        ``,
+        "Before you start",
+        ...rendered.prerequisites.flatMap((prerequisite) => [
+            ``,
+            `  ${prerequisite.title}`,
+            `    ${prerequisite.action}`,
+            `    Why: ${prerequisite.because}`,
+        ]),
+        ``,
+        `First value, in ${String(rendered.steps.length)} steps`,
+        ...rendered.steps.flatMap((step, index) => [
+            ``,
+            `  ${String(index + 1)}. ${step.title}`,
+            `     ${step.purpose}`,
+            `     Look for: ${step.observe}`,
+            ...(step.command === undefined ? [] : [`     Run: ${step.command}`]),
+        ]),
+    ];
+    return {
+        data: { ...(chosen === undefined ? {} : { origin: chosen }), ...rendered },
+        human: lines.join("\n"),
+        nextMove: `Start with: ${STEP_COMMANDS["check-service"]}`,
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Destinations                                                               */
+/* -------------------------------------------------------------------------- */
+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");
+    }
+    const session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const created = responseSchemaFor("endpoints.create")?.parse(await session.client.request("endpoints_create", { url }));
+    return {
+        // **The secret is here and in no later output.** The service returns it
+        // from this call and from no other, which is the product behaviour rather
+        // than a limitation of this command — so printing it once, with the warning,
+        // is the only place it can honestly appear.
+        data: { id: created.id, secret: created.secret, status: created.status },
+        human: [
+            `Destination  ${created.id}`,
+            `Status       ${created.status}`,
+            ``,
+            `Signing key  ${created.secret}`,
+            ``,
+            `This key is shown once and is not recoverable. Store it now — your receiver`,
+            `verifies every callback with it, and reading this destination back will show`,
+            `${redactSecret(created.secret)} instead.`,
+        ].join("\n"),
+        nextMove: `Next: greatwait schedules create --endpoint ${created.id} --in 30s`,
+    };
+};
+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 session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const disabled = responseSchemaFor("endpoints.disable")?.parse(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.`,
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* 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 session = await openSession(runtime, { apiUrl: apiUrlOption(args) });
+    const data = await readPayload(runtime, args.options["--data"]);
+    // **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 replayed = answer.headers["Idempotency-Replayed"] === "true";
+    return {
+        data: {
+            idempotencyKey,
+            occurrence: created.occurrence.id,
+            plannedFor: created.occurrence.plannedFor,
+            replayed,
+            schedule: created.schedule.id,
+        },
+        human: [
+            `Schedule     ${created.schedule.id}`,
+            `Occurrence   ${created.occurrence.id}`,
+            `Planned for  ${created.occurrence.plannedFor}`,
+            `Retry key    ${idempotencyKey}`,
+            ...(replayed
+                ? [
+                    ``,
+                    `This key had already been used for this exact request, so nothing was`,
+                    `created a second time and no second callback will be delivered.`,
+                ]
+                : []),
+        ].join("\n"),
+        nextMove: `Next: greatwait 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>");
+    }
+    expectNoExtraArguments(args, 1, "greatwait 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);
+    const etag = answer.headers["ETag"];
+    return {
+        data: {
+            ...(etag === undefined ? {} : { etag }),
+            recurrence: view.schedule.recurrence.kind,
+            schedule: view.schedule.id,
+            status: view.schedule.status,
+            version: view.schedule.version,
+        },
+        human: [
+            `Schedule     ${view.schedule.id}`,
+            `Status       ${view.schedule.status}`,
+            `Recurrence   ${view.schedule.recurrence.kind}`,
+            `Version      ${String(view.schedule.version)}`,
+            ...(etag === undefined ? [] : [`ETag         ${etag}`]),
+        ].join("\n"),
+        ...(etag === undefined
+            ? {}
+            : {
+                nextMove: "Send that ETag back in If-Match to make a later pause, replace or cancel conditional on nothing having changed in between.",
+            }),
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Waiting                                                                    */
+/* -------------------------------------------------------------------------- */
+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>");
+    }
+    expectNoExtraArguments(args, 2, "greatwait 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
+    // the JavaScript page already answer identically.
+    const { intervalMs, timeoutMs } = publishedWait();
+    const override = args.options["--timeout"];
+    const deadline = runtime.now() +
+        (override === undefined ? timeoutMs : parseDuration(override) * 1000);
+    const seen = [];
+    for (;;) {
+        const view = responseSchemaFor("occurrences.read")?.parse(await session.client.request("occurrences_read", schedule, occurrence));
+        const state = view.occurrence.state;
+        if (seen[seen.length - 1] !== state) {
+            seen.push(state);
+            runtime.stderr(`  ${state}\n`);
+        }
+        if (isTerminalOccurrenceState(state)) {
+            return {
+                data: {
+                    attempts: view.occurrence.attemptCount,
+                    occurrence,
+                    schedule,
+                    settled: true,
+                    state,
+                    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}`,
+            };
+        }
+        if (runtime.now() >= deadline) {
+            throw new CliError(`occurrence ${occurrence} was still ${state} when the deadline passed`, "timeout", recoveryFor("await-occurrence", "not-settled"));
+        }
+        await sleepOrAbort(runtime, intervalMs);
+    }
+};
+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>");
+    }
+    expectNoExtraArguments(args, 2, "greatwait 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");
+    return {
+        data: { attempts: page.data, occurrence, schedule },
+        human: page.data.length === 0
+            ? "No attempt has been made yet."
+            : page.data
+                .map((attempt) => `${attempt.state.padEnd(20)}${attempt.responseStatus === undefined ? "no response" : `answered ${String(attempt.responseStatus)}`}${attempt.diagnostic === undefined ? "" : `  ${attempt.diagnostic}`}${attempt.remediation === undefined ? "" : ` / ${attempt.remediation}`}`)
+                .join("\n"),
+        // **The journey's own sentence, not a paraphrase of the code.**
+        // `diagnostic` and `remediation` are closed vocabularies rather than prose
+        // — the step's `observe` says to read them, and its recovery entry is the
+        // sentence written for a person meeting a failed attempt. Inventing a
+        // second one here would be this command maintaining its own copy of every
+        // delivery failure the service can classify.
+        ...(failed === undefined
+            ? {}
+            : (() => {
+                const nextMove = recoveryFor("read-attempt", "attempt-failed");
+                return nextMove === undefined ? {} : { nextMove };
+            })()),
+    };
+};
+/* -------------------------------------------------------------------------- */
+/* Dispatch                                                                   */
+/* -------------------------------------------------------------------------- */
+/** Every command, keyed by the words that select it. */
+export const COMMANDS = {
+    "attempts list": attemptsList,
+    context,
+    "destinations create": destinationsCreate,
+    "destinations disable": destinationsDisable,
+    doctor,
+    journey,
+    login,
+    logout,
+    "occurrences wait": occurrencesWait,
+    "schedules create": schedulesCreate,
+    "schedules read": schedulesRead,
+    whoami,
+};