@valbuild/cli 0.97.3 → 0.97.4

package/cli/dist/valbuild-cli-cli.esm.js

@@ -5,24 +5,39 @@ import pc from 'picocolors';
 import fs from 'fs/promises';
 import { glob } from 'fast-glob';
 import { Internal, FILE_REF_PROP, DEFAULT_VAL_REMOTE_HOST, DEFAULT_CONTENT_HOST, VAL_EXTENSION } from '@valbuild/core';
-import { createService, createFixPatch, getPersonalAccessTokenPath, parsePersonalAccessTokenFile, getSettings, uploadRemoteFile } from '@valbuild/server';
+import { createService, createFixPatch, getPersonalAccessTokenPath, parsePersonalAccessTokenFile, getModulePathRange, createModulePathMap, getSettings, uploadRemoteFile, loadValModules, safeReadGit, ValOpsHttp, ValOpsFS, formatPatchSourceError } from '@valbuild/server';
 import vm from 'node:vm';
 import ts from 'typescript';
 import z from 'zod';
 import { createRequire } from 'node:module';
 import { resolveSchemaSourceFixes } from '@valbuild/shared/internal';
-import nodeFs from 'fs';
+import fs$1 from 'fs';
+import JSZip from 'jszip';
+import readline from 'readline';
 
 function error(message) {
   console.error(chalk.red("❌Error: ") + message);
 }
+function info(message, opts = {}) {
+  if (opts.isCodeSnippet) {
+    console.log(chalk.cyanBright("$ > ") + chalk.cyan(message));
+    return;
+  }
+  if (opts.isGood) {
+    console.log(chalk.green("✅: ") + message);
+    return;
+  }
+  console.log(chalk.blue("️ℹ️ : ") + message);
+}
 
 const ValConfigSchema = z.object({
   project: z.string().optional(),
   root: z.string().optional(),
   files: z.object({
-    directory: z.string().refine(val => val.startsWith("/public/val"), {
-      message: "files.directory must start with '/public/val'"
+    directory: z.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.string().optional(),
@@ -263,10 +278,10 @@ async function handleRemoteFileUpload(ctx) {
     };
   }
   const relativeFilePath = path.relative(ctx.projectRoot, filePath).split(path.sep).join("/");
-  if (!relativeFilePath.startsWith("public/val/")) {
+  if (!relativeFilePath.startsWith("public/")) {
     return {
       success: false,
-      errorMessage: `File path must be within the public/val/ directory (e.g. public/val/path/to/file.txt). Got: ${relativeFilePath}`
+      errorMessage: `File path must be within the public/ directory (e.g. public/path/to/file.txt). Got: ${relativeFilePath}`
     };
   }
   const fileHash = Internal.remote.getFileHash(fileBuffer);
@@ -350,8 +365,6 @@ async function handleUniqueFolderCheck(ctx) {
     const otherModuleFilePath = `/${file}`;
     if (otherModuleFilePath === ctx.moduleFilePath) continue;
     const otherModule = await ctx.service.get(otherModuleFilePath, "", {
-      source: false,
-      schema: true,
       validate: false
     });
     const schema = otherModule.schema;
@@ -464,15 +477,15 @@ function createDefaultValFSHost() {
   return {
     ...ts.sys,
     writeFile: (fileName, data, encoding) => {
-      nodeFs.mkdirSync(path.dirname(fileName), {
+      fs$1.mkdirSync(path.dirname(fileName), {
         recursive: true
       });
-      nodeFs.writeFileSync(fileName, typeof data === "string" ? data : new Uint8Array(data), encoding);
+      fs$1.writeFileSync(fileName, typeof data === "string" ? data : new Uint8Array(data), encoding);
     },
-    rmFile: nodeFs.rmSync,
+    rmFile: fs$1.rmSync,
     readBuffer: fileName => {
       try {
-        return nodeFs.readFileSync(fileName);
+        return fs$1.readFileSync(fileName);
       } catch {
         return undefined;
       }
@@ -488,21 +501,23 @@ async function* runValidation({
   fs
 }) {
   const projectRoot = path.resolve(root);
-  const service = await createService(projectRoot, {}, fs);
+  const service = await createService(projectRoot, fs);
+
+  // Modules registered in the project's val.modules. Files found on disk that
+  // are not registered here are not validated (a warning is emitted instead).
+  const registered = new Set(service.getModuleFilePaths());
   let errors = 0;
 
   // Build a single schema/source snapshot up front so the shared resolver
   // can resolve keyof:check-keys / router:check-route references that span
-  // multiple val files.
+  // multiple val files. Use the full registry so cross-module references
+  // resolve even against modules not in the validated subset.
   const snapshot = {
     schemas: {},
     sources: {}
   };
-  for (const file of valFiles) {
-    const moduleFilePath = `/${file}`;
+  for (const moduleFilePath of registered) {
     const valModule = await service.get(moduleFilePath, "", {
-      source: true,
-      schema: true,
       validate: false
     });
     if (valModule.schema) {
@@ -514,10 +529,15 @@ async function* runValidation({
   }
   async function* validateFile(file) {
     const moduleFilePath = `/${file}`; // TODO: check if this always works? (Windows?)
+    if (!registered.has(moduleFilePath)) {
+      yield {
+        type: "unregistered-module",
+        file
+      };
+      return;
+    }
     const start = Date.now();
     const valModule = await service.get(moduleFilePath, "", {
-      source: true,
-      schema: true,
       validate: true
     });
     const remoteFiles = {};
@@ -548,7 +568,10 @@ async function* runValidation({
                 yield {
                   type: "validation-error",
                   sourcePath,
-                  message: v.message
+                  message: v.message,
+                  ...(v.keyError ? {
+                    keyError: true
+                  } : {})
                 };
                 continue;
               }
@@ -560,7 +583,10 @@ async function* runValidation({
                 yield {
                   type: "unknown-fix",
                   sourcePath,
-                  fixes: v.fixes
+                  fixes: v.fixes,
+                  ...(v.keyError ? {
+                    keyError: true
+                  } : {})
                 };
                 fileErrors += 1;
                 continue;
@@ -604,7 +630,10 @@ async function* runValidation({
                 yield {
                   type: "validation-error",
                   sourcePath,
-                  message: result.errorMessage ?? "Unknown error"
+                  message: result.errorMessage ?? "Unknown error",
+                  ...(v.keyError ? {
+                    keyError: true
+                  } : {})
                 };
                 fileErrors += 1;
                 continue;
@@ -630,16 +659,24 @@ async function* runValidation({
                     type: "validation-fixable-error",
                     sourcePath,
                     message: v.message,
-                    fixable: true
+                    fixable: true,
+                    ...(v.keyError ? {
+                      keyError: true
+                    } : {})
                   };
                 }
                 for (const e of (fixPatch === null || fixPatch === void 0 ? void 0 : fixPatch.remainingErrors) ?? []) {
                   fileErrors += 1;
                   yield {
                     type: "validation-fixable-error",
-                    sourcePath,
+                    // Gallery checks expand into per-entry errors that point at
+                    // the individual entry; fall back to the record sourcePath.
+                    sourcePath: e.sourcePath ?? sourcePath,
                     message: e.message,
-                    fixable: !!(e.fixes && e.fixes.length)
+                    fixable: !!(e.fixes && e.fixes.length),
+                    ...(e.keyError ? {
+                      keyError: true
+                    } : {})
                   };
                 }
               }
@@ -695,108 +732,441 @@ async function* runValidation({
   }
 }
 
+/**
+ * Resolves a validation `sourcePath` to its individual location parts: the
+ * relative file path and the 1-indexed line/column of the offending literal.
+ * Returns `undefined` when the location cannot be resolved (the caller should
+ * then fall back to the raw `sourcePath`).
+ */
+function sourcePathToLocationParts(sourcePath, projectRoot, cache, target = "value") {
+  const resolved = resolveRange(sourcePath, projectRoot, cache, target);
+  if (!resolved) {
+    return undefined;
+  }
+  // TS line/character are 0-indexed; editors/terminals expect 1-indexed.
+  const {
+    relativeFile,
+    range
+  } = resolved;
+  return {
+    relativeFile,
+    line: range.start.line + 1,
+    character: range.start.character + 1
+  };
+}
+
+/**
+ * Renders a Rust-style code frame for the offending `sourcePath`: the line
+ * above, the offending line, and the line below, with red carets underlining
+ * the offending span. Returns `undefined` when the location cannot be resolved
+ * (the caller should then skip the frame).
+ */
+function sourcePathToCodeFrame(sourcePath, projectRoot, cache, target = "value") {
+  const resolved = resolveRange(sourcePath, projectRoot, cache, target);
+  if (!resolved) {
+    return undefined;
+  }
+  const {
+    lines,
+    range
+  } = resolved;
+  const startLine = range.start.line;
+  const firstLine = Math.max(0, startLine - 1);
+  const lastLine = Math.min(lines.length - 1, startLine + 1);
+  const gutterWidth = String(lastLine + 1).length;
+  const out = [];
+  for (let i = firstLine; i <= lastLine; i++) {
+    const lineText = lines[i] ?? "";
+    const gutter = pc.dim(`${String(i + 1).padStart(gutterWidth, " ")} | `);
+    out.push(`${gutter}${lineText}`);
+    if (i === startLine) {
+      const caretStart = range.start.character;
+      const sameLine = range.end.line === range.start.line;
+      const caretEnd = sameLine ? range.end.character : lineText.length;
+      const caretCount = Math.max(1, caretEnd - caretStart);
+      const emptyGutter = pc.dim(`${" ".repeat(gutterWidth)} | `);
+      out.push(`${emptyGutter}${" ".repeat(caretStart)}${pc.red("^".repeat(caretCount))}`);
+    }
+  }
+  return out.join("\n");
+}
+function resolveRange(sourcePath, projectRoot, cache, target) {
+  const [moduleFilePath, modulePath] = Internal.splitModuleFilePathAndModulePath(sourcePath);
+  const cached = getCachedFile(moduleFilePath, projectRoot, cache);
+  if (!cached || !cached.map) {
+    return undefined;
+  }
+  const range = getModulePathRange(modulePath, cached.map, target);
+  if (!range) {
+    return undefined;
+  }
+  return {
+    relativeFile: moduleFilePath.replace(/^\//, ""),
+    lines: cached.lines,
+    // Defensive: a bad range must degrade to an odd-looking frame, never a
+    // crash - the caret math below does `" ".repeat(start.character)`, which
+    // throws a RangeError on a negative count.
+    range: {
+      start: clampPosition(range.start),
+      end: clampPosition(range.end)
+    }
+  };
+}
+function clampPosition(position) {
+  return {
+    line: Math.max(0, position.line),
+    character: Math.max(0, position.character)
+  };
+}
+function getCachedFile(moduleFilePath, projectRoot, cache) {
+  const existing = cache.get(moduleFilePath);
+  if (existing !== undefined) {
+    return existing;
+  }
+  const filePath = path.join(projectRoot, moduleFilePath);
+  let fileContent;
+  try {
+    fileContent = fs$1.readFileSync(filePath, "utf-8");
+  } catch {
+    cache.set(moduleFilePath, null);
+    return null;
+  }
+  const sourceFile = ts.createSourceFile(filePath, fileContent, ts.ScriptTarget.ES2015);
+  const entry = {
+    lines: fileContent.split(/\r?\n/),
+    map: createModulePathMap(sourceFile)
+  };
+  cache.set(moduleFilePath, entry);
+  return entry;
+}
+
 async function validate({
   root,
-  fix
+  fix,
+  watch
 }) {
   const projectRoot = root ? path.resolve(root) : process.cwd();
-  const valConfigFile = (await evalValConfigFile(projectRoot, "val.config.ts")) || (await evalValConfigFile(projectRoot, "val.config.js"));
-  const resolvedValConfigFile = valConfigFile ? {
-    ...valConfigFile,
-    project: process.env.VAL_PROJECT || valConfigFile.project
-  } : process.env.VAL_PROJECT ? {
-    project: process.env.VAL_PROJECT
-  } : undefined;
-  console.log(pc.greenBright(`Validating project${resolvedValConfigFile !== null && resolvedValConfigFile !== void 0 && resolvedValConfigFile.project ? ` '${pc.inverse(resolvedValConfigFile.project)}'` : ""}...`));
-  const valFiles = await glob("**/*.val.{js,ts}", {
-    ignore: ["node_modules/**"],
-    cwd: projectRoot
-  });
-  console.log(pc.greenBright(`Found ${valFiles.length} files...`));
   let prettier;
   try {
-    prettier = (await import('prettier')).default;
+    prettier = await import('prettier');
   } catch {
     console.log("Prettier not found, skipping formatting");
   }
-  const fixedFiles = new Set();
-  let totalErrors = 0;
-  for await (const event of runValidation({
-    root: projectRoot,
-    fix: !!fix,
-    valFiles,
-    project: resolvedValConfigFile === null || resolvedValConfigFile === void 0 ? void 0 : resolvedValConfigFile.project,
-    remote: {
-      remoteHost: process.env.VAL_REMOTE_HOST || DEFAULT_VAL_REMOTE_HOST,
-      getSettings: (projectName, options) => getSettings(projectName, options),
-      uploadFile: (project, bucket, fileHash, fileExt, fileBuffer, options) => uploadRemoteFile(process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST, project, bucket, fileHash, fileExt ?? "", fileBuffer, options)
-    },
-    fs: createDefaultValFSHost()
-  })) {
-    switch (event.type) {
-      case "file-valid":
-        console.log(pc.green("✔"), event.file, "is valid (" + event.durationMs + "ms)");
-        break;
-      case "file-error-count":
-        console.log(pc.red("✘"), `${event.file} contains ${event.errorCount} error${event.errorCount > 1 ? "s" : ""}`, " (" + event.durationMs + "ms)");
-        totalErrors += event.errorCount;
-        break;
-      case "validation-error":
-        console.log(pc.red("✘"), "Got error in", `${event.sourcePath}:`, event.message);
-        break;
-      case "validation-fixable-error":
-        console.log(event.fixable ? pc.yellow("⚠") : pc.red("✘"), `Got ${event.fixable ? "fixable " : ""}error in`, `${event.sourcePath}:`, event.message);
-        break;
-      case "unknown-fix":
-        console.log(pc.red("✘"), "Unknown fix", event.fixes, "for", event.sourcePath);
-        break;
-      case "fix-applied":
-        console.log(pc.yellow("⚠"), "Applied fix for", event.sourcePath);
-        fixedFiles.add(event.file);
-        break;
-      case "fatal-error":
-        console.log(pc.red("✘"), event.file, "is invalid:", event.message);
-        break;
-      case "remote-uploading":
-        console.log(pc.yellow("⚠"), `Uploading remote file: '${event.ref}'...`);
-        break;
-      case "remote-uploaded":
-        console.log(pc.green("✔"), `Completed upload of remote file: '${event.ref}'`);
-        break;
-      case "remote-already-uploaded":
-        console.log(pc.yellow("⚠"), `Remote file ${event.filePath} already uploaded`);
-        break;
-      case "remote-downloading":
-        console.log(pc.yellow("⚠"), `Downloading remote file in ${event.sourcePath}...`);
-        break;
+
+  // Runs a single validation pass over the project and returns the number of
+  // errors found. Re-reads config and val files each call so it always reflects
+  // the latest state on disk (used both for one-shot and watch mode).
+  async function runOnce() {
+    const valConfigFile = (await evalValConfigFile(projectRoot, "val.config.ts")) || (await evalValConfigFile(projectRoot, "val.config.js"));
+    const resolvedValConfigFile = valConfigFile ? {
+      ...valConfigFile,
+      project: process.env.VAL_PROJECT || valConfigFile.project
+    } : process.env.VAL_PROJECT ? {
+      project: process.env.VAL_PROJECT
+    } : undefined;
+    console.log(pc.greenBright(`Validating project${resolvedValConfigFile !== null && resolvedValConfigFile !== void 0 && resolvedValConfigFile.project ? ` '${pc.inverse(resolvedValConfigFile.project)}'` : ""}...`));
+    const valFiles = await glob("**/*.val.{js,ts}", {
+      ignore: ["node_modules/**"],
+      cwd: projectRoot
+    });
+    console.log(pc.greenBright(`Found ${valFiles.length} files...`));
+    const fixedFiles = new Set();
+    let totalErrors = 0;
+
+    // Caches each val file's parsed source so files are read/parsed at most once
+    // per pass when resolving sourcePaths to file locations and code frames.
+    const sourceFileCache = new Map();
+
+    // Diagnostics are buffered per module (keyed by relative file path) so we can
+    // render them grouped and prioritised after the run, rather than streaming
+    // them out interleaved. Transient progress (remote/fix-applied) still streams
+    // live below.
+    const reports = new Map();
+    const valid = [];
+    const skipped = [];
+
+    // Relative file path (no leading slash), matching the code frame's
+    // relativeFile so headers, diagnostics and frames all agree.
+    const relFile = file => file.replace(/^\//, "");
+    // The module a sourcePath/file belongs to is the part before the `?p=...`.
+    const moduleOf = sourcePathOrFile => relFile(sourcePathOrFile.split("?")[0]);
+    const reportFor = file => {
+      const key = relFile(file);
+      let report = reports.get(key);
+      if (!report) {
+        report = {
+          file: key,
+          durationMs: 0,
+          diagnostics: []
+        };
+        reports.set(key, report);
+      }
+      return report;
+    };
+    for await (const event of runValidation({
+      root: projectRoot,
+      fix: !!fix,
+      valFiles,
+      project: resolvedValConfigFile === null || resolvedValConfigFile === void 0 ? void 0 : resolvedValConfigFile.project,
+      remote: {
+        remoteHost: process.env.VAL_REMOTE_HOST || DEFAULT_VAL_REMOTE_HOST,
+        getSettings: (projectName, options) => getSettings(projectName, options),
+        uploadFile: (project, bucket, fileHash, fileExt, fileBuffer, options) => uploadRemoteFile(process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST, project, bucket, fileHash, fileExt ?? "", fileBuffer, options)
+      },
+      fs: createDefaultValFSHost()
+    })) {
+      switch (event.type) {
+        case "file-valid":
+          valid.push({
+            file: relFile(event.file),
+            durationMs: event.durationMs
+          });
+          break;
+        case "file-error-count":
+          reportFor(event.file).durationMs = event.durationMs;
+          totalErrors += event.errorCount;
+          break;
+        case "validation-error":
+          reportFor(moduleOf(event.sourcePath)).diagnostics.push({
+            severity: "error",
+            sourcePath: event.sourcePath,
+            message: event.message,
+            ...(event.keyError ? {
+              keyError: true
+            } : {})
+          });
+          break;
+        case "validation-fixable-error":
+          reportFor(moduleOf(event.sourcePath)).diagnostics.push({
+            severity: event.fixable ? "fixable" : "error",
+            sourcePath: event.sourcePath,
+            message: event.message,
+            ...(event.keyError ? {
+              keyError: true
+            } : {})
+          });
+          break;
+        case "unknown-fix":
+          reportFor(moduleOf(event.sourcePath)).diagnostics.push({
+            severity: "error",
+            sourcePath: event.sourcePath,
+            message: `Unknown fix: ${event.fixes.join(", ")}`,
+            ...(event.keyError ? {
+              keyError: true
+            } : {})
+          });
+          break;
+        case "unregistered-module":
+          skipped.push(event.file);
+          break;
+        case "fatal-error":
+          // No sourcePath for fatal errors; group by file, render message only.
+          reportFor(event.file).diagnostics.push({
+            severity: "error",
+            sourcePath: event.file,
+            message: event.message
+          });
+          break;
+        case "fix-applied":
+          console.log(pc.yellow("⚠"), "Applied fix for", event.sourcePath);
+          fixedFiles.add(event.file);
+          break;
+        case "remote-uploading":
+          console.log(pc.yellow("⚠"), `Uploading remote file: '${event.ref}'...`);
+          break;
+        case "remote-uploaded":
+          console.log(pc.green("✔"), `Completed upload of remote file: '${event.ref}'`);
+          break;
+        case "remote-already-uploaded":
+          console.log(pc.yellow("⚠"), `Remote file ${event.filePath} already uploaded`);
+          break;
+        case "remote-downloading":
+          console.log(pc.yellow("⚠"), `Downloading remote file in ${event.sourcePath}...`);
+          break;
+      }
     }
-  }
 
-  // Run prettier on files that had fixes applied
-  if (prettier) {
-    for (const file of fixedFiles) {
-      const filePath = path.join(projectRoot, file);
-      const fileContent = await fs.readFile(filePath, "utf-8");
-      const formattedContent = await prettier.format(fileContent, {
-        filepath: filePath
-      });
-      await fs.writeFile(filePath, formattedContent);
+    // Renders a module's diagnostics under a single left "│" gutter bar, with the
+    // file name on top and blank gutter lines for air. Output flows least- to
+    // most-actionable top-to-bottom, so fixable diagnostics are shown last (at the
+    // bottom, nearest the prompt).
+    const renderModule = report => {
+      const bar = pc.dim("│");
+      const diagnostics = [...report.diagnostics].sort((a, b) => a.severity === b.severity ? 0 : a.severity === "fixable" ? 1 : -1);
+      const fixableCount = diagnostics.filter(d => d.severity === "fixable").length;
+      const total = diagnostics.length;
+      const hasError = fixableCount < total;
+      const symbol = hasError ? pc.red("✘") : pc.yellow("⚠");
+      let label;
+      if (fixableCount === total) {
+        label = `${fixableCount} fixable`;
+      } else if (fixableCount > 0) {
+        label = `${total} error${total > 1 ? "s" : ""} (${fixableCount} fixable)`;
+      } else {
+        label = `${total} error${total > 1 ? "s" : ""}`;
+      }
+      console.log(`${pc.bold(report.file)}  ${symbol} ${label}  ${pc.dim(`(${report.durationMs}ms)`)}`);
+      for (const d of diagnostics) {
+        const target = d.keyError ? "key" : "value";
+        const dsym = d.severity === "fixable" ? pc.yellow("⚠") : pc.red("✘");
+        const parts = sourcePathToLocationParts(d.sourcePath, projectRoot, sourceFileCache, target);
+        console.log(bar);
+        if (parts) {
+          // `file:line:col` (no key/value label) so VS Code's terminal links it.
+          console.log(`${bar}  ${dsym}  ${parts.relativeFile}:${parts.line}:${parts.character}`);
+          console.log(`${bar}     ${d.message}`);
+        } else {
+          console.log(`${bar}  ${dsym}  ${d.message}`);
+        }
+        const frame = sourcePathToCodeFrame(d.sourcePath, projectRoot, sourceFileCache, target);
+        if (frame !== undefined) {
+          console.log(bar);
+          for (const frameLine of frame.split("\n")) {
+            console.log(`${bar}     ${frameLine}`);
+          }
+        }
+        if (d.severity === "fixable") {
+          console.log(`${bar}     ${pc.dim("→ run with --fix to apply")}`);
+        }
+      }
+      console.log(bar);
+      console.log("");
+    };
+
+    // Run prettier on files that had fixes applied
+    if (prettier) {
+      for (const file of fixedFiles) {
+        const filePath = path.join(projectRoot, file);
+        const fileContent = await fs.readFile(filePath, "utf-8");
+        const formattedContent = await prettier.format(fileContent, {
+          filepath: filePath
+        });
+        await fs.writeFile(filePath, formattedContent);
+      }
+    }
+
+    // Render the grouped report least- to most-actionable, top-to-bottom, so the
+    // most important things end up at the bottom nearest the prompt: valid files
+    // and skipped modules first, then error-only modules, then fixable modules.
+    const allReports = [...reports.values()];
+    const fixableModules = allReports.filter(r => r.diagnostics.some(d => d.severity === "fixable"));
+    const errorModules = allReports.filter(r => !r.diagnostics.some(d => d.severity === "fixable"));
+    for (const v of valid) {
+      console.log(pc.green("✔"), pc.dim(`${v.file}  valid (${v.durationMs}ms)`));
+    }
+    for (const file of skipped) {
+      console.log(pc.yellow("⚠"), pc.dim(`/${file} is not registered in val.modules - skipping`));
+    }
+    if (allReports.length > 0) {
+      console.log("");
     }
+    for (const report of [...errorModules, ...fixableModules]) {
+      renderModule(report);
+    }
+    const fixableTotal = allReports.reduce((n, r) => n + r.diagnostics.filter(d => d.severity === "fixable").length, 0);
+    if (totalErrors > 0) {
+      let summary = `${totalErrors} error${totalErrors > 1 ? "s" : ""}`;
+      if (fixableTotal > 0) {
+        summary += ` (${fixableTotal} fixable)`;
+      }
+      summary += ` across ${allReports.length} file${allReports.length > 1 ? "s" : ""}`;
+      if (valid.length > 0) {
+        summary += ` · ${valid.length} valid`;
+      }
+      if (skipped.length > 0) {
+        summary += ` · ${skipped.length} skipped`;
+      }
+      console.log(pc.red("✘"), summary);
+    } else {
+      let summary = "No validation errors found";
+      if (valid.length > 0) {
+        summary += ` · ${valid.length} valid`;
+      }
+      if (skipped.length > 0) {
+        summary += ` · ${skipped.length} skipped`;
+      }
+      console.log(pc.green("✔"), summary);
+    }
+    return totalErrors;
   }
-  if (totalErrors > 0) {
-    console.log(pc.red("✘"), "Got", totalErrors, "error" + (totalErrors > 1 ? "s" : ""));
-    process.exit(1);
-  } else {
-    console.log(pc.green("✔"), "No validation errors found");
+  if (!watch) {
+    const totalErrors = await runOnce();
+    if (totalErrors > 0) {
+      process.exit(1);
+    }
+    return;
   }
+  await watchAndValidate(projectRoot, runOnce);
+}
+
+// Directory names anywhere in the path that should never be watched.
+const WATCH_IGNORED = /(^|[\\/])(node_modules|\.git|dist)([\\/]|$)/;
+function isRelevantValFile(filePath) {
+  const base = path.basename(filePath);
+  return base === "val.modules.ts" || base === "val.modules.js" || base === "val.config.ts" || base === "val.config.js" || /\.val\.(ts|js)$/.test(base);
+}
+async function watchAndValidate(projectRoot, runOnce) {
+  // Initial pass.
+  await runOnce();
+  const watchingMessage = pc.dim("Watching for changes... (Ctrl+C to exit)");
+  console.log(watchingMessage);
+
+  // chokidar 5 is ESM-only; load it dynamically (like prettier above).
+  const {
+    watch
+  } = await import('chokidar');
+  let running = false;
+  let pending = false;
+  let debounceTimer;
+  const triggerRun = async () => {
+    if (running) {
+      pending = true;
+      return;
+    }
+    running = true;
+    // Clear the screen (and scrollback) so only the latest result shows.
+    process.stdout.write("\x1b[2J\x1b[3J\x1b[H");
+    console.log(pc.cyanBright("Re-validating..."));
+    try {
+      await runOnce();
+    } catch (err) {
+      console.error(err);
+    }
+    console.log(watchingMessage);
+    running = false;
+    if (pending) {
+      pending = false;
+      void triggerRun();
+    }
+  };
+  const watcher = watch(projectRoot, {
+    ignoreInitial: true,
+    ignored: watchedPath => WATCH_IGNORED.test(watchedPath)
+  });
+  watcher.on("all", (_event, changedPath) => {
+    if (!isRelevantValFile(changedPath)) {
+      return;
+    }
+    if (debounceTimer) {
+      clearTimeout(debounceTimer);
+    }
+    debounceTimer = setTimeout(() => void triggerRun(), 150);
+  });
+  process.on("SIGINT", () => {
+    void watcher.close().then(() => process.exit(0));
+  });
 }
 
 async function listUnusedFiles({
   root
 }) {
-  const managedDir = "public/val";
+  var _valConfigFile$files;
   const projectRoot = root ? path.resolve(root) : process.cwd();
-  const service = await createService(projectRoot, {});
+  const valConfigFile = (await evalValConfigFile(projectRoot, "val.config.ts")) || (await evalValConfigFile(projectRoot, "val.config.js"));
+  // Strip the leading "/" so it is relative to the project root (e.g. "public/val").
+  const managedDir = ((valConfigFile === null || valConfigFile === void 0 || (_valConfigFile$files = valConfigFile.files) === null || _valConfigFile$files === void 0 ? void 0 : _valConfigFile$files.directory) ?? "/public/val").replace(/^\//, "");
+  const service = await createService(projectRoot);
+  const registered = new Set(service.getModuleFilePaths());
   const valFiles = await glob("**/*.val.{js,ts}", {
     ignore: ["node_modules/**"],
     cwd: projectRoot
@@ -804,10 +1174,12 @@ async function listUnusedFiles({
   const filesUsedByVal = [];
   async function pushFilesUsedByVal(file) {
     const moduleId = `/${file}`; // TODO: check if this always works? (Windows?)
+    if (!registered.has(moduleId)) {
+      // Not registered in val.modules - skip (e.g. reusable schema fragments).
+      return;
+    }
     const valModule = await service.get(moduleId, "", {
-      validate: true,
-      source: true,
-      schema: true
+      validate: true
     });
     // TODO: not sure using validation is the best way to do this, but it works currently.
     if (valModule.errors) {
@@ -954,8 +1326,8 @@ function tryGetGitConfig(root) {
   let lastDir = null;
   while (currentDir !== lastDir) {
     const gitConfigPath = path.join(currentDir, ".git", "config");
-    if (nodeFs.existsSync(gitConfigPath)) {
-      return nodeFs.readFileSync(gitConfigPath, "utf-8");
+    if (fs$1.existsSync(gitConfigPath)) {
+      return fs$1.readFileSync(gitConfigPath, "utf-8");
     }
     lastDir = currentDir;
     currentDir = path.dirname(currentDir);
@@ -1038,13 +1410,909 @@ async function pollForConfirmation(token) {
   process.exit(1);
 }
 function saveToken(result, filePath) {
-  nodeFs.mkdirSync(path.dirname(filePath), {
+  fs$1.mkdirSync(path.dirname(filePath), {
     recursive: true
   });
-  nodeFs.writeFileSync(filePath, JSON.stringify(result, null, 2));
+  fs$1.writeFileSync(filePath, JSON.stringify(result, null, 2));
   console.log(pc.green(`Token for ${pc.cyan(result.profile.email)} saved to ${pc.cyan(filePath)}`));
 }
 
+/**
+ * Everything the debug commands need in order to talk to the same ops the
+ * running app talks to.
+ *
+ * Mirrors how the app itself decides between fs and http mode in
+ * `initHandlerOptions` (packages/server/src/ValRouter.ts): a project name plus
+ * credentials means the patches live in the hosted content service, otherwise
+ * they are on disk under `<root>/.val`.
+ */
+
+class DebugContextError extends Error {}
+async function createDebugContext(options) {
+  var _config$files;
+  const projectRoot = options.root ? path.resolve(options.root) : process.cwd();
+  if (!fs$1.existsSync(projectRoot)) {
+    throw new DebugContextError(`Project root does not exist: ${projectRoot}`);
+  }
+  const config = (await evalValConfigFile(projectRoot, "val.config.ts")) || (await evalValConfigFile(projectRoot, "val.config.js"));
+  if (!config) {
+    throw new DebugContextError(`Could not find val.config.ts nor val.config.js in: ${projectRoot}`);
+  }
+  const valModules = loadValModules(projectRoot);
+  const contentUrl = process.env.VAL_CONTENT_URL || DEFAULT_CONTENT_HOST;
+  const filesDirectory = ((_config$files = config.files) === null || _config$files === void 0 ? void 0 : _config$files.directory) ?? "/public/val";
+  const project = config.project || process.env.VAL_PROJECT || null;
+  const git = await safeReadGit(projectRoot);
+  const branch = options.branch || config.gitBranch || process.env.VAL_GIT_BRANCH || git.branch || null;
+  const commit = options.commit || config.gitCommit || process.env.VAL_GIT_COMMIT || git.commit || null;
+  const wantsRemote = options.remote || !!process.env.VAL_API_KEY;
+  const auth = wantsRemote ? readAuth(projectRoot) : null;
+  if (wantsRemote) {
+    if (!project) {
+      throw new DebugContextError("Cannot read remote patches: no project is configured.\n" + "Set 'project' in val.config, or the VAL_PROJECT env var.");
+    }
+    if (!auth) {
+      throw new DebugContextError("Cannot read remote patches: you are not logged in.\n\n\tnpx val login\n\n" + "(or set the VAL_API_KEY env var)");
+    }
+    if (!branch) {
+      throw new DebugContextError("Could not determine the branch. Pass --branch, or set VAL_GIT_BRANCH.");
+    }
+    if (!commit) {
+      throw new DebugContextError("Could not determine the commit. Pass --commit, or set VAL_GIT_COMMIT.\n" + "This must be the commit the app was deployed from: it is the commit the module sources are read at.");
+    }
+    return {
+      projectRoot,
+      valModules,
+      config,
+      mode: "http",
+      project,
+      branch,
+      commit,
+      authKind: "pat" in auth ? "pat" : "api-key",
+      contentUrl,
+      filesDirectory,
+      serverOps: new ValOpsHttp(contentUrl, project, commit, branch, auth, valModules, {
+        root: config.root,
+        config
+      })
+    };
+  }
+  return {
+    projectRoot,
+    valModules,
+    config,
+    mode: "fs",
+    project,
+    branch,
+    commit,
+    authKind: "none",
+    contentUrl,
+    filesDirectory,
+    serverOps: new ValOpsFS(contentUrl, projectRoot, valModules, {
+      config
+    })
+  };
+}
+
+/**
+ * The personal access token written by `val login`, falling back to the api key
+ * the app itself uses. Reading the pat file is the same dance as
+ * `resolveRemoteFile` in runValidation.ts.
+ */
+function readAuth(projectRoot) {
+  const patFile = getPersonalAccessTokenPath(projectRoot);
+  if (fs$1.existsSync(patFile)) {
+    const contents = fs$1.readFileSync(patFile, "utf-8");
+    const parsed = parsePersonalAccessTokenFile(contents);
+    if (parsed.success) {
+      return {
+        pat: parsed.data.pat
+      };
+    }
+    throw new DebugContextError(`Could not parse the personal access token at ${patFile}: ${parsed.error}.\n` + `Log in again:\n\n\tnpx val login`);
+  }
+  const apiKey = process.env.VAL_API_KEY;
+  if (apiKey) {
+    return {
+      apiKey
+    };
+  }
+  return null;
+}
+
+/**
+ * The set of modules a snapshot has to carry so that it both evaluates and
+ * validates the same way the customer's project does.
+ *
+ * Starts from the modules the pending patches touch and closes over the
+ * cross-module references a schema can hold:
+ *  - `keyOf` points at another module through its `path` (a SourcePath)
+ *  - `image`/`file` point at a gallery module through `referencedModule`
+ *  - route validation cross-references *every* router module, so if any
+ *    included module has a route or router we need all of them
+ */
+function resolveModuleClosure(patchedModules, serializedSchemas) {
+  const included = new Map();
+  const addReason = (moduleFilePath, reason) => {
+    const existing = included.get(moduleFilePath);
+    if (existing) {
+      existing.push(reason);
+      return false;
+    }
+    included.set(moduleFilePath, [reason]);
+    return true;
+  };
+  const queue = [];
+  for (const moduleFilePath of patchedModules) {
+    if (addReason(moduleFilePath, {
+      type: "patched"
+    })) {
+      queue.push(moduleFilePath);
+    }
+  }
+  let needsAllRouterModules = false;
+  while (queue.length > 0) {
+    const moduleFilePath = queue.shift();
+    if (moduleFilePath === undefined) {
+      continue;
+    }
+    const schema = serializedSchemas[moduleFilePath];
+    if (!schema) {
+      continue;
+    }
+    const refs = collectSchemaReferences(schema);
+    if (refs.hasRouteOrRouter) {
+      needsAllRouterModules = true;
+    }
+    for (const keyOfPath of refs.keyOfSourcePaths) {
+      const [referenced] = Internal.splitModuleFilePathAndModulePath(keyOfPath);
+      if (addReason(referenced, {
+        type: "keyOf",
+        from: moduleFilePath
+      })) {
+        queue.push(referenced);
+      }
+    }
+    for (const referencedModule of refs.referencedModules) {
+      // referencedModule is a module file path written in the schema, so it is
+      // only trustworthy insofar as it names a module we know about.
+      const referenced = Object.keys(serializedSchemas).find(candidate => candidate === referencedModule);
+      if (referenced === undefined) {
+        continue;
+      }
+      if (addReason(referenced, {
+        type: "referencedModule",
+        from: moduleFilePath
+      })) {
+        queue.push(referenced);
+      }
+    }
+  }
+  if (needsAllRouterModules) {
+    for (const [moduleFilePathS, schema] of Object.entries(serializedSchemas)) {
+      if (collectSchemaReferences(schema).isRouterModule) {
+        addReason(moduleFilePathS, {
+          type: "router"
+        });
+      }
+    }
+  }
+  return included;
+}
+function collectSchemaReferences(schema) {
+  const refs = {
+    keyOfSourcePaths: [],
+    referencedModules: [],
+    hasRouteOrRouter: false,
+    isRouterModule: false
+  };
+  const visit = (node, isRoot) => {
+    switch (node.type) {
+      case "keyOf":
+        refs.keyOfSourcePaths.push(node.path);
+        break;
+      case "route":
+        refs.hasRouteOrRouter = true;
+        break;
+      case "file":
+      case "image":
+        if (node.referencedModule) {
+          refs.referencedModules.push(node.referencedModule);
+        }
+        break;
+      case "record":
+        if (node.router) {
+          refs.hasRouteOrRouter = true;
+          if (isRoot) {
+            refs.isRouterModule = true;
+          }
+        }
+        visit(node.item, false);
+        if (node.key) {
+          visit(node.key, false);
+        }
+        if (node.alt) {
+          visit(node.alt, false);
+        }
+        break;
+      case "array":
+        visit(node.item, false);
+        break;
+      case "object":
+        for (const item of Object.values(node.items)) {
+          visit(item, false);
+        }
+        break;
+      case "union":
+        if (typeof node.key !== "string") {
+          visit(node.key, false);
+        }
+        for (const item of node.items) {
+          visit(item, false);
+        }
+        break;
+    }
+  };
+  visit(schema, true);
+  return refs;
+}
+
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".cjs", ".mjs"];
+/**
+ * Walks the relative-import graph of `entryFiles` and reads every project file
+ * it reaches, using `readFile` so the contents come from the same revision as
+ * the modules themselves (the deployed commit in http mode).
+ *
+ * `loadValModules` evaluates val.modules.ts and everything it imports in a vm,
+ * so a snapshot that is missing an imported file (a shared schema fragment, or
+ * val.config itself) cannot be replayed at all.
+ */
+async function collectImportedProjectFiles(entryFiles, readFile) {
+  const files = {};
+  const unresolved = [];
+  const seen = new Set();
+  const queue = [];
+  for (const entry of entryFiles) {
+    seen.add(entry.path);
+    queue.push(entry);
+  }
+  while (queue.length > 0) {
+    const current = queue.shift();
+    if (current === undefined) {
+      continue;
+    }
+    const dir = path.posix.dirname(current.path);
+    for (const specifier of readImportSpecifiers(current.path, current.contents)) {
+      if (!specifier.startsWith(".")) {
+        unresolved.push({
+          from: current.path,
+          specifier
+        });
+        continue;
+      }
+      const base = path.posix.resolve(dir, specifier);
+      const resolved = await resolveProjectFile(base, readFile);
+      if (!resolved) {
+        unresolved.push({
+          from: current.path,
+          specifier
+        });
+        continue;
+      }
+      if (seen.has(resolved.path)) {
+        continue;
+      }
+      seen.add(resolved.path);
+      files[resolved.path] = resolved.contents;
+      queue.push(resolved);
+    }
+  }
+  return {
+    files,
+    unresolved
+  };
+}
+async function resolveProjectFile(base, readFile) {
+  const candidates = [base, ...RESOLVE_EXTENSIONS.map(ext => base + ext), ...RESOLVE_EXTENSIONS.map(ext => path.posix.join(base, "index" + ext))];
+  for (const candidate of candidates) {
+    const contents = await readFile(candidate);
+    if (contents !== null) {
+      return {
+        path: candidate,
+        contents
+      };
+    }
+  }
+  return null;
+}
+
+/**
+ * Every module specifier in the file: static imports/exports and the dynamic
+ * `import()` calls val.modules.ts is built out of.
+ */
+function readImportSpecifiers(filePath, contents) {
+  const sourceFile = ts.createSourceFile(filePath, contents, ts.ScriptTarget.ES2020, true);
+  const specifiers = [];
+  const visit = node => {
+    if ((ts.isImportDeclaration(node) || ts.isExportDeclaration(node)) && node.moduleSpecifier && ts.isStringLiteral(node.moduleSpecifier)) {
+      specifiers.push(node.moduleSpecifier.text);
+    } else if (ts.isCallExpression(node) && (node.expression.kind === ts.SyntaxKind.ImportKeyword || ts.isIdentifier(node.expression) && node.expression.text === "require") && node.arguments.length > 0) {
+      const arg = node.arguments[0];
+      if (ts.isStringLiteral(arg)) {
+        specifiers.push(arg.text);
+      }
+    }
+    ts.forEachChild(node, visit);
+  };
+  visit(sourceFile);
+  return specifiers;
+}
+
+/** Long strings (base64 payloads) are elided so a snapshot stays attachable. */
+const MAX_PATCH_STRING_LENGTH = 4096;
+async function buildSnapshot(ctx, options = {}) {
+  const {
+    serverOps
+  } = ctx;
+  const patchesRes = await serverOps.fetchPatches({
+    patchIds: undefined,
+    excludePatchOps: false
+  });
+  if (patchesRes.error) {
+    throw new Error(`Could not fetch patches: ${patchesRes.error.message}`);
+  }
+  const orderedPatches = patchesRes.patches;
+  const analysis = {
+    ...serverOps.analyzePatches(orderedPatches),
+    ...patchesRes
+  };
+  const prepared = await serverOps.prepare(analysis, {
+    continueOnError: true
+  });
+  const serializedSchemas = await serverOps.getSerializedSchemas();
+  const patchedModules = Object.keys(analysis.patchesByModule).map(moduleFilePathS => moduleFilePathS);
+  const closure = resolveModuleClosure(patchedModules, serializedSchemas);
+
+  // Read every included module at the revision the ops point at. prepare()
+  // already read the patched ones, so reuse those rather than fetching twice.
+  const moduleTexts = {};
+  const moduleProvenance = {};
+  for (const moduleFilePath of closure.keys()) {
+    const fromPrepare = prepared.previousSourceFiles[moduleFilePath];
+    if (fromPrepare !== undefined) {
+      moduleTexts[moduleFilePath] = fromPrepare;
+      moduleProvenance[moduleFilePath] = "ops";
+      continue;
+    }
+    const res = await serverOps.readProjectFile(moduleFilePath);
+    if (res.error) {
+      const local = readLocalFile(ctx.projectRoot, moduleFilePath);
+      if (local !== null) {
+        moduleTexts[moduleFilePath] = local;
+        moduleProvenance[moduleFilePath] = "local";
+      } else {
+        moduleProvenance[moduleFilePath] = "missing";
+        console.warn(`Could not read module ${moduleFilePath}: ${res.error.message}`);
+      }
+      continue;
+    }
+    moduleTexts[moduleFilePath] = res.data;
+    moduleProvenance[moduleFilePath] = "ops";
+  }
+
+  // Files the modules import, at the same revision, falling back to local disk.
+  const readProjectFileOrLocal = async projectRelativePath => {
+    const res = await serverOps.readProjectFile(projectRelativePath);
+    if (!res.error) {
+      return res.data;
+    }
+    return readLocalFile(ctx.projectRoot, projectRelativePath);
+  };
+  const imported = await collectImportedProjectFiles(Object.entries(moduleTexts).map(([p, contents]) => ({
+    path: p,
+    contents
+  })), readProjectFileOrLocal);
+  const entries = {};
+  for (const [projectPath, contents] of Object.entries(moduleTexts)) {
+    entries[toSnapshotPath(projectPath)] = contents;
+  }
+  for (const [projectPath, contents] of Object.entries(imported.files)) {
+    entries[toSnapshotPath(projectPath)] = contents;
+  }
+
+  // getCompilerOptions() throws without one of these at the root, so a snapshot
+  // without it cannot be loaded at all.
+  const tsConfig = readLocalFile(ctx.projectRoot, "/tsconfig.json") ?? readLocalFile(ctx.projectRoot, "/jsconfig.json");
+  if (tsConfig === null) {
+    throw new Error(`Could not read tsconfig.json nor jsconfig.json in ${ctx.projectRoot}. ` + `A snapshot cannot be replayed without one.`);
+  }
+  entries["tsconfig.json"] = tsConfig;
+  const originalValModules = readLocalFile(ctx.projectRoot, "/val.modules.ts") ?? readLocalFile(ctx.projectRoot, "/val.modules.js");
+  if (originalValModules !== null) {
+    entries["val.modules.original.ts"] = originalValModules;
+  }
+  entries["val.modules.ts"] = generateValModules(Object.keys(moduleTexts).sort());
+  const patches = toSnapshotPatches(orderedPatches);
+  const elidedPatchValues = [];
+  for (const patch of patches) {
+    const elided = elideLongStrings(patch.patch);
+    patch.patch = elided.value;
+    for (const p of elided.elided) {
+      elidedPatchValues.push({
+        patchId: patch.patchId,
+        path: p
+      });
+    }
+    entries[`.val/patches/${patch.parentPatchId ?? "head"}/patch.json`] = JSON.stringify(toFsPatch(patch), null, 2);
+  }
+  let includesBinaryFiles = false;
+  if (options.includeFiles) {
+    includesBinaryFiles = await writeBinaryFiles(ctx, analysis.fileLastUpdatedByPatchId, patches, entries);
+  }
+  const validation = await validateSnapshotSources(ctx, analysis);
+  const report = {
+    unappliablePatches: prepared.unappliablePatches,
+    appliedPatches: prepared.appliedPatches,
+    triedPatches: prepared.triedPatches,
+    skippedPatches: prepared.skippedPatches,
+    sourceFilePatchErrors: Object.fromEntries(Object.entries(prepared.sourceFilePatchErrors).map(([key, errors]) => [key, errors.map(formatPatchSourceError)])),
+    binaryFilePatchErrors: prepared.binaryFilePatchErrors,
+    hasErrors: prepared.hasErrors,
+    validationErrors: validation
+  };
+  const manifest = {
+    generatedAt: new Date().toISOString(),
+    mode: ctx.mode,
+    project: ctx.project,
+    branch: ctx.branch,
+    commit: ctx.commit,
+    baseSha: await serverOps.getBaseSha(),
+    filesDirectory: ctx.filesDirectory,
+    authKind: ctx.authKind,
+    versions: {
+      core: getVersions().coreVersion,
+      next: getVersions().nextVersion,
+      project: readProjectValVersions(ctx.projectRoot),
+      node: process.version,
+      platform: `${process.platform}-${process.arch}`
+    },
+    modules: Array.from(closure.entries()).map(([moduleFilePath, reasons]) => ({
+      moduleFilePath,
+      reasons,
+      source: moduleProvenance[moduleFilePath] ?? "missing"
+    })),
+    patchCount: patches.length,
+    unappliablePatchCount: Object.keys(prepared.unappliablePatches).length,
+    patchChainSynthesised: ctx.mode === "http",
+    unresolvedImports: imported.unresolved,
+    elidedPatchValues,
+    includesBinaryFiles
+  };
+  entries["manifest.json"] = JSON.stringify(manifest, null, 2);
+  entries["report.json"] = JSON.stringify(report, null, 2);
+  entries["README.md"] = renderReadme(manifest);
+  return {
+    manifest,
+    report,
+    entries
+  };
+}
+
+/**
+ * Validation errors as the studio would compute them: patches applied to the
+ * evaluated json, then the schemas run over the result.
+ */
+async function validateSnapshotSources(ctx, analysis) {
+  const {
+    serverOps
+  } = ctx;
+  const schemas = await serverOps.getSchemas();
+  const validationRes = await serverOps.validateSources(schemas, (await serverOps.getSourcesWithPatchesApplied(analysis)).sources, analysis.patchesByModule);
+  return validationRes.errors;
+}
+function toSnapshotPatches(orderedPatches) {
+  return orderedPatches.map((patch, i) => ({
+    patchId: patch.patchId,
+    path: patch.path,
+    createdAt: patch.createdAt,
+    authorId: patch.authorId,
+    baseSha: patch.baseSha,
+    appliedAt: patch.appliedAt,
+    parentPatchId: i === 0 ? null : orderedPatches[i - 1].patchId,
+    patch: patch.patch
+  }));
+}
+
+/**
+ * The shape ValOpsFS writes per patch, so an unzipped snapshot is a patch store
+ * a plain ValOpsFS can read. The directory is named after the PARENT, and
+ * createPatchChain walks the linked list from "head".
+ */
+function toFsPatch(patch) {
+  return {
+    patch: patch.patch,
+    patchId: patch.patchId,
+    parentRef: patch.parentPatchId === null ? {
+      type: "head",
+      headBaseSha: patch.baseSha
+    } : {
+      type: "patch",
+      patchId: patch.parentPatchId
+    },
+    path: patch.path,
+    authorId: patch.authorId,
+    sessionId: null,
+    baseSha: patch.baseSha,
+    coreVersion: null,
+    createdAt: patch.createdAt
+  };
+}
+async function writeBinaryFiles(ctx, fileLastUpdatedByPatchId, patches, entries) {
+  const parentByPatchId = new Map(patches.map(p => [p.patchId, p.parentPatchId ?? "head"]));
+  let wrote = false;
+  for (const [filePath, data] of Object.entries(fileLastUpdatedByPatchId)) {
+    if (data.isDelete) {
+      continue;
+    }
+    const parentPatchId = parentByPatchId.get(data.patchId);
+    if (parentPatchId === undefined) {
+      continue;
+    }
+    const buffer = await ctx.serverOps.getBase64EncodedBinaryFileFromPatch(filePath, data.patchId, data.remote);
+    if (!buffer) {
+      continue;
+    }
+    // Base64 so the snapshot stays a text-only entry map; the replay decodes it.
+    entries[`.val/patches/${parentPatchId}/files${filePath}/${path.posix.basename(filePath)}.base64`] = buffer.toString("base64");
+    wrote = true;
+  }
+  return wrote;
+}
+function generateValModules(moduleFilePaths) {
+  const imports = moduleFilePaths.map(moduleFilePath => {
+    const withoutExt = moduleFilePath.replace(/\.(ts|js|tsx|jsx)$/, "");
+    return `  { def: () => import(".${withoutExt}") },`;
+  }).join("\n");
+  return `// GENERATED by \`val debug\`: trimmed to the modules this snapshot carries.
+// The project's original is kept as val.modules.original.ts.
+import { modules } from "@valbuild/next";
+import { config } from "./val.config";
+
+export default modules(config, [
+${imports}
+]);
+`;
+}
+function renderReadme(manifest) {
+  return `# Val debug snapshot
+
+Captured ${manifest.generatedAt} from project \`${manifest.project ?? "(fs mode)"}\`,
+branch \`${manifest.branch ?? "?"}\`, commit \`${manifest.commit ?? "?"}\`.
+
+- @valbuild/core: \`${manifest.versions.core ?? "?"}\`
+- @valbuild/next: \`${manifest.versions.next ?? "?"}\`
+- ${manifest.patchCount} pending patches, ${manifest.unappliablePatchCount} of which could not be applied.
+
+## Replaying it
+
+This directory is a minimal Val project: the modules the patches touch (plus the
+ones they reference), a generated \`val.modules.ts\`, and the patch chain under
+\`.val/patches\`. Unzip it into \`debug/\` in the val repo, check out the version
+above, and run:
+
+\`\`\`bash
+pnpm debug:replay debug/<this-directory>
+\`\`\`
+
+That applies the patches the same way \`/save\` does and validates the result, then
+diffs what it finds against \`report.json\` (captured at the time of the bug).
+
+## Notes
+
+${manifest.patchChainSynthesised ? "- The content api does not return `parentRef`, so the patch chain was rebuilt from the order the api returned.\n" : ""}${manifest.unresolvedImports.length > 0 ? `- ${manifest.unresolvedImports.length} import specifier(s) could not be resolved to a project file - see manifest.json. Bare package imports are expected; a tsconfig path alias means the snapshot may not evaluate.\n` : ""}${manifest.elidedPatchValues.length > 0 ? `- ${manifest.elidedPatchValues.length} long patch value(s) were elided - see manifest.json.\n` : ""}${manifest.includesBinaryFiles ? "- Binary files are included, base64 encoded with a `.base64` suffix.\n" : "- Binary files are NOT included (source patching does not need them). Re-run with `--include-files` if you need them.\n"}
+This snapshot contains unpublished content. Treat it as customer data.
+`;
+}
+function toSnapshotPath(projectRelativePath) {
+  return projectRelativePath.replace(/^\//, "");
+}
+
+/** The @valbuild/* versions the project depends on, so we know what to check out. */
+function readProjectValVersions(projectRoot) {
+  const contents = readLocalFile(projectRoot, "/package.json");
+  if (contents === null) {
+    return {};
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(contents);
+  } catch {
+    return {};
+  }
+  if (parsed === null || typeof parsed !== "object") {
+    return {};
+  }
+  const versions = {};
+  for (const field of ["dependencies", "devDependencies"]) {
+    const deps = parsed[field];
+    if (deps === null || typeof deps !== "object") {
+      continue;
+    }
+    for (const [name, version] of Object.entries(deps)) {
+      if (name.startsWith("@valbuild/") && typeof version === "string") {
+        versions[name] = version;
+      }
+    }
+  }
+  return versions;
+}
+function readLocalFile(projectRoot, projectRelativePath) {
+  const absPath = path.join(projectRoot, projectRelativePath);
+  try {
+    return fs$1.readFileSync(absPath, "utf-8");
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Replaces oversized strings (base64 file payloads that were not swapped for a
+ * hash) with a marker, so a snapshot stays small enough to attach.
+ */
+function elideLongStrings(value) {
+  const elided = [];
+  const walk = (node, atPath) => {
+    if (typeof node === "string") {
+      if (node.length > MAX_PATCH_STRING_LENGTH) {
+        elided.push(atPath);
+        return `<elided ${node.length} chars by val debug>`;
+      }
+      return node;
+    }
+    if (Array.isArray(node)) {
+      return node.map((item, i) => walk(item, atPath.concat(i.toString())));
+    }
+    if (node !== null && typeof node === "object") {
+      return Object.fromEntries(Object.entries(node).map(([key, item]) => [key, walk(item, atPath.concat(key))]));
+    }
+    return node;
+  };
+  return {
+    value: walk(value, []),
+    elided
+  };
+}
+
+/**
+ * Prints the pending patches grouped by module, marking the ones that could not
+ * be applied. This is the same information `/save` returns on a 400, except it
+ * lists all of them rather than the first per module.
+ */
+function printPatchReport(patches, prepared, options = {}) {
+  const byModule = new Map();
+  for (const patch of patches) {
+    const existing = byModule.get(patch.path);
+    if (existing) {
+      existing.push(patch);
+    } else {
+      byModule.set(patch.path, [patch]);
+    }
+  }
+  const moduleFilePaths = Array.from(byModule.keys()).sort();
+  for (const moduleFilePath of moduleFilePaths) {
+    const modulePatches = byModule.get(moduleFilePath) ?? [];
+    const unappliableHere = modulePatches.filter(patch => prepared.unappliablePatches[patch.patchId]);
+    const header = `${moduleFilePath} ${pc.dim(`(${modulePatches.length} patch${modulePatches.length === 1 ? "" : "es"})`)}`;
+    console.log(unappliableHere.length > 0 ? pc.red(header) : pc.green(header));
+    for (const patch of modulePatches) {
+      const failure = prepared.unappliablePatches[patch.patchId];
+      if (!failure && !options.verbose) {
+        continue;
+      }
+      const who = patch.authorId ?? "unknown author";
+      const line = `  ${patch.patchId}  ${patch.createdAt}  ${who}`;
+      if (failure) {
+        console.log(pc.red(line));
+        for (const messageLine of failure.message.split("\n")) {
+          console.log(pc.red(`    ${messageLine}`));
+        }
+      } else {
+        console.log(pc.dim(line));
+      }
+    }
+  }
+  const unappliableCount = Object.keys(prepared.unappliablePatches).length;
+  console.log("");
+  if (unappliableCount === 0) {
+    console.log(pc.green(`${patches.length} pending patch${patches.length === 1 ? "" : "es"}, all appliable.`));
+  } else {
+    console.log(pc.red(`${patches.length} pending patch${patches.length === 1 ? "" : "es"}, ` + `${unappliableCount} of which cannot be applied across ${moduleFilePaths.length} module(s).`));
+    console.log(pc.dim("Publishing is blocked until these are removed. See: val delete-unappliable-patches --dry-run"));
+  }
+}
+
+async function debug(options) {
+  let ctx;
+  try {
+    ctx = await createDebugContext(options);
+  } catch (err) {
+    if (err instanceof DebugContextError) {
+      return error(err.message);
+    }
+    throw err;
+  }
+  console.log(pc.dim(`Project: ${ctx.project ?? "(fs mode)"}  branch: ${ctx.branch ?? "?"}  commit: ${ctx.commit ?? "?"}`));
+  console.log(pc.yellow("The snapshot includes unpublished content. Only share it with Val developers."));
+  console.log("");
+  const snapshot = await buildSnapshot(ctx, {
+    includeFiles: options.includeFiles
+  });
+  printPatchReport(snapshot.manifest.modules.length > 0 ? await readPatchMetadata(ctx) : [], snapshot.report, {
+    verbose: options.verbose
+  });
+  const outPath = path.resolve(options.out ?? `./val-debug-${sanitize(ctx.branch ?? "nobranch")}-${(ctx.commit ?? "nocommit").slice(0, 8)}-${timestamp()}.zip`);
+  await writeZip(outPath, snapshot.entries);
+  console.log("");
+  console.log(`Snapshot written to ${pc.cyan(outPath)}`);
+  for (const line of [`unzip ${path.basename(outPath)} -d debug/<name>`, `pnpm debug:replay debug/<name>`]) {
+    console.log(pc.dim(`  ${line}`));
+  }
+  if (snapshot.manifest.unresolvedImports.length > 0) {
+    console.log("");
+    console.log(pc.yellow(`${snapshot.manifest.unresolvedImports.length} import(s) could not be resolved to a project file. ` + `Bare package imports are expected; a tsconfig path alias means the snapshot may not evaluate. See manifest.json.`));
+  }
+}
+
+/**
+ * Patch metadata for the printed report. Fetched without ops so the (large)
+ * patch bodies are not pulled a second time.
+ */
+async function readPatchMetadata(ctx) {
+  const res = await ctx.serverOps.fetchPatches({
+    patchIds: undefined,
+    excludePatchOps: true
+  });
+  if (res.error) {
+    return [];
+  }
+  return res.patches.map(patch => ({
+    patchId: patch.patchId,
+    path: patch.path,
+    createdAt: patch.createdAt,
+    authorId: patch.authorId
+  }));
+}
+async function writeZip(outPath, entries) {
+  const zip = new JSZip();
+  for (const [entryPath, contents] of Object.entries(entries)) {
+    zip.file(entryPath, contents);
+  }
+  const buffer = await zip.generateAsync({
+    type: "nodebuffer",
+    compression: "DEFLATE"
+  });
+  fs$1.mkdirSync(path.dirname(outPath), {
+    recursive: true
+  });
+  fs$1.writeFileSync(outPath, buffer);
+}
+function timestamp() {
+  return new Date().toISOString().replace(/[:.]/g, "-").replace(/Z$/, "");
+}
+function sanitize(value) {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}
+
+/**
+ * Removes the pending patches that cannot be applied, which is what unblocks a
+ * publish that fails with "Failed to create commit".
+ *
+ * Deliberately a separate command from `val debug`: capturing a snapshot must
+ * always be read-only, and deleting destroys the evidence - so take the snapshot
+ * first.
+ */
+async function deleteUnappliablePatches(options) {
+  let ctx;
+  try {
+    ctx = await createDebugContext(options);
+  } catch (err) {
+    if (err instanceof DebugContextError) {
+      return error(err.message);
+    }
+    throw err;
+  }
+  console.log(pc.dim(`Project: ${ctx.project ?? "(fs mode)"}  branch: ${ctx.branch ?? "?"}  commit: ${ctx.commit ?? "?"}`));
+  const first = await analyse(ctx);
+  if (first === null) {
+    return;
+  }
+  printPatchReport(first.metadata, first.prepared, {
+    verbose: options.verbose
+  });
+  const unappliablePatchIds = Object.keys(first.prepared.unappliablePatches).map(patchId => patchId);
+  if (unappliablePatchIds.length === 0) {
+    return;
+  }
+  if (options.dryRun) {
+    console.log("");
+    info("Dry run: nothing was deleted.");
+    return;
+  }
+  if (!options.yes) {
+    console.log("");
+    const confirmed = await confirm(`Delete ${unappliablePatchIds.length} patch(es)? The changes they contain are lost. [y/N] `);
+    if (!confirmed) {
+      info("Aborted, nothing was deleted.");
+      return;
+    }
+  }
+  const deleteRes = await ctx.serverOps.deletePatches(unappliablePatchIds);
+  if (deleteRes.errors && Object.keys(deleteRes.errors).length > 0) {
+    for (const [patchId, err] of Object.entries(deleteRes.errors)) {
+      error(`Could not delete ${patchId}: ${err.message}`);
+    }
+    return;
+  }
+  info(`Deleted ${unappliablePatchIds.length} patch(es).`, {
+    isGood: true
+  });
+  console.log("");
+  console.log(pc.dim("Re-checking the remaining chain..."));
+  const second = await analyse(ctx);
+  if (second === null) {
+    return;
+  }
+  const stillUnappliable = Object.keys(second.prepared.unappliablePatches);
+  if (stillUnappliable.length === 0) {
+    info(`The remaining ${second.metadata.length} patch(es) all apply. Publishing should work now.`, {
+      isGood: true
+    });
+    return;
+  }
+  printPatchReport(second.metadata, second.prepared, {
+    verbose: options.verbose
+  });
+  error(`${stillUnappliable.length} patch(es) still cannot be applied. Run the command again to remove them too.`);
+}
+async function analyse(ctx) {
+  const patchesRes = await ctx.serverOps.fetchPatches({
+    patchIds: undefined,
+    excludePatchOps: false
+  });
+  if (patchesRes.error) {
+    error(`Could not fetch patches: ${patchesRes.error.message}`);
+    return null;
+  }
+  const analysis = {
+    ...ctx.serverOps.analyzePatches(patchesRes.patches),
+    ...patchesRes
+  };
+  const prepared = await ctx.serverOps.prepare(analysis, {
+    continueOnError: true
+  });
+  return {
+    prepared,
+    metadata: patchesRes.patches.map(patch => ({
+      patchId: patch.patchId,
+      path: patch.path,
+      createdAt: patch.createdAt,
+      authorId: patch.authorId
+    }))
+  };
+}
+function confirm(question) {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+  return new Promise(resolve => {
+    rl.question(question, answer => {
+      rl.close();
+      resolve(answer.trim().toLowerCase() === "y");
+    });
+  });
+}
+
 async function main() {
   const {
     input,
@@ -1063,12 +2331,15 @@ async function main() {
         files
         connect
         versions
-      
+        debug
+        delete-unappliable-patches
+
       Command: validate
       Description: val-idate val modules
       Options:
         --root [root], -r [root] Set project root directory (default process.cwd())
         --fix  [fix]             Attempt to fix validation errors
+        --watch, -w              Re-validate on changes to val.config, val.modules and *.val files
 
       
       Command: login
@@ -1084,10 +2355,38 @@ async function main() {
 
       Command: list-unused-files
       Description: EXPERIMENTAL.
-        List files that are in public/val but not in use by any Val module.
+        List files that are in the configured files directory (files.directory, default public/val) but not in use by any Val module.
         This is useful for cleaning up unused files.
       Options:
         --root [root], -r [root] Set project root directory (default process.cwd())
+
+      Command: debug
+      Description: Create a self-contained snapshot (the pending patches plus the modules they
+        touch or reference) that Val developers can replay to reproduce validation and save
+        errors. Read-only.
+      Options:
+        --root [root], -r [root] Set project root directory (default process.cwd())
+        --out [file]             Output zip (default ./val-debug-<branch>-<commit>-<timestamp>.zip)
+        --remote                 Read the patches from the hosted project instead of <root>/.val
+                                 (requires "val login"; implied by VAL_API_KEY)
+        --commit [sha]           Commit to read module sources at (default VAL_GIT_COMMIT, else git HEAD)
+        --branch [name]          Branch (default VAL_GIT_BRANCH, else the current git branch)
+        --include-files          Also download the binary files the patches reference
+        --verbose                List every pending patch, not just the failing ones
+
+      Command: delete-unappliable-patches
+      Description: Delete the pending patches that cannot be applied. This is what unblocks a
+        publish failing with "Failed to create commit". Capture a "val debug" snapshot first:
+        deleting discards the changes those patches contain.
+      Options:
+        --root [root], -r [root] Set project root directory (default process.cwd())
+        --remote                 Operate on the hosted project instead of <root>/.val
+                                 (requires "val login"; implied by VAL_API_KEY)
+        --commit [sha]           Commit to read module sources at (default VAL_GIT_COMMIT, else git HEAD)
+        --branch [name]          Branch (default VAL_GIT_BRANCH, else the current git branch)
+        --dry-run                Only list what would be deleted
+        --yes                    Do not ask for confirmation
+        --verbose                List every pending patch, not just the failing ones
     `, {
     flags: {
       port: {
@@ -1102,11 +2401,39 @@ async function main() {
       fix: {
         type: "boolean"
       },
+      watch: {
+        type: "boolean",
+        alias: "w"
+      },
       noEslint: {
         type: "boolean"
       },
       managedDir: {
         type: "string"
+      },
+      out: {
+        type: "string"
+      },
+      commit: {
+        type: "string"
+      },
+      branch: {
+        type: "string"
+      },
+      includeFiles: {
+        type: "boolean"
+      },
+      remote: {
+        type: "boolean"
+      },
+      dryRun: {
+        type: "boolean"
+      },
+      yes: {
+        type: "boolean"
+      },
+      verbose: {
+        type: "boolean"
       }
     },
     hardRejection: false
@@ -1128,6 +2455,26 @@ async function main() {
       });
     case "versions":
       return versions();
+    case "debug":
+      return debug({
+        root: flags.root,
+        out: flags.out,
+        commit: flags.commit,
+        branch: flags.branch,
+        remote: flags.remote,
+        includeFiles: flags.includeFiles,
+        verbose: flags.verbose
+      });
+    case "delete-unappliable-patches":
+      return deleteUnappliablePatches({
+        root: flags.root,
+        commit: flags.commit,
+        branch: flags.branch,
+        remote: flags.remote,
+        dryRun: flags.dryRun,
+        yes: flags.yes,
+        verbose: flags.verbose
+      });
     case "login":
       return login({
         root: flags.root
@@ -1144,9 +2491,13 @@ async function main() {
       if (flags.managedDir) {
         return error(`Command "validate" does not support --managedDir flag`);
       }
+      if (flags.watch && flags.fix) {
+        return error(`Command "validate" does not support --watch together with --fix`);
+      }
       return validate({
         root: flags.root,
-        fix: flags.fix
+        fix: flags.fix,
+        watch: flags.watch
       });
     default:
       return error(`Unknown command "${input.join(" ")}"`);