@bkm016/calcite 0.0.0-stage → 0.1.0

package/dist/cli.js

@@ -0,0 +1,242 @@
+#!/usr/bin/env node
+import { writeFile } from 'node:fs/promises';
+import { createInterface } from 'node:readline';
+import { Command, InvalidArgumentError, Option } from 'commander';
+import { listAccounts, removeAccount, startLogin } from './accounts.js';
+import { Client, defaultUsername, installVersion } from './client.js';
+import { hasSharedLib, which } from './display.js';
+import { findJavaInstalls } from './java.js';
+import { setLogLevel } from './log.js';
+import { getManifest } from './mojang.js';
+import { runMcpStdio } from './mcp.js';
+import { resolvePaths } from './paths.js';
+import { VERSION } from './version.js';
+const out = (line = '') => process.stdout.write(`${line}\n`);
+function positiveInt(value) {
+    const n = Number(value);
+    if (!Number.isInteger(n) || n <= 0)
+        throw new InvalidArgumentError('must be a positive integer');
+    return n;
+}
+function fail(err) {
+    const e = err;
+    process.stderr.write(`error${e.code ? ` [${e.code}]` : ''}: ${e.message}\n`);
+    process.exit(1);
+}
+const program = new Command()
+    .name('calcite')
+    .description('Run real Minecraft clients headlessly for testing and AI agents')
+    .version(VERSION)
+    .option('-v, --verbose', 'debug logging')
+    .hook('preAction', (cmd) => {
+    if (cmd.opts().verbose)
+        setLogLevel('debug');
+});
+program
+    .command('launch')
+    .description('Launch a client and control it from the terminal')
+    .argument('[server]', 'host[:port] to join')
+    .option('-n, --name <name>', 'client / instance name', 'calcite')
+    .option('-V, --mc-version <version>', 'Minecraft version, "release" or "snapshot"', 'release')
+    .option('-u, --username <name>', 'offline username (default: the client name)')
+    .option('-m, --microsoft [account]', 'use a stored Microsoft account (primary one, or by name)')
+    .addOption(new Option('-r, --render <mode>', 'renderer mode').choices(['on-demand', 'always', 'off']).default('on-demand'))
+    .option('--java <path>', 'java executable to use')
+    .option('--no-java-download', 'never download a Java runtime')
+    .option('--memory <size>', 'max heap, e.g. 2G', '2G')
+    .option('--no-reconnect', 'do not rejoin after a disconnect or crash')
+    .action(async (server, o) => {
+    const account = o.microsoft
+        ? { type: 'microsoft', name: typeof o.microsoft === 'string' ? o.microsoft : undefined }
+        : { type: 'offline', username: o.username ?? defaultUsername(o.name) };
+    const client = new Client({
+        name: o.name,
+        version: o.mcVersion,
+        server,
+        account,
+        render: o.render,
+        javaPath: o.java,
+        allowJavaDownload: o.javaDownload,
+        memory: o.memory,
+        reconnect: o.reconnect,
+    });
+    client.on('phase', (p) => process.stderr.write(`[${p}]\n`));
+    client.on('chat', (c) => out(c.message));
+    let stopping = false;
+    const stop = async (code = 0) => {
+        if (stopping)
+            return;
+        stopping = true;
+        await client.stop();
+        process.exit(code);
+    };
+    process.once('SIGINT', () => void stop(130));
+    process.once('SIGTERM', () => void stop(143));
+    try {
+        await client.start();
+    }
+    catch (err) {
+        process.stderr.write(client.logsSince({ limit: 30 }).map((l) => `  ${l.line}`).join('\n') + '\n');
+        await client.stop();
+        fail(err);
+    }
+    process.stderr.write('Ready. Type chat, /command, or :state :ents [radius] :shot [file] :render on|off :respawn :quit\n');
+    const rl = createInterface({ input: process.stdin });
+    rl.on('close', () => void stop());
+    for await (const raw of rl) {
+        const line = raw.trim();
+        if (!line)
+            continue;
+        try {
+            if (line === ':quit' || line === ':q')
+                break;
+            else if (line === ':state')
+                out(JSON.stringify(await client.state(), null, 2));
+            else if (line.startsWith(':ents')) {
+                const radius = Number(line.split(/\s+/)[1] ?? 32);
+                for (const e of await client.entities({ radius })) {
+                    out(`${e.id}\t${e.type}\t${e.name ?? ''}${e.customName ? ` (${e.customName})` : ''}\t${e.x?.toFixed(1)} ${e.y?.toFixed(1)} ${e.z?.toFixed(1)}`);
+                }
+            }
+            else if (line.startsWith(':shot')) {
+                const file = line.split(/\s+/)[1] ?? `calcite-${Date.now()}.png`;
+                const shot = await client.screenshot();
+                await writeFile(file, shot.png);
+                out(`saved ${file} (${shot.png.length} bytes)`);
+            }
+            else if (line.startsWith(':render')) {
+                await client.setRender(line.endsWith('on'));
+            }
+            else if (line === ':respawn')
+                await client.respawn();
+            else if (line.startsWith('/'))
+                await client.command(line.slice(1));
+            else if (line.startsWith(':'))
+                process.stderr.write(`unknown command ${line}\n`);
+            else
+                await client.chat(line);
+        }
+        catch (err) {
+            process.stderr.write(`error: ${err.message}\n`);
+        }
+    }
+    await stop();
+});
+program
+    .command('install')
+    .description('Download a version (client, libraries, assets, Java) without launching')
+    .argument('[version]', 'version id, "release" or "snapshot"', 'release')
+    .option('--java <path>', 'java executable to use')
+    .action(async (version, o) => {
+    try {
+        const r = await installVersion(version, { javaPath: o.java, onLine: (l) => process.stderr.write(`  ${l}\n`) });
+        out(`installed ${r.id} (java ${r.java}; probe ${r.probe})`);
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+program
+    .command('versions')
+    .description('List Minecraft versions')
+    .addOption(new Option('-t, --type <type>', 'version type').choices(['release', 'snapshot', 'old_beta', 'old_alpha', 'all']).default('release'))
+    .option('-l, --limit <n>', 'how many', positiveInt, 20)
+    .action(async (o) => {
+    try {
+        const manifest = await getManifest(resolvePaths());
+        out(`latest release ${manifest.latest.release}, snapshot ${manifest.latest.snapshot}`);
+        for (const v of manifest.versions.filter((v) => o.type === 'all' || v.type === o.type).slice(0, o.limit)) {
+            out(`${v.id.padEnd(24)} ${v.type.padEnd(9)} ${v.releaseTime.slice(0, 10)}`);
+        }
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+program
+    .command('login')
+    .description('Log in with a Microsoft account (device code); the login is saved and refreshed automatically')
+    .action(async () => {
+    try {
+        const handle = await startLogin(resolvePaths());
+        process.once('SIGINT', () => void handle.cancel().then(() => process.exit(130)));
+        out(`Open this URL in a browser and sign in:\n\n  ${await handle.url}\n`);
+        out(`Logged in as ${await handle.done}`);
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+program
+    .command('accounts')
+    .description('List saved Microsoft accounts')
+    .action(async () => {
+    try {
+        const accounts = await listAccounts(resolvePaths());
+        if (!accounts.length)
+            out('No saved accounts. Run `calcite login`.');
+        for (const a of accounts)
+            out(`${a.primary ? '*' : ' '} ${a.name}${a.uuid ? `  ${a.uuid}` : ''}`);
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+program
+    .command('logout')
+    .description('Remove a saved Microsoft account')
+    .argument('<account>', 'profile name')
+    .action(async (name) => {
+    try {
+        if (!(await removeAccount(resolvePaths(), name)))
+            fail(Object.assign(new Error(`No saved account named "${name}"`), { code: 'unknown_account' }));
+        out(`Removed ${name}`);
+    }
+    catch (err) {
+        fail(err);
+    }
+});
+program
+    .command('doctor')
+    .description('Check the environment')
+    .action(async () => {
+    const paths = resolvePaths();
+    out(`calcite ${VERSION} on node ${process.versions.node} (${process.platform}/${process.arch})`);
+    out(`home:  ${paths.home}`);
+    out(`probe: ${paths.probe}`);
+    const javas = await findJavaInstalls(paths);
+    out(`java:  ${javas.length ? '' : 'none found (will be downloaded on demand)'}`);
+    for (const j of javas)
+        out(`  ${String(j.major).padStart(2)}  ${j.version.padEnd(12)} ${j.path}`);
+    if (process.platform === 'linux') {
+        const xvfb = which('Xvfb');
+        out(`xvfb:  ${xvfb ?? 'missing — needed for screenshots without a display (apt install xvfb libgl1-mesa-dri libegl1 libegl-mesa0)'}`);
+        out(`egl:   ${hasSharedLib('libEGL.so.1') ? 'ok' : 'missing — Minecraft 26.x needs it to render on Xvfb (apt install libegl1 libegl-mesa0)'}`);
+        out(`display: ${process.env.DISPLAY ?? 'none (a virtual one will be started)'}`);
+    }
+    try {
+        const accounts = await listAccounts(paths);
+        out(`accounts: ${accounts.map((a) => a.name).join(', ') || 'none'}`);
+    }
+    catch (err) {
+        out(`accounts: unreadable (${err.message})`);
+    }
+    try {
+        const m = await getManifest(paths, { refresh: true });
+        out(`mojang: reachable (latest ${m.latest.release})`);
+    }
+    catch (err) {
+        out(`mojang: UNREACHABLE (${err.message})`);
+    }
+});
+program
+    .command('mcp')
+    .description('Run the MCP server on stdio')
+    .addOption(new Option('-r, --render <mode>', 'default renderer mode').choices(['on-demand', 'always', 'off']))
+    .option('--memory <size>', 'default max heap')
+    .action(async (o) => {
+    // stdout belongs to the protocol; logs go to stderr
+    await runMcpStdio({ defaults: { render: o.render, memory: o.memory } });
+});
+program.parseAsync().catch(fail);
+//# sourceMappingURL=cli.js.map

package/dist/cli.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"cli.js","sourceRoot":"","sources":["../src/cli.ts"],"names":[],"mappings":"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"}

package/dist/client.d.ts

@@ -0,0 +1,251 @@
+import { EventEmitter } from 'node:events';
+import { type CalcitePaths } from './paths.js';
+export type RenderMode = 'off' | 'on-demand' | 'always';
+export type Account = {
+    type: 'offline';
+    username: string;
+} | {
+    type: 'microsoft';
+    name?: string;
+};
+export type Phase = 'idle' | 'preparing' | 'waiting_for_server' | 'starting' | 'connecting' | 'in_game' | 'disconnected' | 'reconnecting' | 'stopping' | 'stopped' | 'crashed';
+export interface ServerAddress {
+    host: string;
+    port: number;
+}
+export interface ClientOptions {
+    /** Instance name; also the game directory name. Letters, digits, '-', '_' and '.' only. */
+    name: string;
+    /** Minecraft version id, "latest" or "snapshot". */
+    version: string;
+    /** Server to join ("host[:port]"). Without a server the client stays on the title screen. */
+    server?: string | ServerAddress;
+    /** Account: offline (any username, for online-mode=false servers) or a stored Microsoft account. */
+    account?: Account;
+    /**
+     * World rendering: 'off' (no renderer, cheapest, no screenshots), 'on-demand' (renders only for screenshots,
+     * default), 'always'. Rendering needs a display (Linux: DISPLAY or Xvfb) and, with an offline account, Linux.
+     */
+    render?: RenderMode;
+    /** Explicit java executable for the game. */
+    javaPath?: string;
+    /** Download a Temurin runtime when the required Java is missing (default true). */
+    allowJavaDownload?: boolean;
+    /** Max heap, e.g. "2G" (default "2G"). */
+    memory?: string;
+    /** Extra JVM / game arguments (must not contain spaces). */
+    jvmArgs?: string[];
+    gameArgs?: string[];
+    renderDistance?: number;
+    maxFps?: number;
+    /** Reconnect (relaunch) after a disconnect or crash. Default: enabled, 10 attempts. */
+    reconnect?: boolean | {
+        maxAttempts?: number;
+    };
+    /** How long to wait for the server port before launching (default 120 s). */
+    waitForServerMs?: number;
+    /** Overall start timeout including downloads (default 15 min). */
+    startTimeoutMs?: number;
+    paths?: CalcitePaths;
+}
+export interface LogLine {
+    seq: number;
+    time: number;
+    source: 'game' | 'calcite';
+    line: string;
+}
+export interface ChatLine {
+    seq: number;
+    time: number;
+    message: string;
+}
+export interface PlayerState {
+    id?: number;
+    uuid?: string;
+    name?: string;
+    x?: number;
+    y?: number;
+    z?: number;
+    yaw?: number;
+    pitch?: number;
+    health?: number;
+    dimension?: string;
+}
+export interface GameState {
+    ready: boolean;
+    headless: boolean;
+    inGame: boolean;
+    screen?: string | null;
+    /** A resource (re)load overlay is showing. */
+    loading?: boolean;
+    disconnectReason?: string | null;
+    fps?: number;
+    noRender?: boolean;
+    player?: PlayerState;
+}
+export interface EntityInfo {
+    id: number;
+    uuid: string;
+    type: string;
+    x?: number;
+    y?: number;
+    z?: number;
+    yaw?: number;
+    pitch?: number;
+    name?: string;
+    customName?: string;
+    vehicleId?: number | null;
+    invisible?: boolean;
+    removed?: boolean;
+}
+export interface EntityQuery {
+    /** Only entities within this distance of the player (blocks). */
+    radius?: number;
+    /** Entity type id, e.g. "minecraft:villager" (the "minecraft:" prefix is optional). */
+    type?: string;
+    uuid?: string;
+    /** Substring match on name or custom name (case-insensitive). */
+    name?: string;
+    limit?: number;
+    includeSelf?: boolean;
+}
+export interface ClientStatus {
+    name: string;
+    version: string;
+    phase: Phase;
+    render: RenderMode;
+    headless: boolean;
+    account: Account;
+    server?: ServerAddress;
+    gameDir: string;
+    pid?: number;
+    java?: string;
+    startedAt?: number;
+    reconnects: number;
+    lastError?: string;
+    probeConnected: boolean;
+    game?: GameState;
+}
+export declare class CalciteError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function parseServer(server: string | ServerAddress): ServerAddress;
+/** Offline username derived from a client name (3-16 chars of [A-Za-z0-9_]). */
+export declare function defaultUsername(name: string): string;
+export interface InstallOptions {
+    paths?: CalcitePaths;
+    javaPath?: string;
+    allowJavaDownload?: boolean;
+    onLine?: (line: string) => void;
+}
+/**
+ * Downloads everything a version needs (client, libraries, natives, assets, mappings, Java, HeadlessMC) without
+ * starting the game, so later launches start fast and work offline.
+ */
+export declare function installVersion(spec: string, opts?: InstallOptions): Promise<{
+    id: string;
+    java: string;
+    probe: string;
+}>;
+/**
+ * One Minecraft client controlled by Calcite.
+ *
+ * Events: 'phase' (Phase), 'log' (LogLine), 'chat' (ChatLine), 'state' (GameState), 'exit' (code).
+ */
+export declare class Client extends EventEmitter {
+    readonly options: Required<Pick<ClientOptions, 'name' | 'version'>> & ClientOptions;
+    readonly paths: CalcitePaths;
+    readonly gameDir: string;
+    readonly render: RenderMode;
+    readonly account: Account;
+    readonly server?: ServerAddress;
+    private phaseValue;
+    private logs;
+    private chats;
+    private seq;
+    private probe;
+    private run;
+    private display;
+    private releaseInstance;
+    private probeConfig;
+    private java;
+    private versionJson;
+    private names;
+    private headlessValue;
+    private lastState;
+    private lastError;
+    /** Error code of a failure that relaunching cannot fix (reported by start() instead of "crashed"). */
+    private fatalCode;
+    private startedAt;
+    private reconnects;
+    private stopping;
+    private poller;
+    private inGameSince;
+    private relaunching;
+    private everInGame;
+    private joinRequested;
+    private readonly log;
+    constructor(options: ClientOptions);
+    get phase(): Phase;
+    get headless(): boolean;
+    private setPhase;
+    private note;
+    private pushLog;
+    /**
+     * Prepares everything (Java, game files, mappings), launches the client and resolves once it is in a world
+     * (or on the title screen when no server is configured).
+     */
+    start(): Promise<ClientStatus>;
+    /** Downloads and verifies everything needed to launch (idempotent). */
+    prepare(): Promise<void>;
+    private resolveHeadless;
+    private launch;
+    private onProbeConnected;
+    private poll;
+    private reconnectLimit;
+    private maybeReconnect;
+    private onGameExit;
+    private waitUntilStarted;
+    private cleanupRun;
+    private shutdown;
+    /** Stops the game and releases all resources. */
+    stop(): Promise<void>;
+    status(): ClientStatus;
+    private requireProbe;
+    state(): Promise<GameState>;
+    entities(query?: EntityQuery): Promise<EntityInfo[]>;
+    chat(message: string): Promise<void>;
+    command(command: string): Promise<void>;
+    respawn(): Promise<void>;
+    setRender(enabled: boolean): Promise<void>;
+    /** Takes a screenshot and returns the PNG. With {@code keep} the file stays in the game's screenshots folder. */
+    screenshot({ keep }?: {
+        keep?: boolean | undefined;
+    }): Promise<{
+        path?: string;
+        png: Buffer;
+    }>;
+    logsSince(opts?: {
+        since?: number;
+        limit?: number;
+        contains?: string;
+        source?: LogLine['source'];
+    }): LogLine[];
+    chatSince(since?: number, limit?: number): ChatLine[];
+    /**
+     * Waits for a condition: a chat line matching {@code chat} (regex), an entity appearing/disappearing, or a
+     * phase. Resolves with a description of what matched.
+     */
+    waitFor(cond: {
+        chat?: string;
+        entity?: EntityQuery & {
+            present?: boolean;
+        };
+        phase?: Phase;
+    }, timeoutMs?: number): Promise<{
+        matched: string;
+        chat?: ChatLine;
+        entities?: EntityInfo[];
+    }>;
+}