@timber-js/app 0.2.0-alpha.20 → 0.2.0-alpha.201

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

@@ -0,0 +1,260 @@
+/**
+ * Shared scaffold for dev-mode HTML pages (dev error page, dev 404 page).
+ *
+ * Both pages are self-contained HTML documents served when the normal
+ * render pipeline can't produce a page. They share:
+ * - The document scaffold (head, container, footer)
+ * - Base CSS (layout, light/dark variables, common components)
+ * - The HMR auto-reload script that watches Vite's WebSocket and reloads
+ *   when the developer fixes the error / adds the missing route
+ *
+ * Dev-only: this module is only imported by dev-mode code paths. It is
+ * never included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay", §"Dev 404 Page"
+ */
+
+import { escapeHtml } from '../server/utils/escape-html.ts';
+
+// ─── HMR Options ────────────────────────────────────────────────────────────
+
+/**
+ * HMR connection options for the dev page auto-reload WebSocket.
+ * Derived from Vite's resolved server config so the page can connect
+ * to the correct HMR endpoint (TIM-789).
+ */
+export interface DevErrorHmrOptions {
+  protocol?: string;
+  host?: string;
+  port?: number;
+  path?: string;
+  token?: string;
+}
+
+/**
+ * Extract HMR connection options from a Vite resolved config.
+ * Used by the dev server to pass HMR config to the dev page generators
+ * so the auto-reload WebSocket connects to the correct endpoint.
+ */
+export function extractHmrOptions(config: {
+  server?: {
+    hmr?:
+      | { protocol?: string; host?: string; port?: number; clientPort?: 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.clientPort || hmrOpts.port,
+    path: hmrOpts.path,
+    token: config.webSocketToken,
+  };
+  // If no HMR fields were explicitly configured, return undefined so the
+  // reload script derives everything from the browser's location, which
+  // correctly includes the current port (TIM-805).
+  if (!opts.protocol && !opts.host && !opts.port && !opts.path && !opts.token) {
+    return undefined;
+  }
+  return opts;
+}
+
+// ─── Auto-Reload Script ─────────────────────────────────────────────────────
+
+/**
+ * Build the inline auto-reload script for dev pages.
+ *
+ * The page is static HTML, not a Vite-managed module, so the normal HMR
+ * update flow can't reach it. Instead we connect to Vite's HMR WebSocket
+ * directly and reload on any update event.
+ *
+ * URL construction mirrors Vite's own client.mjs: explicitly configured
+ * values win, and the browser's location fills any gaps at runtime. This
+ * matters because Vite 8 requires a `?token=` on browser WS upgrades in
+ * every config — a config with only a token still needs the host and port
+ * from `location` (TIM-1067).
+ */
+export function buildReloadScript(hmrOptions?: DevErrorHmrOptions): string {
+  // `<` is escaped as a unicode escape so config text can never close the
+  // <script> block (same defense as escJsonForScript in error-page.ts, TIM-788).
+  const opts = JSON.stringify(hmrOptions ?? {}).replace(/</g, '\\u003c');
+  return `    (function() {
+      try {
+        var o = ${opts};
+        var protocol = o.protocol || (location.protocol === 'https:' ? 'wss' : 'ws');
+        var host = o.host || location.hostname;
+        var port = o.port || location.port;
+        var url = protocol + '://' + host + (port ? ':' + port : '') + (o.path || '')
+          + (o.token ? '?token=' + encodeURIComponent(o.token) : '');
+        var ws = new WebSocket(url, 'vite-hmr');
+        ws.addEventListener('message', function(e) {
+          try {
+            var data = JSON.parse(e.data);
+            if (data.type === 'full-reload' || data.type === 'update') {
+              location.reload();
+            }
+          } catch (ex) {}
+        });
+      } catch (ex) {}
+    })();`;
+}
+
+// ─── Page Shell ─────────────────────────────────────────────────────────────
+
+export interface DevPageShellOptions {
+  /** Page title — escaped by the shell. */
+  title: string;
+  /** Page-specific CSS appended after the shared base (badge colors, etc.). */
+  extraCss?: string;
+  /** Inner HTML of the container — must already be escaped by the caller. */
+  bodyHtml: string;
+  /** Hint text shown next to the timber logo in the footer. */
+  footerHint: string;
+  /** Additional inline script placed before the auto-reload script. */
+  extraScript?: string;
+  /** HMR connection options for the auto-reload WebSocket. */
+  hmrOptions?: DevErrorHmrOptions;
+}
+
+/**
+ * Render a self-contained dev page: scaffold + shared CSS + footer +
+ * HMR auto-reload script.
+ */
+export function renderDevPageShell(opts: DevPageShellOptions): string {
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="utf-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <title>${escapeHtml(opts.title)}</title>
+  <style>${SHARED_CSS}${opts.extraCss ?? ''}</style>
+</head>
+<body>
+  <div class="container">
+    ${opts.bodyHtml}
+
+    <footer class="footer">
+      <span class="timber-logo">🪵 timber.js</span>
+      <span class="footer-hint">${opts.footerHint}</span>
+    </footer>
+  </div>
+
+  <script>
+${opts.extraScript ?? ''}
+    // Auto-reload when Vite HMR signals an update (file fixed, route added).
+${buildReloadScript(opts.hmrOptions)}
+  </script>
+</body>
+</html>`;
+}
+
+// ─── Shared CSS ─────────────────────────────────────────────────────────────
+
+/**
+ * Base CSS shared by all dev pages. Pages override the --badge-* variables
+ * (and add their own component styles) via `extraCss`.
+ */
+const SHARED_CSS = `
+  :root {
+    --bg: #fff;
+    --fg: #1a1a1a;
+    --fg-dim: #6b7280;
+    --border: #e5e7eb;
+    --source-bg: #fafafa;
+    --link: #2563eb;
+    --code-bg: #f3f4f6;
+    --btn-bg: #f3f4f6;
+    --btn-fg: #374151;
+    --btn-border: #d1d5db;
+    --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;
+      --source-bg: #18181b;
+      --link: #60a5fa;
+      --code-bg: #27272a;
+      --btn-bg: #27272a;
+      --btn-fg: #e5e7eb;
+      --btn-border: #3f3f46;
+    }
+  }
+
+  * { 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;
+  }
+
+  .section {
+    margin-bottom: 1rem;
+    border: 1px solid var(--border);
+    border-radius: 0.5rem;
+    overflow: hidden;
+  }
+
+  .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);
+  }
+
+  .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/error-page.ts

@@ -0,0 +1,331 @@
+/**
+ * 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')
+ * and via dynamic import from fallback-error.ts in dev mode. It is never
+ * included in production builds.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import { readFileSync } from 'node:fs';
+import { extractComponentStack, parseFirstAppFrame, type ErrorPhase } from './overlay.ts';
+import { classifyStack } from './stack-classifier.ts';
+import { escapeHtml } from '../server/utils/escape-html.ts';
+import { renderDevPageShell, type DevErrorHmrOptions } from './dev-page-shell.ts';
+
+// ─── 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).
+ *
+ * Uses a top-level `node:fs` import — this module is dev-server-only and
+ * Node-only. A bare `require()` here would throw in the ESM build and the
+ * code frame would silently never render (TIM-1067, B48).
+ */
+function readSourceContext(
+  filePath: string,
+  line: number,
+  contextLines = 3
+): { lines: Array<{ num: number; text: string; highlight: boolean }>; startLine: number } | null {
+  try {
+    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 the equivalent unicode escape, 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');
+}
+
+// ─── 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;
+
+  const bodyHtml = `<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="section-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>`;
+
+  const copyScript = `    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); }
+      });
+    }
+`;
+
+  return renderDevPageShell({
+    title: `Error — ${phaseLabel} | timber.js`,
+    extraCss: ERROR_CSS,
+    bodyHtml,
+    footerHint: 'Fix the error and save — the page will reload automatically via HMR.',
+    extraScript: copyScript,
+    hmrOptions,
+  });
+}
+
+// ─── Page-Specific CSS ──────────────────────────────────────────────────────
+
+const ERROR_CSS = `
+  :root {
+    --badge-bg: #fef2f2;
+    --badge-fg: #991b1b;
+    --badge-border: #fecaca;
+    --highlight-bg: #fef2f2;
+    --highlight-border: #ef4444;
+    --line-num: #9ca3af;
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      --badge-bg: #450a0a;
+      --badge-fg: #fca5a5;
+      --badge-border: #7f1d1d;
+      --highlight-bg: #450a0a;
+      --highlight-border: #dc2626;
+      --line-num: #6b7280;
+    }
+  }
+
+  .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-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;
+  }
+
+  .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; }
+`;