@kzheart_/mc-pilot 0.3.4 → 0.4.1

package/dist/commands/client.js

@@ -129,6 +129,7 @@ export function createClientCommand() {
         .option("--account <account>", "Offline username or account identifier")
         .option("--ws-port <port>", "WebSocket port override", Number)
         .option("--headless", "Launch in headless mode")
+        .option("--force", "Kill any existing client with the same name before launching")
         .action(wrapCommand(async (context, { args, options }) => {
         const clientName = args[0] ?? context.activeProfile?.clients[0];
         if (!clientName) {
@@ -154,16 +155,19 @@ export function createClientCommand() {
     }));
     command
         .command("wait-ready")
-        .description("Wait until client WebSocket is connected")
+        .description("Wait until client WebSocket is connected AND the player has joined a world")
         .argument("[name]", "Client instance name (default: from active profile)")
         .option("--timeout <seconds>", "Timeout in seconds", Number)
+        .option("--no-world-check", "Only wait for WebSocket connection, skip the in-world check")
         .action(wrapCommand(async (context, { args, options }) => {
         const clientName = args[0] ?? context.activeProfile?.clients[0];
         if (!clientName) {
             throw new MctError({ code: "INVALID_PARAMS", message: "Client name is required" }, 4);
         }
         const manager = new ClientInstanceManager(context.globalState);
-        return manager.waitReady(clientName, options.timeout ?? context.timeout("clientReady"));
+        return manager.waitReady(clientName, options.timeout ?? context.timeout("clientReady"), {
+            requireWorld: options.worldCheck !== false
+        });
     }));
     command
         .command("reconnect")

package/dist/commands/project.js

@@ -82,16 +82,21 @@ export function createUpCommand() {
         // 3. Wait for server
         const serverMeta = await serverManager.loadMeta(profile.server);
         await serverManager.waitReady(profile.server, context.timeout("serverReady"));
-        // 4. Launch clients
+        // 4. Launch clients (reuse running clients via reconnect)
+        const serverAddress = `localhost:${serverMeta.port}`;
         const clientResults = [];
         for (const clientName of profile.clients) {
-            const result = await clientManager.launch(clientName, {
-                server: `localhost:${serverMeta.port}`
-            });
-            clientResults.push(result);
+            if (await clientManager.isAlreadyRunning(clientName)) {
+                const reconnected = await clientManager.reconnect(clientName, serverAddress);
+                clientResults.push(reconnected);
+            }
+            else {
+                const result = await clientManager.launch(clientName, { server: serverAddress });
+                clientResults.push(result);
+            }
         }
         results.clients = clientResults;
-        // 5. Wait for clients
+        // 5. Wait for clients (WS connected + in-world)
         for (const clientName of profile.clients) {
             await clientManager.waitReady(clientName, context.timeout("clientReady"));
         }
@@ -123,7 +128,11 @@ export function createDownCommand() {
         }
         results.clients = clientResults;
         // Stop server
-        results.server = await serverManager.stop(profile.server);
+        const serverResult = await serverManager.stop(profile.server);
+        results.server = serverResult;
+        const everythingAccountedFor = clientResults.every((r) => r.stopped || r.alreadyStopped) &&
+            (serverResult.stopped || serverResult.alreadyStopped);
+        results.allClean = Boolean(everythingAccountedFor);
         return results;
     }));
 }

package/dist/instance/ClientInstanceManager.d.ts

@@ -15,6 +15,10 @@ export interface LaunchClientOptions {
     account?: string;
     wsPort?: number;
     headless?: boolean;
+    force?: boolean;
+}
+export interface WaitReadyOptions {
+    requireWorld?: boolean;
 }
 export declare class ClientInstanceManager {
     private readonly globalState;
@@ -23,12 +27,20 @@ export declare class ClientInstanceManager {
     launch(clientName: string, options?: LaunchClientOptions): Promise<ClientRuntimeEntry>;
     stop(clientName: string): Promise<{
         stopped: boolean;
+        alreadyStopped: boolean;
         name: string;
         pid?: undefined;
     } | {
         stopped: boolean;
         name: string;
         pid: number;
+        alreadyStopped?: undefined;
+    }>;
+    isAlreadyRunning(clientName: string): Promise<boolean>;
+    reconnect(clientName: string, address: string): Promise<{
+        reconnected: boolean;
+        name: string;
+        address: string;
     }>;
     list(): Promise<{
         defaultClient: string | undefined;
@@ -37,10 +49,19 @@ export declare class ClientInstanceManager {
             pid?: number;
         })[];
     }>;
-    waitReady(clientName: string, timeoutSeconds: number): Promise<{
+    waitReady(clientName: string, timeoutSeconds: number, options?: WaitReadyOptions): Promise<{
+        connected: boolean;
+        url: string;
+        inWorld?: undefined;
+        position?: undefined;
+    } | {
         connected: boolean;
         url: string;
+        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

@@ -3,7 +3,7 @@ import { mkdirSync, openSync } from "node:fs";
 import { spawn } from "node:child_process";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
-import { resolveClientInstanceDir, resolveClientsDir } from "../util/paths.js";
+import { resolveMctHome, resolveClientInstanceDir, resolveClientsDir } from "../util/paths.js";
 import { MctError } from "../util/errors.js";
 import { getListeningPids, isProcessRunning, killProcessTree } from "../util/process.js";
 import { WebSocketClient } from "../client/WebSocketClient.js";
@@ -37,10 +37,20 @@ export class ClientInstanceManager {
         return meta;
     }
     async launch(clientName, options = {}) {
-        const state = await this.globalState.readClientState();
+        let state = await this.globalState.readClientState();
         const existing = state.clients[clientName];
         if (existing && isProcessRunning(existing.pid)) {
-            throw new MctError({ code: "CLIENT_ALREADY_RUNNING", message: `Client ${clientName} is already running`, details: existing }, 3);
+            if (options.force) {
+                await this.stop(clientName);
+                state = await this.globalState.readClientState();
+            }
+            else {
+                throw new MctError({
+                    code: "CLIENT_ALREADY_RUNNING",
+                    message: `Client ${clientName} is already running. Pass --force to kill and relaunch.`,
+                    details: existing
+                }, 3);
+            }
         }
         const meta = await this.loadMeta(clientName);
         const instanceDir = resolveClientInstanceDir(clientName);
@@ -64,7 +74,7 @@ export class ClientInstanceManager {
         }
         const launchCommand = [process.execPath, getLaunchScriptPath(), ...meta.launchArgs];
         const minecraftDir = path.join(instanceDir, "minecraft");
-        const logsDir = path.join(this.globalState.getRootDir(), "logs");
+        const logsDir = path.join(resolveMctHome(), "logs");
         mkdirSync(logsDir, { recursive: true });
         const logPath = path.join(logsDir, `client-${clientName}.log`);
         const stdout = openSync(logPath, "a");
@@ -101,7 +111,7 @@ export class ClientInstanceManager {
         const state = await this.globalState.readClientState();
         const entry = state.clients[clientName];
         if (!entry) {
-            return { stopped: false, name: clientName };
+            return { stopped: false, alreadyStopped: true, name: clientName };
         }
         if (isProcessRunning(entry.pid)) {
             killProcessTree(entry.pid);
@@ -118,6 +128,27 @@ export class ClientInstanceManager {
         await this.globalState.writeClientState(state);
         return { stopped: true, name: clientName, pid: entry.pid };
     }
+    async isAlreadyRunning(clientName) {
+        const state = await this.globalState.readClientState();
+        const entry = state.clients[clientName];
+        return Boolean(entry && isProcessRunning(entry.pid));
+    }
+    async reconnect(clientName, address) {
+        const state = await this.globalState.readClientState();
+        const entry = state.clients[clientName];
+        if (!entry) {
+            throw new MctError({ code: "CLIENT_NOT_FOUND", message: `Client ${clientName} is not running` }, 3);
+        }
+        const ws = new WebSocketClient(`ws://127.0.0.1:${entry.wsPort}`);
+        const response = (await ws.send("client.reconnect", { address }, 5));
+        if (response.error) {
+            throw new MctError({
+                code: response.error.code || "INTERNAL_ERROR",
+                message: response.error.message || `Reconnect failed for ${clientName}`
+            }, 3);
+        }
+        return { reconnected: true, name: clientName, address };
+    }
     async list() {
         const state = await this.globalState.readClientState();
         const runningClients = state.clients;
@@ -148,7 +179,7 @@ export class ClientInstanceManager {
             clients: instances
         };
     }
-    async waitReady(clientName, timeoutSeconds) {
+    async waitReady(clientName, timeoutSeconds, options = {}) {
         const state = await this.globalState.readClientState();
         const entry = state.clients[clientName];
         if (!entry) {
@@ -156,16 +187,91 @@ export class ClientInstanceManager {
         }
         const wsUrl = `ws://127.0.0.1:${entry.wsPort}`;
         const deadline = Date.now() + timeoutSeconds * 1000;
+        const requireWorld = options.requireWorld ?? true;
+        // 阶段 A：等 WS 连通
+        let connected = false;
+        let lastConnectError;
         while (Date.now() < deadline) {
             try {
                 const ws = new WebSocketClient(wsUrl);
-                return await ws.ping(1);
+                await ws.ping(1);
+                connected = true;
+                break;
             }
-            catch {
+            catch (err) {
+                lastConnectError = err instanceof Error ? err.message : String(err);
                 await new Promise((resolve) => setTimeout(resolve, 500));
             }
         }
-        throw new MctError({ code: "TIMEOUT", message: `Timed out waiting for client ${clientName} on ${wsUrl}` }, 2);
+        if (!connected) {
+            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 };
+        }
+        // 阶段 B：轮询 position.get 直到不再 NOT_IN_WORLD
+        let lastErrorCode = "NOT_IN_WORLD";
+        while (Date.now() < deadline) {
+            try {
+                const ws = new WebSocketClient(wsUrl);
+                const response = (await ws.send("position.get", {}, 1));
+                if (!response.error) {
+                    return { connected: true, url: wsUrl, inWorld: true, position: response.data };
+                }
+                lastErrorCode = response.error.code || lastErrorCode;
+                if (lastErrorCode !== "NOT_IN_WORLD") {
+                    break;
+                }
+            }
+            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: `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();

package/dist/instance/ServerInstanceManager.d.ts

@@ -25,11 +25,13 @@ export declare class ServerInstanceManager {
     stop(serverName: string): Promise<{
         running: boolean;
         stopped: boolean;
+        alreadyStopped: boolean;
         pid?: undefined;
     } | {
         running: boolean;
         stopped: boolean;
         pid: number;
+        alreadyStopped?: undefined;
     }>;
     status(serverName?: string): Promise<{
         [key: string]: unknown;

package/dist/instance/ServerInstanceManager.js

@@ -2,7 +2,7 @@ import { copyFile, mkdir, readdir, readFile, writeFile, unlink } from "node:fs/p
 import { mkdirSync, openSync } from "node:fs";
 import { spawn, execSync } from "node:child_process";
 import path from "node:path";
-import { resolveProjectDir, resolveServerInstanceDir } from "../util/paths.js";
+import { resolveMctHome, resolveProjectDir, resolveServerInstanceDir } from "../util/paths.js";
 import { MctError } from "../util/errors.js";
 import { waitForTcpPort } from "../util/net.js";
 import { isProcessRunning, killProcessTree } from "../util/process.js";
@@ -56,8 +56,9 @@ export class ServerInstanceManager {
         if (options.eula) {
             await writeFile(path.join(instanceDir, "eula.txt"), "eula=true\n", "utf8");
         }
-        const logsDir = path.join(this.globalState.getRootDir(), "logs");
-        const stateDir = path.join(this.globalState.getRootDir(), "state");
+        const mctHome = resolveMctHome();
+        const logsDir = path.join(mctHome, "logs");
+        const stateDir = path.join(mctHome, "state");
         mkdirSync(logsDir, { recursive: true });
         mkdirSync(stateDir, { recursive: true });
         const logPath = path.join(logsDir, `server-${this.project}-${serverName}.log`);
@@ -70,11 +71,12 @@ export class ServerInstanceManager {
         }
         catch { /* ignore */ }
         execSync(`mkfifo "${stdinPipe}"`);
-        // Use bash wrapper: hold FIFO write end open (fd 3) to prevent EOF,
+        // Use bash wrapper: hold FIFO open in read-write mode (fd 3 <>) to prevent EOF
+        // without blocking (write-only > would block until a reader opens the other end),
         // then exec java with stdin reading from the FIFO
         const child = spawn("bash", [
             "-c",
-            'exec 3>"$MCT_STDIN_PIPE"; exec java "$@" <"$MCT_STDIN_PIPE"',
+            'exec 3<>"$MCT_STDIN_PIPE"; exec java "$@" <"$MCT_STDIN_PIPE"',
             "mct-server",
             ...jvmArgs, "-jar", jarFile, "nogui"
         ], {
@@ -107,7 +109,7 @@ export class ServerInstanceManager {
         const state = await this.globalState.readServerState();
         const entry = state.servers[stateKey];
         if (!entry) {
-            return { running: false, stopped: false };
+            return { running: false, stopped: false, alreadyStopped: true };
         }
         if (isProcessRunning(entry.pid)) {
             killProcessTree(entry.pid);

package/package.json

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