@kzheart_/mc-pilot 0.1.0

package/dist/util/command.js

@@ -0,0 +1,35 @@
+import process from "node:process";
+import { createCommandContext } from "./context.js";
+import { normalizeError } from "./errors.js";
+import { printError, printSuccess } from "./output.js";
+export function attachGlobalOptions(command) {
+    return command
+        .option("--human", "Human-readable output (default: JSON)")
+        .option("--config <path>", "Config file path (default: ./mct.config.json)")
+        .option("--state-dir <path>", "State directory (default: ./.mct-state/)")
+        .option("--client <name>", "Target client name (required when multiple clients are running)");
+}
+export function wrapCommand(action) {
+    return async function wrappedCommand(...input) {
+        const command = input.at(-1);
+        const options = input.at(-2);
+        const args = input.slice(0, -2).map((value) => String(value));
+        const globalOptions = command.optsWithGlobals();
+        try {
+            const context = await createCommandContext(globalOptions);
+            const result = await action(context, {
+                args,
+                options,
+                command,
+                globalOptions
+            });
+            printSuccess(result, context.outputMode);
+        }
+        catch (error) {
+            const normalized = normalizeError(error);
+            const mode = globalOptions.human ? "human" : "json";
+            printError(normalized, mode);
+            process.exitCode = normalized.exitCode;
+        }
+    };
+}

package/dist/util/config.d.ts

@@ -0,0 +1,30 @@
+export declare const DEFAULT_WS_PORT_BASE = 25580;
+export interface MctConfig {
+    server: {
+        jar?: string;
+        dir: string;
+        port: number;
+        jvmArgs: string[];
+    };
+    clients: Record<string, {
+        version?: string;
+        account?: string;
+        wsPort?: number;
+        server?: string;
+        headless?: boolean;
+        launchCommand?: string[];
+        workingDir?: string;
+        env?: Record<string, string>;
+    }>;
+    screenshot: {
+        outputDir: string;
+    };
+    timeout: {
+        serverReady: number;
+        clientReady: number;
+        default: number;
+    };
+}
+export declare function resolveConfigPath(configPath: string | undefined, cwd: string): string;
+export declare function loadConfig(configPath: string | undefined, cwd: string): Promise<MctConfig>;
+export declare function writeConfig(configPath: string | undefined, cwd: string, config: MctConfig): Promise<void>;

package/dist/util/config.js

@@ -0,0 +1,59 @@
+import { access, mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+export const DEFAULT_WS_PORT_BASE = 25580;
+function createDefaultConfig() {
+    return {
+        server: {
+            dir: "./server",
+            port: 25565,
+            jvmArgs: []
+        },
+        clients: {},
+        screenshot: {
+            outputDir: "./screenshots"
+        },
+        timeout: {
+            serverReady: 120,
+            clientReady: 60,
+            default: 10
+        }
+    };
+}
+export function resolveConfigPath(configPath, cwd) {
+    if (!configPath) {
+        return path.join(cwd, "mct.config.json");
+    }
+    return path.isAbsolute(configPath) ? configPath : path.resolve(cwd, configPath);
+}
+export async function loadConfig(configPath, cwd) {
+    const resolvedPath = resolveConfigPath(configPath, cwd);
+    const defaultConfig = createDefaultConfig();
+    try {
+        await access(resolvedPath);
+    }
+    catch {
+        return defaultConfig;
+    }
+    const raw = await readFile(resolvedPath, "utf8");
+    const parsed = JSON.parse(raw);
+    return {
+        server: {
+            ...defaultConfig.server,
+            ...parsed.server
+        },
+        clients: parsed.clients ?? defaultConfig.clients,
+        screenshot: {
+            ...defaultConfig.screenshot,
+            ...parsed.screenshot
+        },
+        timeout: {
+            ...defaultConfig.timeout,
+            ...parsed.timeout
+        }
+    };
+}
+export async function writeConfig(configPath, cwd, config) {
+    const resolvedPath = resolveConfigPath(configPath, cwd);
+    await mkdir(path.dirname(resolvedPath), { recursive: true });
+    await writeFile(resolvedPath, `${JSON.stringify(config, null, 2)}\n`, "utf8");
+}

package/dist/util/context.d.ts

@@ -0,0 +1,17 @@
+import { type MctConfig } from "./config.js";
+import { type OutputMode } from "./output.js";
+import { StateStore } from "./state.js";
+export interface GlobalOptions {
+    human?: boolean;
+    config?: string;
+    stateDir?: string;
+    client?: string;
+}
+export interface CommandContext {
+    cwd: string;
+    configPath: string;
+    config: MctConfig;
+    state: StateStore;
+    outputMode: OutputMode;
+}
+export declare function createCommandContext(options: GlobalOptions): Promise<CommandContext>;

package/dist/util/context.js

@@ -0,0 +1,16 @@
+import process from "node:process";
+import { loadConfig, resolveConfigPath } from "./config.js";
+import { resolveStateDir, StateStore } from "./state.js";
+export async function createCommandContext(options) {
+    const cwd = process.cwd();
+    const configPath = resolveConfigPath(options.config, cwd);
+    const config = await loadConfig(configPath, cwd);
+    const state = new StateStore(resolveStateDir(options.stateDir, cwd));
+    return {
+        cwd,
+        configPath,
+        config,
+        state,
+        outputMode: options.human ? "human" : "json"
+    };
+}

package/dist/util/errors.d.ts

@@ -0,0 +1,20 @@
+export interface ErrorPayload {
+    code: string;
+    message: string;
+    details?: unknown;
+}
+export declare class MctError extends Error {
+    readonly code: string;
+    readonly exitCode: number;
+    readonly details?: unknown;
+    constructor(payload: ErrorPayload, exitCode?: number);
+    toJSON(): {
+        success: boolean;
+        error: {
+            code: string;
+            message: string;
+            details: {};
+        };
+    };
+}
+export declare function normalizeError(error: unknown): MctError;

package/dist/util/errors.js

@@ -0,0 +1,37 @@
+export class MctError extends Error {
+    code;
+    exitCode;
+    details;
+    constructor(payload, exitCode = 1) {
+        super(payload.message);
+        this.name = "MctError";
+        this.code = payload.code;
+        this.exitCode = exitCode;
+        this.details = payload.details;
+    }
+    toJSON() {
+        return {
+            success: false,
+            error: {
+                code: this.code,
+                message: this.message,
+                details: this.details ?? {}
+            }
+        };
+    }
+}
+export function normalizeError(error) {
+    if (error instanceof MctError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new MctError({
+            code: "INTERNAL_ERROR",
+            message: error.message
+        }, 1);
+    }
+    return new MctError({
+        code: "INTERNAL_ERROR",
+        message: "Unknown error"
+    }, 1);
+}

package/dist/util/net.d.ts

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

package/dist/util/net.js

@@ -0,0 +1,35 @@
+import net from "node:net";
+import { MctError } from "./errors.js";
+function wait(ms) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, ms);
+    });
+}
+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) {
+            return {
+                reachable: true,
+                host,
+                port
+            };
+        }
+        await wait(500);
+    }
+    throw new MctError({
+        code: "TIMEOUT",
+        message: `Timed out waiting for ${host}:${port}`
+    }, 2);
+}

package/dist/util/output.d.ts

@@ -0,0 +1,4 @@
+import type { MctError } from "./errors.js";
+export type OutputMode = "json" | "human";
+export declare function printSuccess(data: unknown, mode: OutputMode): void;
+export declare function printError(error: MctError, mode: OutputMode): void;

package/dist/util/output.js

@@ -0,0 +1,23 @@
+import process from "node:process";
+import { inspect } from "node:util";
+export function printSuccess(data, mode) {
+    if (mode === "human") {
+        if (typeof data === "string") {
+            process.stdout.write(`${data}\n`);
+            return;
+        }
+        process.stdout.write(`${inspect(data, { colors: true, depth: null })}\n`);
+        return;
+    }
+    process.stdout.write(`${JSON.stringify({ success: true, data }, null, 2)}\n`);
+}
+export function printError(error, mode) {
+    if (mode === "human") {
+        process.stderr.write(`[${error.code}] ${error.message}\n`);
+        if (error.details && typeof error.details === "object" && Object.keys(error.details).length > 0) {
+            process.stderr.write(`${inspect(error.details, { colors: true, depth: null })}\n`);
+        }
+        return;
+    }
+    process.stderr.write(`${JSON.stringify(error.toJSON(), null, 2)}\n`);
+}

package/dist/util/process.d.ts

@@ -0,0 +1,3 @@
+export declare function isProcessRunning(pid: number): boolean;
+export declare function killProcessTree(pid: number, signal?: NodeJS.Signals): void;
+export declare function getListeningPids(port: number): number[];

package/dist/util/process.js

@@ -0,0 +1,32 @@
+import { spawnSync } from "node:child_process";
+import process from "node:process";
+export function isProcessRunning(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function killProcessTree(pid, signal = "SIGTERM") {
+    try {
+        process.kill(-pid, signal);
+        return;
+    }
+    catch {
+        process.kill(pid, signal);
+    }
+}
+export function getListeningPids(port) {
+    const result = spawnSync("lsof", ["-nP", "-t", `-iTCP:${port}`, "-sTCP:LISTEN"], {
+        encoding: "utf8"
+    });
+    if (result.status !== 0 || !result.stdout) {
+        return [];
+    }
+    return result.stdout
+        .split(/\s+/)
+        .map((entry) => Number(entry.trim()))
+        .filter((entry) => Number.isInteger(entry) && entry > 0);
+}

package/dist/util/state.d.ts

@@ -0,0 +1,10 @@
+export declare class StateStore {
+    private readonly rootDir;
+    constructor(rootDir: string);
+    getRootDir(): string;
+    ensure(): Promise<void>;
+    readJson<T>(name: string, fallback: T): Promise<T>;
+    writeJson(name: string, value: unknown): Promise<void>;
+    remove(name: string): Promise<void>;
+}
+export declare function resolveStateDir(stateDir: string | undefined, cwd: string): string;

package/dist/util/state.js

@@ -0,0 +1,40 @@
+import { mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import path from "node:path";
+export class StateStore {
+    rootDir;
+    constructor(rootDir) {
+        this.rootDir = rootDir;
+    }
+    getRootDir() {
+        return this.rootDir;
+    }
+    async ensure() {
+        await mkdir(this.rootDir, { recursive: true });
+    }
+    async readJson(name, fallback) {
+        await this.ensure();
+        const target = path.join(this.rootDir, name);
+        try {
+            const raw = await readFile(target, "utf8");
+            return JSON.parse(raw);
+        }
+        catch {
+            return fallback;
+        }
+    }
+    async writeJson(name, value) {
+        await this.ensure();
+        const target = path.join(this.rootDir, name);
+        const content = JSON.stringify(value, null, 2);
+        await writeFile(target, `${content}\n`, "utf8");
+    }
+    async remove(name) {
+        await rm(path.join(this.rootDir, name), { force: true });
+    }
+}
+export function resolveStateDir(stateDir, cwd) {
+    if (!stateDir) {
+        return path.join(cwd, ".mct-state");
+    }
+    return path.isAbsolute(stateDir) ? stateDir : path.resolve(cwd, stateDir);
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+  "name": "@kzheart_/mc-pilot",
+  "version": "0.1.0",
+  "description": "Minecraft plugin/mod automated testing CLI – control a real Minecraft client to simulate player actions",
+  "type": "module",
+  "bin": {
+    "mct": "./bin/mct"
+  },
+  "files": [
+    "bin/",
+    "dist/",
+    "data/",
+    "!dist/**/*.test.js",
+    "!dist/**/*.test.d.ts",
+    "!dist/**/*.e2e.test.js",
+    "!dist/**/*.e2e.test.d.ts"
+  ],
+  "keywords": [
+    "minecraft",
+    "testing",
+    "automation",
+    "fabric",
+    "plugin",
+    "mod",
+    "cli"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/kzheart/mc-pilot.git",
+    "directory": "cli"
+  },
+  "license": "MIT",
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "tsc -p tsconfig.json && node --test dist/*.test.js dist/**/*.test.js",
+    "test:e2e": "tsc -p tsconfig.json && node --test dist/*.e2e.test.js dist/**/*.e2e.test.js"
+  },
+  "dependencies": {
+    "@xmcl/core": "^2.15.1",
+    "@xmcl/file-transfer": "^2.0.3",
+    "@xmcl/installer": "^6.1.2",
+    "commander": "^14.0.1",
+    "ws": "^8.19.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.5.2",
+    "@types/ws": "^8.18.1",
+    "tsx": "^4.20.5",
+    "typescript": "^5.9.2"
+  }
+}