summer-engine 2.5.0 → 2.6.0

package/dist/lib/cloud/containment.js

@@ -0,0 +1,52 @@
+import { lstat, mkdir, realpath } from "fs/promises";
+import { join, resolve, sep } from "path";
+import { validateCloudPath } from "./validate-path.js";
+/**
+ * Write containment (spec 9): after joining a manifest key to the project
+ * root, resolve the parent chain and assert the final absolute path is
+ * strictly inside the realpath of the project root; refuse to write through
+ * any symlinked directory component; create nested parents per component so
+ * a hostile manifest can never escape the project.
+ */
+export async function containedProjectPath(projectRoot, key) {
+    const valid = validateCloudPath(key);
+    if (!valid.ok) {
+        throw new Error(`Refusing unsafe path ${key}: ${valid.reason}`);
+    }
+    const rootReal = await realpath(projectRoot);
+    const segments = key.split("/");
+    let current = rootReal;
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        current = join(current, segments[i]);
+        let info;
+        try {
+            info = await lstat(current);
+        }
+        catch {
+            await mkdir(current);
+            continue;
+        }
+        if (info.isSymbolicLink()) {
+            throw new Error(`Refusing to write through symlinked directory component: ${current}`);
+        }
+        if (!info.isDirectory()) {
+            throw new Error(`Path component is not a directory: ${current}`);
+        }
+    }
+    const target = join(current, segments[segments.length - 1]);
+    const normalizedRoot = rootReal.endsWith(sep) ? rootReal : rootReal + sep;
+    if (!resolve(target).startsWith(normalizedRoot)) {
+        throw new Error(`Path escapes project root: ${key}`);
+    }
+    try {
+        const info = await lstat(target);
+        if (info.isSymbolicLink()) {
+            throw new Error(`Refusing to replace a symlink: ${key}`);
+        }
+    }
+    catch (err) {
+        if (err.code !== "ENOENT")
+            throw err;
+    }
+    return target;
+}

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

@@ -0,0 +1,39 @@
+import type { CloudManifest, ManifestFile } from "./types.js";
+export type DecisionKind = "push" | "pull" | "delete-local" | "delete-remote" | "conflict-remote-wins" | "keep-local" | "converged";
+export interface PathDecision {
+    path: string;
+    kind: DecisionKind;
+    base?: ManifestFile;
+    local?: ManifestFile;
+    remote?: ManifestFile;
+}
+export interface DiffPlan {
+    decisions: PathDecision[];
+    pushPaths: string[];
+    pullPaths: string[];
+    deleteLocalPaths: string[];
+    deleteRemotePaths: string[];
+    conflictPaths: string[];
+    /** Row 14: local edit beat a remote delete; surfaced as a notice. */
+    keepLocalPaths: string[];
+    /** Row 15: remote edit beat a local delete; surfaced as a notice. */
+    restoredRemotePaths: string[];
+}
+export declare function diffManifests(base: CloudManifest, local: CloudManifest, remote: CloudManifest): DiffPlan;
+/**
+ * Sidecar pairing (spec 8.4): foo.png + foo.png.import and foo.gd + foo.gd.uid
+ * diff, transfer, delete, and conflict-resolve as one atomic unit. When the
+ * primary and its sidecar disagree about which side wins, the primary's
+ * direction wins and the sidecar decision is recomputed under that direction.
+ */
+export declare function sidecarPrimary(path: string): string | null;
+/**
+ * Mass-deletion guardrail (spec 8.5). Confirmation required when deletions
+ * exceed 10 files, reach 20% of the base, or cover the entire base.
+ */
+export declare function assertDeleteGuard(plan: DiffPlan, baseFileCount: number, confirmDeletes?: boolean): void;
+/**
+ * Hard abort (spec 8.5): base non-empty and the local tree reads as completely
+ * empty (unmounted volume, wrong directory). No confirmation can override this.
+ */
+export declare function assertNotEmptyLocalTree(baseFileCount: number, localFileCount: number): void;

package/dist/lib/cloud/diff.js

@@ -0,0 +1,138 @@
+export function diffManifests(base, local, remote) {
+    const paths = new Set([...Object.keys(base.files), ...Object.keys(local.files), ...Object.keys(remote.files)]);
+    const decisions = [];
+    for (const path of [...paths].sort()) {
+        const b = base.files[path];
+        const l = local.files[path];
+        const r = remote.files[path];
+        const kind = decide(b, l, r);
+        decisions.push({ path, kind, base: b, local: l, remote: r });
+    }
+    pairSidecars(decisions);
+    return planFromDecisions(decisions);
+}
+function planFromDecisions(decisions) {
+    return {
+        decisions,
+        pushPaths: decisions.filter((d) => d.kind === "push").map((d) => d.path),
+        pullPaths: decisions.filter((d) => d.kind === "pull").map((d) => d.path),
+        deleteLocalPaths: decisions.filter((d) => d.kind === "delete-local").map((d) => d.path),
+        deleteRemotePaths: decisions.filter((d) => d.kind === "delete-remote").map((d) => d.path),
+        conflictPaths: decisions.filter((d) => d.kind === "conflict-remote-wins").map((d) => d.path),
+        keepLocalPaths: decisions.filter((d) => d.kind === "keep-local").map((d) => d.path),
+        restoredRemotePaths: decisions
+            .filter((d) => d.kind === "pull" && d.base && !d.local && d.remote && !same(d.remote, d.base))
+            .map((d) => d.path),
+    };
+}
+function decide(base, local, remote) {
+    if (same(local, remote))
+        return "converged";
+    if (!base && local && !remote)
+        return "push";
+    if (!base && !local && remote)
+        return "pull";
+    if (!base && local && remote)
+        return same(local, remote) ? "converged" : "conflict-remote-wins";
+    if (base && same(local, base) && remote && !same(remote, base))
+        return "pull";
+    if (base && local && !same(local, base) && same(remote, base))
+        return "push";
+    if (base && local && remote && same(local, remote))
+        return "converged";
+    if (base && local && remote && !same(local, base) && !same(remote, base))
+        return "conflict-remote-wins";
+    if (base && !local && same(remote, base))
+        return "delete-remote";
+    if (base && same(local, base) && !remote)
+        return "delete-local";
+    if (base && !local && remote && !same(remote, base))
+        return "pull";
+    if (base && local && !same(local, base) && !remote)
+        return "keep-local";
+    return "converged";
+}
+function same(a, b) {
+    if (!a && !b)
+        return true;
+    if (!a || !b)
+        return false;
+    return a.sha256 === b.sha256 && a.size === b.size;
+}
+/**
+ * Sidecar pairing (spec 8.4): foo.png + foo.png.import and foo.gd + foo.gd.uid
+ * diff, transfer, delete, and conflict-resolve as one atomic unit. When the
+ * primary and its sidecar disagree about which side wins, the primary's
+ * direction wins and the sidecar decision is recomputed under that direction.
+ */
+export function sidecarPrimary(path) {
+    if (path.endsWith(".import"))
+        return path.slice(0, -".import".length);
+    if (path.endsWith(".uid"))
+        return path.slice(0, -".uid".length);
+    return null;
+}
+const REMOTE_WINS = new Set(["pull", "delete-local", "conflict-remote-wins"]);
+const LOCAL_WINS = new Set(["push", "delete-remote", "keep-local"]);
+function pairSidecars(decisions) {
+    const byPath = new Map(decisions.map((d) => [d.path, d]));
+    for (const sidecar of decisions) {
+        const primaryPath = sidecarPrimary(sidecar.path);
+        if (!primaryPath)
+            continue;
+        const primary = byPath.get(primaryPath);
+        if (!primary)
+            continue;
+        // A converged sidecar (L == R) is compatible with either side and a
+        // converged primary lets the sidecar act alone; only direction
+        // disagreement inside the pair is overridden, with the primary winning.
+        if (sidecar.kind === "converged" || primary.kind === "converged")
+            continue;
+        if (REMOTE_WINS.has(primary.kind) && !REMOTE_WINS.has(sidecar.kind)) {
+            sidecar.kind = forceRemoteSide(sidecar);
+        }
+        else if (LOCAL_WINS.has(primary.kind) && !LOCAL_WINS.has(sidecar.kind)) {
+            sidecar.kind = forceLocalSide(sidecar);
+        }
+    }
+}
+function forceRemoteSide(sidecar) {
+    if (sidecar.remote && sidecar.local && !same(sidecar.local, sidecar.remote))
+        return "conflict-remote-wins";
+    if (sidecar.remote && !sidecar.local)
+        return "pull";
+    if (!sidecar.remote && sidecar.local)
+        return "delete-local";
+    return "converged";
+}
+function forceLocalSide(sidecar) {
+    if (sidecar.local && !same(sidecar.local, sidecar.remote))
+        return "push";
+    if (!sidecar.local && sidecar.remote)
+        return "delete-remote";
+    return "converged";
+}
+/**
+ * Mass-deletion guardrail (spec 8.5). Confirmation required when deletions
+ * exceed 10 files, reach 20% of the base, or cover the entire base.
+ */
+export function assertDeleteGuard(plan, baseFileCount, confirmDeletes) {
+    const deletes = plan.deleteRemotePaths.length;
+    if (!deletes)
+        return;
+    const tooMany = deletes > 10 ||
+        (baseFileCount > 0 && deletes >= Math.ceil(baseFileCount * 0.2)) ||
+        deletes === baseFileCount;
+    if (tooMany && !confirmDeletes) {
+        throw new Error(`Push would delete ${deletes} cloud files. Re-run with --confirm-deletes after verifying the project path.`);
+    }
+}
+/**
+ * Hard abort (spec 8.5): base non-empty and the local tree reads as completely
+ * empty (unmounted volume, wrong directory). No confirmation can override this.
+ */
+export function assertNotEmptyLocalTree(baseFileCount, localFileCount) {
+    if (baseFileCount > 0 && localFileCount === 0) {
+        throw new Error("Local project tree is empty but the sync base is not. This looks like an unmounted volume or wrong directory. Aborting sync; no confirmation can push this.");
+    }
+}

package/dist/lib/cloud/engine-bridge.d.ts

@@ -0,0 +1,21 @@
+/**
+ * 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 declare function readProjectIdHash(projectRoot: string): Promise<string | null>;
+export declare function readProjectPathMarker(projectRoot: string): Promise<string | null>;
+export declare function writeProjectPathMarker(projectRoot: string): Promise<void>;
+/**
+ * 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 declare function saveDirtyScenesIfRunning(projectRoot: string): Promise<boolean>;
+/**
+ * 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 declare function notifyEngineAfterApply(projectRoot: string, appliedPaths: readonly string[]): Promise<void>;

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 {};