@kzheart_/mc-pilot 0.9.0 → 0.9.2

package/dist/download/client/ClientDownloader.js

@@ -7,7 +7,7 @@ import { CacheManager } from "../CacheManager.js";
 import { copyFileIfMissing, downloadFile } from "../DownloadUtils.js";
 import { detectJava } from "../JavaDetector.js";
 import { findVariantByVersionAndLoader, getDefaultVariant, getModArtifactFileName, loadModVariantCatalog } from "../ModVariantCatalog.js";
-import { prepareManagedFabricRuntime } from "./FabricRuntimeDownloader.js";
+import { prepareManagedClientRuntime } from "./FabricRuntimeDownloader.js";
 function getLaunchScriptPath() {
     const thisFile = fileURLToPath(import.meta.url);
     // dist/download/client/ClientDownloader.js -> scripts/launch-fabric-client.mjs
@@ -15,13 +15,27 @@ function getLaunchScriptPath() {
 }
 const GITHUB_RELEASE_BASE_URL = process.env.MCT_MOD_DOWNLOAD_BASE_URL || "https://github.com/kzheart/mc-pilot/releases/download";
 function ensureSupportedVariant(variant) {
-    if (variant.loader !== "fabric") {
+    if (variant.support !== "ready" && variant.support !== "configured") {
         throw new MctError({
-            code: "UNSUPPORTED_LOADER",
-            message: `Loader ${variant.loader} is not implemented yet`
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} is not buildable yet`,
+            details: {
+                support: variant.support,
+                validation: variant.validation
+            }
+        }, 4);
+    }
+    if (variant.loader === "fabric" && (!variant.fabricLoaderVersion || !variant.yarnMappings)) {
+        throw new MctError({
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} is not buildable yet`,
+            details: {
+                support: variant.support,
+                validation: variant.validation
+            }
         }, 4);
     }
-    if (!variant.fabricLoaderVersion || !variant.yarnMappings) {
+    if (variant.loader === "forge" && !variant.forgeVersion) {
         throw new MctError({
             code: "VARIANT_NOT_BUILDABLE",
             message: `Variant ${variant.id} is not buildable yet`,
@@ -31,6 +45,12 @@ function ensureSupportedVariant(variant) {
             }
         }, 4);
     }
+    if (variant.loader !== "fabric" && variant.loader !== "forge") {
+        throw new MctError({
+            code: "UNSUPPORTED_LOADER",
+            message: `Loader ${variant.loader} is not implemented yet`
+        }, 4);
+    }
 }
 export async function resolveArtifact(cwd, variant, cacheManager, fetchImpl = fetch) {
     const artifactFileName = getModArtifactFileName(variant);
@@ -51,7 +71,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 {
@@ -114,6 +134,12 @@ function resolveLaunchRuntimePaths(cwd, options) {
     };
 }
 function buildLaunchArgs(runtimePaths, variant) {
+    if (variant.loader !== "fabric") {
+        throw new MctError({
+            code: "INVALID_PARAMS",
+            message: `Custom runtime directories are not supported for ${variant.loader} clients yet`
+        }, 4);
+    }
     return [
         "--instance-dir",
         runtimePaths.instanceDir,
@@ -169,11 +195,13 @@ export async function downloadClientModToDir(cwd, targetDir, options, dependenci
     const cacheManager = dependencies.cacheManager ?? new CacheManager();
     const detectJavaImpl = dependencies.detectJavaImpl ?? detectJava;
     const fetchImpl = dependencies.fetchImpl ?? fetch;
-    const prepareManagedRuntimeImpl = dependencies.prepareManagedRuntimeImpl ?? prepareManagedFabricRuntime;
+    const prepareManagedRuntimeImpl = dependencies.prepareManagedRuntimeImpl ?? prepareManagedClientRuntime;
     const catalog = await loadModVariantCatalog();
     const variant = options.version
         ? findVariantByVersionAndLoader(catalog, options.version, loader)
-        : getDefaultVariant(catalog);
+        : loader === "fabric"
+            ? getDefaultVariant(catalog)
+            : undefined;
     if (!variant) {
         throw new MctError({
             code: "VARIANT_NOT_FOUND",

package/dist/download/client/FabricRuntimeDownloader.d.ts

@@ -12,3 +12,5 @@ export interface PrepareFabricRuntimeOptions {
     gameDir: string;
 }
 export declare function prepareManagedFabricRuntime(variant: ModVariant, runtimeOptions: PrepareFabricRuntimeOptions, dependencies?: PrepareFabricRuntimeDependencies): Promise<PreparedFabricRuntime>;
+export declare function prepareManagedForgeRuntime(variant: ModVariant, runtimeOptions: PrepareFabricRuntimeOptions, dependencies?: PrepareFabricRuntimeDependencies): Promise<PreparedFabricRuntime>;
+export declare function prepareManagedClientRuntime(variant: ModVariant, runtimeOptions: PrepareFabricRuntimeOptions, dependencies?: PrepareFabricRuntimeDependencies): Promise<PreparedFabricRuntime>;

package/dist/download/client/FabricRuntimeDownloader.js

@@ -2,7 +2,7 @@ import { access, mkdir, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { setTimeout as sleep } from "node:timers/promises";
 import { MinecraftFolder, Version } from "@xmcl/core";
-import { getVersionList, installDependencies, installFabric, installVersion } from "@xmcl/installer";
+import { getVersionList, installDependencies, installFabric, installForge, installVersion } from "@xmcl/installer";
 import { Agent, interceptors } from "undici";
 import { MctError } from "../../util/errors.js";
 import { applyArm64LwjglPatch } from "./Arm64LwjglPatcher.js";
@@ -42,19 +42,11 @@ async function fetchWithRetry(input, init, attempts = 4) {
     }
     throw lastError;
 }
-export async function prepareManagedFabricRuntime(variant, runtimeOptions, dependencies = {}) {
+async function prepareManagedRuntime(variant, runtimeOptions, dependencies, expectedVersionId, installLoader) {
     const fetchImpl = dependencies.fetchImpl ?? fetchWithRetry;
-    const loaderVersion = variant.fabricLoaderVersion;
-    if (!loaderVersion) {
-        throw new MctError({
-            code: "VARIANT_NOT_BUILDABLE",
-            message: `Variant ${variant.id} does not define a Fabric loader version`
-        }, 4);
-    }
     const { runtimeRootDir, gameDir } = runtimeOptions;
     await mkdir(runtimeRootDir, { recursive: true });
     await mkdir(gameDir, { recursive: true });
-    const expectedVersionId = `${variant.minecraftVersion}-fabric${loaderVersion}`;
     const readyMarker = path.join(runtimeRootDir, `.ready-${expectedVersionId}`);
     try {
         await access(readyMarker);
@@ -77,13 +69,7 @@ export async function prepareManagedFabricRuntime(variant, runtimeOptions, depen
         side: "client",
         dispatcher: DOWNLOAD_DISPATCHER
     });
-    const installedVersionId = await installFabric({
-        minecraftVersion: variant.minecraftVersion,
-        version: loaderVersion,
-        minecraft,
-        side: "client",
-        fetch: fetchImpl
-    });
+    const installedVersionId = await installLoader(minecraft, fetchImpl);
     const resolvedVersion = await Version.parse(minecraft, installedVersionId);
     await installDependencies(resolvedVersion, {
         side: "client",
@@ -99,3 +85,47 @@ export async function prepareManagedFabricRuntime(variant, runtimeOptions, depen
         versionId: installedVersionId
     };
 }
+export async function prepareManagedFabricRuntime(variant, runtimeOptions, dependencies = {}) {
+    const loaderVersion = variant.fabricLoaderVersion;
+    if (!loaderVersion) {
+        throw new MctError({
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} does not define a Fabric loader version`
+        }, 4);
+    }
+    return prepareManagedRuntime(variant, runtimeOptions, dependencies, `${variant.minecraftVersion}-fabric${loaderVersion}`, (minecraft, fetchImpl) => installFabric({
+        minecraftVersion: variant.minecraftVersion,
+        version: loaderVersion,
+        minecraft,
+        side: "client",
+        fetch: fetchImpl
+    }));
+}
+export async function prepareManagedForgeRuntime(variant, runtimeOptions, dependencies = {}) {
+    const forgeVersion = variant.forgeVersion;
+    if (!forgeVersion) {
+        throw new MctError({
+            code: "VARIANT_NOT_BUILDABLE",
+            message: `Variant ${variant.id} does not define a Forge version`
+        }, 4);
+    }
+    return prepareManagedRuntime(variant, runtimeOptions, dependencies, `${variant.minecraftVersion}-forge-${forgeVersion}`, (minecraft) => installForge({
+        mcversion: variant.minecraftVersion,
+        version: forgeVersion
+    }, minecraft, {
+        side: "client",
+        dispatcher: DOWNLOAD_DISPATCHER
+    }));
+}
+export async function prepareManagedClientRuntime(variant, runtimeOptions, dependencies = {}) {
+    if (variant.loader === "fabric") {
+        return prepareManagedFabricRuntime(variant, runtimeOptions, dependencies);
+    }
+    if (variant.loader === "forge") {
+        return prepareManagedForgeRuntime(variant, runtimeOptions, dependencies);
+    }
+    throw new MctError({
+        code: "UNSUPPORTED_LOADER",
+        message: `Loader ${variant.loader} is not implemented yet`
+    }, 4);
+}

package/dist/index.js

@@ -12,6 +12,7 @@ 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 { createImageCommand } from "./commands/image.js";
 import { createInputCommand } from "./commands/input.js";
 import { createInventoryCommand } from "./commands/inventory.js";
 import { createLookCommand } from "./commands/look.js";
@@ -83,6 +84,7 @@ export function buildProgram() {
     program.addCommand(createEntityCommand());
     program.addCommand(createInventoryCommand());
     program.addCommand(createGuiCommand());
+    program.addCommand(createImageCommand());
     program.addCommand(createScreenshotCommand());
     program.addCommand(createScreenCommand());
     program.addCommand(createHudCommand());

package/dist/instance/ClientInstanceManager.d.ts

@@ -7,6 +7,7 @@ export interface CreateClientOptions {
     wsPort?: number;
     account?: string;
     headless?: boolean;
+    mute?: boolean;
     launchArgs?: string[];
     env?: Record<string, string>;
 }
@@ -15,6 +16,7 @@ export interface LaunchClientOptions {
     account?: string;
     wsPort?: number;
     headless?: boolean;
+    mute?: boolean;
     force?: boolean;
 }
 export interface WaitReadyOptions {
@@ -67,4 +69,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,110 @@ 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,
+                mute: options.mute,
+                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;
+            const mute = options.mute ?? meta.mute;
+            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),
+                    ...(mute === undefined ? {} : { MCT_CLIENT_MUTE: String(mute) })
+                }
+            });
+            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 +336,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>;
 }