@codeyam/codeyam-cli 0.1.0-staging.dd216e0 → 0.1.0-staging.e057775

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

@@ -0,0 +1,877 @@
+import http from 'http';
+import net from 'net';
+import fs from 'fs';
+import path from 'path';
+import { getProjectRoot } from "../state.js";
+import { createMockStateManager, } from "../utils/editorMockState.js";
+import { computeEditorPorts } from "../utils/editorDevServer.js";
+/**
+ * Normalize a target URL by stripping trailing slashes for consistency.
+ *
+ * Previously this also replaced `localhost` with `127.0.0.1`, but that broke
+ * forwarding to dev servers that bind to IPv6 only (e.g. Vite 6 on macOS
+ * binds to `[::1]`). The hostname is now left as-is — `resolveLoopbackAddress`
+ * probes the actual target at startup to pick the right address.
+ */
+export function normalizeTargetUrl(url) {
+    try {
+        const parsed = new URL(url);
+        return parsed.toString().replace(/\/$/, '');
+    }
+    catch {
+        return url;
+    }
+}
+/**
+ * Probe a localhost port to determine the correct loopback address.
+ * Dev servers may bind to IPv4 (127.0.0.1), IPv6 (::1), or both.
+ * Returns the first address that accepts a TCP connection.
+ */
+export async function resolveLoopbackAddress(port) {
+    const candidates = ['127.0.0.1', '::1'];
+    for (const host of candidates) {
+        try {
+            const connected = await new Promise((resolve) => {
+                const socket = new net.Socket();
+                socket.setTimeout(1000);
+                socket.once('connect', () => {
+                    socket.destroy();
+                    resolve(true);
+                });
+                socket.once('error', () => {
+                    socket.destroy();
+                    resolve(false);
+                });
+                socket.once('timeout', () => {
+                    socket.destroy();
+                    resolve(false);
+                });
+                socket.connect(port, host);
+            });
+            if (connected) {
+                return host;
+            }
+        }
+        catch {
+            // Try next candidate
+        }
+    }
+    return null;
+}
+// Global key so the proxy survives HMR
+const GLOBAL_KEY = '__codeyam_editor_proxy__';
+// ─── Live Preview Health ─────────────────────────────────────────────
+const PREVIEW_HEALTH_KEY = '__codeyam_preview_health__';
+function getPreviewHealth() {
+    return globalThis[PREVIEW_HEALTH_KEY] ?? null;
+}
+function setPreviewHealth(report) {
+    globalThis[PREVIEW_HEALTH_KEY] = report;
+}
+/**
+ * Get the current live preview health report (read by API endpoint).
+ */
+export function getPreviewHealthReport() {
+    return getPreviewHealth();
+}
+/**
+ * Reset preview health state (called when a new HTML page is served).
+ */
+export function resetPreviewHealth() {
+    setPreviewHealth(null);
+}
+/**
+ * Error-catching script injected into HTML responses.
+ * Uses vanilla JS for maximum compatibility.
+ */
+export const PREVIEW_HEALTH_SCRIPT = `<script data-codeyam-health>
+(function() {
+  var errors = [];
+  var reported = false;
+  function report(type, msg, stack) {
+    errors.push({ type: type, message: msg, stack: stack, timestamp: Date.now() });
+    if (!reported) {
+      reported = true;
+      setTimeout(function() { flush(); }, 500);
+    }
+  }
+  function flush() {
+    fetch('/__codeyam__/preview-health', {
+      method: 'POST',
+      headers: { 'Content-Type': 'application/json' },
+      body: JSON.stringify({ errors: errors, url: location.href })
+    }).catch(function(){});
+    reported = false;
+    errors = [];
+  }
+  window.addEventListener('error', function(e) {
+    report('error', e.message, e.error && e.error.stack);
+  });
+  window.addEventListener('unhandledrejection', function(e) {
+    report('unhandledrejection', String(e.reason), e.reason && e.reason.stack);
+  });
+  var origError = console.error;
+  console.error = function() {
+    report('console.error', Array.prototype.join.call(arguments, ' '));
+    origError.apply(console, arguments);
+  };
+  window.addEventListener('load', function() {
+    setTimeout(function() {
+      var hasContent = document.body && document.body.innerText.trim().length > 0;
+      fetch('/__codeyam__/preview-health', {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          loaded: true,
+          hasContent: hasContent,
+          url: location.href,
+          errorCount: errors.length
+        })
+      }).catch(function(){});
+    }, 1000);
+  });
+})();
+</script>`;
+const CACHE_TTL_MS = 500;
+let scenarioCache = { data: null, timestamp: 0 };
+// Session config extracted from the active scenario — drives cookie injection
+let sessionConfig = undefined;
+// localStorage config extracted from the active scenario — drives HTML injection
+let localStorageConfig = null;
+// Active scenario ID — used to gate localStorage seeding (only re-seed on switch)
+let activeScenarioId = null;
+// Prototype ID — used to gate a one-time localStorage.clear() when a new project is scaffolded
+let currentPrototypeId = null;
+// Max body size to buffer for mock matching (10MB)
+const MAX_BODY_SIZE = 10 * 1024 * 1024;
+function getProxyState() {
+    return globalThis[GLOBAL_KEY] ?? null;
+}
+function setProxyState(state) {
+    globalThis[GLOBAL_KEY] = state;
+}
+/**
+ * Get or create the mock state manager (survives HMR via globalThis).
+ */
+function getMockStateManager() {
+    const key = '__codeyam_mock_state__';
+    if (!globalThis[key]) {
+        globalThis[key] = createMockStateManager();
+    }
+    return globalThis[key];
+}
+/**
+ * Get the proxy URL if the proxy is running.
+ */
+export function getProxyUrl() {
+    const state = getProxyState();
+    if (!state)
+        return null;
+    return `http://localhost:${state.port}`;
+}
+/**
+ * Read the active scenario's mock data from disk, with brief caching.
+ * Feeds the data into the MockStateManager.
+ *
+ * For application/user scenarios (type-aware): only loads `externalApis`
+ * into the mock state manager. All DB-backed routes flow through to the
+ * real app (database is seeded with real data).
+ *
+ * For component scenarios (or legacy): loads all routes as before.
+ */
+function readScenarioData() {
+    const now = Date.now();
+    if (scenarioCache.data !== null &&
+        now - scenarioCache.timestamp < CACHE_TTL_MS) {
+        return scenarioCache.data;
+    }
+    const projectRoot = getProjectRoot() || process.env.CODEYAM_ROOT_PATH || process.cwd();
+    const activeScenarioPath = path.join(projectRoot, '.codeyam', 'active-scenario.json');
+    try {
+        if (!fs.existsSync(activeScenarioPath)) {
+            scenarioCache = { data: null, timestamp: now };
+            return null;
+        }
+        const active = JSON.parse(fs.readFileSync(activeScenarioPath, 'utf-8'));
+        const scenarioId = active.scenarioId;
+        if (!scenarioId) {
+            // No active scenario — but may have a prototypeId for localStorage clearing
+            currentPrototypeId = active.prototypeId || null;
+            scenarioCache = { data: null, timestamp: now };
+            return null;
+        }
+        const dataFilePath = path.join(projectRoot, '.codeyam', 'editor-scenarios', `${scenarioId}.json`);
+        if (!fs.existsSync(dataFilePath)) {
+            console.log(`[editorProxy] Scenario data file not found: ${dataFilePath}`);
+            scenarioCache = { data: null, timestamp: now };
+            return null;
+        }
+        const rawData = JSON.parse(fs.readFileSync(dataFilePath, 'utf-8'));
+        // Extract session config for cookie injection
+        sessionConfig = rawData.session || null;
+        // Extract localStorage config for HTML injection
+        localStorageConfig = rawData.localStorage || null;
+        activeScenarioId = scenarioId;
+        // Type-aware: for seed-based scenarios, only serve externalApis via proxy
+        const scenarioType = active.type || rawData.type || null;
+        let mockData;
+        if ((scenarioType === 'application' || scenarioType === 'user') &&
+            rawData.seed) {
+            // Seed-based scenario: only load externalApis as routes for the proxy
+            if (rawData.externalApis && typeof rawData.externalApis === 'object') {
+                mockData = { routes: rawData.externalApis };
+            }
+            else {
+                // No external APIs — proxy passes everything through
+                mockData = {};
+            }
+        }
+        else {
+            // Component/legacy scenario: load all data
+            mockData = rawData;
+        }
+        scenarioCache = { data: mockData, timestamp: now };
+        // Feed into mock state manager (smart reload handles dedup)
+        getMockStateManager().loadScenario(mockData);
+        return mockData;
+    }
+    catch (err) {
+        console.warn('[editorProxy] Error reading scenario data:', err);
+        scenarioCache = { data: null, timestamp: now };
+        return null;
+    }
+}
+/**
+ * Buffer the request body, up to MAX_BODY_SIZE.
+ * Returns null if the body exceeds the limit.
+ */
+function bufferRequestBody(req) {
+    return new Promise((resolve) => {
+        const chunks = [];
+        let totalSize = 0;
+        req.on('data', (chunk) => {
+            totalSize += chunk.length;
+            if (totalSize > MAX_BODY_SIZE) {
+                resolve(null); // Too large — skip mock matching
+                req.resume(); // Drain remaining
+            }
+            else {
+                chunks.push(chunk);
+            }
+        });
+        req.on('end', () => {
+            if (totalSize > MAX_BODY_SIZE)
+                return; // Already resolved
+            resolve(Buffer.concat(chunks));
+        });
+        req.on('error', () => {
+            resolve(null);
+        });
+    });
+}
+/**
+ * Strip IPv6 bracket notation for use with http.request hostname.
+ * URL.hostname returns `[::1]` for IPv6 but http.request needs `::1`.
+ */
+function stripIPv6Brackets(hostname) {
+    if (hostname.startsWith('[') && hostname.endsWith(']')) {
+        return hostname.slice(1, -1);
+    }
+    return hostname;
+}
+/**
+ * Forward a buffered request to the target dev server.
+ * Unlike the streaming forwardRequest, this replays a buffered body.
+ */
+function forwardBufferedRequest(req, res, targetUrl, bodyBuffer) {
+    const target = new URL(targetUrl);
+    const hostname = stripIPv6Brackets(target.hostname);
+    const headers = { ...req.headers, host: `${target.hostname}:${target.port}` };
+    // Remove accept-encoding so the dev server returns uncompressed responses.
+    // The proxy injects a health script into HTML — this fails on compressed bodies.
+    delete headers['accept-encoding'];
+    // Update content-length if we have the body buffer
+    if (bodyBuffer) {
+        headers['content-length'] = String(bodyBuffer.length);
+    }
+    const options = {
+        hostname,
+        port: target.port,
+        path: req.url,
+        method: req.method,
+        headers,
+    };
+    const proxyReq = http.request(options, (proxyRes) => {
+        const status = proxyRes.statusCode || 200;
+        if (status >= 400) {
+            console.warn(`[editorProxy] Target returned ${status} for ${req.method} ${req.url}`);
+        }
+        const headers = { ...proxyRes.headers };
+        injectSessionCookie(headers);
+        // Check if response is HTML — if so, buffer and inject health script
+        const contentType = proxyRes.headers['content-type'] || '';
+        if (contentType.includes('text/html')) {
+            resetPreviewHealth();
+            const chunks = [];
+            proxyRes.on('data', (chunk) => chunks.push(chunk));
+            proxyRes.on('end', () => {
+                const body = Buffer.concat(chunks).toString('utf-8');
+                const lsScript = buildLocalStorageScript(localStorageConfig, activeScenarioId || '', currentPrototypeId);
+                const injected = injectHealthScript(body, lsScript);
+                delete headers['content-length'];
+                delete headers['content-encoding'];
+                // Prevent browser from caching HTML responses — scenario switches
+                // serve different content from the same URL (seed data changes the
+                // rendered page but the proxy URL stays the same).
+                headers['cache-control'] = 'no-store, must-revalidate';
+                res.writeHead(status, headers);
+                res.end(injected);
+            });
+            return;
+        }
+        res.writeHead(status, headers);
+        proxyRes.pipe(res, { end: true });
+    });
+    proxyReq.on('error', (err) => {
+        console.warn(`[editorProxy] Forward error for ${req.method} ${req.url}: ${err.message}`);
+        if (!res.headersSent) {
+            res.writeHead(502, { 'Content-Type': 'text/plain' });
+            res.end('Bad Gateway — dev server unreachable');
+        }
+    });
+    if (bodyBuffer && bodyBuffer.length > 0) {
+        proxyReq.end(bodyBuffer);
+    }
+    else {
+        proxyReq.end();
+    }
+}
+/**
+ * Forward an HTTP request to the target dev server.
+ * For HTML responses: buffers body to inject health-check script.
+ * For non-HTML responses: pipes directly (no buffering).
+ */
+function forwardRequest(req, res, targetUrl) {
+    const target = new URL(targetUrl);
+    const hostname = stripIPv6Brackets(target.hostname);
+    // Build headers, stripping accept-encoding so the dev server returns uncompressed
+    // responses. The proxy injects a health script into HTML — this fails on compressed bodies.
+    const { 'accept-encoding': _ae, ...forwardHeaders } = req.headers;
+    const options = {
+        hostname,
+        port: target.port,
+        path: req.url,
+        method: req.method,
+        headers: {
+            ...forwardHeaders,
+            host: `${target.hostname}:${target.port}`,
+        },
+    };
+    const proxyReq = http.request(options, (proxyRes) => {
+        const status = proxyRes.statusCode || 200;
+        if (status >= 400) {
+            console.warn(`[editorProxy] Target returned ${status} for ${req.method} ${req.url}`);
+        }
+        const headers = { ...proxyRes.headers };
+        injectSessionCookie(headers);
+        // Check if response is HTML — if so, buffer and inject health script
+        const contentType = proxyRes.headers['content-type'] || '';
+        if (contentType.includes('text/html')) {
+            // Reset health state for new page loads
+            resetPreviewHealth();
+            const chunks = [];
+            proxyRes.on('data', (chunk) => chunks.push(chunk));
+            proxyRes.on('end', () => {
+                const body = Buffer.concat(chunks).toString('utf-8');
+                const lsScript = buildLocalStorageScript(localStorageConfig, activeScenarioId || '', currentPrototypeId);
+                const injected = injectHealthScript(body, lsScript);
+                // Remove content-length since body size changed; use chunked transfer
+                delete headers['content-length'];
+                // Remove content-encoding since we're serving uncompressed
+                delete headers['content-encoding'];
+                // Prevent browser from caching HTML responses — scenario switches
+                // serve different content from the same URL (seed data changes the
+                // rendered page but the proxy URL stays the same).
+                headers['cache-control'] = 'no-store, must-revalidate';
+                res.writeHead(status, headers);
+                res.end(injected);
+            });
+            return;
+        }
+        res.writeHead(status, headers);
+        proxyRes.pipe(res, { end: true });
+    });
+    proxyReq.on('error', (err) => {
+        console.warn(`[editorProxy] Forward error for ${req.method} ${req.url}: ${err.message}`);
+        if (!res.headersSent) {
+            res.writeHead(502, { 'Content-Type': 'text/plain' });
+            res.end('Bad Gateway — dev server unreachable');
+        }
+    });
+    req.pipe(proxyReq, { end: true });
+}
+/**
+ * Inject or clear the session-token cookie on proxied responses.
+ * When a scenario has session.cookieValue, sets the cookie to auto-log the user in.
+ * When a scenario has no session field (null), clears any existing session cookie.
+ * When sessionConfig is undefined (no scenario loaded yet), does nothing.
+ */
+function injectSessionCookie(headers) {
+    if (sessionConfig === undefined)
+        return;
+    let cookie;
+    if (sessionConfig?.cookieValue) {
+        cookie = `session-token=${sessionConfig.cookieValue}; Path=/; SameSite=Lax`;
+    }
+    else {
+        // No session config — clear any existing session cookie
+        cookie = `session-token=; Path=/; Max-Age=0`;
+    }
+    const existing = headers['set-cookie'];
+    if (existing) {
+        headers['set-cookie'] = [
+            ...(Array.isArray(existing) ? existing : [existing]),
+            cookie,
+        ];
+    }
+    else {
+        headers['set-cookie'] = [cookie];
+    }
+}
+/**
+ * Get the current session config (for testing).
+ */
+export function getSessionConfig() {
+    return sessionConfig;
+}
+/**
+ * Get the current localStorage config (for testing and script generation).
+ */
+export function getLocalStorageConfig() {
+    return localStorageConfig;
+}
+/**
+ * Get the active scenario ID (for testing and script generation).
+ */
+export function getActiveScenarioId() {
+    return activeScenarioId;
+}
+/**
+ * Get the current prototype ID (for testing).
+ */
+export function getCurrentPrototypeId() {
+    return currentPrototypeId;
+}
+/**
+ * Build a script tag that seeds localStorage with scenario data on first load.
+ * Gated by scenario ID — only seeds when the scenario changes, preserving
+ * interactive modifications across page reloads / HMR.
+ *
+ * Returns empty string if no localStorage config is provided.
+ */
+export function buildLocalStorageScript(localStorageConfig, scenarioId, prototypeId) {
+    // null/undefined means no localStorage config at all — but if we have a
+    // prototypeId, emit a one-time localStorage.clear() to flush stale data
+    // from a previous prototype session.
+    if (!localStorageConfig || typeof localStorageConfig !== 'object') {
+        if (prototypeId) {
+            return `<script data-codeyam-ls>
+(function() {
+  if (localStorage.getItem('__codeyam_proto__') === ${JSON.stringify(prototypeId)}) return;
+  localStorage.clear();
+  localStorage.setItem('__codeyam_proto__', ${JSON.stringify(prototypeId)});
+})();
+</script>`;
+        }
+        return '';
+    }
+    // Even an empty object needs a cleanup script — switching from a scenario
+    // with localStorage data to one without must clear the previous keys.
+    const entries = Object.entries(localStorageConfig);
+    const keys = entries.map(([k]) => k);
+    // Build setItem calls — stringify non-string values
+    const setStatements = entries
+        .map(([key, value]) => {
+        const serialized = typeof value === 'string' ? value : JSON.stringify(value);
+        return `localStorage.setItem(${JSON.stringify(key)}, ${JSON.stringify(serialized)});`;
+    })
+        .join('\n');
+    return `<script data-codeyam-ls>
+(function() {
+  if (localStorage.getItem('__codeyam_ls_sid__') === ${JSON.stringify(scenarioId)}) return;
+  var prev = JSON.parse(localStorage.getItem('__codeyam_ls_keys__') || '[]');
+  for (var i = 0; i < prev.length; i++) localStorage.removeItem(prev[i]);
+  ${setStatements}
+  localStorage.setItem('__codeyam_ls_keys__', ${JSON.stringify(JSON.stringify(keys))});
+  localStorage.setItem('__codeyam_ls_sid__', ${JSON.stringify(scenarioId)});
+})();
+</script>`;
+}
+/**
+ * Inject the health-check script (and optional localStorage script) into an HTML response body.
+ * Inserts before </head> if present, otherwise before </body>, otherwise appends.
+ * When a localStorageScript is provided, it's injected BEFORE the health script
+ * so localStorage is populated before the app loads.
+ */
+export function injectHealthScript(html, localStorageScript) {
+    const scripts = (localStorageScript || '') + PREVIEW_HEALTH_SCRIPT;
+    if (html.includes('</head>')) {
+        return html.replace('</head>', scripts + '</head>');
+    }
+    if (html.includes('</body>')) {
+        return html.replace('</body>', scripts + '</body>');
+    }
+    return html + scripts;
+}
+/**
+ * Handle POST /__codeyam__/preview-health — store health data in globalThis.
+ */
+function handlePreviewHealthPost(req, res) {
+    const chunks = [];
+    req.on('data', (chunk) => chunks.push(chunk));
+    req.on('end', () => {
+        try {
+            const body = JSON.parse(Buffer.concat(chunks).toString('utf-8'));
+            const current = getPreviewHealth() || {
+                errors: [],
+                loaded: false,
+                hasContent: false,
+                url: '',
+                lastUpdated: 0,
+            };
+            if (body.errors && Array.isArray(body.errors)) {
+                current.errors = current.errors.concat(body.errors);
+            }
+            if (body.loaded !== undefined) {
+                current.loaded = body.loaded;
+            }
+            if (body.hasContent !== undefined) {
+                current.hasContent = body.hasContent;
+            }
+            if (body.url) {
+                current.url = body.url;
+            }
+            current.lastUpdated = Date.now();
+            setPreviewHealth(current);
+        }
+        catch {
+            // Ignore malformed JSON
+        }
+        res.writeHead(204);
+        res.end();
+    });
+}
+/**
+ * Handle WebSocket upgrade by piping to the target dev server.
+ */
+function handleUpgrade(req, socket, head, targetUrl) {
+    const target = new URL(targetUrl);
+    const hostname = stripIPv6Brackets(target.hostname);
+    const port = parseInt(target.port, 10) || 80;
+    console.log(`[editorProxy] WebSocket upgrade: ${req.url} → ${hostname}:${port}`);
+    const proxySocket = net.connect(port, hostname, () => {
+        // Reconstruct the HTTP upgrade request
+        const requestLine = `${req.method} ${req.url} HTTP/${req.httpVersion}\r\n`;
+        const headers = Object.entries(req.headers)
+            .filter(([, v]) => v != null)
+            .map(([k, v]) => `${k}: ${Array.isArray(v) ? v.join(', ') : v}`)
+            .join('\r\n');
+        proxySocket.write(requestLine + headers + '\r\n\r\n');
+        if (head.length > 0) {
+            proxySocket.write(head);
+        }
+        // Pipe both directions
+        proxySocket.pipe(socket, { end: true });
+        socket.pipe(proxySocket, { end: true });
+    });
+    proxySocket.on('error', (err) => {
+        console.warn(`[editorProxy] WebSocket proxy error: ${err.message}`);
+        socket.destroy();
+    });
+    socket.on('error', () => {
+        proxySocket.destroy();
+    });
+}
+/**
+ * Write proxy-config.json so the preload module can discover the proxy.
+ */
+function writeProxyConfig(proxyPort, targetUrl) {
+    const projectRoot = getProjectRoot() || process.env.CODEYAM_ROOT_PATH || process.cwd();
+    const configPath = path.join(projectRoot, '.codeyam', 'proxy-config.json');
+    try {
+        fs.mkdirSync(path.dirname(configPath), { recursive: true });
+        fs.writeFileSync(configPath, JSON.stringify({
+            proxyUrl: `http://localhost:${proxyPort}`,
+            devServerUrl: targetUrl,
+        }), 'utf-8');
+        console.log(`[editorProxy] Wrote proxy config to ${configPath}`);
+    }
+    catch (err) {
+        console.warn('[editorProxy] Failed to write proxy-config.json:', err);
+    }
+}
+/**
+ * Remove proxy-config.json on proxy stop.
+ */
+function removeProxyConfig() {
+    const projectRoot = getProjectRoot() || process.env.CODEYAM_ROOT_PATH || process.cwd();
+    const configPath = path.join(projectRoot, '.codeyam', 'proxy-config.json');
+    try {
+        if (fs.existsSync(configPath)) {
+            fs.unlinkSync(configPath);
+        }
+    }
+    catch {
+        // Best effort
+    }
+}
+/**
+ * Start the editor proxy server.
+ * Intercepts requests to API routes matching the active scenario, forwards everything else.
+ * Supports all HTTP methods (GET, POST, PUT, DELETE, PATCH) with body buffering.
+ */
+export async function startEditorProxy(options) {
+    // If proxy is already running, reuse it (prevents second tab from killing first tab's proxy)
+    const existing = getProxyState();
+    if (existing) {
+        console.log(`[editorProxy] Proxy already running on port ${existing.port} → ${existing.targetUrl}`);
+        return { port: existing.port };
+    }
+    // Stop any leftover state (shouldn't happen, but defensive)
+    await stopEditorProxy();
+    let targetUrl = normalizeTargetUrl(options.targetUrl);
+    let port = options.port;
+    // When the target is localhost, probe to find the correct loopback address.
+    // Dev servers may bind to IPv4 (127.0.0.1) or IPv6 (::1) — Vite 6 on macOS
+    // binds to ::1 by default. We need to match the actual binding.
+    try {
+        const parsed = new URL(targetUrl);
+        if (parsed.hostname === 'localhost') {
+            const targetPort = parseInt(parsed.port || '80', 10);
+            const resolvedHost = await resolveLoopbackAddress(targetPort);
+            if (resolvedHost) {
+                parsed.hostname = resolvedHost;
+                targetUrl = parsed.toString().replace(/\/$/, '');
+                console.log(`[editorProxy] Resolved localhost to ${resolvedHost} for port ${targetPort}`);
+            }
+        }
+    }
+    catch {
+        // Keep original targetUrl
+    }
+    console.log(`[editorProxy] Starting proxy (requested port ${port}, target ${targetUrl})`);
+    const mockState = getMockStateManager();
+    const server = http.createServer((req, res) => {
+        void (async () => {
+            const parsedUrl = new URL(req.url || '/', `http://localhost:${port}`);
+            const pathname = parsedUrl.pathname;
+            const method = req.method || 'GET';
+            // CORS preflight — permissive 204 for browser cross-origin requests
+            if (method === 'OPTIONS') {
+                res.writeHead(204, {
+                    'Access-Control-Allow-Origin': '*',
+                    'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, OPTIONS',
+                    'Access-Control-Allow-Headers': 'Content-Type, Authorization, X-Requested-With',
+                    'Access-Control-Max-Age': '86400',
+                });
+                res.end();
+                return;
+            }
+            // Intercept preview health reports from the injected script
+            if (method === 'POST' && pathname === '/__codeyam__/preview-health') {
+                handlePreviewHealthPost(req, res);
+                return;
+            }
+            // Load scenario data (also feeds MockStateManager)
+            readScenarioData();
+            // For methods that may carry a body, buffer it first
+            const needsBody = method === 'POST' ||
+                method === 'PUT' ||
+                method === 'DELETE' ||
+                method === 'PATCH';
+            if (needsBody) {
+                const bodyBuffer = await bufferRequestBody(req);
+                if (bodyBuffer === null) {
+                    // Body too large — forward without mock matching
+                    forwardBufferedRequest(req, res, targetUrl, null);
+                    return;
+                }
+                // Try to parse body as JSON for mock matching
+                let parsedBody = undefined;
+                if (bodyBuffer.length > 0) {
+                    try {
+                        parsedBody = JSON.parse(bodyBuffer.toString('utf-8'));
+                    }
+                    catch {
+                        // Not JSON — that's fine, still try mock matching without parsed body
+                    }
+                }
+                const match = mockState.matchRequest(method, pathname, parsedBody);
+                if (match) {
+                    console.log(`[editorProxy] Intercepted ${method} ${pathname} → mock response (status ${match.status})`);
+                    res.writeHead(match.status, {
+                        'Content-Type': 'application/json',
+                        'Access-Control-Allow-Origin': '*',
+                        'X-CodeYam-Proxy': 'scenario-data',
+                        'Cache-Control': 'no-store',
+                    });
+                    res.end(match.body != null ? JSON.stringify(match.body) : '');
+                    return;
+                }
+                // No mock match — forward with buffered body
+                forwardBufferedRequest(req, res, targetUrl, bodyBuffer);
+                return;
+            }
+            // GET, HEAD, etc. — try mock matching (no body)
+            const match = mockState.matchRequest(method, pathname);
+            if (match) {
+                console.log(`[editorProxy] Intercepted ${method} ${pathname} → mock response (status ${match.status})`);
+                res.writeHead(match.status, {
+                    'Content-Type': 'application/json',
+                    'Access-Control-Allow-Origin': '*',
+                    'X-CodeYam-Proxy': 'scenario-data',
+                    'Cache-Control': 'no-store',
+                });
+                res.end(match.body != null ? JSON.stringify(match.body) : '');
+                return;
+            }
+            // Forward everything else to the dev server
+            forwardRequest(req, res, targetUrl);
+        })();
+    });
+    // Handle WebSocket upgrades (for HMR)
+    server.on('upgrade', (req, socket, head) => {
+        handleUpgrade(req, socket, head, targetUrl);
+    });
+    // Try to bind, with port fallback
+    const maxAttempts = 10;
+    for (let attempt = 0; attempt < maxAttempts; attempt++) {
+        const currentPort = port + attempt;
+        try {
+            await new Promise((resolve, reject) => {
+                server.once('error', reject);
+                server.listen(currentPort, '0.0.0.0', () => {
+                    server.removeListener('error', reject);
+                    resolve();
+                });
+            });
+            // When port 0 is requested, the OS assigns an ephemeral port
+            const addr = server.address();
+            port =
+                typeof addr === 'object' && addr !== null ? addr.port : currentPort;
+            const state = { server, port, targetUrl };
+            setProxyState(state);
+            // Write proxy-config.json for the preload module
+            writeProxyConfig(port, targetUrl);
+            console.log(`[editorProxy] Proxy started on port ${port}, forwarding to ${targetUrl}`);
+            return { port };
+        }
+        catch (err) {
+            if (err?.code === 'EADDRINUSE' && attempt < maxAttempts - 1) {
+                console.log(`[editorProxy] Port ${currentPort} in use, trying ${currentPort + 1}`);
+                continue;
+            }
+            console.error(`[editorProxy] Failed to start proxy:`, err);
+            return null;
+        }
+    }
+    return null;
+}
+/**
+ * Stop the editor proxy server.
+ */
+export async function stopEditorProxy() {
+    const state = getProxyState();
+    if (!state)
+        return;
+    console.log(`[editorProxy] Stopping proxy on port ${state.port}`);
+    removeProxyConfig();
+    return new Promise((resolve) => {
+        state.server.close(() => {
+            console.log('[editorProxy] Proxy stopped');
+            resolve();
+        });
+        setProxyState(null);
+        // Force-close after 2s if graceful close doesn't happen
+        setTimeout(resolve, 2000);
+    });
+}
+/**
+ * Invalidate the scenario data cache (e.g., after writing a new active-scenario.json).
+ */
+export function invalidateScenarioCache() {
+    scenarioCache = { data: null, timestamp: 0 };
+    sessionConfig = undefined;
+    localStorageConfig = null;
+    activeScenarioId = null;
+    currentPrototypeId = null;
+}
+/**
+ * Verify that the proxy can successfully forward a request to the target dev server.
+ * Makes a HEAD request through the proxy and checks that it gets a response (any status).
+ * Returns false if the proxy isn't running or if the request fails entirely.
+ */
+export async function verifyProxyForwarding() {
+    const state = getProxyState();
+    if (!state) {
+        console.warn('[editorProxy] Cannot verify — proxy is not running');
+        return false;
+    }
+    try {
+        const response = await fetch(`http://127.0.0.1:${state.port}/`, {
+            method: 'HEAD',
+            signal: AbortSignal.timeout(5000),
+        });
+        // Any response from the target (even 404) means forwarding works.
+        // Only 502 (our own Bad Gateway) means the target is unreachable.
+        if (response.status === 502) {
+            console.warn(`[editorProxy] Verification failed — proxy returned 502 (target unreachable)`);
+            return false;
+        }
+        console.log(`[editorProxy] Verification passed — proxy forwarding to ${state.targetUrl} (status ${response.status})`);
+        return true;
+    }
+    catch (err) {
+        console.warn(`[editorProxy] Verification failed — could not reach proxy on port ${state.port}`);
+        return false;
+    }
+}
+/**
+ * Ensure the proxy is running. If it's not, start it using the current dev server URL.
+ * Returns the proxy URL once ready, or null if it can't be started.
+ *
+ * Used by capture flows to guarantee the proxy is listening before Playwright navigates.
+ */
+export async function ensureProxyRunning() {
+    // Already running?
+    const existing = getProxyUrl();
+    if (existing) {
+        console.log(`[editorProxy] Proxy already running at ${existing}`);
+        return existing;
+    }
+    // Try to start it — we need the dev server URL
+    const devServer = globalThis.__codeyam_editor_dev_server__;
+    if (!devServer || devServer.status !== 'running' || !devServer.url) {
+        console.log('[editorProxy] Cannot start proxy — dev server not running');
+        return null;
+    }
+    const codeyamPort = parseInt(process.env.CODEYAM_PORT || '3111', 10);
+    const { proxyPort } = computeEditorPorts(codeyamPort);
+    console.log(`[editorProxy] Proxy not running, starting on-demand (port ${proxyPort}, target ${devServer.url})`);
+    const result = await startEditorProxy({
+        port: proxyPort,
+        targetUrl: devServer.url,
+    });
+    if (result) {
+        const url = `http://localhost:${result.port}`;
+        console.log(`[editorProxy] On-demand proxy started at ${url}`);
+        return url;
+    }
+    console.error('[editorProxy] Failed to start on-demand proxy');
+    return null;
+}
+/**
+ * Test-only export: trigger readScenarioData so tests can verify session config extraction.
+ */
+export const _readScenarioDataForTest = readScenarioData;
+//# sourceMappingURL=editorProxy.js.map