summer-engine 1.2.0 → 1.2.1

package/dist/lib/agent-config.js

@@ -0,0 +1,284 @@
+import { existsSync } from "fs";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
+import { homedir } from "os";
+export const SUMMER_MCP_SERVER_NAME = "summer-engine";
+export const supportedAgents = [
+    "codex",
+    "claude-code",
+    "cursor",
+    "windsurf",
+];
+const agentAliases = {
+    claude: "claude-code",
+    "claude-code": "claude-code",
+    codex: "codex",
+    cursor: "cursor",
+    windsurf: "windsurf",
+};
+export function parseAgent(value) {
+    if (!value)
+        return null;
+    return agentAliases[value.trim().toLowerCase()] ?? null;
+}
+export function parseScope(value) {
+    if (!value)
+        return "user";
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "user" || normalized === "project")
+        return normalized;
+    return null;
+}
+export async function configureAgentMcp(options) {
+    const env = options.env ?? process.env;
+    const cwd = resolve(options.cwd ?? process.cwd());
+    const server = createSummerMcpServerConfig(Boolean(options.localDev));
+    const target = resolveConfigTarget(options.agent, options.scope, cwd, env);
+    const snippet = renderConfigSnippet(options.agent, server);
+    const dryRun = Boolean(options.dryRun);
+    const print = Boolean(options.print);
+    const shouldWrite = !dryRun && !print;
+    const update = print
+        ? { changed: true }
+        : target.format === "toml"
+            ? await upsertCodexConfig(target.path, server, shouldWrite)
+            : await upsertJsonMcpConfig(target.path, server, shouldWrite);
+    return {
+        agent: options.agent,
+        scope: options.scope,
+        path: target.path,
+        serverName: SUMMER_MCP_SERVER_NAME,
+        server,
+        format: target.format,
+        snippet,
+        changed: update.changed,
+        wrote: shouldWrite && update.changed,
+        dryRun,
+        print,
+        localDev: Boolean(options.localDev),
+        warnings: target.warnings,
+        nextSteps: createNextSteps(options.agent, options.scope, target.path),
+    };
+}
+export function createSummerMcpServerConfig(localDev) {
+    if (localDev) {
+        return {
+            command: "node",
+            args: [resolveLocalCliPath(), "mcp"],
+        };
+    }
+    return {
+        command: "npx",
+        args: ["summer-engine", "mcp"],
+    };
+}
+export function renderConfigSnippet(agent, server) {
+    if (agent === "codex") {
+        return renderCodexServerTable(server);
+    }
+    return (JSON.stringify({
+        mcpServers: {
+            [SUMMER_MCP_SERVER_NAME]: server,
+        },
+    }, null, 2) + "\n");
+}
+function resolveLocalCliPath() {
+    const thisFile = fileURLToPath(import.meta.url);
+    return resolve(dirname(thisFile), "..", "bin", "summer.js");
+}
+function resolveConfigTarget(agent, scope, cwd, env) {
+    const override = getConfigPathOverride(agent, env);
+    const warnings = [];
+    if (override) {
+        return {
+            path: resolve(override),
+            format: agent === "codex" ? "toml" : "json",
+            warnings,
+        };
+    }
+    if (agent === "codex") {
+        return {
+            path: scope === "user"
+                ? join(homedir(), ".codex", "config.toml")
+                : join(cwd, ".codex", "config.toml"),
+            format: "toml",
+            warnings,
+        };
+    }
+    if (agent === "claude-code") {
+        return {
+            path: scope === "user"
+                ? join(homedir(), ".claude.json")
+                : join(cwd, ".mcp.json"),
+            format: "json",
+            warnings,
+        };
+    }
+    if (agent === "cursor") {
+        return {
+            path: scope === "user"
+                ? join(homedir(), ".cursor", "mcp.json")
+                : join(cwd, ".cursor", "mcp.json"),
+            format: "json",
+            warnings,
+        };
+    }
+    if (scope === "project") {
+        warnings.push("Windsurf documents MCP configuration as user-scoped; project scope writes .windsurf/mcp_config.json for teams that load workspace config.");
+    }
+    return {
+        path: scope === "user"
+            ? join(homedir(), ".codeium", "windsurf", "mcp_config.json")
+            : join(cwd, ".windsurf", "mcp_config.json"),
+        format: "json",
+        warnings,
+    };
+}
+function getConfigPathOverride(agent, env) {
+    if (agent === "codex")
+        return env.SUMMER_CODEX_CONFIG_FILE;
+    if (agent === "claude-code")
+        return env.SUMMER_CLAUDE_CONFIG_FILE;
+    if (agent === "cursor")
+        return env.SUMMER_CURSOR_MCP_CONFIG_FILE;
+    return env.SUMMER_WINDSURF_MCP_CONFIG_FILE;
+}
+async function upsertJsonMcpConfig(path, server, write) {
+    const current = await readJsonConfig(path);
+    const next = copyJsonObject(current);
+    next.mcpServers = mergeMcpServers(next.mcpServers, server);
+    const currentRendered = renderJsonFile(current);
+    const nextRendered = renderJsonFile(next);
+    const changed = currentRendered !== nextRendered;
+    if (write && changed) {
+        await writeTextFile(path, nextRendered);
+    }
+    return { changed };
+}
+function mergeMcpServers(value, server) {
+    if (value !== undefined && !isJsonObject(value)) {
+        throw new Error("Existing mcpServers value must be a JSON object.");
+    }
+    return {
+        ...(isJsonObject(value) ? value : {}),
+        [SUMMER_MCP_SERVER_NAME]: server,
+    };
+}
+async function readJsonConfig(path) {
+    if (!existsSync(path))
+        return {};
+    let content;
+    try {
+        content = await readFile(path, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`Could not read ${path}: ${formatError(error)}`);
+    }
+    if (content.trim() === "")
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        throw new Error(`Could not parse JSON in ${path}: ${formatError(error)}`);
+    }
+    if (!isJsonObject(parsed)) {
+        throw new Error(`Expected ${path} to contain a JSON object.`);
+    }
+    return parsed;
+}
+async function upsertCodexConfig(path, server, write) {
+    const current = await readTextFileIfExists(path);
+    const next = upsertTomlTable(current, renderCodexServerTable(server));
+    const changed = current !== next;
+    if (write && changed) {
+        await writeTextFile(path, next);
+    }
+    return { changed };
+}
+async function readTextFileIfExists(path) {
+    if (!existsSync(path))
+        return "";
+    try {
+        return await readFile(path, "utf-8");
+    }
+    catch (error) {
+        throw new Error(`Could not read ${path}: ${formatError(error)}`);
+    }
+}
+function upsertTomlTable(content, table) {
+    const lines = content.split(/\r?\n/);
+    const serverHeader = /^\s*\[mcp_servers\.(?:"summer-engine"|summer-engine)(?:\.|\])/;
+    const start = lines.findIndex((line) => /^\s*\[mcp_servers\.(?:"summer-engine"|summer-engine)\]\s*(?:#.*)?$/.test(line));
+    if (start === -1) {
+        const trimmed = content.endsWith("\n") || content === "" ? content : `${content}\n`;
+        return `${trimmed}${trimmed === "" ? "" : "\n"}${table}`;
+    }
+    let end = lines.length;
+    for (let index = start + 1; index < lines.length; index += 1) {
+        if (/^\s*\[/.test(lines[index]) && !serverHeader.test(lines[index])) {
+            end = index;
+            break;
+        }
+    }
+    const replacement = table.trimEnd().split("\n");
+    if (lines[end] && lines[end].trim() !== "") {
+        replacement.push("");
+    }
+    const nextLines = [
+        ...lines.slice(0, start),
+        ...replacement,
+        ...lines.slice(end),
+    ];
+    return ensureTrailingNewline(nextLines.join("\n"));
+}
+function renderCodexServerTable(server) {
+    const lines = [
+        `[mcp_servers.${SUMMER_MCP_SERVER_NAME}]`,
+        `command = ${tomlString(server.command)}`,
+        `args = [${server.args.map(tomlString).join(", ")}]`,
+    ];
+    if (server.env && Object.keys(server.env).length > 0) {
+        lines.push(`env = { ${Object.entries(server.env)
+            .map(([key, value]) => `${key} = ${tomlString(value)}`)
+            .join(", ")} }`);
+    }
+    return `${lines.join("\n")}\n`;
+}
+function tomlString(value) {
+    return JSON.stringify(value);
+}
+function renderJsonFile(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function copyJsonObject(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+async function writeTextFile(path, content) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    await writeFile(path, content, { encoding: "utf-8", mode: 0o600 });
+}
+function ensureTrailingNewline(value) {
+    return value.endsWith("\n") ? value : `${value}\n`;
+}
+function createNextSteps(agent, scope, path) {
+    const restart = agent === "claude-code"
+        ? "Restart Claude Code or run /mcp in a new session."
+        : agent === "codex"
+            ? "Restart Codex or run /mcp in a new session."
+            : agent === "cursor"
+                ? "Restart Cursor and enable the summer-engine MCP server if prompted."
+                : "Restart Windsurf and refresh MCP servers from Cascade settings.";
+    const projectTrust = scope === "project" && agent === "codex"
+        ? "Codex only loads project .codex/config.toml from trusted projects."
+        : null;
+    return [projectTrust, `Updated ${path}.`, restart].filter((step) => Boolean(step));
+}
+function formatError(error) {
+    return error instanceof Error ? error.message : String(error);
+}

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

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

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

@@ -0,0 +1,80 @@
+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/api-client.d.ts

@@ -1,3 +1,18 @@
+export type EngineSnapshot = {
+    ok: boolean;
+    localPath?: string;
+    path?: string;
+    width?: number;
+    height?: number;
+    format?: string;
+    mime?: string;
+    context?: string;
+    op?: string;
+    provenance?: unknown;
+    bytes?: number;
+    error?: string;
+    metadata?: Record<string, unknown>;
+};
 export declare class EngineApiClient {
     private port;
     private token;
@@ -17,7 +32,9 @@ export declare class EngineApiClient {
     readFile(path: string, maxBytes?: number): Promise<unknown>;
     getFsTree(root?: string, limit?: number): Promise<unknown>;
     getSelection(): Promise<unknown>;
-    viewportSnapshot(): Promise<Buffer>;
-    gameSnapshot(): Promise<Buffer>;
+    private writeSnapshotFile;
+    private snapshot;
+    viewportSnapshot(): Promise<EngineSnapshot>;
+    gameSnapshot(): Promise<EngineSnapshot>;
     getPort(): number;
 }

package/dist/lib/api-client.js

@@ -1,4 +1,64 @@
+import { mkdir, writeFile } from "fs/promises";
+import { tmpdir } from "os";
+import { join } from "path";
 import { getApiToken, getApiPort, checkEngineHealth } from "./engine.js";
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringFrom(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function numberFrom(value) {
+    return typeof value === "number" ? value : undefined;
+}
+function findSnapshotPayload(value) {
+    const record = asRecord(value);
+    if (!record)
+        return null;
+    if (typeof record.base64 === "string" ||
+        typeof record.image_base64 === "string" ||
+        record.op === "ViewportSnapshot" ||
+        record.op === "GameSnapshot") {
+        return record;
+    }
+    if (Array.isArray(record.results)) {
+        for (const result of record.results) {
+            const payload = findSnapshotPayload(result);
+            if (payload)
+                return payload;
+        }
+    }
+    return findSnapshotPayload(record.data);
+}
+function snapshotFormat(payload) {
+    const explicitMime = stringFrom(payload.mime)?.toLowerCase();
+    const explicitFormat = stringFrom(payload.format)?.toLowerCase();
+    const format = explicitFormat ??
+        (explicitMime?.includes("png")
+            ? "png"
+            : explicitMime?.includes("webp")
+                ? "webp"
+                : "jpeg");
+    const mime = explicitMime ??
+        (format === "png"
+            ? "image/png"
+            : format === "webp"
+                ? "image/webp"
+                : "image/jpeg");
+    const ext = format === "jpeg" ? "jpg" : format;
+    return { format, mime, ext };
+}
+function withoutImageData(payload) {
+    const metadata = {};
+    for (const [key, value] of Object.entries(payload)) {
+        if (key !== "base64" && key !== "image_base64") {
+            metadata[key] = value;
+        }
+    }
+    return metadata;
+}
 export class EngineApiClient {
     port;
     token;
@@ -82,25 +142,80 @@ export class EngineApiClient {
     async getSelection() {
         return this.request("GET", "/api/state/selection");
     }
-    async viewportSnapshot() {
-        const url = `http://127.0.0.1:${this.port}/api/snapshot/viewport`;
+    async writeSnapshotFile(kind, buffer, ext) {
+        const dir = join(tmpdir(), "summer-engine", "snapshots");
+        await mkdir(dir, { recursive: true });
+        const filename = `${kind}-${Date.now()}-${Math.random()
+            .toString(36)
+            .slice(2, 8)}.${ext}`;
+        const localPath = join(dir, filename);
+        await writeFile(localPath, buffer);
+        return localPath;
+    }
+    async snapshot(kind) {
+        const url = `http://127.0.0.1:${this.port}/api/snapshot/${kind}`;
         const res = await fetch(url, {
             headers: { Authorization: `Bearer ${this.token}` },
-            signal: AbortSignal.timeout(15000),
+            signal: AbortSignal.timeout(30000),
         });
-        if (!res.ok)
-            throw new Error(`Viewport snapshot failed: ${res.status}`);
-        return Buffer.from(await res.arrayBuffer());
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            throw new Error(`Snapshot failed ${res.status}: ${text.slice(0, 200)}`);
+        }
+        const contentType = res.headers.get("content-type") ?? "";
+        if (!contentType.toLowerCase().includes("application/json")) {
+            const { format, mime, ext } = snapshotFormat({ mime: contentType });
+            const buffer = Buffer.from(await res.arrayBuffer());
+            const localPath = await this.writeSnapshotFile(kind, buffer, ext);
+            return {
+                ok: true,
+                localPath,
+                path: localPath,
+                format,
+                mime,
+                context: kind === "viewport" ? "scene" : "game",
+                bytes: buffer.byteLength,
+            };
+        }
+        const response = await res.json();
+        const payload = findSnapshotPayload(response);
+        if (!payload) {
+            return {
+                ok: false,
+                error: "Snapshot response did not include a viewport/game payload.",
+            };
+        }
+        const base64 = stringFrom(payload.base64) ?? stringFrom(payload.image_base64);
+        if (!base64) {
+            return {
+                ok: false,
+                error: stringFrom(payload.error) ?? "Snapshot response did not include image data.",
+                metadata: withoutImageData(payload),
+            };
+        }
+        const { format, mime, ext } = snapshotFormat(payload);
+        const buffer = Buffer.from(base64, "base64");
+        const localPath = await this.writeSnapshotFile(kind, buffer, ext);
+        return {
+            ok: payload.ok !== false,
+            localPath,
+            path: localPath,
+            width: numberFrom(payload.width),
+            height: numberFrom(payload.height),
+            format,
+            mime,
+            context: stringFrom(payload.context),
+            op: stringFrom(payload.op),
+            provenance: payload.provenance,
+            bytes: buffer.byteLength,
+            metadata: withoutImageData(payload),
+        };
+    }
+    async viewportSnapshot() {
+        return this.snapshot("viewport");
     }
     async gameSnapshot() {
-        const url = `http://127.0.0.1:${this.port}/api/snapshot/game`;
-        const res = await fetch(url, {
-            headers: { Authorization: `Bearer ${this.token}` },
-            signal: AbortSignal.timeout(15000),
-        });
-        if (!res.ok)
-            throw new Error(`Game snapshot failed: ${res.status}`);
-        return Buffer.from(await res.arrayBuffer());
+        return this.snapshot("game");
     }
     getPort() {
         return this.port;

package/dist/lib/skills-registry.d.ts

@@ -0,0 +1,69 @@
+export declare const AGENT_CLIENTS: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+export type AgentClient = (typeof AGENT_CLIENTS)[number];
+export type SkillCategory = "workflow" | "scripting" | "scene" | "gameplay" | "lighting" | "assets" | "ui";
+export interface SkillRegistryEntry {
+    name: string;
+    public: boolean;
+    category: SkillCategory;
+    clients: readonly AgentClient[];
+    recommended: boolean;
+    requiresMcpTools: readonly string[];
+    testScenario: string;
+}
+export declare const SKILL_REGISTRY: readonly [{
+    readonly name: "gdscript-patterns";
+    readonly public: true;
+    readonly category: "scripting";
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_set_prop", "summer_connect_signal", "summer_input_map_bind", "summer_get_script_errors"];
+    readonly testScenario: "Create a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.";
+}, {
+    readonly name: "scene-composition";
+    readonly public: true;
+    readonly category: "scene";
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_create_scene", "summer_open_scene", "summer_get_scene_tree", "summer_add_node", "summer_instantiate_scene", "summer_save_scene"];
+    readonly testScenario: "Build a small reusable player scene, instantiate it in a main scene, and save both scenes through Summer tools.";
+}, {
+    readonly name: "fps-controller";
+    readonly public: true;
+    readonly category: "gameplay";
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_add_node", "summer_set_prop", "summer_set_resource_property", "summer_input_map_bind"];
+    readonly testScenario: "Create a CharacterBody3D player with collision, camera, input actions, and a host-edited controller script.";
+}, {
+    readonly name: "3d-lighting";
+    readonly public: true;
+    readonly category: "lighting";
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_add_node", "summer_set_prop", "summer_set_resource_property"];
+    readonly testScenario: "Add sun, fill lighting, WorldEnvironment, and shadow settings to a simple 3D scene.";
+}, {
+    readonly name: "ui-basics";
+    readonly public: true;
+    readonly category: "ui";
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_add_node", "summer_set_prop", "summer_connect_signal"];
+    readonly testScenario: "Create a HUD CanvasLayer with labels, a ProgressBar, and a connected Button signal.";
+}, {
+    readonly name: "asset-strategy";
+    readonly public: true;
+    readonly category: "assets";
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: true;
+    readonly requiresMcpTools: readonly ["summer_search_assets", "summer_import_asset", "summer_import_from_url", "summer_generate_image", "summer_generate_3d", "summer_generate_audio"];
+    readonly testScenario: "Choose library, generated, or primitive assets for a small level and import one asset into the project.";
+}, {
+    readonly name: "make-game";
+    readonly public: true;
+    readonly category: "workflow";
+    readonly clients: readonly ["summer", "codex", "claude-code", "cursor", "windsurf"];
+    readonly recommended: false;
+    readonly requiresMcpTools: readonly ["summer_get_agent_playbook", "summer_get_project_context", "summer_create_scene", "summer_open_scene", "summer_save_scene", "summer_add_node", "summer_set_prop", "summer_set_resource_property", "summer_instantiate_scene", "summer_play", "summer_stop", "summer_get_diagnostics"];
+    readonly testScenario: "Build one narrow playable prototype from requirements through scene setup, host-edited scripts, and diagnostics.";
+}];