@timber-js/app 0.2.0-alpha.9 → 0.2.0-alpha.91

package/src/codec.ts

@@ -0,0 +1,49 @@
+/**
+ * @timber-js/app/codec — Shared codec protocol and Standard Schema bridge.
+ *
+ * The canonical import path for codec primitives shared across search params,
+ * route params, and cookies.
+ *
+ * Design doc: design/23a-search-params-triage.md §"Unify Codec<T> type"
+ */
+
+// ─── Codec protocol ──────────────────────────────────────────────────────
+
+/**
+ * A codec that converts between string values and typed values.
+ *
+ * The canonical protocol shared across search params, cookies, and
+ * any future timber feature that needs string ↔ typed conversion.
+ */
+export interface Codec<T> {
+  /** String → typed value. Receives undefined when the value is absent. */
+  parse(value: string | string[] | undefined): T;
+  /** Typed value → string. Return null to omit/clear. */
+  serialize(value: T): string | null;
+}
+
+/**
+ * Recursive JSON-serializable type. The canonical definition for data that
+ * can safely cross the RSC → client boundary.
+ *
+ * Previously exported from both @timber-js/app/server and @timber-js/app/client.
+ * Moved here so there is exactly one canonical import path.
+ */
+export type JsonSerializable =
+  | string
+  | number
+  | boolean
+  | null
+  | JsonSerializable[]
+  | { [key: string]: JsonSerializable };
+
+// ─── Standard Schema bridge ──────────────────────────────────────────────
+
+export {
+  fromSchema,
+  fromArraySchema,
+  validateSync,
+  isStandardSchema,
+  isCodec,
+} from './schema-bridge.js';
+export type { StandardSchemaV1, StandardSchemaResult } from './schema-bridge.js';

package/src/config-types.ts

@@ -0,0 +1,264 @@
+/**
+ * Timber configuration types.
+ *
+ * Extracted to a shared file so both the public entry point (index.ts)
+ * and internal plugin-context.ts can import them without circular deps.
+ */
+
+/** Configuration for client-side JavaScript output. */
+export interface ClientJavascriptConfig {
+  /** When true, no client JS bundles are emitted or referenced in HTML. */
+  disabled: boolean;
+  /**
+   * When `disabled` is true, still inject the Vite HMR client in dev mode
+   * so hot reloading works during development. Default: true.
+   */
+  enableHMRInDev?: boolean;
+}
+
+export interface TimberUserConfig {
+  output?: 'server' | 'static';
+  /**
+   * Enable timber debug logging in production builds.
+   *
+   * When `true`, timber's own diagnostics (dev warnings, verbose logging)
+   * are active even in production mode. React stays in production mode —
+   * only timber's logs are affected.
+   *
+   * Can also be enabled at runtime via the `TIMBER_DEBUG` environment variable.
+   *
+   * Default: `false`.
+   */
+  debug?: boolean;
+  /**
+   * Control client-side JavaScript output.
+   *
+   * Boolean shorthand:
+   *   `clientJavascript: false` disables all client JS (equivalent to `{ disabled: true }`).
+   *   `clientJavascript: true` enables client JS (the default).
+   *
+   * Object form:
+   *   `clientJavascript: { disabled: true, enableHMRInDev: true }` disables client JS
+   *   in production but preserves Vite HMR in dev mode.
+   *
+   * When `disabled` is true, `enableHMRInDev` defaults to `true`.
+   * Server-side JS still runs — this only affects what is sent to the browser.
+   */
+  clientJavascript?: boolean | ClientJavascriptConfig;
+  adapter?: unknown;
+  cacheHandler?: unknown;
+  allowedOrigins?: string[];
+  csrf?: boolean;
+  limits?: {
+    actionBodySize?: string;
+    uploadBodySize?: string;
+    maxFields?: number;
+  };
+  /**
+   * Server-action form handling.
+   *
+   * See design/08-forms-and-actions.md §"Validation errors" and
+   * design/13-security.md §"Sensitive field stripping".
+   */
+  forms?: {
+    /**
+     * Strip sensitive fields (passwords, tokens, CVV, SSN, etc.) from the
+     * `submittedValues` echoed back on validation failure.
+     *
+     * Applied to both the with-JS (`createActionClient`) and no-JS (form POST
+     * re-render) paths. Safe-by-default: the built-in deny-list is active
+     * unless you explicitly opt out.
+     *
+     * - `true` / omitted — use the built-in deny-list (default, recommended).
+     * - `false` — do not strip anything. Dev convenience only; never do this
+     *   in production — plaintext passwords end up in `defaultValue` attributes,
+     *   browser history, proxy logs, and the back-forward cache.
+     * - `string[]` — additional field names to strip, merged with the built-in list.
+     *
+     * The built-in list matches (case-insensitive, substring match on
+     * normalized names) the following patterns: password / passwd / pwd,
+     * secret, apiKey, accessToken, refreshToken, cvv, cvc, cardNumber,
+     * cardCvc, ssn, socialSecurityNumber, otp, totp, mfaCode, twoFactorCode,
+     * privateKey — plus exact match on `token` (exact-only to avoid
+     * false positives on `csrfToken`).
+     *
+     * **Function predicates are not supported at the global level** because
+     * `timber.config.ts` is JSON-serialized into the runtime config and
+     * functions cannot cross that boundary. For custom predicates, use
+     * the per-action override: `createActionClient({ stripSensitiveFields:
+     * (name) => ... })` (functions are supported at the per-action level
+     * since `createActionClient` runs in the same module graph as user code).
+     *
+     * See TIM-816.
+     */
+    stripSensitiveFields?: boolean | readonly string[];
+  };
+  pageExtensions?: string[];
+  /**
+   * Slow request threshold in milliseconds. Requests exceeding this emit
+   * a warning via the logger. Set to 0 to disable. Default: 3000.
+   *
+   * See design/17-logging.md §"slowRequestMs".
+   */
+  slowRequestMs?: number;
+  /**
+   * Render timeout in milliseconds. If an SSR render or RSC stream read
+   * does not complete within this duration, the render is aborted and
+   * the connection is closed. Protects against hung fetches and Suspense
+   * components that never resolve.
+   *
+   * Set to 0 to disable (not recommended in production).
+   * Default: 30000 (30 seconds).
+   *
+   * See design/02-rendering-pipeline.md §"Streaming Constraints".
+   */
+  renderTimeoutMs?: number;
+  /**
+   * Forward browser console output to the server terminal in dev mode.
+   *
+   * Sets the minimum log level to forward:
+   * - `'error'` — only `console.error`
+   * - `'warn'` — `console.error` + `console.warn` (default)
+   * - `'info'` — `console.error` + `console.warn` + `console.info`
+   * - `'none'` — disabled
+   *
+   * Does not intercept `console.log` or `console.debug` (too noisy).
+   * No effect in production builds.
+   *
+   * See TIM-513.
+   */
+  devBrowserLogs?: 'error' | 'warn' | 'info' | 'none';
+  /** Dev-mode options. These have no effect in production builds. */
+  dev?: {
+    /** Threshold in ms to highlight slow phases in dev logging output. Default: 200. */
+    slowPhaseMs?: number;
+  };
+  /**
+   * Control Server-Timing header output.
+   *
+   * - `'detailed'` — per-phase breakdown (proxy, middleware, render). Useful
+   *   for APM / network monitoring. Exposes phase names to clients.
+   * - `'total'` — single `total;dur=N` entry. Safe to expose, gives
+   *   browser DevTools useful timing without internal details.
+   * - `false` — no Server-Timing header at all.
+   *
+   * Default: `'detailed'` in dev, `'total'` in production.
+   *
+   * This is separate from `debug` / `TIMBER_DEBUG` — it's an intentional
+   * decision to expose timing data to clients, not a side effect of debug
+   * logging.
+   */
+  serverTiming?: 'detailed' | 'total' | false;
+  /**
+   * Override the app directory location. By default, timber auto-detects
+   * `app/` at the project root, falling back to `src/app/`.
+   *
+   * Set this to a relative path from the project root (e.g. `'src/app'`)
+   * to use a custom location.
+   */
+  appDir?: string;
+  /** MDX compilation options passed to @mdx-js/rollup. See design/20-content-collections.md. */
+  mdx?: {
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    recmaPlugins?: unknown[];
+    remarkRehypeOptions?: Record<string, unknown>;
+  };
+  /**
+   * Server action bound args encryption configuration.
+   *
+   * The RSC plugin encrypts closure variables captured by 'use server' functions
+   * using AES-256-GCM so they are opaque and tamper-proof in the Flight payload.
+   * Encryption is always enabled in production.
+   *
+   * The encryption key is auto-generated at build time and embedded in the server bundle,
+   * so all instances running the same build share the same key automatically.
+   * For rolling/blue-green deployments where multiple builds coexist, set
+   * `TIMBER_ACTIONS_ENCRYPTION_KEY` env var to share a key across builds.
+   *
+   * See design/08-forms-and-actions.md §"Security"
+   */
+  actionEncryption?: {
+    /**
+     * Disable encryption in dev mode for easier debugging of bound args.
+     * Has no effect in production — encryption is always enabled.
+     * Default: false (encryption is on in dev too).
+     */
+    disableInDev?: boolean;
+  };
+  /**
+   * Enable the React Compiler (babel-plugin-react-compiler) for automatic
+   * memoization of components and hooks at build time.
+   *
+   * - `true` — enable with default options
+   * - `{ compilationMode, target }` — enable with custom options
+   *   - `compilationMode: 'annotation'` — only compile files with `'use memo'`
+   *   - `target: '18'` — target React 18 (uses react-compiler-runtime package)
+   * - `false` or omitted — disabled (default)
+   *
+   * Uses `@vitejs/plugin-react`'s built-in `reactCompilerPreset`, which:
+   * - Applies Babel only for the compiler pass (OXC handles JSX)
+   * - Automatically scopes to client environment only
+   * - Uses `react/compiler-runtime` built into React 19
+   *
+   * Requires `babel-plugin-react-compiler` as a peer dependency.
+   */
+  reactCompiler?: boolean | { compilationMode?: string; target?: string };
+  /**
+   * Auto-generate sitemap.xml from the route tree.
+   *
+   * When enabled, timber walks the file-system route tree and produces a sitemap
+   * for all discoverable pages. Dynamic routes with `generateStaticParams()` are
+   * enumerated. Routes protected by `access.ts` are excluded by default.
+   *
+   * If a user-authored `sitemap.ts` or `sitemap.xml` exists at the app root,
+   * auto-generation is disabled — the user takes full control.
+   *
+   * Supports automatic pagination (sitemap index) for sites with > 50,000 URLs.
+   *
+   * See design/16-metadata.md §"Auto-generated Sitemap"
+   */
+  sitemap?: {
+    /** Must be explicitly `true` to enable auto-generation. Default: false. */
+    enabled?: boolean;
+    /** Base URL for absolute URLs in the sitemap. Required when enabled. e.g., 'https://example.com' */
+    baseUrl?: string;
+    /** Default `<changefreq>` for all entries. Optional. */
+    defaultChangeFrequency?: string;
+    /** Default `<priority>` for all entries (0.0–1.0). Optional. */
+    defaultPriority?: number;
+    /** Include routes protected by `access.ts`. Default: false. */
+    includeProtected?: boolean;
+  };
+  /**
+   * Override the build output directory.
+   *
+   * The resolved path is relative to the project root. Timber config
+   * takes precedence over Vite's `build.outDir`. If neither is set,
+   * defaults to `.timber/dist`.
+   *
+   * @example
+   * ```ts
+   * // timber.config.ts
+   * export default defineConfig({
+   *   buildDir: 'build',        // outputs to <root>/build/
+   *   buildDir: '.timber/dist', // default
+   * });
+   * ```
+   */
+  buildDir?: string;
+  topLoader?: {
+    /** Whether the top-loader is enabled. Default: true. */
+    enabled?: boolean;
+    /** Bar color. Default: '#2299DD'. */
+    color?: string;
+    /** Bar height in pixels. Default: 3. */
+    height?: number;
+    /** Show subtle glow/shadow effect. Default: true. */
+    shadow?: boolean;
+    /** Delay in ms before showing the bar (avoids flash on fast navs). Default: 0. */
+    delay?: number;
+    /** CSS z-index. Default: 1600. */
+    zIndex?: number;
+  };
+}

package/src/config-validation.ts

@@ -0,0 +1,303 @@
+/**
+ * Config validation — validates timber.config.ts at startup.
+ *
+ * Runs in the plugin's configResolved hook (once, at startup/build).
+ * Each check produces a clear error message with the invalid value,
+ * what's expected, and how to fix it.
+ *
+ * Design doc: 18-build-system.md
+ */
+
+import { createRequire } from 'node:module';
+import type { TimberUserConfig } from './config-types.js';
+
+// ─── Types ──────────────────────────────────────────────────────────────────
+
+export interface ConfigError {
+  field: string;
+  message: string;
+  value?: unknown;
+  suggestion?: string;
+}
+
+// ─── Validation ─────────────────────────────────────────────────────────────
+
+/**
+ * Validate a TimberUserConfig object.
+ *
+ * Returns an array of errors. Empty array means the config is valid.
+ * Does not throw — the caller decides how to surface errors.
+ */
+export function validateConfig(config: TimberUserConfig): ConfigError[] {
+  const errors: ConfigError[] = [];
+
+  // output
+  if (config.output !== undefined && config.output !== 'server' && config.output !== 'static') {
+    errors.push({
+      field: 'output',
+      message: `Invalid output mode: "${String(config.output)}". Must be "server" or "static".`,
+      value: config.output,
+      suggestion: 'Use output: "server" (default) or output: "static" for static site generation.',
+    });
+  }
+
+  // pageExtensions
+  if (config.pageExtensions !== undefined) {
+    if (!Array.isArray(config.pageExtensions)) {
+      errors.push({
+        field: 'pageExtensions',
+        message: 'pageExtensions must be an array of strings.',
+        value: config.pageExtensions,
+        suggestion: 'Example: pageExtensions: ["tsx", "ts", "jsx", "js", "mdx"]',
+      });
+    } else {
+      for (const ext of config.pageExtensions) {
+        if (typeof ext !== 'string') {
+          errors.push({
+            field: 'pageExtensions',
+            message: `pageExtensions contains a non-string value: ${JSON.stringify(ext)}`,
+            value: ext,
+          });
+          break;
+        }
+        if (ext.startsWith('.')) {
+          errors.push({
+            field: 'pageExtensions',
+            message: `pageExtensions should not include the leading dot: "${ext}"`,
+            value: ext,
+            suggestion: `Use "${ext.slice(1)}" instead of "${ext}".`,
+          });
+          break;
+        }
+      }
+    }
+  }
+
+  // slowRequestMs
+  if (config.slowRequestMs !== undefined) {
+    if (typeof config.slowRequestMs !== 'number' || config.slowRequestMs < 0) {
+      errors.push({
+        field: 'slowRequestMs',
+        message: `slowRequestMs must be a non-negative number (got ${JSON.stringify(config.slowRequestMs)}).`,
+        value: config.slowRequestMs,
+        suggestion: 'Use slowRequestMs: 3000 (default) or slowRequestMs: 0 to disable.',
+      });
+    }
+  }
+
+  // renderTimeoutMs
+  if (config.renderTimeoutMs !== undefined) {
+    if (typeof config.renderTimeoutMs !== 'number' || config.renderTimeoutMs < 0) {
+      errors.push({
+        field: 'renderTimeoutMs',
+        message: `renderTimeoutMs must be a non-negative number (got ${JSON.stringify(config.renderTimeoutMs)}).`,
+        value: config.renderTimeoutMs,
+        suggestion: 'Use renderTimeoutMs: 30000 (default) or renderTimeoutMs: 0 to disable.',
+      });
+    }
+  }
+
+  // serverTiming
+  if (config.serverTiming !== undefined) {
+    if (
+      config.serverTiming !== 'detailed' &&
+      config.serverTiming !== 'total' &&
+      config.serverTiming !== false
+    ) {
+      errors.push({
+        field: 'serverTiming',
+        message: `Invalid serverTiming value: ${JSON.stringify(config.serverTiming)}.`,
+        value: config.serverTiming,
+        suggestion: 'Use "detailed", "total", or false.',
+      });
+    }
+  }
+
+  // devBrowserLogs
+  if (config.devBrowserLogs !== undefined) {
+    const valid = ['error', 'warn', 'info', 'none'];
+    if (!valid.includes(config.devBrowserLogs)) {
+      errors.push({
+        field: 'devBrowserLogs',
+        message: `Invalid devBrowserLogs value: ${JSON.stringify(config.devBrowserLogs)}.`,
+        value: config.devBrowserLogs,
+        suggestion: `Use one of: ${valid.map((v) => `"${v}"`).join(', ')}.`,
+      });
+    }
+  }
+
+  // sitemap
+  if (config.sitemap != null && typeof config.sitemap === 'object') {
+    if (config.sitemap.enabled && !config.sitemap.baseUrl) {
+      errors.push({
+        field: 'sitemap.baseUrl',
+        message: 'sitemap.baseUrl is required when sitemap is enabled.',
+        suggestion: 'Add sitemap: { enabled: true, baseUrl: "https://example.com" }.',
+      });
+    }
+    if (
+      config.sitemap.defaultPriority !== undefined &&
+      (config.sitemap.defaultPriority < 0 || config.sitemap.defaultPriority > 1)
+    ) {
+      errors.push({
+        field: 'sitemap.defaultPriority',
+        message: `sitemap.defaultPriority must be between 0.0 and 1.0 (got ${config.sitemap.defaultPriority}).`,
+        value: config.sitemap.defaultPriority,
+      });
+    }
+  }
+
+  // Unknown top-level keys
+  const knownKeys = new Set([
+    'output',
+    'debug',
+    'clientJavascript',
+    'adapter',
+    'cacheHandler',
+    'allowedOrigins',
+    'csrf',
+    'limits',
+    'pageExtensions',
+    'slowRequestMs',
+    'renderTimeoutMs',
+    'devBrowserLogs',
+    'dev',
+    'serverTiming',
+    'appDir',
+    'mdx',
+    'actionEncryption',
+    'reactCompiler',
+    'sitemap',
+    'buildDir',
+    'topLoader',
+  ]);
+
+  for (const key of Object.keys(config)) {
+    if (!knownKeys.has(key)) {
+      errors.push({
+        field: key,
+        message: `Unknown config option: "${key}".`,
+        suggestion: `Check for typos. Known options: ${[...knownKeys].sort().join(', ')}.`,
+      });
+    }
+  }
+
+  return errors;
+}
+
+// ─── Formatting ─────────────────────────────────────────────────────────────
+
+const RED = '\x1b[31m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const RESET = '\x1b[0m';
+
+/**
+ * Format config errors for terminal output.
+ */
+export function formatConfigErrors(errors: ConfigError[]): string {
+  if (errors.length === 0) return '';
+
+  const lines: string[] = [];
+  lines.push(
+    `${RED}${BOLD}[timber]${RESET} ${RED}${errors.length} config error${errors.length !== 1 ? 's' : ''} in timber.config.ts:${RESET}`
+  );
+
+  for (const err of errors) {
+    lines.push('');
+    lines.push(`  ${RED}✗${RESET} ${BOLD}${err.field}${RESET}: ${err.message}`);
+    if (err.suggestion) {
+      lines.push(`    ${DIM}${err.suggestion}${RESET}`);
+    }
+  }
+
+  return lines.join('\n');
+}
+
+// ─── Virtual Module Name Mapping ────────────────────────────────────────────
+
+const VIRTUAL_MODULE_NAMES: Record<string, string> = {
+  'virtual:timber-rsc-entry': 'RSC entry (server component handler)',
+  'virtual:timber-ssr-entry': 'SSR entry (HTML renderer)',
+  'virtual:timber-browser-entry': 'Browser entry (client hydration)',
+  'virtual:timber-config': 'Runtime config (timber.config.ts)',
+  'virtual:timber-route-manifest': 'Route manifest (app/ file tree)',
+  'virtual:timber-instrumentation': 'Instrumentation (instrumentation.ts)',
+  'virtual:timber-cache-handler': 'Cache handler (cacheHandler config)',
+  'virtual:timber-build-manifest': 'Build manifest (asset mapping)',
+};
+
+/**
+ * Add timber-specific context to an error message that references virtual modules.
+ *
+ * If the error message contains a `virtual:timber-*` ID, appends a
+ * human-readable explanation. Does not replace the original message.
+ */
+export function addVirtualModuleContext(errorMessage: string): string {
+  for (const [id, name] of Object.entries(VIRTUAL_MODULE_NAMES)) {
+    if (errorMessage.includes(id)) {
+      return `${errorMessage}\n\n  [timber] This error references "${id}" — timber's ${name}.\n  This is an internal module. The issue is likely in your app code or timber configuration.`;
+    }
+  }
+  return errorMessage;
+}
+
+// ─── Peer Dependency Check ──────────────────────────────────────────────────
+
+interface PeerDepResult {
+  name: string;
+  status: 'ok' | 'missing';
+}
+
+/**
+ * Required (non-optional) peer dependencies that must be installed.
+ */
+const REQUIRED_PEERS = ['react', 'react-dom', '@vitejs/plugin-react', '@vitejs/plugin-rsc'];
+
+/**
+ * Check that required peer dependencies are installed.
+ *
+ * Uses require.resolve with a try/catch — no fs scanning.
+ * Returns only the missing packages.
+ */
+export function checkPeerDependencies(projectRoot: string): PeerDepResult[] {
+  const results: PeerDepResult[] = [];
+
+  // Use createRequire from the project root to resolve as the user would.
+  // `createRequire` MUST be a top-level ESM import — inline `require('node:module')`
+  // throws "Dynamic require not supported" in ESM and the catch below would
+  // mark every peer as missing. Same class of bug as TIM-796.
+  const userRequire = createRequire(`${projectRoot}/package.json`);
+
+  for (const name of REQUIRED_PEERS) {
+    try {
+      userRequire.resolve(name);
+      results.push({ name, status: 'ok' });
+    } catch {
+      results.push({ name, status: 'missing' });
+    }
+  }
+
+  return results;
+}
+
+/**
+ * Format missing peer dependencies as an actionable warning.
+ */
+export function formatMissingPeers(results: PeerDepResult[]): string {
+  const missing = results.filter((r) => r.status === 'missing');
+  if (missing.length === 0) return '';
+
+  const names = missing.map((r) => r.name);
+  const lines: string[] = [];
+  lines.push(`${RED}${BOLD}[timber]${RESET} ${RED}Missing required dependencies:${RESET}`);
+  lines.push('');
+  for (const name of names) {
+    lines.push(`  ${RED}✗${RESET} ${name}`);
+  }
+  lines.push('');
+  lines.push(`  ${DIM}Install with:${RESET}`);
+  lines.push(`  ${BOLD}pnpm add ${names.join(' ')}${RESET}`);
+
+  return lines.join('\n');
+}

package/src/content/index.ts

@@ -1,13 +1,5 @@
-/**
- * @timber-js/app/content — Public API for content collections.
- *
- * Re-exports from content-collections and provides timber-specific utilities.
- * Users can import directly from 'content-collections' for generated types,
- * or use this module for the re-exports.
- *
- * Design doc: 20-content-collections.md §"Querying Collections"
- */
-
-// Re-export defineCollection and defineConfig for convenience.
-// Users can also import these directly from @content-collections/core.
-export { defineCollection, defineConfig } from '@content-collections/core';
+// @timber-js/app/content entry point removed per TIM-722.
+//
+// Import defineCollection and defineConfig directly from @content-collections/core.
+// This file is kept for the content plugin which uses other files in this directory.
+export {};