projectstore-claude 0.30.8 → 0.30.10
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.
- package/node_modules/projectstore/.claude-plugin/marketplace.json +1 -1
- package/node_modules/projectstore/.claude-plugin/plugin.json +1 -1
- package/node_modules/projectstore/.mcp.json +1 -5
- package/node_modules/projectstore/README.md +6 -5
- package/node_modules/projectstore/agents/archaeologist.md +1 -1
- package/node_modules/projectstore/agents/critic.md +26 -3
- package/node_modules/projectstore/agents/librarian.md +1 -1
- package/node_modules/projectstore/agents/planner.md +13 -1
- package/node_modules/projectstore/agents/reviewer.md +19 -2
- package/node_modules/projectstore/commands/adr.md +10 -0
- package/node_modules/projectstore/commands/bind.md +4 -3
- package/node_modules/projectstore/commands/concept.md +9 -0
- package/node_modules/projectstore/commands/doctor.md +17 -4
- package/node_modules/projectstore/commands/epic.md +10 -0
- package/node_modules/projectstore/commands/meeting.md +9 -0
- package/node_modules/projectstore/commands/research.md +9 -0
- package/node_modules/projectstore/commands/review.md +11 -7
- package/node_modules/projectstore/commands/runbook.md +9 -0
- package/node_modules/projectstore/commands/spec.md +10 -0
- package/node_modules/projectstore/commands/story.md +25 -1
- package/node_modules/projectstore/docs/contracts-and-tests.md +107 -0
- package/node_modules/projectstore/docs/extending.md +44 -5
- package/node_modules/projectstore/harnesses/claude-code.json +3 -3
- package/node_modules/projectstore/harnesses/codex.json +1 -1
- package/node_modules/projectstore/package.json +1 -1
- package/node_modules/projectstore/scaffold/guides/adr.md +42 -0
- package/node_modules/projectstore/scaffold/guides/concept.md +10 -0
- package/node_modules/projectstore/scaffold/guides/epic.md +36 -0
- package/node_modules/projectstore/scaffold/guides/meeting.md +11 -0
- package/node_modules/projectstore/scaffold/guides/research.md +16 -0
- package/node_modules/projectstore/scaffold/guides/runbook.md +12 -0
- package/node_modules/projectstore/scaffold/guides/spec.md +39 -0
- package/node_modules/projectstore/scaffold/guides/story.md +34 -0
- package/node_modules/projectstore/scripts/cli.mjs +55 -1
- package/node_modules/projectstore/scripts/configure-menu.mjs +2 -1
- package/node_modules/projectstore/scripts/configure.mjs +12 -2
- package/node_modules/projectstore/scripts/diff-refs.mjs +39 -0
- package/node_modules/projectstore/scripts/doctor.mjs +648 -33
- package/node_modules/projectstore/scripts/guides.mjs +217 -0
- package/node_modules/projectstore/scripts/harness.mjs +2 -0
- package/node_modules/projectstore/scripts/lib.mjs +163 -1
- package/node_modules/projectstore/scripts/mcp-server.mjs +11 -4
- package/node_modules/projectstore/scripts/mcp.mjs +30 -3
- package/node_modules/projectstore/scripts/read-verbs.mjs +59 -3
- package/node_modules/projectstore/scripts/scaffold.mjs +1 -1
- package/node_modules/projectstore/scripts/story-section.mjs +16 -1
- package/node_modules/projectstore/scripts/verbs.mjs +33 -1
- package/node_modules/projectstore/scripts/version-guard.mjs +5 -10
- package/node_modules/projectstore/skills/projectstore-peer-reviewer/SKILL.md +9 -3
- package/node_modules/projectstore/templates/de/spec.md.tmpl +9 -1
- package/node_modules/projectstore/templates/de/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/en/spec.md.tmpl +8 -1
- package/node_modules/projectstore/templates/en/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/es/spec.md.tmpl +9 -1
- package/node_modules/projectstore/templates/es/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/fr/spec.md.tmpl +9 -1
- package/node_modules/projectstore/templates/fr/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/ru/spec.md.tmpl +8 -1
- package/node_modules/projectstore/templates/ru/story.md.tmpl +1 -0
- package/node_modules/projectstore/templates/zh/spec.md.tmpl +8 -1
- package/node_modules/projectstore/templates/zh/story.md.tmpl +1 -0
- package/package.json +2 -2
- package/node_modules/projectstore/scaffold/checklists.json +0 -88
|
@@ -0,0 +1,217 @@
|
|
|
1
|
+
// projectstore — guides.mjs
|
|
2
|
+
//
|
|
3
|
+
// Authoring guides: one markdown file per artifact kind that the author reads
|
|
4
|
+
// before a draft and the critic checks after it. The package ships the
|
|
5
|
+
// defaults in scaffold/guides/<kind>.md; a vault may override one, whole, in
|
|
6
|
+
// <vault>/guides/<kind>.md. Resolved at every read, never cached and never
|
|
7
|
+
// copied into the project tree: an edit in Obsidian reaches the next reader.
|
|
8
|
+
// Normative: the ADR "One authoring guide per artifact kind, read by the
|
|
9
|
+
// author before the draft and by the critic after, overridable from the
|
|
10
|
+
// vault" (decisions 1-5) and SPEC-001 contract 12.
|
|
11
|
+
//
|
|
12
|
+
// A leaf: lib.mjs, harness.mjs and node built-ins only. The read side serves
|
|
13
|
+
// the `guide` verb and the MCP `guide` tool (read-verbs.mjs); eject is the one
|
|
14
|
+
// writer, reached only through the CLI's own handler (cli.mjs).
|
|
15
|
+
|
|
16
|
+
import { existsSync, readFileSync, readdirSync, statSync, mkdirSync } from "node:fs";
|
|
17
|
+
import { join } from "node:path";
|
|
18
|
+
import { pluginRoot, parseFrontmatter, guideItems, linesOutsideFences, createFileExclusive } from "./lib.mjs";
|
|
19
|
+
import { LAYOUT } from "./harness.mjs";
|
|
20
|
+
|
|
21
|
+
// The five sections, read by name; English in every vault language.
|
|
22
|
+
export const GUIDE_SECTIONS = Object.freeze(["Lens", "Must", "Common mistakes", "Do not write", "Length"]);
|
|
23
|
+
const LIST_SECTIONS = new Set(["Must", "Common mistakes", "Do not write"]);
|
|
24
|
+
// A kind, or <kind>.<variant>. Checked before any path is built.
|
|
25
|
+
export const GUIDE_NAME = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)?$/;
|
|
26
|
+
|
|
27
|
+
export const guidesDir = (vault) => join(vault, LAYOUT.guides);
|
|
28
|
+
export const packageGuidesDir = (root = pluginRoot()) => join(root, "scaffold", "guides");
|
|
29
|
+
|
|
30
|
+
const usageError = (msg) => Object.assign(new Error(msg), { code: "USAGE" });
|
|
31
|
+
|
|
32
|
+
export function checkGuideName(name) {
|
|
33
|
+
if (typeof name !== "string" || !GUIDE_NAME.test(name))
|
|
34
|
+
throw usageError(`guide takes a kind such as \`spec\` or \`story.test\`, not "${name ?? ""}"`);
|
|
35
|
+
return name;
|
|
36
|
+
}
|
|
37
|
+
|
|
38
|
+
// A file read that never throws: an iCloud placeholder, a directory named
|
|
39
|
+
// spec.md or a permission error is "unreadable", reported, not a crash.
|
|
40
|
+
function readText(p) {
|
|
41
|
+
try {
|
|
42
|
+
if (!statSync(p).isFile()) return { error: "not a file" };
|
|
43
|
+
return { text: readFileSync(p, "utf8").replace(/\r\n/g, "\n") };
|
|
44
|
+
} catch (e) {
|
|
45
|
+
return { error: e && e.code === "ENOENT" ? "absent" : `unreadable (${e && e.code ? e.code : "error"})` };
|
|
46
|
+
}
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
// The sections of a guide body: `## <name>` headings outside fences. A list
|
|
50
|
+
// section is its items; Lens and Length are their trimmed text. A section that
|
|
51
|
+
// is absent is null; a heading that is not one of the five is ignored.
|
|
52
|
+
function sectionsOf(body) {
|
|
53
|
+
const raw = {};
|
|
54
|
+
let cur = null;
|
|
55
|
+
for (const line of linesOutsideFences(body)) {
|
|
56
|
+
const h = line.match(/^##\s+(.+?)\s*$/);
|
|
57
|
+
if (h) {
|
|
58
|
+
cur = GUIDE_SECTIONS.includes(h[1]) ? h[1] : null;
|
|
59
|
+
if (cur) raw[cur] = [];
|
|
60
|
+
continue;
|
|
61
|
+
}
|
|
62
|
+
if (cur) raw[cur].push(line);
|
|
63
|
+
}
|
|
64
|
+
const sections = {};
|
|
65
|
+
for (const s of GUIDE_SECTIONS) {
|
|
66
|
+
if (!raw[s]) sections[s] = null;
|
|
67
|
+
else if (LIST_SECTIONS.has(s)) sections[s] = guideItems(raw[s]);
|
|
68
|
+
else sections[s] = raw[s].join("\n").trim() || null;
|
|
69
|
+
}
|
|
70
|
+
return { sections, raw };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
const intOrNull = (v) => {
|
|
74
|
+
const n = Number(v);
|
|
75
|
+
return v !== null && v !== undefined && v !== "" && Number.isInteger(n) ? n : null;
|
|
76
|
+
};
|
|
77
|
+
const boolOrNull = (v) => (v === "true" ? true : v === "false" ? false : null);
|
|
78
|
+
|
|
79
|
+
// The parse rule (decision 1): frontmatter whose guide_for equals the file's
|
|
80
|
+
// name, and a ## Must with at least one item.
|
|
81
|
+
export function parseGuide(text, name) {
|
|
82
|
+
if (!/^---\n/.test(text)) return { ok: false, reason: "no frontmatter" };
|
|
83
|
+
const { data, body } = parseFrontmatter(text);
|
|
84
|
+
if (data.guide_for !== name)
|
|
85
|
+
return { ok: false, reason: `guide_for is "${data.guide_for ?? ""}", not "${name}"`, fm: data };
|
|
86
|
+
const { sections, raw } = sectionsOf(body);
|
|
87
|
+
if (!sections.Must || sections.Must.length === 0) return { ok: false, reason: "## Must has no item", fm: data };
|
|
88
|
+
return { ok: true, fm: data, sections, raw, body };
|
|
89
|
+
}
|
|
90
|
+
|
|
91
|
+
// The candidates for a name, in decision 2's order: vault variant, package
|
|
92
|
+
// variant, vault base, package base. `source` keeps one side.
|
|
93
|
+
function candidates(name, { vault, root, source }) {
|
|
94
|
+
const base = name.includes(".") ? name.split(".")[0] : null;
|
|
95
|
+
const names = base ? [name, base] : [name];
|
|
96
|
+
const out = [];
|
|
97
|
+
for (const n of names) {
|
|
98
|
+
if (vault && source !== "package") out.push({ name: n, source: "vault", path: join(guidesDir(vault), `${n}.md`) });
|
|
99
|
+
if (source !== "vault") out.push({ name: n, source: "package", path: join(packageGuidesDir(root), `${n}.md`) });
|
|
100
|
+
}
|
|
101
|
+
return out;
|
|
102
|
+
}
|
|
103
|
+
|
|
104
|
+
// The resolved guide, or null when no candidate parses. Every vault file that
|
|
105
|
+
// exists and does not parse is a warning, and the next candidate is tried.
|
|
106
|
+
export function resolveGuide(name, { vault = null, root = pluginRoot(), source = null } = {}) {
|
|
107
|
+
checkGuideName(name);
|
|
108
|
+
const warnings = [];
|
|
109
|
+
for (const c of candidates(name, { vault, root, source })) {
|
|
110
|
+
const r = readText(c.path);
|
|
111
|
+
if (r.error === "absent") continue;
|
|
112
|
+
if (r.error) {
|
|
113
|
+
if (c.source === "vault") warnings.push(`skipped ${LAYOUT.guides}/${c.name}.md: ${r.error}`);
|
|
114
|
+
continue;
|
|
115
|
+
}
|
|
116
|
+
const g = parseGuide(r.text, c.name);
|
|
117
|
+
if (!g.ok) {
|
|
118
|
+
if (c.source === "vault") warnings.push(`skipped ${LAYOUT.guides}/${c.name}.md: ${g.reason}`);
|
|
119
|
+
continue;
|
|
120
|
+
}
|
|
121
|
+
return {
|
|
122
|
+
kind: name,
|
|
123
|
+
resolved: c.name,
|
|
124
|
+
source: c.source,
|
|
125
|
+
path: c.path,
|
|
126
|
+
guide_version: c.source === "package" ? intOrNull(g.fm.guide_version) : null,
|
|
127
|
+
based_on: intOrNull(g.fm.based_on),
|
|
128
|
+
default_review: boolOrNull(g.fm.default_review),
|
|
129
|
+
sections: g.sections,
|
|
130
|
+
warnings,
|
|
131
|
+
text: r.text,
|
|
132
|
+
raw: g.raw,
|
|
133
|
+
};
|
|
134
|
+
}
|
|
135
|
+
return { kind: name, resolved: null, warnings };
|
|
136
|
+
}
|
|
137
|
+
|
|
138
|
+
// The names that have a guide on either side (for the "no guide" message).
|
|
139
|
+
export function guideKinds({ vault = null, root = pluginRoot() } = {}) {
|
|
140
|
+
const names = new Set();
|
|
141
|
+
const scan = (dir, side) => {
|
|
142
|
+
let list;
|
|
143
|
+
try {
|
|
144
|
+
list = readdirSync(dir);
|
|
145
|
+
} catch {
|
|
146
|
+
return;
|
|
147
|
+
}
|
|
148
|
+
for (const f of list) {
|
|
149
|
+
if (!f.endsWith(".md") || f.startsWith(".")) continue;
|
|
150
|
+
const n = f.slice(0, -3);
|
|
151
|
+
if (!GUIDE_NAME.test(n)) continue;
|
|
152
|
+
const r = readText(join(dir, f));
|
|
153
|
+
if (side === "vault" && (r.error || !parseGuide(r.text, n).ok)) continue;
|
|
154
|
+
names.add(n);
|
|
155
|
+
}
|
|
156
|
+
};
|
|
157
|
+
scan(packageGuidesDir(root), "package");
|
|
158
|
+
if (vault) scan(guidesDir(vault), "vault");
|
|
159
|
+
return [...names].sort();
|
|
160
|
+
}
|
|
161
|
+
|
|
162
|
+
// The JSON result of the read (decision 3, plus default_review at the plan
|
|
163
|
+
// gate): the internals (text, raw) stay out.
|
|
164
|
+
export function guideResult(g) {
|
|
165
|
+
return {
|
|
166
|
+
kind: g.kind,
|
|
167
|
+
source: g.source,
|
|
168
|
+
path: g.path,
|
|
169
|
+
guide_version: g.guide_version,
|
|
170
|
+
based_on: g.based_on,
|
|
171
|
+
default_review: g.default_review,
|
|
172
|
+
sections: g.sections,
|
|
173
|
+
warnings: g.warnings,
|
|
174
|
+
};
|
|
175
|
+
}
|
|
176
|
+
|
|
177
|
+
// The text form: a header line, then the guide's body or one raw section.
|
|
178
|
+
export function renderGuide(g, section = null) {
|
|
179
|
+
const head = `guide ${g.resolved} · source ${g.source} · ${g.path}\n`;
|
|
180
|
+
if (!section) return head + "\n" + g.text.replace(/\n*$/, "\n");
|
|
181
|
+
if (!g.raw[section]) return head + `\n(no ## ${section} in this guide)\n`;
|
|
182
|
+
return head + `\n## ${section}\n` + g.raw[section].join("\n").replace(/\n*$/, "\n");
|
|
183
|
+
}
|
|
184
|
+
|
|
185
|
+
// ─── eject: the one writer ─────────────────────────────────────────────
|
|
186
|
+
//
|
|
187
|
+
// Copies a package guide into <vault>/guides/<name>.md with `based_on` set to
|
|
188
|
+
// its guide_version, create-only (decision 5). A plan first, so the preview
|
|
189
|
+
// and the write are the same thing.
|
|
190
|
+
|
|
191
|
+
export function planEject(name, { vault, root = pluginRoot() } = {}) {
|
|
192
|
+
checkGuideName(name);
|
|
193
|
+
const src = join(packageGuidesDir(root), `${name}.md`);
|
|
194
|
+
const target = vault ? join(guidesDir(vault), `${name}.md`) : null;
|
|
195
|
+
const refuse = (why) => ({ ok: false, name, target, refusal: why });
|
|
196
|
+
if (!vault || !existsSync(vault) || !statSync(vault).isDirectory())
|
|
197
|
+
return refuse("the binding names no vault directory to write the guide into");
|
|
198
|
+
const r = readText(src);
|
|
199
|
+
if (r.error) return refuse(`the package has no guide named "${name}" (eject copies a package guide)`);
|
|
200
|
+
const dir = guidesDir(vault);
|
|
201
|
+
if (existsSync(dir) && !statSync(dir).isDirectory())
|
|
202
|
+
return refuse(`${LAYOUT.guides} exists in the vault and is not a folder`);
|
|
203
|
+
if (existsSync(target)) return refuse(`${LAYOUT.guides}/${name}.md already exists; eject never overwrites it`);
|
|
204
|
+
const version = intOrNull(parseFrontmatter(r.text).data.guide_version);
|
|
205
|
+
const content = r.text.replace(/^(guide_version:.*)$/m, `$1\nbased_on: ${version}`);
|
|
206
|
+
return { ok: true, name, target, content, based_on: version };
|
|
207
|
+
}
|
|
208
|
+
|
|
209
|
+
export function applyEject(plan) {
|
|
210
|
+
if (!plan.ok) return { written: false };
|
|
211
|
+
mkdirSync(join(plan.target, ".."), { recursive: true });
|
|
212
|
+
// Create-only for real (lib.mjs's exclusive create): a file made meanwhile
|
|
213
|
+
// is never replaced.
|
|
214
|
+
if (!createFileExclusive(plan.target, plan.content))
|
|
215
|
+
return { written: false, refusal: `${plan.target} appeared meanwhile` };
|
|
216
|
+
return { written: true };
|
|
217
|
+
}
|
|
@@ -746,6 +746,8 @@ export const LAYOUT = Object.freeze({
|
|
|
746
746
|
// The vault's own, unrelated files under the same name (ADR-007 decision 4; sessions).
|
|
747
747
|
vaultConfig: ".projectstore.json",
|
|
748
748
|
vaultSessions: "sessions",
|
|
749
|
+
// <vault>/guides/: per-kind authoring guide overrides (the authoring-guides ADR, decision 2).
|
|
750
|
+
guides: "guides",
|
|
749
751
|
});
|
|
750
752
|
// The header both the legacy and the new state .gitignore carry — how
|
|
751
753
|
// uninstall recognises a state directory as ours (layout spec, contract 6).
|
|
@@ -14,6 +14,7 @@ import {
|
|
|
14
14
|
mkdirSync,
|
|
15
15
|
utimesSync,
|
|
16
16
|
unlinkSync,
|
|
17
|
+
linkSync,
|
|
17
18
|
renameSync,
|
|
18
19
|
rmSync,
|
|
19
20
|
realpathSync,
|
|
@@ -506,6 +507,26 @@ export function writeFileAtomic(p, content, { sweep = true } = {}) {
|
|
|
506
507
|
}
|
|
507
508
|
}
|
|
508
509
|
|
|
510
|
+
// Create a file only if it is absent, atomically: the content goes to the
|
|
511
|
+
// same dot-prefixed temp writeFileAtomic uses, and a hard link puts it at
|
|
512
|
+
// the target, which fails EEXIST when the target exists — a file made
|
|
513
|
+
// meanwhile is never replaced. Returns false on EEXIST; other errors throw.
|
|
514
|
+
export function createFileExclusive(p, content) {
|
|
515
|
+
const tmp = join(dirname(p), `.${basename(p)}.${process.pid}.tmp`);
|
|
516
|
+
writeFileSync(tmp, content, "utf8");
|
|
517
|
+
try {
|
|
518
|
+
linkSync(tmp, p);
|
|
519
|
+
return true;
|
|
520
|
+
} catch (e) {
|
|
521
|
+
if (e && e.code === "EEXIST") return false;
|
|
522
|
+
throw e;
|
|
523
|
+
} finally {
|
|
524
|
+
try {
|
|
525
|
+
unlinkSync(tmp);
|
|
526
|
+
} catch {}
|
|
527
|
+
}
|
|
528
|
+
}
|
|
529
|
+
|
|
509
530
|
// Write metadata into a descriptor the caller acquired with O_EXCL. The
|
|
510
531
|
// exclusive create is the lock; keeping this tiny write in lib preserves the
|
|
511
532
|
// repository's single write boundary without weakening the atomic lock race.
|
|
@@ -896,6 +917,17 @@ export function envFlag(env, name) {
|
|
|
896
917
|
return v !== undefined && v !== null && v !== "" && !["0", "false"].includes(String(v).toLowerCase());
|
|
897
918
|
}
|
|
898
919
|
|
|
920
|
+
// The one package in `npm pack --json`'s answer: an array of one entry up to
|
|
921
|
+
// npm 11, an object keyed by the package's name from npm 12. Here, not in
|
|
922
|
+
// scripts/version-guard.mjs: packaging/shells.mjs reads it too, and an import
|
|
923
|
+
// of the guard from there is a cycle (the guard loads shells.mjs while its own
|
|
924
|
+
// top-level await is pending, and Node exits 13).
|
|
925
|
+
export function packEntry(answer) {
|
|
926
|
+
const [pkg] = Array.isArray(answer) ? answer : Object.values(answer ?? {});
|
|
927
|
+
if (!pkg || !Array.isArray(pkg.files)) throw new Error("no package entry with a file list");
|
|
928
|
+
return pkg;
|
|
929
|
+
}
|
|
930
|
+
|
|
899
931
|
// The files a package ships, as the release gate defines them — package.json
|
|
900
932
|
// files[] plus npm's always-included package.json, README and LICENSE — copied
|
|
901
933
|
// from `from` to `to`. Never node_modules, never a symlink (a symlink is a
|
|
@@ -1835,6 +1867,24 @@ export function storiesAttributionRe() {
|
|
|
1835
1867
|
return new RegExp(`[—–-]\\s*${keywordRe("stories").source}\\s*[::]\\s*(.+)$`, "i");
|
|
1836
1868
|
}
|
|
1837
1869
|
|
|
1870
|
+
// A test cites a spec contract with `[<key>#<n>]` (the spec policy ADR,
|
|
1871
|
+
// Decisions 4 and 8): <key> is the spec's id or alias, <n> the contract
|
|
1872
|
+
// number in ASCII — `4'` for 4′, `4''` for 4″, `4/1''` for a step nested
|
|
1873
|
+
// under contract 4. The closing bracket ends the token, so #4 never matches
|
|
1874
|
+
// #4' or #40. The lookarounds drop a Markdown link `[x#1](…)` and a
|
|
1875
|
+
// wikilink `[[x#1]]`. These tokens are machine tokens: English in every
|
|
1876
|
+
// locale, never in the heading registry.
|
|
1877
|
+
export const CITATION_EXAMPLE_KEY = "example";
|
|
1878
|
+
export function citationTokenRe() {
|
|
1879
|
+
return /(?<!\[)\[([A-Za-z0-9][A-Za-z0-9._-]*)#(\d+'*(?:\/\d+'*)?)\](?![(\]])/g;
|
|
1880
|
+
}
|
|
1881
|
+
// A loose ERE for git's side of the scan; citationTokenRe decides.
|
|
1882
|
+
export const CITATION_PREFILTER = "\\[[A-Za-z0-9][A-Za-z0-9._-]*#[0-9]";
|
|
1883
|
+
// A contract number as a spec writes it (`4′`, `1″`), in the token's ASCII.
|
|
1884
|
+
export function contractNumberAscii(n) {
|
|
1885
|
+
return String(n).replace(/″/g, "''").replace(/′/g, "'");
|
|
1886
|
+
}
|
|
1887
|
+
|
|
1838
1888
|
// The body footer (`*Last updated: 2026-01-01*`) is content rather than a heading,
|
|
1839
1889
|
// but the lifecycle gates keep it in step with frontmatter `updated:`. Matching
|
|
1840
1890
|
// accepts every registered language; the rewrite preserves the file's OWN prefix
|
|
@@ -1890,7 +1940,8 @@ export function listOf(fm, key) {
|
|
|
1890
1940
|
// would defeat the whole point. Keys: spec_policy ("required"|"optional"),
|
|
1891
1941
|
// lifecycle_gates ("on"|"off"), spec_policy_since (ISO-8601, stamped whenever
|
|
1892
1942
|
// spec_policy becomes "required" from anything else; kept otherwise — the
|
|
1893
|
-
// configure spec, contract 7)
|
|
1943
|
+
// configure spec, contract 7), gates_since (stamped when lifecycle_gates
|
|
1944
|
+
// turns on; the configure spec, contract 7 as amended 2026-11-08).
|
|
1894
1945
|
export function vaultConfigPath(vault) {
|
|
1895
1946
|
return join(vault, LAYOUT.vaultConfig);
|
|
1896
1947
|
}
|
|
@@ -1931,9 +1982,113 @@ export function nextVaultConfig(before, patch, now = new Date().toISOString()) {
|
|
|
1931
1982
|
const prev = before.spec_policy_since;
|
|
1932
1983
|
next.spec_policy_since = prev && String(prev) > now ? prev : now;
|
|
1933
1984
|
}
|
|
1985
|
+
// gates_since (the spec policy ADR, Decision 18a): the date the lifecycle
|
|
1986
|
+
// checks start counting from under any spec policy. Stamped when the gates
|
|
1987
|
+
// turn on, and when they are set on again with no stamp yet, so a vault
|
|
1988
|
+
// already on can get its date. Same never-earlier rule as above.
|
|
1989
|
+
if (patch.lifecycle_gates === "on" && (before.lifecycle_gates !== "on" || !before.gates_since)) {
|
|
1990
|
+
const prev = before.gates_since;
|
|
1991
|
+
next.gates_since = prev && String(prev) > now ? prev : now;
|
|
1992
|
+
}
|
|
1934
1993
|
return next;
|
|
1935
1994
|
}
|
|
1936
1995
|
|
|
1996
|
+
// The date the legacy predicate reads: spec_policy_since, else gates_since.
|
|
1997
|
+
// Spec coverage itself reads only spec_policy_since.
|
|
1998
|
+
export function legacySince(vaultCfg) {
|
|
1999
|
+
return (vaultCfg && (vaultCfg.spec_policy_since || vaultCfg.gates_since)) || null;
|
|
2000
|
+
}
|
|
2001
|
+
|
|
2002
|
+
export function lifecycleGatesOn(vaultCfg) {
|
|
2003
|
+
return ["on", "true"].includes(String((vaultCfg && vaultCfg.lifecycle_gates) || "off").toLowerCase());
|
|
2004
|
+
}
|
|
2005
|
+
|
|
2006
|
+
// A story's declared opt-out from a spec (Decision 13). `declared` when the
|
|
2007
|
+
// key is present at all; `reason` is its text, trimmed, "" when empty.
|
|
2008
|
+
export function noSpecOf(fm) {
|
|
2009
|
+
if (!fm || fm.no_spec == null || fm.no_spec === "null") {
|
|
2010
|
+
return { declared: false, reason: "" };
|
|
2011
|
+
}
|
|
2012
|
+
return { declared: true, reason: String(fm.no_spec ?? "").trim() };
|
|
2013
|
+
}
|
|
2014
|
+
|
|
2015
|
+
// `doctor --policy required[@<date>]` (Decision 18): the overlay a dry run
|
|
2016
|
+
// evaluates the vault with. A bare date means UTC midnight; none means now.
|
|
2017
|
+
export function parseDryRunPolicy(value, now = new Date().toISOString()) {
|
|
2018
|
+
const m = String(value || "").match(/^required(?:@(.+))?$/);
|
|
2019
|
+
if (!m) return { error: `--policy takes required or required@<date>, not "${value}"` };
|
|
2020
|
+
if (!m[1]) return { policy: { spec_policy: "required", spec_policy_since: now } };
|
|
2021
|
+
// ISO only: a date (UTC midnight), or a full timestamp with its zone.
|
|
2022
|
+
const iso = /^\d{4}-\d{2}-\d{2}(T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2}))?$/;
|
|
2023
|
+
if (!iso.test(m[1])) return { error: `--policy: "${m[1]}" is not an ISO date (YYYY-MM-DD)` };
|
|
2024
|
+
const d = /^\d{4}-\d{2}-\d{2}$/.test(m[1]) ? `${m[1]}T00:00:00.000Z` : m[1];
|
|
2025
|
+
const t = Date.parse(d);
|
|
2026
|
+
if (!Number.isFinite(t)) return { error: `--policy: "${m[1]}" is not a date` };
|
|
2027
|
+
return { policy: { spec_policy: "required", spec_policy_since: new Date(t).toISOString() } };
|
|
2028
|
+
}
|
|
2029
|
+
|
|
2030
|
+
// A checklist item read together with its wrapped continuation lines: the
|
|
2031
|
+
// lines after `- [x] …` indented deeper than its dash, nested bullets
|
|
2032
|
+
// included (a criterion that lists cases ends with the evidence on its last
|
|
2033
|
+
// bullet). `— evidence:` on a wrapped line belongs to the item.
|
|
2034
|
+
export function checklistItems(lines) {
|
|
2035
|
+
const items = [];
|
|
2036
|
+
let cur = null;
|
|
2037
|
+
for (const line of lines) {
|
|
2038
|
+
const m = line.match(/^(\s*)-\s*\[( |x|X)\]\s*(.*)$/);
|
|
2039
|
+
if (m) {
|
|
2040
|
+
cur = { checked: m[2].toLowerCase() === "x", text: m[3], indent: m[1].length };
|
|
2041
|
+
items.push(cur);
|
|
2042
|
+
continue;
|
|
2043
|
+
}
|
|
2044
|
+
if (cur && /^\s+\S/.test(line) && line.match(/^\s*/)[0].length > cur.indent) {
|
|
2045
|
+
cur.text += " " + line.trim();
|
|
2046
|
+
continue;
|
|
2047
|
+
}
|
|
2048
|
+
cur = null;
|
|
2049
|
+
}
|
|
2050
|
+
return items;
|
|
2051
|
+
}
|
|
2052
|
+
|
|
2053
|
+
// A guide's rule items (the authoring-guides ADR, decision 1): plain bullets,
|
|
2054
|
+
// not checkboxes. An item is its bullet line plus the lines indented deeper
|
|
2055
|
+
// than its dash (wrapped text and nested bullets); a bullet at the same or a
|
|
2056
|
+
// lesser depth starts the next item; a blank or an unindented line ends it.
|
|
2057
|
+
// The caller drops fenced lines first (linesOutsideFences).
|
|
2058
|
+
export function guideItems(lines) {
|
|
2059
|
+
const items = [];
|
|
2060
|
+
let cur = null;
|
|
2061
|
+
for (const line of lines) {
|
|
2062
|
+
const m = line.match(/^(\s*)-\s+(\S.*)$/);
|
|
2063
|
+
if (m && (!cur || m[1].length <= cur.indent)) {
|
|
2064
|
+
cur = { text: m[2].trim(), indent: m[1].length };
|
|
2065
|
+
items.push(cur);
|
|
2066
|
+
continue;
|
|
2067
|
+
}
|
|
2068
|
+
if (cur && /^\s+\S/.test(line) && line.match(/^\s*/)[0].length > cur.indent) {
|
|
2069
|
+
cur.text += " " + line.trim();
|
|
2070
|
+
continue;
|
|
2071
|
+
}
|
|
2072
|
+
cur = null;
|
|
2073
|
+
}
|
|
2074
|
+
return items.map((i) => i.text);
|
|
2075
|
+
}
|
|
2076
|
+
|
|
2077
|
+
// RAW lines outside fenced blocks — for checks that must both MATCH (fence-
|
|
2078
|
+
// immune) and REPORT the line verbatim (backticks intact in the message).
|
|
2079
|
+
export function linesOutsideFences(s) {
|
|
2080
|
+
const out = [];
|
|
2081
|
+
let fenced = false;
|
|
2082
|
+
for (const line of s.split("\n")) {
|
|
2083
|
+
if (/^\s*```/.test(line)) {
|
|
2084
|
+
fenced = !fenced;
|
|
2085
|
+
continue;
|
|
2086
|
+
}
|
|
2087
|
+
if (!fenced) out.push(line);
|
|
2088
|
+
}
|
|
2089
|
+
return out;
|
|
2090
|
+
}
|
|
2091
|
+
|
|
1937
2092
|
// The one writer of the vault config: atomic, and every key it was not asked
|
|
1938
2093
|
// to change is kept as it was.
|
|
1939
2094
|
export function writeVaultConfig(vault, cfg) {
|
|
@@ -3576,6 +3731,13 @@ export function isSourcePath(absPath, projectDir, vaultPath) {
|
|
|
3576
3731
|
return !(vaultPath && vaultLocation(absPath, vaultPath));
|
|
3577
3732
|
}
|
|
3578
3733
|
|
|
3734
|
+
// A test file, for the opt-out's size check only (Decision 15): tests do not
|
|
3735
|
+
// weigh. Not part of SOURCE_IGNORE — the entry-rule hook and diff-refs count
|
|
3736
|
+
// a test edit as source.
|
|
3737
|
+
export function isTestPath(rel) {
|
|
3738
|
+
return /(^|\/)(test|tests|__tests__)(\/|$)/.test(rel) || /\.(test|spec)\.[^/]+$/.test(rel);
|
|
3739
|
+
}
|
|
3740
|
+
|
|
3579
3741
|
export function scoreDir(projectDir, sessionId) {
|
|
3580
3742
|
return join(stateDir(projectDir), `${sessionId}.paths`);
|
|
3581
3743
|
}
|
|
@@ -2,9 +2,15 @@
|
|
|
2
2
|
// projectstore — mcp-server.mjs
|
|
3
3
|
//
|
|
4
4
|
// The MCP server's entry: what the plugin's .mcp.json runs, as `node
|
|
5
|
-
// <plugin root>/scripts/mcp-server.mjs
|
|
6
|
-
//
|
|
7
|
-
//
|
|
5
|
+
// <plugin root>/scripts/mcp-server.mjs` with no other argument. The project
|
|
6
|
+
// comes from the directory the host declares in the server's environment
|
|
7
|
+
// (projectRootDeclared), since 0.30.9: Anthropic's plugin portal blocks any
|
|
8
|
+
// variable but the plugin root in a server's command (PS-DIRECTORY: "The MCP
|
|
9
|
+
// server's entry names no variable but ${CLAUDE_PLUGIN_ROOT}…"). That
|
|
10
|
+
// directory comes before PROJECTSTORE_PROJECT_DIR, as 0.30.8's --project
|
|
11
|
+
// did; --project still wins, for a test or a start by hand. It starts the
|
|
12
|
+
// server through mcp.mjs's serveSupplied, the path the CLI's `mcp` verb
|
|
13
|
+
// takes too, so the two entries serve alike.
|
|
8
14
|
// It lives under scripts/, never bin/: a file in the plugin's top-level bin/
|
|
9
15
|
// is on the host's Bash PATH, and it imports nothing from cli.mjs, so its
|
|
10
16
|
// imports reach no install verb (the PS-DIRECTORY story "The MCP server's
|
|
@@ -17,6 +23,7 @@
|
|
|
17
23
|
|
|
18
24
|
import { parseArgs } from "node:util";
|
|
19
25
|
import { serveSupplied } from "./mcp.mjs";
|
|
26
|
+
import { projectRootDeclared } from "./harness.mjs";
|
|
20
27
|
|
|
21
28
|
let values;
|
|
22
29
|
try {
|
|
@@ -30,4 +37,4 @@ try {
|
|
|
30
37
|
process.stderr.write(`mcp-server: ${e.message} — it takes --project <dir> alone\n`);
|
|
31
38
|
process.exitCode = 2;
|
|
32
39
|
}
|
|
33
|
-
if (values) process.exitCode = await serveSupplied({ project: values.project ??
|
|
40
|
+
if (values) process.exitCode = await serveSupplied({ project: values.project ?? projectRootDeclared(process.env) });
|
|
@@ -62,7 +62,7 @@ export const isErrorExit = (code) => code !== 0 && code !== 1;
|
|
|
62
62
|
export const PROTOCOL_VERSIONS = Object.freeze(["2025-11-25", "2025-06-18"]);
|
|
63
63
|
export { DOCTOR_TIMEOUT_MS };
|
|
64
64
|
export const SERVER_NAME = "projectstore";
|
|
65
|
-
export const TOOL_CEILING = 8
|
|
65
|
+
export const TOOL_CEILING = 9; // amended by the authoring-guides ADR, decision 8
|
|
66
66
|
export const TOOL_LIST_TOKEN_CEILING = 3000; // ADR decision 7, chars/4
|
|
67
67
|
export const RESOURCE_SCHEME = "projectstore://";
|
|
68
68
|
|
|
@@ -205,8 +205,31 @@ export const TOOLS = Object.freeze({
|
|
|
205
205
|
inputSchema: schema({
|
|
206
206
|
install: bool("only the install section"),
|
|
207
207
|
vault: bool("only the vault section"),
|
|
208
|
+
policy: str("a dry run of the vault section: required, or required@<date>; writes nothing"),
|
|
209
|
+
}),
|
|
210
|
+
argv: (a) => ({
|
|
211
|
+
opts: [...flag("install", a.install), ...flag("vault", a.vault), ...opt("policy", a.policy)],
|
|
212
|
+
positionals: [],
|
|
213
|
+
}),
|
|
214
|
+
},
|
|
215
|
+
// The ninth tool (the authoring-guides ADR, decision 8, amending the MCP
|
|
216
|
+
// surface ADR's decision 7): the read half of `guide`; eject is not served.
|
|
217
|
+
guide: {
|
|
218
|
+
verb: "guide",
|
|
219
|
+
description:
|
|
220
|
+
"An artifact kind's authoring guide (Lens, Must, Common mistakes, Do not write, Length). Call it before drafting an artifact of that kind and before reviewing one; the vault's override wins over the package default.",
|
|
221
|
+
inputSchema: schema(
|
|
222
|
+
{
|
|
223
|
+
kind: str("a kind (adr, spec, epic, story, …) or <kind>.<variant>, such as story.test"),
|
|
224
|
+
section: str("one section: Lens, Must, Common mistakes, Do not write or Length"),
|
|
225
|
+
source: { type: "string", enum: ["vault", "package"], description: "read one side only" },
|
|
226
|
+
},
|
|
227
|
+
["kind"],
|
|
228
|
+
),
|
|
229
|
+
argv: (a) => ({
|
|
230
|
+
opts: [...opt("section", a.section), ...opt("source", a.source)],
|
|
231
|
+
positionals: [a.kind],
|
|
208
232
|
}),
|
|
209
|
-
argv: (a) => ({ opts: [...flag("install", a.install), ...flag("vault", a.vault)], positionals: [] }),
|
|
210
233
|
},
|
|
211
234
|
});
|
|
212
235
|
|
|
@@ -332,7 +355,11 @@ export function createServer({
|
|
|
332
355
|
).error,
|
|
333
356
|
};
|
|
334
357
|
// An option value that starts with "-" would read as a flag to the CLI's parser; a positional is safe behind "--".
|
|
335
|
-
if (
|
|
358
|
+
if (
|
|
359
|
+
typeof v === "string" &&
|
|
360
|
+
v.startsWith("-") &&
|
|
361
|
+
["section", "status", "direction", "selector", "source", "kind"].includes(k)
|
|
362
|
+
)
|
|
336
363
|
return { error: rpcError(null, E_INVALID_PARAMS, `${name}: "${k}" may not start with "-"`).error };
|
|
337
364
|
}
|
|
338
365
|
// The verb table decides who runs unbound: status and doctor do (doctor
|
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
// projectstore — read-verbs.mjs
|
|
2
2
|
//
|
|
3
3
|
// The read-verb runner: the handlers of the verbs that write nothing (status,
|
|
4
|
-
// orientation, search, show, graph, codemap, doctor and version
|
|
4
|
+
// orientation, search, show, graph, codemap, doctor and version, and the read
|
|
5
|
+
// half of guide, whose eject only the CLI serves), and
|
|
5
6
|
// runRead(), which dispatches through the one verb table (scripts/verbs.mjs)
|
|
6
7
|
// with these handlers alone. The CLI's run() hands dispatch() these and its
|
|
7
8
|
// write handlers; the MCP server (scripts/mcp.mjs) runs runRead() and imports
|
|
@@ -21,8 +22,10 @@ import { resolve, dirname } from "node:path";
|
|
|
21
22
|
import { fileURLToPath } from "node:url";
|
|
22
23
|
import * as term from "./term.mjs";
|
|
23
24
|
import { doctorFallbackText } from "./lib.mjs";
|
|
24
|
-
import { READ_OPERATIONS, LINEAGE_KINDS } from "./query.mjs";
|
|
25
|
-
import {
|
|
25
|
+
import { READ_OPERATIONS, LINEAGE_KINDS, oneOf } from "./query.mjs";
|
|
26
|
+
import { normaliseVaultPath } from "./binding.mjs";
|
|
27
|
+
import { GUIDE_SECTIONS, checkGuideName, resolveGuide, guideKinds, guideResult, renderGuide } from "./guides.mjs";
|
|
28
|
+
import { dispatch, envelope, packageVersion, usageFail, ownEnv, runVersion, PACKAGE_ROOT } from "./verbs.mjs";
|
|
26
29
|
|
|
27
30
|
const HERE = dirname(fileURLToPath(import.meta.url));
|
|
28
31
|
export const DOCTOR_SCRIPT = resolve(HERE, "doctor.mjs");
|
|
@@ -111,6 +114,57 @@ async function runCodemap(ctx) {
|
|
|
111
114
|
}
|
|
112
115
|
}
|
|
113
116
|
|
|
117
|
+
// ─── guide ─────────────────────────────────────────────────────────────
|
|
118
|
+
//
|
|
119
|
+
// The read half of the guide row (the authoring-guides ADR, decision 3): the
|
|
120
|
+
// resolved guide, vault override first. `eject` writes, so this runner, which
|
|
121
|
+
// the MCP server runs, refuses it; the CLI serves it with its own handler.
|
|
122
|
+
|
|
123
|
+
// The vault the binding names, as scaffold and eject read it; null when the
|
|
124
|
+
// project is unbound or names no usable path (the package side still answers).
|
|
125
|
+
export function guideVault(cfg, project) {
|
|
126
|
+
const norm = cfg && cfg.vault_path ? normaliseVaultPath(cfg.vault_path, project) : null;
|
|
127
|
+
return typeof norm === "string" ? norm : null;
|
|
128
|
+
}
|
|
129
|
+
|
|
130
|
+
async function runGuide(ctx) {
|
|
131
|
+
const { row, values, positionals, cfg, project, stdout, stderr } = ctx;
|
|
132
|
+
const usage = (m) => usageFail(Object.assign(new Error(m), { code: "USAGE" }), { verb: row.verb, ...ctx });
|
|
133
|
+
const vault = guideVault(cfg, project);
|
|
134
|
+
if (positionals[0] === "eject")
|
|
135
|
+
return usage("guide eject writes; the read-only runner does not serve it. Run it from a terminal in the project");
|
|
136
|
+
if (values.write) return usage("--write belongs to guide eject");
|
|
137
|
+
const name = positionals[0];
|
|
138
|
+
if (!name) return usage(`guide takes a kind: ${guideKinds({ vault, root: PACKAGE_ROOT }).join(", ")}`);
|
|
139
|
+
try {
|
|
140
|
+
checkGuideName(name);
|
|
141
|
+
const source = oneOf("source", values.source, ["vault", "package"], null);
|
|
142
|
+
const section = values.section ?? null;
|
|
143
|
+
if (section !== null && !GUIDE_SECTIONS.includes(section))
|
|
144
|
+
throw Object.assign(new Error(`--section takes one of: ${GUIDE_SECTIONS.join(", ")}`), { code: "USAGE" });
|
|
145
|
+
const g = resolveGuide(name, { vault, root: PACKAGE_ROOT, source });
|
|
146
|
+
if (!g.resolved) {
|
|
147
|
+
const why = `no guide for "${name}"${source ? ` on the ${source} side` : ""}. Kinds with a guide: ${guideKinds({ vault, root: PACKAGE_ROOT }).join(", ")}`;
|
|
148
|
+
if (values.json)
|
|
149
|
+
stdout.write(
|
|
150
|
+
JSON.stringify(envelope(row.verb, project, false, { error: why, warnings: g.warnings }), null, 2) + "\n",
|
|
151
|
+
);
|
|
152
|
+
else stderr.write(why + "\n");
|
|
153
|
+
return 1;
|
|
154
|
+
}
|
|
155
|
+
for (const w of g.warnings) if (!values.json) stderr.write(`guide: ${w}\n`);
|
|
156
|
+
if (values.json) {
|
|
157
|
+
const result = guideResult(g);
|
|
158
|
+
if (section) result.sections = { [section]: g.sections[section] };
|
|
159
|
+
stdout.write(JSON.stringify(envelope(row.verb, project, true, result), null, 2) + "\n");
|
|
160
|
+
} else stdout.write(renderGuide(g, section));
|
|
161
|
+
return 0;
|
|
162
|
+
} catch (e) {
|
|
163
|
+
if (e && e.code === "USAGE") return usageFail(e, { verb: row.verb, ...ctx });
|
|
164
|
+
throw e;
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
|
|
114
168
|
// ─── doctor ────────────────────────────────────────────────────────────
|
|
115
169
|
//
|
|
116
170
|
// Spawned, never imported (MCP ADR decision 2): doctor's main writes to
|
|
@@ -127,6 +181,7 @@ export const doctorArgs = (values) => [
|
|
|
127
181
|
DOCTOR_SCRIPT,
|
|
128
182
|
"--json",
|
|
129
183
|
...[values.install && "--install", values.vault && "--vault"].filter(Boolean),
|
|
184
|
+
...(values.policy ? ["--policy", String(values.policy)] : []),
|
|
130
185
|
];
|
|
131
186
|
|
|
132
187
|
// Where the child runs: in the project when it exists — a project that does
|
|
@@ -265,6 +320,7 @@ export const READ_HANDLERS = Object.freeze({
|
|
|
265
320
|
show: readVerb("show"),
|
|
266
321
|
graph: runGraph,
|
|
267
322
|
codemap: runCodemap,
|
|
323
|
+
guide: runGuide,
|
|
268
324
|
doctor: runDoctor,
|
|
269
325
|
version: runVersion,
|
|
270
326
|
});
|
|
@@ -42,7 +42,7 @@ import { packageCommand } from "./harness.mjs";
|
|
|
42
42
|
|
|
43
43
|
const README = "README.md";
|
|
44
44
|
|
|
45
|
-
const kindsOf = (layout) => [...new Set((layout.folders || []).map((f) => f.kind))];
|
|
45
|
+
export const kindsOf = (layout) => [...new Set((layout.folders || []).map((f) => f.kind))];
|
|
46
46
|
const usable = (v) => typeof v === "string" && v.trim() !== "";
|
|
47
47
|
const pathKind = (p) => {
|
|
48
48
|
try {
|