@serverkgg/bridge 0.1.7 → 0.1.8

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.1.7",
+	"version": "0.1.8",
 	"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

@@ -51,6 +51,7 @@ One Serverk package (a game or a bot runtime) on `@serverkgg/bridge`, with no pi
 - Write `ar:` before `en:` in every localized field.
 - `secrets` are platform API keys the game can use, `required: false`; customer settings are a panel form, and a bot customer's own values go through `environment.vault`.
 - Change an outcome by changing the declared value (`reset.keep: []`, `backup.only`), never by asking the platform to ignore a field.
+- `files.protected` holds only `.serverk` paths: the stamp, sidecars, journals and driver scratch under `.serverk-staging/`. Never a drop point under `.serverk-uploads/`, a `files.notable` match, an `@[open](files:…)` target or a folder the customer collects a file from; `serverk-bridge validate` fails each but the last, a runtime path.
 
 ## Guides and image
 

package/src/cli/validate.test.ts

@@ -4,9 +4,9 @@ import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { renderDetectTable } from "../bot/detect";
 import { BridgeKind, BridgeSetupStepKind } from "../core";
-import { GuideOpenTab } from "../guides";
-import { MANIFEST_SCHEMA_VERSION, PackageKind } from "../manifest";
-import type { BridgeDriver, BridgeSetupModule } from "../modules";
+import { GuideOpenTab, type GuidePack, type ParsedBlock, type ParsedLeafBlock } from "../guides";
+import { MANIFEST_SCHEMA_VERSION, PackageKind, type RunnableManifest } from "../manifest";
+import type { BridgeDriver, BridgePendingModule, BridgeSetupModule } from "../modules";
 import {
 	type BridgeCatalogSection,
 	BridgeConfirm,
@@ -23,9 +23,13 @@ import { RULES_FILE, readShippedRules, writeRules } from "./rules";
 import {
 	availabilityReportLines,
 	confirmReportLines,
+	notableReportLines,
+	openTargetReportLines,
 	placementReportLines,
+	protectedNameReportLines,
 	runValidate,
 	setupReportLines,
+	uploadStagingReportLines,
 } from "./validate";
 
 const text = (value: string) => ({
@@ -822,3 +826,425 @@ describe("the confirm report", () => {
 		).toEqual([]);
 	});
 });
+
+const manifestWith = (rules: string[], notes: string[] = []) => {
+	return {
+		files: {
+			protected: rules,
+			notable: notes.map((match) => ({
+				match,
+			})),
+		},
+	} as unknown as RunnableManifest;
+};
+
+const worldsWith = (staging: string): BridgeTableSection => ({
+	layout: BridgeLayout.Table,
+	id: "worlds",
+	module: "worlds",
+	columns: [
+		{
+			key: "name",
+			label: text("Name"),
+		},
+	],
+	upload: {
+		label: text("Upload a world"),
+		extensions: [
+			"zip",
+		],
+		staging,
+	},
+});
+
+const pendingWith = (staging: string): BridgePendingModule => ({
+	kind: BridgeKind.Pending,
+	staging,
+	extensions: [
+		"jar",
+	],
+	list: async () => [],
+	add: async () => {
+		return;
+	},
+});
+
+const driverWith = (
+	sections: BridgeTab["sections"],
+	pending?: BridgePendingModule,
+	setup?: BridgeSetupModule,
+): BridgeDriver => ({
+	install: {
+		kind: BridgeKind.Install,
+		run: async () => {
+			return;
+		},
+	},
+	lifecycle: {
+		kind: BridgeKind.Lifecycle,
+		command: async () => [
+			"run",
+		],
+	},
+	pending,
+	setup,
+	panel: {
+		tabs: [
+			{
+				id: "worlds",
+				title: text("Worlds"),
+				sections,
+			},
+		],
+	},
+});
+
+const packWith = (blocks: ParsedBlock[]): GuidePack => ({
+	drafts: [
+		{
+			id: "getting-started",
+			title: text("Getting started"),
+			summary: text("Start here"),
+			tags: [],
+			surfaces: [],
+			videoId: null,
+			body: {
+				ar: blocks,
+				en: blocks,
+			},
+		},
+	],
+	files: [],
+	images: [],
+	commands: [],
+});
+
+const filesOpenWith = (path: string | null): ParsedLeafBlock => ({
+	type: "open",
+	target: {
+		tab: GuideOpenTab.Files,
+		path,
+	},
+});
+
+const SERVERK_RULES = [
+	".serverk-install.json",
+	".serverk/**",
+	"plugins/.serverk-catalog.json",
+	".serverk-staging/**",
+	".serverk-wipe",
+	"Server/mods/.serverk-mods.json",
+];
+
+const FOREIGN_RULES = [
+	"bedrock_server",
+	"*.so",
+	"worlds/*/db/**",
+	"config",
+	".serverkfoo",
+];
+
+const JAVA_RULES = [
+	".serverk-install.json",
+	".serverk-crashscan.json",
+	".serverk-companions.json",
+	".serverk-modpack.json",
+	"plugins/.serverk-catalog.json",
+	"mods/.serverk-catalog.json",
+];
+
+describe("protectedNameReportLines", () => {
+	it("passes rules that each name a .serverk path", () => {
+		expect(protectedNameReportLines(manifestWith(SERVERK_RULES))).toEqual([]);
+	});
+
+	for (const rule of FOREIGN_RULES) {
+		it(`fails "${rule}", which names no .serverk path`, () => {
+			expect(
+				protectedNameReportLines(
+					manifestWith([
+						".serverk-install.json",
+						rule,
+					]),
+				),
+			).toEqual([
+				`  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`,
+			]);
+		});
+	}
+});
+
+describe("uploadStagingReportLines", () => {
+	it("fails a section upload that stages under a protected folder", () => {
+		const manifest = manifestWith([
+			".serverk-download/**",
+			".serverk-worlds/**",
+		]);
+
+		expect(
+			uploadStagingReportLines(
+				manifest,
+				driverWith([
+					worldsWith(".serverk-worlds"),
+				]),
+			),
+		).toEqual([
+			'  error: upload staging ".serverk-worlds" of tab "worlds" section "worlds" is protected by ".serverk-worlds/**" — a protected path refuses the customer\'s upload, so take the folder off `files.protected`',
+		]);
+	});
+
+	it("fails a pending upload that stages under a protected folder", () => {
+		const manifest = manifestWith([
+			".serverk-staging",
+		]);
+
+		expect(uploadStagingReportLines(manifest, driverWith([], pendingWith(".serverk-staging/pending-upload")))).toEqual([
+			'  error: upload staging ".serverk-staging/pending-upload" of the pending upload is protected by ".serverk-staging" — a protected path refuses the customer\'s upload, so take the folder off `files.protected`',
+		]);
+	});
+
+	it("passes when no protected rule reaches an upload staging folder", () => {
+		const manifest = manifestWith([
+			".serverk-download/**",
+			".serverk-install.json",
+			".serverk-staging/install/**",
+			"*.json",
+		]);
+
+		expect(
+			uploadStagingReportLines(
+				manifest,
+				driverWith(
+					[
+						worldsWith(".serverk-staging/world-upload"),
+					],
+					pendingWith(".serverk-staging/pending-upload"),
+				),
+			),
+		).toEqual([]);
+	});
+
+	it("passes an upload staging folder that sits beside a protected sibling", () => {
+		const manifest = manifestWith([
+			".serverk-staging/**",
+		]);
+
+		expect(
+			uploadStagingReportLines(
+				manifest,
+				driverWith([
+					worldsWith(".serverk-uploads/world"),
+				]),
+			),
+		).toEqual([]);
+	});
+
+	it("passes a staging folder that merely holds a protected sidecar", () => {
+		const manifest = manifestWith([
+			".serverk-staging/install/**",
+		]);
+
+		expect(
+			uploadStagingReportLines(
+				manifest,
+				driverWith([
+					worldsWith(".serverk-staging"),
+				]),
+			),
+		).toEqual([]);
+	});
+});
+
+describe("notableReportLines", () => {
+	it("fails a note on a protected file", () => {
+		const manifest = manifestWith(
+			[
+				".serverk-install.json",
+			],
+			[
+				".serverk-install.json",
+			],
+		);
+
+		expect(notableReportLines(manifest)).toEqual([
+			'  error: files.notable ".serverk-install.json" is protected by ".serverk-install.json" — the file manager hides a protected path before it annotates it, so the note never shows; take one of the two off',
+		]);
+	});
+
+	it("fails a note on a file inside a protected folder", () => {
+		const manifest = manifestWith(
+			[
+				".serverk/**",
+			],
+			[
+				".serverk/install.json",
+			],
+		);
+
+		expect(notableReportLines(manifest)).toEqual([
+			'  error: files.notable ".serverk/install.json" is protected by ".serverk/**" — the file manager hides a protected path before it annotates it, so the note never shows; take one of the two off',
+		]);
+	});
+
+	it("fails a wildcard note under a protected folder", () => {
+		const manifest = manifestWith(
+			[
+				".serverk-staging",
+			],
+			[
+				".serverk-staging/**",
+			],
+		);
+
+		expect(notableReportLines(manifest)).toEqual([
+			'  error: files.notable ".serverk-staging/**" is protected by ".serverk-staging" — the file manager hides a protected path before it annotates it, so the note never shows; take one of the two off',
+		]);
+	});
+
+	it("passes notes on folders that merely hold protected sidecars", () => {
+		const manifest = manifestWith(JAVA_RULES, [
+			"plugins",
+			"mods",
+			"world/**",
+			"*.json",
+		]);
+
+		expect(notableReportLines(manifest)).toEqual([]);
+	});
+});
+
+describe("openTargetReportLines", () => {
+	it("fails a guide link that opens a protected file", () => {
+		const manifest = manifestWith([
+			".serverk-install.json",
+		]);
+
+		expect(
+			openTargetReportLines(
+				manifest,
+				driverWith([]),
+				packWith([
+					filesOpenWith(".serverk-install.json"),
+				]),
+			),
+		).toEqual([
+			'  error: guide "getting-started" (ar) opens files at ".serverk-install.json", which ".serverk-install.json" protects — the panel refuses a protected path, so the link is dead; point it elsewhere or take the rule off `files.protected`',
+			'  error: guide "getting-started" (en) opens files at ".serverk-install.json", which ".serverk-install.json" protects — the panel refuses a protected path, so the link is dead; point it elsewhere or take the rule off `files.protected`',
+		]);
+	});
+
+	it("fails a guide link inside a conditional block", () => {
+		const manifest = manifestWith([
+			".serverk/**",
+		]);
+
+		expect(
+			openTargetReportLines(
+				manifest,
+				driverWith([]),
+				packWith([
+					{
+						type: "conditional",
+						key: "panel.modded",
+						when: [],
+						otherwise: [
+							filesOpenWith(".serverk/install.json"),
+						],
+					},
+				]),
+			),
+		).toEqual([
+			'  error: guide "getting-started" (ar) opens files at ".serverk/install.json", which ".serverk/**" protects — the panel refuses a protected path, so the link is dead; point it elsewhere or take the rule off `files.protected`',
+			'  error: guide "getting-started" (en) opens files at ".serverk/install.json", which ".serverk/**" protects — the panel refuses a protected path, so the link is dead; point it elsewhere or take the rule off `files.protected`',
+		]);
+	});
+
+	it("fails a setup step that opens a protected folder", () => {
+		const manifest = manifestWith([
+			".serverk-level/**",
+		]);
+
+		const setup: BridgeSetupModule = {
+			kind: BridgeKind.Setup,
+			steps: [
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "level",
+					title: text("Level"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Files,
+						path: ".serverk-level",
+					},
+				},
+			],
+			submit: async () => {
+				return;
+			},
+		};
+
+		expect(openTargetReportLines(manifest, driverWith([], undefined, setup), null)).toEqual([
+			'  error: setup step "level" opens files at ".serverk-level", which ".serverk-level/**" protects — the panel refuses a protected path, so the link is dead; point it elsewhere or take the rule off `files.protected`',
+		]);
+	});
+
+	it("passes files links with no path, other tabs and unprotected paths", () => {
+		const manifest = manifestWith([
+			".serverk-install.json",
+			".serverk-staging/**",
+		]);
+
+		const setup: BridgeSetupModule = {
+			kind: BridgeKind.Setup,
+			steps: [
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "files",
+					title: text("Files"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Files,
+						path: null,
+					},
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "invite",
+					title: text("Invite"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Access,
+					},
+				},
+			],
+			submit: async () => {
+				return;
+			},
+		};
+
+		expect(
+			openTargetReportLines(
+				manifest,
+				driverWith([], undefined, setup),
+				packWith([
+					filesOpenWith(null),
+					filesOpenWith("server.properties"),
+					filesOpenWith(".serverk-uploads/world"),
+					{
+						type: "open",
+						target: {
+							tab: GuideOpenTab.Panel,
+							tabId: "settings",
+						},
+					},
+					{
+						type: "open",
+						target: {
+							tab: GuideOpenTab.Console,
+						},
+					},
+				]),
+			),
+		).toEqual([]);
+	});
+});

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;