@serverkgg/bridge 0.1.4 → 0.1.6

package/src/bot/detect/detectTable.ts

@@ -9,7 +9,7 @@ import {
 	SERVERK_JSON_EXAMPLE_LENGTH_LIMIT,
 } from "./serverkJson";
 
-export const DETECT_TABLE_VERSION = 1;
+export const DETECT_TABLE_VERSION = 2;
 
 export const DETECT_TABLE_FILE = "image/detect.json";
 
@@ -18,6 +18,13 @@ export interface DetectLockfile {
 	manager: string;
 }
 
+export interface DetectVersionFile {
+	file: string;
+	tool?: string;
+	prefix?: string;
+	key?: string;
+}
+
 export interface DetectProcfile {
 	file: string;
 	line: string;
@@ -38,16 +45,28 @@ export interface ServerkJsonDetectTable {
 
 export interface NodeDetectTable {
 	manifest: string;
+	managerField: string;
+	berryFile: string;
+	enginesKey: string;
+	buildScript: string;
 	startFiles: string[];
 	lockfiles: DetectLockfile[];
-	installCommands: Record<string, string[]>;
-	unlockedManager: string;
+	installCommands: {
+		locked: Record<string, string[]>;
+		unlocked: Record<string, string[]>;
+	};
+	runCommands: Record<string, string[]>;
+	versionFiles: DetectVersionFile[];
+	defaultVersion: string;
 }
 
 export interface PythonDetectTable {
 	startFiles: string[];
 	manifests: DetectLockfile[];
-	installArguments: Record<string, string[]>;
+	installCommands: Record<string, string[]>;
+	unhonouredManagers: string[];
+	versionFiles: DetectVersionFile[];
+	defaultVersion: string;
 }
 
 export interface DetectTable {
@@ -81,6 +100,10 @@ export const DETECT_TABLE: DetectTable = {
 	},
 	node: {
 		manifest: "package.json",
+		managerField: "packageManager",
+		berryFile: ".yarnrc.yml",
+		enginesKey: "node",
+		buildScript: "build",
 		startFiles: [
 			"index.js",
 			"src/index.js",
@@ -90,44 +113,125 @@ export const DETECT_TABLE: DetectTable = {
 		],
 		lockfiles: [
 			{
-				file: "package-lock.json",
-				manager: "npm",
+				file: "pnpm-lock.yaml",
+				manager: "pnpm",
 			},
 			{
-				file: "npm-shrinkwrap.json",
-				manager: "npm",
+				file: "bun.lock",
+				manager: "bun",
 			},
 			{
-				file: "pnpm-lock.yaml",
-				manager: "pnpm",
+				file: "bun.lockb",
+				manager: "bun",
 			},
 			{
 				file: "yarn.lock",
 				manager: "yarn",
 			},
+			{
+				file: "package-lock.json",
+				manager: "npm",
+			},
+			{
+				file: "npm-shrinkwrap.json",
+				manager: "npm",
+			},
 		],
 		installCommands: {
+			locked: {
+				npm: [
+					"npm",
+					"ci",
+				],
+				pnpm: [
+					"corepack",
+					"pnpm",
+					"install",
+					"--frozen-lockfile",
+				],
+				yarn: [
+					"corepack",
+					"yarn",
+					"install",
+					"--frozen-lockfile",
+				],
+				"yarn-berry": [
+					"corepack",
+					"yarn",
+					"install",
+					"--immutable",
+				],
+				bun: [
+					"bun",
+					"install",
+					"--frozen-lockfile",
+				],
+			},
+			unlocked: {
+				npm: [
+					"npm",
+					"install",
+				],
+				pnpm: [
+					"corepack",
+					"pnpm",
+					"install",
+				],
+				yarn: [
+					"corepack",
+					"yarn",
+					"install",
+				],
+				"yarn-berry": [
+					"corepack",
+					"yarn",
+					"install",
+					"--no-immutable",
+				],
+				bun: [
+					"bun",
+					"install",
+				],
+			},
+		},
+		runCommands: {
 			npm: [
 				"npm",
-				"ci",
+				"run",
 			],
 			pnpm: [
 				"corepack",
 				"pnpm",
-				"install",
-				"--frozen-lockfile",
+				"run",
 			],
 			yarn: [
 				"corepack",
 				"yarn",
-				"install",
+				"run",
 			],
-			"npm-install": [
-				"npm",
-				"install",
+			"yarn-berry": [
+				"corepack",
+				"yarn",
+				"run",
+			],
+			bun: [
+				"bun",
+				"run",
 			],
 		},
-		unlockedManager: "npm-install",
+		versionFiles: [
+			{
+				file: ".nvmrc",
+			},
+			{
+				file: ".node-version",
+			},
+			{
+				file: ".tool-versions",
+				tool: "nodejs",
+			},
+		],
+		defaultVersion: "24",
 	},
 	python: {
 		startFiles: [
@@ -142,22 +246,86 @@ export const DETECT_TABLE: DetectTable = {
 				file: "requirements.txt",
 				manager: "requirements",
 			},
+			{
+				file: "uv.lock",
+				manager: "uv",
+			},
+			{
+				file: "poetry.lock",
+				manager: "poetry",
+			},
+			{
+				file: "pdm.lock",
+				manager: "pdm",
+			},
+			{
+				file: "Pipfile",
+				manager: "pipenv",
+			},
 			{
 				file: "pyproject.toml",
 				manager: "project",
 			},
 		],
-		installArguments: {
+		installCommands: {
 			requirements: [
+				"uv",
+				"pip",
 				"install",
 				"-r",
 				"requirements.txt",
 			],
+			uv: [
+				"uv",
+				"sync",
+				"--locked",
+				"--no-dev",
+			],
+			poetry: [
+				"uv",
+				"pip",
+				"install",
+				".",
+			],
+			pdm: [
+				"uv",
+				"pip",
+				"install",
+				".",
+			],
+			pipenv: [
+				"pipenv",
+				"install",
+			],
 			project: [
+				"uv",
+				"pip",
 				"install",
 				".",
 			],
 		},
+		unhonouredManagers: [
+			"poetry",
+			"pdm",
+		],
+		versionFiles: [
+			{
+				file: ".python-version",
+			},
+			{
+				file: "runtime.txt",
+				prefix: "python-",
+			},
+			{
+				file: "Pipfile",
+				key: "python_version",
+			},
+			{
+				file: ".tool-versions",
+				tool: "python",
+			},
+		],
+		defaultVersion: "3.12",
 	},
 };
 

package/src/bot/detect/detectedVersion.ts

@@ -0,0 +1,5 @@
+export const DETECTED_VERSION_PATTERN = /^\d+(?:\.\d+)?$/;
+
+export const isDetectedVersion = (value: string | null): value is string => {
+	return value !== null && DETECTED_VERSION_PATTERN.test(value);
+};

package/src/bot/detect/envExample.test.ts

@@ -1,5 +1,5 @@
 import { describe, expect, it } from "bun:test";
-import { parseEnvExample } from "./envExample";
+import { isSecretEnvFile, parseEnvExample } from "./envExample";
 
 describe("parseEnvExample", () => {
 	it("reads keys and example values the way dotenv files write them", () => {
@@ -27,3 +27,57 @@ describe("parseEnvExample", () => {
 		]);
 	});
 });
+
+describe("isSecretEnvFile", () => {
+	const CASES: readonly {
+		name: string;
+		secret: boolean;
+	}[] = [
+		{
+			name: ".env",
+			secret: true,
+		},
+		{
+			name: ".env.local",
+			secret: true,
+		},
+		{
+			name: ".env.production",
+			secret: true,
+		},
+		{
+			name: ".env.example",
+			secret: false,
+		},
+		{
+			name: ".env.sample",
+			secret: false,
+		},
+		{
+			name: ".env.template",
+			secret: false,
+		},
+		{
+			name: ".env.dist",
+			secret: false,
+		},
+		{
+			name: ".env.defaults",
+			secret: false,
+		},
+		{
+			name: "env.py",
+			secret: false,
+		},
+		{
+			name: ".envrc",
+			secret: false,
+		},
+	];
+
+	for (const item of CASES) {
+		it(`${item.secret ? "holds values" : "holds no values"} in ${item.name}`, () => {
+			expect(isSecretEnvFile(item.name)).toBe(item.secret);
+		});
+	}
+});

package/src/bot/detect/envExample.ts

@@ -6,6 +6,16 @@ export const ENV_EXAMPLE_FILES: readonly string[] = [
 	".env.template",
 ];
 
+const ENV_TEMPLATE_FILES: ReadonlySet<string> = new Set([
+	...ENV_EXAMPLE_FILES,
+	".env.dist",
+	".env.defaults",
+]);
+
+export const ENV_FILE = ".env";
+
+const ENV_FILE_NAME = /^\.env(?:\..+)?$/;
+
 export interface EnvExampleEntry {
 	key: string;
 	value: string;
@@ -46,3 +56,7 @@ export const parseEnvExample = (text: string): EnvExampleEntry[] => {
 
 	return entries;
 };
+
+export const isSecretEnvFile = (name: string) => {
+	return ENV_FILE_NAME.test(name) && !ENV_TEMPLATE_FILES.has(name);
+};

package/src/bot/detect/index.ts

@@ -6,6 +6,7 @@ export * from "./botPlatform";
 export * from "./botRuntime";
 export * from "./botToken";
 export * from "./detect";
+export * from "./detectedVersion";
 export * from "./detectResult";
 export * from "./detectTable";
 export * from "./envExample";

package/src/bot/detect/keys.test.ts

@@ -1,5 +1,12 @@
 import { describe, expect, it } from "bun:test";
-import { BOT_PLATFORM_KEYS, BOT_PLATFORM_SECRET_KEYS, BOT_PROTECTED_KEYS, isReservedBotKey } from "./keys";
+import {
+	BOT_AMBIENT_KEYS,
+	BOT_PLATFORM_KEYS,
+	BOT_PLATFORM_SECRET_KEYS,
+	BOT_PROTECTED_KEYS,
+	BOT_PROVIDED_KEYS,
+	isReservedBotKey,
+} from "./keys";
 
 describe("isReservedBotKey", () => {
 	it("reserves every platform-owned key, the protected runtime keys and the SERVERK_ prefix", () => {
@@ -26,3 +33,27 @@ describe("isReservedBotKey", () => {
 		}
 	});
 });
+
+describe("BOT_AMBIENT_KEYS", () => {
+	it("holds every key the runtime protects or the platform provides, beside the ones code reads with a default", () => {
+		for (const key of [
+			...BOT_PROTECTED_KEYS,
+			...BOT_PROVIDED_KEYS,
+			"NODE_ENV",
+			"PORT",
+			"PYTHONPATH",
+		]) {
+			expect(BOT_AMBIENT_KEYS.includes(key)).toBe(true);
+		}
+	});
+
+	it("leaves a bot's own keys out", () => {
+		for (const key of [
+			"DISCORD_TOKEN",
+			"GUILD_ID",
+			"node_env",
+		]) {
+			expect(BOT_AMBIENT_KEYS.includes(key)).toBe(false);
+		}
+	});
+});

package/src/bot/detect/keys.ts

@@ -54,6 +54,21 @@ export const BOT_PROVIDED_KEYS: readonly string[] = [
 	BOT_PLATFORM,
 ];
 
+export const BOT_AMBIENT_KEYS: readonly string[] = [
+	...BOT_PROTECTED_KEYS,
+	...BOT_PROVIDED_KEYS,
+	"NODE_ENV",
+	"NODE_OPTIONS",
+	"PORT",
+	"HOST",
+	"HOSTNAME",
+	"DEBUG",
+	"LOG_LEVEL",
+	"CI",
+	"PYTHONPATH",
+	"PYTHONDONTWRITEBYTECODE",
+];
+
 export const isReservedBotKey = (key: string) => {
 	return (
 		key.startsWith(SERVERK_PREFIX)

package/src/bot/detect/serverkJson.test.ts

@@ -30,6 +30,7 @@ describe("parseServerkJson", () => {
 			framework: BotFramework.DiscordPy,
 			start: "python -m bot",
 			install: "pip install -r requirements/prod.txt",
+			build: null,
 			env: [
 				{
 					key: "GUILD_ID",
@@ -52,6 +53,7 @@ describe("parseServerkJson", () => {
 			framework: null,
 			start: null,
 			install: null,
+			build: null,
 			env: [],
 		});
 	});

package/src/bot/detect/serverkJson.ts

@@ -17,6 +17,7 @@ export interface ServerkJson {
 	framework: BotFramework | null;
 	start: string | null;
 	install: string | null;
+	build: string | null;
 	env: ServerkJsonEnv[];
 }
 
@@ -157,9 +158,10 @@ export const parseServerkJson = (text: string): ServerkJson | null => {
 	const framework = optionalOf(document.framework, isBotFramework);
 	const start = commandOf(document.start);
 	const install = commandOf(document.install);
+	const build = commandOf(document.build);
 	const env = envOf(document.env);
 
-	if (!runtime.ok || !platform.ok || !framework.ok || !start.ok || !install.ok || !env.ok) {
+	if (!runtime.ok || !platform.ok || !framework.ok || !start.ok || !install.ok || !build.ok || !env.ok) {
 		return null;
 	}
 
@@ -169,6 +171,7 @@ export const parseServerkJson = (text: string): ServerkJson | null => {
 		framework: framework.value,
 		start: start.value,
 		install: install.value,
+		build: build.value,
 		env: env.value,
 	};
 };

package/src/bot/index.ts

@@ -1,3 +1,4 @@
+export * from "./botCauses";
 export * from "./botDeploy";
 export * from "./botEnvironment";
 export * from "./botIdentity";

package/src/manifest/manifest.ts

@@ -224,7 +224,8 @@ export type ManifestFileNote = z.infer<typeof manifestFileNoteSchema>;
 
 const manifestFilesSchema = z.object({
 	protected: z.array(zGlob).max(64).default([]).meta({
-		description: "Paths the player cannot edit, rename or delete from the file manager.",
+		description:
+			"Platform state inside the server directory: hidden from the file manager and left out of archives and copies. Only what the bridge cannot manage without and cannot detect losing.",
 	}),
 	notable: z.array(manifestFileNoteSchema).max(32).default([]).meta({
 		description: "Paths the file manager annotates with a label, note and icon.",

package/src/modules/bridge.ts

@@ -39,6 +39,7 @@ import type {
 	BridgeCatalogProvider,
 	BridgeCatalogQuery,
 } from "../protocol/bridgeCatalog";
+import type { BridgeCrashReport } from "../protocol/bridgeCrash";
 import type { BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
 import type {
@@ -96,6 +97,7 @@ export namespace Bridge {
 	export type Collection<Row extends BridgeRow = BridgeRow> = BridgeCollectionModule<Row>;
 	export type Context = BridgeContext;
 	export type Copy = BridgeCopy;
+	export type CrashReport = BridgeCrashReport;
 	export type Detail = BridgeDetailModule;
 	export type DetailAction = BridgeDetailAction;
 	export type DetailBadge = BridgeDetailBadge;

package/src/modules/bridgeModule.ts

@@ -15,6 +15,7 @@ import type {
 	BridgeCatalogQuery,
 	BridgeCatalogRelease,
 } from "../protocol/bridgeCatalog";
+import type { BridgeCrashReport } from "../protocol/bridgeCrash";
 import type { BridgeBackupSnapshot, BridgeDescribeResult, BridgePendingFile } from "../protocol/bridgeFrame";
 import type { BridgePreview } from "../protocol/bridgePreview";
 import type { BridgeSetupStep } from "../protocol/bridgeSetup";
@@ -34,6 +35,8 @@ export interface BridgeLifecycleModule {
 	kind: BridgeKind.Lifecycle;
 	ready?: RegExp;
 	failed?: RegExp;
+	graceSeconds?: number;
+	stableLine?: RegExp;
 	stopTimeoutSeconds?: number;
 	readyTimeoutSeconds?: number;
 	stopSignal?: BridgeStopSignal;
@@ -42,6 +45,8 @@ export interface BridgeLifecycleModule {
 	environment?(context: BridgeContext): Promise<Record<string, string>>;
 	stop?(context: BridgeContext): Promise<void>;
 	onReady?(context: BridgeContext): Promise<void>;
+	onStable?(context: BridgeContext): Promise<void>;
+	onExit?(context: BridgeContext, report: BridgeCrashReport): Promise<void>;
 }
 
 export interface BridgeAnnounceModule {

package/src/probes/minecraftPing.test.ts

@@ -5,6 +5,7 @@ import { parseStatus, probeMinecraftPing } from "./minecraftPing";
 const HOST = "127.0.0.1";
 
 const CLOSED_PORT = 59_441;
+const CLOSED_HOST = "::1";
 
 const varInt = (value: number) => {
 	const bytes: number[] = [];
@@ -294,7 +295,7 @@ describe("probeMinecraftPing", () => {
 	it("rejects as unreachable when nothing listens on the port", async () => {
 		const error = await probeMinecraftPing(
 			{
-				address: HOST,
+				address: CLOSED_HOST,
 				port: CLOSED_PORT,
 			},
 			2000,

package/src/protocol/bridgeCrash.ts

@@ -8,6 +8,15 @@ export enum BridgeCrashCause {
 	WorldCorrupt = "world-corrupt",
 	MissingDependency = "missing-dependency",
 	ModCrashed = "mod-crashed",
+	TokenInvalid = "token-invalid",
+	IntentsDisallowed = "intents-disallowed",
+	TokenInUse = "token-in-use",
+	WrongTelegramPackage = "wrong-telegram-package",
+	WrongDiscordPackage = "wrong-discord-package",
+	BuildTools = "build-tools",
+	FfmpegMissing = "ffmpeg-missing",
+	AudioopRemoved = "audioop-removed",
+	RateLimited = "rate-limited",
 	Unknown = "unknown",
 }
 
@@ -38,6 +47,22 @@ export const BRIDGE_CRASH_EVIDENCE: readonly BridgeCrashEvidence[] = [
 		name: BridgeEventName.WorldCorrupt,
 		cause: BridgeCrashCause.WorldCorrupt,
 	},
+	{
+		name: BridgeEventName.AudioopRemoved,
+		cause: BridgeCrashCause.AudioopRemoved,
+	},
+	{
+		name: BridgeEventName.WrongTelegramPackage,
+		cause: BridgeCrashCause.WrongTelegramPackage,
+	},
+	{
+		name: BridgeEventName.WrongDiscordPackage,
+		cause: BridgeCrashCause.WrongDiscordPackage,
+	},
+	{
+		name: BridgeEventName.BuildToolsMissing,
+		cause: BridgeCrashCause.BuildTools,
+	},
 	{
 		name: BridgeEventName.MissingDependency,
 		cause: BridgeCrashCause.MissingDependency,
@@ -46,6 +71,26 @@ export const BRIDGE_CRASH_EVIDENCE: readonly BridgeCrashEvidence[] = [
 		name: BridgeEventName.ModCrashed,
 		cause: BridgeCrashCause.ModCrashed,
 	},
+	{
+		name: BridgeEventName.FfmpegMissing,
+		cause: BridgeCrashCause.FfmpegMissing,
+	},
+	{
+		name: BridgeEventName.IntentsDisallowed,
+		cause: BridgeCrashCause.IntentsDisallowed,
+	},
+	{
+		name: BridgeEventName.TokenInvalid,
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		name: BridgeEventName.TokenInUse,
+		cause: BridgeCrashCause.TokenInUse,
+	},
+	{
+		name: BridgeEventName.RateLimited,
+		cause: BridgeCrashCause.RateLimited,
+	},
 ];
 
 const BRIDGE_CRASH_EVIDENCE_NAMES: ReadonlySet<string> = new Set(BRIDGE_CRASH_EVIDENCE.map((entry) => entry.name));
@@ -81,3 +126,7 @@ export interface BridgeCrashRecord {
 	restarts: number;
 	lastLine: string | null;
 }
+
+export interface BridgeCrashReport extends BridgeCrashRecord {
+	cause: BridgeCrashCause;
+}

package/src/protocol/bridgeEvents.ts

@@ -1,11 +1,15 @@
 export enum BridgeEventName {
 	AccessGranted = "AccessGranted",
 	AccessRevoked = "AccessRevoked",
+	AudioopRemoved = "AudioopRemoved",
 	BroadcastSent = "BroadcastSent",
+	BuildToolsMissing = "BuildToolsMissing",
+	FfmpegMissing = "FfmpegMissing",
 	GameInstalled = "GameInstalled",
 	GameModeChanged = "GameModeChanged",
 	GameplayChanged = "GameplayChanged",
 	InstallFailed = "InstallFailed",
+	IntentsDisallowed = "IntentsDisallowed",
 	MemoryUndersized = "MemoryUndersized",
 	MissingDependency = "MissingDependency",
 	ModCrashed = "ModCrashed",
@@ -28,6 +32,7 @@ export enum BridgeEventName {
 	PlayerLeft = "PlayerLeft",
 	PlayerUnbanned = "PlayerUnbanned",
 	PortBindFailed = "PortBindFailed",
+	RateLimited = "RateLimited",
 	SecretRotated = "SecretRotated",
 	ServerCrashed = "ServerCrashed",
 	ServerStarted = "ServerStarted",
@@ -40,6 +45,8 @@ export enum BridgeEventName {
 	SetupRejected = "SetupRejected",
 	SignInExpired = "SignInExpired",
 	TickLagging = "TickLagging",
+	TokenInUse = "TokenInUse",
+	TokenInvalid = "TokenInvalid",
 	WorldActivated = "WorldActivated",
 	WorldCloned = "WorldCloned",
 	WorldCorrupt = "WorldCorrupt",
@@ -48,7 +55,9 @@ export enum BridgeEventName {
 	WorldImported = "WorldImported",
 	WorldSaved = "WorldSaved",
 	WorldWiped = "WorldWiped",
+	WrongDiscordPackage = "WrongDiscordPackage",
 	WrongJavaVersion = "WrongJavaVersion",
+	WrongTelegramPackage = "WrongTelegramPackage",
 }
 
 export const BRIDGE_EVENT_NAMES: readonly string[] = Object.values(BridgeEventName);