rulebookguard 0.3.1 → 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.1";
+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-DDM1Hs0N.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-DDM1Hs0N.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 = "";
@@ -65,6 +66,12 @@ const STATUSES = [
 	"proposed",
 	"deprecated"
 ];
+const FAVICON = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 32 32">
+  <rect width="32" height="32" rx="7" fill="#3c51e8"/>
+  <path d="M9 8h10a4 4 0 0 1 4 4v12H13a4 4 0 0 1-4-4z" fill="#fff"/>
+  <path d="m13 16 2.5 2.5L20 14" fill="none" stroke="#3c51e8" stroke-width="2.2" stroke-linecap="round" stroke-linejoin="round"/>
+</svg>
+`;
 const TEXT = {
 	en: {
 		title: "Business rules",
@@ -162,6 +169,7 @@ function sitePages(data, options) {
 		return path === void 0 ? id : `[${id}](${path})`;
 	};
 	const files = /* @__PURE__ */ new Map();
+	files.set("public/favicon.svg", FAVICON);
 	files.set("src/content.config.ts", `import { defineCollection } from 'astro:content';
 import { docsLoader } from '@astrojs/starlight/loaders';
 import { docsSchema } from '@astrojs/starlight/schema';
@@ -267,7 +275,7 @@ function rulesPage(data, text, rulePath) {
 			rule.summary
 		].join(" ").toLowerCase();
 		return `      <tr data-context="${html(rule.context)}" data-status="${rule.status}" data-search="${html(search)}">
-        <td><a href="${rulePath.get(rule.id) ?? ""}">${rule.id}</a></td>
+        <td class="rbg-id"><a href="${rulePath.get(rule.id) ?? ""}">${rule.id}</a></td>
         <td>${html(rule.context)}</td>
         <td>${rule.status}</td>
         <td>${html(rule.summary)}</td>
@@ -289,6 +297,7 @@ ${contexts.map((context) => `      <option value="${html(context)}">${html(conte
 ${STATUSES.map((status) => `      <option value="${status}">${status}</option>`).join("\n")}
     </select>
   </div>
+  <div class="rbg-table">
   <table class="rbg-rules">
     <thead>
       <tr><th>${html(text.rule)}</th><th>${html(text.context)}</th><th>${html(text.status)}</th><th>${html(text.summary)}</th></tr>
@@ -297,12 +306,32 @@ ${STATUSES.map((status) => `      <option value="${status}">${status}</option>`)
 ${rows.join("\n")}
     </tbody>
   </table>
+  </div>
   <p class="rbg-empty" hidden>${html(text.noMatch)}</p>
 </StarlightPage>
 
 <style>
-  .rbg-filters { display: flex; flex-wrap: wrap; gap: 0.5rem; margin-bottom: 1rem; }
+  .rbg-filters { display: flex; flex-wrap: wrap; align-items: center; gap: 0.5rem; margin-bottom: 1rem; }
+  /* Starlight spaces sibling content blocks with margin-top; inside the filter row it misaligns the controls. */
+  .rbg-filters > * { margin: 0; }
+  .rbg-filters :is(input, select) {
+    border: 1px solid var(--sl-color-gray-5);
+    border-radius: 0.5rem;
+    background-color: var(--sl-color-bg);
+    color: var(--sl-color-white);
+    font: inherit;
+    font-size: var(--sl-text-sm);
+    padding: 0.5rem 0.75rem;
+    height: 2.5rem;
+    box-sizing: border-box;
+  }
   .rbg-filters input { flex: 1 1 16rem; }
+  .rbg-filters select { flex: 1 1 12rem; cursor: pointer; }
+  .rbg-filters :is(input, select):focus-visible { outline: 2px solid var(--sl-color-accent); outline-offset: 1px; }
+  .rbg-id { white-space: nowrap; }
+  .rbg-table { overflow-x: auto; }
+  .rbg-table table { margin: 0; }
+  .rbg-rules td:last-child { min-width: 16rem; }
 </style>
 
 <script>
@@ -370,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);
@@ -378,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
@@ -417,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.1",
+  "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": {