@timber-js/app 0.2.0-alpha.71 → 0.2.0-alpha.72

package/src/index.ts

@@ -1,5 +1,16 @@
+/**
+ * @timber-js/app — Root entry point (public API).
+ *
+ * User-facing exports: timber(), defineConfig(), TimberUserConfig, Routes.
+ *
+ * Internal helpers (PluginContext, resolveAppDir, loadTimberConfigFile,
+ * warnConfigConflicts, resolveClientJavascript) live in plugin-context.ts
+ * and are NOT re-exported here. Sub-plugins import them via relative paths.
+ *
+ * Design doc: 18-build-system.md §"Plugin Architecture"
+ */
+
 import type { Plugin, PluginOption } from 'vite';
-import { existsSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { createRequire } from 'node:module';
 import react, { reactCompilerPreset } from '@vitejs/plugin-react';
@@ -21,401 +32,59 @@ import { clientChunkGroup } from './plugins/client-chunks';
 import { timberServerBundle } from './plugins/server-bundle';
 import { timberAdapterBuild } from './plugins/adapter-build';
 import { timberBuildReport } from './plugins/build-report';
-import type { RouteTree } from './routing/types';
-import type { BuildManifest } from './server/build-manifest';
-import type { StartupTimer } from './utils/startup-timer';
-import { createStartupTimer, createNoopTimer } from './utils/startup-timer';
+import { createNoopTimer } from './utils/startup-timer';
 import { resolveEncryptionKeyExpression, shouldEnableEncryption } from './server/action-encryption';
+import { createHoldingServer } from './server/dev-holding-server.js';
+import type { TimberUserConfig } from './config-types.js';
+import type { PluginContext } from './plugin-context.js';
+import {
+  createPluginContext,
+  loadTimberConfigFile,
+  mergeFileConfig,
+  resolveAppDir,
+  resolveClientJavascript,
+} from './plugin-context.js';
 
-/** 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;
-}
+// ── Public API ────────────────────────────────────────────────────────────
 
-/** Fully resolved client JavaScript configuration (no optionals). */
-export interface ResolvedClientJavascript {
-  disabled: boolean;
-  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;
-  };
-  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>;
-  };
-  /**
-   * Built-in top-loader progress bar for client navigations.
-   * Shows an animated bar at the top of the viewport during RSC navigations.
-   * Enabled by default — set `enabled: false` to opt out.
-   *
-   * Users who want a fully custom progress indicator should disable this
-   * and use `useNavigationPending()` directly.
-   *
-   * See LOCAL-336 for design decisions.
-   */
-  /**
-   * 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;
-  };
-  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;
-  };
-}
-
-/**
- * Resolve `clientJavascript` into a fully resolved config.
- */
-export function resolveClientJavascript(config: TimberUserConfig): ResolvedClientJavascript {
-  if (config.clientJavascript !== undefined) {
-    if (typeof config.clientJavascript === 'boolean') {
-      // `clientJavascript: false` → disabled
-      // `clientJavascript: true` → enabled (default)
-      return {
-        disabled: !config.clientJavascript,
-        enableHMRInDev: !config.clientJavascript, // default true when disabled
-      };
-    }
-    // Object form
-    return {
-      disabled: config.clientJavascript.disabled,
-      enableHMRInDev: config.clientJavascript.enableHMRInDev ?? config.clientJavascript.disabled,
-    };
-  }
-
-  // Default: client JS enabled
-  return { disabled: false, enableHMRInDev: false };
-}
+export type { TimberUserConfig } from './config-types.js';
 
 /**
- * Shared context object passed to all sub-plugins via closure.
+ * Route map interface — augmented by the generated timber-routes.d.ts.
  *
- * 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;
-}
-
-/**
- * Resolve the app directory. Checks (in order):
- * 1. Explicit `configAppDir` from timber.config.ts
- * 2. `<root>/app`
- * 3. `<root>/src/app`
+ * Each key is a route path pattern. Values have:
+ *   segmentParams: shape of URL segment params (e.g. { id: string })
+ *   searchParams: parsed type from search-params.ts, or {} if none
  *
- * Throws if none exist.
+ * This interface is empty by default and populated via codegen.
+ * See design/09-typescript.md §"Typed Routes".
  */
-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.`
-  );
-}
-
-function createPluginContext(config?: TimberUserConfig, root?: string): PluginContext {
-  const projectRoot = root ?? process.cwd();
-  // Don't apply defaults here — they would override file-based config
-  // during mergeFileConfig (inline spreads over file). Defaults are
-  // applied after merge in timber(). See TIM-451.
-  const resolvedConfig: TimberUserConfig = { ...config };
-  // Timer starts as active — swapped to noop in configResolved for production builds
-  return {
-    config: resolvedConfig,
-    clientJavascript: resolveClientJavascript(resolvedConfig),
-    routeTree: null,
-    appDir: join(projectRoot, 'app'),
-    root: projectRoot,
-    dev: false,
-    buildManifest: null,
-    deploymentId: null,
-    timer: createStartupTimer(),
-  };
-}
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface Routes {}
 
 /**
- * Load timber.config.ts (or .js, .mjs) from the project root.
- * Returns the config object or null if no config file is found.
+ * Type-safe helper for timber.config.ts files.
  *
- * 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.
+ * A pass-through identity function that provides autocomplete and
+ * type checking for timber configuration. No runtime validation —
+ * purely a DX convenience (same pattern as Vite's defineConfig).
+ *
+ * @example
+ * ```ts
+ * // timber.config.ts
+ * import { defineConfig } from '@timber-js/app';
  *
- * Returns the list of conflicting key names (for testing).
+ * export default defineConfig({
+ *   output: 'server',
+ *   pageExtensions: ['tsx', 'ts', 'mdx'],
+ * });
+ * ```
  */
-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;
+export function defineConfig(config: TimberUserConfig): TimberUserConfig {
+  return config;
 }
 
-/**
- * Merge file-based config into ctx.config. Inline config (already in ctx.config)
- * takes precedence — file config only fills in missing fields.
- */
-function mergeFileConfig(ctx: PluginContext, fileConfig: TimberUserConfig): void {
-  const inline = ctx.config;
-
-  // Warn if the same key is set in both places
-  warnConfigConflicts(inline, fileConfig);
-
-  // For each top-level key, use inline value if present, otherwise file value
-  ctx.config = {
-    ...fileConfig,
-    ...inline,
-    // Deep merge for nested objects where both exist
-    ...(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 } } : {}),
-  };
-}
+// ── Private helpers ───────────────────────────────────────────────────────
 
 /**
  * Resolve the React Compiler plugin via @rolldown/plugin-babel.
@@ -507,6 +176,8 @@ function createRscOptions(
 // The timber.cache() API (createCache) remains available for explicit caching.
 // See design/06-caching.md.
 
+// ── Main plugin factory ──────────────────────────────────────────────────
+
 /**
  * Create the timber Vite plugin array.
  *
@@ -605,6 +276,38 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
       // We explicitly set `oxc.jsx.development: false` for builds so
       // the client bundle always uses jsx/jsxs from react/jsx-runtime,
       // regardless of the ambient NODE_ENV value.
+      // ── Start holding server for dev mode ───────────────────────
+      // Bind the port immediately so browsers see a loading page
+      // instead of ERR_CONNECTION_REFUSED during the ~6-8s startup.
+      // The holding server is closed in timber-dev-server's
+      // configureServer hook (the last plugin), right before Vite
+      // calls server.listen().
+      // See design/21-dev-server.md §"Startup Holding Server", TIM-665.
+      if (command === 'serve') {
+        const port = (userConfig.server?.port as number) ?? 5173;
+        try {
+          ctx.holdingServer = createHoldingServer();
+          // listen() is async but we fire-and-forget — the server
+          // starts binding immediately and will be ready well before
+          // any browser request arrives. We can't await here because
+          // config() must return synchronously.
+          ctx.holdingServer.listen(port).then(
+            (boundPort) => {
+              const url = `http://localhost:${boundPort}`;
+              console.log(
+                `\n  \x1b[2m🪵 timber.js dev server starting at\x1b[0m \x1b[36m${url}\x1b[0m\n`
+              );
+            },
+            () => {
+              // Port already in use — skip gracefully.
+              ctx.holdingServer = null;
+            }
+          );
+        } catch {
+          ctx.holdingServer = null;
+        }
+      }
+
       if (command === 'build') {
         return {
           oxc: {
@@ -691,39 +394,4 @@ export function timber(config?: TimberUserConfig): PluginOption[] {
   ];
 }
 
-/**
- * Route map interface — augmented by the generated timber-routes.d.ts.
- *
- * Each key is a route path pattern. Values have:
- *   segmentParams: shape of URL segment params (e.g. { id: string })
- *   searchParams: parsed type from search-params.ts, or {} if none
- *
- * This interface is empty by default and populated via codegen.
- * See design/09-typescript.md §"Typed Routes".
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-export interface Routes {}
-
-/**
- * Type-safe helper for timber.config.ts files.
- *
- * A pass-through identity function that provides autocomplete and
- * type checking for timber configuration. No runtime validation —
- * purely a DX convenience (same pattern as Vite's defineConfig).
- *
- * @example
- * ```ts
- * // timber.config.ts
- * import { defineConfig } from '@timber-js/app';
- *
- * export default defineConfig({
- *   output: 'server',
- *   pageExtensions: ['tsx', 'ts', 'mdx'],
- * });
- * ```
- */
-export function defineConfig(config: TimberUserConfig): TimberUserConfig {
-  return config;
-}
-
 export default timber;