summer-engine 2.5.0 → 2.6.0

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/lib/auth.d.ts

@@ -1,6 +1,8 @@
 export declare function getSummerDir(): string;
 export declare function getAuthToken(): Promise<string | null>;
 export declare function saveAuthToken(token: string): Promise<void>;
+export declare function getCloudToken(): Promise<string | null>;
+export declare function saveCloudToken(token: string): Promise<void>;
 export declare function getUserInfo(): Promise<{
     id: string;
     email: string;

package/dist/lib/auth.js

@@ -24,6 +24,19 @@ export async function saveAuthToken(token) {
     await ensureSummerDir();
     await writeFile(join(SUMMER_DIR, "auth-token"), token, { encoding: "utf-8", mode: 0o600 });
 }
+export async function getCloudToken() {
+    try {
+        const token = await readFile(join(SUMMER_DIR, "cloud-token"), "utf-8");
+        return token.trim() || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCloudToken(token) {
+    await ensureSummerDir();
+    await writeFile(join(SUMMER_DIR, "cloud-token"), token, { encoding: "utf-8", mode: 0o600 });
+}
 export async function getUserInfo() {
     try {
         const data = await readFile(join(SUMMER_DIR, "user.json"), "utf-8");

package/dist/lib/cloud/api.d.ts

@@ -0,0 +1,79 @@
+import type { CloudManifest } from "./types.js";
+export declare class CloudApiError extends Error {
+    readonly status: number;
+    readonly code: string;
+    readonly details: Record<string, unknown>;
+    constructor(status: number, code: string, message: string, details?: Record<string, unknown>);
+}
+export interface PresignedBlob {
+    sha256: string;
+    status: "exists" | "upload" | "quota_exceeded" | "too_large";
+    uploadId?: string;
+    url?: string;
+    headers?: Record<string, string>;
+    message?: string;
+}
+export interface RemoteManifest {
+    version: number;
+    rulesVersion: number;
+    manifest: CloudManifest;
+}
+/**
+ * Every server interaction goes through this interface so tests can run the
+ * full sync pipeline against an in-memory double (no network, no server).
+ */
+export interface CloudApi {
+    createCloudProject(body: {
+        projectId: string;
+    } | {
+        name: string;
+    }): Promise<{
+        projectId: string;
+        headVersion: number;
+    }>;
+    getCloudProject(projectId: string): Promise<{
+        projectId: string;
+        headVersion: number;
+        rulesVersion: number;
+    }>;
+    checkBlobs(projectId: string, hashes: string[]): Promise<{
+        missing: string[];
+    }>;
+    presignBlobs(projectId: string, blobs: Array<{
+        sha256: string;
+        size: number;
+    }>): Promise<{
+        blobs: PresignedBlob[];
+    }>;
+    completeBlobs(projectId: string, uploads: Array<{
+        sha256: string;
+        uploadId: string;
+    }>): Promise<{
+        uploads: Array<{
+            sha256: string;
+            status: string;
+        }>;
+    }>;
+    presignGet(projectId: string, hashes: string[]): Promise<{
+        urls: Record<string, string>;
+        missing: string[];
+    }>;
+    getManifest(projectId: string, version?: number): Promise<RemoteManifest>;
+    commitManifest(projectId: string, body: {
+        baseVersion: number;
+        manifestSha256: string;
+        syncId: string;
+        rulesVersion: number;
+    }): Promise<{
+        version: number;
+    }>;
+    restoreVersion(projectId: string, body: {
+        toVersion: number;
+        baseVersion: number;
+        syncId: string;
+    }): Promise<{
+        version: number;
+    }>;
+}
+export declare function getCloudApi(): CloudApi;
+export declare function setCloudApiForTests(api: CloudApi | null): void;

package/dist/lib/cloud/api.js

@@ -0,0 +1,107 @@
+import { getCloudToken } from "../auth.js";
+import { parseManifest } from "./manifest.js";
+const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+export class CloudApiError extends Error {
+    status;
+    code;
+    details;
+    constructor(status, code, message, details = {}) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.details = details;
+    }
+}
+async function cloudFetch(path, init = {}) {
+    const token = await getCloudToken();
+    if (!token) {
+        throw new CloudApiError(401, "unauthorized", "Run: summer login");
+    }
+    const res = await fetch(`${GATEWAY_URL}${path}`, {
+        ...init,
+        headers: {
+            ...(init.body ? { "content-type": "application/json" } : {}),
+            ...(init.headers ?? {}),
+            authorization: `Bearer ${token}`,
+        },
+    });
+    if (!res.ok) {
+        let body = null;
+        try {
+            body = await res.json();
+        }
+        catch {
+            // ignore
+        }
+        const error = body?.error ?? {};
+        throw new CloudApiError(res.status, error.code ?? "request_failed", error.message ?? `Cloud request failed (${res.status})`, error);
+    }
+    return (await res.json());
+}
+const realCloudApi = {
+    async createCloudProject(body) {
+        return cloudFetch("/api/cloud/projects", { method: "POST", body: JSON.stringify(body) });
+    },
+    async getCloudProject(projectId) {
+        return cloudFetch(`/api/cloud/projects/${projectId}`);
+    },
+    async checkBlobs(projectId, hashes) {
+        return cloudFetch("/api/cloud/blobs/check", {
+            method: "POST",
+            body: JSON.stringify({ projectId, hashes }),
+        });
+    },
+    async presignBlobs(projectId, blobs) {
+        return cloudFetch("/api/cloud/blobs/presign", {
+            method: "POST",
+            body: JSON.stringify({ projectId, blobs }),
+        });
+    },
+    async completeBlobs(projectId, uploads) {
+        return cloudFetch("/api/cloud/blobs/complete", {
+            method: "POST",
+            body: JSON.stringify({ projectId, uploads }),
+        });
+    },
+    async presignGet(projectId, hashes) {
+        return cloudFetch("/api/cloud/blobs/presign-get", {
+            method: "POST",
+            body: JSON.stringify({ projectId, hashes }),
+        });
+    },
+    async getManifest(projectId, version) {
+        const suffix = version !== undefined ? `?version=${version}` : "";
+        const meta = await cloudFetch(`/api/cloud/projects/${projectId}/manifest${suffix}`);
+        if (meta.version === 0) {
+            return {
+                version: 0,
+                rulesVersion: meta.rulesVersion ?? 1,
+                manifest: { schemaVersion: 1, projectId, rulesVersion: meta.rulesVersion ?? 1, files: {} },
+            };
+        }
+        const res = await fetch(meta.url);
+        if (!res.ok)
+            throw new CloudApiError(res.status, "manifest_download_failed", "Could not download manifest");
+        const bytes = Buffer.from(await res.arrayBuffer());
+        return { version: meta.version, rulesVersion: meta.rulesVersion, manifest: parseManifest(bytes, projectId) };
+    },
+    async commitManifest(projectId, body) {
+        return cloudFetch(`/api/cloud/projects/${projectId}/commit`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    },
+    async restoreVersion(projectId, body) {
+        return cloudFetch(`/api/cloud/projects/${projectId}/restore-version`, {
+            method: "POST",
+            body: JSON.stringify(body),
+        });
+    },
+};
+let activeApi = realCloudApi;
+export function getCloudApi() {
+    return activeApi;
+}
+export function setCloudApiForTests(api) {
+    activeApi = api ?? realCloudApi;
+}

package/dist/lib/cloud/apply.d.ts

@@ -0,0 +1,32 @@
+import type { ConflictSetWriter } from "./conflicts.js";
+import type { DiffPlan } from "./diff.js";
+import type { CloudManifest, LocalFileStat } from "./types.js";
+export interface ApplyContext {
+    /** Staged blob path per sha256 (downloaded and hash-verified). */
+    staged: Map<string, string>;
+    /** Actual on-disk byte-name path per NFC manifest key (from the walk). */
+    diskPathByKey: Map<string, string>;
+    /** Pre-image stats captured at hash time for the apply-time stat check. */
+    statByKey: Map<string, LocalFileStat>;
+    /** Conflict set writer; losing bytes are preserved through it. */
+    conflicts: ConflictSetWriter;
+    /** Base manifest (for the project.godot 3-way merge). */
+    base: CloudManifest | null;
+    /** Called once before the first destructive apply (modify or delete). */
+    onBeforeDestructive: () => Promise<void>;
+}
+export interface ApplyResult {
+    /** Paths written or deleted on disk (for the engine rescan). */
+    appliedPaths: string[];
+    notices: string[];
+    /** Local hashes preserved as conflict losers (pushed to R2 by the caller). */
+    preservedLocalHashes: Map<string, string>;
+}
+/**
+ * Two-phase pull, phase 2 (spec 8.7). Fixed order: renames first (case-only
+ * renames as two-step), then writes (project.godot and *.tscn last), then
+ * deletes. Every write is an atomic rename from staging; every modify or
+ * delete is preceded by exactly one full-tree checkpoint and a pre-image
+ * stat check that routes drifted files to conflicts instead of overwriting.
+ */
+export declare function applyRemotePlan(projectRoot: string, plan: DiffPlan, remote: CloudManifest, context: ApplyContext): Promise<ApplyResult>;