rulebookguard 0.2.0 → 0.3.0

package/README.md

@@ -13,7 +13,7 @@ It is language-agnostic: rules are Markdown, and tests in any language link to t
 
 ## Install
 
-Requires Node.js 22 or later.
+Requires Node.js 22.23.4 or later (the `site` command builds with Astro 7, which needs it).
 
 ```sh
 npx rulebookguard lint
@@ -260,6 +260,26 @@ An [MCP](https://modelcontextprotocol.io) server over stdio for AI agents, with
 
 The rulebook is found from `--project` (default: the current directory). A command that would fail answers a tool error carrying the same message the CLI prints, for example `Unknown rule id "R-NOPE-001". Run "rulebookguard list" to list them.`
 
+### `site [--out <dir>] [--base <path>]`
+
+Builds a read-only static site of the rulebook with [Astro Starlight](https://starlight.astro.build) into `--out` (default `site`, relative to the current directory) and prints that path. Open it from disk or publish it as is, for example on GitHub Pages; pass `--base` when it is served from a sub-path (`--base /rules`).
+
+```sh
+$ rulebookguard site --out public/rules --base /rules
+public/rules
+```
+
+The site has:
+
+- **Home:** the contexts map, with how many rules of each status every context holds.
+- **A page per context** with its description and rules.
+- **All rules:** one table filterable by text, context and status.
+- **A page per rule:** summary, status, entities, rule file, the supersedes chain both ways, the rule text, its anchors and the files they match, the tests tagging it, and the git history of the rule file.
+- **Health:** the `lint` findings when the site was built.
+- Full-text search (Pagefind).
+
+Generated text and the interface follow `language` in the config. The site is a view: rules are still edited in their files, through pull requests. `site` replaces `--out` only when it is empty or was written by an earlier `site`; any other non-empty directory makes it fail, exit 1, without touching it. Add the output directory to `.gitignore` unless you mean to commit it.
+
 ### `lint [--base <ref>] [--json]`
 
 Checks the whole catalog. Each finding is printed as `<severity> <code> <file>[:line] <message>`, followed by a count.

package/dist/anchors-BFJCm1NU.mjs

@@ -0,0 +1,10 @@
+import { h as createGlobMatcher, v as toRepoPath } from "./lint-C1yUeLOq.mjs";
+// src/catalog/anchors.ts
+function rulesForPath(rules, path) {
+	const target = toRepoPath(path);
+	return rules.filter((rule) => createGlobMatcher(rule.anchors)(target)).sort((a, b) => compare(a.id, b.id));
+}
+function compare(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+export { rulesForPath as t };

package/dist/cli.mjs

@@ -1,5 +1,6 @@
 #!/usr/bin/env node
-import { M as FormatError, N as formatIssue, _ as expandGlobs, a as CliError, c as openCatalog, d as scanTestTags, f as findRulebookRoot, h as rulesForPath, l as writeJson, o as findRule, p as loadCatalog, r as lintCommand, s as gitFallbackWarning, u as writeLines, y as toRepoPath } from "./lint-DtD_Ekei.mjs";
+import { M as FormatError, N as formatIssue, a as CliError, c as openCatalog, d as scanTestTags, f as findRulebookRoot, g as expandGlobs, l as writeJson, o as findRule, p as loadCatalog, r as lintCommand, s as gitFallbackWarning, u as writeLines, v as toRepoPath } from "./lint-C1yUeLOq.mjs";
+import { t as rulesForPath } from "./anchors-BFJCm1NU.mjs";
 import { readdir, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
@@ -79,7 +80,7 @@ function render(path, rules, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.2.0";
+var version = "0.3.0";
 // src/mcp/server.ts
 function createRulesServer(projectDir) {
 	const server = new McpServer({
@@ -328,6 +329,8 @@ Commands:
                                                      and prints the rules anchored to the edited file
   mcp [--project <dir>]                              MCP server over stdio with rules_for and rules_show;
                                                      --project: directory to find the rulebook from (default: cwd)
+  site [--out <dir>] [--base <path>]                 build the read-only static site of the rulebook;
+                                                     --out: output directory (default: site), --base: URL path
 
 Exit codes: 0 success, 1 failure (lint: any error), 2 usage error.
 `;
@@ -373,6 +376,13 @@ const COMMANDS = {
 		usage: "rulebookguard mcp [--project <dir>]",
 		options: { project: { type: "string" } }
 	},
+	site: {
+		usage: "rulebookguard site [--out <dir>] [--base <path>]",
+		options: {
+			out: { type: "string" },
+			base: { type: "string" }
+		}
+	},
 	lint: {
 		usage: "rulebookguard lint [--base <ref>] [--json]",
 		options: {
@@ -414,6 +424,14 @@ async function dispatch(argv, io) {
 		await mcpCommand(io, values.project);
 		return 0;
 	}
+	if (name === "site") {
+		const { siteCommand } = await import("./site-DYOm-dEC.mjs");
+		await siteCommand(io, {
+			out: values.out,
+			base: values.base
+		});
+		return 0;
+	}
 	if (name === "lint") return lintCommand(io, {
 		base: values.base,
 		json

package/dist/index.mjs

@@ -1 +1,3 @@
-export { k as CONFIG_FILE_NAME, T as CONTEXT_FILE_NAME, M as FormatError, b as RULE_TAG_PATTERN, g as createGlobMatcher, _ as expandGlobs, x as findRuleTags, f as findRulebookRoot, t as formatFinding, N as formatIssue, S as isRuleId, n as lintCatalog, v as listRepoFiles, p as loadCatalog, A as loadConfig, E as loadContext, C as loadRule, j as parseConfig, D as parseContext, w as parseRule, i as pendingImplementation, m as relativeToRoot, h as rulesForPath, d as scanTestTags, O as splitFrontmatter, y as toRepoPath } from "./lint-DtD_Ekei.mjs";
+import { A as loadConfig, C as loadRule, D as parseContext, E as loadContext, M as FormatError, N as formatIssue, O as splitFrontmatter, S as isRuleId, T as CONTEXT_FILE_NAME, _ as listRepoFiles, b as RULE_TAG_PATTERN, d as scanTestTags, f as findRulebookRoot, g as expandGlobs, h as createGlobMatcher, i as pendingImplementation, j as parseConfig, k as CONFIG_FILE_NAME, m as relativeToRoot, n as lintCatalog, p as loadCatalog, t as formatFinding, v as toRepoPath, w as parseRule, x as findRuleTags } from "./lint-C1yUeLOq.mjs";
+import { t as rulesForPath } from "./anchors-BFJCm1NU.mjs";
+export { CONFIG_FILE_NAME, CONTEXT_FILE_NAME, FormatError, RULE_TAG_PATTERN, createGlobMatcher, expandGlobs, findRuleTags, findRulebookRoot, formatFinding, formatIssue, isRuleId, lintCatalog, listRepoFiles, loadCatalog, loadConfig, loadContext, loadRule, parseConfig, parseContext, parseRule, pendingImplementation, relativeToRoot, rulesForPath, scanTestTags, splitFrontmatter, toRepoPath };

package/dist/{lint-DtD_Ekei.mjs → lint-C1yUeLOq.mjs}

@@ -452,14 +452,6 @@ async function walk(root, prefix, files) {
 		} else if (entry.isFile()) files.push(path);
 	}
 }
-// src/catalog/anchors.ts
-function rulesForPath(rules, path) {
-	const target = toRepoPath(path);
-	return rules.filter((rule) => createGlobMatcher(rule.anchors)(target)).sort((a, b) => compare$1(a.id, b.id));
-}
-function compare$1(a, b) {
-	return a < b ? -1 : a > b ? 1 : 0;
-}
 // src/catalog/load.ts
 async function findRulebookRoot(start) {
 	let directory = resolve(start);
@@ -760,4 +752,4 @@ function plural(count, noun) {
 function compare(a, b) {
 	return a < b ? -1 : a > b ? 1 : 0;
 }
-export { loadConfig as A, loadRule as C, parseContext as D, loadContext as E, FormatError as M, formatIssue as N, splitFrontmatter as O, isRuleId as S, CONTEXT_FILE_NAME as T, expandGlobs as _, CliError as a, RULE_TAG_PATTERN as b, openCatalog as c, scanTestTags as d, findRulebookRoot as f, createGlobMatcher as g, rulesForPath as h, pendingImplementation as i, parseConfig as j, CONFIG_FILE_NAME as k, writeJson as l, relativeToRoot as m, lintCatalog as n, findRule as o, loadCatalog as p, lintCommand as r, gitFallbackWarning as s, formatFinding as t, writeLines as u, listRepoFiles as v, parseRule as w, findRuleTags as x, toRepoPath as y };
+export { loadConfig as A, loadRule as C, parseContext as D, loadContext as E, FormatError as M, formatIssue as N, splitFrontmatter as O, isRuleId as S, CONTEXT_FILE_NAME as T, listRepoFiles as _, CliError as a, RULE_TAG_PATTERN as b, openCatalog as c, scanTestTags as d, findRulebookRoot as f, expandGlobs as g, createGlobMatcher as h, pendingImplementation as i, parseConfig as j, CONFIG_FILE_NAME as k, writeJson as l, relativeToRoot as m, lintCatalog as n, findRule as o, loadCatalog as p, lintCommand as r, gitFallbackWarning as s, formatFinding as t, writeLines as u, toRepoPath as v, parseRule as w, findRuleTags as x, runGit as y };

package/dist/site-DYOm-dEC.mjs

@@ -0,0 +1,491 @@
+import { a as CliError, c as openCatalog, d as scanTestTags, g as expandGlobs, n as lintCatalog, s as gitFallbackWarning, u as writeLines, y as runGit } from "./lint-C1yUeLOq.mjs";
+import { cp, mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { randomUUID } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+// src/site/data.ts
+const FIELD = "";
+async function siteData(catalog, onGitFallback) {
+	const tags = await scanTestTags(catalog.root, catalog.config.testGlobs, onGitFallback);
+	const byId = new Map(catalog.rules.map((rule) => [rule.id, rule]));
+	const rules = [...catalog.rules].sort((a, b) => compare(a.id, b.id));
+	return {
+		contexts: [...catalog.contexts].sort((a, b) => compare(a.context, b.context)),
+		rules: await Promise.all(rules.map(async (rule) => ({
+			rule,
+			files: await expandGlobs(catalog.root, rule.anchors, onGitFallback),
+			tests: tags.get(rule.id) ?? [],
+			history: await history(catalog.root, rule.file),
+			supersedes: chain(rule, byId),
+			supersededBy: rules.find((other) => other.supersedes === rule.id)?.id
+		}))),
+		findings: await lintCatalog(catalog, tags, onGitFallback)
+	};
+}
+function chain(rule, byId) {
+	const ids = [];
+	for (let next = rule.supersedes; next !== void 0; next = byId.get(next)?.supersedes) {
+		ids.push(next);
+		if (next === rule.id || ids.indexOf(next) !== ids.length - 1) break;
+	}
+	return ids;
+}
+async function history(root, file) {
+	let output;
+	try {
+		output = await runGit(root, [
+			"log",
+			"--follow",
+			`--format=%h${FIELD}%as${FIELD}%an${FIELD}%s`,
+			"--",
+			file
+		]);
+	} catch {
+		return [];
+	}
+	return output.split("\n").filter((line) => line !== "").map((line) => {
+		const [hash = "", date = "", author = "", subject = ""] = line.split(FIELD);
+		return {
+			hash,
+			date,
+			author,
+			subject
+		};
+	});
+}
+function compare(a, b) {
+	return a < b ? -1 : a > b ? 1 : 0;
+}
+// src/site/pages.ts
+const STATUSES = [
+	"active",
+	"proposed",
+	"deprecated"
+];
+const TEXT = {
+	en: {
+		title: "Business rules",
+		homeIntro: "The business rules of this repository: the source of truth that the code implements and the tests verify.",
+		contexts: "Contexts",
+		context: "Context",
+		prefix: "Prefix",
+		summary: "Summary",
+		allRules: "All rules",
+		health: "Health",
+		rule: "Rule",
+		status: "Status",
+		entities: "Entities",
+		supersedes: "Supersedes",
+		supersededBy: "Superseded by",
+		ruleFile: "Rule file",
+		ruleText: "Rule",
+		anchors: "Anchors",
+		matchedFiles: "Files matched by the anchors",
+		tests: "Tests",
+		history: "History",
+		date: "Date",
+		commit: "Commit",
+		author: "Author",
+		change: "Change",
+		noHistory: "No git history.",
+		none: "None.",
+		search: "Search rules",
+		anyContext: "Any context",
+		anyStatus: "Any status",
+		noMatch: "No rule matches the filters.",
+		severity: "Severity",
+		code: "Code",
+		file: "File",
+		line: "Line",
+		message: "Message",
+		noIssues: "No issues found.",
+		counts: (errors, warnings) => `${errors} ${errors === 1 ? "error" : "errors"}, ${warnings} ${warnings === 1 ? "warning" : "warnings"}`,
+		healthIntro: "Findings of `rulebookguard lint` when the site was built."
+	},
+	es: {
+		title: "Reglas de negocio",
+		homeIntro: "Las reglas de negocio de este repositorio: la fuente de verdad que el código implementa y los tests verifican.",
+		contexts: "Contextos",
+		context: "Contexto",
+		prefix: "Prefijo",
+		summary: "Resumen",
+		allRules: "Todas las reglas",
+		health: "Salud",
+		rule: "Regla",
+		status: "Estado",
+		entities: "Entidades",
+		supersedes: "Reemplaza a",
+		supersededBy: "Reemplazada por",
+		ruleFile: "Archivo de la regla",
+		ruleText: "Regla",
+		anchors: "Anclas",
+		matchedFiles: "Archivos que coinciden con las anclas",
+		tests: "Tests",
+		history: "Historial",
+		date: "Fecha",
+		commit: "Commit",
+		author: "Autor",
+		change: "Cambio",
+		noHistory: "Sin historial de git.",
+		none: "Ninguno.",
+		search: "Buscar reglas",
+		anyContext: "Cualquier contexto",
+		anyStatus: "Cualquier estado",
+		noMatch: "Ninguna regla coincide con los filtros.",
+		severity: "Severidad",
+		code: "Código",
+		file: "Archivo",
+		line: "Línea",
+		message: "Mensaje",
+		noIssues: "No se encontraron problemas.",
+		counts: (errors, warnings) => `${errors} ${errors === 1 ? "error" : "errores"}, ${warnings} ${warnings === 1 ? "advertencia" : "advertencias"}`,
+		healthIntro: "Hallazgos de `rulebookguard lint` al momento de generar el sitio."
+	}
+};
+function siteText(language) {
+	return TEXT[language];
+}
+function normalizeBase(base) {
+	const trimmed = base.replace(/^\/+|\/+$/g, "");
+	return trimmed === "" ? "/" : `/${trimmed}/`;
+}
+function sitePages(data, options) {
+	const text = TEXT[options.language];
+	const base = normalizeBase(options.base);
+	const rulePath = new Map(data.rules.map(({ rule }) => [rule.id, `${base}${rule.context}/${rule.id.toLowerCase()}/`]));
+	const ruleByFile = new Map(data.rules.map(({ rule }) => [rule.file, rule.id]));
+	const ruleLink = (id) => {
+		const path = rulePath.get(id);
+		return path === void 0 ? id : `[${id}](${path})`;
+	};
+	const files = /* @__PURE__ */ new Map();
+	files.set("src/content.config.ts", `import { defineCollection } from 'astro:content';
+import { docsLoader } from '@astrojs/starlight/loaders';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = { docs: defineCollection({ loader: docsLoader(), schema: docsSchema() }) };
+`);
+	files.set("src/content/docs/index.md", page(text.title, text.homeIntro, [
+		text.homeIntro,
+		"",
+		`[${text.allRules}](${base}rules/) · [${text.health}](${base}health/)`,
+		"",
+		`## ${text.contexts}`,
+		"",
+		`| ${text.context} | ${text.prefix} | ${text.summary} | ${STATUSES.join(" | ")} |`,
+		`| --- | --- | --- | ${STATUSES.map(() => "---:").join(" | ")} |`,
+		...data.contexts.map((context) => {
+			const rules = data.rules.filter(({ rule }) => rule.context === context.context);
+			const counts = STATUSES.map((status) => rules.filter(({ rule }) => rule.status === status).length);
+			return `| [${context.context}](${base}${context.context}/) | ${context.prefix} | ${cell(context.summary)} | ${counts.join(" | ")} |`;
+		})
+	]));
+	for (const context of data.contexts) {
+		const rules = data.rules.filter(({ rule }) => rule.context === context.context);
+		files.set(`src/content/docs/${context.context}/index.md`, page(context.context, context.summary, [
+			`**${cell(context.summary)}**`,
+			"",
+			demote(context.body.trim()),
+			"",
+			`| ${text.rule} | ${text.status} | ${text.summary} |`,
+			"| --- | --- | --- |",
+			...rules.map(({ rule }) => `| ${ruleLink(rule.id)} | ${rule.status} | ${cell(rule.summary)} |`)
+		]));
+	}
+	for (const entry of data.rules) files.set(`src/content/docs/${entry.rule.context}/${entry.rule.id.toLowerCase()}.md`, rulePage(entry, text, base, ruleLink));
+	files.set("src/pages/rules.astro", rulesPage(data, text, rulePath));
+	const errors = data.findings.filter((finding) => finding.severity === "error").length;
+	const warnings = data.findings.length - errors;
+	files.set("src/content/docs/health.md", page(text.health, text.healthIntro, [
+		text.healthIntro,
+		"",
+		data.findings.length === 0 ? text.noIssues : `**${text.counts(errors, warnings)}**`,
+		"",
+		...data.findings.length === 0 ? [] : [
+			`| ${text.severity} | ${text.code} | ${text.file} | ${text.line} | ${text.message} |`,
+			"| --- | --- | --- | ---: | --- |",
+			...data.findings.map((finding) => {
+				const id = ruleByFile.get(finding.file);
+				const path = id === void 0 ? void 0 : rulePath.get(id);
+				const file = path === void 0 ? `\`${finding.file}\`` : `[${finding.file}](${path})`;
+				return `| ${finding.severity} | ${finding.code} | ${file} | ${finding.line ?? ""} | ${cell(finding.message)} |`;
+			})
+		]
+	]));
+	return files;
+}
+function rulePage({ rule, files, tests, history, supersedes, supersededBy }, text, base, ruleLink) {
+	const rows = [
+		[text.status, rule.status],
+		[text.context, `[${rule.context}](${base}${rule.context}/)`],
+		[text.entities, rule.entities.length === 0 ? "—" : rule.entities.map(cell).join(", ")],
+		[text.ruleFile, `\`${rule.file}\``]
+	];
+	if (supersedes.length > 0) rows.push([text.supersedes, supersedes.map(ruleLink).join(" → ")]);
+	if (supersededBy !== void 0) rows.push([text.supersededBy, ruleLink(supersededBy)]);
+	return page(rule.id, rule.summary, [
+		`**${cell(rule.summary)}**`,
+		"",
+		"| | |",
+		"| --- | --- |",
+		...rows.map(([label, value]) => `| ${label} | ${value} |`),
+		"",
+		`## ${text.ruleText}`,
+		"",
+		demote(rule.body.trim()),
+		"",
+		`## ${text.anchors}`,
+		"",
+		...list(rule.anchors.map((anchor) => `\`${anchor}\``), text.none),
+		"",
+		`### ${text.matchedFiles} (${files.length})`,
+		"",
+		...list(files.map((file) => `\`${file}\``), text.none),
+		"",
+		`## ${text.tests} (${tests.length})`,
+		"",
+		...list(tests.map((test) => `\`${test.file}:${test.line}\``), text.none),
+		"",
+		`## ${text.history}`,
+		"",
+		...history.length === 0 ? [text.noHistory] : [
+			`| ${text.date} | ${text.commit} | ${text.author} | ${text.change} |`,
+			"| --- | --- | --- | --- |",
+			...history.map((commit) => `| ${commit.date} | \`${commit.hash}\` | ${cell(commit.author)} | ${cell(commit.subject)} |`)
+		]
+	]);
+}
+function rulesPage(data, text, rulePath) {
+	const contexts = data.contexts.map((context) => context.context);
+	const rows = data.rules.map(({ rule }) => {
+		const search = [
+			rule.id,
+			rule.context,
+			rule.summary
+		].join(" ").toLowerCase();
+		return `      <tr data-context="${html(rule.context)}" data-status="${rule.status}" data-search="${html(search)}">
+        <td><a href="${rulePath.get(rule.id) ?? ""}">${rule.id}</a></td>
+        <td>${html(rule.context)}</td>
+        <td>${rule.status}</td>
+        <td>${html(rule.summary)}</td>
+      </tr>`;
+	});
+	return `---
+import StarlightPage from "@astrojs/starlight/components/StarlightPage.astro";
+---
+
+<StarlightPage frontmatter={{ title: ${JSON.stringify(text.allRules)}, tableOfContents: false }}>
+  <div class="rbg-filters">
+    <input type="search" data-filter="search" placeholder="${html(text.search)}" aria-label="${html(text.search)}" />
+    <select data-filter="context" aria-label="${html(text.context)}">
+      <option value="">${html(text.anyContext)}</option>
+${contexts.map((context) => `      <option value="${html(context)}">${html(context)}</option>`).join("\n")}
+    </select>
+    <select data-filter="status" aria-label="${html(text.status)}">
+      <option value="">${html(text.anyStatus)}</option>
+${STATUSES.map((status) => `      <option value="${status}">${status}</option>`).join("\n")}
+    </select>
+  </div>
+  <table class="rbg-rules">
+    <thead>
+      <tr><th>${html(text.rule)}</th><th>${html(text.context)}</th><th>${html(text.status)}</th><th>${html(text.summary)}</th></tr>
+    </thead>
+    <tbody>
+${rows.join("\n")}
+    </tbody>
+  </table>
+  <p class="rbg-empty" hidden>${html(text.noMatch)}</p>
+</StarlightPage>
+
+<style>
+  .rbg-filters { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-bottom: 1rem; }
+  .rbg-filters input { flex: 1 1 16rem; }
+</style>
+
+<script>
+  const value = (name: string) =>
+    (document.querySelector<HTMLInputElement | HTMLSelectElement>(\`[data-filter="\${name}"]\`)?.value ?? '').trim().toLowerCase();
+  const apply = () => {
+    const search = value('search');
+    const context = value('context');
+    const status = value('status');
+    let shown = 0;
+    for (const row of document.querySelectorAll<HTMLTableRowElement>('.rbg-rules tbody tr')) {
+      const visible =
+        (search === '' || (row.dataset.search ?? '').includes(search)) &&
+        (context === '' || row.dataset.context === context) &&
+        (status === '' || row.dataset.status === status);
+      row.hidden = !visible;
+      if (visible) shown += 1;
+    }
+    const empty = document.querySelector<HTMLElement>('.rbg-empty');
+    if (empty) empty.hidden = shown > 0;
+  };
+  for (const control of document.querySelectorAll('[data-filter]')) {
+    control.addEventListener('input', apply);
+  }
+<\/script>
+`;
+}
+function page(title, description, lines) {
+	return [
+		"---",
+		`title: ${JSON.stringify(title)}`,
+		`description: ${JSON.stringify(description)}`,
+		"---",
+		"",
+		...lines,
+		""
+	].join("\n");
+}
+function list(items, empty) {
+	return items.length === 0 ? [empty] : items.map((item) => `- ${item}`);
+}
+/** Text inside a Markdown table cell. */
+function cell(text) {
+	return text.replaceAll("\\", "\\\\").replaceAll("|", "\\|").replaceAll("<", "&lt;");
+}
+/** Text inside the Astro page, where braces start expressions. */
+function html(text) {
+	return text.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;").replaceAll("\"", "&quot;").replaceAll("{", "&#123;").replaceAll("}", "&#125;");
+}
+/** Pushes the headings of a rule text two levels down, below the page's own sections. */
+function demote(markdown) {
+	let fence;
+	return markdown.split("\n").map((line) => {
+		const marker = /^\s*(```+|~~~+)/.exec(line)?.[1];
+		if (marker !== void 0) {
+			if (fence === void 0) fence = marker;
+			else if (marker.startsWith(fence)) fence = void 0;
+			return line;
+		}
+		if (fence === void 0 && /^#{1,4} /.test(line)) return `##${line}`;
+		return line;
+	}).join("\n");
+}
+// src/commands/site.ts
+const execFileAsync = promisify(execFile);
+/** Marks an output directory as written by `site`, so a rebuild may replace it. */
+const MARKER = ".rulebookguard-site";
+async function siteCommand(io, options) {
+	const catalog = await openCatalog(io);
+	const out = resolve(io.cwd, options.out ?? "site");
+	const fromCwd = relative(io.cwd, out);
+	const shown = fromCwd === "" ? "." : fromCwd.startsWith("..") || isAbsolute(fromCwd) ? out : fromCwd;
+	await assertReplaceable(out, shown);
+	const language = catalog.config.language ?? "en";
+	const base = normalizeBase(options.base ?? "/");
+	const files = sitePages(await siteData(catalog, gitFallbackWarning(io)), {
+		language,
+		base
+	});
+	const text = siteText(language);
+	const sidebar = [
+		{
+			label: text.allRules,
+			link: "/rules/"
+		},
+		{
+			label: text.health,
+			slug: "health"
+		},
+		...catalog.contexts.map((context) => context.context).sort().map((context) => ({
+			label: context,
+			items: [{ autogenerate: { directory: context } }]
+		}))
+	];
+	files.set("astro.config.mjs", astroConfig(text.title, language, base, sidebar));
+	const work = join(siteWorkRoot(), randomUUID());
+	try {
+		for (const [path, content] of files) {
+			await mkdir(dirname(join(work, path)), { recursive: true });
+			await writeFile(join(work, path), content);
+		}
+		await buildWithAstro(work);
+		await rm(out, {
+			recursive: true,
+			force: true
+		});
+		await cp(join(work, "dist"), out, { recursive: true });
+		await writeFile(join(out, MARKER), "");
+	} finally {
+		await rm(work, {
+			recursive: true,
+			force: true
+		});
+	}
+	writeLines(io, [shown]);
+}
+/**
+* Starlight injects its routes as package specifiers that Astro resolves from the project root, so the generated
+* project must live inside the node_modules directory that holds rulebookguard's own dependencies.
+*/
+function siteWorkRoot() {
+	let directory = dirname(fileURLToPath(import.meta.url));
+	while (!isOwnPackageRoot(directory)) {
+		const parent = dirname(directory);
+		if (parent === directory) throw new Error("rulebookguard package root not found");
+		directory = parent;
+	}
+	const parent = dirname(directory);
+	const modules = basename(parent) === "node_modules" ? parent : join(directory, "node_modules");
+	return join(modules, ".rulebookguard-site");
+}
+function isOwnPackageRoot(directory) {
+	const file = join(directory, "package.json");
+	return existsSync(file) && JSON.parse(readFileSync(file, "utf8")).name === "rulebookguard";
+}
+async function assertReplaceable(out, shown) {
+	let entries;
+	try {
+		entries = await readdir(out);
+	} catch (error) {
+		if (error.code === "ENOENT") return;
+		throw error;
+	}
+	if (entries.length > 0 && !entries.includes(MARKER)) throw new CliError(`${shown} is not empty and was not written by "rulebookguard site"; choose another --out or empty it first.`);
+}
+async function buildWithAstro(work) {
+	const astro = join(dirname(siteWorkRoot()), "astro");
+	const { bin } = JSON.parse(readFileSync(join(astro, "package.json"), "utf8"));
+	try {
+		await execFileAsync(process.execPath, [
+			join(astro, bin.astro),
+			"build",
+			"--silent"
+		], {
+			cwd: work,
+			env: {
+				...process.env,
+				ASTRO_TELEMETRY_DISABLED: "1"
+			},
+			maxBuffer: 67108864
+		});
+	} catch (error) {
+		const { stderr, stdout } = error;
+		const detail = `${stderr ?? ""}${stdout ?? ""}`.trim().split("\n").slice(-5).join("\n");
+		throw new CliError(`The site build failed:\n${detail}`);
+	}
+}
+function astroConfig(title, language, base, sidebar) {
+	return `import starlight from '@astrojs/starlight';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+  base: ${JSON.stringify(base)},
+  outDir: './dist',
+  cacheDir: './.astro-cache',
+  integrations: [
+    starlight({
+      title: ${JSON.stringify(title)},
+      locales: { root: { label: ${JSON.stringify(language)}, lang: ${JSON.stringify(language)} } },
+      sidebar: ${JSON.stringify(sidebar)},
+    }),
+  ],
+});
+`;
+}
+export { siteCommand };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Keep business rules as the single source of truth, bound to code and tests.",
   "homepage": "https://github.com/JuanCJR/rulebookguard#readme",
   "bugs": {
@@ -28,8 +28,11 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@astrojs/markdown-remark": "^7.3.2",
+    "@astrojs/starlight": "^0.42.6",
     "@modelcontextprotocol/server": "^2.3.1",
     "ajv": "^8.20.0",
+    "astro": "^7.3.8",
     "picomatch": "^4.0.7",
     "yaml": "^2.9.1",
     "zod": "^4.6.7"
@@ -42,6 +45,6 @@
     "vite-plus": "^1.4.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.23.4"
   }
 }