@timber-js/app 0.2.0-alpha.8 → 0.2.0-alpha.80

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 '../plugin-context.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 '../plugin-context.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 ────────────────────────────────────────────────────────────
 
@@ -96,6 +96,21 @@ export function timberDevServer(ctx: PluginContext): Plugin {
       // Pre-hook — registers middleware before Vite's internals
       server.middlewares.use(createTimberMiddleware(server, ctx.root));
 
+      // Wrap server.listen() to close the holding server immediately
+      // before Vite binds the port — no gap where nothing is listening.
+      // The holding server was started in rootSync's config() hook to
+      // serve a loading page during initialization.
+      // See design/21-dev-server.md §"Startup Holding Server", TIM-665.
+      if (ctx.holdingServer) {
+        const originalListen = server.listen.bind(server);
+        const holdingRef = ctx.holdingServer;
+        ctx.holdingServer = null;
+        server.listen = async (port?: number, isRestart?: boolean) => {
+          await holdingRef.close().catch(() => {});
+          return originalListen(port, isRestart);
+        };
+      }
+
       // 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');
@@ -161,12 +176,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) {
@@ -191,8 +220,20 @@ function createTimberMiddleware(server: ViteDevServer, projectRoot: string) {
       // Convert Node IncomingMessage → Web Request
       const webRequest = toWebRequest(req);
 
-      // Run the full pipeline
-      const webResponse = await handler(webRequest);
+      // Check for a platform-specific request wrapper (e.g., Cloudflare
+      // dev bindings). The cloudflareDevBindings() plugin stores a wrapper
+      // function on the server instance using a well-known Symbol. The
+      // wrapper runs the handler inside an ALS context so platform APIs
+      // like getCloudflareBindings() work during dev.
+      // See design/35-cloudflare-primitives.md §"Dev Experience".
+      const wrapper = (server as any)[Symbol.for('timber:dev-request-wrapper')] as
+        | (<T>(fn: () => T) => T)
+        | undefined;
+
+      // Run the full pipeline (wrapped if a platform dev plugin is active)
+      const webResponse = wrapper
+        ? await wrapper(() => handler(webRequest))
+        : await handler(webRequest);
 
       // Compress the response if the client supports it.
       // In dev mode, compression is always enabled for parity with production.
@@ -317,6 +358,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 +377,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 '../plugin-context.js';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -34,6 +34,7 @@ const VIRTUAL_IDS = {
   browserEntry: 'virtual:timber-browser-entry',
   config: 'virtual:timber-config',
   instrumentation: 'virtual:timber-instrumentation',
+  cacheHandler: 'virtual:timber-cache-handler',
 } as const;
 
 /**
@@ -48,7 +49,7 @@ const VIRTUAL_IDS = {
 const ENTRY_FILE_MAP: Record<string, string> = {
   [VIRTUAL_IDS.rscEntry]: resolve(SRC_DIR, 'server', 'rsc-entry', 'index.ts'),
   [VIRTUAL_IDS.ssrEntry]: resolve(SRC_DIR, 'server', 'ssr-entry.ts'),
-  [VIRTUAL_IDS.browserEntry]: resolve(SRC_DIR, 'client', 'browser-entry.ts'),
+  [VIRTUAL_IDS.browserEntry]: resolve(SRC_DIR, 'client', 'browser-entry', 'index.ts'),
 };
 
 /** The \0-prefixed resolved ID for virtual:timber-config */
@@ -57,6 +58,9 @@ const RESOLVED_CONFIG_ID = `\0${VIRTUAL_IDS.config}`;
 /** The \0-prefixed resolved ID for virtual:timber-instrumentation */
 const RESOLVED_INSTRUMENTATION_ID = `\0${VIRTUAL_IDS.instrumentation}`;
 
+/** The \0-prefixed resolved ID for virtual:timber-cache-handler */
+const RESOLVED_CACHE_HANDLER_ID = `\0${VIRTUAL_IDS.cacheHandler}`;
+
 /**
  * Strip the \0 prefix from a module ID.
  *
@@ -95,11 +99,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,11 +107,16 @@ 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,
-    fontCssUrl: ctx.fontCssUrl ?? null,
+    serverTiming: ctx.config.serverTiming,
+    renderTimeoutMs: ctx.config.renderTimeoutMs ?? 30_000,
+    // Auto-generated sitemap config — opt-in via timber.config.ts.
+    // See design/16-metadata.md §"Auto-generated Sitemap"
+    sitemap: ctx.config.sitemap,
+    // 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 [
@@ -178,6 +182,53 @@ export function generateInstrumentationModule(instrumentationPath: string | null
   ].join('\n');
 }
 
+/**
+ * Detect the user's timber.config file at the project root.
+ * Returns the absolute path or null if not found.
+ */
+function detectConfigFile(root: string): string | null {
+  const names = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+  for (const name of names) {
+    const candidate = resolve(root, name);
+    if (existsSync(candidate)) return candidate;
+  }
+  return null;
+}
+
+/**
+ * Generate the virtual:timber-cache-handler module source.
+ *
+ * When the user's config has a cacheHandler, generates a module that
+ * dynamically imports the config file and extracts the cacheHandler.
+ * The cacheHandler is a class instance (e.g. RedisCacheHandler) that
+ * cannot be JSON-serialized into virtual:timber-config, so it must
+ * be loaded at runtime via dynamic import. See TIM-599.
+ */
+function generateCacheHandlerModule(configPath: string | null, hasCacheHandler: boolean): string {
+  if (configPath && hasCacheHandler) {
+    return [
+      '// Auto-generated cache handler loader — do not edit.',
+      '// Generated by timber-entries plugin.',
+      '',
+      `export default async function loadCacheHandler() {`,
+      `  const mod = await import(${JSON.stringify(configPath)});`,
+      `  const config = mod.default ?? mod;`,
+      `  return config.cacheHandler ?? null;`,
+      `}`,
+    ].join('\n');
+  }
+
+  return [
+    '// Auto-generated cache handler loader — do not edit.',
+    '// Generated by timber-entries plugin.',
+    '// No cacheHandler configured in timber.config.',
+    '',
+    `export default async function loadCacheHandler() {`,
+    `  return null;`,
+    `}`,
+  ].join('\n');
+}
+
 /**
  * Create the timber-entries Vite plugin.
  *
@@ -220,6 +271,11 @@ export function timberEntries(ctx: PluginContext): Plugin {
         return RESOLVED_INSTRUMENTATION_ID;
       }
 
+      // Check cache handler virtual module
+      if (cleanId === VIRTUAL_IDS.cacheHandler) {
+        return RESOLVED_CACHE_HANDLER_ID;
+      }
+
       return null;
     },
 
@@ -237,6 +293,11 @@ export function timberEntries(ctx: PluginContext): Plugin {
         const instrumentationPath = detectInstrumentationFile(ctx.root);
         return generateInstrumentationModule(instrumentationPath);
       }
+      if (id === RESOLVED_CACHE_HANDLER_ID) {
+        const configPath = detectConfigFile(ctx.root);
+        const hasCacheHandler = ctx.config.cacheHandler != null;
+        return generateCacheHandlerModule(configPath, hasCacheHandler);
+      }
       return null;
     },