summer-engine 2.3.0 → 2.5.0

package/dist/lib/async-op-lifecycle.js

@@ -0,0 +1,83 @@
+/**
+ * 0.5.34 Block E — async tool-lifecycle consumer for the CLI/MCP.
+ *
+ * Ported from the web orchestrator (publicsummerengine
+ * src/lib/bridge/async-op-lifecycle.ts) so the CLI speaks the SAME contract as
+ * the engine's responsive tool server (Block E):
+ *   - NEW path: `202 {requestId, status:"queued"}` -> long-poll
+ *     GET /api/ops/result?requestId=&wait=ms until terminal (done|failed|canceled).
+ *   - LEGACY path (dormant/older engine): a synchronous `200` with the full apply
+ *     result, exactly as before.
+ *
+ * It inspects the RESPONSE (status/body), not a flag, so it stays compatible with
+ * both an async and a synchronous engine. Pure + dependency-injected (now/sleep/
+ * pollOnce) so it is unit-tested without HTTP.
+ */
+const TERMINAL_STATUSES = new Set(["done", "failed", "canceled"]);
+export function isTerminalStatus(status) {
+    return status != null && TERMINAL_STATUSES.has(status);
+}
+/**
+ * Decide whether a POST /api/ops (or GET /api/snapshot/*) response is the new
+ * async ack (`202`) or the legacy synchronous result (`200`). Inspecting the HTTP
+ * status (not a flag) is what keeps this compatible with both engines.
+ */
+export function classifyOpsResponse(httpStatus, body) {
+    const b = (body ?? {});
+    const looksQueued = b.accepted === true && b.status === "queued" && typeof b.requestId === "string";
+    if (httpStatus === 202 || looksQueued) {
+        return { mode: "queued", requestId: String(b.requestId ?? "") };
+    }
+    return { mode: "legacy", legacyResult: body };
+}
+const TIMED_OUT_RESULT = {
+    status: "error",
+    error: "Tool timeout - Summer Engine may be unresponsive",
+    terminalState: "timed_out",
+    errorClass: "transient",
+};
+/**
+ * Drive an async op to a terminal result by polling. `pollOnce(waitMs)` performs
+ * one GET /api/ops/result (long-poll up to waitMs). Returns the engine's apply
+ * dict with terminalState/errorClass/appliedSeq merged on top, or a synthetic
+ * `timed_out` result if the budget is exhausted.
+ */
+export async function pollOpToTerminal(pollOnce, opts) {
+    const now = opts.now ?? (() => Date.now());
+    const sleep = opts.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const pollWaitMs = opts.pollWaitMs ?? 5000;
+    const pacingMs = opts.pacingMs ?? 250;
+    const noProgressMs = opts.noProgressTimeoutMs ?? opts.totalTimeoutMs;
+    const start = now();
+    let lastAdvanceAt = start;
+    let lastStatus;
+    let lastSeq = -1;
+    let lastProgress = "";
+    for (;;) {
+        const env = await pollOnce(pollWaitMs);
+        if (isTerminalStatus(env.status)) {
+            const out = { ...(env.result ?? {}) };
+            if (env.terminalState)
+                out.terminalState = env.terminalState;
+            if (env.errorClass)
+                out.errorClass = env.errorClass;
+            if (env.appliedSeq != null)
+                out.appliedSeq = env.appliedSeq;
+            return out;
+        }
+        const progressJson = env.progress != null ? JSON.stringify(env.progress) : "";
+        const seq = env.appliedSeq ?? -1;
+        const advanced = env.status !== lastStatus || seq !== lastSeq || progressJson !== lastProgress;
+        const t = now();
+        if (advanced) {
+            lastAdvanceAt = t;
+            lastStatus = env.status;
+            lastSeq = seq;
+            lastProgress = progressJson;
+        }
+        if (t - start >= opts.totalTimeoutMs || t - lastAdvanceAt >= noProgressMs) {
+            return { ...TIMED_OUT_RESULT };
+        }
+        await sleep(pacingMs);
+    }
+}

package/dist/lib/project-memory.d.ts

@@ -0,0 +1,33 @@
+export interface ProjectMemoryFileSummary {
+    path: string;
+    kind: string;
+    title: string | null;
+    modifiedTime: string;
+    bytes: number;
+    locked: boolean;
+}
+export interface ProjectMemorySummary {
+    present: boolean;
+    root: ".summer";
+    reason?: string;
+    canonical: {
+        gameSoul: ProjectMemoryFileSummary | null;
+        artBible: ProjectMemoryFileSummary | null;
+        audioBible: ProjectMemoryFileSummary | null;
+        buildPlan: ProjectMemoryFileSummary | null;
+        legacyVoiceCast: ProjectMemoryFileSummary | null;
+    };
+    structured: {
+        present: boolean;
+        indexPresent: boolean;
+        fileCount: number;
+        lockedCount: number;
+        files: ProjectMemoryFileSummary[];
+        truncated: boolean;
+    };
+    files: ProjectMemoryFileSummary[];
+    guidance: string;
+}
+export declare function getProjectMemorySummary(projectPath: string | null | undefined, options?: {
+    maxFiles?: number;
+}): ProjectMemorySummary;

package/dist/lib/project-memory.js

@@ -0,0 +1,220 @@
+import { closeSync, existsSync, openSync, readSync, readdirSync, statSync, } from "node:fs";
+import { join, relative, sep } from "node:path";
+const CANONICAL_FILES = [
+    { key: "gameSoul", relativePath: ".summer/GameSoul.md", kind: "brief" },
+    { key: "artBible", relativePath: ".summer/art-bible.md", kind: "art" },
+    { key: "audioBible", relativePath: ".summer/audio-bible.md", kind: "audio" },
+    { key: "buildPlan", relativePath: ".summer/build-plan.md", kind: "build-plan" },
+    { key: "legacyVoiceCast", relativePath: ".summer/voice-cast.md", kind: "legacy-casting" },
+];
+const SKIPPED_DIRS = new Set(["skills", "local"]);
+const DEFAULT_MAX_FILES = 30;
+const MAX_TITLE_BYTES = 16_384;
+export function getProjectMemorySummary(projectPath, options = {}) {
+    const maxFiles = options.maxFiles ?? DEFAULT_MAX_FILES;
+    const empty = createEmptySummary();
+    if (!projectPath) {
+        return {
+            ...empty,
+            reason: "Project path is not available from the running engine.",
+        };
+    }
+    const summerDir = join(projectPath, ".summer");
+    if (!existsSync(summerDir)) {
+        return {
+            ...empty,
+            reason: "No .summer directory found yet.",
+        };
+    }
+    const canonical = createCanonicalSummary(projectPath);
+    const allFiles = scanMarkdownFiles(projectPath, summerDir, maxFiles);
+    const memoryDir = join(projectPath, ".summer", "memory");
+    const structuredFiles = existsSync(memoryDir)
+        ? scanMarkdownFiles(projectPath, memoryDir, maxFiles)
+        : [];
+    const indexPath = join(projectPath, ".summer", "memory", "index.json");
+    return {
+        present: true,
+        root: ".summer",
+        canonical,
+        structured: {
+            present: existsSync(memoryDir),
+            indexPresent: existsSync(indexPath),
+            fileCount: Math.min(structuredFiles.length, maxFiles),
+            lockedCount: structuredFiles.filter((file) => file.locked).length,
+            files: structuredFiles.slice(0, maxFiles),
+            truncated: structuredFiles.length > maxFiles,
+        },
+        files: allFiles.slice(0, maxFiles),
+        guidance: "Read relevant .summer Markdown before creative, audio, dialogue, level, or character work. Ask before writing .summer files. Changing priority: locked memory requires explicit user confirmation.",
+    };
+}
+function createEmptySummary() {
+    return {
+        present: false,
+        root: ".summer",
+        canonical: {
+            gameSoul: null,
+            artBible: null,
+            audioBible: null,
+            buildPlan: null,
+            legacyVoiceCast: null,
+        },
+        structured: {
+            present: false,
+            indexPresent: false,
+            fileCount: 0,
+            lockedCount: 0,
+            files: [],
+            truncated: false,
+        },
+        files: [],
+        guidance: "Create .summer/GameSoul.md for the project brief. Use .summer/memory/ for locked facts such as character voice IDs, world canon, and provider bindings.",
+    };
+}
+function createCanonicalSummary(projectPath) {
+    const canonical = createEmptySummary().canonical;
+    for (const spec of CANONICAL_FILES) {
+        const absolutePath = join(projectPath, ...spec.relativePath.split("/"));
+        canonical[spec.key] = summarizeFile(projectPath, absolutePath, spec.kind);
+    }
+    return canonical;
+}
+function scanMarkdownFiles(projectPath, startDir, maxFiles) {
+    const files = [];
+    walkSummerDir(projectPath, startDir, startDir, files, maxFiles + 1, 0);
+    return files;
+}
+function walkSummerDir(projectPath, summerDir, currentDir, files, maxFiles, depth) {
+    if (files.length >= maxFiles || depth > 5)
+        return;
+    let entries;
+    try {
+        entries = readdirSync(currentDir).sort();
+    }
+    catch {
+        return;
+    }
+    for (const entry of entries) {
+        if (files.length >= maxFiles)
+            return;
+        const absolutePath = join(currentDir, entry);
+        let stat;
+        try {
+            stat = statSync(absolutePath);
+        }
+        catch {
+            continue;
+        }
+        if (stat.isDirectory()) {
+            const relativeToSummer = relative(summerDir, absolutePath);
+            if (depth === 0 && SKIPPED_DIRS.has(relativeToSummer))
+                continue;
+            walkSummerDir(projectPath, summerDir, absolutePath, files, maxFiles, depth + 1);
+            continue;
+        }
+        if (!stat.isFile() || !entry.endsWith(".md"))
+            continue;
+        const summary = summarizeFile(projectPath, absolutePath, kindForPath(projectPath, absolutePath));
+        if (summary)
+            files.push(summary);
+    }
+}
+function summarizeFile(projectPath, absolutePath, kind) {
+    if (!existsSync(absolutePath))
+        return null;
+    let stat;
+    try {
+        stat = statSync(absolutePath);
+    }
+    catch {
+        return null;
+    }
+    if (!stat.isFile())
+        return null;
+    const preview = readPreview(absolutePath);
+    return {
+        path: normalizePath(relative(projectPath, absolutePath)),
+        kind,
+        title: extractTitle(preview),
+        modifiedTime: stat.mtime.toISOString(),
+        bytes: stat.size,
+        locked: isLockedMemory(preview),
+    };
+}
+function readPreview(absolutePath) {
+    let fd = null;
+    try {
+        fd = openSync(absolutePath, "r");
+        const buffer = Buffer.alloc(MAX_TITLE_BYTES);
+        const bytesRead = readSync(fd, buffer, 0, MAX_TITLE_BYTES, 0);
+        return buffer.toString("utf-8", 0, bytesRead);
+    }
+    catch {
+        return "";
+    }
+    finally {
+        if (fd !== null) {
+            try {
+                closeSync(fd);
+            }
+            catch {
+                // Best-effort summary only.
+            }
+        }
+    }
+}
+function extractTitle(markdown) {
+    for (const line of markdown.split(/\r?\n/)) {
+        const heading = line.match(/^#\s+(.+?)\s*$/);
+        if (heading)
+            return heading[1];
+    }
+    for (const line of markdown.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (trimmed && trimmed !== "---" && !trimmed.includes(":")) {
+            return trimmed.slice(0, 120);
+        }
+    }
+    return null;
+}
+function isLockedMemory(markdown) {
+    return (/^priority:\s*locked\s*$/im.test(markdown) ||
+        /^stable:\s*true\s*$/im.test(markdown) ||
+        /\|\s*locked\s*\|/i.test(markdown));
+}
+function kindForPath(projectPath, absolutePath) {
+    const path = normalizePath(relative(projectPath, absolutePath));
+    if (path === ".summer/GameSoul.md")
+        return "brief";
+    if (path === ".summer/art-bible.md")
+        return "art";
+    if (path === ".summer/audio-bible.md")
+        return "audio";
+    if (path === ".summer/build-plan.md")
+        return "build-plan";
+    if (path === ".summer/voice-cast.md")
+        return "legacy-casting";
+    if (path.startsWith(".summer/memory/casting/"))
+        return "casting";
+    if (path.startsWith(".summer/memory/characters/"))
+        return "character";
+    if (path.startsWith(".summer/memory/world/"))
+        return "world";
+    if (path.startsWith(".summer/memory/systems/"))
+        return "system";
+    if (path.startsWith(".summer/memory/decisions/"))
+        return "decision";
+    if (path.startsWith(".summer/memory/conflicts/"))
+        return "conflict";
+    if (path.startsWith(".summer/mechanics/"))
+        return "mechanic";
+    if (path.startsWith(".summer/levels/"))
+        return "level";
+    if (path.startsWith(".summer/npcs/"))
+        return "npc";
+    return "note";
+}
+function normalizePath(path) {
+    return path.split(sep).join("/");
+}