@nubbin/store-fs 0.1.1 → 0.2.0

package/README.md

@@ -20,15 +20,21 @@ await store.publish("/promotions/summer", artifact.hash);
 .nubbin/
   artifacts/<hash>.json
   routes/%2Fpromotions%2Fsummer.json
+  history/%2Fpromotions%2Fsummer.jsonl
 ```
 
 Writes are temp-then-rename, so a concurrent reader sees the old pointer or the new one and
 never half of either. `manifest()` reads the pointer directory rather than a stored file, so
 there is nothing to keep in step.
 
+Each publish also appends one line to the route's history log — after the pointer has moved,
+so a failed publish is never recorded as live. Appending writes only the new line, never
+reading the log back to rewrite it, so concurrent publishes of one route cannot lose each
+other's entry either. `history(route)` reads it back oldest first, and `unpublish` leaves it
+where it is.
+
 It passes a shared `ArtifactStore` contract suite, which is how a replacement adapter proves
 itself equivalent — by execution rather than by inspection.
 
-**Release candidate.**
-
-<https://effekt.github.io/nubbin/>. MIT.
+Read the [Nubbin documentation](https://nubbin.io) for the complete artifact store reference.
+MIT.

package/dist/index.d.ts

@@ -1,8 +1,85 @@
 import { ArtifactStore } from '@nubbin/core';
 
 /**
- * One pointer file per route, one file per artifact, and nothing else. No aggregate document
- * exists, so two publishes to different routes cannot lose each other's write.
+ * Builds the reference `ArtifactStore` over a directory — the store the studio, the example app
+ * and the documented `@nubbin/cli` setup all publish through, and the one a replacement adapter is
+ * measured against.
+ *
+ * Three kinds of file live under `root`, and nothing else does:
+ *
+ * ```text
+ * <root>/
+ *   artifacts/<hash>.json                 one per written artifact, never rewritten
+ *   routes/%2Fpromotions%2Fsummer.json    the pointer — the only file that moves
+ *   history/%2Fpromotions%2Fsummer.jsonl  one line per publish, oldest first
+ * ```
+ *
+ * A route key is percent-encoded, so a route with slashes is one flat filename rather than a
+ * directory tree, and `manifest()` can list `routes/` to find every published route. The logs sit
+ * in their own directory for that reason: a `.jsonl` filed among the pointers would be read as one
+ * and break the listing.
+ *
+ * Nothing is created until something is written — `root` need not exist, and each write makes the
+ * directory it needs. Reading before then is not a failure: an unknown hash and an unpublished
+ * route both read as `null`, and a store with no `routes/` yet manifests as no routes.
+ *
+ * Repeating a call is safe, which is what a publish retried after a timeout needs, but the two
+ * repeats differ. Writing a hash the store already holds leaves the file alone — a content address
+ * that already resolves holds the same bytes by construction. Publishing the same route and hash
+ * again does not: the pointer is rewritten with a fresh `updatedAt` and a second move is appended
+ * to the log. Content addressing dedupes artifacts, not moves.
+ *
+ * Every `ArtifactStore` method is implemented, `history` included, so a caller reading a route's
+ * moves needs no `?? []` fallback for this store. Within one publish the pointer moves first and
+ * the log is appended after: a crash between the two leaves the log one entry short, which
+ * under-reports. The opposite order would let the log claim a publish that never went live.
+ *
+ * @param root - The directory the store owns, absolute or resolved against `process.cwd()`. It
+ *   owns everything beneath it, so give it a directory nothing else writes into. Two stores over
+ *   one root are the same store, and so is a second process pointed at it — the state is the files.
+ * @returns An `ArtifactStore` bound to `root`. It holds no cache and no open handle: every call
+ *   reads the filesystem, so one built at module scope stays correct as other processes publish
+ *   underneath it.
+ *
+ * @throws {NubbinError} From `publish`, coded `artifact-not-stored` when nothing has been written
+ *   at that hash. A pointer at an unwritten hash would be a live 404, so the existence check comes
+ *   before the pointer is touched.
+ * @throws {NubbinError} From `publish`, coded `invalid-route` when the route addresses no page.
+ *   Core's `parseMatchKind` judges it, so an adapter that never called `compile` still cannot
+ *   publish an unaddressable route.
+ * @throws A Node filesystem error, unchanged, when the operation itself fails — no permission on
+ *   `root`, a full disk, or a path taken by something that is not the expected kind of file.
+ *   `ENOENT` alone is not one of these: it is how absence is read.
+ * @throws A `SyntaxError` from `read`, `pointer` or `manifest` when a file under `root` is not the
+ *   JSON this store wrote. Hand-editing the directory, or pointing two tools at one root, is what
+ *   produces that.
+ *
+ * @example Compile, store, publish
+ * ```ts
+ * import { compile } from "@nubbin/core";
+ * import { createFsArtifactStore } from "@nubbin/store-fs";
+ *
+ * const store = createFsArtifactStore("./.nubbin");
+ *
+ * const { artifact } = compile(version, catalog, registry, "/promotions/summer");
+ * await store.write(artifact);
+ * await store.publish(artifact.route, artifact.hash);
+ * ```
+ *
+ * @example Serve a request from the store
+ * ```ts
+ * const pointer = await store.pointer("/promotions/summer");
+ * const artifact = pointer === null ? null : await store.read(pointer.hash);
+ * ```
+ *
+ * @example Roll a route back to what it pointed at before
+ * ```ts
+ * const moves = await store.history?.("/promotions/summer") ?? [];
+ * const previous = moves.at(-2);
+ * if (previous !== undefined) {
+ *   await store.publish("/promotions/summer", previous.hash);
+ * }
+ * ```
  */
 declare function createFsArtifactStore(root: string): ArtifactStore;
 

package/dist/index.js

@@ -4,15 +4,25 @@ function artifactPath(root, hash) {
   return join(root, "artifacts", `${hash}.json`);
 }
 
-// src/fsManifest.ts
-import { readdir } from "fs/promises";
+// src/historyPath.ts
 import { join as join2 } from "path";
 
-// src/readJsonOrNull.ts
+// src/encodeRouteKey.ts
+function encodeRouteKey(route) {
+  return encodeURIComponent(route);
+}
+
+// src/historyPath.ts
+function historyPath(root, route) {
+  const key = encodeRouteKey(route);
+  return join2(root, "history", `${key}.jsonl`);
+}
+
+// src/readFileOrNull.ts
 import { readFile } from "fs/promises";
-async function readJsonOrNull(filePath) {
+async function readFileOrNull(filePath) {
   try {
-    return JSON.parse(await readFile(filePath, "utf8"));
+    return await readFile(filePath, "utf8");
   } catch (error) {
     if (error.code === "ENOENT") {
       return null;
@@ -21,9 +31,28 @@ async function readJsonOrNull(filePath) {
   }
 }
 
+// src/fsHistory.ts
+async function fsHistory(root, route) {
+  const log = await readFileOrNull(historyPath(root, route));
+  if (log === null) {
+    return [];
+  }
+  return log.split("\n").filter((line) => line !== "").map((line) => JSON.parse(line));
+}
+
+// src/fsManifest.ts
+import { readdir } from "fs/promises";
+import { join as join3 } from "path";
+
+// src/readJsonOrNull.ts
+async function readJsonOrNull(filePath) {
+  const text = await readFileOrNull(filePath);
+  return text === null ? null : JSON.parse(text);
+}
+
 // src/fsManifest.ts
 async function fsManifest(root) {
-  const directory = join2(root, "routes");
+  const directory = join3(root, "routes");
   let entries;
   try {
     entries = await readdir(directory);
@@ -33,7 +62,7 @@ async function fsManifest(root) {
     }
     entries = [];
   }
-  const read = entries.map((entry) => readJsonOrNull(join2(directory, entry)));
+  const read = entries.map((entry) => readJsonOrNull(join3(directory, entry)));
   const routes = (await Promise.all(read)).filter((pointer) => pointer !== null);
   return { routes, generatedAt: (/* @__PURE__ */ new Date()).toISOString() };
 }
@@ -41,25 +70,28 @@ async function fsManifest(root) {
 // src/fsPublish.ts
 import { NubbinIssueCode, parseMatchKind, refuse } from "@nubbin/core";
 
-// src/pointerPath.ts
-import { join as join3 } from "path";
-
-// src/encodeRouteKey.ts
-function encodeRouteKey(route) {
-  return encodeURIComponent(route);
+// src/appendJsonLine.ts
+import { appendFile, mkdir } from "fs/promises";
+import { dirname } from "path";
+async function appendJsonLine(filePath, value) {
+  const line = `${JSON.stringify(value)}
+`;
+  await mkdir(dirname(filePath), { recursive: true });
+  await appendFile(filePath, line);
 }
 
 // src/pointerPath.ts
+import { join as join4 } from "path";
 function pointerPath(root, route) {
-  return join3(root, "routes", `${encodeRouteKey(route)}.json`);
+  return join4(root, "routes", `${encodeRouteKey(route)}.json`);
 }
 
 // src/writeJsonAtomic.ts
-import { mkdir, rename, writeFile } from "fs/promises";
-import { dirname } from "path";
+import { mkdir as mkdir2, rename, writeFile } from "fs/promises";
+import { dirname as dirname2 } from "path";
 var writes = 0;
 async function writeJsonAtomic(filePath, value) {
-  await mkdir(dirname(filePath), { recursive: true });
+  await mkdir2(dirname2(filePath), { recursive: true });
   writes += 1;
   const temp = `${filePath}.${process.pid}.${writes}.tmp`;
   await writeFile(temp, JSON.stringify(value, null, 2));
@@ -68,7 +100,8 @@ async function writeJsonAtomic(filePath, value) {
 
 // src/fsPublish.ts
 async function fsPublish(root, route, hash) {
-  if (!await readJsonOrNull(artifactPath(root, hash))) {
+  const artifact = await readJsonOrNull(artifactPath(root, hash));
+  if (artifact === null) {
     refuse(
       NubbinIssueCode.ArtifactNotStored,
       `cannot publish ${route}: artifact ${hash} is not in the store`,
@@ -82,6 +115,11 @@ async function fsPublish(root, route, hash) {
     updatedAt: (/* @__PURE__ */ new Date()).toISOString()
   };
   await writeJsonAtomic(pointerPath(root, route), pointer);
+  await appendJsonLine(historyPath(root, route), {
+    hash,
+    documentVersion: artifact.documentVersion,
+    movedAt: pointer.updatedAt
+  });
 }
 
 // src/fsUnpublish.ts
@@ -107,7 +145,8 @@ function createFsArtifactStore(root) {
     pointer: (route) => readJsonOrNull(pointerPath(root, route)),
     manifest: () => fsManifest(root),
     publish: (route, hash) => fsPublish(root, route, hash),
-    unpublish: (route) => fsUnpublish(root, route)
+    unpublish: (route) => fsUnpublish(root, route),
+    history: (route) => fsHistory(root, route)
   };
 }
 export {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubbin/store-fs",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "description": "The reference artifact store for Nubbin: one file per artifact, one pointer file per route, and no aggregate to lose a write.",
   "keywords": [
     "nubbin",
@@ -32,7 +32,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@nubbin/core": "0.1.1"
+    "@nubbin/core": "0.2.0"
   },
   "devDependencies": {
     "@types/node": "25.9.2",