summer-engine 0.0.1 → 1.0.1

package/README.md

@@ -1,21 +1,50 @@
 # 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.
 
-> Coming soon. Visit [summerengine.com](https://summerengine.com) to get started.
+## Install
+
+```bash
+npm install -g summer-engine
+```
+
+Or use without installing:
+
+```bash
+npx summer-engine <command>
+```
+
+## Commands
+
+| Command | Description |
+|---------|-------------|
+| `summer install` | Download and install Summer Engine |
+| `summer login` | Sign in via browser (Google/GitHub) |
+| `summer logout` | Clear auth tokens |
+| `summer status` | Check engine status, port, auth state |
+| `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) |
 
 ## Quick Start
 
 ```bash
-npx summer-engine install    # Install Summer Engine
-npx summer-engine login      # Sign in with your account
-npx summer-engine create fps # Create a new project from template
-npx summer-engine run        # Launch the engine
+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
 ```
 
 ## MCP Integration
 
-Use Summer Engine with Cursor, Claude Code, or any MCP-compatible AI tool:
+Use Summer Engine with Cursor, Claude Code, or any MCP-compatible AI tool.
+
+**Cursor** (`.cursor/mcp.json`):
 
 ```json
 {
@@ -28,7 +57,42 @@ Use Summer Engine with Cursor, Claude Code, or any MCP-compatible AI tool:
 }
 ```
 
-## Learn More
+**Claude Code** (`~/.claude/claude_code_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "summer-engine": {
+      "command": "npx",
+      "args": ["summer-engine", "mcp"]
+    }
+  }
+}
+```
+
+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.
+
+**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.
+
+## 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
+
+The engine must be running for MCP tools to work. If it's not running, tools return a helpful error message.
+
+## Templates
+
+Built-in templates:
+
+- `empty` — Empty 3D project with a root node
+- `3d-basic` — 3D scene with camera, light, and floor
+
+More templates coming soon.
+
+## Links
 
 - [Website](https://summerengine.com)
 - [Documentation](https://summerengine.com/docs)

package/dist/bin/postinstall.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/postinstall.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { printWelcome } from "../lib/banner.js";
+printWelcome("1.0.0");

package/dist/bin/summer.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/bin/summer.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { Command } from "commander";
+import { mcpCommand } from "../commands/mcp.js";
+import { loginCommand } from "../commands/login.js";
+import { logoutCommand } from "../commands/logout.js";
+import { statusCommand } from "../commands/status.js";
+import { runCommand } from "../commands/run.js";
+import { openCommand } from "../commands/open.js";
+import { installCommand } from "../commands/install.js";
+import { createCommand } from "../commands/create.js";
+import { listCommand } from "../commands/list.js";
+import { skillsCommand } from "../commands/skills.js";
+const require = createRequire(import.meta.url);
+const { version } = require("../../package.json");
+const program = new Command();
+program
+    .name("summer")
+    .description("CLI and MCP tools for Summer Engine — the AI-native game engine")
+    .version(version);
+program.addCommand(installCommand);
+program.addCommand(loginCommand);
+program.addCommand(logoutCommand);
+program.addCommand(statusCommand);
+program.addCommand(runCommand);
+program.addCommand(openCommand);
+program.addCommand(createCommand);
+program.addCommand(listCommand);
+program.addCommand(skillsCommand);
+program.addCommand(mcpCommand);
+program.parseAsync().catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});

package/dist/commands/create.d.ts

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

package/dist/commands/create.js

@@ -0,0 +1,99 @@
+import { Command } from "commander";
+import { existsSync, mkdirSync, writeFileSync } from "fs";
+import { join, resolve } from "path";
+const BUILTIN_TEMPLATES = [
+    {
+        name: "empty",
+        description: "Empty 3D project with just a root node",
+        builtin: true,
+        generate: (dir, name) => {
+            writeFileSync(join(dir, "project.godot"), projectGodot(name, "res://main.tscn"));
+            writeFileSync(join(dir, "main.tscn"), emptyScene());
+        },
+    },
+    {
+        name: "3d-basic",
+        description: "3D scene with camera, light, and floor",
+        builtin: true,
+        generate: (dir, name) => {
+            writeFileSync(join(dir, "project.godot"), projectGodot(name, "res://main.tscn"));
+            writeFileSync(join(dir, "main.tscn"), basicScene3D());
+        },
+    },
+];
+export const createCommand = new Command("create")
+    .description("Create a new Summer Engine project from a template")
+    .argument("<template>", `Template name (${BUILTIN_TEMPLATES.map((t) => t.name).join(", ")})`)
+    .argument("[name]", "Project directory name (defaults to template name)")
+    .action(async (templateName, projectName) => {
+    const template = BUILTIN_TEMPLATES.find((t) => t.name === templateName);
+    if (!template) {
+        console.error(`Unknown template: ${templateName}`);
+        console.log("\nAvailable templates:");
+        for (const t of BUILTIN_TEMPLATES) {
+            console.log(`  ${t.name.padEnd(12)} ${t.description}`);
+        }
+        console.log("\nMore templates coming soon at github.com/summerengine/templates");
+        process.exit(1);
+    }
+    const dirName = projectName || templateName;
+    const fullPath = resolve(dirName);
+    if (existsSync(fullPath)) {
+        console.error(`Directory already exists: ${fullPath}`);
+        process.exit(1);
+    }
+    console.log(`Creating project from '${templateName}' template...`);
+    mkdirSync(fullPath, { recursive: true });
+    template.generate(fullPath, dirName);
+    console.log(`\nProject created at ${fullPath}`);
+    console.log("\nNext steps:");
+    console.log(`  summer run ${dirName}`);
+});
+function projectGodot(name, mainScene) {
+    return `; Summer Engine Project
+; Generated by summer-engine CLI
+
+[application]
+
+config/name="${name}"
+run/main_scene="${mainScene}"
+config/features=PackedStringArray("4.5")
+
+[rendering]
+
+renderer/rendering_method="forward_plus"
+`;
+}
+function emptyScene() {
+    return `[gd_scene format=3]
+
+[node name="World" type="Node3D"]
+`;
+}
+function basicScene3D() {
+    return `[gd_scene load_steps=4 format=3]
+
+[sub_resource type="BoxMesh" id="BoxMesh_floor"]
+size = Vector3(20, 0.2, 20)
+
+[sub_resource type="StandardMaterial3D" id="StandardMaterial3D_floor"]
+albedo_color = Color(0.4, 0.45, 0.4, 1)
+
+[sub_resource type="ProceduralSkyMaterial" id="ProceduralSkyMaterial_sky"]
+
+[node name="World" type="Node3D"]
+
+[node name="Camera3D" type="Camera3D" parent="."]
+transform = Transform3D(1, 0, 0, 0, 0.939693, 0.34202, 0, -0.34202, 0.939693, 0, 5, 10)
+
+[node name="DirectionalLight3D" type="DirectionalLight3D" parent="."]
+transform = Transform3D(1, 0, 0, 0, 0.866025, 0.5, 0, -0.5, 0.866025, 0, 8, 0)
+shadow_enabled = true
+
+[node name="Floor" type="MeshInstance3D" parent="."]
+mesh = SubResource("BoxMesh_floor")
+surface_material_override/0 = SubResource("StandardMaterial3D_floor")
+
+[node name="WorldEnvironment" type="WorldEnvironment" parent="."]
+`;
+}

package/dist/commands/install.d.ts

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

package/dist/commands/install.js

@@ -0,0 +1,135 @@
+import { Command } from "commander";
+import { execSync } from "child_process";
+import { createWriteStream, existsSync, mkdirSync } from "fs";
+import { pipeline } from "stream/promises";
+import { Readable } from "stream";
+import { tmpdir, platform } from "os";
+import { join } from "path";
+const RELEASES_URL = "https://www.summerengine.com/api/desktop/releases";
+export const installCommand = new Command("install")
+    .description("Download and install Summer Engine")
+    .option("--path <dir>", "Custom install directory")
+    .action(async (opts) => {
+    const os = platform();
+    if (os !== "darwin" && os !== "win32") {
+        console.error("Linux support is coming soon.\n" +
+            "For now, download from: https://summerengine.com/download");
+        process.exit(1);
+    }
+    console.log("Fetching latest release info...");
+    let releases;
+    try {
+        const res = await fetch(RELEASES_URL, { signal: AbortSignal.timeout(10000) });
+        if (!res.ok)
+            throw new Error(`HTTP ${res.status}`);
+        releases = (await res.json());
+    }
+    catch (err) {
+        console.error("Could not fetch release info. Download manually from:\n" +
+            "  https://summerengine.com/download");
+        process.exit(1);
+    }
+    if (os === "darwin") {
+        await installMac(releases, opts.path);
+    }
+    else {
+        await installWindows(releases, opts.path);
+    }
+});
+async function installMac(releases, customPath) {
+    const info = releases.latest.macos;
+    if (!info) {
+        console.error("No macOS release found.");
+        process.exit(1);
+    }
+    console.log(`Latest version: ${info.version}`);
+    const destApp = customPath || "/Applications/Summer.app";
+    if (existsSync(destApp)) {
+        console.log(`Summer Engine already installed at ${destApp}`);
+        console.log("Updating to latest version...");
+    }
+    const dmgPath = join(tmpdir(), `Summer-v${info.version}.dmg`);
+    console.log(`Downloading Summer Engine v${info.version} (~145MB)...`);
+    await downloadFile(info.dmg_url, dmgPath);
+    console.log("Mounting DMG...");
+    const mountOutput = execSync(`hdiutil attach "${dmgPath}" -nobrowse -noverify -noautoopen`, {
+        encoding: "utf-8",
+    });
+    const mountPoint = mountOutput
+        .split("\n")
+        .filter((line) => line.includes("/Volumes/"))
+        .map((line) => line.trim().split("\t").pop()?.trim())
+        .find(Boolean);
+    if (!mountPoint) {
+        console.error("Failed to find mount point. Install manually from the DMG.");
+        process.exit(1);
+    }
+    try {
+        console.log("Installing to " + destApp + "...");
+        execSync(`rm -rf "${destApp}"`, { stdio: "ignore" });
+        execSync(`cp -R "${mountPoint}/Summer.app" "${destApp}"`);
+        console.log("Done!");
+    }
+    finally {
+        execSync(`hdiutil detach "${mountPoint}" -quiet`, { stdio: "ignore" });
+        try {
+            execSync(`rm "${dmgPath}"`, { stdio: "ignore" });
+        }
+        catch { }
+    }
+    console.log(`\nSummer Engine v${info.version} installed to ${destApp}`);
+    console.log("\nNext steps:");
+    console.log("  summer login    # Sign in to your account");
+    console.log("  summer run      # Launch the engine");
+}
+async function installWindows(releases, customPath) {
+    const info = releases.latest.windows;
+    if (!info) {
+        console.error("No Windows release found.");
+        process.exit(1);
+    }
+    console.log(`Latest version: ${info.version}`);
+    const exePath = join(tmpdir(), `Summer-v${info.version}.exe`);
+    console.log(`Downloading Summer Engine v${info.version}...`);
+    await downloadFile(info.url, exePath);
+    console.log("Running installer...");
+    try {
+        execSync(`"${exePath}" /S${customPath ? ` /D=${customPath}` : ""}`, {
+            stdio: "inherit",
+        });
+    }
+    catch {
+        console.error("Installer failed. Try running it manually:\n  " + exePath);
+        process.exit(1);
+    }
+    try {
+        execSync(`del "${exePath}"`, { stdio: "ignore" });
+    }
+    catch { }
+    console.log(`\nSummer Engine v${info.version} installed!`);
+    console.log("\nNext steps:");
+    console.log("  summer login    # Sign in to your account");
+    console.log("  summer run      # Launch the engine");
+}
+async function downloadFile(url, dest) {
+    const res = await fetch(url);
+    if (!res.ok || !res.body) {
+        throw new Error(`Download failed: HTTP ${res.status}`);
+    }
+    const dir = join(dest, "..");
+    if (!existsSync(dir))
+        mkdirSync(dir, { recursive: true });
+    const fileStream = createWriteStream(dest);
+    const readable = Readable.fromWeb(res.body);
+    let downloaded = 0;
+    const total = parseInt(res.headers.get("content-length") || "0", 10);
+    readable.on("data", (chunk) => {
+        downloaded += chunk.length;
+        if (total > 0) {
+            const pct = Math.round((downloaded / total) * 100);
+            process.stdout.write(`\r  ${pct}% (${(downloaded / 1024 / 1024).toFixed(1)}MB)`);
+        }
+    });
+    await pipeline(readable, fileStream);
+    process.stdout.write("\n");
+}

package/dist/commands/list.d.ts

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

package/dist/commands/list.js

@@ -0,0 +1,48 @@
+import { Command } from "commander";
+import { readdirSync, existsSync } from "fs";
+import { join } from "path";
+export const listCommand = new Command("list")
+    .description("List available templates or local projects")
+    .argument("<what>", "'templates' or 'projects'")
+    .action(async (what) => {
+    if (what === "templates") {
+        listTemplates();
+    }
+    else if (what === "projects") {
+        listProjects();
+    }
+    else {
+        console.error(`Unknown: '${what}'. Use 'templates' or 'projects'.`);
+        process.exit(1);
+    }
+});
+function listTemplates() {
+    console.log("Built-in Templates:\n");
+    console.log("  empty        Empty 3D project with just a root node");
+    console.log("  3d-basic     3D scene with camera, light, and floor");
+    console.log("\nCreate a project: summer create <template> [name]");
+    console.log("\nMore templates coming soon at github.com/summerengine/templates");
+}
+function listProjects() {
+    const cwd = process.cwd();
+    const entries = readdirSync(cwd, { withFileTypes: true });
+    const projects = [];
+    for (const entry of entries) {
+        if (entry.isDirectory()) {
+            const projectFile = join(cwd, entry.name, "project.godot");
+            if (existsSync(projectFile)) {
+                projects.push(entry.name);
+            }
+        }
+    }
+    if (projects.length === 0) {
+        console.log("No Summer Engine / Godot projects found in current directory.");
+        console.log("\nCreate one: summer create 3d-basic my-game");
+        return;
+    }
+    console.log(`Projects in ${cwd}:\n`);
+    for (const p of projects) {
+        console.log(`  ${p}/`);
+    }
+    console.log(`\nOpen a project: summer run <name>`);
+}

package/dist/commands/login.d.ts

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

package/dist/commands/login.js

@@ -0,0 +1,75 @@
+import { Command } from "commander";
+import { randomUUID } from "crypto";
+import open from "open";
+import { getAuthToken, saveAuthToken, saveUserInfo } from "../lib/auth.js";
+const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+const POLL_INTERVAL_MS = 2000;
+const POLL_TIMEOUT_MS = 120000;
+export const loginCommand = new Command("login")
+    .description("Sign in to Summer Engine via your browser")
+    .option("--force", "Force re-authentication even if already logged in")
+    .action(async (opts) => {
+    const existing = await getAuthToken();
+    if (existing && !opts.force) {
+        console.log("Already logged in. Use --force to re-authenticate.");
+        return;
+    }
+    await doLogin();
+});
+async function doLogin() {
+    const sessionId = randomUUID();
+    const loginUrl = `${GATEWAY_URL}/login?cli_session=${sessionId}`;
+    console.log("Sign in at: " + loginUrl);
+    console.log("");
+    try {
+        await open(loginUrl);
+    }
+    catch {
+        console.log("Could not open browser. Copy the URL above and open it manually.");
+        console.log("");
+    }
+    console.log("Waiting for authentication...");
+    const pollUrl = `${GATEWAY_URL}/api/auth/cli-login?session=${sessionId}`;
+    const startTime = Date.now();
+    let lastError = null;
+    while (Date.now() - startTime < POLL_TIMEOUT_MS) {
+        await sleep(POLL_INTERVAL_MS);
+        try {
+            const res = await fetch(pollUrl, {
+                signal: AbortSignal.timeout(5000),
+            });
+            if (!res.ok) {
+                if (res.status === 503) {
+                    lastError = "Server not ready (Redis/auth not configured). Try again later.";
+                }
+                else if (res.status >= 500) {
+                    lastError = `Server error (${res.status}). Try again later.`;
+                }
+                continue;
+            }
+            const data = (await res.json());
+            if (data.status === "pending")
+                continue;
+            if (data.status === "complete" && data.token) {
+                await saveAuthToken(data.token);
+                if (data.user) {
+                    await saveUserInfo(data.user);
+                }
+                console.log(`\nLogged in as ${data.user?.email || "unknown"}`);
+                return;
+            }
+        }
+        catch (err) {
+            lastError = err instanceof Error ? err.message : "Network error";
+        }
+    }
+    console.error("\nLogin timed out. Please try again.");
+    if (lastError) {
+        console.error(`Last error: ${lastError}`);
+    }
+    console.error("\nDid you click \"Yes, Sign In\" in the browser after opening the URL?");
+    process.exit(1);
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/commands/logout.d.ts

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

package/dist/commands/logout.js

@@ -0,0 +1,26 @@
+import { Command } from "commander";
+import { unlink } from "fs/promises";
+import { join } from "path";
+import { getSummerDir } from "../lib/auth.js";
+export const logoutCommand = new Command("logout")
+    .description("Sign out and clear stored auth tokens")
+    .action(async () => {
+    const dir = getSummerDir();
+    const files = ["auth-token", "user.json"];
+    let cleared = false;
+    for (const file of files) {
+        try {
+            await unlink(join(dir, file));
+            cleared = true;
+        }
+        catch {
+            // File doesn't exist, that's fine
+        }
+    }
+    if (cleared) {
+        console.log("Logged out. Auth tokens cleared.");
+    }
+    else {
+        console.log("Already logged out (no tokens found).");
+    }
+});

package/dist/commands/mcp.d.ts

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

package/dist/commands/mcp.js

@@ -0,0 +1,7 @@
+import { Command } from "commander";
+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();
+});

package/dist/commands/open.d.ts

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

package/dist/commands/open.js

@@ -0,0 +1,32 @@
+import { Command } from "commander";
+import { existsSync } from "fs";
+import { resolve } from "path";
+import { getApiPort, checkEngineHealth } from "../lib/engine.js";
+export const openCommand = new Command("open")
+    .description("Open a project in Summer Engine")
+    .argument("<path>", "Path to project directory (must contain project.godot)")
+    .action(async (projectPath) => {
+    const fullPath = resolve(projectPath);
+    if (!existsSync(fullPath)) {
+        console.error(`Directory not found: ${fullPath}`);
+        process.exit(1);
+    }
+    if (!existsSync(`${fullPath}/project.godot`)) {
+        console.error(`No project.godot found in ${fullPath}\n` +
+            "This doesn't look like a Godot/Summer Engine project.\n" +
+            "Create one with: summer create 3d-basic my-game");
+        process.exit(1);
+    }
+    const port = await getApiPort();
+    const health = await checkEngineHealth(port);
+    if (!health) {
+        console.log("Engine not running. Launching with this project...");
+        // Import dynamically to avoid circular deps
+        const { runCommand } = await import("./run.js");
+        await runCommand.parseAsync(["node", "summer", fullPath], { from: "user" });
+        return;
+    }
+    console.log(`Opening project: ${fullPath}`);
+    console.log("Note: To switch projects, close the current one in Summer Engine first,\n" +
+        "or run: summer run " + fullPath);
+});

package/dist/commands/run.d.ts

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