@bluewombat/persist-fs 0.1.0

package/README.md

@@ -0,0 +1,31 @@
+# persist-fs
+
+Persistence Port for WorkLedger: one JSON file per FeatureStandard key, atomic
+rename on save. The ledger never imports this package. Glue does.
+
+```ts
+import { openWorkLedger } from "@bluewombat/work-ledger";
+import { openFilesystemPersist } from "@bluewombat/persist-fs";
+
+const persist = await openFilesystemPersist({ root: "/absolute/path/to/ledger" });
+const ledger = openWorkLedger({ persist });
+```
+
+This is what Host uses when a config says nothing (`"persist"` unset): it calls
+`openPersist({ ledgerRoot })`, one JSON file per key directly under the root.
+
+`root` must be absolute. The adapter creates it if missing.
+
+## 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 type { FilesystemPersistOptions } from "./open-filesystem-persist.js";
+export { openFilesystemPersist } from "./open-filesystem-persist.js";
+export { openPersist } from "./open-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,YAAY,EAAE,wBAAwB,EAAE,MAAM,8BAA8B,CAAC;AAC7E,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,3 @@
+export { openFilesystemPersist } from "./open-filesystem-persist.js";
+export { openPersist } from "./open-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":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AACrE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC"}

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

@@ -0,0 +1,10 @@
+import type { PersistencePort } from "@bluewombat/work-ledger";
+export type FilesystemPersistOptions = {
+    root: string;
+};
+/**
+ * Filesystem Persistence Port. One JSON file per key. Atomic rename on save.
+ * Does not know FeatureStandard transitions.
+ */
+export declare function openFilesystemPersist(options: FilesystemPersistOptions): Promise<PersistencePort>;
+//# sourceMappingURL=open-filesystem-persist.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"open-filesystem-persist.d.ts","sourceRoot":"","sources":["../src/open-filesystem-persist.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAGV,eAAe,EAEhB,MAAM,yBAAyB,CAAC;AAEjC,MAAM,MAAM,wBAAwB,GAAG;IACrC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAgCF;;;GAGG;AACH,wBAAsB,qBAAqB,CACzC,OAAO,EAAE,wBAAwB,GAChC,OAAO,CAAC,eAAe,CAAC,CA+D1B"}

package/dist/open-filesystem-persist.js

@@ -0,0 +1,95 @@
+import { mkdir, readdir, readFile, rename, unlink, writeFile } from "node:fs/promises";
+import { isAbsolute, join } from "node:path";
+function fileNameFor(key) {
+    return `${encodeURIComponent(key)}.json`;
+}
+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;
+}
+/**
+ * Filesystem Persistence Port. One JSON file per key. Atomic rename on save.
+ * Does not know FeatureStandard transitions.
+ */
+export async function openFilesystemPersist(options) {
+    if (!isAbsolute(options.root)) {
+        throw new Error(`Filesystem persist root must be an absolute directory, got "${options.root}".`);
+    }
+    await mkdir(options.root, { recursive: true });
+    const root = options.root;
+    return {
+        async load(key) {
+            const path = join(root, fileNameFor(key));
+            try {
+                const raw = await readFile(path, "utf8");
+                const parsed = JSON.parse(raw);
+                if (!isAggregate(parsed)) {
+                    return undefined;
+                }
+                return parsed;
+            }
+            catch (error) {
+                if (error instanceof Error && "code" in error && error.code === "ENOENT") {
+                    return undefined;
+                }
+                throw error;
+            }
+        },
+        async save(key, aggregate) {
+            const target = join(root, fileNameFor(key));
+            const temporary = join(root, `.${fileNameFor(key)}.tmp`);
+            try {
+                await writeFile(temporary, `${JSON.stringify(aggregate)}\n`, "utf8");
+                await rename(temporary, target);
+                return { ok: true };
+            }
+            catch (error) {
+                try {
+                    await unlink(temporary);
+                }
+                catch {
+                    // Best-effort cleanup of a leftover temporary file.
+                }
+                const detail = error instanceof Error ? error.message : String(error);
+                return { ok: false, detail };
+            }
+        },
+        async listSummaries() {
+            const names = await readdir(root);
+            const summaries = [];
+            for (const name of names) {
+                if (!name.endsWith(".json") || name.startsWith(".")) {
+                    continue;
+                }
+                try {
+                    const raw = await readFile(join(root, name), "utf8");
+                    const parsed = JSON.parse(raw);
+                    if (isAggregate(parsed)) {
+                        summaries.push(toSummary(parsed));
+                    }
+                }
+                catch { }
+            }
+            return summaries;
+        },
+    };
+}
+//# sourceMappingURL=open-filesystem-persist.js.map

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

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

package/dist/open-persist.d.ts

@@ -0,0 +1,9 @@
+import type { PersistencePort } from "@bluewombat/work-ledger";
+/**
+ * The face Host loads by name (`"persist": "@bluewombat/persist-fs"`): the
+ * ledger directory in, a Port out. One JSON file per key, directly under it.
+ */
+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":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAG/D;;;GAGG;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,9 @@
+import { openFilesystemPersist } from "./open-filesystem-persist.js";
+/**
+ * The face Host loads by name (`"persist": "@bluewombat/persist-fs"`): the
+ * ledger directory in, a Port out. One JSON file per key, directly under it.
+ */
+export function openPersist(context) {
+    return openFilesystemPersist({ root: context.ledgerRoot });
+}
+//# 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":"AACA,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE;;;GAGG;AACH,MAAM,UAAU,WAAW,CAAC,OAA+B;IACzD,OAAO,qBAAqB,CAAC,EAAE,IAAI,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC;AAC7D,CAAC"}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@bluewombat/persist-fs",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "WorkLedger persistence: one JSON file per key on the filesystem.",
+  "keywords": [
+    "mason",
+    "bluewombat",
+    "persistence"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/tilap/bluewombat/tree/main/packages/plugins/persist-fs#readme",
+  "bugs": "https://github.com/tilap/bluewombat/issues",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tilap/bluewombat.git",
+    "directory": "packages/plugins/persist-fs"
+  },
+  "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"
+  }
+}