@storystick/cli 0.0.0-stage → 0.2.0-rc.0

package/dist/output.js

@@ -0,0 +1,771 @@
+/**
+ * Storystick CLI — output primitives (ADR-061).
+ *
+ * Every user-visible byte the CLI emits flows through this module. The
+ * boundary is enforced mechanically by `scripts/lint-output.mjs`, which
+ * forbids raw `console.*`, `process.(stdout|stderr).write`, and direct
+ * imports of `ora` / `@inquirer/prompts` anywhere outside this file.
+ *
+ * The five locked style rules (ADR-061 §Decision):
+ *   1. One active line at a time — spinner text mutates in place.
+ *   2. Two icons (✔ green, ✖ red), four colors (green / red / cyan-spinner
+ *      / rare yellow+gray).
+ *   3. Zero chrome — no boxes, no gutters, no banners.
+ *   4. URLs emitted bare (terminal auto-linkifies).
+ *   5. stderr for status, stdout for data payloads.
+ *
+ * Mode state is module-global: a CLI is a single short-lived process, not
+ * a library. `resetOutput()` is the only test-isolation mechanism.
+ *
+ * `ora` and `@inquirer/prompts` are lazy-imported inside the primitives
+ * that need them — fast commands (`generate`, `push`, `sync`) never pay
+ * the startup cost.
+ */
+import pc from 'picocolors';
+import { relative } from 'node:path';
+import { StorystickError } from './cli-error.js';
+// ─── Module state (per-process, reset via resetOutput()) ─────
+let currentMode = 'human';
+let verboseMode = false;
+let quietMode = false;
+let capture = null;
+let activeSpinner = null;
+const listeners = [];
+let sigintInstalled = false;
+/**
+ * Configure the per-invocation output mode (ADR-072 §D12).
+ *
+ * Mutual exclusivity:
+ *   - `verbose + quiet` → fatal (exit 1 with hint) — they're directly
+ *     contradictory.
+ *   - `verbose + json`  → JSON wins. `verbose` still affects what makes
+ *     it INTO the envelope (info diagnostics rendered) but the human
+ *     rendering layer is muted under JSON regardless.
+ *   - `quiet + json`    → both apply. stdout still emits the envelope
+ *     (data is data); stderr is silent except for failures.
+ */
+export function configureOutput(opts = {}) {
+    if (opts.verbose === true && opts.quiet === true) {
+        // configureOutput is called BEFORE the canonical-shell try/catch in
+        // every action, so this surfaces as a clean fatal — not a stack trace.
+        currentMode = opts.json === true ? 'json' : 'human';
+        verboseMode = false;
+        quietMode = false;
+        ensureSigintHandler();
+        exitWithError('--verbose and --quiet are mutually exclusive.', 'Pass exactly one (or neither).');
+    }
+    currentMode = opts.json === true ? 'json' : 'human';
+    verboseMode = opts.verbose === true;
+    quietMode = opts.quiet === true;
+    ensureSigintHandler();
+}
+export function getOutputMode() {
+    return currentMode;
+}
+/**
+ * `--verbose` is set. Action handlers consult this to decide whether to
+ * render info-level diagnostics + list warning details post-success,
+ * instead of just counting them.
+ */
+export function isVerbose() {
+    return verboseMode;
+}
+/**
+ * `--quiet` is set. Status / warning lines are muted under quiet — but
+ * failures (`logFailure`) and data (`logOutput`) always pass through
+ * per ADR-061 rule 5.
+ */
+export function isQuiet() {
+    return quietMode;
+}
+/**
+ * Fully reset module state. Call from `beforeEach` in tests — the in-process
+ * test suite shares this module across cases.
+ */
+export function resetOutput() {
+    if (activeSpinner) {
+        try {
+            activeSpinner.stop();
+        }
+        catch {
+            /* stopping a dead spinner shouldn't crash the test run */
+        }
+        activeSpinner = null;
+    }
+    currentMode = 'human';
+    verboseMode = false;
+    quietMode = false;
+    capture = null;
+    listeners.length = 0;
+}
+/**
+ * Start capturing output. Writes go to in-memory buffers instead of the
+ * real streams; events are appended to `events`. Inversion of control,
+ * no `process.std*` spying.
+ */
+export function __testing_enableCapture() {
+    capture = { stdout: [], stderr: [], events: [] };
+    return capture;
+}
+export function onEvent(fn) {
+    listeners.push(fn);
+    return () => {
+        const idx = listeners.indexOf(fn);
+        if (idx >= 0)
+            listeners.splice(idx, 1);
+    };
+}
+function emit(event) {
+    if (capture)
+        capture.events.push(event);
+    for (const l of listeners) {
+        try {
+            l(event);
+        }
+        catch {
+            /* listener errors must not poison primitives */
+        }
+    }
+}
+function writeStderr(text) {
+    if (capture) {
+        capture.stderr.push(text);
+        return;
+    }
+    process.stderr.write(text);
+}
+function writeStdout(text) {
+    if (capture) {
+        capture.stdout.push(text);
+        return;
+    }
+    process.stdout.write(text);
+}
+// ─── Logging primitives ───────────────────────────────────────
+/** Dimmed status line — muted under --json or --quiet. */
+export function logMessage(text) {
+    emit({ type: 'message', text });
+    if (currentMode === 'json' || quietMode)
+        return;
+    writeStderr(text + '\n');
+}
+export function logFinishedStep(text) {
+    emit({ type: 'finished-step', text });
+    if (currentMode === 'json' || quietMode)
+        return;
+    writeStderr(`${pc.green('✔')} ${text}\n`);
+}
+export function logFailure(text) {
+    emit({ type: 'failure', text });
+    // logFailure is the ONE status primitive that is never muted — real
+    // errors must surface even under --json (stderr line still useful in
+    // mixed-pipe contexts) and even under --quiet (per ADR-061 rule 5).
+    writeStderr(`${pc.red('✖')} ${text}\n`);
+}
+export function logWarning(text) {
+    emit({ type: 'warning', text });
+    if (currentMode === 'json' || quietMode)
+        return;
+    writeStderr(`${pc.yellow(text)}\n`);
+}
+/**
+ * THE ONLY function writing to stdout. Payload must already carry its own
+ * trailing newline when the caller wants one (matches the Pattern D JSON
+ * convention at `list.ts` / `info.ts` today).
+ */
+export function logOutput(payload) {
+    emit({ type: 'data' });
+    writeStdout(payload);
+}
+/**
+ * Identity helper retained for source stability — `Diagnostic` IS
+ * `JsonDiagnostic` post-batch-6, so the conversion is a no-op. Kept
+ * exported (vs deleted) so existing call sites don't churn ; can be
+ * inlined in a future cleanup batch.
+ */
+export function diagnosticToJson(d) {
+    return d;
+}
+export function emitJsonResult(args) {
+    const envelope = args.ok
+        ? {
+            ok: true,
+            command: args.command,
+            version: '1',
+            data: args.data,
+            diagnostics: args.diagnostics ?? [],
+        }
+        : {
+            ok: false,
+            command: args.command,
+            version: '1',
+            // Caller must pass a JsonError when ok=false; the type guard
+            // above enforces it at call sites.
+            error: args.error,
+            diagnostics: args.diagnostics ?? [],
+        };
+    emit({ type: 'data' });
+    writeStdout(JSON.stringify(envelope) + '\n');
+}
+/**
+ * Emit a single line of the JSONL stream. Used by `backfill-refs --json`
+ * (ADR-072 §A3 / L5) — multiple `progress` events followed by exactly
+ * one `final` event.
+ */
+export function emitJsonlEvent(args) {
+    const line = {
+        command: args.command,
+        version: '1',
+        event: args.event,
+        data: args.data,
+    };
+    if (args.event === 'final') {
+        line.ok = args.ok ?? true;
+    }
+    emit({ type: 'data-jsonl', event: args.event });
+    writeStdout(JSON.stringify(line) + '\n');
+}
+/** Emit the terminal canonical failure event for a JSONL command. */
+export function emitJsonlFailure(args) {
+    emit({ type: 'data-jsonl', event: 'final' });
+    writeStdout(JSON.stringify({
+        command: args.command,
+        version: '1',
+        event: 'final',
+        ok: false,
+        error: jsonErrorFromUnknown(args.err, args.hint),
+    }) + '\n');
+}
+// ─── Diagnostic formatting (shared by generate / push / sync) ─
+export function formatDiagnostic(d, rootDir) {
+    const icon = d.severity === 'error'
+        ? pc.red('✖')
+        : d.severity === 'warning'
+            ? pc.yellow('!')
+            : pc.dim('·');
+    const file = relative(rootDir, d.file);
+    // ADR-080 + ADR-079 D3 : `range` is LSP-style 0-indexed `{start, end}` ;
+    // editors/compilers conventionally show 1-indexed line:col, so +1 here.
+    const loc = d.range
+        ? `:${d.range.start.line + 1}:${d.range.start.character + 1}`
+        : '';
+    const code = pc.dim(`[${d.code}]`);
+    let msg = `${icon} ${file}${loc} ${code} ${d.message}`;
+    if (d.related) {
+        for (const r of d.related) {
+            const rFile = relative(rootDir, r.file);
+            msg += `\n  ${pc.dim('—')} ${rFile} ${r.message}`;
+        }
+    }
+    return msg;
+}
+// ─── Spinner primitives ───────────────────────────────────────
+let oraModulePromise = null;
+async function loadOra() {
+    if (!oraModulePromise) {
+        oraModulePromise = import('ora').then((m) => m.default);
+    }
+    return await oraModulePromise;
+}
+/**
+ * Start a spinner. Under `--json` or capture, no TTY updates happen — the
+ * event is still emitted so tests can assert the orchestration shape.
+ */
+export async function showSpinner(text) {
+    ensureSigintHandler();
+    emit({ type: 'spinner-start', text });
+    if (currentMode === 'json' || capture) {
+        activeSpinner = makeNoopSpinner(text);
+        return;
+    }
+    const ora = await loadOra();
+    const instance = ora({ text, color: 'cyan', stream: process.stderr }).start();
+    activeSpinner = {
+        get text() {
+            return instance.text;
+        },
+        set text(v) {
+            instance.text = v;
+        },
+        succeed: (t) => {
+            // Force the ✔ prefix to match our palette rules even if ora's default
+            // ever drifts. Stream discipline (stderr) comes from the stream option.
+            instance.stopAndPersist({
+                symbol: pc.green('✔'),
+                text: t ?? instance.text,
+            });
+        },
+        fail: (t) => {
+            instance.stopAndPersist({
+                symbol: pc.red('✖'),
+                text: t ?? instance.text,
+            });
+        },
+        stop: () => instance.stop(),
+    };
+}
+/** Mutate the active spinner's text in place. No-op if no spinner is live. */
+export function changeSpinner(text) {
+    emit({ type: 'spinner-change', text });
+    if (!activeSpinner)
+        return;
+    activeSpinner.text = text;
+}
+/** Land the spinner with `✔ <text>` (or the current spinner text). */
+export function succeedSpinner(text) {
+    if (activeSpinner) {
+        emit({ type: 'spinner-success', text: text ?? activeSpinner.text });
+        activeSpinner.succeed(text);
+        activeSpinner = null;
+    }
+    else {
+        // No spinner live — fall back to a plain finished-step line so callers
+        // can use `succeedSpinner` uniformly.
+        logFinishedStep(text ?? '');
+    }
+}
+/** Land the spinner with `✖ <text>`. */
+export function failSpinner(text) {
+    if (activeSpinner) {
+        emit({ type: 'spinner-failure', text: text ?? activeSpinner.text });
+        activeSpinner.fail(text);
+        activeSpinner = null;
+    }
+    else {
+        logFailure(text ?? '');
+    }
+}
+/** Stop the spinner without landing a symbol. UI cleanup — no event. */
+export function stopSpinner() {
+    if (!activeSpinner)
+        return;
+    emit({ type: 'spinner-stop' });
+    activeSpinner.stop();
+    activeSpinner = null;
+}
+/**
+ * Show a spinner ONLY if `fn` takes longer than `delayMs`. Used for init's
+ * six orchestration phases — fast ops (<delayMs) finish silently; slow ops
+ * land a `✔`; throws land a `✖` and rethrow.
+ *
+ * NOT for device-auth: that path goes through `promptDeviceAuth` directly.
+ *
+ * For multi-phase work that needs an external success line (push/sync),
+ * use `withSlowSpinner` instead — it suppresses the auto-✔ so the caller
+ * can print its own `logFinishedStep` line after.
+ */
+export async function showSpinnerIfSlow(text, delayMs, fn) {
+    let shown = false;
+    const timer = setTimeout(() => {
+        shown = true;
+        void showSpinner(text);
+    }, delayMs);
+    try {
+        const result = await fn();
+        clearTimeout(timer);
+        if (shown)
+            succeedSpinner(text);
+        return result;
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if (shown)
+            failSpinner(text);
+        throw err;
+    }
+}
+/**
+ * Thin slow-gate around the bare spinner primitives, for ADR-072 §D11
+ * (push/sync/generate spinners). Like `showSpinnerIfSlow` but:
+ *
+ *   - Does NOT auto-succeed at the end — caller is expected to print its
+ *     own success line via `logFinishedStep` after the work returns. This
+ *     avoids the double-✔ that `showSpinnerIfSlow` produces when callers
+ *     also want a structured success line.
+ *   - Stops the spinner cleanly on success (no ✔ symbol) and on throw
+ *     (no ✖ symbol either — failures are surfaced by the caller's
+ *     diagnostic rendering + `logFailure` / `exitWithError`).
+ *   - Inside `fn`, callers may call `changeSpinner('…')` to mutate the
+ *     visible text across phases. The "single spinner that mutates"
+ *     pattern in ADR-072 §D11.
+ *
+ * On fast paths (<delayMs), no spinner is ever shown — UX is silent
+ * during the work; the caller's success line is the only visible output.
+ */
+export async function withSlowSpinner(text, delayMs, fn) {
+    let shown = false;
+    const timer = setTimeout(() => {
+        shown = true;
+        void showSpinner(text);
+    }, delayMs);
+    try {
+        const result = await fn();
+        clearTimeout(timer);
+        if (shown)
+            stopSpinner();
+        return result;
+    }
+    catch (err) {
+        clearTimeout(timer);
+        if (shown)
+            stopSpinner();
+        throw err;
+    }
+}
+// ─── Device-auth prompt (replaces the six pre-refactor copies) ─
+/**
+ * Render the "visit URL + type code" block and resume with a spinner. If
+ * a spinner is active when the prompt fires (typical during `link`'s
+ * resolve-project phase), it is stopped before the block lands so the
+ * prompt doesn't race with the spinner frame.
+ *
+ * URL is emitted bare per rule 4 — no underline, no brackets, no color.
+ */
+export function promptDeviceAuth(data) {
+    // Stop any live spinner FIRST so the prompt text doesn't race with
+    // spinner frames — the clack-gutter bug this refactor explicitly fixes.
+    if (activeSpinner)
+        stopSpinner();
+    emit({ type: 'prompt-device-auth' });
+    const minutes = Math.max(1, Math.round(data.expiresIn / 60));
+    writeStderr('\n');
+    if (data.issuer)
+        writeStderr(`  Gateway: ${data.issuer}\n`);
+    writeStderr(`  Visit ${data.verificationUrl}\n`);
+    writeStderr(`  Your code: ${pc.bold(data.userCode)} ${pc.dim(`(expires in ${minutes} minutes)`)}\n`);
+    writeStderr('\n');
+    // Fire-and-forget browser launch — nice-to-have, silent on failure.
+    void maybeOpenBrowser(data.verificationUrl);
+    // Resume with "Waiting…" spinner — every call site shares this step.
+    void showSpinner(data.waitingText ?? 'Waiting for authorization…');
+}
+/**
+ * Attempt to launch the user's default browser at `url`. Scoped to cases
+ * where it actually helps: skip under test capture, JSON mode, non-TTY
+ * stdout (CI / SSH), or the explicit `STORYSTICK_NO_BROWSER=1` opt-out.
+ *
+ * Failures are swallowed — the printed URL stays as the source of truth,
+ * so missing `$DISPLAY` / sandboxed environments degrade cleanly.
+ */
+async function maybeOpenBrowser(url) {
+    if (capture)
+        return;
+    if (currentMode === 'json')
+        return;
+    if (process.env.STORYSTICK_NO_BROWSER)
+        return;
+    if (!process.stdout.isTTY)
+        return;
+    try {
+        const open = (await import('open')).default;
+        await open(url);
+    }
+    catch {
+        /* silent — the printed URL is the fallback */
+    }
+}
+/**
+ * Type guard for the "user cancelled a prompt" case. `@inquirer/prompts`
+ * throws a specific error class on Ctrl-C; every prompt call site catches
+ * this and treats it as an exit-0 cancel (per-command semantic, ADR-061
+ * §SIGINT scope).
+ *
+ * Lives here so the boundary-lint can keep @inquirer/core out of command
+ * files — matching by `name` is sufficient since the error surfaces from
+ * our own wrappers.
+ */
+export function isExitPromptCancel(err) {
+    return (err instanceof Error &&
+        (err.name === 'ExitPromptError' || err.constructor?.name === 'ExitPromptError'));
+}
+// ─── @inquirer/prompts wrappers (lazy-imported) ───────────────
+let promptsModulePromise = null;
+async function loadPrompts() {
+    if (!promptsModulePromise) {
+        promptsModulePromise = import('@inquirer/prompts');
+    }
+    return await promptsModulePromise;
+}
+/**
+ * Unified no-human-in-loop check — any path that needs a human must call
+ * this first. Fails fast with non-zero exit + stderr diagnostic + empty
+ * stdout when stdin is not a TTY OR when `--json` is active.
+ */
+function assertInteractive(remediation) {
+    if (currentMode === 'json' || !process.stdin.isTTY) {
+        logFailure(remediation);
+        exit(1);
+    }
+}
+export async function promptText(message, opts = {}) {
+    assertInteractive(`Cannot prompt for "${message}" — stdin is not a TTY.`);
+    emit({ type: 'prompt-input' });
+    const { input } = await loadPrompts();
+    return await input({
+        message,
+        default: opts.placeholder,
+        validate: opts.validate
+            ? (value) => {
+                const result = opts.validate(value);
+                return result === undefined ? true : result;
+            }
+            : undefined,
+    });
+}
+export async function promptSelect(message, choices) {
+    assertInteractive(`Cannot prompt for "${message}" — stdin is not a TTY.`);
+    emit({ type: 'prompt-select' });
+    const { select } = await loadPrompts();
+    return (await select({
+        message,
+        choices: choices.map((c) => ({
+            value: c.value,
+            name: c.name,
+            description: c.description,
+        })),
+    }));
+}
+export async function promptConfirm(message, opts = {}) {
+    assertInteractive(`Cannot prompt for "${message}" — stdin is not a TTY.`);
+    emit({ type: 'prompt-confirm' });
+    const { confirm } = await loadPrompts();
+    return await confirm({ message, default: opts.default ?? false });
+}
+// ─── Error exit — replaces the four copies of handleCliError ──
+/**
+ * Network error codes that route to exit 2 (system-level failures the
+ * caller can retry). Per ADR-072 §D13 / lock A4 — Unix canonical
+ * "transient retryable" set.
+ */
+const NETWORK_RETRY_CODES = new Set([
+    'ECONNREFUSED',
+    'ENOTFOUND',
+    'ETIMEDOUT',
+    'ECONNRESET',
+    'EAI_AGAIN',
+]);
+/**
+ * Map an error onto its semantic exit code (ADR-072 §D13 / A4):
+ *   130 — user cancel (Ctrl-C / ExitPromptError)
+ *     2 — system failure (5xx / connection refused / DNS / timeout)
+ *     1 — user error (parse, validation, 4xx, missing env, …)
+ *
+ * 0 is reserved for success (no error → caller never reaches this path).
+ *
+ * The predicate handles errors at any wrapping depth: post-Batch 3,
+ * `StorystickError(cause: TypeError(cause: { code: 'ECONNREFUSED' }))` is
+ * the canonical shape for fetch failures. We descend up to two `cause`
+ * levels so the predicate stays robust against future shapes.
+ */
+export function routeExitCode(err) {
+    if (isExitPromptCancel(err))
+        return 130;
+    if (err instanceof Error && err.name === 'AbortError')
+        return 130;
+    if (err instanceof StorystickError && typeof err.status === 'number' && err.status >= 500) {
+        return 2;
+    }
+    // Walk up to two cause levels — TypeError-from-fetch is `err.cause`
+    // (when wrapped) or `err` itself, with the system error living one
+    // level deeper as `cause.cause`. Anywhere along the chain that we
+    // find an ECONNREFUSED-style code, route to 2.
+    const visited = new Set();
+    let cur = err;
+    for (let depth = 0; depth < 4 && cur; depth++) {
+        if (visited.has(cur))
+            break;
+        visited.add(cur);
+        const sysCode = cur.code;
+        if (typeof sysCode === 'string' && NETWORK_RETRY_CODES.has(sysCode)) {
+            return 2;
+        }
+        cur = cur.cause;
+    }
+    return 1;
+}
+/**
+ * Print an error and exit. Accepts our `StorystickError` (for which we
+ * dim-append the Pattern D code) or any other `Error | unknown`.
+ *
+ * The caller passes `hint` for structured follow-up text (rendered as a
+ * dim line). Exit code defaults to `routeExitCode(err)` (ADR-072 §D13);
+ * pass `{ exitCode }` to force a specific value.
+ *
+ * Under JSON mode, the human-readable failure line is suppressed — the
+ * caller is expected to have already emitted (or to emit immediately
+ * after) a `{ ok: false, ... }` envelope on stdout.
+ *
+ * Mock via `vi.spyOn(process, 'exit')` in tests.
+ */
+export function exitWithError(err, hint, opts = {}) {
+    if (currentMode !== 'json') {
+        const message = err instanceof Error ? err.message : String(err);
+        logFailure(message);
+        // Surface Pattern D error code if present without leaking the class.
+        const code = err.code;
+        if (typeof code === 'string' && code.length > 0) {
+            writeStderr(`  ${pc.dim(`(${code})`)}\n`);
+        }
+        if (hint)
+            writeStderr(`  ${pc.dim(hint)}\n`);
+    }
+    else {
+        // Always emit the failure event so tests can assert orchestration
+        // even under --json (the human line is muted).
+        emit({
+            type: 'failure',
+            text: err instanceof Error ? err.message : String(err),
+        });
+    }
+    const code = opts.exitCode ?? routeExitCode(err);
+    exit(code);
+}
+/**
+ * Centralized Ctrl-C → exit 130 routing (ADR-072 §A5 / D16). Replaces
+ * the per-call `if (isExitPromptCancel(err)) process.exit(0)` pattern at
+ * 4 sites pre-ADR-072. Only exits if the error IS a prompt cancel; no-op
+ * otherwise so callers can continue with their normal catch path.
+ */
+export function maybeExitOnCancel(err) {
+    if (isExitPromptCancel(err))
+        exit(130);
+}
+/**
+ * Combined "emit JSON failure envelope + exit" for action handlers under
+ * --json mode. Calling exitWithError directly from the canonical-shell
+ * catch block under JSON mode emits a failure event but no envelope —
+ * this helper closes that gap. Caller is responsible for choosing a
+ * meaningful `error.code`; falls back to the StorystickError's code or
+ * a generic 'INTERNAL' marker.
+ */
+export function exitJsonFailure(args) {
+    const { command, err, diagnostics, hint } = args;
+    const envelope = jsonErrorFromUnknown(err, hint);
+    emitJsonResult({
+        command,
+        ok: false,
+        error: envelope,
+        diagnostics: diagnostics ?? [],
+    });
+    exit(routeExitCode(err));
+}
+/** Convert an arbitrary command error into the canonical JSON wire shape. */
+export function jsonErrorFromUnknown(err, hint) {
+    const rawCode = err instanceof StorystickError && err.code
+        ? err.code
+        : err instanceof Error && err.name === 'StorystickError'
+            ? 'STORYSTICK_ERROR'
+            : 'INTERNAL';
+    // Auto-namespace bare CLI codes per ADR-079 batch 6 wire-format
+    // contract (canonical Envelope `code: storystick/<NAME>`).
+    const code = rawCode.startsWith('storystick/')
+        ? rawCode
+        : `storystick/${rawCode}`;
+    const message = err instanceof Error ? err.message : String(err);
+    const structured = err instanceof StorystickError ? err : undefined;
+    const structuredCategory = structured?.category;
+    const category = structuredCategory === 'validation' ||
+        structuredCategory === 'conflict' ||
+        structuredCategory === 'auth' ||
+        structuredCategory === 'system' ||
+        structuredCategory === 'cancel'
+        ? structuredCategory
+        : 'system';
+    // Preserve a canonical gateway envelope end-to-end. CLI-local errors that
+    // lack catalogue metadata retain conservative defaults; network failures
+    // detected by routeExitCode remain retryable.
+    const exitCode = routeExitCode(err);
+    const envelope = {
+        code,
+        message,
+        category,
+        recoverable: structured?.recoverable ?? false,
+        retryable: structured?.retryable ?? exitCode === 2,
+        ...(structured?.payload !== undefined
+            ? { payload: structured.payload }
+            : {}),
+        ...(structured?.messageKey
+            ? { messageKey: structured.messageKey }
+            : hint
+                ? { messageKey: 'cli.hint' }
+                : {}),
+        ...(structured?.params
+            ? { params: structured.params }
+            : hint
+                ? { params: { hint } }
+                : {}),
+        ...(structured?.ref ? { ref: structured.ref } : {}),
+        ...(structured?.docUrl ? { docUrl: structured.docUrl } : {}),
+    };
+    return envelope;
+}
+/** Indirection so tests can stub `process.exit` without patching the primitive. */
+function exit(code) {
+    process.exit(code);
+}
+// ─── Cancellable-work helper (per-command semantic abort) ────
+/**
+ * Bind an `AbortController` to SIGINT for the duration of a piece of work.
+ * Complements the output.ts SIGINT handler (which only cleans UI): this is
+ * how a command translates Ctrl-C into "throw out of the in-flight poll /
+ * fetch". Call `dispose()` in a `finally` so the listener doesn't leak.
+ *
+ * ```ts
+ * const { signal, dispose } = withInterrupt()
+ * try {
+ *   await callHubApi(path, { signal, onAuthPrompt: promptDeviceAuth })
+ * } finally {
+ *   dispose()
+ * }
+ * ```
+ */
+export function withInterrupt() {
+    const ac = new AbortController();
+    const onInt = () => ac.abort();
+    process.on('SIGINT', onInt);
+    return {
+        signal: ac.signal,
+        dispose: () => {
+            process.off('SIGINT', onInt);
+        },
+    };
+}
+// ─── SIGINT — UI cleanup only (no process.exit) ──────────────
+function ensureSigintHandler() {
+    if (sigintInstalled)
+        return;
+    sigintInstalled = true;
+    process.on('SIGINT', onSigint);
+}
+function onSigint() {
+    if (activeSpinner) {
+        try {
+            activeSpinner.stop();
+        }
+        catch {
+            /* spinner teardown shouldn't crash the signal path */
+        }
+        activeSpinner = null;
+    }
+    // Restore the cursor in case a library hid it (DECTCEM show).
+    if (!capture)
+        process.stderr.write('\x1b[?25h');
+    // Per ADR-061: we do NOT call process.exit. Commands that need semantic
+    // cancellation (login's AbortController) register their own listener —
+    // Node fires all listeners.
+}
+// ─── Internal helpers ────────────────────────────────────────
+function makeNoopSpinner(text) {
+    let current = text;
+    return {
+        get text() {
+            return current;
+        },
+        set text(v) {
+            current = v;
+        },
+        succeed: () => { },
+        fail: () => { },
+        stop: () => { },
+    };
+}