@serverkgg/bridge 0.0.1

package/LICENSE.md

@@ -0,0 +1,22 @@
+# Serverk Community License
+
+Version 1.0
+
+Copyright (c) 2026 Serverk — serverk.gg. All rights reserved.
+
+## Grant
+
+Permission is granted, free of charge, to any person obtaining a copy of this software (the "Bridge") to:
+
+1. Use, copy, and modify the Bridge solely to develop, test, and operate game packages that run on the Serverk platform (`serverk.gg`).
+2. Contribute changes back to Serverk repositories.
+
+## Restrictions
+
+1. The Bridge may not be used, in whole or in part, with any platform or service other than Serverk, or to build or operate a product or service that competes with Serverk.
+2. The Bridge may not be redistributed, sublicensed, or sold, except as installed unmodified from the official npm package or as part of a contribution to Serverk repositories.
+3. This license grants no rights to Serverk names, logos, or trademarks.
+
+## Disclaimer
+
+THE BRIDGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. IN NO EVENT SHALL SERVERK BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER LIABILITY ARISING FROM THE USE OF THE BRIDGE.

package/README.md

@@ -0,0 +1,52 @@
+# @serverkgg/bridge
+
+جسر سيرفرك — المكتبة اللي تربط حزمة اللعبة بمنصة سيرفرك (Serverk). تكتب فيها الـ driver حق لعبتك، وتنضغط معه في ملف تنفيذي واحد يصير هو نقطة دخول كونتينر السيرفر.
+
+The Serverk bridge — the library that connects a game package to the Serverk platform (`serverk.gg`). You write your game's driver against it, and it compiles with your code into a single binary that becomes the server container's entrypoint.
+
+The bridge ships raw TypeScript and targets the Bun runtime only.
+
+## Entry points
+
+- `@serverkgg/bridge` — the game-author API: `serve`, the `Bridge` namespace, capability modules, and panel types.
+- `@serverkgg/bridge/protocol` — the wire contract between the bridge and the Serverk agent.
+- `@serverkgg/bridge/manifest` — the `serverk.yml` schema and validation helpers.
+
+## Writing a game package
+
+Export your driver from `src/driver.ts` and serve it from `src/main.ts`:
+
+```ts
+import type { BridgeDriver } from "@serverkgg/bridge";
+
+export const driver: BridgeDriver = {
+ install,
+ lifecycle,
+};
+```
+
+```ts
+import { serve } from "@serverkgg/bridge";
+import { driver } from "./driver";
+
+await serve(driver);
+```
+
+The `src/driver.ts` convention is what lets `serverk-bridge validate` check your wiring without booting a server.
+
+## CLI
+
+```sh
+bunx serverk-bridge validate
+bunx serverk-bridge compile
+```
+
+`validate` checks `serverk.yml` against the real platform schema, verifies the logo and banner, and validates the driver's panel wiring. `compile` produces `dist/bridge-amd64` and `dist/bridge-arm64`.
+
+## Compatibility
+
+Only the major version carries compatibility meaning. The platform refuses a game image whose bridge major differs from the fleet's; minor and patch releases are always safe to pick up.
+
+## License
+
+Source-available under the Serverk Community License: use it to build and run game packages for Serverk. See `LICENSE.md`.

package/package.json

@@ -0,0 +1,26 @@
+{
+	"name": "@serverkgg/bridge",
+	"version": "0.0.1",
+	"description": "Serverk game bridge — driver runtime, wire protocol, manifest schema, and maintainer CLI",
+	"homepage": "https://serverk.gg",
+	"license": "SEE LICENSE IN LICENSE.md",
+	"type": "module",
+	"bin": {
+		"serverk-bridge": "./src/cli/main.ts"
+	},
+	"files": [
+		"src"
+	],
+	"exports": {
+		".": "./src/main.ts",
+		"./protocol": "./src/protocol/index.ts",
+		"./manifest": "./src/manifest/index.ts",
+		"./package.json": "./package.json"
+	},
+	"scripts": {
+		"tsc": "tsc"
+	},
+	"dependencies": {
+		"zod": "4.4.3"
+	}
+}

package/src/cli/compile.ts

@@ -0,0 +1,75 @@
+import { parseArgs } from "node:util";
+
+const TARGETS: Record<string, string> = {
+	amd64: "bun-linux-x64",
+	arm64: "bun-linux-arm64",
+};
+
+const HELP = `serverk-bridge compile [options]
+
+options:
+  --arch <amd64|arm64>   architecture to compile (repeatable, default: both)
+  --entry <path>         entrypoint (default: src/main.ts)
+  --outdir <path>        output directory (default: dist)
+  --help                 show this help`;
+
+export const runCompile = async (args: string[]) => {
+	const { values } = parseArgs({
+		args,
+		options: {
+			arch: {
+				type: "string",
+				multiple: true,
+			},
+			entry: {
+				type: "string",
+				default: "src/main.ts",
+			},
+			outdir: {
+				type: "string",
+				default: "dist",
+			},
+			help: {
+				type: "boolean",
+				default: false,
+			},
+		},
+	});
+
+	if (values.help) {
+		console.log(HELP);
+
+		return;
+	}
+
+	const arches = values.arch?.length ? values.arch : Object.keys(TARGETS);
+
+	for (const arch of arches) {
+		const target = TARGETS[arch];
+
+		if (!target) {
+			throw new Error(`unknown arch "${arch}" — expected amd64 or arm64`);
+		}
+
+		const outfile = `${values.outdir}/bridge-${arch}`;
+		const child = Bun.spawn(
+			[
+				"bun",
+				"build",
+				"--compile",
+				`--target=${target}`,
+				values.entry,
+				"--outfile",
+				outfile,
+			],
+			{
+				stderr: "inherit",
+				stdout: "inherit",
+			},
+		);
+
+		if ((await child.exited) !== 0) {
+			throw new Error(`compile failed for ${arch}`);
+		}
+	}
+};

package/src/cli/directorySource.ts

@@ -0,0 +1,48 @@
+import { readdirSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { PackageSource } from "../manifest";
+
+const EXCLUDED = new Set([
+	".git",
+	"dist",
+	"node_modules",
+	"tmp",
+	"vendor",
+]);
+
+const walk = (root: string, prefix: string, paths: string[]) => {
+	for (const entry of readdirSync(join(root, prefix), {
+		withFileTypes: true,
+	})) {
+		if (EXCLUDED.has(entry.name)) {
+			continue;
+		}
+
+		const path = prefix ? `${prefix}/${entry.name}` : entry.name;
+
+		if (entry.isDirectory()) {
+			walk(root, path, paths);
+		} else if (entry.isFile()) {
+			paths.push(path);
+		}
+	}
+};
+
+export const directorySource = (root: string): PackageSource => {
+	return {
+		list() {
+			const paths: string[] = [];
+
+			walk(root, "", paths);
+
+			return paths;
+		},
+		read(path) {
+			try {
+				return new Uint8Array(readFileSync(join(root, path)));
+			} catch {
+				return null;
+			}
+		},
+	};
+};

package/src/cli/main.ts

@@ -0,0 +1,44 @@
+#!/usr/bin/env bun
+import { runCompile } from "./compile";
+import { runValidate } from "./validate";
+
+const USAGE = `serverk-bridge <command>
+
+commands:
+  validate   validate serverk.yml, assets, and driver wiring
+  compile    compile the bridge binary for amd64 and arm64
+
+run "serverk-bridge <command> --help" for options`;
+
+const [command, ...args] = process.argv.slice(2);
+
+try {
+	switch (command) {
+		case "validate": {
+			await runValidate(args);
+
+			break;
+		}
+
+		case "compile": {
+			await runCompile(args);
+
+			break;
+		}
+
+		case undefined:
+		case "--help": {
+			console.log(USAGE);
+
+			break;
+		}
+
+		default: {
+			console.error(`unknown command "${command}"\n\n${USAGE}`);
+			process.exit(1);
+		}
+	}
+} catch (error) {
+	console.error(error instanceof Error ? error.message : String(error));
+	process.exit(1);
+}

package/src/cli/validate.ts

@@ -0,0 +1,94 @@
+import { existsSync } from "node:fs";
+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 { BridgeDriver } from "../modules";
+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)
+  --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,
+			},
+		},
+	});
+
+	if (values.help) {
+		console.log(HELP);
+
+		return;
+	}
+
+	const dir = resolve(values.dir);
+	const source = directorySource(dir);
+
+	let manifest: Manifest;
+
+	try {
+		manifest = readPackage(source).manifest;
+	} catch (error) {
+		if (error instanceof z.ZodError) {
+			throw new Error(`serverk.yml is invalid\n${z.prettifyError(error)}`);
+		}
+
+		throw error;
+	}
+
+	const assets = readAssets(source, manifest);
+	const guideFiles = manifest.guides.flatMap((guide) => [
+		guide.body.ar,
+		guide.body.en,
+	]);
+
+	for (const path of declaredFiles(manifest, guideFiles)) {
+		if (source.read(path) === null) {
+			throw new Error(`declared file "${path}" is missing`);
+		}
+	}
+
+	const driverPath = values.driver ? resolve(values.driver) : join(dir, "src/driver.ts");
+
+	if (!existsSync(driverPath)) {
+		throw new Error(`no driver module at ${driverPath} — export your BridgeDriver from src/driver.ts`);
+	}
+
+	const imported = await import(pathToFileURL(driverPath).href);
+	const driver: BridgeDriver | undefined = imported.driver ?? imported.default;
+
+	if (!driver || typeof driver !== "object") {
+		throw new Error(`${driverPath} must export a BridgeDriver named "driver"`);
+	}
+
+	validateDriver(driver);
+
+	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)`,
+	);
+	console.log(
+		`  assets: logo ${assets.logo.dimensions.width}x${assets.logo.dimensions.height}, banner ${assets.banner.dimensions.width}x${assets.banner.dimensions.height}`,
+	);
+	console.log(
+		`  driver: ${Object.keys(driver.modules ?? {}).length} panel module(s), ${driver.panel?.tabs.length ?? 0} tab(s)`,
+	);
+};

package/src/codecs/index.ts

@@ -0,0 +1,3 @@
+export * from "./json";
+export * from "./properties";
+export * from "./ueIni";

package/src/codecs/json.ts

@@ -0,0 +1,42 @@
+import type { BridgeValue } from "../core";
+
+const isScalar = (value: unknown): value is BridgeValue => {
+	return value === null || typeof value === "string" || typeof value === "number" || typeof value === "boolean";
+};
+
+const toObject = (contents: string) => {
+	if (contents.trim().length === 0) {
+		return {};
+	}
+
+	const parsed: unknown = JSON.parse(contents);
+
+	if (parsed === null || typeof parsed !== "object" || Array.isArray(parsed)) {
+		return {};
+	}
+
+	return parsed as Record<string, unknown>;
+};
+
+export const parseJson = (contents: string) => {
+	const values: Record<string, BridgeValue> = {};
+
+	for (const [key, value] of Object.entries(toObject(contents))) {
+		if (isScalar(value)) {
+			values[key] = value;
+		}
+	}
+
+	return values;
+};
+
+export const mergeJson = (contents: string, values: Record<string, BridgeValue>) => {
+	return `${JSON.stringify(
+		{
+			...toObject(contents),
+			...values,
+		},
+		null,
+		2,
+	)}\n`;
+};

package/src/codecs/properties.ts

@@ -0,0 +1,75 @@
+const COMMENT_MARKERS = [
+	"#",
+	"!",
+];
+
+const SEPARATOR = "=";
+
+const isComment = (line: string) => {
+	const trimmed = line.trimStart();
+
+	return trimmed.length === 0 || COMMENT_MARKERS.some((marker) => trimmed.startsWith(marker));
+};
+
+export const parseProperties = (contents: string) => {
+	const values: Record<string, string> = {};
+
+	for (const line of contents.split("\n")) {
+		if (isComment(line)) {
+			continue;
+		}
+
+		const separator = line.indexOf(SEPARATOR);
+
+		if (separator === -1) {
+			continue;
+		}
+
+		values[line.slice(0, separator).trim()] = line.slice(separator + 1).trim();
+	}
+
+	return values;
+};
+
+export const mergeProperties = (contents: string, values: Record<string, string>) => {
+	const pending = new Map(Object.entries(values));
+	const lines = contents.length === 0 ? [] : contents.split("\n");
+	const output: string[] = [];
+
+	for (const line of lines) {
+		if (isComment(line)) {
+			output.push(line);
+
+			continue;
+		}
+
+		const separator = line.indexOf(SEPARATOR);
+
+		if (separator === -1) {
+			output.push(line);
+
+			continue;
+		}
+
+		const key = line.slice(0, separator).trim();
+
+		if (!pending.has(key)) {
+			output.push(line);
+
+			continue;
+		}
+
+		output.push(`${key}${SEPARATOR}${pending.get(key)}`);
+		pending.delete(key);
+	}
+
+	while (output.length > 0 && output.at(-1)?.length === 0) {
+		output.pop();
+	}
+
+	for (const [key, value] of pending) {
+		output.push(`${key}${SEPARATOR}${value}`);
+	}
+
+	return `${output.join("\n")}\n`;
+};