@timber-js/app 0.2.0-alpha.6 → 0.2.0-alpha.61

package/src/plugins/dev-browser-logs.ts

@@ -0,0 +1,284 @@
+/**
+ * timber-dev-browser-logs — Forwards browser console output to the server terminal.
+ *
+ * Injects a small inline script in dev mode that intercepts browser
+ * `console.error`, `console.warn`, and `console.info`, then forwards
+ * messages to the server via Vite's HMR WebSocket.
+ *
+ * The server-side listener formats and prints the messages with color-coded
+ * prefixes: [browser:error], [browser:warn], [browser:info].
+ *
+ * Dev-only: this plugin only runs during `vite dev`.
+ * No runtime overhead in production.
+ *
+ * See TIM-513 for design context.
+ * See design/18-build-system.md §"Dev Server" for sub-plugin architecture.
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import type { PluginContext } from '../index.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/** Log levels forwarded from the browser. */
+export type BrowserLogLevel = 'error' | 'warn' | 'info';
+
+/** Configuration value for devBrowserLogs in timber.config.ts. */
+export type DevBrowserLogsConfig = BrowserLogLevel | 'none' | undefined;
+
+/**
+ * Payload sent from browser to server via Vite's HMR WebSocket.
+ * Kept small — truncated before sending.
+ */
+export interface BrowserLogPayload {
+  level: BrowserLogLevel;
+  /** Serialized message string. */
+  message: string;
+  /** Error stack trace, if the first argument was an Error. */
+  stack: string | null;
+  /** Source URL and line number, if available. */
+  source: string | null;
+  /** Timestamp in ms (Date.now()) from the browser. */
+  timestamp: number;
+}
+
+// ─── Constants ───────────────────────────────────────────────────────────
+
+/** Max message size in bytes before truncation. */
+const MAX_MESSAGE_BYTES = 2048;
+
+/** HMR event name for browser→server log forwarding. */
+const HMR_EVENT = 'timber:browser-log';
+
+/** ANSI color codes for terminal output. */
+const COLORS = {
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  blue: '\x1b[34m',
+  dim: '\x1b[2m',
+  reset: '\x1b[0m',
+} as const;
+
+/** Level severity ordering for threshold comparison. */
+const LEVEL_SEVERITY: Record<BrowserLogLevel | 'none', number> = {
+  none: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+};
+
+// ─── Formatting ──────────────────────────────────────────────────────────
+
+/**
+ * Format a browser log payload for server terminal output.
+ *
+ * Produces color-coded output like:
+ *   [browser:error] Uncaught TypeError: x is not a function
+ *     at App (app.tsx:10:5)
+ *   [browser:warn] Deprecation warning (app/page.tsx:42:12)
+ */
+export function formatBrowserLog(payload: BrowserLogPayload): string {
+  const { level, message, stack, source } = payload;
+
+  // Color-coded prefix
+  const color = level === 'error' ? COLORS.red : level === 'warn' ? COLORS.yellow : COLORS.blue;
+  const prefix = `${color}[browser:${level}]${COLORS.reset}`;
+
+  // Source suffix
+  const sourceSuffix = source ? ` ${COLORS.dim}(${source})${COLORS.reset}` : '';
+
+  let output = `${prefix} ${message}${sourceSuffix}`;
+
+  // Append stack trace indented
+  if (stack) {
+    const indented = stack
+      .split('\n')
+      .map((line) => `  ${COLORS.dim}${line}${COLORS.reset}`)
+      .join('\n');
+    output += `\n${indented}`;
+  }
+
+  return output;
+}
+
+// ─── Level Filtering ─────────────────────────────────────────────────────
+
+/**
+ * Check if a log at `level` should be forwarded given the configured threshold.
+ *
+ * The threshold acts as a minimum severity:
+ * - 'error' → only errors
+ * - 'warn' → errors + warnings
+ * - 'info' → errors + warnings + info
+ * - 'none' → nothing
+ */
+export function shouldForwardLevel(
+  level: BrowserLogLevel,
+  threshold: BrowserLogLevel | 'none'
+): boolean {
+  if (threshold === 'none') return false;
+  return LEVEL_SEVERITY[level] >= LEVEL_SEVERITY[threshold];
+}
+
+// ─── Truncation ──────────────────────────────────────────────────────────
+
+/**
+ * Truncate a message to `maxBytes` to avoid flooding the terminal.
+ * Appends a suffix indicating how many bytes were dropped.
+ */
+export function truncateMessage(message: string, maxBytes: number): string {
+  if (message.length <= maxBytes) return message;
+
+  const truncated = message.slice(0, maxBytes);
+  const droppedBytes = message.length - maxBytes;
+  return `${truncated}… [truncated ${droppedBytes} bytes]`;
+}
+
+// ─── Client Injection Script ─────────────────────────────────────────────
+
+/**
+ * Generate the inline script injected into the browser in dev mode.
+ *
+ * This script:
+ * 1. Saves references to the original console methods
+ * 2. Wraps `console.error`, `console.warn`, `console.info`
+ * 3. Calls the original first (browser devtools still work)
+ * 4. Serializes and forwards via `import.meta.hot.send()`
+ * 5. Truncates messages to MAX_MESSAGE_BYTES
+ *
+ * The script is minimal and self-contained — no imports, no dependencies.
+ */
+export function generateClientScript(threshold: BrowserLogLevel | 'none'): string {
+  if (threshold === 'none') return '';
+
+  // Only intercept levels that meet the threshold
+  const levels: BrowserLogLevel[] = ['error', 'warn', 'info'].filter((l) =>
+    shouldForwardLevel(l as BrowserLogLevel, threshold)
+  ) as BrowserLogLevel[];
+
+  if (levels.length === 0) return '';
+
+  return `
+(function() {
+  if (!import.meta.hot) return;
+  var MAX_BYTES = ${MAX_MESSAGE_BYTES};
+  var levels = ${JSON.stringify(levels)};
+  var originals = {};
+
+  function serialize(arg) {
+    if (arg === null) return 'null';
+    if (arg === undefined) return 'undefined';
+    if (arg instanceof Error) return arg.stack || arg.message || String(arg);
+    if (typeof arg === 'object') {
+      try { return JSON.stringify(arg); } catch(e) { return String(arg); }
+    }
+    return String(arg);
+  }
+
+  function truncate(s) {
+    if (s.length <= MAX_BYTES) return s;
+    return s.slice(0, MAX_BYTES) + '... [truncated ' + (s.length - MAX_BYTES) + ' bytes]';
+  }
+
+  levels.forEach(function(level) {
+    originals[level] = console[level];
+    console[level] = function() {
+      originals[level].apply(console, arguments);
+      try {
+        var args = Array.prototype.slice.call(arguments);
+        var firstArg = args[0];
+        var stack = null;
+        var source = null;
+
+        if (firstArg instanceof Error) {
+          stack = firstArg.stack || null;
+          source = null;
+        }
+
+        var message = args.map(serialize).join(' ');
+        message = truncate(message);
+
+        import.meta.hot.send('${HMR_EVENT}', {
+          level: level,
+          message: message,
+          stack: stack,
+          source: source,
+          timestamp: Date.now()
+        });
+      } catch(e) {
+        // Never let log forwarding break the page
+      }
+    };
+  });
+})();
+`.trim();
+}
+
+// ─── Plugin ──────────────────────────────────────────────────────────────
+
+/**
+ * Create the timber-dev-browser-logs Vite plugin.
+ *
+ * - `configureServer`: Listens for HMR messages and prints them to the terminal
+ * - `transformIndexHtml`: Injects the client-side interception script
+ *
+ * Only active during `vite dev` (apply: 'serve').
+ */
+export function timberDevBrowserLogs(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-dev-browser-logs',
+    apply: 'serve',
+
+    configureServer(server: ViteDevServer) {
+      const threshold = ctx.config.devBrowserLogs ?? 'warn';
+      if (threshold === 'none') return;
+
+      // Register the client injection script on globalThis so the RSC entry
+      // can include it in headHtml for all Timber route responses.
+      // transformIndexHtml only runs for Vite's index.html fallback, not
+      // for responses served by createTimberMiddleware (TIM-575).
+      const script = generateClientScript(threshold);
+      if (script) {
+        (globalThis as Record<string, unknown>).__timber_dev_browser_log_script =
+          `<script type="module">${script}</script>`;
+      }
+
+      // Listen for browser log messages via HMR WebSocket
+      server.hot.on(HMR_EVENT, (payload: BrowserLogPayload) => {
+        try {
+          // Validate level
+          if (!shouldForwardLevel(payload.level, threshold)) return;
+
+          // Truncate server-side too (defense in depth)
+          payload.message = truncateMessage(payload.message, MAX_MESSAGE_BYTES);
+
+          const formatted = formatBrowserLog(payload);
+
+          // Use the correct console method for the log level
+          if (payload.level === 'error') {
+            process.stderr.write(formatted + '\n');
+          } else {
+            process.stdout.write(formatted + '\n');
+          }
+        } catch {
+          // Never let log forwarding crash the server
+        }
+      });
+    },
+
+    transformIndexHtml() {
+      const threshold = ctx.config.devBrowserLogs ?? 'warn';
+      const script = generateClientScript(threshold);
+      if (!script) return [];
+
+      return [
+        {
+          tag: 'script',
+          attrs: { type: 'module' },
+          children: script,
+          injectTo: 'head' as const,
+        },
+      ];
+    },
+  };
+}

package/src/plugins/dev-error-overlay.ts

@@ -180,6 +180,63 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
   return lines.join('\n');
 }
 
+// ─── RSC Debug Context ──────────────────────────────────────────────────────
+
+/**
+ * Component info extracted from the RSC debug channel.
+ * Contains only names, environments, and stack frames — never source code.
+ */
+export interface RscDebugComponentInfo {
+  name: string;
+  env: string | null;
+  stack: unknown[] | null;
+}
+
+/**
+ * Format RSC debug component info into a readable string for the overlay.
+ *
+ * Renders the server component tree that was active when an error occurred,
+ * including component names and source locations from stack frames. This
+ * gives developers visibility into which server components were rendering
+ * without exposing source code.
+ *
+ * Returns an empty string if no components are provided.
+ */
+export function formatRscDebugContext(components: RscDebugComponentInfo[]): string {
+  if (!components || components.length === 0) return '';
+
+  // Deduplicate by name — the debug channel may emit the same component
+  // multiple times (e.g., when re-rendered or when multiple instances exist).
+  const seen = new Set<string>();
+  const unique: RscDebugComponentInfo[] = [];
+  for (const c of components) {
+    if (!seen.has(c.name)) {
+      seen.add(c.name);
+      unique.push(c);
+    }
+  }
+
+  const lines: string[] = ['Server Component Tree:'];
+  for (let i = 0; i < unique.length; i++) {
+    const c = unique[i]!;
+    const indent = '  '.repeat(i + 1);
+    const envLabel = c.env ? ` [${c.env}]` : '';
+
+    // Extract file location from stack frames if available
+    let locStr = '';
+    if (c.stack && c.stack.length > 0) {
+      const frame = c.stack[0] as [string, string, number, number] | undefined;
+      if (Array.isArray(frame) && frame.length >= 3) {
+        locStr = ` (${frame[1]}:${frame[2]})`;
+      }
+    }
+
+    lines.push(`${indent}${c.name}${envLabel}${locStr}`);
+  }
+
+  return lines.join('\n');
+}
+
 // ─── Overlay Integration ────────────────────────────────────────────────────
 
 /**
@@ -188,13 +245,19 @@ export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot
  * Uses `server.ssrFixStacktrace()` to map stack traces back to source,
  * then sends the error via `server.hot.send()` for the browser overlay.
  *
+ * When `rscDebugComponents` is provided (dev mode only), the server
+ * component tree context is appended to the error message. This helps
+ * developers identify which server component caused the error without
+ * exposing source code.
+ *
  * The dev server remains running — errors are handled, not fatal.
  */
 export function sendErrorToOverlay(
   server: ViteDevServer,
   error: Error,
   phase: ErrorPhase,
-  projectRoot: string
+  projectRoot: string,
+  rscDebugComponents?: RscDebugComponentInfo[]
 ): void {
   // Fix stack trace to use source-mapped positions
   server.ssrFixStacktrace(error);
@@ -212,6 +275,12 @@ export function sendErrorToOverlay(
     message = `${error.message}\n\nComponent Stack:\n${componentStack.trim()}`;
   }
 
+  // Append RSC debug context if available (dev mode only)
+  const debugContext = formatRscDebugContext(rscDebugComponents ?? []);
+  if (debugContext) {
+    message = `${message}\n\n${debugContext}`;
+  }
+
   // Send to browser via Vite's error overlay protocol
   try {
     server.hot.send({

package/src/plugins/dev-logs.ts

@@ -13,7 +13,7 @@
  */
 
 import type { Plugin, ViteDevServer } from 'vite';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../index.js';
 
 // ─── Types ───────────────────────────────────────────────────────────────
 

package/src/plugins/dev-server.ts

@@ -15,10 +15,10 @@
 import type { Plugin, ViteDevServer, DevEnvironment } from 'vite';
 import type { IncomingMessage, ServerResponse } from 'node:http';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
-import { setViteServer } from '#/server/dev-warnings.js';
+import type { PluginContext } from '../index.js';
+import { setViteServer } from '../server/dev-warnings.js';
 import { sendErrorToOverlay, classifyErrorPhase, parseFirstAppFrame } from './dev-error-overlay.js';
-import { compressResponse } from '#/server/compress.js';
+import { compressResponse } from '../server/compress.js';
 
 // ─── Constants ────────────────────────────────────────────────────────────
 
@@ -161,12 +161,26 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
 
       // Wire pipeline errors into the browser error overlay.
       // setDevPipelineErrorHandler is only defined in dev (rsc-entry.ts exports it).
+      // The handler receives optional RSC debug component data (component names,
+      // environments, stack frames) from the Flight debug channel for render errors.
       const setHandler = rscModule.setDevPipelineErrorHandler as
-        | ((fn: (error: Error, phase: string) => void) => void)
+        | ((
+            fn: (
+              error: Error,
+              phase: string,
+              debugComponents?: Array<{ name: string; env: string | null; stack: unknown[] | null }>
+            ) => void
+          ) => void)
         | undefined;
       if (typeof setHandler === 'function') {
-        setHandler((error) => {
-          sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
+        setHandler((error, _phase, debugComponents) => {
+          sendErrorToOverlay(
+            server,
+            error,
+            classifyErrorPhase(error, projectRoot),
+            projectRoot,
+            debugComponents
+          );
         });
       }
     } catch (error) {
@@ -317,6 +331,17 @@ async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response):
   nodeRes.flushHeaders();
 
   const reader = webResponse.body.getReader();
+
+  // Cancel the reader when the client disconnects. This causes any pending
+  // reader.read() to reject, breaking the pump loop. Critical for SSE and
+  // other infinite streams — without this, disconnected clients leak readers.
+  let clientDisconnected = false;
+  const onClose = () => {
+    clientDisconnected = true;
+    reader.cancel('Client disconnected').catch(() => {});
+  };
+  nodeRes.on('close', onClose);
+
   try {
     while (true) {
       const { done, value } = await reader.read();
@@ -325,9 +350,18 @@ async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response):
       // don't need back-pressure here — just keep pushing chunks.
       nodeRes.write(value);
     }
+  } catch (err) {
+    // reader.cancel() from the close handler causes read() to reject.
+    // This is expected on client disconnect — not an error.
+    if (!clientDisconnected) {
+      throw err;
+    }
   } finally {
+    nodeRes.off('close', onClose);
     reader.releaseLock();
-    nodeRes.end();
+    if (!nodeRes.writableEnded) {
+      nodeRes.end();
+    }
   }
 }
 

package/src/plugins/entries.ts

@@ -15,7 +15,7 @@ import type { Plugin } from 'vite';
 import { resolve, dirname } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { existsSync } from 'node:fs';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../index.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -95,11 +95,6 @@ function stripRootPrefix(id: string, root: string): string {
  * Serializes output mode and feature flags for runtime consumption.
  */
 function generateConfigModule(ctx: PluginContext): string {
-  // Resolve cookie secrets: `secret` shorthand expands to `secrets: [secret]`
-  const cookieSecrets =
-    ctx.config.cookies?.secrets ??
-    (ctx.config.cookies?.secret ? [ctx.config.cookies.secret] : undefined);
-
   const runtimeConfig = {
     output: ctx.config.output ?? 'server',
     csrf: ctx.config.csrf ?? true,
@@ -108,10 +103,13 @@ function generateConfigModule(ctx: PluginContext): string {
     dev: ctx.dev ?? false,
     slowPhaseMs: ctx.config.dev?.slowPhaseMs ?? 200,
     slowRequestMs: ctx.config.slowRequestMs ?? 3000,
-    cookieSecrets,
     topLoader: ctx.config.topLoader,
-    responseCache: ctx.config.responseCache,
     debug: ctx.config.debug ?? false,
+    serverTiming: ctx.config.serverTiming,
+    renderTimeoutMs: ctx.config.renderTimeoutMs ?? 30_000,
+    // Per-build deployment ID for version skew detection (TIM-446).
+    // Null in dev mode — HMR handles code updates without full reloads.
+    deploymentId: ctx.deploymentId ?? null,
   };
 
   return [