@serverkgg/bridge 0.0.8 → 0.0.9

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.9",
+	"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,7 @@ 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"}`);
 	reportEvents(driver);
 	reportActionTargets(driver);
 };

package/src/context/bridgeContext.ts

@@ -1,4 +1,5 @@
 import type { BridgeStream, BridgeValues } from "../core";
+import type { BridgeHttpMethod } 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;

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,11 +4,13 @@ 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",

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/index.ts

@@ -1,5 +1,7 @@
 export * from "./bridgeAction";
+export * from "./bridgeDownloadError";
 export * from "./bridgeFailure";
+export * from "./bridgeHold";
 export * from "./bridgeId";
 export * from "./bridgeKind";
 export * from "./bridgeNetError";
@@ -7,4 +9,5 @@ export * from "./bridgePort";
 export * from "./bridgeRuntime";
 export * from "./bridgeSecretError";
 export * from "./bridgeStream";
+export * from "./bridgeUserError";
 export * from "./bridgeValue";

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

@@ -586,3 +586,88 @@ 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("refuses an avatar template that is not https", () => {
+		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 url template");
+	});
+
+	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,48 @@
+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 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(/^https:\/\//, "must be an https 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,

package/src/modules/bridge.ts

@@ -1,6 +1,29 @@
 import type { BridgeContext, BridgeExecResult, BridgeFileEntry, BridgeReply } from "../context";
-import type { BridgeOption, BridgeRow, BridgeValue, BridgeValues, LocalizedText } from "../core";
-import type { BridgeField, BridgePanel, BridgeSection, BridgeSectionAction, BridgeTab } from "../panel";
+import type {
+	BridgeInstallHold,
+	BridgeInstallOutcome,
+	BridgeOption,
+	BridgeRow,
+	BridgeValue,
+	BridgeValues,
+	LocalizedText,
+} from "../core";
+import { BridgeUserError } from "../core";
+import type {
+	BridgeDetail,
+	BridgeDetailBadge,
+	BridgeDetailLink,
+	BridgeDetailOutcome,
+	BridgeDetailStat,
+	BridgeField,
+	BridgeFormClear,
+	BridgePanel,
+	BridgeSection,
+	BridgeSectionAction,
+	BridgeTab,
+	BridgeTabRef,
+	BridgeUploadMode,
+} from "../panel";
 import type {
 	BridgeCatalogEntry,
 	BridgeCatalogFacet,
@@ -9,6 +32,7 @@ import type {
 	BridgeCatalogProvider,
 	BridgeCatalogQuery,
 } from "../protocol/bridgeCatalog";
+import type { BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
 import type { BridgeTerminalArg, BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
 import type { BridgeDriver } from "./bridgeDriver";
@@ -18,11 +42,14 @@ import type {
 	BridgeBackupModule,
 	BridgeCatalogModule,
 	BridgeCollectionModule,
+	BridgeDetailAction,
+	BridgeDetailModule,
 	BridgeEventPattern,
 	BridgeEventsModule,
 	BridgeInstallModule,
 	BridgeLifecycleModule,
 	BridgeOptionsModule,
+	BridgePendingModule,
 	BridgePreviewModule,
 	BridgeQueryModule,
 	BridgeRowAction,
@@ -45,17 +72,29 @@ export namespace Bridge {
 	export type CatalogQuery = BridgeCatalogQuery;
 	export type Collection<Row extends BridgeRow = BridgeRow> = BridgeCollectionModule<Row>;
 	export type Context = BridgeContext;
+	export type Detail = BridgeDetailModule;
+	export type DetailAction = BridgeDetailAction;
+	export type DetailBadge = BridgeDetailBadge;
+	export type DetailLink = BridgeDetailLink;
+	export type DetailOutcome = BridgeDetailOutcome;
+	export type DetailResult = BridgeDetail;
+	export type DetailStat = BridgeDetailStat;
 	export type Driver = BridgeDriver;
 	export type EventPattern = BridgeEventPattern;
 	export type Events = BridgeEventsModule;
 	export type ExecResult = BridgeExecResult;
 	export type Field = BridgeField;
 	export type FileEntry = BridgeFileEntry;
+	export type FormClear = BridgeFormClear;
 	export type Install = BridgeInstallModule;
+	export type InstallHold = BridgeInstallHold;
+	export type InstallOutcome = BridgeInstallOutcome;
 	export type Lifecycle = BridgeLifecycleModule;
 	export type Option = BridgeOption;
 	export type Options = BridgeOptionsModule;
 	export type Panel = BridgePanel;
+	export type Pending = BridgePendingModule;
+	export type PendingFile = BridgePendingFile;
 	export type Preview = BridgePreviewModule;
 	export type PreviewResult = BridgePreview;
 	export type Query = BridgeQueryModule;
@@ -72,6 +111,10 @@ export namespace Bridge {
 	export type TerminalCommand = BridgeTerminalCommand;
 	export type TerminalRule = BridgeTerminalRule;
 	export type Tab = BridgeTab;
+	export type TabRef = BridgeTabRef;
+	export type UploadMode = BridgeUploadMode;
+	export const UserError = BridgeUserError;
+	export type UserError = BridgeUserError;
 	export type Text = LocalizedText;
 	export type Value = BridgeValue;
 	export type Values = BridgeValues;

package/src/modules/bridgeDriver.ts

@@ -6,6 +6,7 @@ import type {
 	BridgeInstallModule,
 	BridgeLifecycleModule,
 	BridgePanelModule,
+	BridgePendingModule,
 	BridgeQueryModule,
 	BridgeTerminalModule,
 } from "./bridgeModule";
@@ -17,6 +18,7 @@ export interface BridgeDriver {
 	query?: BridgeQueryModule;
 	backup?: BridgeBackupModule;
 	announce?: BridgeAnnounceModule;
+	pending?: BridgePendingModule;
 	terminal?: BridgeTerminalModule;
 	panel?: BridgePanel;
 	modules?: Record<string, BridgePanelModule>;

package/src/modules/bridgeModule.ts

@@ -1,7 +1,8 @@
 import type { BridgeContext } from "../context";
-import type { BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
+import type { BridgeInstallOutcome, BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
+import type { BridgeDetail, BridgeDetailOutcome } from "../panel";
 import type { BridgeCatalogEntry, BridgeCatalogPage, BridgeCatalogQuery } from "../protocol/bridgeCatalog";
-import type { BridgeDescribeResult } from "../protocol/bridgeFrame";
+import type { BridgeDescribeResult, BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
 import type { BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
 
@@ -9,7 +10,7 @@ export type BridgeDescription = Omit<BridgeDescribeResult, "supported">;
 
 export interface BridgeInstallModule {
 	kind: BridgeKind.Install;
-	run(context: BridgeContext): Promise<void>;
+	run(context: BridgeContext): Promise<BridgeInstallOutcome | undefined>;
 	describe?(context: BridgeContext): Promise<BridgeDescription>;
 }
 
@@ -34,6 +35,14 @@ export interface BridgeBackupModule {
 	release?(context: BridgeContext): Promise<void>;
 }
 
+export interface BridgePendingModule {
+	kind: BridgeKind.Pending;
+	staging: string;
+	extensions: string[];
+	list(context: BridgeContext): Promise<BridgePendingFile[]>;
+	add(context: BridgeContext, input: string): Promise<void>;
+}
+
 export interface BridgeSample {
 	online: number | null;
 	max: number | null;
@@ -49,6 +58,7 @@ export interface BridgeEventPattern {
 	match: RegExp;
 	emit: string;
 	stream?: BridgeStream;
+	payload?: BridgeValues;
 }
 
 export interface BridgeEventsModule {
@@ -104,6 +114,16 @@ export interface BridgeCollectionModule<Row extends BridgeRow = BridgeRow> {
 	actions?: Record<string, BridgeRowAction<Row>>;
 }
 
+export type BridgeDetailAction = (context: BridgeContext, args: BridgeValues) => Promise<BridgeDetailOutcome | null>;
+
+export interface BridgeDetailModule {
+	kind: BridgeKind.Detail;
+	requiresRunning?: boolean;
+	refreshSeconds?: number;
+	read(context: BridgeContext): Promise<BridgeDetail | null>;
+	actions?: Record<string, BridgeDetailAction>;
+}
+
 export interface BridgeCatalogModule {
 	kind: BridgeKind.Catalog;
 	pageSize?: number;
@@ -118,6 +138,7 @@ export type BridgePanelModule =
 	| BridgeActionsModule
 	| BridgeCatalogModule
 	| BridgeCollectionModule
+	| BridgeDetailModule
 	| BridgeOptionsModule
 	| BridgePreviewModule
 	| BridgeSettingsModule;
@@ -130,4 +151,5 @@ export type BridgeModule =
 	| BridgeInstallModule
 	| BridgeLifecycleModule
 	| BridgePanelModule
+	| BridgePendingModule
 	| BridgeQueryModule;

package/src/panel/bridgeDetail.ts

@@ -0,0 +1,49 @@
+import type { BridgeValue, LocalizedText } from "../core";
+
+export enum BridgeDetailTone {
+	Neutral = "neutral",
+	Success = "success",
+	Warning = "warning",
+	Danger = "danger",
+}
+
+export enum BridgeDetailFormat {
+	Bytes = "bytes",
+	Date = "date",
+	Number = "number",
+	Text = "text",
+}
+
+export interface BridgeDetailBadge {
+	label: LocalizedText;
+	tone: BridgeDetailTone;
+}
+
+export interface BridgeDetailStat {
+	key: string;
+	label: LocalizedText;
+	value: BridgeValue;
+	format: BridgeDetailFormat;
+}
+
+export interface BridgeDetailLink {
+	label: LocalizedText;
+	url: string;
+}
+
+export interface BridgeDetail {
+	id: string;
+	title: string;
+	subtitle: string | null;
+	description: string | null;
+	image: string | null;
+	badges: BridgeDetailBadge[];
+	stats: BridgeDetailStat[];
+	links: BridgeDetailLink[];
+	stale: boolean;
+	actions: string[];
+}
+
+export interface BridgeDetailOutcome {
+	variables: Record<string, string> | null;
+}

package/src/panel/bridgeLayout.ts

@@ -2,6 +2,7 @@ export enum BridgeLayout {
 	Actions = "actions",
 	Cards = "cards",
 	Catalog = "catalog",
+	Detail = "detail",
 	Form = "form",
 	Table = "table",
 }

package/src/panel/bridgePanel.ts

@@ -5,6 +5,7 @@ import type { BridgeControl } from "./bridgeControl";
 import type { BridgeFormTarget } from "./bridgeFormTarget";
 import type { BridgeIcon } from "./bridgeIcon";
 import type { BridgeLayout } from "./bridgeLayout";
+import type { BridgeUploadMode } from "./bridgeUploadMode";
 
 export interface BridgeVisibleWhen {
 	variable: string;
@@ -44,6 +45,16 @@ export interface BridgeSectionAction {
 	fields?: BridgeField[];
 }
 
+export interface BridgeTabRef {
+	tab: string;
+	label: LocalizedText;
+}
+
+export interface BridgeFormClear {
+	variable: string;
+	warning: LocalizedText;
+}
+
 export interface BridgeSectionAdd {
 	label: LocalizedText;
 	placeholder?: string;
@@ -53,6 +64,7 @@ export interface BridgeSectionUpload {
 	label: LocalizedText;
 	extensions: string[];
 	staging: string;
+	mode?: BridgeUploadMode;
 }
 
 export interface BridgeActionsSection {
@@ -78,6 +90,7 @@ export interface BridgeFormSection {
 	confirm?: BridgeConfirm;
 	confirmText?: LocalizedText;
 	fields: BridgeField[];
+	clears?: BridgeFormClear[];
 	visibleWhen?: BridgeVisibleWhen;
 	access?: BridgeAccess;
 }
@@ -130,10 +143,27 @@ export interface BridgeCatalogSection {
 	access?: BridgeAccess;
 }
 
+export interface BridgeDetailSection {
+	layout: BridgeLayout.Detail;
+	id: string;
+	title?: LocalizedText;
+	module: string;
+	actions?: BridgeSectionAction[];
+	reinstall?: boolean;
+	variable?: string;
+	confirm?: BridgeConfirm;
+	confirmText?: LocalizedText;
+	related?: BridgeTabRef;
+	empty?: LocalizedText;
+	visibleWhen?: BridgeVisibleWhen;
+	access?: BridgeAccess;
+}
+
 export type BridgeSection =
 	| BridgeActionsSection
 	| BridgeCardsSection
 	| BridgeCatalogSection
+	| BridgeDetailSection
 	| BridgeFormSection
 	| BridgeTableSection;