@kzheart_/mc-pilot 0.1.0

package/dist/download/client/FabricRuntimeDownloader.js

@@ -0,0 +1,91 @@
+import { mkdir } 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 { Agent, interceptors } from "undici";
+import { MctError } from "../../util/errors.js";
+import { applyArm64LwjglPatch } from "./Arm64LwjglPatcher.js";
+const DOWNLOAD_DISPATCHER = new Agent({
+    connect: {
+        timeout: 30_000
+    },
+    connections: 2
+}).compose(interceptors.retry({
+    maxRetries: 4,
+    minTimeout: 500,
+    maxTimeout: 5_000
+}), interceptors.redirect({
+    maxRedirections: 5
+}));
+async function fetchWithRetry(input, init, attempts = 4) {
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            const response = await fetch(input, init);
+            if (response.ok) {
+                return response;
+            }
+            if (response.status >= 500 && attempt < attempts) {
+                await sleep(attempt * 500);
+                continue;
+            }
+            return response;
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= attempts) {
+                throw error;
+            }
+            await sleep(attempt * 500);
+        }
+    }
+    throw lastError;
+}
+export async function prepareManagedFabricRuntime(variant, clientRootDir, dependencies = {}) {
+    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 = path.join(clientRootDir, "runtime");
+    const gameDir = path.join(clientRootDir, "minecraft");
+    await mkdir(runtimeRootDir, { recursive: true });
+    await mkdir(gameDir, { recursive: true });
+    const minecraft = new MinecraftFolder(runtimeRootDir);
+    const versionList = await getVersionList({ fetch: fetchImpl });
+    const versionMeta = versionList.versions.find((entry) => entry.id === variant.minecraftVersion);
+    if (!versionMeta) {
+        throw new MctError({
+            code: "UNSUPPORTED_VERSION",
+            message: `Minecraft ${variant.minecraftVersion} metadata was not found`
+        }, 4);
+    }
+    await installVersion(versionMeta, minecraft, {
+        side: "client",
+        dispatcher: DOWNLOAD_DISPATCHER
+    });
+    const versionId = await installFabric({
+        minecraftVersion: variant.minecraftVersion,
+        version: loaderVersion,
+        minecraft,
+        side: "client",
+        fetch: fetchImpl
+    });
+    const resolvedVersion = await Version.parse(minecraft, versionId);
+    await installDependencies(resolvedVersion, {
+        side: "client",
+        dispatcher: DOWNLOAD_DISPATCHER,
+        assetsDownloadConcurrency: 2,
+        librariesDownloadConcurrency: 2
+    });
+    await applyArm64LwjglPatch(runtimeRootDir, versionId, { fetchImpl });
+    return {
+        runtimeRootDir,
+        gameDir,
+        versionId
+    };
+}

package/dist/download/server/ServerDownloader.d.ts

@@ -0,0 +1,51 @@
+import type { CommandContext } from "../../util/context.js";
+import { CacheManager } from "../CacheManager.js";
+import { type ServerType } from "../VersionMatrix.js";
+type ExecFileLike = (file: string, args: string[], options: {
+    cwd?: string;
+    maxBuffer?: number;
+}) => Promise<{
+    stdout: string;
+    stderr: string;
+}>;
+export interface DownloadServerOptions {
+    type?: ServerType;
+    version?: string;
+    build?: string;
+    dir?: string;
+    fixtures?: string;
+}
+export interface DownloadServerDependencies {
+    fetchImpl?: typeof fetch;
+    cacheManager?: CacheManager;
+    execFileImpl?: ExecFileLike;
+}
+export declare function resolveServerDownloadSpec(options: DownloadServerOptions): {
+    type: "vanilla";
+    version: string;
+    build: string;
+    fileName: string;
+    downloadUrl: string;
+} | {
+    type: "spigot";
+    version: string;
+    build: string;
+    fileName: string;
+    downloadUrl: string;
+} | {
+    type: "paper" | "purpur";
+    version: string;
+    build: string;
+    fileName: string;
+    downloadUrl: string;
+};
+export declare function downloadServerJar(context: CommandContext, options: DownloadServerOptions, dependencies?: DownloadServerDependencies): Promise<{
+    downloaded: boolean;
+    type: "paper" | "purpur" | "spigot" | "vanilla";
+    version: string;
+    build: string;
+    cachePath: string;
+    jar: string;
+    dir: string;
+}>;
+export {};

package/dist/download/server/ServerDownloader.js

@@ -0,0 +1,196 @@
+import { execFile } from "node:child_process";
+import { access, mkdir } from "node:fs/promises";
+import path from "node:path";
+import { setTimeout as sleep } from "node:timers/promises";
+import { promisify } from "node:util";
+import { MctError } from "../../util/errors.js";
+import { loadConfig, writeConfig } from "../../util/config.js";
+import { CacheManager } from "../CacheManager.js";
+import { copyFileIfMissing, downloadFile } from "../DownloadUtils.js";
+import { getMinecraftSupport } from "../VersionMatrix.js";
+const SERVER_DOWNLOAD_BASE_URLS = {
+    paper: process.env.MCT_PAPER_API_BASE_URL || "https://api.papermc.io/v2/projects",
+    purpur: process.env.MCT_PURPUR_API_BASE_URL || "https://api.purpurmc.org/v2"
+};
+const MOJANG_VERSION_MANIFEST_URL = process.env.MCT_MOJANG_VERSION_MANIFEST_URL || "https://launchermeta.mojang.com/mc/game/version_manifest.json";
+const SPIGOT_BUILD_TOOLS_URL = process.env.MCT_SPIGOT_BUILDTOOLS_URL ||
+    "https://hub.spigotmc.org/jenkins/job/BuildTools/lastSuccessfulBuild/artifact/target/BuildTools.jar";
+const execFileAsync = promisify(execFile);
+function resolveDownloadUrl(type, version, build) {
+    if (type === "paper") {
+        return `${SERVER_DOWNLOAD_BASE_URLS.paper}/paper/versions/${version}/builds/${build}/downloads/paper-${version}-${build}.jar`;
+    }
+    return `${SERVER_DOWNLOAD_BASE_URLS.purpur}/purpur/${version}/${build}/download`;
+}
+async function fetchJsonWithRetry(url, fetchImpl, attempts = 4) {
+    let lastError;
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+        try {
+            const response = await fetchImpl(url);
+            if (!response.ok) {
+                throw new Error(`HTTP ${response.status} ${response.statusText}`.trim());
+            }
+            return (await response.json());
+        }
+        catch (error) {
+            lastError = error;
+            if (attempt >= attempts) {
+                throw error;
+            }
+            await sleep(attempt * 500);
+        }
+    }
+    throw lastError;
+}
+async function resolveVanillaDownloadSpec(version, fetchImpl) {
+    const manifest = await fetchJsonWithRetry(MOJANG_VERSION_MANIFEST_URL, fetchImpl);
+    const versionEntry = manifest.versions.find((entry) => entry.id === version);
+    if (!versionEntry) {
+        throw new MctError({
+            code: "UNSUPPORTED_VERSION",
+            message: `Unsupported vanilla version ${version}`
+        }, 4);
+    }
+    const versionJson = await fetchJsonWithRetry(versionEntry.url, fetchImpl);
+    const serverDownload = versionJson.downloads?.server;
+    if (!serverDownload?.url) {
+        throw new MctError({
+            code: "UNSUPPORTED_VERSION",
+            message: `Vanilla server jar is not available for ${version}`
+        }, 4);
+    }
+    return {
+        type: "vanilla",
+        version,
+        build: "release",
+        fileName: `vanilla-${version}.jar`,
+        downloadUrl: serverDownload.url
+    };
+}
+async function buildSpigotServerJar(version, cacheManager, fetchImpl, execFileImpl) {
+    const buildToolsJarPath = cacheManager.getServerJarPath("spigot", "buildtools", "latest");
+    const cachePath = cacheManager.getServerJarPath("spigot", version, "buildtools");
+    const buildDir = path.join(cacheManager.getRootDir(), "server", "spigot", "build", version);
+    const builtJarPath = path.join(buildDir, `spigot-${version}.jar`);
+    try {
+        await access(cachePath);
+        return {
+            cachePath,
+            build: "buildtools"
+        };
+    }
+    catch { }
+    try {
+        await access(buildToolsJarPath);
+    }
+    catch {
+        await downloadFile(SPIGOT_BUILD_TOOLS_URL, buildToolsJarPath, fetchImpl);
+    }
+    await mkdir(buildDir, { recursive: true });
+    await execFileImpl("java", ["-jar", buildToolsJarPath, "--rev", version, "--compile", "SPIGOT", "--disable-certificate-check", "--output-dir", "."], {
+        cwd: buildDir,
+        maxBuffer: 32 * 1024 * 1024
+    });
+    try {
+        await access(builtJarPath);
+    }
+    catch {
+        throw new MctError({
+            code: "DOWNLOAD_FAILED",
+            message: `BuildTools did not produce spigot-${version}.jar`,
+            details: {
+                buildDir
+            }
+        }, 2);
+    }
+    await copyFileIfMissing(builtJarPath, cachePath);
+    return {
+        cachePath,
+        build: "buildtools"
+    };
+}
+export function resolveServerDownloadSpec(options) {
+    const type = options.type ?? "paper";
+    const resolvedVersion = options.version ?? "1.21.4";
+    const versionEntry = getMinecraftSupport(resolvedVersion);
+    if (!versionEntry) {
+        throw new MctError({
+            code: "UNSUPPORTED_VERSION",
+            message: `Unsupported ${type} version ${options.version ?? ""}`.trim()
+        }, 4);
+    }
+    if (type === "vanilla") {
+        return {
+            type,
+            version: resolvedVersion,
+            build: "release",
+            fileName: `vanilla-${resolvedVersion}.jar`,
+            downloadUrl: ""
+        };
+    }
+    if (type === "spigot") {
+        return {
+            type,
+            version: resolvedVersion,
+            build: "buildtools",
+            fileName: `spigot-${resolvedVersion}.jar`,
+            downloadUrl: SPIGOT_BUILD_TOOLS_URL
+        };
+    }
+    const resolvedBuild = options.build ?? versionEntry.servers[type].latestBuild?.toString();
+    if (!resolvedBuild) {
+        throw new MctError({
+            code: "INVALID_PARAMS",
+            message: `${type} ${resolvedVersion} requires an explicit build`
+        }, 4);
+    }
+    return {
+        type,
+        version: resolvedVersion,
+        build: resolvedBuild,
+        fileName: `${type}-${resolvedVersion}-${resolvedBuild}.jar`,
+        downloadUrl: resolveDownloadUrl(type, resolvedVersion, resolvedBuild)
+    };
+}
+export async function downloadServerJar(context, options, dependencies = {}) {
+    const cacheManager = dependencies.cacheManager ?? new CacheManager();
+    const fetchImpl = dependencies.fetchImpl ?? fetch;
+    const execFileImpl = (dependencies.execFileImpl ?? execFileAsync);
+    const initialSpec = resolveServerDownloadSpec(options);
+    const spec = initialSpec.type === "vanilla"
+        ? await resolveVanillaDownloadSpec(initialSpec.version, fetchImpl)
+        : initialSpec;
+    const cachePath = spec.type === "spigot"
+        ? (await buildSpigotServerJar(spec.version, cacheManager, fetchImpl, execFileImpl)).cachePath
+        : cacheManager.getServerJarPath(spec.type, spec.version, spec.build);
+    if (spec.type !== "spigot") {
+        try {
+            await access(cachePath);
+        }
+        catch {
+            await downloadFile(spec.downloadUrl, cachePath, fetchImpl);
+        }
+    }
+    const targetDir = path.resolve(context.cwd, options.dir ?? context.config.server.dir);
+    const targetJarPath = path.join(targetDir, spec.fileName);
+    await copyFileIfMissing(cachePath, targetJarPath);
+    if (options.fixtures) {
+        const fixturesPath = path.resolve(context.cwd, options.fixtures);
+        const pluginsDir = path.join(targetDir, "plugins");
+        await mkdir(pluginsDir, { recursive: true });
+        await copyFileIfMissing(fixturesPath, path.join(pluginsDir, path.basename(fixturesPath)));
+    }
+    const latestConfig = await loadConfig(context.configPath, context.cwd);
+    latestConfig.server.jar = path.relative(context.cwd, targetJarPath);
+    latestConfig.server.dir = path.relative(context.cwd, targetDir) || ".";
+    await writeConfig(context.configPath, context.cwd, latestConfig);
+    return {
+        downloaded: true,
+        type: spec.type,
+        version: spec.version,
+        build: spec.build,
+        cachePath,
+        jar: targetJarPath,
+        dir: targetDir
+    };
+}

package/dist/download/types.d.ts

@@ -0,0 +1,37 @@
+export type LoaderType = "fabric" | "forge" | "neoforge";
+export type ServerType = "paper" | "purpur" | "spigot" | "vanilla";
+export type SupportLevel = "ready" | "configured" | "planned" | "unsupported";
+export type ValidationLevel = "verified" | "limited" | "planned";
+export interface ModVariant {
+    id: string;
+    minecraftVersion: string;
+    loader: LoaderType;
+    support: SupportLevel;
+    validation: ValidationLevel;
+    modVersion?: string;
+    fabricLoaderVersion?: string;
+    yarnMappings?: string;
+    forgeVersion?: string;
+    neoforgeVersion?: string;
+    javaVersion?: number;
+    notes?: string;
+}
+export interface ModVariantCatalog {
+    defaultVariant: string;
+    variants: ModVariant[];
+}
+export interface ServerVersionSupport {
+    type: ServerType;
+    version: string;
+    support: Exclude<SupportLevel, "unsupported">;
+    notes?: string;
+}
+export interface ClientVersionSupport {
+    version: string;
+    loader: LoaderType;
+    support: SupportLevel;
+    validation: ValidationLevel;
+    loaderVersion?: string;
+    modVersion?: string;
+    notes?: string;
+}

package/dist/download/types.js

@@ -0,0 +1 @@
+export {};

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,89 @@
+import { Command } from "commander";
+import { pathToFileURL } from "node:url";
+import { createBlockCommand } from "./commands/block.js";
+import { createBookCommand } from "./commands/book.js";
+import { createClientCommand } from "./commands/client.js";
+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 { createGuiCommand } from "./commands/gui.js";
+import { createHudCommand } from "./commands/hud.js";
+import { createInputCommand } from "./commands/input.js";
+import { createInventoryCommand } from "./commands/inventory.js";
+import { createLookCommand } from "./commands/look.js";
+import { createMoveCommand } from "./commands/move.js";
+import { createPositionCommand } from "./commands/position.js";
+import { createResourcepackCommand } from "./commands/resourcepack.js";
+import { createRotationCommand } from "./commands/rotation.js";
+import { createScreenCommand } from "./commands/screen.js";
+import { createScreenshotCommand } from "./commands/screenshot.js";
+import { createServerCommand } from "./commands/server.js";
+import { createSignCommand } from "./commands/sign.js";
+import { createStatusCommand } from "./commands/status.js";
+import { createWaitCommand } from "./commands/wait.js";
+import { attachGlobalOptions, wrapCommand } from "./util/command.js";
+export function buildProgram() {
+    const program = new Command();
+    program
+        .name("mct")
+        .description("MC Pilot – Minecraft plugin/mod automated testing CLI\n\n" +
+        "Control a real Minecraft client via CLI to simulate player actions and verify plugin behavior.\n" +
+        "All commands output JSON by default. Use --human for human-readable output.\n\n" +
+        "Quick start:\n" +
+        "  mct server download --type paper --version 1.20.4\n" +
+        "  mct client download --version 1.20.4\n" +
+        "  mct server start --eula && mct server wait-ready\n" +
+        "  mct client launch default && mct client wait-ready default\n" +
+        "  mct chat command \"gamemode creative\"\n" +
+        "  mct move to 100 64 100\n" +
+        "  mct screenshot --output ./test.png\n\n" +
+        "Multi-client:\n" +
+        "  mct client download --version 1.20.4 --name p1 --ws-port 25560\n" +
+        "  mct client download --version 1.20.4 --name p2 --ws-port 25561\n" +
+        "  mct client launch p1 && mct client launch p2\n" +
+        "  mct --client p1 chat send \"Hello from p1\"\n" +
+        "  mct --client p2 chat send \"Hello from p2\"")
+        .version("0.1.0", "--cli-version", "Show CLI version");
+    attachGlobalOptions(program);
+    program
+        .command("config-show")
+        .description("Show current config and state directory")
+        .action(wrapCommand(async (context) => {
+        return {
+            cwd: context.cwd,
+            stateDir: context.state.getRootDir(),
+            config: context.config
+        };
+    }));
+    program.addCommand(createServerCommand());
+    program.addCommand(createClientCommand());
+    program.addCommand(createChatCommand());
+    program.addCommand(createInputCommand());
+    program.addCommand(createMoveCommand());
+    program.addCommand(createLookCommand());
+    program.addCommand(createPositionCommand());
+    program.addCommand(createRotationCommand());
+    program.addCommand(createBlockCommand());
+    program.addCommand(createEntityCommand());
+    program.addCommand(createInventoryCommand());
+    program.addCommand(createGuiCommand());
+    program.addCommand(createScreenshotCommand());
+    program.addCommand(createScreenCommand());
+    program.addCommand(createHudCommand());
+    program.addCommand(createStatusCommand());
+    program.addCommand(createSignCommand());
+    program.addCommand(createBookCommand());
+    program.addCommand(createResourcepackCommand());
+    program.addCommand(createCombatCommand());
+    program.addCommand(createCraftCommand());
+    program.addCommand(createAnvilCommand());
+    program.addCommand(createEnchantCommand());
+    program.addCommand(createTradeCommand());
+    program.addCommand(createWaitCommand());
+    return program;
+}
+const program = buildProgram();
+if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+    program.parseAsync(process.argv);
+}

package/dist/server/ServerManager.d.ts

@@ -0,0 +1,63 @@
+import type { CommandContext } from "../util/context.js";
+export interface ServerRuntimeState {
+    pid: number;
+    jar: string;
+    dir: string;
+    port: number;
+    startedAt: string;
+    logPath: string;
+}
+export interface StartServerOptions {
+    jar?: string;
+    dir?: string;
+    port?: number;
+    eula?: boolean;
+}
+export declare class ServerManager {
+    private readonly context;
+    constructor(context: CommandContext);
+    start(options: StartServerOptions): Promise<{
+        pid: number;
+        jar: string;
+        dir: string;
+        port: number;
+        startedAt: string;
+        logPath: string;
+        running: boolean;
+    }>;
+    stop(): Promise<{
+        running: boolean;
+        stopped: boolean;
+        pid?: undefined;
+    } | {
+        running: boolean;
+        stopped: boolean;
+        pid: number;
+    }>;
+    status(): Promise<{
+        running: boolean;
+    } | {
+        pid: number;
+        jar: string;
+        dir: string;
+        port: number;
+        startedAt: string;
+        logPath: string;
+        running: boolean;
+        stale: boolean;
+    } | {
+        pid: number;
+        jar: string;
+        dir: string;
+        port: number;
+        startedAt: string;
+        logPath: string;
+        running: boolean;
+    }>;
+    waitReady(timeoutSeconds: number): Promise<{
+        reachable: boolean;
+        host: string;
+        port: number;
+    }>;
+    getState(): Promise<ServerRuntimeState | null>;
+}

package/dist/server/ServerManager.js

@@ -0,0 +1,114 @@
+import { mkdirSync, openSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import path from "node:path";
+import { MctError } from "../util/errors.js";
+import { waitForTcpPort } from "../util/net.js";
+import { isProcessRunning, killProcessTree } from "../util/process.js";
+const SERVER_STATE_FILE = "server.json";
+export class ServerManager {
+    context;
+    constructor(context) {
+        this.context = context;
+    }
+    async start(options) {
+        const existing = await this.getState();
+        if (existing && isProcessRunning(existing.pid)) {
+            throw new MctError({
+                code: "SERVER_ALREADY_RUNNING",
+                message: "Server is already running",
+                details: existing
+            }, 5);
+        }
+        const jar = options.jar ?? this.context.config.server.jar;
+        if (!jar) {
+            throw new MctError({
+                code: "INVALID_PARAMS",
+                message: "Server jar is required"
+            }, 4);
+        }
+        const dir = path.resolve(this.context.cwd, options.dir ?? this.context.config.server.dir);
+        const port = options.port ?? this.context.config.server.port;
+        mkdirSync(dir, { recursive: true });
+        mkdirSync(path.join(this.context.state.getRootDir(), "logs"), { recursive: true });
+        if (options.eula) {
+            writeFileSync(path.join(dir, "eula.txt"), "eula=true\n", "utf8");
+        }
+        const logPath = path.join(this.context.state.getRootDir(), "logs", "paper-server.log");
+        const stdout = openSync(logPath, "a");
+        const child = spawn("java", [...this.context.config.server.jvmArgs, "-jar", path.resolve(this.context.cwd, jar), "nogui"], {
+            cwd: dir,
+            detached: true,
+            stdio: ["ignore", stdout, stdout],
+            env: {
+                ...process.env,
+                MCT_SERVER_PORT: String(port)
+            }
+        });
+        child.unref();
+        const state = {
+            pid: child.pid ?? 0,
+            jar: path.resolve(this.context.cwd, jar),
+            dir,
+            port,
+            startedAt: new Date().toISOString(),
+            logPath
+        };
+        await this.context.state.writeJson(SERVER_STATE_FILE, state);
+        return {
+            running: true,
+            ...state
+        };
+    }
+    async stop() {
+        const state = await this.getState();
+        if (!state) {
+            return {
+                running: false,
+                stopped: false
+            };
+        }
+        if (isProcessRunning(state.pid)) {
+            killProcessTree(state.pid);
+        }
+        await this.context.state.remove(SERVER_STATE_FILE);
+        return {
+            running: false,
+            stopped: true,
+            pid: state.pid
+        };
+    }
+    async status() {
+        const state = await this.getState();
+        if (!state) {
+            return {
+                running: false
+            };
+        }
+        const running = isProcessRunning(state.pid);
+        if (!running) {
+            await this.context.state.remove(SERVER_STATE_FILE);
+            return {
+                running: false,
+                stale: true,
+                ...state
+            };
+        }
+        return {
+            running: true,
+            ...state
+        };
+    }
+    async waitReady(timeoutSeconds) {
+        const state = await this.getState();
+        if (!state) {
+            throw new MctError({
+                code: "SERVER_NOT_RUNNING",
+                message: "Server is not running"
+            }, 5);
+        }
+        return waitForTcpPort("127.0.0.1", state.port, timeoutSeconds);
+    }
+    async getState() {
+        return this.context.state.readJson(SERVER_STATE_FILE, null);
+    }
+}

package/dist/util/command.d.ts

@@ -0,0 +1,10 @@
+import type { Command } from "commander";
+import { createCommandContext, type GlobalOptions } from "./context.js";
+export type CommandAction<TOptions = Record<string, unknown>> = (context: Awaited<ReturnType<typeof createCommandContext>>, payload: {
+    args: string[];
+    options: TOptions;
+    command: Command;
+    globalOptions: GlobalOptions;
+}) => Promise<unknown>;
+export declare function attachGlobalOptions(command: Command): Command;
+export declare function wrapCommand<TOptions = Record<string, unknown>>(action: CommandAction<TOptions>): (this: Command, ...input: unknown[]) => Promise<void>;