summer-engine 1.5.0 → 2.2.0

package/dist/commands/project.js

@@ -0,0 +1,170 @@
+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 projectCommand = new Command("project").description("Project context and settings (requires running engine)");
+projectCommand
+    .command("context")
+    .description("Get project context: health, current scene, main scene, project path")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient(async (client) => {
+            const [health, projectState] = await Promise.all([
+                client.health(),
+                client.getProjectState(),
+            ]);
+            const healthObj = (health ?? {});
+            const mainScene = await readMainSceneFromProject(typeof healthObj.project_path === "string"
+                ? healthObj.project_path
+                : undefined);
+            return {
+                health,
+                project: projectState,
+                mainScene,
+                guidance: mainScene
+                    ? "Use `summer scene open` with mainScene if no scene is open."
+                    : "Main scene not found in project.godot. Open a known scene path explicitly.",
+            };
+        });
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("open-main")
+    .description("Open the project's main scene from project.godot")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient(async (client) => {
+            const health = (await client.health());
+            const projectPath = typeof health.project_path === "string"
+                ? health.project_path
+                : undefined;
+            const mainScene = await readMainSceneFromProject(projectPath);
+            if (!mainScene) {
+                throw new Error("Could not resolve main_scene from project.godot. Run `summer project context` and open a scene explicitly.");
+            }
+            return client.executeOps([{ op: "OpenScene", path: mainScene }]);
+        });
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("setting <key> <value>")
+    .description('Set a project setting (e.g. summer project setting application/config/name "My Game")')
+    .action(async (key, value, _opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const result = await withEngineClient((c) => c.executeOps([
+            { op: "ProjectSetting", key, value: parseValue(value) },
+        ]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("input-bind <name> <events>")
+    .description('Bind input events to an action (e.g. summer project input-bind jump \'[{"type":"key","key":"Space"}]\')')
+    .action(async (name, eventsJson, _opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const events = JSON.parse(eventsJson);
+        const result = await withEngineClient((c) => c.executeOps([
+            { op: "InputMapAddAction", name },
+            { op: "InputMapBind", name, events },
+        ]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("import <url>")
+    .description("Download a file from a URL and import into the project")
+    .option("--path <path>", "Target path in project (auto-inferred from URL if omitted)")
+    .action(async (url, opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const op = { op: "ImportFromUrl", url };
+        if (opts.path)
+            op.path = opts.path;
+        const result = await withEngineClient((c) => c.executeOps([op]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("import-batch <json>")
+    .description('Import multiple files. Pass JSON array of {url, path} or "-" for stdin')
+    .action(async (jsonArg, _opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    try {
+        const imports = (await readJsonArg(jsonArg));
+        const result = await withEngineClient((c) => c.executeOps([{ op: "ImportFromUrlBatch", imports }]));
+        outputResult(result, fmt);
+    }
+    catch (err) {
+        outputError(err instanceof Error ? err.message : String(err), fmt);
+    }
+});
+projectCommand
+    .command("playbook")
+    .description("Show the AI agent operating guide for Summer Engine")
+    .action(async (_opts, cmd) => {
+    const fmt = isJsonMode(cmd);
+    const playbook = {
+        startupChecklist: [
+            "Decide first: file edit or engine operation.",
+            "For normal code/content edits (.gd/.tscn/.tres/.ts), use host file-edit tools directly.",
+            "Call `summer project context` first.",
+            "If no scene is open, call `summer project open-main`.",
+            "Call `summer scene tree` before structural edits.",
+            "Call `summer scene save` after edits.",
+        ],
+        safeDefaults: [
+            "Never guess scene filenames (main.tscn/Main.tscn).",
+            "Do not route ordinary code edits through engine ops when direct file tools are available.",
+            "Never remove multiple top-level nodes unless user explicitly requests destructive edits.",
+            "Never write .tscn/.scn with file write tools; use scene commands.",
+        ],
+        preferredFlow: [
+            "summer project context",
+            "summer project open-main (if needed)",
+            "summer scene tree",
+            "edit via summer scene add / summer scene prop / summer scene rprop",
+            "summer scene save",
+            "summer debug diagnostics",
+        ],
+        recovery: [
+            "If you see 'no scene open': run summer project open-main.",
+            "If open fails: re-check mainScene from summer project context.",
+            "If save fails: verify scene is open and game is not running.",
+        ],
+    };
+    outputResult(playbook, fmt);
+});

package/dist/commands/scene.d.ts

@@ -0,0 +1,2 @@
+import { Command } from "commander";
+export declare const sceneCommand: Command;

package/dist/commands/scene.js

@@ -0,0 +1,290 @@
+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/banner.js

@@ -84,10 +84,10 @@ export function getWelcome(version) {
     ];
     const footerLines = [
         pad("", 69),
-        pad(`  ${sunC2}summer-engine-cli${reset} · ${dim}local${reset}`, 69),
+        pad(`  ${sunC2}summer${reset} · ${dim}local${reset}`, 69),
         pad(`  ${dim}Docs: https://summerengine.com/docs/mcp${reset}`, 69)
     ];
-    const title = ` Summer Engine CLI v${version} `;
+    const title = ` Summer v${version} `;
     const titleLen = stripAnsi(title).length;
     const totalDashes = 69 - titleLen;
     const leftDashes = Math.floor(totalDashes / 2);

package/dist/lib/log-filters.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Post-processors for engine log/diagnostic payloads before they are returned
+ * to the AI model. The engine API stays lossless; the AI-facing surface
+ * trims, dedupes, and prioritizes.
+ *
+ * Two passes:
+ *  - dedupe(): collapse consecutive identical messages into one with a
+ *    `(×N)` count suffix so a 200-frame `null check` flood reads as one line.
+ *  - errorsOnly(): drop info/std lines, keep errors and warnings.
+ */
+export type LogEntry = {
+    message?: string;
+    text?: string;
+    type?: string;
+    severity?: string;
+    level?: string;
+    timestamp?: string;
+    [k: string]: unknown;
+};
+export interface FilterOptions {
+    /** Drop everything that isn't an error or warning. Default: false. */
+    errorsOnly?: boolean;
+    /** Drop everything that isn't an error. Default: false. */
+    errorsOnlyStrict?: boolean;
+    /** Hard cap on returned entries after dedupe. Default: 100. */
+    maxEntries?: number;
+    /** Skip dedupe — return everything as-is. Default: false. */
+    noDedupe?: boolean;
+}
+export interface FilterSummary {
+    totalIn: number;
+    totalOut: number;
+    duplicatesCollapsed: number;
+    droppedByLevel: number;
+    truncated: number;
+}
+export interface FilterResult<T extends LogEntry = LogEntry> {
+    entries: T[];
+    summary: FilterSummary;
+}
+export declare function filterAndDedupe<T extends LogEntry>(entries: T[], opts?: FilterOptions): FilterResult<T>;
+/**
+ * Walks a parsed engine response and applies filterAndDedupe to the first
+ * recognized log-bearing array. Mutates a clone — the input is not modified.
+ *
+ * Returns a tuple of [shapedResult, summary] where shapedResult is the same
+ * shape as input but with the array replaced and a `_filter` summary
+ * appended at the same level so the model can see what was hidden.
+ */
+export declare function shapeEngineLogResponse(raw: unknown, opts?: FilterOptions): {
+    result: unknown;
+    summary: FilterSummary | null;
+};

package/dist/lib/log-filters.js

@@ -0,0 +1,130 @@
+const ERROR_TYPES = new Set(["error", "fatal", "critical"]);
+const WARNING_TYPES = new Set(["warning", "warn"]);
+const NOISE_TYPES = new Set(["info", "debug", "std", "stdout", "trace", "verbose"]);
+function entryKey(e) {
+    // Identical message + same type counts as a duplicate.
+    // Timestamps differ by frame, so they're excluded from the key.
+    const msg = (e.message ?? e.text ?? "").trim();
+    const type = (e.type ?? e.severity ?? e.level ?? "").toLowerCase();
+    return `${type}::${msg}`;
+}
+function entryLevel(e) {
+    const t = (e.type ?? e.severity ?? e.level ?? "").toLowerCase();
+    if (ERROR_TYPES.has(t))
+        return "error";
+    if (WARNING_TYPES.has(t))
+        return "warning";
+    if (NOISE_TYPES.has(t))
+        return "noise";
+    return "other";
+}
+export function filterAndDedupe(entries, opts = {}) {
+    const { errorsOnly = false, errorsOnlyStrict = false, maxEntries = 100, noDedupe = false } = opts;
+    const summary = {
+        totalIn: entries.length,
+        totalOut: 0,
+        duplicatesCollapsed: 0,
+        droppedByLevel: 0,
+        truncated: 0,
+    };
+    // Pass 1: level filter
+    let kept = entries;
+    if (errorsOnlyStrict || errorsOnly) {
+        kept = entries.filter((e) => {
+            const level = entryLevel(e);
+            if (errorsOnlyStrict)
+                return level === "error";
+            return level === "error" || level === "warning";
+        });
+        summary.droppedByLevel = entries.length - kept.length;
+    }
+    // Pass 2: dedupe consecutive identical entries
+    let deduped;
+    if (noDedupe) {
+        deduped = kept;
+    }
+    else {
+        deduped = [];
+        let lastKey = null;
+        let lastIdx = -1;
+        let runCount = 0;
+        for (const e of kept) {
+            const key = entryKey(e);
+            if (key === lastKey && lastIdx >= 0) {
+                runCount += 1;
+                const tagged = { ...deduped[lastIdx] };
+                tagged.duplicate_count = runCount;
+                const baseMsg = (tagged.message ?? tagged.text ?? "");
+                const stripped = baseMsg.replace(/\s*\(×\d+\)\s*$/, "");
+                if (tagged.message !== undefined)
+                    tagged.message = `${stripped} (×${runCount})`;
+                else if (tagged.text !== undefined)
+                    tagged.text = `${stripped} (×${runCount})`;
+                deduped[lastIdx] = tagged;
+                summary.duplicatesCollapsed += 1;
+            }
+            else {
+                deduped.push(e);
+                lastKey = key;
+                lastIdx = deduped.length - 1;
+                runCount = 1;
+            }
+        }
+    }
+    // Pass 3: truncate
+    let final = deduped;
+    if (deduped.length > maxEntries) {
+        final = deduped.slice(0, maxEntries);
+        summary.truncated = deduped.length - maxEntries;
+    }
+    summary.totalOut = final.length;
+    return { entries: final, summary };
+}
+const ENTRY_KEYS = ["messages", "errors", "entries", "items", "lines", "output"];
+/**
+ * Walks a parsed engine response and applies filterAndDedupe to the first
+ * recognized log-bearing array. Mutates a clone — the input is not modified.
+ *
+ * Returns a tuple of [shapedResult, summary] where shapedResult is the same
+ * shape as input but with the array replaced and a `_filter` summary
+ * appended at the same level so the model can see what was hidden.
+ */
+export function shapeEngineLogResponse(raw, opts = {}) {
+    if (!raw || typeof raw !== "object")
+        return { result: raw, summary: null };
+    const cloned = JSON.parse(JSON.stringify(raw));
+    const summary = applyToFirstArray(cloned, opts);
+    return { result: cloned, summary };
+}
+function applyToFirstArray(node, opts) {
+    if (!node || typeof node !== "object")
+        return null;
+    if (Array.isArray(node)) {
+        for (const item of node) {
+            if (item && typeof item === "object") {
+                const inner = applyToFirstArray(item, opts);
+                if (inner)
+                    return inner;
+            }
+        }
+        return null;
+    }
+    const obj = node;
+    for (const key of ENTRY_KEYS) {
+        const arr = obj[key];
+        if (Array.isArray(arr) && arr.length > 0 && typeof arr[0] === "object") {
+            const { entries, summary } = filterAndDedupe(arr, opts);
+            obj[key] = entries;
+            obj["_filter"] = summary;
+            return summary;
+        }
+    }
+    for (const v of Object.values(obj)) {
+        if (v && typeof v === "object") {
+            const inner = applyToFirstArray(v, opts);
+            if (inner)
+                return inner;
+        }
+    }
+    return null;
+}

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

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