@serverkgg/bridge 0.1.12 → 0.1.13

package/src/cli/readme.ts

@@ -0,0 +1,570 @@
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import {
+	type GuideEntry,
+	type GuideTag,
+	type LocalizedText,
+	MANIFEST_FILE,
+	type Package,
+	PackageKind,
+	type PackageSource,
+	readPackageDocument,
+} from "../manifest";
+import { directorySource } from "./directorySource";
+import { LINK_SOURCE } from "./link";
+import { writeRenderedFile } from "./renderedFile";
+
+export const README_FILE = "README.md";
+
+export const README_COMMAND = "serverk-bridge readme";
+
+const SITE_URL = "https://serverk.gg";
+
+const PACKAGE_FILE = "package.json";
+
+const HOOK_FILE = ".githooks/pre-commit";
+
+const WORKFLOWS_FOLDER = ".github/workflows/";
+
+const SENTENCE_END = /[.!?؟…]$/;
+
+const HOOK_COMMAND = /^(bun run|bunx) /;
+
+const GUIDE_PACKAGE_NAME: LocalizedText = {
+	ar: "شروحات المنصة",
+	en: "Platform guides",
+};
+
+const HELP = `serverk-bridge readme [options]
+
+write ${README_FILE} from ${MANIFEST_FILE}, package.json and the pre-commit hook, Arabic first, then English.
+the file is committed, and "serverk-bridge validate" fails while it is missing or out of date.
+
+options:
+  --dir <path>   package directory (default: current directory)
+  --check        change nothing, fail when the file is missing or out of date
+  --help         show this help`;
+
+interface LayoutEntry {
+	path: string;
+	label: string;
+	kinds: readonly PackageKind[];
+	text: string;
+}
+
+const RUNNABLE_KINDS = [
+	PackageKind.Game,
+	PackageKind.Bot,
+];
+
+const ALL_KINDS = [
+	PackageKind.Game,
+	PackageKind.Bot,
+	PackageKind.Guide,
+];
+
+const LAUNCHER_TEXT =
+	"what the bridge starts; it puts the deployed code in place, installs its dependencies and starts the bot.";
+
+const LAYOUT: readonly LayoutEntry[] = [
+	{
+		path: MANIFEST_FILE,
+		label: `\`${MANIFEST_FILE}\``,
+		kinds: [
+			PackageKind.Game,
+		],
+		text: "the game manifest with its metadata, resources, ports, backup and reset rules, and the guide list.",
+	},
+	{
+		path: MANIFEST_FILE,
+		label: `\`${MANIFEST_FILE}\``,
+		kinds: [
+			PackageKind.Bot,
+		],
+		text: "the bot manifest with its metadata, resources, environment vault, backup rules and the guide list.",
+	},
+	{
+		path: MANIFEST_FILE,
+		label: `\`${MANIFEST_FILE}\``,
+		kinds: [
+			PackageKind.Guide,
+		],
+		text: "the guide package manifest with each guide's id, title, summary, tags and body paths.",
+	},
+	{
+		path: "serverk.schema.json",
+		label: "`serverk.schema.json`",
+		kinds: ALL_KINDS,
+		text: `the JSON Schema of \`${MANIFEST_FILE}\` for the editor, written by \`serverk-bridge schema\`.`,
+	},
+	{
+		path: "src/",
+		label: "`src/`",
+		kinds: RUNNABLE_KINDS,
+		text: "the driver, built on `@serverkgg/bridge`; `src/driver.ts` exports it and `src/main.ts` serves it.",
+	},
+	{
+		path: "image/Dockerfile",
+		label: "`image/Dockerfile`",
+		kinds: RUNNABLE_KINDS,
+		text: "the container image, with the compiled bridge as its entrypoint.",
+	},
+	{
+		path: "image/launcher.mjs",
+		label: "`image/launcher.mjs`",
+		kinds: [
+			PackageKind.Bot,
+		],
+		text: LAUNCHER_TEXT,
+	},
+	{
+		path: "image/launcher.py",
+		label: "`image/launcher.py`",
+		kinds: [
+			PackageKind.Bot,
+		],
+		text: LAUNCHER_TEXT,
+	},
+	{
+		path: "image/detect.json",
+		label: "`image/detect.json`",
+		kinds: [
+			PackageKind.Bot,
+		],
+		text: "the start and install table the launcher reads, written by `serverk-bridge detect-table`.",
+	},
+	{
+		path: "templates/",
+		label: "`templates/`",
+		kinds: [
+			PackageKind.Bot,
+		],
+		text: "starter bots, synced to the public `serverkgg/bot-template-*` repositories by `bunx outdo templates`.",
+	},
+	{
+		path: "assets/",
+		label: "`assets/`",
+		kinds: RUNNABLE_KINDS,
+		text: "the logo and the banner the site and the panel show.",
+	},
+	{
+		path: "guides/",
+		label: "`guides/<id>/ar.md` and `en.md`",
+		kinds: ALL_KINDS,
+		text: `the guide bodies; each guide's title, summary and tags live in \`${MANIFEST_FILE}\`.`,
+	},
+	{
+		path: "blog/",
+		label: "`blog/<id>/ar.md` and `en.md`",
+		kinds: [
+			PackageKind.Guide,
+		],
+		text: `the blog articles at \`serverk.gg/blog/<id>\`, not listed in \`${MANIFEST_FILE}\`. Each file opens with YAML frontmatter holding \`title\` and \`summary\` per language; \`publishedAt\`, \`updatedAt\`, \`tags\` and \`video\` are read from \`ar.md\`.`,
+	},
+];
+
+const SCRIPT_TEXTS: readonly (readonly [
+	string,
+	string,
+])[] = [
+	[
+		"tsc",
+		"type-checks the code.",
+	],
+	[
+		"test",
+		"runs the tests.",
+	],
+	[
+		"validate",
+		"runs the checks the platform runs at publish, and fails while this README is out of date.",
+	],
+	[
+		"compile",
+		"builds `dist/bridge`, the linux/amd64 binary the image starts.",
+	],
+];
+
+const textOf = (bytes: Uint8Array | null) => {
+	return bytes === null ? null : new TextDecoder().decode(bytes);
+};
+
+const scriptsOf = (source: PackageSource): Record<string, string> => {
+	const text = textOf(source.read(PACKAGE_FILE));
+
+	if (text === null) {
+		return {};
+	}
+
+	let parsed: unknown;
+
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return {};
+	}
+
+	if (typeof parsed !== "object" || parsed === null || !("scripts" in parsed)) {
+		return {};
+	}
+
+	const scripts: unknown = parsed.scripts;
+
+	if (typeof scripts !== "object" || scripts === null) {
+		return {};
+	}
+
+	return Object.fromEntries(
+		Object.entries(scripts).filter(
+			(
+				entry,
+			): entry is [
+				string,
+				string,
+			] => typeof entry[1] === "string",
+		),
+	);
+};
+
+const hookCommandsOf = (source: PackageSource) => {
+	const text = textOf(source.read(HOOK_FILE));
+
+	if (text === null) {
+		return null;
+	}
+
+	return text
+		.split("\n")
+		.map((line) => line.trim())
+		.filter((line) => HOOK_COMMAND.test(line));
+};
+
+const sentenceOf = (text: string) => {
+	const trimmed = text.trim();
+
+	return SENTENCE_END.test(trimmed) ? trimmed : `${trimmed}.`;
+};
+
+const englishListOf = (items: readonly string[]) => {
+	if (items.length < 2) {
+		return items.join("");
+	}
+
+	return `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+};
+
+const arabicListOf = (items: readonly string[]) => {
+	return items.join("، و");
+};
+
+const codeOf = (text: string) => {
+	return `\`${text}\``;
+};
+
+const linkOf = (path: string) => {
+	return `[serverk.gg${path}](${SITE_URL}${path})`;
+};
+
+const linkTextOf = (text: string) => {
+	return text.replaceAll("[", "\\[").replaceAll("]", "\\]");
+};
+
+const nameOf = (document: Package) => {
+	return document.kind === PackageKind.Guide ? GUIDE_PACKAGE_NAME : document.metadata.name;
+};
+
+const pagePathOf = (document: Package) => {
+	switch (document.kind) {
+		case PackageKind.Game: {
+			return `/games/${document.metadata.id}`;
+		}
+
+		case PackageKind.Bot: {
+			return "/bots";
+		}
+
+		case PackageKind.Guide: {
+			return "/guides";
+		}
+	}
+};
+
+const guidePathOf = (document: Package, guide: GuideEntry) => {
+	switch (document.kind) {
+		case PackageKind.Game: {
+			return `/games/${document.metadata.id}/guides/${guide.id}`;
+		}
+
+		case PackageKind.Bot: {
+			return `/bots/${document.metadata.id}/guides/${guide.id}`;
+		}
+
+		case PackageKind.Guide: {
+			return `/guides/${guide.id}`;
+		}
+	}
+};
+
+const releaseCommandOf = (document: Package) => {
+	return document.kind === PackageKind.Guide
+		? "bunx outdo platform --prod"
+		: `bunx outdo package --prod --name ${document.metadata.id}`;
+};
+
+const tagSentencesOf = (tags: readonly GuideTag[]): LocalizedText | null => {
+	if (tags.length === 0) {
+		return null;
+	}
+
+	return {
+		ar: ` وتتوزع على هذه الأقسام: ${arabicListOf(tags.map((tag) => `«${tag.name.ar}»`))}.`,
+		en: ` They are grouped under ${englishListOf(tags.map((tag) => `"${tag.name.en}"`))}.`,
+	};
+};
+
+const introOf = (document: Package): LocalizedText => {
+	const page = linkOf(pagePathOf(document));
+
+	switch (document.kind) {
+		case PackageKind.Game: {
+			const { name, description, tagline } = document.metadata;
+
+			return {
+				ar: `يضم هذا الريبو كل ما تحتاجه منصة سيرفرك لتشغيل سيرفرات ${name.ar}. ${sentenceOf(description.ar)} ${sentenceOf(tagline.ar)} صفحة اللعبة: ${page}`,
+				en: `This repository holds everything Serverk needs to run ${name.en} servers. ${sentenceOf(description.en)} ${sentenceOf(tagline.en)} Game page: ${page}`,
+			};
+		}
+
+		case PackageKind.Bot: {
+			const { name, description, tagline } = document.metadata;
+
+			return {
+				ar: `يضم هذا الريبو بيئة تشغيل ${name.ar}، وهي كل ما تحتاجه منصة سيرفرك لتشغيل بوتك. ${sentenceOf(description.ar)} ${sentenceOf(tagline.ar)} صفحة البوتات: ${page}`,
+				en: `This repository holds the ${name.en} runtime: everything Serverk needs to run your bot. ${sentenceOf(description.en)} ${sentenceOf(tagline.en)} Bots page: ${page}`,
+			};
+		}
+
+		case PackageKind.Guide: {
+			const tags = tagSentencesOf(document.guideTags);
+
+			return {
+				ar: `يضم هذا الريبو الشروحات العامة لمنصة سيرفرك، وهي كل شرح لا يرتبط بلعبة معيّنة.${tags?.ar ?? ""} صفحة الشروحات: ${page}`,
+				en: `This repository holds the general guides for Serverk: every guide that is not tied to one game.${tags?.en ?? ""} Guides page: ${page}`,
+			};
+		}
+	}
+};
+
+const headerOf = (document: Package) => {
+	const name = nameOf(document);
+	const intro = introOf(document);
+	const title = `# ${name.ar} (${name.en})`;
+
+	if (document.kind === PackageKind.Guide) {
+		return [
+			title,
+			intro.ar,
+			intro.en,
+		];
+	}
+
+	return [
+		`![${linkTextOf(name.en)}](${document.metadata.banner})`,
+		title,
+		intro.ar,
+		intro.en,
+	];
+};
+
+const layoutOf = (document: Package, paths: readonly string[]) => {
+	const present = (path: string) => {
+		return path.endsWith("/") ? paths.some((entry) => entry.startsWith(path)) : paths.includes(path);
+	};
+
+	const lines = LAYOUT.filter((entry) => entry.kinds.includes(document.kind) && present(entry.path)).map(
+		(entry) => `- ${entry.label}: ${entry.text}`,
+	);
+
+	return [
+		"## Layout",
+		lines.join("\n"),
+	];
+};
+
+const guidesOf = (document: Package) => {
+	if (document.guides.length === 0) {
+		return [];
+	}
+
+	const lines = document.guides.map(
+		(guide) =>
+			`- [${linkTextOf(guide.title.ar)} · ${linkTextOf(guide.title.en)}](${SITE_URL}${guidePathOf(document, guide)})`,
+	);
+
+	return [
+		"## Guides",
+		lines.join("\n"),
+	];
+};
+
+const installLineOf = (scripts: Record<string, string>) => {
+	const parts = [
+		"installs the dependencies",
+	];
+
+	if (scripts.prepare?.includes("core.hooksPath")) {
+		parts.push("points Git at the hooks in `.githooks/`");
+	}
+
+	if (scripts.postinstall?.includes("serverk-bridge rules")) {
+		parts.push("writes `.claude/rules/package.md` from the bridge");
+	}
+
+	return `- \`bun install\`: ${englishListOf(parts)}.`;
+};
+
+const scriptLinesOf = (scripts: Record<string, string>) => {
+	const lines: string[] = [];
+
+	if (scripts.check !== undefined) {
+		const fix = scripts.fix === undefined ? "" : "; `bun run fix` applies the fixes";
+
+		lines.push(`- \`bun run check\`: checks lint and formatting with Biome${fix}.`);
+	}
+
+	for (const [script, text] of SCRIPT_TEXTS) {
+		if (scripts[script] !== undefined) {
+			lines.push(`- \`bun run ${script}\`: ${text}`);
+		}
+	}
+
+	return lines;
+};
+
+const hookParagraphOf = (source: PackageSource, paths: readonly string[]) => {
+	const commands = hookCommandsOf(source);
+
+	if (commands === null || commands.length === 0) {
+		return [];
+	}
+
+	const ci = paths.some((path) => path.startsWith(WORKFLOWS_FOLDER))
+		? ""
+		: " There is no CI: a commit that passes the hook is ready.";
+
+	return [
+		`${codeOf(HOOK_FILE)} runs ${englishListOf(commands.map(codeOf))} before every commit.${ci}`,
+	];
+};
+
+const linkParagraphOf = (scripts: Record<string, string>) => {
+	if (!scripts.postinstall?.includes("serverk-bridge link")) {
+		return [];
+	}
+
+	return [
+		`\`bun install\` runs \`serverk-bridge link\`, which links \`@serverkgg/bridge\` to a sibling \`serverk\` checkout at \`${LINK_SOURCE}\` when one exists. Never commit a \`file:\` or \`link:\` dependency.`,
+	];
+};
+
+const developOf = (source: PackageSource, paths: readonly string[]) => {
+	const scripts = scriptsOf(source);
+
+	return [
+		"## Develop",
+		"Everything runs on [Bun](https://bun.sh).",
+		[
+			installLineOf(scripts),
+			...scriptLinesOf(scripts),
+		].join("\n"),
+		...hookParagraphOf(source, paths),
+		...linkParagraphOf(scripts),
+	];
+};
+
+const contributeOf = (document: Package) => {
+	const release = codeOf(releaseCommandOf(document));
+	const ar = [
+		"افتح issue لأي مشكلة أو اقتراح، بالعربية أو بالإنجليزية.",
+		`ينشر فريق سيرفرك هذا الريبو من ريبو \`serverk\` بالأمر ${release}، ويصل كل تغيير مدموج مع النشر التالي.`,
+		"العربية هي لغة المصدر: يُكتب كل نص يقرؤه العميل بالعربية أولًا، بلغة رسمية مع لمسة خليجية خفيفة، ثم بالإنجليزية.",
+		"أبقِ أسماء الملفات والأوامر والمفاتيح بالحروف اللاتينية.",
+	];
+	const en = [
+		"Open an issue for any problem or suggestion, in Arabic or English.",
+		`Serverk releases this repository from \`serverk\` with ${release}; merged changes ride the next release.`,
+		"Arabic is the source language: every string a customer reads is written in Arabic first, formal with a light Gulf touch, then in English.",
+		"Keep file names, commands and config keys in Latin script.",
+	];
+
+	return [
+		"## Contribute",
+		ar.join(" "),
+		en.join(" "),
+	];
+};
+
+const licenseOf = () => {
+	return [
+		"## License",
+		"الكود متاح للقراءة، وجميع الحقوق محفوظة لمنصة سيرفرك، ولا يُمنح أي ترخيص.",
+		"The code is public to read. All rights are reserved by Serverk, and no license is granted.",
+	];
+};
+
+const footerOf = () => {
+	return [
+		`يُنشأ هذا الملف بالأمر \`${README_COMMAND}\` من \`${MANIFEST_FILE}\`، فعدّل ملف التعريف لا هذا الملف.`,
+		`Generated by \`${README_COMMAND}\` from \`${MANIFEST_FILE}\`; edit the manifest, not this file.`,
+	];
+};
+
+export const renderReadme = (source: PackageSource, document: Package) => {
+	const paths = source.list();
+	const blocks = [
+		...headerOf(document),
+		...layoutOf(document, paths),
+		...guidesOf(document),
+		...developOf(source, paths),
+		...contributeOf(document),
+		...licenseOf(),
+		...footerOf(),
+	];
+
+	return `${blocks.join("\n\n")}\n`;
+};
+
+export const runReadme = async (args: string[]) => {
+	const { values } = parseArgs({
+		args,
+		options: {
+			dir: {
+				type: "string",
+				default: ".",
+			},
+			check: {
+				type: "boolean",
+				default: false,
+			},
+			help: {
+				type: "boolean",
+				default: false,
+			},
+		},
+	});
+
+	if (values.help) {
+		console.log(HELP);
+
+		return;
+	}
+
+	const source = directorySource(resolve(values.dir));
+
+	writeRenderedFile({
+		out: join(values.dir, README_FILE),
+		check: values.check,
+		rendered: renderReadme(source, readPackageDocument(source)),
+		command: README_COMMAND,
+	});
+};

package/src/cli/validate.test.ts

@@ -5,7 +5,7 @@ import { join } from "node:path";
 import { BOT_SWITCH_ON, BOT_WEB, BOT_WEB_PORT_KEY, renderDetectTable } from "../bot/detect";
 import { BridgeKind, BridgeSetupStepKind } from "../core";
 import { GuideOpenTab, type GuidePack, type ParsedBlock, type ParsedLeafBlock } from "../guides";
-import { MANIFEST_SCHEMA_VERSION, PackageKind, type RunnableManifest } from "../manifest";
+import { MANIFEST_SCHEMA_VERSION, PackageKind, packageSchema, type RunnableManifest } from "../manifest";
 import type { BridgeDriver, BridgePendingModule, BridgeSetupModule } from "../modules";
 import {
 	type BridgeCatalogSection,
@@ -19,6 +19,8 @@ import {
 	type BridgeTab,
 	type BridgeTableSection,
 } from "../panel";
+import { directorySource } from "./directorySource";
+import { README_FILE, renderReadme } from "./readme";
 import { RULES_FILE, readShippedRules, writeRules } from "./rules";
 import {
 	availabilityReportLines,
@@ -508,6 +510,12 @@ describe("validating a bot package", () => {
 		writeFileSync(join(root, "assets/banner.webp"), webp(1280, 720));
 		writeFileSync(join(root, "src/driver.ts"), BOT_DRIVER);
 		writeRules(root, readShippedRules());
+
+		const parsed = packageSchema.safeParse(manifest);
+
+		if (parsed.success) {
+			writeFileSync(join(root, README_FILE), renderReadme(directorySource(root), parsed.data));
+		}
 	};
 
 	const validate = () => {
@@ -547,9 +555,41 @@ describe("validating a bot package", () => {
 		);
 		expect(lines).toContain("  environment: vault off");
 		expect(lines).toContain("  detect: image/detect.json matches this bridge");
+		expect(lines).toContain("  readme: README.md matches serverk.yml");
 		expect(lines.some((line) => line.includes("warning"))).toBe(false);
 	});
 
+	it("fails a bot whose README is missing", async () => {
+		writeBot(botManifest());
+		rmSync(join(root, README_FILE));
+
+		await expect(validate()).rejects.toThrow('README.md is missing — run "serverk-bridge readme" and commit it');
+	});
+
+	it("fails a bot whose README is out of date", async () => {
+		writeBot(botManifest());
+		writeFileSync(join(root, README_FILE), "# edited by hand\n");
+
+		await expect(validate()).rejects.toThrow('README.md is out of date — run "serverk-bridge readme" and commit it');
+	});
+
+	it("fails a bot whose README no longer matches its manifest", async () => {
+		writeBot(botManifest());
+		writeFileSync(
+			join(root, "serverk.yml"),
+			JSON.stringify(
+				botManifest({
+					metadata: {
+						...botManifest().metadata,
+						name: text("Renamed bot"),
+					},
+				}),
+			),
+		);
+
+		await expect(validate()).rejects.toThrow('README.md is out of date — run "serverk-bridge readme" and commit it');
+	});
+
 	it("warns about a missing rule file and still validates", async () => {
 		writeBot(botManifest());
 		rmSync(join(root, RULES_FILE));

package/src/cli/validate.ts

@@ -40,6 +40,7 @@ import {
 } from "../protocol";
 import { validateDriver, validatePortActivation } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
+import { README_COMMAND, README_FILE, renderReadme } from "./readme";
 import { rulesReportLines } from "./rules";
 
 const HELP = `serverk-bridge validate [options]
@@ -173,8 +174,14 @@ const validateGuidePackage = (source: PackageSource, document: GuidePackage) =>
 
 	const pack = readGuidePackage(source, document);
 	const articles = compileArticles(source);
+	const readme = readmeLines(source, document);
 
 	console.log(`${document.metadata.id} is valid`);
+
+	for (const line of readme) {
+		console.log(line);
+	}
+
 	reportGuides(pack);
 	reportArticles(articles);
 };
@@ -644,6 +651,22 @@ export const botDetectLines = (source: PackageSource, manifest: RunnableManifest
 	];
 };
 
+export const readmeLines = (source: PackageSource, document: Package): string[] => {
+	const bytes = source.read(README_FILE);
+
+	if (bytes === null) {
+		throw new Error(`${README_FILE} is missing — run "${README_COMMAND}" and commit it`);
+	}
+
+	if (new TextDecoder().decode(bytes) !== renderReadme(source, document)) {
+		throw new Error(`${README_FILE} is out of date — run "${README_COMMAND}" and commit it`);
+	}
+
+	return [
+		`  readme: ${README_FILE} matches ${MANIFEST_FILE}`,
+	];
+};
+
 const validateRunnablePackage = async (
 	source: PackageSource,
 	manifest: RunnableManifest,
@@ -670,6 +693,7 @@ const validateRunnablePackage = async (
 	}
 
 	const detectLines = botDetectLines(source, manifest);
+	const readme = readmeLines(source, manifest);
 	const driverPath = driverArg ? resolve(driverArg) : join(dir, "src/driver.ts");
 
 	if (!existsSync(driverPath)) {
@@ -721,6 +745,7 @@ const validateRunnablePackage = async (
 		...botPortLines(manifest),
 		...botEnvironmentLines(manifest),
 		...detectLines,
+		...readme,
 		...rulesReportLines(dir),
 	]) {
 		console.log(line);

package/src/context/bridgeContext.ts

@@ -220,4 +220,5 @@ export interface BridgeContext {
 	emit(event: string, payload?: BridgeValues): void;
 	restart(): Promise<void>;
 	log: BridgeLog;
+	print(line: string, stream?: BridgeStream): void;
 }

package/src/modules/bridgeModule.ts

@@ -108,6 +108,7 @@ export interface BridgeTerminalModule {
 	kind: BridgeKind.Terminal;
 	commands: BridgeTerminalCommand[];
 	rules?: BridgeTerminalRule[];
+	shell?: boolean;
 	run?(context: BridgeContext, input: string): Promise<BridgeReply | null>;
 }