@serverkgg/bridge 0.0.9 → 0.0.10

package/src/runtime/serve.ts

@@ -1,5 +1,5 @@
 import { chmod, chown, mkdir, rm } from "node:fs/promises";
-import { BridgeDesired, type BridgeInstallHold, BridgeRuntime, BridgeUserError } from "../core";
+import { BridgeDesired, type BridgeInstallHold, BridgeRuntime, BridgeUserError, type LocalizedText } from "../core";
 import type { BridgeDriver } from "../modules";
 import {
 	BRIDGE_INSTALL_ERROR_LIMIT,
@@ -7,6 +7,8 @@ import {
 	type BridgeConfig,
 	type BridgePendingResult,
 	type BridgeSampleResult,
+	type BridgeSetupResult,
+	type BridgeSetupRuntime,
 	type BridgeStatus,
 } from "../protocol";
 import { configPath, readConfig, socketPath, statePath } from "./bridgeConfigReader";
@@ -18,6 +20,7 @@ import { errorText, log } from "./bridgeLog";
 import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
 import { createRegistry } from "./bridgeRegistry";
 import { createServer } from "./bridgeServer";
+import { failedSetup, setupSummaryOf, unsupportedSetup } from "./bridgeSetup";
 import { readDesired, writeDesired } from "./bridgeState";
 import { createSupervisor } from "./bridgeSupervisor";
 
@@ -67,8 +70,12 @@ export const serve = async (driver: BridgeDriver) => {
 
 	let installError: string | null = null;
 
+	let installErrorText: LocalizedText | null = null;
+
 	let installHold: BridgeInstallHold | null = null;
 
+	let setupRuntime: BridgeSetupRuntime | null = null;
+
 	const supervisor = createSupervisor({
 		cwd: config.cwd,
 		uid: config.gameUid,
@@ -98,6 +105,9 @@ export const serve = async (driver: BridgeDriver) => {
 		onEmit(event, payload) {
 			ring.emit(event, payload);
 		},
+		onSetup(runtime) {
+			setupRuntime = runtime;
+		},
 	});
 
 	const registry = createRegistry(driver, context, supervisor, ring);
@@ -113,7 +123,9 @@ export const serve = async (driver: BridgeDriver) => {
 			outOfMemory: supervisor.outOfMemory,
 			restarts: supervisor.restarts,
 			installError,
+			installErrorText,
 			installHold,
+			setup: setupSummaryOf(setupRuntime),
 		};
 	};
 
@@ -307,6 +319,44 @@ export const serve = async (driver: BridgeDriver) => {
 
 			return await pending();
 		},
+		onSetupStatus() {
+			if (!driver.setup) {
+				return unsupportedSetup();
+			}
+
+			return {
+				supported: true,
+				runtime: setupRuntime,
+			};
+		},
+		async onSetupSubmit(step, action, args): Promise<BridgeSetupResult> {
+			const module = driver.setup;
+
+			if (!module?.submit) {
+				return unsupportedSetup();
+			}
+
+			try {
+				await module.submit(context, step, action, args);
+			} catch (error) {
+				if (!(error instanceof BridgeUserError)) {
+					throw error;
+				}
+
+				log.warn("setup submit rejected", {
+					step,
+					action,
+					error: error.message,
+				});
+
+				return failedSetup(setupRuntime, error.text);
+			}
+
+			return {
+				supported: true,
+				runtime: setupRuntime,
+			};
+		},
 	});
 
 	await chmod(socketPath(config), SOCKET_MODE);
@@ -358,6 +408,7 @@ export const serve = async (driver: BridgeDriver) => {
 		log("install complete");
 	} catch (error) {
 		installError = errorText(error).slice(0, BRIDGE_INSTALL_ERROR_LIMIT);
+		installErrorText = error instanceof BridgeUserError ? error.text : null;
 
 		supervisor.setRuntime(BridgeRuntime.Crashed);
 

package/src/utils/index.ts

@@ -1 +1,2 @@
 export * from "./glob";
+export * from "./stripAnsi";

package/src/utils/stripAnsi.ts

@@ -0,0 +1,12 @@
+const ANSI_PATTERN = new RegExp(
+	[
+		"\\u001B\\][^\\u0007\\u001B]*(?:\\u0007|\\u001B\\\\)",
+		"\\u001B\\[[0-9;?]*[ -/]*[@-~]",
+		"\\u001B[@-Z\\\\-_]",
+	].join("|"),
+	"g",
+);
+
+export const stripAnsi = (line: string): string => {
+	return line.replace(ANSI_PATTERN, "");
+};

package/src/wire/panel.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import { GuideOpenTab } from "@serverkgg/bridge/guides";
 import {
 	BridgeAccess,
 	BridgeAction,
@@ -8,6 +9,8 @@ import {
 	BridgeKind,
 	BridgeLayout,
 	type BridgeManifest,
+	type BridgeSetupManifest,
+	BridgeSetupStepKind,
 	BridgeUploadMode,
 } from "@serverkgg/bridge/protocol";
 import { bridgeManifestSchema } from "./panel";
@@ -98,6 +101,7 @@ const manifest = (): BridgeManifest => ({
 		],
 	},
 	terminal: null,
+	setup: null,
 	modules: [
 		{
 			id: "broadcast",
@@ -159,6 +163,7 @@ const previewManifest = (): BridgeManifest => ({
 		],
 	},
 	terminal: null,
+	setup: null,
 	modules: [
 		{
 			id: "transition",
@@ -337,6 +342,7 @@ const detailManifest = (): BridgeManifest => ({
 		],
 	},
 	terminal: null,
+	setup: null,
 	modules: [
 		{
 			id: "modpackStatus",
@@ -412,6 +418,7 @@ const uploadManifest = (mode?: BridgeUploadMode): BridgeManifest => ({
 		],
 	},
 	terminal: null,
+	setup: null,
 	modules: [
 		{
 			id: "pending",
@@ -449,3 +456,89 @@ describe("the upload mirror", () => {
 		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
 	});
 });
+
+const setupManifest = (setup: BridgeSetupManifest | null): BridgeManifest => ({
+	version: "1.0.0",
+	panel: null,
+	terminal: null,
+	setup,
+	modules: [],
+	events: [],
+});
+
+describe("the setup mirror", () => {
+	test("carries every step kind through unchanged", () => {
+		const source = setupManifest({
+			steps: [
+				{
+					kind: BridgeSetupStepKind.Driver,
+					id: "sign-in",
+					title: text("Sign in"),
+					help: text("Sign in with your account"),
+					requiresRunning: true,
+				},
+				{
+					kind: BridgeSetupStepKind.Form,
+					id: "name",
+					title: text("Name your server"),
+					required: false,
+					tab: "settings",
+					section: "server",
+					fields: [
+						"SERVER_NAME",
+					],
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "invite",
+					title: text("Invite your friends"),
+					target: {
+						tab: GuideOpenTab.Access,
+					},
+				},
+			],
+		});
+
+		expect(bridgeManifestSchema.parse(source).setup).toEqual(source.setup);
+	});
+
+	test("takes a manifest that declares no setup", () => {
+		expect(bridgeManifestSchema.parse(setupManifest(null)).setup).toBeNull();
+	});
+
+	test("defaults a manifest from an older bridge that carries no setup block to null", () => {
+		const older = setupManifest(null);
+
+		delete (older as Partial<BridgeManifest>).setup;
+
+		expect(bridgeManifestSchema.parse(older).setup).toBeNull();
+	});
+
+	test("refuses a step kind the platform does not know", () => {
+		const source = setupManifest({
+			steps: [
+				{
+					kind: "wizard" as BridgeSetupStepKind.Driver,
+					id: "sign-in",
+					title: text("Sign in"),
+				},
+			],
+		});
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+
+	test("refuses more steps than the platform takes", () => {
+		const source = setupManifest({
+			steps: Array.from({
+				length: 9,
+			}).map((_entry, index) => ({
+				kind: BridgeSetupStepKind.Driver as const,
+				id: `step-${index}`,
+				title: text(`Step ${index}`),
+			})),
+		});
+
+		expect(bridgeManifestSchema.safeParse(source).success).toBe(false);
+	});
+});

package/src/wire/panel.ts

@@ -1,3 +1,4 @@
+import { guideOpenTargetSchema } from "@serverkgg/bridge/guides";
 import {
 	BRIDGE_ID_PATTERN,
 	BRIDGE_MODULE_ID_PATTERN,
@@ -11,6 +12,9 @@ import {
 	type BridgeManifest,
 	type BridgePanel,
 	type BridgeSection,
+	type BridgeSetupManifest,
+	type BridgeSetupStep,
+	BridgeSetupStepKind,
 	BridgeStream,
 	type BridgeTerminalArg,
 	type BridgeTerminalCommand,
@@ -30,6 +34,10 @@ const SECTION_ACTIONS_LIMIT = 10;
 
 const FORM_CLEARS_LIMIT = 8;
 
+const SETUP_STEPS_LIMIT = 8;
+
+const SETUP_STEP_FIELDS_LIMIT = 32;
+
 const zKey = z
 	.string()
 	.min(1)
@@ -276,6 +284,37 @@ export const bridgeTerminalManifestSchema: z.ZodType<BridgeTerminalManifest> = z
 	rules: z.array(bridgeTerminalRuleSchema).max(64),
 });
 
+const setupStepBase = {
+	id: zBridgeId,
+	title: panelTextSchema,
+	help: panelTextSchema.optional(),
+	required: z.boolean().optional(),
+};
+
+export const bridgeSetupStepSchema: z.ZodType<BridgeSetupStep> = z.discriminatedUnion("kind", [
+	z.object({
+		...setupStepBase,
+		kind: z.literal(BridgeSetupStepKind.Driver),
+		requiresRunning: z.boolean().optional(),
+	}),
+	z.object({
+		...setupStepBase,
+		kind: z.literal(BridgeSetupStepKind.Form),
+		tab: zBridgeId,
+		section: zBridgeId,
+		fields: z.array(zKey).max(SETUP_STEP_FIELDS_LIMIT).optional(),
+	}),
+	z.object({
+		...setupStepBase,
+		kind: z.literal(BridgeSetupStepKind.Open),
+		target: guideOpenTargetSchema,
+	}),
+]);
+
+export const bridgeSetupManifestSchema: z.ZodType<BridgeSetupManifest> = z.object({
+	steps: z.array(bridgeSetupStepSchema).min(1).max(SETUP_STEPS_LIMIT),
+});
+
 export const bridgeModuleManifestSchema = z.object({
 	id: zBridgeModuleId,
 	kind: z.enum(BridgeKind),
@@ -290,6 +329,7 @@ export const bridgeManifestSchema: z.ZodType<BridgeManifest> = z.object({
 	version: z.string(),
 	panel: bridgePanelSchema.nullable(),
 	terminal: bridgeTerminalManifestSchema.nullable().default(null),
+	setup: bridgeSetupManifestSchema.nullable().default(null),
 	modules: z.array(bridgeModuleManifestSchema).max(32),
 	events: z.array(z.string().min(1).max(64)).max(32),
 });