@timber-js/app 0.2.0-alpha.15 → 0.2.0-alpha.150

package/src/plugins/cache.ts

@@ -0,0 +1,285 @@
+/**
+ * timber-cache-transform — Vite plugin that injects stable callsite IDs
+ * into `cache()` calls imported from `@timber-js/app/cache`.
+ *
+ * Detected callsite forms (TIM-1054):
+ *   - named imports, including aliases: `import { cache as c }` + `c(fn, opts)`
+ *   - namespace imports: `import * as ns` + `ns.cache(fn, opts)`
+ * Forms a per-module transform cannot trace — local variable aliases
+ * (`const c = cache`), user re-export wrapper modules, computed access
+ * (`ns['cache']`) — fall back to the runtime fnId derived from
+ * fnv1a(fn.toString()) (see cache/timber-cache.ts), which is deterministic
+ * across instances and cold starts of the same build. Without either
+ * mechanism, an ordinal counter would collide across instances with a shared
+ * CacheHandler (Redis/KV) — cache key poisoning, serving one route's cached
+ * data to another.
+ *
+ * The plugin transforms:
+ *   cache(fn, opts)      →  cache(fn, opts, "stable-id")
+ *   ns.cache(fn, opts)   →  ns.cache(fn, opts, "stable-id")
+ *
+ * where stable-id =
+ *   fnv1a(relPath + ":cache:" + fnv1a(stmtText) + ":" + fnv1a(callSpanText) + ":" + occurrence)
+ *
+ * stmtText is the source text of the enclosing *top-level statement* and
+ * callSpanText is the source text of the cache(...) call expression itself.
+ *
+ * The ID is derived from the *content* of the call, not its ordinal position
+ * in the file. A position-based index (the original TIM-997 scheme) was stable
+ * within one build but shifted across builds: inserting, deleting, or
+ * reordering a cache() call changed the index of every call below it, so with
+ * a persistent shared CacheHandler (Redis/KV) a new function could inherit
+ * another function's old ID and serve its persisted data — cross-deploy cache
+ * poisoning (TIM-1053). Content hashing makes IDs immune to reordering and
+ * unrelated edits, while a changed call gets a fresh ID — which is exactly
+ * when invalidation is wanted.
+ *
+ * The enclosing-statement text is included so that byte-identical cache()
+ * calls in different scopes — e.g. two factory helpers that each `return
+ * cache(fn, { ttl: 60 })` — get distinct, insertion-stable IDs: their
+ * enclosing declarations differ by name/body even when the call spans are
+ * identical. Without it, a source-order occurrence counter alone would shift
+ * when an identical span is inserted above, reassigning IDs across deploys.
+ * Calls that are byte-identical INCLUDING their enclosing top-level statement
+ * are disambiguated by a source-order occurrence index. That residue is safe:
+ * identical top-level declarations are a redeclaration error, so fully
+ * identical (statement, call) pairs can only be expression statements
+ * referencing the same bindings — the same function, where an ID swap is
+ * harmless.
+ *
+ * See TIM-997, TIM-1053, design/06-caching.md §"Cache Key Security".
+ */
+
+import { relative } from 'node:path';
+import MagicString from 'magic-string';
+import { parseAst } from 'vite';
+import type { Plugin } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+import { fnv1aHash } from '../cache/fast-hash.js';
+
+const CACHE_MODULE_SOURCES = new Set(['@timber-js/app/cache', 'timber/cache']);
+
+interface PositionedNode {
+  type: string;
+  start: number;
+  end: number;
+  [key: string]: unknown;
+}
+
+interface IdentifierNode extends PositionedNode {
+  type: 'Identifier';
+  name: string;
+}
+
+interface ImportDeclarationNode extends PositionedNode {
+  type: 'ImportDeclaration';
+  source: { value: string };
+  specifiers: Array<
+    PositionedNode & {
+      type: string;
+      local: IdentifierNode;
+      imported?: IdentifierNode;
+    }
+  >;
+}
+
+interface CallExpressionNode extends PositionedNode {
+  type: 'CallExpression';
+  callee: PositionedNode;
+  arguments: PositionedNode[];
+}
+
+interface MemberExpressionNode extends PositionedNode {
+  type: 'MemberExpression';
+  object: PositionedNode;
+  property: PositionedNode;
+  computed: boolean;
+}
+
+interface ProgramNode extends PositionedNode {
+  type: 'Program';
+  body: PositionedNode[];
+}
+
+interface CacheBindings {
+  /** Local names bound to `cache` via named imports (`import { cache as c }`). */
+  named: Set<string>;
+  /** Local names of namespace imports (`import * as ns`) of a cache module. */
+  namespaces: Set<string>;
+}
+
+/**
+ * Find the local binding name(s) for `cache` imported from the cache module —
+ * both named imports and namespace imports (TIM-1054).
+ */
+function findCacheBindings(program: ProgramNode): CacheBindings {
+  const named = new Set<string>();
+  const namespaces = new Set<string>();
+  for (const stmt of program.body) {
+    if (stmt.type !== 'ImportDeclaration') continue;
+    const decl = stmt as unknown as ImportDeclarationNode;
+    if (!CACHE_MODULE_SOURCES.has(decl.source.value)) continue;
+    for (const spec of decl.specifiers) {
+      if (spec.type === 'ImportNamespaceSpecifier') {
+        namespaces.add(spec.local.name);
+        continue;
+      }
+      if (spec.type !== 'ImportSpecifier') continue;
+      const importedName = spec.imported?.name ?? spec.local.name;
+      if (importedName === 'cache') {
+        named.add(spec.local.name);
+      }
+    }
+  }
+  return { named, namespaces };
+}
+
+/**
+ * Is this callee a reference to the imported `cache` function — either a bare
+ * identifier bound by a named import, or `ns.cache` on a namespace import?
+ * Computed access (`ns['cache']`) is deliberately not matched; it falls back
+ * to the runtime fnId derivation.
+ */
+function isCacheCallee(callee: PositionedNode, bindings: CacheBindings): boolean {
+  if (callee.type === 'Identifier') {
+    return bindings.named.has((callee as IdentifierNode).name);
+  }
+  if (callee.type === 'MemberExpression') {
+    const member = callee as unknown as MemberExpressionNode;
+    return (
+      !member.computed &&
+      member.object.type === 'Identifier' &&
+      bindings.namespaces.has((member.object as IdentifierNode).name) &&
+      member.property.type === 'Identifier' &&
+      (member.property as IdentifierNode).name === 'cache'
+    );
+  }
+  return false;
+}
+
+/**
+ * Recursively walk AST nodes to find cache() call expressions.
+ *
+ * cache() is typically called at module scope, but we also handle calls
+ * inside functions/blocks for completeness.
+ */
+function findCacheCallSites(
+  node: PositionedNode,
+  cacheBindings: CacheBindings,
+  results: CallExpressionNode[]
+): void {
+  if (node.type === 'CallExpression') {
+    const call = node as unknown as CallExpressionNode;
+    if (call.arguments.length === 2 && isCacheCallee(call.callee, cacheBindings)) {
+      results.push(call);
+    }
+  }
+  for (const key of Object.keys(node)) {
+    if (key === 'type' || key === 'start' || key === 'end') continue;
+    const val = node[key];
+    if (val && typeof val === 'object') {
+      if (Array.isArray(val)) {
+        for (const item of val) {
+          if (item && typeof item === 'object' && typeof item.type === 'string') {
+            findCacheCallSites(item as PositionedNode, cacheBindings, results);
+          }
+        }
+      } else if (typeof (val as PositionedNode).type === 'string') {
+        findCacheCallSites(val as PositionedNode, cacheBindings, results);
+      }
+    }
+  }
+}
+
+/**
+ * Generate a stable callsite ID from a module path, the source text of the
+ * enclosing top-level statement, the source text of the cache(...) call
+ * expression, and an occurrence index among fully byte-identical
+ * (statement, call) pairs in the same file.
+ *
+ * The ID is deterministic and:
+ * - Stable across cold starts AND across builds/deploys for unchanged calls —
+ *   inserting, deleting, or reordering other cache() calls does not affect it
+ * - Unique across different modules (relPath component)
+ * - Unique across distinct cache() calls within a module (statement + span
+ *   hashes), with fully identical duplicates disambiguated by source-order
+ *   occurrence
+ * - Fresh when the wrapped fn, opts, or enclosing statement change, which
+ *   intentionally invalidates the old persisted entries
+ */
+function generateStableId(
+  relativeModulePath: string,
+  statementText: string,
+  callSpanText: string,
+  occurrence: number
+): string {
+  return fnv1aHash(
+    `${relativeModulePath}:cache:${fnv1aHash(statementText)}:${fnv1aHash(callSpanText)}:${occurrence}`
+  );
+}
+
+export function timberCacheTransform(ctx: PluginContext): Plugin {
+  return {
+    name: 'timber-cache-transform',
+
+    transform(code, id) {
+      if (!code.includes('@timber-js/app/cache') && !code.includes('timber/cache')) return;
+      // Skip node_modules (don't transform third-party code)
+      if (id.includes('node_modules')) return;
+
+      let program: ProgramNode;
+      try {
+        program = parseAst(code, { lang: 'tsx' }) as unknown as ProgramNode;
+      } catch {
+        return;
+      }
+
+      const cacheBindings = findCacheBindings(program);
+      if (cacheBindings.named.size === 0 && cacheBindings.namespaces.size === 0) return;
+
+      // Collect call sites per top-level statement so each call carries its
+      // enclosing statement's source text into the ID hash.
+      const callSites: Array<{ call: CallExpressionNode; stmt: PositionedNode }> = [];
+      for (const stmt of program.body) {
+        const calls: CallExpressionNode[] = [];
+        findCacheCallSites(stmt, cacheBindings, calls);
+        for (const call of calls) callSites.push({ call, stmt });
+      }
+      if (callSites.length === 0) return;
+
+      // Sort by position in file so occurrence indices among byte-identical
+      // (statement, call) pairs are assigned in deterministic source order
+      callSites.sort((a, b) => a.call.start - b.call.start);
+
+      const root = ctx.root || process.cwd();
+      const relPath = relative(root, id);
+      const s = new MagicString(code);
+      const occurrences = new Map<string, number>();
+
+      for (const { call, stmt } of callSites) {
+        const stmtText = code.slice(stmt.start, stmt.end);
+        const spanText = code.slice(call.start, call.end);
+        const dupKey = stmtText + String.fromCharCode(0) + spanText;
+        const occurrence = occurrences.get(dupKey) ?? 0;
+        occurrences.set(dupKey, occurrence + 1);
+        const stableId = generateStableId(relPath, stmtText, spanText, occurrence);
+        // Insert the stable ID as the 3rd argument directly after the last
+        // argument — NOT before the closing ')'. The call may already have a
+        // trailing comma after the options argument (Prettier v3 default for
+        // multiline calls); inserting before ')' would emit `,, "id"`, a
+        // parse error (TIM-1021). A trailing comma after the inserted
+        // argument remains valid JS.
+        const lastArg = call.arguments[call.arguments.length - 1];
+        s.appendLeft(lastArg.end, `, "${stableId}"`);
+      }
+
+      return {
+        code: s.toString(),
+        map: s.generateMap({ hires: 'boundary' }),
+      };
+    },
+  };
+}
+
+// Exported for testing
+export { generateStableId };

package/src/plugins/client-chunks.ts

@@ -0,0 +1,113 @@
+/**
+ * Client chunk grouping strategy for @vitejs/plugin-rsc.
+ *
+ * Groups client reference modules by layout boundary to balance route-scoped
+ * code splitting with HTTP request count. A constant group name would collapse
+ * all routes into one chunk (every page downloads every client component).
+ * Per-serverChunk grouping creates many sub-500B files. Layout-boundary
+ * grouping is the middle ground.
+ *
+ * See design/27-chunking-strategy.md, TIM-440, TIM-499.
+ */
+
+import { relative } from 'node:path';
+
+/**
+ * Check whether a root-relative path lives under the app directory,
+ * and if so return the first non-group route segment.
+ *
+ * `appPrefix` is the root-relative app directory with a trailing slash
+ * (e.g. "app/" or "src/app/"), computed once from the resolved appDir
+ * and root. Matching uses `startsWith` — no ambiguity.
+ *
+ * Returns:
+ *   { inApp: false }                       — path is not under app/
+ *   { inApp: true, segment: null }         — root of app/ (e.g. app/layout.tsx)
+ *   { inApp: true, segment: "dashboard" }  — nested route boundary
+ */
+function findAppBoundary(
+  path: string,
+  appPrefix: string
+): { inApp: false } | { inApp: true; segment: string | null } {
+  const relPath = path.replace(/\\/g, '/');
+  if (!relPath.startsWith(appPrefix)) return { inApp: false };
+
+  const withinApp = relPath.slice(appPrefix.length);
+  const segments = withinApp.split('/');
+
+  for (const seg of segments) {
+    if (seg.includes('.')) break;
+    if (seg.startsWith('(') && seg.endsWith(')')) continue;
+    return { inApp: true, segment: seg };
+  }
+
+  return { inApp: true, segment: null };
+}
+
+/**
+ * Derive a chunk group name for a client reference module.
+ *
+ * Groups by the first non-group route segment under appDir so that all
+ * client components belonging to the same layout boundary land in one
+ * chunk. For example:
+ *   - `facade:app/dashboard/settings/page.tsx` → `"client-dashboard"`
+ *   - `facade:app/(group-a)/group-page-a/page.tsx` → `"client-group-page-a"`
+ *   - `facade:app/layout.tsx` (root layout) → `"client-shared"`
+ *   - `shared:...` (shared across chunks) → `"client-shared"`
+ *
+ * When a 'use client' module lives outside the app directory (e.g. in
+ * src/posts/ or src/components/), the function falls back to deriving
+ * the layout boundary from the serverChunk's facade path. This prevents
+ * lazily-loaded client dependencies (e.g. via import.meta.glob) from
+ * being hoisted into the shared chunk when they're only used by a
+ * specific route.
+ *
+ * This balances route-scoped code splitting with HTTP request count:
+ * fewer chunks than per-serverChunk, but still avoids downloading every
+ * client component on every page.
+ */
+export function clientChunkGroup(
+  meta: { id: string; normalizedId: string; serverChunk: string },
+  appDir: string,
+  root: string
+): string {
+  const { normalizedId, serverChunk } = meta;
+
+  // Shared chunks (not associated with a single route entry) get one group.
+  if (serverChunk.startsWith('shared:')) return 'client-shared';
+
+  // Compute the root-relative app directory prefix once. Both normalizedId
+  // and serverChunk paths from the RSC plugin are root-relative (via
+  // path.relative(root, absoluteId)), so this prefix matches exactly —
+  // no ambiguity with content directories that happen to share a name.
+  const appPrefix = relative(root, appDir).replace(/\\/g, '/') + '/';
+
+  // Try the client module's own path first.
+  const result = findAppBoundary(normalizedId, appPrefix);
+  if (result.inApp && result.segment) return `client-${result.segment}`;
+  if (result.inApp) return 'client-shared';
+
+  // The client module lives outside the app directory (e.g. src/posts/,
+  // src/components/). Fall back to the serverChunk's facade path — the
+  // RSC entry point that imported this module — to derive the route's
+  // layout boundary. This keeps dependencies of lazily-loaded 'use client'
+  // components (e.g. from import.meta.glob) in per-route async chunks
+  // instead of hoisting them into client-shared.
+  if (serverChunk.startsWith('facade:')) {
+    const facadePath = serverChunk.slice('facade:'.length).replace(/\\/g, '/');
+    const facadeResult = findAppBoundary(facadePath, appPrefix);
+    if (facadeResult.inApp && facadeResult.segment) return `client-${facadeResult.segment}`;
+    if (facadeResult.inApp) return 'client-shared';
+
+    // Both module and facade are outside app/. Derive a chunk name from
+    // the full facade path to keep these isolated from client-shared.
+    // Uses the full path (minus extension) to avoid collisions between
+    // facades with the same basename (e.g. foo/index.mdx vs bar/index.mdx).
+    const facadeName = facadePath.replace(/\.[^.]+$/, '').replace(/\//g, '-');
+    if (facadeName) return `client-${facadeName}`;
+  }
+
+  // Root-level files (layout.tsx, page.tsx directly in app/) go into the
+  // shared group since the root layout is loaded on every page.
+  return 'client-shared';
+}

package/src/plugins/cloudflare-wasm.ts

@@ -0,0 +1,141 @@
+/**
+ * timber-cloudflare-wasm — Handle WASM modules for Cloudflare Workers builds.
+ *
+ * Cloudflare Workers can natively import `.wasm` files as compiled
+ * WebAssembly.Module. But Rolldown can't load `.wasm` files at build time.
+ *
+ * This plugin bridges the gap:
+ * 1. Adds the `workerd` resolve condition so libraries like @takumi-rs/wasm
+ *    resolve to their Cloudflare-native entry (bare `.wasm` import)
+ * 2. Externalizes `.wasm` imports so Rolldown skips them
+ * 3. Copies the WASM files to the build output so wrangler can find them
+ *
+ * Only active for Cloudflare adapter production builds — every hook bails
+ * unless `isCloudflareBuild` was set in configResolved. In dev and non-CF
+ * builds, `.wasm` imports are left to Vite's own handling (?init / ?url or
+ * a clear build error), never silently externalized.
+ */
+
+import { basename, resolve, dirname } from 'node:path';
+import { createHash } from 'node:crypto';
+import { copyFile, mkdir, readFile } from 'node:fs/promises';
+import type { Plugin, ResolvedConfig } from 'vite';
+import type { PluginContext } from '../plugin-context.js';
+
+function isCloudflareAdapter(ctx: PluginContext): boolean {
+  const adapter = ctx.config.adapter as { name?: string } | undefined;
+  return adapter?.name === 'cloudflare';
+}
+
+export function timberCloudflareWasm(ctx: PluginContext): Plugin[] {
+  // Resolved WASM files, keyed by absolute source path so two files that
+  // share a basename (e.g. lib_bg.wasm from two packages) don't collide.
+  // The value is the unique output basename used for the external import
+  // specifier and the copy destination.
+  const wasmFiles = new Map<string, string>();
+  const usedBasenames = new Set<string>();
+  let isCloudflareBuild = false;
+
+  const plugin: Plugin = {
+    name: 'timber-cloudflare-wasm',
+
+    configResolved(resolved: ResolvedConfig) {
+      if (resolved.command !== 'build') return;
+      if (!isCloudflareAdapter(ctx)) return;
+      isCloudflareBuild = true;
+
+      // Prepend `workerd` to resolve conditions for server environments
+      // so @takumi-rs/wasm/auto resolves to the Cloudflare-native entry
+      // (bare WASM import) instead of the Vite entry (?url + fetch).
+      // Must happen in configResolved because the RSC plugin sets its own
+      // conditions during config — merging via config() would lose them.
+      for (const envName of ['rsc', 'ssr']) {
+        const env = resolved.environments[envName];
+        if (!env) continue;
+        const conditions = env.resolve.conditions;
+        if (!conditions.includes('workerd')) {
+          conditions.unshift('workerd');
+        }
+      }
+    },
+
+    // Strip /* @vite-ignore */ from @takumi-rs/wasm dynamic imports so
+    // Rolldown bundles them instead of leaving bare specifiers that fail
+    // at runtime on Cloudflare Workers (no node_modules).
+    transform(code, id) {
+      if (!isCloudflareBuild) return;
+      if (!id.includes('takumi')) return;
+      const stripped = code.replaceAll(
+        /\/\*\s*@vite-ignore\s*\*\/\s*\n\s*"@takumi-rs\/wasm"/g,
+        '"@takumi-rs/wasm"'
+      );
+      if (stripped !== code) return stripped;
+    },
+
+    resolveId: {
+      order: 'pre',
+      async handler(source, importer) {
+        if (!isCloudflareBuild) return;
+        if (!source.endsWith('.wasm')) return;
+
+        let absolutePath: string;
+        if (source.startsWith('.') && importer) {
+          absolutePath = resolve(dirname(importer), source);
+        } else {
+          return;
+        }
+
+        let outputName = wasmFiles.get(absolutePath);
+        if (!outputName) {
+          outputName = basename(absolutePath);
+          if (usedBasenames.has(outputName)) {
+            // Another wasm file already claimed this basename — disambiguate
+            // with a short content hash so both files land in the output.
+            const hash = createHash('sha256')
+              .update(await readFile(absolutePath))
+              .digest('hex')
+              .slice(0, 8);
+            outputName = outputName.replace(/\.wasm$/, `.${hash}.wasm`);
+          }
+          usedBasenames.add(outputName);
+          wasmFiles.set(absolutePath, outputName);
+        }
+
+        return { id: './' + outputName, external: true };
+      },
+    },
+
+    async writeBundle(options, bundle) {
+      if (!isCloudflareBuild) return;
+      if (wasmFiles.size === 0) return;
+
+      const outDir = options.dir;
+      if (!outDir) return;
+
+      // Find which output chunks reference WASM files and copy the WASM
+      // to the same directory so the relative imports resolve correctly.
+      const targetDirs = new Set<string>();
+      for (const chunk of Object.values(bundle)) {
+        if (chunk.type !== 'chunk') continue;
+        for (const outputName of wasmFiles.values()) {
+          if (chunk.code.includes(outputName)) {
+            targetDirs.add(dirname(resolve(outDir, chunk.fileName)));
+          }
+        }
+      }
+
+      if (targetDirs.size === 0) return;
+
+      const copies: Promise<void>[] = [];
+      for (const dir of targetDirs) {
+        await mkdir(dir, { recursive: true });
+        for (const [absolutePath, outputName] of wasmFiles) {
+          copies.push(copyFile(absolutePath, resolve(dir, outputName)));
+        }
+      }
+      await Promise.all(copies);
+    },
+  };
+
+  return [plugin];
+}

package/src/plugins/content.ts

@@ -11,7 +11,7 @@
 import type { Plugin } from 'vite';
 import { existsSync } from 'node:fs';
 import { join } from 'node:path';
-import type { PluginContext } from '#/index.js';
+import type { PluginContext } from '../plugin-context.js';
 
 const CONFIG_FILE_NAMES = [
   'content-collections.ts',