@valbuild/server 0.120.4 → 0.122.0

package/CHANGELOG.md

@@ -1,5 +1,247 @@
 # @valbuild/server
 
+## 0.122.0
+
+### Minor Changes
+
+- [#563](https://github.com/valbuild/val/pull/563) [`be32261`](https://github.com/valbuild/val/commit/be32261af19db8018bc37b180d903416018c0b79) Thanks [@freekh](https://github.com/freekh)! - See how a module looked at any past commit, and restore from it by pointing at it
+
+  Val could publish edits but never look back. Now every commit is a durable
+  record you can open, and any part of it can be put back.
+
+  **Open a commit and the Studio splits in two.** The left half is the Studio
+  itself — same navigation, same fields, same everything, because it _is_ the
+  editor rather than a copy of it. The right half shows the project as that commit
+  left it. On a phone the two become one pane and a toggle.
+
+  **Restoring is directed: you point at the old value, then at where it goes.**
+  Val does not try to work out which of today's fields corresponds to which of the
+  commit's. It cannot be sure — array items splice, schemas move — and a restore
+  that guesses wrong writes into the wrong place and looks like it worked. Two
+  picks leave nothing to guess. You can restore across paths, so last month's
+  headline can become today's tagline.
+
+  Before you click, every field on the "now" side says whether it can hold the
+  value you picked, and a field that cannot explains why when you click it rather
+  than doing nothing. A changed union is not itself a blocker: what matters is
+  whether the value's own shape is still allowed, so a union that gained a case
+  restores fine and one that lost the case you are restoring does not.
+
+  Rich text can be restored but is marked "probably fits" rather than confirmed —
+  comparing every mark and block against the options a schema allows is not done
+  yet, and saying so is better than a confident answer we cannot back. It is
+  checked properly the moment you commit to it: before anything is staged, the old
+  value is checked against the field it is going into, and a value that cannot be
+  that field is refused with the reason. A value that is the right shape but
+  breaks a rule about its content — a name too short for its `minLength` — is
+  staged and then held at publish, the same as if you had typed it, because a
+  restore should not be stricter than typing.
+
+  **A whole module can be put back on its own**, from a commit that changed
+  several, without reverting the rest of the commit.
+
+  **Restores are staged, not applied.** They land in pending changes, are reviewed
+  beside every other edit, and go out with the next publish. There is also "put
+  everything back", for when a whole publish was the mistake.
+
+  To make this possible, publishing now records each changed module's data and the
+  schema it was written against. Not the `.val.ts` — git already keeps that, but
+  it is code, and turning code back into data means parsing it, which is
+  best-effort and stops working as TypeScript, your runtime and Val move on. The
+  schema is kept because a value on its own cannot be drawn: showing a module as it
+  was at a commit whose schema has since changed needs _that commit's_ schema, and
+  nothing in your current checkout has it.
+
+  Things it will not pretend about: a module the commit did not touch says so
+  rather than showing today's value; a module saved by a different version of Val
+  says the version differs and that nothing is lost; a commit made before Val
+  started recording history disables restore with the reason next to it. Images
+  and files are restored by re-uploading them, since the bytes at an old commit
+  may no longer be on your branch.
+
+  History requires the Val content service. In filesystem mode it reports
+  `not-supported-in-fs-mode` rather than faking it from git, which has the files
+  but not which of a commit's changes were one editor's work.
+
+- [#597](https://github.com/valbuild/val/pull/597) [`5d14612`](https://github.com/valbuild/val/commit/5d14612f612d657a37338136188f2b3c02b28fe7) Thanks [@freekh](https://github.com/freekh)! - MCP: remove personal access token auth. The endpoint now needs an `oauth`
+  config, or local filesystem mode.
+
+  Until now, an MCP endpoint with no `oauth` config accepted whatever bearer token
+  a caller presented and relayed it to the Val content backend unread. The
+  reasoning was that without an issuer the app has no key to check a token
+  against, so it should not pretend to be the authority on what that token may
+  do — and that much was right. The shape was not: a credential the app cannot
+  check is one it cannot refuse either, so "a deployed endpoint that authenticates
+  nobody" was a supported configuration, and an app could serve content-rewriting
+  tools without ever being told where its callers should authorize.
+
+  **If you run Val in proxy mode**, MCP now requires the `oauth` config that
+  shipped in `0.120.0`. Callers authorize as themselves against the Val
+  authorization server, this app verifies the token's signature, issuer, audience
+  and expiry itself, and patches carry the verified profile as their author:
+
+  ```ts
+  initValMcp(valModules, config, {
+    oauth: {
+      issuer: "https://admin.val.build",
+      resource: "https://your-app.com/api/mcp",
+    },
+  });
+  ```
+
+  Leave it out and the endpoint answers `500` naming the missing config, rather
+  than serving the request.
+
+  **If you run Val in local filesystem mode**, nothing changes. Local development
+  still needs no `oauth` config and no authorization server: there is no backend
+  to authenticate to, and patches are written with no author. A token presented
+  to such a project is still refused rather than ignored — the endpoint answers
+  `400` and says to take the credential out of the client's configuration, since
+  what it reached was a working tree with no permission check in front of it.
+
+  Two API changes if you built your own host on `createValTools`:
+
+  - `ValToolContext.auth` no longer has a `{ type: "pat", pat }` variant.
+    `{ type: "verified-profile", profileId, scopes }` is the only credential the
+    registry accepts, and `null` still means local filesystem mode.
+  - `createValOps` no longer takes an `auth` argument. `ValOpsHttp` still accepts
+    a personal access token directly — that is how `val debug` uses the token from
+    `val login` — but no server request builds one.
+
+  Proxy mode also stops keeping one data layer per credential. Each personal
+  access token needed its own `ValOpsHttp` to hold it, each of those cached the
+  project's evaluated modules, and the bounded cache that kept the memory in
+  check turned an eviction into a re-evaluation of every module on the next call.
+  Verified callers all share one instance, because they all reach the backend
+  under the app's own API key.
+
+### Patch Changes
+
+- [#618](https://github.com/valbuild/val/pull/618) [`da6794f`](https://github.com/valbuild/val/commit/da6794f3dbd77d49ccfe780b359bab1689ee1b11) Thanks [@freekh](https://github.com/freekh)! - Remove the unused `GET /api/val/session` endpoint.
+
+  Nothing called it. The Studio reads the profile id from `/stat`, and in proxy
+  mode the route proxied to `${VAL_BUILD_URL}/api/val/${project}/auth/session`,
+  an upstream route that no longer exists — so calling it by hand returned a 500
+  rather than a session. It is gone from both the route declarations in
+  `@valbuild/shared` and the implementation in `@valbuild/server`.
+
+  Session cookie handling itself is unchanged: `/authorize`, `/callback` and
+  `/logout` still set and clear `val_session` as before.
+
+- Updated dependencies [[`be32261`](https://github.com/valbuild/val/commit/be32261af19db8018bc37b180d903416018c0b79), [`da6794f`](https://github.com/valbuild/val/commit/da6794f3dbd77d49ccfe780b359bab1689ee1b11), [`1c8b7fd`](https://github.com/valbuild/val/commit/1c8b7fda1e84cd8bd32a03a85d2789598b98c3fb)]:
+  - @valbuild/shared@0.122.0
+  - @valbuild/ui@0.122.0
+
+## 0.121.0
+
+### Minor Changes
+
+- [#464](https://github.com/valbuild/val/pull/464) [`2bcc6fd`](https://github.com/valbuild/val/commit/2bcc6fdff8d668123e07e3c5e81ac6fa1436e47b) Thanks [@freekh](https://github.com/freekh)! - Add staging and unstaging of pending changes, so one person can publish a small fix without shipping somebody else's unfinished work.
+
+  A **patch group** is the set of patches one user has chosen to publish. It is not a patch _set_: a patch set is computed from the schema and says which patches must move together, while a patch group is curated and says which ones you want live.
+
+  A group holds its owner's own work plus whatever the closure entangled with it — not everything pending. **So Publish changes meaning on a shared branch: it ships your changes and what they depend on, instead of everything anybody has pending.** That is the feature. Unstaging goes further: hold one of your own changes back and it leaves both your preview and your publish, while still existing for everyone else.
+
+  The rule relating the two is that for every group and every patch set, the group's members within that patch set must form a prefix in patch-chain order. Staging a change therefore pulls in whatever preceded it in the same patch set; unstaging drops whatever was built on top of it. The compare view names what a toggle moves, and whose it is, rather than quietly enlarging or shrinking a publish.
+
+  Editing inside a region you are holding back is allowed, and the patches you were holding are loaded back in rather than the edit being refused. An earlier design made such a region read-only until it was staged again, because an author picks an array index while looking at their own view — so re-staging patches afterwards can shift the content under the path they just chose, and their edit lands on the wrong element cleanly, with every invariant intact and only the content wrong. That guard is not what ships. It is a rare shape in practice, since two people's edits mostly land in different routes, and refusing an edit for a reason the author cannot see is a worse everyday experience than the case it prevents. Instead the real result is shown immediately: the widened set is what the editor renders and what the compare view lists.
+
+  Also fixes a pre-existing bug in patch set grouping: patch set paths were compared with a raw string prefix test, and nothing terminates a path segment, so `?foobar/title` matched `?foo`. Deleting record key `foo` and retitling record key `foobar` were treated as one inseparable change. Previously that over-grouped two unrelated edits in the review screen; with staging it would have meant publishing a deletion nobody asked for.
+
+  The `/patches` routes gain optional patch group fields and `/patch-groups/~/patches` is new. This needs a content API that has patch groups. Filesystem mode keeps the group in the client, since it has a single author and already sends an explicit patch id list when publishing.
+
+  When a save pulls other people's changes in, you are told: a toast names how many and whose. There is no undo, because your edit was written against the view those changes produce and now depends on them — the compare view shows the widened set.
+
+  Two other things keep a session honest about a shared branch. `/stat` now says which pending changes have already been published, so another author's publish stops looking pending in your Studio the moment it lands rather than when the site redeploys. And Publish refuses, without writing anything, if somebody published while you were reviewing — the review screen you acted on described a branch that has since moved.
+
+  Two things this does **not** do yet, both of which need the group annotation to refresh on its own rather than only inside a fetch for missing patch ids:
+
+  - a stage or unstage in one tab does not reach another tab;
+  - if persisting a stage fails, the local view keeps it until the page is reloaded.
+
+  `docs/independent-publish/DESIGN.md` describes the model and lists what is still a judgement call.
+
+- [#605](https://github.com/valbuild/val/pull/605) [`6794d29`](https://github.com/valbuild/val/commit/6794d2980bc81284ab7f2cc667f01cc21c9e3a79) Thanks [@freekh](https://github.com/freekh)! - `s.settings()`: the project's settings, as content.
+
+  A settings module is one per project, at the root of the content tree:
+
+  ```typescript
+  // settings.val.ts
+  export default c.define("/settings.val.ts", s.settings(), {});
+  ```
+
+  Register it in `val.modules.ts` like any other module, and it shows up in the
+  Studio under the cog at the foot of the left rail. Everything in it is content:
+  it is edited as a draft, it appears in the publish diff, and it is the same for
+  everyone working on the project.
+
+  Every key is optional, at every level, so `{}` is a complete settings module —
+  and stays one as sections are added. What it holds today is the assistant:
+
+  ```typescript
+  export default c.define("/settings.val.ts", s.settings(), {
+    assistant: {
+      enabled: true,
+      context: "A CMS for developers, run by a team of four in Oslo.",
+      tone: "Plain and direct. British English, sentence case in headings.",
+    },
+  });
+  ```
+
+  `context` is background the assistant would otherwise guess at; `tone` is how it
+  should write when it writes content. Both are sent with every message it makes.
+
+  `enabled` decides whether editors have an assistant, and it has **three** states
+  rather than two:
+
+  - `true` — they do.
+  - `false` — they do not, and every trace of it goes: no button in the top bar,
+    no row in the quick actions, no panel, nothing sent.
+  - unset — nobody has decided. The assistant is still **shown**, and asks to be
+    turned on before it is used. Hiding an assistant nobody has decided about
+    means nobody discovers it; quietly enabling one means a project starts sending
+    its content to a model because it did not know to say no.
+
+  A project with no settings module at all has an assistant, as before: there is
+  nowhere to record a decision, and nowhere for the prompt to write the answer.
+
+  **Breaking: `ai.chat` is gone from `val.config.ts`.** Whether the assistant is
+  available is a decision about the project's content, made by the people who edit
+  it, so it moved to settings — turning the chat on used to take a developer, a
+  deploy and a code review of a boolean. Remove the whole block:
+
+  ```diff
+   const { s, c, val, config } = initVal({
+  -  ai: {
+  -    chat: {
+  -      experimental: { enable: true },
+  -      suggestions: ["Summarize", "Fix typos at this page"],
+  -      title: "Ask me anything",
+  -      description: "Val can answer questions about the content.",
+  -    },
+  -  },
+   });
+  ```
+
+  `experimental.enable` becomes `assistant.enabled` in the settings module.
+  `suggestions`, `title` and `description` are removed with nothing replacing
+  them: the assistant now opens with its own copy. A project that had the chat
+  enabled and wants it to stay on for everyone should write
+  `assistant: { enabled: true }` — otherwise editors are offered it and asked.
+
+  `ai.commitMessages` stays in `val.config.ts`, and is unaffected.
+
+  Two settings modules, or one in a subdirectory, is a module error: the dev
+  server refuses to serve sources, `npx val validate` reports it against the file,
+  and the Studio says so rather than picking one.
+
+### Patch Changes
+
+- Updated dependencies [[`105479b`](https://github.com/valbuild/val/commit/105479b84a08846f1fe5971916f6a54275198d12), [`55ec736`](https://github.com/valbuild/val/commit/55ec73651394908b6f440e360d181b95a91c0a93), [`2bcc6fd`](https://github.com/valbuild/val/commit/2bcc6fdff8d668123e07e3c5e81ac6fa1436e47b), [`2bcbee1`](https://github.com/valbuild/val/commit/2bcbee1be682c2bbd5b7bc7d152ddd4204162fd2), [`6794d29`](https://github.com/valbuild/val/commit/6794d2980bc81284ab7f2cc667f01cc21c9e3a79), [`2db27d5`](https://github.com/valbuild/val/commit/2db27d555441bee2dd31817acc8c92b7b718ee55)]:
+  - @valbuild/ui@0.121.0
+  - @valbuild/shared@0.121.0
+  - @valbuild/core@0.121.0
+
 ## 0.120.4
 
 ### Patch Changes

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

@@ -14,6 +14,21 @@ export declare class Service {
      * The module file paths that are registered in the project's val.modules.
      */
     getModuleFilePaths(): ModuleFilePath[];
+    /**
+     * Everything that is wrong with how the project's modules are DECLARED, as
+     * opposed to what is in them.
+     *
+     * A module that failed to load is here, and so is a rule that spans the whole
+     * set — "one settings module, at the root" cannot be checked while looking at
+     * a single module, so `extractValModules` appends it with the offending path.
+     * `get` only surfaces these when the module is missing entirely, which a
+     * misplaced settings module is not: `val validate` reads them from here and
+     * reports them against the file.
+     */
+    getModuleErrors(): {
+        message: string;
+        path?: ModuleFilePath;
+    }[];
     private serializedSchemaOf;
     get(moduleFilePath: ModuleFilePath, modulePath: ModulePath, options?: {
         validate: boolean;

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

@@ -1,6 +1,8 @@
 import { MediaSource, FileMetadata, FileSource, ImageMetadata, ModuleFilePath, PatchId, Schema, SelectorSource, SerializedSchema, Source, SourcePath, ValConfig, ValModules, ValidationError } from "@valbuild/core";
 import { result } from "@valbuild/core/fp";
 import { JSONValue, ParentRef, Patch, PatchError } from "@valbuild/core/patch";
+import type { HistoryError } from "./history/HistoryError.js";
+import type { AffectedFile, StoredModuleVersion, CommitPage, CommitPatch, HistoricalCommit } from "./history/types.js";
 import { ValSyntaxError, ValSyntaxErrorTree } from "./patch/ts/syntax.js";
 import { ParentPatchId } from "@valbuild/core";
 import type { ReifiedPreview } from "@valbuild/core";
@@ -220,8 +222,11 @@ export declare abstract class ValOps {
      * in-flight client patches the server has not seen) must pass
      * `applyPatches: false` or the same edits would be applied twice.
      */
-    getJsonEntry(moduleFilePath: ModuleFilePath, entryKey: string, opts?: {
+    getJsonEntry(moduleFilePath: ModuleFilePath, entryKey: string, 
+    /** Passed straight through — see {@link getJsonEntries}. */
+    opts?: {
         applyPatches?: boolean;
+        patchIds?: PatchId[];
     }): Promise<{
         status: "success";
         content: JSONValue | null;
@@ -260,6 +265,15 @@ export declare abstract class ValOps {
         limit: number;
     }, opts?: {
         applyPatches?: boolean;
+        /**
+         * Only these pending patches, or every one when `undefined`.
+         *
+         * A draft render is scoped to the caller's own groups, and a page renders
+         * `jsonValues` entries beside module content — so without this the two
+         * halves of one page disagreed about whose unpublished work they showed.
+         * `undefined` is what every other caller passes and must keep getting.
+         */
+        patchIds?: PatchId[];
     }): Promise<{
         status: "success";
         entries: {
@@ -362,10 +376,25 @@ export declare abstract class ValOps {
     readProjectFile(path: string): Promise<WithGenericError<{
         data: string;
     }>>;
-    createPatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef, sessionId: string | null, authorId: AuthorId | null): Promise<result.Result<{
+    createPatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef, sessionId: string | null, authorId: AuthorId | null, 
+    /**
+     * Which patch group this patch joins, recorded in the SAME request.
+     *
+     * Atomic on purpose. The content API runs every refusal before its insert,
+     * so an invalid closure is a 400 with nothing written. Recording membership
+     * in a second call would let a patch exist outside its author's group if
+     * that call failed — and a patch outside your own group is one you cannot
+     * publish until a repair puts it back.
+     *
+     * Optional: `fs` mode has no groups, and a client that predates them sends
+     * nothing.
+     */
+    patchGroup?: PatchGroupMembership): Promise<result.Result<{
         error?: undefined;
         patchId: PatchId;
         createdAt: string;
+        /** See {@link SaveSourceFilePatchResult} — absent where there are no groups. */
+        patchGroupId?: string;
     }, {
         errorType: "other";
         error: GenericErrorMessage;
@@ -377,14 +406,36 @@ export declare abstract class ValOps {
         patchIds?: PatchId[];
         excludePatchOps: ExcludePatchOps;
     }): Promise<ExcludePatchOps extends true ? OrderedPatchesMetadata : OrderedPatches>;
-    protected abstract saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef | null, authorId: AuthorId | null, sessionId: string | null): Promise<SaveSourceFilePatchResult>;
+    protected abstract saveSourceFilePatch(path: ModuleFilePath, patch: Patch, patchId: PatchId, parentRef: ParentRef | null, authorId: AuthorId | null, sessionId: string | null, patchGroup?: PatchGroupMembership): Promise<SaveSourceFilePatchResult>;
     protected abstract getSourceFile(path: string): Promise<WithGenericError<{
         data: string;
     }>>;
+    /**
+     * Save a patch's binary file from a `data:...;base64,...` URL.
+     *
+     * The wire form: `FileReader.readAsDataURL` is what the browser produces, and
+     * published `@valbuild/server` versions send it. Code that already HAS bytes
+     * should call {@link saveBinaryFileFromPatch} instead of wrapping them in a
+     * data URL just to have this unwrap them again.
+     *
+     * A `null` `data` records a DELETION, which is why this cannot simply be
+     * replaced by the byte-taking sibling: there is nothing to hand it.
+     */
     abstract saveBase64EncodedBinaryFileFromPatch(filePath: string, parentRef: ParentRef, patchId: PatchId, data: string | null, type: "file" | "image", metadata: MetadataOfType<"file" | "image"> | undefined): Promise<WithGenericError<{
         patchId: PatchId;
         filePath: string;
     }>>;
+    /**
+     * The same, for a caller that already has the bytes.
+     *
+     * Default implementation wraps them back into a data URL so every backend
+     * gets this for free; a backend that can take bytes straight through should
+     * override it.
+     */
+    saveBinaryFileFromPatch(filePath: string, parentRef: ParentRef, patchId: PatchId, bytes: Buffer, mimeType: string, type: "file" | "image", metadata: MetadataOfType<"file" | "image"> | undefined): Promise<WithGenericError<{
+        patchId: PatchId;
+        filePath: string;
+    }>>;
     abstract getBase64EncodedBinaryFileFromPatch(filePath: string, patchId: PatchId, remote: boolean): Promise<Buffer | null>;
     protected abstract getBase64EncodedBinaryFileMetadataFromPatch<T extends "file" | "image">(filePath: string, type: T, patchId: PatchId, remote: boolean): Promise<OpsMetadata<T>>;
     abstract getBinaryFile(filePathOrRef: string): Promise<Buffer | null>;
@@ -401,6 +452,40 @@ export declare abstract class ValOps {
         errors?: undefined;
         deleted?: undefined;
     }>;
+    /** One page of a branch's commits, newest first. See history/listCommits. */
+    abstract listCommits(branch: string, options?: {
+        limit?: number;
+        cursor?: string;
+    }): Promise<result.Result<CommitPage, HistoryError>>;
+    /** The patches that produced one commit, with their ops. */
+    abstract getCommitPatches(commitSha: string): Promise<result.Result<{
+        commit: HistoricalCommit;
+        patches: CommitPatch[];
+    }, HistoryError>>;
+    /**
+     * How each `.val.ts` the commit changed looked BEFORE it, keyed by module
+     * file path. Empty for a commit made before this was recorded - which the
+     * caller reports as `source-unavailable` rather than as an empty module.
+     */
+    /**
+     * Each module a commit changed: its data, and the schema it was under.
+     *
+     * `asOf` widens it from "what this commit changed" to "the whole project as
+     * this commit left it", which is what reverting everything to a point in time
+     * needs; `moduleFilePath` narrows it to one module, for navigating the
+     * history pane off the changed set.
+     */
+    abstract getCommitModules(commitSha: string, options?: {
+        asOf?: boolean;
+        moduleFilePath?: ModuleFilePath;
+    }): Promise<result.Result<{
+        modules: StoredModuleVersion[];
+        complete: boolean;
+    }, HistoryError>>;
+    /** Which files the commit touched, and how. Names them; does not fetch them. */
+    abstract getCommitAffectedFiles(commitSha: string): Promise<result.Result<AffectedFile[], HistoryError>>;
+    /** One file's bytes as they were at one commit. */
+    abstract getFileAtCommit(commitSha: string, filePath: string, remote: boolean): Promise<result.Result<Buffer, HistoryError>>;
 }
 export type WithGenericError<T extends Record<string, unknown>> = (T & {
     error?: undefined;
@@ -414,8 +499,37 @@ export type GenericErrorMessage = {
     message: string;
     details?: unknown;
 };
+/**
+ * The patch group a newly created patch joins.
+ *
+ * `withPatchIds` is the CLOSURE the client computed — the patches that share
+ * a patch set with this one and must move with it. It is not derived here and
+ * must not be: the closure needs the content schema, and the service that
+ * stores groups does not have it. One implementation of that rule, on the side
+ * that can actually compute it.
+ *
+ * Membership rows are stamped with `coreVersion` on the content side, the same
+ * stamp the patch row itself carries, so which client wrote a row stays legible
+ * after the fact.
+ */
+export type PatchGroupMembership = {
+    /**
+     * Absent means "the author's open group, created if absent" — the content API
+     * resolves it. The client does not hold an id across publishes, because a
+     * published group is refused and the stale id would lose the write.
+     */
+    patchGroupId?: string;
+    withPatchIds: PatchId[];
+};
 export type SaveSourceFilePatchResult = result.Result<{
     patchId: PatchId;
+    /**
+     * The group the patch ended up in, where the store has groups at all.
+     *
+     * Absent in `fs` mode and against a content API that predates groups. The
+     * client uses it to learn the id of the group its own first write created.
+     */
+    patchGroupId?: string;
 }, ({
     errorType: "other";
 } & GenericErrorMessage) | {
@@ -477,6 +591,15 @@ export type PreparedCommit = {
      * Previous source files that were patched
      */
     previousSourceFiles: Record<ModuleFilePath, string>;
+    /**
+     * Each changed module's Source after this commit, and its schema.
+     *
+     * This is what makes a commit restorable. See the comment where it is built.
+     */
+    moduleVersions: Record<ModuleFilePath, {
+        source: JSONValue | null;
+        schema: SerializedSchema;
+    }>;
     /**
      * Diagnosis only: what the source file looks like with the appliable patches
      * applied, for modules that had at least one unappliable patch. Populated
@@ -523,6 +646,36 @@ export type PatchReadError = {
     parentPatchId: ParentPatchId;
     message: string;
 };
+/**
+ * The patches a json entry render should apply, out of the whole chain.
+ *
+ * Three rules, and the second is the one that was missing. A draft page renders
+ * `jsonValues` entries beside module content, and only the modules were scoped
+ * — so one screen showed the caller's own view for its modules and base plus
+ * EVERY pending patch on the branch for the entries beside them, including
+ * another author's half-finished edit rendered as though it were live.
+ *
+ * 1. this module's, since the chain is branch-wide;
+ * 2. this caller's, when they asked to be scoped. `undefined` is "everything",
+ *    which is what every unscoped caller gets and must keep getting;
+ * 3. not already applied — a fact about this path rather than about scoping,
+ *    and true with or without a scope.
+ *
+ * Filtered here rather than by asking `fetchPatches` for a list, and that is
+ * load-bearing: both implementations read an empty `patchIds` as "no filter"
+ * and return the whole chain. That is the right default for a caller that
+ * cannot mean "none", and the most dangerous possible reading of a group that
+ * is genuinely empty — it would render every unpublished patch on the branch
+ * instead of base. It costs no round trip either: the whole chain is what the
+ * unscoped path fetches anyway.
+ */
+export declare function scopedModulePatches<T extends {
+    path: ModuleFilePath;
+    patchId: PatchId;
+    appliedAt: {
+        commitSha: CommitSha;
+    } | null;
+}>(patches: T[], moduleFilePath: ModuleFilePath, patchIds: PatchId[] | undefined): T[];
 export type OrderedPatches = {
     patches: {
         path: ModuleFilePath;
@@ -554,6 +707,5 @@ export type OrderedPatchesMetadata = {
 };
 export declare function getFieldsForType<T extends BinaryFileType>(type: T): (keyof MetadataOfType<T> & string)[];
 export declare function createMetadataFromBuffer<T extends BinaryFileType>(type: BinaryFileType, mimeType: string, buffer: Buffer): OpsMetadata<T>;
-export declare function getMimeTypeFromBase64(content: string): string | null;
 export declare function guessMimeTypeFromPath(filePath: string): string | null;
 export declare function bufferFromDataUrl(dataUrl: string): Buffer | undefined;

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

@@ -1,6 +1,9 @@
 import { PatchId, ModuleFilePath, ValModules } from "@valbuild/core";
-import { AuthorId, BaseSha, BinaryFileType, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, SchemaSha, CommitSha, OrderedPatches, OrderedPatchesMetadata, SourcesSha } from "./ValOps.js";
+import { AuthorId, BaseSha, BinaryFileType, GenericErrorMessage, MetadataOfType, OpsMetadata, PreparedCommit, ValOps, ValOpsOptions, WithGenericError, SaveSourceFilePatchResult, type PatchGroupMembership, SchemaSha, CommitSha, OrderedPatches, OrderedPatchesMetadata, SourcesSha } from "./ValOps.js";
 import { Patch, ParentRef, ValCommit } from "@valbuild/shared/internal";
+import type { HistoryError } from "./history/HistoryError.js";
+import type { AffectedFile, StoredModuleVersion, CommitPage, CommitPatch, HistoricalCommit } from "./history/types.js";
+import { result } from "@valbuild/core/fp";
 import { Buffer } from "buffer";
 export declare class ValOpsFS extends ValOps {
     private readonly contentUrl;
@@ -102,7 +105,7 @@ export declare class ValOpsFS extends ValOps {
         excludePatchOps: ExcludePatchOps;
     }): Promise<ExcludePatchOps extends true ? OrderedPatchesMetadata : OrderedPatches>;
     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, _patchGroup?: PatchGroupMembership): Promise<SaveSourceFilePatchResult>;
     protected getSourceFile(path: string): Promise<WithGenericError<{
         data: string;
     }>>;
@@ -158,4 +161,15 @@ export declare class ValOpsFS extends ValOps {
      * whole directory, and a lock that moves away with it is not holding anything.
      */
     private getPatchLockFile;
+    listCommits(): Promise<result.Result<CommitPage, HistoryError>>;
+    getCommitPatches(): Promise<result.Result<{
+        commit: HistoricalCommit;
+        patches: CommitPatch[];
+    }, HistoryError>>;
+    getCommitModules(): Promise<result.Result<{
+        modules: StoredModuleVersion[];
+        complete: boolean;
+    }, HistoryError>>;
+    getCommitAffectedFiles(): Promise<result.Result<AffectedFile[], HistoryError>>;
+    getFileAtCommit(): Promise<result.Result<Buffer, HistoryError>>;
 }