summer-engine 2.3.0 → 2.6.0

package/dist/lib/cloud/engine-bridge.js

@@ -0,0 +1,105 @@
+import { createHash } from "crypto";
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { join } from "path";
+import { EngineApiClient } from "../api-client.js";
+import { checkEngineHealth, getApiPort, getApiToken } from "../engine.js";
+/**
+ * Engine coordination (spec 8.6.1 and 8.7). All calls degrade gracefully: an
+ * unreachable engine never blocks a sync; the stability check and conflict
+ * routing cover the gaps.
+ */
+/** sha256 hex of the stable .summer/local/.project_id (mirrors SummerEngineIdentity::project_id_hash). */
+export async function readProjectIdHash(projectRoot) {
+    try {
+        const id = (await readFile(join(projectRoot, ".summer", "local", ".project_id"), "utf8")).trim();
+        if (!id)
+            return null;
+        return createHash("sha256").update(id, "utf8").digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+export async function readProjectPathMarker(projectRoot) {
+    try {
+        const marker = (await readFile(join(projectRoot, ".summer", "local", ".project_path"), "utf8")).trim();
+        return marker || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeProjectPathMarker(projectRoot) {
+    const dir = join(projectRoot, ".summer", "local");
+    await mkdir(dir, { recursive: true });
+    await writeFile(join(dir, ".project_path"), projectRoot, "utf8");
+}
+async function connectForProject(projectRoot) {
+    const projectIdHash = await readProjectIdHash(projectRoot);
+    if (!projectIdHash)
+        return null;
+    try {
+        const port = await getApiPort();
+        const token = await getApiToken();
+        if (!token)
+            return null;
+        const health = await checkEngineHealth(port);
+        if (!health)
+            return null;
+        // A different project's engine instance must never be asked to save or
+        // rescan; the executor rejects mismatches too, but skip the round trip.
+        if (health.projectIdHash && health.projectIdHash !== projectIdHash)
+            return null;
+        return { client: new EngineApiClient(port, token), projectIdHash, scene: health.scene };
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Before hashing (spec 8.6.1): ask the running engine to flush dirty scenes
+ * to disk so the walk hashes what the user actually sees.
+ */
+export async function saveDirtyScenesIfRunning(projectRoot) {
+    const session = await connectForProject(projectRoot);
+    if (!session)
+        return false;
+    try {
+        await session.client.executeOps([{ op: "SaveDirtyScenes" }], { projectIdHash: session.projectIdHash });
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * After apply (spec 8.7): trigger a filesystem rescan and reload the open
+ * scene if the pull replaced it. ScanChanges is the engine-side hook; older
+ * engines without it simply reject the op and the editor's own focus scan
+ * picks the changes up.
+ */
+export async function notifyEngineAfterApply(projectRoot, appliedPaths) {
+    if (!appliedPaths.length)
+        return;
+    const session = await connectForProject(projectRoot);
+    if (!session)
+        return;
+    try {
+        await session.client.executeOps([{ op: "ScanChanges" }], { projectIdHash: session.projectIdHash });
+    }
+    catch {
+        // Engine build without the ScanChanges op; non-fatal.
+    }
+    try {
+        const scene = session.scene;
+        if (scene && scene.startsWith("res://")) {
+            const sceneRel = scene.slice("res://".length);
+            if (appliedPaths.includes(sceneRel)) {
+                await session.client.executeOps([{ op: "OpenScene", path: scene }], { projectIdHash: session.projectIdHash });
+            }
+        }
+    }
+    catch {
+        // Reload is best-effort; the editor reloads from disk on focus.
+    }
+}

package/dist/lib/cloud/hash-cache.d.ts

@@ -0,0 +1,23 @@
+export interface HashCacheEntry {
+    sha256: string;
+    size: number;
+    mtimeNs: string;
+    ctimeNs: string;
+    inode: string;
+}
+export type HashCache = Record<string, HashCacheEntry>;
+export declare function readHashCache(projectRoot: string): Promise<HashCache>;
+export declare function writeHashCache(projectRoot: string, cache: HashCache): Promise<void>;
+export interface StatLike {
+    size: bigint;
+    mtimeNs: bigint;
+    ctimeNs: bigint;
+    ino: bigint;
+}
+/**
+ * Cache hit rule (spec 6.2): rehash when any field differs, and apply Git's
+ * racily-clean rule: any file whose mtime is at or after the sync start time
+ * is rehashed regardless of cache.
+ */
+export declare function cacheHit(entry: HashCacheEntry | undefined, stat: StatLike, syncStartMs: number): boolean;
+export declare function cacheEntryFor(sha256: string, stat: StatLike): HashCacheEntry;

package/dist/lib/cloud/hash-cache.js

@@ -0,0 +1,44 @@
+import { readFile } from "fs/promises";
+import { hashCachePath, writeJsonAtomic } from "./paths.js";
+export async function readHashCache(projectRoot) {
+    try {
+        const parsed = JSON.parse(await readFile(hashCachePath(projectRoot), "utf8"));
+        return parsed && typeof parsed === "object" ? parsed : {};
+    }
+    catch {
+        return {};
+    }
+}
+export async function writeHashCache(projectRoot, cache) {
+    await writeJsonAtomic(hashCachePath(projectRoot), cache);
+}
+/**
+ * Cache hit rule (spec 6.2): rehash when any field differs, and apply Git's
+ * racily-clean rule: any file whose mtime is at or after the sync start time
+ * is rehashed regardless of cache.
+ */
+export function cacheHit(entry, stat, syncStartMs) {
+    if (!entry)
+        return false;
+    if (BigInt(entry.size) !== stat.size)
+        return false;
+    if (entry.mtimeNs !== stat.mtimeNs.toString())
+        return false;
+    if (entry.ctimeNs !== stat.ctimeNs.toString())
+        return false;
+    if (entry.inode !== stat.ino.toString())
+        return false;
+    const mtimeMs = Number(stat.mtimeNs / 1000000n);
+    if (mtimeMs >= syncStartMs)
+        return false;
+    return true;
+}
+export function cacheEntryFor(sha256, stat) {
+    return {
+        sha256,
+        size: Number(stat.size),
+        mtimeNs: stat.mtimeNs.toString(),
+        ctimeNs: stat.ctimeNs.toString(),
+        inode: stat.ino.toString(),
+    };
+}

package/dist/lib/cloud/hash.d.ts

@@ -0,0 +1,10 @@
+import { type TrackedRules } from "./rules.js";
+import type { WalkResult } from "./types.js";
+export interface WalkOptions {
+    /** Sync start time for the racily-clean rule. Defaults to now. */
+    syncStartMs?: number;
+    /** Skip reading/writing hash-cache.json (used by tests). */
+    noCache?: boolean;
+}
+export declare function walkProject(projectRoot: string, options?: WalkOptions): Promise<WalkResult>;
+export type { TrackedRules };

package/dist/lib/cloud/hash.js

@@ -0,0 +1,111 @@
+import { createHash } from "crypto";
+import { open, readdir } from "fs/promises";
+import { join } from "path";
+import { cacheEntryFor, cacheHit, readHashCache, writeHashCache } from "./hash-cache.js";
+import { isHardExcludedDir, isHardExcludedFile, isIgnoredByRules, loadTrackedRules } from "./rules.js";
+import { findPathCollisions, validateCloudPath } from "./validate-path.js";
+export async function walkProject(projectRoot, options = {}) {
+    const rules = await loadTrackedRules(projectRoot);
+    const syncStartMs = options.syncStartMs ?? Date.now();
+    const cache = options.noCache ? {} : await readHashCache(projectRoot);
+    const nextCache = {};
+    const files = {};
+    const fileByHash = new Map();
+    const diskPathByKey = new Map();
+    const statByKey = new Map();
+    const skippedSymlinks = [];
+    const unstablePaths = [];
+    async function walk(dir, relKey) {
+        const entries = await readdir(dir, { withFileTypes: true });
+        const siblingNames = new Set(entries.map((entry) => entry.name.normalize("NFC")));
+        for (const entry of entries) {
+            // Manifest keys are NFC; diskPathByKey keeps the actual byte names for I/O.
+            const nfcName = entry.name.normalize("NFC");
+            const fullPath = join(dir, entry.name);
+            const key = relKey ? `${relKey}/${nfcName}` : nfcName;
+            if (!key || key === "summer-cloud.json")
+                continue;
+            if (entry.isSymbolicLink()) {
+                skippedSymlinks.push(key);
+                continue;
+            }
+            if (entry.isDirectory()) {
+                if (isHardExcludedDir(key, nfcName))
+                    continue;
+                if (isIgnoredByRules(key, true, rules))
+                    continue;
+                await walk(fullPath, key);
+                continue;
+            }
+            if (!entry.isFile())
+                continue;
+            if (isHardExcludedFile(key, nfcName, siblingNames))
+                continue;
+            if (isIgnoredByRules(key, false, rules))
+                continue;
+            const valid = validateCloudPath(key);
+            if (!valid.ok) {
+                throw new Error(`Refusing to sync invalid path ${key}: ${valid.reason}`);
+            }
+            const hashed = await hashStableFile(fullPath, cache[key], syncStartMs);
+            if (!hashed) {
+                unstablePaths.push(key);
+                continue;
+            }
+            files[key] = { sha256: hashed.sha256, size: hashed.size };
+            nextCache[key] = cacheEntryFor(hashed.sha256, hashed.stat);
+            diskPathByKey.set(key, fullPath);
+            statByKey.set(key, {
+                size: hashed.size,
+                mtimeNs: hashed.stat.mtimeNs.toString(),
+                inode: hashed.stat.ino.toString(),
+            });
+            if (!fileByHash.has(hashed.sha256)) {
+                fileByHash.set(hashed.sha256, fullPath);
+            }
+        }
+    }
+    await walk(projectRoot, "");
+    const collisions = findPathCollisions(Object.keys(files));
+    if (collisions.length) {
+        const lines = collisions.map((c) => `${c.a} and ${c.b} (${c.kind})`).join("; ");
+        throw new Error(`On-disk file names collide after normalization and cannot sync: ${lines}. Rename one of each pair.`);
+    }
+    if (!options.noCache) {
+        await writeHashCache(projectRoot, nextCache).catch(() => { });
+    }
+    return { files, fileByHash, diskPathByKey, statByKey, skippedSymlinks, unstablePaths };
+}
+/**
+ * Per-file stability check (spec 8.6.2): fstat the open fd before hashing,
+ * hash, fstat again; on any difference re-read; after 3 attempts return null
+ * so the caller excludes the file from THIS push and carries forward its
+ * previous manifest entry. Never throws for instability.
+ */
+async function hashStableFile(path, cached, syncStartMs) {
+    for (let attempt = 0; attempt < 3; attempt += 1) {
+        const handle = await open(path, "r");
+        try {
+            const before = statLike(await handle.stat({ bigint: true }));
+            if (cacheHit(cached, before, syncStartMs)) {
+                return { sha256: cached.sha256, size: Number(before.size), stat: before };
+            }
+            const bytes = await handle.readFile();
+            const after = statLike(await handle.stat({ bigint: true }));
+            if (before.size === after.size && before.mtimeNs === after.mtimeNs && before.ino === after.ino) {
+                return {
+                    sha256: createHash("sha256").update(bytes).digest("hex"),
+                    size: bytes.length,
+                    stat: after,
+                };
+            }
+        }
+        finally {
+            await handle.close();
+        }
+    }
+    return null;
+}
+function statLike(stat) {
+    return { size: stat.size, mtimeNs: stat.mtimeNs, ctimeNs: stat.ctimeNs, ino: stat.ino };
+}

package/dist/lib/cloud/http.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Blob transport boundary. Production talks to presigned R2 URLs; tests swap
+ * in a double so no test ever needs the network.
+ */
+export interface BlobTransport {
+    /** Streams a GET to a file, hashing as it goes. Returns sha256 hex and size. */
+    getToFile(url: string, destPath: string): Promise<{
+        sha256: string;
+        size: number;
+        status: number;
+    }>;
+    /** PUTs bytes from a file or buffer. Returns the HTTP status. */
+    put(url: string, headers: Record<string, string>, body: Buffer): Promise<number>;
+}
+export declare function getBlobTransport(): BlobTransport;
+export declare function setBlobTransportForTests(transport: BlobTransport | null): void;
+export declare function readFileBytes(path: string): Promise<Buffer>;

package/dist/lib/cloud/http.js

@@ -0,0 +1,47 @@
+import { createHash } from "crypto";
+import { createWriteStream } from "fs";
+import { open, readFile } from "fs/promises";
+import { Readable } from "stream";
+import { pipeline } from "stream/promises";
+const realTransport = {
+    async getToFile(url, destPath) {
+        const res = await fetch(url);
+        if (!res.ok || !res.body) {
+            return { sha256: "", size: 0, status: res.status };
+        }
+        const hash = createHash("sha256");
+        let size = 0;
+        const out = createWriteStream(destPath, { mode: 0o600 });
+        await pipeline(Readable.fromWeb(res.body), async function* (source) {
+            for await (const chunk of source) {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                hash.update(buf);
+                size += buf.length;
+                yield buf;
+            }
+        }, out);
+        // fsync so a staged blob survives a crash before apply.
+        const handle = await open(destPath, "r+");
+        try {
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        return { sha256: hash.digest("hex"), size, status: res.status };
+    },
+    async put(url, headers, body) {
+        const res = await fetch(url, { method: "PUT", headers, body: new Uint8Array(body) });
+        return res.status;
+    },
+};
+let activeTransport = realTransport;
+export function getBlobTransport() {
+    return activeTransport;
+}
+export function setBlobTransportForTests(transport) {
+    activeTransport = transport ?? realTransport;
+}
+export async function readFileBytes(path) {
+    return readFile(path);
+}

package/dist/lib/cloud/lock-path.d.ts

@@ -0,0 +1 @@
+export declare function lockPath(projectRoot: string): string;

package/dist/lib/cloud/lock-path.js

@@ -0,0 +1,5 @@
+import { join } from "path";
+import { localCloudDir } from "./paths.js";
+export function lockPath(projectRoot) {
+    return join(localCloudDir(projectRoot), "lock");
+}

package/dist/lib/cloud/lock.d.ts

@@ -0,0 +1,14 @@
+export interface CloudLock {
+    release(): Promise<void>;
+}
+type Face = "cli" | "mcp" | "engine";
+/**
+ * Per-project sync mutex (spec 8.2). O_EXCL create, 30s heartbeat, stale only
+ * by heartbeat age (120s). Two fixed races: the payload is written to the fd
+ * before close and verified by token after create (a contender that reads an
+ * empty just-created file treats parse failure as FRESH while the file is
+ * young); takeover goes through an atomic rename so two waiters can never
+ * both remove the same stale lock and both proceed.
+ */
+export declare function acquireCloudLock(projectRoot: string, face?: Face): Promise<CloudLock>;
+export {};

package/dist/lib/cloud/lock.js

@@ -0,0 +1,143 @@
+import { randomUUID } from "crypto";
+import { open, readFile, rename, rm, stat, writeFile } from "fs/promises";
+import { lockPath } from "./lock-path.js";
+const STALE_MS = 120_000;
+const WAIT_MS = 10_000;
+const HEARTBEAT_MS = 30_000;
+/**
+ * Per-project sync mutex (spec 8.2). O_EXCL create, 30s heartbeat, stale only
+ * by heartbeat age (120s). Two fixed races: the payload is written to the fd
+ * before close and verified by token after create (a contender that reads an
+ * empty just-created file treats parse failure as FRESH while the file is
+ * young); takeover goes through an atomic rename so two waiters can never
+ * both remove the same stale lock and both proceed.
+ */
+export async function acquireCloudLock(projectRoot, face = "cli") {
+    const path = lockPath(projectRoot);
+    const started = Date.now();
+    const token = randomUUID();
+    while (Date.now() - started < WAIT_MS) {
+        const acquired = await tryCreate(path, face, token);
+        if (acquired)
+            return acquired;
+        if (await isStale(path)) {
+            await takeoverStale(path);
+            continue;
+        }
+        await sleep(250);
+    }
+    throw new Error("Summer Cloud sync already in progress");
+}
+async function tryCreate(path, face, token) {
+    const startedAt = new Date().toISOString();
+    let file;
+    try {
+        file = await open(path, "wx", 0o600);
+    }
+    catch {
+        return null;
+    }
+    try {
+        await file.writeFile(JSON.stringify(payload(face, token, startedAt)), { encoding: "utf8" });
+        await file.sync();
+    }
+    finally {
+        await file.close();
+    }
+    // Re-check ownership: a racing waiter may have taken the file over between
+    // our create and write. If the token on disk is not ours, we lost.
+    if (!(await ownsLock(path, token))) {
+        return null;
+    }
+    const heartbeat = setInterval(() => {
+        void writeFile(path, JSON.stringify(payload(face, token, startedAt)), { encoding: "utf8" }).catch(() => { });
+    }, HEARTBEAT_MS);
+    heartbeat.unref?.();
+    return {
+        async release() {
+            clearInterval(heartbeat);
+            if (await ownsLock(path, token)) {
+                await rm(path, { force: true });
+            }
+        },
+    };
+}
+function payload(face, token, startedAt) {
+    return { pid: process.pid, face, token, startedAt, heartbeatAt: new Date().toISOString() };
+}
+async function ownsLock(path, token) {
+    try {
+        const raw = JSON.parse(await readFile(path, "utf8"));
+        return raw.token === token;
+    }
+    catch {
+        return false;
+    }
+}
+async function isStale(path) {
+    let raw;
+    try {
+        raw = await readFile(path, "utf8");
+    }
+    catch {
+        // Gone already; the create loop will race for it.
+        return false;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        const heartbeat = parsed.heartbeatAt ? Date.parse(parsed.heartbeatAt) : NaN;
+        if (!Number.isFinite(heartbeat))
+            throw new Error("no heartbeat");
+        return Date.now() - heartbeat > STALE_MS;
+    }
+    catch {
+        // Unparseable: probably a holder between open('wx') and write. Treat as
+        // fresh while the file is young; stale only once the mtime ages out.
+        try {
+            const info = await stat(path);
+            return Date.now() - info.mtimeMs > STALE_MS;
+        }
+        catch {
+            return false;
+        }
+    }
+}
+async function takeoverStale(path) {
+    // Atomic claim: only one waiter wins the rename; the loser's rename fails
+    // with ENOENT and it simply retries the exclusive create.
+    const claimed = `${path}.takeover.${process.pid}.${Date.now()}`;
+    try {
+        await rename(path, claimed);
+    }
+    catch {
+        return;
+    }
+    // Verify what we actually grabbed. If it turned fresh under us (the holder
+    // heartbeated between our staleness read and the rename), restore it
+    // without ever clobbering a lock someone else created in the gap.
+    try {
+        const content = await readFile(claimed, "utf8");
+        const parsed = JSON.parse(content);
+        const heartbeat = parsed.heartbeatAt ? Date.parse(parsed.heartbeatAt) : NaN;
+        if (Number.isFinite(heartbeat) && Date.now() - heartbeat <= STALE_MS) {
+            try {
+                const file = await open(path, "wx", 0o600);
+                await file.writeFile(content, { encoding: "utf8" });
+                await file.close();
+            }
+            catch {
+                // Someone else already created a new lock; the displaced holder's
+                // next heartbeat write will contend through ownsLock on release.
+            }
+            await rm(claimed, { force: true });
+            return;
+        }
+    }
+    catch {
+        // Unparseable claimed file: it aged past staleness to get here; discard.
+    }
+    await rm(claimed, { force: true });
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

package/dist/lib/cloud/manifest.d.ts

@@ -0,0 +1,6 @@
+import type { CloudManifest } from "./types.js";
+export declare function sha256Hex(bytes: Buffer | Uint8Array | string): string;
+/** Spec 6.3: keys sorted bytewise (UTF-8), no whitespace, then gzip. */
+export declare function compareKeysBytewise(a: string, b: string): number;
+export declare function serializeManifest(manifest: CloudManifest): Buffer;
+export declare function parseManifest(bytes: Buffer, expectedProjectId?: string): CloudManifest;

package/dist/lib/cloud/manifest.js

@@ -0,0 +1,41 @@
+import { createHash } from "crypto";
+import { gunzipSync, gzipSync } from "zlib";
+import { findPathCollisions, validateCloudPath } from "./validate-path.js";
+export function sha256Hex(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+/** Spec 6.3: keys sorted bytewise (UTF-8), no whitespace, then gzip. */
+export function compareKeysBytewise(a, b) {
+    return Buffer.compare(Buffer.from(a, "utf8"), Buffer.from(b, "utf8"));
+}
+export function serializeManifest(manifest) {
+    const files = Object.fromEntries(Object.entries(manifest.files).sort(([a], [b]) => compareKeysBytewise(a, b)));
+    const document = {
+        schemaVersion: manifest.schemaVersion,
+        projectId: manifest.projectId,
+        rulesVersion: manifest.rulesVersion,
+        files,
+    };
+    return gzipSync(Buffer.from(JSON.stringify(document), "utf8"));
+}
+export function parseManifest(bytes, expectedProjectId) {
+    const parsed = JSON.parse(gunzipSync(bytes).toString("utf8"));
+    if (parsed.schemaVersion !== 1 || typeof parsed.projectId !== "string" || typeof parsed.files !== "object") {
+        throw new Error("Invalid Summer Cloud manifest");
+    }
+    if (expectedProjectId && parsed.projectId !== expectedProjectId) {
+        throw new Error("Manifest projectId mismatch");
+    }
+    const keys = Object.keys(parsed.files);
+    for (const path of keys) {
+        const valid = validateCloudPath(path);
+        if (!valid.ok)
+            throw new Error(`Invalid manifest path ${path}: ${valid.reason}`);
+    }
+    const collisions = findPathCollisions(keys);
+    if (collisions.length) {
+        const first = collisions[0];
+        throw new Error(`Manifest path collision (${first.kind}): ${first.a} and ${first.b}`);
+    }
+    return parsed;
+}

package/dist/lib/cloud/paths.d.ts

@@ -0,0 +1,20 @@
+import type { BaseState, CloudBinding, PullJournal } from "./types.js";
+export declare function resolveProjectRoot(project?: string): string;
+export declare function bindingPath(projectRoot: string): string;
+export declare function localCloudDir(projectRoot: string): string;
+export declare function basePath(projectRoot: string): string;
+export declare function journalPath(projectRoot: string): string;
+export declare function hashCachePath(projectRoot: string): string;
+export declare function stagingDir(projectRoot: string): string;
+export declare function conflictsDir(projectRoot: string): string;
+export declare function ensureCloudDirs(projectRoot: string): Promise<void>;
+export declare function readBinding(projectRoot: string): Promise<CloudBinding | null>;
+export declare function writeBinding(projectRoot: string, binding: CloudBinding): Promise<void>;
+export declare function readBase(projectRoot: string): Promise<BaseState | null>;
+export declare function writeBase(projectRoot: string, base: BaseState): Promise<void>;
+export declare function readJournal(projectRoot: string): Promise<PullJournal | null>;
+export declare function writeJournal(projectRoot: string, journal: PullJournal): Promise<void>;
+export declare function removeJournal(projectRoot: string): Promise<void>;
+export declare function writeJsonAtomic(path: string, value: unknown): Promise<void>;
+export declare function projectDisplayName(projectRoot: string): Promise<string>;
+export declare function isCloudEnabled(projectRoot: string): boolean;