@serverkgg/bridge 0.0.10 → 0.0.12

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.10",
+	"version": "0.0.12",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
@@ -21,6 +21,8 @@
 		"./protocol": "./src/protocol/index.ts",
 		"./manifest": "./src/manifest/index.ts",
 		"./guides": "./src/guides/index.ts",
+		"./blog": "./src/blog/index.ts",
+		"./probes": "./src/probes/index.ts",
 		"./wire": "./src/wire/index.ts",
 		"./package.json": "./package.json"
 	},

package/src/blog/articleFrontmatter.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import { parseArticleFrontmatter, parseArticleTranslationFrontmatter, splitFrontmatter } from "./articleFrontmatter";
+
+const article = (front: string, body = "## عنوان\n\nنص.\n") => `---\n${front}\n---\n\n${body}`;
+
+const VALID = `title: كيف تسوي سيرفر
+summary: ثلاث طرق تسوي فيها سيرفر.
+publishedAt: 2026-09-05
+tags:
+  - minecraft`;
+
+describe("splitFrontmatter", () => {
+	test("blanks the frontmatter lines so body line numbers stay true", () => {
+		const split = splitFrontmatter("blog/x/ar.md", article(VALID));
+
+		expect(split.body.split("\n").slice(0, 7)).toEqual([
+			"",
+			"",
+			"",
+			"",
+			"",
+			"",
+			"",
+		]);
+		expect(split.body).toContain("## عنوان");
+	});
+
+	test("rejects a file that does not open with a fence", () => {
+		expect(() => splitFrontmatter("blog/x/ar.md", "## عنوان\n")).toThrow('must open with a "---" frontmatter block');
+	});
+
+	test("rejects a frontmatter block that is never closed", () => {
+		expect(() => splitFrontmatter("blog/x/ar.md", `---\n${VALID}\n`)).toThrow("never closed");
+	});
+});
+
+describe("parseArticleFrontmatter", () => {
+	test("reads every declared field", () => {
+		const parsed = parseArticleFrontmatter(
+			"blog/x/ar.md",
+			article(`${VALID}\nupdatedAt: 2026-09-06\nvideo: dQw4w9WgXcQ`),
+		);
+
+		expect(parsed.front.title).toBe("كيف تسوي سيرفر");
+		expect(parsed.front.publishedAt).toBe("2026-09-05");
+		expect(parsed.front.updatedAt).toBe("2026-09-06");
+		expect(parsed.front.video).toBe("dQw4w9WgXcQ");
+		expect(parsed.front.tags).toEqual([
+			"minecraft",
+		]);
+	});
+
+	test("defaults tags to an empty list", () => {
+		const parsed = parseArticleFrontmatter(
+			"blog/x/ar.md",
+			article("title: عنوان\nsummary: ملخص.\npublishedAt: 2026-09-05"),
+		);
+
+		expect(parsed.front.tags).toEqual([]);
+		expect(parsed.front.updatedAt).toBeUndefined();
+	});
+
+	test("rejects a missing title", () => {
+		expect(() => parseArticleFrontmatter("blog/x/ar.md", article("summary: ملخص.\npublishedAt: 2026-09-05"))).toThrow(
+			"frontmatter is invalid",
+		);
+	});
+
+	test("rejects a publishedAt that is not a calendar date", () => {
+		expect(() =>
+			parseArticleFrontmatter(
+				"blog/x/ar.md",
+				article("title: عنوان\nsummary: ملخص.\npublishedAt: 2026-09-05T00:00:00Z"),
+			),
+		).toThrow("must be a calendar date");
+	});
+
+	test("rejects an unknown key", () => {
+		expect(() => parseArticleFrontmatter("blog/x/ar.md", article(`${VALID}\nauthor: mohammed`))).toThrow(
+			"frontmatter is invalid",
+		);
+	});
+});
+
+describe("parseArticleTranslationFrontmatter", () => {
+	test("lets a translation omit the language-independent fields", () => {
+		const parsed = parseArticleTranslationFrontmatter(
+			"blog/x/en.md",
+			article("title: How to make a server\nsummary: The three ways."),
+		);
+
+		expect(parsed.front.publishedAt).toBeUndefined();
+		expect(parsed.front.tags).toBeUndefined();
+	});
+});

package/src/blog/articleFrontmatter.ts

@@ -0,0 +1,99 @@
+import { z } from "zod";
+import { zGuideTag, zYoutubeId } from "../manifest/guide";
+
+export const ARTICLE_TITLE_MAX = 120;
+
+export const ARTICLE_SUMMARY_MAX = 300;
+
+export const ARTICLE_TAGS_MAX = 8;
+
+export const FRONTMATTER_FENCE = "---";
+
+export const zArticleDate = z.iso.date("must be a calendar date, for example 2026-09-05");
+
+export const articleFrontmatterSchema = z.strictObject({
+	title: z.string().min(1).max(ARTICLE_TITLE_MAX),
+	summary: z.string().min(1).max(ARTICLE_SUMMARY_MAX),
+	publishedAt: zArticleDate,
+	updatedAt: zArticleDate.optional(),
+	tags: z.array(zGuideTag).max(ARTICLE_TAGS_MAX).default([]),
+	video: zYoutubeId.optional(),
+});
+
+export type ArticleFrontmatter = z.infer<typeof articleFrontmatterSchema>;
+
+export const articleTranslationFrontmatterSchema = articleFrontmatterSchema.extend({
+	publishedAt: zArticleDate.optional(),
+	tags: z.array(zGuideTag).max(ARTICLE_TAGS_MAX).optional(),
+});
+
+export type ArticleTranslationFrontmatter = z.infer<typeof articleTranslationFrontmatterSchema>;
+
+export interface SplitFrontmatter {
+	data: unknown;
+	body: string;
+}
+
+export const splitFrontmatter = (path: string, text: string): SplitFrontmatter => {
+	const lines = text.replace(/^/, "").split(/\r?\n/);
+
+	if (lines[0]?.trim() !== FRONTMATTER_FENCE) {
+		throw new Error(`${path}:1 must open with a "${FRONTMATTER_FENCE}" frontmatter block`);
+	}
+
+	const close = lines.findIndex((line, index) => index > 0 && line.trim() === FRONTMATTER_FENCE);
+
+	if (close === -1) {
+		throw new Error(`${path}:1 frontmatter block is never closed with "${FRONTMATTER_FENCE}"`);
+	}
+
+	let data: unknown;
+
+	try {
+		data = Bun.YAML.parse(lines.slice(1, close).join("\n"));
+	} catch (error) {
+		throw new Error(`${path}:2 frontmatter is not valid YAML — ${error instanceof Error ? error.message : error}`);
+	}
+
+	return {
+		data: data ?? {},
+		body: [
+			...lines.slice(0, close + 1).map(() => ""),
+			...lines.slice(close + 1),
+		].join("\n"),
+	};
+};
+
+export interface ParsedArticleFile<TFrontmatter> {
+	front: TFrontmatter;
+	body: string;
+}
+
+const parseWith = <TSchema extends z.ZodType>(
+	schema: TSchema,
+	path: string,
+	text: string,
+): ParsedArticleFile<z.infer<TSchema>> => {
+	const split = splitFrontmatter(path, text);
+	const parsed = schema.safeParse(split.data);
+
+	if (!parsed.success) {
+		throw new Error(`${path} frontmatter is invalid\n${z.prettifyError(parsed.error)}`);
+	}
+
+	return {
+		front: parsed.data,
+		body: split.body,
+	};
+};
+
+export const parseArticleFrontmatter = (path: string, text: string): ParsedArticleFile<ArticleFrontmatter> => {
+	return parseWith(articleFrontmatterSchema, path, text);
+};
+
+export const parseArticleTranslationFrontmatter = (
+	path: string,
+	text: string,
+): ParsedArticleFile<ArticleTranslationFrontmatter> => {
+	return parseWith(articleTranslationFrontmatterSchema, path, text);
+};

package/src/blog/compile.test.ts

@@ -0,0 +1,148 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { directorySource } from "../cli/directorySource";
+import { compileArticles, resolveArticleImages } from "./compile";
+
+const body = (heading: string) => `## ${heading}\n\nنص المقال هنا.\n`;
+
+describe("compileArticles", () => {
+	let root = "";
+
+	const write = (id: string, ar: string, en: string) => {
+		mkdirSync(join(root, "blog", id), {
+			recursive: true,
+		});
+		writeFileSync(join(root, "blog", id, "ar.md"), ar);
+		writeFileSync(join(root, "blog", id, "en.md"), en);
+	};
+
+	const article = (front: string, heading: string) => `---\n${front}\n---\n\n${body(heading)}`;
+
+	const compile = () => compileArticles(directorySource(root));
+
+	beforeEach(() => {
+		root = mkdtempSync(`${tmpdir()}/serverk-blog-`);
+	});
+
+	afterEach(() => {
+		rmSync(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("returns nothing when the package has no blog directory", () => {
+		expect(compile().drafts).toEqual([]);
+	});
+
+	test("compiles both languages into one article", () => {
+		write(
+			"make-a-server",
+			article("title: كيف تسوي سيرفر\nsummary: ثلاث طرق.\npublishedAt: 2026-09-05\ntags:\n  - minecraft", "عنوان"),
+			article("title: How to make a server\nsummary: Three ways.", "Heading"),
+		);
+
+		const [draft] = compile().drafts;
+
+		expect(draft?.id).toBe("make-a-server");
+		expect(draft?.title).toEqual({
+			ar: "كيف تسوي سيرفر",
+			en: "How to make a server",
+		});
+		expect(draft?.summary.en).toBe("Three ways.");
+		expect(draft?.publishedAt).toBe("2026-09-05");
+		expect(draft?.updatedAt).toBeNull();
+		expect(draft?.videoId).toBeNull();
+		expect(draft?.tags).toEqual([
+			"minecraft",
+		]);
+		expect(draft?.body.ar.at(0)).toMatchObject({
+			type: "heading",
+		});
+	});
+
+	test("records both markdown files so the bundle digest covers them", () => {
+		write(
+			"one",
+			article("title: عنوان\nsummary: ملخص.\npublishedAt: 2026-09-05", "عنوان"),
+			article("title: Title\nsummary: Summary.", "Heading"),
+		);
+
+		expect(compile().files).toEqual([
+			"blog/one/ar.md",
+			"blog/one/en.md",
+		]);
+	});
+
+	test("orders newest first and breaks ties by id", () => {
+		write(
+			"beta",
+			article("title: ب\nsummary: ملخص.\npublishedAt: 2026-09-05", "عنوان"),
+			article("title: Beta\nsummary: Summary.", "Heading"),
+		);
+		write(
+			"alpha",
+			article("title: أ\nsummary: ملخص.\npublishedAt: 2026-09-05", "عنوان"),
+			article("title: Alpha\nsummary: Summary.", "Heading"),
+		);
+		write(
+			"newer",
+			article("title: ج\nsummary: ملخص.\npublishedAt: 2026-09-07", "عنوان"),
+			article("title: Newer\nsummary: Summary.", "Heading"),
+		);
+
+		expect(compile().drafts.map((draft) => draft.id)).toEqual([
+			"newer",
+			"alpha",
+			"beta",
+		]);
+	});
+
+	test("rejects a translation that contradicts a language-independent field", () => {
+		write(
+			"one",
+			article("title: عنوان\nsummary: ملخص.\npublishedAt: 2026-09-05", "عنوان"),
+			article("title: Title\nsummary: Summary.\npublishedAt: 2026-09-06", "Heading"),
+		);
+
+		expect(compile).toThrow("a language-independent field must match");
+	});
+
+	test("accepts a translation that repeats a language-independent field with the same value", () => {
+		write(
+			"one",
+			article("title: عنوان\nsummary: ملخص.\npublishedAt: 2026-09-05\ntags:\n  - minecraft", "عنوان"),
+			article("title: Title\nsummary: Summary.\npublishedAt: 2026-09-05\ntags:\n  - minecraft", "Heading"),
+		);
+
+		expect(compile().drafts).toHaveLength(1);
+	});
+
+	test("reports a missing english translation", () => {
+		mkdirSync(join(root, "blog", "one"), {
+			recursive: true,
+		});
+		writeFileSync(
+			join(root, "blog", "one", "ar.md"),
+			article("title: عنوان\nsummary: ملخص.\npublishedAt: 2026-09-05", "عنوان"),
+		);
+
+		expect(compile).toThrow("missing article body blog/one/en.md");
+	});
+
+	test("resolves into a compiled article the contract accepts", () => {
+		write(
+			"one",
+			article("title: عنوان\nsummary: ملخص.\npublishedAt: 2026-09-05\nupdatedAt: 2026-09-06", "عنوان"),
+			article("title: Title\nsummary: Summary.", "Heading"),
+		);
+
+		const [compiled] = resolveArticleImages(compile().drafts, new Map());
+
+		expect(compiled?.id).toBe("one");
+		expect(compiled?.updatedAt).toBe("2026-09-06");
+		expect(compiled?.body.en).toHaveLength(2);
+	});
+});

package/src/blog/compile.ts

@@ -0,0 +1,172 @@
+import {
+	type GuideImageAsset,
+	markdownBodyReader,
+	type ParsedBlock,
+	type ResolvedGuideImage,
+	resolveGuideBlocks,
+} from "../guides";
+import type { LocalizedText } from "../manifest/localized";
+import { zSlug } from "../manifest/primitives";
+import type { PackageSource } from "../manifest/source";
+import {
+	type ArticleFrontmatter,
+	type ArticleTranslationFrontmatter,
+	parseArticleFrontmatter,
+	parseArticleTranslationFrontmatter,
+} from "./articleFrontmatter";
+import { type CompiledArticle, compiledArticleSchema } from "./compiled";
+
+export const BLOG_DIRECTORY = "blog";
+
+export const ARTICLE_SOURCE_MAX = 200;
+
+export interface DraftArticle {
+	id: string;
+	title: LocalizedText;
+	summary: LocalizedText;
+	publishedAt: string;
+	updatedAt: string | null;
+	tags: string[];
+	videoId: string | null;
+	body: {
+		ar: ParsedBlock[];
+		en: ParsedBlock[];
+	};
+}
+
+export interface ArticlePack {
+	drafts: DraftArticle[];
+	files: string[];
+	images: GuideImageAsset[];
+	commands: string[];
+}
+
+const ARTICLE_PATH_PATTERN = /^blog\/([^/]+)\/ar\.md$/;
+
+const articleIds = (source: PackageSource): string[] => {
+	const ids: string[] = [];
+
+	for (const path of source.list()) {
+		const match = ARTICLE_PATH_PATTERN.exec(path);
+
+		if (!match) {
+			continue;
+		}
+
+		const id = zSlug.safeParse(match[1]);
+
+		if (!id.success) {
+			throw new Error(`"${path}" is not a valid article folder — the folder name must be a slug`);
+		}
+
+		ids.push(id.data);
+	}
+
+	return ids.sort();
+};
+
+const readText = (source: PackageSource, path: string): string => {
+	const bytes = source.read(path);
+
+	if (!bytes) {
+		throw new Error(`missing article body ${path}`);
+	}
+
+	return new TextDecoder().decode(bytes);
+};
+
+const SHARED_KEYS = [
+	"publishedAt",
+	"updatedAt",
+	"video",
+] as const;
+
+const assertSharedFields = (path: string, article: ArticleFrontmatter, translation: ArticleTranslationFrontmatter) => {
+	for (const key of SHARED_KEYS) {
+		if (translation[key] !== undefined && translation[key] !== article[key]) {
+			throw new Error(
+				`${path} frontmatter "${key}" is "${translation[key]}" but ar.md declares "${article[key] ?? "nothing"}" — a language-independent field must match`,
+			);
+		}
+	}
+
+	if (translation.tags !== undefined && translation.tags.join(",") !== article.tags.join(",")) {
+		throw new Error(
+			`${path} frontmatter "tags" is [${translation.tags.join(", ")}] but ar.md declares [${article.tags.join(", ")}] — a language-independent field must match`,
+		);
+	}
+};
+
+export const compileArticles = (source: PackageSource): ArticlePack => {
+	const ids = articleIds(source);
+
+	if (ids.length > ARTICLE_SOURCE_MAX) {
+		throw new Error(
+			`${ids.length} articles found under ${BLOG_DIRECTORY}/ — at most ${ARTICLE_SOURCE_MAX} are allowed`,
+		);
+	}
+
+	const reader = markdownBodyReader(source);
+	const drafts: DraftArticle[] = [];
+
+	for (const id of ids) {
+		const arPath = `${BLOG_DIRECTORY}/${id}/ar.md`;
+		const enPath = `${BLOG_DIRECTORY}/${id}/en.md`;
+
+		const ar = parseArticleFrontmatter(arPath, readText(source, arPath));
+		const en = parseArticleTranslationFrontmatter(enPath, readText(source, enPath));
+
+		assertSharedFields(enPath, ar.front, en.front);
+
+		drafts.push({
+			id,
+			title: {
+				ar: ar.front.title,
+				en: en.front.title,
+			},
+			summary: {
+				ar: ar.front.summary,
+				en: en.front.summary,
+			},
+			publishedAt: ar.front.publishedAt,
+			updatedAt: ar.front.updatedAt ?? null,
+			tags: ar.front.tags,
+			videoId: ar.front.video ?? null,
+			body: {
+				ar: reader.read(arPath, ar.body),
+				en: reader.read(enPath, en.body),
+			},
+		});
+	}
+
+	drafts.sort((left, right) => {
+		return right.publishedAt.localeCompare(left.publishedAt) || left.id.localeCompare(right.id);
+	});
+
+	return {
+		drafts,
+		files: [
+			...reader.files,
+			...reader.images.keys(),
+		],
+		images: [
+			...reader.images.values(),
+		],
+		commands: reader.commands,
+	};
+};
+
+export const resolveArticleImages = (
+	drafts: DraftArticle[],
+	resolved: Map<string, ResolvedGuideImage>,
+): CompiledArticle[] => {
+	return drafts.map((draft) => {
+		return compiledArticleSchema.parse({
+			...draft,
+			body: {
+				ar: resolveGuideBlocks(draft.body.ar, resolved),
+				en: resolveGuideBlocks(draft.body.en, resolved),
+			},
+		});
+	});
+};

package/src/blog/compiled.ts

@@ -0,0 +1,22 @@
+import { z } from "zod";
+import { GUIDE_BODY_MAX_BLOCKS, guideBlockSchema } from "../guides";
+import { zGuideTag, zYoutubeId } from "../manifest/guide";
+import { localizedTextSchema } from "../manifest/localized";
+import { zSlug } from "../manifest/primitives";
+import { ARTICLE_TAGS_MAX } from "./articleFrontmatter";
+
+export const compiledArticleSchema = z.object({
+	id: zSlug,
+	title: localizedTextSchema,
+	summary: localizedTextSchema,
+	publishedAt: z.iso.date(),
+	updatedAt: z.iso.date().nullable(),
+	tags: z.array(zGuideTag).max(ARTICLE_TAGS_MAX).default([]),
+	videoId: zYoutubeId.nullable(),
+	body: z.object({
+		ar: z.array(guideBlockSchema).min(1).max(GUIDE_BODY_MAX_BLOCKS),
+		en: z.array(guideBlockSchema).min(1).max(GUIDE_BODY_MAX_BLOCKS),
+	}),
+});
+
+export type CompiledArticle = z.infer<typeof compiledArticleSchema>;

package/src/blog/index.ts

@@ -0,0 +1,3 @@
+export * from "./articleFrontmatter";
+export * from "./compile";
+export * from "./compiled";

package/src/cli/validate.test.ts

@@ -2,7 +2,15 @@ import { afterEach, beforeEach, describe, expect, test } from "bun:test";
 import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
-import { runValidate } from "./validate";
+import { BridgeKind, BridgeSetupStepKind } from "../core";
+import { GuideOpenTab } from "../guides";
+import type { BridgeSetupModule } from "../modules";
+import { runValidate, setupReportLines } from "./validate";
+
+const text = (value: string) => ({
+	ar: value,
+	en: value,
+});
 
 describe("validate", () => {
 	let root = "";
@@ -87,3 +95,110 @@ describe("validate", () => {
 		await expect(validate()).rejects.toThrow("missing serverk.yml");
 	});
 });
+
+describe("the setup report", () => {
+	test("says none for a driver that declares no setup", () => {
+		expect(setupReportLines(undefined)).toEqual([
+			"  setup: none",
+		]);
+	});
+
+	test("names every step, its kind, whether it is required, and where it lands", () => {
+		const setup: BridgeSetupModule = {
+			kind: BridgeKind.Setup,
+			steps: [
+				{
+					kind: BridgeSetupStepKind.Form,
+					id: "license",
+					title: text("Licence"),
+					required: true,
+					tab: "license",
+					section: "license",
+					fields: [
+						"LICENSE_KEY",
+					],
+				},
+				{
+					kind: BridgeSetupStepKind.Driver,
+					id: "verify",
+					title: text("Verify"),
+					required: true,
+					requiresRunning: true,
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "txadmin",
+					title: text("txAdmin"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Panel,
+						tabId: "license",
+					},
+				},
+				{
+					kind: BridgeSetupStepKind.Open,
+					id: "invite",
+					title: text("Invite"),
+					required: false,
+					target: {
+						tab: GuideOpenTab.Access,
+					},
+				},
+			],
+			submit: async () => {
+				return;
+			},
+		};
+
+		expect(setupReportLines(setup)).toEqual([
+			"  setup: 4 step(s)",
+			"    license — form, required → license/license [LICENSE_KEY]",
+			"    verify — driver, required → driver (needs the game running)",
+			'    txadmin — open, optional → panel tab "license"',
+			"    invite — open, optional → access",
+		]);
+	});
+
+	test("leaves a driver step that needs nothing running with no target", () => {
+		expect(
+			setupReportLines({
+				kind: BridgeKind.Setup,
+				steps: [
+					{
+						kind: BridgeSetupStepKind.Driver,
+						id: "sign-in",
+						title: text("Sign in"),
+						required: false,
+					},
+				],
+				submit: async () => {
+					return;
+				},
+			}),
+		).toEqual([
+			"  setup: 1 step(s)",
+			"    sign-in — driver, optional → driver",
+		]);
+	});
+
+	test("reads an omitted required as required, the way the platform does", () => {
+		expect(
+			setupReportLines({
+				kind: BridgeKind.Setup,
+				steps: [
+					{
+						kind: BridgeSetupStepKind.Driver,
+						id: "sign-in",
+						title: text("Sign in"),
+					},
+				],
+				submit: async () => {
+					return;
+				},
+			}),
+		).toEqual([
+			"  setup: 1 step(s)",
+			"    sign-in — driver, required → driver",
+		]);
+	});
+});