@timber-js/app 0.1.1 → 0.1.3

package/src/plugins/dev-logs.ts

@@ -0,0 +1,280 @@
+/**
+ * timber-dev-logs — Pipes server console output to the browser console in dev.
+ *
+ * Patches `console.log/warn/error/debug/info` on the server side and
+ * forwards messages to connected browsers via Vite's HMR WebSocket.
+ * The browser entry replays them in the browser console with the
+ * correct log level and a "[server]" prefix.
+ *
+ * Dev-only: this plugin only runs during `vite dev` (apply: 'serve').
+ * No runtime overhead in production.
+ *
+ * Design docs: 18-build-system.md §"Dev Server", 02-rendering-pipeline.md
+ */
+
+import type { Plugin, ViteDevServer } from 'vite';
+import type { PluginContext } from '#/index.js';
+
+// ─── Types ───────────────────────────────────────────────────────────────
+
+/** Log levels that are patched and forwarded. */
+export type ServerLogLevel = 'log' | 'warn' | 'error' | 'debug' | 'info';
+
+const LOG_LEVELS: ServerLogLevel[] = ['log', 'warn', 'error', 'debug', 'info'];
+
+/** Payload sent over Vite's HMR WebSocket. */
+export interface ServerLogPayload {
+  level: ServerLogLevel;
+  args: unknown[];
+  /** Server-side source location (file:line:col) if available. */
+  location: string | null;
+  /** Timestamp in ms (Date.now()) */
+  timestamp: number;
+}
+
+// ─── Serialization ───────────────────────────────────────────────────────
+
+/** Patterns that look like env vars or secrets — these are redacted. */
+const SENSITIVE_PATTERNS =
+  /(?:^|[^a-z])(?:SECRET|TOKEN|PASSWORD|API_KEY|PRIVATE_KEY|AUTH|CREDENTIAL|SESSION_SECRET)(?:[^a-z]|$)/i;
+
+/**
+ * Serialize a console argument for transmission over WebSocket.
+ *
+ * Handles: strings, numbers, booleans, null, undefined, arrays, plain
+ * objects, Errors, Dates, RegExps, and falls back to String() for others.
+ *
+ * Redacts values that match sensitive patterns to avoid leaking secrets.
+ */
+function serializeArg(arg: unknown, depth = 0): unknown {
+  if (depth > 5) return '[...]';
+
+  if (arg === null) return null;
+  if (arg === undefined) return '[undefined]';
+
+  switch (typeof arg) {
+    case 'string':
+      if (SENSITIVE_PATTERNS.test(arg)) return '[REDACTED]';
+      return arg;
+    case 'number':
+    case 'boolean':
+      return arg;
+    case 'bigint':
+      return `${arg}n`;
+    case 'symbol':
+      return arg.toString();
+    case 'function':
+      return `[Function: ${arg.name || 'anonymous'}]`;
+    case 'object':
+      break;
+    default:
+      return String(arg);
+  }
+
+  // Error
+  if (arg instanceof Error) {
+    return {
+      __type: 'Error',
+      name: arg.name,
+      message: arg.message,
+      stack: arg.stack ?? null,
+    };
+  }
+
+  // Date
+  if (arg instanceof Date) {
+    return arg.toISOString();
+  }
+
+  // RegExp
+  if (arg instanceof RegExp) {
+    return arg.toString();
+  }
+
+  // Array
+  if (Array.isArray(arg)) {
+    return arg.map((item) => serializeArg(item, depth + 1));
+  }
+
+  // Map
+  if (arg instanceof Map) {
+    const entries: Record<string, unknown> = {};
+    for (const [key, value] of arg) {
+      entries[String(key)] = serializeArg(value, depth + 1);
+    }
+    return { __type: 'Map', entries };
+  }
+
+  // Set
+  if (arg instanceof Set) {
+    return { __type: 'Set', values: [...arg].map((v) => serializeArg(v, depth + 1)) };
+  }
+
+  // Plain object
+  if (Object.getPrototypeOf(arg) === Object.prototype || Object.getPrototypeOf(arg) === null) {
+    const result: Record<string, unknown> = {};
+    for (const [key, value] of Object.entries(arg as Record<string, unknown>)) {
+      if (SENSITIVE_PATTERNS.test(key)) {
+        result[key] = '[REDACTED]';
+      } else {
+        result[key] = serializeArg(value, depth + 1);
+      }
+    }
+    return result;
+  }
+
+  // Fallback — use toString or constructor name
+  try {
+    return `[${(arg as object).constructor?.name ?? 'Object'}]`;
+  } catch {
+    return '[Object]';
+  }
+}
+
+// ─── Source Location ─────────────────────────────────────────────────────
+
+/**
+ * Extract the caller's source location from an Error stack trace.
+ *
+ * Walks the stack to find the first frame that isn't inside this file
+ * or Node internals. Returns "file:line:col" or null.
+ */
+function extractCallerLocation(projectRoot: string): string | null {
+  const err = new Error();
+  const stack = err.stack;
+  if (!stack) return null;
+
+  const lines = stack.split('\n');
+  // Skip first line ("Error") and frames inside this module
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    // Skip our own patching frames
+    if (line.includes('dev-logs')) continue;
+    // Skip node internals
+    if (line.includes('node:') || line.includes('node_modules')) continue;
+
+    // Extract file path from "at ... (file:line:col)" or "at file:line:col"
+    const match = line.match(/\((.+?):(\d+):(\d+)\)/) ?? line.match(/at (.+?):(\d+):(\d+)/);
+    if (match) {
+      let filePath = match[1];
+      // Make path relative to project root for readability
+      if (filePath.startsWith(projectRoot)) {
+        filePath = filePath.slice(projectRoot.length + 1);
+      }
+      return `${filePath}:${match[2]}:${match[3]}`;
+    }
+  }
+  return null;
+}
+
+// ─── Framework-Internal Detection ────────────────────────────────────────
+
+/**
+ * Check if the calling code is from timber's internal plugin/adapter plumbing.
+ *
+ * Only filters logs from `plugins/` and `adapters/` directories — these are
+ * framework operational noise (request summaries, codegen warnings, adapter
+ * setup). Logs from `server/` are preserved because they surface user errors
+ * (render errors, action errors, route handler errors, etc.).
+ *
+ * Handles both monorepo paths (timber-app/src/plugins/) and installed
+ * package paths (@timber/app/dist/plugins/).
+ */
+export function isFrameworkInternalCaller(): boolean {
+  const err = new Error();
+  const stack = err.stack;
+  if (!stack) return false;
+
+  const lines = stack.split('\n');
+  for (let i = 1; i < lines.length; i++) {
+    const line = lines[i].trim();
+    // Skip our own patching frames
+    if (line.includes('dev-logs')) continue;
+    // Skip node internals (but NOT node_modules — we need to inspect those)
+    if (line.includes('node:')) continue;
+
+    // Check if this first real frame is inside timber's own source
+    const isTimberPath = line.includes('timber-app/') || line.includes('@timber/app/');
+    if (!isTimberPath) return false;
+
+    // Only filter plugin and adapter internals, not server/ runtime code
+    // which surfaces user errors (render errors, action errors, etc.)
+    return line.includes('/plugins/') || line.includes('/adapters/');
+  }
+  return false;
+}
+
+// ─── Console Patching ────────────────────────────────────────────────────
+
+/**
+ * Patch console methods to forward logs to the browser via HMR WebSocket.
+ *
+ * Each patched method:
+ * 1. Calls the original console method (server terminal still works)
+ * 2. Serializes arguments for JSON transport
+ * 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>();
+
+  for (const level of LOG_LEVELS) {
+    originals.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;
+
+      // Serialize and forward to browser
+      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
+      }
+    };
+  }
+
+  // Return a cleanup function to restore originals
+  return () => {
+    for (const [level, original] of originals) {
+      console[level] = original;
+    }
+  };
+}
+
+// ─── Plugin ──────────────────────────────────────────────────────────────
+
+/**
+ * Create the timber-dev-logs Vite plugin.
+ *
+ * Patches console methods when the dev server starts and restores them
+ * when the server closes. Only active during `vite dev`.
+ */
+export function timberDevLogs(_ctx: PluginContext): Plugin {
+  let cleanup: (() => void) | null = null;
+
+  return {
+    name: 'timber-dev-logs',
+    apply: 'serve',
+
+    configureServer(server: ViteDevServer) {
+      cleanup = patchConsole(server, _ctx.root);
+
+      // Restore console on server close
+      server.httpServer?.on('close', () => {
+        cleanup?.();
+        cleanup = null;
+      });
+    },
+  };
+}

package/src/plugins/dev-server.ts

@@ -0,0 +1,391 @@
+/**
+ * timber-dev-server — Vite sub-plugin for dev server request handling.
+ *
+ * Registers a configureServer middleware that intercepts requests and
+ * routes them through the timber pipeline:
+ *   proxy.ts → canonicalize → route match → middleware → access → render → flush
+ *
+ * The RSC entry module is loaded via Vite's ssrLoadModule, which uses
+ * Vite's dev module graph instead of built bundles. The full pipeline
+ * (including proxy.ts) runs on every request.
+ *
+ * Design docs: 18-build-system.md §"Dev Server", 02-rendering-pipeline.md
+ */
+
+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 { sendErrorToOverlay, classifyErrorPhase, parseFirstAppFrame } from './dev-error-overlay.js';
+
+// ─── Constants ────────────────────────────────────────────────────────────
+
+const RSC_ENTRY_ID = 'virtual:timber-rsc-entry';
+
+/**
+ * Config file names that trigger a full dev server restart when changed.
+ * See 21-dev-server.md §HMR Wiring — config is loaded once at startup.
+ */
+const CONFIG_FILE_NAMES = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+
+/**
+ * URL prefixes that are Vite-internal and should never be intercepted.
+ * These are passed through to Vite's built-in middleware.
+ */
+const VITE_INTERNAL_PREFIXES = [
+  '/@', // /@vite/client, /@fs/, /@id/
+  '/__vite', // /__vite_hmr, /__vite_ping
+  '/node_modules/',
+];
+
+/**
+ * File extensions that indicate static asset requests.
+ * These are passed through to Vite's static file serving.
+ */
+const ASSET_EXTENSIONS =
+  /\.(?:js|ts|tsx|jsx|css|map|json|svg|png|jpg|jpeg|gif|webp|avif|ico|woff|woff2|ttf|eot|mp4|webm|ogg|mp3|wav)(?:\?.*)?$/;
+
+// ─── Plugin ───────────────────────────────────────────────────────────────
+
+/**
+ * Create the timber-dev-server Vite plugin.
+ *
+ * Hook: configureServer (returns post-hook to register after Vite's middleware)
+ */
+export function timberDevServer(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-dev-server',
+
+    // Only active in dev mode (command === 'serve'), not during build.
+    // See 21-dev-server.md §Plugin Registration.
+    apply: 'serve',
+
+    /**
+     * Register the dev server middleware and config file watcher.
+     *
+     * Registers as a pre-hook (no return value) so our middleware runs
+     * before Vite's built-in SPA fallback / historyApiFallback. This
+     * ensures we see the original URL (e.g. /blog) rather than a
+     * rewritten /index.html. Vite-internal and asset requests are
+     * filtered out explicitly and passed through to Vite.
+     */
+    configureServer(server: ViteDevServer) {
+      // Watch config files for full restart.
+      // timber.config.ts is loaded once at startup — any change requires
+      // a full dev server restart. See 21-dev-server.md §HMR Wiring.
+      const configPaths = CONFIG_FILE_NAMES.map((name) => join(ctx.root, name));
+
+      server.watcher.on('change', (filePath: string) => {
+        if (configPaths.includes(filePath)) {
+          server.restart();
+        }
+      });
+
+      // Register Vite server for browser console warning forwarding.
+      // See 21-dev-server.md §Dev-Mode Warnings.
+      setViteServer(server);
+
+      // Listen for client-side errors forwarded from the browser.
+      // The browser entry sends 'timber:client-error' events via HMR
+      // for uncaught errors and unhandled rejections. We echo them back
+      // as Vite's '{ type: "error" }' payload to trigger the overlay.
+      listenForClientErrors(server, ctx.root);
+
+      // Pre-hook — registers middleware before Vite's internals
+      server.middlewares.use(createTimberMiddleware(server, ctx.root));
+
+      // Log startup timing summary. configureServer runs on all plugins
+      // before the server listens, so this captures the full cold start.
+      ctx.timer.end('dev-server-setup');
+      const summary = ctx.timer.formatSummary();
+      if (summary) {
+        console.log(summary);
+      }
+    },
+  };
+}
+
+// ─── Middleware ────────────────────────────────────────────────────────────
+
+/**
+ * Create the Connect middleware that routes requests through the timber pipeline.
+ *
+ * For route requests (HTML pages, API endpoints), the middleware:
+ * 1. Loads the RSC entry via ssrLoadModule
+ * 2. Converts the Node request to a Web Request
+ * 3. Passes it through the RSC handler (which runs the full pipeline)
+ * 4. Converts the Web Response back to a Node response
+ *
+ * For non-route requests (assets, Vite internals, HMR), the middleware
+ * calls next() to let Vite handle them.
+ */
+function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
+  return async (req: IncomingMessage, res: ServerResponse, next: () => void): Promise<void> => {
+    const url = req.url;
+    if (!url) {
+      next();
+      return;
+    }
+
+    // Pass through Vite-internal requests
+    if (isViteInternal(url)) {
+      next();
+      return;
+    }
+
+    // Pass through static asset requests
+    if (isAssetRequest(url)) {
+      next();
+      return;
+    }
+
+    // Step 1: Load the RSC entry module from the RSC environment.
+    // The RSC entry runs in the 'rsc' Vite environment (separate module
+    // graph with react-server conditions). In dev mode, this uses the
+    // environment's module runner for HMR-aware loading.
+    let handler: (req: Request) => Promise<Response>;
+    try {
+      const rscEnv = server.environments.rsc as DevEnvironment & { runner?: { import: (id: string) => Promise<any> } };
+      // Duck-type check instead of isRunnableDevEnvironment() — the vite
+      // import-based check fails across pnpm link boundaries where the
+      // linked package resolves a different vite module instance.
+      if (!rscEnv?.runner?.import) {
+        throw new Error('[timber] RSC environment is not runnable');
+      }
+      const rscModule = await rscEnv.runner.import(RSC_ENTRY_ID);
+      handler = rscModule.default as (req: Request) => Promise<Response>;
+
+      // Wire pipeline errors into the browser error overlay.
+      // setDevPipelineErrorHandler is only defined in dev (rsc-entry.ts exports it).
+      const setHandler = rscModule.setDevPipelineErrorHandler as
+        | ((fn: (error: Error, phase: string) => void) => void)
+        | undefined;
+      if (typeof setHandler === 'function') {
+        setHandler((error) => {
+          sendErrorToOverlay(server, error, classifyErrorPhase(error, projectRoot), projectRoot);
+        });
+      }
+    } catch (error) {
+      // Module transform error — syntax error, missing import, etc.
+      // Vite may already show its own overlay for these, but we still
+      // log to stderr with frame dimming for the terminal.
+      if (error instanceof Error) {
+        sendErrorToOverlay(server, error, 'module-transform', projectRoot);
+      }
+      respond500(res, error);
+      return;
+    }
+
+    if (typeof handler !== 'function') {
+      console.error('[timber] RSC entry module does not export a default function');
+      next();
+      return;
+    }
+
+    // Step 2: Run the pipeline.
+    try {
+      // Convert Node IncomingMessage → Web Request
+      const webRequest = toWebRequest(req);
+
+      // Run the full pipeline
+      const webResponse = await handler(webRequest);
+
+      // Convert Web Response → Node ServerResponse
+      await sendWebResponse(res, webResponse);
+    } catch (error) {
+      // Pipeline error — classify the phase, send to overlay, respond 500.
+      // The dev server remains running for recovery on file fix + HMR.
+      if (error instanceof Error) {
+        const phase = classifyErrorPhase(error, projectRoot);
+        sendErrorToOverlay(server, error, phase, projectRoot);
+      } else {
+        process.stderr.write(`\x1b[31m[timber] Dev server error:\x1b[0m ${String(error)}\n`);
+      }
+      respond500(res, error);
+    }
+  };
+}
+
+/**
+ * Send a 500 response without crashing the dev server.
+ */
+function respond500(res: ServerResponse, error: unknown): void {
+  if (!res.headersSent) {
+    res.statusCode = 500;
+    res.setHeader('content-type', 'text/plain');
+    res.end(
+      `[timber] Internal server error\n\n${error instanceof Error ? (error.stack ?? error.message) : String(error)}`
+    );
+  }
+}
+
+// ─── Request/Response Conversion ──────────────────────────────────────────
+
+/**
+ * Convert a Node IncomingMessage to a Web Request.
+ *
+ * Constructs the full URL from the Host header and request URL,
+ * and forwards the method, headers, and body.
+ */
+function toWebRequest(nodeReq: IncomingMessage): Request {
+  const protocol = 'http';
+  const host = nodeReq.headers.host ?? 'localhost';
+  const url = `${protocol}://${host}${nodeReq.url}`;
+
+  const headers = new Headers();
+  for (const [key, value] of Object.entries(nodeReq.headers)) {
+    if (value === undefined) continue;
+    if (Array.isArray(value)) {
+      for (const v of value) {
+        headers.append(key, v);
+      }
+    } else {
+      headers.set(key, value);
+    }
+  }
+
+  const method = nodeReq.method ?? 'GET';
+  const hasBody = method !== 'GET' && method !== 'HEAD';
+
+  return new Request(url, {
+    method,
+    headers,
+    body: hasBody ? nodeReadableToWebStream(nodeReq) : undefined,
+    // @ts-expect-error — duplex is required for streaming request bodies
+    duplex: hasBody ? 'half' : undefined,
+  });
+}
+
+/**
+ * Convert a Node Readable stream to a Web ReadableStream.
+ */
+function nodeReadableToWebStream(nodeStream: IncomingMessage): ReadableStream<Uint8Array> {
+  return new ReadableStream({
+    start(controller) {
+      nodeStream.on('data', (chunk: Buffer) => {
+        controller.enqueue(new Uint8Array(chunk));
+      });
+      nodeStream.on('end', () => {
+        controller.close();
+      });
+      nodeStream.on('error', (err) => {
+        controller.error(err);
+      });
+    },
+  });
+}
+
+/**
+ * Write a Web Response to a Node ServerResponse.
+ *
+ * Copies status code, headers, and streams the body.
+ */
+async function sendWebResponse(nodeRes: ServerResponse, webResponse: Response): Promise<void> {
+  nodeRes.statusCode = webResponse.status;
+
+  // Copy headers. Set-Cookie needs special handling: Headers.forEach()
+  // joins multiple Set-Cookie values with ", " into one entry, but each
+  // cookie must be its own header per RFC 6265 §4.1. Use getSetCookie()
+  // to preserve individual Set-Cookie headers.
+  webResponse.headers.forEach((value, key) => {
+    if (key.toLowerCase() !== 'set-cookie') {
+      nodeRes.setHeader(key, value);
+    }
+  });
+  const setCookies = webResponse.headers.getSetCookie();
+  if (setCookies.length > 0) {
+    nodeRes.setHeader('Set-Cookie', setCookies);
+  }
+
+  // Stream the body
+  if (!webResponse.body) {
+    nodeRes.end();
+    return;
+  }
+
+  // Flush headers immediately so the client can start processing
+  // the response (critical for SSE and other streaming responses).
+  nodeRes.flushHeaders();
+
+  const reader = webResponse.body.getReader();
+  try {
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      // write() returns false when the kernel buffer is full, but we
+      // don't need back-pressure here — just keep pushing chunks.
+      nodeRes.write(value);
+    }
+  } finally {
+    reader.releaseLock();
+    nodeRes.end();
+  }
+}
+
+// ─── URL Classification ──────────────────────────────────────────────────
+
+/**
+ * Check if a URL is a Vite-internal request that should be passed through.
+ */
+function isViteInternal(url: string): boolean {
+  return VITE_INTERNAL_PREFIXES.some((prefix) => url.startsWith(prefix));
+}
+
+/**
+ * Check if a URL looks like a static asset request.
+ */
+function isAssetRequest(url: string): boolean {
+  return ASSET_EXTENSIONS.test(url);
+}
+
+// ─── Client Error Listener ─────────────────────────────────────────────
+
+interface ClientErrorPayload {
+  message: string;
+  stack: string;
+  componentStack: string | null;
+}
+
+/**
+ * Listen for client-side errors forwarded from the browser via HMR.
+ *
+ * The browser entry catches uncaught errors and unhandled rejections,
+ * then sends them as 'timber:client-error' custom events. We parse
+ * the first app frame for the overlay's loc field and forward the
+ * error to Vite's overlay protocol.
+ */
+function listenForClientErrors(server: ViteDevServer, projectRoot: string): void {
+  server.hot.on('timber:client-error', (data: ClientErrorPayload) => {
+    const loc = parseFirstAppFrame(data.stack, projectRoot);
+
+    let message = data.message;
+    if (data.componentStack) {
+      message = `${data.message}\n\nComponent Stack:\n${data.componentStack.trim()}`;
+    }
+
+    // Log to stderr
+    const RED = '\x1b[31m';
+    const BOLD = '\x1b[1m';
+    const RESET = '\x1b[0m';
+    process.stderr.write(
+      `${RED}${BOLD}[timber] Client Error${RESET}\n${RED}${data.message}${RESET}\n\n`
+    );
+
+    // Forward to Vite's overlay
+    try {
+      server.hot.send({
+        type: 'error',
+        err: {
+          message,
+          stack: data.stack,
+          id: loc?.file,
+          plugin: 'timber (Client)',
+          loc: loc ? { file: loc.file, line: loc.line, column: loc.column } : undefined,
+        },
+      });
+    } catch {
+      // Overlay send must never crash the dev server
+    }
+  });
+}