projectstore-claude 0.29.2 → 0.29.3

package/node_modules/projectstore/scripts/surfaces.mjs

@@ -44,6 +44,7 @@ import {
   claudeHome,
   whichOnPath,
   installedPluginEntries,
+  projectCopiesByKey,
   pluginEnabled,
   treeDigest,
   packageDigest,
@@ -52,6 +53,7 @@ import {
   RUNTIME_GITIGNORE_HEADER,
   LAUNCHER_HEADER,
   commandForm,
+  registrationProvenance,
 } from "./lib.mjs";
 import { analysePortableRegistration, portableRegistrationPaths, portablePayloadRoot } from "./portable-registration.mjs";
 
@@ -89,7 +91,12 @@ export function isOurFile(text) {
 
 // ─── markdown-block: the ADR-002 block ─────────────────────────────────
 
-export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir = MANIFEST_DIR } = {}) {
+// `layout` names the roster the run leaves (a layout name; the binding's when
+// null). `readers` is a run's harnesses as [{ display, files }], passed when a
+// run names more than one: the migration reason then names the one whose
+// files lack the block's file, rather than the harness whose surface `s` is
+// (the story "One run plans the agents block once…", rules 1 and 3).
+export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir = MANIFEST_DIR, layout = null, readers = null } = {}) {
   const files = s.files || ["AGENTS.md", "CLAUDE.md"];
   const PREFERRED = files[0], FALLBACK = files[files.length - 1];
   // LOOK across every file any manifest names; WRITE to one this harness can
@@ -120,8 +127,9 @@ export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir =
   a.version = agentsBlockVersion(tmpl.text);
   const cfg = readConfigAt(projectDir);
   let roster = null;
-  if (cfg && typeof cfg.layout === "string") {
-    try { roster = loadLayout(cfg.layout, root).agents || null; } catch { roster = null; }
+  const name = layout ?? cfg?.layout;
+  if (typeof name === "string") {
+    try { roster = loadLayout(name, root).agents || null; } catch { roster = null; }
   }
   a.desired = renderAgentsBlock(tmpl.text, roster);
   a.current = withBlock.find((e) => e.file === preferred.file) || withBlock[0] || null;
@@ -134,7 +142,10 @@ export function analyseBlock(projectDir, s, { root = pluginRoot(), manifestDir =
   // never acquires an AGENTS.md it did not ask for, while installing Codex into
   // that same project moves the substance to the file Codex can read and leaves
   // CLAUDE.md importing it.
-  if (!a.current.own) return { ...a, state: "ours-stale", reason: `in ${a.current.file}, which ${s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}` };
+  if (!a.current.own) {
+    const reader = readers?.find((r) => !(r.files || []).includes(a.current.file))?.display;
+    return { ...a, state: "ours-stale", reason: `in ${a.current.file}, which ${reader || s.harness_display || "this harness"} does not read; install moves it to ${preferred.file}` };
+  }
   if (a.current.file !== preferred.file && preferred.present) return { ...a, state: "ours-stale", reason: `in ${a.current.file}; install migrates it to ${preferred.file}` };
   if (a.duplicates.length) return { ...a, state: "ours-stale", reason: `also in ${a.duplicates.map((e) => e.file).join(", ")}; install keeps the one in ${a.current.file}` };
   if (a.current.block.v === a.version && a.current.block.block === a.desired) return { ...a, state: "ours-current" };
@@ -250,8 +261,8 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
   // Machine-global facts: our directory, the host's marketplace registry, every row of ours.
   if (a.dir.present) {
     a.dir.manifest = readJson(paths.manifest);
-    const prov = a.dir.manifest && a.dir.manifest[s.provenance_key];
-    if (prov && typeof prov === "object" && typeof prov.pkg === "string") {
+    const prov = registrationProvenance(a.dir.manifest, s);
+    if (prov) {
       a.dir.prov = prov; a.dir.pkg = prov.pkg;
       a.dir.disabled = Array.isArray(prov.disabled) ? prov.disabled.filter((x) => typeof x === "string") : [];
       if (typeof prov.project === "string" && !samePath(prov.project, projectDir)) a.writtenBy = prov.project;
@@ -278,12 +289,13 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
   a.installPath = row ? row.path : null;
   a.installedVersion = row ? row.version : null;
   a.enabled = pluginEnabled(id, home, projectDir);
-  // Competing registrations of the same plugin, enabled for this project.
-  const seen = new Set();
-  for (const e of installedPluginEntries(home, projectDir)) {
-    if (e.key === id || seen.has(e.key) || !e.present || e.enabled === false) continue;
-    if (e.projectPath && !samePath(e.projectPath, projectDir)) continue;
-    seen.add(e.key); a.others.push({ key: e.key, path: e.path, version: e.version });
+  // Competing registrations of the same plugin, enabled for this project:
+  // contract 12's selection, one row per key — the row the host loads here,
+  // this checkout's own before a user-scope one. The convergence story's rule
+  // 6 reads the same rows (lib's projectCopiesByKey), so the deferral of a
+  // newer copy and the stop never disagree about its version.
+  for (const e of projectCopiesByKey(home, projectDir)) {
+    if (e.key !== id) a.others.push({ key: e.key, path: e.path, version: e.version });
   }
   a.newer = Boolean(a.dir.pkg) && cmpPrecedence(a.dir.pkg, pkg) > 0;
   // Same version, different payload: the directory's recorded digest against
@@ -318,6 +330,15 @@ export function analyseRegistration(projectDir, s, { root = pluginRoot(), home =
   return { ...a, state: "current", reason: a.newer ? `the directory is at ${a.dir.pkg}, newer than this package (${pkg})${a.writtenBy ? `, written from ${a.writtenBy}` : ""} — not downgraded` : null };
 }
 
+// The root a registration renders the project's dependent surfaces against,
+// read-only (contract 4′, two phases): the host's install path of this
+// checkout's row, when that copy is on disk and enabled; else null. One rule
+// for plan() (a run that leaves the registration out) and surfaceStates
+// (doctor), so the two cannot disagree about which root a launcher is for.
+export function registrationRenderRoot(a) {
+  return a && a.installed && (a.installed.present ?? true) && a.enabled ? a.installPath : null;
+}
+
 // ─── the project-level layout: legacy / new / both (the layout ADR) ─────
 //
 // Which of the two layouts a project holds, file by file — what the `layout`
@@ -357,6 +378,35 @@ export function analyseLayout(projectDir, { harness = null } = {}) {
   };
 }
 
+// ─── a harness's state directory: the welcome marker (contract 13) ──────
+//
+// What a project uninstall may take from .projectstore/state/<id>/: the
+// welcome marker, and the directory once it is empty. Without that the
+// directory outlives the uninstall and the next bare upgrade selects the
+// removed harness again (layout spec contract 5). The marker carries no
+// provenance line, so it is recognised three ways at once — the third
+// recogniser contract 13 accepts beside the provenance line and rung 1″: its
+// path, layoutPaths(p).welcomed(id); the state directory's .gitignore carrying
+// RUNTIME_GITIGNORE_HEADER; and its content, one ISO timestamp line, exactly
+// as the SessionStart hook writes it. Anything else in the directory — a
+// launcher, a file of the user's — is named in `others` and never ours to
+// take here: a launcher is its surface item's. Read-only, like everything in
+// this module.
+const WELCOME_STAMP = /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z\n?$/;
+export function analyseHarnessState(projectDir, id) {
+  const p = layoutPaths(projectDir);
+  const dir = p.harnessState(id);
+  let names;
+  try { names = readdirSync(dir).sort(); } catch { return { dir, present: false, names: [], headed: false, marker: null, others: [] }; }
+  let headed = false;
+  try { headed = readFileSync(p.stateGitignore, "utf8").includes(RUNTIME_GITIGNORE_HEADER); } catch {}
+  const markerPath = p.welcomed(id);
+  const markerName = markerPath.slice(dir.length + 1);
+  const t = names.includes(markerName) ? readText(markerPath) : { present: false, text: null };
+  const marker = headed && t.present && typeof t.text === "string" && WELCOME_STAMP.test(t.text) ? markerPath : null;
+  return { dir, present: true, names, headed, marker, others: names.filter((n) => !(marker && n === markerName)) };
+}
+
 // ─── every surface, for doctor ─────────────────────────────────────────
 
 export { analysePortableRegistration, portableRegistrationPaths };
@@ -378,9 +428,21 @@ export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(
     // that merely contained the harness's directory.
     const rows = Object.entries(m.surfaces || {}).filter(([k, s]) => !k.startsWith("_") && s.kind !== "host" && s.supported !== false && ANALYSERS[s.format]
       && !(s.condition === "distribution_root" && !portablePayloadRoot(s, { root, env })));
+    // The render root, as plan() takes it (contract 0 as amended 2026-10-10):
+    // an enabled, produced registration's install path. The launcher and the
+    // status-line entry are analysed against it — from the marketplace
+    // directory the host loads an npm registration from, or from a package
+    // root, the running root alone read the launcher as "not produced here".
+    // Read once, before the rows (the registration sorts last in the
+    // manifest); its own row reuses the result, since the analysis digests
+    // the payload.
+    const reg = rows.find(([, s]) => s.kind === "registration");
+    const regA = reg ? ANALYSERS[reg[1].format](projectDir, reg[1], { root, home, harness: m, env }) : null;
+    const renderRoot = (regA && regA.produced !== false && registrationRenderRoot(regA)) || root;
     const states = [];
     for (const [key, s] of rows) {
-      const a = ANALYSERS[s.format](projectDir, s, { root, home, harness: m, env });
+      const dependent = renderRoot !== root && ["json-entry", "mjs"].includes(s.format);
+      const a = reg && s === reg[1] ? regA : ANALYSERS[s.format](projectDir, s, { root, home, harness: m, env, ...(dependent ? { renderRoot } : {}) });
       const entry = s.kind === "shared" ? (a.entryKey || s.marker?.pointer || null) : null;
       const path = a.legacyPath || a.path || (a.current ? a.current.path : (a.preferred ? a.preferred.path : join(projectDir, s.file || "")));
       const row = { harness: m.id, surface: key, kind: s.kind, path, entry, state: a.state, reason: a.reason || a.refusal || null, writtenBy: a.writtenBy || null, sameProject: Boolean(a.sameProject), produced: a.produced !== false, legacy: Boolean(a.legacy), installedPkg: a.installedPkg || null, present: a.file ? a.file.present : (a.current ? true : (a.curEntry ? true : false)) };
@@ -392,6 +454,9 @@ export function surfaceStates(projectDir, { home = homedir(), root = pluginRoot(
         dirPkg: a.dir?.pkg || a.ownership?.version || null,
         installedVersion: a.installedVersion,
         installPath: a.installPath,
+        // The plugin's root inside our directory (registrationPaths' payload):
+        // what a host that loads the registration in place runs from.
+        payload: a.paths?.payload || null,
         enabled: a.enabled,
         others: a.others || [],
         otherProjects: a.otherProjects || 0,