@serverkgg/bridge 0.1.2 → 0.1.3

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);
+};

package/src/cli/validate.test.ts

@@ -1,4 +1,4 @@
-import { afterEach, beforeEach, describe, expect, spyOn, test } from "bun:test";
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
@@ -16,6 +16,7 @@ import {
 	type BridgeTab,
 	type BridgeTableSection,
 } from "../panel";
+import { RULES_FILE, readShippedRules, writeRules } from "./rules";
 import { availabilityReportLines, placementReportLines, runValidate, setupReportLines } from "./validate";
 
 const text = (value: string) => ({
@@ -54,7 +55,7 @@ describe("validate", () => {
 		});
 	});
 
-	test("refuses a file: bridge dependency", async () => {
+	it("refuses a file: bridge dependency", async () => {
 		writePackage({
 			"@serverkgg/bridge": "file:../serverk/modules/bridge",
 		});
@@ -64,7 +65,7 @@ describe("validate", () => {
 		);
 	});
 
-	test("refuses a link: bridge dependency", async () => {
+	it("refuses a link: bridge dependency", async () => {
 		writePackage({
 			"@serverkgg/bridge": "link:@serverkgg/bridge",
 		});
@@ -72,7 +73,7 @@ describe("validate", () => {
 		await expect(validate()).rejects.toThrow('depends on @serverkgg/bridge via "link:@serverkgg/bridge"');
 	});
 
-	test("refuses a file: bridge devDependency", async () => {
+	it("refuses a file: bridge devDependency", async () => {
 		writeFileSync(
 			join(root, "package.json"),
 			JSON.stringify({
@@ -86,7 +87,7 @@ describe("validate", () => {
 		await expect(validate()).rejects.toThrow("pin a published version");
 	});
 
-	test("accepts a published bridge dependency and moves on to the manifest", async () => {
+	it("accepts a published bridge dependency and moves on to the manifest", async () => {
 		writePackage({
 			"@serverkgg/bridge": "0.0.3",
 		});
@@ -94,7 +95,7 @@ describe("validate", () => {
 		await expect(validate()).rejects.toThrow("missing serverk.yml");
 	});
 
-	test("ignores a package without a bridge dependency", async () => {
+	it("ignores a package without a bridge dependency", async () => {
 		writePackage({
 			zod: "4.4.3",
 		});
@@ -102,19 +103,19 @@ describe("validate", () => {
 		await expect(validate()).rejects.toThrow("missing serverk.yml");
 	});
 
-	test("ignores a package.json that is absent", async () => {
+	it("ignores a package.json that is absent", async () => {
 		await expect(validate()).rejects.toThrow("missing serverk.yml");
 	});
 });
 
 describe("the setup report", () => {
-	test("says none for a driver that declares no setup", () => {
+	it("says none for a driver that declares no setup", () => {
 		expect(setupReportLines(undefined)).toEqual([
 			"  setup: none",
 		]);
 	});
 
-	test("names every step, its kind, whether it is required, and where it lands", () => {
+	it("names every step, its kind, whether it is required, and where it lands", () => {
 		const setup: BridgeSetupModule = {
 			kind: BridgeKind.Setup,
 			steps: [
@@ -138,8 +139,8 @@ describe("the setup report", () => {
 				},
 				{
 					kind: BridgeSetupStepKind.Open,
-					id: "txadmin",
-					title: text("txAdmin"),
+					id: "dashboard",
+					title: text("Dashboard"),
 					required: false,
 					target: {
 						tab: GuideOpenTab.Panel,
@@ -165,12 +166,12 @@ describe("the setup report", () => {
 			"  setup: 4 step(s)",
 			"    license — form, required → license/license [LICENSE_KEY]",
 			"    verify — driver, required → driver (needs the game running)",
-			'    txadmin — open, optional → panel tab "license"',
+			'    dashboard — open, optional → panel tab "license"',
 			"    invite — open, optional → access",
 		]);
 	});
 
-	test("leaves a driver step that needs nothing running with no target", () => {
+	it("leaves a driver step that needs nothing running with no target", () => {
 		expect(
 			setupReportLines({
 				kind: BridgeKind.Setup,
@@ -192,7 +193,7 @@ describe("the setup report", () => {
 		]);
 	});
 
-	test("reads an omitted required as required, the way the platform does", () => {
+	it("reads an omitted required as required, the way the platform does", () => {
 		expect(
 			setupReportLines({
 				kind: BridgeKind.Setup,
@@ -259,7 +260,7 @@ describe("the placement report", () => {
 		},
 	});
 
-	test("says nothing about a roster table that declares where it belongs", () => {
+	it("says nothing about a roster table that declares where it belongs", () => {
 		expect(
 			placementReportLines(
 				driverWithTabs([
@@ -277,7 +278,7 @@ describe("the placement report", () => {
 		]);
 	});
 
-	test("warns that the platform absorbs an unplaced players collection by convention", () => {
+	it("warns that the platform absorbs an unplaced players collection by convention", () => {
 		expect(
 			placementReportLines(
 				driverWithTabs([
@@ -295,7 +296,7 @@ describe("the placement report", () => {
 		]);
 	});
 
-	test("warns about a tab that takes the name of a platform sidebar entry", () => {
+	it("warns about a tab that takes the name of a platform sidebar entry", () => {
 		expect(
 			placementReportLines(
 				driverWithTabs([
@@ -313,7 +314,7 @@ describe("the placement report", () => {
 		]);
 	});
 
-	test("leaves a players tab alone while it is the roster tab", () => {
+	it("leaves a players tab alone while it is the roster tab", () => {
 		expect(
 			placementReportLines(
 				driverWithTabs([
@@ -331,7 +332,7 @@ describe("the placement report", () => {
 		]);
 	});
 
-	test("warns about a players tab that holds no roster", () => {
+	it("warns about a players tab that holds no roster", () => {
 		expect(
 			placementReportLines(
 				driverWithTabs([
@@ -349,7 +350,7 @@ describe("the placement report", () => {
 		]);
 	});
 
-	test("says nothing about a tab that declares no sections at all", () => {
+	it("says nothing about a tab that declares no sections at all", () => {
 		expect(
 			placementReportLines(
 				driverWithTabs([
@@ -363,7 +364,7 @@ describe("the placement report", () => {
 		).toEqual([]);
 	});
 
-	test("still warns about an empty players tab, which holds no roster", () => {
+	it("still warns about an empty players tab, which holds no roster", () => {
 		expect(
 			placementReportLines(
 				driverWithTabs([
@@ -379,7 +380,7 @@ describe("the placement report", () => {
 		]);
 	});
 
-	test("says nothing about a tab that keeps a leftover section", () => {
+	it("says nothing about a tab that keeps a leftover section", () => {
 		expect(
 			placementReportLines(
 				driverWithTabs([
@@ -493,6 +494,7 @@ describe("validating a bot package", () => {
 		writeFileSync(join(root, "assets/logo.webp"), webp(256, 256));
 		writeFileSync(join(root, "assets/banner.webp"), webp(1280, 720));
 		writeFileSync(join(root, "src/driver.ts"), BOT_DRIVER);
+		writeRules(root, readShippedRules());
 	};
 
 	const validate = () => {
@@ -521,7 +523,7 @@ describe("validating a bot package", () => {
 		});
 	});
 
-	test("validates a bot with no ports and says which kind it read", async () => {
+	it("validates a bot with no ports and says which kind it read", async () => {
 		writeBot(botManifest());
 
 		await validate();
@@ -535,7 +537,27 @@ describe("validating a bot package", () => {
 		expect(lines.some((line) => line.includes("warning"))).toBe(false);
 	});
 
-	test("says when a bot turns the environment vault on", async () => {
+	it("warns about a missing rule file and still validates", async () => {
+		writeBot(botManifest());
+		rmSync(join(root, RULES_FILE));
+
+		await validate();
+
+		expect(lines).toContain("bot-node is valid");
+		expect(lines).toContain(`  warning: ${RULES_FILE} is missing — run "serverk-bridge rules"`);
+	});
+
+	it("warns about a stale rule file and still validates", async () => {
+		writeBot(botManifest());
+		writeFileSync(join(root, RULES_FILE), "# edited by hand\n");
+
+		await validate();
+
+		expect(lines).toContain("bot-node is valid");
+		expect(lines).toContain(`  warning: ${RULES_FILE} is out of date — run "serverk-bridge rules"`);
+	});
+
+	it("says when a bot turns the environment vault on", async () => {
 		writeBot(
 			botManifest({
 				environment: {
@@ -549,7 +571,7 @@ describe("validating a bot package", () => {
 		expect(lines).toContain("  environment: vault on");
 	});
 
-	test("fails a bot whose detection table is missing", async () => {
+	it("fails a bot whose detection table is missing", async () => {
 		writeBot(botManifest(), null);
 
 		await expect(validate()).rejects.toThrow(
@@ -557,7 +579,7 @@ describe("validating a bot package", () => {
 		);
 	});
 
-	test("fails a bot whose detection table is stale", async () => {
+	it("fails a bot whose detection table is stale", async () => {
 		writeBot(botManifest(), "{}\n");
 
 		await expect(validate()).rejects.toThrow(
@@ -565,7 +587,7 @@ describe("validating a bot package", () => {
 		);
 	});
 
-	test("warns about a port on a bot but still validates it", async () => {
+	it("warns about a port on a bot but still validates it", async () => {
 		writeBot(
 			botManifest({
 				container: {
@@ -585,7 +607,7 @@ describe("validating a bot package", () => {
 		);
 	});
 
-	test("fails a bot that declares platform secrets", async () => {
+	it("fails a bot that declares platform secrets", async () => {
 		writeBot(
 			botManifest({
 				secrets: [
@@ -620,7 +642,7 @@ describe("availability report", () => {
 		modules,
 	});
 
-	test("warns about a protected module that cannot say when its action is unavailable", () => {
+	it("warns about a protected module that cannot say when its action is unavailable", () => {
 		expect(
 			availabilityReportLines(
 				driverWithModules({
@@ -643,7 +665,7 @@ describe("availability report", () => {
 		]);
 	});
 
-	test("says nothing when the protected module declares the hook or protects nothing", () => {
+	it("says nothing when the protected module declares the hook or protects nothing", () => {
 		expect(
 			availabilityReportLines(
 				driverWithModules({

package/src/cli/validate.ts

@@ -31,6 +31,7 @@ import {
 } from "../protocol";
 import { validateDriver, validatePortActivation } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
+import { rulesReportLines } from "./rules";
 
 const HELP = `serverk-bridge validate [options]
 
@@ -446,6 +447,7 @@ const validateRunnablePackage = async (
 		...botPortLines(manifest),
 		...botEnvironmentLines(manifest),
 		...detectLines,
+		...rulesReportLines(dir),
 	]) {
 		console.log(line);
 	}