cyclops-clientdevbridge-cli 0.1.1

package/dist/session.js

@@ -0,0 +1,79 @@
+import * as fs from 'node:fs';
+import { z } from 'zod';
+import { SessionError } from './errors.js';
+import { resolvePaths } from './paths.js';
+export const sessionSchema = z.object({
+    version: z.literal(1),
+    port: z.number().int().positive(),
+    pid: z.number().int().positive(),
+    pgid: z.number().int(),
+    loader: z.enum(['fabric', 'neoforge']),
+    mcVersion: z.string(),
+    bridgeVersion: z.string(),
+    projectDir: z.string(),
+    gradleTask: z.string(),
+    startedAt: z.string(),
+    world: z.string().nullable(),
+    headed: z.boolean(),
+    display: z.string().nullable(),
+    jdwpPort: z.number().int().positive().nullable(),
+    /**
+     * 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.array(z.number().int().positive()).optional(),
+});
+export function readSession(projectDir) {
+    const paths = resolvePaths(projectDir);
+    if (!fs.existsSync(paths.sessionFile)) {
+        return { paths, session: null, stale: false };
+    }
+    let parsed;
+    try {
+        parsed = sessionSchema.parse(JSON.parse(fs.readFileSync(paths.sessionFile, 'utf8')));
+    }
+    catch {
+        // A truncated or older session file is treated exactly like a dead one, so that a cold VM
+        // never leaves the CLI stuck on a file it cannot read.
+        return { paths, session: null, stale: true };
+    }
+    return { paths, session: parsed, stale: !isProcessAlive(parsed.pid) };
+}
+export function writeSession(paths, session) {
+    fs.writeFileSync(paths.sessionFile, `${JSON.stringify(session, null, 2)}\n`, 'utf8');
+}
+export function clearSession(paths) {
+    if (fs.existsSync(paths.sessionFile)) {
+        fs.rmSync(paths.sessionFile);
+    }
+}
+/**
+ * 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 function requireRunningSession(projectDir) {
+    const status = readSession(projectDir);
+    if (status.session === null) {
+        if (status.stale) {
+            throw new SessionError(`The session file at ${status.paths.sessionFile} is unreadable, so no client is being tracked.`, "Run 'clientdevbridge start' to launch a fresh client.");
+        }
+        throw new SessionError(`No ClientDevBridge session in ${status.paths.projectDir}.`, "Run 'clientdevbridge start' first (add --project <dir> if the mod project is elsewhere).");
+    }
+    if (status.stale) {
+        throw new SessionError(`The recorded client (pid ${status.session.pid}) is no longer running.`, "Run 'clientdevbridge start' to launch a new one; 'clientdevbridge logs --gradle' shows why the old one exited.");
+    }
+    return { session: status.session, paths: status.paths };
+}
+export function isProcessAlive(pid) {
+    try {
+        // Signal 0 performs the permission and existence checks without delivering a signal.
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === 'EPERM';
+    }
+}
+//# sourceMappingURL=session.js.map

package/dist/session.js.map

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

package/dist/snapshot/model.d.ts

@@ -0,0 +1,327 @@
+import { z } from 'zod';
+export declare const boundsSchema: z.ZodObject<{
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    w: z.ZodNumber;
+    h: z.ZodNumber;
+}, "strip", z.ZodTypeAny, {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}, {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+}>;
+export type Bounds = z.infer<typeof boundsSchema>;
+export interface SnapshotNode {
+    path: string;
+    type: string;
+    bounds: Bounds | null;
+    message: string | null;
+    narration: string | null;
+    visible: boolean;
+    active: boolean;
+    focused: boolean;
+    hovered: boolean;
+    value?: unknown;
+    extra: Record<string, unknown>;
+    children: SnapshotNode[];
+}
+export declare const snapshotNodeSchema: z.ZodType<SnapshotNode, z.ZodTypeDef, unknown>;
+export declare const slotSchema: z.ZodObject<{
+    index: z.ZodNumber;
+    item: z.ZodNullable<z.ZodString>;
+    count: z.ZodNumber;
+    name: z.ZodOptional<z.ZodString>;
+    x: z.ZodNumber;
+    y: z.ZodNumber;
+    hovered: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    x: number;
+    y: number;
+    hovered: boolean;
+    index: number;
+    item: string | null;
+    count: number;
+    name?: string | undefined;
+}, {
+    x: number;
+    y: number;
+    hovered: boolean;
+    index: number;
+    item: string | null;
+    count: number;
+    name?: string | undefined;
+}>;
+export declare const containerSchema: z.ZodObject<{
+    menuClass: z.ZodString;
+    leftPos: z.ZodNumber;
+    topPos: z.ZodNumber;
+    imageWidth: z.ZodNumber;
+    imageHeight: z.ZodNumber;
+    carried: z.ZodObject<{
+        item: z.ZodNullable<z.ZodString>;
+        count: z.ZodNumber;
+    }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+        item: z.ZodNullable<z.ZodString>;
+        count: z.ZodNumber;
+    }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+        item: z.ZodNullable<z.ZodString>;
+        count: z.ZodNumber;
+    }, z.ZodTypeAny, "passthrough">>;
+    slots: z.ZodArray<z.ZodObject<{
+        index: z.ZodNumber;
+        item: z.ZodNullable<z.ZodString>;
+        count: z.ZodNumber;
+        name: z.ZodOptional<z.ZodString>;
+        x: z.ZodNumber;
+        y: z.ZodNumber;
+        hovered: z.ZodBoolean;
+    }, "strip", z.ZodTypeAny, {
+        x: number;
+        y: number;
+        hovered: boolean;
+        index: number;
+        item: string | null;
+        count: number;
+        name?: string | undefined;
+    }, {
+        x: number;
+        y: number;
+        hovered: boolean;
+        index: number;
+        item: string | null;
+        count: number;
+        name?: string | undefined;
+    }>, "many">;
+}, "strip", z.ZodTypeAny, {
+    menuClass: string;
+    leftPos: number;
+    topPos: number;
+    imageWidth: number;
+    imageHeight: number;
+    carried: {
+        item: string | null;
+        count: number;
+    } & {
+        [k: string]: unknown;
+    };
+    slots: {
+        x: number;
+        y: number;
+        hovered: boolean;
+        index: number;
+        item: string | null;
+        count: number;
+        name?: string | undefined;
+    }[];
+}, {
+    menuClass: string;
+    leftPos: number;
+    topPos: number;
+    imageWidth: number;
+    imageHeight: number;
+    carried: {
+        item: string | null;
+        count: number;
+    } & {
+        [k: string]: unknown;
+    };
+    slots: {
+        x: number;
+        y: number;
+        hovered: boolean;
+        index: number;
+        item: string | null;
+        count: number;
+        name?: string | undefined;
+    }[];
+}>;
+export declare const snapshotSchema: z.ZodObject<{
+    screenClass: z.ZodNullable<z.ZodString>;
+    title: z.ZodNullable<z.ZodString>;
+    guiScale: z.ZodNumber;
+    guiWidth: z.ZodNumber;
+    guiHeight: z.ZodNumber;
+    pixelWidth: z.ZodNumber;
+    pixelHeight: z.ZodNumber;
+    mouse: z.ZodArray<z.ZodNumber, "many">;
+    focused: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    hovered: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    truncated: z.ZodDefault<z.ZodBoolean>;
+    container: z.ZodNullable<z.ZodObject<{
+        menuClass: z.ZodString;
+        leftPos: z.ZodNumber;
+        topPos: z.ZodNumber;
+        imageWidth: z.ZodNumber;
+        imageHeight: z.ZodNumber;
+        carried: z.ZodObject<{
+            item: z.ZodNullable<z.ZodString>;
+            count: z.ZodNumber;
+        }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
+            item: z.ZodNullable<z.ZodString>;
+            count: z.ZodNumber;
+        }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
+            item: z.ZodNullable<z.ZodString>;
+            count: z.ZodNumber;
+        }, z.ZodTypeAny, "passthrough">>;
+        slots: z.ZodArray<z.ZodObject<{
+            index: z.ZodNumber;
+            item: z.ZodNullable<z.ZodString>;
+            count: z.ZodNumber;
+            name: z.ZodOptional<z.ZodString>;
+            x: z.ZodNumber;
+            y: z.ZodNumber;
+            hovered: z.ZodBoolean;
+        }, "strip", z.ZodTypeAny, {
+            x: number;
+            y: number;
+            hovered: boolean;
+            index: number;
+            item: string | null;
+            count: number;
+            name?: string | undefined;
+        }, {
+            x: number;
+            y: number;
+            hovered: boolean;
+            index: number;
+            item: string | null;
+            count: number;
+            name?: string | undefined;
+        }>, "many">;
+    }, "strip", z.ZodTypeAny, {
+        menuClass: string;
+        leftPos: number;
+        topPos: number;
+        imageWidth: number;
+        imageHeight: number;
+        carried: {
+            item: string | null;
+            count: number;
+        } & {
+            [k: string]: unknown;
+        };
+        slots: {
+            x: number;
+            y: number;
+            hovered: boolean;
+            index: number;
+            item: string | null;
+            count: number;
+            name?: string | undefined;
+        }[];
+    }, {
+        menuClass: string;
+        leftPos: number;
+        topPos: number;
+        imageWidth: number;
+        imageHeight: number;
+        carried: {
+            item: string | null;
+            count: number;
+        } & {
+            [k: string]: unknown;
+        };
+        slots: {
+            x: number;
+            y: number;
+            hovered: boolean;
+            index: number;
+            item: string | null;
+            count: number;
+            name?: string | undefined;
+        }[];
+    }>>;
+    root: z.ZodNullable<z.ZodType<SnapshotNode, z.ZodTypeDef, unknown>>;
+}, "strip", z.ZodTypeAny, {
+    guiScale: number;
+    guiWidth: number;
+    guiHeight: number;
+    pixelWidth: number;
+    pixelHeight: number;
+    screenClass: string | null;
+    title: string | null;
+    mouse: number[];
+    truncated: boolean;
+    container: {
+        menuClass: string;
+        leftPos: number;
+        topPos: number;
+        imageWidth: number;
+        imageHeight: number;
+        carried: {
+            item: string | null;
+            count: number;
+        } & {
+            [k: string]: unknown;
+        };
+        slots: {
+            x: number;
+            y: number;
+            hovered: boolean;
+            index: number;
+            item: string | null;
+            count: number;
+            name?: string | undefined;
+        }[];
+    } | null;
+    root: SnapshotNode | null;
+    focused?: string | null | undefined;
+    hovered?: string | null | undefined;
+}, {
+    guiScale: number;
+    guiWidth: number;
+    guiHeight: number;
+    pixelWidth: number;
+    pixelHeight: number;
+    screenClass: string | null;
+    title: string | null;
+    mouse: number[];
+    container: {
+        menuClass: string;
+        leftPos: number;
+        topPos: number;
+        imageWidth: number;
+        imageHeight: number;
+        carried: {
+            item: string | null;
+            count: number;
+        } & {
+            [k: string]: unknown;
+        };
+        slots: {
+            x: number;
+            y: number;
+            hovered: boolean;
+            index: number;
+            item: string | null;
+            count: number;
+            name?: string | undefined;
+        }[];
+    } | null;
+    focused?: string | null | undefined;
+    hovered?: string | null | undefined;
+    truncated?: boolean | undefined;
+    root?: unknown;
+}>;
+export type Snapshot = z.infer<typeof snapshotSchema>;
+export type Slot = z.infer<typeof slotSchema>;
+/** Depth-first walk, parents before children. */
+export declare function walk(node: SnapshotNode, visit: (node: SnapshotNode, depth: number) => void, depth?: number): void;
+export declare function flatten(root: SnapshotNode | null): {
+    node: SnapshotNode;
+    depth: number;
+}[];
+/** The point a click should target for a node. */
+export declare function centre(node: SnapshotNode): {
+    x: number;
+    y: number;
+} | null;
+/** A short, human-meaningful label for a node: its message, else its narration, else nothing. */
+export declare function label(node: SnapshotNode): string;
+export declare function simpleType(node: SnapshotNode): string;
+//# sourceMappingURL=model.d.ts.map

package/dist/snapshot/model.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"model.d.ts","sourceRoot":"","sources":["../../src/snapshot/model.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;EAA2E,CAAC;AACrG,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,YAAY,CAAC,CAAC;AAElD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,OAAO,CAAC;IAChB,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC/B,QAAQ,EAAE,YAAY,EAAE,CAAC;CAC1B;AAID,eAAO,MAAM,kBAAkB,EAAE,CAAC,CAAC,OAAO,CAAC,YAAY,EAAE,CAAC,CAAC,UAAU,EAAE,OAAO,CAe7E,CAAC;AAEF,eAAO,MAAM,UAAU;;;;;;;;;;;;;;;;;;;;;;;;EAQrB,CAAC;AAEH,eAAO,MAAM,eAAe;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAQ1B,CAAC;AAEH,eAAO,MAAM,cAAc;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAczB,CAAC;AAEH,MAAM,MAAM,QAAQ,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,cAAc,CAAC,CAAC;AACtD,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,UAAU,CAAC,CAAC;AAE9C,iDAAiD;AACjD,wBAAgB,IAAI,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,CAAC,IAAI,EAAE,YAAY,EAAE,KAAK,EAAE,MAAM,KAAK,IAAI,EAAE,KAAK,SAAI,GAAG,IAAI,CAK5G;AAED,wBAAgB,OAAO,CAAC,IAAI,EAAE,YAAY,GAAG,IAAI,GAAG;IAAE,IAAI,EAAE,YAAY,CAAC;IAAC,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,CAO1F;AAED,kDAAkD;AAClD,wBAAgB,MAAM,CAAC,IAAI,EAAE,YAAY,GAAG;IAAE,CAAC,EAAE,MAAM,CAAC;IAAC,CAAC,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAQ1E;AAED,iGAAiG;AACjG,wBAAgB,KAAK,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAQhD;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAGrD"}

package/dist/snapshot/model.js

@@ -0,0 +1,91 @@
+import { z } from 'zod';
+export const boundsSchema = z.object({ x: z.number(), y: z.number(), w: z.number(), h: z.number() });
+// The input type differs from the output type because of the `.default()`s, so the third
+// type argument is `unknown` rather than SnapshotNode.
+export const snapshotNodeSchema = z.lazy(() => z.object({
+    path: z.string(),
+    type: z.string(),
+    bounds: boundsSchema.nullable(),
+    message: z.string().nullable(),
+    narration: z.string().nullable(),
+    visible: z.boolean(),
+    active: z.boolean(),
+    focused: z.boolean(),
+    hovered: z.boolean(),
+    value: z.unknown(),
+    extra: z.record(z.unknown()).default({}),
+    children: z.array(snapshotNodeSchema).default([]),
+}));
+export const slotSchema = z.object({
+    index: z.number(),
+    item: z.string().nullable(),
+    count: z.number(),
+    name: z.string().optional(),
+    x: z.number(),
+    y: z.number(),
+    hovered: z.boolean(),
+});
+export const containerSchema = z.object({
+    menuClass: z.string(),
+    leftPos: z.number(),
+    topPos: z.number(),
+    imageWidth: z.number(),
+    imageHeight: z.number(),
+    carried: z.object({ item: z.string().nullable(), count: z.number() }).passthrough(),
+    slots: z.array(slotSchema),
+});
+export const snapshotSchema = z.object({
+    screenClass: z.string().nullable(),
+    title: z.string().nullable(),
+    guiScale: z.number(),
+    guiWidth: z.number(),
+    guiHeight: z.number(),
+    pixelWidth: z.number(),
+    pixelHeight: z.number(),
+    mouse: z.array(z.number()),
+    focused: z.string().nullable().optional(),
+    hovered: z.string().nullable().optional(),
+    truncated: z.boolean().default(false),
+    container: containerSchema.nullable(),
+    root: snapshotNodeSchema.nullable(),
+});
+/** Depth-first walk, parents before children. */
+export function walk(node, visit, depth = 0) {
+    visit(node, depth);
+    for (const child of node.children) {
+        walk(child, visit, depth + 1);
+    }
+}
+export function flatten(root) {
+    if (root === null) {
+        return [];
+    }
+    const all = [];
+    walk(root, (node, depth) => all.push({ node, depth }));
+    return all;
+}
+/** The point a click should target for a node. */
+export function centre(node) {
+    if (node.bounds === null) {
+        return null;
+    }
+    return {
+        x: node.bounds.x + Math.floor(node.bounds.w / 2),
+        y: node.bounds.y + Math.floor(node.bounds.h / 2),
+    };
+}
+/** A short, human-meaningful label for a node: its message, else its narration, else nothing. */
+export function label(node) {
+    if (node.message !== null && node.message.length > 0) {
+        return node.message;
+    }
+    if (node.narration !== null && node.narration.length > 0) {
+        return node.narration;
+    }
+    return '';
+}
+export function simpleType(node) {
+    const parts = node.type.split('.');
+    return parts[parts.length - 1] ?? node.type;
+}
+//# sourceMappingURL=model.js.map

package/dist/snapshot/model.js.map

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

package/dist/snapshot/outline.d.ts

@@ -0,0 +1,35 @@
+import { type Slot, type Snapshot, type SnapshotNode } from './model.js';
+/**
+ * Renders a snapshot as one line per widget, indented by depth.
+ *
+ * This is the format an agent actually reads, so it is optimised for scanning: the type and label
+ * first, then the geometry it would need to click, then only the flags that are *not* the default.
+ * A line looks like:
+ *
+ * ```
+ *   Button "Apply" @(312,208 60x20) disabled  /root/children[3]
+ * ```
+ *
+ * The trailing path is what `click --widget` consumes, so an outline line can be copied verbatim.
+ */
+export declare function formatOutline(snapshot: Snapshot, options?: {
+    includeHidden?: boolean;
+}): string;
+export declare function formatSlot(slot: Slot): string;
+export declare function formatNode(node: SnapshotNode): string;
+export interface Match {
+    readonly node: SnapshotNode;
+    readonly centre: {
+        x: number;
+        y: number;
+    } | null;
+}
+/**
+ * Finds nodes by label, by path, or by type.
+ *
+ * An exact path match wins outright, then an exact label match, then a case-insensitive
+ * substring match — so `click --widget Apply` picks the "Apply" button even on a screen that
+ * also has an "Apply to all" one.
+ */
+export declare function findNodes(snapshot: Snapshot, query: string, typeFilter?: string): Match[];
+//# sourceMappingURL=outline.d.ts.map

package/dist/snapshot/outline.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"outline.d.ts","sourceRoot":"","sources":["../../src/snapshot/outline.ts"],"names":[],"mappings":"AAAA,OAAO,EAA0B,KAAK,IAAI,EAAE,KAAK,QAAQ,EAAE,KAAK,YAAY,EAAc,MAAM,YAAY,CAAC;AAE7G;;;;;;;;;;;;GAYG;AACH,wBAAgB,aAAa,CAAC,QAAQ,EAAE,QAAQ,EAAE,OAAO,GAAE;IAAE,aAAa,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,MAAM,CAmDnG;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAI7C;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAuCrD;AAYD,MAAM,WAAW,KAAK;IACpB,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,EAAE;QAAE,CAAC,EAAE,MAAM,CAAC;QAAC,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;CAClD;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,QAAQ,EAAE,QAAQ,EAAE,KAAK,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,KAAK,EAAE,CAwBzF"}