@serverkgg/bridge 0.0.21 → 0.1.2

package/src/bot/detect/detectResult.ts

@@ -0,0 +1,40 @@
+import type { BotFramework } from "./botFramework";
+import type { BotInspectWarning } from "./botInspectWarning";
+import type { BotPackageManager } from "./botPackageManager";
+import type { BotPlatform } from "./botPlatform";
+import type { BotRuntime } from "./botRuntime";
+
+export interface DetectEntry {
+	path: string;
+	size?: number;
+}
+
+export interface DetectInput {
+	files: readonly DetectEntry[];
+	contents: Readonly<Record<string, string>>;
+}
+
+export interface DetectedCommand {
+	command: string;
+	source: string;
+}
+
+export interface DetectedEnvKey {
+	key: string;
+	sensitive: boolean;
+	source: string;
+	example: string | null;
+}
+
+export interface DetectResult {
+	runtime: BotRuntime | null;
+	package: string | null;
+	packageManager: BotPackageManager | null;
+	framework: BotFramework | null;
+	platform: BotPlatform | null;
+	install: DetectedCommand | null;
+	start: DetectedCommand | null;
+	env: DetectedEnvKey[];
+	tokenKey: string | null;
+	warnings: BotInspectWarning[];
+}

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

@@ -0,0 +1,72 @@
+import { describe, expect, test } from "bun:test";
+import { BotFramework } from "./botFramework";
+import { DETECT_TABLE, renderDetectTable } from "./detectTable";
+import { isEnvKey } from "./envKey";
+import { parseServerkJson } from "./serverkJson";
+
+describe("renderDetectTable", () => {
+	test("renders the table the launchers read as stable, tab-indented JSON", () => {
+		const rendered = renderDetectTable();
+
+		expect(rendered.endsWith("}\n")).toBe(true);
+		expect(rendered).toContain('\t"version": 1,');
+		expect(JSON.parse(rendered)).toEqual(DETECT_TABLE);
+	});
+
+	test("names an install command for every manager a lockfile or manifest points at", () => {
+		for (const lockfile of DETECT_TABLE.node.lockfiles) {
+			expect(DETECT_TABLE.node.installCommands[lockfile.manager]).toBeDefined();
+		}
+
+		expect(DETECT_TABLE.node.installCommands[DETECT_TABLE.node.unlockedManager]).toBeDefined();
+
+		for (const manifest of DETECT_TABLE.python.manifests) {
+			expect(DETECT_TABLE.python.installArguments[manifest.manager]).toBeDefined();
+		}
+	});
+
+	test("carries the serverk.json rules the launchers need to agree with the parser", () => {
+		const rules = DETECT_TABLE.serverkJson;
+		const envKey = new RegExp(rules.envKey);
+
+		expect(rules.file).toBe("serverk.json");
+		expect(rules.frameworks).toEqual(Object.values(BotFramework));
+		expect(envKey.test("DISCORD_TOKEN")).toBe(isEnvKey("DISCORD_TOKEN"));
+		expect(envKey.test("1BAD")).toBe(isEnvKey("1BAD"));
+		expect(
+			parseServerkJson(
+				JSON.stringify({
+					start: "x".repeat(rules.commandLengthLimit),
+				}),
+			),
+		).not.toBeNull();
+		expect(
+			parseServerkJson(
+				JSON.stringify({
+					start: "x".repeat(rules.commandLengthLimit + 1),
+				}),
+			),
+		).toBeNull();
+		expect(
+			parseServerkJson(
+				JSON.stringify({
+					env: Array.from(
+						{
+							length: rules.envLimit + 1,
+						},
+						(_, index) => `KEY_${index}`,
+					),
+				}),
+			),
+		).toBeNull();
+	});
+
+	test("compiles the Procfile line in both JavaScript and Python syntax", () => {
+		const line = new RegExp(DETECT_TABLE.procfile.line);
+
+		expect(line.exec("worker: node bot.js")?.slice(1)).toEqual([
+			"worker",
+			"node bot.js",
+		]);
+	});
+});

package/src/bot/detect/detectTable.ts

@@ -0,0 +1,166 @@
+import { BotFramework } from "./botFramework";
+import { BotPlatform } from "./botPlatform";
+import { BotRuntime } from "./botRuntime";
+import { ENV_KEY_LENGTH_LIMIT, ENV_KEY_PATTERN } from "./envKey";
+import {
+	SERVERK_JSON,
+	SERVERK_JSON_COMMAND_LENGTH_LIMIT,
+	SERVERK_JSON_ENV_LIMIT,
+	SERVERK_JSON_EXAMPLE_LENGTH_LIMIT,
+} from "./serverkJson";
+
+export const DETECT_TABLE_VERSION = 1;
+
+export const DETECT_TABLE_FILE = "image/detect.json";
+
+export interface DetectLockfile {
+	file: string;
+	manager: string;
+}
+
+export interface DetectProcfile {
+	file: string;
+	line: string;
+	processes: string[];
+}
+
+export interface ServerkJsonDetectTable {
+	file: string;
+	commandLengthLimit: number;
+	runtimes: string[];
+	platforms: string[];
+	frameworks: string[];
+	envLimit: number;
+	envKey: string;
+	envKeyLengthLimit: number;
+	exampleLengthLimit: number;
+}
+
+export interface NodeDetectTable {
+	manifest: string;
+	startFiles: string[];
+	lockfiles: DetectLockfile[];
+	installCommands: Record<string, string[]>;
+	unlockedManager: string;
+}
+
+export interface PythonDetectTable {
+	startFiles: string[];
+	manifests: DetectLockfile[];
+	installArguments: Record<string, string[]>;
+}
+
+export interface DetectTable {
+	version: number;
+	procfile: DetectProcfile;
+	serverkJson: ServerkJsonDetectTable;
+	node: NodeDetectTable;
+	python: PythonDetectTable;
+}
+
+export const DETECT_TABLE: DetectTable = {
+	version: DETECT_TABLE_VERSION,
+	procfile: {
+		file: "Procfile",
+		line: "^(worker|bot)\\s*:\\s*(.+)$",
+		processes: [
+			"worker",
+			"bot",
+		],
+	},
+	serverkJson: {
+		file: SERVERK_JSON,
+		commandLengthLimit: SERVERK_JSON_COMMAND_LENGTH_LIMIT,
+		runtimes: Object.values(BotRuntime),
+		platforms: Object.values(BotPlatform),
+		frameworks: Object.values(BotFramework),
+		envLimit: SERVERK_JSON_ENV_LIMIT,
+		envKey: ENV_KEY_PATTERN.source,
+		envKeyLengthLimit: ENV_KEY_LENGTH_LIMIT,
+		exampleLengthLimit: SERVERK_JSON_EXAMPLE_LENGTH_LIMIT,
+	},
+	node: {
+		manifest: "package.json",
+		startFiles: [
+			"index.js",
+			"src/index.js",
+			"bot.js",
+			"src/bot.js",
+			"index.ts",
+		],
+		lockfiles: [
+			{
+				file: "package-lock.json",
+				manager: "npm",
+			},
+			{
+				file: "npm-shrinkwrap.json",
+				manager: "npm",
+			},
+			{
+				file: "pnpm-lock.yaml",
+				manager: "pnpm",
+			},
+			{
+				file: "yarn.lock",
+				manager: "yarn",
+			},
+		],
+		installCommands: {
+			npm: [
+				"npm",
+				"ci",
+			],
+			pnpm: [
+				"corepack",
+				"pnpm",
+				"install",
+				"--frozen-lockfile",
+			],
+			yarn: [
+				"corepack",
+				"yarn",
+				"install",
+			],
+			"npm-install": [
+				"npm",
+				"install",
+			],
+		},
+		unlockedManager: "npm-install",
+	},
+	python: {
+		startFiles: [
+			"main.py",
+			"bot.py",
+			"app.py",
+			"src/main.py",
+			"src/bot.py",
+		],
+		manifests: [
+			{
+				file: "requirements.txt",
+				manager: "requirements",
+			},
+			{
+				file: "pyproject.toml",
+				manager: "project",
+			},
+		],
+		installArguments: {
+			requirements: [
+				"install",
+				"-r",
+				"requirements.txt",
+			],
+			project: [
+				"install",
+				".",
+			],
+		},
+	},
+};
+
+export const renderDetectTable = (table: DetectTable = DETECT_TABLE) => {
+	return `${JSON.stringify(table, null, "\t")}\n`;
+};

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

@@ -0,0 +1,29 @@
+import { describe, expect, test } from "bun:test";
+import { parseEnvExample } from "./envExample";
+
+describe("parseEnvExample", () => {
+	test("reads keys and example values the way dotenv files write them", () => {
+		expect(
+			parseEnvExample(
+				"# Discord\r\nDISCORD_TOKEN=\r\nexport PREFIX=\"!\" # command prefix\nOWNER_ID = 1234 # yours\nQUOTED='a # b'\nnot a line\n1BAD=x\n",
+			),
+		).toEqual([
+			{
+				key: "DISCORD_TOKEN",
+				value: "",
+			},
+			{
+				key: "PREFIX",
+				value: "!",
+			},
+			{
+				key: "OWNER_ID",
+				value: "1234",
+			},
+			{
+				key: "QUOTED",
+				value: "a # b",
+			},
+		]);
+	});
+});

package/src/bot/detect/envExample.ts

@@ -0,0 +1,48 @@
+import { isEnvKey } from "./envKey";
+
+export const ENV_EXAMPLE_FILES: readonly string[] = [
+	".env.example",
+	".env.sample",
+	".env.template",
+];
+
+export interface EnvExampleEntry {
+	key: string;
+	value: string;
+}
+
+const ASSIGNMENT = /^\s*(?:export\s+)?([A-Za-z_][A-Za-z0-9_]*)\s*=\s*(.*)$/;
+
+const INLINE_COMMENT = /\s+#.*$/;
+
+const unquote = (raw: string) => {
+	const quote = raw[0];
+
+	if (quote === '"' || quote === "'") {
+		const end = raw.indexOf(quote, 1);
+
+		return end === -1 ? raw.slice(1) : raw.slice(1, end);
+	}
+
+	return raw.replace(INLINE_COMMENT, "").trim();
+};
+
+export const parseEnvExample = (text: string): EnvExampleEntry[] => {
+	const entries: EnvExampleEntry[] = [];
+
+	for (const line of text.replace(/^/, "").split(/\r?\n/)) {
+		const match = ASSIGNMENT.exec(line);
+		const key = match?.[1];
+
+		if (!key || !isEnvKey(key)) {
+			continue;
+		}
+
+		entries.push({
+			key,
+			value: unquote((match[2] ?? "").trim()),
+		});
+	}
+
+	return entries;
+};

package/src/bot/detect/envKey.ts

@@ -0,0 +1,7 @@
+export const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+export const ENV_KEY_LENGTH_LIMIT = 64;
+
+export const isEnvKey = (key: string) => {
+	return key.length <= ENV_KEY_LENGTH_LIMIT && ENV_KEY_PATTERN.test(key);
+};

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

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { scanEnvKeys } from "./envScan";
+
+describe("scanEnvKeys", () => {
+	test("finds every way Node code reads a variable", () => {
+		expect(
+			scanEnvKeys(
+				"src/index.ts",
+				'process.env.A; process.env["B"]; process.env[`C`]; const { D, E: e, F = 1, ...rest } = process.env;',
+			),
+		).toEqual([
+			"A",
+			"B",
+			"C",
+			"D",
+			"E",
+			"F",
+		]);
+	});
+
+	test("finds every way Python code reads a variable", () => {
+		expect(
+			scanEnvKeys(
+				"bot/main.py",
+				'os.environ["A"]\nos.environ.get("B", "x")\nos.getenv(\'C\')\nfrom os import getenv, environ\ngetenv("D")\nenviron["E"]\nmyos.getenv("NO")',
+			),
+		).toEqual([
+			"A",
+			"B",
+			"C",
+			"D",
+			"E",
+		]);
+	});
+
+	test("reads nothing from files that are not code", () => {
+		expect(scanEnvKeys("README.md", "process.env.A")).toEqual([]);
+	});
+});

package/src/bot/detect/envScan.ts

@@ -0,0 +1,87 @@
+export const NODE_SOURCE_EXTENSIONS: readonly string[] = [
+	".js",
+	".mjs",
+	".cjs",
+	".ts",
+	".mts",
+	".cts",
+];
+
+export const PYTHON_SOURCE_EXTENSIONS: readonly string[] = [
+	".py",
+];
+
+const NAME = "([A-Za-z_][A-Za-z0-9_]*)";
+
+const NODE_PATTERNS: readonly RegExp[] = [
+	new RegExp(`\\bprocess\\.env\\.${NAME}`, "g"),
+	new RegExp(`\\bprocess\\.env\\[\\s*["'\`]${NAME}["'\`]\\s*\\]`, "g"),
+];
+
+const NODE_DESTRUCTURE = /\{([^{}]{1,2000})\}\s*=\s*process\.env\b/g;
+
+const DESTRUCTURED_NAME = /^\s*([A-Za-z_][A-Za-z0-9_]*)/;
+
+const PYTHON_PATTERNS: readonly RegExp[] = [
+	new RegExp(`(?<![\\w.])(?:os\\.)?environ\\[\\s*["']${NAME}["']\\s*\\]`, "g"),
+	new RegExp(`(?<![\\w.])(?:os\\.)?environ\\.get\\(\\s*["']${NAME}["']`, "g"),
+	new RegExp(`(?<![\\w.])(?:os\\.)?getenv\\(\\s*["']${NAME}["']`, "g"),
+];
+
+interface Found {
+	at: number;
+	name: string;
+}
+
+export const isNodeSource = (path: string) => {
+	return NODE_SOURCE_EXTENSIONS.some((extension) => path.endsWith(extension));
+};
+
+export const isPythonSource = (path: string) => {
+	return PYTHON_SOURCE_EXTENSIONS.some((extension) => path.endsWith(extension));
+};
+
+const collect = (text: string, patterns: readonly RegExp[], found: Found[]) => {
+	for (const pattern of patterns) {
+		for (const match of text.matchAll(pattern)) {
+			if (match[1]) {
+				found.push({
+					at: match.index,
+					name: match[1],
+				});
+			}
+		}
+	}
+};
+
+const destructured = (text: string, found: Found[]) => {
+	for (const match of text.matchAll(NODE_DESTRUCTURE)) {
+		for (const part of (match[1] ?? "").split(",")) {
+			const name = DESTRUCTURED_NAME.exec(part)?.[1];
+
+			if (name && !part.trimStart().startsWith("...")) {
+				found.push({
+					at: match.index,
+					name,
+				});
+			}
+		}
+	}
+};
+
+export const scanEnvKeys = (path: string, text: string): string[] => {
+	const found: Found[] = [];
+
+	if (isNodeSource(path)) {
+		collect(text, NODE_PATTERNS, found);
+		destructured(text, found);
+	}
+
+	if (isPythonSource(path)) {
+		collect(text, PYTHON_PATTERNS, found);
+	}
+
+	return [
+		...new Set(found.sort((a, b) => a.at - b.at).map((entry) => entry.name)),
+	];
+};

package/src/bot/detect/index.ts

@@ -0,0 +1,17 @@
+export * from "./botFramework";
+export * from "./botFrameworks";
+export * from "./botInspectWarning";
+export * from "./botPackageManager";
+export * from "./botPlatform";
+export * from "./botRuntime";
+export * from "./botToken";
+export * from "./detect";
+export * from "./detectResult";
+export * from "./detectTable";
+export * from "./envExample";
+export * from "./envKey";
+export * from "./envScan";
+export * from "./inferBotPlatform";
+export * from "./keys";
+export * from "./sensitiveKey";
+export * from "./serverkJson";

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

@@ -0,0 +1,60 @@
+import { describe, expect, test } from "bun:test";
+import { BotPlatform } from "./botPlatform";
+import { inferBotPlatform } from "./inferBotPlatform";
+
+const TELEGRAM_TOKEN = "7123456789:AAHdqTcvCH1vGWJxfSeofSAs0K5PALDsaw";
+
+describe("inferBotPlatform", () => {
+	test("takes the explicit platform first", () => {
+		expect(
+			inferBotPlatform({
+				variables: {
+					BOT_PLATFORM: "telegram",
+					DISCORD_TOKEN: "x",
+				},
+				secrets: {},
+			}),
+		).toBe(BotPlatform.Telegram);
+	});
+
+	test("then the key names, then the token shape", () => {
+		expect(
+			inferBotPlatform({
+				variables: {},
+				secrets: {
+					DISCORD_BOT_TOKEN: "x",
+				},
+			}),
+		).toBe(BotPlatform.Discord);
+		expect(
+			inferBotPlatform({
+				variables: {},
+				secrets: {
+					TOKEN: TELEGRAM_TOKEN,
+				},
+			}),
+		).toBe(BotPlatform.Telegram);
+	});
+
+	test("answers null when the hints disagree or do not exist", () => {
+		expect(
+			inferBotPlatform({
+				variables: {},
+				secrets: {
+					DISCORD_TOKEN: "x",
+					TELEGRAM_TOKEN: "y",
+				},
+			}),
+		).toBeNull();
+		expect(
+			inferBotPlatform({
+				variables: {
+					BOT_PLATFORM: "slack",
+				},
+				secrets: {
+					API_KEY: "x",
+				},
+			}),
+		).toBeNull();
+	});
+});

package/src/bot/detect/inferBotPlatform.ts

@@ -0,0 +1,28 @@
+import { type BotPlatform, isBotPlatform } from "./botPlatform";
+import { type BotEnvironmentMaps, platformOfKey, platformOfToken } from "./botToken";
+import { BOT_PLATFORM, isReservedBotKey } from "./keys";
+
+const single = (platforms: (BotPlatform | null)[]) => {
+	const found = [
+		...new Set(platforms.filter((platform) => platform !== null)),
+	];
+
+	return found.length === 1 ? (found[0] ?? null) : null;
+};
+
+export const inferBotPlatform = (maps: BotEnvironmentMaps): BotPlatform | null => {
+	const explicit = maps.variables[BOT_PLATFORM]?.trim();
+
+	if (isBotPlatform(explicit)) {
+		return explicit;
+	}
+
+	const entries = [
+		...Object.entries(maps.secrets),
+		...Object.entries(maps.variables),
+	].filter(([key]) => !isReservedBotKey(key));
+
+	return (
+		single(entries.map(([key]) => platformOfKey(key))) ?? single(entries.map(([, value]) => platformOfToken(value)))
+	);
+};

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

@@ -0,0 +1,28 @@
+import { describe, expect, test } from "bun:test";
+import { BOT_PLATFORM_KEYS, BOT_PLATFORM_SECRET_KEYS, BOT_PROTECTED_KEYS, isReservedBotKey } from "./keys";
+
+describe("isReservedBotKey", () => {
+	test("reserves every platform-owned key, the protected runtime keys and the SERVERK_ prefix", () => {
+		for (const key of [
+			...BOT_PLATFORM_KEYS,
+			...BOT_PLATFORM_SECRET_KEYS,
+			...BOT_PROTECTED_KEYS,
+			"SERVERK_BOT",
+			"SERVERK_ANYTHING",
+		]) {
+			expect(isReservedBotKey(key)).toBe(true);
+		}
+	});
+
+	test("leaves the customer's own keys alone, case included", () => {
+		for (const key of [
+			"DISCORD_TOKEN",
+			"NODE_OPTIONS",
+			"path",
+			"serverk_mine",
+			"REPO_URL_MIRROR",
+		]) {
+			expect(isReservedBotKey(key)).toBe(false);
+		}
+	});
+});

package/src/bot/detect/keys.ts

@@ -0,0 +1,64 @@
+export const SERVERK_PREFIX = "SERVERK_";
+
+export const REPO_URL = "REPO_URL";
+
+export const REPO_REF = "REPO_REF";
+
+export const REPO_BRANCH = "REPO_BRANCH";
+
+export const START_COMMAND = "START_COMMAND";
+
+export const INSTALL_COMMAND = "INSTALL_COMMAND";
+
+export const ROOT_DIRECTORY = "ROOT_DIRECTORY";
+
+export const DEPLOYMENT_ID = "DEPLOYMENT_ID";
+
+export const SNAPSHOT_ID = "SNAPSHOT_ID";
+
+export const BOT_PLATFORM = "BOT_PLATFORM";
+
+export const GIT_TOKEN = "GIT_TOKEN";
+
+export const SERVERK_BOT = "SERVERK_BOT";
+
+export const SERVERK_SERVER_CODE = "SERVERK_SERVER_CODE";
+
+export const BOT_PLATFORM_KEYS: readonly string[] = [
+	REPO_URL,
+	REPO_REF,
+	REPO_BRANCH,
+	START_COMMAND,
+	INSTALL_COMMAND,
+	ROOT_DIRECTORY,
+	DEPLOYMENT_ID,
+	SNAPSHOT_ID,
+	BOT_PLATFORM,
+];
+
+export const BOT_PLATFORM_SECRET_KEYS: readonly string[] = [
+	GIT_TOKEN,
+];
+
+export const BOT_PROTECTED_KEYS: readonly string[] = [
+	"PATH",
+	"HOME",
+	"VIRTUAL_ENV",
+	"PYTHONUNBUFFERED",
+	"TZ",
+];
+
+export const BOT_PROVIDED_KEYS: readonly string[] = [
+	SERVERK_BOT,
+	SERVERK_SERVER_CODE,
+	BOT_PLATFORM,
+];
+
+export const isReservedBotKey = (key: string) => {
+	return (
+		key.startsWith(SERVERK_PREFIX)
+		|| BOT_PLATFORM_KEYS.includes(key)
+		|| BOT_PLATFORM_SECRET_KEYS.includes(key)
+		|| BOT_PROTECTED_KEYS.includes(key)
+	);
+};