@kzheart_/mc-pilot 0.4.0 → 0.5.0

package/dist/commands/events.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare function createEventsCommand(): Command;

package/dist/commands/events.js

@@ -0,0 +1,129 @@
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { Command } from "commander";
+import { MctError } from "../util/errors.js";
+import { resolveMctHome } from "../util/paths.js";
+import { wrapCommand } from "../util/command.js";
+function resolveEventsFile(clientName) {
+    if (!clientName) {
+        throw new MctError({
+            code: "INVALID_PARAMS",
+            message: "Client name is required. Use --client <name> or set an active profile."
+        }, 4);
+    }
+    return path.join(resolveMctHome(), "logs", clientName, "events.jsonl");
+}
+function parseSince(raw, nowMs) {
+    if (!raw)
+        return undefined;
+    const trimmed = raw.trim();
+    // 支持 "30s" / "5m" / "1h" / "200ms" / epoch 毫秒
+    const m = /^(\d+(?:\.\d+)?)(ms|s|m|h)?$/.exec(trimmed);
+    if (!m) {
+        throw new MctError({ code: "INVALID_PARAMS", message: `Invalid --since value: ${raw}` }, 4);
+    }
+    const value = Number(m[1]);
+    const unit = m[2];
+    if (!unit) {
+        // epoch millis
+        return value;
+    }
+    const multipliers = { ms: 1, s: 1000, m: 60_000, h: 3_600_000 };
+    return nowMs - value * multipliers[unit];
+}
+function readAllEvents(filePath) {
+    if (!existsSync(filePath))
+        return [];
+    const raw = readFileSync(filePath, "utf8");
+    const lines = raw.split("\n").filter((line) => line.length > 0);
+    const out = [];
+    for (const line of lines) {
+        try {
+            out.push(JSON.parse(line));
+        }
+        catch {
+            // 跳过损坏行
+        }
+    }
+    return out;
+}
+export function createEventsCommand() {
+    const command = new Command("events").description("Inspect the client event log (written by the mod to ~/.mct/logs/<client>/events.jsonl)");
+    command
+        .command("list")
+        .description("Print events. Defaults to the last 20 for the active client.")
+        .option("--tail <n>", "Show the last N events (default 20)", (v) => Number(v))
+        .option("--since <duration>", "Only show events since duration ago (e.g. 30s, 5m, 1h) or epoch ms")
+        .option("--type <types>", "Comma-separated list of event types to include")
+        .option("--all", "Show all events (ignore --tail)")
+        .option("--file <path>", "Override the log file path")
+        .action(wrapCommand(async (context, { options, globalOptions }) => {
+        const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
+        const filePath = options.file ?? resolveEventsFile(clientName);
+        const events = readAllEvents(filePath);
+        let filtered = events;
+        const sinceMs = parseSince(options.since, Date.now());
+        if (sinceMs !== undefined) {
+            filtered = filtered.filter((e) => e.t >= sinceMs);
+        }
+        if (options.type) {
+            const wanted = new Set(options.type.split(",").map((s) => s.trim()).filter(Boolean));
+            filtered = filtered.filter((e) => wanted.has(e.type));
+        }
+        if (!options.all) {
+            const tail = options.tail ?? 20;
+            if (filtered.length > tail) {
+                filtered = filtered.slice(filtered.length - tail);
+            }
+        }
+        return {
+            file: filePath,
+            total: events.length,
+            returned: filtered.length,
+            events: filtered
+        };
+    }));
+    command
+        .command("tail")
+        .description("Shortcut for `events list --tail N`")
+        .argument("[n]", "Number of events (default 20)")
+        .option("--type <types>", "Comma-separated event types to include")
+        .option("--file <path>", "Override the log file path")
+        .action(wrapCommand(async (context, { args, options, globalOptions }) => {
+        const tail = args[0] ? Number(args[0]) : 20;
+        const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
+        const filePath = options.file ?? resolveEventsFile(clientName);
+        let events = readAllEvents(filePath);
+        if (options.type) {
+            const wanted = new Set(options.type.split(",").map((s) => s.trim()).filter(Boolean));
+            events = events.filter((e) => wanted.has(e.type));
+        }
+        if (events.length > tail)
+            events = events.slice(events.length - tail);
+        return { file: filePath, returned: events.length, events };
+    }));
+    command
+        .command("clear")
+        .description("Truncate the event log for the active client")
+        .option("--file <path>", "Override the log file path")
+        .action(wrapCommand(async (context, { options, globalOptions }) => {
+        const { truncateSync, existsSync: exists, mkdirSync } = await import("node:fs");
+        const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
+        const filePath = options.file ?? resolveEventsFile(clientName);
+        if (exists(filePath)) {
+            truncateSync(filePath, 0);
+            return { cleared: true, file: filePath };
+        }
+        // ensure directory exists for future writes
+        mkdirSync(path.dirname(filePath), { recursive: true });
+        return { cleared: false, reason: "file_not_found", file: filePath };
+    }));
+    command
+        .command("path")
+        .description("Print the expected path to the event log for the active client")
+        .action(wrapCommand(async (context, { globalOptions }) => {
+        const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
+        return { file: resolveEventsFile(clientName), exists: existsSync(resolveEventsFile(clientName)) };
+    }));
+    return command;
+}

package/dist/index.js

@@ -9,6 +9,7 @@ import { createChatCommand } from "./commands/chat.js";
 import { createCombatCommand } from "./commands/combat.js";
 import { createAnvilCommand, createCraftCommand, createEnchantCommand, createTradeCommand } from "./commands/craft.js";
 import { createEntityCommand } from "./commands/entity.js";
+import { createEventsCommand } from "./commands/events.js";
 import { createGuiCommand } from "./commands/gui.js";
 import { createHudCommand } from "./commands/hud.js";
 import { createInputCommand } from "./commands/input.js";
@@ -90,6 +91,7 @@ export function buildProgram() {
     program.addCommand(createEnchantCommand());
     program.addCommand(createTradeCommand());
     program.addCommand(createWaitCommand());
+    program.addCommand(createEventsCommand());
     return program;
 }
 const program = buildProgram();

package/dist/instance/ClientInstanceManager.d.ts

@@ -60,6 +60,8 @@ export declare class ClientInstanceManager {
         inWorld: boolean;
         position: unknown;
     }>;
+    private buildDiagnostics;
+    private formatDiagnostics;
     getClient(name?: string): Promise<ClientRuntimeEntry>;
     loadMeta(clientName: string): Promise<ClientInstanceMeta>;
     updateMeta(clientName: string, updates: Partial<ClientInstanceMeta>): Promise<ClientInstanceMeta>;

package/dist/instance/ClientInstanceManager.js

@@ -190,6 +190,7 @@ export class ClientInstanceManager {
         const requireWorld = options.requireWorld ?? true;
         // 阶段 A：等 WS 连通
         let connected = false;
+        let lastConnectError;
         while (Date.now() < deadline) {
             try {
                 const ws = new WebSocketClient(wsUrl);
@@ -197,12 +198,22 @@ export class ClientInstanceManager {
                 connected = true;
                 break;
             }
-            catch {
+            catch (err) {
+                lastConnectError = err instanceof Error ? err.message : String(err);
                 await new Promise((resolve) => setTimeout(resolve, 500));
             }
         }
         if (!connected) {
-            throw new MctError({ code: "TIMEOUT", message: `Timed out connecting to client ${clientName} on ${wsUrl}` }, 2);
+            const diag = this.buildDiagnostics(entry.pid, entry.wsPort, {
+                wsConnected: false,
+                inWorld: false,
+                lastError: lastConnectError
+            });
+            throw new MctError({
+                code: "TIMEOUT",
+                message: `Timed out after ${timeoutSeconds}s waiting for client ${clientName} (${wsUrl}). ${this.formatDiagnostics(diag)}`,
+                details: diag
+            }, 2);
         }
         if (!requireWorld) {
             return { connected: true, url: wsUrl };
@@ -221,16 +232,47 @@ export class ClientInstanceManager {
                     break;
                 }
             }
-            catch {
-                // 连接瞬断等偶发错误，继续轮询
+            catch (err) {
+                lastErrorCode = err instanceof Error ? `WS_ERROR(${err.message})` : "WS_ERROR";
             }
             await new Promise((resolve) => setTimeout(resolve, 500));
         }
+        const diag = this.buildDiagnostics(entry.pid, entry.wsPort, {
+            wsConnected: true,
+            inWorld: false,
+            lastError: lastErrorCode
+        });
         throw new MctError({
             code: "TIMEOUT",
-            message: `Client ${clientName} connected (${wsUrl}) but did not join a world (last status: ${lastErrorCode}). Tip: try \`mct client reconnect --address <server>\` or \`mct client launch --force\`.`
+            message: `Timed out after ${timeoutSeconds}s waiting for client ${clientName} to join a world (${wsUrl}). ${this.formatDiagnostics(diag)} Tip: try \`mct client reconnect --address <server>\` or \`mct client launch --force\`.`,
+            details: diag
         }, 2);
     }
+    buildDiagnostics(pid, wsPort, extras) {
+        const processAlive = isProcessRunning(pid);
+        const portListening = getListeningPids(wsPort).length > 0;
+        return {
+            pid,
+            processAlive,
+            wsPort,
+            portListening,
+            wsConnected: extras.wsConnected,
+            inWorld: extras.inWorld,
+            lastError: extras.lastError
+        };
+    }
+    formatDiagnostics(diag) {
+        const parts = [
+            `processAlive=${diag.processAlive}`,
+            `portListening=${diag.portListening}`,
+            `wsConnected=${diag.wsConnected}`,
+            `inWorld=${diag.inWorld}`
+        ];
+        if (diag.lastError) {
+            parts.push(`lastError=${diag.lastError}`);
+        }
+        return `Diagnostics: ${parts.join(", ")}.`;
+    }
     async getClient(name) {
         const state = await this.globalState.readClientState();
         const resolvedName = name ?? state.defaultClient;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kzheart_/mc-pilot",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "description": "Minecraft plugin/mod automated testing CLI – control a real Minecraft client to simulate player actions",
   "type": "module",
   "bin": {