@serverkgg/bridge 0.1.13 → 0.1.15

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.1.13",
+	"version": "0.1.15",
 	"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/rules/package.md

@@ -36,9 +36,12 @@ One Serverk package (a game or a bot runtime) on `@serverkgg/bridge`, with no pi
 - A game declares each tab as `const <name>Tab: Bridge.Tab`, listed in `export const panel: Bridge.Panel`; a bot's panel is the tab `createBotPanel()` from `@serverkgg/bridge/bot` builds. Reusable copy is a `Bridge.Text` constant.
 - Every label, title, help text and message is `{ ar, en }`, Arabic first.
 - A settings form targets `BridgeFormTarget.Settings` and module `settings`, with a one-sentence `help` and `restartHint: true`.
+- A variables-form field may declare `default`, which the form shows and `context.variable` returns while the variable is unset or empty. A default redefines unset, so set the current value on existing servers by hand before their next start.
 - In a game, the roster and moderation tables go on `place: BridgePlace.Players`, metrics on `BridgePlace.Overview`.
 - A setup `Form` step points at an existing panel form by `tab`, `section` and field keys, never redeclaring a field; `Form` and `Open` steps state `required`. A game's setup ends with the `Open` step `invite` targeting `GuideOpenTab.Access`.
 - A preview module that knows the change cannot install answers `blocked: true`, with the reason in `lines`. The panel then shows the lines with a close button only, and the platform refuses the change before it rebuilds anything.
+- A catalog whose items the platform downloads is a `Bridge.SourcedCatalog` declaring `source`, with `provided` naming what the image ships. The platform answers its `search` and `preview`; `install` reads the archive at `workshopArchivePath(appId, id)` from `@serverkgg/bridge/steam`, deletes it, and links an item with `workshopItemPageUrl(id)`.
+- A `Catalog` section may carry `upload` when its module defines `add`, which installs the folder the platform extracted the upload into and returns its entry.
 - `BridgeConfirm.None` runs on the click: reads, downloads, start, stop and restart.
 - `BridgeConfirm.Normal` asks once, for anything the player can come back from: a settings form, a variable flip, a reinstall, a version or type switch, a modpack or mod install, op and deop, kick, ban, whitelist, rotating a password.
 - `BridgeConfirm.Strong` is only for an action with no way back, where no restore point is taken and nothing in the panel brings the state back: deleting a world, save, map or character data, resetting a dimension, a wipe. A protected action takes no restore point.

package/src/catalogs/curseforge.test.ts

@@ -9,6 +9,7 @@ import {
 	type CurseforgeCatalogOptions,
 	type CurseforgeFile,
 	CurseforgeHash,
+	CurseforgeModLoader,
 	CurseforgeReleaseType,
 	CurseforgeSort,
 	CurseforgeSortOrder,
@@ -536,6 +537,51 @@ describe("createCurseforgeCatalog", () => {
 		expect(second.at(-1)).toBe(150);
 	});
 
+	it("posts the mod ids in one sorted body inside the project window and keeps the latest file indexes", async () => {
+		const mod = {
+			id: 238_222,
+			latestFilesIndexes: [
+				{
+					gameVersion: "26.3",
+					fileId: 7_100_200,
+					filename: "jei-26.3-neoforge-31.16.0.90.jar",
+					releaseType: CurseforgeReleaseType.Release,
+					modLoader: CurseforgeModLoader.NeoForge,
+				},
+			],
+		};
+		const { catalog, calls } = catalogContext({
+			result: {
+				data: [
+					mod,
+				],
+			},
+			options: {
+				projectCacheSeconds: 600,
+			},
+		});
+
+		const mods = await catalog.mods([
+			238_222,
+			32_274,
+			238_222,
+		]);
+
+		expect(calls).toHaveLength(1);
+		expect(calls[0]?.url).toBe(`${CURSEFORGE_API}/mods`);
+		expect(calls[0]?.httpMethod).toBe(BridgeHttpMethod.Post);
+		expect(calls[0]?.cacheSeconds).toBe(600);
+		expect(JSON.parse(calls[0]?.body ?? "null")).toEqual({
+			modIds: [
+				32_274,
+				238_222,
+			],
+		});
+		expect(mods).toEqual([
+			mod,
+		] as unknown as typeof mods);
+	});
+
 	it("refuses to work without a key", async () => {
 		const { catalog, calls } = catalogContext({
 			key: null,

package/src/catalogs/curseforge.ts

@@ -51,6 +51,16 @@ export enum CurseforgeReleaseType {
 	Release = 1,
 }
 
+export enum CurseforgeModLoader {
+	Any = 0,
+	Cauldron = 2,
+	Fabric = 4,
+	Forge = 1,
+	LiteLoader = 3,
+	NeoForge = 6,
+	Quilt = 5,
+}
+
 export enum CurseforgeDependency {
 	EmbeddedLibrary = 1,
 	Include = 6,
@@ -85,6 +95,14 @@ export interface CurseforgeCategory {
 	isClass?: boolean | null;
 }
 
+export interface CurseforgeFileIndex {
+	gameVersion: string;
+	fileId: number;
+	filename: string;
+	releaseType: number;
+	modLoader: number | null;
+}
+
 export interface CurseforgeMod {
 	id: number;
 	classId: number | null;
@@ -102,6 +120,8 @@ export interface CurseforgeMod {
 	links: {
 		websiteUrl: string | null;
 	} | null;
+	latestFiles?: CurseforgeFile[];
+	latestFilesIndexes?: CurseforgeFileIndex[];
 }
 
 export interface CurseforgeHashEntry {

package/src/context/bridgeContext.ts

@@ -7,6 +7,7 @@ export interface BridgeServer {
 	cpuPercent: number;
 	running: boolean;
 	readonly publicAddress: string | null;
+	readonly playerAddress: string | null;
 }
 
 export interface BridgePortBlock {

package/src/manifest/extension.ts

@@ -12,6 +12,7 @@ export enum ManifestExtensionSource {
 	CurseForge = "curseforge",
 	Hangar = "hangar",
 	Thunderstore = "thunderstore",
+	Workshop = "workshop",
 }
 
 export const EXTENSIONS_LIMIT = Object.values(ManifestExtensionKind).length;

package/src/manifest/manifest.test.ts

@@ -322,6 +322,24 @@ describe("extensions", () => {
 			expect(rendered).toContain(`"${value}"`);
 		}
 	});
+
+	it("carry the Steam Workshop as a catalog and render it into the JSON schema", () => {
+		const manifest = manifestSchema.parse(
+			withExtensions([
+				{
+					kind: ManifestExtensionKind.Mods,
+					sources: [
+						ManifestExtensionSource.Workshop,
+					],
+				},
+			]),
+		);
+
+		expect(manifest.metadata.extensions[0]?.sources).toEqual([
+			ManifestExtensionSource.Workshop,
+		]);
+		expect(JSON.stringify(buildJsonSchema())).toContain('"workshop"');
+	});
 });
 
 describe("port presentation", () => {

package/src/modules/bridge.ts

@@ -38,7 +38,11 @@ import type {
 	BridgeCatalogPage,
 	BridgeCatalogProvider,
 	BridgeCatalogQuery,
+	BridgeCatalogRelease,
+	BridgeCatalogUpdate,
 } from "../protocol/bridgeCatalog";
+import type { BridgeCatalogSource } from "../protocol/bridgeCatalogSource";
+import { BridgeCatalogSourceKind } from "../protocol/bridgeCatalogSource";
 import type { BridgeCrashReport } from "../protocol/bridgeCrash";
 import type { BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
@@ -57,7 +61,6 @@ import type {
 	BridgeActionsModule,
 	BridgeAnnounceModule,
 	BridgeBackupModule,
-	BridgeCatalogModule,
 	BridgeCollectionModule,
 	BridgeDetailAction,
 	BridgeDetailModule,
@@ -71,9 +74,11 @@ import type {
 	BridgeQueryModule,
 	BridgeRowAction,
 	BridgeSample,
+	BridgeSearchCatalogModule,
 	BridgeServerAction,
 	BridgeSettingsModule,
 	BridgeSetupModule,
+	BridgeSourcedCatalogModule,
 	BridgeTerminalModule,
 } from "./bridgeModule";
 
@@ -85,13 +90,18 @@ export namespace Bridge {
 	export type Announce = BridgeAnnounceModule;
 	export type Availability = BridgeAvailability;
 	export type Backup = BridgeBackupModule;
-	export type Catalog = BridgeCatalogModule;
+	export type Catalog = BridgeSearchCatalogModule;
 	export type CatalogEntry = BridgeCatalogEntry;
 	export type CatalogFacet = BridgeCatalogFacet;
 	export type CatalogHit = BridgeCatalogHit;
 	export type CatalogPage = BridgeCatalogPage;
 	export type CatalogProvider = BridgeCatalogProvider;
 	export type CatalogQuery = BridgeCatalogQuery;
+	export type CatalogRelease = BridgeCatalogRelease;
+	export type CatalogSource = BridgeCatalogSource;
+	export const CatalogSourceKind = BridgeCatalogSourceKind;
+	export type CatalogSourceKind = BridgeCatalogSourceKind;
+	export type CatalogUpdate = BridgeCatalogUpdate;
 	export type Cell = BridgeCell;
 	export type Cells = BridgeCells;
 	export type Collection<Row extends BridgeRow = BridgeRow> = BridgeCollectionModule<Row>;
@@ -140,6 +150,7 @@ export namespace Bridge {
 	export type SetupStep = BridgeSetupStep;
 	export type SetupStepStatus = BridgeSetupStepStatus;
 	export type SetupSummary = BridgeSetupSummary;
+	export type SourcedCatalog = BridgeSourcedCatalogModule;
 	export type Terminal = BridgeTerminalModule;
 	export type TerminalArg = BridgeTerminalArg;
 	export type TerminalCommand = BridgeTerminalCommand;

package/src/modules/bridgeModule.ts

@@ -15,6 +15,7 @@ import type {
 	BridgeCatalogQuery,
 	BridgeCatalogRelease,
 } from "../protocol/bridgeCatalog";
+import type { BridgeCatalogSource } from "../protocol/bridgeCatalogSource";
 import type { BridgeCrashReport } from "../protocol/bridgeCrash";
 import type { BridgeBackupSnapshot, BridgeDescribeResult, BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
@@ -83,6 +84,7 @@ export interface BridgeSetupModule {
 export interface BridgeSample {
 	online: number | null;
 	max: number | null;
+	tick?: number | null;
 }
 
 export interface BridgeQueryModule {
@@ -170,20 +172,34 @@ export interface BridgeDetailModule {
 	actions?: Record<string, BridgeDetailAction>;
 }
 
-export interface BridgeCatalogModule {
+interface BridgeCatalogModuleBase {
 	kind: BridgeKind.Catalog;
 	protectedActions?: string[];
 	pageSize?: number;
-	search(context: BridgeContext, query: BridgeCatalogQuery): Promise<BridgeCatalogPage>;
 	installed(context: BridgeContext): Promise<BridgeCatalogEntry[]>;
-	releases?(context: BridgeContext, id: string): Promise<BridgeCatalogRelease[]>;
-	preview?(context: BridgeContext, id: string, releaseId?: string): Promise<BridgePreview>;
 	install(context: BridgeContext, id: string, releaseId?: string): Promise<BridgeCatalogEntry>;
+	add?(context: BridgeContext, input: string): Promise<BridgeCatalogEntry>;
 	remove(context: BridgeContext, id: string): Promise<void>;
 	toggle?(context: BridgeContext, id: string, enabled: boolean): Promise<void>;
 	unavailable?(context: BridgeContext, entry: BridgeCatalogEntry): Promise<BridgeUnavailable>;
 }
 
+export interface BridgeSearchCatalogModule extends BridgeCatalogModuleBase {
+	source?: never;
+	search(context: BridgeContext, query: BridgeCatalogQuery): Promise<BridgeCatalogPage>;
+	releases?(context: BridgeContext, id: string): Promise<BridgeCatalogRelease[]>;
+	preview?(context: BridgeContext, id: string, releaseId?: string): Promise<BridgePreview>;
+}
+
+export interface BridgeSourcedCatalogModule extends BridgeCatalogModuleBase {
+	source: BridgeCatalogSource;
+	search?: never;
+	releases?: never;
+	preview?: never;
+}
+
+export type BridgeCatalogModule = BridgeSearchCatalogModule | BridgeSourcedCatalogModule;
+
 export type BridgePanelModule =
 	| BridgeActionsModule
 	| BridgeCatalogModule

package/src/panel/bridgePanel.ts

@@ -29,6 +29,7 @@ export interface BridgeField {
 	help?: LocalizedText;
 	warning?: LocalizedText;
 	placeholder?: string;
+	default?: string;
 	min?: number;
 	max?: number;
 	step?: number;
@@ -149,6 +150,7 @@ export interface BridgeCatalogSection {
 	variable?: string;
 	confirm?: BridgeConfirm;
 	confirmText?: LocalizedText;
+	upload?: BridgeSectionUpload;
 	empty?: LocalizedText;
 	visibleWhen?: BridgeVisibleWhen;
 	access?: BridgeAccess;

package/src/protocol/bridgeCatalog.ts

@@ -39,6 +39,11 @@ export interface BridgeCatalogPage {
 	sorts: BridgeCatalogFacet[];
 }
 
+export interface BridgeCatalogUpdate {
+	version: string;
+	releaseId: string;
+}
+
 export interface BridgeCatalogEntry {
 	id: string;
 	provider: string | null;
@@ -52,6 +57,8 @@ export interface BridgeCatalogEntry {
 	pageUrl: string | null;
 	icon: string | null;
 	variables?: Record<string, string> | null;
+	update?: BridgeCatalogUpdate | null;
+	note?: LocalizedText;
 }
 
 export interface BridgeCatalogQuery {

package/src/protocol/bridgeCatalogSource.ts

@@ -0,0 +1,9 @@
+export enum BridgeCatalogSourceKind {
+	Workshop = "workshop",
+}
+
+export interface BridgeCatalogSource {
+	kind: BridgeCatalogSourceKind;
+	appId: number;
+	provided?: string[];
+}

package/src/protocol/bridgeConfig.ts

@@ -6,6 +6,7 @@ export interface BridgeConfig {
 	ports: Record<string, number>;
 	portCounts?: Record<string, number>;
 	publicAddress?: string;
+	playerAddress?: string | null;
 	memoryMb: number;
 	cpuPercent: number;
 	gameUid: number;

package/src/protocol/bridgeFrame.ts

@@ -98,6 +98,7 @@ export interface BridgeStatus {
 export interface BridgeSampleResult {
 	online: number | null;
 	max: number | null;
+	tick?: number | null;
 }
 
 export interface BridgeAnnounceResult {

package/src/protocol/bridgeLimits.ts

@@ -28,6 +28,8 @@ export const BRIDGE_FORM_CLEARS_LIMIT = 8;
 
 export const BRIDGE_UPLOAD_EXTENSIONS_LIMIT = 8;
 
+export const BRIDGE_CATALOG_PROVIDED_LIMIT = 16;
+
 export const BRIDGE_MODULES_LIMIT = 32;
 
 export const BRIDGE_MODULE_ACTIONS_LIMIT = 16;
@@ -52,10 +54,14 @@ export const BRIDGE_OPTION_VALUE_LENGTH_LIMIT = 128;
 
 export const BRIDGE_PLACEHOLDER_LENGTH_LIMIT = 256;
 
+export const BRIDGE_DEFAULT_LENGTH_LIMIT = 256;
+
 export const BRIDGE_STAGING_LENGTH_LIMIT = 128;
 
 export const BRIDGE_EXTENSION_LENGTH_LIMIT = 16;
 
+export const BRIDGE_PROVIDED_NAME_LENGTH_LIMIT = 128;
+
 export const BRIDGE_PATTERN_LENGTH_LIMIT = 256;
 
 export const BRIDGE_SETUP_CODE_LENGTH_LIMIT = 64;

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 { BridgeCatalogSource } from "./bridgeCatalogSource";
 import type { BridgeSetupManifest } from "./bridgeSetup";
 
 export interface BridgeTerminalRuleManifest {
@@ -25,6 +26,7 @@ export interface BridgeModuleManifest {
 	dependsOn: string[];
 	actions: string[];
 	protectedActions?: string[];
+	source?: BridgeCatalogSource;
 }
 
 export interface BridgeManifest {

package/src/protocol/index.ts

@@ -3,6 +3,7 @@ export * from "../panel";
 export * from "../terminal";
 export * from "./bridgeActivity";
 export * from "./bridgeCatalog";
+export * from "./bridgeCatalogSource";
 export * from "./bridgeConfig";
 export * from "./bridgeCrash";
 export * from "./bridgeEgress";

package/src/runtime/bridgeActions.ts

@@ -66,13 +66,15 @@ export const actionsOf = (module: BridgePanelModule): string[] => {
 		}
 
 		case BridgeKind.Catalog: {
+			const sourced = module.source !== undefined;
+
 			return [
-				...(module.releases
+				...(module.releases && !sourced
 					? [
 							BridgeAction.Releases,
 						]
 					: []),
-				...(module.preview
+				...(module.preview || sourced
 					? [
 							BridgeAction.Preview,
 						]
@@ -81,6 +83,11 @@ export const actionsOf = (module: BridgePanelModule): string[] => {
 				BridgeAction.Installed,
 				BridgeAction.Remove,
 				BridgeAction.Search,
+				...(module.add
+					? [
+							BridgeAction.Add,
+						]
+					: []),
 				...(module.toggle
 					? [
 							BridgeAction.Toggle,

package/src/runtime/bridgeConfigReader.test.ts

@@ -68,6 +68,37 @@ describe("parseConfig", () => {
 		});
 	});
 
+	it("reads a file an older agent wrote, with no player address", () => {
+		expect(parseConfig(written()).playerAddress).toBeUndefined();
+	});
+
+	it("reads the player address when the agent wrote it", () => {
+		expect(
+			parseConfig(
+				written({
+					playerAddress: "lobby.srvk.gg",
+				}),
+			).playerAddress,
+		).toBe("lobby.srvk.gg");
+	});
+
+	it("ignores a malformed or empty player address", () => {
+		expect(
+			parseConfig(
+				written({
+					playerAddress: 25_565,
+				}),
+			).playerAddress,
+		).toBeUndefined();
+		expect(
+			parseConfig(
+				written({
+					playerAddress: "",
+				}),
+			).playerAddress,
+		).toBeUndefined();
+	});
+
 	it("still refuses a game that would run as root", () => {
 		expect(() =>
 			parseConfig(

package/src/runtime/bridgeConfigReader.ts

@@ -117,6 +117,7 @@ export const parseConfig = (text: string): BridgeConfig => {
 		ports: numberRecord(source, "ports"),
 		portCounts: optionalNumberRecord(source, "portCounts"),
 		publicAddress: optionalString(source, "publicAddress"),
+		playerAddress: optionalString(source, "playerAddress"),
 		memoryMb: requireNumber(source, "memoryMb"),
 		cpuPercent: requireNumber(source, "cpuPercent"),
 		gameUid: requireNumber(source, "gameUid"),

package/src/runtime/bridgeContext.test.ts

@@ -250,4 +250,57 @@ describe("the context's ports and address", () => {
 
 		expect(context.server.publicAddress).toBe("198.51.100.4");
 	});
+
+	it("hand a driver the address players type", async () => {
+		const boot = configWith({
+			publicAddress: "203.0.113.7",
+			playerAddress: "lobby.srvk.gg",
+		});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context } = contextOf(boot);
+
+		expect(context.server.playerAddress).toBe("lobby.srvk.gg");
+		expect(context.server.publicAddress).toBe("203.0.113.7");
+	});
+
+	it("treat the player address as unknown for a file an older agent wrote", async () => {
+		const boot = configWith({});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context } = contextOf(boot);
+
+		expect(context.server.playerAddress).toBeNull();
+	});
+
+	it("follow a rename and a clear of the player address", async () => {
+		const boot = configWith({
+			playerAddress: "lobby.srvk.gg",
+		});
+
+		await writeFile(path, JSON.stringify(boot));
+
+		const { context, live } = contextOf(boot);
+
+		await writeFile(
+			path,
+			JSON.stringify(
+				configWith({
+					playerAddress: "arena.srvk.gg",
+				}),
+			),
+		);
+
+		live.reload();
+
+		expect(context.server.playerAddress).toBe("arena.srvk.gg");
+
+		await writeFile(path, JSON.stringify(configWith({})));
+
+		live.reload();
+
+		expect(context.server.playerAddress).toBeNull();
+	});
 });

package/src/runtime/bridgeContext.ts

@@ -64,6 +64,9 @@ export const createContext = (
 			get publicAddress() {
 				return live.publicAddress();
 			},
+			get playerAddress() {
+				return live.playerAddress();
+			},
 		},
 
 		variable(key) {