@serverkgg/bridge 0.0.21 → 0.1.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.21",
+	"version": "0.1.1",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
@@ -24,6 +24,8 @@
 		"./blog": "./src/blog/index.ts",
 		"./probes": "./src/probes/index.ts",
 		"./wire": "./src/wire/index.ts",
+		"./bot": "./src/bot/index.ts",
+		"./bot/detect": "./src/bot/detect/index.ts",
 		"./catalogs": "./src/catalogs/index.ts",
 		"./install": "./src/install/index.ts",
 		"./net": "./src/net/index.ts",

package/src/bot/botDeploy.test.ts

@@ -0,0 +1,363 @@
+import { describe, expect, test } from "bun:test";
+import type { BridgeValues } from "../core";
+import { BridgeEventName } from "../protocol";
+import {
+	DEPLOY_MARKER,
+	DEPLOY_MARKER_DRAFT,
+	DEPLOYMENT_EVENT_PATTERN,
+	DEPLOYMENT_LINE,
+	type DeployMarker,
+	deploymentLine,
+	deployPending,
+	requestDeploy,
+} from "./botDeploy";
+import { BotDeploymentOutcome, BotDeploymentSource, BotDeploymentStage, DEPLOYMENT_STATE_FILE } from "./botState";
+
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+
+const deployContext = (running: boolean, files: Record<string, string> = {}) => {
+	const stored = new Map<string, string>(Object.entries(files));
+	const events: string[] = [];
+	const emitted: {
+		event: string;
+		payload: BridgeValues | undefined;
+	}[] = [];
+
+	const log = Object.assign(
+		(message: string) => {
+			events.push(`log ${message}`);
+		},
+		{
+			warn: () => {},
+			error: () => {},
+		},
+	);
+
+	const context = {
+		server: {
+			code: "abc",
+			memoryMb: 512,
+			cpuPercent: 100,
+			running,
+			publicAddress: null,
+		},
+		files: {
+			async write(path: string, content: string) {
+				stored.set(path, content);
+				events.push(`write ${path}`);
+			},
+			async remove(path: string) {
+				stored.delete(path);
+				events.push(`remove ${path}`);
+			},
+			async move(from: string, to: string) {
+				const content = stored.get(from);
+
+				if (content === undefined || stored.has(to)) {
+					throw new Error(`cannot move ${from} to ${to}`);
+				}
+
+				stored.delete(from);
+				stored.set(to, content);
+				events.push(`move ${from} ${to}`);
+			},
+			async exists(path: string) {
+				return stored.has(path);
+			},
+			async read(path: string) {
+				const content = stored.get(path);
+
+				if (content === undefined) {
+					throw new Error(`no ${path}`);
+				}
+
+				return content;
+			},
+		},
+		log,
+		emit(event: string, payload?: BridgeValues) {
+			emitted.push({
+				event,
+				payload,
+			});
+		},
+		async restart() {
+			events.push("restart");
+		},
+	};
+
+	return {
+		context: context as never,
+		stored,
+		events,
+		emitted,
+	};
+};
+
+const markerOf = (stored: Map<string, string>): DeployMarker => {
+	return JSON.parse(stored.get(DEPLOY_MARKER) ?? "null");
+};
+
+const MARKER_WRITE = [
+	`write ${DEPLOY_MARKER_DRAFT}`,
+	`remove ${DEPLOY_MARKER}`,
+	`move ${DEPLOY_MARKER_DRAFT} ${DEPLOY_MARKER}`,
+];
+
+const liveState = (deployment: string, source: BotDeploymentSource = BotDeploymentSource.Git) => {
+	return {
+		[DEPLOYMENT_STATE_FILE]: JSON.stringify({
+			deployment,
+			source,
+			ref: source === BotDeploymentSource.Git ? SHA : null,
+			commit: SHA,
+			snapshot: source === BotDeploymentSource.Snapshot ? "snap_1" : null,
+			outcome: BotDeploymentOutcome.Ready,
+			stage: null,
+			detail: null,
+			finishedAt: "2026-09-27T10:00:00.000Z",
+		}),
+	};
+};
+
+describe("deploymentLine", () => {
+	test("announces a ready deployment with the short commit", () => {
+		expect(
+			deploymentLine({
+				deployment: "dep_a1b2c3d4",
+				outcome: BotDeploymentOutcome.Ready,
+				commit: SHA,
+			}),
+		).toBe("serverk: deployment dep_a1b2c3d4 ready at 0123456789ab");
+	});
+
+	test("announces a ready deployment with no commit for files and snapshots", () => {
+		expect(
+			deploymentLine({
+				deployment: "dep_a1b2c3d4",
+				outcome: BotDeploymentOutcome.Ready,
+				commit: null,
+			}),
+		).toBe("serverk: deployment dep_a1b2c3d4 ready");
+	});
+
+	test("names the stage and one line of detail for a failure", () => {
+		expect(
+			deploymentLine({
+				deployment: "dep_a1b2c3d4",
+				outcome: BotDeploymentOutcome.Failed,
+				stage: BotDeploymentStage.Sync,
+				detail: `fatal: remote error:\n  upload-pack: not our ref ${"x".repeat(300)}`,
+			}),
+		).toBe(
+			`serverk: deployment dep_a1b2c3d4 failed: sync: fatal: remote error: upload-pack: not our ref ${"x".repeat(154)}`,
+		);
+	});
+
+	test("round-trips through the line pattern", () => {
+		const ready = DEPLOYMENT_LINE.exec(
+			deploymentLine({
+				deployment: "dep_a1b2c3d4",
+				outcome: BotDeploymentOutcome.Ready,
+				commit: SHA,
+			}),
+		);
+
+		expect(ready?.groups).toMatchObject({
+			deployment: "dep_a1b2c3d4",
+			outcome: "ready",
+			commit: "0123456789ab",
+		});
+
+		const failed = DEPLOYMENT_LINE.exec(
+			deploymentLine({
+				deployment: "dep_a1b2c3d4",
+				outcome: BotDeploymentOutcome.Failed,
+				stage: BotDeploymentStage.Install,
+				detail: "npm ci exited with code 1",
+			}),
+		);
+
+		expect(failed?.groups).toMatchObject({
+			deployment: "dep_a1b2c3d4",
+			outcome: "failed",
+			stage: "install",
+			detail: "npm ci exited with code 1",
+		});
+	});
+
+	test("cuts the detail at 200 characters, counting an emoji as one the way the Python launcher does", () => {
+		const line = deploymentLine({
+			deployment: "dep_a1b2c3d4",
+			outcome: BotDeploymentOutcome.Failed,
+			stage: BotDeploymentStage.Start,
+			detail: "🤖".repeat(250),
+		});
+
+		expect(line).toBe(`serverk: deployment dep_a1b2c3d4 failed: start: ${"🤖".repeat(200)}`);
+		expect(DEPLOYMENT_LINE.exec(line)?.groups?.detail).toBe("🤖".repeat(200));
+	});
+
+	test("reads only deployment ids of at most 64 characters", () => {
+		expect(DEPLOYMENT_LINE.test(`serverk: deployment ${"d".repeat(64)} ready`)).toBe(true);
+		expect(DEPLOYMENT_LINE.test(`serverk: deployment ${"d".repeat(65)} ready`)).toBe(false);
+	});
+
+	test("is reported as a server update tagged as a deployment", () => {
+		expect(DEPLOYMENT_EVENT_PATTERN.emit).toBe(BridgeEventName.ServerUpdated);
+		expect(DEPLOYMENT_EVENT_PATTERN.payload).toEqual({
+			kind: "deployment",
+		});
+		expect(DEPLOYMENT_EVENT_PATTERN.match.test("serverk: deployment dep_1 ready at abcdef1")).toBe(true);
+		expect(DEPLOYMENT_EVENT_PATTERN.match.test("serverk: bot process starting")).toBe(false);
+	});
+});
+
+describe("requestDeploy", () => {
+	test("writes the request as JSON and restarts a running bot", async () => {
+		const { context, stored, events } = deployContext(true);
+
+		await requestDeploy(context, {
+			deployment: "dep_a1b2c3d4",
+			ref: SHA,
+			snapshot: null,
+			reinstall: false,
+		});
+
+		expect(events).toEqual([
+			...MARKER_WRITE,
+			"log deploy requested, restarting the bot",
+			"restart",
+		]);
+		expect(stored.has(DEPLOY_MARKER_DRAFT)).toBe(false);
+		expect(markerOf(stored)).toMatchObject({
+			deployment: "dep_a1b2c3d4",
+			ref: SHA,
+			snapshot: null,
+			reinstall: false,
+		});
+		expect(Number.isNaN(Date.parse(markerOf(stored).requestedAt))).toBe(false);
+	});
+
+	test("records the request without a restart while the bot is stopped", async () => {
+		const { context, stored, events } = deployContext(false);
+
+		await requestDeploy(context, {
+			deployment: "dep_a1b2c3d4",
+			ref: null,
+			snapshot: "snap_1",
+			reinstall: true,
+		});
+
+		expect(events).toEqual([
+			...MARKER_WRITE,
+			"log deploy recorded, the bot runs it on its next start",
+		]);
+		expect(markerOf(stored)).toMatchObject({
+			snapshot: "snap_1",
+			reinstall: true,
+		});
+	});
+
+	test("does nothing for a deployment that is already live and reports it again", async () => {
+		const { context, stored, events, emitted } = deployContext(true, liveState("dep_a1b2c3d4"));
+
+		await requestDeploy(context, {
+			deployment: "dep_a1b2c3d4",
+			ref: SHA,
+			snapshot: null,
+			reinstall: false,
+		});
+
+		expect(stored.has(DEPLOY_MARKER)).toBe(false);
+		expect(events).toEqual([
+			"log the deployment is already live, nothing to do",
+		]);
+		expect(emitted).toEqual([
+			{
+				event: BridgeEventName.ServerUpdated,
+				payload: {
+					kind: "deployment",
+					deployment: "dep_a1b2c3d4",
+					outcome: "ready",
+					commit: "0123456789ab",
+				},
+			},
+		]);
+	});
+
+	test("reports no commit again for a live deployment of uploaded code", async () => {
+		const { context, emitted } = deployContext(true, liveState("dep_a1b2c3d4", BotDeploymentSource.Snapshot));
+
+		await requestDeploy(context, {
+			deployment: "dep_a1b2c3d4",
+			ref: null,
+			snapshot: "snap_1",
+			reinstall: false,
+		});
+
+		expect(emitted[0]?.payload).toMatchObject({
+			deployment: "dep_a1b2c3d4",
+			commit: null,
+		});
+	});
+
+	test("replaces a request the bot has not taken yet", async () => {
+		const { context, stored } = deployContext(false, {
+			[DEPLOY_MARKER]: "{}",
+		});
+
+		await requestDeploy(context, {
+			deployment: "dep_newer000",
+			ref: SHA,
+			snapshot: null,
+			reinstall: false,
+		});
+
+		expect(markerOf(stored).deployment).toBe("dep_newer000");
+	});
+
+	test("still reinstalls a deployment that is already live", async () => {
+		const { context, events } = deployContext(true, liveState("dep_a1b2c3d4"));
+
+		await requestDeploy(context, {
+			deployment: "dep_a1b2c3d4",
+			ref: SHA,
+			snapshot: null,
+			reinstall: true,
+		});
+
+		expect(events.at(-1)).toBe("restart");
+	});
+
+	test("runs a new deployment when another one is live", async () => {
+		const { context, events } = deployContext(true, liveState("dep_old00000"));
+
+		await requestDeploy(context, {
+			deployment: "dep_new00000",
+			ref: SHA,
+			snapshot: null,
+			reinstall: false,
+		});
+
+		expect(events.at(-1)).toBe("restart");
+	});
+});
+
+describe("deployPending", () => {
+	test("is true only while a running bot has not taken the marker yet", async () => {
+		const running = deployContext(true);
+
+		expect(await deployPending(running.context)).toBe(false);
+
+		running.stored.set(DEPLOY_MARKER, "{}");
+
+		expect(await deployPending(running.context)).toBe(true);
+
+		const stopped = deployContext(false, {
+			[DEPLOY_MARKER]: "{}",
+		});
+
+		expect(await deployPending(stopped.context)).toBe(false);
+	});
+});

package/src/bot/botDeploy.ts

@@ -0,0 +1,136 @@
+import type { BridgeContext } from "../context";
+import type { BridgeValues } from "../core";
+import type { BridgeEventPattern } from "../modules";
+import { BridgeEventName } from "../protocol";
+import {
+	BOT_STATE_DIR,
+	BotDeploymentOutcome,
+	BotDeploymentSource,
+	type BotDeploymentStage,
+	readDeploymentState,
+} from "./botState";
+
+export const DEPLOY_MARKER = `${BOT_STATE_DIR}/deploy-requested`;
+
+export const DEPLOY_MARKER_DRAFT = `${DEPLOY_MARKER}.draft`;
+
+export const DEPLOYMENT_EVENT_KIND = "deployment";
+
+export const DEPLOYMENT_LINE =
+	/^serverk: deployment (?<deployment>\S{1,64}) (?<outcome>ready|failed)(?: at (?<commit>[0-9a-f]{7,64}))?(?:: (?<stage>[a-z-]+): (?<detail>.{1,200}))?$/u;
+
+export const DEPLOYMENT_DETAIL_LIMIT = 200;
+
+export const DEPLOYMENT_COMMIT_LENGTH = 12;
+
+export interface DeployRequest {
+	deployment: string | null;
+	ref: string | null;
+	snapshot: string | null;
+	reinstall: boolean;
+}
+
+export interface DeployMarker extends DeployRequest {
+	requestedAt: string;
+}
+
+export type DeploymentLineInput =
+	| {
+			deployment: string;
+			outcome: BotDeploymentOutcome.Ready;
+			commit: string | null;
+	  }
+	| {
+			deployment: string;
+			outcome: BotDeploymentOutcome.Failed;
+			stage: BotDeploymentStage;
+			detail: string;
+	  };
+
+export const deploymentLine = (input: DeploymentLineInput) => {
+	if (input.outcome === BotDeploymentOutcome.Ready) {
+		const commit = input.commit ? ` at ${input.commit.slice(0, DEPLOYMENT_COMMIT_LENGTH)}` : "";
+
+		return `serverk: deployment ${input.deployment} ready${commit}`;
+	}
+
+	const detail =
+		Array.from(input.detail.replace(/\s+/g, " ").trim()).slice(0, DEPLOYMENT_DETAIL_LIMIT).join("") || "no detail";
+
+	return `serverk: deployment ${input.deployment} failed: ${input.stage}: ${detail}`;
+};
+
+export const DEPLOYMENT_EVENT_PATTERN: BridgeEventPattern = {
+	match: DEPLOYMENT_LINE,
+	emit: BridgeEventName.ServerUpdated,
+	payload: {
+		kind: DEPLOYMENT_EVENT_KIND,
+	},
+};
+
+export const deploymentEvent = (deployment: string, commit: string | null): BridgeValues => {
+	return {
+		kind: DEPLOYMENT_EVENT_KIND,
+		deployment,
+		outcome: BotDeploymentOutcome.Ready,
+		commit: commit ? commit.slice(0, DEPLOYMENT_COMMIT_LENGTH) : null,
+	};
+};
+
+export const deployPending = async (context: Pick<BridgeContext, "files" | "server">) => {
+	return context.server.running && (await context.files.exists(DEPLOY_MARKER));
+};
+
+type DeployContext = Pick<BridgeContext, "files" | "log" | "restart" | "server" | "emit">;
+
+const alreadyLive = async (context: DeployContext, request: DeployRequest) => {
+	if (request.deployment === null || request.reinstall) {
+		return false;
+	}
+
+	const state = await readDeploymentState(context.files);
+
+	if (state?.deployment !== request.deployment || state.outcome !== BotDeploymentOutcome.Ready) {
+		return false;
+	}
+
+	context.log("the deployment is already live, nothing to do", {
+		deployment: request.deployment,
+	});
+
+	context.emit(
+		BridgeEventName.ServerUpdated,
+		deploymentEvent(request.deployment, state.source === BotDeploymentSource.Git ? state.commit : null),
+	);
+
+	return true;
+};
+
+export const requestDeploy = async (context: DeployContext, request: DeployRequest) => {
+	if (await alreadyLive(context, request)) {
+		return;
+	}
+
+	const marker: DeployMarker = {
+		...request,
+		requestedAt: new Date().toISOString(),
+	};
+
+	await context.files.write(DEPLOY_MARKER_DRAFT, `${JSON.stringify(marker)}\n`);
+	await context.files.remove(DEPLOY_MARKER);
+	await context.files.move(DEPLOY_MARKER_DRAFT, DEPLOY_MARKER);
+
+	if (!context.server.running) {
+		context.log("deploy recorded, the bot runs it on its next start", {
+			deployment: request.deployment,
+		});
+
+		return;
+	}
+
+	context.log(request.reinstall ? "reinstall requested, restarting the bot" : "deploy requested, restarting the bot", {
+		deployment: request.deployment,
+	});
+
+	await context.restart();
+};

package/src/bot/botEnvironment.test.ts

@@ -0,0 +1,189 @@
+import { describe, expect, test } from "bun:test";
+import {
+	botProcessEnvironment,
+	customerEnvironment,
+	LAUNCHER_DEPLOYMENT_ID,
+	LAUNCHER_GIT_TOKEN,
+	LAUNCHER_INSTALL_COMMAND,
+	LAUNCHER_KEYS,
+	LAUNCHER_REPO_BRANCH,
+	LAUNCHER_REPO_REF,
+	LAUNCHER_REPO_URL,
+	LAUNCHER_ROOT_DIRECTORY,
+	LAUNCHER_SNAPSHOT_ID,
+	LAUNCHER_START_COMMAND,
+	LAUNCHER_STATE_DIR,
+	launcherEnvironment,
+	platformEnvironment,
+} from "./botEnvironment";
+import { type BotConfig, DEFAULT_REPO_BRANCH } from "./botVariables";
+import { BotPlatform } from "./detect";
+
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+
+const config = (overrides: Partial<BotConfig> = {}): BotConfig => ({
+	platform: null,
+	repo: null,
+	ref: null,
+	branch: DEFAULT_REPO_BRANCH,
+	startCommand: null,
+	installCommand: null,
+	rootDirectory: null,
+	deployment: null,
+	snapshot: null,
+	gitToken: null,
+	...overrides,
+});
+
+describe("customerEnvironment", () => {
+	test("hands the process every vault key and nothing the platform or the runtime owns", () => {
+		expect(
+			customerEnvironment(
+				{
+					MY_VAR: "plain",
+					node_env_lower: "kept",
+					NODE_OPTIONS: "--enable-source-maps",
+					REPO_URL: "https://github.com/you/bot",
+					REPO_REF: SHA,
+					START_COMMAND: "node .",
+					INSTALL_COMMAND: "npm i",
+					DEPLOYMENT_ID: "dep_1",
+					SNAPSHOT_ID: "snap_1",
+					BOT_PLATFORM: "discord",
+					SERVERK_BOT: "0",
+					SERVERK_ANYTHING: "x",
+					PATH: "/evil",
+					HOME: "/tmp",
+					VIRTUAL_ENV: "/tmp/venv",
+					PYTHONUNBUFFERED: "0",
+					TZ: "Asia/Riyadh",
+				},
+				{
+					DISCORD_TOKEN: "sealed-value",
+					GIT_TOKEN: "ghs_installation",
+				},
+			),
+		).toEqual({
+			MY_VAR: "plain",
+			node_env_lower: "kept",
+			NODE_OPTIONS: "--enable-source-maps",
+			DISCORD_TOKEN: "sealed-value",
+		});
+	});
+
+	test("lets a secret win over a plain value under the same key", () => {
+		expect(
+			customerEnvironment(
+				{
+					API_KEY: "plain",
+				},
+				{
+					API_KEY: "sealed",
+				},
+			),
+		).toEqual({
+			API_KEY: "sealed",
+		});
+	});
+});
+
+describe("launcherEnvironment", () => {
+	test("maps the platform-owned keys onto the launcher internals", () => {
+		expect(
+			launcherEnvironment(
+				config({
+					repo: "https://github.com/you/bot",
+					ref: SHA,
+					branch: "dev",
+					gitToken: "ghs_installation",
+					startCommand: "node .",
+					installCommand: "npm install --legacy-peer-deps",
+					rootDirectory: "apps/bot",
+					deployment: "dep_a1b2c3d4",
+				}),
+				"/home/container/.serverk",
+			),
+		).toEqual({
+			[LAUNCHER_STATE_DIR]: "/home/container/.serverk",
+			[LAUNCHER_REPO_URL]: "https://github.com/you/bot",
+			[LAUNCHER_REPO_REF]: SHA,
+			[LAUNCHER_REPO_BRANCH]: "dev",
+			[LAUNCHER_GIT_TOKEN]: "ghs_installation",
+			[LAUNCHER_START_COMMAND]: "node .",
+			[LAUNCHER_INSTALL_COMMAND]: "npm install --legacy-peer-deps",
+			[LAUNCHER_ROOT_DIRECTORY]: "apps/bot",
+			[LAUNCHER_DEPLOYMENT_ID]: "dep_a1b2c3d4",
+		});
+	});
+
+	test("keeps the git keys out when no repository is linked", () => {
+		expect(
+			launcherEnvironment(
+				config({
+					ref: SHA,
+					gitToken: "ghs_installation",
+					snapshot: "snap_1",
+				}),
+				"/state",
+			),
+		).toEqual({
+			[LAUNCHER_STATE_DIR]: "/state",
+			[LAUNCHER_SNAPSHOT_ID]: "snap_1",
+		});
+	});
+
+	test("owns only SERVERK_ names the launcher strips before the bot starts", () => {
+		expect(LAUNCHER_KEYS.every((key) => key.startsWith("SERVERK_"))).toBe(true);
+		expect(LAUNCHER_KEYS).toContain(LAUNCHER_REPO_REF);
+		expect(LAUNCHER_KEYS).toContain(LAUNCHER_INSTALL_COMMAND);
+		expect(LAUNCHER_KEYS).toContain(LAUNCHER_ROOT_DIRECTORY);
+	});
+});
+
+describe("platformEnvironment", () => {
+	test("marks the process as a Serverk bot and names the platform when known", () => {
+		expect(platformEnvironment("abc", BotPlatform.Discord)).toEqual({
+			SERVERK_BOT: "1",
+			SERVERK_SERVER_CODE: "abc",
+			BOT_PLATFORM: BotPlatform.Discord,
+		});
+		expect(platformEnvironment("abc", null)).toEqual({
+			SERVERK_BOT: "1",
+			SERVERK_SERVER_CODE: "abc",
+		});
+	});
+});
+
+describe("botProcessEnvironment", () => {
+	test("layers tool defaults under the customer, then the launcher and the platform", () => {
+		expect(
+			botProcessEnvironment({
+				tool: {
+					TZ: "UTC",
+					HOME: "/home/container",
+					NODE_OPTIONS: "--max-old-space-size=384",
+					[LAUNCHER_STATE_DIR]: "/home/container/.serverk",
+				},
+				customer: {
+					NODE_OPTIONS: "--enable-source-maps",
+					MY_VAR: "1",
+				},
+				launcher: {
+					[LAUNCHER_STATE_DIR]: "/state",
+					[LAUNCHER_DEPLOYMENT_ID]: "dep_1",
+				},
+				platform: platformEnvironment("abc", BotPlatform.Telegram),
+			}),
+		).toEqual({
+			TZ: "UTC",
+			HOME: "/home/container",
+			NODE_OPTIONS: "--enable-source-maps",
+			MY_VAR: "1",
+			[LAUNCHER_STATE_DIR]: "/state",
+			[LAUNCHER_DEPLOYMENT_ID]: "dep_1",
+			SERVERK_BOT: "1",
+			SERVERK_SERVER_CODE: "abc",
+			BOT_PLATFORM: BotPlatform.Telegram,
+		});
+	});
+});