@valbuild/server 0.122.0 → 0.123.2

package/CHANGELOG.md

@@ -1,5 +1,128 @@
 # @valbuild/server
 
+## 0.123.2
+
+### Patch Changes
+
+- [#619](https://github.com/valbuild/val/pull/619) [`8e58c34`](https://github.com/valbuild/val/commit/8e58c3495d1bf0f221a57082cb0a3045929722a1) Thanks [@freekh](https://github.com/freekh)! - Stop `val validate` reporting published remote gallery images as missing — and `--fix` deleting them
+
+  A remote gallery (`s.images({ remote: true })`) keys an uploaded entry by its
+  remote URL. Two separate checks read that key, normalised it back to the local
+  path it encodes, and then required a file to be sitting there:
+
+  - `val validate` reported _"Gallery … has tracked files that do not exist on
+    disk"_ for every published remote image;
+  - `val validate --fix` **removed the entry from the gallery**, silently deleting
+    the reference to a file that was safely on the content host.
+
+  Both were wrong for the same reason. Publishing uploads remote files to the
+  content host and copies only local ones into the working tree, so an image added
+  through the Studio — or over MCP — has no file in the repo by design. Putting one
+  there is exactly what remote storage exists to avoid.
+
+  Remote entries are now exempt from both the missing-file check and the
+  metadata-from-disk verification. Whether a remote entry is sound is
+  `image:check-remote`'s question, and it already asks it. Nothing changes for
+  local entries, or for a remote entry that does have a local file — `--fix`
+  promotes a local file to a remote ref and leaves the file where it was, and that
+  file is still counted as tracked rather than reported as untracked.
+
+- Updated dependencies [[`04b6d4c`](https://github.com/valbuild/val/commit/04b6d4cbbecc131bbaf3c20633af9dad8c857310), [`3e93508`](https://github.com/valbuild/val/commit/3e93508b05d08b0c24947a97c6141a9ad8a3931e)]:
+  - @valbuild/shared@0.123.2
+  - @valbuild/ui@0.123.2
+
+## 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

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

@@ -162,6 +162,35 @@ export declare function handleRemoteGalleryFileUpload(ctx: FixHandlerContext): P
 export declare function handleRemoteFileDownload(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleRemoteFileCheck(): Promise<FixHandlerResult>;
 export declare function handleUniqueFolderCheck(ctx: FixHandlerContext): Promise<FixHandlerResult>;
+/**
+ * What is out of step between a gallery's entries and its directory.
+ *
+ * Two questions, and they treat a remote entry differently — which is the whole
+ * reason this is separate from the handler around it:
+ *
+ * - **Missing**: an entry with no bytes at its local path. Asked of LOCAL
+ *   entries only. A remote entry's bytes live on the content host, and nothing
+ *   puts a copy in the working tree: `saveOrUploadFiles` uploads the remote
+ *   descriptors and copies only the local ones into the tree, so a remote entry
+ *   added through the Studio (or over MCP) has no local file by design, and
+ *   demanding one would mean committing remote bytes to git — which is what
+ *   remote storage exists to avoid. Whether those bytes really are on the host
+ *   is a different check, `image:check-remote`, which already runs for exactly
+ *   these entries.
+ * - **Untracked**: a file in the directory that no entry claims. Asked of every
+ *   entry, remote included, and that is why they are normalised to their local
+ *   path: `val validate --fix` promotes a local file to a remote ref and leaves
+ *   the file where it was, so a remote entry can perfectly well have one.
+ */
+export declare function checkGalleryFiles(input: {
+    entryKeys: string[];
+    directory: string;
+    projectRoot: string;
+    fs: Pick<IValFSHost, "fileExists" | "readDirectory">;
+}): {
+    missingTrackedFiles: string[];
+    untrackedFiles: string[];
+};
 export declare function handleCheckAllFiles(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 export declare function handleJsonValuesExtractEntry(ctx: FixHandlerContext): Promise<FixHandlerResult>;
 /**

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

@@ -2,10 +2,9 @@ export { createService, Service } from "./Service.js";
 export { defineExternal, ok, err, isExternalResult, EXTERNAL_RESULT, } from "./externalRecords.js";
 export type { AdapterFor, BoundExternalRecord, ExternalAuthor, ExternalBuilder, ExternalCtx, ExternalDefinition, ExternalFile, ExternalIssue, ExternalKeyPage, ExternalRecords, ExternalResult, ExternalSearchHit, ExternalSearchPage, ExternalSort, ItemOfModule, ReadonlyRecordHasNoWrites, Returns, } from "./externalRecords.js";
 export { createValApiRouter, createValServer, safeReadGit } from "./ValRouter.js";
-export { createValTools } from "./tools/index.js";
-export { VAL_SCOPE_READ, VAL_SCOPE_WRITE, authorIdFromVerifiedSubject, } from "./tools/index.js";
-export type { ValScope, ValToolAuth, ValToolContext, ValToolDefinition, ValToolDefinitionJson, ValToolErrorCode, ValToolResult, ValTools, ValToolsOptions, } from "./tools/index.js";
 export { initHandlerOptions, createValOps } from "./valServerConfig.js";
+export { resolveRemoteFileAuth } from "./valServerConfig.js";
+export type { RemoteFileAuth, ResolveRemoteFileAuthResult, } from "./valServerConfig.js";
 export { ValModuleLoader } from "./ValModuleLoader.js";
 export { getCompilerOptions } from "./getCompilerOptions.js";
 export { ValSourceFileHandler } from "./ValSourceFileHandler.js";
@@ -47,6 +46,9 @@ 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";
+export type { ValOps } from "./ValOps.js";
+export type { AuthorId, BinaryFileType, MetadataOfType, Schemas, Sources, } from "./ValOps.js";
+export type { ValServerConfig } from "./ValServer.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

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

@@ -81,4 +81,41 @@ type CredentialBearingUrl = "valBuildUrl" | "valContentUrl";
  * internal http host today.
  */
 export declare function insecureUrlWarning(name: CredentialBearingUrl, url: string): string | null;
+/**
+ * Which credential talks to the content host about REMOTE FILES.
+ *
+ * A separate question from the one `createValOps` answers, and it has to be:
+ * `ValOps` is authenticated per caller, but remote files are project-level —
+ * looking up a project's public id and its buckets, and later pushing bytes to
+ * them, is the same operation whoever asked for it.
+ *
+ * The rule, in order:
+ *
+ * 1. The app's API key, if there is one. Proxy mode always has one; fs mode has
+ *    one when `VAL_API_KEY` is set.
+ * 2. In fs mode, the developer's own `val login` token, read off disk. This is
+ *    the same file `val validate --fix` reads, and it is why local remote
+ *    uploads work with no configuration beyond having logged in.
+ * 3. Nothing, which is an error rather than a fallback.
+ *
+ * Lives here rather than inside `createValServer` because the MCP image tool
+ * needs the same answer, and this is the file that exists so that two callers
+ * cannot disagree about how a project is configured. A registry that decided it
+ * had no credential while the Studio in the same process had one would be a
+ * genuinely confusing afternoon.
+ */
+export type RemoteFileAuth = {
+    apiKey: string;
+} | {
+    pat: string;
+};
+export type ResolveRemoteFileAuthResult = {
+    status: "success";
+    auth: RemoteFileAuth;
+} | {
+    status: "error";
+    errorCode: "project-not-configured" | "pat-error";
+    message: string;
+};
+export declare function resolveRemoteFileAuth(options: ValServerConfig): Promise<ResolveRemoteFileAuthResult>;
 export {};