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

package/src/dev-tools/index.ts

@@ -0,0 +1,79 @@
+/**
+ * Dev tools barrel — re-exports all dev-only modules.
+ *
+ * Organized by concern, not by Vite plugin vs server module:
+ * - stack-classifier: frame classification for error display
+ * - overlay: Vite browser error overlay integration
+ * - error-page: self-contained HTML 500 page
+ * - 404-page: self-contained HTML 404 page
+ * - terminal: boxed terminal error output
+ * - logger: structured request tree logger
+ * - browser-logs: forward browser console to server
+ * - logs: forward server console to browser
+ * - holding-server: startup holding server
+ * - instrumentation: fetch tracing + OTEL span processor
+ *
+ * Dev-only: all modules in this subtree are only active during `vite dev`.
+ * They are never included in production builds.
+ */
+
+// Stack trace classification
+export {
+  classifyFrame,
+  classifyStack,
+  type FrameType,
+  type ClassifiedFrame,
+} from './stack-classifier.ts';
+
+// Error overlay (Vite integration)
+export {
+  sendErrorToOverlay,
+  classifyErrorPhase,
+  extractComponentStack,
+  parseFirstAppFrame,
+  formatTerminalError,
+  PHASE_LABELS,
+  type ErrorPhase,
+} from './overlay.ts';
+
+// HTML error pages
+export { generateDevErrorPage } from './error-page.ts';
+export {
+  extractHmrOptions,
+  renderDevPageShell,
+  buildReloadScript,
+  type DevErrorHmrOptions,
+} from './dev-page-shell.ts';
+export { generateDev404Page, collectRoutes, findSimilarRoutes } from './404-page.ts';
+
+// Terminal error formatting
+export { formatTerminalError as formatTerminalErrorDirect } from './terminal.ts';
+
+// Request tree logger
+export {
+  formatSpanTree,
+  formatSpanSummary,
+  formatJson,
+  resolveLogMode,
+  type DevLogMode,
+  type DevLoggerConfig,
+} from './logger.ts';
+
+// Browser log forwarding (Vite 8 config mapping)
+export {
+  resolveForwardConsole,
+  type BrowserLogLevel,
+  type DevBrowserLogsConfig,
+} from './browser-logs.ts';
+
+// Server log forwarding
+export { timberDevLogs } from './logs.ts';
+
+// Holding server
+export { createHoldingServer, type HoldingServer } from './holding-server.ts';
+
+// OTEL instrumentation
+export { instrumentDevFetch, DevSpanProcessor, type DevFetchCleanup } from './instrumentation.ts';
+
+// Hydration mismatch overlay (client-side, dev-only)
+export { isHydrationError, showHydrationError } from './hydration-overlay.ts';

package/src/dev-tools/instrumentation.ts

@@ -0,0 +1,261 @@
+/**
+ * Dev-mode OTEL instrumentation — fetch tracing and span processing.
+ *
+ * Combines two concerns:
+ * 1. Fetch instrumentation: patches globalThis.fetch to create OTEL spans
+ *    for every fetch call, giving visibility into async data fetching in
+ *    the dev request log tree.
+ * 2. Span processing: collects completed spans per-request and drives
+ *    dev log output when the root span ends.
+ *
+ * Activated in dev, and in production only when TIMBER_DEBUG is set
+ * (design/13-security.md §"Debug Flag Security Boundary"); otherwise never
+ * loaded.
+ *
+ * Design ref: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
+ */
+
+import * as api from '@opentelemetry/api';
+import { AsyncLocalStorageContextManager } from '@opentelemetry/context-async-hooks';
+import {
+  BasicTracerProvider,
+  type SpanProcessor,
+  type ReadableSpan,
+} from '@opentelemetry/sdk-trace-base';
+import type { Span, Context } from '@opentelemetry/api';
+import {
+  formatSpanTree,
+  formatSpanSummary,
+  formatJson,
+  type DevLogMode,
+  type DevLoggerConfig,
+} from './logger.ts';
+
+// ─── Fetch Instrumentation ──────────────────────────────────────────────────
+
+export type DevFetchCleanup = () => void;
+
+/**
+ * Well-known key holding the active fetch patch's cleanup function.
+ *
+ * The RSC entry module re-evaluates on every HMR invalidation and calls
+ * instrumentDevFetch() again. Without this guard each call would wrap the
+ * previous wrapper — N nested wrappers emitting N duplicate timber.fetch
+ * spans per request. Symbol.for() survives module re-evaluation (same
+ * pattern as globalThis Symbol guards). See TIM-1067, B49.
+ */
+const FETCH_PATCH_KEY = Symbol.for('timber.dev.fetch-instrumentation-cleanup');
+
+/**
+ * Patch globalThis.fetch to wrap every call in an OTEL span.
+ *
+ * Returns a cleanup function that restores the original fetch.
+ * Idempotent: a repeated call restores the previous patch before
+ * re-patching, so wrappers never stack. Only call this in dev mode.
+ */
+export function instrumentDevFetch(): DevFetchCleanup {
+  const globals = globalThis as Record<symbol, unknown>;
+  const priorCleanup = globals[FETCH_PATCH_KEY] as DevFetchCleanup | undefined;
+  priorCleanup?.();
+
+  const originalFetch = globalThis.fetch;
+  const tracer = api.trace.getTracer('timber.js');
+
+  globalThis.fetch = async (input: RequestInfo | URL, init?: RequestInit): Promise<Response> => {
+    const { method, url } = extractFetchInfo(input, init);
+
+    return tracer.startActiveSpan(
+      'timber.fetch',
+      {
+        attributes: {
+          'http.request.method': method,
+          'http.url': url,
+        },
+      },
+      async (span) => {
+        try {
+          const response = await originalFetch(input, init);
+
+          span.setAttribute('http.response.status_code', response.status);
+
+          // Surface cache status from standard headers
+          const cacheStatus =
+            response.headers.get('X-Cache') ?? response.headers.get('CF-Cache-Status');
+          if (cacheStatus) {
+            span.setAttribute('timber.cache_status', cacheStatus);
+          }
+
+          span.setStatus({ code: api.SpanStatusCode.OK });
+          span.end();
+          return response;
+        } catch (error) {
+          span.setStatus({ code: api.SpanStatusCode.ERROR });
+          if (error instanceof Error) {
+            span.setAttribute('timber.fetch_error', error.message);
+            span.recordException(error);
+          }
+          span.end();
+          throw error;
+        }
+      }
+    );
+  };
+
+  const cleanup: DevFetchCleanup = () => {
+    globalThis.fetch = originalFetch;
+    if (globals[FETCH_PATCH_KEY] === cleanup) {
+      delete globals[FETCH_PATCH_KEY];
+    }
+  };
+  globals[FETCH_PATCH_KEY] = cleanup;
+  return cleanup;
+}
+
+/**
+ * Extract method and URL from the various fetch() call signatures.
+ */
+function extractFetchInfo(
+  input: RequestInfo | URL,
+  init?: RequestInit
+): { method: string; url: string } {
+  let method = init?.method ?? 'GET';
+  let url: string;
+
+  if (input instanceof Request) {
+    url = input.url;
+    if (!init?.method) {
+      method = input.method;
+    }
+  } else if (input instanceof URL) {
+    url = input.toString();
+  } else {
+    url = input;
+  }
+
+  return { method: method.toUpperCase(), url };
+}
+
+// ─── Span Processor ─────────────────────────────────────────────────────────
+
+/**
+ * DevSpanProcessor — Custom OTEL SpanProcessor that drives dev log output.
+ *
+ * Collects completed spans per-request (correlated by trace ID). When the
+ * root span (http.server.request) ends, all child spans are already collected
+ * (child spans end before parent in OTEL). The processor formats the span
+ * tree and writes it to stderr.
+ *
+ * This replaces the old DevLogEmitter/DevLogEvents system. OTEL spans are
+ * now the single source of truth for dev logging — no more parallel event
+ * systems that can drift.
+ */
+export class DevSpanProcessor implements SpanProcessor {
+  /**
+   * Max traces retained while waiting for their root span. Traces are only
+   * deleted when an `http.server.request` root ends — orphan fetches (no
+   * active request) and spans ending after their root would otherwise
+   * accumulate for the dev-server lifetime. Beyond the cap, the
+   * oldest-inserted trace is evicted (Map preserves insertion order).
+   * See TIM-1067, B49.
+   */
+  private static readonly MAX_PENDING_TRACES = 512;
+
+  private spansByTrace = new Map<string, ReadableSpan[]>();
+  private mode: DevLogMode;
+  private config: DevLoggerConfig;
+
+  constructor(config: DevLoggerConfig) {
+    this.config = config;
+    this.mode = config.mode ?? 'tree';
+  }
+
+  onStart(_span: Span, _context: Context): void {
+    // No action needed on span start — we collect on end.
+  }
+
+  onEnd(span: ReadableSpan): void {
+    const traceId = span.spanContext().traceId;
+
+    let spans = this.spansByTrace.get(traceId);
+    if (!spans) {
+      if (this.spansByTrace.size >= DevSpanProcessor.MAX_PENDING_TRACES) {
+        const oldest = this.spansByTrace.keys().next().value;
+        if (oldest !== undefined) {
+          this.spansByTrace.delete(oldest);
+        }
+      }
+      spans = [];
+      this.spansByTrace.set(traceId, spans);
+    }
+    spans.push(span);
+
+    // Root span signals request completion — all child spans are already
+    // collected because OTEL ends child spans before parent spans.
+    if (span.name === 'http.server.request') {
+      const output = this.format(spans);
+      if (output) {
+        process.stderr.write(output);
+      }
+      this.spansByTrace.delete(traceId);
+    }
+  }
+
+  private format(spans: ReadableSpan[]): string {
+    if (this.mode === 'quiet') return '';
+    if (this.mode === 'json') return formatJson(spans);
+    if (this.mode === 'summary') return formatSpanSummary(spans, this.config);
+    // Both 'tree' and 'verbose' use the tree formatter.
+    // verbose will show additional detail (every component render) once
+    // component-level spans are wired.
+    return formatSpanTree(spans, this.config);
+  }
+
+  async shutdown(): Promise<void> {
+    this.spansByTrace.clear();
+  }
+
+  async forceFlush(): Promise<void> {
+    // Nothing to flush — output happens synchronously in onEnd.
+  }
+}
+
+// ─── SDK Registration ───────────────────────────────────────────────────────
+
+/**
+ * Register a context manager and a tracer provider feeding DevSpanProcessor
+ * as the OTEL globals. Called once by initDevTracing().
+ *
+ * The SDK packages are imported statically here, and this module is the one
+ * initDevTracing() loads dynamically. A dynamic import of the CJS-only
+ * @opentelemetry/context-async-hooks bundles into a chunk whose namespace
+ * holds the exports on `default`, and loaders that rewrite such namespaces
+ * (tsx exposes the named exports and drops `default`) hand back no
+ * constructor at all (TIM-1554). A static import calls the bundled CJS
+ * factory directly and has no namespace to rewrite.
+ */
+export function registerDevTracing(config: DevLoggerConfig): void {
+  // Construct everything before registering anything: a constructor that
+  // throws must leave no half-registered global state behind.
+
+  // A minimal TracerProvider with our DevSpanProcessor. If the user also
+  // configures an SDK in register(), their provider will coexist — the
+  // global provider set last wins for new tracers, but our processor
+  // captures all spans from the timber.js tracer.
+  const provider = new BasicTracerProvider({
+    spanProcessors: [new DevSpanProcessor(config)],
+  });
+
+  // A context manager so OTEL can propagate the active span across async
+  // boundaries. Without this, startActiveSpan can't make spans "active" —
+  // child spans get random trace IDs and getActiveSpan() returns undefined.
+  const contextManager = new AsyncLocalStorageContextManager();
+
+  contextManager.enable();
+  api.context.setGlobalContextManager(contextManager);
+  api.trace.setGlobalTracerProvider(provider);
+
+  // Fetch spans nest under the active component span in the dev log tree.
+  // Patched here, not by the caller, so one guarded import of this module
+  // covers all of tracing setup (TIM-1554).
+  instrumentDevFetch();
+}

package/src/{server/dev-logger.ts → dev-tools/logger.ts}

@@ -14,6 +14,9 @@
  * Design doc: 21-dev-server.md §"Dev Logging", 17-logging.md §"Dev Logging"
  */
 
+import { STATUS_CODES } from 'node:http';
+import type { InspectColor } from 'node:util';
+import { styleText } from 'node:util';
 import type { ReadableSpan } from '@opentelemetry/sdk-trace-base';
 
 // ─── Configuration ──────────────────────────────────────────────────────────
@@ -27,16 +30,11 @@ export interface DevLoggerConfig {
   slowPhaseMs?: number;
 }
 
-// ─── ANSI Codes ─────────────────────────────────────────────────────────────
+// ─── Styling ────────────────────────────────────────────────────────────────
 
-const DIM = '\x1b[2m';
-const BOLD = '\x1b[1m';
-const RESET = '\x1b[0m';
-const GREEN = '\x1b[32m';
-const YELLOW = '\x1b[33m';
-const RED = '\x1b[31m';
-const CYAN = '\x1b[36m';
-const MAGENTA = '\x1b[35m';
+type Format = InspectColor | readonly InspectColor[];
+const noValidate = { validateStream: false } as const;
+const style = (fmt: Format, text: string) => styleText(fmt, text, noValidate);
 
 /**
  * Color an HTTP method for dev log output.
@@ -45,21 +43,21 @@ const MAGENTA = '\x1b[35m';
 function colorMethod(method: string): string {
   switch (method) {
     case 'GET':
-      return `${DIM}${method}${RESET}`;
+      return style('dim', method);
     case 'POST':
-      return `${GREEN}${BOLD}${method}${RESET}`;
+      return style(['green', 'bold'], method);
     case 'PUT':
-      return `${YELLOW}${BOLD}${method}${RESET}`;
+      return style(['yellow', 'bold'], method);
     case 'DELETE':
-      return `${RED}${BOLD}${method}${RESET}`;
+      return style(['red', 'bold'], method);
     case 'PATCH':
-      return `${CYAN}${BOLD}${method}${RESET}`;
+      return style(['cyan', 'bold'], method);
     case 'HEAD':
-      return `${DIM}${method}${RESET}`;
+      return style('dim', method);
     case 'OPTIONS':
-      return `${MAGENTA}${BOLD}${method}${RESET}`;
+      return style(['magenta', 'bold'], method);
     default:
-      return `${BOLD}${method}${RESET}`;
+      return style('bold', method);
   }
 }
 
@@ -251,14 +249,14 @@ export function formatSpanTree(spans: ReadableSpan[], config?: DevLoggerConfig):
   const traceId = root.spanContext().traceId;
   const actionName = root.attributes['timber.action_name'] as string | undefined;
 
-  const dimTrace = `${DIM}trace_id: ${traceId}${RESET}`;
+  const dimTrace = style('dim', `trace_id: ${traceId}`);
   if (actionName) {
     const actionFile = root.attributes['timber.action_file'] as string | undefined;
     lines.push(
-      `${BOLD}ACTION ${actionName}${actionFile ? ` (${actionFile})` : ''}${RESET}  ${dimTrace}`
+      `${style('bold', `ACTION ${actionName}${actionFile ? ` (${actionFile})` : ''}`)}  ${dimTrace}`
     );
   } else {
-    lines.push(`${colorMethod(method)} ${BOLD}${path}${RESET}  ${dimTrace}`);
+    lines.push(`${colorMethod(method)} ${style('bold', path)}  ${dimTrace}`);
   }
 
   // Render child span nodes
@@ -271,17 +269,17 @@ export function formatSpanTree(spans: ReadableSpan[], config?: DevLoggerConfig):
   const statusCode = root.attributes['http.response.status_code'] as number | undefined;
   const status = statusCode ?? (root.status.code === 2 ? 500 : 200);
   const totalMs = Math.round(hrTimeToMs(root.duration));
-  const statusColor = status < 400 ? GREEN : status < 500 ? YELLOW : RED;
+  const statusFmt = status < 400 ? 'green' : status < 500 ? 'yellow' : 'red';
   const statusText = `${status} ${httpStatusText(status)}`;
 
   // Surface deny() signal info for 500s caused by deny-inside-suspense
   const denyInfo = root.attributes['timber.deny_status'] as number | undefined;
   const denyNote = denyInfo
-    ? `${DIM}  (caused by deny(${denyInfo}) inside Suspense — status already committed)${RESET}`
+    ? style('dim', `  (caused by deny(${denyInfo}) inside Suspense — status already committed)`)
     : '';
 
   lines.push(
-    `${statusColor}└─ ✓ ${statusText}${RESET}${DIM}                              total    ${totalMs}ms${RESET}${denyNote}`
+    `${style(statusFmt, `└─ ✓ ${statusText}`)}${style('dim', `                              total    ${totalMs}ms`)}${denyNote}`
   );
 
   return lines.join('\n') + '\n';
@@ -307,18 +305,18 @@ function formatFetchLine(
   const fetchError = span.attributes['timber.fetch_error'] as string | undefined;
   const isError = span.status.code === 2; // SpanStatusCode.ERROR
 
-  let line = `${prefix}${connector} ${DIM}fetch ${method}${RESET} ${url}`;
-  line += `  ${DIM}${startMs}ms → ${endMs}ms (${durationMs}ms)${RESET}`;
+  let line = `${prefix}${connector} ${style('dim', `fetch ${method}`)} ${url}`;
+  line += `  ${style('dim', `${startMs}ms → ${endMs}ms (${durationMs}ms)`)}`;
 
   if (cacheStatus) {
-    line += `  ${DIM}[cdn: ${cacheStatus}]${RESET}`;
+    line += `  ${style('dim', `[cdn: ${cacheStatus}]`)}`;
   }
 
   if (isError) {
     const errMsg = fetchError ? `: ${fetchError}` : '';
-    line += `  ${RED}ERROR${errMsg}${RESET}`;
+    line += `  ${style('red', `ERROR${errMsg}`)}`;
   } else if (statusCode && statusCode >= 400) {
-    line += `  ${YELLOW}${statusCode}${RESET}`;
+    line += `  ${style('yellow', String(statusCode))}`;
   }
 
   return line;
@@ -363,10 +361,9 @@ function formatSpanNode(
     }
   }
 
-  const slowHighlight = isSlow ? YELLOW : '';
-  const slowReset = isSlow ? RESET : '';
-  const envTag = `${CYAN}[${env}]${RESET}`;
-  const line = `${prefix}${connector} ${envTag} ${slowHighlight}${label}${slowReset}  ${DIM}${timing}${RESET}`;
+  const styledLabel = isSlow ? style('yellow', label) : label;
+  const envTag = style('cyan', `[${env}]`);
+  const line = `${prefix}${connector} ${envTag} ${styledLabel}  ${style('dim', timing)}`;
   lines.push(line);
 
   // Span events (cache hits/misses) as child annotations
@@ -378,7 +375,7 @@ function formatSpanNode(
       const durStr = durMs !== undefined ? `  ${durMs < 1 ? '<1' : Math.round(durMs)}ms` : '';
       const stale = event.attributes?.['stale'] ? ' (stale)' : '';
       lines.push(
-        `${childPrefix}${DIM}└── ${key}  timber.cache ${hitMiss}${durStr}${stale}${RESET}`
+        `${childPrefix}${style('dim', `└── ${key}  timber.cache ${hitMiss}${durStr}${stale}`)}`
       );
     }
   }
@@ -405,8 +402,8 @@ export function formatSpanSummary(spans: ReadableSpan[], _config?: DevLoggerConf
   const traceId = root.spanContext().traceId;
   const traceIdShort = traceId.slice(0, 8);
 
-  const statusColor = status < 400 ? GREEN : status < 500 ? YELLOW : RED;
-  return `${colorMethod(method)} ${path} → ${statusColor}${status} ${httpStatusText(status)}${RESET}  ${totalMs}ms  ${DIM}trace_id: ${traceIdShort}...${RESET}\n`;
+  const statusFmt = status < 400 ? 'green' : status < 500 ? 'yellow' : 'red';
+  return `${colorMethod(method)} ${path} → ${style(statusFmt, `${status} ${httpStatusText(status)}`)}  ${totalMs}ms  ${style('dim', `trace_id: ${traceIdShort}...`)}\n`;
 }
 
 /**
@@ -449,20 +446,5 @@ export function formatJson(spans: ReadableSpan[]): string {
 // ─── Helpers ────────────────────────────────────────────────────────────────
 
 function httpStatusText(status: number): string {
-  const texts: Record<number, string> = {
-    200: 'OK',
-    201: 'Created',
-    204: 'No Content',
-    301: 'Moved Permanently',
-    302: 'Found',
-    304: 'Not Modified',
-    400: 'Bad Request',
-    401: 'Unauthorized',
-    403: 'Forbidden',
-    404: 'Not Found',
-    405: 'Method Not Allowed',
-    413: 'Payload Too Large',
-    500: 'Internal Server Error',
-  };
-  return texts[status] ?? String(status);
+  return STATUS_CODES[status] ?? String(status);
 }