@serverkgg/bridge 0.0.9 → 0.0.11

package/package.json

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

@@ -2,7 +2,15 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { runValidate } from "./validate";
+import { BridgeKind, BridgeSetupStepKind } from "../core";
+import { GuideOpenTab } from "../guides";
+import type { BridgeSetupModule } from "../modules";
+import { runValidate, setupReportLines } from "./validate";
+
+const text = (value: string) => ({
+	ar: value,
+	en: value,
+});
 
 describe("validate", () => {
 	let root = "";
@@ -87,3 +95,110 @@ describe("validate", () => {
 		await expect(validate()).rejects.toThrow("missing serverk.yml");
 	});
 });
+
+describe("the setup report", () => {
+	test("says none for a driver that declares no setup", () => {
+		expect(setupReportLines(undefined)).toEqual([
+			"  setup: none",
+		]);
+	});
+
+	test("names every step, its kind, whether it is required, and where it lands", () => {
+		const setup: BridgeSetupModule = {
+			kind: BridgeKind.Setup,
+			steps: [
+				{
+					kind: BridgeSetupStepKind.Form,
+					id: "license",
+					title: text("Licence"),
+					required: true,
+					tab: "license",
+					section: "license",
+					fields: [
+						"LICENSE_KEY",
+					],
+				},
+				{
+					kind: BridgeSetupStepKind.Driver,
+					id: "verify",
+					title: text("Verify"),
+					required: true,
+					requiresRunning: true,
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "txadmin",
+					title: text("txAdmin"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Panel,
+						tabId: "license",
+					},
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "invite",
+					title: text("Invite"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Access,
+					},
+				},
+			],
+			submit: async () => {
+				return;
+			},
+		};
+
+		expect(setupReportLines(setup)).toEqual([
+			"  setup: 4 step(s)",
+			"    license — form, required → license/license [LICENSE_KEY]",
+			"    verify — driver, required → driver (needs the game running)",
+			'    txadmin — open, optional → panel tab "license"',
+			"    invite — open, optional → access",
+		]);
+	});
+
+	test("leaves a driver step that needs nothing running with no target", () => {
+		expect(
+			setupReportLines({
+				kind: BridgeKind.Setup,
+				steps: [
+					{
+						kind: BridgeSetupStepKind.Driver,
+						id: "sign-in",
+						title: text("Sign in"),
+						required: false,
+					},
+				],
+				submit: async () => {
+					return;
+				},
+			}),
+		).toEqual([
+			"  setup: 1 step(s)",
+			"    sign-in — driver, optional → driver",
+		]);
+	});
+
+	test("reads an omitted required as required, the way the platform does", () => {
+		expect(
+			setupReportLines({
+				kind: BridgeKind.Setup,
+				steps: [
+					{
+						kind: BridgeSetupStepKind.Driver,
+						id: "sign-in",
+						title: text("Sign in"),
+					},
+				],
+				submit: async () => {
+					return;
+				},
+			}),
+		).toEqual([
+			"  setup: 1 step(s)",
+			"    sign-in — driver, required → driver",
+		]);
+	});
+});

package/src/cli/validate.ts

@@ -3,7 +3,7 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { z } from "zod";
-import { type GuidePack, readGuidePack, readGuidePackage } from "../guides";
+import { GuideOpenTab, type GuideOpenTarget, type GuidePack, readGuidePack, readGuidePackage } from "../guides";
 import {
 	declaredFiles,
 	type GuidePackage,
@@ -13,8 +13,8 @@ import {
 	readAssets,
 	readPackageDocument,
 } from "../manifest";
-import type { BridgeDriver } from "../modules";
-import { isBridgeEventName } from "../protocol";
+import type { BridgeDriver, BridgeSetupModule } from "../modules";
+import { type BridgeSetupStep, BridgeSetupStepKind, isBridgeEventName } from "../protocol";
 import { validateDriver, validatePortActivation } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
 
@@ -186,6 +186,49 @@ const reportActionTargets = (driver: BridgeDriver) => {
 	}
 };
 
+const openTargetOf = (target: GuideOpenTarget) => {
+	if (target.tab === GuideOpenTab.Panel) {
+		return `panel tab "${target.tabId}"`;
+	}
+
+	if (target.tab === GuideOpenTab.Files) {
+		return target.path ? `files at "${target.path}"` : "files";
+	}
+
+	return target.tab;
+};
+
+const setupTargetOf = (step: BridgeSetupStep) => {
+	if (step.kind === BridgeSetupStepKind.Form) {
+		const fields = step.fields ?? [];
+
+		return `→ ${step.tab}/${step.section}${fields.length === 0 ? "" : ` [${fields.join(", ")}]`}`;
+	}
+
+	if (step.kind === BridgeSetupStepKind.Open) {
+		return `→ ${openTargetOf(step.target)}`;
+	}
+
+	return step.requiresRunning ? "→ driver (needs the game running)" : "→ driver";
+};
+
+export const setupReportLines = (setup: BridgeSetupModule | undefined): string[] => {
+	if (!setup) {
+		return [
+			"  setup: none",
+		];
+	}
+
+	return [
+		`  setup: ${setup.steps.length} step(s)`,
+		...setup.steps.map((step) => {
+			const target = setupTargetOf(step);
+
+			return `    ${step.id} — ${step.kind}, ${step.required === false ? "optional" : "required"}${target === "" ? "" : ` ${target}`}`;
+		}),
+	];
+};
+
 const validateGamePackage = async (source: PackageSource, manifest: Manifest, dir: string, driverArg?: string) => {
 	const assets = readAssets(source, manifest);
 	const guideFiles = manifest.guides.flatMap((guide) => [
@@ -230,6 +273,10 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 		`  driver: ${Object.keys(driver.modules ?? {}).length} panel module(s), ${driver.panel?.tabs.length ?? 0} tab(s)`,
 	);
 	console.log(`  pending: ${driver.pending ? `declared (${driver.pending.extensions.length} extension(s))` : "none"}`);
+	for (const line of setupReportLines(driver.setup)) {
+		console.log(line);
+	}
+
 	reportEvents(driver);
 	reportActionTargets(driver);
 };

package/src/context/bridgeContext.ts

@@ -1,5 +1,5 @@
 import type { BridgeStream, BridgeValues } from "../core";
-import type { BridgeHttpMethod } from "../protocol";
+import type { BridgeHttpMethod, BridgeSetupRuntime } from "../protocol";
 
 export interface BridgeServer {
 	code: string;
@@ -121,6 +121,12 @@ export interface BridgeExecResult {
 export interface BridgeLogs {
 	tail(lines: number): Promise<string[]>;
 	watch(pattern: RegExp, timeoutMs: number): Promise<RegExpMatchArray | null>;
+	follow(pattern: RegExp, onMatch: (match: RegExpMatchArray) => void): () => void;
+}
+
+export interface BridgeSetupReporter {
+	report(runtime: BridgeSetupRuntime): void;
+	clear(): void;
 }
 
 export interface BridgeLog {
@@ -141,6 +147,7 @@ export interface BridgeContext {
 	command(input: string, options?: BridgeCommandOptions): Promise<BridgeReply>;
 	exec(command: string[], options?: BridgeExecOptions): Promise<BridgeExecResult>;
 	logs: BridgeLogs;
+	setup: BridgeSetupReporter;
 	emit(event: string, payload?: BridgeValues): void;
 	log: BridgeLog;
 }

package/src/core/bridgeKind.ts

@@ -14,4 +14,5 @@ export enum BridgeKind {
 	Preview = "preview",
 	Query = "query",
 	Settings = "settings",
+	Setup = "setup",
 }

package/src/core/bridgeProbeError.ts

@@ -0,0 +1,16 @@
+export enum BridgeProbeCode {
+	Unreachable = "unreachable",
+	TimedOut = "timed-out",
+	Malformed = "malformed",
+}
+
+export class BridgeProbeError extends Error {
+	readonly code: BridgeProbeCode;
+
+	constructor(code: BridgeProbeCode, message: string) {
+		super(message);
+
+		this.name = "BridgeProbeError";
+		this.code = code;
+	}
+}

package/src/core/bridgeSetup.ts

@@ -0,0 +1,20 @@
+export enum BridgeSetupStepKind {
+	Driver = "driver",
+	Form = "form",
+	Open = "open",
+}
+
+export enum BridgeSetupStepState {
+	Pending = "pending",
+	Active = "active",
+	Done = "done",
+	Failed = "failed",
+}
+
+export enum BridgeSetupPromptKind {
+	Wait = "wait",
+	Progress = "progress",
+	Link = "link",
+	Action = "action",
+	Failed = "failed",
+}

package/src/core/bridgeValue.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import { isLocalizedText } from "./bridgeValue";
+
+describe("isLocalizedText", () => {
+	test("recognises the shape a driver authors copy in", () => {
+		expect(
+			isLocalizedText({
+				ar: "التركيب",
+				en: "Setup",
+			}),
+		).toBe(true);
+	});
+
+	test("leaves every other bridge value alone", () => {
+		expect(isLocalizedText("Hytale")).toBe(false);
+		expect(isLocalizedText(12)).toBe(false);
+		expect(isLocalizedText(true)).toBe(false);
+		expect(isLocalizedText(null)).toBe(false);
+		expect(isLocalizedText(undefined)).toBe(false);
+	});
+
+	test("refuses a half-written text rather than rendering an empty language", () => {
+		expect(
+			isLocalizedText({
+				en: "Setup",
+			}),
+		).toBe(false);
+	});
+});

package/src/core/bridgeValue.ts

@@ -11,6 +11,18 @@ export interface LocalizedText {
 	en: string;
 }
 
+export type BridgeCopy = LocalizedText | string;
+
+export const isLocalizedText = (value: unknown): value is LocalizedText => {
+	if (typeof value !== "object" || value === null) {
+		return false;
+	}
+
+	const text = value as Partial<LocalizedText>;
+
+	return typeof text.ar === "string" && typeof text.en === "string";
+};
+
 export interface BridgeOption {
 	value: string;
 	label: LocalizedText;

package/src/core/index.ts

@@ -6,8 +6,10 @@ export * from "./bridgeId";
 export * from "./bridgeKind";
 export * from "./bridgeNetError";
 export * from "./bridgePort";
+export * from "./bridgeProbeError";
 export * from "./bridgeRuntime";
 export * from "./bridgeSecretError";
+export * from "./bridgeSetup";
 export * from "./bridgeStream";
 export * from "./bridgeUserError";
 export * from "./bridgeValue";

package/src/guides/blocks.ts

@@ -13,6 +13,8 @@ export enum GuideOpenTab {
 	Console = "console",
 	Files = "files",
 	Backups = "backups",
+	Access = "access",
+	Setup = "setup",
 	Panel = "panel",
 }
 
@@ -51,6 +53,12 @@ export const guideOpenTargetSchema = z.discriminatedUnion("tab", [
 	z.object({
 		tab: z.literal(GuideOpenTab.Backups),
 	}),
+	z.object({
+		tab: z.literal(GuideOpenTab.Access),
+	}),
+	z.object({
+		tab: z.literal(GuideOpenTab.Setup),
+	}),
 	z.object({
 		tab: z.literal(GuideOpenTab.Files),
 		path: zGuideFilePath.nullable(),

package/src/guides/markdown.test.ts

@@ -132,6 +132,8 @@ describe("directives", () => {
 				"@[open](backups)",
 				"@[open](files:server.properties)",
 				"@[open](files)",
+				"@[open](access)",
+				"@[open](setup)",
 				"@[open](panel:mods)",
 			].join("\n"),
 		);
@@ -163,6 +165,18 @@ describe("directives", () => {
 					path: null,
 				},
 			},
+			{
+				type: "open",
+				target: {
+					tab: GuideOpenTab.Access,
+				},
+			},
+			{
+				type: "open",
+				target: {
+					tab: GuideOpenTab.Setup,
+				},
+			},
 			{
 				type: "open",
 				target: {
@@ -181,6 +195,10 @@ describe("directives", () => {
 		expect(() => parse("@[open](nowhere)")).toThrow(/unknown open target "nowhere"/);
 	});
 
+	test("rejects an argument on a target that takes none", () => {
+		expect(() => parse("@[open](setup:sign-in)")).toThrow(/"setup" target does not take an argument/);
+	});
+
 	test("rejects a traversing file path", () => {
 		expect(() => parse("@[open](files:../../etc/passwd)")).toThrow();
 	});

package/src/guides/markdown.ts

@@ -312,7 +312,13 @@ const parseOpenTarget = (path: string, line: number, value: string): GuideOpenTa
 		fail(path, line, `"${tab}" target does not take an argument`);
 	}
 
-	if (tab !== GuideOpenTab.Overview && tab !== GuideOpenTab.Console && tab !== GuideOpenTab.Backups) {
+	if (
+		tab !== GuideOpenTab.Overview
+		&& tab !== GuideOpenTab.Console
+		&& tab !== GuideOpenTab.Backups
+		&& tab !== GuideOpenTab.Access
+		&& tab !== GuideOpenTab.Setup
+	) {
 		fail(path, line, `unknown open target "${value}"`);
 	}
 

package/src/manifest/guide.ts

@@ -16,6 +16,7 @@ export enum GuideSurface {
 	Files = "files",
 	Backups = "backups",
 	Panel = "panel",
+	Setup = "setup",
 }
 
 export const guideTagSchema = z.object({

package/src/manifest/manifest.test.ts

@@ -3,6 +3,7 @@ import { z } from "zod";
 import { PortJoin } from "../core";
 import { GameCategory } from "./category";
 import { guidePackageSchema, MANIFEST_SCHEMA_VERSION, manifestSchema, packageSchema } from "./manifest";
+import { isServerkAvatarTemplate, PRESENCE_AVATAR_LENGTH_LIMIT } from "./presence";
 
 const text = (value: string) => ({
 	ar: value,
@@ -626,7 +627,21 @@ describe("presence", () => {
 		expect(result.success && result.data.presence?.fields[0]?.inline).toBe(true);
 	});
 
-	test("refuses an avatar template that is not https", () => {
+	test("accepts a serverk avatar template", () => {
+		const result = manifestSchema.safeParse({
+			...base(),
+			presence: {
+				name: "player",
+				id: "playerId",
+				avatar: "serverk://avatars/hytale/{playerId}",
+			},
+		});
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.presence?.avatar).toBe("serverk://avatars/hytale/{playerId}");
+	});
+
+	test("refuses an avatar template that is neither https nor a serverk avatar", () => {
 		const result = manifestSchema.safeParse({
 			...base(),
 			presence: {
@@ -635,7 +650,39 @@ describe("presence", () => {
 		});
 
 		expect(result.success).toBe(false);
-		expect(result.error && z.prettifyError(result.error)).toContain("must be an https url template");
+		expect(result.error && z.prettifyError(result.error)).toContain(
+			"must be an https or serverk://avatars/ url template",
+		);
+	});
+
+	test("refuses a serverk scheme that is not an avatar path", () => {
+		const result = manifestSchema.safeParse({
+			...base(),
+			presence: {
+				avatar: "serverk://heads/hytale/{playerId}",
+			},
+		});
+
+		expect(result.success).toBe(false);
+		expect(result.error && z.prettifyError(result.error)).toContain(
+			"must be an https or serverk://avatars/ url template",
+		);
+	});
+
+	test("refuses a serverk avatar template longer than the limit", () => {
+		const result = manifestSchema.safeParse({
+			...base(),
+			presence: {
+				avatar: `serverk://avatars/hytale/${"a".repeat(PRESENCE_AVATAR_LENGTH_LIMIT)}`,
+			},
+		});
+
+		expect(result.success).toBe(false);
+	});
+
+	test("tells a serverk avatar template apart from an https one", () => {
+		expect(isServerkAvatarTemplate("serverk://avatars/hytale/{playerId}")).toBe(true);
+		expect(isServerkAvatarTemplate("https://mc-heads.net/avatar/{skin}/128")).toBe(false);
 	});
 
 	test("refuses a payload key that could never be a capture group", () => {

package/src/manifest/presence.ts

@@ -6,6 +6,14 @@ export const PRESENCE_FIELDS_LIMIT = 6;
 
 export const PRESENCE_AVATAR_LENGTH_LIMIT = 300;
 
+export const SERVERK_AVATAR_PREFIX = "serverk://avatars/";
+
+export const PRESENCE_AVATAR_PATTERN = /^(https:\/\/|serverk:\/\/avatars\/)/;
+
+export const isServerkAvatarTemplate = (template: string): boolean => {
+	return template.startsWith(SERVERK_AVATAR_PREFIX);
+};
+
 export const manifestPresenceFieldSchema = z.object({
 	key: zPayloadKey,
 	label: localizedText(32),
@@ -20,7 +28,7 @@ export const manifestPresenceSchema = z.object({
 	avatar: z
 		.string()
 		.max(PRESENCE_AVATAR_LENGTH_LIMIT)
-		.regex(/^https:\/\//, "must be an https url template")
+		.regex(PRESENCE_AVATAR_PATTERN, "must be an https or serverk://avatars/ url template")
 		.optional(),
 	fields: z.array(manifestPresenceFieldSchema).max(PRESENCE_FIELDS_LIMIT).default([]),
 });

package/src/modules/bridge.ts

@@ -1,5 +1,6 @@
 import type { BridgeContext, BridgeExecResult, BridgeFileEntry, BridgeReply } from "../context";
 import type {
+	BridgeCopy,
 	BridgeInstallHold,
 	BridgeInstallOutcome,
 	BridgeOption,
@@ -34,6 +35,15 @@ import type {
 } from "../protocol/bridgeCatalog";
 import type { BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
+import type {
+	BridgeSetupAction,
+	BridgeSetupManifest,
+	BridgeSetupPrompt,
+	BridgeSetupRuntime,
+	BridgeSetupStep,
+	BridgeSetupStepStatus,
+	BridgeSetupSummary,
+} from "../protocol/bridgeSetup";
 import type { BridgeTerminalArg, BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
 import type { BridgeDriver } from "./bridgeDriver";
 import type {
@@ -56,6 +66,7 @@ import type {
 	BridgeSample,
 	BridgeServerAction,
 	BridgeSettingsModule,
+	BridgeSetupModule,
 	BridgeTerminalModule,
 } from "./bridgeModule";
 
@@ -72,6 +83,7 @@ export namespace Bridge {
 	export type CatalogQuery = BridgeCatalogQuery;
 	export type Collection<Row extends BridgeRow = BridgeRow> = BridgeCollectionModule<Row>;
 	export type Context = BridgeContext;
+	export type Copy = BridgeCopy;
 	export type Detail = BridgeDetailModule;
 	export type DetailAction = BridgeDetailAction;
 	export type DetailBadge = BridgeDetailBadge;
@@ -106,6 +118,14 @@ export namespace Bridge {
 	export type SectionAction = BridgeSectionAction;
 	export type ServerAction = BridgeServerAction;
 	export type Settings = BridgeSettingsModule;
+	export type Setup = BridgeSetupModule;
+	export type SetupAction = BridgeSetupAction;
+	export type SetupManifest = BridgeSetupManifest;
+	export type SetupPrompt = BridgeSetupPrompt;
+	export type SetupRuntime = BridgeSetupRuntime;
+	export type SetupStep = BridgeSetupStep;
+	export type SetupStepStatus = BridgeSetupStepStatus;
+	export type SetupSummary = BridgeSetupSummary;
 	export type Terminal = BridgeTerminalModule;
 	export type TerminalArg = BridgeTerminalArg;
 	export type TerminalCommand = BridgeTerminalCommand;

package/src/modules/bridgeDriver.ts

@@ -8,6 +8,7 @@ import type {
 	BridgePanelModule,
 	BridgePendingModule,
 	BridgeQueryModule,
+	BridgeSetupModule,
 	BridgeTerminalModule,
 } from "./bridgeModule";
 
@@ -19,6 +20,7 @@ export interface BridgeDriver {
 	backup?: BridgeBackupModule;
 	announce?: BridgeAnnounceModule;
 	pending?: BridgePendingModule;
+	setup?: BridgeSetupModule;
 	terminal?: BridgeTerminalModule;
 	panel?: BridgePanel;
 	modules?: Record<string, BridgePanelModule>;

package/src/modules/bridgeModule.ts

@@ -4,6 +4,7 @@ import type { BridgeDetail, BridgeDetailOutcome } from "../panel";
 import type { BridgeCatalogEntry, BridgeCatalogPage, BridgeCatalogQuery } from "../protocol/bridgeCatalog";
 import type { BridgeDescribeResult, BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
+import type { BridgeSetupStep } from "../protocol/bridgeSetup";
 import type { BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
 
 export type BridgeDescription = Omit<BridgeDescribeResult, "supported">;
@@ -43,6 +44,12 @@ export interface BridgePendingModule {
 	add(context: BridgeContext, input: string): Promise<void>;
 }
 
+export interface BridgeSetupModule {
+	kind: BridgeKind.Setup;
+	steps: BridgeSetupStep[];
+	submit?(context: BridgeContext, step: string, action: string, args: BridgeValues): Promise<void>;
+}
+
 export interface BridgeSample {
 	online: number | null;
 	max: number | null;

package/src/panel/bridgeControl.ts

@@ -1,6 +1,7 @@
 export enum BridgeControl {
 	Boolean = "boolean",
 	Number = "number",
+	Secret = "secret",
 	Select = "select",
 	Slider = "slider",
 	Text = "text",

package/src/panel/bridgeDetail.ts

@@ -1,4 +1,4 @@
-import type { BridgeValue, LocalizedText } from "../core";
+import type { BridgeCopy, BridgeValue, LocalizedText } from "../core";
 
 export enum BridgeDetailTone {
 	Neutral = "neutral",
@@ -11,6 +11,7 @@ export enum BridgeDetailFormat {
 	Bytes = "bytes",
 	Date = "date",
 	Number = "number",
+	Secret = "secret",
 	Text = "text",
 }
 
@@ -22,7 +23,7 @@ export interface BridgeDetailBadge {
 export interface BridgeDetailStat {
 	key: string;
 	label: LocalizedText;
-	value: BridgeValue;
+	value: BridgeValue | LocalizedText;
 	format: BridgeDetailFormat;
 }
 
@@ -33,9 +34,9 @@ export interface BridgeDetailLink {
 
 export interface BridgeDetail {
 	id: string;
-	title: string;
-	subtitle: string | null;
-	description: string | null;
+	title: BridgeCopy;
+	subtitle: BridgeCopy | null;
+	description: BridgeCopy | null;
 	image: string | null;
 	badges: BridgeDetailBadge[];
 	stats: BridgeDetailStat[];

package/src/panel/bridgePanel.ts

@@ -32,6 +32,8 @@ export interface BridgeField {
 	max?: number;
 	step?: number;
 	maxLength?: number;
+	pattern?: string;
+	patternHint?: LocalizedText;
 	options?: BridgeOption[] | BridgeOptionsRef;
 	visibleWhen?: BridgeVisibleWhen;
 }