@velum-labs/routekit-cli-ui 0.9.0

package/dist/plain.js

@@ -0,0 +1,291 @@
+/**
+ * The plain-text presenter: ordered, deterministic line logs for CI, pipes,
+ * `ROUTEKIT_NO_TUI=1`, and the `node --test` subprocess suites. Live surfaces
+ * print one line per state transition instead of animating in place.
+ */
+import { contentWidth, formatBytes, wrapText } from "./format.js";
+import { uiStream } from "./runtime.js";
+import { bold, box, brandBanner, brandHeader, cyan, dim, glyph, gray, green, red, stripAnsi, yellow } from "./theme.js";
+function statusGlyph(kind) {
+    switch (kind) {
+        case "ok":
+            return green(glyph.tick());
+        case "warn":
+            return yellow(glyph.warn());
+        case "fail":
+            return red(glyph.cross());
+        case "info":
+            return cyan(glyph.bullet());
+        case "pending":
+            return gray(glyph.bullet());
+        default: {
+            const exhaustive = kind;
+            throw new Error(`unknown status kind: ${String(exhaustive)}`);
+        }
+    }
+}
+function stepGlyph(status) {
+    switch (status) {
+        case "pending":
+            return gray(glyph.pending());
+        case "active":
+            return dim(glyph.arrow());
+        case "done":
+            return green(glyph.tick());
+        case "failed":
+            return red(glyph.cross());
+        case "skipped":
+            return yellow(glyph.bullet());
+        default: {
+            const exhaustive = status;
+            throw new Error(`unknown step status: ${String(exhaustive)}`);
+        }
+    }
+}
+/** Pad table cells against their visible (ANSI-stripped) width. */
+function padCell(text, width, align = "left") {
+    const pad = " ".repeat(Math.max(0, width - stripAnsi(text).length));
+    return align === "right" ? pad + text : text + pad;
+}
+export function renderTableLines(rows, options = {}) {
+    const all = options.head !== undefined ? [options.head.map((cell) => dim(cell)), ...rows] : [...rows];
+    if (all.length === 0)
+        return [];
+    const columns = Math.max(...all.map((row) => row.length));
+    const widths = Array.from({ length: columns }, (_, index) => Math.max(...all.map((row) => stripAnsi(row[index] ?? "").length)));
+    const indent = " ".repeat(options.indent ?? 0);
+    return all.map((row) => (indent +
+        row.map((cell, index) => padCell(cell, widths[index] ?? 0, options.align?.[index] ?? "left")).join("  ")).trimEnd());
+}
+/**
+ * Render the failure panel as styled lines: a red-framed box with the message,
+ * dim evidence lines, the hint, and a `try:` next command. Shared by the plain
+ * and Ink presenters (identical settled output) and reused by the top-level
+ * error handler.
+ */
+export function renderErrorPanelLines(input) {
+    const width = contentWidth();
+    const body = wrapText(input.message, width).map((line) => red(line));
+    if (input.details !== undefined && input.details.length > 0) {
+        body.push("");
+        for (const detail of input.details) {
+            for (const line of wrapText(detail, width - 2))
+                body.push(dim(`  ${line}`));
+        }
+    }
+    if (input.hint !== undefined) {
+        body.push("");
+        for (const line of wrapText(input.hint, width))
+            body.push(line);
+    }
+    if (input.tryCommand !== undefined) {
+        body.push("");
+        body.push(`${dim("try:")}  ${cyan(input.tryCommand)}`);
+    }
+    if (input.docs !== undefined) {
+        if (input.tryCommand === undefined)
+            body.push("");
+        body.push(`${dim("docs:")} ${dim(input.docs)}`);
+    }
+    return box(input.title ?? "error", body, { tone: "error" }).split("\n");
+}
+export function renderKeyValueLines(rows) {
+    const labelWidth = Math.max(0, ...rows.map((row) => row.label.length));
+    const valueWidth = Math.max(0, ...rows.map((row) => stripAnsi(row.value).length));
+    return rows.map((row) => {
+        const indent = " ".repeat(2 + (row.indent ?? 0) * 2);
+        const label = dim(row.label.padEnd(labelWidth));
+        const value = row.tag !== undefined ? padCell(row.value, valueWidth) : row.value;
+        const tag = row.tag !== undefined ? ` ${dim(row.tag)}` : "";
+        return `${indent}${label}  ${value}${tag}`.trimEnd();
+    });
+}
+class PlainChecklist {
+    steps;
+    write;
+    constructor(steps, title, write) {
+        this.steps = new Map(steps.map((step) => [step.id, { label: step.label }]));
+        this.write = write;
+        if (title !== undefined)
+            write(title);
+    }
+    transition(id, status, detail) {
+        const step = this.steps.get(id);
+        if (step === undefined)
+            throw new Error(`unknown step id: ${id}`);
+        if (detail !== undefined)
+            step.detail = detail;
+        const suffix = step.detail !== undefined ? ` ${dim(step.detail)}` : "";
+        this.write(`${stepGlyph(status)} ${step.label}${suffix}`);
+    }
+    setActive(id, detail) {
+        this.transition(id, "active", detail);
+    }
+    setDone(id, detail) {
+        this.transition(id, "done", detail);
+    }
+    setFailed(id, detail) {
+        this.transition(id, "failed", detail);
+    }
+    setSkipped(id, detail) {
+        this.transition(id, "skipped", detail);
+    }
+    setDetail(id, detail) {
+        const step = this.steps.get(id);
+        if (step === undefined)
+            throw new Error(`unknown step id: ${id}`);
+        step.detail = detail;
+    }
+    stop() {
+        // line-per-transition output needs no settling
+    }
+}
+class PlainTask {
+    text;
+    write;
+    constructor(text, write) {
+        this.text = text;
+        this.write = write;
+        write(`${dim(glyph.arrow())} ${text}`);
+    }
+    update(text) {
+        this.text = text;
+        this.write(`${dim(glyph.arrow())} ${text}`);
+    }
+    succeed(text) {
+        this.write(`${green(glyph.tick())} ${text ?? this.text}`);
+    }
+    fail(text) {
+        this.write(`${red(glyph.cross())} ${text ?? this.text}`);
+    }
+    warn(text) {
+        this.write(`${yellow(glyph.warn())} ${text ?? this.text}`);
+    }
+    info(text) {
+        this.write(`${cyan(glyph.bullet())} ${text ?? this.text}`);
+    }
+    stop() {
+        // nothing to settle
+    }
+}
+class PlainProgress {
+    label;
+    write;
+    downloaded = 0;
+    total;
+    /** Last milestone (in 10% steps) printed, so logs stay short. */
+    lastMilestone = -1;
+    constructor(label, write) {
+        this.label = label;
+        this.write = write;
+        write(`${dim(glyph.arrow())} ${label}`);
+    }
+    update(progress) {
+        this.downloaded = progress.downloaded;
+        if (progress.total !== undefined && progress.total > 0)
+            this.total = progress.total;
+        if (this.total === undefined)
+            return;
+        const pct = Math.floor((this.downloaded / this.total) * 10) * 10;
+        if (pct > this.lastMilestone && pct < 100) {
+            this.lastMilestone = pct;
+            this.write(`  ${dim(`${pct}% — ${formatBytes(this.downloaded)} / ${formatBytes(this.total)}`)}`);
+        }
+    }
+    succeed(text) {
+        this.write(`${green(glyph.tick())} ${text ?? `${this.label} ${dim(`(${formatBytes(this.downloaded)})`)}`}`);
+    }
+    fail(text) {
+        this.write(`${red(glyph.cross())} ${text ?? `${this.label} ${gray("(failed)")}`}`);
+    }
+    stop() {
+        // nothing to settle
+    }
+}
+class PlainLiveFrame {
+    write;
+    stopped = false;
+    constructor(write) {
+        this.write = write;
+    }
+    render(content) {
+        if (this.stopped)
+            return;
+        this.write(dim(`[${new Date().toISOString()}]`));
+        for (const line of typeof content === "function" ? content() : content)
+            this.write(line);
+    }
+    stop() {
+        this.stopped = true;
+    }
+}
+export class PlainPresenter {
+    interactive = false;
+    stream;
+    constructor(stream = uiStream()) {
+        this.stream = stream;
+    }
+    writeLine = (line) => {
+        this.stream.write(`${line}\n`);
+    };
+    banner(subtitle) {
+        this.writeLine(brandBanner(subtitle));
+    }
+    header(subtitle) {
+        this.writeLine(brandHeader(subtitle));
+    }
+    heading(text) {
+        this.writeLine(bold(text));
+    }
+    line(text) {
+        this.writeLine(text);
+    }
+    blank() {
+        this.stream.write("\n");
+    }
+    note(text) {
+        this.writeLine(`${gray(glyph.arrow())} ${text}`);
+    }
+    success(text) {
+        this.writeLine(`${green(glyph.tick())} ${text}`);
+    }
+    warn(text) {
+        this.writeLine(`${yellow(glyph.warn())} ${text}`);
+    }
+    error(text) {
+        this.writeLine(`${red(glyph.cross())} ${text}`);
+    }
+    status(kind, label, detail, hint) {
+        const suffix = detail !== undefined ? ` ${dim(detail)}` : "";
+        this.writeLine(`  ${statusGlyph(kind)} ${label}${suffix}`);
+        if (hint !== undefined)
+            this.writeLine(`    ${yellow(glyph.arrow())} ${hint}`);
+    }
+    keyValue(rows) {
+        for (const line of renderKeyValueLines(rows))
+            this.writeLine(line);
+    }
+    table(rows, options) {
+        for (const line of renderTableLines(rows, options))
+            this.writeLine(line);
+    }
+    box(title, lines) {
+        this.writeLine(box(title, [...lines]));
+    }
+    errorPanel(input) {
+        for (const line of renderErrorPanelLines(input))
+            this.writeLine(line);
+    }
+    checklist(steps, options = {}) {
+        return new PlainChecklist(steps, options.title, this.writeLine);
+    }
+    task(text) {
+        return new PlainTask(text, this.writeLine);
+    }
+    progress(label) {
+        return new PlainProgress(label, this.writeLine);
+    }
+    liveFrame() {
+        return new PlainLiveFrame(this.writeLine);
+    }
+}

package/dist/presenter.d.ts

@@ -0,0 +1,144 @@
+/**
+ * The presenter contract every command renders through. Two
+ * implementations exist:
+ *
+ * - `InkPresenter` — rich Ink (React) rendering on an interactive TTY.
+ * - `PlainPresenter` — ordered line logs for CI, pipes, and `ROUTEKIT_NO_TUI`.
+ *
+ * Both write exclusively to stderr (`uiStream()`); stdout stays reserved for
+ * machine payloads (`--json`, `config path`, `export-yaml`) and tool output.
+ * Live surfaces (checklist / task / progress) return controllers; a command
+ * must settle a live surface before printing static lines so output never
+ * interleaves with an active Ink render.
+ */
+export type StepStatus = "pending" | "active" | "done" | "failed" | "skipped";
+export type StepInput = {
+    id: string;
+    label: string;
+};
+export type ChecklistController = {
+    setActive(id: string, detail?: string): void;
+    setDone(id: string, detail?: string): void;
+    setFailed(id: string, detail?: string): void;
+    setSkipped(id: string, detail?: string): void;
+    setDetail(id: string, detail: string): void;
+    /** Settle the checklist and leave the final frame in place. */
+    stop(): void;
+};
+export type TaskController = {
+    update(text: string): void;
+    succeed(text?: string): void;
+    fail(text?: string): void;
+    warn(text?: string): void;
+    info(text?: string): void;
+    stop(): void;
+};
+export type ProgressUpdate = {
+    downloaded: number;
+    total?: number;
+    file?: string;
+};
+export type ProgressController = {
+    update(progress: ProgressUpdate): void;
+    succeed(text?: string): void;
+    fail(text?: string): void;
+    stop(): void;
+};
+export type LiveFrameContent = readonly string[] | (() => readonly string[]);
+export type LiveFrameController = {
+    /** Replace the current frame. Plain output appends a timestamped snapshot. */
+    render(content: LiveFrameContent): void;
+    /** Render a failed refresh. Quiet presenters may surface only this frame. */
+    renderError?(content: LiveFrameContent): void;
+    /** Settle the frame and release any terminal resources. Idempotent. */
+    stop(): void;
+};
+/** One row of a `keyValue` block: label, rendered value, optional dim tag. */
+export type KeyValueRow = {
+    label: string;
+    value: string;
+    tag?: string;
+    indent?: number;
+};
+export type TableOptions = {
+    /** Column headers (rendered dim). */
+    head?: string[];
+    /** Indentation (spaces) applied to every row. */
+    indent?: number;
+    /** Per-column alignment (numbers read best right-aligned). Defaults to left. */
+    align?: readonly ("left" | "right")[];
+};
+/**
+ * One error, three renderings: a red-framed panel on rich/plain UI, prefixed
+ * lines when boxes would be noise, and the same fields in `--json` payloads.
+ */
+export type ErrorPanelInput = {
+    /** Panel title (defaults to "error"). */
+    title?: string;
+    message: string;
+    /** Supporting evidence, e.g. a distilled log tail (rendered dim). */
+    details?: readonly string[];
+    /** A human explanation of what likely went wrong / what to check. */
+    hint?: string;
+    /** A copy-pasteable next command, rendered as `→ try: <command>`. */
+    tryCommand?: string;
+    /** A docs URL for the failure area. */
+    docs?: string;
+};
+export type StatusKind = "ok" | "warn" | "fail" | "info" | "pending";
+export interface Presenter {
+    /** True when this presenter renders rich (Ink) output. */
+    readonly interactive: boolean;
+    /** The full-dress brand banner (degrades to a one-line header when plain). */
+    banner(subtitle?: string): void;
+    /** The compact one-line brand header. */
+    header(subtitle?: string): void;
+    /** A bold section heading. */
+    heading(text: string): void;
+    /** A raw styled line. */
+    line(text: string): void;
+    /** An empty spacer line. */
+    blank(): void;
+    /** A dim informational note (arrow-prefixed). */
+    note(text: string): void;
+    /** A green tick line. */
+    success(text: string): void;
+    /** A yellow warning line. */
+    warn(text: string): void;
+    /** A red error line. */
+    error(text: string): void;
+    /** A status row: glyph + label + optional dim detail + optional hint line. */
+    status(kind: StatusKind, label: string, detail?: string, hint?: string): void;
+    /** Aligned label/value rows with optional provenance tags. */
+    keyValue(rows: readonly KeyValueRow[]): void;
+    /** A simple aligned table. */
+    table(rows: readonly (readonly string[])[], options?: TableOptions): void;
+    /** A titled rounded box. */
+    box(title: string, lines: readonly string[]): void;
+    /** A red-framed failure panel: message, evidence, hint, and the next command. */
+    errorPanel(input: ErrorPanelInput): void;
+    /** A live multi-step checklist. */
+    checklist(steps: readonly StepInput[], options?: {
+        title?: string;
+    }): ChecklistController;
+    /** A single live spinner task. */
+    task(text: string): TaskController;
+    /** A live byte-download progress bar. */
+    progress(label: string): ProgressController;
+    /** A generic replaceable region for status dashboards and watch commands. */
+    liveFrame(): LiveFrameController;
+}
+/** Run `work` under a task spinner, settling to success/failure automatically. */
+export declare function withTask<T>(presenter: Presenter, text: string, work: () => Promise<T>, options?: {
+    success?: (value: T) => string;
+    failure?: (error: unknown) => string;
+}): Promise<T>;
+export type WatchOptions = {
+    signal?: AbortSignal;
+    errorFrame?: (error: unknown) => readonly string[];
+};
+/**
+ * Poll and redraw a live frame until Ctrl+C or an AbortSignal stops it.
+ * Fetch failures become frames and are retried on the next interval.
+ */
+export declare function watch(presenter: Presenter, intervalSeconds: number, fetchAndRender: (signal: AbortSignal) => Promise<LiveFrameContent> | LiveFrameContent, options?: WatchOptions): Promise<void>;

package/dist/presenter.js

@@ -0,0 +1,124 @@
+/**
+ * The presenter contract every command renders through. Two
+ * implementations exist:
+ *
+ * - `InkPresenter` — rich Ink (React) rendering on an interactive TTY.
+ * - `PlainPresenter` — ordered line logs for CI, pipes, and `ROUTEKIT_NO_TUI`.
+ *
+ * Both write exclusively to stderr (`uiStream()`); stdout stays reserved for
+ * machine payloads (`--json`, `config path`, `export-yaml`) and tool output.
+ * Live surfaces (checklist / task / progress) return controllers; a command
+ * must settle a live surface before printing static lines so output never
+ * interleaves with an active Ink render.
+ */
+/** Run `work` under a task spinner, settling to success/failure automatically. */
+export async function withTask(presenter, text, work, options = {}) {
+    const task = presenter.task(text);
+    try {
+        const value = await work();
+        task.succeed(options.success ? options.success(value) : text);
+        return value;
+    }
+    catch (error) {
+        task.fail(options.failure ? options.failure(error) : `${text} (failed)`);
+        throw error;
+    }
+}
+function waitForInterval(milliseconds, signal) {
+    return new Promise((resolve) => {
+        let settled = false;
+        let timer;
+        const finish = () => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal.removeEventListener("abort", finish);
+            resolve();
+        };
+        timer = setTimeout(finish, milliseconds);
+        signal.addEventListener("abort", finish, { once: true });
+        if (signal.aborted)
+            finish();
+    });
+}
+function fetchFrame(fetchAndRender, signal) {
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const cleanup = () => signal.removeEventListener("abort", onAbort);
+        const succeed = (content) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            resolve(content);
+        };
+        const fail = (error) => {
+            if (settled)
+                return;
+            settled = true;
+            cleanup();
+            reject(error);
+        };
+        const onAbort = () => succeed(undefined);
+        signal.addEventListener("abort", onAbort, { once: true });
+        if (signal.aborted) {
+            onAbort();
+            return;
+        }
+        Promise.resolve()
+            .then(() => {
+            if (settled || signal.aborted)
+                return undefined;
+            return fetchAndRender(signal);
+        })
+            .then((content) => {
+            if (content !== undefined)
+                succeed(content);
+        }, fail);
+    });
+}
+/**
+ * Poll and redraw a live frame until Ctrl+C or an AbortSignal stops it.
+ * Fetch failures become frames and are retried on the next interval.
+ */
+export async function watch(presenter, intervalSeconds, fetchAndRender, options = {}) {
+    const frame = presenter.liveFrame();
+    const localAbort = new AbortController();
+    const onSigint = () => localAbort.abort();
+    const onExternalAbort = () => localAbort.abort();
+    process.once("SIGINT", onSigint);
+    options.signal?.addEventListener("abort", onExternalAbort, { once: true });
+    if (options.signal?.aborted === true)
+        localAbort.abort();
+    const milliseconds = Math.max(0.1, intervalSeconds) * 1000;
+    try {
+        while (!localAbort.signal.aborted) {
+            try {
+                const content = await fetchFrame(fetchAndRender, localAbort.signal);
+                if (content === undefined || localAbort.signal.aborted)
+                    break;
+                frame.render(content);
+            }
+            catch (error) {
+                if (localAbort.signal.aborted)
+                    break;
+                const content = options.errorFrame?.(error) ?? [
+                    `error: ${error instanceof Error ? error.message : String(error)}`,
+                    `retrying in ${intervalSeconds}s`
+                ];
+                if (frame.renderError !== undefined)
+                    frame.renderError(content);
+                else
+                    frame.render(content);
+            }
+            await waitForInterval(milliseconds, localAbort.signal);
+        }
+    }
+    finally {
+        process.removeListener("SIGINT", onSigint);
+        options.signal?.removeEventListener("abort", onExternalAbort);
+        frame.stop();
+    }
+}

package/dist/prompt.d.ts

@@ -0,0 +1,95 @@
+export type SelectOption<T> = {
+    value: T;
+    label: string;
+    hint?: string;
+};
+/** Returned by prompts with `allowBack: true` when the user presses Esc. */
+export declare const BACK: unique symbol;
+export type Back = typeof BACK;
+/**
+ * Single-choice selection. On a raw-capable TTY this is an Ink arrow-key
+ * picker with a live highlighted cursor; otherwise it falls back to a numbered
+ * prompt read from stdin (so piped input and non-raw terminals still work).
+ * Returns the default when input is empty or unparseable.
+ */
+export declare function select<T>(input: {
+    message: string;
+    options: ReadonlyArray<SelectOption<T>>;
+    defaultIndex?: number;
+    allowBack: true;
+}): Promise<T | Back>;
+export declare function select<T>(input: {
+    message: string;
+    options: ReadonlyArray<SelectOption<T>>;
+    defaultIndex?: number;
+}): Promise<T>;
+/**
+ * Type-to-filter selection over a (possibly large or live-fetched) option
+ * list: fuzzy subsequence filtering with highlighted matches, arrow keys to
+ * move, enter to pick. `refresh` (when given) runs in the background while the
+ * picker is open — the list starts on the cached `options` and live-updates
+ * when fresh data lands (stale-while-revalidate). Falls back to the numbered
+ * prompt off-TTY, awaiting `refresh` first only when no cached options exist.
+ */
+export declare function fuzzySelect<T>(input: {
+    message: string;
+    options: ReadonlyArray<SelectOption<T>>;
+    refresh?: () => Promise<ReadonlyArray<SelectOption<T>>>;
+    refreshNote?: string;
+    placeholder?: string;
+    allowBack: true;
+}): Promise<T | Back>;
+export declare function fuzzySelect<T>(input: {
+    message: string;
+    options: ReadonlyArray<SelectOption<T>>;
+    refresh?: () => Promise<ReadonlyArray<SelectOption<T>>>;
+    refreshNote?: string;
+    placeholder?: string;
+}): Promise<T>;
+/**
+ * Free text with an inline ghost suggestion completed from `suggestions`
+ * (Tab or → accepts). Falls back to the plain text prompt off-TTY.
+ */
+export declare function autocompleteText(input: {
+    message: string;
+    suggestions: ReadonlyArray<string>;
+    defaultValue?: string;
+    placeholder?: string;
+    allowBack?: boolean;
+}): Promise<string | Back>;
+/**
+ * Multi-choice selection. On a raw-capable TTY this is an Ink checkbox list;
+ * otherwise it reads comma-separated numbers from stdin (empty input keeps the
+ * default selection).
+ */
+export declare function multiselect<T>(input: {
+    message: string;
+    options: ReadonlyArray<SelectOption<T>>;
+    defaultSelected?: readonly number[];
+}): Promise<T[]>;
+/** Yes/no confirmation. Returns `defaultValue` on empty input. */
+export declare function confirm(input: {
+    message: string;
+    defaultValue?: boolean;
+    allowBack: true;
+}): Promise<boolean | Back>;
+export declare function confirm(input: {
+    message: string;
+    defaultValue?: boolean;
+}): Promise<boolean>;
+/** Free-text prompt. Returns `defaultValue` (or "") on empty input. */
+export declare function text(input: {
+    message: string;
+    defaultValue?: string;
+    placeholder?: string;
+    allowBack: true;
+}): Promise<string | Back>;
+export declare function text(input: {
+    message: string;
+    defaultValue?: string;
+    placeholder?: string;
+}): Promise<string>;
+/** A success line for the end of a wizard. */
+export declare function done(message: string): void;
+/** A neutral note line. */
+export declare function note(message: string): void;