@serverkgg/bridge 0.0.9 → 0.0.10

package/src/protocol/bridgeManifest.ts

@@ -1,6 +1,7 @@
 import type { BridgeKind, BridgeStream } from "../core";
 import type { BridgePanel } from "../panel";
 import type { BridgeTerminalCommand, BridgeTerminalLevel } from "../terminal";
+import type { BridgeSetupManifest } from "./bridgeSetup";
 
 export interface BridgeTerminalRuleManifest {
 	match: string;
@@ -28,6 +29,7 @@ export interface BridgeManifest {
 	version: string;
 	panel: BridgePanel | null;
 	terminal: BridgeTerminalManifest | null;
+	setup: BridgeSetupManifest | null;
 	modules: BridgeModuleManifest[];
 	events: string[];
 }

package/src/protocol/bridgeSetup.ts

@@ -0,0 +1,97 @@
+import type { BridgeSetupPromptKind, BridgeSetupStepKind, BridgeSetupStepState, LocalizedText } from "../core";
+import type { GuideOpenTarget } from "../guides";
+
+interface BridgeSetupStepBase {
+	id: string;
+	title: LocalizedText;
+	help?: LocalizedText;
+	required?: boolean;
+}
+
+export interface BridgeSetupDriverStep extends BridgeSetupStepBase {
+	kind: BridgeSetupStepKind.Driver;
+	requiresRunning?: boolean;
+}
+
+export interface BridgeSetupFormStep extends BridgeSetupStepBase {
+	kind: BridgeSetupStepKind.Form;
+	tab: string;
+	section: string;
+	fields?: string[];
+}
+
+export interface BridgeSetupOpenStep extends BridgeSetupStepBase {
+	kind: BridgeSetupStepKind.Open;
+	target: GuideOpenTarget;
+}
+
+export type BridgeSetupStep = BridgeSetupDriverStep | BridgeSetupFormStep | BridgeSetupOpenStep;
+
+export interface BridgeSetupManifest {
+	steps: BridgeSetupStep[];
+}
+
+export interface BridgeSetupAction {
+	id: string;
+	label: LocalizedText;
+}
+
+export interface BridgeSetupWaitPrompt {
+	kind: BridgeSetupPromptKind.Wait;
+	message: LocalizedText;
+}
+
+export interface BridgeSetupProgressPrompt {
+	kind: BridgeSetupPromptKind.Progress;
+	message: LocalizedText;
+	percent: number | null;
+	detail: string | null;
+}
+
+export interface BridgeSetupLinkPrompt {
+	kind: BridgeSetupPromptKind.Link;
+	message: LocalizedText;
+	url: string;
+	code: string | null;
+	expiresAt: string | null;
+	actions: BridgeSetupAction[];
+}
+
+export interface BridgeSetupActionPrompt {
+	kind: BridgeSetupPromptKind.Action;
+	message: LocalizedText;
+	actions: BridgeSetupAction[];
+}
+
+export interface BridgeSetupFailedPrompt {
+	kind: BridgeSetupPromptKind.Failed;
+	message: LocalizedText;
+	actions: BridgeSetupAction[];
+}
+
+export type BridgeSetupPrompt =
+	| BridgeSetupActionPrompt
+	| BridgeSetupFailedPrompt
+	| BridgeSetupLinkPrompt
+	| BridgeSetupProgressPrompt
+	| BridgeSetupWaitPrompt;
+
+export interface BridgeSetupStepStatus {
+	id: string;
+	state: BridgeSetupStepState;
+}
+
+export interface BridgeSetupRuntime {
+	steps: BridgeSetupStepStatus[];
+	prompt: BridgeSetupPrompt | null;
+}
+
+export interface BridgeSetupSummary {
+	step: string | null;
+	attention: boolean;
+}
+
+export interface BridgeSetupResult {
+	supported: boolean;
+	runtime: BridgeSetupRuntime | null;
+}

package/src/protocol/index.ts

@@ -10,4 +10,5 @@ export * from "./bridgeLimits";
 export * from "./bridgeLine";
 export * from "./bridgeManifest";
 export * from "./bridgePreview";
+export * from "./bridgeSetup";
 export * from "./bridgeVersion";

package/src/runtime/bridgeConfigReader.ts

@@ -82,14 +82,8 @@ export const statePath = (config: BridgeConfig) => {
 	return `${config.run}/${BRIDGE_STATE_NAME}`;
 };
 
-export const readConfig = async (path: string): Promise<BridgeConfig> => {
-	const file = Bun.file(path);
-
-	if (!(await file.exists())) {
-		throw new BridgeConfigError(`no bridge config at "${path}"`);
-	}
-
-	const parsed: unknown = JSON.parse(await file.text());
+export const parseConfig = (text: string): BridgeConfig => {
+	const parsed: unknown = JSON.parse(text);
 
 	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
 		throw new BridgeConfigError("bridge config must be an object");
@@ -117,3 +111,13 @@ export const readConfig = async (path: string): Promise<BridgeConfig> => {
 
 	return config;
 };
+
+export const readConfig = async (path: string): Promise<BridgeConfig> => {
+	const file = Bun.file(path);
+
+	if (!(await file.exists())) {
+		throw new BridgeConfigError(`no bridge config at "${path}"`);
+	}
+
+	return parseConfig(await file.text());
+};

package/src/runtime/bridgeContext.ts

@@ -1,18 +1,22 @@
 import type { BridgeContext } from "../context";
 import type { BridgeValues } from "../core";
-import type { BridgeConfig } from "../protocol";
+import type { BridgeConfig, BridgeSetupRuntime } from "../protocol";
+import { stripAnsi } from "../utils";
 import { createBridgeCodecs } from "./bridgeCodec";
+import { configPath } from "./bridgeConfigReader";
 import { createBridgeEgress } from "./bridgeEgress";
 import { createBridgeExec } from "./bridgeExec";
 import { createBridgeFiles } from "./bridgeFiles";
 import type { BridgeLeveledLogger } from "./bridgeLog";
 import { createBridgeNet } from "./bridgeNet";
 import { createBridgeProbes } from "./bridgeProbe";
+import { createBridgeSecrets } from "./bridgeSecrets";
 import type { BridgeSupervisor } from "./bridgeSupervisor";
 
 export interface ContextHooks {
 	onLog: BridgeLeveledLogger;
 	onEmit: (event: string, payload?: BridgeValues) => void;
+	onSetup: (runtime: BridgeSetupRuntime | null) => void;
 }
 
 export const createContext = (
@@ -22,6 +26,8 @@ export const createContext = (
 ): BridgeContext => {
 	const egress = createBridgeEgress(config);
 
+	const secrets = createBridgeSecrets(configPath(), config);
+
 	const files = createBridgeFiles({
 		root: config.cwd,
 		uid: config.gameUid,
@@ -45,7 +51,7 @@ export const createContext = (
 		},
 
 		secret(key) {
-			return config.secrets[key] ?? null;
+			return secrets.read(key);
 		},
 
 		port(key) {
@@ -84,6 +90,26 @@ export const createContext = (
 			async watch(pattern, timeoutMs) {
 				return await supervisor.watch(pattern, timeoutMs);
 			},
+
+			follow(pattern, onMatch) {
+				return supervisor.subscribe((entry) => {
+					const match = stripAnsi(entry.line).match(pattern);
+
+					if (match) {
+						onMatch(match);
+					}
+				});
+			},
+		},
+
+		setup: {
+			report(runtime) {
+				hooks.onSetup(runtime);
+			},
+
+			clear() {
+				hooks.onSetup(null);
+			},
 		},
 
 		emit(event, payload) {

package/src/runtime/bridgeDriver.test.ts

@@ -1,7 +1,8 @@
 import { describe, expect, test } from "bun:test";
-import { BridgeKind, PortJoin, PortProtocol } from "../core";
+import { BridgeKind, BridgeSetupStepKind, PortJoin, PortProtocol } from "../core";
+import { GuideOpenTab } from "../guides";
 import type { ManifestPort, ManifestPortActivation } from "../manifest";
-import type { BridgeDriver, BridgePendingModule } from "../modules";
+import type { BridgeDriver, BridgePendingModule, BridgeSetupModule } from "../modules";
 import {
 	BridgeConfirm,
 	BridgeControl,
@@ -13,6 +14,7 @@ import {
 	BridgeUploadMode,
 	type BridgeVisibleWhen,
 } from "../panel";
+import type { BridgeSetupStep } from "../protocol";
 import { validateDriver, validatePortActivation } from "./bridgeDriver";
 
 const text = (value: string) => ({
@@ -1125,3 +1127,271 @@ describe("the pending module", () => {
 		).toThrow('module id "pending" is reserved');
 	});
 });
+
+const driverWithSetup = (setup: BridgeSetupModule): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	setup,
+	panel: {
+		tabs: [
+			{
+				id: "settings",
+				title: text("Settings"),
+				sections: [
+					{
+						layout: BridgeLayout.Form,
+						id: "server",
+						target: BridgeFormTarget.Variables,
+						fields: [
+							field("SERVER_NAME"),
+							field("MOTD"),
+						],
+					},
+				],
+			},
+		],
+	},
+});
+
+const driverStep = (id: string) => ({
+	kind: BridgeSetupStepKind.Driver as const,
+	id,
+	title: text(id),
+});
+
+const setupWith = (steps: BridgeSetupStep[]): BridgeSetupModule => ({
+	kind: BridgeKind.Setup,
+	steps,
+});
+
+describe("the setup singleton", () => {
+	test("takes a driver step with both locales", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						driverStep("sign-in"),
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a setup that declares no steps", () => {
+		expect(() => validateDriver(driverWithSetup(setupWith([])))).toThrow("the setup module declares no steps");
+	});
+
+	test("rejects more steps than the platform takes", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith(
+						Array.from({
+							length: 9,
+						}).map((_entry, index) => driverStep(`step-${index}`)),
+					),
+				),
+			),
+		).toThrow("the setup module declares 9 steps — the platform takes at most 8");
+	});
+
+	test("rejects a step id that is not kebab-case", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						driverStep("signIn"),
+					]),
+				),
+			),
+		).toThrow('the setup module step id "signIn" must be kebab-case');
+	});
+
+	test("rejects the same step id twice", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						driverStep("sign-in"),
+						driverStep("sign-in"),
+					]),
+				),
+			),
+		).toThrow('the setup module declares step "sign-in" more than once');
+	});
+
+	test("rejects a title that is missing a locale", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Driver,
+							id: "sign-in",
+							title: {
+								ar: "",
+								en: "Sign in",
+							},
+						},
+					]),
+				),
+			),
+		).toThrow('the setup module step "sign-in" title needs both arabic and english text');
+	});
+
+	test("takes a form step that names an existing form section and its own fields", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Form,
+							id: "name",
+							title: text("Name"),
+							tab: "settings",
+							section: "server",
+							fields: [
+								"SERVER_NAME",
+							],
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects a form step that names a section the panel does not declare", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Form,
+							id: "name",
+							title: text("Name"),
+							tab: "settings",
+							section: "missing",
+						},
+					]),
+				),
+			),
+		).toThrow(
+			'the setup module step "name" names tab "settings" section "missing", which is not a form section of this panel',
+		);
+	});
+
+	test("rejects a form step that names a field the section does not declare", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Form,
+							id: "name",
+							title: text("Name"),
+							tab: "settings",
+							section: "server",
+							fields: [
+								"PASSWORD",
+							],
+						},
+					]),
+				),
+			),
+		).toThrow('the setup module step "name" names field "PASSWORD", which section "server" does not declare');
+	});
+
+	test("takes an open step that names an existing panel tab", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Open,
+							id: "tune",
+							title: text("Tune"),
+							target: {
+								tab: GuideOpenTab.Panel,
+								tabId: "settings",
+							},
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("rejects an open step that names a panel tab the panel does not declare", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Open,
+							id: "tune",
+							title: text("Tune"),
+							target: {
+								tab: GuideOpenTab.Panel,
+								tabId: "world",
+							},
+						},
+					]),
+				),
+			),
+		).toThrow('the setup module step "tune" opens panel tab "world", which the panel does not declare');
+	});
+
+	test("takes an open step that leaves the panel altogether", () => {
+		expect(() =>
+			validateDriver(
+				driverWithSetup(
+					setupWith([
+						{
+							kind: BridgeSetupStepKind.Open,
+							id: "invite",
+							title: text("Invite"),
+							target: {
+								tab: GuideOpenTab.Access,
+							},
+						},
+					]),
+				),
+			),
+		).not.toThrow();
+	});
+
+	test("reserves the setup module id for the singleton", () => {
+		expect(() =>
+			validateDriver({
+				install: {
+					kind: BridgeKind.Install,
+					run: async () => {
+						return;
+					},
+				},
+				lifecycle: {
+					kind: BridgeKind.Lifecycle,
+					command: async () => [
+						"run",
+					],
+				},
+				modules: {
+					setup: {
+						kind: BridgeKind.Collection,
+						list: async () => [],
+					},
+				},
+			}),
+		).toThrow('module id "setup" is reserved');
+	});
+});

package/src/runtime/bridgeDriver.ts

@@ -1,4 +1,11 @@
-import { BRIDGE_ID_PATTERN, BRIDGE_MODULE_ID_PATTERN, BridgeKind, type LocalizedText } from "../core";
+import {
+	BRIDGE_ID_PATTERN,
+	BRIDGE_MODULE_ID_PATTERN,
+	BridgeKind,
+	BridgeSetupStepKind,
+	type LocalizedText,
+} from "../core";
+import { GuideOpenTab } from "../guides";
 import type { ManifestPort } from "../manifest";
 import type { BridgeDriver, BridgePanelModule } from "../modules";
 import {
@@ -28,6 +35,7 @@ import {
 	BRIDGE_PLACEHOLDER_LENGTH_LIMIT,
 	BRIDGE_ROW_ACTIONS_LIMIT,
 	BRIDGE_SECTION_ACTIONS_LIMIT,
+	BRIDGE_SETUP_STEPS_LIMIT,
 	BRIDGE_STAGING_LENGTH_LIMIT,
 	BRIDGE_TAB_SECTIONS_LIMIT,
 	BRIDGE_TABLE_COLUMNS_LIMIT,
@@ -47,6 +55,7 @@ const RESERVED_MODULE_IDS = new Set([
 	"lifecycle",
 	"pending",
 	"query",
+	"setup",
 ]);
 
 export class BridgeDriverError extends Error {
@@ -437,6 +446,77 @@ const validatePending = (driver: BridgeDriver) => {
 	}
 };
 
+const formSectionOf = (driver: BridgeDriver, tabId: string, sectionId: string) => {
+	const tab = (driver.panel?.tabs ?? []).find((entry) => entry.id === tabId);
+	const section = (tab?.sections ?? []).find((entry) => entry.id === sectionId);
+
+	if (!section || section.layout !== BridgeLayout.Form) {
+		return null;
+	}
+
+	return section;
+};
+
+const validateSetup = (driver: BridgeDriver) => {
+	const setup = driver.setup;
+
+	if (!setup) {
+		return;
+	}
+
+	const where = "the setup module";
+
+	if (setup.kind !== BridgeKind.Setup) {
+		fail(`${where} declares kind "${setup.kind}", which is not "${BridgeKind.Setup}"`);
+	}
+
+	if (setup.steps.length === 0) {
+		fail(`${where} declares no steps`);
+	}
+
+	countIn(setup.steps.length, BRIDGE_SETUP_STEPS_LIMIT, "steps", where);
+
+	const ids = new Set<string>();
+
+	for (const step of setup.steps) {
+		if (ids.has(step.id)) {
+			fail(`${where} declares step "${step.id}" more than once`);
+		}
+
+		ids.add(step.id);
+
+		const at = `${where} step "${step.id}"`;
+
+		validateId(step.id, `${where} step`);
+		validateText(step.title, "title", at);
+		validateText(step.help, "help", at);
+
+		if (step.kind === BridgeSetupStepKind.Form) {
+			const section = formSectionOf(driver, step.tab, step.section);
+
+			if (!section) {
+				fail(`${at} names tab "${step.tab}" section "${step.section}", which is not a form section of this panel`);
+
+				continue;
+			}
+
+			for (const key of step.fields ?? []) {
+				if (!section.fields.some((field) => field.key === key)) {
+					fail(`${at} names field "${key}", which section "${step.section}" does not declare`);
+				}
+			}
+		}
+
+		if (step.kind === BridgeSetupStepKind.Open) {
+			const target = step.target;
+
+			if (target.tab === GuideOpenTab.Panel && !(driver.panel?.tabs ?? []).some((tab) => tab.id === target.tabId)) {
+				fail(`${at} opens panel tab "${target.tabId}", which the panel does not declare`);
+			}
+		}
+	}
+};
+
 const validateTab = (modules: Record<string, BridgePanelModule>, tab: BridgeTab) => {
 	const sections = new Set<string>();
 
@@ -474,6 +554,7 @@ export const validateDriver = (driver: BridgeDriver) => {
 	countIn(emitted.size, BRIDGE_EVENTS_LIMIT, "event names", "the driver");
 
 	validatePending(driver);
+	validateSetup(driver);
 
 	for (const [id, module] of Object.entries(modules)) {
 		validateModuleId(id, "module");