@kzheart_/mc-pilot 0.9.0 → 0.9.1

package/data/variants.json

@@ -9,7 +9,7 @@
       "loader": "fabric",
       "support": "ready",
       "validation": "verified",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "fabricLoaderVersion": "0.16.14",
       "yarnMappings": "1.18.2+build.4",
       "javaVersion": 17,
@@ -21,7 +21,7 @@
       "loader": "fabric",
       "support": "ready",
       "validation": "verified",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "fabricLoaderVersion": "0.16.14",
       "yarnMappings": "1.20.1+build.10",
       "javaVersion": 17,
@@ -33,7 +33,7 @@
       "loader": "forge",
       "support": "planned",
       "validation": "planned",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "forgeVersion": "47.3.0",
       "javaVersion": 17
     },
@@ -43,7 +43,7 @@
       "loader": "fabric",
       "support": "ready",
       "validation": "verified",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "fabricLoaderVersion": "0.16.14",
       "yarnMappings": "1.20.2+build.4",
       "javaVersion": 17,
@@ -55,7 +55,7 @@
       "loader": "forge",
       "support": "planned",
       "validation": "planned",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "forgeVersion": "48.1.0",
       "javaVersion": 17
     },
@@ -65,7 +65,7 @@
       "loader": "fabric",
       "support": "ready",
       "validation": "verified",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "fabricLoaderVersion": "0.16.14",
       "yarnMappings": "1.20.4+build.3",
       "javaVersion": 17,
@@ -77,7 +77,7 @@
       "loader": "forge",
       "support": "planned",
       "validation": "planned",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "forgeVersion": "49.0.49",
       "javaVersion": 17
     },
@@ -87,7 +87,7 @@
       "loader": "neoforge",
       "support": "planned",
       "validation": "planned",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "neoforgeVersion": "20.4.237",
       "javaVersion": 17
     },
@@ -97,7 +97,7 @@
       "loader": "fabric",
       "support": "ready",
       "validation": "verified",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "fabricLoaderVersion": "0.16.14",
       "yarnMappings": "1.21.1+build.3",
       "javaVersion": 21,
@@ -109,7 +109,7 @@
       "loader": "neoforge",
       "support": "planned",
       "validation": "planned",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "neoforgeVersion": "21.1.77",
       "javaVersion": 21
     },
@@ -119,7 +119,7 @@
       "loader": "fabric",
       "support": "ready",
       "validation": "verified",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "fabricLoaderVersion": "0.16.14",
       "yarnMappings": "1.21.4+build.1",
       "javaVersion": 21,
@@ -131,7 +131,7 @@
       "loader": "neoforge",
       "support": "planned",
       "validation": "planned",
-      "modVersion": "0.1.1",
+      "modVersion": "0.9.1",
       "neoforgeVersion": "21.4.75",
       "javaVersion": 21
     }

package/dist/commands/client.js

@@ -91,7 +91,7 @@ export function createClientCommand() {
                 sourcePath = cacheArtifactPath;
             }
             catch {
-                const modVersion = variant.modVersion ?? "0.1.0";
+                const modVersion = variant.modVersion ?? "0.9.1";
                 const baseUrl = process.env.MCT_MOD_DOWNLOAD_BASE_URL || "https://github.com/kzheart/mc-pilot/releases/download";
                 const downloadUrl = `${baseUrl}/v${modVersion}/${artifactFileName}`;
                 await downloadFile(downloadUrl, cacheArtifactPath, fetch);

package/dist/download/VersionMatrix.js

@@ -10,9 +10,9 @@ const VERSION_MATRIX = [
             spigot: { supported: true, requiresBuildTools: true }
         },
         clients: {
-            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.1.1", validation: "verified" },
+            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1", validation: "verified" },
             forge: { supported: false, notes: "不支持此版本" },
-            neoforge: { supported: true, loaderVersion: "21.4.x", modVersion: "0.1.1" }
+            neoforge: { supported: true, loaderVersion: "21.4.x", modVersion: "0.9.1" }
         }
     },
     {
@@ -25,9 +25,9 @@ const VERSION_MATRIX = [
             spigot: { supported: true, requiresBuildTools: true }
         },
         clients: {
-            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.1.1", validation: "verified" },
+            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1", validation: "verified" },
             forge: { supported: false, notes: "不支持此版本" },
-            neoforge: { supported: true, loaderVersion: "21.1.x", modVersion: "0.1.1" }
+            neoforge: { supported: true, loaderVersion: "21.1.x", modVersion: "0.9.1" }
         }
     },
     {
@@ -40,8 +40,8 @@ const VERSION_MATRIX = [
             spigot: { supported: true, requiresBuildTools: true }
         },
         clients: {
-            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.1.1" },
-            forge: { supported: true, loaderVersion: "49.0.49", modVersion: "0.1.1" },
+            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1" },
+            forge: { supported: true, loaderVersion: "49.0.49", modVersion: "0.9.1" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
     },
@@ -55,7 +55,7 @@ const VERSION_MATRIX = [
             spigot: { supported: true, requiresBuildTools: true }
         },
         clients: {
-            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.1.1", validation: "verified" },
+            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1", validation: "verified" },
             forge: { supported: false, notes: "当前未接入此 loader" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
@@ -70,7 +70,7 @@ const VERSION_MATRIX = [
             spigot: { supported: true, requiresBuildTools: true }
         },
         clients: {
-            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.1.1" },
+            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1" },
             forge: { supported: false, notes: "当前未接入此 loader" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
@@ -85,8 +85,8 @@ const VERSION_MATRIX = [
             spigot: { supported: true, requiresBuildTools: true }
         },
         clients: {
-            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.1.1" },
-            forge: { supported: true, loaderVersion: "47.x", modVersion: "0.1.1" },
+            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1" },
+            forge: { supported: true, loaderVersion: "47.x", modVersion: "0.9.1" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
     },
@@ -100,8 +100,8 @@ const VERSION_MATRIX = [
             spigot: { supported: true, requiresBuildTools: true }
         },
         clients: {
-            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.1.1", validation: "verified" },
-            forge: { supported: true, loaderVersion: "40.x", modVersion: "0.1.1" },
+            fabric: { supported: true, loaderVersion: "0.16.14", modVersion: "0.9.1", validation: "verified" },
+            forge: { supported: true, loaderVersion: "40.x", modVersion: "0.9.1" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
     },
@@ -116,7 +116,7 @@ const VERSION_MATRIX = [
         },
         clients: {
             fabric: { supported: false, notes: "当前未接入此版本 mod" },
-            forge: { supported: true, loaderVersion: "36.x", modVersion: "0.1.1" },
+            forge: { supported: true, loaderVersion: "36.x", modVersion: "0.9.1" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
     },
@@ -131,7 +131,7 @@ const VERSION_MATRIX = [
         },
         clients: {
             fabric: { supported: false, notes: "不支持此版本" },
-            forge: { supported: true, loaderVersion: "14.23.x", modVersion: "0.1.1" },
+            forge: { supported: true, loaderVersion: "14.23.x", modVersion: "0.9.1" },
             neoforge: { supported: false, notes: "不支持此版本" }
         }
     }

package/dist/download/client/ClientDownloader.js

@@ -51,7 +51,7 @@ export async function resolveArtifact(cwd, variant, cacheManager, fetchImpl = fe
     }
     catch { }
     // 3. Download from GitHub Releases
-    const modVersion = variant.modVersion ?? "0.1.0";
+    const modVersion = variant.modVersion ?? "0.9.1";
     const releaseTag = `v${modVersion}`;
     const downloadUrl = `${GITHUB_RELEASE_BASE_URL}/${releaseTag}/${artifactFileName}`;
     try {

package/dist/instance/ClientInstanceManager.d.ts

@@ -67,4 +67,5 @@ export declare class ClientInstanceManager {
     updateMeta(clientName: string, updates: Partial<ClientInstanceMeta>): Promise<ClientInstanceMeta>;
     private isWsReachable;
     private findAvailablePort;
+    private stopTrackedClient;
 }

package/dist/instance/ClientInstanceManager.js

@@ -19,114 +19,107 @@ export class ClientInstanceManager {
         this.globalState = globalState;
     }
     async create(options) {
-        const instanceDir = resolveClientInstanceDir(options.name);
-        await mkdir(instanceDir, { recursive: true });
-        const wsPort = options.wsPort ?? (await this.findAvailablePort());
-        const meta = {
-            name: options.name,
-            loader: options.loader ?? "fabric",
-            mcVersion: options.version,
-            wsPort,
-            account: options.account,
-            headless: options.headless,
-            launchArgs: options.launchArgs,
-            env: options.env,
-            createdAt: new Date().toISOString()
-        };
-        await writeFile(path.join(instanceDir, INSTANCE_FILE), `${JSON.stringify(meta, null, 2)}\n`, "utf8");
-        return meta;
+        return this.globalState.withClientLock(async () => {
+            const instanceDir = resolveClientInstanceDir(options.name);
+            await mkdir(instanceDir, { recursive: true });
+            const wsPort = options.wsPort ?? (await this.findAvailablePort());
+            const meta = {
+                name: options.name,
+                loader: options.loader ?? "fabric",
+                mcVersion: options.version,
+                wsPort,
+                account: options.account,
+                headless: options.headless,
+                launchArgs: options.launchArgs,
+                env: options.env,
+                createdAt: new Date().toISOString()
+            };
+            await writeFile(path.join(instanceDir, INSTANCE_FILE), `${JSON.stringify(meta, null, 2)}\n`, "utf8");
+            return meta;
+        });
     }
     async launch(clientName, options = {}) {
-        let state = await this.globalState.readClientState();
-        const existing = state.clients[clientName];
-        if (existing && isProcessRunning(existing.pid)) {
-            if (options.force) {
-                await this.stop(clientName);
-                state = await this.globalState.readClientState();
+        return this.globalState.withClientLock(async () => {
+            const state = await this.globalState.readClientState();
+            const existing = state.clients[clientName];
+            if (existing && isProcessRunning(existing.pid)) {
+                if (options.force) {
+                    await this.stopTrackedClient(state, clientName, existing);
+                }
+                else {
+                    throw new MctError({
+                        code: "CLIENT_ALREADY_RUNNING",
+                        message: `Client ${clientName} is already running. Pass --force to kill and relaunch.`,
+                        details: existing
+                    }, 3);
+                }
             }
-            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);
+            const wsPort = options.wsPort ?? meta.wsPort;
+            if (!meta.launchArgs || meta.launchArgs.length === 0) {
+                throw new MctError({ code: "INVALID_PARAMS", message: `Client ${clientName} has no launchArgs configured` }, 4);
             }
-        }
-        const meta = await this.loadMeta(clientName);
-        const instanceDir = resolveClientInstanceDir(clientName);
-        const wsPort = options.wsPort ?? meta.wsPort;
-        if (!meta.launchArgs || meta.launchArgs.length === 0) {
-            throw new MctError({ code: "INVALID_PARAMS", message: `Client ${clientName} has no launchArgs configured` }, 4);
-        }
-        // Kill any existing processes on the port
-        const listeningPids = getListeningPids(wsPort);
-        for (const pid of listeningPids) {
-            killProcessTree(pid);
-        }
-        if (listeningPids.length > 0) {
-            const deadline = Date.now() + 10_000;
-            while (Date.now() < deadline) {
-                if (getListeningPids(wsPort).length === 0) {
-                    break;
-                }
-                await new Promise((resolve) => setTimeout(resolve, 250));
+            const listeningPids = getListeningPids(wsPort);
+            for (const pid of listeningPids) {
+                killProcessTree(pid);
             }
-        }
-        const launchCommand = [process.execPath, getLaunchScriptPath(), ...meta.launchArgs];
-        const minecraftDir = path.join(instanceDir, "minecraft");
-        const logsDir = path.join(resolveMctHome(), "logs");
-        mkdirSync(logsDir, { recursive: true });
-        const logPath = path.join(logsDir, `client-${clientName}.log`);
-        const stdout = openSync(logPath, "a");
-        const child = spawn(launchCommand[0], launchCommand.slice(1), {
-            cwd: minecraftDir,
-            detached: true,
-            stdio: ["ignore", stdout, stdout],
-            env: {
-                ...process.env,
-                ...meta.env,
-                MCT_CLIENT_NAME: clientName,
-                MCT_CLIENT_VERSION: meta.mcVersion,
-                MCT_CLIENT_ACCOUNT: options.account ?? meta.account ?? "",
-                MCT_CLIENT_SERVER: options.server ?? "",
-                MCT_CLIENT_WS_PORT: String(wsPort),
-                MCT_CLIENT_HEADLESS: String(options.headless ?? meta.headless ?? false)
+            if (listeningPids.length > 0) {
+                const deadline = Date.now() + 10_000;
+                while (Date.now() < deadline) {
+                    if (getListeningPids(wsPort).length === 0) {
+                        break;
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, 250));
+                }
             }
+            const launchCommand = [process.execPath, getLaunchScriptPath(), ...meta.launchArgs];
+            const minecraftDir = path.join(instanceDir, "minecraft");
+            const logsDir = path.join(resolveMctHome(), "logs");
+            mkdirSync(logsDir, { recursive: true });
+            const logPath = path.join(logsDir, `client-${clientName}.log`);
+            const stdout = openSync(logPath, "a");
+            const child = spawn(launchCommand[0], launchCommand.slice(1), {
+                cwd: minecraftDir,
+                detached: true,
+                stdio: ["ignore", stdout, stdout],
+                env: {
+                    ...process.env,
+                    ...meta.env,
+                    MCT_CLIENT_NAME: clientName,
+                    MCT_CLIENT_VERSION: meta.mcVersion,
+                    MCT_CLIENT_ACCOUNT: options.account ?? meta.account ?? "",
+                    MCT_CLIENT_SERVER: options.server ?? "",
+                    MCT_CLIENT_WS_PORT: String(wsPort),
+                    MCT_CLIENT_HEADLESS: String(options.headless ?? meta.headless ?? false)
+                }
+            });
+            child.unref();
+            const entry = {
+                pid: child.pid ?? 0,
+                name: clientName,
+                wsPort,
+                startedAt: new Date().toISOString(),
+                logPath,
+                instanceDir
+            };
+            state.defaultClient ??= clientName;
+            state.clients[clientName] = entry;
+            await this.globalState.writeClientState(state);
+            return entry;
         });
-        child.unref();
-        const entry = {
-            pid: child.pid ?? 0,
-            name: clientName,
-            wsPort,
-            startedAt: new Date().toISOString(),
-            logPath,
-            instanceDir
-        };
-        state.defaultClient ??= clientName;
-        state.clients[clientName] = entry;
-        await this.globalState.writeClientState(state);
-        return entry;
     }
     async stop(clientName) {
-        const state = await this.globalState.readClientState();
-        const entry = state.clients[clientName];
-        if (!entry) {
-            return { stopped: false, alreadyStopped: true, name: clientName };
-        }
-        if (isProcessRunning(entry.pid)) {
-            killProcessTree(entry.pid);
-        }
-        for (const pid of getListeningPids(entry.wsPort)) {
-            if (pid !== entry.pid) {
-                killProcessTree(pid);
+        return this.globalState.withClientLock(async () => {
+            const state = await this.globalState.readClientState();
+            const entry = state.clients[clientName];
+            if (!entry) {
+                return { stopped: false, alreadyStopped: true, name: clientName };
             }
-        }
-        delete state.clients[clientName];
-        if (state.defaultClient === clientName) {
-            state.defaultClient = Object.keys(state.clients)[0];
-        }
-        await this.globalState.writeClientState(state);
-        return { stopped: true, name: clientName, pid: entry.pid };
+            await this.stopTrackedClient(state, clientName, entry);
+            await this.globalState.writeClientState(state);
+            return { stopped: true, name: clientName, pid: entry.pid };
+        });
     }
     async isAlreadyRunning(clientName) {
         const state = await this.globalState.readClientState();
@@ -340,4 +333,18 @@ export class ClientInstanceManager {
         }
         return port;
     }
+    async stopTrackedClient(state, clientName, entry) {
+        if (isProcessRunning(entry.pid)) {
+            killProcessTree(entry.pid);
+        }
+        for (const pid of getListeningPids(entry.wsPort)) {
+            if (pid !== entry.pid) {
+                killProcessTree(pid);
+            }
+        }
+        delete state.clients[clientName];
+        if (state.defaultClient === clientName) {
+            state.defaultClient = Object.keys(state.clients)[0];
+        }
+    }
 }

package/dist/instance/ServerInstanceManager.d.ts

@@ -70,6 +70,10 @@ export declare class ServerInstanceManager {
         reachable: boolean;
         host: string;
         port: number;
+        phase: string;
+        logPath: string;
+        lastLine: string | null;
+        recentLines: string[];
     }>;
     exec(serverName: string, command: string): Promise<{
         sent: boolean;
@@ -99,6 +103,7 @@ export declare class ServerInstanceManager {
         timedOut: boolean;
     }>;
     private requireRuntimeEntry;
+    private describeStartup;
     private requireRunning;
     list(): Promise<ServerInstanceMeta[]>;
     static listAll(globalState: GlobalStateStore): Promise<ServerInstanceMeta[]>;

package/dist/instance/ServerInstanceManager.js

@@ -4,11 +4,12 @@ import { spawn, execSync } from "node:child_process";
 import path from "node:path";
 import { resolveMctHome, resolveProjectDir, resolveServerInstanceDir } from "../util/paths.js";
 import { MctError } from "../util/errors.js";
-import { waitForTcpPort } from "../util/net.js";
+import { isTcpPortReachable } from "../util/net.js";
 import { isProcessRunning, killProcessTree } from "../util/process.js";
 import { copyFileIfMissing } from "../download/DownloadUtils.js";
 const INSTANCE_FILE = "instance.json";
 const ANSI_ESCAPE_PATTERN = /\u001b\[[0-?]*[ -/]*[@-~]/g;
+const SERVER_READY_POLL_MS = 500;
 export function stripAnsiCodes(text) {
     return text.replace(ANSI_ESCAPE_PATTERN, "");
 }
@@ -108,7 +109,7 @@ export class ServerInstanceManager {
         // 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 "$@" 0<&3',
             "mct-server",
             ...jvmArgs, "-jar", jarFile, "nogui"
         ], {
@@ -206,7 +207,51 @@ export class ServerInstanceManager {
         if (!entry) {
             throw new MctError({ code: "SERVER_NOT_RUNNING", message: `Server ${stateKey} is not running` }, 5);
         }
-        return waitForTcpPort("127.0.0.1", entry.port, timeoutSeconds);
+        const deadline = Date.now() + timeoutSeconds * 1000;
+        let snapshot = await this.describeStartup(entry.logPath);
+        while (Date.now() < deadline) {
+            if (!isProcessRunning(entry.pid)) {
+                throw new MctError({
+                    code: "SERVER_EXITED",
+                    message: `Server ${stateKey} exited before becoming ready (${snapshot.phase})`,
+                    details: {
+                        pid: entry.pid,
+                        host: "127.0.0.1",
+                        port: entry.port,
+                        phase: snapshot.phase,
+                        logPath: snapshot.logPath,
+                        lastLine: snapshot.lastLine,
+                        recentLines: snapshot.recentLines
+                    }
+                }, 5);
+            }
+            if (await isTcpPortReachable("127.0.0.1", entry.port)) {
+                snapshot = await this.describeStartup(entry.logPath);
+                return {
+                    reachable: true,
+                    host: "127.0.0.1",
+                    port: entry.port,
+                    phase: snapshot.phase,
+                    logPath: snapshot.logPath,
+                    lastLine: snapshot.lastLine,
+                    recentLines: snapshot.recentLines
+                };
+            }
+            snapshot = await this.describeStartup(entry.logPath);
+            await new Promise((resolve) => setTimeout(resolve, SERVER_READY_POLL_MS));
+        }
+        throw new MctError({
+            code: "TIMEOUT",
+            message: `Timed out waiting for 127.0.0.1:${entry.port} (${snapshot.phase})`,
+            details: {
+                host: "127.0.0.1",
+                port: entry.port,
+                phase: snapshot.phase,
+                logPath: snapshot.logPath,
+                lastLine: snapshot.lastLine,
+                recentLines: snapshot.recentLines
+            }
+        }, 2);
     }
     async exec(serverName, command) {
         const entry = await this.requireRunning(serverName);
@@ -338,6 +383,21 @@ export class ServerInstanceManager {
         }
         return entry;
     }
+    async describeStartup(logPath) {
+        const raw = await readFile(logPath, "utf8").catch(() => "");
+        const recentLines = raw
+            .split(/\r?\n/)
+            .map((line) => stripAnsiCodes(line).trim())
+            .filter((line) => line.length > 0)
+            .slice(-10);
+        const lastLine = recentLines[recentLines.length - 1] ?? null;
+        return {
+            phase: detectServerStartupPhase(recentLines),
+            logPath,
+            recentLines,
+            lastLine
+        };
+    }
     async requireRunning(serverName) {
         const entry = await this.requireRuntimeEntry(serverName);
         if (!isProcessRunning(entry.pid)) {
@@ -430,3 +490,25 @@ export class ServerInstanceManager {
         return port;
     }
 }
+function detectServerStartupPhase(lines) {
+    const joined = lines.join("\n");
+    if (/Done \(.+\)! For help, type "help"/.test(joined)) {
+        return "ready";
+    }
+    if (/Preparing start region|Preparing level/.test(joined)) {
+        return "initializing-world";
+    }
+    if (/Starting Minecraft server on/.test(joined)) {
+        return "binding-port";
+    }
+    if (/Loading libraries, please wait|Starting org\.bukkit\.craftbukkit\.Main|Starting minecraft server version/.test(joined)) {
+        return "bootstrapping";
+    }
+    if (/Downloading |Applying patches/.test(joined)) {
+        return "downloading";
+    }
+    if (lines.length > 0) {
+        return "starting";
+    }
+    return "waiting-for-log";
+}

package/dist/util/command-log.d.ts

@@ -0,0 +1,12 @@
+export interface CommandLogEntry {
+    t: number;
+    iso: string;
+    argv: string[];
+    cwd: string;
+    projectId: string | null;
+    exitCode: number;
+    durationMs: number;
+    errorCode?: string;
+    errorMessage?: string;
+}
+export declare function appendCommandHistory(entry: CommandLogEntry): Promise<void>;

package/dist/util/command-log.js

@@ -0,0 +1,13 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { resolveCommandsLogPath } from "./paths.js";
+export async function appendCommandHistory(entry) {
+    try {
+        const filePath = resolveCommandsLogPath();
+        await mkdir(path.dirname(filePath), { recursive: true });
+        await appendFile(filePath, `${JSON.stringify(entry)}\n`, "utf8");
+    }
+    catch {
+        // Never block the command on logging failure
+    }
+}

package/dist/util/global-state.d.ts

@@ -2,8 +2,12 @@ import { StateStore } from "./state.js";
 import type { GlobalClientState, GlobalServerState } from "./instance-types.js";
 export declare class GlobalStateStore extends StateStore {
     constructor();
+    withClientLock<T>(task: () => Promise<T>): Promise<T>;
+    withServerLock<T>(task: () => Promise<T>): Promise<T>;
     readServerState(): Promise<GlobalServerState>;
     writeServerState(state: GlobalServerState): Promise<void>;
     readClientState(): Promise<GlobalClientState>;
     writeClientState(state: GlobalClientState): Promise<void>;
+    updateClientState<T>(mutate: (state: GlobalClientState) => Promise<T> | T): Promise<T>;
+    updateServerState<T>(mutate: (state: GlobalServerState) => Promise<T> | T): Promise<T>;
 }

package/dist/util/global-state.js

@@ -6,6 +6,12 @@ export class GlobalStateStore extends StateStore {
     constructor() {
         super(resolveGlobalStateDir());
     }
+    async withClientLock(task) {
+        return this.withLock("clients", task);
+    }
+    async withServerLock(task) {
+        return this.withLock("servers", task);
+    }
     async readServerState() {
         return this.readJson(SERVERS_STATE_FILE, { servers: {} });
     }
@@ -18,4 +24,20 @@ export class GlobalStateStore extends StateStore {
     async writeClientState(state) {
         await this.writeJson(CLIENTS_STATE_FILE, state);
     }
+    async updateClientState(mutate) {
+        return this.withClientLock(async () => {
+            const state = await this.readClientState();
+            const result = await mutate(state);
+            await this.writeClientState(state);
+            return result;
+        });
+    }
+    async updateServerState(mutate) {
+        return this.withServerLock(async () => {
+            const state = await this.readServerState();
+            const result = await mutate(state);
+            await this.writeServerState(state);
+            return result;
+        });
+    }
 }

package/dist/util/net.d.ts

@@ -1,3 +1,4 @@
+export declare function isTcpPortReachable(host: string, port: number): Promise<boolean>;
 export declare function waitForTcpPort(host: string, port: number, timeoutSeconds: number): Promise<{
     reachable: boolean;
     host: string;

package/dist/util/net.js

@@ -5,21 +5,23 @@ function wait(ms) {
         setTimeout(resolve, ms);
     });
 }
+export async function isTcpPortReachable(host, port) {
+    return await new Promise((resolve) => {
+        const socket = net.createConnection({ host, port });
+        socket.once("connect", () => {
+            socket.destroy();
+            resolve(true);
+        });
+        socket.once("error", () => {
+            socket.destroy();
+            resolve(false);
+        });
+    });
+}
 export async function waitForTcpPort(host, port, timeoutSeconds) {
     const deadline = Date.now() + timeoutSeconds * 1000;
     while (Date.now() < deadline) {
-        const reachable = await new Promise((resolve) => {
-            const socket = net.createConnection({ host, port });
-            socket.once("connect", () => {
-                socket.destroy();
-                resolve(true);
-            });
-            socket.once("error", () => {
-                socket.destroy();
-                resolve(false);
-            });
-        });
-        if (reachable) {
+        if (await isTcpPortReachable(host, port)) {
             return {
                 reachable: true,
                 host,

package/dist/util/state.d.ts

@@ -6,5 +6,10 @@ export declare class StateStore {
     readJson<T>(name: string, fallback: T): Promise<T>;
     writeJson(name: string, value: unknown): Promise<void>;
     remove(name: string): Promise<void>;
+    withLock<T>(name: string, task: () => Promise<T>, options?: {
+        timeoutMs?: number;
+        staleMs?: number;
+    }): Promise<T>;
+    private cleanupStaleLock;
 }
 export declare function resolveStateDir(stateDir: string | undefined, cwd: string): string;

package/dist/util/state.js

@@ -1,5 +1,22 @@
-import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { mkdir, readFile, rename, rm, writeFile } from "node:fs/promises";
 import path from "node:path";
+import process from "node:process";
+const DEFAULT_LOCK_TIMEOUT_MS = 15_000;
+const DEFAULT_LOCK_STALE_MS = 60_000;
+const LOCK_POLL_INTERVAL_MS = 50;
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isPidRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
 export class StateStore {
     rootDir;
     constructor(rootDir) {
@@ -25,12 +42,74 @@ export class StateStore {
     async writeJson(name, value) {
         await this.ensure();
         const target = path.join(this.rootDir, name);
+        const tempTarget = `${target}.${process.pid}.${randomUUID()}.tmp`;
         const content = JSON.stringify(value, null, 2);
-        await writeFile(target, `${content}\n`, "utf8");
+        await writeFile(tempTarget, `${content}\n`, "utf8");
+        await rename(tempTarget, target);
     }
     async remove(name) {
         await rm(path.join(this.rootDir, name), { force: true });
     }
+    async withLock(name, task, options = {}) {
+        await this.ensure();
+        const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_LOCK_TIMEOUT_MS);
+        const staleMs = options.staleMs ?? DEFAULT_LOCK_STALE_MS;
+        const safeName = name.replace(/[\\/]/g, "-");
+        const lockDir = path.join(this.rootDir, `${safeName}.lock`);
+        const ownerPath = path.join(lockDir, "owner.json");
+        while (true) {
+            try {
+                await mkdir(lockDir);
+                const owner = {
+                    pid: process.pid,
+                    acquiredAt: new Date().toISOString(),
+                    acquiredAtMs: Date.now()
+                };
+                await writeFile(ownerPath, `${JSON.stringify(owner, null, 2)}\n`, "utf8");
+                break;
+            }
+            catch (error) {
+                const lockExists = typeof error === "object"
+                    && error !== null
+                    && "code" in error
+                    && error.code === "EEXIST";
+                if (!lockExists) {
+                    throw error;
+                }
+                if (await this.cleanupStaleLock(lockDir, ownerPath, staleMs)) {
+                    continue;
+                }
+                if (Date.now() >= deadline) {
+                    throw new Error(`Timed out waiting for lock ${safeName}`);
+                }
+                await sleep(LOCK_POLL_INTERVAL_MS);
+            }
+        }
+        try {
+            return await task();
+        }
+        finally {
+            await rm(lockDir, { recursive: true, force: true });
+        }
+    }
+    async cleanupStaleLock(lockDir, ownerPath, staleMs) {
+        try {
+            const raw = await readFile(ownerPath, "utf8");
+            const owner = JSON.parse(raw);
+            const pid = Number(owner.pid);
+            const acquiredAtMs = typeof owner.acquiredAtMs === "number" ? owner.acquiredAtMs : NaN;
+            const ownerAlive = Number.isInteger(pid) && pid > 0 ? isPidRunning(pid) : false;
+            const isStale = Number.isFinite(acquiredAtMs) && Date.now() - acquiredAtMs > staleMs;
+            if (!ownerAlive || isStale) {
+                await rm(lockDir, { recursive: true, force: true });
+                return true;
+            }
+        }
+        catch {
+            // The owner file may not exist yet while another process is finalizing lock acquisition.
+        }
+        return false;
+    }
 }
 export function resolveStateDir(stateDir, cwd) {
     if (!stateDir) {

package/package.json

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

package/scripts/launch-fabric-client.mjs

@@ -126,9 +126,17 @@ async function readJson(filePath) {
   return JSON.parse(await readFile(filePath, "utf8"));
 }
 
-async function syncBuiltMod(instanceRoot, repoRoot, variantId) {
-  const artifactName = `mct-client-mod-${variantId.endsWith("-fabric") ? "fabric" : variantId.split("-").pop()}-${variantId.replace(/-fabric$|-forge$|-neoforge$/, "")}.jar`;
-  const sourceJar = path.join(repoRoot, "client-mod", "versions", variantId, "build", "libs", artifactName);
+function getLocalBuildArtifactPath(repoRoot, variant) {
+  const artifactName = `mct-client-mod-${variant.loader ?? "fabric"}-${variant.minecraftVersion}.jar`;
+  const gradleModule = variant.gradleModule || `version-${variant.minecraftVersion}`;
+  return {
+    artifactName,
+    sourceJar: path.join(repoRoot, "client-mod", gradleModule, "build", "libs", artifactName)
+  };
+}
+
+async function syncBuiltMod(instanceRoot, repoRoot, variant) {
+  const { artifactName, sourceJar } = getLocalBuildArtifactPath(repoRoot, variant);
   const targetDir = path.join(instanceRoot, "minecraft", "mods");
   const targetJar = path.join(targetDir, artifactName);
 
@@ -193,7 +201,7 @@ async function ensureAutomationOptions(gameDir, server) {
 }
 
 async function buildLaunchSpec(options) {
-  const repoRoot = process.cwd();
+  const repoRoot = path.resolve(__dirname, "..", "..");
   const defaultVariant = getDefaultVariant();
   const minecraftVersion = process.env.MCT_CLIENT_VERSION || options["minecraft-version"] || defaultVariant.minecraftVersion;
   const modVariantId = process.env.MCT_CLIENT_MOD_VARIANT || options["mod-variant"] || `${minecraftVersion}-fabric`;
@@ -206,7 +214,7 @@ async function buildLaunchSpec(options) {
   const nativesDir = options["natives-dir"] || path.join(instanceRoot, "natives");
   const gameDir = path.join(instanceRoot, "minecraft");
   const packMeta = await readJson(path.join(instanceRoot, "mmc-pack.json"));
-  await syncBuiltMod(instanceRoot, repoRoot, modVariantId);
+  await syncBuiltMod(instanceRoot, repoRoot, selectedVariant);
   const componentMetas = new Map();
   for (const component of packMeta.components) {
     const componentMetaPath = path.join(metaRoot, component.uid, `${component.version}.json`);