@serverkgg/bridge 0.0.1 → 0.0.2

package/src/guides/variables.ts

@@ -0,0 +1,52 @@
+import { z } from "zod";
+
+export enum GuideVariableFormat {
+	Text = "text",
+	Code = "code",
+	Number = "number",
+	DateTime = "datetime",
+}
+
+export const GUIDE_VARIABLES = {
+	"server.name": GuideVariableFormat.Text,
+	"server.code": GuideVariableFormat.Code,
+	"server.address": GuideVariableFormat.Code,
+	"server.host": GuideVariableFormat.Code,
+	"server.port": GuideVariableFormat.Code,
+	"server.game": GuideVariableFormat.Text,
+	"server.region": GuideVariableFormat.Text,
+	"server.state": GuideVariableFormat.Text,
+	"server.version": GuideVariableFormat.Code,
+	"server.memory": GuideVariableFormat.Number,
+	"server.disk": GuideVariableFormat.Number,
+	"server.playersOnline": GuideVariableFormat.Number,
+	"server.playersMax": GuideVariableFormat.Number,
+	"server.expiresAt": GuideVariableFormat.DateTime,
+	"user.username": GuideVariableFormat.Text,
+} as const satisfies Record<string, GuideVariableFormat>;
+
+export type GuideVariableKey = keyof typeof GUIDE_VARIABLES;
+
+export const GUIDE_VARIABLE_KEYS = Object.keys(GUIDE_VARIABLES) as GuideVariableKey[];
+
+const PANEL_VARIABLE_PATTERN = /^panel\.[A-Z][A-Z0-9_]*$/;
+
+export const isGuideVariableKey = (value: string): value is GuideVariableKey => {
+	return value in GUIDE_VARIABLES;
+};
+
+export const isPanelVariableKey = (value: string) => {
+	return PANEL_VARIABLE_PATTERN.test(value);
+};
+
+export const guideVariableFormat = (key: string) => {
+	return isGuideVariableKey(key) ? GUIDE_VARIABLES[key] : GuideVariableFormat.Text;
+};
+
+export const zGuideVariableRef = z
+	.string()
+	.min(1)
+	.max(64)
+	.refine((value) => isGuideVariableKey(value) || isPanelVariableKey(value), {
+		error: `unknown variable; use one of ${GUIDE_VARIABLE_KEYS.join(", ")} or panel.SOME_KEY`,
+	});

package/src/guides/version.ts

@@ -0,0 +1 @@
+export const GUIDE_COMPILER_VERSION = "2";

package/src/main.ts

@@ -2,4 +2,5 @@ export * from "./context";
 export * from "./core";
 export * from "./modules";
 export * from "./panel";
-export { BridgeNetError, serve } from "./runtime";
+export * from "./runtime";
+export * from "./terminal";

package/src/manifest/assets.ts

@@ -1,10 +1,10 @@
 import { ASSET_MAX_EDGE, type AssetDimensions, readDimensions } from "./dimensions";
 
-export const ASSET_MAX_BYTES = 512 * 1024;
+const ASSET_MAX_BYTES = 512 * 1024;
 
-export const ASSET_EXTENSION = "webp";
+const ASSET_EXTENSION = "webp";
 
-export const ASSET_MEDIA_TYPE = "image/webp";
+const ASSET_MEDIA_TYPE = "image/webp";
 
 const RIFF_HEADER_BYTES = 12;
 
@@ -55,7 +55,7 @@ const isWebp = (bytes: Uint8Array) => {
 	return declared + 8 === bytes.byteLength;
 };
 
-export const assetMediaType = (path: string) => {
+const assetMediaType = (path: string) => {
 	const extension = path.slice(path.lastIndexOf(".") + 1).toLowerCase();
 
 	if (extension !== ASSET_EXTENSION) {

package/src/manifest/guide.ts

@@ -1,33 +1,38 @@
 import { z } from "zod";
-import { localizedTextSchema } from "./localized";
-
-export const zGuideId = z
-	.string()
-	.min(1)
-	.max(64)
-	.regex(/^[a-z0-9][a-z0-9-]*$/);
+import { localizedText } from "./localized";
+import { zMarkdownPath, zSlug } from "./primitives";
 
 export const zGuideTag = z
 	.string()
 	.min(1)
 	.max(32)
-	.regex(/^[a-z0-9][a-z0-9._-]*$/);
+	.regex(/^[a-z0-9][a-z0-9._-]*$/, "must be lowercase letters, digits, dots, dashes and underscores");
 
-export const zYoutubeId = z.string().regex(/^[A-Za-z0-9_-]{11}$/);
+export const zYoutubeId = z.string().regex(/^[A-Za-z0-9_-]{11}$/, "must be an 11-character YouTube video id");
 
-const zMarkdownPath = z
-	.string()
-	.min(1)
-	.max(256)
-	.regex(/^[a-zA-Z0-9][a-zA-Z0-9/_-]*\.md$/);
+export enum GuideSurface {
+	Overview = "overview",
+	Console = "console",
+	Files = "files",
+	Backups = "backups",
+	Panel = "panel",
+}
+
+export const guideTagSchema = z.object({
+	id: zGuideTag,
+	name: localizedText(48),
+});
+
+export type GuideTag = z.infer<typeof guideTagSchema>;
 
 export const guideEntrySchema = z.object({
-	id: zGuideId,
-	title: localizedTextSchema,
-	summary: localizedTextSchema,
+	id: zSlug,
+	title: localizedText(120),
+	summary: localizedText(300),
 	tags: z.array(zGuideTag).max(8).default([]),
+	surfaces: z.array(z.enum(GuideSurface)).max(8).default([]),
 	video: zYoutubeId.optional(),
-	body: z.object({
+	bodyPath: z.object({
 		ar: zMarkdownPath,
 		en: zMarkdownPath,
 	}),

package/src/manifest/index.ts

@@ -1,9 +1,10 @@
+export * from "../utils";
 export * from "./assets";
 export * from "./category";
-export * from "./checks";
-export * from "./dimensions";
 export * from "./guide";
 export * from "./image";
+export * from "./jsonSchema";
 export * from "./localized";
 export * from "./manifest";
+export * from "./primitives";
 export * from "./source";

package/src/manifest/jsonSchema.ts

@@ -0,0 +1,16 @@
+import { z } from "zod";
+import { packageSchema } from "./manifest";
+
+export const SCHEMA_FILE = "serverk.schema.json";
+
+export const buildJsonSchema = () => {
+	return z.toJSONSchema(packageSchema, {
+		io: "input",
+		target: "draft-2020-12",
+		unrepresentable: "any",
+	});
+};
+
+export const renderJsonSchema = () => {
+	return `${JSON.stringify(buildJsonSchema(), null, "\t")}\n`;
+};

package/src/manifest/localized.ts

@@ -6,3 +6,10 @@ export const localizedTextSchema = z.object({
 });
 
 export type LocalizedText = z.infer<typeof localizedTextSchema>;
+
+export const localizedText = (max: number) => {
+	return z.object({
+		ar: z.string().trim().min(1, "is required in Arabic").max(max),
+		en: z.string().trim().min(1, "is required in English").max(max),
+	});
+};

package/src/manifest/manifest.test.ts

@@ -0,0 +1,366 @@
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import { GameCategory } from "./category";
+import { guidePackageSchema, MANIFEST_SCHEMA_VERSION, manifestSchema, packageSchema } from "./manifest";
+
+const text = (value: string) => ({
+	ar: value,
+	en: value,
+});
+
+const base = () => ({
+	schemaVersion: MANIFEST_SCHEMA_VERSION,
+	kind: "GamePackage",
+	metadata: {
+		id: "minecraft",
+		name: text("Minecraft"),
+		description: text("A game"),
+		tagline: text("Play now"),
+		category: GameCategory.Sandbox,
+		logo: "assets/logo.webp",
+		banner: "assets/banner.webp",
+	},
+	resources: {
+		minMemoryMb: 1024,
+		recommendedMemoryMb: 4096,
+		minDiskMb: 5120,
+	},
+	container: {
+		image: "serverkgg/minecraft",
+		ports: [
+			{
+				key: "game",
+				containerPort: 25_565,
+				protocol: "tcp",
+				hostRange: {
+					default: 25_565,
+					min: 25_565,
+					max: 25_664,
+				},
+			},
+		],
+	},
+});
+
+const failure = (input: unknown) => {
+	const result = manifestSchema.safeParse(input);
+
+	if (result.success) {
+		throw new Error("expected the manifest to be rejected");
+	}
+
+	return result.error.issues.map((issue) => ({
+		path: issue.path.join("."),
+		message: issue.message,
+	}));
+};
+
+describe("defaults", () => {
+	test("fills in the optional sections so consumers never guard", () => {
+		const manifest = manifestSchema.parse(base());
+
+		expect(manifest.backup).toEqual({
+			only: [],
+			except: [],
+		});
+		expect(manifest.reset).toEqual({
+			keep: [],
+		});
+		expect(manifest.files).toEqual({
+			protected: [],
+			notable: [],
+		});
+		expect(manifest.guides).toEqual([]);
+		expect(manifest.secrets).toEqual([]);
+	});
+});
+
+describe("cross-entry checks", () => {
+	test("rejects an image that does not match metadata.id", () => {
+		const manifest = base();
+
+		manifest.container.image = "serverkgg/minecraft-java";
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "container.image",
+				message: 'must be "serverkgg/minecraft" to match metadata.id',
+			},
+		]);
+	});
+
+	test("rejects duplicate secret keys", () => {
+		const manifest = {
+			...base(),
+			secrets: [
+				{
+					key: "MODRINTH_API_KEY",
+					description: text("A key"),
+				},
+				{
+					key: "MODRINTH_API_KEY",
+					description: text("The same key"),
+				},
+			],
+		};
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "secrets.1.key",
+				message: 'secret "MODRINTH_API_KEY" is declared twice',
+			},
+		]);
+	});
+
+	test("rejects duplicate protected paths and notable matches", () => {
+		const manifest = {
+			...base(),
+			files: {
+				protected: [
+					"eula.txt",
+					"eula.txt",
+				],
+				notable: [
+					{
+						match: "server.properties",
+						label: text("Settings"),
+						note: text("Core settings"),
+					},
+					{
+						match: "server.properties",
+						label: text("Settings again"),
+						note: text("Core settings"),
+					},
+				],
+			},
+		};
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "files.protected.1",
+				message: '"eula.txt" is protected twice',
+			},
+			{
+				path: "files.notable.1.match",
+				message: '"server.properties" already has a note',
+			},
+		]);
+	});
+
+	test("rejects duplicate port keys and overlapping host ranges", () => {
+		const manifest = base();
+		const [game] = manifest.container.ports;
+
+		if (!game) {
+			throw new Error("fixture is missing its port");
+		}
+
+		manifest.container.ports.push({
+			...game,
+			hostRange: {
+				default: 25_600,
+				min: 25_600,
+				max: 25_700,
+			},
+		});
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "container.ports.1.key",
+				message: 'port "game" is declared twice',
+			},
+			{
+				path: "container.ports.1.hostRange",
+				message: 'host range overlaps port "game" — two tcp ports cannot share host ports',
+			},
+		]);
+	});
+
+	test("rejects a guide tag that is not declared", () => {
+		const manifest = {
+			...base(),
+			guides: [
+				{
+					id: "getting-started",
+					title: text("Getting started"),
+					summary: text("Start here"),
+					tags: [
+						"start",
+					],
+					bodyPath: {
+						ar: "guides/getting-started/ar.md",
+						en: "guides/getting-started/en.md",
+					},
+				},
+			],
+		};
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "guides.0.tags.0",
+				message: 'tag "start" is not declared in guideTags',
+			},
+		]);
+	});
+
+	test("rejects one body file serving both locales", () => {
+		const manifest = {
+			...base(),
+			guides: [
+				{
+					id: "getting-started",
+					title: text("Getting started"),
+					summary: text("Start here"),
+					bodyPath: {
+						ar: "guides/getting-started/en.md",
+						en: "guides/getting-started/en.md",
+					},
+				},
+			],
+		};
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "guides.0.bodyPath",
+				message: 'guide "getting-started" reuses one body file for both locales',
+			},
+		]);
+	});
+});
+
+describe("field validation", () => {
+	test("explains a bad host range instead of saying nothing", () => {
+		const manifest = base();
+		const [game] = manifest.container.ports;
+
+		if (!game) {
+			throw new Error("fixture is missing its port");
+		}
+
+		game.hostRange.min = 25_700;
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "container.ports.0.hostRange",
+				message: "min must not be greater than max",
+			},
+			{
+				path: "container.ports.0.hostRange",
+				message: "default must fall inside min..max",
+			},
+		]);
+	});
+
+	test("explains a default that sits outside its range", () => {
+		const manifest = base();
+		const [game] = manifest.container.ports;
+
+		if (!game) {
+			throw new Error("fixture is missing its port");
+		}
+
+		game.hostRange.default = 30_000;
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "container.ports.0.hostRange",
+				message: "default must fall inside min..max",
+			},
+		]);
+	});
+
+	test("explains a bad colour", () => {
+		const manifest = {
+			...base(),
+			files: {
+				notable: [
+					{
+						match: "server.properties",
+						label: text("Settings"),
+						note: text("Core settings"),
+						color: "green",
+					},
+				],
+			},
+		};
+
+		expect(failure(manifest)).toEqual([
+			{
+				path: "files.notable.0.color",
+				message: "must be a six-digit hex colour like #4a8fd4",
+			},
+		]);
+	});
+
+	test("field failures short-circuit the cross-entry checks", () => {
+		const manifest = base();
+
+		manifest.metadata.id = "Minecraft";
+		manifest.container.image = "serverkgg/minecraft";
+
+		const issues = failure(manifest);
+
+		expect(issues).toEqual([
+			{
+				path: "metadata.id",
+				message: "must be lowercase letters, digits and dashes, starting with a letter or digit",
+			},
+		]);
+	});
+});
+
+describe("packageSchema", () => {
+	test("routes on kind without a separate pre-parse", () => {
+		const game = packageSchema.parse(base());
+
+		expect(game.kind).toBe("GamePackage");
+
+		const guides = packageSchema.parse({
+			schemaVersion: MANIFEST_SCHEMA_VERSION,
+			kind: "GuidePackage",
+			metadata: {
+				id: "platform",
+			},
+			guides: [
+				{
+					id: "getting-started",
+					title: text("Getting started"),
+					summary: text("Start here"),
+					bodyPath: {
+						ar: "guides/getting-started/ar.md",
+						en: "guides/getting-started/en.md",
+					},
+				},
+			],
+		});
+
+		expect(guides.kind).toBe("GuidePackage");
+	});
+
+	test("guide packages get the same guide checks", () => {
+		const result = guidePackageSchema.safeParse({
+			schemaVersion: MANIFEST_SCHEMA_VERSION,
+			kind: "GuidePackage",
+			metadata: {
+				id: "platform",
+			},
+			guides: [
+				{
+					id: "getting-started",
+					title: text("Getting started"),
+					summary: text("Start here"),
+					tags: [
+						"start",
+					],
+					bodyPath: {
+						ar: "guides/getting-started/ar.md",
+						en: "guides/getting-started/en.md",
+					},
+				},
+			],
+		});
+
+		expect(result.success).toBe(false);
+		expect(result.error && z.prettifyError(result.error)).toContain('tag "start" is not declared in guideTags');
+	});
+});