@serverkgg/bridge 0.1.8 → 0.1.10

package/src/bot/detect/corpus/mruniquehacker-knightbot-md.json

@@ -0,0 +1,35 @@
+{
+	"source": {
+		"url": "https://github.com/mruniquehacker/Knightbot-MD",
+		"branch": "main",
+		"commit": "871bce832169c3a52a632dc100c1f235cb35977c",
+		"stars": 8128
+	},
+	"files": [
+		".gitignore",
+		"README.md",
+		"config.js",
+		"index.js",
+		"main.js",
+		"package.json",
+		"settings.js"
+	],
+	"contents": {
+		"package.json": "{\n  \"name\": \"knightbot\",\n  \"version\": \"1.0.0\",\n  \"description\": \"WhatsApp Bot\",\n  \"main\": \"index.js\",\n  \"scripts\": {\n    \"start\": \"node index.js\",\n    \"start:optimized\": \"node --max-old-space-size=512 --optimize-for-size --gc-interval=100 index.js\",\n    \"cleanup\": \"node cleanup.js\",\n    \"reset-session\": \"node reset-session.js\",\n    \"start:clean\": \"npm run cleanup && npm run start:optimized\",\n    \"start:fresh\": \"npm run reset-session && npm start\",\n    \"install:panel\": \"npm install --legacy-peer-deps\",\n    \"install:force\": \"npm install --force\",\n    \"test\": \"echo \\\"Error: no test specified\\\" && exit 1\",\n    \"docker:build\": \"docker build -t docker run -e SESSION_ID=$SESSION_ID knightbot\"\n  },\n  \"keywords\": [\n    \"whatsapp-bot\"\n  ],\n  \"author\": \"\",\n  \"license\": \"ISC\",\n  \"dependencies\": {\n    \"@adiwajshing/keyed-db\": \"^0.2.4\",\n    \"@ffmpeg/ffmpeg\": \"^0.12.15\",\n    \"@hapi/boom\": \"^10.0.1\",\n    \"@types/node\": \"^18.0.6\",\n    \"@whiskeysockets/baileys\": \"^v7.0.0-rc.9\",\n    \"awesome-phonenumber\": \"^5.9.0\",\n    \"axios\": \"^1.8.4\",\n    \"chalk\": \"^4.1.2\",\n    \"cheerio\": \"^1.0.0-rc.12\",\n    \"cookie\": \"^0.5.0\",\n    \"dotenv\": \"^16.4.5\",\n    \"events\": \"^3.3.0\",\n    \"file-type\": \"^16.5.4\",\n    \"fluent-ffmpeg\": \"^2.1.3\",\n    \"form-data\": \"^4.0.1\",\n    \"fs-extra\": \"^11.2.0\",\n    \"gtts\": \"^0.2.1\",\n    \"human-readable\": \"^0.2.1\",\n    \"jimp\": \"^1.6.0\",\n    \"jsdom\": \"^22.1.0\",\n    \"libphonenumber-js\": \"^1.11.18\",\n    \"libsignal\": \"^2.0.1\",\n    \"link-preview-js\": \"^3.0.5\",\n    \"moment-timezone\": \"^0.5.43\",\n    \"mumaker\": \"^2.0.0\",\n    \"node-cache\": \"^5.1.2\",\n    \"node-fetch\": \"^2.7.0\",\n    \"node-id3\": \"^0.2.3\",\n    \"node-webpmux\": \"^3.1.0\",\n    \"node-youtube-music\": \"^0.8.3\",\n    \"performance-now\": \"^2.1.0\",\n    \"phin\": \"^3.7.1\",\n    \"pino\": \"^8.21.0\",\n    \"qrcode\": \"^1.5.4\",\n    \"qrcode-reader\": \"^1.0.4\",\n    \"qrcode-terminal\": \"^0.12.0\",\n    \"request\": \"^2.88.2\",\n    \"ruhend-scraper\": \"^8.3.0\",\n    \"safe-stable-stringify\": \"^2.5.0\",\n    \"set-cookie\": \"^0.0.4\",\n    \"sharp\": \"^0.32.6\",\n    \"tough-cookie\": \"^5.0.0\",\n    \"translate-google-api\": \"^1.0.4\",\n    \"ws\": \"^8.17.1\",\n    \"yargs\": \"^17.6.0\",\n    \"yargs-parser\": \"^21.1.1\",\n    \"youtube-yts\": \"^2.0.0\",\n    \"youtubedl-core\": \"^4.11.7\",\n    \"yt-search\": \"^2.12.1\",\n    \"ytdl-core\": \"^4.11.5\"\n  },\n  \"overrides\": {\n    \"jimp\": \"^1.6.0\"\n  },\n  \"engines\": {\n    \"node\": \">=18.0.0\"\n  }\n}\n"
+	},
+	"expected": {
+		"runtime": "node",
+		"packageManager": "npm",
+		"framework": null,
+		"platform": null,
+		"install": "npm install",
+		"build": null,
+		"start": "node index.js",
+		"nodeVersion": "18",
+		"pythonVersion": null,
+		"tokenKey": null,
+		"warnings": [
+			"no-lockfile"
+		]
+	}
+}

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

@@ -678,6 +678,28 @@ 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);
+	});
 });
 
 describe("detect with serverk.json", () => {

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);
 

package/src/guides/markdown.test.ts

@@ -390,3 +390,121 @@ describe("conditionals", () => {
 		expect(() => parse(":::if server.address")).toThrow(/conditionals open with :::when/);
 	});
 });
+
+describe("heading anchors", () => {
+	it("takes the id after a heading and keeps it out of the heading text", () => {
+		const { blocks } = parse(
+			[
+				"## The token is invalid {#token-invalid}",
+				"",
+				"### التوكن غير صحيح {#token-invalid-2}",
+			].join("\n"),
+		);
+
+		expect(blocks).toEqual([
+			{
+				type: "heading",
+				level: 2,
+				id: "token-invalid",
+				children: [
+					{
+						type: "text",
+						text: "The token is invalid",
+					},
+				],
+			},
+			{
+				type: "heading",
+				level: 3,
+				id: "token-invalid-2",
+				children: [
+					{
+						type: "text",
+						text: "التوكن غير صحيح",
+					},
+				],
+			},
+		]);
+	});
+
+	it("keeps inline markup before the anchor", () => {
+		const { blocks } = parse("## `ffmpeg` is missing {#ffmpeg-missing}");
+
+		expect(blocks[0]).toEqual({
+			type: "heading",
+			level: 2,
+			id: "ffmpeg-missing",
+			children: [
+				{
+					type: "code",
+					text: "ffmpeg",
+				},
+				{
+					type: "text",
+					text: " is missing",
+				},
+			],
+		});
+	});
+
+	it("still slugs a heading without an anchor", () => {
+		const { blocks } = parse("## Find your line");
+
+		expect(blocks[0]).toMatchObject({
+			id: "find-your-line",
+		});
+	});
+
+	it("moves a later slug aside instead of taking an anchored id", () => {
+		const { blocks } = parse(
+			[
+				"## Rate limits {#rate-limited}",
+				"",
+				"## Rate limited",
+			].join("\n"),
+		);
+
+		expect(blocks.map((block) => (block.type === "heading" ? block.id : null))).toEqual([
+			"rate-limited",
+			"rate-limited-2",
+		]);
+	});
+
+	it("rejects an anchored id that is already used", () => {
+		expect(() =>
+			parse(
+				[
+					"## Rate limited",
+					"",
+					"## Too many requests {#rate-limited}",
+				].join("\n"),
+			),
+		).toThrow(/heading id "rate-limited" is already used/);
+		expect(() =>
+			parse(
+				[
+					"## One {#same}",
+					"",
+					"## Two {#same}",
+				].join("\n"),
+			),
+		).toThrow(/heading id "same" is already used/);
+	});
+
+	it("rejects an id that is not lowercase letters, digits and hyphens", () => {
+		for (const id of [
+			"Token-Invalid",
+			"token_invalid",
+			"token invalid",
+			"-token",
+			"token--invalid",
+			"",
+		]) {
+			expect(() => parse(`## The token is invalid {#${id}}`)).toThrow(/must be lowercase letters, digits/);
+		}
+	});
+
+	it("rejects an anchor with no heading text", () => {
+		expect(() => parse("## {#token-invalid}")).toThrow(/empty text run/);
+	});
+});

package/src/guides/markdown.ts

@@ -52,6 +52,10 @@ const HEADING_2_PATTERN = /^##\s+(.+)$/;
 
 const HEADING_3_PATTERN = /^###\s+(.+)$/;
 
+const HEADING_ANCHOR_PATTERN = /^(.*?)\s*\{#([^}]*)\}$/;
+
+const HEADING_ID_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+
 const CALLOUT_OPEN_PATTERN = /^>\s*\[!(note|warning|danger)\]\s*(.*)$/;
 
 const IMAGE_LINE_PATTERN = /^!\[([^\]]*)\]\(([^)\s]+)\)$/;
@@ -285,6 +289,20 @@ const headingId = (inlines: GuideInline[], used: Map<string, number>, fallback:
 	return count === 0 ? base : `${base}-${count + 1}`;
 };
 
+const anchoredHeadingId = (path: string, line: number, id: string, used: Map<string, number>) => {
+	if (!HEADING_ID_PATTERN.test(id)) {
+		fail(path, line, `heading id "${id}" must be lowercase letters, digits and single hyphens`);
+	}
+
+	if (used.has(id)) {
+		fail(path, line, `heading id "${id}" is already used in this guide`);
+	}
+
+	used.set(id, 1);
+
+	return id;
+};
+
 const parseOpenTarget = (path: string, line: number, value: string): GuideOpenTarget => {
 	const separator = value.indexOf(":");
 	const tab = separator === -1 ? value : value.slice(0, separator);
@@ -459,12 +477,16 @@ const scanLeafBlocks = (scanner: Scanner, nested: boolean): ParsedLeafBlock[] =>
 				fail(path, lineNumber, "unsupported heading depth; use ## or ###");
 			}
 
-			const children = parseInlines(path, lineNumber, match[1].trim());
+			const text = match[1].trim();
+			const anchor = text.match(HEADING_ANCHOR_PATTERN);
+			const children = parseInlines(path, lineNumber, anchor ? (anchor[1] ?? "") : text);
 
 			blocks.push({
 				type: "heading",
 				level: h3 ? 3 : 2,
-				id: headingId(children, scanner.headingIds, `section-${scanner.headingIds.size + 1}`),
+				id: anchor
+					? anchoredHeadingId(path, lineNumber, anchor[2] ?? "", scanner.headingIds)
+					: headingId(children, scanner.headingIds, `section-${scanner.headingIds.size + 1}`),
 				children,
 			});