@valbuild/server 0.123.0 → 0.123.3

package/dist/valbuild-server.esm.js

@@ -1,7 +1,7 @@
 import ts from 'typescript';
 import { pipe, result, array } from '@valbuild/core/fp';
 import { PatchError, deepEqual, parseAndValidateArrayIndex, isNotRoot, applyPatch, JSONOps, deepClone, sourceToPatchPath } from '@valbuild/core/patch';
-import { derefPatch, Internal, RecordSchema, extractValModules, computeValModuleShas, VAL_EXTENSION, ImageSchema, DEFAULT_CONTENT_HOST, hasRemoteFileSchema } from '@valbuild/core';
+import { derefPatch, Internal, extractValModules, computeValModuleShas, VAL_EXTENSION, ImageSchema, DEFAULT_CONTENT_HOST, hasRemoteFileSchema } from '@valbuild/core';
 export { hasRemoteFileSchema } from '@valbuild/core';
 import * as path from 'path';
 import path__default from 'path';
@@ -1368,6 +1368,43 @@ function resolveExistingJsonPath(moduleFilePath, importPath) {
  * only way to avoid loading every entry twice.
  */
 
+/**
+ * The part of a `.jsonValues()` record this file calls. Named structurally
+ * because the value may not be an instance of *this* copy of `RecordSchema` —
+ * see {@link isJsonValuesRecord}.
+ */
+
+/**
+ * Is this a `.jsonValues()` record?
+ *
+ * NOT `schema instanceof RecordSchema`, and the distinction is the whole point.
+ * `loadValModules` evaluates the project's `*.val.ts` with a `require` rooted at
+ * the PROJECT, deliberately, so the schemas are built by whatever
+ * `@valbuild/core` the project resolves. When the CLI is itself installed in
+ * that project, that is this very module and `instanceof` holds. When it is run
+ * through `npx` / `pnpm dlx`, the tool gets its own copy of `@valbuild/core`
+ * beside the project's, and `instanceof` is false for a record that is a record
+ * in every way that matters — same class name, same serialized schema, same
+ * methods, different realm.
+ *
+ * That failed OPEN: the whole check returned "no errors", so
+ * `npx @valbuild/cli validate` called a module with un-extracted entries VALID
+ * and a CI gate on it was green for the wrong reason. `loadValModules` avoids
+ * constructor checks for exactly this reason and says so; this one was the
+ * exception.
+ *
+ * `validateJsonEntryContent` is declared by `RecordSchema` and by nothing else,
+ * so it is the brand — and checking it first keeps the cheap short-circuit
+ * `instanceof` gave us, rather than serializing every non-record schema.
+ */
+function isJsonValuesRecord(schema) {
+  if (!("validateJsonEntryContent" in schema) || typeof schema.validateJsonEntryContent !== "function") {
+    return false;
+  }
+  const serialized = schema["executeSerialize"]();
+  return serialized.type === "record" && serialized.jsonValues === true;
+}
+
 /**
  * Validates the content of every `.jsonValues()` entry in a module by loading
  * each backing `*.val.json` (via its lazy import thunk) and checking it against
@@ -1425,10 +1462,7 @@ async function validateJsonValuesEntries(schema, source, modulePath) {
     errors: out,
     loadedEntries
   };
-  if (!(schema instanceof RecordSchema)) {
-    return res;
-  }
-  if (!schema["executeSerialize"]().jsonValues) {
+  if (!isJsonValuesRecord(schema)) {
     return res;
   }
   if (source === null || typeof source !== "object" || Array.isArray(source)) {
@@ -13472,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 = 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 +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 = 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 +14075,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);
@@ -14197,37 +14300,50 @@ async function getFileMetadata(projectRoot, validationError) {
 }
 
 /**
- * Moves ONE `.jsonValues()` entry that was written inline in the `.val.ts` into
- * its own `*.val.json`, replacing the inline value with
- * `c.json(() => import("./<key>.val.json"))`.
+ * The two files an extraction touches, as text — nothing written yet.
  *
- * This is the fix for the `jsonValues:extract-entry` validation error. It is not
- * expressible as a patch (a patch edits one `.val.ts` and cannot create the
- * backing JSON file), so it writes both files directly — JSON first, so a
- * failure part-way through never leaves the module pointing at a file that does
- * not exist.
+ * Both paths are project-relative in the `ModuleFilePath` style (a leading
+ * slash), because that is what the callers already hold and what
+ * {@link getNewJsonEntryPaths} derives. Join them onto the project root to get
+ * somewhere to write.
+ */
+
+/**
+ * Works out what moving ONE inline `.jsonValues()` entry into its own
+ * `*.val.json` would change, without changing anything.
+ *
+ * This is the whole fix for `jsonValues:extract-entry`, minus the writing. It
+ * is split out because the two callers cannot share a way of applying it: the
+ * CLI writes both files ({@link extractJsonValuesEntry}), while the editor has
+ * to hand the same two changes back as a `WorkspaceEdit` so they go through the
+ * undo stack and respect an unsaved buffer. Anything that lived in only one of
+ * those would be a fix that behaves differently depending on where it was
+ * invoked from, which is exactly the drift `codeActions.ts` exists to prevent.
+ *
+ * It does NOT check whether `jsonPath` already exists: that needs a filesystem,
+ * and the editor's answer ("is there a buffer or a file here?") is not the
+ * CLI's. Every caller must check before writing — overwriting an unrelated file
+ * is not a fix.
  *
  * Root-only, like the rest of the `.jsonValues()` machinery: the entry is looked
  * up in the module's root record/router object literal.
  */
-function extractJsonValuesEntry(moduleFilePath, rootDir, entryKey, content, sourceFileHandler) {
-  const valTsPath = sourceFileHandler.resolveSourceModulePath(getSyntheticContainingPath(rootDir), `.${moduleFilePath.replace(".val.ts", ".val").replace(".val.js", ".val").replace(".val.jsx", ".val").replace(".val.tsx", ".val")}`);
-  const sourceFile = sourceFileHandler.getSourceFile(valTsPath);
-  if (!sourceFile) {
-    throw Error(`Source file ${valTsPath} not found`);
-  }
+function planJsonValuesEntryExtraction({
+  moduleFilePath,
+  entryKey,
+  content,
+  valTsPath,
+  valTsText
+}) {
   const pathsRes = getNewJsonEntryPaths(moduleFilePath, entryKey);
   if (result.isErr(pathsRes)) {
-    throw Error(formatPatchSourceError(pathsRes.error));
+    return result.err(formatPatchSourceError(pathsRes.error));
   }
   const {
     jsonPath,
     importPath
   } = pathsRes.value;
-  const absoluteJsonPath = path__default.join(rootDir, jsonPath);
-  if (sourceFileHandler.host.fileExists(absoluteJsonPath)) {
-    throw Error(`Cannot extract .jsonValues() entry '${entryKey}' of ${moduleFilePath}: '${jsonPath}' already exists`);
-  }
+  const sourceFile = ts.createSourceFile(valTsPath, valTsText, ts.ScriptTarget.ES2020);
 
   // Remove the inline property, then add the `c.json(...)` reference back. The
   // entry moves to the end of the record: entry ORDER in a jsonValues record is
@@ -14235,14 +14351,70 @@ function extractJsonValuesEntry(moduleFilePath, rootDir, entryKey, content, sour
   // insert-in-place would mean reimplementing insertValJsonEntry.
   const removed = removeValJsonEntry(sourceFile, [], entryKey);
   if (result.isErr(removed)) {
-    throw Error(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
+    return result.err(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
   }
   const inserted = insertValJsonEntry(removed.value, [], entryKey, importPath);
   if (result.isErr(inserted)) {
-    throw Error(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
+    return result.err(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
+  }
+  return result.ok({
+    jsonPath,
+    jsonContent: JSON.stringify(content, null, 2) + "\n",
+    valTsPath,
+    valTsContent: printSourceFile(inserted.value)
+  });
+}
+
+/**
+ * Moves ONE `.jsonValues()` entry that was written inline in the `.val.ts` into
+ * its own `*.val.json`, replacing the inline value with
+ * `c.json(() => import("./<key>.val.json"))`.
+ *
+ * The `val validate --fix` half of {@link planJsonValuesEntryExtraction}. It is
+ * not expressible as a patch (a patch edits one `.val.ts` and cannot create the
+ * backing JSON file), so it writes both files directly — JSON first, so a
+ * failure part-way through never leaves the module pointing at a file that does
+ * not exist.
+ */
+function extractJsonValuesEntry(moduleFilePath, rootDir, entryKey, content, sourceFileHandler) {
+  const valTsPath = sourceFileHandler.resolveSourceModulePath(getSyntheticContainingPath(rootDir), `.${moduleFilePath.replace(".val.ts", ".val").replace(".val.js", ".val").replace(".val.jsx", ".val").replace(".val.tsx", ".val")}`);
+  const valTsText = sourceFileHandler.host.readFile(valTsPath);
+  if (valTsText === undefined) {
+    throw Error(`Source file ${valTsPath} not found`);
   }
-  sourceFileHandler.writeFile(absoluteJsonPath, JSON.stringify(content, null, 2) + "\n", "utf8");
-  sourceFileHandler.writeSourceFile(inserted.value);
+  const planned = planJsonValuesEntryExtraction({
+    moduleFilePath,
+    entryKey,
+    content,
+    valTsPath,
+    valTsText
+  });
+  if (result.isErr(planned)) {
+    throw Error(planned.error);
+  }
+  const absoluteJsonPath = path__default.join(rootDir, planned.value.jsonPath);
+  if (sourceFileHandler.host.fileExists(absoluteJsonPath)) {
+    throw Error(`Cannot extract .jsonValues() entry '${entryKey}' of ${moduleFilePath}: '${planned.value.jsonPath}' already exists`);
+  }
+  sourceFileHandler.writeFile(absoluteJsonPath, planned.value.jsonContent, "utf8");
+  sourceFileHandler.writeFile(valTsPath, planned.value.valTsContent, "utf8");
+}
+
+/**
+ * The text of a source file the TS ops produced, exactly as
+ * `ValSourceFileHandler.writeSourceFile` would have written it.
+ *
+ * The unescape undoes the printer's `\uXXXX` output for non-ASCII. Today the
+ * ops splice printed text into `document.text` and this fix only ever prints an
+ * ASCII `c.json(() => import("./..."))`, so nothing here is escaped and the
+ * unescape is a no-op — but `neverAsciiEscape` is off in the printer, so that is
+ * a property of what this fix happens to print, not a guarantee. Kept because
+ * this replaced a `writeSourceFile` call and the text written must not change.
+ *
+ * https://github.com/microsoft/TypeScript/issues/36174
+ */
+function printSourceFile(sourceFile) {
+  return unescape(sourceFile.text.replace(/\\u/g, "%u"));
 }
 function formatOpsError(error, sourceFile) {
   if (error instanceof PatchError) {
@@ -14649,15 +14821,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 +14882,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 +14904,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,
@@ -15461,4 +15654,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleExternalUpload, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, isExternalResult, loadValModules, ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, resolveRemoteFileAuth, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };
+export { DEFAULT_LOGIN_EXPIRES_IN_SECONDS, DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_POLL_INTERVAL_SECONDS, EXTERNAL_RESULT, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, classifyJsonValuesOp, compareWithCapturedReport, createDefaultValFSHost, createFixPatch, createJsonEntryPathMap, createModulePathMap, createService, createValApiRouter, createValModuleFileInspector, createValOps, createValServer, currentFixHandlers, decodeJwtWithoutVerifying, defineExternal, describePatchStoreProblems, downloadFileFromRemote, encodeJwt, err, evalValConfigFile, extractFileMetadata, extractImageMetadata, extractJsonValuesEntry, findAndEvalValConfigFile, findJsonEntryFilePath, fixHandlers, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, handleCheckAllFiles, handleExternalUpload, handleFileMetadata, handleJsonValuesExtractEntry, handleRemoteFileCheck, handleRemoteFileDownload, handleRemoteFileUpload, handleRemoteGalleryFileUpload, handleUniqueFolderCheck, initHandlerOptions, isExternalResult, loadValModules, ok, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, planJsonValuesEntryExtraction, readCapturedReport, readPatchStore, rebaseContentOp, replaySnapshot, resolveRemoteFileAuth, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata, verifyJwt };

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.3",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"
@@ -30,8 +30,8 @@
     "zod": "^4.4.3",
     "zod-validation-error": "^5.0.0",
     "@valbuild/core": "0.121.0",
-    "@valbuild/shared": "0.123.0",
-    "@valbuild/ui": "0.123.0"
+    "@valbuild/ui": "0.123.3",
+    "@valbuild/shared": "0.123.3"
   },
   "engines": {
     "node": "^20.19.0 || >=22"