@valbuild/cli 0.97.3 → 0.97.5

package/src/debug.ts

@@ -0,0 +1,120 @@
+import fs from "fs";
+import path from "path";
+import JSZip from "jszip";
+import pc from "picocolors";
+import { createDebugContext, DebugContextError } from "./debug/context";
+import { buildSnapshot } from "./debug/snapshot";
+import { printPatchReport } from "./debug/report";
+import { error } from "./logger";
+
+export async function debug(options: {
+  root?: string;
+  out?: string;
+  commit?: string;
+  branch?: string;
+  remote?: boolean;
+  includeFiles?: boolean;
+  verbose?: boolean;
+}): Promise<void> {
+  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: Awaited<ReturnType<typeof createDebugContext>>,
+) {
+  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: string,
+  entries: Record<string, string>,
+): Promise<void> {
+  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.mkdirSync(path.dirname(outPath), { recursive: true });
+  fs.writeFileSync(outPath, buffer);
+}
+
+function timestamp(): string {
+  return new Date().toISOString().replace(/[:.]/g, "-").replace(/Z$/, "");
+}
+
+function sanitize(value: string): string {
+  return value.replace(/[^a-zA-Z0-9._-]/g, "_");
+}

package/src/deleteUnappliablePatches.ts

@@ -0,0 +1,139 @@
+import readline from "readline";
+import pc from "picocolors";
+import { PatchId } from "@valbuild/core";
+import { OrderedPatches, PatchAnalysis } from "@valbuild/server";
+import { createDebugContext, DebugContextError } from "./debug/context";
+import { printPatchReport } from "./debug/report";
+import { error, info } from "./logger";
+
+/**
+ * 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.
+ */
+export async function deleteUnappliablePatches(options: {
+  root?: string;
+  commit?: string;
+  branch?: string;
+  remote?: boolean;
+  dryRun?: boolean;
+  yes?: boolean;
+  verbose?: boolean;
+}): Promise<void> {
+  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 as 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: Awaited<ReturnType<typeof createDebugContext>>) {
+  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: PatchAnalysis & OrderedPatches = {
+    ...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: string): Promise<boolean> {
+  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");
+    });
+  });
+}

package/src/listUnusedFiles.ts

@@ -8,12 +8,22 @@ import {
 import { createService } from "@valbuild/server";
 import { glob } from "fast-glob";
 import path from "path";
+import { evalValConfigFile } from "./utils/evalValConfigFile";
 
 export async function listUnusedFiles({ root }: { root?: string }) {
-  const managedDir = "public/val";
   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?.files?.directory ?? "/public/val").replace(
+    /^\//,
+    "",
+  );
+
+  const service = await createService(projectRoot);
+  const registered = new Set<ModuleFilePath>(service.getModuleFilePaths());
 
   const valFiles: string[] = await glob("**/*.val.{js,ts}", {
     ignore: ["node_modules/**"],
@@ -23,10 +33,12 @@ export async function listUnusedFiles({ root }: { root?: string }) {
   const filesUsedByVal: string[] = [];
   async function pushFilesUsedByVal(file: string) {
     const moduleId = `/${file}` as ModuleFilePath; // 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, "" as ModulePath, {
       validate: true,
-      source: true,
-      schema: true,
     });
     // TODO: not sure using validation is the best way to do this, but it works currently.
     if (valModule.errors) {

package/src/runValidation.test.ts

@@ -265,12 +265,12 @@ describe("runValidation", () => {
       next = await gen.next();
     }
 
-    const service = await createService(tmpDir, {}, createDefaultValFSHost());
+    const service = await createService(tmpDir, createDefaultValFSHost());
     try {
       const result = await service.get(
         "/content/basic-gallery-missing-tracked.val.ts" as ModuleFilePath,
         "" as ModulePath,
-        { source: true, schema: true, validate: true },
+        { validate: true },
       );
       expect(result.source).not.toHaveProperty(
         "/public/val/images4/missing.png",
@@ -322,12 +322,12 @@ describe("runValidation", () => {
       next = await gen.next();
     }
 
-    const service = await createService(tmpDir, {}, createDefaultValFSHost());
+    const service = await createService(tmpDir, createDefaultValFSHost());
     try {
       const result = await service.get(
         "/content/basic-gallery-wrong-metadata.val.ts" as ModuleFilePath,
         "" as ModulePath,
-        { source: true, schema: true, validate: true },
+        { validate: true },
       );
       expect(result.source).toMatchObject({
         "/public/val/images3/image.png": {
@@ -356,12 +356,12 @@ describe("runValidation", () => {
       next = await gen.next();
     }
 
-    const service = await createService(tmpDir, {}, createDefaultValFSHost());
+    const service = await createService(tmpDir, createDefaultValFSHost());
     try {
       const result = await service.get(
         "/content/basic-image.val.ts" as ModuleFilePath,
         "" as ModulePath,
-        { source: true, schema: true, validate: true },
+        { validate: true },
       );
       // The schema always emits image:check-metadata when metadata exists
       // (actual metadata verification happens in the fix handler).

package/src/runValidation.ts

@@ -62,6 +62,8 @@ export type ValidationError = {
   message: string;
   value?: unknown;
   fixes?: ValidationFix[];
+  // True when the error is about an object/record key rather than its value.
+  keyError?: boolean;
 };
 
 export type FixHandlerContext = {
@@ -109,14 +111,26 @@ export type ValidationEvent =
       errorCount: number;
       durationMs: number;
     }
-  | { type: "validation-error"; sourcePath: string; message: string }
+  | {
+      type: "validation-error";
+      sourcePath: string;
+      message: string;
+      keyError?: boolean;
+    }
   | {
       type: "validation-fixable-error";
       sourcePath: string;
       message: string;
       fixable: boolean;
+      keyError?: boolean;
     }
-  | { type: "unknown-fix"; sourcePath: string; fixes: string[] }
+  | {
+      type: "unknown-fix";
+      sourcePath: string;
+      fixes: string[];
+      keyError?: boolean;
+    }
+  | { type: "unregistered-module"; file: string }
   | { type: "fix-applied"; file: string; sourcePath: string }
   | { type: "fatal-error"; file: string; message: string }
   | { type: "remote-uploading"; ref: string }
@@ -335,12 +349,12 @@ export async function handleRemoteFileUpload(
   const relativeFilePath = path
     .relative(ctx.projectRoot, filePath)
     .split(path.sep)
-    .join("/") as `public/val/${string}`;
+    .join("/") as `public/${string}`;
 
-  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}`,
     };
   }
 
@@ -443,7 +457,7 @@ export async function handleUniqueFolderCheck(
     const otherModule = await ctx.service.get(
       otherModuleFilePath,
       "" as ModulePath,
-      { source: false, schema: true, validate: false },
+      { validate: false },
     );
     const schema = otherModule.schema as
       | { type?: string; directory?: string; mediaType?: string }
@@ -602,19 +616,21 @@ export async function* runValidation({
 }): AsyncGenerator<ValidationEvent> {
   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<ModuleFilePath>(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: SchemaSourceSnapshot = { schemas: {}, sources: {} };
-  for (const file of valFiles) {
-    const moduleFilePath = `/${file}` as ModuleFilePath;
+  for (const moduleFilePath of registered) {
     const valModule = await service.get(moduleFilePath, "" as ModulePath, {
-      source: true,
-      schema: true,
       validate: false,
     });
     if (valModule.schema) {
@@ -627,10 +643,12 @@ export async function* runValidation({
 
   async function* validateFile(file: string): AsyncGenerator<ValidationEvent> {
     const moduleFilePath = `/${file}` as ModuleFilePath; // 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, "" as ModulePath, {
-      source: true,
-      schema: true,
       validate: true,
     });
     const remoteFiles: Record<
@@ -670,6 +688,7 @@ export async function* runValidation({
                   type: "validation-error",
                   sourcePath,
                   message: v.message,
+                  ...(v.keyError ? { keyError: true } : {}),
                 };
                 continue;
               }
@@ -683,6 +702,7 @@ export async function* runValidation({
                   type: "unknown-fix",
                   sourcePath,
                   fixes: v.fixes,
+                  ...(v.keyError ? { keyError: true } : {}),
                 };
                 fileErrors += 1;
                 continue;
@@ -728,6 +748,7 @@ export async function* runValidation({
                   type: "validation-error",
                   sourcePath,
                   message: result.errorMessage ?? "Unknown error",
+                  ...(v.keyError ? { keyError: true } : {}),
                 };
                 fileErrors += 1;
                 continue;
@@ -760,6 +781,7 @@ export async function* runValidation({
                     sourcePath,
                     message: v.message,
                     fixable: true,
+                    ...(v.keyError ? { keyError: true } : {}),
                   };
                 }
 
@@ -767,9 +789,12 @@ export async function* runValidation({
                   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),
+                    ...(e.keyError ? { keyError: true } : {}),
                   };
                 }
               }

package/src/utils/evalValConfigFile.ts

@@ -11,11 +11,19 @@ const ValConfigSchema = z.object({
   root: z.string().optional(),
   files: z
     .object({
-      directory: z
-        .string()
-        .refine((val): val is `/public/val` => val.startsWith("/public/val"), {
-          message: "files.directory must start with '/public/val'",
-        }),
+      directory: z.string().refine(
+        (val): val is `/public` | `/public/${string}` =>
+          (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(),