@valbuild/cli 0.97.3 → 0.97.4

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@valbuild/cli",
   "private": false,
-  "version": "0.97.3",
+  "version": "0.97.4",
   "description": "Val CLI tools",
   "repository": {
     "type": "git",
@@ -19,16 +19,18 @@
   },
   "dependencies": {
     "chalk": "^5.6.2",
+    "chokidar": "^5.0.0",
     "cors": "^2.8.5",
     "fast-glob": "^3.3.3",
+    "jszip": "^3.10.1",
     "meow": "^9.0.0",
     "open": "^9.1.0",
     "picocolors": "^1.1.1",
     "zod": "^4.3.5",
-    "@valbuild/core": "0.97.1",
+    "@valbuild/core": "0.97.4",
     "@valbuild/eslint-plugin": "0.93.0",
-    "@valbuild/server": "0.97.3",
-    "@valbuild/shared": "0.97.1"
+    "@valbuild/server": "0.97.4",
+    "@valbuild/shared": "0.97.4"
   },
   "peerDependencies": {
     "prettier": "*",

package/src/__fixtures__/basic/val.config.ts

@@ -1,5 +1,5 @@
 import { initVal } from "@valbuild/core";
 
-const { s, c } = initVal();
+const { s, c, config } = initVal();
 
-export { s, c };
+export { s, c, config };

package/src/__fixtures__/basic/val.modules.ts

@@ -0,0 +1,16 @@
+import { modules } from "@valbuild/core";
+import { config } from "./val.config";
+
+export default modules(config, [
+  { def: () => import("./content/basic-valid.val") },
+  { def: () => import("./content/basic-errors.val") },
+  { def: () => import("./content/basic-files.val") },
+  { def: () => import("./content/basic-image.val") },
+  { def: () => import("./content/basic-image-from-gallery.val") },
+  { def: () => import("./content/basic-image-from-galleries.val") },
+  { def: () => import("./content/basic-gallery.val") },
+  { def: () => import("./content/basic-gallery-2.val") },
+  { def: () => import("./content/basic-gallery-fail-on-non-unique-dir.val") },
+  { def: () => import("./content/basic-gallery-missing-tracked.val") },
+  { def: () => import("./content/basic-gallery-wrong-metadata.val") },
+]);

package/src/__fixtures__/debug-snapshot/.val/patches/11111111-1111-4111-8111-111111111111/patch.json

@@ -0,0 +1,19 @@
+{
+  "patch": [
+    {
+      "op": "remove",
+      "path": ["BBL", "summary", "services", "2"]
+    }
+  ],
+  "patchId": "22222222-2222-4222-8222-222222222222",
+  "parentRef": {
+    "type": "patch",
+    "patchId": "11111111-1111-4111-8111-111111111111"
+  },
+  "path": "/content/projects.val.ts",
+  "authorId": "author-b",
+  "sessionId": null,
+  "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
+  "coreVersion": null,
+  "createdAt": "2026-08-11T09:00:00.000Z"
+}

package/src/__fixtures__/debug-snapshot/.val/patches/22222222-2222-4222-8222-222222222222/patch.json

@@ -0,0 +1,20 @@
+{
+  "patch": [
+    {
+      "op": "replace",
+      "path": ["BBL", "summary", "services", "2"],
+      "value": "Development U"
+    }
+  ],
+  "patchId": "33333333-3333-4333-8333-333333333333",
+  "parentRef": {
+    "type": "patch",
+    "patchId": "22222222-2222-4222-8222-222222222222"
+  },
+  "path": "/content/projects.val.ts",
+  "authorId": "author-a",
+  "sessionId": null,
+  "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
+  "coreVersion": null,
+  "createdAt": "2026-08-11T09:00:05.000Z"
+}

package/src/__fixtures__/debug-snapshot/.val/patches/head/patch.json

@@ -0,0 +1,20 @@
+{
+  "patch": [
+    {
+      "op": "replace",
+      "path": ["BBL", "title"],
+      "value": "BBL Housing"
+    }
+  ],
+  "patchId": "11111111-1111-4111-8111-111111111111",
+  "parentRef": {
+    "type": "head",
+    "headBaseSha": "0000000000000000000000000000000000000000000000000000000000000000"
+  },
+  "path": "/content/projects.val.ts",
+  "authorId": "author-a",
+  "sessionId": null,
+  "baseSha": "0000000000000000000000000000000000000000000000000000000000000000",
+  "coreVersion": null,
+  "createdAt": "2026-08-10T12:00:00.000Z"
+}

package/src/__fixtures__/debug-snapshot/content/projects.val.ts

@@ -0,0 +1,23 @@
+import { c, s } from "../val.config";
+import tagsVal from "./tags.val";
+import { summarySchema } from "./summary";
+
+export default c.define(
+  "/content/projects.val.ts",
+  s.record(
+    s.object({
+      title: s.string(),
+      tag: s.keyOf(tagsVal),
+      summary: summarySchema,
+    }),
+  ),
+  {
+    BBL: {
+      title: "BBL",
+      tag: "design",
+      summary: {
+        services: ["Strategy", "Design", "Development"],
+      },
+    },
+  },
+);

package/src/__fixtures__/debug-snapshot/content/summary.ts

@@ -0,0 +1,6 @@
+import { s } from "../val.config";
+
+// A shared schema fragment: a snapshot that omits this file cannot be evaluated.
+export const summarySchema = s.object({
+  services: s.array(s.string()),
+});

package/src/__fixtures__/debug-snapshot/content/tags.val.ts

@@ -0,0 +1,10 @@
+import { c, s } from "../val.config";
+
+export default c.define(
+  "/content/tags.val.ts",
+  s.record(s.object({ label: s.string() })),
+  {
+    design: { label: "Design" },
+    tech: { label: "Tech" },
+  },
+);

package/src/__fixtures__/debug-snapshot/content/unrelated.val.ts

@@ -0,0 +1,5 @@
+import { c, s } from "../val.config";
+
+// Nothing references this module and no patch touches it, so a debug snapshot
+// must NOT include it.
+export default c.define("/content/unrelated.val.ts", s.string(), "unrelated");

package/src/__fixtures__/debug-snapshot/tsconfig.json

@@ -0,0 +1,12 @@
+{
+  "compilerOptions": {
+    "target": "ES2017",
+    "allowJs": true,
+    "skipLibCheck": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "module": "esnext",
+    "moduleResolution": "node"
+  },
+  "exclude": ["node_modules"]
+}

package/src/__fixtures__/debug-snapshot/val.config.ts

@@ -0,0 +1,5 @@
+import { initVal } from "@valbuild/core";
+
+const { s, c, config } = initVal({});
+
+export { s, c, config };

package/src/__fixtures__/debug-snapshot/val.modules.ts

@@ -0,0 +1,8 @@
+import { modules } from "@valbuild/core";
+import { config } from "./val.config";
+
+export default modules(config, [
+  { def: () => import("./content/projects.val") },
+  { def: () => import("./content/tags.val") },
+  { def: () => import("./content/unrelated.val") },
+]);

package/src/cli.ts

@@ -6,6 +6,8 @@ import { getVersions } from "./getVersions";
 import { connect } from "./connect";
 import chalk from "chalk";
 import { login } from "./login";
+import { debug } from "./debug";
+import { deleteUnappliablePatches } from "./deleteUnappliablePatches";
 
 async function main(): Promise<void> {
   const { input, flags, showHelp } = meow(
@@ -22,12 +24,15 @@ async function main(): Promise<void> {
         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
@@ -43,10 +48,38 @@ async function main(): Promise<void> {
 
       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: {
@@ -62,12 +95,40 @@ async function main(): Promise<void> {
         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,
     },
@@ -94,6 +155,26 @@ async function main(): Promise<void> {
       });
     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,
@@ -112,9 +193,15 @@ async function main(): Promise<void> {
       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,
+        watch: flags.watch,
       });
     default:
       return error(`Unknown command "${input.join(" ")}"`);

package/src/debug/context.ts

@@ -0,0 +1,173 @@
+import fs from "fs";
+import path from "path";
+import { DEFAULT_CONTENT_HOST, ValConfig, ValModules } from "@valbuild/core";
+import {
+  getPersonalAccessTokenPath,
+  loadValModules,
+  parsePersonalAccessTokenFile,
+  safeReadGit,
+  ValOpsFS,
+  ValOpsHttp,
+} from "@valbuild/server";
+import { evalValConfigFile } from "../utils/evalValConfigFile";
+
+/**
+ * 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`.
+ */
+export type DebugContext = {
+  projectRoot: string;
+  valModules: ValModules;
+  config: ValConfig;
+  mode: "fs" | "http";
+  project: string | null;
+  branch: string | null;
+  commit: string | null;
+  /** How we authenticated, for the snapshot manifest. Never the secret itself. */
+  authKind: "pat" | "api-key" | "none";
+  contentUrl: string;
+  filesDirectory: string;
+  serverOps: ValOpsFS | ValOpsHttp;
+};
+
+export class DebugContextError extends Error {}
+
+export async function createDebugContext(options: {
+  root?: string;
+  commit?: string;
+  branch?: string;
+  /**
+   * Read patches from the hosted content service rather than `<root>/.val`.
+   *
+   * Has to be explicit: whether a project's patches live remotely depends on
+   * how the *deployed* app is configured (proxy mode), which a local checkout
+   * cannot know. A `val login` token says nothing about it either - it is a user
+   * credential, not a signal. We default to fs mode and let VAL_API_KEY (the
+   * same thing that puts the app in proxy mode) opt in automatically.
+   */
+  remote?: boolean;
+}): Promise<DebugContext> {
+  const projectRoot = options.root ? path.resolve(options.root) : process.cwd();
+  if (!fs.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?.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: string,
+): { pat: string } | { apiKey: string } | null {
+  const patFile = getPersonalAccessTokenPath(projectRoot);
+  if (fs.existsSync(patFile)) {
+    const contents = fs.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;
+}

package/src/debug/importGraph.ts

@@ -0,0 +1,126 @@
+import path from "path";
+import ts from "typescript";
+
+const RESOLVE_EXTENSIONS = [".ts", ".tsx", ".js", ".jsx", ".cjs", ".mjs"];
+
+export type ImportGraphResult = {
+  /** Project-relative path (leading "/") -> file contents. */
+  files: Record<string, string>;
+  /**
+   * Specifiers we could not resolve to a project file: bare packages (fine,
+   * they come from node_modules) and tsconfig path aliases (NOT fine - the
+   * snapshot will not evaluate). Recorded so the manifest can say so out loud
+   * rather than shipping a bundle that mysteriously fails to load.
+   */
+  unresolved: { from: string; specifier: string }[];
+};
+
+/**
+ * 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.
+ */
+export async function collectImportedProjectFiles(
+  entryFiles: { path: string; contents: string }[],
+  readFile: (projectRelativePath: string) => Promise<string | null>,
+): Promise<ImportGraphResult> {
+  const files: Record<string, string> = {};
+  const unresolved: { from: string; specifier: string }[] = [];
+  const seen = new Set<string>();
+  const queue: { path: string; contents: string }[] = [];
+
+  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: string,
+  readFile: (projectRelativePath: string) => Promise<string | null>,
+): Promise<{ path: string; contents: string } | null> {
+  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: string, contents: string): string[] {
+  const sourceFile = ts.createSourceFile(
+    filePath,
+    contents,
+    ts.ScriptTarget.ES2020,
+    true,
+  );
+  const specifiers: string[] = [];
+  const visit = (node: ts.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;
+}