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

package/dist/output.d.ts

@@ -0,0 +1,347 @@
+/**
+ * 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 type { Diagnostic } from '@storystick/core';
+export type OutputMode = 'human' | 'json';
+export type OutputEvent = {
+    type: 'spinner-start';
+    text: string;
+} | {
+    type: 'spinner-change';
+    text: string;
+} | {
+    type: 'spinner-success';
+    text: string;
+} | {
+    type: 'spinner-failure';
+    text: string;
+} | {
+    type: 'spinner-stop';
+} | {
+    type: 'finished-step';
+    text: string;
+} | {
+    type: 'failure';
+    text: string;
+} | {
+    type: 'warning';
+    text: string;
+} | {
+    type: 'message';
+    text: string;
+} | {
+    type: 'data';
+} | {
+    type: 'data-jsonl';
+    event: string;
+} | {
+    type: 'prompt-device-auth';
+} | {
+    type: 'prompt-input';
+} | {
+    type: 'prompt-select';
+} | {
+    type: 'prompt-confirm';
+};
+export interface Capture {
+    stdout: string[];
+    stderr: string[];
+    events: OutputEvent[];
+}
+export interface DeviceAuthPromptData {
+    /** Canonical recipient of the device credential, independent of the Hub UI. */
+    issuer?: string;
+    verificationUrl: string;
+    userCode: string;
+    expiresIn: number;
+    /** Text shown on the post-prompt spinner. Defaults to "Waiting for
+     * authorization…". Per ADR-061, all six call sites collapse to this
+     * single function. */
+    waitingText?: string;
+}
+export interface ConfigureOutputOptions {
+    json?: boolean;
+    verbose?: boolean;
+    quiet?: boolean;
+}
+/**
+ * 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 declare function configureOutput(opts?: ConfigureOutputOptions): void;
+export declare function getOutputMode(): OutputMode;
+/**
+ * `--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 declare function isVerbose(): boolean;
+/**
+ * `--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 declare function isQuiet(): boolean;
+/**
+ * Fully reset module state. Call from `beforeEach` in tests — the in-process
+ * test suite shares this module across cases.
+ */
+export declare function resetOutput(): void;
+/**
+ * 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 declare function __testing_enableCapture(): Capture;
+export declare function onEvent(fn: (event: OutputEvent) => void): () => void;
+/** Dimmed status line — muted under --json or --quiet. */
+export declare function logMessage(text: string): void;
+export declare function logFinishedStep(text: string): void;
+export declare function logFailure(text: string): void;
+export declare function logWarning(text: string): void;
+/**
+ * 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 declare function logOutput(payload: string): void;
+import type { Envelope } from '@storystick/types/errors';
+export type JsonDiagnostic = Diagnostic;
+export type JsonError = Envelope;
+export type CliJsonEnvelope = {
+    ok: true;
+    command: string;
+    version: '1';
+    data: unknown;
+    diagnostics: JsonDiagnostic[];
+} | {
+    ok: false;
+    command: string;
+    version: '1';
+    error: JsonError;
+    diagnostics: JsonDiagnostic[];
+};
+/**
+ * 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 declare function diagnosticToJson(d: Diagnostic): JsonDiagnostic;
+/**
+ * Emit the single-result envelope on stdout. One call per command — the
+ * stream-discipline lint asserts a single `data` event per invocation.
+ *
+ * `version: "1"` is documented as a "format placeholder for future schema
+ * evolution" (ADR-072 §L8 / D15) — there's no migration negotiation
+ * promised, just a stable marker.
+ */
+export declare function emitJsonResult<T>(args: {
+    command: string;
+    ok: true;
+    data: T;
+    diagnostics?: JsonDiagnostic[];
+}): void;
+export declare function emitJsonResult(args: {
+    command: string;
+    ok: false;
+    error: JsonError;
+    diagnostics?: JsonDiagnostic[];
+}): void;
+/**
+ * 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 declare function emitJsonlEvent<T>(args: {
+    command: string;
+    event: 'progress' | 'final';
+    data: T;
+    ok?: boolean;
+}): void;
+/** Emit the terminal canonical failure event for a JSONL command. */
+export declare function emitJsonlFailure(args: {
+    command: string;
+    err: unknown;
+    hint?: string;
+}): void;
+export declare function formatDiagnostic(d: Diagnostic, rootDir: string): string;
+/**
+ * Start a spinner. Under `--json` or capture, no TTY updates happen — the
+ * event is still emitted so tests can assert the orchestration shape.
+ */
+export declare function showSpinner(text: string): Promise<void>;
+/** Mutate the active spinner's text in place. No-op if no spinner is live. */
+export declare function changeSpinner(text: string): void;
+/** Land the spinner with `✔ <text>` (or the current spinner text). */
+export declare function succeedSpinner(text?: string): void;
+/** Land the spinner with `✖ <text>`. */
+export declare function failSpinner(text?: string): void;
+/** Stop the spinner without landing a symbol. UI cleanup — no event. */
+export declare function stopSpinner(): void;
+/**
+ * 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 declare function showSpinnerIfSlow<T>(text: string, delayMs: number, fn: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function withSlowSpinner<T>(text: string, delayMs: number, fn: () => Promise<T>): Promise<T>;
+/**
+ * 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 declare function promptDeviceAuth(data: DeviceAuthPromptData): void;
+/**
+ * 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 declare function isExitPromptCancel(err: unknown): boolean;
+export declare function promptText(message: string, opts?: {
+    placeholder?: string;
+    validate?: (v: string) => string | undefined;
+}): Promise<string>;
+export declare function promptSelect<T extends string>(message: string, choices: Array<{
+    value: T;
+    name: string;
+    description?: string;
+}>): Promise<T>;
+export declare function promptConfirm(message: string, opts?: {
+    default?: boolean;
+}): Promise<boolean>;
+/**
+ * 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 declare function routeExitCode(err: unknown): 130 | 2 | 1;
+export interface ExitWithErrorOptions {
+    /** Override the routed exit code. Pass `1` or `2`. */
+    exitCode?: 1 | 2;
+}
+/**
+ * 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 declare function exitWithError(err: unknown, hint?: string, opts?: ExitWithErrorOptions): never;
+/**
+ * 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 declare function maybeExitOnCancel(err: unknown): void;
+/**
+ * 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 declare function exitJsonFailure(args: {
+    command: string;
+    err: unknown;
+    diagnostics?: JsonDiagnostic[];
+    hint?: string;
+}): never;
+/** Convert an arbitrary command error into the canonical JSON wire shape. */
+export declare function jsonErrorFromUnknown(err: unknown, hint?: string): JsonError;
+/**
+ * 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 declare function withInterrupt(): {
+    signal: AbortSignal;
+    dispose: () => void;
+};