cyclops-clientdevbridge-cli 0.1.1

package/dist/loopback.js

@@ -0,0 +1,19 @@
+/**
+ * The loopback addresses a ClientDevBridge client may be listening on.
+ *
+ * 127.0.0.1 is what the mod binds, and the only address it has ever meant to bind. But a client
+ * built before that was made explicit calls `InetAddress.getLoopbackAddress()`, and NeoForge's dev
+ * run configuration passes `-Djava.net.preferIPv6Addresses=system`, under which the JDK answers
+ * `::1` on any machine that has `::1` bound. Such a client is perfectly healthy and completely
+ * unreachable on 127.0.0.1, so the CLI tries both rather than making the two versions move
+ * together.
+ *
+ * IPv4 comes first: it is the normal case, and trying it first keeps the usual error message the
+ * IPv4 one.
+ */
+export const LOOPBACK_HOSTS = ['127.0.0.1', '::1'];
+/** Wraps an IPv6 literal in the brackets a URL authority needs; IPv4 passes through. */
+export function urlHost(host) {
+    return host.includes(':') ? `[${host}]` : host;
+}
+//# sourceMappingURL=loopback.js.map

package/dist/loopback.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"loopback.js","sourceRoot":"","sources":["../src/loopback.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,WAAW,EAAE,KAAK,CAAU,CAAC;AAE5D,wFAAwF;AACxF,MAAM,UAAU,OAAO,CAAC,IAAY;IAClC,OAAO,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,GAAG,CAAC,CAAC,CAAC,IAAI,CAAC;AACjD,CAAC"}

package/dist/output.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Output conventions (plan §5), in one place so every command obeys them.
+ *
+ * - Default output is text meant to be read by a human or an agent; `--json` prints the raw
+ *   protocol result instead.
+ * - Images are never printed. A screenshot writes a file and prints its absolute path on its
+ *   own line, so an agent can hand that path straight to a file-reading tool.
+ */
+export interface OutputOptions {
+    readonly json: boolean;
+    readonly quiet: boolean;
+}
+export declare function printJson(value: unknown): void;
+export declare function line(text?: string): void;
+/** Prints a path on its own line, which is the contract for every file the CLI produces. */
+export declare function printPath(absolutePath: string): void;
+export declare function warn(text: string): void;
+export declare function keyValues(entries: readonly (readonly [string, unknown])[]): void;
+/** Renders a duration the way a person reads it, for `status`. */
+export declare function formatDuration(ms: number): string;
+//# sourceMappingURL=output.d.ts.map

package/dist/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,CAE9C;AAED,wBAAgB,IAAI,CAAC,IAAI,SAAK,GAAG,IAAI,CAEpC;AAED,4FAA4F;AAC5F,wBAAgB,SAAS,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAEpD;AAED,wBAAgB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAEvC;AAED,wBAAgB,SAAS,CAAC,OAAO,EAAE,SAAS,CAAC,SAAS,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,GAAG,IAAI,CAKhF;AAYD,kEAAkE;AAClE,wBAAgB,cAAc,CAAC,EAAE,EAAE,MAAM,GAAG,MAAM,CAUjD"}

package/dist/output.js

@@ -0,0 +1,41 @@
+export function printJson(value) {
+    process.stdout.write(`${JSON.stringify(value, null, 2)}\n`);
+}
+export function line(text = '') {
+    process.stdout.write(`${text}\n`);
+}
+/** Prints a path on its own line, which is the contract for every file the CLI produces. */
+export function printPath(absolutePath) {
+    process.stdout.write(`${absolutePath}\n`);
+}
+export function warn(text) {
+    process.stderr.write(`warning: ${text}\n`);
+}
+export function keyValues(entries) {
+    const width = Math.max(...entries.map(([key]) => key.length));
+    for (const [key, value] of entries) {
+        line(`${key.padEnd(width)}  ${formatValue(value)}`);
+    }
+}
+function formatValue(value) {
+    if (value === null || value === undefined) {
+        return '-';
+    }
+    if (Array.isArray(value)) {
+        return value.length === 0 ? '-' : value.join(', ');
+    }
+    return String(value);
+}
+/** Renders a duration the way a person reads it, for `status`. */
+export function formatDuration(ms) {
+    const seconds = Math.floor(ms / 1000);
+    if (seconds < 60) {
+        return `${seconds}s`;
+    }
+    const minutes = Math.floor(seconds / 60);
+    if (minutes < 60) {
+        return `${minutes}m ${seconds % 60}s`;
+    }
+    return `${Math.floor(minutes / 60)}h ${minutes % 60}m`;
+}
+//# sourceMappingURL=output.js.map

package/dist/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../src/output.ts"],"names":[],"mappings":"AAaA,MAAM,UAAU,SAAS,CAAC,KAAc;IACtC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,EAAE,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC;AAC9D,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAI,GAAG,EAAE;IAC5B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,IAAI,IAAI,CAAC,CAAC;AACpC,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,SAAS,CAAC,YAAoB;IAC5C,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,GAAG,YAAY,IAAI,CAAC,CAAC;AAC5C,CAAC;AAED,MAAM,UAAU,IAAI,CAAC,IAAY;IAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,YAAY,IAAI,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED,MAAM,UAAU,SAAS,CAAC,OAAgD;IACxE,MAAM,KAAK,GAAG,IAAI,CAAC,GAAG,CAAC,GAAG,OAAO,CAAC,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,EAAE,EAAE,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,CAAC;IAC9D,KAAK,MAAM,CAAC,GAAG,EAAE,KAAK,CAAC,IAAI,OAAO,EAAE,CAAC;QACnC,IAAI,CAAC,GAAG,GAAG,CAAC,MAAM,CAAC,KAAK,CAAC,KAAK,WAAW,CAAC,KAAK,CAAC,EAAE,CAAC,CAAC;IACtD,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAc;IACjC,IAAI,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EAAE,CAAC;QAC1C,OAAO,GAAG,CAAC;IACb,CAAC;IACD,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC,EAAE,CAAC;QACzB,OAAO,KAAK,CAAC,MAAM,KAAK,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,MAAM,CAAC,KAAK,CAAC,CAAC;AACvB,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,cAAc,CAAC,EAAU;IACvC,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,EAAE,GAAG,IAAI,CAAC,CAAC;IACtC,IAAI,OAAO,GAAG,EAAE,EAAE,CAAC;QACjB,OAAO,GAAG,OAAO,GAAG,CAAC;IACvB,CAAC;IACD,MAAM,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,CAAC;IACzC,IAAI,OAAO,GAAG,EAAE,EAAE,CAAC;QACjB,OAAO,GAAG,OAAO,KAAK,OAAO,GAAG,EAAE,GAAG,CAAC;IACxC,CAAC;IACD,OAAO,GAAG,IAAI,CAAC,KAAK,CAAC,OAAO,GAAG,EAAE,CAAC,KAAK,OAAO,GAAG,EAAE,GAAG,CAAC;AACzD,CAAC"}

package/dist/paths.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Everything a session writes lives under `<projectDir>/.clientdevbridge/`, so that a
+ * session is discoverable from a cold shell and disappears with the checkout.
+ */
+export interface BridgePaths {
+    readonly projectDir: string;
+    readonly root: string;
+    readonly sessionFile: string;
+    readonly gradleLog: string;
+    readonly screenshots: string;
+    readonly golden: string;
+    readonly diffs: string;
+    readonly initScript: string;
+    readonly hotswapState: string;
+}
+export declare function resolvePaths(projectDir: string): BridgePaths;
+export declare function ensureDirectories(paths: BridgePaths): void;
+/**
+ * The generated session state is disposable, but golden images are committed alongside the
+ * consumer's code, so only the rest is ignored. Idempotent: re-running never duplicates the block.
+ */
+export declare function ensureGitignore(paths: BridgePaths): boolean;
+//# sourceMappingURL=paths.d.ts.map

package/dist/paths.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.d.ts","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED,wBAAgB,YAAY,CAAC,UAAU,EAAE,MAAM,GAAG,WAAW,CAc5D;AAED,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAI1D;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,WAAW,GAAG,OAAO,CAoB3D"}

package/dist/paths.js

@@ -0,0 +1,47 @@
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+export function resolvePaths(projectDir) {
+    const resolved = path.resolve(projectDir);
+    const root = path.join(resolved, '.clientdevbridge');
+    return {
+        projectDir: resolved,
+        root,
+        sessionFile: path.join(root, 'session.json'),
+        gradleLog: path.join(root, 'gradle.log'),
+        screenshots: path.join(root, 'screenshots'),
+        golden: path.join(root, 'golden'),
+        diffs: path.join(root, 'diffs'),
+        initScript: path.join(root, 'init.gradle'),
+        hotswapState: path.join(root, 'hotswap'),
+    };
+}
+export function ensureDirectories(paths) {
+    for (const dir of [paths.root, paths.screenshots, paths.golden, paths.diffs, paths.hotswapState]) {
+        fs.mkdirSync(dir, { recursive: true });
+    }
+}
+/**
+ * The generated session state is disposable, but golden images are committed alongside the
+ * consumer's code, so only the rest is ignored. Idempotent: re-running never duplicates the block.
+ */
+export function ensureGitignore(paths) {
+    const gitignorePath = path.join(paths.projectDir, '.gitignore');
+    const marker = '# ClientDevBridge session state (golden images are intentionally kept)';
+    const block = [
+        marker,
+        '.clientdevbridge/*',
+        '!.clientdevbridge/golden/',
+        '',
+    ].join('\n');
+    let existing = '';
+    if (fs.existsSync(gitignorePath)) {
+        existing = fs.readFileSync(gitignorePath, 'utf8');
+        if (existing.includes(marker)) {
+            return false;
+        }
+    }
+    const separator = existing.length > 0 && !existing.endsWith('\n') ? '\n' : '';
+    fs.writeFileSync(gitignorePath, `${existing}${separator}${existing.length > 0 ? '\n' : ''}${block}`, 'utf8');
+    return true;
+}
+//# sourceMappingURL=paths.js.map

package/dist/paths.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"paths.js","sourceRoot":"","sources":["../src/paths.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,SAAS,CAAC;AAC9B,OAAO,KAAK,IAAI,MAAM,WAAW,CAAC;AAkBlC,MAAM,UAAU,YAAY,CAAC,UAAkB;IAC7C,MAAM,QAAQ,GAAG,IAAI,CAAC,OAAO,CAAC,UAAU,CAAC,CAAC;IAC1C,MAAM,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,QAAQ,EAAE,kBAAkB,CAAC,CAAC;IACrD,OAAO;QACL,UAAU,EAAE,QAAQ;QACpB,IAAI;QACJ,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,cAAc,CAAC;QAC5C,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,YAAY,CAAC;QACxC,WAAW,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QAC3C,MAAM,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC;QACjC,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC;QAC/B,UAAU,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,aAAa,CAAC;QAC1C,YAAY,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,SAAS,CAAC;KACzC,CAAC;AACJ,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,KAAkB;IAClD,KAAK,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,KAAK,CAAC,WAAW,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,KAAK,CAAC,YAAY,CAAC,EAAE,CAAC;QACjG,EAAE,CAAC,SAAS,CAAC,GAAG,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAC;IACzC,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,eAAe,CAAC,KAAkB;IAChD,MAAM,aAAa,GAAG,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;IAChE,MAAM,MAAM,GAAG,wEAAwE,CAAC;IACxF,MAAM,KAAK,GAAG;QACZ,MAAM;QACN,oBAAoB;QACpB,2BAA2B;QAC3B,EAAE;KACH,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAEb,IAAI,QAAQ,GAAG,EAAE,CAAC;IAClB,IAAI,EAAE,CAAC,UAAU,CAAC,aAAa,CAAC,EAAE,CAAC;QACjC,QAAQ,GAAG,EAAE,CAAC,YAAY,CAAC,aAAa,EAAE,MAAM,CAAC,CAAC;QAClD,IAAI,QAAQ,CAAC,QAAQ,CAAC,MAAM,CAAC,EAAE,CAAC;YAC9B,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC;IACD,MAAM,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC;IAC9E,EAAE,CAAC,aAAa,CAAC,aAAa,EAAE,GAAG,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,GAAG,KAAK,EAAE,EAAE,MAAM,CAAC,CAAC;IAC7G,OAAO,IAAI,CAAC;AACd,CAAC"}

package/dist/protocol/client.d.ts

@@ -0,0 +1,35 @@
+import { type Hello } from './types.js';
+export type NotificationListener = (method: string, params: Record<string, unknown>) => void;
+export interface ConnectOptions {
+    readonly port: number;
+    readonly timeoutMs?: number;
+    readonly onNotification?: NotificationListener;
+}
+/**
+ * A JSON-RPC 2.0 client over the mod's localhost WebSocket.
+ *
+ * One instance per CLI invocation: connect, do one thing, close.
+ */
+export declare class BridgeClient {
+    private readonly socket;
+    private readonly pending;
+    private readonly listeners;
+    private nextId;
+    private closedReason;
+    readonly hello: Hello;
+    private constructor();
+    /**
+     * Connects to the client on this port, over whichever loopback address it is listening on.
+     *
+     * The first address that answers wins. When none does, the failure reported is the one from
+     * 127.0.0.1: that is where a client is supposed to be, so it is the message that helps.
+     */
+    static connect(options: ConnectOptions): Promise<BridgeClient>;
+    private static connectTo;
+    onNotification(listener: NotificationListener): void;
+    call<T = unknown>(method: string, params?: Record<string, unknown>, timeoutMs?: number): Promise<T>;
+    private onMessage;
+    private failAll;
+    close(): void;
+}
+//# sourceMappingURL=client.d.ts.map

package/dist/protocol/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/protocol/client.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,KAAK,KAAK,EAA6E,MAAM,YAAY,CAAC;AAEnH,MAAM,MAAM,oBAAoB,GAAG,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,KAAK,IAAI,CAAC;AAE7F,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,cAAc,CAAC,EAAE,oBAAoB,CAAC;CAChD;AAOD;;;;GAIG;AACH,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAY;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAA8B;IACtD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA8B;IACxD,OAAO,CAAC,MAAM,CAAK;IACnB,OAAO,CAAC,YAAY,CAAuB;IAE3C,SAAgB,KAAK,EAAE,KAAK,CAAC;IAE7B,OAAO;IAQP;;;;;OAKG;WACiB,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,YAAY,CAAC;mBAYtD,SAAS;IAyEvB,cAAc,CAAC,QAAQ,EAAE,oBAAoB,GAAG,IAAI;IAI9C,IAAI,CAAC,CAAC,GAAG,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,EAAE,SAAS,SAAU,GAAG,OAAO,CAAC,CAAC,CAAC;IA2BrH,OAAO,CAAC,SAAS;IAiCjB,OAAO,CAAC,OAAO;IAQR,KAAK,IAAI,IAAI;CAIrB"}

package/dist/protocol/client.js

@@ -0,0 +1,170 @@
+import WebSocket from 'ws';
+import { ProtocolError, SessionError } from '../errors.js';
+import { LOOPBACK_HOSTS, urlHost } from '../loopback.js';
+import { helloSchema, rpcNotificationSchema, rpcResponseSchema, SUPPORTED_PROTOCOL } from './types.js';
+/**
+ * A JSON-RPC 2.0 client over the mod's localhost WebSocket.
+ *
+ * One instance per CLI invocation: connect, do one thing, close.
+ */
+export class BridgeClient {
+    socket;
+    pending = new Map();
+    listeners = [];
+    nextId = 1;
+    closedReason = null;
+    hello;
+    constructor(socket, hello) {
+        this.socket = socket;
+        this.hello = hello;
+        socket.on('message', (raw) => this.onMessage(String(raw)));
+        socket.on('close', () => this.failAll('The client closed the connection.'));
+        socket.on('error', (error) => this.failAll(`Connection error: ${error.message}`));
+    }
+    /**
+     * Connects to the client on this port, over whichever loopback address it is listening on.
+     *
+     * The first address that answers wins. When none does, the failure reported is the one from
+     * 127.0.0.1: that is where a client is supposed to be, so it is the message that helps.
+     */
+    static async connect(options) {
+        let first;
+        for (const host of LOOPBACK_HOSTS) {
+            try {
+                return await BridgeClient.connectTo(host, options);
+            }
+            catch (error) {
+                first ??= error;
+            }
+        }
+        throw first;
+    }
+    static async connectTo(host, options) {
+        const timeoutMs = options.timeoutMs ?? 15_000;
+        const url = `ws://${urlHost(host)}:${options.port}`;
+        const socket = new WebSocket(url, { handshakeTimeout: timeoutMs });
+        const early = [];
+        const hello = await new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                socket.terminate();
+                reject(new SessionError(`Timed out after ${timeoutMs} ms waiting for the ClientDevBridge handshake on ${url}.`));
+            }, timeoutMs);
+            socket.once('error', (error) => {
+                clearTimeout(timer);
+                const reason = error.code === 'ECONNREFUSED'
+                    ? `Nothing is listening on ${url}.`
+                    : `Could not connect to ${url}: ${error.message}`;
+                reject(new SessionError(reason));
+            });
+            socket.on('message', function onMessage(raw) {
+                let parsed;
+                try {
+                    parsed = JSON.parse(String(raw));
+                }
+                catch {
+                    return;
+                }
+                const notification = rpcNotificationSchema.safeParse(parsed);
+                if (!notification.success) {
+                    return;
+                }
+                if (notification.data.method !== 'hello') {
+                    early.push({ method: notification.data.method, params: notification.data.params });
+                    return;
+                }
+                socket.off('message', onMessage);
+                clearTimeout(timer);
+                const helloResult = helloSchema.safeParse(notification.data.params);
+                if (!helloResult.success) {
+                    reject(new SessionError(`The client sent a handshake this CLI cannot read: ${helloResult.error.message}`));
+                    return;
+                }
+                resolve(helloResult.data);
+            });
+        });
+        if (hello.protocol !== SUPPORTED_PROTOCOL) {
+            socket.close();
+            const direction = hello.protocol > SUPPORTED_PROTOCOL ? 'update the CLI' : 'update the mod';
+            throw new SessionError(`Protocol mismatch: this CLI speaks protocol ${SUPPORTED_PROTOCOL}, the ClientDevBridge mod speaks ${hello.protocol}. Please ${direction}.`, hello.protocol > SUPPORTED_PROTOCOL
+                ? 'npm install -g cyclops-clientdevbridge-cli@latest'
+                : 'Rebuild the ClientDevBridge mod, or pass --clientdevbridge-version to pick a matching build.');
+        }
+        const client = new BridgeClient(socket, hello);
+        if (options.onNotification !== undefined) {
+            client.onNotification(options.onNotification);
+            for (const notification of early) {
+                options.onNotification(notification.method, notification.params);
+            }
+        }
+        return client;
+    }
+    onNotification(listener) {
+        this.listeners.push(listener);
+    }
+    async call(method, params = {}, timeoutMs = 120_000) {
+        if (this.closedReason !== null) {
+            throw new SessionError(this.closedReason);
+        }
+        const id = this.nextId++;
+        const message = JSON.stringify({ jsonrpc: '2.0', id, method, params });
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new SessionError(`'${method}' did not answer within ${timeoutMs} ms.`));
+            }, timeoutMs);
+            this.pending.set(id, {
+                resolve: (value) => {
+                    clearTimeout(timer);
+                    resolve(value);
+                },
+                reject: (error) => {
+                    clearTimeout(timer);
+                    reject(error);
+                },
+            });
+            this.socket.send(message);
+        });
+    }
+    onMessage(raw) {
+        let parsed;
+        try {
+            parsed = JSON.parse(raw);
+        }
+        catch {
+            return;
+        }
+        const response = rpcResponseSchema.safeParse(parsed);
+        if (response.success && response.data.id !== null) {
+            const pending = this.pending.get(Number(response.data.id));
+            if (pending === undefined) {
+                return;
+            }
+            this.pending.delete(Number(response.data.id));
+            if (response.data.error !== undefined) {
+                pending.reject(new ProtocolError(response.data.error.code, response.data.error.message, response.data.error.data));
+            }
+            else {
+                pending.resolve(response.data.result ?? {});
+            }
+            return;
+        }
+        const notification = rpcNotificationSchema.safeParse(parsed);
+        if (notification.success) {
+            for (const listener of this.listeners) {
+                listener(notification.data.method, notification.data.params);
+            }
+        }
+    }
+    failAll(reason) {
+        this.closedReason = reason;
+        for (const pending of this.pending.values()) {
+            pending.reject(new SessionError(reason));
+        }
+        this.pending.clear();
+    }
+    close() {
+        this.closedReason = this.closedReason ?? 'Connection closed by the CLI.';
+        this.socket.close();
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/protocol/client.js.map

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

package/dist/protocol/types.d.ts

@@ -0,0 +1,114 @@
+import { z } from 'zod';
+/** The protocol version this CLI speaks. Bumped only by a breaking change landed on every branch. */
+export declare const SUPPORTED_PROTOCOL = 1;
+export declare const helloSchema: z.ZodObject<{
+    protocol: z.ZodNumber;
+    mcVersion: z.ZodString;
+    loader: z.ZodString;
+    clientDevBridgeVersion: z.ZodString;
+    evalEnabled: z.ZodOptional<z.ZodBoolean>;
+    /** The project this client was launched for; absent on an older bridge build. */
+    projectDir: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    mods: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    protocol: number;
+    mcVersion: string;
+    loader: string;
+    clientDevBridgeVersion: string;
+    mods: string[];
+    evalEnabled?: boolean | undefined;
+    projectDir?: string | null | undefined;
+}, {
+    protocol: number;
+    mcVersion: string;
+    loader: string;
+    clientDevBridgeVersion: string;
+    evalEnabled?: boolean | undefined;
+    projectDir?: string | null | undefined;
+    mods?: string[] | undefined;
+}>;
+export type Hello = z.infer<typeof helloSchema>;
+export declare const rpcErrorSchema: z.ZodObject<{
+    code: z.ZodNumber;
+    message: z.ZodString;
+    data: z.ZodOptional<z.ZodUnknown>;
+}, "strip", z.ZodTypeAny, {
+    code: number;
+    message: string;
+    data?: unknown;
+}, {
+    code: number;
+    message: string;
+    data?: unknown;
+}>;
+export declare const rpcResponseSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    id: z.ZodUnion<[z.ZodNumber, z.ZodString, z.ZodNull]>;
+    result: z.ZodOptional<z.ZodUnknown>;
+    error: z.ZodOptional<z.ZodObject<{
+        code: z.ZodNumber;
+        message: z.ZodString;
+        data: z.ZodOptional<z.ZodUnknown>;
+    }, "strip", z.ZodTypeAny, {
+        code: number;
+        message: string;
+        data?: unknown;
+    }, {
+        code: number;
+        message: string;
+        data?: unknown;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    } | undefined;
+}, {
+    jsonrpc: "2.0";
+    id: string | number | null;
+    result?: unknown;
+    error?: {
+        code: number;
+        message: string;
+        data?: unknown;
+    } | undefined;
+}>;
+export declare const rpcNotificationSchema: z.ZodObject<{
+    jsonrpc: z.ZodLiteral<"2.0">;
+    method: z.ZodString;
+    params: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, "strip", z.ZodTypeAny, {
+    params: Record<string, unknown>;
+    jsonrpc: "2.0";
+    method: string;
+}, {
+    jsonrpc: "2.0";
+    method: string;
+    params?: Record<string, unknown> | undefined;
+}>;
+/** The metrics block every screenshot and snapshot result carries. */
+export declare const metricsSchema: z.ZodObject<{
+    guiScale: z.ZodNumber;
+    guiWidth: z.ZodNumber;
+    guiHeight: z.ZodNumber;
+    pixelWidth: z.ZodNumber;
+    pixelHeight: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    guiScale: number;
+    guiWidth: number;
+    guiHeight: number;
+    pixelWidth: number;
+    pixelHeight: number;
+}, {
+    guiScale: number;
+    guiWidth: number;
+    guiHeight: number;
+    pixelWidth: number;
+    pixelHeight: number;
+}>;
+export type Metrics = z.infer<typeof metricsSchema>;
+//# sourceMappingURL=types.d.ts.map

package/dist/protocol/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/protocol/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qGAAqG;AACrG,eAAO,MAAM,kBAAkB,IAAI,CAAC;AAEpC,eAAO,MAAM,WAAW;;;;;;IAMtB,iFAAiF;;;;;;;;;;;;;;;;;;;EAGjF,CAAC;AAEH,MAAM,MAAM,KAAK,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,WAAW,CAAC,CAAC;AAEhD,eAAO,MAAM,cAAc;;;;;;;;;;;;EAIzB,CAAC;AAEH,eAAO,MAAM,iBAAiB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAK5B,CAAC;AAEH,eAAO,MAAM,qBAAqB;;;;;;;;;;;;EAIhC,CAAC;AAEH,sEAAsE;AACtE,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;;;;EAMxB,CAAC;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC"}

package/dist/protocol/types.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+/** The protocol version this CLI speaks. Bumped only by a breaking change landed on every branch. */
+export const SUPPORTED_PROTOCOL = 1;
+export const helloSchema = z.object({
+    protocol: z.number().int(),
+    mcVersion: z.string(),
+    loader: z.string(),
+    clientDevBridgeVersion: z.string(),
+    evalEnabled: z.boolean().optional(),
+    /** The project this client was launched for; absent on an older bridge build. */
+    projectDir: z.string().nullish(),
+    mods: z.array(z.string()).default([]),
+});
+export const rpcErrorSchema = z.object({
+    code: z.number().int(),
+    message: z.string(),
+    data: z.unknown().optional(),
+});
+export const rpcResponseSchema = z.object({
+    jsonrpc: z.literal('2.0'),
+    id: z.union([z.number(), z.string(), z.null()]),
+    result: z.unknown().optional(),
+    error: rpcErrorSchema.optional(),
+});
+export const rpcNotificationSchema = z.object({
+    jsonrpc: z.literal('2.0'),
+    method: z.string(),
+    params: z.record(z.unknown()).default({}),
+});
+/** The metrics block every screenshot and snapshot result carries. */
+export const metricsSchema = z.object({
+    guiScale: z.number(),
+    guiWidth: z.number(),
+    guiHeight: z.number(),
+    pixelWidth: z.number(),
+    pixelHeight: z.number(),
+});
+//# sourceMappingURL=types.js.map

package/dist/protocol/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/protocol/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,qGAAqG;AACrG,MAAM,CAAC,MAAM,kBAAkB,GAAG,CAAC,CAAC;AAEpC,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,CAAC,MAAM,CAAC;IAClC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IAC1B,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,sBAAsB,EAAE,CAAC,CAAC,MAAM,EAAE;IAClC,WAAW,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IACnC,iFAAiF;IACjF,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE;IAChC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CACtC,CAAC,CAAC;AAIH,MAAM,CAAC,MAAM,cAAc,GAAG,CAAC,CAAC,MAAM,CAAC;IACrC,IAAI,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;IACtB,OAAO,EAAE,CAAC,CAAC,MAAM,EAAE;IACnB,IAAI,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;CAC7B,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,iBAAiB,GAAG,CAAC,CAAC,MAAM,CAAC;IACxC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACzB,EAAE,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC;IAC/C,MAAM,EAAE,CAAC,CAAC,OAAO,EAAE,CAAC,QAAQ,EAAE;IAC9B,KAAK,EAAE,cAAc,CAAC,QAAQ,EAAE;CACjC,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,qBAAqB,GAAG,CAAC,CAAC,MAAM,CAAC;IAC5C,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;IACzB,MAAM,EAAE,CAAC,CAAC,MAAM,EAAE;IAClB,MAAM,EAAE,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,OAAO,EAAE,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC;CAC1C,CAAC,CAAC;AAEH,sEAAsE;AACtE,MAAM,CAAC,MAAM,aAAa,GAAG,CAAC,CAAC,MAAM,CAAC;IACpC,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,QAAQ,EAAE,CAAC,CAAC,MAAM,EAAE;IACpB,SAAS,EAAE,CAAC,CAAC,MAAM,EAAE;IACrB,UAAU,EAAE,CAAC,CAAC,MAAM,EAAE;IACtB,WAAW,EAAE,CAAC,CAAC,MAAM,EAAE;CACxB,CAAC,CAAC"}

package/dist/session.d.ts

@@ -0,0 +1,77 @@
+import { z } from 'zod';
+import { type BridgePaths } from './paths.js';
+export declare const sessionSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    port: z.ZodNumber;
+    pid: z.ZodNumber;
+    pgid: z.ZodNumber;
+    loader: z.ZodEnum<["fabric", "neoforge"]>;
+    mcVersion: z.ZodString;
+    bridgeVersion: z.ZodString;
+    projectDir: z.ZodString;
+    gradleTask: z.ZodString;
+    startedAt: z.ZodString;
+    world: z.ZodNullable<z.ZodString>;
+    headed: z.ZodBoolean;
+    display: z.ZodNullable<z.ZodString>;
+    jdwpPort: z.ZodNullable<z.ZodNumber>;
+    /**
+     * Xvfb servers this launch started. `stop` kills them explicitly: killing the process group
+     * does not reliably take them with it, and a leaked one is not harmless -- a stale server on a
+     * display a later run reuses makes the next client die with an X GLX BadAccess before it
+     * renders anything. Optional so a session file written by an older CLI still parses.
+     */
+    xvfbPids: z.ZodOptional<z.ZodArray<z.ZodNumber, "many">>;
+}, "strip", z.ZodTypeAny, {
+    mcVersion: string;
+    loader: "fabric" | "neoforge";
+    projectDir: string;
+    version: 1;
+    port: number;
+    pid: number;
+    pgid: number;
+    bridgeVersion: string;
+    gradleTask: string;
+    startedAt: string;
+    world: string | null;
+    headed: boolean;
+    display: string | null;
+    jdwpPort: number | null;
+    xvfbPids?: number[] | undefined;
+}, {
+    mcVersion: string;
+    loader: "fabric" | "neoforge";
+    projectDir: string;
+    version: 1;
+    port: number;
+    pid: number;
+    pgid: number;
+    bridgeVersion: string;
+    gradleTask: string;
+    startedAt: string;
+    world: string | null;
+    headed: boolean;
+    display: string | null;
+    jdwpPort: number | null;
+    xvfbPids?: number[] | undefined;
+}>;
+export type Session = z.infer<typeof sessionSchema>;
+export interface SessionStatus {
+    readonly paths: BridgePaths;
+    readonly session: Session | null;
+    /** True when session.json exists but the process it names is gone (a reclaimed VM, a crash, a reboot). */
+    readonly stale: boolean;
+}
+export declare function readSession(projectDir: string): SessionStatus;
+export declare function writeSession(paths: BridgePaths, session: Session): void;
+export declare function clearSession(paths: BridgePaths): void;
+/**
+ * Returns the session for commands that need a running client, with a message that says what to do
+ * rather than just what went wrong.
+ */
+export declare function requireRunningSession(projectDir: string): {
+    session: Session;
+    paths: BridgePaths;
+};
+export declare function isProcessAlive(pid: number): boolean;
+//# sourceMappingURL=session.d.ts.map

package/dist/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../src/session.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,EAAE,KAAK,WAAW,EAAgB,MAAM,YAAY,CAAC;AAE5D,eAAO,MAAM,aAAa;;;;;;;;;;;;;;;IAexB;;;;;OAKG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAEH,CAAC;AAEH,MAAM,MAAM,OAAO,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,aAAa,CAAC,CAAC;AAEpD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,KAAK,EAAE,WAAW,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,OAAO,GAAG,IAAI,CAAC;IACjC,0GAA0G;IAC1G,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAC;CACzB;AAED,wBAAgB,WAAW,CAAC,UAAU,EAAE,MAAM,GAAG,aAAa,CAgB7D;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,EAAE,OAAO,EAAE,OAAO,GAAG,IAAI,CAEvE;AAED,wBAAgB,YAAY,CAAC,KAAK,EAAE,WAAW,GAAG,IAAI,CAIrD;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,KAAK,EAAE,WAAW,CAAA;CAAE,CAqBlG;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAQnD"}