rulebookguard 0.3.2 → 0.5.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.23.4 or later (the `site` command builds with Astro 7, which needs it).
+Requires Node.js 22 or later.
 
 ```sh
 npx rulebookguard lint
@@ -260,15 +260,35 @@ 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>]`
+### `site:generate [--out <dir>] [--base <path>]`
+
+The site commands build with Astro, which lives in a separate package so that installing the linter does not download it. Install it next to `rulebookguard` (it requires Node.js 22.23.4 or later):
+
+```sh
+npm install --save-dev rulebookguard @rulebookguard/site
+```
+
+Without it, the site commands fail, exit 1, with `The site commands need the @rulebookguard/site package. Install it next to rulebookguard: npm install --save-dev @rulebookguard/site`. One-off, without installing: `npx -p rulebookguard -p @rulebookguard/site rulebookguard site:run`.
 
 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
+$ rulebookguard site:generate --out public/rules --base /rules
 public/rules
 ```
 
+`site` is the same command.
+
+### `site:run [--out <dir>] [--base <path>] [--port <n>]`
+
+Builds the site like `site:generate`, then serves `--out` on `127.0.0.1` (port 4321, or `--port`) and prints the URL, until Ctrl+C. Unknown paths get the site's 404 page. A taken port fails, exit 1, before building.
+
+```sh
+$ rulebookguard site:run
+site
+Serving site at http://127.0.0.1:4321/ (Ctrl+C to stop)
+```
+
 The site has:
 
 - **Home:** the contexts map, with how many rules of each status every context holds.

package/dist/cli.mjs

@@ -80,7 +80,7 @@ function render(path, rules, text) {
 	return parts.join("\n\n");
 }
 // package.json
-var version = "0.3.2";
+var version = "0.5.0";
 // src/mcp/server.ts
 function createRulesServer(projectDir) {
 	const server = new McpServer({
@@ -329,12 +329,20 @@ 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;
+  site:generate [--out <dir>] [--base <path>]        build the read-only static site of the rulebook (alias: site);
                                                      --out: output directory (default: site), --base: URL path
+  site:run [--out <dir>] [--base <path>] [--port <n>]
+                                                     build the site, then serve it on 127.0.0.1 until Ctrl+C;
+                                                     --port: port to serve on (default: 4321)
+                                                     site commands need @rulebookguard/site installed
 
 Exit codes: 0 success, 1 failure (lint: any error), 2 usage error.
 `;
 const JSON_OPTION = { json: { type: "boolean" } };
+const SITE_OPTIONS = {
+	out: { type: "string" },
+	base: { type: "string" }
+};
 const COMMANDS = {
 	contexts: {
 		usage: "rulebookguard contexts [--json]",
@@ -378,9 +386,17 @@ const COMMANDS = {
 	},
 	site: {
 		usage: "rulebookguard site [--out <dir>] [--base <path>]",
+		options: SITE_OPTIONS
+	},
+	"site:generate": {
+		usage: "rulebookguard site:generate [--out <dir>] [--base <path>]",
+		options: SITE_OPTIONS
+	},
+	"site:run": {
+		usage: "rulebookguard site:run [--out <dir>] [--base <path>] [--port <n>]",
 		options: {
-			out: { type: "string" },
-			base: { type: "string" }
+			...SITE_OPTIONS,
+			port: { type: "string" }
 		}
 	},
 	lint: {
@@ -424,11 +440,13 @@ async function dispatch(argv, io) {
 		await mcpCommand(io, values.project);
 		return 0;
 	}
-	if (name === "site") {
-		const { siteCommand } = await import("./site-C2qLRXNK.mjs");
+	if (name === "site" || name === "site:generate" || name === "site:run") {
+		const { siteCommand } = await import("./site-BiiOPVEe.mjs");
 		await siteCommand(io, {
 			out: values.out,
-			base: values.base
+			base: values.base,
+			serve: name === "site:run",
+			port: sitePort(values.port, spec.usage)
 		});
 		return 0;
 	}
@@ -461,6 +479,12 @@ async function dispatch(argv, io) {
 	}
 	return 0;
 }
+function sitePort(value, usage) {
+	if (value === void 0) return;
+	const port = Number(value);
+	if (!/^\d+$/.test(value) || port > 65535) throw new CliError(`--port must be a number from 0 to 65535.\nUsage: ${usage}`, 2);
+	return port;
+}
 function parse(spec, args) {
 	let parsed;
 	try {

package/dist/{site-C2qLRXNK.mjs → site-BiiOPVEe.mjs}

@@ -1,11 +1,9 @@
 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";
+import { createRequire } from "node:module";
+import { readFile, readdir, stat, writeFile } from "node:fs/promises";
+import { dirname, extname, isAbsolute, join, relative, resolve, sep } from "node:path";
+import { createServer } from "node:http";
+import { fileURLToPath, pathToFileURL } from "node:url";
 // src/site/data.ts
 const FIELD = "";
 async function siteData(catalog, onGitFallback) {
@@ -395,17 +393,53 @@ function demote(markdown) {
 	}).join("\n");
 }
 // src/commands/site.ts
-const execFileAsync = promisify(execFile);
+const SITE_PACKAGE = "@rulebookguard/site";
 /** Marks an output directory as written by `site`, so a rebuild may replace it. */
 const MARKER = ".rulebookguard-site";
-async function siteCommand(io, options) {
+/**
+* Builds the site into `--out`; with `serve`, also serves it on 127.0.0.1 until `until` settles (Ctrl+C by default).
+*/
+async function siteCommand(io, options, until = untilInterrupted()) {
 	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 site = await importSitePackage([catalog.root, dirname(fileURLToPath(import.meta.url))]);
 	const language = catalog.config.language ?? "en";
 	const base = normalizeBase(options.base ?? "/");
+	const server = options.serve ? await listen(out, base, options.port ?? 4321) : void 0;
+	try {
+		await buildSite(site, catalog, out, language, base, io);
+	} catch (error) {
+		server?.close();
+		throw error;
+	}
+	writeLines(io, [shown]);
+	if (server === void 0) return;
+	const { port } = server.address();
+	writeLines(io, [`Serving ${shown} at http://127.0.0.1:${port}${base} (Ctrl+C to stop)`]);
+	await until;
+	await new Promise((closed) => {
+		server.close(() => closed());
+		server.closeAllConnections();
+	});
+}
+/** Imports the site builder from the first of `from` that resolves it. */
+async function importSitePackage(from) {
+	for (const directory of from) {
+		let entry;
+		try {
+			entry = createRequire(join(directory, "package.json")).resolve(SITE_PACKAGE);
+		} catch (error) {
+			if (error.code === "MODULE_NOT_FOUND") continue;
+			throw error;
+		}
+		return await import(pathToFileURL(entry).href);
+	}
+	throw new CliError(`The site commands need the ${SITE_PACKAGE} package. Install it next to rulebookguard: npm install --save-dev ${SITE_PACKAGE}`);
+}
+async function buildSite(site, catalog, out, language, base, io) {
 	const files = sitePages(await siteData(catalog, gitFallbackWarning(io)), {
 		language,
 		base
@@ -426,45 +460,85 @@ async function siteCommand(io, options) {
 		}))
 	];
 	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 site.buildSite(files, out);
+	} catch (error) {
+		throw error instanceof site.SiteBuildError ? new CliError(error.message) : error;
+	}
+	await writeFile(join(out, MARKER), "");
+}
+function untilInterrupted() {
+	return new Promise((stop) => {
+		process.once("SIGINT", () => stop());
+		process.once("SIGTERM", () => stop());
+	});
+}
+const CONTENT_TYPES = {
+	".html": "text/html; charset=utf-8",
+	".css": "text/css; charset=utf-8",
+	".js": "text/javascript; charset=utf-8",
+	".mjs": "text/javascript; charset=utf-8",
+	".json": "application/json; charset=utf-8",
+	".txt": "text/plain; charset=utf-8",
+	".xml": "application/xml; charset=utf-8",
+	".svg": "image/svg+xml",
+	".png": "image/png",
+	".jpg": "image/jpeg",
+	".ico": "image/x-icon",
+	".webp": "image/webp",
+	".woff2": "font/woff2",
+	".wasm": "application/wasm"
+};
+function listen(out, base, port) {
+	const server = createServer((request, response) => {
+		serveFile(out, base, request, response).catch(() => {
+			response.writeHead(500).end();
 		});
-		await cp(join(work, "dist"), out, { recursive: true });
-		await writeFile(join(out, MARKER), "");
-	} finally {
-		await rm(work, {
-			recursive: true,
-			force: true
+	});
+	return new Promise((ready, fail) => {
+		server.once("error", (error) => {
+			fail(error.code === "EADDRINUSE" ? new CliError(`Port ${port} is already in use; pass another --port.`) : error);
 		});
-	}
-	writeLines(io, [shown]);
+		server.listen(port, "127.0.0.1", () => ready(server));
+	});
 }
-/**
-* 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;
+async function serveFile(out, base, request, response) {
+	const path = decodeURIComponent(new URL(request.url ?? "/", "http://localhost").pathname);
+	if (`${path}/` === base) {
+		response.writeHead(301, { location: base }).end();
+		return;
+	}
+	if (!path.startsWith(base)) {
+		if (path === "/") {
+			response.writeHead(301, { location: base }).end();
+			return;
+		}
+		await sendNotFound(out, response);
+		return;
+	}
+	let file = resolve(out, `.${sep}${path.slice(base.length)}`);
+	if (file !== out && !file.startsWith(`${out}${sep}`)) {
+		await sendNotFound(out, response);
+		return;
 	}
-	const parent = dirname(directory);
-	const modules = basename(parent) === "node_modules" ? parent : join(directory, "node_modules");
-	return join(modules, ".rulebookguard-site");
+	if ((await stat(file).catch(() => void 0))?.isDirectory()) {
+		if (!path.endsWith("/")) {
+			response.writeHead(301, { location: `${path}/` }).end();
+			return;
+		}
+		file = join(file, "index.html");
+	}
+	const body = await readFile(file).catch(() => void 0);
+	if (body === void 0) {
+		await sendNotFound(out, response);
+		return;
+	}
+	response.writeHead(200, { "content-type": CONTENT_TYPES[extname(file)] ?? "application/octet-stream" });
+	response.end(body);
 }
-function isOwnPackageRoot(directory) {
-	const file = join(directory, "package.json");
-	return existsSync(file) && JSON.parse(readFileSync(file, "utf8")).name === "rulebookguard";
+async function sendNotFound(out, response) {
+	const page = await readFile(join(out, "404.html")).catch(() => "Not found");
+	response.writeHead(404, { "content-type": CONTENT_TYPES[".html"] }).end(page);
 }
 async function assertReplaceable(out, shown) {
 	let entries;
@@ -476,31 +550,6 @@ async function assertReplaceable(out, shown) {
 	}
 	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;
-		throw new CliError(`The site build failed:\n${astroFailureDetail(`${stderr ?? ""}${stdout ?? ""}`)}`);
-	}
-}
-/** The first lines of Astro's error output, without its stack trace. */
-function astroFailureDetail(output) {
-	return output.split("\n").filter((line) => !/^\s*at /.test(line) && !/^\s*Stack trace:/.test(line)).filter((line) => line.trim() !== "").slice(0, 12).join("\n");
-}
 function astroConfig(title, language, base, sidebar) {
 	return `import starlight from '@astrojs/starlight';
 import { defineConfig } from 'astro/config';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.3.2",
+  "version": "0.5.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,23 +28,29 @@
     "./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"
   },
   "devDependencies": {
     "@modelcontextprotocol/client": "2.3.1",
+    "@rulebookguard/site": "0.5.0",
     "@types/node": "^20.19.43",
     "@types/picomatch": "^4.0.3",
     "typescript": "^7.0.2",
     "vite-plus": "^1.4.0"
   },
+  "peerDependencies": {
+    "@rulebookguard/site": "^0.5.0"
+  },
+  "peerDependenciesMeta": {
+    "@rulebookguard/site": {
+      "optional": true
+    }
+  },
   "engines": {
-    "node": ">=22.23.4"
+    "node": ">=22"
   }
 }