@kzheart_/mc-pilot 0.6.0 → 0.8.0

package/dist/commands/chat.js

@@ -2,27 +2,68 @@ import { Command } from "commander";
 import { ServerInstanceManager } from "../instance/ServerInstanceManager.js";
 import { MctError } from "../util/errors.js";
 import { wrapCommand } from "../util/command.js";
-import { createRequestAction, sendClientRequest, withTransportTimeoutBuffer } from "./request-helpers.js";
+import { createRequestAction, resolvePreferredClientName, sendClientRequest, withTransportTimeoutBuffer } from "./request-helpers.js";
+function normalizeChatCommand(text) {
+    const command = text?.trim();
+    if (!command) {
+        throw new MctError({ code: "INVALID_PARAMS", message: "Command is required" }, 4);
+    }
+    return command;
+}
+async function executeServerCommand(context, serverName, command) {
+    const manager = new ServerInstanceManager(context.globalState, context.projectName);
+    const result = await manager.exec(serverName, command);
+    return {
+        ...result,
+        warning: "Commands that require a player sender should use --via client."
+    };
+}
 export function createChatCommand() {
     const command = new Command("chat").description("Chat and server commands");
     command
         .command("send")
-        .description("Send a chat message")
+        .description("Send a chat message. Slash-prefixed text is routed as a player command unless --literal is set.")
         .argument("<message>", "Message text")
-        .action(createRequestAction("chat.send", ({ args }) => ({ message: args[0] })));
+        .option("--literal", "Send slash-prefixed text as plain chat instead of a command packet")
+        .action(wrapCommand(async (context, { args, options, globalOptions }) => {
+        const message = args[0] ?? "";
+        const preferredClient = resolvePreferredClientName(context, globalOptions);
+        if (!options.literal && message.trim().startsWith("/")) {
+            return sendClientRequest(context, preferredClient, "chat.command", { command: message });
+        }
+        return sendClientRequest(context, preferredClient, "chat.send", { message });
+    }));
     command
         .command("command")
-        .description("Execute a server command. Defaults to server stdin FIFO (reliable); use --via client to route through the client's chat.")
+        .description("Execute a command. Defaults to auto-routing: prefer player context when a client is available, otherwise use server stdin.")
         .argument("<command>", "Command text, e.g. \"gamemode creative\" (leading slash optional)")
-        .option("--via <target>", "Delivery channel: server (stdin FIFO, default) or client (client WS, may fail if chat disabled)", "server")
+        .option("--via <target>", "Delivery channel: auto (default), server (stdin FIFO), or client (client WS)", "auto")
         .option("--server <name>", "Server instance name when --via server (default: active profile server)")
         .action(wrapCommand(async (context, { args, options, globalOptions }) => {
-        const via = options.via ?? "server";
+        const via = options.via ?? "auto";
+        const commandText = normalizeChatCommand(args[0]);
+        const preferredClient = resolvePreferredClientName(context, globalOptions);
         if (via === "client") {
-            return sendClientRequest(context, globalOptions.client, "chat.command", { command: args[0] });
+            return sendClientRequest(context, preferredClient, "chat.command", { command: commandText });
+        }
+        if (via === "auto") {
+            if (preferredClient) {
+                return sendClientRequest(context, preferredClient, "chat.command", { command: commandText });
+            }
+            if (!context.projectName) {
+                return sendClientRequest(context, undefined, "chat.command", { command: commandText });
+            }
+            const serverName = options.server ?? context.activeProfile?.server;
+            if (!serverName) {
+                throw new MctError({
+                    code: "INVALID_PARAMS",
+                    message: "No client context is available, and auto-routing could not resolve a server. Use --client, --server, or run inside a project profile."
+                }, 4);
+            }
+            return executeServerCommand(context, serverName, commandText);
         }
         if (via !== "server") {
-            throw new MctError({ code: "INVALID_PARAMS", message: `--via must be \"server\" or \"client\", got: ${via}` }, 4);
+            throw new MctError({ code: "INVALID_PARAMS", message: `--via must be \"auto\", \"server\" or \"client\", got: ${via}` }, 4);
         }
         if (!context.projectName) {
             throw new MctError({ code: "NO_PROJECT", message: "--via server requires a project context. Use --via client or run inside an mct project." }, 4);
@@ -31,8 +72,7 @@ export function createChatCommand() {
         if (!serverName) {
             throw new MctError({ code: "INVALID_PARAMS", message: "--via server requires --server <name> or an active profile with a server." }, 4);
         }
-        const manager = new ServerInstanceManager(context.globalState, context.projectName);
-        return manager.exec(serverName, args[0]);
+        return executeServerCommand(context, serverName, commandText);
     }));
     command
         .command("history")
@@ -49,5 +89,9 @@ export function createChatCommand() {
         .command("last")
         .description("Get the last chat message")
         .action(createRequestAction("chat.last", () => ({})));
+    command
+        .command("clear")
+        .description("Clear the cached chat history tracked by the client mod")
+        .action(createRequestAction("chat.clear", () => ({})));
     return command;
 }

package/dist/commands/client.d.ts

@@ -1,2 +1,4 @@
 import { Command } from "commander";
+import type { CommandContext } from "../util/context.js";
+export declare function resolveProfileServerAddress(context: Pick<CommandContext, "projectName" | "activeProfile" | "globalState">, explicitServer: string | undefined, loadPort?: (projectName: string, serverName: string) => Promise<number>): Promise<string | undefined>;
 export declare function createClientCommand(): Command;

package/dist/commands/client.js

@@ -1,6 +1,7 @@
 import { Command } from "commander";
 import { buildClientSearchResults } from "../download/SearchCommand.js";
 import { ClientInstanceManager } from "../instance/ClientInstanceManager.js";
+import { ServerInstanceManager } from "../instance/ServerInstanceManager.js";
 import { MctError } from "../util/errors.js";
 import { createRequestAction } from "./request-helpers.js";
 import { wrapCommand } from "../util/command.js";
@@ -12,6 +13,23 @@ import { copyFileIfMissing, downloadFile } from "../download/DownloadUtils.js";
 import { resolveClientInstanceDir } from "../util/paths.js";
 import { access, mkdir } from "node:fs/promises";
 import path from "node:path";
+export async function resolveProfileServerAddress(context, explicitServer, loadPort) {
+    if (explicitServer) {
+        return explicitServer;
+    }
+    if (!context.projectName || !context.activeProfile?.server) {
+        return undefined;
+    }
+    try {
+        const port = loadPort
+            ? await loadPort(context.projectName, context.activeProfile.server)
+            : (await new ServerInstanceManager(context.globalState, context.projectName).loadMeta(context.activeProfile.server)).port;
+        return `127.0.0.1:${port}`;
+    }
+    catch {
+        return undefined;
+    }
+}
 export function createClientCommand() {
     const command = new Command("client").description("Manage Minecraft client instances");
     command
@@ -125,7 +143,7 @@ export function createClientCommand() {
         .command("launch")
         .description("Launch a client instance")
         .argument("[name]", "Client instance name (default: from active profile)")
-        .option("--server <address>", "Target server address (e.g. localhost:25565)")
+        .option("--server <address>", "Target server address (default: active profile server, e.g. localhost:25565)")
         .option("--account <account>", "Offline username or account identifier")
         .option("--ws-port <port>", "WebSocket port override", Number)
         .option("--headless", "Launch in headless mode")
@@ -136,7 +154,11 @@ export function createClientCommand() {
             throw new MctError({ code: "INVALID_PARAMS", message: "Client name is required. Specify it as argument or set a profile." }, 4);
         }
         const manager = new ClientInstanceManager(context.globalState);
-        return manager.launch(clientName, options);
+        const serverAddress = await resolveProfileServerAddress(context, options.server);
+        return manager.launch(clientName, {
+            ...options,
+            server: serverAddress
+        });
     }));
     command
         .command("stop")

package/dist/commands/events.js

@@ -47,6 +47,66 @@ function readAllEvents(filePath) {
     }
     return out;
 }
+function filterEvents(events, options) {
+    let filtered = events;
+    if (options.sinceMs !== undefined) {
+        filtered = filtered.filter((event) => event.t >= options.sinceMs);
+    }
+    if (options.type) {
+        const wanted = new Set(options.type.split(",").map((s) => s.trim()).filter(Boolean));
+        filtered = filtered.filter((event) => wanted.has(event.type));
+    }
+    return filtered;
+}
+function buildPayloadText(event) {
+    return JSON.stringify({
+        type: event.type,
+        payload: event.payload ?? {}
+    });
+}
+function buildMatchPattern(raw) {
+    if (!raw)
+        return null;
+    try {
+        return new RegExp(raw);
+    }
+    catch {
+        throw new MctError({ code: "INVALID_PARAMS", message: `Invalid --match pattern: ${raw}` }, 4);
+    }
+}
+async function waitForEvent(filePath, options) {
+    const deadline = Date.now() + options.timeoutSeconds * 1000;
+    const matchPattern = buildMatchPattern(options.match);
+    const startedAt = Date.now();
+    while (Date.now() < deadline) {
+        const events = filterEvents(readAllEvents(filePath), {
+            sinceMs: options.sinceMs,
+            type: options.type
+        });
+        const matched = matchPattern
+            ? events.find((event) => matchPattern.test(buildPayloadText(event)))
+            : events[0];
+        if (matched) {
+            return {
+                file: filePath,
+                matched: true,
+                waitedMs: Date.now() - startedAt,
+                event: matched
+            };
+        }
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    throw new MctError({
+        code: "TIMEOUT",
+        message: `Timed out after ${options.timeoutSeconds}s waiting for events in ${filePath}`,
+        details: {
+            file: filePath,
+            type: options.type ?? null,
+            match: options.match ?? null,
+            sinceMs: options.sinceMs
+        }
+    }, 2);
+}
 export function createEventsCommand() {
     const command = new Command("events").description("Inspect the client event log (written by the mod to ~/.mct/logs/<client>/events.jsonl)");
     command
@@ -61,15 +121,10 @@ export function createEventsCommand() {
         const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
         const filePath = options.file ?? resolveEventsFile(clientName);
         const events = readAllEvents(filePath);
-        let filtered = events;
-        const sinceMs = parseSince(options.since, Date.now());
-        if (sinceMs !== undefined) {
-            filtered = filtered.filter((e) => e.t >= sinceMs);
-        }
-        if (options.type) {
-            const wanted = new Set(options.type.split(",").map((s) => s.trim()).filter(Boolean));
-            filtered = filtered.filter((e) => wanted.has(e.type));
-        }
+        let filtered = filterEvents(events, {
+            sinceMs: parseSince(options.since, Date.now()),
+            type: options.type
+        });
         if (!options.all) {
             const tail = options.tail ?? 20;
             if (filtered.length > tail) {
@@ -93,15 +148,31 @@ export function createEventsCommand() {
         const tail = args[0] ? Number(args[0]) : 20;
         const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
         const filePath = options.file ?? resolveEventsFile(clientName);
-        let events = readAllEvents(filePath);
-        if (options.type) {
-            const wanted = new Set(options.type.split(",").map((s) => s.trim()).filter(Boolean));
-            events = events.filter((e) => wanted.has(e.type));
-        }
+        let events = filterEvents(readAllEvents(filePath), {
+            type: options.type
+        });
         if (events.length > tail)
             events = events.slice(events.length - tail);
         return { file: filePath, returned: events.length, events };
     }));
+    command
+        .command("wait")
+        .description("Wait for a matching event. Defaults to events emitted after this command starts.")
+        .option("--timeout <seconds>", "Timeout in seconds (default 10)", Number)
+        .option("--since <duration>", "Also consider events since duration ago (e.g. 30s, 5m, 1h) or epoch ms")
+        .option("--type <types>", "Comma-separated list of event types to include")
+        .option("--match <pattern>", "Regex matched against event type and payload JSON")
+        .option("--file <path>", "Override the log file path")
+        .action(wrapCommand(async (context, { options, globalOptions }) => {
+        const clientName = globalOptions.client ?? context.activeProfile?.clients[0];
+        const filePath = options.file ?? resolveEventsFile(clientName);
+        return waitForEvent(filePath, {
+            timeoutSeconds: options.timeout ?? context.timeout("default"),
+            sinceMs: parseSince(options.since, Date.now()) ?? Date.now(),
+            type: options.type,
+            match: options.match
+        });
+    }));
     command
         .command("clear")
         .description("Truncate the event log for the active client")

package/dist/commands/request-helpers.d.ts

@@ -6,6 +6,7 @@ export interface RequestPayload<TOptions> {
     globalOptions: GlobalOptions;
 }
 export declare function sendClientRequest(context: CommandContext, clientName: string | undefined, action: string, params: Record<string, unknown>, timeoutSeconds?: number): Promise<unknown>;
+export declare function resolvePreferredClientName(context: CommandContext, globalOptions: GlobalOptions): string | undefined;
 export declare function createRequestAction<TOptions = Record<string, any>>(action: string, buildParams: (payload: RequestPayload<TOptions>) => Record<string, unknown>, timeoutSelector?: (payload: RequestPayload<TOptions>, context: CommandContext) => number | undefined): (this: Command, ...input: unknown[]) => Promise<void>;
 export declare function parseJson(text: string, fieldName: string): Record<string, unknown>;
 export declare function parseNumberList(text: string): number[];

package/dist/commands/request-helpers.js

@@ -9,10 +9,13 @@ export async function sendClientRequest(context, clientName, action, params, tim
     const ws = new WebSocketClient(`ws://127.0.0.1:${client.wsPort}`);
     return ws.send(action, params, timeoutSeconds ?? context.timeout("default"));
 }
+export function resolvePreferredClientName(context, globalOptions) {
+    return globalOptions.client ?? context.activeProfile?.clients[0];
+}
 export function createRequestAction(action, buildParams, timeoutSelector) {
     return wrapCommand(async (context, payload) => {
         const timeout = timeoutSelector?.(payload, context);
-        return sendClientRequest(context, payload.globalOptions.client, action, buildParams(payload), timeout);
+        return sendClientRequest(context, resolvePreferredClientName(context, payload.globalOptions), action, buildParams(payload), timeout);
     });
 }
 export function parseJson(text, fieldName) {

package/dist/commands/schema.d.ts

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

package/dist/commands/schema.js

@@ -0,0 +1,10 @@
+import { Command } from "commander";
+import { buildSchemaDocument } from "../schema.js";
+import { wrapCommand } from "../util/command.js";
+export function createSchemaCommand(getProgram) {
+    return new Command("schema")
+        .description("Output a machine-readable CLI and protocol schema")
+        .action(wrapCommand(async () => {
+        return buildSchemaDocument(getProgram());
+    }));
+}

package/dist/commands/server.js

@@ -88,9 +88,15 @@ export function createServerCommand() {
         .command("status")
         .description("Show server status")
         .argument("[name]", "Server instance name (omit to show all in project)")
-        .action(wrapCommand(async (context, { args }) => {
-        const project = requireProject(context);
-        const manager = new ServerInstanceManager(context.globalState, project);
+        .option("--all", "Show running servers across all projects")
+        .action(wrapCommand(async (context, { args, options }) => {
+        if (options.all || (!context.projectName && !args[0])) {
+            return ServerInstanceManager.statusAll(context.globalState);
+        }
+        if (!context.projectName) {
+            throw new MctError({ code: "NO_PROJECT", message: "No project context. Omit the name to inspect all running servers, or use --project <name>." }, 4);
+        }
+        const manager = new ServerInstanceManager(context.globalState, context.projectName);
         return manager.status(args[0]);
     }));
     command
@@ -137,6 +143,7 @@ export function createServerCommand() {
         .option("--follow", "Wait for new log lines (requires --timeout)")
         .option("--timeout <seconds>", "Max seconds to wait when --follow is set", Number)
         .option("--first-match", "With --follow, exit as soon as the first matching line appears")
+        .option("--raw-colors", "Preserve ANSI color escape sequences in returned lines")
         .action(wrapCommand(async (context, { args, options }) => {
         const project = requireProject(context);
         const serverName = resolveServerName(context, args[0]);
@@ -146,13 +153,15 @@ export function createServerCommand() {
             return manager.followLogs(serverName, {
                 grep: options.grep,
                 timeoutSeconds,
-                firstMatchOnly: Boolean(options.firstMatch)
+                firstMatchOnly: Boolean(options.firstMatch),
+                rawColors: Boolean(options.rawColors)
             });
         }
         return manager.readLogs(serverName, {
             tail: options.tail,
             grep: options.grep,
-            since: options.since
+            since: options.since,
+            rawColors: Boolean(options.rawColors)
         });
     }));
     return command;

package/dist/index.js

@@ -21,6 +21,7 @@ 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 { createSchemaCommand } from "./commands/schema.js";
 import { createServerCommand } from "./commands/server.js";
 import { createSignCommand } from "./commands/sign.js";
 import { createStatusCommand } from "./commands/status.js";
@@ -67,6 +68,7 @@ export function buildProgram() {
     program.addCommand(createServerCommand());
     program.addCommand(createClientCommand());
     program.addCommand(createPluginCommand());
+    program.addCommand(createSchemaCommand(() => program));
     // Game interaction commands
     program.addCommand(createChatCommand());
     program.addCommand(createInputCommand());

package/dist/instance/ClientInstanceManager.js

@@ -244,7 +244,7 @@ export class ClientInstanceManager {
         });
         throw new MctError({
             code: "TIMEOUT",
-            message: `Timed out after ${timeoutSeconds}s waiting for client ${clientName} to join a world (${wsUrl}). ${this.formatDiagnostics(diag)} Tip: try \`mct client reconnect --address <server>\` or \`mct client launch --force\`.`,
+            message: `Timed out after ${timeoutSeconds}s waiting for client ${clientName} to join a world (${wsUrl}). ${this.formatDiagnostics(diag)} Tip: if the client is still at the main menu, run \`mct client reconnect --address <server>\` or relaunch with \`mct client launch --server <address>\` (inside a project, plain \`mct client launch\` uses the active profile server).`,
             details: diag
         }, 2);
     }

package/dist/instance/ServerInstanceManager.d.ts

@@ -1,5 +1,7 @@
 import type { GlobalStateStore } from "../util/global-state.js";
 import type { ServerInstanceMeta, ServerRuntimeEntry, ServerType } from "../util/instance-types.js";
+export declare function stripAnsiCodes(text: string): string;
+export declare function ensureServerPortProperty(instanceDir: string, port: number): Promise<void>;
 export interface CreateServerOptions {
     name: string;
     project: string;
@@ -60,6 +62,10 @@ export declare class ServerInstanceManager {
         stdinPipe?: string;
         running: boolean;
     }>;
+    static statusAll(globalState: GlobalStateStore): Promise<{
+        [key: string]: unknown;
+        running: boolean;
+    }[]>;
     waitReady(serverName: string, timeoutSeconds: number): Promise<{
         reachable: boolean;
         host: string;
@@ -74,6 +80,7 @@ export declare class ServerInstanceManager {
         tail?: number;
         grep?: string;
         since?: number;
+        rawColors?: boolean;
     }): Promise<{
         logPath: string;
         totalLines: number;
@@ -84,6 +91,7 @@ export declare class ServerInstanceManager {
         grep?: string;
         timeoutSeconds: number;
         firstMatchOnly?: boolean;
+        rawColors?: boolean;
     }): Promise<{
         logPath: string;
         matched: boolean;

package/dist/instance/ServerInstanceManager.js

@@ -8,6 +8,36 @@ import { waitForTcpPort } 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;
+export function stripAnsiCodes(text) {
+    return text.replace(ANSI_ESCAPE_PATTERN, "");
+}
+export async function ensureServerPortProperty(instanceDir, port) {
+    const filePath = path.join(instanceDir, "server.properties");
+    let lines = [];
+    try {
+        const raw = await readFile(filePath, "utf8");
+        lines = raw.split(/\r?\n/);
+        if (lines.length > 0 && lines[lines.length - 1] === "") {
+            lines.pop();
+        }
+    }
+    catch {
+        // initialize from scratch
+    }
+    let updated = false;
+    lines = lines.map((line) => {
+        if (/^\s*server-port\s*=/.test(line)) {
+            updated = true;
+            return `server-port=${port}`;
+        }
+        return line;
+    });
+    if (!updated) {
+        lines.push(`server-port=${port}`);
+    }
+    await writeFile(filePath, `${lines.join("\n")}\n`, "utf8");
+}
 export class ServerInstanceManager {
     globalState;
     project;
@@ -28,6 +58,7 @@ export class ServerInstanceManager {
             await writeFile(path.join(instanceDir, "eula.txt"), "eula=true\n", "utf8");
         }
         await mkdir(path.join(instanceDir, "plugins"), { recursive: true });
+        await ensureServerPortProperty(instanceDir, port);
         const meta = {
             name: options.name,
             project: options.project,
@@ -56,6 +87,7 @@ export class ServerInstanceManager {
         if (options.eula) {
             await writeFile(path.join(instanceDir, "eula.txt"), "eula=true\n", "utf8");
         }
+        await ensureServerPortProperty(instanceDir, meta.port);
         const mctHome = resolveMctHome();
         const logsDir = path.join(mctHome, "logs");
         const stateDir = path.join(mctHome, "state");
@@ -154,6 +186,19 @@ export class ServerInstanceManager {
         await this.globalState.writeServerState(state);
         return results;
     }
+    static async statusAll(globalState) {
+        const state = await globalState.readServerState();
+        const results = [];
+        for (const [key, entry] of Object.entries(state.servers)) {
+            const running = isProcessRunning(entry.pid);
+            if (!running) {
+                delete state.servers[key];
+            }
+            results.push({ running, ...entry });
+        }
+        await globalState.writeServerState(state);
+        return results;
+    }
     async waitReady(serverName, timeoutSeconds) {
         const stateKey = `${this.project}/${serverName}`;
         const state = await this.globalState.readServerState();
@@ -201,6 +246,9 @@ export class ServerInstanceManager {
         if (lines.length > 0 && lines[lines.length - 1] === "")
             lines = lines.slice(0, -1);
         const total = lines.length;
+        if (!options.rawColors) {
+            lines = lines.map((line) => stripAnsiCodes(line));
+        }
         if (options.since !== undefined && options.since > 0) {
             lines = lines.slice(Math.max(0, options.since));
         }
@@ -269,8 +317,9 @@ export class ServerInstanceManager {
                 const parts = buffer.split("\n");
                 buffer = parts.pop() ?? "";
                 for (const line of parts) {
-                    if (!re || re.test(line)) {
-                        matches.push(line);
+                    const rendered = options.rawColors ? line : stripAnsiCodes(line);
+                    if (!re || re.test(rendered)) {
+                        matches.push(rendered);
                         if (options.firstMatchOnly)
                             return finish(false);
                     }

package/dist/schema.d.ts

@@ -0,0 +1,63 @@
+import type { Argument, Command, Option } from "commander";
+interface ProtocolEntry {
+    name?: string;
+    code?: string;
+    description?: string;
+    params?: string[];
+    exitCode?: number;
+}
+declare function serializeOption(option: Option): {
+    name: string;
+    flags: string;
+    description: string;
+    required: boolean;
+    mandatory: boolean;
+    defaultValue: any;
+};
+declare function serializeArgument(argument: Argument): {
+    name: string;
+    required: boolean;
+    variadic: boolean;
+};
+declare function serializeCommand(command: Command, parents?: string[]): {
+    name: string;
+    path: string;
+    description: string;
+    aliases: string[];
+    arguments: ReturnType<typeof serializeArgument>[];
+    options: ReturnType<typeof serializeOption>[];
+    subcommands: ReturnType<typeof serializeCommand>[];
+    leaf: boolean;
+};
+export declare function buildSchemaDocument(program: Command): {
+    schemaVersion: number;
+    cli: {
+        name: string;
+        description: string;
+        globalOptions: {
+            name: string;
+            flags: string;
+            description: string;
+            required: boolean;
+            mandatory: boolean;
+            defaultValue: any;
+        }[];
+        commands: {
+            name: string;
+            path: string;
+            description: string;
+            aliases: string[];
+            arguments: ReturnType<typeof serializeArgument>[];
+            options: ReturnType<typeof serializeOption>[];
+            subcommands: ReturnType<typeof serializeCommand>[];
+            leaf: boolean;
+        }[];
+        leafCommands: string[];
+    };
+    protocol: {
+        actions: number | ProtocolEntry[];
+        queries: number | ProtocolEntry[];
+        errors: number | ProtocolEntry[];
+    };
+};
+export {};

package/dist/schema.js

@@ -0,0 +1,77 @@
+import { readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+function resolveRepoRoot() {
+    return path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..", "..");
+}
+function loadJsonFile(relativePath) {
+    const filePath = path.join(resolveRepoRoot(), relativePath);
+    return JSON.parse(readFileSync(filePath, "utf8"));
+}
+function serializeOption(option) {
+    return {
+        name: option.name(),
+        flags: option.flags,
+        description: option.description,
+        required: option.required,
+        mandatory: option.mandatory,
+        defaultValue: option.defaultValue
+    };
+}
+function serializeArgument(argument) {
+    return {
+        name: argument.name(),
+        required: argument.required,
+        variadic: argument.variadic
+    };
+}
+function serializeCommand(command, parents = []) {
+    const pathSegments = [...parents, command.name()];
+    return {
+        name: command.name(),
+        path: pathSegments.join(" "),
+        description: command.description(),
+        aliases: command.aliases(),
+        arguments: command.registeredArguments.map(serializeArgument),
+        options: command.options.map(serializeOption),
+        subcommands: command.commands.map((subcommand) => serializeCommand(subcommand, pathSegments)),
+        leaf: command.commands.length === 0
+    };
+}
+function collectLeafCommands(commands) {
+    const leaves = [];
+    const visit = (command) => {
+        if (command.leaf) {
+            leaves.push(command.path);
+            return;
+        }
+        for (const subcommand of command.subcommands) {
+            visit(subcommand);
+        }
+    };
+    for (const command of commands) {
+        visit(command);
+    }
+    return leaves;
+}
+export function buildSchemaDocument(program) {
+    const actions = loadJsonFile("protocol/actions.json");
+    const queries = loadJsonFile("protocol/queries.json");
+    const errors = loadJsonFile("protocol/errors.json");
+    const commands = program.commands.map((command) => serializeCommand(command));
+    return {
+        schemaVersion: 1,
+        cli: {
+            name: program.name(),
+            description: program.description(),
+            globalOptions: program.options.map(serializeOption),
+            commands,
+            leafCommands: collectLeafCommands(commands)
+        },
+        protocol: {
+            actions: actions.actions ?? [],
+            queries: queries.queries ?? [],
+            errors: errors.errors ?? []
+        }
+    };
+}

package/package.json

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