@serverkgg/bridge 0.0.1 → 0.0.2

package/package.json

@@ -1,12 +1,17 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.1",
+	"version": "0.0.2",
 	"description": "Serverk game bridge — driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/serverkgg/serverk.git",
+		"directory": "modules/bridge"
+	},
 	"type": "module",
 	"bin": {
-		"serverk-bridge": "./src/cli/main.ts"
+		"serverk-bridge": "src/cli/main.ts"
 	},
 	"files": [
 		"src"
@@ -15,10 +20,12 @@
 		".": "./src/main.ts",
 		"./protocol": "./src/protocol/index.ts",
 		"./manifest": "./src/manifest/index.ts",
+		"./guides": "./src/guides/index.ts",
 		"./package.json": "./package.json"
 	},
 	"scripts": {
-		"tsc": "tsc"
+		"tsc": "tsc",
+		"test": "bun test"
 	},
 	"dependencies": {
 		"zod": "4.4.3"

package/src/cli/main.ts

@@ -1,11 +1,15 @@
 #!/usr/bin/env bun
+
+import { errorText } from "../runtime/bridgeLog";
 import { runCompile } from "./compile";
+import { runSchema } from "./schema";
 import { runValidate } from "./validate";
 
 const USAGE = `serverk-bridge <command>
 
 commands:
   validate   validate serverk.yml, assets, and driver wiring
+  schema     write the serverk.yml JSON Schema for editor tooling
   compile    compile the bridge binary for amd64 and arm64
 
 run "serverk-bridge <command> --help" for options`;
@@ -20,6 +24,12 @@ try {
 			break;
 		}
 
+		case "schema": {
+			await runSchema(args);
+
+			break;
+		}
+
 		case "compile": {
 			await runCompile(args);
 
@@ -39,6 +49,6 @@ try {
 		}
 	}
 } catch (error) {
-	console.error(error instanceof Error ? error.message : String(error));
+	console.error(errorText(error));
 	process.exit(1);
 }

package/src/cli/schema.ts

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { renderJsonSchema, SCHEMA_FILE } from "../manifest";
+
+const HELP = `serverk-bridge schema [options]
+
+options:
+  --out <path>   file to write (default: ${SCHEMA_FILE})
+  --check        fail when the file on disk is out of date instead of writing
+  --help         show this help`;
+
+export const runSchema = async (args: string[]) => {
+	const { values } = parseArgs({
+		args,
+		options: {
+			out: {
+				type: "string",
+				default: SCHEMA_FILE,
+			},
+			check: {
+				type: "boolean",
+				default: false,
+			},
+			help: {
+				type: "boolean",
+				default: false,
+			},
+		},
+	});
+
+	if (values.help) {
+		console.log(HELP);
+
+		return;
+	}
+
+	const target = resolve(values.out);
+	const rendered = renderJsonSchema();
+
+	if (values.check) {
+		let current: string;
+
+		try {
+			current = readFileSync(target, "utf8");
+		} catch {
+			throw new Error(`${values.out} is missing — run "serverk-bridge schema" and commit it`);
+		}
+
+		if (current !== rendered) {
+			throw new Error(`${values.out} is out of date — run "serverk-bridge schema" and commit it`);
+		}
+
+		console.log(`${values.out} is up to date`);
+
+		return;
+	}
+
+	writeFileSync(target, rendered);
+
+	console.log(`wrote ${values.out}`);
+};

package/src/cli/validate.ts

@@ -3,7 +3,16 @@ 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 { validateDriver } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
@@ -11,53 +20,81 @@ 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 invalidManifest = (error: unknown): never => {
+	if (error instanceof z.ZodError) {
+		throw new Error(`${MANIFEST_FILE} is invalid\n${z.prettifyError(error)}`);
+	}
 
-	if (values.help) {
-		console.log(HELP);
+	throw 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;
 	}
 
-	const dir = resolve(values.dir);
-	const source = directorySource(dir);
+	console.log(
+		`  guides: ${pack.drafts.length} guide(s), ${countDynamic(pack)} dynamic block(s), ${pack.images.length} image(s)`,
+	);
 
-	let manifest: Manifest;
+	if (pack.commands.length === 0) {
+		return;
+	}
 
-	try {
-		manifest = readPackage(source).manifest;
-	} catch (error) {
-		if (error instanceof z.ZodError) {
-			throw new Error(`serverk.yml is invalid\n${z.prettifyError(error)}`);
-		}
+	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,
+	]);
 
-		throw error;
+	for (const path of guideFiles) {
+		if (source.read(path) === null) {
+			throw new Error(`declared file "${path}" is missing`);
+		}
 	}
 
+	const pack = readGuidePackage(source, document);
+
+	console.log(`${document.metadata.id} is valid`);
+	reportGuides(pack);
+};
+
+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 +103,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 +121,57 @@ 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)`,
 	);
 };
+
+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);
+
+	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,7 @@ export interface BridgeFileEntry {
 export interface BridgeDownloadOptions {
 	digest?: string;
 	sizeBytes?: number;
+	cache?: boolean;
 }
 
 export interface BridgeFiles {
@@ -52,6 +53,9 @@ export interface BridgeCodecs {
 export interface BridgeRequestOptions {
 	headers?: Record<string, string>;
 	timeoutMs?: number;
+	cache?: boolean;
+	cacheSeconds?: number;
+	refresh?: boolean;
 }
 
 export interface BridgeNet {
@@ -103,6 +107,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 +126,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,9 @@
 export enum BridgeKind {
+	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>;