rulebookguard 0.3.2 → 0.4.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.23.4 or later (the `site:generate` and `site:run` commands build with Astro 7, which needs it).
 
 ```sh
 npx rulebookguard lint
@@ -260,15 +260,27 @@ 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>]`
 
 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.4.0";
 // src/mcp/server.ts
 function createRulesServer(projectDir) {
 	const server = new McpServer({
@@ -329,12 +329,19 @@ 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)
 
 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 +385,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 +439,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-BgH5724T.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 +478,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-BgH5724T.mjs}

@@ -1,10 +1,11 @@
 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 { cp, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { basename, dirname, extname, isAbsolute, join, relative, resolve, sep } 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 { createServer } from "node:http";
 import { fileURLToPath } from "node:url";
 // src/site/data.ts
 const FIELD = "";
@@ -398,7 +399,10 @@ function demote(markdown) {
 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) {
+/**
+* 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);
@@ -406,6 +410,24 @@ async function siteCommand(io, options) {
 	await assertReplaceable(out, shown);
 	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(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();
+	});
+}
+async function buildSite(catalog, out, language, base, io) {
 	const files = sitePages(await siteData(catalog, gitFallbackWarning(io)), {
 		language,
 		base
@@ -445,7 +467,79 @@ async function siteCommand(io, options) {
 			force: true
 		});
 	}
-	writeLines(io, [shown]);
+}
+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();
+		});
+	});
+	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);
+		});
+		server.listen(port, "127.0.0.1", () => ready(server));
+	});
+}
+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;
+	}
+	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);
+}
+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);
 }
 /**
 * Starlight injects its routes as package specifiers that Astro resolves from the project root, so the generated

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "rulebookguard",
-  "version": "0.3.2",
+  "version": "0.4.0",
   "description": "Keep business rules as the single source of truth, bound to code and tests.",
   "homepage": "https://github.com/JuanCJR/rulebookguard#readme",
   "bugs": {