@serverkgg/bridge 0.1.7 → 0.1.9

package/src/cli/validate.ts

@@ -6,8 +6,16 @@ import { z } from "zod";
 import { type ArticlePack, compileArticles } from "../blog";
 import { DETECT_TABLE_FILE, renderDetectTable } from "../bot/detect";
 import { BridgeKind, PortProtocol } from "../core";
-import { GuideOpenTab, type GuideOpenTarget, type GuidePack, readGuidePack, readGuidePackage } from "../guides";
 import {
+	GuideOpenTab,
+	type GuideOpenTarget,
+	type GuidePack,
+	type ParsedBlock,
+	readGuidePack,
+	readGuidePackage,
+} from "../guides";
+import {
+	compileGlob,
 	declaredFiles,
 	type GuidePackage,
 	isBotManifest,
@@ -347,6 +355,206 @@ export const confirmReportLines = (driver: BridgeDriver): string[] => {
 	return lines;
 };
 
+const REACH_PROBE = "x";
+
+const SERVERK_SEGMENT = ".serverk";
+
+const WILDCARD = "*";
+
+interface UploadStaging {
+	owner: string;
+	folder: string;
+}
+
+interface FilesOpen {
+	owner: string;
+	path: string;
+}
+
+const protectedReaches = (path: string, rule: string) => {
+	if (rule === path || path.startsWith(`${rule}/`)) {
+		return true;
+	}
+
+	if (!rule.includes(WILDCARD)) {
+		return false;
+	}
+
+	const pattern = compileGlob(rule);
+
+	return pattern.test(path) || pattern.test(`${path}/${REACH_PROBE}`);
+};
+
+const isServerkPath = (rule: string) => {
+	return rule.split("/").some((segment) => segment === SERVERK_SEGMENT || segment.startsWith(`${SERVERK_SEGMENT}-`));
+};
+
+export const protectedNameReportLines = (manifest: RunnableManifest): string[] => {
+	const lines: string[] = [];
+
+	for (const rule of manifest.files.protected) {
+		if (isServerkPath(rule)) {
+			continue;
+		}
+
+		lines.push(
+			`  error: files.protected "${rule}" is not a .serverk path — a package protects only platform state, so drop the rule or move the file under a .serverk name`,
+		);
+	}
+
+	return lines;
+};
+
+export const uploadStagingReportLines = (manifest: RunnableManifest, driver: BridgeDriver): string[] => {
+	const stagings: UploadStaging[] = [];
+
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			if (!("upload" in section) || !section.upload) {
+				continue;
+			}
+
+			stagings.push({
+				owner: `tab "${tab.id}" section "${section.id}"`,
+				folder: section.upload.staging,
+			});
+		}
+	}
+
+	if (driver.pending) {
+		stagings.push({
+			owner: "the pending upload",
+			folder: driver.pending.staging,
+		});
+	}
+
+	const lines: string[] = [];
+
+	for (const staging of stagings) {
+		for (const rule of manifest.files.protected) {
+			if (!protectedReaches(staging.folder, rule)) {
+				continue;
+			}
+
+			lines.push(
+				`  error: upload staging "${staging.folder}" of ${staging.owner} is protected by "${rule}" — a protected path refuses the customer's upload, so take the folder off \`files.protected\``,
+			);
+		}
+	}
+
+	return lines;
+};
+
+const literalPrefixOf = (match: string) => {
+	const segments = match.split("/");
+	const wild = segments.findIndex((segment) => segment.includes(WILDCARD));
+
+	return (wild === -1 ? segments : segments.slice(0, wild)).join("/");
+};
+
+export const notableReportLines = (manifest: RunnableManifest): string[] => {
+	const lines: string[] = [];
+
+	for (const note of manifest.files.notable) {
+		const prefix = literalPrefixOf(note.match);
+
+		if (prefix === "") {
+			continue;
+		}
+
+		for (const rule of manifest.files.protected) {
+			if (!protectedReaches(prefix, rule)) {
+				continue;
+			}
+
+			lines.push(
+				`  error: files.notable "${note.match}" is protected by "${rule}" — the file manager hides a protected path before it annotates it, so the note never shows; take one of the two off`,
+			);
+		}
+	}
+
+	return lines;
+};
+
+const guideOpenTargetsOf = (blocks: ParsedBlock[]) => {
+	const leaves = blocks.flatMap((block) =>
+		block.type === "conditional"
+			? [
+					...block.when,
+					...block.otherwise,
+				]
+			: [
+					block,
+				],
+	);
+
+	return leaves.flatMap((block) =>
+		block.type === "open"
+			? [
+					block.target,
+				]
+			: [],
+	);
+};
+
+const filesPathOf = (target: GuideOpenTarget) => {
+	return target.tab === GuideOpenTab.Files ? target.path : null;
+};
+
+export const openTargetReportLines = (
+	manifest: RunnableManifest,
+	driver: BridgeDriver,
+	pack: GuidePack | null,
+): string[] => {
+	const opens: FilesOpen[] = [];
+
+	const collect = (owner: string, targets: GuideOpenTarget[]) => {
+		for (const target of targets) {
+			const path = filesPathOf(target);
+
+			if (path === null) {
+				continue;
+			}
+
+			opens.push({
+				owner,
+				path,
+			});
+		}
+	};
+
+	for (const draft of pack?.drafts ?? []) {
+		collect(`guide "${draft.id}" (ar)`, guideOpenTargetsOf(draft.body.ar));
+		collect(`guide "${draft.id}" (en)`, guideOpenTargetsOf(draft.body.en));
+	}
+
+	for (const step of driver.setup?.steps ?? []) {
+		if (step.kind !== BridgeSetupStepKind.Open) {
+			continue;
+		}
+
+		collect(`setup step "${step.id}"`, [
+			step.target,
+		]);
+	}
+
+	const lines: string[] = [];
+
+	for (const open of opens) {
+		for (const rule of manifest.files.protected) {
+			if (!protectedReaches(open.path, rule)) {
+				continue;
+			}
+
+			lines.push(
+				`  error: ${open.owner} opens files at "${open.path}", which "${rule}" protects — the panel refuses a protected path, so the link is dead; point it elsewhere or take the rule off \`files.protected\``,
+			);
+		}
+	}
+
+	return lines;
+};
+
 const openTargetOf = (target: GuideOpenTarget) => {
 	if (target.tab === GuideOpenTab.Panel) {
 		return `panel tab "${target.tabId}"`;
@@ -451,6 +659,12 @@ const validateRunnablePackage = async (
 	}
 
 	const pack = readGuidePack(source, manifest);
+	const nameLines = protectedNameReportLines(manifest);
+
+	if (nameLines.length > 0) {
+		throw new Error(`files.protected names a path that is not platform state:\n${nameLines.join("\n")}`);
+	}
+
 	const detectLines = botDetectLines(source, manifest);
 	const driverPath = driverArg ? resolve(driverArg) : join(dir, "src/driver.ts");
 
@@ -476,6 +690,16 @@ const validateRunnablePackage = async (
 		);
 	}
 
+	const reachLines = [
+		...uploadStagingReportLines(manifest, driver),
+		...notableReportLines(manifest),
+		...openTargetReportLines(manifest, driver, pack),
+	];
+
+	if (reachLines.length > 0) {
+		throw new Error(`a protected path is where the customer is sent:\n${reachLines.join("\n")}`);
+	}
+
 	const conditionalPorts = manifest.container.ports.filter((port) => port.activeWhen.length > 0).length;
 	const pairedPorts = manifest.container.ports.filter((port) => port.protocol === PortProtocol.TcpUdp).length;
 	const blockPorts = manifest.container.ports.filter((port) => port.count > 1).length;

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/manifest/index.ts

@@ -12,3 +12,4 @@ export * from "./presence";
 export * from "./primitives";
 export * from "./runtime";
 export * from "./source";
+export * from "./steam";

package/src/manifest/manifest.test.ts

@@ -931,6 +931,85 @@ describe("presence", () => {
 	});
 });
 
+describe("steam", () => {
+	it("is optional, so a game that declares none parses", () => {
+		const result = gameManifestSchema.safeParse(base());
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.steam).toBeUndefined();
+	});
+
+	it("accepts the server app id", () => {
+		const result = gameManifestSchema.safeParse({
+			...base(),
+			steam: {
+				appId: 896_660,
+			},
+		});
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.steam).toEqual({
+			appId: 896_660,
+		});
+	});
+
+	it("accepts the variable that holds the Steam branch", () => {
+		const result = gameManifestSchema.safeParse({
+			...base(),
+			steam: {
+				appId: 896_660,
+				branchVariable: "VALHEIM_BRANCH",
+			},
+		});
+
+		expect(result.success).toBe(true);
+		expect(result.success && result.data.steam).toEqual({
+			appId: 896_660,
+			branchVariable: "VALHEIM_BRANCH",
+		});
+	});
+
+	it("refuses a branch variable that is not an environment key", () => {
+		const result = gameManifestSchema.safeParse({
+			...base(),
+			steam: {
+				appId: 896_660,
+				branchVariable: "valheim-branch",
+			},
+		});
+
+		expect(result.success).toBe(false);
+		expect(result.error && z.prettifyError(result.error)).toContain("must be SCREAMING_SNAKE_CASE");
+	});
+
+	for (const appId of [
+		0,
+		-1,
+		2.5,
+		"258550",
+	]) {
+		it(`refuses ${JSON.stringify(appId)} as an app id`, () => {
+			const result = gameManifestSchema.safeParse({
+				...base(),
+				steam: {
+					appId,
+				},
+			});
+
+			expect(result.success).toBe(false);
+		});
+	}
+
+	it("refuses a block with no app id", () => {
+		const result = gameManifestSchema.safeParse({
+			...base(),
+			steam: {},
+		});
+
+		expect(result.success).toBe(false);
+	});
+});
+
 describe("container runtime", () => {
 	it("materializes the defaults when the manifest declares no runtime", () => {
 		const manifest = manifestSchema.parse(base());

package/src/manifest/manifest.ts

@@ -22,6 +22,7 @@ import {
 	zSlug,
 } from "./primitives";
 import { ManifestPlatform, manifestRuntimeSchema, WINE_MIN_SHM_MB } from "./runtime";
+import { manifestSteamSchema } from "./steam";
 
 export const MANIFEST_SCHEMA_VERSION = "serverk.gg/v1";
 
@@ -825,6 +826,10 @@ export const gameManifestSchema = z
 		secrets: z.array(manifestSecretSchema).max(16).default([]),
 		files: manifestFilesSchema.prefault({}),
 		presence: manifestPresenceSchema.optional(),
+		steam: manifestSteamSchema.optional().meta({
+			description:
+				"The Steam app behind this game. Declare it when steamcmd installs the server, so the platform sees when a newer game version is out.",
+		}),
 	})
 	.check((ctx) => {
 		if (ctx.issues.length > 0) {

package/src/manifest/steam.ts

@@ -0,0 +1,14 @@
+import { z } from "zod";
+import { zEnvKey } from "./primitives";
+
+export const manifestSteamSchema = z.object({
+	appId: z.int().positive().meta({
+		description: "Steam app id of the dedicated server, the one steamcmd installs with app_update.",
+	}),
+	branchVariable: zEnvKey.optional().meta({
+		description:
+			"The server variable that holds the Steam branch the customer picked. Omit it when the package installs the public branch only.",
+	}),
+});
+
+export type ManifestSteam = z.infer<typeof manifestSteamSchema>;

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",