@valbuild/server 0.123.2 → 0.124.0

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)) {
@@ -4084,6 +4118,17 @@ class ValOps {
 
   /** One file's bytes as they were at one commit. */
 
+  /**
+   * Where a module lives in the REPOSITORY, as `getFileAtCommit` wants it.
+   *
+   * A `ModuleFilePath` is project-relative (`/app/page.val.ts`); a git path is
+   * repository-relative and carries the project root in front of it
+   * (`examples/next/app/page.val.ts`). Only the ops know that root, which is
+   * why this is here rather than computed by the history functions - and why a
+   * history function that needs to read a module's own file at a commit has to
+   * ask instead of concatenating.
+   */
+
   // #endregion history
 }
 function isOnlyFileCheckValidationError(validationError) {
@@ -6729,6 +6774,14 @@ class ValOpsFS extends ValOps {
       kind: "not-supported-in-fs-mode"
     });
   }
+  gitPathOfModule(
+  // Unused: fs mode has no repository to be relative to. Named anyway, so
+  // this reads as the same method the base class declares.
+  _moduleFilePath) {
+    return fp.result.err({
+      kind: "not-supported-in-fs-mode"
+    });
+  }
   // #endregion history
 }
 class FSOpsHost {
@@ -8520,6 +8573,19 @@ class ValOpsHttp extends ValOps {
     }
     return fp.result.ok(res.value.files);
   }
+
+  /**
+   * `root` in front, and never a doubled or missing slash.
+   *
+   * `root` is "" for a project at the repository root and something like
+   * `examples/next` otherwise; a ModuleFilePath always starts with "/". Joining
+   * them by hand at each call site is how one of these ends up with "//" in the
+   * middle, which GitHub answers with a 404 that reads like a missing file.
+   */
+  gitPathOfModule(moduleFilePath) {
+    const joined = `${this.root}/${moduleFilePath}`.split("/").filter(part => part !== "").join("/");
+    return fp.result.ok(joined);
+  }
   async getFileAtCommit(commitSha, filePath, remote) {
     const params = new URLSearchParams({
       path: filePath
@@ -8979,6 +9045,129 @@ async function getModuleAtCommit(ops, commitSha, moduleFilePath) {
   });
 }
 
+/**
+ * One `.jsonValues()` entry's content, as it was at a commit.
+ *
+ * The history pane renders a commit through the real field components, and a
+ * `.jsonValues()` record's source is only `{_type:"json"}` markers - the
+ * content lives in a separate `*.val.json` per entry, fetched on demand. The
+ * live Studio fetches it from `GET /json`; the commit pane had nothing to
+ * fetch from, so every entry stayed a marker and rendered as though the field
+ * were empty. Which is worse than an error: an empty value is a claim, and it
+ * was a false one.
+ *
+ * ## Why this needs the module's own `.val.ts`
+ *
+ * There is no derivable relationship between a record key and its entry file.
+ * From the example app:
+ *
+ *   "/support/getting-started": c.json(() => import("./content/getting-started.val.json"))
+ *   "/support/faq":             c.json(() => import("./content/faq.val.json"))
+ *
+ * The key is a route and the path is whatever the author wrote. The only place
+ * the two are related is the `import()` literal inside the `.val.ts`, which is
+ * why `findJsonEntryFilePathsInSource` reads them out of the AST too. The
+ * commit archive stores the module's SOURCE (the markers) and its schema, not
+ * its text - so the text is fetched from git at that commit and parsed here.
+ *
+ * Two round trips per entry, then: the module, and the entry. The module's
+ * parse is worth caching per (commit, module) by the caller; nothing here does,
+ * because a `ValOps` is not a cache and the endpoint above it is the layer that
+ * knows how long a commit stays interesting.
+ */
+async function getJsonEntryAtCommit(ops, commitSha, moduleFilePath, key) {
+  const moduleGitPath = ops.gitPathOfModule(moduleFilePath);
+  if (fp.result.isErr(moduleGitPath)) {
+    return moduleGitPath;
+  }
+  const moduleRes = await ops.getFileAtCommit(commitSha, moduleGitPath.value, false);
+  if (fp.result.isErr(moduleRes)) {
+    return moduleRes;
+  }
+  const entryPath = findEntryImportPath(moduleFilePath, moduleGitPath.value, moduleRes.value.toString("utf-8"), key);
+  if (fp.result.isErr(entryPath)) {
+    return entryPath;
+  }
+  // The entry path resolved above is PROJECT-relative, like the module path it
+  // came from; the git path needs the root in front of it, and the ops are what
+  // know the root. Reusing gitPathOfModule rather than re-deriving the prefix:
+  // a `.val.json` is not a module, but "project-relative path -> repo path" is
+  // the same question and one implementation of it is the point.
+  const entryGitPath = ops.gitPathOfModule(entryPath.value);
+  if (fp.result.isErr(entryGitPath)) {
+    return entryGitPath;
+  }
+  const entryRes = await ops.getFileAtCommit(commitSha, entryGitPath.value, false);
+  if (fp.result.isErr(entryRes)) {
+    return entryRes;
+  }
+  try {
+    return fp.result.ok(JSON.parse(entryRes.value.toString("utf-8")));
+  } catch (err) {
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: entryGitPath.value,
+      message: `not valid JSON at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+}
+
+/**
+ * The `import()` path a key's entry is behind, from the module's text.
+ *
+ * Exported for its own test: this is the part with a real chance of being
+ * wrong, and it is pure.
+ */
+function findEntryImportPath(moduleFilePath,
+/**
+ * The same module, repository-relative, for error reporting only.
+ *
+ * A `gitPath` in a HistoryError is a REPOSITORY path - that is what every
+ * other history helper reports, and what a reader can paste into a `git show`
+ * - so reporting the project-relative ModuleFilePath here named a file that
+ * does not exist at that path for any project not rooted at the repo root.
+ */
+moduleGitPath, valTsSource, key) {
+  const sourceFile = ts__default["default"].createSourceFile(moduleFilePath, valTsSource, ts__default["default"].ScriptTarget.ES2015, true);
+  let analysis;
+  try {
+    analysis = analyzeValModule(sourceFile);
+  } catch (err) {
+    // `file-unavailable` rather than a kind of its own: the module's TEXT is
+    // the file we could not use, and adding a wire kind for "unparseable"
+    // would be a new case every reader has to handle to say the same thing.
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `could not parse the module at this commit: ${err instanceof Error ? err.message : String(err)}`
+    });
+  }
+  if (fp.result.isErr(analysis)) {
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: "could not read the module at this commit"
+    });
+  }
+  const entries = analyzeJsonValuesEntries(analysis.value.source);
+  const entry = entries.get(key);
+  if (entry === undefined) {
+    /*
+     * Reported, not treated as empty. A key with no entry at this commit means
+     * the entry was added later - so "there is nothing to show for it here" is
+     * the true answer, and rendering an empty field instead would say the
+     * author had left it blank.
+     */
+    return fp.result.err({
+      kind: "file-unavailable",
+      gitPath: moduleGitPath,
+      message: `'${key}' had no entry at this commit`
+    });
+  }
+  const moduleDir = path__namespace["default"].posix.dirname(moduleFilePath);
+  return fp.result.ok(path__namespace["default"].posix.join(moduleDir, entry.importPath));
+}
+
 const host = process.env.VAL_CONTENT_URL || core.DEFAULT_CONTENT_HOST;
 const SettingsSchema = z.z.object({
   publicProjectId: z.z.string(),
@@ -12274,12 +12463,60 @@ const ValServer = (valModules, options, callbacks) => {
         };
       }
     },
+    "/history/json": {
+      GET: async req => {
+        // Authenticated, for the reasons on /history/files below.
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
+        const res = await getJsonEntryAtCommit(serverOps, req.query.commit_sha, req.query.path, req.query.key);
+        if (fp.result.isErr(res)) {
+          return historyErrorResponse(res.error);
+        }
+        return {
+          status: 200,
+          json: {
+            path: req.query.path,
+            key: req.query.key,
+            content: res.value
+          }
+        };
+      }
+    },
     "/history/files": {
       GET: async req => {
-        // No auth, for the same reason /files has none: this is served to an
-        // <img> that the app's own backend may fetch during image
-        // optimisation, with no cookies. What it exposes is a file at a commit
-        // that is already in the repository.
+        /*
+         * Authenticated, unlike /files.
+         *
+         * This used to reason "same as /files" and that was wrong twice over.
+         * /files is open because a `patch_id` is an unguessable UUID standing
+         * in for a credential, and because it HAS to be: a draft image is
+         * fetched by the app's own backend during Next image optimisation,
+         * backend-to-backend, with no cookies to send.
+         *
+         * A commit sha is not a secret - it is in `git log`, in the GitHub UI,
+         * on every PR - so the first argument does not transfer. And nothing
+         * fetches this server-side; both callers are the Studio in a browser
+         * that has the session cookie (the history pane's <img>, and
+         * stageRestore's fetch, both same-origin so the cookie goes). So the
+         * second does not either, and there is nothing to trade away by
+         * asking.
+         */
+        const auth = getAuth(req.cookies);
+        if (auth.error) {
+          return {
+            status: 401,
+            json: {
+              message: auth.error
+            }
+          };
+        }
         const res = await serverOps.getFileAtCommit(req.query.commit_sha, req.query.path, req.query.remote === "true");
         if (fp.result.isErr(res)) {
           const response = historyErrorResponse(res.error);
@@ -12318,6 +12555,11 @@ const ValServer = (valModules, options, callbacks) => {
         //     3) the benefit an attacker would get is an image that is not yet published (i.e. most cases: not very interesting)
         // Thus: attack surface + ease of attack + benefit = low probability of attack
         // If we couldn't argue that patch ids are secret enough, then this would be a problem.
+        // Note that /history/files, which looks like the same endpoint, IS
+        // authenticated: its token is a commit sha, which is published, and
+        // nothing fetches it backend-to-backend. Neither half of the argument
+        // above transfers. See architecture/media.md, "Why /files has no auth,
+        // and /history/files does".
         let fileBuffer;
         let mimeType;
         const remote = query.remote === "true";
@@ -14300,37 +14542,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 +14593,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);
   }
-  sourceFileHandler.writeFile(absoluteJsonPath, JSON.stringify(content, null, 2) + "\n", "utf8");
-  sourceFileHandler.writeSourceFile(inserted.value);
+  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, 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) {
@@ -14613,7 +14924,7 @@ async function handleRemoteFileUpload(ctx) {
   return uploadRemoteFileCore(ctx, fileRefProp, fileSourceMetadata, resolveRemoteFileSchema);
 }
 
-// Gallery (s.images({ remote: true }) / s.files({ remote: true })) upload.
+// Gallery (s.images({ ... }).remote() / s.files({ ... }).remote()) upload.
 // Unlike a single image/file field, a gallery entry is keyed by its local file
 // path and the value is bare metadata (no FileSource), so we derive the file
 // ref from the key and synthesize the image/file schema from the record's
@@ -15655,6 +15966,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;