rulebookguard 0.7.0 → 0.8.0

package/README.md

@@ -52,8 +52,8 @@ npm install --save-dev rulebookguard
 
 A first rule in four steps:
 
-1. Create `rulebookguard.config.yaml` at the repository root (see [Configuration](#configuration)).
-2. Scaffold a rule: `npx rulebookguard new clients` creates the context and `docs/rules/clients/R-CLI-001.md` as `proposed`.
+1. Set up the rulebook: `npx rulebookguard init clients --ci` writes `rulebookguard.config.yaml`, the `clients` context and a CI workflow (see [Configuration](#configuration) to adjust `testGlobs`).
+2. Scaffold a rule: `npx rulebookguard new clients` creates `docs/rules/clients/R-CLI-001.md` as `proposed`.
 3. Write the rule, add its `anchors`, set `status: active`, and wrap the test that proves it with `@rule R-CLI-001` and `@endrule R-CLI-001`.
 4. Run `npx rulebookguard lint`, and add it to CI with the [CI recipe](#ci-recipe).
 
@@ -213,22 +213,38 @@ SELECT count(*) FROM invoices WHERE number IS NULL;
 
 `rulebookguard --help` prints the command list. Exit codes: `0` success, `1` failure (unknown id or context, missing config, lint errors, git errors), `2` usage error (unknown command or option, missing or extra argument).
 
-| Command                                                | What it does                                                 |
-| ------------------------------------------------------ | ------------------------------------------------------------ |
-| [`contexts`](#contexts-l0)                             | the contexts map (L0)                                        |
-| [`list`](#list---context-c---status-s-l1)              | rule ids and summaries (L1)                                  |
-| [`show <id>`](#show-id-l2)                             | the full rule (L2)                                           |
-| [`for <path>`](#for-path)                              | the active rules anchored to a file                          |
-| [`impact <id>`](#impact-id)                            | the files and tests a rule touches                           |
-| [`new <context>`](#new-context---prefix-p)             | scaffolds the next rule of a context                         |
-| [`lint`](#lint---base-ref---json)                      | checks the whole catalog, and optionally changes since a ref |
-| [`hook`](#hook)                                        | Claude Code hook that injects the rules of a file            |
-| [`mcp`](#mcp---project-dir)                            | MCP server for AI agents                                     |
-| [`site:generate`](#sitegenerate---out-dir---base-path) | builds a static site of the rulebook                         |
-| [`site:run`](#siterun---out-dir---base-path---port-n)  | builds the site and serves it locally                        |
+| Command                                                           | What it does                                                 |
+| ----------------------------------------------------------------- | ------------------------------------------------------------ |
+| [`init <context>`](#init-context---prefix-p---language-enes---ci) | sets up the config, a first context and optionally CI        |
+| [`contexts`](#contexts-l0)                                        | the contexts map (L0)                                        |
+| [`list`](#list---context-c---status-s-l1)                         | rule ids and summaries (L1)                                  |
+| [`show <id>`](#show-id-l2)                                        | the full rule (L2)                                           |
+| [`for <path>`](#for-path)                                         | the active rules anchored to a file                          |
+| [`impact <id>`](#impact-id)                                       | the files and tests a rule touches                           |
+| [`new <context>`](#new-context---prefix-p)                        | scaffolds the next rule of a context                         |
+| [`lint`](#lint---base-ref---json)                                 | checks the whole catalog, and optionally changes since a ref |
+| [`hook`](#hook)                                                   | Claude Code hook that injects the rules of a file            |
+| [`mcp`](#mcp---project-dir)                                       | MCP server for AI agents                                     |
+| [`site:generate`](#sitegenerate---out-dir---base-path)            | builds a static site of the rulebook                         |
+| [`site:run`](#siterun---out-dir---base-path---port-n)             | builds the site and serves it locally                        |
 
 The read commands (`contexts`, `list`, `show`, `for`, `impact`) accept `--json` for machine consumers. When the catalog has problems they still run, and print one warning on stderr pointing at `lint`.
 
+### `init <context> [--prefix <P>] [--language <en|es>] [--ci]`
+
+Sets up a rulebook in the current directory and prints the paths it wrote: `rulebookguard.config.yaml`, then the context, the same one `new` would create (`--prefix` works the same way).
+
+```sh
+$ rulebookguard init clients --ci
+rulebookguard.config.yaml
+docs/rules/clients/_context.md
+.github/workflows/rulebookguard.yml
+```
+
+The config uses `rulesDir: docs/rules` and these `testGlobs`, which you can narrow afterwards: `**/*.test.*`, `**/*.spec.*`, `**/test_*.py` and `**/*_test.go`. `--language` writes `language` into the config, so the context template and later messages follow it. `--ci` also writes the GitHub Actions workflow of the [CI recipe](#ci-recipe), pinned to the running version.
+
+Exits 1, writing nothing, when `rulebookguard.config.yaml` (or, with `--ci`, the workflow) already exists in the current directory, or when the context name or prefix is invalid. Exits 2 for a `--language` other than `en` or `es`.
+
 ### `contexts` (L0)
 
 ```sh
@@ -429,7 +445,7 @@ Generated text and the interface follow `language` in the config. The site is a
 
 ## CI recipe
 
-Run the linter on every pull request, comparing against the main branch. The full history is needed so that `origin/main` exists.
+Run the linter on every pull request, comparing against the branch it targets. The full history is needed so that the base branch exists. `rulebookguard init --ci` writes this file as `.github/workflows/rulebookguard.yml`.
 
 ```yaml
 name: rules
@@ -442,7 +458,10 @@ jobs:
       - uses: actions/checkout@v7.0.1
         with:
           fetch-depth: 0
-      - run: npx --yes rulebookguard@0.1.0 lint --base origin/main
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: npx --yes rulebookguard@0.8.0 lint --base origin/${{ github.base_ref }}
 ```
 
 > [!TIP]
@@ -465,4 +484,4 @@ 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.
+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. In a checkout of rulebookguard itself it runs the checkout's own built CLI (`dist/cli.mjs`, from `vp pack`), whatever its version. The hooks never block a tool: any failure, including a timeout, lets it go ahead without rules.

package/dist/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
-import { F as messages, I as FormatError, L as formatIssue, O as CONTEXT_FILE_NAME, _ as expandGlobs, a as CliError, c as openCatalog, f as scanTestTags, l as writeJson, m as loadCatalog, o as findRule, p as findRulebookRoot, r as lintCommand, s as gitFallbackWarning, u as writeLines, y as toRepoPath } from "./lint-DfibQDW3.mjs";
+import { F as messages, I as FormatError, L as formatIssue, M as CONFIG_FILE_NAME, O as CONTEXT_FILE_NAME, _ as expandGlobs, a as CliError, c as openCatalog, f as scanTestTags, l as writeJson, m as loadCatalog, o as findRule, p as findRulebookRoot, r as lintCommand, s as gitFallbackWarning, u as writeLines, y as toRepoPath } from "./lint-DfibQDW3.mjs";
 import { t as rulesForPath } from "./anchors-C2j9c5MI.mjs";
-import { mkdir, readdir, rm, writeFile } from "node:fs/promises";
+import { access, mkdir, readdir, rm, writeFile } from "node:fs/promises";
 import { dirname, isAbsolute, join, relative, resolve, sep } from "node:path";
 import { parseArgs } from "node:util";
 import { StdioServerTransport } from "@modelcontextprotocol/server/stdio";
@@ -80,60 +80,7 @@ function render(path, rules, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.7.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());
-}
+var version = "0.8.0";
 // src/commands/new.ts
 const MAX_NUMBER = 999;
 const CONTEXT_NAME = /^[a-z0-9][a-z0-9_-]*$/;
@@ -163,7 +110,7 @@ async function createContext(catalog, name, option, text) {
 	const directory = `${toRepoPath(catalog.config.rulesDir).replace(/\/+$/, "")}/${name}`;
 	const file = `${directory}/${CONTEXT_FILE_NAME}`;
 	await mkdir(join(catalog.root, directory), { recursive: true });
-	await writeNew(catalog, file, contextTemplate(name, prefix, text), text);
+	await writeNew$1(catalog, file, contextTemplate(name, prefix, text), text);
 	return {
 		file,
 		context: name,
@@ -181,10 +128,10 @@ async function writeNextRule(catalog, context, text) {
 	if (last >= MAX_NUMBER) throw new CliError(text.noFreeId(context.context, `R-${context.prefix}-${MAX_NUMBER}`));
 	const id = `R-${context.prefix}-${String(last + 1).padStart(3, "0")}`;
 	const file = `${directory}/${id}.md`;
-	await writeNew(catalog, file, ruleTemplate(id, context.context, catalog.config.language ?? "en"), text);
+	await writeNew$1(catalog, file, ruleTemplate(id, context.context, catalog.config.language ?? "en"), text);
 	return file;
 }
-async function writeNew(catalog, file, content, text) {
+async function writeNew$1(catalog, file, content, text) {
 	try {
 		await writeFile(join(catalog.root, file), content, { flag: "wx" });
 	} catch (error) {
@@ -243,6 +190,116 @@ ${text.scenario}
 \`\`\`
 `;
 }
+// src/commands/init.ts
+const WORKFLOW_FILE = ".github/workflows/rulebookguard.yml";
+const TEST_GLOBS = [
+	"**/*.test.*",
+	"**/*.spec.*",
+	"**/test_*.py",
+	"**/*_test.go"
+];
+async function initCommand(io, name, options) {
+	const root = io.cwd;
+	const text = messages(options.language);
+	const files = options.ci ? [CONFIG_FILE_NAME, WORKFLOW_FILE] : [CONFIG_FILE_NAME];
+	for (const file of files) if (await exists(join(root, file))) throw new CliError(text.alreadyExists(file));
+	const written = [];
+	try {
+		await writeNew(root, CONFIG_FILE_NAME, configTemplate(options.language), written);
+		const context = await createContext(await loadCatalog(root), name, options.prefix, text);
+		written.push(context.file);
+		if (options.ci) await writeNew(root, WORKFLOW_FILE, WORKFLOW, written);
+	} catch (error) {
+		await Promise.all(written.map((file) => rm(join(root, file), { force: true })));
+		if (error.code === "EEXIST") throw new CliError(text.alreadyExists(written.at(-1) ?? "rulebookguard.config.yaml"));
+		throw error;
+	}
+	writeLines(io, written);
+}
+async function writeNew(root, file, content, written) {
+	await mkdir(dirname(join(root, file)), { recursive: true });
+	await writeFile(join(root, file), content, { flag: "wx" });
+	written.push(file);
+}
+async function exists(path) {
+	try {
+		await access(path);
+		return true;
+	} catch {
+		return false;
+	}
+}
+function configTemplate(language) {
+	return `schema: 1\nrulesDir: docs/rules\ntestGlobs:\n${TEST_GLOBS.map((glob) => `  - '${glob}'\n`).join("")}${language === void 0 ? "" : `language: ${language}\n`}`;
+}
+const WORKFLOW = `name: rules
+on: pull_request
+
+jobs:
+  rulebookguard:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v7.0.1
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-node@v6
+        with:
+          node-version: 22
+      - run: npx --yes rulebookguard@${version} lint --base origin/\${{ github.base_ref }}
+`;
+// 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/read.ts
 const RULE_STATUSES = [
 	"proposed",
@@ -377,6 +434,11 @@ function compare(a, b) {
 const USAGE = `Usage: rulebookguard <command> [options]
 
 Commands:
+  init <context> [--prefix <P>] [--language <en|es>] [--ci]
+                                                     create rulebookguard.config.yaml and a first context in
+                                                     the current directory; --language: language of generated
+                                                     text (default: en), --ci: also a GitHub Actions workflow
+                                                     that runs lint --base on pull requests
   contexts [--json]                                  L0: list the contexts
   list [--context <c>] [--status <s>] [--json]       L1: id and summary of each rule
   show <id> [--json]                                 L2: the full rule
@@ -407,6 +469,15 @@ const SITE_OPTIONS = {
 	base: { type: "string" }
 };
 const COMMANDS = {
+	init: {
+		usage: "rulebookguard init <context> [--prefix <P>] [--language <en|es>] [--ci]",
+		argument: "context",
+		options: {
+			prefix: { type: "string" },
+			language: { type: "string" },
+			ci: { type: "boolean" }
+		}
+	},
 	contexts: {
 		usage: "rulebookguard contexts [--json]",
 		options: JSON_OPTION
@@ -513,6 +584,14 @@ async function dispatch(argv, io) {
 		});
 		return 0;
 	}
+	if (name === "init") {
+		await initCommand(io, argument, {
+			prefix: values.prefix,
+			language: initLanguage(values.language, spec.usage),
+			ci: values.ci === true
+		});
+		return 0;
+	}
 	if (name === "lint") return lintCommand(io, {
 		base: values.base,
 		json
@@ -542,6 +621,10 @@ async function dispatch(argv, io) {
 	}
 	return 0;
 }
+function initLanguage(value, usage) {
+	if (value === void 0 || value === "en" || value === "es") return value;
+	throw new CliError(`--language must be en or es.\nUsage: ${usage}`, 2);
+}
 function sitePort(value, usage) {
 	if (value === void 0) return;
 	const port = Number(value);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Keep business rules as the single source of truth, bound to code and tests.",
   "homepage": "https://github.com/JuanCJR/rulebookguard#readme",
   "bugs": {
@@ -36,14 +36,14 @@
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.3.1",
-    "@rulebookguard/site": "0.7.0",
+    "@rulebookguard/site": "0.8.0",
     "@types/node": "^20.19.43",
     "@types/picomatch": "^4.0.3",
     "typescript": "^7.0.2",
     "vite-plus": "^1.4.0"
   },
   "peerDependencies": {
-    "@rulebookguard/site": "^0.7.0"
+    "@rulebookguard/site": "^0.8.0"
   },
   "peerDependenciesMeta": {
     "@rulebookguard/site": {