@fusionkit/cli 0.1.0 → 0.1.1

package/dist/ui/prompt.d.ts

@@ -0,0 +1,30 @@
+export type SelectOption<T> = {
+    value: T;
+    label: string;
+    hint?: string;
+};
+/**
+ * Single-choice selection. On a raw-capable TTY this is arrow-key driven 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;
+}): Promise<T>;
+/** Yes/no confirmation. Returns `defaultValue` on empty input. */
+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;
+}): 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;

package/dist/ui/prompt.js

@@ -0,0 +1,178 @@
+import { createInterface, emitKeypressEvents } from "node:readline";
+import { canPromptInteractively, uiStream } from "./runtime.js";
+import { bold, cyan, dim, glyph, gray, green } from "./theme.js";
+const out = uiStream();
+// For non-interactive input (piped/redirected/empty stdin) we read all of stdin
+// exactly once and serve answers line by line. This supports scripted input
+// (`printf "2\n3\n" | fusionkit fusion init`) and falls back to "" (the prompt
+// default) once exhausted — without the fragile behavior of attaching multiple
+// readline interfaces to an already-ended stdin.
+let bufferedLines;
+let bufferedRead = false;
+async function ensureBufferedStdin() {
+    if (bufferedRead)
+        return;
+    bufferedRead = true;
+    if (process.stdin.isTTY || process.stdin.readableEnded) {
+        bufferedLines = [];
+        return;
+    }
+    const chunks = [];
+    await new Promise((resolve) => {
+        process.stdin.on("data", (chunk) => chunks.push(Buffer.from(chunk)));
+        process.stdin.once("end", () => resolve());
+        process.stdin.once("error", () => resolve());
+    });
+    bufferedLines = Buffer.concat(chunks).toString("utf8").split("\n");
+}
+/**
+ * Read a single line from stdin, prompting on stderr. On a TTY this reads live;
+ * otherwise it draws from buffered stdin and resolves to "" when there is no
+ * more input, so callers fall back to their default instead of hanging.
+ */
+async function readLine(promptText) {
+    if (!process.stdin.isTTY) {
+        out.write(promptText);
+        await ensureBufferedStdin();
+        const next = bufferedLines?.shift();
+        out.write("\n");
+        return (next ?? "").trim();
+    }
+    return new Promise((resolve) => {
+        const rl = createInterface({ input: process.stdin, output: out });
+        let answered = false;
+        rl.question(promptText, (answer) => {
+            answered = true;
+            rl.close();
+            resolve(answer.trim());
+        });
+        rl.on("close", () => {
+            if (!answered)
+                resolve("");
+        });
+    });
+}
+/**
+ * Single-choice selection. On a raw-capable TTY this is arrow-key driven 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 async function select(input) {
+    const { options } = input;
+    if (options.length === 0)
+        throw new Error("select requires at least one option");
+    const fallbackIndex = Math.min(Math.max(input.defaultIndex ?? 0, 0), options.length - 1);
+    if (!canPromptInteractively()) {
+        return selectNumbered(input.message, options, fallbackIndex);
+    }
+    return selectInteractive(input.message, options, fallbackIndex);
+}
+function optionAt(options, index) {
+    const option = options[index];
+    if (option === undefined)
+        throw new Error(`option index out of range: ${index}`);
+    return option;
+}
+async function selectNumbered(message, options, fallbackIndex) {
+    out.write(`${bold(message)}\n`);
+    options.forEach((option, index) => {
+        const marker = index === fallbackIndex ? cyan(`${index + 1}`) : `${index + 1}`;
+        const hint = option.hint !== undefined ? dim(` — ${option.hint}`) : "";
+        out.write(`  ${marker}) ${option.label}${hint}\n`);
+    });
+    const answer = await readLine(`Choose [1-${options.length}] (${fallbackIndex + 1}): `);
+    if (answer.length === 0)
+        return optionAt(options, fallbackIndex).value;
+    const byNumber = Number.parseInt(answer, 10);
+    if (Number.isInteger(byNumber) && byNumber >= 1 && byNumber <= options.length) {
+        return optionAt(options, byNumber - 1).value;
+    }
+    const byLabel = options.findIndex((option) => option.label.toLowerCase() === answer.toLowerCase());
+    if (byLabel >= 0)
+        return optionAt(options, byLabel).value;
+    return optionAt(options, fallbackIndex).value;
+}
+function selectInteractive(message, options, fallbackIndex) {
+    return new Promise((resolve) => {
+        let cursor = fallbackIndex;
+        let rendered = 0;
+        const stdin = process.stdin;
+        emitKeypressEvents(stdin);
+        const wasRaw = stdin.isRaw === true;
+        if (stdin.setRawMode)
+            stdin.setRawMode(true);
+        stdin.resume();
+        out.write("\u001b[?25l");
+        const render = () => {
+            if (rendered > 0) {
+                out.write(`\u001b[${rendered}A`);
+                out.write("\u001b[0J");
+            }
+            const lines = [bold(message)];
+            options.forEach((option, index) => {
+                const active = index === cursor;
+                const pointer = active ? cyan(glyph.pointer()) : " ";
+                const label = active ? cyan(option.label) : option.label;
+                const hint = option.hint !== undefined ? dim(` — ${option.hint}`) : "";
+                lines.push(`${pointer} ${label}${hint}`);
+            });
+            lines.push(dim("  (arrows to move, enter to select)"));
+            out.write(lines.join("\n") + "\n");
+            rendered = lines.length;
+        };
+        const cleanup = () => {
+            stdin.removeListener("keypress", onKey);
+            if (stdin.setRawMode)
+                stdin.setRawMode(wasRaw);
+            stdin.pause();
+            out.write("\u001b[?25h");
+        };
+        const onKey = (_str, key) => {
+            if (key.sequence === "\u0003") {
+                cleanup();
+                out.write("\n");
+                process.exit(130);
+            }
+            if (key.name === "up" || key.name === "k") {
+                cursor = (cursor - 1 + options.length) % options.length;
+                render();
+            }
+            else if (key.name === "down" || key.name === "j") {
+                cursor = (cursor + 1) % options.length;
+                render();
+            }
+            else if (key.name === "return" || key.name === "enter") {
+                cleanup();
+                resolve(optionAt(options, cursor).value);
+            }
+        };
+        stdin.on("keypress", onKey);
+        render();
+    });
+}
+/** Yes/no confirmation. Returns `defaultValue` on empty input. */
+export async function confirm(input) {
+    const def = input.defaultValue ?? false;
+    const hint = def ? "[Y/n]" : "[y/N]";
+    const answer = (await readLine(`${bold(input.message)} ${dim(hint)} `)).toLowerCase();
+    if (answer.length === 0)
+        return def;
+    return answer === "y" || answer === "yes";
+}
+/** Free-text prompt. Returns `defaultValue` (or "") on empty input. */
+export async function text(input) {
+    const suffix = input.defaultValue !== undefined && input.defaultValue.length > 0 ? dim(` (${input.defaultValue})`) : "";
+    const answer = await readLine(`${bold(input.message)}${suffix} `);
+    if (answer.length === 0)
+        return input.defaultValue ?? "";
+    return answer;
+}
+/** A success line for the end of a wizard. */
+export function done(message) {
+    out.write(`${green(glyph.tick())} ${message}\n`);
+}
+/** A neutral note line. */
+export function note(message) {
+    out.write(`${gray(glyph.arrow())} ${message}\n`);
+}

package/dist/ui/runtime.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Interaction-mode detection. The CLI's rich surfaces (spinners, live step
+ * lists, prompts) only render when we are attached to an interactive terminal
+ * and not running under CI; otherwise everything degrades to plain line logs so
+ * pipes, captures, and `node --test` stay deterministic.
+ */
+/** True under a recognized CI environment. */
+export declare function isCI(): boolean;
+/** The stream all UI is written to (stderr; stdout is reserved for tool output). */
+export declare function uiStream(): NodeJS.WriteStream;
+/** True when we should render rich, animated UI to `stream`. */
+export declare function isInteractive(stream?: NodeJS.WriteStream): boolean;
+/** True when we can read interactive keypresses (raw mode) from stdin. */
+export declare function canPromptInteractively(): boolean;

package/dist/ui/runtime.js

@@ -0,0 +1,33 @@
+/**
+ * Interaction-mode detection. The CLI's rich surfaces (spinners, live step
+ * lists, prompts) only render when we are attached to an interactive terminal
+ * and not running under CI; otherwise everything degrades to plain line logs so
+ * pipes, captures, and `node --test` stay deterministic.
+ */
+/** True under a recognized CI environment. */
+export function isCI() {
+    const env = process.env;
+    return Boolean(env.CI === "true" ||
+        env.CI === "1" ||
+        env.CONTINUOUS_INTEGRATION ||
+        env.GITHUB_ACTIONS ||
+        env.GITLAB_CI ||
+        env.BUILDKITE ||
+        env.CIRCLECI);
+}
+/** The stream all UI is written to (stderr; stdout is reserved for tool output). */
+export function uiStream() {
+    return process.stderr;
+}
+/** True when we should render rich, animated UI to `stream`. */
+export function isInteractive(stream = uiStream()) {
+    if (process.env.FUSIONKIT_NO_TUI === "1")
+        return false;
+    if (isCI())
+        return false;
+    return Boolean(stream.isTTY);
+}
+/** True when we can read interactive keypresses (raw mode) from stdin. */
+export function canPromptInteractively() {
+    return Boolean(process.stdin.isTTY) && !isCI() && process.env.FUSIONKIT_NO_TUI !== "1";
+}

package/dist/ui/spinner.d.ts

@@ -0,0 +1,31 @@
+/**
+ * A single-line spinner. On an interactive TTY it animates in place; otherwise
+ * it prints one line per state transition so logs stay readable and ordered.
+ */
+export declare class Spinner {
+    private timer;
+    private frame;
+    private text;
+    private readonly stream;
+    private readonly interactive;
+    private active;
+    constructor(text: string);
+    start(): this;
+    update(text: string): this;
+    succeed(text?: string): void;
+    fail(text?: string): void;
+    warn(text?: string): void;
+    info(text?: string): void;
+    stop(): void;
+    private settle;
+    private render;
+    private teardown;
+    private clearLine;
+    private hideCursor;
+    private showCursor;
+}
+/** Run `work` under a spinner, settling to success/failure automatically. */
+export declare function withSpinner<T>(text: string, work: () => Promise<T>, options?: {
+    success?: (value: T) => string;
+    failure?: (error: unknown) => string;
+}): Promise<T>;

package/dist/ui/spinner.js

@@ -0,0 +1,102 @@
+import { isInteractive, uiStream } from "./runtime.js";
+import { SPINNER_FRAMES, cyan, dim, glyph, gray, green, red, yellow } from "./theme.js";
+/**
+ * A single-line spinner. On an interactive TTY it animates in place; otherwise
+ * it prints one line per state transition so logs stay readable and ordered.
+ */
+export class Spinner {
+    timer;
+    frame = 0;
+    text;
+    stream = uiStream();
+    interactive = isInteractive();
+    active = false;
+    constructor(text) {
+        this.text = text;
+    }
+    start() {
+        if (this.active)
+            return this;
+        this.active = true;
+        if (!this.interactive) {
+            this.stream.write(`${dim(glyph.arrow())} ${this.text}\n`);
+            return this;
+        }
+        this.hideCursor();
+        this.render();
+        this.timer = setInterval(() => {
+            this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+            this.render();
+        }, 80);
+        this.timer.unref();
+        return this;
+    }
+    update(text) {
+        this.text = text;
+        if (this.active && this.interactive)
+            this.render();
+        else if (this.active)
+            this.stream.write(`${dim(glyph.arrow())} ${this.text}\n`);
+        return this;
+    }
+    succeed(text) {
+        this.settle(green(glyph.tick()), text ?? this.text);
+    }
+    fail(text) {
+        this.settle(red(glyph.cross()), text ?? this.text);
+    }
+    warn(text) {
+        this.settle(yellow(glyph.warn()), text ?? this.text);
+    }
+    info(text) {
+        this.settle(cyan(glyph.bullet()), text ?? this.text);
+    }
+    stop() {
+        this.teardown();
+    }
+    settle(symbol, text) {
+        this.teardown();
+        this.stream.write(`${symbol} ${text}\n`);
+    }
+    render() {
+        const symbol = cyan(SPINNER_FRAMES[this.frame] ?? "-");
+        this.clearLine();
+        this.stream.write(`${symbol} ${this.text}`);
+    }
+    teardown() {
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.active && this.interactive) {
+            this.clearLine();
+            this.showCursor();
+        }
+        this.active = false;
+    }
+    clearLine() {
+        if (this.interactive)
+            this.stream.write("\r\u001b[2K");
+    }
+    hideCursor() {
+        if (this.interactive)
+            this.stream.write("\u001b[?25l");
+    }
+    showCursor() {
+        if (this.interactive)
+            this.stream.write("\u001b[?25h");
+    }
+}
+/** Run `work` under a spinner, settling to success/failure automatically. */
+export async function withSpinner(text, work, options = {}) {
+    const spinner = new Spinner(text).start();
+    try {
+        const value = await work();
+        spinner.succeed(options.success ? options.success(value) : text);
+        return value;
+    }
+    catch (error) {
+        spinner.fail(options.failure ? options.failure(error) : `${text} ${gray("(failed)")}`);
+        throw error;
+    }
+}

package/dist/ui/steps.d.ts

@@ -0,0 +1,38 @@
+export type StepStatus = "pending" | "active" | "done" | "failed" | "skipped";
+export type StepInput = {
+    id: string;
+    label: string;
+};
+/**
+ * A live checklist of stages. On a TTY it re-renders in place with per-stage
+ * spinners and elapsed time; otherwise it prints one line per state transition
+ * so non-interactive logs stay ordered and readable.
+ */
+export declare class StepList {
+    private readonly steps;
+    private readonly stream;
+    private readonly interactive;
+    private readonly title;
+    private timer;
+    private frame;
+    private renderedLines;
+    private started;
+    constructor(steps: readonly StepInput[], options?: {
+        title?: string;
+    });
+    start(): this;
+    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;
+    /** Stop animation and leave the final frame in place. */
+    stop(): void;
+    private transition;
+    private printLine;
+    private render;
+    private clear;
+    private find;
+    private hideCursor;
+    private showCursor;
+}

package/dist/ui/steps.js

@@ -0,0 +1,149 @@
+import { isInteractive, uiStream } from "./runtime.js";
+import { SPINNER_FRAMES, cyan, dim, glyph, gray, green, red, yellow } from "./theme.js";
+function elapsedLabel(step) {
+    if (step.startedAt === undefined)
+        return "";
+    const end = step.endedAt ?? Date.now();
+    const seconds = (end - step.startedAt) / 1000;
+    if (seconds < 0.05)
+        return "";
+    return gray(` ${seconds.toFixed(1)}s`);
+}
+function symbolFor(step, frame) {
+    switch (step.status) {
+        case "pending":
+            return gray(glyph.pending());
+        case "active":
+            return cyan(SPINNER_FRAMES[frame] ?? "-");
+        case "done":
+            return green(glyph.tick());
+        case "failed":
+            return red(glyph.cross());
+        case "skipped":
+            return yellow(glyph.bullet());
+        default: {
+            const exhaustive = step.status;
+            throw new Error(`unknown step status: ${String(exhaustive)}`);
+        }
+    }
+}
+/**
+ * A live checklist of stages. On a TTY it re-renders in place with per-stage
+ * spinners and elapsed time; otherwise it prints one line per state transition
+ * so non-interactive logs stay ordered and readable.
+ */
+export class StepList {
+    steps;
+    stream = uiStream();
+    interactive = isInteractive();
+    title;
+    timer;
+    frame = 0;
+    renderedLines = 0;
+    started = false;
+    constructor(steps, options = {}) {
+        this.steps = steps.map((step) => ({ id: step.id, label: step.label, status: "pending" }));
+        this.title = options.title;
+    }
+    start() {
+        if (this.started)
+            return this;
+        this.started = true;
+        if (this.interactive) {
+            this.hideCursor();
+            this.render();
+            this.timer = setInterval(() => {
+                this.frame = (this.frame + 1) % SPINNER_FRAMES.length;
+                this.render();
+            }, 80);
+            this.timer.unref();
+        }
+        else if (this.title !== undefined) {
+            this.stream.write(`${this.title}\n`);
+        }
+        return this;
+    }
+    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.find(id);
+        step.detail = detail;
+        if (this.interactive)
+            this.render();
+    }
+    /** Stop animation and leave the final frame in place. */
+    stop() {
+        if (this.timer !== undefined) {
+            clearInterval(this.timer);
+            this.timer = undefined;
+        }
+        if (this.interactive && this.started) {
+            this.render();
+            this.showCursor();
+        }
+        this.started = false;
+    }
+    transition(id, status, detail) {
+        const step = this.find(id);
+        if (status === "active" && step.startedAt === undefined)
+            step.startedAt = Date.now();
+        if ((status === "done" || status === "failed" || status === "skipped") && step.endedAt === undefined) {
+            step.endedAt = Date.now();
+            if (step.startedAt === undefined)
+                step.startedAt = step.endedAt;
+        }
+        step.status = status;
+        if (detail !== undefined)
+            step.detail = detail;
+        if (this.interactive)
+            this.render();
+        else
+            this.printLine(step);
+    }
+    printLine(step) {
+        const detail = step.detail !== undefined ? ` ${dim(step.detail)}` : "";
+        this.stream.write(`${symbolFor(step, 0)} ${step.label}${detail}\n`);
+    }
+    render() {
+        const lines = [];
+        if (this.title !== undefined)
+            lines.push(this.title);
+        for (const step of this.steps) {
+            const detail = step.detail !== undefined ? ` ${dim(step.detail)}` : "";
+            lines.push(`${symbolFor(step, this.frame)} ${step.label}${detail}${elapsedLabel(step)}`);
+        }
+        this.clear();
+        this.stream.write(lines.join("\n") + "\n");
+        this.renderedLines = lines.length;
+    }
+    clear() {
+        if (!this.interactive || this.renderedLines === 0)
+            return;
+        this.stream.write(`\u001b[${this.renderedLines}A`);
+        this.stream.write("\u001b[0J");
+    }
+    find(id) {
+        const step = this.steps.find((candidate) => candidate.id === id);
+        if (step === undefined)
+            throw new Error(`unknown step id: ${id}`);
+        return step;
+    }
+    hideCursor() {
+        if (this.interactive)
+            this.stream.write("\u001b[?25l");
+    }
+    showCursor() {
+        if (this.interactive)
+            this.stream.write("\u001b[?25h");
+    }
+}

package/dist/ui/theme.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Zero-dependency terminal theming. All color/format helpers no-op when color
+ * is not supported (not a TTY, `NO_COLOR` set, or a dumb terminal), so output
+ * stays clean when piped or captured. UI is written to stderr by convention so
+ * the launched coding tool's stdout stays pristine.
+ */
+/** True when ANSI styling should be emitted to the given stream. */
+export declare function supportsColor(stream?: NodeJS.WriteStream): boolean;
+type Style = (text: string) => string;
+export declare const bold: Style;
+export declare const dim: Style;
+export declare const italic: Style;
+export declare const underline: Style;
+export declare const red: Style;
+export declare const green: Style;
+export declare const yellow: Style;
+export declare const blue: Style;
+export declare const magenta: Style;
+export declare const cyan: Style;
+export declare const gray: Style;
+/** Status glyphs, with ASCII fallbacks when color (≈ unicode-friendly TTY) is off. */
+export declare const glyph: {
+    tick: () => "✔" | "[ok]";
+    cross: () => "✖" | "[x]";
+    bullet: () => "•" | "*";
+    arrow: () => "›" | ">";
+    pointer: () => ">" | "❯";
+    warn: () => "⚠" | "[!]";
+    pending: () => "○" | "( )";
+};
+/** Frames for the in-place spinner (braille dots when color is on). */
+export declare const SPINNER_FRAMES: readonly string[];
+/** The product banner shown atop interactive surfaces. */
+export declare function brandHeader(subtitle?: string): string;
+export {};

package/dist/ui/theme.js

@@ -0,0 +1,52 @@
+/**
+ * Zero-dependency terminal theming. All color/format helpers no-op when color
+ * is not supported (not a TTY, `NO_COLOR` set, or a dumb terminal), so output
+ * stays clean when piped or captured. UI is written to stderr by convention so
+ * the launched coding tool's stdout stays pristine.
+ */
+/** True when ANSI styling should be emitted to the given stream. */
+export function supportsColor(stream = process.stderr) {
+    if (process.env.NO_COLOR !== undefined && process.env.NO_COLOR !== "")
+        return false;
+    if (process.env.FORCE_COLOR !== undefined && process.env.FORCE_COLOR !== "0")
+        return true;
+    if (process.env.TERM === "dumb")
+        return false;
+    return Boolean(stream.isTTY);
+}
+function wrap(open, close) {
+    return (text) => (supportsColor() ? `\u001b[${open}m${text}\u001b[${close}m` : text);
+}
+export const bold = wrap(1, 22);
+export const dim = wrap(2, 22);
+export const italic = wrap(3, 23);
+export const underline = wrap(4, 24);
+export const red = wrap(31, 39);
+export const green = wrap(32, 39);
+export const yellow = wrap(33, 39);
+export const blue = wrap(34, 39);
+export const magenta = wrap(35, 39);
+export const cyan = wrap(36, 39);
+export const gray = wrap(90, 39);
+/** Status glyphs, with ASCII fallbacks when color (≈ unicode-friendly TTY) is off. */
+export const glyph = {
+    tick: () => (supportsColor() ? "\u2714" : "[ok]"),
+    cross: () => (supportsColor() ? "\u2716" : "[x]"),
+    bullet: () => (supportsColor() ? "\u2022" : "*"),
+    arrow: () => (supportsColor() ? "\u203a" : ">"),
+    pointer: () => (supportsColor() ? "\u276f" : ">"),
+    warn: () => (supportsColor() ? "\u26a0" : "[!]"),
+    pending: () => (supportsColor() ? "\u25cb" : "( )")
+};
+/** Frames for the in-place spinner (braille dots when color is on). */
+export const SPINNER_FRAMES = supportsColorFrames();
+function supportsColorFrames() {
+    return ["\u280b", "\u2819", "\u2839", "\u2838", "\u283c", "\u2834", "\u2826", "\u2827", "\u2807", "\u280f"];
+}
+/** The product banner shown atop interactive surfaces. */
+export function brandHeader(subtitle) {
+    const title = bold(cyan("fusionkit"));
+    const tag = dim("real model fusion behind your coding agent");
+    const head = `${title}  ${tag}`;
+    return subtitle === undefined ? head : `${head}\n${dim(subtitle)}`;
+}