@valbuild/server 0.103.0 → 0.103.2

package/dist/declarations/src/ValOps.d.ts

@@ -84,6 +84,15 @@ export declare abstract class ValOps {
         schemaSha: SchemaSha;
         sourcesSha: SourcesSha;
         patches: PatchId[];
+        /**
+         * Unpublished changes the store threw away because it could not read
+         * them. FS mode only: the content api owns its own patches and does not
+         * discard them behind the client's back.
+         */
+        removed?: {
+            patchId: PatchId;
+            reason: string;
+        }[];
         /** FS mode only — see the `params` counterpart. */
         jsonEntriesSha?: string;
     } | {

package/dist/declarations/src/ValOpsFS.d.ts

@@ -1,7 +1,6 @@
 import { PatchId, ModuleFilePath, ValModules } from "@valbuild/core";
-import { AuthorId, BaseSha, BinaryFileType, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, SchemaSha, CommitSha, OrderedPatches, OrderedPatchesMetadata, PatchReadError, SourcesSha } from "./ValOps.js";
+import { AuthorId, BaseSha, BinaryFileType, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, SchemaSha, CommitSha, OrderedPatches, OrderedPatchesMetadata, SourcesSha } from "./ValOps.js";
 import { Patch, ParentRef, ValCommit } from "@valbuild/shared/internal";
-import { ParentPatchId } from "@valbuild/core";
 import { Buffer } from "buffer";
 export declare class ValOpsFS extends ValOps {
     private readonly contentUrl;
@@ -14,6 +13,20 @@ export declare class ValOpsFS extends ValOps {
      * content lives behind a thunk that `JSON.stringify` drops).
      */
     private readonly jsonEntryFilesFingerprint;
+    /**
+     * Unpublished changes repair threw away, waiting to be told to somebody.
+     *
+     * Held here and drained by the next `getStat`, because stat is the channel
+     * that always flows. The case worth reporting is a repair that removed
+     * EVERYTHING - which is what an old store looks like - and then there is
+     * nothing left for the studio to fetch, so a notice riding on `fetchPatches`
+     * would never be collected. Drained rather than kept, because this has to be
+     * said once: a permanent flag would put a toast on the screen forever.
+     *
+     * Held in memory only: a restart loses it, and that is the right trade. The
+     * durable record is `patches.repair.log`.
+     */
+    private readonly removedPatchNotices;
     onInit(): Promise<void>;
     getPresignedAuthNonce(project: string, corsOrigin: string, auth: {
         pat: string;
@@ -50,6 +63,10 @@ export declare class ValOpsFS extends ValOps {
         schemaSha: SchemaSha;
         sourcesSha: SourcesSha;
         patches: PatchId[];
+        removed?: {
+            patchId: PatchId;
+            reason: string;
+        }[];
         jsonEntriesSha?: string;
     } | {
         type: "use-websocket";
@@ -67,23 +84,39 @@ export declare class ValOpsFS extends ValOps {
         unauthorized?: boolean;
         networkError?: boolean;
     }>;
-    private readPatches;
-    getParentPatchIdFromParentRef(parentRef: ParentRef): ParentPatchId;
+    /**
+     * The one read every other read comes out of.
+     *
+     * `getStat` announces from this and `fetchPatches` delivers from this, so the
+     * two cannot disagree. They used to: `getStat` counted the directories on disk
+     * while `fetchPatches` walked the parent links between them, and when a single
+     * record went missing the first said 410 and the second said 359 — with no
+     * error anywhere, because a walk that runs out of links just stops.
+     *
+     * Anything wrong is reported, then repaired, and reset only if repair does not
+     * settle it. In that order, and never silently.
+     */
+    private readStore;
+    /**
+     * Report, repair, and reset only if repair did not take.
+     *
+     * Reached only when something is actually wrong, so the healthy path — which
+     * is every stat poll — never touches the lock.
+     */
+    private repairStore;
     fetchPatches<ExcludePatchOps extends boolean>(filters: {
         patchIds?: PatchId[];
         excludePatchOps: ExcludePatchOps;
     }): Promise<ExcludePatchOps extends true ? OrderedPatchesMetadata : OrderedPatches>;
-    fetchPatchesFromFS<ExcludePatchOps extends boolean>(excludePatchOps: ExcludePatchOps): Promise<ExcludePatchOps extends true ? FSPatchesMetadata : FSPatches>;
-    private createPatchChain;
     private parseJsonFile;
-    protected saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef, authorId: AuthorId | null, sessionId: string | null): Promise<SaveSourceFilePatchResult>;
+    protected saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, _parentRef: ParentRef, authorId: AuthorId | null, sessionId: string | null): Promise<SaveSourceFilePatchResult>;
     protected getSourceFile(path: string): Promise<WithGenericError<{
         data: string;
     }>>;
     protected saveSourceFile(path: ModuleFilePath, data: string): Promise<WithGenericError<{
         path: ModuleFilePath;
     }>>;
-    saveBase64EncodedBinaryFileFromPatch(filePath: string, parentRef: ParentRef, patchId: PatchId, data: string | null, _type: BinaryFileType, metadata: MetadataOfType<BinaryFileType> | undefined): Promise<WithGenericError<{
+    saveBase64EncodedBinaryFileFromPatch(filePath: string, _parentRef: ParentRef, patchId: PatchId, data: string | null, _type: BinaryFileType, metadata: MetadataOfType<BinaryFileType> | undefined): Promise<WithGenericError<{
         patchId: PatchId;
         filePath: string;
     }>>;
@@ -104,7 +137,6 @@ export declare class ValOpsFS extends ValOps {
     deleteAllPatches(): Promise<{
         error?: GenericErrorMessage;
     }>;
-    private updateOrderedPatches;
     saveOrUploadFiles(preparedCommit: PreparedCommit, mode: "skip-remote" | "upload-remote", auth?: {
         apiKey: string;
     } | {
@@ -118,33 +150,10 @@ export declare class ValOpsFS extends ValOps {
     }>;
     getBinaryFile(filePath: string): Promise<Buffer | null>;
     protected getBinaryFileMetadata<T extends BinaryFileType>(filePath: string, type: T): Promise<OpsMetadata<T>>;
-    private getParentPatchIdFromPatchId;
-    private getParentPatchIdFromPatchIdMap;
     private getPatchesDir;
-    private getFullPatchDir;
-    private getBinaryFilePath;
-    private getBinaryFileMetadataPath;
-    private getPatchFilePath;
-    private getPatchBaseFile;
+    /**
+     * Deliberately outside the patches directory: delete-all and reset rename that
+     * whole directory, and a lock that moves away with it is not holding anything.
+     */
+    private getPatchLockFile;
 }
-type FSPatches = {
-    patches: Record<PatchId, {
-        path: ModuleFilePath;
-        patch: Patch;
-        parentRef: ParentRef;
-        createdAt: string;
-        authorId: AuthorId | null;
-        baseSha: BaseSha;
-        appliedAt: null;
-    }>;
-    error?: GenericErrorMessage;
-    errors?: PatchReadError[];
-};
-type FSPatchesMetadata = {
-    patches: Record<PatchId, Omit<FSPatches["patches"][PatchId], "patch"> & {
-        patch?: undefined;
-    }>;
-    error?: GenericErrorMessage;
-    errors?: FSPatches["errors"];
-};
-export {};

package/dist/declarations/src/index.d.ts

@@ -38,3 +38,10 @@ export { formatPatchSourceError } from "./ValOps.js";
 export { compareWithCapturedReport, readCapturedReport, replaySnapshot, } from "./debug/replaySnapshot.js";
 export type { ReplayComparison, ReplayResult } from "./debug/replaySnapshot.js";
 export type { OrderedPatches, PatchAnalysis, PatchSourceError, PreparedCommit, } from "./ValOps.js";
+/**
+ * The local-dev patch store, exported so the CLI's debug tooling can read a
+ * snapshot back with the same code the server uses rather than a second
+ * implementation of the layout.
+ */
+export { readPatchStore, describePatchStoreProblems } from "./patchStore.js";
+export type { PatchStoreEntry, PatchStoreProblem, ReadPatchStoreResult, } from "./patchStore.js";

package/dist/declarations/src/patchLog.d.ts

@@ -0,0 +1,124 @@
+import { ModuleFilePath, PatchId } from "@valbuild/core";
+/**
+ * The order of the pending patches, held in one flat, append-only text file.
+ *
+ * ## Why a log and not links between the patches
+ *
+ * The store this replaces kept the order in the patches themselves: every record
+ * carried a `parentRef`, and the directory a record lived in was named after that
+ * parent. Reading the chain meant walking those links from `head`, and the walk
+ * stopped dead — silently — at the first id nothing on disk answered for.
+ *
+ * That is not a hypothetical. A store with 410 patches lost exactly one record,
+ * and the 51 patches written after it became unreachable: `/stat` counted the
+ * directories and announced 410, `GET /patches` walked the links and delivered
+ * 359, and the studio waited forever for 51 ids that no longer had a path back to
+ * `head`. One missing file cost every edit made after it.
+ *
+ * So the order lives in one place and the patches reference nothing. A patch
+ * directory is self-contained data; this file says what order the directories go
+ * in. Removing a line cannot orphan the lines below it, because there is nothing
+ * below it to orphan — the entry after a dropped one is simply next.
+ *
+ * ## Why text
+ *
+ * It is read by people during exactly the incidents that make it interesting, and
+ * `cat` should be enough. One entry per line, whitespace-separated, id first:
+ *
+ * ```
+ * val-patch-log v1
+ * 659b8cfa-065c-47d1-8d82-fc69a2ac72a9 2026-08-27T11:46:13.730Z /content/authors.val.ts
+ * ```
+ *
+ * Position in the file IS the order. There is deliberately no sequence number:
+ * a number stored beside the thing it describes is a number that can disagree
+ * with it, and then something has to decide which one lies.
+ *
+ * The timestamp and path are there to make the file readable, not to be believed
+ * — `patch.json` owns those fields. Nothing here is a second copy of state that
+ * anything reads back.
+ */
+export declare const PATCH_LOG_FILE_NAME = "patches.log";
+export type PatchLogEntry = {
+    patchId: PatchId;
+    createdAt: string;
+    path: ModuleFilePath;
+};
+/**
+ * Something that is wrong with the file but does not stop it being read.
+ *
+ * Reported rather than thrown, because a log that is 99% intact is worth reading
+ * and then repairing. Only a file that cannot be understood at all is fatal, and
+ * that is a `status` on the read result, not a problem in this list.
+ */
+export type PatchLogProblem = {
+    type: "missing-header";
+    /** What stood where the header should have been. */
+    firstLine: string;
+} | {
+    type: "unsupported-version";
+    header: string;
+} | {
+    type: "unparseable-line";
+    lineNumber: number;
+    line: string;
+} | {
+    type: "duplicate-entry";
+    patchId: PatchId;
+    lineNumber: number;
+}
+/**
+ * A final line with no newline after it: a write that did not finish.
+ *
+ * Discarded rather than guessed at, and only ever possible on the LAST line —
+ * appends are serialized by the patch lock, so no other writer can have got in
+ * behind an interrupted one.
+ */
+ | {
+    type: "torn-final-line";
+    line: string;
+};
+export type ReadPatchLogResult = {
+    status: "ok";
+    entries: PatchLogEntry[];
+    problems: PatchLogProblem[];
+}
+/** No log file at all — an empty store, not a broken one. */
+ | {
+    status: "absent";
+} | {
+    status: "unreadable";
+    message: string;
+};
+export declare function formatPatchLogLine(entry: PatchLogEntry): string;
+/**
+ * Split on the first two runs of whitespace only: a module file path may contain
+ * spaces, and it is last precisely so that it can.
+ */
+export declare function parsePatchLogLine(line: string): PatchLogEntry | null;
+export declare function serializePatchLog(entries: readonly PatchLogEntry[]): string;
+export declare function readPatchLog(logFilePath: string): ReadPatchLogResult;
+export declare function parsePatchLog(raw: string): ReadPatchLogResult;
+/**
+ * Add one entry to the end of the log.
+ *
+ * A single `writeSync` on an append-only descriptor, then fsync: the whole line
+ * reaches the file or none of it does, and a reader that catches it mid-flight
+ * discards the partial last line rather than misreading it.
+ *
+ * Callers must hold the patch lock. That is what makes "the torn line can only be
+ * the last one" true, and it is why this does not try to be safe against
+ * concurrent appends on its own.
+ */
+export declare function appendPatchLogEntry(logFilePath: string, entry: PatchLogEntry): void;
+/**
+ * Replace the log wholesale — used by delete and by repair.
+ *
+ * Write a sibling temp file, fsync it, then rename over the original: a rename is
+ * atomic, so a reader either sees the old log or the new one and never a
+ * half-rewritten file. In-place truncation would have a window where the log is
+ * short and the store looks like it lost patches.
+ *
+ * Callers must hold the patch lock.
+ */
+export declare function writePatchLogFile(logFilePath: string, entries: readonly PatchLogEntry[]): void;

package/dist/declarations/src/patchStore.d.ts

@@ -0,0 +1,216 @@
+import { ModuleFilePath, PatchId } from "@valbuild/core";
+import { z } from "zod";
+import type { AuthorId, BaseSha } from "./ValOps.js";
+import { PatchLogEntry, PatchLogProblem } from "./patchLog.js";
+/**
+ * The on-disk shape of the local-dev patch store.
+ *
+ * ```
+ * .val/patches/
+ *   patches.log            the order, and the only place it lives
+ *   patches.repair.log     what repair has done, for the person who has to know
+ *   <patchId>/patch.json   one plain, self-contained directory per patch
+ *   <patchId>/base.json    written when the patch is published
+ *   <patchId>/files/…      binary payloads for this patch's file ops
+ * ```
+ *
+ * A directory is named after the patch it holds, and a record references nothing
+ * outside itself. That is the whole design, and it is a direct answer to how the
+ * old layout failed: there, a directory was named after a record's PARENT, so
+ * reading the store meant following links, and one absent record silently cut off
+ * every patch written after it.
+ *
+ * The invariant this module exists to hold up is narrow and worth stating: **the
+ * announced set and the delivered set are the same array.** `getStat` and
+ * `fetchPatches` both come out of one `readPatchStore` call, so they cannot report
+ * different numbers - which is exactly what they did when this broke, announcing
+ * 410 patches and delivering 359 with no error in between.
+ */
+export declare const PATCH_REPAIR_LOG_FILE_NAME = "patches.repair.log";
+export declare const FSPatch: z.ZodObject<{
+    path: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+    patch: z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
+        op: z.ZodLiteral<"add">;
+        path: z.ZodArray<z.ZodString>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+    }, z.core.$strict>, z.ZodObject<{
+        op: z.ZodLiteral<"remove">;
+        path: z.ZodTuple<[z.ZodString], z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        op: z.ZodLiteral<"replace">;
+        path: z.ZodArray<z.ZodString>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+    }, z.core.$strict>, z.ZodObject<{
+        op: z.ZodLiteral<"move">;
+        from: z.ZodTuple<[z.ZodString], z.ZodString>;
+        path: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        op: z.ZodLiteral<"copy">;
+        from: z.ZodArray<z.ZodString>;
+        path: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        op: z.ZodLiteral<"test">;
+        path: z.ZodArray<z.ZodString>;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+    }, z.core.$strict>, z.ZodObject<{
+        op: z.ZodLiteral<"file">;
+        path: z.ZodArray<z.ZodString>;
+        filePath: z.ZodString;
+        value: z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>;
+        remote: z.ZodBoolean;
+        nestedFilePath: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        metadata: z.ZodOptional<z.ZodType<import("@valbuild/core/patch").JSONValue, unknown, z.core.$ZodTypeInternals<import("@valbuild/core/patch").JSONValue, unknown>>>;
+    }, z.core.$strict>], "op">>;
+    patchId: z.ZodString;
+    baseSha: z.ZodString & z.ZodType<BaseSha, string, z.core.$ZodTypeInternals<BaseSha, string>>;
+    authorId: z.ZodNullable<z.ZodString & z.ZodType<AuthorId, string, z.core.$ZodTypeInternals<AuthorId, string>>>;
+    createdAt: z.ZodString;
+    coreVersion: z.ZodNullable<z.ZodString>;
+    sessionId: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export type FSPatchRecord = z.infer<typeof FSPatch>;
+export declare const FSPatchBase: z.ZodObject<{
+    baseSha: z.ZodString & z.ZodType<BaseSha, string, z.core.$ZodTypeInternals<BaseSha, string>>;
+    timestamp: z.ZodString;
+}, z.core.$strip>;
+export type FSPatchBaseRecord = z.infer<typeof FSPatchBase>;
+export type PatchStoreEntry = {
+    patchId: PatchId;
+    record: FSPatchRecord;
+    /** Present once the patch has been published. */
+    base: FSPatchBaseRecord | null;
+};
+/**
+ * Something wrong with the store that a reader can see.
+ *
+ * Every one of these used to be invisible. Reporting them is the point: the
+ * failure that motivated this rewrite was not that the store broke, it was that
+ * breaking looked exactly like working.
+ */
+export type PatchStoreProblem = {
+    type: "log";
+    problem: PatchLogProblem;
+}
+/**
+ * A directory that cannot be used as a patch: no record, a record that does
+ * not parse, or one whose `patchId` is not the directory it sits in.
+ *
+ * That last case is what a store from before this layout looks like - its
+ * directories are named after each record's PARENT - and it is deliberately
+ * not special-cased. There is nothing to recover: the order lived in links
+ * that are exactly what goes wrong, so an old store is read as a pile of
+ * unusable directories and removed like any other.
+ *
+ * This is the problem the person editing is told about, because it is the one
+ * where unpublished work disappears.
+ */
+ | {
+    type: "unreadable-patch";
+    /** The directory name, which for a usable patch IS the patch id. */
+    name: string;
+    dir: string;
+    message: string;
+}
+/**
+ * A perfectly good record the log does not name.
+ *
+ * The benign half of a crash: a record is written before its log line, so an
+ * interrupted append leaves this behind. Nothing ever read it, so nothing is
+ * lost by sweeping it up, and the person editing does not need to hear about
+ * a patch that never existed as far as they were concerned.
+ */
+ | {
+    type: "orphan-directory";
+    name: string;
+    dir: string;
+}
+/**
+ * The log was gone, and the order was recovered from the records' timestamps.
+ *
+ * Reported because it is a guess. Patches written inside the same millisecond
+ * have no recoverable order - a real store had eight inside 20ms.
+ */
+ | {
+    type: "reconstructed-log";
+    entryCount: number;
+};
+export type ReadPatchStoreResult = {
+    status: "ok";
+    entries: PatchStoreEntry[];
+    problems: PatchStoreProblem[];
+} | {
+    status: "unreadable";
+    message: string;
+};
+export declare function patchesLogFile(patchesDir: string): string;
+export declare function patchRepairLogFile(patchesDir: string): string;
+export declare function patchDir(patchesDir: string, patchId: PatchId): string;
+export declare function patchRecordFile(patchesDir: string, patchId: PatchId): string;
+export declare function patchBaseFile(patchesDir: string, patchId: PatchId): string;
+export declare function patchBinaryFile(patchesDir: string, patchId: PatchId, filePath: string): string;
+export declare function patchBinaryFileMetadata(patchesDir: string, patchId: PatchId, filePath: string): string;
+/**
+ * Read the whole store: the order, the records, and everything wrong with it.
+ *
+ * One call, one answer. Callers that need only the ids and callers that need the
+ * ops both use this, which is what stops them disagreeing.
+ */
+export declare function readPatchStore(patchesDir: string): ReadPatchStoreResult;
+/** Write a patch record so that a reader sees all of it or none of it. */
+export declare function writePatchRecord(patchesDir: string, patchId: PatchId, record: FSPatchRecord): void;
+/**
+ * Add a patch to the store.
+ *
+ * Record first, then the log line, and the order is the safety property: an
+ * interrupted append leaves a directory nothing points at, which repair sweeps
+ * up. The reverse order would leave the log naming a patch that is not there -
+ * the exact state this whole rewrite exists to make unreachable.
+ *
+ * Callers must hold the patch lock.
+ */
+export declare function appendPatch(patchesDir: string, record: FSPatchRecord): PatchLogEntry;
+export type RepairAction = {
+    type: "removed-unreadable-patch";
+    name: string;
+    because: string;
+} | {
+    type: "removed-orphan-directory";
+    name: string;
+} | {
+    type: "rewrote-log";
+    entryCount: number;
+};
+/**
+ * Bring the store back to a state where the log and the directories agree.
+ *
+ * Safe in a way the old layout's repair could never be: the log is a flat list,
+ * so dropping an entry does not orphan the entries after it. There is nothing to
+ * re-link, which is why this can run unattended where re-parenting a chain could
+ * not.
+ *
+ * A patch that cannot be read is removed rather than kept around to fail again
+ * on every load. That does discard unpublished work, which is why
+ * {@link RepairAction} carries the reason, why it is written to
+ * `patches.repair.log`, and why the caller is expected to tell the person
+ * editing.
+ *
+ * Callers must hold the patch lock.
+ */
+export declare function repairPatchStore(patchesDir: string, read: Extract<ReadPatchStoreResult, {
+    status: "ok";
+}>): RepairAction[];
+/**
+ * Last resort: move the whole store aside and start empty.
+ *
+ * A rename, never a delete. What is being given up on here is someone's
+ * unpublished work, and the least this can do is say where it went.
+ *
+ * Callers must hold the patch lock.
+ */
+export declare function resetPatchStore(patchesDir: string, reason: string): {
+    movedTo: string;
+} | {
+    error: string;
+};
+/** One line per problem, for a log line or an API error a person has to act on. */
+export declare function describePatchStoreProblems(problems: readonly PatchStoreProblem[]): string[];