@serverkgg/bridge 0.1.9 → 0.1.11

package/src/bot/detect/botInspectWarning.ts

@@ -15,4 +15,5 @@ export enum BotInspectWarning {
 	ManifestDisagrees = "manifest-disagrees",
 	ManifestInvalid = "manifest-invalid",
 	ReservedEnvKey = "reserved-env-key",
+	WebPort = "web-port",
 }

package/src/bot/detect/corpus/anonymousx1025-anonxmusic.json

@@ -27,7 +27,8 @@
 		".python-version": "3.13\n",
 		"Procfile": "worker: bash start\n",
 		"pyproject.toml": "[project]\nname = \"anonxmusic\"\nversion = \"3.0.3\"\ndescription = \"Telegram Group Calls Streaming bot with some useful features.\"\nreadme = \".github/README.md\"\nrequires-python = \">=3.10\"\n\ndependencies = [\n    \"aiohttp~=3.14.3\",\n    \"kurigram>=2.2.25\",\n    \"ntgcalls==3.0.0rc1\",\n    \"pillow~=12.3.0\",\n    \"psutil~=7.2.2\",\n    \"py-tgcalls==3.0.0rc1\",\n    \"py-yt-search~=0.8.0\",\n    \"pymongo>=4.17.0\",\n    \"pytgcrypto>=1.2.12\",\n    \"python-dotenv~=1.2.3\",\n    \"yt-dlp[default]>=2026.8.19\",\n]\n",
-		"requirements.txt": "aiohttp~=3.14.3\nkurigram>=2.2.25\nntgcalls==3.0.0rc1\npillow~=12.3.0\npsutil~=7.2.2\npy-tgcalls==3.0.0rc1\npy-yt-search~=0.8.0\npymongo>=4.17.0\npytgcrypto>=1.2.12\npython-dotenv~=1.2.3\nyt-dlp[default]>=2026.8.19\n"
+		"requirements.txt": "aiohttp~=3.14.3\nkurigram>=2.2.25\nntgcalls==3.0.0rc1\npillow~=12.3.0\npsutil~=7.2.2\npy-tgcalls==3.0.0rc1\npy-yt-search~=0.8.0\npymongo>=4.17.0\npytgcrypto>=1.2.12\npython-dotenv~=1.2.3\nyt-dlp[default]>=2026.8.19\n",
+		"sample.env": "# from my.telegram.org/apps\nAPI_ID=\nAPI_HASH=\n\n# from @BotFather on telegram\nBOT_TOKEN=\nLOGGER_ID=\n\n# mongo url from cloud.mongodb.com\nMONGO_URL=\n\nOWNER_ID=\n\n# pyrogram session from @StringFatherBot on telegram\nSESSION=\n"
 	},
 	"expected": {
 		"runtime": "python",
@@ -39,7 +40,7 @@
 		"start": "bash start",
 		"nodeVersion": null,
 		"pythonVersion": "3.13",
-		"tokenKey": null,
+		"tokenKey": "BOT_TOKEN",
 		"warnings": []
 	}
 }

package/src/bot/detect/corpus/bot-base-telegram-bot-template.json

@@ -30,6 +30,8 @@
 		"nodeVersion": "20",
 		"pythonVersion": null,
 		"tokenKey": "BOT_TOKEN",
-		"warnings": []
+		"warnings": [
+			"web-port"
+		]
 	}
 }

package/src/bot/detect/corpus/nezdemkovski-telegram-bot-boilerplate.json

@@ -35,6 +35,8 @@
 		"nodeVersion": null,
 		"pythonVersion": null,
 		"tokenKey": "BOT_TOKEN",
-		"warnings": []
+		"warnings": [
+			"web-port"
+		]
 	}
 }

package/src/bot/detect/corpus/serverk-discord-node.json

@@ -1,13 +1,14 @@
 {
 	"source": {
-		"url": "https://github.com/serverkgg/bot-node/tree/main/templates/discord-node",
+		"url": "https://github.com/serverkgg/bot-template-discord-node",
 		"branch": "main",
-		"commit": "3f9f6c033824857a9ffd849421fc5ecff31500d7",
+		"commit": "0c950227f6c2ab97b610080f2e9c9f60ff8c6069",
 		"stars": null
 	},
 	"files": [
 		".env.example",
 		".gitignore",
+		"AGENTS.md",
 		"LICENSE",
 		"README.md",
 		"index.js",

package/src/bot/detect/corpus/serverk-discord-python.json

@@ -1,13 +1,14 @@
 {
 	"source": {
-		"url": "https://github.com/serverkgg/bot-python/tree/main/templates/discord-python",
+		"url": "https://github.com/serverkgg/bot-template-discord-python",
 		"branch": "main",
-		"commit": "0a623a9dc114e31f0f2a5011e1f0471b2c047df3",
+		"commit": "e520ae1dfb07bb1e8a1eba73c5651a3ad3d39ad1",
 		"stars": null
 	},
 	"files": [
 		".env.example",
 		".gitignore",
+		"AGENTS.md",
 		"LICENSE",
 		"README.md",
 		"main.py",

package/src/bot/detect/corpus/serverk-telegram-node.json

@@ -1,13 +1,14 @@
 {
 	"source": {
-		"url": "https://github.com/serverkgg/bot-node/tree/main/templates/telegram-node",
+		"url": "https://github.com/serverkgg/bot-template-telegram-node",
 		"branch": "main",
-		"commit": "3f9f6c033824857a9ffd849421fc5ecff31500d7",
+		"commit": "49a55385c7336551dbb50b6ebc99a4e18743418f",
 		"stars": null
 	},
 	"files": [
 		".env.example",
 		".gitignore",
+		"AGENTS.md",
 		"LICENSE",
 		"README.md",
 		"index.js",

package/src/bot/detect/corpus/serverk-telegram-python.json

@@ -1,13 +1,14 @@
 {
 	"source": {
-		"url": "https://github.com/serverkgg/bot-python/tree/main/templates/telegram-python",
+		"url": "https://github.com/serverkgg/bot-template-telegram-python",
 		"branch": "main",
-		"commit": "0a623a9dc114e31f0f2a5011e1f0471b2c047df3",
+		"commit": "342e61c43f02f469c572f43cd3ed1e95ba85a130",
 		"stars": null
 	},
 	"files": [
 		".env.example",
 		".gitignore",
+		"AGENTS.md",
 		"LICENSE",
 		"README.md",
 		"main.py",

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

@@ -51,6 +51,16 @@ const TELEGRAM_PYTHON = {
 	".env.example": "TELEGRAM_TOKEN=\n",
 };
 
+const NPM_INSTALLED_PACKAGE = `${JSON.stringify(
+	{
+		dependencies: {
+			"discord.js": "^14.27.0",
+		},
+	},
+	null,
+	2,
+)}\n`;
+
 describe("detect on the templates", () => {
 	it("reads the discord.js template end to end", () => {
 		expect(
@@ -371,6 +381,89 @@ describe("detect on the templates", () => {
 		expect(project(TELEGRAM_PYTHON).pythonVersion).toBeNull();
 	});
 
+	const NODE_VERSION_CASES: readonly {
+		first: string;
+		second: string;
+		files: Record<string, string>;
+		version: string;
+	}[] = [
+		{
+			first: "engines.node",
+			second: ".nvmrc",
+			files: {
+				"package.json": JSON.stringify({
+					...JSON.parse(DISCORD_NODE["package.json"]),
+					engines: {
+						node: ">=18",
+					},
+				}),
+				".nvmrc": "v20.11.1\n",
+			},
+			version: "18",
+		},
+		{
+			first: ".nvmrc",
+			second: ".node-version",
+			files: {
+				".nvmrc": "v22.11.0\n",
+				".node-version": "20.11.1\n",
+			},
+			version: "22",
+		},
+		{
+			first: ".node-version",
+			second: ".tool-versions",
+			files: {
+				".node-version": "20.11.1\n",
+				".tool-versions": "nodejs 22.3.0\n",
+			},
+			version: "20",
+		},
+	];
+
+	for (const item of NODE_VERSION_CASES) {
+		it(`reads the Node version from ${item.first} before ${item.second}`, () => {
+			const result = project({
+				...DISCORD_NODE,
+				...item.files,
+			});
+
+			expect(result.nodeVersion).toBe(item.version);
+		});
+	}
+
+	it("reads the Python version from runtime.txt before the Pipfile's python_version", () => {
+		const result = project({
+			Pipfile:
+				'[[source]]\nurl = "https://pypi.org/simple"\nverify_ssl = true\nname = "pypi"\n\n[packages]\n"discord.py" = "*"\n\n[dev-packages]\n\n[requires]\npython_version = "3.10"\n',
+			"runtime.txt": "python-3.11.9\n",
+			"bot.py": "import discord\n",
+		});
+
+		expect(result.packageManager).toBe(BotPackageManager.Pipenv);
+		expect(result.pythonVersion).toBe("3.11");
+	});
+
+	it("installs with yarn when only engines.yarn names a manager and no lockfile ships", () => {
+		const result = project({
+			...DISCORD_NODE,
+			"package.json": JSON.stringify({
+				...JSON.parse(DISCORD_NODE["package.json"]),
+				engines: {
+					node: ">=18",
+					yarn: ">=1.22",
+				},
+			}),
+		});
+
+		expect(result.packageManager).toBe(BotPackageManager.Yarn);
+		expect(result.install).toEqual({
+			command: "corepack yarn install",
+			source: "package.json",
+		});
+		expect(result.warnings).toContain(BotInspectWarning.NoLockfile);
+	});
+
 	it("installs from the Python lockfiles, honouring uv and warning about the rest", () => {
 		const locked = (lockfile: string) => {
 			return project(
@@ -484,6 +577,107 @@ describe("detect start commands", () => {
 		});
 	});
 
+	const NODE_START_CASES: readonly {
+		file: string;
+		beside: string[];
+	}[] = [
+		{
+			file: "index.js",
+			beside: [
+				"src/index.js",
+				"bot.js",
+				"src/bot.js",
+				"index.ts",
+			],
+		},
+		{
+			file: "src/index.js",
+			beside: [
+				"bot.js",
+				"src/bot.js",
+				"index.ts",
+			],
+		},
+		{
+			file: "bot.js",
+			beside: [
+				"src/bot.js",
+				"index.ts",
+			],
+		},
+		{
+			file: "src/bot.js",
+			beside: [
+				"index.ts",
+			],
+		},
+		{
+			file: "index.ts",
+			beside: [],
+		},
+	];
+
+	for (const item of NODE_START_CASES) {
+		it(`starts ${item.file} when package.json names no start script and no main, ahead of [${item.beside.join(", ")}]`, () => {
+			const result = project(
+				{
+					"package.json": NPM_INSTALLED_PACKAGE,
+					[item.file]: "",
+				},
+				item.beside,
+			);
+
+			expect(result.start).toEqual({
+				command: `node ${item.file}`,
+				source: item.file,
+			});
+			expect(result.warnings).toEqual([
+				BotInspectWarning.NoLockfile,
+			]);
+		});
+	}
+
+	const PYTHON_START_CASES: readonly {
+		file: string;
+		beside: string[];
+	}[] = [
+		{
+			file: "app.py",
+			beside: [
+				"src/main.py",
+				"src/bot.py",
+			],
+		},
+		{
+			file: "src/main.py",
+			beside: [
+				"src/bot.py",
+			],
+		},
+		{
+			file: "src/bot.py",
+			beside: [],
+		},
+	];
+
+	for (const item of PYTHON_START_CASES) {
+		it(`starts ${item.file} when no main.py or bot.py exists, ahead of [${item.beside.join(", ")}]`, () => {
+			const result = project(
+				{
+					"requirements.txt": "python-telegram-bot==21.11.1\n",
+					[item.file]: "",
+				},
+				item.beside,
+			);
+
+			expect(result.start).toEqual({
+				command: `python ${item.file}`,
+				source: item.file,
+			});
+			expect(result.warnings).toEqual([]);
+		});
+	}
+
 	it("starts the one Python package that has a __main__ module when no start file exists", () => {
 		expect(
 			project(
@@ -678,6 +872,90 @@ describe("detect warnings", () => {
 
 		expect(quiet.warnings).not.toContain(BotInspectWarning.ReservedEnvKey);
 	});
+
+	it("keeps quiet about the web address and raw port variables an example file lists, and warns about the switches", () => {
+		const quiet = project({
+			...DISCORD_NODE,
+			".env.example": "DISCORD_TOKEN=\nSERVERK_WEB_URL=\nSERVERK_WEB_HOST=\nSERVERK_PORT_1=\nSERVERK_PORT_2=\n",
+		});
+
+		expect(quiet.env.map((entry) => entry.key)).toEqual([
+			"DISCORD_TOKEN",
+		]);
+		expect(quiet.warnings).not.toContain(BotInspectWarning.ReservedEnvKey);
+
+		const loud = project({
+			...DISCORD_NODE,
+			".env.example": "DISCORD_TOKEN=\nBOT_WEB=on\n",
+		});
+
+		expect(loud.env.map((entry) => entry.key)).toEqual([
+			"DISCORD_TOKEN",
+		]);
+		expect(loud.warnings).toContain(BotInspectWarning.ReservedEnvKey);
+	});
+
+	it("warns that a node bot reading PORT needs the web address, and keeps PORT among the variables", () => {
+		const result = project({
+			...DISCORD_NODE,
+			"index.js": "const token = process.env.DISCORD_TOKEN;\napp.listen(process.env.PORT);\n",
+		});
+
+		expect(result.env.map((entry) => entry.key)).toEqual([
+			"DISCORD_TOKEN",
+			"PORT",
+		]);
+		expect(result.warnings).toContain(BotInspectWarning.WebPort);
+	});
+
+	it("warns that a python bot whose example file lists a webhook needs the web address", () => {
+		const result = project({
+			...TELEGRAM_PYTHON,
+			".env.example": "TELEGRAM_TOKEN=\nWEBHOOK_URL=\n",
+		});
+
+		expect(result.env.map((entry) => entry.key)).toEqual([
+			"TELEGRAM_TOKEN",
+			"WEBHOOK_URL",
+		]);
+		expect(result.warnings).toContain(BotInspectWarning.WebPort);
+	});
+
+	it("reads a webhook key on a discord bot as an outgoing log webhook, and on a telegram bot as one it receives", () => {
+		const discord = project({
+			...DISCORD_NODE,
+			".env.example": "DISCORD_TOKEN=\nLOG_WEBHOOK_URL=\n",
+		});
+
+		expect(discord.platform).toBe(BotPlatform.Discord);
+		expect(discord.env.map((entry) => entry.key)).toEqual([
+			"DISCORD_TOKEN",
+			"LOG_WEBHOOK_URL",
+		]);
+		expect(discord.warnings).not.toContain(BotInspectWarning.WebPort);
+
+		const telegram = project({
+			...TELEGRAM_PYTHON,
+			".env.example": "TELEGRAM_TOKEN=\nLOG_WEBHOOK_URL=\n",
+		});
+
+		expect(telegram.platform).toBe(BotPlatform.Telegram);
+		expect(telegram.warnings).toContain(BotInspectWarning.WebPort);
+	});
+
+	it("keeps quiet about the web address for a bot that reads neither PORT nor a webhook", () => {
+		const result = project({
+			...DISCORD_NODE,
+			"index.js": "const token = process.env.DISCORD_TOKEN;\nconst port = process.env.SERVER_PORT;\n",
+		});
+
+		expect(result.env.map((entry) => entry.key)).toEqual([
+			"DISCORD_TOKEN",
+			"SERVER_PORT",
+		]);
+		expect(result.warnings).not.toContain(BotInspectWarning.WebPort);
+		expect(project(TELEGRAM_PYTHON).warnings).not.toContain(BotInspectWarning.WebPort);
+	});
 });
 
 describe("detect with serverk.json", () => {
@@ -711,6 +989,32 @@ describe("detect with serverk.json", () => {
 		expect(result.warnings).toContain(BotInspectWarning.ManifestDisagrees);
 	});
 
+	it("says when the file names a runtime the code is not written in", () => {
+		const disagrees = project({
+			...TELEGRAM_PYTHON,
+			"serverk.json": JSON.stringify({
+				runtime: "node",
+			}),
+		});
+
+		expect(disagrees.runtime).toBe(BotRuntime.Node);
+		expect(disagrees.warnings).toEqual([
+			BotInspectWarning.NoStart,
+			BotInspectWarning.NoManifest,
+			BotInspectWarning.ManifestDisagrees,
+		]);
+
+		const agrees = project({
+			...TELEGRAM_PYTHON,
+			"serverk.json": JSON.stringify({
+				runtime: "python",
+			}),
+		});
+
+		expect(agrees.runtime).toBe(BotRuntime.Python);
+		expect(agrees.warnings).toEqual([]);
+	});
+
 	it("installs with the file's own install command over the lockfile's", () => {
 		const result = project({
 			...DISCORD_NODE,
@@ -825,6 +1129,9 @@ describe("detect env suggestions", () => {
 		{
 			file: ".env.dist",
 		},
+		{
+			file: "sample.env",
+		},
 	];
 
 	for (const item of CASES) {

package/src/bot/detect/detect.ts

@@ -2,15 +2,16 @@ import type { BotFramework } from "./botFramework";
 import { BOT_FRAMEWORKS, type BotFrameworkSpec, botFrameworkSpec } from "./botFrameworks";
 import { BotInspectWarning } from "./botInspectWarning";
 import { BotPackageManager } from "./botPackageManager";
-import type { BotPlatform } from "./botPlatform";
+import { BotPlatform } from "./botPlatform";
 import { BOT_RUNTIME_PACKAGES, BotRuntime } from "./botRuntime";
 import { BOT_TOKEN_KEYS, platformOfKey } from "./botToken";
+import { nodeLtsMajorOf } from "./detectedVersion";
 import type { DetectEntry, DetectedCommand, DetectedEnvKey, DetectInput, DetectResult } from "./detectResult";
 import { DETECT_TABLE, type DetectVersionFile } from "./detectTable";
 import { ENV_EXAMPLE_FILES, ENV_FILE, isSecretEnvFile, parseEnvExample } from "./envExample";
 import { isEnvKey } from "./envKey";
 import { isNodeSource, isPythonSource, scanEnvKeys } from "./envScan";
-import { BOT_PROTECTED_KEYS, BOT_PROVIDED_KEYS, isReservedBotKey } from "./keys";
+import { BOT_PROTECTED_KEYS, BOT_PROVIDED_KEYS, isReservedBotKey, PORT } from "./keys";
 import { isSensitiveKey } from "./sensitiveKey";
 import { parseServerkJson, SERVERK_JSON, type ServerkJson } from "./serverkJson";
 
@@ -79,6 +80,8 @@ const TOKEN_KEY = /TOKEN/i;
 
 const BOT_KEY = /BOT/i;
 
+const WEBHOOK_KEY = /WEBHOOK/i;
+
 const NODE_IMPORT = /(?:\brequire\s*\(\s*|\bfrom\s+|\bimport\s*\(\s*|\bimport\s+)(["'])([^"'\n]+)\1/g;
 
 const PYTHON_IMPORT = /^[ \t]*(?:from[ \t]+([A-Za-z_]\w*)|import[ \t]+([A-Za-z_]\w*))/gm;
@@ -192,14 +195,16 @@ const START_FILES: readonly string[] = [
 ];
 
 const FIXED_FILES: readonly string[] = [
-	DETECT_TABLE.node.manifest,
-	REQUIREMENTS_FILE,
-	PYPROJECT_FILE,
-	DETECT_TABLE.procfile.file,
-	SERVERK_JSON,
-	...ENV_EXAMPLE_FILES,
-	...DETECT_TABLE.node.versionFiles.map((entry) => entry.file),
-	...DETECT_TABLE.python.versionFiles.map((entry) => entry.file),
+	...new Set([
+		DETECT_TABLE.node.manifest,
+		REQUIREMENTS_FILE,
+		PYPROJECT_FILE,
+		DETECT_TABLE.procfile.file,
+		SERVERK_JSON,
+		...ENV_EXAMPLE_FILES,
+		...DETECT_TABLE.node.versionFiles.map((entry) => entry.file),
+		...DETECT_TABLE.python.versionFiles.map((entry) => entry.file),
+	]),
 ];
 
 const sourceRank = (path: string) => {
@@ -587,7 +592,11 @@ const nodeBuildOf = (packageJson: PackageJson | null, manager: string): Detected
 	};
 };
 
-const versionFromFile = (text: string, spec: DetectVersionFile): string | null => {
+const versionFromFile = (
+	text: string,
+	spec: DetectVersionFile,
+	aliasOf: (value: string) => string | null,
+): string | null => {
 	for (const raw of text.split("\n")) {
 		let line = raw.trim();
 
@@ -623,7 +632,7 @@ const versionFromFile = (text: string, spec: DetectVersionFile): string | null =
 			line = line.slice(spec.prefix.length);
 		}
 
-		return VERSION_NUMBER.exec(line)?.[1] ?? null;
+		return VERSION_NUMBER.exec(line)?.[1] ?? aliasOf(line);
 	}
 
 	return null;
@@ -633,6 +642,7 @@ const versionFromFiles = (
 	specs: readonly DetectVersionFile[],
 	read: (path: string) => string | null,
 	parts: number,
+	aliasOf: (value: string) => string | null = () => null,
 ): string | null => {
 	for (const spec of specs) {
 		const text = read(spec.file);
@@ -641,7 +651,7 @@ const versionFromFiles = (
 			continue;
 		}
 
-		const version = versionFromFile(text, spec);
+		const version = versionFromFile(text, spec, aliasOf);
 
 		if (version !== null) {
 			return version.split(".").slice(0, parts).join(".");
@@ -731,7 +741,7 @@ const nodeRequirementOf = (
 		}
 	}
 
-	const version = versionFromFiles(DETECT_TABLE.node.versionFiles, read, 1);
+	const version = versionFromFiles(DETECT_TABLE.node.versionFiles, read, 1, nodeLtsMajorOf);
 
 	return version === null
 		? null
@@ -845,6 +855,19 @@ const committedWarnings = (paths: ReadonlySet<string>, warnings: Set<BotInspectW
 	}
 };
 
+const webPortWarning = (
+	platform: BotPlatform | null,
+	env: readonly DetectedEnvKey[],
+	warnings: Set<BotInspectWarning>,
+) => {
+	const keys = env.map((entry) => entry.key);
+	const webhook = platform !== BotPlatform.Discord && keys.some((key) => WEBHOOK_KEY.test(key));
+
+	if (keys.includes(PORT) || webhook) {
+		warnings.add(BotInspectWarning.WebPort);
+	}
+};
+
 interface EnvCollector {
 	add(key: string, source: string, sensitive: boolean | null, example: string | null): void;
 	entries: DetectedEnvKey[];
@@ -1165,6 +1188,8 @@ export const detect = (input: DetectInput): DetectResult => {
 	);
 	const platform = platformOf(serverk, framework, candidates, keyPlatforms, warnings);
 
+	webPortWarning(platform, env.entries, warnings);
+
 	return {
 		runtime,
 		package: runtime ? BOT_RUNTIME_PACKAGES[runtime] : null,

package/src/bot/detect/detectTable.ts

@@ -230,6 +230,10 @@ export const DETECT_TABLE: DetectTable = {
 				file: ".tool-versions",
 				tool: "nodejs",
 			},
+			{
+				file: ".tool-versions",
+				tool: "node",
+			},
 		],
 		defaultVersion: "24",
 	},