rulebookguard 0.1.1 → 0.2.0

package/README.md

@@ -236,6 +236,30 @@ 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.`
+
 ### `lint [--base <ref>] [--json]`
 
 Checks the whole catalog. Each finding is printed as `<severity> <code> <file>[:line] <message>`, followed by a count.
@@ -295,9 +319,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/cli.mjs

@@ -1,8 +1,138 @@
 #!/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, _ 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 { 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.2.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 +324,10 @@ 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)
 
 Exit codes: 0 success, 1 failure (lint: any error), 2 usage error.
 `;
@@ -231,6 +365,14 @@ const COMMANDS = {
 		argument: "context",
 		options: {}
 	},
+	hook: {
+		usage: "rulebookguard hook",
+		options: {}
+	},
+	mcp: {
+		usage: "rulebookguard mcp [--project <dir>]",
+		options: { project: { type: "string" } }
+	},
 	lint: {
 		usage: "rulebookguard lint [--base <ref>] [--json]",
 		options: {
@@ -264,6 +406,14 @@ 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 === "lint") return lintCommand(io, {
 		base: values.base,
 		json
@@ -317,6 +467,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.1.1",
+  "version": "0.2.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,11 +28,14 @@
     "./package.json": "./package.json"
   },
   "dependencies": {
+    "@modelcontextprotocol/server": "^2.3.1",
     "ajv": "^8.20.0",
     "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",