@valbuild/server 0.120.4 → 0.122.0

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

@@ -1,13 +1,25 @@
 import { type PatchId, type ModuleFilePath, ValModules } from "@valbuild/core";
 import type { Patch as PatchT, ParentRef as ParentRefT } from "@valbuild/core/patch";
-import { type AuthorId, type BaseSha, BinaryFileType, type CommitSha, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha } from "./ValOps.js";
+import { type AuthorId, type BaseSha, BinaryFileType, type CommitSha, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha } from "./ValOps.js";
 import { z } from "zod";
-import { ParentRef, ValCommit, ValDeployment } from "@valbuild/shared/internal";
+import type { HistoryError } from "./history/HistoryError.js";
+import type { AffectedFile, StoredModuleVersion, CommitPage, CommitPatch, HistoricalCommit } from "./history/types.js";
+import { ParentRef, ValCommit, ValDeployment, type PatchGroupT } from "@valbuild/shared/internal";
+import { result } from "@valbuild/core/fp";
 declare const PatchId: z.ZodString & z.ZodType<PatchId, string, z.core.$ZodTypeInternals<PatchId, string>>;
 declare const CommitSha: z.ZodString & z.ZodType<CommitSha, string, z.core.$ZodTypeInternals<CommitSha, string>>;
 declare const BaseSha: z.ZodString & z.ZodType<BaseSha, string, z.core.$ZodTypeInternals<BaseSha, string>>;
 declare const AuthorId: z.ZodString & z.ZodType<AuthorId, string, z.core.$ZodTypeInternals<AuthorId, string>>;
 declare const ModuleFilePath: z.ZodString & z.ZodType<ModuleFilePath, string, z.core.$ZodTypeInternals<ModuleFilePath, string>>;
+export type PatchGroupMutationResult = {
+    patchIds: PatchId[];
+    status?: undefined;
+    error?: undefined;
+} | {
+    patchIds: PatchId[];
+    status: 403 | 409 | 500;
+    error: GenericErrorMessage;
+};
 export declare class ValOpsHttp extends ValOps {
     private readonly contentUrl;
     private readonly project;
@@ -68,6 +80,10 @@ export declare class ValOpsHttp extends ValOps {
         commits: ValCommit[];
         deployments: ValDeployment[];
         patches: PatchId[];
+        /** Of `patches`, the ones that have shipped. See the implementation. */
+        appliedPatches: PatchId[];
+        /** The newest commit, which is the publish head. */
+        headCommitSha?: string;
     } | {
         type: "error";
         error: GenericErrorMessage;
@@ -92,7 +108,120 @@ export declare class ValOpsHttp extends ValOps {
         patchIds?: PatchId[];
         excludePatchOps: ExcludePatchOps;
     }): Promise<ExcludePatchOps extends true ? OrderedPatchesMetadata : OrderedPatches>;
-    protected saveSourceFilePatch(path: ModuleFilePath, patch: PatchT, patchId: PatchId, parentRef: ParentRefT, authorId: AuthorId | null, sessionId: string | null): Promise<SaveSourceFilePatchResult>;
+    /**
+     * Add patches to a patch group.
+     *
+     * The set arrives closed by the client — `withPatchIds` is the prefix closure
+     * over the patch sets the staged patches belong to. We forward it and do not
+     * second-guess it: deriving the closure needs the content schema, which this
+     * process does have but content.val.build does not, and having two
+     * implementations of the rule would be worse than having one.
+     *
+     * Membership rows are stamped with `coreVersion` on the content side — the
+     * same stamp the patch row carries — so which client wrote a row stays
+     * legible after the fact.
+     */
+    stagePatches(patchGroupId: string, 
+    /** What the user asked to stage. */
+    patchIds: PatchId[], 
+    /**
+     * What has to come with it, because the staged patches are written on top
+     * of it.
+     *
+     * The content API stores each membership row as `explicit` or `dependency`
+     * and treats what it is not told about as a dependency. Folding the two
+     * halves into `patchIds` therefore files the patch somebody clicked as one
+     * the closure dragged in — the exact opposite of what happened, and the
+     * only record anywhere of what the author chose.
+     */
+    withPatchIds: PatchId[], 
+    /**
+     * WHO is asking, so the content API can refuse a group that is not theirs.
+     *
+     * Every call from this class carries the app's API key, which says which
+     * PROJECT is calling and nothing about which editor. Without this the
+     * content API cannot tell one of a project's editors from another, so the
+     * only check on stage and unstage is the one in `ValServer` — and anything
+     * reaching the content API by another route (an API key, a PAT) has none at
+     * all.
+     *
+     * `null` where there is no session. The content API refuses rather than
+     * treating that as a match: a group written by an api key has a null author
+     * too, and `null === null` must not read as ownership.
+     */
+    authorId: AuthorId | null): Promise<PatchGroupMutationResult>;
+    /**
+     * Remove patches from a patch group.
+     *
+     * The set arrives closed FORWARDS by the client: unstaging a patch also
+     * unstages everything built on top of it within its patch sets, and that is
+     * what `withPatchIds` carries.
+     */
+    unstagePatches(patchGroupId: string, 
+    /** What the user asked to unstage. */
+    patchIds: PatchId[], 
+    /** What has to go with it: everything built on top of it. */
+    withPatchIds: PatchId[], 
+    /** See {@link stagePatches} — the content API's half of the ownership check. */
+    authorId: AuthorId | null): Promise<PatchGroupMutationResult>;
+    /**
+     * Every patch group on this branch, with what each holds.
+     *
+     * Read rather than mutated, and used to answer "which pending patches is THIS
+     * person allowed to see". A draft render that skips this shows base + every
+     * pending patch on the branch, including work other people have not
+     * published — which is what independent publish exists to prevent.
+     *
+     * A failure is an empty list rather than a throw, and the caller decides what
+     * that means. For a draft render the honest fallback is "show nothing
+     * pending" rather than "show everything": being shown your own committed
+     * content when the group lookup is down is a worse experience than being
+     * shown somebody else's unpublished draft is a bug.
+     */
+    /**
+     * The last group lookup, and when it was made.
+     *
+     * A draft render calls `getPatchGroups` once per `fetchVal`, in series with
+     * the whole-chain fetch, and a page that calls `fetchVal` several times pays
+     * the round trip several times. Groups are per branch and change rarely, so a
+     * short window removes the multiplier without letting a stage go unseen for
+     * meaningfully longer than one render.
+     *
+     * Deliberately short. This is a read whose staleness decides whose draft
+     * content someone sees, so it is a per-request de-duplication rather than a
+     * cache: a second render a second later asks again.
+     */
+    private patchGroupsCache;
+    getPatchGroups(options?: {
+        /**
+         * Ask the content API even if a recent answer is remembered.
+         *
+         * For the checks that DECIDE something rather than render something.
+         * `refuseUnlessOwn` reads this list to say whether a group is yours, and a
+         * group is at its youngest exactly when that matters: the first write
+         * creates it, the save response names it, and the shell flushes its queued
+         * stages immediately — well inside the cache window. Served from a list
+         * fetched before the group existed, every one of those was refused 403 and
+         * dropped, so the queue that exists to survive the post-publish window
+         * persisted nothing in the flow it was built for.
+         *
+         * Not solved by shortening the window: the cache sits on this instance,
+         * which outlives the request, so "recent" is recent for the whole server
+         * and not for one render.
+         */
+        fresh?: boolean;
+    }): Promise<{
+        status: "ok";
+        patchGroups: PatchGroupT[];
+    } | {
+        status: "unsupported";
+    } | {
+        status: "error";
+        message: string;
+    }>;
+    private fetchPatchGroups;
+    private mutatePatchGroup;
+    protected saveSourceFilePatch(path: ModuleFilePath, patch: PatchT, patchId: PatchId, parentRef: ParentRefT, authorId: AuthorId | null, sessionId: string | null, patchGroup?: PatchGroupMembership): Promise<SaveSourceFilePatchResult>;
     /**
      * @deprecated For HTTP ops use direct upload instead (i.e. client should upload the files directly) since hosting platforms (Vercel) might have low limits on the size of the request body.
      */
@@ -108,7 +237,17 @@ export declare class ValOpsHttp extends ValOps {
     getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, remote: boolean): Promise<Buffer | null>;
     protected getBase64EncodedBinaryFileMetadataFromPatch<T extends "file" | "image">(filePath: string, type: T, patchId: PatchId, remote: boolean): Promise<OpsMetadata<T>>;
     protected getBinaryFileMetadata<T extends "file" | "image">(filePath: string, type: T): Promise<OpsMetadata<T>>;
-    deletePatches(patchIds: PatchId[]): Promise<{
+    deletePatches(patchIds: PatchId[], 
+    /**
+     * Patches that are NOT deleted but must lose their group membership.
+     *
+     * Deleting a patch out of the middle of a patch set leaves every group
+     * still holding the rest with a non-prefix intersection — the patches after
+     * the hole were written against a view that had it. The content API cannot
+     * work out which those are (it has no schema), so the client sends the
+     * forward closure and it drops those memberships without deleting anything.
+     */
+    unstagePatchIds?: PatchId[]): Promise<{
         deleted: PatchId[];
         errors?: undefined;
         error?: undefined;
@@ -120,7 +259,22 @@ export declare class ValOpsHttp extends ValOps {
         errors?: undefined;
         deleted?: undefined;
     }>;
-    commit(prepared: PreparedCommit, message: string, committer: AuthorId, filesDirectory: string, newBranch?: string): Promise<{
+    commit(prepared: PreparedCommit, message: string, committer: AuthorId, filesDirectory: string, newBranch?: string, 
+    /**
+     * The patch group this commit EMPTIES, if it empties one.
+     *
+     * The content API closes the group it is given — and closes it WITHOUT
+     * checking that the commit shipped all of it, so a caller that names a
+     * group still holding work takes those patches out of every group and
+     * leaves their author unable to publish them. The client therefore sends it
+     * only when the publish accounts for everything the group still holds.
+     *
+     * Omitting it is not neutral: the commit still empties the group (the
+     * content API drops applied ids from every group), but `published_at` is
+     * never set, so the id is reused across publishes instead of a new group
+     * per publish and the "already published" refusal can never fire.
+     */
+    patchGroupId?: string): Promise<{
         isNotFastForward?: boolean;
         updatedFiles: string[];
         commit: CommitSha;
@@ -130,5 +284,32 @@ export declare class ValOpsHttp extends ValOps {
         isNotFastForward?: boolean;
         error: GenericErrorMessage;
     }>;
+    /**
+     * One GET against the content service, parsed and Result-typed.
+     *
+     * Every history read has the same three failure modes - could not reach the
+     * service, the commit is not there, the answer was not what was expected -
+     * and each of them means something different to a caller deciding whether to
+     * offer a restore. Doing it once here is what keeps that consistent across
+     * the five endpoints.
+     */
+    private getHistory;
+    listCommits(branch: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<result.Result<CommitPage, HistoryError>>;
+    getCommitPatches(commitSha: string): Promise<result.Result<{
+        commit: HistoricalCommit;
+        patches: CommitPatch[];
+    }, HistoryError>>;
+    getCommitModules(commitSha: string, options?: {
+        asOf?: boolean;
+        moduleFilePath?: ModuleFilePath;
+    }): Promise<result.Result<{
+        modules: StoredModuleVersion[];
+        complete: boolean;
+    }, HistoryError>>;
+    getCommitAffectedFiles(commitSha: string): Promise<result.Result<AffectedFile[], HistoryError>>;
+    getFileAtCommit(commitSha: string, filePath: string, remote: boolean): Promise<result.Result<Buffer, HistoryError>>;
 }
 export {};

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

@@ -1,6 +1,9 @@
-import { ValModules, ValConfig } from "@valbuild/core";
+import { ValModules, PatchId, ModuleFilePath, ValConfig } from "@valbuild/core";
 import { Api, ServerOf } from "@valbuild/shared/internal";
 import { z } from "zod";
+import { ValOpsFS } from "./ValOpsFS.js";
+import { CommitSha } from "./ValOps.js";
+import { ValOpsHttp } from "./ValOpsHttp.js";
 export type ValServerOptions = {
     route: string;
     valEnableRedirectUrl?: string;
@@ -33,6 +36,108 @@ export type ValServerCallbacks = {
     onEnable: (success: boolean) => Promise<void>;
     onDisable: (success: boolean) => Promise<void>;
 };
+/**
+ * Refuse to touch a group that is not the caller's.
+ *
+ * Exported for `patchGroupOwnership.test.ts`: this is the whole of the
+ * authorization for stage and unstage, and nothing else in the process checks
+ * it, so it is worth testing as a policy rather than only through a route.
+ *
+ * `getAuth` only proves a session EXISTS; it says nothing about whose
+ * group this is. And the content API cannot decide either — every call
+ * from here carries the app's API key, not the editor's identity — so if
+ * this does not check, nothing does.
+ *
+ * `GET /patches?include_patch_groups=true` hands every editor the id and
+ * author of every open group on the branch, so without this any logged-in
+ * editor can unstage another author's patches (their next publish
+ * silently ships less) or stage into their group (it silently ships
+ * more). The 403 declared for this route in `ApiRoutes.ts` was
+ * unreachable.
+ *
+ * Fails CLOSED: if the groups cannot be read, the mutation is refused
+ * rather than allowed unverified.
+ */
+/**
+ * The patches a scoped draft render should apply: the caller's own group, plus
+ * everything already committed.
+ *
+ * Scoping is about PENDING work. A published patch stays in the chain with
+ * `appliedAt` set until the next deployment moves the base, and it is part of
+ * everyone's view in that window — the unscoped path applies it. Dropping it
+ * meant the moment somebody published, their own draft preview reverted the
+ * field they had just shipped, and nobody else saw it either until the deploy
+ * landed; anything written on top in that window is authored against content
+ * already stale on `main`.
+ *
+ * Keyed on `appliedAt` rather than on the group's `publishedAt`, because a
+ * PARTIAL publish leaves the group open with only some of its patches applied.
+ * Those are committed too, and no flag on the group names them.
+ *
+ * `undefined` scope is unscoped and never reaches here; an EMPTY scope is a
+ * caller holding nothing, and on a branch with nothing applied it correctly
+ * filters down to no patches, which renders base.
+ */
+export declare function scopedPatches<T extends {
+    patchId: PatchId;
+    appliedAt: {
+        commitSha: CommitSha;
+    } | null;
+}>(patches: T[], ownPatchIds: PatchId[] | undefined): T[];
+/**
+ * Which of the client's `unstagePatchIds` this server is willing to forward.
+ *
+ * The forward closure of a discard is the client's to compute — it needs the
+ * patch sets, which need the schema — and it was being forwarded verbatim. But
+ * the content API removes those memberships from EVERY group with no ownership
+ * check, so any logged-in editor could strip arbitrary patches out of any other
+ * author's group by attaching them to a delete of one of their own throwaway
+ * patches. That is the outcome the 403 on `/patch-groups` exists to prevent,
+ * reached by a different door: their next publish silently ships less.
+ *
+ * Neither server can compute the true closure, but this one can BOUND it. A
+ * patch can only be invalidated by a delete if it was written after that delete
+ * — its paths were chosen against a view that had it — and if it is in the same
+ * module, since a patch set never spans two. Anything outside those bounds was
+ * not in the closure whatever the client says, so it is dropped rather than
+ * refused: the delete is still correct, and refusing the whole request over an
+ * over-broad extra would turn a discard into an error the user cannot act on.
+ *
+ * Exported for the test. Pure, and given the chain rather than fetching it, so
+ * the ordering it depends on is visible in the test rather than mocked.
+ */
+export declare function boundUnstageClosure(
+/** The pending chain, in chain order, as `fetchPatches` returns it. */
+chain: readonly {
+    patchId: PatchId;
+    path: ModuleFilePath;
+}[], deleted: readonly PatchId[], requested: readonly PatchId[]): PatchId[];
+/**
+ * Which pending patches this caller may see, when they asked for "only mine".
+ *
+ * Shared by `/sources/~` and `/json`, and it has to be: a draft page renders
+ * both, so two answers to "whose work is this" put one person's half-finished
+ * edit on another person's preview through whichever route was not scoped. That
+ * is exactly what happened — `/json` applied every pending patch on the branch
+ * while the module content beside it was scoped.
+ *
+ * `undefined` means "apply everything", which is what every caller that does
+ * not ask for scoping gets and must keep getting.
+ */
+export declare function resolveOwnPatchScope(serverOps: ValOpsFS | ValOpsHttp, opts: {
+    /** A caller that named a list already knows what it wants. */
+    explicitPatchIds: PatchId[] | undefined;
+    ownGroupsOnly: boolean;
+    /** `undefined` where there is no session to have one. */
+    authorId: string | undefined;
+}): Promise<{
+    ownPatchIds: PatchId[] | undefined;
+    scopeAlsoIncludesApplied: boolean;
+}>;
+export declare function refuseUnlessOwn(ops: ValOpsHttp, patchGroupId: string, authorId: string): Promise<{
+    status: 403 | 409 | 500;
+    message: string;
+} | null>;
 declare const IntegratedServerJwtPayload: z.ZodObject<{
     sub: z.ZodString;
     exp: z.ZodNumber;