@serverkgg/bridge 0.0.9 → 0.0.11

package/src/runtime/bridgeDriver.ts

@@ -1,7 +1,15 @@
-import { BRIDGE_ID_PATTERN, BRIDGE_MODULE_ID_PATTERN, BridgeKind, type LocalizedText } from "../core";
+import {
+	BRIDGE_ID_PATTERN,
+	BRIDGE_MODULE_ID_PATTERN,
+	BridgeKind,
+	BridgeSetupStepKind,
+	type LocalizedText,
+} from "../core";
+import { GuideOpenTab } from "../guides";
 import type { ManifestPort } from "../manifest";
 import type { BridgeDriver, BridgePanelModule } from "../modules";
 import {
+	BridgeControl,
 	type BridgeField,
 	BridgeFormTarget,
 	BridgeLayout,
@@ -25,9 +33,11 @@ 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,
+	BRIDGE_SETUP_STEPS_LIMIT,
 	BRIDGE_STAGING_LENGTH_LIMIT,
 	BRIDGE_TAB_SECTIONS_LIMIT,
 	BRIDGE_TABLE_COLUMNS_LIMIT,
@@ -47,6 +57,7 @@ const RESERVED_MODULE_IDS = new Set([
 	"lifecycle",
 	"pending",
 	"query",
+	"setup",
 ]);
 
 export class BridgeDriverError extends Error {
@@ -112,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;
@@ -140,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);
 
@@ -437,6 +579,81 @@ const validatePending = (driver: BridgeDriver) => {
 	}
 };
 
+const formSectionOf = (driver: BridgeDriver, tabId: string, sectionId: string) => {
+	const tab = (driver.panel?.tabs ?? []).find((entry) => entry.id === tabId);
+	const section = (tab?.sections ?? []).find((entry) => entry.id === sectionId);
+
+	if (!section || section.layout !== BridgeLayout.Form) {
+		return null;
+	}
+
+	return section;
+};
+
+const validateSetup = (driver: BridgeDriver) => {
+	const setup = driver.setup;
+
+	if (!setup) {
+		return;
+	}
+
+	const where = "the setup module";
+
+	if (setup.kind !== BridgeKind.Setup) {
+		fail(`${where} declares kind "${setup.kind}", which is not "${BridgeKind.Setup}"`);
+	}
+
+	if (setup.steps.length === 0) {
+		fail(`${where} declares no steps`);
+	}
+
+	countIn(setup.steps.length, BRIDGE_SETUP_STEPS_LIMIT, "steps", where);
+
+	const ids = new Set<string>();
+
+	for (const step of setup.steps) {
+		if (ids.has(step.id)) {
+			fail(`${where} declares step "${step.id}" more than once`);
+		}
+
+		ids.add(step.id);
+
+		const at = `${where} step "${step.id}"`;
+
+		validateId(step.id, `${where} step`);
+		validateText(step.title, "title", at);
+		validateText(step.help, "help", at);
+
+		if (step.kind === BridgeSetupStepKind.Form) {
+			const section = formSectionOf(driver, step.tab, step.section);
+
+			if (!section) {
+				fail(`${at} names tab "${step.tab}" section "${step.section}", which is not a form section of this panel`);
+
+				continue;
+			}
+
+			for (const key of step.fields ?? []) {
+				if (!section.fields.some((field) => field.key === key)) {
+					fail(`${at} names field "${key}", which section "${step.section}" does not declare`);
+				}
+			}
+		}
+
+		if (step.kind === BridgeSetupStepKind.Open) {
+			const target = step.target;
+
+			if (target.tab === GuideOpenTab.Panel && !(driver.panel?.tabs ?? []).some((tab) => tab.id === target.tabId)) {
+				fail(`${at} opens panel tab "${target.tabId}", which the panel does not declare`);
+			}
+		}
+	}
+
+	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) => {
 	const sections = new Set<string>();
 
@@ -474,6 +691,7 @@ export const validateDriver = (driver: BridgeDriver) => {
 	countIn(emitted.size, BRIDGE_EVENTS_LIMIT, "event names", "the driver");
 
 	validatePending(driver);
+	validateSetup(driver);
 
 	for (const [id, module] of Object.entries(modules)) {
 		validateModuleId(id, "module");

package/src/runtime/bridgeEvents.test.ts

@@ -0,0 +1,96 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { BridgeKind } from "../core";
+import type { BridgeEventsModule } from "../modules";
+import { BridgeEventName } from "../protocol";
+import { createEventRing } from "./bridgeEvents";
+import type { BridgeLeveledLogger } from "./bridgeLog";
+import { createSupervisor } from "./bridgeSupervisor";
+
+const RESET = "\u001B[m";
+
+const PLAYER_JOINED = /^\[World\|(?<world>[^\]]+)\] Player '(?<player>[^']+)' joined world (?<target>\S+)$/;
+
+const silent: BridgeLeveledLogger = Object.assign(() => {}, {
+	warn: () => {},
+	error: () => {},
+});
+
+const events: BridgeEventsModule = {
+	kind: BridgeKind.Events,
+	patterns: [
+		{
+			match: PLAYER_JOINED,
+			emit: BridgeEventName.PlayerJoined,
+		},
+	],
+};
+
+const emittedFor = async (line: string) => {
+	const dir = await mkdtemp(join(tmpdir(), "bridge-events-"));
+	const path = join(dir, "line.txt");
+
+	await Bun.write(path, `${line}\n`);
+
+	const supervisor = createSupervisor({
+		cwd: dir,
+		uid: process.getuid?.() ?? 0,
+		gid: process.getgid?.() ?? 0,
+		stopTimeoutSeconds: 1,
+		onLog: silent,
+		resolveCommand: async () => [
+			"bash",
+			"-c",
+			'cat "$0"; sleep 300',
+			path,
+		],
+	});
+
+	const ring = createEventRing(events, supervisor);
+
+	await supervisor.start();
+
+	try {
+		for (let waited = 0; waited < 5000; waited += 50) {
+			if (ring.drain(0).events.length > 0) {
+				break;
+			}
+
+			await Bun.sleep(50);
+		}
+
+		return ring.drain(0).events;
+	} finally {
+		await supervisor.stop();
+		await rm(dir, {
+			force: true,
+			recursive: true,
+		});
+	}
+};
+
+const joined = {
+	seq: 1,
+	event: BridgeEventName.PlayerJoined,
+	payload: {
+		world: "default",
+		player: "Meslzy",
+		target: "default",
+	},
+};
+
+describe("matching a game line against the driver patterns", () => {
+	test("emits on the plain line", async () => {
+		expect(await emittedFor("[World|default] Player 'Meslzy' joined world default")).toEqual([
+			joined,
+		]);
+	});
+
+	test("emits on the line hytale really prints, wrapped in ansi resets at both ends", async () => {
+		expect(await emittedFor(`${RESET}[World|default] Player 'Meslzy' joined world default${RESET}`)).toEqual([
+			joined,
+		]);
+	});
+});

package/src/runtime/bridgeEvents.ts

@@ -1,6 +1,7 @@
 import type { BridgeValues } from "../core";
 import type { BridgeEventsModule } from "../modules";
 import type { BridgeEvent } from "../protocol";
+import { stripAnsi } from "../utils";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
 
 const EVENT_BUFFER = 500;
@@ -26,12 +27,14 @@ export const createEventRing = (events: BridgeEventsModule | undefined, supervis
 
 	if (events) {
 		supervisor.subscribe((entry) => {
+			const line = stripAnsi(entry.line);
+
 			for (const pattern of events.patterns) {
 				if (pattern.stream && pattern.stream !== entry.stream) {
 					continue;
 				}
 
-				const match = entry.line.match(pattern.match);
+				const match = line.match(pattern.match);
 
 				if (!match) {
 					continue;

package/src/runtime/bridgeRegistry.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { tmpdir } from "node:os";
-import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues } from "../core";
+import { BridgeAction, BridgeKind, type BridgeRow, BridgeSetupStepKind, type BridgeValues } from "../core";
 import type { BridgeDriver } from "../modules";
 import { type BridgeConfig, BridgeConfirm, BridgeEventName } from "../protocol";
 import { createContext } from "./bridgeContext";
@@ -62,6 +62,9 @@ const registryFor = (driver: BridgeDriver, variables: Record<string, string> = {
 		onEmit(event, payload) {
 			ring.emit(event, payload);
 		},
+		onSetup() {
+			return;
+		},
 	});
 
 	return createRegistry(driver, context, supervisor, ring);
@@ -560,3 +563,37 @@ describe("detail modules", () => {
 		);
 	});
 });
+
+describe("the setup singleton", () => {
+	test("rides the manifest as its own block and never joins the panel modules", () => {
+		const steps = [
+			{
+				kind: BridgeSetupStepKind.Driver as const,
+				id: "sign-in",
+				title: {
+					ar: "تسجيل الدخول",
+					en: "Sign in",
+				},
+			},
+		];
+
+		const registry = registryFor({
+			...baseDriver(),
+			setup: {
+				kind: BridgeKind.Setup,
+				steps,
+			},
+		});
+
+		const manifest = registry.manifest();
+
+		expect(manifest.setup).toEqual({
+			steps,
+		});
+		expect(manifest.modules.some((module) => module.kind === BridgeKind.Setup)).toBe(false);
+	});
+
+	test("leaves the manifest block empty for a driver that declares no setup", () => {
+		expect(registryFor(baseDriver()).manifest().setup).toBeNull();
+	});
+});

package/src/runtime/bridgeRegistry.ts

@@ -1,10 +1,11 @@
 import type { BridgeContext } from "../context";
 import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues, isReadAction } from "../core";
-import type { BridgeDriver, BridgePanelModule, BridgeTerminalModule } from "../modules";
+import type { BridgeDriver, BridgePanelModule, BridgeSetupModule, BridgeTerminalModule } from "../modules";
 import {
 	BRIDGE_VERSION,
 	type BridgeManifest,
 	type BridgeModuleManifest,
+	type BridgeSetupManifest,
 	type BridgeTerminalManifest,
 } from "../protocol";
 import { actionsOf } from "./bridgeActions";
@@ -63,6 +64,16 @@ const terminalManifestOf = (module: BridgeTerminalModule | undefined): BridgeTer
 	};
 };
 
+const setupManifestOf = (module: BridgeSetupModule | undefined): BridgeSetupManifest | null => {
+	if (!module) {
+		return null;
+	}
+
+	return {
+		steps: module.steps,
+	};
+};
+
 const withVariables = (context: BridgeContext, overlay: Record<string, string>): BridgeContext => {
 	return {
 		get server() {
@@ -88,6 +99,7 @@ const withVariables = (context: BridgeContext, overlay: Record<string, string>):
 			return context.exec(command, options);
 		},
 		logs: context.logs,
+		setup: context.setup,
 		emit(event, payload) {
 			context.emit(event, payload);
 		},
@@ -368,6 +380,7 @@ export const createRegistry = (
 				version: BRIDGE_VERSION,
 				panel: driver.panel ?? null,
 				terminal: terminalManifestOf(driver.terminal),
+				setup: setupManifestOf(driver.setup),
 				modules: entries,
 				events: ring.names(),
 			};

package/src/runtime/bridgeSecrets.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BridgeConfig } from "../protocol";
+import { createBridgeSecrets } from "./bridgeSecrets";
+
+const configWith = (secrets: Record<string, string>): BridgeConfig => ({
+	code: "wsvv8fakxm",
+	token: "token",
+	cwd: "/data",
+	run: "/run/bridge",
+	ports: {
+		game: 25_565,
+	},
+	memoryMb: 2048,
+	cpuPercent: 100,
+	gameUid: 1000,
+	gameGid: 1000,
+	variables: {
+		VERSION: "1.21",
+	},
+	secrets,
+});
+
+let directory: string;
+
+let path: string;
+
+const write = async (config: BridgeConfig) => {
+	await writeFile(path, `${JSON.stringify(config, null, 2)}\n`);
+};
+
+beforeEach(async () => {
+	directory = await mkdtemp(join(tmpdir(), "bridge-secrets-"));
+	path = join(directory, "config.json");
+});
+
+afterEach(async () => {
+	await rm(directory, {
+		force: true,
+		recursive: true,
+	});
+});
+
+describe("the bridge secrets reader", () => {
+	test("answers from the boot snapshot", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+		expect(secrets.read("MODRINTH_API_KEY")).toBeNull();
+	});
+
+	test("sees a value the agent rewrote into the config", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await write(
+			configWith({
+				CURSEFORGE_API_KEY: "rotated",
+				MODRINTH_API_KEY: "added",
+			}),
+		);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("rotated");
+		expect(secrets.read("MODRINTH_API_KEY")).toBe("added");
+	});
+
+	test("keeps the last good values while the config is mid-write", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await writeFile(path, '{"code": "wsvv8fak');
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await rm(path);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+	});
+
+	test("re-reads the file at most once per refresh window", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 60_000);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await write(
+			configWith({
+				CURSEFORGE_API_KEY: "rotated",
+			}),
+		);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+	});
+});

package/src/runtime/bridgeSecrets.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import type { BridgeConfig } from "../protocol";
+import { parseConfig } from "./bridgeConfigReader";
+
+export const BRIDGE_SECRET_REFRESH_MS = 2000;
+
+export interface BridgeSecrets {
+	read: (key: string) => string | null;
+}
+
+export const createBridgeSecrets = (
+	path: string,
+	config: BridgeConfig,
+	refreshMs: number = BRIDGE_SECRET_REFRESH_MS,
+): BridgeSecrets => {
+	let values = config.secrets;
+
+	let checkedAt: number | null = null;
+
+	const refresh = () => {
+		const stamp = performance.now();
+
+		if (checkedAt !== null && stamp - checkedAt < refreshMs) {
+			return;
+		}
+
+		checkedAt = stamp;
+
+		try {
+			values = parseConfig(readFileSync(path, "utf8")).secrets;
+		} catch {
+			return;
+		}
+	};
+
+	return {
+		read(key) {
+			refresh();
+
+			return values[key] ?? null;
+		},
+	};
+};