@serverkgg/bridge 0.0.14 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.14",
+	"version": "0.0.15",
 	"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

@@ -4,8 +4,17 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { BridgeKind, BridgeSetupStepKind } from "../core";
 import { GuideOpenTab } from "../guides";
-import type { BridgeSetupModule } from "../modules";
-import { runValidate, setupReportLines } from "./validate";
+import type { BridgeDriver, BridgeSetupModule } from "../modules";
+import {
+	BridgeControl,
+	type BridgeFormSection,
+	BridgeFormTarget,
+	BridgeLayout,
+	BridgePlace,
+	type BridgeTab,
+	type BridgeTableSection,
+} from "../panel";
+import { placementReportLines, runValidate, setupReportLines } from "./validate";
 
 const text = (value: string) => ({
 	ar: value,
@@ -202,3 +211,186 @@ describe("the setup report", () => {
 		]);
 	});
 });
+
+describe("the placement report", () => {
+	const rosterTable = (place?: BridgePlace): BridgeTableSection => ({
+		layout: BridgeLayout.Table,
+		id: "online",
+		module: "players",
+		place,
+		columns: [
+			{
+				key: "name",
+				label: text("Name"),
+			},
+		],
+	});
+
+	const settingsForm = (): BridgeFormSection => ({
+		layout: BridgeLayout.Form,
+		id: "world",
+		target: BridgeFormTarget.Variables,
+		fields: [
+			{
+				key: "WORLD_NAME",
+				control: BridgeControl.Text,
+				label: text("World name"),
+			},
+		],
+	});
+
+	const driverWithTabs = (tabs: BridgeTab[]): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		panel: {
+			tabs,
+		},
+	});
+
+	test("says nothing about a roster table that declares where it belongs", () => {
+		expect(
+			placementReportLines(
+				driverWithTabs([
+					{
+						id: "roster",
+						title: text("Roster"),
+						sections: [
+							rosterTable(BridgePlace.Players),
+						],
+					},
+				]),
+			),
+		).toEqual([
+			'  placement: tab "roster" is fully placed, it will not appear in the sidebar',
+		]);
+	});
+
+	test("warns that the platform absorbs an unplaced players collection by convention", () => {
+		expect(
+			placementReportLines(
+				driverWithTabs([
+					{
+						id: "roster",
+						title: text("Roster"),
+						sections: [
+							rosterTable(),
+						],
+					},
+				]),
+			),
+		).toEqual([
+			'  warning: tab "roster" section "online" is the players collection with no place — the platform absorbs it by convention today; declare `place: players` to make it explicit',
+		]);
+	});
+
+	test("warns about a tab that takes the name of a platform sidebar entry", () => {
+		expect(
+			placementReportLines(
+				driverWithTabs([
+					{
+						id: "analytics",
+						title: text("Analytics"),
+						sections: [
+							settingsForm(),
+						],
+					},
+				]),
+			),
+		).toEqual([
+			`  warning: tab "analytics" takes the name of a platform sidebar entry — rename it, the platform's own entry owns that noun`,
+		]);
+	});
+
+	test("leaves a players tab alone while it is the roster tab", () => {
+		expect(
+			placementReportLines(
+				driverWithTabs([
+					{
+						id: "players",
+						title: text("Players"),
+						sections: [
+							rosterTable(BridgePlace.Players),
+						],
+					},
+				]),
+			),
+		).toEqual([
+			'  placement: tab "players" is fully placed, it will not appear in the sidebar',
+		]);
+	});
+
+	test("warns about a players tab that holds no roster", () => {
+		expect(
+			placementReportLines(
+				driverWithTabs([
+					{
+						id: "players",
+						title: text("Players"),
+						sections: [
+							settingsForm(),
+						],
+					},
+				]),
+			),
+		).toEqual([
+			`  warning: tab "players" takes the name of a platform sidebar entry — rename it, the platform's own entry owns that noun`,
+		]);
+	});
+
+	test("says nothing about a tab that declares no sections at all", () => {
+		expect(
+			placementReportLines(
+				driverWithTabs([
+					{
+						id: "empty",
+						title: text("Empty"),
+						sections: [],
+					},
+				]),
+			),
+		).toEqual([]);
+	});
+
+	test("still warns about an empty players tab, which holds no roster", () => {
+		expect(
+			placementReportLines(
+				driverWithTabs([
+					{
+						id: "players",
+						title: text("Players"),
+						sections: [],
+					},
+				]),
+			),
+		).toEqual([
+			`  warning: tab "players" takes the name of a platform sidebar entry — rename it, the platform's own entry owns that noun`,
+		]);
+	});
+
+	test("says nothing about a tab that keeps a leftover section", () => {
+		expect(
+			placementReportLines(
+				driverWithTabs([
+					{
+						id: "world",
+						title: text("World"),
+						sections: [
+							rosterTable(BridgePlace.Players),
+							settingsForm(),
+						],
+					},
+				]),
+			),
+		).toEqual([]);
+	});
+});

package/src/cli/validate.ts

@@ -15,7 +15,15 @@ import {
 	readPackageDocument,
 } from "../manifest";
 import type { BridgeDriver, BridgeSetupModule } from "../modules";
-import { type BridgeSetupStep, BridgeSetupStepKind, isBridgeEventName } from "../protocol";
+import {
+	BridgeLayout,
+	BridgePlace,
+	type BridgeSection,
+	type BridgeSetupStep,
+	BridgeSetupStepKind,
+	type BridgeTab,
+	isBridgeEventName,
+} from "../protocol";
 import { validateDriver, validatePortActivation } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
 
@@ -193,6 +201,79 @@ const reportActionTargets = (driver: BridgeDriver) => {
 	}
 };
 
+const PLATFORM_TAB_IDS: ReadonlySet<string> = new Set([
+	"overview",
+	"console",
+	"files",
+	"backups",
+	"schedules",
+	"analytics",
+	"feed",
+	"access",
+	"integrations",
+	"needs",
+	"setup",
+	"change-game",
+]);
+
+const ROSTER_TAB_ID = "players";
+
+const ROSTER_MODULE = "players";
+
+const isCollectionSection = (section: BridgeSection) => {
+	return section.layout === BridgeLayout.Table || section.layout === BridgeLayout.Cards;
+};
+
+const placeOf = (section: BridgeSection) => {
+	return "place" in section ? section.place : undefined;
+};
+
+const isRosterTab = (tab: BridgeTab) => {
+	if (tab.sections.some((section) => isCollectionSection(section) && section.module === ROSTER_MODULE)) {
+		return true;
+	}
+
+	return tab.sections.length > 0 && tab.sections.every((section) => placeOf(section) === BridgePlace.Players);
+};
+
+export const placementReportLines = (driver: BridgeDriver): string[] => {
+	const lines: string[] = [];
+
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			if (!isCollectionSection(section) || section.module !== ROSTER_MODULE) {
+				continue;
+			}
+
+			if (placeOf(section) === BridgePlace.Players) {
+				continue;
+			}
+
+			lines.push(
+				`  warning: tab "${tab.id}" section "${section.id}" is the players collection with no place — the platform absorbs it by convention today; declare \`place: players\` to make it explicit`,
+			);
+		}
+
+		if (PLATFORM_TAB_IDS.has(tab.id) || (tab.id === ROSTER_TAB_ID && !isRosterTab(tab))) {
+			lines.push(
+				`  warning: tab "${tab.id}" takes the name of a platform sidebar entry — rename it, the platform's own entry owns that noun`,
+			);
+		}
+
+		if (tab.sections.length > 0 && tab.sections.every((section) => placeOf(section) !== undefined)) {
+			lines.push(`  placement: tab "${tab.id}" is fully placed, it will not appear in the sidebar`);
+		}
+	}
+
+	return lines;
+};
+
+const reportPlacement = (driver: BridgeDriver) => {
+	for (const line of placementReportLines(driver)) {
+		console.log(line);
+	}
+};
+
 const openTargetOf = (target: GuideOpenTarget) => {
 	if (target.tab === GuideOpenTab.Panel) {
 		return `panel tab "${target.tabId}"`;
@@ -286,6 +367,7 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 
 	reportEvents(driver);
 	reportActionTargets(driver);
+	reportPlacement(driver);
 };
 
 export const runValidate = async (args: string[]) => {

package/src/guides/variables.ts

@@ -12,6 +12,7 @@ export const GUIDE_VARIABLES = {
 	"server.code": GuideVariableFormat.Code,
 	"server.address": GuideVariableFormat.Code,
 	"server.host": GuideVariableFormat.Code,
+	"server.ip": GuideVariableFormat.Code,
 	"server.port": GuideVariableFormat.Code,
 	"server.game": GuideVariableFormat.Text,
 	"server.region": GuideVariableFormat.Text,

package/src/panel/bridgePanel.ts

@@ -5,6 +5,7 @@ import type { BridgeControl } from "./bridgeControl";
 import type { BridgeFormTarget } from "./bridgeFormTarget";
 import type { BridgeIcon } from "./bridgeIcon";
 import type { BridgeLayout } from "./bridgeLayout";
+import type { BridgePlace } from "./bridgePlace";
 import type { BridgeUploadMode } from "./bridgeUploadMode";
 
 export interface BridgeVisibleWhen {
@@ -44,6 +45,7 @@ export interface BridgeSectionAction {
 	confirm?: BridgeConfirm;
 	confirmText?: LocalizedText;
 	download?: boolean;
+	offline?: boolean;
 	fields?: BridgeField[];
 }
 
@@ -74,6 +76,7 @@ export interface BridgeActionsSection {
 	id: string;
 	title?: LocalizedText;
 	help?: LocalizedText;
+	place?: BridgePlace;
 	module: string;
 	actions: BridgeSectionAction[];
 	visibleWhen?: BridgeVisibleWhen;
@@ -84,6 +87,7 @@ export interface BridgeFormSection {
 	layout: BridgeLayout.Form;
 	id: string;
 	title?: LocalizedText;
+	help?: LocalizedText;
 	target: BridgeFormTarget;
 	module?: string;
 	preview?: BridgePreviewRef;
@@ -106,6 +110,8 @@ export interface BridgeTableSection {
 	layout: BridgeLayout.Table;
 	id: string;
 	title?: LocalizedText;
+	help?: LocalizedText;
+	place?: BridgePlace;
 	module: string;
 	restartHint?: boolean;
 	columns: BridgeColumn[];
@@ -121,6 +127,8 @@ export interface BridgeCardsSection {
 	layout: BridgeLayout.Cards;
 	id: string;
 	title?: LocalizedText;
+	help?: LocalizedText;
+	place?: BridgePlace;
 	module: string;
 	titleKey: string;
 	subtitleKey?: string;
@@ -134,6 +142,7 @@ export interface BridgeCatalogSection {
 	layout: BridgeLayout.Catalog;
 	id: string;
 	title?: LocalizedText;
+	help?: LocalizedText;
 	module: string;
 	restartHint?: boolean;
 	reinstall?: boolean;
@@ -149,6 +158,8 @@ export interface BridgeDetailSection {
 	layout: BridgeLayout.Detail;
 	id: string;
 	title?: LocalizedText;
+	help?: LocalizedText;
+	place?: BridgePlace;
 	module: string;
 	actions?: BridgeSectionAction[];
 	reinstall?: boolean;

package/src/panel/bridgePlace.ts

@@ -0,0 +1,4 @@
+export enum BridgePlace {
+	Overview = "overview",
+	Players = "players",
+}

package/src/panel/index.ts

@@ -6,4 +6,5 @@ export * from "./bridgeFormTarget";
 export * from "./bridgeIcon";
 export * from "./bridgeLayout";
 export * from "./bridgePanel";
+export * from "./bridgePlace";
 export * from "./bridgeUploadMode";

package/src/rcon/rconAccess.test.ts

@@ -15,7 +15,7 @@ import {
 
 interface StubOptions {
 	exposed?: boolean;
-	port?: number;
+	port?: number | null;
 }
 
 const stubContext = (options: StubOptions = {}) => {
@@ -25,7 +25,11 @@ const stubContext = (options: StubOptions = {}) => {
 		variable: (key: string) => {
 			return key === RCON_ACCESS_VARIABLE && options.exposed === true ? "true" : null;
 		},
-		port: () => {
+		port: (key: string) => {
+			if (options.port === null) {
+				throw new Error(`this game declares no port named "${key}"`);
+			}
+
 			return options.port ?? 12_500;
 		},
 		log: (message: string) => {
@@ -154,6 +158,20 @@ describe("createRconAccess", () => {
 		]);
 	});
 
+	test("an inactive port leaves the port stat empty instead of failing the read", async () => {
+		const detail = await accessWith({
+			value: "secret",
+			pending: false,
+		}).read(
+			stubContext({
+				port: null,
+			}).context,
+		);
+
+		expect(detail?.stats.find((stat) => stat.key === "port")?.value).toBeNull();
+		expect(detail?.stats.find((stat) => stat.key === "password")?.value).toBe("secret");
+	});
+
 	test("a server with no password yet has no detail", async () => {
 		expect(await accessWith(null).read(stubContext().context)).toBeNull();
 	});

package/src/rcon/rconAccess.ts

@@ -127,6 +127,14 @@ const badgesFor = (exposed: boolean, pending: boolean): BridgeDetailBadge[] => {
 	return badges;
 };
 
+const declaredPort = (context: BridgeContext, key: string): number | null => {
+	try {
+		return context.port(key);
+	} catch {
+		return null;
+	}
+};
+
 export const createRconAccess = (options: RconAccessOptions): BridgeDetailModule => {
 	const protocol = options.protocol ?? DEFAULT_PROTOCOL;
 	const portKey = options.portKey ?? RCON_ACCESS_PORT;
@@ -155,7 +163,7 @@ export const createRconAccess = (options: RconAccessOptions): BridgeDetailModule
 							ar: `منفذ ${protocol.ar}`,
 							en: `${protocol.en} port`,
 						},
-						value: context.port(portKey),
+						value: declaredPort(context, portKey),
 						format: BridgeDetailFormat.Number,
 					},
 					{

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) {