@serverkgg/bridge 0.0.8 → 0.0.10

package/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.8",
-	"description": "Serverk game bridge — driver runtime, wire protocol, manifest schema, and maintainer CLI",
+	"version": "0.0.10",
+	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
 	"repository": {
@@ -29,6 +29,6 @@
 		"test": "bun test --parallel"
 	},
 	"dependencies": {
-		"zod": "4.4.3"
+		"zod": "4.5.4"
 	}
 }

package/src/cli/validate.ts

@@ -229,6 +229,8 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 	console.log(
 		`  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"}`);
+	console.log(`  setup: ${driver.setup ? `${driver.setup.steps.length} step(s)` : "none"}`);
 	reportEvents(driver);
 	reportActionTargets(driver);
 };

package/src/context/bridgeContext.ts

@@ -1,4 +1,5 @@
 import type { BridgeStream, BridgeValues } from "../core";
+import type { BridgeHttpMethod, BridgeSetupRuntime } from "../protocol";
 
 export interface BridgeServer {
 	code: string;
@@ -15,16 +16,22 @@ export interface BridgeFileEntry {
 	modifiedAt: string;
 }
 
+export type BridgeDigestAlgorithm = "sha1" | "sha256" | "sha512";
+
 export interface BridgeDownloadOptions {
 	digest?: string;
 	sizeBytes?: number;
 	cache?: boolean;
+	quiet?: boolean;
+	timeoutMs?: number;
 }
 
 export interface BridgeExtractOptions {
 	extensions?: string[];
 	tree?: boolean;
 	select?: string;
+	selects?: string[];
+	exclude?: string[];
 }
 
 export interface BridgeFiles {
@@ -36,6 +43,7 @@ export interface BridgeFiles {
 	ensure(...paths: string[]): Promise<void>;
 	exists(path: string): Promise<boolean>;
 	size(path: string): Promise<number>;
+	digest(path: string, algorithm: BridgeDigestAlgorithm): Promise<string>;
 	download(path: string, url: string, options?: BridgeDownloadOptions): Promise<void>;
 	extract(path: string, destination: string, options?: BridgeExtractOptions): Promise<string[]>;
 }
@@ -57,6 +65,8 @@ export interface BridgeCodecs {
 }
 
 export interface BridgeRequestOptions {
+	httpMethod?: BridgeHttpMethod;
+	body?: string;
 	headers?: Record<string, string>;
 	timeoutMs?: number;
 	cache?: boolean;
@@ -111,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 {
@@ -131,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/context/index.ts

@@ -1 +1,2 @@
+export { BridgeHttpMethod } from "../protocol";
 export * from "./bridgeContext";

package/src/core/bridgeDownloadError.ts

@@ -0,0 +1,10 @@
+export class BridgeDownloadError extends Error {
+	readonly status: number | null;
+
+	constructor(status: number | null, message: string) {
+		super(message);
+
+		this.name = "BridgeDownloadError";
+		this.status = status;
+	}
+}

package/src/core/bridgeHold.ts

@@ -0,0 +1,12 @@
+export enum BridgeHoldReason {
+	PendingFiles = "pending-files",
+}
+
+export interface BridgeInstallHold {
+	reason: BridgeHoldReason;
+	count: number;
+}
+
+export interface BridgeInstallOutcome {
+	hold: BridgeInstallHold | null;
+}

package/src/core/bridgeKind.ts

@@ -4,12 +4,15 @@ export enum BridgeKind {
 	Backup = "backup",
 	Catalog = "catalog",
 	Collection = "collection",
+	Detail = "detail",
 	Terminal = "terminal",
 	Events = "events",
 	Install = "install",
 	Lifecycle = "lifecycle",
 	Options = "options",
+	Pending = "pending",
 	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/bridgeUserError.test.ts

@@ -0,0 +1,23 @@
+import { describe, expect, test } from "bun:test";
+import { Bridge } from "../modules";
+import { BridgeUserError } from "./bridgeUserError";
+
+describe("BridgeUserError", () => {
+	const text = {
+		ar: "هذا مو الملف اللي ننتظره",
+		en: "this is not a file we are waiting for",
+	};
+
+	test("reads as english in a log line and keeps both languages for the player", () => {
+		const error = new BridgeUserError(text);
+
+		expect(error).toBeInstanceOf(Error);
+		expect(error.name).toBe("BridgeUserError");
+		expect(error.message).toBe(text.en);
+		expect(error.text).toEqual(text);
+	});
+
+	test("is the class a driver reaches through the published namespace", () => {
+		expect(new Bridge.UserError(text)).toBeInstanceOf(BridgeUserError);
+	});
+});

package/src/core/bridgeUserError.ts

@@ -0,0 +1,12 @@
+import type { LocalizedText } from "./bridgeValue";
+
+export class BridgeUserError extends Error {
+	readonly text: LocalizedText;
+
+	constructor(text: LocalizedText) {
+		super(text.en);
+
+		this.name = "BridgeUserError";
+		this.text = text;
+	}
+}

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

@@ -1,10 +1,15 @@
 export * from "./bridgeAction";
+export * from "./bridgeDownloadError";
 export * from "./bridgeFailure";
+export * from "./bridgeHold";
 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/index.ts

@@ -6,5 +6,6 @@ export * from "./image";
 export * from "./jsonSchema";
 export * from "./localized";
 export * from "./manifest";
+export * from "./presence";
 export * from "./primitives";
 export * from "./source";

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,
@@ -586,3 +587,134 @@ describe("packageSchema", () => {
 		expect(result.error && z.prettifyError(result.error)).toContain('tag "start" is not declared in guideTags');
 	});
 });
+
+describe("presence", () => {
+	test("is optional, so a game that declares none parses", () => {
+		const result = manifestSchema.safeParse(base());
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.presence).toBeUndefined();
+	});
+
+	test("defaults the name key to player and the field list to empty", () => {
+		const result = manifestSchema.safeParse({
+			...base(),
+			presence: {},
+		});
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.presence?.name).toBe("player");
+		expect(result.success && result.data.presence?.fields).toEqual([]);
+	});
+
+	test("accepts an avatar template and localized fields", () => {
+		const result = manifestSchema.safeParse({
+			...base(),
+			presence: {
+				name: "player",
+				id: "uuid",
+				avatar: "https://mc-heads.net/avatar/{skin}/128",
+				fields: [
+					{
+						key: "platform",
+						label: text("Platform"),
+					},
+				],
+			},
+		});
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.presence?.fields[0]?.inline).toBe(true);
+	});
+
+	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: {
+				avatar: "http://mc-heads.net/avatar/{skin}/128",
+			},
+		});
+
+		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 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", () => {
+		const result = manifestSchema.safeParse({
+			...base(),
+			presence: {
+				name: "player name",
+			},
+		});
+
+		expect(result.success).toBe(false);
+		expect(result.error && z.prettifyError(result.error)).toContain("must be a valid capture group name");
+	});
+
+	test("refuses the same field declared twice", () => {
+		const result = manifestSchema.safeParse({
+			...base(),
+			presence: {
+				fields: [
+					{
+						key: "platform",
+						label: text("Platform"),
+					},
+					{
+						key: "platform",
+						label: text("Platform again"),
+					},
+				],
+			},
+		});
+
+		expect(result.success).toBe(false);
+		expect(result.error && z.prettifyError(result.error)).toContain('"platform" is declared more than once');
+	});
+});

package/src/manifest/manifest.ts

@@ -6,6 +6,7 @@ import { GameCategory } from "./category";
 import { type GuideEntry, type GuideTag, guideEntrySchema, guideTagSchema } from "./guide";
 import { IMAGE_NAMESPACE } from "./image";
 import { localizedText } from "./localized";
+import { type ManifestPresence, manifestPresenceSchema } from "./presence";
 import {
 	HOST_RANGE_MAX_SIZE,
 	zAssetPath,
@@ -205,6 +206,24 @@ const duplicateIssues = <Item>(
 	}));
 };
 
+const presenceIssues = (presence: ManifestPresence | undefined): CheckIssue[] => {
+	if (!presence) {
+		return [];
+	}
+
+	return duplicateIssues(
+		presence.fields,
+		(field) => field.key,
+		(index) => [
+			"presence",
+			"fields",
+			index,
+			"key",
+		],
+		(key) => `"${key}" is declared more than once`,
+	);
+};
+
 const hostRangesOverlap = (a: ManifestPort, b: ManifestPort) => {
 	return a.hostRange.min <= b.hostRange.max && b.hostRange.min <= a.hostRange.max;
 };
@@ -355,6 +374,7 @@ export const manifestSchema = z
 		reset: manifestResetSchema.prefault({}),
 		secrets: z.array(manifestSecretSchema).max(16).default([]),
 		files: manifestFilesSchema.prefault({}),
+		presence: manifestPresenceSchema.optional(),
 	})
 	.check((ctx) => {
 		if (ctx.issues.length > 0) {
@@ -410,6 +430,7 @@ export const manifestSchema = z
 				(key) => `"${key}" already has a note`,
 			),
 			...guideIssues(manifest.guideTags, manifest.guides),
+			...presenceIssues(manifest.presence),
 		);
 	});
 

package/src/manifest/presence.ts

@@ -0,0 +1,56 @@
+import { z } from "zod";
+import { localizedText } from "./localized";
+import { zPayloadKey } from "./primitives";
+
+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),
+	inline: z.boolean().default(true),
+});
+
+export type ManifestPresenceField = z.infer<typeof manifestPresenceFieldSchema>;
+
+export const manifestPresenceSchema = z.object({
+	name: zPayloadKey.default("player"),
+	id: zPayloadKey.optional(),
+	avatar: z
+		.string()
+		.max(PRESENCE_AVATAR_LENGTH_LIMIT)
+		.regex(PRESENCE_AVATAR_PATTERN, "must be an https or serverk://avatars/ url template")
+		.optional(),
+	fields: z.array(manifestPresenceFieldSchema).max(PRESENCE_FIELDS_LIMIT).default([]),
+});
+
+export type ManifestPresence = z.infer<typeof manifestPresenceSchema>;
+
+export const PRESENCE_PLACEHOLDER = /\{([A-Za-z_][A-Za-z0-9_]*)\}/g;
+
+export const presencePlaceholders = (template: string): string[] => {
+	PRESENCE_PLACEHOLDER.lastIndex = 0;
+
+	const names: string[] = [];
+
+	let match = PRESENCE_PLACEHOLDER.exec(template);
+
+	while (match) {
+		if (match[1]) {
+			names.push(match[1]);
+		}
+
+		match = PRESENCE_PLACEHOLDER.exec(template);
+	}
+
+	return names;
+};

package/src/manifest/primitives.ts

@@ -26,6 +26,12 @@ export const zEnvKey = z
 	.max(32)
 	.regex(/^[A-Z][A-Z0-9_]*$/, "must be SCREAMING_SNAKE_CASE, starting with a letter");
 
+export const zPayloadKey = z
+	.string()
+	.min(1)
+	.max(64)
+	.regex(/^[A-Za-z_][A-Za-z0-9_]*$/, "must be a valid capture group name, starting with a letter or underscore");
+
 export const zImageReference = z.templateLiteral([
 	`${IMAGE_NAMESPACE}/`,
 	zSlug,