summer-engine 2.8.2 → 3.1.0

package/dist/core/headless/registry.d.ts

@@ -0,0 +1,91 @@
+/**
+ * Reader for the headless process registry the engine maintains at
+ * <editor cache dir>/summer_processes.cfg (engine ConfigFile / INI-ish format).
+ *
+ * Shape (contract — mirror of the worker agent's brief):
+ *   [<absolute project path>]        ; section name = project path
+ *   role="worker"
+ *   pid=12345
+ *   port=6600
+ *   token="hex..."
+ *   started_ts=1756700000
+ *
+ * This module only READS the registry. Dead-pid "pruning" is in-memory
+ * filtering — the CLI never rewrites the file, because the engine/worker owns
+ * it and a concurrent rewrite from the CLI could race a worker registering
+ * itself.
+ */
+export declare const REGISTRY_FILENAME = "summer_processes.cfg";
+/** A registry file larger than this is treated as corrupt (empty registry). */
+export declare const MAX_REGISTRY_BYTES: number;
+export interface WorkerRegistryEntry {
+    /** Canonical absolute project path (the section name, resolved). */
+    projectPath: string;
+    role: string;
+    pid: number;
+    port: number;
+    token: string;
+    startedTs?: number;
+}
+export interface ReadRegistryOptions {
+    /** Full path to summer_processes.cfg. Overrides cacheDir. */
+    registryPath?: string;
+    /** Editor cache dir containing the registry file. */
+    cacheDir?: string;
+    /** Liveness probe, injectable for tests. Defaults to kill(pid, 0). */
+    isAlive?: (pid: number) => boolean;
+}
+/**
+ * Canonicalize a project path for registry-section matching:
+ *   - resolve to absolute, then REALPATH it — the engine canonicalizes the
+ *     section paths it writes (macOS: /var is a symlink to /private/var), so
+ *     a resolve()-only lookup of a symlinked path would never match the
+ *     engine-written section and spawn would time out with the worker alive.
+ *     Non-existent paths fall back to the resolved form.
+ *   - strip trailing separators
+ *   - on Windows: normalize backslashes to forward slashes and lowercase
+ *     (NTFS is case-insensitive; the engine may write either casing)
+ * `platformName` is injectable so the Windows rules are unit-testable
+ * anywhere. Used consistently for registry lookups AND single-flight keys.
+ */
+export declare function normalizeProjectPath(path: string, platformName?: NodeJS.Platform): string;
+import { processIsAlive } from "../util/process.js";
+export { processIsAlive };
+/**
+ * Resolve the editor cache dir that holds summer_processes.cfg.
+ *
+ * The engine derives it from OS::get_cache_path() + get_godot_dir_name():
+ *   macOS   ~/Library/Caches/<Name>        (platform/macos/os_macos.mm:503,561)
+ *   Windows %LOCALAPPDATA%/<Name>          (platform/windows/os_windows.cpp:2688)
+ *   Linux   $XDG_CACHE_HOME|~/.cache/<name> (platform/linuxbsd/os_linuxbsd.cpp:957)
+ * <Name> is version.py short_name — "Summer" in shipped Summer builds
+ * (verified: ~/Library/Caches/Summer holds editor_doc_cache/resthumb files),
+ * the upstream name in unrebranded dev builds. We probe the Summer name first
+ * and fall back to the upstream name only when the registry file actually
+ * exists there.
+ *
+ * SUMMER_CACHE_DIR overrides everything (useful for tests and nonstandard
+ * installs).
+ */
+export declare function resolveEditorCacheDir(env?: NodeJS.ProcessEnv): string;
+export declare function registryPathFor(options?: ReadRegistryOptions): string;
+/**
+ * Parse the registry's ConfigFile text into raw sections. Exported for tests.
+ * Tolerant: comments (; or #), blank lines, quoted or bare section names,
+ * `key=value` with or without spaces. Malformed lines are skipped — one bad
+ * section must not hide live workers.
+ */
+export declare function parseRegistryText(text: string): Array<{
+    section: string;
+    values: Record<string, string>;
+}>;
+/**
+ * Read the registry and return LIVE entries only (dead-pid sections are
+ * pruned from the result; the file itself is never rewritten). A missing or
+ * unreadable registry yields [] — same meaning as "no workers".
+ */
+export declare function readProcessRegistry(options?: ReadRegistryOptions): Promise<WorkerRegistryEntry[]>;
+/** Find the live worker entry for a project (normalized path match — see
+ *  normalizeProjectPath: trailing slashes stripped; on Windows additionally
+ *  case-insensitive with separators normalized). */
+export declare function findWorkerEntry(projectPath: string, options?: ReadRegistryOptions): Promise<WorkerRegistryEntry | null>;

package/dist/core/headless/registry.js

@@ -0,0 +1,226 @@
+import { lstat, readFile } from "fs/promises";
+import { existsSync, realpathSync } from "fs";
+import { homedir } from "os";
+import { join, resolve } from "path";
+/**
+ * Reader for the headless process registry the engine maintains at
+ * <editor cache dir>/summer_processes.cfg (engine ConfigFile / INI-ish format).
+ *
+ * Shape (contract — mirror of the worker agent's brief):
+ *   [<absolute project path>]        ; section name = project path
+ *   role="worker"
+ *   pid=12345
+ *   port=6600
+ *   token="hex..."
+ *   started_ts=1756700000
+ *
+ * This module only READS the registry. Dead-pid "pruning" is in-memory
+ * filtering — the CLI never rewrites the file, because the engine/worker owns
+ * it and a concurrent rewrite from the CLI could race a worker registering
+ * itself.
+ */
+export const REGISTRY_FILENAME = "summer_processes.cfg";
+/** A registry file larger than this is treated as corrupt (empty registry). */
+export const MAX_REGISTRY_BYTES = 512 * 1024;
+/**
+ * Canonicalize a project path for registry-section matching:
+ *   - resolve to absolute, then REALPATH it — the engine canonicalizes the
+ *     section paths it writes (macOS: /var is a symlink to /private/var), so
+ *     a resolve()-only lookup of a symlinked path would never match the
+ *     engine-written section and spawn would time out with the worker alive.
+ *     Non-existent paths fall back to the resolved form.
+ *   - strip trailing separators
+ *   - on Windows: normalize backslashes to forward slashes and lowercase
+ *     (NTFS is case-insensitive; the engine may write either casing)
+ * `platformName` is injectable so the Windows rules are unit-testable
+ * anywhere. Used consistently for registry lookups AND single-flight keys.
+ */
+export function normalizeProjectPath(path, platformName = process.platform) {
+    let normalized = resolve(path.trim());
+    try {
+        normalized = realpathSync(normalized);
+    }
+    catch {
+        // Path does not exist (yet) — keep the resolved form.
+    }
+    if (platformName === "win32") {
+        normalized = normalized.replace(/\\/g, "/").toLowerCase();
+    }
+    while (normalized.length > 1 && normalized.endsWith("/")) {
+        normalized = normalized.slice(0, -1);
+    }
+    return normalized;
+}
+import { processIsAlive } from "../util/process.js";
+export { processIsAlive };
+/**
+ * Resolve the editor cache dir that holds summer_processes.cfg.
+ *
+ * The engine derives it from OS::get_cache_path() + get_godot_dir_name():
+ *   macOS   ~/Library/Caches/<Name>        (platform/macos/os_macos.mm:503,561)
+ *   Windows %LOCALAPPDATA%/<Name>          (platform/windows/os_windows.cpp:2688)
+ *   Linux   $XDG_CACHE_HOME|~/.cache/<name> (platform/linuxbsd/os_linuxbsd.cpp:957)
+ * <Name> is version.py short_name — "Summer" in shipped Summer builds
+ * (verified: ~/Library/Caches/Summer holds editor_doc_cache/resthumb files),
+ * the upstream name in unrebranded dev builds. We probe the Summer name first
+ * and fall back to the upstream name only when the registry file actually
+ * exists there.
+ *
+ * SUMMER_CACHE_DIR overrides everything (useful for tests and nonstandard
+ * installs).
+ */
+export function resolveEditorCacheDir(env = process.env) {
+    const override = env.SUMMER_CACHE_DIR?.trim();
+    if (override)
+        return override;
+    const home = homedir();
+    let base;
+    let names;
+    switch (process.platform) {
+        case "darwin":
+            base = join(home, "Library", "Caches");
+            names = ["Summer", "Godot"];
+            break;
+        case "win32":
+            base = env.LOCALAPPDATA?.trim() || join(home, "AppData", "Local");
+            names = ["Summer", "Godot"];
+            break;
+        default: {
+            const xdg = env.XDG_CACHE_HOME?.trim();
+            base = xdg && xdg.startsWith("/") ? xdg : join(home, ".cache");
+            names = ["summer", "godot"];
+            break;
+        }
+    }
+    for (const name of names) {
+        if (existsSync(join(base, name, REGISTRY_FILENAME)))
+            return join(base, name);
+    }
+    // Default to the Summer-branded dir even when the registry does not exist
+    // yet — a spawned worker will create the file there.
+    return join(base, names[0]);
+}
+export function registryPathFor(options = {}) {
+    if (options.registryPath)
+        return options.registryPath;
+    return join(options.cacheDir ?? resolveEditorCacheDir(), REGISTRY_FILENAME);
+}
+function unquote(raw) {
+    const trimmed = raw.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith('"') && trimmed.endsWith('"')) {
+        // The registry's string escapes are a JSON subset for the values we
+        // care about (paths, roles, hex tokens). Fall back to a bare strip when
+        // JSON.parse rejects an exotic escape.
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (typeof parsed === "string")
+                return parsed;
+        }
+        catch {
+            /* fall through */
+        }
+        return trimmed.slice(1, -1);
+    }
+    return trimmed;
+}
+function numberValue(raw) {
+    const value = Number(unquote(raw));
+    return Number.isFinite(value) ? value : undefined;
+}
+/**
+ * Parse the registry's ConfigFile text into raw sections. Exported for tests.
+ * Tolerant: comments (; or #), blank lines, quoted or bare section names,
+ * `key=value` with or without spaces. Malformed lines are skipped — one bad
+ * section must not hide live workers.
+ */
+export function parseRegistryText(text) {
+    const sections = [];
+    let current = null;
+    for (const rawLine of text.split(/\r?\n/)) {
+        const line = rawLine.trim();
+        if (!line || line.startsWith(";") || line.startsWith("#"))
+            continue;
+        if (line.startsWith("[") && line.endsWith("]")) {
+            // Godot's ConfigFile writes a section name as "[" + name.replace("]",
+            // "\\]") + "]", so a project path containing "]" arrives escaped and
+            // would otherwise never match the caller's normalized path.
+            const name = unquote(line.slice(1, -1).replace(/\\\]/g, "]"));
+            current = { section: name, values: {} };
+            sections.push(current);
+            continue;
+        }
+        if (!current)
+            continue;
+        const eq = line.indexOf("=");
+        if (eq <= 0)
+            continue;
+        const key = line.slice(0, eq).trim();
+        const value = line.slice(eq + 1).trim();
+        if (key)
+            current.values[key] = value;
+    }
+    return sections;
+}
+/**
+ * Read the registry and return LIVE entries only (dead-pid sections are
+ * pruned from the result; the file itself is never rewritten). A missing or
+ * unreadable registry yields [] — same meaning as "no workers".
+ */
+export async function readProcessRegistry(options = {}) {
+    const path = registryPathFor(options);
+    const isAlive = options.isAlive ?? processIsAlive;
+    let text;
+    try {
+        // Trust boundary: only a REGULAR file is accepted — a symlink planted at
+        // the registry path (pointing at attacker-chosen content) is refused, as
+        // is an implausibly large file. lstat does not follow symlinks.
+        const info = await lstat(path);
+        if (!info.isFile() ||
+            info.isSymbolicLink() ||
+            info.size > MAX_REGISTRY_BYTES) {
+            return [];
+        }
+        text = await readFile(path, "utf-8");
+    }
+    catch {
+        return [];
+    }
+    const entries = [];
+    for (const { section, values } of parseRegistryText(text)) {
+        const pid = numberValue(values.pid ?? "");
+        const port = numberValue(values.port ?? "");
+        const token = values.token !== undefined ? unquote(values.token) : "";
+        const role = values.role !== undefined ? unquote(values.role) : "";
+        if (!section ||
+            !pid ||
+            !Number.isInteger(pid) ||
+            pid <= 0 ||
+            !port ||
+            !Number.isInteger(port) ||
+            port < 1 ||
+            port > 65535 ||
+            !token) {
+            continue;
+        }
+        if (!isAlive(pid))
+            continue;
+        entries.push({
+            projectPath: resolve(section),
+            role,
+            pid,
+            port,
+            token,
+            startedTs: numberValue(values.started_ts ?? ""),
+        });
+    }
+    return entries;
+}
+/** Find the live worker entry for a project (normalized path match — see
+ *  normalizeProjectPath: trailing slashes stripped; on Windows additionally
+ *  case-insensitive with separators normalized). */
+export async function findWorkerEntry(projectPath, options = {}) {
+    const target = normalizeProjectPath(projectPath);
+    const entries = await readProcessRegistry(options);
+    return (entries.find((entry) => normalizeProjectPath(entry.projectPath) === target &&
+        entry.role === "worker") ?? null);
+}

package/dist/core/headless/resolve.d.ts

@@ -0,0 +1,46 @@
+import type { ProjectConnection } from "./connection.js";
+import { EditorConnection } from "./editor-connection.js";
+import { type ReadRegistryOptions, type WorkerRegistryEntry } from "./registry.js";
+import { type SpawnWorkerOptions } from "./spawn.js";
+import { WorkerConnection } from "./worker-connection.js";
+/**
+ * resolveProjectConnection — the routing decision, in fixed priority order:
+ *
+ *   1. EDITOR   a live editor that has the project open (today's transport,
+ *               via the existing instance registry in ~/.summer/instances)
+ *   2. WORKER   a live headless worker registered for the project in
+ *               <editor cache dir>/summer_processes.cfg
+ *   3. SPAWN    launch `<engine> --summer-worker --path <project>`, wait for
+ *               its registry entry (up to ~120s), connect to it
+ *
+ * Every step is injectable for tests; the defaults wire the real editor
+ * discovery (core/engine.ts resolveEngineConnection via EngineApiClient),
+ * the real registry reader, and the real spawner.
+ */
+export interface ResolveProjectConnectionOptions {
+    registry?: ReadRegistryOptions;
+    spawn?: Omit<SpawnWorkerOptions, "registry">;
+    onProgress?: (progress: {
+        phase: string;
+        elapsedMs?: number;
+    }) => void;
+    /** Test seams. Defaults are the real implementations. */
+    deps?: {
+        tryEditor?: (projectPath: string) => Promise<EditorConnection>;
+        findWorker?: (projectPath: string, registry?: ReadRegistryOptions) => Promise<WorkerRegistryEntry | null>;
+        spawnWorker?: (projectPath: string, options?: SpawnWorkerOptions) => Promise<WorkerRegistryEntry>;
+        connectWorker?: (entry: WorkerRegistryEntry, projectPath: string) => Promise<WorkerConnection>;
+    };
+}
+/**
+ * Classify an editor-resolution failure. Routing may fall through to a
+ * worker ONLY when the failure positively means "no live editor has this
+ * project" (core/engine.ts: no registry match, or legacy no-api-token).
+ * Everything else — ambiguity ("more than one editor matches"), identity
+ * changes, an editor that exists but is not responding, auth failures, a
+ * path that is not a project — means the editor's presence is UNCERTAIN, and
+ * a worker must never write while that is true. Those errors RETHROW.
+ * Exported for tests and for mcp-routing.
+ */
+export declare function isNoEditorForProjectError(error: unknown): boolean;
+export declare function resolveProjectConnection(projectPath: string, options?: ResolveProjectConnectionOptions): Promise<ProjectConnection>;

package/dist/core/headless/resolve.js

@@ -0,0 +1,75 @@
+import { resolve as resolvePath } from "path";
+import { EngineApiClient } from "../api-client.js";
+import { EditorConnection } from "./editor-connection.js";
+import { findWorkerEntry, } from "./registry.js";
+import { spawnWorker } from "./spawn.js";
+import { WorkerConnection } from "./worker-connection.js";
+async function defaultTryEditor(projectPath) {
+    // resolveEngineConnection (inside connect) throws when no live editor
+    // matches this exact project — ONLY that failure class is the signal to
+    // fall through to the worker path (see isNoEditorForProjectError).
+    const client = await EngineApiClient.connect({ projectPath });
+    return new EditorConnection(client, projectPath);
+}
+/**
+ * Classify an editor-resolution failure. Routing may fall through to a
+ * worker ONLY when the failure positively means "no live editor has this
+ * project" (core/engine.ts: no registry match, or legacy no-api-token).
+ * Everything else — ambiguity ("more than one editor matches"), identity
+ * changes, an editor that exists but is not responding, auth failures, a
+ * path that is not a project — means the editor's presence is UNCERTAIN, and
+ * a worker must never write while that is true. Those errors RETHROW.
+ * Exported for tests and for mcp-routing.
+ */
+export function isNoEditorForProjectError(error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return (message.includes("No running Summer editor matches") ||
+        message.includes("no api-token found"));
+}
+function defaultConnectWorker(entry, projectPath) {
+    return WorkerConnection.connect({
+        port: entry.port,
+        token: entry.token,
+        pid: entry.pid,
+        projectPath,
+    });
+}
+export async function resolveProjectConnection(projectPath, options = {}) {
+    const target = resolvePath(projectPath);
+    const tryEditor = options.deps?.tryEditor ?? defaultTryEditor;
+    const findWorker = options.deps?.findWorker ?? findWorkerEntry;
+    const doSpawn = options.deps?.spawnWorker ?? spawnWorker;
+    const connectWorker = options.deps?.connectWorker ?? defaultConnectWorker;
+    // 1. Editor beats worker. ONLY a positive "no editor has this project"
+    // falls through — ambiguity/identity/auth/unresponsive-editor errors
+    // rethrow, because a worker must never write while an editor's presence is
+    // uncertain.
+    try {
+        return await tryEditor(target);
+    }
+    catch (error) {
+        if (!isNoEditorForProjectError(error))
+            throw error;
+    }
+    // 2. Live worker from the registry. A stale entry whose process answers the
+    // pid probe but whose socket/handshake is gone falls through to spawn —
+    // and spawnWorker snapshots it as a baseline so the stale entry can never
+    // satisfy the post-spawn poll.
+    const existing = await findWorker(target, options.registry);
+    if (existing) {
+        try {
+            return await connectWorker(existing, target);
+        }
+        catch {
+            options.onProgress?.({ phase: "registry_worker_unreachable" });
+        }
+    }
+    // 3. Spawn on demand, then connect.
+    options.onProgress?.({ phase: "spawning_worker" });
+    const entry = await doSpawn(target, {
+        ...options.spawn,
+        registry: options.registry,
+        onProgress: options.onProgress,
+    });
+    return connectWorker(entry, target);
+}

package/dist/core/headless/spawn.d.ts

@@ -0,0 +1,46 @@
+import { type ReadRegistryOptions, type WorkerRegistryEntry } from "./registry.js";
+export declare function findEngineBinary(env?: NodeJS.ProcessEnv): string | null;
+/** What a launcher must report back so the poll loop can fail fast when the
+ *  worker dies before registering. The default launcher wires a real child
+ *  process; tests inject fakes. */
+export interface LaunchHandle {
+    /** Non-null once the child has exited. */
+    exit(): {
+        code: number | null;
+        signal: NodeJS.Signals | null;
+    } | null;
+    /** Last bytes of the child's stderr (best-effort, may be ""). MUST never
+     *  contain the registry token — workers own their own log hygiene, but
+     *  this layer additionally never logs tokens itself. */
+    stderrTail(): string;
+    /** Terminate the child (SIGTERM, escalating to SIGKILL after a grace
+     *  period). Called whenever the spawn attempt is ABANDONED without
+     *  adopting a registry entry — an unadopted worker must never be leaked.
+     *  Optional so test fakes without a real process can omit it. */
+    kill?(): void;
+}
+export type Launcher = (binary: string, args: string[]) => LaunchHandle;
+export interface SpawnWorkerOptions {
+    /** Explicit engine binary; defaults to findEngineBinary(). */
+    binary?: string;
+    /** Registry read options (test injection: registryPath / isAlive). */
+    registry?: ReadRegistryOptions;
+    /** Registration budget. Default SUMMER_WORKER_SPAWN_TIMEOUT_MS or 120s
+     *  (first imports of large projects are slow). */
+    timeoutMs?: number;
+    pollIntervalMs?: number;
+    /** Elapsed-time progress while waiting for the worker to register. */
+    onProgress?: (progress: {
+        phase: string;
+        elapsedMs: number;
+    }) => void;
+    /** Process launcher, injectable for tests. */
+    launch?: Launcher;
+}
+/**
+ * Spawn a headless worker for `projectPath` and wait for its registry entry.
+ * Resolves with the live entry; rejects on missing binary, early exit
+ * (surfacing the exit code and a stderr tail), or registration timeout.
+ * Concurrent calls for the same project share ONE spawn.
+ */
+export declare function spawnWorker(projectPath: string, options?: SpawnWorkerOptions): Promise<WorkerRegistryEntry>;