@serverkgg/bridge 0.0.9 → 0.0.11

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, BridgePendingModule } from "../modules";
+import type { BridgeDriver, BridgePendingModule, BridgeSetupModule } from "../modules";
 import {
 	BridgeConfirm,
 	BridgeControl,
@@ -13,6 +14,7 @@ import {
 	BridgeUploadMode,
 	type BridgeVisibleWhen,
 } from "../panel";
+import type { BridgeSetupStep } from "../protocol";
 import { validateDriver, validatePortActivation } from "./bridgeDriver";
 
 const text = (value: string) => ({
@@ -1125,3 +1127,511 @@ describe("the pending module", () => {
 		).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"),
+							{
+								key: "ADMIN_PASSWORD",
+								control: BridgeControl.Secret,
+								label: text("Admin password"),
+							},
+						],
+					},
+				],
+			},
+		],
+	},
+});
+
+const driverStep = (id: string) => ({
+	kind: BridgeSetupStepKind.Driver as const,
+	id,
+	title: text(id),
+});
+
+const setupWith = (steps: BridgeSetupStep[]): BridgeSetupModule => ({
+	kind: BridgeKind.Setup,
+	steps,
+	submit: async () => {
+		return;
+	},
+});
+
+const setupWithoutSubmit = (steps: BridgeSetupStep[]): BridgeSetupModule => ({
+	kind: BridgeKind.Setup,
+	steps,
+});
+
+const driverWithFields = (fields: BridgeField[]): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	panel: {
+		tabs: [
+			{
+				id: "settings",
+				title: text("Settings"),
+				sections: [
+					formSection("server", fields),
+				],
+			},
+		],
+	},
+});
+
+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("takes a form step over a secret field", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Form,
+							id: "password",
+							title: text("Password"),
+							tab: "settings",
+							section: "server",
+							fields: [
+								"ADMIN_PASSWORD",
+							],
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a driver step while the setup exports no submit", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWithoutSubmit([
+						driverStep("sign-in"),
+					]),
+				),
+			),
+		).toThrow("the setup module declares a driver step but exports no submit");
+	});
+
+	test("takes a setup with no submit while every step is answered elsewhere", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWithoutSubmit([
+						{
+							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');
+	});
+});
+
+describe("field patterns", () => {
+	test("takes a pattern on a text field and on a secret one", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Secret,
+						label: text("Licence key"),
+						pattern: "^cfxk_\\w{1,60}_\\w{1,20}$",
+						patternHint: text("A licence key starts with cfxk_"),
+					},
+					{
+						key: "SERVER_NAME",
+						control: BridgeControl.Text,
+						label: text("Name"),
+						pattern: "^.{1,32}$",
+					},
+				]),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a pattern that is not a regular expression", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Text,
+						label: text("Licence key"),
+						pattern: "^cfxk_(",
+					},
+				]),
+			),
+		).toThrow('declares pattern "^cfxk_(", which is not a valid regular expression');
+	});
+
+	test("takes the FiveM licence pattern, whose repeats are all bounded", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Secret,
+						label: text("Licence key"),
+						pattern: "^(?:cfxk_\\w{1,60}_\\w{1,20}|\\w{32})$",
+					},
+				]),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a pattern that repeats a group which already repeats", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Text,
+						label: text("Licence key"),
+						pattern: "^(a+)+$",
+					},
+				]),
+			),
+		).toThrow('declares pattern "^(a+)+$", which repeats a group that already repeats');
+	});
+
+	test("rejects a starred group whose body repeats without a bound", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "SERVER_NAME",
+						control: BridgeControl.Text,
+						label: text("Name"),
+						pattern: "^(\\w+\\s?)*$",
+					},
+				]),
+			),
+		).toThrow("repeats a group that already repeats");
+	});
+
+	test("rejects a pattern longer than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Text,
+						label: text("Licence key"),
+						pattern: `^${"a".repeat(256)}$`,
+					},
+				]),
+			),
+		).toThrow("pattern is 258 characters — the platform takes at most 256");
+	});
+
+	test("rejects a pattern hint with no pattern to explain", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "LICENSE_KEY",
+						control: BridgeControl.Text,
+						label: text("Licence key"),
+						patternHint: text("A licence key starts with cfxk_"),
+					},
+				]),
+			),
+		).toThrow("declares a pattern hint with no pattern to explain");
+	});
+
+	test("rejects a pattern on a control that never matches one", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "WHITELIST",
+						control: BridgeControl.Boolean,
+						label: text("Whitelist"),
+						pattern: "^true$",
+					},
+				]),
+			),
+		).toThrow('declares a pattern on a "boolean" control — only text and secret controls match one');
+	});
+
+	test("rejects a secret control that offers options", () => {
+		expect(() =>
+			validateDriver(
+				driverWithFields([
+					{
+						key: "ADMIN_PASSWORD",
+						control: BridgeControl.Secret,
+						label: text("Admin password"),
+						options: [
+							{
+								value: "letmein",
+								label: text("letmein"),
+							},
+						],
+					},
+				]),
+			),
+		).toThrow("is a secret control with options — a secret is typed, never chosen from a list");
+	});
+});