summer-engine 2.3.0 → 2.6.0

package/dist/lib/cloud/transfer.js

@@ -0,0 +1,184 @@
+import { mkdir, readFile } from "fs/promises";
+import { join } from "path";
+import { getCloudApi } from "./api.js";
+import { getBlobTransport } from "./http.js";
+import { sha256Hex } from "./manifest.js";
+import { stagingDir } from "./paths.js";
+/** Server batch caps (spec 7.5 to 7.8); the server 400s above these. */
+export const CHECK_BATCH = 10_000;
+export const PRESIGN_BATCH = 500;
+export const COMPLETE_BATCH = 500;
+export const PRESIGN_GET_BATCH = 500;
+const UPLOAD_CONCURRENCY = 16;
+const DOWNLOAD_CONCURRENCY = 32;
+const RETRY_BACKOFF_MS = [1_000, 2_000, 4_000];
+export async function uploadBlobs(projectId, blobs) {
+    const api = getCloudApi();
+    const hashes = [...blobs.keys()];
+    const outcome = { uploaded: [], requeued: [] };
+    if (!hashes.length)
+        return outcome;
+    const missing = new Set();
+    for (const chunk of chunks(hashes, CHECK_BATCH)) {
+        for (const hash of (await api.checkBlobs(projectId, chunk)).missing)
+            missing.add(hash);
+    }
+    if (!missing.size)
+        return outcome;
+    // JIT presign loop: presign in batches as the upload queue drains so URLs
+    // stay fresh on slow links.
+    const queue = [...missing];
+    while (queue.length) {
+        const batch = queue.splice(0, PRESIGN_BATCH);
+        const toPresign = batch.map((sha256) => {
+            const source = blobs.get(sha256);
+            if (!source)
+                throw new Error(`Missing upload source for ${sha256}`);
+            return { sha256, size: source.size };
+        });
+        const signed = await api.presignBlobs(projectId, toPresign);
+        const completed = [];
+        await runWithConcurrency(signed.blobs, UPLOAD_CONCURRENCY, async (item) => {
+            if (item.status === "exists")
+                return;
+            if (item.status !== "upload" || !item.url || !item.uploadId || !item.headers) {
+                throw new Error(item.message || `Could not presign ${item.sha256}: ${item.status}`);
+            }
+            const result = await putWithRetry(projectId, item, blobs.get(item.sha256));
+            if (result === "uploaded") {
+                completed.push({ sha256: item.sha256, uploadId: item.uploadId });
+                outcome.uploaded.push(item.sha256);
+            }
+            else if (result === "already-verified") {
+                outcome.uploaded.push(item.sha256);
+            }
+            else {
+                outcome.requeued.push(item.sha256);
+            }
+        });
+        for (const completeChunk of chunks(completed, COMPLETE_BATCH)) {
+            if (!completeChunk.length)
+                continue;
+            const result = await api.completeBlobs(projectId, completeChunk);
+            const failed = result.uploads.filter((upload) => upload.status !== "verified");
+            if (failed.length) {
+                throw new Error(`Cloud upload completion failed: ${failed.map((f) => `${f.sha256}:${f.status}`).join(", ")}`);
+            }
+        }
+    }
+    return outcome;
+}
+async function putWithRetry(projectId, item, source) {
+    const api = getCloudApi();
+    const transport = getBlobTransport();
+    // Re-hash the bytes that are actually sent (spec 8.6.4); on divergence from
+    // the diff-time hash, abort this file and requeue it for the next run.
+    const bytes = source.bytes ?? (await readFile(source.path));
+    if (sha256Hex(bytes) !== item.sha256) {
+        return "requeued";
+    }
+    for (let attempt = 0;; attempt += 1) {
+        const status = await transport.put(item.url, item.headers, bytes);
+        if (status >= 200 && status < 300)
+            return "uploaded";
+        if (status === 429) {
+            // R2 per-key write throttling: back off 1s and re-check; verified means
+            // someone else won the race with identical bytes.
+            await sleep(1_000);
+            const recheck = await api.checkBlobs(projectId, [item.sha256]);
+            if (!recheck.missing.includes(item.sha256))
+                return "already-verified";
+        }
+        if (attempt >= RETRY_BACKOFF_MS.length) {
+            throw new Error(`R2 upload failed for ${item.sha256}: ${status}`);
+        }
+        await sleep(RETRY_BACKOFF_MS[attempt]);
+    }
+}
+/**
+ * Two-phase pull, phase 1 (spec 8.7): stream every needed blob to
+ * .summer/local/cloud/staging/{sha256}, verify its sha256, fsync. Returns the
+ * staged file path per hash. Already-staged blobs with a verified hash are
+ * reused (journal resume).
+ */
+export async function downloadBlobs(projectRoot, projectId, hashes) {
+    const api = getCloudApi();
+    const transport = getBlobTransport();
+    const unique = [...new Set(hashes)];
+    const staged = new Map();
+    await mkdir(stagingDir(projectRoot), { recursive: true, mode: 0o700 });
+    const needed = [];
+    for (const hash of unique) {
+        const path = join(stagingDir(projectRoot), hash);
+        if (await isStagedAndValid(path, hash)) {
+            staged.set(hash, path);
+        }
+        else {
+            needed.push(hash);
+        }
+    }
+    for (const chunk of chunks(needed, PRESIGN_GET_BATCH)) {
+        const signed = await api.presignGet(projectId, chunk);
+        if (signed.missing.length) {
+            throw new Error(`Cloud is missing referenced blobs: ${signed.missing.join(", ")}`);
+        }
+        await runWithConcurrency(chunk, DOWNLOAD_CONCURRENCY, async (hash) => {
+            const url = signed.urls[hash];
+            if (!url)
+                throw new Error(`No URL for ${hash}`);
+            const path = join(stagingDir(projectRoot), hash);
+            for (let attempt = 0;; attempt += 1) {
+                const result = await transport.getToFile(url, path);
+                if (result.status >= 200 && result.status < 300) {
+                    if (result.sha256 !== hash)
+                        throw new Error(`Downloaded blob hash mismatch: ${hash}`);
+                    staged.set(hash, path);
+                    return;
+                }
+                if (attempt >= RETRY_BACKOFF_MS.length) {
+                    throw new Error(`Download failed for ${hash}: ${result.status}`);
+                }
+                await sleep(RETRY_BACKOFF_MS[attempt]);
+            }
+        });
+    }
+    return staged;
+}
+async function isStagedAndValid(path, hash) {
+    try {
+        const bytes = await readFile(path);
+        return sha256Hex(bytes) === hash;
+    }
+    catch {
+        return false;
+    }
+}
+async function runWithConcurrency(items, limit, worker) {
+    const pending = [...items];
+    const errors = [];
+    const runners = Array.from({ length: Math.min(limit, pending.length) }, async () => {
+        while (pending.length) {
+            const item = pending.shift();
+            if (item === undefined)
+                return;
+            try {
+                await worker(item);
+            }
+            catch (err) {
+                errors.push(err);
+            }
+        }
+    });
+    await Promise.all(runners);
+    if (errors.length)
+        throw errors[0];
+}
+function chunks(items, size) {
+    const out = [];
+    for (let i = 0; i < items.length; i += size)
+        out.push(items.slice(i, i + size));
+    return out;
+}
+function sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}

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

@@ -0,0 +1,62 @@
+export type HashHex = string;
+export interface ManifestFile {
+    sha256: HashHex;
+    size: number;
+}
+export interface CloudManifest {
+    schemaVersion: 1;
+    projectId: string;
+    rulesVersion: number;
+    files: Record<string, ManifestFile>;
+}
+export interface CloudBinding {
+    schemaVersion: 1;
+    projectId: string;
+    pinnedVersion?: number;
+}
+export interface BaseState extends CloudManifest {
+    version: number;
+}
+export interface PullJournal {
+    syncId: string;
+    targetVersion: number;
+    phase: "staging" | "applying";
+    pending: Array<{
+        path: string;
+        sha256: string;
+    }>;
+}
+export interface LocalFileStat {
+    size: number;
+    mtimeNs: string;
+    inode: string;
+}
+export interface WalkResult {
+    files: Record<string, ManifestFile>;
+    fileByHash: Map<string, string>;
+    /** NFC manifest key to actual absolute on-disk path (byte-name map for I/O). */
+    diskPathByKey: Map<string, string>;
+    /** Pre-image stats captured at hash time, used by the apply-time stat check. */
+    statByKey: Map<string, LocalFileStat>;
+    skippedSymlinks: string[];
+    /** Paths excluded from THIS run because they kept changing while hashing. */
+    unstablePaths: string[];
+}
+export type BootstrapChoice = "keep-cloud" | "keep-local" | "merge";
+export interface SyncOptions {
+    project?: string;
+    json?: boolean;
+    confirmDeletes?: boolean;
+    bootstrap?: BootstrapChoice;
+    /** Accept that the project folder moved and update .summer/local/.project_path. */
+    adoptPath?: boolean;
+}
+export interface SyncResult {
+    ok: boolean;
+    action: string;
+    projectId?: string;
+    version?: number;
+    message: string;
+    notices?: string[];
+    details?: Record<string, unknown>;
+}

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

@@ -0,0 +1,23 @@
+/**
+ * Unicode case folding approximation without ICU: lower, upper, lower. The
+ * round trip folds one-to-many mappings that plain toLowerCase misses
+ * (eszett to ss, long s to s, final sigma to sigma).
+ */
+export declare function casefoldKey(path: string): string;
+export declare function validateCloudPath(path: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export interface PathCollision {
+    kind: "casefold" | "nfc" | "prefix";
+    a: string;
+    b: string;
+}
+/**
+ * Pairwise key collision checks (spec section 9): two keys equal after NFC,
+ * two keys equal under casefold(NFC(key)), or one key being a directory
+ * prefix of another (file vs directory collision).
+ */
+export declare function findPathCollisions(keys: readonly string[]): PathCollision[];

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

@@ -0,0 +1,103 @@
+const WINDOWS_RESERVED_BASENAMES = new Set([
+    "con",
+    "prn",
+    "aux",
+    "nul",
+    "com0",
+    "com1",
+    "com2",
+    "com3",
+    "com4",
+    "com5",
+    "com6",
+    "com7",
+    "com8",
+    "com9",
+    "com¹",
+    "com²",
+    "com³",
+    "lpt0",
+    "lpt1",
+    "lpt2",
+    "lpt3",
+    "lpt4",
+    "lpt5",
+    "lpt6",
+    "lpt7",
+    "lpt8",
+    "lpt9",
+    "lpt¹",
+    "lpt²",
+    "lpt³",
+]);
+/** Spec section 9: full key at most 1024 bytes, each segment at most 255. */
+const MAX_KEY_BYTES = 1024;
+const MAX_SEGMENT_BYTES = 255;
+/**
+ * Unicode case folding approximation without ICU: lower, upper, lower. The
+ * round trip folds one-to-many mappings that plain toLowerCase misses
+ * (eszett to ss, long s to s, final sigma to sigma).
+ */
+export function casefoldKey(path) {
+    return path.normalize("NFC").toLowerCase().toUpperCase().toLowerCase();
+}
+export function validateCloudPath(path) {
+    if (!path || path !== path.normalize("NFC"))
+        return { ok: false, reason: "Path must be non-empty and NFC-normalized" };
+    if (path.startsWith("/") || path.startsWith("\\") || /^[a-zA-Z]:/.test(path))
+        return { ok: false, reason: "Path must be relative" };
+    if (path.includes("\\") || path.includes("//") || path.endsWith("/") || /[\u0000-\u001f]/.test(path)) {
+        return { ok: false, reason: "Path contains invalid characters" };
+    }
+    if (Buffer.byteLength(path, "utf8") > MAX_KEY_BYTES)
+        return { ok: false, reason: `Path exceeds ${MAX_KEY_BYTES} bytes` };
+    for (const segment of path.split("/")) {
+        if (!segment || segment === "." || segment === "..")
+            return { ok: false, reason: "Path contains dot or empty segment" };
+        if (Buffer.byteLength(segment, "utf8") > MAX_SEGMENT_BYTES)
+            return { ok: false, reason: `Path segment exceeds ${MAX_SEGMENT_BYTES} bytes` };
+        if (segment.endsWith(".") || segment.endsWith(" "))
+            return { ok: false, reason: "Path segment ends with dot or space" };
+        if (/[<>:"|?*]/.test(segment))
+            return { ok: false, reason: "Path segment contains a reserved character" };
+        if (WINDOWS_RESERVED_BASENAMES.has(casefoldKey(segment.split(".")[0] || ""))) {
+            return { ok: false, reason: "Path segment uses a Windows device name" };
+        }
+    }
+    return { ok: true };
+}
+/**
+ * Pairwise key collision checks (spec section 9): two keys equal after NFC,
+ * two keys equal under casefold(NFC(key)), or one key being a directory
+ * prefix of another (file vs directory collision).
+ */
+export function findPathCollisions(keys) {
+    const collisions = [];
+    const byNfc = new Map();
+    const byFold = new Map();
+    for (const key of keys) {
+        const nfc = key.normalize("NFC");
+        const priorNfc = byNfc.get(nfc);
+        if (priorNfc !== undefined && priorNfc !== key) {
+            collisions.push({ kind: "nfc", a: priorNfc, b: key });
+        }
+        else {
+            byNfc.set(nfc, key);
+        }
+        const folded = casefoldKey(key);
+        const priorFold = byFold.get(folded);
+        if (priorFold !== undefined && priorFold !== key) {
+            collisions.push({ kind: "casefold", a: priorFold, b: key });
+        }
+        else {
+            byFold.set(folded, key);
+        }
+    }
+    const sorted = [...keys].sort();
+    for (let i = 0; i + 1 < sorted.length; i += 1) {
+        if (sorted[i + 1].startsWith(`${sorted[i]}/`)) {
+            collisions.push({ kind: "prefix", a: sorted[i], b: sorted[i + 1] });
+        }
+    }
+    return collisions;
+}

package/dist/lib/engine.d.ts

@@ -5,6 +5,12 @@ export interface EngineHealth {
     engine: string;
     version: string;
     port: number;
+    pid?: number;
+    instanceId?: string;
+    projectId?: string;
+    projectIdHash?: string;
+    mainAliveMs?: number;
+    queueDepth?: number;
     project_name?: string;
     project_path?: string;
     scene?: string;

package/dist/lib/engine.js

@@ -21,6 +21,17 @@ export async function getApiPort() {
         return DEFAULT_PORT;
     }
 }
+function asRecord(value) {
+    return value && typeof value === "object" && !Array.isArray(value)
+        ? value
+        : null;
+}
+function stringFrom(value) {
+    return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+function numberFrom(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : undefined;
+}
 export async function checkEngineHealth(port) {
     try {
         const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
@@ -28,7 +39,31 @@ export async function checkEngineHealth(port) {
         });
         if (!res.ok)
             return null;
-        return (await res.json());
+        const data = asRecord(await res.json());
+        if (!data)
+            return null;
+        const ok = data.ok === true;
+        const engine = stringFrom(data.engine);
+        const version = stringFrom(data.version);
+        const instanceId = stringFrom(data.instanceId);
+        if (!ok || engine !== "summer" || !version || !instanceId) {
+            return null;
+        }
+        return {
+            ok,
+            engine,
+            version,
+            port: numberFrom(data.port) ?? port,
+            pid: numberFrom(data.pid),
+            instanceId,
+            projectId: stringFrom(data.projectId),
+            projectIdHash: stringFrom(data.projectIdHash),
+            mainAliveMs: numberFrom(data.mainAliveMs),
+            queueDepth: numberFrom(data.queueDepth),
+            project_name: stringFrom(data.project_name),
+            project_path: stringFrom(data.project_path),
+            scene: stringFrom(data.scene),
+        };
     }
     catch {
         return null;

package/dist/lib/game-task-plan.d.ts

@@ -0,0 +1,42 @@
+export declare const GAME_TASK_MODES: readonly ["auto", "new-game", "feature", "asset", "debug", "playtest", "polish", "ship"];
+export declare const GAME_TASK_TARGETS: readonly ["auto", "2d", "3d", "ui", "audio", "animation", "level", "npc", "multiplayer"];
+export declare const ASSET_POLICIES: readonly ["reuse-first", "ask-before-paid-generation", "no-paid-generation", "generate-when-clearly-needed"];
+export declare const VERIFICATION_LEVELS: readonly ["none", "fast", "full"];
+export type GameTaskMode = (typeof GAME_TASK_MODES)[number];
+export type GameTaskTarget = (typeof GAME_TASK_TARGETS)[number];
+export type AssetPolicy = (typeof ASSET_POLICIES)[number];
+export type VerificationLevel = (typeof VERIFICATION_LEVELS)[number];
+export interface GameTaskPlanOptions {
+    goal: string;
+    mode?: GameTaskMode;
+    target?: GameTaskTarget;
+    assetPolicy?: AssetPolicy;
+    verification?: VerificationLevel;
+}
+export interface SkillRoute {
+    id: string;
+    name: string;
+    category: string;
+    why: string;
+    requiresMcpTools: readonly string[];
+}
+export interface GameTaskPlan {
+    goal: string;
+    mode: Exclude<GameTaskMode, "auto">;
+    target: Exclude<GameTaskTarget, "auto"> | "general";
+    assetPolicy: AssetPolicy;
+    verification: VerificationLevel;
+    principles: string[];
+    recommendedSkills: SkillRoute[];
+    mcpToolPlan: {
+        start: string[];
+        mutate: string[];
+        assets: string[];
+        verify: string[];
+    };
+    hostFileWork: string[];
+    userGates: string[];
+    nextAgentSteps: string[];
+    antiPatterns: string[];
+}
+export declare function buildGameTaskPlan(options: GameTaskPlanOptions): GameTaskPlan;