repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

feat(the-system): cut governance over to markdown bundles

42997c0d2df8e3fb480d86ce1973adfd002c1037

Oliver Jan Krylow <oliver@bugabinga.net> ·

unsigned

Browse filesCompare with HEAD

Changed files (10)

extensions/the-system/__tests__/doctor.test.ts

Modified
7 7 readFileSync,
8 8 rmSync,
9 9 statSync,
10 + symlinkSync,
10 11 writeFileSync,
11 12 } from "node:fs";
12 13 import { tmpdir } from "node:os";
26 27 mkdirSync(path.dirname(target), { recursive: true });
27 28 writeFileSync(target, content, "utf8");
29 -const metadata = (value: object) =>
30 - `<script type="application/json" id="system-meta">${JSON.stringify(value)}</script>`;
31 -const html = (meta: object, body = "<p>contract</p>") => `<!doctype html>
32 -<html lang="en">
33 -<head>
34 -<meta charset="utf-8">
35 -<meta name="viewport" content="width=device-width, initial-scale=1">
36 -<title>Fixture</title>
37 -<link rel="stylesheet" href="../system.css">
38 -${metadata(meta)}
39 -</head>
40 -<body><header><h1>Fixture</h1></header><main><section>${body}</section></main></body>
41 -</html>`;
30 +const markdown = (id: string, type = "spec", extra = "") =>
31 + `---\nid: ${id}\ntype: ${type}${extra}\n---\n\n# Contract\n`;
42 32 const validSystem = (root: string) => {
43 33 for (const directory of ["specs", "roadmaps", "plans", "issues", "research"])
44 34 mkdirSync(path.join(root, ".system", directory), { recursive: true });
45 35 for (const file of ["SYSTEM.md", "MISSION.md", "RULES.md"])
46 36 write(root, `.system/${file}`, `# ${file}\n`);
47 - write(
48 - root,
49 - ".system/config.json",
50 - '{"prefix":"PX","schemaVersion":1,"styleVersion":1}',
51 - );
52 - write(root, ".system/system.css", "/* The System styleVersion: 1 */\n");
37 + write(root, ".system/config.json", '{"prefix":"PX","schemaVersion":2}');
55 39 const snapshot = (root: string) => {
56 40 const entries: {
57 41 path: string;
61 45 }[] = [];
62 46 const visit = (directory: string) => {
63 47 for (const entry of readdirSync(directory, { withFileTypes: true }).sort(
64 - (left, right) => left.name.localeCompare(right.name),
48 + (a, b) => a.name.localeCompare(b.name),
66 50 const target = path.join(directory, entry.name);
67 51 const stats = statSync(target);
81 65 visit(root);
82 66 return entries;
85 68 afterEach(() => {
86 69 for (const root of roots.splice(0))
87 70 rmSync(root, { recursive: true, force: true });
90 73 describe("system doctor", () => {
91 - it("reports every required path in stable path/code order", () => {
74 + it("requires config, cores, and typed directories but not CSS", () => {
92 75 const root = temporaryRoot();
93 - const result = runDoctor(path.join(root, "nested"));
95 - assert.equal(result.root, root);
96 - assert.equal(result.exitCode, 1);
76 + const result = runDoctor(root);
97 77 assert.deepEqual(
98 78 result.diagnostics.map(({ code, path }) => `${path} ${code}`),
107 87 ".system/research filesystem.missing",
108 88 ".system/roadmaps filesystem.missing",
109 89 ".system/specs filesystem.missing",
110 - ".system/system.css filesystem.missing",
115 - it("combines machine-state, kernel, mockup, and test-reference findings", () => {
94 + it("combines shared bundle, graph, obsolete CSS, and test diagnostics", () => {
116 95 const root = temporaryRoot();
117 96 validSystem(root);
97 + write(root, ".system/system.css", "legacy\n");
118 98 write(
119 99 root,
120 - ".system/config.json",
121 - '{"prefix":"PX","schemaVersion":2,"styleVersion":2}',
122 - );
123 - write(root, ".system/system.css", "/* The System styleVersion: 1 */\n");
124 - write(
125 - root,
126 - ".system/specs/PX-SPEC-001-contract.html",
127 - html({ id: "PX-SPEC-001", type: "spec" }),
100 + ".system/specs/PX-SPEC-001-contract/index.md",
101 + markdown("PX-SPEC-001"),
129 103 write(
131 - ".system/plans/PX-PLAN-001-work.html",
132 - html({ id: "PX-PLAN-001", type: "plan", spec: "PX-SPEC-999" }),
105 + ".system/specs/PX-SPEC-001-contract/mockup-mobile.html",
106 + "<!doctype html>",
134 108 write(
136 - ".system/specs/PX-SPEC-404-gone-mockup-empty.html",
137 - "<!doctype html><title>asset</title>",
110 + ".system/plans/PX-PLAN-001-work/index.md",
111 + markdown("PX-PLAN-001", "plan", "\nspec: PX-SPEC-999"),
139 - write(
140 - root,
141 - "tests/contract.test.ts",
142 - "// SYSTEM-SPEC: PX-SPEC-001\n// SYSTEM-SPEC: PX-SPEC-999\n",
143 - );
113 + write(root, ".system/specs/PX-SPEC-002-empty/readme.txt", "asset");
114 + write(root, "tests/contract.test.ts", "// SYSTEM-SPEC: PX-SPEC-999\n");
145 115 const result = runDoctor(root);
147 - assert.deepEqual(result.references, [
148 - { path: "tests/contract.test.ts", spec: "PX-SPEC-001" },
149 - { path: "tests/contract.test.ts", spec: "PX-SPEC-999" },
150 - ]);
151 116 assert.deepEqual(
152 117 result.diagnostics.map(({ code, path }) => `${path} ${code}`),
154 - ".system/config.json config.schema-outdated",
155 - ".system/config.json config.style-outdated",
156 - ".system/plans/PX-PLAN-001-work.html graph.dangling-reference",
157 - ".system/specs/PX-SPEC-404-gone-mockup-empty.html mockup.orphaned",
158 - ".system/system.css css.version-mismatch",
119 + ".system/plans/PX-PLAN-001-work/index.md graph.dangling-reference",
120 + ".system/specs/PX-SPEC-002-empty bundle.missing-index",
121 + ".system/system.css filesystem.obsolete",
159 122 "tests/contract.test.ts test.dangling-reference",
162 - assert.equal(result.exitCode, 1);
165 - it("returns green for a complete system and ignores symlinks and non-HTML files", () => {
127 + it("does not follow bundle symlinks and is green for a complete bundled system", () => {
166 128 const root = temporaryRoot();
129 + const outside = temporaryRoot();
167 130 validSystem(root);
168 131 write(
170 - ".system/specs/PX-SPEC-001-contract.html",
171 - html({ id: "PX-SPEC-001", type: "spec" }),
133 + ".system/specs/PX-SPEC-001-contract/index.md",
134 + markdown("PX-SPEC-001"),
135 + );
136 + write(
137 + root,
138 + ".system/specs/PX-SPEC-001-contract/mockup-mobile.html",
139 + "<!doctype html>",
140 + );
141 + assert.deepEqual(runDoctor(root).diagnostics, []);
142 + symlinkSync(
143 + outside,
144 + path.join(root, ".system/specs/PX-SPEC-002-link"),
145 + "dir",
146 + );
147 + assert.deepEqual(
148 + runDoctor(root).diagnostics.map(({ code }) => code),
149 + ["bundle.symbolic-link"],
173 - write(root, ".system/specs/notes.txt", "not authored HTML");
174 - write(root, "src/value.ts", "export const value = 1;\n");
176 - const result = runDoctor(root);
178 - assert.deepEqual(result.diagnostics, []);
179 - assert.deepEqual(result.references, []);
180 - assert.equal(result.exitCode, 0);
183 - it("renders stable CLI output, returns status, and does not mutate the tree", () => {
153 + it("renders stable CLI output without mutation", () => {
184 154 const root = temporaryRoot();
185 155 validSystem(root);
186 156 write(
188 - ".system/specs/PX-SPEC-001-contract.html",
189 - html({ id: "PX-SPEC-001", type: "spec" }),
158 + ".system/specs/PX-SPEC-001-contract/index.md",
159 + markdown("PX-SPEC-001"),
191 161 write(root, "tests/contract.test.ts", "// SYSTEM-SPEC: PX-SPEC-001\n");
192 162 const before = snapshot(root);
193 163 const script = path.resolve(import.meta.dirname, "../scripts/doctor.mjs");
195 - const green = spawnSync(
164 + const child = spawnSync(
196 165 process.execPath,
197 166 ["--experimental-strip-types", script, root],
198 167 { encoding: "utf8", env: { ...process.env, NODE_NO_WARNINGS: "1" } },
201 - assert.equal(green.status, 0);
169 + assert.equal(child.status, 0);
202 170 assert.equal(
203 - green.stdout,
171 + child.stdout,
204 172 `ROOT ${root}\nREF tests/contract.test.ts PX-SPEC-001\nOK The System is valid\n`,
206 - assert.equal(green.stderr, "");
174 + assert.equal(child.stderr, "");
207 175 assert.deepEqual(snapshot(root), before);
209 - write(root, ".system/system.css", "unversioned\n");
210 - const brokenBefore = snapshot(root);
211 - const red = spawnSync(
212 - process.execPath,
213 - ["--experimental-strip-types", script, root],
214 - { encoding: "utf8", env: { ...process.env, NODE_NO_WARNINGS: "1" } },
215 - );
217 - assert.equal(red.status, 1);
218 - assert.equal(
219 - red.stdout,
220 - `ROOT ${root}\nREF tests/contract.test.ts PX-SPEC-001\nERROR css.version .system/system.css: Missing The System styleVersion marker\n`,
221 - );
222 - assert.equal(red.stderr, "");
223 - assert.deepEqual(snapshot(root), brokenBefore);

extensions/the-system/__tests__/documents.test.ts

Modified
2 2 import assert from "node:assert/strict";
3 3 import {
4 4 mkdirSync,
5 5 mkdtempSync,
6 - readFileSync,
7 6 rmSync,
7 + symlinkSync,
8 8 writeFileSync,
9 9 } from "node:fs";
10 10 import { tmpdir } from "node:os";
11 11 import path from "node:path";
12 12 import { afterEach, describe, it } from "vitest";
13 13 import {
14 + discoverDocumentBundles,
14 15 discoverProjectRoot,
15 - indexDocuments,
16 - parseDocumentId,
17 - parseDocumentMetadata,
16 + indexBundleDocuments,
17 + inspectSystemConfig,
18 + parseAuthoredDocument,
18 19 parseSystemConfig,
19 20 resolveGovernedPath,
20 21 SystemDocumentError,
21 - validateAuthoredHtml,
22 - validateDocumentCandidate,
23 - validateFilename,
22 + validateBundleCandidate,
23 + validateDocumentPath,
24 24 } from "../documents.ts";
26 -const temporary: string[] = [];
26 +const roots: string[] = [];
27 27 const tree = () => {
28 28 const root = mkdtempSync(path.join(tmpdir(), "the-system-documents-"));
29 - temporary.push(root);
29 + roots.push(root);
30 30 return root;
32 -const dir = (...parts: string[]) => {
33 - const result = path.join(...parts);
34 - mkdirSync(result, { recursive: true });
35 - return result;
32 +const dir = (root: string, ...parts: string[]) => {
33 + const target = path.join(root, ...parts);
34 + mkdirSync(target, { recursive: true });
35 + return target;
37 +const write = (root: string, relative: string, content: string) => {
38 + const target = path.join(root, relative);
39 + dir(path.dirname(target));
40 + writeFileSync(target, content);
41 +};
42 +const markdownSource = (
43 + directory: string,
44 + id: string,
45 + slug: string,
46 + frontmatter: string,
47 +) => ({
48 + path: `.system/${directory}/${id}-${slug}/index.md`,
49 + markdown: `---\n${frontmatter}\n---\n\n# ${id}\n`,
50 +});
51 +const specMarkdown = (id: string) =>
52 + `---\nid: ${id}\ntype: spec\n---\n\n# ${id}\n`;
37 53 afterEach(() => {
38 - for (const root of temporary.splice(0))
54 + for (const root of roots.splice(0))
39 55 rmSync(root, { recursive: true, force: true });
42 -describe("project root", () => {
43 - it.each([
44 - ["simple Git", [".git"], "directory"],
45 - ["Git worktree", [".git"], "file"],
46 - ["JJ workspace", [".jj"], "directory"],
47 - ["colocated JJ/Git", [".jj", ".git"], "directory"],
48 - ] as const)("resolves %s", (_name, markers, markerKind) => {
58 +describe("project root and schema-v2 config", () => {
59 + it("contains paths and resolves nearest marker", () => {
49 60 const root = tree();
50 - const cwd = dir(root, "packages", "app");
51 - for (const marker of markers) {
52 - const target = path.join(root, marker);
53 - if (markerKind === "file" && marker === ".git")
54 - writeFileSync(target, "gitdir: ../shared\n");
55 - else mkdirSync(target);
56 - }
57 - assert.equal(discoverProjectRoot(cwd), root);
58 - });
60 - it("uses cwd when no VCS marker exists", () => {
61 - const cwd = dir(tree(), "plain");
62 - assert.equal(discoverProjectRoot(cwd), path.resolve(cwd));
63 - });
65 - it("fails when nearest JJ and Git roots differ", () => {
66 - const gitRoot = tree();
67 - mkdirSync(path.join(gitRoot, ".git"));
68 - const jjRoot = dir(gitRoot, "nested");
69 - mkdirSync(path.join(jjRoot, ".jj"));
70 - const cwd = dir(jjRoot, "src");
61 + mkdirSync(path.join(root, ".git"));
62 + assert.equal(discoverProjectRoot(path.join(root, "nested")), root);
63 + assert.equal(resolveGovernedPath(root, "x/../x"), path.join(root, "x"));
71 64 assert.throws(
72 - () => discoverProjectRoot(cwd),
73 - (error: unknown) =>
74 - error instanceof SystemDocumentError &&
75 - error.code === "root.conflict" &&
76 - error.message ===
77 - `Conflicting project roots: Git ${gitRoot}; JJ ${jjRoot}`,
65 + () => resolveGovernedPath(root, "../outside"),
66 + SystemDocumentError,
80 -});
82 -describe("governed path containment", () => {
83 - it("normalizes a contained relative path", () => {
84 - const root = path.resolve("project");
85 - assert.equal(
86 - resolveGovernedPath(root, ".system/specs/../plans/a.html"),
87 - path.join(root, ".system", "plans", "a.html"),
88 - );
89 - });
91 - it.each([
92 - "../outside",
93 - path.resolve("outside"),
94 - ])("rejects %s", (candidate) => {
95 - assert.throws(
96 - () => resolveGovernedPath(path.resolve("project"), candidate),
97 - (error: unknown) =>
98 - error instanceof SystemDocumentError &&
99 - error.code === "path.outside-root",
100 - );
101 - });
103 - it("does not confuse a sibling sharing the root prefix for a child", () => {
104 - const root = path.resolve("project");
105 - assert.throws(
106 - () => resolveGovernedPath(root, path.resolve("project-other/file")),
107 - /outside project root/,
108 - );
109 - });
110 -});
112 -describe("system config", () => {
113 - it("accepts only the exact versioned shape", () => {
114 - assert.deepEqual(
115 - parseSystemConfig('{"prefix":"PX","schemaVersion":1,"styleVersion":1}'),
116 - {
117 - prefix: "PX",
118 - schemaVersion: 1,
119 - styleVersion: 1,
120 - },
121 - );
122 - });
124 - it("rejects duplicate config keys", () =>
125 - assert.throws(
126 - () =>
127 - parseSystemConfig(
128 - '{"prefix":"PX","prefix":"AB","schemaVersion":1,"styleVersion":1}',
129 - ),
130 - (error: unknown) =>
131 - error instanceof SystemDocumentError &&
132 - error.code === "config.duplicate-key",
133 - ));
135 - it.each([
136 - ["malformed JSON", "{"],
137 - [
138 - "unknown key",
139 - '{"prefix":"PX","schemaVersion":1,"styleVersion":1,"extra":true}',
140 - ],
141 - ["missing key", '{"prefix":"PX","schemaVersion":1}'],
142 - ["short prefix", '{"prefix":"P","schemaVersion":1,"styleVersion":1}'],
143 - ["lowercase prefix", '{"prefix":"px","schemaVersion":1,"styleVersion":1}'],
144 - ["zero schema", '{"prefix":"PX","schemaVersion":0,"styleVersion":1}'],
145 - [
146 - "fractional style",
147 - '{"prefix":"PX","schemaVersion":1,"styleVersion":1.5}',
148 - ],
149 - ])("rejects %s", (_name, source) =>
150 - assert.throws(() => parseSystemConfig(source), SystemDocumentError));
151 -});
153 -describe("document IDs and filenames", () => {
154 - it.each([
155 - ["PX-SPEC-001", "spec", 1],
156 - ["PX-ROADMAP-999", "roadmap", 999],
157 - ["PX-PLAN-1000", "plan", 1000],
158 - ["PX-ISSUE-042", "issue", 42],
159 - ["PX-RESEARCH-007", "research", 7],
160 - ] as const)("parses %s", (id, type, sequence) => {
161 - assert.deepEqual(parseDocumentId(id, "PX"), {
162 - id,
69 + it("accepts current config and inspects only narrow v1 config", () => {
70 + assert.deepEqual(parseSystemConfig('{"prefix":"PX","schemaVersion":2}'), {
163 71 prefix: "PX",
164 - type,
165 - sequence,
72 + schemaVersion: 2,
167 - });
169 - it.each([
170 - "P-SPEC-001",
171 - "px-SPEC-001",
172 - "PX-spec-001",
173 - "PX-SPEC-01",
174 - "PX-SPEC-000",
175 - "PX-SPEC-0001",
176 - "PX-TEST-001",
177 - "PX-SPEC-001-slug",
178 - ])("rejects invalid ID %s", (id) =>
179 - assert.throws(() => parseDocumentId(id), /Invalid document ID/));
181 - it("rejects a foreign configured prefix", () =>
182 - assert.throws(() => parseDocumentId("AB-SPEC-001", "PX"), /prefix PX/));
184 - it("accepts a matching type directory, ID, and slug", () => {
185 - assert.doesNotThrow(() =>
186 - validateFilename(
187 - "/project/.system/specs/PX-SPEC-001-login-flow.html",
188 - { id: "PX-SPEC-001", type: "spec" },
189 - "PX",
190 - ),
191 - );
192 - });
194 - it.each([
195 - "/project/.system/specs/PX-SPEC-002-login-flow.html",
196 - "/project/.system/specs/PX-SPEC-001-Login.html",
197 - "/project/.system/plans/PX-SPEC-001-login-flow.html",
198 - "/project/.system/specs/PX-SPEC-001-login_flow.html",
199 - ])("rejects mismatched filename %s", (filename) => {
200 74 assert.throws(
201 75 () =>
202 - validateFilename(filename, { id: "PX-SPEC-001", type: "spec" }, "PX"),
203 - /Filename mismatch/,
76 + parseSystemConfig('{"prefix":"PX","schemaVersion":1,"styleVersion":1}'),
77 + SystemDocumentError,
78 + );
79 + assert.deepEqual(
80 + inspectSystemConfig('{"prefix":"PX","schemaVersion":1,"styleVersion":1}'),
81 + { config: { prefix: "PX", schemaVersion: 1 }, legacyStyleVersion: 1 },
208 -const shell = (
209 - metadata: string,
210 - body = "<header><h1>Title</h1></header><main><section><h2>Contract</h2><p>Readable.</p></section></main>",
211 -) => `<!doctype html>
212 -<html lang="en"><head><meta charset="utf-8">
213 -<meta name="viewport" content="width=device-width, initial-scale=1">
214 -<title>Title</title><link rel="stylesheet" href="../system.css"></head>
215 -<body>${body}<script type="application/json" id="system-meta">${metadata}</script></body></html>`;
217 -describe("document metadata", () => {
218 - it.each([
219 - ['{"id":"PX-SPEC-001","type":"spec"}', { id: "PX-SPEC-001", type: "spec" }],
220 - [
221 - '{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-SPEC-001"}',
222 - { id: "PX-ROADMAP-001", type: "roadmap", spec: "PX-SPEC-001" },
223 - ],
224 - [
225 - '{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001"}',
226 - { id: "PX-PLAN-001", type: "plan", spec: "PX-SPEC-001" },
227 - ],
228 - [
229 - '{"id":"PX-PLAN-002","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001","phase":2}',
230 - {
231 - id: "PX-PLAN-002",
232 - type: "plan",
233 - spec: "PX-SPEC-001",
234 - roadmap: "PX-ROADMAP-001",
235 - phase: 2,
236 - },
237 - ],
238 - [
239 - '{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":[]}',
240 - { id: "PX-ISSUE-001", type: "issue", status: "open", specs: [] },
241 - ],
242 - [
243 - '{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11","sources":["https://example.com/a"]}',
86 +describe("Markdown bundle metadata", () => {
87 + it("projects known graph fields while preserving unknown frontmatter", () => {
88 + const parsed = parseAuthoredDocument(
89 + `---\nid: PX-PLAN-001\ntype: plan\nspec: PX-SPEC-001\nroadmap: PX-ROADMAP-001\nphase: 2\ntitle: Delivery\nreview:\n owner: human\n---\n\n# Delivery\n`,
90 + "PX",
91 + );
92 + assert.deepEqual(parsed.metadata, {
93 + id: "PX-PLAN-001",
94 + type: "plan",
95 + spec: "PX-SPEC-001",
96 + roadmap: "PX-ROADMAP-001",
97 + phase: 2,
98 + });
99 + assert.deepEqual(
100 + [...parsed.frontmatter.keys()],
101 + ["id", "type", "spec", "roadmap", "phase", "title", "review"],
102 + );
103 + assert.deepEqual(
104 + parseAuthoredDocument(
105 + "---\nid: PX-RESEARCH-001\ntype: research\ncapturedAt: 2026-07-15\nsources: [notes/local.txt, http://example.test]\n---\n",
106 + "PX",
107 + ).metadata,
245 109 id: "PX-RESEARCH-001",
246 110 type: "research",
247 - capturedAt: "2026-07-11",
248 - sources: ["https://example.com/a"],
111 + capturedAt: "2026-07-15",
112 + sources: ["notes/local.txt", "http://example.test"],
250 - ],
251 - ] as const)("parses exact metadata %s", (json, expected) =>
252 - assert.deepEqual(parseDocumentMetadata(shell(json), "PX"), expected));
254 - it("wraps malformed metadata JSON", () => {
255 - assert.throws(
256 - () =>
257 - parseDocumentMetadata(
258 - shell('{"id":"PX-SPEC-001","type":"spec","\\uZZZZ":true}'),
259 - "PX",
260 - ),
261 - (error: unknown) =>
262 - error instanceof SystemDocumentError &&
263 - error.code === "metadata.invalid-json",
116 + it("accepts only canonical index paths", () => {
117 + const metadata = { id: "PX-SPEC-001", type: "spec" } as const;
118 + assert.doesNotThrow(() =>
119 + validateDocumentPath(
120 + ".system/specs/PX-SPEC-001-login-flow/index.md",
121 + metadata,
122 + "PX",
123 + ),
124 + );
125 + for (const item of [
126 + ".system/specs/PX-SPEC-001-login-flow.md",
127 + ".system/plans/PX-SPEC-001-login-flow/index.md",
128 + ".system/specs/PX-SPEC-001-Login/index.md",
129 + ".system/specs/PX-SPEC-001-login-flow/other/index.md",
130 + ])
131 + assert.throws(
132 + () => validateDocumentPath(item, metadata, "PX"),
133 + SystemDocumentError,
134 + );
135 + });
136 +});
267 - it("ignores metadata blocks inside HTML comments", () => {
268 - const html = `${shell('{"id":"PX-SPEC-001","type":"spec"}')}<!-- <script type="application/json" id="system-meta">{}</script> -->`;
269 - assert.deepEqual(parseDocumentMetadata(html, "PX"), {
270 - id: "PX-SPEC-001",
271 - type: "spec",
138 +describe("bundle discovery", () => {
139 + it("returns authored indexes and structural diagnostics separately", () => {
140 + const root = tree();
141 + write(
142 + root,
143 + ".system/specs/PX-SPEC-001-contract/index.md",
144 + specMarkdown("PX-SPEC-001"),
145 + );
146 + write(root, ".system/specs/PX-SPEC-001-contract/assets/data.csv", "a,b");
147 + write(root, ".system/plans/loose.md", "bad");
148 + dir(root, ".system", "specs", "PX-SPEC-002-empty");
149 + assert.deepEqual(discoverDocumentBundles(root).sources, [
151 + path: ".system/specs/PX-SPEC-001-contract/index.md",
152 + markdown: specMarkdown("PX-SPEC-001"),
153 + },
154 + ]);
155 + assert.deepEqual(
156 + discoverDocumentBundles(root).diagnostics.map(
157 + (item) => `${item.path} ${item.code}`,
158 + ),
160 + ".system/plans/loose.md bundle.expected-directory",
161 + ".system/specs/PX-SPEC-002-empty bundle.missing-index",
162 + ],
163 + );
164 + });
165 + it("rejects a symlinked .system root without following it", () => {
166 + const root = tree();
167 + const outside = tree();
168 + write(
169 + outside,
170 + ".system/specs/PX-SPEC-001-contract/index.md",
171 + specMarkdown("PX-SPEC-001"),
172 + );
173 + symlinkSync(
174 + path.join(outside, ".system"),
175 + path.join(root, ".system"),
176 + "dir",
177 + );
178 + assert.deepEqual(discoverDocumentBundles(root), {
179 + sources: [],
180 + diagnostics: [
182 + code: "bundle.symbolic-link",
183 + path: ".system",
184 + message: "Bundle path is a symbolic link: .system",
185 + },
186 + ],
275 - it.each([
276 - ["missing block", '<!doctype html><html lang="en"></html>'],
277 - [
278 - "duplicate blocks",
279 - shell('{"id":"PX-SPEC-001","type":"spec"}') +
280 - '<script type="application/json" id="system-meta">{}</script>',
281 - ],
282 - [
283 - "duplicate JSON key",
284 - shell('{"id":"PX-SPEC-001","id":"PX-SPEC-002","type":"spec"}'),
285 - ],
286 - [
287 - "unknown key",
288 - shell('{"id":"PX-SPEC-001","type":"spec","status":"open"}'),
289 - ],
290 - ["own ID/type mismatch", shell('{"id":"PX-PLAN-001","type":"spec"}')],
291 - [
292 - "one-sided roadmap",
293 - shell(
294 - '{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001"}',
295 - ),
296 - ],
297 - [
298 - "duplicate issue specs",
299 - shell(
300 - '{"id":"PX-ISSUE-001","type":"issue","status":"fixed","specs":["PX-SPEC-001","PX-SPEC-001"]}',
301 - ),
302 - ],
303 - [
304 - "invalid date",
305 - shell(
306 - '{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-02-30"}',
307 - ),
308 - ],
309 - [
310 - "non-HTTPS source",
311 - shell(
312 - '{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11","sources":["http://example.com"]}',
313 - ),
314 - ],
315 - ])("rejects %s", (_name, html) =>
316 - assert.throws(
317 - () => parseDocumentMetadata(html, "PX"),
318 - SystemDocumentError,
319 - ));
320 -});
322 -describe("authored HTML", () => {
323 - it("accepts the complete semantic shell and inert progressive enhancement", () => {
324 - const html = shell(
325 - '{"id":"PX-SPEC-001","type":"spec"}',
326 - "<header><h1>Title</h1></header><main><section><h2>Contract</h2><details><summary>More</summary><p>Text.</p></details></section></main><script>document.querySelector('details');</script>",
190 + it("reports symlinks without following them", () => {
191 + const root = tree();
192 + const outside = tree();
193 + write(
194 + root,
195 + ".system/specs/PX-SPEC-001-contract/index.md",
196 + specMarkdown("PX-SPEC-001"),
197 + );
198 + symlinkSync(
199 + outside,
200 + path.join(root, ".system/specs/PX-SPEC-002-link"),
201 + "dir",
202 + );
203 + symlinkSync(
204 + outside,
205 + path.join(root, ".system/specs/PX-SPEC-001-contract/assets-link"),
206 + "dir",
328 208 assert.deepEqual(
329 - validateAuthoredHtml("specs/PX-SPEC-001-title.html", html),
330 - [],
331 - );
332 - });
334 - it.each([
335 - [
336 - "document.doctype",
337 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(
338 - "<!doctype html>",
339 - "",
340 - ),
341 - ],
342 - [
343 - "document.language",
344 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(
345 - 'lang="en"',
346 - 'lang="fr"',
347 - ),
348 - ],
349 - [
350 - "document.charset",
351 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(
352 - '<meta charset="utf-8">',
353 - "",
354 - ),
355 - ],
356 - [
357 - "document.viewport",
358 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(
359 - /<meta name="viewport"[^>]+>/,
360 - "",
361 - ),
362 - ],
363 - [
364 - "document.title",
365 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(
366 - "<title>Title</title>",
367 - "<title></title>",
368 - ),
369 - ],
370 - [
371 - "document.stylesheet",
372 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(
373 - "../system.css",
374 - "./local.css",
375 - ),
376 - ],
377 - [
378 - "document.semantic-shell",
379 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(
380 - /<main>|<\/main>/g,
381 - "",
382 - ),
383 - ],
384 - [
385 - "document.forbidden-tag",
386 - shell(
387 - '{"id":"PX-SPEC-001","type":"spec"}',
388 - '<header><h1>X</h1></header><main><section><iframe src="x"></iframe></section></main>',
389 - ),
390 - ],
391 - [
392 - "document.event-handler",
393 - shell(
394 - '{"id":"PX-SPEC-001","type":"spec"}',
395 - '<header><h1>X</h1></header><main><section onclick="x()">X</section></main>',
396 - ),
397 - ],
398 - [
399 - "document.executable-url",
400 - shell(
401 - '{"id":"PX-SPEC-001","type":"spec"}',
402 - '<header><h1>X</h1></header><main><section><a href="javascript:x()">X</a></section></main>',
403 - ),
404 - ],
405 - [
406 - "document.external-script",
407 - shell(
408 - '{"id":"PX-SPEC-001","type":"spec"}',
409 - '<header><h1>X</h1></header><main><section>X</section></main><script src="https://example.com/x.js"></script>',
410 - ),
411 - ],
412 - [
413 - "document.active-api",
414 - shell(
415 - '{"id":"PX-SPEC-001","type":"spec"}',
416 - "<header><h1>X</h1></header><main><section>X</section></main><script>fetch('https://example.com')</script>",
417 - ),
418 - ],
419 - [
420 - "document.css-resource",
421 - shell(
422 - '{"id":"PX-SPEC-001","type":"spec"}',
423 - "<header><h1>X</h1></header><main><section>X</section></main><style>@import url('https://example.com/x.css');</style>",
424 - ),
425 - ],
426 - [
427 - "document.meta-refresh",
428 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(
429 - "</head>",
430 - '<meta http-equiv="refresh" content="0; url=x"></head>',
431 - ),
432 - ],
433 - ])("reports %s", (code, html) =>
434 - assert.ok(
435 - validateAuthoredHtml("doc.html", html).some((item) => item.code === code),
436 - ));
438 - it("ignores shell and forbidden tags inside HTML comments", () => {
439 - const html = shell(
440 - '{"id":"PX-SPEC-001","type":"spec"}',
441 - "<!-- <header><main><section><iframe></iframe></section></main></header> -->",
442 - );
443 - const codes = validateAuthoredHtml("doc.html", html).map(
444 - ({ code }) => code,
445 - );
446 - assert.ok(codes.includes("document.semantic-shell"));
447 - assert.ok(!codes.includes("document.forbidden-tag"));
448 - });
450 - it.each([
451 - ["missing head close", "</head>"],
452 - ["missing body close", "</body>"],
453 - ["missing html close", "</html>"],
454 - ["missing header close", "</header>"],
455 - ["missing main close", "</main>"],
456 - ["missing section close", "</section>"],
457 - ] as const)("requires a complete shell: %s", (_name, removed) => {
458 - const findings = validateAuthoredHtml(
459 - "doc.html",
460 - shell('{"id":"PX-SPEC-001","type":"spec"}').replace(removed, ""),
461 - );
462 - assert.ok(
463 - findings.some(
464 - ({ code }) =>
465 - code === "document.structure" || code === "document.semantic-shell",
466 - ),
467 - );
468 - });
470 - it.each([
471 - [
472 - "unquoted executable URL",
473 - "<a href=javascript:alert(1)>X</a>",
474 - "document.executable-url",
475 - ],
476 - [
477 - "encoded executable URL with control whitespace",
478 - '<a href="java&#x09;script&colon;alert(1)">X</a>',
479 - "document.executable-url",
480 - ],
481 - [
482 - "unquoted remote src",
483 - "<img src=https://example.com/a.png>",
484 - "document.remote-resource",
485 - ],
486 - [
487 - "encoded remote srcset",
488 - '<img srcset="/local.png 1x, https&#58;//example.com/a.png 2x">',
489 - "document.remote-resource",
490 - ],
491 - [
492 - "remote poster",
493 - '<video poster="//example.com/poster.png"></video>',
494 - "document.remote-resource",
495 - ],
496 - [
497 - "resource-bearing href",
498 - '<link rel="preload" href="https://example.com/font.woff2">',
499 - "document.remote-resource",
500 - ],
501 - ] as const)("rejects %s", (_name, markup, code) => {
502 - const html = shell(
503 - '{"id":"PX-SPEC-001","type":"spec"}',
504 - `<header><h1>X</h1></header><main><section>${markup}</section></main>`,
505 - );
506 - assert.ok(
507 - validateAuthoredHtml("doc.html", html).some(
508 - (finding) => finding.code === code,
509 - ),
510 - );
511 - });
513 - it("allows quoted and unquoted remote HTTPS navigation anchors", () => {
514 - for (const anchor of [
515 - '<a href="https://example.com/reference">Reference</a>',
516 - "<a href=https://example.com/reference>Reference</a>",
517 - ]) {
518 - const html = shell(
519 - '{"id":"PX-SPEC-001","type":"spec"}',
520 - `<header><h1>X</h1></header><main><section>${anchor}</section></main>`,
521 - );
522 - assert.deepEqual(validateAuthoredHtml("doc.html", html), []);
523 - }
524 - });
525 -});
527 -const source = (
528 - folder: string,
529 - id: string,
530 - slug: string,
531 - metadata: string,
532 -) => ({
533 - path: `/project/.system/${folder}/${id}-${slug}.html`,
534 - html: shell(metadata),
535 -});
537 -describe("document index", () => {
538 - it("indexes a valid complete graph without diagnostics", () => {
539 - const result = indexDocuments(
540 - [
541 - source(
542 - "specs",
543 - "PX-SPEC-001",
544 - "login",
545 - '{"id":"PX-SPEC-001","type":"spec"}',
546 - ),
547 - source(
548 - "roadmaps",
549 - "PX-ROADMAP-001",
550 - "login",
551 - '{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-SPEC-001"}',
552 - ),
553 - source(
554 - "plans",
555 - "PX-PLAN-001",
556 - "login-phase-2",
557 - '{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-001","phase":2}',
558 - ),
559 - source(
560 - "issues",
561 - "PX-ISSUE-001",
562 - "login-error",
563 - '{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":["PX-SPEC-001"]}',
564 - ),
565 - source(
566 - "research",
567 - "PX-RESEARCH-001",
568 - "login",
569 - '{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-11"}',
570 - ),
571 - ],
572 - "PX",
573 - );
574 - assert.equal(result.documents.length, 5);
575 - assert.deepEqual(result.diagnostics, []);
576 - });
578 - it("excludes HTML- and filename-invalid documents from graph edges", () => {
579 - const invalidSpec = source(
580 - "specs",
581 - "PX-SPEC-009",
582 - "bad-html",
583 - '{"id":"PX-SPEC-009","type":"spec"}',
584 - );
585 - invalidSpec.html = invalidSpec.html.replace(
586 - "<header>",
587 - "<!-- <header> -->",
588 - );
589 - const invalidPlan = source(
590 - "plans",
591 - "PX-PLAN-002",
592 - "invalid-source",
593 - '{"id":"PX-PLAN-002","type":"plan","spec":"PX-SPEC-404"}',
594 - );
595 - invalidPlan.html = invalidPlan.html.replace("<main>", "");
596 - const invalidFilenamePlan = source(
597 - "plans",
598 - "PX-PLAN-004",
599 - "invalid-filename-source",
600 - '{"id":"PX-PLAN-003","type":"plan","spec":"PX-SPEC-405"}',
601 - );
602 - const result = indexDocuments(
603 - [
604 - invalidSpec,
605 - source(
606 - "specs",
607 - "PX-SPEC-002",
608 - "wrong-name",
609 - '{"id":"PX-SPEC-010","type":"spec"}',
610 - ),
611 - source(
612 - "plans",
613 - "PX-PLAN-001",
614 - "references-invalid-html",
615 - '{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-009"}',
616 - ),
617 - source(
618 - "plans",
619 - "PX-PLAN-005",
620 - "references-invalid-filename",
621 - '{"id":"PX-PLAN-005","type":"plan","spec":"PX-SPEC-010"}',
622 - ),
623 - invalidPlan,
624 - invalidFilenamePlan,
625 - ],
626 - "PX",
627 - );
628 - const invalidSourcePaths = new Set(
629 - result.documents
630 - .filter(({ metadata }) =>
631 - ["PX-PLAN-002", "PX-PLAN-003"].includes(metadata.id),
632 - )
633 - .map(({ path }) => path),
634 - );
635 - assert.ok(
636 - result.diagnostics.some(
637 - ({ code, path }) =>
638 - code === "document.filename" && path.includes("PX-SPEC-002"),
639 - ),
640 - );
641 - assert.ok(
642 - result.diagnostics.some(
643 - ({ code, path }) =>
644 - code === "document.semantic-shell" && path.includes("PX-SPEC-009"),
645 - ),
646 - );
647 - for (const planId of ["PX-PLAN-001", "PX-PLAN-005"])
648 - assert.ok(
649 - result.diagnostics.some(
650 - ({ code, path }) =>
651 - code === "graph.dangling-reference" && path.includes(planId),
652 - ),
653 - );
654 - for (const path of invalidSourcePaths)
655 - assert.ok(
656 - result.diagnostics.some(
657 - (item) => item.path === path && item.code.startsWith("document."),
658 - ),
659 - );
660 - assert.ok(
661 - !result.diagnostics.some(
662 - ({ code, path }) =>
663 - code.startsWith("graph.") && invalidSourcePaths.has(path),
664 - ),
665 - );
666 - });
668 - it("sorts stable filename, dangling, and forbidden-edge diagnostics", () => {
669 - const result = indexDocuments(
670 - [
671 - source(
672 - "specs",
673 - "PX-SPEC-001",
674 - "one",
675 - '{"id":"PX-SPEC-001","type":"spec"}',
676 - ),
677 - source(
678 - "specs",
679 - "PX-SPEC-002",
680 - "two",
681 - '{"id":"PX-SPEC-001","type":"spec"}',
682 - ),
683 - source(
684 - "roadmaps",
685 - "PX-ROADMAP-001",
686 - "wrong-target",
687 - '{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-PLAN-009"}',
688 - ),
689 - source(
690 - "plans",
691 - "PX-PLAN-001",
692 - "dangling",
693 - '{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-404"}',
694 - ),
695 - source(
696 - "plans",
697 - "PX-PLAN-002",
698 - "crossed",
699 - '{"id":"PX-PLAN-002","type":"plan","spec":"PX-SPEC-001","roadmap":"PX-ROADMAP-002","phase":1}',
700 - ),
701 - source(
702 - "roadmaps",
703 - "PX-ROADMAP-002",
704 - "other",
705 - '{"id":"PX-ROADMAP-002","type":"roadmap","spec":"PX-SPEC-003"}',
706 - ),
707 - source(
708 - "issues",
709 - "PX-ISSUE-001",
710 - "unknown",
711 - '{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":[]}',
712 - ),
713 - ],
714 - "PX",
715 - );
716 - assert.deepEqual(
717 - result.diagnostics.map(({ code }) => code),
718 - [...result.diagnostics]
719 - .sort(
720 - (a, b) =>
721 - a.path.localeCompare(b.path) ||
722 - a.code.localeCompare(b.code) ||
723 - a.message.localeCompare(b.message),
724 - )
725 - .map(({ code }) => code),
726 - );
727 - assert.ok(
728 - !result.diagnostics.some((item) => item.code === "graph.duplicate-id"),
729 - );
730 - assert.ok(
731 - result.diagnostics.some((item) => item.code === "document.filename"),
732 - );
733 - assert.ok(
734 - result.diagnostics.some(
735 - (item) =>
736 - item.code === "graph.dangling-reference" &&
737 - item.message.includes("PX-SPEC-404"),
738 - ),
739 - );
740 - assert.ok(
741 - result.diagnostics.some(
742 - (item) =>
743 - item.code === "graph.forbidden-edge" &&
744 - item.message.includes("must reference spec"),
745 - ),
746 - );
747 - assert.ok(
748 - result.diagnostics.some(
749 - (item) =>
750 - item.code === "graph.forbidden-edge" &&
751 - item.message.includes("belongs to PX-SPEC-003"),
752 - ),
753 - );
754 - assert.ok(
755 - !result.diagnostics.some(
756 - (item) =>
757 - item.path.includes("PX-ISSUE-001") && item.code.startsWith("graph."),
758 - ),
209 + discoverDocumentBundles(root).diagnostics.map((item) => item.code),
210 + ["bundle.symbolic-link", "bundle.symbolic-link"],
763 -describe("document candidate validation", () => {
764 - const spec = (id: string, slug: string) => ({
765 - path: `.system/specs/${id}-${slug}.html`,
766 - html: shell(JSON.stringify({ id, type: "spec" })),
767 - });
768 - const roadmap = {
769 - path: ".system/roadmaps/PX-ROADMAP-001-delivery.html",
770 - html: shell(
771 - '{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-SPEC-001"}',
772 - ),
773 - };
775 - it("accepts a valid new spec against a valid current index", () => {
776 - const current = [spec("PX-SPEC-001", "first")];
777 - assert.deepEqual(
778 - validateDocumentCandidate(current, spec("PX-SPEC-002", "second"), "PX"),
779 - [],
780 - );
781 - });
783 - it("reports candidate failures and graph breakage caused by replacement", () => {
784 - const current = [spec("PX-SPEC-001", "first"), roadmap];
785 - const replacement = {
786 - path: ".system/specs/PX-SPEC-001-first.html",
787 - html: shell('{"id":"PX-SPEC-002","type":"spec"}'),
788 - };
789 - assert.deepEqual(
790 - validateDocumentCandidate(current, replacement, "PX").map(
791 - ({ code, path }) => `${path} ${code}`,
792 - ),
793 - [
794 - ".system/roadmaps/PX-ROADMAP-001-delivery.html graph.dangling-reference",
795 - ".system/specs/PX-SPEC-001-first.html document.filename",
796 - ],
797 - );
798 - });
800 - it("reports a duplicate ID on the candidate without replaying old findings", () => {
801 - const current = [
802 - spec("PX-SPEC-001", "first"),
803 - { path: ".system/specs/broken.html", html: "not html" },
215 +describe("bundle graph and candidate validation", () => {
216 + it("excludes duplicate IDs from reference targets", () => {
217 + const duplicatePaths = [
218 + ".system/specs/PX-SPEC-001-alpha/index.md",
219 + ".system/specs/PX-SPEC-001-beta/index.md",
805 - const findings = validateDocumentCandidate(
806 - current,
807 - {
808 - path: ".system/specs/PX-SPEC-001-copy.html",
809 - html: shell('{"id":"PX-SPEC-001","type":"spec"}'),
810 - },
221 + const indexed = indexBundleDocuments(
223 + markdownSource(
224 + "specs",
225 + "PX-SPEC-001",
226 + "alpha",
227 + "id: PX-SPEC-001\ntype: spec",
228 + ),
229 + markdownSource(
230 + "specs",
231 + "PX-SPEC-001",
232 + "beta",
233 + "id: PX-SPEC-001\ntype: spec",
234 + ),
235 + markdownSource(
236 + "roadmaps",
237 + "PX-ROADMAP-001",
238 + "delivery",
239 + "id: PX-ROADMAP-001\ntype: roadmap\nspec: PX-SPEC-001",
240 + ),
241 + ],
813 244 assert.deepEqual(
814 - findings.map(({ code, path }) => `${path} ${code}`),
815 - [".system/specs/PX-SPEC-001-copy.html graph.duplicate-id"],
245 + indexed.diagnostics.map(
246 + (item) => `${item.path} ${item.code}: ${item.message}`,
247 + ),
249 + ".system/roadmaps/PX-ROADMAP-001-delivery/index.md graph.dangling-reference: PX-ROADMAP-001 references missing PX-SPEC-001",
250 + `.system/specs/PX-SPEC-001-alpha/index.md graph.duplicate-id: Duplicate ID PX-SPEC-001: ${duplicatePaths.join(", ")}`,
251 + `.system/specs/PX-SPEC-001-beta/index.md graph.duplicate-id: Duplicate ID PX-SPEC-001: ${duplicatePaths.join(", ")}`,
252 + ],
818 -});
820 -describe("bundled system.css", () => {
821 - it("contains exact Nugu tokens, version, components, and responsive contracts", () => {
822 - const css = readFileSync(
823 - path.resolve(import.meta.dirname, "../assets/system.css"),
824 - "utf8",
256 + it("indexes references, ignores unknown fields, and suppresses baseline findings", () => {
257 + const current = [
258 + markdownSource(
259 + "specs",
260 + "PX-SPEC-001",
261 + "one",
262 + "id: PX-SPEC-001\ntype: spec\nrelated: PX-SPEC-404",
263 + ),
264 + markdownSource(
265 + "roadmaps",
266 + "PX-ROADMAP-001",
267 + "delivery",
268 + "id: PX-ROADMAP-001\ntype: roadmap\nspec: PX-SPEC-001",
269 + ),
270 + ];
271 + assert.deepEqual(indexBundleDocuments(current, "PX").diagnostics, []);
272 + const candidate = markdownSource(
273 + "specs",
274 + "PX-SPEC-001",
275 + "one",
276 + "id: PX-SPEC-002\ntype: spec",
277 + );
278 + assert.deepEqual(
279 + validateBundleCandidate(current, candidate, "PX").map(
280 + (item) => `${item.path} ${item.code}`,
281 + ),
283 + ".system/roadmaps/PX-ROADMAP-001-delivery/index.md graph.dangling-reference",
284 + ".system/specs/PX-SPEC-001-one/index.md document.path",
285 + ],
826 - for (const token of [
827 - "The System styleVersion: 1",
828 - "--fg: #121212",
829 - "--page: #ededed",
830 - "--panel: #dbdbdb",
831 - "--accent: #ae2eae",
832 - "--ui-accent: #922792",
833 - "--minor: #3b3b3b",
834 - "--focus: #184e5b",
835 - "--important: #4f3c69",
836 - "--error: #bd172e",
837 - "--warning: #6e6c10",
838 - "--info: #116477",
839 - "--fg: #ededed",
840 - "--page: #121212",
841 - "--panel: #242424",
842 - "--accent: #d151d1",
843 - "--ui-accent: #d86dd8",
844 - "--minor: #8b8b8b",
845 - "--focus: #7ba1aa",
846 - "--important: #dfd3f3",
847 - "--error: #ec6376",
848 - "--warning: #f0ee69",
849 - "--info: #3ec5e3",
850 - ".doc",
851 - ".mast",
852 - ".grid",
853 - ".section",
854 - ".contract",
855 - ".callout",
856 - ".flow",
857 - ".metadata",
858 - ".status",
859 - ".document-nav",
860 - "table",
861 - "pre",
862 - "overflow-wrap: anywhere",
863 - "@media (max-width: 560px)",
864 - ])
865 - assert.ok(css.includes(token), `missing CSS contract: ${token}`);
866 - assert.doesNotMatch(css, /@import|url\s*\(|https?:\/\//i);

extensions/the-system/__tests__/init.test.ts

Modified
16 16 import { SystemDocumentError } from "../documents.ts";
17 17 import {
18 18 applyInitialization,
19 - DEFAULT_MACHINE_ASSETS,
20 19 inspectInitialization,
21 - type MachineAssets,
20 + type MachineState,
22 21 } from "../init.ts";
24 23 const roots: string[] = [];
28 27 mkdirSync(path.join(value, ".git"));
29 28 return value;
31 -const write = (root: string, relative: string, content: string) => {
32 - const target = path.join(root, relative);
30 +const write = (project: string, relative: string, content: string) => {
31 + const target = path.join(project, relative);
33 32 mkdirSync(path.dirname(target), { recursive: true });
34 33 writeFileSync(target, content, "utf8");
36 -const cores = (root: string) => {
37 - write(root, ".system/SYSTEM.md", "# System\n\nApproved topology.\n");
38 - write(root, ".system/MISSION.md", "# Mission\n\nApproved purpose.\n");
39 - write(root, ".system/RULES.md", "# Rules\n\nApproved constraints.\n");
40 -};
41 -const future: MachineAssets = {
42 - schemaVersion: 2,
43 - styleVersion: 2,
44 - css: "/* The System styleVersion: 2 */\n.future {}\n",
35 +const cores = (project: string) => {
36 + for (const name of ["SYSTEM.md", "MISSION.md", "RULES.md"])
37 + write(project, `.system/${name}`, `# ${name}\n\nApproved.\n`);
39 +const legacy = '{ "prefix": "PX", "schemaVersion": 1, "styleVersion": 1 }\n';
40 +const future: MachineState = { schemaVersion: 3 };
46 41 afterEach(() => {
47 42 for (const value of roots.splice(0))
48 43 rmSync(value, { recursive: true, force: true });
51 46 describe("guided initialization machine state", () => {
52 - it("copies current machine assets to the discovered root", () => {
47 + it("creates only schema-v2 config and preserves cores on rerun", () => {
53 48 const project = root();
54 49 const cwd = path.join(project, "packages", "app");
55 50 mkdirSync(cwd, { recursive: true });
57 52 const child = spawnSync(
58 53 process.execPath,
59 54 ["--experimental-strip-types", script, "apply", cwd, "PX"],
60 - {
61 - encoding: "utf8",
62 - env: { ...process.env, NODE_NO_WARNINGS: "1" },
63 - },
55 + { encoding: "utf8", env: { ...process.env, NODE_NO_WARNINGS: "1" } },
65 57 assert.equal(child.status, 0);
66 - assert.equal(child.stderr, "");
67 - assert.equal(
68 - child.stdout,
69 - [
70 - `ROOT ${project}`,
71 - "PREFIX PX",
72 - "WROTE .system",
73 - "WROTE .system/specs",
74 - "WROTE .system/roadmaps",
75 - "WROTE .system/plans",
76 - "WROTE .system/issues",
77 - "WROTE .system/research",
78 - "WROTE .system/config.json",
79 - "WROTE .system/system.css",
80 - "OK machine state applied",
81 - "",
82 - ].join("\n"),
83 - );
58 + assert.match(child.stdout, /WROTE \.system\/config\.json/);
59 + assert.doesNotMatch(child.stdout, /system\.css/);
84 60 assert.equal(
85 61 readFileSync(path.join(project, ".system/config.json"), "utf8"),
86 - '{\n\t"prefix": "PX",\n\t"schemaVersion": 1,\n\t"styleVersion": 1\n}\n',
62 + '{\n\t"prefix": "PX",\n\t"schemaVersion": 2\n}\n',
88 64 assert.equal(
89 - readFileSync(path.join(project, ".system/system.css"), "utf8"),
90 - DEFAULT_MACHINE_ASSETS.css,
91 - );
92 - assert.deepEqual(
93 - inspectInitialization(project, "PX").cores.map((item) => item.state),
94 - ["missing", "missing", "missing"],
95 - );
96 - });
98 - it("becomes doctor-green and preserves all bytes and mtimes on rerun", () => {
99 - const project = root();
100 - applyInitialization(project, "PX");
101 - cores(project);
102 - const paths = [
103 - "config.json",
104 - "system.css",
105 - "SYSTEM.md",
106 - "MISSION.md",
107 - "RULES.md",
108 - ];
109 - const before = new Map(
110 - paths.map((name) => {
111 - const target = path.join(project, ".system", name);
112 - return [
113 - name,
114 - [readFileSync(target, "utf8"), lstatSync(target).mtimeMs] as const,
115 - ];
65 + lstatSync(path.join(project, ".system/system.css"), {
66 + throwIfNoEntry: false,
68 + undefined,
118 - const repeated = applyInitialization(project, "PX");
119 - assert.deepEqual(repeated, {
70 + cores(project);
71 + const before = ["SYSTEM.md", "MISSION.md", "RULES.md"].map((name) => {
72 + const target = path.join(project, ".system", name);
73 + return [name, readFileSync(target, "utf8"), lstatSync(target).mtimeMs];
74 + });
75 + assert.deepEqual(applyInitialization(project, "PX"), {
120 76 root: project,
121 77 prefix: "PX",
122 78 changed: [],
79 + removed: [],
123 80 pending: [],
125 - assert.deepEqual(
126 - inspectInitialization(project, "PX").cores.map((item) => item.state),
127 - ["preserve", "preserve", "preserve"],
128 - );
129 - for (const name of paths) {
82 + for (const [name, source, mtime] of before) {
130 83 const target = path.join(project, ".system", name);
131 84 assert.deepEqual(
132 85 [readFileSync(target, "utf8"), lstatSync(target).mtimeMs],
133 - before.get(name),
86 + [source, mtime],
136 89 assert.equal(runDoctor(project).exitCode, 0);
139 - it("reports machine upgrades and applies them only with approval", () => {
92 + it("holds legacy config and CSS pending, then upgrades only when approved", () => {
140 93 const project = root();
141 - applyInitialization(project, "PX");
94 + write(project, ".system/config.json", legacy);
95 + write(project, ".system/system.css", "legacy css\n");
142 96 cores(project);
143 - const oldConfig = readFileSync(
144 - path.join(project, ".system/config.json"),
145 - "utf8",
146 - );
147 - const oldCss = readFileSync(
148 - path.join(project, ".system/system.css"),
149 - "utf8",
150 - );
151 97 const upgrades = [
152 - ".system/config.json schemaVersion 1 -> 2, styleVersion 1 -> 2",
153 - ".system/system.css bundled styleVersion 2",
98 + ".system/config.json schemaVersion 1 -> 2; remove styleVersion",
99 + ".system/system.css remove obsolete machine-owned asset",
155 - assert.deepEqual(
156 - inspectInitialization(project, undefined, future).upgrades,
157 - upgrades,
158 - );
159 - assert.deepEqual(
160 - applyInitialization(project, undefined, false, future).pending,
161 - upgrades,
162 - );
101 + assert.deepEqual(inspectInitialization(project).upgrades, upgrades);
102 + assert.deepEqual(applyInitialization(project).pending, upgrades);
163 103 assert.equal(
164 104 readFileSync(path.join(project, ".system/config.json"), "utf8"),
165 - oldConfig,
105 + legacy,
167 107 assert.equal(
168 108 readFileSync(path.join(project, ".system/system.css"), "utf8"),
169 - oldCss,
170 - );
171 - assert.deepEqual(
172 - applyInitialization(project, undefined, true, future).changed,
173 - [".system/config.json", ".system/system.css"],
109 + "legacy css\n",
111 + const result = applyInitialization(project, undefined, true);
112 + assert.deepEqual(result.changed, [".system/config.json"]);
113 + assert.deepEqual(result.removed, [".system/system.css"]);
175 114 assert.equal(
176 - readFileSync(path.join(project, ".system/system.css"), "utf8"),
177 - future.css,
115 + lstatSync(path.join(project, ".system/system.css"), {
116 + throwIfNoEntry: false,
117 + }),
118 + undefined,
179 - for (const name of ["SYSTEM.md", "MISSION.md", "RULES.md"])
180 - assert.match(
181 - readFileSync(path.join(project, ".system", name), "utf8"),
182 - /Approved/,
183 - );
186 - it("fails on missing/invalid/conflicting prefixes, newer versions, and symlinks", () => {
122 + it("rejects invalid prefixes, newer configs, and unsafe obsolete CSS paths", () => {
187 123 const project = root();
188 - assert.throws(
189 - () => applyInitialization(project),
190 - (error: unknown) =>
191 - error instanceof SystemDocumentError &&
192 - error.code === "init.prefix-required",
193 - );
124 + assert.throws(() => applyInitialization(project), /prefix is required/i);
194 125 assert.throws(() => applyInitialization(project, "x"), SystemDocumentError);
195 126 applyInitialization(project, "PX");
196 127 assert.throws(
197 128 () => inspectInitialization(project, "AB"),
198 - (error: unknown) =>
199 - error instanceof SystemDocumentError &&
200 - error.code === "init.prefix-conflict",
201 - );
202 - write(
203 - project,
204 - ".system/config.json",
205 - '{"prefix":"PX","schemaVersion":3,"styleVersion":1}',
129 + /prefix.*does not match/i,
131 + write(project, ".system/config.json", '{"prefix":"PX","schemaVersion":4}');
207 132 assert.throws(
208 133 () => inspectInitialization(project, undefined, future),
209 - (error: unknown) =>
210 - error instanceof SystemDocumentError &&
211 - error.code === "init.version-newer",
134 + /newer/i,
214 137 const linked = root();
215 - const outside = mkdtempSync(
216 - path.join(tmpdir(), "the-system-init-outside-"),
217 - );
218 - roots.push(outside);
219 - symlinkSync(outside, path.join(linked, ".system"), "dir");
138 + write(linked, ".system/config.json", legacy);
139 + symlinkSync("elsewhere.css", path.join(linked, ".system/system.css"));
220 140 assert.throws(
221 - () => inspectInitialization(linked, "PX"),
141 + () => inspectInitialization(linked),
222 142 (error: unknown) =>
223 143 error instanceof SystemDocumentError &&
224 144 error.code === "init.unsafe-path",

extensions/the-system/__tests__/system.test.ts

Modified
2 2 import assert from "node:assert/strict";
3 3 import {
4 4 mkdirSync,
5 5 mkdtempSync,
6 - readFileSync,
7 6 rmSync,
8 7 symlinkSync,
9 8 writeFileSync,
10 9 import { tmpdir } from "node:os";
11 10 import path from "node:path";
12 11 import { afterEach, describe, it } from "vitest";
13 -import { createTestSession, type TestSession } from "../../../test/harness.ts";
14 12 import { applyInitialization } from "../init.ts";
15 -import { CORE_BYTE_LIMIT, composeSystemPrompt } from "../system.ts";
13 +import {
14 + CORE_BYTE_LIMIT,
15 + composeSystemPrompt,
16 + preflightFileMutation,
17 + preflightShellMutation,
18 +} from "../system.ts";
17 -const temporary: string[] = [];
18 -const sessions: TestSession[] = [];
19 -const extensionPath = path.resolve(import.meta.dirname, "../index.ts");
20 -const makeDirectory = (prefix: string) => {
21 - const value = mkdtempSync(path.join(tmpdir(), prefix));
22 - temporary.push(value);
20 +const roots: string[] = [];
21 +const root = () => {
22 + const value = mkdtempSync(path.join(tmpdir(), "the-system-runtime-"));
23 + roots.push(value);
24 + mkdirSync(path.join(value, ".git"));
25 + applyInitialization(value, "PX");
26 + for (const name of ["SYSTEM.md", "MISSION.md", "RULES.md"])
27 + write(value, `.system/${name}`, `# ${name}\n\nApproved.\n`);
23 28 return value;
25 30 const write = (root: string, relative: string, content: string) => {
27 32 mkdirSync(path.dirname(target), { recursive: true });
28 33 writeFileSync(target, content, "utf8");
30 -const writeCores = (root: string, label: string) => {
31 - write(root, ".system/SYSTEM.md", `# System\n\n${label} topology.\n`);
32 - write(root, ".system/MISSION.md", `# Mission\n\n${label} purpose.\n`);
33 - write(root, ".system/RULES.md", `# Rules\n\n${label} constraints.\n`);
34 -};
35 -const documentShell = (id: string, metadata?: string) => `<!doctype html>
36 -<html lang="en"><head><meta charset="utf-8">
37 -<meta name="viewport" content="width=device-width, initial-scale=1">
38 -<title>${id}</title><link rel="stylesheet" href="../system.css"></head>
39 -<body><header><h1>${id}</h1></header><main><section><h2>Contract</h2><p>Approved.</p></section></main>${
40 - metadata
41 - ? `
42 -<script type="application/json" id="system-meta">${metadata}</script>`
43 - : ""
44 -}</body></html>`;
45 -const shell = (id: string) => documentShell(id, `{"id":"${id}","type":"spec"}`);
46 -const writeSpec = (root: string, id = "PX-SPEC-001", slug = "contract") => {
47 - const relative = `.system/specs/${id}-${slug}.html`;
48 - write(root, relative, shell(id));
35 +const documentSource = (metadata: Record<string, string | readonly string[]>) =>
36 + `---\n${Object.entries(metadata)
37 + .map(
38 + ([key, value]) =>
39 + `${key}: ${Array.isArray(value) ? `[${value.join(", ")}]` : value}`,
40 + )
41 + .join("\n")}\n---\n\n# Contract\n\nApproved.\n`;
42 +const writeSpec = (project: string) => {
43 + const relative = ".system/specs/PX-SPEC-001-contract/index.md";
44 + write(project, relative, documentSource({ id: "PX-SPEC-001", type: "spec" }));
49 45 return relative;
51 -const initialized = () => {
52 - const root = makeDirectory("the-system-runtime-");
53 - mkdirSync(path.join(root, ".git"));
54 - applyInitialization(root, "PX");
55 - writeCores(root, "root");
56 - return root;
57 -};
47 +const approval = (hasUI = true) => ({
48 + hasUI,
49 + select: async (_title: string, items: string[]) => items[0],
50 +});
58 51 afterEach(() => {
59 - for (const session of sessions.splice(0)) session.dispose();
60 - for (const root of temporary.splice(0))
61 - rmSync(root, { recursive: true, force: true });
52 + for (const value of roots.splice(0))
53 + rmSync(value, { recursive: true, force: true });
64 56 describe("runtime core injection", () => {
65 - it("appends existing cores in stable order and marks an oversized core", () => {
66 - const root = initialized();
67 - write(root, ".system/MISSION.md", "x".repeat(CORE_BYTE_LIMIT + 1));
68 - const prompt = composeSystemPrompt(root, "BASE");
69 - assert.ok(prompt.startsWith("BASE\n\n# The System project law"));
70 - assert.ok(prompt.indexOf("## SYSTEM.md") < prompt.indexOf("## MISSION.md"));
71 - assert.ok(prompt.indexOf("## MISSION.md") < prompt.indexOf("## RULES.md"));
72 - assert.match(prompt, /MISSION\.md exceeds the 32768-byte injection limit/);
73 - assert.match(prompt, /root topology/);
74 - assert.match(prompt, /root constraints/);
75 - });
77 - it("omits absent cores rather than inventing defaults", () => {
78 - const root = makeDirectory("the-system-runtime-empty-");
79 - write(root, ".system/RULES.md", "# Rules\n\nOnly existing truth.\n");
80 - const prompt = composeSystemPrompt(root, "BASE");
81 - assert.doesNotMatch(prompt, /## SYSTEM\.md|## MISSION\.md/);
82 - assert.match(prompt, /## RULES\.md[\s\S]*Only existing truth/);
83 - });
85 - it("returns a governance error block for malformed core paths", () => {
86 - const root = initialized();
87 - rmSync(path.join(root, ".system/SYSTEM.md"));
88 - mkdirSync(path.join(root, ".system/SYSTEM.md"));
89 - const prompt = composeSystemPrompt(root, "BASE");
90 - assert.match(prompt, /# The System governance error/);
91 - assert.match(prompt, /Malformed core path \.system\/SYSTEM\.md/);
92 - assert.match(prompt, /Do not mutate \.system/);
93 - });
95 - it("resolves the root again for every before_agent_start event", async () => {
96 - const parent = makeDirectory("the-system-root-change-");
97 - const cwd = path.join(parent, "packages", "app");
98 - mkdirSync(cwd, { recursive: true });
99 - writeCores(cwd, "nested");
100 - const t = await createTestSession({ cwd, extensions: [extensionPath] });
101 - sessions.push(t);
102 - const first = await t.session.extensionRunner.emitBeforeAgentStart(
103 - "first",
104 - undefined,
105 - "BASE",
106 - {},
107 - );
108 - assert.match(first?.systemPrompt ?? "", /nested topology/);
109 - mkdirSync(path.join(parent, ".git"));
110 - writeCores(parent, "parent");
111 - const second = await t.session.extensionRunner.emitBeforeAgentStart(
112 - "second",
113 - undefined,
114 - "BASE",
115 - {},
116 - );
117 - assert.match(second?.systemPrompt ?? "", /parent topology/);
118 - assert.doesNotMatch(second?.systemPrompt ?? "", /nested topology/);
57 + it("injects cores and reports malformed core paths", () => {
58 + const project = root();
59 + write(project, ".system/MISSION.md", "x".repeat(CORE_BYTE_LIMIT + 1));
60 + assert.match(composeSystemPrompt(project, "BASE"), /MISSION\.md exceeds/);
61 + rmSync(path.join(project, ".system/SYSTEM.md"));
62 + mkdirSync(path.join(project, ".system/SYSTEM.md"));
63 + assert.match(composeSystemPrompt(project, "BASE"), /governance error/);
122 -describe("runtime readiness notice", () => {
123 - it("notifies once per session when initialization is incomplete", async () => {
124 - const root = makeDirectory("the-system-notice-");
125 - mkdirSync(path.join(root, ".git"));
126 - const t = await createTestSession({
127 - cwd: root,
128 - extensions: [extensionPath],
129 - });
130 - sessions.push(t);
131 - await t.session.extensionRunner.emitBeforeAgentStart(
132 - "one",
133 - undefined,
134 - "BASE",
135 - {},
136 - );
137 - await t.session.extensionRunner.emitBeforeAgentStart(
138 - "two",
139 - undefined,
140 - "BASE",
141 - {},
142 - );
143 - const notices = t.events
144 - .uiCallsFor("notify")
145 - .filter((call) => String(call.args[0]).includes("/system-init"));
146 - assert.equal(notices.length, 1);
147 - assert.match(String(notices[0]?.args[0]), /incomplete or invalid/);
148 - });
150 - it("stays silent for a doctor-green initialized project", async () => {
151 - const root = initialized();
152 - const t = await createTestSession({
153 - cwd: root,
154 - extensions: [extensionPath],
155 - });
156 - sessions.push(t);
157 - await t.session.extensionRunner.emitBeforeAgentStart(
158 - "one",
159 - undefined,
160 - "BASE",
161 - {},
162 - );
163 - assert.equal(
164 - t.events
165 - .uiCallsFor("notify")
166 - .filter((call) => String(call.args[0]).includes("/system-init")).length,
167 - 0,
168 - );
169 - });
170 -});
172 -describe("runtime write and edit governance", () => {
173 - it("blocks write/edit of existing cores and permits approved missing-core creation", async () => {
174 - const root = initialized();
175 - const t = await createTestSession({
176 - cwd: root,
177 - extensions: [extensionPath],
178 - });
179 - sessions.push(t);
180 - for (const event of [
181 - {
182 - type: "tool_call",
183 - toolCallId: "w",
184 - toolName: "write",
185 - input: { path: ".system/RULES.md", content: "replacement" },
186 - },
187 - {
188 - type: "tool_call",
189 - toolCallId: "e",
190 - toolName: "edit",
191 - input: {
192 - path: ".system/MISSION.md",
193 - edits: [{ oldText: "root", newText: "agent" }],
194 - },
195 - },
196 - ] as const) {
197 - const result = await t.session.extensionRunner.emitToolCall(event);
198 - assert.equal(result?.block, true);
199 - assert.match(result?.reason ?? "", /human-owned core/);
200 - }
201 - rmSync(path.join(root, ".system/SYSTEM.md"));
202 - const creation = await t.session.extensionRunner.emitToolCall({
203 - type: "tool_call",
204 - toolCallId: "new-core",
205 - toolName: "write",
206 - input: {
207 - path: ".system/SYSTEM.md",
208 - content: "# System\n\nHuman-approved.\n",
209 - },
210 - });
211 - assert.equal(creation?.block, undefined);
212 - });
214 - it("rejects symbolic-link governed targets and ancestors before allowing a write", async () => {
215 - const root = initialized();
216 - const system = await import("../system.ts");
217 - rmSync(path.join(root, ".system/SYSTEM.md"));
218 - symlinkSync("missing-core.md", path.join(root, ".system/SYSTEM.md"));
219 - const danglingCore = await system.preflightFileMutation(
220 - root,
221 - "write",
222 - { path: ".system/SYSTEM.md", content: "replacement" },
223 - { hasUI: true, select: async () => undefined },
224 - );
225 - assert.equal(danglingCore?.block, true);
226 - assert.match(danglingCore?.reason ?? "", /symbolic link/i);
228 - rmSync(path.join(root, ".system/specs"), { recursive: true });
229 - const outside = makeDirectory("the-system-linked-specs-");
230 - symlinkSync(outside, path.join(root, ".system/specs"), "dir");
231 - const linkedDirectory = await system.preflightFileMutation(
232 - root,
67 +describe("runtime bundle governance", () => {
68 + it("allows valid new index candidates and blocks invalid layouts and metadata before approval", async () => {
69 + const project = root();
70 + const valid = await preflightFileMutation(
71 + project,
233 72 "write",
235 - path: ".system/specs/PX-SPEC-001-contract.html",
236 - content: shell("PX-SPEC-001"),
74 + path: ".system/specs/PX-SPEC-001-contract/index.md",
75 + content: documentSource({ id: "PX-SPEC-001", type: "spec" }),
238 - { hasUI: true, select: async () => undefined },
77 + approval(),
240 - assert.equal(linkedDirectory?.block, true);
241 - assert.match(linkedDirectory?.reason ?? "", /symbolic link/i);
242 - });
244 - it("allows a valid new spec without a redundant UI gate and blocks an invalid candidate", async () => {
245 - const root = initialized();
246 - const t = await createTestSession({
247 - cwd: root,
248 - extensions: [extensionPath],
249 - });
250 - sessions.push(t);
251 - const valid = await t.session.extensionRunner.emitToolCall({
252 - type: "tool_call",
253 - toolCallId: "valid",
254 - toolName: "write",
255 - input: {
256 - path: ".system/specs/PX-SPEC-001-contract.html",
257 - content: shell("PX-SPEC-001"),
258 - },
259 - });
260 79 assert.equal(valid?.block, undefined);
261 - assert.equal(t.events.uiCallsFor("select").length, 0);
262 - const invalid = await t.session.extensionRunner.emitToolCall({
263 - type: "tool_call",
264 - toolCallId: "invalid",
265 - toolName: "write",
266 - input: {
267 - path: ".system/specs/PX-SPEC-002-broken.html",
268 - content: "<html>broken</html>",
269 - },
270 - });
271 - assert.equal(invalid?.block, true);
272 - assert.match(invalid?.reason ?? "", /candidate validation failed/);
273 - });
275 - it("requires authored documents directly inside their matching directory", async () => {
276 - const root = initialized();
277 - const system = await import("../system.ts");
278 - const result = await system.preflightFileMutation(
279 - root,
280 - "write",
80 + for (const input of [
282 - path: ".system/specs/nested/PX-SPEC-001-contract.html",
283 - content: shell("PX-SPEC-001"),
82 + path: ".system/specs/PX-SPEC-002-broken/index.md",
83 + content: "# no frontmatter",
285 - { hasUI: true, select: async () => undefined },
286 - );
287 - assert.equal(result?.block, true);
288 - assert.match(result?.reason ?? "", /directly inside/);
289 - });
291 - it.each([
292 - ["approve", (items: string[]) => items[0], false, /./],
293 - ["deny", (items: string[]) => items[1], true, /denied/],
294 - ["cancel", () => undefined, true, /cancelled/],
295 - ] as const)("handles UI %s for an existing spec", async (_name, choose, blocked, reason) => {
296 - const root = initialized();
297 - const relative = writeSpec(root);
298 - const t = await createTestSession({
299 - cwd: root,
300 - extensions: [extensionPath],
301 - mockUI: { select: (_title, items) => choose(items) },
302 - });
303 - sessions.push(t);
304 - const result = await t.session.extensionRunner.emitToolCall({
305 - type: "tool_call",
306 - toolCallId: "edit",
307 - toolName: "edit",
308 - input: {
309 - path: relative,
310 - edits: [{ oldText: "Approved.", newText: "Approved and reviewed." }],
311 - },
312 - });
313 - assert.equal(result?.block === true, blocked);
314 - if (blocked) assert.match(result?.reason ?? "", reason);
315 - assert.equal(t.events.uiCallsFor("select").length, 1);
316 - });
318 - it("fails closed without UI and validates the computed edit candidate first", async () => {
319 - const root = initialized();
320 - const relative = writeSpec(root);
321 - const system = await import("../system.ts");
322 - const result = await system.preflightFileMutation(
323 - root,
324 - "edit",
326 - path: relative,
327 - edits: [{ oldText: "Approved.", newText: "Reviewed." }],
86 + path: ".system/specs/PX-SPEC-002-broken.md",
87 + content: "# loose document",
329 - { hasUI: false, select: async () => undefined },
330 - );
331 - assert.equal(result?.block, true);
332 - assert.match(result?.reason ?? "", /interactive UI is unavailable/);
333 - const invalid = await system.preflightFileMutation(
334 - root,
335 - "edit",
336 - { path: relative, edits: [{ oldText: "</main>", newText: "" }] },
337 - { hasUI: true, select: async (_title, items) => items[0] },
338 - );
339 - assert.equal(invalid?.block, true);
340 - assert.match(invalid?.reason ?? "", /candidate validation failed/);
341 - });
343 - it("classifies metadata-bearing mockup slugs as specs and metadata-free files as mockups", async () => {
344 - const root = initialized();
345 - const system = await import("../system.ts");
346 - const specNamedLikeMockup = await system.preflightFileMutation(
347 - root,
348 - "write",
349 - {
350 - path: ".system/specs/PX-SPEC-002-contract-mockup-mobile.html",
351 - content: shell("PX-SPEC-002"),
352 - },
353 - { hasUI: true, select: async () => undefined },
354 - );
355 - assert.equal(specNamedLikeMockup?.block, undefined);
357 - writeSpec(root);
358 - const mockup = ".system/specs/PX-SPEC-001-contract-mockup-mobile.html";
359 - write(root, mockup, documentShell("mockup"));
360 - let approvals = 0;
361 - const metadataFreeMockup = await system.preflightFileMutation(
362 - root,
363 - "write",
364 - { path: mockup, content: documentShell("mockup") },
365 - {
366 - hasUI: true,
367 - select: async (_title, items) => {
368 - approvals += 1;
369 - return items[0];
370 - },
371 - },
372 - );
373 - assert.equal(metadataFreeMockup?.block, undefined);
374 - assert.equal(approvals, 1);
375 - });
377 - it("preflights every document type but only requests ownership approval for specs and mockups", async () => {
378 - const root = initialized();
379 - writeSpec(root);
380 - const system = await import("../system.ts");
381 - for (const [directory, id, metadata] of [
382 - [
383 - "roadmaps",
384 - "PX-ROADMAP-001",
385 - '{"id":"PX-ROADMAP-001","type":"roadmap","spec":"PX-SPEC-001"}',
386 - ],
387 - [
388 - "plans",
389 - "PX-PLAN-001",
390 - '{"id":"PX-PLAN-001","type":"plan","spec":"PX-SPEC-001"}',
391 - ],
392 - [
393 - "issues",
394 - "PX-ISSUE-001",
395 - '{"id":"PX-ISSUE-001","type":"issue","status":"open","specs":[]}',
396 - ],
397 - [
398 - "research",
399 - "PX-RESEARCH-001",
400 - '{"id":"PX-RESEARCH-001","type":"research","capturedAt":"2026-07-15"}',
401 - ],
402 - ] as const) {
403 - const relative = `.system/${directory}/${id}-delivery.html`;
404 - const invalid = await system.preflightFileMutation(
405 - root,
89 + { path: ".system/specs/loose.md", content: "x" },
90 + { path: ".system/specs/PX-SPEC-002-broken/other/index.md", content: "x" },
91 + ]) {
92 + const result = await preflightFileMutation(
93 + project,
406 94 "write",
407 - { path: relative, content: "<html>broken</html>" },
95 + input,
96 + approval(),
97 + );
98 + assert.equal(result?.block, true, input.path);
99 + assert.match(result?.reason ?? "", /bundle|candidate validation/i);
101 + });
103 + it("requires a valid index before assets and approves every existing spec file", async () => {
104 + const project = root();
105 + const asset = ".system/specs/PX-SPEC-001-contract/evidence/data.csv";
106 + assert.equal(
108 + await preflightFileMutation(
109 + project,
110 + "write",
111 + { path: asset, content: "a,b" },
112 + approval(),
114 + )?.block,
115 + true,
116 + );
117 + const index = writeSpec(project);
118 + assert.equal(
120 + await preflightFileMutation(
121 + project,
122 + "write",
123 + { path: asset, content: "a,b" },
124 + approval(),
126 + )?.block,
127 + undefined,
128 + );
129 + const nestedIndex = await preflightFileMutation(
130 + project,
131 + "write",
133 + path: ".system/specs/PX-SPEC-001-contract/other/index.md",
134 + content: documentSource({ id: "PX-SPEC-001", type: "spec" }),
135 + },
136 + approval(),
137 + );
138 + assert.equal(nestedIndex?.block, true);
139 + assert.match(nestedIndex?.reason ?? "", /document bundles/);
140 + for (const relative of [
141 + index,
142 + ".system/specs/PX-SPEC-001-contract/mockup-mobile.html",
143 + ".system/specs/PX-SPEC-001-contract/diagram.svg",
144 + asset,
145 + ]) {
146 + write(
147 + project,
148 + relative,
149 + relative === index
150 + ? documentSource({ id: "PX-SPEC-001", type: "spec" })
151 + : "existing",
152 + );
153 + let approvals = 0;
154 + const result = await preflightFileMutation(
155 + project,
156 + "write",
158 + path: relative,
159 + content:
160 + relative === index
161 + ? documentSource({ id: "PX-SPEC-001", type: "spec" })
162 + : "replacement",
163 + },
409 165 hasUI: true,
410 - select: async () => {
411 - throw new Error("unexpected approval");
166 + select: async (_title, items) => {
167 + approvals += 1;
168 + return items[0];
415 - assert.equal(invalid?.block, true, directory);
416 - assert.match(invalid?.reason ?? "", /candidate validation failed/);
172 + assert.equal(result?.block, undefined, relative);
173 + assert.equal(approvals, 1, relative);
175 + const closed = await preflightFileMutation(
176 + project,
177 + "write",
178 + { path: asset, content: "replacement" },
179 + approval(false),
180 + );
181 + assert.equal(closed?.block, true);
182 + assert.match(closed?.reason ?? "", /interactive UI/);
183 + });
418 - write(root, relative, documentShell(id, metadata));
419 - const existing = await system.preflightFileMutation(
420 - root,
185 + it("validates existing non-spec indexes without ownership approval and rejects symlinks", async () => {
186 + const project = root();
187 + writeSpec(project);
188 + for (const [relative, metadata] of [
190 + ".system/roadmaps/PX-ROADMAP-001-delivery/index.md",
191 + { id: "PX-ROADMAP-001", type: "roadmap", spec: "PX-SPEC-001" },
192 + ],
194 + ".system/plans/PX-PLAN-001-delivery/index.md",
195 + { id: "PX-PLAN-001", type: "plan", spec: "PX-SPEC-001" },
196 + ],
198 + ".system/issues/PX-ISSUE-001-delivery/index.md",
200 + id: "PX-ISSUE-001",
201 + type: "issue",
202 + status: "open",
203 + specs: ["PX-SPEC-001"],
204 + },
205 + ],
207 + ".system/research/PX-RESEARCH-001-delivery/index.md",
208 + { id: "PX-RESEARCH-001", type: "research", capturedAt: "2026-07-16" },
209 + ],
210 + ] as const) {
211 + write(project, relative, documentSource(metadata));
212 + const result = await preflightFileMutation(
213 + project,
421 214 "edit",
423 216 path: relative,
433 - assert.equal(existing?.block, undefined, directory);
226 + assert.equal(result?.block, undefined, relative);
228 + symlinkSync(
229 + "missing.md",
230 + path.join(project, ".system/specs/PX-SPEC-002-link"),
231 + );
232 + const linked = await preflightFileMutation(
233 + project,
234 + "write",
236 + path: ".system/specs/PX-SPEC-002-link/index.md",
237 + content: documentSource({ id: "PX-SPEC-002", type: "spec" }),
238 + },
239 + approval(),
240 + );
241 + assert.equal(linked?.block, true);
242 + assert.match(linked?.reason ?? "", /symbolic link/i);
437 - it("permits a valid new spec-owned mockup and gates an existing one", async () => {
438 - const root = initialized();
439 - const owner = writeSpec(root);
440 - assert.ok(
441 - readFileSync(path.join(root, owner), "utf8").includes("PX-SPEC-001"),
442 - );
443 - const mockup = ".system/specs/PX-SPEC-001-contract-mockup-mobile.html";
444 - const t = await createTestSession({
445 - cwd: root,
446 - extensions: [extensionPath],
447 - mockUI: { select: () => undefined },
448 - });
449 - sessions.push(t);
450 - const first = await t.session.extensionRunner.emitToolCall({
451 - type: "tool_call",
452 - toolCallId: "new-mockup",
453 - toolName: "write",
454 - input: { path: mockup, content: documentShell("mockup") },
455 - });
456 - assert.equal(first?.block, undefined);
457 - write(root, mockup, documentShell("mockup"));
458 - const second = await t.session.extensionRunner.emitToolCall({
459 - type: "tool_call",
460 - toolCallId: "old-mockup",
461 - toolName: "write",
462 - input: {
463 - path: mockup,
464 - content: documentShell("mockup").replace("Approved.", "Reviewed."),
245 + it("validates computed edits before approval", async () => {
246 + const project = root();
247 + const relative = writeSpec(project);
248 + const result = await preflightFileMutation(
249 + project,
250 + "edit",
252 + path: relative,
253 + edits: [{ oldText: "id: PX-SPEC-001", newText: "id: PX-SPEC-002" }],
466 - });
467 - assert.equal(second?.block, true);
468 - assert.match(second?.reason ?? "", /cancelled/);
255 + approval(),
256 + );
257 + assert.equal(result?.block, true);
258 + assert.match(result?.reason ?? "", /candidate validation/i);
472 262 describe("runtime shell advisory guard", () => {
473 263 it.each([
474 264 "printf replacement > .system/RULES.md",
475 - "sed -i 's/Approved/Changed/' .system/specs/PX-SPEC-001-contract.html",
476 - "rm .system/specs/PX-SPEC-001-contract-mockup-mobile.html",
477 - ])("blocks recognizable owned mutation: %s", async (command) => {
478 - const root = initialized();
479 - writeSpec(root);
480 - const t = await createTestSession({
481 - cwd: root,
482 - extensions: [extensionPath],
483 - });
484 - sessions.push(t);
485 - const result = await t.session.extensionRunner.emitToolCall({
486 - type: "tool_call",
487 - toolCallId: "bash",
488 - toolName: "bash",
489 - input: { command },
490 - });
265 + "sed -i 's/Approved/Changed/' .system/specs/PX-SPEC-001-contract/index.md",
266 + "rm .system/specs/PX-SPEC-001-contract/evidence/data.csv",
267 + "rm -rf .system/specs/PX-SPEC-001-contract",
268 + ])("blocks recognizable owned mutation: %s", (command) => {
269 + const result = preflightShellMutation(command);
491 270 assert.equal(result?.block, true);
492 - assert.match(result?.reason ?? "", /advisory shell guard/);
493 271 assert.match(result?.reason ?? "", /not a sandbox/);
494 - assert.match(result?.reason ?? "", /use write or edit/i);
497 273 it.each([
498 274 "cat .system/RULES.md",
499 275 "printf report > build/report.txt",
500 276 "git status --short",
501 - ])("allows a command without a recognizable owned mutation: %s", async (command) => {
502 - const root = initialized();
503 - const t = await createTestSession({
504 - cwd: root,
505 - extensions: [extensionPath],
506 - });
507 - sessions.push(t);
508 - const result = await t.session.extensionRunner.emitToolCall({
509 - type: "tool_call",
510 - toolCallId: "bash-safe",
511 - toolName: "bash",
512 - input: { command },
513 - });
514 - assert.equal(result?.block, undefined);
277 + ])("allows safe shell command: %s", (command) => {
278 + assert.equal(preflightShellMutation(command), undefined);

extensions/the-system/assets/system.css

Deleted
deleted file mode 100644
1 -/* The System styleVersion: 1 */
2 -:root {
3 - color-scheme: light dark;
4 - --fg: #121212;
5 - --page: #ededed;
6 - --panel: #dbdbdb;
7 - --accent: #ae2eae;
8 - --ui-accent: #922792;
9 - --minor: #3b3b3b;
10 - --focus: #184e5b;
11 - --important: #4f3c69;
12 - --error: #bd172e;
13 - --warning: #6e6c10;
14 - --info: #116477;
15 - font-family: ui-monospace, SFMono-Regular, Consolas, monospace;
16 - color: var(--fg);
17 - background: var(--page);
19 -@media (prefers-color-scheme: dark) {
20 - :root {
21 - --fg: #ededed;
22 - --page: #121212;
23 - --panel: #242424;
24 - --accent: #d151d1;
25 - --ui-accent: #d86dd8;
26 - --minor: #8b8b8b;
27 - --focus: #7ba1aa;
28 - --important: #dfd3f3;
29 - --error: #ec6376;
30 - --warning: #f0ee69;
31 - --info: #3ec5e3;
32 - }
34 -* {
35 - box-sizing: border-box;
37 -body {
38 - margin: 0;
39 - padding: 1rem;
41 -.doc {
42 - background: var(--page);
43 - border: 3px solid var(--fg);
44 - box-shadow: 9px 9px 0 var(--ui-accent);
45 - max-width: 780px;
46 - margin: 0 auto;
48 -.mast {
49 - display: grid;
50 - grid-template-columns: minmax(0, 1fr) auto;
51 - gap: 1rem;
52 - padding: clamp(0.85rem, 3vw, 1.3rem);
53 - border-bottom: 3px solid var(--fg);
54 - background: var(--panel);
56 -.k {
57 - font-size: 0.7rem;
58 - font-weight: 900;
59 - letter-spacing: 0.16em;
60 - text-transform: uppercase;
61 - color: var(--accent);
63 -.mast h1 {
64 - margin: 0.2rem 0 0;
65 - font: 900 clamp(1.35rem, 5vw, 2.25rem) / 0.96 system-ui;
66 - text-transform: uppercase;
67 - overflow-wrap: anywhere;
69 -.id {
70 - border: 2px solid var(--fg);
71 - padding: 0.45rem;
72 - font-weight: 900;
73 - align-self: start;
74 - background: var(--page);
76 -.grid {
77 - display: grid;
78 - grid-template-columns: minmax(0, 1.15fr) minmax(0, 0.85fr);
80 -.section {
81 - padding: clamp(0.8rem, 2vw, 1.1rem);
82 - border-bottom: 2px solid var(--fg);
83 - min-width: 0;
85 -.section:nth-child(odd) {
86 - border-right: 2px solid var(--fg);
88 -.section h2 {
89 - font: 900 0.76rem / 1 system-ui;
90 - text-transform: uppercase;
91 - letter-spacing: 0.11em;
92 - margin: 0 0 0.75rem;
93 - color: var(--accent);
95 -.section p,
96 -.section li {
97 - font-size: 0.82rem;
98 - line-height: 1.55;
100 -.contract {
101 - background: var(--panel);
102 - color: var(--fg);
103 - padding: 0.8rem;
104 - border: 2px solid var(--fg);
105 - border-left: 7px solid var(--ui-accent);
106 - font-weight: 800;
108 -.flow {
109 - display: flex;
110 - align-items: center;
111 - gap: 0.35rem;
112 - flex-wrap: wrap;
114 -.node {
115 - border: 2px solid var(--fg);
116 - padding: 0.35rem 0.5rem;
117 - background: var(--panel);
118 - font-weight: 900;
120 -.arrow {
121 - font-size: 1.2rem;
122 - color: var(--accent);
124 -.note {
125 - border: 2px dashed var(--focus);
126 - padding: 0.65rem;
127 - color: var(--focus);
128 - background: var(--panel);
130 -@media (max-width: 560px) {
131 - body {
132 - padding: 0.5rem;
133 - }
134 - .doc {
135 - box-shadow: 5px 5px 0 var(--ui-accent);
136 - }
137 - .mast {
138 - grid-template-columns: 1fr;
139 - }
140 - .id {
141 - justify-self: start;
142 - }
143 - .grid {
144 - grid-template-columns: 1fr;
145 - }
146 - .section:nth-child(odd) {
147 - border-right: 0;
148 - }
149 - .flow {
150 - align-items: stretch;
151 - }
152 - .node {
153 - flex: 1;
154 - text-align: center;
155 - }
156 - .arrow {
157 - align-self: center;
158 - }
161 -/* Shared authored-document primitives. */
162 -a {
163 - color: var(--focus);
164 - font-weight: 800;
165 - overflow-wrap: anywhere;
167 -.document-nav {
168 - display: flex;
169 - flex-wrap: wrap;
170 - gap: 0.5rem;
171 - padding: 0.8rem;
172 - border-bottom: 2px solid var(--fg);
174 -.metadata {
175 - display: grid;
176 - grid-template-columns: repeat(auto-fit, minmax(9rem, 1fr));
177 - gap: 0.5rem;
178 - margin: 0;
179 - padding: 0.8rem;
180 - background: var(--panel);
181 - border: 2px solid var(--fg);
183 -.metadata dt {
184 - color: var(--accent);
185 - font-size: 0.7rem;
186 - font-weight: 900;
187 - letter-spacing: 0.12em;
188 - text-transform: uppercase;
190 -.metadata dd {
191 - margin: 0.2rem 0 0;
192 - overflow-wrap: anywhere;
194 -.callout {
195 - padding: 0.75rem;
196 - border: 2px solid var(--fg);
197 - border-left: 7px solid var(--info);
198 - background: var(--panel);
200 -.callout.important {
201 - border-left-color: var(--important);
203 -.callout.warning {
204 - border-left-color: var(--warning);
206 -.callout.error {
207 - border-left-color: var(--error);
209 -.status {
210 - display: inline-block;
211 - padding: 0.15rem 0.45rem;
212 - border: 2px solid currentColor;
213 - color: var(--info);
214 - font-size: 0.7rem;
215 - font-weight: 900;
216 - text-transform: uppercase;
218 -.status.open,
219 -.status.error {
220 - color: var(--error);
222 -.status.fixed {
223 - color: var(--focus);
225 -table {
226 - width: 100%;
227 - border-collapse: collapse;
229 -th,
230 -td {
231 - padding: 0.6rem;
232 - border: 2px solid var(--fg);
233 - text-align: left;
234 - vertical-align: top;
235 - overflow-wrap: anywhere;
237 -th {
238 - background: var(--panel);
240 -pre,
241 -code {
242 - background: var(--panel);
244 -code {
245 - padding: 0.1rem 0.3rem;
246 - overflow-wrap: anywhere;
248 -pre {
249 - max-width: 100%;
250 - padding: 0.8rem;
251 - overflow: auto;
252 - border-left: 7px solid var(--ui-accent);
254 -pre code {
255 - padding: 0;
257 -figure {
258 - max-width: 100%;
259 - margin: 1rem 0;
260 - overflow: auto;
262 -details {
263 - border: 2px solid var(--fg);
264 - padding: 0.65rem;
266 -summary {
267 - min-height: 2.75rem;
268 - cursor: pointer;
269 - font-weight: 900;
271 -@media (max-width: 560px) {
272 - .document-nav a {
273 - min-height: 2.75rem;
274 - display: inline-flex;
275 - align-items: center;
276 - }
277 - table,
278 - tbody,
279 - tr,
280 - th,
281 - td {
282 - display: block;
283 - width: 100%;
284 - }
285 - th {
286 - border-bottom: 0;
287 - }
288 - .metadata {
289 - grid-template-columns: 1fr;
290 - }

extensions/the-system/doctor.ts

Modified
1 -import { readdirSync, readFileSync, statSync } from "node:fs";
1 +import { lstatSync, readdirSync, readFileSync } from "node:fs";
2 2 import path from "node:path";
3 3 import {
4 4 type Diagnostic,
5 + discoverDocumentBundles,
5 6 discoverProjectRoot,
6 - indexDocuments,
7 - parseSystemConfig,
8 - SCHEMA_VERSION,
9 - STYLE_VERSION,
7 + indexBundleDocuments,
8 + inspectSystemConfig,
10 9 type SystemDocumentError,
11 - validateAuthoredHtml,
12 10 } from "./documents.ts";
14 12 export type TestReference = Readonly<{ path: string; spec: string }>;
29 27 ] as const;
30 28 const SYSTEM_FILES = [
31 29 ".system/config.json",
32 - ".system/system.css",
33 30 ".system/SYSTEM.md",
34 31 ".system/MISSION.md",
35 32 ".system/RULES.md",
36 33 ] as const;
37 -const DOCUMENT_DIRECTORIES = [
38 - "specs",
39 - "roadmaps",
40 - "plans",
41 - "issues",
42 - "research",
43 -] as const;
44 34 const TEST_DIRECTORIES = ["test", "tests", "__tests__"] as const;
45 35 const TEST_REFERENCE = /SYSTEM-SPEC:\s*([A-Z][A-Z0-9]{1,7}-SPEC-[0-9]{3,})/g;
46 -const MOCKUP = /^(.*)-mockup-[a-z0-9]+(?:-[a-z0-9]+)*\.html$/;
48 37 const diagnostic = (
49 38 code: string,
50 - path: string,
39 + diagnosticPath: string,
51 40 message: string,
52 -): Diagnostic => ({
53 - code,
54 - path,
55 - message,
56 -});
41 +): Diagnostic => ({ code, path: diagnosticPath, message });
57 42 const compareText = (left: string, right: string) =>
58 43 left < right ? -1 : left > right ? 1 : 0;
59 44 const compareDiagnostics = (left: Diagnostic, right: Diagnostic) =>
62 47 compareText(left.message, right.message);
63 48 const relativePath = (root: string, target: string) =>
64 49 path.relative(root, target).split(path.sep).join("/");
65 -const isDirectory = (target: string) => {
66 - try {
67 - return statSync(target, { throwIfNoEntry: false })?.isDirectory() === true;
68 - } catch {
69 - return false;
70 - }
71 -};
72 -const isFile = (target: string) => {
73 - try {
74 - return statSync(target, { throwIfNoEntry: false })?.isFile() === true;
75 - } catch {
76 - return false;
77 - }
78 -};
80 -const collectDocumentSources = (root: string) => {
81 - const sources: { path: string; html: string }[] = [];
82 - const mockups: string[] = [];
83 - for (const directory of DOCUMENT_DIRECTORIES) {
84 - const absoluteDirectory = path.join(root, ".system", directory);
85 - if (!isDirectory(absoluteDirectory)) continue;
86 - for (const entry of readdirSync(absoluteDirectory, {
87 - withFileTypes: true,
88 - })) {
89 - if (!entry.isFile() || !entry.name.endsWith(".html")) continue;
90 - const relative = `.system/${directory}/${entry.name}`;
91 - if (directory === "specs" && MOCKUP.test(entry.name)) {
92 - mockups.push(relative);
93 - continue;
94 - }
95 - sources.push({
96 - path: relative,
97 - html: readFileSync(path.join(absoluteDirectory, entry.name), "utf8"),
98 - });
99 - }
100 - }
101 - return {
102 - sources: sources.sort((left, right) => left.path.localeCompare(right.path)),
103 - mockups: mockups.sort(),
104 - };
105 -};
50 +const isDirectory = (target: string) =>
51 + lstatSync(target, { throwIfNoEntry: false })?.isDirectory() === true;
52 +const isFile = (target: string) =>
53 + lstatSync(target, { throwIfNoEntry: false })?.isFile() === true;
107 55 const collectTestReferences = (root: string): TestReference[] => {
108 56 const references: TestReference[] = [];
122 70 continue;
124 72 if (!entry.isFile()) continue;
125 - const source = readFileSync(target, "utf8");
126 - for (const match of source.matchAll(TEST_REFERENCE))
127 - references.push({ path: relativePath(root, target), spec: match[1] });
73 + for (const match of readFileSync(target, "utf8").matchAll(
74 + TEST_REFERENCE,
75 + )) {
76 + const spec = match[1];
77 + if (spec) references.push({ path: relativePath(root, target), spec });
78 + }
130 81 for (const directory of TEST_DIRECTORIES) scan(path.join(root, directory));
141 92 root = discoverProjectRoot(cwd);
142 93 } catch (error) {
143 94 const value = error as SystemDocumentError;
144 - const diagnostics = [
145 - diagnostic(value.code, path.resolve(cwd), value.message),
146 - ];
147 95 return {
148 96 root: path.resolve(cwd),
149 - diagnostics,
97 + diagnostics: [diagnostic(value.code, path.resolve(cwd), value.message)],
150 98 references: [],
151 99 exitCode: 1,
155 102 const diagnostics: Diagnostic[] = [];
156 - for (const relative of SYSTEM_DIRECTORIES) {
157 - const target = path.join(root, relative);
158 - if (!isDirectory(target))
103 + for (const relative of SYSTEM_DIRECTORIES)
104 + if (!isDirectory(path.join(root, relative)))
159 105 diagnostics.push(
160 106 diagnostic(
161 107 "filesystem.missing",
163 109 `Missing directory ${relative}`,
166 - }
167 - for (const relative of SYSTEM_FILES) {
168 - const target = path.join(root, relative);
169 - if (!isFile(target))
112 + for (const relative of SYSTEM_FILES)
113 + if (!isFile(path.join(root, relative)))
170 114 diagnostics.push(
171 115 diagnostic("filesystem.missing", relative, `Missing file ${relative}`),
173 - }
117 + const cssPath = path.join(root, ".system/system.css");
118 + const css = lstatSync(cssPath, { throwIfNoEntry: false });
119 + if (css?.isFile())
120 + diagnostics.push(
121 + diagnostic(
122 + "filesystem.obsolete",
123 + ".system/system.css",
124 + "Remove obsolete machine-owned asset .system/system.css",
125 + ),
126 + );
127 + else if (css)
128 + diagnostics.push(
129 + diagnostic(
130 + "filesystem.unsafe",
131 + ".system/system.css",
132 + ".system/system.css must be a regular file or absent",
133 + ),
134 + );
175 136 let prefix: string | undefined;
176 - let configuredStyleVersion = STYLE_VERSION;
177 137 const configPath = path.join(root, ".system/config.json");
178 138 if (isFile(configPath)) {
180 - const config = parseSystemConfig(readFileSync(configPath, "utf8"));
181 - prefix = config.prefix;
182 - configuredStyleVersion = config.styleVersion;
183 - if (config.schemaVersion !== SCHEMA_VERSION)
140 + const inspected = inspectSystemConfig(readFileSync(configPath, "utf8"));
141 + prefix = inspected.config.prefix;
142 + if (inspected.config.schemaVersion !== 2)
184 143 diagnostics.push(
185 144 diagnostic(
186 145 "config.schema-outdated",
187 146 ".system/config.json",
188 - `Schema version ${config.schemaVersion}; installed ${SCHEMA_VERSION}`,
189 - ),
190 - );
191 - if (config.styleVersion !== STYLE_VERSION)
192 - diagnostics.push(
193 - diagnostic(
194 - "config.style-outdated",
195 - ".system/config.json",
196 - `Style version ${config.styleVersion}; installed ${STYLE_VERSION}`,
147 + `Schema version ${inspected.config.schemaVersion}; installed 2`,
199 150 } catch (error) {
207 - const cssPath = path.join(root, ".system/system.css");
208 - if (isFile(cssPath)) {
209 - const css = readFileSync(cssPath, "utf8");
210 - const version = /The System styleVersion:\s*([0-9]+)/.exec(css)?.[1];
211 - if (!version)
212 - diagnostics.push(
213 - diagnostic(
214 - "css.version",
215 - ".system/system.css",
216 - "Missing The System styleVersion marker",
217 - ),
218 - );
219 - else if (Number(version) !== configuredStyleVersion)
220 - diagnostics.push(
221 - diagnostic(
222 - "css.version-mismatch",
223 - ".system/system.css",
224 - `Stylesheet version ${version}; configured ${configuredStyleVersion}`,
225 - ),
226 - );
227 - }
229 - const { sources, mockups } = collectDocumentSources(root);
157 + const discovery = discoverDocumentBundles(root);
158 + diagnostics.push(...discovery.diagnostics);
230 159 let specIds = new Set<string>();
231 160 if (prefix) {
232 - const index = indexDocuments(sources, prefix);
161 + const index = indexBundleDocuments(discovery.sources, prefix);
233 162 diagnostics.push(...index.diagnostics);
234 163 specIds = new Set(
235 164 index.documents
236 165 .filter((document) => document.metadata.type === "spec")
237 166 .map((document) => document.metadata.id),
239 - } else {
240 - for (const source of sources)
241 - diagnostics.push(...validateAuthoredHtml(source.path, source.html));
244 - const sourcePaths = new Set(sources.map((source) => source.path));
245 - for (const mockup of mockups) {
246 - const filename = path.posix.basename(mockup);
247 - const owner = MOCKUP.exec(filename)?.[1];
248 - const ownerPath = `.system/specs/${owner}.html`;
249 - if (!owner || !sourcePaths.has(ownerPath))
250 - diagnostics.push(
251 - diagnostic(
252 - "mockup.orphaned",
253 - mockup,
254 - `Mockup owner is missing: ${ownerPath}`,
255 - ),
256 - );
257 - }
259 169 const references = collectTestReferences(root);
260 170 for (const reference of references)
261 171 if (prefix && !specIds.has(reference.spec))
266 176 `Test references missing ${reference.spec}`,
270 179 diagnostics.sort(compareDiagnostics);
271 180 return {

extensions/the-system/documents.ts

Modified
1 -import { existsSync } from "node:fs";
1 +import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
2 2 import path from "node:path";
3 +import {
4 + type FrontmatterMap,
5 + type MarkdownDocumentError,
6 + parseRichMarkdown,
7 +} from "./markdown.ts";
4 -export const SCHEMA_VERSION = 1;
5 -export const STYLE_VERSION = 1;
9 +export const SCHEMA_VERSION = 2;
7 11 export class SystemDocumentError extends Error {
8 12 readonly code: string;
17 21 const nearestMarker = (
18 22 cwd: string,
19 23 marker: string,
20 - markerExists: (path: string) => boolean,
24 + markerExists: (candidate: string) => boolean,
21 25 ) => {
22 26 let current = path.resolve(cwd);
23 27 while (true) {
35 39 const resolvedCwd = path.resolve(cwd);
36 40 const jj = nearestMarker(resolvedCwd, ".jj", markerExists);
37 41 const git = nearestMarker(resolvedCwd, ".git", markerExists);
38 - if (jj && git && jj !== git) {
42 + if (jj && git && jj !== git)
39 43 throw new SystemDocumentError(
40 44 "root.conflict",
41 45 `Conflicting project roots: Git ${git}; JJ ${jj}`,
43 - }
44 47 return jj ?? git ?? resolvedCwd;
52 55 relative === ".." ||
53 56 relative.startsWith(`..${path.sep}`) ||
54 57 path.isAbsolute(relative)
55 - ) {
58 + )
56 59 throw new SystemDocumentError(
57 60 "path.outside-root",
58 61 `Path is outside project root: ${candidate}`,
60 - }
61 63 return target;
69 71 "research",
70 72 ] as const;
71 73 export type DocumentType = (typeof DOCUMENT_TYPES)[number];
72 -export type SystemConfig = Readonly<{
73 - prefix: string;
74 - schemaVersion: number;
75 - styleVersion: number;
74 +export type SystemConfig = Readonly<{ prefix: string; schemaVersion: number }>;
75 +export type InspectedSystemConfig = Readonly<{
76 + config: SystemConfig;
77 + legacyStyleVersion?: number;
77 79 export type ParsedDocumentId = Readonly<{
78 80 id: string;
111 113 | PlanMetadata
112 114 | IssueMetadata
113 115 | ResearchMetadata;
116 +export type Diagnostic = Readonly<{
117 + code: string;
118 + path: string;
119 + message: string;
120 +}>;
121 +export type AuthoredDocument = Readonly<{
122 + metadata: DocumentMetadata;
123 + frontmatter: FrontmatterMap;
124 +}>;
125 +export type BundleDocumentSource = Readonly<{ path: string; markdown: string }>;
126 +export type BundleDocumentRecord = Readonly<{
127 + path: string;
128 + metadata: DocumentMetadata;
129 + frontmatter: FrontmatterMap;
130 +}>;
131 +export type BundleDocumentIndex = Readonly<{
132 + documents: readonly BundleDocumentRecord[];
133 + diagnostics: readonly Diagnostic[];
134 +}>;
135 +export type BundleDiscovery = Readonly<{
136 + sources: readonly BundleDocumentSource[];
137 + diagnostics: readonly Diagnostic[];
138 +}>;
115 140 const PREFIX = /^[A-Z][A-Z0-9]{1,7}$/;
116 141 const SLUG = "[a-z0-9]+(?:-[a-z0-9]+)*";
129 154 value: unknown,
130 155 label: string,
131 156 ): Record<string, unknown> => {
132 - if (typeof value !== "object" || value === null || Array.isArray(value)) {
157 + if (typeof value !== "object" || value === null || Array.isArray(value))
133 158 throw new SystemDocumentError(
134 159 "json.shape",
135 160 `${label} must be a JSON object`,
137 - }
138 162 return value as Record<string, unknown>;
140 164 const exactKeys = (
141 165 value: Record<string, unknown>,
142 166 required: readonly string[],
143 - optional: readonly string[] = [],
144 167 ) => {
145 168 const actual = Object.keys(value).sort();
146 - const allowed = new Set([...required, ...optional]);
148 170 required.some((key) => !(key in value)) ||
149 - actual.some((key) => !allowed.has(key))
150 - ) {
171 + actual.some((key) => !required.includes(key))
151 173 throw new SystemDocumentError(
152 174 "json.keys",
153 - `Expected keys ${[...required, ...optional].sort().join(", ")}; received ${actual.join(", ")}`,
175 + `Expected keys ${[...required].sort().join(", ")}; received ${actual.join(", ")}`,
155 - }
157 178 const positiveInteger = (value: unknown) =>
158 179 typeof value === "number" && Number.isInteger(value) && value > 0;
160 -export function parseSystemConfig(source: string): SystemConfig {
161 - let parsed: unknown;
162 - try {
163 - parsed = JSON.parse(source);
164 - } catch {
165 - throw new SystemDocumentError("config.invalid-json", "Invalid config JSON");
166 - }
167 - const duplicates = duplicateTopLevelKeys(source);
168 - if (duplicates.length)
169 - throw new SystemDocumentError(
170 - "config.duplicate-key",
171 - `Duplicate config keys: ${duplicates.join(", ")}`,
172 - );
173 - const value = objectValue(parsed, "Config");
174 - exactKeys(value, ["prefix", "schemaVersion", "styleVersion"]);
175 - if (typeof value.prefix !== "string" || !PREFIX.test(value.prefix)) {
176 - throw new SystemDocumentError("config.prefix", "Invalid project prefix");
177 - }
178 - if (
179 - !positiveInteger(value.schemaVersion) ||
180 - !positiveInteger(value.styleVersion)
181 - ) {
182 - throw new SystemDocumentError(
183 - "config.version",
184 - "Schema and style versions must be positive integers",
185 - );
186 - }
187 - return {
188 - prefix: value.prefix,
189 - schemaVersion: value.schemaVersion as number,
190 - styleVersion: value.styleVersion as number,
191 - };
194 -export function parseDocumentId(
195 - source: string,
196 - expectedPrefix?: string,
197 -): ParsedDocumentId {
198 - const match =
199 - /^([A-Z][A-Z0-9]{1,7})-(SPEC|ROADMAP|PLAN|ISSUE|RESEARCH)-([0-9]{3,})$/.exec(
200 - source,
201 - );
202 - const sequence = match ? Number(match[3]) : 0;
203 - const canonical = sequence > 0 ? String(sequence).padStart(3, "0") : "";
204 - if (!match || match[3] !== canonical) {
205 - throw new SystemDocumentError(
206 - "id.invalid",
207 - `Invalid document ID: ${source}`,
208 - );
209 - }
210 - if (expectedPrefix && match[1] !== expectedPrefix) {
211 - throw new SystemDocumentError(
212 - "id.prefix",
213 - `Document ID must use prefix ${expectedPrefix}: ${source}`,
214 - );
215 - }
216 - return {
217 - id: source,
218 - prefix: match[1],
219 - type: TYPE_BY_TOKEN.get(match[2]) as DocumentType,
220 - sequence,
221 - };
224 -export function validateFilename(
225 - filename: string,
226 - metadata: DocumentMetadata,
227 - prefix: string,
228 -): void {
229 - const parsed = parseDocumentId(metadata.id, prefix);
230 - const expectedDirectory = DIRECTORY_BY_TYPE[metadata.type];
231 - const directory = path.basename(path.dirname(filename));
232 - const pattern = new RegExp(`^${metadata.id}-${SLUG}\\.html$`);
233 - if (
234 - parsed.type !== metadata.type ||
235 - directory !== expectedDirectory ||
236 - !pattern.test(path.basename(filename))
237 - ) {
238 - throw new SystemDocumentError(
239 - "document.filename",
240 - `Filename mismatch for ${metadata.id}: ${filename}`,
241 - );
242 - }
245 180 const duplicateTopLevelKeys = (source: string): string[] => {
246 181 const keys: string[] = [];
247 182 const duplicates = new Set<string>();
263 198 index += 1;
264 199 continue;
266 - const start = index;
267 - index += 1;
201 + const start = index++;
268 202 let escaped = false;
269 203 while (index < source.length) {
270 204 const current = source[index++];
283 217 return [...duplicates].sort();
286 -const stringArray = (value: unknown, label: string): string[] => {
287 - if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
220 +export function parseSystemConfig(source: string): SystemConfig {
221 + let parsed: unknown;
222 + try {
223 + parsed = JSON.parse(source);
224 + } catch {
225 + throw new SystemDocumentError("config.invalid-json", "Invalid config JSON");
227 + const duplicates = duplicateTopLevelKeys(source);
228 + if (duplicates.length)
288 229 throw new SystemDocumentError(
289 - "metadata.value",
290 - `${label} must be a string array`,
230 + "config.duplicate-key",
231 + `Duplicate config keys: ${duplicates.join(", ")}`,
292 - if (new Set(value).size !== value.length)
233 + const value = objectValue(parsed, "Config");
234 + exactKeys(value, ["prefix", "schemaVersion"]);
235 + if (typeof value.prefix !== "string" || !PREFIX.test(value.prefix))
236 + throw new SystemDocumentError("config.prefix", "Invalid project prefix");
237 + if (!positiveInteger(value.schemaVersion))
293 238 throw new SystemDocumentError(
294 - "metadata.duplicate",
295 - `${label} must contain unique values`,
239 + "config.version",
240 + "Schema version must be a positive integer",
297 - return value;
298 -};
242 + return { prefix: value.prefix, schemaVersion: value.schemaVersion as number };
245 +export function inspectSystemConfig(source: string): InspectedSystemConfig {
246 + try {
247 + return { config: parseSystemConfig(source) };
248 + } catch (currentError) {
249 + let parsed: unknown;
250 + try {
251 + parsed = JSON.parse(source);
252 + } catch {
253 + throw currentError;
255 + if (duplicateTopLevelKeys(source).length > 0) throw currentError;
256 + let value: Record<string, unknown>;
257 + try {
258 + value = objectValue(parsed, "Legacy config");
259 + exactKeys(value, ["prefix", "schemaVersion", "styleVersion"]);
260 + } catch {
261 + throw currentError;
263 + if (value.schemaVersion !== 1 || !positiveInteger(value.styleVersion))
264 + throw currentError;
265 + const config = parseSystemConfig(
266 + JSON.stringify({
267 + prefix: value.prefix,
268 + schemaVersion: value.schemaVersion,
269 + }),
270 + );
271 + return { config, legacyStyleVersion: value.styleVersion as number };
275 +export function parseDocumentId(
276 + source: string,
277 + expectedPrefix?: string,
278 +): ParsedDocumentId {
279 + const match =
280 + /^([A-Z][A-Z0-9]{1,7})-(SPEC|ROADMAP|PLAN|ISSUE|RESEARCH)-([0-9]{3,})$/.exec(
281 + source,
282 + );
283 + const sequence = match ? Number(match[3]) : 0;
284 + const canonical = sequence > 0 ? String(sequence).padStart(3, "0") : "";
285 + if (!match || match[3] !== canonical)
286 + throw new SystemDocumentError(
287 + "id.invalid",
288 + `Invalid document ID: ${source}`,
289 + );
290 + if (expectedPrefix && match[1] !== expectedPrefix)
291 + throw new SystemDocumentError(
292 + "id.prefix",
293 + `Document ID must use prefix ${expectedPrefix}: ${source}`,
294 + );
295 + return {
296 + id: source,
297 + prefix: match[1],
298 + type: TYPE_BY_TOKEN.get(match[2]) as DocumentType,
299 + sequence,
300 + };
303 +export function validateDocumentPath(
304 + documentPath: string,
305 + metadata: DocumentMetadata,
306 + prefix: string,
307 +): void {
308 + const parsed = parseDocumentId(metadata.id, prefix);
309 + const expectedDirectory = DIRECTORY_BY_TYPE[metadata.type];
310 + const pattern = new RegExp(`^${metadata.id}-${SLUG}$`);
311 + const parts = documentPath.split("/");
312 + if (
313 + parsed.type !== metadata.type ||
314 + parts.length !== 4 ||
315 + parts[0] !== ".system" ||
316 + parts[1] !== expectedDirectory ||
317 + !pattern.test(parts[2] ?? "") ||
318 + parts[3] !== "index.md"
320 + throw new SystemDocumentError(
321 + "document.path",
322 + `Bundle path mismatch for ${metadata.id}: ${documentPath}`,
323 + );
299 326 const validDate = (value: unknown) => {
300 327 if (typeof value !== "string" || !/^\d{4}-\d{2}-\d{2}$/.test(value))
301 328 return false;
304 331 !Number.isNaN(date.valueOf()) && date.toISOString().slice(0, 10) === value
307 -const httpsUrl = (value: string) => {
308 - try {
309 - return new URL(value).protocol === "https:";
310 - } catch {
311 - return false;
312 - }
334 +const requiredStringField = (fields: FrontmatterMap, key: string): string => {
335 + const value = fields.get(key);
336 + if (typeof value !== "string")
337 + throw new SystemDocumentError("metadata.value", `${key} must be a string`);
338 + return value;
314 -type HtmlTag = Readonly<{
315 - name: string;
316 - closing: boolean;
317 - start: number;
318 - end: number;
319 - attributes: ReadonlyMap<string, string | undefined>;
320 -}>;
322 -const withoutHtmlComments = (html: string) =>
323 - html.replace(/<!--[\s\S]*?(?:-->|$)/g, (comment) =>
324 - comment.replace(/[^\r\n]/g, " "),
325 - );
327 -const scanAttributes = (
328 - source: string,
329 -): ReadonlyMap<string, string | undefined> => {
330 - const attributes = new Map<string, string | undefined>();
331 - let index = 0;
332 - while (index < source.length) {
333 - while (/\s|\//.test(source[index] ?? "")) index += 1;
334 - const start = index;
335 - while (!/[\s=/>]/.test(source[index] ?? ">")) index += 1;
336 - if (start === index) break;
337 - const name = source.slice(start, index).toLowerCase();
338 - while (/\s/.test(source[index] ?? "")) index += 1;
339 - let value: string | undefined;
340 - if (source[index] === "=") {
341 - index += 1;
342 - while (/\s/.test(source[index] ?? "")) index += 1;
343 - const quote =
344 - source[index] === '"' || source[index] === "'"
345 - ? source[index++]
346 - : undefined;
347 - const valueStart = index;
348 - if (quote)
349 - while (index < source.length && source[index] !== quote) index += 1;
350 - else
351 - while (index < source.length && !/[\s>]/.test(source[index]))
352 - index += 1;
353 - value = source.slice(valueStart, index);
354 - if (quote && source[index] === quote) index += 1;
355 - }
356 - if (!attributes.has(name)) attributes.set(name, value);
357 - }
358 - return attributes;
340 +const optionalUniqueStrings = (
341 + fields: FrontmatterMap,
342 + key: string,
343 +): readonly string[] | undefined => {
344 + const value = fields.get(key);
345 + if (value === undefined) return undefined;
346 + if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
347 + throw new SystemDocumentError(
348 + "metadata.value",
349 + `${key} must be a string array`,
350 + );
351 + if (new Set(value).size !== value.length)
352 + throw new SystemDocumentError(
353 + "metadata.duplicate",
354 + `${key} must contain unique values`,
355 + );
356 + return value as readonly string[];
361 -const scanHtmlTags = (html: string): readonly HtmlTag[] => {
362 - const source = withoutHtmlComments(html);
363 - const tags: HtmlTag[] = [];
364 - let index = 0;
365 - while (index < source.length) {
366 - const start = source.indexOf("<", index);
367 - if (start < 0) break;
368 - let cursor = start + 1;
369 - const closing = source[cursor] === "/";
370 - if (closing) cursor += 1;
371 - while (/\s/.test(source[cursor] ?? "")) cursor += 1;
372 - const nameStart = cursor;
373 - while (/[A-Za-z0-9:-]/.test(source[cursor] ?? "")) cursor += 1;
374 - if (cursor === nameStart) {
375 - index = start + 1;
376 - continue;
377 - }
378 - const name = source.slice(nameStart, cursor).toLowerCase();
379 - let quote: string | undefined;
380 - let end = cursor;
381 - for (; end < source.length; end += 1) {
382 - const character = source[end];
383 - if (quote) {
384 - if (character === quote) quote = undefined;
385 - } else if (character === '"' || character === "'") quote = character;
386 - else if (character === ">") break;
387 - }
388 - if (end >= source.length) break;
389 - tags.push({
390 - name,
391 - closing,
392 - start,
393 - end: end + 1,
394 - attributes: closing
395 - ? new Map()
396 - : scanAttributes(source.slice(cursor, end)),
397 - });
398 - index = end + 1;
399 - }
400 - return tags;
401 -};
403 -const namedEntities: Readonly<Record<string, string>> = {
404 - amp: "&",
405 - apos: "'",
406 - colon: ":",
407 - gt: ">",
408 - lt: "<",
409 - newline: "\n",
410 - quot: '"',
411 - tab: "\t",
412 -};
413 -const decodeBasicEntities = (value: string) =>
414 - value.replace(
415 - /&(?:#(\d+)|#x([\da-f]+)|([a-z][a-z\d]+));?/gi,
416 - (entity, decimal: string, hexadecimal: string, named: string) => {
417 - if (named) return namedEntities[named.toLowerCase()] ?? entity;
418 - const point = Number.parseInt(decimal ?? hexadecimal, decimal ? 10 : 16);
419 - try {
420 - return String.fromCodePoint(point);
421 - } catch {
422 - return "�";
423 - }
424 - },
425 - );
426 -const attributeValue = (tag: HtmlTag, name: string) => {
427 - const value = tag.attributes.get(name);
428 - return value === undefined ? undefined : decodeBasicEntities(value);
429 -};
430 -const normalizedUrl = (value: string) =>
431 - decodeBasicEntities(value)
432 - .replace(/[\u0000-\u001f\u007f-\u009f]/g, "")
433 - .trim();
435 -const scriptBlocks = (html: string, tags = scanHtmlTags(html)) => {
436 - const blocks: { tag: HtmlTag; content: string }[] = [];
437 - for (let index = 0; index < tags.length; index += 1) {
438 - const tag = tags[index];
439 - if (tag.name !== "script" || tag.closing) continue;
440 - const close = tags
441 - .slice(index + 1)
442 - .find((item) => item.name === "script" && item.closing);
443 - if (close) blocks.push({ tag, content: html.slice(tag.end, close.start) });
444 - }
445 - return blocks;
446 -};
448 -const metadataScripts = (html: string) =>
449 - scriptBlocks(html).filter(
450 - ({ tag }) =>
451 - attributeValue(tag, "id")?.toLowerCase() === "system-meta" &&
452 - attributeValue(tag, "type")?.toLowerCase() === "application/json",
453 - );
455 -export function parseDocumentMetadata(
456 - html: string,
358 +const projectMetadata = (
359 + fields: FrontmatterMap,
457 360 prefix: string,
458 -): DocumentMetadata {
459 - const blocks = metadataScripts(html);
460 - if (blocks.length !== 1)
461 - throw new SystemDocumentError(
462 - "metadata.block",
463 - `Expected exactly one system-meta block; received ${blocks.length}`,
464 - );
465 - const json = blocks[0].content.trim();
466 - let parsed: unknown;
467 - let duplicates: string[];
468 - try {
469 - parsed = JSON.parse(json);
470 - duplicates = duplicateTopLevelKeys(json);
471 - } catch {
472 - throw new SystemDocumentError(
473 - "metadata.invalid-json",
474 - "Invalid system metadata JSON",
475 - );
476 - }
477 - if (duplicates.length)
478 - throw new SystemDocumentError(
479 - "metadata.duplicate-key",
480 - `Duplicate metadata keys: ${duplicates.join(", ")}`,
481 - );
482 - const value = objectValue(parsed, "Metadata");
483 - if (typeof value.id !== "string" || typeof value.type !== "string")
361 +): DocumentMetadata => {
362 + const id = requiredStringField(fields, "id");
363 + const type = requiredStringField(fields, "type");
364 + const own = parseDocumentId(id, prefix);
365 + if (own.type !== type)
484 366 throw new SystemDocumentError(
485 367 "metadata.identity",
486 - "Metadata requires string id and type",
487 - );
488 - const ownId = parseDocumentId(value.id, prefix);
489 - if (ownId.type !== value.type)
490 - throw new SystemDocumentError(
491 - "metadata.identity",
492 - `Metadata ID/type mismatch: ${value.id} / ${value.type}`,
368 + `Metadata ID/type mismatch: ${id} / ${type}`,
494 370 const reference = (key: string) => {
495 - if (typeof value[key] !== "string")
496 - throw new SystemDocumentError(
497 - "metadata.value",
498 - `${key} must be a document ID`,
499 - );
500 - parseDocumentId(value[key] as string, prefix);
501 - return value[key] as string;
371 + const value = requiredStringField(fields, key);
372 + parseDocumentId(value, prefix);
373 + return value;
503 - switch (value.type) {
375 + switch (type) {
504 376 case "spec":
505 - exactKeys(value, ["id", "type"]);
506 - return { id: value.id, type: "spec" };
377 + return { id, type };
507 378 case "roadmap":
508 - exactKeys(value, ["id", "type", "spec"]);
509 - return { id: value.id, type: "roadmap", spec: reference("spec") };
379 + return { id, type, spec: reference("spec") };
510 380 case "plan": {
511 - exactKeys(value, ["id", "type", "spec"], ["roadmap", "phase"]);
512 - const hasRoadmap = "roadmap" in value;
513 - const hasPhase = "phase" in value;
381 + const roadmap = fields.get("roadmap");
382 + const phase = fields.get("phase");
515 - hasRoadmap !== hasPhase ||
516 - (hasPhase && !positiveInteger(value.phase))
384 + (roadmap === undefined) !== (phase === undefined) ||
385 + (roadmap !== undefined &&
386 + (typeof roadmap !== "string" || !positiveInteger(phase)))
518 388 throw new SystemDocumentError(
519 389 "metadata.plan-phase",
520 390 "Plan roadmap and positive phase must appear together",
522 - return hasRoadmap
523 - ? {
524 - id: value.id,
525 - type: "plan",
392 + return roadmap === undefined
393 + ? { id, type, spec: reference("spec") }
394 + : {
395 + id,
396 + type,
526 397 spec: reference("spec"),
527 - roadmap: reference("roadmap"),
528 - phase: value.phase as number,
529 - }
530 - : { id: value.id, type: "plan", spec: reference("spec") };
398 + roadmap,
399 + phase: phase as number,
400 + };
532 402 case "issue": {
533 - exactKeys(value, ["id", "type", "status", "specs"]);
534 - if (value.status !== "open" && value.status !== "fixed")
403 + const status = requiredStringField(fields, "status");
404 + if (status !== "open" && status !== "fixed")
535 405 throw new SystemDocumentError(
536 406 "metadata.status",
537 407 "Issue status must be open or fixed",
539 - const specs = stringArray(value.specs, "specs");
540 - for (const id of specs) parseDocumentId(id, prefix);
541 - return { id: value.id, type: "issue", status: value.status, specs };
409 + const specs = optionalUniqueStrings(fields, "specs");
410 + if (!specs)
411 + throw new SystemDocumentError(
412 + "metadata.value",
413 + "specs must be a string array",
414 + );
415 + for (const spec of specs) parseDocumentId(spec, prefix);
416 + return { id, type, status, specs };
543 418 case "research": {
544 - exactKeys(value, ["id", "type", "capturedAt"], ["sources"]);
545 - if (!validDate(value.capturedAt))
419 + const capturedAt = requiredStringField(fields, "capturedAt");
420 + if (!validDate(capturedAt))
546 421 throw new SystemDocumentError(
547 422 "metadata.date",
548 423 "capturedAt must be a valid ISO date",
550 - const sources =
551 - "sources" in value ? stringArray(value.sources, "sources") : undefined;
552 - if (sources?.some((source) => !httpsUrl(source)))
553 - throw new SystemDocumentError(
554 - "metadata.source",
555 - "Research sources must use HTTPS",
556 - );
425 + const sources = optionalUniqueStrings(fields, "sources");
557 426 return sources
558 - ? {
559 - id: value.id,
560 - type: "research",
561 - capturedAt: value.capturedAt as string,
562 - sources,
563 - }
564 - : {
565 - id: value.id,
566 - type: "research",
567 - capturedAt: value.capturedAt as string,
568 - };
427 + ? { id, type, capturedAt, sources }
428 + : { id, type, capturedAt };
570 430 default:
571 431 throw new SystemDocumentError(
572 432 "metadata.type",
573 - `Unsupported metadata type: ${value.type}`,
433 + `Unsupported metadata type: ${type}`,
438 +export function parseAuthoredDocument(
439 + source: string,
440 + prefix: string,
441 +): AuthoredDocument {
442 + const parsed = parseRichMarkdown(source);
443 + return {
444 + metadata: projectMetadata(parsed.frontmatter, prefix),
445 + frontmatter: parsed.frontmatter,
446 + };
578 -export type Diagnostic = Readonly<{
579 - code: string;
580 - path: string;
581 - message: string;
582 -}>;
583 449 const diagnostic = (
584 450 code: string,
585 - path: string,
451 + diagnosticPath: string,
586 452 message: string,
587 -): Diagnostic => ({ code, path, message });
588 -const tagsNamed = (tags: readonly HtmlTag[], name: string, closing = false) =>
589 - tags.filter((tag) => tag.name === name && tag.closing === closing);
590 -const isExecutableUrl = (value: string) =>
591 - /^(?:javascript|vbscript|data):/i.test(normalizedUrl(value));
592 -const isRemoteUrl = (value: string) =>
593 - /^(?:https?:|\/\/)/i.test(normalizedUrl(value));
594 -const srcsetUrls = (value: string) =>
595 - decodeBasicEntities(value)
596 - .split(",")
597 - .map((candidate) => candidate.trim().split(/\s+/)[0] ?? "");
598 -const srcsetHasRemoteUrl = (value: string) =>
599 - srcsetUrls(value).some(isRemoteUrl);
601 -export function validateAuthoredHtml(
602 - filename: string,
603 - html: string,
604 -): readonly Diagnostic[] {
605 - const findings: Diagnostic[] = [];
606 - const cleanHtml = withoutHtmlComments(html);
607 - const tags = scanHtmlTags(html);
608 - const opening = (name: string) => tagsNamed(tags, name);
609 - const closing = (name: string) => tagsNamed(tags, name, true);
610 - const add = (code: string, message: string) =>
611 - findings.push(diagnostic(code, filename, message));
613 - if (!/^<!doctype html>/i.test(cleanHtml.trimStart()))
614 - add("document.doctype", "Document must begin with HTML doctype");
616 - const htmlOpen = opening("html");
617 - const htmlClose = closing("html");
618 - const headOpen = opening("head");
619 - const headClose = closing("head");
620 - const bodyOpen = opening("body");
621 - const bodyClose = closing("body");
622 - if (
623 - htmlOpen.length !== 1 ||
624 - htmlClose.length !== 1 ||
625 - headOpen.length !== 1 ||
626 - headClose.length !== 1 ||
627 - bodyOpen.length !== 1 ||
628 - bodyClose.length !== 1 ||
629 - !(htmlOpen[0]?.start < headOpen[0]?.start) ||
630 - !(headOpen[0]?.start < headClose[0]?.start) ||
631 - !(headClose[0]?.start < bodyOpen[0]?.start) ||
632 - !(bodyOpen[0]?.start < bodyClose[0]?.start) ||
633 - !(bodyClose[0]?.start < htmlClose[0]?.start)
634 - )
635 - add(
636 - "document.structure",
637 - "Document requires one complete html, head, and body structure",
638 - );
640 - if (
641 - htmlOpen.length !== 1 ||
642 - attributeValue(htmlOpen[0], "lang")?.toLowerCase() !== "en"
643 - )
644 - add("document.language", "Document requires one html lang=en root");
646 - const meta = opening("meta");
647 - if (
648 - meta.filter(
649 - (tag) => attributeValue(tag, "charset")?.toLowerCase() === "utf-8",
650 - ).length !== 1
651 - )
652 - add("document.charset", "Document requires one UTF-8 charset meta");
653 - if (
654 - meta.filter(
655 - (tag) =>
656 - attributeValue(tag, "name")?.toLowerCase() === "viewport" &&
657 - /^width=device-width,\s*initial-scale=1$/i.test(
658 - attributeValue(tag, "content") ?? "",
659 - ),
660 - ).length !== 1
661 - )
662 - add("document.viewport", "Document requires one viewport meta");
664 - const titleOpen = opening("title");
665 - const titleClose = closing("title");
666 - if (
667 - titleOpen.length !== 1 ||
668 - titleClose.length !== 1 ||
669 - titleOpen[0].end >= titleClose[0].start ||
670 - !html.slice(titleOpen[0].end, titleClose[0].start).trim()
671 - )
672 - add("document.title", "Document requires one nonempty title");
674 - const stylesheets = opening("link").filter((tag) =>
675 - (attributeValue(tag, "rel") ?? "")
676 - .toLowerCase()
677 - .split(/\s+/)
678 - .includes("stylesheet"),
679 - );
680 - if (
681 - stylesheets.length !== 1 ||
682 - attributeValue(stylesheets[0], "href") !== "../system.css"
683 - )
684 - add(
685 - "document.stylesheet",
686 - "Document requires exactly one ../system.css stylesheet",
687 - );
689 - const semantic = {
690 - header: { open: opening("header"), close: closing("header") },
691 - main: { open: opening("main"), close: closing("main") },
692 - section: { open: opening("section"), close: closing("section") },
693 - };
694 - for (const name of ["header", "main", "section"] as const) {
695 - const pair = semantic[name];
696 - if (
697 - pair.open.length !== 1 ||
698 - pair.close.length !== 1 ||
699 - pair.open[0].start >= pair.close[0].start
700 - )
701 - add(
702 - "document.semantic-shell",
703 - `Document requires one complete ${name} element`,
704 - );
705 - }
706 - if (
707 - bodyOpen.length === 1 &&
708 - bodyClose.length === 1 &&
709 - semantic.header.open.length === 1 &&
710 - semantic.header.close.length === 1 &&
711 - semantic.main.open.length === 1 &&
712 - semantic.main.close.length === 1 &&
713 - semantic.section.open.length === 1 &&
714 - semantic.section.close.length === 1 &&
715 - !(
716 - bodyOpen[0].start < semantic.header.open[0].start &&
717 - semantic.header.close[0].start < semantic.main.open[0].start &&
718 - semantic.main.open[0].start < semantic.section.open[0].start &&
719 - semantic.section.close[0].start < semantic.main.close[0].start &&
720 - semantic.main.close[0].start < bodyClose[0].start
721 - )
722 - )
723 - add(
724 - "document.semantic-shell",
725 - "Document requires header then main with one contained section",
726 - );
728 - if (tags.some((tag) => ["iframe", "object", "embed"].includes(tag.name)))
729 - add("document.forbidden-tag", "iframe, object, and embed are forbidden");
730 - if (
731 - meta.some(
732 - (tag) => attributeValue(tag, "http-equiv")?.toLowerCase() === "refresh",
733 - )
734 - )
735 - add("document.meta-refresh", "Meta refresh is forbidden");
736 - if (
737 - tags.some(
738 - (tag) =>
739 - !tag.closing &&
740 - [...tag.attributes].some(([name]) => /^on[a-z]+$/i.test(name)),
741 - )
742 - )
743 - add("document.event-handler", "Event-handler attributes are forbidden");
745 - const urlAttributes = new Set([
746 - "href",
747 - "src",
748 - "srcset",
749 - "poster",
750 - "action",
751 - "formaction",
752 - "xlink:href",
753 - ]);
754 - let executableUrl = false;
755 - let remoteResource = false;
756 - for (const tag of tags) {
757 - if (tag.closing) continue;
758 - for (const [name, rawValue] of tag.attributes) {
759 - if (!urlAttributes.has(name) || rawValue === undefined) continue;
760 - if (
761 - isExecutableUrl(rawValue) ||
762 - (name === "srcset" && srcsetUrls(rawValue).some(isExecutableUrl))
763 - )
764 - executableUrl = true;
765 - if (
766 - ((name === "src" || name === "poster") && isRemoteUrl(rawValue)) ||
767 - (name === "srcset" && srcsetHasRemoteUrl(rawValue)) ||
768 - ((name === "href" || name === "xlink:href") &&
769 - tag.name !== "a" &&
770 - tag.name !== "area" &&
771 - isRemoteUrl(rawValue))
772 - )
773 - remoteResource = true;
774 - }
775 - }
776 - if (executableUrl)
777 - add("document.executable-url", "Executable URL schemes are forbidden");
778 - if (remoteResource)
779 - add("document.remote-resource", "Remote runtime resources are forbidden");
780 - if (opening("script").some((tag) => tag.attributes.has("src")))
781 - add("document.external-script", "External script sources are forbidden");
782 - if (/(?:@import|url\s*\(\s*["']?\s*(?:https?:|data:))/i.test(cleanHtml))
783 - add(
784 - "document.css-resource",
785 - "CSS imports and remote/data URLs are forbidden",
786 - );
788 - const executable = scriptBlocks(html, tags)
789 - .filter(
790 - ({ tag }) =>
791 - attributeValue(tag, "type")?.toLowerCase() !== "application/json",
792 - )
793 - .map(({ content }) => content)
794 - .join("\n");
795 - if (
796 - /\b(?:fetch|XMLHttpRequest|WebSocket|EventSource|importScripts|localStorage|sessionStorage|indexedDB)\b/.test(
797 - executable,
798 - ) ||
799 - /\bimport\s*\(/.test(executable)
800 - )
801 - add(
802 - "document.active-api",
803 - "Network, import, and browser storage APIs are forbidden",
804 - );
805 - return findings.sort(compareDiagnostics);
453 +): Diagnostic => ({ code, path: diagnosticPath, message });
808 454 const compareDiagnostics = (left: Diagnostic, right: Diagnostic) =>
809 455 left.path.localeCompare(right.path) ||
810 456 left.code.localeCompare(right.code) ||
811 457 left.message.localeCompare(right.message);
458 +const scanBundleAssets = (
459 + absolute: string,
460 + relative: string,
461 + findings: Diagnostic[],
462 +): void => {
463 + for (const entry of readdirSync(absolute, { withFileTypes: true }).sort(
464 + (left, right) => left.name.localeCompare(right.name),
465 + )) {
466 + if (relative.split("/").length === 3 && entry.name === "index.md") continue;
467 + const childAbsolute = path.join(absolute, entry.name);
468 + const childRelative = `${relative}/${entry.name}`;
469 + const stats = lstatSync(childAbsolute, { throwIfNoEntry: false });
470 + if (!stats) continue;
471 + if (stats.isSymbolicLink())
472 + findings.push(
473 + diagnostic(
474 + "bundle.symbolic-link",
475 + childRelative,
476 + `Bundle path is a symbolic link: ${childRelative}`,
477 + ),
478 + );
479 + else if (stats.isDirectory())
480 + scanBundleAssets(childAbsolute, childRelative, findings);
813 -export type DocumentSource = Readonly<{ path: string; html: string }>;
814 -export type DocumentRecord = Readonly<{
815 - path: string;
816 - metadata: DocumentMetadata;
817 -}>;
818 -export type DocumentIndex = Readonly<{
819 - documents: readonly DocumentRecord[];
820 - diagnostics: readonly Diagnostic[];
821 -}>;
484 +export function discoverDocumentBundles(root: string): BundleDiscovery {
485 + const sources: BundleDocumentSource[] = [];
486 + const diagnostics: Diagnostic[] = [];
487 + const systemRoot = path.join(root, ".system");
488 + if (lstatSync(systemRoot, { throwIfNoEntry: false })?.isSymbolicLink())
489 + return {
490 + sources,
491 + diagnostics: [
492 + diagnostic(
493 + "bundle.symbolic-link",
494 + ".system",
495 + "Bundle path is a symbolic link: .system",
496 + ),
497 + ],
498 + };
499 + for (const directory of Object.values(DIRECTORY_BY_TYPE)) {
500 + const relativeDirectory = `.system/${directory}`;
501 + const absoluteDirectory = path.join(root, relativeDirectory);
502 + const directoryStats = lstatSync(absoluteDirectory, {
503 + throwIfNoEntry: false,
504 + });
505 + if (!directoryStats?.isDirectory() || directoryStats.isSymbolicLink())
506 + continue;
507 + for (const entry of readdirSync(absoluteDirectory, {
508 + withFileTypes: true,
509 + }).sort((left, right) => left.name.localeCompare(right.name))) {
510 + const bundleRelative = `${relativeDirectory}/${entry.name}`;
511 + const bundleAbsolute = path.join(absoluteDirectory, entry.name);
512 + const bundleStats = lstatSync(bundleAbsolute, { throwIfNoEntry: false });
513 + if (bundleStats?.isSymbolicLink()) {
514 + diagnostics.push(
515 + diagnostic(
516 + "bundle.symbolic-link",
517 + bundleRelative,
518 + `Bundle path is a symbolic link: ${bundleRelative}`,
519 + ),
520 + );
521 + continue;
523 + if (!bundleStats?.isDirectory()) {
524 + diagnostics.push(
525 + diagnostic(
526 + "bundle.expected-directory",
527 + bundleRelative,
528 + `Expected a document bundle directory: ${bundleRelative}`,
529 + ),
530 + );
531 + continue;
533 + const indexRelative = `${bundleRelative}/index.md`;
534 + const indexAbsolute = path.join(bundleAbsolute, "index.md");
535 + const indexStats = lstatSync(indexAbsolute, { throwIfNoEntry: false });
536 + if (!indexStats)
537 + diagnostics.push(
538 + diagnostic(
539 + "bundle.missing-index",
540 + bundleRelative,
541 + `Bundle is missing index.md: ${bundleRelative}`,
542 + ),
543 + );
544 + else if (indexStats.isSymbolicLink())
545 + diagnostics.push(
546 + diagnostic(
547 + "bundle.symbolic-link",
548 + indexRelative,
549 + `Bundle path is a symbolic link: ${indexRelative}`,
550 + ),
551 + );
552 + else if (!indexStats.isFile())
553 + diagnostics.push(
554 + diagnostic(
555 + "bundle.expected-file",
556 + indexRelative,
557 + `Expected a regular index.md: ${indexRelative}`,
558 + ),
559 + );
560 + else
561 + sources.push({
562 + path: indexRelative,
563 + markdown: readFileSync(indexAbsolute, "utf8"),
564 + });
565 + scanBundleAssets(bundleAbsolute, bundleRelative, diagnostics);
568 + return {
569 + sources: sources.sort((left, right) => left.path.localeCompare(right.path)),
570 + diagnostics: diagnostics.sort(compareDiagnostics),
571 + };
823 574 const references = (
824 575 metadata: DocumentMetadata,
825 -): readonly (readonly [string, "spec" | "roadmap"])[] => {
576 +): readonly (readonly [string, DocumentType])[] => {
826 577 switch (metadata.type) {
827 578 case "roadmap":
828 579 return [[metadata.spec, "spec"]];
829 580 case "plan":
830 581 return [
831 582 [metadata.spec, "spec"],
832 - ...(metadata.roadmap ? [[metadata.roadmap, "roadmap"] as const] : []),
583 + ...(metadata.roadmap ? ([[metadata.roadmap, "roadmap"]] as const) : []),
834 585 case "issue":
835 - return metadata.specs.map((id) => [id, "spec"] as const);
586 + return metadata.specs.map((spec) => [spec, "spec"] as const);
836 587 default:
837 588 return [];
841 591 const diagnosticIdentity = (item: Diagnostic) =>
842 592 JSON.stringify([item.path, item.code, item.message]);
844 -export function validateDocumentCandidate(
845 - current: readonly DocumentSource[],
846 - candidate: DocumentSource,
594 +export function indexBundleDocuments(
595 + sources: readonly BundleDocumentSource[],
847 596 prefix: string,
848 -): readonly Diagnostic[] {
849 - const baseline = new Set(
850 - indexDocuments(current, prefix).diagnostics.map(diagnosticIdentity),
851 - );
852 - const next = indexDocuments(
853 - [...current.filter((source) => source.path !== candidate.path), candidate],
854 - prefix,
855 - );
856 - return next.diagnostics.filter(
857 - (item) =>
858 - item.path === candidate.path ||
859 - (!baseline.has(diagnosticIdentity(item)) &&
860 - item.code !== "graph.duplicate-id"),
861 - );
864 -export function indexDocuments(
865 - sources: readonly DocumentSource[],
866 - prefix: string,
867 -): DocumentIndex {
868 - const documents: DocumentRecord[] = [];
869 - const graphEligible: DocumentRecord[] = [];
597 +): BundleDocumentIndex {
598 + const documents: BundleDocumentRecord[] = [];
599 + const graphEligible: BundleDocumentRecord[] = [];
870 600 const diagnostics: Diagnostic[] = [];
871 601 for (const item of [...sources].sort((left, right) =>
872 602 left.path.localeCompare(right.path),
874 - const htmlDiagnostics = validateAuthoredHtml(item.path, item.html);
875 - diagnostics.push(...htmlDiagnostics);
877 - const metadata = parseDocumentMetadata(item.html, prefix);
878 - let filenameValid = true;
605 + const parsed = parseAuthoredDocument(item.markdown, prefix);
606 + let pathValid = true;
880 - validateFilename(item.path, metadata, prefix);
608 + validateDocumentPath(item.path, parsed.metadata, prefix);
881 609 } catch (error) {
882 - filenameValid = false;
610 + pathValid = false;
883 611 diagnostics.push(
884 - diagnostic("document.filename", item.path, (error as Error).message),
612 + diagnostic("document.path", item.path, (error as Error).message),
887 - const record = { path: item.path, metadata };
615 + const record = {
616 + path: item.path,
617 + metadata: parsed.metadata,
618 + frontmatter: parsed.frontmatter,
619 + };
888 620 documents.push(record);
889 - if (filenameValid && htmlDiagnostics.length === 0)
890 - graphEligible.push(record);
621 + if (pathValid) graphEligible.push(record);
891 622 } catch (error) {
892 - const value = error as SystemDocumentError;
623 + const value = error as SystemDocumentError | MarkdownDocumentError;
893 624 diagnostics.push(
894 625 diagnostic(
895 626 "document.metadata",
902 - const groups = new Map<string, DocumentRecord[]>();
633 + const groups = new Map<string, BundleDocumentRecord[]>();
903 634 for (const document of graphEligible)
904 635 groups.set(document.metadata.id, [
905 636 ...(groups.get(document.metadata.id) ?? []),
906 637 document,
908 639 for (const [id, records] of groups) {
909 - if (records.length > 1) {
910 - const paths = records.map((record) => record.path).sort();
911 - for (const record of records)
912 - diagnostics.push(
913 - diagnostic(
914 - "graph.duplicate-id",
915 - record.path,
916 - `Duplicate ID ${id}: ${paths.join(", ")}`,
917 - ),
918 - );
919 - }
640 + if (records.length < 2) continue;
641 + const paths = records.map((record) => record.path).sort();
642 + for (const record of records)
643 + diagnostics.push(
644 + diagnostic(
645 + "graph.duplicate-id",
646 + record.path,
647 + `Duplicate ID ${id}: ${paths.join(", ")}`,
648 + ),
649 + );
921 651 const unique = new Map(
922 - [...groups]
923 - .filter(([, records]) => records.length === 1)
924 - .map(([id, records]) => [id, records[0]]),
652 + [...groups].flatMap(([id, records]) => {
653 + const [record] = records;
654 + return records.length === 1 && record ? [[id, record] as const] : [];
655 + }),
926 657 for (const document of graphEligible) {
927 658 for (const [targetId, expectedType] of references(document.metadata)) {
928 659 const referencedType = parseDocumentId(targetId, prefix).type;
929 660 const target = unique.get(targetId);
930 - if (referencedType !== expectedType) {
661 + if (referencedType !== expectedType)
931 662 diagnostics.push(
932 663 diagnostic(
933 664 "graph.forbidden-edge",
935 666 `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${referencedType}`,
938 - } else if (!target) {
669 + else if (!target)
939 670 diagnostics.push(
940 671 diagnostic(
941 672 "graph.dangling-reference",
943 674 `${document.metadata.id} references missing ${targetId}`,
946 - } else if (target.metadata.type !== expectedType) {
677 + else if (target.metadata.type !== expectedType)
947 678 diagnostics.push(
948 679 diagnostic(
949 680 "graph.forbidden-edge",
951 682 `${document.metadata.id} must reference ${expectedType}; ${targetId} is ${target.metadata.type}`,
954 - }
956 686 if (document.metadata.type === "plan" && document.metadata.roadmap) {
957 687 const roadmap = unique.get(document.metadata.roadmap);
959 689 roadmap?.metadata.type === "roadmap" &&
960 690 roadmap.metadata.spec !== document.metadata.spec
961 - ) {
962 692 diagnostics.push(
963 693 diagnostic(
964 694 "graph.forbidden-edge",
966 696 `${document.metadata.roadmap} belongs to ${roadmap.metadata.spec}, not ${document.metadata.spec}`,
969 - }
972 701 return { documents, diagnostics: diagnostics.sort(compareDiagnostics) };
704 +export function validateBundleCandidate(
705 + current: readonly BundleDocumentSource[],
706 + candidate: BundleDocumentSource,
707 + prefix: string,
708 +): readonly Diagnostic[] {
709 + const baseline = new Set(
710 + indexBundleDocuments(current, prefix).diagnostics.map(diagnosticIdentity),
711 + );
712 + const next = indexBundleDocuments(
713 + [...current.filter((source) => source.path !== candidate.path), candidate],
714 + prefix,
715 + );
716 + return next.diagnostics.filter(
717 + (item) =>
718 + item.path === candidate.path ||
719 + (!baseline.has(diagnosticIdentity(item)) &&
720 + item.code !== "graph.duplicate-id"),
721 + );

extensions/the-system/init.ts

Modified
1 -import { lstatSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
2 -import path from "node:path";
1 +import {
2 + lstatSync,
3 + mkdirSync,
4 + readFileSync,
5 + unlinkSync,
6 + writeFileSync,
7 +} from "node:fs";
3 8 import {
4 9 discoverProjectRoot,
10 + inspectSystemConfig,
5 11 parseSystemConfig,
6 12 resolveGovernedPath,
7 13 SCHEMA_VERSION,
8 - STYLE_VERSION,
9 14 SystemDocumentError,
10 15 } from "./documents.ts";
12 -export type MachineAssets = Readonly<{
13 - schemaVersion: number;
14 - styleVersion: number;
15 - css: string;
16 -}>;
17 +export type MachineState = Readonly<{ schemaVersion: number }>;
17 18 export type InitializationInspection = Readonly<{
18 19 root: string;
19 20 prefix?: string;
25 26 root: string;
26 27 prefix: string;
27 28 changed: readonly string[];
29 + removed: readonly string[];
28 30 pending: readonly string[];
30 33 const DIRECTORIES = [
31 34 ".system",
32 35 ".system/specs",
42 45 ] as const;
43 46 const CONFIG = ".system/config.json";
44 47 const CSS = ".system/system.css";
45 -export const DEFAULT_MACHINE_ASSETS: MachineAssets = Object.freeze({
48 +export const DEFAULT_MACHINE_STATE: MachineState = Object.freeze({
46 49 schemaVersion: SCHEMA_VERSION,
47 - styleVersion: STYLE_VERSION,
48 - css: readFileSync(
49 - path.join(import.meta.dirname, "assets/system.css"),
50 - "utf8",
51 - ),
53 52 const target = (root: string, relative: string) =>
54 53 resolveGovernedPath(root, relative);
55 54 const kind = (file: string) => {
74 73 return actual;
76 -const validatePrefix = (prefix: string, assets: MachineAssets) => {
75 +const validatePrefix = (prefix: string, state: MachineState) => {
77 76 parseSystemConfig(
78 - JSON.stringify({
79 - prefix,
80 - schemaVersion: assets.schemaVersion,
81 - styleVersion: assets.styleVersion,
82 - }),
77 + JSON.stringify({ prefix, schemaVersion: state.schemaVersion }),
84 79 return prefix;
86 -const configSource = (prefix: string, assets: MachineAssets) =>
87 - `${JSON.stringify({ prefix, schemaVersion: assets.schemaVersion, styleVersion: assets.styleVersion }, null, "\t")}\n`;
81 +const configSource = (prefix: string, state: MachineState) =>
82 + `${JSON.stringify({ prefix, schemaVersion: state.schemaVersion }, null, "\t")}\n`;
89 84 export function inspectInitialization(
90 85 cwd: string,
91 86 requestedPrefix?: string,
92 - assets: MachineAssets = DEFAULT_MACHINE_ASSETS,
87 + state: MachineState = DEFAULT_MACHINE_STATE,
93 88 ): InitializationInspection {
94 89 const root = discoverProjectRoot(cwd);
95 90 for (const relative of DIRECTORIES) requireKind(root, relative, "directory");
96 91 const configKind = requireKind(root, CONFIG, "file");
97 92 const cssKind = requireKind(root, CSS, "file");
98 93 const requested = requestedPrefix
99 - ? validatePrefix(requestedPrefix, assets)
94 + ? validatePrefix(requestedPrefix, state)
100 95 : undefined;
101 - const config =
96 + const inspected =
102 97 configKind === "file"
103 - ? parseSystemConfig(readFileSync(target(root, CONFIG), "utf8"))
98 + ? inspectSystemConfig(readFileSync(target(root, CONFIG), "utf8"))
104 99 : undefined;
100 + const config = inspected?.config;
105 101 if (config && requested && config.prefix !== requested)
106 102 throw new SystemDocumentError(
107 103 "init.prefix-conflict",
108 104 `Existing prefix ${config.prefix} does not match requested ${requested}`,
110 - if (
111 - config &&
112 - (config.schemaVersion > assets.schemaVersion ||
113 - config.styleVersion > assets.styleVersion)
114 - )
106 + if (config && config.schemaVersion > state.schemaVersion)
115 107 throw new SystemDocumentError(
116 108 "init.version-newer",
117 - `Project versions schema ${config.schemaVersion}, style ${config.styleVersion} are newer than installed schema ${assets.schemaVersion}, style ${assets.styleVersion}`,
109 + `Project schema ${config.schemaVersion} is newer than installed schema ${state.schemaVersion}`,
119 111 const creates: string[] = [];
120 112 for (const relative of DIRECTORIES)
121 113 if (kind(target(root, relative)) === "missing") creates.push(relative);
122 114 if (configKind === "missing") creates.push(CONFIG);
123 - if (cssKind === "missing") creates.push(CSS);
124 115 const upgrades: string[] = [];
125 - if (
126 - config &&
127 - (config.schemaVersion !== assets.schemaVersion ||
128 - config.styleVersion !== assets.styleVersion)
129 - )
116 + if (config && config.schemaVersion !== state.schemaVersion)
130 117 upgrades.push(
131 - `${CONFIG} schemaVersion ${config.schemaVersion} -> ${assets.schemaVersion}, styleVersion ${config.styleVersion} -> ${assets.styleVersion}`,
118 + `${CONFIG} schemaVersion ${config.schemaVersion} -> ${state.schemaVersion}${inspected?.legacyStyleVersion ? "; remove styleVersion" : ""}`,
133 - if (
134 - cssKind === "file" &&
135 - readFileSync(target(root, CSS), "utf8") !== assets.css
136 - )
137 - upgrades.push(`${CSS} bundled styleVersion ${assets.styleVersion}`);
120 + if (cssKind === "file")
121 + upgrades.push(`${CSS} remove obsolete machine-owned asset`);
138 122 return {
140 124 prefix: config?.prefix ?? requested,
152 136 cwd: string,
153 137 requestedPrefix?: string,
154 138 approveUpgrades = false,
155 - assets: MachineAssets = DEFAULT_MACHINE_ASSETS,
139 + state: MachineState = DEFAULT_MACHINE_STATE,
156 140 ): InitializationResult {
157 - const inspection = inspectInitialization(cwd, requestedPrefix, assets);
141 + const inspection = inspectInitialization(cwd, requestedPrefix, state);
158 142 if (!inspection.prefix)
159 143 throw new SystemDocumentError(
160 144 "init.prefix-required",
161 145 "An approved project prefix is required before initialization",
163 147 const changed: string[] = [];
148 + const removed: string[] = [];
164 149 for (const relative of DIRECTORIES) {
165 150 if (kind(target(inspection.root, relative)) !== "missing") continue;
166 151 mkdirSync(target(inspection.root, relative));
176 161 writeFileSync(
177 162 target(inspection.root, CONFIG),
178 - configSource(inspection.prefix, assets),
163 + configSource(inspection.prefix, state),
179 164 kind(target(inspection.root, CONFIG)) === "missing"
180 165 ? { encoding: "utf8", flag: "wx" }
181 166 : "utf8",
183 168 changed.push(CONFIG);
185 - const cssUpgrade = inspection.upgrades.some((item) =>
186 - item.startsWith(`${CSS} `),
187 - );
189 - kind(target(inspection.root, CSS)) === "missing" ||
190 - (approveUpgrades && cssUpgrade)
171 + approveUpgrades &&
172 + inspection.upgrades.includes(`${CSS} remove obsolete machine-owned asset`)
192 - writeFileSync(
193 - target(inspection.root, CSS),
194 - assets.css,
195 - kind(target(inspection.root, CSS)) === "missing"
196 - ? { encoding: "utf8", flag: "wx" }
197 - : "utf8",
198 - );
199 - changed.push(CSS);
174 + unlinkSync(target(inspection.root, CSS));
175 + removed.push(CSS);
201 177 return {
202 178 root: inspection.root,
203 179 prefix: inspection.prefix,
204 180 changed,
181 + removed,
205 182 pending: approveUpgrades ? [] : inspection.upgrades,

extensions/the-system/scripts/init.mjs

Modified
20 20 console.log(`ROOT ${result.root}`);
21 21 console.log(`PREFIX ${result.prefix}`);
22 22 for (const item of result.changed) console.log(`WROTE ${item}`);
23 + for (const item of result.removed) console.log(`REMOVED ${item}`);
23 24 for (const item of result.pending) console.log(`PENDING ${item}`);
24 25 if (result.pending.length === 0) console.log("OK machine state applied");
25 26 } else

extensions/the-system/system.ts

Modified
1 -import { existsSync, lstatSync, readdirSync, readFileSync } from "node:fs";
1 +import { existsSync, lstatSync, readFileSync } from "node:fs";
2 2 import path from "node:path";
3 -import {
4 - type EditToolInput,
5 - type ExtensionAPI,
6 - type ExtensionContext,
7 - isToolCallEventType,
8 - type WriteToolInput,
3 +import type {
4 + EditToolInput,
5 + ExtensionAPI,
6 + ExtensionContext,
7 + WriteToolInput,
9 8 } from "@earendil-works/pi-coding-agent";
9 +import { isToolCallEventType } from "@earendil-works/pi-coding-agent";
10 10 import {
11 11 type Diagnostic,
12 + type DocumentMetadata,
13 + discoverDocumentBundles,
12 14 discoverProjectRoot,
13 - parseDocumentMetadata,
15 + indexBundleDocuments,
16 + parseAuthoredDocument,
14 17 parseSystemConfig,
15 18 resolveGovernedPath,
16 - validateAuthoredHtml,
17 - validateDocumentCandidate,
19 + validateBundleCandidate,
18 20 } from "./documents.ts";
19 21 import { inspectInitialization } from "./init.ts";
21 23 export const CORE_BYTE_LIMIT = 32 * 1024;
22 24 const CORES = ["SYSTEM.md", "MISSION.md", "RULES.md"] as const;
24 25 const governanceError = (systemPrompt: string, message: string) =>
25 26 `${systemPrompt}\n\n# The System governance error\n\n${message}\n\nDo not mutate .system until /system-doctor resolves this governance error.`;
27 27 const coreBlock = (root: string, name: (typeof CORES)[number]) => {
28 28 const relative = `.system/${name}`;
29 29 const target = path.join(root, relative);
38 38 return `## ${name}\n\n[Not injected: ${name} exceeds the ${CORE_BYTE_LIMIT}-byte injection limit.]`;
39 39 return `## ${name}\n\n${readFileSync(target, "utf8")}`;
40 40 } catch (error) {
41 - const message = error instanceof Error ? error.message : String(error);
42 - throw new Error(`Unable to read core path ${relative}: ${message}`);
41 + throw new Error(
42 + `Unable to read core path ${relative}: ${error instanceof Error ? error.message : String(error)}`,
43 + );
57 58 const blocks = CORES.map((name) => coreBlock(root, name)).filter(
58 59 (block): block is string => block !== undefined,
60 - if (blocks.length === 0) return systemPrompt;
61 - return `${systemPrompt}\n\n# The System project law\n\n${blocks.join("\n\n")}`;
61 + return blocks.length === 0
62 + ? systemPrompt
63 + : `${systemPrompt}\n\n# The System project law\n\n${blocks.join("\n\n")}`;
62 64 } catch (error) {
63 65 return governanceError(
64 66 systemPrompt,
77 79 return "The System is incomplete or invalid; run /system-init before governed work.";
78 80 if (inspection.upgrades.length > 0)
79 - return "The System schema/style refresh is available; run /system-init to inspect and approve it.";
81 + return "The System schema refresh is available; run /system-init to inspect and approve it.";
80 82 return undefined;
81 83 } catch {
82 84 return "The System is incomplete or invalid; run /system-init before governed work.";
90 92 hasUI: boolean;
91 93 select(title: string, items: string[]): Promise<string | undefined>;
93 -const DOCUMENT_DIRECTORIES = [
94 - "specs",
95 - "roadmaps",
96 - "plans",
97 - "issues",
98 - "research",
99 -] as const;
100 95 const CORE_PATHS = new Set([
101 96 ".system/SYSTEM.md",
102 97 ".system/MISSION.md",
103 98 ".system/RULES.md",
105 -const MOCKUP_NAME = /^(.*)-mockup-[a-z0-9]+(?:-[a-z0-9]+)*\.html$/;
106 100 const posixRelative = (root: string, target: string) =>
107 101 path.relative(root, target).split(path.sep).join("/");
108 102 const blocked = (reason: string): GateResult => ({ block: true, reason });
114 108 shown.push(`+${diagnostics.length - shown.length} more finding(s)`);
115 109 return `The System candidate validation failed: ${shown.join("; ")}`;
117 -const collectDocumentSources = (root: string, prefix: string) => {
118 - const sources: { path: string; html: string }[] = [];
119 - for (const directory of DOCUMENT_DIRECTORIES) {
120 - const absolute = path.join(root, ".system", directory);
121 - const stats = lstatSync(absolute, { throwIfNoEntry: false });
122 - if (!stats?.isDirectory()) continue;
123 - for (const entry of readdirSync(absolute, { withFileTypes: true })) {
124 - if (!entry.isFile() || !entry.name.endsWith(".html")) continue;
125 - const sourcePath = `.system/${directory}/${entry.name}`;
126 - const html = readFileSync(path.join(absolute, entry.name), "utf8");
127 - if (directory === "specs" && MOCKUP_NAME.test(entry.name)) {
128 - try {
129 - if (parseDocumentMetadata(html, prefix).type !== "spec") continue;
130 - } catch {
131 - continue;
132 - }
133 - }
134 - sources.push({ path: sourcePath, html });
135 - }
136 - }
137 - return sources.sort((left, right) => left.path.localeCompare(right.path));
138 -};
139 111 const applyExactEdits = (source: string, edits: EditToolInput["edits"]) => {
140 112 const replacements = edits
141 113 .map((edit) => {
176 148 parseSystemConfig(
177 149 readFileSync(path.join(root, ".system/config.json"), "utf8"),
178 150 ).prefix;
179 -const validateDocument = (root: string, relative: string, content: string) => {
180 - const prefix = projectPrefix(root);
181 - return validateDocumentCandidate(
182 - collectDocumentSources(root, prefix),
183 - { path: relative, html: content },
184 - prefix,
185 - );
152 +type GovernedDocumentPath = Readonly<{
153 + directory: "specs" | "roadmaps" | "plans" | "issues" | "research";
154 + bundle: string;
155 + asset: string;
156 + index: boolean;
157 +}>;
158 +const governedDocumentPath = (
159 + relative: string,
160 +): GovernedDocumentPath | undefined => {
161 + const match =
162 + /^\.system\/(specs|roadmaps|plans|issues|research)\/([^/]+)\/(.+)$/.exec(
163 + relative,
164 + );
165 + if (!match) return undefined;
166 + const [, directory, bundle, asset] = match;
167 + if (!directory || !bundle || !asset || asset.endsWith("/index.md"))
168 + return undefined;
169 + return {
170 + directory: directory as GovernedDocumentPath["directory"],
171 + bundle,
172 + asset,
173 + index: asset === "index.md",
174 + };
187 -const isSpecCandidate = (root: string, content: string) => {
188 - try {
189 - return parseDocumentMetadata(content, projectPrefix(root)).type === "spec";
190 - } catch {
191 - return false;
192 - }
193 -};
194 -const validateMockup = (
176 +type ResolvedBundleMutation = Readonly<{
177 + location: GovernedDocumentPath;
178 + metadata?: DocumentMetadata;
179 + findings: readonly Diagnostic[];
180 +}>;
181 +const resolveBundleMutation = (
195 182 root: string,
196 183 relative: string,
197 - content: string,
198 -): readonly Diagnostic[] => {
199 - const findings = [...validateAuthoredHtml(relative, content)];
200 - const filename = path.posix.basename(relative);
201 - const owner = MOCKUP_NAME.exec(filename)?.[1];
202 - const ownerPath = owner ? `.system/specs/${owner}.html` : undefined;
203 - if (!ownerPath || !existsSync(path.join(root, ownerPath)))
204 - findings.push({
205 - code: "mockup.orphaned",
206 - path: relative,
207 - message: `Mockup owner is missing: ${ownerPath ?? "unrecognized filename"}`,
208 - });
209 - return findings.sort(
210 - (left, right) =>
211 - left.path.localeCompare(right.path) ||
212 - left.code.localeCompare(right.code) ||
213 - left.message.localeCompare(right.message),
184 + content: string | undefined,
185 +): ResolvedBundleMutation => {
186 + const location = governedDocumentPath(relative);
187 + if (!location)
188 + throw new Error(
189 + `Authored paths require .system/<type>/<ID>-<slug>/<file>: ${relative}`,
190 + );
191 + const prefix = projectPrefix(root);
192 + const discovery = discoverDocumentBundles(root);
193 + const bundlePath = `.system/${location.directory}/${location.bundle}`;
194 + const localDiscovery = discovery.diagnostics
195 + .filter(
196 + (item) =>
197 + item.path === bundlePath || item.path.startsWith(`${bundlePath}/`),
199 + .filter(
200 + (item) =>
201 + !(
202 + location.index &&
203 + item.path === bundlePath &&
204 + item.code === "bundle.missing-index"
205 + ),
206 + );
207 + if (localDiscovery.length > 0) return { location, findings: localDiscovery };
208 + if (location.index) {
209 + if (content === undefined)
210 + throw new Error("Missing index candidate content");
211 + const findings = validateBundleCandidate(
212 + discovery.sources,
213 + { path: relative, markdown: content },
214 + prefix,
215 + );
216 + const parsed = parseAuthoredDocument(content, prefix);
217 + return { location, metadata: parsed.metadata, findings };
219 + const indexPath = `${bundlePath}/index.md`;
220 + const owner = discovery.sources.find((source) => source.path === indexPath);
221 + if (!owner)
222 + throw new Error(
223 + `Bundle requires a valid index.md before assets: ${bundlePath}`,
224 + );
225 + const indexed = indexBundleDocuments(discovery.sources, prefix);
226 + const findings = indexed.diagnostics.filter(
227 + (item) => item.path === indexPath,
229 + const document = indexed.documents.find((item) => item.path === indexPath);
230 + if (!document) throw new Error(`Bundle index is invalid: ${indexPath}`);
231 + return { location, metadata: document.metadata, findings };
217 -const directDocumentPath = (relative: string) =>
218 - /^\.system\/(specs|roadmaps|plans|issues|research)\/[^/]+\.html$/.test(
219 - relative,
220 - );
221 -const nestedDocumentPath = (relative: string) =>
222 - /^\.system\/(specs|roadmaps|plans|issues|research)\/.+\/[^/]+\.html$/.test(
223 - relative,
224 - );
225 233 const symbolicLinkInPath = (root: string, target: string) => {
226 - const relative = path.relative(root, target);
227 234 let current = root;
228 - for (const part of relative.split(path.sep)) {
235 + for (const part of path.relative(root, target).split(path.sep)) {
229 236 if (!part) continue;
230 237 current = path.join(current, part);
231 - const stats = lstatSync(current, { throwIfNoEntry: false });
232 - if (stats?.isSymbolicLink()) return posixRelative(root, current);
238 + if (lstatSync(current, { throwIfNoEntry: false })?.isSymbolicLink())
239 + return posixRelative(root, current);
234 241 return undefined;
237 244 const SHELL_MUTATOR =
238 245 /(?:^|[;&|]\s*)(?:rm|mv|cp|install|truncate|touch|tee|sed\s+-[^\n]*i|perl\s+-[^\n]*i)\b|(?:^|[^<])>>?/i;
239 246 const OWNED_SHELL_PATH =
240 - /(?:^|[\s"'`])([^\s"'`;&|]*\.system\/(?:SYSTEM\.md|MISSION\.md|RULES\.md|specs\/[^\s"'`;&|]+\.html))(?=$|[\s"'`;&|])/i;
247 + /(?:^|[\s"'`])([^\s"'`;&|]*\.system\/(?:SYSTEM\.md|MISSION\.md|RULES\.md|specs\/[^/\s"'`;&|]+(?:\/[^\s"'`;&|]+)?))(?=$|[\s"'`;&|])/i;
242 248 export function preflightShellMutation(command: string): GateResult {
243 249 if (!SHELL_MUTATOR.test(command)) return undefined;
244 250 const owned = OWNED_SHELL_PATH.exec(command)?.[1];
273 279 const relative = posixRelative(root, target);
274 - if (nestedDocumentPath(relative))
275 - return blocked(
276 - `The System requires authored documents directly inside their matching .system directory: ${relative}.`,
277 - );
278 - const documentPath = directDocumentPath(relative);
279 - if (!CORE_PATHS.has(relative) && !documentPath) return undefined;
280 + if (
281 + !CORE_PATHS.has(relative) &&
282 + !/^\.system\/(specs|roadmaps|plans|issues|research)(?:\/|$)/.test(relative)
284 + return undefined;
281 286 const link = symbolicLinkInPath(root, target);
282 287 if (link)
301 306 return undefined;
303 - let content: string;
304 - let findings: readonly Diagnostic[];
305 - let mockup: boolean;
306 - let spec: boolean;
308 + const location = governedDocumentPath(relative);
309 + if (!location)
310 + return blocked(
311 + `The System requires document bundles at .system/<type>/<ID>-<slug>/<file>: ${relative}.`,
312 + );
313 + let content: string | undefined;
314 + if (location.index)
315 + try {
316 + content = candidateContent(target, kind, input);
317 + } catch (error) {
318 + return blocked(
319 + `The System candidate validation failed: ${error instanceof Error ? error.message : String(error)}`,
320 + );
322 + let resolved: ResolvedBundleMutation;
308 - content = candidateContent(target, kind, input);
309 - spec = isSpecCandidate(root, content);
310 - mockup = MOCKUP_NAME.test(path.posix.basename(relative)) && !spec;
311 - findings = mockup
312 - ? validateMockup(root, relative, content)
313 - : validateDocument(root, relative, content);
324 + resolved = resolveBundleMutation(root, relative, content);
314 325 } catch (error) {
315 326 return blocked(
316 327 `The System candidate validation failed: ${error instanceof Error ? error.message : String(error)}`,
319 - if (findings.length > 0) return blocked(diagnosticsReason(findings));
330 + if (resolved.findings.length > 0)
331 + return blocked(diagnosticsReason(resolved.findings));
332 + if (!resolved.metadata)
333 + return blocked(
334 + `The System could not determine bundle ownership: ${relative}.`,
335 + );
320 336 if (!targetStats) return undefined;
321 337 if (!targetStats.isFile())
322 338 return blocked(`The System expected a regular owned file at ${relative}.`);
323 - if (!spec && !mockup) return undefined;
339 + if (resolved.metadata.type !== "spec") return undefined;
324 340 if (!ui.hasUI)
325 341 return blocked(
326 342 `The System blocked existing human-owned ${relative}: interactive UI is unavailable.`,