summer-engine 2.3.0 → 2.6.0

package/dist/commands/memory.js

@@ -0,0 +1,196 @@
+import { existsSync, readFileSync, statSync } from "node:fs";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { Command } from "commander";
+import { checkEngineHealth, getApiPort } from "../lib/engine.js";
+import { getProjectMemorySummary, } from "../lib/project-memory.js";
+import { c, pad, tildeify } from "../lib/format.js";
+export const memoryCommand = new Command("memory")
+    .description("Inspect project memory in .summer")
+    .option("--project <path>", "Project directory to inspect")
+    .option("--json", "Print memory summary as JSON")
+    .action(async (opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        if (opts.json) {
+            console.log(JSON.stringify({ ok: false, ...resolvedProject }, null, 2));
+        }
+        else {
+            console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+            console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        }
+        process.exit(1);
+    }
+    const summary = getProjectMemorySummary(resolvedProject.projectPath);
+    if (opts.json) {
+        console.log(JSON.stringify({
+            ok: true,
+            projectPath: resolvedProject.projectPath,
+            source: resolvedProject.source,
+            memory: summary,
+        }, null, 2));
+        return;
+    }
+    console.log(formatMemorySummary(resolvedProject.projectPath, summary));
+});
+memoryCommand
+    .command("show <file>")
+    .description("Print a .summer memory Markdown file")
+    .option("--project <path>", "Project directory to inspect")
+    .action(async (file, opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+        console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        process.exit(1);
+    }
+    const filePath = resolveMemoryFilePath(resolvedProject.projectPath, file);
+    console.log(readFileSync(filePath, "utf-8"));
+});
+memoryCommand
+    .command("path")
+    .description("Print the .summer directory path for the current project")
+    .option("--project <path>", "Project directory to inspect")
+    .action(async (opts) => {
+    const resolvedProject = await resolveMemoryProject(opts.project);
+    if (!resolvedProject.projectPath) {
+        console.error(resolvedProject.reason ?? "Could not find a Summer project.");
+        console.error("Run from a project directory, pass --project <path>, or start Summer Engine.");
+        process.exit(1);
+    }
+    console.log(join(resolvedProject.projectPath, ".summer"));
+});
+export async function resolveMemoryProject(projectOption) {
+    if (projectOption) {
+        const projectPath = resolve(projectOption);
+        if (!existsSync(projectPath)) {
+            return {
+                projectPath: null,
+                source: "option",
+                reason: `Project directory not found: ${projectPath}`,
+            };
+        }
+        if (!existsSync(join(projectPath, "project.godot"))) {
+            return {
+                projectPath: null,
+                source: "option",
+                reason: `No project.godot found in ${projectPath}.`,
+            };
+        }
+        return { projectPath, source: "option" };
+    }
+    const cwdProject = findProjectRoot(process.cwd());
+    if (cwdProject)
+        return { projectPath: cwdProject, source: "cwd" };
+    const port = await getApiPort();
+    const health = await checkEngineHealth(port);
+    if (health?.project_path && existsSync(join(health.project_path, "project.godot"))) {
+        return { projectPath: health.project_path, source: "engine" };
+    }
+    return {
+        projectPath: null,
+        source: "none",
+        reason: "No Summer project found from engine state or current directory.",
+    };
+}
+export function findProjectRoot(startDir) {
+    let current = resolve(startDir);
+    while (true) {
+        if (existsSync(join(current, "project.godot")))
+            return current;
+        const parent = dirname(current);
+        if (parent === current)
+            return null;
+        current = parent;
+    }
+}
+export function resolveMemoryFilePath(projectPath, requested) {
+    const summerDir = resolve(projectPath, ".summer");
+    const rawPath = requested.startsWith(".summer/")
+        ? resolve(projectPath, requested)
+        : resolve(summerDir, requested);
+    const withinSummer = isPathInside(summerDir, rawPath);
+    if (!withinSummer) {
+        throw new Error("Memory files must be inside the project's .summer directory.");
+    }
+    if (!existsSync(rawPath)) {
+        throw new Error(`Memory file not found: ${requested}`);
+    }
+    if (!statSync(rawPath).isFile()) {
+        throw new Error(`Memory path is not a file: ${requested}`);
+    }
+    return rawPath;
+}
+export function formatMemorySummary(projectPath, summary) {
+    const lines = [];
+    lines.push(c.bold("Project Memory"));
+    lines.push("");
+    lines.push(`  Project: ${tildeify(projectPath)}`);
+    lines.push(`  Folder:  ${tildeify(join(projectPath, ".summer"))}`);
+    lines.push("");
+    if (!summary.present) {
+        lines.push(`  ${summary.reason ?? "No .summer memory found yet."}`);
+        lines.push("");
+        lines.push("  Agents create this through Summer skills.");
+        lines.push("  Start with .summer/GameSoul.md for the project brief.");
+        lines.push("  Use .summer/memory/ for locked facts like voice IDs and world canon.");
+        return lines.join("\n");
+    }
+    const totalFiles = summary.files.length;
+    const structured = summary.structured;
+    lines.push(`  Status:  ${totalFiles} .summer Markdown file${totalFiles === 1 ? "" : "s"}, ` +
+        `${structured.fileCount} structured memory file${structured.fileCount === 1 ? "" : "s"}, ` +
+        `${structured.lockedCount} locked`);
+    lines.push("");
+    const canonicalRows = canonicalRowsFromSummary(summary);
+    if (canonicalRows.length > 0) {
+        lines.push(c.bold("Canonical"));
+        for (const [label, file] of canonicalRows) {
+            lines.push(formatMemoryFileLine(label, file));
+        }
+        lines.push("");
+    }
+    if (structured.files.length > 0) {
+        lines.push(c.bold("Structured"));
+        for (const file of structured.files) {
+            lines.push(formatMemoryFileLine(file.kind, file));
+        }
+        if (structured.truncated) {
+            lines.push("  ...more files omitted from summary");
+        }
+        lines.push("");
+    }
+    lines.push("Read a file:");
+    lines.push("  summer memory show .summer/memory/casting/voices.md");
+    lines.push("");
+    lines.push("Rule:");
+    lines.push("  Markdown is canonical. Changing priority: locked memory requires explicit user confirmation.");
+    return lines.join("\n");
+}
+export function formatStatusMemoryLine(summary) {
+    if (!summary.present)
+        return "Memory: No .summer folder yet";
+    const fileCount = summary.files.length;
+    const structuredCount = summary.structured.fileCount;
+    const lockedCount = summary.structured.lockedCount;
+    return `Memory: ${fileCount} .summer file${fileCount === 1 ? "" : "s"}, ${structuredCount} memory file${structuredCount === 1 ? "" : "s"}, ${lockedCount} locked`;
+}
+function canonicalRowsFromSummary(summary) {
+    const rows = [
+        ["brief", summary.canonical.gameSoul],
+        ["art", summary.canonical.artBible],
+        ["audio", summary.canonical.audioBible],
+        ["build", summary.canonical.buildPlan],
+        ["legacy-casting", summary.canonical.legacyVoiceCast],
+    ];
+    return rows.filter((row) => row[1] !== null);
+}
+function formatMemoryFileLine(label, file) {
+    const lock = file.locked ? "locked" : "";
+    const title = file.title ? ` - ${file.title}` : "";
+    return `  ${pad(label, 15)} ${pad(file.path, 42)} ${lock}${title}`;
+}
+function isPathInside(parent, child) {
+    const relativePath = relative(parent, child);
+    return (relativePath === "" ||
+        (!relativePath.startsWith("..") && !isAbsolute(relativePath)));
+}

package/dist/commands/open.js

@@ -28,5 +28,5 @@ export const openCommand = new Command("open")
     }
     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);
+        "then run: summer run " + fullPath);
 });

package/dist/commands/plan.d.ts

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

package/dist/commands/plan.js

@@ -0,0 +1,60 @@
+import { Command } from "commander";
+import { ASSET_POLICIES, GAME_TASK_MODES, GAME_TASK_TARGETS, VERIFICATION_LEVELS, buildGameTaskPlan, } from "../lib/game-task-plan.js";
+import { c } from "../lib/format.js";
+function parseChoice(value, choices, label) {
+    if (!value)
+        return undefined;
+    if (choices.includes(value))
+        return value;
+    throw new Error(`Invalid ${label}: ${value}. Use one of: ${choices.join(", ")}`);
+}
+function printList(title, items) {
+    if (items.length === 0)
+        return;
+    console.log(c.bold(title));
+    for (const item of items) {
+        console.log(`  - ${item}`);
+    }
+    console.log("");
+}
+export const planCommand = new Command("plan")
+    .description("Plan the right Summer CLI/MCP workflow for an AI game-building task")
+    .argument("<goal...>", "What the user wants to build, fix, polish, or create")
+    .option("--mode <mode>", `Task mode: ${GAME_TASK_MODES.join("|")}`)
+    .option("--target <target>", `Task target: ${GAME_TASK_TARGETS.join("|")}`)
+    .option("--asset-policy <policy>", `Asset policy: ${ASSET_POLICIES.join("|")}`)
+    .option("--verification <level>", `Verification level: ${VERIFICATION_LEVELS.join("|")}`)
+    .option("--json", "Print the plan as JSON")
+    .action((goalParts, opts) => {
+    const plan = buildGameTaskPlan({
+        goal: goalParts.join(" "),
+        mode: parseChoice(opts.mode, GAME_TASK_MODES, "mode"),
+        target: parseChoice(opts.target, GAME_TASK_TARGETS, "target"),
+        assetPolicy: parseChoice(opts.assetPolicy, ASSET_POLICIES, "asset policy"),
+        verification: parseChoice(opts.verification, VERIFICATION_LEVELS, "verification"),
+    });
+    if (opts.json) {
+        console.log(JSON.stringify(plan, null, 2));
+        return;
+    }
+    console.log("");
+    console.log(c.bold("Summer Game Task Plan"));
+    console.log(`Goal: ${plan.goal}`);
+    console.log(`Mode: ${plan.mode}`);
+    console.log(`Target: ${plan.target}`);
+    console.log(`Asset policy: ${plan.assetPolicy}`);
+    console.log(`Verification: ${plan.verification}`);
+    console.log("");
+    console.log(c.bold("Recommended Skills"));
+    for (const skill of plan.recommendedSkills) {
+        console.log(`  - ${skill.id}: ${skill.why}`);
+    }
+    console.log("");
+    printList("MCP Start", plan.mcpToolPlan.start);
+    printList("MCP Mutations", plan.mcpToolPlan.mutate);
+    printList("MCP Assets", plan.mcpToolPlan.assets);
+    printList("MCP Verify", plan.mcpToolPlan.verify);
+    printList("Host File Work", plan.hostFileWork);
+    printList("User Gates", plan.userGates);
+    printList("Next Agent Steps", plan.nextAgentSteps);
+});

package/dist/commands/run.js

@@ -1,7 +1,10 @@
 import { Command } from "commander";
 import { spawn } from "child_process";
 import { existsSync } from "fs";
+import { mkdir, readFile, rm, writeFile } from "fs/promises";
 import { platform } from "os";
+import { join, resolve } from "path";
+import { getSummerDir } from "../lib/auth.js";
 import { getApiPort, checkEngineHealth } from "../lib/engine.js";
 const MAC_PATHS = [
     "/Applications/Summer.app/Contents/MacOS/Summer",
@@ -12,6 +15,8 @@ const WIN_PATHS = [
     `${process.env.LOCALAPPDATA}\\Programs\\Summer Engine\\Summer.exe`,
     `${process.env.PROGRAMFILES}\\Summer Engine\\Summer.exe`,
 ];
+const LAUNCH_LOCK_STALE_MS = 60_000;
+const LAUNCH_LOCK_WAIT_MS = 15_000;
 function findEngineBinary() {
     const paths = platform() === "darwin" ? MAC_PATHS : WIN_PATHS;
     for (const p of paths) {
@@ -20,50 +25,142 @@ function findEngineBinary() {
     }
     return null;
 }
+function isProcessAlive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error.code;
+        return code === "EPERM";
+    }
+}
+async function removeStaleLaunchLock(lockDir) {
+    const ownerPath = join(lockDir, "owner.json");
+    try {
+        const raw = await readFile(ownerPath, "utf-8");
+        const owner = JSON.parse(raw);
+        const pid = typeof owner.pid === "number" ? owner.pid : 0;
+        const createdAt = typeof owner.createdAt === "number" ? owner.createdAt : 0;
+        const staleByTime = Date.now() - createdAt > LAUNCH_LOCK_STALE_MS;
+        const staleByPid = !isProcessAlive(pid);
+        if (!staleByTime && !staleByPid) {
+            return false;
+        }
+    }
+    catch {
+        // Broken owner metadata should not permanently block launches.
+    }
+    await rm(lockDir, { recursive: true, force: true });
+    return true;
+}
+async function withLaunchLock(fn) {
+    const summerDir = getSummerDir();
+    await mkdir(summerDir, { recursive: true, mode: 0o700 });
+    const lockDir = join(summerDir, "launch.lock");
+    const ownerPath = join(lockDir, "owner.json");
+    const startedAt = Date.now();
+    while (true) {
+        try {
+            await mkdir(lockDir, { mode: 0o700 });
+            try {
+                await writeFile(ownerPath, JSON.stringify({ pid: process.pid, createdAt: Date.now() }, null, 2), { encoding: "utf-8", mode: 0o600 });
+                return await fn();
+            }
+            finally {
+                await rm(lockDir, { recursive: true, force: true });
+            }
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST") {
+                throw error;
+            }
+            if (await removeStaleLaunchLock(lockDir)) {
+                continue;
+            }
+            if (Date.now() - startedAt > LAUNCH_LOCK_WAIT_MS) {
+                throw new Error("Another `summer run` launch is still in progress. Try again in a few seconds.");
+            }
+            await sleep(100);
+        }
+    }
+}
 export const runCommand = new Command("run")
     .description("Launch Summer Engine, optionally opening a project")
     .argument("[path]", "Path to a project directory (must contain project.godot)")
     .action(async (projectPath) => {
-    const port = await getApiPort();
-    const health = await checkEngineHealth(port);
-    if (health && !projectPath) {
-        console.log(`Summer Engine is already running (v${health.version}) on port ${port}`);
-        if (health.project_name) {
-            console.log(`  Project: ${health.project_name}`);
+    const fullProjectPath = projectPath ? resolve(projectPath) : null;
+    if (fullProjectPath) {
+        if (!existsSync(fullProjectPath)) {
+            console.error(`Directory not found: ${fullProjectPath}`);
+            process.exit(1);
+        }
+        if (!existsSync(join(fullProjectPath, "project.godot"))) {
+            console.error(`No project.godot found in ${fullProjectPath}\n` +
+                "This doesn't look like a Godot/Summer Engine project.");
+            process.exit(1);
         }
-        return;
-    }
-    const binary = findEngineBinary();
-    if (!binary) {
-        console.error("Summer Engine not found. Install it first:\n" +
-            "  summer install\n" +
-            "  or download from https://summerengine.com/download");
-        process.exit(1);
-    }
-    const args = ["--editor"];
-    if (projectPath) {
-        args.unshift("--path", projectPath);
     }
-    console.log("Launching Summer Engine...");
-    const child = spawn(binary, args, { detached: true, stdio: "ignore" });
-    child.unref();
-    // Wait for engine to start responding
-    const startTime = Date.now();
-    const timeout = 20000;
-    while (Date.now() - startTime < timeout) {
-        await sleep(500);
-        const newPort = await getApiPort();
-        const h = await checkEngineHealth(newPort);
-        if (h) {
-            console.log(`Summer Engine running (v${h.version}) on port ${newPort}`);
-            if (h.project_name) {
-                console.log(`  Project: ${h.project_name}`);
+    await withLaunchLock(async () => {
+        const port = await getApiPort();
+        const health = await checkEngineHealth(port);
+        if (health) {
+            const runningProjectPath = health.project_path
+                ? resolve(health.project_path)
+                : null;
+            if (!fullProjectPath || runningProjectPath === fullProjectPath) {
+                console.log(`Summer Engine is already running (v${health.version}) on port ${port}`);
+                if (health.project_name) {
+                    console.log(`  Project: ${health.project_name}`);
+                }
+                if (health.project_path) {
+                    console.log(`  Path: ${health.project_path}`);
+                }
+                return;
             }
+            console.log(`Summer Engine is already running (v${health.version}) on port ${port}`);
+            console.log(`  Current project: ${health.project_path ?? health.project_name ?? "unknown"}`);
+            console.error(`Refusing to launch a second editor for: ${fullProjectPath}\n` +
+                "Close or switch the current Summer Engine project first, then run this command again.");
+            process.exitCode = 1;
             return;
         }
-    }
-    console.log("Summer Engine launched but API not responding yet.\n" +
-        "It may still be loading. Run 'summer status' to check.");
+        const binary = findEngineBinary();
+        if (!binary) {
+            console.error("Summer Engine not found. Install it first:\n" +
+                "  summer install\n" +
+                "  or download from https://summerengine.com/download");
+            process.exitCode = 1;
+            return;
+        }
+        const args = ["--editor"];
+        if (fullProjectPath) {
+            args.unshift("--path", fullProjectPath);
+        }
+        console.log("Launching Summer Engine...");
+        const child = spawn(binary, args, { detached: true, stdio: "ignore" });
+        child.unref();
+        // Wait for engine to start responding
+        const startTime = Date.now();
+        const timeout = 20000;
+        while (Date.now() - startTime < timeout) {
+            await sleep(500);
+            const newPort = await getApiPort();
+            const h = await checkEngineHealth(newPort);
+            if (h) {
+                console.log(`Summer Engine running (v${h.version}) on port ${newPort}`);
+                if (h.project_name) {
+                    console.log(`  Project: ${h.project_name}`);
+                }
+                return;
+            }
+        }
+        console.log("Summer Engine launched but API not responding yet.\n" +
+            "It may still be loading. Run 'summer status' to check.");
+    });
 });
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));

package/dist/commands/setup.js

@@ -14,6 +14,8 @@ const AGENT_LABEL = {
     cline: "Cline",
     "roo-code": "Roo Code",
     gemini: "Gemini CLI",
+    "github-copilot": "GitHub Copilot CLI",
+    "vscode-copilot": "GitHub Copilot in VS Code",
     opencode: "OpenCode",
 };
 export const setupCommand = new Command("setup")
@@ -25,6 +27,7 @@ export const setupCommand = new Command("setup")
     .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")
+    .option("--force", "Overwrite existing skill content (passes --force through to skills install)")
     .action(async (agentArg, opts) => {
     const agent = resolveAgent(agentArg, opts.agent);
     const scope = resolveScope(opts.scope);
@@ -37,6 +40,7 @@ export const setupCommand = new Command("setup")
     const skills = setupRecommendedSkills(agent, {
         dryRun: Boolean(opts.dryRun || opts.print),
         yes: Boolean(opts.yes),
+        force: Boolean(opts.force),
     });
     const doctor = await runDoctor({ quiet: true });
     if (opts.json) {
@@ -72,7 +76,7 @@ function resolveScope(scopeOpt) {
     return parsed;
 }
 function setupRecommendedSkills(agent, options) {
-    const invocation = skillInstallInvocation(agent);
+    const invocation = skillInstallInvocation(agent, { force: options.force });
     if (!invocation) {
         return {
             status: "skipped",
@@ -107,13 +111,15 @@ function setupRecommendedSkills(agent, options) {
         stderr: result.stderr.trim(),
     };
 }
-function skillInstallInvocation(agent) {
+function skillInstallInvocation(agent, opts = { force: false }) {
     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];
+    if (opts.force)
+        baseArgs.push("--force");
     return {
         command,
         args: [...prefix, ...baseArgs],