@serverkgg/bridge 0.0.13 → 0.0.15

package/src/runtime/bridgeConsoleHandler.test.ts

@@ -0,0 +1,196 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeCommandOptions, BridgeContext, BridgeReply } from "../context";
+import { BridgeKind, BridgeUserError } from "../core";
+import type { BridgeDriver, BridgeTerminalModule } from "../modules";
+import { createConsoleHandler } from "./bridgeConsoleHandler";
+
+const context = {} as unknown as BridgeContext;
+
+const driverWith = (terminal: BridgeTerminalModule | undefined): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	terminal,
+});
+
+const terminalWith = (run: BridgeTerminalModule["run"]): BridgeTerminalModule => ({
+	kind: BridgeKind.Terminal,
+	commands: [
+		{
+			name: "Save",
+			summary: {
+				ar: "يحفظ العالم.",
+				en: "Save the world.",
+			},
+		},
+	],
+	run,
+});
+
+const handlerFor = (driver: BridgeDriver) => {
+	const written: string[] = [];
+
+	const handler = createConsoleHandler({
+		driver,
+		context,
+		async onStdin(input: string, options: BridgeCommandOptions): Promise<BridgeReply> {
+			written.push(input);
+
+			return {
+				sent: input,
+				line: options.expect ? "matched" : null,
+				groups: {},
+			};
+		},
+	});
+
+	return {
+		handler,
+		written,
+	};
+};
+
+describe("routing a console line to the driver before the game's stdin", () => {
+	test("answers with the driver's reply when the driver handles the line", async () => {
+		const { handler, written } = handlerFor(
+			driverWith(
+				terminalWith(async (_context, input) => {
+					return {
+						sent: input,
+						line: "Save requested",
+						groups: {},
+					};
+				}),
+			),
+		);
+
+		expect(await handler("Save", {})).toEqual({
+			sent: "Save",
+			line: "Save requested",
+			groups: {},
+		});
+		expect(written).toEqual([]);
+	});
+
+	test("hands the driver the same line the caller typed", async () => {
+		const seen: string[] = [];
+
+		const { handler } = handlerFor(
+			driverWith(
+				terminalWith(async (_context, input) => {
+					seen.push(input);
+
+					return {
+						sent: input,
+						line: null,
+						groups: {},
+					};
+				}),
+			),
+		);
+
+		await handler("Broadcast hello world", {});
+
+		expect(seen).toEqual([
+			"Broadcast hello world",
+		]);
+	});
+
+	test("writes the line to stdin when the driver answers null", async () => {
+		const { handler, written } = handlerFor(
+			driverWith(
+				terminalWith(async () => {
+					return null;
+				}),
+			),
+		);
+
+		expect(await handler("save-all", {})).toEqual({
+			sent: "save-all",
+			line: null,
+			groups: {},
+		});
+		expect(written).toEqual([
+			"save-all",
+		]);
+	});
+
+	test("keeps the expect and timeout of a line the driver leaves alone", async () => {
+		const { handler } = handlerFor(
+			driverWith(
+				terminalWith(async () => {
+					return null;
+				}),
+			),
+		);
+
+		expect(
+			(
+				await handler("list", {
+					expect: /players online/,
+					timeoutMs: 1000,
+				})
+			).line,
+		).toBe("matched");
+	});
+
+	test("writes the line to stdin when the driver declares no handler", async () => {
+		const { handler, written } = handlerFor(
+			driverWith({
+				kind: BridgeKind.Terminal,
+				commands: [],
+			}),
+		);
+
+		await handler("list", {});
+
+		expect(written).toEqual([
+			"list",
+		]);
+	});
+
+	test("writes the line to stdin when the game declares no terminal at all", async () => {
+		const { handler, written } = handlerFor(driverWith(undefined));
+
+		await handler("list", {});
+
+		expect(written).toEqual([
+			"list",
+		]);
+	});
+
+	test("refuses the line with the driver's own text when the driver rejects it", async () => {
+		const refusal = {
+			ar: "هذا الأمر يشتغل داخل اللعبة بس.",
+			en: "That command only works inside the game.",
+		};
+
+		const { handler, written } = handlerFor(
+			driverWith(
+				terminalWith(async () => {
+					throw new BridgeUserError(refusal);
+				}),
+			),
+		);
+
+		try {
+			await handler("TeleportToPlayer meslzy", {});
+
+			expect.unreachable();
+		} catch (error) {
+			expect(error).toBeInstanceOf(BridgeUserError);
+			expect((error as BridgeUserError).text).toEqual(refusal);
+		}
+
+		expect(written).toEqual([]);
+	});
+});

package/src/runtime/bridgeConsoleHandler.ts

@@ -0,0 +1,26 @@
+import type { BridgeCommandOptions, BridgeContext, BridgeReply } from "../context";
+import type { BridgeDriver } from "../modules";
+
+export type BridgeConsoleHandler = (input: string, options: BridgeCommandOptions) => Promise<BridgeReply>;
+
+export interface BridgeConsoleOptions {
+	driver: BridgeDriver;
+	context: BridgeContext;
+	onStdin: BridgeConsoleHandler;
+}
+
+export const createConsoleHandler = (options: BridgeConsoleOptions): BridgeConsoleHandler => {
+	return async (input, commandOptions) => {
+		const run = options.driver.terminal?.run;
+
+		if (run) {
+			const reply = await run(options.context, input);
+
+			if (reply) {
+				return reply;
+			}
+		}
+
+		return await options.onStdin(input, commandOptions);
+	};
+};

package/src/runtime/bridgeDriver.test.ts

@@ -9,8 +9,10 @@ import {
 	type BridgeField,
 	BridgeFormTarget,
 	BridgeLayout,
+	BridgePlace,
 	type BridgeSectionAction,
 	type BridgeSectionUpload,
+	type BridgeTableSection,
 	BridgeUploadMode,
 	type BridgeVisibleWhen,
 } from "../panel";
@@ -1636,3 +1638,146 @@ describe("field patterns", () => {
 		).toThrow("is a secret control with options — a secret is typed, never chosen from a list");
 	});
 });
+
+describe("section placement", () => {
+	const anyVisibleWhen: BridgeVisibleWhen = {
+		variable: "MODPACK",
+		empty: true,
+	};
+
+	const driverWithRoster = (section: Partial<BridgeTableSection>): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		modules: {
+			players: {
+				kind: BridgeKind.Collection,
+				list: async () => [],
+				actions: {
+					ban: async () => {
+						return;
+					},
+				},
+			},
+		},
+		panel: {
+			tabs: [
+				{
+					id: "roster",
+					title: text("Roster"),
+					sections: [
+						{
+							layout: BridgeLayout.Table,
+							id: "online",
+							module: "players",
+							columns: [
+								{
+									key: "name",
+									label: text("Name"),
+								},
+							],
+							...section,
+						},
+					],
+				},
+			],
+		},
+	});
+
+	const placedForm = (place: BridgePlace): BridgeDriver => {
+		const driver = driverWith(anyVisibleWhen);
+
+		Object.assign(formSectionOf(driver), {
+			place,
+		});
+
+		return driver;
+	};
+
+	test("accepts a table placed on the players page", () => {
+		expect(() =>
+			validateDriver(
+				driverWithRoster({
+					place: BridgePlace.Players,
+				}),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a form placed on the players page", () => {
+		expect(() => validateDriver(placedForm(BridgePlace.Players))).toThrow(
+			'tab "version" section "version" places a form section on players, which that page cannot render',
+		);
+	});
+
+	test("rejects a form placed on the overview page", () => {
+		expect(() => validateDriver(placedForm(BridgePlace.Overview))).toThrow(
+			"places a form section on overview, which that page cannot render",
+		);
+	});
+
+	test("rejects a table placed on the overview page", () => {
+		expect(() =>
+			validateDriver(
+				driverWithRoster({
+					place: BridgePlace.Overview,
+				}),
+			),
+		).toThrow('tab "roster" section "online" places a table section on overview, which that page cannot render');
+	});
+
+	test("accepts an offline row action on a table", () => {
+		expect(() =>
+			validateDriver(
+				driverWithRoster({
+					place: BridgePlace.Players,
+					actions: [
+						{
+							id: "ban",
+							label: text("Ban"),
+							offline: true,
+						},
+					],
+				}),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects an offline action on an actions section", () => {
+		expect(() =>
+			validateDriver(
+				driverWithActions([
+					{
+						id: "say",
+						label: text("Say"),
+						offline: true,
+					},
+				]),
+			),
+		).toThrow(
+			'tab "gameplay" section "broadcast" action "say" is offline-only, which only a table or cards row action can be',
+		);
+	});
+
+	test("rejects a form help that is missing a locale", () => {
+		const driver = driverWith(anyVisibleWhen);
+
+		formSectionOf(driver).help = {
+			ar: "",
+			en: "The version the server runs",
+		};
+
+		expect(() => validateDriver(driver)).toThrow(
+			'tab "version" section "version" help needs both arabic and english text',
+		);
+	});
+});

package/src/runtime/bridgeDriver.ts

@@ -13,6 +13,7 @@ import {
 	type BridgeField,
 	BridgeFormTarget,
 	BridgeLayout,
+	BridgePlace,
 	type BridgeSection,
 	type BridgeSectionAction,
 	type BridgeTab,
@@ -333,12 +334,53 @@ const validateActions = (modules: Record<string, BridgePanelModule>, actions: Br
 	}
 };
 
+const PLACE_LAYOUTS: Record<BridgePlace, BridgeLayout[]> = {
+	[BridgePlace.Overview]: [
+		BridgeLayout.Actions,
+		BridgeLayout.Detail,
+	],
+	[BridgePlace.Players]: [
+		BridgeLayout.Actions,
+		BridgeLayout.Cards,
+		BridgeLayout.Table,
+	],
+};
+
+const validatePlace = (section: BridgeSection, where: string) => {
+	const place = "place" in section ? section.place : undefined;
+
+	if (place === undefined) {
+		return;
+	}
+
+	if (!(PLACE_LAYOUTS[place] ?? []).includes(section.layout)) {
+		fail(`${where} places a ${section.layout} section on ${place}, which that page cannot render`);
+	}
+};
+
+const validateOffline = (section: BridgeSection, where: string) => {
+	if (section.layout === BridgeLayout.Table || section.layout === BridgeLayout.Cards) {
+		return;
+	}
+
+	const actions = "actions" in section ? (section.actions ?? []) : [];
+
+	for (const action of actions) {
+		if (action.offline !== undefined) {
+			fail(`${where} action "${action.id}" is offline-only, which only a table or cards row action can be`);
+		}
+	}
+};
+
 const validateSection = (modules: Record<string, BridgePanelModule>, section: BridgeSection, where: string) => {
 	validateVisibleWhen(section.visibleWhen, where);
 	validateText(section.title, "title", where);
+	validateText(section.help, "help", where);
+	validatePlace(section, where);
+	validateOffline(section, where);
 
-	if (section.layout !== BridgeLayout.Form) {
-		validateText(section.layout === BridgeLayout.Actions ? section.help : section.empty, "text", where);
+	if (section.layout !== BridgeLayout.Form && section.layout !== BridgeLayout.Actions) {
+		validateText(section.empty, "empty text", where);
 	}
 
 	switch (section.layout) {

package/src/runtime/bridgeRcon.ts

@@ -1,15 +1,19 @@
 import type { BridgeRcons } from "../context";
-import { sourceRcon } from "../rcon";
+import { RconClient } from "../rcon";
 
 const RCON_HOST = "127.0.0.1";
 
 export const createBridgeRcons = (): BridgeRcons => {
 	return {
 		async source(options) {
-			return await sourceRcon({
+			const client = new RconClient({
 				...options,
 				host: RCON_HOST,
 			});
+
+			await client.connect();
+
+			return client;
 		},
 	};
 };

package/src/runtime/bridgeRegistry.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, test } from "bun:test";
 import { tmpdir } from "node:os";
 import { BridgeAction, BridgeKind, type BridgeRow, BridgeSetupStepKind, type BridgeValues } from "../core";
 import type { BridgeDriver } from "../modules";
+import { BridgeLayout } from "../panel";
 import { type BridgeConfig, BridgeConfirm, BridgeEventName } from "../protocol";
 import { createContext } from "./bridgeContext";
 import { createEventRing } from "./bridgeEvents";
@@ -296,6 +297,101 @@ describe("collection row actions", () => {
 	});
 });
 
+describe("offline row actions", () => {
+	const rosterDriver = (
+		offline: boolean,
+		list: () => Promise<BridgeRow[]>,
+		ban: (row: BridgeRow) => void,
+	): BridgeDriver => ({
+		...baseDriver(),
+		panel: {
+			tabs: [
+				{
+					id: "players",
+					title: {
+						ar: "اللاعبين",
+						en: "Players",
+					},
+					sections: [
+						{
+							layout: BridgeLayout.Table,
+							id: "online",
+							module: "players",
+							columns: [
+								{
+									key: "name",
+									label: {
+										ar: "الاسم",
+										en: "Name",
+									},
+								},
+							],
+							actions: [
+								{
+									id: "ban",
+									label: {
+										ar: "حظر",
+										en: "Ban",
+									},
+									offline,
+								},
+							],
+						},
+					],
+				},
+			],
+		},
+		modules: {
+			players: {
+				kind: BridgeKind.Collection,
+				list,
+				actions: {
+					ban: async (_context, row) => {
+						ban(row);
+					},
+				},
+			},
+		},
+	});
+
+	test("hands an offline action the id alone when the row is not listed", async () => {
+		const seen: BridgeRow[] = [];
+		const registry = registryFor(
+			rosterDriver(
+				true,
+				async () => [],
+				(row) => seen.push(row),
+			),
+		);
+
+		await registry.invoke("players", "ban", {
+			id: "steam_1",
+		});
+
+		expect(seen).toEqual([
+			{
+				id: "steam_1",
+			},
+		]);
+	});
+
+	test("still refuses an unlisted row for an action that is not offline", async () => {
+		const registry = registryFor(
+			rosterDriver(
+				false,
+				async () => [],
+				() => undefined,
+			),
+		);
+
+		await expect(
+			registry.invoke("players", "ban", {
+				id: "steam_1",
+			}),
+		).rejects.toThrow('module "players" has no row "steam_1"');
+	});
+});
+
 describe("preview modules", () => {
 	test("lists the preview action in the manifest", () => {
 		const registry = registryFor({

package/src/runtime/bridgeRegistry.ts

@@ -1,6 +1,7 @@
 import type { BridgeContext } from "../context";
 import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues, isReadAction } from "../core";
 import type { BridgeDriver, BridgePanelModule, BridgeSetupModule, BridgeTerminalModule } from "../modules";
+import { BridgeLayout } from "../panel";
 import {
 	BRIDGE_VERSION,
 	type BridgeManifest,
@@ -148,6 +149,29 @@ const asPage = (args: BridgeValues) => {
 	return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : 0;
 };
 
+const offlineActionsOf = (driver: BridgeDriver): Map<string, Set<string>> => {
+	const offline = new Map<string, Set<string>>();
+
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			if (section.layout !== BridgeLayout.Table && section.layout !== BridgeLayout.Cards) {
+				continue;
+			}
+
+			for (const action of section.actions ?? []) {
+				if (action.offline === true) {
+					const actions = offline.get(section.module) ?? new Set<string>();
+
+					actions.add(action.id);
+					offline.set(section.module, actions);
+				}
+			}
+		}
+	}
+
+	return offline;
+};
+
 export const createRegistry = (
 	driver: BridgeDriver,
 	context: BridgeContext,
@@ -157,6 +181,7 @@ export const createRegistry = (
 	const cache = new Map<string, CacheEntry>();
 	const inflight = new Map<string, Promise<unknown>>();
 	const modules = driver.modules ?? {};
+	const offlineActions = offlineActionsOf(driver);
 
 	for (const [id, module] of Object.entries(modules)) {
 		if (module.kind !== BridgeKind.Actions && module.kind !== BridgeKind.Detail) {
@@ -297,7 +322,14 @@ export const createRegistry = (
 				if (rowAction) {
 					const rows = await module.list(context);
 					const id = asString(args, "id");
-					const row = rows.find((entry) => entry.id === id);
+					const listed = rows.find((entry) => entry.id === id);
+					const row =
+						listed
+						?? (offlineActions.get(name)?.has(action)
+							? {
+									id,
+								}
+							: undefined);
 
 					if (!row) {
 						throw new BridgeDriverError(`module "${name}" has no row "${id}"`);

package/src/runtime/serve.ts

@@ -10,6 +10,7 @@ import {
 	type BridgeStatus,
 } from "../protocol";
 import { configPath, readConfig, socketPath, statePath } from "./bridgeConfigReader";
+import { createConsoleHandler } from "./bridgeConsoleHandler";
 import { createContext } from "./bridgeContext";
 import { validateDriver } from "./bridgeDriver";
 import { createEventRing } from "./bridgeEvents";
@@ -111,6 +112,14 @@ export const serve = async (driver: BridgeDriver) => {
 
 	const registry = createRegistry(driver, context, supervisor, ring);
 
+	const runConsole = createConsoleHandler({
+		driver,
+		context,
+		async onStdin(input, commandOptions) {
+			return await supervisor.command(input, commandOptions);
+		},
+	});
+
 	let current = desired;
 
 	const status = (): BridgeStatus => {
@@ -205,7 +214,7 @@ export const serve = async (driver: BridgeDriver) => {
 			await supervisor.stop();
 		},
 		async onCommand(input, expect, timeoutMs) {
-			return await supervisor.command(input, {
+			return await runConsole(input, {
 				expect: expect === undefined ? undefined : new RegExp(expect),
 				timeoutMs,
 			});