@valbuild/server 0.123.2 → 0.123.3

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @valbuild/server
 
+## 0.123.3
+
+### Patch Changes
+
+- [#623](https://github.com/valbuild/val/pull/623) [`4c9369b`](https://github.com/valbuild/val/commit/4c9369bad3f17e96868262e78a4f47361d85319e) Thanks [@freekh](https://github.com/freekh)! - Add the editor quick fix for a `.jsonValues()` entry written inline: **Val: move entry into its own .val.json**.
+
+  The language server already reported the problem — "Entry '…' is written inline … Run 'val validate --fix' to move it" — but offered no way to act on it, so the only remedy was to leave the editor and run the CLI. It now offers a quick fix that creates the `*.val.json` with the entry's content and rewrites the `.val.ts` to `c.json(() => import("./…"))`, in one undoable step.
+
+  The fix is computed from the same code `val validate --fix` runs, so the two write the same files, and it is computed against the buffer you are looking at rather than what is on disk — an unsaved module can be fixed without saving first. It refuses, rather than overwriting, when a file or an unsaved buffer already occupies the target path.
+
+  Requires an editor that honours file creation inside a workspace edit; VS Code does. In an editor that does not announce it, no action is offered rather than one that would rewrite the module to import a file that never got created.
+
+- [#621](https://github.com/valbuild/val/pull/621) [`fb1baff`](https://github.com/valbuild/val/commit/fb1baffead5228d8a86a51af65178b88738d5a64) Thanks [@freekh](https://github.com/freekh)! - Fix `.jsonValues()` validation being silently skipped when the CLI is run through `npx` / `pnpm dlx`.
+
+  `npx @valbuild/cli validate` reported a `.jsonValues()` module whose entries were still written inline in the `.val.ts` as **valid**, and `--fix` moved nothing into `*.val.json`. Running the CLI installed in the project (`./node_modules/.bin/val validate --fix`) worked, which made this look like a schema or path problem rather than a tooling one.
+
+  The cause: the project's `*.val.ts` are evaluated with a `require` rooted at the project, so their schemas come from the project's `@valbuild/core`, while `npx`/`dlx` runs the CLI's own second copy. The entry check guarded on `schema instanceof RecordSchema`, which is false across those two copies, and it failed open — the whole check returned "no errors". The guard is now structural, so it holds whichever copy built the schema. If you gate CI on `npx @valbuild/cli validate`, that gate was green for the wrong reason.
+
+- Updated dependencies [[`accf4f8`](https://github.com/valbuild/val/commit/accf4f852fe3400d762cc14e80316da741a69a9a), [`356eb11`](https://github.com/valbuild/val/commit/356eb11b5f6a0a02dfec80580c6fccac75d28402), [`aef45ce`](https://github.com/valbuild/val/commit/aef45ce3ef269f1b6221de44a56df0f6a0d9dbbd)]:
+  - @valbuild/shared@0.123.3
+  - @valbuild/ui@0.123.3
+
 ## 0.123.2
 
 ### Patch Changes

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

@@ -1,17 +1,61 @@
 import type { Json, ModuleFilePath } from "@valbuild/core";
+import { result } from "@valbuild/core/fp";
 import { ValSourceFileHandler } from "./ValSourceFileHandler.js";
+/**
+ * The two files an extraction touches, as text — nothing written yet.
+ *
+ * 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.
+ */
+export type JsonValuesEntryExtraction = {
+    /** The `*.val.json` to CREATE. It must not already exist — see the note below. */
+    jsonPath: string;
+    jsonContent: string;
+    /** The `.val.ts` to rewrite, and its complete new text. */
+    valTsPath: string;
+    valTsContent: string;
+};
+/**
+ * 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.
+ */
+export declare function planJsonValuesEntryExtraction({ moduleFilePath, entryKey, content, valTsPath, valTsText, }: {
+    moduleFilePath: ModuleFilePath;
+    entryKey: string;
+    /** The entry's value, as it is written inline in the `.val.ts`. */
+    content: Json;
+    /** Where the `.val.ts` lives, for error messages. */
+    valTsPath: string;
+    /** Its text — the editor's version of it, where there is an editor. */
+    valTsText: string;
+}): result.Result<JsonValuesEntryExtraction, string>;
 /**
  * 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"))`.
  *
- * 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
+ * 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.
- *
- * Root-only, like the rest of the `.jsonValues()` machinery: the entry is looked
- * up in the module's root record/router object literal.
  */
 export declare function extractJsonValuesEntry(moduleFilePath: ModuleFilePath, rootDir: string, entryKey: string, content: Json, sourceFileHandler: ValSourceFileHandler): void;

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

@@ -36,7 +36,8 @@ export { createModulePathMap, createJsonEntryPathMap, getModulePathRange, } from
 export { findJsonEntryFilePath } from "./jsonEntryLocation.js";
 export { classifyJsonValuesOp, rebaseContentOp } from "./patch/jsonValuesPatch.js";
 export type { JsonValuesOpClass } from "./patch/jsonValuesPatch.js";
-export { extractJsonValuesEntry } from "./extractJsonValuesEntry.js";
+export { extractJsonValuesEntry, planJsonValuesEntryExtraction, } from "./extractJsonValuesEntry.js";
+export type { JsonValuesEntryExtraction } from "./extractJsonValuesEntry.js";
 export type { ModulePathMap } from "./modulePathMap.js";
 export { ValOpsFS } from "./ValOpsFS.js";
 export { ValOpsHttp } from "./ValOpsHttp.js";

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

@@ -1402,6 +1402,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
@@ -1459,10 +1496,7 @@ async function validateJsonValuesEntries(schema, source, modulePath) {
     errors: out,
     loadedEntries
   };
-  if (!(schema instanceof core.RecordSchema)) {
-    return res;
-  }
-  if (!schema["executeSerialize"]().jsonValues) {
+  if (!isJsonValuesRecord(schema)) {
     return res;
   }
   if (source === null || typeof source !== "object" || Array.isArray(source)) {
@@ -14300,37 +14334,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 (fp.result.isErr(pathsRes)) {
-    throw Error(formatPatchSourceError(pathsRes.error));
+    return fp.result.err(formatPatchSourceError(pathsRes.error));
   }
   const {
     jsonPath,
     importPath
   } = pathsRes.value;
-  const absoluteJsonPath = path__namespace["default"].join(rootDir, jsonPath);
-  if (sourceFileHandler.host.fileExists(absoluteJsonPath)) {
-    throw Error(`Cannot extract .jsonValues() entry '${entryKey}' of ${moduleFilePath}: '${jsonPath}' already exists`);
-  }
+  const sourceFile = ts__default["default"].createSourceFile(valTsPath, valTsText, ts__default["default"].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
@@ -14338,14 +14385,70 @@ function extractJsonValuesEntry(moduleFilePath, rootDir, entryKey, content, sour
   // insert-in-place would mean reimplementing insertValJsonEntry.
   const removed = removeValJsonEntry(sourceFile, [], entryKey);
   if (fp.result.isErr(removed)) {
-    throw Error(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
+    return fp.result.err(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
   }
   const inserted = insertValJsonEntry(removed.value, [], entryKey, importPath);
   if (fp.result.isErr(inserted)) {
-    throw Error(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
+    return fp.result.err(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
+  }
+  return fp.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`);
+  }
+  const planned = planJsonValuesEntryExtraction({
+    moduleFilePath,
+    entryKey,
+    content,
+    valTsPath,
+    valTsText
+  });
+  if (fp.result.isErr(planned)) {
+    throw Error(planned.error);
+  }
+  const absoluteJsonPath = path__namespace["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, JSON.stringify(content, null, 2) + "\n", "utf8");
-  sourceFileHandler.writeSourceFile(inserted.value);
+  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 patch.PatchError) {
@@ -15655,6 +15758,7 @@ exports.ok = ok;
 exports.parsePersonalAccessTokenFile = parsePersonalAccessTokenFile;
 exports.patchSourceFile = patchSourceFile;
 exports.persistPersonalAccessToken = persistPersonalAccessToken;
+exports.planJsonValuesEntryExtraction = planJsonValuesEntryExtraction;
 exports.readCapturedReport = readCapturedReport;
 exports.readPatchStore = readPatchStore;
 exports.rebaseContentOp = rebaseContentOp;

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

@@ -1402,6 +1402,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
@@ -1459,10 +1496,7 @@ async function validateJsonValuesEntries(schema, source, modulePath) {
     errors: out,
     loadedEntries
   };
-  if (!(schema instanceof core.RecordSchema)) {
-    return res;
-  }
-  if (!schema["executeSerialize"]().jsonValues) {
+  if (!isJsonValuesRecord(schema)) {
     return res;
   }
   if (source === null || typeof source !== "object" || Array.isArray(source)) {
@@ -14300,37 +14334,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 (fp.result.isErr(pathsRes)) {
-    throw Error(formatPatchSourceError(pathsRes.error));
+    return fp.result.err(formatPatchSourceError(pathsRes.error));
   }
   const {
     jsonPath,
     importPath
   } = pathsRes.value;
-  const absoluteJsonPath = path__namespace["default"].join(rootDir, jsonPath);
-  if (sourceFileHandler.host.fileExists(absoluteJsonPath)) {
-    throw Error(`Cannot extract .jsonValues() entry '${entryKey}' of ${moduleFilePath}: '${jsonPath}' already exists`);
-  }
+  const sourceFile = ts__default["default"].createSourceFile(valTsPath, valTsText, ts__default["default"].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
@@ -14338,14 +14385,70 @@ function extractJsonValuesEntry(moduleFilePath, rootDir, entryKey, content, sour
   // insert-in-place would mean reimplementing insertValJsonEntry.
   const removed = removeValJsonEntry(sourceFile, [], entryKey);
   if (fp.result.isErr(removed)) {
-    throw Error(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
+    return fp.result.err(`${valTsPath}\n${formatOpsError(removed.error, sourceFile)}`);
   }
   const inserted = insertValJsonEntry(removed.value, [], entryKey, importPath);
   if (fp.result.isErr(inserted)) {
-    throw Error(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
+    return fp.result.err(`${valTsPath}\n${formatOpsError(inserted.error, removed.value)}`);
+  }
+  return fp.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`);
+  }
+  const planned = planJsonValuesEntryExtraction({
+    moduleFilePath,
+    entryKey,
+    content,
+    valTsPath,
+    valTsText
+  });
+  if (fp.result.isErr(planned)) {
+    throw Error(planned.error);
+  }
+  const absoluteJsonPath = path__namespace["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, JSON.stringify(content, null, 2) + "\n", "utf8");
-  sourceFileHandler.writeSourceFile(inserted.value);
+  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 patch.PatchError) {
@@ -15655,6 +15758,7 @@ exports.ok = ok;
 exports.parsePersonalAccessTokenFile = parsePersonalAccessTokenFile;
 exports.patchSourceFile = patchSourceFile;
 exports.persistPersonalAccessToken = persistPersonalAccessToken;
+exports.planJsonValuesEntryExtraction = planJsonValuesEntryExtraction;
 exports.readCapturedReport = readCapturedReport;
 exports.readPatchStore = readPatchStore;
 exports.rebaseContentOp = rebaseContentOp;

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)) {
@@ -14266,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
@@ -14304,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`);
+  }
+  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, JSON.stringify(content, null, 2) + "\n", "utf8");
-  sourceFileHandler.writeSourceFile(inserted.value);
+  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) {
@@ -15551,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.2",
+  "version": "0.123.3",
   "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/ui": "0.123.2"
+    "@valbuild/ui": "0.123.3",
+    "@valbuild/shared": "0.123.3"
   },
   "engines": {
     "node": "^20.19.0 || >=22"