fix(nix): fail fast on lockfile drift instead of letting bun hit the network

Two hook fixes for failure modes found installing opencode offline. Both
stem from the same bun behavior: any drift between package.json and
bun.lock makes bun re-resolve the affected dependencies, and re-resolving a
git/github/remote-tarball dependency downloads it unconditionally — fatal
in the sandbox no matter how complete the cache is.

- Detect trustedDependencies / patchedDependencies drift between the root
  package.json and bun.lock and fail with an actionable message (refresh
  bun.lock, regenerate bun.nix). Projects routinely commit a lockfile whose
  copies of these sections lag package.json (opencode's does); without the
  check the drift surfaces as a wall of ConnectionRefused errors at resolve
  time with no hint of the cause.
- Leave catalog: references pointing at non-registry specs (github:, git+,
  tarball URLs, file:) unrewritten. bun resolves those natively from the
  lockfile's catalog section; rewriting them to their resolution registered
  as a changed spec and forced a re-resolve.

The hook now runs the prep script whenever bun.lock exists (previously only
when it contained catalog: refs), so the drift check covers every project.

Author: typedrat

nix/mk-derivation/hook.sh

@@ -83,14 +83,14 @@ function bunPatchPhase {
   runHook postBunPatchPhase
 }
 
-# bun re-resolves `catalog:` dependency specifiers against the npm registry on
-# every `bun install`, even with a fully populated cache. In the Nix sandbox
-# this fails. The lockfile already records the exact resolved version for
-# every package, so rewrite every `catalog:` reference (in bun.lock's
-# `workspaces` section and in every workspace package.json) to that exact
-# version (or `workspace:*` for workspace packages) before `bun install`.
-function bunResolveCatalogRefs {
-  if ! [ -f bun.lock ] || ! grep -q '"catalog:' bun.lock 2>/dev/null; then
+# Prepare the project for offline install: rewrite `catalog:` references to
+# the exact versions recorded in bun.lock (bun re-resolves them against the
+# registry otherwise, which fails in the sandbox), and fail fast if bun.lock
+# has drifted from package.json (drift makes bun re-resolve, with the same
+# result). Runs whenever a lockfile exists — the drift check applies to every
+# project, not just those using catalogs.
+function bunPrepareOfflineInstall {
+  if ! [ -f bun.lock ]; then
     return 0
   fi
   # --config=/dev/null: ignore the project's bunfig.toml, which may remap
@@ -103,7 +103,7 @@ function bunNodeModulesInstallPhase {
   pushd "$bunRoot" || exit 1
   runHook preBunNodeModulesInstallPhase
 
-  bunResolveCatalogRefs
+  bunPrepareOfflineInstall
 
   # Remove patchedDependencies from package.json and bun.lock since we
   # pre-patch packages during the Nix build. This ensures bun looks for

nix/mk-derivation/resolve-catalog.ts

@@ -1,12 +1,21 @@
-// bun2nix: resolve `catalog:` specifiers to exact versions for offline install.
+// bun2nix: prepare the project for offline install.
 //
-// bun re-resolves `catalog:` dependency specifiers against the npm registry on
-// every `bun install`, even with a fully populated cache and
-// `--frozen-lockfile` / `--offline`. In the Nix sandbox this fails. The
-// lockfile already records the exact resolved version for every package, so
-// rewrite every `catalog:` reference (in bun.lock's `workspaces` section and
-// in every workspace package.json) to that exact version (or `workspace:*`
-// for workspace packages) before `bun install` runs.
+// Both steps exist because bun re-resolves any dependency whose recorded
+// state drifted from package.json — and re-resolving git/github/
+// remote-tarball deps downloads them unconditionally, which fails in the Nix
+// sandbox no matter how complete the cache is:
+//
+// 1. Resolve `catalog:` specifiers to exact versions (older bun re-resolves
+//    them against the registry on every `bun install`). Non-registry catalog
+//    values (github:/git+/tarball URLs) are left as `catalog:` — bun resolves
+//    those natively from the lockfile's catalog section, and rewriting them
+//    would itself register as a changed spec and force a re-resolve.
+// 2. Detect `trustedDependencies` / `patchedDependencies` drift between the
+//    root package.json and bun.lock, and fail with an actionable message.
+//    Projects routinely commit a bun.lock whose copies of these sections lag
+//    package.json; any mismatch makes bun distrust the lockfile mapping
+//    wholesale, and the resulting re-resolution surfaces as a wall of
+//    ConnectionRefused errors long after the actual cause.
 //
 // Invoked as: bun resolve-catalog.ts <bunRoot>
 
@@ -29,6 +38,8 @@ interface BunLock {
   catalog?: Deps;
   catalogs?: Record<string, Deps>;
   packages?: Record<string, [string, ...unknown[]]>;
+  trustedDependencies?: string[];
+  patchedDependencies?: Deps;
 }
 
 const depSections = [
@@ -42,7 +53,7 @@ const root = process.argv[2] ?? ".";
 const lockPath = join(root, "bun.lock");
 
 if (!existsSync(lockPath)) process.exit(0);
-if (!readFileSync(lockPath, "utf8").includes('"catalog:')) process.exit(0);
+const hasCatalogRefs = readFileSync(lockPath, "utf8").includes('"catalog:');
 
 // bun.lock is JSON-with-trailing-commas. Bun's module loader has a built-in
 // JSONC parser (used for tsconfig.json / bun.lock) that we can reach via
@@ -71,6 +82,20 @@ for (const [name, entry] of Object.entries(packages)) {
   resolved[name] = spec.slice(prefix.length);
 }
 
+// A spec whose resolution is not a plain registry version. Rewriting a
+// `catalog:` reference to one of these would change the dependency's spec
+// string and force bun to re-resolve (= re-download) it; bun resolves these
+// natively from the lockfile's catalog section, so leave them alone.
+function isNonRegistrySpec(spec: string): boolean {
+  return (
+    spec.startsWith("github:") ||
+    spec.startsWith("git+") ||
+    spec.startsWith("http://") ||
+    spec.startsWith("https://") ||
+    spec.startsWith("file:")
+  );
+}
+
 function cresolve(name: string, spec: string): string {
   const cname = spec.slice("catalog:".length);
   const table = cname === "" ? catalog : (catalogs[cname] ?? {});
@@ -79,6 +104,8 @@ function cresolve(name: string, spec: string): string {
   if (typeof cv === "string" && cv.startsWith("workspace:")) return cv;
   if (typeof rv === "string" && rv.startsWith("workspace:"))
     return "workspace:*";
+  if (typeof cv === "string" && isNonRegistrySpec(cv)) return spec;
+  if (typeof rv === "string" && isNonRegistrySpec(rv)) return spec;
   if (typeof rv === "string") return rv;
   if (typeof cv === "string") return cv;
   return spec;
@@ -99,25 +126,79 @@ function rewriteDeps(holder: DepHolder): boolean {
   return changed;
 }
 
-console.log("bun2nix: resolving catalog: specifiers from bun.lock");
-
-// Rewrite the lockfile's workspaces section.
 let lockChanged = false;
-for (const ws of Object.values(workspaces)) {
-  if (rewriteDeps(ws)) lockChanged = true;
+
+if (hasCatalogRefs) {
+  console.log("bun2nix: resolving catalog: specifiers from bun.lock");
+
+  // Rewrite the lockfile's workspaces section.
+  for (const ws of Object.values(workspaces)) {
+    if (rewriteDeps(ws)) lockChanged = true;
+  }
+
+  // Rewrite every workspace package.json (root "" + each workspace dir).
+  for (const wsDir of Object.keys(workspaces)) {
+    const pkgJson = join(root, wsDir, "package.json");
+    if (!existsSync(pkgJson)) continue;
+    const text = readFileSync(pkgJson, "utf8");
+    if (!text.includes('"catalog:')) continue;
+    const pkg = JSON.parse(text) as DepHolder;
+    if (rewriteDeps(pkg)) {
+      writeFileSync(pkgJson, JSON.stringify(pkg, null, 2) + "\n");
+    }
+  }
 }
+
 if (lockChanged) {
   writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n");
 }
 
-// Rewrite every workspace package.json (root "" + each workspace dir).
-for (const wsDir of Object.keys(workspaces)) {
-  const pkgJson = join(root, wsDir, "package.json");
-  if (!existsSync(pkgJson)) continue;
-  const text = readFileSync(pkgJson, "utf8");
-  if (!text.includes('"catalog:')) continue;
-  const pkg = JSON.parse(text) as DepHolder;
-  if (rewriteDeps(pkg)) {
-    writeFileSync(pkgJson, JSON.stringify(pkg, null, 2) + "\n");
+// Fail fast on trustedDependencies / patchedDependencies drift between the
+// root package.json and bun.lock. Compared as a set / as key-value pairs so
+// pure ordering differences don't trip the check.
+const rootPkgPath = join(root, "package.json");
+if (existsSync(rootPkgPath)) {
+  const rootPkg = JSON.parse(readFileSync(rootPkgPath, "utf8")) as {
+    trustedDependencies?: string[];
+    patchedDependencies?: Deps;
+  };
+
+  const drift: string[] = [];
+
+  const pkgTrusted = [...(rootPkg.trustedDependencies ?? [])].sort();
+  const lockTrusted = [...(lock.trustedDependencies ?? [])].sort();
+  if (JSON.stringify(pkgTrusted) !== JSON.stringify(lockTrusted)) {
+    const missing = pkgTrusted.filter((n) => !lockTrusted.includes(n));
+    const extra = lockTrusted.filter((n) => !pkgTrusted.includes(n));
+    drift.push(
+      `trustedDependencies differ` +
+        (missing.length
+          ? `; missing from bun.lock: ${missing.join(", ")}`
+          : "") +
+        (extra.length ? `; only in bun.lock: ${extra.join(", ")}` : ""),
+    );
+  }
+
+  const pkgPatched = rootPkg.patchedDependencies ?? {};
+  const lockPatched = lock.patchedDependencies ?? {};
+  const patchKeys = [
+    ...new Set([...Object.keys(pkgPatched), ...Object.keys(lockPatched)]),
+  ].sort();
+  const patchDiffs = patchKeys.filter((k) => pkgPatched[k] !== lockPatched[k]);
+  if (patchDiffs.length) {
+    drift.push(`patchedDependencies differ for: ${patchDiffs.join(", ")}`);
+  }
+
+  if (drift.length) {
+    console.error(`
+bun2nix: error: bun.lock is out of sync with package.json:
+${drift.map((d) => `  - ${d}`).join("\n")}
+
+bun re-resolves dependencies when these sections drift, and re-resolving
+git/github/tarball dependencies requires network access, which is not
+available in the Nix sandbox. Run \`bun install\` to refresh bun.lock,
+commit the result, and regenerate bun.nix.
+`);
+    process.exit(1);
   }
 }