@serverkgg/bridge 0.0.17 → 0.0.19

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@serverkgg/bridge",
-	"version": "0.0.17",
+	"version": "0.0.19",
 	"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/core/bridgeValue.test.ts

@@ -1,4 +1,5 @@
 import { describe, expect, test } from "bun:test";
+import type { BridgeRow } from "./bridgeValue";
 import { isLocalizedText } from "./bridgeValue";
 
 describe("isLocalizedText", () => {
@@ -27,3 +28,20 @@ describe("isLocalizedText", () => {
 		).toBe(false);
 	});
 });
+
+describe("BridgeRow", () => {
+	test('carries a localized cell beside its scalars so a driver never writes "English / عربي" into one string', () => {
+		const row: BridgeRow = {
+			id: "u-1",
+			kills: 12,
+			banned: false,
+			status: {
+				ar: "متصل",
+				en: "Online",
+			},
+		};
+
+		expect(isLocalizedText(row.status)).toBe(true);
+		expect(isLocalizedText(row.kills)).toBe(false);
+	});
+});

package/src/core/bridgeValue.ts

@@ -2,15 +2,19 @@ export type BridgeValue = boolean | number | string | null;
 
 export type BridgeValues = Record<string, BridgeValue>;
 
-export type BridgeRow = BridgeValues & {
-	id: string;
-};
-
 export interface LocalizedText {
 	ar: string;
 	en: string;
 }
 
+export type BridgeCell = BridgeValue | LocalizedText;
+
+export type BridgeCells = Record<string, BridgeCell>;
+
+export type BridgeRow = BridgeCells & {
+	id: string;
+};
+
 export type BridgeCopy = LocalizedText | string;
 
 export const isLocalizedText = (value: unknown): value is LocalizedText => {

package/src/modules/bridge.ts

@@ -1,5 +1,7 @@
 import type { BridgeContext, BridgeExecResult, BridgeFileEntry, BridgeReply } from "../context";
 import type {
+	BridgeCell,
+	BridgeCells,
 	BridgeCopy,
 	BridgeInstallHold,
 	BridgeInstallOutcome,
@@ -11,6 +13,7 @@ import type {
 } from "../core";
 import { BridgeUserError } from "../core";
 import type {
+	BridgeAddOutcome,
 	BridgeDetail,
 	BridgeDetailBadge,
 	BridgeDetailLink,
@@ -72,6 +75,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;
@@ -81,6 +85,8 @@ export namespace Bridge {
 	export type CatalogPage = BridgeCatalogPage;
 	export type CatalogProvider = BridgeCatalogProvider;
 	export type CatalogQuery = BridgeCatalogQuery;
+	export type Cell = BridgeCell;
+	export type Cells = BridgeCells;
 	export type Collection<Row extends BridgeRow = BridgeRow> = BridgeCollectionModule<Row>;
 	export type Context = BridgeContext;
 	export type Copy = BridgeCopy;

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/rcon/rconAccess.test.ts

@@ -286,6 +286,35 @@ describe("rconAccessSections", () => {
 		expect(detail.empty).toBeDefined();
 	});
 
+	test("the two sections carry different titles so the panel never repeats a heading", () => {
+		const [form, detail] = rconAccessSections();
+
+		expect(form?.title).toEqual({
+			ar: "الوصول عن بُعد",
+			en: "Remote access",
+		});
+		expect(detail?.title).toEqual({
+			ar: "بيانات الوصول عن بُعد",
+			en: "Remote access details",
+		});
+		expect(detail?.title).not.toEqual(form?.title);
+	});
+
+	test("the detail is visible only while remote access is on", () => {
+		const [, detail] = rconAccessSections();
+
+		if (detail?.layout !== BridgeLayout.Detail) {
+			throw new Error("the second section is the detail");
+		}
+
+		expect(detail.visibleWhen).toEqual({
+			variable: RCON_ACCESS_VARIABLE,
+			values: [
+				"true",
+			],
+		});
+	});
+
 	test("a dedicated port opens a port and a shared one only turns access on", () => {
 		const [dedicated] = rconAccessSections({
 			portKey: RCON_ACCESS_PORT,

package/src/rcon/rconAccess.ts

@@ -49,6 +49,11 @@ const ACCESS_TITLE: LocalizedText = {
 	en: "Remote access",
 };
 
+const ACCESS_DETAIL_TITLE: LocalizedText = {
+	ar: "بيانات الوصول عن بُعد",
+	en: "Remote access details",
+};
+
 const ACCESS_DESCRIPTION: LocalizedText = {
 	ar: "الوصول عن بُعد يخلي أداة خارجية تتحكم بسيرفرك بكلمة المرور هذي. الكلمة تمشي على النت بدون تشفير، فاقفل الوصول لما ما فيه أداة تستخدمه، ولا تعطي الكلمة أحد. لو تسربت غيّرها على طول.",
 	en: "Remote access lets an external tool control your server with this password. The password crosses the internet in the clear, so turn remote access off when no tool is using it, and never share the password. Rotate it the moment it leaks.",
@@ -235,7 +240,7 @@ export const rconAccessSections = (options: RconAccessSectionsOptions = {}): Bri
 		{
 			layout: BridgeLayout.Detail,
 			id: DETAIL_SECTION_ID,
-			title: ACCESS_TITLE,
+			title: ACCESS_DETAIL_TITLE,
 			module: RCON_ACCESS_MODULE,
 			actions: [
 				{
@@ -255,6 +260,12 @@ export const rconAccessSections = (options: RconAccessSectionsOptions = {}): Bri
 				ar: "شغّل سيرفرك مرة عشان تتولد كلمة المرور.",
 				en: "Start your server once to generate the password.",
 			},
+			visibleWhen: {
+				variable: RCON_ACCESS_VARIABLE,
+				values: [
+					"true",
+				],
+			},
 		},
 	];
 };

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];

package/src/wire/panel.test.ts

@@ -15,7 +15,7 @@ import {
 	BridgeSetupStepKind,
 	BridgeUploadMode,
 } from "@serverkgg/bridge/protocol";
-import { bridgeManifestSchema } from "./panel";
+import { bridgeCellsSchema, bridgeManifestSchema } from "./panel";
 
 const text = (value: string) => ({
 	ar: value,
@@ -683,3 +683,37 @@ describe("the placement mirror", () => {
 		expect(bridgeManifestSchema.parse(source)).toEqual(source);
 	});
 });
+
+describe("the cell schema", () => {
+	test("accepts a scalar and a localized cell", () => {
+		expect(
+			bridgeCellsSchema.parse({
+				id: "u-1",
+				kills: 12,
+				banned: false,
+				status: {
+					ar: "متصل",
+					en: "Online",
+				},
+			}),
+		).toEqual({
+			id: "u-1",
+			kills: 12,
+			banned: false,
+			status: {
+				ar: "متصل",
+				en: "Online",
+			},
+		});
+	});
+
+	test("rejects a cell that carries only one language", () => {
+		expect(
+			bridgeCellsSchema.safeParse({
+				status: {
+					ar: "متصل",
+				},
+			}).success,
+		).toBe(false);
+	});
+});

package/src/wire/panel.ts

@@ -68,6 +68,17 @@ export const panelTextSchema = z.object({
 	en: z.string().min(1).max(PANEL_TEXT_LENGTH_LIMIT),
 });
 
+export const bridgeCellSchema = z.union([
+	bridgeValueSchema,
+	panelTextSchema,
+]);
+
+export type BridgeCellInput = z.infer<typeof bridgeCellSchema>;
+
+export const bridgeCellsSchema = z.record(zKey, bridgeCellSchema);
+
+export type BridgeCellsInput = z.infer<typeof bridgeCellsSchema>;
+
 export const bridgeOptionSchema = z.object({
 	value: z.string().min(1).max(128),
 	label: panelTextSchema,