@compilr-dev/cli 0.4.0 → 0.5.1

package/dist/ui/overlay/impl/config-overlay-v2.js

@@ -0,0 +1,718 @@
+/**
+ * Config Overlay V2
+ *
+ * Claude Code-style settings overlay with 4 tabs:
+ * - Status: Read-only info (version, model, provider, cwd, session)
+ * - Config: Interactive settings (toggle/cycle with Enter/Space)
+ * - Paths: Path configuration and safety settings
+ * - Usage: Usage statistics with progress bars
+ *
+ * Theme, Model, and Mascot selection are delegated to standalone overlays.
+ * Uses BaseOverlayV2 for the new Overlay interface.
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import { execSync } from 'child_process';
+import { BaseOverlayV2, isEscape, isTab, isShiftTab, isEnter, isSpace, isCtrlC, isNavigateUp, isNavigateDown, isBackspace, getNumberKey, isPrintable, extractPrintable, renderProgressBar, formatTokens, truncate, } from '../../base/index.js';
+import { getCurrentTheme, } from '../../../themes/index.js';
+import { getSettings, setSetting, permissionModeToDisplay, displayToPermissionMode, notificationModeToDisplay, displayToNotificationMode, projectStartupModeToDisplay, displayToProjectStartupMode, projectSessionModeToDisplay, displayToProjectSessionMode, sessionRetentionToDisplay, displayToSessionRetention, compactModeToDisplay, displayToCompactMode, } from '../../../settings/index.js';
+import { getResolvedPathConfig, setDeleteProtection, setProjectMatchRequired, setWorkspacePath, setProjectsPath, setDataPath, } from '../../../settings/paths.js';
+import { MASCOT_LABELS, } from '../../mascot/index.js';
+import { ThemeOverlayV2 } from './theme-overlay-v2.js';
+import { ModelOverlayV2 } from './model-overlay-v2.js';
+import { MascotOverlayV2 } from './mascot-overlay-v2.js';
+import { getDefaultModelsForUI } from '../../../models/index.js';
+import { isInVSCode, ensureExtensionInstalled } from '../../../utils/vscode-detect.js';
+// =============================================================================
+// Constants
+// =============================================================================
+const VERSION = '0.4.0';
+const TARGET_HEIGHT = 25;
+const TABS = [
+    { id: 'status', label: 'Status' },
+    { id: 'config', label: 'Config' },
+    { id: 'paths', label: 'Environment' },
+    { id: 'usage', label: 'Usage' },
+];
+// =============================================================================
+// Model Options (from registry - single source of truth)
+// =============================================================================
+// Get model options from registry for display name lookup
+function getModelOptions() {
+    return getDefaultModelsForUI();
+}
+// =============================================================================
+// Helper Functions
+// =============================================================================
+function generateSessionId() {
+    const chars = '0123456789abcdef';
+    let id = '';
+    for (let i = 0; i < 8; i++) {
+        id += chars[Math.floor(Math.random() * chars.length)];
+    }
+    id += '-';
+    for (let i = 0; i < 4; i++) {
+        id += chars[Math.floor(Math.random() * chars.length)];
+    }
+    id += '-';
+    for (let i = 0; i < 4; i++) {
+        id += chars[Math.floor(Math.random() * chars.length)];
+    }
+    id += '-';
+    for (let i = 0; i < 12; i++) {
+        id += chars[Math.floor(Math.random() * chars.length)];
+    }
+    return id;
+}
+function findMemoryFile(cwd) {
+    const dir = cwd || process.cwd();
+    const candidates = [
+        'COMPILR.md',
+        '.compilr/instructions.md',
+        'CLAUDE.md',
+        '.claude/instructions.md',
+        'AGENTS.md',
+    ];
+    for (const candidate of candidates) {
+        const fullPath = path.join(dir, candidate);
+        if (fs.existsSync(fullPath)) {
+            return fullPath;
+        }
+    }
+    return null;
+}
+/**
+ * Get git config value, returns null if not set
+ */
+function getGitConfigValue(key) {
+    try {
+        const value = execSync(`git config --global ${key}`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        }).trim();
+        return value || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Set git config value
+ */
+function setGitConfigValue(key, value) {
+    try {
+        execSync(`git config --global ${key} "${value.replace(/"/g, '\\"')}"`, {
+            encoding: 'utf-8',
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function getConfigItems(currentModel) {
+    const currentTheme = getCurrentTheme();
+    const settings = getSettings();
+    // Find display name for current model (from registry)
+    const modelOptions = getModelOptions();
+    const modelOption = modelOptions.find(m => m.id === currentModel);
+    const modelDisplay = modelOption ? modelOption.name : currentModel || 'Default';
+    return [
+        { id: 'autoCompact', label: 'Auto-compact', type: 'boolean', value: settings.autoCompact },
+        { id: 'delegation', label: 'Auto-delegate large results', type: 'boolean', value: settings.delegation },
+        // VS Code diff toggle — only visible when running inside VS Code
+        ...(isInVSCode() ? [{ id: 'vsDiffExtension', label: 'VS Code diff view', type: 'boolean', value: settings.vsDiffExtension }] : []),
+        { id: 'compactMode', label: 'Default compact mode', type: 'cycle', value: compactModeToDisplay(settings.compactMode), options: ['Active agent', 'All agents', 'Auto (>70%)'] },
+        // TODO: Implement show tips feature
+        // { id: 'showTips', label: 'Show tips', type: 'boolean', value: settings.showTips },
+        // TODO: Implement checkpoints/rewind feature (Claude Code v2.0)
+        // { id: 'reviseCode', label: 'Revise code (checkpoints)', type: 'boolean', value: settings.reviseCode },
+        { id: 'verbose', label: 'Verbose output', type: 'boolean', value: settings.verbose },
+        { id: 'progressBar', label: 'Terminal progress bar', type: 'boolean', value: settings.progressBar },
+        {
+            id: 'permissionMode',
+            label: 'Default permission mode',
+            type: 'cycle',
+            value: permissionModeToDisplay(settings.permissionMode),
+            options: ['Default', 'Plan mode', 'Accept edits', "Don't ask"],
+        },
+        { id: 'theme', label: 'Theme', type: 'submenu', value: currentTheme.name },
+        { id: 'model', label: 'Model', type: 'submenu', value: modelDisplay },
+        {
+            id: 'notifications',
+            label: 'Terminal notifications',
+            type: 'cycle',
+            value: notificationModeToDisplay(settings.notifications),
+            options: ['Auto', 'Terminal Bell', 'Disabled'],
+        },
+        { id: 'checkUpdates', label: 'Check for updates on startup', type: 'boolean', value: settings.checkUpdates },
+        {
+            id: 'startupMode',
+            label: 'Startup behavior',
+            type: 'cycle',
+            value: settings.startupMode === 'menu' ? 'Show menu' : 'Direct to REPL',
+            options: ['Show menu', 'Direct to REPL'],
+        },
+        {
+            id: 'projectStartup',
+            label: 'Auto-open project',
+            type: 'cycle',
+            value: projectStartupModeToDisplay(settings.projectStartup),
+            options: ['Last opened', 'Off'],
+        },
+        {
+            id: 'projectSessionMode',
+            label: 'Session restore mode',
+            type: 'cycle',
+            value: projectSessionModeToDisplay(settings.projectSessionMode),
+            options: ['Auto', 'Ask', 'Fresh'],
+        },
+        {
+            id: 'sessionRetentionDays',
+            label: 'Session history retention',
+            type: 'cycle',
+            value: sessionRetentionToDisplay(settings.sessionRetentionDays),
+            options: ['7 days', '14 days', '30 days', '60 days', '90 days', 'Forever'],
+        },
+        { id: 'mascot', label: 'Mascot', type: 'submenu', value: MASCOT_LABELS[settings.mascot] },
+    ];
+}
+// =============================================================================
+// Config Overlay V2 Class
+// =============================================================================
+export class ConfigOverlayV2 extends BaseOverlayV2 {
+    type = 'inline';
+    id = 'config-overlay-v2';
+    minHeight = TARGET_HEIGHT;
+    settingsChanged = false;
+    constructor(options = {}) {
+        super({
+            currentTab: 1, // Start on Config tab (like Claude Code)
+            selectedItem: 0,
+            scrollOffset: 0,
+            // Path settings state
+            pathSelectedItem: 0,
+            pathEditMode: false,
+            pathEditInput: '',
+            configItems: getConfigItems(options.model),
+            statusInfo: {
+                version: options.version || VERSION,
+                sessionId: options.sessionId || generateSessionId(),
+                cwd: options.cwd || process.cwd(),
+                model: options.model || 'unknown',
+                provider: options.provider || 'unknown',
+                toolCount: options.toolCount ?? 0,
+                directToolCount: options.directToolCount,
+                metaToolCount: options.metaToolCount,
+                hasTeam: options.hasTeam,
+                startTime: options.startTime || new Date(),
+                memoryFile: findMemoryFile(options.cwd),
+            },
+            usageStats: {
+                inputTokens: options.inputTokens ?? 0,
+                outputTokens: options.outputTokens ?? 0,
+                requests: options.requests ?? 0,
+                contextUsed: options.contextUsed ?? 0,
+                contextMax: options.contextMax ?? 200000,
+                messageCount: options.messageCount ?? 0,
+            },
+        });
+    }
+    // ===========================================================================
+    // Rendering
+    // ===========================================================================
+    renderContent(context) {
+        const lines = [];
+        lines.push(...this.renderTabHeader(context));
+        switch (TABS[this.state.currentTab].id) {
+            case 'status':
+                lines.push(...this.renderStatusTab(context));
+                break;
+            case 'config':
+                lines.push(...this.renderConfigTab(context));
+                break;
+            case 'paths':
+                lines.push(...this.renderPathsTab(context));
+                break;
+            case 'usage':
+                lines.push(...this.renderUsageTab(context));
+                break;
+        }
+        lines.push(...this.renderTabFooter(context));
+        // Pad to target height for consistent rendering
+        while (lines.length < TARGET_HEIGHT) {
+            lines.push('');
+        }
+        return lines;
+    }
+    renderTabHeader(context) {
+        const s = context.styles;
+        const lines = [];
+        const cols = context.width;
+        lines.push(s.muted('─'.repeat(Math.max(1, cols - 1))));
+        // Tab row
+        let tabLine = ' Settings: ';
+        for (let i = 0; i < TABS.length; i++) {
+            const tab = TABS[i];
+            if (i === this.state.currentTab) {
+                tabLine += s.selected(` ${tab.label} `) + ' ';
+            }
+            else {
+                tabLine += s.muted(` ${tab.label} `) + ' ';
+            }
+        }
+        tabLine += s.muted('(Tab · 1-4)');
+        lines.push(tabLine);
+        lines.push('');
+        return lines;
+    }
+    renderStatusTab(context) {
+        const s = context.styles;
+        const lines = [];
+        const info = this.state.statusInfo;
+        // Calculate uptime
+        const uptimeMs = Date.now() - info.startTime.getTime();
+        const uptimeSecs = Math.floor(uptimeMs / 1000);
+        const uptimeMins = Math.floor(uptimeSecs / 60);
+        const uptimeStr = uptimeMins > 0
+            ? `${String(uptimeMins)}m ${String(uptimeSecs % 60)}s`
+            : `${String(uptimeSecs)}s`;
+        lines.push(` Version: ${s.primary(info.version)}`);
+        lines.push(` Session: ${s.muted(info.sessionId)}`);
+        lines.push(` Uptime: ${s.muted(uptimeStr)}`);
+        lines.push('');
+        lines.push(` Provider: ${s.primary(info.provider)}`);
+        // Show model with "(default)" label when team is active
+        const modelLabel = info.hasTeam ? 'Model (default agent)' : 'Model';
+        lines.push(` ${modelLabel}: ${s.primary(info.model)}`);
+        // Show tool count with breakdown if available
+        if (info.directToolCount !== undefined && info.metaToolCount !== undefined) {
+            lines.push(` Tools: ${s.muted(String(info.toolCount))} ${s.muted(`(${String(info.directToolCount)} direct + ${String(info.metaToolCount)} via use_tool)`)}`);
+        }
+        else {
+            lines.push(` Tools: ${s.muted(String(info.toolCount))}`);
+        }
+        lines.push('');
+        lines.push(` Cwd: ${s.muted(info.cwd)}`);
+        lines.push(` Memory: ${s.muted(info.memoryFile || 'none')}`);
+        lines.push(` Settings: ${s.muted('~/.compilr-dev/settings.json')}`);
+        return lines;
+    }
+    renderConfigTab(context) {
+        const s = context.styles;
+        const lines = [];
+        lines.push(s.primaryBold(' Configure preferences'));
+        lines.push('');
+        for (let i = 0; i < this.state.configItems.length; i++) {
+            const item = this.state.configItems[i];
+            const isSelected = i === this.state.selectedItem;
+            const prefix = isSelected ? s.primary(' ❯ ') : '   ';
+            let valueStr;
+            if (item.type === 'boolean') {
+                valueStr = item.value ? s.success('true') : s.muted('false');
+            }
+            else if (item.type === 'submenu') {
+                valueStr = s.primary(String(item.value));
+            }
+            else {
+                valueStr = s.primary(String(item.value));
+            }
+            const labelStyled = isSelected
+                ? s.primary(item.label.padEnd(35))
+                : item.label.padEnd(35);
+            lines.push(prefix + labelStyled + valueStr);
+        }
+        return lines;
+    }
+    renderPathsTab(context) {
+        const s = context.styles;
+        const lines = [];
+        const pathConfig = getResolvedPathConfig();
+        const cols = context.width;
+        // Layout constants
+        const labelWidth = 24;
+        const valueWidth = Math.max(30, cols - labelWidth - 8);
+        // Get git config
+        const gitUserName = getGitConfigValue('user.name');
+        const gitUserEmail = getGitConfigValue('user.email');
+        lines.push(s.primaryBold(' Path Configuration'));
+        lines.push('');
+        // Helper to render a path/text item
+        const renderEditableItem = (index, label, value, placeholder) => {
+            const isSelected = this.state.pathSelectedItem === index;
+            const prefix = isSelected ? s.primary(' ❯ ') : '   ';
+            const displayValue = value || placeholder || 'not set';
+            if (this.state.pathEditMode && isSelected) {
+                // Edit mode - show input field
+                const labelStyled = s.primary(label.padEnd(labelWidth));
+                const inputDisplay = this.state.pathEditInput + '█';
+                lines.push(`${prefix}${labelStyled}${inputDisplay}`);
+            }
+            else {
+                // Normal mode - show value
+                const labelStyled = isSelected ? s.primary(label.padEnd(labelWidth)) : label.padEnd(labelWidth);
+                const truncatedValue = truncate(displayValue, valueWidth);
+                const valueStyled = value
+                    ? (isSelected ? s.primary(truncatedValue) : s.muted(truncatedValue))
+                    : s.warning(truncatedValue);
+                lines.push(`${prefix}${labelStyled}${valueStyled}`);
+            }
+        };
+        // Path items (0-2)
+        renderEditableItem(0, 'Workspace path', pathConfig.workspacePath);
+        renderEditableItem(1, 'Projects path', pathConfig.projectsPath);
+        renderEditableItem(2, 'Data path', pathConfig.dataPath);
+        lines.push('');
+        lines.push(s.primaryBold(' Git Configuration'));
+        lines.push('');
+        // Git config items (3-4)
+        renderEditableItem(3, 'Git user name', gitUserName, 'not set');
+        renderEditableItem(4, 'Git user email', gitUserEmail, 'not set');
+        lines.push('');
+        lines.push(s.primaryBold(' Safety Settings'));
+        lines.push('');
+        // Helper to render a toggle item with consistent alignment
+        const renderToggleItem = (index, label, enabled, hint) => {
+            const isSelected = this.state.pathSelectedItem === index;
+            const prefix = isSelected ? s.primary(' ❯ ') : '   ';
+            const labelStyled = isSelected ? s.primary(label.padEnd(labelWidth)) : label.padEnd(labelWidth);
+            const valueStyled = enabled ? s.success('enabled'.padStart(10)) : s.warning('disabled'.padStart(10));
+            lines.push(`${prefix}${labelStyled}${valueStyled}`);
+            lines.push(s.muted(`      ${hint}`));
+        };
+        // Toggle items (5-6)
+        renderToggleItem(5, 'Delete protection', pathConfig.deleteProtection, 'Only allow file deletion within projects path');
+        renderToggleItem(6, 'CWD mismatch warning', pathConfig.requireProjectMatch, 'Warn when current directory differs from active project');
+        lines.push('');
+        // Allowed paths (if any)
+        if (pathConfig.allowedPaths.length > 0) {
+            lines.push(s.primaryBold(' Additional Allowed Paths'));
+            for (const allowed of pathConfig.allowedPaths) {
+                lines.push(`   ${s.muted('•')} ${allowed}`);
+            }
+            lines.push('');
+        }
+        return lines;
+    }
+    renderUsageTab(context) {
+        const s = context.styles;
+        const lines = [];
+        const stats = this.state.usageStats;
+        lines.push(s.primaryBold(' Session Tokens'));
+        lines.push(`   Input:  ${s.primary(formatTokens(stats.inputTokens).padStart(8))}`);
+        lines.push(`   Output: ${s.primary(formatTokens(stats.outputTokens).padStart(8))}`);
+        lines.push(`   Total:  ${s.primary(formatTokens(stats.inputTokens + stats.outputTokens).padStart(8))}`);
+        lines.push('');
+        lines.push(s.primaryBold(' Context Window'));
+        const contextPct = stats.contextMax > 0 ? stats.contextUsed / stats.contextMax : 0;
+        const contextPctDisplay = Math.round(contextPct * 100);
+        lines.push(`   ${renderProgressBar(contextPct, 30, s)} ${String(contextPctDisplay)}% used`);
+        lines.push(s.muted(`   ${formatTokens(Math.round(stats.contextUsed))} / ${formatTokens(stats.contextMax)} tokens`));
+        lines.push('');
+        lines.push(s.primaryBold(' Session Activity'));
+        lines.push(`   Requests: ${s.primary(String(stats.requests))}`);
+        lines.push(`   Messages: ${s.primary(String(stats.messageCount))}`);
+        return lines;
+    }
+    renderTabFooter(context) {
+        const s = context.styles;
+        const lines = [];
+        lines.push('');
+        const tabId = TABS[this.state.currentTab].id;
+        if (tabId === 'config') {
+            lines.push(s.muted(' ↑↓/jk Navigate · Enter/Space Change · q/Esc Close'));
+        }
+        else if (tabId === 'paths') {
+            if (this.state.pathEditMode) {
+                lines.push(s.muted(' Type path · Enter Save · Esc Cancel'));
+            }
+            else {
+                lines.push(s.muted(' ↑↓/jk Navigate · Enter Edit/Toggle · q/Esc Close'));
+            }
+        }
+        else {
+            lines.push(s.muted(' q/Esc Close'));
+        }
+        return lines;
+    }
+    // ===========================================================================
+    // Key Handling
+    // ===========================================================================
+    handleKey(key) {
+        const data = key.raw;
+        const char = extractPrintable(data);
+        // Handle path edit mode first
+        if (this.state.pathEditMode) {
+            return this.handlePathEditKey(data, char);
+        }
+        // q or Esc closes
+        if (isEscape(data) || isCtrlC(data) || this.isQuit(data)) {
+            return this.close({ settingsChanged: this.settingsChanged });
+        }
+        // Tab switching: Tab for next, Shift+Tab for previous
+        if (isTab(data)) {
+            this.state.currentTab = (this.state.currentTab + 1) % TABS.length;
+            this.state.selectedItem = 0;
+            this.state.pathSelectedItem = 0;
+            return this.rerender();
+        }
+        if (isShiftTab(data)) {
+            this.state.currentTab = (this.state.currentTab - 1 + TABS.length) % TABS.length;
+            this.state.selectedItem = 0;
+            this.state.pathSelectedItem = 0;
+            return this.rerender();
+        }
+        // Number keys 1-4 to directly select tabs
+        const tabNumKey = getNumberKey(data);
+        if (tabNumKey !== null && tabNumKey >= 1 && tabNumKey <= TABS.length) {
+            this.state.currentTab = tabNumKey - 1;
+            this.state.selectedItem = 0;
+            this.state.pathSelectedItem = 0;
+            return this.rerender();
+        }
+        // Tab-specific key handling
+        const tabId = TABS[this.state.currentTab].id;
+        if (tabId === 'config') {
+            return this.handleConfigTabKey(data);
+        }
+        if (tabId === 'paths') {
+            return this.handlePathsTabKey(data);
+        }
+        return this.noAction();
+    }
+    handleConfigTabKey(data) {
+        // Navigation
+        if (isNavigateUp(data) && this.state.selectedItem > 0) {
+            this.state.selectedItem--;
+            return this.rerender();
+        }
+        if (isNavigateDown(data) && this.state.selectedItem < this.state.configItems.length - 1) {
+            this.state.selectedItem++;
+            return this.rerender();
+        }
+        // Toggle/cycle/submenu
+        if (isEnter(data) || isSpace(data)) {
+            const subOverlay = this.toggleOrCycleItem();
+            if (subOverlay) {
+                return this.push(subOverlay);
+            }
+            return this.rerender();
+        }
+        return this.noAction();
+    }
+    handlePathsTabKey(data) {
+        const pathItemCount = 7; // 3 paths + 2 git config + 2 toggles
+        // Navigation
+        if (isNavigateUp(data) && this.state.pathSelectedItem > 0) {
+            this.state.pathSelectedItem--;
+            return this.rerender();
+        }
+        if (isNavigateDown(data) && this.state.pathSelectedItem < pathItemCount - 1) {
+            this.state.pathSelectedItem++;
+            return this.rerender();
+        }
+        // Edit/toggle
+        if (isEnter(data) || isSpace(data)) {
+            const currentConfig = getResolvedPathConfig();
+            if (this.state.pathSelectedItem <= 2) {
+                // Path items (0-2) - enter edit mode
+                this.state.pathEditMode = true;
+                switch (this.state.pathSelectedItem) {
+                    case 0:
+                        this.state.pathEditInput = currentConfig.workspacePath;
+                        break;
+                    case 1:
+                        this.state.pathEditInput = currentConfig.projectsPath;
+                        break;
+                    case 2:
+                        this.state.pathEditInput = currentConfig.dataPath;
+                        break;
+                }
+                return this.rerender();
+            }
+            else if (this.state.pathSelectedItem === 3) {
+                // Git user name - enter edit mode
+                this.state.pathEditMode = true;
+                this.state.pathEditInput = getGitConfigValue('user.name') || '';
+                return this.rerender();
+            }
+            else if (this.state.pathSelectedItem === 4) {
+                // Git user email - enter edit mode
+                this.state.pathEditMode = true;
+                this.state.pathEditInput = getGitConfigValue('user.email') || '';
+                return this.rerender();
+            }
+            else if (this.state.pathSelectedItem === 5) {
+                // Toggle delete protection
+                setDeleteProtection(!currentConfig.deleteProtection);
+                this.settingsChanged = true;
+                return this.rerender();
+            }
+            else if (this.state.pathSelectedItem === 6) {
+                // Toggle CWD match warning
+                setProjectMatchRequired(!currentConfig.requireProjectMatch);
+                this.settingsChanged = true;
+                return this.rerender();
+            }
+        }
+        return this.noAction();
+    }
+    handlePathEditKey(data, char) {
+        if (isEscape(data)) {
+            // Cancel edit
+            this.state.pathEditMode = false;
+            this.state.pathEditInput = '';
+            return this.rerender();
+        }
+        if (isEnter(data)) {
+            // Save the value
+            const newValue = this.state.pathEditInput.trim();
+            if (newValue) {
+                switch (this.state.pathSelectedItem) {
+                    case 0:
+                        setWorkspacePath(newValue);
+                        break;
+                    case 1:
+                        setProjectsPath(newValue);
+                        break;
+                    case 2:
+                        setDataPath(newValue);
+                        break;
+                    case 3:
+                        setGitConfigValue('user.name', newValue);
+                        break;
+                    case 4:
+                        setGitConfigValue('user.email', newValue);
+                        break;
+                }
+                this.settingsChanged = true;
+            }
+            this.state.pathEditMode = false;
+            this.state.pathEditInput = '';
+            return this.rerender();
+        }
+        if (isBackspace(data)) {
+            this.state.pathEditInput = this.state.pathEditInput.slice(0, -1);
+            return this.rerender();
+        }
+        if (isPrintable(data)) {
+            this.state.pathEditInput += char;
+            return this.rerender();
+        }
+        return this.noAction();
+    }
+    // ===========================================================================
+    // Config Item Actions
+    // ===========================================================================
+    /**
+     * Toggle/cycle a config item, or return a sub-overlay for submenus.
+     * Returns the sub-overlay to push, or null if handled internally.
+     */
+    toggleOrCycleItem() {
+        const item = this.state.configItems[this.state.selectedItem];
+        // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
+        if (!item)
+            return null; // Defensive check
+        if (item.type === 'boolean') {
+            const newValue = !item.value;
+            item.value = newValue;
+            this.settingsChanged = true;
+            // Persist boolean settings
+            switch (item.id) {
+                case 'autoCompact':
+                    setSetting('autoCompact', newValue);
+                    break;
+                case 'verbose':
+                    setSetting('verbose', newValue);
+                    break;
+                case 'progressBar':
+                    setSetting('progressBar', newValue);
+                    break;
+                case 'checkUpdates':
+                    setSetting('checkUpdates', newValue);
+                    break;
+                case 'delegation':
+                    setSetting('delegation', newValue);
+                    break;
+                case 'vsDiffExtension':
+                    setSetting('vsDiffExtension', newValue);
+                    // On enable, ensure the extension is installed
+                    if (newValue) {
+                        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' +
+                                    '  \x1b[2mRestart the CLI after reload.\x1b[0m\n\n');
+                            }
+                        });
+                    }
+                    break;
+            }
+            return null;
+        }
+        if (item.type === 'cycle' && item.options) {
+            const currentIndex = item.options.indexOf(String(item.value));
+            const nextIndex = (currentIndex + 1) % item.options.length;
+            const newValue = item.options[nextIndex];
+            item.value = newValue;
+            this.settingsChanged = true;
+            // Persist cycle settings
+            switch (item.id) {
+                case 'permissionMode':
+                    setSetting('permissionMode', displayToPermissionMode(newValue));
+                    break;
+                case 'notifications':
+                    setSetting('notifications', displayToNotificationMode(newValue));
+                    break;
+                case 'startupMode':
+                    setSetting('startupMode', newValue === 'Show menu' ? 'menu' : 'repl');
+                    break;
+                case 'projectStartup':
+                    setSetting('projectStartup', displayToProjectStartupMode(newValue));
+                    break;
+                case 'projectSessionMode':
+                    setSetting('projectSessionMode', displayToProjectSessionMode(newValue));
+                    break;
+                case 'sessionRetentionDays':
+                    setSetting('sessionRetentionDays', displayToSessionRetention(newValue));
+                    break;
+                case 'compactMode':
+                    setSetting('compactMode', displayToCompactMode(newValue));
+                    break;
+            }
+            return null;
+        }
+        // Submenus - return the overlay to push
+        if (item.type === 'submenu') {
+            if (item.id === 'theme') {
+                return new ThemeOverlayV2();
+            }
+            if (item.id === 'model') {
+                return new ModelOverlayV2({
+                    currentModel: this.state.statusInfo.model,
+                    currentProvider: this.state.statusInfo.provider,
+                });
+            }
+            if (item.id === 'mascot') {
+                return new MascotOverlayV2({
+                    currentMascot: getSettings().mascot,
+                });
+            }
+        }
+        return null;
+    }
+    isQuit(data) {
+        return data.toString() === 'q';
+    }
+    // ===========================================================================
+    // Lifecycle
+    // ===========================================================================
+    /**
+     * When overlay closes, refresh config items to reflect any changes from sub-overlays.
+     */
+    onUnmount() {
+        // Refresh config items when returning from sub-overlays
+        this.state.configItems = getConfigItems(this.state.statusInfo.model);
+    }
+}