@timber-js/app 0.2.0-alpha.13 → 0.2.0-alpha.132

package/src/params/codec-registry.ts

@@ -0,0 +1,34 @@
+/**
+ * Client-side registry for schema segment param codecs.
+ *
+ * The Link component uses codec `serialize` functions to convert typed
+ * segment param values back to URL-safe strings. Without this registry,
+ * Link falls back to `String(value)` — which works for simple types
+ * but breaks for custom codecs (e.g., Date → '2026-04-10').
+ *
+ * Populated at startup by the browser entry importing `virtual:timber-schema`.
+ * Also usable on the server (isomorphic).
+ *
+ * Design doc: design/41-global-params.md §"Link Component"
+ */
+
+import type { Codec } from '../codec.js';
+
+let _codecs: Record<string, Codec<unknown>> | null = null;
+
+/**
+ * Register the resolved schema codecs for use by Link's URL interpolation.
+ * Called once at startup from the browser entry or RSC entry.
+ * @internal
+ */
+export function setLinkCodecs(codecs: Record<string, Codec<unknown>> | null): void {
+  _codecs = codecs;
+}
+
+/**
+ * Look up a codec by bracket key (e.g. '[id]', '[...slug]').
+ * Returns undefined if no schema is registered or the key has no codec.
+ */
+export function getLinkCodec(bracketKey: string): Codec<unknown> | undefined {
+  return _codecs?.[bracketKey] ?? undefined;
+}

package/src/params/define-schema.ts

@@ -0,0 +1,114 @@
+/**
+ * defineSchema — global segment param schema definition.
+ *
+ * Identity function at runtime; the type information is what matters.
+ * The Vite plugin reads the schema at build time for codegen, and
+ * the pipeline reads it at runtime for coercion.
+ *
+ * Design doc: design/41-global-params.md
+ */
+
+import type { Codec, CatchAllCodec, OptionalCatchAllCodec } from '../codec.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
+// ---------------------------------------------------------------------------
+// Types
+// ---------------------------------------------------------------------------
+
+/**
+ * Infer the output type from a Codec, StandardSchemaV1, or nuqs parser.
+ *
+ * Used by codegen to reference schema types without hardcoding:
+ *   `InferCodecType<typeof schema.segmentParams['[year]']>`
+ */
+export type InferCodecType<V> =
+  V extends Codec<infer T>
+    ? T
+    : V extends StandardSchemaV1<infer T>
+      ? T
+      : V extends { parseServerSide: (value: string) => infer T }
+        ? T
+        : string;
+
+/** Acceptable codec value for segment params: a Codec or Standard Schema. */
+export type SegmentParamCodec = Codec<unknown> | StandardSchemaV1<unknown>;
+
+/** Codec constraint for catch-all segment keys (`[...name]`). */
+export type CatchAllParamCodec = CatchAllCodec<unknown> | StandardSchemaV1<readonly unknown[]>;
+
+/** Codec constraint for optional catch-all segment keys (`[[...name]]`). */
+export type OptionalCatchAllParamCodec =
+  | OptionalCatchAllCodec<unknown>
+  | StandardSchemaV1<readonly unknown[] | undefined>;
+
+/**
+ * Resolves the required codec type for a given bracket key pattern.
+ * - `[...name]`    → requires a catch-all codec
+ * - `[[...name]]`  → requires an optional catch-all codec
+ * - `[name]`       → accepts any segment param codec
+ */
+export type CodecForKey<K extends string> = K extends `[[...${string}]]`
+  ? OptionalCatchAllParamCodec
+  : K extends `[...${string}]`
+    ? CatchAllParamCodec
+    : SegmentParamCodec;
+
+/**
+ * Registry interface augmented by codegen with known filesystem bracket keys.
+ * When empty (no codegen yet), ValidDynamicSegmentKeys falls back to string.
+ */
+export interface ValidDynamicSegmentKeysRegistry {}
+
+/**
+ * Union of valid bracket keys for defineSchema.
+ * After codegen runs, this is the set of filesystem segment names.
+ * Before codegen (fresh project), accepts any string.
+ */
+export type ValidDynamicSegmentKeys = keyof ValidDynamicSegmentKeysRegistry extends never
+  ? string
+  : keyof ValidDynamicSegmentKeysRegistry & string;
+
+/** Configuration object for defineSchema. */
+export interface SchemaConfig<S extends Record<string, SegmentParamCodec>> {
+  segmentParams: S;
+}
+
+// ---------------------------------------------------------------------------
+// Factory
+// ---------------------------------------------------------------------------
+
+/**
+ * Define the global segment param schema.
+ *
+ * Each key uses the bracket syntax from the filesystem (`[id]`, `[...slug]`,
+ * `[[...slug]]`) mapped to a codec. This makes the relationship between
+ * filesystem segments and codecs visually obvious.
+ *
+ * A dynamic segment with no key here defaults to `string` at codegen time.
+ *
+ * ```ts
+ * // app/schema.ts
+ * import { defineSchema } from '@timber-js/app/params';
+ * import { codec } from '@timber-js/app/codec';
+ * import { z } from 'zod';
+ *
+ * export default defineSchema({
+ *   segmentParams: {
+ *     '[artistSlug]': codec.string,
+ *     '[year]': codec.integer,
+ *     '[id]': z.coerce.number().int(),
+ *   },
+ * });
+ * ```
+ */
+export function defineSchema<
+  S extends {
+    [K in keyof S]: K extends ValidDynamicSegmentKeys
+      ? K extends string
+        ? CodecForKey<K>
+        : SegmentParamCodec
+      : never;
+  },
+>(config: { segmentParams: S }): { segmentParams: S } {
+  return config;
+}

package/src/params/index.ts

@@ -0,0 +1,17 @@
+// @timber-js/app/params — Global segment param schema and typed accessors.
+//
+// This is the import path for defineSchema, InferCodecType, and
+// the future getSegmentParams/useSegmentParams with route narrowing.
+//
+// See design/41-global-params.md
+
+export { defineSchema } from './define-schema.js';
+export type {
+  InferCodecType,
+  SchemaConfig,
+  SegmentParamCodec,
+  ValidDynamicSegmentKeys,
+  ValidDynamicSegmentKeysRegistry,
+} from './define-schema.js';
+export { resolveSchemaCodecs, toBracketKey } from './resolve-schema.js';
+export { setLinkCodecs, getLinkCodec } from './codec-registry.js';

package/src/params/resolve-schema.ts

@@ -0,0 +1,116 @@
+/**
+ * Schema resolution — resolves the global schema's segmentParams into
+ * a runtime-ready codec map keyed by bracket name (e.g. '[id]').
+ *
+ * Bracket keys are preserved so that `[id]`, `[...id]`, and `[[...id]]`
+ * remain distinct entries. The coercion layer reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Design doc: design/41-global-params.md §Pipeline Integration
+ */
+
+import type { Codec } from '../codec.js';
+import { isCodec, isStandardSchema, validateSync } from '../schema-bridge.js';
+import type { StandardSchemaV1 } from '../schema-bridge.js';
+
+/**
+ * Wrap a Standard Schema into a Codec for route params.
+ * Parse throws on failure (invalid param → 404). Serialize returns string.
+ */
+function fromParamSchema<T>(fieldName: string, schema: StandardSchemaV1<T>): Codec<T> {
+  return {
+    parse(value: string | string[] | undefined): T {
+      const result = validateSync(schema, value);
+      if (!result.issues) {
+        return result.value;
+      }
+      const messages = result.issues.map((i) => i.message).join(', ');
+      throw new Error(`[timber] Param '${fieldName}' coercion failed: ${messages}`);
+    },
+    serialize(value: T): string | null {
+      if (value === null || value === undefined) return null;
+      if (Array.isArray(value)) return value.join('/');
+      return String(value);
+    },
+  };
+}
+
+/**
+ * Resolve a schema entry to a Codec. Accepts Codec<T> or StandardSchemaV1<T>.
+ */
+function resolveCodec(fieldName: string, value: unknown): Codec<unknown> {
+  if (isCodec(value)) return value;
+  if (isStandardSchema(value)) return fromParamSchema(fieldName, value);
+  throw new Error(`[timber] Schema field '${fieldName}' is not a valid codec or Standard Schema.`);
+}
+
+/**
+ * Reconstruct the bracket key for a segment from its type and param name.
+ * Used by the coercion layer to look up codecs in the bracket-keyed map.
+ *
+ * 'dynamic'          + 'id'   → '[id]'
+ * 'catch-all'        + 'slug' → '[...slug]'
+ * 'optional-catch-all' + 'slug' → '[[...slug]]'
+ */
+export function toBracketKey(segmentType: string, paramName: string): string {
+  switch (segmentType) {
+    case 'catch-all':
+      return `[...${paramName}]`;
+    case 'optional-catch-all':
+      return `[[...${paramName}]]`;
+    default:
+      return `[${paramName}]`;
+  }
+}
+
+const CATCH_ALL_RE = /^\[\.\.\..+\]$/;
+const OPTIONAL_CATCH_ALL_RE = /^\[\[\.\.\..+\]\]$/;
+
+function isCatchAllKey(key: string): boolean {
+  return CATCH_ALL_RE.test(key) || OPTIONAL_CATCH_ALL_RE.test(key);
+}
+
+function isOptionalCatchAllKey(key: string): boolean {
+  return OPTIONAL_CATCH_ALL_RE.test(key);
+}
+
+/**
+ * Resolve the global schema's segmentParams into a map of bracket-keyed
+ * param name → resolved Codec.
+ *
+ * Keys are preserved exactly as written in `app/schema.ts` so that
+ * `[id]`, `[...id]`, and `[[...id]]` remain distinct entries.
+ * The coercion layer in `param-coercion.ts` reconstructs bracket keys
+ * from matched segment metadata to look up the correct codec.
+ *
+ * Input:  { '[id]': z.coerce.number(), '[...slug]': codec.string }
+ * Output: { '[id]': Codec<number>, '[...slug]': Codec<string> }
+ */
+export function resolveSchemaCodecs(
+  segmentParams: Record<string, unknown>
+): Record<string, Codec<unknown>> {
+  const resolved: Record<string, Codec<unknown>> = Object.create(null);
+
+  for (const [bracketName, value] of Object.entries(segmentParams)) {
+    if (isCatchAllKey(bracketName) && isCodec(value) && !('__catchAll' in value)) {
+      throw new Error(
+        `[timber] Schema error: '${bracketName}' is a catch-all segment and requires an array codec ` +
+          `(e.g. codec.catchAll(codec.string)). Got a scalar codec.`
+      );
+    }
+    if (
+      isOptionalCatchAllKey(bracketName) &&
+      isCodec(value) &&
+      '__catchAll' in value &&
+      !('__optional' in value)
+    ) {
+      throw new Error(
+        `[timber] Schema error: '${bracketName}' is an optional catch-all segment and requires codec.optionalCatchAll() ` +
+          `(e.g. codec.optionalCatchAll(codec.string)). Got a non-optional catch-all codec.`
+      );
+    }
+    resolved[bracketName] = resolveCodec(bracketName, value);
+  }
+
+  return resolved;
+}

package/src/plugin-context.ts

@@ -0,0 +1,240 @@
+/**
+ * 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 './dev-tools/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;
+  /**
+   * Resolved absolute path to the build output directory.
+   *
+   * Defaults to `<root>/.timber/dist`. Can be overridden via
+   * `timber.config.ts` `buildDir` or Vite's `build.outDir`.
+   * Timber config takes precedence when both are set.
+   *
+   * Used by adapter-build and cli preview.
+   */
+  buildDir: string;
+}
+
+// ── 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,
+    buildDir: resolveBuildDir(projectRoot, resolvedConfig.buildDir),
+  };
+}
+
+// ── Build directory resolution ────────────────────────────────────────────
+
+/** Default build output directory (relative to root). */
+export const DEFAULT_BUILD_DIR = join('.timber', 'dist');
+
+/**
+ * Resolve the build output directory.
+ *
+ * Priority:
+ * 1. Explicit `timberBuildDir` from timber.config.ts
+ * 2. Explicit `viteBuildOutDir` from Vite's build.outDir (if not the default 'dist')
+ * 3. Default: `.timber/dist`
+ *
+ * Returns an absolute path.
+ */
+export function resolveBuildDir(
+  root: string,
+  timberBuildDir?: string,
+  viteBuildOutDir?: string
+): string {
+  if (timberBuildDir) {
+    return join(root, timberBuildDir);
+  }
+  if (viteBuildOutDir && viteBuildOutDir !== 'dist') {
+    return join(root, viteBuildOutDir);
+  }
+  return join(root, DEFAULT_BUILD_DIR);
+}
+
+// ── 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,9 @@
 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';
+import { swallow } from '../server/logger.js';
 
 export function timberAdapterBuild(ctx: PluginContext): Plugin {
   return {
@@ -35,7 +36,7 @@ export function timberAdapterBuild(ctx: PluginContext): Plugin {
         const adapter = ctx.config.adapter as TimberPlatformAdapter | undefined;
         if (!adapter || typeof adapter.buildOutput !== 'function') return;
 
-        const buildDir = join(ctx.root, 'dist');
+        const buildDir = ctx.buildDir;
 
         // Serialize the build manifest as a JS module that sets the global.
         // The adapter writes this as _timber-manifest-init.mjs and imports it
@@ -50,6 +51,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
@@ -97,7 +104,8 @@ async function stripJsFromRscAssetsManifests(buildDir: string): Promise<void> {
     let manifest: Record<string, unknown>;
     try {
       manifest = JSON.parse(jsonStr);
-    } catch {
+    } catch (err) {
+      swallow(err, `corrupted RSC assets manifest: ${path}`, { level: 'warn' });
       continue;
     }