summer-engine 2.3.0 → 2.6.0

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;

package/dist/lib/cloud/rules.js

@@ -0,0 +1,159 @@
+import { readFile } from "fs/promises";
+import { join } from "path";
+/**
+ * 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 const RULES_VERSION = 1;
+/** Directory names hard-excluded at any depth. */
+const EXCLUDED_DIR_NAMES = new Set([
+    ".git",
+    ".godot",
+    "node_modules",
+    ".next",
+    ".claude",
+    ".specstory",
+]);
+/** Root-only excluded directories. */
+const EXCLUDED_ROOT_DIRS = new Set(["android"]);
+/** Exact file basenames hard-excluded everywhere. */
+const EXCLUDED_FILE_NAMES = new Set([".DS_Store", "Thumbs.db", "desktop.ini", "project.godot.bak"]);
+export function isHardExcludedDir(relPath, name) {
+    if (EXCLUDED_DIR_NAMES.has(name))
+        return true;
+    if (EXCLUDED_ROOT_DIRS.has(name) && relPath === name)
+        return true;
+    // .summer/local/ is machine state; the rest of .summer/** is tracked.
+    if (relPath === ".summer/local")
+        return true;
+    return false;
+}
+/**
+ * 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 function isHardExcludedFile(relPath, name, siblings) {
+    if (EXCLUDED_FILE_NAMES.has(name))
+        return true;
+    if (name.startsWith(".env"))
+        return true;
+    if (name.endsWith(".translation"))
+        return true;
+    if (name.endsWith(".tmp"))
+        return true;
+    if (isGodotSafeSaveTemp(name, siblings))
+        return true;
+    return false;
+}
+/** Godot safe-save writes `name-XXXXXX` (six trailing random chars) next to `name`. */
+export function isGodotSafeSaveTemp(name, siblings) {
+    const match = /^(.+)-[A-Za-z0-9]{6}$/.exec(name);
+    if (!match)
+        return false;
+    return siblings.has(match[1]);
+}
+/** True when a manifest key falls under the built-in hard excludes. */
+export function isHardExcludedPath(path) {
+    if (path === ".summer/local" || path.startsWith(".summer/local/"))
+        return true;
+    const segments = path.split("/");
+    let prefix = "";
+    for (let i = 0; i < segments.length - 1; i += 1) {
+        prefix = prefix ? `${prefix}/${segments[i]}` : segments[i];
+        if (isHardExcludedDir(prefix, segments[i]))
+            return true;
+    }
+    const name = segments[segments.length - 1];
+    if (EXCLUDED_DIR_NAMES.has(name))
+        return true;
+    return isHardExcludedFile(path, name, new Set());
+}
+export async function loadTrackedRules(projectRoot) {
+    let raw = "";
+    try {
+        raw = await readFile(join(projectRoot, ".summercloudignore"), "utf8");
+    }
+    catch {
+        return { rulesVersion: RULES_VERSION, ignore: [] };
+    }
+    return { rulesVersion: RULES_VERSION, ignore: parseIgnoreRules(raw) };
+}
+export function parseIgnoreRules(raw) {
+    return raw
+        .split(/\r?\n/)
+        .map((line) => line.trim())
+        .filter((line) => line && !line.startsWith("#") && !line.startsWith("!"))
+        .map((line) => {
+        const directory = line.endsWith("/");
+        let cleaned = directory ? line.slice(0, -1) : line;
+        const anchored = cleaned.startsWith("/");
+        if (anchored)
+            cleaned = cleaned.slice(1);
+        return { raw: cleaned, directory, anchored, regex: globToRegex(cleaned, anchored) };
+    });
+}
+function globToRegex(pattern, anchored) {
+    let out = "";
+    for (let i = 0; i < pattern.length; i += 1) {
+        const ch = pattern[i];
+        if (ch === "*") {
+            if (pattern[i + 1] === "*") {
+                out += ".*";
+                i += 1;
+                if (pattern[i + 1] === "/")
+                    i += 1;
+            }
+            else {
+                out += "[^/]*";
+            }
+        }
+        else if (ch === "?") {
+            out += "[^/]";
+        }
+        else {
+            out += escapeRegex(ch);
+        }
+    }
+    // Gitignore semantics: an unanchored pattern without a slash matches at any
+    // depth; a pattern containing a slash is root-relative.
+    const prefix = anchored || pattern.includes("/") ? "^" : "(^|/)";
+    return new RegExp(`${prefix}${out}$`);
+}
+function escapeRegex(value) {
+    return value.replace(/[.+?^${}()|[\]\\]/g, "\\$&");
+}
+export function isIgnoredByRules(path, isDirectory, rules) {
+    for (const rule of rules.ignore) {
+        if (rule.regex.test(path)) {
+            if (rule.directory && !isDirectory)
+                continue;
+            return true;
+        }
+        // A directory rule also excludes everything under a matching directory.
+        const segments = path.split("/");
+        let prefix = "";
+        for (let i = 0; i < segments.length - 1; i += 1) {
+            prefix = prefix ? `${prefix}/${segments[i]}` : segments[i];
+            if (rule.regex.test(prefix))
+                return true;
+        }
+    }
+    return false;
+}
+/**
+ * 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 function isTrackedByCurrentRules(path, rules) {
+    if (path === "summer-cloud.json")
+        return false;
+    if (isHardExcludedPath(path))
+        return false;
+    if (isIgnoredByRules(path, false, rules))
+        return false;
+    return true;
+}

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

@@ -0,0 +1,21 @@
+import type { SyncOptions, SyncResult } from "./types.js";
+/** Jittered 409 backoff schedule. Exported so tests can shrink the delays. */
+export declare const CAS_BACKOFF_MS: number[];
+type Face = "cli" | "mcp" | "engine";
+export interface SyncRunOptions extends SyncOptions {
+    face?: Face;
+}
+export declare function cloudInit(options?: SyncRunOptions): Promise<SyncResult>;
+export declare function cloudStatus(options?: SyncRunOptions): Promise<SyncResult>;
+export declare function cloudPush(options?: SyncRunOptions): Promise<SyncResult>;
+export declare function cloudPull(options?: SyncRunOptions): Promise<SyncResult>;
+export declare function cloudConflicts(options?: SyncRunOptions & {
+    restorePath?: string;
+    set?: string;
+}): Promise<SyncResult>;
+export declare function cloudRestore(options?: SyncRunOptions & {
+    version?: number;
+    checkpoint?: string;
+}): Promise<SyncResult>;
+export declare function cloudCheckpoints(options?: SyncRunOptions): Promise<SyncResult>;
+export {};