summer-engine 4.2.0 → 4.5.0

package/dist/cli/commands/ops.js

@@ -1,13 +1,15 @@
 import { Command } from "commander";
 import { CLI_AREAS } from "../../core/ops/areas.js";
-import { localEntries, localInputSchema, localWireForm, missingInput } from "../../core/ops/catalog.js";
+import { closestActions, localEntries, localInputSchema, localWireForm, missingInput, resolveCliOp } from "../../core/ops/catalog.js";
+import { shippedCloudEntries, shippedWireForm } from "../../core/ops/public-catalog.js";
 import { answerOfHosted, callHostedV4, describeFromShipped, hostedCallFailure, searchEverywhere } from "../../core/ops/cloud.js";
-import { errorAnswer, isLocalOp, localToolsFor, opFromCli, OP_NAME, resolveOpName } from "../../core/ops/contract.js";
+import { errorAnswer, isLocalOp, localToolsFor, OP_NAME, resolveOpName } from "../../core/ops/contract.js";
 import { ENGINE_SPLIT_OPS, engineOpDef, splitToolArgs } from "../../core/ops/engine.js";
-import { engineFailure, engineNotRunning } from "../../core/ops/engine-answer.js";
+import { codedLocalFailure, engineFailure, engineNotRunning } from "../../core/ops/engine-answer.js";
 import { loadLibraryIndex } from "../../core/library-search.js";
 import { FileSaver, withOutField } from "../../core/ops/save-files.js";
 import { dispatchTool, EngineUnavailableError, ToolResultError } from "../../core/capabilities/tool-dispatch.js";
+import { noteCliError, noteCliHosted } from "../../core/cli-usage.js";
 /**
  * The CLI view of the operation catalog (on by default; SUMMER_SURFACE=v3 leaves it out):
  *
@@ -112,8 +114,12 @@ async function runLocal(op, call, deps) {
     const split = ENGINE_SPLIT_OPS[op];
     const entry = localEntries().find((candidate) => candidate.name === op);
     const tool = split?.tool ?? entry?.mcpTool ?? localToolsFor(op)[0];
-    if (!tool)
-        return errorAnswer("not_found", `No operation is named "${op}".`, { next: { op: "ops.search", input: { query: op } } });
+    if (!tool) {
+        const [area] = op.split(".");
+        const closest = closestActions(op).map((action) => `summer ${area} ${action}`);
+        const hint = closest.length ? ` Closest: ${closest.join(", ")}. All of them: summer ${area} --help` : "";
+        return errorAnswer("not_found", `No operation is named "${op}".${hint}`, { next: { op: "ops.search", input: { query: op } } });
+    }
     // maxCharacters cuts the text an MCP client gets; the CLI prints the whole answer.
     const { maxCharacters, ...input } = call.input;
     const uncut = maxCharacters === undefined ? undefined : ["maxCharacters: the CLI prints the whole answer; cut it in the shell (for example | head -c 8000)."];
@@ -134,7 +140,9 @@ async function runLocal(op, call, deps) {
         if (error instanceof EngineUnavailableError)
             return engineNotRunning();
         if (error instanceof ToolResultError) {
-            return def ? engineFailure(JSON.stringify(error.result), op, { effect: def.effect, guide }) : errorAnswer("invalid_input", error.message, { details: { tool: error.result } });
+            if (def)
+                return engineFailure(JSON.stringify(error.result), op, { effect: def.effect, guide });
+            return codedLocalFailure(error.result) ?? errorAnswer("invalid_input", error.message, { details: { tool: error.result } });
         }
         return errorAnswer("invalid_input", error instanceof Error ? error.message : String(error), { next: describe });
     }
@@ -195,12 +203,19 @@ async function waitFor(answer, deps) {
 /** A value as one shell word: single quotes, so the shell expands nothing in it. */
 const shellWord = (value) => (/^[\w./:@+=-]+$/.test(value) ? value : `'${value.replace(/'/g, `'\\''`)}'`);
 /** The answer for a person; `out` is the --out to keep in the printed wait command. */
+/** A failure's problem list (a manifest's fields), one per line: in the answer's details or its tool's structured result. */
+function problemLines(details) {
+    const tool = details?.tool && typeof details.tool === "object" ? details.tool : undefined;
+    const problems = Array.isArray(details?.problems) ? details.problems : Array.isArray(tool?.problems) ? tool.problems : [];
+    const lines = problems.filter((problem) => typeof problem === "string");
+    return lines.length ? `\n${lines.map((problem) => `  - ${problem}`).join("\n")}` : "";
+}
 export function formatAnswer(answer, out) {
     const waitFlags = (id) => `summer jobs wait --job-id ${id}${out ? ` --out ${shellWord(out)}` : ""}`;
     if (!answer.ok) {
         const next = answer.error.next;
         const step = !next ? "" : "op" in next ? `\nNext: ${next.op}` : "url" in next ? `\nNext: ${next.label}: ${next.url}` : `\nNext: ${next.say}`;
-        return `Error (${answer.error.code}): ${answer.error.message}${step}`;
+        return `Error (${answer.error.code}): ${answer.error.message}${problemLines(answer.error.details)}${step}`;
     }
     switch (answer.status) {
         case "done":
@@ -236,6 +251,8 @@ export async function runOpFromCli(op, argv, deps = defaultOpsCliDeps) {
             answer = await waitFor(answer, deps);
     }
     else {
+        // Summer's server records a cloud operation itself (X-Summer-Client-Surface: cli).
+        noteCliHosted();
         // --out stays here: the files save on this machine once the answer (or the waited job) names them.
         const files = deps.files ?? new FileSaver({ saveByDefault: true });
         const taken = files.take(op, call.input);
@@ -245,6 +262,8 @@ export async function runOpFromCli(op, argv, deps = defaultOpsCliDeps) {
             answer = await waitFor(answer, deps);
         answer = await files.finish(op, answer, out);
     }
+    if (!answer.ok)
+        noteCliError(answer.error.code);
     (answer.ok ? deps.print : deps.printError)(call.json ? JSON.stringify(answer) : formatAnswer(answer, out));
     if (!call.json && answer.ok)
         for (const warning of answer.warnings ?? [])
@@ -289,15 +308,89 @@ export async function describeFromCli(op, deps = defaultOpsCliDeps, options = {}
             deps.printError(`Warning: ${warning}`);
     return answer.ok ? 0 : 1;
 }
+const HELP_WORDS = new Set(["--help", "-h", "help"]);
+/** gameId -> game-id, look_at -> look-at: the flag a field takes. */
+const flagOf = (field) => field.replace(/_/g, "-").replace(/[A-Z]/g, (letter) => `-${letter.toLowerCase()}`);
+const VIEW_FLAGS = "[--input '<json>'] [--dry-run] [--wait] [--json]";
+/** `summer <area> --help`: the area's actions, from this package and the shipped catalog (no network). */
+export function areaHelp(area) {
+    const titles = new Map();
+    for (const entry of [...localEntries(), ...shippedCloudEntries()]) {
+        if (entry.name.startsWith(`${area}.`) && !titles.has(entry.name))
+            titles.set(entry.name, entry.title);
+    }
+    const actions = [...titles].map(([name, title]) => [flagOf(name.slice(area.length + 1)), title]).sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));
+    const width = Math.max(0, ...actions.map(([action]) => action.length));
+    return [
+        `Usage: summer ${area} <action> [--<field> <value> ...] ${VIEW_FLAGS}`,
+        "",
+        ...(actions.length ? ["Actions:", ...actions.map(([action, title]) => `  ${action.padEnd(width)}  ${title}`)] : [`This version lists no ${area} operations; signed in, summer ops search ${area} finds the server's.`]),
+        "",
+        `One action's fields: summer ${area} <action> --help`,
+    ].join("\n");
+}
+/** One operation's help: its command, what it does, who approves, the sign-in and each field as a flag. */
+export function operationHelp(operation) {
+    const [area, action] = operation.name.split(".");
+    const command = action ? `summer ${area} ${flagOf(action)}` : `summer ${area}`;
+    const required = new Set(operation.input?.required ?? []);
+    const fields = Object.entries(operation.input?.properties ?? {}).map(([field, schema]) => {
+        const type = Array.isArray(schema.type) ? schema.type[0] : schema.type;
+        const flag = `--${flagOf(field)}${type === "boolean" ? "" : ` <${type ?? "value"}>`}`;
+        const description = schema.description ?? "";
+        return [flag, `${required.has(field) ? "Required. " : ""}${description}`.trim()];
+    });
+    const width = Math.max(0, ...fields.map(([flag]) => flag.length));
+    const signIn = operation.auth === "account" ? "Needs a sign-in: summer login (the store sign-in alone: summer login --store)." : "Works signed out.";
+    return [
+        `Usage: ${command} ${fields.length ? "[--<field> <value> ...] " : ""}${VIEW_FLAGS}`,
+        "",
+        `${operation.title ?? operation.name}${operation.summary ? `: ${operation.summary}` : ""}`,
+        `Effect: ${operation.effect ?? "unknown"}. Approval: ${operation.approval ?? "none"}. ${signIn}`,
+        ...(fields.length ? ["", "Fields:", ...fields.map(([flag, text]) => `  ${flag.padEnd(width)}  ${text}`)] : []),
+        "",
+        `The exact input: summer ops describe ${operation.name}`,
+    ].join("\n");
+}
+/** `summer <area> <action> --help`: from this package or the shipped catalog; the server only for an operation newer than both. */
+export async function operationHelpFromCli(op, deps = defaultOpsCliDeps) {
+    const name = resolveOpName(op);
+    let operation = (localWireForm(name) ?? shippedWireForm(name));
+    if (!operation) {
+        const asked = await runCloud("ops.describe", { input: { name }, json: true, dryRun: false, wait: false }, deps);
+        if (!asked.ok || asked.status !== "done") {
+            deps.printError(formatAnswer(asked));
+            return 1;
+        }
+        operation = asked.result.operation ?? null;
+        if (!operation) {
+            deps.printError(formatAnswer(errorAnswer("not_found", `No operation is named "${name}".`, { next: { op: "ops.search", input: { query: name } } })));
+            return 1;
+        }
+    }
+    deps.print(operationHelp(operation));
+    return 0;
+}
 function areaCommand(area) {
     return new Command(area)
         .description(`Summer ${area} operations: summer ${area} <action> --field value. Find them: summer ops search ${area}`)
-        .argument("<action>", "The operation's action, e.g. list or set-base")
+        .argument("[action]", "The operation's action, e.g. list or set-base")
         .allowUnknownOption(true)
         .allowExcessArguments(true)
         .helpOption(false)
         .action(async (action, _options, command) => {
-        process.exitCode = await runOpFromCli(opFromCli(area, action), command.args.slice(1));
+        // Our own help: commander's would list no actions and no fields.
+        if (action === undefined || HELP_WORDS.has(action)) {
+            (action === undefined ? defaultOpsCliDeps.printError : defaultOpsCliDeps.print)(areaHelp(area));
+            process.exitCode = action === undefined ? 1 : 0;
+            return;
+        }
+        const argv = command.args.slice(1);
+        // A 3.x tool name as the action runs its operation (resolveCliOp).
+        const op = resolveCliOp(area, action);
+        process.exitCode = argv.some((token) => HELP_WORDS.has(token) && token !== "help")
+            ? await operationHelpFromCli(op)
+            : await runOpFromCli(op, argv);
     });
 }
 export function opsCliCommands() {

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

@@ -0,0 +1,58 @@
+/**
+ * summer preview — the running game in a local web page, so an agent's own
+ * browser (Claude Code Desktop's Browser pane, the Codex app's in-app browser)
+ * can see it, screenshot it and check it after every edit.
+ *
+ *   summer preview                 http://127.0.0.1:5199 (next free port if taken)
+ *   summer preview --port 5300     exactly that port (Desktop rewrites this one)
+ *   summer preview --open          also open it in the default browser
+ *
+ * Run it in the folder the agent session works in: the project itself, a
+ * folder inside it, or a folder above it (a repo with the game in game/). The
+ * preview shows that project's editor only, and adds a summer-preview entry to
+ * <that folder>/.claude/launch.json (never changing other entries), which is
+ * where Desktop reads it when the session started there; Desktop then starts
+ * the preview itself and verifies changes with it. --no-launch-json skips that.
+ * The server, the page and the writer live in core/preview/.
+ */
+import { Command } from "commander";
+import { type EngineSelection } from "../../core/engine.js";
+import type { PreviewEngine } from "../../core/preview/preview-source.js";
+import { type PreviewServer } from "../../core/preview/server.js";
+export interface PreviewCommandOptions {
+    port?: string;
+    launchJson?: boolean;
+    open?: boolean;
+    json?: boolean;
+}
+export interface PreviewIo {
+    cwd: string;
+    env: NodeJS.ProcessEnv;
+    out(line: string): void;
+    err(line: string): void;
+    connect(selection: EngineSelection | undefined): Promise<PreviewEngine>;
+    openUrl(url: string): Promise<void>;
+}
+/** --port asks for exactly that port; without it, 5199 or the next free one.
+ *  A PORT variable is not read: shells often export one for a web app, and
+ *  Desktop passes the port it picked in --port. */
+export declare function resolvePreviewPort(flag: string | undefined): {
+    port: number;
+    strict: boolean;
+};
+export interface PreviewProject {
+    /** The folder with project.godot, or null outside any project. */
+    projectRoot: string | null;
+    /** Where .claude/launch.json goes: the folder the command runs in. */
+    sessionRoot: string;
+    /** The entry's cwd when the project sits below the session folder. */
+    entryCwd?: string;
+}
+/** The project `summer preview` is for: at or above `cwd` (the same walk as
+ *  `summer setup`), else the one project below it. Several below is an error. */
+export declare function findPreviewProject(cwd: string): PreviewProject;
+/** Start the preview; resolves with the running server (the command keeps it
+ *  open until Ctrl-C). Throws on a bad --port, a taken explicit port, or
+ *  several projects below the folder. */
+export declare function runPreview(opts: PreviewCommandOptions, io: PreviewIo): Promise<PreviewServer>;
+export declare const previewCommand: Command;

package/dist/cli/commands/preview.js

@@ -0,0 +1,181 @@
+/**
+ * summer preview — the running game in a local web page, so an agent's own
+ * browser (Claude Code Desktop's Browser pane, the Codex app's in-app browser)
+ * can see it, screenshot it and check it after every edit.
+ *
+ *   summer preview                 http://127.0.0.1:5199 (next free port if taken)
+ *   summer preview --port 5300     exactly that port (Desktop rewrites this one)
+ *   summer preview --open          also open it in the default browser
+ *
+ * Run it in the folder the agent session works in: the project itself, a
+ * folder inside it, or a folder above it (a repo with the game in game/). The
+ * preview shows that project's editor only, and adds a summer-preview entry to
+ * <that folder>/.claude/launch.json (never changing other entries), which is
+ * where Desktop reads it when the session started there; Desktop then starts
+ * the preview itself and verifies changes with it. --no-launch-json skips that.
+ * The server, the page and the writer live in core/preview/.
+ */
+import { Command } from "commander";
+import { existsSync, readdirSync, realpathSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, parse, relative, resolve, sep } from "node:path";
+import open from "open";
+import { EngineApiClient } from "../../core/api-client.js";
+import { engineSelectionFromEnv } from "../../core/engine.js";
+import { c, sym, tildeify } from "../../core/format.js";
+import { DEFAULT_PREVIEW_PORT, previewLaunchEntry, writeClaudeLaunchConfig, } from "../../core/preview/launch-config.js";
+import { PortInUseError, startPreviewServer } from "../../core/preview/server.js";
+import { findSetupProjectRoot } from "../../project-memory/agent-instructions.js";
+/** --port asks for exactly that port; without it, 5199 or the next free one.
+ *  A PORT variable is not read: shells often export one for a web app, and
+ *  Desktop passes the port it picked in --port. */
+export function resolvePreviewPort(flag) {
+    if (flag === undefined || flag.trim() === "")
+        return { port: DEFAULT_PREVIEW_PORT, strict: false };
+    const port = Number(flag.trim());
+    if (!Number.isInteger(port) || port < 0 || port > 65535) {
+        throw new Error(`--port must be a whole number from 0 through 65535, got "${flag}".`);
+    }
+    return { port, strict: true };
+}
+const SEARCH_DEPTH = 3;
+const SEARCH_MAX_DIRS = 2000;
+/** Folders holding project.godot below `dir`: the shallowest level that has
+ *  any (depth <= 3, no hidden folders or node_modules, at most 2000 read). */
+function projectsBelow(dir) {
+    const found = [];
+    let read = 0;
+    let level = [dir];
+    for (let depth = 1; depth <= SEARCH_DEPTH && level.length > 0 && found.length === 0; depth += 1) {
+        const next = [];
+        for (const parent of level) {
+            if (++read > SEARCH_MAX_DIRS)
+                return found;
+            let names;
+            try {
+                names = readdirSync(parent, { withFileTypes: true })
+                    .filter((entry) => entry.isDirectory() && !entry.name.startsWith(".") && entry.name !== "node_modules")
+                    .map((entry) => entry.name);
+            }
+            catch {
+                continue;
+            }
+            for (const name of names) {
+                const child = join(parent, name);
+                if (existsSync(join(child, "project.godot")))
+                    found.push(child);
+                else
+                    next.push(child);
+            }
+        }
+        level = next;
+    }
+    return found;
+}
+/** The project `summer preview` is for: at or above `cwd` (the same walk as
+ *  `summer setup`), else the one project below it. Several below is an error. */
+export function findPreviewProject(cwd) {
+    const sessionRoot = realpathSync(resolve(cwd));
+    const above = findSetupProjectRoot(sessionRoot);
+    if (above)
+        return { projectRoot: above, sessionRoot };
+    if (sessionRoot === realpathSync(homedir()) || sessionRoot === parse(sessionRoot).root) {
+        return { projectRoot: null, sessionRoot };
+    }
+    const below = projectsBelow(sessionRoot);
+    if (below.length > 1) {
+        throw new Error(`Several Summer projects below ${tildeify(sessionRoot)} (${below.map((dir) => relative(sessionRoot, dir)).join(", ")}). ` +
+            "Run summer preview inside the one to show.");
+    }
+    if (below.length === 0)
+        return { projectRoot: null, sessionRoot };
+    return { projectRoot: below[0], sessionRoot, entryCwd: relative(sessionRoot, below[0]).split(sep).join("/") };
+}
+function launchLine(result, project, skipped) {
+    if (!project.projectRoot) {
+        return `${sym.warn()} No Summer project here, above or below (no project.godot): .claude/launch.json not written.`;
+    }
+    if (skipped)
+        return `${c.dim("·")} .claude/launch.json not written (--no-launch-json).`;
+    if (!result)
+        return `${sym.warn()} .claude/launch.json not written.`;
+    const where = tildeify(result.path);
+    const reader = `Claude Code Desktop reads it when the session's folder is ${tildeify(project.sessionRoot)}`;
+    switch (result.status) {
+        case "created":
+        case "added":
+            return `${sym.ok()} ${result.status === "created" ? "Wrote" : "Added summer-preview to"} ${where}. ${reader}: its Browser pane then starts this preview and checks it after each edit.`;
+        case "kept":
+            return `${sym.ok()} ${where} already has summer-preview${result.autoVerify ? "" : " (auto-verify is off in that file)"}. ${reader}.`;
+        case "skipped":
+            return `${sym.warn()} ${where} left as it is: ${result.reason}. Add this entry to its configurations: ${JSON.stringify(result.entry)}`;
+    }
+}
+/** Start the preview; resolves with the running server (the command keeps it
+ *  open until Ctrl-C). Throws on a bad --port, a taken explicit port, or
+ *  several projects below the folder. */
+export async function runPreview(opts, io) {
+    const { port, strict } = resolvePreviewPort(opts.port);
+    const project = findPreviewProject(io.cwd);
+    // Only this project's editor: never another project's through the global pointer.
+    const selection = engineSelectionFromEnv(io.env) ?? (project.projectRoot ? { projectPath: project.projectRoot } : undefined);
+    let server;
+    try {
+        server = await startPreviewServer({ port, strictPort: strict, connect: () => io.connect(selection), log: io.err });
+    }
+    catch (err) {
+        if (err instanceof PortInUseError) {
+            throw new Error(`Port ${err.port} is in use. Pass another --port (0 picks any free one), or stop what runs there.`);
+        }
+        throw err;
+    }
+    let launch = null;
+    const skipped = opts.launchJson === false;
+    if (project.projectRoot && !skipped) {
+        try {
+            launch = writeClaudeLaunchConfig(project.sessionRoot, { entry: previewLaunchEntry(DEFAULT_PREVIEW_PORT, project.entryCwd) });
+        }
+        catch (err) {
+            io.err(`${sym.warn()} .claude/launch.json not written: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    }
+    if (opts.json) {
+        io.out(JSON.stringify({ ok: true, url: server.url, port: server.port, projectRoot: project.projectRoot, launchJson: launch }));
+    }
+    else {
+        io.out(`${sym.arrow()} ${c.bold("Summer preview")}  ${server.url}`);
+        io.out(`  Shows the running game, or the editor viewport when no game runs${project.projectRoot ? ` (${tildeify(project.projectRoot)})` : ""}. Ctrl-C to stop.`);
+        io.out(`  ${launchLine(launch, project, skipped)}`);
+    }
+    if (opts.open)
+        await io.openUrl(server.url).catch(() => undefined);
+    return server;
+}
+function defaultIo() {
+    return {
+        cwd: process.cwd(),
+        env: process.env,
+        out: (line) => console.log(line),
+        err: (line) => console.error(line),
+        connect: (selection) => EngineApiClient.connect(selection),
+        openUrl: async (url) => {
+            await open(url);
+        },
+    };
+}
+export const previewCommand = new Command("preview")
+    .description("Show the running game (or the editor viewport) in a local web page an agent's browser can see; registers it in .claude/launch.json")
+    .option("--port <n>", `Port to serve on (default ${DEFAULT_PREVIEW_PORT}, or the next free one)`)
+    .option("--no-launch-json", "Do not add the summer-preview entry to .claude/launch.json in this folder")
+    .option("--open", "Also open the page in the default browser")
+    .option("--json", "Print one JSON line with the URL instead of text")
+    .action(async (opts) => {
+    const server = await runPreview(opts, defaultIo());
+    await new Promise((resolve) => {
+        const stop = () => resolve();
+        process.once("SIGINT", stop);
+        process.once("SIGTERM", stop);
+    });
+    await server.close();
+    process.exit(0);
+});

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

@@ -1,19 +1,3 @@
 import { Command } from "commander";
-import { ENGINE_BIN_ENV } from "../../core/engine-install.js";
-export type RunBinaryResolution = {
-    binary: string;
-    source: "--bin" | typeof ENGINE_BIN_ENV | "installed";
-} | {
-    binary: null;
-    error: string;
-};
-/**
- * Which engine executable `summer run` launches (and probes with --help):
- * `--bin <path>`, else SUMMER_BIN, else the installed engine
- * (findEngineBinary, which also honours the older SUMMER_ENGINE_BINARY).
- * An explicit override is never silently swapped for the installed engine:
- * a missing path or a bare `.app` bundle is an error, because the caller
- * asked for THAT build.
- */
-export declare function resolveRunBinary(binFlag: string | undefined, env?: NodeJS.ProcessEnv): RunBinaryResolution;
+export { resolveRunBinary, type RunBinaryResolution } from "../../core/engine-launch.js";
 export declare const runCommand: Command;