@serverkgg/bridge 0.1.6 → 0.1.8

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