@timber-js/app 0.1.1 → 0.1.2

package/src/plugins/cache-transform.ts

@@ -0,0 +1,199 @@
+import type { Plugin } from 'vite';
+import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
+
+/**
+ * Parse a cacheLife duration string to seconds.
+ * Supports: '30s', '5m', '1h', '2d', '1w', or a plain number (seconds).
+ */
+export function parseCacheLife(value: string | number): number {
+  if (typeof value === 'number') return value;
+
+  const match = value.match(/^(\d+)(s|m|h|d|w)$/);
+  if (!match) {
+    throw new Error(
+      `Invalid cacheLife value: "${value}". Expected format: "30s", "5m", "1h", "2d", "1w", or a number.`
+    );
+  }
+
+  const amount = parseInt(match[1], 10);
+  const unit = match[2];
+  const multipliers: Record<string, number> = { s: 1, m: 60, h: 3600, d: 86400, w: 604800 };
+  return amount * multipliers[unit];
+}
+
+// Default TTL when no cacheLife() is specified (Infinity means cache until explicit invalidation).
+const DEFAULT_TTL = Infinity;
+
+export interface CacheTransformWarning {
+  message: string;
+  functionName: string;
+}
+
+interface TransformResult {
+  code: string;
+  map?: null;
+  warnings?: CacheTransformWarning[];
+}
+
+/**
+ * Match cacheLife() calls: cacheLife('1h'), cacheLife("5m"), cacheLife(300)
+ */
+const CACHE_LIFE_PATTERN = /cacheLife\(\s*(?:'([^']+)'|"([^"]+)"|(\d+))\s*\)/;
+
+/**
+ * Strip the 'use cache' directive and cacheLife() call from a function body.
+ * Returns the cleaned body and the extracted TTL.
+ */
+function extractCacheDirectives(body: string): { cleanBody: string; ttl: number } {
+  let ttl = DEFAULT_TTL;
+
+  // Remove 'use cache' / "use cache" directive (including optional semicolon and newline)
+  let cleanBody = body.replace(/\s*['"]use cache['"];?\s*\n?/, '\n');
+
+  // Extract and remove cacheLife() calls
+  const lifeMatch = cleanBody.match(CACHE_LIFE_PATTERN);
+  if (lifeMatch) {
+    const value = lifeMatch[1] || lifeMatch[2] || parseInt(lifeMatch[3], 10);
+    ttl = parseCacheLife(value);
+    cleanBody = cleanBody.replace(/\s*cacheLife\([^)]*\);?\s*\n?/, '\n');
+  }
+
+  return { cleanBody, ttl };
+}
+
+/**
+ * Determine if a function name is a React component (PascalCase).
+ */
+function isComponentName(name: string): boolean {
+  return /^[A-Z]/.test(name);
+}
+
+/**
+ * Pattern matching page/layout file conventions in a dynamic route segment.
+ * Matches paths like: app/[slug]/page.tsx, app/[id]/layout.ts, etc.
+ */
+const DYNAMIC_ROUTE_PAGE_PATTERN = /\/\[[^\]]+\].*\/(page|layout)\.[jt]sx?$/;
+
+/**
+ * Detect if a function declaration has Promise-typed parameters.
+ *
+ * Checks for common patterns:
+ * - `params: Promise<...>`
+ * - `{ params }: { params: Promise<...> }`
+ * - `props: { params: Promise<...> }`
+ */
+const PROMISE_PARAMS_PATTERN = /params\s*(?::|.*?:)\s*Promise\s*</;
+
+/**
+ * Check if a 'use cache' function in a dynamic route page/layout receives
+ * Promise-typed params, which are not serializable as cache keys.
+ */
+export function detectPromiseParamsWarning(
+  declaration: string,
+  functionName: string,
+  fileId: string
+): CacheTransformWarning | null {
+  if (!DYNAMIC_ROUTE_PAGE_PATTERN.test(fileId)) return null;
+  if (!PROMISE_PARAMS_PATTERN.test(declaration)) return null;
+
+  return {
+    message:
+      `'use cache' on "${functionName}" in "${fileId}" receives Promise params. ` +
+      `Promise is not serializable as a cache key and will cause runtime errors. ` +
+      `Either remove 'use cache' or await the params before using them in a separate cached function.`,
+    functionName,
+  };
+}
+
+/**
+ * Transform source code containing 'use cache' directives into
+ * registerCachedFunction() calls.
+ *
+ * Returns null if no transformations were made.
+ */
+export function transformUseCache(code: string, fileId: string): TransformResult | null {
+  if (!containsDirective(code, 'use cache')) return null;
+
+  const functions = findFunctionsWithDirective(code, 'use cache');
+  if (functions.length === 0) return null;
+
+  let result = code;
+  let needsImport = false;
+  const warnings: CacheTransformWarning[] = [];
+
+  // Process functions from end to start (sorted descending by start position)
+  for (const fn of functions) {
+    // Warn if function receives Promise params in a dynamic route page/layout
+    const promiseWarning = detectPromiseParamsWarning(fn.declaration, fn.name, fileId);
+    if (promiseWarning) warnings.push(promiseWarning);
+    const { cleanBody, ttl } = extractCacheDirectives(fn.bodyContent);
+    const stableId = `${fileId}#${fn.name}`;
+    const isComponent = isComponentName(fn.name);
+
+    // Build the options object
+    const optsParts = [`ttl: ${ttl === Infinity ? 'Infinity' : ttl}`];
+    optsParts.push(`id: '${stableId}'`);
+    if (isComponent) {
+      optsParts.push('isComponent: true');
+    }
+    const optsStr = `{ ${optsParts.join(', ')} }`;
+
+    // Build the replacement
+    let replacement: string;
+    if (fn.isArrow) {
+      // const Name = async (...) => { body } → const Name = registerCachedFunction(async (...) => { body }, opts)
+      const arrowSig = fn.declaration.replace(/^(?:const|let|var)\s+\w+\s*=\s*/, '');
+      replacement = `const ${fn.name} = registerCachedFunction(${arrowSig} {${cleanBody}}, ${optsStr})`;
+    } else {
+      // async function Name(...) { body } → const Name = registerCachedFunction(async function Name(...) { body }, opts)
+      const fnDecl = fn.declaration.replace(/^(?:export\s+default\s+|export\s+)?/, '');
+      const exportPrefix = fn.prefix.includes('default')
+        ? 'export default '
+        : fn.prefix.includes('export')
+          ? 'export '
+          : '';
+
+      replacement = `${exportPrefix}const ${fn.name} = registerCachedFunction(${fnDecl} {${cleanBody}}, ${optsStr})`;
+    }
+
+    result = result.slice(0, fn.start) + replacement + result.slice(fn.end);
+    needsImport = true;
+  }
+
+  if (needsImport) {
+    // Add the import at the top of the file
+    result = `import { registerCachedFunction } from '@timber/app/cache';\n` + result;
+  }
+
+  return { code: result, map: null, warnings: warnings.length > 0 ? warnings : undefined };
+}
+
+/**
+ * Vite plugin: timber-cache
+ *
+ * Transforms 'use cache' directives into registerCachedFunction() calls.
+ * Only runs in the RSC environment.
+ */
+export function cacheTransformPlugin(): Plugin {
+  return {
+    name: 'timber-cache',
+
+    transform(code, id) {
+      // Only transform in RSC environment
+      // Skip node_modules and non-JS/TS files
+      if (id.includes('node_modules')) return null;
+      if (!/\.[jt]sx?$/.test(id)) return null;
+
+      // Quick bail-out: no 'use cache' directive in this file
+      if (!containsDirective(code, 'use cache')) return null;
+
+      const result = transformUseCache(code, id);
+      if (result?.warnings) {
+        for (const w of result.warnings) {
+          this.warn(`[timber] ${w.message}`);
+        }
+      }
+      return result;
+    },
+  };
+}

package/src/plugins/chunks.ts

@@ -0,0 +1,90 @@
+/**
+ * timber-chunks — Vite sub-plugin for intelligent client chunk splitting.
+ *
+ * Splits client bundles into cache tiers based on update frequency:
+ *
+ * Tier 1: vendor-react  — react, react-dom, scheduler (changes rarely)
+ * Tier 2: vendor-timber — timber runtime, RSC runtime (changes per framework update)
+ * Tier 3: [route]-*     — per-route app code (changes per deploy, handled by Vite defaults)
+ *
+ * Server environments (RSC, SSR) are left to Vite's default chunking since
+ * Cloudflare Workers load all code from a single deployment bundle with no
+ * benefit from cache-tier separation.
+ *
+ * Design docs: 27-chunking-strategy.md
+ */
+
+import type { Plugin } from 'vite';
+
+/**
+ * Categorize a module ID into a cache tier chunk name.
+ *
+ * Returns a chunk name for vendor modules, or undefined to let
+ * Rollup's default splitting handle app/route code.
+ */
+export function assignChunk(id: string): string | undefined {
+  // Tier 1: React ecosystem — changes on version bumps only
+  if (
+    id.includes('node_modules/react-dom') ||
+    id.includes('node_modules/react/') ||
+    id.includes('node_modules/scheduler')
+  ) {
+    return 'vendor-react';
+  }
+
+  // Tier 2: timber framework runtime — changes on framework updates
+  if (
+    id.includes('/timber-app/') ||
+    id.includes('react-server-dom') ||
+    id.includes('@vitejs/plugin-rsc')
+  ) {
+    return 'vendor-timber';
+  }
+
+  // Everything else: Rollup's default splitting (per-route chunks)
+}
+
+/**
+ * Group timber's internal 'use client' modules into the vendor-timber chunk.
+ *
+ * The RSC plugin creates separate entry points for each 'use client' module,
+ * which manualChunks can't merge. This function is passed as the RSC plugin's
+ * `clientChunks` callback to group timber internals into a single chunk.
+ * User and third-party client components are left to default per-route splitting.
+ */
+export function assignClientChunk(meta: {
+  id: string;
+  normalizedId: string;
+  serverChunk: string;
+}): string | undefined {
+  if (meta.id.includes('/timber-app/')) return 'vendor-timber';
+}
+
+/**
+ * Create the timber-chunks Vite plugin.
+ *
+ * Uses Vite's per-environment config to apply manualChunks only to
+ * the client build. The config hook runs before environments are
+ * created, so we use `environments.client` to target the client.
+ */
+export function timberChunks(): Plugin {
+  return {
+    name: 'timber-chunks',
+
+    config() {
+      return {
+        environments: {
+          client: {
+            build: {
+              rollupOptions: {
+                output: {
+                  manualChunks: assignChunk,
+                },
+              },
+            },
+          },
+        },
+      };
+    },
+  };
+}

package/src/plugins/content.ts

@@ -0,0 +1,136 @@
+/**
+ * timber-content — Vite sub-plugin for content collections.
+ *
+ * Wraps @content-collections/vite to provide content collection support.
+ * Activates only when a content-collections.ts config file exists at the
+ * project root.
+ *
+ * Design doc: 20-content-collections.md §"Content Collections"
+ */
+
+import type { Plugin } from 'vite';
+import { existsSync } from 'node:fs';
+import { join } from 'node:path';
+import type { PluginContext } from '#/index.js';
+
+const CONFIG_FILE_NAMES = [
+  'content-collections.ts',
+  'content-collections.js',
+  'content-collections.mts',
+  'content-collections.mjs',
+];
+
+/**
+ * Find the content-collections config file at the project root.
+ * Returns the filename (not full path) if found, otherwise undefined.
+ */
+function findConfigFile(root: string): string | undefined {
+  for (const name of CONFIG_FILE_NAMES) {
+    if (existsSync(join(root, name))) return name;
+  }
+  return undefined;
+}
+
+/**
+ * Create the timber-content Vite plugin.
+ *
+ * Delegates all content scanning, validation, code generation, and file watching
+ * to @content-collections/vite. This plugin only handles detection and activation.
+ */
+export function timberContent(ctx: PluginContext): Plugin {
+  let innerPlugin: Plugin | null = null;
+
+  async function activate(root: string): Promise<void> {
+    if (innerPlugin !== null) return;
+
+    const configFile = findConfigFile(root);
+    if (!configFile) return;
+
+    let createPlugin: ((options?: { configPath?: string }) => Plugin) | undefined;
+    try {
+      const mod = await import('@content-collections/vite');
+      createPlugin = (mod.default ?? mod) as typeof createPlugin;
+    } catch {
+      throw new Error(
+        [
+          '[timber] Content collections are enabled but @content-collections/vite is not installed.',
+          '',
+          'Install content-collections:',
+          '  pnpm add -D @content-collections/core @content-collections/vite',
+          '',
+          'For MDX content, also install:',
+          '  pnpm add -D @content-collections/mdx',
+          '',
+          'Content collections are activated because a content-collections.ts file exists.',
+        ].join('\n')
+      );
+    }
+
+    if (createPlugin) {
+      innerPlugin = createPlugin({ configPath: configFile });
+    }
+  }
+
+  return {
+    name: 'timber-content',
+
+    async config(config, env) {
+      const root = config.root ?? ctx.root;
+      ctx.timer.start('content-activate');
+      await activate(root);
+      ctx.timer.end('content-activate');
+      if (!innerPlugin) return;
+      if (typeof innerPlugin.config === 'function') {
+        return innerPlugin.config.call(this, config, env);
+      }
+    },
+
+    async configResolved(config) {
+      if (!innerPlugin) return;
+      if (typeof innerPlugin.configResolved === 'function') {
+        await (innerPlugin.configResolved as (...args: unknown[]) => unknown).call(this, config);
+      }
+    },
+
+    async buildStart(options) {
+      if (!innerPlugin) return;
+      if (typeof innerPlugin.buildStart === 'function') {
+        await (innerPlugin.buildStart as (...args: unknown[]) => unknown).call(this, options);
+      }
+    },
+
+    async resolveId(source: string, importer: string | undefined, options: unknown) {
+      if (!innerPlugin) return null;
+      if (typeof innerPlugin.resolveId === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (innerPlugin.resolveId as any).call(this, source, importer, options);
+      }
+      return null;
+    },
+
+    async load(id: string) {
+      if (!innerPlugin) return null;
+      if (typeof innerPlugin.load === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (innerPlugin.load as any).call(this, id);
+      }
+      return null;
+    },
+
+    async transform(code: string, id: string) {
+      if (!innerPlugin) return null;
+      if (typeof innerPlugin.transform === 'function') {
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        return (innerPlugin.transform as any).call(this, code, id);
+      }
+      return null;
+    },
+
+    async configureServer(server) {
+      if (!innerPlugin) return;
+      if (typeof innerPlugin.configureServer === 'function') {
+        await (innerPlugin.configureServer as (...args: unknown[]) => unknown).call(this, server);
+      }
+    },
+  };
+}

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

@@ -0,0 +1,230 @@
+/**
+ * Dev error overlay — formats and sends errors to Vite's browser overlay and stderr.
+ *
+ * Integrates with Vite's built-in error overlay (`server.ssrFixStacktrace` +
+ * `server.hot.send`) rather than implementing a custom overlay.
+ *
+ * Design doc: 21-dev-server.md §"Error Overlay"
+ */
+
+import type { ViteDevServer } from 'vite';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+/** The phase of the pipeline where the error occurred. */
+export type ErrorPhase =
+  | 'module-transform'
+  | 'proxy'
+  | 'middleware'
+  | 'access'
+  | 'render'
+  | 'handler';
+
+/** Labels for terminal output. */
+const PHASE_LABELS: Record<ErrorPhase, string> = {
+  'module-transform': 'Module Transform',
+  'proxy': 'Proxy',
+  'middleware': 'Middleware',
+  'access': 'Access Check',
+  'render': 'RSC Render',
+  'handler': 'Route Handler',
+};
+
+// ─── Frame Classification ───────────────────────────────────────────────────
+
+export type FrameType = 'app' | 'framework' | 'internal';
+
+/**
+ * Classify a stack frame line by origin.
+ *
+ * - 'app': user application code (in project root, not node_modules)
+ * - 'framework': timber-app internal code
+ * - 'internal': node_modules, Node.js internals
+ */
+export function classifyFrame(frameLine: string, projectRoot: string): FrameType {
+  // Strip leading whitespace and "at "
+  const trimmed = frameLine.trim();
+
+  if (trimmed.includes('packages/timber-app/')) return 'framework';
+  if (trimmed.includes('node_modules/')) return 'internal';
+  if (trimmed.startsWith('at node:') || trimmed.includes('(node:')) return 'internal';
+  if (trimmed.includes(projectRoot)) return 'app';
+
+  return 'internal';
+}
+
+// ─── Component Stack Extraction ─────────────────────────────────────────────
+
+/**
+ * Extract the React component stack from an error, if present.
+ * React attaches this as `componentStack` during renderToReadableStream errors.
+ */
+export function extractComponentStack(error: unknown): string | null {
+  if (
+    error &&
+    typeof error === 'object' &&
+    'componentStack' in error &&
+    typeof (error as Record<string, unknown>).componentStack === 'string'
+  ) {
+    return (error as Record<string, unknown>).componentStack as string;
+  }
+  return null;
+}
+
+// ─── First App Frame Parsing ────────────────────────────────────────────────
+
+interface SourceLocation {
+  file: string;
+  line: number;
+  column: number;
+}
+
+/**
+ * Parse the first application frame from a stack trace.
+ * Returns file/line/column for the overlay's `loc` field.
+ */
+export function parseFirstAppFrame(stack: string, projectRoot: string): SourceLocation | null {
+  const lines = stack.split('\n');
+  // Match patterns like:
+  //   at functionName (/absolute/path:line:column)
+  //   at /absolute/path:line:column
+  const parenRegex = /\(([^)]+):(\d+):(\d+)\)/;
+  const bareRegex = /at (\/[^:]+):(\d+):(\d+)/;
+
+  for (const line of lines) {
+    if (classifyFrame(line, projectRoot) !== 'app') continue;
+
+    const match = parenRegex.exec(line) ?? bareRegex.exec(line);
+    if (!match) continue;
+
+    const [, file, lineNum, col] = match;
+    if (file && lineNum && col) {
+      return { file, line: parseInt(lineNum, 10), column: parseInt(col, 10) };
+    }
+  }
+
+  return null;
+}
+
+// ─── Error Phase Classification ─────────────────────────────────────────────
+
+/**
+ * Classify the error phase by inspecting the error's stack trace.
+ * Falls back to 'render' if no specific phase can be determined.
+ */
+export function classifyErrorPhase(error: Error, projectRoot: string): ErrorPhase {
+  const stack = error.stack ?? '';
+
+  // Check for React component stack (render error)
+  if (extractComponentStack(error)) return 'render';
+
+  // Check for specific file patterns in app frames
+  const appRoot = projectRoot.replace(/\/$/, '');
+  if (stack.includes(`${appRoot}/app/`) || stack.includes('/app/')) {
+    if (stack.includes('/middleware.ts') || stack.includes('/middleware.js')) return 'middleware';
+    if (stack.includes('/access.ts') || stack.includes('/access.js')) return 'access';
+    if (stack.includes('/route.ts') || stack.includes('/route.js')) return 'handler';
+  }
+
+  return 'render';
+}
+
+// ─── Terminal Formatting ────────────────────────────────────────────────────
+
+// ANSI codes
+const RED = '\x1b[31m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+
+/**
+ * Format an error for terminal output.
+ *
+ * - Red for the error message and phase label
+ * - Dim for framework-internal frames
+ * - Normal for application frames
+ * - Separate section for component stack (if present)
+ */
+export function formatTerminalError(error: Error, phase: ErrorPhase, projectRoot: string): string {
+  const lines: string[] = [];
+
+  // Phase header + error message
+  lines.push(`${RED}${BOLD}[timber] ${PHASE_LABELS[phase]} Error${RESET}`);
+  lines.push(`${RED}${error.message}${RESET}`);
+  lines.push('');
+
+  // Component stack (if present)
+  const componentStack = extractComponentStack(error);
+  if (componentStack) {
+    lines.push(`${BOLD}Component Stack:${RESET}`);
+    for (const csLine of componentStack.trim().split('\n')) {
+      lines.push(`  ${csLine.trim()}`);
+    }
+    lines.push('');
+  }
+
+  // Stack trace with frame dimming
+  if (error.stack) {
+    lines.push(`${BOLD}Stack Trace:${RESET}`);
+    const stackLines = error.stack.split('\n').slice(1); // Skip the first line (message)
+    for (const stackLine of stackLines) {
+      const frameType = classifyFrame(stackLine, projectRoot);
+      if (frameType === 'app') {
+        lines.push(stackLine);
+      } else {
+        lines.push(`${DIM}${stackLine}${RESET}`);
+      }
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Overlay Integration ────────────────────────────────────────────────────
+
+/**
+ * Send an error to Vite's browser overlay and log it to stderr.
+ *
+ * Uses `server.ssrFixStacktrace()` to map stack traces back to source,
+ * then sends the error via `server.hot.send()` for the browser overlay.
+ *
+ * The dev server remains running — errors are handled, not fatal.
+ */
+export function sendErrorToOverlay(
+  server: ViteDevServer,
+  error: Error,
+  phase: ErrorPhase,
+  projectRoot: string
+): void {
+  // Fix stack trace to use source-mapped positions
+  server.ssrFixStacktrace(error);
+
+  // Log to stderr with frame dimming
+  const formatted = formatTerminalError(error, phase, projectRoot);
+  process.stderr.write(`${formatted}\n`);
+
+  // Build overlay payload
+  const loc = parseFirstAppFrame(error.stack ?? '', projectRoot);
+  const componentStack = extractComponentStack(error);
+
+  let message = error.message;
+  if (componentStack) {
+    message = `${error.message}\n\nComponent Stack:\n${componentStack.trim()}`;
+  }
+
+  // Send to browser via Vite's error overlay protocol
+  try {
+    server.hot.send({
+      type: 'error',
+      err: {
+        message,
+        stack: error.stack ?? '',
+        id: loc?.file,
+        plugin: `timber (${PHASE_LABELS[phase]})`,
+        loc: loc ? { file: loc.file, line: loc.line, column: loc.column } : undefined,
+      },
+    });
+  } catch {
+    // Overlay send must never crash the dev server
+  }
+}