@serverkgg/bridge 0.0.8 → 0.0.10

package/src/runtime/bridgePending.test.ts

@@ -0,0 +1,148 @@
+import { describe, expect, test } from "bun:test";
+import { BRIDGE_PENDING_FILES_LIMIT, type BridgePendingFile } from "../protocol";
+import type { BridgeLeveledLogger } from "./bridgeLog";
+import { pendingResult, rejectedPending, unsupportedPending } from "./bridgePending";
+
+const file = (id: string): BridgePendingFile => ({
+	id,
+	title: {
+		ar: id,
+		en: id,
+	},
+	fileName: `${id}.jar`,
+	sizeBytes: null,
+	digest: null,
+	sourceUrl: null,
+	note: null,
+});
+
+const files = (count: number) => {
+	return Array.from({
+		length: count,
+	}).map((_entry, index) => file(`file-${index}`));
+};
+
+const recorder = () => {
+	const warnings: string[] = [];
+
+	const onLog: BridgeLeveledLogger = Object.assign(
+		() => {
+			return;
+		},
+		{
+			warn: (message: string) => {
+				warnings.push(message);
+			},
+			error: () => {
+				return;
+			},
+		},
+	);
+
+	return {
+		onLog,
+		warnings,
+	};
+};
+
+describe("unsupportedPending", () => {
+	test("answers the sentinel a driver without a pending module gets", () => {
+		expect(unsupportedPending()).toEqual({
+			supported: false,
+			staging: "",
+			extensions: [],
+			files: [],
+			rejected: null,
+		});
+	});
+});
+
+describe("pendingResult", () => {
+	test("carries the staging path, the extensions and the files the driver listed", () => {
+		const { onLog, warnings } = recorder();
+
+		expect(
+			pendingResult(
+				".serverk-staging/pending-upload",
+				[
+					"jar",
+				],
+				files(2),
+				onLog,
+			),
+		).toEqual({
+			supported: true,
+			staging: ".serverk-staging/pending-upload",
+			extensions: [
+				"jar",
+			],
+			files: files(2),
+			rejected: null,
+		});
+
+		expect(warnings).toEqual([]);
+	});
+
+	test("truncates a list longer than the platform takes and warns instead of throwing", () => {
+		const { onLog, warnings } = recorder();
+
+		const result = pendingResult(
+			".serverk-staging/pending-upload",
+			[
+				"jar",
+			],
+			files(BRIDGE_PENDING_FILES_LIMIT + 5),
+			onLog,
+		);
+
+		expect(result.files).toHaveLength(BRIDGE_PENDING_FILES_LIMIT);
+		expect(result.files.at(0)?.id).toBe("file-0");
+		expect(warnings).toEqual([
+			"pending list truncated",
+		]);
+	});
+});
+
+describe("rejectedPending", () => {
+	test("names every file still pending as what the upload was expected to be", () => {
+		const { onLog } = recorder();
+
+		const result = rejectedPending(
+			pendingResult(
+				".serverk-staging/pending-upload",
+				[
+					"jar",
+				],
+				files(2),
+				onLog,
+			),
+		);
+
+		expect(result.rejected).toEqual({
+			expected: [
+				"file-0.jar",
+				"file-1.jar",
+			],
+		});
+		expect(result.files).toHaveLength(2);
+	});
+
+	test("leaves an empty expectation when the driver has nothing pending left", () => {
+		const { onLog } = recorder();
+
+		expect(
+			rejectedPending(
+				pendingResult(
+					".serverk-staging/pending-upload",
+					[
+						"jar",
+					],
+					[],
+					onLog,
+				),
+			).rejected,
+		).toEqual({
+			expected: [],
+		});
+	});
+});

package/src/runtime/bridgePending.ts

@@ -0,0 +1,43 @@
+import { BRIDGE_PENDING_FILES_LIMIT, type BridgePendingFile, type BridgePendingResult } from "../protocol";
+import type { BridgeLeveledLogger } from "./bridgeLog";
+
+export const unsupportedPending = (): BridgePendingResult => {
+	return {
+		supported: false,
+		staging: "",
+		extensions: [],
+		files: [],
+		rejected: null,
+	};
+};
+
+export const pendingResult = (
+	staging: string,
+	extensions: string[],
+	files: BridgePendingFile[],
+	onLog: BridgeLeveledLogger,
+): BridgePendingResult => {
+	if (files.length > BRIDGE_PENDING_FILES_LIMIT) {
+		onLog.warn("pending list truncated", {
+			files: files.length,
+			limit: BRIDGE_PENDING_FILES_LIMIT,
+		});
+	}
+
+	return {
+		supported: true,
+		staging,
+		extensions,
+		files: files.slice(0, BRIDGE_PENDING_FILES_LIMIT),
+		rejected: null,
+	};
+};
+
+export const rejectedPending = (result: BridgePendingResult): BridgePendingResult => {
+	return {
+		...result,
+		rejected: {
+			expected: result.files.map((file) => file.fileName),
+		},
+	};
+};

package/src/runtime/bridgeRegistry.test.ts

@@ -1,6 +1,6 @@
 import { describe, expect, test } from "bun:test";
 import { tmpdir } from "node:os";
-import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues } from "../core";
+import { BridgeAction, BridgeKind, type BridgeRow, BridgeSetupStepKind, type BridgeValues } from "../core";
 import type { BridgeDriver } from "../modules";
 import { type BridgeConfig, BridgeConfirm, BridgeEventName } from "../protocol";
 import { createContext } from "./bridgeContext";
@@ -62,6 +62,9 @@ const registryFor = (driver: BridgeDriver, variables: Record<string, string> = {
 		onEmit(event, payload) {
 			ring.emit(event, payload);
 		},
+		onSetup() {
+			return;
+		},
 	});
 
 	return createRegistry(driver, context, supervisor, ring);
@@ -426,3 +429,171 @@ describe("preview modules", () => {
 		);
 	});
 });
+
+describe("detail modules", () => {
+	test("lists read and its own action ids in the manifest", () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => null,
+					actions: {
+						update: async () => null,
+					},
+				},
+			},
+		});
+
+		expect(registry.manifest().modules).toEqual([
+			{
+				id: "modpackStatus",
+				kind: BridgeKind.Detail,
+				requiresRunning: false,
+				refreshSeconds: null,
+				pageSize: null,
+				dependsOn: [],
+				actions: [
+					BridgeAction.Read,
+					"update",
+				],
+			},
+		]);
+	});
+
+	test("returns what read answers", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => ({
+						id: "modrinth:abc",
+						title: "Better MC",
+						subtitle: "1.21.1 · NeoForge",
+						description: null,
+						image: null,
+						badges: [],
+						stats: [],
+						links: [],
+						stale: false,
+						actions: [],
+					}),
+				},
+			},
+		});
+
+		expect(await registry.invoke("modpackStatus", BridgeAction.Read)).toMatchObject({
+			id: "modrinth:abc",
+			title: "Better MC",
+		});
+	});
+
+	test("hands the argument bag to an action and returns its outcome", async () => {
+		const received: BridgeValues[] = [];
+
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => null,
+					actions: {
+						update: async (_context, args) => {
+							received.push(args);
+
+							return {
+								variables: {
+									MODPACK: "modrinth:abc:v2",
+								},
+							};
+						},
+					},
+				},
+			},
+		});
+
+		expect(
+			await registry.invoke("modpackStatus", "update", {
+				id: "modrinth:abc",
+			}),
+		).toEqual({
+			variables: {
+				MODPACK: "modrinth:abc:v2",
+			},
+		});
+
+		expect(received).toEqual([
+			{
+				id: "modrinth:abc",
+			},
+		]);
+	});
+
+	test("refuses an action named after a read", () => {
+		expect(() =>
+			registryFor({
+				...baseDriver(),
+				modules: {
+					modpackStatus: {
+						kind: BridgeKind.Detail,
+						read: async () => null,
+						actions: {
+							read: async () => null,
+						},
+					},
+				},
+			}),
+		).toThrow('module "modpackStatus" declares action "read", which is reserved for reads');
+	});
+
+	test("refuses an action the module does not answer", async () => {
+		const registry = registryFor({
+			...baseDriver(),
+			modules: {
+				modpackStatus: {
+					kind: BridgeKind.Detail,
+					read: async () => null,
+				},
+			},
+		});
+
+		await expect(registry.invoke("modpackStatus", "update")).rejects.toThrow(
+			'module "modpackStatus" does not support "update"',
+		);
+	});
+});
+
+describe("the setup singleton", () => {
+	test("rides the manifest as its own block and never joins the panel modules", () => {
+		const steps = [
+			{
+				kind: BridgeSetupStepKind.Driver as const,
+				id: "sign-in",
+				title: {
+					ar: "تسجيل الدخول",
+					en: "Sign in",
+				},
+			},
+		];
+
+		const registry = registryFor({
+			...baseDriver(),
+			setup: {
+				kind: BridgeKind.Setup,
+				steps,
+			},
+		});
+
+		const manifest = registry.manifest();
+
+		expect(manifest.setup).toEqual({
+			steps,
+		});
+		expect(manifest.modules.some((module) => module.kind === BridgeKind.Setup)).toBe(false);
+	});
+
+	test("leaves the manifest block empty for a driver that declares no setup", () => {
+		expect(registryFor(baseDriver()).manifest().setup).toBeNull();
+	});
+});

package/src/runtime/bridgeRegistry.ts

@@ -1,10 +1,11 @@
 import type { BridgeContext } from "../context";
 import { BridgeAction, BridgeKind, type BridgeRow, type BridgeValues, isReadAction } from "../core";
-import type { BridgeDriver, BridgePanelModule, BridgeTerminalModule } from "../modules";
+import type { BridgeDriver, BridgePanelModule, BridgeSetupModule, BridgeTerminalModule } from "../modules";
 import {
 	BRIDGE_VERSION,
 	type BridgeManifest,
 	type BridgeModuleManifest,
+	type BridgeSetupManifest,
 	type BridgeTerminalManifest,
 } from "../protocol";
 import { actionsOf } from "./bridgeActions";
@@ -18,7 +19,11 @@ interface CacheEntry {
 }
 
 const requiresRunning = (module: BridgePanelModule) => {
-	if (module.kind === BridgeKind.Actions || module.kind === BridgeKind.Collection) {
+	if (
+		module.kind === BridgeKind.Actions
+		|| module.kind === BridgeKind.Collection
+		|| module.kind === BridgeKind.Detail
+	) {
 		return module.requiresRunning ?? false;
 	}
 
@@ -26,7 +31,11 @@ const requiresRunning = (module: BridgePanelModule) => {
 };
 
 const refreshOf = (module: BridgePanelModule) => {
-	return module.kind === BridgeKind.Collection ? (module.refreshSeconds ?? null) : null;
+	if (module.kind === BridgeKind.Collection || module.kind === BridgeKind.Detail) {
+		return module.refreshSeconds ?? null;
+	}
+
+	return null;
 };
 
 const dependsOf = (module: BridgePanelModule) => {
@@ -55,6 +64,16 @@ const terminalManifestOf = (module: BridgeTerminalModule | undefined): BridgeTer
 	};
 };
 
+const setupManifestOf = (module: BridgeSetupModule | undefined): BridgeSetupManifest | null => {
+	if (!module) {
+		return null;
+	}
+
+	return {
+		steps: module.steps,
+	};
+};
+
 const withVariables = (context: BridgeContext, overlay: Record<string, string>): BridgeContext => {
 	return {
 		get server() {
@@ -80,6 +99,7 @@ const withVariables = (context: BridgeContext, overlay: Record<string, string>):
 			return context.exec(command, options);
 		},
 		logs: context.logs,
+		setup: context.setup,
 		emit(event, payload) {
 			context.emit(event, payload);
 		},
@@ -138,11 +158,11 @@ export const createRegistry = (
 	const modules = driver.modules ?? {};
 
 	for (const [id, module] of Object.entries(modules)) {
-		if (module.kind !== BridgeKind.Actions) {
+		if (module.kind !== BridgeKind.Actions && module.kind !== BridgeKind.Detail) {
 			continue;
 		}
 
-		for (const action of Object.keys(module.actions)) {
+		for (const action of Object.keys(module.actions ?? {})) {
 			if (isReadAction(action)) {
 				throw new BridgeDriverError(
 					`module "${id}" declares action "${action}", which is reserved for reads — pick another id`,
@@ -290,6 +310,20 @@ export const createRegistry = (
 				break;
 			}
 
+			case BridgeKind.Detail: {
+				if (action === BridgeAction.Read) {
+					return await module.read(context);
+				}
+
+				const detailAction = module.actions?.[action];
+
+				if (detailAction) {
+					return await detailAction(context, args);
+				}
+
+				break;
+			}
+
 			case BridgeKind.Catalog: {
 				if (action === BridgeAction.Search) {
 					return await module.search(context, {
@@ -346,6 +380,7 @@ export const createRegistry = (
 				version: BRIDGE_VERSION,
 				panel: driver.panel ?? null,
 				terminal: terminalManifestOf(driver.terminal),
+				setup: setupManifestOf(driver.setup),
 				modules: entries,
 				events: ring.names(),
 			};

package/src/runtime/bridgeSecrets.test.ts

@@ -0,0 +1,121 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { BridgeConfig } from "../protocol";
+import { createBridgeSecrets } from "./bridgeSecrets";
+
+const configWith = (secrets: Record<string, string>): BridgeConfig => ({
+	code: "wsvv8fakxm",
+	token: "token",
+	cwd: "/data",
+	run: "/run/bridge",
+	ports: {
+		game: 25_565,
+	},
+	memoryMb: 2048,
+	cpuPercent: 100,
+	gameUid: 1000,
+	gameGid: 1000,
+	variables: {
+		VERSION: "1.21",
+	},
+	secrets,
+});
+
+let directory: string;
+
+let path: string;
+
+const write = async (config: BridgeConfig) => {
+	await writeFile(path, `${JSON.stringify(config, null, 2)}\n`);
+};
+
+beforeEach(async () => {
+	directory = await mkdtemp(join(tmpdir(), "bridge-secrets-"));
+	path = join(directory, "config.json");
+});
+
+afterEach(async () => {
+	await rm(directory, {
+		force: true,
+		recursive: true,
+	});
+});
+
+describe("the bridge secrets reader", () => {
+	test("answers from the boot snapshot", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+		expect(secrets.read("MODRINTH_API_KEY")).toBeNull();
+	});
+
+	test("sees a value the agent rewrote into the config", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await write(
+			configWith({
+				CURSEFORGE_API_KEY: "rotated",
+				MODRINTH_API_KEY: "added",
+			}),
+		);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("rotated");
+		expect(secrets.read("MODRINTH_API_KEY")).toBe("added");
+	});
+
+	test("keeps the last good values while the config is mid-write", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 0);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await writeFile(path, '{"code": "wsvv8fak');
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await rm(path);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+	});
+
+	test("re-reads the file at most once per refresh window", async () => {
+		const config = configWith({
+			CURSEFORGE_API_KEY: "boot",
+		});
+
+		await write(config);
+
+		const secrets = createBridgeSecrets(path, config, 60_000);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+
+		await write(
+			configWith({
+				CURSEFORGE_API_KEY: "rotated",
+			}),
+		);
+
+		expect(secrets.read("CURSEFORGE_API_KEY")).toBe("boot");
+	});
+});

package/src/runtime/bridgeSecrets.ts

@@ -0,0 +1,43 @@
+import { readFileSync } from "node:fs";
+import type { BridgeConfig } from "../protocol";
+import { parseConfig } from "./bridgeConfigReader";
+
+export const BRIDGE_SECRET_REFRESH_MS = 2000;
+
+export interface BridgeSecrets {
+	read: (key: string) => string | null;
+}
+
+export const createBridgeSecrets = (
+	path: string,
+	config: BridgeConfig,
+	refreshMs: number = BRIDGE_SECRET_REFRESH_MS,
+): BridgeSecrets => {
+	let values = config.secrets;
+
+	let checkedAt: number | null = null;
+
+	const refresh = () => {
+		const stamp = performance.now();
+
+		if (checkedAt !== null && stamp - checkedAt < refreshMs) {
+			return;
+		}
+
+		checkedAt = stamp;
+
+		try {
+			values = parseConfig(readFileSync(path, "utf8")).secrets;
+		} catch {
+			return;
+		}
+	};
+
+	return {
+		read(key) {
+			refresh();
+
+			return values[key] ?? null;
+		},
+	};
+};