summer-engine 2.8.2 → 3.1.0

package/dist/{commands → cli/commands}/status.d.ts

@@ -1,2 +1,3 @@
 import { Command } from "commander";
 export declare const statusCommand: Command;
+export declare function runStatus(log: (message: string) => void): Promise<void>;

package/dist/cli/commands/status.js

@@ -0,0 +1,62 @@
+import { Command } from "commander";
+import { getAuthToken, getUserInfo, hasEnvAuthToken } from "../../core/auth.js";
+import { resolveGatewayUrl } from "../../core/config.js";
+import { getApiToken, getApiPort, checkEngineHealth } from "../../core/engine.js";
+export const statusCommand = new Command("status")
+    .description("Check Summer Engine status, connection, and auth state")
+    .action(async () => {
+    await runStatus(console.log);
+});
+export async function runStatus(log) {
+    log("Summer Engine Status\n");
+    const authToken = await getAuthToken();
+    if (!authToken) {
+        log("  Auth: Not logged in");
+        log("        Run: npx -y summer-engine@latest login");
+        log(`        Or: ${await loginPageHint()}`);
+    }
+    else if (hasEnvAuthToken()) {
+        // The env credential is what every gateway call uses; a stored identity
+        // (if any) is not the one in effect, so it is not printed.
+        log("  Auth: SUMMER_TOKEN (env) — logout does not affect it");
+    }
+    else {
+        log(`  Auth: Logged in${await storedIdentitySuffix()}`);
+    }
+    const apiToken = await getApiToken();
+    const port = await getApiPort();
+    if (!apiToken) {
+        log("  Engine: Not running (no api-token found)");
+        log("\n  To start: summer run");
+        return;
+    }
+    log("  API Token: Found (~/.summer/api-token)");
+    log(`  Port: ${port}`);
+    const health = await checkEngineHealth(port);
+    if (!health) {
+        log("  Engine: Not responding (may have closed since last launch)");
+        log("\n  To start: summer run");
+        return;
+    }
+    // /api/health carries no project name/path/scene (see EngineHealth in
+    // core/engine.ts); summer_get_project_context is the read for those.
+    log(`  Engine: Running (v${health.version})`);
+}
+/** A corrupt user.json must not take `summer status` down with it. */
+async function storedIdentitySuffix() {
+    try {
+        const userInfo = await getUserInfo();
+        return userInfo?.email ? ` as ${userInfo.email}` : "";
+    }
+    catch (error) {
+        return ` (identity unreadable: ${error instanceof Error ? error.message : String(error)})`;
+    }
+}
+async function loginPageHint() {
+    try {
+        return `${await resolveGatewayUrl()}/login`;
+    }
+    catch (error) {
+        return `(gateway.url is invalid: ${error instanceof Error ? error.message : String(error)})`;
+    }
+}

package/dist/cli/commands/tool.d.ts

@@ -0,0 +1,11 @@
+import { Command } from "commander";
+import { type ToolDispatchEntry } from "../../core/capabilities/tool-dispatch.js";
+/** Resolve a name through the compiled registry index when it exists —
+ *  accepts full ids ("tool/add-node") and legacy aliases, returning the slug
+ *  the dispatch table knows. Returns null when the index is absent or the
+ *  name is not a tool resource. */
+export declare function resolveViaRegistryIndex(name: string, root?: string): string | null;
+export declare function resolveToolForCli(name: string): ToolDispatchEntry | null;
+export declare function parseJsonArgs(raw: string | undefined): Record<string, unknown>;
+export declare function formatToolList(entries: readonly ToolDispatchEntry[]): string;
+export declare const toolCommand: Command;

package/dist/cli/commands/tool.js

@@ -0,0 +1,121 @@
+/**
+ * summer tool — CLI parity passthrough for every library tool resource.
+ *
+ * Dispatches through the shared registry in
+ * src/core/capabilities/tool-dispatch.ts (the same core capabilities, engine
+ * client, and gateway endpoints the MCP surface uses; contract §2: cli never
+ * imports mcp). Name resolution prefers the dispatch table and, when the
+ * compiled registry exists (registry/generated/index.json), also resolves
+ * library ids and legacy aliases through it.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { PACKAGE_ROOT } from "../../core/package-root.js";
+import { Command, Option } from "commander";
+import { ToolDispatchError, ToolResultError, dispatchTool, listToolDispatches, resolveToolDispatch, } from "../../core/capabilities/tool-dispatch.js";
+import { c } from "../../core/format.js";
+/** Resolve a name through the compiled registry index when it exists —
+ *  accepts full ids ("tool/add-node") and legacy aliases, returning the slug
+ *  the dispatch table knows. Returns null when the index is absent or the
+ *  name is not a tool resource. */
+export function resolveViaRegistryIndex(name, root = PACKAGE_ROOT) {
+    const indexPath = join(root, "registry", "generated", "index.json");
+    if (!existsSync(indexPath))
+        return null;
+    let resources;
+    try {
+        const parsed = JSON.parse(readFileSync(indexPath, "utf8"));
+        resources = Array.isArray(parsed.resources) ? parsed.resources : [];
+    }
+    catch {
+        return null;
+    }
+    const needle = name.trim();
+    for (const resource of resources) {
+        if (resource.kind !== "tool" || typeof resource.id !== "string")
+            continue;
+        const matches = resource.id === needle ||
+            resource.id === `tool/${needle}` ||
+            (Array.isArray(resource.aliases) && resource.aliases.includes(needle));
+        if (matches)
+            return resource.id.replace(/^tool\//, "");
+    }
+    return null;
+}
+export function resolveToolForCli(name) {
+    const direct = resolveToolDispatch(name);
+    if (direct)
+        return direct;
+    const viaRegistry = resolveViaRegistryIndex(name);
+    return viaRegistry ? resolveToolDispatch(viaRegistry) : null;
+}
+export function parseJsonArgs(raw) {
+    if (raw === undefined)
+        return {};
+    let parsed;
+    try {
+        parsed = JSON.parse(raw);
+    }
+    catch (err) {
+        throw new ToolDispatchError(`--args must be valid JSON: ${err instanceof Error ? err.message : String(err)}`);
+    }
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+        throw new ToolDispatchError("--args must be a JSON object of tool arguments");
+    }
+    return parsed;
+}
+export function formatToolList(entries) {
+    const width = Math.max(...entries.map((entry) => entry.slug.length));
+    const lines = [...entries]
+        .sort((a, b) => a.slug.localeCompare(b.slug))
+        .map((entry) => `  ${entry.slug.padEnd(width)}  ${entry.summary}${entry.engineRequired ? c.dim(" [engine]") : ""}`);
+    return [
+        c.bold(`Summer tools (${entries.length})`),
+        ...lines,
+        "",
+        c.dim("[engine] needs the Summer Engine app running with the project open."),
+        c.dim(`Run one: summer tool <name> --args '{"arg": "value"}'`),
+    ].join("\n");
+}
+export const toolCommand = new Command("tool")
+    .description("Run any Summer tool from the CLI — same implementations as the MCP surface")
+    .argument("[name]", "Tool name: library slug (add-node) or MCP alias (summer_add_node)")
+    .option("--args <json>", "Tool arguments as a JSON object (matches the tool's input_schema)")
+    .addOption(new Option("--json <args>", "Deprecated alias of --args").hideHelp())
+    .option("--list", "List every tool with a one-line summary")
+    .action(async (name, options) => {
+    if (options.list || name === undefined) {
+        console.log(formatToolList(listToolDispatches()));
+        if (name === undefined && !options.list) {
+            console.log("");
+            console.log(c.dim("Pass a tool name to run one."));
+        }
+        return;
+    }
+    const entry = resolveToolForCli(name);
+    if (!entry) {
+        throw new ToolDispatchError(`Unknown tool "${name}". Run 'summer tool --list' to see all ${listToolDispatches().length} tools.`);
+    }
+    if (options.json !== undefined && options.args === undefined) {
+        console.error("Note: 'summer tool --json <args>' is deprecated; use --args <json>.");
+    }
+    const args = parseJsonArgs(options.args ?? options.json);
+    let result;
+    try {
+        result = await dispatchTool(entry.slug, args);
+    }
+    catch (err) {
+        // A structured failure — any engine receipt the MCP face would mark
+        // isError, engine_lacks_op, a library/navigation miss — is printed whole
+        // (stdout, exit 1) so callers read ok/error/failure_reason instead of
+        // scraping a sentence. Argument and connection errors stay plain text on
+        // stderr (thrown; the program's catch exits 1).
+        if (err instanceof ToolResultError) {
+            console.log(JSON.stringify(err.result, null, 2));
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    console.log(JSON.stringify(result, null, 2));
+});

package/dist/cli/index.d.ts

@@ -0,0 +1,6 @@
+import { Command } from "commander";
+/**
+ * Build and run the summer CLI. The `mcp` command is injected by the bin
+ * entry (the composition root) so the cli layer never imports from src/mcp.
+ */
+export declare function runCli(mcpCommand: Command): void;

package/dist/cli/index.js

@@ -0,0 +1,89 @@
+import { Command } from "commander";
+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 { memoryCommand } from "./commands/memory.js";
+import { skillsCommand } from "./commands/skills.js";
+import { setupCommand } from "./commands/setup.js";
+import { doctorCommand } from "./commands/doctor.js";
+import { planCommand } from "./commands/plan.js";
+import { debugCommand } from "./commands/debug.js";
+import { configCommand } from "./commands/config.js";
+import { publishCommand } from "./commands/publish.js";
+import { releasesCommand } from "./commands/releases.js";
+import { eventsCommand } from "./commands/events.js";
+import { toolCommand } from "./commands/tool.js";
+import { getBanner } from "./banner.js";
+import { runRootAction } from "./root-action.js";
+import { c, sym } from "../core/format.js";
+import { TOOLKIT_VERSION as version } from "../core/version.js";
+/**
+ * Build and run the summer CLI. The `mcp` command is injected by the bin
+ * entry (the composition root) so the cli layer never imports from src/mcp.
+ */
+export function runCli(mcpCommand) {
+    const program = new Command();
+    program
+        .name("summer")
+        .description("CLI and MCP tools for Summer Engine — the AI-native game engine")
+        .version(version)
+        .action((_opts, command) => {
+        runRootAction(command.args, () => printIntro(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(memoryCommand);
+    program.addCommand(skillsCommand);
+    program.addCommand(mcpCommand);
+    program.addCommand(setupCommand);
+    program.addCommand(doctorCommand);
+    program.addCommand(debugCommand);
+    program.addCommand(planCommand);
+    program.addCommand(configCommand);
+    program.addCommand(publishCommand);
+    program.addCommand(releasesCommand);
+    program.addCommand(eventsCommand);
+    program.addCommand(toolCommand);
+    program.parseAsync().catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+}
+function printIntro(version) {
+    console.log("");
+    console.log(getBanner());
+    console.log("");
+    console.log(`     ${sym.arrow()} ${c.bold("Summer Engine")} ${c.dim("v" + version)}  ${c.dim("·")}  AI-native game engine`);
+    console.log("");
+    console.log(`     ${c.bold("Setup wizard")}`);
+    console.log(`     Open Claude Code, Cursor, Codex, Copilot, Devin Desktop (formerly Windsurf), or another supported agent and paste:`);
+    console.log(`     ${c.brand("\"Install Summer Engine and let's make a game.\"")}`);
+    console.log("");
+    console.log(`     ${c.bold("Manual commands")}`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest setup claude-code --yes`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest create 3d-basic my-game`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest plan make a small arena shooter`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest debug "player crashes on pickup"`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest memory`);
+    console.log(`     ${c.dim("$")} npx -y summer-engine@latest doctor`);
+    console.log("");
+    console.log(`     ${c.bold("Slash commands")} ${c.dim("(in your AI agent)")}`);
+    console.log(`     ${c.brand("/summer debug")}   ${c.dim("Create a support-ready debug report")}`);
+    console.log(`     ${c.brand("/debug")}   ${c.dim("Triage and fix a bug end-to-end")}`);
+    console.log(`     ${c.brand("/play")}    ${c.dim("Run the game and report state")}`);
+    console.log("");
+    console.log(`     ${c.dim("Docs:")} https://summerengine.com/docs`);
+    console.log(`     ${c.dim("Source:")} https://github.com/summerengine/summer`);
+    console.log("");
+}

package/dist/cli/root-action.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Root `summer` invocation. Commander routes an unknown subcommand
+ * (`summer bogus`) to the program action with the stray word as an operand,
+ * so a bare-intro action would print the banner and exit 0. Agents probe
+ * commands by exit code — an unknown command must fail.
+ */
+export declare function runRootAction(operands: readonly string[], printIntro: () => void): void;

package/dist/cli/root-action.js

@@ -0,0 +1,15 @@
+/**
+ * Root `summer` invocation. Commander routes an unknown subcommand
+ * (`summer bogus`) to the program action with the stray word as an operand,
+ * so a bare-intro action would print the banner and exit 0. Agents probe
+ * commands by exit code — an unknown command must fail.
+ */
+export function runRootAction(operands, printIntro) {
+    if (operands.length > 0) {
+        console.error(`error: unknown command '${operands[0]}'`);
+        console.error("Run 'summer --help' to see the available commands.");
+        process.exitCode = 1;
+        return;
+    }
+    printIntro();
+}

package/dist/{lib → core}/api-client.d.ts

@@ -1,4 +1,6 @@
-import { type EngineSelection } from "./engine.js";
+import { type DiscoverEngineOptions, type EngineSelection } from "./engine.js";
+import type { EngineCapabilities } from "./capability-skew.js";
+import { type PlayDeterminism } from "./capabilities/play-determinism.js";
 export type EngineSnapshot = {
     ok: boolean;
     localPath?: string;
@@ -48,13 +50,52 @@ type EngineTargetIdentity = {
     projectId?: string;
     projectIdHash?: string;
 };
+/** Query parameters of GET /api/events/poll (the engine's events channel). */
+export type EventsPollParams = {
+    /** Deliver events with seq > since. Omitted = live only (from the newest
+     *  seq at request time); 0 = replay the whole retained ring. A value beyond
+     *  the newest seq is clamped by the engine so the caller resyncs. */
+    since?: number;
+    /** Allow-list of event kinds (op.applied, play.started, ...); omitted or
+     *  empty = every kind. */
+    kinds?: string[];
+    /** Max ms the engine holds the request before answering with zero events
+     *  (engine default 25000, cap 60000; 0 = answer immediately). */
+    wait?: number;
+    /** Max events per answer (engine default 100, cap 500); the answer says
+     *  truncated:true when the page was full. */
+    limit?: number;
+};
+/** rebind() could not re-read engine health; the session identity is unchanged. */
+export declare class EngineRebindError extends Error {
+    constructor(message: string);
+}
 export declare class EngineApiClient {
     private port;
     private token;
     private targetIdentity;
     private selection;
+    private registryDiscovery;
+    private lastHealth;
     constructor(port: number, token: string, targetIdentity?: EngineTargetIdentity | string, selection?: EngineSelection | null);
-    static connect(selection?: EngineSelection): Promise<EngineApiClient>;
+    /**
+     * With a selection (the MCP server: --project / --instance / its cwd) the
+     * registry decides — resolveEngineConnection. Without one (the CLI face):
+     * SUMMER_ENGINE_PROJECT / SUMMER_ENGINE_INSTANCE_ID when set (same names the
+     * MCP server reads), else the global pointer (~/.summer/api-token + api-port)
+     * when it names an engine that answers /api/health — today's behaviour,
+     * unchanged — else the instance registry (discoverRegistryConnection), so an
+     * editor launched `--summer-no-publish` or a second editor is still found.
+     * The pointer is read through getApiPort/getApiToken/checkEngineHealth so
+     * tests that stub those readers never touch the real ~/.summer. `discovery`
+     * is a test seam (fake ~/.summer, cwd, env).
+     */
+    static connect(selection?: EngineSelection, discovery?: DiscoverEngineOptions): Promise<EngineApiClient>;
+    /** The engine's capability advert from the last health read (connect or
+     *  rebind), or undefined when the engine predates the advert. */
+    getEngineCapabilities(): EngineCapabilities | undefined;
+    /** Engine version string from the last health read, for skew messages. */
+    getEngineVersion(): string | undefined;
     /** The projectIdHash this session is bound to (undefined if none was reported
      *  at connect — e.g. no project open yet). */
     getBoundProjectIdHash(): string | undefined;
@@ -64,6 +105,10 @@ export declare class EngineApiClient {
      * switch (the deliberate escape hatch after an identity_mismatch). Returns the
      * new bound hash. The direct health probe is intentionally unscoped, so it can
      * reach the current engine even when bound requests would be rejected.
+     *
+     * Throws EngineRebindError when the health probe fails: the previous identity
+     * is kept, and reporting it as "the rebound hash" would tell the agent a
+     * switch it never followed had succeeded.
      */
     rebind(): Promise<string | undefined>;
     /** Identity to attach to a MUTATING command's options so the engine can reject
@@ -86,14 +131,39 @@ export declare class EngineApiClient {
      * state instead of pretending the accepted operation did not apply.
      */
     private _requestQueued;
+    /**
+     * The post-submission half of _requestQueued: classify an already-fetched
+     * response (200 legacy / 202 queued / 429 backpressure) and, for 202, poll
+     * the accepted requestId to its terminal receipt. Split out so a caller that
+     * has to inspect the raw status first (gameSnapshot's 409 bridge check) can
+     * feed its ONE response in here instead of issuing a second request.
+     */
+    private _resolveQueuedResponse;
     health(): Promise<unknown>;
-    executeOps(ops: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
+    /**
+     * One long-poll of GET /api/events/poll (the engine's events channel). The
+     * engine answers on the first event matching `kinds` with seq > `since`, or
+     * after `wait` ms with `timed_out:true`; a 2xx is the poll envelope
+     * {ok, events:[{seq, kind, ts, data}], next_seq, last_seq, since, truncated,
+     * timed_out}. Identity-gated like every other route: the bound project rides
+     * in the query, so a wrong project answers 409 identity_mismatch.
+     *
+     * The three answers this route documents — 404 (no channel on this build),
+     * 409 (identity mismatch), 503 (bus not started) — come back as a STRUCTURED
+     * failure {ok:false, http_status, ...body} so both faces classify them (a
+     * terminalState keeps its standard message and rebind hint; the events
+     * capability rewrites a 404 into engine_lacks_events). Anything else throws
+     * like every other request, so a stale-token 401/403 still triggers
+     * withEngine's reconnect-and-retry.
+     */
+    pollEvents(params?: EventsPollParams, timeoutMs?: number): Promise<unknown>;
+    executeOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
     /**
      * Mutation path for MCP file tools. Unlike legacy executeOps callers, this
      * fails closed when health did not provide a complete target identity. The
      * bound hash is stamped last so a caller cannot override it in options.
      */
-    executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>): Promise<unknown>;
+    executeIdentityBoundOps(ops: Record<string, unknown>[], options?: Record<string, unknown>, timeoutMs?: number): Promise<unknown>;
     readProjectFile(path: string, maxBytes?: number): Promise<unknown>;
     getSceneState(scenePath?: string, options?: {
         depth?: number;
@@ -104,7 +174,7 @@ export declare class EngineApiClient {
     inspectNode(path: string): Promise<unknown>;
     inspectResource(path: string): Promise<unknown>;
     getScriptErrors(path: string): Promise<unknown>;
-    play(scene?: string): Promise<unknown>;
+    play(scene?: string, determinism?: PlayDeterminism): Promise<unknown>;
     stop(): Promise<unknown>;
     readFile(path: string, maxBytes?: number): Promise<unknown>;
     getFsTree(root?: string, limit?: number): Promise<unknown>;
@@ -115,14 +185,12 @@ export declare class EngineApiClient {
      *  Used by viewport/game snapshots and by scenePreview. */
     private _parseSnapshotResponse;
     /**
-     * Probe /api/snapshot/game for the structural 409 `bridge_required` shape
-     * (tool_net_thread.cpp:495-503). Returns a structured failure only when the
-     * engine actually answers 409 with `bridge_required` / `unsupported_transport`;
-     * ANY other status (200/202/other) returns null so the caller proceeds to the
-     * normal queued path — so the moment the engine starts answering over HTTP
-     * (P4.4), game capture just works with no code change here.
+     * Turn a 409 from /api/snapshot/game into a structured failure. The engine's
+     * structural refusal carries `bridge_required` / `unsupported_transport`
+     * (tool_net_thread.cpp:495-503); a 409 without that shape is surfaced as a
+     * plain error rather than silently claiming "bridge required".
      */
-    private _detectBridgeRequired;
+    private _bridgeRequiredFromResponse;
     viewportSnapshot(): Promise<EngineSnapshot>;
     gameSnapshot(): Promise<EngineSnapshot>;
     /**
@@ -134,15 +202,38 @@ export declare class EngineApiClient {
      * 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 /
+     * framing "camera" renders through the scene's current/first Camera3D — or
+     * the Camera3D named by `cameraPath` — with the scene's REAL WorldEnvironment
+     * instead of the flat preview substitute; the engine echoes the resolved
+     * framing, so an older build that ignores the value is detectable by the
+     * caller. 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.
+     *
+     * Perception additions (engine scene-scripting contracts): framing "free" takes
+     * `cameraPosition` / `cameraLookAt` (Godot "Vector3(x, y, z)" literals) and
+     * `fov`; framing "bookmark:<name>" resolves the pose from the project's
+     * camera bookmarks (fov overrides the bookmark's). `marks` draws the
+     * Set-of-Mark overlay (numbered tags + boxes over the largest visible
+     * VisualInstance3D nodes), capped by `maxMarks`. The result adds
+     * framing_source / camera_pose / bookmark and marks / marks_skipped /
+     * marks_candidates / marks_truncated / max_marks (all kept in `metadata`).
+     * Older engines resolve the new framings to a preset and echo THAT — the
+     * caller compares the echo against what it asked for.
      */
     scenePreview(input?: {
         scenePath?: string;
-        framing?: "auto" | "iso" | "top" | "front" | "back" | "left" | "right";
+        /** A preset ("auto" | "iso" | "top" | "front" | "back" | "left" | "right" |
+         *  "camera"), "free", or "bookmark:<name>". */
+        framing?: string;
         size?: [number, number];
         nodePath?: string;
+        cameraPath?: string;
+        cameraPosition?: string;
+        cameraLookAt?: string;
+        fov?: number;
+        marks?: boolean;
+        maxMarks?: number;
     }): Promise<EngineSnapshot>;
     getPort(): number;
     /**