@rithien/comfy_adapter 0.1.0

package/README.md

@@ -0,0 +1,49 @@
+# `@rithien/comfy_adapter` — clusterio plugin
+
+Adapter między tag-stream stdout scenariusza `factorio-polska` (`../scenario/`) a clusterio bus + Discord (przez współistniejący `../discord-bridge/`).
+
+## Stan
+
+**Faza 2.5 ukończona (statyczna walidacja)** — `v0.1.0` zaimplementowane, nieopublikowane. Publish + runtime test na zdalnym clusterio → Faza 2.7.
+
+## Zakres
+
+| Tag z scenariusza | Akcja w plugin'ie |
+| --- | --- |
+| `[DISCORD]<msg>` / `[-RAW]` / `[-BOLD]` | `channel.send({content})` na kanał instancji (przez `discord_bridge.getChannelForInstance`) |
+| `[DISCORD-ADMIN]<msg>` / `[-RAW]` | jak wyżej, z prefiksem `[ADMIN] ` (configurable) |
+| `[DISCORD-EMBED]<msg>` / `[-RAW]` | embed z `description=msg` |
+| `[DISCORD-EMBED-PARSED]<json>` | JSON.parse → embed z `{title, description, color?, fields?}` |
+| `[DISCORD-ADMIN-EMBED]<msg>` / `[-RAW]` | embed z `description=admin_prefix+msg` |
+| `[ANTIGRIEF-LOG]{category, action}` | embed z color-coded category (lub plain `[ANTIGRIEF: cat] action` jeśli `antigrief_log_as_embed=false`) |
+| `[DATA-SET]{data_set, key, value?}` | UPSERT do JSON storage (debounce fsync). `value=nil` → DELETE |
+| `[DATA-GET]<token>{data_set, key}` | Read JSON, RCON callback `/cc Token.get(<token>)(d); Server.raise_data_set(d)` (dual-path) |
+| `[DATA-GET-AND-PRINT]<token>{...,to_print}` | jak wyżej + `to_print` w callback data |
+| `[DATA-GET-ALL]<token>{data_set}` | Read whole dataset, RCON callback z `entries` table |
+
+Pozostałe tagi (`[BAN-SYNC]`, `[PING]`, `[START-SCENARIO]`) — silent skip (bany robi clusterio natywnie, lifecycle nieużywany).
+
+## Architektura
+
+- **`info.js`** — manifest + schema 4 eventów instance→controller (`ScenarioDiscordEvent`, `AntigriefLogEvent`, `DataSetEvent`, `DataGetRequest`) + controller config fields.
+- **`instance.js`** — hook `onOutput`, regex tag-stream parser, mini-parser pseudo-Lua-JSON (`parseComfyPayload`), message queue dla disconnected controller.
+- **`controller.js`** — 4 handlery + Discord client sharing (delegacja do `discord_bridge`) + JSON storage manager (atomic write, debounce, load on init).
+- **Storage:** pojedynczy plik JSON (`comfy_adapter_storage.json` configurable), schema `{ "<dataset>": { "<key>": <value> } }`.
+
+## Config (controller-side)
+
+| Klucz | Default | Opis |
+|---|---|---|
+| `comfy_adapter.storage_path` | `comfy_adapter_storage.json` | Plik JSON datastore (relative do CWD kontrolera) |
+| `comfy_adapter.write_debounce_ms` | `1000` | Coalesce multiple [DATA-SET] writes |
+| `comfy_adapter.antigrief_log_as_embed` | `true` | Embed vs plain message dla anti-grief log |
+| `comfy_adapter.admin_prefix` | `[ADMIN] ` | Prefix dla [DISCORD-ADMIN*] tagów |
+
+## Zależności runtime
+
+- **`@rithien/discord_bridge`** (Faza 1, `^0.3.1`) — channel routing per instancja + shared Discord client. Bez niego: Discord eventy są no-op (log verbose), datastore nadal działa.
+- **`clusterio` alpha 14+** — API hooks `onOutput`, `controller.handle`, `controller.plugins.get`, `InstanceSendRconRequest`.
+
+## Pełna spec
+
+Szczegóły w [`../PLAN.md`](../PLAN.md) sekcja "Faza 2.5". Architektoniczne decyzje w [`../DECISIONS.md`](../DECISIONS.md) (search "Faza 2.5").

package/controller.js

@@ -0,0 +1,453 @@
+"use strict";
+// factorio-polska / comfy_adapter — controller plugin (Faza 2.5).
+//
+// 4 handlery eventów (wszystkie instance→controller):
+//   ScenarioDiscordEvent  → Discord channel instancji (przez discord_bridge.getChannelForInstance)
+//   AntigriefLogEvent     → Discord embed (lub plain) na tym samym kanale
+//   DataSetEvent          → upsert do JSON storage (debounced fs flush)
+//   DataGetRequest        → read JSON + RCON callback `/cc local d={...}; require(...).get(<token>)(d); ...`
+//
+// Discord client sharing (decyzja [PLAN.md Faza 2.5 punkt 5, opcja B]):
+//   Reuse client z `@rithien/discord_bridge` (kontroler trzyma jeden Discord login).
+//   Dostęp: `this.controller.plugins.get("discord_bridge")?.client`.
+//   Fallback: jeśli discord_bridge nie zainstalowany / nie zalogowany → log warn,
+//   Discord eventy są no-op (datastore nadal działa).
+//
+// Storage:
+//   Schema: `{ "<dataset>": { "<key>": <value>, ... }, ... }`.
+//   Atomic write: tmp file + rename. Debounce: kombinuje multiple SET w jednym fsync.
+//   Read on init (load existing or {}).
+//
+// Callback resolver (decyzja [PLAN.md Faza 2.6 punkt 3]):
+//   Każdy DATA-GET response wywołuje BOTH `Token.get(<token>)(data)` ORAZ
+//   `Server.raise_data_set(data)`. Powód: scenariusz (sessions.lua) używa obu paths
+//   — Token-based per-request closures (logika seed/upload), oraz registered
+//   on_data_set_changed handlers (broadcast subscribers). Redundancja jest bezpieczna
+//   (handlers są idempotentne).
+
+const fs = require("fs/promises");
+const path = require("path");
+const { BaseControllerPlugin } = require("@clusterio/controller");
+
+const {
+	ScenarioDiscordEvent,
+	AntigriefLogEvent,
+	DataSetEvent,
+	DataGetRequest,
+} = require("./info.js");
+
+
+// Mapa kategorii anti-grief → kolor embed Discord (decimal RGB).
+const ANTIGRIEF_COLORS = {
+	landfill: 0x3b88c3,         // niebieski (water tile)
+	capsule: 0xffcc00,           // żółty (capsule warning)
+	friendly_fire: 0xff6b00,     // pomarańczowy
+	mining: 0xff3b30,            // czerwony (anti-grief mining)
+	whitelist_mining: 0xff9500,  // jasno-pomarańczowy
+	corpse: 0x8e44ad,            // fioletowy (loot)
+	whisper: 0x95a5a6,           // szary (whisper log)
+	cancel_crafting: 0xff2d55,   // różowy (exploit cancel-craft)
+	deconstruct: 0xc0392b,       // ciemno-czerwony (mass decon)
+	scenario: 0x2c3e50,          // grafit (scenario events)
+	default: 0x7f8c8d,           // jasny szary fallback
+};
+
+
+/**
+ * Escapuje Lua-string dla wstawki w `/cc` RCON command:
+ *   "abc"     →  'abc'  (no special chars)
+ *   `it's`    →  'it\'s'
+ *   `a\nb`    →  'a\nb' (preserve, but no actual newline in RCON line)
+ */
+function luaString(s) {
+	if (s === null || s === undefined) return "nil";
+	const escaped = String(s)
+		.replace(/\\/g, "\\\\")
+		.replace(/'/g, "\\'")
+		.replace(/\n/g, "\\n")
+		.replace(/\r/g, "\\r");
+	return `'${escaped}'`;
+}
+
+/**
+ * Konwertuje wartość JS na literalną reprezentację Lua (do wstawki w `/cc`).
+ */
+function luaLiteral(v) {
+	if (v === null || v === undefined) return "nil";
+	if (typeof v === "boolean") return v ? "true" : "false";
+	if (typeof v === "number") return Number.isFinite(v) ? String(v) : "nil";
+	if (typeof v === "string") return luaString(v);
+	if (Array.isArray(v) || typeof v === "object") {
+		const parts = [];
+		if (Array.isArray(v)) {
+			for (const item of v) parts.push(luaLiteral(item));
+		} else {
+			for (const [k, val] of Object.entries(v)) {
+				const keyExpr = /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(k) ? k : `[${luaString(k)}]`;
+				parts.push(`${keyExpr}=${luaLiteral(val)}`);
+			}
+		}
+		return `{${parts.join(",")}}`;
+	}
+	return "nil"; // fallback (np. function, symbol)
+}
+
+
+class ControllerPlugin extends BaseControllerPlugin {
+	async init() {
+		this.storage = {};
+		this.writePending = false;
+		this.writeTimer = null;
+		this.writeInflight = null;
+
+		this.controller.handle(ScenarioDiscordEvent, this.handleScenarioDiscord.bind(this));
+		this.controller.handle(AntigriefLogEvent, this.handleAntigriefLog.bind(this));
+		this.controller.handle(DataSetEvent, this.handleDataSet.bind(this));
+		this.controller.handle(DataGetRequest, this.handleDataGetRequest.bind(this));
+
+		await this.loadStorage();
+	}
+
+	async onShutdown() {
+		if (this.writeTimer) {
+			clearTimeout(this.writeTimer);
+			this.writeTimer = null;
+		}
+		if (this.writePending) {
+			await this.flushStorage();
+		}
+		if (this.writeInflight) {
+			await this.writeInflight.catch(() => {}); // best-effort
+		}
+	}
+
+	// =========================================================================
+	// Discord client access (delegated to discord_bridge)
+	// =========================================================================
+
+	getDiscordBridge() {
+		const dbPlugin = this.controller.plugins?.get("discord_bridge");
+		if (!dbPlugin) return null;
+		if (!dbPlugin.client) return null;
+		return dbPlugin;
+	}
+
+	getChannelForInstance(instanceId) {
+		const dbPlugin = this.getDiscordBridge();
+		if (!dbPlugin) return null;
+		const instance = this.controller.instances.get(instanceId);
+		if (!instance) return null;
+		// discord_bridge controller eksportuje getChannelForInstance(instance).
+		if (typeof dbPlugin.getChannelForInstance === "function") {
+			return dbPlugin.getChannelForInstance(instance);
+		}
+		return dbPlugin.fallbackChannel ?? null;
+	}
+
+	// =========================================================================
+	// Discord event handlers
+	// =========================================================================
+
+	async handleScenarioDiscord(event, src) {
+		const channel = this.getChannelForInstance(src.id);
+		if (!channel) {
+			this.logger.verbose(`comfy_adapter: no Discord channel for instance ${src.id}, dropping ${event.variant}`);
+			return;
+		}
+
+		const adminPrefix = this.controller.config.get("comfy_adapter.admin_prefix") || "";
+		const variant = event.variant;
+		const content = event.content ?? "";
+
+		try {
+			if (variant === "DISCORD-EMBED-PARSED") {
+				let embedData;
+				try {
+					embedData = JSON.parse(content);
+				} catch (err) {
+					this.logger.warn(`comfy_adapter: DISCORD-EMBED-PARSED has invalid JSON: ${err.message}`);
+					return;
+				}
+				await channel.send({ embeds: [this.buildEmbedFromParsed(embedData)] });
+			} else if (variant === "DISCORD-EMBED" || variant === "DISCORD-EMBED-RAW") {
+				await channel.send({ embeds: [{ description: content }] });
+			} else if (variant === "DISCORD-ADMIN-EMBED" || variant === "DISCORD-ADMIN-EMBED-RAW") {
+				await channel.send({ embeds: [{ description: adminPrefix + content }] });
+			} else if (variant === "DISCORD-ADMIN" || variant === "DISCORD-ADMIN-RAW") {
+				await channel.send({ content: adminPrefix + content, allowedMentions: { parse: [] } });
+			} else if (variant === "DISCORD-BOLD") {
+				await channel.send({ content: `**${content}**`, allowedMentions: { parse: [] } });
+			} else {
+				// DISCORD, DISCORD-RAW
+				await channel.send({ content, allowedMentions: { parse: [] } });
+			}
+		} catch (err) {
+			this.logger.error(`comfy_adapter: Discord send failed for ${variant}: ${err.message}`);
+		}
+	}
+
+	buildEmbedFromParsed(data) {
+		const embed = {};
+		if (data.title) embed.title = String(data.title);
+		if (data.description) embed.description = String(data.description);
+		if (data.color !== undefined) embed.color = Number(data.color);
+		if (Array.isArray(data.fields)) {
+			embed.fields = data.fields.map(f => ({
+				name: String(f.name ?? "—"),
+				value: String(f.value ?? "—"),
+				inline: !!f.inline,
+			}));
+		}
+		return embed;
+	}
+
+	async handleAntigriefLog(event, src) {
+		const channel = this.getChannelForInstance(src.id);
+		if (!channel) return;
+
+		const asEmbed = this.controller.config.get("comfy_adapter.antigrief_log_as_embed");
+		try {
+			if (asEmbed) {
+				const color = ANTIGRIEF_COLORS[event.category] ?? ANTIGRIEF_COLORS.default;
+				await channel.send({
+					embeds: [{
+						title: `Antigrief: ${event.category}`,
+						description: event.action || "—",
+						color,
+					}],
+				});
+			} else {
+				await channel.send({
+					content: `[ANTIGRIEF: ${event.category}] ${event.action}`,
+					allowedMentions: { parse: [] },
+				});
+			}
+		} catch (err) {
+			this.logger.error(`comfy_adapter: Discord send failed for antigrief ${event.category}: ${err.message}`);
+		}
+	}
+
+	// =========================================================================
+	// Datastore: JSON file persistence
+	// =========================================================================
+
+	getStoragePath() {
+		const configured = this.controller.config.get("comfy_adapter.storage_path") || "comfy_adapter_storage.json";
+		return path.isAbsolute(configured) ? configured : path.resolve(process.cwd(), configured);
+	}
+
+	async loadStorage() {
+		const file = this.getStoragePath();
+		try {
+			const raw = await fs.readFile(file, "utf8");
+			this.storage = JSON.parse(raw);
+			if (typeof this.storage !== "object" || this.storage === null || Array.isArray(this.storage)) {
+				this.logger.warn(`comfy_adapter: storage at ${file} is not an object, resetting to {}`);
+				this.storage = {};
+			}
+			this.logger.info(`comfy_adapter: loaded storage from ${file} (${Object.keys(this.storage).length} datasets)`);
+		} catch (err) {
+			if (err.code === "ENOENT") {
+				this.logger.info(`comfy_adapter: no storage file at ${file}, starting empty`);
+				this.storage = {};
+			} else {
+				this.logger.error(`comfy_adapter: failed to load storage at ${file}: ${err.message}; starting empty`);
+				this.storage = {};
+			}
+		}
+	}
+
+	scheduleFlush() {
+		if (this.writePending) return;
+		this.writePending = true;
+		const debounce = Number(this.controller.config.get("comfy_adapter.write_debounce_ms")) || 1000;
+		this.writeTimer = setTimeout(() => {
+			this.writeTimer = null;
+			this.flushStorage().catch(err => {
+				this.logger.error(`comfy_adapter: storage flush failed: ${err.message}`);
+			});
+		}, debounce);
+	}
+
+	async flushStorage() {
+		if (!this.writePending) return;
+		this.writePending = false;
+
+		// Czekaj na poprzedni in-flight write (atomicity z perspektywy callera).
+		if (this.writeInflight) {
+			try { await this.writeInflight; } catch (_) { /* swallow, fresh try */ }
+		}
+
+		const file = this.getStoragePath();
+		const tmp = `${file}.tmp`;
+		const snapshot = JSON.stringify(this.storage, null, 2);
+
+		this.writeInflight = (async () => {
+			await fs.mkdir(path.dirname(file), { recursive: true });
+			await fs.writeFile(tmp, snapshot, "utf8");
+			await fs.rename(tmp, file);
+		})();
+		try {
+			await this.writeInflight;
+		} finally {
+			this.writeInflight = null;
+		}
+	}
+
+	async handleDataSet(event, src) {
+		const ds = event.dataSet;
+		const key = event.key;
+		if (!ds || !key) return;
+
+		if (!this.storage[ds]) this.storage[ds] = {};
+		if (event.value === null || event.value === undefined) {
+			delete this.storage[ds][key];
+		} else {
+			this.storage[ds][key] = event.value;
+		}
+		this.scheduleFlush();
+
+		// Cross-instance broadcast (Faza 2.6): propaguj zmianę do innych instancji.
+		// Powód: scenariusz instance A właśnie zaktualizował sessions[player] — instance B
+		// (z tym samym scenariuszem) nie wie o tym aż do następnego DATA-GET przy on_player_joined.
+		// Broadcast tworzy eventually-consistent storage.sessions w obrębie wszystkich instancji,
+		// co umożliwia natychmiastową propagację trust (player trusted na A → trusted na B teraz).
+		if (this.shouldBroadcast(ds)) {
+			this.broadcastDataSet(src.id, ds, key, event.value).catch(err => {
+				this.logger.error(`comfy_adapter: broadcast failed for ${ds}/${key}: ${err.message}`);
+			});
+		}
+	}
+
+	shouldBroadcast(dataSet) {
+		const raw = this.controller.config.get("comfy_adapter.broadcast_data_sets") || "";
+		if (!raw.trim()) return false;
+		const allowed = raw.split(",").map(s => s.trim()).filter(Boolean);
+		return allowed.includes(dataSet);
+	}
+
+	async broadcastDataSet(sourceInstanceId, dataSet, key, value) {
+		// Buduje pojedyncze /cc per instancja docelowa. Tylko raise_data_set
+		// (nie Token.get — żaden token nie został wygenerowany dla tego data set u odbiorcy).
+		const fields = [`data_set=${luaString(dataSet)}`, `key=${luaString(key)}`];
+		if (value !== null && value !== undefined) {
+			fields.push(`value=${luaLiteral(value)}`);
+		}
+		const data = `{${fields.join(",")}}`;
+		const cmd =
+			`/cc local d=${data} ` +
+			`local ok,err=pcall(function() require('lib.server').raise_data_set(d) end) ` +
+			`if not ok then log('[comfy_adapter broadcast] '..tostring(err)) end`;
+
+		const targets = [];
+		for (const instance of this.controller.instances.values()) {
+			if (instance.id === sourceInstanceId) continue;
+			if (instance.status !== "running") continue;
+			targets.push(instance.id);
+		}
+		if (targets.length === 0) return;
+
+		await Promise.allSettled(targets.map(id => this.sendRcon(id, cmd)));
+	}
+
+	async handleDataGetRequest(event, src) {
+		const ds = event.dataSet;
+		const dataset = this.storage[ds] || {};
+
+		let responseLua;
+		if (event.mode === "get") {
+			const value = dataset[event.key] ?? null;
+			responseLua = this.buildSingleCallback(event.token, ds, event.key, value);
+		} else if (event.mode === "get_and_print") {
+			const value = dataset[event.key] ?? null;
+			// Print do gracza realizowany w callback Lua-side (try_get_data_and_print_token) —
+			// my dostarczamy tylko data; ten sam wzór co `get`.
+			responseLua = this.buildSingleCallback(event.token, ds, event.key, value, event.toPrint);
+		} else if (event.mode === "get_all") {
+			responseLua = this.buildAllCallback(event.token, ds, dataset);
+		} else {
+			this.logger.warn(`comfy_adapter: unknown DATA-GET mode "${event.mode}"`);
+			return;
+		}
+
+		await this.sendRcon(event.instanceId, responseLua);
+	}
+
+	/**
+	 * Buduje `/cc local d={...}; require('lib.token').get(<token>)(d); require('lib.server').raise_data_set(d)`.
+	 * Oba paths są wywoływane: per-request closure (Token) i broadcast (raise_data_set).
+	 */
+	buildSingleCallback(token, dataSet, key, value, toPrint = null) {
+		const fields = [
+			`data_set=${luaString(dataSet)}`,
+			`key=${luaString(key)}`,
+		];
+		if (value !== null && value !== undefined) {
+			fields.push(`value=${luaLiteral(value)}`);
+		}
+		if (toPrint) {
+			fields.push(`to_print=${luaString(toPrint)}`);
+		}
+		const data = `{${fields.join(",")}}`;
+		return (
+			`/cc local d=${data} ` +
+			`local ok1,err1=pcall(function() require('lib.token').get(${token})(d) end) ` +
+			`local ok2,err2=pcall(function() require('lib.server').raise_data_set(d) end) ` +
+			`if not ok1 then log('[comfy_adapter Token callback] '..tostring(err1)) end ` +
+			`if not ok2 then log('[comfy_adapter raise_data_set] '..tostring(err2)) end`
+		);
+	}
+
+	/**
+	 * DATA-GET-ALL response: pojedyncze callback z `entries` jako tabela {key=value,...}.
+	 * Format kompatybilny z Comfy try_get_all_data callback signature.
+	 */
+	buildAllCallback(token, dataSet, dataset) {
+		const data = `{data_set=${luaString(dataSet)},entries=${luaLiteral(dataset)}}`;
+		return (
+			`/cc local d=${data} ` +
+			`local ok,err=pcall(function() require('lib.token').get(${token})(d) end) ` +
+			`if not ok then log('[comfy_adapter Token all callback] '..tostring(err)) end`
+		);
+	}
+
+	async sendRcon(instanceId, command) {
+		const instance = this.controller.instances.get(instanceId);
+		if (!instance) {
+			this.logger.warn(`comfy_adapter: instance ${instanceId} not found for RCON`);
+			return;
+		}
+		const hostId = instance.config.get("instance.assigned_host");
+		if (hostId === null || hostId === undefined) {
+			this.logger.warn(`comfy_adapter: instance ${instanceId} has no assigned host`);
+			return;
+		}
+		try {
+			// Clusterio API: controller wysyła RCON przez host (sendRconCommandRequest lub przez plugin API).
+			// W alpha 14 jest helper this.controller.sendTo({instanceId}, new RawRconCommandRequest(command)).
+			// Tu trzymamy minimalne API zewnętrzne — jeśli interfejs się zmieni, ten miejsce do aktualizacji.
+			const hostConn = this.controller.wsServer?.hostConnections?.get(hostId);
+			if (!hostConn) {
+				this.logger.warn(`comfy_adapter: host ${hostId} not connected for instance ${instanceId}`);
+				return;
+			}
+			// Lazy require — RawRconCommandRequest jest standardowym lib API.
+			const lib = require("@clusterio/lib");
+			const Req = lib.InstanceSendRconRequest ?? lib.SendRconRequest ?? null;
+			if (!Req) {
+				this.logger.error("comfy_adapter: clusterio lib does not export RCON request class — RCON disabled");
+				return;
+			}
+			await this.controller.sendTo({ instanceId }, new Req(command));
+		} catch (err) {
+			this.logger.error(`comfy_adapter: RCON send failed for instance ${instanceId}: ${err.message}`);
+		}
+	}
+}
+
+module.exports = {
+	ControllerPlugin,
+	// Helpers exported dla unit testów (przyszłość).
+	_luaLiteral: luaLiteral,
+	_luaString: luaString,
+};

package/dist/web/manifest.json

@@ -0,0 +1,6 @@
+{
+  "main.js": "static/main.761df12d5815fb8e02fa.js",
+  "comfy_adapter.js": "static/comfy_adapter.1ca70d5b170a77bb6963.js",
+  "static/info_js.js": "static/info_js.9ad5f016be3454c1a255.js",
+  "static/package_json.js": "static/package_json.b88ad27d58c1784bb20f.js"
+}