summer-engine 2.2.0 → 2.5.0

package/dist/commands/scene.js

@@ -1,290 +0,0 @@
-import { Command } from "commander";
-import { readFile } from "fs/promises";
-import { join } from "path";
-import { withEngineClient } from "../lib/with-engine.js";
-import { outputResult, outputError, parseValue, readJsonArg, isJsonMode, } from "../lib/format.js";
-async function readMainSceneFromProject(projectPath) {
-    if (!projectPath)
-        return null;
-    try {
-        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
-        const match = text.match(/run\/main_scene="([^"]+)"/);
-        return match?.[1] ?? null;
-    }
-    catch {
-        return null;
-    }
-}
-export const sceneCommand = new Command("scene").description("Scene editing commands (requires running engine)");
-// --- Tier 1 ---
-sceneCommand
-    .command("tree")
-    .description("Get the full scene tree of the currently open scene")
-    .action(async (_opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.getSceneState());
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("open <path>")
-    .description("Open a scene file in the editor (e.g. res://main.tscn)")
-    .action(async (path, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.executeOps([{ op: "OpenScene", path }]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("add <parent> <type> <name>")
-    .description("Add a node to the scene tree (e.g. summer scene add ./World MeshInstance3D Floor)")
-    .action(async (parent, type, name, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.executeOps([{ op: "AddNode", parent, type, name }]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("prop <path> <key> <value>")
-    .description('Set a property on a node (e.g. summer scene prop ./Player position "Vector3(0,5,0)")')
-    .action(async (path, key, value, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.executeOps([{ op: "SetProp", path, key, value: parseValue(value) }]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("save [path]")
-    .description("Save the current scene (optionally save-as to a new path)")
-    .action(async (path, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const op = { op: "SaveScene" };
-        if (path)
-            op.path = path;
-        const result = await withEngineClient((c) => c.executeOps([op]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("inspect <path>")
-    .description("Get all editable properties of a node (e.g. summer scene inspect Player)")
-    .action(async (path, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.inspectNode(path));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("batch <json>")
-    .description('Execute multiple ops in one undo step. Pass JSON array or "-" for stdin')
-    .action(async (jsonArg, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const ops = (await readJsonArg(jsonArg));
-        const result = await withEngineClient((c) => c.executeOps(ops, { groupUndo: true }));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-// --- Tier 2 ---
-sceneCommand
-    .command("remove <path>")
-    .description("Remove a node and all its children from the scene tree")
-    .action(async (path, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.executeOps([{ op: "RemoveNode", path }]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("rprop <nodePath> <resourceProperty> <subProperty> <value>")
-    .description("Set a nested resource property (e.g. summer scene rprop ./Player/Col shape size \"Vector3(1,2,1)\")")
-    .action(async (nodePath, resourceProperty, subProperty, value, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.executeOps([
-            {
-                op: "SetResourceProperty",
-                nodePath,
-                resourceProperty,
-                subProperty,
-                value: parseValue(value),
-            },
-        ]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("instantiate <parent> <scene>")
-    .description("Add an existing scene/model as a child (e.g. summer scene instantiate ./World res://player.tscn)")
-    .option("--name <name>", "Override the instance name")
-    .action(async (parent, scene, opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const op = {
-            op: "InstantiateScene",
-            parent,
-            scene,
-        };
-        if (opts.name)
-            op.name = opts.name;
-        const result = await withEngineClient((c) => c.executeOps([op]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("create <path>")
-    .description("Create a new empty scene file")
-    .option("--root-name <name>", "Root node name", "Main")
-    .option("--yes", "Skip safety confirmation")
-    .action(async (path, opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    if (!opts.yes) {
-        outputError("Scene creation uses a temporary mutation strategy. Pass --yes to confirm.", fmt);
-    }
-    try {
-        const result = await withEngineClient(async (client) => {
-            const health = (await client.health());
-            const currentScene = typeof health.scene === "string" && health.scene.length > 0
-                ? health.scene
-                : null;
-            const projectPath = typeof health.project_path === "string"
-                ? health.project_path
-                : undefined;
-            const mainScene = await readMainSceneFromProject(projectPath);
-            const templateScene = currentScene || mainScene;
-            if (!templateScene) {
-                throw new Error("No scene open and could not resolve main scene. Run `summer project context` first.");
-            }
-            await client.executeOps([{ op: "OpenScene", path: templateScene }]);
-            const tree = (await client.getSceneState());
-            const children = tree.data?.children ?? tree.children ?? [];
-            const removeOps = children
-                .map((c) => c.path)
-                .filter((p) => typeof p === "string" && p.length > 0)
-                .map((p) => ({ op: "RemoveNode", path: `./${p}` }));
-            if (removeOps.length > 0) {
-                await client.executeOps(removeOps, { groupUndo: true });
-            }
-            await client.executeOps([
-                { op: "SetProp", path: ".", key: "name", value: opts.rootName },
-            ]);
-            await client.executeOps([{ op: "SaveScene", path }]);
-            if (currentScene && currentScene !== path) {
-                await client.executeOps([{ op: "OpenScene", path: currentScene }]);
-            }
-            return {
-                ok: true,
-                created: path,
-                rootName: opts.rootName,
-                templateScene,
-                restoredScene: currentScene,
-            };
-        });
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("replace <path>")
-    .description("Replace a node with a different type or scene")
-    .option("--type <type>", "New node type (e.g. RigidBody3D)")
-    .option("--scene <scene>", "Scene to replace with (e.g. res://enemies/boss.tscn)")
-    .action(async (path, opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const op = { op: "ReplaceNode", path };
-        if (opts.type)
-            op.type = opts.type;
-        if (opts.scene)
-            op.scene = opts.scene;
-        const result = await withEngineClient((c) => c.executeOps([op]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("signal <emitter> <signal> <receiver> <method>")
-    .description("Connect a signal between two nodes (e.g. summer scene signal ./HitArea body_entered ./Player _on_hit)")
-    .action(async (emitter, signal, receiver, method, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.executeOps([
-            { op: "ConnectSignal", emitter, signal, receiver, method },
-        ]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("select <nodePath>")
-    .description("Select a node in the editor inspector")
-    .option("--scene <scenePath>", "Open this scene first, then select")
-    .action(async (nodePath, opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const op = { op: "SelectNode", nodePath };
-        if (opts.scene)
-            op.scenePath = opts.scene;
-        const result = await withEngineClient((c) => c.executeOps([op]));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});
-sceneCommand
-    .command("inspect-resource <path>")
-    .description("Get all properties of a resource (material, mesh, shape, etc.)")
-    .action(async (path, _opts, cmd) => {
-    const fmt = isJsonMode(cmd);
-    try {
-        const result = await withEngineClient((c) => c.inspectResource(path));
-        outputResult(result, fmt);
-    }
-    catch (err) {
-        outputError(err instanceof Error ? err.message : String(err), fmt);
-    }
-});

package/dist/lib/agent-config.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/lib/agent-config.test.js

@@ -1,80 +0,0 @@
-import { mkdtempSync, readFileSync, writeFileSync } from "fs";
-import { tmpdir } from "os";
-import { join } from "path";
-import { describe, expect, it } from "vitest";
-import { configureAgentMcp } from "./agent-config.js";
-function tmp() {
-    return mkdtempSync(join(tmpdir(), "summer-agent-config-"));
-}
-describe("configureAgentMcp", () => {
-    it("writes a fresh claude-code config", async () => {
-        const dir = tmp();
-        const path = join(dir, ".claude.json");
-        const result = await configureAgentMcp({
-            agent: "claude-code",
-            scope: "user",
-            env: { SUMMER_CLAUDE_CONFIG_FILE: path },
-        });
-        expect(result.wrote).toBe(true);
-        const written = JSON.parse(readFileSync(path, "utf-8"));
-        expect(written.mcpServers["summer-engine"].command).toBe("npx");
-        expect(written.mcpServers["summer-engine"].args).toEqual([
-            "summer-engine",
-            "mcp",
-        ]);
-    });
-    it("preserves unrelated keys when merging claude-code config", async () => {
-        const dir = tmp();
-        const path = join(dir, ".claude.json");
-        writeFileSync(path, JSON.stringify({
-            theme: "dark",
-            mcpServers: {
-                other: { command: "node", args: ["other.js"] },
-            },
-        }, null, 2));
-        await configureAgentMcp({
-            agent: "claude-code",
-            scope: "user",
-            env: { SUMMER_CLAUDE_CONFIG_FILE: path },
-        });
-        const written = JSON.parse(readFileSync(path, "utf-8"));
-        expect(written.theme).toBe("dark");
-        expect(written.mcpServers.other.command).toBe("node");
-        expect(written.mcpServers["summer-engine"].command).toBe("npx");
-    });
-    it("upserts a codex TOML server table", async () => {
-        const dir = tmp();
-        const path = join(dir, "config.toml");
-        writeFileSync(path, ['[mcp_servers.other]', 'command = "node"', 'args = ["other.js"]', ''].join("\n"));
-        const first = await configureAgentMcp({
-            agent: "codex",
-            scope: "user",
-            env: { SUMMER_CODEX_CONFIG_FILE: path },
-        });
-        expect(first.wrote).toBe(true);
-        let content = readFileSync(path, "utf-8");
-        expect(content).toContain("[mcp_servers.other]");
-        expect(content).toContain("[mcp_servers.summer-engine]");
-        const second = await configureAgentMcp({
-            agent: "codex",
-            scope: "user",
-            env: { SUMMER_CODEX_CONFIG_FILE: path },
-        });
-        expect(second.wrote).toBe(false);
-        content = readFileSync(path, "utf-8");
-        const occurrences = content.match(/\[mcp_servers\.summer-engine\]/g) ?? [];
-        expect(occurrences.length).toBe(1);
-    });
-    it("dry-run does not write", async () => {
-        const dir = tmp();
-        const path = join(dir, ".claude.json");
-        const result = await configureAgentMcp({
-            agent: "claude-code",
-            scope: "user",
-            dryRun: true,
-            env: { SUMMER_CLAUDE_CONFIG_FILE: path },
-        });
-        expect(result.wrote).toBe(false);
-        expect(() => readFileSync(path, "utf-8")).toThrow();
-    });
-});

package/dist/lib/format.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/lib/format.test.js

@@ -1,36 +0,0 @@
-import { homedir } from "os";
-import { describe, expect, it } from "vitest";
-import { stripAnsi, tildeify } from "./format.js";
-describe("tildeify", () => {
-    it("replaces home directory prefix with ~", () => {
-        const home = homedir();
-        expect(tildeify(home + "/.claude.json")).toBe("~/.claude.json");
-        expect(tildeify(home + "/projects/foo")).toBe("~/projects/foo");
-    });
-    it("returns ~ when path is the home directory exactly", () => {
-        expect(tildeify(homedir())).toBe("~");
-    });
-    it("does not touch non-home paths", () => {
-        expect(tildeify("/Applications/Summer.app")).toBe("/Applications/Summer.app");
-        expect(tildeify("/tmp/foo")).toBe("/tmp/foo");
-    });
-    it("does not partial-match (e.g. /Users/Mat vs /Users/MathiasWork)", () => {
-        const home = homedir();
-        const sibling = home.slice(0, -2) + "Other";
-        expect(tildeify(sibling + "/file")).toBe(sibling + "/file");
-    });
-    it("handles empty/null/undefined input", () => {
-        expect(tildeify(undefined)).toBe("");
-        expect(tildeify(null)).toBe("");
-        expect(tildeify("")).toBe("");
-    });
-});
-describe("stripAnsi", () => {
-    it("removes ANSI color codes", () => {
-        expect(stripAnsi("\x1b[31mhello\x1b[0m")).toBe("hello");
-        expect(stripAnsi("\x1b[1;32mbold green\x1b[0m text")).toBe("bold green text");
-    });
-    it("leaves clean strings untouched", () => {
-        expect(stripAnsi("hello")).toBe("hello");
-    });
-});

package/dist/lib/plugin-manifests.test.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/lib/plugin-manifests.test.js

@@ -1,134 +0,0 @@
-/**
- * Validates that every agent plugin manifest references real, on-disk skills,
- * and that every skill claimed HAVE in catalog.yaml actually exists.
- *
- * Catches broken-path bugs before they ship. Add a manifest, add a path here.
- */
-import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
-import { dirname, join } from "node:path";
-import { fileURLToPath } from "node:url";
-import { describe, expect, it } from "vitest";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const repoRoot = join(__dirname, "..", "..");
-const MANIFESTS = [
-    {
-        name: ".claude-plugin/plugin.json",
-        path: join(repoRoot, ".claude-plugin", "plugin.json"),
-        skillsField: [],
-    },
-    {
-        name: ".cursor-plugin/plugin.json",
-        path: join(repoRoot, ".cursor-plugin", "plugin.json"),
-        skillsField: [],
-    },
-    {
-        name: ".codex-plugin/plugin.json",
-        path: join(repoRoot, ".codex-plugin", "plugin.json"),
-        skillsField: [],
-    },
-];
-function loadSkillsField(manifestPath) {
-    const raw = readFileSync(manifestPath, "utf-8");
-    const json = JSON.parse(raw);
-    if (json.skills === undefined) {
-        throw new Error(`${manifestPath}: missing "skills" field`);
-    }
-    return json.skills;
-}
-function listSkillDirs(skillsRoot) {
-    const entries = readdirSync(skillsRoot);
-    const out = [];
-    for (const cat of entries) {
-        const catPath = join(skillsRoot, cat);
-        if (!statSync(catPath).isDirectory())
-            continue;
-        if (cat === "_shared" || cat === "_tests")
-            continue;
-        for (const skill of readdirSync(catPath)) {
-            const skillPath = join(catPath, skill);
-            if (!statSync(skillPath).isDirectory())
-                continue;
-            if (existsSync(join(skillPath, "SKILL.md"))) {
-                out.push(`./skills/${cat}/${skill}/`);
-            }
-        }
-    }
-    return out;
-}
-describe("agent plugin manifests", () => {
-    for (const m of MANIFESTS) {
-        describe(m.name, () => {
-            it("exists and parses as JSON", () => {
-                expect(existsSync(m.path), `${m.name} not found`).toBe(true);
-                m.skillsField = loadSkillsField(m.path);
-            });
-            it("every referenced skill path resolves to a SKILL.md on disk", () => {
-                const skills = m.skillsField;
-                if (typeof skills === "string") {
-                    // Directory pointer mode (e.g. "./skills/")
-                    const dir = join(repoRoot, skills);
-                    expect(existsSync(dir), `${m.name}: skills dir ${skills} missing`).toBe(true);
-                    return;
-                }
-                const broken = [];
-                for (const rel of skills) {
-                    const skillMd = join(repoRoot, rel, "SKILL.md");
-                    if (!existsSync(skillMd))
-                        broken.push(rel);
-                }
-                expect(broken, `${m.name} references missing skills:\n${broken.join("\n")}`).toEqual([]);
-            });
-            it("does not duplicate skill paths", () => {
-                const skills = m.skillsField;
-                if (typeof skills === "string")
-                    return;
-                const seen = new Set();
-                const dupes = [];
-                for (const rel of skills) {
-                    if (seen.has(rel))
-                        dupes.push(rel);
-                    seen.add(rel);
-                }
-                expect(dupes, `${m.name} duplicates: ${dupes.join(", ")}`).toEqual([]);
-            });
-        });
-    }
-    describe("skills directory <-> manifest coverage", () => {
-        it("every on-disk skill is listed in .claude-plugin/plugin.json", () => {
-            const onDisk = listSkillDirs(join(repoRoot, "skills"));
-            const claudeManifest = JSON.parse(readFileSync(join(repoRoot, ".claude-plugin", "plugin.json"), "utf-8"));
-            const listed = new Set(claudeManifest.skills);
-            const orphans = onDisk.filter((p) => !listed.has(p));
-            expect(orphans, `On-disk skills missing from .claude-plugin/plugin.json (add or move under skills/_shared|_tests):\n${orphans.join("\n")}`).toEqual([]);
-        });
-    });
-});
-describe("skill SKILL.md frontmatter", () => {
-    it("every shipped SKILL.md has name and Use-when-style description", () => {
-        const skillsRoot = join(repoRoot, "skills");
-        const skillDirs = listSkillDirs(skillsRoot);
-        const failures = [];
-        for (const rel of skillDirs) {
-            const file = join(repoRoot, rel, "SKILL.md");
-            const text = readFileSync(file, "utf-8");
-            const match = text.match(/^---\s*\n([\s\S]+?)\n---/);
-            if (!match) {
-                failures.push(`${rel}: no frontmatter`);
-                continue;
-            }
-            const fm = match[1];
-            const nameMatch = fm.match(/^name:\s*(.+)$/m);
-            const descMatch = fm.match(/^description:\s*(.+)$/m);
-            if (!nameMatch || !nameMatch[1].trim())
-                failures.push(`${rel}: missing name`);
-            if (!descMatch || !descMatch[1].trim())
-                failures.push(`${rel}: missing description`);
-            const desc = descMatch?.[1] ?? "";
-            // Auto-trigger discipline: description must contain "Use when"
-            if (desc && !/\bUse when\b/i.test(desc)) {
-                failures.push(`${rel}: description must contain "Use when ..." (got: "${desc.slice(0, 80)}...")`);
-            }
-        }
-        expect(failures, `Skill frontmatter problems:\n${failures.join("\n")}`).toEqual([]);
-    });
-});

package/dist/lib/with-engine.d.ts

@@ -1,14 +0,0 @@
-import { EngineApiClient } from "./api-client.js";
-export declare function extractOpError(result: unknown): string | null;
-export declare function buildActionHint(message: string): string | null;
-export declare function checkQuota(): Promise<{
-    allowed: boolean;
-    message?: string;
-}>;
-export declare function getClient(): Promise<EngineApiClient>;
-export declare function resetClient(): void;
-/**
- * Connect to the engine, check quota, and run the given function.
- * Throws on errors (quota, connection, op errors).
- */
-export declare function withEngineClient<T>(fn: (client: EngineApiClient) => Promise<T>): Promise<T>;

package/dist/lib/with-engine.js

@@ -1,109 +0,0 @@
-import { EngineApiClient } from "./api-client.js";
-import { getAuthToken } from "./auth.js";
-const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
-export function extractOpError(result) {
-    if (!result || typeof result !== "object")
-        return null;
-    const op = result;
-    if (op.status === "error" && op.error)
-        return op.error;
-    const firstFailed = op.results?.find((r) => r.ok === false && r.error);
-    return firstFailed?.error ?? null;
-}
-export function buildActionHint(message) {
-    const normalized = message.toLowerCase();
-    if (normalized.includes("no scene open") || normalized.includes("no edited scene")) {
-        return "No scene is currently open. Run `summer project context` first, then `summer project open-main` (or `summer scene open` with a known .tscn path).";
-    }
-    if (normalized.includes("failed to open scene")) {
-        return "Scene path could not be opened. Run `summer project context` to get mainScene, then open that exact path. Avoid guessing scene filenames.";
-    }
-    if (normalized.includes("writefile cannot edit .tscn/.scn")) {
-        return "Cannot write .tscn/.scn directly. Use summer scene commands for scene-tree operations, and file-edit tools for .gd scripts.";
-    }
-    return null;
-}
-export async function checkQuota() {
-    const token = await getAuthToken();
-    if (!token) {
-        return {
-            allowed: false,
-            message: "Not signed in. Run: summer login\nOr open: https://www.summerengine.com/login\nEngine tools require a Summer Engine account (free to create).",
-        };
-    }
-    try {
-        const res = await fetch(`${GATEWAY_URL}/api/mcp/log-local-call`, {
-            method: "POST",
-            headers: {
-                Authorization: `Bearer ${token}`,
-                "Content-Type": "application/json",
-            },
-            body: JSON.stringify({}),
-            signal: AbortSignal.timeout(10000),
-        });
-        const data = (await res.json().catch(() => ({})));
-        if ([401, 402, 403, 429].includes(res.status)) {
-            return {
-                allowed: false,
-                message: data.message || "Quota check failed. Try again.",
-            };
-        }
-        // Soft-fail on service/gateway issues so local tools keep working.
-        if (!res.ok) {
-            return { allowed: true };
-        }
-        if (data.allowed === false) {
-            return {
-                allowed: false,
-                message: data.message || "Call limit reached. Upgrade at https://summerengine.com/pricing",
-            };
-        }
-        return { allowed: true };
-    }
-    catch {
-        // Network/transient errors should not brick local usage.
-        return { allowed: true };
-    }
-}
-let cachedClient = null;
-export function getClient() {
-    if (cachedClient)
-        return Promise.resolve(cachedClient);
-    return EngineApiClient.connect().then((c) => {
-        cachedClient = c;
-        return c;
-    });
-}
-export function resetClient() {
-    cachedClient = null;
-}
-/**
- * Connect to the engine, check quota, and run the given function.
- * Throws on errors (quota, connection, op errors).
- */
-export async function withEngineClient(fn) {
-    const quota = await checkQuota();
-    if (!quota.allowed) {
-        throw new Error(quota.message || "Quota exceeded");
-    }
-    try {
-        const client = await getClient();
-        const result = await fn(client);
-        const opError = extractOpError(result);
-        if (opError) {
-            const hint = buildActionHint(opError);
-            throw new Error(hint ? `${opError}\n\nHint: ${hint}` : opError);
-        }
-        return result;
-    }
-    catch (err) {
-        // Reset client on connection errors so next call retries
-        if (err instanceof Error &&
-            (err.message.includes("not running") ||
-                err.message.includes("not responding") ||
-                err.message.includes("ECONNREFUSED"))) {
-            resetClient();
-        }
-        throw err;
-    }
-}