@serverkgg/bridge 0.0.8 → 0.0.10

package/src/runtime/bridgeDriver.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { BridgeKind, PortJoin, PortProtocol } from "../core";
+import { BridgeKind, BridgeSetupStepKind, PortJoin, PortProtocol } from "../core";
+import { GuideOpenTab } from "../guides";
 import type { ManifestPort, ManifestPortActivation } from "../manifest";
-import type { BridgeDriver } from "../modules";
+import type { BridgeDriver, BridgePendingModule, BridgeSetupModule } from "../modules";
 import {
 	BridgeConfirm,
 	BridgeControl,
@@ -9,8 +10,11 @@ import {
 	BridgeFormTarget,
 	BridgeLayout,
 	type BridgeSectionAction,
+	type BridgeSectionUpload,
+	BridgeUploadMode,
 	type BridgeVisibleWhen,
 } from "../panel";
+import type { BridgeSetupStep } from "../protocol";
 import { validateDriver, validatePortActivation } from "./bridgeDriver";
 
 const text = (value: string) => ({
@@ -647,6 +651,747 @@ describe("validatePortActivation", () => {
 				],
 				driverWithVariables(),
 			),
-		).toThrow('port "bedrock" activeWhen[0] names "CROSSPLAY", which no variables form or catalog declares');
+		).toThrow('port "bedrock" activeWhen[0] names "CROSSPLAY", which no variables form, catalog or detail declares');
+	});
+});
+
+const driverWithDetail = (): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	modules: {
+		modpackStatus: {
+			kind: BridgeKind.Detail,
+			read: async () => null,
+			actions: {
+				update: async () => null,
+			},
+		},
+	},
+	panel: {
+		tabs: [
+			{
+				id: "version",
+				title: text("Version"),
+				sections: [
+					{
+						layout: BridgeLayout.Form,
+						id: "version",
+						target: BridgeFormTarget.Variables,
+						fields: [
+							field("MC_VERSION"),
+						],
+						clears: [
+							{
+								variable: "MODPACK",
+								warning: text("Applying this removes the modpack"),
+							},
+						],
+					},
+					{
+						layout: BridgeLayout.Detail,
+						id: "modpack-status",
+						module: "modpackStatus",
+						variable: "MODPACK",
+						reinstall: true,
+						related: {
+							tab: "modpacks",
+							label: text("Browse modpacks"),
+						},
+						actions: [
+							{
+								id: "update",
+								label: text("Update"),
+							},
+						],
+					},
+				],
+			},
+			{
+				id: "modpacks",
+				title: text("Modpacks"),
+				sections: [
+					{
+						layout: BridgeLayout.Actions,
+						id: "noop",
+						module: "noop",
+						actions: [
+							{
+								id: "ping",
+								label: text("Ping"),
+							},
+						],
+					},
+				],
+			},
+		],
+	},
+});
+
+const withNoop = (driver: BridgeDriver): BridgeDriver => ({
+	...driver,
+	modules: {
+		...driver.modules,
+		noop: {
+			kind: BridgeKind.Actions,
+			actions: {
+				ping: async () => {
+					return;
+				},
+			},
+		},
+	},
+});
+
+const detailSectionOf = (driver: BridgeDriver) => {
+	const section = driver.panel?.tabs[0]?.sections[1];
+
+	if (section?.layout !== BridgeLayout.Detail) {
+		throw new Error("fixture is missing its detail section");
+	}
+
+	return section;
+};
+
+const clearingFormOf = (driver: BridgeDriver) => {
+	const section = driver.panel?.tabs[0]?.sections[0];
+
+	if (section?.layout !== BridgeLayout.Form) {
+		throw new Error("fixture is missing its form section");
+	}
+
+	return section;
+};
+
+describe("detail sections", () => {
+	test("accepts a detail section on a detail module", () => {
+		expect(() => validateDriver(withNoop(driverWithDetail()))).not.toThrow();
+	});
+
+	test("rejects a section pointing at a module that is not a detail module", () => {
+		const driver = withNoop(driverWithDetail());
+
+		driver.modules = {
+			...driver.modules,
+			modpackStatus: {
+				kind: BridgeKind.Collection,
+				list: async () => [],
+			},
+		};
+
+		expect(() => validateDriver(driver)).toThrow('references "modpackStatus", which is not a detail module');
+	});
+
+	test("rejects an action the module does not implement", () => {
+		const driver = withNoop(driverWithDetail());
+
+		detailSectionOf(driver).actions = [
+			{
+				id: "reinstall",
+				label: text("Reinstall"),
+			},
+		];
+
+		expect(() => validateDriver(driver)).toThrow(
+			'declares action "reinstall", which module "modpackStatus" does not implement',
+		);
+	});
+
+	test("rejects a download action, since a detail has no rows to serve", () => {
+		const driver = withNoop(driverWithDetail());
+
+		detailSectionOf(driver).actions = [
+			{
+				id: "update",
+				label: text("Update"),
+				download: true,
+			},
+		];
+
+		expect(() => validateDriver(driver)).toThrow('declares action "update" as a download');
+	});
+
+	test("rejects a related tab the panel does not declare", () => {
+		const driver = withNoop(driverWithDetail());
+
+		detailSectionOf(driver).related = {
+			tab: "worlds",
+			label: text("Worlds"),
+		};
+
+		expect(() => validateDriver(driver)).toThrow('relates to tab "worlds", which the panel does not declare');
+	});
+
+	test("counts a detail variable as declared for port activation", () => {
+		expect(() =>
+			validatePortActivation(
+				[
+					port([
+						{
+							variable: "MODPACK",
+							empty: false,
+						},
+					]),
+				],
+				driverWithDetail(),
+			),
+		).not.toThrow();
+	});
+});
+
+describe("form clears", () => {
+	test("accepts a clear of a variable a detail section declares", () => {
+		expect(() => validateDriver(withNoop(driverWithDetail()))).not.toThrow();
+	});
+
+	test("rejects a clear of a variable nothing declares", () => {
+		const driver = withNoop(driverWithDetail());
+
+		clearingFormOf(driver).clears = [
+			{
+				variable: "CROSSPLAY",
+				warning: text("Applying this turns crossplay off"),
+			},
+		];
+
+		expect(() => validateDriver(driver)).toThrow(
+			'clears "CROSSPLAY", which no variables form, catalog or detail declares',
+		);
+	});
+
+	test("rejects a clear of one of the form's own fields", () => {
+		const driver = withNoop(driverWithDetail());
+
+		clearingFormOf(driver).clears = [
+			{
+				variable: "MC_VERSION",
+				warning: text("Applying this resets the version"),
+			},
+		];
+
+		expect(() => validateDriver(driver)).toThrow('clears "MC_VERSION", which is one of its own fields');
+	});
+
+	test("rejects clears on a form that writes settings", () => {
+		const driver = withNoop(driverWithDetail());
+		const form = clearingFormOf(driver);
+
+		form.target = BridgeFormTarget.Settings;
+		form.module = "config";
+
+		driver.modules = {
+			...driver.modules,
+			config: {
+				kind: BridgeKind.Settings,
+				read: async () => ({}),
+				write: async () => {
+					return;
+				},
+			},
+		};
+
+		expect(() => validateDriver(driver)).toThrow("clears variables but does not target variables");
+	});
+});
+
+describe("table uploads", () => {
+	const driverWithUpload = (upload: BridgeSectionUpload): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		modules: {
+			modpackPending: {
+				kind: BridgeKind.Collection,
+				list: async () => [],
+				add: async () => {
+					return;
+				},
+			},
+		},
+		panel: {
+			tabs: [
+				{
+					id: "modpacks",
+					title: text("Modpacks"),
+					sections: [
+						{
+							layout: BridgeLayout.Table,
+							id: "pending",
+							module: "modpackPending",
+							columns: [
+								{
+									key: "name",
+									label: text("Name"),
+								},
+							],
+							upload,
+						},
+					],
+				},
+			],
+		},
+	});
+
+	const upload = (mode?: BridgeUploadMode): BridgeSectionUpload => ({
+		label: text("Upload"),
+		extensions: [
+			"jar",
+		],
+		staging: ".serverk-staging/pending-upload",
+		mode,
+	});
+
+	test("accepts an upload that declares no mode", () => {
+		expect(() => validateDriver(driverWithUpload(upload()))).not.toThrow();
+	});
+
+	test("accepts both declared upload modes", () => {
+		expect(() => validateDriver(driverWithUpload(upload(BridgeUploadMode.Archive)))).not.toThrow();
+		expect(() => validateDriver(driverWithUpload(upload(BridgeUploadMode.File)))).not.toThrow();
+	});
+
+	test("rejects an upload mode the platform does not know", () => {
+		const section = upload("stream" as BridgeUploadMode);
+
+		expect(() => validateDriver(driverWithUpload(section))).toThrow('declares an unknown upload mode "stream"');
+	});
+});
+
+describe("the pending module", () => {
+	const driverWithPending = (pending: BridgePendingModule): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		pending,
+	});
+
+	const pendingWith = (overrides: Partial<BridgePendingModule>): BridgePendingModule => ({
+		kind: BridgeKind.Pending,
+		staging: ".serverk-staging/pending-upload",
+		extensions: [
+			"jar",
+		],
+		list: async () => [],
+		add: async () => {
+			return;
+		},
+		...overrides,
+	});
+
+	test("accepts a driver that declares no pending module", () => {
+		expect(() =>
+			validateDriver({
+				install: {
+					kind: BridgeKind.Install,
+					run: async () => {
+						return;
+					},
+				},
+				lifecycle: {
+					kind: BridgeKind.Lifecycle,
+					command: async () => [
+						"run",
+					],
+				},
+			}),
+		).not.toThrow();
+	});
+
+	test("accepts a pending module declaring a staging path and one extension", () => {
+		expect(() => validateDriver(driverWithPending(pendingWith({})))).not.toThrow();
+	});
+
+	test("rejects a pending module carrying another kind", () => {
+		const pending = pendingWith({
+			kind: BridgeKind.Collection as BridgeKind.Pending,
+		});
+
+		expect(() => validateDriver(driverWithPending(pending))).toThrow(
+			'the pending module declares kind "collection", which is not "pending"',
+		);
+	});
+
+	test("rejects a pending module with no staging path", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						staging: "",
+					}),
+				),
+			),
+		).toThrow("the pending module declares no staging path");
+	});
+
+	test("rejects a staging path longer than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						staging: "x".repeat(129),
+					}),
+				),
+			),
+		).toThrow("the pending module staging path is 129 characters — the platform takes at most 128");
+	});
+
+	test("rejects a pending module declaring no extensions", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						extensions: [],
+					}),
+				),
+			),
+		).toThrow("the pending module declares no extensions");
+	});
+
+	test("rejects more extensions than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						extensions: Array.from({
+							length: 9,
+						}).map((_entry, index) => `e${index}`),
+					}),
+				),
+			),
+		).toThrow("the pending module declares 9 extensions — the platform takes at most 8");
+	});
+
+	test("rejects an extension longer than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithPending(
+					pendingWith({
+						extensions: [
+							"x".repeat(17),
+						],
+					}),
+				),
+			),
+		).toThrow('the pending module extension "xxxxxxxxxxxxxxxxx" is 17 characters — the platform takes at most 16');
+	});
+
+	test("reserves the pending module id for the singleton", () => {
+		expect(() =>
+			validateDriver({
+				install: {
+					kind: BridgeKind.Install,
+					run: async () => {
+						return;
+					},
+				},
+				lifecycle: {
+					kind: BridgeKind.Lifecycle,
+					command: async () => [
+						"run",
+					],
+				},
+				modules: {
+					pending: {
+						kind: BridgeKind.Collection,
+						list: async () => [],
+					},
+				},
+			}),
+		).toThrow('module id "pending" is reserved');
+	});
+});
+
+const driverWithSetup = (setup: BridgeSetupModule): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	setup,
+	panel: {
+		tabs: [
+			{
+				id: "settings",
+				title: text("Settings"),
+				sections: [
+					{
+						layout: BridgeLayout.Form,
+						id: "server",
+						target: BridgeFormTarget.Variables,
+						fields: [
+							field("SERVER_NAME"),
+							field("MOTD"),
+						],
+					},
+				],
+			},
+		],
+	},
+});
+
+const driverStep = (id: string) => ({
+	kind: BridgeSetupStepKind.Driver as const,
+	id,
+	title: text(id),
+});
+
+const setupWith = (steps: BridgeSetupStep[]): BridgeSetupModule => ({
+	kind: BridgeKind.Setup,
+	steps,
+});
+
+describe("the setup singleton", () => {
+	test("takes a driver step with both locales", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						driverStep("sign-in"),
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a setup that declares no steps", () => {
+		expect(() => validateDriver(driverWithSetup(setupWith([])))).toThrow("the setup module declares no steps");
+	});
+
+	test("rejects more steps than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith(
+						Array.from({
+							length: 9,
+						}).map((_entry, index) => driverStep(`step-${index}`)),
+					),
+				),
+			),
+		).toThrow("the setup module declares 9 steps — the platform takes at most 8");
+	});
+
+	test("rejects a step id that is not kebab-case", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						driverStep("signIn"),
+					]),
+				),
+			),
+		).toThrow('the setup module step id "signIn" must be kebab-case');
+	});
+
+	test("rejects the same step id twice", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						driverStep("sign-in"),
+						driverStep("sign-in"),
+					]),
+				),
+			),
+		).toThrow('the setup module declares step "sign-in" more than once');
+	});
+
+	test("rejects a title that is missing a locale", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Driver,
+							id: "sign-in",
+							title: {
+								ar: "",
+								en: "Sign in",
+							},
+						},
+					]),
+				),
+			),
+		).toThrow('the setup module step "sign-in" title needs both arabic and english text');
+	});
+
+	test("takes a form step that names an existing form section and its own fields", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Form,
+							id: "name",
+							title: text("Name"),
+							tab: "settings",
+							section: "server",
+							fields: [
+								"SERVER_NAME",
+							],
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a form step that names a section the panel does not declare", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Form,
+							id: "name",
+							title: text("Name"),
+							tab: "settings",
+							section: "missing",
+						},
+					]),
+				),
+			),
+		).toThrow(
+			'the setup module step "name" names tab "settings" section "missing", which is not a form section of this panel',
+		);
+	});
+
+	test("rejects a form step that names a field the section does not declare", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Form,
+							id: "name",
+							title: text("Name"),
+							tab: "settings",
+							section: "server",
+							fields: [
+								"PASSWORD",
+							],
+						},
+					]),
+				),
+			),
+		).toThrow('the setup module step "name" names field "PASSWORD", which section "server" does not declare');
+	});
+
+	test("takes an open step that names an existing panel tab", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Open,
+							id: "tune",
+							title: text("Tune"),
+							target: {
+								tab: GuideOpenTab.Panel,
+								tabId: "settings",
+							},
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects an open step that names a panel tab the panel does not declare", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Open,
+							id: "tune",
+							title: text("Tune"),
+							target: {
+								tab: GuideOpenTab.Panel,
+								tabId: "world",
+							},
+						},
+					]),
+				),
+			),
+		).toThrow('the setup module step "tune" opens panel tab "world", which the panel does not declare');
+	});
+
+	test("takes an open step that leaves the panel altogether", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Open,
+							id: "invite",
+							title: text("Invite"),
+							target: {
+								tab: GuideOpenTab.Access,
+							},
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("reserves the setup module id for the singleton", () => {
+		expect(() =>
+			validateDriver({
+				install: {
+					kind: BridgeKind.Install,
+					run: async () => {
+						return;
+					},
+				},
+				lifecycle: {
+					kind: BridgeKind.Lifecycle,
+					command: async () => [
+						"run",
+					],
+				},
+				modules: {
+					setup: {
+						kind: BridgeKind.Collection,
+						list: async () => [],
+					},
+				},
+			}),
+		).toThrow('module id "setup" is reserved');
 	});
 });