projectstore-claude 0.29.3 → 0.30.0

package/node_modules/projectstore/scripts/codemap.mjs

@@ -79,19 +79,34 @@ function main() {
     lines.push(`| [[${folder.path}/${e.id}/epic\\|${e.id}]] | ${e.title} | ${e.status} | ${refs} |`);
   }
   if (storyRows.length) {
-    lines.push("", "## Story-level refs (files each story touched)", "",
-      "| Epic | Story | code_refs |", "|------|-------|-----------|");
+    lines.push(
+      "",
+      "## Story-level refs (files each story touched)",
+      "",
+      "| Epic | Story | code_refs |",
+      "|------|-------|-----------|",
+    );
     for (const s of storyRows) {
       lines.push(`| ${s.epic} | ${s.title} | ${s.refs.map((r) => `\`${r}\``).join(", ")} |`);
     }
   }
   lines.push("");
 
-  process.stdout.write(JSON.stringify({
-    path: join(cfg.vault_path, "code-map.md"),
-    content: lines.join("\n"),
-    stats: { epics: epics.length, epics_with_refs: epics.filter((e) => e.refs.length).length, story_rows: storyRows.length },
-  }, null, 2) + "\n");
+  process.stdout.write(
+    JSON.stringify(
+      {
+        path: join(cfg.vault_path, "code-map.md"),
+        content: lines.join("\n"),
+        stats: {
+          epics: epics.length,
+          epics_with_refs: epics.filter((e) => e.refs.length).length,
+          story_rows: storyRows.length,
+        },
+      },
+      null,
+      2,
+    ) + "\n",
+  );
 }
 
 if (isMain(import.meta.url)) {

package/node_modules/projectstore/scripts/convergence.mjs

@@ -12,12 +12,14 @@
 //   decide({ copies, version, read, skipped, verb, args })
 //                                     → stop or proceed, with the stop's texts
 //   proceedCase(decision, v)          → the words a newer row adds when not stopped
-//   channelChoices({ harness, s, copy, running, gate }) → the ways this release
-//                                       offers to settle a project's channel (rule
-//                                       2's helper: the gate's text, and a newer copy's)
-//   newerCopyDeferral({ copy, running, decision, harness, s })
+//   channelChoices({ harness, copy, running, gate, pin }) → the ways to settle a
+//                                       project's channel (rule 2's helper: the
+//                                       gate's text, and a newer copy's): setup's
+//   pinFor(root, version)             → the version a command names: the running
+//                                       one, on a package root
+//   newerCopyDeferral({ copy, running, decision, harness, pin })
 //                                     → a newer copy not switched off: { reason, advice }
-//   switchConsequence(harness)        → a switch row's consequence line (rule 2)
+//   switchConsequence()               → a switch row's consequence line (rule 2)
 //   switchReason({ copy, running, runs, decision, unbound })
 //                                     → what a switch row adds under the channel "npm"
 //   noCopyToKeep({ harness, surface, off }) → the channel "git" with nothing to keep
@@ -39,15 +41,23 @@
 //
 // Imports lib, harness, portable-registration and surfaces, never the fetch
 // or the host runner: every spawn and resolver is the caller's. Only the
-// installer imports this file; doctor, lib and the hooks never do, so the
-// SessionStart graph never loads it (tests/convergence.test.mjs asserts
-// both). Pure node, no external deps — the read is Node's own fetch.
+// installer and setup's front-end (setup.mjs, which reads the running copies
+// before its questions) import this file; doctor, lib and the hooks never do,
+// so the SessionStart graph never loads it (tests/convergence.test.mjs
+// asserts both). Pure node, no external deps — the read is Node's own fetch.
 
-import { readFileSync, mkdirSync, existsSync, realpathSync } from "node:fs";
+import { readFileSync, mkdirSync, realpathSync } from "node:fs";
 import { dirname, join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
-import { cmpPrecedence, installChannel, projectCopiesByKey, writeFileAtomic, envFlag } from "./lib.mjs";
-import { loadHarness, loadHarnesses, packageCommand } from "./harness.mjs";
+import {
+  cmpPrecedence,
+  installChannel,
+  projectCopiesByKey,
+  writeFileAtomic,
+  envFlag,
+  isEphemeralRoot,
+} from "./lib.mjs";
+import { loadHarness, loadHarnesses } from "./harness.mjs";
 import { analysePortableRegistration, portableRegistrationPaths } from "./portable-registration.mjs";
 import { registrationPaths } from "./surfaces.mjs";
 
@@ -65,6 +75,11 @@ export const ACCEPT = "application/vnd.npm.install-v1+json";
 // resolver's own 10 s (REGISTRY_BUDGET_MS, fetch-shell.mjs) before it.
 export const READ_TIMEOUT_MS = 2000;
 export const NOTICE_BUDGET_MS = 2000;
+// What the resolver leaves of a shared bound is no time for a request below
+// this: no registry answers in less, and the resolver's timer and Date.now()
+// round differently, so a resolver that took the whole bound can read as one
+// that left 1 ms of it.
+export const MIN_READ_MS = 50;
 export const FRESH_MS = 24 * 60 * 60 * 1000;
 export const NO_CHECK_ENV = "PROJECTSTORE_NO_UPDATE_CHECK";
 
@@ -72,13 +87,25 @@ export const NO_CHECK_ENV = "PROJECTSTORE_NO_UPDATE_CHECK";
 // anything else counts as missing — never printed, never compared.
 const NUM = "(?:0|[1-9]\\d*)";
 const PRE = `(?:${NUM}|\\d*[A-Za-z-][0-9A-Za-z-]*)`;
-const SEMVER = new RegExp(`^${NUM}\\.${NUM}\\.${NUM}(?:-${PRE}(?:\\.${PRE})*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$`);
+const SEMVER = new RegExp(
+  `^${NUM}\\.${NUM}\\.${NUM}(?:-${PRE}(?:\\.${PRE})*)?(?:\\+[0-9A-Za-z-]+(?:\\.[0-9A-Za-z-]+)*)?$`,
+);
 export const isSemver = (v) => typeof v === "string" && SEMVER.test(v);
 
 // ─── Which roots check (rule 6) and show the notice (rule 8) ────────────
 
-const real = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
-const within = (root, dir) => { const r = real(root), d = real(dir); return r === d || r.startsWith(d + sep); };
+const real = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+};
+const within = (root, dir) => {
+  const r = real(root),
+    d = real(dir);
+  return r === d || r.startsWith(d + sep);
+};
 
 // A copy a host runs, updated through its own channel (layout spec contract
 // 12): never stopped, never told to update. installChannel names the host's
@@ -130,7 +157,10 @@ export const updateCheckOff = (env) => envFlag(env, NO_CHECK_ENV);
 // - a portable registration: the global registration's recorded version,
 //   when it is effectively enabled for this project.
 // `analyse(harness, s)` lets the caller share one analysis with the fetch.
-export function runningCopies(projectDir, { harnesses = [], root, home = homedir(), env = process.env, channel = null, version = null, analyse = null } = {}) {
+export function runningCopies(
+  projectDir,
+  { harnesses = [], root, home = homedir(), env = process.env, channel = null, version = null, analyse = null } = {},
+) {
   const out = [];
   for (const id of harnesses) {
     const harness = loadHarness(id);
@@ -140,10 +170,13 @@ export function runningCopies(projectDir, { harnesses = [], root, home = homedir
       if (s.format === "host-plugin-registration") {
         if (channel === "git") continue;
         for (const e of projectCopiesByKey(home, projectDir)) {
-          if (typeof e.version === "string" && e.version) out.push({ harness: id, key: e.key, version: e.version, path: e.path, scope: e.scope, own: e.own });
+          if (typeof e.version === "string" && e.version)
+            out.push({ harness: id, key: e.key, version: e.version, path: e.path, scope: e.scope, own: e.own });
         }
       } else if (s.format === "portable-plugin-registration") {
-        const a = analyse ? analyse(harness, s) : analysePortableRegistration(projectDir, s, { root, home, harness, env, version });
+        const a = analyse
+          ? analyse(harness, s)
+          : analysePortableRegistration(projectDir, s, { root, home, harness, env, version });
         const v = a?.ownership?.version;
         if (typeof v === "string" && v && a.enabled) out.push({ harness: id, key: a.id, version: v });
       }
@@ -152,7 +185,8 @@ export function runningCopies(projectDir, { harnesses = [], root, home = homedir
   return out;
 }
 
-export const newerCopies = (copies, version) => (version ? copies.filter((c) => cmpPrecedence(c.version, version) > 0) : []);
+export const newerCopies = (copies, version) =>
+  version ? copies.filter((c) => cmpPrecedence(c.version, version) > 0) : [];
 // The lowest of them: a fresh cache entry below it is read again (rule 8).
 export const lowestVersion = (copies) => copies.map((c) => c.version).sort(cmpPrecedence)[0] || null;
 
@@ -163,7 +197,9 @@ function readCache(cachePath) {
   try {
     const c = JSON.parse(readFileSync(cachePath, "utf8"));
     return c && typeof c === "object" && !Array.isArray(c) ? c : {};
-  } catch { return {}; }
+  } catch {
+    return {};
+  }
 }
 
 // Fresh for a day; an `at` in the future is stale (a clock that moved back).
@@ -178,29 +214,44 @@ function fresh(entry, t) {
 // its connection is released.
 function request(url, { fetch, timers, timeoutMs }) {
   return new Promise((settle) => {
-    let done = false, timer = null;
+    let done = false,
+      timer = null;
     const ac = typeof AbortController === "function" ? new AbortController() : null;
     const finish = (r) => {
       if (done) return;
       done = true;
-      if (timer !== null) { try { timers.clearTimeout(timer); } catch {} }
+      if (timer !== null) {
+        try {
+          timers.clearTimeout(timer);
+        } catch {}
+      }
       settle(r);
     };
     timer = timers.setTimeout(() => {
       timer = null;
-      try { ac?.abort(); } catch {}
+      try {
+        ac?.abort();
+      } catch {}
       finish({ error: `no answer within ${timeoutMs / 1000} s` });
     }, timeoutMs);
-    try { timer?.unref?.(); } catch {}
+    try {
+      timer?.unref?.();
+    } catch {}
     Promise.resolve()
       .then(() => fetch(url, { headers: { accept: ACCEPT }, ...(ac ? { signal: ac.signal } : {}) }))
       .then(async (res) => {
         if (!res || !res.ok) {
-          try { Promise.resolve(res?.body?.cancel?.()).catch(() => {}); } catch {}
+          try {
+            Promise.resolve(res?.body?.cancel?.()).catch(() => {});
+          } catch {}
           return finish({ error: `HTTP ${res?.status ?? "error"}` });
         }
         let body;
-        try { body = await res.json(); } catch { return finish({ error: "the answer is not JSON" }); }
+        try {
+          body = await res.json();
+        } catch {
+          return finish({ error: "the answer is not JSON" });
+        }
         const latest = body && typeof body === "object" ? body["dist-tags"]?.latest : undefined;
         if (!isSemver(latest)) return finish({ error: "the answer names no dist-tags.latest" });
         finish({ latest });
@@ -217,7 +268,15 @@ function request(url, { fetch, timers, timeoutMs }) {
 function writeCache(cachePath, cache, registry, latest, at) {
   if (!cachePath) return;
   const prev = cache.user_latest && typeof cache.user_latest === "object" ? cache.user_latest : null;
-  const next = { ...cache, [registry]: { latest, at }, user_latest: { latest, at, published_at: prev && prev.latest === latest && typeof prev.published_at === "string" ? prev.published_at : null } };
+  const next = {
+    ...cache,
+    [registry]: { latest, at },
+    user_latest: {
+      latest,
+      at,
+      published_at: prev && prev.latest === latest && typeof prev.published_at === "string" ? prev.published_at : null,
+    },
+  };
   try {
     mkdirSync(dirname(cachePath), { recursive: true });
     writeFileAtomic(cachePath, JSON.stringify(next, null, 2) + "\n", { sweep: false });
@@ -230,7 +289,17 @@ function writeCache(cachePath, cache, registry, latest, at) {
 // `atLeast`, the lowest newer copy rule 6 asks about: a release may have come
 // out since it was written. The cache never supplies a URL: an entry is only
 // looked up with the registry this run resolved. Never throws.
-export async function readLatest({ registry, cachePath = null, fetch = globalThis.fetch, now = Date.now, timers = globalThis, timeoutMs = READ_TIMEOUT_MS, atLeast = null } = {}) {
+/* eslint-disable n/no-unsupported-features/node-builtins -- the global fetch is experimental but present at Node 20 and stable from 21; without it readLatest answers "no fetch in this Node", and the suite runs it on Node 20 in CI */
+export async function readLatest({
+  registry,
+  cachePath = null,
+  fetch = globalThis.fetch,
+  now = Date.now,
+  timers = globalThis,
+  timeoutMs = READ_TIMEOUT_MS,
+  atLeast = null,
+} = {}) {
+  /* eslint-enable n/no-unsupported-features/node-builtins */
   try {
     const cache = readCache(cachePath);
     const entry = cache[registry];
@@ -261,13 +330,22 @@ export function coreCommand(verb, { version = null, args = "" } = {}) {
 // part on its own line — the envelope's form, which an agent relays as it
 // is; `advice` is what PLAN draws, the commands in their own blocks.
 export function advised(text, blocks = []) {
-  return { reason: [text, ...blocks.flatMap((b) => [b.lead, b.command])].join("\n"), advice: { text, blocks } };
+  return {
+    reason: [text, ...blocks.flatMap((b) => [b.lead, b.command])]
+      .filter((x) => x !== null && x !== undefined)
+      .join("\n"),
+    advice: { text, blocks },
+  };
 }
 
 // The run's own selection, repeated: --harness and --surface as given, and
 // --no-register; never --project (the ADR's decision 5).
 function runArgs({ harnesses = [], surfaces = null, register = true } = {}) {
-  return [...harnesses.map((h) => `--harness ${h}`), ...(surfaces || []).map((s) => `--surface ${s}`), ...(register === false ? ["--no-register"] : [])].join(" ");
+  return [
+    ...harnesses.map((h) => `--harness ${h}`),
+    ...(surfaces || []).map((s) => `--surface ${s}`),
+    ...(register === false ? ["--no-register"] : []),
+  ].join(" ");
 }
 
 // Stop when the registry's latest is at least a newer copy this project runs
@@ -276,12 +354,21 @@ function runArgs({ harnesses = [], surfaces = null, register = true } = {}) {
 // readLatest's answer, null when nothing was read; `skipped` says the read
 // was switched off by PROJECTSTORE_NO_UPDATE_CHECK. The refusal's text puts
 // each command on a line of its own, never followed by punctuation.
-export function decide({ copies = [], version = null, read = null, skipped = false, verb = "upgrade", args = {} } = {}) {
+export function decide({
+  copies = [],
+  version = null,
+  read = null,
+  skipped = false,
+  verb = "upgrade",
+  args = {},
+} = {}) {
   const newer = newerCopies(copies, version);
   const decision = { checks: true, version, newer, read: skipped ? { skipped: true } : read, stop: null };
   const latest = read && isSemver(read.latest) ? read.latest : null;
   if (skipped || !latest) return decision;
-  const top = newer.filter((c) => cmpPrecedence(latest, c.version) >= 0).sort((a, b) => cmpPrecedence(b.version, a.version))[0];
+  const top = newer
+    .filter((c) => cmpPrecedence(latest, c.version) >= 0)
+    .sort((a, b) => cmpPrecedence(b.version, a.version))[0];
   if (!top) return decision;
   const lead = `this project runs ${PACKAGE} ${top.version} (${top.key}), newer than this package (${version}), and ${top.version} is published. Nothing is written. Run the newer one from a terminal in this project:`;
   const commands = [coreCommand(verb, { version: "latest", args: runArgs(args) }), `npm install -g ${PACKAGE}@latest`];
@@ -294,7 +381,8 @@ export function decide({ copies = [], version = null, read = null, skipped = fal
 // `v`: the dry run's note when no decision was made (plan reads nothing), none
 // for a root that never checks, else what the read found.
 export function proceedCase(decision, v) {
-  if (decision === null || decision === undefined) return `install and upgrade read the registry first, and stop when ${v} is published`;
+  if (decision === null || decision === undefined)
+    return `install and upgrade read the registry first, and stop when ${v} is published`;
   if (!decision.checks) return null;
   const r = decision.read;
   if (!r) return null;
@@ -304,55 +392,79 @@ export function proceedCase(decision, v) {
   return `${v} is published (the registry's latest is ${r.latest})`;
 }
 
-// Rule 2's helper: the ways this release offers to settle which copy a
-// project runs, when a copy from another marketplace is enabled for it. Only
-// verbs this release has are named, never `setup`, which does not exist yet;
-// the setup story replaces both branches below with its own commands
-// (`npx projectstore setup`, and its `--channel npm` and `--channel git`),
-// here and nowhere else.
-// - `gate` ({ verb, args, keys }): the channel gate's text (rule 2). A switch
-//   planned under no channel answer is a choice made at a terminal, and this
-//   release has no verb that takes the answer without one, so it names the
-//   terminal run of the same verb with the run's own --harness and --surface,
-//   in the core form (rule 9).
-// - otherwise, a newer copy that is not switched off (rule 6): the copy's own
-//   bin in the layout remedy's form (layout spec contract 12), which converges
-//   the project on that copy; and the host's own disable, built from the
-//   manifest as a plan step is, which leaves the project to this package's
-//   registration on the next run.
-export function channelChoices({ harness = null, s = null, copy = null, running = null, gate = null } = {}) {
+// The version a command a person runs next names (the setup story, rule 17;
+// the converge story's review follow-up): the running version on a package
+// root — npx's cache, a node_modules — so a run of `npx projectstore@0.30.0`
+// is answered by commands that run 0.30.0 again, never whatever is latest. A
+// checkout or a host's own copy names none.
+export function pinFor(root, version) {
+  return version && root && isEphemeralRoot(root) ? version : null;
+}
+
+// Rule 2's helper: the ways to settle which copy a project runs, when a copy
+// from another marketplace is enabled for it — setup's own commands (the
+// setup story, rule 17): the terminal run, `npx projectstore setup`, which
+// asks, then the two runs that name the answer without a terminal, `--channel
+// npm` and `--channel git`, each alone on its line (a `|` copied into a shell
+// is a pipe). Each names `@<version>` when the pin says so (pinFor), and
+// never --project (the ADR's decision 5).
+// - `gate` ({ args: { harnesses }, keys, version }): the channel gate's text
+//   (rule 2), for a switch planned under no channel answer without a
+//   terminal, the run's own --harness repeated in each command. setup takes
+//   no --surface, so a narrowed run's --surface is not repeated. A block with
+//   no lead follows the one before it.
+// - otherwise, a newer copy that is not switched off (rule 6), for `harness`:
+//   keeping it lets that copy write this project's surfaces (the keep), and
+//   switching runs this older package — both named, after the terminal run.
+export function channelChoices({ harness = null, copy = null, running = null, gate = null, pin = null } = {}) {
   if (gate) {
     const from = gate.keys?.length ? ` (${gate.keys.join(", ")})` : "";
-    return [{ lead: `Nothing written: this project loads ${PACKAGE} from the git marketplace${from}, and moving it to the npm install is a choice made at a terminal in this project:`, command: coreCommand(gate.verb || "upgrade", { args: runArgs(gate.args || {}) }) }];
+    const run = (extra = "") =>
+      coreCommand("setup", {
+        version: gate.version || null,
+        args: [runArgs({ harnesses: gate.args?.harnesses || [] }), extra].filter(Boolean).join(" "),
+      });
+    return [
+      {
+        lead: `Nothing written: this project loads ${PACKAGE} from the git marketplace${from}, and moving it to the npm install is a choice made at a terminal in this project:`,
+        command: run(),
+      },
+      { lead: "Without a terminal, name the channel:", command: run("--channel npm") },
+      { lead: null, command: run("--channel git") },
+    ];
   }
-  const blocks = [];
-  const bin = copy?.path ? join(copy.path, "bin", "projectstore.mjs") : null;
-  if (bin && existsSync(bin)) blocks.push({ lead: "Run the newer copy instead, from a terminal in this project:", command: `node "${bin}" upgrade --harness ${harness.id} --no-register` });
-  const disable = s?.cli?.commands?.disable;
-  if (Array.isArray(disable) && disable.length && s.cli.bin) {
-    const argv = disable.map((t) => t.replace(/\{(\w+)\}/g, (_, k) => (k === "other" || k === "id" ? copy.key : `{${k}}`)));
-    blocks.push({ lead: `Or move this project to this package's registration, the older ${running}: turn that copy off for this project, then repeat this run:`, command: [s.cli.bin, ...argv].join(" ") });
-  }
-  return blocks;
+  const run = (extra = "") =>
+    coreCommand("setup", { version: pin, args: [`--harness ${harness.id}`, extra].filter(Boolean).join(" ") });
+  return [
+    { lead: "Choose at a terminal in this project; setup asks whether to keep that copy or switch:", command: run() },
+    {
+      lead: `Without a terminal, keep ${copy?.key || "that copy"}, which then writes this project's surfaces itself:`,
+      command: run("--channel git"),
+    },
+    {
+      lead: `Or move this project to this package's npm install, the older ${running}:`,
+      command: run("--channel npm"),
+    },
+  ];
 }
 
 // A newer copy from another marketplace under channel null: not switched
 // off, because switching it off would run the project on an older package.
 // The rows name both versions and the case, then the ways out.
-export function newerCopyDeferral({ copy, running, decision, harness, s }) {
+export function newerCopyDeferral({ copy, running, decision, harness, pin = null }) {
   const c = proceedCase(decision, copy.version);
   const text = `this project runs a newer copy (${copy.key} ${copy.version}) than this package (${running}), so it is not switched off${c ? ` — ${c}` : ""}.`;
-  return advised(text, channelChoices({ harness, s, copy, running }));
+  return advised(text, channelChoices({ harness, copy, running, pin }));
 }
 
 // The consequence line of a switch (rule 2; presentation spec contract 7):
 // the ADR's three facts — the git-marketplace copy is off for this project,
 // the host's update no longer reaches it, and what updates it from now on —
 // with no backticks, and no command followed by punctuation. The command is
-// packageCommand's, so it keeps the shell form until the text-cleanup story
-// moves it (rule 9's command-form rule).
-export function switchConsequence(harness) {
-  return `this project stops loading the git-marketplace copy, and /plugin update no longer reaches it — from now on it is updated by ${packageCommand(harness, "upgrade")}`;
+// setup's, in the core form and unpinned (the setup story, rule 17): what
+// updates the project from now on is whichever version runs it next.
+export function switchConsequence() {
+  return `this project stops loading the git-marketplace copy, and /plugin update no longer reaches it — from now on it is updated by ${coreCommand("setup")}`;
 }
 
 // The words a switch row adds under the channel "npm" (rules 2 and 6): over a
@@ -367,7 +479,9 @@ export function switchReason({ copy, running, runs = running, decision, unbound
   // would be false.
   if (copy && typeof copy.version === "string" && runs && cmpPrecedence(copy.version, runs) > 0) {
     const c = proceedCase(decision, copy.version);
-    parts.push(`${copy.key} ${copy.version} is newer than this package (${running})${c ? ` — ${c}` : ""}; turning it off runs this project on the older ${runs}`);
+    parts.push(
+      `${copy.key} ${copy.version} is newer than this package (${running})${c ? ` — ${c}` : ""}; turning it off runs this project on the older ${runs}`,
+    );
   }
   if (unbound) parts.push("the project is not bound yet: the switch is recorded in its binding once it is");
   return parts.length ? parts.join("; ") : null;
@@ -380,9 +494,18 @@ export function switchReason({ copy, running, runs = running, decision, unbound
 // npm row leaves — is turned back on in the host. Each command alone on its
 // line (presentation spec contract 6).
 export function noCopyToKeep({ harness, surface, off = [] }) {
-  const blocks = off.map((key) => ({ lead: `This checkout's local settings hold ${key} off. To load it again, run this in ${harness.display_name}:`, command: `/plugin enable ${key}` }));
-  blocks.push({ lead: "The way back from an earlier switch to the npm install is its uninstall, from a terminal in this project:", command: coreCommand("uninstall", { args: runArgs({ harnesses: [harness.id], surfaces: [surface] }) }) });
-  return advised(`no git-marketplace copy of ${PACKAGE} is enabled for this project, so there is none to keep. Nothing is written.`, blocks);
+  const blocks = off.map((key) => ({
+    lead: `This checkout's local settings hold ${key} off. To load it again, run this in ${harness.display_name}:`,
+    command: `/plugin enable ${key}`,
+  }));
+  blocks.push({
+    lead: "The way back from an earlier switch to the npm install is its uninstall, from a terminal in this project:",
+    command: coreCommand("uninstall", { args: runArgs({ harnesses: [harness.id], surfaces: [surface] }) }),
+  });
+  return advised(
+    `no git-marketplace copy of ${PACKAGE} is enabled for this project, so there is none to keep. Nothing is written.`,
+    blocks,
+  );
 }
 
 // ─── The keep (rule 5) ──────────────────────────────────────────────────
@@ -394,15 +517,29 @@ export function noCopyToKeep({ harness, surface, off = [] }) {
 // the status line would opt it in (rule 5). `process.execPath`, not `node`:
 // the Node that runs us is sure to exist, and the PLAN shows the argv verbatim.
 export function keepArgv(copy, { verb, harness, projectDir }) {
-  return [process.execPath, join(copy.path, "bin", "projectstore.mjs"), verb, "--harness", harness.id, "--no-register", "--json", "--project", projectDir];
+  return [
+    process.execPath,
+    join(copy.path, "bin", "projectstore.mjs"),
+    verb,
+    "--harness",
+    harness.id,
+    "--no-register",
+    "--json",
+    "--project",
+    projectDir,
+  ];
 }
 
 // The bin's `--json` envelope, `{ schema_version, verb, project, ok, result }`:
 // its `result`, or null when stdout holds none. The top-level `ok` is never
 // read — for plan it is `ok && !incomplete`, for a write verb the gate too.
 export function keepResult(stdout) {
-  let env = null;
-  try { env = JSON.parse(String(stdout || "").trim()); } catch { return null; }
+  let env;
+  try {
+    env = JSON.parse(String(stdout || "").trim());
+  } catch {
+    return null;
+  }
   const r = env && typeof env === "object" && !Array.isArray(env) ? env.result : null;
   return r && typeof r === "object" && !Array.isArray(r) ? r : null;
 }
@@ -422,17 +559,37 @@ export function keepResult(stdout) {
 export async function readKeepPlan(copy, { harness, projectDir, env, run, budget = 120000 } = {}) {
   const argv = keepArgv(copy, { verb: "plan", harness, projectDir });
   let r;
-  try { r = await run(argv[0], argv.slice(1), { env, cwd: projectDir, budget }); }
-  catch (e) { r = { status: null, stdout: "", stderr: "", error: e }; }
+  try {
+    r = await run(argv[0], argv.slice(1), { env, cwd: projectDir, budget });
+  } catch (e) {
+    r = { status: null, stdout: "", stderr: "", error: e };
+  }
   const status = r?.status ?? null;
   const stderr = String(r?.stderr || "").trim();
   const result = keepResult(r?.stdout);
-  if (!result) return { argv, envelope: false, status, stderr, error: r?.error ? String(r.error.message || r.error) : null };
+  if (!result)
+    return { argv, envelope: false, status, stderr, error: r?.error ? String(r.error.message || r.error) : null };
   const items = Array.isArray(result.items) ? result.items.filter((i) => i && typeof i === "object") : [];
-  const writes = items.filter((i) => !["skip", "refuse"].includes(i.action)).map((i) => ({ surface: String(i.surface ?? ""), action: String(i.action ?? ""), path: i.path ?? null }));
-  const refusals = [...(Array.isArray(result.refusals) ? result.refusals : []), ...items.filter((i) => i.action === "refuse").map((i) => i.reason)].filter((x) => typeof x === "string" && x);
-  const deferred = items.filter((i) => i.deferred === true).map((i) => ({ surface: String(i.surface ?? ""), reason: typeof i.reason === "string" ? i.reason : null }));
-  return { argv, envelope: true, ok: result.ok !== false, incomplete: result.incomplete === true, refusals, writes, deferred, status };
+  const writes = items
+    .filter((i) => !["skip", "refuse"].includes(i.action))
+    .map((i) => ({ surface: String(i.surface ?? ""), action: String(i.action ?? ""), path: i.path ?? null }));
+  const refusals = [
+    ...(Array.isArray(result.refusals) ? result.refusals : []),
+    ...items.filter((i) => i.action === "refuse").map((i) => i.reason),
+  ].filter((x) => typeof x === "string" && x);
+  const deferred = items
+    .filter((i) => i.deferred === true)
+    .map((i) => ({ surface: String(i.surface ?? ""), reason: typeof i.reason === "string" ? i.reason : null }));
+  return {
+    argv,
+    envelope: true,
+    ok: result.ok !== false,
+    incomplete: result.incomplete === true,
+    refusals,
+    writes,
+    deferred,
+    status,
+  };
 }
 
 // The kept copy's own upgrade, in the form channelChoices names a copy's bin:
@@ -440,19 +597,28 @@ export async function readKeepPlan(copy, { harness, projectDir, env, run, budget
 // preview and its own question (we never run what we could not preview,
 // install spec contract 9).
 export function ownUpgrade(copy, harness) {
-  return { lead: "Run that copy's own upgrade from a terminal in this project; it shows its own plan and asks:", command: `node "${join(copy.path, "bin", "projectstore.mjs")}" upgrade --harness ${harness.id} --no-register` };
+  return {
+    lead: "Run that copy's own upgrade from a terminal in this project; it shows its own plan and asks:",
+    command: `node "${join(copy.path, "bin", "projectstore.mjs")}" upgrade --harness ${harness.id} --no-register`,
+  };
 }
 
 // This checkout's npm registration enabled beside the kept copy: the keep
 // changes no registration, so it stays; its uninstall (rule 4) drops it.
 export function npmRowBeside({ harness, id, surface }) {
-  return { lead: `This checkout's npm registration (${id}) stays enabled beside the kept copy. To drop it, from a terminal in this project:`, command: coreCommand("uninstall", { args: runArgs({ harnesses: [harness.id], surfaces: [surface] }) }) };
+  return {
+    lead: `This checkout's npm registration (${id}) stays enabled beside the kept copy. To drop it, from a terminal in this project:`,
+    command: coreCommand("uninstall", { args: runArgs({ harnesses: [harness.id], surfaces: [surface] }) }),
+  };
 }
 
 // A newer registration that is damaged: never rewritten or staged over from
 // the older package; repaired from its own version.
 export function repairAdvice(harness, v) {
-  return { lead: "not downgraded — repair it from its own version:", command: coreCommand("upgrade", { version: v, args: `--harness ${harness.id}` }) };
+  return {
+    lead: "not downgraded — repair it from its own version:",
+    command: coreCommand("upgrade", { version: v, args: `--harness ${harness.id}` }),
+  };
 }
 
 // ─── The update notice (rule 8) ─────────────────────────────────────────
@@ -464,5 +630,9 @@ export function repairAdvice(harness, v) {
 export function updateNotice({ latest, version, root, verb = "upgrade" } = {}) {
   if (!isSemver(latest) || !version || cmpPrecedence(latest, version) <= 0) return null;
   const npx = /[\\/]_npx[\\/]/.test(String(root || ""));
-  return { latest, text: `newer published: ${latest} (this is ${version}). To update:`, command: npx ? coreCommand(verb, { version: "latest" }) : `npm install -g ${PACKAGE}@latest` };
+  return {
+    latest,
+    text: `newer published: ${latest} (this is ${version}). To update:`,
+    command: npx ? coreCommand(verb, { version: "latest" }) : `npm install -g ${PACKAGE}@latest`,
+  };
 }

package/node_modules/projectstore/scripts/diff-refs.mjs

@@ -112,14 +112,20 @@ function main() {
   ]);
   const files = filterFiles(committed);
 
-  const fallback = !range && !since || (files.length === 0 && uncommitted.length === 0);
-  process.stdout.write(JSON.stringify({
-    since: since || null,
-    range: usedRange,
-    files,
-    uncommitted,
-    fallback,
-  }, null, 2) + "\n");
+  const fallback = (!range && !since) || (files.length === 0 && uncommitted.length === 0);
+  process.stdout.write(
+    JSON.stringify(
+      {
+        since: since || null,
+        range: usedRange,
+        files,
+        uncommitted,
+        fallback,
+      },
+      null,
+      2,
+    ) + "\n",
+  );
 }
 
 if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {