projectstore-claude 0.29.3 → 0.29.4

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (53) hide show
  1. package/bin/projectstore-claude.mjs +1 -1
  2. package/node_modules/projectstore/.claude-plugin/marketplace.json +1 -1
  3. package/node_modules/projectstore/.claude-plugin/plugin.json +1 -1
  4. package/node_modules/projectstore/README.md +17 -0
  5. package/node_modules/projectstore/commands/bind.md +6 -17
  6. package/node_modules/projectstore/commands/doctor.md +12 -7
  7. package/node_modules/projectstore/commands/statusline.md +1 -1
  8. package/node_modules/projectstore/commands/story.md +15 -2
  9. package/node_modules/projectstore/docs/how-it-works.md +5 -3
  10. package/node_modules/projectstore/harnesses/claude-code.json +5 -5
  11. package/node_modules/projectstore/harnesses/codex.json +4 -5
  12. package/node_modules/projectstore/hooks/band.tsx +48 -20
  13. package/node_modules/projectstore/hooks/pre-compact.mjs +7 -10
  14. package/node_modules/projectstore/hooks/session-rules.mjs +14 -8
  15. package/node_modules/projectstore/hooks/session-start.mjs +50 -18
  16. package/node_modules/projectstore/hooks/session-stop.mjs +8 -6
  17. package/node_modules/projectstore/package.json +11 -2
  18. package/node_modules/projectstore/scripts/band-shared.mjs +141 -24
  19. package/node_modules/projectstore/scripts/band.mjs +72 -21
  20. package/node_modules/projectstore/scripts/binding.mjs +616 -85
  21. package/node_modules/projectstore/scripts/build-adapters.mjs +73 -29
  22. package/node_modules/projectstore/scripts/cli.mjs +1015 -185
  23. package/node_modules/projectstore/scripts/codemap.mjs +22 -7
  24. package/node_modules/projectstore/scripts/convergence.mjs +253 -83
  25. package/node_modules/projectstore/scripts/diff-refs.mjs +14 -8
  26. package/node_modules/projectstore/scripts/doctor-report.mjs +91 -23
  27. package/node_modules/projectstore/scripts/doctor.mjs +1317 -371
  28. package/node_modules/projectstore/scripts/draft.mjs +5 -2
  29. package/node_modules/projectstore/scripts/fetch-shell.mjs +106 -20
  30. package/node_modules/projectstore/scripts/graph.mjs +19 -13
  31. package/node_modules/projectstore/scripts/harness.mjs +123 -48
  32. package/node_modules/projectstore/scripts/install-harness.mjs +3511 -616
  33. package/node_modules/projectstore/scripts/kanban.mjs +2 -1
  34. package/node_modules/projectstore/scripts/lib.mjs +694 -159
  35. package/node_modules/projectstore/scripts/mcp.mjs +386 -105
  36. package/node_modules/projectstore/scripts/portable-registration.mjs +224 -51
  37. package/node_modules/projectstore/scripts/provenance.mjs +26 -10
  38. package/node_modules/projectstore/scripts/query.mjs +378 -80
  39. package/node_modules/projectstore/scripts/reconcile.mjs +55 -18
  40. package/node_modules/projectstore/scripts/run-host.mjs +62 -17
  41. package/node_modules/projectstore/scripts/scaffold.mjs +89 -28
  42. package/node_modules/projectstore/scripts/setup.mjs +987 -0
  43. package/node_modules/projectstore/scripts/stages.mjs +5 -1
  44. package/node_modules/projectstore/scripts/statusline-launcher.mjs +36 -11
  45. package/node_modules/projectstore/scripts/statusline.mjs +32 -14
  46. package/node_modules/projectstore/scripts/story-section.mjs +39 -17
  47. package/node_modules/projectstore/scripts/surfaces.mjs +416 -95
  48. package/node_modules/projectstore/scripts/term.mjs +382 -97
  49. package/node_modules/projectstore/scripts/tokens.mjs +106 -28
  50. package/node_modules/projectstore/scripts/touch-session.mjs +109 -70
  51. package/node_modules/projectstore/scripts/version-guard.mjs +74 -27
  52. package/node_modules/projectstore/scripts/worktree.mjs +16 -5
  53. package/package.json +2 -2
@@ -54,7 +54,8 @@ import {
54
54
  slugify,
55
55
  findSlugCollision,
56
56
  displayNumberOf,
57
- today, isMain,
57
+ today,
58
+ isMain,
58
59
  commandForm,
59
60
  } from "./lib.mjs";
60
61
 
@@ -117,7 +118,9 @@ function scanCollision(dir, fileName, opts) {
117
118
 
118
119
  function digitLeadingWarnings(slug) {
119
120
  return /^\d/.test(slug)
120
- ? [`Slug "${slug}" is digit-leading — the filename visually resembles a numbered-era artifact. Machine resolution keys on id:, so this is safe, but a word-leading title avoids the ambiguity.`]
121
+ ? [
122
+ `Slug "${slug}" is digit-leading — the filename visually resembles a numbered-era artifact. Machine resolution keys on id:, so this is safe, but a word-leading title avoids the ambiguity.`,
123
+ ]
121
124
  : [];
122
125
  }
123
126
 
@@ -31,10 +31,21 @@ import { existsSync, readFileSync, readdirSync } from "node:fs";
31
31
  import { join } from "node:path";
32
32
  import { registrationDeferred } from "./harness.mjs";
33
33
  import { removeTreeUnder, pidAlive, whichOnPath } from "./lib.mjs";
34
- import { isPortablePluginRoot, payloadManifest, payloadManifestPath, payloadManifestPaths } from "./portable-registration.mjs";
34
+ import {
35
+ isPortablePluginRoot,
36
+ payloadManifest,
37
+ payloadManifestPath,
38
+ payloadManifestPaths,
39
+ } from "./portable-registration.mjs";
35
40
  import { runHost, startFailure, HOST_BUDGET_MS } from "./run-host.mjs";
36
41
 
37
- const readJson = (p) => { try { return JSON.parse(readFileSync(p, "utf8")); } catch { return null; } };
42
+ const readJson = (p) => {
43
+ try {
44
+ return JSON.parse(readFileSync(p, "utf8"));
45
+ } catch {
46
+ return null;
47
+ }
48
+ };
38
49
 
39
50
  // The version a shell-rooted harness is fetched at has one source: the
40
51
  // package.json of the root the plan runs from — never `latest`, never a range.
@@ -65,9 +76,20 @@ const STAGING_VERBS = ["install", "upgrade", "setup"];
65
76
  // ownShell — the run is this harness's own shell's core (rule 8)
66
77
  // env — the run's: a named distribution root, a session marker or a
67
78
  // registration_defer_env variable
68
- export function fetchDecision({ verb, harness, s, excluded = false, named = false, interactive = false, analysis = null, ownShell = false, env = process.env } = {}) {
79
+ export function fetchDecision({
80
+ verb,
81
+ harness,
82
+ s,
83
+ excluded = false,
84
+ named = false,
85
+ interactive = false,
86
+ analysis = null,
87
+ ownShell = false,
88
+ env = process.env,
89
+ } = {}) {
69
90
  if (!STAGING_VERBS.includes(verb)) return { fetch: false, why: "verb" };
70
- if (s?.condition !== "distribution_root" || !harness?.install?.shell) return { fetch: false, why: "not-shell-rooted" };
91
+ if (s?.condition !== "distribution_root" || !harness?.install?.shell)
92
+ return { fetch: false, why: "not-shell-rooted" };
71
93
  if (excluded) return { fetch: false, why: "excluded" };
72
94
  // A set root is used as is — a root or not — and nothing is fetched.
73
95
  if (env && env.PROJECTSTORE_DISTRIBUTION_ROOT) return { fetch: false, why: "root-named" };
@@ -100,9 +122,20 @@ export function fetchDecision({ verb, harness, s, excluded = false, named = fals
100
122
  // outer bound. --ignore-scripts: no install-time code from a registry runs.
101
123
  export function fetchArgv({ prefix, registry = null, shell, version }) {
102
124
  return [
103
- "install", "--prefix", prefix, "--no-save", "--ignore-scripts", "--no-audit", "--no-fund", "--no-update-notifier", "--json",
125
+ "install",
126
+ "--prefix",
127
+ prefix,
128
+ "--no-save",
129
+ "--ignore-scripts",
130
+ "--no-audit",
131
+ "--no-fund",
132
+ "--no-update-notifier",
133
+ "--json",
104
134
  ...(registry ? ["--registry", registry] : []),
105
- "--fetch-timeout=30000", "--fetch-retries=2", "--fetch-retry-mintimeout=1000", "--fetch-retry-maxtimeout=5000",
135
+ "--fetch-timeout=30000",
136
+ "--fetch-retries=2",
137
+ "--fetch-retry-mintimeout=1000",
138
+ "--fetch-retry-maxtimeout=5000",
106
139
  `${shell}@${version}`,
107
140
  ];
108
141
  }
@@ -132,7 +165,12 @@ export async function npmRegistry(projectDir, { env = process.env, spawn, budget
132
165
  const call = npmCall(["config", "get", "registry", "--no-update-notifier"], env);
133
166
  const r = await runHost(call.bin, call.argv, { env, cwd: projectDir, budget, spawn, shell: call.shell });
134
167
  if (r.error || r.status !== 0) return null;
135
- const value = String(r.stdout || "").trim().split(/\r?\n/).pop()?.trim() || "";
168
+ const value =
169
+ String(r.stdout || "")
170
+ .trim()
171
+ .split(/\r?\n/)
172
+ .pop()
173
+ ?.trim() || "";
136
174
  return value && !/\s/.test(value) && value !== "undefined" ? value : null;
137
175
  }
138
176
 
@@ -157,10 +195,19 @@ export async function npmUserRegistry({ home = null, env = process.env, spawn, b
157
195
  export function npmError(stdout, stderr) {
158
196
  try {
159
197
  const e = JSON.parse(String(stdout || ""))?.error;
160
- if (e && typeof e === "object") return { code: String(e.code || "") || null, summary: String(e.summary || "").trim(), detail: String(e.detail || "").trim() };
198
+ if (e && typeof e === "object")
199
+ return {
200
+ code: String(e.code || "") || null,
201
+ summary: String(e.summary || "").trim(),
202
+ detail: String(e.detail || "").trim(),
203
+ };
161
204
  } catch {}
162
205
  const code = String(stderr || "").match(/npm (?:error|ERR!) code (\S+)/)?.[1] || null;
163
- const summary = String(stderr || "").split(/\r?\n/).map((l) => l.replace(/^npm (?:error|ERR!) ?/, "").trim()).find((l) => l && !/^code \S+$/.test(l) && !/complete log of this run/i.test(l)) || "";
206
+ const summary =
207
+ String(stderr || "")
208
+ .split(/\r?\n/)
209
+ .map((l) => l.replace(/^npm (?:error|ERR!) ?/, "").trim())
210
+ .find((l) => l && !/^code \S+$/.test(l) && !/complete log of this run/i.test(l)) || "";
164
211
  return { code, summary, detail: "" };
165
212
  }
166
213
 
@@ -172,7 +219,18 @@ const seconds = (ms) => `${Number((ms / 1000).toFixed(ms % 1000 ? 1 : 0))} s`;
172
219
  // cache). Every way out is a terminal command or a variable; none names a
173
220
  // version but the one this run is at.
174
221
  export function fetchRefusal(code, ctx = {}) {
175
- const { pkg = "the shell", shell = "the shell", registry = null, display = "this harness", budget = HOST_BUDGET_MS, summary = "", cause = "", path = null, from = null, variable = null } = ctx;
222
+ const {
223
+ pkg = "the shell",
224
+ shell = "the shell",
225
+ registry = null,
226
+ display = "this harness",
227
+ budget = HOST_BUDGET_MS,
228
+ summary = "",
229
+ cause = "",
230
+ path = null,
231
+ from = null,
232
+ variable = null,
233
+ } = ctx;
176
234
  const where = registry || "the registry npm resolves";
177
235
  const without = `name --harness without ${display}`;
178
236
  switch (code) {
@@ -206,17 +264,20 @@ export function fetchRefusal(code, ctx = {}) {
206
264
  // naming the file and both values. Nothing is staged either way.
207
265
  export function verifyFetched(root, { shell, version, pluginName, coreName }) {
208
266
  const pkg = `${shell}@${version}`;
209
- const mismatch = (file, what, got, want) => `the fetched ${pkg} is not what this run plans: ${file} has ${what} ${JSON.stringify(got ?? null)}, expected ${JSON.stringify(want)} — nothing is staged`;
267
+ const mismatch = (file, what, got, want) =>
268
+ `the fetched ${pkg} is not what this run plans: ${file} has ${what} ${JSON.stringify(got ?? null)}, expected ${JSON.stringify(want)} — nothing is staged`;
210
269
  const pkgFile = join(root, "package.json");
211
270
  const shellPkg = readJson(pkgFile);
212
271
  if (shellPkg?.name !== shell) return mismatch(pkgFile, "name", shellPkg?.name, shell);
213
272
  if (shellPkg?.version !== version) return mismatch(pkgFile, "version", shellPkg?.version, version);
214
- if (!isPortablePluginRoot(root)) return `the fetched ${pkg} is not a plugin root: neither ${payloadManifestPaths(root).join(" nor ")} exists — nothing is staged`;
273
+ if (!isPortablePluginRoot(root))
274
+ return `the fetched ${pkg} is not a plugin root: neither ${payloadManifestPaths(root).join(" nor ")} exists — nothing is staged`;
215
275
  // Exactly the shell's one manifest, the one the host validates: a root
216
276
  // manifest would be read first and load no hooks, so it never passes.
217
277
  const manifestFile = payloadManifestPath(root, "legacy");
218
278
  const rootFile = payloadManifestPath(root, "root");
219
- if (existsSync(rootFile)) return `the fetched ${pkg} carries ${rootFile}, which the host reads before ${manifestFile} and loads no hooks from — nothing is staged`;
279
+ if (existsSync(rootFile))
280
+ return `the fetched ${pkg} carries ${rootFile}, which the host reads before ${manifestFile} and loads no hooks from — nothing is staged`;
220
281
  const manifest = payloadManifest(root, { kind: "legacy" });
221
282
  if (!manifest) return `the fetched ${pkg} has no readable plugin manifest at ${manifestFile} — nothing is staged`;
222
283
  if (manifest.name !== pluginName) return mismatch(manifestFile, "name", manifest.name, pluginName);
@@ -231,7 +292,10 @@ export function verifyFetched(root, { shell, version, pluginName, coreName }) {
231
292
  // the run's environment. The payload root is computed, never read from npm's
232
293
  // output: npm's --json result printed it with one UUID-like segment redacted
233
294
  // as *** (measured). A failure is a refusal before the plan, never a fallback.
234
- export async function fetchShell({ harness, s, version, coreName }, { dir, registry = null, env = process.env, spawn, budget = HOST_BUDGET_MS } = {}) {
295
+ export async function fetchShell(
296
+ { harness, s, version, coreName },
297
+ { dir, registry = null, env = process.env, spawn, budget = HOST_BUDGET_MS } = {},
298
+ ) {
235
299
  const shell = harness.install.shell;
236
300
  const pkg = `${shell}@${version}`;
237
301
  const ctx = { pkg, shell, registry, display: harness.display_name, budget };
@@ -240,16 +304,31 @@ export async function fetchShell({ harness, s, version, coreName }, { dir, regis
240
304
  const r = await runHost(call.bin, call.argv, { env, cwd: dir, budget, spawn, shell: call.shell });
241
305
  const ms = Date.now() - t0;
242
306
  if (r.error) {
243
- if (r.error.code === "ETIMEDOUT") return { ok: false, ms, code: "ETIMEDOUT", refusal: fetchRefusal("EBUDGET", ctx) };
244
- return { ok: false, ms, code: r.error.code || "ESTART", refusal: fetchRefusal("ESTART", { ...ctx, cause: startFailure(r.error, { bin: "npm", resolved: call.resolved, cwd: dir }) }) };
307
+ if (r.error.code === "ETIMEDOUT")
308
+ return { ok: false, ms, code: "ETIMEDOUT", refusal: fetchRefusal("EBUDGET", ctx) };
309
+ return {
310
+ ok: false,
311
+ ms,
312
+ code: r.error.code || "ESTART",
313
+ refusal: fetchRefusal("ESTART", {
314
+ ...ctx,
315
+ cause: startFailure(r.error, { bin: "npm", resolved: call.resolved, cwd: dir }),
316
+ }),
317
+ };
245
318
  }
246
319
  if (r.status !== 0) {
247
320
  const e = npmError(r.stdout, r.stderr);
248
321
  // npm reports a request it gave up on as FETCH_ERROR, "network timeout
249
322
  // at: <url>" (measured in review, 2026-10-08), not as ETIMEDOUT.
250
323
  const timeout = e.code === "FETCH_ERROR" && /network timeout at:\s*(\S+)/.exec(e.summary);
251
- if (timeout) return { ok: false, ms, code: e.code, refusal: fetchRefusal("FETCH_TIMEOUT", { ...ctx, url: timeout[1] }) };
252
- return { ok: false, ms, code: e.code || `exit ${r.status}`, refusal: fetchRefusal(e.code, { ...ctx, summary: e.summary }) };
324
+ if (timeout)
325
+ return { ok: false, ms, code: e.code, refusal: fetchRefusal("FETCH_TIMEOUT", { ...ctx, url: timeout[1] }) };
326
+ return {
327
+ ok: false,
328
+ ms,
329
+ code: e.code || `exit ${r.status}`,
330
+ refusal: fetchRefusal(e.code, { ...ctx, summary: e.summary }),
331
+ };
253
332
  }
254
333
  const root = join(dir, "node_modules", shell);
255
334
  const wrong = verifyFetched(root, { shell, version, pluginName: s.plugin_name, coreName });
@@ -270,14 +349,21 @@ export function fetchRunId() {
270
349
  // dead run's directory is caught by a later sweep: it converges.
271
350
  export function sweepFetchRuns(fetchDir) {
272
351
  let names;
273
- try { names = readdirSync(fetchDir); } catch { return []; }
352
+ try {
353
+ names = readdirSync(fetchDir);
354
+ } catch {
355
+ return [];
356
+ }
274
357
  const removed = [];
275
358
  for (const n of names) {
276
359
  const m = /^(\d+)-\d+$/.exec(n);
277
360
  if (!m) continue;
278
361
  const pid = Number(m[1]);
279
362
  if (!pid || pid === process.pid || pidAlive(pid)) continue;
280
- try { removeTreeUnder(join(fetchDir, n), fetchDir, { maxRetries: 3 }); removed.push(n); } catch {}
363
+ try {
364
+ removeTreeUnder(join(fetchDir, n), fetchDir, { maxRetries: 3 });
365
+ removed.push(n);
366
+ } catch {}
281
367
  }
282
368
  return removed;
283
369
  }
@@ -23,7 +23,8 @@ import {
23
23
  buildNodeIndex,
24
24
  extractLinks,
25
25
  resolveLinkTarget,
26
- storyMatchesEntry, isMain,
26
+ storyMatchesEntry,
27
+ isMain,
27
28
  commandForm,
28
29
  } from "./lib.mjs";
29
30
  import { walkVaultFiles } from "./doctor.mjs";
@@ -39,9 +40,7 @@ function refsOf(fm, key) {
39
40
  const viaList = listOf(fm, key);
40
41
  if (viaList.length) return viaList;
41
42
  const raw = fm[key];
42
- return typeof raw === "string" && raw && raw !== "[]" && !raw.trim().startsWith("[")
43
- ? [raw.trim()]
44
- : [];
43
+ return typeof raw === "string" && raw && raw !== "[]" && !raw.trim().startsWith("[") ? [raw.trim()] : [];
45
44
  }
46
45
 
47
46
  // Resolve a qualified "<epic-id>/<story-id>" spec entry to a story node —
@@ -58,8 +57,10 @@ function resolveStoryEntry(entry, index, epicsPath) {
58
57
  if (n.type !== "story" || !n.path.startsWith(`${epicsPath}/${epicId}/`)) continue;
59
58
  const tier = storyMatchesEntry(storyId, { id: n.identity, stem: n.stem });
60
59
  if (!tier) continue;
61
- if (best === 0 || tier < best) { best = tier; hits = [n]; }
62
- else if (tier === best) hits.push(n);
60
+ if (best === 0 || tier < best) {
61
+ best = tier;
62
+ hits = [n];
63
+ } else if (tier === best) hits.push(n);
63
64
  }
64
65
  if (hits.length === 1) return { outcome: "node", node: hits[0] };
65
66
  if (hits.length > 1) return { outcome: "ambiguous", candidates: hits.map((n) => n.path).sort() };
@@ -151,8 +152,7 @@ export function buildGraph(cfg, layout, { files = null } = {}) {
151
152
  // machines and locales; minimal diffs on a synced root file.
152
153
  const cmp = (a, b) => (a < b ? -1 : a > b ? 1 : 0);
153
154
  const nodeRows = [...index.nodes].sort((a, b) => cmp(a.path, b.path));
154
- const edgeRows = [...edges.values()].sort(
155
- (a, b) => cmp(a.from, b.from) || cmp(a.kind, b.kind) || cmp(a.to, b.to));
155
+ const edgeRows = [...edges.values()].sort((a, b) => cmp(a.from, b.from) || cmp(a.kind, b.kind) || cmp(a.to, b.to));
156
156
 
157
157
  const esc = (s) => String(s).replace(/\|/g, "\\|");
158
158
  const lines = [
@@ -208,11 +208,17 @@ function main() {
208
208
  if (!cfg) die(`No projectstore config. Run ${commandForm("bind")} first.`);
209
209
  const layout = loadLayout(cfg.layout);
210
210
  const g = buildGraph(cfg, layout);
211
- process.stdout.write(JSON.stringify({
212
- path: join(cfg.vault_path, "graph.md"),
213
- content: g.content,
214
- stats: g.stats,
215
- }, null, 2) + "\n");
211
+ process.stdout.write(
212
+ JSON.stringify(
213
+ {
214
+ path: join(cfg.vault_path, "graph.md"),
215
+ content: g.content,
216
+ stats: g.stats,
217
+ },
218
+ null,
219
+ 2,
220
+ ) + "\n",
221
+ );
216
222
  }
217
223
 
218
224
  if (isMain(import.meta.url)) {
@@ -51,9 +51,11 @@ let _cache = null;
51
51
  export function loadHarnesses(dir = MANIFEST_DIR) {
52
52
  if (_cache && _cache.dir === dir) return _cache.map;
53
53
  const map = new Map();
54
- let names = [];
54
+ let names;
55
55
  try {
56
- names = readdirSync(dir).filter((n) => n.endsWith(".json")).sort();
56
+ names = readdirSync(dir)
57
+ .filter((n) => n.endsWith(".json"))
58
+ .sort();
57
59
  } catch {
58
60
  names = [];
59
61
  }
@@ -153,7 +155,8 @@ export function identifiedHarnessId(env = process.env, dir = MANIFEST_DIR) {
153
155
  if (forced && loadHarnesses(dir).has(forced)) return forced;
154
156
  // A parent of ours decided before it named the project in the harness's own
155
157
  // vocabulary (childEnv), so its answer stands — an empty one included.
156
- if (env[IDENTIFIED_ENV] !== undefined) return loadHarnesses(dir).has(env[IDENTIFIED_ENV]) ? env[IDENTIFIED_ENV] : null;
158
+ if (env[IDENTIFIED_ENV] !== undefined)
159
+ return loadHarnesses(dir).has(env[IDENTIFIED_ENV]) ? env[IDENTIFIED_ENV] : null;
157
160
  const best = ranked(env, dir);
158
161
  if (best && best.strong) return best.id;
159
162
  for (const m of loadHarnesses(dir).values()) {
@@ -239,11 +242,16 @@ export function detectHarnesses(projectDir, { dir = MANIFEST_DIR, state = false
239
242
  const p = state ? layoutPaths(projectDir, { dir }) : null;
240
243
  for (const m of loadHarnesses(dir).values()) {
241
244
  const d = m.runtime?.harness_dir;
242
- if (d && existsSync(join(projectDir, d))) { out.push({ id: m.id, why: "directory", evidence: d }); continue; }
245
+ if (d && existsSync(join(projectDir, d))) {
246
+ out.push({ id: m.id, why: "directory", evidence: d });
247
+ continue;
248
+ }
243
249
  if (!p) continue;
244
250
  const at = p.harnessState(m.id);
245
251
  let isDir = false;
246
- try { isDir = statSync(at).isDirectory(); } catch {}
252
+ try {
253
+ isDir = statSync(at).isDirectory();
254
+ } catch {}
247
255
  if (isDir) out.push({ id: m.id, why: "state", evidence: relative(projectDir, at) });
248
256
  }
249
257
  return out;
@@ -256,10 +264,15 @@ export function detectHarnesses(projectDir, { dir = MANIFEST_DIR, state = false
256
264
  export function whichOnPath(name, env = process.env) {
257
265
  const sep = process.platform === "win32" ? ";" : ":";
258
266
  const exts = process.platform === "win32" ? ["", ".cmd", ".exe", ".bat"] : [""];
259
- for (const dir of String(env.PATH || "").split(sep).filter(Boolean)) {
267
+ for (const dir of String(env.PATH || "")
268
+ .split(sep)
269
+ .filter(Boolean)) {
260
270
  for (const ext of exts) {
261
271
  const p = join(dir, name + ext);
262
- try { const st = statSync(p); if (st.isFile() && (process.platform === "win32" || (st.mode & 0o111))) return p; } catch {}
272
+ try {
273
+ const st = statSync(p);
274
+ if (st.isFile() && (process.platform === "win32" || st.mode & 0o111)) return p;
275
+ } catch {}
263
276
  }
264
277
  }
265
278
  return null;
@@ -279,13 +292,25 @@ export function whichOnPath(name, env = process.env) {
279
292
  // what was looked for (null when the manifest names none), so a reason can
280
293
  // name them when either is missing.
281
294
  export function hostPresence(manifest, { env = process.env, home = homedir() } = {}) {
282
- 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;
295
+ const s =
296
+ Object.entries(manifest?.surfaces || {}).find(
297
+ ([k, x]) =>
298
+ !k.startsWith("_") &&
299
+ x?.kind === "registration" &&
300
+ x.supported !== false &&
301
+ typeof x.cli?.bin === "string" &&
302
+ x.cli.bin,
303
+ )?.[1] || null;
283
304
  const bin = s ? s.cli.bin : null;
284
305
  const r = manifest?.runtime || {};
285
306
  const fromEnv = r.home_env && env ? env[r.home_env] : null;
286
307
  const homeDir = fromEnv || (home && r.home_default ? join(home, r.home_default) : null);
287
308
  let present = false;
288
- if (homeDir) { try { present = statSync(homeDir).isDirectory(); } catch {} }
309
+ if (homeDir) {
310
+ try {
311
+ present = statSync(homeDir).isDirectory();
312
+ } catch {}
313
+ }
289
314
  return { cli: bin ? whichOnPath(bin, env || {}) : null, home: present ? homeDir : null, bin, homeDir };
290
315
  }
291
316
 
@@ -305,7 +330,10 @@ export function commonBlockFiles(manifests) {
305
330
  // A manifest's agents-block row as [key, surface], or null: found by its
306
331
  // format, as the installer's handlers are keyed, never by the key's name.
307
332
  export function agentsBlockRow(manifest) {
308
- return Object.entries(manifest?.surfaces || {}).find(([k, s]) => !k.startsWith("_") && s?.format === "markdown-block") || null;
333
+ return (
334
+ Object.entries(manifest?.surfaces || {}).find(([k, s]) => !k.startsWith("_") && s?.format === "markdown-block") ||
335
+ null
336
+ );
309
337
  }
310
338
 
311
339
  // Rule 2, for the schema test: the manifests' lists share a file, or a run of
@@ -321,13 +349,24 @@ export function blockTargetProblem(manifests) {
321
349
  // manifests, so a new harness appears in it without an edit here. With
322
350
  // `state` (upgrade's set) it names both signals the selection read.
323
351
  export function harnessRefusal(projectDir, { dir = MANIFEST_DIR, state = false } = {}) {
324
- const lines = [`No harness detected in ${projectDir}, and none named. Name one:`];
325
352
  const p = state ? layoutPaths(projectDir, { dir }) : null;
326
- for (const m of loadHarnesses(dir).values()) {
353
+ const rows = [...loadHarnesses(dir).values()].map((m) => {
327
354
  const by = `detected by its project directory: ${m.runtime?.harness_dir || "?"}`;
328
- lines.push(` --harness ${m.id} (${m.display_name}; ${p ? `${by}, or by its state directory: ${relative(projectDir, p.harnessState(m.id))}` : by})`);
329
- }
330
- return lines.join("\n");
355
+ return {
356
+ id: m.id,
357
+ display: m.display_name,
358
+ why: p ? `${by}, or by its state directory: ${relative(projectDir, p.harnessState(m.id))}` : by,
359
+ };
360
+ });
361
+ return [`No harness detected in ${projectDir}, and none named. Name one:`, ...harnessNameLines(rows)].join("\n");
362
+ }
363
+
364
+ // That refusal's rows, one per harness — `--harness <id>`, then its display
365
+ // name and why — shared with setup's (its rule 12), so the two cannot drift.
366
+ // The ids are padded to one width, so every reason starts in one column.
367
+ export function harnessNameLines(rows) {
368
+ const width = Math.max(0, ...rows.map((r) => r.id.length));
369
+ return rows.map((r) => ` --harness ${r.id.padEnd(width)} (${r.display}; ${r.why})`);
331
370
  }
332
371
 
333
372
  // Inside a live session of the host, its CLI and the session both rewrite the
@@ -396,7 +435,10 @@ export function invocation(manifest, name, { kind = "commands", args = "" } = {}
396
435
  // read these same patterns.
397
436
  export function uiWordPatterns(manifest) {
398
437
  const esc = (t) => t.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
399
- return (manifest?.ui_vocabulary || []).map((word) => ({ word, re: new RegExp(`(?<![\\w.-])${esc(word)}(?![\\w-]|\\.\\w)`, "g") }));
438
+ return (manifest?.ui_vocabulary || []).map((word) => ({
439
+ word,
440
+ re: new RegExp(`(?<![\\w.-])${esc(word)}(?![\\w-]|\\.\\w)`, "g"),
441
+ }));
400
442
  }
401
443
 
402
444
  // The harness whose distribution shell bundles this core, by the shell's
@@ -417,7 +459,9 @@ export function bundlingShellHarnessId({ core = REPO_ROOT, dir = MANIFEST_DIR }
417
459
  const name = JSON.parse(readFileSync(join(dirname(parent), "package.json"), "utf8")).name;
418
460
  id = [...loadHarnesses(dir).values()].find((m) => m.install?.shell && m.install.shell === name)?.id ?? null;
419
461
  }
420
- } catch { id = null; }
462
+ } catch {
463
+ id = null;
464
+ }
421
465
  if (memo) _bundling = id;
422
466
  return id;
423
467
  }
@@ -441,10 +485,8 @@ function speaker(env, dir) {
441
485
  if (identified) return identified;
442
486
  const bundled = bundlingShellHarnessId({ dir });
443
487
  if (bundled) return bundled;
444
- if (env.PROJECTSTORE_SHELL) {
445
- const named = [...loadHarnesses(dir).values()].find((m) => m.install?.shell === env.PROJECTSTORE_SHELL);
446
- if (named) return named.id;
447
- }
488
+ const named = shellHarnessId(env, dir);
489
+ if (named) return named;
448
490
  return sourceHarness(dir)?.id ?? null;
449
491
  }
450
492
 
@@ -550,7 +592,13 @@ function hostPluginRoot(env) {
550
592
  // bin's child), is honoured as named. Real paths on both sides: the module's
551
593
  // own is already real, so a root under a symlink (macOS's /var and /tmp)
552
594
  // would never compare.
553
- const realOr = (p) => { try { return realpathSync(p); } catch { return resolve(p); } };
595
+ const realOr = (p) => {
596
+ try {
597
+ return realpathSync(p);
598
+ } catch {
599
+ return resolve(p);
600
+ }
601
+ };
554
602
  let _realCore = null;
555
603
  function containsThisCore(root) {
556
604
  const core = (_realCore ??= realOr(REPO_ROOT));
@@ -577,7 +625,7 @@ export function agentHome(env = process.env, home = homedir()) {
577
625
  // path is spelled — every reader and writer goes through layoutPaths(), and a
578
626
  // test greps the rest of scripts/, hooks/ and bin/ for the literals. The
579
627
  // legacy shape (.claude/projectstore.json, .claude/.projectstore/…) is named
580
- // here too, for the readers' fallback through 0.29 (layout spec, contracts
628
+ // here too, for the readers' fallback through 0.30 (layout spec, contracts
581
629
  // 0, 1 and 7); its harness directory is the source harness's own.
582
630
  export const LAYOUT = Object.freeze({
583
631
  root: ".projectstore",
@@ -648,7 +696,7 @@ export function cachePaths({ env = process.env, home = homedir() } = {}) {
648
696
  const variable = "XDG_CACHE_HOME";
649
697
  const xdg = env ? env[variable] : null;
650
698
  const fromEnv = typeof xdg === "string" && xdg !== "" && isAbsolute(xdg);
651
- const base = fromEnv ? xdg : (home ? join(home, ".cache") : null);
699
+ const base = fromEnv ? xdg : home ? join(home, ".cache") : null;
652
700
  const root = base ? join(base, "projectstore") : null;
653
701
  return {
654
702
  root,
@@ -660,30 +708,47 @@ export function cachePaths({ env = process.env, home = homedir() } = {}) {
660
708
  };
661
709
  }
662
710
 
663
- // The command a user types from a terminal for this harness (the layout ADR
664
- // decision 6; layout spec contract 12): the harness's distribution shell when
665
- // the manifest names one — `npx projectstore-claude install --project "…"`,
666
- // the harness fixed by the shell — else the core with --harness. Finding
667
- // messages and deferred reasons are built here, so the installer names no
668
- // harness id and no shell name of its own. The shell's name is data
669
- // (install.shell), not `projectstore-<id>`: the id is claude-code, the
670
- // published name is projectstore-claude.
671
- export function packageCommand(harness, verb, { version = null, args = "" } = {}) {
672
- const shell = harness?.install?.shell || null;
673
- const pkg = `${shell || "projectstore"}${version ? `@${version}` : ""}`;
674
- const fixed = shell ? "" : ` --harness ${harness?.id || "<id>"}`;
675
- return `npx ${pkg} ${verb}${fixed}${args ? ` ${args}` : ""}`;
676
- }
677
-
678
- // The package this run was invoked as, for a command it prints to be typed
679
- // next: the shell it came through (the shell's bin sets PROJECTSTORE_SHELL,
680
- // and fixes the harness, so a verb that takes --harness needs none), else the
681
- // core. packageCommand() above is the install family's, per harness; this one
682
- // is for the verbs that name no harness (bind, status, scaffold, reconcile),
683
- // which every shell passes through. `npx` runs it with no bin on PATH.
711
+ // The core through npx: how every command a person is told to type next
712
+ // begins (the story "User-facing text says where to run and names no project
713
+ // path and no shell", rules 2 and 6). `npx` runs it with no bin on PATH.
714
+ export const CORE_NPX = "npx projectstore";
715
+
716
+ // The command a person types from a terminal (the front-door ADR, decision 5;
717
+ // the story above, rule 2): always the core, with one --harness per manifest
718
+ // in the order given — `npx projectstore[@<v>] <verb> --harness a [--harness
719
+ // b] [args]`. It names no shell, whatever the manifest's install.shell says,
720
+ // and its callers pass no --project: where to run it is their prose, `from a
721
+ // terminal in "<dir>"` (lib.mjs fromTerminalIn). The id stays because a bare
722
+ // upgrade or uninstall plans every harness the project uses. An empty array
723
+ // names none, for a verb that takes no --harness (bind, status, scaffold,
724
+ // reconcile). Finding messages, deferred reasons and DONE's tip are built
725
+ // here, so the installer spells no command of its own. The string is built
726
+ // here, not by the converge story's coreCommand, whose module imports this one.
727
+ export function packageCommand(harnesses, verb, { version = null, args = "" } = {}) {
728
+ const list = Array.isArray(harnesses) ? harnesses : [harnesses];
729
+ const ids = list.map((h) => ` --harness ${h?.id || "<id>"}`).join("");
730
+ return `${CORE_NPX}${version ? `@${version}` : ""} ${verb}${ids}${args ? ` ${args}` : ""}`;
731
+ }
732
+
733
+ // The package this run was invoked as: the shell it came through (the shell's
734
+ // bin sets PROJECTSTORE_SHELL, and fixes the harness), else the core. Only
735
+ // what describes the binary that ran uses it — the help's first line, its
736
+ // Usage lines, the fixed-harness line and the usage errors (the story above,
737
+ // rule 6). A command printed for a person to type next is the core's
738
+ // (packageCommand, CORE_NPX), through a shell too.
684
739
  export function invokedAs(env = process.env) {
685
740
  const shell = env.PROJECTSTORE_SHELL || null;
686
- return { shell, cmd: shell ? `npx ${shell}` : "npx projectstore" };
741
+ return { shell, cmd: shell ? `npx ${shell}` : CORE_NPX };
742
+ }
743
+
744
+ // The harness a shell fixes: the manifest whose install.shell is the name the
745
+ // shell's bin exports (PROJECTSTORE_SHELL), or null. Never speakingHarnessId,
746
+ // which a session's identity overrides: the Codex shell run inside a Claude
747
+ // Code session still installs Codex, so its help's examples name codex.
748
+ export function shellHarnessId(env = process.env, dir = MANIFEST_DIR) {
749
+ const shell = env.PROJECTSTORE_SHELL;
750
+ if (!shell) return null;
751
+ return [...loadHarnesses(dir).values()].find((m) => m.install?.shell === shell)?.id ?? null;
687
752
  }
688
753
 
689
754
  // The overlay a harness reads: <project>/.projectstore/harness/<overlay>.json —
@@ -852,7 +917,11 @@ export function lintPatterns(harness, dir = MANIFEST_DIR) {
852
917
  // shared_env to the derivation below would forbid Claude Code's own variable
853
918
  // inside Claude Code's own tree.
854
919
  const o = harness.runtime || {};
855
- const own = new Set([o.project_dir_env, o.plugin_root_env, o.home_env, ...(o.detect_env || []), ...(o.shared_env || [])].filter(Boolean));
920
+ const own = new Set(
921
+ [o.project_dir_env, o.plugin_root_env, o.home_env, ...(o.detect_env || []), ...(o.shared_env || [])].filter(
922
+ Boolean,
923
+ ),
924
+ );
856
925
  for (const m of loadHarnesses(dir).values()) {
857
926
  if (m.id === harness.id) continue;
858
927
  for (const t of m.tools?.write_tools || []) out.push({ pattern: `\\b${t}\\b`, class: "token", derived: true });
@@ -860,7 +929,13 @@ export function lintPatterns(harness, dir = MANIFEST_DIR) {
860
929
  // shared_env included: a name is no less branded for being set by two
861
930
  // harnesses, and it exists in no other field of the manifest that declares
862
931
  // it — CLAUDE_PLUGIN_DATA appears nowhere but codex.json's shared_env.
863
- for (const k of [r.project_dir_env, r.plugin_root_env, r.home_env, ...(r.detect_env || []), ...(r.shared_env || [])]) {
932
+ for (const k of [
933
+ r.project_dir_env,
934
+ r.plugin_root_env,
935
+ r.home_env,
936
+ ...(r.detect_env || []),
937
+ ...(r.shared_env || []),
938
+ ]) {
864
939
  if (k && !own.has(k)) out.push({ pattern: `\\b${k}\\b`, class: "token", derived: true });
865
940
  }
866
941
  }