@valbuild/server 0.121.0 → 0.123.0

package/CHANGELOG.md

@@ -1,5 +1,229 @@
 # @valbuild/server
 
+## 0.123.0
+
+### Minor Changes
+
+- [#613](https://github.com/valbuild/val/pull/613) [`c5e7dfd`](https://github.com/valbuild/val/commit/c5e7dfd12aa1371195be642e1c2fb72b6f3e3ce2) Thanks [@freekh](https://github.com/freekh)! - Val's MCP endpoint moves to its own package, and can now upload images
+
+  Everything that serves Val's content tools over MCP — the tool registry, the
+  write path behind it, the request guards and the access-token verification —
+  now lives in **`@valbuild/mcp`** instead of being split between
+  `@valbuild/server` and `@valbuild/next`.
+
+  **Nothing changes for an app that already mounts it.** `initValMcp` is still
+  exported from `@valbuild/next/server` and behaves exactly as before; it is now a
+  ten-line binding over `@valbuild/mcp`, supplying the Next version that
+  `initHandlerOptions` asks for. A host that is not Next can call
+  `initValMcp` from `@valbuild/mcp` directly.
+
+  If you built your own host on `createValTools`, import it from `@valbuild/mcp`
+  rather than `@valbuild/server`; the tool types moved with it.
+
+  ## Image uploads
+
+  An agent can now add an image, with a new `upload_image` tool. It takes a path
+  to a file on the machine your app runs on, or the image inline as base64, and
+  puts it in an `s.image()` field or an `s.images()` gallery.
+
+  Uploads are converted **only where the Studio would convert them**: `encode` is
+  off unless the schema asks for it (`s.image({ encode: { type: "webp" } })`), and
+  when it does, which images are converted, how far they are scaled and when the
+  original wins are the same decisions the browser makes — the same code, now
+  shared. An upload to a schema without `encode` is stored exactly as it arrived,
+  whatever its size.
+
+  One thing the tool does that the Studio does not: it refuses an image the
+  schema's `accept` does not cover, checked on the bytes that would actually be
+  stored. The Studio does not need to — its file picker carries `accept` — and
+  validation reports a mismatch as server-repairable, so nothing downstream would
+  stop it. An agent has no picker. Note the ordering:
+  `s.image({ accept: "image/webp", encode: { type: "webp" } })` still takes a PNG,
+  because the conversion happens first and it is the result that is checked.
+
+  It is the one tool you construct yourself, because it needs an image library
+  and `sharp` ships a compiled binary per platform. Val does not put one in every
+  project that installs it, so you decide:
+
+  ```sh
+  npm install sharp
+  ```
+
+  ```ts
+  import sharp from "sharp";
+  import { createValImageTools } from "@valbuild/mcp";
+  import { sharpImageProcessor } from "@valbuild/mcp/sharp";
+
+  const { valMcpAuthorize, valMcpTools } = initValMcp(valModules, config, {
+    extraTools: createValImageTools(sharpImageProcessor(sharp)),
+  });
+  ```
+
+  Leave `extraTools` out and everything else works as before — the agent can read,
+  validate and edit content, it just cannot add an image. `sharp` is passed in
+  rather than imported, so you can supply another encoder: `ValImageProcessor` is
+  two functions, `read` and `encode`.
+
+  Remotely stored images work too — `s.image().remote()` and
+  `s.images({ remote: true })` — and they need nothing extra from the MCP client.
+  Adding one does not upload anything to Val's content host: the bytes go into the
+  patch store like any other unpublished change, and the push to
+  `remote.val.build` happens when you publish, exactly as it does for an image
+  added through the Studio. All the tool has to do first is ask the project which
+  bucket to name in the ref, and the credential for that is the one your app
+  already has — its API key when it has one, and in local development the
+  `val login` token in your project, the same one `val validate --fix` uses. If
+  you have not logged in, it says so and writes nothing.
+
+  ## `npm create @valbuild` asks
+
+  The starter template now ships the MCP endpoint, and `npm create @valbuild`
+  asks whether you want it — and, if you do, whether agents should be able to
+  upload images, saying that this adds `sharp`. Both default to yes, and both can
+  be answered up front for a scripted setup:
+
+  ```sh
+  pnpm create @valbuild my-app --mcp --no-image-uploads
+  ```
+
+### Patch Changes
+
+- Updated dependencies [[`c5e7dfd`](https://github.com/valbuild/val/commit/c5e7dfd12aa1371195be642e1c2fb72b6f3e3ce2), [`53f670c`](https://github.com/valbuild/val/commit/53f670c0cf2d7a03a6d068c78b7874ce77652c2a)]:
+  - @valbuild/shared@0.123.0
+  - @valbuild/ui@0.123.0
+
+## 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

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";
@@ -408,10 +410,32 @@ export declare abstract class ValOps {
     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>;
@@ -428,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;
@@ -533,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
@@ -640,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, 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;
@@ -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>>;
 }

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

@@ -2,7 +2,10 @@ 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, type PatchGroupMembership, SchemaSha, OrderedPatchesMetadata, OrderedPatches, SourcesSha } from "./ValOps.js";
 import { z } from "zod";
+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>>;
@@ -281,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 {};