@timber-js/app 0.2.0-alpha.1 → 0.2.0-alpha.100

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

@@ -1,230 +0,0 @@
-/**
- * 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
-  }
-}

package/src/plugins/dynamic-transform.ts

@@ -1,161 +0,0 @@
-/**
- * timber-dynamic-transform — Vite sub-plugin for 'use dynamic' directive.
- *
- * Detects `'use dynamic'` directives in server component function bodies
- * and transforms them into `markDynamic()` runtime calls. The directive
- * declares a dynamic boundary — the component and its subtree opt out of
- * the pre-rendered shell and render per-request.
- *
- * - In `output: 'static'` mode, `'use dynamic'` is a build error.
- * - In standard SSR routes (no prerender.ts), the directive is a no-op
- *   (everything is already per-request), but the transform still runs
- *   so the runtime can skip unnecessary work.
- *
- * Design doc: design/15-future-prerendering.md §"'use dynamic'"
- */
-
-import type { Plugin } from 'vite';
-import type { PluginContext } from '#/index.js';
-import { findFunctionsWithDirective, containsDirective } from '#/utils/directive-parser.js';
-
-// ---------------------------------------------------------------------------
-// Detection
-// ---------------------------------------------------------------------------
-
-/**
- * Quick check: does this source file contain 'use dynamic' anywhere?
- * Used as a fast bail-out before doing expensive AST parsing.
- */
-export function containsUseDynamic(code: string): boolean {
-  return containsDirective(code, 'use dynamic');
-}
-
-// ---------------------------------------------------------------------------
-// Transform
-// ---------------------------------------------------------------------------
-
-interface TransformResult {
-  code: string;
-  map?: null;
-}
-
-/**
- * Find function declarations/expressions containing 'use dynamic' and
- * transform them into markDynamic() calls.
- *
- * Input:
- * ```tsx
- * export default async function AddToCartButton({ productId }) {
- *   'use dynamic'
- *   const user = await getUser()
- *   return <button>Add to cart</button>
- * }
- * ```
- *
- * Output:
- * ```tsx
- * import { markDynamic as __markDynamic } from '@timber-js/app/runtime';
- * export default async function AddToCartButton({ productId }) {
- *   __markDynamic();
- *   const user = await getUser()
- *   return <button>Add to cart</button>
- * }
- * ```
- *
- * The markDynamic() call registers the component boundary as dynamic
- * at render time. The pre-render pass uses this to know which subtrees
- * to skip and leave as holes for per-request rendering.
- */
-export function transformUseDynamic(code: string): TransformResult | null {
-  if (!containsUseDynamic(code)) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use dynamic');
-  if (functions.length === 0) return null;
-
-  // Replace directive strings with __markDynamic() calls, processing
-  // from end to start to preserve source offsets
-  let result = code;
-  for (const fn of functions) {
-    // Replace the directive in the body content
-    const cleanBody = fn.bodyContent.replace(/['"]use dynamic['"];?/, '__markDynamic();');
-    // Reconstruct: replace the body content between braces
-    result = result.slice(0, fn.bodyStart) + cleanBody + result.slice(fn.bodyEnd);
-  }
-
-  // Add the import at the top
-  result = `import { markDynamic as __markDynamic } from '@timber-js/app/runtime';\n` + result;
-
-  return { code: result, map: null };
-}
-
-// ---------------------------------------------------------------------------
-// Static mode validation
-// ---------------------------------------------------------------------------
-
-/**
- * In `output: 'static'` mode, `'use dynamic'` is a build error.
- * Static mode renders everything at build time — there is no per-request
- * rendering to opt into.
- */
-export function validateNoDynamicInStaticMode(
-  code: string
-): { message: string; line?: number } | null {
-  if (!containsUseDynamic(code)) return null;
-
-  const functions = findFunctionsWithDirective(code, 'use dynamic');
-  if (functions.length === 0) return null;
-
-  return {
-    message:
-      `'use dynamic' cannot be used in static mode (output: 'static'). ` +
-      `Static mode renders all content at build time — there is no per-request rendering. ` +
-      `Remove the directive or switch to output: 'server'.`,
-    line: functions[functions.length - 1].directiveLine, // First occurrence (sorted descending)
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Vite Plugin
-// ---------------------------------------------------------------------------
-
-/**
- * Create the timber-dynamic-transform Vite plugin.
- *
- * In server mode: transforms 'use dynamic' into markDynamic() calls.
- * In static mode: rejects 'use dynamic' as a build error.
- */
-export function timberDynamicTransform(ctx: PluginContext): Plugin {
-  const isStatic = ctx.config.output === 'static';
-
-  return {
-    name: 'timber-dynamic-transform',
-
-    transform(code: string, id: string) {
-      // Skip node_modules
-      if (id.includes('node_modules')) return null;
-
-      // Only check files in the app directory
-      if (!id.includes('/app/') && !id.startsWith('app/')) return null;
-
-      // Only check JS/TS files
-      if (!/\.[jt]sx?$/.test(id)) return null;
-
-      // Quick bail-out
-      if (!containsUseDynamic(code)) return null;
-
-      // In static mode, 'use dynamic' is a build error
-      if (isStatic) {
-        const error = validateNoDynamicInStaticMode(code);
-        if (error) {
-          this.error(
-            `[timber] Static mode error in ${id}${error.line ? `:${error.line}` : ''}: ${error.message}`
-          );
-        }
-        return null;
-      }
-
-      // In server mode, transform the directive
-      return transformUseDynamic(code);
-    },
-  };
-}

package/src/search-params/analyze.ts

@@ -1,192 +0,0 @@
-/**
- * Static analyzability checker for search-params.ts files.
- *
- * Validates that a search-params.ts file's default export is statically
- * analyzable — a createSearchParams() call or a chain of .extend()/.pick()
- * calls on a SearchParamsDefinition.
- *
- * Non-analyzable files produce a hard build error with a diagnostic.
- *
- * Design doc: design/09-typescript.md §"Static Analyzability"
- */
-
-// ---------------------------------------------------------------------------
-// Types
-// ---------------------------------------------------------------------------
-
-/** Result of analyzing a search-params.ts file. */
-export interface AnalyzeResult {
-  /** Whether the file is statically analyzable. */
-  valid: boolean;
-  /** Error details when valid is false. */
-  error?: AnalyzeError;
-}
-
-/** Diagnostic error for non-analyzable search-params.ts. */
-export interface AnalyzeError {
-  /** Absolute file path. */
-  filePath: string;
-  /** Description of the non-analyzable expression. */
-  expression: string;
-  /** Suggested fix. */
-  suggestion: string;
-}
-
-// ---------------------------------------------------------------------------
-// AST-free source analysis
-//
-// We use a lightweight regex-based approach to validate the structure of the
-// default export. This avoids requiring a TypeScript compiler instance at
-// build time for the initial validation pass. The full type extraction
-// (reading T from SearchParamsDefinition<T>) still happens via the TypeScript
-// compiler in the codegen step — this module just validates the *shape*.
-// ---------------------------------------------------------------------------
-
-/**
- * Patterns that indicate a valid default export:
- *
- * 1. `export default createSearchParams(...)`
- * 2. `export default someVar.extend(...)`
- * 3. `export default someVar.pick(...)`
- * 4. `export default someVar.extend(...).extend(...)`  (chained)
- * 5. `export default someVar.extend(...).pick(...)`    (chained)
- * 6. `export default createSearchParams(...).extend(...)`
- *
- * Invalid patterns:
- * - `export default someFunction(...)` (arbitrary factory)
- * - `export default condition ? a : b` (runtime conditional)
- * - `export default variable` (opaque reference without call)
- */
-
-/**
- * Analyze a search-params.ts file source for static analyzability.
- *
- * @param source - The file content as a string
- * @param filePath - Absolute path to the file (for diagnostics)
- */
-export function analyzeSearchParams(source: string, filePath: string): AnalyzeResult {
-  // Strip comments to avoid false matches
-  const stripped = stripComments(source);
-
-  // Find the default export
-  const defaultExport = extractDefaultExport(stripped);
-
-  if (!defaultExport) {
-    return {
-      valid: false,
-      error: {
-        filePath,
-        expression: '(no default export found)',
-        suggestion:
-          'search-params.ts must have a default export. Use: export default createSearchParams({ ... })',
-      },
-    };
-  }
-
-  // Validate the expression
-  if (isValidExpression(defaultExport.trim())) {
-    return { valid: true };
-  }
-
-  return {
-    valid: false,
-    error: {
-      filePath,
-      expression: defaultExport.trim(),
-      suggestion:
-        'The default export must be a createSearchParams() call, or a chain of ' +
-        '.extend() / .pick() calls on a SearchParamsDefinition. Arbitrary factory ' +
-        'functions and runtime conditionals are not supported.',
-    },
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Internal helpers
-// ---------------------------------------------------------------------------
-
-/** Strip single-line and multi-line comments from source. */
-function stripComments(source: string): string {
-  // Remove multi-line comments
-  let result = source.replace(/\/\*[\s\S]*?\*\//g, '');
-  // Remove single-line comments
-  result = result.replace(/\/\/.*$/gm, '');
-  return result;
-}
-
-/**
- * Extract the expression from `export default <expr>`.
- *
- * Handles both:
- *   export default createSearchParams(...)
- *   export default expr\n (terminated by newline or semicolon before next statement)
- */
-function extractDefaultExport(source: string): string | undefined {
-  // Match `export default` followed by the expression
-  const match = source.match(
-    /export\s+default\s+([\s\S]+?)(?:;|\n(?=export|import|const|let|var|function|class|type|interface|declare))/
-  );
-  if (match) {
-    return match[1];
-  }
-
-  // Fallback: match everything after `export default` to end of file
-  const fallback = source.match(/export\s+default\s+([\s\S]+)$/);
-  if (fallback) {
-    return fallback[1].replace(/;\s*$/, '');
-  }
-
-  return undefined;
-}
-
-/**
- * Check if an expression is a valid statically-analyzable pattern.
- *
- * Valid patterns:
- * - Starts with `createSearchParams(`
- * - Contains `.extend(` or `.pick(` chains (possibly starting with createSearchParams or a variable)
- * - A variable identifier followed by chaining
- */
-function isValidExpression(expr: string): boolean {
-  // Normalize whitespace
-  const normalized = expr.replace(/\s+/g, ' ').trim();
-
-  // Pattern 1: starts with createSearchParams(
-  if (normalized.startsWith('createSearchParams(')) {
-    return true;
-  }
-
-  // Pattern 2: chain ending with .extend(...) or .pick(...)
-  // This covers: someVar.extend(...), createSearchParams(...).extend(...).pick(...), etc.
-  if (/\.(extend|pick)\s*\(/.test(normalized)) {
-    // Reject ternaries and other conditional patterns
-    if (/\?/.test(normalized) && /:/.test(normalized)) {
-      return false;
-    }
-    // Reject function declarations/expressions
-    if (/^\s*(function|=>|\()/.test(normalized)) {
-      return false;
-    }
-    return true;
-  }
-
-  return false;
-}
-
-/**
- * Format an AnalyzeError into a human-readable build error message.
- */
-export function formatAnalyzeError(error: AnalyzeError): string {
-  return [
-    `[timber] Non-analyzable search-params.ts`,
-    ``,
-    `  File: ${error.filePath}`,
-    `  Expression: ${error.expression}`,
-    ``,
-    `  ${error.suggestion}`,
-    ``,
-    `  The framework must be able to statically extract the type from your`,
-    `  search-params.ts at build time. Dynamic values, conditionals, and`,
-    `  arbitrary factory functions prevent this analysis.`,
-  ].join('\n');
-}