@tuan_son.dinh/gsd 2.6.0

package/dist/onboarding.js

@@ -0,0 +1,418 @@
+/**
+ * Unified first-run onboarding wizard.
+ *
+ * Replaces the raw API-key-only wizard with a branded, clack-based experience
+ * that guides users through LLM provider authentication before the TUI launches.
+ *
+ * Flow: logo -> choose LLM provider -> authenticate (OAuth or API key) ->
+ *       optional tool keys -> summary -> TUI launches.
+ *
+ * All steps are skippable. All errors are recoverable. Never crashes boot.
+ */
+import { exec } from 'node:child_process';
+import { renderLogo } from './logo.js';
+// ─── Constants ────────────────────────────────────────────────────────────────
+const TOOL_KEYS = [
+    {
+        provider: 'brave',
+        envVar: 'BRAVE_API_KEY',
+        label: 'Brave Search',
+        hint: 'web search + search_and_read tools',
+    },
+    {
+        provider: 'brave_answers',
+        envVar: 'BRAVE_ANSWERS_KEY',
+        label: 'Brave Answers',
+        hint: 'AI-summarised search answers',
+    },
+    {
+        provider: 'context7',
+        envVar: 'CONTEXT7_API_KEY',
+        label: 'Context7',
+        hint: 'up-to-date library docs',
+    },
+    {
+        provider: 'jina',
+        envVar: 'JINA_API_KEY',
+        label: 'Jina AI',
+        hint: 'clean web page extraction',
+    },
+    {
+        provider: 'slack_bot',
+        envVar: 'SLACK_BOT_TOKEN',
+        label: 'Slack Bot',
+        hint: 'remote questions in auto-mode',
+    },
+    {
+        provider: 'discord_bot',
+        envVar: 'DISCORD_BOT_TOKEN',
+        label: 'Discord Bot',
+        hint: 'remote questions in auto-mode',
+    },
+];
+/** Known LLM provider IDs that, if authed, mean the user doesn't need onboarding */
+const LLM_PROVIDER_IDS = [
+    'anthropic',
+    'openai',
+    'github-copilot',
+    'openai-codex',
+    'google-gemini-cli',
+    'google-antigravity',
+    'google',
+    'groq',
+    'xai',
+    'openrouter',
+    'mistral',
+];
+/** API key prefix validation — loose checks to catch obvious mistakes */
+const API_KEY_PREFIXES = {
+    anthropic: ['sk-ant-'],
+    openai: ['sk-'],
+};
+const OTHER_PROVIDERS = [
+    { value: 'google', label: 'Google (Gemini)' },
+    { value: 'groq', label: 'Groq' },
+    { value: 'xai', label: 'xAI (Grok)' },
+    { value: 'openrouter', label: 'OpenRouter' },
+    { value: 'mistral', label: 'Mistral' },
+];
+// ─── Dynamic imports ──────────────────────────────────────────────────────────
+/**
+ * Dynamically import @clack/prompts and picocolors.
+ * Dynamic import with fallback so the module doesn't crash if they're missing.
+ */
+async function loadClack() {
+    try {
+        return await import('@clack/prompts');
+    }
+    catch {
+        throw new Error('[gsd] @clack/prompts not found — onboarding wizard requires this dependency');
+    }
+}
+async function loadPico() {
+    try {
+        const mod = await import('picocolors');
+        return mod.default ?? mod;
+    }
+    catch {
+        // Fallback: return identity functions
+        const identity = (s) => s;
+        return { cyan: identity, green: identity, yellow: identity, dim: identity, bold: identity, red: identity, reset: identity };
+    }
+}
+// ─── Utilities ────────────────────────────────────────────────────────────────
+/** Open a URL in the system browser (best-effort, non-blocking) */
+function openBrowser(url) {
+    const cmd = process.platform === 'darwin' ? 'open' :
+        process.platform === 'win32' ? 'start' :
+            'xdg-open';
+    exec(`${cmd} "${url}"`, () => {
+        // Ignore errors — user can manually open the URL
+    });
+}
+/** Check if an error is a clack cancel signal */
+function isCancelError(p, err) {
+    return p.isCancel(err);
+}
+// ─── Public API ───────────────────────────────────────────────────────────────
+/**
+ * Determine if the onboarding wizard should run.
+ *
+ * Returns true when:
+ * - No LLM provider has credentials in authStorage
+ * - We're on a TTY (interactive terminal)
+ *
+ * Returns false (skip wizard) when:
+ * - Any LLM provider is already authed (returning user)
+ * - Not a TTY (piped input, subagent, CI)
+ */
+export function shouldRunOnboarding(authStorage) {
+    if (!process.stdin.isTTY)
+        return false;
+    // Check if any LLM provider has credentials
+    const authedProviders = authStorage.list();
+    const hasLlmAuth = authedProviders.some(id => LLM_PROVIDER_IDS.includes(id));
+    return !hasLlmAuth;
+}
+/**
+ * Run the unified onboarding wizard.
+ *
+ * Walks the user through:
+ * 1. Choose LLM provider
+ * 2. Authenticate (OAuth or API key)
+ * 3. Optional tool API keys
+ * 4. Summary
+ *
+ * All steps are skippable. All errors are recoverable.
+ * Writes status to stderr during execution.
+ */
+export async function runOnboarding(authStorage) {
+    let p;
+    let pc;
+    try {
+        ;
+        [p, pc] = await Promise.all([loadClack(), loadPico()]);
+    }
+    catch (err) {
+        // If clack isn't available, fall back silently — don't block boot
+        process.stderr.write(`[gsd] Onboarding wizard unavailable: ${err instanceof Error ? err.message : String(err)}\n`);
+        return;
+    }
+    // ── Intro ─────────────────────────────────────────────────────────────────
+    process.stderr.write(renderLogo(pc.cyan));
+    p.intro(pc.bold('Welcome to GSD — let\'s get you set up'));
+    // ── LLM Provider Selection ────────────────────────────────────────────────
+    let llmConfigured = false;
+    try {
+        llmConfigured = await runLlmStep(p, pc, authStorage);
+    }
+    catch (err) {
+        // User cancelled (Ctrl+C in clack throws) or unexpected error
+        if (isCancelError(p, err)) {
+            p.cancel('Setup cancelled — you can run /login inside GSD later.');
+            return;
+        }
+        p.log.warn(`LLM setup failed: ${err instanceof Error ? err.message : String(err)}`);
+        p.log.info('You can configure your LLM provider later with /login inside GSD.');
+    }
+    // ── Tool API Keys ─────────────────────────────────────────────────────────
+    let toolKeyCount = 0;
+    try {
+        toolKeyCount = await runToolKeysStep(p, pc, authStorage);
+    }
+    catch (err) {
+        if (isCancelError(p, err)) {
+            p.cancel('Setup cancelled.');
+            return;
+        }
+        p.log.warn(`Tool key setup failed: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    // ── Summary ───────────────────────────────────────────────────────────────
+    const summaryLines = [];
+    if (llmConfigured) {
+        // Re-read what provider was stored
+        const authed = authStorage.list().filter(id => LLM_PROVIDER_IDS.includes(id));
+        if (authed.length > 0) {
+            const name = authed[0];
+            summaryLines.push(`${pc.green('✓')} LLM provider: ${name}`);
+        }
+        else {
+            summaryLines.push(`${pc.green('✓')} LLM provider configured`);
+        }
+    }
+    else {
+        summaryLines.push(`${pc.yellow('↷')} LLM provider: skipped — use /login inside GSD`);
+    }
+    if (toolKeyCount > 0) {
+        summaryLines.push(`${pc.green('✓')} ${toolKeyCount} tool key${toolKeyCount > 1 ? 's' : ''} saved`);
+    }
+    else {
+        summaryLines.push(`${pc.dim('↷')} Tool keys: none configured`);
+    }
+    p.note(summaryLines.join('\n'), 'Setup complete');
+    p.outro(pc.dim('Launching GSD...'));
+}
+// ─── LLM Authentication Step ──────────────────────────────────────────────────
+async function runLlmStep(p, pc, authStorage) {
+    // Build the OAuth provider list dynamically from what's registered
+    const oauthProviders = authStorage.getOAuthProviders();
+    const oauthMap = new Map(oauthProviders.map(op => [op.id, op]));
+    const choice = await p.select({
+        message: 'Choose your LLM provider',
+        options: [
+            { value: 'anthropic-oauth', label: 'Anthropic — Claude (OAuth login)', hint: 'recommended' },
+            { value: 'anthropic-api-key', label: 'Anthropic — Claude (API key)' },
+            { value: 'openai-api-key', label: 'OpenAI (API key)' },
+            { value: 'github-copilot-oauth', label: 'GitHub Copilot (OAuth login)' },
+            { value: 'openai-codex-oauth', label: 'ChatGPT Plus/Pro — Codex (OAuth login)' },
+            { value: 'google-gemini-cli-oauth', label: 'Google Gemini CLI (OAuth login)' },
+            { value: 'google-antigravity-oauth', label: 'Antigravity — Gemini 3, Claude, GPT-OSS (OAuth login)' },
+            { value: 'other-api-key', label: 'Other provider (API key)' },
+            { value: 'skip', label: 'Skip for now', hint: 'use /login inside GSD later' },
+        ],
+    });
+    if (p.isCancel(choice) || choice === 'skip')
+        return false;
+    // ── OAuth flows ───────────────────────────────────────────────────────────
+    if (choice === 'anthropic-oauth') {
+        return await runOAuthFlow(p, pc, authStorage, 'anthropic', oauthMap);
+    }
+    if (choice === 'github-copilot-oauth') {
+        return await runOAuthFlow(p, pc, authStorage, 'github-copilot', oauthMap);
+    }
+    if (choice === 'openai-codex-oauth') {
+        return await runOAuthFlow(p, pc, authStorage, 'openai-codex', oauthMap);
+    }
+    if (choice === 'google-gemini-cli-oauth') {
+        return await runOAuthFlow(p, pc, authStorage, 'google-gemini-cli', oauthMap);
+    }
+    if (choice === 'google-antigravity-oauth') {
+        return await runOAuthFlow(p, pc, authStorage, 'google-antigravity', oauthMap);
+    }
+    // ── API key flows ─────────────────────────────────────────────────────────
+    if (choice === 'anthropic-api-key') {
+        return await runApiKeyFlow(p, pc, authStorage, 'anthropic', 'Anthropic');
+    }
+    if (choice === 'openai-api-key') {
+        return await runApiKeyFlow(p, pc, authStorage, 'openai', 'OpenAI');
+    }
+    if (choice === 'other-api-key') {
+        return await runOtherProviderFlow(p, pc, authStorage);
+    }
+    return false;
+}
+// ─── OAuth Flow ───────────────────────────────────────────────────────────────
+async function runOAuthFlow(p, pc, authStorage, providerId, oauthMap) {
+    const providerInfo = oauthMap.get(providerId);
+    const providerName = providerInfo?.name ?? providerId;
+    const usesCallbackServer = providerInfo?.usesCallbackServer ?? false;
+    const s = p.spinner();
+    s.start(`Authenticating with ${providerName}...`);
+    try {
+        await authStorage.login(providerId, {
+            onAuth: (info) => {
+                s.stop(`Opening browser for ${providerName}`);
+                openBrowser(info.url);
+                p.log.info(`${pc.dim('URL:')} ${pc.cyan(info.url)}`);
+                if (info.instructions) {
+                    p.log.info(pc.yellow(info.instructions));
+                }
+            },
+            onPrompt: async (prompt) => {
+                const result = await p.text({
+                    message: prompt.message,
+                    placeholder: prompt.placeholder,
+                });
+                if (p.isCancel(result))
+                    return '';
+                return result;
+            },
+            onProgress: (message) => {
+                p.log.step(pc.dim(message));
+            },
+            onManualCodeInput: usesCallbackServer
+                ? async () => {
+                    const result = await p.text({
+                        message: 'Paste the redirect URL from your browser:',
+                        placeholder: 'http://localhost:...',
+                    });
+                    if (p.isCancel(result))
+                        return '';
+                    return result;
+                }
+                : undefined,
+        });
+        p.log.success(`Authenticated with ${pc.green(providerName)}`);
+        return true;
+    }
+    catch (err) {
+        s.stop(`${providerName} authentication failed`);
+        const errorMsg = err instanceof Error ? err.message : String(err);
+        p.log.warn(`OAuth error: ${errorMsg}`);
+        // Offer retry or skip
+        const retry = await p.select({
+            message: 'What would you like to do?',
+            options: [
+                { value: 'retry', label: 'Try again' },
+                { value: 'skip', label: 'Skip — configure later with /login' },
+            ],
+        });
+        if (p.isCancel(retry) || retry === 'skip')
+            return false;
+        // Recursive retry
+        return runOAuthFlow(p, pc, authStorage, providerId, oauthMap);
+    }
+}
+// ─── API Key Flow ─────────────────────────────────────────────────────────────
+async function runApiKeyFlow(p, pc, authStorage, providerId, providerLabel) {
+    const key = await p.password({
+        message: `Paste your ${providerLabel} API key:`,
+        mask: '●',
+    });
+    if (p.isCancel(key) || !key)
+        return false;
+    const trimmed = key.trim();
+    if (!trimmed)
+        return false;
+    // Basic prefix validation
+    const expectedPrefixes = API_KEY_PREFIXES[providerId];
+    if (expectedPrefixes && !expectedPrefixes.some(pfx => trimmed.startsWith(pfx))) {
+        p.log.warn(`Key doesn't start with expected prefix (${expectedPrefixes.join(' or ')}). Saving anyway.`);
+    }
+    authStorage.set(providerId, { type: 'api_key', key: trimmed });
+    p.log.success(`API key saved for ${pc.green(providerLabel)}`);
+    return true;
+}
+// ─── "Other Provider" Sub-Flow ────────────────────────────────────────────────
+async function runOtherProviderFlow(p, pc, authStorage) {
+    const provider = await p.select({
+        message: 'Select provider',
+        options: OTHER_PROVIDERS.map(op => ({
+            value: op.value,
+            label: op.label,
+        })),
+    });
+    if (p.isCancel(provider))
+        return false;
+    const label = OTHER_PROVIDERS.find(op => op.value === provider)?.label ?? String(provider);
+    return runApiKeyFlow(p, pc, authStorage, provider, label);
+}
+// ─── Tool API Keys Step ───────────────────────────────────────────────────────
+async function runToolKeysStep(p, pc, authStorage) {
+    // Filter to keys not already configured
+    const missing = TOOL_KEYS.filter(tk => !authStorage.has(tk.provider) && !process.env[tk.envVar]);
+    if (missing.length === 0)
+        return 0;
+    const wantToolKeys = await p.confirm({
+        message: 'Set up optional tool API keys? (web search, docs, etc.)',
+        initialValue: false,
+    });
+    if (p.isCancel(wantToolKeys) || !wantToolKeys)
+        return 0;
+    let savedCount = 0;
+    for (const tk of missing) {
+        const key = await p.password({
+            message: `${tk.label} ${pc.dim(`(${tk.hint})`)} — Enter to skip:`,
+            mask: '●',
+        });
+        if (p.isCancel(key))
+            break;
+        const trimmed = key?.trim();
+        if (trimmed) {
+            authStorage.set(tk.provider, { type: 'api_key', key: trimmed });
+            process.env[tk.envVar] = trimmed;
+            p.log.success(`${tk.label} saved`);
+            savedCount++;
+        }
+        else {
+            // Store empty key so wizard doesn't re-ask on next launch
+            authStorage.set(tk.provider, { type: 'api_key', key: '' });
+            p.log.info(pc.dim(`${tk.label} skipped`));
+        }
+    }
+    return savedCount;
+}
+// ─── Env hydration (migrated from wizard.ts) ─────────────────────────────────
+/**
+ * Hydrate process.env from stored auth.json credentials for optional tool keys.
+ * Runs on every launch so extensions see Brave/Context7/Jina keys stored via the
+ * wizard on prior launches.
+ */
+export function loadStoredEnvKeys(authStorage) {
+    const providers = [
+        ['brave', 'BRAVE_API_KEY'],
+        ['brave_answers', 'BRAVE_ANSWERS_KEY'],
+        ['context7', 'CONTEXT7_API_KEY'],
+        ['jina', 'JINA_API_KEY'],
+        ['slack_bot', 'SLACK_BOT_TOKEN'],
+        ['discord_bot', 'DISCORD_BOT_TOKEN'],
+    ];
+    for (const [provider, envVar] of providers) {
+        if (!process.env[envVar]) {
+            const cred = authStorage.get(provider);
+            if (cred?.type === 'api_key' && cred.key) {
+                process.env[envVar] = cred.key;
+            }
+        }
+    }
+}

package/dist/pi-migration.d.ts

@@ -0,0 +1,14 @@
+/**
+ * One-time migration of provider credentials from Pi (~/.pi/agent/auth.json)
+ * into GSD's auth storage. Runs when GSD has no LLM providers configured,
+ * so users with an existing Pi install skip re-authentication.
+ */
+import type { AuthStorage } from '@mariozechner/pi-coding-agent';
+/**
+ * Migrate provider credentials from Pi's auth.json into GSD's AuthStorage.
+ *
+ * Only runs when GSD has no LLM provider configured and Pi's auth.json exists.
+ * Copies any credentials GSD doesn't already have. Returns true if an LLM
+ * provider was migrated (so onboarding can be skipped).
+ */
+export declare function migratePiCredentials(authStorage: AuthStorage): boolean;

package/dist/pi-migration.js

@@ -0,0 +1,57 @@
+/**
+ * One-time migration of provider credentials from Pi (~/.pi/agent/auth.json)
+ * into GSD's auth storage. Runs when GSD has no LLM providers configured,
+ * so users with an existing Pi install skip re-authentication.
+ */
+import { existsSync, readFileSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+const PI_AUTH_PATH = join(homedir(), '.pi', 'agent', 'auth.json');
+const LLM_PROVIDER_IDS = [
+    'anthropic',
+    'openai',
+    'github-copilot',
+    'openai-codex',
+    'google-gemini-cli',
+    'google-antigravity',
+    'google',
+    'groq',
+    'xai',
+    'openrouter',
+    'mistral',
+];
+/**
+ * Migrate provider credentials from Pi's auth.json into GSD's AuthStorage.
+ *
+ * Only runs when GSD has no LLM provider configured and Pi's auth.json exists.
+ * Copies any credentials GSD doesn't already have. Returns true if an LLM
+ * provider was migrated (so onboarding can be skipped).
+ */
+export function migratePiCredentials(authStorage) {
+    try {
+        // Only migrate when GSD has no LLM providers
+        const existing = authStorage.list();
+        const hasLlm = existing.some(id => LLM_PROVIDER_IDS.includes(id));
+        if (hasLlm)
+            return false;
+        if (!existsSync(PI_AUTH_PATH))
+            return false;
+        const raw = readFileSync(PI_AUTH_PATH, 'utf-8');
+        const piData = JSON.parse(raw);
+        let migratedLlm = false;
+        for (const [providerId, credential] of Object.entries(piData)) {
+            if (authStorage.has(providerId))
+                continue;
+            authStorage.set(providerId, credential);
+            const isLlm = LLM_PROVIDER_IDS.includes(providerId);
+            if (isLlm)
+                migratedLlm = true;
+            process.stderr.write(`[gsd] Migrated ${isLlm ? 'LLM provider' : 'credential'}: ${providerId} (from Pi)\n`);
+        }
+        return migratedLlm;
+    }
+    catch {
+        // Non-fatal — don't block startup
+        return false;
+    }
+}

package/dist/resource-loader.d.ts

@@ -0,0 +1,22 @@
+import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
+/**
+ * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
+ *
+ * - extensions/ → ~/.gsd/agent/extensions/   (always overwrite — ensures updates ship on next launch)
+ * - agents/     → ~/.gsd/agent/agents/        (always overwrite)
+ * - AGENTS.md   → ~/.gsd/agent/AGENTS.md      (always overwrite)
+ * - GSD-WORKFLOW.md is read directly from bundled path via GSD_WORKFLOW_PATH env var
+ *
+ * Always-overwrite ensures `npm update -g @glittercowboy/gsd` takes effect immediately.
+ * User customizations should go in ~/.gsd/agent/extensions/ subdirs with unique names,
+ * not by editing the gsd-managed files.
+ *
+ * Inspectable: `ls ~/.gsd/agent/extensions/`
+ */
+export declare function initResources(agentDir: string): void;
+/**
+ * Constructs a DefaultResourceLoader that loads extensions from both
+ * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).
+ * This allows users to use extensions from either location.
+ */
+export declare function buildResourceLoader(agentDir: string): DefaultResourceLoader;

package/dist/resource-loader.js

@@ -0,0 +1,60 @@
+import { DefaultResourceLoader } from '@mariozechner/pi-coding-agent';
+import { homedir } from 'node:os';
+import { cpSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+// Resolves to the bundled src/resources/ inside the npm package at runtime:
+//   dist/resource-loader.js → .. → package root → src/resources/
+const resourcesDir = resolve(dirname(fileURLToPath(import.meta.url)), '..', 'src', 'resources');
+const bundledExtensionsDir = join(resourcesDir, 'extensions');
+/**
+ * Syncs all bundled resources to agentDir (~/.gsd/agent/) on every launch.
+ *
+ * - extensions/ → ~/.gsd/agent/extensions/   (always overwrite — ensures updates ship on next launch)
+ * - agents/     → ~/.gsd/agent/agents/        (always overwrite)
+ * - AGENTS.md   → ~/.gsd/agent/AGENTS.md      (always overwrite)
+ * - GSD-WORKFLOW.md is read directly from bundled path via GSD_WORKFLOW_PATH env var
+ *
+ * Always-overwrite ensures `npm update -g @glittercowboy/gsd` takes effect immediately.
+ * User customizations should go in ~/.gsd/agent/extensions/ subdirs with unique names,
+ * not by editing the gsd-managed files.
+ *
+ * Inspectable: `ls ~/.gsd/agent/extensions/`
+ */
+export function initResources(agentDir) {
+    mkdirSync(agentDir, { recursive: true });
+    // Sync extensions — always overwrite so updates land on next launch
+    const destExtensions = join(agentDir, 'extensions');
+    cpSync(bundledExtensionsDir, destExtensions, { recursive: true, force: true });
+    // Sync agents
+    const destAgents = join(agentDir, 'agents');
+    const srcAgents = join(resourcesDir, 'agents');
+    if (existsSync(srcAgents)) {
+        cpSync(srcAgents, destAgents, { recursive: true, force: true });
+    }
+    // Sync skills — always overwrite so updates land on next launch
+    const destSkills = join(agentDir, 'skills');
+    const srcSkills = join(resourcesDir, 'skills');
+    if (existsSync(srcSkills)) {
+        cpSync(srcSkills, destSkills, { recursive: true, force: true });
+    }
+    // Sync AGENTS.md
+    const srcAgentsMd = join(resourcesDir, 'AGENTS.md');
+    const destAgentsMd = join(agentDir, 'AGENTS.md');
+    if (existsSync(srcAgentsMd)) {
+        writeFileSync(destAgentsMd, readFileSync(srcAgentsMd));
+    }
+}
+/**
+ * Constructs a DefaultResourceLoader that loads extensions from both
+ * ~/.gsd/agent/extensions/ (GSD's default) and ~/.pi/agent/extensions/ (pi's default).
+ * This allows users to use extensions from either location.
+ */
+export function buildResourceLoader(agentDir) {
+    const piAgentDir = join(homedir(), '.pi', 'agent');
+    const piExtensionsDir = join(piAgentDir, 'extensions');
+    return new DefaultResourceLoader({
+        agentDir,
+        additionalExtensionPaths: [piExtensionsDir],
+    });
+}

package/dist/tool-bootstrap.d.ts

@@ -0,0 +1,4 @@
+type ManagedTool = "fd" | "rg";
+export declare function resolveToolFromPath(tool: ManagedTool, pathValue?: string | undefined): string | null;
+export declare function ensureManagedTools(targetDir: string, pathValue?: string | undefined): string[];
+export {};

package/dist/tool-bootstrap.js

@@ -0,0 +1,74 @@
+import { chmodSync, copyFileSync, existsSync, lstatSync, mkdirSync, rmSync, symlinkSync } from "node:fs";
+import { delimiter, join } from "node:path";
+const TOOL_SPECS = {
+    fd: {
+        targetName: process.platform === "win32" ? "fd.exe" : "fd",
+        candidates: process.platform === "win32" ? ["fd.exe", "fd", "fdfind.exe", "fdfind"] : ["fd", "fdfind"],
+    },
+    rg: {
+        targetName: process.platform === "win32" ? "rg.exe" : "rg",
+        candidates: process.platform === "win32" ? ["rg.exe", "rg"] : ["rg"],
+    },
+};
+function splitPath(pathValue) {
+    if (!pathValue)
+        return [];
+    return pathValue.split(delimiter).map((segment) => segment.trim()).filter(Boolean);
+}
+function getCandidateNames(name) {
+    if (process.platform !== "win32")
+        return [name];
+    const lower = name.toLowerCase();
+    if (lower.endsWith(".exe") || lower.endsWith(".cmd") || lower.endsWith(".bat"))
+        return [name];
+    return [name, `${name}.exe`, `${name}.cmd`, `${name}.bat`];
+}
+function isRegularFile(path) {
+    try {
+        return lstatSync(path).isFile() || lstatSync(path).isSymbolicLink();
+    }
+    catch {
+        return false;
+    }
+}
+export function resolveToolFromPath(tool, pathValue = process.env.PATH) {
+    const spec = TOOL_SPECS[tool];
+    for (const dir of splitPath(pathValue)) {
+        for (const candidate of spec.candidates) {
+            for (const name of getCandidateNames(candidate)) {
+                const fullPath = join(dir, name);
+                if (existsSync(fullPath) && isRegularFile(fullPath)) {
+                    return fullPath;
+                }
+            }
+        }
+    }
+    return null;
+}
+function provisionTool(targetDir, tool, sourcePath) {
+    const targetPath = join(targetDir, TOOL_SPECS[tool].targetName);
+    if (existsSync(targetPath))
+        return targetPath;
+    mkdirSync(targetDir, { recursive: true });
+    try {
+        symlinkSync(sourcePath, targetPath);
+    }
+    catch {
+        rmSync(targetPath, { force: true });
+        copyFileSync(sourcePath, targetPath);
+        chmodSync(targetPath, 0o755);
+    }
+    return targetPath;
+}
+export function ensureManagedTools(targetDir, pathValue = process.env.PATH) {
+    const provisioned = [];
+    for (const tool of Object.keys(TOOL_SPECS)) {
+        if (existsSync(join(targetDir, TOOL_SPECS[tool].targetName)))
+            continue;
+        const sourcePath = resolveToolFromPath(tool, pathValue);
+        if (!sourcePath)
+            continue;
+        provisioned.push(provisionTool(targetDir, tool, sourcePath));
+    }
+    return provisioned;
+}

package/dist/wizard.d.ts

@@ -0,0 +1,7 @@
+import type { AuthStorage } from '@mariozechner/pi-coding-agent';
+/**
+ * Hydrate process.env from stored auth.json credentials for optional tool keys.
+ * Runs on every launch so extensions see Brave/Context7/Jina keys stored via the
+ * wizard on prior launches.
+ */
+export declare function loadStoredEnvKeys(authStorage: AuthStorage): void;