projectstore-claude 0.29.2 → 0.29.4

package/node_modules/projectstore/scripts/harness.mjs

@@ -24,8 +24,8 @@
 //
 // Pure node, no external deps — same constraint as lib.mjs. Read-only.
 
-import { readFileSync, existsSync, readdirSync, realpathSync } from "node:fs";
-import { join, dirname, resolve, sep } from "node:path";
+import { readFileSync, existsSync, readdirSync, realpathSync, statSync } from "node:fs";
+import { join, dirname, resolve, sep, relative, isAbsolute } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 
@@ -51,9 +51,11 @@ let _cache = null;
 export function loadHarnesses(dir = MANIFEST_DIR) {
   if (_cache && _cache.dir === dir) return _cache.map;
   const map = new Map();
-  let names = [];
+  let names;
   try {
-    names = readdirSync(dir).filter((n) => n.endsWith(".json")).sort();
+    names = readdirSync(dir)
+      .filter((n) => n.endsWith(".json"))
+      .sort();
   } catch {
     names = [];
   }
@@ -153,7 +155,8 @@ export function identifiedHarnessId(env = process.env, dir = MANIFEST_DIR) {
   if (forced && loadHarnesses(dir).has(forced)) return forced;
   // A parent of ours decided before it named the project in the harness's own
   // vocabulary (childEnv), so its answer stands — an empty one included.
-  if (env[IDENTIFIED_ENV] !== undefined) return loadHarnesses(dir).has(env[IDENTIFIED_ENV]) ? env[IDENTIFIED_ENV] : null;
+  if (env[IDENTIFIED_ENV] !== undefined)
+    return loadHarnesses(dir).has(env[IDENTIFIED_ENV]) ? env[IDENTIFIED_ENV] : null;
   const best = ranked(env, dir);
   if (best && best.strong) return best.id;
   for (const m of loadHarnesses(dir).values()) {
@@ -226,23 +229,175 @@ export function resetDetection() {
 // process" from branded environment variables, and using it here would
 // conjure .claude/ for a Codex user. Not memoised: it is per directory, and a
 // test builds a project per case.
-export function detectHarnesses(projectDir, { dir = MANIFEST_DIR } = {}) {
+//
+// `state` adds the second signal `upgrade` reads: a harness whose state
+// directory of ours exists (layoutPaths(p).harnessState(id), layout spec
+// contract 5). A Codex session wrote its welcome marker there, so Codex is
+// used here even with no .codex/ (measured in this repository, 2026-10-08).
+// Never a machine-global registration: one exists for every project on the
+// machine and would select its harness everywhere. One entry per manifest,
+// the directory first, in manifest order as before.
+export function detectHarnesses(projectDir, { dir = MANIFEST_DIR, state = false } = {}) {
   const out = [];
+  const p = state ? layoutPaths(projectDir, { dir }) : null;
   for (const m of loadHarnesses(dir).values()) {
     const d = m.runtime?.harness_dir;
-    if (d && existsSync(join(projectDir, d))) out.push({ id: m.id, why: "directory", evidence: d });
+    if (d && existsSync(join(projectDir, d))) {
+      out.push({ id: m.id, why: "directory", evidence: d });
+      continue;
+    }
+    if (!p) continue;
+    const at = p.harnessState(m.id);
+    let isDir = false;
+    try {
+      isDir = statSync(at).isDirectory();
+    } catch {}
+    if (isDir) out.push({ id: m.id, why: "state", evidence: relative(projectDir, at) });
   }
   return out;
 }
 
-// The refusal when nothing is detected and nothing is named — built from the
-// manifests, so a new harness appears in it without an edit here.
-export function harnessRefusal(projectDir, dir = MANIFEST_DIR) {
-  const lines = [`No harness detected in ${projectDir}, and none named. Name one:`];
-  for (const m of loadHarnesses(dir).values()) {
-    lines.push(`  --harness ${m.id}    (${m.display_name}; detected by its project directory: ${m.runtime?.harness_dir || "?"})`);
+// A pure PATH walk for a host binary — a read, not a subprocess: the analysers
+// run on every doctor call. Returns the absolute path or null. It lives here,
+// beside hostPresence, which needs it; lib.mjs re-exports it under the name
+// it already published.
+export function whichOnPath(name, env = process.env) {
+  const sep = process.platform === "win32" ? ";" : ":";
+  const exts = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
+  for (const dir of String(env.PATH || "")
+    .split(sep)
+    .filter(Boolean)) {
+    for (const ext of exts) {
+      const p = join(dir, name + ext);
+      try {
+        const st = statSync(p);
+        if (st.isFile() && (process.platform === "win32" || st.mode & 0o111)) return p;
+      } catch {}
+    }
+  }
+  return null;
+}
+
+// Whether a harness's host is on this MACHINE (the story "projectstore setup
+// asks, shows one plan and installs every harness it finds, with the vault",
+// rule 5): its registration surface's CLI found on PATH, and its home
+// directory present — the manifest's home variable when set, else
+// <home>/<home_default>. Not detectHarnesses, which answers for a PROJECT, and
+// not detectHarnessId, which names the harness running this process. Setup's
+// pre-tick is the one place machine presence counts; install keeps contract 8.
+// Every name comes from the manifest. Read-only: a stat per PATH entry and one
+// for the home.
+//   → { cli, home, bin, homeDir }: `cli` is the absolute path found, or null;
+//     `home` the directory when it exists, or null. `bin` and `homeDir` are
+//     what was looked for (null when the manifest names none), so a reason can
+//     name them when either is missing.
+export function hostPresence(manifest, { env = process.env, home = homedir() } = {}) {
+  const s =
+    Object.entries(manifest?.surfaces || {}).find(
+      ([k, x]) =>
+        !k.startsWith("_") &&
+        x?.kind === "registration" &&
+        x.supported !== false &&
+        typeof x.cli?.bin === "string" &&
+        x.cli.bin,
+    )?.[1] || null;
+  const bin = s ? s.cli.bin : null;
+  const r = manifest?.runtime || {};
+  const fromEnv = r.home_env && env ? env[r.home_env] : null;
+  const homeDir = fromEnv || (home && r.home_default ? join(home, r.home_default) : null);
+  let present = false;
+  if (homeDir) {
+    try {
+      present = statSync(homeDir).isDirectory();
+    } catch {}
   }
-  return lines.join("\n");
+  return { cli: bin ? whichOnPath(bin, env || {}) : null, home: present ? homeDir : null, bin, homeDir };
+}
+
+// The agents block of a RUN (the story "One run plans the agents block once,
+// and a bare uninstall selects every harness the project uses", rules 1–2):
+// the files every manifest of the run names for it, in the FIRST manifest's
+// order. The block is written to the first of them, so it lands where every
+// harness of the run can read it, natively or through the import the run
+// creates. One manifest gives its own list unchanged, which is what keeps a
+// single-harness plan as it was.
+export function commonBlockFiles(manifests) {
+  const lists = manifests.map((m) => agentsBlockRow(m)?.[1].files || []);
+  if (!lists.length) return [];
+  return lists[0].filter((f) => lists.every((l) => l.includes(f)));
+}
+
+// A manifest's agents-block row as [key, surface], or null: found by its
+// format, as the installer's handlers are keyed, never by the key's name.
+export function agentsBlockRow(manifest) {
+  return (
+    Object.entries(manifest?.surfaces || {}).find(([k, s]) => !k.startsWith("_") && s?.format === "markdown-block") ||
+    null
+  );
+}
+
+// Rule 2, for the schema test: the manifests' lists share a file, or a run of
+// all of them has nowhere to write the block. Null when they do; otherwise
+// the problem, naming each manifest's list.
+export function blockTargetProblem(manifests) {
+  const withBlock = manifests.filter((m) => agentsBlockRow(m));
+  if (commonBlockFiles(withBlock).length) return null;
+  return `the agents-block files lists share no file, so a run of every harness has no file to write the block to: ${withBlock.map((m) => `${m.id} ${JSON.stringify(agentsBlockRow(m)[1].files || [])}`).join(", ")}`;
+}
+
+// The refusal when nothing is detected and nothing is named — built from the
+// manifests, so a new harness appears in it without an edit here. With
+// `state` (upgrade's set) it names both signals the selection read.
+export function harnessRefusal(projectDir, { dir = MANIFEST_DIR, state = false } = {}) {
+  const p = state ? layoutPaths(projectDir, { dir }) : null;
+  const rows = [...loadHarnesses(dir).values()].map((m) => {
+    const by = `detected by its project directory: ${m.runtime?.harness_dir || "?"}`;
+    return {
+      id: m.id,
+      display: m.display_name,
+      why: p ? `${by}, or by its state directory: ${relative(projectDir, p.harnessState(m.id))}` : by,
+    };
+  });
+  return [`No harness detected in ${projectDir}, and none named. Name one:`, ...harnessNameLines(rows)].join("\n");
+}
+
+// That refusal's rows, one per harness — `--harness <id>`, then its display
+// name and why — shared with setup's (its rule 12), so the two cannot drift.
+// The ids are padded to one width, so every reason starts in one column.
+export function harnessNameLines(rows) {
+  const width = Math.max(0, ...rows.map((r) => r.id.length));
+  return rows.map((r) => `  --harness ${r.id.padEnd(width)}    (${r.display}; ${r.why})`);
+}
+
+// Inside a live session of the host, its CLI and the session both rewrite the
+// same settings files on their own schedules; the registration is planned
+// only from a terminal outside one. The host marks its sessions in the
+// environment (manifest runtime.session_env). It lives here, beside
+// detection, so the installer and the shell fetch read one predicate without
+// an import cycle.
+export function insideHostSession(env, harness) {
+  // runtime.session_env, not detect_env: a Bash tool inside a session carries
+  // the session marker, not the plugin-root variables a hook receives
+  // (measured 2026-09-05; the critic's third pass caught the first draft
+  // keying on detect_env, which never fired in a session).
+  return (harness?.runtime?.session_env || []).some((k) => env && env[k]);
+}
+
+// Whether a harness's registration — and the shell fetch that would feed it —
+// defers in this environment (the setup story, rule 15: the front-door ADR's
+// first open question, answered by the maintainer on 2026-10-08). It defers
+// inside the harness's own session (insideHostSession, runtime.session_env),
+// or while one of its runtime.registration_defer_env variables is set. That
+// second list defers the registration and the fetch and nothing else:
+// isInteractive, the layout move and session identity read session_env alone.
+// Codex's exec tool sets CODEX_THREAD_ID in every command (measured
+// 2026-10-05), while its session_env stays empty so the doctor skill's
+// `upgrade --json` still moves the layout there. Keyed on the PLANNED
+// harness's manifest: inside one host's session another host's registration
+// does not defer.
+export function registrationDeferred(env, harness) {
+  if (insideHostSession(env, harness)) return true;
+  return (harness?.runtime?.registration_defer_env || []).some((k) => env && env[k]);
 }
 
 export function activeHarness(env = process.env, dir = MANIFEST_DIR) {
@@ -280,7 +435,10 @@ export function invocation(manifest, name, { kind = "commands", args = "" } = {}
 // read these same patterns.
 export function uiWordPatterns(manifest) {
   const esc = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
-  return (manifest?.ui_vocabulary || []).map((word) => ({ word, re: new RegExp(`(?<![\\w.-])${esc(word)}(?![\\w-]|\\.\\w)`, "g") }));
+  return (manifest?.ui_vocabulary || []).map((word) => ({
+    word,
+    re: new RegExp(`(?<![\\w.-])${esc(word)}(?![\\w-]|\\.\\w)`, "g"),
+  }));
 }
 
 // The harness whose distribution shell bundles this core, by the shell's
@@ -301,7 +459,9 @@ export function bundlingShellHarnessId({ core = REPO_ROOT, dir = MANIFEST_DIR }
       const name = JSON.parse(readFileSync(join(dirname(parent), "package.json"), "utf8")).name;
       id = [...loadHarnesses(dir).values()].find((m) => m.install?.shell && m.install.shell === name)?.id ?? null;
     }
-  } catch { id = null; }
+  } catch {
+    id = null;
+  }
   if (memo) _bundling = id;
   return id;
 }
@@ -325,10 +485,8 @@ function speaker(env, dir) {
   if (identified) return identified;
   const bundled = bundlingShellHarnessId({ dir });
   if (bundled) return bundled;
-  if (env.PROJECTSTORE_SHELL) {
-    const named = [...loadHarnesses(dir).values()].find((m) => m.install?.shell === env.PROJECTSTORE_SHELL);
-    if (named) return named.id;
-  }
+  const named = shellHarnessId(env, dir);
+  if (named) return named;
   return sourceHarness(dir)?.id ?? null;
 }
 
@@ -434,7 +592,13 @@ function hostPluginRoot(env) {
 // bin's child), is honoured as named. Real paths on both sides: the module's
 // own is already real, so a root under a symlink (macOS's /var and /tmp)
 // would never compare.
-const realOr = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
+const realOr = (p) => {
+  try {
+    return realpathSync(p);
+  } catch {
+    return resolve(p);
+  }
+};
 let _realCore = null;
 function containsThisCore(root) {
   const core = (_realCore ??= realOr(REPO_ROOT));
@@ -461,7 +625,7 @@ export function agentHome(env = process.env, home = homedir()) {
 // path is spelled — every reader and writer goes through layoutPaths(), and a
 // test greps the rest of scripts/, hooks/ and bin/ for the literals. The
 // legacy shape (.claude/projectstore.json, .claude/.projectstore/…) is named
-// here too, for the readers' fallback through 0.29 (layout spec, contracts
+// here too, for the readers' fallback through 0.30 (layout spec, contracts
 // 0, 1 and 7); its harness directory is the source harness's own.
 export const LAYOUT = Object.freeze({
   root: ".projectstore",
@@ -516,19 +680,75 @@ export function layoutPaths(projectDir, { harnessDir = null, dir = MANIFEST_DIR
   };
 }
 
-// The command a user types from a terminal for this harness (the layout ADR
-// decision 6; layout spec contract 12): the harness's distribution shell when
-// the manifest names one — `npx projectstore-claude install --project "…"`,
-// the harness fixed by the shell — else the core with --harness. Finding
-// messages and deferred reasons are built here, so the installer names no
-// harness id and no shell name of its own. The shell's name is data
-// (install.shell), not `projectstore-<id>`: the id is claude-code, the
-// published name is projectstore-claude.
-export function packageCommand(harness, verb, { version = null, args = "" } = {}) {
-  const shell = harness?.install?.shell || null;
-  const pkg = `${shell || "projectstore"}${version ? `@${version}` : ""}`;
-  const fixed = shell ? "" : ` --harness ${harness?.id || "<id>"}`;
-  return `npx ${pkg} ${verb}${fixed}${args ? ` ${args}` : ""}`;
+// ─── The user-level cache (layout spec contract 0, the user-level class) ─
+//
+// What is ours on the machine but belongs to no project and no harness home:
+// the shell fetch's scratch (<root>/fetch/<pid>-<ms>/, removed when its run
+// ends) and the registry answer the update notice caches for a day
+// (<root>/registry.json, named now and read by no one yet). The XDG Base
+// Directory spec puts a cache at $XDG_CACHE_HOME when that is an absolute
+// path and ignores a relative one; an empty one is ignored too. Otherwise it
+// is <home>/.cache. With neither, `root` is null and the fetch refuses. This
+// is the one place either name is spelled (contract 0's grep): `from` and
+// `variable` carry them into a refusal's text. env and home are always
+// parameters.
+export function cachePaths({ env = process.env, home = homedir() } = {}) {
+  const variable = "XDG_CACHE_HOME";
+  const xdg = env ? env[variable] : null;
+  const fromEnv = typeof xdg === "string" && xdg !== "" && isAbsolute(xdg);
+  const base = fromEnv ? xdg : home ? join(home, ".cache") : null;
+  const root = base ? join(base, "projectstore") : null;
+  return {
+    root,
+    fetch: root ? join(root, "fetch") : null,
+    fetchRun: (id) => (root ? join(root, "fetch", id) : null),
+    registry: root ? join(root, "registry.json") : null,
+    from: fromEnv ? variable : "the home directory",
+    variable,
+  };
+}
+
+// The core through npx: how every command a person is told to type next
+// begins (the story "User-facing text says where to run and names no project
+// path and no shell", rules 2 and 6). `npx` runs it with no bin on PATH.
+export const CORE_NPX = "npx projectstore";
+
+// The command a person types from a terminal (the front-door ADR, decision 5;
+// the story above, rule 2): always the core, with one --harness per manifest
+// in the order given — `npx projectstore[@<v>] <verb> --harness a [--harness
+// b] [args]`. It names no shell, whatever the manifest's install.shell says,
+// and its callers pass no --project: where to run it is their prose, `from a
+// terminal in "<dir>"` (lib.mjs fromTerminalIn). The id stays because a bare
+// upgrade or uninstall plans every harness the project uses. An empty array
+// names none, for a verb that takes no --harness (bind, status, scaffold,
+// reconcile). Finding messages, deferred reasons and DONE's tip are built
+// here, so the installer spells no command of its own. The string is built
+// here, not by the converge story's coreCommand, whose module imports this one.
+export function packageCommand(harnesses, verb, { version = null, args = "" } = {}) {
+  const list = Array.isArray(harnesses) ? harnesses : [harnesses];
+  const ids = list.map((h) => ` --harness ${h?.id || "<id>"}`).join("");
+  return `${CORE_NPX}${version ? `@${version}` : ""} ${verb}${ids}${args ? ` ${args}` : ""}`;
+}
+
+// The package this run was invoked as: the shell it came through (the shell's
+// bin sets PROJECTSTORE_SHELL, and fixes the harness), else the core. Only
+// what describes the binary that ran uses it — the help's first line, its
+// Usage lines, the fixed-harness line and the usage errors (the story above,
+// rule 6). A command printed for a person to type next is the core's
+// (packageCommand, CORE_NPX), through a shell too.
+export function invokedAs(env = process.env) {
+  const shell = env.PROJECTSTORE_SHELL || null;
+  return { shell, cmd: shell ? `npx ${shell}` : CORE_NPX };
+}
+
+// The harness a shell fixes: the manifest whose install.shell is the name the
+// shell's bin exports (PROJECTSTORE_SHELL), or null. Never speakingHarnessId,
+// which a session's identity overrides: the Codex shell run inside a Claude
+// Code session still installs Codex, so its help's examples name codex.
+export function shellHarnessId(env = process.env, dir = MANIFEST_DIR) {
+  const shell = env.PROJECTSTORE_SHELL;
+  if (!shell) return null;
+  return [...loadHarnesses(dir).values()].find((m) => m.install?.shell === shell)?.id ?? null;
 }
 
 // The overlay a harness reads: <project>/.projectstore/harness/<overlay>.json —
@@ -552,6 +772,22 @@ export function harnessForOverlay(key, dir = MANIFEST_DIR) {
   return all.find((m) => m.runtime?.overlay === key) || all.find((m) => m.id === key) || null;
 }
 
+// Whether a harness draws the band above the prompt (the band spec, contract
+// 1): the one predicate for "a harness without a band", read by the generator
+// (which keeps the module out of such a harness's tree) and by `band status`.
+export function hasBand(manifest) {
+  return manifest?.surfaces?.band?.supported === true;
+}
+
+// The session id the host hands a tool process, by the manifest's name for
+// it (runtime.session_id_env), or null where the harness names none or the
+// process got none.
+export function hostSessionId(env = process.env, harness = activeHarness(env)) {
+  const k = harness?.runtime?.session_id_env;
+  const v = k && env ? env[k] : null;
+  return typeof v === "string" && v ? v : null;
+}
+
 // A reader's fallback: the new path when it exists, else the legacy one when
 // THAT exists, else the new path (a writer's target) — at most two existsSync
 // calls, never a directory scan (contract 1; the SessionStart budget).
@@ -681,7 +917,11 @@ export function lintPatterns(harness, dir = MANIFEST_DIR) {
   // shared_env to the derivation below would forbid Claude Code's own variable
   // inside Claude Code's own tree.
   const o = harness.runtime || {};
-  const own = new Set([o.project_dir_env, o.plugin_root_env, o.home_env, ...(o.detect_env || []), ...(o.shared_env || [])].filter(Boolean));
+  const own = new Set(
+    [o.project_dir_env, o.plugin_root_env, o.home_env, ...(o.detect_env || []), ...(o.shared_env || [])].filter(
+      Boolean,
+    ),
+  );
   for (const m of loadHarnesses(dir).values()) {
     if (m.id === harness.id) continue;
     for (const t of m.tools?.write_tools || []) out.push({ pattern: `\\b${t}\\b`, class: "token", derived: true });
@@ -689,7 +929,13 @@ export function lintPatterns(harness, dir = MANIFEST_DIR) {
     // shared_env included: a name is no less branded for being set by two
     // harnesses, and it exists in no other field of the manifest that declares
     // it — CLAUDE_PLUGIN_DATA appears nowhere but codex.json's shared_env.
-    for (const k of [r.project_dir_env, r.plugin_root_env, r.home_env, ...(r.detect_env || []), ...(r.shared_env || [])]) {
+    for (const k of [
+      r.project_dir_env,
+      r.plugin_root_env,
+      r.home_env,
+      ...(r.detect_env || []),
+      ...(r.shared_env || []),
+    ]) {
       if (k && !own.has(k)) out.push({ pattern: `\\b${k}\\b`, class: "token", derived: true });
     }
   }