@serverkgg/bridge 0.0.21 → 0.1.2

package/src/bot/botPanel.test.ts

@@ -0,0 +1,246 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeKind, BridgeUserError, type BridgeValues } from "../core";
+import { BridgeLayout, BridgePlace } from "../panel";
+import { bridgePanelSchema } from "../wire";
+import { DEPLOY_MARKER } from "./botDeploy";
+import {
+	BOT_DEPLOY_MODULE,
+	BOT_IDENTITY_MODULE,
+	BOT_IDENTITY_REFRESH_SECONDS,
+	BOT_TAB,
+	BotDeployAction,
+	BotSection,
+	createBotDeployModule,
+	createBotIdentityModule,
+	createBotPanel,
+	deployRequestOf,
+} from "./botPanel";
+
+const SHA = "0123456789abcdef0123456789abcdef01234567";
+
+describe("createBotPanel", () => {
+	test("is one bot tab holding only the identity card on the overview", () => {
+		const tab = createBotPanel();
+
+		expect(tab.id).toBe(BOT_TAB);
+		expect(tab.sections).toHaveLength(1);
+
+		const [identity] = tab.sections;
+
+		expect(identity?.id).toBe(BotSection.Identity);
+		expect(identity?.layout).toBe(BridgeLayout.Detail);
+		expect(identity?.layout === BridgeLayout.Detail && identity.place).toBe(BridgePlace.Overview);
+		expect(identity?.layout === BridgeLayout.Detail && identity.module).toBe(BOT_IDENTITY_MODULE);
+	});
+
+	test("parses through the panel mirror the agent and the api read", () => {
+		expect(
+			bridgePanelSchema.safeParse({
+				tabs: [
+					createBotPanel(),
+				],
+			}).success,
+		).toBe(true);
+	});
+
+	test("names the deploy module the platform invokes", () => {
+		expect(BOT_DEPLOY_MODULE).toBe("botDeploy");
+		expect(Object.values(BotDeployAction).map(String)).toEqual([
+			"redeploy",
+			"reinstall",
+		]);
+	});
+});
+
+describe("deployRequestOf", () => {
+	test("takes the deployment, the pinned ref and the reinstall flag from the invoke values", () => {
+		expect(
+			deployRequestOf(
+				{
+					deployment: "dep_a1b2c3d4",
+					ref: SHA,
+					reinstall: true,
+				},
+				false,
+			),
+		).toEqual({
+			deployment: "dep_a1b2c3d4",
+			ref: SHA,
+			snapshot: null,
+			reinstall: true,
+		});
+	});
+
+	test("treats a bare press as a redeploy of whatever is configured", () => {
+		expect(deployRequestOf({}, false)).toEqual({
+			deployment: null,
+			ref: null,
+			snapshot: null,
+			reinstall: false,
+		});
+		expect(deployRequestOf({}, true).reinstall).toBe(true);
+	});
+
+	test("refuses a short ref, a bad id and a ref beside a snapshot", () => {
+		const refusals: BridgeValues[] = [
+			{
+				ref: "0123456",
+			},
+			{
+				ref: SHA.toUpperCase(),
+			},
+			{
+				deployment: "dep a1",
+			},
+			{
+				snapshot: "../snap",
+			},
+			{
+				ref: SHA,
+				snapshot: "snap_1",
+			},
+			{
+				deployment: 7,
+			},
+		];
+
+		for (const args of refusals) {
+			expect(() => deployRequestOf(args, false)).toThrow(BridgeUserError);
+		}
+	});
+});
+
+describe("the bot modules", () => {
+	test("read the identity while the bot is stopped and refresh it every minute", () => {
+		const read = async () => null;
+
+		expect(createBotIdentityModule(read)).toEqual({
+			kind: BridgeKind.Detail,
+			requiresRunning: false,
+			refreshSeconds: BOT_IDENTITY_REFRESH_SECONDS,
+			read,
+		});
+	});
+
+	const deployContext = (running: boolean, markers: string[] = []) => {
+		const stored = new Map<string, string>(
+			markers.map((marker) => [
+				marker,
+				"{}",
+			]),
+		);
+		let restarts = 0;
+
+		const context = {
+			server: {
+				code: "abc",
+				memoryMb: 512,
+				cpuPercent: 100,
+				running,
+				publicAddress: null,
+			},
+			files: {
+				async write(path: string, content: string) {
+					stored.set(path, content);
+				},
+				async remove(path: string) {
+					stored.delete(path);
+				},
+				async move(from: string, to: string) {
+					stored.set(to, stored.get(from) ?? "");
+					stored.delete(from);
+				},
+				async exists(path: string) {
+					return stored.has(path);
+				},
+				async read(path: string) {
+					return stored.get(path) ?? "";
+				},
+			},
+			log: Object.assign(() => {}, {
+				warn: () => {},
+				error: () => {},
+			}),
+			emit() {},
+			async restart() {
+				restarts += 1;
+			},
+		};
+
+		return {
+			context: context as never,
+			stored,
+			restarts: () => restarts,
+		};
+	};
+
+	test("deploy while the bot is stopped too, so the platform can start the new code", async () => {
+		const module = createBotDeployModule();
+		const { context, stored, restarts } = deployContext(false);
+
+		expect(module.requiresRunning).toBe(false);
+
+		await module.actions[BotDeployAction.Redeploy]?.(context, {
+			deployment: "dep_a1b2c3d4",
+			ref: SHA,
+		});
+
+		expect(JSON.parse(stored.get(DEPLOY_MARKER) ?? "{}")).toMatchObject({
+			deployment: "dep_a1b2c3d4",
+			ref: SHA,
+			reinstall: false,
+		});
+		expect(restarts()).toBe(0);
+	});
+
+	test("reinstall forces the flag and restarts a running bot", async () => {
+		const module = createBotDeployModule();
+		const { context, stored, restarts } = deployContext(true);
+
+		await module.actions[BotDeployAction.Reinstall]?.(context, {});
+
+		expect(JSON.parse(stored.get(DEPLOY_MARKER) ?? "{}")).toMatchObject({
+			reinstall: true,
+		});
+		expect(restarts()).toBe(1);
+	});
+
+	test("refuses a second press while a running bot has not taken the first", async () => {
+		const module = createBotDeployModule();
+		const { context } = deployContext(true, [
+			DEPLOY_MARKER,
+		]);
+
+		await expect(module.actions[BotDeployAction.Redeploy]?.(context, {})).rejects.toThrow(BridgeUserError);
+	});
+
+	test("greys out both deploy buttons with the refusal's words while a running bot has not taken a deploy", async () => {
+		const module = createBotDeployModule();
+		const pending = deployContext(true, [
+			DEPLOY_MARKER,
+		]);
+
+		const unavailable = await module.unavailable?.(pending.context);
+
+		expect(Object.keys(unavailable ?? {}).sort()).toEqual([
+			BotDeployAction.Redeploy,
+			BotDeployAction.Reinstall,
+		]);
+		await expect(module.actions[BotDeployAction.Redeploy]?.(pending.context, {})).rejects.toThrow(
+			unavailable?.[BotDeployAction.Redeploy]?.en,
+		);
+	});
+
+	test("offers both deploy buttons when nothing is pending or the bot is stopped", async () => {
+		const module = createBotDeployModule();
+
+		expect(await module.unavailable?.(deployContext(true).context)).toEqual({});
+		expect(
+			await module.unavailable?.(
+				deployContext(false, [
+					DEPLOY_MARKER,
+				]).context,
+			),
+		).toEqual({});
+	});
+});

package/src/bot/botPanel.ts

@@ -0,0 +1,129 @@
+import type { BridgeContext } from "../context";
+import { BridgeKind, type BridgeUnavailable, BridgeUserError, type BridgeValues, type LocalizedText } from "../core";
+import type { BridgeActionsModule, BridgeDetailModule } from "../modules";
+import { BridgeIcon, BridgeLayout, BridgePlace, type BridgeTab } from "../panel";
+import { type DeployRequest, deployPending, requestDeploy } from "./botDeploy";
+import { DEPLOYMENT_ID_PATTERN, REPO_REF_PATTERN, SNAPSHOT_ID_PATTERN } from "./botVariables";
+
+export const BOT_TAB = "bot";
+
+export enum BotSection {
+	Identity = "identity",
+}
+
+export const BOT_IDENTITY_MODULE = "botIdentity";
+
+export const BOT_DEPLOY_MODULE = "botDeploy";
+
+export enum BotDeployAction {
+	Redeploy = "redeploy",
+	Reinstall = "reinstall",
+}
+
+export const BOT_IDENTITY_REFRESH_SECONDS = 60;
+
+const DEPLOY_PENDING: LocalizedText = {
+	ar: "فيه نشر شغّال الحين. انتظر لين يخلص وجرّب بعدها.",
+	en: "A deploy is already running. Wait for it to finish, then try again.",
+};
+
+const INVALID_DEPLOY: LocalizedText = {
+	ar: "طلب النشر هذا ناقص أو غلط. جرّب النشر من صفحة البوت.",
+	en: "This deploy request is incomplete or malformed. Try deploying from the bot page.",
+};
+
+export const createBotPanel = (): BridgeTab => {
+	return {
+		id: BOT_TAB,
+		icon: BridgeIcon.Command,
+		title: {
+			ar: "البوت",
+			en: "Bot",
+		},
+		sections: [
+			{
+				layout: BridgeLayout.Detail,
+				id: BotSection.Identity,
+				place: BridgePlace.Overview,
+				module: BOT_IDENTITY_MODULE,
+				title: {
+					ar: "بوتك",
+					en: "Your bot",
+				},
+				empty: {
+					ar: "بنعرف بوتك أول ما يشتغل ويسجّل دخوله.",
+					en: "We learn who your bot is once it runs and logs in.",
+				},
+			},
+		],
+	};
+};
+
+export const createBotIdentityModule = (read: BridgeDetailModule["read"]): BridgeDetailModule => {
+	return {
+		kind: BridgeKind.Detail,
+		requiresRunning: false,
+		refreshSeconds: BOT_IDENTITY_REFRESH_SECONDS,
+		read,
+	};
+};
+
+const optionalText = (args: BridgeValues, key: string, pattern: RegExp) => {
+	const value = args[key];
+
+	if (value === undefined || value === null || value === "") {
+		return null;
+	}
+
+	if (typeof value !== "string" || !pattern.test(value)) {
+		throw new BridgeUserError(INVALID_DEPLOY);
+	}
+
+	return value;
+};
+
+export const deployRequestOf = (args: BridgeValues, reinstall: boolean): DeployRequest => {
+	const request: DeployRequest = {
+		deployment: optionalText(args, "deployment", DEPLOYMENT_ID_PATTERN),
+		ref: optionalText(args, "ref", REPO_REF_PATTERN),
+		snapshot: optionalText(args, "snapshot", SNAPSHOT_ID_PATTERN),
+		reinstall: reinstall || args.reinstall === true,
+	};
+
+	if (request.ref !== null && request.snapshot !== null) {
+		throw new BridgeUserError(INVALID_DEPLOY);
+	}
+
+	return request;
+};
+
+const deploy = (reinstall: boolean) => {
+	return async (context: BridgeContext, args: BridgeValues) => {
+		const request = deployRequestOf(args, reinstall);
+
+		if (await deployPending(context)) {
+			throw new BridgeUserError(DEPLOY_PENDING);
+		}
+
+		await requestDeploy(context, request);
+	};
+};
+
+export const createBotDeployModule = (): BridgeActionsModule => {
+	return {
+		kind: BridgeKind.Actions,
+		requiresRunning: false,
+		actions: {
+			[BotDeployAction.Redeploy]: deploy(false),
+			[BotDeployAction.Reinstall]: deploy(true),
+		},
+		async unavailable(context): Promise<BridgeUnavailable> {
+			return (await deployPending(context))
+				? {
+						[BotDeployAction.Redeploy]: DEPLOY_PENDING,
+						[BotDeployAction.Reinstall]: DEPLOY_PENDING,
+					}
+				: {};
+		},
+	};
+};

package/src/bot/botState.test.ts

@@ -0,0 +1,45 @@
+import { describe, expect, test } from "bun:test";
+import { BotDeploymentOutcome, BotDeploymentSource, DEPLOYMENT_STATE_FILE, readDeploymentState } from "./botState";
+
+const filesWith = (content: string | null) => {
+	return {
+		async exists(path: string) {
+			return content !== null && path === DEPLOYMENT_STATE_FILE;
+		},
+		async read() {
+			return content ?? "";
+		},
+	};
+};
+
+describe("readDeploymentState", () => {
+	test("reads what the launcher wrote", async () => {
+		const state = {
+			deployment: "dep_a1b2c3d4",
+			source: BotDeploymentSource.Snapshot,
+			ref: null,
+			commit: "abc1234abc1234abc1234abc1234abc1234abc12",
+			snapshot: "snap_1",
+			outcome: BotDeploymentOutcome.Ready,
+			stage: null,
+			detail: null,
+			finishedAt: "2026-09-27T10:00:00.000Z",
+		};
+
+		expect(await readDeploymentState(filesWith(JSON.stringify(state)))).toEqual(state);
+	});
+
+	test("answers null for a missing, broken or foreign file", async () => {
+		expect(await readDeploymentState(filesWith(null))).toBeNull();
+		expect(await readDeploymentState(filesWith("{"))).toBeNull();
+		expect(
+			await readDeploymentState(
+				filesWith(
+					JSON.stringify({
+						deployment: 1,
+					}),
+				),
+			),
+		).toBeNull();
+	});
+});

package/src/bot/botState.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import type { BridgeFiles } from "../context";
+
+export const BOT_STATE_DIR = ".serverk";
+
+export const DEPLOYMENT_STATE_FILE = `${BOT_STATE_DIR}/deployment.json`;
+
+export enum BotDeploymentSource {
+	Git = "git",
+	Snapshot = "snapshot",
+	Local = "local",
+}
+
+export enum BotDeploymentOutcome {
+	Ready = "ready",
+	Failed = "failed",
+}
+
+export enum BotDeploymentStage {
+	Sync = "sync",
+	Snapshot = "snapshot",
+	Install = "install",
+	Start = "start",
+}
+
+export const botDeploymentStateSchema = z.object({
+	deployment: z.string().nullable(),
+	source: z.enum(BotDeploymentSource),
+	ref: z.string().nullable(),
+	commit: z.string().nullable(),
+	snapshot: z.string().nullable(),
+	outcome: z.enum(BotDeploymentOutcome),
+	stage: z.enum(BotDeploymentStage).nullable(),
+	detail: z.string().nullable(),
+	finishedAt: z.string(),
+});
+
+export type BotDeploymentState = z.infer<typeof botDeploymentStateSchema>;
+
+export const readDeploymentState = async (
+	files: Pick<BridgeFiles, "exists" | "read">,
+): Promise<BotDeploymentState | null> => {
+	if (!(await files.exists(DEPLOYMENT_STATE_FILE))) {
+		return null;
+	}
+
+	try {
+		const parsed = botDeploymentStateSchema.safeParse(JSON.parse(await files.read(DEPLOYMENT_STATE_FILE)));
+
+		return parsed.success ? parsed.data : null;
+	} catch {
+		return null;
+	}
+};

package/src/bot/botTerminal.test.ts

@@ -0,0 +1,79 @@
+import { describe, expect, test } from "bun:test";
+import { BridgeTerminalLevel, type BridgeTerminalRule } from "../terminal";
+import { bridgeTerminalRuleSchema } from "../wire";
+import { LAUNCHER_RULES, NODE_RULES, PYTHON_RULES } from "./botTerminal";
+
+const levelOf = (rules: BridgeTerminalRule[], line: string) => {
+	return rules.find((rule) => rule.match.test(line))?.level ?? null;
+};
+
+describe("the bot terminal rules", () => {
+	test("colour the launcher's own lines, failures as errors", () => {
+		expect(levelOf(LAUNCHER_RULES, "serverk: install failed: npm ci exited 1")).toBe(BridgeTerminalLevel.Error);
+		expect(levelOf(LAUNCHER_RULES, "serverk: start failed: no bot token yet — open Setup")).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(LAUNCHER_RULES, "serverk: bot process starting")).toBe(BridgeTerminalLevel.Info);
+		expect(levelOf(LAUNCHER_RULES, "Logged in as helper#0001")).toBeNull();
+	});
+
+	test("catch node errors, stack frames and warnings", () => {
+		expect(levelOf(NODE_RULES, "TypeError: Cannot read properties of undefined (reading 'id')")).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(NODE_RULES, "DiscordAPIError[50001]: Missing Access")).toBe(BridgeTerminalLevel.Error);
+		expect(levelOf(NODE_RULES, "    at Client.<anonymous> (/home/container/index.js:12:7)")).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(NODE_RULES, "npm error code ERESOLVE")).toBe(BridgeTerminalLevel.Error);
+		expect(levelOf(NODE_RULES, "(node:42) DeprecationWarning: ready is deprecated")).toBe(BridgeTerminalLevel.Warn);
+		expect(levelOf(NODE_RULES, "npm warn deprecated inflight@1.0.6")).toBe(BridgeTerminalLevel.Warn);
+		expect(levelOf(NODE_RULES, "Ready! Logged in as helper")).toBeNull();
+	});
+
+	test("catch python tracebacks, exceptions, log levels and warnings", () => {
+		expect(levelOf(PYTHON_RULES, "Traceback (most recent call last):")).toBe(BridgeTerminalLevel.Error);
+		expect(levelOf(PYTHON_RULES, '  File "/home/container/bot.py", line 3, in <module>')).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(PYTHON_RULES, "discord.errors.LoginFailure: Improper token has been passed.")).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(PYTHON_RULES, "telegram.error.InvalidToken: The token was rejected by the server.")).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(PYTHON_RULES, "ModuleNotFoundError: No module named 'discord'")).toBe(BridgeTerminalLevel.Error);
+		expect(levelOf(PYTHON_RULES, "[2026-09-27 10:00:00] [ERROR   ] discord.client: Ignoring exception")).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(PYTHON_RULES, "2026-09-27 10:00:00,123 - telegram.ext - ERROR - No error handlers")).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(PYTHON_RULES, "ERROR: Could not find a version that satisfies the requirement")).toBe(
+			BridgeTerminalLevel.Error,
+		);
+		expect(levelOf(PYTHON_RULES, "[2026-09-27 10:00:00] [WARNING ] discord.client: PyNaCl is not installed")).toBe(
+			BridgeTerminalLevel.Warn,
+		);
+		expect(levelOf(PYTHON_RULES, "/home/container/bot.py:9: RuntimeWarning: coroutine 'main' was never awaited")).toBe(
+			BridgeTerminalLevel.Warn,
+		);
+		expect(levelOf(PYTHON_RULES, "[2026-09-27 10:00:00] [INFO    ] discord.client: logging in")).toBeNull();
+	});
+
+	test("cross the wire the way the panel reads them", () => {
+		for (const rule of [
+			...LAUNCHER_RULES,
+			...NODE_RULES,
+			...PYTHON_RULES,
+		]) {
+			expect(
+				bridgeTerminalRuleSchema.safeParse({
+					match: rule.match.source,
+					flags: rule.match.flags,
+					level: rule.level,
+				}).success,
+			).toBe(true);
+		}
+	});
+});

package/src/bot/botTerminal.ts

@@ -0,0 +1,62 @@
+import { BridgeTerminalLevel, type BridgeTerminalRule } from "../terminal";
+
+export const LAUNCHER_RULES: BridgeTerminalRule[] = [
+	{
+		match: /^serverk: .* failed/,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^serverk:/,
+		level: BridgeTerminalLevel.Info,
+	},
+];
+
+export const NODE_RULES: BridgeTerminalRule[] = [
+	{
+		match: /^(?:Uncaught )?[A-Z][A-Za-z]*Error\b/,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^\s+at .+:\d+:\d+\)?$/,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^node:internal\//,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^npm (?:ERR!|error)/,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^\(node:\d+\) /,
+		level: BridgeTerminalLevel.Warn,
+	},
+	{
+		match: /^npm (?:WARN|warn)/,
+		level: BridgeTerminalLevel.Warn,
+	},
+];
+
+export const PYTHON_RULES: BridgeTerminalRule[] = [
+	{
+		match: /^Traceback \(most recent call last\):/,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^\s+File ".+", line \d+/,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^(?:[a-z_]\w*\.)*[A-Z]\w*(?:Error|Exception|Failure)\b|^(?:[a-z_]\w*\.)+[A-Z]\w*: /,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^(?:ERROR|CRITICAL):|^\[?\d{4}-\d{2}-\d{2} [\d:,.]+\]? (?:- \S+ - |\[)?(?:ERROR|CRITICAL)\b/,
+		level: BridgeTerminalLevel.Error,
+	},
+	{
+		match: /^WARNING:|^\[?\d{4}-\d{2}-\d{2} [\d:,.]+\]? (?:- \S+ - |\[)?WARNING\b|: [A-Z]\w*Warning: /,
+		level: BridgeTerminalLevel.Warn,
+	},
+];