@greatwait/cli 0.1.0-alpha.3

package/dist/config.d.ts

@@ -0,0 +1,74 @@
+export interface StoredCredential {
+    /** `api-key` carries `secret`; `oauth` carries the token set. */
+    readonly kind: "api-key" | "oauth";
+    readonly secret?: string;
+    readonly accessToken?: string;
+    readonly refreshToken?: string;
+    /** Epoch milliseconds. Absent for an API key, which does not rotate itself. */
+    readonly expiresAtMs?: number;
+    /** The dynamically registered client, needed to refresh and to revoke. */
+    readonly clientId?: string;
+    readonly scope?: string;
+}
+export interface ConfigLocations {
+    readonly credentials: string;
+    readonly directory: string;
+    readonly selection: string;
+}
+/**
+ * The configuration directory for this platform.
+ *
+ * `XDG_CONFIG_HOME` wins wherever it is set, including on macOS and Windows:
+ * somebody who has set it has said where their configuration goes, and a tool
+ * that ignores it puts a file where they will not find it. Otherwise the
+ * platform's own convention — `%APPDATA%` on Windows, Application Support on
+ * macOS, `~/.config` elsewhere.
+ *
+ * Both inputs are parameters rather than reads of `process`, because the
+ * refusals below have to be exercised on a platform the test is not running on.
+ */
+export declare function configDirectory(options: {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly home: string;
+    readonly platform: string;
+}): string;
+export declare function configLocations(options: {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly home: string;
+    readonly platform: string;
+}): ConfigLocations;
+/** The default home, read once here so nothing else touches the environment. */
+export declare function defaultHome(): string;
+export declare class UnsafeConfigError extends Error {
+    readonly path: string;
+    constructor(path: string, reason: string);
+}
+/** A stored origin key: scheme and authority, lower case, no trailing slash. */
+export declare function originKey(apiUrl: string): string;
+export interface CredentialStore {
+    forget(origin: string): Promise<void>;
+    locations(): ConfigLocations;
+    read(origin: string): Promise<StoredCredential | undefined>;
+    origins(): Promise<readonly string[]>;
+    readSelection(): Promise<string | undefined>;
+    select(origin: string | undefined): Promise<void>;
+    write(origin: string, credential: StoredCredential): Promise<void>;
+}
+export declare function createCredentialStore(options: {
+    readonly env: Readonly<Record<string, string | undefined>>;
+    readonly home: string;
+    readonly platform: string;
+    /** `undefined` on a platform whose file mode says nothing about access. */
+    readonly uid: number | undefined;
+}): CredentialStore;
+/**
+ * Whether the configuration directory itself is owner-only.
+ *
+ * Reported by `doctor` rather than refused on every read: a directory a group
+ * can list is not a directory a group can read a `0600` file out of, so this is
+ * a warning about the next file somebody puts there rather than a reason to
+ * refuse the one already checked.
+ */
+export declare function directoryConcerns(paths: ConfigLocations, uid: number | undefined): Promise<readonly string[]>;
+export declare const CONFIG_FILE_MODE = 384;
+export declare const CONFIG_DIRECTORY_MODE = 448;

package/dist/config.js

@@ -0,0 +1,242 @@
+import { chmod, lstat, mkdir, readFile, readdir, rename, rm, writeFile, } from "node:fs/promises";
+import { homedir } from "node:os";
+import { dirname, posix, win32 } from "node:path";
+/**
+ * Where a credential and the remembered origin live, and what makes a file here
+ * safe to read.
+ *
+ * **Per origin, and the origin is the key.** A person working against staging
+ * and production has two credentials, and the failure this arrangement exists
+ * to prevent is one being presented to the other — "staging can never answer as
+ * production", which is a property of *storage* rather than of a flag somebody
+ * remembers to pass. There is no merged view: a lookup takes an origin and
+ * either finds that origin's material or finds nothing.
+ *
+ * **Owner-only, checked on read rather than promised on write.** Writing `0600`
+ * says nothing about a file that already existed, was restored from a backup,
+ * or was created by a different tool. The refusals below are what a reader can
+ * rely on, and they are refusals rather than repairs: a file this process did
+ * not create, whose permissions it does not recognise, is one whose contents it
+ * has no business trusting either.
+ */
+/** The one file secrets live in. Split from `config.json` so the two can differ
+ *  in permissions and in what a diagnostic may print. */
+const CREDENTIALS_FILE = "credentials.json";
+const SELECTION_FILE = "config.json";
+const OWNER_ONLY_FILE = 0o600;
+const OWNER_ONLY_DIRECTORY = 0o700;
+/**
+ * The configuration directory for this platform.
+ *
+ * `XDG_CONFIG_HOME` wins wherever it is set, including on macOS and Windows:
+ * somebody who has set it has said where their configuration goes, and a tool
+ * that ignores it puts a file where they will not find it. Otherwise the
+ * platform's own convention — `%APPDATA%` on Windows, Application Support on
+ * macOS, `~/.config` elsewhere.
+ *
+ * Both inputs are parameters rather than reads of `process`, because the
+ * refusals below have to be exercised on a platform the test is not running on.
+ */
+export function configDirectory(options) {
+    // **The path flavour follows the platform argument, not the machine.**
+    // `join` from `node:path` is whichever one this process happens to be
+    // running on, so a `win32` branch built with it produces forward slashes
+    // everywhere but Windows — and a case that asserts the result with the same
+    // `join` agrees with it. On a real Windows process the two are identical;
+    // what this buys is that the injected platform is honestly injected.
+    const paths = options.platform === "win32" ? win32 : posix;
+    const xdg = options.env["XDG_CONFIG_HOME"];
+    if (xdg !== undefined && xdg !== "") {
+        return paths.join(xdg, "greatwait");
+    }
+    if (options.platform === "win32") {
+        const appData = options.env["APPDATA"];
+        return paths.join(appData !== undefined && appData !== ""
+            ? appData
+            : paths.join(options.home, "AppData", "Roaming"), "greatwait");
+    }
+    if (options.platform === "darwin") {
+        return paths.join(options.home, "Library", "Application Support", "greatwait");
+    }
+    return paths.join(options.home, ".config", "greatwait");
+}
+export function configLocations(options) {
+    // The same flavour the directory above was built with. Mixing them produced
+    // a path whose directory part used backslashes and whose filename was
+    // appended with a forward slash — never reachable in production, where the
+    // native `join` and the real platform always agree, and exactly the
+    // inconsistency that makes an injected-platform case prove less than it
+    // looks like it proves.
+    const paths = options.platform === "win32" ? win32 : posix;
+    const directory = configDirectory(options);
+    return {
+        credentials: paths.join(directory, CREDENTIALS_FILE),
+        directory,
+        selection: paths.join(directory, SELECTION_FILE),
+    };
+}
+/** The default home, read once here so nothing else touches the environment. */
+export function defaultHome() {
+    return homedir();
+}
+export class UnsafeConfigError extends Error {
+    path;
+    constructor(path, reason) {
+        super(`${path} ${reason}`);
+        this.name = "UnsafeConfigError";
+        this.path = path;
+    }
+}
+/**
+ * Reads a file this process is willing to trust, or refuses saying why.
+ *
+ * **`lstat`, not `stat`.** A symbolic link is followed by `stat`, so a check
+ * built on it describes the target while the thing being opened is the link —
+ * and a link is how a file with safe-looking permissions points at one without
+ * them. Refusing the link outright is the only answer that does not depend on
+ * winning a race with whoever can replace it.
+ *
+ * A missing file is not an error: it is the state before `login`.
+ */
+async function readTrusted(path, uid) {
+    let entry;
+    try {
+        entry = await lstat(path);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return undefined;
+        throw error;
+    }
+    if (entry.isSymbolicLink()) {
+        throw new UnsafeConfigError(path, "is a symbolic link; a credential file is read only where it is stored");
+    }
+    if (!entry.isFile()) {
+        throw new UnsafeConfigError(path, "is not a regular file");
+    }
+    if (uid !== undefined && entry.uid !== uid) {
+        throw new UnsafeConfigError(path, `is owned by uid ${String(entry.uid)} and this process is uid ${String(uid)}`);
+    }
+    // **Group and other, not an exact mode.** `0400` and `0600` are both fine and
+    // an equality check would refuse one of them; what matters is that nobody
+    // else can read it. Windows reports a mode that says nothing about access
+    // control, which is why the caller passes `undefined` for `uid` there and
+    // this bit is skipped with it.
+    if (uid !== undefined && (entry.mode & 0o077) !== 0) {
+        throw new UnsafeConfigError(path, `is readable by somebody other than its owner (mode ${(entry.mode & 0o777).toString(8).padStart(3, "0")}); run chmod 600 on it or delete it and sign in again`);
+    }
+    return readFile(path, "utf8");
+}
+async function writeOwnerOnly(path, text) {
+    await mkdir(dirname(path), { mode: OWNER_ONLY_DIRECTORY, recursive: true });
+    // **A temporary file and a rename, so a crash cannot leave half a token
+    // set.** The rename is atomic within a directory, and the mode is set on the
+    // temporary file before anything is written into it rather than after — a
+    // file that is briefly world-readable while it holds a credential is a file
+    // that was world-readable while it held a credential.
+    const temporary = `${path}.${String(process.pid)}.tmp`;
+    await writeFile(temporary, text, { mode: OWNER_ONLY_FILE });
+    await chmod(temporary, OWNER_ONLY_FILE);
+    await rename(temporary, path);
+}
+/** A stored origin key: scheme and authority, lower case, no trailing slash. */
+export function originKey(apiUrl) {
+    const url = new URL(apiUrl);
+    if (url.protocol !== "https:" && url.protocol !== "http:") {
+        throw new Error(`${apiUrl} is not an http or https origin`);
+    }
+    return url.origin.toLowerCase();
+}
+export function createCredentialStore(options) {
+    const paths = configLocations(options);
+    async function readCredentials() {
+        const text = await readTrusted(paths.credentials, options.uid);
+        if (text === undefined)
+            return { origins: {}, version: 1 };
+        let parsed;
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new UnsafeConfigError(paths.credentials, "is not readable as JSON; delete it and sign in again");
+        }
+        const origins = parsed.origins;
+        if (typeof origins !== "object" || origins === null) {
+            throw new UnsafeConfigError(paths.credentials, "does not carry an `origins` object; delete it and sign in again");
+        }
+        return {
+            origins: origins,
+            version: 1,
+        };
+    }
+    return {
+        async forget(origin) {
+            const file = await readCredentials();
+            const remaining = Object.fromEntries(Object.entries(file.origins).filter(([key]) => key !== origin));
+            if (Object.keys(remaining).length === 0) {
+                // Nothing left to hold: remove the file rather than leaving an empty
+                // one, so `logout` leaves no trace that there was ever a credential.
+                await rm(paths.credentials, { force: true });
+                return;
+            }
+            await writeOwnerOnly(paths.credentials, `${JSON.stringify({ origins: remaining, version: 1 }, null, 2)}\n`);
+        },
+        locations: () => paths,
+        async origins() {
+            return Object.keys((await readCredentials()).origins).sort();
+        },
+        async read(origin) {
+            return (await readCredentials()).origins[origin];
+        },
+        async readSelection() {
+            const text = await readTrusted(paths.selection, options.uid);
+            if (text === undefined)
+                return undefined;
+            try {
+                return JSON.parse(text).selected;
+            }
+            catch {
+                throw new UnsafeConfigError(paths.selection, "is not readable as JSON; delete it and select an origin again");
+            }
+        },
+        async select(origin) {
+            const body = origin === undefined
+                ? { version: 1 }
+                : { selected: origin, version: 1 };
+            await writeOwnerOnly(paths.selection, `${JSON.stringify(body, null, 2)}\n`);
+        },
+        async write(origin, credential) {
+            const file = await readCredentials();
+            await writeOwnerOnly(paths.credentials, `${JSON.stringify({ origins: { ...file.origins, [origin]: credential }, version: 1 }, null, 2)}\n`);
+        },
+    };
+}
+/**
+ * Whether the configuration directory itself is owner-only.
+ *
+ * Reported by `doctor` rather than refused on every read: a directory a group
+ * can list is not a directory a group can read a `0600` file out of, so this is
+ * a warning about the next file somebody puts there rather than a reason to
+ * refuse the one already checked.
+ */
+export async function directoryConcerns(paths, uid) {
+    if (uid === undefined)
+        return [];
+    try {
+        const entry = await lstat(paths.directory);
+        if ((entry.mode & 0o077) !== 0) {
+            return [
+                `${paths.directory} is reachable by somebody other than its owner (mode ${(entry.mode & 0o777).toString(8).padStart(3, "0")}); chmod 700 it`,
+            ];
+        }
+        await readdir(paths.directory);
+        return [];
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        return [`${paths.directory} could not be read: ${String(error)}`];
+    }
+}
+export const CONFIG_FILE_MODE = OWNER_ONLY_FILE;
+export const CONFIG_DIRECTORY_MODE = OWNER_ONLY_DIRECTORY;

package/dist/exit.d.ts

@@ -0,0 +1,58 @@
+/**
+ * What the shell learns when `greatwait` stops.
+ *
+ * **Classes rather than one code per failure.** A script branching on an exit
+ * status needs to know what to *do* — retry, fix the request, get a new
+ * credential, give up — and a code per problem makes that a lookup table the
+ * caller has to maintain against a list that grows. The public problem code is
+ * still there, in `--json` and in the human message; this is the coarse
+ * decision, and the two are published together so neither has to carry the
+ * other's job.
+ *
+ * The numbers are the contract. They may not be renumbered: a script that
+ * branches on `4` is the whole reason to have them.
+ */
+export declare const EXIT_CLASSES: {
+    /** The command did what it was asked. */
+    readonly ok: 0;
+    /**
+     * The command could not do what it was asked, for a reason it did not
+     * anticipate. Reserved for a defect: every refusal the service publishes has
+     * a class of its own below.
+     */
+    readonly internal: 1;
+    /** The command line was wrong — an unknown command, a missing argument. */
+    readonly usage: 2;
+    /** No usable credential. `greatwait login`. */
+    readonly authentication: 3;
+    /** A credential that authenticated and may not do this. */
+    readonly authorization: 4;
+    /** The request was refused on its merits: invalid, missing, or conflicting. */
+    readonly validation: 5;
+    /** The service could not answer now. The identical request may work later. */
+    readonly retryable: 6;
+    /** A deadline this command was given passed before the answer arrived. */
+    readonly timeout: 7;
+    /**
+     * Interrupted.
+     *
+     * 130 rather than 8, because `128 + SIGINT` is what a shell reports for a
+     * process killed by Ctrl-C and what `$?` is compared against in every script
+     * that checks. A private number here would be a second answer to a question
+     * POSIX already answers.
+     */
+    readonly interrupted: 130;
+};
+export type ExitClass = keyof typeof EXIT_CLASSES;
+/**
+ * The class an HTTP status falls in.
+ *
+ * **Status rather than problem code, and the two are checked in that order.**
+ * A refusal from an edge proxy carries no problem document at all — there is no
+ * code to read — and a client that branched on the code first would classify
+ * every one of those as internal. The code refines the answer where it
+ * disagrees with the status, which is exactly once: `scope_missing` is a `403`
+ * and belongs in `authorization`, and everything else in the 4xx range that is
+ * not authentication is the caller's request to fix.
+ */
+export declare function classifyStatus(status: number, problemCode?: string): ExitClass;

package/dist/exit.js

@@ -0,0 +1,73 @@
+/**
+ * What the shell learns when `greatwait` stops.
+ *
+ * **Classes rather than one code per failure.** A script branching on an exit
+ * status needs to know what to *do* — retry, fix the request, get a new
+ * credential, give up — and a code per problem makes that a lookup table the
+ * caller has to maintain against a list that grows. The public problem code is
+ * still there, in `--json` and in the human message; this is the coarse
+ * decision, and the two are published together so neither has to carry the
+ * other's job.
+ *
+ * The numbers are the contract. They may not be renumbered: a script that
+ * branches on `4` is the whole reason to have them.
+ */
+export const EXIT_CLASSES = {
+    /** The command did what it was asked. */
+    ok: 0,
+    /**
+     * The command could not do what it was asked, for a reason it did not
+     * anticipate. Reserved for a defect: every refusal the service publishes has
+     * a class of its own below.
+     */
+    internal: 1,
+    /** The command line was wrong — an unknown command, a missing argument. */
+    usage: 2,
+    /** No usable credential. `greatwait login`. */
+    authentication: 3,
+    /** A credential that authenticated and may not do this. */
+    authorization: 4,
+    /** The request was refused on its merits: invalid, missing, or conflicting. */
+    validation: 5,
+    /** The service could not answer now. The identical request may work later. */
+    retryable: 6,
+    /** A deadline this command was given passed before the answer arrived. */
+    timeout: 7,
+    /**
+     * Interrupted.
+     *
+     * 130 rather than 8, because `128 + SIGINT` is what a shell reports for a
+     * process killed by Ctrl-C and what `$?` is compared against in every script
+     * that checks. A private number here would be a second answer to a question
+     * POSIX already answers.
+     */
+    interrupted: 130,
+};
+/**
+ * The class an HTTP status falls in.
+ *
+ * **Status rather than problem code, and the two are checked in that order.**
+ * A refusal from an edge proxy carries no problem document at all — there is no
+ * code to read — and a client that branched on the code first would classify
+ * every one of those as internal. The code refines the answer where it
+ * disagrees with the status, which is exactly once: `scope_missing` is a `403`
+ * and belongs in `authorization`, and everything else in the 4xx range that is
+ * not authentication is the caller's request to fix.
+ */
+export function classifyStatus(status, problemCode) {
+    if (problemCode === "scope_missing")
+        return "authorization";
+    if (status === 401)
+        return "authentication";
+    if (status === 403)
+        return "authorization";
+    if (status === 408 || status === 504)
+        return "timeout";
+    if (status === 429)
+        return "retryable";
+    if (status >= 500)
+        return "retryable";
+    if (status >= 400)
+        return "validation";
+    return "ok";
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { run, USAGE } from "./cli.js";
+export { COMMANDS } from "./commands.js";
+export { configDirectory, configLocations, createCredentialStore, originKey, UnsafeConfigError, type CredentialStore, type StoredCredential, } from "./config.js";
+export { EXIT_CLASSES, classifyStatus, type ExitClass } from "./exit.js";
+export { nodeRuntime, openLoopback } from "./node-runtime.js";
+export { OUTPUT_VERSION, redactSecret, renderFailure, renderResult, } from "./output.js";
+export { parseArguments, parseDuration } from "./args.js";
+export { publishedWait, renderJourney, STEP_COMMANDS } from "./journey.js";
+export { CliError, InterruptedError, type CliRuntime, type LoopbackListener, } from "./runtime.js";

package/dist/index.js

@@ -0,0 +1,9 @@
+export { run, USAGE } from "./cli.js";
+export { COMMANDS } from "./commands.js";
+export { configDirectory, configLocations, createCredentialStore, originKey, UnsafeConfigError, } from "./config.js";
+export { EXIT_CLASSES, classifyStatus } from "./exit.js";
+export { nodeRuntime, openLoopback } from "./node-runtime.js";
+export { OUTPUT_VERSION, redactSecret, renderFailure, renderResult, } from "./output.js";
+export { parseArguments, parseDuration } from "./args.js";
+export { publishedWait, renderJourney, STEP_COMMANDS } from "./journey.js";
+export { CliError, InterruptedError, } from "./runtime.js";

package/dist/journey.d.ts

@@ -0,0 +1,49 @@
+import { type JourneyStep } from "@greatwait/contracts";
+/**
+ * The published first-value sequence, rendered for a terminal.
+ *
+ * **Rendered, not restated.** The steps, their purposes, what to look at, and
+ * what to do when each one goes wrong are all in the journey declaration that
+ * ships in `@greatwait/contracts`, because the website, the curl page, the
+ * JavaScript page and this command all need the same sentences and none of them
+ * may own them. A second description here would be a fourth answer to a
+ * question that has one, and it would drift on the first contract change
+ * nobody remembered to mirror.
+ *
+ * The one thing this adds is the command that performs each step, which is a
+ * fact about this surface and about no other.
+ */
+/** The command in this CLI that performs each journey step. */
+export declare const STEP_COMMANDS: Readonly<Record<string, string>>;
+export interface RenderedStep {
+    readonly command: string | undefined;
+    readonly key: string;
+    readonly needs: readonly string[];
+    readonly observe: string;
+    readonly purpose: string;
+    readonly title: string;
+}
+export declare function renderStep(step: JourneyStep): RenderedStep;
+export declare function renderJourney(): {
+    readonly prerequisites: readonly {
+        readonly action: string;
+        readonly because: string;
+        readonly title: string;
+    }[];
+    readonly steps: readonly RenderedStep[];
+};
+/**
+ * The wait the journey publishes, for the one command that waits.
+ *
+ * **Read rather than chosen.** `await-occurrence` declares the interval and the
+ * deadline, and the website, the curl page and the JavaScript page all wait
+ * exactly that long. A number here would be a fourth answer to a question with
+ * one, and the first person to notice would be the one whose command gave up
+ * before the documentation said it would.
+ */
+export declare function publishedWait(): {
+    readonly intervalMs: number;
+    readonly timeoutMs: number;
+};
+/** The recovery the journey publishes for a named condition, if it has one. */
+export declare function recoveryFor(stepKey: string, when: string): string | undefined;

package/dist/journey.js

@@ -0,0 +1,76 @@
+import { FIRST_VALUE_JOURNEY, journeyStepVariables, } from "@greatwait/contracts";
+/**
+ * The published first-value sequence, rendered for a terminal.
+ *
+ * **Rendered, not restated.** The steps, their purposes, what to look at, and
+ * what to do when each one goes wrong are all in the journey declaration that
+ * ships in `@greatwait/contracts`, because the website, the curl page, the
+ * JavaScript page and this command all need the same sentences and none of them
+ * may own them. A second description here would be a fourth answer to a
+ * question that has one, and it would drift on the first contract change
+ * nobody remembered to mirror.
+ *
+ * The one thing this adds is the command that performs each step, which is a
+ * fact about this surface and about no other.
+ */
+/** The command in this CLI that performs each journey step. */
+export const STEP_COMMANDS = {
+    "await-occurrence": "greatwait occurrences wait <schedule> <occurrence>",
+    "check-credential": "greatwait whoami",
+    "check-service": "greatwait doctor",
+    "clean-up": "greatwait destinations disable <destination>",
+    "create-destination": "greatwait destinations create --url <your receiver>",
+    "create-one-shot": "greatwait schedules create --endpoint <destination> --in 30s",
+    "read-attempt": "greatwait attempts list <schedule> <occurrence>",
+    "read-schedule": "greatwait schedules read <schedule>",
+    "replay-one-shot": "greatwait schedules create --endpoint <destination> --in 30s --idempotency-key <the same key>",
+};
+export function renderStep(step) {
+    return {
+        command: STEP_COMMANDS[step.key],
+        key: step.key,
+        // What the step must be given, as the journey names it — the path
+        // parameters an earlier step captured, and the references in its body and
+        // headers. The join is published rather than re-derived here.
+        needs: [...journeyStepVariables(step)],
+        observe: step.observe,
+        purpose: step.purpose,
+        title: step.title,
+    };
+}
+export function renderJourney() {
+    return {
+        prerequisites: FIRST_VALUE_JOURNEY.prerequisites.map((prerequisite) => ({
+            action: prerequisite.action,
+            because: prerequisite.because,
+            title: prerequisite.title,
+        })),
+        steps: FIRST_VALUE_JOURNEY.steps.map(renderStep),
+    };
+}
+/**
+ * The wait the journey publishes, for the one command that waits.
+ *
+ * **Read rather than chosen.** `await-occurrence` declares the interval and the
+ * deadline, and the website, the curl page and the JavaScript page all wait
+ * exactly that long. A number here would be a fourth answer to a question with
+ * one, and the first person to notice would be the one whose command gave up
+ * before the documentation said it would.
+ */
+export function publishedWait() {
+    const step = FIRST_VALUE_JOURNEY.steps.find((candidate) => candidate.key === "await-occurrence");
+    const poll = step?.poll;
+    if (poll === undefined) {
+        throw new Error("the published journey no longer declares a poll for await-occurrence");
+    }
+    return {
+        intervalMs: poll.intervalSeconds * 1000,
+        timeoutMs: poll.timeoutSeconds * 1000,
+    };
+}
+/** The recovery the journey publishes for a named condition, if it has one. */
+export function recoveryFor(stepKey, when) {
+    return FIRST_VALUE_JOURNEY.steps
+        .find((step) => step.key === stepKey)
+        ?.recovery.find((entry) => entry.when === when)?.nextMove;
+}

package/dist/main.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/main.js

@@ -0,0 +1,24 @@
+#!/usr/bin/env node
+import { run } from "./cli.js";
+import { nodeRuntime } from "./node-runtime.js";
+/**
+ * The installed executable.
+ *
+ * **The whole file is the part the repository's own test suite cannot reach**,
+ * which is why criterion 7 asks for a regression against a `bin` that does
+ * nothing: every case here drives `run` directly, so a package whose source is
+ * perfect and whose `bin` entry points at a file that does not exist passes all
+ * of them. `scripts/verify-clean-install.ts` installs the packed tarball and
+ * executes this path.
+ *
+ * `process.exitCode` rather than `process.exit`: the second truncates whatever
+ * is still buffered on stdout, and this command's last act is to print.
+ */
+const controller = new AbortController();
+process.on("SIGINT", () => {
+    controller.abort();
+});
+process.on("SIGTERM", () => {
+    controller.abort();
+});
+process.exitCode = await run(nodeRuntime(controller.signal));

package/dist/node-runtime.d.ts

@@ -0,0 +1,35 @@
+import { type CliRuntime, type LoopbackListener } from "./runtime.js";
+/**
+ * The one file that knows there is a process.
+ *
+ * Everything above this takes its surroundings as a parameter, so the shape of
+ * this file is the list of things a test has to be able to fake: a browser, a
+ * listener, a terminal, a clock, a signal.
+ */
+/**
+ * A listener for exactly one authorization redirect.
+ *
+ * **Only the redirect satisfies it.** A browser sent to a loopback address will
+ * happily make other requests to it first — a speculative preconnect, a
+ * `/favicon.ico` once the page renders — and a listener that resolved on the
+ * first request would resolve with one of those, carrying no `state`, killing
+ * the sign-in with a message about a state mismatch while the real redirect
+ * lands a moment later on a closed socket. Anything that is not the redirect is
+ * answered and the wait continues.
+ *
+ * Port zero: the operating system picks, and the port is known before the
+ * client is registered for it, which RFC 8252's exact-match rule requires.
+ */
+export declare function openLoopback(): Promise<LoopbackListener>;
+/**
+ * One line, not echoed.
+ *
+ * `readline` with the terminal's own echo turned off rather than a library:
+ * what has to be true is that the characters never reach the screen or the
+ * scrollback, and that is a property of the terminal rather than of the prompt.
+ */
+export declare function promptSecret(question: string, streams?: {
+    readonly input: NodeJS.ReadStream;
+    readonly output: NodeJS.WriteStream;
+}): Promise<string>;
+export declare function nodeRuntime(signal: AbortSignal): CliRuntime;