@symbols-cli/cli 0.0.1

package/dist/sync/diff.js

@@ -0,0 +1,172 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+/**
+ * The whole decision, in one place.
+ *
+ * Deliberately pure: no I/O, no clock, no filesystem. That is what makes the
+ * table exhaustively testable, and every row below has a test.
+ */
+export function decide(s) {
+    const { server, local, base } = s;
+    // ── 1. The loop breaker. Content equality ends it, in BOTH directions. ─────
+    //
+    // Ported from `writeback_one` (odin_notebook_writeback.rs:1603-1605), where it
+    // exists because a push that echoes back as a pull that pushes again is the
+    // runaway-loop class. Note this fires even when B disagrees with both: if the
+    // two sides hold identical bytes there is nothing to transfer, and the only
+    // repair needed is to advance B.
+    if (server === local) {
+        // Note both sides may still disagree with B (e.g. the same edit was made
+        // twice, or a crash lost the confirm). There is nothing to TRANSFER, so the
+        // action is `none` either way — the caller advances B to this hash on `none`,
+        // which is the repair. Returning a distinct action for that would put a
+        // second decision point in a table whose whole value is being the only one.
+        return { kind: "none" };
+    }
+    // ── 2. Never synced (B absent) and present on both sides, differently. ────
+    //
+    // This is NOT a conflict to auto-resolve. It is the first-contact case: a
+    // project materialized over an existing directory, or a ledger that was
+    // deleted. There is no evidence about which side is newer, so freezing is the
+    // only non-destructive answer.
+    if (base === null && server !== null && local !== null) {
+        return {
+            kind: "conflict",
+            reason: "both sides have content and there is no common ancestor",
+        };
+    }
+    // ── 3. One side is unchanged since the base — the simple, safe cases. ─────
+    // Local matches the base => the local side did not change => take the server's.
+    if (local === base) {
+        if (server === null) {
+            return { kind: "pull-delete", reason: "deleted on the server; unchanged locally" };
+        }
+        return { kind: "pull", reason: "changed on the server; unchanged locally" };
+    }
+    // Server matches the base => the server did not change => send ours.
+    if (server === base) {
+        if (local === null) {
+            return { kind: "push-delete", reason: "deleted locally; unchanged on the server" };
+        }
+        return { kind: "push", reason: "changed locally; unchanged on the server" };
+    }
+    // ── 4. All three differ. Both sides moved. ────────────────────────────────
+    // A delete on one side against an EDIT on the other is the case where LWW is
+    // most destructive, and it is not a conflict we can represent as a file pair —
+    // there is nothing to write beside. Keep the content, always: a delete is
+    // cheap to redo and an edit is not.
+    if (server === null) {
+        return {
+            kind: "conflict",
+            reason: "deleted on the server but edited locally — keeping the local file",
+        };
+    }
+    if (local === null) {
+        return {
+            kind: "conflict",
+            reason: "deleted locally but edited on the server — restoring the server copy",
+        };
+    }
+    return { kind: "conflict", reason: "edited on both sides since the last sync" };
+}
+/**
+ * May the ledger base advance to this hash?
+ *
+ * Both subtleties from the header, in one testable function. The caller must not
+ * write B unless this returns a hash.
+ *
+ * Returns the hash to store, or `null` meaning "leave B alone and re-diff next
+ * cycle" — which is always safe, because a stale B produces at worst a redundant
+ * transfer, while an over-eager B produces silent loss.
+ */
+export function baseAfter(i) {
+    // Subtlety 1: only the far side's acknowledgement counts.
+    if (!i.confirmed)
+        return "hold";
+    // Subtlety 2: the file moved under us while the request was in flight. The
+    // diff we acted on described content that is no longer there.
+    if (i.hashAfter !== i.hashAtDecision)
+        return "hold";
+    return i.hashAtDecision;
+}
+/**
+ * The same question, for a PUSH — and the answer differs.
+ *
+ * ⚠ `baseAfter` above is the PULL rule, and applying it to a push produces a
+ * SPURIOUS CONFLICT. Walk it: base `v0`, we push `v1`, the file becomes `v2`
+ * while the PATCH is in flight. `baseAfter` holds, so `B` stays `v0`. The next
+ * sweep sees `S=v1, L=v2, B=v0` — all three differ — and reports a conflict,
+ * writing a sidecar and freezing a path where NOTHING was actually in conflict:
+ * the server's `v1` is the copy we sent it a second ago.
+ *
+ * The plan's verification line says the outcome must be *"re-pushed next
+ * cycle"*, and it is right. The two functions differ because they answer
+ * different questions:
+ *
+ *   pull  — "is the LOCAL file now the bytes I wrote?"  A partially-written file
+ *           whose hash we recorded as the base would be pushed over the good
+ *           server copy on the next sweep. That is why it holds.
+ *   push  — "does the SERVER now hold the bytes I sent?"  Its answer does not
+ *           depend on what the local file did afterwards. Recording it gives
+ *           `S=v1, L=v2, B=v1` next sweep -> a plain `push` of the newer edit.
+ *
+ * The mid-flight edit is never lost either way; the difference is whether the
+ * user is asked to resolve a merge that does not exist.
+ */
+export function baseAfterPush(i) {
+    if (!i.confirmed)
+        return "hold";
+    return i.hashAtDecision;
+}
+/**
+ * Guard 2 of the four the container never needed.
+ *
+ * `rm -rf`, a bad `git clean`, and a real cleanup are indistinguishable from
+ * here. On a container the workspace was ours and a mass delete meant one thing;
+ * on a laptop it is far more likely to be an accident, an unplugged drive, or a
+ * mistyped command.
+ *
+ * ⚠ This is a BACKSTOP, not the primary protection, and the plan is explicit
+ * about why: the >20 threshold is blind to a server-side notebook 404, which
+ * reads naively as "all files missing". That case is handled upstream by
+ * freezing the project offline (F4), and must never reach here.
+ */
+export function deleteGuard(i) {
+    if (i.deletions === 0)
+        return { allowed: true };
+    if (i.confirmed)
+        return { allowed: true };
+    const fraction = i.totalTracked > 0 ? i.deletions / i.totalTracked : 1;
+    if (i.deletions > 20) {
+        return {
+            allowed: false,
+            reason: `${i.deletions} deletions exceeds the 20-file limit — re-run with \`symbols sync --confirm-deletes\` if this is intended`,
+        };
+    }
+    if (fraction > 0.25) {
+        return {
+            allowed: false,
+            reason: `${i.deletions} of ${i.totalTracked} tracked files (${Math.round(fraction * 100)}%) would be deleted — re-run with \`symbols sync --confirm-deletes\` if this is intended`,
+        };
+    }
+    return { allowed: true };
+}
+/**
+ * Where a conflicting server copy is written, beside the local file.
+ *
+ * Never overwrites the user's file, and the name says which side it came from —
+ * `strategy.py` stays theirs, `strategy.server.py` is the other one. The
+ * extension is preserved so an editor still highlights it.
+ */
+export function conflictSidecarPath(rel) {
+    const slash = rel.lastIndexOf("/");
+    const dir = slash === -1 ? "" : rel.slice(0, slash + 1);
+    const base = rel.slice(slash + 1);
+    const dot = base.lastIndexOf(".");
+    // A leading dot is the whole name (`.env`), not an extension.
+    if (dot <= 0)
+        return `${dir}${base}.server`;
+    return `${dir}${base.slice(0, dot)}.server${base.slice(dot)}`;
+}

package/dist/sync/ledger.js

@@ -0,0 +1,319 @@
+// Copyright (c) 2025 Symbols LLC. All rights reserved.
+//
+// This source code is proprietary and confidential. Unauthorized copying,
+// distribution, modification, or use of this file, via any medium, is strictly prohibited.
+// The sync ledger — SQLite at `~/.symbols/state.db`.
+//
+// This file exists to hold ONE value durably: **B**, the last state both sides
+// confirmed for each path. Without a durable B the three-way table degrades to a
+// two-way compare, which cannot distinguish "the server changed" from "I
+// changed", and every implementation that tries collapses to last-writer-wins.
+// On a laptop, where "offline three days" is normal, that silently eats work.
+//
+// Why SQLite and not a JSON file:
+//
+//   * **Crash atomicity.** A JSON manifest rewritten on every settle is a
+//     truncated-file bug waiting for a kill -9 mid-write, and a truncated B is
+//     worse than a missing one — the diff would treat a partial file's paths as
+//     never-synced and re-conflict them.
+//   * **Read cost.** Reconcile runs every 60s over potentially thousands of
+//     paths; it needs point lookups, not a full parse.
+//   * `tracked_tickers.json` in R2 is this project's own worked example of the
+//     failure: a one-object read-modify-write that wiped 247 entries down to 14.
+//
+// ⚠ THE INODE BINDING IS A SAFETY CONTROL, NOT BOOKKEEPING. `project.json` is
+// agent-writable and Finder-copyable. Duplicating a project directory gives two
+// watchers on one notebook; editing `notebook_id` retargets sync at a different
+// notebook. So the ledger binds `notebook_id <-> (realpath, inode)` and
+// **freezes on ambiguity rather than guessing** — the plan is explicit that
+// guessing here is how one project's content lands in another.
+import Database from "better-sqlite3";
+import { promises as fs } from "node:fs";
+import { homedir } from "node:os";
+import { join, dirname } from "node:path";
+const SCHEMA = `
+CREATE TABLE IF NOT EXISTS meta (
+  key   TEXT PRIMARY KEY,
+  value TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS project (
+  id            TEXT PRIMARY KEY,
+  notebook_id   TEXT NOT NULL UNIQUE,
+  name          TEXT NOT NULL,
+  dirname       TEXT NOT NULL,
+  root          TEXT NOT NULL,
+  inode         INTEGER,
+  device_no     INTEGER,
+  frozen_reason TEXT
+);
+
+CREATE TABLE IF NOT EXISTS file (
+  project_id    TEXT NOT NULL,
+  path          TEXT NOT NULL,
+  base_hash     TEXT,
+  file_id       TEXT,
+  size          INTEGER,
+  mtime_ms      REAL,
+  local_hash    TEXT,
+  frozen_reason TEXT,
+  updated_at    INTEGER NOT NULL,
+  PRIMARY KEY (project_id, path)
+);
+
+-- The path a DELETE was confirmed for. Kept rather than dropping the row,
+-- because "no row" and "confirmed deleted" are different states: the first
+-- re-pulls the file, the second does not.
+CREATE TABLE IF NOT EXISTS tombstone (
+  project_id TEXT NOT NULL,
+  path       TEXT NOT NULL,
+  deleted_at INTEGER NOT NULL,
+  PRIMARY KEY (project_id, path)
+);
+
+-- Work that must survive a restart: a push whose response never arrived is
+-- retried, not lost.
+CREATE TABLE IF NOT EXISTS queue (
+  id         INTEGER PRIMARY KEY AUTOINCREMENT,
+  project_id TEXT NOT NULL,
+  path       TEXT NOT NULL,
+  op         TEXT NOT NULL,
+  attempts   INTEGER NOT NULL DEFAULT 0,
+  last_error TEXT,
+  created_at INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS file_by_project ON file (project_id);
+CREATE INDEX IF NOT EXISTS queue_by_project ON queue (project_id);
+`;
+/** Bumped only for a migration; `meta.schema_version` is checked on open. */
+const SCHEMA_VERSION = 1;
+export function statePath() {
+    return join(process.env["SYMBOLS_HOME"] ?? join(homedir(), ".symbols"), "state.db");
+}
+export class Ledger {
+    db;
+    constructor(db) {
+        this.db = db;
+    }
+    static async open(path = statePath()) {
+        await fs.mkdir(dirname(path), { recursive: true, mode: 0o700 });
+        const db = new Database(path);
+        // WAL so a reader (`symbols status`) never blocks the watcher, and so a
+        // crash mid-write rolls back to the last commit rather than corrupting.
+        db.pragma("journal_mode = WAL");
+        // NORMAL rather than FULL: a lost transaction on power failure costs one
+        // re-sync cycle, which the reconcile sweep repairs anyway. FULL would fsync
+        // on every settle of a 5,000-file project.
+        db.pragma("synchronous = NORMAL");
+        db.pragma("foreign_keys = ON");
+        db.exec(SCHEMA);
+        const ledger = new Ledger(db);
+        const existing = ledger.meta("schema_version");
+        if (existing === null) {
+            ledger.setMeta("schema_version", String(SCHEMA_VERSION));
+        }
+        else if (Number(existing) > SCHEMA_VERSION) {
+            // A newer CLI wrote this file. Refuse rather than silently misread it —
+            // reading a future schema with today's queries is how a base gets treated
+            // as absent, which re-conflicts every path in the account.
+            db.close();
+            throw new Error(`~/.symbols/state.db was written by a newer Symbols CLI (schema ${existing} > ${SCHEMA_VERSION}). ` +
+                `Upgrade with \`npm i -g @symbols-cli/cli\`.`);
+        }
+        return ledger;
+    }
+    close() {
+        this.db.close();
+    }
+    // ── meta ───────────────────────────────────────────────────────────────────
+    meta(key) {
+        const row = this.db.prepare("SELECT value FROM meta WHERE key = ?").get(key);
+        return row?.value ?? null;
+    }
+    setMeta(key, value) {
+        this.db
+            .prepare("INSERT INTO meta (key, value) VALUES (?, ?) ON CONFLICT(key) DO UPDATE SET value = excluded.value")
+            .run(key, value);
+    }
+    // ── projects ───────────────────────────────────────────────────────────────
+    /**
+     * Bind a notebook to a directory, or refuse.
+     *
+     * ⚠ THE FREEZE-ON-AMBIGUITY RULE. Three ways this goes wrong, all of them
+     * reachable without malice:
+     *
+     *   * The user duplicates the folder in Finder. Two directories now claim one
+     *     `notebook_id`; syncing both means each overwrites the other's pushes.
+     *   * The agent edits `project.json` and retargets it at a different notebook.
+     *   * The user renames or moves the directory. That one is BENIGN and must be
+     *     followed, which is why the inode — not the path — is the identity.
+     *
+     * Returns the bound project, or throws. It never guesses.
+     */
+    bindProject(p) {
+        const existing = this.db
+            .prepare("SELECT * FROM project WHERE notebook_id = ?")
+            .get(p.notebookId);
+        if (existing) {
+            const sameInode = p.inode !== null && existing["inode"] === p.inode && existing["device_no"] === p.deviceNo;
+            const samePath = existing["root"] === p.root;
+            if (!sameInode && !samePath) {
+                // Neither the inode nor the path matches: this is a second directory
+                // claiming the same notebook. Freeze BOTH rather than pick.
+                const reason = `notebook ${p.notebookId} is already bound to ${String(existing["root"])}; ` +
+                    `${p.root} also claims it. Sync is frozen for this project — remove or ` +
+                    `detach one copy (\`symbols project detach\`).`;
+                this.freezeProject(String(existing["id"]), reason);
+                throw new Error(reason);
+            }
+            // Same inode, different path = a rename or move. Follow it.
+            this.db
+                .prepare("UPDATE project SET root = ?, name = ?, dirname = ?, inode = ?, device_no = ? WHERE id = ?")
+                .run(p.root, p.name, p.dirname, p.inode, p.deviceNo, existing["id"]);
+            return this.project(p.notebookId);
+        }
+        this.db
+            .prepare("INSERT INTO project (id, notebook_id, name, dirname, root, inode, device_no) VALUES (?,?,?,?,?,?,?)")
+            .run(p.id, p.notebookId, p.name, p.dirname, p.root, p.inode, p.deviceNo);
+        return this.project(p.notebookId);
+    }
+    project(notebookId) {
+        const r = this.db.prepare("SELECT * FROM project WHERE notebook_id = ?").get(notebookId);
+        return r ? toProject(r) : null;
+    }
+    projects() {
+        return this.db.prepare("SELECT * FROM project ORDER BY name").all().map(toProject);
+    }
+    freezeProject(id, reason) {
+        this.db.prepare("UPDATE project SET frozen_reason = ? WHERE id = ?").run(reason, id);
+    }
+    unfreezeProject(id) {
+        this.db.prepare("UPDATE project SET frozen_reason = NULL WHERE id = ?").run(id);
+    }
+    // ── files ──────────────────────────────────────────────────────────────────
+    file(projectId, path) {
+        const r = this.db
+            .prepare("SELECT * FROM file WHERE project_id = ? AND path = ?")
+            .get(projectId, path);
+        return r ? toFile(r) : null;
+    }
+    files(projectId) {
+        return this.db.prepare("SELECT * FROM file WHERE project_id = ?").all(projectId).map(toFile);
+    }
+    /**
+     * Record a CONFIRMED state.
+     *
+     * ⚠ Call this ONLY after `baseAfter()` in `diff.ts` has returned a hash. This
+     * function does not re-check the two subtleties (far-side confirmation, and L
+     * unchanged mid-flight) because putting that decision in two places is how the
+     * two copies drift. `diff.ts` owns it.
+     */
+    confirm(row) {
+        this.db
+            .prepare(`INSERT INTO file (project_id, path, base_hash, file_id, size, mtime_ms, local_hash, updated_at)
+         VALUES (@projectId, @path, @base, @fileId, @size, @mtimeMs, @localHash, @now)
+         ON CONFLICT(project_id, path) DO UPDATE SET
+           base_hash  = excluded.base_hash,
+           file_id    = COALESCE(excluded.file_id, file.file_id),
+           size       = excluded.size,
+           mtime_ms   = excluded.mtime_ms,
+           local_hash = excluded.local_hash,
+           updated_at = excluded.updated_at`)
+            .run({
+            projectId: row.projectId,
+            path: row.path,
+            base: row.base,
+            fileId: row.fileId ?? null,
+            size: row.size ?? null,
+            mtimeMs: row.mtimeMs ?? null,
+            localHash: row.localHash ?? null,
+            now: Date.now(),
+        });
+        // A path that comes back is no longer deleted.
+        this.db.prepare("DELETE FROM tombstone WHERE project_id = ? AND path = ?").run(row.projectId, row.path);
+    }
+    freezeFile(projectId, path, reason) {
+        this.db
+            .prepare(`INSERT INTO file (project_id, path, frozen_reason, updated_at) VALUES (?,?,?,?)
+         ON CONFLICT(project_id, path) DO UPDATE SET frozen_reason = excluded.frozen_reason,
+                                                     updated_at    = excluded.updated_at`)
+            .run(projectId, path, reason, Date.now());
+    }
+    unfreezeFile(projectId, path) {
+        this.db
+            .prepare("UPDATE file SET frozen_reason = NULL WHERE project_id = ? AND path = ?")
+            .run(projectId, path);
+    }
+    frozen(projectId) {
+        return this.db
+            .prepare("SELECT * FROM file WHERE project_id = ? AND frozen_reason IS NOT NULL")
+            .all(projectId).map(toFile);
+    }
+    /**
+     * Record a confirmed delete.
+     *
+     * The row is REPLACED BY A TOMBSTONE rather than simply dropped, because "no
+     * row" and "confirmed deleted" produce different diffs: the first has `B =
+     * null`, which reads as never-synced and re-pulls the file the user just
+     * deleted.
+     */
+    tombstone(projectId, path) {
+        const tx = this.db.transaction(() => {
+            this.db.prepare("DELETE FROM file WHERE project_id = ? AND path = ?").run(projectId, path);
+            this.db
+                .prepare("INSERT INTO tombstone (project_id, path, deleted_at) VALUES (?,?,?) ON CONFLICT DO NOTHING")
+                .run(projectId, path, Date.now());
+        });
+        tx();
+    }
+    isTombstoned(projectId, path) {
+        return (this.db
+            .prepare("SELECT 1 FROM tombstone WHERE project_id = ? AND path = ?")
+            .get(projectId, path) !== undefined);
+    }
+    // ── queue ──────────────────────────────────────────────────────────────────
+    enqueue(projectId, path, op) {
+        this.db
+            .prepare("INSERT INTO queue (project_id, path, op, created_at) VALUES (?,?,?,?)")
+            .run(projectId, path, op, Date.now());
+    }
+    pending(projectId) {
+        return this.db
+            .prepare("SELECT id, path, op, attempts FROM queue WHERE project_id = ? ORDER BY id")
+            .all(projectId);
+    }
+    dequeue(id) {
+        this.db.prepare("DELETE FROM queue WHERE id = ?").run(id);
+    }
+    failed(id, error) {
+        this.db
+            .prepare("UPDATE queue SET attempts = attempts + 1, last_error = ? WHERE id = ?")
+            .run(error, id);
+    }
+}
+function toProject(r) {
+    return {
+        id: String(r["id"]),
+        notebookId: String(r["notebook_id"]),
+        name: String(r["name"]),
+        dirname: String(r["dirname"]),
+        root: String(r["root"]),
+        inode: r["inode"] === null ? null : Number(r["inode"]),
+        deviceNo: r["device_no"] === null ? null : Number(r["device_no"]),
+        frozenReason: r["frozen_reason"] ?? null,
+    };
+}
+function toFile(r) {
+    return {
+        projectId: String(r["project_id"]),
+        path: String(r["path"]),
+        base: r["base_hash"] ?? null,
+        fileId: r["file_id"] ?? null,
+        size: r["size"] === null ? null : Number(r["size"]),
+        mtimeMs: r["mtime_ms"] === null ? null : Number(r["mtime_ms"]),
+        localHash: r["local_hash"] ?? null,
+        frozenReason: r["frozen_reason"] ?? null,
+        updatedAt: Number(r["updated_at"] ?? 0),
+    };
+}