@mandujs/core 0.21.0 → 0.22.1

package/src/bundler/vendor-cache.ts

@@ -0,0 +1,526 @@
+/**
+ * Phase 7.2 — Tier 2 vendor shim disk cache (Agent A / S2).
+ *
+ * # Why this exists
+ *
+ * `buildVendorShims` produces four small-but-deterministic JS bundles:
+ *   - `_vendor-react.js` / `_vendor-react-dom.js` / `_vendor-react-refresh.js`
+ *     / `_fast-refresh-runtime.js` (+ two JSX runtimes).
+ *
+ * The inputs are the upstream npm versions of `react` / `react-dom` /
+ * `react-refresh` plus the shim source strings we hard-code in `build.ts`.
+ * If none of those change, re-running Bun.build yields byte-identical output
+ * — but it still costs ~100-160 ms (Windows) because `Bun.build` has to parse
+ * and resolve each shim fresh every boot.
+ *
+ * Cold-start breakdown (`docs/bun/phase-7-1-diagnostics/cold-start-breakdown.md`
+ * §3.B and §5 Tier 2) attributes ~80-120 ms of the 910 ms tmpdir cold start
+ * to these rebuilds. Cache hit on warm workflow eliminates that cost.
+ *
+ * # Design
+ *
+ * - **Single atomic manifest** at `.mandu/vendor-cache/vendor-cache.json`.
+ *   Any mismatch → *every* cached output is treated as invalid and
+ *   `buildVendorShims` runs its full parallel build path. We do not support
+ *   per-entry invalidation because the outputs always move together (they
+ *   share the same React version).
+ *
+ * - **Five-part hash input** (order-preserved):
+ *     1. `Bun.version` (runtime semantics may change between minor bumps)
+ *     2. resolved `react/package.json.version`
+ *     3. resolved `react-dom/package.json.version`
+ *     4. resolved `react-refresh/package.json.version`
+ *     5. `@mandujs/core/package.json.version` (shim source evolves with Mandu)
+ *
+ *   Any of the five differing triggers a cold path. See the §6 risk section
+ *   of `docs/bun/phase-7-2-team-plan.md`.
+ *
+ * - **SHA-256 per entry** for tamper detection. If an output file was
+ *   truncated / edited / corrupted, the cached-hit path refuses to use it
+ *   and falls through to the full rebuild. `size` is a cheaper first-pass
+ *   check so we avoid hashing every byte for the common case.
+ *
+ * - **NO concurrency**: dev servers are single-process, so write-after-read
+ *   races don't happen. Two concurrent `mandu dev` invocations on the same
+ *   project WILL step on each other — this is the same story as the pre-
+ *   existing `.mandu/dev-cache/ssr` directory used by the SSR bundled
+ *   importer, which is also single-writer.
+ *
+ * - **Gitignored location**: `.mandu/` is already in the starter's
+ *   `.gitignore`, so branch switches preserve the cache but a hard clean
+ *   (`git clean -fdx`) triggers a rebuild — intentional because hard-cleaned
+ *   trees should not trust stale artifacts.
+ *
+ * # Error handling
+ *
+ * Every I/O path swallows errors by falling back to miss:
+ *   - manifest read fails → miss "no-manifest"
+ *   - JSON parse fails → miss "no-manifest" (treat as absent)
+ *   - any `fs.stat` / hash mismatch → miss "missing-entry" / "hash-mismatch"
+ *
+ * The writer is best-effort: if writing the manifest or a cached entry
+ * fails, we log via perf (opt-in) but never block the build. Next boot
+ * will either find a complete cache or hit a miss and rebuild.
+ *
+ * References:
+ *   docs/bun/phase-7-2-team-plan.md §2.2
+ *   docs/bun/phase-7-1-diagnostics/cold-start-breakdown.md §§3.B, 5
+ *   packages/core/src/bundler/vendor-cache-types.ts (the contract)
+ */
+
+import fs from "fs/promises";
+import path from "path";
+import { createHash } from "node:crypto";
+import {
+  type VendorCacheManifest,
+  type VendorCacheResult,
+  type VendorCacheEntry,
+  VENDOR_CACHE_DIR,
+  VENDOR_CACHE_FILENAME,
+  VENDOR_CACHE_MAX_BYTES,
+} from "./vendor-cache-types";
+
+// ============================================
+// Public API
+// ============================================
+
+/**
+ * Input to {@link readVendorCache} and {@link writeVendorCache}. Callers
+ * resolve these versions once (at the start of `buildVendorShims`) and
+ * pass them to both functions so the hash input is stable.
+ */
+export interface VendorCacheKeyInput {
+  bunVersion: string;
+  reactVersion: string;
+  reactDomVersion: string;
+  reactRefreshVersion: string;
+  manduCoreVersion: string;
+}
+
+/**
+ * Logical id → on-disk filename map. Must stay in lock-step with
+ * `buildVendorShims` in `build.ts`: any new shim added there needs its
+ * logical id registered here so the cache knows which file to
+ * preserve/restore.
+ */
+export const VENDOR_SHIM_FILES: Record<string, string> = {
+  "react": "_react.js",
+  "react-dom": "_react-dom.js",
+  "react-dom-client": "_react-dom-client.js",
+  "jsx-runtime": "_jsx-runtime.js",
+  "jsx-dev-runtime": "_jsx-dev-runtime.js",
+  "react-refresh-runtime": "_vendor-react-refresh.js",
+  "fast-refresh-glue": "_fast-refresh-runtime.js",
+} as const;
+
+/** Keys of {@link VENDOR_SHIM_FILES}. */
+export type VendorShimId = keyof typeof VENDOR_SHIM_FILES;
+
+// ============================================
+// Read path
+// ============================================
+
+/**
+ * Try to load the vendor cache for `rootDir`. Returns `hit` only when:
+ *   1. The manifest file exists and parses cleanly.
+ *   2. Every version field matches the requested inputs.
+ *   3. Every entry's file exists, has the recorded size, and hashes back
+ *      to the stored SHA-256.
+ *
+ * All other cases return a typed `miss` so the caller can decide what to
+ * log (perf markers fire here so a diagnostic pass doesn't need to read
+ * the result type).
+ *
+ * The manifest is consulted at boot only — no lazy / partial reads. A
+ * "size" field > {@link VENDOR_CACHE_MAX_BYTES} is treated as a miss so
+ * pathological disk corruption can't feed a nonsensical 10 GB file into
+ * a hash round-trip.
+ */
+export async function readVendorCache(
+  rootDir: string,
+  keys: VendorCacheKeyInput,
+): Promise<VendorCacheResult> {
+  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
+  const manifestPath = path.join(cacheDir, VENDOR_CACHE_FILENAME);
+
+  let rawManifest: string;
+  try {
+    rawManifest = await fs.readFile(manifestPath, "utf-8");
+  } catch {
+    return { kind: "miss", reason: "no-manifest" };
+  }
+
+  let manifest: VendorCacheManifest;
+  try {
+    manifest = JSON.parse(rawManifest) as VendorCacheManifest;
+  } catch {
+    // Corrupt / partial write — treat as absent.
+    return { kind: "miss", reason: "no-manifest" };
+  }
+
+  // Format version — reject unknown schemas (future-proofing).
+  if (manifest.version !== 1) {
+    return { kind: "miss", reason: "format-version" };
+  }
+
+  // Version comparison — any mismatch invalidates everything.
+  const versionCheck = compareVersions(manifest, keys);
+  if (versionCheck !== null) {
+    return {
+      kind: "miss",
+      reason: "version-mismatch",
+      mismatchedField: versionCheck,
+    };
+  }
+
+  // Size check (cheap) before hash check (expensive).
+  for (const [logicalId, entry] of Object.entries(manifest.entries)) {
+    const entryPath = path.join(cacheDir, entry.path);
+    let stat;
+    try {
+      stat = await fs.stat(entryPath);
+    } catch {
+      return { kind: "miss", reason: "missing-entry" };
+    }
+
+    if (stat.size !== entry.size) {
+      return { kind: "miss", reason: "size-mismatch" };
+    }
+
+    if (stat.size > VENDOR_CACHE_MAX_BYTES) {
+      // Pathological — refuse to read.
+      return { kind: "miss", reason: "size-mismatch" };
+    }
+
+    // Hash check — full read. Entries are small (~25 KB total today).
+    let buf;
+    try {
+      buf = await fs.readFile(entryPath);
+    } catch {
+      return { kind: "miss", reason: "missing-entry" };
+    }
+
+    const actualHash = sha256(buf);
+    if (actualHash !== entry.hash) {
+      return { kind: "miss", reason: "hash-mismatch" };
+    }
+
+    // Swallow unused loop variable to satisfy no-unused-vars.
+    void logicalId;
+  }
+
+  return { kind: "hit", manifest };
+}
+
+// ============================================
+// Write path
+// ============================================
+
+/**
+ * Input for {@link writeVendorCache} — one entry per shim produced by
+ * `buildVendorShims`. The `absPath` points at the freshly-built file in
+ * `.mandu/client/` which we copy into the cache dir to avoid depending on
+ * downstream `buildClientBundles` side-effects.
+ */
+export interface VendorCacheWriteEntry {
+  logicalId: string;
+  /** Absolute path to the built shim in `.mandu/client/`. */
+  absPath: string;
+}
+
+/**
+ * Persist the freshly-built shims + manifest to `.mandu/vendor-cache/`.
+ *
+ * - Creates the cache dir if missing.
+ * - Copies each entry's file by bytes (not a symlink — Windows junction
+ *   semantics differ between filesystems, and a hard-copy sidesteps the
+ *   "rebuild deletes the original" GC hazard).
+ * - Writes the manifest LAST so a crashed write leaves the cache in a
+ *   safe state (missing-entry on next read → miss).
+ *
+ * Best-effort: returns `false` on any write failure but does not throw,
+ * so the build continues even if the disk is read-only.
+ */
+export async function writeVendorCache(
+  rootDir: string,
+  keys: VendorCacheKeyInput,
+  entries: VendorCacheWriteEntry[],
+): Promise<boolean> {
+  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
+
+  try {
+    await fs.mkdir(cacheDir, { recursive: true });
+  } catch {
+    return false;
+  }
+
+  const manifestEntries: Record<string, VendorCacheEntry> = {};
+
+  for (const entry of entries) {
+    let buf: Buffer;
+    try {
+      buf = await fs.readFile(entry.absPath);
+    } catch {
+      // Source file missing (build must have failed earlier) — skip
+      // this entry. An incomplete cache manifest is still safe because
+      // the read path checks every referenced entry.
+      continue;
+    }
+
+    if (buf.byteLength > VENDOR_CACHE_MAX_BYTES) {
+      continue;
+    }
+
+    const fileName = path.basename(entry.absPath);
+    const destPath = path.join(cacheDir, fileName);
+
+    try {
+      await fs.writeFile(destPath, buf);
+    } catch {
+      continue;
+    }
+
+    manifestEntries[entry.logicalId] = {
+      path: fileName,
+      size: buf.byteLength,
+      hash: sha256(buf),
+    };
+  }
+
+  // Nothing to cache → skip writing a stub manifest (would cause miss on
+  // next boot). Callers should interpret this as a best-effort success.
+  if (Object.keys(manifestEntries).length === 0) {
+    return false;
+  }
+
+  const manifest: VendorCacheManifest = {
+    version: 1,
+    bunVersion: keys.bunVersion,
+    reactVersion: keys.reactVersion,
+    reactDomVersion: keys.reactDomVersion,
+    reactRefreshVersion: keys.reactRefreshVersion,
+    manduCoreVersion: keys.manduCoreVersion,
+    entries: manifestEntries,
+    generatedAt: new Date().toISOString(),
+  };
+
+  try {
+    await fs.writeFile(
+      path.join(cacheDir, VENDOR_CACHE_FILENAME),
+      JSON.stringify(manifest, null, 2),
+    );
+  } catch {
+    return false;
+  }
+
+  return true;
+}
+
+// ============================================
+// Restore path — used on cache hit to re-populate `.mandu/client/`
+// ============================================
+
+/**
+ * Copy every manifest-referenced file from the cache dir into `outDir`
+ * (`.mandu/client/`). Returns the list of absolute output paths, in the
+ * same order as the manifest's `entries` object iteration.
+ *
+ * Called on cache hit from `buildVendorShims` — skips re-running the
+ * Bun.build calls entirely. If a copy fails (partial disk read, for
+ * instance) the caller should fall back to rebuild — we return `null`
+ * from this function in that case to make the degraded path explicit.
+ */
+export async function restoreVendorCache(
+  rootDir: string,
+  manifest: VendorCacheManifest,
+  outDir: string,
+): Promise<Map<string, string> | null> {
+  const cacheDir = path.resolve(rootDir, VENDOR_CACHE_DIR);
+
+  try {
+    await fs.mkdir(outDir, { recursive: true });
+  } catch {
+    return null;
+  }
+
+  const result = new Map<string, string>();
+  for (const [logicalId, entry] of Object.entries(manifest.entries)) {
+    const src = path.join(cacheDir, entry.path);
+    const dst = path.join(outDir, path.basename(entry.path));
+    try {
+      const buf = await fs.readFile(src);
+      // Phase 7.2.R3 M-02 — TOCTOU hardening. `readVendorCache` already
+      // verified SHA-256/size, but an attacker with filesystem write
+      // access could swap `_vendor-*.js` between the read and this
+      // copy. Re-hash the buffer we are about to copy — if it diverges
+      // from the manifest entry, bail out and force rebuild instead of
+      // shipping attacker-controlled JS into `.mandu/client/`.
+      const actualSize = buf.byteLength;
+      if (actualSize !== entry.size) return null;
+      const actualHash = createHash("sha256").update(buf).digest("hex");
+      if (actualHash !== entry.hash) return null;
+      await fs.writeFile(dst, buf);
+      result.set(logicalId, dst);
+    } catch {
+      // Any partial failure invalidates the restore — caller rebuilds.
+      return null;
+    }
+  }
+
+  return result;
+}
+
+// ============================================
+// Key resolution — package.json probing
+// ============================================
+
+/**
+ * Resolve the key input from a project root. Reads the requested npm
+ * packages' `package.json` via Node resolution from `rootDir`, with a
+ * fallback lookup through Bun's resolution if the standard path does
+ * not apply (eg. monorepo hoisting).
+ *
+ * We do NOT use `require.resolve` — it isn't available under pure ESM
+ * in Bun. Instead we read `node_modules/<name>/package.json` directly
+ * and walk up the tree if needed.
+ *
+ * The `manduCoreVersion` is sourced from our own package.json at build
+ * time (it's read through `import.meta.url`). This guards against the
+ * project's own React/React-DOM being rebuilt against a newer Mandu
+ * shim source.
+ */
+export async function resolveVendorCacheKeys(
+  rootDir: string,
+): Promise<VendorCacheKeyInput> {
+  const bunVersion = typeof Bun !== "undefined" ? Bun.version : "0.0.0";
+
+  const [reactVersion, reactDomVersion, reactRefreshVersion, manduCoreVersion] =
+    await Promise.all([
+      resolvePackageVersion(rootDir, "react"),
+      resolvePackageVersion(rootDir, "react-dom"),
+      resolvePackageVersion(rootDir, "react-refresh"),
+      resolveManduCoreVersion(rootDir),
+    ]);
+
+  return {
+    bunVersion,
+    reactVersion,
+    reactDomVersion,
+    reactRefreshVersion,
+    manduCoreVersion,
+  };
+}
+
+/**
+ * Walk up from `rootDir` looking for
+ * `node_modules/<pkg>/package.json`, return its `version` field. Falls
+ * back to `"unknown"` if nothing is found — intentional so missing a
+ * dependency (eg. `react-refresh` in pure-SSR projects) doesn't
+ * throw. A stable `"unknown"` value still permits cache reuse as long
+ * as the project isn't mutated.
+ */
+async function resolvePackageVersion(
+  rootDir: string,
+  pkgName: string,
+): Promise<string> {
+  let current = path.resolve(rootDir);
+  const { root } = path.parse(current);
+
+  // Cap the walk at 10 levels to avoid pathological symlink loops.
+  for (let i = 0; i < 10; i++) {
+    const candidate = path.join(
+      current,
+      "node_modules",
+      pkgName,
+      "package.json",
+    );
+    try {
+      const raw = await fs.readFile(candidate, "utf-8");
+      const parsed = JSON.parse(raw) as { version?: string };
+      if (typeof parsed.version === "string" && parsed.version.length > 0) {
+        return parsed.version;
+      }
+      return "unknown";
+    } catch {
+      // Not here — keep walking.
+    }
+
+    if (current === root) break;
+    const next = path.dirname(current);
+    if (next === current) break;
+    current = next;
+  }
+
+  return "unknown";
+}
+
+/**
+ * Resolve `@mandujs/core` own version from the repo relative to this
+ * source file. We can't reuse `resolvePackageVersion(rootDir, "@mandujs/core")`
+ * because during local dev the core is linked through `workspace:*` and
+ * doesn't exist in `<project>/node_modules` — it lives in the monorepo's
+ * `packages/core/package.json`.
+ */
+async function resolveManduCoreVersion(rootDir: string): Promise<string> {
+  // Try the project's own node_modules first (published install path).
+  const published = await resolvePackageVersion(rootDir, "@mandujs/core");
+  if (published !== "unknown") {
+    return published;
+  }
+
+  // Fallback: walk up from this source file. `import.meta.dir` is the
+  // directory containing this module. `<dir>/../../package.json` is
+  // `packages/core/package.json` in the monorepo layout.
+  try {
+    const corePackagePath = path.resolve(import.meta.dir, "..", "..", "package.json");
+    const raw = await fs.readFile(corePackagePath, "utf-8");
+    const parsed = JSON.parse(raw) as { version?: string; name?: string };
+    if (
+      parsed.name === "@mandujs/core" &&
+      typeof parsed.version === "string"
+    ) {
+      return parsed.version;
+    }
+  } catch {
+    // Fall through.
+  }
+
+  return "unknown";
+}
+
+// ============================================
+// Internal helpers
+// ============================================
+
+/**
+ * Compare the manifest's version fields against the requested input.
+ * Returns `null` on match, or the mismatched field name on miss. The
+ * field names are restricted to the keys actually gated by the cache
+ * key — `generatedAt` is NOT part of the hash input.
+ */
+function compareVersions(
+  manifest: VendorCacheManifest,
+  keys: VendorCacheKeyInput,
+):
+  | null
+  | "bunVersion"
+  | "reactVersion"
+  | "reactDomVersion"
+  | "reactRefreshVersion"
+  | "manduCoreVersion" {
+  if (manifest.bunVersion !== keys.bunVersion) return "bunVersion";
+  if (manifest.reactVersion !== keys.reactVersion) return "reactVersion";
+  if (manifest.reactDomVersion !== keys.reactDomVersion) return "reactDomVersion";
+  if (manifest.reactRefreshVersion !== keys.reactRefreshVersion)
+    return "reactRefreshVersion";
+  if (manifest.manduCoreVersion !== keys.manduCoreVersion)
+    return "manduCoreVersion";
+  return null;
+}
+
+/** SHA-256 of a buffer, returned as a hex string. */
+function sha256(buf: Buffer | Uint8Array): string {
+  const h = createHash("sha256");
+  h.update(buf);
+  return h.digest("hex");
+}