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

package/src/dev-tools/index.ts

@@ -0,0 +1,90 @@
+/**
+ * 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
+ * - warnings: dev-mode footgun warnings
+ * - 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.js';
+
+// Error overlay (Vite integration)
+export {
+  sendErrorToOverlay,
+  fixErrorStacktrace,
+  classifyErrorPhase,
+  extractComponentStack,
+  parseFirstAppFrame,
+  calculateModuleRunnerOffset,
+  formatRscDebugContext,
+  formatTerminalError,
+  PHASE_LABELS,
+  type ErrorPhase,
+  type RscDebugComponentInfo,
+} from './overlay.js';
+
+// HTML error pages
+export { generateDevErrorPage, extractHmrOptions, type DevErrorHmrOptions } from './error-page.js';
+export { generateDev404Page, collectRoutes, findSimilarRoutes } from './404-page.js';
+
+// Terminal error formatting
+export { formatTerminalError as formatTerminalErrorDirect } from './terminal.js';
+
+// Request tree logger
+export {
+  formatSpanTree,
+  formatSpanSummary,
+  formatJson,
+  resolveLogMode,
+  type DevLogMode,
+  type DevLoggerConfig,
+} from './logger.js';
+
+// Dev-mode warnings
+export {
+  warnSuspenseWrappingChildren,
+  warnDenyInSuspense,
+  warnRedirectInSuspense,
+  warnRedirectInAccess,
+  warnStaticRequestApi,
+  warnSlowSlotWithoutSuspense,
+  setViteServer,
+  WarningId,
+  type DevWarningConfig,
+  _resetWarnings,
+  _getEmitted,
+} from './warnings.js';
+
+// Browser log forwarding
+export {
+  timberDevBrowserLogs,
+  type BrowserLogLevel,
+  type DevBrowserLogsConfig,
+} from './browser-logs.js';
+
+// Server log forwarding
+export { timberDevLogs } from './logs.js';
+
+// Holding server
+export { createHoldingServer, type HoldingServer } from './holding-server.js';
+
+// OTEL instrumentation
+export { instrumentDevFetch, DevSpanProcessor, type DevFetchCleanup } from './instrumentation.js';

package/src/dev-tools/instrumentation.ts

@@ -0,0 +1,176 @@
+/**
+ * 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.
+ *
+ * Only activated in dev mode — zero overhead in production.
+ *
+ * Design ref: 17-logging.md §"Dev Logging", 21-dev-server.md §"Dev Logging"
+ */
+
+import * as api from '@opentelemetry/api';
+import type { SpanProcessor, ReadableSpan } from '@opentelemetry/sdk-trace-base';
+import type { Span, Context } from '@opentelemetry/api';
+import {
+  formatSpanTree,
+  formatSpanSummary,
+  formatJson,
+  type DevLogMode,
+  type DevLoggerConfig,
+} from './logger.js';
+
+// ─── Fetch Instrumentation ──────────────────────────────────────────────────
+
+export type DevFetchCleanup = () => void;
+
+/**
+ * Patch globalThis.fetch to wrap every call in an OTEL span.
+ *
+ * Returns a cleanup function that restores the original fetch.
+ * Only call this in dev mode.
+ */
+export function instrumentDevFetch(): DevFetchCleanup {
+  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;
+        }
+      }
+    );
+  };
+
+  return () => {
+    globalThis.fetch = originalFetch;
+  };
+}
+
+/**
+ * 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 {
+  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) {
+      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.
+  }
+}

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

@@ -13,7 +13,7 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 
@@ -149,7 +149,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 +189,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;
 
@@ -238,8 +238,12 @@ function patchConsole(server: ViteDevServer, projectRoot: string): () => void {
         };
 
         server.hot.send('timber:server-log', payload);
-      } catch {
-        // Never let log forwarding break the server
+      } catch (e) {
+        // Use the original console.debug to avoid re-entering the patched handler
+        originals.get('debug')!(
+          '[timber] server log forwarding failed:',
+          e instanceof Error ? e.message : e
+        );
       }
     };
   }