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

package/src/plugin-context.ts

@@ -0,0 +1,200 @@
+/**
+ * Plugin context — internal types and helpers for timber sub-plugins.
+ *
+ * These are NOT part of the user-facing API. They are consumed by
+ * sub-plugins (routing, entries, shims, etc.) via relative imports.
+ * The root entry point (index.ts) does not re-export them.
+ *
+ * Design doc: 18-build-system.md §"Shared Plugin Context"
+ */
+
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import { createRequire } from 'node:module';
+import type { RouteTree } from './routing/types';
+import type { BuildManifest } from './server/build-manifest';
+import type { StartupTimer } from './utils/startup-timer';
+import { createStartupTimer } from './utils/startup-timer';
+import type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+import type { HoldingServer } from './server/dev-holding-server.js';
+
+// Re-export for sub-plugin convenience — they import from plugin-context.ts
+export type { TimberUserConfig, ClientJavascriptConfig } from './config-types.js';
+
+// ── Client JavaScript config ─────────────────────────────────────────────
+
+/** Fully resolved client JavaScript configuration (no optionals). */
+export interface ResolvedClientJavascript {
+  disabled: boolean;
+  enableHMRInDev: boolean;
+}
+
+/**
+ * Resolve `clientJavascript` into a fully resolved config.
+ */
+export function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {
+  if (config.clientJavascript !== undefined) {
+    if (typeof config.clientJavascript === 'boolean') {
+      return {
+        disabled: !config.clientJavascript,
+        enableHMRInDev: !config.clientJavascript,
+      };
+    }
+    return {
+      disabled: config.clientJavascript.disabled,
+      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,
+    };
+  }
+  return { disabled: false, enableHMRInDev: false };
+}
+
+// ── Plugin Context ────────────────────────────────────────────────────────
+
+/**
+ * Shared context object passed to all sub-plugins via closure.
+ *
+ * Sub-plugins communicate through this context — not through Vite's
+ * plugin API or global state.
+ * See design/18-build-system.md §"Shared Plugin Context".
+ */
+export interface PluginContext {
+  config: TimberUserConfig;
+  /** Resolved client JavaScript configuration */
+  clientJavascript: ResolvedClientJavascript;
+  /** The scanned route tree (populated by timber-routing, consumed by timber-entries) */
+  routeTree: RouteTree | null;
+  /** Absolute path to the app/ directory */
+  appDir: string;
+  /** Absolute path to the project root */
+  root: string;
+  /** Whether the dev server is running (set by timber-root-sync in configResolved) */
+  dev: boolean;
+  /** CSS build manifest (populated by adapter after client build, null in dev) */
+  buildManifest: BuildManifest | null;
+  /** Per-build deployment ID for version skew detection (null in dev) */
+  deploymentId: string | null;
+  /** Startup timer for profiling cold start phases (active in dev, no-op in prod) */
+  timer: StartupTimer;
+  /** Holding server that binds the port during dev startup (closed in timber-dev-server) */
+  holdingServer?: HoldingServer | null;
+}
+
+// ── App directory resolution ──────────────────────────────────────────────
+
+/**
+ * Resolve the app directory. Checks (in order):
+ * 1. Explicit `configAppDir` from timber.config.ts
+ * 2. `<root>/app`
+ * 3. `<root>/src/app`
+ *
+ * Throws if none exist.
+ */
+export function resolveAppDir(root: string, configAppDir?: string): string {
+  if (configAppDir) {
+    const explicit = join(root, configAppDir);
+    if (!existsSync(explicit)) {
+      throw new Error(`[timber] Configured appDir "${configAppDir}" does not exist at ${explicit}`);
+    }
+    return explicit;
+  }
+
+  const rootApp = join(root, 'app');
+  if (existsSync(rootApp)) return rootApp;
+
+  const srcApp = join(root, 'src', 'app');
+  if (existsSync(srcApp)) return srcApp;
+
+  throw new Error(
+    `[timber] Could not find app directory. Expected "app/" or "src/app/" in ${root}. ` +
+      `You can set appDir in timber.config.ts to specify a custom location.`
+  );
+}
+
+// ── Plugin context factory ────────────────────────────────────────────────
+
+export function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {
+  const projectRoot = root ?? process.cwd();
+  const resolvedConfig: TimberUserConfig = { ...config };
+  return {
+    config: resolvedConfig,
+    clientJavascript: resolveClientJavascript(resolvedConfig),
+    routeTree: null,
+    appDir: join(projectRoot, 'app'),
+    root: projectRoot,
+    dev: false,
+    buildManifest: null,
+    deploymentId: null,
+    timer: createStartupTimer(),
+    holdingServer: null,
+  };
+}
+
+// ── Config file loading ───────────────────────────────────────────────────
+
+/**
+ * Load timber.config.ts (or .js, .mjs) from the project root.
+ * Returns the config object or null if no config file is found.
+ *
+ * Uses require() which works for ESM modules on Node 22.12+.
+ * This keeps timber() synchronous — no async config loading needed.
+ */
+export function loadTimberConfigFile(root: string): TimberUserConfig | null {
+  const configNames = ['timber.config.ts', 'timber.config.js', 'timber.config.mjs'];
+  const req = createRequire(join(root, 'package.json'));
+
+  for (const name of configNames) {
+    const configPath = join(root, name);
+    if (existsSync(configPath)) {
+      const mod = req(configPath);
+      return (mod.default ?? mod) as TimberUserConfig;
+    }
+  }
+  return null;
+}
+
+/**
+ * Detect config keys set in both inline (vite.config.ts) and file (timber.config.ts)
+ * and warn the user. The `output` key is excluded because it defaults to 'server'
+ * in createPluginContext and would always appear as an inline key.
+ *
+ * Returns the list of conflicting key names (for testing).
+ */
+export function warnConfigConflicts(
+  inline: TimberUserConfig,
+  fileConfig: TimberUserConfig
+): string[] {
+  const conflicts: string[] = [];
+  for (const key of Object.keys(fileConfig) as (keyof TimberUserConfig)[]) {
+    if (key in inline && inline[key] !== undefined) {
+      conflicts.push(key);
+    }
+  }
+  if (conflicts.length > 0) {
+    console.warn(
+      `[timber] Config conflict: ${conflicts.map((k) => `"${k}"`).join(', ')} set in both ` +
+        `vite.config.ts (inline) and timber.config.ts. ` +
+        `Move all config to timber.config.ts to avoid confusion. ` +
+        `The inline value from vite.config.ts will be used.`
+    );
+  }
+  return conflicts;
+}
+
+/**
+ * Merge file-based config into ctx.config. Inline config (already in ctx.config)
+ * takes precedence — file config only fills in missing fields.
+ */
+export function mergeFileConfig(ctx: PluginContext, fileConfig: TimberUserConfig): void {
+  const inline = ctx.config;
+  warnConfigConflicts(inline, fileConfig);
+
+  ctx.config = {
+    ...fileConfig,
+    ...inline,
+    ...(fileConfig.limits && inline.limits
+      ? { limits: { ...fileConfig.limits, ...inline.limits } }
+      : {}),
+    ...(fileConfig.dev && inline.dev ? { dev: { ...fileConfig.dev, ...inline.dev } } : {}),
+    ...(fileConfig.mdx && inline.mdx ? { mdx: { ...fileConfig.mdx, ...inline.mdx } } : {}),
+  };
+}

package/src/plugins/adapter-build.ts

@@ -16,8 +16,8 @@
 import type { Plugin } from 'vite';
 import { join } from 'node:path';
 import { readFile, writeFile } from 'node:fs/promises';
-import type { PluginContext } from '#/index.js';
-import type { TimberPlatformAdapter, TimberConfig } from '#/adapters/types.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { TimberPlatformAdapter, TimberConfig } from '../adapters/types.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -50,6 +50,12 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
             : ctx.buildManifest;
           const json = JSON.stringify(manifest);
           manifestInit = `globalThis.__TIMBER_BUILD_MANIFEST__ = ${json};\n`;
+
+          // Embed the deployment ID for version skew detection (TIM-446).
+          // The server reads this at startup via setDeploymentId().
+          if (ctx.deploymentId) {
+            manifestInit += `globalThis.__TIMBER_DEPLOYMENT_ID__ = ${JSON.stringify(ctx.deploymentId)};\n`;
+          }
         }
 
         // Strip JS from the RSC plugin's assets manifest when client JS

package/src/plugins/build-manifest.ts

@@ -16,9 +16,10 @@
  * Design docs: 18-build-system.md §"Build Manifest", 02-rendering-pipeline.md §"Early Hints"
  */
 
+import { randomUUID } from 'node:crypto';
 import type { Plugin, ResolvedConfig } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { BuildManifest } from '#/server/build-manifest.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { BuildManifest } from '../server/build-manifest.js';
 
 // Rollup types used by generateBundle hook — imported from vite which re-exports them.
 // We define minimal interfaces here to avoid a direct 'rollup' dependency.
@@ -242,6 +243,16 @@ export function timberBuildManifest(ctx: PluginContext): Plugin {
     configResolved(config: ResolvedConfig) {
       resolvedBase = config.base;
       isDev = config.command === 'serve';
+
+      // Generate a per-build deployment ID early so virtual:timber-config
+      // can serialize it during the load hook (which runs before generateBundle).
+      // A random UUID is used instead of a content hash — determinism provides
+      // no real benefit here since you almost never redeploy identical code,
+      // and a random ID avoids the timing problem where the content hash was
+      // only available after generateBundle (TIM-452).
+      if (!isDev && !ctx.deploymentId) {
+        ctx.deploymentId = randomUUID().replace(/-/g, '').slice(0, 16);
+      }
     },
 
     resolveId(id: string) {

package/src/plugins/build-report.ts

@@ -15,9 +15,9 @@
 
 import { gzipSync } from 'node:zlib';
 import type { Plugin, Logger } from 'vite';
-import type { PluginContext } from '#/index.js';
-import type { SegmentNode, RouteTree } from '#/routing/types.js';
-import { formatSize } from '#/utils/format.js';
+import type { PluginContext } from '../plugin-context.js';
+import type { SegmentNode, RouteTree } from '../routing/types.js';
+import { formatSize } from '../utils/format.js';
 
 // ─── Public types ─────────────────────────────────────────────────────────
 

package/src/plugins/client-chunks.ts

@@ -0,0 +1,65 @@
+/**
+ * Client chunk grouping strategy for @vitejs/plugin-rsc.
+ *
+ * Groups client reference modules by layout boundary to balance route-scoped
+ * code splitting with HTTP request count. A constant group name would collapse
+ * all routes into one chunk (every page downloads every client component).
+ * Per-serverChunk grouping creates many sub-500B files. Layout-boundary
+ * grouping is the middle ground.
+ *
+ * See design/27-chunking-strategy.md, TIM-440, TIM-499.
+ */
+
+/**
+ * Derive a chunk group name for a client reference module.
+ *
+ * Groups by the first non-group route segment under appDir so that all
+ * client components belonging to the same layout boundary land in one
+ * chunk. For example:
+ *   - `facade:app/dashboard/settings/page.tsx` → `"client-dashboard"`
+ *   - `facade:app/(group-a)/group-page-a/page.tsx` → `"client-group-page-a"`
+ *   - `facade:app/layout.tsx` (root layout) → `"client-shared"`
+ *   - `shared:...` (shared across chunks) → `"client-shared"`
+ *
+ * This balances route-scoped code splitting with HTTP request count:
+ * fewer chunks than per-serverChunk, but still avoids downloading every
+ * client component on every page.
+ */
+export function clientChunkGroup(
+  meta: { id: string; normalizedId: string; serverChunk: string },
+  appDir: string
+): string {
+  const { normalizedId, serverChunk } = meta;
+
+  // Shared chunks (not associated with a single route entry) get one group.
+  if (serverChunk.startsWith('shared:')) return 'client-shared';
+
+  // Derive the layout boundary from the file's location relative to the
+  // app directory. normalizedId is root-relative (e.g. "app/dashboard/shell.tsx"
+  // or "src/app/dashboard/shell.tsx"). We find the "app/" prefix and walk
+  // segments after it to find the first non-group directory.
+  const relPath = normalizedId.replace(/\\/g, '/');
+
+  // Find the app directory boundary in the path. The last segment of appDir
+  // is the app folder name (usually "app").
+  const appDirName = appDir.replace(/\\/g, '/').split('/').pop() || 'app';
+  const appIdx = relPath.indexOf(appDirName + '/');
+  if (appIdx === -1) return 'client-shared';
+
+  const withinApp = relPath.slice(appIdx + appDirName.length + 1);
+  const segments = withinApp.split('/');
+
+  // Find first directory segment that isn't a route group like (group-a)
+  for (const seg of segments) {
+    // Skip the filename itself
+    if (seg.includes('.')) break;
+    // Skip route groups — parenthesized segments like (group-a)
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    // Found a real route segment
+    return `client-${seg}`;
+  }
+
+  // Root-level files (layout.tsx, page.tsx directly in app/) go into the
+  // shared group since the root layout is loaded on every page.
+  return 'client-shared';
+}

package/src/plugins/content.ts

@@ -11,7 +11,7 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const CONFIG_FILE_NAMES = [
   'content-collections.ts',

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

@@ -0,0 +1,288 @@
+/**
+ * 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 '../plugin-context.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') {
+        // Clear any stale script from a prior server instance (e.g. HMR reconfigure)
+        delete (globalThis as Record<string, unknown>).__timber_dev_browser_log_script;
+        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,
+        },
+      ];
+    },
+  };
+}