makersclaw 0.5.2 → 0.7.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,87 @@ 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.
+
+/**
+ * The mode files/ is: a Next server in the workspace. Every other mode is
+ * files/ with some fixed files replaced and some left out (template.json
+ * `modes`), and an app says which in makersclaw.json `mode` (absent: this
+ * one). Browser mode (0.7.0, claw's STATIC-SPEC §3): the app's code runs
+ * in the member's browser, from files the platform serves, and every read
+ * and write goes through the platform's data door. So it lays no
+ * proxy.js, no /claw-alive, no pg (lib/db.js) and no server reads of the
+ * brain (lib/brain-server.js).
+ */
+export const BASE_MODE = "server";
+
+/**
+ * A mode's overlay and drop list, checked against the base's files. Pure:
+ * names in, the first thing wrong thrown, nothing returned. `base` is the
+ * base's files ({ path, class }), `overlay` the paths under the mode's
+ * overlay folder, `drop` the base paths the mode leaves out.
+ *   - No file is both dropped and overlaid: a mode lays a file or leaves
+ *     it out, never both.
+ *   - Each overlay file is a fixed file of the base. The overlay replaces
+ *     what the check pins (and update lays again); it adds no file, and
+ *     never a starter or a doc, which are the app's or read only.
+ *   - Each dropped file is a fixed file of the base: a drop the base does
+ *     not ship drops nothing, without a word, and only a pinned file is
+ *     the template's to remove from an app.
+ */
+export function checkMode(template, mode, { base, overlay, drop }) {
+  const fixed = new Set(base.filter((f) => f.class === "fixed").map((f) => f.path));
+  const dropped = new Set(drop);
+  for (const path of overlay) {
+    if (dropped.has(path)) throw new Error(`template ${template}: mode ${mode} both drops and overlays ${path} — a mode lays a file or leaves it out, not both`);
+    if (!fixed.has(path)) {
+      throw new Error(`template ${template}: mode ${mode} overlays ${path}, which is not a fixed file of files/ — an overlay replaces a fixed file and adds none`);
+    }
+  }
+  for (const path of drop) {
+    if (!fixed.has(path)) throw new Error(`template ${template}: mode ${mode} drops ${path}, which is not a fixed file of files/ — it would drop nothing`);
+  }
+}
+
+/** A mode's overlay folder: beside files/, a plain name. */
+const OVERLAY = /^[a-z]+$/;
+
+function loadModes(name, dir, meta, base) {
+  const modes = {};
+  for (const [mode, spec] of Object.entries(meta.modes ?? {})) {
+    if (!NAME.test(mode) || mode === BASE_MODE) throw new Error(`template ${name}: mode "${mode}" — ${BASE_MODE} is files/ itself, and a mode is named lowercase and dashed`);
+    const folder = spec?.overlay;
+    if (typeof folder !== "string" || !OVERLAY.test(folder) || folder === "files") {
+      throw new Error(`template ${name}: mode ${mode} names its overlay ${JSON.stringify(folder)} — a plain folder name beside files/`);
+    }
+    const root = join(dir, folder);
+    // A folder that is not there is an empty overlay: the mode only leaves
+    // files out. Browser mode's own files come after its drop list does.
+    const overlay = existsSync(root) ? walk(root) : [];
+    const drop = [...(spec.drop ?? [])];
+    checkMode(name, mode, { base, overlay, drop });
+    modes[mode] = { root, drop, files: overlay.map((path) => ({ path, class: "fixed", from: join(root, path) })) };
+  }
+  return modes;
+}
+
+/**
+ * The files a template lays in a mode: the base's, less the mode's drops,
+ * with the mode's copy in place of the base's where its overlay has one.
+ * The base mode is files/ as it is. null for a mode the template has not.
+ */
+export function modeFiles(template, mode = BASE_MODE) {
+  if (mode === BASE_MODE) return template.files;
+  const m = template.modes?.[mode];
+  if (!m) return null;
+  const over = new Map(m.files.map((f) => [f.path, f]));
+  const drop = new Set(m.drop);
+  return template.files.filter((f) => !drop.has(f.path)).map((f) => over.get(f.path) ?? f);
+}
+
 export function loadTemplate(name) {
   const dir = join(TEMPLATES, name);
   const meta = readJson(join(dir, "template.json"));
@@ -82,7 +163,50 @@ 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;
+  const modes = loadModes(name, dir, meta, files);
+  return { name, title: meta.title ?? name, description: meta.description ?? "", root, files, components, retired, lock, modes };
+}
+
+/** 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/browser/app/auto-refresh.jsx

@@ -0,0 +1,67 @@
+"use client";
+
+import { useEffect } from "react";
+import { claw } from "../lib/claw";
+import { dataChanged, whenLanded } from "../lib/door";
+import { changeFeed, refreshLoop } from "./frame";
+
+// A browser app's auto-refresh (makersclaw.json "mode": "browser"). Rows
+// change under this page from outside it: the agent writes them while
+// the founder watches, and so do jobs and other members. The page is
+// files, so there is nothing to re-render from a server: the hooks that
+// read the rows (lib/data's useRows and the rest, lib/brain.js's) read
+// again, and only when the data door says something changed.
+//
+// The rules are app/frame.js's (refreshLoop, and the reasons with each),
+// the server app's every one:
+//
+//   - only while the tab is visible AND the App tab is on screen: no timer
+//     at all otherwise, and coming back asks at once;
+//   - only while someone is there: after 30 minutes with no key, pointer,
+//     touch, wheel or focus in the app it stops, and the next sign asks
+//     at once;
+//   - only while the founder is not typing and no dialog is open
+//     (isEditing), and never while a surface has opted out with
+//     data-claw-refresh="off" on its root;
+//   - one tick at a time, the next timed once the last has landed: the
+//     interval plus what the last one took.
+//
+// What a tick does is this mode's own (changeFeed):
+//
+//   - it asks GET _claw/data/changes?since=<cursor>. The first answer
+//     only sets the cursor and the stamp of the app's own tables; after
+//     it, a brain change or a different stamp is a change;
+//   - a change is dataChanged(), every hook on the page reading again,
+//     and the tick lands when whenLanded() says they all have their new
+//     rows. A read that fails keeps the rows it had;
+//   - never router.refresh(): under an export it fetches the same
+//     prebuilt payload. Never /claw-alive: nothing in the machine answers
+//     for a browser app, and the door is the platform's.
+//
+// The feed's first answer is asked as the page mounts, not at the first
+// tick. That answer only sets where the feed is, so a change between it
+// and the tick would never count: asked five seconds late, it would hide
+// every change made while the page opened. This sits ahead of the Shell
+// in the layout and React runs effects in that order, so the ask goes
+// out before the surfaces' first reads: a change made in between is read
+// twice, not missed.
+export default function AutoRefresh() {
+  useEffect(() => {
+    const feed = changeFeed((path, signal) => claw(path, { signal }));
+    feed.probe();
+    const loop = refreshLoop({
+      doc: document,
+      probe: feed.probe,
+      refresh: () => {
+        feed.covered();
+        dataChanged();
+        return whenLanded();
+      },
+    });
+    return () => {
+      loop.stop();
+      feed.stop();
+    };
+  }, []);
+  return null;
+}