@timber-js/app 0.2.0-alpha.21 → 0.2.0-alpha.210

package/src/{plugins/dev-logs.ts → dev-tools/logs.ts}

@@ -12,8 +12,85 @@
  * Design docs: 18-build-system.md §"Dev Server", 02-rendering-pipeline.md
  */
 
-import type { Plugin, ViteDevServer } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { Plugin, ViteDevServer, Logger } from 'vite';
+import type { PluginContext } from '../plugin-context.ts';
+
+// ─── Original Console Snapshot ──────────────────────────────────────────
+
+/**
+ * Snapshot of the original console methods, captured at module load time
+ * (before any patching). Used as Vite's `customLogger` console so that
+ * forwardConsole output bypasses our patch entirely — eliminating the
+ * server→browser→server forwarding loop without string matching.
+ */
+export const originalConsole: Pick<Console, 'log' | 'warn' | 'error' | 'debug' | 'info'> = {
+  log: console.log.bind(console),
+  warn: console.warn.bind(console),
+  error: console.error.bind(console),
+  debug: console.debug.bind(console),
+  info: console.info.bind(console),
+};
+
+/**
+ * Wrap a Vite Logger so its output methods route through `originalConsole`
+ * instead of the global (potentially patched) console. This prevents the
+ * server→browser→server forwarding loop even when the user supplies their
+ * own `customLogger` that internally calls console methods.
+ */
+export function wrapLoggerWithOriginalConsole(logger: Logger): Logger {
+  // Swap all patched console methods to originals during any logger call,
+  // since user loggers may call any combination of console methods internally.
+  function withOriginals<T>(fn: () => T): T {
+    const saved = {
+      log: console.log,
+      warn: console.warn,
+      error: console.error,
+      debug: console.debug,
+      info: console.info,
+    };
+    console.log = originalConsole.log;
+    console.warn = originalConsole.warn;
+    console.error = originalConsole.error;
+    console.debug = originalConsole.debug;
+    console.info = originalConsole.info;
+    try {
+      return fn();
+    } finally {
+      console.log = saved.log;
+      console.warn = saved.warn;
+      console.error = saved.error;
+      console.debug = saved.debug;
+      console.info = saved.info;
+    }
+  }
+
+  return {
+    get hasWarned() {
+      return logger.hasWarned;
+    },
+    set hasWarned(v) {
+      logger.hasWarned = v;
+    },
+    info(msg, opts) {
+      withOriginals(() => logger.info(msg, opts));
+    },
+    warn(msg, opts) {
+      withOriginals(() => logger.warn(msg, opts));
+    },
+    warnOnce(msg, opts) {
+      withOriginals(() => logger.warnOnce(msg, opts));
+    },
+    error(msg, opts) {
+      withOriginals(() => logger.error(msg, opts));
+    },
+    clearScreen(type) {
+      logger.clearScreen(type);
+    },
+    hasErrorLogged(error) {
+      return logger.hasErrorLogged(error);
+    },
+  };
+}
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -149,7 +226,7 @@ function extractCallerLocation(projectRoot: string): string | null {
   for (let i = 1; i < lines.length; i++) {
     const line = lines[i].trim();
     // Skip our own patching frames
-    if (line.includes('dev-logs')) continue;
+    if (line.includes('dev-tools/logs')) continue;
     // Skip node internals
     if (line.includes('node:') || line.includes('node_modules')) continue;
 
@@ -189,7 +266,7 @@ export function isFrameworkInternalCaller(): boolean {
   for (let i = 1; i < lines.length; i++) {
     const line = lines[i].trim();
     // Skip our own patching frames
-    if (line.includes('dev-logs')) continue;
+    if (line.includes('dev-tools/logs')) continue;
     // Skip node internals (but NOT node_modules — we need to inspect those)
     if (line.includes('node:')) continue;
 
@@ -215,39 +292,58 @@ export function isFrameworkInternalCaller(): boolean {
  * 3. Sends via server.hot.send() — dropped if no clients connected
  */
 function patchConsole(server: ViteDevServer, projectRoot: string): () => void {
-  const originals = new Map<ServerLogLevel, (...args: unknown[]) => void>();
+  const prevConsole = new Map<ServerLogLevel, (...args: unknown[]) => void>();
+  // Per-level guard so a console.warn inside a console.error handler isn't
+  // suppressed — only same-level synchronous re-entrancy is blocked.
+  const patchingLevel = new Set<ServerLogLevel>();
 
   for (const level of LOG_LEVELS) {
-    originals.set(level, console[level].bind(console));
+    prevConsole.set(level, console[level].bind(console));
 
     console[level] = (...args: unknown[]) => {
-      // Always call the original — server terminal output is preserved
-      originals.get(level)!(...args);
-
-      // Skip framework-internal logs (plugins/, adapters/) from browser forwarding.
-      // Server runtime logs (render errors, action errors, etc.) are preserved.
-      if (isFrameworkInternalCaller()) return;
+      // Same-level re-entrancy guard: if prevConsole's wrapper calls back
+      // into console[level], just pass through without forwarding.
+      if (patchingLevel.has(level)) {
+        prevConsole.get(level)!(...args);
+        return;
+      }
 
-      // Serialize and forward to browser
+      patchingLevel.add(level);
       try {
-        const payload: ServerLogPayload = {
-          level,
-          args: args.map((arg) => serializeArg(arg)),
-          location: extractCallerLocation(projectRoot),
-          timestamp: Date.now(),
-        };
-
-        server.hot.send('timber:server-log', payload);
-      } catch {
-        // Never let log forwarding break the server
+        // Call the previous console method first — guarantees terminal output
+        // even if serialization or forwarding fails downstream. If prevConsole
+        // throws, the error propagates (not swallowed) but patchingLevel is
+        // still cleaned up by the outer finally.
+        prevConsole.get(level)!(...args);
+
+        // Skip framework-internal logs (plugins/, adapters/) from browser forwarding.
+        if (isFrameworkInternalCaller()) return;
+
+        try {
+          const payload: ServerLogPayload = {
+            level,
+            args: args.map((arg) => serializeArg(arg)),
+            location: extractCallerLocation(projectRoot),
+            timestamp: Date.now(),
+          };
+
+          server.hot.send('timber:server-log', payload);
+        } catch (e) {
+          originalConsole.debug(
+            '[timber] server log forwarding failed:',
+            e instanceof Error ? e.message : e
+          );
+        }
+      } finally {
+        patchingLevel.delete(level);
       }
     };
   }
 
-  // Return a cleanup function to restore originals
+  // Return a cleanup function to restore the previous console methods
   return () => {
-    for (const [level, original] of originals) {
-      console[level] = original;
+    for (const [level, prev] of prevConsole) {
+      console[level] = prev;
     }
   };
 }

package/src/{plugins/dev-error-overlay.ts → dev-tools/overlay.ts}

@@ -1,13 +1,18 @@
 /**
  * Dev error overlay — formats and sends errors to Vite's browser overlay and stderr.
  *
- * Integrates with Vite's built-in error overlay (`server.ssrFixStacktrace` +
- * `server.hot.send`) rather than implementing a custom overlay.
+ * Integrates with Vite's built-in error overlay (`server.hot.send`) rather
+ * than implementing a custom overlay.
  *
- * Design doc: 21-dev-server.md §"Error Overlay"
+ * Stacks are shown as they arrive: Vite's module runner already reports
+ * source positions for the code it runs, and a second mapping pass moves
+ * them (TIM-1555).
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay", §"RSC Source-Mapping"
  */
 
 import type { ViteDevServer } from 'vite';
+import { classifyFrame } from './stack-classifier.ts';
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -21,7 +26,7 @@ export type ErrorPhase =
   | 'handler';
 
 /** Labels for terminal output. */
-const PHASE_LABELS: Record<ErrorPhase, string> = {
+export const PHASE_LABELS: Record<ErrorPhase, string> = {
   'module-transform': 'Module Transform',
   'proxy': 'Proxy',
   'middleware': 'Middleware',
@@ -30,28 +35,14 @@ const PHASE_LABELS: Record<ErrorPhase, string> = {
   'handler': 'Route Handler',
 };
 
-// ─── Frame Classification ───────────────────────────────────────────────────
-
-export type FrameType = 'app' | 'framework' | 'internal';
-
-/**
- * Classify a stack frame line by origin.
- *
- * - 'app': user application code (in project root, not node_modules)
- * - 'framework': timber-app internal code
- * - 'internal': node_modules, Node.js internals
- */
-export function classifyFrame(frameLine: string, projectRoot: string): FrameType {
-  // Strip leading whitespace and "at "
-  const trimmed = frameLine.trim();
-
-  if (trimmed.includes('packages/timber-app/')) return 'framework';
-  if (trimmed.includes('node_modules/')) return 'internal';
-  if (trimmed.startsWith('at node:') || trimmed.includes('(node:')) return 'internal';
-  if (trimmed.includes(projectRoot)) return 'app';
+// ─── Frame Classification (re-exported from stack-classifier) ───────────────
 
-  return 'internal';
-}
+export {
+  classifyFrame,
+  classifyStack,
+  type FrameType,
+  type ClassifiedFrame,
+} from './stack-classifier.ts';
 
 // ─── Component Stack Extraction ─────────────────────────────────────────────
 
@@ -131,62 +122,19 @@ export function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhas
 
 // ─── Terminal Formatting ────────────────────────────────────────────────────
 
-// ANSI codes
-const RED = '\x1b[31m';
-const DIM = '\x1b[2m';
-const RESET = '\x1b[0m';
-const BOLD = '\x1b[1m';
-
-/**
- * Format an error for terminal output.
- *
- * - Red for the error message and phase label
- * - Dim for framework-internal frames
- * - Normal for application frames
- * - Separate section for component stack (if present)
- */
-export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string {
-  const lines: string[] = [];
-
-  // Phase header + error message
-  lines.push(`${RED}${BOLD}[timber] ${PHASE_LABELS[phase]} Error${RESET}`);
-  lines.push(`${RED}${error.message}${RESET}`);
-  lines.push('');
-
-  // Component stack (if present)
-  const componentStack = extractComponentStack(error);
-  if (componentStack) {
-    lines.push(`${BOLD}Component Stack:${RESET}`);
-    for (const csLine of componentStack.trim().split('\n')) {
-      lines.push(`  ${csLine.trim()}`);
-    }
-    lines.push('');
-  }
-
-  // Stack trace with frame dimming
-  if (error.stack) {
-    lines.push(`${BOLD}Stack Trace:${RESET}`);
-    const stackLines = error.stack.split('\n').slice(1); // Skip the first line (message)
-    for (const stackLine of stackLines) {
-      const frameType = classifyFrame(stackLine, projectRoot);
-      if (frameType === 'app') {
-        lines.push(stackLine);
-      } else {
-        lines.push(`${DIM}${stackLine}${RESET}`);
-      }
-    }
-  }
-
-  return lines.join('\n');
-}
+// formatTerminalError is implemented in the dedicated terminal formatter module
+// (terminal.ts) to keep this file under 500 lines.
+// Import for use in sendErrorToOverlay, and re-export for external consumers.
+import { formatTerminalError as _formatTerminalError } from './terminal.ts';
+export const formatTerminalError = _formatTerminalError;
 
 // ─── Overlay Integration ────────────────────────────────────────────────────
 
 /**
  * Send an error to Vite's browser overlay and log it to stderr.
  *
- * Uses `server.ssrFixStacktrace()` to map stack traces back to source,
- * then sends the error via `server.hot.send()` for the browser overlay.
+ * Reads `error` and never writes it: the pipeline may render the same object
+ * on the fallback error page after reporting it here.
  *
  * The dev server remains running — errors are handled, not fatal.
  */
@@ -196,9 +144,6 @@ export function sendErrorToOverlay(
   phase: ErrorPhase,
   projectRoot: string
 ): void {
-  // Fix stack trace to use source-mapped positions
-  server.ssrFixStacktrace(error);
-
   // Log to stderr with frame dimming
   const formatted = formatTerminalError(error, phase, projectRoot);
   process.stderr.write(`${formatted}\n`);
@@ -224,7 +169,7 @@ export function sendErrorToOverlay(
         loc: loc ? { file: loc.file, line: loc.line, column: loc.column } : undefined,
       },
     });
-  } catch {
-    // Overlay send must never crash the dev server
+  } catch (e) {
+    console.debug('[timber] overlay error send failed:', e instanceof Error ? e.message : e);
   }
 }

package/src/dev-tools/stack-classifier.ts

@@ -0,0 +1,75 @@
+/**
+ * Stack trace frame classifier — categorizes stack frames by origin.
+ *
+ * Provides `classifyFrame` (single frame) and `classifyStack` (full stack
+ * string) as the shared primitives used by the error page, terminal
+ * formatter, and overlay.
+ *
+ * Dev-only: this module is only imported by other dev-tools modules.
+ */
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export type FrameType = 'app' | 'framework' | 'internal';
+
+export interface ClassifiedFrame {
+  raw: string;
+  type: FrameType;
+  file?: string;
+  line?: number;
+  col?: number;
+}
+
+// ─── Frame Parsing ──────────────────────────────────────────────────────────
+
+/** Parse file/line/col from a stack frame line. */
+function parseFrame(frameLine: string): { file?: string; line?: number; col?: number } {
+  const parenMatch = /\(([^)]+):(\d+):(\d+)\)/.exec(frameLine);
+  if (parenMatch) {
+    return { file: parenMatch[1], line: Number(parenMatch[2]), col: Number(parenMatch[3]) };
+  }
+  const bareMatch = /at (\/[^:]+):(\d+):(\d+)/.exec(frameLine);
+  if (bareMatch) {
+    return { file: bareMatch[1], line: Number(bareMatch[2]), col: Number(bareMatch[3]) };
+  }
+  return {};
+}
+
+// ─── Classification ─────────────────────────────────────────────────────────
+
+/**
+ * Classify a single stack frame line by origin.
+ *
+ * - 'app': user application code (in project root, not node_modules)
+ * - 'framework': timber-app internal code
+ * - 'internal': node_modules, Node.js internals
+ */
+export function classifyFrame(frameLine: string, projectRoot: string): FrameType {
+  const trimmed = frameLine.trim();
+
+  if (trimmed.includes('packages/timber-app/')) return 'framework';
+  if (trimmed.includes('node_modules/')) return 'internal';
+  if (trimmed.startsWith('at node:') || trimmed.includes('(node:')) return 'internal';
+  if (trimmed.includes(projectRoot)) return 'app';
+
+  return 'internal';
+}
+
+/**
+ * Classify all frames in a full stack trace string.
+ *
+ * Parses the stack, skips the first line (error message), filters to
+ * lines starting with "at ", and returns classified frames with optional
+ * file/line/col metadata.
+ */
+export function classifyStack(stack: string, projectRoot: string): ClassifiedFrame[] {
+  return stack
+    .split('\n')
+    .slice(1) // skip first line (error message)
+    .filter((line) => line.trim().startsWith('at '))
+    .map((raw) => {
+      const type = classifyFrame(raw, projectRoot);
+      const { file, line, col } = parseFrame(raw);
+      return { raw, type, file, line, col };
+    });
+}

package/src/dev-tools/terminal.ts

@@ -0,0 +1,182 @@
+/**
+ * Terminal error formatting — boxed, color-coded error output for dev mode.
+ *
+ * Produces a visually scannable error block with:
+ * - Unicode box-drawing border around the error
+ * - Phase badge and error message
+ * - First app frame highlighted as the primary action item
+ * - OSC 8 clickable file:line links (VSCode terminal, iTerm2, etc.)
+ * - Internal/framework frames collapsed with a count
+ * - Component stack (for React render errors)
+ *
+ * Dev-only: this module is only imported by dev-error-overlay.ts.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import { pathToFileURL } from 'node:url';
+import type { InspectColor } from 'node:util';
+import { styleText } from 'node:util';
+import {
+  extractComponentStack,
+  parseFirstAppFrame,
+  PHASE_LABELS,
+  type ErrorPhase,
+} from './overlay.ts';
+import { classifyStack } from './stack-classifier.ts';
+
+// ─── Styling ────────────────────────────────────────────────────────────────
+
+type Format = InspectColor | readonly InspectColor[];
+const noValidate = { validateStream: false } as const;
+const style = (fmt: Format, text: string) => styleText(fmt, text, noValidate);
+
+// ─── OSC 8 Hyperlinks ──────────────────────────────────────────────────────
+
+/**
+ * Wrap text in an OSC 8 hyperlink escape sequence.
+ *
+ * Terminals that support OSC 8 (VSCode, iTerm2, Windows Terminal, etc.)
+ * render this as a clickable link. Others ignore the escape sequences
+ * and show the text normally.
+ *
+ * Format: \x1b]8;;URL\x07TEXT\x1b]8;;\x07
+ */
+function hyperlink(text: string, url: string): string {
+  return `\x1b]8;;${url}\x07${text}\x1b]8;;\x07`;
+}
+
+/**
+ * Format a file:line:col reference as a clickable terminal link.
+ *
+ * Uses file:// URLs so terminals open the file in the configured editor.
+ * The link text is styled with cyan + underline for visibility.
+ */
+function fileLink(filePath: string, line?: number, col?: number): string {
+  const display = line ? `${filePath}:${line}${col ? `:${col}` : ''}` : filePath;
+  // Use pathToFileURL for proper encoding of spaces, #, ?, and Windows
+  // drive letters (TIM-792). Append :line:col after the URL.
+  const base = pathToFileURL(filePath).href;
+  const url = line ? `${base}:${line}${col ? `:${col}` : ''}` : base;
+  return style(['cyan', 'underline'], hyperlink(display, url));
+}
+
+// ─── Box Drawing ────────────────────────────────────────────────────────────
+
+const BOX = {
+  topLeft: '╭',
+  topRight: '╮',
+  bottomLeft: '╰',
+  bottomRight: '╯',
+  horizontal: '─',
+  vertical: '│',
+};
+
+/**
+ * Wrap lines of text in a Unicode box with a colored left border.
+ *
+ * @param lines - Content lines (no ANSI length calculation — keeps it simple)
+ * @param width - Box width (characters). Lines longer than this are not truncated.
+ */
+function box(lines: string[], borderFormat: Format, width = 80): string {
+  const bar = BOX.horizontal.repeat(width - 2);
+  const output: string[] = [];
+
+  output.push(style(borderFormat, `${BOX.topLeft}${bar}${BOX.topRight}`));
+  for (const line of lines) {
+    output.push(`${style(borderFormat, BOX.vertical)} ${line}`);
+  }
+  output.push(style(borderFormat, `${BOX.bottomLeft}${bar}${BOX.bottomRight}`));
+
+  return output.join('\n');
+}
+
+// Frame classification and parsing provided by stack-classifier.ts
+
+// ─── Public API ─────────────────────────────────────────────────────────────
+
+/**
+ * Format an error for terminal output with a boxed layout.
+ *
+ * The output is designed to be scannable at a glance:
+ * 1. Red box with phase badge and error message
+ * 2. First app frame as a clickable link (the primary action item)
+ * 3. App frames listed normally
+ * 4. Internal/framework frames collapsed with count
+ * 5. Component stack (if present)
+ */
+export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string {
+  const sections: string[] = [];
+  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 internalCount = frames.filter((f) => f.type !== 'app').length;
+
+  // ── Box: Phase + Message ──────────────────────────────────────────
+  const boxLines: string[] = [];
+  boxLines.push(style(['red', 'bold'], `${PHASE_LABELS[phase]} Error`));
+  boxLines.push('');
+
+  // Error message — may be multi-line
+  for (const msgLine of error.message.split('\n')) {
+    boxLines.push(style('red', msgLine));
+  }
+
+  // Primary file location (clickable)
+  if (loc) {
+    boxLines.push('');
+    const relPath = loc.file.startsWith(projectRoot)
+      ? loc.file.slice(projectRoot.length + 1)
+      : loc.file;
+    boxLines.push(
+      `${style('bold', '→')} ${fileLink(loc.file, loc.line, loc.column)} ${style('dim', `(${relPath})`)}`
+    );
+  }
+
+  sections.push(box(boxLines, 'red'));
+
+  // ── Component Stack ───────────────────────────────────────────────
+  if (componentStack) {
+    sections.push('');
+    sections.push(`  ${style('bold', 'Component Stack:')}`);
+    for (const csLine of componentStack.trim().split('\n')) {
+      sections.push(`  ${style('dim', csLine.trim())}`);
+    }
+  }
+
+  // ── App Frames ────────────────────────────────────────────────────
+  if (appFrames.length > 0) {
+    sections.push('');
+    sections.push(`  ${style('bold', 'Application Frames:')}`);
+    for (let i = 0; i < appFrames.length; i++) {
+      const f = appFrames[i]!;
+      if (f.file && f.line) {
+        const prefix = i === 0 ? style('bold', '▸') : ' ';
+        sections.push(
+          `  ${prefix} ${fileLink(f.file, f.line, f.col)} ${style('dim', extractFnName(f.raw))}`
+        );
+      } else {
+        sections.push(`  ${f.raw}`);
+      }
+    }
+  }
+
+  // ── Internal Frames (collapsed) ───────────────────────────────────
+  if (internalCount > 0) {
+    sections.push(
+      `  ${style('dim', `… ${internalCount} internal frame${internalCount !== 1 ? 's' : ''} hidden`)}`
+    );
+  }
+
+  sections.push('');
+  return sections.join('\n');
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+/** Extract the function name from a stack frame line like "    at fnName (/path:1:2)". */
+function extractFnName(frameLine: string): string {
+  const match = /at\s+(\S+)\s+\(/.exec(frameLine.trim());
+  return match ? match[1]! : '';
+}