summer-engine 1.2.0 → 1.3.0

package/dist/lib/skills-registry.js

@@ -0,0 +1,143 @@
+export const AGENT_CLIENTS = [
+    "summer",
+    "codex",
+    "claude-code",
+    "cursor",
+    "windsurf",
+];
+export const SKILL_CATEGORIES = [
+    "_meta",
+    "character-controllers",
+    "gameplay-mechanics",
+    "scripting-patterns",
+    "scene-and-project",
+    "rendering-and-lighting",
+    "shaders",
+    "visual-effects",
+    "post-processing",
+    "animation",
+    "audio",
+    "physics",
+    "multiplayer-and-networking",
+    "ai-and-npcs",
+    "level-design",
+    "performance",
+    "ui-and-ux",
+    "asset-pipeline",
+    "input-and-controls",
+    "debugging",
+    "deployment",
+];
+const ALL_CLIENTS = AGENT_CLIENTS;
+/**
+ * Skills with `status: HAVE` in catalog.yaml. The catalog is the planning source
+ * of truth (~85 skills); this TS registry is the install-time list (only skills
+ * with shippable content). When a NEXT skill ships, mirror it here.
+ */
+export const SKILL_REGISTRY = [
+    {
+        name: "gdscript-patterns",
+        category: "scripting-patterns",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_get_script_errors",
+        ],
+        testScenario: "Write a typed GDScript with a signal, attach it to a node, connect the signal, and verify script errors.",
+    },
+    {
+        name: "scene-composition",
+        category: "scene-and-project",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_create_scene",
+            "summer_open_scene",
+            "summer_get_scene_tree",
+            "summer_add_node",
+            "summer_instantiate_scene",
+            "summer_save_scene",
+        ],
+        testScenario: "Build a small reusable player scene, instantiate it in a main scene, and save both scenes through Summer tools.",
+    },
+    {
+        name: "fps-controller",
+        category: "character-controllers",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_add_node",
+            "summer_set_prop",
+            "summer_set_resource_property",
+            "summer_input_map_bind",
+        ],
+        testScenario: "Create a CharacterBody3D player with collision, camera, input actions, and a host-edited controller script.",
+    },
+    {
+        name: "3d-lighting",
+        category: "rendering-and-lighting",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_add_node",
+            "summer_set_prop",
+            "summer_set_resource_property",
+        ],
+        testScenario: "Add sun, fill lighting, WorldEnvironment, and shadow settings to a simple 3D scene.",
+    },
+    {
+        name: "ui-basics",
+        category: "ui-and-ux",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_add_node",
+            "summer_set_prop",
+            "summer_connect_signal",
+        ],
+        testScenario: "Create a HUD CanvasLayer with labels, a ProgressBar, and a connected Button signal.",
+    },
+    {
+        name: "asset-strategy",
+        category: "asset-pipeline",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: true,
+        requiresMcpTools: [
+            "summer_search_assets",
+            "summer_import_asset",
+            "summer_import_from_url",
+            "summer_generate_image",
+            "summer_generate_3d",
+            "summer_generate_audio",
+        ],
+        testScenario: "Choose library, generated, or primitive assets for a small level and import one asset into the project.",
+    },
+    {
+        name: "make-game",
+        category: "scene-and-project",
+        public: true,
+        clients: ALL_CLIENTS,
+        recommended: false,
+        requiresMcpTools: [
+            "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",
+        ],
+        testScenario: "Build one narrow playable prototype from requirements through scene setup, host-edited scripts, and diagnostics.",
+    },
+];

package/dist/mcp/tools/project-tools.js

@@ -1,18 +1,83 @@
 import { z } from "zod";
 import { withEngine } from "./with-engine.js";
-import { readFile } from "fs/promises";
-import { join } from "path";
-async function readMainSceneFromProject(projectPath) {
-    if (!projectPath)
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringFrom(value) {
+    return typeof value === "string" && value.length > 0 ? value : null;
+}
+function pickString(record, keys) {
+    if (!record)
         return null;
-    try {
-        const text = await readFile(join(projectPath, "project.godot"), "utf-8");
-        const match = text.match(/run\/main_scene="([^"]+)"/);
-        return match?.[1] ?? null;
+    for (const key of keys) {
+        const value = stringFrom(record[key]);
+        if (value)
+            return value;
     }
-    catch {
+    return null;
+}
+function getProjectData(projectState) {
+    return asRecord(asRecord(projectState)?.data);
+}
+function getProjectSetting(projectState, keys) {
+    const data = getProjectData(projectState);
+    const entries = data?.entries;
+    if (!Array.isArray(entries))
         return null;
+    for (const entry of entries) {
+        const item = asRecord(entry);
+        const key = stringFrom(item?.key);
+        if (key && keys.includes(key)) {
+            return stringFrom(item?.value);
+        }
     }
+    return null;
+}
+function getProjectPath(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, [
+        "projectPath",
+        "project_path",
+        "projectRoot",
+        "project_root",
+        "rootPath",
+        "root_path",
+    ]) ??
+        pickString(root, ["projectPath", "project_path", "projectRoot", "project_root"]) ??
+        null);
+}
+function getProjectName(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, ["projectName", "project_name", "name"]) ??
+        pickString(root, ["projectName", "project_name", "name"]) ??
+        getProjectSetting(projectState, ["application/config/name", "config/name"]));
+}
+function getMainScene(projectState) {
+    const root = asRecord(projectState);
+    const data = getProjectData(projectState);
+    return (pickString(data, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
+        pickString(root, ["mainScene", "main_scene", "mainScenePath", "main_scene_path"]) ??
+        getProjectSetting(projectState, [
+            "application/run/main_scene",
+            "run/main_scene",
+        ]));
+}
+function getCurrentScene(projectState, sceneState) {
+    const sceneRoot = asRecord(sceneState);
+    const sceneData = asRecord(sceneRoot?.data);
+    const sceneProvenance = asRecord(sceneRoot?.provenance);
+    const projectRoot = asRecord(projectState);
+    const projectData = getProjectData(projectState);
+    const projectProvenance = asRecord(projectRoot?.provenance);
+    return (pickString(sceneProvenance, ["scenePath", "scene_path"]) ??
+        pickString(sceneData, ["scenePath", "scene_path", "currentScene", "current_scene"]) ??
+        pickString(projectData, ["currentScene", "current_scene", "scenePath", "scene_path"]) ??
+        pickString(projectProvenance, ["scenePath", "scene_path"]) ??
+        null);
 }
 export function registerProjectTools(server) {
     server.tool("summer_get_agent_playbook", `AI-first operating guide for Summer Engine MCP.
@@ -25,7 +90,8 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                 text: JSON.stringify({
                     startupChecklist: [
                         "Decide first: file edit or engine operation.",
-                        "For normal code/content edits (.gd/.tscn/.tres/.ts), use host file-edit tools directly.",
+                        "Write .gd/.cs/.json/docs/simple config with host file-edit tools directly.",
+                        "Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, screenshots/verification.",
                         "Call summer_get_project_context first.",
                         "If no scene is open, call summer_open_main_scene.",
                         "Call summer_get_scene_tree before structural edits.",
@@ -33,15 +99,16 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
                     ],
                     safeDefaults: [
                         "Never guess scene filenames (main.tscn/Main.tscn).",
-                        "Do not route ordinary code edits through MCP when direct file tools are available.",
+                        "Do not route ordinary script, JSON, docs, or simple config edits through MCP 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 ops.",
+                        "Use MCP for scene-tree mutations and inspector-visible values instead of hand-editing live scene state.",
                     ],
                     preferredFlow: [
                         "summer_get_project_context",
                         "summer_open_main_scene (if needed)",
                         "summer_get_scene_tree",
                         "edit via summer_add_node / summer_set_prop / summer_set_resource_property",
+                        "write scripts/data/docs/simple config directly with host file-edit tools",
                         "summer_save_scene",
                         "summer_get_diagnostics",
                     ],
@@ -56,35 +123,45 @@ It returns the safe workflow, anti-patterns, and recovery steps.`, {}, async ()
     }));
     server.tool("summer_get_project_context", `Get essential project context before editing. Returns:
 - engine health/status
-- project name and path
+- project name and project path when exposed by project state
 - current scene path (if available)
-- main scene path from project.godot
+- main scene path from project settings
 
 Use this first in every fresh chat to avoid guessing scene filenames or editing the wrong scene.`, {}, async () => withEngine(async (client) => {
-        const [health, projectState] = await Promise.all([
+        const [health, projectState, sceneState] = await Promise.all([
             client.health(),
             client.getProjectState(),
+            client.getSceneState().catch((err) => ({
+                ok: false,
+                error: err instanceof Error ? err.message : String(err),
+            })),
         ]);
-        const healthObj = (health ?? {});
-        const mainScene = await readMainSceneFromProject(typeof healthObj.project_path === "string" ? healthObj.project_path : undefined);
+        const projectPath = getProjectPath(projectState);
+        const projectName = getProjectName(projectState);
+        const mainScene = getMainScene(projectState);
+        const currentScene = getCurrentScene(projectState, sceneState);
         return {
             health,
             project: projectState,
+            scene: sceneState,
+            projectName,
+            projectPath,
+            currentScene,
             mainScene,
             guidance: mainScene
                 ? "Use `summer_open_scene` with `mainScene` if no scene is open."
-                : "Main scene not found in project.godot. Open a known scene path explicitly.",
+                : "Main scene not found in project state. Open a known scene path explicitly.",
+            fileEditingGuidance: "Write .gd/.cs/.json/docs/simple config directly with host file tools. Use MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.",
         };
     }));
-    server.tool("summer_open_main_scene", `Open the project's configured main scene from project.godot.
+    server.tool("summer_open_main_scene", `Open the project's configured main scene from project settings.
 
 Safer than guessing scene names like main.tscn/Main.tscn.
 Call this when you get "no scene open".`, {}, async () => withEngine(async (client) => {
-        const health = (await client.health());
-        const projectPath = typeof health.project_path === "string" ? health.project_path : undefined;
-        const mainScene = await readMainSceneFromProject(projectPath);
+        const projectState = await client.getProjectState();
+        const mainScene = getMainScene(projectState);
         if (!mainScene) {
-            throw new Error("Could not resolve application/run/main_scene from project.godot. Call `summer_get_project_context` and open a scene explicitly.");
+            throw new Error("Could not resolve application/run/main_scene from project state. Call `summer_get_project_context` and open a scene explicitly.");
         }
         return client.executeOps([{ op: "OpenScene", path: mainScene }]);
     }));

package/dist/mcp/tools/with-engine.js

@@ -1,10 +1,10 @@
 import { getClient, resetClient } from "../server.js";
-import { getAuthToken } from "../../lib/auth.js";
-const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
 function extractOpError(result) {
     if (!result || typeof result !== "object")
         return null;
     const op = result;
+    if (op.ok === false && op.error)
+        return op.error;
     if (op.status === "error" && op.error)
         return op.error;
     const firstFailed = op.results?.find((r) => r.ok === false && r.error);
@@ -19,62 +19,12 @@ function buildActionHint(message) {
         return "Scene path could not be opened. Call `summer_get_project_context` to get `mainScene`, then open that exact path. Avoid guessing scene filenames.";
     }
     if (normalized.includes("writefile cannot edit .tscn/.scn")) {
-        return "This MCP operation cannot write .tscn/.scn directly. If your host AI has normal file-edit tools, edit .gd/.tscn files there; use Summer MCP for engine/state/scene-tree operations.";
+        return "Write .gd/.cs/.json/docs/simple config files with normal file-edit tools. Use Summer MCP for live scene state, inspector/node edits, imports, play/stop, diagnostics, and visual verification.";
     }
     return null;
 }
-async function checkMcpQuota() {
-    const token = await getAuthToken();
-    if (!token) {
-        return {
-            allowed: false,
-            message: "Not signed in. The user needs to run this in their terminal:\n  npx summer-engine login\nOr open: https://www.summerengine.com/login\nMCP 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(() => ({})));
-        // Hard enforcement errors should block tool execution.
-        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 || "MCP call limit reached. Upgrade at https://summerengine.com/pricing",
-            };
-        }
-        return { allowed: true };
-    }
-    catch (err) {
-        // Network/transient errors should not brick local MCP usage.
-        return { allowed: true };
-    }
-}
 export async function withEngine(fn) {
     try {
-        const quota = await checkMcpQuota();
-        if (!quota.allowed) {
-            return {
-                content: [{ type: "text", text: quota.message || "Quota exceeded" }],
-                isError: true,
-            };
-        }
         const client = await getClient();
         const result = await fn(client);
         const opError = extractOpError(result);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "summer-engine",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "CLI and MCP tools for Summer Engine — the AI-native game engine",
   "keywords": [
     "game-engine",
@@ -31,6 +31,8 @@
     "build": "tsc",
     "dev": "tsc --watch",
     "summer": "node dist/bin/summer.js",
+    "test": "vitest run",
+    "test:watch": "vitest",
     "prepublishOnly": "npm run build"
   },
   "engines": {
@@ -48,6 +50,7 @@
   "devDependencies": {
     "@types/diff": "^7.0.0",
     "@types/node": "^20.0.0",
-    "typescript": "^5.5.0"
+    "typescript": "^5.5.0",
+    "vitest": "^3.2.4"
   }
 }

package/skills/README.md

@@ -0,0 +1,96 @@
+# Summer Skill Library
+
+The canonical agent-readable game-dev knowledge source for Claude Code, Cursor, Codex, and Windsurf.
+
+When an agent is asked to make a game in Godot, this is what it reads to learn how.
+
+## Layout
+
+```
+skills/
+├── README.md                  # this file
+├── catalog.yaml               # canonical registry (name, category, status, template-id)
+├── _shared/                   # cross-skill references every skill can link
+│   ├── godot-version.md
+│   ├── mcp-tools-reference.md
+│   ├── collaborative-protocol.md
+│   ├── template-registry.md
+│   └── gd-style.md
+├── _meta/
+│   ├── skill-test/            # static + behavioral linter
+│   ├── skill-create/          # bootstrap a new skill
+│   └── skill-improve/         # eval-harness iteration
+├── _tests/
+│   ├── runner.md              # how /skill-test works
+│   └── specs/                 # behavioral specs per skill
+└── <category>/<skill>/
+    ├── SKILL.md               # < 500 lines, frontmatter + body
+    ├── references/            # loaded on demand
+    ├── examples/              # working snippets
+    └── tests/spec.md          # behavioral spec
+```
+
+## Categories (20)
+
+`character-controllers`, `gameplay-mechanics`, `scripting-patterns`, `scene-and-project`, `rendering-and-lighting`, `shaders`, `visual-effects`, `post-processing`, `animation`, `audio`, `physics`, `multiplayer-and-networking`, `ai-and-npcs`, `level-design`, `performance`, `ui-and-ux`, `asset-pipeline`, `input-and-controls`, `debugging`, `deployment`.
+
+## Standard
+
+Adopts the **Anthropic Agent Skills open standard** (`agentskills.io`). Frontmatter:
+
+```yaml
+---
+name: <kebab-case>
+description: <when-to-use, key trigger phrases first>
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: <one of the 20>
+template-id: <optional, resolved against _shared/template-registry.md>
+allowed-tools: Read Grep summer_add_node summer_set_prop ...
+paths: ["**/*.gd", "**/*.tscn"]
+---
+```
+
+Cross-portable. Cursor / Codex / Windsurf understand the same SKILL.md.
+
+## Authoring rules
+
+1. **SKILL.md ≤ 500 lines.** Push detail into `references/`. Progressive disclosure.
+2. **MCP-preferred + file-edit-fallback.** Every code-touching skill must show both paths so the skill works without Summer MCP installed.
+3. **Collaborative protocol.** "May I write…?" before any user-visible mutation. See `_shared/collaborative-protocol.md`.
+4. **Template cross-link.** When a working starter exists, link via `template-id` and the section "Want a working starter?".
+5. **Test spec.** Every non-`_meta` skill ships `tests/spec.md` with at least one Test Case.
+
+## Adding a new skill
+
+```
+/skill-create
+```
+
+(See `_meta/skill-create/SKILL.md`.)
+
+## Testing
+
+```
+/skill-test <name>           # static lint
+/skill-test <name> spec      # behavioral spec runner
+/skill-test audit            # whole-library audit
+/skill-improve <name>        # parallel-eval harness for iteration
+```
+
+(See `_meta/skill-test/SKILL.md` and `_tests/runner.md`.)
+
+## Roadmap
+
+Status legend in `catalog.yaml`:
+
+- **HAVE** — ships today.
+- **NEXT** — next wave, in active development.
+- **LATER** — on roadmap.
+
+Currently: **7 HAVE / ~50 NEXT / ~30 LATER ≈ 85 skills across 20 categories**. Subagents fill content category by category.
+
+## See also
+
+- [Architecture spec](../../../publicsummerengine/Docs/superpowers/specs/2026-05-05-skill-library-architecture.md) (lives in publicsummerengine for spec history)
+- [Research notes](../../../publicsummerengine/Docs/superpowers/research/2026-05-05-skill-library-research.md)

package/skills/_meta/skill-create/SKILL.md

@@ -0,0 +1,143 @@
+---
+name: skill-create
+description: Bootstrap a new Summer skill with the canonical folder structure, frontmatter, and stub sections. Use when adding a new skill to the library. Trigger on "create skill", "add skill", "new skill".
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: _meta
+allowed-tools: Read Write Glob Grep
+---
+
+# /skill-create — Bootstrap a New Skill
+
+## Steps
+
+### 1. Get the basics
+
+Ask the user:
+- **Name** (kebab-case, ≤ 64 chars). Example: `state-machine-patterns`.
+- **Category** (one of the 20 in `catalog.yaml`). Example: `scripting-patterns`.
+- **One-sentence description** for the frontmatter.
+- **Template-id** (optional). Lookup against `_shared/template-registry.md`.
+
+### 2. Create the folder
+
+May I create `skills/<category>/<name>/` with this structure?
+
+```
+skills/<category>/<name>/
+├── SKILL.md
+├── references/        (empty, populate as needed)
+├── examples/          (empty, populate as needed)
+└── tests/spec.md
+```
+
+### 3. Write SKILL.md (template)
+
+```markdown
+---
+name: <name>
+description: <one-sentence what + when. Lead with key trigger phrases.>
+license: MIT
+compatibility: [Cursor, Claude Code, Windsurf, Codex]
+category: <category>
+template-id: <optional template-id from _shared/template-registry.md>
+allowed-tools: Read Grep <summer_* tools this skill uses>
+paths: ["**/*.gd", "**/*.tscn"]
+---
+
+# <Title> for Summer Engine
+
+<One-paragraph context. Why this exists, who needs it.>
+
+## Steps
+
+### 1. <First step>
+
+**Preferred (Summer MCP):**
+
+\`\`\`
+summer_<tool>(...)
+\`\`\`
+
+**Fallback (no MCP — edit `<file>` directly):**
+
+\`\`\`
+<raw text/code>
+\`\`\`
+
+May I <action>?
+
+### 2. <Second step>
+
+...
+
+## Common mistakes
+
+- <mistake 1, with one-line fix>
+- <mistake 2, with one-line fix>
+
+## Want a working starter?
+
+→ **template-id**: `<template-id>`
+→ **Repo**: <github URL from _shared/template-registry.md>
+→ **Bootstrap**: `summer template clone <template-id> my-game`
+
+## See also
+
+- `_shared/godot-version.md`
+- `_shared/mcp-tools-reference.md`
+- `_shared/gd-style.md`
+- (other relevant skills)
+```
+
+### 4. Write tests/spec.md (template)
+
+```markdown
+# Skill Spec: /<name>
+
+## Fixture
+- <starting state of the project>
+- <which tools are available — Summer MCP yes/no>
+
+## Case 1: Happy Path
+**Input:** "<typical user prompt>"
+**Expected MCP tool sequence (in order):**
+1. <first tool call>
+2. <second>
+
+**Assertions:**
+- [ ] <observable outcome>
+- [ ] <skill asks "May I" before any write step>
+
+## Case 2: Failure / Edge
+**Fixture:** <something different>
+**Input:** "<edge prompt>"
+**Expected:** <how the skill should adapt>
+```
+
+### 5. Register in catalog.yaml
+
+Append:
+
+```yaml
+  - name: <name>
+    category: <category>
+    status: NEXT  # or HAVE if shipping immediately
+    template-id: <or omit>
+    public: true
+    recommended: false  # flip to true when status: HAVE and tested
+```
+
+### 6. Run /skill-test in static mode
+
+Confirm the new skill passes the 7 structural checks before commit.
+
+## Collaborative protocol
+
+This skill writes files (the new skill folder + catalog update). Always ask before each write step.
+
+## See also
+
+- `_shared/collaborative-protocol.md`
+- `_meta/skill-test/SKILL.md`
+- `catalog.yaml`