@codeyam/codeyam-cli 0.1.0-staging.8df382d → 0.1.0-staging.a890816

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

@@ -0,0 +1,753 @@
+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';
+// 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-refresh 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
+const ANSI_ESCAPE_RE = /\x1b\[[0-9;]*[a-zA-Z]/g;
+/**
+ * Build a position map from ANSI-stripped indices to original indices.
+ * posMap[strippedIndex] = originalIndex, skipping over ANSI sequences.
+ */
+function buildAnsiPositionMap(data, stripped) {
+    const posMap = [];
+    for (let di = 0, si = 0; di < data.length; di++) {
+        if (data[di] === '\x1b') {
+            const seqMatch = data.slice(di).match(/^\x1b\[[0-9;]*[a-zA-Z]/);
+            if (seqMatch) {
+                di += seqMatch[0].length - 1; // -1 because loop increments
+                continue;
+            }
+        }
+        posMap[si] = di;
+        si++;
+    }
+    posMap[stripped.length] = data.length; // sentinel for end-of-string markers
+    return posMap;
+}
+/**
+ * Transform {{scenario:Name:ID}} markers in PTY output into OSC 8 hyperlinks.
+ * OSC 8 format: \x1b]8;;URL\x07VISIBLE_TEXT\x1b]8;;\x07
+ * xterm.js renders the visible text as a clickable link.
+ *
+ * Claude Code's renderer inserts ANSI escape codes (colors/styles) within the
+ * marker text, so we can't regex match on the raw PTY data directly. Instead,
+ * strip ANSI codes to find markers, then map positions back to the original
+ * string for replacement.
+ */
+function transformScenarioMarkers(data, port) {
+    // Strip ANSI escape sequences to get clean text for marker detection
+    const stripped = data.replace(ANSI_ESCAPE_RE, '');
+    if (!stripped.includes('{{scenario:'))
+        return data;
+    const posMap = buildAnsiPositionMap(data, stripped);
+    // Find markers in the stripped text
+    const markerRegex = /\{\{scenario:([^:}]+):([^}]+)\}\}/g;
+    const replacements = [];
+    let m;
+    while ((m = markerRegex.exec(stripped)) !== null) {
+        const url = `http://localhost:${port}/editor?scenario=${m[2]}&ref=link`;
+        const visibleName = m[1];
+        // Pad replacement to match the original marker's visible width so table
+        // columns stay aligned after the shorter hyperlink text replaces the marker.
+        const pad = ' '.repeat(Math.max(0, m[0].length - visibleName.length));
+        replacements.push({
+            origStart: posMap[m.index],
+            origEnd: posMap[m.index + m[0].length],
+            replacement: `\x1b]8;;${url}\x07${visibleName}\x1b]8;;\x07${pad}`,
+        });
+    }
+    if (replacements.length === 0)
+        return data;
+    // Replace from end to start so earlier positions stay valid
+    let result = data;
+    for (let i = replacements.length - 1; i >= 0; i--) {
+        const r = replacements[i];
+        result =
+            result.slice(0, r.origStart) + r.replacement + result.slice(r.origEnd);
+    }
+    return result;
+}
+/**
+ * Create a stateful scenario marker transformer that buffers partial markers
+ * across PTY chunks. Claude Code streams output token by token, so the PTY
+ * can split a {{scenario:Name:ID}} marker across two (or more) data events.
+ * Without buffering, split markers pass through un-transformed as raw text.
+ */
+function createMarkerTransformer(port) {
+    let buffer = '';
+    return function transform(data) {
+        // Prepend any buffered partial-marker text from the previous chunk
+        const combined = buffer + data;
+        buffer = '';
+        // Strip ANSI to detect partial markers at the end
+        const stripped = combined.replace(ANSI_ESCAPE_RE, '');
+        // Check for an unclosed {{ at the end — potential partial marker
+        const lastOpen = stripped.lastIndexOf('{{');
+        if (lastOpen !== -1 && !stripped.slice(lastOpen).includes('}}')) {
+            // Map the stripped position back to the original string
+            const posMap = buildAnsiPositionMap(combined, stripped);
+            const splitPos = posMap[lastOpen];
+            // Safety: if partial marker exceeds 500 chars, it's not a real marker — flush it
+            if (combined.length - splitPos > 500) {
+                return transformScenarioMarkers(combined, port);
+            }
+            buffer = combined.slice(splitPos);
+            const toSend = combined.slice(0, splitPos);
+            // If nothing to send yet (entire chunk is a partial marker), return empty
+            if (toSend.length === 0)
+                return '';
+            return transformScenarioMarkers(toSend, port);
+        }
+        return transformScenarioMarkers(combined, port);
+    };
+}
+// 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',
+];
+function buildPtyEnv() {
+    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';
+    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-refresh\``);
+        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` for the next step (plan → prototype → confirm → deconstruct → extract → glossary → analyze → app scenarios → user scenarios → verify → review)',
+            '- Each feature follows 11 steps: `codeyam editor 1` through `codeyam editor 11`',
+            '- Steps 1, 3, and 11 require user confirmation before proceeding',
+            '',
+            '## 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":"...","description":"...","mockData":{"routes":{"/api/tasks":{"body":[...]}}}}'\``,
+            `- **Get active scenario data:** \`curl http://localhost:${serverPort}/api/editor-scenario-data\``,
+            `- **Refresh preview:** \`curl -X POST http://localhost:${serverPort}/api/dev-mode-refresh\``,
+            `- **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',
+            '- To screenshot individual components, create ONE isolation route per component:',
+            '  - **Remix:** `app/routes/codeyam-isolate.ComponentName.tsx` → `/codeyam-isolate/ComponentName`',
+            '  - **Next.js:** `app/codeyam-isolate/ComponentName/page.tsx` → `/codeyam-isolate/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;padding:20px"><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":"/codeyam-isolate/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 `**/codeyam-isolate*` 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;
+    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') || '';
+        // --- 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);
+            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 }));
+                    }
+                    const stripped = data.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+                    if (stripped.includes('Editor Mode \u2014')) {
+                        console.log('[terminalServer] Detected claude-idle signal (reconnect)');
+                        ws.send(JSON.stringify({ type: 'claude-idle' }));
+                    }
+                }
+            });
+            detached.ptyProcess.onExit(() => {
+                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') {
+                        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(),
+            });
+        }
+        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;
+        // Rolling buffer of trailing text to detect "Editor Mode —" across PTY chunks.
+        let idleDetectBuffer = '';
+        const IDLE_MARKER = 'Editor Mode \u2014';
+        // 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) {
+                // When Claude Code starts (indicated by its box-drawing welcome banner),
+                // clear the screen to hide the raw shell command.
+                if (!hasClearedScreen && hasContext && data.includes('╭')) {
+                    hasClearedScreen = true;
+                    ws.send(JSON.stringify({ type: 'output', data: '\x1b[2J\x1b[H' }));
+                }
+                // 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 }));
+                }
+                // Detect the Stop hook output — signals Claude is waiting for user input.
+                // The hook outputs "Editor Mode —" when Claude finishes a turn.
+                // Strip ANSI escape codes and check buffer+current to handle cross-chunk splits.
+                const stripped = data.replace(/\x1b\[[0-9;]*[a-zA-Z]/g, '');
+                const combined = idleDetectBuffer + stripped;
+                if (combined.includes(IDLE_MARKER)) {
+                    console.log('[terminalServer] Detected claude-idle signal');
+                    ws.send(JSON.stringify({ type: 'claude-idle' }));
+                    idleDetectBuffer = '';
+                }
+                else {
+                    // Keep trailing chars in case the marker spans two chunks
+                    idleDetectBuffer = stripped.slice(-(IDLE_MARKER.length - 1));
+                }
+            }
+        });
+        ptyProcess.onExit(() => {
+            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') {
+                    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);
+        });
+        // Start Claude Code with the appropriate skill.
+        // Using a skill avoids shell escaping issues and multi-line paste detection.
+        setTimeout(() => {
+            if (editorMode && hasContext) {
+                ptyProcess.write("claude '/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() {
+    const msg = JSON.stringify({ type: 'refresh-preview' });
+    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