gsd-pi 2.33.1 → 2.34.0-dev.bbb5216

package/dist/resources/extensions/gsd/collision-diagnostics.js

@@ -0,0 +1,226 @@
+/**
+ * Collision Diagnostics Module
+ *
+ * Bridges NamespacedRegistry collision data and NamespacedResolver ambiguous
+ * resolution into a classified diagnostic taxonomy. Provides two functions:
+ * - analyzeCollisions: Scans registry and resolver state to produce classified diagnostics
+ * - doctorReport: Formats diagnostics into human-readable output with severity and remediation
+ *
+ * This module implements R010 (collision reporting) and R011 (doctor advice) for the
+ * namespaced component system.
+ */
+// ============================================================================
+// Implementation
+// ============================================================================
+/**
+ * Analyze a registry and resolver to produce classified diagnostics.
+ *
+ * This function:
+ * 1. Reads registry.getDiagnostics() for canonical conflicts (→ error severity)
+ * 2. Groups registry.getAll() by bare component.name
+ * 3. For groups with 2+ entries, calls resolver.resolve(bareName) to confirm ambiguity
+ * 4. Produces warning diagnostics for ambiguous shorthand resolution
+ *
+ * @param registry - The namespaced registry to analyze
+ * @param resolver - The resolver to test ambiguity
+ * @returns Array of classified diagnostics
+ */
+export function analyzeCollisions(registry, resolver) {
+    const diagnostics = [];
+    // Step 1: Process canonical conflicts from registry diagnostics
+    const registryDiagnostics = registry.getDiagnostics();
+    for (const diag of registryDiagnostics) {
+        if (diag.type === 'collision') {
+            diagnostics.push({
+                class: 'canonical-conflict',
+                severity: 'error',
+                involvedCanonicalNames: [diag.collision.canonicalName],
+                filePaths: [diag.collision.winnerPath, diag.collision.loserPath],
+                remediation: `Canonical name "${diag.collision.canonicalName}" registered multiple times. ` +
+                    `The first registration (${diag.collision.winnerSource ?? 'unknown source'}) ` +
+                    `took precedence over subsequent registration (${diag.collision.loserSource ?? 'unknown source'}). ` +
+                    `Rename one of the conflicting components to resolve.`,
+            });
+        }
+    }
+    // Step 2: Find shorthand overlaps by grouping components by bare name
+    const components = registry.getAll();
+    const byBareName = new Map();
+    for (const component of components) {
+        const bareName = component.name;
+        if (!byBareName.has(bareName)) {
+            byBareName.set(bareName, []);
+        }
+        byBareName.get(bareName).push(component);
+    }
+    // Step 3: For groups with 2+ entries, check if resolver confirms ambiguity
+    for (const [bareName, candidates] of byBareName) {
+        if (candidates.length >= 2) {
+            // Use resolver to confirm ambiguity
+            const result = resolver.resolve(bareName);
+            if (result.resolution === 'ambiguous') {
+                // This is a shorthand overlap
+                const canonicalNames = candidates.map(c => c.canonicalName);
+                const filePaths = candidates.map(c => c.filePath);
+                diagnostics.push({
+                    class: 'shorthand-overlap',
+                    severity: 'warning',
+                    involvedCanonicalNames: canonicalNames,
+                    filePaths,
+                    remediation: formatShorthandRemediation(bareName, canonicalNames),
+                    ambiguousBareName: bareName,
+                });
+            }
+            // If resolution is 'shorthand' or 'local-first', the overlap is resolved
+            // unambiguously by the resolver, so we don't warn
+        }
+    }
+    // Step 4: Check for alias conflicts
+    const aliases = registry.getAliases();
+    const canonicalNamesSet = new Set(components.map(c => c.canonicalName));
+    for (const [alias, targetCanonical] of aliases) {
+        // Check if alias shadows a canonical name
+        // (This can happen if a component was registered AFTER the alias was created)
+        if (canonicalNamesSet.has(alias)) {
+            const shadowedComponent = components.find(c => c.canonicalName === alias);
+            const aliasedComponent = components.find(c => c.canonicalName === targetCanonical);
+            diagnostics.push({
+                class: 'alias-conflict',
+                severity: 'warning',
+                involvedCanonicalNames: [alias, targetCanonical],
+                filePaths: [
+                    shadowedComponent?.filePath ?? '<unknown>',
+                    aliasedComponent?.filePath ?? '<unknown>',
+                ],
+                remediation: formatAliasShadowsCanonicalRemediation(alias, targetCanonical),
+                alias,
+                aliasTarget: targetCanonical,
+                aliasConflictType: 'shadows-canonical',
+            });
+            continue; // Skip further checks for this alias
+        }
+        // Check if alias shadows a bare name (matches component.name in any namespace)
+        const matchingBareNames = components.filter(c => c.name === alias);
+        if (matchingBareNames.length > 0) {
+            const filePaths = matchingBareNames.map(c => c.filePath);
+            const aliasedComponent = components.find(c => c.canonicalName === targetCanonical);
+            if (aliasedComponent)
+                filePaths.push(aliasedComponent.filePath);
+            diagnostics.push({
+                class: 'alias-conflict',
+                severity: 'warning',
+                involvedCanonicalNames: [targetCanonical, ...matchingBareNames.map(c => c.canonicalName)],
+                filePaths,
+                remediation: formatAliasShadowsBareNameRemediation(alias, targetCanonical, matchingBareNames.map(c => c.canonicalName)),
+                alias,
+                aliasTarget: targetCanonical,
+                aliasConflictType: 'shadows-bare-name',
+            });
+        }
+    }
+    return diagnostics;
+}
+/**
+ * Format remediation advice for shorthand overlap.
+ *
+ * @param bareName - The ambiguous bare name
+ * @param canonicalNames - All canonical names that match
+ * @returns Human-readable remediation message
+ */
+function formatShorthandRemediation(bareName, canonicalNames) {
+    const suggestions = canonicalNames
+        .map(cn => `\`${cn}\``)
+        .join(', ');
+    return `Bare name "${bareName}" is ambiguous across ${canonicalNames.length} namespaces. ` +
+        `Use a canonical name (${suggestions}) to avoid ambiguity.`;
+}
+/**
+ * Format remediation advice for alias shadowing a canonical name.
+ *
+ * @param alias - The alias that shadows a canonical name
+ * @param targetCanonical - The canonical name the alias points to
+ * @returns Human-readable remediation message
+ */
+function formatAliasShadowsCanonicalRemediation(alias, targetCanonical) {
+    return `Alias "${alias}" shadows an existing canonical name. ` +
+        `The alias points to "${targetCanonical}", but resolving "${alias}" will now match the component, not the alias. ` +
+        `Consider rename or remove the alias to avoid confusion.`;
+}
+/**
+ * Format remediation advice for alias shadowing a bare name.
+ *
+ * @param alias - The alias that shadows bare names
+ * @param targetCanonical - The canonical name the alias points to
+ * @param shadowedCanonicals - The canonical names whose bare names are shadowed
+ * @returns Human-readable remediation message
+ */
+function formatAliasShadowsBareNameRemediation(alias, targetCanonical, shadowedCanonicals) {
+    const shadowed = shadowedCanonicals.map(cn => `\`${cn}\``).join(', ');
+    return `Alias "${alias}" shadows ${shadowedCanonicals.length} component(s) with the same bare name (${shadowed}). ` +
+        `Resolving "${alias}" will use the alias (pointing to "${targetCanonical}"), not shorthand resolution. ` +
+        `Use canonical names to be explicit, or rename the alias if this is unintended.`;
+}
+/**
+ * Format diagnostics into a human-readable doctor report.
+ *
+ * Each diagnostic is formatted with:
+ * - Severity icon (❌ error / ⚠️ warning)
+ * - Description of the issue
+ * - Involved file paths
+ * - Remediation advice
+ *
+ * @param diagnostics - Array of classified diagnostics
+ * @returns Doctor report with summary and formatted entries
+ */
+export function doctorReport(diagnostics) {
+    const summary = {
+        total: diagnostics.length,
+        canonicalConflicts: diagnostics.filter(d => d.class === 'canonical-conflict').length,
+        shorthandOverlaps: diagnostics.filter(d => d.class === 'shorthand-overlap').length,
+        aliasConflicts: diagnostics.filter(d => d.class === 'alias-conflict').length,
+    };
+    const entries = diagnostics.map(diagnostic => formatDiagnosticEntry(diagnostic));
+    return { summary, entries };
+}
+/**
+ * Format a single diagnostic entry for display.
+ *
+ * @param diagnostic - The diagnostic to format
+ * @returns Formatted string entry
+ */
+function formatDiagnosticEntry(diagnostic) {
+    const icon = diagnostic.severity === 'error' ? '❌' : '⚠️';
+    const lines = [];
+    // Header with severity and class
+    lines.push(`${icon} ${diagnostic.class.toUpperCase()}`);
+    // Description
+    if (diagnostic.class === 'canonical-conflict') {
+        lines.push(`   Canonical name conflict: ${diagnostic.involvedCanonicalNames[0]}`);
+    }
+    else if (diagnostic.class === 'alias-conflict') {
+        if (diagnostic.aliasConflictType === 'shadows-canonical') {
+            lines.push(`   Alias "${diagnostic.alias}" shadows canonical name (points to ${diagnostic.aliasTarget})`);
+        }
+        else {
+            lines.push(`   Alias "${diagnostic.alias}" shadows bare name (points to ${diagnostic.aliasTarget})`);
+        }
+    }
+    else {
+        lines.push(`   Shorthand overlap: "${diagnostic.ambiguousBareName}" matches ${diagnostic.involvedCanonicalNames.length} components`);
+    }
+    // File paths
+    lines.push('   Files:');
+    for (const path of diagnostic.filePaths) {
+        lines.push(`     - ${path}`);
+    }
+    // Remediation
+    lines.push(`   Remediation: ${diagnostic.remediation}`);
+    return lines.join('\n');
+}
+// ============================================================================
+// Exports
+// ============================================================================
+export default {
+    analyzeCollisions,
+    doctorReport,
+};

package/dist/resources/extensions/gsd/commands-bootstrap.js

@@ -0,0 +1,223 @@
+import { importExtensionModule } from "@gsd/pi-coding-agent";
+const TOP_LEVEL_SUBCOMMANDS = [
+    { cmd: "help", desc: "Categorized command reference with descriptions" },
+    { cmd: "next", desc: "Explicit step mode (same as /gsd)" },
+    { cmd: "auto", desc: "Autonomous mode — research, plan, execute, commit, repeat" },
+    { cmd: "stop", desc: "Stop auto mode gracefully" },
+    { cmd: "pause", desc: "Pause auto-mode (preserves state, /gsd auto to resume)" },
+    { cmd: "status", desc: "Progress dashboard" },
+    { cmd: "visualize", desc: "Open workflow visualizer" },
+    { cmd: "queue", desc: "Queue and reorder future milestones" },
+    { cmd: "quick", desc: "Execute a quick task without full planning overhead" },
+    { cmd: "discuss", desc: "Discuss architecture and decisions" },
+    { cmd: "capture", desc: "Fire-and-forget thought capture" },
+    { cmd: "triage", desc: "Manually trigger triage of pending captures" },
+    { cmd: "dispatch", desc: "Dispatch a specific phase directly" },
+    { cmd: "history", desc: "View execution history" },
+    { cmd: "undo", desc: "Revert last completed unit" },
+    { cmd: "skip", desc: "Prevent a unit from auto-mode dispatch" },
+    { cmd: "export", desc: "Export milestone or slice results" },
+    { cmd: "cleanup", desc: "Remove merged branches or snapshots" },
+    { cmd: "mode", desc: "Switch workflow mode (solo/team)" },
+    { cmd: "prefs", desc: "Manage preferences" },
+    { cmd: "config", desc: "Set API keys for external tools" },
+    { cmd: "keys", desc: "API key manager" },
+    { cmd: "hooks", desc: "Show configured hooks" },
+    { cmd: "run-hook", desc: "Manually trigger a specific hook" },
+    { cmd: "skill-health", desc: "Skill lifecycle dashboard" },
+    { cmd: "doctor", desc: "Runtime health checks with auto-fix" },
+    { cmd: "logs", desc: "Browse activity logs, debug logs, and metrics" },
+    { cmd: "forensics", desc: "Examine execution logs" },
+    { cmd: "init", desc: "Project init wizard" },
+    { cmd: "setup", desc: "Global setup status and configuration" },
+    { cmd: "migrate", desc: "Migrate a v1 .planning directory to .gsd format" },
+    { cmd: "remote", desc: "Control remote auto-mode" },
+    { cmd: "steer", desc: "Hard-steer plan documents during execution" },
+    { cmd: "inspect", desc: "Show SQLite DB diagnostics" },
+    { cmd: "knowledge", desc: "Add persistent project knowledge" },
+    { cmd: "new-milestone", desc: "Create a milestone from a specification document" },
+    { cmd: "parallel", desc: "Parallel milestone orchestration" },
+    { cmd: "park", desc: "Park a milestone" },
+    { cmd: "unpark", desc: "Reactivate a parked milestone" },
+    { cmd: "update", desc: "Update GSD to the latest version" },
+    { cmd: "start", desc: "Start a workflow template" },
+    { cmd: "templates", desc: "List available workflow templates" },
+    { cmd: "extensions", desc: "Manage extensions" },
+];
+function filterStartsWith(partial, options, prefix = "") {
+    const normalizedPrefix = prefix.length > 0 ? `${prefix} ` : "";
+    return options
+        .filter((option) => option.cmd.startsWith(partial))
+        .map((option) => ({
+        value: `${normalizedPrefix}${option.cmd}`,
+        label: option.cmd,
+        description: option.desc,
+    }));
+}
+function getGsdArgumentCompletions(prefix) {
+    const parts = prefix.trim().split(/\s+/);
+    if (parts.length <= 1) {
+        return filterStartsWith(parts[0] ?? "", TOP_LEVEL_SUBCOMMANDS);
+    }
+    const partial = parts[1] ?? "";
+    if (parts[0] === "auto" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "--verbose", desc: "Show detailed execution output" },
+            { cmd: "--debug", desc: "Enable debug logging" },
+        ], "auto");
+    }
+    if (parts[0] === "next" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "--verbose", desc: "Show detailed step output" },
+            { cmd: "--dry-run", desc: "Preview next step without executing" },
+        ], "next");
+    }
+    if (parts[0] === "mode" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "global", desc: "Edit global workflow mode" },
+            { cmd: "project", desc: "Edit project-specific workflow mode" },
+        ], "mode");
+    }
+    if (parts[0] === "parallel" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "start", desc: "Start parallel milestone orchestration" },
+            { cmd: "status", desc: "Show parallel worker statuses" },
+            { cmd: "stop", desc: "Stop all parallel workers" },
+            { cmd: "pause", desc: "Pause a specific worker" },
+            { cmd: "resume", desc: "Resume a paused worker" },
+            { cmd: "merge", desc: "Merge completed milestone branches" },
+        ], "parallel");
+    }
+    if (parts[0] === "setup" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "llm", desc: "Configure LLM provider settings" },
+            { cmd: "search", desc: "Configure web search provider" },
+            { cmd: "remote", desc: "Configure remote integrations" },
+            { cmd: "keys", desc: "Manage API keys" },
+            { cmd: "prefs", desc: "Configure global preferences" },
+        ], "setup");
+    }
+    if (parts[0] === "logs" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "debug", desc: "List or view debug log files" },
+            { cmd: "tail", desc: "Show last N activity log summaries" },
+            { cmd: "clear", desc: "Remove old activity and debug logs" },
+        ], "logs");
+    }
+    if (parts[0] === "keys" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "list", desc: "Show key status dashboard" },
+            { cmd: "add", desc: "Add a key for a provider" },
+            { cmd: "remove", desc: "Remove a key" },
+            { cmd: "test", desc: "Validate key(s) with API call" },
+            { cmd: "rotate", desc: "Replace an existing key" },
+            { cmd: "doctor", desc: "Health check all keys" },
+        ], "keys");
+    }
+    if (parts[0] === "prefs" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "global", desc: "Edit global preferences file" },
+            { cmd: "project", desc: "Edit project preferences file" },
+            { cmd: "status", desc: "Show effective preferences" },
+            { cmd: "wizard", desc: "Interactive preferences wizard" },
+            { cmd: "setup", desc: "First-time preferences setup" },
+            { cmd: "import-claude", desc: "Import settings from Claude Code" },
+        ], "prefs");
+    }
+    if (parts[0] === "remote" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "slack", desc: "Configure Slack integration" },
+            { cmd: "discord", desc: "Configure Discord integration" },
+            { cmd: "status", desc: "Show remote connection status" },
+            { cmd: "disconnect", desc: "Disconnect remote integrations" },
+        ], "remote");
+    }
+    if (parts[0] === "history" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "--cost", desc: "Show cost breakdown per entry" },
+            { cmd: "--phase", desc: "Filter by phase type" },
+            { cmd: "--model", desc: "Filter by model used" },
+            { cmd: "10", desc: "Show last 10 entries" },
+            { cmd: "20", desc: "Show last 20 entries" },
+            { cmd: "50", desc: "Show last 50 entries" },
+        ], "history");
+    }
+    if (parts[0] === "export" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "--json", desc: "Export as JSON" },
+            { cmd: "--markdown", desc: "Export as Markdown" },
+            { cmd: "--html", desc: "Export as HTML" },
+            { cmd: "--html --all", desc: "Export all milestones as HTML" },
+        ], "export");
+    }
+    if (parts[0] === "cleanup" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "branches", desc: "Remove merged milestone branches" },
+            { cmd: "snapshots", desc: "Remove old execution snapshots" },
+        ], "cleanup");
+    }
+    if (parts[0] === "knowledge" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "rule", desc: "Add a project rule" },
+            { cmd: "pattern", desc: "Add a code pattern" },
+            { cmd: "lesson", desc: "Record a lesson learned" },
+        ], "knowledge");
+    }
+    if (parts[0] === "start" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "bugfix", desc: "Triage, fix, test, and ship a bug fix" },
+            { cmd: "small-feature", desc: "Lightweight feature with optional discussion" },
+            { cmd: "spike", desc: "Research, prototype, and document findings" },
+            { cmd: "hotfix", desc: "Minimal: fix it, test it, ship it" },
+            { cmd: "refactor", desc: "Inventory, plan waves, migrate, verify" },
+            { cmd: "security-audit", desc: "Scan, triage, remediate, re-scan" },
+            { cmd: "dep-upgrade", desc: "Assess, upgrade, fix breaks, verify" },
+            { cmd: "full-project", desc: "Complete GSD workflow with full ceremony" },
+            { cmd: "resume", desc: "Resume an in-progress workflow" },
+            { cmd: "--list", desc: "List all available templates" },
+            { cmd: "--dry-run", desc: "Preview workflow without executing" },
+        ], "start");
+    }
+    if (parts[0] === "templates" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "info", desc: "Show detailed template info" },
+        ], "templates");
+    }
+    if (parts[0] === "extensions" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "list", desc: "List all extensions and their status" },
+            { cmd: "enable", desc: "Enable a disabled extension" },
+            { cmd: "disable", desc: "Disable an extension" },
+            { cmd: "info", desc: "Show extension details" },
+        ], "extensions");
+    }
+    if (parts[0] === "doctor" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "fix", desc: "Auto-fix detected issues" },
+            { cmd: "heal", desc: "AI-driven deep healing" },
+            { cmd: "audit", desc: "Run health audit without fixing" },
+        ], "doctor");
+    }
+    if (parts[0] === "dispatch" && parts.length <= 2) {
+        return filterStartsWith(partial, [
+            { cmd: "research", desc: "Run research phase" },
+            { cmd: "plan", desc: "Run planning phase" },
+            { cmd: "execute", desc: "Run execution phase" },
+            { cmd: "complete", desc: "Run completion phase" },
+            { cmd: "reassess", desc: "Reassess current progress" },
+            { cmd: "uat", desc: "Run user acceptance testing" },
+            { cmd: "replan", desc: "Replan the current slice" },
+        ], "dispatch");
+    }
+    return null;
+}
+export function registerLazyGSDCommand(pi) {
+    pi.registerCommand("gsd", {
+        description: "GSD — Get Shit Done",
+        getArgumentCompletions: getGsdArgumentCompletions,
+        handler: async (args, ctx) => {
+            const { handleGSDCommand } = await importExtensionModule(import.meta.url, "./commands.js");
+            await handleGSDCommand(args, ctx, pi);
+        },
+    });
+}

package/dist/resources/extensions/gsd/commands-config.js

@@ -0,0 +1,89 @@
+/**
+ * GSD Config — Tool API key management.
+ *
+ * Contains: TOOL_KEYS, loadToolApiKeys, getConfigAuthStorage, handleConfig
+ */
+import { AuthStorage } from "@gsd/pi-coding-agent";
+import { existsSync, mkdirSync } from "node:fs";
+import { join, dirname } from "node:path";
+/**
+ * Tool API key configurations.
+ * This is the source of truth for tool credentials - used by both the config wizard
+ * and session startup to load keys from auth.json into environment variables.
+ */
+export const TOOL_KEYS = [
+    { id: "tavily", env: "TAVILY_API_KEY", label: "Tavily Search", hint: "tavily.com/app/api-keys" },
+    { id: "brave", env: "BRAVE_API_KEY", label: "Brave Search", hint: "brave.com/search/api" },
+    { id: "context7", env: "CONTEXT7_API_KEY", label: "Context7 Docs", hint: "context7.com/dashboard" },
+    { id: "jina", env: "JINA_API_KEY", label: "Jina Page Extract", hint: "jina.ai/api" },
+    { id: "groq", env: "GROQ_API_KEY", label: "Groq Voice", hint: "console.groq.com" },
+];
+/**
+ * Load tool API keys from auth.json into environment variables.
+ * Called at session startup to ensure tools have access to their credentials.
+ */
+export function loadToolApiKeys() {
+    try {
+        const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+        if (!existsSync(authPath))
+            return;
+        const auth = AuthStorage.create(authPath);
+        for (const tool of TOOL_KEYS) {
+            const cred = auth.get(tool.id);
+            if (cred && cred.type === "api_key" && cred.key && !process.env[tool.env]) {
+                process.env[tool.env] = cred.key;
+            }
+        }
+    }
+    catch {
+        // Failed to load tool keys — ignore, they can still be set via env vars
+    }
+}
+export function getConfigAuthStorage() {
+    const authPath = join(process.env.HOME ?? "", ".gsd", "agent", "auth.json");
+    mkdirSync(dirname(authPath), { recursive: true });
+    return AuthStorage.create(authPath);
+}
+export async function handleConfig(ctx) {
+    const auth = getConfigAuthStorage();
+    // Show current status
+    const statusLines = ["GSD Tool Configuration\n"];
+    for (const tool of TOOL_KEYS) {
+        const hasKey = !!process.env[tool.env] || !!auth.get(tool.id)?.key;
+        statusLines.push(`  ${hasKey ? "\u2713" : "\u2717"} ${tool.label}${hasKey ? "" : ` \u2014 get key at ${tool.hint}`}`);
+    }
+    ctx.ui.notify(statusLines.join("\n"), "info");
+    // Ask which tools to configure
+    const options = TOOL_KEYS.map(t => {
+        const hasKey = !!process.env[t.env] || !!auth.get(t.id)?.key;
+        return `${t.label} ${hasKey ? "(configured \u2713)" : "(not set)"}`;
+    });
+    options.push("(done)");
+    let changed = false;
+    while (true) {
+        const choice = await ctx.ui.select("Configure which tool? Press Escape when done.", options);
+        if (!choice || typeof choice !== "string" || choice === "(done)")
+            break;
+        const toolIdx = TOOL_KEYS.findIndex(t => choice.startsWith(t.label));
+        if (toolIdx === -1)
+            break;
+        const tool = TOOL_KEYS[toolIdx];
+        const input = await ctx.ui.input(`API key for ${tool.label} (${tool.hint}):`, "paste your key here");
+        if (input !== null && input !== undefined) {
+            const key = input.trim();
+            if (key) {
+                auth.set(tool.id, { type: "api_key", key });
+                process.env[tool.env] = key;
+                ctx.ui.notify(`${tool.label} key saved and activated.`, "info");
+                // Update option label
+                options[toolIdx] = `${tool.label} (configured \u2713)`;
+                changed = true;
+            }
+        }
+    }
+    if (changed) {
+        await ctx.waitForIdle();
+        await ctx.reload();
+        ctx.ui.notify("Configuration saved. Extensions reloaded with new keys.", "info");
+    }
+}