@valbuild/server 0.97.7 → 0.99.0

package/dist/valbuild-server.esm.js

@@ -6,16 +6,17 @@ import * as path from 'path';
 import path__default from 'path';
 import fs, { promises } from 'fs';
 import vm from 'node:vm';
-import { Module } from 'node:module';
+import { Module, createRequire } from 'node:module';
 import { resolveSchemaSourceFixForError, getErrorMessageFromUnknownJson, Patch, ParentRef, VAL_ENABLE_COOKIE_NAME, VAL_STATE_COOKIE, VAL_SESSION_COOKIE, Api } from '@valbuild/shared/internal';
 import { createUIRequestHandler } from '@valbuild/ui/server';
 import crypto$1 from 'crypto';
-import { z } from 'zod';
+import z$1, { z } from 'zod';
 import sizeOf from 'image-size';
 import { fromError } from 'zod-validation-error';
 import { transform } from 'sucrase';
 import http from 'http';
 import https from 'https';
+import fs$1 from 'fs/promises';
 
 class ValSyntaxError {
   constructor(message, node) {
@@ -925,6 +926,15 @@ const getCompilerOptions = (rootDir, parseConfigHost) => {
   return parsedConfigFile.options;
 };
 
+/**
+ * The filesystem seam `loadValModules` reads through.
+ *
+ * Defaults to `ts.sys`, i.e. the real filesystem. An editor integration (see
+ * `@valbuild/language-server`) passes a host that overlays unsaved buffers, so
+ * that evaluation sees what the user is looking at rather than what was last
+ * saved.
+ */
+
 /**
  * Loads the project's root `val.modules.ts` (or `.js`) using Node's `vm`
  * module and returns its default export (a `ValModules` registry).
@@ -946,24 +956,24 @@ const getCompilerOptions = (rootDir, parseConfigHost) => {
  * same trust level as running the project's build. It must never be used to
  * evaluate untrusted or third-party modules.
  */
-function loadValModules(projectRoot) {
-  const valModulesPath = findValModulesPath(projectRoot);
+function loadValModules(projectRoot, host = ts.sys) {
+  const valModulesPath = findValModulesPath(projectRoot, host);
   if (!valModulesPath) {
     throw Error(`Could not find 'val.modules.ts' nor 'val.modules.js' in project root: '${projectRoot}'`);
   }
-  const compilerOptions = getCompilerOptions(projectRoot, ts.sys);
+  const compilerOptions = getCompilerOptions(projectRoot, host);
   const cache = {};
-  const loaded = loadModule(valModulesPath, cache, compilerOptions);
+  const loaded = loadModule(valModulesPath, cache, compilerOptions, host);
   const valModules = loaded.exports.default;
   if (!valModules) {
     throw Error(`Val modules file at path: '${valModulesPath}' must have a default export. Got: ${valModules}`);
   }
   return valModules;
 }
-function findValModulesPath(projectRoot) {
+function findValModulesPath(projectRoot, host) {
   for (const fileName of ["val.modules.ts", "val.modules.js"]) {
     const candidate = path__default.join(projectRoot, fileName);
-    if (fs.existsSync(candidate)) {
+    if (host.fileExists(candidate)) {
       return candidate;
     }
   }
@@ -1004,12 +1014,15 @@ function makeStub(spec) {
   const stub = new Proxy({}, handler);
   return stub;
 }
-function loadModule(absPath, cache, compilerOptions) {
+function loadModule(absPath, cache, compilerOptions, host) {
   const cached = cache[absPath];
   if (cached) {
     return cached;
   }
-  const code = fs.readFileSync(absPath, "utf-8");
+  const code = host.readFile(absPath);
+  if (code === undefined) {
+    throw Error(`Could not read Val module file: '${absPath}'`);
+  }
   const transpiled = ts.transpileModule(code, {
     compilerOptions: {
       target: ts.ScriptTarget.ES2020,
@@ -1032,17 +1045,17 @@ function loadModule(absPath, cache, compilerOptions) {
       return makeStub(spec);
     }
     if (spec.startsWith(".") || path__default.isAbsolute(spec)) {
-      const resolved = resolveRelative(dirName, spec);
+      const resolved = resolveRelative(dirName, spec, host);
       if (!resolved) {
         throw Error(`Could not resolve module '${spec}' from '${absPath}'`);
       }
-      return loadModule(resolved, cache, compilerOptions).exports;
+      return loadModule(resolved, cache, compilerOptions, host).exports;
     }
     // Non-relative specifier: it might be a tsconfig path alias (e.g. "_/val.config")
     // pointing at a local source file, or an actual node_modules package.
-    const tsResolved = (_ts$resolveModuleName = ts.resolveModuleName(spec, absPath, compilerOptions, ts.sys).resolvedModule) === null || _ts$resolveModuleName === void 0 ? void 0 : _ts$resolveModuleName.resolvedFileName;
+    const tsResolved = (_ts$resolveModuleName = ts.resolveModuleName(spec, absPath, compilerOptions, host).resolvedModule) === null || _ts$resolveModuleName === void 0 ? void 0 : _ts$resolveModuleName.resolvedFileName;
     if (tsResolved && !tsResolved.includes("/node_modules/") && !tsResolved.endsWith(".d.ts")) {
-      return loadModule(tsResolved, cache, compilerOptions).exports;
+      return loadModule(tsResolved, cache, compilerOptions, host).exports;
     }
     // Real node_modules package – use the real require so user modules share
     // the same @valbuild/core instance as extractValModules.
@@ -1068,24 +1081,25 @@ function loadModule(absPath, cache, compilerOptions) {
   script.runInContext(context);
   return moduleObj;
 }
-function resolveRelative(dirName, spec) {
+function resolveRelative(dirName, spec, host) {
+  var _host$directoryExists;
   const base = path__default.resolve(dirName, spec);
   // Exact file (with extension)
-  if (fs.existsSync(base) && fs.statSync(base).isFile()) {
+  if (host.fileExists(base)) {
     return base;
   }
   // Probe extensions (handles `./x.val` -> `./x.val.ts`)
   for (const ext of RESOLVE_EXTENSIONS) {
     const candidate = base + ext;
-    if (fs.existsSync(candidate)) {
+    if (host.fileExists(candidate)) {
       return candidate;
     }
   }
   // Directory index
-  if (fs.existsSync(base) && fs.statSync(base).isDirectory()) {
+  if (((_host$directoryExists = host.directoryExists) === null || _host$directoryExists === void 0 ? void 0 : _host$directoryExists.call(host, base)) ?? fs.existsSync(base)) {
     for (const ext of RESOLVE_EXTENSIONS) {
       const candidate = path__default.join(base, "index" + ext);
-      if (fs.existsSync(candidate)) {
+      if (host.fileExists(candidate)) {
         return candidate;
       }
     }
@@ -1112,7 +1126,9 @@ async function createService(projectRoot, host = {
 }) {
   const compilerOptions = getCompilerOptions(projectRoot, host);
   const sourceFileHandler = new ValSourceFileHandler(projectRoot, compilerOptions, host);
-  const valModules = loadValModules(projectRoot);
+  // Read val.modules (and everything it imports) through the same host, so an
+  // embedder that overlays unsaved editor buffers evaluates what the user sees.
+  const valModules = loadValModules(projectRoot, host);
   const extracted = await extractValModules(valModules);
   return new Service(projectRoot, sourceFileHandler, extracted);
 }
@@ -7728,6 +7744,33 @@ 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
+// remaining parent path — whose ancestors are plain object keys / array
+// indices — instead.
+function parentPatchPathOfMediaEntry(sourcePath, entryKey) {
+  const jsonKey = JSON.stringify(entryKey);
+  let parent = sourcePath;
+  if (parent.endsWith(jsonKey)) {
+    parent = parent.slice(0, parent.length - jsonKey.length);
+  }
+  if (parent.endsWith(".")) {
+    parent = parent.slice(0, -1);
+  } else if (parent.endsWith(Internal.ModuleFilePathSep)) {
+    parent = parent.slice(0, parent.length - Internal.ModuleFilePathSep.length);
+  }
+  return sourceToPatchPath(parent);
+}
+
 // TODO: find a better name? transformFixesToPatch?
 async function createFixPatch(config, apply, sourcePath, validationError, remoteFiles, moduleSource, moduleSchema) {
   const remainingErrors = [];
@@ -7905,6 +7948,61 @@ async function createFixPatch(config, apply, sourcePath, validationError, remote
           path: sourceToPatchPath(sourcePath)
         });
       }
+    } else if (fix === "images:upload-remote" || fix === "files:upload-remote") {
+      // Gallery entry: the record is keyed by the file path, so uploading to
+      // remote means renaming the key from the local path to the remote URL
+      // (remove the old key, add the new one with the same metadata).
+      const remoteFile = remoteFiles[sourcePath];
+      if (!remoteFile) {
+        remainingErrors.push({
+          ...validationError,
+          message: "Cannot fix local to remote gallery entry: remote file was not uploaded",
+          fixes: undefined
+        });
+        continue;
+      }
+      const metadata = remoteFile.metadata;
+      if (!metadata) {
+        remainingErrors.push({
+          ...validationError,
+          message: "Failed to get metadata for remote gallery file",
+          fixes: undefined
+        });
+        continue;
+      }
+      // The entry is keyed by its (local) file path, which can contain dots
+      // (e.g. image.png). sourceToPatchPath can't round-trip such keys, so
+      // build the patch path from the parent record path plus the key (which
+      // validateMediaKey carries as the error value), like the UI does.
+      const entryKey = validationError.value;
+      if (typeof entryKey !== "string") {
+        remainingErrors.push({
+          ...validationError,
+          message: "Cannot rewrite remote gallery entry: missing entry key",
+          fixes: undefined
+        });
+        continue;
+      }
+      const parentPath = parentPatchPathOfMediaEntry(sourcePath, entryKey);
+      const removePath = parentPath.concat(entryKey);
+      const addPath = parentPath.concat(remoteFile.ref);
+      if (!isNotRoot(removePath) || !isNotRoot(addPath)) {
+        remainingErrors.push({
+          ...validationError,
+          message: "Cannot rewrite remote gallery entry at root path",
+          fixes: undefined
+        });
+        continue;
+      }
+      patch.push({
+        op: "remove",
+        path: removePath
+      });
+      patch.push({
+        op: "add",
+        path: addPath,
+        value: metadata
+      });
     } else if (fix === "image:download-remote" || fix === "file:download-remote") {
       const v = getRemoteValueFromValidationError(validationError);
       if (!v.success) {
@@ -7981,7 +8079,7 @@ 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, entryKey);
+        const filename = path__default.join(config.projectRoot, galleryKeyToLocalPath(entryKey));
         let buffer;
         try {
           buffer = fs.readFileSync(filename);
@@ -8209,6 +8307,294 @@ async function getFileMetadata(projectRoot, validationError) {
   return extractFileMetadata(fileRef);
 }
 
+function validateMetadata(actualMetadata, expectedMetadata) {
+  const missingMetadata = [];
+  const erroneousMetadata = {};
+  if (typeof actualMetadata !== "object" || actualMetadata === null) {
+    return {
+      globalErrors: ["Metadata is wrong type: must be an object."]
+    };
+  }
+  if (Array.isArray(actualMetadata)) {
+    return {
+      globalErrors: ["Metadata is wrong type: cannot be an array."]
+    };
+  }
+  const recordMetadata = actualMetadata;
+  const globalErrors = [];
+  for (const anyKey in expectedMetadata) {
+    if (typeof anyKey !== "string") {
+      globalErrors.push(`Expected metadata has key '${anyKey}' that is not typeof 'string', but: '${typeof anyKey}'. This is most likely a Val bug.`);
+    } else {
+      if (anyKey in actualMetadata) {
+        const key = anyKey;
+        if (expectedMetadata[key] !== recordMetadata[key]) {
+          erroneousMetadata[key] = `Expected metadata '${key}' to be ${JSON.stringify(expectedMetadata[key])}, but got ${JSON.stringify(recordMetadata[key])}.`;
+        }
+      } else {
+        missingMetadata.push(anyKey);
+      }
+    }
+  }
+  if (globalErrors.length === 0 && missingMetadata.length === 0 && Object.keys(erroneousMetadata).length === 0) {
+    return false;
+  }
+  return {
+    missingMetadata,
+    erroneousMetadata
+  };
+}
+
+/**
+ * NOTE: this is intentionally NOT `SharedValConfig` from `@valbuild/shared`.
+ * That schema requires `files.directory` to be exactly `/public/val`, whereas
+ * this one accepts any path beneath `/public`. Unifying them would change which
+ * configs are accepted, so they are kept separate on purpose.
+ */
+const ValConfigSchema = z$1.object({
+  project: z$1.string().optional(),
+  root: z$1.string().optional(),
+  files: z$1.object({
+    directory: z$1.string().refine(val => (val === "/public" || val.startsWith("/public/") && !val.endsWith("/")) &&
+    // Reject path traversal so the directory cannot escape /public
+    !val.split("/").some(segment => segment === "." || segment === ".."), {
+      message: "files.directory must start with '/public', must not end with '/' and must not contain '.' or '..' segments"
+    })
+  }).optional(),
+  gitCommit: z$1.string().optional(),
+  gitBranch: z$1.string().optional(),
+  defaultTheme: z$1.union([z$1.literal("light"), z$1.literal("dark")]).optional(),
+  ai: z$1.object({
+    commitMessages: z$1.object({
+      disabled: z$1.boolean().optional()
+    }).optional()
+  }).optional()
+});
+
+/**
+ * `ENOENT` (nothing at this path) and `ENOTDIR` (a path segment is a file) both
+ * mean the config file simply is not there.
+ */
+function isFileNotFound(err) {
+  const code = err && typeof err === "object" && "code" in err ? err.code : undefined;
+  return code === "ENOENT" || code === "ENOTDIR";
+}
+
+/**
+ * Read and evaluate a `val.config.{ts,js}` file from disk.
+ *
+ * Returns `null` if the file does not exist, and throws if it exists but does
+ * not export a valid `config` object.
+ *
+ * Used by the Val CLI and by `@valbuild/language-server`, so that an editor
+ * resolves project config exactly the way the CLI does.
+ */
+async function evalValConfigFile(projectRoot, configFileName) {
+  const valConfigPath = path__default.join(projectRoot, configFileName);
+  let code;
+  try {
+    code = await fs$1.readFile(valConfigPath, "utf-8");
+  } catch (err) {
+    // A missing file means "this project does not use this config file name",
+    // which callers handle by trying the next candidate. Anything else (no read
+    // permission, an IO error, a directory where a file was expected) is a real
+    // problem and must not be reported as "no config".
+    if (isFileNotFound(err)) {
+      return null;
+    }
+    throw Error(`Could not read Val config file at path: '${valConfigPath}': ${err instanceof Error ? err.message : String(err)}`);
+  }
+  if (!code.trim()) {
+    return null;
+  }
+  const transpiled = ts.transpileModule(code, {
+    compilerOptions: {
+      target: ts.ScriptTarget.ES2020,
+      module: ts.ModuleKind.CommonJS,
+      esModuleInterop: true
+    },
+    fileName: valConfigPath
+  });
+  const projectRootRequire = createRequire(valConfigPath);
+  const exportsObj = {};
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  const sandbox = {
+    exports: exportsObj,
+    module: {
+      exports: exportsObj
+    },
+    require: projectRootRequire,
+    // NOTE: this is a security risk, but this code is running in the users own environment at the CLI level
+    __filename: valConfigPath,
+    __dirname: projectRoot,
+    console,
+    process
+  };
+  sandbox.global = sandbox;
+  const context = vm.createContext(sandbox);
+  const script = new vm.Script(transpiled.outputText, {
+    filename: valConfigPath
+  });
+  script.runInContext(context);
+  const valConfig = sandbox.module.exports.config;
+  if (!valConfig) {
+    throw Error(`Val config file at path: '${valConfigPath}' must export a config object. Got: ${valConfig}`);
+  }
+  const result = ValConfigSchema.safeParse(valConfig);
+  if (!result.success) {
+    throw Error(`Val config file at path: '${valConfigPath}' has invalid schema: ${result.error.message}`);
+  }
+  return result.data;
+}
+
+/**
+ * Resolve the project's Val config, trying the TypeScript file first and
+ * falling back to JavaScript. Mirrors what the CLI has always done at each of
+ * its call sites.
+ */
+async function findAndEvalValConfigFile(projectRoot) {
+  return (await evalValConfigFile(projectRoot, "val.config.ts")) || (await evalValConfigFile(projectRoot, "val.config.js"));
+}
+
+/**
+ * The Val login device flow, as reusable primitives.
+ *
+ * The CLI wraps these with terminal output, and `@valbuild/language-server`
+ * wraps them with LSP `window/showDocument` and progress reporting. Neither the
+ * polling nor the token handling is duplicated between them.
+ *
+ * Deliberately no `console` output and no `process.exit`: every failure is a
+ * thrown {@link ValLoginError} so an embedder can decide how to surface it.
+ */
+
+const DEFAULT_LOGIN_HOST = "https://admin.val.build";
+function defaultHost() {
+  return process.env.VAL_BUILD_URL || DEFAULT_LOGIN_HOST;
+}
+class ValLoginError extends Error {
+  constructor(code, message, details) {
+    super(message);
+    this.code = code;
+    this.details = details;
+    this.name = "ValLoginError";
+  }
+}
+
+/** A login attempt that is waiting for the user to confirm in a browser. */
+
+/**
+ * Begin a login attempt. The caller is responsible for getting
+ * {@link ValLoginSession.url} in front of the user.
+ */
+async function startValLogin(options = {}) {
+  var _response$headers$get;
+  const host = options.host ?? defaultHost();
+  const response = await fetch(`${host}/api/login`, {
+    method: "POST",
+    headers: {
+      "Content-Type": "application/json"
+    }
+  });
+  if (response.status >= 500) {
+    const text = await response.text().catch(() => "");
+    throw new ValLoginError("server-error", "An error occurred on the server.", text ? `Server response: ${text} (status: ${response.status})` : `Status: ${response.status}`);
+  }
+  if (!((_response$headers$get = response.headers.get("content-type")) !== null && _response$headers$get !== void 0 && _response$headers$get.includes("application/json"))) {
+    const text = await response.text().catch(() => "");
+    throw new ValLoginError("unexpected-content-type", "Unexpected failure while trying to login (content type was not JSON).", text ? `Server response: ${text} (status: ${response.status})` : `Status: ${response.status}`);
+  }
+  const json = await response.json();
+  const nonce = json === null || json === void 0 ? void 0 : json.nonce;
+  const url = json === null || json === void 0 ? void 0 : json.url;
+  if (typeof nonce !== "string" || typeof url !== "string") {
+    throw new ValLoginError("unexpected-response", "Unexpected response from the server.", JSON.stringify(json));
+  }
+  return {
+    nonce,
+    url
+  };
+}
+const DEFAULT_LOGIN_MAX_DURATION = 5 * 60 * 1000; // 5 minutes
+const DEFAULT_LOGIN_POLL_INTERVAL = 1000;
+
+/**
+ * Poll until the user confirms the login in their browser.
+ *
+ * Accepts an `AbortSignal` so an editor can cancel the flow when the user
+ * dismisses the prompt, instead of leaving a poll loop running for 5 minutes.
+ */
+async function awaitValLoginConfirmation(nonce, options = {}) {
+  const host = options.host ?? defaultHost();
+  const maxDuration = options.maxDurationMs ?? DEFAULT_LOGIN_MAX_DURATION;
+  const pollInterval = options.pollIntervalMs ?? DEFAULT_LOGIN_POLL_INTERVAL;
+  const now = options.now ?? (() => Date.now());
+  const start = now();
+  while (now() - start < maxDuration) {
+    var _options$signal, _options$signal2;
+    if ((_options$signal = options.signal) !== null && _options$signal !== void 0 && _options$signal.aborted) {
+      throw new ValLoginError("aborted", "Login was cancelled.");
+    }
+    await new Promise(resolve => setTimeout(resolve, pollInterval));
+    if ((_options$signal2 = options.signal) !== null && _options$signal2 !== void 0 && _options$signal2.aborted) {
+      throw new ValLoginError("aborted", "Login was cancelled.");
+    }
+    const response = await fetch(`${host}/api/login?token=${nonce}&consume=true`, {
+      method: "POST"
+    });
+    if (response.status >= 500) {
+      throw new ValLoginError("server-error", "An error occurred on the server.", `Status: ${response.status}`);
+    }
+    if (response.status === 200) {
+      var _json$profile;
+      const json = await response.json().catch(() => null);
+      if (!json) {
+        // A 200 with an empty body is not a confirmation; keep polling rather
+        // than failing the login, which is what the CLI has always done.
+        continue;
+      }
+      if (typeof ((_json$profile = json.profile) === null || _json$profile === void 0 ? void 0 : _json$profile.email) === "string" && typeof json.pat === "string") {
+        return json;
+      }
+      throw new ValLoginError("unexpected-response", "Unexpected response from the server.", JSON.stringify(json));
+    }
+  }
+  throw new ValLoginError("timeout", "Login confirmation timed out.");
+}
+
+/**
+ * Write a completed login to the project's personal access token file.
+ *
+ * @returns the path the token was written to.
+ */
+function persistPersonalAccessToken(projectRoot, result) {
+  const filePath = getPersonalAccessTokenPath(projectRoot);
+  // NOTE: no restrictive mode on the directory. This is the project's shared
+  // `.val`, which also holds the pending patches the dev server reads and
+  // writes; making it owner-only would lock out anyone who did not run the
+  // login. Only the token file itself is tightened.
+  fs.mkdirSync(path__default.dirname(filePath), {
+    recursive: true
+  });
+  // The token is a credential: keep it owner-only rather than at the mercy of
+  // the process umask. `mode` only applies when the file is created, so an
+  // already existing file is chmod-ed explicitly.
+  fs.writeFileSync(filePath, JSON.stringify(result, null, 2), {
+    mode: 0o600
+  });
+  try {
+    fs.chmodSync(filePath, 0o600);
+  } catch {
+    // Not all platforms / filesystems support POSIX modes (Windows, some
+    // network mounts). Failing to tighten them must not fail the login.
+  }
+  return filePath;
+}
+
+/**
+ * NOTE: `@valbuild/language-server` has a near-identical `modulePathMap.ts`.
+ * Fix traversal bugs in both, or fold them together.
+ */
+
 function getModulePathRange(modulePath, modulePathMap,
 // Which part of an object/record member to point at. For an object property
 // the resolved node's own range is the *key* (property name); the *value*
@@ -8218,31 +8604,39 @@ function getModulePathRange(modulePath, modulePathMap,
 // existing callers.
 target = "key") {
   var _range$children;
-  // Handle empty or invalid module paths gracefully
-  if (!modulePath || typeof modulePath !== "string") {
-    return undefined;
-  }
-  let segments;
-  try {
-    // Quote-aware splitter that correctly handles keys containing dots
-    // (e.g. file refs like `"/public/val/images/logo.png"`), unlike a naive
-    // split on ".". Throws on malformed input (e.g. unbalanced quotes).
-    segments = Internal.splitModulePath(modulePath);
-  } catch {
-    // Return undefined if the module path is malformed. This can happen when
-    // there are upstream errors in schema serialization.
+  // Handle invalid module paths gracefully
+  if (typeof modulePath !== "string") {
     return undefined;
   }
-  if (segments.length === 0) {
-    return undefined;
-  }
-  let range = modulePathMap[segments[0]];
-  for (const pathSegment of segments.slice(1)) {
-    var _range;
-    if (!range) {
-      break;
+  let range;
+  if (modulePath === "") {
+    // The empty module path is the module root, stored under the "" key: the
+    // source argument of `c.define`. This is what module-level diagnostics
+    // (which have no module path) resolve to.
+    range = modulePathMap[""];
+  } else {
+    let segments;
+    try {
+      // Quote-aware splitter that correctly handles keys containing dots
+      // (e.g. file refs like `"/public/val/images/logo.png"`), unlike a naive
+      // split on ".". Throws on malformed input (e.g. unbalanced quotes).
+      segments = Internal.splitModulePath(modulePath);
+    } catch {
+      // Return undefined if the module path is malformed. This can happen when
+      // there are upstream errors in schema serialization.
+      return undefined;
+    }
+    if (segments.length === 0) {
+      return undefined;
+    }
+    range = modulePathMap[segments[0]];
+    for (const pathSegment of segments.slice(1)) {
+      var _range;
+      if (!range) {
+        break;
+      }
+      range = (_range = range) === null || _range === void 0 || (_range = _range.children) === null || _range === void 0 ? void 0 : _range[pathSegment];
     }
-    range = (_range = range) === null || _range === void 0 || (_range = _range.children) === null || _range === void 0 ? void 0 : _range[pathSegment];
   }
   if (!range) {
     return undefined;
@@ -8274,7 +8668,20 @@ function createModulePathMap(sourceFile) {
     if (ts.isExportAssignment(child)) {
       const contentNode = child.expression && ts.isCallExpression(child.expression) && child.expression.arguments[2];
       if (contentNode) {
-        return traverse(contentNode, sourceFile);
+        const map = traverse(contentNode, sourceFile) ?? {};
+        // Always expose the module root under the "" key so diagnostics without
+        // a module path still resolve to a location. `traverse` already emits ""
+        // for primitive roots (with a tighter range), so keep that if present.
+        // Object/record keys are never "" (see traverseObjectLiteral), so this
+        // cannot collide with a real key.
+        return {
+          ...map,
+          "": map[""] ?? {
+            children: {},
+            start: sourceFile.getLineAndCharacterOfPosition(contentNode.getStart(sourceFile)),
+            end: sourceFile.getLineAndCharacterOfPosition(contentNode.getEnd())
+          }
+        };
       }
     }
   }
@@ -8467,4 +8874,4 @@ function readCapturedReport(snapshotDir) {
   return JSON.parse(fs.readFileSync(reportPath, "utf-8"));
 }
 
-export { Service, ValFSHost, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, compareWithCapturedReport, createFixPatch, createModulePathMap, createService, createValApiRouter, createValServer, decodeJwt, encodeJwt, formatPatchSourceError, formatSyntaxErrorTree, getCompilerOptions, getExpire, getModulePathRange, getPersonalAccessTokenPath, getSettings, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, readCapturedReport, replaySnapshot, safeReadGit, uploadRemoteFile };
+export { DEFAULT_LOGIN_HOST, DEFAULT_LOGIN_MAX_DURATION, DEFAULT_LOGIN_POLL_INTERVAL, Service, ValFSHost, ValLoginError, ValModuleLoader, ValOpsFS, ValOpsHttp, ValSourceFileHandler, analyzeValModule, awaitValLoginConfirmation, checkRemoteRef, compareWithCapturedReport, createFixPatch, createModulePathMap, createService, createValApiRouter, createValServer, decodeJwt, downloadFileFromRemote, encodeJwt, evalValConfigFile, extractFileMetadata, extractImageMetadata, findAndEvalValConfigFile, formatPatchSourceError, formatSyntaxErrorTree, getCachedRemoteFileDir, getCachedRemoteFilePath, getCompilerOptions, getExpire, getFileExt, getModulePathRange, getPersonalAccessTokenPath, getSettings, getValidationErrorFileRef, hasRemoteFileSchema, loadValModules, parsePersonalAccessTokenFile, patchSourceFile, persistPersonalAccessToken, readCapturedReport, replaySnapshot, safeReadGit, startValLogin, uploadRemoteFile, validateMetadata };

package/package.json

@@ -16,7 +16,7 @@
     "./package.json": "./package.json"
   },
   "types": "dist/valbuild-server.cjs.d.ts",
-  "version": "0.97.7",
+  "version": "0.99.0",
   "devDependencies": {
     "@prettier/sync": "^0.6.1",
     "@types/jest": "^30.0.0"
@@ -29,9 +29,9 @@
     "typescript": "^5.9.3",
     "zod": "^4.3.5",
     "zod-validation-error": "^5.0.0",
-    "@valbuild/core": "0.97.7",
-    "@valbuild/shared": "0.97.7",
-    "@valbuild/ui": "0.97.7"
+    "@valbuild/core": "0.99.0",
+    "@valbuild/shared": "0.99.0",
+    "@valbuild/ui": "0.99.0"
   },
   "engines": {
     "node": ">=18.17.0"