@greatwait/cli 0.1.0-alpha.3

package/dist/node-runtime.js

@@ -0,0 +1,210 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:http";
+import { homedir } from "node:os";
+import { createInterface } from "node:readline";
+import { InterruptedError, } 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 async function openLoopback() {
+    let deliver;
+    let fail;
+    const received = new Promise((resolve, reject) => {
+        deliver = resolve;
+        fail = reject;
+    });
+    // **Nobody is necessarily waiting on this when `close` runs.** A sign-in
+    // abandoned before the wait begins — dynamic registration refused, the
+    // authorization address unbuildable — reaches the `finally` that closes the
+    // listener while `received` has never been awaited, and an unhandled
+    // rejection ends the process in Node with a stack trace instead of the exit
+    // class the refusal earned. A handler attached here is never the *only* one:
+    // a caller that does await it still sees the rejection.
+    received.catch(() => undefined);
+    const server = createServer((request, response) => {
+        const url = new URL(request.url ?? "/", "http://127.0.0.1");
+        const isRedirect = url.pathname === "/callback" &&
+            (url.searchParams.has("code") || url.searchParams.has("error"));
+        if (!isRedirect) {
+            response.writeHead(204);
+            response.end();
+            return;
+        }
+        response.writeHead(200, { "content-type": "text/plain; charset=utf-8" });
+        response.end("Greatwait received the answer. You can close this tab.\n");
+        deliver?.(url.searchParams);
+    });
+    await new Promise((resolve, reject) => {
+        server.once("error", reject);
+        // `127.0.0.1` rather than every interface: this socket receives an
+        // authorization code, and nothing outside this machine has any business
+        // reaching it.
+        server.listen(0, "127.0.0.1", () => {
+            resolve();
+        });
+    });
+    const address = server.address();
+    if (address === null || typeof address === "string") {
+        server.close();
+        throw new Error("the loopback listener did not bind a port");
+    }
+    return {
+        close: () => {
+            fail?.(new Error("the sign-in was abandoned"));
+            server.close();
+        },
+        received,
+        redirectUri: `http://127.0.0.1:${String(address.port)}/callback`,
+    };
+}
+/** The platform's "open this" command, or a rejection where there is none. */
+async function openBrowser(url) {
+    const command = process.platform === "darwin"
+        ? { args: [url], name: "open" }
+        : process.platform === "win32"
+            ? { args: ["/c", "start", "", url], name: "cmd" }
+            : { args: [url], name: "xdg-open" };
+    await new Promise((resolve, reject) => {
+        const child = spawn(command.name, command.args, {
+            // The browser outlives this process and must not hold its streams.
+            detached: true,
+            stdio: "ignore",
+        });
+        child.once("error", reject);
+        child.once("spawn", () => {
+            child.unref();
+            resolve();
+        });
+    });
+}
+/**
+ * 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 async function promptSecret(question, streams = { input: process.stdin, output: process.stderr }) {
+    const input = streams.input;
+    const wasRaw = input.isRaw === true;
+    const readline = createInterface({ input, output: streams.output });
+    streams.output.write(question);
+    if (input.isTTY)
+        input.setRawMode(true);
+    try {
+        return await new Promise((resolve, reject) => {
+            let typed = "";
+            const onData = (chunk) => {
+                for (const byte of chunk) {
+                    if (byte === 0x0d || byte === 0x0a) {
+                        input.off("data", onData);
+                        streams.output.write("\n");
+                        resolve(typed);
+                        return;
+                    }
+                    if (byte === 0x7f || byte === 0x08) {
+                        typed = typed.slice(0, -1);
+                        continue;
+                    }
+                    if (byte === 0x03) {
+                        input.off("data", onData);
+                        streams.output.write("\n");
+                        // **Ctrl-C at the prompt is an interruption, not an empty
+                        // answer.** Resolving empty made it a `usage` refusal about a
+                        // credential nobody entered, which is the wrong sentence and the
+                        // wrong exit number: a shell reports `130` for a process the
+                        // person stopped, and every other wait in this command already
+                        // does.
+                        reject(new InterruptedError());
+                        return;
+                    }
+                    typed += String.fromCharCode(byte);
+                }
+            };
+            input.on("data", onData);
+        });
+    }
+    finally {
+        if (input.isTTY)
+            input.setRawMode(wasRaw);
+        readline.close();
+    }
+}
+async function readStdin() {
+    if (process.stdin.isTTY)
+        return "";
+    const chunks = [];
+    for await (const chunk of process.stdin) {
+        chunks.push(chunk);
+    }
+    return Buffer.concat(chunks).toString("utf8");
+}
+/**
+ * A sleep that ends when the signal fires.
+ *
+ * The reason Ctrl-C is a criterion of its own: the published poll interval is
+ * five seconds, so a wait that only noticed its signal between sleeps would
+ * hold the terminal for up to five seconds after somebody asked it to stop.
+ */
+function sleep(milliseconds, signal) {
+    return new Promise((resolve) => {
+        const timer = setTimeout(() => {
+            signal.removeEventListener("abort", onAbort);
+            resolve();
+        }, milliseconds);
+        function onAbort() {
+            clearTimeout(timer);
+            resolve();
+        }
+        signal.addEventListener("abort", onAbort, { once: true });
+    });
+}
+export function nodeRuntime(signal) {
+    return {
+        argv: process.argv.slice(2),
+        env: process.env,
+        fetch: ((url, init) => fetch(url, init)),
+        home: homedir(),
+        interactive: process.stdin.isTTY === true,
+        listen: openLoopback,
+        now: () => Date.now(),
+        openBrowser,
+        platform: process.platform,
+        promptSecret: (question) => promptSecret(question),
+        randomBytes: (length) => crypto.getRandomValues(new Uint8Array(length)),
+        randomUuid: () => crypto.randomUUID(),
+        readStdin,
+        signal,
+        sleep,
+        stderr: (text) => {
+            process.stderr.write(text);
+        },
+        stdout: (text) => {
+            process.stdout.write(text);
+        },
+        // **`undefined` on Windows**, where a file mode carries no access
+        // information at all: `stat` reports `0o666` for everything, so an
+        // owner-only check there would be asserting a constant.
+        uid: process.platform === "win32"
+            ? undefined
+            : (process.getuid?.() ?? undefined),
+    };
+}

package/dist/oauth.d.ts

@@ -0,0 +1,96 @@
+import { type CliRuntime } from "./runtime.js";
+/**
+ * The delegated-authorization half of `login`, spoken as a public client.
+ *
+ * **Everything here is discovered, not configured.** The origin is the only
+ * thing this command is told: it reads RFC 9728 protected-resource metadata to
+ * learn which authorization server protects that origin, then RFC 8414 metadata
+ * to learn where that server's endpoints are, and uses exactly the URLs it
+ * found. A client that constructed `/oauth/token` from the origin would work
+ * against this service and against nothing else, and would keep working after
+ * the service moved the endpoint — right up until it did not.
+ *
+ * **No client secret, ever.** A command installed on somebody's laptop cannot
+ * hold one: whatever it shipped with, every copy has. That is what makes S256
+ * PKCE mandatory rather than advisable here — the code is bound to a verifier
+ * this process generated and never sent, so a code intercepted on its way back
+ * is worth nothing.
+ *
+ * **The loopback listener binds before registration.** RFC 8252 has the
+ * authorization server match a redirect URI exactly, port included, so the port
+ * has to be known before the client is registered. Registering first and
+ * binding afterwards is how a client ends up registered for a port something
+ * else has taken.
+ */
+export interface AuthorizationServer {
+    readonly authorizationEndpoint: string;
+    readonly registrationEndpoint: string | undefined;
+    readonly resource: string;
+    readonly revocationEndpoint: string | undefined;
+    readonly scopesSupported: readonly string[];
+    readonly tokenEndpoint: string;
+}
+export interface OAuthTokens {
+    readonly accessToken: string;
+    readonly expiresInSeconds: number;
+    readonly refreshToken: string;
+    readonly scope: string;
+}
+/**
+ * Discovery, in the order a client that had never heard of this service does it.
+ *
+ * The protected-resource document is asked first because it is the one a `401`
+ * points at, and it is what says *which* authorization server to trust for this
+ * origin. Going straight to the authorization-server document would be assuming
+ * the answer.
+ */
+export declare function discover(runtime: CliRuntime, origin: string): Promise<AuthorizationServer>;
+export declare function registerClient(runtime: CliRuntime, server: AuthorizationServer, options: {
+    readonly redirectUri: string;
+    readonly scopes: readonly string[];
+}): Promise<string>;
+export interface AuthorizationRequest {
+    readonly authorizationUrl: string;
+    readonly state: string;
+    readonly verifier: string;
+}
+export declare function buildAuthorization(runtime: CliRuntime, server: AuthorizationServer, options: {
+    readonly clientId: string;
+    readonly redirectUri: string;
+    readonly scopes: readonly string[];
+}): Promise<AuthorizationRequest>;
+/**
+ * Turns the redirect into a code, refusing anything that is not this run's.
+ *
+ * `state` is compared before `code` is read. A redirect carrying somebody
+ * else's state is not a code to exchange — it is a request this process did not
+ * make — and reading the code first would exchange it anyway.
+ */
+export declare function codeFrom(returned: URLSearchParams, state: string): string;
+export declare function exchangeCode(runtime: CliRuntime, server: AuthorizationServer, options: {
+    readonly clientId: string;
+    readonly code: string;
+    readonly redirectUri: string;
+    readonly verifier: string;
+}): Promise<OAuthTokens>;
+export declare function refresh(runtime: CliRuntime, server: AuthorizationServer, options: {
+    readonly clientId: string;
+    readonly refreshToken: string;
+}): Promise<OAuthTokens>;
+/**
+ * Revokes the refresh token, and says whether the server took it.
+ *
+ * **The refresh token rather than the access token**, because RFC 7009 lets a
+ * server end the whole grant when it is given one, and ending the grant is what
+ * `logout` means. Revoking only the access token would leave a refresh token
+ * this command has just deleted and the service still honours.
+ *
+ * A failure here is reported, not thrown: local material is removed either way.
+ * A `logout` that refused to forget a credential because the network was down
+ * would leave the credential on the disk, which is the opposite of what was
+ * asked for.
+ */
+export declare function revoke(runtime: CliRuntime, server: AuthorizationServer, options: {
+    readonly clientId: string;
+    readonly token: string;
+}): Promise<boolean>;

package/dist/oauth.js

@@ -0,0 +1,205 @@
+import { CliError } from "./runtime.js";
+function base64Url(bytes) {
+    return Buffer.from(bytes).toString("base64url");
+}
+async function readJson(runtime, url, init) {
+    const response = await runtime.fetch(url, {
+        ...init,
+        signal: runtime.signal,
+    });
+    const text = await response.text();
+    let body;
+    try {
+        body = JSON.parse(text);
+    }
+    catch {
+        body = undefined;
+    }
+    return { body, status: response.status };
+}
+function requireString(value, field, source) {
+    if (typeof value !== "string" || value === "") {
+        throw new CliError(`${source} does not name a ${field}`, "internal", "This origin publishes authorization metadata this command cannot use. Sign in with an API key instead: greatwait login --api-key");
+    }
+    return value;
+}
+/**
+ * Discovery, in the order a client that had never heard of this service does it.
+ *
+ * The protected-resource document is asked first because it is the one a `401`
+ * points at, and it is what says *which* authorization server to trust for this
+ * origin. Going straight to the authorization-server document would be assuming
+ * the answer.
+ */
+export async function discover(runtime, origin) {
+    const resourceUrl = `${origin}/.well-known/oauth-protected-resource`;
+    const resource = await readJson(runtime, resourceUrl);
+    if (resource.status !== 200) {
+        throw new CliError(`${origin} does not publish protected-resource metadata (${String(resource.status)})`, "validation", "Check the origin. A Greatwait API answers GET /__greatwait/version with no credential; try greatwait doctor --api-url <origin>.");
+    }
+    const resourceBody = resource.body;
+    const servers = Array.isArray(resourceBody.authorization_servers)
+        ? resourceBody.authorization_servers
+        : [];
+    const issuer = requireString(servers[0], "authorization server", resourceUrl);
+    const metadataUrl = `${issuer}/.well-known/oauth-authorization-server`;
+    const metadata = await readJson(runtime, metadataUrl);
+    if (metadata.status !== 200) {
+        throw new CliError(`${issuer} does not publish authorization-server metadata (${String(metadata.status)})`, "validation");
+    }
+    const body = metadata.body;
+    const scopes = body["scopes_supported"];
+    return {
+        authorizationEndpoint: requireString(body["authorization_endpoint"], "authorization endpoint", metadataUrl),
+        registrationEndpoint: typeof body["registration_endpoint"] === "string"
+            ? body["registration_endpoint"]
+            : undefined,
+        // The audience this token is for, taken from the document rather than from
+        // the origin the command was given. RFC 8707's whole point is that a token
+        // minted for one audience must not be accepted by another, and a client
+        // that names an audience it invented is asserting something it did not
+        // check.
+        resource: requireString(resourceBody.resource, "resource", resourceUrl),
+        revocationEndpoint: typeof body["revocation_endpoint"] === "string"
+            ? body["revocation_endpoint"]
+            : undefined,
+        scopesSupported: Array.isArray(scopes)
+            ? scopes.filter((scope) => typeof scope === "string")
+            : [],
+        tokenEndpoint: requireString(body["token_endpoint"], "token endpoint", metadataUrl),
+    };
+}
+export async function registerClient(runtime, server, options) {
+    if (server.registrationEndpoint === undefined) {
+        throw new CliError("this authorization server does not offer dynamic client registration", "validation", "Sign in with an API key instead: greatwait login --api-key");
+    }
+    const registered = await readJson(runtime, server.registrationEndpoint, {
+        body: JSON.stringify({
+            client_name: "Greatwait CLI",
+            client_uri: "https://greatwait.dev",
+            grant_types: ["authorization_code", "refresh_token"],
+            redirect_uris: [options.redirectUri],
+            response_types: ["code"],
+            scope: options.scopes.join(" "),
+            // A public client: no secret to present, which is what the standard
+            // calls this and what PKCE compensates for.
+            token_endpoint_auth_method: "none",
+        }),
+        headers: { "content-type": "application/json" },
+        method: "POST",
+    });
+    if (registered.status !== 201 && registered.status !== 200) {
+        throw new CliError(`dynamic client registration was refused (${String(registered.status)}: ${registered.body?.error ??
+            "no reason given"})`, "validation");
+    }
+    return requireString(registered.body.client_id, "client_id", server.registrationEndpoint);
+}
+export async function buildAuthorization(runtime, server, options) {
+    const state = base64Url(runtime.randomBytes(24));
+    const verifier = base64Url(runtime.randomBytes(48));
+    const challenge = base64Url(new Uint8Array(await crypto.subtle.digest("SHA-256", new TextEncoder().encode(verifier))));
+    const url = new URL(server.authorizationEndpoint);
+    url.searchParams.set("client_id", options.clientId);
+    url.searchParams.set("code_challenge", challenge);
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("redirect_uri", options.redirectUri);
+    url.searchParams.set("resource", server.resource);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", options.scopes.join(" "));
+    url.searchParams.set("state", state);
+    return { authorizationUrl: url.toString(), state, verifier };
+}
+/**
+ * Turns the redirect into a code, refusing anything that is not this run's.
+ *
+ * `state` is compared before `code` is read. A redirect carrying somebody
+ * else's state is not a code to exchange — it is a request this process did not
+ * make — and reading the code first would exchange it anyway.
+ */
+export function codeFrom(returned, state) {
+    const error = returned.get("error");
+    if (error !== null) {
+        throw new CliError(`authorization was refused (${error})`, "authentication", error === "access_denied"
+            ? "Nothing was granted. Run greatwait login again and approve the request, or use an API key."
+            : undefined);
+    }
+    const returnedState = returned.get("state");
+    if (returnedState !== state) {
+        throw new CliError(`the redirect carried ${returnedState === null ? "no state" : "a state this run did not issue"}`, "authentication", "A browser tab left open from an earlier sign-in is the usual cause. Close it and run greatwait login again.");
+    }
+    const code = returned.get("code");
+    if (code === null) {
+        throw new CliError("the redirect carried no code", "authentication");
+    }
+    return code;
+}
+async function exchange(runtime, server, form) {
+    const response = await readJson(runtime, server.tokenEndpoint, {
+        body: new URLSearchParams(form).toString(),
+        headers: { "content-type": "application/x-www-form-urlencoded" },
+        method: "POST",
+    });
+    if (response.status !== 200) {
+        const error = response.body?.error;
+        throw new CliError(`the authorization server refused the token request (${error ?? String(response.status)})`, "authentication", error === "invalid_grant"
+            ? "The grant is no longer usable — it expired, was revoked, or was already spent. Run greatwait login again."
+            : undefined);
+    }
+    const body = response.body;
+    return {
+        accessToken: requireString(body["access_token"], "access_token", server.tokenEndpoint),
+        expiresInSeconds: typeof body["expires_in"] === "number" ? body["expires_in"] : 0,
+        refreshToken: requireString(body["refresh_token"], "refresh_token", server.tokenEndpoint),
+        scope: typeof body["scope"] === "string" ? body["scope"] : "",
+    };
+}
+export async function exchangeCode(runtime, server, options) {
+    return exchange(runtime, server, {
+        client_id: options.clientId,
+        code: options.code,
+        code_verifier: options.verifier,
+        grant_type: "authorization_code",
+        redirect_uri: options.redirectUri,
+        resource: server.resource,
+    });
+}
+export async function refresh(runtime, server, options) {
+    return exchange(runtime, server, {
+        client_id: options.clientId,
+        grant_type: "refresh_token",
+        refresh_token: options.refreshToken,
+        resource: server.resource,
+    });
+}
+/**
+ * Revokes the refresh token, and says whether the server took it.
+ *
+ * **The refresh token rather than the access token**, because RFC 7009 lets a
+ * server end the whole grant when it is given one, and ending the grant is what
+ * `logout` means. Revoking only the access token would leave a refresh token
+ * this command has just deleted and the service still honours.
+ *
+ * A failure here is reported, not thrown: local material is removed either way.
+ * A `logout` that refused to forget a credential because the network was down
+ * would leave the credential on the disk, which is the opposite of what was
+ * asked for.
+ */
+export async function revoke(runtime, server, options) {
+    if (server.revocationEndpoint === undefined)
+        return false;
+    try {
+        const response = await readJson(runtime, server.revocationEndpoint, {
+            body: new URLSearchParams({
+                client_id: options.clientId,
+                token: options.token,
+                token_type_hint: "refresh_token",
+            }).toString(),
+            headers: { "content-type": "application/x-www-form-urlencoded" },
+            method: "POST",
+        });
+        return response.status === 200;
+    }
+    catch {
+        return false;
+    }
+}

package/dist/output.d.ts

@@ -0,0 +1,66 @@
+import type { Problem } from "@greatwait/contracts";
+import { type ExitClass } from "./exit.js";
+/**
+ * What a machine reads, and what a person reads, kept apart on purpose.
+ *
+ * **`--json` is not a serialization of the human text.** The project's own CLI
+ * invariants say so, and the reason is that the two have different obligations:
+ * the human line may be rewritten whenever it reads badly, and the machine
+ * shape may not change without a version. Deriving one from the other means
+ * every wording change is a contract change nobody notices until a script
+ * breaks.
+ *
+ * So a command returns *data*, and this file renders it twice.
+ */
+/**
+ * The version of the machine shape, in every `--json` document.
+ *
+ * One number for the envelope rather than one per command: a consumer's first
+ * question is "can I parse this at all", and a per-command version makes that a
+ * table they have to hold. The payload under `data` is the operation's own
+ * published response shape wherever there is one, which is versioned already by
+ * the contract it comes from.
+ */
+export declare const OUTPUT_VERSION = 1;
+export interface CommandResult {
+    /** Rendered for a person, one line or a short block. Never parsed. */
+    readonly human: string;
+    /** The machine shape, under `data`. */
+    readonly data: unknown;
+    /**
+     * A non-zero class for a command that answered, and whose answer is bad news.
+     *
+     * **`doctor` is why this exists.** It has a real machine shape — a check per
+     * name with an outcome — and its refusal is that shape rather than a
+     * different one. Raising instead put the whole rendered table into the
+     * error's `message` string, so a script asking which check failed got a
+     * paragraph to parse. A command that *cannot* answer still raises; this is
+     * for one that answered "no".
+     */
+    readonly exit?: ExitClass;
+    /**
+     * What to do next, in a person's words. Printed after `human` and never in
+     * the JSON: a machine acts on `data` and on the exit class, and a sentence
+     * rewritten because it read badly must not be a change to a versioned
+     * contract.
+     */
+    readonly nextMove?: string;
+}
+export interface CommandFailure {
+    readonly exit: ExitClass;
+    readonly human: string;
+    readonly nextMove?: string;
+    /** The service's own problem document, where the service produced one. */
+    readonly problem?: Problem;
+}
+export declare function renderResult(command: string, result: CommandResult, json: boolean): string;
+export declare function renderFailure(command: string, failure: CommandFailure, json: boolean): string;
+/**
+ * A secret, as anything but the command that just minted it may print it.
+ *
+ * The prefix is kept because it is what a person matches against a listing, and
+ * it is the part the service itself publishes as `displayPrefix`. Everything
+ * after it becomes a fixed run of dots rather than a length-preserving mask: a
+ * mask that preserved length would publish how long the secret is.
+ */
+export declare function redactSecret(value: string): string;

package/dist/output.js

@@ -0,0 +1,76 @@
+import { EXIT_CLASSES } from "./exit.js";
+/**
+ * What a machine reads, and what a person reads, kept apart on purpose.
+ *
+ * **`--json` is not a serialization of the human text.** The project's own CLI
+ * invariants say so, and the reason is that the two have different obligations:
+ * the human line may be rewritten whenever it reads badly, and the machine
+ * shape may not change without a version. Deriving one from the other means
+ * every wording change is a contract change nobody notices until a script
+ * breaks.
+ *
+ * So a command returns *data*, and this file renders it twice.
+ */
+/**
+ * The version of the machine shape, in every `--json` document.
+ *
+ * One number for the envelope rather than one per command: a consumer's first
+ * question is "can I parse this at all", and a per-command version makes that a
+ * table they have to hold. The payload under `data` is the operation's own
+ * published response shape wherever there is one, which is versioned already by
+ * the contract it comes from.
+ */
+export const OUTPUT_VERSION = 1;
+export function renderResult(command, result, json) {
+    if (!json) {
+        return result.nextMove === undefined
+            ? `${result.human}\n`
+            : `${result.human}\n\n${result.nextMove}\n`;
+    }
+    return `${JSON.stringify({
+        command,
+        data: result.data,
+        ...(result.exit === undefined
+            ? {}
+            : { exit: result.exit, exitCode: EXIT_CLASSES[result.exit] }),
+        outputVersion: OUTPUT_VERSION,
+        ok: result.exit === undefined,
+    }, null, 2)}\n`;
+}
+export function renderFailure(command, failure, json) {
+    if (!json) {
+        const detail = failure.problem?.detail === undefined
+            ? ""
+            : `\n${failure.problem.detail}`;
+        return failure.nextMove === undefined
+            ? `${failure.human}${detail}\n`
+            : `${failure.human}${detail}\n\n${failure.nextMove}\n`;
+    }
+    return `${JSON.stringify({
+        command,
+        error: {
+            // **The public problem code survives.** A script that already branches
+            // on `idempotency_key_reused` against the REST surface must not have to
+            // learn a second vocabulary to branch on it here, and the exit class is
+            // deliberately coarser than the code rather than a rename of it.
+            ...(failure.problem === undefined ? {} : { problem: failure.problem }),
+            exit: failure.exit,
+            exitCode: EXIT_CLASSES[failure.exit],
+            message: failure.human,
+        },
+        ok: false,
+        outputVersion: OUTPUT_VERSION,
+    }, null, 2)}\n`;
+}
+/**
+ * A secret, as anything but the command that just minted it may print it.
+ *
+ * The prefix is kept because it is what a person matches against a listing, and
+ * it is the part the service itself publishes as `displayPrefix`. Everything
+ * after it becomes a fixed run of dots rather than a length-preserving mask: a
+ * mask that preserved length would publish how long the secret is.
+ */
+export function redactSecret(value) {
+    const visible = value.slice(0, 8);
+    return `${visible}${"•".repeat(12)}`;
+}