@bkm016/calcite 0.0.0-stage → 0.2.0

package/dist/client.d.ts

@@ -0,0 +1,127 @@
+import { ClientCore } from './client-core.js';
+import { type BlockFace, type BlockInfo, type BlockPosition, type ChatLine, type ClickMode, type ContainerInfo, type DigResult, type EntityInfo, type EntityQuery, type GameState, type HitTarget, type InventoryInfo, type ItemInfo, type LogLine, type MoveControls, type Phase, type WalkResult } from './types.js';
+export * from './types.js';
+export { installVersion, type InstallOptions } from './install.js';
+/**
+ * One Minecraft client controlled by Calcite.
+ *
+ * Events: 'phase' (Phase), 'log' (LogLine), 'chat' (ChatLine), 'state' (GameState), 'exit' (code).
+ */
+export declare class Client extends ClientCore {
+    state(): Promise<GameState>;
+    entities(query?: EntityQuery): Promise<EntityInfo[]>;
+    chat(message: string): Promise<void>;
+    command(command: string): Promise<void>;
+    respawn(): Promise<void>;
+    /** Turns the player to an absolute rotation (degrees; yaw 0 = south, pitch -90 = up) or towards a point. */
+    look(to: {
+        yaw?: number;
+        pitch?: number;
+    } | {
+        x: number;
+        y: number;
+        z: number;
+    }): Promise<{
+        yaw: number;
+        pitch: number;
+    }>;
+    /**
+     * Holds movement controls until changed (or for {@code ticks} game ticks, 20 per second). Pass false to release
+     * a control; {@link stop} releases all of them.
+     */
+    move(controls: MoveControls, opts?: {
+        ticks?: number;
+    }): Promise<MoveControls & {
+        releaseInTicks?: number;
+    }>;
+    /** Releases every control and cancels a running walkTo/dig/held use. */
+    stopActions(): Promise<void>;
+    /**
+     * Walks in a straight line to (x, z), jumping over single blocks and swimming. Resolves when within
+     * {@code range} blocks, or with {@code arrived: false} when stuck (no progress for 3 s) or timed out.
+     * There is no path finding: route around obstacles with intermediate points.
+     */
+    walkTo(x: number, z: number, opts?: {
+        range?: number;
+        sprint?: boolean;
+        timeoutMs?: number;
+    }): Promise<WalkResult>;
+    /** Left click: attacks the entity (facing it first) or whatever the crosshair points at. */
+    attack(entityId?: number): Promise<HitTarget>;
+    /**
+     * Right click: interacts with an entity, a block (opening chests, pressing buttons, placing the held block
+     * against that face) or, with no target, whatever the crosshair points at / the held item in the air.
+     * {@code holdTicks} keeps the button pressed afterwards (eating, drinking, drawing a bow, shields).
+     */
+    use(target?: {
+        entityId?: number;
+        block?: BlockPosition & {
+            face?: BlockFace;
+        };
+        holdTicks?: number;
+    }): Promise<HitTarget>;
+    /** Mines a block like a player (holding left click, taking the real break time). */
+    dig(block: BlockPosition & {
+        face?: BlockFace;
+    }, opts?: {
+        timeoutMs?: number;
+    }): Promise<DigResult>;
+    /** The block at a position as the client sees it. */
+    block(pos: BlockPosition): Promise<BlockInfo>;
+    /** What the crosshair points at. */
+    target(): Promise<HitTarget>;
+    inventory(): Promise<InventoryInfo>;
+    /** Selects hotbar slot 0-8. */
+    selectSlot(slot: number): Promise<{
+        selected: number;
+        item: ItemInfo | null;
+    }>;
+    /** The open container (chest, furnace, villager trade, ...) or the inventory; {@code waitMs} waits for one to open. */
+    container(opts?: {
+        waitMs?: number;
+    }): Promise<ContainerInfo>;
+    /**
+     * Clicks a slot of the open container (or the inventory). Modes: pickup (default; button 0 left, 1 right),
+     * quick_move (shift click), swap (button = hotbar slot 0-8 or 40 for the offhand), clone, throw (button 1 =
+     * whole stack), quick_craft, pickup_all. Slot -999 is outside the window.
+     */
+    click(slot: number, opts?: {
+        button?: number;
+        mode?: ClickMode;
+    }): Promise<ContainerInfo>;
+    closeContainer(): Promise<void>;
+    /** Drops one item (or the whole stack) from the selected hotbar slot. */
+    drop(opts?: {
+        all?: boolean;
+    }): Promise<ItemInfo>;
+    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[];
+    }>;
+}

package/dist/client.js

@@ -0,0 +1,185 @@
+import { readFile, rm } from 'node:fs/promises';
+import { ClientCore, sleep } from './client-core.js';
+import { ProbeError } from './probe-server.js';
+import { CalciteError, } from './types.js';
+export * from './types.js';
+export { installVersion } from './install.js';
+/**
+ * One Minecraft client controlled by Calcite.
+ *
+ * Events: 'phase' (Phase), 'log' (LogLine), 'chat' (ChatLine), 'state' (GameState), 'exit' (code).
+ */
+export class Client extends ClientCore {
+    async state() {
+        const state = await this.requireProbe().request('state');
+        this.lastState = state;
+        return state;
+    }
+    async entities(query = {}) {
+        const list = await this.requireProbe().request('entities', { radius: query.radius ?? 0, limit: query.type || query.uuid || query.name ? 0 : query.limit ?? 0, includeSelf: !!query.includeSelf }, 20_000);
+        const type = query.type ? (query.type.includes(':') ? query.type : `minecraft:${query.type}`).toLowerCase() : undefined;
+        const name = query.name?.toLowerCase();
+        let result = list.filter((e) => (!type || e.type?.toLowerCase() === type) &&
+            (!query.uuid || e.uuid === query.uuid) &&
+            (!name || (e.name ?? '').toLowerCase().includes(name) || (e.customName ?? '').toLowerCase().includes(name)));
+        if (query.limit && query.limit > 0)
+            result = result.slice(0, query.limit);
+        return result;
+    }
+    async chat(message) {
+        if (!message || message.length > 256)
+            throw new CalciteError('bad_message', 'Chat message must be 1-256 characters');
+        await this.requireProbe().request('chat', { message });
+    }
+    async command(command) {
+        if (!command.trim())
+            throw new CalciteError('bad_command', 'Command is empty');
+        await this.requireProbe().request('command', { command: command.trim() });
+    }
+    async respawn() {
+        await this.requireProbe().request('respawn');
+    }
+    // ------------------------------------------------------------------ actions
+    /** Turns the player to an absolute rotation (degrees; yaw 0 = south, pitch -90 = up) or towards a point. */
+    async look(to) {
+        return this.requireProbe().request('look', to);
+    }
+    /**
+     * Holds movement controls until changed (or for {@code ticks} game ticks, 20 per second). Pass false to release
+     * a control; {@link stop} releases all of them.
+     */
+    async move(controls, opts = {}) {
+        return this.requireProbe().request('move', { ...controls, ticks: opts.ticks ?? 0 });
+    }
+    /** Releases every control and cancels a running walkTo/dig/held use. */
+    async stopActions() {
+        await this.requireProbe().request('stop');
+    }
+    /**
+     * Walks in a straight line to (x, z), jumping over single blocks and swimming. Resolves when within
+     * {@code range} blocks, or with {@code arrived: false} when stuck (no progress for 3 s) or timed out.
+     * There is no path finding: route around obstacles with intermediate points.
+     */
+    async walkTo(x, z, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 60_000;
+        return this.requireProbe().request('walk_to', { x, z, range: opts.range ?? 0.5, sprint: opts.sprint ?? true, timeoutMs }, timeoutMs + 15_000);
+    }
+    /** Left click: attacks the entity (facing it first) or whatever the crosshair points at. */
+    async attack(entityId) {
+        return this.requireProbe().request('attack', entityId === undefined ? {} : { entityId });
+    }
+    /**
+     * Right click: interacts with an entity, a block (opening chests, pressing buttons, placing the held block
+     * against that face) or, with no target, whatever the crosshair points at / the held item in the air.
+     * {@code holdTicks} keeps the button pressed afterwards (eating, drinking, drawing a bow, shields).
+     */
+    async use(target = {}) {
+        const { block, ...rest } = target;
+        return this.requireProbe().request('use', { ...rest, ...(block ?? {}) });
+    }
+    /** Mines a block like a player (holding left click, taking the real break time). */
+    async dig(block, opts = {}) {
+        const timeoutMs = opts.timeoutMs ?? 30_000;
+        return this.requireProbe().request('dig', { ...block, timeoutMs }, timeoutMs + 15_000);
+    }
+    /** The block at a position as the client sees it. */
+    async block(pos) {
+        return this.requireProbe().request('block', { ...pos });
+    }
+    /** What the crosshair points at. */
+    async target() {
+        return this.requireProbe().request('target');
+    }
+    async inventory() {
+        return this.requireProbe().request('inventory');
+    }
+    /** Selects hotbar slot 0-8. */
+    async selectSlot(slot) {
+        return this.requireProbe().request('select_slot', { slot });
+    }
+    /** The open container (chest, furnace, villager trade, ...) or the inventory; {@code waitMs} waits for one to open. */
+    async container(opts = {}) {
+        const waitMs = opts.waitMs ?? 0;
+        return this.requireProbe().request('container', { waitMs }, waitMs + 15_000);
+    }
+    /**
+     * Clicks a slot of the open container (or the inventory). Modes: pickup (default; button 0 left, 1 right),
+     * quick_move (shift click), swap (button = hotbar slot 0-8 or 40 for the offhand), clone, throw (button 1 =
+     * whole stack), quick_craft, pickup_all. Slot -999 is outside the window.
+     */
+    async click(slot, opts = {}) {
+        return this.requireProbe().request('click', { slot, button: opts.button ?? 0, mode: opts.mode ?? 'pickup' });
+    }
+    async closeContainer() {
+        await this.requireProbe().request('close_container');
+    }
+    /** Drops one item (or the whole stack) from the selected hotbar slot. */
+    async drop(opts = {}) {
+        return this.requireProbe().request('drop', { all: !!opts.all });
+    }
+    async setRender(enabled) {
+        if (this.headless)
+            throw new CalciteError('headless', 'This client runs without a renderer');
+        await this.requireProbe().request('render', { enabled });
+    }
+    /** Takes a screenshot and returns the PNG. With {@code keep} the file stays in the game's screenshots folder. */
+    async screenshot({ keep = false } = {}) {
+        if (this.headless) {
+            throw new CalciteError('headless', this.render === 'off'
+                ? 'This client was started with render "off"; start it with render "on-demand" to take screenshots'
+                : 'Screenshots need a renderer: offline accounts can only render on Linux (Xvfb); use a Microsoft account on Windows/macOS');
+        }
+        const name = `calcite-${Date.now()}.png`;
+        const path = await this.requireProbe().request('screenshot', { name, settleFrames: 3, timeoutMs: 30_000 }, 45_000);
+        const png = await readFile(path);
+        if (keep)
+            return { path, png };
+        await rm(path, { force: true });
+        return { png };
+    }
+    logsSince(opts = {}) {
+        const contains = opts.contains?.toLowerCase();
+        const lines = this.logs.filter((l) => l.seq > (opts.since ?? 0) && (!opts.source || l.source === opts.source) && (!contains || l.line.toLowerCase().includes(contains)));
+        return opts.limit ? lines.slice(-opts.limit) : lines;
+    }
+    chatSince(since = 0, limit) {
+        const lines = this.chats.filter((c) => c.seq > since);
+        return limit ? lines.slice(-limit) : lines;
+    }
+    /**
+     * 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.
+     */
+    async waitFor(cond, timeoutMs = 30_000) {
+        const deadline = Date.now() + timeoutMs;
+        const chatRe = cond.chat ? new RegExp(cond.chat, 'i') : undefined;
+        const startSeq = this.seq;
+        for (;;) {
+            if (chatRe) {
+                const hit = this.chats.find((c) => c.seq > startSeq && chatRe.test(c.message));
+                if (hit)
+                    return { matched: 'chat', chat: hit };
+            }
+            if (cond.phase && this.phase === cond.phase)
+                return { matched: 'phase' };
+            if (cond.entity && this.probe?.connected) {
+                const { present = true, ...query } = cond.entity;
+                try {
+                    const found = await this.entities(query);
+                    if (present ? found.length > 0 : found.length === 0)
+                        return { matched: present ? 'entity_present' : 'entity_absent', entities: found };
+                }
+                catch (err) {
+                    if (!(err instanceof ProbeError) || !['not_ready', 'not_in_game'].includes(err.code))
+                        throw err;
+                }
+            }
+            if (Date.now() > deadline)
+                throw new CalciteError('timeout', `Condition not met within ${timeoutMs}ms`);
+            if (['stopped', 'crashed'].includes(this.phase))
+                throw new CalciteError('not_running', `Client stopped (phase ${this.phase})`);
+            await sleep(300);
+        }
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/display.d.ts

@@ -0,0 +1,23 @@
+export interface DisplayLease {
+    /** Environment variables the game needs (DISPLAY, software GL). */
+    env: Record<string, string>;
+    /** True when Calcite started its own Xvfb (HeadlessMC must then be told to check for it). */
+    virtual: boolean;
+    release(): void;
+}
+export declare function which(binary: string): string | null;
+/** True when a GPU device node exists (Linux); otherwise Mesa software rendering is used. */
+export declare function hasGpu(): boolean;
+/** True when a shared library (e.g. "libEGL.so.1") is present in the usual Linux library directories. */
+export declare function hasSharedLib(name: string): boolean;
+/**
+ * Provides a display for a rendering client.
+ * - Linux with DISPLAY set (desktop, or an existing Xvfb): use it.
+ * - Linux without DISPLAY: start a shared Xvfb (needs the `Xvfb` binary) with software GL when there is no GPU.
+ * - Windows / macOS: the native display is used.
+ */
+export declare function acquireDisplay(opts?: {
+    width?: number;
+    height?: number;
+    forceVirtual?: boolean;
+}): Promise<DisplayLease>;

package/dist/display.js

@@ -0,0 +1,164 @@
+import { spawn } from 'node:child_process';
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { delimiter, join } from 'node:path';
+import { logger } from './log.js';
+const log = logger('display');
+export function which(binary) {
+    for (const dir of (process.env.PATH || '').split(delimiter)) {
+        if (!dir)
+            continue;
+        const p = join(dir, binary);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/** True when a GPU device node exists (Linux); otherwise Mesa software rendering is used. */
+export function hasGpu() {
+    if (process.platform !== 'linux')
+        return true;
+    try {
+        return readdirSync('/dev/dri').some((f) => f.startsWith('renderD') || f.startsWith('card'));
+    }
+    catch {
+        return false;
+    }
+}
+const libCache = new Map();
+/** True when a shared library (e.g. "libEGL.so.1") is present in the usual Linux library directories. */
+export function hasSharedLib(name) {
+    const cached = libCache.get(name);
+    if (cached !== undefined)
+        return cached;
+    const dirs = ['/usr/lib64', '/usr/lib', '/lib64', '/lib', '/usr/local/lib'];
+    for (const base of ['/usr/lib', '/lib']) {
+        try {
+            for (const d of readdirSync(base))
+                if (/-linux-gnu/.test(d))
+                    dirs.push(join(base, d));
+        }
+        catch {
+            // not there
+        }
+    }
+    const found = dirs.some((d) => existsSync(join(d, name)));
+    libCache.set(name, found);
+    return found;
+}
+function softwareGlEnv() {
+    return hasGpu() ? {} : { LIBGL_ALWAYS_SOFTWARE: '1', GALLIUM_DRIVER: 'llvmpipe' };
+}
+/**
+ * Environment for a virtual (Xvfb) display. Minecraft 26.x renders through SDL3 and asks for an sRGB-capable
+ * framebuffer, which Xvfb's GLX never offers; SDL's EGL path provides it. Older versions use GLFW and ignore this.
+ */
+function virtualDisplayEnv() {
+    return { ...softwareGlEnv(), ...(hasSharedLib('libEGL.so.1') ? { SDL_VIDEO_FORCE_EGL: '1' } : {}) };
+}
+let shared = null;
+/** Display numbers in use, including X servers that only listen on an abstract socket (no lock or socket file). */
+function displaysInUse() {
+    const used = new Set();
+    try {
+        for (const m of readFileSync('/proc/net/unix', 'utf8').matchAll(/@?\/tmp\/\.X11-unix\/X(\d+)/g))
+            used.add(Number(m[1]));
+    }
+    catch {
+        // no procfs
+    }
+    return used;
+}
+function freeDisplayNumber(skip) {
+    const used = displaysInUse();
+    for (let n = 99; n < 199; n++) {
+        if (skip.has(n) || used.has(n))
+            continue;
+        if (!existsSync(`/tmp/.X11-unix/X${n}`) && !existsSync(`/tmp/.X${n}-lock`))
+            return n;
+    }
+    throw new Error('No free X display number between :99 and :198');
+}
+async function waitFor(check, timeoutMs) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (check())
+            return true;
+        await new Promise((r) => setTimeout(r, 100));
+    }
+    return check();
+}
+/**
+ * Provides a display for a rendering client.
+ * - Linux with DISPLAY set (desktop, or an existing Xvfb): use it.
+ * - Linux without DISPLAY: start a shared Xvfb (needs the `Xvfb` binary) with software GL when there is no GPU.
+ * - Windows / macOS: the native display is used.
+ */
+export async function acquireDisplay(opts = {}) {
+    if (process.platform !== 'linux') {
+        return { env: {}, virtual: false, release() { } };
+    }
+    if (process.env.DISPLAY && !opts.forceVirtual) {
+        const virtual = /xvfb/i.test(process.env.CALCITE_DISPLAY_KIND || '');
+        return { env: { DISPLAY: process.env.DISPLAY, ...(virtual ? virtualDisplayEnv() : softwareGlEnv()) }, virtual, release() { } };
+    }
+    if (!shared || shared.proc.exitCode !== null) {
+        const xvfb = which('Xvfb');
+        if (!xvfb) {
+            throw new Error('Rendering on a Linux machine without a display needs Xvfb and Mesa: apt-get install -y xvfb libgl1-mesa-dri libegl1 libegl-mesa0 (or run with --render off)');
+        }
+        const width = opts.width ?? 1280;
+        const height = opts.height ?? 720;
+        // a display may still be taken without leaving traces we can see; Xvfb then exits and the next number is tried
+        const tried = new Set();
+        let n = 0;
+        let proc;
+        for (let attempt = 0; attempt < 5 && !proc; attempt++) {
+            n = freeDisplayNumber(tried);
+            tried.add(n);
+            const candidate = spawn(xvfb, [`:${n}`, '-screen', '0', `${width}x${height}x24`, '-nolisten', 'tcp'], {
+                stdio: 'ignore',
+                detached: false,
+            });
+            candidate.unref();
+            await waitFor(() => existsSync(`/tmp/.X11-unix/X${n}`) || candidate.exitCode !== null, 10_000);
+            if (candidate.exitCode === null && existsSync(`/tmp/.X11-unix/X${n}`))
+                proc = candidate;
+            else {
+                candidate.kill();
+                log.debug(`Xvfb :${n} did not start, trying another display`);
+            }
+        }
+        if (!proc)
+            throw new Error(`Xvfb failed to start (tried displays ${[...tried].map((d) => `:${d}`).join(', ')})`);
+        log.info(`started Xvfb :${n} (${width}x${height})`);
+        const xvfbProc = proc;
+        shared = { proc: xvfbProc, display: `:${n}`, refs: 0 };
+        const cleanup = () => {
+            try {
+                xvfbProc.kill();
+            }
+            catch {
+                // already gone
+            }
+        };
+        process.once('exit', cleanup);
+    }
+    const lease = shared;
+    lease.refs++;
+    let released = false;
+    return {
+        env: { DISPLAY: lease.display, ...virtualDisplayEnv() },
+        virtual: true,
+        release() {
+            if (released)
+                return;
+            released = true;
+            lease.refs--;
+            if (lease.refs <= 0 && shared === lease) {
+                lease.proc.kill();
+                shared = null;
+            }
+        },
+    };
+}
+//# sourceMappingURL=display.js.map

package/dist/display.js.map

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

package/dist/hmc.d.ts

@@ -0,0 +1,53 @@
+import { type ChildProcess } from 'node:child_process';
+import type { CalcitePaths } from './paths.js';
+/** Pinned HeadlessMC release (MIT, https://github.com/headlesshq/headlessmc). */
+export declare const HMC_VERSION = "3.0.0-RC3";
+export declare const HMC_URL = "https://github.com/headlesshq/headlessmc/releases/download/3.0.0-RC3/headlessmc.jar";
+export declare const HMC_SHA256 = "dcc061a336ecf7aa638794bd47840fa9970b31d562e630e84c3d587c906153a8";
+/** Path of the HeadlessMC jar (CALCITE_HMC_JAR overrides the pinned download). */
+export declare function ensureHmc(paths: CalcitePaths): Promise<string>;
+/** Escapes one entry of a comma separated HeadlessMC list setting. */
+export declare function hmcListEntry(value: string): string;
+/** Quotes one argument for HeadlessMC's `--jvm`/`--game` options, which are split like a shell command line. */
+export declare function hmcQuote(arg: string): string;
+/**
+ * Writes the HeadlessMC profile used when launching `versionId` from `location`. HeadlessMC only runs a version
+ * with the exact Java major the version asks for; the profile pins the runtime Calcite chose instead. With a
+ * {@code loader} the profile selects that platform (fabric, forge, neoforge) and build for Minecraft {@code versionId}.
+ */
+export declare function writeHmcProfile(location: string, versionId: string, gameDir: string, javaMajor: number, loader?: {
+    kind: string;
+    build?: string;
+}): Promise<void>;
+/**
+ * HeadlessMC's version argument: "1.21.11", or "fabric 1.21.11 0.19.5" for a mod loader. HeadlessMC names NeoForge
+ * builds without the Minecraft part of their version (NeoForge 21.11.45 for 1.21.11 is build "45").
+ */
+export declare function hmcVersionArgs(versionId: string, loader?: {
+    kind: string;
+    build?: string;
+}): string[];
+export interface HmcRun {
+    child: ChildProcess;
+    /** Resolves with the exit code when the HeadlessMC process exits. */
+    exited: Promise<number | null>;
+}
+export interface HmcRunOptions {
+    javaPath: string;
+    hmcJar: string;
+    /** HeadlessMC files location (config, accounts, caches) of this run. */
+    location: string;
+    /** hmc.* (and other) system properties for this run. */
+    props?: Record<string, string>;
+    /** HeadlessMC command line, e.g. ["launch", "1.21.11", "--headless"]. */
+    command: string[];
+    env?: NodeJS.ProcessEnv;
+    onLine?: (line: string) => void;
+}
+/**
+ * Runs one HeadlessMC command non-interactively; HeadlessMC exits once the command (and a launched game) finished.
+ * Settings are passed as -D system properties, which take precedence over any config file.
+ */
+export declare function runHmc(opts: HmcRunOptions): HmcRun;
+/** Stops a process tree started by {@link runHmc}. */
+export declare function killTree(child: ChildProcess, graceMs?: number): Promise<void>;