@serverkgg/bridge 0.0.13 → 0.0.15

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.13",
+	"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/context/bridgeContext.ts

@@ -123,11 +123,18 @@ export interface BridgeRconOptions {
 	password: string;
 	timeoutMs?: number;
 	multiPacket?: boolean;
+	mirroredIds?: boolean;
+}
+
+export interface BridgeRconCommandOptions {
+	timeoutMs?: number;
 }
 
 export interface BridgeRconClient {
-	command(text: string): Promise<string>;
-	close(): void;
+	readonly connected: boolean;
+	connect(): Promise<void>;
+	command(text: string, options?: BridgeRconCommandOptions): Promise<string>;
+	disconnect(): Promise<void>;
 }
 
 export interface BridgeRcons {

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/manifest/manifest.ts

@@ -90,7 +90,7 @@ const manifestPortSchema = z.object({
 		}),
 	activeWhen: z.array(manifestPortActivationSchema).max(4).default([]).meta({
 		description:
-			"Conditions on the server's variables that must all hold for the game to listen on this port. The port is still allocated; the panel hides the address otherwise.",
+			"Conditions on the server's variables that must all hold for this port to be published. The host port stays allocated either way; while a condition fails the container does not publish it and the panel hides the address.",
 	}),
 	mirror: z.boolean().default(false).meta({
 		description:

package/src/modules/bridgeModule.ts

@@ -1,4 +1,4 @@
-import type { BridgeContext } from "../context";
+import type { BridgeContext, BridgeReply } from "../context";
 import type { BridgeInstallOutcome, BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
 import type { BridgeDetail, BridgeDetailOutcome } from "../panel";
 import type { BridgeCatalogEntry, BridgeCatalogPage, BridgeCatalogQuery } from "../protocol/bridgeCatalog";
@@ -78,6 +78,7 @@ export interface BridgeTerminalModule {
 	kind: BridgeKind.Terminal;
 	commands: BridgeTerminalCommand[];
 	rules?: BridgeTerminalRule[];
+	run?(context: BridgeContext, input: string): Promise<BridgeReply | null>;
 }
 
 export interface BridgeOptionsModule {

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/index.ts

@@ -1,3 +1,4 @@
 export { BridgeRconCode, BridgeRconError } from "../core";
-export * from "./sourceRcon";
-export * from "./sourceRconFrame";
+export * from "./rconAccess";
+export * from "./rconClient";
+export * from "./rconFrame";