rulebookguard 0.1.1 → 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
@@ -236,6 +236,50 @@ docs/rules/clients/R-CLI-004.md
 
 Exits 1 for an unknown context or when the context has no free id left.
 
+### `hook`
+
+A Claude Code hook for `PreToolUse` and `PostToolUse` events of tools that take a `file_path` (the Claude Code plugin below wires it up). It reads the hook event as JSON on stdin, takes `tool_input.file_path` (relative paths resolve against the event's `cwd`), finds `rulebookguard.config.yaml` by walking up from that file, and prints the active rules anchored to it as additional context for Claude, under the same `hookEventName`:
+
+```sh
+$ echo '{"hook_event_name":"PostToolUse","tool_name":"Read","tool_input":{"file_path":"/repo/src/billing/invoice.go"}}' | rulebookguard hook
+{"hookSpecificOutput":{"hookEventName":"PostToolUse","additionalContext":"Business rules anchored to src/billing/invoice.go (rulebookguard). …"}}
+```
+
+Claude Code adds the context next to the tool result, so a `PostToolUse` hook on `Read` delivers the rules together with the file contents, before Claude writes a change (Claude Code requires reading a file before editing it).
+
+Each rule comes with its id, context, summary, rule file and full text; when the texts add up to more than 10,000 characters only the summaries are listed, with a pointer to `rulebookguard show <id>`. The header follows `language` in the config. The hook never blocks a tool and never answers the permission prompt: with no config, a path outside the rulebook root, no active rule, another event, unreadable input or any error, it prints nothing and exits 0.
+
+### `mcp [--project <dir>]`
+
+An [MCP](https://modelcontextprotocol.io) server over stdio for AI agents, with two read-only tools:
+
+| Tool         | Input                                                  | Answers                                       |
+| ------------ | ------------------------------------------------------ | --------------------------------------------- |
+| `rules_for`  | `path`: absolute, or relative to the project directory | what `rulebookguard for <path> --json` prints |
+| `rules_show` | `id`: a rule id                                        | what `rulebookguard show <id> --json` prints  |
+
+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.
@@ -295,9 +339,28 @@ jobs:
 
 Pin the version, or add rulebookguard as a dev dependency and run it from the lockfile, so a new release never changes CI results by itself.
 
+## Claude Code plugin
+
+The plugin in [`plugin/`](plugin) connects the rulebook to Claude Code:
+
+- **Hooks:** after every `Read` and before every `Write`, it runs `rulebookguard hook`, so Claude gets the active rules anchored to a file together with its contents, before it writes a change. A `Write` of a new file, which needs no `Read`, gets them right after the file is created.
+- **MCP server:** the `rules_for` and `rules_show` tools from `rulebookguard mcp`, for rules of files Claude has not opened yet.
+- **Skill** `rulebookguard:rules`: the protocol, that is, follow the rules, and change a rule (then its tests, then the code) only when the user asks for the behavior change.
+
+Install it from this repository's marketplace:
+
+```sh
+claude plugin marketplace add JuanCJR/rulebookguard
+claude plugin install rulebookguard@rulebookguard
+```
+
+Or, inside Claude Code 2.1.275 or later: `/plugin install rulebookguard --marketplace JuanCJR/rulebookguard`.
+
+The plugin runs the project's own rulebookguard (`node_modules/rulebookguard`, in the project directory or a parent) when its version is at least the plugin's; otherwise it runs `npx rulebookguard@<plugin version>`, which needs Node.js and network access the first time. The hooks never block a tool: any failure, including a timeout, lets it go ahead without rules.
+
 ## Releasing
 
-Releases are published to npm from GitHub Actions with [trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored and every version carries a provenance attestation. To release, bump `version` in `package.json`, merge it to `main`, then push a matching tag:
+Releases are published to npm from GitHub Actions with [trusted publishing](https://docs.npmjs.com/trusted-publishers), so no npm token is stored and every version carries a provenance attestation. To release, bump `version` in `package.json` and in `plugin/.claude-plugin/plugin.json` (a test keeps them equal), merge it to `main`, then push a matching tag:
 
 ```sh
 git tag v0.1.0

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,8 +1,139 @@
 #!/usr/bin/env node
-import { M as FormatError, N as formatIssue, _ as expandGlobs, a as CliError, c as openCatalog, d as scanTestTags, h as rulesForPath, l as writeJson, o as findRule, 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 { isAbsolute, join, relative, resolve } from "node:path";
+import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
+import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
+import { McpServer } from "@modelcontextprotocol/server";
+import * as z from "zod/v4";
+// src/commands/hook.ts
+const HOOK_BODY_LIMIT = 1e4;
+const TEXT = {
+	en: {
+		header: (path) => `Business rules anchored to ${path} (rulebookguard). They are the source of truth: keep any change to this file consistent with them, and change the rule first if a change alters its behavior.`,
+		ruleFile: "Rule file",
+		omitted: `Rule texts omitted (over ${HOOK_BODY_LIMIT} characters); run \`rulebookguard show <id>\` for the full text.`
+	},
+	es: {
+		header: (path) => `Reglas de negocio ancladas a ${path} (rulebookguard). Son la fuente de verdad: mantén cualquier cambio a este archivo coherente con ellas y, si un cambio altera su comportamiento, cambia primero la regla.`,
+		ruleFile: "Archivo de la regla",
+		omitted: `Se omitió el texto de las reglas (más de ${HOOK_BODY_LIMIT} caracteres); ejecuta \`rulebookguard show <id>\` para verlo completo.`
+	}
+};
+async function hookCommand(io) {
+	try {
+		const event = parseEvent(await (io.stdin?.() ?? Promise.resolve("")));
+		const context = event === void 0 ? void 0 : await hookContext(event, io.cwd);
+		if (event !== void 0 && context !== void 0) io.stdout(`${JSON.stringify({ hookSpecificOutput: {
+			hookEventName: event.name,
+			additionalContext: context
+		} })}\n`);
+	} catch {}
+}
+const TOOL_EVENTS = ["PreToolUse", "PostToolUse"];
+async function hookContext(event, cwd) {
+	const file = resolve(event.cwd ?? cwd, event.filePath);
+	const root = await findRulebookRoot(dirname(file));
+	if (root === void 0) return;
+	const path = relative(root, file);
+	if (path === "" || path === ".." || path.startsWith(`..${sep}`) || isAbsolute(path)) return;
+	const catalog = await loadCatalog(root);
+	const repoPath = path.split(sep).join("/");
+	const rules = rulesForPath(catalog.rules, repoPath).filter((rule) => rule.status === "active");
+	if (rules.length === 0) return;
+	return render(repoPath, rules, TEXT[catalog.config.language ?? "en"]);
+}
+function parseEvent(input) {
+	let event;
+	try {
+		event = JSON.parse(input);
+	} catch {
+		return;
+	}
+	if (typeof event !== "object" || event === null) return;
+	const { hook_event_name: name, tool_input: toolInput, cwd } = event;
+	const filePath = toolInput?.file_path;
+	const toolEvent = TOOL_EVENTS.find((candidate) => candidate === name);
+	if (toolEvent === void 0 || typeof filePath !== "string" || filePath === "") return;
+	return typeof cwd === "string" ? {
+		name: toolEvent,
+		filePath,
+		cwd
+	} : {
+		name: toolEvent,
+		filePath
+	};
+}
+function render(path, rules, text) {
+	const withBodies = rules.reduce((total, rule) => total + rule.body.trim().length, 0) <= HOOK_BODY_LIMIT;
+	const sections = rules.map((rule) => {
+		const lines = [`## ${rule.id} (${rule.context}): ${rule.summary}`, `${text.ruleFile}: ${rule.file}`];
+		return withBodies ? [
+			...lines,
+			"",
+			rule.body.trim()
+		].join("\n") : lines.join("\n");
+	});
+	const parts = [text.header(path), ...sections];
+	if (!withBodies) parts.push(text.omitted);
+	return parts.join("\n\n");
+}
+// package.json
+var version = "0.3.0";
+// src/mcp/server.ts
+function createRulesServer(projectDir) {
+	const server = new McpServer({
+		name: "rulebookguard",
+		version
+	});
+	server.registerTool("rules_for", {
+		description: "Active business rules anchored to a file (id, context, summary, rule file). Call it before changing a file; the rules are the source of truth for its behavior.",
+		inputSchema: z.object({ path: z.string().describe("File path, absolute or relative to the project directory") }),
+		annotations: { readOnlyHint: true }
+	}, ({ path }) => cli(projectDir, [
+		"for",
+		path,
+		"--json"
+	]));
+	server.registerTool("rules_show", {
+		description: "Full text of one business rule: summary, anchors, entities, supersedes and the rule body with its examples.",
+		inputSchema: z.object({ id: z.string().describe("Rule id, for example R-CLI-001") }),
+		annotations: { readOnlyHint: true }
+	}, ({ id }) => cli(projectDir, [
+		"show",
+		id,
+		"--json"
+	]));
+	return server;
+}
+async function cli(cwd, args) {
+	let stdout = "";
+	let stderr = "";
+	if (await runCli(args, {
+		cwd,
+		stdout: (text) => {
+			stdout += text;
+		},
+		stderr: (text) => {
+			stderr += text;
+		}
+	}) === 0) return { content: [{
+		type: "text",
+		text: stdout
+	}] };
+	return {
+		content: [{
+			type: "text",
+			text: stderr.trim()
+		}],
+		isError: true
+	};
+}
+// src/commands/mcp.ts
+async function mcpCommand(io, project) {
+	await createRulesServer(resolve(io.cwd, project ?? ".")).connect(new StdioServerTransport());
+}
 // src/commands/new.ts
 const MAX_NUMBER = 999;
 async function newCommand(catalog, io, name) {
@@ -194,6 +325,12 @@ Commands:
   new <context>                                      scaffold the next free rule id as a proposed rule
   lint [--base <ref>] [--json]                       check the catalog, anchors and test tags;
                                                      --base: rules changed since <ref> need a changed test
+  hook                                               Claude Code PreToolUse hook: reads the event on stdin
+                                                     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.
 `;
@@ -231,6 +368,21 @@ const COMMANDS = {
 		argument: "context",
 		options: {}
 	},
+	hook: {
+		usage: "rulebookguard hook",
+		options: {}
+	},
+	mcp: {
+		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: {
@@ -264,6 +416,22 @@ async function dispatch(argv, io) {
 	if (spec === void 0) throw new CliError(`Unknown command "${name}".\n${USAGE.trimEnd()}`, 2);
 	const { values, argument } = parse(spec, rest);
 	const json = values.json === true;
+	if (name === "hook") {
+		await hookCommand(io);
+		return 0;
+	}
+	if (name === "mcp") {
+		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
@@ -317,6 +485,11 @@ function parse(spec, args) {
 process.exitCode = await runCli(process.argv.slice(2), {
 	cwd: process.cwd(),
 	stdout: (text) => process.stdout.write(text),
-	stderr: (text) => process.stderr.write(text)
+	stderr: (text) => process.stderr.write(text),
+	stdin: async () => {
+		let text = "";
+		for await (const chunk of process.stdin) text += String(chunk);
+		return text;
+	}
 });
 export {};

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.1.1",
+  "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,17 +28,23 @@
     "./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"
+    "yaml": "^2.9.1",
+    "zod": "^4.6.7"
   },
   "devDependencies": {
+    "@modelcontextprotocol/client": "2.3.1",
     "@types/node": "^20.19.43",
     "@types/picomatch": "^4.0.3",
     "typescript": "^7.0.2",
     "vite-plus": "^1.4.0"
   },
   "engines": {
-    "node": ">=22"
+    "node": ">=22.23.4"
   }
 }