@bluewombat/persist-sqlite 0.1.0

package/README.md

@@ -0,0 +1,37 @@
+# persist-sqlite
+
+Persistence Port for WorkLedger: one SQLite file, `node:sqlite`. The ledger
+never imports this package. Glue does.
+
+```ts
+import { openWorkLedger } from "@bluewombat/work-ledger";
+import { openSqlitePersist } from "@bluewombat/persist-sqlite";
+
+const persist = await openSqlitePersist({ path: "/absolute/path/to/ledger.sqlite" });
+const ledger = openWorkLedger({ persist });
+```
+
+`path` must be absolute. The adapter creates the parent directory if missing.
+
+From a Project, name it instead and let Host load it:
+
+```json
+{ "persist": "@bluewombat/persist-sqlite" }
+```
+
+Host calls `openPersist({ ledgerRoot })`; the file is `<ledgerRoot>/ledger.sqlite`,
+beside Host's own Cursor and journal. Install the package next to mason.
+
+## Stack
+
+Repository stack — TypeScript, Node 24.20, Biome, `node:test`. See [docs/DEVELOPMENT.md](../../../docs/DEVELOPMENT.md).
+
+## Commands
+
+| Task      | Command          |
+| --------- | ---------------- |
+| Lint      | `npm run lint`   |
+| Format    | `npm run format` |
+| Typecheck | `npm run tsc`    |
+| Test      | `npm test`       |
+| Build     | `npm run build`  |

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { LEDGER_FILE, openPersist } from "./open-persist.js";
+export type { SqlitePersistOptions } from "./open-sqlite-persist.js";
+export { openSqlitePersist } from "./open-sqlite-persist.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAC7D,YAAY,EAAE,oBAAoB,EAAE,MAAM,0BAA0B,CAAC;AACrE,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { LEDGER_FILE, openPersist } from "./open-persist.js";
+export { openSqlitePersist } from "./open-sqlite-persist.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE7D,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC"}

package/dist/open-persist.d.ts

@@ -0,0 +1,12 @@
+import type { PersistencePort } from "@bluewombat/work-ledger";
+/** The one file the ledger lives in, under Host's ledger directory. */
+export declare const LEDGER_FILE = "ledger.sqlite";
+/**
+ * The face Host loads by name (`"persist": "@bluewombat/persist-sqlite"`):
+ * the ledger directory in, a Port out. Everything goes in `ledger.sqlite`
+ * there; Host's own files (Cursor, journal, lock) sit beside it untouched.
+ */
+export declare function openPersist(context: {
+    ledgerRoot: string;
+}): Promise<PersistencePort>;
+//# sourceMappingURL=open-persist.d.ts.map

package/dist/open-persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-persist.d.ts","sourceRoot":"","sources":["../src/open-persist.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D,uEAAuE;AACvE,eAAO,MAAM,WAAW,kBAAkB,CAAC;AAE3C;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,MAAM,CAAA;CAAE,GAAG,OAAO,CAAC,eAAe,CAAC,CAErF"}

package/dist/open-persist.js

@@ -0,0 +1,13 @@
+import { join } from "node:path";
+import { openSqlitePersist } from "./open-sqlite-persist.js";
+/** The one file the ledger lives in, under Host's ledger directory. */
+export const LEDGER_FILE = "ledger.sqlite";
+/**
+ * The face Host loads by name (`"persist": "@bluewombat/persist-sqlite"`):
+ * the ledger directory in, a Port out. Everything goes in `ledger.sqlite`
+ * there; Host's own files (Cursor, journal, lock) sit beside it untouched.
+ */
+export function openPersist(context) {
+    return openSqlitePersist({ path: join(context.ledgerRoot, LEDGER_FILE) });
+}
+//# sourceMappingURL=open-persist.js.map

package/dist/open-persist.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-persist.js","sourceRoot":"","sources":["../src/open-persist.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,iBAAiB,EAAE,MAAM,0BAA0B,CAAC;AAE7D,uEAAuE;AACvE,MAAM,CAAC,MAAM,WAAW,GAAG,eAAe,CAAC;AAE3C;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAA+B;IACzD,OAAO,iBAAiB,CAAC,EAAE,IAAI,EAAE,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,WAAW,CAAC,EAAE,CAAC,CAAC;AAC5E,CAAC"}

package/dist/open-sqlite-persist.d.ts

@@ -0,0 +1,10 @@
+import type { PersistencePort } from "@bluewombat/work-ledger";
+export type SqlitePersistOptions = {
+    path: string;
+};
+/**
+ * SQLite Persistence Port. One row per key. A transaction wraps each save.
+ * Does not know FeatureStandard transitions.
+ */
+export declare function openSqlitePersist(options: SqlitePersistOptions): Promise<PersistencePort>;
+//# sourceMappingURL=open-sqlite-persist.d.ts.map

package/dist/open-sqlite-persist.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"open-sqlite-persist.d.ts","sourceRoot":"","sources":["../src/open-sqlite-persist.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAGV,eAAe,EAEhB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAqCF;;;GAGG;AACH,wBAAsB,iBAAiB,CAAC,OAAO,EAAE,oBAAoB,GAAG,OAAO,CAAC,eAAe,CAAC,CAuD/F"}

package/dist/open-sqlite-persist.js

@@ -0,0 +1,93 @@
+import { mkdir } from "node:fs/promises";
+import { dirname, isAbsolute } from "node:path";
+import { DatabaseSync } from "node:sqlite";
+function isAggregate(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const record = value;
+    return (typeof record.state === "string" &&
+        record.intention !== null &&
+        typeof record.intention === "object");
+}
+function toSummary(aggregate) {
+    const summary = {
+        key: aggregate.intention.key,
+        project: aggregate.intention.project,
+        state: aggregate.state,
+        priority: aggregate.intention.priority,
+        received_at: aggregate.received_at,
+    };
+    if (aggregate.bail !== undefined) {
+        summary.bail_expires_at = aggregate.bail.expires_at;
+    }
+    return summary;
+}
+function parsePayload(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        return isAggregate(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/**
+ * SQLite Persistence Port. One row per key. A transaction wraps each save.
+ * Does not know FeatureStandard transitions.
+ */
+export async function openSqlitePersist(options) {
+    if (!isAbsolute(options.path)) {
+        throw new Error(`SQLite persist path must be an absolute file path, got "${options.path}".`);
+    }
+    await mkdir(dirname(options.path), { recursive: true });
+    const db = new DatabaseSync(options.path);
+    db.exec(`
+    CREATE TABLE IF NOT EXISTS features (
+      key TEXT PRIMARY KEY NOT NULL,
+      payload TEXT NOT NULL
+    );
+  `);
+    const loadStmt = db.prepare("SELECT payload FROM features WHERE key = ?");
+    const saveStmt = db.prepare("INSERT OR REPLACE INTO features (key, payload) VALUES (?, ?)");
+    const listStmt = db.prepare("SELECT payload FROM features");
+    return {
+        async load(key) {
+            const row = loadStmt.get(key);
+            if (row === undefined) {
+                return undefined;
+            }
+            return parsePayload(row.payload);
+        },
+        async save(key, aggregate) {
+            try {
+                db.exec("BEGIN IMMEDIATE");
+                saveStmt.run(key, JSON.stringify(aggregate));
+                db.exec("COMMIT");
+                return { ok: true };
+            }
+            catch (error) {
+                try {
+                    db.exec("ROLLBACK");
+                }
+                catch {
+                    // Rollback can fail if BEGIN never succeeded.
+                }
+                const detail = error instanceof Error ? error.message : String(error);
+                return { ok: false, detail };
+            }
+        },
+        async listSummaries() {
+            const rows = listStmt.all();
+            const summaries = [];
+            for (const row of rows) {
+                const aggregate = parsePayload(row.payload);
+                if (aggregate !== undefined) {
+                    summaries.push(toSummary(aggregate));
+                }
+            }
+            return summaries;
+        },
+    };
+}
+//# sourceMappingURL=open-sqlite-persist.js.map

package/dist/open-sqlite-persist.js.map

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

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@bluewombat/persist-sqlite",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "WorkLedger persistence: one SQLite database via node:sqlite.",
+  "keywords": [
+    "mason",
+    "bluewombat",
+    "persistence",
+    "sqlite"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/tilap/bluewombat/tree/main/packages/plugins/persist-sqlite#readme",
+  "bugs": "https://github.com/tilap/bluewombat/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tilap/bluewombat.git",
+    "directory": "packages/plugins/persist-sqlite"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=24.20.0"
+  },
+  "scripts": {
+    "lint": "biome check .",
+    "format": "biome check --write .",
+    "tsc": "tsc --noEmit",
+    "test": "tsx --test $(find src -name '*.test.ts')",
+    "build": "tsc -p tsconfig.build.json"
+  },
+  "dependencies": {
+    "@bluewombat/work-ledger": "^0.1.0"
+  }
+}