@timber-js/app 0.2.0-alpha.14 → 0.2.0-alpha.141

package/src/dev-tools/error-page.ts

@@ -0,0 +1,507 @@
+/**
+ * Dev error page — self-contained HTML error page for dev server 500s.
+ *
+ * Generates a styled, self-contained HTML page when the RSC pipeline fails
+ * and the Vite error overlay can't fire (e.g., first page load before HMR
+ * WebSocket connects, RSC entry module crash, early pipeline errors).
+ *
+ * This is NOT a replacement for Vite's error overlay — it's the fallback
+ * for when the overlay's transport (WebSocket) isn't available yet.
+ *
+ * Dev-only: this module is only imported by dev-server.ts (apply: 'serve').
+ * It is never included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import { extractComponentStack, parseFirstAppFrame, type ErrorPhase } from './overlay.js';
+import { classifyStack } from './stack-classifier.js';
+import { escapeHtml } from '../server/utils/escape-html.js';
+
+// ─── Phase Labels ───────────────────────────────────────────────────────────
+
+const PHASE_LABELS: Record<ErrorPhase, string> = {
+  'module-transform': 'Module Transform',
+  'proxy': 'Proxy',
+  'middleware': 'Middleware',
+  'access': 'Access Check',
+  'render': 'RSC Render',
+  'handler': 'Route Handler',
+};
+
+const PHASE_HINTS: Record<ErrorPhase, string> = {
+  'module-transform':
+    'This error occurred while Vite was transforming a module. Check for syntax errors or missing imports.',
+  'proxy': 'This error occurred in proxy.ts. Check your proxy configuration.',
+  'middleware':
+    'This error occurred in a middleware.ts file. Check the middleware function for unhandled exceptions.',
+  'access': 'This error occurred in an access.ts file. Check your access control logic.',
+  'render':
+    'This error occurred while rendering a server component. Check the component for runtime errors.',
+  'handler': 'This error occurred in a route handler (route.ts). Check the handler function.',
+};
+
+// ─── Source Context ─────────────────────────────────────────────────────────
+
+/**
+ * Try to read a few lines of source code around the error location.
+ * Returns null if the file can't be read (e.g., virtual modules).
+ */
+function readSourceContext(
+  filePath: string,
+  line: number,
+  contextLines = 3
+): { lines: Array<{ num: number; text: string; highlight: boolean }>; startLine: number } | null {
+  try {
+    // eslint-disable-next-line no-var-requires -- sync require needed at render time
+    const { readFileSync } = require('node:fs');
+    const content = readFileSync(filePath, 'utf-8');
+    const allLines = content.split('\n');
+
+    const start = Math.max(0, line - 1 - contextLines);
+    const end = Math.min(allLines.length, line + contextLines);
+
+    return {
+      startLine: start + 1,
+      lines: allLines.slice(start, end).map((text: string, i: number) => ({
+        num: start + 1 + i,
+        text,
+        highlight: start + 1 + i === line,
+      })),
+    };
+  } catch (e) {
+    console.debug('[timber] source context extraction failed:', e instanceof Error ? e.message : e);
+    return null;
+  }
+}
+
+// HTML escaping provided by server/utils/escape-html.ts
+const esc = escapeHtml;
+
+/**
+ * Escape a JSON string for safe embedding in an HTML `<script>` block.
+ *
+ * `JSON.stringify` does not escape `</script>`, so error text containing
+ * that sequence breaks out of the script block — an XSS vector.
+ * We replace all `<` with `\u003c` which is valid in JSON strings and
+ * prevents the HTML parser from seeing a closing `</script>` tag.
+ *
+ * Security: TIM-788
+ */
+function escJsonForScript(json: string): string {
+  return json.replace(/</g, '\\u003c');
+}
+
+// ─── HMR Options ────────────────────────────────────────────────────────────
+
+/**
+ * HMR connection options for the dev error page auto-reload WebSocket.
+ * Derived from Vite's resolved server config so the error page can
+ * connect to the correct HMR endpoint (TIM-789).
+ */
+export interface DevErrorHmrOptions {
+  protocol?: string;
+  host?: string;
+  port?: number;
+  path?: string;
+  token?: string;
+}
+
+/**
+ * Build a WebSocket URL from Vite HMR options.
+ * Mirrors the logic in Vite's client.mjs for constructing the WS connection URL.
+ */
+function buildWsUrl(opts: DevErrorHmrOptions): string {
+  const protocol = opts.protocol ?? 'ws';
+  const host = opts.host ?? 'localhost';
+  const port = opts.port ? `:${opts.port}` : '';
+  const path = opts.path ?? '';
+  const token = opts.token ? `?token=${opts.token}` : '';
+  return `${protocol}://${host}${port}${path}${token}`;
+}
+
+/**
+ * Extract HMR connection options from a Vite resolved config.
+ * Used by the dev server to pass HMR config to the error page generator
+ * so the auto-reload WebSocket connects to the correct endpoint.
+ */
+export function extractHmrOptions(config: {
+  server?: { hmr?: { protocol?: string; host?: string; port?: number; path?: string } | boolean };
+  webSocketToken?: string;
+}): DevErrorHmrOptions | undefined {
+  const hmr = config.server?.hmr;
+  if (hmr === false) return undefined;
+  const hmrOpts = typeof hmr === 'object' ? hmr : {};
+  const opts: DevErrorHmrOptions = {
+    protocol: hmrOpts.protocol,
+    host: hmrOpts.host,
+    port: hmrOpts.port,
+    path: hmrOpts.path,
+    token: config.webSocketToken,
+  };
+  // If no HMR fields were explicitly configured, return undefined so the
+  // error page falls back to `'ws://' + location.host` which correctly
+  // includes the browser's current port (TIM-805).
+  if (!opts.protocol && !opts.host && !opts.port && !opts.path && !opts.token) {
+    return undefined;
+  }
+  return opts;
+}
+
+// ─── HTML Generation ────────────────────────────────────────────────────────
+
+/**
+ * Generate a self-contained HTML error page for dev server 500 responses.
+ *
+ * The page includes:
+ * - Error message and phase label
+ * - Source code context around the first app frame (if readable)
+ * - Component stack (for React render errors)
+ * - Classified stack trace (app frames highlighted, internals collapsed)
+ * - Copy button for the full error
+ * - Dark/light mode via prefers-color-scheme
+ * - Auto-reconnect script that watches for Vite HMR and reloads
+ */
+export function generateDevErrorPage(
+  error: Error,
+  phase: ErrorPhase,
+  projectRoot: string,
+  hmrOptions?: DevErrorHmrOptions
+): string {
+  const message = error.message || 'Unknown error';
+  const phaseLabel = PHASE_LABELS[phase];
+  const phaseHint = PHASE_HINTS[phase];
+  const componentStack = extractComponentStack(error);
+  const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
+  const frames = error.stack ? classifyStack(error.stack, projectRoot) : [];
+  const appFrames = frames.filter((f) => f.type === 'app');
+  const internalFrameCount = frames.filter((f) => f.type !== 'app').length;
+
+  // Try to read source code context
+  let sourceContext: ReturnType<typeof readSourceContext> = null;
+  if (loc) {
+    sourceContext = readSourceContext(loc.file, loc.line);
+  }
+
+  // Relative path for display
+  const relPath = loc?.file.startsWith(projectRoot)
+    ? loc.file.slice(projectRoot.length + 1)
+    : loc?.file;
+
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>Error — ${esc(phaseLabel)} | timber.js</title>
+  <style>${CSS}</style>
+</head>
+<body>
+  <div class="container">
+    <header class="header">
+      <div class="badge">${esc(phaseLabel)} Error</div>
+      <h1 class="message">${esc(message)}</h1>
+      ${phaseHint ? `<p class="hint">${esc(phaseHint)}</p>` : ''}
+    </header>
+
+    ${relPath ? `<div class="location">${esc(relPath)}${loc ? `:${loc.line}:${loc.column}` : ''}</div>` : ''}
+
+    ${
+      sourceContext
+        ? `<div class="source-context">
+        <div class="source-header">Source</div>
+        <pre class="source-code"><code>${sourceContext.lines
+          .map(
+            (l) =>
+              `<span class="source-line${l.highlight ? ' source-line-highlight' : ''}"` +
+              `><span class="line-num">${l.num}</span>${esc(l.text)}</span>`
+          )
+          .join('\n')}</code></pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      componentStack
+        ? `<div class="section">
+        <div class="section-header">Component Stack</div>
+        <pre class="component-stack">${esc(componentStack.trim())}</pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      appFrames.length > 0
+        ? `<div class="section">
+        <div class="section-header">Application Frames</div>
+        <pre class="stack">${appFrames.map((f) => esc(f.raw)).join('\n')}</pre>
+      </div>`
+        : ''
+    }
+
+    ${
+      internalFrameCount > 0
+        ? `<details class="section internal-frames">
+        <summary class="section-header clickable">${internalFrameCount} internal frame${internalFrameCount !== 1 ? 's' : ''}</summary>
+        <pre class="stack dimmed">${frames
+          .filter((f) => f.type !== 'app')
+          .map((f) => esc(f.raw))
+          .join('\n')}</pre>
+      </details>`
+        : ''
+    }
+
+    <div class="actions">
+      <button class="btn" onclick="copyError()">Copy Error</button>
+    </div>
+
+    <footer class="footer">
+      <span class="timber-logo">🪵 timber.js</span>
+      <span class="footer-hint">Fix the error and save — the page will reload automatically via HMR.</span>
+    </footer>
+  </div>
+
+  <script>
+    function copyError() {
+      var text = ${escJsonForScript(
+        JSON.stringify(
+          `${phaseLabel} Error: ${message}\n\n` +
+            (relPath ? `File: ${relPath}${loc ? `:${loc.line}:${loc.column}` : ''}\n\n` : '') +
+            (componentStack ? `Component Stack:\n${componentStack.trim()}\n\n` : '') +
+            `Stack Trace:\n${error.stack ?? ''}`
+        )
+      )};
+      navigator.clipboard.writeText(text).then(function() {
+        var btn = document.querySelector('.btn');
+        if (btn) { btn.textContent = 'Copied!'; setTimeout(function() { btn.textContent = 'Copy Error'; }, 1500); }
+      });
+    }
+
+    // Auto-reload when Vite HMR reconnects.
+    // When the developer fixes the error and saves, Vite's module graph
+    // invalidates. We can't rely on the normal HMR update flow (the page
+    // is a static error page, not a Vite-managed module), so we connect
+    // to Vite's WebSocket and reload on any update event.
+    (function() {
+      try {
+        var wsUrl = ${hmrOptions ? escJsonForScript(JSON.stringify(buildWsUrl(hmrOptions))) : "'ws://' + location.host"};
+        var ws = new WebSocket(wsUrl, 'vite-hmr');
+        ws.addEventListener('message', function(e) {
+          try {
+            var data = JSON.parse(e.data);
+            if (data.type === 'full-reload' || data.type === 'update' || data.type === 'connected') {
+              if (data.type !== 'connected') location.reload();
+            }
+          } catch(ex) {}
+        });
+      } catch(ex) {}
+    })();
+  </script>
+</body>
+</html>`;
+}
+
+// ─── CSS ────────────────────────────────────────────────────────────────────
+
+const CSS = `
+  :root {
+    --bg: #fff;
+    --fg: #1a1a1a;
+    --fg-dim: #6b7280;
+    --border: #e5e7eb;
+    --badge-bg: #fef2f2;
+    --badge-fg: #991b1b;
+    --badge-border: #fecaca;
+    --source-bg: #fafafa;
+    --highlight-bg: #fef2f2;
+    --highlight-border: #ef4444;
+    --line-num: #9ca3af;
+    --btn-bg: #f3f4f6;
+    --btn-fg: #374151;
+    --btn-border: #d1d5db;
+    --link: #2563eb;
+    --code-font: ui-monospace, SFMono-Regular, 'SF Mono', Menlo, Consolas, 'Liberation Mono', monospace;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --bg: #0a0a0a;
+      --fg: #f5f5f5;
+      --fg-dim: #9ca3af;
+      --border: #27272a;
+      --badge-bg: #450a0a;
+      --badge-fg: #fca5a5;
+      --badge-border: #7f1d1d;
+      --source-bg: #18181b;
+      --highlight-bg: #450a0a;
+      --highlight-border: #dc2626;
+      --line-num: #6b7280;
+      --btn-bg: #27272a;
+      --btn-fg: #e5e7eb;
+      --btn-border: #3f3f46;
+      --link: #60a5fa;
+    }
+  }
+
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+    background: var(--bg);
+    color: var(--fg);
+    line-height: 1.6;
+    padding: 2rem;
+  }
+
+  .container {
+    max-width: 56rem;
+    margin: 0 auto;
+  }
+
+  .header { margin-bottom: 1.5rem; }
+
+  .badge {
+    display: inline-block;
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.25rem 0.625rem;
+    border-radius: 0.375rem;
+    background: var(--badge-bg);
+    color: var(--badge-fg);
+    border: 1px solid var(--badge-border);
+    margin-bottom: 0.75rem;
+  }
+
+  .message {
+    font-size: 1.375rem;
+    font-weight: 600;
+    line-height: 1.3;
+    word-break: break-word;
+  }
+
+  .hint {
+    margin-top: 0.5rem;
+    color: var(--fg-dim);
+    font-size: 0.875rem;
+  }
+
+  .location {
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    color: var(--link);
+    margin-bottom: 1rem;
+    padding: 0.5rem 0.75rem;
+    background: var(--source-bg);
+    border-radius: 0.375rem;
+    border: 1px solid var(--border);
+  }
+
+  .source-context {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .source-header, .section-header {
+    font-size: 0.75rem;
+    font-weight: 600;
+    text-transform: uppercase;
+    letter-spacing: 0.05em;
+    padding: 0.5rem 0.75rem;
+    background: var(--source-bg);
+    border-bottom: 1px solid var(--border);
+    color: var(--fg-dim);
+  }
+
+  .source-code {
+    overflow-x: auto;
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    padding: 0;
+    margin: 0;
+  }
+
+  .source-code code {
+    display: block;
+  }
+
+  .source-line {
+    display: block;
+    padding: 0 0.75rem;
+    border-left: 3px solid transparent;
+  }
+
+  .source-line-highlight {
+    background: var(--highlight-bg);
+    border-left-color: var(--highlight-border);
+  }
+
+  .line-num {
+    display: inline-block;
+    width: 3rem;
+    text-align: right;
+    margin-right: 1rem;
+    color: var(--line-num);
+    user-select: none;
+  }
+
+  .section {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .clickable { cursor: pointer; }
+  .clickable:hover { background: var(--btn-bg); }
+
+  .component-stack, .stack {
+    font-family: var(--code-font);
+    font-size: 0.8125rem;
+    line-height: 1.7;
+    padding: 0.75rem;
+    overflow-x: auto;
+    white-space: pre;
+    margin: 0;
+  }
+
+  .dimmed { color: var(--fg-dim); }
+
+  .actions {
+    margin: 1.5rem 0;
+  }
+
+  .btn {
+    font-family: inherit;
+    font-size: 0.8125rem;
+    font-weight: 500;
+    padding: 0.5rem 1rem;
+    border-radius: 0.375rem;
+    border: 1px solid var(--btn-border);
+    background: var(--btn-bg);
+    color: var(--btn-fg);
+    cursor: pointer;
+    transition: background 0.15s;
+  }
+
+  .btn:hover { opacity: 0.85; }
+
+  .footer {
+    display: flex;
+    align-items: center;
+    gap: 0.75rem;
+    padding-top: 1rem;
+    border-top: 1px solid var(--border);
+    font-size: 0.75rem;
+    color: var(--fg-dim);
+  }
+
+  .timber-logo {
+    font-weight: 600;
+    white-space: nowrap;
+  }
+`;

package/src/dev-tools/holding-server.ts

@@ -0,0 +1,187 @@
+/**
+ * Dev holding server — serves a loading page while Vite initializes.
+ *
+ * When `timber dev` (or `vite dev`) starts, Vite takes several seconds
+ * to initialize all plugins, scan routes, and boot the RSC environment.
+ * During this window, the port is unbound and browsers get
+ * ERR_CONNECTION_REFUSED.
+ *
+ * This module creates a lightweight HTTP server that binds the port
+ * immediately and serves a branded holding page with auto-refresh.
+ * Once Vite is ready, the holding server is closed and Vite's server
+ * takes over the port.
+ *
+ * The holding server is started in rootSync's config() hook (the
+ * earliest Vite plugin lifecycle point where we know the port) and
+ * closed in timber-dev-server's configureServer() hook (the last
+ * plugin, right before Vite calls server.listen()).
+ *
+ * Browser requests (Accept: text/html) get the HTML holding page.
+ * API requests (Accept: application/json) get a 503 JSON response.
+ * All responses include Retry-After: 1.
+ *
+ * See design/21-dev-server.md, TIM-665.
+ */
+
+import http from 'node:http';
+
+// ─── Types ────────────────────────────────────────────────────────────────
+
+export interface HoldingServer {
+  /**
+   * Start listening on the given port.
+   * Returns the actual bound port (useful when port is 0 for OS assignment).
+   */
+  listen(port: number): Promise<number>;
+
+  /** Gracefully close the server and stop accepting connections. */
+  close(): Promise<void>;
+}
+
+// ─── Holding Page HTML ────────────────────────────────────────────────────
+
+/**
+ * Minimal self-contained HTML holding page.
+ *
+ * Matches the timber.js docs site theme:
+ * - Light mode: warm stone/grain background, timber/bark text
+ * - Dark mode: stone-900 background, stone-200 text
+ * - 🪵 timber.js branding
+ *
+ * Uses meta-refresh (1s) for auto-reload — works without JavaScript.
+ * Inline CSS only, no external dependencies.
+ */
+const HOLDING_PAGE_HTML = [
+  '<!DOCTYPE html>',
+  '<html lang="en">',
+  '<head>',
+  '  <meta charset="utf-8">',
+  '  <meta name="viewport" content="width=device-width, initial-scale=1">',
+  '  <meta http-equiv="refresh" content="2">',
+  '  <title>timber — starting...</title>',
+  '  <style>',
+  '    *, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }',
+  '    body {',
+  '      font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, sans-serif;',
+  '      background: #fafaf9;',
+  '      color: #44403c;',
+  '      display: flex;',
+  '      align-items: center;',
+  '      justify-content: center;',
+  '      min-height: 100vh;',
+  '      -webkit-font-smoothing: antialiased;',
+  '    }',
+  '    @media (prefers-color-scheme: dark) {',
+  '      body { background: #1c1917; color: #e7e5e4; }',
+  '      .message { color: #a8a29e; }',
+  '      .spinner { border-color: #57534e; border-top-color: #a1887f; }',
+  '      .logo { color: #e7e5e4; }',
+  '    }',
+  '    .container { text-align: center; padding: 2rem; }',
+  '    .logo {',
+  '      font-size: 1.5rem;',
+  '      font-weight: 700;',
+  '      letter-spacing: -0.02em;',
+  '      color: #5c3d2e;',
+  '      margin-bottom: 1.5rem;',
+  '    }',
+  '    .message {',
+  '      font-size: 0.95rem;',
+  '      color: #78716c;',
+  '      margin-bottom: 2rem;',
+  '    }',
+  '    .spinner {',
+  '      width: 24px;',
+  '      height: 24px;',
+  '      border: 2.5px solid #d7ccc8;',
+  '      border-top-color: #6d4c41;',
+  '      border-radius: 50%;',
+  '      animation: spin 0.8s linear infinite;',
+  '      margin: 0 auto;',
+  '    }',
+  '    @keyframes spin { to { transform: rotate(360deg); } }',
+  '  </style>',
+  '</head>',
+  '<body>',
+  '  <div class="container">',
+  '    <div class="logo">\u{1FAB5} timber.js</div>',
+  '    <p class="message">Dev server starting&hellip;</p>',
+  '    <div class="spinner"></div>',
+  '  </div>',
+  '</body>',
+  '</html>',
+].join('\n');
+
+// ─── Factory ──────────────────────────────────────────────────────────────
+
+/**
+ * Create a holding HTTP server that serves a loading page during startup.
+ *
+ * Usage (inside Vite plugin):
+ * ```ts
+ * // In config() hook — earliest point where port is known.
+ * // Use bindWithBump() to honor the default-3000 + auto-bump policy
+ * // (see ../server/port-resolution.ts and TIM-842).
+ * const holding = createHoldingServer();
+ * await bindWithBump((p) => holding.listen(p), { startPort: 3000, autoBump: true });
+ *
+ * // In last plugin's configureServer() — wrap listen for seamless handoff
+ * const originalListen = server.listen.bind(server);
+ * server.listen = async (...args) => {
+ *   await holding.close();
+ *   return originalListen(...args);
+ * };
+ * ```
+ */
+export function createHoldingServer(): HoldingServer {
+  const server = http.createServer((req, res) => {
+    const accept = req.headers.accept ?? '';
+
+    // API requests: JSON 503
+    if (accept.includes('application/json') && !accept.includes('text/html')) {
+      res.writeHead(503, {
+        'Content-Type': 'application/json; charset=utf-8',
+        'Retry-After': '1',
+        'Cache-Control': 'no-store',
+      });
+      res.end(
+        JSON.stringify({
+          error: 'Service Unavailable',
+          message: 'timber dev server is starting — please retry shortly',
+        })
+      );
+      return;
+    }
+
+    // Browser and other requests: HTML holding page
+    res.writeHead(503, {
+      'Content-Type': 'text/html; charset=utf-8',
+      'Retry-After': '1',
+      'Cache-Control': 'no-store',
+    });
+    res.end(HOLDING_PAGE_HTML);
+  });
+
+  return {
+    listen(port: number): Promise<number> {
+      return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, () => {
+          server.removeListener('error', reject);
+          const addr = server.address();
+          const boundPort = typeof addr === 'object' && addr ? addr.port : port;
+          resolve(boundPort);
+        });
+      });
+    },
+
+    close(): Promise<void> {
+      return new Promise((resolve, reject) => {
+        server.close((err) => {
+          if (err) reject(err);
+          else resolve();
+        });
+      });
+    },
+  };
+}