@codeyam/codeyam-cli 0.1.0-staging.2a88920 → 0.1.0-staging.30dc541

package/codeyam-cli/src/webserver/terminalServer.js

@@ -0,0 +1,897 @@
+var _a, _b;
+import { WebSocketServer, WebSocket } from 'ws';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
+import * as pty from 'node-pty';
+import { createMarkerTransformer } from "../utils/scenarioMarkers.js";
+import { IdleDetector } from "./idleDetector.js";
+import { mockStateEventEmitter } from "./mockStateEvents.js";
+/**
+ * Strip the raw `claude ...` shell command from suppressed PTY output
+ * so it doesn't leak to the user in the fallback timeout path.
+ */
+export function stripClaudeCommand(output) {
+    return output.replace(/[^\r\n]*claude\s[^\r\n]*[\r\n]*/, '');
+}
+/**
+ * Manages PTY output suppression during Claude startup.
+ *
+ * Suppresses all output until the `╭` welcome banner arrives, then clears
+ * the screen. The claude command is stripped from any chunk that is forwarded
+ * (both the banner chunk on the normal path and the buffered output on the
+ * fallback timeout path).
+ */
+export class StartupOutputFilter {
+    constructor() {
+        this.hasClearedScreen = false;
+        this.suppressedOutput = '';
+    }
+    /**
+     * Process a PTY data chunk. Returns an object describing what action to take:
+     * - `type: 'suppress'` — buffer the chunk, send nothing
+     * - `type: 'clear-and-send'` — clear screen, then send `data`
+     * - `type: 'send'` — send `data` as-is (post-startup)
+     */
+    processChunk(data) {
+        if (!this.hasClearedScreen && data.includes('╭')) {
+            this.hasClearedScreen = true;
+            const cleaned = stripClaudeCommand(data);
+            return { type: 'clear-and-send', data: cleaned };
+        }
+        if (!this.hasClearedScreen) {
+            this.suppressedOutput += data;
+            return { type: 'suppress' };
+        }
+        return { type: 'send', data };
+    }
+    /**
+     * Called when the fallback timeout fires (╭ never arrived).
+     * Returns the buffered output with the command stripped, or null if
+     * the screen was already cleared.
+     */
+    getTimeoutOutput() {
+        if (this.hasClearedScreen)
+            return null;
+        this.hasClearedScreen = true;
+        if (this.suppressedOutput.length === 0)
+            return null;
+        const cleaned = stripClaudeCommand(this.suppressedOutput);
+        return cleaned.length > 0 ? cleaned : null;
+    }
+}
+// Use globalThis so the sessions Set is shared across module instances.
+// In Vite dev mode, this file is loaded twice: once by the Vite plugin (Node.js native)
+// and once by the SSR context (ssrLoadModule). Without globalThis, each instance
+// gets its own empty Set — so broadcastPreviewRefresh() called from the SSR instance
+// (via the /api/dev-mode-preview endpoint) would broadcast to 0 sessions.
+const sessions = ((_a = globalThis).__codeyamTerminalSessions ?? (_a.__codeyamTerminalSessions = new Set()));
+// Detached PTYs waiting for reconnection (keyed by sessionId).
+// When a WebSocket drops, the PTY is moved here with a grace timer
+// instead of being killed immediately, allowing the client to reconnect.
+const detachedPtys = ((_b = globalThis).__codeyamDetachedPtys ?? (_b.__codeyamDetachedPtys = new Map()));
+const PING_INTERVAL_MS = 30000;
+const DETACH_GRACE_MS = 60000;
+const OUTPUT_BUFFER_MAX = 8 * 1024; // 8KB
+// Ping interval reference — shared so cleanup can clear it
+let pingInterval = globalThis.__codeyamPingInterval ?? null;
+// Keys to forward from the server env into the PTY shell.
+// Keeps the env clean (no giant CODEYAM_PROJECT JSON blobs) while
+// preserving everything Claude Code and the user's shell need.
+const ENV_PASSTHROUGH_KEYS = [
+    'PATH',
+    'HOME',
+    'USER',
+    'LOGNAME',
+    'SHELL',
+    'TERM',
+    'LANG',
+    'LC_ALL',
+    'LC_CTYPE',
+    'EDITOR',
+    'VISUAL',
+    'TMPDIR',
+    'XDG_CONFIG_HOME',
+    'XDG_DATA_HOME',
+    'XDG_CACHE_HOME',
+    // API keys Claude Code may need
+    'ANTHROPIC_API_KEY',
+    'OPENAI_API_KEY',
+    // nvm / fnm / volta node version managers
+    'NVM_DIR',
+    'NVM_BIN',
+    'FNM_DIR',
+    'VOLTA_HOME',
+    // Homebrew
+    'HOMEBREW_PREFIX',
+    'HOMEBREW_CELLAR',
+    'HOMEBREW_REPOSITORY',
+];
+export function buildPtyEnv(options) {
+    const env = {};
+    for (const key of ENV_PASSTHROUGH_KEYS) {
+        const val = process.env[key];
+        if (val != null)
+            env[key] = val;
+    }
+    // Always set TERM for proper terminal behavior
+    if (!env.TERM)
+        env.TERM = 'xterm-256color';
+    // Signal to hooks that this is an editor Build session.
+    // Without this, editor hooks fire in ALL Claude sessions in the project.
+    if (options?.editorMode) {
+        env.CODEYAM_EDITOR_ACTIVE = '1';
+    }
+    return env;
+}
+/**
+ * Convert a name to a safe file name matching CodeYam's convention.
+ * e.g. "Default Scenario" -> "Default_Scenario"
+ */
+function safeFileName(name) {
+    const safe = name.replace(/[^a-zA-Z0-9_]+/g, '_').replace(/^_+|_+$/g, '');
+    return safe.slice(0, 1).toUpperCase() + safe.slice(1);
+}
+/**
+ * Find the actual mock data file for a scenario in the tmp project.
+ * Tries a fast heuristic (extract app dir from entity file path) first,
+ * then falls back to a shallow directory search.
+ */
+function findMockDataFile(projectRoot, entityFilePath, scenarioName) {
+    const scenarioSlug = safeFileName(scenarioName);
+    const mockFile = `MockData_${scenarioSlug}.tsx`;
+    // Heuristic: the __codeyamMocks__ dir lives at the app directory level.
+    // Extract "app/" (or "src/", "pages/") from the entity's file path.
+    if (entityFilePath) {
+        const parts = entityFilePath.split('/');
+        for (let i = 0; i < parts.length; i++) {
+            if (['app', 'src', 'pages'].includes(parts[i])) {
+                const appDir = parts.slice(0, i + 1).join('/');
+                const candidate = path.join(projectRoot, appDir, '__codeyamMocks__', mockFile);
+                if (fs.existsSync(candidate))
+                    return candidate;
+            }
+        }
+    }
+    // Fallback: search __codeyamMocks__ directories up to 5 levels deep
+    function searchDir(dir, depth) {
+        if (depth > 5)
+            return null;
+        try {
+            for (const entry of fs.readdirSync(dir)) {
+                if (entry === 'node_modules' ||
+                    entry === '.git' ||
+                    entry === 'coverage')
+                    continue;
+                const full = path.join(dir, entry);
+                if (entry === '__codeyamMocks__') {
+                    const candidate = path.join(full, mockFile);
+                    if (fs.existsSync(candidate))
+                        return candidate;
+                    continue;
+                }
+                try {
+                    if (fs.statSync(full).isDirectory()) {
+                        const result = searchDir(full, depth + 1);
+                        if (result)
+                            return result;
+                    }
+                }
+                catch {
+                    // Permission error or broken symlink
+                }
+            }
+        }
+        catch {
+            // Directory unreadable
+        }
+        return null;
+    }
+    return searchDir(projectRoot, 0);
+}
+/**
+ * Write a structured context file for the codeyam-dev-mode skill.
+ * The skill reads this file on startup instead of receiving a long CLI argument.
+ * Returns true if context was written successfully, false otherwise.
+ */
+function writeDevModeContext(ctx) {
+    if (!ctx.entityName)
+        return false;
+    const codeyamRoot = process.env.CODEYAM_ROOT_PATH || process.cwd();
+    const contextDir = path.join(codeyamRoot, '.codeyam');
+    const contextPath = path.join(contextDir, 'dev-mode-context.md');
+    try {
+        fs.mkdirSync(contextDir, { recursive: true });
+        const lines = ['# Dev Mode Context', ''];
+        // Entity section
+        lines.push('## Entity');
+        lines.push(`- **Name:** ${ctx.entityName}`);
+        if (ctx.entityType)
+            lines.push(`- **Type:** ${ctx.entityType}`);
+        if (ctx.entitySha)
+            lines.push(`- **SHA:** ${ctx.entitySha}`);
+        if (ctx.entityFilePath)
+            lines.push(`- **Source file:** ${ctx.entityFilePath}`);
+        lines.push('');
+        // Scenario section
+        if (ctx.scenarioName) {
+            lines.push('## Scenario');
+            lines.push(`- **Name:** ${ctx.scenarioName}`);
+            if (ctx.scenarioDescription)
+                lines.push(`- **Description:** ${ctx.scenarioDescription}`);
+            if (ctx.analysisId)
+                lines.push(`- **Analysis ID:** ${ctx.analysisId}`);
+            lines.push('');
+        }
+        // Files section
+        lines.push('## Files');
+        if (ctx.entityFilePath) {
+            lines.push(`- **Source file:** ${ctx.entityFilePath}`);
+        }
+        if (ctx.projectSlug && ctx.scenarioName) {
+            const tmpBase = `/tmp/codeyam/local-dev/${ctx.projectSlug}`;
+            const tmpProject = `${tmpBase}/project`;
+            const mockDataPath = findMockDataFile(tmpProject, ctx.entityFilePath, ctx.scenarioName);
+            if (mockDataPath) {
+                lines.push(`- **Mock data:** ${mockDataPath}`);
+            }
+            else {
+                const scenarioSlug = safeFileName(ctx.scenarioName);
+                lines.push(`- **Mock data:** search for \`MockData_${scenarioSlug}.tsx\` in \`__codeyamMocks__\` under ${tmpProject}`);
+            }
+            lines.push(`- **Dev server project:** ${tmpProject}`);
+            lines.push(`- **Server log:** ${tmpBase}/codeyam/log.txt`);
+        }
+        lines.push('');
+        // Database
+        lines.push('## Database');
+        lines.push(`- **Path:** .codeyam/db.sqlite3`);
+        lines.push('');
+        // Server
+        const serverPort = process.env.CODEYAM_PORT || '3111';
+        lines.push('## Server');
+        lines.push(`- **Refresh preview:** \`curl -X POST http://localhost:${serverPort}/api/dev-mode-preview -H 'Content-Type: application/json' -d '{"dimension":"Desktop"}'\` (dimension is REQUIRED)`);
+        lines.push('');
+        fs.writeFileSync(contextPath, lines.join('\n'), 'utf8');
+        return true;
+    }
+    catch (error) {
+        console.error('[terminalServer] Failed to write dev-mode-context.md:', error);
+        return false;
+    }
+}
+/**
+ * Write a structured context file for the codeyam-editor skill.
+ * Returns true if context was written successfully, false otherwise.
+ */
+function writeEditorModeContext(ctx) {
+    if (!ctx.projectSlug)
+        return false;
+    const codeyamRoot = process.env.CODEYAM_ROOT_PATH || process.cwd();
+    const contextDir = path.join(codeyamRoot, '.codeyam');
+    const contextPath = path.join(contextDir, 'editor-mode-context.md');
+    try {
+        fs.mkdirSync(contextDir, { recursive: true });
+        const serverPort = process.env.CODEYAM_PORT || '3111';
+        const proxyPort = parseInt(serverPort, 10) + 1;
+        const lines = [
+            '# Editor Mode Context',
+            '',
+            '## Project',
+            `- **Root:** ${codeyamRoot}`,
+            `- **Slug:** ${ctx.projectSlug}`,
+            '',
+            '## Server',
+            `- **Port:** ${serverPort}`,
+            `- **Dashboard:** http://localhost:${serverPort}/editor`,
+            `- **Proxy:** http://localhost:${proxyPort} (used by the browser iframe only — do NOT use for health checks)`,
+            '',
+            '## Workflow',
+            '- **Guided steps:** Run `codeyam editor steps` for the next step (plan → prepare → prototype → verify prototype → confirm → deconstruct → extract → glossary → analyze → app scenarios → user scenarios → verify → journal → review → present → commit → finalize → push)',
+            '- Each feature follows 18 steps: `codeyam editor 1` through `codeyam editor 18`',
+            '- Steps 1, 5, 15, and 18 require user confirmation before proceeding',
+            '',
+            '## Preview Updates',
+            '- **Refresh the preview frequently** — the user watches the preview as you work. Refresh after every meaningful change (new page, UI section, data seeding, styling), not just at the end.',
+            `- **Refresh command:** \`curl -s -X POST http://localhost:${serverPort}/api/dev-mode-preview -H 'Content-Type: application/json' -d '{"dimension":"Desktop"}'\` (dimension is REQUIRED)`,
+            '- Aim for 4-8+ preview updates during a typical building session.',
+            '',
+            '## Verifying the Dev Server',
+            '- Get the dev server URL: `curl -s http://localhost:' +
+                serverPort +
+                '/api/editor-dev-server` → look at the `"url"` field (e.g., `http://localhost:3000`)',
+            '- Check the page loads: `curl -s -o /dev/null -w "%{http_code}" http://localhost:3000` (use the actual dev server URL, NOT the proxy)',
+            '- Check API routes work: `curl -s http://localhost:3000/api/your-route` (should return JSON, not "Internal Server Error")',
+            '- **NEVER check localhost:' +
+                proxyPort +
+                ' for health** — the proxy returns 200 even when the app is broken',
+            '',
+            '## API Endpoints',
+            `- **Register scenario (auto-captures screenshot):** \`codeyam editor register '{"name":"...","url":"/page-to-screenshot","type":"application","seed":{...}}'\` — ALWAYS include "url" for the page to screenshot. For large payloads, write JSON to a file and use @ prefix: \`codeyam editor register @/tmp/scenario.json\``,
+            `- **Get active scenario data:** \`curl http://localhost:${serverPort}/api/editor-scenario-data\``,
+            `- **Refresh/navigate/switch preview:** \`curl -X POST http://localhost:${serverPort}/api/dev-mode-preview -H 'Content-Type: application/json' -d '{"dimension":"Desktop"}'\` (dimension is REQUIRED in every call; add \`"path":"/route"\` to navigate; add \`"scenarioId":"..."\` to switch scenario). Clears logs, waits for HMR, checks SSR health.`,
+            `- **Refresh config:** \`curl -X POST http://localhost:${serverPort}/api/editor-refresh\` (also starts dev server if a webapp is detected)`,
+            `- **Dev server status:** \`curl http://localhost:${serverPort}/api/editor-dev-server\``,
+            `- **Start dev server:** \`curl -X POST http://localhost:${serverPort}/api/editor-dev-server -H 'Content-Type: application/json' -d '{"action":"start"}'\``,
+            `- **Restart dev server:** \`curl -X POST http://localhost:${serverPort}/api/editor-dev-server -H 'Content-Type: application/json' -d '{"action":"restart"}'\``,
+            `- **Re-capture scenario screenshot:** \`curl -X POST http://localhost:${serverPort}/api/editor-capture-scenario -H 'Content-Type: application/json' -d '{"scenarioId":"...","url":"..."}'\` (for manual re-capture; register auto-captures)`,
+            `- **Journal screenshot:** \`curl -X POST http://localhost:${serverPort}/api/editor-journal-screenshot -H 'Content-Type: application/json' -d '{"url":"...","filename":"..."}'\``,
+            `- **Journal entry:** \`curl -X POST http://localhost:${serverPort}/api/editor-journal-entry -H 'Content-Type: application/json' -d '{"title":"...","type":"feature","description":"..."}'\``,
+            '',
+            '## Scenario Data Format',
+            '- Use **route-keyed** mock data: keys are the API paths your app fetches',
+            '- Example: `{ "routes": { "/api/tasks": { "body": [...] }, "/api/users": { "body": [...] } } }`',
+            '- Error scenarios: `{ "routes": { "/api/tasks": { "status": 500, "body": { "error": "..." } } } }`',
+            '- The proxy intercepts GET requests to matching routes and returns the mock data',
+            '- POST/PUT/DELETE always go through to the real dev server',
+            '',
+            '## Component Isolation Routes',
+            '- Create isolation route dirs: `codeyam editor isolate ComponentA ComponentB ...`',
+            '  - This creates the layout guard and a directory per component under `app/isolated-components/`',
+            '- Create ONE isolation route page per component:',
+            '  - **Remix:** `app/routes/isolated-components.ComponentName.tsx` → `/isolated-components/ComponentName`',
+            '  - **Next.js:** `app/isolated-components/ComponentName/page.tsx` → `/isolated-components/ComponentName`',
+            '- The route defines a `scenarios` object mapping scenario names to props, reads `?s=ScenarioName` from the URL, and renders the component',
+            '- Wrap the component in a centered container: `<div style="display:flex;justify-content:center;align-items:center;min-height:100vh"><div style="width:100%;max-width:...">` — set max-width to match the component\'s real container (e.g. card in 3-col grid → 24rem)',
+            '- **Create multiple scenarios per component** (like tests): default/happy path, edge cases (empty data, long text, max items), different visual states (loading, error, disabled)',
+            '- Register each scenario: `codeyam editor register \'{"name":"ComponentName - Scenario","componentName":"ComponentName","componentPath":"path/to/file.tsx","url":"/isolated-components/ComponentName?s=Scenario","mockData":{"routes":{"/api/...":{"body":[...]}}}}\'`',
+            '- The url is a PATH, not a full URL — the proxy appends it and intercepts API calls the component makes',
+            '- `mockData.routes` provides data for any API calls the component makes internally (omit if none)',
+            '- Isolation routes stay in the project so the editor preview can display them',
+            '- Ensure `.gitignore` includes `**/isolated-components*` so they are not committed',
+            '',
+            '## Files',
+            '- **Scenario data:** .codeyam/editor-scenarios/{scenario-id}.json',
+            '- **Scenario screenshots:** .codeyam/editor-scenarios/screenshots/{scenario-id}.png',
+            '- **Active scenario:** .codeyam/active-scenario.json',
+            '- **Database:** .codeyam/db.sqlite3',
+            '- **Journal:** .codeyam/journal/ (daily .md files + index.json + screenshots/)',
+            '',
+        ];
+        // Check if package.json exists to give context about project state
+        const hasPackageJson = fs.existsSync(path.join(codeyamRoot, 'package.json'));
+        if (!hasPackageJson) {
+            lines.push('## Status');
+            lines.push('- **Empty project** — no package.json found. Ask the user what they want to build.');
+            lines.push('');
+        }
+        fs.writeFileSync(contextPath, lines.join('\n'), 'utf8');
+        return true;
+    }
+    catch (error) {
+        console.error('[terminalServer] Failed to write editor-mode-context.md:', error);
+        return false;
+    }
+}
+/**
+ * Attach a WebSocket server at /ws/terminal to an existing HTTP server.
+ * Each WS connection spawns a PTY running the user's shell, then auto-starts `claude`.
+ *
+ * Features:
+ * - Ping/pong keepalive (30s interval) to detect dead connections
+ * - PTY detach/reattach: on WS close the PTY survives for 60s, allowing the client
+ *   to reconnect with ?reconnectId=<sessionId> and reattach to the same PTY
+ * - Session IDs sent to client on connection for reconnect tracking
+ */
+export function attachTerminalServer(httpServer) {
+    const wss = new WebSocketServer({ server: httpServer, path: '/ws/terminal' });
+    // --- Ping/pong keepalive ---
+    // The browser's native WebSocket automatically responds to ping frames with pong.
+    if (pingInterval)
+        clearInterval(pingInterval);
+    pingInterval = setInterval(() => {
+        for (const session of sessions) {
+            if (!session.isAlive) {
+                // Didn't respond to last ping — terminate
+                console.log(`[terminalServer] Session ${session.sessionId} ping timeout, terminating`);
+                session.ws.terminate();
+                continue;
+            }
+            session.isAlive = false;
+            session.ws.ping();
+        }
+    }, PING_INTERVAL_MS);
+    globalThis.__codeyamPingInterval = pingInterval;
+    // Subscribe to mock state events and broadcast to all terminal clients
+    mockStateEventEmitter.on('event', (event) => {
+        if (event.type === 'data-mutation-forwarded') {
+            broadcastDataMutationForwarded(event.method, event.pathname);
+        }
+    });
+    wss.on('connection', (ws, req) => {
+        // Parse entity context from query params
+        const url = new URL(req.url || '', `http://${req.headers.host}`);
+        const entityName = url.searchParams.get('entityName') || '';
+        const entityType = url.searchParams.get('entityType') || '';
+        const entitySha = url.searchParams.get('entitySha') || '';
+        const entityFilePath = url.searchParams.get('entityFilePath') || '';
+        const scenarioName = url.searchParams.get('scenarioName') || '';
+        const scenarioDescription = url.searchParams.get('scenarioDescription') || '';
+        const analysisId = url.searchParams.get('analysisId') || '';
+        const projectSlug = url.searchParams.get('projectSlug') || '';
+        const editorMode = url.searchParams.get('editorMode') === 'true';
+        const reconnectId = url.searchParams.get('reconnectId') || '';
+        const claudeStartMode = url.searchParams.get('claudeStartMode') || '';
+        const claudeSessionId = url.searchParams.get('claudeSessionId') || '';
+        // --- Reconnection: reattach to a detached PTY ---
+        if (reconnectId && detachedPtys.has(reconnectId)) {
+            const detached = detachedPtys.get(reconnectId);
+            clearTimeout(detached.graceTimer);
+            detachedPtys.delete(reconnectId);
+            console.log(`[terminalServer] Reattaching session ${reconnectId}`);
+            const session = {
+                ws,
+                ptyProcess: detached.ptyProcess,
+                sessionId: detached.sessionId,
+                isAlive: true,
+            };
+            sessions.add(session);
+            // Send session ID so client can track it
+            ws.send(JSON.stringify({ type: 'session-id', sessionId: session.sessionId }));
+            // Send buffered output so client catches up
+            if (detached.outputBuffer) {
+                ws.send(JSON.stringify({ type: 'output', data: detached.outputBuffer }));
+            }
+            // Re-wire PTY output -> new WebSocket
+            // node-pty's onData returns a disposable; the old listener was still attached
+            // and was buffering output into detached.outputBuffer. We need to replace it.
+            // Unfortunately node-pty doesn't expose removeListener, so we use a closure flag.
+            let detachedFlag = false;
+            const reconnectPort = process.env.CODEYAM_PORT || '3111';
+            const reconnectTransformMarkers = createMarkerTransformer(reconnectPort);
+            const reconnectIdleDetector = new IdleDetector({
+                onIdle: () => {
+                    if (ws.readyState === WebSocket.OPEN) {
+                        ws.send(JSON.stringify({ type: 'claude-idle' }));
+                    }
+                },
+                onActive: () => {
+                    if (ws.readyState === WebSocket.OPEN) {
+                        ws.send(JSON.stringify({ type: 'claude-active' }));
+                    }
+                },
+            }, { activeOutputPattern: /[✶✢]/ });
+            detached.ptyProcess.onData((data) => {
+                if (detachedFlag)
+                    return; // Superseded by a newer listener
+                if (ws.readyState === WebSocket.OPEN) {
+                    if (!detached.hasClearedScreen &&
+                        detached.hasContext &&
+                        data.includes('╭')) {
+                        detached.hasClearedScreen = true;
+                        ws.send(JSON.stringify({ type: 'output', data: '\x1b[2J\x1b[H' }));
+                    }
+                    const transformed = reconnectTransformMarkers(data);
+                    if (transformed.length > 0) {
+                        ws.send(JSON.stringify({ type: 'output', data: transformed }));
+                    }
+                    reconnectIdleDetector.onPtyOutput(data);
+                }
+            });
+            detached.ptyProcess.onExit(() => {
+                reconnectIdleDetector.dispose();
+                sessions.delete(session);
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.close();
+                }
+            });
+            // WebSocket messages -> PTY
+            ws.on('message', (raw) => {
+                try {
+                    const msg = JSON.parse(raw.toString());
+                    if (msg.type === 'input') {
+                        reconnectIdleDetector.onUserInput();
+                        detached.ptyProcess.write(msg.data);
+                    }
+                    else if (msg.type === 'resize' && msg.cols && msg.rows) {
+                        detached.ptyProcess.resize(msg.cols, msg.rows);
+                    }
+                }
+                catch {
+                    detached.ptyProcess.write(raw.toString());
+                }
+            });
+            ws.on('pong', () => {
+                session.isAlive = true;
+            });
+            ws.on('close', () => {
+                detachedFlag = true;
+                detachSession(session, detached.hasContext, detached.hasClearedScreen);
+            });
+            return;
+        }
+        // --- New connection: spawn a fresh PTY ---
+        const shell = process.env.SHELL || '/bin/zsh';
+        const cwd = process.env.CODEYAM_ROOT_PATH || process.cwd();
+        // Verify cwd exists, fall back to HOME
+        const safeCwd = fs.existsSync(cwd) ? cwd : process.env.HOME || '/tmp';
+        // Spawn PTY with a clean env (no giant JSON blobs from CODEYAM_PROJECT etc.)
+        let ptyProcess;
+        try {
+            ptyProcess = pty.spawn(shell, ['-l'], {
+                name: 'xterm-256color',
+                cols: 120,
+                rows: 30,
+                cwd: safeCwd,
+                env: buildPtyEnv({ editorMode }),
+            });
+        }
+        catch (error) {
+            console.error('[terminalServer] Failed to spawn PTY:', {
+                shell,
+                cwd: safeCwd,
+                error,
+            });
+            ws.send(JSON.stringify({
+                type: 'output',
+                data: `\r\nFailed to start terminal: ${error.message}\r\n`,
+            }));
+            ws.close();
+            return;
+        }
+        const sessionId = crypto.randomUUID();
+        const session = {
+            ws,
+            ptyProcess,
+            sessionId,
+            isAlive: true,
+        };
+        sessions.add(session);
+        // Send session ID so client can use it for reconnection
+        ws.send(JSON.stringify({ type: 'session-id', sessionId }));
+        // Write context file for the appropriate skill (dev-mode or editor)
+        const hasContext = editorMode
+            ? writeEditorModeContext({ projectSlug })
+            : writeDevModeContext({
+                entityName,
+                entityType,
+                entitySha,
+                entityFilePath,
+                scenarioName,
+                scenarioDescription,
+                analysisId,
+                projectSlug,
+            });
+        let hasClearedScreen = false;
+        const startupFilter = hasContext ? new StartupOutputFilter() : null;
+        // Safety timeout: stop suppressing output after 5s even if ╭ never arrives.
+        // Prevents "Starting Claude..." hanging forever if the banner format changes.
+        if (hasContext) {
+            setTimeout(() => {
+                const output = startupFilter.getTimeoutOutput();
+                if (output !== null) {
+                    hasClearedScreen = true;
+                    console.log('[terminalServer] Suppression timeout — showing output');
+                    if (ws.readyState === WebSocket.OPEN) {
+                        // Clear the "Starting Claude..." message
+                        ws.send(JSON.stringify({ type: 'output', data: '\x1b[2J\x1b[H' }));
+                        const transformed = transformMarkers(output);
+                        if (transformed.length > 0) {
+                            ws.send(JSON.stringify({ type: 'output', data: transformed }));
+                        }
+                    }
+                }
+            }, 5000);
+        }
+        const idleDetector = new IdleDetector({
+            onIdle: () => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(JSON.stringify({ type: 'claude-idle' }));
+                }
+            },
+            onActive: () => {
+                if (ws.readyState === WebSocket.OPEN) {
+                    ws.send(JSON.stringify({ type: 'claude-active' }));
+                }
+            },
+        }, { activeOutputPattern: /[✶✢]/ });
+        // PTY output -> WebSocket
+        const serverPort = process.env.CODEYAM_PORT || '3111';
+        // Stateful transformer that buffers partial {{scenario:...}} markers
+        // across PTY chunks so they don't appear as raw text.
+        const transformMarkers = createMarkerTransformer(serverPort);
+        ptyProcess.onData((data) => {
+            if (ws.readyState === WebSocket.OPEN) {
+                // During startup, suppress output until Claude's welcome banner (╭)
+                // arrives, then clear screen and strip the raw command from the chunk.
+                if (startupFilter && !hasClearedScreen) {
+                    const result = startupFilter.processChunk(data);
+                    if (result.type === 'clear-and-send') {
+                        hasClearedScreen = true;
+                        ws.send(JSON.stringify({ type: 'output', data: '\x1b[2J\x1b[H' }));
+                        if (result.data.length > 0) {
+                            const transformed = transformMarkers(result.data);
+                            if (transformed.length > 0) {
+                                ws.send(JSON.stringify({ type: 'output', data: transformed }));
+                            }
+                        }
+                        idleDetector.onPtyOutput(data);
+                    }
+                    // type === 'suppress': skip sending and idle detection
+                }
+                else {
+                    // Transform {{scenario:Name:ID}} markers into OSC 8 clickable hyperlinks.
+                    // Uses stateful buffering to handle markers split across PTY chunks.
+                    const transformed = transformMarkers(data);
+                    if (transformed.length > 0) {
+                        ws.send(JSON.stringify({ type: 'output', data: transformed }));
+                    }
+                    idleDetector.onPtyOutput(data);
+                }
+            }
+        });
+        ptyProcess.onExit(() => {
+            idleDetector.dispose();
+            sessions.delete(session);
+            // Also clean up from detachedPtys if it was detached
+            if (detachedPtys.has(sessionId)) {
+                clearTimeout(detachedPtys.get(sessionId).graceTimer);
+                detachedPtys.delete(sessionId);
+            }
+            if (ws.readyState === WebSocket.OPEN) {
+                ws.close();
+            }
+        });
+        // WebSocket messages -> PTY
+        ws.on('message', (raw) => {
+            try {
+                const msg = JSON.parse(raw.toString());
+                if (msg.type === 'input') {
+                    idleDetector.onUserInput();
+                    ptyProcess.write(msg.data);
+                }
+                else if (msg.type === 'resize' && msg.cols && msg.rows) {
+                    ptyProcess.resize(msg.cols, msg.rows);
+                }
+            }
+            catch {
+                // Non-JSON message, treat as raw input
+                ptyProcess.write(raw.toString());
+            }
+        });
+        ws.on('pong', () => {
+            session.isAlive = true;
+        });
+        ws.on('close', () => {
+            detachSession(session, hasContext, hasClearedScreen);
+        });
+        // Show a loading indicator while Claude Code starts up.
+        // PTY output is suppressed until Claude's welcome banner (╭) appears
+        // and triggers a screen clear, so the user never sees the raw command.
+        if (hasContext) {
+            ws.send(JSON.stringify({
+                type: 'output',
+                data: '\x1b[2J\x1b[H\r\n\x1b[90m  Starting Claude...\x1b[0m\r\n',
+            }));
+        }
+        // Start Claude Code with the appropriate skill.
+        // Using a skill avoids shell escaping issues and multi-line paste detection.
+        //
+        // Session recovery modes (editor only):
+        //   resume + sessionId → claude --resume <uuid> (resumes exact conversation)
+        //   resume, no sessionId → claude --continue (fallback for pre-existing sessions)
+        //   fresh → generate UUID, write to .codeyam/claude-session-id.txt,
+        //           launch claude --session-id <uuid> '/codeyam-editor'
+        //
+        // The UUID is generated HERE (not in printStep1) so it's available before
+        // Claude launches. printStep1 runs inside the session — too late.
+        setTimeout(() => {
+            if (editorMode && hasContext) {
+                if (claudeStartMode === 'resume' && claudeSessionId) {
+                    ptyProcess.write(`claude --resume '${claudeSessionId}' 'The session was interrupted. Please continue where you left off.'\r`);
+                }
+                else if (claudeStartMode === 'resume') {
+                    // No session ID available — fall back to most recent session
+                    ptyProcess.write("claude --continue 'The session was interrupted. Please continue where you left off.'\r");
+                }
+                else {
+                    // Fresh session: generate a trackable UUID
+                    const newSessionId = crypto.randomUUID();
+                    const sessionIdPath = path.join(cwd, '.codeyam', 'claude-session-id.txt');
+                    try {
+                        fs.mkdirSync(path.dirname(sessionIdPath), { recursive: true });
+                        fs.writeFileSync(sessionIdPath, newSessionId, 'utf8');
+                    }
+                    catch (err) {
+                        console.error('[terminalServer] Failed to write claude-session-id.txt:', err);
+                    }
+                    ptyProcess.write(`claude --session-id '${newSessionId}' '/codeyam-editor'\r`);
+                }
+            }
+            else if (hasContext) {
+                ptyProcess.write("claude '/codeyam-dev-mode'\r");
+            }
+            else {
+                ptyProcess.write('claude\r');
+            }
+        }, 500);
+    });
+    console.log('[terminalServer] WebSocket terminal server attached at /ws/terminal');
+}
+/**
+ * Detach a session's PTY instead of killing it, giving the client time to reconnect.
+ * The PTY is moved to `detachedPtys` with a grace timer; if the client reconnects
+ * within DETACH_GRACE_MS, the PTY is reattached. Otherwise it's killed.
+ */
+function detachSession(session, hasContext = false, hasClearedScreen = false) {
+    sessions.delete(session);
+    const { sessionId, ptyProcess } = session;
+    // If already detached (shouldn't happen), skip
+    if (detachedPtys.has(sessionId))
+        return;
+    let outputBuffer = '';
+    // Buffer PTY output during detachment so the client can catch up on reconnect
+    ptyProcess.onData((data) => {
+        outputBuffer += data;
+        // Cap buffer size
+        if (outputBuffer.length > OUTPUT_BUFFER_MAX) {
+            outputBuffer = outputBuffer.slice(-OUTPUT_BUFFER_MAX);
+        }
+    });
+    const graceTimer = setTimeout(() => {
+        console.log(`[terminalServer] Grace period expired for session ${sessionId}, killing PTY`);
+        detachedPtys.delete(sessionId);
+        try {
+            ptyProcess.kill();
+        }
+        catch {
+            /* already dead */
+        }
+    }, DETACH_GRACE_MS);
+    detachedPtys.set(sessionId, {
+        ptyProcess,
+        sessionId,
+        graceTimer,
+        outputBuffer,
+        hasContext,
+        hasClearedScreen,
+    });
+    console.log(`[terminalServer] Session ${sessionId} detached, PTY kept alive for ${DETACH_GRACE_MS / 1000}s`);
+}
+/**
+ * Send a refresh-preview message to all connected terminal WebSocket clients.
+ * The Terminal component relays this to the parent page to reload the iframe.
+ */
+export function broadcastPreviewRefresh(path, scenarioId) {
+    const msg = JSON.stringify({
+        type: 'refresh-preview',
+        ...(path && { path }),
+        ...(scenarioId && { scenarioId }),
+    });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Notify all connected terminal WebSocket clients that a data mutation
+ * was forwarded to the real dev server (seed-based scenario).
+ * The Terminal component relays this to editor.tsx to show a save banner.
+ */
+export function broadcastDataMutationForwarded(method, pathname) {
+    const msg = JSON.stringify({
+        type: 'data-mutation-forwarded',
+        method,
+        pathname,
+    });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Show the results panel below the terminal in the Build tab.
+ * Triggered by Claude at end of step 12.
+ */
+export function broadcastShowResults() {
+    const msg = JSON.stringify({ type: 'show-results' });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Hide the results panel (e.g. after Save & Commit).
+ */
+export function broadcastHideResults() {
+    const msg = JSON.stringify({ type: 'hide-results' });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Send a set-viewport message to all connected terminal WebSocket clients.
+ * The Terminal component relays this to the parent page to update the preview viewport.
+ */
+export function broadcastSetViewport(viewport) {
+    const msg = JSON.stringify({ type: 'set-viewport', ...viewport });
+    let count = 0;
+    for (const session of sessions) {
+        try {
+            if (session.ws.readyState === WebSocket.OPEN) {
+                session.ws.send(msg);
+                count++;
+            }
+        }
+        catch {
+            // Ignore send errors
+        }
+    }
+    return count;
+}
+/**
+ * Kill all active PTY sessions and detached PTYs. Call during shutdown.
+ */
+export function cleanupAllTerminalSessions() {
+    // Clear ping interval
+    if (pingInterval) {
+        clearInterval(pingInterval);
+        pingInterval = null;
+        globalThis.__codeyamPingInterval = null;
+    }
+    // Clean up active sessions
+    for (const session of Array.from(sessions)) {
+        try {
+            session.ptyProcess.kill();
+        }
+        catch {
+            // Already dead
+        }
+        try {
+            session.ws.close();
+        }
+        catch {
+            // Already closed
+        }
+    }
+    sessions.clear();
+    // Clean up detached PTYs
+    for (const [, detached] of detachedPtys) {
+        clearTimeout(detached.graceTimer);
+        try {
+            detached.ptyProcess.kill();
+        }
+        catch {
+            // Already dead
+        }
+    }
+    detachedPtys.clear();
+}
+//# sourceMappingURL=terminalServer.js.map