Merge pull request #1230 from bbassie/feature/ctl-output-json

Add --output json to clusterioctl
This commit is contained in:
Cooldude2606 authored and GitHub committed 2026-11-20 15:22:38 +00:00
commit 34deacb881
26 files changed
+1048 -347

No files matched your search

+95
View File
@@ -0,0 +1,95 @@
import assert from "node:assert/strict";
import * as lib from "@clusterio/lib";
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) {
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("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" });
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 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(() => {
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 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.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"), () => 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"]);
});
});
});
+88
View File
@@ -0,0 +1,88 @@
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";
/** 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);
},
async sendTo(destination, message) {
return this.send(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("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() {
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 <deleted> (2):"), lines.join("\n"));
assert(lines.some(line => /joinCount +\| 4/.test(line)), lines.join("\n"));
});
});
});
+91
View File
@@ -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."]);
});
});
});
+56
View File
@@ -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"}'],
);
});
});
});
+124
View File
@@ -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/);
});
});
@@ -2119,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"));
@@ -2317,6 +2321,126 @@ 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"));
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}`), '{"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 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 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"), "");
});
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);
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");
+2 -3
View File
@@ -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;