@serverkgg/bridge 0.0.17 → 0.0.18

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.17",
+	"version": "0.0.18",
 	"description": "Serverk game bridge and driver runtime, wire protocol, manifest schema, and maintainer CLI",
 	"homepage": "https://serverk.gg",
 	"license": "SEE LICENSE IN LICENSE.md",
@@ -39,6 +39,6 @@
 		"test": "bun test --parallel"
 	},
 	"dependencies": {
-		"zod": "4.5.4"
+		"zod": "4.6.4"
 	}
 }

package/src/codecs/index.ts

@@ -1,4 +1,5 @@
 export * from "./ini";
+export * from "./javaProperties";
 export * from "./json";
 export * from "./properties";
 export * from "./sourceCfg";

package/src/codecs/javaProperties.test.ts

@@ -0,0 +1,67 @@
+import { describe, expect, test } from "bun:test";
+import { escapeJavaProperty, mergeJavaProperties, parseJavaProperties, unescapeJavaProperty } from "./javaProperties";
+
+const ARABIC = "سيرفرك";
+
+describe("parseJavaProperties", () => {
+	test("decodes the unicode escapes the java server writes", () => {
+		expect(parseJavaProperties("motd=\\u0633\\u064A\\u0631\\u0641\\u0631\\u0643\n")).toEqual({
+			motd: ARABIC,
+		});
+	});
+
+	test("decodes backslash escapes in values", () => {
+		expect(parseJavaProperties("resource-pack=https\\://example.com/pack.zip\nmotd=a\\tb\\\\c\n")).toEqual({
+			"resource-pack": "https://example.com/pack.zip",
+			motd: "a\tb\\c",
+		});
+	});
+
+	test("repairs a value the server stored as latin-1 bytes of utf-8", () => {
+		expect(parseJavaProperties("motd=ddss \\u00D9\\u008A\\u00D8\\u00AA\n")).toEqual({
+			motd: "ddss يت",
+		});
+	});
+
+	test("keeps plain latin-1 text that is not utf-8", () => {
+		expect(unescapeJavaProperty("caf\\u00E9")).toBe("café");
+	});
+
+	test("keeps comments and plain values", () => {
+		expect(parseJavaProperties("#Minecraft server properties\nmax-players=20\n")).toEqual({
+			"max-players": "20",
+		});
+	});
+});
+
+describe("mergeJavaProperties", () => {
+	test("writes non ascii text as unicode escapes", () => {
+		expect(
+			mergeJavaProperties("motd=A Minecraft Server\nmax-players=20\n", {
+				motd: ARABIC,
+			}),
+		).toBe("motd=\\u0633\\u064A\\u0631\\u0641\\u0631\\u0643\nmax-players=20\n");
+	});
+
+	test("escapes the characters java treats as separators", () => {
+		expect(escapeJavaProperty("https://a.b#c=d!e")).toBe("https\\://a.b\\#c\\=d\\!e");
+	});
+
+	test("escapes a leading space and control characters", () => {
+		expect(escapeJavaProperty(" a\tb\\c")).toBe("\\ a\\tb\\\\c");
+	});
+
+	test("round trips astral characters", () => {
+		const value = "hi 🎮";
+
+		expect(unescapeJavaProperty(escapeJavaProperty(value))).toBe(value);
+	});
+
+	test("appends a key the file does not have yet", () => {
+		expect(
+			mergeJavaProperties("", {
+				motd: "hello",
+			}),
+		).toBe("motd=hello\n");
+	});
+});

package/src/codecs/javaProperties.ts

@@ -0,0 +1,99 @@
+import { mergeProperties, parseProperties } from "./properties";
+
+const UNICODE_ESCAPE = /\\u([0-9A-Fa-f]{4})/g;
+
+const SIMPLE_ESCAPE = /\\(.)/g;
+
+const SIMPLE_ESCAPES: Record<string, string> = {
+	t: "\t",
+	n: "\n",
+	r: "\r",
+	f: "\f",
+};
+
+const ESCAPED_CHARACTERS: Record<string, string> = {
+	"\\": "\\\\",
+	"\t": "\\t",
+	"\n": "\\n",
+	"\r": "\\r",
+	"\f": "\\f",
+	"=": "\\=",
+	":": "\\:",
+	"#": "\\#",
+	"!": "\\!",
+};
+
+const PRINTABLE_MIN = 0x20;
+
+const PRINTABLE_MAX = 0x7e;
+
+const LATIN1_MAX = 0xff;
+
+const HEX_DIGITS = 4;
+
+const latin1Decoder = new TextDecoder("utf-8", {
+	fatal: true,
+});
+
+const repairLatin1 = (text: string) => {
+	const codes = Array.from(text, (character) => character.charCodeAt(0));
+
+	if (codes.every((code) => code <= PRINTABLE_MAX) || codes.some((code) => code > LATIN1_MAX)) {
+		return text;
+	}
+
+	try {
+		return latin1Decoder.decode(Uint8Array.from(codes));
+	} catch {
+		return text;
+	}
+};
+
+export const unescapeJavaProperty = (text: string) => {
+	const unescaped = text
+		.replace(UNICODE_ESCAPE, (_, hex: string) => String.fromCharCode(Number.parseInt(hex, 16)))
+		.replace(SIMPLE_ESCAPE, (_, character: string) => SIMPLE_ESCAPES[character] ?? character);
+
+	return repairLatin1(unescaped);
+};
+
+export const escapeJavaProperty = (text: string) => {
+	let escaped = "";
+
+	for (const character of text) {
+		const code = character.codePointAt(0) ?? 0;
+		const known = ESCAPED_CHARACTERS[character];
+
+		if (known !== undefined) {
+			escaped += known;
+		} else if (code < PRINTABLE_MIN || code > PRINTABLE_MAX) {
+			for (let index = 0; index < character.length; index += 1) {
+				escaped += `\\u${character.charCodeAt(index).toString(16).toUpperCase().padStart(HEX_DIGITS, "0")}`;
+			}
+		} else {
+			escaped += character;
+		}
+	}
+
+	return escaped.startsWith(" ") ? `\\${escaped}` : escaped;
+};
+
+export const parseJavaProperties = (contents: string) => {
+	const values: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(parseProperties(contents))) {
+		values[unescapeJavaProperty(key)] = unescapeJavaProperty(value);
+	}
+
+	return values;
+};
+
+export const mergeJavaProperties = (contents: string, values: Record<string, string>) => {
+	const escaped: Record<string, string> = {};
+
+	for (const [key, value] of Object.entries(values)) {
+		escaped[escapeJavaProperty(key)] = escapeJavaProperty(value);
+	}
+
+	return mergeProperties(contents, escaped);
+};

package/src/context/bridgeContext.ts

@@ -66,6 +66,7 @@ export interface BridgeCodec {
 
 export interface BridgeCodecs {
 	ini: BridgeCodec;
+	javaProperties: BridgeCodec;
 	json: BridgeCodec;
 	properties: BridgeCodec;
 	sourceCfg: BridgeCodec;

package/src/modules/bridge.ts

@@ -11,6 +11,7 @@ import type {
 } from "../core";
 import { BridgeUserError } from "../core";
 import type {
+	BridgeAddOutcome,
 	BridgeDetail,
 	BridgeDetailBadge,
 	BridgeDetailLink,
@@ -72,6 +73,7 @@ import type {
 
 export namespace Bridge {
 	export type Actions = BridgeActionsModule;
+	export type AddOutcome = BridgeAddOutcome;
 	export type Announce = BridgeAnnounceModule;
 	export type Backup = BridgeBackupModule;
 	export type Catalog = BridgeCatalogModule;

package/src/modules/bridgeModule.ts

@@ -1,6 +1,6 @@
 import type { BridgeContext, BridgeReply } from "../context";
 import type { BridgeInstallOutcome, BridgeKind, BridgeOption, BridgeRow, BridgeStream, BridgeValues } from "../core";
-import type { BridgeDetail, BridgeDetailOutcome } from "../panel";
+import type { BridgeAddOutcome, BridgeDetail, BridgeDetailOutcome } from "../panel";
 import type {
 	BridgeCatalogEntry,
 	BridgeCatalogPage,
@@ -131,7 +131,7 @@ export interface BridgeCollectionModule<Row extends BridgeRow = BridgeRow> {
 	requiresRunning?: boolean;
 	refreshSeconds?: number;
 	list(context: BridgeContext): Promise<Row[]>;
-	add?(context: BridgeContext, input: string): Promise<void>;
+	add?(context: BridgeContext, input: string): Promise<BridgeAddOutcome | undefined>;
 	actions?: Record<string, BridgeRowAction<Row>>;
 }
 

package/src/panel/bridgeCollection.ts

@@ -0,0 +1,5 @@
+import type { LocalizedText } from "../core";
+
+export interface BridgeAddOutcome {
+	notice: LocalizedText;
+}

package/src/panel/index.ts

@@ -1,4 +1,5 @@
 export * from "./bridgeAccess";
+export * from "./bridgeCollection";
 export * from "./bridgeConfirm";
 export * from "./bridgeControl";
 export * from "./bridgeDetail";

package/src/runtime/bridgeCodec.ts

@@ -1,11 +1,13 @@
 import {
 	mergeIni,
+	mergeJavaProperties,
 	mergeJson,
 	mergeProperties,
 	mergeSourceCfg,
 	mergeUeIni,
 	mergeXmlProperties,
 	parseIni,
+	parseJavaProperties,
 	parseJson,
 	parseProperties,
 	parseSourceCfg,
@@ -61,6 +63,15 @@ export const createBridgeCodecs = (files: BridgeFiles): BridgeCodecs => {
 		},
 	};
 
+	const javaProperties: BridgeCodec = {
+		async read(path) {
+			return widen(parseJavaProperties(await readOr(files, path)));
+		},
+		async merge(path, values) {
+			await files.write(path, mergeJavaProperties(await readOr(files, path), toStrings(values)));
+		},
+	};
+
 	const json: BridgeCodec = {
 		async read(path) {
 			return parseJson(await readOr(files, path));
@@ -112,6 +123,7 @@ export const createBridgeCodecs = (files: BridgeFiles): BridgeCodecs => {
 
 	return {
 		ini,
+		javaProperties,
 		json,
 		properties,
 		sourceCfg,

package/src/runtime/bridgeRegistry.ts

@@ -324,9 +324,7 @@ export const createRegistry = (
 				}
 
 				if (action === BridgeAction.Add && module.add) {
-					await module.add(context, asString(args, "input"));
-
-					return null;
+					return (await module.add(context, asString(args, "input"))) ?? null;
 				}
 
 				const rowAction = module.actions?.[action];