summer-engine 1.2.0 → 1.2.1

package/README.md

@@ -1,6 +1,6 @@
 # Summer Engine CLI
 
-CLI and MCP tools for [Summer Engine](https://summerengine.com) — the AI-native game engine.
+CLI and MCP tools for [Summer Engine](https://summerengine.com) — the AI-native game engine. MIT licensed.
 
 ## Install
 
@@ -14,6 +14,28 @@ Or use without installing:
 npx summer-engine <command>
 ```
 
+## Quickstart (under 2 minutes)
+
+```bash
+summer install                       # Download the engine
+summer login                         # Sign in via browser
+summer create 3d-basic my-game       # Create a starter project
+summer run my-game                   # Open it in the engine
+summer setup claude-code --yes       # Configure MCP + install recommended skills
+```
+
+Replace `claude-code` with `codex`, `cursor`, or `windsurf`. Add `--scope project` to keep the configuration inside the project.
+
+Verify:
+
+```bash
+summer doctor
+```
+
+Then open your agent and try the verification prompt:
+
+> Use Summer Engine MCP. First call `summer_get_project_context` and `summer_get_agent_playbook`, then add a `DirectionalLight3D` and `Camera3D` to the main scene, save it, and check diagnostics.
+
 ## Commands
 
 | Command | Description |
@@ -22,29 +44,25 @@ npx summer-engine <command>
 | `summer login` | Sign in via browser (Google/GitHub) |
 | `summer logout` | Clear auth tokens |
 | `summer status` | Check engine status, port, auth state |
+| `summer doctor` | Diagnose Node, login, engine, local API, MCP boot |
 | `summer run [path]` | Launch engine (optionally with a project) |
 | `summer open <path>` | Open a project in the running engine |
 | `summer create <template> [name]` | Create new project from template |
-| `summer list templates` | Show available templates |
-| `summer list projects` | Show local projects |
-| `summer skills list` | Show available skills (best-practice guides) |
-| `summer skills install <name>` | Install a skill for AI agents to use |
-| `summer mcp` | Start MCP server (used by Cursor/Claude Code) |
+| `summer list templates \| projects` | List available templates or local projects |
+| `summer skills list` | Show available skills |
+| `summer skills install <name>` | Install one skill |
+| `summer skills install --recommended --agent <agent>` | Install the recommended set |
+| `summer mcp` | Start the MCP server (used by Codex/Cursor/Claude Code/Windsurf) |
+| `summer mcp setup <agent>` | Write MCP config for an agent |
+| `summer setup <agent>` | One shot: MCP config + recommended skills + doctor |
 
-## Quick Start
-
-```bash
-summer install          # Download the engine
-summer login            # Sign in
-summer create 3d-basic my-game   # Create a project
-summer run my-game      # Open it in the engine
-```
+Supported agents: `codex`, `claude-code`, `cursor`, `windsurf`. Supported scopes: `user` (default), `project`.
 
 ## MCP Integration
 
-Use Summer Engine with Cursor, Claude Code, or any MCP-compatible AI tool.
+`summer setup <agent>` writes the right config in the right place. If you need to do it by hand:
 
-**Cursor** (`.cursor/mcp.json`):
+**Cursor** (`.cursor/mcp.json` per project, or `~/.cursor/mcp.json` user-wide):
 
 ```json
 {
@@ -57,7 +75,7 @@ Use Summer Engine with Cursor, Claude Code, or any MCP-compatible AI tool.
 }
 ```
 
-**Claude Code** (`~/.claude/claude_code_config.json`):
+**Claude Code** (`~/.claude.json` user-wide, or `.mcp.json` per project):
 
 ```json
 {
@@ -70,18 +88,34 @@ Use Summer Engine with Cursor, Claude Code, or any MCP-compatible AI tool.
 }
 ```
 
-The MCP server exposes 24 focused tools for scene manipulation, debugging, project settings, and asset search — only things AI tools can't do on their own.
+**Codex** (`~/.codex/config.toml`):
 
-**Visual feedback** (viewport and game screenshots) is currently available in the Summer Engine app via the built-in Summer Agent. MCP support for screenshots is in development.
+```toml
+[mcp_servers.summer-engine]
+command = "npx"
+args = ["summer-engine", "mcp"]
+```
+
+The MCP server exposes focused tools for scene manipulation, inspector/resource ops, project settings, asset import, play/stop, diagnostics, and asset search/generation. Tools the host agent already has natively (file ops, git, shell, grep) are intentionally not exposed.
+
+**Visual feedback** (viewport and game screenshots) is currently available in the Summer Engine app via the built-in Summer Agent. MCP support for screenshots is on the MVP2 roadmap, gated on host clients reliably consuming image content.
 
 ## How It Works
 
-1. Summer Engine runs a local API server on `localhost:6550`
-2. The MCP server connects to this API via a local auth token (`~/.summer/api-token`)
-3. AI tools call MCP tools, which translate to API requests to the engine
-4. The engine executes operations and returns results
+1. Summer Engine runs a local API server on `localhost:6550`.
+2. The MCP server (`npx summer-engine mcp`) connects to that local API via a per-machine auth token (`~/.summer/api-token`) and exposes engine ops as MCP tools.
+3. Agents call the MCP tools and edit `.gd`/`.cs`/`.json`/`.md` files directly with their own file tools. Scenes (`.tscn`) flow through MCP.
+
+The engine must be running for MCP tools that touch scenes/assets/diagnostics. If it isn't, tools return a clear error pointing at `summer run`.
+
+## Per-Agent Docs
 
-The engine must be running for MCP tools to work. If it's not running, tools return a helpful error message.
+- [Agent Kit overview](docs/AGENT_KIT.md)
+- [Claude Code](docs/CLAUDE_CODE.md)
+- [Codex](docs/CODEX.md)
+- [Cursor](docs/CURSOR.md)
+- [Skills overview](docs/SKILLS.md)
+- [Templates overview](docs/TEMPLATES.md)
 
 ## Templates
 

package/dist/bin/summer.js

@@ -12,6 +12,8 @@ import { createCommand } from "../commands/create.js";
 import { listCommand } from "../commands/list.js";
 import { skillsCommand } from "../commands/skills.js";
 import { orchestratorCommand } from "../commands/orchestrator.js";
+import { setupCommand } from "../commands/setup.js";
+import { doctorCommand } from "../commands/doctor.js";
 const require = createRequire(import.meta.url);
 const { version } = require("../../package.json");
 const program = new Command();
@@ -29,6 +31,8 @@ program.addCommand(createCommand);
 program.addCommand(listCommand);
 program.addCommand(skillsCommand);
 program.addCommand(mcpCommand);
+program.addCommand(setupCommand);
+program.addCommand(doctorCommand);
 program.addCommand(orchestratorCommand);
 program.parseAsync().catch((err) => {
     console.error(err instanceof Error ? err.message : String(err));

package/dist/commands/doctor.d.ts

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+export type DoctorStatus = "ok" | "warning" | "fail";
+export interface DoctorCheck {
+    id: string;
+    label: string;
+    status: DoctorStatus;
+    message: string;
+    details?: Record<string, unknown>;
+}
+export interface DoctorResult {
+    ok: boolean;
+    checks: DoctorCheck[];
+    summary: {
+        ok: number;
+        warnings: number;
+        failures: number;
+    };
+}
+interface DoctorOptions {
+    json?: boolean;
+    quiet?: boolean;
+}
+export declare const doctorCommand: Command;
+export declare function runDoctor(options?: DoctorOptions): Promise<DoctorResult>;
+export declare function printDoctorResult(result: DoctorResult): void;
+export {};

package/dist/commands/doctor.js

@@ -0,0 +1,248 @@
+import { spawn } from "child_process";
+import { existsSync } from "fs";
+import { createRequire } from "node:module";
+import { platform } from "os";
+import { Command } from "commander";
+import { getAuthToken, getUserInfo } from "../lib/auth.js";
+import { checkEngineHealth, getApiPort, getApiToken } from "../lib/engine.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+const MAC_ENGINE_PATHS = [
+    "/Applications/Summer.app/Contents/MacOS/Summer",
+    `${process.env.HOME}/Applications/Summer.app/Contents/MacOS/Summer`,
+];
+const WIN_ENGINE_PATHS = [
+    `${process.env.LOCALAPPDATA}\\SummerEngine\\current\\Summer.exe`,
+    `${process.env.LOCALAPPDATA}\\Programs\\Summer Engine\\Summer.exe`,
+    `${process.env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
+];
+export const doctorCommand = new Command("doctor")
+    .description("Run setup and connection diagnostics")
+    .option("--json", "Print diagnostics as JSON")
+    .option("--human", "Print diagnostics in a human-readable format")
+    .action(async (opts) => {
+    const result = await runDoctor({ json: opts.json || !opts.human });
+    if (!result.ok) {
+        process.exit(1);
+    }
+});
+export async function runDoctor(options = {}) {
+    const checks = [];
+    checks.push(checkNodeVersion());
+    checks.push({
+        id: "cli-version",
+        label: "Summer CLI",
+        status: "ok",
+        message: `summer-engine CLI v${version}`,
+    });
+    checks.push(await checkLogin());
+    checks.push(checkEngineInstall());
+    checks.push(await checkLocalApi());
+    checks.push(await checkMcpBoot());
+    const result = summarizeChecks(checks);
+    if (!options.quiet) {
+        if (options.json) {
+            console.log(JSON.stringify(result, null, 2));
+        }
+        else {
+            printDoctorResult(result);
+        }
+    }
+    return result;
+}
+function checkNodeVersion() {
+    const major = Number(process.versions.node.split(".")[0]);
+    if (Number.isFinite(major) && major >= 18) {
+        return {
+            id: "node-version",
+            label: "Node.js",
+            status: "ok",
+            message: `Node ${process.version}`,
+        };
+    }
+    return {
+        id: "node-version",
+        label: "Node.js",
+        status: "fail",
+        message: `Node ${process.version} found; Summer CLI requires Node 18 or newer.`,
+    };
+}
+async function checkLogin() {
+    const token = await getAuthToken();
+    const user = await getUserInfo();
+    if (!token) {
+        return {
+            id: "login",
+            label: "Login",
+            status: "warning",
+            message: "Not logged in. Run: summer login",
+        };
+    }
+    return {
+        id: "login",
+        label: "Login",
+        status: "ok",
+        message: user ? `Logged in as ${user.email}` : "Auth token found.",
+    };
+}
+function checkEngineInstall() {
+    const binary = findEngineBinary();
+    if (binary) {
+        return {
+            id: "engine-install",
+            label: "Engine Install",
+            status: "ok",
+            message: `Summer Engine binary found at ${binary}`,
+            details: { path: binary },
+        };
+    }
+    return {
+        id: "engine-install",
+        label: "Engine Install",
+        status: "warning",
+        message: "Summer Engine binary was not found in the default install locations.",
+    };
+}
+async function checkLocalApi() {
+    const token = await getApiToken();
+    const port = await getApiPort();
+    if (!token) {
+        return {
+            id: "local-api",
+            label: "Local API",
+            status: "warning",
+            message: "Engine API token not found; Summer Engine is probably not running.",
+            details: { port },
+        };
+    }
+    const health = await checkEngineHealth(port);
+    if (!health) {
+        return {
+            id: "local-api",
+            label: "Local API",
+            status: "warning",
+            message: `API token found, but Summer Engine is not responding on port ${port}.`,
+            details: { port },
+        };
+    }
+    return {
+        id: "local-api",
+        label: "Local API",
+        status: "ok",
+        message: `Summer Engine API is responding on port ${port}.`,
+        details: {
+            port,
+            version: health.version,
+            projectName: health.project_name,
+            projectPath: health.project_path,
+        },
+    };
+}
+async function checkMcpBoot() {
+    const cliPath = process.argv[1];
+    if (!cliPath) {
+        return {
+            id: "mcp-boot",
+            label: "MCP Server",
+            status: "fail",
+            message: "Could not resolve the current Summer CLI entrypoint.",
+        };
+    }
+    return new Promise((resolve) => {
+        const command = cliPath.endsWith(".js") ? process.execPath : cliPath;
+        const args = cliPath.endsWith(".js") ? [cliPath, "mcp"] : ["mcp"];
+        const child = spawn(command, args, {
+            env: process.env,
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        let stderr = "";
+        let stdout = "";
+        let settled = false;
+        const finish = (check) => {
+            if (settled)
+                return;
+            settled = true;
+            child.kill();
+            resolve(check);
+        };
+        const timer = setTimeout(() => {
+            finish({
+                id: "mcp-boot",
+                label: "MCP Server",
+                status: "fail",
+                message: "MCP server did not finish startup within 3 seconds.",
+                details: trimOutput({ stdout, stderr }),
+            });
+        }, 3000);
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString("utf-8");
+            if (stderr.includes("MCP server running")) {
+                clearTimeout(timer);
+                finish({
+                    id: "mcp-boot",
+                    label: "MCP Server",
+                    status: "ok",
+                    message: "MCP stdio server starts successfully.",
+                });
+            }
+        });
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString("utf-8");
+        });
+        child.on("error", (error) => {
+            clearTimeout(timer);
+            finish({
+                id: "mcp-boot",
+                label: "MCP Server",
+                status: "fail",
+                message: `Could not start MCP server: ${error.message}`,
+            });
+        });
+        child.on("exit", (code) => {
+            clearTimeout(timer);
+            if (!settled) {
+                finish({
+                    id: "mcp-boot",
+                    label: "MCP Server",
+                    status: "fail",
+                    message: `MCP server exited before reporting readiness${code === null ? "" : ` (code ${code})`}.`,
+                    details: trimOutput({ stdout, stderr }),
+                });
+            }
+        });
+    });
+}
+function summarizeChecks(checks) {
+    const summary = {
+        ok: checks.filter((check) => check.status === "ok").length,
+        warnings: checks.filter((check) => check.status === "warning").length,
+        failures: checks.filter((check) => check.status === "fail").length,
+    };
+    return {
+        ok: summary.failures === 0,
+        checks,
+        summary,
+    };
+}
+export function printDoctorResult(result) {
+    console.log("Summer Doctor\n");
+    for (const check of result.checks) {
+        const mark = check.status === "ok" ? "OK" : check.status === "warning" ? "WARN" : "FAIL";
+        console.log(`  ${mark.padEnd(4)} ${check.label}: ${check.message}`);
+    }
+    console.log(`\n${result.summary.ok} ok, ${result.summary.warnings} warnings, ${result.summary.failures} failures`);
+}
+function findEngineBinary() {
+    const paths = platform() === "darwin" ? MAC_ENGINE_PATHS : WIN_ENGINE_PATHS;
+    for (const path of paths) {
+        if (path && existsSync(path))
+            return path;
+    }
+    return null;
+}
+function trimOutput(output) {
+    return {
+        stdout: output.stdout.trim().slice(0, 500),
+        stderr: output.stderr.trim().slice(0, 500),
+    };
+}

package/dist/commands/doctor.test.d.ts

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

package/dist/commands/doctor.test.js

@@ -0,0 +1,29 @@
+import { describe, expect, it } from "vitest";
+function summarize(checks) {
+    return {
+        ok: checks.filter((c) => c.status === "ok").length,
+        warnings: checks.filter((c) => c.status === "warning").length,
+        failures: checks.filter((c) => c.status === "fail").length,
+    };
+}
+describe("doctor summarization", () => {
+    it("counts mixed statuses", () => {
+        const summary = summarize([
+            { id: "a", label: "A", status: "ok", message: "" },
+            { id: "b", label: "B", status: "warning", message: "" },
+            { id: "c", label: "C", status: "fail", message: "" },
+            { id: "d", label: "D", status: "ok", message: "" },
+        ]);
+        expect(summary).toEqual({ ok: 2, warnings: 1, failures: 1 });
+    });
+    it("counts an all-ok run", () => {
+        const summary = summarize([
+            { id: "a", label: "A", status: "ok", message: "" },
+            { id: "b", label: "B", status: "ok", message: "" },
+        ]);
+        expect(summary).toEqual({ ok: 2, warnings: 0, failures: 0 });
+    });
+    it("counts an empty check list", () => {
+        expect(summarize([])).toEqual({ ok: 0, warnings: 0, failures: 0 });
+    });
+});

package/dist/commands/mcp.js

@@ -1,7 +1,56 @@
 import { Command } from "commander";
+import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../lib/agent-config.js";
 import { startMcpServer } from "../mcp/server.js";
 export const mcpCommand = new Command("mcp")
     .description("Start the MCP server for AI tool integration (Cursor, Claude Code, etc.)")
     .action(async () => {
     await startMcpServer();
 });
+mcpCommand
+    .command("setup <agent>")
+    .description("Configure an AI agent to use the Summer Engine MCP server")
+    .option("--scope <scope>", "Configuration scope: user or project", "user")
+    .option("--print", "Print the MCP config snippet instead of writing files")
+    .option("--dry-run", "Show planned changes without writing files")
+    .option("--local-dev", "Use the local built CLI instead of npx summer-engine")
+    .option("--json", "Print the setup result as JSON")
+    .action(async (agentValue, opts) => {
+    const agent = parseAgent(agentValue);
+    if (!agent) {
+        throw new Error(`Unsupported agent. Use one of: ${supportedAgents.join(", ")}`);
+    }
+    const scope = parseScope(opts.scope);
+    if (!scope) {
+        throw new Error("Invalid --scope. Use user or project.");
+    }
+    const result = await configureAgentMcp({
+        agent,
+        scope,
+        print: opts.print,
+        dryRun: opts.dryRun,
+        localDev: opts.localDev,
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(result, null, 2));
+        return;
+    }
+    if (result.print) {
+        console.log(result.snippet.trimEnd());
+    }
+    else if (result.dryRun) {
+        console.log(`Would update ${result.path} for ${result.agent} (${result.scope}).`);
+        console.log(result.snippet.trimEnd());
+    }
+    else if (result.wrote) {
+        console.log(`Configured Summer Engine MCP for ${result.agent} (${result.scope}) at ${result.path}.`);
+    }
+    else {
+        console.log(`Summer Engine MCP already configured for ${result.agent} (${result.scope}) at ${result.path}.`);
+    }
+    for (const warning of result.warnings) {
+        console.warn(`Warning: ${warning}`);
+    }
+    if (!result.print && !result.dryRun) {
+        console.log(result.nextSteps[result.nextSteps.length - 1]);
+    }
+});

package/dist/commands/setup.d.ts

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

package/dist/commands/setup.js

@@ -0,0 +1,128 @@
+import { spawnSync } from "child_process";
+import { Command } from "commander";
+import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../lib/agent-config.js";
+import { printDoctorResult, runDoctor } from "./doctor.js";
+export const setupCommand = new Command("setup")
+    .description("Configure Summer Engine for an AI agent and run diagnostics")
+    .argument("[agent]", `Agent to configure: ${supportedAgents.join(", ")}`)
+    .option("--agent <agent>", `Agent to configure: ${supportedAgents.join(", ")}`)
+    .option("--scope <scope>", "Configuration scope: user or project", "user")
+    .option("--dry-run", "Show planned changes without writing files")
+    .option("--print", "Print the MCP config snippet instead of writing files")
+    .option("--yes", "Apply practical setup steps without prompting")
+    .option("--json", "Print setup result as JSON")
+    .action(async (agentArg, opts) => {
+    const agent = resolveAgent(agentArg, opts.agent);
+    const scope = resolveScope(opts.scope);
+    const config = await configureAgentMcp({
+        agent,
+        scope,
+        dryRun: opts.dryRun,
+        print: opts.print,
+    });
+    const skills = setupRecommendedSkills(agent, {
+        dryRun: Boolean(opts.dryRun || opts.print),
+        yes: Boolean(opts.yes),
+    });
+    const doctor = await runDoctor({ quiet: true });
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: doctor.ok && skills.status !== "failed",
+            config,
+            skills,
+            doctor,
+        }, null, 2));
+    }
+    else {
+        printSetupResult(config, skills, doctor);
+    }
+    if (!doctor.ok || skills.status === "failed") {
+        process.exit(1);
+    }
+});
+function resolveAgent(agentArg, agentOpt) {
+    if (agentArg && agentOpt && parseAgent(agentArg) !== parseAgent(agentOpt)) {
+        throw new Error("Specify the agent either positionally or with --agent, not both.");
+    }
+    const parsed = parseAgent(agentOpt ?? agentArg);
+    if (!parsed) {
+        throw new Error(`Specify an agent: ${supportedAgents.join(", ")}`);
+    }
+    return parsed;
+}
+function resolveScope(scopeOpt) {
+    const parsed = parseScope(scopeOpt);
+    if (!parsed) {
+        throw new Error("Invalid --scope. Use user or project.");
+    }
+    return parsed;
+}
+function setupRecommendedSkills(agent, options) {
+    const invocation = skillInstallInvocation(agent);
+    if (!invocation) {
+        return {
+            status: "skipped",
+            message: "No automatic skill installer is available for this agent yet. Run `summer skills install --all` and point the agent at the installed SKILL.md files.",
+        };
+    }
+    if (options.dryRun || !options.yes) {
+        return {
+            status: "planned",
+            command: invocation.display,
+            message: `Recommended skills can be installed with: ${invocation.display.join(" ")}`,
+        };
+    }
+    const result = spawnSync(invocation.command, invocation.args, {
+        env: process.env,
+        encoding: "utf-8",
+    });
+    if (result.status === 0) {
+        return {
+            status: "installed",
+            command: invocation.display,
+            message: "Recommended Summer skills installed.",
+            stdout: result.stdout.trim(),
+            stderr: result.stderr.trim(),
+        };
+    }
+    return {
+        status: "failed",
+        command: invocation.display,
+        message: `Recommended skill install failed with exit code ${result.status ?? "unknown"}.`,
+        stdout: result.stdout.trim(),
+        stderr: result.stderr.trim(),
+    };
+}
+function skillInstallInvocation(agent) {
+    const cliPath = process.argv[1];
+    if (!cliPath)
+        return null;
+    const command = cliPath.endsWith(".js") ? process.execPath : cliPath;
+    const prefix = cliPath.endsWith(".js") ? [cliPath] : [];
+    const baseArgs = ["skills", "install", "--recommended", "--agent", agent];
+    return {
+        command,
+        args: [...prefix, ...baseArgs],
+        display: [cliPath, ...baseArgs],
+    };
+}
+function printSetupResult(config, skills, doctor) {
+    if (config.print) {
+        console.log(config.snippet.trimEnd());
+    }
+    else if (config.dryRun) {
+        console.log(`Would update ${config.path} for ${config.agent} (${config.scope}).`);
+    }
+    else if (config.wrote) {
+        console.log(`Configured Summer Engine MCP for ${config.agent} (${config.scope}) at ${config.path}.`);
+    }
+    else {
+        console.log(`Summer Engine MCP already configured for ${config.agent} (${config.scope}) at ${config.path}.`);
+    }
+    for (const warning of config.warnings) {
+        console.warn(`Warning: ${warning}`);
+    }
+    console.log(`Skills: ${skills.message}`);
+    console.log("");
+    printDoctorResult(doctor);
+}