@velum-labs/routekit-cli-ui 0.9.0

package/dist/theme.d.ts

@@ -0,0 +1,82 @@
+/** True when ANSI styling should be emitted to the given stream. */
+export declare function supportsColor(stream?: NodeJS.WriteStream): boolean;
+/** True when Unicode glyphs (box-drawing, status icons) should be used. */
+export declare function supportsUnicode(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 on dumb terminals. */
+export declare const glyph: {
+    tick: () => "✔" | "[ok]";
+    cross: () => "✖" | "[x]";
+    bullet: () => "•" | "*";
+    arrow: () => "›" | ">";
+    pointer: () => ">" | "❯";
+    warn: () => "⚠" | "[!]";
+    pending: () => "○" | "( )";
+    checkboxOn: () => "[x]" | "◉";
+    checkboxOff: () => "◯" | "[ ]";
+};
+/** Frames for the in-place spinner (braille dots when Unicode is supported). */
+export declare const SPINNER_FRAMES: readonly string[];
+export type BrandOptions = {
+    name: string;
+    tagline: string;
+};
+/** Configure the product wordmark rendered by presenter banners. */
+export declare function configureBrand(options: BrandOptions): void;
+/** The compact one-line product header (used for sub-surfaces and fallbacks). */
+export declare function brandHeader(subtitle?: string): string;
+/** Remove ANSI styling so we can measure on-screen width. */
+export declare function stripAnsi(text: string): string;
+/** Visible (printed) width of a string, ignoring ANSI escapes. */
+export declare function visibleWidth(text: string): number;
+/**
+ * Greedy word-wrap that is safe for ANSI-styled text: visible width is
+ * measured without escapes, and styles that are open at a line break are
+ * closed at the end of the line and re-opened on the next, so every returned
+ * line renders standalone.
+ */
+export declare function wrapAnsi(text: string, width: number): string[];
+/** Frame tones: neutral (dim) for informational boxes, error (red) for failures. */
+export type BoxTone = "neutral" | "error";
+/**
+ * A titled, framed block rendered as plain strings. Rounded box-drawing
+ * characters when color (≈ a unicode TTY) is on, ASCII otherwise. Lines may
+ * contain ANSI styling; widths are measured against the visible text so the
+ * frame always aligns. The box never draws wider than the terminal — content
+ * lines that would overflow are word-wrapped (ANSI-safely) instead.
+ *
+ * Deliberately NOT Ink's `<Box borderStyle>`: Ink borders only exist inside a
+ * mounted live app, while these boxes are *transcript* output — written once
+ * to the stream and left in scrollback. They must render identically from the
+ * plain presenter (non-TTY, `--quiet`, CI), from the top-level error handler
+ * after any Ink app has unmounted, and inside string-snapshot tests, none of
+ * which can mount a React tree.
+ */
+export declare function box(title: string, lines: string[], options?: {
+    tone?: BoxTone;
+}): string;
+/**
+ * Apply a left-to-right truecolor gradient across each line of `text`. Returns
+ * the text unchanged when 24-bit color is unavailable (callers pick a fallback
+ * color). Spaces are left uncolored so the escape sequences stay minimal.
+ */
+export declare function gradient(text: string): string;
+/**
+ * The full-dress figlet wordmark + gradient + tagline, shown once per command
+ * as an entrance "moment". Degrades gracefully to the one-line {@link
+ * brandHeader} when color is off, the terminal is too narrow, or figlet is
+ * somehow unavailable — preserving clean output when piped or captured.
+ */
+export declare function brandBanner(subtitle?: string): string;
+export {};

package/dist/theme.js

@@ -0,0 +1,299 @@
+/**
+ * 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.
+ *
+ * `figlet` is used purely for the one-shot wordmark banner; everything else is
+ * plain ANSI shared by the Ink presenter and the plain-text fallback.
+ */
+import figlet from "figlet";
+import stringWidth from "string-width";
+/** 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);
+}
+/** True when Unicode glyphs (box-drawing, status icons) should be used. */
+export function supportsUnicode(stream = process.stderr) {
+    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 on dumb terminals. */
+export const glyph = {
+    tick: () => (supportsUnicode() ? "✔" : "[ok]"),
+    cross: () => (supportsUnicode() ? "✖" : "[x]"),
+    bullet: () => (supportsUnicode() ? "•" : "*"),
+    arrow: () => (supportsUnicode() ? "›" : ">"),
+    pointer: () => (supportsUnicode() ? "❯" : ">"),
+    warn: () => (supportsUnicode() ? "⚠" : "[!]"),
+    pending: () => (supportsUnicode() ? "○" : "( )"),
+    checkboxOn: () => (supportsUnicode() ? "◉" : "[x]"),
+    checkboxOff: () => (supportsUnicode() ? "◯" : "[ ]")
+};
+/** Frames for the in-place spinner (braille dots when Unicode is supported). */
+export const SPINNER_FRAMES = supportsUnicode()
+    ? ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"]
+    : ["|", "/", "-", "\\"];
+let brand = { name: "routekit", tagline: "shared routing infrastructure" };
+/** Configure the product wordmark rendered by presenter banners. */
+export function configureBrand(options) {
+    brand = { ...options };
+}
+/** The compact one-line product header (used for sub-surfaces and fallbacks). */
+export function brandHeader(subtitle) {
+    const title = bold(cyan(brand.name));
+    const tag = dim(brand.tagline);
+    const head = `${title}  ${tag}`;
+    return subtitle === undefined ? head : `${head}\n${dim(subtitle)}`;
+}
+const ANSI_PATTERN = /\u001b\[[0-9;]*m/g;
+/** Remove ANSI styling so we can measure on-screen width. */
+export function stripAnsi(text) {
+    return text.replace(ANSI_PATTERN, "");
+}
+/** Visible (printed) width of a string, ignoring ANSI escapes. */
+export function visibleWidth(text) {
+    return stringWidth(stripAnsi(text));
+}
+/** Track open SGR codes across a sequence boundary (theme styles only). */
+function applySgr(active, sequence) {
+    const body = sequence.slice(2, -1);
+    const drop = (codes) => {
+        for (let index = active.length - 1; index >= 0; index--) {
+            const code = active[index] ?? "";
+            if (codes.includes(code) || (codes.includes("38") && code.startsWith("38;")))
+                active.splice(index, 1);
+        }
+    };
+    if (body === "" || body === "0")
+        active.length = 0;
+    else if (body === "22")
+        drop(["1", "2"]);
+    else if (body === "23")
+        drop(["3"]);
+    else if (body === "24")
+        drop(["4"]);
+    else if (body === "39")
+        drop(["31", "32", "33", "34", "35", "36", "90", "38"]);
+    else
+        active.push(body);
+}
+/**
+ * Greedy word-wrap that is safe for ANSI-styled text: visible width is
+ * measured without escapes, and styles that are open at a line break are
+ * closed at the end of the line and re-opened on the next, so every returned
+ * line renders standalone.
+ */
+export function wrapAnsi(text, width) {
+    if (width <= 0)
+        return [text];
+    const lines = [];
+    for (const paragraph of text.split("\n")) {
+        if (visibleWidth(paragraph) <= width) {
+            lines.push(paragraph);
+            continue;
+        }
+        // Codes open at the current position; re-opened at each new line start.
+        const active = [];
+        let line = "";
+        let lineWidth = 0;
+        const endLine = () => {
+            lines.push(active.length > 0 ? `${line}\u001b[0m` : line);
+            line = active.map((code) => `\u001b[${code}m`).join("");
+            lineWidth = 0;
+        };
+        for (const word of paragraph.split(" ")) {
+            const wordWidth = visibleWidth(word);
+            if (lineWidth > 0) {
+                if (lineWidth + 1 + wordWidth <= width) {
+                    line += " ";
+                    lineWidth += 1;
+                }
+                else {
+                    endLine();
+                }
+            }
+            if (wordWidth <= width) {
+                for (const escape of word.match(ANSI_PATTERN) ?? [])
+                    applySgr(active, escape);
+                line += word;
+                lineWidth += wordWidth;
+                continue;
+            }
+            // A single word wider than the line (URL, long id): hard split.
+            let index = 0;
+            while (index < word.length) {
+                const escape = /^\u001b\[[0-9;]*m/.exec(word.slice(index));
+                if (escape !== null) {
+                    applySgr(active, escape[0]);
+                    line += escape[0];
+                    index += escape[0].length;
+                    continue;
+                }
+                if (lineWidth >= width)
+                    endLine();
+                line += word[index] ?? "";
+                lineWidth += 1;
+                index += 1;
+            }
+        }
+        if (stripAnsi(line).length > 0) {
+            lines.push(active.length > 0 ? `${line}\u001b[0m` : line);
+        }
+    }
+    return lines;
+}
+/** The widest a box may draw on the current terminal (frame included). */
+function maxBoxWidth(stream = process.stderr) {
+    const columns = stream.columns;
+    if (columns === undefined || columns <= 0)
+        return 84;
+    return Math.min(Math.max(columns, 24), 100);
+}
+const ROUNDED_BOX = {
+    topLeft: "╭",
+    topRight: "╮",
+    bottomLeft: "╰",
+    bottomRight: "╯",
+    horizontal: "─",
+    vertical: "│"
+};
+const ASCII_BOX = {
+    topLeft: "+",
+    topRight: "+",
+    bottomLeft: "+",
+    bottomRight: "+",
+    horizontal: "-",
+    vertical: "|"
+};
+/**
+ * A titled, framed block rendered as plain strings. Rounded box-drawing
+ * characters when color (≈ a unicode TTY) is on, ASCII otherwise. Lines may
+ * contain ANSI styling; widths are measured against the visible text so the
+ * frame always aligns. The box never draws wider than the terminal — content
+ * lines that would overflow are word-wrapped (ANSI-safely) instead.
+ *
+ * Deliberately NOT Ink's `<Box borderStyle>`: Ink borders only exist inside a
+ * mounted live app, while these boxes are *transcript* output — written once
+ * to the stream and left in scrollback. They must render identically from the
+ * plain presenter (non-TTY, `--quiet`, CI), from the top-level error handler
+ * after any Ink app has unmounted, and inside string-snapshot tests, none of
+ * which can mount a React tree.
+ */
+export function box(title, lines, options = {}) {
+    const chars = supportsUnicode() ? ROUNDED_BOX : ASCII_BOX;
+    const frame = options.tone === "error" ? red : dim;
+    const titleText = options.tone === "error" ? bold(red(title)) : bold(title);
+    // "│ " + content + " │" -> the frame consumes 4 columns.
+    const maxContent = maxBoxWidth() - 4;
+    const wrapped = lines.flatMap((line) => {
+        if (visibleWidth(line) <= maxContent)
+            return [line];
+        // Indent wrapped continuations so they read as part of the first line.
+        return wrapAnsi(line, maxContent - 2).map((part, index) => (index === 0 ? part : `  ${part}`));
+    });
+    const contentWidth = Math.min(Math.max(visibleWidth(titleText), ...wrapped.map(visibleWidth), 0), maxContent);
+    const inner = contentWidth + 2; // one space of padding each side
+    // Build with un-nested styles: color the frame pieces, bold only the title,
+    // so a bold reset (SGR 22) never prematurely closes a surrounding style.
+    const titleRule = chars.horizontal.repeat(Math.max(0, inner - visibleWidth(titleText) - 3));
+    const top = `${frame(`${chars.topLeft}${chars.horizontal} `)}${titleText}${frame(` ${titleRule}${chars.topRight}`)}`;
+    const body = wrapped.map((line) => {
+        const pad = " ".repeat(Math.max(0, contentWidth - visibleWidth(line)));
+        return `${frame(chars.vertical)} ${line}${pad} ${frame(chars.vertical)}`;
+    });
+    const bottom = frame(`${chars.bottomLeft}${chars.horizontal.repeat(inner)}${chars.bottomRight}`);
+    return [top, ...body, bottom].join("\n");
+}
+/** True when the terminal advertises 24-bit color (needed for the gradient). */
+function supportsTrueColor() {
+    if (!supportsColor())
+        return false;
+    const colorterm = process.env.COLORTERM ?? "";
+    return colorterm.includes("truecolor") || colorterm.includes("24bit");
+}
+/** Gradient endpoints: cyan-400 -> fuchsia-500, for the "magical" wordmark. */
+const GRADIENT_FROM = [34, 211, 238];
+const GRADIENT_TO = [217, 70, 239];
+function mix(from, to, t) {
+    return Math.round(from + (to - from) * t);
+}
+/**
+ * Apply a left-to-right truecolor gradient across each line of `text`. Returns
+ * the text unchanged when 24-bit color is unavailable (callers pick a fallback
+ * color). Spaces are left uncolored so the escape sequences stay minimal.
+ */
+export function gradient(text) {
+    if (!supportsTrueColor())
+        return text;
+    const lines = text.split("\n");
+    const width = Math.max(1, ...lines.map((line) => line.length));
+    return lines
+        .map((line) => {
+        let out = "";
+        for (let i = 0; i < line.length; i++) {
+            const ch = line[i] ?? "";
+            if (ch === " ") {
+                out += ch;
+                continue;
+            }
+            const t = width <= 1 ? 0 : i / (width - 1);
+            const r = mix(GRADIENT_FROM[0], GRADIENT_TO[0], t);
+            const g = mix(GRADIENT_FROM[1], GRADIENT_TO[1], t);
+            const b = mix(GRADIENT_FROM[2], GRADIENT_TO[2], t);
+            out += `\u001b[38;2;${r};${g};${b}m${ch}`;
+        }
+        return out + "\u001b[39m";
+    })
+        .join("\n");
+}
+/**
+ * The full-dress figlet wordmark + gradient + tagline, shown once per command
+ * as an entrance "moment". Degrades gracefully to the one-line {@link
+ * brandHeader} when color is off, the terminal is too narrow, or figlet is
+ * somehow unavailable — preserving clean output when piped or captured.
+ */
+export function brandBanner(subtitle) {
+    const fallback = brandHeader(subtitle);
+    if (!supportsColor())
+        return fallback;
+    let art;
+    try {
+        art = figlet.textSync(brand.name, { font: "ANSI Shadow" });
+    }
+    catch {
+        return fallback;
+    }
+    // Drop trailing blank lines figlet pads with, keep the shape otherwise.
+    const lines = art.replace(/[\s\n]+$/u, "").split("\n");
+    const widest = Math.max(0, ...lines.map((line) => line.length));
+    const columns = process.stderr.columns;
+    if (columns !== undefined && widest > columns)
+        return fallback;
+    const trimmed = lines.join("\n");
+    const wordmark = supportsTrueColor() ? gradient(trimmed) : bold(cyan(trimmed));
+    const tag = dim(brand.tagline);
+    const sub = subtitle !== undefined ? `\n${dim(subtitle)}` : "";
+    return `${wordmark}\n${tag}${sub}`;
+}

package/dist/wizard.d.ts

@@ -0,0 +1,13 @@
+import type { Back } from "./prompt.js";
+export type WizardStep<S> = {
+    id: string;
+    title: string;
+    /** Run the step: return the next state, or BACK to go back one step. */
+    run: (state: S) => Promise<S | Back>;
+    /** When true for the current state the step is skipped (both directions). */
+    skip?: (state: S) => boolean;
+};
+export declare function runWizard<S>(input: {
+    steps: ReadonlyArray<WizardStep<S>>;
+    initial: S;
+}): Promise<S>;

package/dist/wizard.js

@@ -0,0 +1,54 @@
+/**
+ * A tiny wizard runner: ordered steps over a shared state object, with Esc
+ * back-navigation (steps receive prompts created with `allowBack: true` and
+ * return {@link BACK} to go back one step). Each step prints a dim
+ * `step N/M · title` header so a finished wizard reads as a transcript of the
+ * journey; skipped steps disappear from the count.
+ */
+import { BACK } from "./prompt.js";
+import { isInteractive, uiStream } from "./runtime.js";
+import { dim } from "./theme.js";
+export async function runWizard(input) {
+    const out = uiStream();
+    let state = input.initial;
+    // Snapshots of the state as it was when each step started, so going back
+    // replays from exactly where that step began.
+    const snapshots = [];
+    let index = 0;
+    while (index < input.steps.length) {
+        const step = input.steps[index];
+        if (step === undefined)
+            break;
+        if (step.skip !== undefined && step.skip(state)) {
+            snapshots[index] = state;
+            index += 1;
+            continue;
+        }
+        const active = input.steps.filter((candidate) => candidate.skip === undefined || !candidate.skip(state));
+        const position = active.indexOf(step);
+        if (position >= 0 && active.length > 1 && isInteractive()) {
+            out.write(`${dim(`step ${position + 1}/${active.length} · ${step.title} ${position > 0 ? "(esc goes back)" : ""}`.trimEnd())}\n`);
+        }
+        snapshots[index] = state;
+        const result = await step.run(state);
+        if (result === BACK) {
+            // Walk back past skipped steps; stay on the first step when already there.
+            let previous = index - 1;
+            while (previous >= 0) {
+                const candidate = input.steps[previous];
+                const snapshot = snapshots[previous];
+                if (candidate !== undefined && snapshot !== undefined && (candidate.skip === undefined || !candidate.skip(snapshot)))
+                    break;
+                previous -= 1;
+            }
+            if (previous >= 0) {
+                index = previous;
+                state = snapshots[previous];
+            }
+            continue;
+        }
+        state = result;
+        index += 1;
+    }
+    return state;
+}

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "@velum-labs/routekit-cli-ui",
+  "private": false,
+  "version": "0.9.0",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/velum-labs/handoffkit.git",
+    "directory": "packages/cli-ui"
+  },
+  "description": "Brand-configurable terminal UX: an Ink presenter, prompt facade, and plain-text fallback.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org",
+    "access": "public",
+    "provenance": true
+  },
+  "dependencies": {
+    "figlet": "1.11.0",
+    "ink": "7.1.0",
+    "react": "19.2.7",
+    "string-width": "8.2.1"
+  },
+  "devDependencies": {
+    "@types/figlet": "1.7.0",
+    "@types/react": "19.2.17",
+    "ink-testing-library": "4.0.0"
+  },
+  "keywords": [
+    "routekit",
+    "terminal-ui",
+    "ink",
+    "prompts"
+  ],
+  "scripts": {
+    "build": "tsc -b",
+    "clean": "tsc -b --clean",
+    "test": "node --test \"dist/test/*.test.js\""
+  }
+}