@serverkgg/bridge 0.0.1 → 0.0.3

package/src/cli/validate.test.ts

@@ -0,0 +1,89 @@
+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";
+
+describe("validate", () => {
+	let root = "";
+
+	const writePackage = (dependencies: Record<string, string>) => {
+		writeFileSync(
+			join(root, "package.json"),
+			JSON.stringify({
+				name: "@serverkgg/minecraft",
+				dependencies,
+			}),
+		);
+	};
+
+	const validate = () => {
+		return runValidate([
+			"--dir",
+			root,
+		]);
+	};
+
+	beforeEach(() => {
+		root = mkdtempSync(`${tmpdir()}/serverk-validate-`);
+	});
+
+	afterEach(() => {
+		rmSync(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("refuses a file: bridge dependency", async () => {
+		writePackage({
+			"@serverkgg/bridge": "file:../serverk/modules/bridge",
+		});
+
+		await expect(validate()).rejects.toThrow(
+			'package.json depends on @serverkgg/bridge via "file:../serverk/modules/bridge"',
+		);
+	});
+
+	test("refuses a link: bridge dependency", async () => {
+		writePackage({
+			"@serverkgg/bridge": "link:@serverkgg/bridge",
+		});
+
+		await expect(validate()).rejects.toThrow('depends on @serverkgg/bridge via "link:@serverkgg/bridge"');
+	});
+
+	test("refuses a file: bridge devDependency", async () => {
+		writeFileSync(
+			join(root, "package.json"),
+			JSON.stringify({
+				name: "@serverkgg/platform",
+				devDependencies: {
+					"@serverkgg/bridge": "file:../serverk/modules/bridge",
+				},
+			}),
+		);
+
+		await expect(validate()).rejects.toThrow("pin a published version");
+	});
+
+	test("accepts a published bridge dependency and moves on to the manifest", async () => {
+		writePackage({
+			"@serverkgg/bridge": "0.0.3",
+		});
+
+		await expect(validate()).rejects.toThrow("missing serverk.yml");
+	});
+
+	test("ignores a package without a bridge dependency", async () => {
+		writePackage({
+			zod: "4.4.3",
+		});
+
+		await expect(validate()).rejects.toThrow("missing serverk.yml");
+	});
+
+	test("ignores a package.json that is absent", async () => {
+		await expect(validate()).rejects.toThrow("missing serverk.yml");
+	});
+});

package/src/cli/validate.ts

@@ -3,61 +3,194 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { z } from "zod";
-import { declaredFiles, type Manifest, readAssets, readPackage } from "../manifest";
+import { type GuidePack, readGuidePack, readGuidePackage } from "../guides";
+import {
+	declaredFiles,
+	type GuidePackage,
+	MANIFEST_FILE,
+	type Manifest,
+	type PackageSource,
+	readAssets,
+	readPackageDocument,
+} from "../manifest";
 import type { BridgeDriver } from "../modules";
+import { isBridgeEventName } from "../protocol";
 import { validateDriver } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
 
 const HELP = `serverk-bridge validate [options]
 
 options:
-  --dir <path>      game package directory (default: current directory)
-  --driver <path>   driver module (default: <dir>/src/driver.ts)
+  --dir <path>      package directory (default: current directory)
+  --driver <path>   driver module (default: <dir>/src/driver.ts), game packages only
   --help            show this help`;
 
-export const runValidate = async (args: string[]) => {
-	const { values } = parseArgs({
-		args,
-		options: {
-			dir: {
-				type: "string",
-				default: ".",
-			},
-			driver: {
-				type: "string",
-			},
-			help: {
-				type: "boolean",
-				default: false,
-			},
-		},
-	});
+const BRIDGE_PACKAGE = "@serverkgg/bridge";
 
-	if (values.help) {
-		console.log(HELP);
+const LOCAL_SPECS = [
+	"file:",
+	"link:",
+];
+
+const localBridgeSpec = (source: PackageSource) => {
+	const bytes = source.read("package.json");
+
+	if (!bytes) {
+		return null;
+	}
+
+	let parsed: unknown;
+
+	try {
+		parsed = JSON.parse(new TextDecoder().decode(bytes));
+	} catch {
+		return null;
+	}
+
+	if (typeof parsed !== "object" || parsed === null) {
+		return null;
+	}
+
+	const groups: unknown[] = [
+		"dependencies" in parsed ? parsed.dependencies : null,
+		"devDependencies" in parsed ? parsed.devDependencies : null,
+	];
+
+	for (const group of groups) {
+		if (typeof group !== "object" || group === null || !(BRIDGE_PACKAGE in group)) {
+			continue;
+		}
 
+		const spec: unknown = group[BRIDGE_PACKAGE];
+
+		if (typeof spec === "string" && LOCAL_SPECS.some((prefix) => spec.startsWith(prefix))) {
+			return spec;
+		}
+	}
+
+	return null;
+};
+
+const assertRegistryBridge = (source: PackageSource) => {
+	const spec = localBridgeSpec(source);
+
+	if (!spec) {
 		return;
 	}
 
-	const dir = resolve(values.dir);
-	const source = directorySource(dir);
+	throw new Error(
+		`package.json depends on ${BRIDGE_PACKAGE} via "${spec}" — pin a published version and use "serverk-bridge link" for local development`,
+	);
+};
+
+const invalidManifest = (error: unknown): never => {
+	if (error instanceof z.ZodError) {
+		throw new Error(`${MANIFEST_FILE} is invalid\n${z.prettifyError(error)}`);
+	}
 
-	let manifest: Manifest;
+	throw error;
+};
 
-	try {
-		manifest = readPackage(source).manifest;
-	} catch (error) {
-		if (error instanceof z.ZodError) {
-			throw new Error(`serverk.yml is invalid\n${z.prettifyError(error)}`);
+const DYNAMIC_BLOCKS: ReadonlySet<string> = new Set([
+	"field",
+	"command",
+	"open",
+	"conditional",
+]);
+
+const countDynamic = (pack: GuidePack) => {
+	return pack.drafts.reduce((total, draft) => {
+		const blocks = [
+			...draft.body.ar,
+			...draft.body.en,
+		];
+
+		return total + blocks.filter((block) => DYNAMIC_BLOCKS.has(block.type)).length;
+	}, 0);
+};
+
+const reportGuides = (pack: GuidePack | null) => {
+	if (!pack) {
+		return;
+	}
+
+	console.log(
+		`  guides: ${pack.drafts.length} guide(s), ${countDynamic(pack)} dynamic block(s), ${pack.images.length} image(s)`,
+	);
+
+	if (pack.commands.length === 0) {
+		return;
+	}
+
+	console.log(`  commands: ${pack.commands.length} runnable command(s) — review each one`);
+
+	for (const command of [
+		...new Set(pack.commands),
+	]) {
+		console.log(`    ${command}`);
+	}
+};
+
+const validateGuidePackage = (source: PackageSource, document: GuidePackage) => {
+	const guideFiles = document.guides.flatMap((guide) => [
+		guide.bodyPath.ar,
+		guide.bodyPath.en,
+	]);
+
+	for (const path of guideFiles) {
+		if (source.read(path) === null) {
+			throw new Error(`declared file "${path}" is missing`);
 		}
+	}
+
+	const pack = readGuidePackage(source, document);
 
-		throw error;
+	console.log(`${document.metadata.id} is valid`);
+	reportGuides(pack);
+};
+
+const ACTION_TARGET_BUDGET = 80;
+
+const reportEvents = (driver: BridgeDriver) => {
+	const unknown = [
+		...new Set([
+			...(driver.events?.patterns ?? []).map((pattern) => pattern.emit),
+			...(driver.events?.emits ?? []),
+		]),
+	].filter((name) => !isBridgeEventName(name));
+
+	if (unknown.length === 0) {
+		return;
 	}
 
+	console.log(
+		`  warning: ${unknown.join(", ")} — outside the platform event taxonomy, the platform drops what it does not know`,
+	);
+};
+
+const reportActionTargets = (driver: BridgeDriver) => {
+	for (const tab of driver.panel?.tabs ?? []) {
+		for (const section of tab.sections) {
+			const actions = "actions" in section ? (section.actions ?? []) : [];
+
+			for (const action of actions) {
+				const target = `${tab.id}.${section.id}:${action.id}`;
+
+				if (target.length > ACTION_TARGET_BUDGET) {
+					console.log(
+						`  warning: "${target}" is ${target.length} characters — keep it under ${ACTION_TARGET_BUDGET} so it fits a discord custom id`,
+					);
+				}
+			}
+		}
+	}
+};
+
+const validateGamePackage = async (source: PackageSource, manifest: Manifest, dir: string, driverArg?: string) => {
 	const assets = readAssets(source, manifest);
 	const guideFiles = manifest.guides.flatMap((guide) => [
-		guide.body.ar,
-		guide.body.en,
+		guide.bodyPath.ar,
+		guide.bodyPath.en,
 	]);
 
 	for (const path of declaredFiles(manifest, guideFiles)) {
@@ -66,7 +199,8 @@ export const runValidate = async (args: string[]) => {
 		}
 	}
 
-	const driverPath = values.driver ? resolve(values.driver) : join(dir, "src/driver.ts");
+	const pack = readGuidePack(source, manifest);
+	const driverPath = driverArg ? resolve(driverArg) : join(dir, "src/driver.ts");
 
 	if (!existsSync(driverPath)) {
 		throw new Error(`no driver module at ${driverPath} — export your BridgeDriver from src/driver.ts`);
@@ -83,12 +217,61 @@ export const runValidate = async (args: string[]) => {
 
 	console.log(`${manifest.metadata.id} is valid`);
 	console.log(
-		`  manifest: ${manifest.runtime.ports.length} port(s), ${manifest.secrets.length} secret(s), ${manifest.guides.length} guide(s)`,
+		`  manifest: ${manifest.container.ports.length} port(s), ${manifest.secrets.length} secret(s), ${manifest.guides.length} guide(s)`,
 	);
 	console.log(
 		`  assets: logo ${assets.logo.dimensions.width}x${assets.logo.dimensions.height}, banner ${assets.banner.dimensions.width}x${assets.banner.dimensions.height}`,
 	);
+	reportGuides(pack);
 	console.log(
 		`  driver: ${Object.keys(driver.modules ?? {}).length} panel module(s), ${driver.panel?.tabs.length ?? 0} tab(s)`,
 	);
+	reportEvents(driver);
+	reportActionTargets(driver);
+};
+
+export const runValidate = async (args: string[]) => {
+	const { values } = parseArgs({
+		args,
+		options: {
+			dir: {
+				type: "string",
+				default: ".",
+			},
+			driver: {
+				type: "string",
+			},
+			help: {
+				type: "boolean",
+				default: false,
+			},
+		},
+	});
+
+	if (values.help) {
+		console.log(HELP);
+
+		return;
+	}
+
+	const dir = resolve(values.dir);
+	const source = directorySource(dir);
+
+	assertRegistryBridge(source);
+
+	let document: Manifest | GuidePackage;
+
+	try {
+		document = readPackageDocument(source);
+	} catch (error) {
+		return invalidManifest(error);
+	}
+
+	if (document.kind === "GuidePackage") {
+		validateGuidePackage(source, document);
+
+		return;
+	}
+
+	await validateGamePackage(source, document, dir, values.driver);
 };

package/src/context/bridgeContext.ts

@@ -18,6 +18,13 @@ export interface BridgeFileEntry {
 export interface BridgeDownloadOptions {
 	digest?: string;
 	sizeBytes?: number;
+	cache?: boolean;
+}
+
+export interface BridgeExtractOptions {
+	extensions?: string[];
+	tree?: boolean;
+	select?: string;
 }
 
 export interface BridgeFiles {
@@ -30,7 +37,7 @@ export interface BridgeFiles {
 	exists(path: string): Promise<boolean>;
 	size(path: string): Promise<number>;
 	download(path: string, url: string, options?: BridgeDownloadOptions): Promise<void>;
-	extract(path: string, destination: string, extensions?: string[]): Promise<string[]>;
+	extract(path: string, destination: string, options?: BridgeExtractOptions): Promise<string[]>;
 }
 
 export interface BridgeCodecOptions {
@@ -52,6 +59,9 @@ export interface BridgeCodecs {
 export interface BridgeRequestOptions {
 	headers?: Record<string, string>;
 	timeoutMs?: number;
+	cache?: boolean;
+	cacheSeconds?: number;
+	refresh?: boolean;
 }
 
 export interface BridgeNet {
@@ -103,6 +113,12 @@ export interface BridgeLogs {
 	watch(pattern: RegExp, timeoutMs: number): Promise<RegExpMatchArray | null>;
 }
 
+export interface BridgeLog {
+	(message: string, fields?: BridgeValues): void;
+	warn(message: string, fields?: BridgeValues): void;
+	error(message: string, fields?: BridgeValues): void;
+}
+
 export interface BridgeContext {
 	readonly server: BridgeServer;
 	variable(key: string): string | null;
@@ -116,5 +132,5 @@ export interface BridgeContext {
 	exec(command: string[], options?: BridgeExecOptions): Promise<BridgeExecResult>;
 	logs: BridgeLogs;
 	emit(event: string, payload?: BridgeValues): void;
-	log(message: string, fields?: BridgeValues): void;
+	log: BridgeLog;
 }

package/src/core/bridgeAction.ts

@@ -9,5 +9,18 @@ export enum BridgeAction {
 	Remove = "remove",
 	Sample = "sample",
 	Search = "search",
+	Toggle = "toggle",
 	Write = "write",
 }
+
+export const BRIDGE_READ_ACTIONS: readonly string[] = [
+	BridgeAction.Installed,
+	BridgeAction.List,
+	BridgeAction.Read,
+	BridgeAction.Sample,
+	BridgeAction.Search,
+];
+
+export const isReadAction = (action: string): boolean => {
+	return BRIDGE_READ_ACTIONS.includes(action);
+};

package/src/core/bridgeFailure.ts

@@ -0,0 +1,16 @@
+export enum BridgeFailureCode {
+	CatalogRateLimited = "catalog-rate-limited",
+	CatalogRestricted = "catalog-restricted",
+	NoCatalogVersionAvailable = "no-catalog-version-available",
+}
+
+export class BridgeFailureError extends Error {
+	readonly code: BridgeFailureCode;
+
+	constructor(code: BridgeFailureCode, message: string) {
+		super(message);
+
+		this.name = "BridgeFailureError";
+		this.code = code;
+	}
+}

package/src/core/bridgeKind.ts

@@ -1,7 +1,10 @@
 export enum BridgeKind {
+	Actions = "actions",
+	Announce = "announce",
 	Backup = "backup",
 	Catalog = "catalog",
 	Collection = "collection",
+	Terminal = "terminal",
 	Events = "events",
 	Install = "install",
 	Lifecycle = "lifecycle",

package/src/core/bridgeNetError.ts

@@ -0,0 +1,10 @@
+export class BridgeNetError extends Error {
+	readonly status: number | null;
+
+	constructor(status: number | null, message: string) {
+		super(message);
+
+		this.name = "BridgeNetError";
+		this.status = status;
+	}
+}

package/src/core/index.ts

@@ -1,6 +1,8 @@
 export * from "./bridgeAction";
+export * from "./bridgeFailure";
 export * from "./bridgeId";
 export * from "./bridgeKind";
+export * from "./bridgeNetError";
 export * from "./bridgePort";
 export * from "./bridgeRuntime";
 export * from "./bridgeSecretError";

package/src/guides/blocks.ts

@@ -0,0 +1,167 @@
+import { z } from "zod";
+import { zYoutubeId } from "../manifest/guide";
+import { zGuideVariableRef } from "./variables";
+
+export enum GuideCalloutTone {
+	Note = "note",
+	Warning = "warning",
+	Danger = "danger",
+}
+
+export enum GuideOpenTab {
+	Overview = "overview",
+	Console = "console",
+	Files = "files",
+	Backups = "backups",
+	Panel = "panel",
+}
+
+export const zGuideFilePath = z
+	.string()
+	.min(1)
+	.max(256)
+	.regex(/^[a-zA-Z0-9][a-zA-Z0-9./_-]*$/)
+	.refine((value) => !value.includes(".."), {
+		error: "file path must not traverse upwards",
+	});
+
+export const zGuidePanelTabId = z
+	.string()
+	.min(1)
+	.max(32)
+	.regex(/^[a-z][a-z0-9-]*$/);
+
+export const GUIDE_COMMAND_MAX_LENGTH = 512;
+
+export const zGuideCommand = z
+	.string()
+	.min(1)
+	.max(GUIDE_COMMAND_MAX_LENGTH)
+	.regex(/^[^\p{Cc}]+$/u, {
+		error: "a command must be a single line without control characters",
+	});
+
+export const guideOpenTargetSchema = z.discriminatedUnion("tab", [
+	z.object({
+		tab: z.literal(GuideOpenTab.Overview),
+	}),
+	z.object({
+		tab: z.literal(GuideOpenTab.Console),
+	}),
+	z.object({
+		tab: z.literal(GuideOpenTab.Backups),
+	}),
+	z.object({
+		tab: z.literal(GuideOpenTab.Files),
+		path: zGuideFilePath.nullable(),
+	}),
+	z.object({
+		tab: z.literal(GuideOpenTab.Panel),
+		tabId: zGuidePanelTabId,
+	}),
+]);
+
+export type GuideOpenTarget = z.infer<typeof guideOpenTargetSchema>;
+
+export const guideInlineSchema = z.discriminatedUnion("type", [
+	z.object({
+		type: z.literal("text"),
+		text: z.string().min(1).max(2048),
+	}),
+	z.object({
+		type: z.literal("bold"),
+		text: z.string().min(1).max(512),
+	}),
+	z.object({
+		type: z.literal("italic"),
+		text: z.string().min(1).max(512),
+	}),
+	z.object({
+		type: z.literal("code"),
+		text: z.string().min(1).max(512),
+	}),
+	z.object({
+		type: z.literal("link"),
+		href: z
+			.string()
+			.max(2048)
+			.regex(/^(https:\/\/|\/)/),
+		text: z.string().min(1).max(512),
+	}),
+	z.object({
+		type: z.literal("variable"),
+		key: zGuideVariableRef,
+	}),
+]);
+
+export type GuideInline = z.infer<typeof guideInlineSchema>;
+
+const guideLeafVariants = [
+	z.object({
+		type: z.literal("heading"),
+		level: z.union([
+			z.literal(2),
+			z.literal(3),
+		]),
+		id: z.string().min(1).max(128),
+		children: z.array(guideInlineSchema).min(1),
+	}),
+	z.object({
+		type: z.literal("paragraph"),
+		children: z.array(guideInlineSchema).min(1),
+	}),
+	z.object({
+		type: z.literal("list"),
+		ordered: z.boolean(),
+		items: z.array(z.array(guideInlineSchema).min(1)).min(1).max(64),
+	}),
+	z.object({
+		type: z.literal("code"),
+		language: z.string().min(1).max(32).nullable(),
+		content: z.string().min(1).max(8192),
+	}),
+	z.object({
+		type: z.literal("callout"),
+		tone: z.enum(GuideCalloutTone),
+		children: z.array(guideInlineSchema).min(1),
+	}),
+	z.object({
+		type: z.literal("image"),
+		url: z.url(),
+		alt: z.string().max(256),
+		width: z.int().positive().nullable(),
+		height: z.int().positive().nullable(),
+	}),
+	z.object({
+		type: z.literal("youtube"),
+		videoId: zYoutubeId,
+	}),
+	z.object({
+		type: z.literal("field"),
+		key: zGuideVariableRef,
+	}),
+	z.object({
+		type: z.literal("command"),
+		command: zGuideCommand,
+	}),
+	z.object({
+		type: z.literal("open"),
+		target: guideOpenTargetSchema,
+	}),
+] as const;
+
+export const guideLeafBlockSchema = z.discriminatedUnion("type", guideLeafVariants);
+
+export type GuideLeafBlock = z.infer<typeof guideLeafBlockSchema>;
+
+export const guideBlockSchema = z.discriminatedUnion("type", [
+	...guideLeafVariants,
+	z.object({
+		type: z.literal("conditional"),
+		key: zGuideVariableRef,
+		when: z.array(guideLeafBlockSchema).min(1).max(32),
+		otherwise: z.array(guideLeafBlockSchema).max(32),
+	}),
+]);
+
+export type GuideBlock = z.infer<typeof guideBlockSchema>;