@serverkgg/bridge 0.1.3 → 0.1.4

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.1.3",
+	"version": "0.1.4",
 	"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/rules/package.md

@@ -37,6 +37,11 @@ One Serverk package (a game or a bot runtime) on `@serverkgg/bridge`, with no pi
 - A settings form targets `BridgeFormTarget.Settings` and module `settings`, with a one-sentence `help` and `restartHint: true`.
 - In a game, the roster and moderation tables go on `place: BridgePlace.Players`, metrics on `BridgePlace.Overview`.
 - A setup `Form` step points at an existing panel form by `tab`, `section` and field keys, never redeclaring a field; `Form` and `Open` steps state `required`. A game's setup ends with the `Open` step `invite` targeting `GuideOpenTab.Access`.
+- A preview module that knows the change cannot install answers `blocked: true`, with the reason in `lines`. The panel then shows the lines with a close button only, and the platform refuses the change before it rebuilds anything.
+- `BridgeConfirm.None` runs on the click: reads, downloads, start, stop and restart.
+- `BridgeConfirm.Normal` asks once, for anything the player can come back from: a settings form, a variable flip, a reinstall, a version or type switch, a modpack or mod install, op and deop, kick, ban, whitelist, rotating a password.
+- `BridgeConfirm.Strong` is only for an action with no way back, where no restore point is taken and nothing in the panel brings the state back: deleting a world, save, map or character data, resetting a dimension, a wipe. A protected action takes no restore point.
+- A `Form` or `Catalog` section, a `Preview` answer and any section with `reinstall` are never `Strong`, because the platform takes a restore point first; `serverk-bridge validate` fails on such a section. The web shows `Strong` as a checkbox acknowledgement.
 - Emit event names from `BridgeEventName`, never strings, and list every event raised from code in `emits` (`patterns: []` when none match the log). A bot matches deployments with `DEPLOYMENT_EVENT_PATTERN`.
 - `install.run` runs on every boot: keep it idempotent with `readStamp` and `writeStamp` (`@serverkgg/bridge/install`), the stamp in `files.protected`. A game protects the default `.serverk-install.json`; a bot writes `.serverk/install.json` (`INSTALL_STAMP`, `shared/botRuntime.ts`) and protects `.serverk/**`.
 

package/src/cli/validate.test.ts

@@ -8,7 +8,10 @@ import { GuideOpenTab } from "../guides";
 import { MANIFEST_SCHEMA_VERSION, PackageKind } from "../manifest";
 import type { BridgeDriver, BridgeSetupModule } from "../modules";
 import {
+	type BridgeCatalogSection,
+	BridgeConfirm,
 	BridgeControl,
+	type BridgeDetailSection,
 	type BridgeFormSection,
 	BridgeFormTarget,
 	BridgeLayout,
@@ -17,7 +20,13 @@ import {
 	type BridgeTableSection,
 } from "../panel";
 import { RULES_FILE, readShippedRules, writeRules } from "./rules";
-import { availabilityReportLines, placementReportLines, runValidate, setupReportLines } from "./validate";
+import {
+	availabilityReportLines,
+	confirmReportLines,
+	placementReportLines,
+	runValidate,
+	setupReportLines,
+} from "./validate";
 
 const text = (value: string) => ({
 	ar: value,
@@ -696,3 +705,120 @@ describe("availability report", () => {
 		).toEqual([]);
 	});
 });
+
+describe("the confirm report", () => {
+	const driverWithSections = (sections: BridgeTab["sections"]): BridgeDriver => ({
+		install: {
+			kind: BridgeKind.Install,
+			run: async () => {
+				return;
+			},
+		},
+		lifecycle: {
+			kind: BridgeKind.Lifecycle,
+			command: async () => [
+				"run",
+			],
+		},
+		panel: {
+			tabs: [
+				{
+					id: "settings",
+					title: text("Settings"),
+					sections,
+				},
+			],
+		},
+	});
+
+	const versionForm = (confirm?: BridgeConfirm): BridgeFormSection => ({
+		layout: BridgeLayout.Form,
+		id: "version",
+		target: BridgeFormTarget.Variables,
+		reinstall: true,
+		confirm,
+		fields: [
+			{
+				key: "VERSION",
+				control: BridgeControl.Text,
+				label: text("Version"),
+			},
+		],
+	});
+
+	const modpacks = (confirm?: BridgeConfirm): BridgeCatalogSection => ({
+		layout: BridgeLayout.Catalog,
+		id: "modpacks",
+		module: "modpacks",
+		confirm,
+	});
+
+	const modpack = (confirm?: BridgeConfirm, reinstall?: boolean): BridgeDetailSection => ({
+		layout: BridgeLayout.Detail,
+		id: "modpack",
+		module: "modpack",
+		variable: "MODPACK",
+		reinstall,
+		confirm,
+	});
+
+	const worlds = (): BridgeTableSection => ({
+		layout: BridgeLayout.Table,
+		id: "worlds",
+		module: "worlds",
+		columns: [
+			{
+				key: "name",
+				label: text("Name"),
+			},
+		],
+		actions: [
+			{
+				id: "delete",
+				label: text("Delete"),
+				confirm: BridgeConfirm.Strong,
+			},
+		],
+	});
+
+	it("fails a form or a catalog that asks for a strong confirmation", () => {
+		expect(
+			confirmReportLines(
+				driverWithSections([
+					versionForm(BridgeConfirm.Strong),
+					modpacks(BridgeConfirm.Strong),
+				]),
+			),
+		).toEqual([
+			'  error: tab "settings" section "version" is a form with `confirm: strong` — the platform takes a restore point before applying it, so declare `normal`; `strong` is only for what nothing brings back',
+			'  error: tab "settings" section "modpacks" is a catalog with `confirm: strong` — the platform takes a restore point before applying it, so declare `normal`; `strong` is only for what nothing brings back',
+		]);
+	});
+
+	it("fails any section that reinstalls behind a strong confirmation", () => {
+		expect(
+			confirmReportLines(
+				driverWithSections([
+					modpack(BridgeConfirm.Strong, true),
+				]),
+			),
+		).toEqual([
+			'  error: tab "settings" section "modpack" reinstalls with `confirm: strong` — the platform takes a restore point before every reinstall, so declare `normal`; `strong` is only for what nothing brings back',
+		]);
+	});
+
+	it("leaves a strong action that deletes data and every normal confirmation alone", () => {
+		expect(
+			confirmReportLines(
+				driverWithSections([
+					versionForm(BridgeConfirm.Normal),
+					versionForm(),
+					modpacks(BridgeConfirm.Normal),
+					modpack(BridgeConfirm.Normal, true),
+					modpack(BridgeConfirm.Strong),
+					worlds(),
+				]),
+			),
+		).toEqual([]);
+	});
+});

package/src/cli/validate.ts

@@ -21,6 +21,7 @@ import {
 } from "../manifest";
 import type { BridgeDriver, BridgeSetupModule } from "../modules";
 import {
+	BridgeConfirm,
 	BridgeLayout,
 	BridgePlace,
 	type BridgeSection,
@@ -313,6 +314,39 @@ const reportAvailability = (driver: BridgeDriver) => {
 	}
 };
 
+const RESTORE_POINT_LAYOUTS: ReadonlySet<BridgeLayout> = new Set([
+	BridgeLayout.Form,
+	BridgeLayout.Catalog,
+]);
+
+export const confirmReportLines = (driver: BridgeDriver): string[] => {
+	const lines: string[] = [];
+
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			if (!("confirm" in section) || section.confirm !== BridgeConfirm.Strong) {
+				continue;
+			}
+
+			if (RESTORE_POINT_LAYOUTS.has(section.layout)) {
+				lines.push(
+					`  error: tab "${tab.id}" section "${section.id}" is a ${section.layout} with \`confirm: strong\` — the platform takes a restore point before applying it, so declare \`normal\`; \`strong\` is only for what nothing brings back`,
+				);
+
+				continue;
+			}
+
+			if ("reinstall" in section && section.reinstall === true) {
+				lines.push(
+					`  error: tab "${tab.id}" section "${section.id}" reinstalls with \`confirm: strong\` — the platform takes a restore point before every reinstall, so declare \`normal\`; \`strong\` is only for what nothing brings back`,
+				);
+			}
+		}
+	}
+
+	return lines;
+};
+
 const openTargetOf = (target: GuideOpenTarget) => {
 	if (target.tab === GuideOpenTab.Panel) {
 		return `panel tab "${target.tabId}"`;
@@ -434,6 +468,14 @@ const validateRunnablePackage = async (
 	validateDriver(driver);
 	validatePortActivation(manifest.container.ports, driver);
 
+	const confirmLines = confirmReportLines(driver);
+
+	if (confirmLines.length > 0) {
+		throw new Error(
+			`the panel asks for a strong confirmation where a restore point is taken:\n${confirmLines.join("\n")}`,
+		);
+	}
+
 	const conditionalPorts = manifest.container.ports.filter((port) => port.activeWhen.length > 0).length;
 	const pairedPorts = manifest.container.ports.filter((port) => port.protocol === PortProtocol.TcpUdp).length;
 	const blockPorts = manifest.container.ports.filter((port) => port.count > 1).length;

package/src/protocol/bridgePreview.ts

@@ -5,4 +5,5 @@ export interface BridgePreview {
 	variables?: Record<string, string>;
 	confirm: BridgeConfirm;
 	lines: LocalizedText[];
+	blocked?: boolean;
 }

package/src/rcon/rconAccess.ts

@@ -249,7 +249,7 @@ export const rconAccessSections = (options: RconAccessSectionsOptions = {}): Bri
 						ar: "غيّر كلمة المرور",
 						en: "Rotate the password",
 					},
-					confirm: BridgeConfirm.Strong,
+					confirm: BridgeConfirm.Normal,
 					confirmText: {
 						ar: "ستتوقف كل أداة خارجية تستخدمها حتى تضيف إليها كلمة المرور الجديدة.",
 						en: "Every external tool you use stops working until you paste the new password into it.",

package/src/runtime/bridgeRegistry.test.ts

@@ -550,6 +550,38 @@ describe("preview modules", () => {
 		});
 	});
 
+	it("passes a blocked preview through untouched", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				transition: {
+					kind: BridgeKind.Preview,
+					preview: async () => ({
+						confirm: BridgeConfirm.Strong,
+						blocked: true,
+						lines: [
+							{
+								ar: "لا يوجد بيلد مستقر لهذا الإصدار بعد",
+								en: "There is no stable build for this version yet",
+							},
+						],
+					}),
+				},
+			},
+		});
+
+		expect((await registry.invoke("transition", BridgeAction.Preview)).result).toEqual({
+			confirm: BridgeConfirm.Strong,
+			blocked: true,
+			lines: [
+				{
+					ar: "لا يوجد بيلد مستقر لهذا الإصدار بعد",
+					en: "There is no stable build for this version yet",
+				},
+			],
+		});
+	});
+
 	it("refuses an action a preview module does not answer", async () => {
 		const registry = registryFor({
 			...baseDriver(),