@serverkgg/bridge 0.0.2 → 0.0.4

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

@@ -14,6 +14,7 @@ import {
 	readPackageDocument,
 } from "../manifest";
 import type { BridgeDriver } from "../modules";
+import { isBridgeEventName } from "../protocol";
 import { validateDriver } from "../runtime/bridgeDriver";
 import { directorySource } from "./directorySource";
 
@@ -24,6 +25,64 @@ options:
   --driver <path>   driver module (default: <dir>/src/driver.ts), game packages only
   --help            show this help`;
 
+const BRIDGE_PACKAGE = "@serverkgg/bridge";
+
+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;
+	}
+
+	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)}`);
@@ -90,6 +149,43 @@ const validateGuidePackage = (source: PackageSource, document: GuidePackage) =>
 	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) => [
@@ -130,6 +226,8 @@ const validateGamePackage = async (source: PackageSource, manifest: Manifest, di
 	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[]) => {
@@ -159,6 +257,8 @@ export const runValidate = async (args: string[]) => {
 	const dir = resolve(values.dir);
 	const source = directorySource(dir);
 
+	assertRegistryBridge(source);
+
 	let document: Manifest | GuidePackage;
 
 	try {

package/src/context/bridgeContext.ts

@@ -21,6 +21,12 @@ export interface BridgeDownloadOptions {
 	cache?: boolean;
 }
 
+export interface BridgeExtractOptions {
+	extensions?: string[];
+	tree?: boolean;
+	select?: string;
+}
+
 export interface BridgeFiles {
 	read(path: string): Promise<string>;
 	write(path: string, content: string): Promise<void>;
@@ -31,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 {

package/src/core/bridgeKind.ts

@@ -1,4 +1,5 @@
 export enum BridgeKind {
+	Actions = "actions",
 	Announce = "announce",
 	Backup = "backup",
 	Catalog = "catalog",

package/src/modules/bridge.ts

@@ -1,6 +1,6 @@
 import type { BridgeContext, BridgeExecResult, BridgeFileEntry, BridgeReply } from "../context";
 import type { BridgeOption, BridgeRow, BridgeValue, BridgeValues, LocalizedText } from "../core";
-import type { BridgeField, BridgePanel, BridgeSection, BridgeTab } from "../panel";
+import type { BridgeField, BridgePanel, BridgeSection, BridgeSectionAction, BridgeTab } from "../panel";
 import type {
 	BridgeCatalogEntry,
 	BridgeCatalogFacet,
@@ -12,6 +12,7 @@ import type {
 import type { BridgeTerminalArg, BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
 import type { BridgeDriver } from "./bridgeDriver";
 import type {
+	BridgeActionsModule,
 	BridgeAnnounceModule,
 	BridgeBackupModule,
 	BridgeCatalogModule,
@@ -24,11 +25,13 @@ import type {
 	BridgeQueryModule,
 	BridgeRowAction,
 	BridgeSample,
+	BridgeServerAction,
 	BridgeSettingsModule,
 	BridgeTerminalModule,
 } from "./bridgeModule";
 
 export namespace Bridge {
+	export type Actions = BridgeActionsModule;
 	export type Announce = BridgeAnnounceModule;
 	export type Backup = BridgeBackupModule;
 	export type Catalog = BridgeCatalogModule;
@@ -57,6 +60,8 @@ export namespace Bridge {
 	export type RowAction<Row extends BridgeRow = BridgeRow> = BridgeRowAction<Row>;
 	export type Sample = BridgeSample;
 	export type Section = BridgeSection;
+	export type SectionAction = BridgeSectionAction;
+	export type ServerAction = BridgeServerAction;
 	export type Settings = BridgeSettingsModule;
 	export type Terminal = BridgeTerminalModule;
 	export type TerminalArg = BridgeTerminalArg;

package/src/modules/bridgeModule.ts

@@ -1,5 +1,5 @@
 import type { BridgeContext } from "../context";
-import type { BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues, LocalizedText } from "../core";
+import type { BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
 import type { BridgeCatalogEntry, BridgeCatalogPage, BridgeCatalogQuery } from "../protocol/bridgeCatalog";
 import type { BridgeDescribeResult } from "../protocol/bridgeFrame";
 import type { BridgeTerminalCommand, BridgeTerminalRule } from "../terminal";
@@ -23,7 +23,7 @@ export interface BridgeLifecycleModule {
 
 export interface BridgeAnnounceModule {
 	kind: BridgeKind.Announce;
-	announce(context: BridgeContext, message: LocalizedText): Promise<void>;
+	announce(context: BridgeContext, message: string): Promise<void>;
 }
 
 export interface BridgeBackupModule {
@@ -53,6 +53,7 @@ export interface BridgeEventPattern {
 export interface BridgeEventsModule {
 	kind: BridgeKind.Events;
 	patterns: BridgeEventPattern[];
+	emits?: string[];
 }
 
 export interface BridgeTerminalModule {
@@ -74,7 +75,19 @@ export interface BridgeSettingsModule {
 	write?(context: BridgeContext, values: BridgeValues): Promise<void>;
 }
 
-export type BridgeRowAction<Row extends BridgeRow = BridgeRow> = (context: BridgeContext, row: Row) => Promise<void>;
+export type BridgeRowAction<Row extends BridgeRow = BridgeRow> = (
+	context: BridgeContext,
+	row: Row,
+	args: BridgeValues,
+) => Promise<void>;
+
+export type BridgeServerAction = (context: BridgeContext, args: BridgeValues) => Promise<void>;
+
+export interface BridgeActionsModule {
+	kind: BridgeKind.Actions;
+	requiresRunning?: boolean;
+	actions: Record<string, BridgeServerAction>;
+}
 
 export interface BridgeCollectionModule<Row extends BridgeRow = BridgeRow> {
 	kind: BridgeKind.Collection;
@@ -96,6 +109,7 @@ export interface BridgeCatalogModule {
 }
 
 export type BridgePanelModule =
+	| BridgeActionsModule
 	| BridgeCatalogModule
 	| BridgeCollectionModule
 	| BridgeOptionsModule

package/src/panel/bridgeLayout.ts

@@ -1,4 +1,5 @@
 export enum BridgeLayout {
+	Actions = "actions",
 	Cards = "cards",
 	Catalog = "catalog",
 	Form = "form",

package/src/panel/bridgePanel.ts

@@ -8,7 +8,8 @@ import type { BridgeLayout } from "./bridgeLayout";
 
 export interface BridgeVisibleWhen {
 	variable: string;
-	values: string[];
+	values?: string[];
+	empty?: boolean;
 }
 
 export interface BridgeOptionsRef {
@@ -34,6 +35,9 @@ export interface BridgeSectionAction {
 	id: string;
 	label: LocalizedText;
 	confirm?: BridgeConfirm;
+	confirmText?: LocalizedText;
+	download?: boolean;
+	fields?: BridgeField[];
 }
 
 export interface BridgeSectionAdd {
@@ -41,6 +45,23 @@ export interface BridgeSectionAdd {
 	placeholder?: string;
 }
 
+export interface BridgeSectionUpload {
+	label: LocalizedText;
+	extensions: string[];
+	staging: string;
+}
+
+export interface BridgeActionsSection {
+	layout: BridgeLayout.Actions;
+	id: string;
+	title?: LocalizedText;
+	help?: LocalizedText;
+	module: string;
+	actions: BridgeSectionAction[];
+	visibleWhen?: BridgeVisibleWhen;
+	access?: BridgeAccess;
+}
+
 export interface BridgeFormSection {
 	layout: BridgeLayout.Form;
 	id: string;
@@ -66,8 +87,10 @@ export interface BridgeTableSection {
 	id: string;
 	title?: LocalizedText;
 	module: string;
+	restartHint?: boolean;
 	columns: BridgeColumn[];
 	add?: BridgeSectionAdd;
+	upload?: BridgeSectionUpload;
 	actions?: BridgeSectionAction[];
 	empty?: LocalizedText;
 	visibleWhen?: BridgeVisibleWhen;
@@ -93,12 +116,21 @@ export interface BridgeCatalogSection {
 	title?: LocalizedText;
 	module: string;
 	restartHint?: boolean;
+	reinstall?: boolean;
+	variable?: string;
+	confirm?: BridgeConfirm;
+	confirmText?: LocalizedText;
 	empty?: LocalizedText;
 	visibleWhen?: BridgeVisibleWhen;
 	access?: BridgeAccess;
 }
 
-export type BridgeSection = BridgeCardsSection | BridgeCatalogSection | BridgeFormSection | BridgeTableSection;
+export type BridgeSection =
+	| BridgeActionsSection
+	| BridgeCardsSection
+	| BridgeCatalogSection
+	| BridgeFormSection
+	| BridgeTableSection;
 
 export interface BridgeTab {
 	id: string;

package/src/protocol/bridgeCatalog.ts

@@ -45,6 +45,7 @@ export interface BridgeCatalogEntry {
 	stale: boolean;
 	pageUrl: string | null;
 	icon: string | null;
+	variables?: Record<string, string> | null;
 }
 
 export interface BridgeCatalogQuery {

package/src/protocol/bridgeEvents.ts

@@ -0,0 +1,20 @@
+export enum BridgeEventName {
+	GameModeChanged = "GameModeChanged",
+	MissingDependency = "MissingDependency",
+	PlayerJoined = "PlayerJoined",
+	PlayerLeft = "PlayerLeft",
+	PortBindFailed = "PortBindFailed",
+	ServerCrashed = "ServerCrashed",
+	ServerStarted = "ServerStarted",
+	ServerStopping = "ServerStopping",
+	TickLagging = "TickLagging",
+	WorldCorrupt = "WorldCorrupt",
+	WorldSaved = "WorldSaved",
+	WrongJavaVersion = "WrongJavaVersion",
+}
+
+export const BRIDGE_EVENT_NAMES: readonly string[] = Object.values(BridgeEventName);
+
+export const isBridgeEventName = (name: string): boolean => {
+	return BRIDGE_EVENT_NAMES.includes(name);
+};

package/src/protocol/bridgeFrame.ts

@@ -1,4 +1,4 @@
-import type { BridgeDesired, BridgeRuntime, BridgeValues, LocalizedText } from "../core";
+import type { BridgeDesired, BridgeRuntime, BridgeValues } from "../core";
 
 export const BRIDGE_SOCKET_NAME = "bridge.sock";
 
@@ -38,7 +38,7 @@ export interface BridgeRequest {
 	action?: string;
 	args?: BridgeValues;
 	cursor?: number;
-	message?: LocalizedText;
+	message?: string;
 }
 
 export interface BridgeCommandResult {

package/src/protocol/bridgeLimits.ts

@@ -0,0 +1,41 @@
+export const BRIDGE_PANEL_TABS_LIMIT = 8;
+
+export const BRIDGE_TAB_SECTIONS_LIMIT = 8;
+
+export const BRIDGE_FORM_FIELDS_LIMIT = 32;
+
+export const BRIDGE_TABLE_COLUMNS_LIMIT = 8;
+
+export const BRIDGE_ROW_ACTIONS_LIMIT = 8;
+
+export const BRIDGE_SECTION_ACTIONS_LIMIT = 10;
+
+export const BRIDGE_ACTION_FIELDS_LIMIT = 5;
+
+export const BRIDGE_FIELD_OPTIONS_LIMIT = 64;
+
+export const BRIDGE_VISIBLE_VALUES_LIMIT = 16;
+
+export const BRIDGE_UPLOAD_EXTENSIONS_LIMIT = 8;
+
+export const BRIDGE_MODULES_LIMIT = 32;
+
+export const BRIDGE_MODULE_ACTIONS_LIMIT = 16;
+
+export const BRIDGE_DEPENDS_ON_LIMIT = 8;
+
+export const BRIDGE_EVENTS_LIMIT = 32;
+
+export const BRIDGE_ID_LENGTH_LIMIT = 32;
+
+export const BRIDGE_KEY_LENGTH_LIMIT = 64;
+
+export const BRIDGE_TEXT_LENGTH_LIMIT = 512;
+
+export const BRIDGE_OPTION_VALUE_LENGTH_LIMIT = 128;
+
+export const BRIDGE_PLACEHOLDER_LENGTH_LIMIT = 256;
+
+export const BRIDGE_STAGING_LENGTH_LIMIT = 128;
+
+export const BRIDGE_EXTENSION_LENGTH_LIMIT = 16;

package/src/protocol/index.ts

@@ -4,7 +4,9 @@ export * from "../terminal";
 export * from "./bridgeCatalog";
 export * from "./bridgeConfig";
 export * from "./bridgeEgress";
+export * from "./bridgeEvents";
 export * from "./bridgeFrame";
+export * from "./bridgeLimits";
 export * from "./bridgeLine";
 export * from "./bridgeManifest";
 export * from "./bridgeVersion";

package/src/runtime/bridgeActions.ts

@@ -0,0 +1,53 @@
+import { BridgeAction, BridgeKind } from "../core";
+import type { BridgePanelModule } from "../modules";
+
+export const actionsOf = (module: BridgePanelModule): string[] => {
+	switch (module.kind) {
+		case BridgeKind.Actions: {
+			return Object.keys(module.actions);
+		}
+
+		case BridgeKind.Options: {
+			return [
+				BridgeAction.List,
+			];
+		}
+
+		case BridgeKind.Settings: {
+			return [
+				BridgeAction.Read,
+				...(module.write
+					? [
+							BridgeAction.Write,
+						]
+					: []),
+			];
+		}
+
+		case BridgeKind.Collection: {
+			return [
+				BridgeAction.List,
+				...(module.add
+					? [
+							BridgeAction.Add,
+						]
+					: []),
+				...Object.keys(module.actions ?? {}),
+			];
+		}
+
+		case BridgeKind.Catalog: {
+			return [
+				BridgeAction.Install,
+				BridgeAction.Installed,
+				BridgeAction.Remove,
+				BridgeAction.Search,
+				...(module.toggle
+					? [
+							BridgeAction.Toggle,
+						]
+					: []),
+			];
+		}
+	}
+};