summer-engine 2.7.0 → 2.8.1

package/dist/commands/create.js

@@ -1,14 +1,16 @@
 import { Command } from "commander";
-import { existsSync, mkdirSync, writeFileSync } from "fs";
-import { join, resolve } from "path";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, writeFileSync } from "fs";
+import { dirname, join, resolve } from "path";
+import { fileURLToPath } from "url";
 import { fetchRemoteTemplates, cloneTemplate, matchTemplate } from "../lib/remote-templates.js";
+import { SUMMER_ENGINE_COMPATIBILITY } from "../lib/summer-compatibility.js";
 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, "project.godot"), renderProjectSettings(name, "res://main.tscn"));
             writeFileSync(join(dir, "main.tscn"), emptyScene());
         },
     },
@@ -17,11 +19,34 @@ const BUILTIN_TEMPLATES = [
         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, "project.godot"), renderProjectSettings(name, "res://main.tscn"));
             writeFileSync(join(dir, "main.tscn"), basicScene3D());
         },
     },
 ];
+/**
+ * Copy the autopilot verification scaffold into a fresh project.
+ *
+ * Every project gets a working example of how to prove its own gameplay: a probe
+ * that drives the player with real input, saves rendered frames, asserts, and
+ * exits. Without it every agent reinvents verification from scratch, and most
+ * settle for asking the user to play the game instead.
+ *
+ * Never overwrites — an existing tests/autopilot/ is the user's, not ours.
+ */
+function scaffoldAutopilot(projectDir) {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // dist/commands/create.js -> package root
+    const source = resolve(here, "..", "..", "assets", "autopilot");
+    const target = join(projectDir, "tests", "autopilot");
+    if (!existsSync(source) || existsSync(target))
+        return false;
+    mkdirSync(target, { recursive: true });
+    for (const entry of readdirSync(source)) {
+        copyFileSync(join(source, entry), join(target, entry));
+    }
+    return true;
+}
 export const createCommand = new Command("create")
     .description("Create a new Summer Engine project. Built-in templates work offline; community templates clone from github.com/SummerEngine/template-*.")
     .argument("<template>", `Template slug. Built-in: ${BUILTIN_TEMPLATES.map((t) => t.name).join(", ")}. Or any community slug — see "summer list templates".`)
@@ -39,9 +64,12 @@ export const createCommand = new Command("create")
         console.log(`Creating project from built-in '${templateName}' template...`);
         mkdirSync(fullPath, { recursive: true });
         builtin.generate(fullPath, dirName);
+        const scaffolded = scaffoldAutopilot(fullPath);
         console.log(`\nProject created at ${fullPath}`);
         console.log("\nNext steps:");
         console.log(`  summer run ${dirName}`);
+        if (scaffolded)
+            console.log(`  bash ${dirName}/tests/autopilot/run.sh   (verify the game without opening it)`);
         console.log("  Ask your agent to run summer:brainstorm-game to create .summer/GameSoul.md");
         return;
     }
@@ -83,21 +111,25 @@ export const createCommand = new Command("create")
         console.error(err.message);
         process.exit(1);
     }
+    const scaffolded = scaffoldAutopilot(fullPath);
     console.log(`\nProject created at ${fullPath}`);
     console.log("Source: " + remote.url);
     console.log("\nNext steps:");
     console.log(`  summer run ${dirName}`);
+    if (scaffolded)
+        console.log(`  bash ${dirName}/tests/autopilot/run.sh   (verify the game without opening it)`);
     console.log("  Ask your agent to run summer:brainstorm-game to create .summer/GameSoul.md");
 });
-function projectGodot(name, mainScene) {
+export function renderProjectSettings(name, mainScene) {
     return `; Summer Engine Project
 ; Generated by summer-engine CLI
+; Technical base ${SUMMER_ENGINE_COMPATIBILITY.currentTechnicalBaseVersion}; Summer follows upstream continuously
 
 [application]
 
 config/name="${name}"
 run/main_scene="${mainScene}"
-config/features=PackedStringArray("4.5")
+config/features=PackedStringArray("${SUMMER_ENGINE_COMPATIBILITY.projectFeatureTag}")
 
 [rendering]
 

package/dist/commands/list.js

@@ -55,7 +55,7 @@ function listProjects() {
         }
     }
     if (projects.length === 0) {
-        console.log("No Summer Engine / Godot projects found in current directory.");
+        console.log("No Summer Engine projects found in current directory.");
         console.log("\nCreate one: summer create 3d-basic my-game");
         return;
     }

package/dist/commands/login.d.ts

@@ -1,2 +1,21 @@
 import { Command } from "commander";
 export declare const loginCommand: Command;
+export interface CreatorLoginDependencies {
+    openUrl: (url: string) => Promise<unknown>;
+    readSecret: (prompt: string) => Promise<string>;
+    log: (message: string) => void;
+}
+/**
+ * The browser session mints the token; the token is pasted once into a hidden
+ * prompt. This deliberately does not replace the core Summer login JWT.
+ */
+export declare function runCreatorLogin(overrides?: Partial<CreatorLoginDependencies>): Promise<void>;
+export interface LoginDependencies {
+    fetch: typeof fetch;
+    openUrl: (url: string) => Promise<unknown>;
+    randomId: () => string;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    log: (message: string) => void;
+}
+export declare function runLogin(overrides?: Partial<LoginDependencies>): Promise<void>;

package/dist/commands/login.js

@@ -1,49 +1,155 @@
 import { Command } from "commander";
 import { randomUUID } from "crypto";
 import open from "open";
-import { getAuthToken, saveAuthToken, saveCloudToken, saveUserInfo } from "../lib/auth.js";
-const GATEWAY_URL = process.env.SUMMER_GATEWAY_URL || "https://www.summerengine.com";
+import { getAuthToken, getCreatorToken, saveCreatorToken, saveLoginSession, } from "../lib/auth.js";
+import { getCreatorApiUrl, getGatewayUrl } from "../lib/config.js";
 const POLL_INTERVAL_MS = 2000;
-const POLL_TIMEOUT_MS = 120000;
+// One generous window on ONE session id. First-time users may need to create an
+// account and confirm an email before they can approve the CLI. The gateway
+// never expires a pending session (the completed payload waits under this id
+// for pickup), so the worst mistake would be rotating ids mid-wait — the user
+// would approve the original browser tab while we poll a different session.
+const POLL_TIMEOUT_MS = 900000;
+const HEARTBEAT_MS = 30000;
 export const loginCommand = new Command("login")
     .description("Sign in to Summer Engine via your browser")
+    .option("--creator", "Connect a separately scoped Summercraft creator token for publishing")
     .option("--force", "Force re-authentication even if already logged in")
     .action(async (opts) => {
+    if (opts.creator) {
+        const existingCreator = await getCreatorToken();
+        if (existingCreator && !opts.force) {
+            console.log("A creator token is already connected. Use --creator --force to replace it.");
+            return;
+        }
+        await runCreatorLogin();
+        return;
+    }
     const existing = await getAuthToken();
     if (existing && !opts.force) {
         console.log("Already logged in. Use --force to re-authenticate.");
         return;
     }
-    await doLogin();
+    await runLogin();
 });
-async function doLogin() {
-    const sessionId = randomUUID();
-    const loginUrl = `${GATEWAY_URL}/login?cli_session=${sessionId}`;
-    console.log("Sign in at: " + loginUrl);
-    console.log("");
+async function readHiddenLine(prompt) {
+    if (!process.stdin.isTTY || !process.stdout.isTTY) {
+        process.stdout.write(prompt);
+        let value = "";
+        for await (const chunk of process.stdin)
+            value += String(chunk);
+        return value.trim();
+    }
+    process.stdout.write(prompt);
+    const input = process.stdin;
+    const wasRaw = input.isRaw;
+    input.setRawMode(true);
+    input.resume();
+    return new Promise((resolve, reject) => {
+        let value = "";
+        const finish = (error) => {
+            input.off("data", onData);
+            input.setRawMode(Boolean(wasRaw));
+            input.pause();
+            process.stdout.write("\n");
+            if (error)
+                reject(error);
+            else
+                resolve(value.trim());
+        };
+        const onData = (chunk) => {
+            for (const char of String(chunk)) {
+                if (char === "\u0003") {
+                    finish(new Error("Creator token entry cancelled."));
+                    return;
+                }
+                if (char === "\r" || char === "\n" || char === "\u0004") {
+                    finish();
+                    return;
+                }
+                if (char === "\u007f" || char === "\b") {
+                    value = value.slice(0, -1);
+                }
+                else if (char >= " ") {
+                    value += char;
+                }
+            }
+        };
+        input.on("data", onData);
+    });
+}
+const defaultCreatorLoginDependencies = {
+    openUrl: open,
+    readSecret: readHiddenLine,
+    log: console.log,
+};
+/**
+ * The browser session mints the token; the token is pasted once into a hidden
+ * prompt. This deliberately does not replace the core Summer login JWT.
+ */
+export async function runCreatorLogin(overrides = {}) {
+    const deps = { ...defaultCreatorLoginDependencies, ...overrides };
+    const settingsUrl = `${await getCreatorApiUrl()}/creator/settings/tokens`;
+    deps.log(`Opening creator token settings: ${settingsUrl}`);
+    deps.log('Mint a token with the exact "publish" scope, copy its one-time sc_ value, then return here.');
     try {
-        await open(loginUrl);
+        await deps.openUrl(settingsUrl);
     }
     catch {
-        console.log("Could not open browser. Copy the URL above and open it manually.");
-        console.log("");
+        deps.log("Could not open the browser. Copy the URL above and open it manually.");
     }
-    console.log("Waiting for authentication...");
-    const pollUrl = `${GATEWAY_URL}/api/auth/cli-login?session=${sessionId}`;
-    const startTime = Date.now();
+    const token = await deps.readSecret("Creator token (input hidden): ");
+    await saveCreatorToken(token);
+    deps.log("Creator publishing connected. Your core Summer login token was not changed.");
+}
+const defaultDependencies = {
+    fetch,
+    openUrl: open,
+    randomId: randomUUID,
+    sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+    now: Date.now,
+    log: console.log,
+};
+export async function runLogin(overrides = {}) {
+    const deps = { ...defaultDependencies, ...overrides };
+    const gatewayUrl = await getGatewayUrl();
+    const sessionId = deps.randomId();
+    const loginUrl = `${gatewayUrl}/login?cli_session=${encodeURIComponent(sessionId)}`;
+    deps.log("Sign in at: " + loginUrl);
+    deps.log("");
+    try {
+        await deps.openUrl(loginUrl);
+    }
+    catch {
+        deps.log("Could not open browser. Copy the URL above and open it manually.");
+        deps.log("");
+    }
+    deps.log("Waiting for authentication...");
+    const pollUrl = `${gatewayUrl}/api/auth/cli-login?session=${encodeURIComponent(sessionId)}`;
+    const startTime = deps.now();
+    let lastHeartbeat = startTime;
     let lastError = null;
-    while (Date.now() - startTime < POLL_TIMEOUT_MS) {
-        await sleep(POLL_INTERVAL_MS);
+    while (deps.now() - startTime < POLL_TIMEOUT_MS) {
+        await deps.sleep(POLL_INTERVAL_MS);
+        if (deps.now() - lastHeartbeat >= HEARTBEAT_MS) {
+            lastHeartbeat = deps.now();
+            deps.log('Still waiting — finish signing in (or creating your account) in the browser, then click "Yes, Sign In". Same link: ' +
+                loginUrl);
+        }
         try {
-            const res = await fetch(pollUrl, {
+            const res = await deps.fetch(pollUrl, {
                 signal: AbortSignal.timeout(5000),
             });
             if (!res.ok) {
                 if (res.status === 503) {
-                    lastError = "Server not ready (Redis/auth not configured). Try again later.";
+                    lastError =
+                        "The login service is unavailable (Redis/auth is not configured).";
+                }
+                else if (res.status >= 400 && res.status < 500) {
+                    lastError = `The login request was rejected (${res.status}).`;
                 }
                 else if (res.status >= 500) {
-                    lastError = `Server error (${res.status}). Try again later.`;
+                    lastError = `The login service failed (${res.status}).`;
                 }
                 continue;
             }
@@ -51,28 +157,21 @@ async function doLogin() {
             if (data.status === "pending")
                 continue;
             if (data.status === "complete" && data.token) {
-                await saveAuthToken(data.token);
-                if (data.cloudToken) {
-                    await saveCloudToken(data.cloudToken);
-                }
-                if (data.user) {
-                    await saveUserInfo(data.user);
-                }
-                console.log(`\nLogged in as ${data.user?.email || "unknown"}`);
+                await saveLoginSession({
+                    token: data.token,
+                    cloudToken: data.cloudToken,
+                    user: data.user,
+                    scopes: data.scopes,
+                    cloudScopes: data.cloudScopes,
+                });
+                deps.log(`\nLogged in as ${data.user?.email || "unknown"}`);
                 return;
             }
+            lastError = "The login service returned an incomplete authentication result.";
         }
         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));
+    throw new Error(`Login timed out after ${Math.round(POLL_TIMEOUT_MS / 60000)} minutes.${lastError ? ` Last error: ${lastError}` : ""} Recovery: run "summer login" again and complete "Yes, Sign In" in the browser tab it opens.`);
 }

package/dist/commands/logout.js

@@ -1,23 +1,10 @@
 import { Command } from "commander";
-import { unlink } from "fs/promises";
-import { join } from "path";
-import { getSummerDir } from "../lib/auth.js";
+import { clearAuthCredentials } 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", "cloud-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) {
+    const removed = await clearAuthCredentials();
+    if (removed > 0) {
         console.log("Logged out. Auth tokens cleared.");
     }
     else {

package/dist/commands/logs.d.ts

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

package/dist/commands/logs.js

@@ -0,0 +1,19 @@
+import { Command } from "commander";
+import { readCreatorLogs } from "../lib/creator.js";
+export const logsCommand = new Command("logs")
+    .description("Read creator runtime logs")
+    .option("--project-id <id>", "Creator project ID")
+    .option("--release <id>", "Restrict logs to one release")
+    .option("--limit <count>", "Maximum log entries to return", "100")
+    .action(async (opts) => {
+    const limit = Number.parseInt(opts.limit, 10);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 1000) {
+        throw new Error("--limit must be between 1 and 1000. Recovery: pass a whole number in that range.");
+    }
+    await readCreatorLogs({
+        projectId: opts.projectId,
+        releaseId: opts.release,
+        limit,
+        face: "cli",
+    });
+});

package/dist/commands/mcp.js

@@ -3,8 +3,13 @@ import { configureAgentMcp, parseAgent, parseScope, supportedAgents, } from "../
 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();
+    .option("--project <path>", "Bind local engine tools to the editor running this project")
+    .option("--instance <id>", "Bind local engine tools to one exact Summer editor instance")
+    .action(async (opts) => {
+    await startMcpServer({
+        projectPath: opts.project,
+        instanceId: opts.instance,
+    });
 });
 mcpCommand
     .command("setup <agent>")

package/dist/commands/open.js

@@ -13,7 +13,7 @@ export const openCommand = new Command("open")
     }
     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" +
+            "This doesn't look like a Summer Engine project.\n" +
             "Create one with: summer create 3d-basic my-game");
         process.exit(1);
     }

package/dist/commands/publish.d.ts

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

package/dist/commands/publish.js

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { publishCreator } from "../lib/creator.js";
+export const publishCommand = new Command("publish")
+    .description("Publish a confirmed creator release")
+    .argument("[project]", "Project root. Defaults to the current directory.")
+    .requiredOption("--artifact <path>", "Exact exported Summer .pck artifact")
+    .requiredOption("--version <value>", "Immutable release version")
+    .option("--manifest <path>", "Optional JSON release manifest")
+    .option("--project-id <id>", "Creator project ID")
+    .option("--channel <name>", "Release channel")
+    .option("--notes <text>", "Release notes")
+    .option("--confirm", "Confirm the exact project and channel after reviewing them")
+    .action(async (project, opts) => {
+    const result = await publishCreator({
+        project,
+        ...opts,
+        face: "cli",
+    });
+    console.log(JSON.stringify(result, null, 2));
+});

package/dist/commands/releases.d.ts

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

package/dist/commands/releases.js

@@ -0,0 +1,20 @@
+import { Command } from "commander";
+import { listCreatorReleases } from "../lib/creator.js";
+export const releasesCommand = new Command("releases")
+    .description("List creator releases for a project")
+    .option("--project-id <id>", "Creator project ID")
+    .option("--limit <count>", "Maximum releases to return", "20")
+    .option("--cursor <value>", "Opaque cursor returned by the previous page")
+    .action(async (opts) => {
+    const limit = Number.parseInt(opts.limit, 10);
+    if (!Number.isInteger(limit) || limit < 1 || limit > 100) {
+        throw new Error("--limit must be between 1 and 100. Recovery: pass a whole number in that range.");
+    }
+    const result = await listCreatorReleases({
+        projectId: opts.projectId,
+        limit,
+        cursor: opts.cursor,
+        face: "cli",
+    });
+    console.log(JSON.stringify(result, null, 2));
+});

package/dist/commands/run.js

@@ -100,7 +100,7 @@ export const runCommand = new Command("run")
         }
         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.");
+                "This doesn't look like a Summer Engine project.");
             process.exit(1);
         }
     }

package/dist/lib/api-client.d.ts

@@ -1,3 +1,4 @@
+import { type EngineSelection } from "./engine.js";
 export type EngineSnapshot = {
     ok: boolean;
     localPath?: string;
@@ -28,6 +29,15 @@ export type EngineSnapshot = {
     sceneHasCamera?: boolean;
     sceneHadLight?: boolean;
     usedSyntheticCamera?: boolean;
+    /** Scene-preview only: the framing the engine actually rendered with
+     *  ("auto" resolves to "iso"). */
+    framing?: string;
+    /** Scene-preview only: path (relative to the scene root) of the node the
+     *  camera framed when nodePath was given. */
+    framedNode?: string;
+    /** Scene-preview only: how many blank-readback retries the engine needed
+     *  before the capture produced a non-blank frame (0 = clean first read). */
+    renderRetries?: number;
     /** Set true when the bound projectIdHash no longer matches the engine's live
      *  health hash at capture time — the frame may be from the WRONG project
      *  (item 4, client-side drift check). */
@@ -42,8 +52,9 @@ export declare class EngineApiClient {
     private port;
     private token;
     private targetIdentity;
-    constructor(port: number, token: string, targetIdentity?: EngineTargetIdentity | string);
-    static connect(): Promise<EngineApiClient>;
+    private selection;
+    constructor(port: number, token: string, targetIdentity?: EngineTargetIdentity | string, selection?: EngineSelection | null);
+    static connect(selection?: EngineSelection): Promise<EngineApiClient>;
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
     getBoundProjectIdHash(): string | undefined;
@@ -84,8 +95,11 @@ export declare class EngineApiClient {
      */
     executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
     readProjectFile(path: string, maxBytes?: number): Promise<unknown>;
-    getSceneState(scenePath?: string): Promise<unknown>;
-    getProjectState(): Promise<unknown>;
+    getSceneState(scenePath?: string, options?: {
+        depth?: number;
+        limit?: number;
+    }): Promise<unknown>;
+    getProjectState(prefix?: string): Promise<unknown>;
     getDiagnostics(): Promise<unknown>;
     inspectNode(path: string): Promise<unknown>;
     inspectResource(path: string): Promise<unknown>;
@@ -115,13 +129,18 @@ export declare class EngineApiClient {
      * Offscreen scene render via the `ScenePreview` op over /api/ops (no game
      * boot; physics/animations are static). Mirrors the web previewScene op input
      * (snapshot-tools.ts): { op:'ScenePreview', scene_path?, framing?, size?,
-     * node_path? } — scene_path optional, engine defaults to the open scene. The
-     * result carries image_base64 + mime (+ width/height) plus the P4.3 confession
-     * fields (scene_has_camera / scene_had_light / used_synthetic_camera).
+     * node? } — scene_path optional, engine defaults to the open scene. `node` is
+     * the canonical focus-node arg (the engine also accepts the legacy web wire
+     * name `node_path`); an unresolvable node fails with failure_reason
+     * "node_not_found". framing "auto" is an alias of "iso"; the engine also
+     * accepts "top"/"front"/"back"/"left"/"right" and echoes the resolved framing.
+     * The result carries image_base64 + mime (+ width/height) plus the P4.3
+     * confession fields (scene_has_camera / scene_had_light /
+     * used_synthetic_camera) and framing / framed_node / render_retries.
      */
     scenePreview(input?: {
         scenePath?: string;
-        framing?: "auto" | "top" | "front" | "iso";
+        framing?: "auto" | "iso" | "top" | "front" | "back" | "left" | "right";
         size?: [number, number];
         nodePath?: string;
     }): Promise<EngineSnapshot>;