@serverkgg/bridge 0.1.2 → 0.1.4

package/src/cli/rules.test.ts

@@ -0,0 +1,198 @@
+import { afterEach, beforeEach, describe, expect, it } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import {
+	RULES_FILE,
+	readShippedRules,
+	rulesReportLines,
+	rulesState,
+	runRules,
+	SHIPPED_RULES_PATH,
+	writeRules,
+} from "./rules";
+
+const SHIPPED = "# Serverk package\n\nthe conventions\n";
+
+describe("rules", () => {
+	let root = "";
+	let target = "";
+
+	const writeTarget = (text: string) => {
+		mkdirSync(dirname(target), {
+			recursive: true,
+		});
+		writeFileSync(target, text);
+	};
+
+	beforeEach(() => {
+		root = mkdtempSync(`${tmpdir()}/serverk-rules-`);
+		target = join(root, RULES_FILE);
+	});
+
+	afterEach(() => {
+		rmSync(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	it("writes the file and its folders when it is missing", () => {
+		expect(writeRules(root, SHIPPED)).toEqual({
+			kind: "written",
+		});
+
+		expect(readFileSync(target, "utf8")).toBe(SHIPPED);
+	});
+
+	it("rewrites a file that is out of date", () => {
+		writeTarget("# edited by hand\n");
+
+		expect(writeRules(root, SHIPPED)).toEqual({
+			kind: "written",
+		});
+
+		expect(readFileSync(target, "utf8")).toBe(SHIPPED);
+	});
+
+	it("leaves an identical file untouched", () => {
+		writeTarget(SHIPPED);
+
+		const before = statSync(target).mtimeMs;
+
+		expect(writeRules(root, SHIPPED)).toEqual({
+			kind: "unchanged",
+		});
+
+		expect(statSync(target).mtimeMs).toBe(before);
+	});
+
+	it("reports a target it cannot write instead of throwing", () => {
+		writeFileSync(join(root, ".claude"), "a file where the folder should be");
+
+		const result = writeRules(root, SHIPPED);
+
+		expect(result.kind).toBe("failed");
+		expect(existsSync(target)).toBe(false);
+	});
+
+	it("names the state of the file on disk", () => {
+		expect(rulesState(root, SHIPPED)).toBe("missing");
+
+		writeTarget("# stale\n");
+
+		expect(rulesState(root, SHIPPED)).toBe("stale");
+
+		writeTarget(SHIPPED);
+
+		expect(rulesState(root, SHIPPED)).toBe("current");
+	});
+
+	it("writes the shipped rules when run", async () => {
+		await runRules([
+			"--dir",
+			root,
+		]);
+
+		expect(readFileSync(target, "utf8")).toBe(readShippedRules());
+	});
+
+	it("succeeds without writing when the target cannot be written", async () => {
+		writeFileSync(join(root, ".claude"), "a file where the folder should be");
+
+		await expect(
+			runRules([
+				"--dir",
+				root,
+			]),
+		).resolves.toBeUndefined();
+	});
+
+	it("check fails when the file is missing and writes nothing", async () => {
+		await expect(
+			runRules([
+				"--dir",
+				root,
+				"--check",
+			]),
+		).rejects.toThrow(`${RULES_FILE} is missing — run "serverk-bridge rules"`);
+
+		expect(existsSync(target)).toBe(false);
+	});
+
+	it("check fails when the file is out of date and leaves it alone", async () => {
+		writeTarget("# stale\n");
+
+		await expect(
+			runRules([
+				"--dir",
+				root,
+				"--check",
+			]),
+		).rejects.toThrow(`${RULES_FILE} is out of date — run "serverk-bridge rules"`);
+
+		expect(readFileSync(target, "utf8")).toBe("# stale\n");
+	});
+
+	it("check passes when the file matches the shipped rules", async () => {
+		writeTarget(readShippedRules());
+
+		await expect(
+			runRules([
+				"--dir",
+				root,
+				"--check",
+			]),
+		).resolves.toBeUndefined();
+	});
+
+	it("validate warns about a missing or stale file and says nothing about a current one", () => {
+		expect(rulesReportLines(root)).toEqual([
+			`  warning: ${RULES_FILE} is missing — run "serverk-bridge rules"`,
+		]);
+
+		writeTarget("# stale\n");
+
+		expect(rulesReportLines(root)).toEqual([
+			`  warning: ${RULES_FILE} is out of date — run "serverk-bridge rules"`,
+		]);
+
+		writeTarget(readShippedRules());
+
+		expect(rulesReportLines(root)).toEqual([]);
+	});
+});
+
+describe("the shipped rules", () => {
+	const packageRoot = join(dirname(SHIPPED_RULES_PATH), "..");
+
+	it("sit at rules/package.md beside the bridge's package.json", () => {
+		expect(SHIPPED_RULES_PATH).toBe(join(packageRoot, "rules/package.md"));
+		expect(existsSync(join(packageRoot, "package.json"))).toBe(true);
+	});
+
+	it("are published with the module", () => {
+		const manifest = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+
+		expect(manifest.name).toBe("@serverkgg/bridge");
+		expect(manifest.files).toContain("rules");
+	});
+
+	it("always load, with no paths frontmatter", () => {
+		const text = readShippedRules();
+
+		expect(text.startsWith("---")).toBe(false);
+		expect(text).not.toMatch(/^paths:/m);
+	});
+
+	it("send the reader to the project instructions in ../serverk/CLAUDE.md", () => {
+		expect(readShippedRules()).toContain("../serverk/CLAUDE.md");
+	});
+
+	it("say they are generated and must not be edited in place", () => {
+		const opening = readShippedRules().split("\n").slice(0, 3).join("\n");
+
+		expect(opening).toContain("serverk-bridge rules");
+		expect(opening).toContain("Do not edit it here");
+	});
+});

package/src/cli/rules.ts

@@ -0,0 +1,188 @@
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { errorText } from "../runtime/bridgeLog";
+
+export const RULES_FILE = ".claude/rules/package.md";
+
+export const SHIPPED_RULES_PATH = fileURLToPath(new URL("../../rules/package.md", import.meta.url));
+
+const RULES_COMMAND = "serverk-bridge rules";
+
+const HELP = `serverk-bridge rules [options]
+
+write ${RULES_FILE}, the conventions for package code, from the bridge this package pins.
+the file is generated on every install, so it is gitignored and never edited in place.
+a write that fails is reported and never fails the install.
+
+options:
+  --dir <path>   package directory (default: current directory)
+  --check        change nothing, fail when the file is missing or out of date
+  --help         show this help`;
+
+export type RulesState = "current" | "missing" | "stale";
+
+export type RulesResult =
+	| {
+			kind: "unchanged";
+	  }
+	| {
+			kind: "written";
+	  }
+	| {
+			kind: "failed";
+			reason: string;
+	  };
+
+export const readShippedRules = () => {
+	return readFileSync(SHIPPED_RULES_PATH, "utf8");
+};
+
+const rulesPath = (dir: string) => {
+	return join(resolve(dir), RULES_FILE);
+};
+
+const readCurrent = (dir: string) => {
+	try {
+		return readFileSync(rulesPath(dir), "utf8");
+	} catch {
+		return null;
+	}
+};
+
+export const rulesState = (dir: string, shipped: string): RulesState => {
+	const current = readCurrent(dir);
+
+	if (current === null) {
+		return "missing";
+	}
+
+	return current === shipped ? "current" : "stale";
+};
+
+export const writeRules = (dir: string, shipped: string): RulesResult => {
+	if (rulesState(dir, shipped) === "current") {
+		return {
+			kind: "unchanged",
+		};
+	}
+
+	const target = rulesPath(dir);
+
+	try {
+		mkdirSync(dirname(target), {
+			recursive: true,
+		});
+		writeFileSync(target, shipped);
+	} catch (error) {
+		return {
+			kind: "failed",
+			reason: errorText(error),
+		};
+	}
+
+	return {
+		kind: "written",
+	};
+};
+
+export const rulesReportLines = (dir: string): string[] => {
+	let shipped: string;
+
+	try {
+		shipped = readShippedRules();
+	} catch {
+		return [];
+	}
+
+	const state = rulesState(dir, shipped);
+
+	if (state === "current") {
+		return [];
+	}
+
+	return [
+		`  warning: ${RULES_FILE} is ${state === "missing" ? "missing" : "out of date"} — run "${RULES_COMMAND}"`,
+	];
+};
+
+const checkRules = (dir: string) => {
+	const state = rulesState(dir, readShippedRules());
+
+	if (state === "missing") {
+		throw new Error(`${RULES_FILE} is missing — run "${RULES_COMMAND}"`);
+	}
+
+	if (state === "stale") {
+		throw new Error(`${RULES_FILE} is out of date — run "${RULES_COMMAND}"`);
+	}
+
+	console.log(`${RULES_FILE} is up to date`);
+};
+
+const applyRules = (dir: string) => {
+	let shipped: string;
+
+	try {
+		shipped = readShippedRules();
+	} catch (error) {
+		console.error(`skipped ${RULES_FILE}: the bridge ships no rules (${errorText(error)})`);
+
+		return;
+	}
+
+	const result = writeRules(dir, shipped);
+
+	switch (result.kind) {
+		case "unchanged": {
+			return;
+		}
+
+		case "written": {
+			console.log(`wrote ${RULES_FILE}`);
+
+			return;
+		}
+
+		case "failed": {
+			console.error(`could not write ${RULES_FILE}: ${result.reason}`);
+
+			return;
+		}
+	}
+};
+
+export const runRules = async (args: string[]) => {
+	const { values } = parseArgs({
+		args,
+		options: {
+			dir: {
+				type: "string",
+				default: ".",
+			},
+			check: {
+				type: "boolean",
+				default: false,
+			},
+			help: {
+				type: "boolean",
+				default: false,
+			},
+		},
+	});
+
+	if (values.help) {
+		console.log(HELP);
+
+		return;
+	}
+
+	if (values.check) {
+		checkRules(values.dir);
+
+		return;
+	}
+
+	applyRules(values.dir);
+};