@serverkgg/bridge 0.1.9 → 0.1.11

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

@@ -0,0 +1,160 @@
+import { describe, expect, it } from "bun:test";
+import { BotInspectWarning } from "./botInspectWarning";
+import { BotRuntime } from "./botRuntime";
+import { detect } from "./detect";
+import { nodeLtsMajorOf } from "./detectedVersion";
+import { DETECT_TABLE } from "./detectTable";
+
+const DISCORD_NODE = {
+	"package.json": JSON.stringify({
+		name: "discord-bot",
+		main: "index.js",
+		dependencies: {
+			"discord.js": "^14.27.0",
+		},
+	}),
+	"index.js": 'import { Client } from "discord.js";\nawait client.login(process.env.DISCORD_TOKEN);\n',
+};
+
+const resultOf = (files: Record<string, string>) => {
+	const contents = {
+		...DISCORD_NODE,
+		...files,
+	};
+
+	return detect({
+		files: Object.keys(contents).map((path) => ({
+			path,
+		})),
+		contents,
+	});
+};
+
+const LTS_CASES: readonly {
+	alias: string;
+	major: string | null;
+}[] = [
+	{
+		alias: "lts/iron",
+		major: "20",
+	},
+	{
+		alias: "LTS/Hydrogen",
+		major: "18",
+	},
+	{
+		alias: "lts/jod",
+		major: "22",
+	},
+	{
+		alias: "lts-krypton",
+		major: "24",
+	},
+	{
+		alias: " lts/argon ",
+		major: "4",
+	},
+	{
+		alias: "lts/*",
+		major: null,
+	},
+	{
+		alias: "lts/-1",
+		major: null,
+	},
+	{
+		alias: "lts",
+		major: null,
+	},
+	{
+		alias: "lts/unknown",
+		major: null,
+	},
+	{
+		alias: "lts/constructor",
+		major: null,
+	},
+	{
+		alias: "node",
+		major: null,
+	},
+];
+
+describe("nodeLtsMajorOf", () => {
+	for (const item of LTS_CASES) {
+		it(`reads ${item.alias} as ${item.major ?? "no fixed major"}`, () => {
+			expect(nodeLtsMajorOf(item.alias)).toBe(item.major);
+		});
+	}
+});
+
+describe("detect", () => {
+	it("reads the Node major an .nvmrc names by its LTS codename", () => {
+		expect(
+			resultOf({
+				".nvmrc": "lts/iron\n",
+			}).nodeVersion,
+		).toBe("20");
+		expect(
+			resultOf({
+				".nvmrc": "LTS/Hydrogen\n",
+			}).nodeVersion,
+		).toBe("18");
+		expect(
+			resultOf({
+				".nvmrc": "lts/*\n",
+			}).nodeVersion,
+		).toBeNull();
+	});
+
+	it("warns when an LTS codename names a major the image does not run", () => {
+		const result = resultOf({
+			".nvmrc": "lts/hydrogen\n",
+		});
+
+		expect(DETECT_TABLE.node.defaultVersion).not.toBe("18");
+		expect(result.warnings).toContain(BotInspectWarning.NodeVersionUnmet);
+	});
+
+	it("reads the Node version from .tool-versions under mise's node and asdf's nodejs", () => {
+		expect(
+			resultOf({
+				".tool-versions": "node 20.11.0\n",
+			}).nodeVersion,
+		).toBe("20");
+		expect(
+			resultOf({
+				".tool-versions": "nodejs 20.11.0\n",
+			}).nodeVersion,
+		).toBe("20");
+		expect(
+			resultOf({
+				".tool-versions": "python 3.12.1\nnode lts/jod\n",
+			}).nodeVersion,
+		).toBe("22");
+	});
+
+	it("leaves the Python version untouched by a Node LTS codename", () => {
+		const result = detect({
+			files: [
+				{
+					path: "requirements.txt",
+				},
+				{
+					path: "main.py",
+				},
+				{
+					path: ".python-version",
+				},
+			],
+			contents: {
+				"requirements.txt": "python-telegram-bot==21.11.1\n",
+				"main.py": "from telegram.ext import Application\n",
+				".python-version": "lts/iron\n",
+			},
+		});
+
+		expect(result.runtime).toBe(BotRuntime.Python);
+		expect(result.pythonVersion).toBeNull();
+	});
+});

package/src/bot/detect/detectedVersion.ts

@@ -1,5 +1,60 @@
 export const DETECTED_VERSION_PATTERN = /^\d+(?:\.\d+)?$/;
 
+const NODE_LTS_MAJORS: ReadonlyMap<string, string> = new Map([
+	[
+		"argon",
+		"4",
+	],
+	[
+		"boron",
+		"6",
+	],
+	[
+		"carbon",
+		"8",
+	],
+	[
+		"dubnium",
+		"10",
+	],
+	[
+		"erbium",
+		"12",
+	],
+	[
+		"fermium",
+		"14",
+	],
+	[
+		"gallium",
+		"16",
+	],
+	[
+		"hydrogen",
+		"18",
+	],
+	[
+		"iron",
+		"20",
+	],
+	[
+		"jod",
+		"22",
+	],
+	[
+		"krypton",
+		"24",
+	],
+]);
+
+const NODE_LTS_ALIAS = /^lts[/-]([a-z]+)$/i;
+
 export const isDetectedVersion = (value: string | null): value is string => {
 	return value !== null && DETECTED_VERSION_PATTERN.test(value);
 };
+
+export const nodeLtsMajorOf = (alias: string): string | null => {
+	const codename = NODE_LTS_ALIAS.exec(alias.trim())?.[1];
+
+	return codename === undefined ? null : (NODE_LTS_MAJORS.get(codename.toLowerCase()) ?? null);
+};

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

@@ -69,6 +69,10 @@ describe("isSecretEnvFile", () => {
 			name: ".env.dist",
 			secret: false,
 		},
+		{
+			name: "sample.env",
+			secret: false,
+		},
 		{
 			name: ".env.defaults",
 			secret: false,

package/src/bot/detect/envExample.ts

@@ -7,6 +7,7 @@ export const ENV_EXAMPLE_FILES: readonly string[] = [
 	".env-example",
 	".env-sample",
 	".env.dist",
+	"sample.env",
 ];
 
 const ENV_TEMPLATE_FILES: ReadonlySet<string> = new Set([

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

@@ -33,6 +33,116 @@ describe("scanEnvKeys", () => {
 		]);
 	});
 
+	it("finds a Bun.env property read", () => {
+		expect(scanEnvKeys("src/index.ts", "const token = Bun.env.DISCORD_TOKEN;")).toEqual([
+			"DISCORD_TOKEN",
+		]);
+	});
+
+	it("finds a Bun.env bracket read", () => {
+		expect(scanEnvKeys("src/index.ts", 'const guildId = Bun.env["GUILD_ID"] ?? "";')).toEqual([
+			"GUILD_ID",
+		]);
+	});
+
+	it("finds names destructured from Bun.env", () => {
+		expect(scanEnvKeys("src/config.ts", "const { DISCORD_TOKEN, CLIENT_ID } = Bun.env;")).toEqual([
+			"DISCORD_TOKEN",
+			"CLIENT_ID",
+		]);
+	});
+
+	it("finds environs reads, bare and typed", () => {
+		expect(
+			scanEnvKeys(
+				"tgbot/config.py",
+				[
+					"from environs import Env",
+					"",
+					"env = Env()",
+					"env.read_env(path)",
+					'BOT_TOKEN = env.str("BOT_TOKEN")',
+					'ADMIN_ID = env.int("ADMIN_ID")',
+					'admin_ids = env.list("ADMINS", subcast=int)',
+					'use_redis = env.bool("USE_REDIS")',
+					'rate = env.float("RATE_LIMIT", 1.5)',
+					'webhook = env.url("WEBHOOK_URL")',
+					'extra = env.json("EXTRA_OPTIONS")',
+					"SECRET_KEY = env('SECRET_KEY')",
+				].join("\n"),
+			),
+		).toEqual([
+			"BOT_TOKEN",
+			"ADMIN_ID",
+			"ADMINS",
+			"USE_REDIS",
+			"RATE_LIMIT",
+			"WEBHOOK_URL",
+			"EXTRA_OPTIONS",
+			"SECRET_KEY",
+		]);
+	});
+
+	it("finds python-decouple reads", () => {
+		expect(
+			scanEnvKeys(
+				"bot/settings.py",
+				[
+					"import decouple",
+					"from decouple import config",
+					"",
+					'TOKEN = config("TOKEN")',
+					'ADMIN_ID = config("ADMIN_ID", cast=int)',
+					'DEBUG = decouple.config("DEBUG", default=False, cast=bool)',
+				].join("\n"),
+			),
+		).toEqual([
+			"TOKEN",
+			"ADMIN_ID",
+			"DEBUG",
+		]);
+	});
+
+	it("orders names by where the file reads them across os and environs", () => {
+		expect(
+			scanEnvKeys(
+				"bot/config.py",
+				[
+					"import os",
+					"from environs import Env",
+					"",
+					"env = Env()",
+					'BOT_TOKEN = env.str("BOT_TOKEN")',
+					'REDIS_URL = os.getenv("REDIS_URL")',
+					'ADMIN_ID = env.int("ADMIN_ID")',
+				].join("\n"),
+			),
+		).toEqual([
+			"BOT_TOKEN",
+			"REDIS_URL",
+			"ADMIN_ID",
+		]);
+	});
+
+	it("reads no key from calls that only look like environs or decouple", () => {
+		expect(
+			scanEnvKeys(
+				"bot/main.py",
+				[
+					"env = {}",
+					'env["x"] = 1',
+					'value = env["x"]',
+					'logger.config("level")',
+					'logger.config("LEVEL")',
+					'config("level")',
+					'self.env.str("NOPE")',
+					'client.getenv("NOPE")',
+					'cfg.environ.get("NOPE")',
+				].join("\n"),
+			),
+		).toEqual([]);
+	});
+
 	it("reads nothing from files that are not code", () => {
 		expect(scanEnvKeys("README.md", "process.env.A")).toEqual([]);
 	});

package/src/bot/detect/envScan.ts

@@ -13,12 +13,14 @@ export const PYTHON_SOURCE_EXTENSIONS: readonly string[] = [
 
 const NAME = "([A-Za-z_][A-Za-z0-9_]*)";
 
+const UPPER_NAME = "([A-Z_][A-Z0-9_]*)";
+
 const NODE_PATTERNS: readonly RegExp[] = [
-	new RegExp(`\\bprocess\\.env\\.${NAME}`, "g"),
-	new RegExp(`\\bprocess\\.env\\[\\s*["'\`]${NAME}["'\`]\\s*\\]`, "g"),
+	new RegExp(`\\b(?:process|Bun)\\.env\\.${NAME}`, "g"),
+	new RegExp(`\\b(?:process|Bun)\\.env\\[\\s*["'\`]${NAME}["'\`]\\s*\\]`, "g"),
 ];
 
-const NODE_DESTRUCTURE = /\{([^{}]{1,2000})\}\s*=\s*process\.env\b/g;
+const NODE_DESTRUCTURE = /\{([^{}]{1,2000})\}\s*=\s*(?:process|Bun)\.env\b/g;
 
 const DESTRUCTURED_NAME = /^\s*([A-Za-z_][A-Za-z0-9_]*)/;
 
@@ -26,6 +28,8 @@ 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"),
+	new RegExp(`(?<![\\w.])env(?:\\.\\w+)?\\(\\s*["']${UPPER_NAME}["']`, "g"),
+	new RegExp(`(?<![\\w.])(?:decouple\\.)?config\\(\\s*["']${UPPER_NAME}["']`, "g"),
 ];
 
 interface Found {

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

@@ -3,9 +3,21 @@ import {
 	BOT_AMBIENT_KEYS,
 	BOT_PLATFORM_KEYS,
 	BOT_PLATFORM_SECRET_KEYS,
+	BOT_PORT_1,
+	BOT_PORT_1_KEY,
+	BOT_PORT_2,
+	BOT_PORT_2_KEY,
 	BOT_PROTECTED_KEYS,
 	BOT_PROVIDED_KEYS,
+	BOT_RAW_PORT_KEYS,
+	BOT_WEB,
+	BOT_WEB_PORT_KEY,
 	isReservedBotKey,
+	PORT,
+	SERVERK_PORT_1,
+	SERVERK_PORT_2,
+	SERVERK_WEB_HOST,
+	SERVERK_WEB_URL,
 } from "./keys";
 
 describe("isReservedBotKey", () => {
@@ -21,6 +33,21 @@ describe("isReservedBotKey", () => {
 		}
 	});
 
+	it("reserves the web and port switches the platform sets", () => {
+		for (const key of [
+			BOT_WEB,
+			BOT_PORT_1,
+			BOT_PORT_2,
+		]) {
+			expect(BOT_PLATFORM_KEYS).toContain(key);
+			expect(isReservedBotKey(key)).toBe(true);
+		}
+	});
+
+	it("leaves PORT to the customer, so a bot without the web port keeps its own", () => {
+		expect(isReservedBotKey(PORT)).toBe(false);
+	});
+
 	it("leaves the customer's own keys alone, case included", () => {
 		for (const key of [
 			"DISCORD_TOKEN",
@@ -47,6 +74,19 @@ describe("BOT_AMBIENT_KEYS", () => {
 		}
 	});
 
+	it("holds the web address and raw port variables, so detection never asks for them", () => {
+		for (const key of [
+			SERVERK_WEB_URL,
+			SERVERK_WEB_HOST,
+			SERVERK_PORT_1,
+			SERVERK_PORT_2,
+		]) {
+			expect(BOT_PROVIDED_KEYS).toContain(key);
+			expect(BOT_AMBIENT_KEYS).toContain(key);
+			expect(isReservedBotKey(key)).toBe(true);
+		}
+	});
+
 	it("leaves a bot's own keys out", () => {
 		for (const key of [
 			"DISCORD_TOKEN",
@@ -57,3 +97,13 @@ describe("BOT_AMBIENT_KEYS", () => {
 		}
 	});
 });
+
+describe("BOT_RAW_PORT_KEYS", () => {
+	it("names the two raw ports apart from the web port", () => {
+		expect(BOT_RAW_PORT_KEYS).toEqual([
+			BOT_PORT_1_KEY,
+			BOT_PORT_2_KEY,
+		]);
+		expect(BOT_RAW_PORT_KEYS).not.toContain(BOT_WEB_PORT_KEY);
+	});
+});

package/src/bot/detect/keys.ts

@@ -18,12 +18,49 @@ export const SNAPSHOT_ID = "SNAPSHOT_ID";
 
 export const BOT_PLATFORM = "BOT_PLATFORM";
 
+export const BOT_WEB = "BOT_WEB";
+
+export const BOT_PORT_1 = "BOT_PORT_1";
+
+export const BOT_PORT_2 = "BOT_PORT_2";
+
+export const BOT_SWITCH_ON = "on";
+
 export const GIT_TOKEN = "GIT_TOKEN";
 
 export const SERVERK_BOT = "SERVERK_BOT";
 
 export const SERVERK_SERVER_CODE = "SERVERK_SERVER_CODE";
 
+export const SERVERK_WEB_URL = "SERVERK_WEB_URL";
+
+export const SERVERK_WEB_HOST = "SERVERK_WEB_HOST";
+
+export const SERVERK_PORT_1 = "SERVERK_PORT_1";
+
+export const SERVERK_PORT_2 = "SERVERK_PORT_2";
+
+export const PORT = "PORT";
+
+export const BOT_WEB_PORT_KEY = "web";
+
+export const BOT_PORT_1_KEY = "port1";
+
+export const BOT_PORT_2_KEY = "port2";
+
+export const BOT_RAW_PORT_KEYS = [
+	BOT_PORT_1_KEY,
+	BOT_PORT_2_KEY,
+] as const;
+
+export type BotRawPortKey = (typeof BOT_RAW_PORT_KEYS)[number];
+
+export const BOT_PORT_SWITCHES = {
+	[BOT_WEB_PORT_KEY]: BOT_WEB,
+	[BOT_PORT_1_KEY]: BOT_PORT_1,
+	[BOT_PORT_2_KEY]: BOT_PORT_2,
+} as const;
+
 export const BOT_PLATFORM_KEYS: readonly string[] = [
 	REPO_URL,
 	REPO_REF,
@@ -34,6 +71,9 @@ export const BOT_PLATFORM_KEYS: readonly string[] = [
 	DEPLOYMENT_ID,
 	SNAPSHOT_ID,
 	BOT_PLATFORM,
+	BOT_WEB,
+	BOT_PORT_1,
+	BOT_PORT_2,
 ];
 
 export const BOT_PLATFORM_SECRET_KEYS: readonly string[] = [
@@ -52,6 +92,10 @@ export const BOT_PROVIDED_KEYS: readonly string[] = [
 	SERVERK_BOT,
 	SERVERK_SERVER_CODE,
 	BOT_PLATFORM,
+	SERVERK_WEB_URL,
+	SERVERK_WEB_HOST,
+	SERVERK_PORT_1,
+	SERVERK_PORT_2,
 ];
 
 export const BOT_AMBIENT_KEYS: readonly string[] = [
@@ -59,7 +103,7 @@ export const BOT_AMBIENT_KEYS: readonly string[] = [
 	...BOT_PROVIDED_KEYS,
 	"NODE_ENV",
 	"NODE_OPTIONS",
-	"PORT",
+	PORT,
 	"HOST",
 	"HOSTNAME",
 	"DEBUG",

package/src/cli/validate.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
 import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { renderDetectTable } from "../bot/detect";
+import { BOT_SWITCH_ON, BOT_WEB, BOT_WEB_PORT_KEY, renderDetectTable } from "../bot/detect";
 import { BridgeKind, BridgeSetupStepKind } from "../core";
 import { GuideOpenTab, type GuidePack, type ParsedBlock, type ParsedLeafBlock } from "../guides";
 import { MANIFEST_SCHEMA_VERSION, PackageKind, type RunnableManifest } from "../manifest";
@@ -600,7 +600,7 @@ describe("validating a bot package", () => {
 		);
 	});
 
-	it("warns about a port on a bot but still validates it", async () => {
+	it("warns about a bot port with no activeWhen but still validates it", async () => {
 		writeBot(
 			botManifest({
 				container: {
@@ -616,10 +616,40 @@ describe("validating a bot package", () => {
 
 		expect(lines).toContain("bot-node is valid");
 		expect(lines).toContain(
-			"  warning: a bot package declares 1 port(s); bots need none — remove them unless a webhook needs a public port",
+			"  warning: a bot package declares 1 port(s) with no activeWhen; a bot publishes a port only while its author turns it on",
 		);
 	});
 
+	it("validates a bot web port its author turns on without a warning", async () => {
+		writeBot(
+			botManifest({
+				container: {
+					image: "serverkgg/bot-node",
+					ports: [
+						{
+							...WEBHOOK_PORT,
+							key: BOT_WEB_PORT_KEY,
+							web: true,
+							activeWhen: [
+								{
+									variable: BOT_WEB,
+									values: [
+										BOT_SWITCH_ON,
+									],
+								},
+							],
+						},
+					],
+				},
+			}),
+		);
+
+		await validate();
+
+		expect(lines).toContain("bot-node is valid");
+		expect(lines.some((line) => line.includes("warning:"))).toBe(false);
+	});
+
 	it("fails a bot that declares platform secrets", async () => {
 		writeBot(
 			botManifest({

package/src/cli/validate.ts

@@ -4,7 +4,7 @@ import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { z } from "zod";
 import { type ArticlePack, compileArticles } from "../blog";
-import { DETECT_TABLE_FILE, renderDetectTable } from "../bot/detect";
+import { BOT_PORT_SWITCHES, DETECT_TABLE_FILE, renderDetectTable } from "../bot/detect";
 import { BridgeKind, PortProtocol } from "../core";
 import {
 	GuideOpenTab,
@@ -599,14 +599,18 @@ export const setupReportLines = (setup: BridgeSetupModule | undefined): string[]
 };
 
 export const botPortLines = (manifest: RunnableManifest): string[] => {
-	const ports = manifest.container.ports.length;
+	if (!isBotManifest(manifest)) {
+		return [];
+	}
 
-	if (!isBotManifest(manifest) || ports === 0) {
+	const ungated = manifest.container.ports.filter((port) => port.activeWhen.length === 0).length;
+
+	if (ungated === 0) {
 		return [];
 	}
 
 	return [
-		`  warning: a bot package declares ${ports} port(s); bots need none — remove them unless a webhook needs a public port`,
+		`  warning: a bot package declares ${ungated} port(s) with no activeWhen; a bot publishes a port only while its author turns it on`,
 	];
 };
 
@@ -680,7 +684,11 @@ const validateRunnablePackage = async (
 	}
 
 	validateDriver(driver);
-	validatePortActivation(manifest.container.ports, driver);
+	validatePortActivation(
+		manifest.container.ports,
+		driver,
+		isBotManifest(manifest) ? Object.values(BOT_PORT_SWITCHES) : [],
+	);
 
 	const confirmLines = confirmReportLines(driver);