@serverkgg/bridge 0.1.11 → 0.1.13

package/src/cli/readme.test.ts

@@ -0,0 +1,470 @@
+import { afterEach, beforeEach, describe, expect, it, spyOn } from "bun:test";
+import { existsSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { GameCategory, MANIFEST_SCHEMA_VERSION, PackageKind, readPackageDocument } from "../manifest";
+import { directorySource } from "./directorySource";
+import { README_FILE, renderReadme, runReadme } from "./readme";
+
+const SIBLINGS_ROOT = fileURLToPath(new URL("../../../../../", import.meta.url));
+
+const SIBLINGS = [
+	"minecraft-java",
+	"bot-node",
+	"platform",
+];
+
+const HEADINGS = [
+	"## Layout",
+	"## Guides",
+	"## Develop",
+	"## Contribute",
+	"## License",
+];
+
+const FULL_SCRIPTS = {
+	prepare: "git config core.hooksPath .githooks",
+	postinstall: "serverk-bridge link && (serverk-bridge rules || true)",
+	compile: "serverk-bridge compile",
+	validate: "serverk-bridge validate",
+	schema: "serverk-bridge schema",
+	check: "bunx biome check",
+	fix: "bunx biome check --write --unsafe",
+	tsc: "tsc",
+	test: "bun test --parallel",
+};
+
+const HOOK = `#!/usr/bin/env bash
+set -euo pipefail
+
+echo "pre-commit: fix"
+bun run fix
+
+echo "pre-commit: validate"
+bun run validate
+
+echo "pre-commit: schema"
+bunx serverk-bridge schema --check
+`;
+
+const FOOTER_EN = "Generated by `serverk-bridge readme` from `serverk.yml`; edit the manifest, not this file.";
+
+const LICENSE_EN = "The code is public to read. All rights are reserved by Serverk, and no license is granted.";
+
+const guideOf = (id: string) => ({
+	id,
+	title: {
+		ar: `شرح ${id}`,
+		en: `Guide ${id}`,
+	},
+	summary: {
+		ar: "ملخص الشرح.",
+		en: "The guide summary.",
+	},
+	bodyPath: {
+		ar: `guides/${id}/ar.md`,
+		en: `guides/${id}/en.md`,
+	},
+});
+
+const PORT = {
+	key: "game",
+	containerPort: 25_565,
+	protocol: "tcp",
+	hostRange: {
+		default: 25_565,
+		min: 25_565,
+		max: 25_664,
+	},
+};
+
+const gameManifestOf = (overrides: Record<string, unknown> = {}) => ({
+	schemaVersion: MANIFEST_SCHEMA_VERSION,
+	kind: PackageKind.Game,
+	metadata: {
+		id: "minecraft-java",
+		name: {
+			ar: "ماينكرافت جافا",
+			en: "Minecraft Java",
+		},
+		description: {
+			ar: "سيرفر ماينكرافت جافا الأصلي.",
+			en: "Minecraft Java Edition, vanilla.",
+		},
+		tagline: {
+			ar: "سيرفرك جاهز خلال دقيقة",
+			en: "Your server ready in a minute",
+		},
+		category: GameCategory.Sandbox,
+		logo: "assets/logo.webp",
+		banner: "assets/banner.webp",
+	},
+	resources: {
+		minMemoryMb: 1024,
+		recommendedMemoryMb: 4096,
+		minDiskMb: 5120,
+	},
+	container: {
+		image: "serverkgg/minecraft-java",
+		ports: [
+			PORT,
+		],
+	},
+	guides: [
+		guideOf("getting-started"),
+	],
+	...overrides,
+});
+
+const botManifestOf = () => ({
+	schemaVersion: MANIFEST_SCHEMA_VERSION,
+	kind: PackageKind.Bot,
+	metadata: {
+		id: "bot-node",
+		name: {
+			ar: "بوت نود",
+			en: "Node bot",
+		},
+		description: {
+			ar: "انشر بوتك من GitHub.",
+			en: "Deploy your bot from GitHub.",
+		},
+		tagline: {
+			ar: "أي بوت بـ Node.js",
+			en: "Any Node.js bot",
+		},
+		logo: "assets/logo.webp",
+		banner: "assets/banner.webp",
+	},
+	resources: {
+		minMemoryMb: 512,
+		recommendedMemoryMb: 1024,
+		minDiskMb: 2048,
+	},
+	container: {
+		image: "serverkgg/bot-node",
+		ports: [],
+	},
+	guides: [
+		guideOf("errors"),
+	],
+});
+
+const guidePackageOf = () => ({
+	schemaVersion: MANIFEST_SCHEMA_VERSION,
+	kind: PackageKind.Guide,
+	metadata: {
+		id: "platform",
+	},
+	guideTags: [
+		{
+			id: "start",
+			name: {
+				ar: "ابدأ من هنا",
+				en: "Start here",
+			},
+		},
+		{
+			id: "billing",
+			name: {
+				ar: "الفوترة",
+				en: "Billing",
+			},
+		},
+	],
+	guides: [
+		guideOf("billing"),
+	],
+});
+
+describe("renderReadme", () => {
+	let root = "";
+
+	const put = (path: string, content: string) => {
+		mkdirSync(dirname(join(root, path)), {
+			recursive: true,
+		});
+		writeFileSync(join(root, path), content);
+	};
+
+	const putPackage = (manifest: Record<string, unknown>, scripts: Record<string, string>) => {
+		put("serverk.yml", JSON.stringify(manifest));
+		put(
+			"package.json",
+			JSON.stringify({
+				name: "@serverkgg/package",
+				scripts,
+			}),
+		);
+	};
+
+	const render = () => {
+		const source = directorySource(root);
+
+		return renderReadme(source, readPackageDocument(source));
+	};
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "serverk-readme-"));
+	});
+
+	afterEach(() => {
+		rmSync(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	it("renders a game's banner, title, intro, sections and footer in order", () => {
+		putPackage(gameManifestOf(), FULL_SCRIPTS);
+		put(".githooks/pre-commit", HOOK);
+		put("serverk.schema.json", "{}");
+		put("src/driver.ts", "export const driver = {};\n");
+		put("image/Dockerfile", "FROM debian\n");
+		put("assets/logo.webp", "logo");
+		put("assets/banner.webp", "banner");
+		put("guides/getting-started/ar.md", "## البداية\n");
+		put("guides/getting-started/en.md", "## Start\n");
+
+		const readme = render();
+		const lines = readme.split("\n");
+
+		expect(lines.slice(0, 3)).toEqual([
+			"![Minecraft Java](assets/banner.webp)",
+			"",
+			"# ماينكرافت جافا (Minecraft Java)",
+		]);
+		expect(lines.filter((line) => line.startsWith("## "))).toEqual(HEADINGS);
+		expect(lines).toContain(
+			"يضم هذا الريبو كل ما تحتاجه منصة سيرفرك لتشغيل سيرفرات ماينكرافت جافا. سيرفر ماينكرافت جافا الأصلي. سيرفرك جاهز خلال دقيقة. صفحة اللعبة: [serverk.gg/games/minecraft-java](https://serverk.gg/games/minecraft-java)",
+		);
+		expect(lines).toContain(
+			"This repository holds everything Serverk needs to run Minecraft Java servers. Minecraft Java Edition, vanilla. Your server ready in a minute. Game page: [serverk.gg/games/minecraft-java](https://serverk.gg/games/minecraft-java)",
+		);
+		expect(lines.filter((line) => line.startsWith("- `"))).toEqual([
+			"- `serverk.yml`: the game manifest with its metadata, resources, ports, backup and reset rules, and the guide list.",
+			"- `serverk.schema.json`: the JSON Schema of `serverk.yml` for the editor, written by `serverk-bridge schema`.",
+			"- `src/`: the driver, built on `@serverkgg/bridge`; `src/driver.ts` exports it and `src/main.ts` serves it.",
+			"- `image/Dockerfile`: the container image, with the compiled bridge as its entrypoint.",
+			"- `assets/`: the logo and the banner the site and the panel show.",
+			"- `guides/<id>/ar.md` and `en.md`: the guide bodies; each guide's title, summary and tags live in `serverk.yml`.",
+			"- `bun install`: installs the dependencies, points Git at the hooks in `.githooks/` and writes `.claude/rules/package.md` from the bridge.",
+			"- `bun run check`: checks lint and formatting with Biome; `bun run fix` applies the fixes.",
+			"- `bun run tsc`: type-checks the code.",
+			"- `bun run test`: runs the tests.",
+			"- `bun run validate`: runs the checks the platform runs at publish, and fails while this README is out of date.",
+			"- `bun run compile`: builds `dist/bridge`, the linux/amd64 binary the image starts.",
+		]);
+		expect(lines).toContain(
+			"- [شرح getting-started · Guide getting-started](https://serverk.gg/games/minecraft-java/guides/getting-started)",
+		);
+		expect(lines).toContain(
+			"`.githooks/pre-commit` runs `bun run fix`, `bun run validate` and `bunx serverk-bridge schema --check` before every commit. There is no CI: a commit that passes the hook is ready.",
+		);
+		expect(lines).toContain(
+			"`bun install` runs `serverk-bridge link`, which links `@serverkgg/bridge` to a sibling `serverk` checkout at `../serverk/modules/bridge` when one exists. Never commit a `file:` or `link:` dependency.",
+		);
+		expect(readme).toContain("`bunx outdo package --prod --name minecraft-java`");
+		expect(readme).toContain(
+			"العربية هي لغة المصدر: يُكتب كل نص يقرؤه العميل بالعربية أولًا، بلغة رسمية مع لمسة خليجية خفيفة، ثم بالإنجليزية.",
+		);
+		expect(readme).toContain(
+			"Arabic is the source language: every string a customer reads is written in Arabic first, formal with a light Gulf touch, then in English.",
+		);
+		expect(readme).not.toContain(".claude/skills");
+		expect(lines).toContain(LICENSE_EN);
+		expect(lines.slice(-2)).toEqual([
+			FOOTER_EN,
+			"",
+		]);
+		expect(render()).toBe(readme);
+	});
+
+	it("lists only the layout entries on disk and the scripts package.json declares", () => {
+		putPackage(
+			gameManifestOf({
+				guides: [],
+			}),
+			{
+				validate: "serverk-bridge validate",
+			},
+		);
+		put("assets/logo.webp", "logo");
+		put("assets/banner.webp", "banner");
+		put("image/detect.json", "{}");
+
+		const lines = render().split("\n");
+
+		expect(lines.filter((line) => line.startsWith("- `"))).toEqual([
+			"- `serverk.yml`: the game manifest with its metadata, resources, ports, backup and reset rules, and the guide list.",
+			"- `assets/`: the logo and the banner the site and the panel show.",
+			"- `bun install`: installs the dependencies.",
+			"- `bun run validate`: runs the checks the platform runs at publish, and fails while this README is out of date.",
+		]);
+		expect(lines.filter((line) => line.startsWith("## "))).toEqual([
+			"## Layout",
+			"## Develop",
+			"## Contribute",
+			"## License",
+		]);
+		expect(lines.some((line) => line.includes("pre-commit") || line.includes("serverk-bridge link"))).toBe(false);
+	});
+
+	it("says nothing about CI when the repository has a workflow", () => {
+		putPackage(gameManifestOf(), FULL_SCRIPTS);
+		put(".githooks/pre-commit", HOOK);
+		put(".github/workflows/check.yml", "on: push\n");
+
+		expect(render()).toContain(
+			"`.githooks/pre-commit` runs `bun run fix`, `bun run validate` and `bunx serverk-bridge schema --check` before every commit.\n",
+		);
+	});
+
+	it("links a bot to the bots page and its guides, and lists its launcher and detection table", () => {
+		putPackage(botManifestOf(), FULL_SCRIPTS);
+		put("image/Dockerfile", "FROM node\n");
+		put("image/launcher.mjs", "");
+		put("image/detect.json", "{}");
+		put("templates/discord-node/index.js", "");
+
+		const lines = render().split("\n");
+
+		expect(lines.slice(0, 3)).toEqual([
+			"![Node bot](assets/banner.webp)",
+			"",
+			"# بوت نود (Node bot)",
+		]);
+		expect(lines).toContain(
+			"يضم هذا الريبو بيئة تشغيل بوت نود، وهي كل ما تحتاجه منصة سيرفرك لتشغيل بوتك. انشر بوتك من GitHub. أي بوت بـ Node.js. صفحة البوتات: [serverk.gg/bots](https://serverk.gg/bots)",
+		);
+		expect(lines).toContain(
+			"This repository holds the Node bot runtime: everything Serverk needs to run your bot. Deploy your bot from GitHub. Any Node.js bot. Bots page: [serverk.gg/bots](https://serverk.gg/bots)",
+		);
+		expect(lines).toContain("- [شرح errors · Guide errors](https://serverk.gg/bots/bot-node/guides/errors)");
+		expect(lines).toContain(
+			"- `image/launcher.mjs`: what the bridge starts; it puts the deployed code in place, installs its dependencies and starts the bot.",
+		);
+		expect(lines).toContain(
+			"- `image/detect.json`: the start and install table the launcher reads, written by `serverk-bridge detect-table`.",
+		);
+		expect(lines).toContain(
+			"- `templates/`: starter bots, synced to the public `serverkgg/bot-template-*` repositories by `bunx outdo templates`.",
+		);
+	});
+
+	it("renders the guide package with its tags, its guides under /guides, the blog and its own release", () => {
+		putPackage(guidePackageOf(), {
+			validate: "serverk-bridge validate",
+		});
+		put("blog/first-server/ar.md", "---\n");
+
+		const readme = render();
+		const lines = readme.split("\n");
+
+		expect(lines[0]).toBe("# شروحات المنصة (Platform guides)");
+		expect(readme).not.toContain("banner");
+		expect(lines).toContain(
+			"يضم هذا الريبو الشروحات العامة لمنصة سيرفرك، وهي كل شرح لا يرتبط بلعبة معيّنة. وتتوزع على هذه الأقسام: «ابدأ من هنا»، و«الفوترة». صفحة الشروحات: [serverk.gg/guides](https://serverk.gg/guides)",
+		);
+		expect(lines).toContain(
+			'This repository holds the general guides for Serverk: every guide that is not tied to one game. They are grouped under "Start here" and "Billing". Guides page: [serverk.gg/guides](https://serverk.gg/guides)',
+		);
+		expect(lines).toContain("- [شرح billing · Guide billing](https://serverk.gg/guides/billing)");
+		expect(lines.some((line) => line.startsWith("- `blog/<id>/ar.md` and `en.md`: the blog articles"))).toBe(true);
+		expect(readme).toContain("`bunx outdo platform --prod`");
+		expect(readme).not.toContain("outdo package");
+	});
+
+	for (const sibling of SIBLINGS) {
+		const dir = join(SIBLINGS_ROOT, sibling);
+
+		it.skipIf(!existsSync(join(dir, "serverk.yml")))(
+			`renders the ${sibling} readme from its own manifest, the same every time and under 90 lines`,
+			() => {
+				const source = directorySource(dir);
+				const document = readPackageDocument(source);
+				const readme = renderReadme(source, document);
+				const lines = readme.split("\n");
+				const name =
+					document.kind === PackageKind.Guide
+						? {
+								ar: "شروحات المنصة",
+								en: "Platform guides",
+							}
+						: document.metadata.name;
+
+				expect(lines).toContain(`# ${name.ar} (${name.en})`);
+				expect(lines.filter((line) => line.startsWith("## "))).toEqual(HEADINGS);
+				expect(lines.filter((line) => line.startsWith("- [")).length).toBe(document.guides.length);
+
+				for (const guide of document.guides) {
+					expect(readme).toContain(`/guides/${guide.id})`);
+				}
+
+				expect(lines.length).toBeLessThan(90);
+				expect(renderReadme(source, document)).toBe(readme);
+			},
+		);
+	}
+});
+
+describe("runReadme", () => {
+	let root = "";
+	let restore = () => {};
+
+	const target = () => {
+		return join(root, README_FILE);
+	};
+
+	const run = (...args: string[]) => {
+		return runReadme([
+			"--dir",
+			root,
+			...args,
+		]);
+	};
+
+	beforeEach(() => {
+		root = mkdtempSync(join(tmpdir(), "serverk-readme-run-"));
+		writeFileSync(join(root, "serverk.yml"), JSON.stringify(gameManifestOf()));
+
+		const spy = spyOn(console, "log").mockImplementation(() => {});
+
+		restore = () => spy.mockRestore();
+	});
+
+	afterEach(() => {
+		restore();
+		rmSync(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	it("writes README.md from the manifest, then passes its own check", async () => {
+		await run();
+
+		const source = directorySource(root);
+
+		expect(readFileSync(target(), "utf8")).toBe(renderReadme(source, readPackageDocument(source)));
+
+		await expect(run("--check")).resolves.toBeUndefined();
+	});
+
+	it("check fails on a missing README and writes nothing", async () => {
+		await expect(run("--check")).rejects.toThrow(`${target()} is missing — run "serverk-bridge readme" and commit it`);
+
+		expect(existsSync(target())).toBe(false);
+	});
+
+	it("check fails on a stale README and leaves it alone", async () => {
+		writeFileSync(target(), "# edited by hand\n");
+
+		await expect(run("--check")).rejects.toThrow(
+			`${target()} is out of date — run "serverk-bridge readme" and commit it`,
+		);
+
+		expect(readFileSync(target(), "utf8")).toBe("# edited by hand\n");
+	});
+});