rulebookguard 0.1.0 → 0.2.0

package/README.md

@@ -36,9 +36,12 @@ testGlobs: # required: files scanned for @rule tags
   - 'src/**/*.test.ts'
   - 'tests/**/test_*.py'
 contextBudget: 30 # default: 30; lint warns when a context holds more rules
+language: es # default: en; language of the text that rulebookguard generates
 ```
 
-`schema` and `testGlobs` are required (`testGlobs: []` is valid but finds no tags). Unknown fields are rejected. The JSON Schemas ship with the package under `rulebookguard/schemas/v1/`.
+`schema` and `testGlobs` are required (`testGlobs: []` is valid but finds no tags). Unknown fields are rejected.
+
+`language` (`en` or `es`) sets the language of the text rulebookguard writes for you, such as the template of `new`. Rule content is free text and is never checked for language, so rules can be written in any language whatever this setting says. `language` needs rulebookguard 0.1.1 or later; older versions reject it as an unknown field. The JSON Schemas ship with the package under `rulebookguard/schemas/v1/`.
 
 Inside a git work tree, files are listed with `git ls-files --cached --others --exclude-standard`, so anything in `.gitignore` (`dist/`, `coverage/`, caches) is never matched by anchors or test globs; files inside submodules are listed too. A submodule path that is a symlink, or that resolves outside the rulebook root, is skipped. A test file that is a symlink is scanned for `@rule` tags only when its target lies inside the rulebook root. If one submodule cannot be listed, commands print `warning: could not list files of submodule "<path>" (<reason>); skipping it.` and keep the rest of the git listing. Outside git, or when the rulebook root itself is git-ignored, the whole tree is walked, skipping only `.git` and `node_modules`. If git fails (for example, git is missing from `PATH` or the repository has dubious ownership), commands print one warning on stderr and walk the tree instead.
 
@@ -224,7 +227,7 @@ Exits 1 for an unknown id.
 
 ### `new <context>`
 
-Scaffolds the next free id of a context as a `proposed` rule and prints its path. Ids are never reused, and an existing file is never overwritten.
+Scaffolds the next free id of a context as a `proposed` rule and prints its path. Ids are never reused, and an existing file is never overwritten. The placeholder text of the new rule follows `language` in the config.
 
 ```sh
 $ rulebookguard new clients
@@ -233,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.
@@ -292,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-V-Uw5ueZ.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) {
@@ -17,32 +147,51 @@ async function newCommand(catalog, io, name) {
 	const id = `R-${context.prefix}-${String(last + 1).padStart(3, "0")}`;
 	const file = `${directory}/${id}.md`;
 	try {
-		await writeFile(join(catalog.root, file), template(id, context.context), { flag: "wx" });
+		await writeFile(join(catalog.root, file), template(id, context.context, catalog.config.language ?? "en"), { flag: "wx" });
 	} catch (error) {
 		if (error.code === "EEXIST") throw new CliError(`${file} already exists; nothing was written.`);
 		throw error;
 	}
 	writeLines(io, [file]);
 }
-function template(id, context) {
+const TEMPLATE_TEXT = {
+	en: {
+		summary: "TODO: one-line summary of the rule.",
+		title: "TODO: rule title",
+		intro: "TODO: state the rule in full, then add examples as Gherkin scenarios or tables.",
+		scenario: `Scenario: TODO
+  Given TODO
+  When TODO
+  Then TODO`
+	},
+	es: {
+		summary: "TODO: resumen de la regla en una línea.",
+		title: "TODO: título de la regla",
+		intro: "TODO: describe la regla completa y agrega ejemplos como escenarios Gherkin o tablas.",
+		scenario: `# language: es
+Escenario: TODO
+  Dado TODO
+  Cuando TODO
+  Entonces TODO`
+	}
+};
+function template(id, context, language) {
+	const text = TEMPLATE_TEXT[language];
 	return `---
 id: ${id}
 context: ${context}
 entities: []
 status: proposed
 anchors: []
-summary: 'TODO: one-line summary of the rule.'
+summary: '${text.summary}'
 ---
 
-# TODO: rule title
+# ${text.title}
 
-TODO: state the rule in full, then add examples as Gherkin scenarios or tables.
+${text.intro}
 
 \`\`\`gherkin
-Scenario: TODO
-  Given TODO
-  When TODO
-  Then TODO
+${text.scenario}
 \`\`\`
 `;
 }
@@ -175,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.
 `;
@@ -212,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: {
@@ -245,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
@@ -298,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/dist/index.d.mts

@@ -1,9 +1,12 @@
 type RuleStatus = "proposed" | "active" | "deprecated";
+type RuleLanguage = "en" | "es";
 interface RulebookConfig {
   schema: 1;
   rulesDir: string;
   testGlobs: string[];
   contextBudget: number;
+  /** Language the generated rule text is written in; `en` when unset. */
+  language?: RuleLanguage;
 }
 interface ContextFrontmatter {
   context: string;
@@ -146,4 +149,4 @@ interface LintOptions {
 export declare function lintCatalog(catalog: Catalog, tags?: TagIndex, onGitFallback?: GitFallbackListener): Promise<LintFinding[]>;
 export declare function pendingImplementation(catalog: Catalog, tags: TagIndex, base: string, changed: string[]): LintFinding[];
 export declare function formatFinding(finding: LintFinding): string;
-export type { Catalog, CatalogIssue, CatalogIssueCode, ContextDoc, ContextFrontmatter, ContextsJson, ForJson, FormatIssue, Frontmatter, GitFallbackListener, ImpactJson, LintFinding, LintJson, LintOptions, LintSeverity, ListJson, RuleDoc, RuleFrontmatter, RuleStatus, RuleSummaryJson, RuleTag, RulebookConfig, ShowJson, TagIndex, TagLocation };
+export type { Catalog, CatalogIssue, CatalogIssueCode, ContextDoc, ContextFrontmatter, ContextsJson, ForJson, FormatIssue, Frontmatter, GitFallbackListener, ImpactJson, LintFinding, LintJson, LintOptions, LintSeverity, ListJson, RuleDoc, RuleFrontmatter, RuleLanguage, RuleStatus, RuleSummaryJson, RuleTag, RulebookConfig, ShowJson, TagIndex, TagLocation };

package/dist/index.mjs

@@ -1 +1 @@
-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-V-Uw5ueZ.mjs";
+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";

package/dist/{lint-V-Uw5ueZ.mjs → lint-DtD_Ekei.mjs}

@@ -52,7 +52,8 @@ var config_schema_default = {
 			"type": "integer",
 			"minimum": 1,
 			"default": 30
-		}
+		},
+		"language": { "enum": ["en", "es"] }
 	},
 	required: ["schema", "testGlobs"],
 	additionalProperties: false

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.1.0",
+  "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",

package/schemas/v1/config.schema.json

@@ -7,7 +7,8 @@
     "schema": { "const": 1 },
     "rulesDir": { "type": "string", "minLength": 1, "default": "docs/rules" },
     "testGlobs": { "type": "array", "items": { "type": "string", "minLength": 1 } },
-    "contextBudget": { "type": "integer", "minimum": 1, "default": 30 }
+    "contextBudget": { "type": "integer", "minimum": 1, "default": 30 },
+    "language": { "enum": ["en", "es"] }
   },
   "required": ["schema", "testGlobs"],
   "additionalProperties": false