@velum-labs/routekit-cli-ui 0.9.0

package/dist/ink/presenter.d.ts

@@ -0,0 +1,31 @@
+import type { Instance } from "ink";
+import type { ReactElement } from "react";
+import { PlainPresenter } from "../plain.js";
+import type { ChecklistController, LiveFrameController, ProgressController, StepInput, TaskController } from "../presenter.js";
+/** Mount a bounded Ink app on stderr (stdout stays reserved for payloads). */
+export declare function mountInk(node: ReactElement): Instance;
+/**
+ * Clear the live Ink region and unmount, leaving the terminal clean for the
+ * caller to write the settled plain lines.
+ *
+ * Ink throttles renders (~30fps) with a trailing call, so `instance.clear()`
+ * followed by `unmount()` is racy: unmount flushes the pending trailing
+ * render *after* the clear, repainting the live frame — which the caller's
+ * raw write then duplicates on screen. Rerendering an empty node first makes
+ * that flushed render paint emptiness (erasing the region), so nothing stale
+ * survives the unmount.
+ */
+export declare function settleInk(instance: Instance): void;
+/**
+ * Rich presenter. Extends the plain presenter for static output (identical
+ * line rendering) and swaps the live surfaces for Ink-mounted components.
+ */
+export declare class InkPresenter extends PlainPresenter {
+    readonly interactive: boolean;
+    checklist(steps: readonly StepInput[], options?: {
+        title?: string;
+    }): ChecklistController;
+    task(text: string): TaskController;
+    progress(label: string): ProgressController;
+    liveFrame(): LiveFrameController;
+}

package/dist/ink/presenter.js

@@ -0,0 +1,250 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+/**
+ * The Ink presenter: rich rendering for interactive TTYs. Static output is
+ * written as styled lines (identical to the plain presenter, so transcripts
+ * stay consistent); live surfaces — checklist, task, progress — mount a
+ * bounded Ink app each, and settle by clearing the live region, unmounting,
+ * and writing the final state as ordinary lines. Nothing stays mounted after
+ * a surface settles, so the terminal can always be handed to a spawned coding
+ * agent cleanly.
+ */
+import { render } from "ink";
+import { createElement, Fragment } from "react";
+import { formatBytes } from "../format.js";
+import { PlainPresenter } from "../plain.js";
+import { uiStream } from "../runtime.js";
+import { cyan, dim, glyph, gray, green, red, yellow } from "../theme.js";
+import { ChecklistView, LiveFrameView, ProgressView, TaskView } from "./components.js";
+import { Store } from "./store.js";
+/** Mount a bounded Ink app on stderr (stdout stays reserved for payloads). */
+export function mountInk(node) {
+    return render(node, {
+        stdout: uiStream(),
+        stderr: uiStream(),
+        stdin: process.stdin,
+        exitOnCtrlC: false,
+        patchConsole: false
+    });
+}
+/**
+ * Clear the live Ink region and unmount, leaving the terminal clean for the
+ * caller to write the settled plain lines.
+ *
+ * Ink throttles renders (~30fps) with a trailing call, so `instance.clear()`
+ * followed by `unmount()` is racy: unmount flushes the pending trailing
+ * render *after* the clear, repainting the live frame — which the caller's
+ * raw write then duplicates on screen. Rerendering an empty node first makes
+ * that flushed render paint emptiness (erasing the region), so nothing stale
+ * survives the unmount.
+ */
+export function settleInk(instance) {
+    instance.rerender(createElement(Fragment));
+    instance.unmount();
+    instance.cleanup();
+}
+function stepFinalLine(step) {
+    let symbol;
+    switch (step.status) {
+        case "pending":
+            symbol = gray(glyph.pending());
+            break;
+        case "active":
+            symbol = dim(glyph.arrow());
+            break;
+        case "done":
+            symbol = green(glyph.tick());
+            break;
+        case "failed":
+            symbol = red(glyph.cross());
+            break;
+        case "skipped":
+            symbol = yellow(glyph.bullet());
+            break;
+        default: {
+            const exhaustive = step.status;
+            throw new Error(`unknown step status: ${String(exhaustive)}`);
+        }
+    }
+    const detail = step.detail !== undefined ? ` ${dim(step.detail)}` : "";
+    const elapsed = step.startedAt !== undefined && step.endedAt !== undefined && step.endedAt - step.startedAt >= 50
+        ? gray(` ${((step.endedAt - step.startedAt) / 1000).toFixed(1)}s`)
+        : "";
+    return `${symbol} ${step.label}${detail}${elapsed}`;
+}
+class InkChecklist {
+    store;
+    instance;
+    stream = uiStream();
+    settled = false;
+    constructor(steps, title) {
+        this.store = new Store({
+            ...(title !== undefined ? { title } : {}),
+            steps: steps.map((step) => ({ id: step.id, label: step.label, status: "pending" }))
+        });
+        this.instance = mountInk(_jsx(ChecklistView, { store: this.store }));
+    }
+    transition(id, status, detail) {
+        this.store.set((state) => ({
+            ...state,
+            steps: state.steps.map((step) => {
+                if (step.id !== id)
+                    return step;
+                const now = Date.now();
+                const startedAt = step.startedAt ?? (status !== "pending" ? now : undefined);
+                const endedAt = status === "done" || status === "failed" || status === "skipped"
+                    ? (step.endedAt ?? now)
+                    : step.endedAt;
+                return {
+                    ...step,
+                    status,
+                    ...(detail !== undefined ? { detail } : {}),
+                    ...(startedAt !== undefined ? { startedAt } : {}),
+                    ...(endedAt !== undefined ? { endedAt } : {})
+                };
+            })
+        }));
+    }
+    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) {
+        this.store.set((state) => ({
+            ...state,
+            steps: state.steps.map((step) => (step.id === id ? { ...step, detail } : step))
+        }));
+    }
+    stop() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        settleInk(this.instance);
+        const state = this.store.get();
+        const lines = [];
+        if (state.title !== undefined)
+            lines.push(state.title);
+        for (const step of state.steps)
+            lines.push(stepFinalLine(step));
+        this.stream.write(lines.join("\n") + "\n");
+    }
+}
+class InkTask {
+    store;
+    instance;
+    stream = uiStream();
+    settled = false;
+    constructor(text) {
+        this.store = new Store({ text });
+        this.instance = mountInk(_jsx(TaskView, { store: this.store }));
+    }
+    update(text) {
+        this.store.set((state) => ({ ...state, text }));
+    }
+    settle(line) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        settleInk(this.instance);
+        if (line !== undefined)
+            this.stream.write(`${line}\n`);
+    }
+    succeed(text) {
+        this.settle(`${green(glyph.tick())} ${text ?? this.store.get().text}`);
+    }
+    fail(text) {
+        this.settle(`${red(glyph.cross())} ${text ?? this.store.get().text}`);
+    }
+    warn(text) {
+        this.settle(`${yellow(glyph.warn())} ${text ?? this.store.get().text}`);
+    }
+    info(text) {
+        this.settle(`${cyan(glyph.bullet())} ${text ?? this.store.get().text}`);
+    }
+    stop() {
+        this.settle(undefined);
+    }
+}
+class InkProgress {
+    store;
+    instance;
+    stream = uiStream();
+    settled = false;
+    constructor(label) {
+        this.store = new Store({ label, downloaded: 0, startedAt: Date.now() });
+        this.instance = mountInk(_jsx(ProgressView, { store: this.store }));
+    }
+    update(progress) {
+        this.store.set((state) => ({
+            ...state,
+            downloaded: progress.downloaded,
+            ...(progress.total !== undefined && progress.total > 0 ? { total: progress.total } : {})
+        }));
+    }
+    settle(line) {
+        if (this.settled)
+            return;
+        this.settled = true;
+        settleInk(this.instance);
+        if (line !== undefined)
+            this.stream.write(`${line}\n`);
+    }
+    succeed(text) {
+        const state = this.store.get();
+        this.settle(`${green(glyph.tick())} ${text ?? `${state.label} ${dim(`(${formatBytes(state.downloaded)})`)}`}`);
+    }
+    fail(text) {
+        const state = this.store.get();
+        this.settle(`${red(glyph.cross())} ${text ?? `${state.label} ${gray("(failed)")}`}`);
+    }
+    stop() {
+        this.settle(undefined);
+    }
+}
+class InkLiveFrame {
+    store = new Store({ lines: [] });
+    instance = mountInk(_jsx(LiveFrameView, { store: this.store }));
+    stream = uiStream();
+    settled = false;
+    render(content) {
+        if (this.settled)
+            return;
+        const lines = [...(typeof content === "function" ? content() : content)];
+        this.store.set(() => ({ lines }));
+    }
+    stop() {
+        if (this.settled)
+            return;
+        this.settled = true;
+        settleInk(this.instance);
+        const lines = this.store.get().lines;
+        if (lines.length > 0)
+            this.stream.write(`${lines.join("\n")}\n`);
+    }
+}
+/**
+ * Rich presenter. Extends the plain presenter for static output (identical
+ * line rendering) and swaps the live surfaces for Ink-mounted components.
+ */
+export class InkPresenter extends PlainPresenter {
+    interactive = true;
+    checklist(steps, options = {}) {
+        return new InkChecklist(steps, options.title);
+    }
+    task(text) {
+        return new InkTask(text);
+    }
+    progress(label) {
+        return new InkProgress(label);
+    }
+    liveFrame() {
+        return new InkLiveFrame();
+    }
+}

package/dist/ink/prompts.d.ts

@@ -0,0 +1,73 @@
+import type { ReactElement } from "react";
+import { Store } from "./store.js";
+export type PromptOption<T> = {
+    value: T;
+    label: string;
+    hint?: string;
+};
+type SelectProps<T> = {
+    message: string;
+    options: ReadonlyArray<PromptOption<T>>;
+    defaultIndex: number;
+    onSubmit: (value: T, label: string) => void;
+    onAbort: () => void;
+    /** Esc pressed (wizard back-navigation); omitted = Esc is ignored. */
+    onBack?: (() => void) | undefined;
+};
+export declare function SelectPrompt<T>({ message, options, defaultIndex, onSubmit, onAbort, onBack }: SelectProps<T>): ReactElement;
+type MultiSelectProps<T> = {
+    message: string;
+    options: ReadonlyArray<PromptOption<T>>;
+    defaultSelected: ReadonlySet<number>;
+    onSubmit: (values: T[], labels: string[]) => void;
+    onAbort: () => void;
+};
+export declare function MultiSelectPrompt<T>({ message, options, defaultSelected, onSubmit, onAbort }: MultiSelectProps<T>): ReactElement;
+type ConfirmProps = {
+    message: string;
+    defaultValue: boolean;
+    onSubmit: (value: boolean) => void;
+    onAbort: () => void;
+    onBack?: (() => void) | undefined;
+};
+export declare function ConfirmPrompt({ message, defaultValue, onSubmit, onAbort, onBack }: ConfirmProps): ReactElement;
+type TextProps = {
+    message: string;
+    defaultValue: string;
+    placeholder?: string;
+    onSubmit: (value: string) => void;
+    onAbort: () => void;
+    onBack?: (() => void) | undefined;
+};
+export declare function TextPrompt({ message, defaultValue, placeholder, onSubmit, onAbort, onBack }: TextProps): ReactElement;
+/** Live option feed: the facade refreshes `options` while the picker is open. */
+export type FuzzyFeed<T> = {
+    options: ReadonlyArray<PromptOption<T>>;
+    /** True while a background refresh is in flight (renders a spinner note). */
+    loading: boolean;
+    /** A dim note about the feed, e.g. "refreshing model catalog…". */
+    note?: string;
+};
+type FuzzySelectProps<T> = {
+    message: string;
+    feed: Store<FuzzyFeed<T>>;
+    placeholder?: string | undefined;
+    onSubmit: (value: T, label: string) => void;
+    onAbort: () => void;
+    onBack?: (() => void) | undefined;
+};
+export declare function FuzzySelectPrompt<T>({ message, feed, placeholder, onSubmit, onAbort, onBack }: FuzzySelectProps<T>): ReactElement;
+type GhostTextProps = {
+    message: string;
+    /** Ranked suggestion candidates; the first prefix-completion wins. */
+    suggestions: ReadonlyArray<string>;
+    placeholder?: string | undefined;
+    defaultValue: string;
+    onSubmit: (value: string) => void;
+    onAbort: () => void;
+    onBack?: (() => void) | undefined;
+};
+/** The inline (ghost) completion for `value`: the remainder of the best prefix match. */
+export declare function ghostRemainder(value: string, suggestions: ReadonlyArray<string>): string | undefined;
+export declare function GhostTextPrompt({ message, suggestions, placeholder, defaultValue, onSubmit, onAbort, onBack }: GhostTextProps): ReactElement;
+export {};