@compilr-dev/cli 0.5.0 → 0.5.1

package/dist/ui/overlay/impl/onboarding-wizard-overlay-v2.js

@@ -0,0 +1,728 @@
+/**
+ * Onboarding Wizard Overlay V2
+ *
+ * First-run wizard that guides new users through initial CLI setup.
+ * Shown automatically on first launch, or manually via /init command.
+ *
+ * Steps (when running in VS Code):
+ *   1. Welcome - Introduction to the CLI
+ *   2. Telemetry - Opt-in/opt-out for anonymous usage data
+ *   3. VS Code Diff - Enable side-by-side diff view (VS Code only)
+ *   4. API Key Check - Configure LLM API keys (opens /keys overlay)
+ *   5. Git Config - Configure git user.name and user.email
+ *   6. Projects Path - Set default projects folder location
+ *   7. COMPILR.md Intro - Explain project memory files
+ *   8. Quick Tour - Overview of key commands
+ *   9. Complete - Finish setup
+ *
+ * When NOT in VS Code, step 3 is skipped (8 steps total).
+ *
+ * This is an interactive wizard where users can actually configure settings,
+ * not just view status screens.
+ */
+import { BaseOverlayV2, renderBorder } from '../../base/index.js';
+import { hasApiKey } from '../../../utils/credentials.js';
+import { checkGitConfig, setGitConfigValue } from '../../../utils/git-config.js';
+import { completeFirstRun, setSetting } from '../../../settings/index.js';
+import { getProjectsPath, setProjectsPath } from '../../../settings/paths.js';
+import { isInVSCode, ensureExtensionInstalled } from '../../../utils/vscode-detect.js';
+import { InputFeature } from '../../features/index.js';
+import * as terminal from '../../terminal.js';
+// =============================================================================
+// Constants
+// =============================================================================
+/** Total steps depends on whether VS Code step is shown */
+function getTotalSteps(showVSCodeStep) {
+    return showVSCodeStep ? 9 : 8;
+}
+/**
+ * Map numeric step to logical step name based on whether VS Code step is present.
+ */
+function getLogicalStep(step, showVSCodeStep) {
+    if (showVSCodeStep) {
+        // 9-step flow: 1=welcome, 2=telemetry, 3=vscode-diff, 4=api-keys, ...
+        switch (step) {
+            case 1: return 'welcome';
+            case 2: return 'telemetry';
+            case 3: return 'vscode-diff';
+            case 4: return 'api-keys';
+            case 5: return 'git-config';
+            case 6: return 'paths';
+            case 7: return 'compilr-md';
+            case 8: return 'quick-tour';
+            case 9: return 'complete';
+        }
+    }
+    // 8-step flow (no VS Code): 1=welcome, 2=telemetry, 3=api-keys, ...
+    switch (step) {
+        case 1: return 'welcome';
+        case 2: return 'telemetry';
+        case 3: return 'api-keys';
+        case 4: return 'git-config';
+        case 5: return 'paths';
+        case 6: return 'compilr-md';
+        case 7: return 'quick-tour';
+        case 8: return 'complete';
+        default: return 'complete';
+    }
+}
+const PROVIDER_NAMES = {
+    anthropic: 'Anthropic (Claude)',
+    openai: 'OpenAI',
+    google: 'Google AI (Gemini)',
+    ollama: 'Ollama (Local)',
+    together: 'Together AI',
+    groq: 'Groq',
+    fireworks: 'Fireworks AI',
+    perplexity: 'Perplexity',
+    openrouter: 'OpenRouter',
+};
+// =============================================================================
+// Onboarding Wizard Overlay V2
+// =============================================================================
+export class OnboardingWizardOverlayV2 extends BaseOverlayV2 {
+    type = 'inline';
+    id = 'onboarding-wizard-overlay-v2';
+    // Input features for different input modes
+    gitNameInput;
+    gitEmailInput;
+    pathInput;
+    constructor() {
+        // Check API key status
+        const providers = ['anthropic', 'openai', 'google', 'ollama'];
+        const configuredProviders = [];
+        for (const provider of providers) {
+            if (hasApiKey(provider)) {
+                configuredProviders.push(PROVIDER_NAMES[provider]);
+            }
+        }
+        // Check git config
+        const gitConfig = checkGitConfig();
+        // Get paths
+        const projectsPath = getProjectsPath();
+        const showVSCodeStep = isInVSCode();
+        super({
+            step: 1,
+            selectedIndex: 0,
+            hasAnyKey: configuredProviders.length > 0,
+            configuredProviders,
+            gitConfig,
+            projectsPath,
+            inputMode: 'none',
+            pendingGitName: gitConfig.userName ?? '',
+            pendingGitEmail: gitConfig.userEmail ?? '',
+            showVSCodeStep,
+        });
+        // Initialize input features
+        this.gitNameInput = new InputFeature({
+            placeholder: 'Your Name',
+            initialValue: gitConfig.userName ?? '',
+        });
+        this.gitEmailInput = new InputFeature({
+            placeholder: 'you@example.com',
+            initialValue: gitConfig.userEmail ?? '',
+        });
+        this.pathInput = new InputFeature({
+            placeholder: projectsPath,
+            initialValue: projectsPath,
+        });
+        this.minHeight = 22;
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    renderContent(context) {
+        const s = context.styles;
+        const cols = terminal.getTerminalWidth();
+        const border = renderBorder(cols, s);
+        const lines = [];
+        const totalSteps = getTotalSteps(this.state.showVSCodeStep);
+        const logicalStep = getLogicalStep(this.state.step, this.state.showVSCodeStep);
+        // Header
+        lines.push(border);
+        lines.push(`  ${s.primaryBold('Welcome to compilr-dev')} ${s.muted(`[${String(this.state.step)}/${String(totalSteps)}]`)}`);
+        lines.push(border);
+        lines.push('');
+        // Step content based on logical step
+        switch (logicalStep) {
+            case 'welcome':
+                lines.push(...this.renderStepWelcome(s));
+                break;
+            case 'telemetry':
+                lines.push(...this.renderStepTelemetry(s));
+                break;
+            case 'vscode-diff':
+                lines.push(...this.renderStepVSCodeDiff(s));
+                break;
+            case 'api-keys':
+                lines.push(...this.renderStepApiKeys(s));
+                break;
+            case 'git-config':
+                lines.push(...this.renderStepGitConfig(s));
+                break;
+            case 'paths':
+                lines.push(...this.renderStepPaths(s));
+                break;
+            case 'compilr-md':
+                lines.push(...this.renderStepCompilrMd(s));
+                break;
+            case 'quick-tour':
+                lines.push(...this.renderStepQuickTour(s));
+                break;
+            case 'complete':
+                lines.push(...this.renderStepComplete(s));
+                break;
+        }
+        // Footer
+        lines.push('');
+        lines.push(border);
+        lines.push(this.getStepFooter(s));
+        lines.push(border);
+        return lines;
+    }
+    getStepFooter(s) {
+        // Input mode footers
+        if (this.state.inputMode !== 'none') {
+            return s.muted('  Enter Confirm | Esc Cancel');
+        }
+        const logicalStep = getLogicalStep(this.state.step, this.state.showVSCodeStep);
+        const totalSteps = getTotalSteps(this.state.showVSCodeStep);
+        if (this.state.step === totalSteps) {
+            return s.muted('  Enter Finish | Esc Back');
+        }
+        switch (logicalStep) {
+            case 'welcome':
+                return s.muted('  Press Enter to continue');
+            case 'telemetry':
+            case 'vscode-diff':
+                return s.muted('  Up/Down Navigate | Enter Continue | Esc Back');
+            case 'api-keys':
+                if (this.state.hasAnyKey) {
+                    return s.muted('  Enter Continue | Esc Back');
+                }
+                return s.muted('  Up/Down Navigate | Enter Select | Esc Back');
+            case 'git-config':
+                if (this.state.gitConfig.isConfigured) {
+                    return s.muted('  Enter Continue | Esc Back');
+                }
+                return s.muted('  Up/Down Navigate | Enter Select | Esc Back');
+            case 'paths':
+                return s.muted('  Up/Down Navigate | Enter Select | Esc Back');
+            case 'compilr-md':
+            case 'quick-tour':
+                return s.muted('  Enter Continue | Esc Back');
+            default:
+                return '';
+        }
+    }
+    // ===========================================================================
+    // Step Renderers
+    // ===========================================================================
+    renderStepWelcome(s) {
+        const lines = [];
+        lines.push(`  ${s.primary('AI-powered coding assistant for the terminal')}`);
+        lines.push('');
+        lines.push('  This quick setup will help you configure:');
+        lines.push('');
+        let stepNum = 1;
+        lines.push(`  ${s.secondary(`${String(stepNum++)}.`)} Telemetry preferences`);
+        if (this.state.showVSCodeStep) {
+            lines.push(`  ${s.secondary(`${String(stepNum++)}.`)} VS Code diff integration`);
+        }
+        lines.push(`  ${s.secondary(`${String(stepNum++)}.`)} LLM API keys (Claude, GPT-4, Gemini, Ollama)`);
+        lines.push(`  ${s.secondary(`${String(stepNum++)}.`)} Git user configuration`);
+        lines.push(`  ${s.secondary(`${String(stepNum++)}.`)} Default projects folder`);
+        lines.push(`  ${s.secondary(`${String(stepNum)}.`)} Project memory files (COMPILR.md)`);
+        lines.push('');
+        lines.push(s.muted('  You can skip any step and configure later with /config.'));
+        return lines;
+    }
+    renderStepTelemetry(s) {
+        const lines = [];
+        lines.push(`  ${s.secondary('Telemetry Preferences')}`);
+        lines.push('');
+        lines.push('  Help improve compilr by sharing anonymous usage data:');
+        lines.push('');
+        lines.push(`    ${s.muted('•')} Commands used (not their arguments)`);
+        lines.push(`    ${s.muted('•')} Session duration`);
+        lines.push(`    ${s.muted('•')} Error counts`);
+        lines.push('');
+        lines.push(`  We ${s.primaryBold('never')} collect: code, file contents, prompts, or personal data.`);
+        lines.push('');
+        lines.push(this.renderOption(s, 0, 'Enable anonymous telemetry (recommended)'));
+        lines.push(this.renderOption(s, 1, 'Disable telemetry'));
+        return lines;
+    }
+    renderStepVSCodeDiff(s) {
+        const lines = [];
+        lines.push(`  ${s.secondary('VS Code Diff Integration')}`);
+        lines.push('');
+        lines.push('  When the AI proposes file edits, open a side-by-side diff');
+        lines.push('  view in VS Code alongside the terminal prompt.');
+        lines.push('');
+        lines.push(`    ${s.muted('•')} See exactly what will change before accepting`);
+        lines.push(`    ${s.muted('•')} Accept or reject from VS Code or terminal`);
+        lines.push(`    ${s.muted('•')} Installs a companion VS Code extension`);
+        lines.push('');
+        lines.push(this.renderOption(s, 0, 'Enable VS Code diff view (recommended)'));
+        lines.push(this.renderOption(s, 1, 'Skip for now'));
+        lines.push('');
+        lines.push(s.muted('  You can change this later with /config.'));
+        return lines;
+    }
+    renderStepApiKeys(s) {
+        const lines = [];
+        lines.push(`  ${s.secondary('Step 2: LLM API Keys')}`);
+        lines.push('');
+        if (this.state.hasAnyKey) {
+            lines.push(`  ${s.success('✓')} You have API keys configured:`);
+            lines.push('');
+            for (const provider of this.state.configuredProviders) {
+                lines.push(`    ${s.success('●')} ${provider}`);
+            }
+            lines.push('');
+            lines.push(s.muted('  You can manage keys anytime with /keys'));
+        }
+        else {
+            lines.push(`  ${s.warning('⚠')} No API keys found.`);
+            lines.push('');
+            lines.push('  You need at least one API key to use the AI assistant.');
+            lines.push('');
+            lines.push(this.renderOption(s, 0, 'Configure API keys now'));
+            lines.push(this.renderOption(s, 1, 'Skip for now'));
+            lines.push('');
+            lines.push(s.muted('  Tip: Set ANTHROPIC_API_KEY in your environment'));
+        }
+        return lines;
+    }
+    renderStepGitConfig(s) {
+        const lines = [];
+        const { gitConfig, inputMode } = this.state;
+        lines.push(`  ${s.secondary('Step 3: Git Configuration')}`);
+        lines.push('');
+        // Input mode: entering git name
+        if (inputMode === 'git-name') {
+            lines.push('  Enter your name for git commits:');
+            lines.push('');
+            lines.push('  ' + this.gitNameInput.render(s));
+            return lines;
+        }
+        // Input mode: entering git email
+        if (inputMode === 'git-email') {
+            lines.push(`  ${s.success('✓')} Name: ${this.state.pendingGitName}`);
+            lines.push('');
+            lines.push('  Enter your email for git commits:');
+            lines.push('');
+            lines.push('  ' + this.gitEmailInput.render(s));
+            return lines;
+        }
+        // Normal mode: show status
+        if (gitConfig.isConfigured) {
+            lines.push(`  ${s.success('✓')} Git is configured:`);
+            lines.push('');
+            lines.push(`    ${s.muted('Name:')}  ${gitConfig.userName ?? ''}`);
+            lines.push(`    ${s.muted('Email:')} ${gitConfig.userEmail ?? ''}`);
+            lines.push('');
+            lines.push(s.muted('  Press Enter to continue'));
+        }
+        else {
+            lines.push(`  ${s.warning('⚠')} Git user config is incomplete.`);
+            lines.push('');
+            if (gitConfig.userName) {
+                lines.push(`    ${s.success('✓')} Name:  ${gitConfig.userName}`);
+            }
+            else {
+                lines.push(`    ${s.warning('○')} Name:  ${s.muted('not set')}`);
+            }
+            if (gitConfig.userEmail) {
+                lines.push(`    ${s.success('✓')} Email: ${gitConfig.userEmail}`);
+            }
+            else {
+                lines.push(`    ${s.warning('○')} Email: ${s.muted('not set')}`);
+            }
+            lines.push('');
+            lines.push(this.renderOption(s, 0, 'Configure git now'));
+            lines.push(this.renderOption(s, 1, 'Skip for now'));
+        }
+        return lines;
+    }
+    renderStepPaths(s) {
+        const lines = [];
+        const { inputMode, projectsPath } = this.state;
+        lines.push(`  ${s.secondary('Step 4: Projects Folder')}`);
+        lines.push('');
+        // Input mode: editing path
+        if (inputMode === 'projects-path') {
+            lines.push('  Enter projects folder path:');
+            lines.push('');
+            lines.push('  ' + this.pathInput.render(s));
+            lines.push('');
+            lines.push(s.muted('  New projects will be created in this folder.'));
+            return lines;
+        }
+        // Normal mode: show current path with options
+        lines.push('  New projects will be created in:');
+        lines.push('');
+        lines.push(`    ${s.primary(projectsPath)}`);
+        lines.push('');
+        lines.push(this.renderOption(s, 0, 'Keep this path'));
+        lines.push(this.renderOption(s, 1, 'Change path'));
+        return lines;
+    }
+    renderStepCompilrMd(s) {
+        const lines = [];
+        lines.push(`  ${s.secondary('Step 5: Project Memory (COMPILR.md)')}`);
+        lines.push('');
+        lines.push('  Create a COMPILR.md file in your project root to give the');
+        lines.push('  AI assistant context about your codebase.');
+        lines.push('');
+        lines.push(`  ${s.primary('What to include:')}`);
+        lines.push('');
+        lines.push(`    ${s.muted('•')} Project overview and architecture`);
+        lines.push(`    ${s.muted('•')} Key files and directories`);
+        lines.push(`    ${s.muted('•')} Coding conventions and patterns`);
+        lines.push(`    ${s.muted('•')} Build and test commands`);
+        lines.push(`    ${s.muted('•')} Important context the AI should know`);
+        lines.push('');
+        lines.push(s.muted('  The AI reads this file automatically when you work in the'));
+        lines.push(s.muted('  project. It also supports CLAUDE.md and AGENTS.md.'));
+        return lines;
+    }
+    renderStepQuickTour(s) {
+        const lines = [];
+        lines.push(`  ${s.secondary('Quick Tour')}`);
+        lines.push('');
+        lines.push('  Here are the key commands to get started:');
+        lines.push('');
+        lines.push(`    ${s.primary('/menu')}      Dashboard - select projects, settings`);
+        lines.push(`    ${s.primary('/new')}       Create a new project with scaffolding`);
+        lines.push(`    ${s.primary('/help')}      Show all available commands`);
+        lines.push(`    ${s.primary('/config')}    Customize settings and preferences`);
+        lines.push(`    ${s.primary('/keys')}      Manage LLM API keys`);
+        lines.push('');
+        lines.push(s.muted('  Just type naturally to chat with the AI assistant.'));
+        return lines;
+    }
+    renderStepComplete(s) {
+        const lines = [];
+        lines.push(`  ${s.success('✓')} Setup complete!`);
+        lines.push('');
+        // Summary of what was configured
+        const configured = [];
+        if (this.state.hasAnyKey) {
+            configured.push('API keys');
+        }
+        if (this.state.gitConfig.isConfigured) {
+            configured.push('Git config');
+        }
+        configured.push('Projects path');
+        if (configured.length > 0) {
+            lines.push(`  Configured: ${configured.join(', ')}`);
+            lines.push('');
+        }
+        if (this.state.hasAnyKey) {
+            lines.push("  You're ready to start coding! Try:");
+            lines.push('');
+            lines.push(`    • Type a question to chat with the AI`);
+            lines.push(`    • Run ${s.primary('/new')} to create a project`);
+            lines.push(`    • Run ${s.primary('/help')} to see all commands`);
+        }
+        else {
+            lines.push("  Almost there! You'll need an API key to use the AI.");
+            lines.push('');
+            lines.push(`    • Run ${s.primary('/keys')} to add your API key`);
+            lines.push(`    • Or set ANTHROPIC_API_KEY in your environment`);
+        }
+        lines.push('');
+        lines.push(s.muted('  Run /init anytime to see this wizard again.'));
+        return lines;
+    }
+    renderOption(s, index, label) {
+        const isSelected = this.state.selectedIndex === index;
+        const prefix = isSelected ? ' > ' : '   ';
+        return isSelected ? s.primary(prefix + label) : s.muted(prefix + label);
+    }
+    // ===========================================================================
+    // Key Handling
+    // ===========================================================================
+    handleKey(key) {
+        // Ctrl+C always cancels
+        if (this.isInterruptKey(key)) {
+            return this.close({ completed: false });
+        }
+        // Handle input modes
+        if (this.state.inputMode !== 'none') {
+            return this.handleInputMode(key);
+        }
+        // Escape: first step cancels, otherwise goes back
+        if (key.name === 'escape') {
+            if (this.state.step === 1) {
+                return this.close({ completed: false });
+            }
+            this.prevStep();
+            return this.rerender();
+        }
+        // Step-specific handling
+        const logicalStep = getLogicalStep(this.state.step, this.state.showVSCodeStep);
+        switch (logicalStep) {
+            case 'telemetry':
+                return this.handleTelemetrySelection(key);
+            case 'vscode-diff':
+                return this.handleVSCodeDiffSelection(key);
+            case 'api-keys':
+                if (!this.state.hasAnyKey) {
+                    return this.handleApiKeysSelection(key);
+                }
+                break;
+            case 'git-config':
+                if (!this.state.gitConfig.isConfigured) {
+                    return this.handleGitConfigSelection(key);
+                }
+                break;
+            case 'paths':
+                return this.handlePathsSelection(key);
+        }
+        // Enter advances to next step
+        if (this.isEnterKey(key)) {
+            return this.handleEnter();
+        }
+        return this.noAction();
+    }
+    handleInputMode(key) {
+        const { inputMode } = this.state;
+        // Escape cancels input and goes back to selection
+        if (key.name === 'escape') {
+            terminal.hideCursor();
+            this.state.inputMode = 'none';
+            this.state.selectedIndex = 0;
+            return this.rerender();
+        }
+        // Enter confirms input
+        if (this.isEnterKey(key)) {
+            return this.confirmInput();
+        }
+        // Get the current input feature
+        let input;
+        switch (inputMode) {
+            case 'git-name':
+                input = this.gitNameInput;
+                break;
+            case 'git-email':
+                input = this.gitEmailInput;
+                break;
+            case 'projects-path':
+                input = this.pathInput;
+                break;
+            default:
+                return this.noAction();
+        }
+        // Let InputFeature handle the key
+        const result = input.handleKey(key.raw);
+        if (result.handled && result.render) {
+            return this.rerender();
+        }
+        return this.noAction();
+    }
+    confirmInput() {
+        const { inputMode } = this.state;
+        terminal.hideCursor();
+        switch (inputMode) {
+            case 'git-name': {
+                const name = this.gitNameInput.trimmedValue;
+                if (name) {
+                    this.state.pendingGitName = name;
+                    // Move to email input
+                    this.state.inputMode = 'git-email';
+                    terminal.showCursor();
+                    return this.rerender();
+                }
+                // Empty name - stay in input mode
+                return this.noAction();
+            }
+            case 'git-email': {
+                const email = this.gitEmailInput.trimmedValue;
+                if (email) {
+                    // Save both git config values
+                    setGitConfigValue('user.name', this.state.pendingGitName);
+                    setGitConfigValue('user.email', email);
+                    // Refresh git config state
+                    this.state.gitConfig = checkGitConfig();
+                    this.state.inputMode = 'none';
+                    // Move to next step
+                    this.nextStep();
+                    return this.rerender();
+                }
+                // Empty email - stay in input mode
+                return this.noAction();
+            }
+            case 'projects-path': {
+                const path = this.pathInput.trimmedValue;
+                if (path) {
+                    setProjectsPath(path);
+                    this.state.projectsPath = path;
+                }
+                this.state.inputMode = 'none';
+                // Move to next step
+                this.nextStep();
+                return this.rerender();
+            }
+            default:
+                this.state.inputMode = 'none';
+                return this.rerender();
+        }
+    }
+    handleTelemetrySelection(key) {
+        // Navigation
+        if ((this.isUpKey(key) || key.name === 'k') && this.state.selectedIndex > 0) {
+            this.state.selectedIndex--;
+            return this.rerender();
+        }
+        if ((this.isDownKey(key) || key.name === 'j') && this.state.selectedIndex < 1) {
+            this.state.selectedIndex++;
+            return this.rerender();
+        }
+        // Enter to confirm selection and continue
+        if (this.isEnterKey(key)) {
+            // 0 = enable (recommended), 1 = disable
+            setSetting('telemetryEnabled', this.state.selectedIndex === 0);
+            this.nextStep();
+            return this.rerender();
+        }
+        return this.noAction();
+    }
+    handleVSCodeDiffSelection(key) {
+        // Navigation
+        if ((this.isUpKey(key) || key.name === 'k') && this.state.selectedIndex > 0) {
+            this.state.selectedIndex--;
+            return this.rerender();
+        }
+        if ((this.isDownKey(key) || key.name === 'j') && this.state.selectedIndex < 1) {
+            this.state.selectedIndex++;
+            return this.rerender();
+        }
+        // Enter to confirm selection and continue
+        if (this.isEnterKey(key)) {
+            if (this.state.selectedIndex === 0) {
+                // Enable VS Code diff + install extension
+                setSetting('vsDiffExtension', true);
+                void ensureExtensionInstalled().then(result => {
+                    if (result.needsReload) {
+                        process.stderr.write('\n  \x1b[33m⚠ VS Code diff extension installed.\x1b[0m\n' +
+                            '  \x1b[2mReload VS Code window (Ctrl+Shift+P → "Developer: Reload Window") to activate.\x1b[0m\n\n');
+                    }
+                });
+            }
+            // Both options proceed to next step
+            this.nextStep();
+            return this.rerender();
+        }
+        return this.noAction();
+    }
+    handleApiKeysSelection(key) {
+        // Navigation
+        if ((this.isUpKey(key) || key.name === 'k') && this.state.selectedIndex > 0) {
+            this.state.selectedIndex--;
+            return this.rerender();
+        }
+        if ((this.isDownKey(key) || key.name === 'j') && this.state.selectedIndex < 1) {
+            this.state.selectedIndex++;
+            return this.rerender();
+        }
+        // Enter to select
+        if (this.isEnterKey(key)) {
+            if (this.state.selectedIndex === 0) {
+                // Open /keys overlay
+                return this.close({ completed: false, openKeys: true });
+            }
+            // Skip - continue to next step
+            this.nextStep();
+            return this.rerender();
+        }
+        return this.noAction();
+    }
+    handleGitConfigSelection(key) {
+        // Navigation
+        if ((this.isUpKey(key) || key.name === 'k') && this.state.selectedIndex > 0) {
+            this.state.selectedIndex--;
+            return this.rerender();
+        }
+        if ((this.isDownKey(key) || key.name === 'j') && this.state.selectedIndex < 1) {
+            this.state.selectedIndex++;
+            return this.rerender();
+        }
+        // Enter to select
+        if (this.isEnterKey(key)) {
+            if (this.state.selectedIndex === 0) {
+                // Start git config input
+                this.state.inputMode = 'git-name';
+                terminal.showCursor();
+                return this.rerender();
+            }
+            // Skip - continue to next step
+            this.nextStep();
+            return this.rerender();
+        }
+        return this.noAction();
+    }
+    handlePathsSelection(key) {
+        // Navigation
+        if ((this.isUpKey(key) || key.name === 'k') && this.state.selectedIndex > 0) {
+            this.state.selectedIndex--;
+            return this.rerender();
+        }
+        if ((this.isDownKey(key) || key.name === 'j') && this.state.selectedIndex < 1) {
+            this.state.selectedIndex++;
+            return this.rerender();
+        }
+        // Enter to select
+        if (this.isEnterKey(key)) {
+            if (this.state.selectedIndex === 0) {
+                // Keep path - continue to next step
+                this.nextStep();
+                return this.rerender();
+            }
+            // Change path - enter input mode
+            this.state.inputMode = 'projects-path';
+            terminal.showCursor();
+            return this.rerender();
+        }
+        return this.noAction();
+    }
+    handleEnter() {
+        const totalSteps = getTotalSteps(this.state.showVSCodeStep);
+        if (this.state.step === totalSteps) {
+            // Complete the wizard
+            completeFirstRun();
+            return this.close({ completed: true });
+        }
+        this.nextStep();
+        return this.rerender();
+    }
+    nextStep() {
+        const totalSteps = getTotalSteps(this.state.showVSCodeStep);
+        if (this.state.step < totalSteps) {
+            this.state.step = (this.state.step + 1);
+            this.state.selectedIndex = 0;
+        }
+    }
+    prevStep() {
+        if (this.state.step > 1) {
+            this.state.step = (this.state.step - 1);
+            this.state.selectedIndex = 0;
+        }
+    }
+    // ===========================================================================
+    // Close Summary
+    // ===========================================================================
+    getCloseSummary(result) {
+        const s = this.getStyles();
+        if (result.completed) {
+            // No summary — avoids a flash before /menu opens
+            return null;
+        }
+        if (result.openKeys) {
+            return null; // Will open /keys overlay next
+        }
+        return s.muted('Setup cancelled. Run /init to complete setup later.');
+    }
+}