@datename/fastcode-termux 0.0.0-stage → 0.1.6-beta

package/src/skills/manager.ts

@@ -0,0 +1,201 @@
+/**
+ * Skill manager.
+ *
+ * Skills follow Anthropic's "Agent Skills" convention: a folder containing
+ * a SKILL.md file plus optional resource files. FastCode supports three
+ * install sources:
+ *
+ *   1. skills.sh / skillshub.wtf API (default registry)
+ *      `/skills install pdf`               → resolves via the registry
+ *      `/skills install owner/repo/skill`  → fetches raw SKILL.md
+ *   2. Direct https URLs ending in SKILL.md.
+ *   3. Local paths (just symlinks into ~/.fastcode/skills/).
+ *
+ * Installed skills can be enabled per-session and are then stitched into
+ * the system prompt at chat time, exactly like Claude does internally.
+ */
+import { readFileSync, writeFileSync, existsSync, readdirSync, rmSync, mkdirSync, } from "node:fs";
+import { join } from "node:path";
+import { getPaths } from "../config/paths.js";
+import { fetchJson } from "../lib/http.js";
+import { parseSkill } from "./parser.js";
+const DEFAULT_REGISTRY = "https://skillshub.wtf";
+/** List skills currently installed under ~/.fastcode/skills. */
+export function listInstalledSkills() {
+    const { skills } = getPaths();
+    if (!existsSync(skills))
+        return [];
+    const out = [];
+    for (const dir of readdirSync(skills, { withFileTypes: true })) {
+        if (!dir.isDirectory())
+            continue;
+        const folder = join(skills, dir.name);
+        const md = join(folder, "SKILL.md");
+        if (!existsSync(md))
+            continue;
+        const raw = readFileSync(md, "utf8");
+        const parsed = parseSkill(raw, dir.name);
+        const sourcePath = join(folder, ".fastcode-source");
+        const source = existsSync(sourcePath)
+            ? readFileSync(sourcePath, "utf8").trim()
+            : "local";
+        out.push({
+            name: parsed.name || dir.name,
+            description: parsed.description,
+            source,
+            path: folder,
+            body: parsed.body,
+        });
+    }
+    return out.sort((a, b) => a.name.localeCompare(b.name));
+}
+/** Look up a skill by name (matches folder name OR frontmatter name). */
+export function getSkill(name) {
+    return listInstalledSkills().find((s) => s.name === name || basename(s.path) === name);
+}
+/** Install a skill. Returns the parsed manifest on success. */
+export async function installSkill(spec, opts: any = {}) {
+    const { skills } = getPaths();
+    const registry = (opts.registry ?? DEFAULT_REGISTRY).replace(/\/+$/, "");
+    let parsed;
+    let source;
+    let folderName;
+    if (spec.startsWith("http://") || spec.startsWith("https://")) {
+        const body = await fetchText(spec);
+        parsed = parseSkill(body, slugify(spec));
+        source = spec;
+        folderName = slugify(parsed.name || slugify(spec));
+    }
+    else if (looksLikeRepoPath(spec)) {
+        // owner/repo or owner/repo/skill — fetch via registry's raw endpoint.
+        const url = `${registry}/${spec}?format=md`;
+        const body = await fetchText(url);
+        parsed = parseSkill(body, parts(spec).pop() ?? spec);
+        source = url;
+        folderName = slugify(parsed.name || parts(spec).pop() || spec);
+    }
+    else {
+        // Single-token name → search the registry.
+        const hits = await searchRegistry(spec, registry);
+        const hit = hits[0];
+        if (!hit)
+            throw new Error(`No skill found for "${spec}" in ${registry}`);
+        const url = hit.fetchUrl ?? `${registry}/${hit.slug}?format=md`;
+        const body = await fetchText(url);
+        parsed = parseSkill(body, hit.name);
+        source = url;
+        folderName = slugify(parsed.name || hit.name);
+    }
+    const targetDir = join(skills, folderName);
+    if (existsSync(targetDir) && !opts.force) {
+        throw new Error(`Skill "${folderName}" is already installed. Use --force to overwrite.`);
+    }
+    if (existsSync(targetDir))
+        rmSync(targetDir, { recursive: true, force: true });
+    mkdirSync(targetDir, { recursive: true });
+    writeFileSync(join(targetDir, "SKILL.md"), reassemble(parsed));
+    writeFileSync(join(targetDir, ".fastcode-source"), source);
+    return {
+        name: parsed.name || folderName,
+        description: parsed.description,
+        source,
+        path: targetDir,
+        body: parsed.body,
+    };
+}
+/** Remove an installed skill by name or folder. */
+export function uninstallSkill(name) {
+    const { skills } = getPaths();
+    const candidates = readdirSync(skills, { withFileTypes: true });
+    for (const dir of candidates) {
+        if (!dir.isDirectory())
+            continue;
+        if (dir.name !== name) {
+            // Also match by frontmatter name.
+            const md = join(skills, dir.name, "SKILL.md");
+            if (!existsSync(md))
+                continue;
+            const parsed = parseSkill(readFileSync(md, "utf8"), dir.name);
+            if (parsed.name !== name)
+                continue;
+        }
+        rmSync(join(skills, dir.name), { recursive: true, force: true });
+        return true;
+    }
+    return false;
+}
+/** Search the registry for skills matching a query. */
+export async function searchRegistry(query, registry = DEFAULT_REGISTRY) {
+    const base = registry.replace(/\/+$/, "");
+    try {
+        const json = await fetchJson(`${base}/api/v1/skills/search?q=${encodeURIComponent(query)}`);
+        return json.data ?? [];
+    }
+    catch {
+        return [];
+    }
+}
+/** Compose the system-prompt addendum for a list of enabled skill names. */
+export function buildSkillsPrompt(enabled) {
+    if (enabled.length === 0)
+        return "";
+    const installed = listInstalledSkills();
+    const chunks = [];
+    for (const name of enabled) {
+        const skill = installed.find((s) => s.name === name || basename(s.path) === name);
+        if (!skill)
+            continue;
+        chunks.push(`<skill name="${skill.name}">\n${skill.body.trim()}\n</skill>`);
+    }
+    if (chunks.length === 0)
+        return "";
+    return [
+        "",
+        "## Active skills",
+        "The following skills are loaded for this session. Follow their instructions when relevant:",
+        "",
+        chunks.join("\n\n"),
+    ].join("\n");
+}
+// ---------- helpers ----------
+async function fetchText(url) {
+    const res = await fetch(url);
+    if (!res.ok)
+        throw new Error(`Fetch ${url} failed: ${res.status} ${res.statusText}`);
+    return await res.text();
+}
+function reassemble(parsed) {
+    const fmEntries = Object.entries(parsed.frontmatter);
+    if (fmEntries.length === 0 && parsed.name && parsed.description) {
+        return [
+            "---",
+            `name: ${parsed.name}`,
+            `description: ${parsed.description}`,
+            "---",
+            "",
+            parsed.body.trim(),
+            "",
+        ].join("\n");
+    }
+    if (fmEntries.length === 0)
+        return parsed.body;
+    const fmLines = fmEntries.map(([k, v]) => `${k}: ${v}`);
+    return ["---", ...fmLines, "---", "", parsed.body.trim(), ""].join("\n");
+}
+function slugify(s) {
+    return s
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, "-")
+        .replace(/^-+|-+$/g, "")
+        .slice(0, 64) || "skill";
+}
+function looksLikeRepoPath(spec) {
+    return /^[\w-]+\/[\w.-]+(\/[\w.-]+)?$/.test(spec) && !spec.startsWith("/");
+}
+function parts(spec) {
+    return spec.split("/").filter(Boolean);
+}
+function basename(p) {
+    const i = Math.max(p.lastIndexOf("/"), p.lastIndexOf("\\"));
+    return i === -1 ? p : p.slice(i + 1);
+}

package/src/skills/parser.ts

@@ -0,0 +1,65 @@
+/**
+ * SKILL.md parser. Skills follow Anthropic's Agent Skills convention:
+ *
+ *   ---
+ *   name: my-skill
+ *   description: ...
+ *   ---
+ *   <markdown body>
+ *
+ * We accept both `---` and `+++` fences and tolerate missing frontmatter
+ * (treating the first H1 + paragraph as a fallback name/description).
+ */
+export function parseSkill(source, fallbackName) {
+    const fmMatch = source.match(/^(?:---|\+\+\+)\s*\n([\s\S]*?)\n(?:---|\+\+\+)\s*\n?/);
+    let frontmatter = {};
+    let body = source;
+    if (fmMatch) {
+        frontmatter = parseFrontmatter(fmMatch[1] ?? "");
+        body = source.slice(fmMatch[0].length).trimStart();
+    }
+    const name = (frontmatter["name"] ?? fallbackName).trim();
+    const description = (frontmatter["description"] ??
+        extractFirstParagraph(body) ??
+        "").trim();
+    return { name, description, body, frontmatter };
+}
+function parseFrontmatter(yaml) {
+    // Tiny YAML-ish parser: only handles `key: value` lines, which is what
+    // SKILL.md frontmatter uses in practice. This avoids pulling in a YAML lib.
+    const out = {};
+    for (const lineRaw of yaml.split("\n")) {
+        const line = lineRaw.trim();
+        if (!line || line.startsWith("#"))
+            continue;
+        const colon = line.indexOf(":");
+        if (colon === -1)
+            continue;
+        const key = line.slice(0, colon).trim();
+        let value = line.slice(colon + 1).trim();
+        if ((value.startsWith("\"") && value.endsWith("\"")) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        out[key] = value;
+    }
+    return out;
+}
+function extractFirstParagraph(body) {
+    const lines = body.split("\n");
+    let buf = [];
+    for (const line of lines) {
+        if (line.startsWith("#")) {
+            if (buf.length)
+                break;
+            continue;
+        }
+        if (!line.trim()) {
+            if (buf.length)
+                break;
+            continue;
+        }
+        buf.push(line.trim());
+    }
+    return buf.length ? buf.join(" ") : undefined;
+}

package/src/types.ts

@@ -0,0 +1,205 @@
+/**
+ * Shared types used across FastCode.
+ *
+ * The provider abstraction is intentionally narrow — it only exposes
+ * what the chat loop needs (streaming completions, model list, auth).
+ * Providers can layer richer behavior on top in their own modules.
+ */
+export type Role = "system" | "user" | "assistant" | "tool";
+export type ReasoningEffort = "auto" | "low" | "medium" | "high" | "max";
+
+export interface NativeToolCall {
+    id: string;
+    name: string;
+    arguments: string;
+}
+
+export interface ToolSchema {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: Record<string, any>;
+    };
+}
+
+export interface ChatMessage {
+    role: Role;
+    content: string;
+    toolCalls?: NativeToolCall[];
+    toolCallId?: string;
+}
+export interface ChatRequest {
+    model: string;
+    messages: ChatMessage[];
+    /** Optional system prompt. Some providers fold this into messages. */
+    system?: string;
+    /** Sampling temperature. */
+    temperature?: number;
+    /** Soft cap for output tokens. */
+    maxOutputTokens?: number;
+    /**
+     * Requested thinking depth. Providers that support it map this to their
+     * native parameter (`reasoning_effort`, `thinking.budget_tokens`, …);
+     * providers that don't should ignore it.
+     */
+    reasoningEffort?: ReasoningEffort;
+    /** AbortSignal for cancellation (Esc / Ctrl+C). */
+    signal?: AbortSignal;
+    /** Stable idempotency key reused across retries of the same logical request. */
+    clientRequestId?: string;
+    /** Native function-calling schemas (auto mode only). */
+    tools?: ToolSchema[];
+}
+export interface ChatChunk {
+    /** Token text appended to the response. */
+    delta: string;
+    /** True on the final chunk. */
+    done: boolean;
+    /** Complete native tool calls (OpenAI-style) on the final chunk. */
+    toolCalls?: NativeToolCall[];
+    /** Provider-specific usage info on the final chunk. */
+    usage?: {
+        inputTokens?: number;
+        outputTokens?: number;
+        totalTokens?: number;
+        /** Approximate cost in USD if known. */
+        costUsd?: number;
+    };
+}
+export type ChatStream = AsyncIterable<ChatChunk>;
+export interface ProviderModel {
+    id: string;
+    label?: string;
+    /** Optional context window in tokens. */
+    contextWindow?: number;
+    /** Pricing per 1M tokens, used for cost estimation. */
+    pricing?: {
+        inputUsdPerM?: number;
+        outputUsdPerM?: number;
+    };
+}
+export interface Provider {
+    /** Unique id, e.g. "anthropic". */
+    id: string;
+    /** Human label. */
+    label: string;
+    /** ENV var(s) that, when set, satisfy auth. */
+    authEnv: string[];
+    /** Base URL — many providers expose OpenAI-compatible endpoints. */
+    baseUrl: string;
+    /** Default model id when the user hasn't picked one. */
+    defaultModel: string;
+    /** Static or dynamic list of supported models. */
+    listModels(apiKey: string | undefined): Promise<ProviderModel[]>;
+    /** Stream a chat completion. */
+    stream(req: ChatRequest, apiKey: string | undefined): ChatStream;
+    /** Whether this provider/model honors ChatRequest.reasoningEffort. */
+    supportsReasoning?(model: string): boolean;
+}
+export interface PickerItem {
+    value: string;
+    label: string;
+    hint?: string;
+}
+/**
+ * An interactive list a command can hand back to the app. The app renders it
+ * with arrow keys, number shortcuts, and Enter (Esc cancels).
+ */
+export interface PickerRequest {
+    title: string;
+    items: PickerItem[];
+    /** Currently selected value, highlighted on open. */
+    current?: string;
+    onSelect(value: string, item: PickerItem): void;
+    onCancel?(): void;
+}
+export interface SlashCommand {
+    name: string;
+    description: string;
+    /** Optional aliases users can also type. */
+    aliases?: string[];
+    /** Hide from /help (useful for power-user commands). */
+    hidden?: boolean;
+    /** Execute the command. Return text to render, or undefined for no output. */
+    run(ctx: CommandContext): Promise<CommandResult> | CommandResult;
+}
+export interface CommandResult {
+    /** Text rendered as a system message in the transcript. */
+    message?: string;
+    /** Mark this turn as silent (no echo of the slash itself). */
+    silent?: boolean;
+    /** Quit the app after this command. */
+    quit?: boolean;
+    /** Open an interactive picker after the command runs. */
+    picker?: PickerRequest;
+}
+export interface CommandContext {
+    args: string[];
+    raw: string;
+    state: AppStateSnapshot;
+    actions: AppActions;
+}
+export interface AppStateSnapshot {
+    providerId: string;
+    model: string;
+    theme: string;
+    agentMode: boolean;
+    history: ChatMessage[];
+    systemPrompt: string;
+    totalCostUsd: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    enabledSkills: string[];
+    enabledPlugins: string[];
+    skillsRegistry: string;
+    reasoningEffort: ReasoningEffort;
+    expanded: boolean;
+    busy: boolean;
+    draft: string;
+}
+export interface AppActions {
+    setProvider(id: string): void;
+    setModel(id: string): void;
+    setTheme(id: string): void;
+    setAgentMode(enabled: boolean): void;
+    setSystemPrompt(prompt: string): void;
+    setSkillsRegistry(url: string): void;
+    setReasoningEffort(effort: ReasoningEffort): void;
+    enableSkill(name: string): void;
+    disableSkill(name: string): void;
+    enablePlugin(name: string): void;
+    disablePlugin(name: string): void;
+    clearHistory(): void;
+    replaceHistory(messages: ChatMessage[]): void;
+    cancelRun(): void;
+    steer(text: string): void;
+    setExpanded(value: boolean): void;
+    setInput(text: string): void;
+    pushSystemMessage(text: string): void;
+    /** Begin the guided API-key flow (choose provider → model → key). */
+    startLogin(options: { provider?: string; model?: string }): void;
+}
+export interface SkillManifest {
+    name: string;
+    description: string;
+    /** Where the skill came from (e.g. "skills.sh", "anthropics/skills"). */
+    source: string;
+    /** Local on-disk path to the skill folder. */
+    path: string;
+    /** Raw SKILL.md body (the prompt content). */
+    body: string;
+}
+export interface Theme {
+    id: string;
+    label: string;
+    banner: [string, string, string];
+    user: string;
+    assistant: string;
+    system: string;
+    border: string;
+    accent: string;
+    muted: string;
+    error: string;
+    success: string;
+}

package/src/ui/Banner.ts

@@ -0,0 +1,68 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Animated FastCode banner shown at startup.
+ *
+ * We render the wordmark with ink-big-text + a gradient that slowly cycles
+ * through the theme's banner triple. The animation runs for ~1s and then
+ * settles on a stable gradient so we don't waste GPU cycles forever.
+ *
+ * The font is chosen to fit the terminal: `block` needs ~74 columns, so on a
+ * narrow phone terminal we fall back to progressively smaller fonts (see
+ * BANNER_FONTS). If even the smallest font is wider than the terminal, the
+ * banner is skipped entirely.
+ */
+import { useEffect, useState } from "react";
+import { Box, Text, useStdout } from "ink";
+import BigText from "ink-big-text";
+import Gradient from "ink-gradient";
+const FRAMES = 16;
+
+// (font, columns) needed to render the literal text "FastCode" with
+// letterSpacing 1 and space:false. Measured with cfonts; largest first.
+const BANNER_FONTS = [
+    { font: "block", columns: 74 },
+    { font: "simple", columns: 56 },
+    { font: "slick", columns: 49 },
+    { font: "shade", columns: 39 },
+    { font: "chrome", columns: 32 },
+    { font: "console", columns: 16 },
+];
+
+/** Pick the largest font that fits `columns` (2 columns reserved for padding). */
+function pickBannerFont(columns: number): string | null {
+    const usable = columns - 2;
+    for (const entry of BANNER_FONTS) {
+        if (entry.columns <= usable)
+            return entry.font;
+    }
+    return null;
+}
+
+export const Banner = ({ theme, subtitle, stable = false }) => {
+    const [frame, setFrame] = useState(0);
+    const { stdout } = useStdout();
+    const columns = stdout?.columns ?? process.stdout.columns ?? 80;
+    const font = pickBannerFont(columns);
+    useEffect(() => {
+        if (stable)
+            return;
+        if (frame >= FRAMES)
+            return;
+        const t = setTimeout(() => setFrame((f) => f + 1), 60);
+        return () => clearTimeout(t);
+    }, [frame, stable]);
+    if (!font)
+        return null;
+    const t = stable ? 1 : Math.min(1, frame / FRAMES);
+    const colors = rotate(theme.banner, t);
+    return (_jsxs(Box, { flexDirection: "column", alignItems: "flex-start", marginBottom: 1, children: [_jsx(Gradient, { colors: colors, children: _jsx(BigText, { text: "FastCode", font: font, space: false }) }), _jsx(Text, { color: theme.muted, children: subtitle ?? "multi-LLM TUI · skills.sh · slash commands · /help to start" })] }));
+};
+/** Cycle the gradient stops by `t ∈ [0,1]` for a subtle shimmer effect. */
+function rotate(stops, t) {
+    const [a, b, c] = stops;
+    if (t < 0.33)
+        return [a, b, c];
+    if (t < 0.66)
+        return [b, c, a];
+    return [c, a, b];
+}

package/src/ui/Message.ts

@@ -0,0 +1,24 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "ink";
+import { renderMarkdown } from "../lib/markdown.js";
+const SIGIL = {
+    user: "▎ you",
+    assistant: "▍ FastCode",
+    system: "✦ system",
+};
+const markdownCache = new Map();
+function cachedMarkdown(md) {
+    const hit = markdownCache.get(md);
+    if (hit !== undefined)
+        return hit;
+    const rendered = renderMarkdown(md);
+    if (markdownCache.size > 200)
+        markdownCache.clear();
+    markdownCache.set(md, rendered);
+    return rendered;
+}
+export const MessageBubble = ({ theme, role, content, streaming, markdown }: any) => {
+    const color = role === "user" ? theme.user : role === "assistant" ? theme.assistant : theme.system;
+    const display = markdown ? cachedMarkdown(content) : content;
+    return (_jsxs(Box, { flexDirection: "column", marginY: 0, children: [_jsxs(Text, { color: color, bold: true, children: [SIGIL[role], streaming ? _jsx(Text, { color: theme.muted, children: "  (streaming)" }) : null] }), _jsx(Box, { marginLeft: 2, flexDirection: "column", children: _jsx(Text, { color: color, children: display || (streaming ? "…" : "") }) })] }));
+};

package/src/ui/Picker.ts

@@ -0,0 +1,24 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Presentational picker used by /model, /provider, and /effort.
+ *
+ * Keyboard handling lives in App so it can suspend the normal prompt input and
+ * so every picker behaves the same. This component only renders the window of
+ * items around the active index.
+ */
+import { Box, Text } from "ink";
+const WINDOW = 10;
+export const Picker = ({ theme, title, items, index, current, hint }) => {
+    const max = Math.max(0, items.length - 1);
+    const active = Math.max(0, Math.min(index, max));
+    const start = Math.max(0, Math.min(active - Math.floor(WINDOW / 2), Math.max(0, items.length - WINDOW)));
+    const visible = items.slice(start, start + WINDOW);
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: theme.accent, paddingX: 1, children: [_jsx(Text, { color: theme.accent, bold: true, children: title }), ...visible.map((item, offset) => {
+                const itemIndex = start + offset;
+                const selected = itemIndex === active;
+                const marker = selected ? "\u276F" : " ";
+                const number = itemIndex < 9 ? String(itemIndex + 1) : " ";
+                const isCurrent = current !== undefined && item.value === current;
+                return (_jsxs(Text, { color: selected ? theme.accent : theme.muted, children: [marker, " ", number, ". ", isCurrent ? "\u25CF " : "  ", item.label, item.hint ? _jsxs(Text, { color: theme.muted, children: ["  ", item.hint] }) : null] }, item.value));
+            }), items.length > WINDOW ? (_jsx(Text, { color: theme.muted, children: `  … ${start + 1}-${start + visible.length} of ${items.length}` })) : null, _jsx(Text, { color: theme.muted, children: hint ?? "  \u2191/\u2193 select \u00B7 1-9 jump \u00B7 Enter confirm \u00B7 Esc cancel" })] }));
+};

package/src/ui/Prompt.ts

@@ -0,0 +1,38 @@
+import { jsxs as _jsxs, jsx as _jsx } from "react/jsx-runtime";
+/**
+ * Bottom prompt input, with a left-side caret + slash-command autocomplete.
+ *
+ * We re-use ink-text-input for low-level keyboard handling but wrap it with
+ * a fixed caret indicator + autocomplete preview to mirror the look of
+ * Claude Code's prompt.
+ *
+ * The caret used to blink on a 500 ms setInterval. That timer re-rendered the
+ * whole input line twice a second, which on some terminals rewrote the line
+ * while the text cursor was being re-positioned and made the caret occasionally
+ * jump one column ahead after the first keystroke. A static caret removes the
+ * timer-driven redraw; ink-text-input's own cursor still tracks the real caret.
+ */
+import { Box, Text } from "ink";
+import TextInput from "ink-text-input";
+import { COMMANDS } from "../commands/index.js";
+export const Prompt = ({ theme, value, onChange, onSubmit, disabled, placeholder, mask, }) => {
+    const suggestion = autocomplete(value);
+    return (_jsxs(Box, { flexDirection: "column", borderStyle: "round", borderColor: disabled ? theme.muted : theme.accent, paddingX: 1, children: [_jsxs(Box, { children: [_jsx(Text, { color: theme.accent, bold: true, children: "\u276F " }), disabled ? (_jsx(Text, { color: theme.muted, children: placeholder ?? "Working… (Esc to cancel)" })) : (_jsx(TextInput, { value: value, onChange: onChange, onSubmit: onSubmit, placeholder: placeholder ?? "Type a message or /help …", showCursor: true, mask: mask }))] }), !disabled && suggestion ? (_jsx(Box, { marginLeft: 2, children: _jsxs(Text, { color: theme.muted, children: ["\u21AA ", suggestion] }) })) : null] }));
+};
+function autocomplete(value) {
+    if (!value.startsWith("/") || value.includes(" "))
+        return undefined;
+    const partial = value.slice(1).toLowerCase();
+    if (!partial) {
+        return COMMANDS.filter((c) => !c.hidden)
+            .map((c) => `/${c.name}`)
+            .slice(0, 6)
+            .join("  ");
+    }
+    const matches = COMMANDS.filter((c) => !c.hidden &&
+        (c.name.startsWith(partial) ||
+            (c.aliases ?? []).some((a) => a.startsWith(partial))));
+    if (matches.length === 0)
+        return undefined;
+    return matches.map((c) => `/${c.name} — ${c.description}`).slice(0, 4).join("\n  ");
+}

package/src/ui/Spinner.ts

@@ -0,0 +1,39 @@
+import { jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * Custom thinking spinner.
+ *
+ * We don't use ink-spinner's built-in spinners directly because we want to
+ * (1) cycle through a varied set of action verbs ("Thinking…", "Pondering…")
+ * and (2) keep the dots animation in sync with the verb rotation.
+ */
+import { useEffect, useState } from "react";
+import { Text } from "ink";
+const FRAMES = ["⠋", "⠙", "⠹", "⠸", "⠼", "⠴", "⠦", "⠧", "⠇", "⠏"];
+const VERBS = [
+    "Thinking",
+    "Pondering",
+    "Reasoning",
+    "Cooking",
+    "Crafting",
+    "Brewing",
+    "Sketching",
+    "Charging",
+];
+export const Spinner = ({ theme, label, stable = false }) => {
+    const [tick, setTick] = useState(0);
+    // stable UI only lowers the redraw rate; it must still animate. A frozen
+    // frame made long waits look like a hang.
+    const configured = Number(process.env["FASTCODE_SPINNER_MS"]);
+    const interval = Number.isFinite(configured) && configured >= 60
+        ? configured
+        : stable
+            ? 120
+            : 80;
+    useEffect(() => {
+        const id = setInterval(() => setTick((t) => t + 1), interval);
+        return () => clearInterval(id);
+    }, [interval]);
+    const frame = FRAMES[tick % FRAMES.length];
+    const verb = label ?? VERBS[Math.floor(tick / 24) % VERBS.length];
+    return (_jsxs(Text, { color: theme.accent, children: [frame, " ", _jsxs(Text, { color: theme.muted, children: [verb, "\u2026"] })] }));
+};