gekto 0.0.14 → 0.0.15

package/dist/agents/agentWebSocket.js

@@ -440,6 +440,62 @@ export function setupAgentWebSocket(server, path = '/__gekto/agent') {
                                     }));
                                 }
                             }
+                            else if (planResult.type === 'spawn_agent' && planResult.spawn) {
+                                // Restore plan state — only delete if it was a temporary entry
+                                if (msg.planId && getState().activePlans[msg.planId]?.status === 'planning') {
+                                    if (planExistedBefore && previousStatus) {
+                                        mutate(`activePlans.${msg.planId}.status`, previousStatus);
+                                        broadcastSinglePlan(msg.planId);
+                                    }
+                                    else {
+                                        mutate(`activePlans.${msg.planId}`, undefined);
+                                        broadcastSinglePlan(msg.planId);
+                                    }
+                                }
+                                // Spin up a brand-new free agent (no plan) and hand the prompt to it.
+                                // Uses the `agent_` prefix so it shows up in the floating LizardsList swarm UI
+                                // (the `worker_` prefix is filtered out — those agents only render on the whiteboard).
+                                const { agentName, taskDescription, prompt: workerPrompt } = planResult.spawn;
+                                const suffix = `${Date.now()}_${Math.random().toString(36).slice(2, 6)}`;
+                                const newAgentId = `agent_${suffix}`;
+                                const newTaskId = `task_${suffix}`;
+                                const newTask = {
+                                    id: newTaskId,
+                                    name: agentName,
+                                    description: taskDescription,
+                                    prompt: workerPrompt,
+                                    status: 'in_progress',
+                                    dependencies: [],
+                                    files: [],
+                                    assignedAgentId: newAgentId,
+                                };
+                                const newAgent = {
+                                    id: newAgentId,
+                                    taskId: newTaskId,
+                                    personaId: 'plain',
+                                    status: 'working',
+                                    name: agentName,
+                                    createdAt: new Date().toISOString(),
+                                };
+                                mutateBatch([
+                                    { path: `tasks.${newTaskId}`, value: newTask },
+                                    { path: `agents.${newAgentId}`, value: newAgent },
+                                ]);
+                                broadcastTask(newTaskId);
+                                broadcastAgent(newAgentId);
+                                // Notify the master chat so the "Delegated to <name>" badge renders.
+                                // Intentionally omit planId — this worker is a free agent, not part of any plan.
+                                ws.send(JSON.stringify({
+                                    type: 'gekto_delegate',
+                                    agentId: newAgentId,
+                                    agentName,
+                                    message: planResult.message || `Delegated to ${agentName}.`,
+                                }));
+                                // Fire-and-forget: send the prompt to the new worker's session.
+                                sendMessage(newAgentId, workerPrompt, ws).catch(err => {
+                                    console.error(`[Agent] Spawn delegate to ${newAgentId} failed:`, err);
+                                });
+                            }
                             else if (planResult.type === 'chat') {
                                 // Restore plan state — only delete if it was a temporary entry
                                 if (msg.planId && getState().activePlans[msg.planId]?.status === 'planning') {

package/dist/agents/gektoPersistent.js

@@ -8,7 +8,7 @@ export const GEKTO_OUTPUT_SCHEMA = JSON.stringify({
     properties: {
         action: {
             type: 'string',
-            enum: ['create_plan', 'reply', 'clarify', 'remove_agents', 'update_plan', 'delegate', 'add_task'],
+            enum: ['create_plan', 'reply', 'clarify', 'remove_agents', 'update_plan', 'delegate', 'add_task', 'spawn_agent'],
         },
         message: { type: 'string' },
         title: { type: 'string' },
@@ -16,6 +16,7 @@ export const GEKTO_OUTPUT_SCHEMA = JSON.stringify({
         buildPrompt: { type: 'string' },
         target: { type: 'string' },
         agentId: { type: 'string' },
+        agentName: { type: 'string' },
         taskName: { type: 'string' },
         taskDescription: { type: 'string' },
         taskFiles: { type: 'array', items: { type: 'string' } },
@@ -40,6 +41,7 @@ How you act:
 - If the user wants to modify the active plan (marked [ACTIVE] in CURRENT STATE), use "update_plan" with the updated abstract. "update_plan" ALWAYS applies to the active plan. You MUST also include a short "message" for the chat confirming what changed.
 - If the user wants to remove agents, use "remove_agents" with a target.
 - If there is an existing agent that has context about the relevant files or task, use "delegate" with "agentId" (the agent's ID from CURRENT STATE) and "message" (a clear instruction). The agent already has session context — delegating is faster than creating a new plan. Always include a short "message" for the chat confirming what you delegated.
+- If the user wants a single piece of work handed off and no existing agent fits (e.g. they invoked "/delegate" and none of the active agents match), use "spawn_agent" — it creates one new worker without a multi-step plan. Provide: "agentName" (2-3 word descriptive name, e.g. "AuthRefactor" or "ApiDocs"), "taskDescription" (1 sentence describing what the worker will do), and "message" (the full self-contained, actionable prompt that will be sent to the new worker). Use "spawn_agent" instead of "create_plan" when the work is a single agent's job, not a multi-step plan.
 - ALWAYS research the codebase first (Read, Glob, Grep) before creating plans. Understand the project structure, frameworks, and conventions.
 
 Conflict awareness:

package/dist/agents/gektoTools.js

@@ -219,6 +219,20 @@ If the user wants to change this plan, respond with "update_plan" and the FULL u
                 delegateMessage: parsed.message,
                 message: parsed.message,
             };
+        case 'spawn_agent': {
+            const agentName = (parsed.agentName || parsed.taskName || 'Worker').trim();
+            const taskDescription = (parsed.taskDescription || parsed.message || 'Handle delegated task').trim();
+            const workerPrompt = (parsed.message || prompt).trim();
+            return {
+                type: 'spawn_agent',
+                spawn: {
+                    agentName,
+                    taskDescription,
+                    prompt: workerPrompt,
+                },
+                message: `Delegated to ${agentName}.`,
+            };
+        }
         default:
             return { type: 'chat', message: parsed.message || "I'm not sure how to help with that." };
     }

package/dist/detectClaude.js

@@ -0,0 +1,14 @@
+import { execFile } from 'node:child_process';
+import { CLAUDE_PATH } from './claudePath.js';
+export function detectClaude() {
+    return new Promise(resolve => {
+        const opts = { timeout: 3000, shell: process.platform === 'win32' };
+        execFile(CLAUDE_PATH, ['--version'], opts, (err, stdout) => {
+            if (err)
+                return resolve({ available: false });
+            const out = stdout.trim();
+            const version = (out.match(/\d+\.\d+\.\d+[^\s)]*/) || [out])[0];
+            resolve({ available: true, version, path: CLAUDE_PATH });
+        });
+    });
+}

package/dist/inspectRepo.js

@@ -0,0 +1,185 @@
+import { spawn } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import path from 'node:path';
+import { CLAUDE_PATH } from './claudePath.js';
+export const DEV_TEST_APP_DIR = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '../../test-app');
+const INSPECT_PROMPT = `You are inspecting a software project to auto-configure a dev tool called Gekto.
+
+Use Glob, Grep, and Read (read-only) to look at the project's manifest and config files. Likely candidates:
+- package.json, pyproject.toml, requirements.txt, Cargo.toml, go.mod, Gemfile, composer.json, pom.xml, build.gradle(.kts), mix.exs, *.csproj
+- vite.config.*, next.config.*, astro.config.*, nuxt.config.*, angular.json, webpack.config.*, rollup.config.*
+- .env, .env.local, .env.development
+- Dockerfile, docker-compose.yml, Procfile
+
+Return ONLY a single JSON object — no prose, no markdown fences — with exactly this shape:
+
+{
+  "language": "<primary language, lowercase: typescript, javascript, python, go, ruby, rust, java, kotlin, csharp, php, elixir, swift, etc.>",
+  "framework": "<main UI / meta-framework / app framework, lowercase — see rules below>",
+  "bundler": "<build tool, lowercase: vite, webpack, turbopack, esbuild, rollup, parcel, rspack — or null>",
+  "runtime": "<runtime, e.g. node, bun, deno, python, ruby, go, jvm, dotnet, php — or null>",
+  "packageManager": "<e.g. npm, pnpm, yarn, bun, pip, poetry, uv, cargo, gem, composer, maven, gradle — or null>",
+  "hasWebUI": true | false,
+  "port": <integer dev-server port, or null>,
+  "devCommand": "<shell command to start the dev server, e.g. 'npm run dev', 'pnpm dev', 'bun dev', 'python manage.py runserver', 'flask run', 'uvicorn app:app --reload', 'rails server' — or null if uncertain>"
+}
+
+Framework field rules (read carefully — this is the most common mistake):
+- "framework" is the **UI library or app framework**, NOT the bundler. Vite, Webpack, Turbopack, esbuild, Rollup, Parcel, Rspack are **bundlers** — they go in the "bundler" field, never in "framework".
+- For frontend projects, prefer the UI library: "react", "vue", "svelte", "solid", "preact", "lit". Detect this from package.json dependencies (e.g. presence of "react", "vue", "svelte", "solid-js").
+- If the project uses a meta-framework (which implies its own UI library), use the meta-framework name instead: "next", "nuxt", "sveltekit", "remix", "astro", "gatsby", "qwik", "angular".
+- For backend projects, use the server framework: "express", "nestjs", "fastify", "koa", "hono", "django", "flask", "fastapi", "rails", "sinatra", "laravel", "symfony", "spring-boot", "phoenix", "actix", "axum", "gin", "echo".
+- If nothing identifiable, set framework to null.
+
+Other rules:
+- "hasWebUI" is true if the project serves a web frontend that runs on a dev server. Backend-only servers, CLI tools, mobile apps, and libraries: false.
+- "port" must be an integer when hasWebUI is true. Use the explicit port from config if found; otherwise the framework/bundler default (Vite 5173, Next 3000, CRA 3000, Astro 4321, Nuxt 3000, Angular 4200, SvelteKit 5173, Webpack-dev-server 8080).
+- "port" must be null when hasWebUI is false.
+- "devCommand" should be the canonical way to start the dev server based on the package manager (check the lockfile) and the framework. For JS projects: read package.json "scripts" — prefer "dev", then "start", then "serve". Use the right package manager (pnpm/yarn/bun/npm) based on the lockfile. Set null if you can't determine it.
+- Output JSON only, nothing else.`;
+function summarizeTool(name, input) {
+    if (!input)
+        return name;
+    switch (name) {
+        case 'Read':
+            return `Reading ${String(input.file_path ?? '').split('/').pop() || input.file_path}`;
+        case 'Glob':
+            return `Searching for ${input.pattern}`;
+        case 'Grep':
+            return `Grep "${input.pattern}"${input.path ? ` in ${input.path}` : ''}`;
+        default:
+            return name;
+    }
+}
+function parseStack(text) {
+    const jsonMatch = text.match(/\{[\s\S]*\}/);
+    if (!jsonMatch)
+        return null;
+    try {
+        const parsed = JSON.parse(jsonMatch[0]);
+        if (!parsed.language || typeof parsed.hasWebUI !== 'boolean')
+            return null;
+        const port = typeof parsed.port === 'number' ? parsed.port : undefined;
+        return {
+            language: String(parsed.language).toLowerCase(),
+            framework: parsed.framework ? String(parsed.framework).toLowerCase() : undefined,
+            bundler: parsed.bundler ? String(parsed.bundler).toLowerCase() : undefined,
+            runtime: parsed.runtime ? String(parsed.runtime).toLowerCase() : undefined,
+            packageManager: parsed.packageManager ? String(parsed.packageManager).toLowerCase() : undefined,
+            hasWebUI: parsed.hasWebUI,
+            port: parsed.hasWebUI ? port : undefined,
+            devCommand: typeof parsed.devCommand === 'string' && parsed.devCommand.trim() ? parsed.devCommand.trim() : undefined,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export async function inspectRepo(opts = {}) {
+    const prompt = opts.correction
+        ? `${INSPECT_PROMPT}\n\nIMPORTANT: A previous inspection was incorrect. The user said:\n"${opts.correction}"\n\nRe-inspect the project, taking this correction into account. Verify against the actual files before answering.`
+        : INSPECT_PROMPT;
+    if (opts.dry) {
+        console.log('--- inspectRepo prompt ---');
+        console.log(prompt);
+        return null;
+    }
+    const args = [
+        '-p', prompt,
+        '--output-format', 'stream-json',
+        '--verbose',
+        '--model', 'claude-opus-4-6',
+        '--dangerously-skip-permissions',
+        '--allowed-tools', 'Read,Glob,Grep',
+    ];
+    return new Promise(resolve => {
+        const proc = spawn(CLAUDE_PATH, args, {
+            cwd: opts.cwd || process.cwd(),
+            env: process.env,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        proc.stdin?.end();
+        const timeout = setTimeout(() => {
+            proc.kill('SIGTERM');
+        }, opts.timeoutMs ?? 60_000);
+        let buffer = '';
+        let resultText = '';
+        const handleLine = (line) => {
+            if (!line.trim())
+                return;
+            try {
+                const event = JSON.parse(line);
+                if (event.type === 'assistant' && event.message?.content) {
+                    for (const block of event.message.content) {
+                        if (block.type === 'tool_use' && block.name) {
+                            opts.onEvent?.({
+                                type: 'tool',
+                                name: block.name,
+                                summary: summarizeTool(block.name, block.input),
+                            });
+                        }
+                        else if (block.type === 'text' && block.text) {
+                            opts.onEvent?.({ type: 'text', text: block.text });
+                        }
+                        else if (block.type === 'thinking' && block.thinking) {
+                            opts.onEvent?.({ type: 'thinking', text: block.thinking });
+                        }
+                    }
+                }
+                else if (event.type === 'result' && typeof event.result === 'string') {
+                    resultText = event.result;
+                }
+            }
+            catch {
+                // ignore parse errors on partial / non-JSON lines
+            }
+        };
+        proc.stdout.on('data', chunk => {
+            buffer += chunk.toString();
+            const lines = buffer.split('\n');
+            buffer = lines.pop() || '';
+            for (const line of lines)
+                handleLine(line);
+        });
+        proc.stderr.on('data', () => { });
+        proc.on('close', () => {
+            clearTimeout(timeout);
+            if (buffer.trim())
+                handleLine(buffer);
+            resolve(parseStack(resultText));
+        });
+        proc.on('error', () => {
+            clearTimeout(timeout);
+            resolve(null);
+        });
+    });
+}
+export function describeStack(stack) {
+    const parts = [
+        stack.framework,
+        stack.language,
+        stack.bundler && stack.bundler !== stack.framework ? `bundler:${stack.bundler}` : null,
+        stack.runtime,
+        stack.packageManager,
+        stack.hasWebUI ? `port:${stack.port ?? '?'}` : 'no-ui',
+    ].filter(Boolean);
+    return parts.join(' · ');
+}
+// CLI entry — `bun run src/inspectRepo.ts [--dry] [--dev]`
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const dry = process.argv.includes('--dry');
+    const dev = process.argv.includes('--dev');
+    const cwd = dev ? DEV_TEST_APP_DIR : process.cwd();
+    if (dev)
+        console.log(`[inspectRepo] dev mode — inspecting ${cwd}`);
+    const result = await inspectRepo({
+        dry,
+        cwd,
+        onEvent: event => {
+            if (event.type === 'tool')
+                console.log(`  · ${event.summary}`);
+        },
+    });
+    console.log('\nInspection:', result);
+    process.exit(0);
+}

package/dist/onboarding.js

@@ -0,0 +1,339 @@
+import * as p from '@clack/prompts';
+import { fileURLToPath } from 'node:url';
+import { detectClaude } from './detectClaude.js';
+import { inspectRepo, describeStack, DEV_TEST_APP_DIR } from './inspectRepo.js';
+import { isPortInUse, waitForPort, startDevServer } from './portUtils.js';
+import { getPostHog, getDistinctId, initDistinctId } from './posthog.js';
+const c = {
+    reset: '\x1b[0m',
+    bold: '\x1b[1m',
+    dim: '\x1b[2m',
+    green: '\x1b[32m',
+    white: '\x1b[37m',
+};
+const FALLBACK_STACK = {
+    language: 'unknown',
+    hasWebUI: true,
+    port: 3000,
+};
+async function saveLeadToSheetDB(data) {
+    try {
+        await fetch('https://sheetdb.io/api/v1/hxn1hd5nzjxhd?sheet=Leads', {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                data: {
+                    email: data.email,
+                    is_using_claude: data.isUsingClaude ? 'Yes' : 'No',
+                    source: 'tui_onboarding',
+                },
+            }),
+        });
+    }
+    catch {
+        // Silently fail - don't block onboarding
+    }
+}
+function printStack(stack) {
+    const row = (label, value) => p.log.info(`${c.dim}${label.padEnd(11)}${c.reset} ${value ?? '(none)'}`);
+    row('Language:', stack.language);
+    row('Framework:', stack.framework);
+    row('Bundler:', stack.bundler);
+    row('Runtime:', stack.runtime);
+    row('Package mgr:', stack.packageManager);
+    row('Web UI:', stack.hasWebUI ? 'yes' : 'no');
+    row('Port:', stack.hasWebUI ? stack.port : null);
+    row('Dev cmd:', stack.hasWebUI ? stack.devCommand : null);
+}
+function cap(s) {
+    if (!s)
+        return '';
+    return s.charAt(0).toUpperCase() + s.slice(1);
+}
+function describeProject(stack) {
+    if (stack.hasWebUI) {
+        const what = stack.framework ? `${cap(stack.framework)} app` : `${cap(stack.language)} app`;
+        const portPart = stack.port ? ` that runs on port ${stack.port}` : '';
+        return `Looks like it's a ${what}${portPart}. Gekto can run on top of your app.`;
+    }
+    const langPart = cap(stack.language);
+    const fwPart = stack.framework ? ` and ${cap(stack.framework)} framework` : '';
+    return `Hmm, I suggest this is a backend app that uses ${langPart}${fwPart}. There is no visual layer, only data — Gekto will run its widget standalone.`;
+}
+export async function runOnboarding(opts = {}) {
+    const dev = opts.dev ?? false;
+    const proxyPort = opts.defaultProxyPort ?? 3200;
+    let stack = { ...FALLBACK_STACK };
+    console.clear();
+    // Claude Code check — must come before anything else
+    const claudeSpinner = p.spinner();
+    claudeSpinner.start('Looking for installed Claude Code...');
+    const [claude] = await Promise.all([
+        opts.fakeNoClaude ? Promise.resolve({ available: false }) : detectClaude(),
+        new Promise(resolve => setTimeout(resolve, 1000)),
+    ]);
+    if (!claude.available) {
+        claudeSpinner.stop('Claude Code not found on PATH');
+        p.log.warn('Gekto requires the Claude Code CLI to run.');
+        p.log.info(`Install it:  ${c.white}npm install -g @anthropic-ai/claude-code${c.reset}`);
+        p.log.info(`Docs:        ${c.white}https://docs.claude.com/en/docs/claude-code${c.reset}`);
+        p.cancel('Install Claude Code, then run gekto again.');
+        process.exit(1);
+    }
+    claudeSpinner.stop(`Claude Code v${claude.version} detected`);
+    const fs = await import('fs');
+    const path = await import('path');
+    const STORE_PATH = path.join(process.cwd(), 'gekto-store.json');
+    const loadSettings = () => {
+        if (dev)
+            return undefined;
+        try {
+            if (fs.existsSync(STORE_PATH)) {
+                const store = JSON.parse(fs.readFileSync(STORE_PATH, 'utf8'));
+                const settings = store.data?.settings;
+                if (settings?.stack && typeof settings.stack.hasWebUI === 'boolean')
+                    return settings;
+            }
+        }
+        catch { }
+        return undefined;
+    };
+    const saveSettings = (settings) => {
+        if (dev)
+            return;
+        let store = { version: 1, createdAt: new Date().toISOString(), updatedAt: new Date().toISOString(), data: {} };
+        try {
+            if (fs.existsSync(STORE_PATH)) {
+                store = JSON.parse(fs.readFileSync(STORE_PATH, 'utf8'));
+            }
+        }
+        catch { }
+        store.data.settings = settings;
+        store.updatedAt = new Date().toISOString();
+        fs.writeFileSync(STORE_PATH, JSON.stringify(store, null, 2));
+    };
+    const existingSettings = opts.force ? undefined : loadSettings();
+    if (existingSettings?.onboardingCompleted) {
+        initDistinctId(existingSettings.email);
+        console.log(`${c.dim}Loaded settings from gekto-store.json${c.reset}`);
+        return { stack: existingSettings.stack, proxyPort: existingSettings.proxyPort };
+    }
+    p.intro(`${c.green}${c.bold}create-gekto${c.reset}${dev ? `  ${c.dim}(dev mode — not persisting)${c.reset}` : ''}`);
+    // Optional: agent-based repo inspection (requires explicit consent)
+    let inspection = null;
+    const inspectAnswer = await p.confirm({
+        message: 'Inspect this repo with Claude to detect your tech stack? (read-only)',
+        initialValue: true,
+    });
+    if (p.isCancel(inspectAnswer)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+    }
+    if (inspectAnswer) {
+        const inspectSpinner = p.spinner();
+        inspectSpinner.start('Inspecting repository...');
+        inspection = await inspectRepo({
+            cwd: dev ? DEV_TEST_APP_DIR : process.cwd(),
+            onEvent: event => {
+                if (event.type === 'tool')
+                    inspectSpinner.message(event.summary);
+            },
+        });
+        if (inspection) {
+            inspectSpinner.stop(`Detected: ${describeStack(inspection)}`);
+        }
+        else {
+            inspectSpinner.stop('Inspection failed — continuing with manual setup');
+        }
+    }
+    // If inspection succeeded, show summary + narrative, then loop: agree / correct / manual.
+    let confirmedFromInspection = false;
+    let current = inspection;
+    while (current) {
+        printStack(current);
+        p.note(describeProject(current));
+        const choice = await p.select({
+            message: 'Agree?',
+            options: [
+                { label: 'Yes, continue', value: 'yes' },
+                { label: 'No, tell agent where he is wrong', value: 'tell' },
+                { label: 'No, setup manually', value: 'manual' },
+            ],
+        });
+        if (p.isCancel(choice)) {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        }
+        if (choice === 'yes') {
+            stack = current;
+            confirmedFromInspection = true;
+            inspection = current;
+            break;
+        }
+        if (choice === 'manual') {
+            inspection = current;
+            break;
+        }
+        // choice === 'tell' — re-inspect with user's correction
+        const correction = await p.text({
+            message: 'What did Claude get wrong?',
+            placeholder: "e.g. it's actually a Vue 3 app, not React",
+        });
+        if (p.isCancel(correction)) {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        }
+        if (!correction.trim())
+            continue;
+        const refineSpinner = p.spinner();
+        refineSpinner.start('Re-inspecting with your correction...');
+        const refined = await inspectRepo({
+            cwd: dev ? DEV_TEST_APP_DIR : process.cwd(),
+            correction,
+            onEvent: event => {
+                if (event.type === 'tool')
+                    refineSpinner.message(event.summary);
+            },
+        });
+        if (refined) {
+            current = refined;
+            refineSpinner.stop(`Updated: ${describeStack(refined)}`);
+        }
+        else {
+            refineSpinner.stop('Re-inspection failed — keeping previous detection');
+        }
+    }
+    if (!confirmedFromInspection) {
+        // Manual override — only ask what actually affects behavior: hasWebUI + port.
+        // Keep detected lang/framework/etc. as descriptive metadata.
+        const hasWebUIAnswer = await p.confirm({
+            message: 'Does this project have a web UI Gekto should proxy?',
+            initialValue: inspection?.hasWebUI ?? true,
+        });
+        if (p.isCancel(hasWebUIAnswer)) {
+            p.cancel('Setup cancelled.');
+            process.exit(0);
+        }
+        let port;
+        if (hasWebUIAnswer) {
+            const detectedPort = inspection?.port ? String(inspection.port) : '3000';
+            const portAnswer = await p.text({
+                message: 'What port is your dev server running on?',
+                placeholder: detectedPort,
+                defaultValue: detectedPort,
+            });
+            if (p.isCancel(portAnswer)) {
+                p.cancel('Setup cancelled.');
+                process.exit(0);
+            }
+            port = parseInt(portAnswer, 10);
+        }
+        stack = {
+            language: inspection?.language ?? 'unknown',
+            framework: inspection?.framework,
+            bundler: inspection?.bundler,
+            runtime: inspection?.runtime,
+            packageManager: inspection?.packageManager,
+            hasWebUI: hasWebUIAnswer,
+            port,
+        };
+    }
+    const emailAnswer = await p.text({
+        message: 'Enter your email for updates',
+        placeholder: 'you@example.com',
+    });
+    if (p.isCancel(emailAnswer)) {
+        p.cancel('Setup cancelled.');
+        process.exit(0);
+    }
+    const email = emailAnswer || '';
+    // If the project has a web UI and a port, verify the dev server is up — or offer to start it.
+    if (stack.hasWebUI && stack.port) {
+        const cwd = dev ? DEV_TEST_APP_DIR : process.cwd();
+        const portUsed = await isPortInUse(stack.port);
+        if (!portUsed) {
+            const options = [];
+            if (stack.devCommand) {
+                options.push({ label: `Yes, start using "${stack.devCommand}"`, value: 'detected' });
+            }
+            options.push({ label: 'Yes, write command', value: 'custom' });
+            options.push({ label: 'Not now', value: 'skip' });
+            const startChoice = await p.select({
+                message: `Your app isn't running on port ${stack.port}. Start it?`,
+                options,
+            });
+            if (p.isCancel(startChoice)) {
+                p.cancel('Setup cancelled.');
+                process.exit(0);
+            }
+            let command = null;
+            if (startChoice === 'detected') {
+                command = stack.devCommand;
+            }
+            else if (startChoice === 'custom') {
+                const cmdDefault = stack.devCommand || 'npm run dev';
+                const cmdAnswer = await p.text({
+                    message: 'Command to start your dev server:',
+                    placeholder: cmdDefault,
+                    defaultValue: cmdDefault,
+                });
+                if (p.isCancel(cmdAnswer)) {
+                    p.cancel('Setup cancelled.');
+                    process.exit(0);
+                }
+                command = (cmdAnswer || cmdDefault).trim();
+            }
+            if (command) {
+                const launchSpinner = p.spinner();
+                launchSpinner.start(`Starting "${command}"...`);
+                startDevServer(command, cwd);
+                const opened = await waitForPort(stack.port, 60_000, elapsed => {
+                    launchSpinner.message(`Waiting for port ${stack.port}... (${Math.floor(elapsed / 1000)}s)`);
+                });
+                if (opened) {
+                    launchSpinner.stop(`Your app is up on port ${stack.port}`);
+                }
+                else {
+                    launchSpinner.stop(`Timed out waiting for port ${stack.port} — Gekto will start anyway`);
+                }
+            }
+        }
+    }
+    const spinner = p.spinner();
+    spinner.start(dev ? 'Finishing (dev mode — skipping persistence)...' : 'Preparing Gekto...');
+    if (!dev) {
+        await saveLeadToSheetDB({
+            email,
+            isUsingClaude: claude.available,
+        });
+    }
+    saveSettings({ stack, proxyPort, onboardingCompleted: true, email });
+    initDistinctId(email);
+    getPostHog().capture({
+        distinctId: getDistinctId(),
+        event: 'onboarding completed',
+        properties: {
+            language: stack.language,
+            framework: stack.framework,
+            bundler: stack.bundler,
+            runtime: stack.runtime,
+            has_web_ui: stack.hasWebUI,
+            port: stack.port,
+            has_email: Boolean(email),
+            dev_mode: dev,
+            $set: email ? { email } : undefined,
+            $set_once: { initial_language: stack.language, initial_framework: stack.framework },
+        },
+    });
+    spinner.stop('Ready!');
+    p.outro(`${c.green}Starting Gekto...${c.reset}`);
+    return { stack, proxyPort };
+}
+// CLI entry — run `bun run src/onboarding.ts [--dev] [--no-claude]`
+if (process.argv[1] === fileURLToPath(import.meta.url)) {
+    const dev = process.argv.includes('--dev');
+    const fakeNoClaude = process.argv.includes('--no-claude');
+    const result = await runOnboarding({ dev, fakeNoClaude });
+    console.log('\nResult:', result);
+    process.exit(0);
+}