From b6bc11829738e34e6d39a659ba43a19ee1918ce4 Mon Sep 17 00:00:00 2001 From: ILLISIS Date: Sat, 14 Nov 2026 13:20:31 +1100 Subject: [PATCH 01/20] Download at the next join when the controller did not store an upload The controller gave an upload it did not store the same empty reply as one it stored, and the instance confirmed either to the save. An instance restarting after a crash uploads the players it had online, and when another instance had since uploaded the same generation the save took its own copy for the stored one: the next join kept it, and the leave after that stored it over the newer data. The reply now says whether the upload was stored. One that was not marks the save's copy outdated, so it is not uploaded again and the next join downloads. Fixes #1218 Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01JyNnVzRW4jPWaoWTxCyhM7 --- plugins/player_sync/README.md | 2 +- plugins/player_sync/controller.ts | 1 + plugins/player_sync/instance.ts | 9 ++++--- plugins/player_sync/messages.ts | 17 +++++++++++++ plugins/player_sync/module/player_sync.lua | 28 +++++++++++++++++++++- plugins/player_sync/test/controller.js | 12 ++++++++++ plugins/player_sync/test/instance.js | 21 +++++++++++++++- 7 files changed, 84 insertions(+), 6 deletions(-) diff --git a/plugins/player_sync/README.md b/plugins/player_sync/README.md index d148f834..4dd28f8a 100644 --- a/plugins/player_sync/README.md +++ b/plugins/player_sync/README.md @@ -6,7 +6,7 @@ As a player, it mostly just works. Most important to know is that factorio data A note on crashing servers: -When a server crashes while you are online there won't be time to immediately upload the inventory. Instead, the inventory is uploaded as soon as the server restarts. This means if you have been playing on a different server from the one that crashed and gathered/consumed items but are offline at the time of the first server coming online again your inventory will reset to the autosave. +When a server crashes while you are online there won't be time to immediately upload the inventory. Instead, the inventory is uploaded as soon as the server restarts. If you have been playing on a different server in the meantime the controller keeps what that server uploaded, and the crashed server downloads it the next time you join it. ## Installation diff --git a/plugins/player_sync/controller.ts b/plugins/player_sync/controller.ts index a94800cc..4d0bde24 100644 --- a/plugins/player_sync/controller.ts +++ b/plugins/player_sync/controller.ts @@ -258,6 +258,7 @@ export default async function(context: ControllerPluginContext) { prefetch(instanceId, request.destinationInstanceId, merged); } } + return new msg.UploadRequest.Response(store); }); controller.handle(msg.DownloadRequest, async (request: msg.DownloadRequest) => { diff --git a/plugins/player_sync/instance.ts b/plugins/player_sync/instance.ts index 4c185527..b461fcdf 100644 --- a/plugins/player_sync/instance.ts +++ b/plugins/player_sync/instance.ts @@ -200,11 +200,12 @@ export default async function(context: InstancePluginContext) { delete player_data.destination_instance_id; logger.verbose(`Uploading ${player_data.name} (${JSON.stringify(player_data).length / 1000}kB)`); + let stored: boolean; try { - await instance.sendTo( + ({ stored } = await instance.sendTo( "controller", new UploadRequest(instance.id, player_data.name, player_data, destinationInstanceId), - ); + )); } catch (err: any) { if (!(err instanceof lib.SessionLost)) { @@ -213,8 +214,10 @@ export default async function(context: InstancePluginContext) { return; } + // A copy the controller did not store must not pass for the stored one: the save downloads at the next join + const reply = stored ? "confirm_upload" : "reject_upload"; await instance.sendRcon( - `/sc player_sync.confirm_upload("${player_data.name}", ${player_data.generation})`, true, plugin.name + `/sc player_sync.${reply}("${player_data.name}", ${player_data.generation})`, true, plugin.name ); } diff --git a/plugins/player_sync/messages.ts b/plugins/player_sync/messages.ts index a3a1ce9b..506b46df 100644 --- a/plugins/player_sync/messages.ts +++ b/plugins/player_sync/messages.ts @@ -262,12 +262,29 @@ export class ReleaseRequest { } } +export class UploadResponse { + constructor( + /** False when the controller kept what it has: another copy is newer, locked or from another epoch */ + public stored: boolean, + ) { + } + + static jsonSchema = Type.Object({ + "stored": Type.Boolean(), + }); + + static fromJSON(json: Static) { + return new this(json.stored); + } +} + export class UploadRequest { declare ["constructor"]: typeof UploadRequest; static type = "request" as const; static src = "instance" as const; static dst = "controller" as const; static plugin = "player_sync" as const; + static Response = UploadResponse; constructor( public instanceId: number, diff --git a/plugins/player_sync/module/player_sync.lua b/plugins/player_sync/module/player_sync.lua index b2df31b6..8c27fd02 100644 --- a/plugins/player_sync/module/player_sync.lua +++ b/plugins/player_sync/module/player_sync.lua @@ -384,12 +384,14 @@ function player_sync.check_players_in_cutscene() end -- Whether a join should take the stored data: there is some, and this save hasn't synced the player in that epoch at --- that generation or newer with every component synced here now. A player without a record here has nothing to keep. +-- that generation or newer with every component synced here now, or the controller did not store its last upload +-- (reject_upload). A player without a record here has nothing to keep. local function download_needed(player_record, acquire_response, script_data) return acquire_response.has_data and ( not player_record or not player_record.sync + or player_record.outdated or (player_record.epoch or 0) ~= (acquire_response.epoch or 0) or acquire_response.generation > player_record.generation or serialize.newly_synced(player_record.components, script_data.components) @@ -543,6 +545,8 @@ function player_sync.sync_player(acquire_response) start_sync(player_record, script_data.components) player_record.dirty = true player_record.sync_in_progress = false + -- Nothing stored to download: the copy here is all there is + player_record.outdated = nil -- Deleted data keeps its generation and epoch so the next upload is accepted as the new baseline player_record.epoch = epoch -- A copy from another epoch has nothing to do with the stored generation @@ -573,6 +577,7 @@ function player_sync.finish_download(player, finished_record) player_record.dirty = true player_record.sync_in_progress = false + player_record.outdated = nil start_sync(player_record, finished_record.components) player_record.generation = finished_record.generation player_record.epoch = finished_record.epoch @@ -724,6 +729,27 @@ function player_sync.confirm_upload(player_name, generation) player_record.dirty = false end +-- Invoked by the instance code when the controller did not store the uploaded data: it holds another copy that is +-- newer, locked by another instance or from another epoch. This save's copy lost, even at the same generation, so it +-- is not uploaded again and the next join downloads. A retry of an upload the controller already stored ends up here +-- too, and then downloads what this save sent. +function player_sync.reject_upload(player_name, generation) + local player = game.get_player(player_name) + if not player or player.connected then + return + end + local script_data = get_script_data() + local player_record = script_data.players[player.name] + if not player_record or player_record.generation ~= generation then + return + end + + log("Upload of " .. player_name .. " was not stored, the next join downloads") + script_data.active_uploads[player_name] = nil + player_record.dirty = false + player_record.outdated = true +end + function player_sync.initiate_inventory_download(player, player_record, generation, epoch) player.print("Initiating inventory download...") local record = { diff --git a/plugins/player_sync/test/controller.js b/plugins/player_sync/test/controller.js index a249aa7c..7c619f57 100644 --- a/plugins/player_sync/test/controller.js +++ b/plugins/player_sync/test/controller.js @@ -77,6 +77,18 @@ describe("player_sync controller", function() { .playerData; } + it("should reply whether the upload was stored", async function() { + const handler = mock.getHandler(controller, msg.UploadRequest); + const send = (instanceId, generation) => handler( + { instanceId, playerName: "test", playerData: { generation, name: "test" } } + ); + assert.deepEqual(await send(1, 2), new msg.UploadRequest.Response(true)); + // A crashed instance restarting with the generation another instance already uploaded + assert.deepEqual(await send(1, 2), new msg.UploadRequest.Response(false)); + await mock.getHandler(controller, msg.AcquireRequest)(new msg.AcquireRequest(1, "test")); + controller.instances.set(2, controller.instances.get(1)); + assert.deepEqual(await send(2, 3), new msg.UploadRequest.Response(false)); + }); it("should store the upload as is when it has no components", async function() { const playerData = { generation: 2, name: "test", force: "enemy", tag: "uploaded" }; assert.deepEqual(await upload(playerData), playerData); diff --git a/plugins/player_sync/test/instance.js b/plugins/player_sync/test/instance.js index 67132ce6..9142521e 100644 --- a/plugins/player_sync/test/instance.js +++ b/plugins/player_sync/test/instance.js @@ -5,7 +5,7 @@ import * as lib from "@clusterio/lib"; import * as mock from "../../../test/mock.js"; import loadInstancePlugin, { recipeNotificationDelta, applyRecipeNotificationDelta } from "../dist/node/instance.js"; -import { AcquireResponse, DownloadResponse, PrefetchEvent } from "../dist/node/messages.js"; +import { AcquireResponse, DownloadResponse, PrefetchEvent, UploadResponse } from "../dist/node/messages.js"; import { components } from "../dist/node/components.js"; import { plugin as info } from "../dist/node/index.js"; @@ -275,6 +275,25 @@ describe("player_sync", function() { const request = await upload({ name: "test", generation: 2 }); assert.equal(request.destinationInstanceId, undefined); }); + async function rconAfterReply(stored) { + instance.server.reset(); + instance.connector.once("send", message => { + instance.connector.emit("message", new lib.MessageResponse( + 1, message.dst, message.src, new UploadResponse(stored) + )); + }); + instance.server.emit("ipc-player_sync_upload", { name: "test", generation: 2 }); + for (let i = 0; i < 100 && !instance.server.rconCommands.length; i++) { + await lib.wait(1); + } + return instance.server.rconCommands; + } + it("should confirm an upload the controller stored", async function() { + assert.deepEqual(await rconAfterReply(true), ['/sc player_sync.confirm_upload("test", 2)']); + }); + it("should reject an upload the controller did not store", async function() { + assert.deepEqual(await rconAfterReply(false), ['/sc player_sync.reject_upload("test", 2)']); + }); }); describe("PrefetchEvent", function() { From a959ff25a464598b4cd16c7b2ffdcb2a7622988b Mon Sep 17 00:00:00 2001 From: ILLISIS Date: Sat, 14 Nov 2026 14:57:30 +1100 Subject: [PATCH 02/20] Reject an upload for a player who is back, and take an empty reply as stored A player rejoining before the controller's reply was skipped by reject_upload, and the join then kept the copy the controller refused. The rejection now counts while the join still waits for its acquire reply, which the controller sends after it. A controller from before the upload response replies with nothing. That failed validation on a newer host, so its uploads were never confirmed. It is taken as stored, as before. Co-Authored-By: Claude Fable 5.2 Claude-Session: https://claude.ai/code/session_01JyNnVzRW4jPWaoWTxCyhM7 --- plugins/player_sync/messages.ts | 7 ++++--- plugins/player_sync/module/player_sync.lua | 7 ++++++- plugins/player_sync/test/plugin.js | 8 ++++++++ 3 files changed, 18 insertions(+), 4 deletions(-) diff --git a/plugins/player_sync/messages.ts b/plugins/player_sync/messages.ts index 506b46df..ea6059ee 100644 --- a/plugins/player_sync/messages.ts +++ b/plugins/player_sync/messages.ts @@ -269,12 +269,13 @@ export class UploadResponse { ) { } - static jsonSchema = Type.Object({ - "stored": Type.Boolean(), + // No type: a controller from before this response replies with nothing, which counts as stored + static jsonSchema = Type.Unsafe<{ stored: boolean } | undefined>({ + properties: { "stored": { type: "boolean" } }, }); static fromJSON(json: Static) { - return new this(json.stored); + return new this(json?.stored ?? true); } } diff --git a/plugins/player_sync/module/player_sync.lua b/plugins/player_sync/module/player_sync.lua index 8c27fd02..472f7958 100644 --- a/plugins/player_sync/module/player_sync.lua +++ b/plugins/player_sync/module/player_sync.lua @@ -735,10 +735,15 @@ end -- too, and then downloads what this save sent. function player_sync.reject_upload(player_name, generation) local player = game.get_player(player_name) - if not player or player.connected then + if not player then return end local script_data = get_script_data() + -- A player who is back already still waits for the acquire reply, which the controller sent after this one, and + -- that join then downloads. Past that reply the join has decided and this is not about the copy here any more. + if player.connected and not script_data.players_waiting_for_acquire[player_name] then + return + end local player_record = script_data.players[player.name] if not player_record or player_record.generation ~= generation then return diff --git a/plugins/player_sync/test/plugin.js b/plugins/player_sync/test/plugin.js index 2bc67904..7284404d 100644 --- a/plugins/player_sync/test/plugin.js +++ b/plugins/player_sync/test/plugin.js @@ -60,6 +60,14 @@ describe("player_sync plugin", function() { assert(!validate({ instanceId: 1, playerName: "player", playerData: data }), `accepted ${deleted}`); } }); + it("should take the empty reply of an older controller as a stored upload", function() { + const validate = lib.compile(msg.UploadResponse.jsonSchema); + assert(validate(undefined)); + assert.equal(msg.UploadResponse.fromJSON(undefined).stored, true); + assert(validate({ stored: false })); + assert.equal(msg.UploadResponse.fromJSON({ stored: false }).stored, false); + assert(!validate({ stored: "no" })); + }); describe("SetPlayerDataRequest schema", function() { const validate = lib.compile(msg.SetPlayerDataRequest.jsonSchema); // Shaped like module/serialize.lua output From 10beffe16789645ccd539f4d17785c814c163557 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Wed, 18 Nov 2026 13:07:18 +0000 Subject: [PATCH 03/20] Add --output json to clusterioctl Commands print their results through a CommandOutput on the ctl link. In json mode lists print as arrays of objects, other results as an object, commands without a result print {} and failures print { error: ClassName, message } with exit code 1. log follow and debug dump-ws print JSON lines. Human output now goes through the shared asTable printer in every command, results that were logged to stderr (role create, save and mod upload/download) print to stdout, and config edit failures are logged instead of printed. Co-Authored-By: Claude Opus 5.5 --- docs/managing-a-cluster.md | 15 +++ docs/writing-plugins.md | 13 +++ packages/ctl/README.md | 5 + packages/ctl/ctl.ts | 72 +++++++++++--- packages/ctl/index.ts | 1 + packages/ctl/src/command_ops.ts | 81 ++++++++++++++++ packages/ctl/src/commands_controller.ts | 51 +++++----- packages/ctl/src/commands_debug.ts | 10 +- packages/ctl/src/commands_host.ts | 76 +++++++-------- packages/ctl/src/commands_instance.ts | 123 ++++++++++++++---------- packages/ctl/src/commands_log.ts | 23 +++-- packages/ctl/src/commands_mod.ts | 57 ++++++----- packages/ctl/src/commands_mod_pack.ts | 89 +++++++++-------- packages/ctl/src/commands_note.ts | 10 +- packages/ctl/src/commands_permission.ts | 8 +- packages/ctl/src/commands_role.ts | 8 +- packages/ctl/src/commands_user.ts | 57 +++++++---- packages/ctl/src/config_ops.ts | 22 +++++ plugins/player_sync/ctl.ts | 47 ++++++--- plugins/player_sync/test/plugin.js | 33 +++++-- test/ctl/command_ops.test.js | 70 ++++++++++++++ test/integration/clusterio.js | 35 +++++++ test/integration/index.js | 5 +- 23 files changed, 642 insertions(+), 269 deletions(-) create mode 100644 test/ctl/command_ops.test.js diff --git a/docs/managing-a-cluster.md b/docs/managing-a-cluster.md index c973228c..e64bee9c 100644 --- a/docs/managing-a-cluster.md +++ b/docs/managing-a-cluster.md @@ -8,6 +8,21 @@ Before `clusterioctl` can be used it needs to be configured for the cluster it w The easiest way to do this is to run `npx clusteriocontroller bootstrap create-ctl-config ` on the controller, which creates the necessary `config-ctl.json` for managing the cluster as the given user. +## Output Format + + ctl> --output json + +Print the result of the command as JSON on stdout instead of text meant for reading. +Lists are printed as an array of objects, other results as an object, and commands that have no result print `{}`. +If the command fails it prints `{"error": "", "message": ""}` and exits with a non-zero exit code. +Log messages are written to stderr in both formats. + +`log follow` and `debug dump-ws` keep running and print one JSON object per line as entries arrive. +`instance start-all` and `instance stop-all` print an array with an entry per instance, which has an `error` property if that instance failed to start or stop. + +The default is `--output human`. + + ## Hosts ### List hosts diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index 18d32b64..2a0d4e33 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -972,6 +972,19 @@ For a command the `definition` is the arguments to pass to [yargs.command](http: The `handler` is an async function that's invoked when the command is executed and it's passed the parsed command line arguments and a reference to the `Ctl` class of clusterioctl. Note that messages sent from clusterioctl needs to have `"control"` as a part of `src` for it to be accepted by the controller, see [Defining Link Messages](#defining-link-messages) for how to define the messages that can be sent to the controller. +Commands print their results through `ctl.output` so that `--output json` works for them: + +```js +handler: async function(args, ctl) { + const result = await ctl.sendTo("controller", new messages.FrobnicateRequest(args.type)); + ctl.output.result(result, () => console.log(`Frobnicated ${result.count} foos`)); +}, +``` + +`ctl.output.result(data, human)` prints `data` as JSON in json mode and calls `human` otherwise. +`ctl.output.table(rows)` prints an array of objects as a table or as a JSON array. +Commands that print nothing get `{}` printed for them in json mode, and errors thrown from the handler are printed as `{"error": "", "message": ""}`. + To have the command tree become part of clusterioctl it needs to be added to the rootCommand tree in the `addCommands` hook of the ctl entrypoint: ```js diff --git a/packages/ctl/README.md b/packages/ctl/README.md index 4206032f..91ee0c14 100644 --- a/packages/ctl/README.md +++ b/packages/ctl/README.md @@ -23,6 +23,11 @@ Common options: * `--create-config` If the config file is missing, create a new one and carry on instead of exiting with an error. Alternative to the `config create` command. + * `--output ` Format to print the results of cluster commands in. + Defaults to `human`. + See [Output format](/docs/managing-a-cluster.md#output-format) for what `json` prints. + The `plugin` and `config` commands described below always print human readable text. + ### `plugin ` diff --git a/packages/ctl/ctl.ts b/packages/ctl/ctl.ts index d6456cf5..152a8285 100755 --- a/packages/ctl/ctl.ts +++ b/packages/ctl/ctl.ts @@ -17,6 +17,7 @@ import { ConsoleTransport, levels, logger } from "@clusterio/lib"; import * as commands from "./src/commands.js"; import { BaseCtlPlugin, CtlHooks } from "./src/BaseCtlPlugin.js"; +import { CommandOutput, outputFormats, type OutputFormat } from "./src/command_ops.js"; /** @@ -55,6 +56,8 @@ export class Ctl extends lib.Link { config: lib.CtlConfig; /** Keep the control connection alive after the command completes. */ keepOpen = false; + /** Output of the command being run. */ + output = new CommandOutput(); constructor( connector: CtlConnector, @@ -82,12 +85,19 @@ export class Ctl extends lib.Link { } async handleLogMessageEvent(event: lib.LogMessageEvent) { - logger.log(event.info as any); + if (this.output.json && this.output.streaming) { + this.output.result(event.info); + } else { + logger.log(event.info as any); + } } async handleDebugWsMessageEvent(event: lib.DebugWsMessageEvent) { - // eslint-disable-next-line no-console - console.log("WS", event.direction, event.content); + this.output.result( + { direction: event.direction, content: event.content }, + // eslint-disable-next-line no-console + () => console.log("WS", event.direction, event.content), + ); } async shutdown() { @@ -126,6 +136,7 @@ interface CtlArguments { $0: string, _: (string | number)[], logLevel: keyof typeof levels, + output: OutputFormat, config: string, pluginList: string, bypassLockFile: boolean, @@ -165,6 +176,13 @@ export async function initialize( choices: Object.keys(levels), type: "string", }) + .option("output", { + nargs: 1, + describe: "Format to print command results in", + default: "human", + choices: outputFormats, + type: "string", + }) .option("config", { nargs: 1, describe: "config file to get credentails from", @@ -260,19 +278,39 @@ export function selectTargetCommand(args: CtlArguments, rootCommands: lib.Comman return targetCommand; } -async function startCtl() { +/** + * Run the command selected by args, printing results in the format given by args.output + */ +export async function runCommand( + args: CtlArguments, + rootCommands: lib.CommandTree, + link: lib.Link & { output?: CommandOutput }, +) { + link.output = new CommandOutput(args.output); + const targetCommand = selectTargetCommand(args, rootCommands); + await targetCommand.run(args, link); + link.output.finish(); +} + +async function startCtl(output: CommandOutput) { const { args, shouldRun, rootCommands, ctlConfig, } = await initialize(process.argv.slice(2)); + output.format = args.output; if (!shouldRun || !rootCommands || !ctlConfig) { return; } if (!ctlConfig.get("ctl.controller_url") || !ctlConfig.get("ctl.controller_token")) { - logger.error("Missing URL and/or token to connect with. See README.md for setting up access."); + const message = "Missing URL and/or token to connect with. See README.md for setting up access."; + if (output.json) { + output.error(new lib.StartupError(message)); + } else { + logger.error(message); + } process.exitCode = 1; return; } @@ -298,12 +336,20 @@ async function startCtl() { process.on("SIGTERM", lib.createShutdownGuard(logger, "termination", ctl.shutdown.bind(ctl))); try { - const targetCommand = selectTargetCommand(args, rootCommands); - await targetCommand.run(args, ctl); + await runCommand(args, rootCommands, ctl); } catch (err) { ctl.keepOpen = false; - if (err instanceof lib.CommandError) { + const expected = err instanceof lib.CommandError || err instanceof lib.ClientError + || err instanceof lib.ServerError; + if (ctl.output.json) { + ctl.output.error(err); + process.exitCode = 1; + if (!expected) { + logger.error((err as Error).stack ?? String(err)); + } + + } else if (err instanceof lib.CommandError) { logger.error(`Error running command: ${err.message}`); process.exitCode = 1; @@ -327,7 +373,13 @@ async function startCtl() { } export function bootstrap() { - startCtl().catch(err => { + const output = new CommandOutput(); + startCtl(output).catch(err => { + process.exitCode = 1; + if (output.json) { + output.error(err); + return; + } if (err.errors) { logger.fatal(JSON.stringify(err.errors, null, "\t")); } @@ -347,8 +399,6 @@ ${err.stack}` ${err.stack}` ); } - - process.exitCode = 1; }); } diff --git a/packages/ctl/index.ts b/packages/ctl/index.ts index fe5bb9da..e4e69703 100644 --- a/packages/ctl/index.ts +++ b/packages/ctl/index.ts @@ -1,5 +1,6 @@ import { bootstrap } from "./ctl.js"; export * from "./ctl.js"; +export { CommandOutput, type OutputFormat } from "./src/command_ops.js"; export { BaseCtlPlugin, CtlHooks, type CtlPluginContext } from "./src/BaseCtlPlugin.js"; if (import.meta.main) { diff --git a/packages/ctl/src/command_ops.ts b/packages/ctl/src/command_ops.ts index 88e9a7e3..1d2eea0d 100644 --- a/packages/ctl/src/command_ops.ts +++ b/packages/ctl/src/command_ops.ts @@ -13,3 +13,84 @@ function formatCell(value: unknown) { } export const asTable = asTableModule.configure({ delimiter: " | ", print: formatCell }); + +/** Convert class instances, Sets and Maps into plain JSON values, ignoring wire format toJSON methods */ +export function toPlain(value: unknown): unknown { + if (value instanceof Set || value instanceof Array) { + return [...value].map(toPlain); + } + if (value instanceof Map) { + return Object.fromEntries([...value].map(([key, entry]) => [key, toPlain(entry)])); + } + if (value instanceof Date) { + return value.toISOString(); + } + if (typeof value === "object" && value !== null) { + return Object.fromEntries(Object.entries(value).map(([key, entry]) => [key, toPlain(entry)])); + } + return value; +} + +/** Describe an error as `{ error: ClassName, message: string }` */ +export function errorToJson(err: unknown) { + if (err instanceof Error) { + return { error: err.constructor.name, message: err.message }; + } + return { error: "Error", message: String(err) }; +} + +export const outputFormats = ["human", "json"] as const; +export type OutputFormat = typeof outputFormats[number]; + +/** + * Prints the results of a ctl command in the format chosen with --output + * + * In json mode each call to result prints one line of JSON to stdout. + */ +export class CommandOutput { + /** True once a result has been printed */ + written = false; + /** Command prints a JSON line per item as it runs instead of a single result */ + streaming = false; + + constructor( + public format: OutputFormat = "human", + ) { } + + get json() { + return this.format === "json"; + } + + /** + * Print the result of a command + * + * @param data - Printed as JSON in json mode. + * @param human - Prints the result in human mode, defaults to printing data as is. + */ + result(data: unknown, human: () => void = () => print(data)) { + this.written = true; + if (this.json) { + print(JSON.stringify(toPlain(data))); + } else { + human(); + } + } + + /** Print a list of objects as a table, or as an array in json mode */ + table(rows: object[]) { + this.result(rows, () => print(asTable(rows))); + } + + /** Print an error as `{ "error": ClassName, "message": string }` */ + error(err: unknown) { + this.written = true; + print(JSON.stringify(errorToJson(err))); + } + + /** Print `{}` in json mode for commands that finished without printing a result */ + finish() { + if (this.json && !this.written && !this.streaming) { + this.result({}); + } + } +} diff --git a/packages/ctl/src/commands_controller.ts b/packages/ctl/src/commands_controller.ts index 781e1503..d92fb47a 100644 --- a/packages/ctl/src/commands_controller.ts +++ b/packages/ctl/src/commands_controller.ts @@ -1,15 +1,15 @@ import fs from "node:fs/promises"; -import asTableModule from "as-table"; import events from "events"; import os from "os"; import child_process from "child_process"; import * as lib from "@clusterio/lib"; +import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { print } from "./command_ops.js"; -import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops.js"; - -const asTable = asTableModule.configure({ delimiter: " | " }); +import { asTable, print } from "./command_ops.js"; +import { + serializedConfigToString, getEditor, configToKeyVal, printConfig, printRestartRequired, +} from "./config_ops.js"; export const controllerCommands = new lib.CommandTree({ name: "controller", description: "Controller management" }); controllerCommands.add(new lib.Command({ @@ -44,9 +44,8 @@ controllerCommands.add(new lib.Command({ } if (args.restart) { await ctl.send(new lib.ControllerRestartRequest()); - } else { - print("Controller updated; a restart is required to apply the changes."); } + printRestartRequired(ctl, !args.restart, "Controller updated"); }, })); @@ -57,11 +56,7 @@ const controllerConfigCommands = new lib.CommandTree({ controllerConfigCommands.add(new lib.Command({ definition: ["list", "List controller configuration"], handler: async function(args: object, ctl: Ctl) { - let config = await ctl.send(new lib.ControllerConfigGetRequest()); - - for (let [name, value] of Object.entries(config)) { - print(`${name} ${JSON.stringify(value)}`); - } + printConfig(ctl, await ctl.send(new lib.ControllerConfigGetRequest())); }, })); @@ -146,19 +141,22 @@ controllerConfigCommands.add(new lib.Command({ index, final[index], )); - } catch (err) { - // eslint-disable-next-line - print(`Attempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`); - print(err); + } catch (err: any) { // If the string is empty, it's better to just print "" instead of nothing + logger.error( + `Attempt to set ${index} to ${final[index] || String(null)} failed; ` + + `set back to previous value: ${err.message}` + ); } } } try { await fs.unlink(tmpFile); } catch (err) { - print("err: temporary file", tmpFile, "could not be deleted."); - print("This is not fatal, but they may build up over time if the issue persists."); + logger.warn( + `Temporary file ${tmpFile} could not be deleted. ` + + "This is not fatal, but they may build up over time if the issue persists." + ); } }, })); @@ -175,7 +173,7 @@ controllerPluginCommands.add(new lib.Command({ let url = new URL(ctl.config.get("ctl.controller_url")!); url.pathname += "api/plugins"; let response = await fetch(url); - print(asTable(await response.json() as [])); + ctl.output.table(await response.json() as object[]); }, })); controllerPluginCommands.add(new lib.Command({ @@ -187,9 +185,8 @@ controllerPluginCommands.add(new lib.Command({ await ctl.sendTo("controller", new lib.PluginUpdateRequest(args.plugin)); if (args.restart) { await ctl.send(new lib.ControllerRestartRequest()); - } else { - print("Plugin updated; a restart is required to apply the changes."); } + printRestartRequired(ctl, !args.restart, "Plugin updated"); }, })); controllerPluginCommands.add(new lib.Command({ @@ -202,13 +199,16 @@ controllerPluginCommands.add(new lib.Command({ const response = await ctl.sendTo( "controller", new lib.PluginSearchRequest(args.query, args.page, args.pageSize) ); - print(asTable(response.results.map(plugin => ({ + const results = response.results.map(plugin => ({ name: plugin.name, version: plugin.version, publisher: plugin.publisher ?? "", description: plugin.description ?? "", - })))); - print(`Showing ${response.results.length} of ${response.total} results`); + })); + ctl.output.result({ total: response.total, results }, () => { + print(asTable(results)); + print(`Showing ${results.length} of ${response.total} results`); + }); }, })); controllerPluginCommands.add(new lib.Command({ @@ -220,9 +220,8 @@ controllerPluginCommands.add(new lib.Command({ await ctl.sendTo("controller", new lib.PluginInstallRequest(args.plugin)); if (args.restart) { await ctl.send(new lib.ControllerRestartRequest()); - } else { - print("Plugin installed; a restart is required to apply the changes."); } + printRestartRequired(ctl, !args.restart, "Plugin installed"); }, })); diff --git a/packages/ctl/src/commands_debug.ts b/packages/ctl/src/commands_debug.ts index c3dce44e..edc8644f 100644 --- a/packages/ctl/src/commands_debug.ts +++ b/packages/ctl/src/commands_debug.ts @@ -1,5 +1,6 @@ import * as lib from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; +import { print } from "./command_ops.js"; export const debugCommands = new lib.CommandTree({ name: "debug", description: "Debugging utilities" }); debugCommands.add(new lib.Command({ @@ -7,6 +8,7 @@ debugCommands.add(new lib.Command({ handler: async function(args: object, ctl: Ctl) { await ctl.send(new lib.DebugDumpWsRequest()); ctl.keepOpen = true; + ctl.output.streaming = true; }, })); @@ -20,12 +22,6 @@ debugCommands.add(new lib.Command({ }], handler: async function(args: { exchangeString: string, pretty: boolean }, ctl: Ctl) { const result = lib.readMapExchangeString(args.exchangeString); - if (args.pretty) { - // eslint-disable-next-line no-console - console.log(JSON.stringify(result, null, 2)); - } else { - // eslint-disable-next-line no-console - console.log(JSON.stringify(result)); - } + ctl.output.result(result, () => print(JSON.stringify(result, null, args.pretty ? 2 : undefined))); }, })); diff --git a/packages/ctl/src/commands_host.ts b/packages/ctl/src/commands_host.ts index 041a81a8..92c825c7 100644 --- a/packages/ctl/src/commands_host.ts +++ b/packages/ctl/src/commands_host.ts @@ -1,15 +1,15 @@ import fs from "node:fs/promises"; -import asTableModule from "as-table"; import events from "events"; import os from "os"; import child_process from "child_process"; import * as lib from "@clusterio/lib"; +import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { print } from "./command_ops.js"; -import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops.js"; - -const asTable = asTableModule.configure({ delimiter: " | " }); +import { asTable, print } from "./command_ops.js"; +import { + serializedConfigToString, getEditor, configToKeyVal, printConfig, printRestartRequired, +} from "./config_ops.js"; export const hostCommands = new lib.CommandTree({ name: "host", description: "Host management" }); hostCommands.add(new lib.Command({ @@ -45,8 +45,7 @@ hostCommands.add(new lib.Command({ hostCommands.add(new lib.Command({ definition: [["list", "l"], "List hosts connected to the controller"], handler: async function(args: object, ctl: Ctl) { - let hosts = await ctl.send(new lib.HostListRequest()); - print(asTable(hosts)); + ctl.output.table(await ctl.send(new lib.HostListRequest())); }, })); @@ -71,17 +70,19 @@ hostCommands.add(new lib.Command({ definition: ["pending", "List host installers waiting for approval"], handler: async function(args: object, ctl: Ctl) { let requests = await ctl.send(new lib.HostPairingListRequest()); - if (!requests.length) { - print("No pending host requests"); - return; - } - let now = Date.now(); - print(asTable(requests.map(request => ({ - code: request.code, - name: request.name, - address: request.remoteAddress, - age: formatAge(now - request.createdAtMs), - })))); + ctl.output.result(requests, () => { + if (!requests.length) { + print("No pending host requests"); + return; + } + let now = Date.now(); + print(asTable(requests.map(request => ({ + code: request.code, + name: request.name, + address: request.remoteAddress, + age: formatAge(now - request.createdAtMs), + })))); + }); }, })); @@ -99,7 +100,10 @@ hostCommands.add(new lib.Command({ name = requests.find(request => plainCode(request.code) === plainCode(args.code))?.name; } let hostId = await ctl.send(new lib.HostPairingApproveRequest(args.code, args.name)); - print(name ? `Approved host ${name} with id ${hostId}` : `Approved host with id ${hostId}`); + ctl.output.result( + { id: hostId, name }, + () => print(name ? `Approved host ${name} with id ${hostId}` : `Approved host with id ${hostId}`), + ); }, })); @@ -137,9 +141,8 @@ hostCommands.add(new lib.Command({ } if (args.restart) { await ctl.sendTo({ hostId }, new lib.HostRestartRequest()); - } else { - print("Host updated; a restart is required to apply the changes."); } + printRestartRequired(ctl, !args.restart, "Host updated"); }, })); @@ -153,11 +156,7 @@ hostConfigCommands.add(new lib.Command({ }], handler: async function(args: { host: string }, ctl: Ctl) { let hostId = await lib.resolveHost(ctl, args.host); - let config = await ctl.sendTo({ hostId }, new lib.HostConfigGetRequest()); - - for (let [name, value] of Object.entries(config)) { - print(`${name} ${JSON.stringify(value)}`); - } + printConfig(ctl, await ctl.sendTo({ hostId }, new lib.HostConfigGetRequest())); }, })); @@ -255,19 +254,22 @@ hostConfigCommands.add(new lib.Command({ index, final[index], )); - } catch (err) { - // eslint-disable-next-line - print(`Attempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`); + } catch (err: any) { // If the string is empty, it's better to just print "" instead of nothing - print(err); + logger.error( + `Attempt to set ${index} to ${final[index] || String(null)} failed; ` + + `set back to previous value: ${err.message}` + ); } } } try { await fs.unlink(tmpFile); } catch (err) { - print("err: temporary file", tmpFile, "could not be deleted."); - print("This is not fatal, but they may build up over time if the issue persists."); + logger.warn( + `Temporary file ${tmpFile} could not be deleted. ` + + "This is not fatal, but they may build up over time if the issue persists." + ); } }, })); @@ -285,9 +287,9 @@ hostPluginCommands.add(new lib.Command({ handler: async function(args: { host: string }, ctl: Ctl) { let hostId = await lib.resolveHost(ctl, args.host); const plugins = await ctl.sendTo({ hostId }, new lib.PluginListRequest()); - print(asTable(plugins.map(p => ({ + ctl.output.table(plugins.map(p => ({ title: p.title, version: p.version, state: p.state, npmPackage: p.npmPackage, - })))); + }))); }, })); hostPluginCommands.add(new lib.Command({ @@ -301,9 +303,8 @@ hostPluginCommands.add(new lib.Command({ await ctl.sendTo({ hostId }, new lib.PluginUpdateRequest(args.plugin)); if (args.restart) { await ctl.sendTo({ hostId }, new lib.HostRestartRequest()); - } else { - print("Plugin updated; a restart is required to apply the changes."); } + printRestartRequired(ctl, !args.restart, "Plugin updated"); }, })); hostPluginCommands.add(new lib.Command({ @@ -317,9 +318,8 @@ hostPluginCommands.add(new lib.Command({ await ctl.sendTo({ hostId }, new lib.PluginInstallRequest(args.plugin)); if (args.restart) { await ctl.sendTo({ hostId }, new lib.HostRestartRequest()); - } else { - print("Plugin installed; a restart is required to apply the changes."); } + printRestartRequired(ctl, !args.restart, "Plugin installed"); }, })); hostCommands.add(hostPluginCommands); diff --git a/packages/ctl/src/commands_instance.ts b/packages/ctl/src/commands_instance.ts index ff57d1af..93ebc965 100644 --- a/packages/ctl/src/commands_instance.ts +++ b/packages/ctl/src/commands_instance.ts @@ -1,5 +1,4 @@ import fs from "node:fs/promises"; -import asTableModule from "as-table"; import events from "events"; import path from "path"; import os from "os"; @@ -10,10 +9,9 @@ import util from "util"; import * as lib from "@clusterio/lib"; import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { print } from "./command_ops.js"; -import { serializedConfigToString, getEditor, configToKeyVal } from "./config_ops.js"; +import { asTable, errorToJson, print } from "./command_ops.js"; +import { serializedConfigToString, getEditor, configToKeyVal, printConfig } from "./config_ops.js"; -const asTable = asTableModule.configure({ delimiter: " | " }); const finished = util.promisify(stream.finished); export const instanceCommands = new lib.CommandTree({ @@ -27,7 +25,7 @@ instanceCommands.add(new lib.Command({ }], handler: async function(args: { templates: boolean }, ctl: Ctl) { let list = await ctl.send(new lib.InstanceDetailsListRequest()); - print(asTable(list.filter(instance => args.templates || !instance.isTemplate))); + ctl.output.table(list.filter(instance => args.templates || !instance.isTemplate)); }, })); @@ -64,6 +62,7 @@ instanceCommands.add(new lib.Command({ instanceConfig.toRemote("controller", fields), args.from )); + ctl.output.result({ id: instanceConfig.get("instance.id") }, () => {}); }, })); @@ -81,19 +80,13 @@ instanceConfigCommands.add(new lib.Command({ ? config["instance.inherited_fields"] as Record ?? {} : {}; - for (let [name, value] of Object.entries(config)) { - if (name === "instance.inherited_fields") { - continue; - } + printConfig(ctl, config, name => { const entry = inherited[name]; - let note = ""; if (entry instanceof Array && entry.length) { - note = ` (inherited except ${entry.join(", ")})`; - } else if (entry) { - note = " (inherited)"; + return ` (inherited except ${entry.join(", ")})`; } - print(`${name} ${JSON.stringify(value)}${note}`); - } + return entry ? " (inherited)" : ""; + }); }, })); @@ -225,19 +218,22 @@ instanceConfigCommands.add(new lib.Command({ index, final[index], )); - } catch (err) { - // eslint-disable-next-line - print(`Attempt to set ${index} to ${final[index] || String(null)} failed; set back to previous value.`); + } catch (err: any) { // If the string is empty, it's better to just print "" instead of nothing - print(err); + logger.error( + `Attempt to set ${index} to ${final[index] || String(null)} failed; ` + + `set back to previous value: ${err.message}` + ); } } } try { await fs.unlink(tmpFile); } catch (err) { - print("err: temporary file", tmpFile, "could not be deleted."); - print("This is not fatal, but they may build up over time if the issue persists."); + logger.warn( + `Temporary file ${tmpFile} could not be deleted. ` + + "This is not fatal, but they may build up over time if the issue persists." + ); } }, })); @@ -291,9 +287,9 @@ instanceSaveCommands.add(new lib.Command({ let instanceId = await lib.resolveInstance(ctl, args.instance); let saves = await ctl.sendTo("controller", new lib.InstanceSaveDetailsListRequest()); saves = saves.filter(save => save.instanceId === instanceId); - print(asTable(saves.map( + ctl.output.result(saves, () => print(asTable(saves.map( ({ mtimeMs, ...rest }) => ({ ...rest, mtime: new Date(mtimeMs).toLocaleString() }) - ))); + )))); }, })); @@ -394,13 +390,16 @@ instanceSaveCommands.add(new lib.Command({ logger.error(requestError); } - if (result.saves && result.saves.length) { - logger.info(`Successfully uploaded as ${result.saves[0]}`); - } - if ((result.errors || []).length || (result.request_errors || []).length) { throw new lib.CommandError("Uploading save failed"); } + + const name = result.saves?.[0]; + ctl.output.result({ name }, () => { + if (name) { + print(`Successfully uploaded as ${name}`); + } + }); }, })); @@ -439,7 +438,10 @@ instanceSaveCommands.add(new lib.Command({ args.copy ) ); - print(`Transferred as ${storedName} to ${args.targetInstance}.`); + ctl.output.result( + { name: storedName, instanceId: targetInstanceId }, + () => print(`Transferred as ${storedName} to ${args.targetInstance}.`), + ); }, })); @@ -456,7 +458,10 @@ instanceSaveCommands.add(new lib.Command({ url.pathname += `api/stream/${streamId}`; const filename = await lib.downloadFile(url, args.save, "rename"); - logger.info(`Downloaded ${args.save}${args.save === filename ? "" : ` as ${filename}`}`); + ctl.output.result( + { filename }, + () => print(`Downloaded ${args.save}${args.save === filename ? "" : ` as ${filename}`}`), + ); }, })); @@ -566,27 +571,34 @@ instanceCommands.add(new lib.Command({ }); if (instancesToStart.length === 0) { - print("No instances to start."); + ctl.output.result([], () => print("No instances to start.")); return; } - print(`Starting ${instancesToStart.length} instance(s):`); - for (const instance of instancesToStart) { - print(` - ${instance.name} (ID: ${instance.id})`); + const human = !ctl.output.json; + if (human) { + print(`Starting ${instancesToStart.length} instance(s):`); + for (const instance of instancesToStart) { + print(` - ${instance.name} (ID: ${instance.id})`); + } } // Start all filtered instances - const startPromises = instancesToStart.map(async (instance: lib.InstanceDetails) => { + const results = await Promise.all(instancesToStart.map(async (instance: lib.InstanceDetails) => { try { await ctl.sendTo({ instanceId: instance.id }, new lib.InstanceStartRequest()); - print(`✓ Started ${instance.name}`); + if (human) { + print(`✓ Started ${instance.name}`); + } + return { id: instance.id, name: instance.name }; } catch (error) { - print(`✗ Failed to start ${instance.name}: ${error}`); + if (human) { + print(`✗ Failed to start ${instance.name}: ${error}`); + } + return { id: instance.id, name: instance.name, error: errorToJson(error) }; } - }); - - await Promise.all(startPromises); - print("Start all operation completed."); + })); + ctl.output.result(results, () => print("Start all operation completed.")); }, })); @@ -646,27 +658,34 @@ instanceCommands.add(new lib.Command({ .filter((instance: lib.InstanceDetails) => ["starting", "running"].includes(instance.status)); if (instancesToStop.length === 0) { - print("No instances to stop."); + ctl.output.result([], () => print("No instances to stop.")); return; } - print(`Stopping ${instancesToStop.length} instance(s):`); - for (const instance of instancesToStop) { - print(` - ${instance.name} (ID: ${instance.id})`); + const human = !ctl.output.json; + if (human) { + print(`Stopping ${instancesToStop.length} instance(s):`); + for (const instance of instancesToStop) { + print(` - ${instance.name} (ID: ${instance.id})`); + } } // Stop all filtered instances - const stopPromises = instancesToStop.map(async (instance: lib.InstanceDetails) => { + const results = await Promise.all(instancesToStop.map(async (instance: lib.InstanceDetails) => { try { await ctl.sendTo({ instanceId: instance.id }, new lib.InstanceStopRequest()); - print(`✓ Stopped ${instance.name}`); + if (human) { + print(`✓ Stopped ${instance.name}`); + } + return { id: instance.id, name: instance.name }; } catch (error) { - print(`✗ Failed to stop ${instance.name}: ${error}`); + if (human) { + print(`✗ Failed to stop ${instance.name}: ${error}`); + } + return { id: instance.id, name: instance.name, error: errorToJson(error) }; } - }); - - await Promise.all(stopPromises); - print("Stop all operation completed."); + })); + ctl.output.result(results, () => print("Stop all operation completed.")); }, })); @@ -703,6 +722,6 @@ instanceCommands.add(new lib.Command({ ); // Factorio includes a newline in its response output. - process.stdout.write(result); + ctl.output.result({ result }, () => process.stdout.write(result)); }, })); diff --git a/packages/ctl/src/commands_log.ts b/packages/ctl/src/commands_log.ts index 967f2393..a66abdd8 100644 --- a/packages/ctl/src/commands_log.ts +++ b/packages/ctl/src/commands_log.ts @@ -27,6 +27,7 @@ logCommands.add(new lib.Command({ let hostIds = args.host ? [await lib.resolveHost(ctl, args.host)] : []; await ctl.setLogSubscriptions({ all: args.all, controller: args.controller, hostIds, instanceIds }); ctl.keepOpen = true; + ctl.output.streaming = true; }, })); @@ -75,16 +76,18 @@ logCommands.add(new lib.Command({ result.log.reverse(); } - let stdoutLogger = winston.createLogger({ - level: "verbose", - levels, - format: new lib.TerminalFormat({ showTimestamp: true }), - transports: [ - new ConsoleTransport({ errorLevels: [], warnLevels: [] }), - ], + ctl.output.result(result.log, () => { + let stdoutLogger = winston.createLogger({ + level: "verbose", + levels, + format: new lib.TerminalFormat({ showTimestamp: true }), + transports: [ + new ConsoleTransport({ errorLevels: [], warnLevels: [] }), + ], + }); + for (let info of result.log) { + stdoutLogger.log(info as any); + } }); - for (let info of result.log) { - stdoutLogger.log(info as any); - } }, })); diff --git a/packages/ctl/src/commands_mod.ts b/packages/ctl/src/commands_mod.ts index 3eda61d0..188a1b9e 100644 --- a/packages/ctl/src/commands_mod.ts +++ b/packages/ctl/src/commands_mod.ts @@ -1,5 +1,4 @@ import fs from "node:fs/promises"; -import asTableModule from "as-table"; import events from "events"; import path from "path"; import stream from "stream"; @@ -8,9 +7,7 @@ import util from "util"; import * as lib from "@clusterio/lib"; import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { print } from "./command_ops.js"; - -const asTable = asTableModule.configure({ delimiter: " | " }); +import { asTable, print } from "./command_ops.js"; const finished = util.promisify(stream.finished); export const modCommands = new lib.CommandTree({ name: "mod", description: "Manage uploaded mods" }); @@ -24,16 +21,18 @@ modCommands.add(new lib.Command({ throw new lib.CommandError("mod-version must match format digit.digit.digit"); } let modInfo = await ctl.send(new lib.ModGetRequest(args.name, args.modVersion)); - for (let [field, value] of Object.entries(modInfo)) { - if (value instanceof Array) { - print(`${field}:`); - for (let entry of value) { - print(` ${entry}`); + ctl.output.result(modInfo, () => { + for (let [field, value] of Object.entries(modInfo)) { + if (value instanceof Array) { + print(`${field}:`); + for (let entry of value) { + print(` ${entry}`); + } + } else { + print(`${field}: ${value}`); } - } else { - print(`${field}: ${value}`); } - } + }); }, })); @@ -60,7 +59,7 @@ modCommands.add(new lib.Command({ } } } - print(asTable(mods)); + ctl.output.table(mods); }, })); @@ -131,11 +130,19 @@ modCommands.add(new lib.Command({ } } } - for (let issue of response.queryIssues) { - print(issue); - } - print(`page ${args.page} of ${response.pageCount} (${response.resultCount} results)`); - print(asTable(results)); + ctl.output.result({ + page: args.page, + pageCount: response.pageCount, + resultCount: response.resultCount, + queryIssues: response.queryIssues, + results, + }, () => { + for (let issue of response.queryIssues) { + print(issue); + } + print(`page ${args.page} of ${response.pageCount} (${response.resultCount} results)`); + print(asTable(results)); + }); }, })); @@ -174,14 +181,16 @@ modCommands.add(new lib.Command({ logger.error(requestError); } - if (result.mods && result.mods.length) { - const mod = lib.ModInfo.fromJSON(result.mods[0]); - logger.info(`Successfully uploaded ${mod.filename}`); - } - if ((result.errors || []).length || (result.request_errors || []).length) { throw new lib.CommandError("Uploading mod failed"); } + + const uploaded = result.mods?.length ? lib.ModInfo.fromJSON(result.mods[0]).filename : undefined; + ctl.output.result({ filename: uploaded }, () => { + if (uploaded) { + print(`Successfully uploaded ${uploaded}`); + } + }); }, })); @@ -201,7 +210,7 @@ modCommands.add(new lib.Command({ let filename = `${args.name}_${args.modVersion}.zip`; await lib.downloadFile(url, filename, "overwrite"); - logger.info(`Downloaded ${filename}`); + ctl.output.result({ filename }, () => print(`Downloaded ${filename}`)); }, })); diff --git a/packages/ctl/src/commands_mod_pack.ts b/packages/ctl/src/commands_mod_pack.ts index 690b6e9e..7b87aab6 100644 --- a/packages/ctl/src/commands_mod_pack.ts +++ b/packages/ctl/src/commands_mod_pack.ts @@ -1,12 +1,8 @@ -import asTableModule from "as-table"; - import * as lib from "@clusterio/lib"; import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; import { print } from "./command_ops.js"; -const asTable = asTableModule.configure({ delimiter: " | " }); - export const modPackCommands = new lib.CommandTree({ name: "mod-pack", description: "Mod Pack" }); modPackCommands.add(new lib.Command({ definition: ["show ", "Show details of mod pack", (yargs) => { @@ -19,42 +15,45 @@ modPackCommands.add(new lib.Command({ let modPack = await ctl.send( new lib.ModPackGetRequest(await lib.resolveModPack(ctl, args.modPack)) ); - - for (let [field, value] of Object.entries(modPack)) { - if (field === "mods") { - print(`${field}:`); - for (let [name, entry] of value) { - const mod = mods.get(`${name}_${entry.version}`); - const missing = !mod && "? "; - const badChecksum = mod && entry.sha1 && entry.sha1 !== mod.sha1 && "! "; - const warn = missing || badChecksum || ""; - const enabled = entry.enabled ? "" : "(disabled) "; - print(` ${warn}${enabled}${name} ${entry.version}${entry.sha1 ? ` (${entry.sha1})` : ""}`); - } - } else if (field === "settings") { - print(`${field}:`); - for (let [scope, settings] of Object.entries(value)) { - print(` ${scope}:`); - for (let [setting, settingValue] of settings as any) { - print(` ${setting}: ${JSON.stringify(settingValue.value)}`); - } - } - } else if (field === "exportManifest") { - print(`${field}:`); - if (value && value.assets) { - print(" assets:"); - for (let [name, fileName] of Object.entries(value.assets)) { - print(` ${name}: ${fileName}`); - } - } - - } else { - print(`${field}: ${value}`); - } - } + ctl.output.result(modPack, () => printModPack(modPack, mods)); }, })); +function printModPack(modPack: lib.ModPack, mods: Map) { + for (let [field, value] of Object.entries(modPack)) { + if (field === "mods") { + print(`${field}:`); + for (let [name, entry] of value) { + const mod = mods.get(`${name}_${entry.version}`); + const missing = !mod && "? "; + const badChecksum = mod && entry.sha1 && entry.sha1 !== mod.sha1 && "! "; + const warn = missing || badChecksum || ""; + const enabled = entry.enabled ? "" : "(disabled) "; + print(` ${warn}${enabled}${name} ${entry.version}${entry.sha1 ? ` (${entry.sha1})` : ""}`); + } + } else if (field === "settings") { + print(`${field}:`); + for (let [scope, settings] of Object.entries(value)) { + print(` ${scope}:`); + for (let [setting, settingValue] of settings as any) { + print(` ${setting}: ${JSON.stringify(settingValue.value)}`); + } + } + } else if (field === "exportManifest") { + print(`${field}:`); + if (value && value.assets) { + print(" assets:"); + for (let [name, fileName] of Object.entries(value.assets)) { + print(` ${name}: ${fileName}`); + } + } + + } else { + print(`${field}: ${value}`); + } + } +} + modPackCommands.add(new lib.Command({ definition: [["list", "l"], "List mod packs in the cluster"], handler: async function(args: object, ctl: Ctl) { @@ -68,7 +67,7 @@ modPackCommands.add(new lib.Command({ } } } - print(asTable(modPacks)); + ctl.output.table(modPacks); }, })); @@ -194,10 +193,17 @@ modPackCommands.add(new lib.Command({ setModPackModsEnabled(modPack, args.disabledMods, false); setModPackSettings(modPack, args); await ctl.send(new lib.ModPackCreateRequest(modPack)); - print(`Created mod pack ${modPack.name} (${modPack.id})`); + printCreated(ctl, modPack); }, })); +function printCreated(ctl: Ctl, modPack: lib.ModPack) { + ctl.output.result( + { id: modPack.id, name: modPack.name }, + () => print(`Created mod pack ${modPack.name} (${modPack.id})`), + ); +} + modPackCommands.add(new lib.Command({ definition: ["import ", "Import mod pack string", (yargs) => { yargs.positional("string", { describe: "Mod pack string to import", type: "string" }); @@ -205,7 +211,7 @@ modPackCommands.add(new lib.Command({ handler: async function(args: { string: string }, ctl: Ctl) { const modPack = lib.ModPack.fromModPackString(args.string); await ctl.send(new lib.ModPackCreateRequest(modPack)); - print(`Created mod pack ${modPack.name} (${modPack.id})`); + printCreated(ctl, modPack); }, })); @@ -217,7 +223,8 @@ modPackCommands.add(new lib.Command({ const modPack = await ctl.send( new lib.ModPackGetRequest(await lib.resolveModPack(ctl, args.modPack)) ); - print(modPack.toModPackString()); + const modPackString = modPack.toModPackString(); + ctl.output.result({ modPackString }, () => print(modPackString)); }, })); diff --git a/packages/ctl/src/commands_note.ts b/packages/ctl/src/commands_note.ts index b31ea531..7a78fc7b 100644 --- a/packages/ctl/src/commands_note.ts +++ b/packages/ctl/src/commands_note.ts @@ -1,11 +1,7 @@ -import asTableModule from "as-table"; - import * as lib from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; import { print } from "./command_ops.js"; -const asTable = asTableModule.configure({ delimiter: " | " }); - export const noteCommands = new lib.CommandTree({ name: "note", description: "Notes attached to hosts, instances, users and other resources", }); @@ -20,12 +16,12 @@ noteCommands.add(new lib.Command({ if (args.type !== undefined) { notes = notes.filter(note => note.resourceType === args.type); } - print(asTable(notes.map(note => ({ + ctl.output.table(notes.map(note => ({ type: note.resourceType, id: note.resourceId, updatedBy: note.updatedBy, content: note.content, - })))); + }))); }, })); @@ -42,7 +38,7 @@ noteCommands.add(new lib.Command({ if (!note) { throw new lib.CommandError(`No note for ${args.type} ${args.id}`); } - print(note.content); + ctl.output.result(note, () => print(note.content)); }, })); diff --git a/packages/ctl/src/commands_permission.ts b/packages/ctl/src/commands_permission.ts index 6e6dc691..d9b79d2d 100644 --- a/packages/ctl/src/commands_permission.ts +++ b/packages/ctl/src/commands_permission.ts @@ -1,16 +1,10 @@ -import asTableModule from "as-table"; - import * as lib from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { print } from "./command_ops.js"; - -const asTable = asTableModule.configure({ delimiter: " | " }); export const permissionCommands = new lib.CommandTree({ name: "permission", description: "Permission inspection" }); permissionCommands.add(new lib.Command({ definition: [["list", "l"], "List permissions in the cluster"], handler: async function(args: object, ctl: Ctl) { - let permissions = await ctl.send(new lib.PermissionListRequest()); - print(asTable(permissions)); + ctl.output.table(await ctl.send(new lib.PermissionListRequest())); }, })); diff --git a/packages/ctl/src/commands_role.ts b/packages/ctl/src/commands_role.ts index 80893d8f..d957051e 100644 --- a/packages/ctl/src/commands_role.ts +++ b/packages/ctl/src/commands_role.ts @@ -1,15 +1,13 @@ import * as lib from "@clusterio/lib"; -import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { asTable, print } from "./command_ops.js"; +import { print } from "./command_ops.js"; export const roleCommands = new lib.CommandTree({ name: "role", description: "Role management" }); roleCommands.add(new lib.Command({ definition: [["list", "l"], "List roles in the cluster"], handler: async function(args: object, ctl: Ctl) { - let roles = await ctl.send(new lib.RoleListRequest()); - print(asTable(roles)); + ctl.output.table(await ctl.send(new lib.RoleListRequest())); }, })); @@ -27,7 +25,7 @@ roleCommands.add(new lib.Command({ args.description, args.permissions, )); - logger.info(`Created role ID ${id}`); + ctl.output.result({ id }, () => print(`Created role ID ${id}`)); }, })); diff --git a/packages/ctl/src/commands_user.ts b/packages/ctl/src/commands_user.ts index 14235c99..169f03fa 100644 --- a/packages/ctl/src/commands_user.ts +++ b/packages/ctl/src/commands_user.ts @@ -5,6 +5,10 @@ import * as lib from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; import { asTable, print } from "./command_ops.js"; +function printProperties(object: object) { + print(asTable(Object.entries(object).map(([property, value]) => ({ property, value })))); +} + export const userCommands = new lib.CommandTree({ name: "user", alias: ["u"], description: "User management" }); userCommands.add(new lib.Command({ definition: ["show ", "Show details for one user", (yargs) => { @@ -21,23 +25,25 @@ userCommands.add(new lib.Command({ let instanceStats = user.instanceStats; // @ts-expect-error Terrible hack delete user.instanceStats; - print(asTable(Object.entries(user).map(([property, value]) => ({ property, value })))); - - if (args.instanceStats) { - let instances = await ctl.send(new lib.InstanceDetailsListRequest()); - function instanceName(id: number) { - let instance = instances.find(i => i.id === id); - if (instance) { - return instance.name; - } - return ""; - } - for (let [id, playerInstanceStats] of instanceStats || []) { - print(); - print(`Instance ${instanceName(id)} (${id}):`); - print(asTable(Object.entries(playerInstanceStats).map(([property, value]) => ({ property, value })))); - } + if (!args.instanceStats) { + ctl.output.result(user, () => printProperties(user)); + return; } + + let instances = await ctl.send(new lib.InstanceDetailsListRequest()); + const stats = [...instanceStats || []].map(([id, playerInstanceStats]) => ({ + id, + name: instances.find(i => i.id === id)?.name ?? "", + stats: playerInstanceStats, + })); + ctl.output.result({ ...user, instanceStats: stats }, () => { + printProperties(user); + for (let { id, name, stats: playerInstanceStats } of stats) { + print(); + print(`Instance ${name} (${id}):`); + printProperties(playerInstanceStats); + } + }); }, })); @@ -71,7 +77,7 @@ userCommands.add(new lib.Command({ delete user.isBanned; } } - print(asTable(users)); + ctl.output.table(users); }, })); @@ -219,11 +225,17 @@ async function handleImportOrRestore(args: { new lib.UserBulkImportRequest(importType, importType === "users" ? data.users : data, restore) ); - print(`${restore ? "Restored" : "Imported"} ${importType} from ${args.filepath}`); + let backupFile: string | undefined; if (restore && backup && !args.noBackup) { - await fs.writeFile(`${importType}-backup.json`, JSON.stringify(backup, undefined, "\t")); - print(`Wrote backup to ${importType}-backup.json`); + backupFile = `${importType}-backup.json`; + await fs.writeFile(backupFile, JSON.stringify(backup, undefined, "\t")); } + ctl.output.result({ type: importType, backupFile }, () => { + print(`${restore ? "Restored" : "Imported"} ${importType} from ${args.filepath}`); + if (backupFile) { + print(`Wrote backup to ${backupFile}`); + } + }); } userCommands.add(new lib.Command({ @@ -296,6 +308,9 @@ userCommands.add(new lib.Command({ await fs.writeFile(args.filepath, JSON.stringify(await ctl.send( new lib.UserBulkExportRequest(exportType) ), undefined, "\t")); - print(`Exported ${exportType} to ${args.filepath}`); + ctl.output.result( + { type: exportType, filepath: args.filepath }, + () => print(`Exported ${exportType} to ${args.filepath}`), + ); }, })); diff --git a/packages/ctl/src/config_ops.ts b/packages/ctl/src/config_ops.ts index 6a876cd4..d264297d 100644 --- a/packages/ctl/src/config_ops.ts +++ b/packages/ctl/src/config_ops.ts @@ -1,4 +1,6 @@ import * as lib from "@clusterio/lib"; +import type { Ctl } from "../ctl.js"; +import { print } from "./command_ops.js"; export async function getEditor(argsEditor: string) { // eslint-disable-next-line @@ -53,3 +55,23 @@ export function serializedConfigToString( } return allConfigElements; } + +/** Print config fields as `name value` lines, or as an object in json mode */ +export function printConfig(ctl: Ctl, config: lib.ConfigSchema, note = (name: string) => "") { + ctl.output.result(config, () => { + for (let [name, value] of Object.entries(config)) { + if (name !== "instance.inherited_fields") { + print(`${name} ${JSON.stringify(value)}${note(name)}`); + } + } + }); +} + +/** Print whether a restart is still needed after an update or install */ +export function printRestartRequired(ctl: Ctl, restartRequired: boolean, action: string) { + ctl.output.result({ restartRequired }, () => { + if (restartRequired) { + print(`${action}; a restart is required to apply the changes.`); + } + }); +} diff --git a/plugins/player_sync/ctl.ts b/plugins/player_sync/ctl.ts index c0028faf..18cee8c6 100644 --- a/plugins/player_sync/ctl.ts +++ b/plugins/player_sync/ctl.ts @@ -30,14 +30,20 @@ playerSyncCommands.add(new lib.Command({ handler: async function(args: object, ctl: Ctl) { let players = await ctl.send(new msg.ListPlayersRequest()); players.sort((a, b) => a.name.localeCompare(b.name)); - print("name | generation | size | acquired by"); - for (let player of players) { - print( - `${player.name} | ${player.generation ?? "-"} | ` + - `${player.size === undefined ? "-" : lib.formatBytes(player.size)} | ` + - `${await instanceName(ctl, player.instanceId)}` - ); + if (ctl.output.json) { + ctl.output.result(players); + return; } + let rows = []; + for (let player of players) { + rows.push({ + name: player.name, + generation: player.generation ?? "-", + size: player.size === undefined ? "-" : lib.formatBytes(player.size), + "acquired by": await instanceName(ctl, player.instanceId), + }); + } + ctl.output.table(rows); }, })); @@ -47,8 +53,21 @@ playerSyncCommands.add(new lib.Command({ }], handler: async function(args: { player: string }, ctl: Ctl) { let response = await ctl.send(new msg.GetPlayerDataRequest(args.player)); - print(`acquired by: ${await instanceName(ctl, response.instanceId)}`); let playerData = response.playerData; + if (ctl.output.json) { + ctl.output.result({ + instanceId: response.instanceId, + ...playerData && { + generation: playerData.generation, + size: JSON.stringify(playerData).length, + controller: playerData.controller, + force: playerData.force, + inventories: summarizePlayerInventories(playerData), + }, + }); + return; + } + print(`acquired by: ${await instanceName(ctl, response.instanceId)}`); if (!playerData) { print(`No player data stored for ${args.player}`); return; @@ -81,9 +100,12 @@ playerSyncCommands.add(new lib.Command({ let content = JSON.stringify(response.playerData, null, "\t"); if (args.file) { await fs.writeFile(args.file, content); - print(`Wrote player data for ${args.player} to ${args.file}`); + ctl.output.result( + { file: args.file }, + () => print(`Wrote player data for ${args.player} to ${args.file}`), + ); } else { - print(content); + ctl.output.result(response.playerData, () => print(content)); } }, })); @@ -101,7 +123,10 @@ playerSyncCommands.add(new lib.Command({ playerData.name = args.player; playerData.generation ??= 0; let response = await ctl.send(new msg.SetPlayerDataRequest(args.player, playerData)); - print(`Stored player data for ${args.player} as generation ${response.generation}`); + ctl.output.result( + { generation: response.generation }, + () => print(`Stored player data for ${args.player} as generation ${response.generation}`), + ); }, })); diff --git a/plugins/player_sync/test/plugin.js b/plugins/player_sync/test/plugin.js index 2bc67904..b868cb29 100644 --- a/plugins/player_sync/test/plugin.js +++ b/plugins/player_sync/test/plugin.js @@ -4,7 +4,7 @@ import os from "node:os"; import path from "node:path"; import * as lib from "@clusterio/lib"; -import { CtlHooks } from "@clusterio/ctl"; +import { CommandOutput, CtlHooks } from "@clusterio/ctl"; import * as mock from "../../../test/mock.js"; import { testRoundTripJsonSerialisable, testMatrix } from "../../../test/common.js"; @@ -295,6 +295,7 @@ describe("player_sync plugin", function() { let printed; let responses; const ctl = { + output: new CommandOutput(), async send(message) { sent.push(message); const handler = responses.get(message.constructor); @@ -323,6 +324,7 @@ describe("player_sync plugin", function() { beforeEach(function() { sent = []; printed = []; + ctl.output = new CommandOutput(); responses = new Map([ [lib.InstanceDetailsGetRequest, request => ({ id: request.instanceId, name: "Test" })], [msg.ListPlayersRequest, () => [ @@ -352,10 +354,12 @@ describe("player_sync plugin", function() { it("list should print sorted entries", async function() { await run("list"); - assert.deepEqual(printed, [ - "name | generation | size | acquired by", - `alice | 2 | ${lib.formatBytes(100)} | -`, - "bob | - | - | Test (1)", + const lines = printed.join("\n").split("\n").map(line => line.trimEnd()); + assert.deepEqual(lines, [ + "name | generation | size | acquired by", + "--------------------------------------------", + `alice | 2 | ${lib.formatBytes(100)} | -`, + "bob | - | - | Test (1)", ]); }); it("show should print a summary", async function() { @@ -376,7 +380,7 @@ describe("player_sync plugin", function() { throw new lib.PermissionError("Permission denied"); }); await run("list"); - assert.equal(printed[2], "bob | - | - | 1"); + assert.match(printed[0], /bob +\| - +\| - +\| 1/); printed = []; await run("show", { player: "alice" }); assert.equal(printed[0], "acquired by: 1"); @@ -413,6 +417,23 @@ describe("player_sync plugin", function() { new lib.CommandError("Player data must be a JSON object"), ); }); + it("should print JSON in json mode", async function() { + ctl.output = new CommandOutput("json"); + await run("list"); + assert.deepEqual(JSON.parse(printed[0]), [ + { name: "alice", generation: 2, size: 100 }, + { name: "bob", instanceId: 1 }, + ]); + printed = []; + await run("show", { player: "alice" }); + const shown = JSON.parse(printed[0]); + assert.equal(shown.instanceId, 1); + assert.equal(shown.generation, 2); + assert.deepEqual(shown.inventories[0].items[0], { name: "wood", count: 5, quality: "rare" }); + printed = []; + await run("export", { player: "alice" }); + assert.deepEqual(JSON.parse(printed[0]), storedData); + }); it("delete and release should send requests", async function() { await run("delete", { player: "alice" }); await run("release", { player: "alice" }); diff --git a/test/ctl/command_ops.test.js b/test/ctl/command_ops.test.js new file mode 100644 index 00000000..34ad90a2 --- /dev/null +++ b/test/ctl/command_ops.test.js @@ -0,0 +1,70 @@ +import assert from "node:assert/strict"; +import * as lib from "@clusterio/lib"; +import { CommandOutput, errorToJson, toPlain } from "@clusterio/ctl/dist/node/src/command_ops.js"; + +/** Run fn and return the lines it printed with console.log */ +function captureLog(fn) { + const lines = []; + const originalLog = console.log; // eslint-disable-line no-console + console.log = (...args) => lines.push(args.join(" ")); // eslint-disable-line no-console + try { + fn(); + } finally { + console.log = originalLog; // eslint-disable-line no-console + } + return lines; +} + +describe("ctl/command_ops", function() { + describe("toPlain()", function() { + it("converts Sets, Maps and Dates", function() { + assert.deepEqual( + toPlain({ set: new Set([1, 2]), map: new Map([[3, { a: new Set(["b"]) }]]), date: new Date(0) }), + { set: [1, 2], map: { 3: { a: ["b"] } }, date: "1970-01-01T00:00:00.000Z" }, + ); + }); + it("uses own properties instead of toJSON", function() { + const role = new lib.Role(1, "name", "desc", new Set(["core.admin"])); + assert.deepEqual(toPlain(role).permissions, ["core.admin"]); + }); + }); + + describe("errorToJson()", function() { + it("uses the class name of the error", function() { + assert.deepEqual(errorToJson(new lib.NotFoundError("gone")), { error: "NotFoundError", message: "gone" }); + assert.deepEqual(errorToJson("text"), { error: "Error", message: "text" }); + }); + }); + + describe("class CommandOutput", function() { + it("calls the human formatter in human mode", function() { + const output = new CommandOutput("human"); + const human = () => console.log("human"); // eslint-disable-line no-console + assert.deepEqual(captureLog(() => output.result({ a: 1 }, human)), ["human"]); + assert.deepEqual(captureLog(() => output.finish()), []); + }); + it("prints one line of JSON per result in json mode", function() { + const output = new CommandOutput("json"); + const lines = captureLog(() => { + output.result({ a: new Set([1]) }, () => assert.fail("called human formatter")); + output.table([{ b: 2 }]); + output.finish(); + }); + assert.deepEqual(lines, ['{"a":[1]}', '[{"b":2}]']); + }); + it("prints {} for commands without a result", function() { + assert.deepEqual(captureLog(() => new CommandOutput("json").finish()), ["{}"]); + const streaming = new CommandOutput("json"); + streaming.streaming = true; + assert.deepEqual(captureLog(() => streaming.finish()), []); + }); + it("prints errors as JSON", function() { + const output = new CommandOutput("json"); + const lines = captureLog(() => { + output.error(new lib.CommandError("failed")); + output.finish(); + }); + assert.deepEqual(lines, ['{"error":"CommandError","message":"failed"}']); + }); + }); +}); diff --git a/test/integration/clusterio.js b/test/integration/clusterio.js index 5ac99976..2bdd6ed7 100644 --- a/test/integration/clusterio.js +++ b/test/integration/clusterio.js @@ -2317,6 +2317,41 @@ describe("Integration of Clusterio", function() { }); }); + describe("--output json", function() { + it("prints lists as an array of objects", async function() { + const roles = JSON.parse(await execCtlOutput("--output json role list")); + assert.deepEqual(roles.find(role => role.id === 0).permissions, ["core.admin"]); + }); + it("prints single results as an object", async function() { + const { id } = JSON.parse(await execCtlOutput("--output json role create json-role")); + const roles = await getControl().send(new lib.RoleListRequest()); + assert.equal(roles.find(role => role.id === id)?.name, "json-role"); + assert.equal(await execCtlOutput(`--output json role delete ${id}`), "{}"); + }); + it("prints log queries as an array", async function() { + const log = JSON.parse(await execCtlOutput("--output json log query --controller --limit 1")); + assert.equal(log.length, 1); + assert.equal(typeof log[0].message, "string"); + }); + it("prints errors as JSON with a non-zero exit code", async function() { + await assert.rejects( + execCtlProcess("--output json instance stop no-such-instance"), + err => { + assert.equal(err.code, 1); + assert.deepEqual( + JSON.parse(err.stdout), + { error: "CommandError", message: "No instance named no-such-instance" }, + ); + return true; + }, + ); + await assert.rejects( + execCtlProcess("--output json user set-admin no-such-user"), + err => JSON.parse(err.stdout).error === "NotFoundError", + ); + }); + }); + describe("user list", function() { it("prints roles and instances as lists", async function() { const output = await execCtlOutput("user list"); diff --git a/test/integration/index.js b/test/integration/index.js index 09407e23..76146237 100644 --- a/test/integration/index.js +++ b/test/integration/index.js @@ -10,7 +10,7 @@ import events from "node:events"; import * as lib from "@clusterio/lib"; import { LineSplitter, logger } from "@clusterio/lib"; -import { selectTargetCommand, initialize as initializeCtl } from "@clusterio/ctl"; +import { runCommand, initialize as initializeCtl } from "@clusterio/ctl"; import { _listFactorioVersions } from "@clusterio/host/dist/node/src/server.js"; import { pairHost } from "@clusterio/host"; @@ -242,8 +242,7 @@ export async function execCtl(command) { } control.config = initArgs.ctlConfig; - const targetCommand = selectTargetCommand(initArgs.args, initArgs.rootCommands); - await targetCommand.run(initArgs.args, control); + await runCommand(initArgs.args, initArgs.rootCommands, control); } finally { process.chdir("../.."); inExecCtl = false; From 8550df69ebbe39ea7bb5b1e0bf9f92848d632d16 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Wed, 18 Nov 2026 16:48:40 +0000 Subject: [PATCH 04/20] Address review of ctl --output Add a wire output format that prints the toJSON format sent over the link. Commands without a result print {"success": true}, or "Command ran successfully" in human mode. The missing URL check throws a StartupError, unexpected command errors are rethrown to the startup handler, and startup errors log as fatal. user list, note list and host plugin list print the objects they received instead of their table rows. Co-Authored-By: Claude Opus 5.5 --- docs/managing-a-cluster.md | 9 ++-- docs/writing-plugins.md | 5 ++- packages/ctl/README.md | 4 +- packages/ctl/ctl.ts | 55 ++++++++++-------------- packages/ctl/src/command_ops.ts | 34 ++++++++++----- packages/ctl/src/commands_host.ts | 4 +- packages/ctl/src/commands_instance.ts | 4 +- packages/ctl/src/commands_note.ts | 6 +-- packages/ctl/src/commands_user.ts | 35 ++++++---------- packages/ctl/src/config_ops.ts | 1 + plugins/player_sync/ctl.ts | 60 +++++++++++++-------------- test/ctl/command_ops.test.js | 13 +++++- test/integration/clusterio.js | 13 +++++- 13 files changed, 131 insertions(+), 112 deletions(-) diff --git a/docs/managing-a-cluster.md b/docs/managing-a-cluster.md index e64bee9c..cbc36a4b 100644 --- a/docs/managing-a-cluster.md +++ b/docs/managing-a-cluster.md @@ -13,14 +13,17 @@ The easiest way to do this is to run `npx clusteriocontroller bootstrap create-c ctl> --output json Print the result of the command as JSON on stdout instead of text meant for reading. -Lists are printed as an array of objects, other results as an object, and commands that have no result print `{}`. +Lists are printed as an array of objects, other results as an object, and commands that have no result print `{"success": true}`. If the command fails it prints `{"error": "", "message": ""}` and exits with a non-zero exit code. -Log messages are written to stderr in both formats. +Log messages, including the error message, are written to stderr in all formats. + +`--output wire` prints the same results in the format they are sent between the controller, hosts and clusterioctl, which uses snake_case names like `is_admin`. +The `json` format uses the property names shown in the tables of the human format. `log follow` and `debug dump-ws` keep running and print one JSON object per line as entries arrive. `instance start-all` and `instance stop-all` print an array with an entry per instance, which has an `error` property if that instance failed to start or stop. -The default is `--output human`. +The default is `--output human`, which prints `Command ran successfully` for commands that have no result. ## Hosts diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index 2a0d4e33..d7cf7d6d 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -981,9 +981,10 @@ handler: async function(args, ctl) { }, ``` -`ctl.output.result(data, human)` prints `data` as JSON in json mode and calls `human` otherwise. +`ctl.output.result(data, human)` prints `data` as JSON in json and wire mode and calls `human` otherwise. `ctl.output.table(rows)` prints an array of objects as a table or as a JSON array. -Commands that print nothing get `{}` printed for them in json mode, and errors thrown from the handler are printed as `{"error": "", "message": ""}`. +`ctl.output.human` is true when the output is meant for reading. +Commands that print nothing get `Command ran successfully` or `{"success": true}` printed for them, and errors thrown from the handler are printed as `{"error": "", "message": ""}` in json and wire mode. To have the command tree become part of clusterioctl it needs to be added to the rootCommand tree in the `addCommands` hook of the ctl entrypoint: diff --git a/packages/ctl/README.md b/packages/ctl/README.md index 91ee0c14..cf9fc7be 100644 --- a/packages/ctl/README.md +++ b/packages/ctl/README.md @@ -23,9 +23,9 @@ Common options: * `--create-config` If the config file is missing, create a new one and carry on instead of exiting with an error. Alternative to the `config create` command. - * `--output ` Format to print the results of cluster commands in. + * `--output ` Format to print the results of cluster commands in. Defaults to `human`. - See [Output format](/docs/managing-a-cluster.md#output-format) for what `json` prints. + See [Output format](/docs/managing-a-cluster.md#output-format) for what `json` and `wire` print. The `plugin` and `config` commands described below always print human readable text. diff --git a/packages/ctl/ctl.ts b/packages/ctl/ctl.ts index 152a8285..70792252 100755 --- a/packages/ctl/ctl.ts +++ b/packages/ctl/ctl.ts @@ -85,8 +85,9 @@ export class Ctl extends lib.Link { } async handleLogMessageEvent(event: lib.LogMessageEvent) { - if (this.output.json && this.output.streaming) { - this.output.result(event.info); + // Only streaming commands print log events as results, the rest log them to stderr + if (this.output.streaming) { + this.output.result(event.info, () => logger.log(event.info as any)); } else { logger.log(event.info as any); } @@ -292,27 +293,30 @@ export async function runCommand( link.output.finish(); } -async function startCtl(output: CommandOutput) { +async function startCtl() { const { args, shouldRun, rootCommands, ctlConfig, } = await initialize(process.argv.slice(2)); - output.format = args.output; if (!shouldRun || !rootCommands || !ctlConfig) { return; } - if (!ctlConfig.get("ctl.controller_url") || !ctlConfig.get("ctl.controller_token")) { - const message = "Missing URL and/or token to connect with. See README.md for setting up access."; - if (output.json) { - output.error(new lib.StartupError(message)); - } else { - logger.error(message); + try { + await connectAndRun(args, rootCommands, ctlConfig); + } catch (err) { + if (args.output !== "human") { + new CommandOutput(args.output).error(err); } - process.exitCode = 1; - return; + throw err; + } +} + +async function connectAndRun(args: CtlArguments, rootCommands: lib.CommandTree, ctlConfig: lib.CtlConfig) { + if (!ctlConfig.get("ctl.controller_url") || !ctlConfig.get("ctl.controller_token")) { + throw new lib.StartupError("Missing URL and/or token to connect with. See README.md for setting up access."); } let controlConnector = new CtlConnector( @@ -340,30 +344,22 @@ async function startCtl(output: CommandOutput) { } catch (err) { ctl.keepOpen = false; - const expected = err instanceof lib.CommandError || err instanceof lib.ClientError - || err instanceof lib.ServerError; - if (ctl.output.json) { - ctl.output.error(err); - process.exitCode = 1; - if (!expected) { - logger.error((err as Error).stack ?? String(err)); - } - - } else if (err instanceof lib.CommandError) { + if (err instanceof lib.CommandError) { logger.error(`Error running command: ${err.message}`); - process.exitCode = 1; } else if (err instanceof lib.ClientError || err instanceof lib.UnavailableError) { logger.error(`Error sending request: ${err.message}`); - process.exitCode = 1; } else if (err instanceof lib.ServerError) { logger.error(`Error sending request:\n${err.stack ?? err.message}`); - process.exitCode = 1; } else { throw err; } + if (!ctl.output.human) { + ctl.output.error(err); + } + process.exitCode = 1; } finally { if (!ctl.keepOpen) { @@ -373,13 +369,8 @@ async function startCtl(output: CommandOutput) { } export function bootstrap() { - const output = new CommandOutput(); - startCtl(output).catch(err => { + startCtl().catch(err => { process.exitCode = 1; - if (output.json) { - output.error(err); - return; - } if (err.errors) { logger.fatal(JSON.stringify(err.errors, null, "\t")); } @@ -392,7 +383,7 @@ export function bootstrap() { ${err.stack}` ); } else { - logger.error(` + logger.fatal(` +---------------------------------+ | Unable to to start clusterioctl | +---------------------------------+ diff --git a/packages/ctl/src/command_ops.ts b/packages/ctl/src/command_ops.ts index 1d2eea0d..5cdf8e99 100644 --- a/packages/ctl/src/command_ops.ts +++ b/packages/ctl/src/command_ops.ts @@ -39,13 +39,25 @@ export function errorToJson(err: unknown) { return { error: "Error", message: String(err) }; } -export const outputFormats = ["human", "json"] as const; +/** JSON.stringify replacer for Sets and Maps that have no toJSON method */ +function wireReplacer(key: string, value: unknown) { + if (value instanceof Set) { + return [...value]; + } + if (value instanceof Map) { + return Object.fromEntries(value); + } + return value; +} + +export const outputFormats = ["human", "json", "wire"] as const; export type OutputFormat = typeof outputFormats[number]; /** * Prints the results of a ctl command in the format chosen with --output * - * In json mode each call to result prints one line of JSON to stdout. + * In json and wire mode each call to result prints one line of JSON to stdout. json uses the + * property names of the objects, wire uses their toJSON methods to give the format sent over the link. */ export class CommandOutput { /** True once a result has been printed */ @@ -57,26 +69,28 @@ export class CommandOutput { public format: OutputFormat = "human", ) { } - get json() { - return this.format === "json"; + get human() { + return this.format === "human"; } /** * Print the result of a command * - * @param data - Printed as JSON in json mode. + * @param data - Printed as JSON in json and wire mode. * @param human - Prints the result in human mode, defaults to printing data as is. */ result(data: unknown, human: () => void = () => print(data)) { this.written = true; - if (this.json) { + if (this.format === "json") { print(JSON.stringify(toPlain(data))); + } else if (this.format === "wire") { + print(JSON.stringify(data, wireReplacer)); } else { human(); } } - /** Print a list of objects as a table, or as an array in json mode */ + /** Print a list of objects as a table, or as an array in json and wire mode */ table(rows: object[]) { this.result(rows, () => print(asTable(rows))); } @@ -87,10 +101,10 @@ export class CommandOutput { print(JSON.stringify(errorToJson(err))); } - /** Print `{}` in json mode for commands that finished without printing a result */ + /** Print a success result for commands that finished without printing one */ finish() { - if (this.json && !this.written && !this.streaming) { - this.result({}); + if (!this.written && !this.streaming) { + this.result({ success: true }, () => print("Command ran successfully")); } } } diff --git a/packages/ctl/src/commands_host.ts b/packages/ctl/src/commands_host.ts index 92c825c7..e3672d09 100644 --- a/packages/ctl/src/commands_host.ts +++ b/packages/ctl/src/commands_host.ts @@ -287,9 +287,9 @@ hostPluginCommands.add(new lib.Command({ handler: async function(args: { host: string }, ctl: Ctl) { let hostId = await lib.resolveHost(ctl, args.host); const plugins = await ctl.sendTo({ hostId }, new lib.PluginListRequest()); - ctl.output.table(plugins.map(p => ({ + ctl.output.result(plugins, () => print(asTable(plugins.map(p => ({ title: p.title, version: p.version, state: p.state, npmPackage: p.npmPackage, - }))); + }))))); }, })); hostPluginCommands.add(new lib.Command({ diff --git a/packages/ctl/src/commands_instance.ts b/packages/ctl/src/commands_instance.ts index 93ebc965..f469e13a 100644 --- a/packages/ctl/src/commands_instance.ts +++ b/packages/ctl/src/commands_instance.ts @@ -575,7 +575,7 @@ instanceCommands.add(new lib.Command({ return; } - const human = !ctl.output.json; + const human = ctl.output.human; if (human) { print(`Starting ${instancesToStart.length} instance(s):`); for (const instance of instancesToStart) { @@ -662,7 +662,7 @@ instanceCommands.add(new lib.Command({ return; } - const human = !ctl.output.json; + const human = ctl.output.human; if (human) { print(`Stopping ${instancesToStop.length} instance(s):`); for (const instance of instancesToStop) { diff --git a/packages/ctl/src/commands_note.ts b/packages/ctl/src/commands_note.ts index 7a78fc7b..21dd41bd 100644 --- a/packages/ctl/src/commands_note.ts +++ b/packages/ctl/src/commands_note.ts @@ -1,6 +1,6 @@ import * as lib from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { print } from "./command_ops.js"; +import { asTable, print } from "./command_ops.js"; export const noteCommands = new lib.CommandTree({ name: "note", description: "Notes attached to hosts, instances, users and other resources", @@ -16,12 +16,12 @@ noteCommands.add(new lib.Command({ if (args.type !== undefined) { notes = notes.filter(note => note.resourceType === args.type); } - ctl.output.table(notes.map(note => ({ + ctl.output.result(notes, () => print(asTable(notes.map(note => ({ type: note.resourceType, id: note.resourceId, updatedBy: note.updatedBy, content: note.content, - }))); + }))))); }, })); diff --git a/packages/ctl/src/commands_user.ts b/packages/ctl/src/commands_user.ts index 169f03fa..434e5a8b 100644 --- a/packages/ctl/src/commands_user.ts +++ b/packages/ctl/src/commands_user.ts @@ -55,29 +55,18 @@ userCommands.add(new lib.Command({ }); }], handler: async function(args: { stats: boolean, attributes: boolean }, ctl: Ctl) { - let users = await ctl.send(new lib.UserListRequest()); - for (let user of users) { - if (args.stats) { - Object.assign(user, user.playerStats); - } - // @ts-expect-error Terrible hack - delete user.playerStats; - // @ts-expect-error Terrible hack - delete user.isDeleted; - // @ts-expect-error Terrible hack - delete user.banReason; - // @ts-expect-error Terrible hack - delete user.instanceStats; - if (!args.attributes) { - // @ts-expect-error Terrible hack - delete user.isAdmin; - // @ts-expect-error Terrible hack - delete user.isWhitelisted; - // @ts-expect-error Terrible hack - delete user.isBanned; - } - } - ctl.output.table(users); + const users = await ctl.send(new lib.UserListRequest()); + const rows = users.map(user => { + const { + playerStats, isDeleted, banReason, instanceStats, isAdmin, isWhitelisted, isBanned, ...row + } = user; + return { + ...row, + ...args.attributes && { isAdmin, isWhitelisted, isBanned }, + ...args.stats && playerStats, + }; + }); + ctl.output.result(users, () => print(asTable(rows))); }, })); diff --git a/packages/ctl/src/config_ops.ts b/packages/ctl/src/config_ops.ts index d264297d..45c6c831 100644 --- a/packages/ctl/src/config_ops.ts +++ b/packages/ctl/src/config_ops.ts @@ -60,6 +60,7 @@ export function serializedConfigToString( export function printConfig(ctl: Ctl, config: lib.ConfigSchema, note = (name: string) => "") { ctl.output.result(config, () => { for (let [name, value] of Object.entries(config)) { + // Shown as an (inherited) note on each field by instance config list instead if (name !== "instance.inherited_fields") { print(`${name} ${JSON.stringify(value)}${note(name)}`); } diff --git a/plugins/player_sync/ctl.ts b/plugins/player_sync/ctl.ts index 18cee8c6..8932d953 100644 --- a/plugins/player_sync/ctl.ts +++ b/plugins/player_sync/ctl.ts @@ -30,7 +30,7 @@ playerSyncCommands.add(new lib.Command({ handler: async function(args: object, ctl: Ctl) { let players = await ctl.send(new msg.ListPlayersRequest()); players.sort((a, b) => a.name.localeCompare(b.name)); - if (ctl.output.json) { + if (!ctl.output.human) { ctl.output.result(players); return; } @@ -54,36 +54,36 @@ playerSyncCommands.add(new lib.Command({ handler: async function(args: { player: string }, ctl: Ctl) { let response = await ctl.send(new msg.GetPlayerDataRequest(args.player)); let playerData = response.playerData; - if (ctl.output.json) { - ctl.output.result({ - instanceId: response.instanceId, - ...playerData && { - generation: playerData.generation, - size: JSON.stringify(playerData).length, - controller: playerData.controller, - force: playerData.force, - inventories: summarizePlayerInventories(playerData), - }, - }); - return; - } - print(`acquired by: ${await instanceName(ctl, response.instanceId)}`); - if (!playerData) { - print(`No player data stored for ${args.player}`); - return; - } - print(`generation: ${playerData.generation}`); - print(`size: ${lib.formatBytes(JSON.stringify(playerData).length)}`); - print(`controller: ${playerData.controller}`); - print(`force: ${playerData.force}`); - for (let inventory of summarizePlayerInventories(playerData)) { - print(`${inventory.name}:`); - for (let item of inventory.items) { - let quality = item.quality ? ` (${item.quality})` : ""; - let size = item.exportSize ? ` ${lib.formatBytes(item.exportSize)}` : ""; - print(` ${item.count} ${item.name}${quality}${size}`); + const summary = { + instanceId: response.instanceId, + ...playerData && { + generation: playerData.generation, + size: JSON.stringify(playerData).length, + controller: playerData.controller, + force: playerData.force, + inventories: summarizePlayerInventories(playerData), + }, + }; + const acquiredBy = ctl.output.human ? await instanceName(ctl, response.instanceId) : ""; + ctl.output.result(summary, () => { + print(`acquired by: ${acquiredBy}`); + if (!playerData) { + print(`No player data stored for ${args.player}`); + return; } - } + print(`generation: ${summary.generation}`); + print(`size: ${lib.formatBytes(summary.size!)}`); + print(`controller: ${summary.controller}`); + print(`force: ${summary.force}`); + for (let inventory of summary.inventories!) { + print(`${inventory.name}:`); + for (let item of inventory.items) { + let quality = item.quality ? ` (${item.quality})` : ""; + let size = item.exportSize ? ` ${lib.formatBytes(item.exportSize)}` : ""; + print(` ${item.count} ${item.name}${quality}${size}`); + } + } + }); }, })); diff --git a/test/ctl/command_ops.test.js b/test/ctl/command_ops.test.js index 34ad90a2..175318bd 100644 --- a/test/ctl/command_ops.test.js +++ b/test/ctl/command_ops.test.js @@ -43,6 +43,9 @@ describe("ctl/command_ops", function() { assert.deepEqual(captureLog(() => output.result({ a: 1 }, human)), ["human"]); assert.deepEqual(captureLog(() => output.finish()), []); }); + it("prints a success line in human mode for commands without a result", function() { + assert.deepEqual(captureLog(() => new CommandOutput("human").finish()), ["Command ran successfully"]); + }); it("prints one line of JSON per result in json mode", function() { const output = new CommandOutput("json"); const lines = captureLog(() => { @@ -52,8 +55,14 @@ describe("ctl/command_ops", function() { }); assert.deepEqual(lines, ['{"a":[1]}', '[{"b":2}]']); }); - it("prints {} for commands without a result", function() { - assert.deepEqual(captureLog(() => new CommandOutput("json").finish()), ["{}"]); + it("prints the toJSON format in wire mode", function() { + const output = new CommandOutput("wire"); + const role = new lib.Role(1, "name", "desc", new Set(["core.admin"])); + const lines = captureLog(() => output.result({ role, set: new Set([1]), map: new Map([["a", 2]]) })); + assert.deepEqual(JSON.parse(lines[0]), { role: JSON.parse(JSON.stringify(role)), set: [1], map: { a: 2 } }); + }); + it("prints success for commands without a result", function() { + assert.deepEqual(captureLog(() => new CommandOutput("json").finish()), ['{"success":true}']); const streaming = new CommandOutput("json"); streaming.streaming = true; assert.deepEqual(captureLog(() => streaming.finish()), []); diff --git a/test/integration/clusterio.js b/test/integration/clusterio.js index 2bdd6ed7..091319b7 100644 --- a/test/integration/clusterio.js +++ b/test/integration/clusterio.js @@ -2326,7 +2326,18 @@ describe("Integration of Clusterio", function() { const { id } = JSON.parse(await execCtlOutput("--output json role create json-role")); const roles = await getControl().send(new lib.RoleListRequest()); assert.equal(roles.find(role => role.id === id)?.name, "json-role"); - assert.equal(await execCtlOutput(`--output json role delete ${id}`), "{}"); + assert.equal(await execCtlOutput(`--output json role delete ${id}`), '{"success":true}'); + }); + it("prints the toJSON format in wire mode", async function() { + const [jsonUser] = JSON.parse(await execCtlOutput("--output json user list")); + const [wireUser] = JSON.parse(await execCtlOutput("--output wire user list")); + assert("roleIds" in jsonUser); + assert(!("roleIds" in wireUser)); + assert.equal(wireUser.name, jsonUser.name); + }); + it("prints a success line for commands without a result", async function() { + const { id } = JSON.parse(await execCtlOutput("--output json role create human-role")); + assert.equal(await execCtlOutput(`role delete ${id}`), "Command ran successfully"); }); it("prints log queries as an array", async function() { const log = JSON.parse(await execCtlOutput("--output json log query --controller --limit 1")); From a845b7ac5229ba13b6fb045e5a517144e848c461 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Wed, 18 Nov 2026 12:59:39 +0000 Subject: [PATCH 05/20] Add requiredMods to plugin declarations Plugins can list the Factorio mods they need under requiredMods. When an instance starts, the host warns in the instance log about each loaded plugin whose required mods are missing or disabled in the mod pack. Subspace Storage declares the subspace_storage mod. Co-Authored-By: Claude Opus 5.5 --- docs/writing-plugins.md | 17 +++++++++++++++ packages/host/src/Instance.ts | 18 ++++++++++++++++ packages/lib/src/plugin.ts | 2 ++ plugins/subspace_storage/README.md | 4 ++++ plugins/subspace_storage/index.ts | 1 + test/host/Instance.js | 33 ++++++++++++++++++++++++++++++ 6 files changed, 75 insertions(+) diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index 18d32b64..de26816c 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -151,6 +151,10 @@ The following properties are recognized: Array of features the plugin needs from the instances it is loaded on, any of `"SavePatching"`, `"ScriptCommands"` and `"LuaUdp"`. See [Handling Invalid Configuration](#handling-invalid-configuration) +**requiredMods**: + Array of names of Factorio mods the plugin needs in the mod pack of the instances it is loaded on. + See [Handling Invalid Configuration](#handling-invalid-configuration) + **messages**: Array of request and event classes for this plugin. See guide for [defining link messages](#defining-link-messages) below. @@ -321,6 +325,19 @@ export const plugin = { Enabling the plugin on an instance that has the feature turned off then fails config validation, so the mistake is caught when the config is edited instead of when the instance starts. Instances that have the feature turned off get the plugin disabled by default when it is added. +If the plugin talks to a Factorio mod, list the mod under `requiredMods`: + +```js +export const plugin = { + name: "subspace_storage", + // ... + requiredMods: ["subspace_storage"], +}; +``` + +When an instance with the plugin loaded starts with a mod pack that does not have the mod enabled, the host logs a warning to the instance log naming the missing mods. +The mods are not added automatically, and the instance still starts. + Other constraints on config fields are expressed with a `validator` on the field definition, which throws when the value is not acceptable. Use `dependsOn` when the check involves other fields so that the validator runs when those change too. See [Configuration System](config-system.md) for details. diff --git a/packages/host/src/Instance.ts b/packages/host/src/Instance.ts index d6cfe046..8bb02b9f 100644 --- a/packages/host/src/Instance.ts +++ b/packages/host/src/Instance.ts @@ -1032,6 +1032,24 @@ end`.replace(/\r?\n/g, " "); } await this.syncMods(); + this.checkRequiredMods(this.activeModPack); + } + + /** + * Warn about mods required by loaded plugins that the mod pack lacks + */ + checkRequiredMods(modPack: lib.ModPack) { + for (const pluginInfo of this.loadedPlugins) { + const missing = (pluginInfo.requiredMods ?? []).filter(name => !modPack.mods.get(name)?.enabled); + if (missing.length) { + this.logger.warn( + `Plugin ${pluginInfo.name} requires ${missing.join(", ")} which ` + + `${missing.length === 1 ? "is" : "are"} not enabled in mod pack ${modPack.name}. ` + + `Add ${missing.length === 1 ? "it" : "them"} to the mod pack or set ` + + `${pluginInfo.name}.load_plugin to false for this instance.` + ); + } + } } /** diff --git a/packages/lib/src/plugin.ts b/packages/lib/src/plugin.ts index f98e0d4a..dafb28ae 100644 --- a/packages/lib/src/plugin.ts +++ b/packages/lib/src/plugin.ts @@ -41,6 +41,8 @@ export type PluginDeclaration = { migrationEntrypoint?: string; features?: (typeof PluginFeatureFlags)[number][]; + /** Names of Factorio mods the plugin needs in the instance's mod pack */ + requiredMods?: string[]; messages?: any[]; errors?: ErrorClass[]; diff --git a/plugins/subspace_storage/README.md b/plugins/subspace_storage/README.md index 9a4744ec..2dd51e5d 100644 --- a/plugins/subspace_storage/README.md +++ b/plugins/subspace_storage/README.md @@ -12,6 +12,10 @@ Run the following commands in the folder Clusterio is installed to: Substitute clusteriocontroller with clusteriohost or clusterioctl if this a dedicate host or ctl installation respectively. +The plugin needs the [Subspace Storage mod](https://mods.factorio.com/mod/subspace_storage) in the mod pack of every instance it is loaded on. +Instances started without it log a warning, and the plugin's commands fail in game. +Set `subspace_storage.load_plugin` to false on instances that should not use it. + ## Controller Configuration diff --git a/plugins/subspace_storage/index.ts b/plugins/subspace_storage/index.ts index 295268cd..9b11b60f 100644 --- a/plugins/subspace_storage/index.ts +++ b/plugins/subspace_storage/index.ts @@ -19,6 +19,7 @@ export const plugin: lib.PluginDeclaration = { title: "Subspace Storage", description: "Provides shared storage across instances for the Subspace Storage mod", instanceEntrypoint: "dist/node/instance.js", + requiredMods: ["subspace_storage"], instanceConfigFields: { "subspace_storage.log_item_transfers": { title: "Log Item Transfers", diff --git a/test/host/Instance.js b/test/host/Instance.js index 80cca616..14c9addc 100644 --- a/test/host/Instance.js +++ b/test/host/Instance.js @@ -336,6 +336,39 @@ describe("class Instance", function() { }); }); + describe(".checkRequiredMods()", function() { + let warnings; + beforeEach(function() { + warnings = []; + instance.logger = { warn(message) { warnings.push(message); } }; + instance.loadedPlugins = new Set([ + { name: "foo", requiredMods: ["foo_mod", "bar_mod"] }, + { name: "bar" }, + ]); + }); + function modPack(mods) { + return lib.ModPack.fromJSON({ name: "pack", mods }); + } + + it("should not warn when the required mods are enabled", function() { + instance.checkRequiredMods(modPack([ + { name: "foo_mod", enabled: true, version: "1.0.0" }, + { name: "bar_mod", enabled: true, version: "1.0.0" }, + ])); + assert.deepEqual(warnings, []); + }); + + it("should warn about missing and disabled required mods", function() { + instance.checkRequiredMods(modPack([ + { name: "foo_mod", enabled: false, version: "1.0.0" }, + ])); + assert.deepEqual(warnings, [ + "Plugin foo requires foo_mod, bar_mod which are not enabled in mod pack pack. " + + "Add them to the mod pack or set foo.load_plugin to false for this instance.", + ]); + }); + }); + describe("save name checks", function() { it("should reject a start save outside the saves directory", async function() { await assert.rejects( From bf33f4f52ea5463246b861c4998b778c3c0a5363 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Thu, 19 Nov 2026 15:19:05 +0000 Subject: [PATCH 06/20] Refuse to start without required mods and download them requiredMods entries are now Factorio dependency strings, and a mod listed twice gives a version range. The plugin loader validates them. The host refuses to start an instance whose mod pack is missing a required mod of a loaded plugin, has it disabled or has it outside the version range. On start the controller resolves the required mods of its plugins and their dependencies for the default mod pack's Factorio version and downloads the ones missing from the mod store. The resolver and portal download move from the ControlConnection handlers into Controller methods so both paths share them. Subspace Storage requires subspace_storage >= 1.99.0, and the integration tests build a stub of that mod for the test mod pack. Co-Authored-By: Claude Opus 5.5 --- docs/writing-plugins.md | 18 +- packages/controller/src/ControlConnection.ts | 209 +-------------- packages/controller/src/Controller.ts | 262 +++++++++++++++++++ packages/host/src/Instance.ts | 33 ++- packages/lib/src/plugin.ts | 23 +- packages/lib/src/plugin_loader.ts | 6 + plugins/subspace_storage/README.md | 4 +- plugins/subspace_storage/index.ts | 2 +- test/controller/Controller.js | 44 ++++ test/host/Instance.js | 40 +-- test/integration/index.js | 18 ++ test/lib/plugin.js | 18 ++ 12 files changed, 437 insertions(+), 240 deletions(-) diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index de26816c..3f1d300a 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -152,7 +152,7 @@ The following properties are recognized: See [Handling Invalid Configuration](#handling-invalid-configuration) **requiredMods**: - Array of names of Factorio mods the plugin needs in the mod pack of the instances it is loaded on. + Array of Factorio mods the plugin needs in the mod pack of the instances it is loaded on, written as Factorio dependency strings. See [Handling Invalid Configuration](#handling-invalid-configuration) **messages**: @@ -325,18 +325,24 @@ export const plugin = { Enabling the plugin on an instance that has the feature turned off then fails config validation, so the mistake is caught when the config is edited instead of when the instance starts. Instances that have the feature turned off get the plugin disabled by default when it is added. -If the plugin talks to a Factorio mod, list the mod under `requiredMods`: +If the plugin talks to a Factorio mod, list the mod under `requiredMods` using the same format as `dependencies` in a mod's info.json, without a prefix. +List a mod twice to give a version range: ```js export const plugin = { - name: "subspace_storage", + name: "foo_frobber", // ... - requiredMods: ["subspace_storage"], + requiredMods: ["frobber >= 1.2.0", "frobber < 2.0.0"], }; ``` -When an instance with the plugin loaded starts with a mod pack that does not have the mod enabled, the host logs a warning to the instance log naming the missing mods. -The mods are not added automatically, and the instance still starts. +An instance with the plugin loaded refuses to start if its mod pack is missing one of the mods, has it disabled, or has a version outside the range. +Leave out the dependencies of the required mods. Factorio checks those itself. +When the controller starts it downloads required mods it does not have, and their dependencies, from the mod portal for the Factorio version of the default mod pack. +This needs `controller.factorio_username` and `controller.factorio_token` to be set. +The mods still have to be added to the mod packs by hand. + +Forks of a required mod are not supported. Other constraints on config fields are expressed with a `validator` on the field definition, which throws when the value is not acceptable. Use `dependsOn` when the check involves other fields so that the validator runs when those change too. diff --git a/packages/controller/src/ControlConnection.ts b/packages/controller/src/ControlConnection.ts index 9f48aa53..052a2f4b 100644 --- a/packages/controller/src/ControlConnection.ts +++ b/packages/controller/src/ControlConnection.ts @@ -662,36 +662,7 @@ export default class ControlConnection extends BaseConnection { * @param request - Request object with mod name, version, and factorioVersion. */ async handleModPortalDownloadRequest(request: lib.ModPortalDownloadRequest) { - const factorioVersion = request.factorioVersion; - const toDownload = this._controller.modStore.filterInstalled(request.mods, false); - - if (toDownload.length > 0) { - // Get Factorio credentials from config - const username = this._controller.config.get("controller.factorio_username"); - const token = this._controller.config.get("controller.factorio_token"); - - if (!username || username === "" || !token || token === "") { - throw new lib.ConflictError("Factorio credentials (username, token) not configured on the controller."); - } - - try { - logger.info(`Downloading ${toDownload.length} mods for Factorio ${factorioVersion} from portal.`); - await this._controller.modStore.downloadMods(toDownload, username, token, factorioVersion); - - } catch (error: any) { - logger.error(`Error downloading mods from portal: ${error.message}`); - const errorMessage = "Mod portal download failed"; - if (error.message.includes("401") || error.message.includes("Unauthorized")) { - throw new lib.ConflictError( - `${errorMessage}: Authentication failed. Check Factorio username/token in controller config.` - ); - } - if (error.message.includes("404") || error.message.includes("Not Found")) { - throw new lib.NotFoundError(`${errorMessage}: Mod version not found on the portal.`); - } - throw new lib.InternalServerError(`${errorMessage}: ${error.message}`); - } - } + await this._controller.downloadModsFromPortal(request.mods, request.factorioVersion); // Verify all mods are present const modInfos = []; @@ -707,183 +678,9 @@ export default class ControlConnection extends BaseConnection { return modInfos; } - // eslint-disable-next-line complexity async handleModDependencyResolveRequest(request: lib.ModDependencyResolveRequest) { - const {factorioVersion, checkForUpdates} = request; - const searchQueue = [...request.mods]; - const localInfos = [...this._controller.modStore.mods()]; - - const builtInModNames = lib.ModPack.getBuiltinModNames(factorioVersion); - const skipSearch = new Set(builtInModNames); - - type ModPortalModType = InstanceType["mods"][number]; - type ModPortalReleaseType = NonNullable[number]; - const dependencyRequirements = new Map(); - const recommendedRequirements = new Map(); - const optionalRequirements = new Map(); - const candidateReleases = new Map(); - const errors = new Map(); - - const _modPortalReleases = new Map(); - async function fetchModReleases(modName: string) { - let releases = _modPortalReleases.get(modName); - if (releases === undefined) { - try { - releases = await lib.ModStore.fetchModReleases(modName); - } catch (error: any) { - if (!error.message.includes("404") && !error.message.includes("Not Found")) { - logger.error(`Error fetching mod from portal: ${error.message}`); - throw new lib.InternalServerError(`Dependency resolution failed: ${error.message}`); - } else { - releases = null; - } - } - } - _modPortalReleases.set(modName, releases); - return releases; - } - - function selectModRelease(releases: ModPortalModType | null, versionRange: lib.ModVersionRange) { - if (!releases || !releases.releases) { - return null; - } - - // Select the latest matching version for the mod pack's Factorio version - const release = releases.releases - .filter(info => ( - versionRange.testVersion(info.version) - && lib.normaliseMajorMinorVersion( - lib.normaliseSourceVersion(info.info_json.factorio_version) - ) === factorioVersion - )) - .reduce((max, cur) => ( - max && lib.integerSourceVersion(max.version) > lib.integerSourceVersion(cur.version) ? max : cur - ), undefined); - - if (!release) { - return null; - } - - // Create the mod info class from the selected - try { - return lib.ModInfo.fromJSON({ - ...release.info_json, // includes dependencies - sha1: release.sha1, - version: release.version, - name: releases.name, - author: releases.owner, - title: releases.title, - }); - } catch { - // Can error if there are invalid dependencies - errors.set(releases.name, "invalidDependency"); - return null; - } - } - - while (searchQueue.length > 0) { - // Dequeue the next mod, skip if incompatible - const mod = searchQueue.shift()!; - if (mod.incompatible) { - errors.set(mod.name, "incompatible"); - continue; - } - - // Get the current version range (dependencies can be promoted to a stricter requirement) - const versionRange = - dependencyRequirements.get(mod.name) - ?? recommendedRequirements.get(mod.name) - ?? optionalRequirements.get(mod.name) - ?? new lib.ModVersionRange(); - - if (mod.required) { - // Add to required, remove from recommended and optional - dependencyRequirements.set(mod.name, versionRange); - recommendedRequirements.delete(mod.name); - optionalRequirements.delete(mod.name); - - } else if (mod.recommended) { - // If not required, add to recommended and remove from optional - if (!dependencyRequirements.has(mod.name)) { - recommendedRequirements.set(mod.name, versionRange); - optionalRequirements.delete(mod.name); - } - - } else if ( - !dependencyRequirements.has(mod.name) - && !recommendedRequirements.has(mod.name) - ) { - // If not required or recommended, add to optional - optionalRequirements.set(mod.name, versionRange); - } - - // Update the version range if needed - if (mod.version) { - versionRange.combineVersion(mod.version); - if (!versionRange.valid) { - candidateReleases.delete(mod.name); - errors.set(mod.name, "unsatisfiable"); - continue; - } - } - - // Do not add dependencies for errors, skips, optionals, or valid candidates - const existingCandidate = candidateReleases.get(mod.name); - if (errors.has(mod.name) || skipSearch.has(mod.name) || optionalRequirements.has(mod.name) || ( - existingCandidate && versionRange.testVersion(existingCandidate.version) - )) { - continue; - } - - // Check if a local version fits the requirements - let candidate = localInfos - .filter(info => ( - info.name === mod.name - && info.factorioVersion === factorioVersion - && versionRange.testVersion(info.version) - )) - .reduce((max, cur) => ( - max && max.integerVersion > cur.integerVersion ? max : cur - ), undefined); - - // Check if a mod poral version fits the requirements - if (!candidate || checkForUpdates) { - const releases = await fetchModReleases(mod.name); - const release = selectModRelease(releases, versionRange); - // We only select the mod portal release if it is more recent than the local candidate - if (release && (!candidate || release.integerVersion > candidate.integerVersion)) { - candidate = release; - } - } - - // Queue the dependencies of the new candidate - if (candidate) { - candidateReleases.set(mod.name, candidate); - for (const dep of candidate.dependencies) { - searchQueue.push(dep); - } - } else { - candidateReleases.delete(mod.name); - skipSearch.add(mod.name); - } - } - - // Add the not found dependencies as errors - for (const modName of dependencyRequirements.keys()) { - if (!candidateReleases.has(modName) && !errors.has(modName)) { - errors.set(modName, "notFound"); - } - } - - // Remove incompatible and unsatisfiable dependencies if they aren't required by others - for (const [modName, error] of errors) { - if (!dependencyRequirements.has(modName) && (error === "incompatible" || error === "unsatisfiable")) { - errors.delete(modName); - } - } - - return new lib.ModDependencyResolveRequest.Response( - [...candidateReleases.values()], errors, + return await this._controller.resolveModDependencies( + request.mods, request.factorioVersion, request.checkForUpdates, ); } diff --git a/packages/controller/src/Controller.ts b/packages/controller/src/Controller.ts index da5f2369..11618c0d 100644 --- a/packages/controller/src/Controller.ts +++ b/packages/controller/src/Controller.ts @@ -512,6 +512,9 @@ export default class Controller { logger.info("Started controller"); this.startedAtMs = Date.now(); + this.downloadRequiredMods().catch( + err => logger.warn(`Unable to download mods required by plugins: ${err.message}`) + ); this.onAutosaveIntervalChanged(); this.onSystemMetricsIntervalChanged(); this._state = "running"; @@ -1169,6 +1172,265 @@ export default class Controller { } + /** + * Download mods from the Factorio mod portal to the mod store + * + * Mods already in the mod store are skipped. + * + * @throws {lib.ConflictError} if the Factorio credentials are not configured. + */ + async downloadModsFromPortal(mods: lib.ModNameVersionPair[], factorioVersion: lib.MajorMinorVersion) { + const toDownload = this.modStore.filterInstalled(mods, false); + + if (toDownload.length > 0) { + // Get Factorio credentials from config + const username = this.config.get("controller.factorio_username"); + const token = this.config.get("controller.factorio_token"); + + if (!username || username === "" || !token || token === "") { + throw new lib.ConflictError("Factorio credentials (username, token) not configured on the controller."); + } + + try { + logger.info(`Downloading ${toDownload.length} mods for Factorio ${factorioVersion} from portal.`); + await this.modStore.downloadMods(toDownload, username, token, factorioVersion); + + } catch (error: any) { + logger.error(`Error downloading mods from portal: ${error.message}`); + const errorMessage = "Mod portal download failed"; + if (error.message.includes("401") || error.message.includes("Unauthorized")) { + throw new lib.ConflictError( + `${errorMessage}: Authentication failed. Check Factorio username/token in controller config.` + ); + } + if (error.message.includes("404") || error.message.includes("Not Found")) { + throw new lib.NotFoundError(`${errorMessage}: Mod version not found on the portal.`); + } + throw new lib.InternalServerError(`${errorMessage}: ${error.message}`); + } + } + } + + /** + * Resolve mods and their dependencies against the mod store and the Factorio mod portal + */ + // eslint-disable-next-line complexity + async resolveModDependencies( + mods: lib.ModDependency[], + factorioVersion: lib.MajorMinorVersion, + checkForUpdates = false, + ) { + const searchQueue = [...mods]; + const localInfos = [...this.modStore.mods()]; + + const builtInModNames = lib.ModPack.getBuiltinModNames(factorioVersion); + const skipSearch = new Set(builtInModNames); + + type ModPortalModType = InstanceType["mods"][number]; + type ModPortalReleaseType = NonNullable[number]; + const dependencyRequirements = new Map(); + const recommendedRequirements = new Map(); + const optionalRequirements = new Map(); + const candidateReleases = new Map(); + const errors = new Map(); + + const _modPortalReleases = new Map(); + async function fetchModReleases(modName: string) { + let releases = _modPortalReleases.get(modName); + if (releases === undefined) { + try { + releases = await lib.ModStore.fetchModReleases(modName); + } catch (error: any) { + if (!error.message.includes("404") && !error.message.includes("Not Found")) { + logger.error(`Error fetching mod from portal: ${error.message}`); + throw new lib.InternalServerError(`Dependency resolution failed: ${error.message}`); + } else { + releases = null; + } + } + } + _modPortalReleases.set(modName, releases); + return releases; + } + + function selectModRelease(releases: ModPortalModType | null, versionRange: lib.ModVersionRange) { + if (!releases || !releases.releases) { + return null; + } + + // Select the latest matching version for the mod pack's Factorio version + const release = releases.releases + .filter(info => ( + versionRange.testVersion(info.version) + && lib.normaliseMajorMinorVersion( + lib.normaliseSourceVersion(info.info_json.factorio_version) + ) === factorioVersion + )) + .reduce((max, cur) => ( + max && lib.integerSourceVersion(max.version) > lib.integerSourceVersion(cur.version) ? max : cur + ), undefined); + + if (!release) { + return null; + } + + // Create the mod info class from the selected + try { + return lib.ModInfo.fromJSON({ + ...release.info_json, // includes dependencies + sha1: release.sha1, + version: release.version, + name: releases.name, + author: releases.owner, + title: releases.title, + }); + } catch { + // Can error if there are invalid dependencies + errors.set(releases.name, "invalidDependency"); + return null; + } + } + + while (searchQueue.length > 0) { + // Dequeue the next mod, skip if incompatible + const mod = searchQueue.shift()!; + if (mod.incompatible) { + errors.set(mod.name, "incompatible"); + continue; + } + + // Get the current version range (dependencies can be promoted to a stricter requirement) + const versionRange = + dependencyRequirements.get(mod.name) + ?? recommendedRequirements.get(mod.name) + ?? optionalRequirements.get(mod.name) + ?? new lib.ModVersionRange(); + + if (mod.required) { + // Add to required, remove from recommended and optional + dependencyRequirements.set(mod.name, versionRange); + recommendedRequirements.delete(mod.name); + optionalRequirements.delete(mod.name); + + } else if (mod.recommended) { + // If not required, add to recommended and remove from optional + if (!dependencyRequirements.has(mod.name)) { + recommendedRequirements.set(mod.name, versionRange); + optionalRequirements.delete(mod.name); + } + + } else if ( + !dependencyRequirements.has(mod.name) + && !recommendedRequirements.has(mod.name) + ) { + // If not required or recommended, add to optional + optionalRequirements.set(mod.name, versionRange); + } + + // Update the version range if needed + if (mod.version) { + versionRange.combineVersion(mod.version); + if (!versionRange.valid) { + candidateReleases.delete(mod.name); + errors.set(mod.name, "unsatisfiable"); + continue; + } + } + + // Do not add dependencies for errors, skips, optionals, or valid candidates + const existingCandidate = candidateReleases.get(mod.name); + if (errors.has(mod.name) || skipSearch.has(mod.name) || optionalRequirements.has(mod.name) || ( + existingCandidate && versionRange.testVersion(existingCandidate.version) + )) { + continue; + } + + // Check if a local version fits the requirements + let candidate = localInfos + .filter(info => ( + info.name === mod.name + && info.factorioVersion === factorioVersion + && versionRange.testVersion(info.version) + )) + .reduce((max, cur) => ( + max && max.integerVersion > cur.integerVersion ? max : cur + ), undefined); + + // Check if a mod poral version fits the requirements + if (!candidate || checkForUpdates) { + const releases = await fetchModReleases(mod.name); + const release = selectModRelease(releases, versionRange); + // We only select the mod portal release if it is more recent than the local candidate + if (release && (!candidate || release.integerVersion > candidate.integerVersion)) { + candidate = release; + } + } + + // Queue the dependencies of the new candidate + if (candidate) { + candidateReleases.set(mod.name, candidate); + for (const dep of candidate.dependencies) { + searchQueue.push(dep); + } + } else { + candidateReleases.delete(mod.name); + skipSearch.add(mod.name); + } + } + + // Add the not found dependencies as errors + for (const modName of dependencyRequirements.keys()) { + if (!candidateReleases.has(modName) && !errors.has(modName)) { + errors.set(modName, "notFound"); + } + } + + // Remove incompatible and unsatisfiable dependencies if they aren't required by others + for (const [modName, error] of errors) { + if (!dependencyRequirements.has(modName) && (error === "incompatible" || error === "unsatisfiable")) { + errors.delete(modName); + } + } + + return new lib.ModDependencyResolveRequest.Response( + [...candidateReleases.values()], errors, + ); + } + + /** + * Download the mods required by plugins that are missing from the mod store + * + * Resolves for the Factorio version of the default mod pack. Dependencies + * of the required mods are downloaded too. + */ + async downloadRequiredMods() { + const required = this.pluginInfos.flatMap(pluginInfo => lib.pluginRequiredMods(pluginInfo)); + const modPackId = this.config.get("controller.default_mod_pack_id"); + const modPack = modPackId !== null ? this.modPacks.get(modPackId) : undefined; + if (!required.length || !modPack) { + return; + } + + const factorioVersion = lib.normaliseMajorMinorVersion(modPack.factorioVersion); + const { dependencies, errors } = await this.resolveModDependencies(required, factorioVersion); + const builtInMods = new Set(lib.ModPack.getBuiltinModNames(factorioVersion)); + for (const [name, error] of errors) { + if (!builtInMods.has(name)) { + logger.warn(`Unable to resolve mod ${name} required by plugins: ${error}`); + } + } + const toDownload = this.modStore.filterInstalled(dependencies.map( + info => ({ name: info.name, version: new lib.ModVersionEquality("=", info.normalisedVersion) }) + ), false); + if (!toDownload.length) { + return; + } + + const names = toDownload.map(mod => `${mod.name} ${mod.version.version}`).join(", "); + logger.info(`Downloading mods required by plugins: ${names}`); + await this.downloadModsFromPortal(toDownload, factorioVersion); + } + modPacksUpdated(modPacks: lib.ModPack[]) { this.subscriptions.broadcast(new lib.ModPackUpdatesEvent(modPacks)); this.hooks.modPacksUpdated.invoke(modPacks); diff --git a/packages/host/src/Instance.ts b/packages/host/src/Instance.ts index 8bb02b9f..2048cdf8 100644 --- a/packages/host/src/Instance.ts +++ b/packages/host/src/Instance.ts @@ -1036,19 +1036,34 @@ end`.replace(/\r?\n/g, " "); } /** - * Warn about mods required by loaded plugins that the mod pack lacks + * Check that the mod pack has the mods required by the loaded plugins + * + * @throws {lib.ConflictError} if a required mod is missing, disabled or the wrong version. */ checkRequiredMods(modPack: lib.ModPack) { + const problems = []; for (const pluginInfo of this.loadedPlugins) { - const missing = (pluginInfo.requiredMods ?? []).filter(name => !modPack.mods.get(name)?.enabled); - if (missing.length) { - this.logger.warn( - `Plugin ${pluginInfo.name} requires ${missing.join(", ")} which ` + - `${missing.length === 1 ? "is" : "are"} not enabled in mod pack ${modPack.name}. ` + - `Add ${missing.length === 1 ? "it" : "them"} to the mod pack or set ` + - `${pluginInfo.name}.load_plugin to false for this instance.` - ); + const unmet = []; + for (const dependency of lib.pluginRequiredMods(pluginInfo)) { + const mod = modPack.mods.get(dependency.name); + if (!mod) { + unmet.push(`${dependency.spec} (missing)`); + } else if (!mod.enabled) { + unmet.push(`${dependency.spec} (disabled)`); + } else if (dependency.version && !dependency.version.testVersion(mod.version)) { + unmet.push(`${dependency.spec} (found ${mod.version})`); + } } + if (unmet.length) { + problems.push(`Plugin ${pluginInfo.name} requires ${unmet.join(", ")}.`); + } + } + if (problems.length) { + throw new lib.ConflictError( + `Mod pack ${modPack.name} does not have the mods required by the loaded plugins. ` + + `${problems.join(" ")} ` + + "Add the mods to the mod pack or set .load_plugin to false for this instance." + ); } } diff --git a/packages/lib/src/plugin.ts b/packages/lib/src/plugin.ts index dafb28ae..8e5b23db 100644 --- a/packages/lib/src/plugin.ts +++ b/packages/lib/src/plugin.ts @@ -9,6 +9,7 @@ import type { PermissionDefinition } from "./permissions.js"; import type { PlayerStats, Role } from "./data/index.js"; import type { SyncHook } from "./SyncHook.js"; import type { ErrorClass } from "./link/index.js"; +import { ModDependency } from "./data/ModInfo.js"; export const PluginFeatureFlags = [ /** The plugin requires module code to be patched into the save */ @@ -41,7 +42,10 @@ export type PluginDeclaration = { migrationEntrypoint?: string; features?: (typeof PluginFeatureFlags)[number][]; - /** Names of Factorio mods the plugin needs in the instance's mod pack */ + /** + * Factorio mods the plugin needs in the instance's mod pack, as Factorio + * dependency strings like `"subspace_storage >= 2.3.0"`. + */ requiredMods?: string[]; messages?: any[]; @@ -67,6 +71,23 @@ export function pluginNeedsWebBuild(info: PluginDeclaration) { ); } +/** + * Parse the requiredMods of a plugin + * + * A mod listed more than once must satisfy every entry, which gives a range. + * + * @throws Error if an entry is invalid or has a dependency prefix. + */ +export function pluginRequiredMods(pluginInfo: PluginDeclaration) { + return (pluginInfo.requiredMods ?? []).map(spec => { + const dependency = new ModDependency(spec); + if (dependency.type !== "required") { + throw new Error(`requiredMods entry "${spec}" can not have a dependency prefix`); + } + return dependency; + }); +} + export type PluginNodeEnvInfo = PluginDeclaration & { /** * Path to the folder with the static files that should be hosted on the web diff --git a/packages/lib/src/plugin_loader.ts b/packages/lib/src/plugin_loader.ts index 1aec0eee..1832d36a 100644 --- a/packages/lib/src/plugin_loader.ts +++ b/packages/lib/src/plugin_loader.ts @@ -84,6 +84,12 @@ export async function loadPluginInfos(pluginList: Map, skippedNp ); } + try { + libPlugin.pluginRequiredMods(pluginInfo); + } catch (err: any) { + throw new libErrors.PluginError(pluginName, err); + } + // migrate: ignore incompatible old plugins if (pluginInfo.messages && !(pluginInfo.messages instanceof Array)) { logger.warn(`Ignoring incompatible pre alpha.14 plugin ${pluginName}`); diff --git a/plugins/subspace_storage/README.md b/plugins/subspace_storage/README.md index 2dd51e5d..2cfb2739 100644 --- a/plugins/subspace_storage/README.md +++ b/plugins/subspace_storage/README.md @@ -13,8 +13,8 @@ Run the following commands in the folder Clusterio is installed to: Substitute clusteriocontroller with clusteriohost or clusterioctl if this a dedicate host or ctl installation respectively. The plugin needs the [Subspace Storage mod](https://mods.factorio.com/mod/subspace_storage) in the mod pack of every instance it is loaded on. -Instances started without it log a warning, and the plugin's commands fail in game. -Set `subspace_storage.load_plugin` to false on instances that should not use it. +The controller downloads it from the mod portal on start if the Factorio credentials are configured, but you have to add it to the mod packs yourself. +Instances with the plugin loaded refuse to start without it. Set `subspace_storage.load_plugin` to false on instances that should not use it. ## Controller Configuration diff --git a/plugins/subspace_storage/index.ts b/plugins/subspace_storage/index.ts index 9b11b60f..b4a9b58e 100644 --- a/plugins/subspace_storage/index.ts +++ b/plugins/subspace_storage/index.ts @@ -19,7 +19,7 @@ export const plugin: lib.PluginDeclaration = { title: "Subspace Storage", description: "Provides shared storage across instances for the Subspace Storage mod", instanceEntrypoint: "dist/node/instance.js", - requiredMods: ["subspace_storage"], + requiredMods: ["subspace_storage >= 1.99.0"], instanceConfigFields: { "subspace_storage.log_item_transfers": { title: "Log Item Transfers", diff --git a/test/controller/Controller.js b/test/controller/Controller.js index 1eaa26d9..d63d0605 100644 --- a/test/controller/Controller.js +++ b/test/controller/Controller.js @@ -305,6 +305,50 @@ describe("controller/src/Controller", function() { await assert.rejects(Controller.loadJsonObject(path.join(dir, "invalid.json")), SyntaxError); }); }); + describe(".downloadRequiredMods()", function() { + let ctrl, resolveCalls, downloadCalls, resolved; + function modInfo(name, version) { + return lib.ModInfo.fromJSON({ name, version, factorio_version: "2.0" }); + } + beforeEach(function() { + const config = new ControllerConfig("controller", { "controller.version": controllerVersion }); + ctrl = new Controller({}, [ + { name: "foo", title: "Foo", requiredMods: ["foo_mod >= 1.0.0"] }, + { name: "bar", title: "Bar" }, + ], config); + const modPack = ModPack.fromJSON({ id: 7, name: "default", factorio_version: "2.0.10" }); + ctrl.modPacks.set(modPack); + config.set("controller.default_mod_pack_id", 7); + resolveCalls = []; + downloadCalls = []; + resolved = [modInfo("foo_mod", "1.2.0"), modInfo("dep_mod", "0.1.0")]; + ctrl.resolveModDependencies = async (mods, factorioVersion) => { + resolveCalls.push([mods.map(mod => mod.spec), factorioVersion]); + return new lib.ModDependencyResolveRequest.Response(resolved, new Map()); + }; + ctrl.downloadModsFromPortal = async (mods, factorioVersion) => { + downloadCalls.push([mods.map(mod => `${mod.name} ${mod.version}`), factorioVersion]); + }; + }); + + it("should download required mods and their dependencies for the default mod pack", async function() { + await ctrl.downloadRequiredMods(); + assert.deepEqual(resolveCalls, [[["foo_mod >= 1.0.0"], "2.0"]]); + assert.deepEqual(downloadCalls, [[["foo_mod = 1.2.0", "dep_mod = 0.1.0"], "2.0"]]); + }); + + it("should skip mods already in the mod store", async function() { + ctrl.modStore = new lib.ModStore("mods", new Map(resolved.map(info => [info.filename, info]))); + await ctrl.downloadRequiredMods(); + assert.deepEqual(downloadCalls, []); + }); + + it("should do nothing when no plugin requires mods", async function() { + ctrl.pluginInfos = [{ name: "bar", title: "Bar" }]; + await ctrl.downloadRequiredMods(); + assert.deepEqual(resolveCalls, []); + }); + }); describe(".loggableHeaders()", function() { it("should redact credentials and keep other headers", function() { const headers = { diff --git a/test/host/Instance.js b/test/host/Instance.js index 14c9addc..2d6893ed 100644 --- a/test/host/Instance.js +++ b/test/host/Instance.js @@ -337,12 +337,9 @@ describe("class Instance", function() { }); describe(".checkRequiredMods()", function() { - let warnings; beforeEach(function() { - warnings = []; - instance.logger = { warn(message) { warnings.push(message); } }; instance.loadedPlugins = new Set([ - { name: "foo", requiredMods: ["foo_mod", "bar_mod"] }, + { name: "foo", requiredMods: ["foo_mod", "bar_mod >= 1.1.0", "bar_mod < 2.0.0"] }, { name: "bar" }, ]); }); @@ -350,22 +347,35 @@ describe("class Instance", function() { return lib.ModPack.fromJSON({ name: "pack", mods }); } - it("should not warn when the required mods are enabled", function() { + it("should accept a mod pack with the required mods", function() { instance.checkRequiredMods(modPack([ { name: "foo_mod", enabled: true, version: "1.0.0" }, - { name: "bar_mod", enabled: true, version: "1.0.0" }, + { name: "bar_mod", enabled: true, version: "1.1.0" }, ])); - assert.deepEqual(warnings, []); }); - it("should warn about missing and disabled required mods", function() { - instance.checkRequiredMods(modPack([ - { name: "foo_mod", enabled: false, version: "1.0.0" }, - ])); - assert.deepEqual(warnings, [ - "Plugin foo requires foo_mod, bar_mod which are not enabled in mod pack pack. " + - "Add them to the mod pack or set foo.load_plugin to false for this instance.", - ]); + it("should reject missing, disabled and out of range mods", function() { + const expected = (unmet) => new lib.ConflictError( + "Mod pack pack does not have the mods required by the loaded plugins. " + + `Plugin foo requires ${unmet}. ` + + "Add the mods to the mod pack or set .load_plugin to false for this instance." + ); + assert.throws( + () => instance.checkRequiredMods(modPack([{ name: "bar_mod", enabled: true, version: "1.0.0" }])), + expected("foo_mod (missing), bar_mod >= 1.1.0 (found 1.0.0)"), + ); + assert.throws( + () => instance.checkRequiredMods(modPack([ + { name: "foo_mod", enabled: false, version: "1.0.0" }, + { name: "bar_mod", enabled: true, version: "2.0.0" }, + ])), + expected("foo_mod (disabled), bar_mod < 2.0.0 (found 2.0.0)"), + ); + }); + + it("should ignore plugins that are not loaded", function() { + instance.loadedPlugins = new Set([{ name: "bar" }]); + instance.checkRequiredMods(modPack([])); }); }); diff --git a/test/integration/index.js b/test/integration/index.js index 09407e23..0d34f024 100644 --- a/test/integration/index.js +++ b/test/integration/index.js @@ -353,6 +353,21 @@ before(async function() { sourceDir: "packages/host/lua/clusterio_lib", outputDir: modsDir, }); + // Stand-in for the mod required by the subspace_storage plugin + const subspaceStorageDir = path.join("temp", "test", "subspace_storage"); + await fs.rm(subspaceStorageDir, { force: true, recursive: true }); + await fs.mkdir(subspaceStorageDir, { recursive: true }); + await fs.writeFile(path.join(subspaceStorageDir, "info.json"), JSON.stringify({ + name: "subspace_storage", + variants: [ + { version: "2.3.20", factorio_version: "2.0" }, + { version: "2.3.21", factorio_version: "2.1" }, + ], + title: "Subspace Storage test stub", + author: "Clusterio Team", + dependencies: ["base", "clusterio_lib"], + })); + await lib.build({ build: true, pack: true, sourceDir: subspaceStorageDir, outputDir: modsDir }); console.log("Setting Controller Config"); await execController("config create"); @@ -410,6 +425,9 @@ before(async function() { const [major, minor] = lib.normaliseMajorMinorVersion(latestFactorioVersion).split("."); testPack.mods.set("clusterio_lib", { name: "clusterio_lib", enabled: true, version: `2.1.${major}${minor}` }); + testPack.mods.set( + "subspace_storage", { name: "subspace_storage", enabled: true, version: `2.3.${major}${minor}` } + ); await control.sendTo("controller", new lib.ModPackCreateRequest(testPack)); await control.sendTo( diff --git a/test/lib/plugin.js b/test/lib/plugin.js index dd5ef087..babe2557 100644 --- a/test/lib/plugin.js +++ b/test/lib/plugin.js @@ -24,4 +24,22 @@ describe("lib/plugin", function() { } }); }); + describe("pluginRequiredMods()", function() { + it("should parse dependency strings", function() { + const mods = lib.pluginRequiredMods({ + name: "foo", title: "Foo", requiredMods: ["bar", "baz >= 1.2.0", "baz < 2.0.0"], + }); + assert.deepEqual(mods.map(mod => [mod.name, mod.version?.toString()]), [ + ["bar", undefined], ["baz", ">= 1.2.0"], ["baz", "< 2.0.0"], + ]); + }); + it("should return an empty list without requiredMods", function() { + assert.deepEqual(lib.pluginRequiredMods({ name: "foo", title: "Foo" }), []); + }); + it("should reject dependency prefixes and invalid versions", function() { + for (const spec of ["? bar", "! bar", "~ bar", "bar >= 1..2"]) { + assert.throws(() => lib.pluginRequiredMods({ name: "foo", title: "Foo", requiredMods: [spec] })); + } + }); + }); }); From 23187859d6054c1d874704739ebb5575c630dfc2 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Thu, 19 Nov 2026 15:56:48 +0000 Subject: [PATCH 07/20] Address second review of ctl --output CommandOutput.error takes a human reporter like result, so command errors log their message in human mode and print JSON in json and wire mode. table takes a map applied to each row in human mode, which note list, host plugin list, user list and save list now use. Rename streaming to streamingLog, and print startup errors with errorToJson directly. Co-Authored-By: Claude Opus 5.5 --- docs/managing-a-cluster.md | 2 +- docs/writing-plugins.md | 2 +- packages/ctl/ctl.ts | 19 ++++++++-------- packages/ctl/src/command_ops.ts | 32 +++++++++++++++++++-------- packages/ctl/src/commands_debug.ts | 2 +- packages/ctl/src/commands_host.ts | 4 ++-- packages/ctl/src/commands_instance.ts | 6 ++--- packages/ctl/src/commands_log.ts | 2 +- packages/ctl/src/commands_note.ts | 6 ++--- packages/ctl/src/commands_user.ts | 3 +-- test/ctl/command_ops.test.js | 13 +++++++++-- 11 files changed, 55 insertions(+), 36 deletions(-) diff --git a/docs/managing-a-cluster.md b/docs/managing-a-cluster.md index cbc36a4b..2cd6508b 100644 --- a/docs/managing-a-cluster.md +++ b/docs/managing-a-cluster.md @@ -15,7 +15,7 @@ The easiest way to do this is to run `npx clusteriocontroller bootstrap create-c Print the result of the command as JSON on stdout instead of text meant for reading. Lists are printed as an array of objects, other results as an object, and commands that have no result print `{"success": true}`. If the command fails it prints `{"error": "", "message": ""}` and exits with a non-zero exit code. -Log messages, including the error message, are written to stderr in all formats. +Log messages are written to stderr in all formats. `--output wire` prints the same results in the format they are sent between the controller, hosts and clusterioctl, which uses snake_case names like `is_admin`. The `json` format uses the property names shown in the tables of the human format. diff --git a/docs/writing-plugins.md b/docs/writing-plugins.md index d7cf7d6d..731bce10 100644 --- a/docs/writing-plugins.md +++ b/docs/writing-plugins.md @@ -982,7 +982,7 @@ handler: async function(args, ctl) { ``` `ctl.output.result(data, human)` prints `data` as JSON in json and wire mode and calls `human` otherwise. -`ctl.output.table(rows)` prints an array of objects as a table or as a JSON array. +`ctl.output.table(rows, map)` prints an array of objects as a JSON array, or as a table in human mode with `map` applied to each row first. `ctl.output.human` is true when the output is meant for reading. Commands that print nothing get `Command ran successfully` or `{"success": true}` printed for them, and errors thrown from the handler are printed as `{"error": "", "message": ""}` in json and wire mode. diff --git a/packages/ctl/ctl.ts b/packages/ctl/ctl.ts index 70792252..a737b6ef 100755 --- a/packages/ctl/ctl.ts +++ b/packages/ctl/ctl.ts @@ -17,7 +17,7 @@ import { ConsoleTransport, levels, logger } from "@clusterio/lib"; import * as commands from "./src/commands.js"; import { BaseCtlPlugin, CtlHooks } from "./src/BaseCtlPlugin.js"; -import { CommandOutput, outputFormats, type OutputFormat } from "./src/command_ops.js"; +import { CommandOutput, errorToJson, outputFormats, print, type OutputFormat } from "./src/command_ops.js"; /** @@ -85,8 +85,8 @@ export class Ctl extends lib.Link { } async handleLogMessageEvent(event: lib.LogMessageEvent) { - // Only streaming commands print log events as results, the rest log them to stderr - if (this.output.streaming) { + // Only log following commands print log events as results, the rest log them to stderr + if (this.output.streamingLog) { this.output.result(event.info, () => logger.log(event.info as any)); } else { logger.log(event.info as any); @@ -308,7 +308,7 @@ async function startCtl() { await connectAndRun(args, rootCommands, ctlConfig); } catch (err) { if (args.output !== "human") { - new CommandOutput(args.output).error(err); + print(JSON.stringify(errorToJson(err))); } throw err; } @@ -344,21 +344,20 @@ async function connectAndRun(args: CtlArguments, rootCommands: lib.CommandTree, } catch (err) { ctl.keepOpen = false; + let message: string; if (err instanceof lib.CommandError) { - logger.error(`Error running command: ${err.message}`); + message = `Error running command: ${err.message}`; } else if (err instanceof lib.ClientError || err instanceof lib.UnavailableError) { - logger.error(`Error sending request: ${err.message}`); + message = `Error sending request: ${err.message}`; } else if (err instanceof lib.ServerError) { - logger.error(`Error sending request:\n${err.stack ?? err.message}`); + message = `Error sending request:\n${err.stack ?? err.message}`; } else { throw err; } - if (!ctl.output.human) { - ctl.output.error(err); - } + ctl.output.error(err, () => logger.error(message)); process.exitCode = 1; } finally { diff --git a/packages/ctl/src/command_ops.ts b/packages/ctl/src/command_ops.ts index 5cdf8e99..258eea00 100644 --- a/packages/ctl/src/command_ops.ts +++ b/packages/ctl/src/command_ops.ts @@ -62,8 +62,8 @@ export type OutputFormat = typeof outputFormats[number]; export class CommandOutput { /** True once a result has been printed */ written = false; - /** Command prints a JSON line per item as it runs instead of a single result */ - streaming = false; + /** Command prints log events as results while it runs and has no final result */ + streamingLog = false; constructor( public format: OutputFormat = "human", @@ -90,20 +90,34 @@ export class CommandOutput { } } - /** Print a list of objects as a table, or as an array in json and wire mode */ - table(rows: object[]) { - this.result(rows, () => print(asTable(rows))); + /** + * Print a list of objects as a table, or as an array in json and wire mode + * + * @param rows - Printed as is in json and wire mode. + * @param map - Converts each row into the table row printed in human mode. + */ + table(rows: T[], map: (row: T) => object = row => row) { + this.result(rows, () => print(asTable(rows.map(map)))); } - /** Print an error as `{ "error": ClassName, "message": string }` */ - error(err: unknown) { + /** + * Print an error as `{ "error": ClassName, "message": string }` in json and wire mode + * + * @param err - Error to print. + * @param human - Reports the error in human mode. + */ + error(err: unknown, human: () => void) { this.written = true; - print(JSON.stringify(errorToJson(err))); + if (this.human) { + human(); + } else { + print(JSON.stringify(errorToJson(err))); + } } /** Print a success result for commands that finished without printing one */ finish() { - if (!this.written && !this.streaming) { + if (!this.written && !this.streamingLog) { this.result({ success: true }, () => print("Command ran successfully")); } } diff --git a/packages/ctl/src/commands_debug.ts b/packages/ctl/src/commands_debug.ts index edc8644f..4fca9c69 100644 --- a/packages/ctl/src/commands_debug.ts +++ b/packages/ctl/src/commands_debug.ts @@ -8,7 +8,7 @@ debugCommands.add(new lib.Command({ handler: async function(args: object, ctl: Ctl) { await ctl.send(new lib.DebugDumpWsRequest()); ctl.keepOpen = true; - ctl.output.streaming = true; + ctl.output.streamingLog = true; }, })); diff --git a/packages/ctl/src/commands_host.ts b/packages/ctl/src/commands_host.ts index e3672d09..8d3adeb7 100644 --- a/packages/ctl/src/commands_host.ts +++ b/packages/ctl/src/commands_host.ts @@ -287,9 +287,9 @@ hostPluginCommands.add(new lib.Command({ handler: async function(args: { host: string }, ctl: Ctl) { let hostId = await lib.resolveHost(ctl, args.host); const plugins = await ctl.sendTo({ hostId }, new lib.PluginListRequest()); - ctl.output.result(plugins, () => print(asTable(plugins.map(p => ({ + ctl.output.table(plugins, p => ({ title: p.title, version: p.version, state: p.state, npmPackage: p.npmPackage, - }))))); + })); }, })); hostPluginCommands.add(new lib.Command({ diff --git a/packages/ctl/src/commands_instance.ts b/packages/ctl/src/commands_instance.ts index f469e13a..a88b3b42 100644 --- a/packages/ctl/src/commands_instance.ts +++ b/packages/ctl/src/commands_instance.ts @@ -9,7 +9,7 @@ import util from "util"; import * as lib from "@clusterio/lib"; import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { asTable, errorToJson, print } from "./command_ops.js"; +import { errorToJson, print } from "./command_ops.js"; import { serializedConfigToString, getEditor, configToKeyVal, printConfig } from "./config_ops.js"; const finished = util.promisify(stream.finished); @@ -287,9 +287,7 @@ instanceSaveCommands.add(new lib.Command({ let instanceId = await lib.resolveInstance(ctl, args.instance); let saves = await ctl.sendTo("controller", new lib.InstanceSaveDetailsListRequest()); saves = saves.filter(save => save.instanceId === instanceId); - ctl.output.result(saves, () => print(asTable(saves.map( - ({ mtimeMs, ...rest }) => ({ ...rest, mtime: new Date(mtimeMs).toLocaleString() }) - )))); + ctl.output.table(saves, ({ mtimeMs, ...rest }) => ({ ...rest, mtime: new Date(mtimeMs).toLocaleString() })); }, })); diff --git a/packages/ctl/src/commands_log.ts b/packages/ctl/src/commands_log.ts index a66abdd8..312a79c8 100644 --- a/packages/ctl/src/commands_log.ts +++ b/packages/ctl/src/commands_log.ts @@ -27,7 +27,7 @@ logCommands.add(new lib.Command({ let hostIds = args.host ? [await lib.resolveHost(ctl, args.host)] : []; await ctl.setLogSubscriptions({ all: args.all, controller: args.controller, hostIds, instanceIds }); ctl.keepOpen = true; - ctl.output.streaming = true; + ctl.output.streamingLog = true; }, })); diff --git a/packages/ctl/src/commands_note.ts b/packages/ctl/src/commands_note.ts index 21dd41bd..abe8d64a 100644 --- a/packages/ctl/src/commands_note.ts +++ b/packages/ctl/src/commands_note.ts @@ -1,6 +1,6 @@ import * as lib from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { asTable, print } from "./command_ops.js"; +import { print } from "./command_ops.js"; export const noteCommands = new lib.CommandTree({ name: "note", description: "Notes attached to hosts, instances, users and other resources", @@ -16,12 +16,12 @@ noteCommands.add(new lib.Command({ if (args.type !== undefined) { notes = notes.filter(note => note.resourceType === args.type); } - ctl.output.result(notes, () => print(asTable(notes.map(note => ({ + ctl.output.table(notes, note => ({ type: note.resourceType, id: note.resourceId, updatedBy: note.updatedBy, content: note.content, - }))))); + })); }, })); diff --git a/packages/ctl/src/commands_user.ts b/packages/ctl/src/commands_user.ts index 434e5a8b..54991509 100644 --- a/packages/ctl/src/commands_user.ts +++ b/packages/ctl/src/commands_user.ts @@ -56,7 +56,7 @@ userCommands.add(new lib.Command({ }], handler: async function(args: { stats: boolean, attributes: boolean }, ctl: Ctl) { const users = await ctl.send(new lib.UserListRequest()); - const rows = users.map(user => { + ctl.output.table(users, user => { const { playerStats, isDeleted, banReason, instanceStats, isAdmin, isWhitelisted, isBanned, ...row } = user; @@ -66,7 +66,6 @@ userCommands.add(new lib.Command({ ...args.stats && playerStats, }; }); - ctl.output.result(users, () => print(asTable(rows))); }, })); diff --git a/test/ctl/command_ops.test.js b/test/ctl/command_ops.test.js index 175318bd..823faa3e 100644 --- a/test/ctl/command_ops.test.js +++ b/test/ctl/command_ops.test.js @@ -64,16 +64,25 @@ describe("ctl/command_ops", function() { it("prints success for commands without a result", function() { assert.deepEqual(captureLog(() => new CommandOutput("json").finish()), ['{"success":true}']); const streaming = new CommandOutput("json"); - streaming.streaming = true; + streaming.streamingLog = true; assert.deepEqual(captureLog(() => streaming.finish()), []); }); it("prints errors as JSON", function() { const output = new CommandOutput("json"); const lines = captureLog(() => { - output.error(new lib.CommandError("failed")); + output.error(new lib.CommandError("failed"), () => assert.fail("called human formatter")); output.finish(); }); assert.deepEqual(lines, ['{"error":"CommandError","message":"failed"}']); }); + it("calls the human error reporter in human mode", function() { + const output = new CommandOutput("human"); + const human = () => console.log("failed"); // eslint-disable-line no-console + const lines = captureLog(() => { + output.error(new lib.CommandError("failed"), human); + output.finish(); + }); + assert.deepEqual(lines, ["failed"]); + }); }); }); From f49c633e77964cf20df889a00c39d1c48a971a11 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Thu, 19 Nov 2026 16:05:08 +0000 Subject: [PATCH 08/20] Cover ctl output paths and stop deleting fields before printing user show, mod list, mod search and mod-pack list deleted fields off the received objects to trim the table, which made their toJSON throw in wire mode. They now pick the fields for the human table only and print the whole objects in json and wire mode. Add integration cases for config edit on the controller, a host and an instance, user show with instance stats, log query and host pending in human mode, mod-pack show with mods and settings, and wire output of the trimmed lists. Co-Authored-By: Claude Opus 5.5 --- packages/ctl/src/command_ops.ts | 8 ++++ packages/ctl/src/commands_mod.ts | 26 ++--------- packages/ctl/src/commands_mod_pack.ts | 13 +----- packages/ctl/src/commands_user.ts | 33 +++++--------- test/integration/clusterio.js | 63 +++++++++++++++++++++++++++ 5 files changed, 88 insertions(+), 55 deletions(-) diff --git a/packages/ctl/src/command_ops.ts b/packages/ctl/src/command_ops.ts index 258eea00..54c9373f 100644 --- a/packages/ctl/src/command_ops.ts +++ b/packages/ctl/src/command_ops.ts @@ -14,6 +14,14 @@ function formatCell(value: unknown) { export const asTable = asTableModule.configure({ delimiter: " | ", print: formatCell }); +/** Copy of object with only the given fields, or all of them if fields includes "all" */ +export function pickFields(object: object, fields: string[]) { + if (fields.includes("all")) { + return object; + } + return Object.fromEntries(Object.entries(object).filter(([field]) => fields.includes(field))); +} + /** Convert class instances, Sets and Maps into plain JSON values, ignoring wire format toJSON methods */ export function toPlain(value: unknown): unknown { if (value instanceof Set || value instanceof Array) { diff --git a/packages/ctl/src/commands_mod.ts b/packages/ctl/src/commands_mod.ts index 188a1b9e..f81b9abf 100644 --- a/packages/ctl/src/commands_mod.ts +++ b/packages/ctl/src/commands_mod.ts @@ -7,7 +7,7 @@ import util from "util"; import * as lib from "@clusterio/lib"; import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { asTable, print } from "./command_ops.js"; +import { asTable, pickFields, print } from "./command_ops.js"; const finished = util.promisify(stream.finished); export const modCommands = new lib.CommandTree({ name: "mod", description: "Manage uploaded mods" }); @@ -49,17 +49,7 @@ modCommands.add(new lib.Command({ }], handler: async function(args: { fields: string[] }, ctl: Ctl) { let mods = await ctl.send(new lib.ModListRequest()); - if (!args.fields.includes("all")) { - for (let entry of mods) { - for (let field of Object.keys(entry)) { - if (!args.fields.includes(field)) { - // @ts-expect-error terrible hack - delete entry[field]; - } - } - } - } - ctl.output.table(mods); + ctl.output.table(mods, mod => pickFields(mod, args.fields)); }, })); @@ -120,16 +110,6 @@ modCommands.add(new lib.Command({ args.sortOrder )); let results = response.results.flatMap(result => result.versions); - if (!args.fields.includes("all")) { - for (let entry of results) { - for (let field of Object.keys(entry)) { - if (!args.fields.includes(field)) { - // @ts-expect-error terrible hack - delete entry[field]; - } - } - } - } ctl.output.result({ page: args.page, pageCount: response.pageCount, @@ -141,7 +121,7 @@ modCommands.add(new lib.Command({ print(issue); } print(`page ${args.page} of ${response.pageCount} (${response.resultCount} results)`); - print(asTable(results)); + print(asTable(results.map(mod => pickFields(mod, args.fields)))); }); }, })); diff --git a/packages/ctl/src/commands_mod_pack.ts b/packages/ctl/src/commands_mod_pack.ts index 7b87aab6..6f71c0a2 100644 --- a/packages/ctl/src/commands_mod_pack.ts +++ b/packages/ctl/src/commands_mod_pack.ts @@ -1,7 +1,7 @@ import * as lib from "@clusterio/lib"; import { logger } from "@clusterio/lib"; import type { Ctl } from "../ctl.js"; -import { print } from "./command_ops.js"; +import { pickFields, print } from "./command_ops.js"; export const modPackCommands = new lib.CommandTree({ name: "mod-pack", description: "Mod Pack" }); modPackCommands.add(new lib.Command({ @@ -58,16 +58,7 @@ modPackCommands.add(new lib.Command({ definition: [["list", "l"], "List mod packs in the cluster"], handler: async function(args: object, ctl: Ctl) { let modPacks = await ctl.send(new lib.ModPackListRequest()); - let fields = ["id", "name", "factorioVersion"]; - for (let entry of modPacks) { - for (let field of Object.keys(entry)) { - if (!fields.includes(field)) { - // @ts-expect-error terrible hack - delete entry[field]; - } - } - } - ctl.output.table(modPacks); + ctl.output.table(modPacks, modPack => pickFields(modPack, ["id", "name", "factorioVersion"])); }, })); diff --git a/packages/ctl/src/commands_user.ts b/packages/ctl/src/commands_user.ts index 54991509..525a45d7 100644 --- a/packages/ctl/src/commands_user.ts +++ b/packages/ctl/src/commands_user.ts @@ -18,27 +18,18 @@ userCommands.add(new lib.Command({ }); }], handler: async function(args: { name: string, instanceStats: boolean }, ctl: Ctl) { - let user = await ctl.send(new lib.UserGetRequest(args.name)); - Object.assign(user, user.playerStats); - // @ts-expect-error Terrible hack - delete user.playerStats; - let instanceStats = user.instanceStats; - // @ts-expect-error Terrible hack - delete user.instanceStats; - if (!args.instanceStats) { - ctl.output.result(user, () => printProperties(user)); - return; - } - - let instances = await ctl.send(new lib.InstanceDetailsListRequest()); - const stats = [...instanceStats || []].map(([id, playerInstanceStats]) => ({ - id, - name: instances.find(i => i.id === id)?.name ?? "", - stats: playerInstanceStats, - })); - ctl.output.result({ ...user, instanceStats: stats }, () => { - printProperties(user); - for (let { id, name, stats: playerInstanceStats } of stats) { + const user = await ctl.send(new lib.UserGetRequest(args.name)); + const { playerStats, instanceStats, ...properties } = user; + const instances = args.instanceStats && ctl.output.human + ? await ctl.send(new lib.InstanceDetailsListRequest()) + : []; + ctl.output.result(user, () => { + printProperties({ ...properties, ...playerStats }); + if (!args.instanceStats) { + return; + } + for (let [id, playerInstanceStats] of instanceStats) { + const name = instances.find(i => i.id === id)?.name ?? ""; print(); print(`Instance ${name} (${id}):`); printProperties(playerInstanceStats); diff --git a/test/integration/clusterio.js b/test/integration/clusterio.js index 091319b7..2afc9926 100644 --- a/test/integration/clusterio.js +++ b/test/integration/clusterio.js @@ -2064,6 +2064,9 @@ describe("Integration of Clusterio", function() { const roundtrip = lib.ModPack.fromModPackString(result.stdout.trim()); roundtrip.id = reference.id; assert.deepEqual(roundtrip, reference); + const shown = await execCtlOutput("mod-pack show imported-pack"); + assert.match(shown, /empty_mod 1\.0\.0/); + assert.match(shown, /MyDouble: 12\.25/); }); }); @@ -2317,6 +2320,46 @@ describe("Integration of Clusterio", function() { }); }); + describe("config edit", function() { + /** Write an editor script that replaces the edited file with content */ + async function writeEditor(content) { + const file = path.resolve("temp", "test", "editor.sh"); + await fs.writeFile(file, `#!/bin/sh\ncat > "$1" <<'EOF'\n${content}\nEOF\n`, { mode: 0o755 }); + return file; + } + before(function() { + if (process.platform === "win32") { + this.skip(); + } + }); + + it("sets controller config fields and reports failed ones", async function() { + const config = await getControl().send(new lib.ControllerConfigGetRequest()); + const name = config["controller.name"]; + const editor = await writeEditor("controller.name = Edited-Cluster\ncontroller.no_such_field = 1"); + await execCtl(`controller config edit ${editor}`); + const edited = await getControl().send(new lib.ControllerConfigGetRequest()); + assert.equal(edited["controller.name"], "Edited-Cluster"); + await execCtl(`controller config set controller.name ${name}`); + }); + it("sets host config fields and reports failed ones", async function() { + const config = await getControl().sendTo({ hostId }, new lib.HostConfigGetRequest()); + const editor = await writeEditor(`host.name = ${config["host.name"]}\nhost.no_such_field = 1`); + await execCtl(`host config edit ${hostId} ${editor}`); + }); + it("sets instance config fields and reports failed ones", async function() { + const { id } = JSON.parse(await execCtlOutput("--output json instance create config-edit")); + try { + const editor = await writeEditor("instance.auto_start = true\ninstance.no_such_field = 1"); + await execCtl(`instance config edit ${id} ${editor}`); + const config = await getControl().send(new lib.InstanceConfigGetRequest(id)); + assert.equal(config["instance.auto_start"], true); + } finally { + await execCtl(`instance delete ${id}`); + } + }); + }); + describe("--output json", function() { it("prints lists as an array of objects", async function() { const roles = JSON.parse(await execCtlOutput("--output json role list")); @@ -2339,6 +2382,26 @@ describe("Integration of Clusterio", function() { const { id } = JSON.parse(await execCtlOutput("--output json role create human-role")); assert.equal(await execCtlOutput(`role delete ${id}`), "Command ran successfully"); }); + it("prints whole objects for lists that hide fields in human mode", async function() { + const [mod] = JSON.parse(await execCtlOutput("--output json mod list")); + assert("sha1" in mod); + const [wireMod] = JSON.parse(await execCtlOutput("--output wire mod list")); + assert("factorio_version" in wireMod); + const [modPack] = JSON.parse(await execCtlOutput("--output wire mod-pack list")); + assert("mods" in modPack); + const user = JSON.parse(await execCtlOutput("--output wire user show test --instance-stats")); + assert.equal(user.name, "test"); + }); + it("prints the user and instance stats in human mode", async function() { + const output = await execCtlOutput("user show test --instance-stats"); + assert.match(output, /name +\| test/); + }); + it("prints log queries in human mode", async function() { + assert.notEqual(await execCtlOutput("log query --controller --limit 1"), ""); + }); + it("prints pending host requests in human mode", async function() { + assert.notEqual(await execCtlOutput("host pending"), ""); + }); it("prints log queries as an array", async function() { const log = JSON.parse(await execCtlOutput("--output json log query --controller --limit 1")); assert.equal(log.length, 1); From f52821d1cdd2654d73137fdae49b4d0ca5b561f4 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Thu, 19 Nov 2026 16:14:58 +0000 Subject: [PATCH 09/20] Cover ctl output code that only ran in child processes CI coverage does not measure the ctl processes the integration tests start, so cover the Ctl log and debug event handlers, start-all, stop-all and pickFields with unit tests, and run mod show, user list flags, parse-exchange-string and log follow in process. Co-Authored-By: Claude Opus 5.5 --- test/ctl/command_ops.test.js | 9 ++- test/ctl/commands_instance.test.js | 91 ++++++++++++++++++++++++++++++ test/ctl/ctl.test.js | 56 ++++++++++++++++++ test/integration/clusterio.js | 15 +++++ 4 files changed, 170 insertions(+), 1 deletion(-) create mode 100644 test/ctl/commands_instance.test.js create mode 100644 test/ctl/ctl.test.js diff --git a/test/ctl/command_ops.test.js b/test/ctl/command_ops.test.js index 823faa3e..6814ceb9 100644 --- a/test/ctl/command_ops.test.js +++ b/test/ctl/command_ops.test.js @@ -1,6 +1,6 @@ import assert from "node:assert/strict"; import * as lib from "@clusterio/lib"; -import { CommandOutput, errorToJson, toPlain } from "@clusterio/ctl/dist/node/src/command_ops.js"; +import { CommandOutput, errorToJson, pickFields, toPlain } from "@clusterio/ctl/dist/node/src/command_ops.js"; /** Run fn and return the lines it printed with console.log */ function captureLog(fn) { @@ -29,6 +29,13 @@ describe("ctl/command_ops", function() { }); }); + describe("pickFields()", function() { + it("keeps only the given fields unless all is given", function() { + assert.deepEqual(pickFields({ a: 1, b: 2 }, ["a"]), { a: 1 }); + assert.deepEqual(pickFields({ a: 1, b: 2 }, ["all"]), { a: 1, b: 2 }); + }); + }); + describe("errorToJson()", function() { it("uses the class name of the error", function() { assert.deepEqual(errorToJson(new lib.NotFoundError("gone")), { error: "NotFoundError", message: "gone" }); diff --git a/test/ctl/commands_instance.test.js b/test/ctl/commands_instance.test.js new file mode 100644 index 00000000..040503e3 --- /dev/null +++ b/test/ctl/commands_instance.test.js @@ -0,0 +1,91 @@ +import assert from "node:assert/strict"; +import * as lib from "@clusterio/lib"; +import { instanceCommands } from "@clusterio/ctl/dist/node/src/commands_instance.js"; +import { CommandOutput } from "@clusterio/ctl/dist/node/src/command_ops.js"; + +/** Run fn and return the lines it printed with console.log */ +async function captureLog(fn) { + const lines = []; + const originalLog = console.log; // eslint-disable-line no-console + console.log = (...args) => lines.push(args.join(" ")); // eslint-disable-line no-console + try { + await fn(); + } finally { + console.log = originalLog; // eslint-disable-line no-console + } + return lines; +} + +describe("ctl/commands_instance", function() { + let instances; + let sentTo; + const ctl = { + output: new CommandOutput(), + async send(message) { + assert(message instanceof lib.InstanceDetailsListRequest); + return instances; + }, + async sendTo(destination, message) { + sentTo.push([destination.instanceId, message.constructor.name]); + if (destination.instanceId === 2) { + throw new lib.CommandError("broken"); + } + }, + }; + beforeEach(function() { + sentTo = []; + instances = [ + { id: 1, name: "one", status: "stopped", excludeFromStartAll: false }, + { id: 2, name: "two", status: "stopped", excludeFromStartAll: false }, + { id: 3, name: "three", status: "stopped", excludeFromStartAll: true }, + { id: 4, name: "four", status: "running", excludeFromStartAll: false }, + ]; + }); + + describe("start-all", function() { + const startAll = instanceCommands.get("start-all"); + it("starts stopped instances and reports each one", async function() { + ctl.output = new CommandOutput("human"); + const lines = await captureLog(() => startAll.run({ force: false }, ctl)); + assert.deepEqual(sentTo, [[1, "InstanceStartRequest"], [2, "InstanceStartRequest"]]); + assert(lines.includes("✓ Started one"), lines.join("\n")); + assert(lines.some(line => line.startsWith("✗ Failed to start two")), lines.join("\n")); + }); + it("prints an entry per instance in json mode", async function() { + ctl.output = new CommandOutput("json"); + const lines = await captureLog(() => startAll.run({ force: true }, ctl)); + assert.deepEqual(JSON.parse(lines[0]), [ + { id: 1, name: "one" }, + { id: 2, name: "two", error: { error: "CommandError", message: "broken" } }, + { id: 3, name: "three" }, + ]); + }); + it("reports when there is nothing to start", async function() { + instances = []; + ctl.output = new CommandOutput("human"); + assert.deepEqual(await captureLog(() => startAll.run({ force: false }, ctl)), ["No instances to start."]); + }); + }); + + describe("stop-all", function() { + const stopAll = instanceCommands.get("stop-all"); + it("stops running instances and reports each one", async function() { + instances[1].status = "running"; + ctl.output = new CommandOutput("human"); + const lines = await captureLog(() => stopAll.run({}, ctl)); + assert.deepEqual(sentTo, [[2, "InstanceStopRequest"], [4, "InstanceStopRequest"]]); + assert(lines.includes("✓ Stopped four"), lines.join("\n")); + assert(lines.some(line => line.startsWith("✗ Failed to stop two")), lines.join("\n")); + }); + it("prints an entry per instance in json mode", async function() { + ctl.output = new CommandOutput("json"); + const lines = await captureLog(() => stopAll.run({}, ctl)); + assert.deepEqual(JSON.parse(lines[0]), [{ id: 4, name: "four" }]); + }); + it("reports when there is nothing to stop", async function() { + instances = []; + ctl.output = new CommandOutput("human"); + assert.deepEqual(await captureLog(() => stopAll.run({}, ctl)), ["No instances to stop."]); + }); + }); +}); diff --git a/test/ctl/ctl.test.js b/test/ctl/ctl.test.js new file mode 100644 index 00000000..4e2d9b56 --- /dev/null +++ b/test/ctl/ctl.test.js @@ -0,0 +1,56 @@ +import assert from "node:assert/strict"; +import * as lib from "@clusterio/lib"; +import { Ctl } from "@clusterio/ctl/dist/node/ctl.js"; +import { CommandOutput } from "@clusterio/ctl/dist/node/src/command_ops.js"; + +/** Run fn and return the lines it printed with console.log */ +async function captureLog(fn) { + const lines = []; + const originalLog = console.log; // eslint-disable-line no-console + console.log = (...args) => lines.push(args.join(" ")); // eslint-disable-line no-console + try { + await fn(); + } finally { + console.log = originalLog; // eslint-disable-line no-console + } + return lines; +} + +describe("ctl/ctl", function() { + describe("class Ctl", function() { + let ctl; + beforeEach(function() { + const connector = new lib.VirtualConnector( + lib.Address.fromShorthand({ controlId: 1 }), + lib.Address.fromShorthand("controller"), + ); + ctl = new Ctl(connector, new lib.CtlConfig("control")); + }); + + it("prints log events as JSON lines only when streaming the log", async function() { + const info = { level: "info", message: "hello" }; + ctl.output = new CommandOutput("json"); + const logged = await captureLog(() => ctl.handleLogMessageEvent(new lib.LogMessageEvent({ ...info }))); + assert(logged.every(line => !line.startsWith("{")), "log event printed as a result"); + ctl.output.streamingLog = true; + assert.deepEqual( + await captureLog(() => ctl.handleLogMessageEvent(new lib.LogMessageEvent({ ...info, timestamp: 1 }))), + ['{"level":"info","message":"hello","timestamp":1}'], + ); + }); + it("logs log events in human mode", async function() { + ctl.output.streamingLog = true; + const info = { level: "verbose", message: "hello" }; + assert.deepEqual(await captureLog(() => ctl.handleLogMessageEvent(new lib.LogMessageEvent(info))), []); + }); + it("prints debug WebSocket messages", async function() { + const event = new lib.DebugWsMessageEvent("in", "content"); + assert.deepEqual(await captureLog(() => ctl.handleDebugWsMessageEvent(event)), ["WS in content"]); + ctl.output = new CommandOutput("json"); + assert.deepEqual( + await captureLog(() => ctl.handleDebugWsMessageEvent(event)), + ['{"direction":"in","content":"content"}'], + ); + }); + }); +}); diff --git a/test/integration/clusterio.js b/test/integration/clusterio.js index 2afc9926..1c68a5d2 100644 --- a/test/integration/clusterio.js +++ b/test/integration/clusterio.js @@ -2122,6 +2122,7 @@ describe("Integration of Clusterio", function() { describe("mod show", function() { it("gives details of a mod", async function() { + assert.match(await execCtlOutput("mod show empty_mod 1.0.0"), /name: empty_mod/); let result = await execCtlProcess("mod show empty_mod 1.0.0"); let hash = await lib.hashFile(path.join("temp", "test", "mods", "empty_mod_1.0.0.zip")); let stat = await fs.stat(path.join("temp", "test", "mods", "empty_mod_1.0.0.zip")); @@ -2396,6 +2397,20 @@ describe("Integration of Clusterio", function() { const output = await execCtlOutput("user show test --instance-stats"); assert.match(output, /name +\| test/); }); + it("prints the result of human mode commands with more options", async function() { + assert.match(await execCtlOutput("user list --stats --attributes"), /isAdmin/); + const exchange = JSON.parse(await execCtlOutput( + `--output json debug parse-exchange-string ${testStrings.default.replace(/\s/g, "")}` + )); + assert.equal(typeof exchange, "object"); + }); + it("follows the log without a final result", async function() { + try { + assert.equal(await execCtlOutput("--output json log follow --controller"), ""); + } finally { + getControl().keepOpen = false; + } + }); it("prints log queries in human mode", async function() { assert.notEqual(await execCtlOutput("log query --controller --limit 1"), ""); }); From c5ad1953adfcd4d13a3ebce1dfd58a0bb047cb73 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Thu, 19 Nov 2026 16:20:21 +0000 Subject: [PATCH 10/20] Unit test mod show and user show output Co-Authored-By: Claude Opus 5.5 --- test/ctl/commands.test.js | 66 +++++++++++++++++++++++++++++++++++++++ 1 file changed, 66 insertions(+) create mode 100644 test/ctl/commands.test.js diff --git a/test/ctl/commands.test.js b/test/ctl/commands.test.js new file mode 100644 index 00000000..05b5fd0e --- /dev/null +++ b/test/ctl/commands.test.js @@ -0,0 +1,66 @@ +import assert from "node:assert/strict"; +import * as lib from "@clusterio/lib"; +import { modCommands } from "@clusterio/ctl/dist/node/src/commands_mod.js"; +import { userCommands } from "@clusterio/ctl/dist/node/src/commands_user.js"; +import { CommandOutput } from "@clusterio/ctl/dist/node/src/command_ops.js"; + +/** Run fn and return the lines it printed with console.log */ +async function captureLog(fn) { + const lines = []; + const originalLog = console.log; // eslint-disable-line no-console + console.log = (...args) => lines.push(args.join(" ")); // eslint-disable-line no-console + try { + await fn(); + } finally { + console.log = originalLog; // eslint-disable-line no-console + } + return lines; +} + +/** Mock ctl answering requests by their class */ +function mockCtl(responses) { + return { + output: new CommandOutput(), + async send(message) { + return responses.get(message.constructor)(message); + }, + }; +} + +describe("ctl/commands", function() { + describe("mod show", function() { + const show = modCommands.get("show"); + it("prints list fields one entry per line", async function() { + const ctl = mockCtl(new Map([ + [lib.ModGetRequest, () => ({ name: "a_mod", dependencies: ["base", "? other"] })], + ])); + const lines = await captureLog(() => show.run({ name: "a_mod", modVersion: "1.0.0" }, ctl)); + assert.deepEqual(lines, ["name: a_mod", "dependencies:", " base", " ? other"]); + }); + it("rejects an invalid version", async function() { + await assert.rejects( + show.run({ name: "a_mod", modVersion: "latest" }, mockCtl(new Map())), + new lib.CommandError("mod-version must match format digit.digit.digit"), + ); + }); + }); + + describe("user show", function() { + const show = userCommands.get("show"); + it("prints stats per instance", async function() { + const stats = new lib.PlayerStats(); + stats.joinCount = 2; + const user = new lib.UserDetails("alice"); + user.instanceStats = new Map([[1, stats], [2, stats]]); + user.recalculatePlayerStats(); + const ctl = mockCtl(new Map([ + [lib.UserGetRequest, () => user], + [lib.InstanceDetailsListRequest, () => [{ id: 1, name: "one" }]], + ])); + const lines = await captureLog(() => show.run({ name: "alice", instanceStats: true }, ctl)); + assert(lines.includes("Instance one (1):"), lines.join("\n")); + assert(lines.includes("Instance (2):"), lines.join("\n")); + assert(lines.some(line => /joinCount +\| 4/.test(line)), lines.join("\n")); + }); + }); +}); From 3aefcb062f6624fbe3bb5ee0a390c5c8d5a7690d Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Thu, 19 Nov 2026 16:26:37 +0000 Subject: [PATCH 11/20] Unit test mod-pack show warnings and export assets Co-Authored-By: Claude Opus 5.5 --- test/ctl/commands.test.js | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/test/ctl/commands.test.js b/test/ctl/commands.test.js index 05b5fd0e..86bdf56b 100644 --- a/test/ctl/commands.test.js +++ b/test/ctl/commands.test.js @@ -1,6 +1,7 @@ import assert from "node:assert/strict"; import * as lib from "@clusterio/lib"; import { modCommands } from "@clusterio/ctl/dist/node/src/commands_mod.js"; +import { modPackCommands } from "@clusterio/ctl/dist/node/src/commands_mod_pack.js"; import { userCommands } from "@clusterio/ctl/dist/node/src/commands_user.js"; import { CommandOutput } from "@clusterio/ctl/dist/node/src/command_ops.js"; @@ -24,6 +25,9 @@ function mockCtl(responses) { async send(message) { return responses.get(message.constructor)(message); }, + async sendTo(destination, message) { + return this.send(message); + }, }; } @@ -45,6 +49,24 @@ describe("ctl/commands", function() { }); }); + describe("mod-pack show", function() { + it("marks missing mods and checksum mismatches and lists export assets", async function() { + const modPack = lib.ModPack.fromJSON({ id: 7, name: "pack" }); + modPack.mods.set("gone", { name: "gone", enabled: true, version: "1.0.0" }); + modPack.mods.set("changed", { name: "changed", enabled: false, version: "1.0.0", sha1: "aaa" }); + modPack.exportManifest = { assets: { settings: "settings.json" } }; + const ctl = mockCtl(new Map([ + [lib.ModListRequest, () => [{ id: "changed_1.0.0", sha1: "bbb" }]], + [lib.ModPackListRequest, () => [modPack]], + [lib.ModPackGetRequest, () => modPack], + ])); + const lines = await captureLog(() => modPackCommands.get("show").run({ modPack: "pack" }, ctl)); + assert(lines.includes(" ? gone 1.0.0"), lines.join("\n")); + assert(lines.includes(" ! (disabled) changed 1.0.0 (aaa)"), lines.join("\n")); + assert(lines.includes(" settings: settings.json"), lines.join("\n")); + }); + }); + describe("user show", function() { const show = userCommands.get("show"); it("prints stats per instance", async function() { From dbedc4bc0842a9c4cbe7ce38374ae80b719babdb Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Thu, 19 Nov 2026 20:02:31 +0000 Subject: [PATCH 12/20] Add a Factorio 1.1 variant to the subspace_storage test stub The 1.1 test jobs failed because the test mod pack asked for subspace_storage 2.3.11, which the stub did not build. The real mod publishes 2.3.11 for 1.1. Co-Authored-By: Claude Opus 5.5 --- test/integration/index.js | 1 + 1 file changed, 1 insertion(+) diff --git a/test/integration/index.js b/test/integration/index.js index 0d34f024..2f3fbadd 100644 --- a/test/integration/index.js +++ b/test/integration/index.js @@ -360,6 +360,7 @@ before(async function() { await fs.writeFile(path.join(subspaceStorageDir, "info.json"), JSON.stringify({ name: "subspace_storage", variants: [ + { version: "2.3.11", factorio_version: "1.1" }, { version: "2.3.20", factorio_version: "2.0" }, { version: "2.3.21", factorio_version: "2.1" }, ], From aaafce4ace885aa40e58b0fe7591aeb67058b8d0 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Thu, 19 Nov 2026 20:39:58 +0000 Subject: [PATCH 13/20] Keep yauzl and yazl types out of lib's published declarations ZipArchive exposed yauzl.ZipFile and yauzl.Entry in its public members and zipOutputStream took a yazl.ZipFile, so @types/yauzl and @types/yazl had to be runtime dependencies of @clusterio/lib. They pull in @types/node and undici-types, about 2.7 MB in every server install. Entries are now typed with a local ZipEntry interface, the yauzl ZipFile is private, and zipOutputStream takes any object with an outputStream and an error event. ZipWriter.addEntry reads the compressed bytes through the new ZipArchive.openRawStream. Both type packages move to devDependencies. Co-Authored-By: Claude Opus 5.5 --- packages/lib/package.json | 4 +-- packages/lib/src/zip_ops.ts | 49 +++++++++++++++++++++++++++++-------- 2 files changed, 41 insertions(+), 12 deletions(-) diff --git a/packages/lib/package.json b/packages/lib/package.json index 53a1ba2b..aca70df1 100644 --- a/packages/lib/package.json +++ b/packages/lib/package.json @@ -51,8 +51,6 @@ "dependencies": { "@sinclair/typebox": "catalog:", - "@types/yauzl": "catalog:", - "@types/yazl": "catalog:", "ajv": "^8.20.0", "chalk": "catalog:", "fast-deep-equal": "^3.1.3", @@ -71,6 +69,8 @@ "@types/triple-beam": "^1.3.5", "@types/ws": "catalog:", "@types/yargs": "catalog:", + "@types/yauzl": "catalog:", + "@types/yazl": "catalog:", "typescript": "catalog:" } } diff --git a/packages/lib/src/zip_ops.ts b/packages/lib/src/zip_ops.ts index b7087caf..c8a12037 100644 --- a/packages/lib/src/zip_ops.ts +++ b/packages/lib/src/zip_ops.ts @@ -7,10 +7,28 @@ import { PassThrough, type Readable } from "stream"; import util from "util"; import zlib from "zlib"; import yauzl from "yauzl"; -import type yazl from "yazl"; const deflateRaw = util.promisify(zlib.deflateRaw); +/** + * Entry in a ZipArchive + */ +export interface ZipEntry { + fileName: string; + fileComment: string; + versionMadeBy: number; + versionNeededToExtract: number; + generalPurposeBitFlag: number; + compressionMethod: number; + lastModFileTime: number; + lastModFileDate: number; + crc32: number; + compressedSize: number; + uncompressedSize: number; + externalFileAttributes: number; + getLastModDate(options?: { timezone?: "local" | "UTC" | null, forceDosFormat?: boolean }): Date; +} + /** * Zip archive opened for random access reading @@ -21,10 +39,9 @@ const deflateRaw = util.promisify(zlib.deflateRaw); */ export class ZipArchive { private constructor( - /** Underlying yauzl zip file. */ - public zipfile: yauzl.ZipFile, + private zipfile: yauzl.ZipFile, /** Entries by file name in the order they appear in the central directory. */ - public entries: Map, + public entries: Map, ) { } /** @@ -77,8 +94,17 @@ export class ZipArchive { * * @param entry - Entry to read, must belong to this archive. */ - openStream(entry: yauzl.Entry): Promise { - return this.zipfile.openReadStreamPromise(entry); + openStream(entry: ZipEntry): Promise { + return this.zipfile.openReadStreamPromise(entry as yauzl.Entry); + } + + /** + * Open a stream of the content of an entry as stored in the archive + * + * @param entry - Entry to read, must belong to this archive. + */ + openRawStream(entry: ZipEntry): Promise { + return this.zipfile.openReadStreamPromise(entry as yauzl.Entry, { decodeFileData: false }); } /** @@ -86,7 +112,7 @@ export class ZipArchive { * * @param entry - Entry to read, must belong to this archive. */ - async readEntry(entry: yauzl.Entry) { + async readEntry(entry: ZipEntry) { const chunks: Buffer[] = []; for await (const chunk of await this.openStream(entry)) { chunks.push(chunk); @@ -153,7 +179,10 @@ export function findRoot(zip: ZipArchive) { * * @param zipFile - zip file being written. */ -export function zipOutputStream(zipFile: yazl.ZipFile) { +export function zipOutputStream(zipFile: { + outputStream: NodeJS.ReadableStream, + on(event: "error", listener: (err: Error) => void): unknown, +}) { const output = zipFile.outputStream as Readable; zipFile.on("error", err => output.destroy(err)); return output; @@ -224,7 +253,7 @@ export class ZipWriter { * @param zip - Archive to copy from. * @param entry - Entry to copy, must belong to zip. */ - async addEntry(zip: ZipArchive, entry: yauzl.Entry) { + async addEntry(zip: ZipArchive, entry: ZipEntry) { const writerEntry: WriterEntry = { fileName: Buffer.from(entry.fileName, "utf8"), fileComment: Buffer.from(entry.fileComment, "utf8"), @@ -242,7 +271,7 @@ export class ZipWriter { offset: this.offset, }; await this.write(this.localFileHeader(writerEntry)); - const stream = await zip.zipfile.openReadStreamPromise(entry, { decodeFileData: false }); + const stream = await zip.openRawStream(entry); for await (const chunk of stream) { await this.write(chunk); } From 909f6ab08b40447d4140670fb3b849182e281917 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:17:40 +0000 Subject: [PATCH 14/20] Move ModInfo.fromModFile to ModStore.readModInfo Reading a mod zip needs zip_ops, which pulled yauzl into the web interface bundle through the data classes. ModStore is node only, so the zip reading now lives there. Co-Authored-By: Claude Opus 5.5 --- packages/controller/src/routes.ts | 2 +- packages/lib/src/ModStore.ts | 40 ++++++++++++++++++++++++++++++- packages/lib/src/data/ModInfo.ts | 34 -------------------------- test/lib/ModStore.test.js | 35 ++++++++++++++++++++++++++- test/lib/data/ModInfo.js | 32 ------------------------- 5 files changed, 74 insertions(+), 69 deletions(-) diff --git a/packages/controller/src/routes.ts b/packages/controller/src/routes.ts index 9c5121d5..48348726 100644 --- a/packages/controller/src/routes.ts +++ b/packages/controller/src/routes.ts @@ -828,7 +828,7 @@ async function uploadMod(req: Request, res: Response) { // Pipe does not pass on an upload that was cut short. await Promise.all([finished(file.stream), finished(writeStream)]); - const modInfo = await lib.ModInfo.fromModFile(tempFilePath); + const modInfo = await lib.ModStore.readModInfo(tempFilePath); checkModName(modInfo.filename); await fs.rename(tempFilePath, path.join(modsDirectory, modInfo.filename)); req.app.locals.controller.modStore.addMod(modInfo); diff --git a/packages/lib/src/ModStore.ts b/packages/lib/src/ModStore.ts index 3efb7a5b..f9ba4c84 100644 --- a/packages/lib/src/ModStore.ts +++ b/packages/lib/src/ModStore.ts @@ -4,6 +4,8 @@ import events from "events"; import { Static } from "@sinclair/typebox"; import { logger } from "./logging.js"; import { downloadFile, atomicOverwriteFile } from "./file_ops.js"; +import { hashFile } from "./hash.js"; +import { ZipArchive, findRoot } from "./zip_ops.js"; import { ModPortalReleaseSchema, ModPortalDetailsSchema, ModNameVersionPair } from "./data/messages_mod.js"; import { ModInfo, ModPack, MajorMinorVersion, ModVersionEquality, SourceVersion } from "./data/index.js"; @@ -54,8 +56,44 @@ export default class ModStore extends events.EventEmitter { mods() { return this.files.values(); } + /** + * Read the info.json of a mod zip file along with its size, mtime and hash + * + * @param modPath - Path to the mod zip file. + * @returns Mod info for the file. + */ + static async readModInfo(modPath: string) { + let modInfo: Static; + let zip = await ZipArchive.fromFile(modPath); + try { + let content = await zip.readFile(path.posix.join(findRoot(zip), "info.json")); + if (content === null) { + throw new Error("Mod contains no info.json file"); + } + modInfo = JSON.parse(content.toString("utf8")); + } finally { + zip.close(); + } + + let valid = ModInfo.validateInfo(modInfo); + if (!valid) { + throw new Error("Mod's info.json is not valid"); + } + + const stat = await fs.stat(modPath); + return ModInfo.fromJSON({ + ...modInfo, + + size: stat.size, + sha1: await hashFile(modPath), + mtime_ms: stat.mtimeMs, + updated_at_ms: stat.mtimeMs, + is_deleted: false, + }); + } + static async loadFile(modsDirectory: string, file: string) { - let modInfo = await ModInfo.fromModFile(path.join(modsDirectory, file)); + let modInfo = await ModStore.readModInfo(path.join(modsDirectory, file)); if (modInfo.filename !== file) { throw new Error(`filename does not match the expected name ${modInfo.filename}.`); } diff --git a/packages/lib/src/data/ModInfo.ts b/packages/lib/src/data/ModInfo.ts index c44c8a6e..26420ba1 100644 --- a/packages/lib/src/data/ModInfo.ts +++ b/packages/lib/src/data/ModInfo.ts @@ -1,10 +1,6 @@ -import fs from "node:fs/promises"; -import path from "path"; import { Type, Static } from "@sinclair/typebox"; -import * as libHash from "../hash.js"; import * as libSchema from "../schema.js"; -import { ZipArchive, findRoot } from "../zip_ops.js"; import { ModRecord } from "./ModPack.js"; import { @@ -349,34 +345,4 @@ export default class ModInfo { if (this.isDeleted) { json.is_deleted = this.isDeleted; } return json; } - - static async fromModFile(modPath: string) { - let modInfo: Static; - let zip = await ZipArchive.fromFile(modPath); - try { - let content = await zip.readFile(path.posix.join(findRoot(zip), "info.json")); - if (content === null) { - throw new Error("Mod contains no info.json file"); - } - modInfo = JSON.parse(content.toString("utf8")); - } finally { - zip.close(); - } - - let valid = this.validateInfo(modInfo); - if (!valid) { - throw new Error("Mod's info.json is not valid"); - } - - const stat = await fs.stat(modPath); - return this.fromJSON({ - ...modInfo, - - size: stat.size, - sha1: await libHash.hashFile(modPath), - mtime_ms: stat.mtimeMs, - updated_at_ms: stat.mtimeMs, - is_deleted: false, - }); - } } diff --git a/test/lib/ModStore.test.js b/test/lib/ModStore.test.js index 309f3117..a2e02bfd 100644 --- a/test/lib/ModStore.test.js +++ b/test/lib/ModStore.test.js @@ -6,7 +6,8 @@ import stream from "node:stream"; // Capture native fetch before any potential mocks are applied const nativeFetch = global.fetch; -import { ModStore, ModInfo, ModVersionEquality, zipOutputStream } from "@clusterio/lib"; +import { ModStore, ModInfo, ModVersionEquality, zipOutputStream, hashFile } from "@clusterio/lib"; +import * as libBuildMod from "@clusterio/lib/build_mod.js"; import { externalTest, createZip, createZipBuffer } from "../common.js"; import "../setup_logging.js"; @@ -706,6 +707,38 @@ describe("lib/ModStore", function () { }); // === Instance Methods === + describe("readModInfo (static)", function () { + it("should load from a mod zip file", async function () { + await libBuildMod.build({ + build: true, + pack: true, + sourceDir: path.join("test", "file", "empty_mod"), + outputDir: path.join("temp", "test"), + }); + const filePath = path.join("temp", "test", "empty_mod_1.0.0.zip"); + const hash = await hashFile(filePath); + const stat = await fs.stat(filePath); + const mod = await ModStore.readModInfo(filePath); + assert.deepEqual( + mod, + ModInfo.fromJSON({ + name: "empty_mod", + version: "1.0.0", + title: "An Empty Mod", + author: "Me", + description: "An empty mod for testing", + factorio_version: "1.1", + dependencies: [], + filename: "empty_mod_1.0.0.zip", + size: stat.size, + mtime_ms: stat.mtimeMs, + updated_at_ms: stat.mtimeMs, + sha1: hash, + }) + ); + }); + }); + describe("Instance Methods", function () { let modStore; let testMod1Name = "test-mod-1"; diff --git a/test/lib/data/ModInfo.js b/test/lib/data/ModInfo.js index 68926e4a..190b5ac8 100644 --- a/test/lib/data/ModInfo.js +++ b/test/lib/data/ModInfo.js @@ -1,9 +1,6 @@ import assert from "node:assert/strict"; -import fs from "node:fs/promises"; -import path from "node:path"; import * as lib from "@clusterio/lib"; -import * as libBuildMod from "@clusterio/lib/build_mod.js"; import { ModInfo, ModDependency } from "@clusterio/lib"; import { testMatrix, testRoundTripJsonSerialisable } from "../../common.js"; @@ -413,35 +410,6 @@ describe("lib/data/ModInfo", function() { ["UltraMod", "SuperLib >= 1.00", "! bad-mod"].map(dep => new ModDependency(dep)) ); }); - it("should load from a mod zip file", async function() { - await libBuildMod.build({ - build: true, - pack: true, - sourceDir: path.join("test", "file", "empty_mod"), - outputDir: path.join("temp", "test"), - }); - const filePath = path.join("temp", "test", "empty_mod_1.0.0.zip"); - const hash = await lib.hashFile(filePath); - const stat = await fs.stat(filePath); - const mod = await ModInfo.fromModFile(filePath); - assert.deepEqual( - mod, - ModInfo.fromJSON({ - name: "empty_mod", - version: "1.0.0", - title: "An Empty Mod", - author: "Me", - description: "An empty mod for testing", - factorio_version: "1.1", - dependencies: [], - filename: "empty_mod_1.0.0.zip", - size: stat.size, - mtime_ms: stat.mtimeMs, - updated_at_ms: stat.mtimeMs, - sha1: hash, - }) - ); - }); describe("checkDependencySatisfaction()", function() { it("should return undefined when satisfied", function() { const mod = ModInfo.fromJSON({ dependencies: ["! a", "b = 1.0.0", "? c = 2.0.0"] }); From 4d7c1020b06cea288cf91e47815b672620f892fa Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:18:37 +0000 Subject: [PATCH 15/20] Use fflate for zlib in the web interface ModPack and map exchange strings need synchronous inflate and deflate. In the browser these came from the browserify-zlib polyfill, which brings pako, assert and util along. The browser build now imports fflate through a #zlib_sync subpath import, Node.js keeps node:zlib. Co-Authored-By: Claude Opus 5.5 --- packages/lib/package.json | 8 +++++++ packages/lib/src/data/ModPack.ts | 4 ++-- packages/lib/src/factorio/exchange_string.ts | 2 +- packages/lib/src/zlib_sync.browser.ts | 15 ++++++++++++ packages/lib/src/zlib_sync.node.ts | 11 +++++++++ packages/lib/tsconfig.browser.json | 1 + pnpm-workspace.yaml | 1 + test/lib/zlib_sync.test.js | 25 ++++++++++++++++++++ 8 files changed, 64 insertions(+), 3 deletions(-) create mode 100644 packages/lib/src/zlib_sync.browser.ts create mode 100644 packages/lib/src/zlib_sync.node.ts create mode 100644 test/lib/zlib_sync.test.js diff --git a/packages/lib/package.json b/packages/lib/package.json index 53a1ba2b..41749d81 100644 --- a/packages/lib/package.json +++ b/packages/lib/package.json @@ -31,6 +31,13 @@ }, "import": "./src/link/WebSocket.browser.ts" }, + "#zlib_sync": { + "node": { + "types": "./src/zlib_sync.node.ts", + "default": "./dist/node/src/zlib_sync.node.js" + }, + "import": "./src/zlib_sync.browser.ts" + }, "#is_deep_strict_equal": { "node": { "types": "./src/is_deep_strict_equal.node.ts", @@ -56,6 +63,7 @@ "ajv": "^8.20.0", "chalk": "catalog:", "fast-deep-equal": "^3.1.3", + "fflate": "catalog:", "set-blocking": "catalog:", "triple-beam": "^1.4.1", "winston": "catalog:", diff --git a/packages/lib/src/data/ModPack.ts b/packages/lib/src/data/ModPack.ts index 29458422..8fb3d388 100644 --- a/packages/lib/src/data/ModPack.ts +++ b/packages/lib/src/data/ModPack.ts @@ -1,4 +1,4 @@ -import zlib from "zlib"; +import * as zlib from "#zlib_sync"; import { Type, Static } from "@sinclair/typebox"; import * as libSchema from "../schema.js"; @@ -306,7 +306,7 @@ export default class ModPack { // eslint-disable-next-line node/no-sync let buf = zlib.deflateSync(JSON.stringify(json)); - return buf.toString("base64"); + return Buffer.from(buf).toString("base64"); } static fromModPackString(modPackString: string) { diff --git a/packages/lib/src/factorio/exchange_string.ts b/packages/lib/src/factorio/exchange_string.ts index 38d2a36a..325502f4 100644 --- a/packages/lib/src/factorio/exchange_string.ts +++ b/packages/lib/src/factorio/exchange_string.ts @@ -1,4 +1,4 @@ -import zlib from "zlib"; +import * as zlib from "#zlib_sync"; class MapReaderState { pos = 0; diff --git a/packages/lib/src/zlib_sync.browser.ts b/packages/lib/src/zlib_sync.browser.ts new file mode 100644 index 00000000..67caa44f --- /dev/null +++ b/packages/lib/src/zlib_sync.browser.ts @@ -0,0 +1,15 @@ +/* eslint-disable node/no-sync */ +import { strToU8, unzlibSync, zlibSync } from "fflate"; + +export function inflateSync(data: Uint8Array): Uint8Array { + try { + return unzlibSync(data); + } catch (err: any) { + // Match the error code node:zlib gives for invalid data. + throw Object.assign(new Error(err.message), { code: "Z_DATA_ERROR" }); + } +} + +export function deflateSync(data: Uint8Array | string): Uint8Array { + return zlibSync(typeof data === "string" ? strToU8(data) : data); +} diff --git a/packages/lib/src/zlib_sync.node.ts b/packages/lib/src/zlib_sync.node.ts new file mode 100644 index 00000000..10ecf102 --- /dev/null +++ b/packages/lib/src/zlib_sync.node.ts @@ -0,0 +1,11 @@ +import zlib from "zlib"; + +export function inflateSync(data: Uint8Array): Uint8Array { + // eslint-disable-next-line node/no-sync + return zlib.inflateSync(data); +} + +export function deflateSync(data: Uint8Array | string): Uint8Array { + // eslint-disable-next-line node/no-sync + return zlib.deflateSync(data); +} diff --git a/packages/lib/tsconfig.browser.json b/packages/lib/tsconfig.browser.json index 07259d25..00cf87ad 100644 --- a/packages/lib/tsconfig.browser.json +++ b/packages/lib/tsconfig.browser.json @@ -19,6 +19,7 @@ "./src/hash.ts", "./src/ini.ts", "./src/is_deep_strict_equal.browser.ts", + "./src/zlib_sync.browser.ts", "./src/link/*.ts", "./src/lua_tools.ts", "./src/logging.ts", diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index ddd59f18..4636bd27 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -23,6 +23,7 @@ catalog: antd: ^5.29.3 chalk: ^6.0.1 express: ^5.3.0 + fflate: ^0.8.3 jsonwebtoken: ^9.0.3 react: ^18.3.1 react-dom: ^18.3.1 diff --git a/test/lib/zlib_sync.test.js b/test/lib/zlib_sync.test.js new file mode 100644 index 00000000..51a1abfb --- /dev/null +++ b/test/lib/zlib_sync.test.js @@ -0,0 +1,25 @@ +/* eslint-disable node/no-sync */ +import assert from "node:assert/strict"; +import zlib from "node:zlib"; + +import * as browserZlib from "../../packages/lib/src/zlib_sync.browser.ts"; + +describe("lib/zlib_sync.browser", function() { + const text = JSON.stringify({ name: "pack", mods: [{ name: "base", version: "2.0.0" }] }); + + it("should inflate data deflated by node:zlib", function() { + const inflated = browserZlib.inflateSync(zlib.deflateSync(text)); + assert.equal(Buffer.from(inflated).toString(), text); + }); + it("should deflate data node:zlib can inflate", function() { + assert.equal(zlib.inflateSync(browserZlib.deflateSync(text)).toString(), text); + const bytes = Buffer.from(text); + assert.equal(zlib.inflateSync(browserZlib.deflateSync(bytes)).toString(), text); + }); + it("should throw with a Z_ code on invalid data", function() { + assert.throws( + () => browserZlib.inflateSync(Buffer.from("not zlib data")), + err => err.code === "Z_DATA_ERROR" + ); + }); +}); From 6dc48b6732424b1934cf1c7289001611898046d7 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Fri, 20 Nov 2026 10:19:04 +0000 Subject: [PATCH 16/20] Replace node:assert in link with a local assert The assert polyfill is 28 KB in the web interface bundle and link only uses it for plain truthiness checks. Co-Authored-By: Claude Opus 5.5 --- packages/lib/src/link/assert.ts | 6 ++++++ packages/lib/src/link/connectors.ts | 2 +- packages/lib/src/link/link.ts | 2 +- 3 files changed, 8 insertions(+), 2 deletions(-) create mode 100644 packages/lib/src/link/assert.ts diff --git a/packages/lib/src/link/assert.ts b/packages/lib/src/link/assert.ts new file mode 100644 index 00000000..46881b11 --- /dev/null +++ b/packages/lib/src/link/assert.ts @@ -0,0 +1,6 @@ +/** Throws if condition is falsy, node:assert is not available in the browser. */ +export function assert(condition: unknown): asserts condition { + if (!condition) { + throw new Error("Assertion failed"); + } +} diff --git a/packages/lib/src/link/connectors.ts b/packages/lib/src/link/connectors.ts index c87b848a..f9769c83 100644 --- a/packages/lib/src/link/connectors.ts +++ b/packages/lib/src/link/connectors.ts @@ -1,5 +1,4 @@ // Connection adapters for Links -import { strict as assert } from "assert"; import events from "events"; import { WebSocket } from "#WebSocket"; @@ -7,6 +6,7 @@ import * as libData from "../data/index.js"; import * as libErrors from "../errors.js"; import { logger } from "../logging.js"; import ExponentialBackoff from "../ExponentialBackoff.js"; +import { assert } from "./assert.js"; import type { Request, Event } from "./link.js"; /** diff --git a/packages/lib/src/link/link.ts b/packages/lib/src/link/link.ts index 205ae9e6..c2db49aa 100644 --- a/packages/lib/src/link/link.ts +++ b/packages/lib/src/link/link.ts @@ -5,7 +5,7 @@ import { logger } from "../logging.js"; import * as libSchema from "../schema.js"; import { dataClasses, errorClasses } from "./messages.js"; import { BaseConnector, WebSocketBaseConnector } from "./connectors.js"; -import { strict as assert } from "assert"; +import { assert } from "./assert.js"; import type { PluginNodeEnvInfo, PluginWebEnvInfo } from "../plugin.js"; import type { AddressType, JSONDeserialisable, MessageRoutable, MessageRequest, MessageEvent, IUser, From c4a9545d282157f031d6918a23688f7b0a8ad302 Mon Sep 17 00:00:00 2001 From: bbassie <17990055+bbassie@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:11:36 +0000 Subject: [PATCH 17/20] Explain why ZipEntry is a local type Co-Authored-By: Claude Opus 5.5 --- packages/lib/src/zip_ops.ts | 3 +++ 1 file changed, 3 insertions(+) diff --git a/packages/lib/src/zip_ops.ts b/packages/lib/src/zip_ops.ts index c8a12037..1d161c98 100644 --- a/packages/lib/src/zip_ops.ts +++ b/packages/lib/src/zip_ops.ts @@ -12,6 +12,9 @@ const deflateRaw = util.promisify(zlib.deflateRaw); /** * Entry in a ZipArchive + * + * Local subset of yauzl.Entry so the published declarations do not import + * yauzl, which would make @types/yauzl a runtime dependency of lib. */ export interface ZipEntry { fileName: string; From bd41801c8d5be8d562fc3aeef142227963b2e866 Mon Sep 17 00:00:00 2001 From: Cooldude2606 <25043174+Cooldude2606@users.noreply.github.com> Date: Fri, 20 Nov 2026 16:36:01 +0000 Subject: [PATCH 18/20] Prepare 2.1.1 --- CHANGELOG.md | 40 ++++++++++++++++++++++-- packages/controller/package.json | 2 +- packages/create/package.json | 2 +- packages/ctl/package.json | 2 +- packages/host/package.json | 2 +- packages/lib/package.json | 2 +- packages/web_ui/package.json | 2 +- plugins/global_chat/package.json | 2 +- plugins/player_auth/package.json | 2 +- plugins/player_sync/package.json | 2 +- plugins/research_sync/package.json | 2 +- plugins/statistics_exporter/package.json | 2 +- plugins/subspace_storage/package.json | 2 +- 13 files changed, 50 insertions(+), 14 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ea38d78..e0c787bf 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -31,11 +31,47 @@ Many thanks to the following for contributing to this release: [@username](https://github.com/username) --> -## Unreleased +## Version 2.1.1 + +### Features + +- Hosts on ARM64 Linux download and run the ARM64 headless build of Factorio, available from Factorio 2.1.18. [#1228]() +- Added `requiredMods` to plugin declarations. Instances refuse to start when their mod pack lacks a mod a loaded plugin requires, and the controller downloads missing required mods and their dependencies from the mod portal on start. Subspace Storage requires the subspace_storage mod. [#535]() +- Added `--output json` and `--output wire` to clusterioctl for machine readable results and errors. [#1230]() ### Fixes -- Fixed cramped plugin rows and wrapping header branding on mobile screens. +- Fixed a newly paired host reporting that it needs a restart. [#1204]() +- Fixed the installer's run-controller and run-host scripts exiting with 0 when the controller or host exited with 8 to stop the restart loop. [#1208]() +- Fixed clusterioctl user list, user show and role list printing [object Set] for roles, instances and permissions. [#1205]() +- Fixed typo in the delete instance confirmation. [#1209]() +- The Search Mod Portal dialog now opens on the default mod pack's Factorio version instead of always 2.0. [#1209]() +- Fixed the mod portal cache key logging "undefined" when hide_deprecated was not sent. [#1209]() +- Fixed player_sync losing quick bar slots of blueprint library records when a player joins an instance for the first time. [#1219]() +- Fixed cramped plugin rows and wrapping header branding on mobile screens. [#1223]() +- Fixed player_sync keeping an instance's old copy of a player after the controller refused its upload, which let an instance restarted after a crash overwrite newer player data. [#1218]() + +### Changes + +- Restarting the controller or a host from the web interface now asks for confirmation, and for hosts lists the running instances that will be stopped. [#1207]() +- New clusters default controller.default_mod_pack_id to the newest Base Game mod pack, so instances can create saves and start without setting it first. [#1203]() +- Output from npm during `plugin install` now goes through the logger. [#1224]() +- The controller collects system info, including restart required, right after it starts and when a host connects instead of waiting for the first system metrics interval. [#1227]() +- clusterioctl prints all tables with the same formatter and prints command results to stdout instead of the log. [#1230]() +- clusterioctl prints "Command ran successfully" for commands that have no other output. [#1230]() + +### Meta + +- Added a CI check that pull request descriptions have a valid changelog section. [#1226]() + +### Contributors + +Many thanks to the following for contributing to this release: +[@bbassie](), [@ILLISIS](), [@Danielv123]() + +### Statistics + +Commits: 44 Pull Requests: 19 Files Changed: 81 Additions: +2,676 Deletions: -739 ## Version 2.1.0 diff --git a/packages/controller/package.json b/packages/controller/package.json index b611b5e3..5dc9a7b7 100644 --- a/packages/controller/package.json +++ b/packages/controller/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/controller", - "version": "2.1.0", + "version": "2.1.1", "description": "Implementation of Clusterio controller", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/packages/create/package.json b/packages/create/package.json index 339845aa..f059d945 100644 --- a/packages/create/package.json +++ b/packages/create/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/create", - "version": "2.1.0", + "version": "2.1.1", "description": "Installer for clusterio", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/packages/ctl/package.json b/packages/ctl/package.json index 0ecaedc1..642777d4 100644 --- a/packages/ctl/package.json +++ b/packages/ctl/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/ctl", - "version": "2.1.0", + "version": "2.1.1", "description": "Clusterio command line management tool", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/packages/host/package.json b/packages/host/package.json index 51271094..42774635 100644 --- a/packages/host/package.json +++ b/packages/host/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/host", - "version": "2.1.0", + "version": "2.1.1", "description": "Implementation of Clusterio host server", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/packages/lib/package.json b/packages/lib/package.json index 53a1ba2b..f2ca801d 100644 --- a/packages/lib/package.json +++ b/packages/lib/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/lib", - "version": "2.1.0", + "version": "2.1.1", "description": "Shared library for Clusterio", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/packages/web_ui/package.json b/packages/web_ui/package.json index d227b3f5..f5b761e4 100644 --- a/packages/web_ui/package.json +++ b/packages/web_ui/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/web_ui", - "version": "2.1.0", + "version": "2.1.1", "description": "Clusterio web interface implementation", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser", diff --git a/plugins/global_chat/package.json b/plugins/global_chat/package.json index 0b3bf973..8f7d62e5 100644 --- a/plugins/global_chat/package.json +++ b/plugins/global_chat/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/plugin-global_chat", - "version": "2.1.0", + "version": "2.1.1", "description": "Clusterio plugin forwarding between Factorio servers", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/plugins/player_auth/package.json b/plugins/player_auth/package.json index 22066fb2..6ae9aacf 100644 --- a/plugins/player_auth/package.json +++ b/plugins/player_auth/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/plugin-player_auth", - "version": "2.1.0", + "version": "2.1.1", "description": "Clusterio plugin authenticating logged in players to the web interface", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/plugins/player_sync/package.json b/plugins/player_sync/package.json index a8dd03c7..27f0cb52 100644 --- a/plugins/player_sync/package.json +++ b/plugins/player_sync/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/plugin-player_sync", - "version": "2.1.0", + "version": "2.1.1", "description": "Clusterio plugin forwarding between Factorio servers", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Danielv ", diff --git a/plugins/research_sync/package.json b/plugins/research_sync/package.json index 60a10d3f..42c9e6bf 100644 --- a/plugins/research_sync/package.json +++ b/plugins/research_sync/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/plugin-research_sync", - "version": "2.1.0", + "version": "2.1.1", "description": "Clusterio plugin for synchronizing research between Factorio servers", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/plugins/statistics_exporter/package.json b/plugins/statistics_exporter/package.json index 015f7fb3..ed6ea8b0 100644 --- a/plugins/statistics_exporter/package.json +++ b/plugins/statistics_exporter/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/plugin-statistics_exporter", - "version": "2.1.0", + "version": "2.1.1", "description": "Clusterio plugin for gathering statistics from Factorio servers", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", diff --git a/plugins/subspace_storage/package.json b/plugins/subspace_storage/package.json index 5856c9f7..5c492c01 100644 --- a/plugins/subspace_storage/package.json +++ b/plugins/subspace_storage/package.json @@ -1,6 +1,6 @@ { "name": "@clusterio/plugin-subspace_storage", - "version": "2.1.0", + "version": "2.1.1", "description": "Clusterio plugin for sharing storage between Factorio servers", "homepage": "https://github.com/clusterio/clusterio#readme", "author": "Hornwitser ", From 81c7d248676a694e8fff728ab4a1da8a723523bd Mon Sep 17 00:00:00 2001 From: Bastiaan <17990055+bbassie@users.noreply.github.com> Date: Fri, 20 Nov 2026 21:54:30 +0100 Subject: [PATCH 19/20] Merge pull request #1233 from bbassie/chore/drop-chalk Replace chalk with util.styleText --- packages/create/logging.js | 7 ++----- packages/create/package.json | 1 - packages/lib/package.json | 1 - packages/lib/src/logging_utils.ts | 21 ++++++++++----------- pnpm-workspace.yaml | 1 - 5 files changed, 12 insertions(+), 19 deletions(-) diff --git a/packages/create/logging.js b/packages/create/logging.js index 9954b666..872079e6 100644 --- a/packages/create/logging.js +++ b/packages/create/logging.js @@ -1,5 +1,5 @@ /* eslint-disable no-console */ -import chalk from "chalk"; +import { styleText } from "node:util"; export const levels = Object.freeze({ fatal: 0, @@ -27,10 +27,7 @@ for (let [name, level] of Object.entries(levels)) { if (level > maxLogLevel) { return; } - let style = chalk; - for (let part of colors[name].split(" ")) { - style = style[part]; - } + const style = text => styleText(colors[name].split(" "), text); if (["fatal", "error"].includes(name)) { console.error(`${style(name)} ${message}`); } else if (["warn"].includes(name)) { diff --git a/packages/create/package.json b/packages/create/package.json index f059d945..2cfca34a 100644 --- a/packages/create/package.json +++ b/packages/create/package.json @@ -36,7 +36,6 @@ "@inquirer/confirm": "^6.3.5", "@inquirer/input": "^5.1.9", "@inquirer/select": "^5.2.8", - "chalk": "catalog:", "yargs": "catalog:" } } diff --git a/packages/lib/package.json b/packages/lib/package.json index f2ca801d..bb572f4b 100644 --- a/packages/lib/package.json +++ b/packages/lib/package.json @@ -54,7 +54,6 @@ "@types/yauzl": "catalog:", "@types/yazl": "catalog:", "ajv": "^8.20.0", - "chalk": "catalog:", "fast-deep-equal": "^3.1.3", "set-blocking": "catalog:", "triple-beam": "^1.4.1", diff --git a/packages/lib/src/logging_utils.ts b/packages/lib/src/logging_utils.ts index ea062c96..da636a97 100644 --- a/packages/lib/src/logging_utils.ts +++ b/packages/lib/src/logging_utils.ts @@ -8,11 +8,10 @@ import fs from "node:fs/promises"; import type { ReadStream } from "node:fs"; import path from "path"; import stream from "stream"; -import util from "util"; +import util, { styleText } from "util"; import winston from "winston"; import Transport from "winston-transport"; import { LEVEL, MESSAGE } from "triple-beam"; -import chalk from "chalk"; import * as libData from "./data/index.js"; import * as libErrors from "./errors.js"; @@ -108,30 +107,30 @@ export type ParsedFactorioOutput = function formatServerOutput(parsed: ParsedFactorioOutput) { let time = ""; if (parsed.format === "seconds") { - time = `${chalk.yellow(parsed.time.padStart(8))} `; + time = `${styleText("yellow", parsed.time.padStart(8))} `; } else if (parsed.format === "date") { - time = `${chalk.yellow(parsed.time)} `; + time = `${styleText("yellow", parsed.time)} `; } let info = ""; if (parsed.type === "log") { let level = parsed.level; if (level === "Script") { - level = chalk.bold.greenBright(level); + level = styleText(["bold", "greenBright"], level); } else if (level === "Verbose") { - level = chalk.bold.gray(level); + level = styleText(["bold", "gray"], level); } else if (level === "Info") { - level = chalk.bold.blueBright(level); + level = styleText(["bold", "blueBright"], level); } else if (parsed.level === "Warning") { - level = chalk.bold.yellowBright(level); + level = styleText(["bold", "yellowBright"], level); } else if (parsed.level === "Error") { - level = chalk.bold.redBright(level); + level = styleText(["bold", "redBright"], level); } - info = `${level} ${chalk.gray(parsed.file)}: `; + info = `${level} ${styleText("gray", parsed.file)}: `; } else if (parsed.type === "action") { - info = `[${chalk.yellow(parsed.action)}] `; + info = `[${styleText("yellow", parsed.action)}] `; } return time + info + parsed.message; diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index ddd59f18..3211b103 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -21,7 +21,6 @@ catalog: '@types/yazl': ^3.3.1 '@vitejs/plugin-react': ^6.1.2 antd: ^5.29.3 - chalk: ^6.0.1 express: ^5.3.0 jsonwebtoken: ^9.0.3 react: ^18.3.1 From 1c18dc366149c9c99e177e0778e2af86a25fcb04 Mon Sep 17 00:00:00 2001 From: Bastiaan <17990055+bbassie@users.noreply.github.com> Date: Fri, 20 Nov 2026 21:54:42 +0100 Subject: [PATCH 20/20] Merge pull request #1234 from bbassie/chore/inline-daily-rotate Replace winston-daily-rotate-file with an in-repo transport --- packages/controller/controller.ts | 11 ++--- packages/controller/package.json | 1 - packages/host/host.ts | 6 +-- packages/host/package.json | 1 - packages/lib/src/logging_utils.ts | 52 +++++++++++++++++++++- pnpm-workspace.yaml | 1 - test/lib/logging_utils.js | 72 +++++++++++++++++++++++++++++++ 7 files changed, 129 insertions(+), 15 deletions(-) diff --git a/packages/controller/controller.ts b/packages/controller/controller.ts index cd1364a1..09af32fe 100644 --- a/packages/controller/controller.ts +++ b/packages/controller/controller.ts @@ -21,7 +21,6 @@ import crypto from "crypto"; import yargs from "yargs"; import util from "util"; import winston from "winston"; -import DailyRotateFile from "winston-daily-rotate-file"; // homebrew modules @@ -355,19 +354,17 @@ async function initialize(): Promise { level: "verbose", levels, }); - clusterLogger.add(new DailyRotateFile({ + clusterLogger.add(new lib.DailyFileTransport({ format: winston.format.json(), - filename: "cluster-%DATE%.log", - utc: true, dirname: path.join(args.logDirectory, "cluster"), + prefix: "cluster", })); // Log stream for the controller. - logger.add(new DailyRotateFile({ + logger.add(new lib.DailyFileTransport({ format: winston.format.json(), - filename: "controller-%DATE%.log", - utc: true, dirname: path.join(args.logDirectory, "controller"), + prefix: "controller", })); logger.add(new winston.transports.Stream({ stream: clusterLogger, diff --git a/packages/controller/package.json b/packages/controller/package.json index 5dc9a7b7..8a66c52d 100644 --- a/packages/controller/package.json +++ b/packages/controller/package.json @@ -45,7 +45,6 @@ "jsonwebtoken": "catalog:", "semver": "catalog:", "winston": "catalog:", - "winston-daily-rotate-file": "catalog:", "ws": "catalog:", "yargs": "catalog:" }, diff --git a/packages/host/host.ts b/packages/host/host.ts index a250ab06..23e769b8 100755 --- a/packages/host/host.ts +++ b/packages/host/host.ts @@ -17,7 +17,6 @@ import path from "path"; import yargs from "yargs"; import packageConfig from "@clusterio/host/package.json" with { type: "json" }; import winston from "winston"; -import "winston-daily-rotate-file"; // internal libraries // Reduce startup time by lazy compiling schemas. @@ -147,11 +146,10 @@ async function startHost() { .parseSync() ; - logger.add(new winston.transports.DailyRotateFile({ + logger.add(new lib.DailyFileTransport({ format: winston.format.json(), - filename: "host-%DATE%.log", - utc: true, dirname: path.join(args.logDirectory, "host"), + prefix: "host", })); if (args.logLevel !== "none") { logger.add(new ConsoleTransport({ diff --git a/packages/host/package.json b/packages/host/package.json index 42774635..404547b7 100644 --- a/packages/host/package.json +++ b/packages/host/package.json @@ -49,7 +49,6 @@ "semver": "catalog:", "set-blocking": "catalog:", "winston": "catalog:", - "winston-daily-rotate-file": "catalog:", "yargs": "catalog:", "yazl": "catalog:" }, diff --git a/packages/lib/src/logging_utils.ts b/packages/lib/src/logging_utils.ts index da636a97..9d7c4a19 100644 --- a/packages/lib/src/logging_utils.ts +++ b/packages/lib/src/logging_utils.ts @@ -5,7 +5,8 @@ * @module lib/logging_utils */ import fs from "node:fs/promises"; -import type { ReadStream } from "node:fs"; +import { type ReadStream, type WriteStream, createWriteStream, mkdirSync } from "node:fs"; +import os from "node:os"; import path from "path"; import stream from "stream"; import util, { styleText } from "util"; @@ -225,6 +226,55 @@ export class LinkTransport extends Transport { } } +/** + * Writes log entries as lines to dirname/prefix-YYYY-MM-DD.log, opening + * a new file when the UTC date changes. + */ +export class DailyFileTransport extends Transport { + dirname: string; + prefix: string; + now: () => number; + date?: string; + stream?: WriteStream; + + constructor( + options: Transport.TransportStreamOptions & { + dirname: string, + prefix: string, + now?: () => number, + } + ) { + super(options); + this.dirname = options.dirname; + this.prefix = options.prefix; + this.now = options.now ?? Date.now; + // eslint-disable-next-line node/no-sync + mkdirSync(this.dirname, { recursive: true }); + } + + log(info: any, callback: () => void) { + const date = new Date(this.now()).toISOString().slice(0, 10); + if (!this.stream || date !== this.date) { + this.stream?.end(); + this.date = date; + this.stream = createWriteStream(path.join(this.dirname, `${this.prefix}-${date}.log`), { flags: "a" }); + this.stream.on("error", err => this.emit("error", err)); + } + this.stream.write(info[MESSAGE] + os.EOL); + return callback(); + } + + close(callback?: () => void) { + const fileStream = this.stream; + this.stream = undefined; + if (fileStream) { + fileStream.end(callback); + } else { + callback?.(); + } + } +} + const logFileGlob = /^[a-z]+-(\d{4}-\d{2}-\d{2})\.log$/; const logIndexVersion = 2; diff --git a/pnpm-workspace.yaml b/pnpm-workspace.yaml index 3211b103..de4dd120 100644 --- a/pnpm-workspace.yaml +++ b/pnpm-workspace.yaml @@ -33,7 +33,6 @@ catalog: typescript: ^7.0.2 vite: ^8.3.4 winston: ^3.19.0 - winston-daily-rotate-file: ^5.0.0 winston-transport: ^4.9.0 ws: ^8.22.0 yargs: ^18.2.0 diff --git a/test/lib/logging_utils.js b/test/lib/logging_utils.js index b8dab0b9..496c620c 100644 --- a/test/lib/logging_utils.js +++ b/test/lib/logging_utils.js @@ -1,5 +1,6 @@ import assert from "node:assert/strict"; import fs from "node:fs/promises"; +import os from "node:os"; import path from "node:path"; import { testLines } from "./factorio/lines.js"; @@ -66,6 +67,77 @@ describe("lib/logging_utils.js", function() { }); }); + describe("class DailyFileTransport", function() { + let tempDir = path.join("temp", "test", "daily_file"); + beforeEach(async function() { + await fs.rm(tempDir, { recursive: true, force: true }); + }); + + function create(now, dirname = tempDir) { + return new lib.DailyFileTransport({ dirname, prefix: "test", now }); + } + function write(transport, message) { + transport.log({ [Symbol.for("message")]: JSON.stringify({ message }) }, () => {}); + } + async function close(transport) { + await new Promise(resolve => transport.close(resolve)); + } + async function read(file) { + let content = await fs.readFile(path.join(tempDir, file), "utf8"); + assert(content.endsWith(os.EOL)); + return content.split(os.EOL).slice(0, -1).map(line => JSON.parse(line).message); + } + + it("should create the directory and write lines to the file for the UTC date", async function() { + let transport = create(() => Date.parse("2026-11-19T12:00:00Z"), path.join(tempDir, "nested")); + write(transport, "first"); + write(transport, "second"); + await close(transport); + assert.deepEqual(await read(path.join("nested", "test-2026-11-19.log")), ["first", "second"]); + }); + + it("should append to an existing file", async function() { + await fs.mkdir(tempDir, { recursive: true }); + await fs.writeFile(path.join(tempDir, "test-2026-11-19.log"), `{"message":"old"}${os.EOL}`); + let transport = create(() => Date.parse("2026-11-19T12:00:00Z")); + write(transport, "new"); + await close(transport); + assert.deepEqual(await read("test-2026-11-19.log"), ["old", "new"]); + }); + + it("should switch files when the UTC date changes", async function() { + let time = Date.parse("2026-11-19T23:59:59.999Z"); + let transport = create(() => time); + write(transport, "before"); + time += 1; + write(transport, "after"); + await close(transport); + assert.deepEqual((await fs.readdir(tempDir)).sort(), ["test-2026-11-19.log", "test-2026-11-20.log"]); + assert.deepEqual(await read("test-2026-11-19.log"), ["before"]); + assert.deepEqual(await read("test-2026-11-20.log"), ["after"]); + }); + + it("should use the UTC date rather than the local one", async function() { + let transport = create(() => Date.parse("2026-11-20T00:30:00+02:00")); + write(transport, "message"); + await close(transport); + assert.deepEqual(await fs.readdir(tempDir), ["test-2026-11-19.log"]); + }); + + it("should emit write errors", async function() { + await fs.mkdir(path.join(tempDir, "test-2026-11-19.log"), { recursive: true }); + let transport = create(() => Date.parse("2026-11-19T12:00:00Z")); + let error = new Promise(resolve => transport.once("error", resolve)); + write(transport, "message"); + assert.equal((await error).code, "EISDIR"); + }); + + it("should close when nothing was written", async function() { + await close(create(Date.now)); + assert.deepEqual(await fs.readdir(tempDir), []); + }); + }); + describe("deleteOldLogs", function() { let tempDir = path.join("temp", "test", "log_retention"); let files = [