@serverkgg/bridge 0.0.2 → 0.0.3

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.2",
+	"version": "0.0.3",
 	"description": "Serverk game bridge — driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",

package/src/cli/link.test.ts

@@ -0,0 +1,199 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import {
+	existsSync,
+	lstatSync,
+	mkdirSync,
+	mkdtempSync,
+	realpathSync,
+	rmSync,
+	symlinkSync,
+	writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { checkBridge, linkBridge, unlinkBridge } from "./link";
+
+const SOURCE = "../serverk/modules/bridge";
+
+describe("link", () => {
+	let root = "";
+	let cwd = "";
+	let source = "";
+	let target = "";
+
+	const writePackage = (dir: string, name: string, version: string) => {
+		mkdirSync(dir, {
+			recursive: true,
+		});
+		writeFileSync(
+			join(dir, "package.json"),
+			JSON.stringify({
+				name,
+				version,
+			}),
+		);
+	};
+
+	const link = (env: Record<string, string | undefined> = {}) => {
+		return linkBridge({
+			cwd,
+			source: SOURCE,
+			env,
+		});
+	};
+
+	beforeEach(() => {
+		root = realpathSync(mkdtempSync(`${tmpdir()}/serverk-link-`));
+		cwd = join(root, "game");
+		source = join(root, "serverk/modules/bridge");
+		target = join(cwd, "node_modules/@serverkgg/bridge");
+
+		mkdirSync(cwd, {
+			recursive: true,
+		});
+	});
+
+	afterEach(() => {
+		rmSync(root, {
+			force: true,
+			recursive: true,
+		});
+	});
+
+	test("skips when CI is set", () => {
+		writePackage(source, "@serverkgg/bridge", "0.0.3");
+		writePackage(target, "@serverkgg/bridge", "0.0.2");
+
+		expect(
+			link({
+				CI: "true",
+			}),
+		).toMatchObject({
+			kind: "skipped",
+			reason: "ci",
+		});
+
+		expect(lstatSync(target).isSymbolicLink()).toBe(false);
+	});
+
+	test("skips when the local checkout is missing", () => {
+		expect(link()).toMatchObject({
+			kind: "skipped",
+			reason: "source-missing",
+		});
+	});
+
+	test("skips when the local checkout is another package", () => {
+		writePackage(source, "@serverkgg/minecraft", "0.0.0");
+
+		expect(link()).toMatchObject({
+			kind: "skipped",
+			reason: "source-mismatch",
+		});
+	});
+
+	test("replaces the registry directory with a symlink", () => {
+		writePackage(source, "@serverkgg/bridge", "0.0.3");
+		writePackage(target, "@serverkgg/bridge", "0.0.2");
+		writeFileSync(join(target, "installed.txt"), "registry");
+
+		expect(link()).toEqual({
+			kind: "linked",
+			source,
+			version: "0.0.3",
+		});
+
+		expect(lstatSync(target).isSymbolicLink()).toBe(true);
+		expect(realpathSync(target)).toBe(source);
+		expect(existsSync(join(target, "installed.txt"))).toBe(false);
+		expect(existsSync(join(source, "package.json"))).toBe(true);
+	});
+
+	test("creates the scope directory when nothing is installed", () => {
+		writePackage(source, "@serverkgg/bridge", "0.0.3");
+
+		expect(link()).toMatchObject({
+			kind: "linked",
+		});
+
+		expect(realpathSync(target)).toBe(source);
+	});
+
+	test("is idempotent once linked", () => {
+		writePackage(source, "@serverkgg/bridge", "0.0.3");
+
+		expect(link()).toMatchObject({
+			kind: "linked",
+		});
+
+		expect(link()).toEqual({
+			kind: "already-linked",
+			source,
+		});
+
+		expect(realpathSync(target)).toBe(source);
+	});
+
+	test("relinks a symlink pointing somewhere else", () => {
+		const other = join(root, "other");
+
+		writePackage(source, "@serverkgg/bridge", "0.0.3");
+		writePackage(other, "@serverkgg/bridge", "0.0.1");
+		mkdirSync(join(cwd, "node_modules/@serverkgg"), {
+			recursive: true,
+		});
+		symlinkSync(other, target, "dir");
+
+		expect(link()).toMatchObject({
+			kind: "linked",
+			version: "0.0.3",
+		});
+
+		expect(realpathSync(target)).toBe(source);
+		expect(existsSync(join(other, "package.json"))).toBe(true);
+	});
+
+	test("unlink removes the symlink and keeps the checkout", () => {
+		writePackage(source, "@serverkgg/bridge", "0.0.3");
+		link();
+
+		expect(unlinkBridge(cwd)).toEqual({
+			kind: "unlinked",
+			source,
+		});
+
+		expect(existsSync(target)).toBe(false);
+		expect(existsSync(join(source, "package.json"))).toBe(true);
+	});
+
+	test("unlink leaves a registry install alone", () => {
+		writePackage(target, "@serverkgg/bridge", "0.0.2");
+
+		expect(unlinkBridge(cwd)).toEqual({
+			kind: "not-linked",
+		});
+
+		expect(existsSync(join(target, "package.json"))).toBe(true);
+	});
+
+	test("check reports every state", () => {
+		expect(checkBridge(cwd)).toEqual({
+			kind: "missing",
+		});
+
+		writePackage(target, "@serverkgg/bridge", "0.0.2");
+
+		expect(checkBridge(cwd)).toEqual({
+			kind: "registry",
+			version: "0.0.2",
+		});
+
+		writePackage(source, "@serverkgg/bridge", "0.0.3");
+		link();
+
+		expect(checkBridge(cwd)).toEqual({
+			kind: "linked",
+			source,
+		});
+	});
+});

package/src/cli/link.ts

@@ -0,0 +1,319 @@
+import { lstatSync, mkdirSync, readFileSync, realpathSync, rmSync, symlinkSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+
+const PACKAGE_NAME = "@serverkgg/bridge";
+
+const DEFAULT_SOURCE = "../serverk/modules/bridge";
+
+const INSTALL_PATH = `node_modules/${PACKAGE_NAME}`;
+
+const HELP = `serverk-bridge link [options]
+
+point ${INSTALL_PATH} at a local bridge checkout without touching package.json or bun.lock.
+does nothing when CI is set or the checkout is absent, so the registry package is used everywhere else.
+
+options:
+  --source <dir>   local bridge checkout (default: ${DEFAULT_SOURCE})
+  --check          print which bridge is installed, change nothing
+  --unlink         drop the link so the next install restores the registry package
+  --help           show this help`;
+
+interface PackageFile {
+	name: string;
+	version: string;
+}
+
+interface LinkInput {
+	cwd: string;
+	source: string;
+	env: Record<string, string | undefined>;
+}
+
+export type LinkSkip = "ci" | "source-missing" | "source-mismatch";
+
+export type LinkResult =
+	| {
+			kind: "skipped";
+			reason: LinkSkip;
+			source: string;
+	  }
+	| {
+			kind: "already-linked";
+			source: string;
+	  }
+	| {
+			kind: "linked";
+			source: string;
+			version: string;
+	  };
+
+export type CheckResult =
+	| {
+			kind: "linked";
+			source: string;
+	  }
+	| {
+			kind: "registry";
+			version: string;
+	  }
+	| {
+			kind: "missing";
+	  };
+
+export type UnlinkResult =
+	| {
+			kind: "unlinked";
+			source: string;
+	  }
+	| {
+			kind: "not-linked";
+	  };
+
+const readPackageFile = (dir: string): PackageFile | null => {
+	let text: string;
+
+	try {
+		text = readFileSync(join(dir, "package.json"), "utf8");
+	} catch {
+		return null;
+	}
+
+	let parsed: unknown;
+
+	try {
+		parsed = JSON.parse(text);
+	} catch {
+		return null;
+	}
+
+	if (typeof parsed !== "object" || parsed === null || !("name" in parsed) || !("version" in parsed)) {
+		return null;
+	}
+
+	const { name, version } = parsed;
+
+	if (typeof name !== "string" || typeof version !== "string") {
+		return null;
+	}
+
+	return {
+		name,
+		version,
+	};
+};
+
+const linkedSource = (target: string): string | null => {
+	try {
+		if (!lstatSync(target).isSymbolicLink()) {
+			return null;
+		}
+
+		return realpathSync(target);
+	} catch {
+		return null;
+	}
+};
+
+const installPath = (cwd: string) => {
+	return resolve(cwd, INSTALL_PATH);
+};
+
+export const linkBridge = (input: LinkInput): LinkResult => {
+	const source = resolve(input.cwd, input.source);
+
+	if (input.env.CI) {
+		return {
+			kind: "skipped",
+			reason: "ci",
+			source,
+		};
+	}
+
+	const local = readPackageFile(source);
+
+	if (!local) {
+		return {
+			kind: "skipped",
+			reason: "source-missing",
+			source,
+		};
+	}
+
+	if (local.name !== PACKAGE_NAME) {
+		return {
+			kind: "skipped",
+			reason: "source-mismatch",
+			source,
+		};
+	}
+
+	const target = installPath(input.cwd);
+
+	if (linkedSource(target) === realpathSync(source)) {
+		return {
+			kind: "already-linked",
+			source,
+		};
+	}
+
+	rmSync(target, {
+		force: true,
+		recursive: true,
+	});
+	mkdirSync(dirname(target), {
+		recursive: true,
+	});
+	symlinkSync(source, target, "dir");
+
+	return {
+		kind: "linked",
+		source,
+		version: local.version,
+	};
+};
+
+export const checkBridge = (cwd: string): CheckResult => {
+	const target = installPath(cwd);
+	const source = linkedSource(target);
+
+	if (source) {
+		return {
+			kind: "linked",
+			source,
+		};
+	}
+
+	const installed = readPackageFile(target);
+
+	if (!installed) {
+		return {
+			kind: "missing",
+		};
+	}
+
+	return {
+		kind: "registry",
+		version: installed.version,
+	};
+};
+
+export const unlinkBridge = (cwd: string): UnlinkResult => {
+	const target = installPath(cwd);
+	const source = linkedSource(target);
+
+	if (!source) {
+		return {
+			kind: "not-linked",
+		};
+	}
+
+	rmSync(target, {
+		force: true,
+	});
+
+	return {
+		kind: "unlinked",
+		source,
+	};
+};
+
+const linkText = (result: LinkResult): string | null => {
+	switch (result.kind) {
+		case "skipped": {
+			return null;
+		}
+
+		case "already-linked": {
+			return `${PACKAGE_NAME} already linked -> ${result.source}`;
+		}
+
+		case "linked": {
+			return `${PACKAGE_NAME} linked -> ${result.source} (${result.version})`;
+		}
+	}
+};
+
+const checkText = (result: CheckResult): string => {
+	switch (result.kind) {
+		case "linked": {
+			return `${PACKAGE_NAME} linked -> ${result.source}`;
+		}
+
+		case "registry": {
+			return `${PACKAGE_NAME} registry ${result.version}`;
+		}
+
+		case "missing": {
+			return `${PACKAGE_NAME} missing`;
+		}
+	}
+};
+
+const unlinkText = (result: UnlinkResult): string => {
+	switch (result.kind) {
+		case "unlinked": {
+			return `${PACKAGE_NAME} unlinked — run "bun install" to restore the registry package`;
+		}
+
+		case "not-linked": {
+			return `${PACKAGE_NAME} is not linked`;
+		}
+	}
+};
+
+export const runLink = async (args: string[]) => {
+	const { values } = parseArgs({
+		args,
+		options: {
+			source: {
+				type: "string",
+				default: DEFAULT_SOURCE,
+			},
+			check: {
+				type: "boolean",
+				default: false,
+			},
+			unlink: {
+				type: "boolean",
+				default: false,
+			},
+			help: {
+				type: "boolean",
+				default: false,
+			},
+		},
+	});
+
+	if (values.help) {
+		console.log(HELP);
+
+		return;
+	}
+
+	const cwd = process.cwd();
+
+	if (values.check) {
+		console.log(checkText(checkBridge(cwd)));
+
+		return;
+	}
+
+	if (values.unlink) {
+		console.log(unlinkText(unlinkBridge(cwd)));
+
+		return;
+	}
+
+	const message = linkText(
+		linkBridge({
+			cwd,
+			source: values.source,
+			env: process.env,
+		}),
+	);
+
+	if (message) {
+		console.log(message);
+	}
+};

package/src/cli/main.ts

@@ -2,6 +2,7 @@
 
 import { errorText } from "../runtime/bridgeLog";
 import { runCompile } from "./compile";
+import { runLink } from "./link";
 import { runSchema } from "./schema";
 import { runValidate } from "./validate";
 
@@ -11,6 +12,7 @@ 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
+  link       use a local bridge checkout while developing
 
 run "serverk-bridge <command> --help" for options`;
 
@@ -36,6 +38,12 @@ try {
 			break;
 		}
 
+		case "link": {
+			await runLink(args);
+
+			break;
+		}
+
 		case undefined:
 		case "--help": {
 			console.log(USAGE);

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");
+	});
+});