@serverkgg/bridge 0.0.10 → 0.0.12

package/src/cli/validate.ts

@@ -3,7 +3,8 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { z } from "zod";
-import { type GuidePack, readGuidePack, readGuidePackage } from "../guides";
+import { type ArticlePack, compileArticles } from "../blog";
+import { GuideOpenTab, type GuideOpenTarget, type GuidePack, readGuidePack, readGuidePackage } from "../guides";
 import {
 	declaredFiles,
 	type GuidePackage,
@@ -13,8 +14,8 @@ import {
 	readAssets,
 	readPackageDocument,
 } from "../manifest";
-import type { BridgeDriver } from "../modules";
-import { isBridgeEventName } from "../protocol";
+import type { BridgeDriver, BridgeSetupModule } from "../modules";
+import { type BridgeSetupStep, BridgeSetupStepKind, isBridgeEventName } from "../protocol";
 import { validateDriver, validatePortActivation } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
 
@@ -131,6 +132,10 @@ const reportGuides = (pack: GuidePack | null) => {
 	}
 };
 
+const reportArticles = (pack: ArticlePack) => {
+	console.log(`  articles: ${pack.drafts.length} article(s), ${pack.images.length} image(s)`);
+};
+
 const validateGuidePackage = (source: PackageSource, document: GuidePackage) => {
 	const guideFiles = document.guides.flatMap((guide) => [
 		guide.bodyPath.ar,
@@ -144,9 +149,11 @@ const validateGuidePackage = (source: PackageSource, document: GuidePackage) =>
 	}
 
 	const pack = readGuidePackage(source, document);
+	const articles = compileArticles(source);
 
 	console.log(`${document.metadata.id} is valid`);
 	reportGuides(pack);
+	reportArticles(articles);
 };
 
 const ACTION_TARGET_BUDGET = 80;
@@ -186,6 +193,49 @@ const reportActionTargets = (driver: BridgeDriver) => {
 	}
 };
 
+const openTargetOf = (target: GuideOpenTarget) => {
+	if (target.tab === GuideOpenTab.Panel) {
+		return `panel tab "${target.tabId}"`;
+	}
+
+	if (target.tab === GuideOpenTab.Files) {
+		return target.path ? `files at "${target.path}"` : "files";
+	}
+
+	return target.tab;
+};
+
+const setupTargetOf = (step: BridgeSetupStep) => {
+	if (step.kind === BridgeSetupStepKind.Form) {
+		const fields = step.fields ?? [];
+
+		return `→ ${step.tab}/${step.section}${fields.length === 0 ? "" : ` [${fields.join(", ")}]`}`;
+	}
+
+	if (step.kind === BridgeSetupStepKind.Open) {
+		return `→ ${openTargetOf(step.target)}`;
+	}
+
+	return step.requiresRunning ? "→ driver (needs the game running)" : "→ driver";
+};
+
+export const setupReportLines = (setup: BridgeSetupModule | undefined): string[] => {
+	if (!setup) {
+		return [
+			"  setup: none",
+		];
+	}
+
+	return [
+		`  setup: ${setup.steps.length} step(s)`,
+		...setup.steps.map((step) => {
+			const target = setupTargetOf(step);
+
+			return `    ${step.id} — ${step.kind}, ${step.required === false ? "optional" : "required"}${target === "" ? "" : ` ${target}`}`;
+		}),
+	];
+};
+
 const validateGamePackage = async (source: PackageSource, manifest: Manifest, dir: string, driverArg?: string) => {
 	const assets = readAssets(source, manifest);
 	const guideFiles = manifest.guides.flatMap((guide) => [
@@ -230,7 +280,10 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 		`  driver: ${Object.keys(driver.modules ?? {}).length} panel module(s), ${driver.panel?.tabs.length ?? 0} tab(s)`,
 	);
 	console.log(`  pending: ${driver.pending ? `declared (${driver.pending.extensions.length} extension(s))` : "none"}`);
-	console.log(`  setup: ${driver.setup ? `${driver.setup.steps.length} step(s)` : "none"}`);
+	for (const line of setupReportLines(driver.setup)) {
+		console.log(line);
+	}
+
 	reportEvents(driver);
 	reportActionTargets(driver);
 };

package/src/context/bridgeContext.ts

@@ -91,8 +91,28 @@ export interface BridgeA2sInfo {
 	latencyMs: number;
 }
 
+export interface BridgeMinecraftPingStatus {
+	players: BridgePingPlayers;
+	version: string | null;
+	description: string | null;
+	latencyMs: number;
+}
+
+export interface BridgeRaknetPingStatus {
+	players: BridgePingPlayers;
+	edition: string | null;
+	motd: string | null;
+	subMotd: string | null;
+	version: string | null;
+	protocol: number | null;
+	gamemode: string | null;
+	latencyMs: number;
+}
+
 export interface BridgeProbes {
 	a2s(port: number): Promise<BridgeA2sInfo>;
+	minecraftPing(port: number): Promise<BridgeMinecraftPingStatus>;
+	raknetPing(port: number): Promise<BridgeRaknetPingStatus>;
 }
 
 export interface BridgeCommandOptions {

package/src/guides/compile.ts

@@ -52,49 +52,65 @@ const compileTags = (guideTags: GuideTag[], tags: string[]): CompiledGuideTag[]
 	});
 };
 
-export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entries: GuideEntry[]): GuidePack => {
-	const drafts: DraftGuide[] = [];
+export interface MarkdownBodyReader {
+	files: string[];
+	commands: string[];
+	images: Map<string, GuideImageAsset>;
+	read(path: string, text?: string): ParsedBlock[];
+}
+
+export const markdownBodyReader = (source: PackageSource): MarkdownBodyReader => {
 	const files: string[] = [];
 	const commands: string[] = [];
-	const imageByPath = new Map<string, GuideImageAsset>();
+	const images = new Map<string, GuideImageAsset>();
 
-	const readBody = (path: string) => {
-		const body = source.read(path);
+	return {
+		files,
+		commands,
+		images,
+		read(path, text) {
+			const body = source.read(path);
 
-		if (!body) {
-			throw new Error(`missing guide body ${path}`);
-		}
+			if (!body) {
+				throw new Error(`missing markdown body ${path}`);
+			}
 
-		files.push(path);
+			files.push(path);
 
-		const parsed = parseGuideMarkdown(path, new TextDecoder().decode(body));
+			const parsed = parseGuideMarkdown(path, text ?? new TextDecoder().decode(body));
 
-		commands.push(...parsed.commands);
+			commands.push(...parsed.commands);
 
-		for (const imagePath of parsed.images) {
-			if (imageByPath.has(imagePath)) {
-				continue;
-			}
+			for (const imagePath of parsed.images) {
+				if (images.has(imagePath)) {
+					continue;
+				}
 
-			const imageBytes = source.read(imagePath);
+				const imageBytes = source.read(imagePath);
 
-			if (!imageBytes) {
-				throw new Error(`missing guide image ${imagePath}`);
-			}
+				if (!imageBytes) {
+					throw new Error(`missing guide image ${imagePath}`);
+				}
 
-			const verified = verifyAsset(imagePath, imageBytes);
+				const verified = verifyAsset(imagePath, imageBytes);
 
-			imageByPath.set(imagePath, {
-				path: imagePath,
-				bytes: imageBytes,
-				mediaType: verified.mediaType,
-				width: verified.dimensions?.width ?? null,
-				height: verified.dimensions?.height ?? null,
-			});
-		}
+				images.set(imagePath, {
+					path: imagePath,
+					bytes: imageBytes,
+					mediaType: verified.mediaType,
+					width: verified.dimensions?.width ?? null,
+					height: verified.dimensions?.height ?? null,
+				});
+			}
 
-		return parsed.blocks;
+			return parsed.blocks;
+		},
 	};
+};
+
+export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entries: GuideEntry[]): GuidePack => {
+	const drafts: DraftGuide[] = [];
+	const reader = markdownBodyReader(source);
 
 	for (const entry of entries) {
 		drafts.push({
@@ -105,8 +121,8 @@ export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entr
 			surfaces: entry.surfaces,
 			videoId: entry.video ?? null,
 			body: {
-				ar: readBody(entry.bodyPath.ar),
-				en: readBody(entry.bodyPath.en),
+				ar: reader.read(entry.bodyPath.ar),
+				en: reader.read(entry.bodyPath.en),
 			},
 		});
 	}
@@ -114,13 +130,13 @@ export const compileGuides = (source: PackageSource, guideTags: GuideTag[], entr
 	return {
 		drafts,
 		files: [
-			...files,
-			...imageByPath.keys(),
+			...reader.files,
+			...reader.images.keys(),
 		],
 		images: [
-			...imageByPath.values(),
+			...reader.images.values(),
 		],
-		commands,
+		commands: reader.commands,
 	};
 };
 
@@ -142,10 +158,7 @@ export interface ResolvedGuideImage {
 	height: number | null;
 }
 
-export const resolveGuideImages = (
-	drafts: DraftGuide[],
-	resolved: Map<string, ResolvedGuideImage>,
-): CompiledGuide[] => {
+export const resolveGuideBlocks = (blocks: ParsedBlock[], resolved: Map<string, ResolvedGuideImage>): GuideBlock[] => {
 	const resolveLeaf = (block: ParsedLeafBlock): GuideLeafBlock => {
 		if (block.type !== "image") {
 			return block;
@@ -166,27 +179,30 @@ export const resolveGuideImages = (
 		};
 	};
 
-	const resolveBlocks = (blocks: ParsedBlock[]): GuideBlock[] => {
-		return blocks.map((block) => {
-			if (block.type !== "conditional") {
-				return resolveLeaf(block);
-			}
+	return blocks.map((block) => {
+		if (block.type !== "conditional") {
+			return resolveLeaf(block);
+		}
 
-			return {
-				type: "conditional",
-				key: block.key,
-				when: block.when.map(resolveLeaf),
-				otherwise: block.otherwise.map(resolveLeaf),
-			};
-		});
-	};
+		return {
+			type: "conditional",
+			key: block.key,
+			when: block.when.map(resolveLeaf),
+			otherwise: block.otherwise.map(resolveLeaf),
+		};
+	});
+};
 
+export const resolveGuideImages = (
+	drafts: DraftGuide[],
+	resolved: Map<string, ResolvedGuideImage>,
+): CompiledGuide[] => {
 	return drafts.map((draft) => {
 		return compiledGuideSchema.parse({
 			...draft,
 			body: {
-				ar: resolveBlocks(draft.body.ar),
-				en: resolveBlocks(draft.body.en),
+				ar: resolveGuideBlocks(draft.body.ar, resolved),
+				en: resolveGuideBlocks(draft.body.en, resolved),
 			},
 		});
 	});

package/src/manifest/guide.ts

@@ -16,6 +16,7 @@ export enum GuideSurface {
 	Files = "files",
 	Backups = "backups",
 	Panel = "panel",
+	Setup = "setup",
 }
 
 export const guideTagSchema = z.object({

package/src/manifest/manifest.test.ts

@@ -10,6 +10,26 @@ const text = (value: string) => ({
 	en: value,
 });
 
+const guide = (id: string, extra: Record<string, unknown> = {}) => ({
+	id,
+	title: text(id),
+	summary: text(id),
+	bodyPath: {
+		ar: `guides/${id}/ar.md`,
+		en: `guides/${id}/en.md`,
+	},
+	...extra,
+});
+
+const guidePackage = (guides: unknown[]) => ({
+	schemaVersion: MANIFEST_SCHEMA_VERSION,
+	kind: "GuidePackage",
+	metadata: {
+		id: "platform",
+	},
+	guides,
+});
+
 const base = () => ({
 	schemaVersion: MANIFEST_SCHEMA_VERSION,
 	kind: "GamePackage",
@@ -586,6 +606,19 @@ describe("packageSchema", () => {
 		expect(result.success).toBe(false);
 		expect(result.error && z.prettifyError(result.error)).toContain('tag "start" is not declared in guideTags');
 	});
+
+	test("carries up to 64 guides", () => {
+		const many = (count: number) =>
+			Array.from(
+				{
+					length: count,
+				},
+				(_, index) => guide(`guide-${index}`),
+			);
+
+		expect(guidePackageSchema.safeParse(guidePackage(many(64))).success).toBe(true);
+		expect(guidePackageSchema.safeParse(guidePackage(many(65))).success).toBe(false);
+	});
 });
 
 describe("presence", () => {

package/src/panel/bridgeControl.ts

@@ -1,6 +1,7 @@
 export enum BridgeControl {
 	Boolean = "boolean",
 	Number = "number",
+	Secret = "secret",
 	Select = "select",
 	Slider = "slider",
 	Text = "text",

package/src/panel/bridgeDetail.ts

@@ -11,6 +11,7 @@ export enum BridgeDetailFormat {
 	Bytes = "bytes",
 	Date = "date",
 	Number = "number",
+	Secret = "secret",
 	Text = "text",
 }
 

package/src/panel/bridgePanel.ts

@@ -32,6 +32,8 @@ export interface BridgeField {
 	max?: number;
 	step?: number;
 	maxLength?: number;
+	pattern?: string;
+	patternHint?: LocalizedText;
 	options?: BridgeOption[] | BridgeOptionsRef;
 	visibleWhen?: BridgeVisibleWhen;
 }

package/src/probes/index.ts

@@ -1 +1,10 @@
+export type {
+	BridgeA2sInfo,
+	BridgeMinecraftPingStatus,
+	BridgePingPlayers,
+	BridgeRaknetPingStatus,
+} from "../context";
+export { BridgeProbeCode, BridgeProbeError } from "../core";
 export * from "./a2s";
+export * from "./minecraftPing";
+export * from "./raknetPing";