@valbuild/server 0.123.0 → 0.123.2

package/CHANGELOG.md

@@ -1,5 +1,36 @@
 # @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

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/valbuild-server.cjs.dev.js

@@ -13506,6 +13506,72 @@ async function extractFileMetadata(filename, _input // TODO: use buffer to deter
   };
 }
 
+/**
+ * A gallery entry's key, read as what it actually is.
+ *
+ * A gallery is a record keyed by its entries' file paths. A REMOTE gallery keys
+ * an uploaded entry by the remote URL instead — which encodes that same path —
+ * so every entry has a local path, and the interesting question is whether the
+ * bytes are expected to be at it.
+ *
+ * **They are not, for a remote entry added the ordinary way.** `saveOrUploadFiles`
+ * uploads the remote descriptors to the content host and copies only the local
+ * ones into the working tree, so an image added through the Studio (or over MCP)
+ * and published has no file in the repo, by design — putting one there is what
+ * remote storage exists to avoid. A remote entry CAN have one, because
+ * `val validate --fix` promotes a local file to a remote ref and leaves the file
+ * where it was; so "remote" means "do not require it", never "there is not one".
+ *
+ * One copy, in its own file, because this used to be two: a `remoteKeyToLocalPath`
+ * in `fixHandlers` and a `galleryKeyToLocalPath` in `createFixPatch`, each
+ * normalising the key correctly and each then treating the result as a file that
+ * must exist. That agreement is what made a published remote image report as
+ * missing from both sides at once.
+ */
+
+/**
+ * A key that names somewhere else, whether or not it is a ref we can read.
+ *
+ * Case-insensitive, because a scheme is (RFC 3986) — and because
+ * `splitRemoteRef`'s pattern is not, so `HTTPS://…` is precisely one of the
+ * spellings that arrives here unparsed and must not be mistaken for a path.
+ */
+function isRemoteUrl(key) {
+  return /^https?:\/\//i.test(key);
+}
+function galleryEntryOf(key) {
+  const remoteRefRes = core.Internal.remote.splitRemoteRef(key);
+  if (remoteRefRes.status === "success") {
+    return {
+      localPath: `/${remoteRefRes.filePath}`,
+      remote: true
+    };
+  }
+  if (isRemoteUrl(key)) {
+    // A URL that is not a ref this version can read: truncated by a hand edit,
+    // a path outside `public/`, a `..` segment — or written by a core version
+    // whose format `splitRemoteRef` rejects.
+    //
+    // Still not a path in the working tree, so the on-disk checks must not run
+    // against it. They would find nothing at `<projectRoot>/https://…`, report
+    // the entry as missing, and `--fix` would DELETE it — the exact failure
+    // this module exists to prevent, arriving at the one moment the key is the
+    // only remaining record of where the bytes went.
+    //
+    // Nothing is being hidden by this: a malformed key is already reported, by
+    // the record schema's own "Invalid remote URL format". That is an error for
+    // a person to look at, not a file for `--fix` to go missing.
+    return {
+      localPath: key,
+      remote: true
+    };
+  }
+  return {
+    localPath: key,
+    remote: false
+  };
+}
+
 /**
  * The media path a validation error is about, if it is about media at all.
  *
@@ -13701,14 +13767,6 @@ async function downloadFileFromRemote(ref, filePath) {
 // record-level fix expands into per-entry errors that should point at the
 // individual entry (e.g. `?p="/public/val/logo.png"`) rather than the record.
 
-// Gallery entries are keyed by their file path. Remote galleries key uploaded
-// entries by a remote URL while keeping the file on disk at its local path, so
-// normalize a remote-URL key back to that local path for on-disk reads.
-function galleryKeyToLocalPath(key) {
-  const res = core.Internal.remote.splitRemoteRef(key);
-  return res.status === "success" ? `/${res.filePath}` : key;
-}
-
 // Patch path of the record that holds a media entry. Media keys are file paths
 // that can contain dots, which sourceToPatchPath cannot round-trip, so strip
 // the (JSON-encoded) key segment off the entry source path and convert the
@@ -14017,7 +14075,18 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
       }
       const gallerySource = moduleSource;
       for (const [entryKey, storedEntry] of Object.entries(gallerySource)) {
-        const filename = path__namespace["default"].join(config.projectRoot, galleryKeyToLocalPath(entryKey));
+        const entry = galleryEntryOf(entryKey);
+        if (entry.remote) {
+          // A remote entry's bytes are on the content host, so there may be no
+          // local file to re-derive its metadata from — and where there is one,
+          // rewriting the metadata from it would invalidate the ref, which has
+          // that metadata baked into its validation hash. Whether a remote
+          // entry is sound is `image:check-remote`'s question, and it already
+          // asks it. Reading the file here reported every published remote
+          // image as unreadable, and with `--fix` REMOVED it from the gallery.
+          continue;
+        }
+        const filename = path__namespace["default"].join(config.projectRoot, entry.localPath);
         let buffer;
         try {
           buffer = fs__default["default"].readFileSync(filename);
@@ -14683,15 +14752,48 @@ async function handleUniqueFolderCheck(ctx) {
   };
 }
 
-// Maps a gallery key to its on-disk local path. Remote galleries key uploaded
-// entries by a remote URL while keeping the file on disk; everything else is
-// already a local path and is returned unchanged.
-function remoteKeyToLocalPath(key) {
-  const remoteRefRes = core.Internal.remote.splitRemoteRef(key);
-  if (remoteRefRes.status === "success") {
-    return `/${remoteRefRes.filePath}`;
+/**
+ * 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.
+ */
+function checkGalleryFiles(input) {
+  const {
+    directory,
+    projectRoot,
+    fs
+  } = input;
+  const entries = input.entryKeys.map(galleryEntryOf);
+  const trackedFiles = new Set(entries.map(entry => entry.localPath));
+  const missingTrackedFiles = entries.filter(entry => !entry.remote && !fs.fileExists(path__namespace["default"].join(projectRoot, entry.localPath))).map(entry => entry.localPath);
+  const filesInDir = [];
+  try {
+    const found = fs.readDirectory(path__namespace["default"].join(projectRoot, directory), undefined, undefined, ["**/*"]);
+    for (const entry of found) {
+      filesInDir.push("/" + path__namespace["default"].relative(projectRoot, entry).split(path__namespace["default"].sep).join("/"));
+    }
+  } catch {
+    // directory doesn't exist — no untracked files possible
   }
-  return key;
+  return {
+    missingTrackedFiles,
+    untrackedFiles: filesInDir.filter(f => !trackedFiles.has(f))
+  };
 }
 async function handleCheckAllFiles(ctx) {
   const value = ctx.validationError.value;
@@ -14711,14 +14813,14 @@ async function handleCheckAllFiles(ctx) {
       errorMessage: `Could not get source for ${ctx.sourcePath}`
     };
   }
-  // Gallery entries are keyed by their file path. Remote galleries key uploaded
-  // entries by a remote URL, but the file is kept on disk at its local path, so
-  // normalize remote-URL keys back to that local path for the on-disk checks.
-  const trackedFiles = new Set(Object.keys(source).map(remoteKeyToLocalPath));
-
-  // Check that all tracked files exist on disk
-  const missingTrackedFiles = Array.from(trackedFiles).filter(f => {
-    return !ctx.fs.fileExists(path__namespace["default"].join(ctx.projectRoot, f));
+  const {
+    missingTrackedFiles,
+    untrackedFiles
+  } = checkGalleryFiles({
+    entryKeys: Object.keys(source),
+    directory,
+    projectRoot: ctx.projectRoot,
+    fs: ctx.fs
   });
   if (missingTrackedFiles.length > 0) {
     if (!ctx.fix) {
@@ -14733,18 +14835,6 @@ async function handleCheckAllFiles(ctx) {
       shouldApplyPatch: true
     };
   }
-  const dirPath = path__namespace["default"].join(ctx.projectRoot, directory);
-  const filesInDir = [];
-  try {
-    const entries = ctx.fs.readDirectory(dirPath, undefined, undefined, ["**/*"]);
-    for (const entry of entries) {
-      const relPath = "/" + path__namespace["default"].relative(ctx.projectRoot, entry).split(path__namespace["default"].sep).join("/");
-      filesInDir.push(relPath);
-    }
-  } catch {
-    // directory doesn't exist — no untracked files possible
-  }
-  const untrackedFiles = filesInDir.filter(f => !trackedFiles.has(f));
   if (untrackedFiles.length > 0) {
     return {
       success: false,

package/dist/valbuild-server.cjs.prod.js

@@ -13506,6 +13506,72 @@ async function extractFileMetadata(filename, _input // TODO: use buffer to deter
   };
 }
 
+/**
+ * A gallery entry's key, read as what it actually is.
+ *
+ * A gallery is a record keyed by its entries' file paths. A REMOTE gallery keys
+ * an uploaded entry by the remote URL instead — which encodes that same path —
+ * so every entry has a local path, and the interesting question is whether the
+ * bytes are expected to be at it.
+ *
+ * **They are not, for a remote entry added the ordinary way.** `saveOrUploadFiles`
+ * uploads the remote descriptors to the content host and copies only the local
+ * ones into the working tree, so an image added through the Studio (or over MCP)
+ * and published has no file in the repo, by design — putting one there is what
+ * remote storage exists to avoid. A remote entry CAN have one, because
+ * `val validate --fix` promotes a local file to a remote ref and leaves the file
+ * where it was; so "remote" means "do not require it", never "there is not one".
+ *
+ * One copy, in its own file, because this used to be two: a `remoteKeyToLocalPath`
+ * in `fixHandlers` and a `galleryKeyToLocalPath` in `createFixPatch`, each
+ * normalising the key correctly and each then treating the result as a file that
+ * must exist. That agreement is what made a published remote image report as
+ * missing from both sides at once.
+ */
+
+/**
+ * A key that names somewhere else, whether or not it is a ref we can read.
+ *
+ * Case-insensitive, because a scheme is (RFC 3986) — and because
+ * `splitRemoteRef`'s pattern is not, so `HTTPS://…` is precisely one of the
+ * spellings that arrives here unparsed and must not be mistaken for a path.
+ */
+function isRemoteUrl(key) {
+  return /^https?:\/\//i.test(key);
+}
+function galleryEntryOf(key) {
+  const remoteRefRes = core.Internal.remote.splitRemoteRef(key);
+  if (remoteRefRes.status === "success") {
+    return {
+      localPath: `/${remoteRefRes.filePath}`,
+      remote: true
+    };
+  }
+  if (isRemoteUrl(key)) {
+    // A URL that is not a ref this version can read: truncated by a hand edit,
+    // a path outside `public/`, a `..` segment — or written by a core version
+    // whose format `splitRemoteRef` rejects.
+    //
+    // Still not a path in the working tree, so the on-disk checks must not run
+    // against it. They would find nothing at `<projectRoot>/https://…`, report
+    // the entry as missing, and `--fix` would DELETE it — the exact failure
+    // this module exists to prevent, arriving at the one moment the key is the
+    // only remaining record of where the bytes went.
+    //
+    // Nothing is being hidden by this: a malformed key is already reported, by
+    // the record schema's own "Invalid remote URL format". That is an error for
+    // a person to look at, not a file for `--fix` to go missing.
+    return {
+      localPath: key,
+      remote: true
+    };
+  }
+  return {
+    localPath: key,
+    remote: false
+  };
+}
+
 /**
  * The media path a validation error is about, if it is about media at all.
  *
@@ -13701,14 +13767,6 @@ async function downloadFileFromRemote(ref, filePath) {
 // record-level fix expands into per-entry errors that should point at the
 // individual entry (e.g. `?p="/public/val/logo.png"`) rather than the record.
 
-// Gallery entries are keyed by their file path. Remote galleries key uploaded
-// entries by a remote URL while keeping the file on disk at its local path, so
-// normalize a remote-URL key back to that local path for on-disk reads.
-function galleryKeyToLocalPath(key) {
-  const res = core.Internal.remote.splitRemoteRef(key);
-  return res.status === "success" ? `/${res.filePath}` : key;
-}
-
 // Patch path of the record that holds a media entry. Media keys are file paths
 // that can contain dots, which sourceToPatchPath cannot round-trip, so strip
 // the (JSON-encoded) key segment off the entry source path and convert the
@@ -14017,7 +14075,18 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
       }
       const gallerySource = moduleSource;
       for (const [entryKey, storedEntry] of Object.entries(gallerySource)) {
-        const filename = path__namespace["default"].join(config.projectRoot, galleryKeyToLocalPath(entryKey));
+        const entry = galleryEntryOf(entryKey);
+        if (entry.remote) {
+          // A remote entry's bytes are on the content host, so there may be no
+          // local file to re-derive its metadata from — and where there is one,
+          // rewriting the metadata from it would invalidate the ref, which has
+          // that metadata baked into its validation hash. Whether a remote
+          // entry is sound is `image:check-remote`'s question, and it already
+          // asks it. Reading the file here reported every published remote
+          // image as unreadable, and with `--fix` REMOVED it from the gallery.
+          continue;
+        }
+        const filename = path__namespace["default"].join(config.projectRoot, entry.localPath);
         let buffer;
         try {
           buffer = fs__default["default"].readFileSync(filename);
@@ -14683,15 +14752,48 @@ async function handleUniqueFolderCheck(ctx) {
   };
 }
 
-// Maps a gallery key to its on-disk local path. Remote galleries key uploaded
-// entries by a remote URL while keeping the file on disk; everything else is
-// already a local path and is returned unchanged.
-function remoteKeyToLocalPath(key) {
-  const remoteRefRes = core.Internal.remote.splitRemoteRef(key);
-  if (remoteRefRes.status === "success") {
-    return `/${remoteRefRes.filePath}`;
+/**
+ * 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.
+ */
+function checkGalleryFiles(input) {
+  const {
+    directory,
+    projectRoot,
+    fs
+  } = input;
+  const entries = input.entryKeys.map(galleryEntryOf);
+  const trackedFiles = new Set(entries.map(entry => entry.localPath));
+  const missingTrackedFiles = entries.filter(entry => !entry.remote && !fs.fileExists(path__namespace["default"].join(projectRoot, entry.localPath))).map(entry => entry.localPath);
+  const filesInDir = [];
+  try {
+    const found = fs.readDirectory(path__namespace["default"].join(projectRoot, directory), undefined, undefined, ["**/*"]);
+    for (const entry of found) {
+      filesInDir.push("/" + path__namespace["default"].relative(projectRoot, entry).split(path__namespace["default"].sep).join("/"));
+    }
+  } catch {
+    // directory doesn't exist — no untracked files possible
   }
-  return key;
+  return {
+    missingTrackedFiles,
+    untrackedFiles: filesInDir.filter(f => !trackedFiles.has(f))
+  };
 }
 async function handleCheckAllFiles(ctx) {
   const value = ctx.validationError.value;
@@ -14711,14 +14813,14 @@ async function handleCheckAllFiles(ctx) {
       errorMessage: `Could not get source for ${ctx.sourcePath}`
     };
   }
-  // Gallery entries are keyed by their file path. Remote galleries key uploaded
-  // entries by a remote URL, but the file is kept on disk at its local path, so
-  // normalize remote-URL keys back to that local path for the on-disk checks.
-  const trackedFiles = new Set(Object.keys(source).map(remoteKeyToLocalPath));
-
-  // Check that all tracked files exist on disk
-  const missingTrackedFiles = Array.from(trackedFiles).filter(f => {
-    return !ctx.fs.fileExists(path__namespace["default"].join(ctx.projectRoot, f));
+  const {
+    missingTrackedFiles,
+    untrackedFiles
+  } = checkGalleryFiles({
+    entryKeys: Object.keys(source),
+    directory,
+    projectRoot: ctx.projectRoot,
+    fs: ctx.fs
   });
   if (missingTrackedFiles.length > 0) {
     if (!ctx.fix) {
@@ -14733,18 +14835,6 @@ async function handleCheckAllFiles(ctx) {
       shouldApplyPatch: true
     };
   }
-  const dirPath = path__namespace["default"].join(ctx.projectRoot, directory);
-  const filesInDir = [];
-  try {
-    const entries = ctx.fs.readDirectory(dirPath, undefined, undefined, ["**/*"]);
-    for (const entry of entries) {
-      const relPath = "/" + path__namespace["default"].relative(ctx.projectRoot, entry).split(path__namespace["default"].sep).join("/");
-      filesInDir.push(relPath);
-    }
-  } catch {
-    // directory doesn't exist — no untracked files possible
-  }
-  const untrackedFiles = filesInDir.filter(f => !trackedFiles.has(f));
   if (untrackedFiles.length > 0) {
     return {
       success: false,

package/dist/valbuild-server.esm.js

@@ -13472,6 +13472,72 @@ async function extractFileMetadata(filename, _input // TODO: use buffer to deter
   };
 }
 
+/**
+ * A gallery entry's key, read as what it actually is.
+ *
+ * A gallery is a record keyed by its entries' file paths. A REMOTE gallery keys
+ * an uploaded entry by the remote URL instead — which encodes that same path —
+ * so every entry has a local path, and the interesting question is whether the
+ * bytes are expected to be at it.
+ *
+ * **They are not, for a remote entry added the ordinary way.** `saveOrUploadFiles`
+ * uploads the remote descriptors to the content host and copies only the local
+ * ones into the working tree, so an image added through the Studio (or over MCP)
+ * and published has no file in the repo, by design — putting one there is what
+ * remote storage exists to avoid. A remote entry CAN have one, because
+ * `val validate --fix` promotes a local file to a remote ref and leaves the file
+ * where it was; so "remote" means "do not require it", never "there is not one".
+ *
+ * One copy, in its own file, because this used to be two: a `remoteKeyToLocalPath`
+ * in `fixHandlers` and a `galleryKeyToLocalPath` in `createFixPatch`, each
+ * normalising the key correctly and each then treating the result as a file that
+ * must exist. That agreement is what made a published remote image report as
+ * missing from both sides at once.
+ */
+
+/**
+ * A key that names somewhere else, whether or not it is a ref we can read.
+ *
+ * Case-insensitive, because a scheme is (RFC 3986) — and because
+ * `splitRemoteRef`'s pattern is not, so `HTTPS://…` is precisely one of the
+ * spellings that arrives here unparsed and must not be mistaken for a path.
+ */
+function isRemoteUrl(key) {
+  return /^https?:\/\//i.test(key);
+}
+function galleryEntryOf(key) {
+  const remoteRefRes = Internal.remote.splitRemoteRef(key);
+  if (remoteRefRes.status === "success") {
+    return {
+      localPath: `/${remoteRefRes.filePath}`,
+      remote: true
+    };
+  }
+  if (isRemoteUrl(key)) {
+    // A URL that is not a ref this version can read: truncated by a hand edit,
+    // a path outside `public/`, a `..` segment — or written by a core version
+    // whose format `splitRemoteRef` rejects.
+    //
+    // Still not a path in the working tree, so the on-disk checks must not run
+    // against it. They would find nothing at `<projectRoot>/https://…`, report
+    // the entry as missing, and `--fix` would DELETE it — the exact failure
+    // this module exists to prevent, arriving at the one moment the key is the
+    // only remaining record of where the bytes went.
+    //
+    // Nothing is being hidden by this: a malformed key is already reported, by
+    // the record schema's own "Invalid remote URL format". That is an error for
+    // a person to look at, not a file for `--fix` to go missing.
+    return {
+      localPath: key,
+      remote: true
+    };
+  }
+  return {
+    localPath: key,
+    remote: false
+  };
+}
+
 /**
  * The media path a validation error is about, if it is about media at all.
  *
@@ -13667,14 +13733,6 @@ async function downloadFileFromRemote(ref, filePath) {
 // record-level fix expands into per-entry errors that should point at the
 // individual entry (e.g. `?p="/public/val/logo.png"`) rather than the record.
 
-// Gallery entries are keyed by their file path. Remote galleries key uploaded
-// entries by a remote URL while keeping the file on disk at its local path, so
-// normalize a remote-URL key back to that local path for on-disk reads.
-function galleryKeyToLocalPath(key) {
-  const res = Internal.remote.splitRemoteRef(key);
-  return res.status === "success" ? `/${res.filePath}` : key;
-}
-
 // Patch path of the record that holds a media entry. Media keys are file paths
 // that can contain dots, which sourceToPatchPath cannot round-trip, so strip
 // the (JSON-encoded) key segment off the entry source path and convert the
@@ -13983,7 +14041,18 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
       }
       const gallerySource = moduleSource;
       for (const [entryKey, storedEntry] of Object.entries(gallerySource)) {
-        const filename = path__default.join(config.projectRoot, galleryKeyToLocalPath(entryKey));
+        const entry = galleryEntryOf(entryKey);
+        if (entry.remote) {
+          // A remote entry's bytes are on the content host, so there may be no
+          // local file to re-derive its metadata from — and where there is one,
+          // rewriting the metadata from it would invalidate the ref, which has
+          // that metadata baked into its validation hash. Whether a remote
+          // entry is sound is `image:check-remote`'s question, and it already
+          // asks it. Reading the file here reported every published remote
+          // image as unreadable, and with `--fix` REMOVED it from the gallery.
+          continue;
+        }
+        const filename = path__default.join(config.projectRoot, entry.localPath);
         let buffer;
         try {
           buffer = fs.readFileSync(filename);
@@ -14649,15 +14718,48 @@ async function handleUniqueFolderCheck(ctx) {
   };
 }
 
-// Maps a gallery key to its on-disk local path. Remote galleries key uploaded
-// entries by a remote URL while keeping the file on disk; everything else is
-// already a local path and is returned unchanged.
-function remoteKeyToLocalPath(key) {
-  const remoteRefRes = Internal.remote.splitRemoteRef(key);
-  if (remoteRefRes.status === "success") {
-    return `/${remoteRefRes.filePath}`;
+/**
+ * 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.
+ */
+function checkGalleryFiles(input) {
+  const {
+    directory,
+    projectRoot,
+    fs
+  } = input;
+  const entries = input.entryKeys.map(galleryEntryOf);
+  const trackedFiles = new Set(entries.map(entry => entry.localPath));
+  const missingTrackedFiles = entries.filter(entry => !entry.remote && !fs.fileExists(path__default.join(projectRoot, entry.localPath))).map(entry => entry.localPath);
+  const filesInDir = [];
+  try {
+    const found = fs.readDirectory(path__default.join(projectRoot, directory), undefined, undefined, ["**/*"]);
+    for (const entry of found) {
+      filesInDir.push("/" + path__default.relative(projectRoot, entry).split(path__default.sep).join("/"));
+    }
+  } catch {
+    // directory doesn't exist — no untracked files possible
   }
-  return key;
+  return {
+    missingTrackedFiles,
+    untrackedFiles: filesInDir.filter(f => !trackedFiles.has(f))
+  };
 }
 async function handleCheckAllFiles(ctx) {
   const value = ctx.validationError.value;
@@ -14677,14 +14779,14 @@ async function handleCheckAllFiles(ctx) {
       errorMessage: `Could not get source for ${ctx.sourcePath}`
     };
   }
-  // Gallery entries are keyed by their file path. Remote galleries key uploaded
-  // entries by a remote URL, but the file is kept on disk at its local path, so
-  // normalize remote-URL keys back to that local path for the on-disk checks.
-  const trackedFiles = new Set(Object.keys(source).map(remoteKeyToLocalPath));
-
-  // Check that all tracked files exist on disk
-  const missingTrackedFiles = Array.from(trackedFiles).filter(f => {
-    return !ctx.fs.fileExists(path__default.join(ctx.projectRoot, f));
+  const {
+    missingTrackedFiles,
+    untrackedFiles
+  } = checkGalleryFiles({
+    entryKeys: Object.keys(source),
+    directory,
+    projectRoot: ctx.projectRoot,
+    fs: ctx.fs
   });
   if (missingTrackedFiles.length > 0) {
     if (!ctx.fix) {
@@ -14699,18 +14801,6 @@ async function handleCheckAllFiles(ctx) {
       shouldApplyPatch: true
     };
   }
-  const dirPath = path__default.join(ctx.projectRoot, directory);
-  const filesInDir = [];
-  try {
-    const entries = ctx.fs.readDirectory(dirPath, undefined, undefined, ["**/*"]);
-    for (const entry of entries) {
-      const relPath = "/" + path__default.relative(ctx.projectRoot, entry).split(path__default.sep).join("/");
-      filesInDir.push(relPath);
-    }
-  } catch {
-    // directory doesn't exist — no untracked files possible
-  }
-  const untrackedFiles = filesInDir.filter(f => !trackedFiles.has(f));
   if (untrackedFiles.length > 0) {
     return {
       success: false,

package/package.json

@@ -16,7 +16,7 @@
     "./package.json": "./package.json"
   },
   "types": "dist/valbuild-server.cjs.d.ts",
-  "version": "0.123.0",
+  "version": "0.123.2",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"
@@ -29,9 +29,9 @@
     "typescript": "^6.0.3",
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
+    "@valbuild/shared": "0.123.2",
     "@valbuild/core": "0.121.0",
-    "@valbuild/shared": "0.123.0",
-    "@valbuild/ui": "0.123.0"
+    "@valbuild/ui": "0.123.2"
   },
   "engines": {
     "node": "^20.19.0 || >=22"