@valbuild/cli 0.102.0 → 0.103.1

package/src/__fixtures__/basic/content/basic-image-from-galleries.val.ts

@@ -9,7 +9,7 @@ export default c.define(
     image2: s.image(basicGallery2Val),
   }),
   {
-    image1: c.image("/public/val/images/image.png"),
-    image2: c.image("/public/val/images2/image.png"),
+    image1: { path: "/public/val/images/image.png" },
+    image2: { path: "/public/val/images2/image.png" },
   },
 );

package/src/__fixtures__/basic/content/basic-image-from-gallery.val.ts

@@ -7,6 +7,6 @@ export default c.define(
     image: s.image(basicGalleryVal),
   }),
   {
-    image: c.image("/public/val/images/image.png"),
+    image: { path: "/public/val/images/image.png" },
   },
 );

package/src/__fixtures__/basic/content/basic-image.val.ts

@@ -1,7 +1,5 @@
 import { c, s } from "../val.config";
 
-export default c.define(
-  "/content/basic-image.val.ts",
-  s.image(),
-  c.image("/public/val/image.png"),
-);
+export default c.define("/content/basic-image.val.ts", s.image(), {
+  path: "/public/val/image.png",
+});

package/src/__fixtures__/debug-snapshot/.val/patches/11111111-1111-4111-8111-111111111111/patch.json

@@ -1,19 +1,16 @@
 {
   "patch": [
     {
-      "op": "remove",
-      "path": ["BBL", "summary", "services", "2"]
+      "op": "replace",
+      "path": ["BBL", "title"],
+      "value": "BBL Housing"
     }
   ],
-  "patchId": "22222222-2222-4222-8222-222222222222",
-  "parentRef": {
-    "type": "patch",
-    "patchId": "11111111-1111-4111-8111-111111111111"
-  },
+  "patchId": "11111111-1111-4111-8111-111111111111",
   "path": "/content/projects.val.ts",
-  "authorId": "author-b",
+  "authorId": "author-a",
   "sessionId": null,
   "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
   "coreVersion": null,
-  "createdAt": "2026-08-11T09:00:00.000Z"
+  "createdAt": "2026-08-10T12:00:00.000Z"
 }

package/src/__fixtures__/debug-snapshot/.val/patches/22222222-2222-4222-8222-222222222222/patch.json

@@ -1,20 +1,15 @@
 {
   "patch": [
     {
-      "op": "replace",
-      "path": ["BBL", "summary", "services", "2"],
-      "value": "Development U"
+      "op": "remove",
+      "path": ["BBL", "summary", "services", "2"]
     }
   ],
-  "patchId": "33333333-3333-4333-8333-333333333333",
-  "parentRef": {
-    "type": "patch",
-    "patchId": "22222222-2222-4222-8222-222222222222"
-  },
+  "patchId": "22222222-2222-4222-8222-222222222222",
   "path": "/content/projects.val.ts",
-  "authorId": "author-a",
+  "authorId": "author-b",
   "sessionId": null,
   "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
   "coreVersion": null,
-  "createdAt": "2026-08-11T09:00:05.000Z"
+  "createdAt": "2026-08-11T09:00:00.000Z"
 }

package/src/__fixtures__/debug-snapshot/.val/patches/33333333-3333-4333-8333-333333333333/patch.json

@@ -0,0 +1,16 @@
+{
+  "patch": [
+    {
+      "op": "replace",
+      "path": ["BBL", "summary", "services", "2"],
+      "value": "Development U"
+    }
+  ],
+  "patchId": "33333333-3333-4333-8333-333333333333",
+  "path": "/content/projects.val.ts",
+  "authorId": "author-a",
+  "sessionId": null,
+  "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
+  "coreVersion": null,
+  "createdAt": "2026-08-11T09:00:05.000Z"
+}

package/src/__fixtures__/debug-snapshot/.val/patches/patches.log

@@ -0,0 +1,4 @@
+val-patch-log v1
+11111111-1111-4111-8111-111111111111 2026-08-10T12:00:00.000Z /content/projects.val.ts
+22222222-2222-4222-8222-222222222222 2026-08-11T09:00:00.000Z /content/projects.val.ts
+33333333-3333-4333-8333-333333333333 2026-08-11T09:00:05.000Z /content/projects.val.ts

package/src/debug/snapshot.ts

@@ -22,8 +22,6 @@ export type SnapshotPatch = {
   authorId: string | null;
   baseSha: string;
   appliedAt: { commitSha: string } | null;
-  /** Parent in the chain: null means it is the first ("head"). */
-  parentPatchId: PatchId | null;
   patch: unknown;
 };
 
@@ -199,9 +197,21 @@ export async function buildSnapshot(
     for (const p of elided.elided) {
       elidedPatchValues.push({ patchId: patch.patchId, path: p });
     }
-    entries[`.val/patches/${patch.parentPatchId ?? "head"}/patch.json`] =
-      JSON.stringify(toFsPatch(patch), null, 2);
+    entries[`.val/patches/${patch.patchId}/patch.json`] = JSON.stringify(
+      toFsPatch(patch),
+      null,
+      2,
+    );
   }
+  // The order lives in the log, not in the records, so it has to be written too
+  // or the unzipped snapshot is a store with no order at all.
+  entries[".val/patches/patches.log"] = [
+    "val-patch-log v1",
+    ...patches.map(
+      (patch) => `${patch.patchId} ${patch.createdAt} ${patch.path}`,
+    ),
+    "",
+  ].join("\n");
 
   let includesBinaryFiles = false;
   if (options.includeFiles) {
@@ -296,31 +306,29 @@ function toSnapshotPatches(
     appliedAt: { commitSha: string } | null;
   }[],
 ): SnapshotPatch[] {
-  return orderedPatches.map((patch, i) => ({
+  return orderedPatches.map((patch) => ({
     patchId: patch.patchId,
     path: patch.path,
     createdAt: patch.createdAt,
     authorId: patch.authorId,
     baseSha: patch.baseSha,
     appliedAt: patch.appliedAt,
-    parentPatchId: i === 0 ? null : orderedPatches[i - 1].patchId,
     patch: patch.patch,
   }));
 }
 
 /**
  * The shape ValOpsFS writes per patch, so an unzipped snapshot is a patch store
- * a plain ValOpsFS can read. The directory is named after the PARENT, and
- * createPatchChain walks the linked list from "head".
+ * a plain ValOpsFS can read.
+ *
+ * The directory is named after the patch itself and the record points at
+ * nothing: the order is in `patches.log` beside it. A record that named its
+ * parent is how a snapshot could carry a chain that had already lost a link.
  */
 function toFsPatch(patch: SnapshotPatch) {
   return {
     patch: patch.patch,
     patchId: patch.patchId,
-    parentRef:
-      patch.parentPatchId === null
-        ? { type: "head", headBaseSha: patch.baseSha }
-        : { type: "patch", patchId: patch.parentPatchId },
     path: patch.path,
     authorId: patch.authorId,
     sessionId: null,
@@ -339,16 +347,13 @@ async function writeBinaryFiles(
   patches: SnapshotPatch[],
   entries: Record<string, string>,
 ): Promise<boolean> {
-  const parentByPatchId = new Map(
-    patches.map((p) => [p.patchId, p.parentPatchId ?? "head"]),
-  );
+  const known = new Set(patches.map((p) => p.patchId));
   let wrote = false;
   for (const [filePath, data] of Object.entries(fileLastUpdatedByPatchId)) {
     if (data.isDelete) {
       continue;
     }
-    const parentPatchId = parentByPatchId.get(data.patchId);
-    if (parentPatchId === undefined) {
+    if (!known.has(data.patchId)) {
       continue;
     }
     const buffer = await ctx.serverOps.getBase64EncodedBinaryFileFromPatch(
@@ -361,7 +366,7 @@ async function writeBinaryFiles(
     }
     // Base64 so the snapshot stays a text-only entry map; the replay decodes it.
     entries[
-      `.val/patches/${parentPatchId}/files${filePath}/${path.posix.basename(filePath)}.base64`
+      `.val/patches/${data.patchId}/files${filePath}/${path.posix.basename(filePath)}.base64`
     ] = buffer.toString("base64");
     wrote = true;
   }

package/src/debug.test.ts

@@ -1,5 +1,8 @@
+import fs from "fs";
+import os from "os";
 import path from "path";
 import { ModuleFilePath } from "@valbuild/core";
+import { readPatchStore } from "@valbuild/server";
 import { createDebugContext } from "./debug/context";
 import { buildSnapshot } from "./debug/snapshot";
 
@@ -71,25 +74,43 @@ describe("val debug snapshot", () => {
     expect(entries["val.modules.original.ts"]).toContain("unrelated");
   });
 
-  test("writes the patch chain in the layout ValOpsFS reads back", async () => {
+  test("writes a patch store ValOpsFS can actually read back", async () => {
     const { entries } = await build();
 
-    // The directory is named after the PARENT patch; the first is "head".
-    const head = JSON.parse(entries[".val/patches/head/patch.json"]);
-    expect(head.patchId).toBe("11111111-1111-4111-8111-111111111111");
-    expect(head.parentRef.type).toBe("head");
-    // A head ref without headBaseSha does not parse, so the snapshot would be
-    // unreadable.
-    expect(typeof head.parentRef.headBaseSha).toBe("string");
-
-    const second = JSON.parse(
-      entries[".val/patches/11111111-1111-4111-8111-111111111111/patch.json"],
-    );
-    expect(second.patchId).toBe("22222222-2222-4222-8222-222222222222");
-    expect(second.parentRef).toEqual({
-      type: "patch",
-      patchId: "11111111-1111-4111-8111-111111111111",
-    });
+    // Materialise it and read it with the real store, rather than asserting on
+    // path strings: "the layout ValOpsFS reads back" is the property, and a
+    // snapshot that merely looks right is exactly what a debug tool must not
+    // produce.
+    const dir = fs.mkdtempSync(path.join(os.tmpdir(), "val-snapshot-"));
+    for (const [name, content] of Object.entries(entries)) {
+      const file = path.join(dir, name);
+      fs.mkdirSync(path.dirname(file), { recursive: true });
+      fs.writeFileSync(file, content);
+    }
+
+    const read = readPatchStore(path.join(dir, ".val", "patches"));
+    if (read.status !== "ok") {
+      throw new Error(`expected ok, got ${read.status}`);
+    }
+    expect(read.problems).toEqual([]);
+    expect(read.entries.map((entry) => entry.patchId)).toEqual([
+      "11111111-1111-4111-8111-111111111111",
+      "22222222-2222-4222-8222-222222222222",
+      "33333333-3333-4333-8333-333333333333",
+    ]);
+
+    // Each record sits under its own id and points at nothing. A record that
+    // named its parent is how a snapshot could carry a chain that had already
+    // lost a link.
+    for (const entry of read.entries) {
+      const raw = JSON.parse(
+        entries[`.val/patches/${entry.patchId}/patch.json`],
+      );
+      expect(raw.patchId).toBe(entry.patchId);
+      expect(raw).not.toHaveProperty("parentRef");
+    }
+
+    fs.rmSync(dir, { recursive: true, force: true });
   });
 
   test("records why the snapshot may be incomplete rather than failing silently", async () => {

package/src/listUnusedFiles.ts

@@ -1,10 +1,4 @@
-import {
-  FILE_REF_PROP,
-  ModuleFilePath,
-  ModulePath,
-  SourcePath,
-  VAL_EXTENSION,
-} from "@valbuild/core";
+import { ModuleFilePath, ModulePath, SourcePath } from "@valbuild/core";
 import { createService } from "@valbuild/server";
 import { glob } from "fast-glob";
 import path from "path";
@@ -49,7 +43,7 @@ export async function listUnusedFiles({ root }: { root?: string }) {
             if (isFileRef(value)) {
               const absoluteFilePathUsedByVal = path.join(
                 projectRoot,
-                ...value[FILE_REF_PROP].split("/"),
+                ...value.path.split("/"),
               );
               filesUsedByVal.push(absoluteFilePathUsedByVal);
             }
@@ -78,18 +72,17 @@ export async function listUnusedFiles({ root }: { root?: string }) {
   return;
 }
 
-function isFileRef(
-  value: unknown,
-): value is { [FILE_REF_PROP]: string; [VAL_EXTENSION]: "file" } {
-  if (!value) return false;
-  if (typeof value !== "object") return false;
-  if (FILE_REF_PROP in value && VAL_EXTENSION in value) {
-    if (
-      value[VAL_EXTENSION] === "file" &&
-      typeof value[FILE_REF_PROP] === "string"
-    ) {
-      return true;
-    }
-  }
-  return false;
+/**
+ * Whether a flagged validation value names a file.
+ *
+ * A `ValidationError` carries no schema, so the shape is all there is to go on —
+ * the same heuristic this whole function documents as a TODO.
+ */
+function isFileRef(value: unknown): value is { path: string } {
+  return (
+    !!value &&
+    typeof value === "object" &&
+    "path" in value &&
+    typeof value.path === "string"
+  );
 }

package/src/runValidation.test.ts

@@ -372,12 +372,12 @@ describe("runValidation", () => {
           .flatMap((e) => e.fixes ?? []);
         expect(allFixes).not.toContain("image:add-metadata");
       }
+      // The fix writes the fields it read from the bytes next to `path`.
       expect(result.source).toMatchObject({
-        metadata: {
-          width: 1,
-          height: 1,
-          mimeType: "image/png",
-        },
+        path: "/public/val/image.png",
+        width: 1,
+        height: 1,
+        mimeType: "image/png",
       });
     } finally {
       service.dispose();