@kinqs/brainrouter-cli 0.3.6 → 0.3.7

package/dist/cli/wizard/runner.js

@@ -0,0 +1,488 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import os from 'node:os';
+import { NoTTYError } from '../cliPrompt.js';
+import { writePreferences } from '../../state/preferencesStore.js';
+import { loadOrInitConfig, saveConfig, } from '../../config/config.js';
+import { initAgentMd } from '../../prompt/initAgentMd.js';
+import { McpClientWrapper } from '../../runtime/mcpClient.js';
+import { PROVIDER_CATALOG, detectProviderFromEnv, validateApiKey, maskApiKey, } from './providers.js';
+import { initWizardState, reduceWizard, } from './types.js';
+import { pickFromList, promptText } from './picker.js';
+import { selectModel } from './modelsApi.js';
+import { buildTheme } from '../theme.js';
+/**
+ * 0.3.7 onboarding wizard — drives the Step state machine over the new
+ * internal picker (`./picker.ts`) which renders atomically and never
+ * has external stdout writes mid-step. Fixes the redraw-stacking bug
+ * the original `askChoice`-based wizard hit on every cursor move.
+ *
+ * Two entry modes (unchanged from the original design):
+ *
+ *   1. **First-run auto-trigger** — `index.ts` calls
+ *      `runWizard({ ownsReadline: true })` BEFORE constructing the
+ *      Agent / McpClient when `~/.config/brainrouter/config.json` is
+ *      missing.
+ *   2. **`/init`** from inside the REPL — `runWizard({ ownsReadline:
+ *      false })` reuses the REPL's existing readline.
+ */
+const ONBOARDED_MARKER = path.join(os.homedir(), '.config', 'brainrouter', '.onboarded');
+export function isOnboarded() {
+    try {
+        return fs.existsSync(ONBOARDED_MARKER);
+    }
+    catch {
+        return false;
+    }
+}
+export function markOnboarded() {
+    try {
+        fs.mkdirSync(path.dirname(ONBOARDED_MARKER), { recursive: true });
+        fs.writeFileSync(ONBOARDED_MARKER, '', 'utf8');
+    }
+    catch {
+        /* non-fatal */
+    }
+}
+const TOTAL_STEPS = 6; // theme, provider, apiKey, model, mcp, agentMd
+function progressBadge(step) {
+    const decisionSteps = ['theme', 'provider', 'apiKey', 'model', 'mcp', 'agentMd'];
+    const idx = decisionSteps.indexOf(step);
+    if (idx < 0)
+        return undefined;
+    return `Step ${idx + 1} of ${TOTAL_STEPS}`;
+}
+export async function runWizard(opts) {
+    if (opts.ownsReadline && !process.stdin.isTTY) {
+        throw new NoTTYError('BrainRouter has no config and stdin is not a TTY — run `brainrouter` in an interactive terminal at least once to complete the setup wizard.');
+    }
+    let state = initWizardState();
+    let theme = buildTheme('dark');
+    while (!state.committed && !state.aborted) {
+        const before = state.draft.theme;
+        state = await runStep(state, opts, theme);
+        if (state.draft.theme && state.draft.theme !== before) {
+            theme = buildTheme(state.draft.theme);
+        }
+    }
+    let savedConfig;
+    if (state.committed) {
+        savedConfig = commitWizardDraft(state.draft, opts.workspaceRoot);
+        markOnboarded();
+        renderDoneSummary(state, savedConfig, theme);
+    }
+    else if (state.aborted) {
+        process.stdout.write(theme.warning('\n  Wizard aborted — no changes saved.\n\n'));
+    }
+    return { state, config: savedConfig };
+}
+async function runStep(state, opts, theme) {
+    switch (state.currentStep) {
+        case 'welcome': return runWelcomeStep(state, theme);
+        case 'theme': return runThemeStep(state, opts.workspaceRoot);
+        case 'provider': return runProviderStep(state, theme);
+        case 'apiKey': return runApiKeyStep(state, theme);
+        case 'model': return runModelStep(state, theme);
+        case 'mcp': return runMcpStep(state, theme);
+        case 'agentMd': return runAgentMdStep(state, opts.workspaceRoot, theme);
+        case 'done': return reduceWizard(state, { kind: 'commit' });
+    }
+}
+// --- Welcome -----------------------------------------------------------
+async function runWelcomeStep(state, theme) {
+    const result = await pickFromList({
+        theme,
+        title: '🧠  BrainRouter',
+        subtitle: 'A memory-native coding agent that runs in your terminal. This wizard takes ~60 seconds and writes to ~/.config/brainrouter/config.json plus <workspace>/.brainrouter/cli/preferences.json. Press ENTER to start, q to abort.',
+        rows: [
+            { id: 'start', label: 'Start setup', description: 'Theme → Provider → API key → Model → MCP → AGENT.md' },
+            { id: 'abort', label: 'Abort', description: 'Exit without saving anything' },
+        ],
+        badge: 'Welcome',
+        eraseOnClose: true,
+    });
+    if (result.kind !== 'pick' || result.id === 'abort')
+        return reduceWizard(state, { kind: 'abort' });
+    return reduceWizard(state, { kind: 'advance', patch: {} });
+}
+// --- Theme -------------------------------------------------------------
+async function runThemeStep(state, workspaceRoot) {
+    const themes = [
+        { id: 'dark', label: 'Dark', description: 'Default · saturated accents on a black terminal' },
+        { id: 'light', label: 'Light', description: 'Darker accents for white terminals (solarized-light, GitHub light)' },
+        { id: 'mono', label: 'Mono', description: 'No color · screenshots, CI logs, pipe-to-less' },
+    ];
+    const result = await pickFromList({
+        theme: buildTheme('dark'),
+        title: 'Theme',
+        subtitle: 'Pick a color palette. Arrow keys live-preview the prompt accent inside this panel.',
+        badge: progressBadge('theme'),
+        rows: themes.map((t) => ({ id: t.id, label: t.label, description: t.description })),
+        initialCursor: 0,
+        onCursorChange: (id) => {
+            const preview = buildTheme(id);
+            return [
+                preview.muted('preview › ') + preview.primary('brainrouter>') + ' ' + preview.heading('sample prompt') + '  ' + preview.muted('with ') + preview.success('success') + preview.muted(' and ') + preview.danger('danger') + preview.muted(' accents'),
+            ];
+        },
+        eraseOnClose: true,
+    });
+    if (result.kind !== 'pick')
+        return reduceWizard(state, { kind: 'abort' });
+    const mode = result.id;
+    try {
+        writePreferences(workspaceRoot, { theme: mode });
+    }
+    catch { /* non-fatal */ }
+    return reduceWizard(state, { kind: 'advance', patch: { theme: mode } });
+}
+// --- Provider ----------------------------------------------------------
+async function runProviderStep(state, theme) {
+    const detected = detectProviderFromEnv();
+    const rows = PROVIDER_CATALOG.map((p) => {
+        const envHit = !!process.env[p.envKey];
+        const status = envHit ? 'env detected' : p.local ? 'local · key optional' : 'needs API key';
+        return {
+            id: p.id,
+            label: p.label,
+            value: status,
+            description: p.hint,
+        };
+    });
+    const initialCursor = detected
+        ? Math.max(0, PROVIDER_CATALOG.findIndex((p) => p.id === detected.id))
+        : 0;
+    const result = await pickFromList({
+        theme,
+        title: 'LLM provider',
+        subtitle: detected
+            ? `Detected ${detected.envKey} in your shell — ${detected.label} is pre-selected. Pick "Other" to enter a custom OpenAI-compatible endpoint.`
+            : 'Pick the LLM provider for the chat agent. Pick "Other" to enter a custom OpenAI-compatible endpoint.',
+        badge: progressBadge('provider'),
+        rows,
+        initialCursor,
+        allowOther: true,
+        otherLabel: 'Other endpoint',
+        otherDescription: 'OpenAI-compatible /v1/chat/completions URL',
+        eraseOnClose: true,
+    });
+    if (result.kind === 'cancelled')
+        return reduceWizard(state, { kind: 'abort' });
+    if (result.kind === 'other') {
+        const url = result.text;
+        if (!url)
+            return state;
+        const ad = {
+            id: 'custom',
+            label: 'Custom endpoint',
+            hint: url,
+            endpoint: url,
+            envKey: 'BRAINROUTER_LLM_API_KEY',
+            local: /localhost|127\.0\.0\.1|::1|0\.0\.0\.0/.test(url),
+            models: [],
+            defaultModel: 'gpt-4o-mini',
+        };
+        return reduceWizard(state, {
+            kind: 'advance',
+            patch: { provider: ad, customEndpoint: url },
+        });
+    }
+    const provider = PROVIDER_CATALOG.find((p) => p.id === result.id);
+    if (!provider)
+        return state;
+    return reduceWizard(state, { kind: 'advance', patch: { provider } });
+}
+// --- API key -----------------------------------------------------------
+async function runApiKeyStep(state, theme) {
+    const provider = state.draft.provider;
+    if (!provider)
+        return reduceWizard(state, { kind: 'back' });
+    const envValue = process.env[provider.envKey] ?? '';
+    const subtitle = envValue
+        ? `${provider.envKey} is set in your shell — press ENTER to accept, or type a different key.`
+        : provider.local
+            ? `${provider.label} is local — a blank API key is fine (just press ENTER).`
+            : `Paste your ${provider.label} API key. Stored at ~/.config/brainrouter/config.json.`;
+    const result = await promptText({
+        theme,
+        title: 'API key',
+        subtitle,
+        badge: `${progressBadge('apiKey')} · ${provider.label}`,
+        prefilled: envValue,
+        mask: false, // we mask on display in the summary; while typing the user benefits from seeing chars
+        placeholder: provider.local ? '(blank OK for local endpoints)' : 'paste your API key here',
+        validate: (raw) => {
+            const verdict = validateApiKey(raw, provider);
+            if (verdict.kind === 'reject')
+                return verdict.reason;
+            return undefined;
+        },
+        eraseOnClose: true,
+    });
+    if (result.kind === 'cancelled')
+        return reduceWizard(state, { kind: 'abort' });
+    const key = result.text;
+    const verdict = validateApiKey(key, provider);
+    let next = state;
+    if (verdict.kind === 'accept' && verdict.warning) {
+        next = reduceWizard(next, { kind: 'warn', message: verdict.warning });
+    }
+    return reduceWizard(next, { kind: 'advance', patch: { apiKey: key } });
+}
+// --- Model -------------------------------------------------------------
+async function runModelStep(state, theme) {
+    const provider = state.draft.provider;
+    if (!provider)
+        return reduceWizard(state, { kind: 'back' });
+    // Wizard delegates to the shared `selectModel` so the in-REPL
+    // `/model` quick-swap and onboarding pick from the same UI. The
+    // wizard wraps the picker's "current model" semantic differently:
+    // here there's no current model yet (we're CREATING the config),
+    // so we pass undefined and the helper opens the cursor on the
+    // provider default. `eraseOnClose: true` keeps the wizard's frame
+    // hygiene (each step blanks itself before the next renders).
+    const result = await selectModel({
+        theme,
+        provider,
+        apiKey: state.draft.apiKey ?? '',
+        endpointOverride: state.draft.customEndpoint,
+        title: 'Model',
+        badge: progressBadge('model'),
+        eraseOnClose: true,
+    });
+    if (!result)
+        return reduceWizard(state, { kind: 'abort' });
+    return reduceWizard(state, { kind: 'advance', patch: { model: result.model || provider.defaultModel } });
+}
+// --- MCP ---------------------------------------------------------------
+async function runMcpStep(state, theme) {
+    const rows = [
+        { id: 'local-stdio', label: 'Local stdio', value: 'spawn brainrouter-mcp', description: 'No HTTP server needed — the CLI spawns the MCP child', pick: { kind: 'local-stdio' } },
+        { id: 'local-http', label: 'Local HTTP', value: 'http://localhost:3747', description: 'Connect to a brainrouter-mcp HTTP server running locally', pick: { kind: 'local-http' } },
+        { id: 'remote-http', label: 'Remote HTTP', value: 'custom URL', description: 'Connect to a hosted BrainRouter MCP (URL + optional key)', pick: { kind: 'remote-http', url: '' } },
+        { id: 'skip', label: 'Skip', value: 'no MCP', description: 'Local tools only · no recall, skills, or capture', pick: { kind: 'skip' } },
+    ];
+    const result = await pickFromList({
+        theme,
+        title: 'MCP server',
+        subtitle: 'BrainRouter\'s memory + skills live behind an MCP server. Pick how to reach it.',
+        badge: progressBadge('mcp'),
+        rows,
+        initialCursor: 0,
+        eraseOnClose: true,
+    });
+    if (result.kind === 'cancelled')
+        return reduceWizard(state, { kind: 'abort' });
+    if (result.kind !== 'pick')
+        return state;
+    const picked = rows.find((r) => r.id === result.id)?.pick;
+    if (!picked)
+        return state;
+    let final = picked;
+    if (final.kind === 'remote-http') {
+        const urlResult = await promptText({
+            theme,
+            title: 'Remote MCP URL',
+            subtitle: 'Paste the full URL (e.g. https://brainrouter.example.com/mcp). Press Esc to back out.',
+            badge: 'MCP',
+            prefilled: '',
+            placeholder: 'https://...',
+            validate: (raw) => {
+                const v = raw.trim();
+                if (!v)
+                    return 'URL is required';
+                try {
+                    new URL(v);
+                }
+                catch {
+                    return 'not a valid URL';
+                }
+                return undefined;
+            },
+            eraseOnClose: true,
+        });
+        if (urlResult.kind === 'cancelled')
+            return reduceWizard(state, { kind: 'abort' });
+        final = { kind: 'remote-http', url: urlResult.text.trim() };
+    }
+    // 0.3.7 — collect the BrainRouter MCP API key for any HTTP transport
+    // (local OR remote). Pre-fill from BRAINROUTER_API_KEY env. Blank
+    // submission is OK — servers without auth accept empty bearers.
+    if (final.kind === 'local-http' || final.kind === 'remote-http') {
+        const envValue = process.env.BRAINROUTER_API_KEY ?? '';
+        const keyResult = await promptText({
+            theme,
+            title: 'BrainRouter API key',
+            subtitle: envValue
+                ? 'BRAINROUTER_API_KEY is set — press ENTER to accept, type to override, or blank if the server is unauthenticated.'
+                : final.kind === 'local-http'
+                    ? 'Optional — leave blank if your local brainrouter-mcp HTTP server runs without auth.'
+                    : 'Optional — leave blank if the hosted MCP doesn\'t require auth. Use the key issued by the BrainRouter dashboard.',
+            badge: 'MCP',
+            prefilled: envValue,
+            placeholder: '(blank OK)',
+            eraseOnClose: true,
+        });
+        if (keyResult.kind === 'cancelled')
+            return reduceWizard(state, { kind: 'abort' });
+        const apiKey = keyResult.text.trim() || undefined;
+        final = final.kind === 'local-http'
+            ? { kind: 'local-http', apiKey }
+            : { kind: 'remote-http', url: final.url, apiKey };
+    }
+    const probe = await probeMcp(final, state.draft);
+    if (probe.warning) {
+        const next = reduceWizard(state, { kind: 'warn', message: probe.warning });
+        return reduceWizard(next, { kind: 'advance', patch: { mcp: final } });
+    }
+    return reduceWizard(state, { kind: 'advance', patch: { mcp: final } });
+}
+async function probeMcp(pick, draft) {
+    if (pick.kind === 'skip')
+        return { ok: true };
+    const wrapper = new McpClientWrapper();
+    const llmConfig = draft.provider && draft.model
+        ? { provider: 'openai', apiKey: draft.apiKey ?? '', model: draft.model, endpoint: draft.customEndpoint ?? draft.provider.endpoint }
+        : undefined;
+    const serverConfig = mcpPickToServerConfig(pick);
+    if (!serverConfig)
+        return { ok: false, warning: 'Could not build MCP server config for this pick.' };
+    try {
+        await Promise.race([
+            wrapper.connect(serverConfig, llmConfig, 'wizard'),
+            new Promise((_, reject) => setTimeout(() => reject(new Error('probe timed out after 5s')), 5_000)),
+        ]);
+        await wrapper.close();
+        return { ok: true };
+    }
+    catch (err) {
+        try {
+            await wrapper.close();
+        }
+        catch { /* ignore */ }
+        return {
+            ok: false,
+            warning: `MCP probe failed (${err?.message ?? err}). Profile saved — start the server and run /mcp reconnect later.`,
+        };
+    }
+}
+function mcpPickToServerConfig(pick) {
+    if (pick.kind === 'local-stdio') {
+        return { type: 'stdio', command: 'brainrouter-mcp', args: [], identity: 'brainrouter' };
+    }
+    if (pick.kind === 'local-http') {
+        return { type: 'http', url: 'http://localhost:3747/mcp', apiKey: pick.apiKey, identity: 'brainrouter' };
+    }
+    if (pick.kind === 'remote-http') {
+        return { type: 'http', url: pick.url, apiKey: pick.apiKey, identity: 'brainrouter' };
+    }
+    return undefined;
+}
+// --- AGENT.md ----------------------------------------------------------
+async function runAgentMdStep(state, workspaceRoot, theme) {
+    const agentMdPath = path.join(workspaceRoot, 'AGENT.md');
+    const claudeMdPath = path.join(workspaceRoot, 'CLAUDE.md');
+    const exists = fs.existsSync(agentMdPath) || fs.existsSync(claudeMdPath);
+    const result = await pickFromList({
+        theme,
+        title: 'AGENT.md',
+        subtitle: exists
+            ? 'Workspace already has AGENT.md / CLAUDE.md — skipping by default. Pick "Overwrite" only if you really want to replace it.'
+            : 'AGENT.md gives every coding agent (Claude Code, Codex, BrainRouter, …) a single hub of repo conventions. Recommended.',
+        badge: progressBadge('agentMd'),
+        rows: exists
+            ? [
+                { id: 'skip', label: 'Skip', value: 'keep existing file', description: 'Leave the current AGENT.md / CLAUDE.md alone' },
+                { id: 'write', label: 'Overwrite', value: 'replace contents', description: 'Drop the starter template over the existing file' },
+            ]
+            : [
+                { id: 'write', label: 'Write AGENT.md', value: 'recommended', description: 'Scaffold a starter template in the workspace root' },
+                { id: 'skip', label: 'Skip', value: 'no file', description: 'Write AGENT.md manually later' },
+            ],
+        initialCursor: 0,
+        eraseOnClose: true,
+    });
+    if (result.kind === 'cancelled')
+        return reduceWizard(state, { kind: 'abort' });
+    if (result.kind !== 'pick')
+        return state;
+    return reduceWizard(state, {
+        kind: 'advance',
+        patch: { writeAgentMd: result.id === 'write' },
+    });
+}
+// --- Commit + summary --------------------------------------------------
+function commitWizardDraft(draft, workspaceRoot) {
+    const config = loadOrInitConfig();
+    if (draft.provider) {
+        config.llm = {
+            provider: 'openai',
+            apiKey: draft.apiKey ?? '',
+            model: draft.model ?? draft.provider.defaultModel,
+            endpoint: draft.customEndpoint ?? draft.provider.endpoint,
+        };
+    }
+    if (draft.mcp && draft.mcp.kind !== 'skip') {
+        const profileName = draft.mcp.kind === 'remote-http' ? 'remote' : draft.mcp.kind === 'local-http' ? 'local-http' : 'local-stdio';
+        const serverConfig = mcpPickToServerConfig(draft.mcp);
+        if (serverConfig) {
+            config.servers[profileName] = serverConfig;
+            config.activeServer = profileName;
+        }
+    }
+    else if (draft.mcp?.kind === 'skip') {
+        // Skip means skip — clear any previously-active profile so the CLI doesn't
+        // silently re-spawn an MCP child from a stale config. The user can re-add
+        // a profile via `/login` later.
+        config.activeServer = '';
+    }
+    saveConfig(config);
+    if (draft.theme) {
+        try {
+            writePreferences(workspaceRoot, { theme: draft.theme });
+        }
+        catch { /* non-fatal */ }
+    }
+    if (draft.writeAgentMd) {
+        try {
+            initAgentMd(workspaceRoot);
+        }
+        catch { /* non-fatal */ }
+    }
+    return config;
+}
+function renderDoneSummary(state, _config, theme) {
+    const lines = [
+        '',
+        theme.heading('  ✓  Setup complete'),
+        '',
+        `    ${theme.muted('theme')}    ${theme.plain(state.draft.theme ?? 'dark')}`,
+        `    ${theme.muted('provider')} ${theme.plain(state.draft.provider?.label ?? '(unset)')}`,
+        `    ${theme.muted('model')}    ${theme.plain(state.draft.model ?? '(unset)')}`,
+        `    ${theme.muted('api key')}  ${theme.plain(maskApiKey(state.draft.apiKey ?? ''))}`,
+        `    ${theme.muted('mcp')}      ${theme.plain(formatMcpForSummary(state.draft.mcp))}`,
+        `    ${theme.muted('agent.md')} ${theme.plain(state.draft.writeAgentMd ? 'written' : 'skipped')}`,
+        '',
+        theme.muted('  Config saved to ~/.config/brainrouter/config.json.'),
+        theme.muted('  Re-run any time with /init.  Tweak individual knobs with /config.'),
+    ];
+    if (state.warnings.length > 0) {
+        lines.push('');
+        lines.push(theme.warning('  Advisories:'));
+        for (const w of state.warnings) {
+            lines.push(`    ${theme.warning('!')} ${w.message}`);
+        }
+    }
+    process.stdout.write(lines.join('\n') + '\n\n');
+}
+function formatMcpForSummary(pick) {
+    if (!pick)
+        return '(unset)';
+    if (pick.kind === 'local-stdio')
+        return 'local stdio (brainrouter-mcp)';
+    if (pick.kind === 'local-http')
+        return 'local http (http://localhost:3747/mcp)';
+    if (pick.kind === 'remote-http')
+        return `remote · ${pick.url}`;
+    return 'skipped (offline-only)';
+}

package/dist/cli/wizard/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * 0.3.7 wizard — pure types + step state machine.
+ *
+ * The wizard walks the user through a small, ordered sequence of
+ * decisions. Each step has its own decision shape; together they fill
+ * in a `WizardDraft` that the Done step commits to disk.
+ *
+ * Why a typed Step enum + draft (instead of one giant async function
+ * with awaits in sequence)? Three reasons:
+ *
+ *   1. **Esc backs out one step at a time.** A reducer transition lets
+ *      us model "back" cleanly (Step.Provider → Step.Theme) without
+ *      unwinding an async stack.
+ *   2. **The runner is testable.** Driving the reducer with synthetic
+ *      events (`pick`, `back`, `abort`) lets us assert the wizard ends
+ *      in a known terminal state without simulating a real TTY.
+ *   3. **The shape lifts straight from peer references.**
+ *      `openSrc/codex/codex-rs/tui/src/onboarding/onboarding_screen.rs`
+ *      uses the same Step enum + per-step state pattern; we copy the
+ *      pattern, not the code.
+ */
+import type { ThemeMode } from '../theme.js';
+import type { ProviderEntry } from './providers.js';
+export type Step = 'welcome' | 'theme' | 'provider' | 'apiKey' | 'model' | 'mcp' | 'agentMd' | 'done';
+/** Ordered list — used by the runner to compute "next" and "previous". */
+export declare const STEP_ORDER: readonly Step[];
+/**
+ * MCP transport pick. `skip` means "no MCP this session — local tools
+ * only". Useful for users who want to try the agent before standing up
+ * the brain. Matches the existing OFFLINE MODE behaviour the REPL
+ * already handles.
+ */
+export type McpPick = {
+    kind: 'local-stdio';
+} | {
+    kind: 'local-http';
+    apiKey?: string;
+} | {
+    kind: 'remote-http';
+    url: string;
+    apiKey?: string;
+} | {
+    kind: 'skip';
+};
+/**
+ * Accumulated wizard state. Every step writes into this draft; only
+ * the final commit phase touches disk. Aborting via `q` discards the
+ * draft so a half-finished wizard never leaves a partial config.
+ */
+export interface WizardDraft {
+    theme?: ThemeMode;
+    provider?: ProviderEntry;
+    /** Endpoint override — set when the user picks "Custom…" from the picker. */
+    customEndpoint?: string;
+    apiKey?: string;
+    model?: string;
+    mcp?: McpPick;
+    writeAgentMd?: boolean;
+}
+/**
+ * Non-fatal advisories the runner accumulates so the Done step can
+ * surface them all at once ("you accepted an unusual key prefix" /
+ * "MCP probe failed — saved anyway"). Better than printing each
+ * warning at the time it's generated and losing it under the next
+ * picker redraw.
+ */
+export interface WizardWarning {
+    step: Step;
+    message: string;
+}
+export interface WizardState {
+    currentStep: Step;
+    draft: WizardDraft;
+    warnings: WizardWarning[];
+    /** True once the Done step has committed the draft to disk. */
+    committed: boolean;
+    /** True if the user aborted via `q` / Ctrl+C — nothing was written. */
+    aborted: boolean;
+}
+/**
+ * Wizard events. The runner translates picker results / Esc keys into
+ * one of these and feeds them through `reduceWizard`. The reducer is
+ * pure so the test suite can drive the full state machine without
+ * touching the TTY.
+ */
+export type WizardEvent = {
+    kind: 'advance';
+    patch: Partial<WizardDraft>;
+} | {
+    kind: 'back';
+} | {
+    kind: 'abort';
+} | {
+    kind: 'warn';
+    message: string;
+} | {
+    kind: 'commit';
+};
+export declare function initWizardState(): WizardState;
+/**
+ * Compute the next step. Pure — used by `reduceWizard` and exposed for
+ * tests + the runner's progress indicator ("step 3 of 7").
+ */
+export declare function nextStep(current: Step): Step | undefined;
+export declare function prevStep(current: Step): Step | undefined;
+/**
+ * Pure reducer. Every wizard transition must go through here so the
+ * test suite can replay the same event sequence the runner emits.
+ *
+ * Contract:
+ *   - `advance` applies the patch into the draft and steps forward;
+ *     a no-op when called on the Done step.
+ *   - `back` rewinds one step; a no-op on the first step.
+ *   - `abort` lands the wizard in a terminal state with `aborted: true`
+ *     and the draft preserved (caller may inspect for partial intent).
+ *   - `warn` appends an advisory; doesn't move the step pointer.
+ *   - `commit` flips `committed: true` on the Done step only.
+ *
+ * The reducer never throws — bad inputs are silently ignored so a
+ * stray key event doesn't crash the wizard mid-render.
+ */
+export declare function reduceWizard(state: WizardState, event: WizardEvent): WizardState;