npm - @kinqs/brainrouter-cli - Versions diffs - 0.3.5 → 0.3.7 - Mend

@kinqs/brainrouter-cli 0.3.5 → 0.3.7

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (125) hide show

package/README.md +29 -52
package/agents/architect.json +18 -0
package/agents/explorer.json +18 -0
package/agents/reviewer.json +18 -0
package/agents/verifier.json +18 -0
package/agents/worker.json +18 -0
package/bin/cli.cjs +71 -0
package/dist/agent/agent.d.ts +224 -3
package/dist/agent/agent.js +561 -55
package/dist/cli/banner.d.ts +80 -0
package/dist/cli/banner.js +232 -0
package/dist/cli/cliPrompt.d.ts +106 -0
package/dist/cli/cliPrompt.js +314 -0
package/dist/cli/commands/_context.d.ts +3 -1
package/dist/cli/commands/_helpers.d.ts +1 -1
package/dist/cli/commands/_helpers.js +6 -6
package/dist/cli/commands/config.d.ts +46 -0
package/dist/cli/commands/config.js +1042 -0
package/dist/cli/commands/guard.js +75 -10
package/dist/cli/commands/init.d.ts +20 -0
package/dist/cli/commands/init.js +64 -0
package/dist/cli/commands/login.d.ts +13 -0
package/dist/cli/commands/login.js +179 -0
package/dist/cli/commands/mcp.d.ts +19 -0
package/dist/cli/commands/mcp.js +286 -0
package/dist/cli/commands/memory.js +2 -2
package/dist/cli/commands/obs.js +22 -22
package/dist/cli/commands/orchestration.js +18 -0
package/dist/cli/commands/session.js +13 -5
package/dist/cli/commands/ui.js +202 -91
package/dist/cli/commands/workflow.d.ts +20 -0
package/dist/cli/commands/workflow.js +368 -51
package/dist/cli/ink/ChatApp.d.ts +206 -0
package/dist/cli/ink/ChatApp.js +493 -0
package/dist/cli/ink/Frame.d.ts +26 -0
package/dist/cli/ink/Frame.js +5 -0
package/dist/cli/ink/Picker.d.ts +65 -0
package/dist/cli/ink/Picker.js +133 -0
package/dist/cli/ink/SlashPalette.d.ts +51 -0
package/dist/cli/ink/SlashPalette.js +136 -0
package/dist/cli/ink/TextField.d.ts +34 -0
package/dist/cli/ink/TextField.js +47 -0
package/dist/cli/ink/WizardApp.d.ts +7 -0
package/dist/cli/ink/WizardApp.js +422 -0
package/dist/cli/ink/ambientChat.d.ts +34 -0
package/dist/cli/ink/ambientChat.js +7 -0
package/dist/cli/ink/consoleCapture.d.ts +11 -0
package/dist/cli/ink/consoleCapture.js +33 -0
package/dist/cli/ink/markdownRender.d.ts +41 -0
package/dist/cli/ink/markdownRender.js +278 -0
package/dist/cli/ink/renderWithResizeClear.d.ts +14 -0
package/dist/cli/ink/renderWithResizeClear.js +33 -0
package/dist/cli/ink/runChat.d.ts +34 -0
package/dist/cli/ink/runChat.js +571 -0
package/dist/cli/ink/runPicker.d.ts +31 -0
package/dist/cli/ink/runPicker.js +139 -0
package/dist/cli/ink/runSlashPalette.d.ts +23 -0
package/dist/cli/ink/runSlashPalette.js +33 -0
package/dist/cli/ink/runWizard.d.ts +22 -0
package/dist/cli/ink/runWizard.js +133 -0
package/dist/cli/ink/stdinHandoff.d.ts +51 -0
package/dist/cli/ink/stdinHandoff.js +78 -0
package/dist/cli/ink/toolFormat.d.ts +73 -0
package/dist/cli/ink/toolFormat.js +180 -0
package/dist/cli/ink/useTerminalSize.d.ts +35 -0
package/dist/cli/ink/useTerminalSize.js +26 -0
package/dist/cli/repl.d.ts +25 -3
package/dist/cli/repl.js +64 -646
package/dist/cli/slashSuggest.d.ts +32 -0
package/dist/cli/slashSuggest.js +146 -0
package/dist/cli/spinner.d.ts +34 -0
package/dist/cli/spinner.js +36 -0
package/dist/cli/statusline.d.ts +67 -0
package/dist/cli/statusline.js +204 -0
package/dist/cli/theme.d.ts +79 -0
package/dist/cli/theme.js +106 -0
package/dist/cli/whereView.d.ts +81 -0
package/dist/cli/whereView.js +245 -0
package/dist/cli/wizard/modelsApi.d.ts +72 -0
package/dist/cli/wizard/modelsApi.js +166 -0
package/dist/cli/wizard/picker.d.ts +202 -0
package/dist/cli/wizard/picker.js +547 -0
package/dist/cli/wizard/providers.d.ts +86 -0
package/dist/cli/wizard/providers.js +190 -0
package/dist/cli/wizard/runner.d.ts +13 -0
package/dist/cli/wizard/runner.js +488 -0
package/dist/cli/wizard/types.d.ts +122 -0
package/dist/cli/wizard/types.js +109 -0
package/dist/config/config.d.ts +52 -0
package/dist/config/config.js +89 -75
package/dist/index.js +215 -206
package/dist/memory/briefing.d.ts +11 -1
package/dist/memory/briefing.js +69 -1
package/dist/memory/consolidation.d.ts +1 -1
package/dist/orchestration/agentRegistry.d.ts +36 -0
package/dist/orchestration/agentRegistry.js +64 -0
package/dist/orchestration/orchestrator.d.ts +7 -0
package/dist/orchestration/orchestrator.js +2 -0
package/dist/orchestration/tools.d.ts +10 -1
package/dist/orchestration/tools.js +48 -4
package/dist/prompt/breadthHint.d.ts +5 -0
package/dist/prompt/breadthHint.js +44 -0
package/dist/prompt/skillCatalog.d.ts +11 -0
package/dist/prompt/skillCatalog.js +134 -0
package/dist/prompt/skillRunner.d.ts +2 -2
package/dist/prompt/skillRunner.js +2 -31
package/dist/prompt/systemPrompt.d.ts +34 -0
package/dist/prompt/systemPrompt.js +128 -108
package/dist/runtime/dangerousCommand.d.ts +53 -0
package/dist/runtime/dangerousCommand.js +105 -0
package/dist/runtime/mcpClient.d.ts +38 -1
package/dist/runtime/mcpClient.js +104 -13
package/dist/runtime/mcpPool.d.ts +162 -0
package/dist/runtime/mcpPool.js +423 -0
package/dist/runtime/mcpUtils.d.ts +3 -1
package/dist/state/goalStore.d.ts +98 -17
package/dist/state/goalStore.js +132 -42
package/dist/state/preferencesStore.d.ts +67 -3
package/dist/state/preferencesStore.js +84 -1
package/dist/state/workflowArtifacts.d.ts +63 -2
package/dist/state/workflowArtifacts.js +120 -8
package/dist/tests/_helpers.d.ts +31 -0
package/dist/tests/_helpers.js +91 -0
package/package.json +12 -5
package/.env.example +0 -109

package/dist/cli/wizard/picker.js ADDED Viewed

@@ -0,0 +1,547 @@
+import readline from 'node:readline';
+import { getActiveReadline, setActiveReadline } from '../cliPrompt.js';
+import { buildTheme } from '../theme.js';
+// --- Module-level shared state ----------------------------------------
+let internalPickerActive = false;
+export function isInternalPickerActive() { return internalPickerActive; }
+/**
+ * Compute the full picker frame as a single string. Pure function so
+ * tests can assert on the exact output without driving a TTY.
+ *
+ * Layout (single column for now — wide-terminal two-column comes in a
+ * follow-up):
+ *
+ *   ┌─ <title> ─────────────────────── <badge> ─┐
+ *   │ <subtitle>                                │
+ *   │                                           │
+ *   │ <body line 1>                             │
+ *   │ <body line 2>                             │
+ *   │ ...                                       │
+ *   │                                           │  (preview block if present)
+ *   │ <preview line 1>                          │
+ *   │ <preview line 2>                          │
+ *   │                                           │
+ *   │ <footer>                                  │
+ *   └───────────────────────────────────────────┘
+ */
+export function renderFrame(f) {
+    const t = f.theme;
+    const W = f.width;
+    // Inner content width: W minus 2 border cols minus 2 padding cols.
+    const inner = Math.max(20, W - 4);
+    const top = renderTopBorder(t, f.title, f.badge, W);
+    const lines = [top];
+    if (f.subtitle) {
+        for (const wrapped of wrap(f.subtitle, inner)) {
+            lines.push(t.primary('│') + ' ' + t.muted(padRight(wrapped, inner)) + ' ' + t.primary('│'));
+        }
+        lines.push(blank(t, W));
+    }
+    for (const raw of f.bodyLines) {
+        // Wrap is opt-out for body — the picker pre-formats option rows with
+        // exact widths, so let those pass through verbatim.
+        lines.push(t.primary('│') + ' ' + padRightVisible(raw, inner) + ' ' + t.primary('│'));
+    }
+    if (f.previewLines && f.previewLines.length > 0) {
+        lines.push(divider(t, W));
+        for (const raw of f.previewLines) {
+            lines.push(t.primary('│') + ' ' + padRightVisible(raw, inner) + ' ' + t.primary('│'));
+        }
+    }
+    lines.push(blank(t, W));
+    lines.push(t.primary('│') + ' ' + padRightVisible(t.muted(f.footer), inner) + ' ' + t.primary('│'));
+    lines.push(t.primary('└' + '─'.repeat(W - 2) + '┘'));
+    return lines.join('\n');
+}
+function renderTopBorder(t, title, badge, W) {
+    const titleText = ` ${t.heading(title)} `;
+    const badgeText = badge ? ` ${t.muted(badge)} ` : '';
+    const titleWidth = visibleLength(titleText);
+    const badgeWidth = visibleLength(badgeText);
+    const dashWidth = Math.max(2, W - 2 - titleWidth - badgeWidth);
+    return (t.primary('┌─') + titleText
+        + t.primary('─'.repeat(dashWidth))
+        + badgeText
+        + t.primary('┐'));
+}
+function blank(t, W) {
+    return t.primary('│') + ' '.repeat(W - 2) + t.primary('│');
+}
+function divider(t, W) {
+    // Subtle in-frame separator — single dim line, no chars.
+    return t.primary('├') + t.dim('─'.repeat(W - 2)) + t.primary('┤');
+}
+function padRight(s, w) {
+    if (s.length >= w)
+        return s.slice(0, w);
+    return s + ' '.repeat(w - s.length);
+}
+/** ANSI-aware right-pad. Strips ANSI sequences when counting width. */
+function padRightVisible(s, w) {
+    const v = visibleLength(s);
+    if (v >= w)
+        return clipVisible(s, w);
+    return s + ' '.repeat(w - v);
+}
+function visibleLength(s) {
+    return stripAnsi(s).length;
+}
+function stripAnsi(s) {
+    return s.replace(/\x1b\[[0-9;]*m/g, '');
+}
+function clipVisible(s, w) {
+    // Naive ANSI-aware clip — used only for badge / overflow protection.
+    let out = '';
+    let visible = 0;
+    let i = 0;
+    while (i < s.length && visible < w) {
+        if (s[i] === '\x1b') {
+            const end = s.indexOf('m', i);
+            if (end < 0)
+                break;
+            out += s.slice(i, end + 1);
+            i = end + 1;
+            continue;
+        }
+        out += s[i];
+        i++;
+        visible++;
+    }
+    return out;
+}
+/** Simple word-wrap; doesn't try to be ANSI-aware (subtitle takes plain text). */
+function wrap(s, w) {
+    const words = s.split(/\s+/);
+    const lines = [];
+    let line = '';
+    for (const word of words) {
+        if (!line) {
+            line = word;
+            continue;
+        }
+        if (line.length + 1 + word.length <= w) {
+            line += ' ' + word;
+        }
+        else {
+            lines.push(line);
+            line = word;
+        }
+    }
+    if (line)
+        lines.push(line);
+    return lines.length > 0 ? lines : [''];
+}
+function formatBodyRow(t, row, isSelected, valueColWidth, inner) {
+    // Selected glyph: `›` lifted from openSrc/grok-cli/src/ui/components/SuggestionOverlay.tsx
+    // (we use ▶ in the LLM-tool picker; switch to › for the internal picker
+    // because it reads cleaner against the chalk gray + bold combo).
+    const marker = isSelected ? t.primary('›') : ' ';
+    const labelFg = row.disabled ? t.dim : isSelected ? t.heading : t.plain;
+    const valueFg = isSelected ? t.muted : t.dim;
+    const label = labelFg(row.label);
+    const value = row.value ? valueFg(row.value) : '';
+    // Layout: " › LABEL ...VALUE"   with value right-aligned.
+    const leftPart = ' ' + marker + ' ' + label;
+    const leftVisible = visibleLength(leftPart);
+    const valueVisible = visibleLength(value);
+    const gapWidth = Math.max(2, inner - leftVisible - valueVisible);
+    const line = leftPart + ' '.repeat(gapWidth) + value;
+    const lines = [line];
+    if (row.description) {
+        const INDENT = '     '; // 5 spaces — aligns under "› LABEL"
+        // Wrap the bare description (no indent) to the inner width MINUS
+        // the indent so the indented line stays inside the frame. Then
+        // re-indent each wrapped line and apply the dim color uniformly.
+        const wrapped = wrap(row.description, Math.max(8, inner - INDENT.length));
+        for (const w of wrapped) {
+            lines.push(INDENT + t.dim(w));
+        }
+    }
+    return lines;
+}
+// --- pickFromList ------------------------------------------------------
+export async function pickFromList(opts) {
+    return runFramedInput(async (frame) => {
+        const theme = opts.theme ?? buildTheme('dark');
+        const augmentedRows = opts.allowOther
+            ? [
+                ...opts.rows,
+                {
+                    id: '__other__',
+                    label: opts.otherLabel ?? 'Other',
+                    description: opts.otherDescription ?? 'Type a free-form answer',
+                },
+            ]
+            : [...opts.rows];
+        let cursor = clamp(opts.initialCursor ?? 0, 0, augmentedRows.length - 1);
+        let phase = opts.prefilledOther !== undefined ? 'other' : 'pick';
+        let otherText = opts.prefilledOther ?? '';
+        let previewLines;
+        // Initial preview if a row is selected on entry.
+        const fireCursorChange = () => {
+            if (opts.onCursorChange && phase === 'pick') {
+                const row = augmentedRows[cursor];
+                if (row && row.id !== '__other__') {
+                    try {
+                        previewLines = opts.onCursorChange(row.id, cursor);
+                    }
+                    catch {
+                        previewLines = undefined;
+                    }
+                }
+                else {
+                    previewLines = undefined;
+                }
+            }
+        };
+        fireCursorChange();
+        const computeFrame = () => {
+            const W = computeWidth(opts.title, augmentedRows, theme);
+            const inner = Math.max(20, W - 4);
+            const bodyLines = [];
+            if (phase === 'pick') {
+                const valueColWidth = computeValueColumn(augmentedRows);
+                for (let i = 0; i < augmentedRows.length; i++) {
+                    const row = augmentedRows[i];
+                    const formatted = formatBodyRow(theme, row, i === cursor, valueColWidth, inner);
+                    bodyLines.push(...formatted);
+                }
+            }
+            else {
+                // Free-text "Other" phase.
+                bodyLines.push(' ' + theme.muted('›') + ' ' + theme.heading('Type your answer'));
+                bodyLines.push('     ' + theme.dim(opts.otherDescription ?? 'Press ENTER to accept · Esc to go back'));
+                bodyLines.push('');
+                const display = otherText.length > 0 ? otherText : theme.dim('(empty)');
+                bodyLines.push('   ' + theme.info('›') + ' ' + display + theme.muted('_'));
+            }
+            const footer = opts.footer ?? defaultFooter(phase, !!opts.allowOther);
+            return renderFrame({
+                theme,
+                title: opts.title,
+                subtitle: opts.subtitle,
+                badge: opts.badge,
+                bodyLines,
+                previewLines,
+                footer,
+                width: W,
+            });
+        };
+        return new Promise((resolve) => {
+            frame.draw(computeFrame());
+            frame.onKey((key, str) => {
+                if (key.ctrl && (key.name === 'c' || key.sequence === '')) {
+                    frame.close();
+                    resolve({ kind: 'cancelled' });
+                    return;
+                }
+                if (phase === 'other') {
+                    if (key.name === 'return') {
+                        const trimmed = otherText.trim();
+                        if (!trimmed)
+                            return; // require non-empty
+                        frame.close();
+                        resolve({ kind: 'other', text: trimmed });
+                        return;
+                    }
+                    if (key.name === 'escape') {
+                        phase = 'pick';
+                        otherText = '';
+                        fireCursorChange();
+                        frame.draw(computeFrame());
+                        return;
+                    }
+                    if (key.name === 'backspace') {
+                        if (otherText.length > 0) {
+                            otherText = otherText.slice(0, -1);
+                            frame.draw(computeFrame());
+                        }
+                        return;
+                    }
+                    if (typeof str === 'string' && str.length === 1 && !key.ctrl && key.name !== 'tab') {
+                        otherText += str;
+                        frame.draw(computeFrame());
+                        return;
+                    }
+                    return;
+                }
+                // pick phase
+                if (key.name === 'up' || (key.name === 'k' && !key.ctrl && !key.meta)) {
+                    cursor = (cursor - 1 + augmentedRows.length) % augmentedRows.length;
+                    while (augmentedRows[cursor].disabled)
+                        cursor = (cursor - 1 + augmentedRows.length) % augmentedRows.length;
+                    fireCursorChange();
+                    frame.draw(computeFrame());
+                    return;
+                }
+                if (key.name === 'down' || (key.name === 'j' && !key.ctrl && !key.meta)) {
+                    cursor = (cursor + 1) % augmentedRows.length;
+                    while (augmentedRows[cursor].disabled)
+                        cursor = (cursor + 1) % augmentedRows.length;
+                    fireCursorChange();
+                    frame.draw(computeFrame());
+                    return;
+                }
+                if (key.name === 'return') {
+                    const row = augmentedRows[cursor];
+                    if (row.disabled)
+                        return;
+                    if (row.id === '__other__') {
+                        phase = 'other';
+                        previewLines = undefined;
+                        frame.draw(computeFrame());
+                        return;
+                    }
+                    frame.close();
+                    resolve({ kind: 'pick', id: row.id });
+                    return;
+                }
+                if (key.name === 'escape' || key.name === 'q') {
+                    frame.close();
+                    resolve({ kind: 'cancelled' });
+                    return;
+                }
+            });
+        });
+    }, { eraseOnClose: opts.eraseOnClose });
+}
+function clamp(n, lo, hi) {
+    if (hi < lo)
+        return lo;
+    return Math.max(lo, Math.min(hi, n));
+}
+function computeValueColumn(rows) {
+    let max = 0;
+    for (const row of rows)
+        if (row.value)
+            max = Math.max(max, visibleLength(row.value));
+    return max;
+}
+function computeWidth(title, rows, _theme) {
+    const terminal = (process.stdout.columns ?? 80);
+    const target = 76;
+    const min = 56;
+    const max = Math.max(min, Math.min(terminal - 4, 100));
+    let widest = visibleLength(title) + 12; // title + badge slack
+    for (const row of rows) {
+        const valueW = row.value ? visibleLength(row.value) : 0;
+        const labelW = visibleLength(row.label);
+        widest = Math.max(widest, labelW + 6 + valueW); // gap + glyph
+        if (row.description)
+            widest = Math.max(widest, visibleLength(row.description) + 6);
+    }
+    return clamp(Math.max(widest + 4, target), min, max);
+}
+function defaultFooter(phase, allowOther) {
+    if (phase === 'other') {
+        return '↵ accept  ·  esc back  ·  ⌫ erase';
+    }
+    return allowOther
+        ? '↑/↓ navigate  ·  ↵ confirm  ·  esc / q cancel'
+        : '↑/↓ navigate  ·  ↵ confirm  ·  esc / q cancel';
+}
+// --- promptText --------------------------------------------------------
+export async function promptText(opts) {
+    return runFramedInput(async (frame) => {
+        const theme = opts.theme ?? buildTheme('dark');
+        let text = opts.prefilled ?? '';
+        let error;
+        const computeFrame = () => {
+            const W = Math.max(60, Math.min((process.stdout.columns ?? 80) - 4, 90));
+            const inner = Math.max(20, W - 4);
+            const bodyLines = [];
+            const visibleText = text.length === 0
+                ? theme.dim(opts.placeholder ?? '(type here)')
+                : opts.mask ? maskInput(text) : text;
+            bodyLines.push('   ' + theme.info('›') + ' ' + visibleText + theme.muted('_'));
+            if (error) {
+                bodyLines.push('');
+                bodyLines.push('   ' + theme.danger('✗ ' + error));
+            }
+            return renderFrame({
+                theme,
+                title: opts.title,
+                subtitle: opts.subtitle,
+                badge: opts.badge,
+                bodyLines,
+                footer: opts.footer ?? '↵ accept  ·  esc cancel  ·  ⌫ erase',
+                width: W,
+            });
+        };
+        return new Promise((resolve) => {
+            frame.draw(computeFrame());
+            frame.onKey((key, str) => {
+                if (key.ctrl && (key.name === 'c' || key.sequence === '')) {
+                    frame.close();
+                    resolve({ kind: 'cancelled' });
+                    return;
+                }
+                if (key.name === 'escape') {
+                    frame.close();
+                    resolve({ kind: 'cancelled' });
+                    return;
+                }
+                if (key.name === 'return') {
+                    const validate = opts.validate;
+                    if (validate) {
+                        const verdict = validate(text);
+                        if (verdict !== undefined) {
+                            error = verdict;
+                            frame.draw(computeFrame());
+                            return;
+                        }
+                    }
+                    frame.close();
+                    resolve({ kind: 'accept', text });
+                    return;
+                }
+                if (key.name === 'backspace') {
+                    if (text.length > 0) {
+                        text = text.slice(0, -1);
+                        error = undefined;
+                        frame.draw(computeFrame());
+                    }
+                    return;
+                }
+                if (typeof str === 'string' && str.length === 1 && !key.ctrl && key.name !== 'tab') {
+                    text += str;
+                    error = undefined;
+                    frame.draw(computeFrame());
+                    return;
+                }
+            });
+        });
+    }, { eraseOnClose: opts.eraseOnClose });
+}
+function maskInput(s) {
+    if (s.length <= 4)
+        return '·'.repeat(s.length);
+    return '·'.repeat(Math.max(4, s.length - 4)) + s.slice(-4);
+}
+/**
+ * Owns stdin / cursor visibility / atomic redraw for the lifetime of a
+ * single picker or prompt. The caller passes a function that returns a
+ * Promise; we manage everything else.
+ *
+ * **Redraw math** — the source of the earlier "frame creeps upward
+ * on every arrow key" bug.
+ *
+ * After writing a frame of M lines separated by M-1 newlines, the
+ * cursor sits at the END of line M (NOT one line below). So to land
+ * back at the START of line 1, we need to move up `M-1` lines, not
+ * `M`. Earlier code used `text.split('\n').length` which is M, off by
+ * one. We now track the newline count directly and use
+ * `\x1b[<newlines>F` (move up + col 1, atomic). When newlines is 0
+ * (single-line frame, edge case), we use `\r\x1b[K` to clear the
+ * single line instead.
+ */
+async function runFramedInput(body, opts = {}) {
+    const stdout = process.stdout;
+    const ownsReadline = !getActiveReadline();
+    let rl;
+    if (ownsReadline) {
+        rl = readline.createInterface({ input: process.stdin, output: process.stdout, terminal: true });
+        setActiveReadline(rl);
+    }
+    else {
+        rl = getActiveReadline();
+        rl.pause();
+    }
+    readline.emitKeypressEvents(process.stdin);
+    try {
+        process.stdin.setRawMode?.(true);
+    }
+    catch { /* not a real TTY */ }
+    process.stdin.resume();
+    stdout.write('\x1b[?25l');
+    internalPickerActive = true;
+    // Number of `\n` chars in the LAST frame we wrote. For an M-line
+    // frame the count is M-1; that's exactly how many lines we need to
+    // move the cursor up to land on the top row.
+    let lastFrameNewlines = 0;
+    let hasDrawn = false;
+    let keyHandler;
+    const eraseLastFrame = () => {
+        if (!hasDrawn)
+            return;
+        if (lastFrameNewlines > 0) {
+            // `\x1b[<n>F` = cursor up n lines AND col 1 (atomic). Then
+            // `\x1b[J` erases from cursor to end of screen. After this the
+            // cursor sits at the top-left of where the previous frame was.
+            stdout.write(`\x1b[${lastFrameNewlines}F\x1b[J`);
+        }
+        else {
+            // Single-line previous frame — just clear the current line in
+            // place. `\r` to col 0, `\x1b[K` erase to end of line.
+            stdout.write('\r\x1b[K');
+        }
+    };
+    const draw = (text) => {
+        eraseLastFrame();
+        if (!hasDrawn) {
+            // First draw — make sure we're at column 0 so the frame top
+            // border doesn't sit mid-line.
+            stdout.write('\r');
+        }
+        stdout.write(text);
+        // Count newlines (NOT lines). `"a\nb\nc".match(/\n/g) → ['\n', '\n']`
+        // → length 2; that's the correct cursor-up count.
+        lastFrameNewlines = (text.match(/\n/g) ?? []).length;
+        hasDrawn = true;
+    };
+    const onKeyInternal = (str, key) => {
+        if (keyHandler)
+            keyHandler(key ?? {}, str);
+    };
+    process.stdin.on('keypress', onKeyInternal);
+    const cleanup = () => {
+        process.stdin.removeListener('keypress', onKeyInternal);
+        stdout.write('\x1b[?25h');
+        if (opts.eraseOnClose !== false) {
+            // Default — erase the last frame entirely so the next step's
+            // frame (or post-picker print) starts at the same screen
+            // position and visually replaces this one. Without this, each
+            // step's cleanup would write `\n` and the next picker would
+            // draw BELOW the previous one, accumulating frames down the
+            // screen on every navigation.
+            eraseLastFrame();
+        }
+        else {
+            // Opt-out: leave the frame on screen as scrollback.
+            stdout.write('\n');
+        }
+        internalPickerActive = false;
+        if (ownsReadline && rl) {
+            setActiveReadline(undefined);
+            try {
+                rl.close();
+            }
+            catch { /* ignore */ }
+        }
+    };
+    const handle = {
+        draw,
+        onKey: (h) => { keyHandler = h; },
+        close: cleanup,
+    };
+    try {
+        const result = await body(handle);
+        return result;
+    }
+    catch (err) {
+        cleanup();
+        throw err;
+    }
+}
+// --- Surface re-exports for tests + callers ---------------------------
+/** Pure helpers exposed for unit tests. */
+export const __test = {
+    renderFrame,
+    formatBodyRow,
+    visibleLength,
+    stripAnsi,
+    wrap,
+    padRightVisible,
+    computeValueColumn,
+    defaultFooter,
+};

package/dist/cli/wizard/providers.d.ts ADDED Viewed

@@ -0,0 +1,86 @@
+/**
+ * 0.3.7 wizard — curated provider catalogue.
+ *
+ * One source of truth for "which LLM providers do we present in the
+ * onboarding picker?" — keeps the wizard step and the `/config` provider
+ * picker in sync. Each entry carries the canonical endpoint, the env-var
+ * name the user is most likely to have set (so we can pre-detect), a
+ * short hint line for the picker, and a curated model short-list.
+ *
+ * Lineage:
+ *   - The "env-var-name as a hint" pattern is borrowed from
+ *     `openSrc/codex/codex-rs/tui/src/onboarding/auth.rs`
+ *     (`ApiKeyInputState.prepopulated_from_env`).
+ *   - The "configured / needs-key / optional-key" row tag is from
+ *     `openSrc/DeepSeek-TUI/crates/tui/src/tui/provider_picker.rs`.
+ *
+ * Adding a provider here makes it appear in the wizard AND the
+ * `/config` panel — no other registration needed.
+ */
+export interface ProviderEntry {
+    /** Stable id used in config.json + tests. */
+    id: string;
+    /** Human-readable picker label. */
+    label: string;
+    /** One-line picker hint shown after the em-dash. */
+    hint: string;
+    /** OpenAI-compatible /v1/chat/completions endpoint. */
+    endpoint: string;
+    /** Env var the wizard checks to pre-detect a usable key. */
+    envKey: string;
+    /** True when the provider runs locally and a blank API key is fine. */
+    local: boolean;
+    /** Curated short-list of model names for the picker (plus "Other"). */
+    models: string[];
+    /** Default model selected by the wizard when none was previously set. */
+    defaultModel: string;
+}
+export declare const PROVIDER_CATALOG: ProviderEntry[];
+/**
+ * Look up a provider entry by stable id. Returns undefined when the id
+ * isn't in the catalog — caller decides whether that's an error
+ * (`/config` reject) or a fallback (custom-endpoint flow).
+ */
+export declare function findProvider(id: string): ProviderEntry | undefined;
+/**
+ * Pre-detect which providers already have a usable key in the shell
+ * environment. Used by the wizard's Provider step to pre-select the
+ * row most likely to "just work". Returns the FIRST hit so first-time
+ * users with multiple keys set don't get a random pick — order in
+ * PROVIDER_CATALOG is the precedence.
+ */
+export declare function detectProviderFromEnv(env?: NodeJS.ProcessEnv): ProviderEntry | undefined;
+/**
+ * 0.3.7 wizard API-key validation tier.
+ *
+ * `Accept` — the key is plausibly fine; persist it as-is.
+ *   - `warning` carries a non-blocking hint (e.g. "unusual prefix —
+ *     check your provider's dashboard if calls fail").
+ * `Reject` — the input is structurally invalid; refuse to persist and
+ *   ask the user to re-enter.
+ *
+ * Pattern lifted from
+ * `openSrc/DeepSeek-TUI/crates/tui/src/tui/onboarding/mod.rs:172`
+ * (`enum ApiKeyValidation { Accept{warning}, Reject(String) }`). The
+ * idea is to warn-not-block on unrecognised key shapes because every
+ * vendor invents new prefixes (`sk-`, `sk-or-v1-`, `dsk-`, `pk-`, …)
+ * and rejecting on shape alone locks users out of legitimate setups.
+ */
+export type ApiKeyValidation = {
+    kind: 'accept';
+    warning?: string;
+} | {
+    kind: 'reject';
+    reason: string;
+};
+export declare function validateApiKey(raw: string, provider: ProviderEntry): ApiKeyValidation;
+/**
+ * Last-four masking for API keys. Visible everywhere the key is
+ * displayed (Done step summary, `/config` panel, `/where` workspace
+ * block). Always keeps a fixed-width tail so two keys with different
+ * lengths align in the panel.
+ *
+ * Borrowed from `openSrc/DeepSeek-TUI/crates/tui/src/tui/onboarding/api_key.rs:77`
+ * (`mask_key()`).
+ */
+export declare function maskApiKey(raw: string): string;