makersclaw 0.5.2 → 0.7.0

package/src/install.mjs

@@ -2,10 +2,21 @@
 // result and prints nothing: src/cli.mjs says it, as text or as --json.
 //
 // Two files record what an app holds:
-//   makersclaw.json   the template and version it was laid from, and each
-//                     block with the version it came from
+//   makersclaw.json   the template and version it was laid from, each
+//                     block with the version it came from, where its
+//                     tables live (`tables`: "own" or "public") and which
+//                     fixed files it runs on (`mode`: "server" or
+//                     "browser"). The rest of its keys are the app's
+//                     (`brain`: the platform's declaration; `moves`: a
+//                     store package's move map); every command keeps
+//                     them. `tables` is never "moved": that is the
+//                     platform's mode, and no command writes it
 //   check/pins.json   sha256 of every fixed file, the template's and the
 //                     blocks' — `npm run check` refuses one that differs
+// and a third says which package versions it installs:
+//   pnpm-lock.yaml    cut from the release lock for this package.json
+//                     (src/lockfile.mjs) by init, add and update; the
+//                     install writes in what the release does not lock
 //
 // Everything this CLI writes is FIXED (ours: pinned, replaced by update),
 // DOCS (ours, not pinned), a STARTER (laid when missing, the app's from
@@ -15,7 +26,9 @@
 import { existsSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { hashFile, readJson, removeFile, sha256, walk, writeFile, writeJson } from "./fsutil.mjs";
-import { BLOCK_DIR, loadBlocks, loadItems, loadTemplate, packageInfo, readmeOf, suggest, templateNames } from "./registry.mjs";
+import { LOCKFILE, LockError, deriveLock, parseLock } from "./lockfile.mjs";
+import { NPM_LOCKFILE, PNPM_VERSION, installDeps } from "./pm.mjs";
+import { BASE_MODE, BLOCK_DIR, loadBlocks, loadItems, loadTemplate, modeFiles, packageInfo, readmeOf, suggest, templateNames } from "./registry.mjs";
 
 export const MANIFEST = "makersclaw.json";
 export const PINS = "check/pins.json";
@@ -62,6 +75,7 @@ function readState(dir) {
 
 function requireManifest(dir) {
   const state = readState(dir);
+  if (state.manifest?.tables === MOVED) throw movedManifest();
   if (!state.manifest) {
     const hasApp = existsSync(join(dir, "package.json"));
     throw new CliError(
@@ -74,6 +88,142 @@ function requireManifest(dir) {
   return state;
 }
 
+/** Where an app's tables live: "own", its own schema (app_<name>), or
+ *  "public", the workspace schema every app shared before 0.7.0. */
+const TABLES = ["own", "public"];
+
+/**
+ * The platform's third mode (claw's MIGRATE-SPEC M17 and §10): a legacy
+ * app whose tables the workspace's move put in its own schema, while its
+ * code still names public. The platform holds it (the app's blueprint,
+ * claw.app_roles); the app's makersclaw.json keeps "public" (or no key)
+ * until its rebuild writes "own". So no command writes "moved": `init
+ * --tables moved` is refused, and so is every command over a manifest
+ * that says it, rather than write it back.
+ */
+const MOVED = "moved";
+const MOVED_WHY = "moved is the platform's mode, never a manifest's";
+function movedManifest() {
+  return new CliError(
+    `${MANIFEST} says tables "moved": ${MOVED_WHY}`,
+    `set "tables" to "public" (or take the key out, for an app laid before 0.7.0): a moved app's code still names public, and its rebuild sets "own"`,
+  );
+}
+
+/**
+ * A makersclaw.json a lay wrote. Every lay since 0.2.0 records the
+ * `version` it laid, so a manifest without one was written by someone
+ * else first: the platform writes its `brain` declaration into a
+ * work-first app's new manifest before that app's first `init`
+ * (APPS-SPEC 4.2). Such a manifest's keys are kept like any other's, but
+ * it is no record of an app from before 0.7.0.
+ */
+function writtenByLay(manifest) {
+  return Boolean(manifest) && Object.hasOwn(manifest, "version");
+}
+
+/**
+ * The `tables` init writes. It never flips an app: an app's tables move
+ * from public to their own schema only with its workspace (the platform's
+ * move), never because a refresh ran `init --force`. So an app's
+ * makersclaw.json keeps its value — an absent key in a manifest a lay
+ * wrote is an app from before 0.7.0, on public — and a `--tables` that
+ * says otherwise is refused. Where no lay wrote a makersclaw.json (there
+ * is none, or it holds only the platform's keys) and it names no tables,
+ * there is no record to keep: a new app is "own" unless told, and an app
+ * laid before makersclaw kept one is "public" unless told (the platform,
+ * which holds the truth, always tells).
+ */
+function tablesFor(dir, before, asked) {
+  if (asked === MOVED) throw new CliError(`--tables moved: ${MOVED_WHY}`, `leave --tables out: a moved app keeps its makersclaw.json's "public" until its rebuild sets "own"`);
+  if (before.manifest?.tables === MOVED) throw movedManifest();
+  if (asked !== undefined && !TABLES.includes(asked)) {
+    throw new CliError(`--tables takes ${TABLES.join(" or ")}, not "${asked}"`, "own: the app's tables in its own schema (every new app) · public: an app from before 0.7.0");
+  }
+  const named = Boolean(before.manifest) && Object.hasOwn(before.manifest, "tables");
+  if (!named && !writtenByLay(before.manifest)) return asked ?? (existsSync(join(dir, "package.json")) ? "public" : "own");
+  const had = named ? before.manifest.tables : "public";
+  if (!TABLES.includes(had)) {
+    throw new CliError(`${MANIFEST} says tables ${JSON.stringify(had)}; an app's tables are ${TABLES.join(" or ")}`, `set "tables" in ${MANIFEST} to the one the platform holds for this app`);
+  }
+  if (asked !== undefined && asked !== had) {
+    throw new CliError(
+      (named ? `this app's tables are ${had}, not ${asked}` : `${MANIFEST} names no tables, so this app's are public (laid before 0.7.0), not ${asked}`) +
+        (had === "public" ? ": an app's tables move from public to their own schema only with its workspace" : ": an app on its own schema never goes back to public"),
+      `leave --tables out, or pass --tables ${had}` + (named ? "" : `; if its tables are already in its own schema, put "tables": "own" back in ${MANIFEST}`),
+    );
+  }
+  return had;
+}
+
+/** Which fixed files an app runs on: "server", a Next server in the
+ *  workspace (files/ as it is; an absent key, every app before 0.7.0), or
+ *  "browser", code that runs in the member's browser: files the platform
+ *  serves, reading and writing through its data door (template.json
+ *  `modes.browser`). */
+const MODES = [BASE_MODE, "browser"];
+
+/** The app's mode, from its makersclaw.json. Anything but the two is
+ *  refused: which fixed files to lay depends on it. */
+function modeOf(manifest) {
+  const mode = manifest && Object.hasOwn(manifest, "mode") ? manifest.mode : BASE_MODE;
+  if (!MODES.includes(mode)) {
+    throw new CliError(`${MANIFEST} says mode ${JSON.stringify(mode)}; an app's mode is ${MODES.join(" or ")}`, `makersclaw mode <${MODES.join("|")}> sets the one the platform holds for this app`);
+  }
+  return mode;
+}
+
+/**
+ * The `mode` init writes. Like `tables`, init never changes an app's: a
+ * refresh is claw's `init --force` over the app it has, and a flip there
+ * would turn a server app into a browser one whose Server Actions then fail
+ * its export. So a manifest that names a mode keeps it, whoever wrote it,
+ * and so does one a lay wrote (absent: server); a --mode that differs is
+ * refused, and `makersclaw mode` is the one switch. A new manifest takes
+ * --mode's value, and with none no key: an absent mode is server, the
+ * CLI's own default, because outside Makersclaw no door answers a browser
+ * app. { mode, key }: the app's mode, and the value to write (undefined:
+ * the key stays as it is).
+ */
+function modeFor(before, asked) {
+  if (asked !== undefined && !MODES.includes(asked)) {
+    throw new CliError(`--mode takes ${MODES.join(" or ")}, not "${asked}"`, "server: a Next server in the workspace (the default) · browser: its code runs in the member's browser, and every read and write goes through the platform's data door");
+  }
+  const named = Boolean(before.manifest) && Object.hasOwn(before.manifest, "mode");
+  if (!named && !writtenByLay(before.manifest)) return { mode: asked ?? BASE_MODE, key: asked };
+  const had = modeOf(before.manifest);
+  if (asked !== undefined && asked !== had) {
+    throw new CliError(
+      `this app is a ${had} app, not ${asked}: an app changes mode only with makersclaw mode`,
+      `leave --mode out, or run makersclaw mode ${asked}: it lays that mode's fixed files and says what the app's own code must change`,
+    );
+  }
+  return { mode: had, key: undefined };
+}
+
+/** A browser app's tables are its own: the door serves an app's own schema
+ *  and nothing else, so a browser app on public would read nothing. `how`
+ *  says where the pair came from, for the refusal's words. */
+function requireOwnTables(mode, tables, how) {
+  if (mode !== "browser" || tables === "own") return;
+  const why = "a browser app reads and writes only through the platform's data door, which serves an app's own schema and nothing else";
+  if (how === "flags") throw new CliError(`a browser app's tables are own, not ${tables}: ${why}`, "leave --tables out: --mode browser writes tables own");
+  if (how === "switch") {
+    throw new CliError(
+      `${tables === undefined ? `${MANIFEST} names no tables, so this app's are public (laid before 0.7.0)` : `this app's tables are ${tables}`}, not own: ${why}`,
+      "an app's tables move to their own schema only with its workspace (the platform's move); until then it stays a server app",
+    );
+  }
+  throw new CliError(`${MANIFEST} says mode browser and tables ${tables}: ${why}`, `if its tables are in its own schema, set "tables": "own"; if not, makersclaw mode server lays it as a server app`);
+}
+
+/** The files the template lays in this mode (registry modeFiles). */
+function modeFilesOrFail(tpl, mode) {
+  const files = modeFiles(tpl, mode);
+  if (!files) throw new CliError(`template ${tpl.name} has no ${mode} mode in makersclaw ${version()}`, `its modes: ${[BASE_MODE, ...Object.keys(tpl.modes ?? {})].join(", ")}`);
+  return files;
+}
+
 function loadTemplateOrFail(name) {
   const tpl = loadTemplate(name);
   if (!tpl) throw new CliError(`this makersclaw has no template "${name}"`, `templates: ${templateNames().join(", ")}`);
@@ -97,22 +247,84 @@ function mergePackage(app, tpl) {
   return { out, changes };
 }
 
-/** Paths a template may remove when a newer version stops shipping them:
- *  its fixed files and the kit, parts and block folders. Anything else a
- *  pins.json names is left alone — it is not ours to delete. */
+const releaseLocks = new Map();
+function releaseLock(tpl) {
+  if (!releaseLocks.has(tpl.lock)) releaseLocks.set(tpl.lock, parseLock(readFileSync(tpl.lock, "utf8")));
+  return releaseLocks.get(tpl.lock);
+}
+
+/**
+ * The app's pnpm-lock.yaml for `pkg`, cut from the template's release
+ * lock: { text, before, covered, carried, left, notes }, or null when the
+ * template ships no lock. The app's current lock lends what the release
+ * does not lock (src/lockfile.mjs says when); one this reader cannot take
+ * lends nothing, and the install resolves those packages again.
+ */
+function cutLock(dir, tpl, pkg) {
+  if (!tpl.lock || !pkg) return null;
+  const path = join(dir, LOCKFILE);
+  const before = existsSync(path) ? readFileSync(path, "utf8") : null;
+  const notes = [];
+  let current = null;
+  if (before !== null) {
+    try {
+      current = parseLock(before);
+    } catch (error) {
+      if (!(error instanceof LockError)) throw error;
+      notes.push(`${LOCKFILE} could not be read (${error.message}) — cut again from the release lock`);
+    }
+  }
+  const cut = deriveLock(releaseLock(tpl), pkg, current);
+  // The install resolves what is left; where npm installed the app before,
+  // at package-lock.json's versions when they still fit (src/pm.mjs).
+  const one = cut.left.length === 1;
+  const npmPinned = existsSync(join(dir, NPM_LOCKFILE)) ? `, keeping ${NPM_LOCKFILE}'s version${one ? "" : "s"} where ${one ? "it fits" : "they fit"}` : "";
+  if (cut.left.length) notes.push(`${LOCKFILE}: ${cut.left.join(", ")} not in makersclaw ${version()}'s lock — the install resolves ${one ? "it" : "them"}${npmPinned}`);
+  return { ...cut, before, notes };
+}
+
+/** Write the cut when it differs; say so in `written`. */
+function writeLock(dir, cut, written) {
+  if (!cut || cut.text === cut.before) return false;
+  writeFile(join(dir, LOCKFILE), cut.text);
+  written.push(LOCKFILE);
+  return true;
+}
+
+const lockSummary = (cut) => (cut ? { covered: cut.covered.length, carried: cut.carried, left: cut.left } : null);
+
+/** Paths a template may remove when a newer version stops shipping them,
+ *  or the app's mode stops laying them: its fixed files (the base's, so
+ *  the ones a mode drops too), the ones it names as retired (middleware.js
+ *  since 0.6.0: Next 16 fails a build that has it beside proxy.js), and
+ *  the kit, parts and block folders. Anything else a pins.json names is
+ *  left alone — it is not ours to delete. */
 function ownedPath(path, tpl) {
   if (/^components\/(?:ui|parts|blocks)\//.test(path) || /^lib\/[^/]+\.js$/.test(path)) return true;
+  if ((tpl.retired ?? []).includes(path)) return true;
   return tpl.files.some((f) => f.class === "fixed" && f.path === path);
 }
 
 /**
  * Lay a template — and the blocks the app already has — over `dir`: the
- * one routine behind init, init --force and update. Fixed files and docs
- * are replaced; starters are laid only when missing; package.json is
+ * one routine behind init, init --force, update and mode. Fixed files and
+ * docs are replaced; starters are laid only when missing; package.json is
  * merged; blocks come again from this version; what an older version
- * pinned and this one no longer ships is removed.
+ * pinned and this one no longer ships is removed. makersclaw.json is
+ * rewritten over what it held: `template`, `version` and `blocks` are
+ * this lay's, `tables` is init's (tablesFor; update leaves it as it was),
+ * `mode` is a new manifest's init's or `makersclaw mode`'s (modeFor), and
+ * every other key — the platform's `brain` declaration, one a later
+ * version adds — survives a refresh and an update. Until 0.7.0 it was
+ * rewritten as exactly those three, and a declaration was lost.
+ *
+ * The files are the app's mode's (modeFiles): a browser app gets the
+ * browser overlay's copy of a fixed file where there is one, and none of
+ * the files browser mode drops. The pins follow: a file the mode does not
+ * lay is not pinned, and one that was pinned is removed as a retired one
+ * is, so a switch of mode leaves only the new mode's fixed files.
  */
-function lay(dir, tpl, before) {
+function lay(dir, tpl, before, { tables, mode } = {}) {
   const v = version();
   const written = [];
   const kept = [];
@@ -122,7 +334,13 @@ function lay(dir, tpl, before) {
   const pins = {};
   const fresh = !existsSync(join(dir, "package.json"));
 
-  for (const f of tpl.files) {
+  // Decided before a file is written: a refused mode leaves the app as it was.
+  const keys = { ...(tables ? { tables } : {}), ...(mode ? { mode } : {}) };
+  const appMode = modeOf({ ...before.manifest, ...keys });
+  requireOwnTables(appMode, keys.tables ?? before.manifest?.tables ?? "public", "manifest");
+  const files = modeFilesOrFail(tpl, appMode);
+
+  for (const f of files) {
     const to = join(dir, f.path);
     if (f.class === "starter" && existsSync(to)) {
       kept.push(f.path);
@@ -187,6 +405,11 @@ function lay(dir, tpl, before) {
     }
   }
 
+  // The lock last: package.json is final now.
+  const cut = cutLock(dir, tpl, readJson(join(dir, "package.json")));
+  const lockWritten = writeLock(dir, cut, written);
+  if (cut) notes.push(...cut.notes);
+
   for (const p of Object.keys(before.pins)) {
     if (p in pins) continue;
     if (p.startsWith(`${BLOCK_DIR}/`) && !(p.split("/")[2] in blocks)) continue;
@@ -199,32 +422,45 @@ function lay(dir, tpl, before) {
       removed.push(p);
     }
   }
+  // A file the mode leaves out that no pin names is not the template's to
+  // delete (the app wrote it, or a hand laid it), but it is in the way:
+  // under output: "export" Next ignores a proxy.js, and lib/db.js is pg.
+  const laid = new Set(files.map((f) => f.path));
+  for (const f of tpl.files) {
+    if (f.class !== "fixed" || laid.has(f.path) || f.path in before.pins || !existsSync(join(dir, f.path))) continue;
+    notes.push(`${f.path}: ${appMode} mode lays none, and this one is not pinned — left alone; delete it unless the app's own code needs it`);
+  }
 
   writeJson(join(dir, PINS), sortKeys(pins));
-  writeJson(join(dir, MANIFEST), { template: tpl.name, version: v, blocks: sortKeys(blocks) });
+  const manifest = { ...before.manifest, template: tpl.name, version: v, blocks: sortKeys(blocks), ...keys };
+  writeJson(join(dir, MANIFEST), manifest);
   return {
     template: tpl.name,
     version: v,
+    // An absent key is an app from before 0.7.0: its tables are in public.
+    tables: manifest.tables ?? "public",
+    mode: appMode,
     from: before.manifest?.version ?? null,
     written,
     kept,
     removed,
     package: pkg,
-    install: fresh || pkg.some((c) => c.key !== "scripts"),
+    lock: lockSummary(cut),
+    install: fresh || lockWritten || pkg.some((c) => c.key !== "scripts"),
     pinned: Object.keys(pins).length,
     blocks: Object.keys(blocks),
     notes,
   };
 }
 
-/** `init [dir] [-t next] [--force]` */
-export function init(dir, { template = "next", force = false } = {}) {
+/** `init [dir] [-t next] [--force] [--tables own|public] [--mode browser|server]` */
+export function init(dir, { template = "next", force = false, tables, mode: askedMode } = {}) {
   const tpl = loadTemplateOrFail(template);
   const before = readState(dir);
   if (existsSync(join(dir, "package.json")) && !force) {
     throw new CliError(
       `${dir} already holds an app`,
-      before.manifest
+      writtenByLay(before.manifest)
         ? "makersclaw update lays this version over it"
         : "makersclaw init --force lays the template over it: fixed files and docs are replaced, your own files stay",
     );
@@ -232,7 +468,13 @@ export function init(dir, { template = "next", force = false } = {}) {
   if (before.manifest?.template && before.manifest.template !== template) {
     throw new CliError(`this app was laid from template "${before.manifest.template}", not "${template}"`, `makersclaw init --force -t ${before.manifest.template}`);
   }
-  return lay(dir, tpl, before);
+  // Decided before a file is written: a refused --tables or --mode leaves
+  // the app as it was. A new browser app's tables are own unless --tables
+  // says otherwise, and then it is refused.
+  const m = modeFor(before, askedMode);
+  const t = tablesFor(dir, before, tables ?? (m.key === "browser" ? "own" : undefined));
+  if (tables !== undefined) requireOwnTables(m.mode, t, "flags");
+  return lay(dir, tpl, before, { tables: t, mode: m.key });
 }
 
 /** `update [--major] [--adopt]` — this version's fixed files, docs and
@@ -269,6 +511,57 @@ export function update(dir, { major = false, adopt = false } = {}) {
   return lay(dir, tpl, before);
 }
 
+/** What an app's own code must change when it moves to a mode. The
+ *  template lays the fixed files; the surfaces are the app's, and move in
+ *  the same build (claw's STATIC-SPEC §3, "What the Builder is told"). */
+export const MODE_CHANGES = {
+  browser: [
+    'every surface a client component ("use client") that reads through the lib/data hooks (useRows, useRow, useCount, useCountBy, useActivity) and writes through lib/actions; a hook compares its options on every render (a time in filter or since to the minute), so anything else worked out per render (a Date.now() number) is worked out once, with useMemo',
+    "view state (?row=) from useSearchParams(): a browser app's page is a file built once and has no request, so a surface gets no searchParams",
+    "a write of more than one row is a function in the app's schema ((args jsonb) returns jsonb), called with runAction and named in references/actions.md",
+    'no server code of its own: no "use server" module, no route.js under app/, no proxy.js or middleware.js, no import of next/headers, next/cache, next/server, pg or lib/db',
+    "no export const dynamic, revalidate, fetchCache, runtime or dynamicParams in the app's own files",
+    "no process.env in the app's own code but CLAW_BASE_PATH, CLAW_PRODUCT and NEXT_PUBLIC_*: a prerendered page prints what it reads into a file anyone who opens the app can fetch",
+  ],
+  server: [
+    "lib/data.js is the server's again (pg, next/headers): a client surface takes its hooks from lib/door.js, or becomes a server component that calls loadRows",
+    "lib/actions.js is Server Actions again: a client surface calls them as it did",
+    "server code the app needs (a route handler, a Server Action of its own) may come back",
+  ],
+};
+
+/**
+ * `mode <browser|server>` — the one switch of an app's mode. It sets
+ * `mode` in makersclaw.json, lays that mode's fixed files, removes the
+ * other mode's (as update removes a retired file), and says what the
+ * app's own code must change. Browser needs `tables: "own"`: the door
+ * serves only an app's own schema. The app must be on this version, as
+ * for add: the switch lays this version's fixed files.
+ */
+export function mode(dir, to) {
+  if (to === undefined) throw new CliError("name a mode: browser or server", "makersclaw mode browser · makersclaw mode server");
+  if (!MODES.includes(to)) throw new CliError(`an app's mode is ${MODES.join(" or ")}, not "${to}"`, "server: a Next server in the workspace · browser: its code runs in the member's browser, and every read and write goes through the platform's data door");
+  const before = requireManifest(dir);
+  const { manifest } = before;
+  const v = version();
+  if (manifest.version !== v) {
+    throw new CliError(
+      `this app is on makersclaw ${manifest.version}; this is ${v}, and a switch of mode lays this version's fixed files`,
+      newer(manifest.version, v)
+        ? `npx makersclaw@${manifest.version} mode ${to}`
+        : compatible(manifest.version, v)
+          ? `makersclaw update first (${manifest.version} → ${v} is compatible), then mode ${to}`
+          : `makersclaw update --major first (makersclaw diff shows what changes), then mode ${to}`,
+    );
+  }
+  const tpl = loadTemplateOrFail(manifest.template);
+  // Not checked: a mode this CLI cannot read is what the switch mends.
+  const was = Object.hasOwn(manifest, "mode") ? manifest.mode : BASE_MODE;
+  requireOwnTables(to, manifest.tables, "switch");
+  const r = lay(dir, tpl, before, { mode: to });
+  return { ...r, was, changed: was !== to, change: MODE_CHANGES[to] };
+}
+
 function importFor(item) {
   if (item.type === "block") {
     const names = item.exports?.length ? item.exports.join(", ") : "…";
@@ -295,6 +588,9 @@ export function add(dir, names) {
   }
   const tpl = loadTemplateOrFail(manifest.template);
   const items = loadItems(tpl);
+  // A kit component is restored from the app's mode's copy of its file.
+  const appMode = modeOf(manifest);
+  const laid = new Map(modeFilesOrFail(tpl, appMode).map((f) => [f.path, f.from]));
   const order = [];
   const seen = new Set();
   const visit = (name, by) => {
@@ -319,7 +615,9 @@ export function add(dir, names) {
     const files = [];
     let changed = 0;
     for (const f of item.files) {
-      const bytes = readFileSync(f.from);
+      const from = item.type === "block" ? f.from : laid.get(f.to);
+      if (!from) throw new CliError(`${item.name}: ${f.to} is not laid in ${appMode} mode`);
+      const bytes = readFileSync(from);
       const hash = sha256(bytes);
       if (hashFile(join(dir, f.to)) !== hash) {
         writeFile(join(dir, f.to), bytes);
@@ -355,13 +653,19 @@ export function add(dir, names) {
     if (changes.length) writeJson(path, out);
     pkg = changes;
   }
+  // A block's packages come with their lock entries: the release resolved
+  // them with everything else, so the next install is frozen.
+  const cut = cutLock(dir, tpl, readJson(join(dir, "package.json")));
+  const lockWritten = writeLock(dir, cut, []);
   writeJson(join(dir, PINS), sortKeys(pins));
   writeJson(join(dir, MANIFEST), { ...manifest, blocks: sortKeys(manifest.blocks) });
   return {
     version: v,
     added,
     package: pkg,
-    install: pkg.length > 0,
+    lock: cut ? { ...lockSummary(cut), written: lockWritten } : null,
+    notes: cut?.notes ?? [],
+    install: pkg.length > 0 || lockWritten,
     usage: order.filter((i) => i.type === "block" && names.includes(i.name)).map((i) => ({ name: i.name, readme: readmeOf(i) })),
   };
 }
@@ -423,6 +727,8 @@ export function diff(dir) {
   const { manifest, pins } = requireManifest(dir);
   const tpl = loadTemplateOrFail(manifest.template);
   const v = version();
+  const appMode = modeOf(manifest);
+  const files = modeFilesOrFail(tpl, appMode);
   const entries = [];
   const statusOf = (path, have, want, pinned) => {
     if (have === want) return null;
@@ -431,12 +737,14 @@ export function diff(dir) {
     return "changed";
   };
 
-  for (const f of tpl.files) {
+  // The app's mode's files: update lays those, and removes a pinned file
+  // the mode does not lay ("dropped").
+  for (const f of files) {
     if (f.class !== "fixed" && f.class !== "docs") continue;
     const status = statusOf(f.path, hashFile(join(dir, f.path)), sha256(readFileSync(f.from)), f.class === "fixed" ? pins[f.path] : null);
     if (status) entries.push({ item: "template", path: f.path, status });
   }
-  const shipped = new Set(tpl.files.map((f) => f.path));
+  const shipped = new Set(files.map((f) => f.path));
   for (const p of Object.keys(pins)) {
     if (!p.startsWith(`${BLOCK_DIR}/`) && !shipped.has(p) && ownedPath(p, tpl)) entries.push({ item: "template", path: p, status: "dropped" });
   }
@@ -464,12 +772,43 @@ export function diff(dir) {
   // …and the installed blocks' npm packages, which update lays with them.
   const blockDeps = Object.assign({}, ...Object.keys(manifest.blocks ?? {}).map((n) => known.find((b) => b.name === n)?.dependencies ?? {}));
   if (existsSync(pkgPath) && Object.keys(blockDeps).length) pkg.push(...mergePackage(readJson(pkgPath), { dependencies: blockDeps }).changes);
+  // …and the lock update would cut for the package.json it would leave.
+  if (existsSync(pkgPath) && tplPkg) {
+    const after = mergePackage(mergePackage(readJson(pkgPath), readJson(tplPkg.from)).out, { dependencies: blockDeps }).out;
+    const cut = cutLock(dir, tpl, after);
+    if (cut && cut.text !== cut.before) entries.push({ item: "template", path: LOCKFILE, status: cut.before === null ? "new" : "changed" });
+  }
   return {
     from: manifest.version,
     to: v,
     compatible: compatible(manifest.version, v) && !newer(manifest.version, v),
+    mode: appMode,
     entries,
     package: pkg,
     blocks: manifest.blocks ?? {},
   };
 }
+
+/** `install` — the app's packages: pnpm from its lock, frozen when the
+ *  lock names exactly package.json's dependencies (src/pm.mjs); npm when
+ *  no pnpm runs, said in `notes` — but not when the registry did not
+ *  answer, since npm would need it too. */
+export function install(dir, { env = process.env, onNote } = {}) {
+  if (!existsSync(join(dir, "package.json"))) {
+    throw new CliError(`${dir} has no package.json — there is no app here`, "makersclaw init lays the template here");
+  }
+  const r = installDeps(dir, { env, onNote });
+  if (r.unreachable) {
+    throw new CliError(
+      `no pnpm on this machine, and npm could not fetch pnpm ${PNPM_VERSION}: the registry did not answer (${r.unreachable}). An npm install would need the same registry, so nothing was installed\n${r.log}`,
+      `name a pnpm ${PNPM_VERSION.split(".")[0]} in MAKERSCLAW_PNPM or put one on PATH, or install again once the registry answers`,
+    );
+  }
+  if (!r.ok) {
+    throw new CliError(
+      `${r.manager} install failed (exit ${r.code})${r.notes.length ? ` — ${r.notes.join("; ")}` : ""}${r.log ? `\n${r.log}` : ""}`,
+      r.manager === "pnpm" && r.frozen ? "a frozen install needs every package in the store or the registry" : null,
+    );
+  }
+  return r;
+}