@catalyst-cloud/sdk 0.1.1 → 0.2.1

package/dist/replica/engine.js

@@ -0,0 +1,216 @@
+// @catalyst-cloud/sdk/node — the portable sqlite ENGINE seam + the injected driver factories.
+//
+// CatalystReplica never statically imports a sqlite driver: that is how it avoids hard-depping one.
+// It defines one tiny portable `ReplicaEngine` — the union of replicate's `ReplicaWriteDb` (run/get),
+// read-model's `SqlExecutor` (all), and schema's `MigrationDb` (exec/query) primitives, plus a
+// per-engine `toBindable` (wire JSON → engine-bindable) and `transaction`/`close`. CatalystReplica
+// adapts THIS one object into the three ports it needs.
+//
+// Drivers are INJECTED, not imported. The SDK ships three factory adapters, each dynamic-import()ing
+// its driver only when called:
+//   • bunSqliteEngine(dbPath)        — `await import("bun:sqlite")` (runtime builtin → never in package.json)
+//   • nodeSqliteEngine(dbPath)       — `await import("node:sqlite")` { DatabaseSync } (Node >=22.5, builtin)
+//   • betterSqlite3Engine(driver, …) — the consumer passes `import Database from "better-sqlite3"`
+//     (an OPTIONAL peer, never statically imported here).
+// Any other driver (D1, sql.js, …) is supported by passing a custom `ReplicaEngine`.
+// Load RUNTIME-BUILTIN drivers (`bun:sqlite` / `node:sqlite`) via `createRequire`, NOT a literal
+// `import("…")`. Vite/vitest and esbuild rewrite (and break) a literal dynamic import of a builtin —
+// they strip the `node:`/`bun:` prefix and fail to resolve a bare `sqlite`; and a `new Function`
+// import throws "dynamic import callback was not specified" under node ESM. `require` of a builtin is
+// untouched by the bundler and resolves natively on both node and Bun. This keeps the drivers OUT of
+// package.json (they are platform builtins) and loaded only when a factory is called.
+import { createRequire } from "node:module";
+const requireBuiltin = createRequire(import.meta.url);
+/** Require a RUNTIME-BUILTIN driver module; the type is supplied by the caller via `typeof import(...)`. */
+function importBuiltin(specifier) {
+    return Promise.resolve(requireBuiltin(specifier));
+}
+/** Coerce a wire JSON value to a node/bun-bindable scalar. Booleans → 0/1, blobs → Uint8Array, nested
+ *  object/array → JSON text (DO rows are flat scalars; this just keeps one odd field from wedging sync). */
+function toBindable(value) {
+    if (value === null || value === undefined)
+        return null;
+    if (typeof value === "boolean")
+        return value ? 1 : 0;
+    if (typeof value === "string" || typeof value === "number" || typeof value === "bigint")
+        return value;
+    if (value instanceof Uint8Array)
+        return value;
+    if (value instanceof ArrayBuffer)
+        return new Uint8Array(value);
+    return JSON.stringify(value);
+}
+/** Fold a driver into the portable engine. `all`/`run`/`get` re-prepare per call (bounded read path,
+ *  and applyDelta's SQL varies per row anyway, so statement caching would not help). */
+function makeEngine(driver) {
+    return {
+        handle: driver.handle,
+        exec: (sql) => driver.exec(sql),
+        all: (sql, ...bindings) => driver.prepare(sql).all(...bindings),
+        run: (sql, ...bindings) => driver.prepare(sql).run(...bindings),
+        get: (sql, ...bindings) => driver.prepare(sql).get(...bindings),
+        transaction: (fn) => driver.transaction(fn),
+        toBindable,
+        close: () => driver.close(),
+    };
+}
+/**
+ * `bun:sqlite` engine. `db.query(sql)` prepares; `.run().changes` is the write count; WAL keeps
+ * concurrent readers non-blocking. `bun:sqlite` is a Bun runtime builtin → dynamic-imported, never a
+ * package.json dependency.
+ *
+ * The WRITER opens read-write + WAL. The READER (`readonly`) opens `{ readonly: true }` and sets
+ * `busy_timeout = 250` instead of WAL — exactly how CTL's replica-read.mjs opens the same file: under
+ * the single-writer/many-reader topology (ADR-0008) a checkpoint can briefly hold the lock, so a
+ * reader waits a beat rather than failing. A readonly handle runs NO migrations and rejects writes at
+ * the sqlite layer.
+ */
+async function openBun(dbPath, readonly) {
+    const { Database } = await importBuiltin("bun:sqlite");
+    const db = readonly ? new Database(dbPath, { readonly: true }) : new Database(dbPath);
+    try {
+        db.run(readonly ? "PRAGMA busy_timeout = 250" : "PRAGMA journal_mode = WAL");
+    }
+    catch {
+        // :memory: rejects WAL on some builds; busy_timeout is harmless either way.
+    }
+    return makeEngine({
+        handle: db,
+        exec: (sql) => db.exec(sql),
+        prepare: (sql) => {
+            const st = db.query(sql);
+            return {
+                all: (...b) => st.all(...b),
+                get: (...b) => (st.get(...b) ?? undefined),
+                run: (...b) => st.run(...b).changes,
+            };
+        },
+        transaction: (fn) => db.transaction(fn)(),
+        close: () => db.close(),
+    });
+}
+export function bunSqliteEngine(dbPath) {
+    return openBun(dbPath, false);
+}
+/** Read-only `bun:sqlite` engine (`{ readonly: true }` + `busy_timeout`). See {@link openBun}. */
+export function bunSqliteReadonlyEngine(dbPath) {
+    return openBun(dbPath, true);
+}
+/**
+ * `node:sqlite` engine (Node >=22.5; may need `--experimental-sqlite` on some 22.x). `DatabaseSync`
+ * has no `.transaction()` helper, so we wrap BEGIN/COMMIT/ROLLBACK. Also a runtime builtin → never a
+ * package.json dependency. The `readonly` variant opens `{ readOnly: true }` (node:sqlite's spelling)
+ * + `busy_timeout`; see {@link openBun} for the read-only rationale.
+ */
+async function openNode(dbPath, readonly) {
+    const { DatabaseSync } = await importBuiltin("node:sqlite");
+    const db = readonly ? new DatabaseSync(dbPath, { readOnly: true }) : new DatabaseSync(dbPath);
+    try {
+        db.exec(readonly ? "PRAGMA busy_timeout = 250" : "PRAGMA journal_mode = WAL");
+    }
+    catch {
+        // :memory: cannot WAL — harmless; busy_timeout is allowed on a readonly handle.
+    }
+    return makeEngine({
+        handle: db,
+        exec: (sql) => db.exec(sql),
+        prepare: (sql) => {
+            const st = db.prepare(sql);
+            return {
+                all: (...b) => st.all(...b),
+                get: (...b) => (st.get(...b) ?? undefined),
+                run: (...b) => Number(st.run(...b).changes),
+            };
+        },
+        transaction: (fn) => {
+            db.exec("BEGIN");
+            try {
+                const out = fn();
+                db.exec("COMMIT");
+                return out;
+            }
+            catch (err) {
+                db.exec("ROLLBACK");
+                throw err;
+            }
+        },
+        close: () => db.close(),
+    });
+}
+export function nodeSqliteEngine(dbPath) {
+    return openNode(dbPath, false);
+}
+/** Read-only `node:sqlite` engine (`{ readOnly: true }` + `busy_timeout`). See {@link openNode}. */
+export function nodeSqliteReadonlyEngine(dbPath) {
+    return openNode(dbPath, true);
+}
+/**
+ * `better-sqlite3` engine. The consumer passes the driver constructor (`import Database from
+ * "better-sqlite3"`) so the SDK never statically imports it — it stays an OPTIONAL peer the consumer's
+ * bundler resolves. Synchronous (the driver is already loaded), so no dynamic import here. The
+ * `readonly` variant opens `{ readonly: true }` + `busy_timeout`; see {@link openBun}.
+ */
+function openBetter(driver, dbPath, readonly) {
+    const db = readonly ? new driver(dbPath, { readonly: true }) : new driver(dbPath);
+    try {
+        db.pragma(readonly ? "busy_timeout = 250" : "journal_mode = WAL");
+    }
+    catch {
+        // :memory: cannot WAL — harmless; busy_timeout is allowed on a readonly handle.
+    }
+    return makeEngine({
+        handle: db,
+        exec: (sql) => db.exec(sql),
+        prepare: (sql) => {
+            const st = db.prepare(sql);
+            return {
+                all: (...b) => st.all(...b),
+                get: (...b) => (st.get(...b) ?? undefined),
+                run: (...b) => Number(st.run(...b).changes),
+            };
+        },
+        transaction: (fn) => db.transaction(fn)(),
+        close: () => db.close(),
+    });
+}
+export function betterSqlite3Engine(driver, dbPath) {
+    return openBetter(driver, dbPath, false);
+}
+/** Read-only `better-sqlite3` engine (`{ readonly: true }` + `busy_timeout`). See {@link openBetter}. */
+export function betterSqlite3ReadonlyEngine(driver, dbPath) {
+    return openBetter(driver, dbPath, true);
+}
+/**
+ * Auto-detect the default engine when `opts.engine` is omitted: Bun → `bunSqliteEngine`; else
+ * `node:sqlite` if available → `nodeSqliteEngine`; else throw a clear "pass opts.engine" error rather
+ * than pick an engine that resolves but breaks on first write.
+ */
+export async function autoDetectEngine(dbPath) {
+    if (typeof globalThis.Bun !== "undefined") {
+        return bunSqliteEngine(dbPath);
+    }
+    try {
+        return await nodeSqliteEngine(dbPath);
+    }
+    catch (err) {
+        throw new Error("CatalystReplica: no sqlite engine available — pass opts.engine. " +
+            "Auto-detect needs Bun (bun:sqlite) or Node >=22.5 (node:sqlite). " +
+            `Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+/** READ-ONLY counterpart of {@link autoDetectEngine}: Bun → `bunSqliteReadonlyEngine`; else
+ *  `nodeSqliteReadonlyEngine`. Used by `CatalystReplica.openReadOnly` when no engine is injected. */
+export async function autoDetectReadonlyEngine(dbPath) {
+    if (typeof globalThis.Bun !== "undefined") {
+        return bunSqliteReadonlyEngine(dbPath);
+    }
+    try {
+        return await nodeSqliteReadonlyEngine(dbPath);
+    }
+    catch (err) {
+        throw new Error("CatalystReplica: no read-only sqlite engine available — pass opts.engine. " +
+            "Auto-detect needs Bun (bun:sqlite) or Node >=22.5 (node:sqlite). " +
+            `Underlying error: ${err instanceof Error ? err.message : String(err)}`);
+    }
+}
+//# sourceMappingURL=engine.js.map

package/dist/replica/engine.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"engine.js","sourceRoot":"","sources":["../../src/replica/engine.ts"],"names":[],"mappings":"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"}

package/dist/replica/writer-lock.d.ts

@@ -0,0 +1,34 @@
+import type { LogLevel } from "../live-sync-client.js";
+/** Config for the single-writer guard. Passed as `CatalystReplicaOptions.writerGuard`. */
+export interface WriterGuardOptions {
+    /** Disable the guard entirely (claim nothing). Default false — the guard is ON for file replicas. */
+    disabled?: boolean;
+    /** Steal an existing LIVE lock instead of throwing (the configurable override). Default false. */
+    override?: boolean;
+    /** A lock with no heartbeat newer than this many ms is treated as abandoned + reclaimed. Default 15000. */
+    staleMs?: number;
+    /** How often the owning writer rewrites its heartbeat. Default max(1000, staleMs/3). */
+    heartbeatMs?: number;
+    /**
+     * A stable identity for THIS logical (singleton) writer — e.g. `<host>-<tenant>`. A relaunch whose
+     * ownerKey matches an existing lock with a DIFFERENT pid reclaims it IMMEDIATELY (its own crashed
+     * predecessor), bypassing the staleMs/pid-liveness gate. Only set this when you guarantee a single
+     * writer per ownerKey per dbPath; the default (unset) keeps full two-writer protection.
+     */
+    ownerKey?: string;
+}
+/** A claimed writer lock. `release()` stops the heartbeat and removes the file if still ours. Idempotent. */
+export interface WriterLockHandle {
+    /** The sidecar lock file path (`dbPath + '.writer.lock'`). */
+    readonly path: string;
+    release(): void;
+}
+type Logger = (level: LogLevel, msg: string, extra?: unknown) => void;
+/**
+ * Best-effort claim sole ownership of `dbPath` for a writer. Returns a {@link WriterLockHandle} (or
+ * `null` when the guard is disabled or `dbPath` is in-memory). Throws a clear error when another LIVE
+ * writer already holds the lock and `override` is not set.
+ */
+export declare function claimWriterLock(dbPath: string, opts: WriterGuardOptions, log?: Logger): WriterLockHandle | null;
+export {};
+//# sourceMappingURL=writer-lock.d.ts.map

package/dist/replica/writer-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-lock.d.ts","sourceRoot":"","sources":["../../src/replica/writer-lock.ts"],"names":[],"mappings":"AAsBA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,wBAAwB,CAAC;AAEvD,0FAA0F;AAC1F,MAAM,WAAW,kBAAkB;IACjC,qGAAqG;IACrG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,kGAAkG;IAClG,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2GAA2G;IAC3G,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAED,6GAA6G;AAC7G,MAAM,WAAW,gBAAgB;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,OAAO,IAAI,IAAI,CAAC;CACjB;AAcD,KAAK,MAAM,GAAG,CAAC,KAAK,EAAE,QAAQ,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,KAAK,IAAI,CAAC;AA4BtE;;;;GAIG;AACH,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,kBAAkB,EACxB,GAAG,CAAC,EAAE,MAAM,GACX,gBAAgB,GAAG,IAAI,CAsFzB"}

package/dist/replica/writer-lock.js

@@ -0,0 +1,135 @@
+// @catalyst-cloud/sdk/node — the single-writer guard for a CatalystReplica writer (CTC-113).
+//
+// The managed replica is single-writer/many-reader (ADR-0008): ONE process owns the SQLite file and
+// applies the change feed; everyone else opens it READ-ONLY (`CatalystReplica.openReadOnly`). Two
+// concurrent WRITERS on the same file would race the cursor + truncate-and-reseed and silently
+// diverge. This guard makes that mistake LOUD: when a writer `start()`s it best-effort claims sole
+// ownership of `dbPath` via a sidecar lock file `dbPath + '.writer.lock'` carrying `{pid, owner,
+// heartbeat}`. A second live writer on the same path throws a clear error instead of corrupting the
+// replica.
+//
+// LIMITS — this is deliberately ADVISORY, not a hard OS lock:
+//   • It is cooperative: it only stops OTHER CatalystReplica writers. A raw `new Database(path)` from
+//     unrelated code is not blocked (use OS file locking / WAL for that).
+//   • Liveness has two signals. The HEARTBEAT (a timestamp rewritten on an interval) is the portable,
+//     cross-host signal — a lock older than `staleMs` with no heartbeat is treated as abandoned and
+//     reclaimed. The PID probe (`process.kill(pid,0)`) only means anything SAME-HOST; cross-host or
+//     when it can't probe, it conservatively assumes the holder is alive and relies on the heartbeat.
+//   • A hard `kill -9` can leave a stale lock until `staleMs` elapses; the next writer reclaims it.
+//   • `:memory:` (and `file::memory:`) replicas are per-connection, never shared, so the guard is a
+//     no-op for them.
+import * as fs from "node:fs";
+const DEFAULT_STALE_MS = 15_000;
+function readLock(lockPath) {
+    try {
+        const rec = JSON.parse(fs.readFileSync(lockPath, "utf8"));
+        if (rec && typeof rec.pid === "number" && typeof rec.heartbeat === "number")
+            return rec;
+        return null;
+    }
+    catch {
+        return null; // absent, partial write, or garbage → treat as no lock
+    }
+}
+/** SAME-HOST liveness probe. Returns true when it cannot tell (assume the holder is alive — the
+ *  heartbeat staleness check is the portable signal that ultimately reclaims a dead lock). */
+function pidAlive(pid) {
+    const proc = globalThis.process;
+    if (!proc?.kill || !pid)
+        return true;
+    try {
+        proc.kill(pid, 0); // signal 0 = existence check, never delivered
+        return true;
+    }
+    catch (err) {
+        if (err.code === "ESRCH")
+            return false; // no such process
+        return true; // EPERM: exists but owned by another user → alive
+    }
+}
+/**
+ * Best-effort claim sole ownership of `dbPath` for a writer. Returns a {@link WriterLockHandle} (or
+ * `null` when the guard is disabled or `dbPath` is in-memory). Throws a clear error when another LIVE
+ * writer already holds the lock and `override` is not set.
+ */
+export function claimWriterLock(dbPath, opts, log) {
+    if (opts.disabled)
+        return null;
+    if (!dbPath || dbPath === ":memory:" || dbPath.startsWith("file::memory:"))
+        return null;
+    const lockPath = `${dbPath}.writer.lock`;
+    const staleMs = opts.staleMs ?? DEFAULT_STALE_MS;
+    const heartbeatMs = opts.heartbeatMs ?? Math.max(1000, Math.floor(staleMs / 3));
+    const pid = globalThis.process?.pid ?? 0;
+    const owner = `${pid}-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+    const serialize = () => JSON.stringify({ pid, owner, heartbeat: Date.now(), ownerKey: opts.ownerKey });
+    const writeFresh = () => fs.writeFileSync(lockPath, serialize());
+    // Atomic exclusive create: wins the claim outright if no file exists.
+    let created = false;
+    try {
+        const fd = fs.openSync(lockPath, "wx");
+        fs.writeSync(fd, serialize());
+        fs.closeSync(fd);
+        created = true;
+    }
+    catch (err) {
+        if (err.code !== "EEXIST")
+            throw err;
+    }
+    if (!created) {
+        const existing = readLock(lockPath);
+        // FAST-RECLAIM: a relaunch of THIS logical writer (same ownerKey) but a DIFFERENT pid is our own
+        // crashed predecessor — reclaim it IMMEDIATELY, bypassing the staleMs/pid-liveness gate. This
+        // dodges the kill -9 + fast-relaunch window where a zombie/pid-reuse makes pidAlive() spuriously
+        // true and would otherwise block the relaunched writer for the full staleMs window.
+        if (opts.ownerKey != null && existing?.ownerKey === opts.ownerKey && existing.pid !== pid) {
+            log?.("info", `writer-lock: reclaiming own crashed predecessor (ownerKey match) at ${lockPath}`);
+            writeFresh();
+        }
+        else {
+            const held = existing != null && Date.now() - existing.heartbeat < staleMs && pidAlive(existing.pid);
+            if (held && !opts.override) {
+                throw new Error(`CatalystReplica: another writer owns this replica at ${dbPath} ` +
+                    `(pid=${existing.pid}, last heartbeat ${Date.now() - existing.heartbeat}ms ago). ` +
+                    `Only ONE writer may hold a replica file (ADR-0008 single-writer/many-reader); open it ` +
+                    `read-only with CatalystReplica.openReadOnly() instead. Pass writerGuard:{override:true} ` +
+                    `to take it over, or writerGuard:{disabled:true} to skip the check. NOTE: this guard is ` +
+                    `advisory (a sidecar ${lockPath}), not a hard OS lock.`);
+            }
+            log?.("warn", held
+                ? `writer-lock: overriding a live writer at ${lockPath} (writerGuard.override)`
+                : `writer-lock: reclaiming a stale/abandoned lock at ${lockPath}`);
+            writeFresh();
+        }
+    }
+    // Keep the lock fresh so peers see it's alive; unref so it never holds the event loop open.
+    const timer = setInterval(() => {
+        try {
+            writeFresh();
+        }
+        catch (err) {
+            log?.("warn", "writer-lock heartbeat failed", err);
+        }
+    }, heartbeatMs);
+    timer.unref?.();
+    let released = false;
+    return {
+        path: lockPath,
+        release() {
+            if (released)
+                return;
+            released = true;
+            clearInterval(timer);
+            const cur = readLock(lockPath);
+            if (cur && cur.owner === owner) {
+                try {
+                    fs.unlinkSync(lockPath);
+                }
+                catch {
+                    // already gone — fine
+                }
+            }
+        },
+    };
+}
+//# sourceMappingURL=writer-lock.js.map

package/dist/replica/writer-lock.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"writer-lock.js","sourceRoot":"","sources":["../../src/replica/writer-lock.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@catalyst-cloud/sdk",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Keep a live local copy of your Linear and GitHub project data — pushed in real time, without polling rate limits or webhook tunnels.",
   "license": "MIT",
   "author": "Coalesce Labs",
@@ -24,6 +24,11 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./node": {
+      "types": "./dist/node.d.ts",
+      "import": "./dist/node.js",
+      "default": "./dist/node.js"
     }
   },
   "files": [
@@ -51,5 +56,22 @@
   "devDependencies": {
     "typescript": "^5.6.3",
     "vitest": "^2.1.8"
+  },
+  "dependencies": {
+    "@catalyst-cloud/read-model": "^0.1.0",
+    "@catalyst-cloud/replicate": "^0.1.0",
+    "@catalyst-cloud/schema": "^0.1.0"
+  },
+  "peerDependencies": {
+    "@sqlite.org/sqlite-wasm": "*",
+    "better-sqlite3": "*"
+  },
+  "peerDependenciesMeta": {
+    "better-sqlite3": {
+      "optional": true
+    },
+    "@sqlite.org/sqlite-wasm": {
+      "optional": true
+    }
   }
 }