summer-engine 2.5.0 → 2.6.0

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;

package/dist/lib/cloud/paths.js

@@ -0,0 +1,90 @@
+import { mkdir, readFile, writeFile } from "fs/promises";
+import { existsSync } from "fs";
+import { basename, dirname, isAbsolute, join, resolve } from "path";
+export function resolveProjectRoot(project) {
+    return resolve(project ? (isAbsolute(project) ? project : join(process.cwd(), project)) : process.cwd());
+}
+export function bindingPath(projectRoot) {
+    return join(projectRoot, "summer-cloud.json");
+}
+export function localCloudDir(projectRoot) {
+    return join(projectRoot, ".summer", "local", "cloud");
+}
+export function basePath(projectRoot) {
+    return join(localCloudDir(projectRoot), "base.json");
+}
+export function journalPath(projectRoot) {
+    return join(localCloudDir(projectRoot), "journal.json");
+}
+export function hashCachePath(projectRoot) {
+    return join(localCloudDir(projectRoot), "hash-cache.json");
+}
+export function stagingDir(projectRoot) {
+    return join(localCloudDir(projectRoot), "staging");
+}
+export function conflictsDir(projectRoot) {
+    return join(localCloudDir(projectRoot), "conflicts");
+}
+export async function ensureCloudDirs(projectRoot) {
+    await mkdir(stagingDir(projectRoot), { recursive: true, mode: 0o700 });
+    await mkdir(conflictsDir(projectRoot), { recursive: true, mode: 0o700 });
+}
+export async function readBinding(projectRoot) {
+    try {
+        return JSON.parse(await readFile(bindingPath(projectRoot), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeBinding(projectRoot, binding) {
+    await writeJsonAtomic(bindingPath(projectRoot), binding);
+}
+export async function readBase(projectRoot) {
+    try {
+        return JSON.parse(await readFile(basePath(projectRoot), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeBase(projectRoot, base) {
+    await writeJsonAtomic(basePath(projectRoot), base);
+}
+export async function readJournal(projectRoot) {
+    try {
+        return JSON.parse(await readFile(journalPath(projectRoot), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+export async function writeJournal(projectRoot, journal) {
+    await writeJsonAtomic(journalPath(projectRoot), journal);
+}
+export async function removeJournal(projectRoot) {
+    const { rm } = await import("fs/promises");
+    await rm(journalPath(projectRoot), { force: true });
+}
+export async function writeJsonAtomic(path, value) {
+    await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+    const tmp = `${path}.${process.pid}.${Date.now()}.tmp`;
+    await writeFile(tmp, `${JSON.stringify(value, null, 2)}\n`, { encoding: "utf8", mode: 0o600 });
+    const { rename } = await import("fs/promises");
+    await rename(tmp, path);
+}
+export async function projectDisplayName(projectRoot) {
+    try {
+        const projectGodot = await readFile(join(projectRoot, "project.godot"), "utf8");
+        const match = projectGodot.match(/^\s*config\/name\s*=\s*"([^"]+)"/m);
+        if (match?.[1])
+            return match[1];
+    }
+    catch {
+        // Fall back to folder name.
+    }
+    return basename(projectRoot) || "Summer Project";
+}
+export function isCloudEnabled(projectRoot) {
+    return existsSync(bindingPath(projectRoot));
+}

package/dist/lib/cloud/project-godot-merge.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Section+key 3-way merge for project.godot (spec 10.2). ConfigFile semantics:
+ * keys added on either side are unioned; a key deleted on one side and
+ * unchanged on the other stays deleted (a naive union would resurrect deleted
+ * autoloads); keys changed on both sides take the CAS winner's (remote) value
+ * and the losing value is surfaced in the sync notice. config_version comes
+ * from the winner. Values can span multiple lines (Object(InputEventKey, ...))
+ * so parsing uses a balanced-delimiter tokenizer, not line splitting.
+ */
+export interface ParsedConfig {
+    /** Section name ("" for the top section) to ordered key/value text map. */
+    sections: Map<string, Map<string, string>>;
+    /** Section order as encountered. */
+    order: string[];
+}
+export declare class ConfigParseError extends Error {
+}
+export declare function parseGodotConfig(text: string): ParsedConfig;
+export declare function serializeGodotConfig(config: ParsedConfig): string;
+export interface GodotMergeResult {
+    ok: boolean;
+    merged: string;
+    /** Both-changed keys where the remote value won; notices for the sync result. */
+    losingValues: Array<{
+        section: string;
+        key: string;
+        localValue: string;
+    }>;
+    /** Parse failure on any input: whole-file remote-wins fallback. */
+    fallback: boolean;
+}
+export declare function mergeProjectGodot(baseText: string, localText: string, remoteText: string): GodotMergeResult;

package/dist/lib/cloud/project-godot-merge.js

@@ -0,0 +1,185 @@
+/**
+ * Section+key 3-way merge for project.godot (spec 10.2). ConfigFile semantics:
+ * keys added on either side are unioned; a key deleted on one side and
+ * unchanged on the other stays deleted (a naive union would resurrect deleted
+ * autoloads); keys changed on both sides take the CAS winner's (remote) value
+ * and the losing value is surfaced in the sync notice. config_version comes
+ * from the winner. Values can span multiple lines (Object(InputEventKey, ...))
+ * so parsing uses a balanced-delimiter tokenizer, not line splitting.
+ */
+export class ConfigParseError extends Error {
+}
+export function parseGodotConfig(text) {
+    const sections = new Map();
+    const order = [];
+    let current = "";
+    ensureSection(sections, order, current);
+    let i = 0;
+    const len = text.length;
+    while (i < len) {
+        // Skip whitespace and blank lines.
+        while (i < len && (text[i] === " " || text[i] === "\t" || text[i] === "\r" || text[i] === "\n"))
+            i += 1;
+        if (i >= len)
+            break;
+        const ch = text[i];
+        if (ch === ";" || ch === "#") {
+            while (i < len && text[i] !== "\n")
+                i += 1;
+            continue;
+        }
+        if (ch === "[") {
+            const close = text.indexOf("]", i);
+            if (close === -1)
+                throw new ConfigParseError("Unterminated section header");
+            current = text.slice(i + 1, close).trim();
+            ensureSection(sections, order, current);
+            i = close + 1;
+            continue;
+        }
+        // key=value. Key runs to the first unquoted '='.
+        const eq = text.indexOf("=", i);
+        const lineEnd = text.indexOf("\n", i);
+        if (eq === -1 || (lineEnd !== -1 && lineEnd < eq)) {
+            throw new ConfigParseError(`Expected key=value near offset ${i}`);
+        }
+        const key = text.slice(i, eq).trim();
+        if (!key)
+            throw new ConfigParseError(`Empty key near offset ${i}`);
+        i = eq + 1;
+        const { value, next } = readValue(text, i);
+        sections.get(current).set(key, value.trim());
+        i = next;
+    }
+    return { sections, order };
+}
+/**
+ * Reads a Variant value starting at `start`, consuming across newlines while
+ * any parenthesis, bracket, or brace is unbalanced or a string is open.
+ */
+function readValue(text, start) {
+    let depth = 0;
+    let inString = false;
+    let i = start;
+    const len = text.length;
+    while (i < len) {
+        const ch = text[i];
+        if (inString) {
+            if (ch === "\\") {
+                i += 2;
+                continue;
+            }
+            if (ch === '"')
+                inString = false;
+            i += 1;
+            continue;
+        }
+        if (ch === '"') {
+            inString = true;
+            i += 1;
+            continue;
+        }
+        if (ch === "(" || ch === "[" || ch === "{")
+            depth += 1;
+        else if (ch === ")" || ch === "]" || ch === "}") {
+            depth -= 1;
+            if (depth < 0)
+                throw new ConfigParseError(`Unbalanced delimiter at offset ${i}`);
+        }
+        else if (ch === "\n" && depth === 0) {
+            return { value: text.slice(start, i), next: i + 1 };
+        }
+        i += 1;
+    }
+    if (inString || depth > 0)
+        throw new ConfigParseError("Unterminated value");
+    return { value: text.slice(start, i), next: i };
+}
+function ensureSection(sections, order, name) {
+    if (!sections.has(name)) {
+        sections.set(name, new Map());
+        order.push(name);
+    }
+}
+export function serializeGodotConfig(config) {
+    const parts = [];
+    for (const name of config.order) {
+        const entries = config.sections.get(name);
+        if (!entries || entries.size === 0) {
+            if (name === "")
+                continue;
+        }
+        if (name !== "") {
+            parts.push(`[${name}]`);
+            parts.push("");
+        }
+        for (const [key, value] of entries ?? []) {
+            parts.push(`${key}=${value}`);
+        }
+        parts.push("");
+    }
+    return `${parts.join("\n").replace(/\n+$/, "")}\n`;
+}
+export function mergeProjectGodot(baseText, localText, remoteText) {
+    let base;
+    let local;
+    let remote;
+    try {
+        base = parseGodotConfig(baseText);
+        local = parseGodotConfig(localText);
+        remote = parseGodotConfig(remoteText);
+    }
+    catch {
+        // Parse failure on any of the three inputs: fall back to whole-file
+        // remote-wins; the caller writes the local bytes as a conflict copy.
+        return { ok: true, merged: remoteText, losingValues: [], fallback: true };
+    }
+    const merged = { sections: new Map(), order: [] };
+    const losingValues = [];
+    const sectionNames = [];
+    for (const name of [...remote.order, ...local.order, ...base.order]) {
+        if (!sectionNames.includes(name))
+            sectionNames.push(name);
+    }
+    for (const section of sectionNames) {
+        const b = base.sections.get(section) ?? new Map();
+        const l = local.sections.get(section) ?? new Map();
+        const r = remote.sections.get(section) ?? new Map();
+        const keys = [];
+        for (const key of [...r.keys(), ...l.keys(), ...b.keys()]) {
+            if (!keys.includes(key))
+                keys.push(key);
+        }
+        const out = new Map();
+        for (const key of keys) {
+            const bv = b.get(key);
+            const lv = l.get(key);
+            const rv = r.get(key);
+            const resolved = mergeKey(bv, lv, rv);
+            if (resolved.losing !== undefined) {
+                losingValues.push({ section, key, localValue: resolved.losing });
+            }
+            if (resolved.value !== undefined)
+                out.set(key, resolved.value);
+        }
+        if (out.size > 0 || section === "") {
+            merged.sections.set(section, out);
+            merged.order.push(section);
+        }
+    }
+    return { ok: true, merged: serializeGodotConfig(merged), losingValues, fallback: false };
+}
+function mergeKey(base, local, remote) {
+    if (local === remote)
+        return { value: local };
+    const localChanged = local !== base;
+    const remoteChanged = remote !== base;
+    if (localChanged && !remoteChanged)
+        return { value: local };
+    if (remoteChanged && !localChanged)
+        return { value: remote };
+    // Changed on both sides (including delete vs change): the CAS winner's
+    // (remote) value wins at key granularity; deletion on the remote side wins
+    // too. The losing local value is surfaced.
+    return { value: remote, losing: local ?? "(deleted locally)" };
+}

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

@@ -0,0 +1,39 @@
+/**
+ * Tracked-set rules (spec section 13). Full-project sync, single mode.
+ * Hard excludes cannot be re-included; .summercloudignore can only exclude
+ * further. The built-in rule set carries RULES_VERSION; manifests record the
+ * rulesVersion that produced them so stale clients can operate restricted.
+ */
+export declare const RULES_VERSION = 1;
+export declare function isHardExcludedDir(relPath: string, name: string): boolean;
+/**
+ * Hard-excluded files. `siblings` is the set of basenames in the same
+ * directory, used to detect Godot safe-save temps (name-XXXXXX with the base
+ * file present).
+ */
+export declare function isHardExcludedFile(relPath: string, name: string, siblings: ReadonlySet<string>): boolean;
+/** Godot safe-save writes `name-XXXXXX` (six trailing random chars) next to `name`. */
+export declare function isGodotSafeSaveTemp(name: string, siblings: ReadonlySet<string>): boolean;
+/** True when a manifest key falls under the built-in hard excludes. */
+export declare function isHardExcludedPath(path: string): boolean;
+export interface IgnoreRule {
+    raw: string;
+    /** Trailing slash: matches directories (and everything under them). */
+    directory: boolean;
+    /** Leading slash: anchored to the project root. */
+    anchored: boolean;
+    regex: RegExp;
+}
+export interface TrackedRules {
+    rulesVersion: number;
+    ignore: IgnoreRule[];
+}
+export declare function loadTrackedRules(projectRoot: string): Promise<TrackedRules>;
+export declare function parseIgnoreRules(raw: string): IgnoreRule[];
+export declare function isIgnoredByRules(path: string, isDirectory: boolean, rules: TrackedRules): boolean;
+/**
+ * Deletion semantics (spec 13): a path may be marked deleted only if it
+ * matches the CURRENT tracked rules AND is absent on disk. Paths that merely
+ * stopped matching rules are carried forward unchanged.
+ */
+export declare function isTrackedByCurrentRules(path: string, rules: TrackedRules): boolean;