@timber-js/app 0.2.0-alpha.157 → 0.2.0-alpha.159

package/src/plugins/prebuilt-capture.ts

@@ -0,0 +1,208 @@
+/**
+ * Post-build prebuilt capture — Node-side orchestration (TIM-1119).
+ *
+ * Runs from timber-prebuilt's `buildApp` post hook, after Vite's 5-step
+ * build sequence. Imports the BUILT `rsc/index.js` (the bundle carries
+ * the react-server condition resolved at build time, so a plain dynamic
+ * import works) and calls its `__timber_capturePrebuilt` export — the
+ * capture itself must run inside the bundle's module graph, where the
+ * component registry and flight renderer live. See
+ * server/prebuilt-builder.ts and design/44-render-at-build-time.md
+ * §Build Phase.
+ *
+ * This side owns PERSISTENCE: each captured payload is written to
+ * `.timber/dist/prebuilt/<componentId>/<cacheKey>.flight` atomically
+ * (temp file + rename — a crashed build never leaves a torn artifact
+ * under its final name), and `manifest.json` is written last, only after
+ * every payload it references is fully on disk. Keeping node:fs on the
+ * plugin side keeps it out of the server bundle, which must also run on
+ * Cloudflare Workers.
+ *
+ * NOTE: importing the built entry runs the app's production startup —
+ * instrumentation.ts register() and the configured cache handler load
+ * inside the build process. That is by design (prebuilt components may
+ * call timber.cache), and it only happens when the app actually declares
+ * prebuilt components.
+ */
+
+import { existsSync } from 'node:fs';
+import { mkdir, rename, rm, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+import type { PluginContext } from '../plugin-context.js';
+import type { CaptureOptions, CaptureSummary, CapturedEntry } from '../server/prebuilt-builder.js';
+import type { PrebuiltManifest } from '../server/prebuilt/payload-source.js';
+
+// ─── Artifact writer ──────────────────────────────────────────────────────
+
+/**
+ * Both patterns are framework-generated (plugins/prebuilt.ts assigns IDs,
+ * server/prebuilt/cache-key.ts hashes keys), so a mismatch is a framework
+ * bug or a tampered registry — either way it must never reach a path join.
+ */
+const COMPONENT_ID_RE = /^[a-z0-9]+_[0-9a-f]{16}$/;
+const CACHE_KEY_RE = /^[0-9a-f]{16}$/;
+
+export interface PrebuiltArtifactWriter {
+  write(entry: CapturedEntry): Promise<void>;
+  /** Write manifest.json (if any entries exist). Returns the entry count. */
+  finalize(): Promise<number>;
+}
+
+/** Write a file atomically: temp sibling + rename. */
+async function writeFileAtomic(path: string, data: Uint8Array | string): Promise<void> {
+  const tmp = `${path}.tmp`;
+  await writeFile(tmp, data);
+  await rename(tmp, path);
+}
+
+/**
+ * Create the writer for `.timber/dist/prebuilt/`. Storage layout per
+ * design/44 §Storage: one directory per component ID, one `.flight` file
+ * per cache key, one manifest.json mapping componentId + key → file +
+ * metadata.
+ */
+export function createPrebuiltArtifactWriter(prebuiltDir: string): PrebuiltArtifactWriter {
+  const manifest: PrebuiltManifest = {};
+  const buildTimestamp = Date.now();
+  let count = 0;
+
+  return {
+    async write(entry: CapturedEntry): Promise<void> {
+      if (!COMPONENT_ID_RE.test(entry.componentId) || !CACHE_KEY_RE.test(entry.cacheKey)) {
+        throw new Error(
+          `[timber] prebuilt artifact writer received a malformed identity ` +
+            `(componentId: ${JSON.stringify(entry.componentId)}, cacheKey: ` +
+            `${JSON.stringify(entry.cacheKey)}) — refusing to write`
+        );
+      }
+      const relativeFile = `${entry.componentId}/${entry.cacheKey}.flight`;
+      const path = join(prebuiltDir, relativeFile);
+      await mkdir(dirname(path), { recursive: true });
+      await writeFileAtomic(path, entry.bytes);
+
+      manifest[entry.componentId] ??= { entries: {} };
+      manifest[entry.componentId].entries[entry.cacheKey] = {
+        params: entry.params,
+        file: relativeFile,
+        bytes: entry.bytes.byteLength,
+        buildTimestamp,
+        ...(entry.tags ? { tags: entry.tags } : {}),
+      };
+      count++;
+    },
+
+    async finalize(): Promise<number> {
+      if (count === 0) return 0;
+      await writeFileAtomic(
+        join(prebuiltDir, 'manifest.json'),
+        JSON.stringify(manifest, null, 2) + '\n'
+      );
+      return count;
+    },
+  };
+}
+
+/**
+ * Remove any `prebuilt/` output left by a previous build in this
+ * directory (watch mode, `emptyOutDir: false`). A stale manifest would
+ * make adapters ship payloads from an OLD build — reviving them serves
+ * outdated content with that build's chunk references instead of the
+ * intended miss → live render. Runs unconditionally at the start of the
+ * post-build hook, BEFORE the capture decision: a build whose app no
+ * longer declares any prebuilt components must also shed the artifacts
+ * (codex P2 on PR #836).
+ */
+export async function cleanPrebuiltDir(buildDir: string): Promise<void> {
+  await rm(join(buildDir, 'prebuilt'), { recursive: true, force: true });
+}
+
+// ─── Capture orchestration ────────────────────────────────────────────────
+
+/** Shape of the built RSC entry's capture export. */
+interface CaptureModule {
+  __timber_capturePrebuilt?: (options: CaptureOptions) => Promise<CaptureSummary>;
+}
+
+/**
+ * Load the built RSC entry and run the capture pass. Throws (failing the
+ * build) on infrastructure errors — missing/unloadable entry — and on
+ * dynamic-context hard errors (cookies()/headers() in a prerendered
+ * component). Per-entry data errors skip-and-report per design/44
+ * §Build-Phase Error Handling.
+ */
+export async function runPrebuiltCapture(ctx: PluginContext): Promise<CaptureSummary> {
+  const routeComponents = ctx.routePrebuiltComponents;
+  if (!routeComponents || routeComponents.size === 0) {
+    return { captured: 0, skipped: [], hardErrors: [], nestingWarnings: 0 };
+  }
+
+  const entryPath = join(ctx.buildDir, 'rsc', 'index.js');
+  if (!existsSync(entryPath)) {
+    throw new Error(
+      `[timber] prebuilt capture: built RSC entry not found at ${entryPath} — ` +
+        `the app declares cache.component({ prerender: true }) call sites but the ` +
+        `RSC build output is missing`
+    );
+  }
+
+  // The same globals the adapter entry sets before importing the handler
+  // (adapter-build.ts). The bundle's virtual:timber-build-manifest falls
+  // back to an empty manifest, but set the real values when available so
+  // capture-time behavior matches production startup.
+  const g = globalThis as Record<string, unknown>;
+  if (ctx.buildManifest) g.__TIMBER_BUILD_MANIFEST__ ??= ctx.buildManifest;
+  if (ctx.deploymentId) g.__TIMBER_DEPLOYMENT_ID__ ??= ctx.deploymentId;
+
+  console.log('[timber] cache.component: capturing prebuilt flight payloads…');
+
+  let mod: CaptureModule;
+  try {
+    // Cache-busting query: in a long-lived build process (vite build
+    // --watch), a bare file URL would return the FIRST build's module from
+    // the ESM cache — stale code and a stale (already-walked) registry.
+    const entryUrl = `${pathToFileURL(entryPath).href}?t=${Date.now()}`;
+    mod = (await import(/* @vite-ignore */ entryUrl)) as CaptureModule;
+  } catch (error) {
+    throw new Error(
+      `[timber] prebuilt capture: failed to load the built RSC entry (${entryPath}). ` +
+        `The capture pass runs the production server module inside the build process — ` +
+        `its startup must succeed for prerendering to work.`,
+      { cause: error }
+    );
+  }
+  const capture = mod.__timber_capturePrebuilt;
+  if (typeof capture !== 'function') {
+    throw new Error(
+      `[timber] prebuilt capture: built RSC entry does not export __timber_capturePrebuilt — ` +
+        `the build output predates this framework version; rebuild from a clean .timber/dist`
+    );
+  }
+
+  const writer = createPrebuiltArtifactWriter(join(ctx.buildDir, 'prebuilt'));
+  const summary = await capture({
+    fileComponentMap: Object.fromEntries(routeComponents),
+    callSiteProps: ctx.prebuiltCallSiteProps
+      ? Object.fromEntries(ctx.prebuiltCallSiteProps)
+      : undefined,
+    onEntry: (entry) => writer.write(entry),
+  });
+
+  if (summary.hardErrors.length > 0) {
+    const details = summary.hardErrors.map((issue) => `  - ${issue.message}`).join('\n');
+    throw new Error(
+      `[timber] prebuilt capture failed: ${summary.hardErrors.length} component(s) read ` +
+        `per-request context at build time:\n${details}`
+    );
+  }
+
+  await writer.finalize();
+
+  const total = summary.captured + summary.skipped.length;
+  console.log(
+    `[timber] Prebuilt ${summary.captured}/${total} entries.` +
+      (summary.skipped.length > 0 ? ` ${summary.skipped.length} skipped due to errors.` : '')
+  );
+  return summary;
+}