@codeyam/codeyam-cli 0.1.0-staging.d0ad4ae → 0.1.0-staging.d57a578

package/codeyam-cli/src/webserver/scripts/journalCapture.ts

@@ -0,0 +1,230 @@
+#!/usr/bin/env npx tsx
+/**
+ * Lightweight Playwright script for journal screenshots.
+ * No DB lookups, no mock data regeneration — just navigate and screenshot.
+ *
+ * Usage: npx tsx journalCapture.ts '<json-args>'
+ * Args: { url, outputPath, viewportWidth?, viewportHeight? }
+ */
+
+import { chromium, Page } from 'playwright';
+
+/**
+ * Wait until DOM mutations stop for `quietMs`, or until `maxWaitMs` elapsed.
+ * Uses MutationObserver to detect when React has finished rendering,
+ * including data-driven re-renders from useEffect fetches.
+ *
+ * Same pattern used in takeElementScreenshot.ts (background package).
+ *
+ * Uses string-based evaluate to avoid tsx/esbuild __name decorator issues
+ * when the function is serialized for browser execution.
+ */
+async function waitForDomIdle(
+  page: Page,
+  quietMs: number,
+  maxWaitMs: number,
+): Promise<void> {
+  await page.evaluate(`
+    new Promise(function(resolve) {
+      var timer;
+      var startTime = Date.now();
+
+      function finish() {
+        clearTimeout(timer);
+        observer.disconnect();
+        resolve();
+      }
+
+      function reset() {
+        clearTimeout(timer);
+        if (Date.now() - startTime >= ${maxWaitMs}) { finish(); return; }
+        timer = setTimeout(finish, ${quietMs});
+      }
+
+      var observer = new MutationObserver(reset);
+      observer.observe(document, {
+        childList: true,
+        subtree: true,
+        attributes: true
+      });
+
+      setTimeout(finish, ${maxWaitMs});
+      reset();
+    })
+  `);
+}
+
+/**
+ * Stabilize the page before taking a screenshot.
+ *
+ * Handles client-side rendered content (React useEffect + fetch pattern):
+ * 1. Wait for DOM to settle after initial hydration
+ * 2. Wait for any network requests triggered by client JS (useEffect fetches)
+ * 3. Wait for DOM to settle again after data-driven re-renders
+ * 4. Wait for web fonts to load
+ */
+async function stabilizePage(page: Page): Promise<void> {
+  // 1. Wait for React hydration / initial client rendering to settle
+  await waitForDomIdle(page, DOM_IDLE_QUIET_MS, DOM_IDLE_MAX_WAIT_MS);
+
+  // 2. Wait for any network requests triggered by client-side JS
+  //    (e.g. useEffect → fetch('/api/data')). This catches in-flight requests
+  //    that started during or after hydration.
+  try {
+    await page.waitForLoadState('networkidle', {
+      timeout: POST_LOAD_NETWORK_TIMEOUT_MS,
+    });
+  } catch {
+    // Timeout is OK — some pages have persistent connections (WebSocket, SSE)
+  }
+
+  // 3. Wait for data-driven re-renders to settle
+  await waitForDomIdle(page, DOM_IDLE_QUIET_MS, DOM_IDLE_MAX_WAIT_MS);
+
+  // 4. Wait for web fonts (string-based to avoid tsx __name decorator issues)
+  try {
+    await page.waitForFunction(
+      `document.fonts ? document.fonts.status === 'loaded' : true`,
+      { timeout: FONTS_TIMEOUT_MS },
+    );
+  } catch {
+    // Font loading timeout — continue anyway
+  }
+}
+
+interface CaptureArgs {
+  url: string;
+  outputPath: string;
+  viewportWidth?: number;
+  viewportHeight?: number;
+  /** CSS selector for element-level screenshot (e.g. '#codeyam-capture').
+   *  If provided, screenshots just that element instead of the full page. */
+  selector?: string;
+}
+
+const MAX_RETRIES = 2;
+const GOTO_TIMEOUT_MS = 15_000;
+const DOM_IDLE_QUIET_MS = 500;
+const DOM_IDLE_MAX_WAIT_MS = 5_000;
+const POST_LOAD_NETWORK_TIMEOUT_MS = 5_000;
+const FONTS_TIMEOUT_MS = 5_000;
+
+async function main() {
+  const args = process.argv.slice(2);
+  if (args.length < 1) {
+    console.error('Usage: journalCapture.ts <json-args>');
+    process.exit(1);
+  }
+
+  const config: CaptureArgs = JSON.parse(args[0]);
+  const {
+    url,
+    outputPath,
+    viewportWidth = 1280,
+    viewportHeight = 720,
+    selector,
+  } = config;
+
+  console.log(`[JournalCapture] URL: ${url}`);
+  console.log(`[JournalCapture] Output: ${outputPath}`);
+  console.log(`[JournalCapture] Viewport: ${viewportWidth}x${viewportHeight}`);
+
+  const browser = await chromium.launch({ headless: true });
+
+  try {
+    const context = await browser.newContext({
+      viewport: { width: viewportWidth, height: viewportHeight },
+    });
+    const page = await context.newPage();
+
+    // Log console messages from the page for debugging
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        console.log(`[JournalCapture] Page console.error: ${msg.text()}`);
+      }
+    });
+
+    // Log failed network requests
+    page.on('requestfailed', (request) => {
+      console.log(
+        `[JournalCapture] Network failed: ${request.method()} ${request.url()} — ${request.failure()?.errorText || 'unknown'}`,
+      );
+    });
+
+    let lastError: Error | null = null;
+
+    for (let attempt = 1; attempt <= MAX_RETRIES; attempt++) {
+      try {
+        console.log(
+          `[JournalCapture] Navigating (attempt ${attempt}/${MAX_RETRIES})...`,
+        );
+
+        const response = await page.goto(url, {
+          waitUntil: 'networkidle',
+          timeout: GOTO_TIMEOUT_MS,
+        });
+
+        if (response) {
+          console.log(
+            `[JournalCapture] Page loaded: status=${response.status()}, url=${response.url()}`,
+          );
+        }
+
+        // Wait for client-side rendering to complete (React hydration,
+        // useEffect data fetches, font loading, etc.)
+        await stabilizePage(page);
+
+        const pageTitle = await page.title();
+        console.log(`[JournalCapture] Page title: ${pageTitle}`);
+
+        if (selector) {
+          // Element-level screenshot — captures just the wrapper element
+          const element = page.locator(selector);
+          try {
+            await element.waitFor({ state: 'visible', timeout: 5000 });
+            await element.screenshot({ path: outputPath });
+            console.log(
+              `[JournalCapture] Element screenshot: selector=${selector}`,
+            );
+          } catch {
+            // Selector not found — fall back to full-page screenshot
+            console.warn(
+              `[JournalCapture] Selector "${selector}" not found, falling back to full page`,
+            );
+            await page.screenshot({ path: outputPath, fullPage: true });
+          }
+        } else {
+          await page.screenshot({ path: outputPath, fullPage: true });
+        }
+
+        console.log(
+          `[JournalCapture] RESULT:${JSON.stringify({ success: true, path: outputPath })}`,
+        );
+        return; // Success
+      } catch (error) {
+        lastError = error instanceof Error ? error : new Error(String(error));
+        console.warn(
+          `[JournalCapture] Attempt ${attempt} failed: ${lastError.message}`,
+        );
+
+        if (attempt < MAX_RETRIES) {
+          // Wait a bit before retrying (server might still be starting)
+          const backoffMs = attempt * 2000;
+          console.log(`[JournalCapture] Retrying in ${backoffMs}ms...`);
+          await new Promise((r) => setTimeout(r, backoffMs));
+        }
+      }
+    }
+
+    // All retries exhausted
+    const message = lastError?.message || 'Unknown error';
+    console.error(
+      `[JournalCapture] All ${MAX_RETRIES} attempts failed: ${message}`,
+    );
+    process.exit(1);
+  } finally {
+    await browser.close();
+  }
+}
+
+void main();

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

@@ -1,11 +1,12 @@
 // codeyam-cli/src/webserver/server.ts
-import express from "express";
-import path from "path";
-import { fileURLToPath } from "url";
-import { createRequestHandler } from "@react-router/express";
-import fs from "fs";
+import express from 'express';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { createRequestHandler } from '@react-router/express';
+import fs from 'fs';
+import { cliVersion } from "../utils/versionInfo.js";
 // BUILD VERSION MARKER - Change this timestamp when rebuilding to verify build is current
-const SERVER_BUILD_VERSION = "2025-01-07T16:00:00.000Z";
+const SERVER_BUILD_VERSION = '2025-01-07T16:00:00.000Z';
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 function toFileUrl(p) {
@@ -21,22 +22,31 @@ function exists(p) {
     }
 }
 const WEBSERVER_ROOT = __dirname;
-const BUILD_FILE = path.join(WEBSERVER_ROOT, "build", "server", "index.js");
-const CLIENT_BUILD_DIR = path.join(WEBSERVER_ROOT, "build", "client");
+const BUILD_FILE = path.join(WEBSERVER_ROOT, 'build', 'server', 'index.js');
+const CLIENT_BUILD_DIR = path.join(WEBSERVER_ROOT, 'build', 'client');
 async function loadBuild(cacheBust = false) {
-    const href = cacheBust ? `${toFileUrl(BUILD_FILE)}?t=${Date.now()}` : toFileUrl(BUILD_FILE);
+    const href = cacheBust
+        ? `${toFileUrl(BUILD_FILE)}?t=${Date.now()}`
+        : toFileUrl(BUILD_FILE);
     const mod = await import(href);
     return (mod.default ?? mod);
 }
 const app = express();
-app.use(express.static(path.join(WEBSERVER_ROOT, "public")));
+app.use(express.static(path.join(WEBSERVER_ROOT, 'public')));
 // Serve Vite-built assets with immutable cache FIRST (these never conflict with routes)
-app.use("/assets", express.static(path.join(CLIENT_BUILD_DIR, "assets"), { immutable: true, maxAge: "1y" }));
-app.get("/api/health", (_req, res) => {
-    res.json({ status: "ok", message: "CodeYam Remix server is running" });
+app.use('/assets', express.static(path.join(CLIENT_BUILD_DIR, 'assets'), {
+    immutable: true,
+    maxAge: '1y',
+}));
+app.get('/api/health', (_req, res) => {
+    res.json({
+        status: 'ok',
+        version: cliVersion,
+        message: 'CodeYam Remix server is running',
+    });
 });
 // Handle Chrome DevTools protocol discovery request
-app.get("/.well-known/appspecific/com.chrome.devtools.json", (_req, res) => {
+app.get('/.well-known/appspecific/com.chrome.devtools.json', (_req, res) => {
     res.status(204).end();
 });
 function createDevHandler() {
@@ -45,11 +55,11 @@ function createDevHandler() {
             const build = await loadBuild(true); // cache-bust per request
             return createRequestHandler({
                 build,
-                mode: "development",
+                mode: 'development',
                 getLoadContext: () => ({
                     analysisQueue: app.locals.analysisQueue,
-                    dbNotifier: app.locals.dbNotifier
-                })
+                    dbNotifier: app.locals.dbNotifier,
+                }),
             })(req, res, next);
         }
         catch (err) {
@@ -66,11 +76,11 @@ function createProdHandler() {
             const build = await buildPromise;
             return createRequestHandler({
                 build,
-                mode: "production",
+                mode: 'production',
                 getLoadContext: () => ({
                     analysisQueue: app.locals.analysisQueue,
-                    dbNotifier: app.locals.dbNotifier
-                })
+                    dbNotifier: app.locals.dbNotifier,
+                }),
             })(req, res, next);
         }
         catch (err) {
@@ -78,16 +88,310 @@ function createProdHandler() {
         }
     };
 }
+// Dev mode preview refresh — handled directly by Express (not React Router)
+// so it works without rebuilding when new route files are added.
+// Broadcasts via WebSocket to the Terminal component which relays to the parent page.
+// Also clears the server log so Claude always sees fresh output after a refresh.
+// After refresh, fetches the preview URL to detect SSR errors (HTTP 500, etc.)
+// that frameworks catch in error boundaries but never write to stdout/stderr.
+// Cache the preview URL — it's stable per dev-mode session
+let cachedPreviewUrl = null;
+/**
+ * Extract the preview URL from the log file. The dev server writes a line like:
+ *   $$INTERACTIVE_SERVER_URL$$:http://localhost:5173/project/codeyam-sample
+ * Must be called BEFORE the log is cleared.
+ */
+function getPreviewUrl(logPath) {
+    if (cachedPreviewUrl)
+        return cachedPreviewUrl;
+    try {
+        const content = fs.readFileSync(logPath, 'utf8');
+        const lines = content.split('\n');
+        const urlLine = lines.find((line) => line.includes('$$INTERACTIVE_SERVER_URL$$:'));
+        if (urlLine) {
+            cachedPreviewUrl = urlLine.split('$$INTERACTIVE_SERVER_URL$$:')[1].trim();
+            return cachedPreviewUrl;
+        }
+    }
+    catch {
+        // Log file not readable — not critical
+    }
+    return null;
+}
+/**
+ * Extract human-readable error text from an HTML error page.
+ * Works across frameworks (Remix error boundaries, Next.js error pages, etc.)
+ */
+function extractErrorFromHtml(html) {
+    // 1. Look for <pre> tag content (most frameworks put stack traces here)
+    const preMatch = html.match(/<pre[^>]*>([\s\S]*?)<\/pre>/i);
+    if (preMatch) {
+        return decodeHtmlEntities(stripTags(preMatch[1])).trim().slice(0, 2000);
+    }
+    // 2. Look for error-related headings
+    const headingMatch = html.match(/<h[12][^>]*>([\s\S]*?)<\/h[12]>/i);
+    if (headingMatch) {
+        const headingText = decodeHtmlEntities(stripTags(headingMatch[1])).trim();
+        if (/error|exception|crash|fail/i.test(headingText) ||
+            /error|exception|crash|fail/i.test(html)) {
+            // Also grab any following paragraph or pre for context
+            const bodyMatch = html.match(/<(?:p|pre|div[^>]*class="[^"]*error[^"]*")[^>]*>([\s\S]*?)<\/(?:p|pre|div)>/i);
+            const body = bodyMatch
+                ? '\n' + decodeHtmlEntities(stripTags(bodyMatch[1])).trim()
+                : '';
+            return (headingText + body).slice(0, 2000);
+        }
+    }
+    // 3. Fall back to stripping all HTML tags
+    const stripped = decodeHtmlEntities(stripTags(html)).trim();
+    return stripped.slice(0, 2000);
+}
+function stripTags(html) {
+    return html.replace(/<[^>]+>/g, '');
+}
+function decodeHtmlEntities(text) {
+    return text
+        .replace(/&#x27;/g, "'")
+        .replace(/&quot;/g, '"')
+        .replace(/&amp;/g, '&')
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&#(\d+);/g, (_m, code) => String.fromCharCode(Number(code)))
+        .replace(/&#x([0-9a-fA-F]+);/g, (_m, code) => String.fromCharCode(parseInt(code, 16)));
+}
+/**
+ * Fetch the preview URL and check if the page loaded successfully.
+ * Returns health status with error details if the page returned an error.
+ */
+async function checkPreviewHealth(url) {
+    try {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), 5000);
+        const response = await fetch(url, { signal: controller.signal });
+        clearTimeout(timeout);
+        if (response.ok) {
+            return { status: response.status, healthy: true };
+        }
+        // Non-OK response — try to extract error from HTML body
+        const body = await response.text();
+        const error = extractErrorFromHtml(body);
+        return { status: response.status, healthy: false, error };
+    }
+    catch (err) {
+        if (err.cause?.code === 'ECONNREFUSED' || err.code === 'ECONNREFUSED') {
+            return {
+                status: null,
+                healthy: false,
+                error: 'Preview server is not running (ECONNREFUSED)',
+            };
+        }
+        if (err.name === 'AbortError') {
+            return {
+                status: null,
+                healthy: false,
+                error: 'Preview server timed out (5s)',
+            };
+        }
+        return {
+            status: null,
+            healthy: false,
+            error: `Preview check failed: ${err.message}`,
+        };
+    }
+}
+// Unified preview control — refresh, navigate, switch scenario, or any combination.
+// Handles log clearing, HMR settle, SSR health check, scenario switching, and navigation.
+app.post('/api/dev-mode-preview', express.json(), async (req, res) => {
+    const { scenarioSlug, scenarioId, path: navPath, dimension } = req.body || {};
+    // Dimension is required — the viewport must always be explicitly set to avoid
+    // mismatched viewport sizes (e.g., popup content squeezed into a desktop-sized preview).
+    if (!dimension || typeof dimension !== 'string') {
+        let availableDimensions = [];
+        try {
+            const configPath = path.join(process.cwd(), '.codeyam', 'config.json');
+            const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+            if (config.screenSizes) {
+                availableDimensions = Object.keys(config.screenSizes);
+            }
+        }
+        catch {
+            // Config not available
+        }
+        const hint = availableDimensions.length > 0
+            ? ` Available dimensions: ${availableDimensions.map((d) => `"${d}"`).join(', ')}.`
+            : '';
+        res.status(400).json({
+            success: false,
+            error: `"dimension" is required. Every preview call must specify the viewport dimension explicitly.${hint}`,
+        });
+        return;
+    }
+    let sessionsNotified = 0;
+    let logCleared = false;
+    // 1. Read config and resolve log path
+    let logPath = null;
+    try {
+        const configPath = path.join(process.cwd(), '.codeyam', 'config.json');
+        const config = JSON.parse(fs.readFileSync(configPath, 'utf8'));
+        if (config.projectSlug) {
+            logPath = `/tmp/codeyam/local-dev/${config.projectSlug}/codeyam/log.txt`;
+        }
+    }
+    catch {
+        // Config not available — not critical
+    }
+    // 2. Extract preview URL from log BEFORE clearing it
+    let previewUrl = null;
+    if (logPath && fs.existsSync(logPath)) {
+        previewUrl = getPreviewUrl(logPath);
+    }
+    // Fall back to cached URL if log didn't have it
+    if (!previewUrl)
+        previewUrl = cachedPreviewUrl;
+    // 3. Switch scenario if provided (accepts scenarioId alone or scenarioSlug+scenarioId)
+    const effectiveScenarioId = scenarioId || null;
+    let effectiveSlug = scenarioSlug || null;
+    let scenarioUrl = null;
+    // Look up the scenario's URL from the database for navigation fallback
+    if (effectiveScenarioId) {
+        try {
+            const { getDatabase } = await import('../../../packages/database/index.js');
+            const db = getDatabase();
+            const row = await db
+                .selectFrom('editor_scenarios')
+                .select(['url'])
+                .where('id', '=', effectiveScenarioId)
+                .executeTakeFirst();
+            if (row?.url) {
+                scenarioUrl = row.url;
+            }
+        }
+        catch {
+            // DB not available — non-critical
+        }
+    }
+    // Switch active scenario using the shared logic that handles type detection,
+    // active-scenario.json writes, and seed adapter execution for app/user scenarios.
+    if (effectiveScenarioId) {
+        try {
+            const { switchActiveScenario } = await import('../utils/editorScenarioSwitch.js');
+            const projectRoot = process.env.CODEYAM_ROOT_PATH || process.cwd();
+            const switchResult = await switchActiveScenario({
+                scenarioId: effectiveScenarioId,
+                scenarioSlug: effectiveSlug || undefined,
+                projectRoot,
+            });
+            effectiveSlug = switchResult.scenarioSlug;
+            // Invalidate proxy cache so it picks up new scenario data
+            const { invalidateScenarioCache } = await import('./editorProxy.js');
+            invalidateScenarioCache();
+        }
+        catch {
+            // Scenario switch failed — not critical, continue with refresh
+        }
+    }
+    // 4a. Resolve viewport from explicit dimension and broadcast set-viewport before refresh.
+    // Dimension is always present (validated above), so this always resolves.
+    try {
+        const { resolveViewportWithProjectDefault } = await import('../utils/editorScenarios.js');
+        const projectRoot = process.env.CODEYAM_ROOT_PATH || process.cwd();
+        const resolved = resolveViewportWithProjectDefault({
+            dimension,
+            codeyamRoot: projectRoot,
+        });
+        const { broadcastSetViewport } = await import('./terminalServer.js');
+        broadcastSetViewport({
+            name: dimension,
+            width: resolved.width,
+            height: resolved.height,
+        });
+    }
+    catch {
+        // Viewport resolution or broadcast failed — non-critical
+    }
+    // 4b. Broadcast WebSocket refresh to browser (iframe starts reloading)
+    // Use explicit path, or fall back to scenario URL from DB, so the preview
+    // navigates to the correct page (e.g. /drinks/1 for a detail page scenario).
+    try {
+        const { broadcastPreviewRefresh } = await import('./terminalServer.js');
+        const { resolvePreviewNavPath } = await import('../utils/editorScenarios.js');
+        const effectivePath = resolvePreviewNavPath(navPath, scenarioUrl);
+        sessionsNotified = broadcastPreviewRefresh(effectivePath, effectiveScenarioId);
+    }
+    catch {
+        // Terminal server not loaded yet — ignore
+    }
+    // 5. Clear the server log so post-refresh log reads only show fresh output
+    if (logPath && fs.existsSync(logPath)) {
+        try {
+            fs.writeFileSync(logPath, '');
+            logCleared = true;
+        }
+        catch {
+            // Log file not writable — not critical
+        }
+    }
+    // 6. Wait for HMR to settle and the page to re-render
+    await new Promise((resolve) => setTimeout(resolve, 2000));
+    // 7. Compute the full URL (with navigation path if provided)
+    let fullUrl = previewUrl;
+    if (navPath && previewUrl) {
+        try {
+            fullUrl = new URL(navPath, previewUrl).href;
+        }
+        catch {
+            fullUrl = previewUrl;
+        }
+    }
+    // 8. Fetch the preview URL to detect SSR errors
+    let preview = null;
+    const healthCheckUrl = fullUrl || previewUrl;
+    if (healthCheckUrl) {
+        preview = await checkPreviewHealth(healthCheckUrl);
+        // If unhealthy, write error to log so Claude can see it via tail
+        if (!preview.healthy && preview.error && logPath) {
+            try {
+                const errorLines = preview.error
+                    .split('\n')
+                    .map((line) => `[DEV-MODE-CHECK] ${line}`)
+                    .join('\n');
+                fs.appendFileSync(logPath, errorLines + '\n');
+            }
+            catch {
+                // Log write failed — the error is still in the response
+            }
+        }
+    }
+    res.json({
+        success: true,
+        sessionsNotified,
+        logCleared,
+        url: fullUrl || null,
+        preview,
+    });
+});
+// Show results panel in the editor Build tab — triggered by Claude at end of step 12.
+app.post('/api/editor-show-results', async (_req, res) => {
+    const { broadcastShowResults } = await import('./terminalServer.js');
+    const sessionsNotified = broadcastShowResults();
+    res.json({ success: true, sessionsNotified });
+});
+// Hide results panel — triggered by Claude before making changes.
+app.post('/api/editor-hide-results', async (_req, res) => {
+    const { broadcastHideResults } = await import('./terminalServer.js');
+    const sessionsNotified = broadcastHideResults();
+    res.json({ success: true, sessionsNotified });
+});
 // Handle Remix routes (API routes, page routes, etc.)
-if (process.env.NODE_ENV === "development") {
+if (process.env.NODE_ENV === 'development') {
     app.use(createDevHandler());
 }
 else {
     app.use(createProdHandler());
 }
 // Serve other client files as fallback
-app.use(express.static(CLIENT_BUILD_DIR, { maxAge: "1h" }));
-export function startRemixServer({ port, analysisQueue, dbNotifier }) {
+app.use(express.static(CLIENT_BUILD_DIR, { maxAge: '1h' }));
+export function startRemixServer({ port, analysisQueue, dbNotifier, }) {
     console.log('[Server] ========================================');
     console.log('[Server] SERVER BUILD VERSION:', SERVER_BUILD_VERSION);
     console.log('[Server] Starting Remix server initialization...');
@@ -98,7 +402,7 @@ export function startRemixServer({ port, analysisQueue, dbNotifier }) {
         console.log('[Server] ✅ Analysis queue stored in app.locals');
         console.log('[Server]    Queue state:', {
             jobs: analysisQueue.getState().jobs.length,
-            paused: analysisQueue.getState().paused
+            paused: analysisQueue.getState().paused,
         });
     }
     else {
@@ -129,7 +433,9 @@ export function startRemixServer({ port, analysisQueue, dbNotifier }) {
             console.warn(`[Server] ⚠️  Remix client build directory not found at:\n    ${CLIENT_BUILD_DIR}\n` +
                 `Make sure you ran "remix vite:build".`);
         }
-        const server = app.listen(port, () => {
+        // Bind explicitly to 0.0.0.0 (IPv4) to avoid IPv6 dual-stack issues
+        // that cause ECONNRESET when Node.js fetch resolves localhost to ::1
+        const server = app.listen(port, '0.0.0.0', () => {
             const url = `http://localhost:${port}`;
             console.log('[Server] ========================================');
             console.log(`[Server] ✅ Remix app running at ${url}`);
@@ -137,7 +443,10 @@ export function startRemixServer({ port, analysisQueue, dbNotifier }) {
             console.log('[Server] ========================================');
             resolve({ url, server });
         });
-        server.on("error", reject);
+        server.on('error', reject);
+        server.on('close', () => {
+            console.error('[Server] ⚠️  HTTP server socket CLOSED unexpectedly');
+        });
     });
 }
 //# sourceMappingURL=server.js.map