toolcraft 0.0.17 → 0.0.18

package/dist/cli.js

@@ -4,12 +4,27 @@ import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Opti
 import { cancel, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "@poe-code/design-system";
 import { ApprovalDeclinedError, UserError, assertCommandRequirements, getCommandSourcePath, resolveCommandSecrets } from "./index.js";
 import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
+import { writeErrorReport } from "./error-report.js";
 import { invokeWithHumanInLoop } from "./human-in-loop/index.js";
 import { resolveMcpProxies } from "./mcp-proxy.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
 import { findEntrypointPackageMetadata } from "./package-metadata.js";
 import { renderResult } from "./renderer.js";
-const RESERVED_SERVICE_NAMES = new Set(["params", "secrets", "fetch", "fs", "env", "progress"]);
+import { renderSourceSnippet } from "./source-snippet.js";
+import { enableSourceMaps, formatDebugStack } from "./stack-trim.js";
+import { suggest } from "./suggest.js";
+import { throwValidationErrors } from "./validation-errors.js";
+const RESERVED_SERVICE_NAMES = new Set([
+    "params",
+    "secrets",
+    "fetch",
+    "fs",
+    "env",
+    "progress",
+    "runtimeOptions",
+    "root"
+]);
+const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, progress, runtimeOptions, root.";
 const NULL_OPTION_VALUE = Symbol("toolcraft.cli.null");
 function inferProgramName(argv) {
     const entrypoint = argv[1];
@@ -368,12 +383,14 @@ function parseBooleanText(value, label) {
     if (normalized === "false") {
         return false;
     }
-    throw new InvalidArgumentError(`Invalid value for "${label}". Expected true or false.`);
+    throw new InvalidArgumentError(`Invalid value for "${label}". Expected true or false, got ${describeReceived(value)}.`);
 }
 function parseEnumValue(value, values, label) {
     const match = values.find((candidate) => String(candidate) === value);
     if (match === undefined) {
-        throw new InvalidArgumentError(`Invalid value for "${label}". Expected one of: ${values.map((candidate) => String(candidate)).join(", ")}.`);
+        const suggestions = suggest(value, values.map((candidate) => String(candidate)));
+        const suggestionLine = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?\n` : " ";
+        throw new InvalidArgumentError(`Invalid value for "${label}".${suggestionLine}Expected one of: ${values.map((candidate) => String(candidate)).join(", ")}, got ${describeReceived(value)}.`);
     }
     return match;
 }
@@ -393,9 +410,114 @@ function parseJsonText(value, label) {
     try {
         return JSON.parse(value);
     }
-    catch {
-        throw new InvalidArgumentError(`Invalid value for "${label}". Expected valid JSON.`);
+    catch (error) {
+        throw new InvalidArgumentError(`Invalid value for "${label}". Expected valid JSON, got ${describeReceived(value)} (parser: ${getErrorMessage(error)}).`);
+    }
+}
+function describeReceived(value) {
+    if (value === null)
+        return "null";
+    if (value === undefined)
+        return "missing";
+    if (Array.isArray(value))
+        return `array(${value.length})`;
+    if (typeof value === "object")
+        return "object";
+    if (typeof value === "string") {
+        const s = value.length > 40 ? `${value.slice(0, 40)}…` : value;
+        return `${JSON.stringify(s)}`;
+    }
+    return JSON.stringify(value);
+}
+function getErrorMessage(error) {
+    return error instanceof Error ? error.message : String(error);
+}
+function formatJsonParseUserErrorMessage(label, filePath, source, error, options) {
+    const location = getJsonParseErrorLocation(error, source);
+    const message = getErrorMessage(error);
+    const positionText = location === null ? "" : ` at line ${location.line} column ${location.column}`;
+    const formattedPath = options.quotePath ? `"${filePath}"` : filePath;
+    const snippet = location === null
+        ? ""
+        : `\n${renderSourceSnippet({
+            source,
+            line: location.line,
+            column: location.column,
+            filePath
+        })}`;
+    return `${label} ${formattedPath} is not valid JSON: ${message}${positionText}.${snippet}`;
+}
+function getJsonParseErrorLocation(error, source) {
+    const causeLocation = getJsonParseCauseLocation(error);
+    if (causeLocation !== null) {
+        return causeLocation;
+    }
+    const directPosition = getNumericProperty(error, "position");
+    if (directPosition !== null) {
+        return getSourceOffsetLocation(source, directPosition);
+    }
+    const messagePosition = getJsonParseMessagePosition(getErrorMessage(error));
+    if (messagePosition !== null) {
+        return getSourceOffsetLocation(source, messagePosition);
+    }
+    return null;
+}
+function getJsonParseCauseLocation(error) {
+    if (typeof error !== "object" || error === null || !("cause" in error)) {
+        return null;
+    }
+    const cause = error.cause;
+    const line = getNumericProperty(cause, "line");
+    const column = getNumericProperty(cause, "column") ?? getNumericProperty(cause, "col");
+    if (line === null || column === null) {
+        return null;
+    }
+    return { line, column };
+}
+function getNumericProperty(value, key) {
+    if (typeof value !== "object" || value === null || !(key in value)) {
+        return null;
+    }
+    const propertyValue = value[key];
+    return typeof propertyValue === "number" && Number.isFinite(propertyValue)
+        ? propertyValue
+        : null;
+}
+function getJsonParseMessagePosition(message) {
+    const marker = " at position ";
+    const markerIndex = message.indexOf(marker);
+    if (markerIndex === -1) {
+        return null;
     }
+    const startIndex = markerIndex + marker.length;
+    let endIndex = startIndex;
+    while (endIndex < message.length && isAsciiDigit(message[endIndex] ?? "")) {
+        endIndex += 1;
+    }
+    if (endIndex === startIndex) {
+        return null;
+    }
+    return Number.parseInt(message.slice(startIndex, endIndex), 10);
+}
+function getSourceOffsetLocation(source, offset) {
+    let line = 1;
+    let column = 1;
+    const boundedOffset = Math.max(0, Math.floor(offset));
+    for (let index = 0; index < boundedOffset && index < source.length; index += 1) {
+        if (source[index] === "\n") {
+            line += 1;
+            column = 1;
+            continue;
+        }
+        column += 1;
+    }
+    return { line, column };
+}
+function isAsciiDigit(value) {
+    return value >= "0" && value <= "9";
+}
+function formatAvailableList(values) {
+    return `Available: ${[...values].sort().join(", ")}.`;
 }
 function normalizeCommanderOptionValue(value) {
     return value === NULL_OPTION_VALUE ? null : value;
@@ -410,7 +532,7 @@ function parseScalarValue(value, schema, label) {
         case "number": {
             const parsed = Number(value);
             if (!isValidNumberSchemaValue(parsed, schema)) {
-                throw new InvalidArgumentError(`Invalid value for "${label}". Expected ${getExpectedNumberDescription(schema)}.`);
+                throw new InvalidArgumentError(`Invalid value for "${label}". Expected ${getExpectedNumberDescription(schema)}, got ${describeReceived(value)}.`);
             }
             return parsed;
         }
@@ -419,7 +541,7 @@ function parseScalarValue(value, schema, label) {
         case "enum":
             return parseEnumValue(value, schema.values, label);
     }
-    throw new UserError("Unsupported CLI schema kind.");
+    throw new UserError(`Unsupported CLI schema kind. ${formatAvailableList(["boolean", "enum", "number", "string"])}`);
 }
 function splitArrayInput(value) {
     const items = [];
@@ -455,7 +577,6 @@ function parseArrayValue(value, schema, label) {
 function createOption(field, globalLongOptionFlags) {
     const flags = formatOptionFlags(field, globalLongOptionFlags);
     const collidesWithGlobalFlag = globalLongOptionFlags.has(field.optionFlag);
-    const commanderValue = (value) => (value === null ? NULL_OPTION_VALUE : value);
     if (field.schema.kind === "boolean") {
         if (collidesWithGlobalFlag) {
             return [createCommanderOption(flags, field.description, field)];
@@ -463,9 +584,7 @@ function createOption(field, globalLongOptionFlags) {
         const mainOption = createCommanderOption(`${flags} [value]`, field.description, field);
         mainOption.preset(true);
         // Commander v14 passes the preset value through argParser too, so guard with typeof check
-        mainOption.argParser((value) => typeof value === "boolean"
-            ? value
-            : commanderValue(parseBooleanText(value, field.displayPath)));
+        mainOption.argParser((value) => (typeof value === "boolean" ? value : value));
         return [
             mainOption,
             createCommanderOption(`--no-${field.optionFlag.slice(2)}`, field.description, field)
@@ -473,29 +592,16 @@ function createOption(field, globalLongOptionFlags) {
     }
     if (field.schema.kind === "array") {
         return [
-            createCommanderOption(`${flags} <value...>`, field.description, field).argParser((value, previous = []) => {
-                const parsed = parseArrayValue(value, field.schema, field.displayPath);
-                if (parsed === null) {
-                    return NULL_OPTION_VALUE;
-                }
-                return [...(previous ?? []), ...parsed];
-            })
+            createCommanderOption(`${flags} <value...>`, field.description, field).argParser((value, previous = []) => [...previous, value])
         ];
     }
     if (field.schema.kind === "json") {
-        return [
-            createCommanderOption(`${flags} <json>`, field.description, field).argParser((value) => commanderValue(parseJsonText(value, field.displayPath)))
-        ];
+        return [createCommanderOption(`${flags} <json>`, field.description, field)];
     }
     const option = createCommanderOption(`${flags} <value>`, field.description, field);
-    if (field.schema.kind === "enum" &&
-        field.schema.values.every((value) => typeof value === "string")) {
-        option.choices([...field.schema.values]);
-    }
-    option.argParser((value) => commanderValue(parseScalarValue(value, field.schema, field.displayPath)));
     return [option];
 }
-const ALWAYS_GLOBAL_LONG_OPTION_FLAGS = ["--yes", "--output", "--debug"];
+const ALWAYS_GLOBAL_LONG_OPTION_FLAGS = ["--yes", "--output", "--debug", "--verbose"];
 function getGlobalLongOptionFlags(presetsEnabled) {
     return new Set(presetsEnabled
         ? ["--preset", ...ALWAYS_GLOBAL_LONG_OPTION_FLAGS]
@@ -850,9 +956,6 @@ function formatGlobalOptionRows(ctx) {
     }, {
         flags: "--output <format>",
         description: "Output format: rich, md, json."
-    }, {
-        flags: "--debug",
-        description: "Print stack traces for unexpected errors."
     });
     if (ctx.showVersion) {
         rows.push({
@@ -871,6 +974,9 @@ function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlag
                 if (field.global !== true) {
                     continue;
                 }
+                if (globalLongOptionFlags.has(field.optionFlag)) {
+                    continue;
+                }
                 const dedupeKey = `${field.optionFlag}|${field.shortFlag ?? ""}`;
                 if (seen.has(dedupeKey)) {
                     continue;
@@ -1083,9 +1189,24 @@ function addGlobalOptions(command, presetsEnabled) {
         if (value === "markdown") {
             return "md";
         }
-        throw new InvalidArgumentError('Invalid value for "--output". Expected one of: rich, md, markdown, json.');
+        throw new InvalidArgumentError(formatInvalidEnumMessage("--output", value, ["rich", "md", "markdown", "json"], {
+            candidates: ["rich", "markdown", "json"],
+            threshold: 3
+        }));
     })
-        .option("--debug", "Print stack traces for unexpected errors.");
+        .addOption(new Option("--debug [mode]", "Print stack traces for unexpected errors.")
+        .preset("trim")
+        .argParser(parseDebugStackMode))
+        .option("--verbose", "Print detailed runtime diagnostics.");
+}
+function parseDebugStackMode(value) {
+    if (value === true || value === "trim") {
+        return "trim";
+    }
+    if (value === "raw") {
+        return "raw";
+    }
+    throw new InvalidArgumentError(formatInvalidEnumMessage("--debug", String(value), ["raw"], { candidates: ["raw"] }));
 }
 function setNestedValue(target, path, value) {
     let cursor = target;
@@ -1283,7 +1404,7 @@ function validatePresetScalarValue(value, schema, fieldPath, presetPath) {
             break;
         }
     }
-    throw new UserError(`Preset file "${presetPath}" has an invalid value for "${fieldPath}". Expected ${describeExpectedPresetValue(schema)}.`);
+    throw new UserError(`Preset file "${presetPath}" has an invalid value for "${fieldPath}". Expected ${describeExpectedPresetValue(schema)}, got ${describeReceived(value)}.`);
 }
 function validatePresetFieldValue(value, field, presetPath) {
     if (field.schema.kind === "json") {
@@ -1297,7 +1418,7 @@ function validatePresetFieldValue(value, field, presetPath) {
         throw new UserError(`Array parameter "${field.displayPath}" must use scalar items.`);
     }
     if (!Array.isArray(value)) {
-        throw new UserError(`Preset file "${presetPath}" has an invalid value for "${field.displayPath}". Expected an array.`);
+        throw new UserError(`Preset file "${presetPath}" has an invalid value for "${field.displayPath}". Expected an array, got ${describeReceived(value)}.`);
     }
     return value.map((item) => validatePresetScalarValue(item, itemSchema, field.displayPath, presetPath));
 }
@@ -1319,8 +1440,10 @@ async function loadPresetValues(fields, presetPath) {
     try {
         parsedPreset = JSON.parse(rawPreset);
     }
-    catch {
-        throw new UserError(`Preset file "${presetPath}" is not valid JSON.`);
+    catch (error) {
+        throw new UserError(formatJsonParseUserErrorMessage("Preset file", presetPath, rawPreset, error, {
+            quotePath: true
+        }), { cause: error });
     }
     if (!isPlainObject(parsedPreset)) {
         throw new UserError(`Preset file "${presetPath}" must contain a JSON object.`);
@@ -1340,7 +1463,7 @@ async function loadPresetValues(fields, presetPath) {
                 throw new UserError(`Preset file "${presetPath}" contains unknown parameter "${displayPath}".`);
             }
             if (!isPlainObject(value)) {
-                throw new UserError(`Preset file "${presetPath}" has an invalid value for "${displayPath}". Expected an object.`);
+                throw new UserError(`Preset file "${presetPath}" has an invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`);
             }
             visitObject(value, nextPath);
         }
@@ -1548,7 +1671,7 @@ function resolveFixturePath(commandPath) {
     const parsed = path.parse(commandPath);
     return path.join(parsed.dir, `${parsed.name}.fixture.json`);
 }
-function selectFixtureScenario(scenarios, selector) {
+function selectFixtureScenario(scenarios, selector, fixturePath) {
     if (isNumericFixtureSelector(selector)) {
         const index = Number(selector) - 1;
         const scenario = scenarios[index];
@@ -1559,7 +1682,13 @@ function selectFixtureScenario(scenarios, selector) {
     }
     const scenario = scenarios.find((entry) => entry.name === selector);
     if (scenario === undefined) {
-        throw new UserError(`Fixture scenario "${selector}" was not found.`);
+        const names = scenarios
+            .map((entry) => entry.name)
+            .filter((name) => typeof name === "string" && name.length > 0);
+        const available = names.length === 0
+            ? `No fixtures are declared in ${fixturePath}.`
+            : formatAvailableList(names);
+        throw new UserError(`Fixture scenario "${selector}" was not found. ${available}`);
     }
     return scenario;
 }
@@ -1582,13 +1711,15 @@ async function loadFixtureScenario(command, selector) {
     try {
         parsed = JSON.parse(rawFixture);
     }
-    catch {
-        throw new UserError(`Fixture file ${fixturePath} is not valid JSON.`);
+    catch (error) {
+        throw new UserError(formatJsonParseUserErrorMessage("Fixture file", fixturePath, rawFixture, error, {
+            quotePath: false
+        }), { cause: error });
     }
     if (!Array.isArray(parsed)) {
         throw new UserError(`Fixture file ${fixturePath} must contain a JSON array of scenarios.`);
     }
-    return selectFixtureScenario(parsed, selector);
+    return selectFixtureScenario(parsed, selector, fixturePath);
 }
 function resolveFixtureSecrets(command) {
     return Object.fromEntries(Object.keys(command.secrets).map((name) => [name, "fixture-secret"]));
@@ -1662,7 +1793,7 @@ function renderApprovalDeclined(error) {
 function validateServices(services) {
     for (const name of Object.keys(services)) {
         if (RESERVED_SERVICE_NAMES.has(name)) {
-            throw new Error(`Service name "${name}" is reserved. Choose a different name.`);
+            throw new Error(`Service name "${name}" is reserved. Choose a different name. ${RESERVED_SERVICE_NAMES_MESSAGE}`);
         }
     }
 }
@@ -1683,6 +1814,38 @@ function parseFieldInputValue(value, schema, label) {
     }
     return parseScalarValue(value, schema, label);
 }
+function parseOptionFieldValue(field, value, errors) {
+    try {
+        if (value === null) {
+            return { ok: true, value };
+        }
+        if (field.schema.kind === "array" && Array.isArray(value)) {
+            const parsedValues = [];
+            for (const item of value) {
+                const parsed = parseArrayValue(String(item), field.schema, field.displayPath);
+                if (parsed === null) {
+                    return { ok: true, value: null };
+                }
+                parsedValues.push(...parsed);
+            }
+            return { ok: true, value: parsedValues };
+        }
+        if (typeof value !== "string") {
+            return { ok: true, value };
+        }
+        return { ok: true, value: parseFieldInputValue(value, field.schema, field.displayPath) };
+    }
+    catch (error) {
+        if (error instanceof UserError || error instanceof InvalidArgumentError) {
+            errors.push({
+                path: field.displayPath,
+                message: error.message
+            });
+            return { ok: false };
+        }
+        throw error;
+    }
+}
 function consumeFieldValue(args, index, schema, label, inlineValue) {
     if (schema.kind === "boolean") {
         if (inlineValue !== undefined) {
@@ -1746,8 +1909,9 @@ function consumeFieldValue(args, index, schema, label, inlineValue) {
         value: parseFieldInputValue(next, schema, label)
     };
 }
-function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displayPath = []) {
+function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displayPath = [], displayPathPrefix = "") {
     const unwrappedSchema = unwrapOptional(schema);
+    const kind = formatCliSchemaKind(unwrappedSchema.kind);
     if (rawSegments.length === 0) {
         if (unwrappedSchema.kind === "json" ||
             unwrappedSchema.kind === "array" ||
@@ -1761,7 +1925,7 @@ function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displa
                 schema: unwrappedSchema
             };
         }
-        throw new UserError(`Unsupported dynamic CLI schema kind "${unwrappedSchema.kind}".`);
+        throw new UserError(formatUnsupportedDynamicSchemaMessage(kind, qualifyDisplayPath(displayPathPrefix, toDisplayPath(displayPath))));
     }
     switch (unwrappedSchema.kind) {
         case "object": {
@@ -1770,30 +1934,32 @@ function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displa
                 if (formatSegment(key, casing) !== head) {
                     continue;
                 }
-                return resolveDynamicLeaf(childSchema, rest, casing, [...outputPath, key], [...displayPath, key]);
+                return resolveDynamicLeaf(childSchema, rest, casing, [...outputPath, key], [...displayPath, key], displayPathPrefix);
             }
-            throw new UserError(`Unknown parameter "${[...displayPath, head].join(".")}".`);
+            throw new UserError(`Unknown parameter "${qualifyDisplayPath(displayPathPrefix, [...displayPath, head].join("."))}". ${formatAvailableList(Object.keys(unwrappedSchema.shape).map((key) => qualifyDisplayPath(displayPathPrefix, toDisplayPath([...displayPath, formatSegment(key, casing)]))))}`);
         }
         case "record": {
             const [head, ...rest] = rawSegments;
-            return resolveDynamicLeaf(unwrappedSchema.value, rest, casing, [...outputPath, head ?? ""], [...displayPath, head ?? ""]);
+            return resolveDynamicLeaf(unwrappedSchema.value, rest, casing, [...outputPath, head ?? ""], [...displayPath, head ?? ""], displayPathPrefix);
         }
         case "array": {
             const itemSchema = unwrapOptional(unwrappedSchema.item);
             if (itemSchema.kind !== "object") {
-                throw new UserError(`Array parameter "${toDisplayPath(displayPath)}" must use object items.`);
+                throw new UserError(`Array parameter "${qualifyDisplayPath(displayPathPrefix, toDisplayPath(displayPath))}" must use object items.`);
             }
             const [head, ...rest] = rawSegments;
             if (head === undefined || !isNumericFixtureSelector(head)) {
-                throw new UserError(`Array parameter "${toDisplayPath(displayPath)}" must use numeric indices.`);
+                throw new UserError(`Array parameter "${qualifyDisplayPath(displayPathPrefix, toDisplayPath(displayPath))}" must use numeric indices.`);
             }
-            return resolveDynamicLeaf(itemSchema, rest, casing, [...outputPath, head], [...displayPath, head]);
+            return resolveDynamicLeaf(itemSchema, rest, casing, [...outputPath, head], [...displayPath, head], displayPathPrefix);
         }
         default:
-            throw new UserError(`Unknown parameter "${[...displayPath, ...rawSegments].join(".")}".`);
+            throw new UserError(`Unknown parameter "${qualifyDisplayPath(displayPathPrefix, [...displayPath, ...rawSegments].join("."))}". ${formatAvailableList(displayPath.length === 0
+                ? []
+                : [qualifyDisplayPath(displayPathPrefix, toDisplayPath(displayPath))])}`);
     }
 }
-function finalizeDynamicValue(schema, value, displayPath) {
+function finalizeDynamicValue(schema, value, displayPath, errors) {
     const unwrappedSchema = unwrapOptional(schema);
     if (value === undefined) {
         return undefined;
@@ -1814,23 +1980,39 @@ function finalizeDynamicValue(schema, value, displayPath) {
                 return value;
             }
             if (!isPlainObject(value)) {
-                throw new UserError(`Invalid value for "${displayPath}". Expected indexed object entries.`);
+                errors.push({
+                    path: displayPath,
+                    message: `Invalid value for "${displayPath}". Expected indexed object entries, got ${describeReceived(value)}.`
+                });
+                return value;
             }
             const entries = Object.entries(value);
             const indices = entries.map(([key]) => Number(key)).sort((left, right) => left - right);
             if (indices.some((index) => !Number.isInteger(index) || index < 0)) {
-                throw new UserError(`Array parameter "${displayPath}" must use numeric indices.`);
+                errors.push({
+                    path: displayPath,
+                    message: `Array parameter "${displayPath}" must use numeric indices.`
+                });
+                return value;
             }
             for (let index = 0; index < indices.length; index += 1) {
                 if (indices[index] !== index) {
-                    throw new UserError(`Array parameter "${displayPath}" must use contiguous indices starting at 0.`);
+                    errors.push({
+                        path: displayPath,
+                        message: `Array parameter "${displayPath}" must use contiguous indices starting at 0.`
+                    });
+                    return value;
                 }
             }
-            return indices.map((index) => finalizeDynamicValue(unwrappedSchema.item, value[String(index)], `${displayPath}.${index}`));
+            return indices.map((index) => finalizeDynamicValue(unwrappedSchema.item, value[String(index)], `${displayPath}.${index}`, errors));
         }
         case "object": {
             if (!isPlainObject(value)) {
-                throw new UserError(`Invalid value for "${displayPath}". Expected an object.`);
+                errors.push({
+                    path: displayPath,
+                    message: `Invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`
+                });
+                return value;
             }
             const result = {};
             for (const [key, rawChildSchema] of Object.entries(unwrappedSchema.shape)) {
@@ -1845,26 +2027,53 @@ function finalizeDynamicValue(schema, value, displayPath) {
                     if (rawChildSchema.kind === "optional") {
                         continue;
                     }
-                    throw new UserError(`Missing required parameter "${childDisplayPath}".`);
+                    errors.push({
+                        path: childDisplayPath,
+                        message: `Missing required parameter "${childDisplayPath}".`
+                    });
+                    continue;
                 }
-                result[key] = finalizeDynamicValue(rawChildSchema, childValue, childDisplayPath);
+                result[key] = finalizeDynamicValue(rawChildSchema, childValue, childDisplayPath, errors);
             }
             return result;
         }
         case "record": {
             if (!isPlainObject(value)) {
-                throw new UserError(`Invalid value for "${displayPath}". Expected an object.`);
+                errors.push({
+                    path: displayPath,
+                    message: `Invalid value for "${displayPath}". Expected an object, got ${describeReceived(value)}.`
+                });
+                return value;
             }
             return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [
                 key,
-                finalizeDynamicValue(unwrappedSchema.value, entryValue, displayPath.length === 0 ? key : `${displayPath}.${key}`)
+                finalizeDynamicValue(unwrappedSchema.value, entryValue, displayPath.length === 0 ? key : `${displayPath}.${key}`, errors)
             ]));
         }
         default:
-            throw new UserError(`Unsupported dynamic CLI schema kind "${unwrappedSchema.kind}".`);
+            errors.push({
+                path: displayPath,
+                message: formatUnsupportedDynamicSchemaMessage(formatCliSchemaKind(unwrappedSchema.kind), displayPath)
+            });
+            return value;
+    }
+}
+function formatCliSchemaKind(kind) {
+    return kind === "oneOf" ? "oneof" : kind;
+}
+function formatUnsupportedDynamicSchemaMessage(kind, displayPath) {
+    return `Unsupported parameter type "${kind}" for "${displayPath}". Supported types: string, number, integer, boolean, array, object, enum, oneof.`;
+}
+function qualifyDisplayPath(prefix, displayPath) {
+    if (prefix.length === 0) {
+        return displayPath;
+    }
+    if (displayPath.length === 0) {
+        return prefix;
     }
+    return `${prefix}.${displayPath}`;
 }
-function parseDynamicValues(dynamicFields, rawArgv, casing) {
+function parseDynamicValues(dynamicFields, rawArgv, casing, errors) {
     const rawValues = new Map();
     const providedFieldIds = new Set();
     const sortedFields = [...dynamicFields].sort((left, right) => right.optionPath.length - left.optionPath.length);
@@ -1885,11 +2094,11 @@ function parseDynamicValues(dynamicFields, rawArgv, casing) {
                 optionPath.every((segment, segmentIndex) => flagPath[segmentIndex] === segment));
         });
         if (match === undefined) {
-            throw new UserError(`Unknown parameter "${flagName}".`);
+            throw new UserError(`Unknown parameter "${flagName}". ${formatAvailableList(dynamicFields.map((field) => field.optionPathDisplay))}`);
         }
         const optionPath = match.optionPath.map((segment) => formatSegment(segment, casing));
         const remainder = flagPath.slice(optionPath.length);
-        const leaf = resolveDynamicLeaf(match.schema, remainder, casing);
+        const leaf = resolveDynamicLeaf(match.schema, remainder, casing, [], [], match.displayPath);
         const rawStore = rawValues.get(match.id) ?? {};
         const label = `${match.displayPath}.${leaf.displayPath}`.replace(/^\./u, "");
         const parsed = negated && leaf.schema.kind === "boolean"
@@ -1909,13 +2118,23 @@ function parseDynamicValues(dynamicFields, rawArgv, casing) {
             .filter((field) => rawValues.has(field.id))
             .map((field) => [
             field.id,
-            finalizeDynamicValue(field.schema.kind === "record" ? field.schema : field.schema, rawValues.get(field.id), field.displayPath)
+            finalizeDynamicValue(field.schema.kind === "record" ? field.schema : field.schema, rawValues.get(field.id), field.displayPath, errors)
         ]))
     };
 }
-async function enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, providedDynamicFieldIds, providedFieldIds, shouldPrompt) {
+async function enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, providedDynamicFieldIds, providedFieldIds, shouldPrompt, errors) {
     const fieldById = new Map(fields.map((field) => [field.id, field]));
     const dynamicFieldById = new Map(dynamicFields.map((field) => [field.id, field]));
+    const getAvailableBranchParameters = (branch) => [
+        ...branch.fieldIds
+            .map((fieldId) => fieldById.get(fieldId))
+            .filter((field) => field !== undefined && field.synthetic !== true)
+            .map((field) => field.displayPath),
+        ...branch.dynamicFieldIds
+            .map((fieldId) => dynamicFieldById.get(fieldId))
+            .filter((field) => field !== undefined)
+            .map((field) => field.optionPathDisplay)
+    ];
     for (const variant of variants) {
         let selectedBranchId = resolvedFieldValues.get(variant.controlFieldId);
         if (selectedBranchId === undefined && shouldPrompt) {
@@ -1932,12 +2151,21 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
             if (variant.optional) {
                 continue;
             }
-            throw new UserError(`Missing required parameter "${variant.controlDisplayPath}".`);
+            errors.push({
+                path: variant.controlDisplayPath,
+                message: `Missing required parameter "${variant.controlDisplayPath}".`
+            });
+            continue;
         }
         const selectedBranch = variant.branches.find((branch) => branch.branchId === selectedBranchId);
         if (selectedBranch === undefined) {
-            throw new UserError(`Invalid value for "${variant.controlDisplayPath}". Expected one of: ${variant.branches.map((branch) => branch.branchId).join(", ")}.`);
+            errors.push({
+                path: variant.controlDisplayPath,
+                message: `Invalid value for "${variant.controlDisplayPath}". Expected one of: ${variant.branches.map((branch) => branch.branchId).join(", ")}, got ${describeReceived(selectedBranchId)}.`
+            });
+            continue;
         }
+        let hasInvalidBranchParameter = false;
         for (const branch of variant.branches) {
             if (branch.branchId === selectedBranch.branchId) {
                 continue;
@@ -1946,17 +2174,28 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
             if (invalidFieldId !== undefined) {
                 const field = fieldById.get(invalidFieldId);
                 if (field !== undefined) {
-                    throw new UserError(`Parameter "${field.displayPath}" is not valid when "${variant.controlDisplayPath}" is "${selectedBranch.branchId}".`);
+                    errors.push({
+                        path: field.displayPath,
+                        message: `Unknown parameter "${field.displayPath}" for ${variant.controlDisplayPath}="${selectedBranch.branchId}". ${formatAvailableList(getAvailableBranchParameters(selectedBranch))}`
+                    });
+                    hasInvalidBranchParameter = true;
                 }
             }
             const invalidDynamicFieldId = branch.dynamicFieldIds.find((fieldId) => providedDynamicFieldIds.has(fieldId));
             if (invalidDynamicFieldId !== undefined) {
                 const field = dynamicFieldById.get(invalidDynamicFieldId);
                 if (field !== undefined) {
-                    throw new UserError(`Parameter "${field.displayPath}" is not valid when "${variant.controlDisplayPath}" is "${selectedBranch.branchId}".`);
+                    errors.push({
+                        path: field.displayPath,
+                        message: `Unknown parameter "${field.displayPath}" for ${variant.controlDisplayPath}="${selectedBranch.branchId}". ${formatAvailableList(getAvailableBranchParameters(selectedBranch))}`
+                    });
+                    hasInvalidBranchParameter = true;
                 }
             }
         }
+        if (hasInvalidBranchParameter) {
+            continue;
+        }
         for (const fieldId of selectedBranch.requiredFieldIds) {
             const field = fieldById.get(fieldId);
             if (field === undefined || field.synthetic) {
@@ -1972,7 +2211,10 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
                 providedFieldIds.add(field.id);
                 continue;
             }
-            throw new UserError(`Missing required parameter "${field.displayPath}".`);
+            errors.push({
+                path: field.displayPath,
+                message: `Missing required parameter "${field.displayPath}" for ${variant.controlDisplayPath}="${selectedBranch.branchId}". ${formatAvailableList(getAvailableBranchParameters(selectedBranch))}`
+            });
         }
         for (const fieldId of selectedBranch.requiredDynamicFieldIds) {
             const field = dynamicFieldById.get(fieldId);
@@ -1982,7 +2224,10 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
             if (getNestedValue(params, field.path) !== undefined) {
                 continue;
             }
-            throw new UserError(`Missing required parameter "${field.displayPath}".`);
+            errors.push({
+                path: field.displayPath,
+                message: `Missing required parameter "${field.displayPath}" for ${variant.controlDisplayPath}="${selectedBranch.branchId}". ${formatAvailableList(getAvailableBranchParameters(selectedBranch))}`
+            });
         }
     }
 }
@@ -1993,6 +2238,7 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
         : {};
     const providedFieldIds = new Set();
     const resolvedFieldValues = new Map();
+    const errors = [];
     for (const field of fields) {
         let value;
         let source;
@@ -2026,11 +2272,25 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             value = normalizeCommanderOptionValue(optionValues[field.optionAttribute]);
             source = "option";
         }
+        if (value === undefined &&
+            field.optionFlag === "--verbose" &&
+            Object.prototype.hasOwnProperty.call(optionValues, field.optionAttribute) &&
+            hasFieldValue(optionValues[field.optionAttribute])) {
+            value = normalizeCommanderOptionValue(optionValues[field.optionAttribute]);
+            source = "option";
+        }
         if (value === undefined &&
             Object.prototype.hasOwnProperty.call(presetValues, field.optionAttribute)) {
             value = presetValues[field.optionAttribute];
             source = "preset";
         }
+        if (source === "option") {
+            const parsed = parseOptionFieldValue(field, value, errors);
+            if (!parsed.ok) {
+                continue;
+            }
+            value = parsed.value;
+        }
         if (value === undefined && shouldPrompt && !field.optional) {
             value = await promptForField(field);
             source = "prompt";
@@ -2043,7 +2303,11 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             if (field.optional) {
                 continue;
             }
-            throw new UserError(`Missing required parameter "${field.displayPath}".`);
+            errors.push({
+                path: field.displayPath,
+                message: `Missing required parameter "${field.displayPath}".`
+            });
+            continue;
         }
         resolvedFieldValues.set(field.id, value);
         if (source !== undefined && source !== "default") {
@@ -2054,7 +2318,7 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
         }
     }
     const dynamicResults = dynamicFields.length > 0
-        ? parseDynamicValues(dynamicFields, rawArgv, casing)
+        ? parseDynamicValues(dynamicFields, rawArgv, casing, errors)
         : {
             providedFieldIds: new Set(),
             values: new Map()
@@ -2068,18 +2332,23 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             if (field.optional || field.variantId !== undefined) {
                 continue;
             }
-            throw new UserError(`Missing required parameter "${field.displayPath}".`);
+            errors.push({
+                path: field.displayPath,
+                message: `Missing required parameter "${field.displayPath}".`
+            });
+            continue;
         }
         setNestedValue(params, field.path, value);
     }
-    await enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, dynamicResults.providedFieldIds, providedFieldIds, shouldPrompt);
+    await enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, dynamicResults.providedFieldIds, providedFieldIds, shouldPrompt, errors);
+    throwValidationErrors(errors);
     return params;
 }
 function getResolvedFlags(command) {
     const flags = command.optsWithGlobals();
     return flags;
 }
-async function executeCommand(state, services, requirementOptions, runtimeOptions) {
+async function executeCommand(state, services, requirementOptions, runtimeOptions, onErrorReportContext) {
     const logger = createLogger();
     const primitives = {
         logger,
@@ -2102,55 +2371,250 @@ async function executeCommand(state, services, requirementOptions, runtimeOption
             logger.info(message);
         }
     };
-    await withOutputFormat(output, async () => {
-        await assertCommandRequirements(state.command, preflightContext, runtime.requirementOptions);
-        const params = await resolveParams(state.fields, state.dynamicFields, state.variants, state.positionalValues, optionValues, state.rawArgv, state.casing, state.presetsEnabled ? resolvedFlags.preset : undefined, shouldPrompt);
-        const context = {
-            ...preflightContext,
-            params
-        };
-        if (state.command.confirm &&
-            !state.command.humanInLoop &&
-            !resolvedFlags.yes &&
-            process.stdin.isTTY) {
-            for (const field of state.fields) {
-                const value = field.path.reduce((current, segment) => current && typeof current === "object"
-                    ? current[segment]
-                    : undefined, params);
-                if (value !== undefined) {
-                    logger.resolved(field.displayPath, formatResolvedValue(value));
+    let runtimeSecrets;
+    let resolvedParams;
+    try {
+        await withOutputFormat(output, async () => {
+            await assertCommandRequirements(state.command, preflightContext, runtime.requirementOptions);
+            const params = await resolveParams(state.fields, state.dynamicFields, state.variants, state.positionalValues, optionValues, state.rawArgv, state.casing, state.presetsEnabled ? resolvedFlags.preset : undefined, shouldPrompt);
+            resolvedParams = params;
+            runtimeSecrets = runtime.secrets;
+            const context = {
+                ...preflightContext,
+                params
+            };
+            if (state.command.confirm &&
+                !state.command.humanInLoop &&
+                !resolvedFlags.yes &&
+                process.stdin.isTTY) {
+                for (const field of state.fields) {
+                    const value = field.path.reduce((current, segment) => current && typeof current === "object"
+                        ? current[segment]
+                        : undefined, params);
+                    if (value !== undefined) {
+                        logger.resolved(field.displayPath, formatResolvedValue(value));
+                    }
+                }
+                const proceed = await confirm({
+                    message: "Proceed?",
+                    initialValue: true
+                });
+                if (isCancel(proceed)) {
+                    cancel("Operation cancelled.");
+                    throw new UserError("Operation cancelled.");
+                }
+                if (proceed !== true) {
+                    throw new UserError("Operation cancelled.");
                 }
             }
-            const proceed = await confirm({
-                message: "Proceed?",
-                initialValue: true
-            });
-            if (isCancel(proceed)) {
-                cancel("Operation cancelled.");
-                throw new UserError("Operation cancelled.");
+            const result = await invokeWithHumanInLoop(state.command, context, runtimeOptions, state.commandPath);
+            if (output === "rich" && runtime.isFixture) {
+                writeRichHeader(`${state.command.name} (fixture)`);
             }
-            if (proceed !== true) {
-                throw new UserError("Operation cancelled.");
+            if (isHumanInLoopPending(result)) {
+                renderHumanInLoopPending(result);
+                return;
             }
+            const renderStatus = renderResult(state.command, result, output, primitives);
+            if (renderStatus.mcpError) {
+                process.exitCode = 1;
+            }
+        });
+    }
+    catch (error) {
+        onErrorReportContext?.({
+            command: state.command,
+            commandPath: state.commandPath,
+            params: resolvedParams,
+            secrets: runtimeSecrets ?? runtime.secrets
+        });
+        throw error;
+    }
+}
+function isStringRecord(value) {
+    return isPlainObject(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function isHttpErrorLike(error) {
+    if (!isPlainObject(error)) {
+        return false;
+    }
+    if (error.name !== "HttpError" || typeof error.message !== "string") {
+        return false;
+    }
+    const request = error.request;
+    const response = error.response;
+    return (isPlainObject(request) &&
+        typeof request.method === "string" &&
+        typeof request.url === "string" &&
+        isStringRecord(request.headers) &&
+        isPlainObject(response) &&
+        typeof response.status === "number" &&
+        typeof response.statusText === "string" &&
+        isStringRecord(response.headers) &&
+        "body" in response);
+}
+function hasTypedOptionalField(value, field, type) {
+    return !(field in value) || typeof value[field] === type;
+}
+function isNonEmptyString(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+function isProblemDetailsLike(body) {
+    if (!isPlainObject(body)) {
+        return false;
+    }
+    if (!hasTypedOptionalField(body, "type", "string")) {
+        return false;
+    }
+    if (!hasTypedOptionalField(body, "title", "string")) {
+        return false;
+    }
+    if (!hasTypedOptionalField(body, "status", "number")) {
+        return false;
+    }
+    if (!hasTypedOptionalField(body, "detail", "string")) {
+        return false;
+    }
+    if (!hasTypedOptionalField(body, "instance", "string")) {
+        return false;
+    }
+    return isNonEmptyString(body.title) || isNonEmptyString(body.detail);
+}
+function isGraphQLErrorEnvelopeLike(body) {
+    if (!isPlainObject(body) || !Array.isArray(body.errors) || body.errors.length === 0) {
+        return false;
+    }
+    return body.errors.every((error) => {
+        if (!isPlainObject(error) || typeof error.message !== "string") {
+            return false;
         }
-        const result = await invokeWithHumanInLoop(state.command, context, runtimeOptions, state.commandPath);
-        if (output === "rich" && runtime.isFixture) {
-            writeRichHeader(`${state.command.name} (fixture)`);
-        }
-        if (isHumanInLoopPending(result)) {
-            renderHumanInLoopPending(result);
-            return;
+        if ("path" in error) {
+            const pathValue = error.path;
+            if (!Array.isArray(pathValue) ||
+                !pathValue.every((entry) => typeof entry === "string" || typeof entry === "number")) {
+                return false;
+            }
         }
-        const renderStatus = renderResult(state.command, result, output, primitives);
-        if (renderStatus.mcpError) {
-            process.exitCode = 1;
+        if ("extensions" in error) {
+            if (!isPlainObject(error.extensions)) {
+                return false;
+            }
+            if ("code" in error.extensions && typeof error.extensions.code !== "string") {
+                return false;
+            }
         }
+        return true;
     });
 }
-function handleRunError(error, debug) {
+function styleHttpErrorLine(value, style) {
+    return process.stdout.isTTY === false ? value : style(value);
+}
+function formatHttpErrorStatus(value) {
+    return styleHttpErrorLine(value, text.error);
+}
+function formatProblemDetailsBody(body) {
+    const lines = [];
+    if (isNonEmptyString(body.title)) {
+        lines.push(`Problem: ${body.title}`);
+    }
+    if (isNonEmptyString(body.detail)) {
+        lines.push(`Detail:  ${body.detail}`);
+    }
+    if (body.type !== undefined) {
+        lines.push(`Type:    ${body.type}`);
+    }
+    if (body.instance !== undefined) {
+        lines.push(`Instance: ${body.instance}`);
+    }
+    if (body.status !== undefined) {
+        lines.push(`Status:  ${body.status}`);
+    }
+    return lines.join("\n");
+}
+function formatGraphQLErrorEnvelopeBody(body) {
+    return body.errors
+        .map((error) => {
+        const lines = [`GraphQL error: ${error.message}`];
+        if (error.path !== undefined) {
+            lines.push(`  at path: ${error.path.join(".")}`);
+        }
+        if (error.extensions?.code !== undefined) {
+            lines.push(`  code:    ${error.extensions.code}`);
+        }
+        return lines.join("\n");
+    })
+        .join("\n\n");
+}
+function formatHttpErrorBody(body) {
+    if (typeof body === "string") {
+        return body;
+    }
+    if (isProblemDetailsLike(body)) {
+        return formatProblemDetailsBody(body);
+    }
+    if (isGraphQLErrorEnvelopeLike(body)) {
+        return formatGraphQLErrorEnvelopeBody(body);
+    }
+    const serialized = JSON.stringify(body, null, 2);
+    return serialized === undefined ? String(body) : serialized;
+}
+function indentHttpErrorBlock(value) {
+    return value
+        .split("\n")
+        .map((line) => `  ${line}`)
+        .join("\n");
+}
+function formatHttpHeaderValue(name, value) {
+    return name.toLowerCase() === "authorization" ? "Bearer ****" : value;
+}
+function formatHttpErrorHeaders(headers) {
+    return Object.entries(headers).map(([name, value]) => `  ${name}: ${formatHttpHeaderValue(name, value)}`);
+}
+function formatHttpErrorSnippet(body) {
+    return formatHttpErrorBody(body).replace(/\s+/g, " ").trim().slice(0, 200);
+}
+function renderHttpError(error, options) {
+    const detailed = options.verbose || options.debugStackMode !== undefined;
+    const lines = [
+        styleHttpErrorLine(`Request:  ${error.request.method} ${error.request.url}`, text.muted)
+    ];
+    if (detailed) {
+        lines.push("", "Request headers:", ...formatHttpErrorHeaders(error.request.headers), "");
+        if (error.request.body !== undefined) {
+            lines.push("Request body:", indentHttpErrorBlock(formatHttpErrorBody(error.request.body)), "");
+        }
+    }
+    lines.push(formatHttpErrorStatus(`Status:   ${error.response.status} ${error.response.statusText}`));
+    if (detailed) {
+        lines.push("", "Response headers:", ...formatHttpErrorHeaders(error.response.headers), "", "Response body:", indentHttpErrorBlock(formatHttpErrorBody(error.response.body)));
+    }
+    else {
+        lines.push("", `Response body: ${formatHttpErrorSnippet(error.response.body)}`, "Re-run with --verbose to see headers and full body.");
+    }
+    process.stderr.write(`${lines.join("\n")}\n`);
+    const stack = error instanceof Error ? error.stack : undefined;
+    if (options.debugStackMode !== undefined && stack) {
+        process.stderr.write(`${formatDebugStack(stack, options.debugStackMode)}\n`);
+    }
+}
+function handleRunError(error, options) {
     const logger = createLogger();
     if (error instanceof UserError) {
-        logger.error(error.message);
+        logger.error(appendUsagePointer(error.message, {
+            rootUsageName: options.rootUsageName,
+            commandPath: options.commandPath
+        }));
+        process.exitCode = 1;
+        return;
+    }
+    if (error instanceof Error && error.name === "ToolcraftBugError") {
+        logger.error(`toolcraft hit an internal invariant: ${error.message}\n` +
+            `This is a bug in toolcraft or in the command definition; ` +
+            `it cannot be worked around by changing argv. ` +
+            `Re-run with --debug for a stack trace and file an issue.`);
+        if (options.debugStackMode !== undefined && error.stack) {
+            process.stderr.write(`${formatDebugStack(error.stack, options.debugStackMode)}\n`);
+        }
         process.exitCode = 1;
         return;
     }
@@ -2159,22 +2623,229 @@ function handleRunError(error, debug) {
         if (error.code === "commander.helpDisplayed" || error.code === "commander.version") {
             return;
         }
+        if (error.code === "commander.unknownCommand") {
+            logger.error(appendUsagePointer(formatUnknownCommandError(error, options.program, options.argv ?? process.argv), {
+                rootUsageName: options.rootUsageName,
+                commandPath: options.commandPath
+            }));
+            return;
+        }
+        if (error.code === "commander.unknownOption") {
+            const argv = options.argv ?? process.argv;
+            logger.error(appendUsagePointer(formatUnknownOptionError(error, options.program, argv), {
+                rootUsageName: options.rootUsageName,
+                commandPath: options.commandPath.length > 0
+                    ? options.commandPath
+                    : findCurrentCommanderCommandPath(options.program, argv)
+            }));
+            return;
+        }
+        return;
+    }
+    if (isHttpErrorLike(error)) {
+        renderHttpError(error, options);
+        process.exitCode = 1;
         return;
     }
     const message = error instanceof Error ? error.message : String(error);
-    logger.error(debug ? message : `${message} Use --debug for a stack trace.`);
-    if (debug && error instanceof Error && error.stack) {
-        process.stderr.write(`${error.stack}\n`);
+    logger.error(options.debugStackMode !== undefined ? message : `${message} Use --debug for a stack trace.`);
+    if (options.debugStackMode !== undefined && error instanceof Error && error.stack) {
+        process.stderr.write(`${formatDebugStack(error.stack, options.debugStackMode)}\n`);
     }
     process.exitCode = 1;
 }
+function formatInvalidEnumMessage(label, value, values, opts = {}) {
+    const suggestions = suggest(value, opts.candidates ?? values.map((candidate) => String(candidate)), opts);
+    const suggestionLine = suggestions.length > 0 ? ` Did you mean: ${suggestions.join(", ")}?\n` : " ";
+    return `Invalid value for "${label}".${suggestionLine}Expected one of: ${values.map((candidate) => String(candidate)).join(", ")}, got ${describeReceived(value)}.`;
+}
+function formatUnknownCommandError(error, program, argv) {
+    const input = extractQuotedCommanderValue(error.message) ?? "";
+    const currentCommand = program === undefined ? undefined : findCurrentCommanderCommand(program, argv);
+    return formatUnknownCommandMessage(input, currentCommand);
+}
+function appendUsagePointer(message, options) {
+    if (message.includes("--help")) {
+        return message;
+    }
+    const helpTarget = options.commandPath.length === 0
+        ? options.rootUsageName
+        : `${options.rootUsageName} ${options.commandPath}`;
+    return `${message}\nRun ${helpTarget} --help for usage.`;
+}
+function formatCliCommandPath(commandPath) {
+    return commandPath
+        .split(".")
+        .filter((segment) => segment.length > 0)
+        .join(" ");
+}
+function formatUnknownCommandMessage(input, currentCommand) {
+    const suggestions = currentCommand === undefined
+        ? []
+        : suggest(input, currentCommand.commands.map((command) => command.name()));
+    return formatSuggestionMessage(`Unknown command "${input}".`, suggestions);
+}
+function formatUnknownOptionError(error, program, argv) {
+    const input = extractQuotedCommanderValue(error.message) ?? "";
+    const currentCommand = program === undefined ? undefined : findCurrentCommanderCommand(program, argv);
+    const suggestions = currentCommand === undefined
+        ? []
+        : suggest(input, currentCommand.options
+            .map((option) => option.long)
+            .filter((flag) => flag !== undefined));
+    return formatSuggestionMessage(`Unknown option "${input}".`, suggestions);
+}
+function formatSuggestionMessage(message, suggestions) {
+    if (suggestions.length === 0) {
+        return message;
+    }
+    return `${message}\nDid you mean: ${suggestions.join(", ")}?`;
+}
+function extractQuotedCommanderValue(message) {
+    const singleQuoted = extractBetweenQuotes(message, "'");
+    if (singleQuoted !== undefined) {
+        return singleQuoted;
+    }
+    return extractBetweenQuotes(message, '"');
+}
+function extractBetweenQuotes(message, quote) {
+    const start = message.indexOf(quote);
+    if (start === -1) {
+        return undefined;
+    }
+    const end = message.indexOf(quote, start + 1);
+    if (end === -1) {
+        return undefined;
+    }
+    return message.slice(start + 1, end);
+}
+function resolveDebugStackMode(value) {
+    if (value === true || value === "trim") {
+        return "trim";
+    }
+    if (value === "raw") {
+        return "raw";
+    }
+    return undefined;
+}
+function getDebugStackModeFromArgv(argv) {
+    for (let index = 2; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === undefined) {
+            continue;
+        }
+        if (token === "--debug") {
+            return "trim";
+        }
+        if (token === "--debug=raw") {
+            return "raw";
+        }
+    }
+    return undefined;
+}
+function findCurrentCommanderCommand(program, argv) {
+    let current = program;
+    const tokens = argv.slice(2);
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === undefined || token === "--") {
+            break;
+        }
+        if (token.startsWith("-")) {
+            const option = current.options.find((candidate) => candidate.long === token || candidate.short === token);
+            if (option?.required === true && !token.includes("=")) {
+                index += 1;
+            }
+            continue;
+        }
+        const child = current.commands.find((command) => command.name() === token || command.aliases().includes(token));
+        if (child === undefined) {
+            break;
+        }
+        current = child;
+    }
+    return current;
+}
+function findCurrentCommanderCommandPath(program, argv) {
+    if (program === undefined) {
+        return "";
+    }
+    let current = program;
+    const pathSegments = [];
+    const tokens = argv.slice(2);
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === undefined || token === "--" || token.startsWith("-")) {
+            break;
+        }
+        const child = current.commands.find((command) => command.name() === token || command.aliases().includes(token));
+        if (child === undefined) {
+            break;
+        }
+        current = child;
+        pathSegments.push(child.name());
+    }
+    return pathSegments.join(" ");
+}
+function findUnknownCommanderCommand(program, argv) {
+    let current = program;
+    const pathSegments = [];
+    const tokens = argv.slice(2);
+    for (let index = 0; index < tokens.length; index += 1) {
+        const token = tokens[index];
+        if (token === undefined || token === "--") {
+            return undefined;
+        }
+        if (token.startsWith("-")) {
+            const option = current.options.find((candidate) => candidate.long === token || candidate.short === token);
+            if (option?.required === true && !token.includes("=")) {
+                index += 1;
+            }
+            continue;
+        }
+        if (current.commands.length === 0 || getDefaultCommanderCommandName(current) !== undefined) {
+            return undefined;
+        }
+        const child = current.commands.find((command) => command.name() === token || command.aliases().includes(token));
+        if (child === undefined) {
+            return {
+                input: token,
+                currentCommand: current,
+                commandPath: pathSegments.join(" ")
+            };
+        }
+        current = child;
+        pathSegments.push(child.name());
+    }
+    return undefined;
+}
+function getDefaultCommanderCommandName(command) {
+    const candidate = command;
+    return typeof candidate._defaultCommandName === "string"
+        ? candidate._defaultCommandName
+        : undefined;
+}
+function configureCommanderSuggestionOutput(command) {
+    command.exitOverride();
+    command.configureOutput({
+        outputError: (message, write) => {
+            if (message.includes("unknown command") || message.includes("unknown option")) {
+                return;
+            }
+            write(message);
+        }
+    });
+    command.commands.forEach((child) => configureCommanderSuggestionOutput(child));
+}
 export async function runCLI(roots, options = {}) {
+    enableSourceMaps();
     const root = mergeApprovalsGroup(normalizeRoots(roots, process.argv));
     await resolveMcpProxies(root, { projectRoot: options.projectRoot });
     const casing = options.casing ?? "kebab";
     const services = (options.services ?? {});
     const runtimeOptions = options.humanInLoop ?? {};
     const version = options.version ?? findEntrypointPackageMetadata(process.argv[1])?.version;
+    const rootUsageName = options.rootUsageName ?? inferProgramName(process.argv);
     const servicesWithBuiltIns = {
         ...services,
         runtimeOptions,
@@ -2200,9 +2871,14 @@ export async function runCLI(roots, options = {}) {
         program.version(version, "--version");
     }
     let lastActionCommand;
+    let resolvedCommandPath = "";
+    let errorReportContext;
     const execute = async (state) => {
         lastActionCommand = state.actionCommand;
-        await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeOptions);
+        resolvedCommandPath = formatCliCommandPath(state.commandPath);
+        await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeOptions, (context) => {
+            errorReportContext = context;
+        });
     };
     for (const child of root.children) {
         const command = createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled);
@@ -2214,6 +2890,16 @@ export async function runCLI(roots, options = {}) {
             (command.name() === root.default.name || command.aliases().includes(root.default.name));
         program.addCommand(command, isDefaultChild ? { isDefault: true } : undefined);
     }
+    configureCommanderSuggestionOutput(program);
+    const unknownCommand = findUnknownCommanderCommand(program, process.argv);
+    if (unknownCommand !== undefined) {
+        createLogger().error(appendUsagePointer(formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand), {
+            rootUsageName,
+            commandPath: unknownCommand.commandPath
+        }));
+        process.exitCode = 1;
+        return;
+    }
     try {
         await program.parseAsync(process.argv);
     }
@@ -2222,8 +2908,31 @@ export async function runCLI(roots, options = {}) {
             renderApprovalDeclined(error);
             return;
         }
-        handleRunError(error, lastActionCommand
-            ? Boolean(getResolvedFlags(lastActionCommand).debug)
-            : process.argv.includes("--debug"));
+        const resolvedFlags = lastActionCommand ? getResolvedFlags(lastActionCommand) : undefined;
+        const report = await writeErrorReport({
+            argv: process.argv,
+            command: errorReportContext?.command,
+            commandPath: errorReportContext?.commandPath ?? resolvedCommandPath,
+            env: process.env,
+            error,
+            errorReports: options.errorReports,
+            params: errorReportContext?.params,
+            projectRoot: options.projectRoot,
+            secrets: errorReportContext?.secrets,
+            version
+        });
+        if (report !== undefined) {
+            process.stderr.write(`Saved error report to ${report.displayPath}\n`);
+        }
+        handleRunError(error, {
+            debugStackMode: resolvedFlags !== undefined
+                ? resolveDebugStackMode(resolvedFlags.debug)
+                : getDebugStackModeFromArgv(process.argv),
+            verbose: resolvedFlags ? Boolean(resolvedFlags.verbose) : process.argv.includes("--verbose"),
+            program,
+            argv: process.argv,
+            rootUsageName,
+            commandPath: resolvedCommandPath
+        });
     }
 }