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

package/src/plugins/entries.ts

@@ -15,7 +15,8 @@ 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.ts';
+import { resolveRenderTimeoutMs } from '../server/render-timeout.ts';
 
 const __dirname = dirname(fileURLToPath(import.meta.url));
 
@@ -34,6 +35,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,15 +50,25 @@ 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 real file behind virtual:timber-browser-entry. The client dep
+ * optimizer scans it explicitly once timber sets optimizeDeps.entries
+ * (see plugins/client-dep-entries.ts).
+ */
+export const BROWSER_ENTRY_FILE = ENTRY_FILE_MAP[VIRTUAL_IDS.browserEntry];
+
 /** The \0-prefixed resolved ID for virtual:timber-config */
 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.
  *
@@ -94,24 +106,77 @@ 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);
+/**
+ * Extract the JSON-serializable subset of `forms` config.
+ *
+ * Drops function-valued `stripSensitiveFields` with a build-time warning —
+ * functions cannot cross the JSON boundary to the runtime, so users must
+ * configure function predicates per-action via `createActionClient` instead.
+ */
+function serializeFormsConfig(
+  forms: { stripSensitiveFields?: unknown } | undefined
+): { stripSensitiveFields?: boolean | readonly string[] } | undefined {
+  if (!forms) return undefined;
+  const opt = forms.stripSensitiveFields;
+  if (opt === undefined) return {};
+  if (typeof opt === 'boolean') return { stripSensitiveFields: opt };
+  if (Array.isArray(opt)) {
+    // Coerce to a string array and drop any non-string entries.
+    const names = opt.filter((v): v is string => typeof v === 'string');
+    return { stripSensitiveFields: names };
+  }
+  if (typeof opt === 'function') {
+    console.warn(
+      '[timber] forms.stripSensitiveFields was set to a function in timber.config.ts — ' +
+        'this is not supported at the global level (functions cannot be serialized ' +
+        'into the runtime config). Use a per-action override via ' +
+        '`createActionClient({ stripSensitiveFields: (name) => ... })` instead. ' +
+        'The built-in deny-list will be used globally.'
+    );
+    return {};
+  }
+  return {};
+}
 
+function generateConfigModule(ctx: PluginContext): string {
   const runtimeConfig = {
     output: ctx.config.output ?? 'server',
     csrf: ctx.config.csrf ?? true,
     allowedOrigins: ctx.config.allowedOrigins,
     clientJavascript: ctx.clientJavascript,
+    // Vite's resolved `base` — the deployment path prefix. The client needs
+    // it to address pre-generated RSC payloads in static mode, which live
+    // below the base like every other emitted file (TIM-1261).
+    base: ctx.base,
     dev: ctx.dev ?? false,
     slowPhaseMs: ctx.config.dev?.slowPhaseMs ?? 200,
     slowRequestMs: ctx.config.slowRequestMs ?? 3000,
-    cookieSecrets,
     topLoader: ctx.config.topLoader,
     debug: ctx.config.debug ?? false,
     serverTiming: ctx.config.serverTiming,
+    renderTimeoutMs: resolveRenderTimeoutMs(ctx.config.renderTimeoutMs),
+    // Auto-generated sitemap config — opt-in via timber.config.ts.
+    // See design/16-metadata.md §"Auto-generated Sitemap"
+    sitemap: ctx.config.sitemap,
+    // Forms config — only the serializable subset. `stripSensitiveFields`
+    // accepts boolean | string[] at the global level. Functions must be
+    // configured per-action via `createActionClient({ stripSensitiveFields })`
+    // because JSON.stringify would silently drop them here. See TIM-816.
+    forms: serializeFormsConfig(ctx.config.forms),
+    // 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,
+    clientSegmentCache: ctx.config.clientSegmentCache ?? false,
+    cache: {
+      strictKeyDiscipline: ctx.config.cache?.strictKeyDiscipline ?? false,
+    },
+    // Browser log forwarding threshold — used by buildClientScripts to
+    // decide whether /@vite/client is needed when clientJavascript is
+    // disabled. See TIM-1152.
+    devBrowserLogs: ctx.config.devBrowserLogs,
+    // Note: project root is NOT included here — it was leaking server
+    // filesystem paths to client bundles (TIM-787). Dev error pages get
+    // the root through the dev server, not the runtime config.
   };
 
   return [
@@ -125,23 +190,39 @@ function generateConfigModule(ctx: PluginContext): string {
 }
 
 /**
- * Detect the user's instrumentation.ts file at the project root.
+ * Detect a user convention file at both root and src/.
  *
- * Checks for instrumentation.ts, .js, and .mjs — matching the same
- * extensions as timber.config.ts detection.
+ * Root takes precedence over src/, extension priority: .ts > .js > .mjs.
+ * Used for instrumentation.ts, timber.cache.ts, and similar file conventions.
  */
-export function detectInstrumentationFile(root: string): string | null {
+export function detectConventionFile(root: string, basename: string): string | null {
   const extensions = ['.ts', '.js', '.mjs'];
   const dirs = [root, resolve(root, 'src')];
   for (const dir of dirs) {
     for (const ext of extensions) {
-      const candidate = resolve(dir, `instrumentation${ext}`);
+      const candidate = resolve(dir, `${basename}${ext}`);
       if (existsSync(candidate)) return candidate;
     }
   }
   return null;
 }
 
+export function detectInstrumentationFile(root: string): string | null {
+  return detectConventionFile(root, 'instrumentation');
+}
+
+/**
+ * Detect the user's timber.cache file.
+ *
+ * This file holds runtime cache instances (cacheHandler, cdnPurge)
+ * that cannot be JSON-serialized. Separating them from timber.config.ts
+ * prevents the RSC build from pulling build-time deps (adapters, MDX,
+ * rollup) into the runtime bundle. See TIM-1211.
+ */
+export function detectCacheFile(root: string): string | null {
+  return detectConventionFile(root, 'timber.cache');
+}
+
 /**
  * Generate the virtual:timber-instrumentation module source.
  *
@@ -153,9 +234,6 @@ export function detectInstrumentationFile(root: string): string | null {
  */
 export function generateInstrumentationModule(instrumentationPath: string | null): string {
   if (instrumentationPath) {
-    // Use the absolute path so the bundler can resolve and include it.
-    // The dynamic import ensures the file is loaded lazily and errors
-    // in the user's code don't prevent the module from being parsed.
     return [
       '// Auto-generated instrumentation loader — do not edit.',
       '// Generated by timber-entries plugin.',
@@ -177,6 +255,52 @@ export function generateInstrumentationModule(instrumentationPath: string | null
   ].join('\n');
 }
 
+/**
+ * Generate the virtual:timber-cache-handler module source.
+ *
+ * When the user's timber.cache.ts exists, generates a module that
+ * dynamically imports it and extracts cacheHandler and cdnPurge.
+ * These are class instances (e.g. RedisCacheHandler) that cannot be
+ * JSON-serialized into virtual:timber-config, so they must be loaded
+ * at runtime via dynamic import.
+ *
+ * timber.cache.ts exports: default cacheHandler, named cdnPurge.
+ *
+ * See TIM-1211, TIM-599.
+ */
+export function generateCacheHandlerModule(cachePath: string | null): string {
+  if (cachePath) {
+    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(cachePath)});`,
+      `  return mod.default ?? null;`,
+      `}`,
+      '',
+      `export async function loadCdnPurgeHandler() {`,
+      `  const mod = await import(${JSON.stringify(cachePath)});`,
+      `  return mod.cdnPurge ?? null;`,
+      `}`,
+    ].join('\n');
+  }
+
+  return [
+    '// Auto-generated cache handler loader — do not edit.',
+    '// Generated by timber-entries plugin.',
+    '// No timber.cache.ts found.',
+    '',
+    `export default async function loadCacheHandler() {`,
+    `  return null;`,
+    `}`,
+    '',
+    `export async function loadCdnPurgeHandler() {`,
+    `  return null;`,
+    `}`,
+  ].join('\n');
+}
+
 /**
  * Create the timber-entries Vite plugin.
  *
@@ -219,6 +343,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;
     },
 
@@ -236,6 +365,10 @@ export function timberEntries(ctx: PluginContext): Plugin {
         const instrumentationPath = detectInstrumentationFile(ctx.root);
         return generateInstrumentationModule(instrumentationPath);
       }
+      if (id === RESOLVED_CACHE_HANDLER_ID) {
+        const cachePath = detectCacheFile(ctx.root);
+        return generateCacheHandlerModule(cachePath);
+      }
       return null;
     },