makersclaw 0.5.2 → 0.6.0

package/src/pm.mjs

@@ -0,0 +1,473 @@
+// The package manager behind `makersclaw install`: pnpm, laying npm's flat
+// node_modules with every file hard-linked from one store.
+//
+// Why pnpm, and why this way (plan 0.1, claw docs/BRAIN-AND-LIGHT-APPS-PLAN.md):
+// with npm every app on a machine holds its own copy of next (about 280 MB);
+// with one pnpm store the second app costs its folders and links. The
+// layout stays npm's (`node-linker=hoisted`: no symlinks, no .pnpm tree),
+// so everything that walks node_modules — Next, Turbopack, the check's
+// copy build, claw's `cp -al` staging — sees what it saw under npm.
+//
+// Which pnpm, in order:
+//   1. MAKERSCLAW_PNPM — the one the platform put on the machine (a
+//      binary, or a pnpm.cjs this node runs). Taken at any version.
+//   2. `pnpm` on PATH, when its major is PNPM_VERSION's: a lockfile's
+//      settings and frozen-install rules are a major's.
+//   3. `npm exec pnpm@PNPM_VERSION`, once: npm fetches that exact pnpm (or
+//      finds it in its cache) and says where it laid it, and this node runs
+//      that file from then on. No corepack: Node 25 stopped shipping it,
+//      and its key rotation in 2025 broke every `corepack pnpm` until
+//      upgraded.
+//   4. None of them: npm, said plainly. npm does not read pnpm-lock.yaml,
+//      so that install resolves from the registry, not the release lock.
+//      Not when npm could not reach the registry to fetch pnpm: npm would
+//      need the same registry, and fail after minutes of retries.
+//
+// The store: MAKERSCLAW_PNPM_STORE when set (claw sets one per VM),
+// pnpm's own default otherwise. Every setting that decides the layout is
+// passed on the command line, so an .npmrc cannot change it.
+
+import { spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { LOCKFILE, deriveLock, dropSnapshots, lockDifference, manifestDeps, parseLock, refToKey } from "./lockfile.mjs";
+
+/** The pnpm makersclaw installs with: the same major as makersclaw-store's
+ *  deps.mjs, lockfile 9.0. */
+export const PNPM_VERSION = "10.34.6";
+const PNPM_MAJOR = Number(PNPM_VERSION.split(".")[0]);
+
+/** npm's lock, which every app npm installed holds (every app before 0.6.0). */
+export const NPM_LOCKFILE = "package-lock.json";
+
+/** How pnpm lays an app. Each one is on the command line of every install. */
+export const PNPM_SETTINGS = [
+  "--config.node-linker=hoisted",
+  // Hard links on every filesystem. pnpm's default clones on APFS and
+  // btrfs; links make a Mac lay the way a Linux VM does, and `du` over a
+  // store and its apps counts each file once.
+  "--config.package-import-method=hardlink",
+  // The release lock's settings: a frozen install refuses a lock made
+  // with others.
+  "--config.auto-install-peers=true",
+  "--config.exclude-links-from-lockfile=false",
+  // An app npm installed before holds npm's node_modules; pnpm asks before
+  // replacing it, and with no terminal to ask on it fails instead.
+  "--config.confirm-modules-purge=false",
+  // An app's own "packageManager" field fetches nothing and refuses nothing.
+  "--config.manage-package-manager-versions=false",
+  "--config.package-manager-strict=false",
+  // Every package's install scripts run, as they did under npm. pnpm 10
+  // skips them unless told, and says so only in its log: a package that
+  // needs its build (better-sqlite3, @prisma/client, canvas) then installs
+  // "fine" and fails when the app runs. No package in the release has a
+  // script, so this reaches only the packages an app adds itself. A
+  // package that will be built is copied into node_modules, never
+  // hard-linked (pnpm imports it "clone-or-copy"), so its script cannot
+  // write into the store's files.
+  "--config.dangerously-allow-all-builds=true",
+  // An app laid inside someone's pnpm workspace installs itself, not the
+  // workspace around it.
+  "--ignore-workspace",
+  "--reporter=append-only",
+];
+
+// pnpm 10 turns on Node's compile cache in os.tmpdir() unless told not to
+// (makersclaw-store reports/store-pnpm.md); corepack's shim would ask
+// before a download, and nothing answers it here.
+const CHILD_ENV = { NODE_DISABLE_COMPILE_CACHE: "1", COREPACK_ENABLE_DOWNLOAD_PROMPT: "0" };
+const MAX_BUFFER = 64 * 1024 * 1024;
+
+const tail = (text, n = 15) =>
+  String(text ?? "")
+    .trim()
+    .split("\n")
+    .slice(-n)
+    .join("\n");
+
+const list = (names) => names.join(", ");
+
+function probe(cmd, args, env, timeout) {
+  const r = spawnSync(cmd, [...args, "--version"], { env: { ...env, ...CHILD_ENV }, encoding: "utf8", timeout });
+  if (r.error) return { error: r.error.code === "ENOENT" ? "not found" : r.error.message };
+  if (r.status !== 0) return { error: `exit ${r.status}: ${tail(r.stderr || r.stdout, 1) || "no output"}` };
+  const version = /(\d+\.\d+\.\d+\S*)\s*$/.exec(r.stdout.trim())?.[1];
+  return version ? { version } : { error: `no version in "${tail(r.stdout, 1)}"` };
+}
+
+// A socket error: the registry did not answer. npm would need it as much.
+const NETWORK = /\b(ECONNREFUSED|ECONNRESET|ENOTFOUND|EAI_AGAIN|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH|ENETDOWN)\b/;
+
+// Run by `npm exec`, whose PATH starts at the bin folder npm laid
+// pnpm@PNPM_VERSION in: print where that pnpm really is (its pnpm.cjs).
+const WHERE_PNPM = `const{delimiter,join}=require("node:path"),fs=require("node:fs");for(const d of(process.env.PATH||"").split(delimiter)){const p=join(d,"pnpm");if(fs.existsSync(p)){process.stdout.write(fs.realpathSync(p));break}}`;
+
+/** npm's own words for a failure: its error code and the line after it. */
+function npmFailure(output) {
+  const lines = String(output ?? "")
+    .split("\n")
+    .map((l) => l.replace(/^npm (?:error|ERR!) ?/, "").trim())
+    .filter((l) => l && !/^(?:errno|syscall|A complete log)/.test(l));
+  const at = lines.findIndex((l) => l.startsWith("code "));
+  return at >= 0 ? [lines[at].slice(5), lines[at + 1]].filter(Boolean).join(": ") : tail(lines.join("\n"), 1) || "no output";
+}
+
+/**
+ * The pnpm to run: { pnpm, tried, unreachable }. `pnpm` is { cmd, args,
+ * version, via } or null; `tried` has one line per door that did not
+ * answer; `unreachable` is the socket error npm met fetching pnpm, when
+ * that is why nothing answered.
+ */
+export function locatePnpm({ env = process.env } = {}) {
+  const tried = [];
+  const named = env.MAKERSCLAW_PNPM?.trim();
+  if (named) {
+    const byNode = /\.[cm]?js$/.test(named);
+    const cmd = byNode ? process.execPath : named;
+    const args = byNode ? [named] : [];
+    const p = probe(cmd, args, env, 30_000);
+    if (p.version) return { pnpm: { cmd, args, version: p.version, via: "MAKERSCLAW_PNPM" }, tried, unreachable: null };
+    tried.push(`MAKERSCLAW_PNPM (${named}): ${p.error}`);
+  }
+  const onPath = probe("pnpm", [], env, 30_000);
+  if (onPath.version && Number(onPath.version.split(".")[0]) === PNPM_MAJOR) return { pnpm: { cmd: "pnpm", args: [], version: onPath.version, via: "PATH" }, tried, unreachable: null };
+  tried.push(onPath.version ? `pnpm on PATH is ${onPath.version}, not ${PNPM_MAJOR}.x` : `pnpm on PATH: ${onPath.error}`);
+
+  // npm exec once, to learn where npm laid pnpm; this node runs that file
+  // from then on. The version is exact, so a copy in npm's cache is the
+  // right one: --prefer-offline asks the registry nothing then. Without it
+  // npm asked on every exec, and with the network down each ask took 71 s
+  // of retries before npm settled for its cache.
+  const door = `npm exec pnpm@${PNPM_VERSION}`;
+  const npx = spawnSync("npm", ["exec", "--yes", "--prefer-offline", `--package=pnpm@${PNPM_VERSION}`, "--", process.execPath, "-e", WHERE_PNPM], {
+    env: { ...env, ...CHILD_ENV },
+    encoding: "utf8",
+    timeout: 180_000,
+    maxBuffer: MAX_BUFFER,
+  });
+  const laid = npx.status === 0 ? npx.stdout.trim() : "";
+  if (laid) {
+    const p = probe(process.execPath, [laid], env, 30_000);
+    if (p.version) return { pnpm: { cmd: process.execPath, args: [laid], version: p.version, via: door }, tried, unreachable: null };
+    tried.push(`${door}: ${laid}: ${p.error}`);
+    return { pnpm: null, tried, unreachable: null };
+  }
+  if (npx.error) {
+    const timedOut = npx.error.code === "ETIMEDOUT";
+    tried.push(`${door}: ${npx.error.code === "ENOENT" ? "npm not found" : timedOut ? "no answer in 180 s" : npx.error.message}`);
+    return { pnpm: null, tried, unreachable: timedOut ? "npm exec timed out after 180 s" : null };
+  }
+  const output = `${npx.stdout ?? ""}${npx.stderr ?? ""}`;
+  tried.push(`${door}: ${npx.status === 0 ? "npm laid no pnpm" : `exit ${npx.status}: ${npmFailure(output)}`}`);
+  return { pnpm: null, tried, unreachable: npx.status === 0 ? null : (NETWORK.exec(output)?.[1] ?? null) };
+}
+
+/** The pnpm to run, or null; `tried` gets one line per door that did not
+ *  answer (scripts/lock.mjs and the tests read it this way). */
+export function findPnpm({ env = process.env, tried = [] } = {}) {
+  const r = locatePnpm({ env });
+  tried.push(...r.tried);
+  return r.pnpm;
+}
+
+/** Write a file through a new one and a rename, so a hard link to the old
+ *  file keeps the old bytes. */
+function replaceFile(path, bytes) {
+  const tmp = `${path}.makersclaw-${process.pid}`;
+  writeFileSync(tmp, bytes);
+  renameSync(tmp, path);
+}
+
+/**
+ * pnpm writes some of its records in node_modules over the old file, not
+ * beside it: `.modules.yaml` and `.pnpm-workspace-state-v1.json` (and
+ * trimCurrentLock below wrote `.pnpm/lock.yaml` the same way until it
+ * renamed). Where the tree was copied as hard links, as claw stages a
+ * working copy (`cp -al`), an install in the copy then rewrote the live
+ * app's records too, and they stopped describing its tree. So each record
+ * still shared with another folder gets a file of its own first. Package
+ * files need nothing: measured, pnpm replaces their folders and never
+ * writes into one. Returns how many it copied.
+ */
+export function unshareRecords(dir) {
+  const nm = join(dir, "node_modules");
+  const records = [];
+  for (const [folder, every] of [
+    [nm, false],
+    [join(nm, ".pnpm"), true],
+  ]) {
+    let names = [];
+    try {
+      names = readdirSync(folder);
+    } catch {
+      continue;
+    }
+    for (const name of names) if (every || name.startsWith(".")) records.push(join(folder, name));
+  }
+  let n = 0;
+  for (const path of records) {
+    try {
+      const st = lstatSync(path);
+      if (!st.isFile() || st.nlink < 2) continue;
+      replaceFile(path, readFileSync(path));
+      n++;
+    } catch {
+      // Left as it is: pnpm writes it as before.
+    }
+  }
+  return n;
+}
+
+/**
+ * pnpm 10's hoisted linker, installing over a tree it laid before, first
+ * lists that tree from its current lockfile (node_modules/.pnpm/lock.yaml)
+ * with the platform check off (lockfileToHoistedDepGraph builds prevGraph
+ * with force: true), and so fetches into the store every package it
+ * skipped as another platform's. For the release's versions that is Next's
+ * compiler for eight other platforms, and sharp's and lightningcss's:
+ * measured, a store of 473 MB became 1.4 GB on the next install that
+ * changed the tree (one package added to package.json). The list only
+ * decides which folders to remove, and a skipped package never had one;
+ * so the snapshots pnpm itself recorded as skipped
+ * (node_modules/.modules.yaml) are dropped from that file first. On any
+ * doubt the file stays as pnpm wrote it. Returns how many were dropped.
+ */
+export function trimCurrentLock(dir) {
+  try {
+    const path = join(dir, "node_modules", ".pnpm", "lock.yaml");
+    const modules = join(dir, "node_modules", ".modules.yaml");
+    if (!existsSync(path) || !existsSync(modules)) return 0;
+    const skipped = new Set(JSON.parse(readFileSync(modules, "utf8")).skipped ?? []);
+    const lock = parseLock(readFileSync(path, "utf8"));
+    const drop = new Set([...lock.snapshots.keys()].filter((key) => skipped.has(key)));
+    if (!drop.size) return 0;
+    const text = dropSnapshots(lock, drop);
+    // Every edge left must land on a snapshot: pnpm throws on one that
+    // does not (LockfileMissingDependencyError), and would on every install.
+    const trimmed = parseLock(text);
+    const roots = [...trimmed.importer.values()].flatMap((deps) => [...deps].map(([name, d]) => refToKey(name, d.version)));
+    const edges = [...trimmed.snapshots.values()].flatMap((s) => s.deps.map((d) => d.key));
+    if ([...roots, ...edges].some((key) => key !== null && !trimmed.snapshots.has(key))) return 0;
+    // Renamed into place, never written into: a copy of the tree made with
+    // hard links must keep its own.
+    replaceFile(path, text);
+    return drop.size;
+  } catch {
+    return 0;
+  }
+}
+
+/** Packages pnpm installed without running their install scripts, as
+ *  name@version: `ignoredBuilds` in node_modules/.modules.yaml. */
+export function ignoredBuilds(dir) {
+  try {
+    const ids = JSON.parse(readFileSync(join(dir, "node_modules", ".modules.yaml"), "utf8")).ignoredBuilds;
+    return Array.isArray(ids) ? ids.map(String) : [];
+  } catch {
+    return [];
+  }
+}
+
+/** name@version → name; a scoped name keeps its first "@". */
+const nameOf = (id) => {
+  const at = id.indexOf("@", 1);
+  return at === -1 ? id : id.slice(0, at);
+};
+
+/** The version part of an importer's reference: `1.2.0(react@19.3.0)` → 1.2.0. */
+const bareVersion = (ref) => {
+  const paren = ref.indexOf("(");
+  return paren === -1 ? ref : ref.slice(0, paren);
+};
+
+/**
+ * An app npm installed holds package-lock.json, and the packages the app
+ * added itself are pinned there, not in the release lock. pnpm reads only
+ * pnpm-lock.yaml, so its first install would resolve them again, to the
+ * newest in range. So, before it: `pnpm import` turns npm's lock into
+ * pnpm's (in a scratch folder, since it writes pnpm-lock.yaml), and the
+ * names pnpm-lock.yaml lacks are carried from it by the cut's own rule
+ * (deriveLock: not one whose peers resolved to another version than the
+ * lock's; that one is resolved again). Says what it did in a note; on any
+ * failure the lock stays as it was and the install resolves them.
+ */
+function seedFromNpmLock(dir, pnpm, pkg, env, settings, note) {
+  const npmPath = join(dir, NPM_LOCKFILE);
+  if (!existsSync(npmPath)) return;
+  let npm;
+  try {
+    npm = JSON.parse(readFileSync(npmPath, "utf8"));
+  } catch {
+    return;
+  }
+  const lockPath = join(dir, LOCKFILE);
+  let current = null;
+  if (existsSync(lockPath)) {
+    try {
+      current = parseLock(readFileSync(lockPath, "utf8"));
+    } catch {
+      // A lock this CLI cannot read is pnpm's to judge, not ours to replace.
+      return;
+    }
+  }
+  const npmVersion = (name) => npm?.packages?.[`node_modules/${name}`]?.version ?? npm?.dependencies?.[name]?.version ?? null;
+  const want = [];
+  for (const [section, deps] of manifestDeps(pkg)) {
+    for (const [name, spec] of deps) {
+      const d = current?.importer.get(section).get(name);
+      if ((!d || d.specifier !== spec) && npmVersion(name)) want.push({ section, name });
+    }
+  }
+  if (!want.length) return;
+  const names = want.map((w) => w.name).sort();
+  const scratch = mkdtempSync(join(tmpdir(), "makersclaw-import-"));
+  try {
+    for (const f of ["package.json", NPM_LOCKFILE, ".npmrc"]) if (existsSync(join(dir, f))) copyFileSync(join(dir, f), join(scratch, f));
+    const r = spawnSync(pnpm.cmd, [...pnpm.args, "import", ...settings], {
+      cwd: scratch,
+      env: { ...env, ...CHILD_ENV },
+      encoding: "utf8",
+      timeout: 180_000,
+      maxBuffer: MAX_BUFFER,
+    });
+    if (r.status !== 0 || !existsSync(join(scratch, LOCKFILE))) {
+      const why = r.error ? r.error.message : tail(`${r.stdout ?? ""}${r.stderr ?? ""}`, 1) || `exit ${r.status}`;
+      note(`${NPM_LOCKFILE} pins ${list(names)}; pnpm could not import it (${why}) — resolved again, the newest in range`);
+      return;
+    }
+    const importedText = readFileSync(join(scratch, LOCKFILE), "utf8");
+    const imported = parseLock(importedText);
+    const text = current ? deriveLock(current, pkg, imported).text : importedText;
+    const now = parseLock(text);
+    const kept = [];
+    const moved = [];
+    for (const { section, name } of want) {
+      const d = now.importer.get(section).get(name);
+      if (d && bareVersion(d.version) === npmVersion(name)) kept.push(`${name} ${npmVersion(name)}`);
+      else moved.push(`${name} (npm had ${npmVersion(name)})`);
+    }
+    if (text !== (current ? readFileSync(lockPath, "utf8") : null)) replaceFile(lockPath, text);
+    if (kept.length) note(`${LOCKFILE}: npm's versions kept from ${NPM_LOCKFILE}: ${list(kept.sort())}`);
+    if (moved.length) note(`${LOCKFILE}: resolved again, not at ${NPM_LOCKFILE}'s version: ${list(moved.sort())}`);
+  } catch (error) {
+    note(`${NPM_LOCKFILE} pins ${list(names)}; its versions could not be carried (${error.message}) — resolved again, the newest in range`);
+  } finally {
+    rmSync(scratch, { recursive: true, force: true });
+  }
+}
+
+// A frozen install that fails on these is the lock's fault, not the
+// network's: installing again without --frozen-lockfile mends it.
+const LOCK_ERRORS = /ERR_PNPM_(?:OUTDATED_LOCKFILE|LOCKFILE_CONFIG_MISMATCH|LOCKFILE_BREAKING_CHANGE|BROKEN_LOCKFILE|LOCKFILE_MISSING_DEPENDENCY)/;
+
+/**
+ * Install the app in `dir`: pnpm with its lock, or npm when no pnpm runs.
+ * Returns { ok, manager, version, via, frozen, store, why, unreachable,
+ * ignoredBuilds, notes, log, code }. `why` says why the install is not
+ * frozen (the lock's first difference from package.json); `unreachable`
+ * is set when no pnpm could be had because the registry did not answer
+ * (nothing was installed); `ignoredBuilds` lists packages whose install
+ * scripts did not run; `notes` say what the reader should know (a
+ * fallback, a retry, versions carried from package-lock.json, scripts).
+ */
+export function installDeps(dir, { env = process.env, onNote = () => {} } = {}) {
+  const pkg = JSON.parse(readFileSync(join(dir, "package.json"), "utf8"));
+  const notes = [];
+  const note = (line) => {
+    notes.push(line);
+    onNote(line);
+  };
+  const { pnpm, tried, unreachable } = locatePnpm({ env });
+
+  if (!pnpm && unreachable) {
+    // npm cannot fetch pnpm because the registry did not answer; npm's
+    // own install would ask the same registry for every package, retrying
+    // for minutes. Nothing is installed, and the reader hears why at once.
+    return { ok: false, code: null, manager: null, version: null, via: null, frozen: false, store: null, why: null, unreachable, ignoredBuilds: [], notes, log: tried.join("\n") };
+  }
+
+  if (!pnpm) {
+    note(`pnpm was not found (${tried.join(" · ")}) — installing with npm`);
+    if (existsSync(join(dir, LOCKFILE))) note(`npm does not read ${LOCKFILE}: versions come from the registry, not this release's lock`);
+    const npm = probe("npm", [], env, 30_000);
+    const r = spawnSync("npm", ["install", "--no-audit", "--no-fund"], { cwd: dir, env: { ...env, ...CHILD_ENV }, encoding: "utf8", maxBuffer: MAX_BUFFER });
+    const log = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+    return {
+      ok: r.status === 0,
+      code: r.status ?? (r.error ? r.error.code ?? -1 : -1),
+      manager: "npm",
+      version: npm.version ?? null,
+      via: "fallback",
+      frozen: false,
+      store: null,
+      why: "npm",
+      unreachable: null,
+      ignoredBuilds: [],
+      notes,
+      log: tail(r.error ? r.error.message : log),
+    };
+  }
+
+  const store = env.MAKERSCLAW_PNPM_STORE?.trim() || null;
+  const settings = [...PNPM_SETTINGS, ...(store ? [`--config.store-dir=${store}`] : [])];
+  const spawnPnpm = (args) => spawnSync(pnpm.cmd, [...pnpm.args, ...args, ...settings], { cwd: dir, env: { ...env, ...CHILD_ENV }, encoding: "utf8", maxBuffer: MAX_BUFFER });
+
+  seedFromNpmLock(dir, pnpm, pkg, env, settings, note);
+
+  let why = null;
+  if (!existsSync(join(dir, LOCKFILE))) why = `no ${LOCKFILE}`;
+  else {
+    try {
+      why = lockDifference(parseLock(readFileSync(join(dir, LOCKFILE), "utf8")), pkg);
+    } catch (error) {
+      why = `${LOCKFILE} is not one makersclaw reads (${error.message})`;
+    }
+  }
+  let frozen = why === null;
+  unshareRecords(dir);
+  // Only an install that changes the tree lists the old one; one that finds
+  // the tree as the lock says is "Already up to date", and a trim would
+  // make it relink everything.
+  const current = join(dir, "node_modules", ".pnpm", "lock.yaml");
+  if (!frozen || !existsSync(current) || readFileSync(current, "utf8") !== readFileSync(join(dir, LOCKFILE), "utf8")) trimCurrentLock(dir);
+  let r = spawnPnpm(["install", frozen ? "--frozen-lockfile" : "--no-frozen-lockfile"]);
+  let log = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+  if (frozen && r.status !== 0 && LOCK_ERRORS.test(log)) {
+    why = `pnpm refused the lock (${LOCK_ERRORS.exec(log)[0]})`;
+    note(`${why} — installing again without --frozen-lockfile, which rewrites ${LOCKFILE}`);
+    frozen = false;
+    r = spawnPnpm(["install", "--no-frozen-lockfile"]);
+    log = `${r.stdout ?? ""}${r.stderr ?? ""}`;
+  }
+
+  // An install that finds the tree as the lock says runs no scripts, so a
+  // package an earlier install left unbuilt (pnpm 10 before scripts were
+  // allowed here) stays unbuilt: rebuild those by name.
+  let skipped = r.status === 0 ? ignoredBuilds(dir) : [];
+  if (skipped.length) {
+    const b = spawnPnpm(["rebuild", ...new Set(skipped.map(nameOf))]);
+    log += `${b.stdout ?? ""}${b.stderr ?? ""}`;
+    if (b.status !== 0) r = b;
+    const still = ignoredBuilds(dir);
+    const ran = skipped.filter((id) => !still.includes(id));
+    if (b.status === 0 && ran.length) note(`ran the install scripts an earlier install skipped: ${list(ran)}`);
+    skipped = still;
+  }
+  if (skipped.length) note(`pnpm did not run the install scripts of ${list(skipped)} — ${skipped.length === 1 ? "it" : "they"} may fail when the app runs`);
+
+  return {
+    ok: r.status === 0,
+    code: r.status ?? -1,
+    manager: "pnpm",
+    version: pnpm.version,
+    via: pnpm.via,
+    frozen,
+    store,
+    why,
+    unreachable: null,
+    ignoredBuilds: skipped,
+    notes,
+    log: tail(r.error ? r.error.message : log),
+  };
+}

package/src/registry.mjs

@@ -51,6 +51,11 @@ export function templateNames() {
  */
 export const FILE_CLASSES = ["fixed", "docs", "starter", "merged"];
 
+// `files.retired` in template.json is not a class: it names fixed files an
+// earlier version laid that this one no longer ships (middleware.js, which
+// Next 16 renamed proxy.js). `update` removes them from an app that has
+// them pinned; nothing lays them.
+
 export function loadTemplate(name) {
   const dir = join(TEMPLATES, name);
   const meta = readJson(join(dir, "template.json"));
@@ -82,7 +87,49 @@ export function loadTemplate(name) {
     }),
     readme: null,
   }));
-  return { name, title: meta.title ?? name, description: meta.description ?? "", root, files, components };
+  const retired = [...(meta.files?.retired ?? [])];
+  for (const path of retired) {
+    if (files.some((f) => f.path === path)) throw new Error(`template ${name}: ${path} is retired and shipped — it cannot be both`);
+  }
+  // The release lock (0.6.0 on): beside files/, never laid as it is. Each
+  // app's pnpm-lock.yaml is cut from it (src/lockfile.mjs).
+  const lock = existsSync(join(dir, RELEASE_LOCK)) ? join(dir, RELEASE_LOCK) : null;
+  return { name, title: meta.title ?? name, description: meta.description ?? "", root, files, components, retired, lock };
+}
+
+/** The release lock's file, in templates/<name>/: made by `npm run lock`
+ *  (scripts/lock.mjs), shipped in the package with the template. */
+export const RELEASE_LOCK = "pnpm-lock.yaml";
+
+/**
+ * What the release lock resolves: the template's package.json, with every
+ * free block's packages beside its dependencies — one resolution, so two
+ * blocks that share a package share its version, and an app with any set
+ * of blocks is a part of it. Only the package's own blocks: premium blocks
+ * (MAKERSCLAW_BLOCKS_DIR) are the platform's, and this lock ships on npm.
+ * Throws when two blocks name one package at different versions.
+ */
+export function releaseManifest(template) {
+  const pkg = readJson(template.files.find((f) => f.class === "merged").from);
+  const dependencies = { ...(pkg.dependencies ?? {}) };
+  const from = Object.fromEntries(Object.keys(dependencies).map((d) => [d, "the template"]));
+  for (const block of loadBlocksFrom(BLOCKS, "free")) {
+    for (const [dep, spec] of Object.entries(block.dependencies)) {
+      if (dependencies[dep] !== undefined && dependencies[dep] !== spec) {
+        throw new Error(`${dep}: ${from[dep]} wants ${dependencies[dep]}, block ${block.name} wants ${spec} — one release resolves one version`);
+      }
+      dependencies[dep] = spec;
+      from[dep] ??= `block ${block.name}`;
+    }
+  }
+  const sorted = (o) => Object.fromEntries(Object.entries(o).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)));
+  return {
+    name: `makersclaw-${template.name}-release`,
+    private: true,
+    dependencies: sorted(dependencies),
+    ...(pkg.devDependencies ? { devDependencies: sorted(pkg.devDependencies) } : {}),
+    ...(pkg.optionalDependencies ? { optionalDependencies: sorted(pkg.optionalDependencies) } : {}),
+  };
 }
 
 let extraRoots = [];

package/templates/next/files/README.md

@@ -1,11 +1,11 @@
 # artifact template
 
-The app every artifact starts from: Next.js 15 (app router, JSX, server
-actions), Postgres via `DATABASE_URL`, Tailwind v4, and a kit of parts
-(`components/ui`, `components/parts`). It carries the behaviour every
-app shares, the parts every app is assembled from, and the workspace's
-colours. You design the surfaces: what is on them, how they are laid
-out, how dense, how they read — never what colour anything is.
+The app every artifact starts from: Next.js 16 (app router, JSX, server
+actions, Turbopack), Postgres via `DATABASE_URL`, Tailwind v4, and a kit
+of parts (`components/ui`, `components/parts`). It carries the behaviour
+every app shares, the parts every app is assembled from, and the
+workspace's colours. You design the surfaces: what is on them, how they
+are laid out, how dense, how they read — never what colour anything is.
 
 ## 1. What you are inside
 
@@ -74,8 +74,8 @@ components/parts/      the parts: RecordSwitcher, LiveEmpty + LiveWork, useFixtu
 check/pins.json        the fixed files by hash; `npm run check` refuses one that differs
 lib/*                  db, data, actions, claw, platform, hooks, sample (§5)
 check/                 `npm run check` (§6)
-middleware.js          product-token check, x-claw-surface and x-claw-theme headers
-next.config.mjs        basePath + Server Actions allowedOrigins, both from env (§4b)
+proxy.js               product-token check, x-claw-surface and x-claw-theme headers (Next 16's name for middleware.js)
+next.config.mjs        basePath + Server Actions allowedOrigins (and the dev server's allowedDevOrigins), from env (§4b)
 postcss.config.mjs     Tailwind v4
 schema.sql             public.artifact_activity, for reference
 ```
@@ -610,7 +610,7 @@ action="/…">`. A real external URL (`https://`, `mailto:`) is fine.
 
 Already handled. Do not fix it in `next.config.mjs`.
 
-Next 15 refuses a Server Action whose `Origin` header disagrees with
+Next refuses a Server Action whose `Origin` header disagrees with
 `x-forwarded-host`, and in this stack they always disagree: the sandbox
 ingress rewrites `x-forwarded-host` to its own vercel.run name while the
 browser is on the product host. Untreated, the app builds, loads and
@@ -620,7 +620,9 @@ button rather than a proxy policy.
 `next.config.mjs` already reads `CLAW_ALLOWED_ORIGINS`, which `product_run`
 derives per environment (`src/lib/products.ts`, `productAllowedOrigins`):
 the product's own FQDN in production, the dashboard's dev origin under a
-path prefix.
+path prefix. The same hosts are the dev server's `allowedDevOrigins`:
+Next 16's `next dev` refuses its own resources (the HMR socket, the error
+overlay) to any other host, and says "Blocked cross-origin request".
 
 **Never hardcode an origin here.** `allowedOrigins: ["localhost:5173"]`
 passes every test you can run in development and refuses every write in
@@ -665,7 +667,7 @@ key of the request, from `x-claw-surface`, unless one is passed).
 Each quotes names with `ident()`, writes one activity row through
 `logActivity`, calls `revalidatePath("/", "layout")`, and resolves
 `{ ok }` or `{ ok: false, error }`. Never throws. `surface` defaults to
-the request's surface (middleware sets it from `/s/<key>`).
+the request's surface (proxy.js sets it from `/s/<key>`).
 
 ```js
 updateRow({ source, idColumn = "id", id, patch, surface, action = "edited", detail, data })
@@ -996,9 +998,9 @@ files has to). The platform agent reads them as console events. Call
 line per rule, under twenty lines, exit 1 on a failure that names the
 file and line and what to use instead. It builds for itself, into
 `.next-check`, and only when a source changed since the last check —
-never run `npm run build` first, and never build into `.next`: the dev
-server product_run started owns that folder as another user, and a
-second build there dies with `EACCES: .next/trace`.
+never run `npm run build` first, and never build into `.next`: it is not
+the check's folder. In a working copy the preview's dev server owns it;
+in a live app it holds the build the platform made and serves.
 
 ```
 check: 5 files · 2 surfaces
@@ -1040,7 +1042,10 @@ surface; `--static` skips the build and the smoke. Then, by eye:
    `artifact_scaffold {dir}` runs it and makes `public.artifact_activity`
    in the workspace database). `makersclaw.json` records the version and
    the blocks; `makersclaw update` moves the fixed files and blocks to a
-   newer version and never touches your own files.
+   newer version and never touches your own files. `pnpm-lock.yaml` is
+   cut from the lock this version ships (by init, add and update), so
+   every app on the version installs the same packages;
+   `makersclaw install` installs from it. Never edit it by hand.
 2. `app_database {name, dir}` → `DATABASE_URL` in `.env`. The app's role
    reads and writes every table in `public`.
 3. Make the domain tables with the `sql` verb (they land in `public`).

package/templates/next/files/app/claw-alive/route.js

@@ -4,8 +4,8 @@
 // before every refresh: only a 2xx from here means the refresh will get
 // its payload and not reload the frame (app/frame.js, answering, has the
 // story). It renders nothing and reads nothing, so the question costs the
-// app almost nothing; the middleware's token check still runs first, as
-// on every request.
+// app almost nothing; proxy.js's token check still runs first, as on
+// every request.
 //
 // A 204 and not the 404 of a path nobody serves: the browser logs every
 // 404 fetch as a console error, and an app that logs one every 5 s reads

package/templates/next/files/app/frame.js

@@ -142,9 +142,9 @@ export function nextRefreshIn(lastCostMs = 0) {
 }
 
 /** What to ask before a refresh: app/claw-alive/route.js, a fixed route
- *  that answers 204 with no body — no render, no database. The middleware
- *  checks the proxy's token first, as on every request, so a 204 says the
- *  page's own request would be answered too.
+ *  that answers 204 with no body — no render, no database. proxy.js
+ *  checks the product proxy's token first, as on every request, so a 204
+ *  says the page's own request would be answered too.
  *
  *  Not a path the app merely 404s. The first draft of 0.3.3 asked for a
  *  file under _next/static/ that no build writes and read the 404 as
@@ -172,8 +172,9 @@ export function probeUrl(doc) {
  *
  *  Why ask first: router.refresh() treats any answer that is not its own
  *  payload as "this is not my app any more" and loads the whole page
- *  again (Next 15, fetch-server-response.js: a non-OK or non-RSC response
- *  becomes a browser navigation). In the frame that reload wipes a
+ *  again (fetch-server-response.js: a non-OK or non-RSC response becomes
+ *  a browser navigation; Next 16's refresh reaches it through
+ *  ppr-navigations.js and still does). In the frame that reload wipes a
  *  half-typed field, and one 502 was enough (landing-page-reviewer,
  *  okr-tracker, 2026-09-24). So the probe says yes exactly where the
  *  refresh would not turn into a reload. Asking first leaves only the

package/templates/next/files/app/layout.jsx

@@ -20,8 +20,8 @@ export const metadata = { title: process.env.CLAW_PRODUCT || "Artifact" };
 // lib/claw.js, the product name, and data-theme. The theme follows the
 // desk: the OS window opens the app with ?theme=light|dark and the
 // product proxy repeats it as the x-claw-theme header on every request
-// (middleware.js explains); the claw_theme cookie covers a run without
-// the proxy. Dark when neither says — the desk is dark.
+// (proxy.js explains); the claw_theme cookie covers a run without
+// the product proxy. Dark when neither says — the desk is dark.
 //
 // The palette follows the WORKSPACE: <head> links `_claw/theme.css`, the
 // preset picked in System Settings → Appearance, served by the product