@serverkgg/bridge 0.1.8 → 0.1.9

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.1.8",
+	"version": "0.1.9",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",

package/rules/package.md

@@ -56,6 +56,7 @@ One Serverk package (a game or a bot runtime) on `@serverkgg/bridge`, with no pi
 ## Guides and image
 
 - A guide is `guides/<id>/ar.md` and `en.md`, starting at `##` with no `#` title; its title and summary live in `serverk.yml`. Every package has a `getting-started` guide tagged `start`.
+- A heading may end with `{#<id>}`, lowercase letters, digits and single hyphens, to fix its anchor. A bot package's `errors` guide gives each cause section its cause id, the same in both languages. Why: the panel links every named cause to `errors#<cause id>`.
 - `image/Dockerfile` keeps the shared contract: `ARG BRIDGE_VERSION` with `LABEL gg.serverk.bridge.version`, a `container` user with uid 1000 and home `/home/container`, `COPY dist/bridge /serverk/bridge`, `ENTRYPOINT ["/usr/bin/tini", "--", "/serverk/bridge"]`, and no `USER` line. Game files download at install, a bot's code arrives with a deploy; neither is baked in.
 - The outermost start wrapper ends in `exec`, with no `setsid`, `nohup` or double fork. Why: the bridge checks the uid of the pid it spawned, and stop escalation signals the process group, so an orphan outside it keeps the port.
 

package/src/bot/botCauses.test.ts

@@ -29,6 +29,10 @@ const CASES: readonly {
 		line: "telegram.error.InvalidToken: The token `123:abc` was rejected by the server.",
 		cause: BridgeCrashCause.TokenInvalid,
 	},
+	{
+		line: "telegram.error.InvalidToken: You must pass the token you received from https://t.me/Botfather!",
+		cause: BridgeCrashCause.TokenInvalid,
+	},
 	{
 		line: "GrammyError: Call to 'deleteWebhook' failed! (404: Not Found)",
 		cause: BridgeCrashCause.TokenInvalid,
@@ -165,6 +169,10 @@ const CASES: readonly {
 		line: "ModuleNotFoundError: No module named 'audioop'",
 		cause: BridgeCrashCause.AudioopRemoved,
 	},
+	{
+		line: "KeyError: 'TELEGRAM_TOKEN'",
+		cause: BridgeCrashCause.VariableMissing,
+	},
 	{
 		line: "discord.errors.HTTPException: 429 Too Many Requests (error code: 0): You are being blocked from accessing our API temporarily due to exceeding our rate limits frequently.",
 		cause: BridgeCrashCause.RateLimited,
@@ -253,6 +261,30 @@ describe("BOT_CRASH_EVIDENCE", () => {
 		});
 	}
 
+	it("names the variable the code read from an empty vault", () => {
+		const { ring, print } = botRing();
+
+		print("KeyError: 'TELEGRAM_TOKEN'");
+
+		expect(ring.crash(recordOf())).toBe(BridgeCrashCause.VariableMissing);
+		expect(ring.drain(0).events.at(0)?.payload?.variable).toBe("TELEGRAM_TOKEN");
+	});
+
+	for (const line of [
+		"KeyError: 0",
+		"KeyError: 'user'",
+		"KeyError: 'X'",
+	]) {
+		it(`leaves a key that is not a variable name unexplained from "${line}"`, () => {
+			const { ring, print } = botRing();
+
+			print(line);
+
+			expect(ring.crash(recordOf())).toBe(BridgeCrashCause.Unknown);
+			expect(ring.drain(0).events.at(0)?.payload?.variable).toBeUndefined();
+		});
+	}
+
 	it("names the removed audioop module before any other missing module", () => {
 		const { ring, print } = botRing();
 

package/src/bot/botCauses.ts

@@ -48,6 +48,10 @@ export const BOT_CRASH_EVIDENCE: readonly BridgeEventPattern[] = [
 		match: /ffmpeg was not found|\bENOENT\b.*\bffmpeg\b|\bffmpeg\b.*\bENOENT\b/i,
 		emit: BridgeEventName.FfmpegMissing,
 	},
+	{
+		match: /^KeyError: '(?<variable>[A-Z][A-Z0-9_]{1,63})'\s*$/,
+		emit: BridgeEventName.VariableMissing,
+	},
 	{
 		match: /No module named 'audioop'/,
 		emit: BridgeEventName.AudioopRemoved,

package/src/bot/botDeploy.test.ts

@@ -8,8 +8,10 @@ import {
 	DEPLOY_MARKER_DRAFT,
 	DEPLOYMENT_EVENT_PATTERN,
 	DEPLOYMENT_LINE,
+	DEPLOYMENT_STAGE_LINE,
 	type DeployMarker,
 	deploymentLine,
+	deploymentStageLine,
 	deployPending,
 	pendingDeploymentOf,
 	requestDeploy,
@@ -216,6 +218,36 @@ describe("deploymentLine", () => {
 	});
 });
 
+describe("deploymentStageLine", () => {
+	it("names the deployment and the stage it entered", () => {
+		expect(deploymentStageLine("dep_a1b2c3d4", BotDeploymentStage.Install)).toBe(
+			"serverk: deployment dep_a1b2c3d4 stage install",
+		);
+	});
+
+	it("round-trips through the stage pattern for every stage", () => {
+		for (const stage of Object.values(BotDeploymentStage)) {
+			expect(DEPLOYMENT_STAGE_LINE.exec(deploymentStageLine("dep_a1b2c3d4", stage))?.groups).toEqual({
+				deployment: "dep_a1b2c3d4",
+				stage,
+			});
+		}
+	});
+
+	it("is never read as a deployment outcome, so it raises no event", () => {
+		const line = deploymentStageLine("dep_a1b2c3d4", BotDeploymentStage.Start);
+
+		expect(DEPLOYMENT_LINE.test(line)).toBe(false);
+		expect(DEPLOYMENT_EVENT_PATTERN.match.test(line)).toBe(false);
+		expect(DEPLOYMENT_STAGE_LINE.test("serverk: deployment dep_a1b2c3d4 ready")).toBe(false);
+	});
+
+	it("reads only deployment ids of at most 64 characters", () => {
+		expect(DEPLOYMENT_STAGE_LINE.test(`serverk: deployment ${"d".repeat(64)} stage sync`)).toBe(true);
+		expect(DEPLOYMENT_STAGE_LINE.test(`serverk: deployment ${"d".repeat(65)} stage sync`)).toBe(false);
+	});
+});
+
 describe("requestDeploy", () => {
 	it("writes the request as JSON and restarts a running bot", async () => {
 		const { context, stored, events } = deployContext(true);

package/src/bot/botDeploy.ts

@@ -21,6 +21,8 @@ export const DEPLOYMENT_EVENT_KIND = "deployment";
 export const DEPLOYMENT_LINE =
 	/^serverk: deployment (?<deployment>\S{1,64}) (?<outcome>ready|failed)(?: at (?<commit>[0-9a-f]{7,64}))?(?:: (?<stage>[a-z-]+): (?<detail>.{1,200}))?$/u;
 
+export const DEPLOYMENT_STAGE_LINE = /^serverk: deployment (?<deployment>\S{1,64}) stage (?<stage>[a-z-]+)$/u;
+
 export const DEPLOYMENT_DETAIL_LIMIT = 200;
 
 export const DEPLOYMENT_COMMIT_LENGTH = 12;
@@ -64,6 +66,10 @@ export const deploymentLine = (input: DeploymentLineInput) => {
 	return `serverk: deployment ${input.deployment} failed: ${input.stage}: ${detail}`;
 };
 
+export const deploymentStageLine = (deployment: string, stage: BotDeploymentStage) => {
+	return `serverk: deployment ${deployment} stage ${stage}`;
+};
+
 export const DEPLOYMENT_EVENT_PATTERN: BridgeEventPattern = {
 	match: DEPLOYMENT_LINE,
 	emit: BridgeEventName.ServerUpdated,

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/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,
 			});
 

package/src/protocol/bridgeCrash.ts

@@ -17,6 +17,7 @@ export enum BridgeCrashCause {
 	FfmpegMissing = "ffmpeg-missing",
 	AudioopRemoved = "audioop-removed",
 	RateLimited = "rate-limited",
+	VariableMissing = "variable-missing",
 	Unknown = "unknown",
 }
 
@@ -75,6 +76,10 @@ export const BRIDGE_CRASH_EVIDENCE: readonly BridgeCrashEvidence[] = [
 		name: BridgeEventName.FfmpegMissing,
 		cause: BridgeCrashCause.FfmpegMissing,
 	},
+	{
+		name: BridgeEventName.VariableMissing,
+		cause: BridgeCrashCause.VariableMissing,
+	},
 	{
 		name: BridgeEventName.IntentsDisallowed,
 		cause: BridgeCrashCause.IntentsDisallowed,

package/src/protocol/bridgeEvents.ts

@@ -47,6 +47,7 @@ export enum BridgeEventName {
 	TickLagging = "TickLagging",
 	TokenInUse = "TokenInUse",
 	TokenInvalid = "TokenInvalid",
+	VariableMissing = "VariableMissing",
 	WorldActivated = "WorldActivated",
 	WorldCloned = "WorldCloned",
 	WorldCorrupt = "WorldCorrupt",