summer-engine 4.3.0 → 4.6.0

package/dist/cli/commands/ops.js

@@ -1,10 +1,11 @@
 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";
@@ -113,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)."];
@@ -135,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 });
     }
@@ -196,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":
@@ -294,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;

package/dist/cli/commands/run.js

@@ -1,110 +1,12 @@
 import { Command } from "commander";
-import { spawn } from "child_process";
 import { existsSync } from "fs";
-import { mkdir, readFile, rm, writeFile } from "fs/promises";
 import { join, resolve } from "path";
-import { getSummerDir } from "../../core/auth.js";
-import { getApiPort, checkEngineHealth } from "../../core/engine.js";
-import { describeEngineExecutableProblem, ENGINE_BIN_ENV, engineBinaryOverride, findEngineBinary, } from "../../core/engine-install.js";
-import { advertisedBackgroundPosture, backgroundLaunchSupport, detectBackgroundLaunchSupport, planLaunch, resolveLaunchPosture, BACKGROUND_LAUNCH_FLAG, BACKGROUND_LAUNCH_MIN_ENGINE_VERSION, } from "../../core/launch-posture.js";
-import { sleep } from "../../core/util/sleep.js";
-const LAUNCH_LOCK_STALE_MS = 60_000;
-const LAUNCH_LOCK_WAIT_MS = 15_000;
-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);
-        }
-    }
-}
-/**
- * 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 function resolveRunBinary(binFlag, env = process.env) {
-    const fromEnv = engineBinaryOverride(env);
-    const explicit = binFlag?.trim()
-        ? { source: "--bin", path: binFlag.trim() }
-        : fromEnv?.name === ENGINE_BIN_ENV
-            ? { source: ENGINE_BIN_ENV, path: fromEnv.path }
-            : null;
-    if (explicit) {
-        const path = resolve(explicit.path);
-        const problem = describeEngineExecutableProblem(path, explicit.source);
-        return problem ? { binary: null, error: problem } : { binary: path, source: explicit.source };
-    }
-    const installed = findEngineBinary();
-    if (!installed) {
-        return {
-            binary: null,
-            error: "Summer Engine not found. Install it first:\n" +
-                "  summer install\n" +
-                "  or download from https://summerengine.com/download\n" +
-                `To launch a build that is not installed, pass --bin <executable> or set ${ENGINE_BIN_ENV}.`,
-        };
-    }
-    return { binary: installed, source: "installed" };
-}
+import { launchEditor } from "../../core/engine-launch.js";
+import { ENGINE_BIN_ENV } from "../../core/engine-install.js";
+import { resolveLaunchPosture } from "../../core/launch-posture.js";
+// The launch itself (lock, already-open check, posture flags, health wait)
+// lives in core/engine-launch.ts, shared with `summer dev` and the MCP.
+export { resolveRunBinary } from "../../core/engine-launch.js";
 export const runCommand = new Command("run")
     .description("Launch Summer Engine with a project. Without a path it launches a bare " +
     "detached editor (project manager), which requires --no-project.")
@@ -148,108 +50,17 @@ export const runCommand = new Command("run")
             process.exit(1);
         }
     }
-    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;
-        }
-        const resolved = resolveRunBinary(opts.bin);
-        if (resolved.binary === null) {
-            console.error(resolved.error);
-            process.exitCode = 1;
-            return;
-        }
-        const binary = resolved.binary;
-        if (resolved.source !== "installed") {
-            console.log(`Using engine from ${resolved.source}: ${binary}`);
-        }
-        // The engine is not running yet, so /api/health cannot tell us whether
-        // it honours --summer-background. Ask THAT binary itself (`--help`, which
-        // exits headless before any window exists; cached per install) with the
-        // installed version as pre-check and fallback; pass the flag only when
-        // the engine is known to support it. Focus launches have nothing to decide.
-        const support = posture === "background" ? await detectBackgroundLaunchSupport(binary) : backgroundLaunchSupport(null);
-        const plan = planLaunch(posture, support);
-        const args = ["--editor", ...plan.extraArgs];
-        if (fullProjectPath) {
-            args.unshift("--path", fullProjectPath);
-        }
-        if (plan.note)
-            console.log(plan.note);
-        console.log(plan.background
-            ? "Launching Summer Engine in the background (the window will not take focus until you click it)..."
-            : "Launching Summer Engine...");
-        // Direct executable, never `open -a`: LaunchServices activates whatever
-        // it opens and would defeat --summer-background regardless of flags.
-        const child = spawn(binary, args, { detached: true, stdio: "ignore" });
-        // A stale or non-executable binary surfaces as an async "error" event
-        // (ENOENT/EACCES). Without a listener Node raises it as an uncaught
-        // exception with a raw stack; catch it and report the path instead.
-        const spawnState = { error: null };
-        child.on("error", (error) => {
-            spawnState.error = error;
-        });
-        child.unref();
-        // Wait for engine to start responding
-        const startTime = Date.now();
-        const timeout = 20000;
-        while (Date.now() - startTime < timeout) {
-            await sleep(500);
-            if (spawnState.error) {
-                reportSpawnFailure(spawnState.error, binary);
-                return;
-            }
-            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}`);
-                }
-                // Background was wanted but the flag was withheld, and the running
-                // engine now says (capabilities.launchPostures, else its version)
-                // that it would have honoured it: say so, so the next launch can be
-                // fixed rather than silently repeating a focus launch.
-                if (posture === "background" && !plan.background) {
-                    const advert = advertisedBackgroundPosture(h.capabilities);
-                    const wouldHonour = advert ?? backgroundLaunchSupport(h.version).supported;
-                    if (wouldHonour) {
-                        console.log(`  Note: this engine (v${h.version}) ${advert ? "advertises" : "should support"} background launches (${BACKGROUND_LAUNCH_FLAG}, ${BACKGROUND_LAUNCH_MIN_ENGINE_VERSION}+), but that could not be confirmed before launch on this platform.`);
-                    }
-                }
-                return;
-            }
-        }
-        if (spawnState.error) {
-            reportSpawnFailure(spawnState.error, binary);
-            return;
-        }
+    const result = await launchEditor({
+        projectPath: fullProjectPath,
+        posture,
+        bin: opts.bin,
+        out: { log: (line) => console.log(line), error: (line) => console.error(line) },
+    });
+    if (result.status === "starting") {
         console.log("Summer Engine launched but API not responding yet.\n" +
             "It may still be loading. Run 'summer status' to check.");
-    });
+    }
+    else if (result.status !== "running") {
+        process.exitCode = 1;
+    }
 });
-function reportSpawnFailure(error, binary) {
-    const code = error.code ?? error.message;
-    console.error(`Summer Engine binary failed to start: ${code} (${binary})\n` +
-        "Re-run 'summer install' to repair the installation, or check the binary path.");
-    process.exitCode = 1;
-}