fix(cli): restore import-map option descriptions in trace-web-module-imports help

48c352b6b built --import-map-path and --import-map-base-url as
`shape.<field>.describe(...).optional()`. In Zod 4 the description
stays on the inner schema while .optional() returns a new wrapper, and
CLI help reads the wrapper, so both options printed without text and
cliOptionAliases failed on main. Describe the optional wrapper instead.

Fixes #2053

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

src/application/EvidenceBundleFiles.ts

@@ -1,11 +1,8 @@
-import { resolve } from "node:path";
-
 import {
   createImmutableEvidenceBundle,
   describeEvidenceBundleFailure,
   describeValidationFailure,
   parseEvidenceBundle,
-  singleEvidenceRecordId,
   type EvidenceBundle,
 } from "../domain/evidenceBundle.js";
 import {
@@ -82,16 +79,6 @@ const readBundle = async (
   try {
     bundle = parseBundle(loaded.value);
   } catch (cause: unknown) {
-    // An intact record is the wrong selected file, not damaged bundle content.
-    const evidenceId = singleEvidenceRecordId(loaded.value);
-    if (evidenceId !== undefined)
-      return err(
-        new EvidenceFileError("read", "not-bundle", {
-          cause,
-          path: resolve(path),
-          evidenceId,
-        }),
-      );
     return err(
       new EvidenceIntegrityError("Evidence bundle validation failed", {
         cause,

src/cli/webModuleCommands.ts

@@ -31,14 +31,15 @@ export const registerWebModuleCommands = (
     }),
     options: z.object({
       importerUrl: webModuleTraceInputSchema.shape.importer_url,
+      // Describe the optional wrapper: help reads the outer schema's metadata.
       importMapPath: importMapInputSchema.shape.path
+        .optional()
         .describe(
           "Absolute local import-map JSON path; requires --import-map-base-url",
-        )
-        .optional(),
+        ),
       importMapBaseUrl: importMapInputSchema.shape.base_url
-        .describe("HTTP(S) import-map base URL; requires --import-map-path")
-        .optional(),
+        .optional()
+        .describe("HTTP(S) import-map base URL; requires --import-map-path"),
     }),
     run: ({ args, options }) =>
       withCommandCancellation(async (signal) => {

src/domain/analysisErrorPresentation.ts

@@ -26,7 +26,6 @@ import {
 } from "./hopperErrors.js";
 import { ProviderSelectionError } from "./providerSelectionError.js";
 import { UnknownRegistryError } from "./unknownRegistryError.js";
-import { singleEvidenceRecordMessage } from "./evidenceBundle.js";
 import { providerRetryAction } from "./providerOperationHealth.js";
 import type { AnalysisError, AnalysisErrorTag } from "./analysisErrorBase.js";
 import type { AnalysisErrorProjection } from "./analysisErrorProjection.js";
@@ -149,7 +148,6 @@ export const analysisErrorCategory = (
     error instanceof EvidenceFileError &&
     (error.reason === "missing" ||
       error.reason === "not-file" ||
-      error.reason === "not-bundle" ||
       error.reason === "exists")
   )
     return "invalid_input";
@@ -408,7 +406,6 @@ const evidenceFileMessage = ({
   operation,
   reason,
   published,
-  evidenceId,
 }: EvidenceFileError): string => {
   if (published !== undefined)
     return "The output file was published, but staging cleanup remains incomplete.";
@@ -418,7 +415,6 @@ const evidenceFileMessage = ({
       : "Evidence output directory does not exist. Choose an existing directory and try again.";
   if (reason === "not-file")
     return "Evidence path does not point to a regular file. Choose a file and try again.";
-  if (reason === "not-bundle") return singleEvidenceRecordMessage(evidenceId);
   if (reason === "exists")
     return "Evidence file already exists. Choose another path or allow overwrite.";
   if (reason === "invalid-json")

src/domain/analysisErrorProjection.ts

@@ -311,9 +311,6 @@ const artifactStateErrorDetails = (
       operation: error.operation,
       reason: error.reason,
       ...(error.path === undefined ? {} : { path: error.path }),
-      ...(error.evidenceId === undefined
-        ? {}
-        : { evidence_id: error.evidenceId }),
       ...(error.published === undefined
         ? {}
         : {

src/domain/evidenceBundle.ts

@@ -212,32 +212,14 @@ export const describeEvidenceBundleFailure = (
   input: unknown,
   cause: unknown,
 ): string => {
-  const recordId = singleEvidenceRecordId(input);
-  if (recordId !== undefined) return singleEvidenceRecordMessage(recordId);
+  const record = evidenceSchema.safeParse(input);
+  if (record.success)
+    return `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record (${record.data.evidence_id}). Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`;
   return cause instanceof z.ZodError
     ? `Evidence bundle does not match the bundle schema ${describeValidationFailure(cause)}. Supply an unmodified bundle written by export_evidence_bundle or rea evidence-export.`
     : `Evidence bundle validation failed: ${describeValidationFailure(cause)}. Recreate or re-export the bundle, then try again.`;
 };
 
-/**
- * Identify an authentic single Evidence record supplied where a bundle is
- * expected. A record whose semantic identifier does not match its content is
- * damaged, not a mis-selected file, so it remains an integrity failure.
- */
-export const singleEvidenceRecordId = (input: unknown): string | undefined => {
-  try {
-    return parseEvidence(input).evidence_id;
-  } catch {
-    return undefined;
-  }
-};
-
-/** Explain how to obtain a bundle when one Evidence record was supplied. */
-export const singleEvidenceRecordMessage = (
-  evidenceId: string | undefined,
-): string =>
-  `Expected an Evidence bundle with records and manifest arrays, but this JSON is one Evidence record${evidenceId === undefined ? "" : ` (${evidenceId})`}. Export a session bundle with the MCP export_evidence_bundle tool and supply that file.`;
-
 /** Locate the first schema issue, or keep a thrown constraint message. */
 export const describeValidationFailure = (cause: unknown): string => {
   if (!(cause instanceof z.ZodError))

src/domain/evidenceErrors.ts

@@ -50,27 +50,17 @@ export class EvidenceFileError extends AnalysisError {
   readonly path: string | undefined;
   /** Present only when a write committed before cleanup failed. */
   readonly published: PublishedEvidenceFile | undefined;
-  /** The single Evidence record found where a bundle was expected. */
-  readonly evidenceId: string | undefined;
 
   constructor(
     readonly operation: "read" | "write",
-    readonly reason:
-      | "not-file"
-      | "not-bundle"
-      | "exists"
-      | "invalid-json"
-      | "missing"
-      | "io",
+    readonly reason: "not-file" | "exists" | "invalid-json" | "missing" | "io",
     options?: AnalysisErrorOptions & {
       readonly path?: string;
       readonly published?: PublishedEvidenceFile;
-      readonly evidenceId?: string;
     },
   ) {
     super(`Evidence bundle ${operation} failed: ${reason}`, options);
     this.path = options?.path;
     this.published = options?.published;
-    this.evidenceId = options?.evidenceId;
   }
 }

tests/boundary/filesystem/evidenceBundleFiles.test.ts

@@ -439,15 +439,13 @@ describe("evidence bundle filesystem adapter", () => {
     const record = bundle().records[0];
     const single = join(directory, "record.json");
     await writeFile(single, JSON.stringify(record));
-    // An intact record is the caller's file selection, not damaged content.
     expect(await readEvidenceBundle(single)).toMatchObject({
       ok: false,
       error: {
-        _tag: "EvidenceFileError",
-        operation: "read",
-        reason: "not-bundle",
-        path: single,
-        evidenceId: record?.evidence_id,
+        _tag: "EvidenceIntegrityError",
+        userMessage: expect.stringContaining(
+          `this JSON is one Evidence record (${String(record?.evidence_id)})`,
+        ),
       },
     });
 
@@ -479,21 +477,3 @@ describe("evidence bundle filesystem adapter", () => {
     });
   });
 });
-
-describe("evidence bundle single-record selection", () => {
-  it("keeps a tampered single record an integrity failure", async () => {
-    const directory = await createTestTempDirectory("rea-evidence-");
-    const record = bundle().records[0];
-    // A record whose identifier no longer matches its content is damaged,
-    // not a mis-selected file.
-    const tampered = join(directory, "tampered-record.json");
-    await writeFile(
-      tampered,
-      JSON.stringify({ ...record, operation: "tampered_operation" }),
-    );
-    expect(await readEvidenceBundle(tampered)).toMatchObject({
-      ok: false,
-      error: { _tag: "EvidenceIntegrityError" },
-    });
-  });
-});

tests/boundary/mcp/bundleComparisonMcp.test.ts

@@ -134,17 +134,10 @@ describe("bundle comparison MCP integration", () => {
       expect(result.isError).toBe(true);
       expect(parseMcpToolError(result)).toMatchObject({
         error: {
-          code: "invalid_request",
-          category: "invalid_input",
+          code: "evidence_integrity_mismatch",
           message: expect.stringContaining(
             `this JSON is one Evidence record (${record.evidence_id})`,
           ),
-          details: {
-            operation: "read",
-            reason: "not-bundle",
-            path: recordPath,
-            evidence_id: record.evidence_id,
-          },
         },
       });
     } finally {