2 Commits

Author SHA1 Message Date
Philipp 076e96f3de fix(monitor): use global console channel and implement shard filtering (#87)
Lint / pre-commit Linting (push) Successful in 47s
Test / Run Tests (push) Successful in 1m3s
This PR fixes the issue where console monitoring was empty when a specific shard was targeted on the official Screeps server.

### Changes:
- **Unified Subscription**: Changed WebSocket subscription path from `shard/console` (invalid) to the global `console` channel.
- **Shard Filtering**: Implemented client-side filtering in `handleConsoleEvent` to only display logs matching the targeted shard.
- **Precise Timing**: Retained the shard-specific `api.time()` call for accurate tick duration tracking.
- **Tests**: Added and updated 48 unit tests verifying the fix and shard filtering logic.
- **Distribution**: Rebuilt `dist/index.js` and bumped version to `v0.2.1`.

Reviewed-on: #87
2026-05-16 22:29:24 +02:00
Philipp bf52580bf3 feat: add Screeps console monitoring with configurable error handling and shard support (#84)
Lint / pre-commit Linting (push) Successful in 1m5s
Test / Run Tests (push) Successful in 1m23s
Reviewed-on: #84
2026-05-16 19:44:39 +02:00
6 changed files with 302 additions and 2011 deletions
+161 -35
View File
@@ -11,12 +11,15 @@ vi.mock("@actions/core", () => ({
endGroup: vi.fn(),
}));
// ── mock @actions/artifact so tests never attempt real uploads ──────────────
vi.mock("@actions/artifact", () => ({
DefaultArtifactClient: vi.fn().mockImplementation(() => ({
import * as artifact from "@actions/artifact";
vi.mock("@actions/artifact", () => {
const mockClient = {
uploadArtifact: vi.fn().mockResolvedValue({}),
})),
}));
};
return {
create: vi.fn(() => mockClient),
};
});
import * as core from "@actions/core";
import fs from "fs";
@@ -28,8 +31,10 @@ import {
buildSubscribePath,
detectTraceback,
detectWarning,
outputMultiline,
buildProgressMessage,
writeLogFile,
uploadLogArtifacts,
handleConsoleEvent,
monitorConsole,
} from "../monitor.js";
@@ -53,20 +58,20 @@ describe("isOfficialServer", () => {
});
describe("buildSubscribePath", () => {
it("returns shard0/console for official server (no shard provided)", () => {
expect(buildSubscribePath("screeps.com")).toBe("shard0/console");
it("returns console for official server (no shard provided)", () => {
expect(buildSubscribePath("screeps.com")).toBe("console");
});
it("returns console for private server (no shard provided)", () => {
expect(buildSubscribePath("builder64")).toBe("console");
});
it("returns <shard>/console when shard is provided (official)", () => {
expect(buildSubscribePath("screeps.com", "shard3")).toBe("shard3/console");
it("returns console when shard is provided (official)", () => {
expect(buildSubscribePath("screeps.com", "shard3")).toBe("console");
});
it("returns <shard>/console when shard is provided (private)", () => {
expect(buildSubscribePath("builder64", "myshard")).toBe("myshard/console");
it("returns console when shard is provided (private)", () => {
expect(buildSubscribePath("builder64", "myshard")).toBe("console");
});
});
@@ -123,6 +128,33 @@ describe("detectWarning", () => {
});
});
describe("outputMultiline", () => {
beforeEach(() => {
vi.clearAllMocks();
});
it("prefixes lines with shard when provided", () => {
outputMultiline("line1\nline2", "info", "shard0");
expect(core.info).toHaveBeenCalledWith("[shard0] line1");
expect(core.info).toHaveBeenCalledWith("[shard0] line2");
});
it("does not prefix when shard is missing", () => {
outputMultiline("line1", "info");
expect(core.info).toHaveBeenCalledWith("line1");
});
it("uses core.warning for level=warning", () => {
outputMultiline("warn", "warning", "s0");
expect(core.warning).toHaveBeenCalledWith("[s0] warn");
});
it("uses core.error for level=error", () => {
outputMultiline("err", "error", "s0");
expect(core.error).toHaveBeenCalledWith("[s0] err");
});
});
describe("buildProgressMessage", () => {
it("formats correctly at 0 elapsed", () => {
expect(buildProgressMessage(0, 50)).toBe("[Monitor] 0/50 ticks elapsed...");
@@ -141,48 +173,79 @@ describe("buildProgressMessage", () => {
});
});
describe("uploadLogArtifacts", () => {
beforeEach(() => {
vi.clearAllMocks();
});
it("instantiates client and calls uploadArtifact", async () => {
await uploadLogArtifacts(
["/path/to/shard0_console_log.txt"],
"custom-name",
);
expect(artifact.create().uploadArtifact).toHaveBeenCalledWith(
"custom-name",
["/path/to/shard0_console_log.txt"],
"/path/to",
{ continueOnError: true },
);
});
it("does nothing if filePaths is empty", async () => {
await uploadLogArtifacts([]);
expect(artifact.create().uploadArtifact).not.toHaveBeenCalled();
});
});
// ────────────────────────────────────────────────────────────────────────────
// handleConsoleEvent
// ────────────────────────────────────────────────────────────────────────────
describe("handleConsoleEvent", () => {
let state;
let stdoutBuffer;
let shardBuffers;
beforeEach(() => {
vi.clearAllMocks();
state = { sawTraceback: false, sawErrorLog: false, sawWarningLog: false };
stdoutBuffer = [];
shardBuffers = {};
});
const makeEvent = (log = [], results = [], error = null) => ({
data: { messages: { log, results }, error },
});
it("calls core.info for each stdout line when logToFile=false", () => {
const event = makeEvent(["line1", "line2"]);
handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
expect(core.info).toHaveBeenCalledWith("line1");
expect(core.info).toHaveBeenCalledWith("line2");
expect(stdoutBuffer).toHaveLength(0);
it("calls core.info for each stdout line with shard prefix when logToFile=false", () => {
const event = {
data: {
shard: "shard0",
messages: { log: ["line1"], results: ["line2"] },
},
};
handleConsoleEvent(event, { logToFile: false }, shardBuffers, state);
expect(core.info).toHaveBeenCalledWith("[shard0] line1");
expect(core.info).toHaveBeenCalledWith("[shard0] line2");
expect(Object.keys(shardBuffers)).toHaveLength(0);
});
it("buffers stdout when logToFile=true; does not call core.info", () => {
const event = makeEvent(["line1", "line2"]);
handleConsoleEvent(event, { logToFile: true }, stdoutBuffer, state);
const event = {
data: { shard: "shard0", messages: { log: ["line1", "line2"] } },
};
handleConsoleEvent(event, { logToFile: true }, shardBuffers, state);
expect(core.info).not.toHaveBeenCalled();
expect(stdoutBuffer).toEqual(["line1", "line2"]);
expect(shardBuffers["shard0"]).toEqual(["line1", "line2"]);
});
it("includes results lines in output", () => {
const event = makeEvent([], ["result1"]);
handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
handleConsoleEvent(event, { logToFile: false }, shardBuffers, state);
expect(core.info).toHaveBeenCalledWith("result1");
});
it("calls core.error when error field is non-empty", () => {
const event = makeEvent([], [], "Script crashed");
handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
handleConsoleEvent(event, { logToFile: false }, shardBuffers, state);
expect(core.error).toHaveBeenCalledWith("Script crashed");
expect(state.sawErrorLog).toBe(true);
});
@@ -190,44 +253,74 @@ describe("handleConsoleEvent", () => {
it("sets state.sawTraceback when error contains stack frames", () => {
const error = "TypeError: boom\n at Object.<anonymous> (main:1:1)";
const event = makeEvent([], [], error);
handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
handleConsoleEvent(event, { logToFile: false }, shardBuffers, state);
expect(state.sawTraceback).toBe(true);
expect(state.sawErrorLog).toBe(true);
});
it("does not set sawTraceback for plain error without stack frames", () => {
const event = makeEvent([], [], "Script error: low CPU");
handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
handleConsoleEvent(event, { logToFile: false }, shardBuffers, state);
expect(state.sawTraceback).toBe(false);
expect(state.sawErrorLog).toBe(true);
});
it("sets state.sawWarningLog and calls core.warning for warn lines", () => {
const event = makeEvent(["<font color='orange'>low energy</font>"]);
handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state);
handleConsoleEvent(event, { logToFile: false }, shardBuffers, state);
expect(state.sawWarningLog).toBe(true);
expect(core.warning).toHaveBeenCalled();
});
it("calls core.warning regardless of logToFile setting", () => {
const event = makeEvent(["<font color='orange'>warn line</font>"]);
handleConsoleEvent(event, { logToFile: true }, stdoutBuffer, state);
handleConsoleEvent(event, { logToFile: true }, shardBuffers, state);
expect(core.warning).toHaveBeenCalled();
});
it("handles missing messages gracefully (no crash on empty event)", () => {
const event = { data: {} };
expect(() =>
handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state),
handleConsoleEvent(event, { logToFile: false }, shardBuffers, state),
).not.toThrow();
});
it("handles completely empty event gracefully", () => {
const event = {};
expect(() =>
handleConsoleEvent(event, { logToFile: false }, stdoutBuffer, state),
handleConsoleEvent(event, { logToFile: false }, shardBuffers, state),
).not.toThrow();
});
it("filters messages by shard when targetShard is provided", () => {
const event = { data: { shard: "shard0", messages: { log: ["msg0"] } } };
handleConsoleEvent(event, { shard: "shard1" }, shardBuffers, state);
expect(core.info).not.toHaveBeenCalled();
handleConsoleEvent(event, { shard: "shard0" }, shardBuffers, state);
expect(core.info).toHaveBeenCalledWith("[shard0] msg0");
});
it("does not filter when targetShard is undefined", () => {
const event = { data: { shard: "shard0", messages: { log: ["msg0"] } } };
handleConsoleEvent(event, {}, shardBuffers, state);
expect(core.info).toHaveBeenCalledWith("[shard0] msg0");
});
it("buffers messages separately for different shards", () => {
const event0 = { data: { shard: "shard0", messages: { log: ["msg0"] } } };
const event1 = { data: { shard: "shard1", messages: { log: ["msg1"] } } };
handleConsoleEvent(event0, { logToFile: true }, shardBuffers, state);
handleConsoleEvent(event1, { logToFile: true }, shardBuffers, state);
expect(shardBuffers["shard0"]).toEqual(["msg0"]);
expect(shardBuffers["shard1"]).toEqual(["msg1"]);
});
it("uses 'default' key when shard is missing in event", () => {
const event = { data: { messages: { log: ["msg"] } } };
handleConsoleEvent(event, { logToFile: true }, shardBuffers, state);
expect(shardBuffers["default"]).toEqual(["msg"]);
});
});
// ────────────────────────────────────────────────────────────────────────────
@@ -357,19 +450,19 @@ describe("monitorConsole", () => {
);
});
it("subscribes to 'shard0/console' for the official server (default)", async () => {
it("subscribes to 'console' for the official server (default)", async () => {
const api = buildMockApi({
hostname: "screeps.com",
ticks: [100, 101, 102, 103],
});
await monitorConsole(api, { ...BASE_OPTS, hostname: "screeps.com" });
expect(api.socket.subscribe).toHaveBeenCalledWith(
"shard0/console",
"console",
expect.any(Function),
);
});
it("subscribes to custom shard when provided", async () => {
it("subscribes to 'console' even when custom shard is provided", async () => {
const api = buildMockApi({
hostname: "screeps.com",
ticks: [100, 101, 102, 103],
@@ -380,10 +473,10 @@ describe("monitorConsole", () => {
shard: "shard3",
});
expect(api.socket.subscribe).toHaveBeenCalledWith(
"shard3/console",
"console",
expect.any(Function),
);
// Verify polling also uses shard3
// Verify polling still uses shard3 for timing
expect(api.time).toHaveBeenCalledWith("shard3");
});
@@ -504,4 +597,37 @@ describe("monitorConsole", () => {
expect(result.sawTraceback).toBe(true);
expect(result.sawErrorLog).toBe(true);
});
it("creates separate log files for different shards when logToFile=true", async () => {
const api = buildMockApi({ ticks: [100, 101, 102, 103] });
setTimeout(() => {
api._fireConsole({
shard: "shard0",
messages: { log: ["msg0"], results: [] },
error: null,
});
api._fireConsole({
shard: "shard1",
messages: { log: ["msg1"], results: [] },
error: null,
});
}, 50);
// Verify uploadArtifact was called with two files
await monitorConsole(api, {
...BASE_OPTS,
logToFile: true,
});
expect(artifact.create().uploadArtifact).toHaveBeenCalledWith(
"screeps-console-log",
expect.arrayContaining([
expect.stringContaining("shard0_console_log.txt"),
expect.stringContaining("shard1_console_log.txt"),
]),
expect.any(String),
{ continueOnError: true },
);
});
});
+11 -84
View File
File diff suppressed because one or more lines are too long
+1 -1
View File
@@ -197,7 +197,7 @@ export async function postCode() {
});
}
// ── Console monitoring (optional) ────────────────────────────────────────
// Console monitoring (optional)
const monitorTicks = parseInt(core.getInput("monitor") || "0", 10);
if (monitorTicks > 0) {
const result = await monitorConsole(api, {
+95 -70
View File
@@ -1,13 +1,9 @@
import * as core from "@actions/core";
import { DefaultArtifactClient } from "@actions/artifact";
import { create } from "@actions/artifact";
import fs from "fs";
import path from "path";
import os from "os";
// ────────────────────────────────────────────────────────────────────────────
// Shard / subscribe-path helpers
// ────────────────────────────────────────────────────────────────────────────
/**
* Returns true if the hostname is the official Screeps server.
* Used to decide whether to prefix the subscribe path with a shard name.
@@ -33,14 +29,11 @@ export function isOfficialServer(hostname) {
* @returns {string}
*/
export function buildSubscribePath(hostname, shard) {
if (shard) return `${shard}/console`;
return isOfficialServer(hostname) ? "shard0/console" : "console";
// The console channel on Screeps official and most private servers is 'console'.
// We subscribe to the aggregate feed and filter by shard in handleConsoleEvent.
return "console";
}
// ────────────────────────────────────────────────────────────────────────────
// Detection helpers
// ────────────────────────────────────────────────────────────────────────────
/**
* Returns true when errorText contains JavaScript stack-frame lines.
* Screeps places runtime errors (including stack traces) in event.data.error.
@@ -76,17 +69,42 @@ export function detectWarning(logLines) {
* @returns {string}
*/
export function safeDecode(text) {
if (typeof text !== "string" || !text.includes("%")) return text;
if (typeof text !== "string") return text;
let result = text;
if (result.includes("%")) {
try {
return decodeURIComponent(text);
result = decodeURIComponent(result);
} catch (err) {
return text;
// Ignore decoding errors
}
}
// Screeps console often contains HTML entities
return result
.replace(/&lt;/g, "<")
.replace(/&gt;/g, ">")
.replace(/&quot;/g, '"')
.replace(/&amp;/g, "&");
}
// ────────────────────────────────────────────────────────────────────────────
// Output helpers
// ────────────────────────────────────────────────────────────────────────────
/**
* Outputs text to the action log, splitting by newline to ensure proper display.
* Optionally prepends a [shard] prefix.
*
* @param {string} text
* @param {"info"|"warning"|"error"} level
* @param {string} [shard]
*/
export function outputMultiline(text, level = "info", shard = null) {
if (!text) return;
const prefix = shard ? `[${shard}] ` : "";
const lines = text.split(/\r?\n/);
lines.forEach((line) => {
const formattedLine = `${prefix}${line}`;
if (level === "error") core.error(formattedLine);
else if (level === "warning") core.warning(formattedLine);
else core.info(formattedLine);
});
}
/**
* Builds a CI-friendly progress string for core.info().
@@ -99,10 +117,6 @@ export function buildProgressMessage(elapsed, total) {
return `[Monitor] ${elapsed}/${total} ticks elapsed...`;
}
// ────────────────────────────────────────────────────────────────────────────
// File / artifact helpers
// ────────────────────────────────────────────────────────────────────────────
/**
* Writes an array of log lines to a UTF-8 text file, one line per entry.
*
@@ -115,37 +129,33 @@ export async function writeLogFile(lines, filePath) {
}
/**
* Uploads a file as a named workflow artifact using @actions/artifact.
* Uploads one or more files as a named workflow artifact using @actions/artifact.
* Degrades gracefully to core.warning() if the runner does not support the
* artifact service (e.g. a bare self-hosted runner without the service configured).
* artifact service.
*
* @param {string} filePath - Absolute path of the file to upload
* @param {string[]} filePaths - Absolute paths of the files to upload
* @param {string} [artifactName="screeps-console-log"] - Artifact display name
* @returns {Promise<void>}
*/
export async function uploadLogArtifact(
filePath,
export async function uploadLogArtifacts(
filePaths,
artifactName = "screeps-console-log",
) {
if (!filePaths || filePaths.length === 0) return;
try {
const client = new DefaultArtifactClient();
await client.uploadArtifact(
artifactName,
[filePath],
path.dirname(filePath),
);
core.info(`[Monitor] Console log uploaded as artifact '${artifactName}'.`);
const client = create();
const rootDir = path.dirname(filePaths[0]);
await client.uploadArtifact(artifactName, filePaths, rootDir, {
continueOnError: true,
});
core.info(`[Monitor] Console logs uploaded as artifact '${artifactName}'.`);
} catch (err) {
core.warning(
`[Monitor] Could not upload console log as artifact: ${err.message}`,
`[Monitor] Could not upload console logs as artifact: ${err.message}`,
);
}
}
// ────────────────────────────────────────────────────────────────────────────
// Console event handler
// ────────────────────────────────────────────────────────────────────────────
/**
* Processes a single 'console' WebSocket event from the Screeps socket.
* Mutates `state` and `stdoutBuffer` in place; never throws.
@@ -167,58 +177,63 @@ export async function uploadLogArtifact(
* - All stdout lines → core.info() when logToFile=false,
* pushed to stdoutBuffer when logToFile=true.
*
* @param {{ data?: { messages?: { log?: string[], results?: string[] }, error?: string } }} event
* @param {{ logToFile: boolean }} opts
* @param {string[]} stdoutBuffer - Mutable buffer used in logToFile mode
* @param {{ data?: { messages?: { log?: string[], results?: string[] }, error?: string, shard?: string } }} event
* @param {{ logToFile: boolean, shard?: string }} opts
* @param {Record<string, string[]>} shardBuffers - Mutable buffer Map used in logToFile mode
* @param {{ sawTraceback: boolean, sawErrorLog: boolean, sawWarningLog: boolean }} state
*/
export function handleConsoleEvent(event, opts, stdoutBuffer, state) {
const { logToFile } = opts;
export function handleConsoleEvent(event, opts, shardBuffers, state) {
const { logToFile, shard: targetShard } = opts;
const data = event?.data ?? {};
// Shard filtering: If a shard is specified in opts, only process messages from that shard.
// Official server events include a 'shard' property in event.data.
if (targetShard && data.shard && data.shard !== targetShard) {
return;
}
const logLines = data?.messages?.log ?? [];
const results = data?.messages?.results ?? [];
const errorText = data?.error ?? null;
// ── Warn detection (always live regardless of logToFile) ─────────────────
// Warn detection (always live regardless of logToFile)
if (detectWarning(logLines)) {
state.sawWarningLog = true;
const warnPattern = /<font\s+color=['"](?:orange|yellow)['"]/i;
logLines
.filter((l) => warnPattern.test(l))
.forEach((l) => core.warning(safeDecode(l)));
.forEach((l) => outputMultiline(safeDecode(l), "warning", data.shard));
}
// ── Traceback detection in log lines (Screeps sometimes sends errors here)
// Traceback detection in log lines (Screeps sometimes sends errors here)
if (logLines.some((l) => detectTraceback(l))) {
state.sawTraceback = true;
state.sawErrorLog = true;
}
// ── Stdout lines ──────────────────────────────────────────────────────────
// Stdout lines
const allStdout = [...logLines, ...results].map(safeDecode);
if (allStdout.length > 0) {
if (logToFile) {
stdoutBuffer.push(...allStdout);
const shard = data.shard || "default";
if (!shardBuffers[shard]) shardBuffers[shard] = [];
shardBuffers[shard].push(...allStdout);
} else {
allStdout.forEach((l) => core.info(l));
allStdout.forEach((l) => outputMultiline(l, "info", data.shard));
}
}
// ── Error field (always live) ─────────────────────────────────────────────
// Error field (always live)
if (errorText) {
state.sawErrorLog = true;
const decodedError = safeDecode(errorText);
core.error(decodedError);
outputMultiline(decodedError, "error", data.shard);
if (detectTraceback(decodedError)) {
state.sawTraceback = true;
}
}
}
// ────────────────────────────────────────────────────────────────────────────
// Tick polling
// ────────────────────────────────────────────────────────────────────────────
/**
* Sleeps for the given number of milliseconds.
*
@@ -262,10 +277,6 @@ export async function pollUntilDone(
return elapsed;
}
// ────────────────────────────────────────────────────────────────────────────
// Main orchestrator
// ────────────────────────────────────────────────────────────────────────────
/**
* @typedef {Object} MonitorOptions
* @property {number} monitor - Number of game ticks to collect.
@@ -317,7 +328,7 @@ export async function monitorConsole(api, opts) {
const subscribePath = buildSubscribePath(hostname, providedShard);
// Shared mutable state — updated by handleConsoleEvent via event listener
const stdoutBuffer = [];
const shardBuffers = {}; // { [shardName]: string[] }
const state = {
sawTraceback: false,
sawErrorLog: false,
@@ -325,13 +336,13 @@ export async function monitorConsole(api, opts) {
};
let lastProgressTick = 0;
// ── Step 1: record starting tick ─────────────────────────────────────────
// Step 1: record starting tick
const { time: startTick } = await api.time(shard);
// ── Step 2: connect socket + subscribe ───────────────────────────────────
// Step 2: connect socket + subscribe
await api.socket.connect();
await api.socket.subscribe(subscribePath, (event) => {
handleConsoleEvent(event, opts, stdoutBuffer, state);
handleConsoleEvent(event, opts, shardBuffers, state);
});
core.info(
@@ -340,7 +351,7 @@ export async function monitorConsole(api, opts) {
"...",
);
// ── Step 3 & 4: tick-poll loop ───────────────────────────────────────────
// Step 3 & 4: tick-poll loop
try {
await pollUntilDone(
api,
@@ -368,15 +379,29 @@ export async function monitorConsole(api, opts) {
},
);
} finally {
// ── Step 5: always disconnect cleanly ────────────────────────────────
// Step 5: always disconnect cleanly
api.socket.disconnect();
}
// ── Step 6: artifact upload ───────────────────────────────────────────────
if (logToFile && stdoutBuffer.length > 0) {
const tmpFile = path.join(os.tmpdir(), "screeps_console_log.txt");
await writeLogFile(stdoutBuffer, tmpFile);
await uploadLogArtifact(tmpFile);
// Step 6: artifact upload
const shardKeys = Object.keys(shardBuffers);
if (logToFile && shardKeys.length > 0) {
const tmpDir = await fs.promises.mkdtemp(
path.join(os.tmpdir(), "screeps-monitor-"),
);
const filePaths = [];
for (const sName of shardKeys) {
const fileName =
sName === "default"
? "screeps_console_log.txt"
: `${sName}_console_log.txt`;
const tmpFile = path.join(tmpDir, fileName);
await writeLogFile(shardBuffers[sName], tmpFile);
filePaths.push(tmpFile);
}
await uploadLogArtifacts(filePaths);
} else if (logToFile) {
core.info(
"[Monitor] No stdout lines were collected; skipping artifact upload.",
+28 -1816
View File
File diff suppressed because it is too large Load Diff
+3 -2
View File
@@ -1,7 +1,7 @@
{
"name": "screeps-deploy-action",
"version": "0.2.0",
"description": "Deploys screeps code to the official game or an pirvate server.",
"version": "0.2.1",
"description": "Deploys screeps code to the official game or a private server.",
"type": "module",
"main": "index.js",
"scripts": {
@@ -10,6 +10,7 @@
"build": "ncc build index.js -o dist -m --external utf-8-validate --external bufferutil"
},
"dependencies": {
"@actions/artifact": "^1.1.2",
"@actions/core": "^3.0.0",
"glob": "^13.0.0",
"screeps-api": "^1.7.2"