@serverkgg/bridge 0.0.11 → 0.0.13

package/src/catalogs/thunderstore.ts

@@ -0,0 +1,239 @@
+import type { BridgeContext } from "../context";
+import { BridgeFailureCode, BridgeFailureError, BridgeNetError } from "../core";
+
+export const THUNDERSTORE_API = "https://thunderstore.io";
+
+export const THUNDERSTORE_CDN = "https://gcdn.thunderstore.io";
+
+export const THUNDERSTORE_PAGE_SIZE = 20;
+
+const LISTING_CACHE_SECONDS = 60;
+
+const PACKAGE_CACHE_SECONDS = 600;
+
+const THROTTLED_STATUSES = [
+	429,
+	503,
+];
+
+export enum ThunderstoreSort {
+	LastUpdated = "last-updated",
+	MostDownloaded = "most-downloaded",
+	Newest = "newest",
+	TopRated = "top-rated",
+}
+
+export interface ThunderstoreCategory {
+	id: string;
+	name: string;
+	slug: string;
+}
+
+export interface ThunderstoreListing {
+	namespace: string;
+	name: string;
+	description: string;
+	icon_url: string | null;
+	download_count: number;
+	rating_count: number;
+	size: number;
+	last_updated: string | null;
+	datetime_created: string | null;
+	is_deprecated: boolean;
+	is_nsfw: boolean;
+	is_pinned: boolean;
+	categories: ThunderstoreCategory[];
+	community_identifier: string;
+}
+
+export interface ThunderstoreVersion {
+	namespace: string;
+	name: string;
+	version_number: string;
+	full_name: string;
+	description: string;
+	icon: string | null;
+	dependencies: string[];
+	download_url: string;
+	downloads: number;
+	date_created: string | null;
+	website_url: string | null;
+	is_active: boolean;
+}
+
+export interface ThunderstorePackage {
+	namespace: string;
+	name: string;
+	full_name: string;
+	owner: string;
+	package_url: string;
+	date_created: string | null;
+	date_updated: string | null;
+	rating_score: number;
+	is_pinned: boolean;
+	is_deprecated: boolean;
+	total_downloads: number;
+	latest: ThunderstoreVersion;
+}
+
+export interface ThunderstoreSearchQuery {
+	query?: string;
+	page?: number;
+	sort?: ThunderstoreSort;
+	includeDeprecated?: boolean;
+	includeNsfw?: boolean;
+}
+
+export interface ThunderstoreSearchPage {
+	count: number;
+	results: ThunderstoreListing[];
+	hasMore: boolean;
+}
+
+export interface ThunderstoreManifest {
+	name: string;
+	version_number: string;
+	website_url?: string;
+	description?: string;
+	dependencies: string[];
+}
+
+export interface ThunderstoreCatalogOptions {
+	community: string;
+}
+
+export interface ThunderstoreCatalog {
+	search(query?: ThunderstoreSearchQuery): Promise<ThunderstoreSearchPage>;
+	resolve(namespace: string, name: string): Promise<ThunderstorePackage>;
+	version(namespace: string, name: string, version: string): Promise<ThunderstoreVersion>;
+	download(version: ThunderstoreVersion): string;
+	dependencies(manifest: string): string[];
+}
+
+export const thunderstoreDownloadUrl = (fullName: string) => {
+	return `${THUNDERSTORE_CDN}/live/repository/packages/${encodeURIComponent(fullName)}.zip`;
+};
+
+export const parseThunderstoreManifest = (manifest: string): ThunderstoreManifest | null => {
+	try {
+		const parsed: unknown = JSON.parse(manifest);
+
+		if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+			return null;
+		}
+
+		const shape = parsed as Partial<ThunderstoreManifest>;
+
+		if (typeof shape.name !== "string" || typeof shape.version_number !== "string") {
+			return null;
+		}
+
+		return {
+			...shape,
+			name: shape.name,
+			version_number: shape.version_number,
+			dependencies: Array.isArray(shape.dependencies)
+				? shape.dependencies.filter((entry): entry is string => typeof entry === "string")
+				: [],
+		};
+	} catch {
+		return null;
+	}
+};
+
+export const thunderstoreDependency = (reference: string) => {
+	const parts = reference.split("-");
+	const version = parts.at(2);
+	const name = parts.at(1);
+	const namespace = parts.at(0);
+
+	if (parts.length !== 3 || !namespace || !name || !version) {
+		return null;
+	}
+
+	return {
+		namespace,
+		name,
+		version,
+		fullName: reference,
+	};
+};
+
+const listingQuery = (query: ThunderstoreSearchQuery) => {
+	const search = new URLSearchParams({
+		page: String(Math.max(query.page ?? 1, 1)),
+		deprecated: query.includeDeprecated === true ? "True" : "False",
+		nsfw: query.includeNsfw === true ? "True" : "False",
+		ordering: query.sort ?? ThunderstoreSort.MostDownloaded,
+	});
+
+	if (query.query !== undefined && query.query.length > 0) {
+		search.set("q", query.query);
+	}
+
+	return search.toString();
+};
+
+export const thunderstoreCatalog = (
+	context: BridgeContext,
+	options: ThunderstoreCatalogOptions,
+): ThunderstoreCatalog => {
+	const community = encodeURIComponent(options.community);
+
+	const request = async <Result>(url: string, cacheSeconds: number): Promise<Result> => {
+		try {
+			return await context.net.json<Result>(url, {
+				cacheSeconds,
+			});
+		} catch (error) {
+			if (error instanceof BridgeNetError && error.status !== null && THROTTLED_STATUSES.includes(error.status)) {
+				throw new BridgeFailureError(
+					BridgeFailureCode.CatalogRateLimited,
+					"thunderstore asked us to slow down, wait a moment and try again",
+				);
+			}
+
+			throw error;
+		}
+	};
+
+	return {
+		async search(query = {}) {
+			const page = await request<{
+				count: number;
+				next: string | null;
+				results: ThunderstoreListing[];
+			}>(`${THUNDERSTORE_API}/api/cyberstorm/listing/${community}/?${listingQuery(query)}`, LISTING_CACHE_SECONDS);
+
+			return {
+				count: page.count,
+				results: page.results,
+				hasMore: page.next !== null,
+			};
+		},
+
+		async resolve(namespace, name) {
+			return await request<ThunderstorePackage>(
+				`${THUNDERSTORE_API}/api/experimental/package/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/`,
+				PACKAGE_CACHE_SECONDS,
+			);
+		},
+
+		async version(namespace, name, version) {
+			return await request<ThunderstoreVersion>(
+				`${THUNDERSTORE_API}/api/experimental/package/${encodeURIComponent(namespace)}/${encodeURIComponent(
+					name,
+				)}/${encodeURIComponent(version)}/`,
+				PACKAGE_CACHE_SECONDS,
+			);
+		},
+
+		download(version) {
+			return thunderstoreDownloadUrl(version.full_name);
+		},
+
+		dependencies(manifest) {
+			return parseThunderstoreManifest(manifest)?.dependencies ?? [];
+		},
+	};
+};

package/src/cli/validate.ts

@@ -3,6 +3,7 @@ import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { parseArgs } from "node:util";
 import { z } from "zod";
+import { type ArticlePack, compileArticles } from "../blog";
 import { GuideOpenTab, type GuideOpenTarget, type GuidePack, readGuidePack, readGuidePackage } from "../guides";
 import {
 	declaredFiles,
@@ -131,6 +132,10 @@ const reportGuides = (pack: GuidePack | null) => {
 	}
 };
 
+const reportArticles = (pack: ArticlePack) => {
+	console.log(`  articles: ${pack.drafts.length} article(s), ${pack.images.length} image(s)`);
+};
+
 const validateGuidePackage = (source: PackageSource, document: GuidePackage) => {
 	const guideFiles = document.guides.flatMap((guide) => [
 		guide.bodyPath.ar,
@@ -144,9 +149,11 @@ const validateGuidePackage = (source: PackageSource, document: GuidePackage) =>
 	}
 
 	const pack = readGuidePackage(source, document);
+	const articles = compileArticles(source);
 
 	console.log(`${document.metadata.id} is valid`);
 	reportGuides(pack);
+	reportArticles(articles);
 };
 
 const ACTION_TARGET_BUDGET = 80;

package/src/codecs/index.ts

@@ -1,3 +1,6 @@
+export * from "./ini";
 export * from "./json";
 export * from "./properties";
+export * from "./sourceCfg";
 export * from "./ueIni";
+export * from "./xmlProperties";

package/src/codecs/ini.test.ts

@@ -0,0 +1,152 @@
+import { describe, expect, test } from "bun:test";
+import { mergeIni, parseIni } from "./ini";
+
+const SAMPLE = [
+	"; the server",
+	"[Server]",
+	"name=serverk",
+	"# a note",
+	"maxPlayers = 10",
+	"",
+	"[Admin]",
+	"password=secret",
+	"",
+].join("\n");
+
+describe("parseIni", () => {
+	test("reads the keys of one section", () => {
+		expect(parseIni(SAMPLE, "Server")).toEqual({
+			name: "serverk",
+			maxPlayers: "10",
+		});
+	});
+
+	test("reads another section without leaking keys", () => {
+		expect(parseIni(SAMPLE, "Admin")).toEqual({
+			password: "secret",
+		});
+	});
+
+	test("reads the keys before the first header when no section is asked for", () => {
+		expect(parseIni("welcome=hello\n[Server]\nname=x\n")).toEqual({
+			welcome: "hello",
+		});
+	});
+
+	test("keeps the last of a repeated key", () => {
+		expect(parseIni("[S]\nmod=a\nmod=b\n", "S")).toEqual({
+			mod: "b",
+		});
+	});
+
+	test("returns nothing for an unknown section", () => {
+		expect(parseIni(SAMPLE, "Nothing")).toEqual({});
+	});
+});
+
+describe("mergeIni", () => {
+	test("rewrites a value in place and keeps comments and order", () => {
+		expect(
+			mergeIni(
+				SAMPLE,
+				{
+					name: "بيتنا",
+				},
+				"Server",
+			),
+		).toBe(
+			[
+				"; the server",
+				"[Server]",
+				"name=بيتنا",
+				"# a note",
+				"maxPlayers = 10",
+				"",
+				"[Admin]",
+				"password=secret",
+				"",
+			].join("\n"),
+		);
+	});
+
+	test("appends an unknown key at the end of its section", () => {
+		expect(
+			mergeIni(
+				SAMPLE,
+				{
+					motd: "hi",
+				},
+				"Server",
+			),
+		).toBe(
+			[
+				"; the server",
+				"[Server]",
+				"name=serverk",
+				"# a note",
+				"maxPlayers = 10",
+				"motd=hi",
+				"[Admin]",
+				"password=secret",
+				"",
+			].join("\n"),
+		);
+	});
+
+	test("creates a section that does not exist yet", () => {
+		expect(
+			mergeIni(
+				"[Server]\nname=x\n",
+				{
+					level: "3",
+				},
+				"Game",
+			),
+		).toBe("[Server]\nname=x\n\n[Game]\nlevel=3\n");
+	});
+
+	test("drops repeated occurrences of a key it rewrites", () => {
+		expect(
+			mergeIni(
+				"[S]\nmod=a\nmod=b\nother=1\n",
+				{
+					mod: "c",
+				},
+				"S",
+			),
+		).toBe("[S]\nmod=c\nother=1\n");
+	});
+
+	test("writes into an empty file", () => {
+		expect(
+			mergeIni(
+				"",
+				{
+					name: "x",
+				},
+				"Server",
+			),
+		).toBe("[Server]\nname=x\n");
+	});
+
+	test("writes preamble keys when no section is asked for", () => {
+		expect(
+			mergeIni("welcome=hello\n[Server]\nname=x\n", {
+				welcome: "salam",
+				extra: "1",
+			}),
+		).toBe("welcome=salam\nextra=1\n[Server]\nname=x\n");
+	});
+
+	test("leaves other sections untouched", () => {
+		expect(
+			mergeIni(
+				"[A]\nkey=1\n[B]\nkey=2\n",
+				{
+					key: "9",
+				},
+				"B",
+			),
+		).toBe("[A]\nkey=1\n[B]\nkey=9\n");
+	});
+});

package/src/codecs/ini.ts

@@ -0,0 +1,158 @@
+const COMMENT_MARKERS = [
+	";",
+	"#",
+];
+
+const SEPARATOR = "=";
+
+const PREAMBLE = "";
+
+const isComment = (line: string) => {
+	const trimmed = line.trimStart();
+
+	return trimmed.length === 0 || COMMENT_MARKERS.some((marker) => trimmed.startsWith(marker));
+};
+
+const isSectionHeader = (line: string) => {
+	const trimmed = line.trim();
+
+	return trimmed.length > 2 && trimmed.startsWith("[") && trimmed.endsWith("]");
+};
+
+const sectionName = (line: string) => {
+	return line.trim().slice(1, -1).trim();
+};
+
+const entryKey = (line: string) => {
+	if (isComment(line) || isSectionHeader(line)) {
+		return null;
+	}
+
+	const separator = line.indexOf(SEPARATOR);
+
+	if (separator === -1) {
+		return null;
+	}
+
+	const key = line.slice(0, separator).trim();
+
+	return key.length > 0 ? key : null;
+};
+
+const entryValue = (line: string) => {
+	return line.slice(line.indexOf(SEPARATOR) + 1).trim();
+};
+
+const trimTrailingBlanks = (lines: string[]) => {
+	while (lines.length > 0 && (lines.at(-1) ?? "").trim().length === 0) {
+		lines.pop();
+	}
+};
+
+export const parseIni = (contents: string, section: string = PREAMBLE) => {
+	const values: Record<string, string> = {};
+
+	let current = PREAMBLE;
+
+	for (const line of contents.split("\n")) {
+		if (isSectionHeader(line)) {
+			current = sectionName(line);
+
+			continue;
+		}
+
+		if (current !== section) {
+			continue;
+		}
+
+		const key = entryKey(line);
+
+		if (key !== null) {
+			values[key] = entryValue(line);
+		}
+	}
+
+	return values;
+};
+
+export const mergeIni = (contents: string, values: Record<string, string>, section: string = PREAMBLE) => {
+	const pending = new Map(Object.entries(values));
+	const written = new Set<string>();
+	const lines = contents.length === 0 ? [] : contents.split("\n");
+	const output: string[] = [];
+
+	let current = PREAMBLE;
+	let inserted = false;
+
+	const appendPending = () => {
+		const missing = [
+			...pending,
+		].filter(([key]) => !written.has(key));
+
+		if (missing.length > 0) {
+			trimTrailingBlanks(output);
+
+			for (const [key, value] of missing) {
+				output.push(`${key}${SEPARATOR}${value}`);
+			}
+		}
+
+		inserted = true;
+	};
+
+	for (const line of lines) {
+		if (isSectionHeader(line)) {
+			if (current === section && !inserted) {
+				appendPending();
+			}
+
+			current = sectionName(line);
+			output.push(line);
+
+			continue;
+		}
+
+		if (current !== section) {
+			output.push(line);
+
+			continue;
+		}
+
+		const key = entryKey(line);
+
+		if (key === null || !pending.has(key)) {
+			output.push(line);
+
+			continue;
+		}
+
+		if (written.has(key)) {
+			continue;
+		}
+
+		written.add(key);
+		output.push(`${key}${SEPARATOR}${pending.get(key)}`);
+	}
+
+	if (current === section && !inserted) {
+		appendPending();
+	}
+
+	if (!inserted) {
+		trimTrailingBlanks(output);
+
+		if (output.length > 0) {
+			output.push("");
+		}
+
+		output.push(`[${section}]`);
+
+		for (const [key, value] of pending) {
+			output.push(`${key}${SEPARATOR}${value}`);
+		}
+	}
+
+	trimTrailingBlanks(output);
+
+	return `${output.join("\n")}\n`;
+};

package/src/codecs/sourceCfg.test.ts

@@ -0,0 +1,100 @@
+import { describe, expect, test } from "bun:test";
+import {
+	decodeSourceCfgValue,
+	encodeSourceCfgValue,
+	mergeSourceCfg,
+	parseSourceCfg,
+	readSourceCfgEntry,
+} from "./sourceCfg";
+
+describe("readSourceCfgEntry", () => {
+	test("splits a key from its value", () => {
+		expect(readSourceCfgEntry('hostname "serverk"')).toEqual({
+			key: "hostname",
+			value: '"serverk"',
+		});
+	});
+
+	test("accepts a key with no value", () => {
+		expect(readSourceCfgEntry("sv_lan")).toEqual({
+			key: "sv_lan",
+			value: "",
+		});
+	});
+
+	test("ignores comments and blank lines", () => {
+		expect(readSourceCfgEntry("// a comment")).toBeNull();
+		expect(readSourceCfgEntry("# a comment")).toBeNull();
+		expect(readSourceCfgEntry("   ")).toBeNull();
+		expect(readSourceCfgEntry('"quoted" 1')).toBeNull();
+	});
+});
+
+describe("decodeSourceCfgValue", () => {
+	test("unquotes a string and unescapes it", () => {
+		expect(decodeSourceCfgValue('"a \\"b\\" c"')).toBe('a "b" c');
+	});
+
+	test("reads booleans and numbers", () => {
+		expect(decodeSourceCfgValue("true")).toBe(true);
+		expect(decodeSourceCfgValue("false")).toBe(false);
+		expect(decodeSourceCfgValue("42")).toBe(42);
+		expect(decodeSourceCfgValue("-1.5")).toBe(-1.5);
+	});
+
+	test("leaves a bare word alone", () => {
+		expect(decodeSourceCfgValue("de_dust2")).toBe("de_dust2");
+	});
+});
+
+describe("encodeSourceCfgValue", () => {
+	test("quotes and escapes text", () => {
+		expect(encodeSourceCfgValue('a "b"')).toBe('"a \\"b\\""');
+	});
+
+	test("flattens newlines", () => {
+		expect(encodeSourceCfgValue("a\nb")).toBe('"a b"');
+	});
+
+	test("writes booleans and numbers bare", () => {
+		expect(encodeSourceCfgValue(true)).toBe("true");
+		expect(encodeSourceCfgValue(7)).toBe("7");
+		expect(encodeSourceCfgValue(null)).toBe('""');
+	});
+});
+
+describe("parseSourceCfg", () => {
+	test("reads a source cfg file", () => {
+		expect(parseSourceCfg('// header\nhostname "serverk"\nsv_maxplayers 24\nsv_cheats false\n')).toEqual({
+			hostname: "serverk",
+			sv_maxplayers: 24,
+			sv_cheats: false,
+		});
+	});
+});
+
+describe("mergeSourceCfg", () => {
+	test("rewrites a value and keeps the comments", () => {
+		expect(
+			mergeSourceCfg('// header\nhostname "old"\nsv_maxplayers 24\n', {
+				hostname: "new",
+			}),
+		).toBe('// header\nhostname "new"\nsv_maxplayers 24\n');
+	});
+
+	test("appends an unknown key", () => {
+		expect(
+			mergeSourceCfg('hostname "x"\n', {
+				rcon_password: "abc",
+			}),
+		).toBe('hostname "x"\nrcon_password "abc"\n');
+	});
+
+	test("collapses a repeated key it rewrites", () => {
+		expect(
+			mergeSourceCfg("map de_dust2\nmap de_nuke\n", {
+				map: "de_inferno",
+			}),
+		).toBe('map "de_inferno"\n');
+	});
+});