@serverkgg/bridge 0.1.5 → 0.1.7

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.1.5",
+	"version": "0.1.7",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
@@ -39,9 +39,9 @@
 	},
 	"scripts": {
 		"tsc": "tsc",
-		"test": "bun test --parallel"
+		"test": "bun test --parallel=8"
 	},
 	"dependencies": {
-		"zod": "4.6.4"
+		"zod": "4.6.5"
 	}
 }

package/src/bot/botCauses.test.ts

@@ -13,6 +13,10 @@ const CASES: readonly {
 		line: "Error [TokenInvalid]: An invalid token was provided.",
 		cause: BridgeCrashCause.TokenInvalid,
 	},
+	{
+		line: "Error [TOKEN_INVALID]: An invalid token was provided.",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
 	{
 		line: "discord.errors.LoginFailure: Improper token has been passed.",
 		cause: BridgeCrashCause.TokenInvalid,
@@ -37,6 +41,46 @@ const CASES: readonly {
 		line: "aiogram.exceptions.TelegramUnauthorizedError: Telegram server says - Unauthorized",
 		cause: BridgeCrashCause.TokenInvalid,
 	},
+	{
+		line: "pyrogram.errors.exceptions.bad_request_400.AccessTokenInvalid: Telegram says: [400 ACCESS_TOKEN_INVALID] - The bot access token is invalid",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "pyrogram.errors.exceptions.bad_request_400.AccessTokenExpired: Telegram says: [400 ACCESS_TOKEN_EXPIRED] - The bot token has expired",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "TypeError: expected token to be a str, received NoneType instead",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "TypeError: expected token to be a str, received <class 'NoneType'> instead",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "TypeError: token must be of type str, not NoneType",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "TypeError: token must be of type str, got NoneType instead",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "TypeError: The token provided was of type <class 'NoneType'> but was expected to be str",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "Error: Empty token!",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "aiogram.utils.token.TokenValidationError: Token is invalid!",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
+	{
+		line: "aiogram.utils.token.TokenValidationError: Token is invalid! It must be 'str' type instead of <class 'NoneType'> type.",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
 	{
 		line: "Error: Used disallowed intents",
 		cause: BridgeCrashCause.IntentsDisallowed,
@@ -45,6 +89,10 @@ const CASES: readonly {
 		line: "Error [DisallowedIntents]: Privileged intent provided is not enabled or whitelisted.",
 		cause: BridgeCrashCause.IntentsDisallowed,
 	},
+	{
+		line: "Error [DISALLOWED_INTENTS]: Privileged intent provided is not enabled or whitelisted.",
+		cause: BridgeCrashCause.IntentsDisallowed,
+	},
 	{
 		line: "discord.errors.PrivilegedIntentsRequired: Shard ID None is requesting privileged intents that have not been explicitly enabled in the developer portal.",
 		cause: BridgeCrashCause.IntentsDisallowed,
@@ -257,6 +305,14 @@ describe("BOT_CRASH_EVIDENCE", () => {
 		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.Unknown);
 	});
 
+	it("leaves a TypeError about something other than the token unexplained", () => {
+		const { ring, print } = botRing();
+
+		print("TypeError: expected str, bytes or os.PathLike object, not NoneType");
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.Unknown);
+	});
+
 	it("calls exit 137 out of memory only when the record carries the flag", () => {
 		const unflagged = botRing();
 

package/src/bot/botCauses.ts

@@ -4,7 +4,7 @@ import { BridgeEventName } from "../protocol";
 export const BOT_CRASH_EVIDENCE: readonly BridgeEventPattern[] = [
 	{
 		match:
-			/\[TokenInvalid\]|An invalid token was provided|LoginFailure: Improper token|\b401:? Unauthorized\b|\bInvalidToken\b|TelegramUnauthorizedError/,
+			/\[TokenInvalid\]|An invalid token was provided|LoginFailure: Improper token|\b401:? Unauthorized\b|\bInvalidToken\b|TelegramUnauthorizedError|\bACCESS_TOKEN_(?:INVALID|EXPIRED)\b/,
 		emit: BridgeEventName.TokenInvalid,
 	},
 	{
@@ -13,7 +13,13 @@ export const BOT_CRASH_EVIDENCE: readonly BridgeEventPattern[] = [
 		emit: BridgeEventName.TokenInvalid,
 	},
 	{
-		match: /Used disallowed intents|\[DisallowedIntents\]|PrivilegedIntentsRequired|close code:? 4014\b/,
+		match:
+			/TypeError: (?:expected token to be a str, received|token must be of type str, (?:not|got) |The token provided was of type .+ but was expected to be str)|\bError: Empty token!|TokenValidationError: Token is invalid!/,
+		emit: BridgeEventName.TokenInvalid,
+	},
+	{
+		match:
+			/Used disallowed intents|\[DisallowedIntents\]|Privileged intent provided is not enabled or whitelisted|PrivilegedIntentsRequired|close code:? 4014\b/,
 		emit: BridgeEventName.IntentsDisallowed,
 	},
 	{

package/src/bot/detect/botFrameworks.ts

@@ -174,6 +174,7 @@ export const BOT_FRAMEWORKS: readonly BotFrameworkSpec[] = [
 		platform: BotPlatform.Telegram,
 		packages: [
 			"pyrogram",
+			"kurigram",
 		],
 		modules: [
 			"pyrogram",

package/src/bot/detect/botInspectWarning.ts

@@ -3,6 +3,7 @@ export enum BotInspectWarning {
 	NodeVersionUnmet = "node-version-unmet",
 	LockfileNotHonoured = "lockfile-not-honoured",
 	NoStart = "no-start",
+	WindowsCommand = "windows-command",
 	NoManifest = "no-manifest",
 	EnvCommitted = "env-committed",
 	NodeModulesCommitted = "node-modules-committed",

package/src/bot/detect/corpus/anasty17-mirror-leech-telegram-bot.json

@@ -35,8 +35,8 @@
 	"expected": {
 		"runtime": "python",
 		"packageManager": "pip",
-		"framework": null,
-		"platform": null,
+		"framework": "pyrogram",
+		"platform": "telegram",
 		"install": "uv pip install -r requirements.txt",
 		"build": null,
 		"start": "python -m bot",

package/src/bot/detect/corpus/anidiotsguide-guidebot.json

@@ -18,6 +18,7 @@
 		"yarn.lock"
 	],
 	"contents": {
+		".env-example": "DISCORD_TOKEN=\nOWNER=",
 		"package.json": "{\n  \"name\": \"guidebot\",\n  \"version\": \"2.1.0\",\n  \"description\": \"A boilerplate example bot with command handler and reloadable commands. Updated and Maintained by the Idiot's Guide Community\",\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"start\": \"node index.js\"\n  },\n  \"engines\": {\n    \"node\": \">=16\"\n  },\n  \"repository\": {\n    \"type\": \"git\",\n    \"url\": \"git+https://github.com/AnIdiotsGuide/guidebot.git\"\n  },\n  \"author\": \"Evelyne Lachance <eslachance@gmail.com> (http://evie.codes)\",\n  \"contributors\": [\n    \"York (http://anidiots.guide)\"\n  ],\n  \"license\": \"MIT\",\n  \"bugs\": {\n    \"url\": \"https://github.com/AnIdiotsGuide/guidebot/issues\"\n  },\n  \"homepage\": \"https://github.com/AnIdiotsGuide/guidebot#readme\",\n  \"dependencies\": {\n    \"@discordjs/builders\": \"^0.2.0\",\n    \"@sapphire/time-utilities\": \"^1.3.8\",\n    \"colorette\": \"^1.3.0\",\n    \"discord.js\": \"^13.0.1\",\n    \"dotenv\": \"^10.0.0\",\n    \"enmap\": \"^5.8.5\"\n  },\n  \"devDependencies\": {\n    \"eslint\": \"^7.30.0\",\n    \"eslint-config-airbnb-base\": \"^14.2.1\",\n    \"eslint-config-standard\": \"^16.0.3\",\n    \"eslint-plugin-import\": \"^2.23.4\",\n    \"eslint-plugin-node\": \"^11.1.0\",\n    \"eslint-plugin-promise\": \"^5.1.0\"\n  }\n}\n"
 	},
 	"expected": {
@@ -30,7 +31,7 @@
 		"start": "node index.js",
 		"nodeVersion": "16",
 		"pythonVersion": null,
-		"tokenKey": null,
+		"tokenKey": "DISCORD_TOKEN",
 		"warnings": []
 	}
 }

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

@@ -32,8 +32,8 @@
 	"expected": {
 		"runtime": "python",
 		"packageManager": "pip",
-		"framework": null,
-		"platform": null,
+		"framework": "pyrogram",
+		"platform": "telegram",
 		"install": "uv pip install -r requirements.txt",
 		"build": null,
 		"start": "bash start",

package/src/bot/detect/corpus/latand-tgbot_template_v3.json

@@ -17,6 +17,7 @@
 		"requirements.txt"
 	],
 	"contents": {
+		".env.dist": "BOT_TOKEN=123456:Your-TokEn_ExaMple\nADMINS=123456,654321\nUSE_REDIS=False\n\n#POSTGRES_USER=someusername\n#POSTGRES_PASSWORD=postgres_pass12345\n#POSTGRES_DB=bot\n#DB_HOST=pg_database\n\n# REDIS_HOST=redis_cache\n# REDIS_PORT=6388\n# REDIS_DB=1\n# REDIS_PASSWORD=someredispass\n\n\n#WEBHOOK_EXPOSE=8001\n#WEBHOOK_APP_NAME=webhook\n",
 		"requirements.txt": "aiogram~=3.0\nenvirons~=9.0\nredis\nbetterlogging\n\n# # For enabling api:\n# backoff\n# ujson\n# yarl\n\n# # For PostgreSQL sqlalchemy + alembic:\n# sqlalchemy~=2.0\n# alembic~=1.0\n# asyncpg\n"
 	},
 	"expected": {
@@ -29,7 +30,7 @@
 		"start": "python bot.py",
 		"nodeVersion": null,
 		"pythonVersion": null,
-		"tokenKey": null,
+		"tokenKey": "BOT_TOKEN",
 		"warnings": [
 			"unpinned-requirements"
 		]

package/src/bot/detect/corpus/mericcan41-discordjs-v14-template-ts.json

@@ -28,6 +28,8 @@
 		"nodeVersion": null,
 		"pythonVersion": null,
 		"tokenKey": null,
-		"warnings": []
+		"warnings": [
+			"windows-command"
+		]
 	}
 }

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

@@ -21,6 +21,7 @@
 		"tsconfig.json"
 	],
 	"contents": {
+		".env-sample": "BOT_TOKEN=\"\"\nUSERNAME=\"\"\nWEBHOOK_URL=\"\"\nPORT=\"3000\"\nNODE_ENV=\"development\"\n",
 		"package.json": "{\n  \"name\": \"telegram-bot-boilerplate\",\n  \"version\": \"1.0.0\",\n  \"description\": \"Telegram Bot Boilerplate\",\n  \"author\": \"Yuri Nezdemkovski <yuri@nezdemkovski.com> (https://nezdemkovski.com/)\",\n  \"homepage\": \"https://github.com/nezdemkovski/telegram-bot-boilerplate\",\n  \"license\": \"MIT\",\n  \"engines\": {\n    \"bun\": \">=1\"\n  },\n  \"dependencies\": {\n    \"grammy\": \"^1.40.0\"\n  },\n  \"devDependencies\": {\n    \"bun-types\": \"1.3.9\",\n    \"eslint\": \"^10.0.1\",\n    \"eslint-config-prettier\": \"^10.1.8\",\n    \"prettier\": \"^3.8.1\",\n    \"typescript\": \"^5.9.3\",\n    \"typescript-eslint\": \"^8.56.0\"\n  },\n  \"scripts\": {\n    \"dev\": \"bun --watch src/index.ts\",\n    \"build\": \"bun build src/index.ts --outdir dist --target bun --minify\",\n    \"start\": \"NODE_ENV=production bun dist/index.js\",\n    \"typecheck\": \"tsc --noEmit\",\n    \"lint\": \"eslint src\",\n    \"format\": \"prettier --write 'src/**/*.ts'\"\n  }\n}\n"
 	},
 	"expected": {
@@ -33,7 +34,7 @@
 		"start": "NODE_ENV=production bun dist/index.js",
 		"nodeVersion": null,
 		"pythonVersion": null,
-		"tokenKey": null,
+		"tokenKey": "BOT_TOKEN",
 		"warnings": []
 	}
 }

package/src/bot/detect/corpus/tgbot-collection-ytdlbot.json

@@ -28,8 +28,8 @@
 	"expected": {
 		"runtime": "python",
 		"packageManager": "pip",
-		"framework": null,
-		"platform": null,
+		"framework": "pyrogram",
+		"platform": "telegram",
 		"install": "uv pip install -r requirements.txt",
 		"build": null,
 		"start": "python src/main.py",

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

@@ -604,6 +604,24 @@ describe("detect warnings", () => {
 		]);
 	});
 
+	it("warns when a start or build script runs a Windows-only command", () => {
+		const scripts = (start: string, build: string) => {
+			return project({
+				"package.json": JSON.stringify({
+					scripts: {
+						start,
+						build,
+					},
+				}),
+				"package-lock.json": "{}",
+			}).warnings;
+		};
+
+		expect(scripts("cls && node build/index.js", "cls && node build.js")).toContain(BotInspectWarning.WindowsCommand);
+		expect(scripts("node build/index.js", "CLS&&node build.js")).toContain(BotInspectWarning.WindowsCommand);
+		expect(scripts("node index.js", "tsc")).not.toContain(BotInspectWarning.WindowsCommand);
+	});
+
 	it("flags two runtimes and picks the one whose framework it found", () => {
 		const result = project({
 			...DISCORD_NODE,
@@ -630,6 +648,17 @@ describe("detect warnings", () => {
 		expect(result.warnings).toContain(BotInspectWarning.TwoPlatforms);
 	});
 
+	it("reads kurigram, the Pyrogram fork the corpus bots install, as Pyrogram on Telegram", () => {
+		const result = project({
+			"requirements.txt": "kurigram>=2.2.25\ntgcrypto\n",
+			"bot/__main__.py": "",
+		});
+
+		expect(result.framework).toBe(BotFramework.Pyrogram);
+		expect(result.platform).toBe(BotPlatform.Telegram);
+		expect(result.warnings).not.toContain(BotInspectWarning.TwoPlatforms);
+	});
+
 	it("drops keys the platform owns and warns, but keeps quiet about keys the runtime gives anyway", () => {
 		const result = project({
 			...DISCORD_NODE,
@@ -784,6 +813,45 @@ describe("detect env suggestions", () => {
 		]);
 	});
 
+	const CASES: readonly {
+		file: string;
+	}[] = [
+		{
+			file: ".env-example",
+		},
+		{
+			file: ".env-sample",
+		},
+		{
+			file: ".env.dist",
+		},
+	];
+
+	for (const item of CASES) {
+		it(`reads ${item.file} the way it reads .env.example`, () => {
+			const result = project({
+				"package.json": "{}",
+				[item.file]: "DISCORD_TOKEN=\nOWNER=\n",
+			});
+
+			expect(result.env).toEqual([
+				{
+					key: "DISCORD_TOKEN",
+					sensitive: true,
+					source: item.file,
+					example: null,
+				},
+				{
+					key: "OWNER",
+					sensitive: false,
+					source: item.file,
+					example: null,
+				},
+			]);
+			expect(result.tokenKey).toBe("DISCORD_TOKEN");
+		});
+	}
+
 	it("suggests the keys of a skipped .env after the example files, never its values", () => {
 		const result = detect({
 			files: [

package/src/bot/detect/detect.ts

@@ -53,6 +53,12 @@ const NOT_A_BOT_PACKAGE: ReadonlySet<string> = new Set([
 	"scripts",
 ]);
 
+const WINDOWS_COMMANDS: ReadonlySet<string> = new Set([
+	"cls",
+]);
+
+const COMMAND_SEPARATOR = /&&|\|\||;|\|/;
+
 const MANAGER_FIELD = /^(npm|pnpm|yarn|bun)@(\d+)/;
 
 const ENGINE_MANAGERS: readonly string[] = [
@@ -394,6 +400,18 @@ const frameworksOf = (
 	return declared.length > 0 ? declared : specs.filter((spec) => spec.modules.some((name) => imports.has(name)));
 };
 
+const runsWindowsCommand = (command: string | null) => {
+	if (command === null) {
+		return false;
+	}
+
+	return command.split(COMMAND_SEPARATOR).some((segment) => {
+		const program = segment.trim().split(/\s+/)[0] ?? "";
+
+		return WINDOWS_COMMANDS.has(program.toLowerCase());
+	});
+};
+
 const procfileCommand = (text: string | null): DetectedCommand | null => {
 	if (text === null) {
 		return null;
@@ -1094,6 +1112,18 @@ export const detect = (input: DetectInput): DetectResult => {
 		warnings.add(BotInspectWarning.NoStart);
 	}
 
+	const buildScript = recordOf(packageJson?.scripts)[DETECT_TABLE.node.buildScript];
+
+	const commands = [
+		start?.command ?? null,
+		build?.command ?? null,
+		build?.source === DETECT_TABLE.node.manifest && typeof buildScript === "string" ? buildScript : null,
+	];
+
+	if (commands.some(runsWindowsCommand)) {
+		warnings.add(BotInspectWarning.WindowsCommand);
+	}
+
 	committedWarnings(paths, warnings);
 
 	const env = envCollector(warnings);

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

@@ -57,6 +57,14 @@ describe("isSecretEnvFile", () => {
 			name: ".env.template",
 			secret: false,
 		},
+		{
+			name: ".env-example",
+			secret: false,
+		},
+		{
+			name: ".env-sample",
+			secret: false,
+		},
 		{
 			name: ".env.dist",
 			secret: false,

package/src/bot/detect/envExample.ts

@@ -4,11 +4,13 @@ export const ENV_EXAMPLE_FILES: readonly string[] = [
 	".env.example",
 	".env.sample",
 	".env.template",
+	".env-example",
+	".env-sample",
+	".env.dist",
 ];
 
 const ENV_TEMPLATE_FILES: ReadonlySet<string> = new Set([
 	...ENV_EXAMPLE_FILES,
-	".env.dist",
 	".env.defaults",
 ]);
 

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/rcon/rconClient.test.ts

@@ -19,6 +19,7 @@ import { createRconWriter, type RconWriter } from "./rconWriter";
 const HOST = "127.0.0.1";
 
 const CLOSED_PORT = 59_433;
+const CLOSED_HOST = "::1";
 
 const PASSWORD = "kX7-forbidden-in-errors";
 
@@ -1005,7 +1006,7 @@ describe("RconClient failures", () => {
 
 	it("reports a port nothing listens on", async () => {
 		const client = new RconClient({
-			host: HOST,
+			host: CLOSED_HOST,
 			port: CLOSED_PORT,
 			password: PASSWORD,
 			timeoutMs: 1000,
@@ -1475,7 +1476,7 @@ describe("RconClient secrecy", () => {
 		});
 
 		const unreachable = new RconClient({
-			host: HOST,
+			host: CLOSED_HOST,
 			port: CLOSED_PORT,
 			password: PASSWORD,
 			timeoutMs: 500,