cyber-sdd 0.4.0 → 0.4.2

package/dist/concept-index/scripts/concept-index.js

@@ -0,0 +1,181 @@
+#!/usr/bin/env node
+import { existsSync, readFileSync, readdirSync, realpathSync, writeFileSync } from "node:fs";
+import { join, relative } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/concept-index/scripts/concept-index.mts
+const BEGIN_MARKER = "<!-- BEGIN generated: by-concept (project-spec/concept-index) -->";
+const END_MARKER = "<!-- END generated: by-concept -->";
+const ANCHOR_HEADING = "## Invariants";
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	".turbo",
+	".next",
+	"coverage"
+]);
+function parseFrontmatter(text) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text);
+	if (!m) return null;
+	const fm = {
+		concepts: [],
+		model: false
+	};
+	const lines = m[1].split("\n").map((l) => l.replace(/\r$/, ""));
+	for (let i = 0; i < lines.length; i++) {
+		const line = lines[i];
+		if (line.trim() === "" || line.trim().startsWith("#")) continue;
+		if (line.length - line.trimStart().length !== 0) continue;
+		const [key, ...rest] = line.trim().split(":");
+		const value = rest.join(":").trim();
+		if (key === "spec-type") fm.specType = unquote(value);
+		else if (key === "model") fm.model = unquote(value) === "true";
+		else if (key === "concept") {
+			if (value === "" || value === "|" || value === ">") for (let j = i + 1; j < lines.length; j++) {
+				const item = lines[j];
+				if (item.trim() === "") continue;
+				if (item.length - item.trimStart().length === 0) break;
+				const dash = /^\s*-\s+(.*)$/.exec(item);
+				if (dash) fm.concepts.push(unquote(dash[1].trim()));
+			}
+			else fm.concepts.push(...parseScalarOrFlow(value));
+		}
+	}
+	return fm;
+}
+function parseScalarOrFlow(value) {
+	const v = value.trim();
+	if (v.startsWith("[") && v.endsWith("]")) return v.slice(1, -1).split(",").map((s) => unquote(s.trim())).filter((s) => s.length > 0);
+	const single = unquote(v);
+	return single.length > 0 ? [single] : [];
+}
+function unquote(v) {
+	return v.replace(/^["']|["']$/g, "");
+}
+function facetKind(relPath, specType) {
+	const p = relPath.replace(/\\/g, "/");
+	if (p.startsWith("design/")) return "rule";
+	if (p.startsWith("workflows/")) return "workflow";
+	if (specType === "reference") return "reference";
+	if (specType === "behavioral") return "behavior";
+	return "index";
+}
+function displayPath(relPath) {
+	const p = relPath.replace(/\\/g, "/");
+	return p.endsWith("/README.md") ? p.slice(0, -9) : p;
+}
+function scanProjectSpec(specDir) {
+	const records = [];
+	walk(specDir, specDir, records);
+	return records;
+}
+function walk(dir, specDir, out) {
+	for (const entry of readdirSync(dir, { withFileTypes: true })) {
+		if (entry.name.startsWith(".") || SKIP_DIRS.has(entry.name)) continue;
+		const full = join(dir, entry.name);
+		if (entry.isDirectory()) walk(full, specDir, out);
+		else if (entry.name.endsWith(".md")) {
+			const fm = parseFrontmatter(readFileSync(full, "utf8"));
+			if (!fm || fm.concepts.length === 0) continue;
+			const relPath = relative(specDir, full).replace(/\\/g, "/");
+			out.push({
+				relPath,
+				display: displayPath(relPath),
+				concepts: fm.concepts,
+				facet: facetKind(relPath, fm.specType)
+			});
+		}
+	}
+}
+function groupByConcept(records) {
+	const grouped = /* @__PURE__ */ new Map();
+	for (const rec of records) for (const concept of rec.concepts) {
+		const list = grouped.get(concept) ?? [];
+		list.push(rec);
+		grouped.set(concept, list);
+	}
+	return new Map([...grouped.entries()].sort(([a], [b]) => a.localeCompare(b)).map(([k, v]) => [k, [...v].sort((x, y) => x.display.localeCompare(y.display))]));
+}
+function renderTable(grouped) {
+	return [
+		"| Concept | Facets |",
+		"|---|---|",
+		...[...grouped.entries()].map(([concept, nodes]) => {
+			return `| \`${concept}\` | ${nodes.map((n) => `\`${n.display}\` (${n.facet})`).join(" · ")} |`;
+		})
+	].join("\n");
+}
+function renderSection(grouped) {
+	return [
+		BEGIN_MARKER,
+		"",
+		"## By concept",
+		"",
+		"> Generated from `concept:` frontmatter by `project-spec/concept-index` — do not edit by hand.",
+		"",
+		renderTable(grouped),
+		"",
+		END_MARKER
+	].join("\n");
+}
+function applySection(specText, section) {
+	const begin = specText.indexOf(BEGIN_MARKER);
+	const end = specText.indexOf(END_MARKER);
+	if (begin !== -1 && end !== -1 && end > begin) {
+		const before = specText.slice(0, begin);
+		const after = specText.slice(end + 34);
+		return before + section + after;
+	}
+	const anchor = specText.indexOf(ANCHOR_HEADING);
+	if (anchor !== -1) return specText.slice(0, anchor) + section + "\n\n" + specText.slice(anchor);
+	return `${specText.replace(/\s*$/, "")}\n\n${section}\n`;
+}
+function extractSection(specText) {
+	const begin = specText.indexOf(BEGIN_MARKER);
+	const end = specText.indexOf(END_MARKER);
+	if (begin === -1 || end === -1 || end < begin) return null;
+	return specText.slice(begin, end + 34);
+}
+function parseArgs(argv) {
+	let specDir = ".";
+	let mode = "print";
+	for (let i = 0; i < argv.length; i++) {
+		const a = argv[i];
+		if (a === "--spec-dir") specDir = argv[++i] ?? ".";
+		else if (a === "--write") mode = "write";
+		else if (a === "--check") mode = "check";
+	}
+	return {
+		specDir,
+		mode
+	};
+}
+function main(argv) {
+	const { specDir, mode } = parseArgs(argv);
+	const section = renderSection(groupByConcept(scanProjectSpec(specDir)));
+	const specPath = join(specDir, "spec.md");
+	if (mode === "print") {
+		process.stdout.write(`${section}\n`);
+		return 0;
+	}
+	if (!existsSync(specPath)) {
+		process.stderr.write(`concept-index: no spec.md at ${specPath}\n`);
+		return 2;
+	}
+	const specText = readFileSync(specPath, "utf8");
+	if (mode === "check") {
+		if (extractSection(specText) === section) {
+			process.stdout.write("concept-index: no drift\n");
+			return 0;
+		}
+		process.stderr.write("concept-index: drift — spec.md by-concept block is stale; run --write\n");
+		return 1;
+	}
+	const next = applySection(specText, section);
+	if (next !== specText) writeFileSync(specPath, next);
+	process.stdout.write(`concept-index: ${next === specText ? "unchanged" : "updated"} ${specPath}\n`);
+	return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { BEGIN_MARKER, END_MARKER, applySection, extractSection, facetKind, groupByConcept, main, parseFrontmatter, parseScalarOrFlow, renderSection, renderTable, scanProjectSpec };

package/dist/discover-specs/scripts/discover-specs.js

@@ -0,0 +1,318 @@
+import { existsSync, readFileSync, readdirSync, realpathSync } from "node:fs";
+import { join } from "node:path";
+import { pathToFileURL } from "node:url";
+//#region skills/discover-specs/scripts/discover-specs.mts
+const LIFECYCLE_STATUSES = /* @__PURE__ */ new Set([
+	"draft",
+	"approved",
+	"implemented",
+	"deprecated"
+]);
+const ROOT_PROJECT_NAME = "repo";
+const SKIP_DIRS = /* @__PURE__ */ new Set([
+	"node_modules",
+	".git",
+	"dist",
+	".turbo",
+	".next",
+	"coverage"
+]);
+/**
+* A directory that is itself a checkout is a DIFFERENT repository's tree, not part of this corpus.
+*
+* A name blocklist cannot express this: it can only say "this is called X", never "this is a
+* boundary". `SKIP_DIRS` already holds `.git`, so the walk skipped the METADATA directory while
+* descending straight into the checkout that directory marks — one level off from where the guard
+* was needed. Agent-harness worktree isolation checks this repo out inside itself, and the scan then
+* found the whole corpus once per worktree: 38 spec files where 10 exist, and every corpus-wide
+* guard silently auditing a tree nobody has.
+*
+* `.git` is a DIRECTORY in a clone and a FILE in a worktree or submodule, so both forms count.
+*/
+function isNestedCheckout(abs) {
+	return existsSync(join(abs, ".git"));
+}
+const ANCHORS_CONFIG = ".agents/sdd/spec-anchors.toml";
+function parseFrontmatter(text) {
+	const m = /^---\r?\n([\s\S]*?)\r?\n---\s*(?:\r?\n|$)/.exec(text);
+	if (!m) return null;
+	const fm = { approval: {} };
+	let gate = null;
+	for (const raw of m[1].split("\n")) {
+		const line = raw.replace(/\r$/, "");
+		if (line.trim() === "" || line.trim().startsWith("#")) continue;
+		const indent = line.length - line.trimStart().length;
+		const [key, ...rest] = line.trim().split(":");
+		const value = rest.join(":").trim();
+		if (indent === 0) {
+			gate = null;
+			if (key === "status") fm.status = unquote(value);
+			else if (key === "project-path") fm.projectPath = unquote(value);
+			else if (key === "name") fm.name = unquote(value);
+			else if (key === "approval") gate = null;
+		} else if (indent === 2 && value === "" && insideApproval(m[1], line)) gate = key;
+		else if (indent >= 4 && key === "verdict" && gate) fm.approval[gate] = unquote(value);
+	}
+	return fm;
+}
+function insideApproval(block, line) {
+	const lines = block.split("\n");
+	const idx = lines.indexOf(line);
+	for (let i = idx - 1; i >= 0; i--) {
+		const l = lines[i].replace(/\r$/, "");
+		if (l.trim() === "" || l.trim().startsWith("#")) continue;
+		if (l.length - l.trimStart().length === 0) return l.trim().replace(/:.*$/, "") === "approval";
+	}
+	return false;
+}
+function unquote(v) {
+	return v.replace(/^["']|["']$/g, "");
+}
+function classifyLocation(relPath) {
+	const p = relPath.replace(/\\/g, "/");
+	if (p === ".agents/spec/spec.md") return {
+		pattern: "root-single",
+		locationDir: ""
+	};
+	const multi = /^\.agents\/specs\/([^/]+)\/spec\.md$/.exec(p);
+	if (multi) return {
+		pattern: "root-multi",
+		locationDir: multi[1]
+	};
+	const nested = /^(.+)\/\.agents\/spec\/spec\.md$/.exec(p);
+	if (nested) return {
+		pattern: "nested",
+		locationDir: nested[1]
+	};
+	return null;
+}
+function deriveName(loc, fm) {
+	if (fm.name) return {
+		name: fm.name,
+		nameSource: "declared"
+	};
+	if (loc.pattern === "root-single") return {
+		name: ROOT_PROJECT_NAME,
+		nameSource: "derived"
+	};
+	if (loc.pattern === "root-multi") return {
+		name: loc.locationDir,
+		nameSource: "derived"
+	};
+	if (loc.pattern === "extra" && loc.capturedName) return {
+		name: loc.capturedName,
+		nameSource: "derived"
+	};
+	return {
+		name: loc.locationDir.split("/").pop() ?? loc.locationDir,
+		nameSource: "guessed"
+	};
+}
+function discoverSpecFiles(root) {
+	const found = [];
+	const walk = (relDir) => {
+		let entries;
+		try {
+			entries = readdirSync(join(root, relDir), { withFileTypes: true });
+		} catch {
+			return;
+		}
+		for (const e of entries) {
+			if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue;
+			const childRel = relDir ? `${relDir}/${e.name}` : e.name;
+			if (isNestedCheckout(join(root, childRel))) continue;
+			if (e.name === ".agents") {
+				probeAgents(root, childRel, found);
+				continue;
+			}
+			walk(childRel);
+		}
+	};
+	walk("");
+	return found;
+}
+function probeAgents(root, agentsRel, found) {
+	const single = `${agentsRel}/spec/spec.md`;
+	if (existsSync(join(root, single))) found.push(single);
+	if (agentsRel === ".agents") {
+		const specsDir = join(root, ".agents", "specs");
+		let projects;
+		try {
+			projects = readdirSync(specsDir, { withFileTypes: true });
+		} catch {
+			projects = [];
+		}
+		for (const p of projects) {
+			if (!p.isDirectory()) continue;
+			const rel = `.agents/specs/${p.name}/spec.md`;
+			if (existsSync(join(root, rel))) found.push(rel);
+		}
+	}
+}
+function parseAnchorsToml(text) {
+	const m = /(^|\n)\s*anchors\s*=\s*\[([\s\S]*?)\]/.exec(text);
+	if (!m) return [];
+	const out = [];
+	for (const q of m[2].matchAll(/"([^"]*)"|'([^']*)'/g)) out.push((q[1] ?? q[2]).trim());
+	return out.filter((s) => s !== "");
+}
+function readAnchors(root) {
+	const file = join(root, ANCHORS_CONFIG);
+	if (!existsSync(file)) return [];
+	try {
+		return parseAnchorsToml(readFileSync(file, "utf8"));
+	} catch {
+		process.stderr.write(`discover-specs: ignoring unreadable ${ANCHORS_CONFIG}\n`);
+		return [];
+	}
+}
+function collectDescendants(root, startDir) {
+	const out = [startDir];
+	let entries;
+	try {
+		entries = readdirSync(join(root, startDir), { withFileTypes: true });
+	} catch {
+		return out;
+	}
+	for (const e of entries) {
+		if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue;
+		const childRel = startDir ? `${startDir}/${e.name}` : e.name;
+		if (isNestedCheckout(join(root, childRel))) continue;
+		out.push(...collectDescendants(root, childRel));
+	}
+	return out;
+}
+function expandAnchor(root, pattern) {
+	const segs = pattern.replace(/\\/g, "/").replace(/^\/+|\/+$/g, "").split("/").filter(Boolean);
+	let frontier = [{ dir: "" }];
+	for (const seg of segs) {
+		const next = [];
+		if (seg === "**") {
+			for (const node of frontier) for (const dir of collectDescendants(root, node.dir)) next.push({
+				dir,
+				capturedName: node.capturedName
+			});
+			frontier = next;
+			continue;
+		}
+		const isGlob = seg === "*" || seg === "<project>";
+		for (const node of frontier) if (isGlob) {
+			let entries;
+			try {
+				entries = readdirSync(join(root, node.dir), { withFileTypes: true });
+			} catch {
+				continue;
+			}
+			for (const e of entries) {
+				if (!e.isDirectory() || SKIP_DIRS.has(e.name)) continue;
+				const childRel = node.dir ? `${node.dir}/${e.name}` : e.name;
+				if (isNestedCheckout(join(root, childRel))) continue;
+				next.push({
+					dir: childRel,
+					capturedName: seg === "<project>" ? e.name : node.capturedName
+				});
+			}
+		} else next.push({
+			dir: node.dir ? `${node.dir}/${seg}` : seg,
+			capturedName: node.capturedName
+		});
+		frontier = next;
+	}
+	const out = [];
+	for (const node of frontier) {
+		const rel = node.dir ? `${node.dir}/spec.md` : "spec.md";
+		if (existsSync(join(root, rel))) out.push({
+			rel,
+			capturedName: node.capturedName
+		});
+	}
+	return out;
+}
+function recordFor(root, rel, loc) {
+	let fm;
+	try {
+		fm = parseFrontmatter(readFileSync(join(root, rel), "utf8"));
+	} catch {
+		return null;
+	}
+	if (!fm?.status || !LIFECYCLE_STATUSES.has(fm.status)) return null;
+	const { name, nameSource } = deriveName(loc, fm);
+	return {
+		path: rel.replace(/\/spec\.md$/, ""),
+		name,
+		nameSource,
+		status: fm.status,
+		projectPath: fm.projectPath ?? "",
+		approvals: Object.entries(fm.approval).map(([gate, verdict]) => `${gate}:${verdict}`).join(";")
+	};
+}
+function collectSpecs(root) {
+	const out = [];
+	const seen = /* @__PURE__ */ new Set();
+	for (const rel of discoverSpecFiles(root)) {
+		const loc = classifyLocation(rel);
+		if (!loc) continue;
+		const rec = recordFor(root, rel, loc);
+		if (rec) {
+			out.push(rec);
+			seen.add(rel);
+		}
+	}
+	for (const pattern of readAnchors(root)) for (const { rel, capturedName } of expandAnchor(root, pattern)) {
+		if (seen.has(rel)) continue;
+		const rec = recordFor(root, rel, {
+			pattern: "extra",
+			locationDir: rel.replace(/\/spec\.md$/, ""),
+			capturedName
+		});
+		if (rec) {
+			out.push(rec);
+			seen.add(rel);
+		}
+	}
+	return out.sort((a, b) => a.path < b.path ? -1 : a.path > b.path ? 1 : 0);
+}
+function resolveByName(specs, name) {
+	const want = name.trim().toLowerCase();
+	const hits = specs.filter((s) => s.name.toLowerCase() === want);
+	if (hits.length === 0) return { kind: "none" };
+	if (hits.length === 1) return {
+		kind: "match",
+		spec: hits[0]
+	};
+	return {
+		kind: "ambiguous",
+		candidates: hits
+	};
+}
+const COLUMNS = [
+	"path",
+	"name",
+	"nameSource",
+	"status",
+	"projectPath",
+	"approvals"
+];
+function toonField(v) {
+	if (v === "" || /[",]/.test(v) || v !== v.trim()) return `"${v.replace(/"/g, "\"\"")}"`;
+	return v;
+}
+function toToon(specs) {
+	return [`specs[${specs.length}]{${COLUMNS.join(",")}}:`, ...specs.map((s) => `  ${COLUMNS.map((c) => toonField(s[c])).join(",")}`)].join("\n");
+}
+function main(argv) {
+	const root = argv.includes("--root") ? argv[argv.indexOf("--root") + 1] ?? "." : ".";
+	const format = argv.includes("--format") ? argv[argv.indexOf("--format") + 1] : "toon";
+	let specs = collectSpecs(root);
+	if (argv.includes("--resolve")) {
+		const name = argv[argv.indexOf("--resolve") + 1] ?? "";
+		const r = resolveByName(specs, name);
+		specs = r.kind === "match" ? [r.spec] : r.kind === "ambiguous" ? r.candidates : [];
+	}
+	const out = format === "json" ? JSON.stringify(specs, null, 2) : toToon(specs);
+	process.stdout.write(`${out}\n`);
+	return 0;
+}
+if (process.argv[1] && import.meta.url === pathToFileURL(realpathSync(process.argv[1])).href) process.exit(main(process.argv.slice(2)));
+//#endregion
+export { LIFECYCLE_STATUSES, classifyLocation, collectSpecs, deriveName, discoverSpecFiles, expandAnchor, main, parseAnchorsToml, parseFrontmatter, readAnchors, resolveByName, toToon };