projectstore-claude 0.29.4 → 0.30.1

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.
@@ -18,7 +18,8 @@
18
18
  // npmUserRegistry({ home, env }) → the user's own registry, read from home, or null
19
19
  // fetchShell(job, { dir, registry }) → { ok, root, ms } or { ok: false, code, refusal }
20
20
  // verifyFetched(root, { … }) → null, or the refusal naming file and values
21
- // fetchRefusal(code, ctx) → rule 4's texts
21
+ // fetchRefusal(code, ctx) → rule 4's texts, the envelope's string
22
+ // fetchRefusalAdvice(code, ctx) → the same, as PLAN draws it: { text, blocks }
22
23
  // sweepFetchRuns(fetchDir) → the leftovers of dead runs, removed
23
24
  // fetchRunId() → <pid>-<epoch ms>
24
25
  //
@@ -29,8 +30,8 @@
29
30
 
30
31
  import { existsSync, readFileSync, readdirSync } from "node:fs";
31
32
  import { join } from "node:path";
32
- import { registrationDeferred } from "./harness.mjs";
33
- import { removeTreeUnder, pidAlive, whichOnPath } from "./lib.mjs";
33
+ import { registrationDeferred, packageCommand } from "./harness.mjs";
34
+ import { removeTreeUnder, pidAlive, whichOnPath, fromTerminalIn } from "./lib.mjs";
34
35
  import {
35
36
  isPortablePluginRoot,
36
37
  payloadManifest,
@@ -213,12 +214,45 @@ export function npmError(stdout, stderr) {
213
214
 
214
215
  const seconds = (ms) => `${Number((ms / 1000).toFixed(ms % 1000 ? 1 : 0))} s`;
215
216
 
216
- // Rule 4's refusals, by npm's code or ours. `ctx`: pkg ("<shell>@<v>"),
217
- // shell, registry (null: npm's own), display (the harness's display name),
218
- // budget, summary (npm's), cause (a start failure's), path/from/variable (the
219
- // cache). Every way out is a terminal command or a variable; none names a
220
- // version but the one this run is at.
221
- export function fetchRefusal(code, ctx = {}) {
217
+ // npm's own registry: the one README's registry-mirror advice names.
218
+ export const PUBLIC_REGISTRY = "https://registry.npmjs.org";
219
+
220
+ // A registry that has no such shell may be a mirror that has not synced it:
221
+ // the run once more, from npm's public registry, in README's form — the
222
+ // variable, not `npx --registry`, because `npm config get registry`, which
223
+ // the fetch's resolver reads, honours it (the story "User-facing text says
224
+ // where to run and names no project path and no shell", rule 7). It is the
225
+ // run the person just saw: its verb and version, and its selection as given —
226
+ // each named --harness, each --surface, and --no-register — never --project
227
+ // (the front-door ADR, decision 5); the directory goes in the lead, and the
228
+ // command stands alone after it (rule 4). `args` is the shape the converge
229
+ // story's stop repeats a run with. Null when the run is unknown, or when the
230
+ // registry is already the public one; a null registry is npm's own
231
+ // resolution, which can be a mirror, so it gets the line.
232
+ function mirrorBlock({ registry = null, verb = null, version = null, args = {}, project = null } = {}) {
233
+ if (!verb || !version || String(registry || "").replace(/\/+$/, "") === PUBLIC_REGISTRY) return null;
234
+ const { harnesses = [], surfaces = null, register = true } = args || {};
235
+ const narrowing = [
236
+ ...(surfaces || []).map((s) => `--surface ${s}`),
237
+ ...(register === false ? ["--no-register"] : []),
238
+ ];
239
+ const command = packageCommand(
240
+ harnesses.map((id) => ({ id })),
241
+ verb,
242
+ { version, args: narrowing.join(" ") },
243
+ );
244
+ const where = project ? fromTerminalIn(project) : "from a terminal in this project";
245
+ return {
246
+ lead: `A mirror that has not synced it? Run this again from npm's public registry, ${where}:`,
247
+ command: `npm_config_registry=${PUBLIC_REGISTRY} ${command}`,
248
+ };
249
+ }
250
+
251
+ // Rule 4's refusals, as PLAN draws them: `{ text, blocks }`, the prose, then
252
+ // each lead and its command (presentation spec contract 6), so PLAN prints a
253
+ // command whole, unwrapped, alone on its line. Only the missing shell has a
254
+ // block today; every other refusal is its text alone.
255
+ export function fetchRefusalAdvice(code, ctx = {}) {
222
256
  const {
223
257
  pkg = "the shell",
224
258
  shell = "the shell",
@@ -233,29 +267,61 @@ export function fetchRefusal(code, ctx = {}) {
233
267
  } = ctx;
234
268
  const where = registry || "the registry npm resolves";
235
269
  const without = `name --harness without ${display}`;
270
+ const said = (text, blocks = []) => ({ text, blocks });
236
271
  switch (code) {
237
272
  case "ETARGET":
238
- case "E404":
239
- return `${pkg} is not on ${where} (npm ${code}); ${display} is registered from that shell at this exact version, and no other version is tried. Just released? The shell is published after the core, so retry in a few minutes. From a checkout at an unpublished version, point PROJECTSTORE_DISTRIBUTION_ROOT at the output of \`npm run shells:build -- --dev\` (dist/build/${shell}). Or ${without}.`;
273
+ case "E404": {
274
+ const mirror = mirrorBlock(ctx);
275
+ return said(
276
+ `${pkg} is not on ${where} (npm ${code}); ${display} is registered from that shell at this exact version, and no other version is tried. Just released? The shell is published after the core, so retry in a few minutes. From a checkout at an unpublished version, point PROJECTSTORE_DISTRIBUTION_ROOT at the output of \`npm run shells:build -- --dev\` (dist/build/${shell}). Or ${without}.`,
277
+ mirror ? [mirror] : [],
278
+ );
279
+ }
240
280
  // Our budget, not npm's: npm's own ETIMEDOUT (a socket) is any other code.
241
281
  case "EBUDGET":
242
- return `fetching ${pkg} from ${where} took longer than ${seconds(budget)} and was stopped. Retry, or ${without}.`;
282
+ return said(
283
+ `fetching ${pkg} from ${where} took longer than ${seconds(budget)} and was stopped. Retry, or ${without}.`,
284
+ );
243
285
  case "FETCH_TIMEOUT":
244
- return `npm gave up on ${ctx.url || where} (network timeout) while fetching ${pkg}. Retry, or ${without}.`;
286
+ return said(`npm gave up on ${ctx.url || where} (network timeout) while fetching ${pkg}. Retry, or ${without}.`);
245
287
  case "E401":
246
288
  case "E403":
247
- return `${where} refused the credentials for ${pkg} (npm ${code}). A project .npmrc's token does not reach this fetch — only its registry does — so the registry's token must be in user config: ~/.npmrc, or an NPM_CONFIG_… variable. Or point PROJECTSTORE_DISTRIBUTION_ROOT at a ${shell} root obtained another way.`;
289
+ return said(
290
+ `${where} refused the credentials for ${pkg} (npm ${code}). A project .npmrc's token does not reach this fetch — only its registry does — so the registry's token must be in user config: ~/.npmrc, or an NPM_CONFIG_… variable. Or point PROJECTSTORE_DISTRIBUTION_ROOT at a ${shell} root obtained another way.`,
291
+ );
248
292
  case "ESTART":
249
- return `${cause}; ${display} is registered from its shell, which npm fetches. Put npm on PATH, or ${without}.`;
293
+ return said(
294
+ `${cause}; ${display} is registered from its shell, which npm fetches. Put npm on PATH, or ${without}.`,
295
+ );
250
296
  case "ENOCACHE":
251
- return `the shell fetch has no cache directory: ${variable} is not an absolute path and the home directory is unknown. Set ${variable} to a writable directory, then run this again.`;
297
+ return said(
298
+ `the shell fetch has no cache directory: ${variable} is not an absolute path and the home directory is unknown. Set ${variable} to a writable directory, then run this again.`,
299
+ );
252
300
  case "ECACHE":
253
- return `the cache directory ${path} cannot be written (${ctx.errno || "error"}); it comes from ${from}. Set ${variable} to a writable directory, then run this again.`;
301
+ return said(
302
+ `the cache directory ${path} cannot be written (${ctx.errno || "error"}); it comes from ${from}. Set ${variable} to a writable directory, then run this again.`,
303
+ );
254
304
  default:
255
- return `npm could not fetch ${pkg} from ${where}: ${code || "an unknown error"}${summary ? ` — ${summary.split(/\r?\n/)[0]}` : ""}. ${display} is registered from its shell, which needs the network: retry once the registry is reachable, or ${without}.`;
305
+ return said(
306
+ `npm could not fetch ${pkg} from ${where}: ${code || "an unknown error"}${summary ? ` — ${summary.split(/\r?\n/)[0]}` : ""}. ${display} is registered from its shell, which needs the network: retry once the registry is reachable, or ${without}.`,
307
+ );
256
308
  }
257
309
  }
258
310
 
311
+ // Rule 4's refusals, by npm's code or ours: the envelope's string, every part
312
+ // on its own line — the prose, then each lead and its command — which an agent
313
+ // relays as it is. `ctx`: pkg ("<shell>@<v>"), shell, registry (null: npm's
314
+ // own), display (the harness's display name), budget, summary (npm's), cause
315
+ // (a start failure's), path/from/variable (the cache), and the run — its verb,
316
+ // version, project and `args` (the selection as given) — which the missing
317
+ // shell's refusal repeats from the public registry. Every way out is a
318
+ // terminal command or a variable; none names a version but the one this run
319
+ // is at.
320
+ export function fetchRefusal(code, ctx = {}) {
321
+ const { text, blocks } = fetchRefusalAdvice(code, ctx);
322
+ return [text, ...blocks.flatMap((b) => [b.lead, b.command])].join("\n");
323
+ }
324
+
259
325
  // Rule 3: the fetched tree is what this run plans, before it is planned —
260
326
  // the shell's name and version, a plugin root by the analyser's own predicate,
261
327
  // its plugin manifest's name and version, and the bundled core at the same
@@ -294,26 +360,29 @@ export function verifyFetched(root, { shell, version, pluginName, coreName }) {
294
360
  // as *** (measured). A failure is a refusal before the plan, never a fallback.
295
361
  export async function fetchShell(
296
362
  { harness, s, version, coreName },
297
- { dir, registry = null, env = process.env, spawn, budget = HOST_BUDGET_MS } = {},
363
+ { dir, registry = null, env = process.env, spawn, budget = HOST_BUDGET_MS, run = {} } = {},
298
364
  ) {
299
365
  const shell = harness.install.shell;
300
366
  const pkg = `${shell}@${version}`;
301
- const ctx = { pkg, shell, registry, display: harness.display_name, budget };
367
+ // `run`: the verb, selection (`args`) and project of the run that fetches,
368
+ // for the missing shell's public-registry form; the version is this one.
369
+ const ctx = { pkg, shell, registry, display: harness.display_name, budget, ...run, version };
370
+ // A refusal in both forms: the envelope's string, and what PLAN draws.
371
+ const refused = (code, extra = {}) => ({
372
+ refusal: fetchRefusal(code, { ...ctx, ...extra }),
373
+ advice: fetchRefusalAdvice(code, { ...ctx, ...extra }),
374
+ });
302
375
  const call = npmCall(fetchArgv({ prefix: dir, registry, shell, version }), env);
303
376
  const t0 = Date.now();
304
377
  const r = await runHost(call.bin, call.argv, { env, cwd: dir, budget, spawn, shell: call.shell });
305
378
  const ms = Date.now() - t0;
306
379
  if (r.error) {
307
- if (r.error.code === "ETIMEDOUT")
308
- return { ok: false, ms, code: "ETIMEDOUT", refusal: fetchRefusal("EBUDGET", ctx) };
380
+ if (r.error.code === "ETIMEDOUT") return { ok: false, ms, code: "ETIMEDOUT", ...refused("EBUDGET") };
309
381
  return {
310
382
  ok: false,
311
383
  ms,
312
384
  code: r.error.code || "ESTART",
313
- refusal: fetchRefusal("ESTART", {
314
- ...ctx,
315
- cause: startFailure(r.error, { bin: "npm", resolved: call.resolved, cwd: dir }),
316
- }),
385
+ ...refused("ESTART", { cause: startFailure(r.error, { bin: "npm", resolved: call.resolved, cwd: dir }) }),
317
386
  };
318
387
  }
319
388
  if (r.status !== 0) {
@@ -321,14 +390,8 @@ export async function fetchShell(
321
390
  // npm reports a request it gave up on as FETCH_ERROR, "network timeout
322
391
  // at: <url>" (measured in review, 2026-10-08), not as ETIMEDOUT.
323
392
  const timeout = e.code === "FETCH_ERROR" && /network timeout at:\s*(\S+)/.exec(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
- };
393
+ if (timeout) return { ok: false, ms, code: e.code, ...refused("FETCH_TIMEOUT", { url: timeout[1] }) };
394
+ return { ok: false, ms, code: e.code || `exit ${r.status}`, ...refused(e.code, { summary: e.summary }) };
332
395
  }
333
396
  const root = join(dir, "node_modules", shell);
334
397
  const wrong = verifyFetched(root, { shell, version, pluginName: s.plugin_name, coreName });
@@ -779,6 +779,14 @@ export function hasBand(manifest) {
779
779
  return manifest?.surfaces?.band?.supported === true;
780
780
  }
781
781
 
782
+ // Whether a harness has the status-line surface: the one predicate for "a
783
+ // harness without a status line", read by configure (its spec, contract 2).
784
+ // Install's own test is the same: a surface declared and not unsupported.
785
+ export function hasStatusLine(manifest) {
786
+ const s = manifest?.surfaces?.statusline;
787
+ return Boolean(s) && s.supported !== false;
788
+ }
789
+
782
790
  // The session id the host hands a tool process, by the manifest's name for
783
791
  // it (runtime.session_id_env), or null where the harness names none or the
784
792
  // process got none.
@@ -1678,15 +1678,21 @@ function planKeepRecord(ctx) {
1678
1678
  });
1679
1679
  }
1680
1680
 
1681
- // The status line's flag (the setup story, rule 9): setup's answer stored as
1682
- // `statusline.enabled`, the key bind's interview writes; every other key of
1683
- // a `statusline` object is kept. Planned for the run's harness that has the
1684
- // status-line surface, when the binding the run leaves does not already say
1685
- // the same; only when there is a binding to record it in.
1681
+ // The status line's flag (the setup story, rule 9; the configure spec,
1682
+ // contract 6): `statusline.enabled`, from setup's answer or from a run that
1683
+ // names the surface — install records on, uninstall off. This item is the
1684
+ // flag's one writer; every other key of a `statusline` object is kept.
1685
+ // Planned for the run's harness that has the status-line surface, when the
1686
+ // binding the run leaves does not already say the same; only when there is a
1687
+ // binding to record it in.
1686
1688
  const STATUSLINE_FLAG = "statusline.enabled";
1687
- function planStatuslineFlag(ctx, value) {
1689
+ function planStatuslineFlag(ctx, value, mode = "install") {
1688
1690
  const b = ctx.binding;
1689
1691
  if (!b || !b.bound || typeof value !== "boolean" || b.statusline === value) return null;
1692
+ const off =
1693
+ mode === "uninstall"
1694
+ ? "the status line is removed in this run, and the SessionStart hook keeps it off"
1695
+ : "the status line stays off, and setup does not ask again";
1690
1696
  return bindingItem({
1691
1697
  harness: ctx.harness.id,
1692
1698
  surface: "statusline_flag",
@@ -1697,7 +1703,7 @@ function planStatuslineFlag(ctx, value) {
1697
1703
  why: {
1698
1704
  [STATUSLINE_FLAG]: value
1699
1705
  ? "the status line is wired in this run, and the SessionStart hook keeps it current"
1700
- : "the status line stays off, and setup does not ask again",
1706
+ : off,
1701
1707
  },
1702
1708
  said: {
1703
1709
  unbound: "the project is not bound; the status line's flag is recorded once it is",
@@ -2342,12 +2348,24 @@ export function plan(
2342
2348
  const s = loadHarness(id).surfaces?.statusline;
2343
2349
  return Boolean(s) && s.supported !== false;
2344
2350
  }) || null;
2345
- const recordFor = (ctx) => {
2346
- if (mode === "uninstall") return;
2351
+ // The flag's value: setup's answer when it gave one; else, when the run
2352
+ // names the status-line surface, what the run does to it — on for install,
2353
+ // off for uninstall. Never on for a line this run neither wires nor finds
2354
+ // ours: a foreign slot, the keep's branch, a root that is never wired.
2355
+ const flagValue = (ctx, keep) => {
2356
+ if (typeof statusline === "boolean") return statusline;
2357
+ if (!(surfaces || []).includes("statusline")) return null;
2358
+ if (mode === "uninstall") return false;
2359
+ if (keep || ctx.slotForeign.has("statusline")) return null;
2360
+ const row = out.items.find((i) => i.harness === ctx.harness.id && i.surface === "statusline");
2361
+ return row && (row.action !== "skip" || row.state === "ours-current") ? true : null;
2362
+ };
2363
+ const recordFor = (ctx, { keep = false } = {}) => {
2347
2364
  if (ctx.harness.id === flagHarness) {
2348
- const flag = planStatuslineFlag(ctx, statusline);
2365
+ const flag = planStatuslineFlag(ctx, flagValue(ctx, keep), mode);
2349
2366
  if (flag) marks.push(flag);
2350
2367
  }
2368
+ if (mode === "uninstall") return;
2351
2369
  if (recordKeep && keeping && ctx.harness.id === keeping.harness.id) {
2352
2370
  const kept = planKeepRecord(ctx);
2353
2371
  if (kept) marks.push(kept);
@@ -2464,7 +2482,7 @@ export function plan(
2464
2482
  out.refusals.push(...ctx.refusals);
2465
2483
  if (ctx.incomplete) out.incomplete = true;
2466
2484
  stateFor(id, harness);
2467
- recordFor(ctx);
2485
+ recordFor(ctx, { keep: true });
2468
2486
  continue;
2469
2487
  }
2470
2488
  const hostRows = [];
@@ -5050,10 +5068,11 @@ async function fetchShells(
5050
5068
  }
5051
5069
  }
5052
5070
  if (!jobs.length) return none;
5053
- const refuse = (message, cleanup = () => {}) => ({
5054
- ...none,
5055
- cleanup,
5056
- refused: {
5071
+ // `advice`: the refusal as PLAN draws it, its commands in their own blocks
5072
+ // (fetchRefusalAdvice) — kept off the envelope, as the channel "git"
5073
+ // refusal's is, so `--json` keeps the one string.
5074
+ const refuse = (message, cleanup = () => {}, advice = null) => {
5075
+ const refused = {
5057
5076
  projectDir,
5058
5077
  mode: "install",
5059
5078
  named,
@@ -5066,8 +5085,10 @@ async function fetchShells(
5066
5085
  incomplete: false,
5067
5086
  root,
5068
5087
  plannedAgainst: {},
5069
- },
5070
- });
5088
+ };
5089
+ if (advice?.blocks?.length) Object.defineProperty(refused, "refusalAdvice", { value: advice, enumerable: false });
5090
+ return { ...none, cleanup, refused };
5091
+ };
5071
5092
  const cache = cachePaths({ env, home });
5072
5093
  if (!cache.root) return refuse(fetchRefusal("ENOCACHE", { variable: cache.variable }));
5073
5094
  sweepFetchRuns(cache.fetch);
@@ -5104,6 +5125,19 @@ async function fetchShells(
5104
5125
  const differs = Boolean(registry) && bare(registry) !== bare(mine);
5105
5126
  const payloadRoots = {},
5106
5127
  fetched = [];
5128
+ // The run, for the missing shell's public-registry form: its verb, its
5129
+ // project, and its selection as given, in the shape the stop repeats a
5130
+ // run with — each named --harness (setup's answered set is named too),
5131
+ // each --surface, --no-register.
5132
+ const run = {
5133
+ verb,
5134
+ project: projectDir,
5135
+ args: {
5136
+ harnesses: named ? (opts.harnesses || []).filter(Boolean) : [],
5137
+ surfaces: opts.surfaces || null,
5138
+ register: opts.register !== false,
5139
+ },
5140
+ };
5107
5141
  for (const job of jobs) {
5108
5142
  const { harness } = job;
5109
5143
  const pkg = `${harness.install.shell}@${version}`;
@@ -5112,10 +5146,13 @@ async function fetchShells(
5112
5146
  const dir = jobs.length === 1 ? runDir : join(runDir, harness.id);
5113
5147
  if (dir !== runDir) mkdirSync(dir, { recursive: true });
5114
5148
  line = opts.onFetch ? opts.onFetch(`fetching ${pkg} for ${harness.display_name}`, ids) : null;
5115
- const r = await fetchShell({ ...job, version, coreName }, { dir, registry, env, spawn: opts.fetchSpawn, budget });
5149
+ const r = await fetchShell(
5150
+ { ...job, version, coreName },
5151
+ { dir, registry, env, spawn: opts.fetchSpawn, budget, run },
5152
+ );
5116
5153
  if (!r.ok) {
5117
5154
  if (line) line.end(false, `fetch failed ${pkg}`, r.code);
5118
- return refuse(r.refusal, cleanup);
5155
+ return refuse(r.refusal, cleanup, r.advice);
5119
5156
  }
5120
5157
  if (line) line.end(true, `fetched ${pkg} for ${harness.display_name}`);
5121
5158
  line = null;
@@ -90,10 +90,15 @@ export function sharedRoleForm(name) {
90
90
  return invocation(sourceHarness(), name, { kind: "agents" });
91
91
  }
92
92
  // What a welcome says about updates, and the product name a message uses.
93
- export function updateHint({ env = process.env } = {}) {
93
+ export function updateHint({ env = process.env, root = pluginRoot(), home = homedir() } = {}) {
94
94
  const m = speakingHarness(env) || {};
95
95
  // A harness that declares no hint gets none — never another harness's advice.
96
- const hint = m.update_hint || { line: "", welcome: [] };
96
+ // A copy loaded from another channel than the hint's own says that
97
+ // channel's way to update (installChannel: string tests, no file read, so
98
+ // the SessionStart budget holds): a git-marketplace copy keeps the host's
99
+ // auto-update toggle, the npm registration and a checkout get the npm form.
100
+ const channel = m.update_hint?.by_channel ? installChannel(root, { home, harness: m }) : null;
101
+ const hint = (channel && m.update_hint.by_channel[channel]) || m.update_hint || { line: "", welcome: [] };
97
102
  // `{upgrade}` is the core's upgrade for this harness, pinned to latest so it
98
103
  // runs as printed, with no --project: the hint says where to run it (the
99
104
  // story "User-facing text says where to run…", rule 2). Any hint that holds
@@ -1723,8 +1728,9 @@ export function listOf(fm, key) {
1723
1728
  // the policy survives clones and second machines), Obsidian hides it, and it
1724
1729
  // is intentionally NOT inside <vault>/.projectstore/, whose .gitignore ("*")
1725
1730
  // would defeat the whole point. Keys: spec_policy ("required"|"optional"),
1726
- // lifecycle_gates ("on"|"off"), spec_policy_since (ISO-8601, stamped when
1727
- // spec_policy first becomes "required").
1731
+ // lifecycle_gates ("on"|"off"), spec_policy_since (ISO-8601, stamped whenever
1732
+ // spec_policy becomes "required" from anything else; kept otherwise — the
1733
+ // configure spec, contract 7).
1728
1734
  export function vaultConfigPath(vault) {
1729
1735
  return join(vault, LAYOUT.vaultConfig);
1730
1736
  }
@@ -1740,8 +1746,38 @@ export function readVaultConfig(vault) {
1740
1746
  }
1741
1747
  }
1742
1748
 
1749
+ // The strict read a writer needs: a file that exists and is not a JSON
1750
+ // object is `corrupt`, never an empty config a write would then replace.
1751
+ export function readVaultConfigStrict(vault) {
1752
+ const path = vaultConfigPath(vault);
1753
+ if (!existsSync(path)) return { path, present: false, corrupt: false, cfg: {} };
1754
+ try {
1755
+ const v = JSON.parse(readFileSync(path, "utf8"));
1756
+ if (v && typeof v === "object" && !Array.isArray(v)) return { path, present: true, corrupt: false, cfg: v };
1757
+ } catch {}
1758
+ return { path, present: true, corrupt: true, cfg: null };
1759
+ }
1760
+
1761
+ // The config a change leaves, pure. A return to "required" re-stamps
1762
+ // spec_policy_since: a story done before the policy (re)took effect is exempt
1763
+ // (ADR-007 decision 6), and since every story the old stamp exempted closed
1764
+ // before the new one, no exemption is lost.
1765
+ export function nextVaultConfig(before, patch, now = new Date().toISOString()) {
1766
+ const next = { ...before, ...patch };
1767
+ if (patch.spec_policy === "required" && before.spec_policy !== "required") {
1768
+ // Never earlier than the stamp it replaces: one written ahead of this
1769
+ // clock (a hand edit, a machine whose clock ran fast) would otherwise
1770
+ // shrink the exemption the old stamp gave.
1771
+ const prev = before.spec_policy_since;
1772
+ next.spec_policy_since = prev && String(prev) > now ? prev : now;
1773
+ }
1774
+ return next;
1775
+ }
1776
+
1777
+ // The one writer of the vault config: atomic, and every key it was not asked
1778
+ // to change is kept as it was.
1743
1779
  export function writeVaultConfig(vault, cfg) {
1744
- writeFileSync(vaultConfigPath(vault), JSON.stringify(cfg, null, 2) + "\n", "utf8");
1780
+ writeFileAtomic(vaultConfigPath(vault), JSON.stringify(cfg, null, 2) + "\n");
1745
1781
  }
1746
1782
 
1747
1783
  // Legacy exemption (ADR-007 Decision 6): a story is exempt from spec-first
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "projectstore-claude",
3
- "version": "0.29.4",
4
- "description": "Installs projectstore for Claude Code from npm: the core pinned and bundled, the harness fixed — npx projectstore-claude install --project \"$PWD\".",
3
+ "version": "0.30.1",
4
+ "description": "projectstore for Claude Code: the core pinned and bundled, the harness fixed. A release artifact; the way in is npx projectstore setup",
5
5
  "keywords": [
6
6
  "projectstore",
7
7
  "installer",
@@ -37,7 +37,7 @@
37
37
  "README.md"
38
38
  ],
39
39
  "dependencies": {
40
- "projectstore": "=0.29.4"
40
+ "projectstore": "=0.30.1"
41
41
  },
42
42
  "bundleDependencies": [
43
43
  "projectstore"