@serverkgg/bridge 0.1.2 → 0.1.4

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";
@@ -8,7 +8,10 @@ import { GuideOpenTab } from "../guides";
 import { MANIFEST_SCHEMA_VERSION, PackageKind } from "../manifest";
 import type { BridgeDriver, BridgeSetupModule } from "../modules";
 import {
+	type BridgeCatalogSection,
+	BridgeConfirm,
 	BridgeControl,
+	type BridgeDetailSection,
 	type BridgeFormSection,
 	BridgeFormTarget,
 	BridgeLayout,
@@ -16,7 +19,14 @@ import {
 	type BridgeTab,
 	type BridgeTableSection,
 } from "../panel";
-import { availabilityReportLines, placementReportLines, runValidate, setupReportLines } from "./validate";
+import { RULES_FILE, readShippedRules, writeRules } from "./rules";
+import {
+	availabilityReportLines,
+	confirmReportLines,
+	placementReportLines,
+	runValidate,
+	setupReportLines,
+} from "./validate";
 
 const text = (value: string) => ({
 	ar: value,
@@ -54,7 +64,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 +74,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 +82,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 +96,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 +104,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 +112,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 +148,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 +175,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 +202,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 +269,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 +287,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 +305,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 +323,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 +341,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 +359,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 +373,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 +389,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 +503,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 +532,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 +546,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 +580,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 +588,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 +596,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 +616,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 +651,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 +674,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({
@@ -674,3 +705,120 @@ describe("availability report", () => {
 		).toEqual([]);
 	});
 });
+
+describe("the confirm report", () => {
+	const driverWithSections = (sections: BridgeTab["sections"]): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		panel: {
+			tabs: [
+				{
+					id: "settings",
+					title: text("Settings"),
+					sections,
+				},
+			],
+		},
+	});
+
+	const versionForm = (confirm?: BridgeConfirm): BridgeFormSection => ({
+		layout: BridgeLayout.Form,
+		id: "version",
+		target: BridgeFormTarget.Variables,
+		reinstall: true,
+		confirm,
+		fields: [
+			{
+				key: "VERSION",
+				control: BridgeControl.Text,
+				label: text("Version"),
+			},
+		],
+	});
+
+	const modpacks = (confirm?: BridgeConfirm): BridgeCatalogSection => ({
+		layout: BridgeLayout.Catalog,
+		id: "modpacks",
+		module: "modpacks",
+		confirm,
+	});
+
+	const modpack = (confirm?: BridgeConfirm, reinstall?: boolean): BridgeDetailSection => ({
+		layout: BridgeLayout.Detail,
+		id: "modpack",
+		module: "modpack",
+		variable: "MODPACK",
+		reinstall,
+		confirm,
+	});
+
+	const worlds = (): BridgeTableSection => ({
+		layout: BridgeLayout.Table,
+		id: "worlds",
+		module: "worlds",
+		columns: [
+			{
+				key: "name",
+				label: text("Name"),
+			},
+		],
+		actions: [
+			{
+				id: "delete",
+				label: text("Delete"),
+				confirm: BridgeConfirm.Strong,
+			},
+		],
+	});
+
+	it("fails a form or a catalog that asks for a strong confirmation", () => {
+		expect(
+			confirmReportLines(
+				driverWithSections([
+					versionForm(BridgeConfirm.Strong),
+					modpacks(BridgeConfirm.Strong),
+				]),
+			),
+		).toEqual([
+			'  error: tab "settings" section "version" is a form with `confirm: strong` — the platform takes a restore point before applying it, so declare `normal`; `strong` is only for what nothing brings back',
+			'  error: tab "settings" section "modpacks" is a catalog with `confirm: strong` — the platform takes a restore point before applying it, so declare `normal`; `strong` is only for what nothing brings back',
+		]);
+	});
+
+	it("fails any section that reinstalls behind a strong confirmation", () => {
+		expect(
+			confirmReportLines(
+				driverWithSections([
+					modpack(BridgeConfirm.Strong, true),
+				]),
+			),
+		).toEqual([
+			'  error: tab "settings" section "modpack" reinstalls with `confirm: strong` — the platform takes a restore point before every reinstall, so declare `normal`; `strong` is only for what nothing brings back',
+		]);
+	});
+
+	it("leaves a strong action that deletes data and every normal confirmation alone", () => {
+		expect(
+			confirmReportLines(
+				driverWithSections([
+					versionForm(BridgeConfirm.Normal),
+					versionForm(),
+					modpacks(BridgeConfirm.Normal),
+					modpack(BridgeConfirm.Normal, true),
+					modpack(BridgeConfirm.Strong),
+					worlds(),
+				]),
+			),
+		).toEqual([]);
+	});
+});

package/src/cli/validate.ts

@@ -21,6 +21,7 @@ import {
 } from "../manifest";
 import type { BridgeDriver, BridgeSetupModule } from "../modules";
 import {
+	BridgeConfirm,
 	BridgeLayout,
 	BridgePlace,
 	type BridgeSection,
@@ -31,6 +32,7 @@ import {
 } from "../protocol";
 import { validateDriver, validatePortActivation } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
+import { rulesReportLines } from "./rules";
 
 const HELP = `serverk-bridge validate [options]
 
@@ -312,6 +314,39 @@ const reportAvailability = (driver: BridgeDriver) => {
 	}
 };
 
+const RESTORE_POINT_LAYOUTS: ReadonlySet<BridgeLayout> = new Set([
+	BridgeLayout.Form,
+	BridgeLayout.Catalog,
+]);
+
+export const confirmReportLines = (driver: BridgeDriver): string[] => {
+	const lines: string[] = [];
+
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			if (!("confirm" in section) || section.confirm !== BridgeConfirm.Strong) {
+				continue;
+			}
+
+			if (RESTORE_POINT_LAYOUTS.has(section.layout)) {
+				lines.push(
+					`  error: tab "${tab.id}" section "${section.id}" is a ${section.layout} with \`confirm: strong\` — the platform takes a restore point before applying it, so declare \`normal\`; \`strong\` is only for what nothing brings back`,
+				);
+
+				continue;
+			}
+
+			if ("reinstall" in section && section.reinstall === true) {
+				lines.push(
+					`  error: tab "${tab.id}" section "${section.id}" reinstalls with \`confirm: strong\` — the platform takes a restore point before every reinstall, so declare \`normal\`; \`strong\` is only for what nothing brings back`,
+				);
+			}
+		}
+	}
+
+	return lines;
+};
+
 const openTargetOf = (target: GuideOpenTarget) => {
 	if (target.tab === GuideOpenTab.Panel) {
 		return `panel tab "${target.tabId}"`;
@@ -433,6 +468,14 @@ const validateRunnablePackage = async (
 	validateDriver(driver);
 	validatePortActivation(manifest.container.ports, driver);
 
+	const confirmLines = confirmReportLines(driver);
+
+	if (confirmLines.length > 0) {
+		throw new Error(
+			`the panel asks for a strong confirmation where a restore point is taken:\n${confirmLines.join("\n")}`,
+		);
+	}
+
 	const conditionalPorts = manifest.container.ports.filter((port) => port.activeWhen.length > 0).length;
 	const pairedPorts = manifest.container.ports.filter((port) => port.protocol === PortProtocol.TcpUdp).length;
 	const blockPorts = manifest.container.ports.filter((port) => port.count > 1).length;
@@ -446,6 +489,7 @@ const validateRunnablePackage = async (
 		...botPortLines(manifest),
 		...botEnvironmentLines(manifest),
 		...detectLines,
+		...rulesReportLines(dir),
 	]) {
 		console.log(line);
 	}

package/src/codecs/ini.test.ts

@@ -1,4 +1,4 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import { mergeIni, parseIni } from "./ini";
 
 const SAMPLE = [
@@ -14,38 +14,38 @@ const SAMPLE = [
 ].join("\n");
 
 describe("parseIni", () => {
-	test("reads the keys of one section", () => {
+	it("reads the keys of one section", () => {
 		expect(parseIni(SAMPLE, "Server")).toEqual({
 			name: "serverk",
 			maxPlayers: "10",
 		});
 	});
 
-	test("reads another section without leaking keys", () => {
+	it("reads another section without leaking keys", () => {
 		expect(parseIni(SAMPLE, "Admin")).toEqual({
 			password: "secret",
 		});
 	});
 
-	test("reads the keys before the first header when no section is asked for", () => {
+	it("reads the keys before the first header when no section is asked for", () => {
 		expect(parseIni("welcome=hello\n[Server]\nname=x\n")).toEqual({
 			welcome: "hello",
 		});
 	});
 
-	test("keeps the last of a repeated key", () => {
+	it("keeps the last of a repeated key", () => {
 		expect(parseIni("[S]\nmod=a\nmod=b\n", "S")).toEqual({
 			mod: "b",
 		});
 	});
 
-	test("returns nothing for an unknown section", () => {
+	it("returns nothing for an unknown section", () => {
 		expect(parseIni(SAMPLE, "Nothing")).toEqual({});
 	});
 });
 
 describe("mergeIni", () => {
-	test("rewrites a value in place and keeps comments and order", () => {
+	it("rewrites a value in place and keeps comments and order", () => {
 		expect(
 			mergeIni(
 				SAMPLE,
@@ -69,7 +69,7 @@ describe("mergeIni", () => {
 		);
 	});
 
-	test("appends an unknown key at the end of its section", () => {
+	it("appends an unknown key at the end of its section", () => {
 		expect(
 			mergeIni(
 				SAMPLE,
@@ -93,7 +93,7 @@ describe("mergeIni", () => {
 		);
 	});
 
-	test("creates a section that does not exist yet", () => {
+	it("creates a section that does not exist yet", () => {
 		expect(
 			mergeIni(
 				"[Server]\nname=x\n",
@@ -105,7 +105,7 @@ describe("mergeIni", () => {
 		).toBe("[Server]\nname=x\n\n[Game]\nlevel=3\n");
 	});
 
-	test("drops repeated occurrences of a key it rewrites", () => {
+	it("drops repeated occurrences of a key it rewrites", () => {
 		expect(
 			mergeIni(
 				"[S]\nmod=a\nmod=b\nother=1\n",
@@ -117,7 +117,7 @@ describe("mergeIni", () => {
 		).toBe("[S]\nmod=c\nother=1\n");
 	});
 
-	test("writes into an empty file", () => {
+	it("writes into an empty file", () => {
 		expect(
 			mergeIni(
 				"",
@@ -129,7 +129,7 @@ describe("mergeIni", () => {
 		).toBe("[Server]\nname=x\n");
 	});
 
-	test("writes preamble keys when no section is asked for", () => {
+	it("writes preamble keys when no section is asked for", () => {
 		expect(
 			mergeIni("welcome=hello\n[Server]\nname=x\n", {
 				welcome: "salam",
@@ -138,7 +138,7 @@ describe("mergeIni", () => {
 		).toBe("welcome=salam\nextra=1\n[Server]\nname=x\n");
 	});
 
-	test("leaves other sections untouched", () => {
+	it("leaves other sections untouched", () => {
 		expect(
 			mergeIni(
 				"[A]\nkey=1\n[B]\nkey=2\n",

package/src/codecs/javaProperties.test.ts

@@ -1,33 +1,33 @@
-import { describe, expect, test } from "bun:test";
+import { describe, expect, it } from "bun:test";
 import { escapeJavaProperty, mergeJavaProperties, parseJavaProperties, unescapeJavaProperty } from "./javaProperties";
 
 const ARABIC = "سيرفرك";
 
 describe("parseJavaProperties", () => {
-	test("decodes the unicode escapes the java server writes", () => {
+	it("decodes the unicode escapes the java server writes", () => {
 		expect(parseJavaProperties("motd=\\u0633\\u064A\\u0631\\u0641\\u0631\\u0643\n")).toEqual({
 			motd: ARABIC,
 		});
 	});
 
-	test("decodes backslash escapes in values", () => {
+	it("decodes backslash escapes in values", () => {
 		expect(parseJavaProperties("resource-pack=https\\://example.com/pack.zip\nmotd=a\\tb\\\\c\n")).toEqual({
 			"resource-pack": "https://example.com/pack.zip",
 			motd: "a\tb\\c",
 		});
 	});
 
-	test("repairs a value the server stored as latin-1 bytes of utf-8", () => {
+	it("repairs a value the server stored as latin-1 bytes of utf-8", () => {
 		expect(parseJavaProperties("motd=ddss \\u00D9\\u008A\\u00D8\\u00AA\n")).toEqual({
 			motd: "ddss يت",
 		});
 	});
 
-	test("keeps plain latin-1 text that is not utf-8", () => {
+	it("keeps plain latin-1 text that is not utf-8", () => {
 		expect(unescapeJavaProperty("caf\\u00E9")).toBe("café");
 	});
 
-	test("keeps comments and plain values", () => {
+	it("keeps comments and plain values", () => {
 		expect(parseJavaProperties("#Minecraft server properties\nmax-players=20\n")).toEqual({
 			"max-players": "20",
 		});
@@ -35,7 +35,7 @@ describe("parseJavaProperties", () => {
 });
 
 describe("mergeJavaProperties", () => {
-	test("writes non ascii text as unicode escapes", () => {
+	it("writes non ascii text as unicode escapes", () => {
 		expect(
 			mergeJavaProperties("motd=A Minecraft Server\nmax-players=20\n", {
 				motd: ARABIC,
@@ -43,21 +43,21 @@ describe("mergeJavaProperties", () => {
 		).toBe("motd=\\u0633\\u064A\\u0631\\u0641\\u0631\\u0643\nmax-players=20\n");
 	});
 
-	test("escapes the characters java treats as separators", () => {
+	it("escapes the characters java treats as separators", () => {
 		expect(escapeJavaProperty("https://a.b#c=d!e")).toBe("https\\://a.b\\#c\\=d\\!e");
 	});
 
-	test("escapes a leading space and control characters", () => {
+	it("escapes a leading space and control characters", () => {
 		expect(escapeJavaProperty(" a\tb\\c")).toBe("\\ a\\tb\\\\c");
 	});
 
-	test("round trips astral characters", () => {
+	it("round trips astral characters", () => {
 		const value = "hi 🎮";
 
 		expect(unescapeJavaProperty(escapeJavaProperty(value))).toBe(value);
 	});
 
-	test("appends a key the file does not have yet", () => {
+	it("appends a key the file does not have yet", () => {
 		expect(
 			mergeJavaProperties("", {
 				motd: "hello",