@serverkgg/bridge 0.0.10 → 0.0.11

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.10",
+	"version": "0.0.11",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",

package/src/cli/validate.test.ts

@@ -2,7 +2,15 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { runValidate } from "./validate";
+import { BridgeKind, BridgeSetupStepKind } from "../core";
+import { GuideOpenTab } from "../guides";
+import type { BridgeSetupModule } from "../modules";
+import { runValidate, setupReportLines } from "./validate";
+
+const text = (value: string) => ({
+	ar: value,
+	en: value,
+});
 
 describe("validate", () => {
 	let root = "";
@@ -87,3 +95,110 @@ describe("validate", () => {
 		await expect(validate()).rejects.toThrow("missing serverk.yml");
 	});
 });
+
+describe("the setup report", () => {
+	test("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", () => {
+		const setup: BridgeSetupModule = {
+			kind: BridgeKind.Setup,
+			steps: [
+				{
+					kind: BridgeSetupStepKind.Form,
+					id: "license",
+					title: text("Licence"),
+					required: true,
+					tab: "license",
+					section: "license",
+					fields: [
+						"LICENSE_KEY",
+					],
+				},
+				{
+					kind: BridgeSetupStepKind.Driver,
+					id: "verify",
+					title: text("Verify"),
+					required: true,
+					requiresRunning: true,
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "txadmin",
+					title: text("txAdmin"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Panel,
+						tabId: "license",
+					},
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "invite",
+					title: text("Invite"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Access,
+					},
+				},
+			],
+			submit: async () => {
+				return;
+			},
+		};
+
+		expect(setupReportLines(setup)).toEqual([
+			"  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"',
+			"    invite — open, optional → access",
+		]);
+	});
+
+	test("leaves a driver step that needs nothing running with no target", () => {
+		expect(
+			setupReportLines({
+				kind: BridgeKind.Setup,
+				steps: [
+					{
+						kind: BridgeSetupStepKind.Driver,
+						id: "sign-in",
+						title: text("Sign in"),
+						required: false,
+					},
+				],
+				submit: async () => {
+					return;
+				},
+			}),
+		).toEqual([
+			"  setup: 1 step(s)",
+			"    sign-in — driver, optional → driver",
+		]);
+	});
+
+	test("reads an omitted required as required, the way the platform does", () => {
+		expect(
+			setupReportLines({
+				kind: BridgeKind.Setup,
+				steps: [
+					{
+						kind: BridgeSetupStepKind.Driver,
+						id: "sign-in",
+						title: text("Sign in"),
+					},
+				],
+				submit: async () => {
+					return;
+				},
+			}),
+		).toEqual([
+			"  setup: 1 step(s)",
+			"    sign-in — driver, required → driver",
+		]);
+	});
+});

package/src/cli/validate.ts

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { z } from "zod";
-import { type GuidePack, readGuidePack, readGuidePackage } from "../guides";
+import { GuideOpenTab, type GuideOpenTarget, type GuidePack, readGuidePack, readGuidePackage } from "../guides";
 import {
 	declaredFiles,
 	type GuidePackage,
@@ -13,8 +13,8 @@ import {
 	readAssets,
 	readPackageDocument,
 } from "../manifest";
-import type { BridgeDriver } from "../modules";
-import { isBridgeEventName } from "../protocol";
+import type { BridgeDriver, BridgeSetupModule } from "../modules";
+import { type BridgeSetupStep, BridgeSetupStepKind, isBridgeEventName } from "../protocol";
 import { validateDriver, validatePortActivation } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
 
@@ -186,6 +186,49 @@ const reportActionTargets = (driver: BridgeDriver) => {
 	}
 };
 
+const openTargetOf = (target: GuideOpenTarget) => {
+	if (target.tab === GuideOpenTab.Panel) {
+		return `panel tab "${target.tabId}"`;
+	}
+
+	if (target.tab === GuideOpenTab.Files) {
+		return target.path ? `files at "${target.path}"` : "files";
+	}
+
+	return target.tab;
+};
+
+const setupTargetOf = (step: BridgeSetupStep) => {
+	if (step.kind === BridgeSetupStepKind.Form) {
+		const fields = step.fields ?? [];
+
+		return `→ ${step.tab}/${step.section}${fields.length === 0 ? "" : ` [${fields.join(", ")}]`}`;
+	}
+
+	if (step.kind === BridgeSetupStepKind.Open) {
+		return `→ ${openTargetOf(step.target)}`;
+	}
+
+	return step.requiresRunning ? "→ driver (needs the game running)" : "→ driver";
+};
+
+export const setupReportLines = (setup: BridgeSetupModule | undefined): string[] => {
+	if (!setup) {
+		return [
+			"  setup: none",
+		];
+	}
+
+	return [
+		`  setup: ${setup.steps.length} step(s)`,
+		...setup.steps.map((step) => {
+			const target = setupTargetOf(step);
+
+			return `    ${step.id} — ${step.kind}, ${step.required === false ? "optional" : "required"}${target === "" ? "" : ` ${target}`}`;
+		}),
+	];
+};
+
 const validateGamePackage = async (source: PackageSource, manifest: Manifest, dir: string, driverArg?: string) => {
 	const assets = readAssets(source, manifest);
 	const guideFiles = manifest.guides.flatMap((guide) => [
@@ -230,7 +273,10 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 		`  driver: ${Object.keys(driver.modules ?? {}).length} panel module(s), ${driver.panel?.tabs.length ?? 0} tab(s)`,
 	);
 	console.log(`  pending: ${driver.pending ? `declared (${driver.pending.extensions.length} extension(s))` : "none"}`);
-	console.log(`  setup: ${driver.setup ? `${driver.setup.steps.length} step(s)` : "none"}`);
+	for (const line of setupReportLines(driver.setup)) {
+		console.log(line);
+	}
+
 	reportEvents(driver);
 	reportActionTargets(driver);
 };

package/src/manifest/guide.ts

@@ -16,6 +16,7 @@ export enum GuideSurface {
 	Files = "files",
 	Backups = "backups",
 	Panel = "panel",
+	Setup = "setup",
 }
 
 export const guideTagSchema = z.object({

package/src/panel/bridgeControl.ts

@@ -1,6 +1,7 @@
 export enum BridgeControl {
 	Boolean = "boolean",
 	Number = "number",
+	Secret = "secret",
 	Select = "select",
 	Slider = "slider",
 	Text = "text",

package/src/panel/bridgeDetail.ts

@@ -11,6 +11,7 @@ export enum BridgeDetailFormat {
 	Bytes = "bytes",
 	Date = "date",
 	Number = "number",
+	Secret = "secret",
 	Text = "text",
 }
 

package/src/panel/bridgePanel.ts

@@ -32,6 +32,8 @@ export interface BridgeField {
 	max?: number;
 	step?: number;
 	maxLength?: number;
+	pattern?: string;
+	patternHint?: LocalizedText;
 	options?: BridgeOption[] | BridgeOptionsRef;
 	visibleWhen?: BridgeVisibleWhen;
 }

package/src/protocol/bridgeLimits.ts

@@ -40,6 +40,8 @@ export const BRIDGE_PENDING_FILES_LIMIT = 64;
 
 export const BRIDGE_SETUP_STEPS_LIMIT = 8;
 
+export const BRIDGE_SETUP_ACTIONS_LIMIT = 4;
+
 export const BRIDGE_ID_LENGTH_LIMIT = 32;
 
 export const BRIDGE_KEY_LENGTH_LIMIT = 64;
@@ -53,3 +55,9 @@ export const BRIDGE_PLACEHOLDER_LENGTH_LIMIT = 256;
 export const BRIDGE_STAGING_LENGTH_LIMIT = 128;
 
 export const BRIDGE_EXTENSION_LENGTH_LIMIT = 16;
+
+export const BRIDGE_PATTERN_LENGTH_LIMIT = 256;
+
+export const BRIDGE_SETUP_CODE_LENGTH_LIMIT = 64;
+
+export const BRIDGE_SETUP_DETAIL_LENGTH_LIMIT = 256;

package/src/runtime/bridgeDriver.test.ts

@@ -1155,6 +1155,11 @@ const driverWithSetup = (setup: BridgeSetupModule): BridgeDriver => ({
 						fields: [
 							field("SERVER_NAME"),
 							field("MOTD"),
+							{
+								key: "ADMIN_PASSWORD",
+								control: BridgeControl.Secret,
+								label: text("Admin password"),
+							},
 						],
 					},
 				],
@@ -1172,6 +1177,40 @@ const driverStep = (id: string) => ({
 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", () => {
@@ -1370,6 +1409,58 @@ describe("the setup singleton", () => {
 		).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({
@@ -1395,3 +1486,152 @@ describe("the setup singleton", () => {
 		).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");
+	});
+});

package/src/runtime/bridgeDriver.ts

@@ -9,6 +9,7 @@ import { GuideOpenTab } from "../guides";
 import type { ManifestPort } from "../manifest";
 import type { BridgeDriver, BridgePanelModule } from "../modules";
 import {
+	BridgeControl,
 	type BridgeField,
 	BridgeFormTarget,
 	BridgeLayout,
@@ -32,6 +33,7 @@ import {
 	BRIDGE_MODULES_LIMIT,
 	BRIDGE_OPTION_VALUE_LENGTH_LIMIT,
 	BRIDGE_PANEL_TABS_LIMIT,
+	BRIDGE_PATTERN_LENGTH_LIMIT,
 	BRIDGE_PLACEHOLDER_LENGTH_LIMIT,
 	BRIDGE_ROW_ACTIONS_LIMIT,
 	BRIDGE_SECTION_ACTIONS_LIMIT,
@@ -121,6 +123,110 @@ const moduleOf = (modules: Record<string, BridgePanelModule>, id: string, where:
 	return module as BridgePanelModule;
 };
 
+const compilePattern = (pattern: string): RegExp | null => {
+	try {
+		return new RegExp(pattern);
+	} catch {
+		return null;
+	}
+};
+
+const OPEN_ENDED_REPEAT = /^\{\d+,\}/;
+
+const repeatsWithoutBound = (source: string): boolean => {
+	let index = 0;
+	let inClass = false;
+
+	while (index < source.length) {
+		const char = source[index];
+
+		if (char === "\\") {
+			index += 2;
+
+			continue;
+		}
+
+		if (inClass) {
+			inClass = char !== "]";
+			index += 1;
+
+			continue;
+		}
+
+		if (char === "[") {
+			inClass = true;
+			index += 1;
+
+			continue;
+		}
+
+		if (char === "*" || char === "+" || (char === "{" && OPEN_ENDED_REPEAT.test(source.slice(index)))) {
+			return true;
+		}
+
+		index += 1;
+	}
+
+	return false;
+};
+
+const nestsQuantifiers = (pattern: string): boolean => {
+	const opened: number[] = [];
+
+	let index = 0;
+	let inClass = false;
+
+	while (index < pattern.length) {
+		const char = pattern[index];
+
+		if (char === "\\") {
+			index += 2;
+
+			continue;
+		}
+
+		if (inClass) {
+			inClass = char !== "]";
+			index += 1;
+
+			continue;
+		}
+
+		if (char === "[") {
+			inClass = true;
+			index += 1;
+
+			continue;
+		}
+
+		if (char === "(") {
+			opened.push(index);
+			index += 1;
+
+			continue;
+		}
+
+		if (char === ")") {
+			const start = opened.pop();
+
+			index += 1;
+
+			const quantified =
+				pattern[index] === "*" || pattern[index] === "+" || OPEN_ENDED_REPEAT.test(pattern.slice(index));
+
+			if (start !== undefined && quantified && repeatsWithoutBound(pattern.slice(start + 1, index - 1))) {
+				return true;
+			}
+
+			continue;
+		}
+
+		index += 1;
+	}
+
+	return false;
+};
+
 const validateVisibleWhen = (visibleWhen: BridgeVisibleWhen | undefined, where: string) => {
 	if (!visibleWhen) {
 		return;
@@ -149,12 +255,39 @@ const validateFields = (modules: Record<string, BridgePanelModule>, fields: Brid
 		validateText(field.label, "label", at);
 		validateText(field.help, "help", at);
 		validateText(field.warning, "warning", at);
+		validateText(field.patternHint, "pattern hint", at);
 		validateVisibleWhen(field.visibleWhen, at);
 
 		if (field.placeholder) {
 			lengthIn(field.placeholder, BRIDGE_PLACEHOLDER_LENGTH_LIMIT, "placeholder", at);
 		}
 
+		if (field.pattern !== undefined) {
+			if (field.control !== BridgeControl.Text && field.control !== BridgeControl.Secret) {
+				fail(`${at} declares a pattern on a "${field.control}" control — only text and secret controls match one`);
+			}
+
+			lengthIn(field.pattern, BRIDGE_PATTERN_LENGTH_LIMIT, "pattern", at);
+
+			if (!compilePattern(field.pattern)) {
+				fail(`${at} declares pattern "${field.pattern}", which is not a valid regular expression`);
+			}
+
+			if (nestsQuantifiers(field.pattern)) {
+				fail(
+					`${at} declares pattern "${field.pattern}", which repeats a group that already repeats — a value can make it run for minutes`,
+				);
+			}
+		}
+
+		if (field.patternHint && field.pattern === undefined) {
+			fail(`${at} declares a pattern hint with no pattern to explain`);
+		}
+
+		if (field.control === BridgeControl.Secret && field.options) {
+			fail(`${at} is a secret control with options — a secret is typed, never chosen from a list`);
+		}
+
 		if (Array.isArray(field.options)) {
 			countIn(field.options.length, BRIDGE_FIELD_OPTIONS_LIMIT, "options", at);
 
@@ -515,6 +648,10 @@ const validateSetup = (driver: BridgeDriver) => {
 			}
 		}
 	}
+
+	if (!setup.submit && setup.steps.some((step) => step.kind === BridgeSetupStepKind.Driver)) {
+		fail(`${where} declares a driver step but exports no submit — a driver step is answered through submit`);
+	}
 };
 
 const validateTab = (modules: Record<string, BridgePanelModule>, tab: BridgeTab) => {