approval-md 0.0.1 → 0.2.0

package/dist/src/cli/prompt.js

@@ -0,0 +1,312 @@
+/**
+ * Terminal prompts — the one place this CLI reads from a human (APRV-74).
+ *
+ * Two of these three functions existed already, privately, inside
+ * `cli/amend.ts`: a synchronous line reader and the `[y/N]` question built on
+ * it. `approval setup` needs both, plus a third that `amend` never needed — a
+ * reader that does not echo — and three copies of a raw-mode byte loop is two
+ * too many. So they live here, `amend` imports the line reader, and the
+ * no-echo one is written once, in the open, where it can be read.
+ *
+ * ## Synchronous, on purpose
+ *
+ * `readSync(0, …)` rather than `readline/promises`. Every verb in this CLI
+ * returns an exit code from a synchronous function, and the two that do not
+ * (`channel`, `daemon`) are asynchronous because they hold a socket open, not
+ * because they ask a question. A prompt that forced `setup identity` to become
+ * a promise would be an async CLI shape adopted for the sake of one line of
+ * input.
+ *
+ * ## The no-echo reader, and what it is worth
+ *
+ * {@link readSecret} puts the terminal in raw mode and reads one byte at a
+ * time, printing nothing — not even asterisks, which leak a length. It restores
+ * the terminal in a `finally`, including on the abort paths, because a shell
+ * left in raw mode after a Ctrl-C is a broken session and the operator's next
+ * act would be to close the window.
+ *
+ * What it defends is a secret in a scrollback buffer, a `script` capture, or a
+ * screen share. What it does not defend is a compromised terminal, a keylogger,
+ * or the process itself: the value is a `string` in this process's heap the
+ * instant it is complete, exactly as `approval vault set`'s stdin value is. The
+ * design point that matters more is upstream of this file — wherever a secret
+ * can be collected by a helper's OWN prompt, `setup` delegates to that helper
+ * and this function is never called (see `cli/setup.ts`, "the token never
+ * enters our process").
+ *
+ * **Ctrl-C is a distinct result, not an exception and not an empty string.** An
+ * aborted prompt must be distinguishable from an empty answer by the caller, so
+ * that "the human changed their mind" stores nothing and exits, while "the
+ * human pressed Enter" is an ordinary validation failure. Collapsing the two is
+ * how a half-configured keystore entry gets written.
+ *
+ * Nothing here throws, and nothing here ever writes the value it read to any
+ * stream.
+ *
+ * ## A bad answer is a question asked again, not a mangled command line (APRV-90)
+ *
+ * {@link askUntil} is the loop every typed question in `setup` runs through. It
+ * exists because the first shipped build treated a wrong answer to a PROMPT the
+ * way it treats a wrong flag on an argv: exit 2 with the whole help page under
+ * it. Observed on 2026-08-18, `setup identity` printed `human identity
+ * (human:<id>):`, the operator typed `carter`, and forty lines of help came
+ * back. A prompt has already told the human what it wants; when the answer does
+ * not fit, the useful reply is one line saying which part did not fit, followed
+ * by the same question.
+ *
+ * Three ends, and they are different on purpose:
+ *
+ * - **accepted** — the validator's parsed value, which may be a NORMALISED form
+ *   of what was typed (`carter` → `human:carter`) rather than the bytes;
+ * - **aborted** — `readLine` returned `null`, which is Ctrl-D (and, for the
+ *   scripted prompter, the modelled Ctrl-C). Nothing is stored, and the caller
+ *   exits with a one-line reason and NO help page, because there was no command
+ *   line for a help page to be about;
+ * - **exhausted** — {@link DEFAULT_MAX_ATTEMPTS} answers in a row failed
+ *   validation. Bounded rather than infinite so that a prompt driven by
+ *   something that is not a person (a stuck script, a terminal replaying bytes)
+ *   terminates instead of looping forever.
+ *
+ * ## EAGAIN is "not yet", never "end of input" (APRV-84)
+ *
+ * Every caller checks `process.stdin.isTTY` before it prompts, and merely
+ * touching `process.stdin` on a terminal has libuv put fd 0 into non-blocking
+ * mode. From then on a `readSync(0, …)` issued before the human has typed
+ * fails with EAGAIN instead of waiting. The first shipped line reader treated
+ * every error as EOF, so `approval setup identity` on a macOS terminal printed
+ * "no identity was entered" the instant the prompt appeared. Both readers now
+ * go through {@link readByteBlocking}, which sleeps a few milliseconds on
+ * EAGAIN and tries again, and treats nothing else as "wait".
+ */
+import { readSync } from "node:fs";
+const CTRL_C = 0x03;
+const CTRL_D = 0x04;
+const BACKSPACE = 0x08;
+const DELETE = 0x7f;
+const CR = 0x0d;
+const LF = 0x0a;
+/**
+ * One line from stdin, synchronously. `null` at EOF.
+ *
+ * Hoisted verbatim from `cli/amend.ts` (APRV-74), which is why it reads bytes
+ * rather than using a stream: it is called from inside a synchronous command
+ * function, after output has already been written, and it must not consume more
+ * of stdin than the line it was asked for.
+ */
+export function readLineFromStdin(read = readByteBlocking) {
+    const buffer = Buffer.alloc(1);
+    const chars = [];
+    for (;;) {
+        let count = 0;
+        try {
+            count = read(buffer);
+        }
+        catch {
+            return chars.length === 0 ? null : chars.join("");
+        }
+        if (count === 0)
+            return chars.length === 0 ? null : chars.join("");
+        const char = buffer.toString("utf8");
+        if (char === "\n")
+            return chars.join("");
+        if (char !== "\r")
+            chars.push(char);
+    }
+}
+/** How long to sleep between EAGAIN retries. Short enough that a keystroke feels immediate. */
+const EAGAIN_NAP_MS = 5;
+const napCell = new Int32Array(new SharedArrayBuffer(4));
+/**
+ * One byte from fd 0, blocking, whatever mode libuv left the descriptor in.
+ *
+ * EAGAIN means the terminal has nothing yet: nap and retry (`Atomics.wait` is
+ * the one synchronous sleep JavaScript has, and it keeps the wait from being a
+ * hot loop). Every other error propagates, and 0 bytes is EOF, exactly as with
+ * `readSync` itself.
+ */
+export function readByteBlocking(buffer) {
+    for (;;) {
+        try {
+            return readSync(0, buffer, 0, 1, null);
+        }
+        catch (cause) {
+            if (cause.code !== "EAGAIN")
+                throw cause;
+            Atomics.wait(napCell, 0, 0, EAGAIN_NAP_MS);
+        }
+    }
+}
+/**
+ * A UTF-8 character's worth of bytes, popped off the end of `bytes`.
+ *
+ * Backspace deletes a CHARACTER, so the continuation bytes (`10xxxxxx`) of a
+ * multi-byte sequence come off together with their lead byte. A loop that
+ * popped one byte would leave a truncated sequence in the buffer and turn a
+ * passphrase containing an accented letter into one the operator cannot retype.
+ */
+function popCharacter(bytes) {
+    while (bytes.length > 0) {
+        const byte = bytes[bytes.length - 1];
+        bytes.pop();
+        if ((byte & 0xc0) !== 0x80)
+            return;
+    }
+}
+/**
+ * Read a secret with no echo. See the module doc for what this is worth.
+ *
+ * The byte loop, in full: `\r` or `\n` ends the read; DEL (0x7f) and BS (0x08)
+ * remove the last character and echo nothing (no cursor movement — there is
+ * nothing on screen to erase); Ctrl-C aborts always; Ctrl-D aborts only on an
+ * empty buffer, which is EOF's meaning everywhere else in a shell and which
+ * leaves the "Ctrl-D at the end of a typed line" case as an ordinary end. Every
+ * other byte accumulates.
+ *
+ * Raw mode is restored in a `finally`, and a newline is printed after, so the
+ * caller's next output starts on its own line whichever way the read ended.
+ */
+export function readSecret(streams, prompt, read = readByteBlocking) {
+    streams.out(prompt);
+    const stdin = process.stdin;
+    const wasRaw = stdin.isRaw === true;
+    const buffer = Buffer.alloc(1);
+    const bytes = [];
+    try {
+        stdin.setRawMode(true);
+        for (;;) {
+            let count = 0;
+            try {
+                count = read(buffer);
+            }
+            catch {
+                // EAGAIN never reaches here (readByteBlocking waits it out); anything else is the terminal going away.
+                return { ok: false, reason: "aborted" };
+            }
+            if (count === 0) {
+                return bytes.length === 0
+                    ? { ok: false, reason: "aborted" }
+                    : { ok: true, value: Buffer.from(bytes).toString("utf8") };
+            }
+            const byte = buffer[0];
+            if (byte === CR || byte === LF) {
+                return { ok: true, value: Buffer.from(bytes).toString("utf8") };
+            }
+            if (byte === CTRL_C)
+                return { ok: false, reason: "aborted" };
+            if (byte === CTRL_D && bytes.length === 0)
+                return { ok: false, reason: "aborted" };
+            if (byte === DELETE || byte === BACKSPACE) {
+                popCharacter(bytes);
+                continue;
+            }
+            if (byte === CTRL_D)
+                continue;
+            bytes.push(byte);
+        }
+    }
+    finally {
+        try {
+            stdin.setRawMode(wasRaw);
+        }
+        catch {
+            /* the terminal went away; there is nothing left to restore it to */
+        }
+        streams.out("\n");
+        bytes.length = 0;
+    }
+}
+/**
+ * The real prompter, or `null` when stdin is not a terminal.
+ *
+ * Refusing to construct is deliberate: a prompter that fell back to reading a
+ * pipe would let a CI job answer `setup`'s confirmations by feeding it a
+ * heredoc, and "a human was asked" is the entire content of these questions.
+ * Callers check `process.stdin.isTTY` themselves and print the non-interactive
+ * alternative; this is the second lock on the same door.
+ */
+export function createPrompter(streams) {
+    if (process.stdin.isTTY !== true)
+        return null;
+    return {
+        readLine(prompt) {
+            streams.out(prompt);
+            return readLineFromStdin();
+        },
+        readSecret(prompt) {
+            return readSecret(streams, prompt);
+        },
+        confirm(prompt, defaultNo = true) {
+            streams.out(`${prompt} ${defaultNo ? "[y/N]" : "[Y/n]"} `);
+            const answer = (readLineFromStdin() ?? "").trim().toLowerCase();
+            if (answer.length === 0)
+                return !defaultNo;
+            return answer === "y" || answer === "yes";
+        },
+    };
+}
+// ---------------------------------------------------------------------------
+// Asking again (APRV-90)
+// ---------------------------------------------------------------------------
+/**
+ * How many failed answers to one question before the loop gives up. See the
+ * module doc: bounded so that a prompt nobody is answering terminates.
+ */
+export const DEFAULT_MAX_ATTEMPTS = 5;
+/**
+ * Ask until the answer validates, the human gives up, or the attempts run out.
+ *
+ * The reason line goes to STDOUT, indented, because it is part of the
+ * conversation and not a diagnostic about a command: it is read by the person
+ * at the terminal, in between their answer and the next prompt. A caller turns
+ * an `aborted` or `exhausted` outcome into its own one-line refusal; nothing
+ * here prints a help page (see the module doc).
+ */
+export function askUntil(streams, prompter, question, validate, options = {}) {
+    const maxAttempts = options.maxAttempts ?? DEFAULT_MAX_ATTEMPTS;
+    for (let attempts = 1;; attempts += 1) {
+        const answer = prompter.readLine(question);
+        // Ctrl-D at the prompt, or the terminal going away. Distinct from an empty
+        // line, which is an ordinary answer a validator may accept or refuse.
+        if (answer === null)
+            return { ok: false, reason: "aborted", attempts };
+        const verdict = validate(answer);
+        if (verdict.ok)
+            return { ok: true, value: verdict.value };
+        // The reason is printed for the LAST attempt too: an operator who has just
+        // run out of tries is owed the same sentence as one who has not.
+        streams.out(`  ${verdict.reason}\n`);
+        if (attempts >= maxAttempts)
+            return { ok: false, reason: "exhausted", attempts };
+    }
+}
+/**
+ * A yes/no question that asks AGAIN when the answer is neither (APRV-99).
+ *
+ * {@link Prompter.confirm} takes the default for anything it does not
+ * recognise, which is the right reading for a question whose default is the
+ * safe answer: a stray keystroke declines. It is the wrong reading for a
+ * question whose default is YES and whose subject is a check the operator
+ * asked for, where a typo would silently skip the proof and report it as a
+ * decision. APRV-90's answer to that class of question is that every question
+ * loops, so this is {@link askUntil} over a yes/no validator: the same bounded
+ * loop, the same indented reason line, the same abort handling.
+ *
+ * Existing `confirm` calls are deliberately untouched — their output is pinned
+ * byte for byte — so this is an addition to the vocabulary, not a replacement.
+ * A withdrawal (Ctrl-D) or an exhausted loop reads as NO, which is the
+ * fail-closed direction for a question that offers to do something.
+ */
+export function confirmUntil(streams, prompter, question, defaultYes) {
+    const asked = askUntil(streams, prompter, `${question} ${defaultYes ? "[Y/n]" : "[y/N]"} `, (answer) => {
+        const typed = answer.trim().toLowerCase();
+        if (typed.length === 0)
+            return { ok: true, value: defaultYes };
+        if (typed === "y" || typed === "yes")
+            return { ok: true, value: true };
+        if (typed === "n" || typed === "no")
+            return { ok: true, value: false };
+        return { ok: false, reason: `${JSON.stringify(answer.trim())} is not yes or no` };
+    });
+    return asked.ok ? asked.value : false;
+}
+//# sourceMappingURL=prompt.js.map

package/dist/src/cli/prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt.js","sourceRoot":"","sources":["../../../src/cli/prompt.ts"],"names":[],"mappings":"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"}

package/dist/src/cli/quickstart.d.ts

@@ -0,0 +1,46 @@
+/**
+ * `approval quickstart` (APRV-309): one human ceremony for a small, operative
+ * policy. The command is terminal-only, displays the exact bytes it will
+ * attest, and leaves any interrupted setup unattested.
+ */
+import { spawn } from "node:child_process";
+import { type SourceRunner } from "../core/env-file.js";
+import type { Streams } from "./main.js";
+import { type Prompter } from "./prompt.js";
+import type { SetupDeps } from "./setup-common.js";
+export declare const QUICKSTART_CLASSES: readonly [{
+    readonly pattern: "communicate.*";
+    readonly label: "send a message or email";
+}, {
+    readonly pattern: "financial.*";
+    readonly label: "spend money";
+}, {
+    readonly pattern: "files.delete.*";
+    readonly label: "delete files";
+}, {
+    readonly pattern: "public.*";
+    readonly label: "post publicly";
+}, {
+    readonly pattern: "vcs.push.main";
+    readonly label: "push to main";
+}];
+type Channel = "cli" | "telegram";
+export interface QuickstartDeps {
+    prompter?: Prompter | null;
+    setup?: SetupDeps;
+    sourceRunner?: SourceRunner;
+    doctor?: (dir: string, actor: string, resolvedEnv: Readonly<Record<string, string>>, apiBase: string | null) => Promise<DoctorRun>;
+}
+interface DoctorRun {
+    code: number;
+    stdout: string;
+    stderr: string;
+}
+export declare function renderSoloPolicy(humanId: string, channel: Channel, patterns: readonly string[]): string;
+export declare function runQuickstartDoctor(dir: string, actor: string, resolvedEnv: Readonly<Record<string, string>>, apiBase: string | null, options?: {
+    timeoutMs?: number;
+    outputLimitBytes?: number;
+    spawnChild?: typeof spawn;
+}): Promise<DoctorRun>;
+export declare function commandQuickstart(argv: string[], streams: Streams, cwd: string, deps?: QuickstartDeps): Promise<number>;
+export {};

package/dist/src/cli/quickstart.js

@@ -0,0 +1,297 @@
+/**
+ * `approval quickstart` (APRV-309): one human ceremony for a small, operative
+ * policy. The command is terminal-only, displays the exact bytes it will
+ * attest, and leaves any interrupted setup unattested.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import { isAbsolute, join, resolve as resolvePathSegments } from "node:path";
+import { fileURLToPath } from "node:url";
+import { appendAttestation, HUMAN_ACTOR_ENV, policyBytesHash } from "../core/attest.js";
+import { SECRET_ENV_PREFIXES } from "../core/child-env.js";
+import { defaultSourceRunner, envFilePathFor, resolveEnvironment, upsertEnvFileEntries, } from "../core/env-file.js";
+import { loadPolicy, loadPolicyText } from "../core/policy-load.js";
+import { parseFlags, boolFlag, stringFlag } from "./args.js";
+import { EXIT_INTEGRITY, EXIT_IO, EXIT_OK, EXIT_TORN_TAIL, EXIT_USAGE } from "./exit-codes.js";
+import { QUICKSTART_HELP } from "./help.js";
+import { commandInit } from "./init.js";
+import { DEFAULT_LOG_PATH } from "./paths.js";
+import { askUntil, createPrompter } from "./prompt.js";
+import { commandSetupChannel } from "./setup-channel.js";
+import { identityFromAnswer } from "./setup.js";
+import { usageErrorText } from "./usage.js";
+const FLAGS = {
+    "--dir": "string",
+    "--api-base": "string",
+    "--json": "boolean",
+    "--help": "boolean",
+    "-h": "boolean",
+};
+export const QUICKSTART_CLASSES = [
+    { pattern: "communicate.*", label: "send a message or email" },
+    { pattern: "financial.*", label: "spend money" },
+    { pattern: "files.delete.*", label: "delete files" },
+    { pattern: "public.*", label: "post publicly" },
+    { pattern: "vcs.push.main", label: "push to main" },
+];
+const DOCTOR_TIMEOUT_MS = 20_000;
+const DOCTOR_OUTPUT_LIMIT_BYTES = 256 * 1024;
+function absolute(value, cwd) {
+    return isAbsolute(value) ? value : resolvePathSegments(cwd, value);
+}
+function refusal(streams, message) {
+    streams.err(usageErrorText(message, QUICKSTART_HELP));
+    return EXIT_USAGE;
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'"'"'`)}'`;
+}
+function nonInteractive(streams, json) {
+    const message = "quickstart needs a human at a terminal and has no JSON mode. Non-interactive equivalent: run `approval init`, write and review APPROVAL.md, run `approval setup identity`, optionally run `approval setup channel telegram`, then run `approval policy attest --as human:<id>`.";
+    if (json)
+        streams.err(`${JSON.stringify({ error: { code: "usage", message } })}\n`);
+    else
+        streams.err(usageErrorText(message, QUICKSTART_HELP));
+    return EXIT_USAGE;
+}
+function channelAnswer(answer) {
+    switch (answer.trim().toLowerCase()) {
+        case "1":
+        case "terminal":
+        case "cli":
+            return { ok: true, value: "cli" };
+        case "2":
+        case "telegram":
+            return { ok: true, value: "telegram" };
+        default:
+            return { ok: false, reason: "choose 1 for this terminal or 2 for Telegram" };
+    }
+}
+function classesAnswer(answer) {
+    const typed = answer.trim().toLowerCase();
+    if (typed.length === 0 || typed === "all") {
+        return { ok: true, value: QUICKSTART_CLASSES.map((entry) => entry.pattern) };
+    }
+    if (typed === "none")
+        return { ok: true, value: [] };
+    const indexes = typed.split(",").map((part) => Number(part.trim()));
+    if (indexes.some((index) => !Number.isInteger(index) || index < 1 || index > QUICKSTART_CLASSES.length)) {
+        return { ok: false, reason: "enter comma-separated numbers 1-5, all, none, or press Enter for all" };
+    }
+    return {
+        ok: true,
+        value: [...new Set(indexes)].map((index) => QUICKSTART_CLASSES[index - 1]?.pattern),
+    };
+}
+function quickstartIdentity(answer) {
+    const parsed = identityFromAnswer(answer);
+    if (!parsed.ok)
+        return parsed;
+    const humanId = parsed.value.slice("human:".length);
+    return /^[a-z0-9][a-z0-9_-]*$/u.test(humanId)
+        ? parsed
+        : { ok: false, reason: "the id must start with a lowercase letter or digit and contain only lowercase letters, digits, _ or -" };
+}
+export function renderSoloPolicy(humanId, channel, patterns) {
+    const rules = patterns
+        .map((pattern) => `  ${pattern}:\n    autonomy: manual\n    approvers: [${humanId}]`)
+        .join("\n");
+    const channelBlock = channel === "telegram"
+        ? "\nchannels:\n  telegram:\n    chat_id_env: APPROVAL_TG_CHAT\n    token_env: APPROVAL_TG_TOKEN\n"
+        : "";
+    return `# Approval Policy\n\nThis is a solo policy. The selected class families ask the person below.\nOther classified reversible actions use the autonomous default. Runtime safety\nfloors and unclassified-command refusals still apply.\n\n\`\`\`yaml approval-policy\nversion: "0.1"\n\ndefaults:\n  autonomy: autonomous       # Tighten to manual to make every unnamed class ask.\n  channel: ${channel}\n  approval_ttl: 24h\n  on_expiry: reject\n\napprovers:\n  ${humanId}:\n    channels: [${channel}]\n\nclasses:\n${rules.length === 0 ? "  {}" : rules}\n${channelBlock}\`\`\`\n\nNo audit block means retrospective sampling is off. Add one only through a\nhuman-reviewed policy amendment; see \`approval policy amend --help\`.\n`;
+}
+function appendBounded(current, chunk, limit) {
+    const remaining = limit - Buffer.byteLength(current);
+    if (remaining <= 0)
+        return { text: current, overflow: true };
+    const bytes = Buffer.from(chunk);
+    if (bytes.byteLength <= remaining)
+        return { text: current + chunk, overflow: false };
+    return { text: current + bytes.subarray(0, remaining).toString("utf8"), overflow: true };
+}
+export function runQuickstartDoctor(dir, actor, resolvedEnv, apiBase, options = {}) {
+    return new Promise((resolve) => {
+        const env = { ...process.env };
+        // The check must not borrow identity or credentials from another instance.
+        // Only values explicitly resolved from this quickstart's source map return.
+        for (const name of Object.keys(env)) {
+            if (SECRET_ENV_PREFIXES.some((prefix) => name.startsWith(prefix)))
+                delete env[name];
+        }
+        Object.assign(env, resolvedEnv, { [HUMAN_ACTOR_ENV]: actor });
+        const cliEntry = fileURLToPath(new URL("./main.js", import.meta.url));
+        const childArgs = [cliEntry, "doctor", "--json", "--dir", dir];
+        if (apiBase !== null)
+            childArgs.push("--api-base", apiBase);
+        const child = (options.spawnChild ?? spawn)(process.execPath, childArgs, {
+            cwd: dir,
+            env,
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const outputLimit = options.outputLimitBytes ?? DOCTOR_OUTPUT_LIMIT_BYTES;
+        const finish = (result) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            resolve(result);
+        };
+        const abortForOutput = () => {
+            child.kill("SIGTERM");
+            finish({ code: EXIT_IO, stdout, stderr: `${stderr}approval doctor output exceeded ${String(outputLimit)} bytes and was stopped\n` });
+        };
+        child.stdout.setEncoding("utf8");
+        child.stderr.setEncoding("utf8");
+        child.stdout.on("data", (text) => {
+            const next = appendBounded(stdout, text, outputLimit);
+            stdout = next.text;
+            if (next.overflow)
+                abortForOutput();
+        });
+        child.stderr.on("data", (text) => {
+            const next = appendBounded(stderr, text, outputLimit);
+            stderr = next.text;
+            if (next.overflow)
+                abortForOutput();
+        });
+        child.once("error", (cause) => finish({ code: EXIT_IO, stdout, stderr: `${stderr}${cause.message}\n` }));
+        child.once("close", (code) => finish({ code: code ?? EXIT_IO, stdout, stderr }));
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            finish({ code: EXIT_IO, stdout, stderr: `${stderr}approval doctor exceeded ${String(options.timeoutMs ?? DOCTOR_TIMEOUT_MS)}ms and was stopped\n` });
+        }, options.timeoutMs ?? DOCTOR_TIMEOUT_MS);
+        timer.unref();
+    });
+}
+function doctorPreflight(run) {
+    if (run.code === EXIT_OK)
+        return { ok: true };
+    if (run.code === EXIT_INTEGRITY) {
+        try {
+            const report = JSON.parse(run.stdout);
+            const failed = report.checks?.filter((check) => check.status === "fail") ?? [];
+            if (failed.length === 1 &&
+                failed[0]?.check === "attestation" &&
+                typeof failed[0].detail === "string" &&
+                failed[0].detail.includes("has never been attested"))
+                return { ok: true };
+        }
+        catch {
+            // The diagnostic's malformed output is reported below with its exit.
+        }
+    }
+    return {
+        ok: false,
+        code: run.code,
+        message: `approval doctor preflight reported a setup problem; the policy remains unattested:\n${run.stderr}${run.stdout}`,
+    };
+}
+export async function commandQuickstart(argv, streams, cwd, deps = {}) {
+    const json = argv.includes("--json");
+    const parsed = parseFlags(argv, FLAGS);
+    if (!parsed.ok)
+        return refusal(streams, parsed.message);
+    if (boolFlag(parsed.flags, "--help") || boolFlag(parsed.flags, "-h")) {
+        streams.out(`${QUICKSTART_HELP}\n`);
+        return EXIT_OK;
+    }
+    if (parsed.positionals.length > 0)
+        return refusal(streams, `unexpected argument ${JSON.stringify(parsed.positionals[0])}`);
+    const prompter = deps.prompter === undefined ? createPrompter(streams) : deps.prompter;
+    if (json || prompter === null)
+        return nonInteractive(streams, json);
+    const dirFlag = stringFlag(parsed.flags, "--dir");
+    const dir = dirFlag === null ? cwd : absolute(dirFlag, cwd);
+    const apiBase = stringFlag(parsed.flags, "--api-base");
+    if (existsSync(join(dir, "APPROVAL.md")) ||
+        existsSync(join(dir, "APPROVALS.md")) ||
+        existsSync(join(dir, ".approval"))) {
+        streams.err(`approval: setup artifacts already exist in ${dir}; quickstart only initializes a fresh instance and changed nothing\n`);
+        return EXIT_IO;
+    }
+    streams.out("approval quickstart — three decisions to make a solo gate operative.\n\n");
+    const identity = askUntil(streams, prompter, "1/3 your name (for human:<id>): ", quickstartIdentity);
+    if (!identity.ok)
+        return refusal(streams, "no valid human identity was entered; nothing was written");
+    const actor = identity.value;
+    const humanId = actor.slice("human:".length);
+    const channel = askUntil(streams, prompter, "2/3 button location (1 terminal, 2 Telegram): ", channelAnswer);
+    if (!channel.ok)
+        return refusal(streams, "no channel was chosen; nothing was written");
+    streams.out(`${QUICKSTART_CLASSES.map((entry, index) => `  ${String(index + 1)}. ${entry.label}`).join("\n")}\n`);
+    const selected = askUntil(streams, prompter, "3/3 always ask (numbers, Enter for all): ", classesAnswer);
+    if (!selected.ok)
+        return refusal(streams, "no valid checklist was entered; nothing was written");
+    const policy = renderSoloPolicy(humanId, channel.value, selected.value);
+    const loaded = loadPolicyText(join(dir, "APPROVAL.md"), policy);
+    if (!loaded.ok) {
+        streams.err(`approval: generated policy failed validation: ${loaded.message}\n`);
+        return EXIT_IO;
+    }
+    let initOut = "";
+    let initErr = "";
+    const initCode = commandInit([], { out: (text) => { initOut += text; }, err: (text) => { initErr += text; } }, dir, { policyText: policy });
+    if (initCode !== EXIT_OK) {
+        streams.err(`${initErr}${initOut}`);
+        return initCode;
+    }
+    const envPath = envFilePathFor(join(dir, DEFAULT_LOG_PATH));
+    const envWrite = upsertEnvFileEntries(envPath, [{ key: HUMAN_ACTOR_ENV, value: actor }]);
+    if (!envWrite.ok) {
+        streams.err(`approval: ${envWrite.message}\n`);
+        return EXIT_IO;
+    }
+    if (channel.value === "telegram") {
+        const setupArgs = ["telegram", "--as", actor, "--dir", dir];
+        if (apiBase !== null)
+            setupArgs.push("--api-base", apiBase);
+        const setupCode = await commandSetupChannel(setupArgs, streams, dir, { ...deps.setup, prompter });
+        if (setupCode !== EXIT_OK)
+            return setupCode;
+    }
+    const onDisk = loadPolicy({ dir });
+    if (!onDisk.ok) {
+        streams.err(`approval: generated policy could not be reloaded for preflight: ${onDisk.message}\n`);
+        return EXIT_IO;
+    }
+    const resolution = resolveEnvironment(onDisk, envPath, deps.sourceRunner ?? defaultSourceRunner, {});
+    if (!resolution.ok) {
+        streams.err(`approval: quickstart environment could not be resolved: ${resolution.message}\n`);
+        return EXIT_IO;
+    }
+    const resolvedEnv = {};
+    for (const variable of resolution.variables) {
+        if (variable.value !== undefined)
+            resolvedEnv[variable.name] = variable.value;
+        else if (variable.declared) {
+            streams.err(`approval: ${variable.name} could not be resolved from this instance (${variable.source}); the policy remains unattested\n`);
+            return EXIT_IO;
+        }
+    }
+    const doctor = await (deps.doctor ?? runQuickstartDoctor)(dir, actor, resolvedEnv, apiBase);
+    const preflight = doctorPreflight(doctor);
+    if (!preflight.ok) {
+        streams.err(preflight.message);
+        return preflight.code;
+    }
+    streams.out(`\nReview the exact policy that will become operative:\n\n${policy}\n`);
+    const understood = askUntil(streams, prompter, "type understood to attest these exact bytes: ", (answer) => answer.trim() === "understood"
+        ? { ok: true, value: true }
+        : { ok: false, reason: "type understood exactly, or Ctrl-D to leave the policy unattested" });
+    if (!understood.ok)
+        return refusal(streams, "policy left unattested");
+    const attestation = appendAttestation(join(dir, DEFAULT_LOG_PATH), join(dir, "APPROVAL.md"), actor, { expectedSha256: policyBytesHash(Buffer.from(policy, "utf8")) });
+    if (!attestation.ok) {
+        streams.err(`approval: ${attestation.error.message}\n`);
+        return attestation.error.code === "corrupt-tail" ? EXIT_TORN_TAIL : EXIT_IO;
+    }
+    streams.out(`ready: ${String(selected.value.length)} selected class families ask ${actor} on ${channel.value}; other classified reversible actions use the autonomous default\n`);
+    streams.out(`activate: eval "$(approval env --dir ${shellQuote(dir)})"\n`);
+    streams.out("try: approval hook classify -- curl -X POST https://api.example.com/apply\n");
+    return EXIT_OK;
+}
+//# sourceMappingURL=quickstart.js.map