toolcraft 0.0.232 → 0.0.233

package/dist/cli.js

@@ -2,8 +2,8 @@ import "./node-require-shim.js";
 import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Option } from "commander";
-import { validate as validateSchema } from "toolcraft-schema";
-import { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderHelpTokens, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
+import { cloneDefaultValue, nativeJsonSchema, unicodeLength, validate as validateSchema } from "toolcraft-schema";
+import { configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderHelpTokens, renderTable, select, text, withOutputFormat } from "toolcraft-design";
 import { ApprovalDeclinedError, ToolcraftBugError, UserError, assertCommandRequirements, getCommandSourcePath, hasMcpProxyConfig, isUserError, resolveCommandSecrets } from "./index.js";
 import { hasOwnErrorCode } from "./error-codes.js";
 import { writeErrorReport } from "./error-report.js";
@@ -203,10 +203,20 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 optional: runtimeOptional,
                 hasDefault: false,
                 defaultValue: undefined,
-                requiredWhenActive
+                requiredWhenActive,
+                variantId: variantContext?.id,
+                variantBranchId: variantContext?.branchId
             };
             collected.fields.push(controlField);
             const branches = [];
+            collected.variants.push({
+                id: variantId,
+                controlDisplayPath: controlField.displayPath,
+                controlFieldId: controlField.id,
+                optional: variantContext === undefined ? runtimeOptional : !requiredWhenActive,
+                parent: variantContext,
+                branches
+            });
             for (const [branchId, branchSchema] of Object.entries(childSchema.branches)) {
                 const branch = collectFields(branchSchema, casing, globalLongOptionFlags, nextPath, true, {
                     id: variantId,
@@ -227,20 +237,21 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                         .map((field) => field.id)
                 });
             }
-            collected.variants.push({
-                id: variantId,
-                controlDisplayPath: controlField.displayPath,
-                controlFieldId: controlField.id,
-                optional: runtimeOptional,
-                branches
-            });
             continue;
         }
         if (childSchema.kind === "union") {
             const variantId = `${toDisplayPath(nextPath)}:union`;
             const controlPath = toUnionKindControlPath(nextPath);
             const controlDisplayPath = toUnionKindDisplayPath(nextPath);
-            const branchIds = childSchema.branches.map((branch) => getRequiredBranchFingerprint(branch, casing));
+            const seenFingerprints = new Set();
+            const branchIds = childSchema.branches.map((branch, index) => {
+                const fingerprint = getRequiredBranchFingerprint(branch, casing);
+                const branchId = seenFingerprints.has(fingerprint)
+                    ? `${fingerprint} (branch ${index + 1})`
+                    : fingerprint;
+                seenFingerprints.add(fingerprint);
+                return branchId;
+            });
             const controlField = {
                 id: controlDisplayPath,
                 path: controlPath,
@@ -256,10 +267,20 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 hasDefault: false,
                 defaultValue: undefined,
                 requiredWhenActive,
-                synthetic: true
+                synthetic: true,
+                variantId: variantContext?.id,
+                variantBranchId: variantContext?.branchId
             };
             collected.fields.push(controlField);
             const branches = [];
+            collected.variants.push({
+                id: variantId,
+                controlDisplayPath,
+                controlFieldId: controlField.id,
+                optional: variantContext === undefined ? runtimeOptional : !requiredWhenActive,
+                parent: variantContext,
+                branches
+            });
             childSchema.branches.forEach((branchSchema, index) => {
                 const branchId = branchIds[index] ?? "";
                 const branch = collectFields(branchSchema, casing, globalLongOptionFlags, nextPath, true, {
@@ -281,13 +302,6 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                         .map((field) => field.id)
                 });
             });
-            collected.variants.push({
-                id: variantId,
-                controlDisplayPath,
-                controlFieldId: controlField.id,
-                optional: runtimeOptional,
-                branches
-            });
             continue;
         }
         if (childSchema.kind === "record") {
@@ -418,23 +432,24 @@ function parseBooleanText(value, label) {
     if (normalized === "false") {
         return false;
     }
-    throw new InvalidArgumentError(`Invalid value for "${label}". Expected true or false, got ${describeReceived(value)}.`);
+    throw new UserError(`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) {
         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)}.`);
+        throw new UserError(`Invalid value for "${label}".${suggestionLine}Expected one of: ${values.map((candidate) => String(candidate)).join(", ")}, got ${describeReceived(value)}.`);
     }
     return match;
 }
 function validateStringPattern(value, schema, label) {
-    if (schema.minLength !== undefined && value.length < schema.minLength) {
-        throw new UserError(`Invalid value for "${label}". Expected a string with length at least ${schema.minLength}, got string with length ${value.length}.`);
+    const length = unicodeLength(value);
+    if (schema.minLength !== undefined && length < schema.minLength) {
+        throw new UserError(`Invalid value for "${label}". Expected a string with length at least ${schema.minLength}, got string with length ${length}.`);
     }
-    if (schema.maxLength !== undefined && value.length > schema.maxLength) {
-        throw new UserError(`Invalid value for "${label}". Expected a string with length at most ${schema.maxLength}, got string with length ${value.length}.`);
+    if (schema.maxLength !== undefined && length > schema.maxLength) {
+        throw new UserError(`Invalid value for "${label}". Expected a string with length at most ${schema.maxLength}, got string with length ${length}.`);
     }
     if (schema.pattern !== undefined && !matchesStringPattern(value, schema.pattern)) {
         throw new UserError(`Invalid value for "${label}": "${value}" does not match pattern "${schema.pattern}".`);
@@ -449,7 +464,7 @@ function parseJsonText(value, label) {
         return JSON.parse(value);
     }
     catch (error) {
-        throw new InvalidArgumentError(`Invalid value for "${label}". Expected valid JSON, got ${describeReceived(value)} (parser: ${getErrorMessage(error)}).`);
+        throw new UserError(`Invalid value for "${label}". Expected valid JSON, got ${describeReceived(value)} (parser: ${getErrorMessage(error)}).`);
     }
 }
 function describeReceived(value) {
@@ -573,8 +588,8 @@ function parseScalarValue(value, schema, label) {
             return validateStringPattern(value, schema, label);
         case "number": {
             const parsed = Number(value);
-            if (!isValidNumberSchemaValue(parsed, schema)) {
-                throw new InvalidArgumentError(`Invalid value for "${label}". Expected ${getExpectedNumberDescription(schema)}, got ${describeReceived(value)}.`);
+            if (value.trim().length === 0 || !isValidNumberSchemaValue(parsed, schema)) {
+                throw new UserError(`Invalid value for "${label}". Expected ${getExpectedNumberDescription(schema)}, got ${describeReceived(value)}.`);
             }
             return parsed;
         }
@@ -616,22 +631,66 @@ function parseArrayValue(value, schema, label) {
     }
     return splitArrayInput(value).map((item) => parseScalarValue(item, itemSchema, label));
 }
-function isNegativeNumericArrayToken(token, schema) {
+function isNegativeNumericToken(token) {
     if (!token.startsWith("-") || token.startsWith("--")) {
         return false;
     }
-    const itemSchema = unwrapOptional(schema.item);
-    if (itemSchema.kind !== "number") {
-        return false;
-    }
     const items = splitArrayInput(token);
-    return (items.length > 0 && items.every((item) => isValidNumberSchemaValue(Number(item), itemSchema)));
+    return (items.length > 0 && items.every((item) => Number.isFinite(Number(item))));
 }
 function isNextArrayOptionToken(token, schema) {
     if (token === "-" && unwrapOptional(schema.item).kind === "string") {
         return false;
     }
-    return token.startsWith("-") && !isNegativeNumericArrayToken(token, schema);
+    return token.startsWith("-") &&
+        !(unwrapOptional(schema.item).kind === "number" && isNegativeNumericToken(token));
+}
+function normalizeNumericArrayOptions(argv, options, numericArrayOptions) {
+    if (numericArrayOptions.size === 0) {
+        return argv;
+    }
+    const normalized = [];
+    let activeFlag;
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index];
+        if (token === "--") {
+            normalized.push(...argv.slice(index));
+            break;
+        }
+        const option = options.find((candidate) => candidate.short === token || candidate.long === token);
+        const attachedOption = token.startsWith("-") && !token.startsWith("--") && token.length > 2
+            ? options.find((candidate) => candidate.short === token.slice(0, 2))
+            : undefined;
+        if (activeFlag !== undefined && option === undefined && attachedOption === undefined) {
+            if (token.startsWith("-") && !token.startsWith("--")) {
+                if (isNegativeNumericToken(token)) {
+                    normalized.push(activeFlag);
+                }
+                else if (token !== "-") {
+                    activeFlag = undefined;
+                }
+            }
+            else if (token.startsWith("--")) {
+                activeFlag = undefined;
+            }
+        }
+        else {
+            activeFlag = undefined;
+        }
+        normalized.push(token);
+        if (option !== undefined) {
+            const nextToken = argv[index + 1];
+            if (nextToken !== undefined && (option.required ||
+                (option.optional && !(nextToken.length > 1 && nextToken.startsWith("-"))))) {
+                normalized.push(nextToken);
+                index += 1;
+            }
+            if (numericArrayOptions.has(option)) {
+                activeFlag = token;
+            }
+        }
+    }
+    return normalized;
 }
 function validateArrayBounds(value, schema, label) {
     if (schema.minItems !== undefined && value.length < schema.minItems) {
@@ -642,31 +701,37 @@ function validateArrayBounds(value, schema, label) {
     }
 }
 function createOption(field, globalLongOptionFlags) {
-    const flags = formatOptionFlags(field, globalLongOptionFlags);
     const collidesWithGlobalFlag = globalLongOptionFlags.has(field.optionFlag);
-    if (field.schema.kind === "boolean") {
-        if (collidesWithGlobalFlag) {
-            return [createCommanderOption(flags, field.description, field)];
-        }
-        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 : value));
-        return [
-            mainOption,
-            createCommanderOption(`--no-${field.optionFlag.slice(2)}`, field.description, field)
+    const flagGroups = collidesWithGlobalFlag
+        ? [formatOptionFlags(field, globalLongOptionFlags)]
+        : [
+            field.shortFlag === undefined ? field.optionFlag : `-${field.shortFlag}, ${field.optionFlag}`,
+            ...field.longAliases
         ];
-    }
-    if (field.schema.kind === "array") {
-        return [
-            createCommanderOption(`${flags} <value...>`, field.description, field).argParser((value, previous = []) => [...previous, value])
-        ];
-    }
-    if (field.schema.kind === "json") {
-        return [createCommanderOption(`${flags} <json>`, field.description, field)];
-    }
-    const option = createCommanderOption(`${flags} <value>`, field.description, field);
-    return [option];
+    return flagGroups.flatMap((flags, index) => {
+        if (field.schema.kind === "boolean") {
+            if (collidesWithGlobalFlag) {
+                return [createCommanderOption(flags, field.description, field)];
+            }
+            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 : value));
+            return index === 0
+                ? [mainOption, createCommanderOption(`--no-${field.optionFlag.slice(2)}`, field.description, field)]
+                : [mainOption];
+        }
+        if (field.schema.kind === "array") {
+            return [
+                createCommanderOption(`${flags} <value...>`, field.description, field).argParser((value, previous = []) => [...previous, value])
+            ];
+        }
+        if (field.schema.kind === "json") {
+            return [createCommanderOption(`${flags} <json>`, field.description, field)];
+        }
+        const option = createCommanderOption(`${flags} <value>`, field.description, field);
+        return [option];
+    });
 }
 function resolveCLIControls(controls) {
     const outputFormats = typeof controls?.output === "object" ? (controls.output.formats ?? {}) : {};
@@ -752,11 +817,101 @@ function createCommanderOption(flags, description, field) {
     }
     return option;
 }
-function hasHelpFlag(argv) {
-    return argv.some((token) => HELP_FLAGS.has(token));
-}
-function normalizeVerboseAlias(argv) {
-    return argv.map((token) => (token === "-v" ? "--verbose" : token));
+function prepareCliArguments(program, argv, fieldLoaders, casing, controls) {
+    const normalized = argv.slice(0, 2);
+    const path = [];
+    let current = program;
+    let helpPath;
+    let output;
+    for (let index = 2; index < argv.length; index += 1) {
+        let token = argv[index];
+        if (token === "--") {
+            normalized.push(...argv.slice(index));
+            break;
+        }
+        if (HELP_FLAGS.has(token)) {
+            helpPath ??= [...path];
+            normalized.push(token);
+            continue;
+        }
+        if (controls.verbose && token === "-v") {
+            token = "--verbose";
+        }
+        const dynamicFields = fieldLoaders.get(current)?.() ?? [];
+        const equalsIndex = token.startsWith("--") ? token.indexOf("=") : -1;
+        const flag = equalsIndex < 0 ? token : token.slice(0, equalsIndex);
+        let option = current.options.find((candidate) => candidate.long === flag || candidate.short === flag);
+        let attached = equalsIndex >= 0;
+        if (option === undefined && token.startsWith("-") && !token.startsWith("--") && token.length > 2) {
+            for (let offset = 1; offset < token.length; offset += 1) {
+                const candidate = current.options.find((entry) => entry.short === `-${token[offset]}`);
+                if (candidate === undefined) {
+                    break;
+                }
+                option = candidate;
+                if (candidate.required || candidate.optional) {
+                    attached = offset < token.length - 1;
+                    break;
+                }
+            }
+        }
+        if (option !== undefined) {
+            normalized.push(token);
+            const next = argv[index + 1];
+            if (flag === "--output" && controls.output) {
+                output = attached ? token.slice(equalsIndex + 1) : next;
+            }
+            if (!attached && next !== undefined && (option.required ||
+                (option.optional && !(next.length > 1 && next.startsWith("-"))))) {
+                normalized.push(next);
+                index += 1;
+            }
+            continue;
+        }
+        const child = current.commands.find((command) => command.name() === token || command.aliases().includes(token));
+        if (child !== undefined) {
+            current = child;
+            path.push(token);
+            normalized.push(token);
+            continue;
+        }
+        const defaultName = getDefaultCommanderCommandName(current);
+        const defaultCommand = current.commands.find((command) => command.name() === defaultName);
+        if (defaultCommand !== undefined) {
+            current = defaultCommand;
+            index -= 1;
+            continue;
+        }
+        if (token.startsWith("--") && equalsIndex < 0) {
+            const normalizedFlag = token.startsWith("--no-") ? token.slice(5) : token.slice(2);
+            let dynamic;
+            try {
+                dynamic = resolveDynamicOption(dynamicFields, normalizedFlag, casing);
+            }
+            catch (error) {
+                if (!isUserError(error)) {
+                    throw error;
+                }
+            }
+            const next = argv[index + 1];
+            if (dynamic !== undefined && next !== undefined &&
+                dynamic.leaf.schema.kind !== "boolean" && dynamic.leaf.schema.kind !== "array") {
+                normalized.push(`${token}=${next}`);
+                index += 1;
+                continue;
+            }
+        }
+        if (!token.startsWith("-") && current.commands.length > 0) {
+            path.push(token);
+        }
+        normalized.push(token);
+    }
+    return {
+        argv: normalized,
+        ...(helpPath === undefined ? {} : {
+            helpArgv: [...argv.slice(0, 2), ...helpPath, ...(output === undefined ? [] : ["--output", output])]
+        })
+    };
 }
 function resolveHelpOutput(argv) {
     for (let index = 0; index < argv.length; index += 1) {
@@ -1538,12 +1693,20 @@ function formatJsonHelpOption(field, globalLongOptionFlags) {
         name: field.displayPath,
         flags: formatHelpFieldFlags(field, globalLongOptionFlags).split(", "),
         type: formatJsonHelpSchemaType(field.schema),
+        ...(field.schema.kind === "enum" ? { choices: formatCLIEnumChoices(field.schema) } : {}),
         ...(field.description === undefined ? {} : { description: field.description }),
         required: field.requiredWhenActive,
         ...(field.hasDefault ? { default: field.defaultValue } : {}),
         ...(field.positionalIndex === undefined ? {} : { positional: true })
     };
 }
+function formatCLIEnumChoices(schema) {
+    const choices = schema.values.map((value) => String(value));
+    if (schema.nullable === true && !choices.includes("null")) {
+        choices.push("null");
+    }
+    return choices;
+}
 function formatJsonHelpSchemaType(schema) {
     if (schema.kind === "enum") {
         return "enum";
@@ -1591,7 +1754,7 @@ async function renderGeneratedHelp(root, argv, options) {
         }, rootUsageName));
         return;
     }
-    await withOutputFormat(output, async () => {
+    await withOutputFormat(toDesignSystemOutput(output), async () => {
         const rendered = target.node.kind === "group"
             ? renderGroupHelp(target.node, target.breadcrumb, "cli", casing, {
                 controls,
@@ -1606,18 +1769,17 @@ async function renderGeneratedHelp(root, argv, options) {
         process.stdout.write(rendered);
     });
 }
-function createNodeCommand(node, casing, globalLongOptionFlags, execute, presetsEnabled, controls, pathSegments = []) {
+function createNodeCommand(node, casing, globalLongOptionFlags, execute, presetsEnabled, controls, fieldLoaders, pathSegments = []) {
     const nextPathSegments = [...pathSegments, node.name];
     if (node.kind === "command") {
         if (!node.scope.includes("cli")) {
             return null;
         }
         const command = new CommanderCommand(node.name);
+        let unknownArgv = [];
+        let loadedFields;
         Reflect.set(command, "_toolcraftHidden", node.hidden);
         Reflect.set(command, "_toolcraftOriginalName", node.name);
-        const collected = collectFields(node.params, casing, globalLongOptionFlags);
-        const fields = assignPositionals(collected.fields, node.positional);
-        validateUniqueOptionFlags(fields, globalLongOptionFlags);
         if (node.description !== undefined) {
             command.description(node.description);
         }
@@ -1625,36 +1787,63 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
         command.addHelpCommand(false);
         addGlobalOptions(command, presetsEnabled, controls);
         command.allowExcessArguments(true);
-        if (collected.dynamicFields.length > 0) {
-            command.allowUnknownOption(true);
-        }
-        for (const field of fields) {
-            if (field.positionalIndex !== undefined) {
-                // Positionals are declared optional so resolveParams stays the single owner of argument
-                // validation: Commander would otherwise report a missing positional in its own words
-                // before prompts, defaults, and presets have had a chance to supply the value.
-                command.argument(field.variadicPosition === true ? `[${field.displayPath}...]` : `[${field.displayPath}]`);
-                continue;
+        fieldLoaders.set(command, () => {
+            if (loadedFields !== undefined) {
+                return loadedFields;
             }
-            for (const option of createOption(field, globalLongOptionFlags)) {
-                command.addOption(option);
-            }
-        }
-        command.action(async (...args) => {
-            const actionCommand = args[args.length - 1];
-            const positionalValues = args.slice(0, -2);
-            await execute({
-                command: node,
-                commandPath: nextPathSegments.join("."),
-                casing,
-                dynamicFields: collected.dynamicFields,
-                fields,
-                positionalValues,
-                presetsEnabled,
-                rawArgv: actionCommand.args,
-                actionCommand,
-                variants: collected.variants
+            const collected = collectFields(node.params, casing, globalLongOptionFlags);
+            const fields = assignPositionals(collected.fields, node.positional);
+            validateUniqueOptionFlags(fields, globalLongOptionFlags);
+            if (collected.dynamicFields.length > 0) {
+                command.allowUnknownOption(true);
+            }
+            const numericArrayOptions = new Set();
+            for (const field of fields) {
+                if (field.positionalIndex !== undefined) {
+                    // Positionals are declared optional so resolveParams stays the single owner of argument
+                    // validation: Commander would otherwise report a missing positional in its own words
+                    // before prompts, defaults, and presets have had a chance to supply the value.
+                    command.argument(field.variadicPosition === true ? `[${field.displayPath}...]` : `[${field.displayPath}]`);
+                    continue;
+                }
+                for (const option of createOption(field, globalLongOptionFlags)) {
+                    command.addOption(option);
+                    if (field.schema.kind === "array" && unwrapOptional(field.schema.item).kind === "number") {
+                        numericArrayOptions.add(option);
+                    }
+                }
+            }
+            const parseOptions = command.parseOptions.bind(command);
+            command.parseOptions = (argv) => {
+                const parsed = parseOptions(normalizeNumericArrayOptions(argv, command.options, numericArrayOptions));
+                const firstUnknownOption = parsed.unknown.findIndex((token) => token.length > 1 && token.startsWith("-") && !isNegativeNumericToken(token));
+                const operandCount = firstUnknownOption < 0 ? parsed.unknown.length : firstUnknownOption;
+                parsed.operands.push(...parsed.unknown.splice(0, operandCount));
+                if (parsed.unknown[0] === "--") {
+                    parsed.operands.push(...parsed.unknown.slice(1));
+                    parsed.unknown.length = 0;
+                }
+                unknownArgv = parsed.unknown;
+                return parsed;
+            };
+            command.action(async (...args) => {
+                const actionCommand = args[args.length - 1];
+                const positionalValues = actionCommand.args.slice(0, actionCommand.args.length - unknownArgv.length);
+                await execute({
+                    command: node,
+                    commandPath: nextPathSegments.join("."),
+                    casing,
+                    dynamicFields: collected.dynamicFields,
+                    fields,
+                    positionalValues,
+                    presetsEnabled,
+                    rawArgv: unknownArgv,
+                    actionCommand,
+                    variants: collected.variants
+                });
             });
+            loadedFields = collected.dynamicFields;
+            return loadedFields;
         });
         return command;
     }
@@ -1665,7 +1854,7 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
         .filter((child) => !isNodeVisibleInScope(child, "cli"))
         .flatMap((child) => getNodeCommandNames(child));
     const visibleChildren = node.children
-        .map((child) => createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled, controls, nextPathSegments))
+        .map((child) => createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled, controls, fieldLoaders, nextPathSegments))
         .filter((child) => child !== null);
     const group = new CommanderCommand(node.name);
     Reflect.set(group, "_toolcraftReservedChildNames", reservedChildNames);
@@ -1773,7 +1962,8 @@ function createGlobalSnapshotOptions(presetsEnabled, versionEnabled, controls) {
             type: "enum",
             required: false,
             hidden: true,
-            description: "Print stack traces for unexpected errors."
+            description: "Print stack traces for unexpected errors.",
+            choices: ["trim", "raw"]
         });
     }
     if (controls.logLevel) {
@@ -1783,7 +1973,8 @@ function createGlobalSnapshotOptions(presetsEnabled, versionEnabled, controls) {
             type: "enum",
             required: false,
             hidden: true,
-            description: "Set runtime diagnostic log level."
+            description: "Set runtime diagnostic log level.",
+            choices: [...LOG_LEVELS]
         });
     }
     if (controls.verbose) {
@@ -1849,6 +2040,7 @@ function createFieldSnapshotOption(field, globalLongOptionFlags) {
         name: field.displayPath,
         flags: formatHelpFieldFlags(field, globalLongOptionFlags).split(", "),
         type: formatJsonHelpSchemaType(field.schema),
+        ...(field.schema.kind === "enum" ? { choices: formatCLIEnumChoices(field.schema) } : {}),
         required: field.requiredWhenActive,
         hidden: false,
         ...(field.description === undefined ? {} : { description: field.description }),
@@ -1999,7 +2191,6 @@ function withPromptStreams(options, streams) {
     };
 }
 function throwPromptCancellation() {
-    cancel("Operation cancelled.");
     throw new UserError("Operation cancelled.");
 }
 async function promptForField(field, streams = {}) {
@@ -2044,7 +2235,7 @@ async function promptForField(field, streams = {}) {
         throw new UserError(`Missing required parameter "${field.displayPath}".`);
     }
     if (entered.trim().length === 0 && field.hasDefault) {
-        return field.defaultValue;
+        return cloneDefaultValue(field.defaultValue);
     }
     if (field.schema.kind === "array") {
         return parseArrayValue(entered, field.schema, field.displayPath);
@@ -2112,23 +2303,6 @@ function toDesignSystemOutput(output) {
     }
     return "terminal";
 }
-async function withOutputFormat(output, fn) {
-    const previous = process.env.OUTPUT_FORMAT;
-    process.env.OUTPUT_FORMAT = toDesignSystemOutput(output);
-    resetOutputFormatCache();
-    try {
-        return await fn();
-    }
-    finally {
-        if (previous === undefined) {
-            delete process.env.OUTPUT_FORMAT;
-        }
-        else {
-            process.env.OUTPUT_FORMAT = previous;
-        }
-        resetOutputFormatCache();
-    }
-}
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -2159,20 +2333,22 @@ function validatePresetScalarValue(value, schema, fieldPath, presetPath) {
         return null;
     }
     switch (schema.kind) {
-        case "string":
+        case "string": {
             if (typeof value !== "string") {
                 break;
             }
-            if (schema.minLength !== undefined && value.length < schema.minLength) {
-                throw new UserError(`Preset file "${presetPath}" has an invalid value for "${fieldPath}". Expected a string with length at least ${schema.minLength}, got string with length ${value.length}.`);
+            const length = unicodeLength(value);
+            if (schema.minLength !== undefined && length < schema.minLength) {
+                throw new UserError(`Preset file "${presetPath}" has an invalid value for "${fieldPath}". Expected a string with length at least ${schema.minLength}, got string with length ${length}.`);
             }
-            if (schema.maxLength !== undefined && value.length > schema.maxLength) {
-                throw new UserError(`Preset file "${presetPath}" has an invalid value for "${fieldPath}". Expected a string with length at most ${schema.maxLength}, got string with length ${value.length}.`);
+            if (schema.maxLength !== undefined && length > schema.maxLength) {
+                throw new UserError(`Preset file "${presetPath}" has an invalid value for "${fieldPath}". Expected a string with length at most ${schema.maxLength}, got string with length ${length}.`);
             }
             if (schema.pattern !== undefined && !matchesStringPattern(value, schema.pattern)) {
                 throw new UserError(`Preset file "${presetPath}" has an invalid value for "${fieldPath}": "${value}" does not match pattern "${schema.pattern}".`);
             }
             return value;
+        }
         case "number":
             if (!isValidNumberSchemaValue(value, schema)) {
                 break;
@@ -2200,6 +2376,9 @@ function validatePresetFieldValue(value, field, presetPath) {
     if (field.schema.kind !== "array") {
         return validatePresetScalarValue(value, field.schema, field.displayPath, presetPath);
     }
+    if (value === null && field.schema.nullable === true) {
+        return null;
+    }
     const itemSchema = unwrapOptional(field.schema.item);
     if (itemSchema.kind === "array" || itemSchema.kind === "object") {
         throw new UserError(`Array parameter "${field.displayPath}" must use scalar items.`);
@@ -2215,7 +2394,7 @@ function validatePresetFieldValue(value, field, presetPath) {
     }
     return value.map((item) => validatePresetScalarValue(item, itemSchema, field.displayPath, presetPath));
 }
-async function loadPresetValues(fields, presetPath) {
+async function loadPresetValues(fields, dynamicFields, presetPath) {
     let rawPreset;
     try {
         rawPreset = await readFile(presetPath, {
@@ -2242,7 +2421,10 @@ async function loadPresetValues(fields, presetPath) {
         throw new UserError(`Preset file "${presetPath}" must contain a JSON object.`);
     }
     const fieldByPath = new Map(fields.map((field) => [field.displayPath, field]));
+    const dynamicFieldByPath = new Map(dynamicFields.map((field) => [field.displayPath, field]));
+    const allFields = [...fields, ...dynamicFields];
     const presetValues = {};
+    const dynamicValues = new Map();
     function visitObject(current, path) {
         for (const [key, value] of Object.entries(current)) {
             const nextPath = [...path, key];
@@ -2252,7 +2434,18 @@ async function loadPresetValues(fields, presetPath) {
                 presetValues[field.optionAttribute] = validatePresetFieldValue(value, field, presetPath);
                 continue;
             }
-            if (!hasNestedField(fields, nextPath)) {
+            const dynamicField = dynamicFieldByPath.get(displayPath);
+            if (dynamicField !== undefined) {
+                const validation = validateSchema(dynamicField.schema, value, { defaults: "all" });
+                if (!validation.ok) {
+                    const issue = validation.issues[0];
+                    const issuePath = [displayPath, ...issue.path].join(".");
+                    throw new UserError(`Preset file "${presetPath}" has an invalid value for "${issuePath}". ${issue.message}`);
+                }
+                dynamicValues.set(dynamicField.id, validation.value);
+                continue;
+            }
+            if (!hasNestedField(allFields, nextPath)) {
                 throw new UserError(`Preset file "${presetPath}" contains unknown parameter "${displayPath}".`);
             }
             if (!isPlainObject(value)) {
@@ -2262,7 +2455,7 @@ async function loadPresetValues(fields, presetPath) {
         }
     }
     visitObject(parsedPreset, []);
-    return presetValues;
+    return { fields: presetValues, dynamic: dynamicValues };
 }
 function isNumericFixtureSelector(value) {
     if (value.length === 0) {
@@ -2576,15 +2769,16 @@ function isHumanInLoopPending(result) {
         typeof result.message === "string" &&
         typeof result.enqueuedAt === "string");
 }
-function renderHumanInLoopPending(pending, rootUsageName) {
-    process.stdout.write(`✓ Queued for human approval (id: ${pending.approvalId})\n` +
+function renderHumanInLoopPending(pending, rootUsageName, outputEmitter) {
+    const message = `✓ Queued for human approval (id: ${pending.approvalId})\n` +
         `  Message: ${pending.message}\n` +
-        `  Track:   ${rootUsageName} approvals show --approval-id ${pending.approvalId}\n`);
-}
-function renderApprovalDeclined(error) {
-    const logger = createLogger();
-    logger.error(error.message);
-    process.exitCode = 1;
+        `  Track:   ${rootUsageName} approvals show --approval-id ${pending.approvalId}`;
+    if (outputEmitter === undefined) {
+        process.stdout.write(`${message}\n`);
+    }
+    else {
+        outputEmitter(message);
+    }
 }
 function renderCliErrorPattern(pattern, outputEmitter) {
     const logger = createLogger(outputEmitter);
@@ -2633,7 +2827,7 @@ function renderCliErrorPattern(pattern, outputEmitter) {
     process.exitCode = 1;
 }
 function getNestedValue(target, path) {
-    return path.reduce((current, segment) => current !== null && typeof current === "object"
+    return path.reduce((current, segment) => current !== null && typeof current === "object" && Object.prototype.hasOwnProperty.call(current, segment)
         ? current[segment]
         : undefined, target);
 }
@@ -2800,6 +2994,10 @@ function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displa
                 : [qualifyDisplayPath(displayPathPrefix, toDisplayPath(displayPath))])}`);
     }
 }
+function formatFieldValidationIssue(issue, displayPath) {
+    const path = [displayPath, ...issue.path].filter((part) => part !== "").join(".") || "parameters";
+    return { path, message: `Invalid value for "${path}". ${issue.message}` };
+}
 function finalizeDynamicValue(schema, value, displayPath, errors) {
     const unwrappedSchema = unwrapOptional(schema);
     if (value === undefined) {
@@ -2813,8 +3011,14 @@ function finalizeDynamicValue(schema, value, displayPath, errors) {
         case "number":
         case "boolean":
         case "enum":
-        case "json":
             return value;
+        case "json": {
+            const validation = validateSchema(unwrappedSchema, value);
+            if (!validation.ok) {
+                errors.push(...validation.issues.map((issue) => formatFieldValidationIssue(issue, displayPath)));
+            }
+            return value;
+        }
         case "array": {
             const itemSchema = unwrapOptional(unwrappedSchema.item);
             if (itemSchema.kind !== "object") {
@@ -2862,7 +3066,7 @@ function finalizeDynamicValue(schema, value, displayPath, errors) {
                 const childDisplayPath = displayPath.length === 0 ? key : `${displayPath}.${key}`;
                 if (childValue === undefined) {
                     if (childSchema.default !== undefined) {
-                        result[key] = childSchema.default;
+                        result[key] = cloneDefaultValue(childSchema.default);
                         continue;
                     }
                     if (rawChildSchema.kind === "optional") {
@@ -2903,7 +3107,7 @@ 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.`;
+    return `Unsupported CLI argument shape for "${displayPath}" (type "${kind}").`;
 }
 function qualifyDisplayPath(prefix, displayPath) {
     if (prefix.length === 0) {
@@ -2914,13 +3118,38 @@ function qualifyDisplayPath(prefix, displayPath) {
     }
     return `${prefix}.${displayPath}`;
 }
+function resolveDynamicOption(dynamicFields, flagName, casing) {
+    const flagPath = flagName.split(".");
+    const match = [...dynamicFields]
+        .sort((left, right) => right.optionPath.length - left.optionPath.length)
+        .find((field) => {
+        const optionPath = field.optionPath.map((segment) => formatSegment(segment, casing));
+        return flagPath.length > optionPath.length &&
+            optionPath.every((segment, index) => flagPath[index] === segment);
+    });
+    if (match === undefined) {
+        return undefined;
+    }
+    return {
+        match,
+        leaf: resolveDynamicLeaf(match.schema, flagPath.slice(match.optionPath.length), casing, [], [], match.displayPath)
+    };
+}
 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);
+    const positionals = [];
     for (let index = 0; index < rawArgv.length; index += 1) {
         const token = rawArgv[index] ?? "";
+        if (token === "--") {
+            positionals.push(...rawArgv.slice(index + 1));
+            break;
+        }
         if (!token.startsWith("--")) {
+            if (token.length > 1 && token.startsWith("-") && !isNegativeNumericToken(token)) {
+                throw new UserError(`Unknown option "${token}".`);
+            }
+            positionals.push(token);
             continue;
         }
         const negated = token.startsWith("--no-");
@@ -2928,18 +3157,11 @@ function parseDynamicValues(dynamicFields, rawArgv, casing, errors) {
         const equalsIndex = normalized.indexOf("=");
         const flagName = equalsIndex >= 0 ? normalized.slice(2, equalsIndex) : normalized.slice(2);
         const inlineValue = equalsIndex >= 0 ? normalized.slice(equalsIndex + 1) : undefined;
-        const flagPath = flagName.split(".");
-        const match = sortedFields.find((field) => {
-            const optionPath = field.optionPath.map((segment) => formatSegment(segment, casing));
-            return (flagPath.length > optionPath.length &&
-                optionPath.every((segment, segmentIndex) => flagPath[segmentIndex] === segment));
-        });
-        if (match === undefined) {
+        const dynamic = resolveDynamicOption(dynamicFields, flagName, casing);
+        if (dynamic === undefined) {
             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, [], [], match.displayPath);
+        const { match, leaf } = dynamic;
         const rawStore = rawValues.get(match.id) ?? {};
         const label = `${match.displayPath}.${leaf.displayPath}`.replace(/^\./u, "");
         const parsed = negated && leaf.schema.kind === "boolean"
@@ -2955,6 +3177,7 @@ function parseDynamicValues(dynamicFields, rawArgv, casing, errors) {
     }
     return {
         providedFieldIds,
+        positionals,
         values: new Map(dynamicFields
             .filter((field) => rawValues.has(field.id))
             .map((field) => [
@@ -2963,9 +3186,10 @@ function parseDynamicValues(dynamicFields, rawArgv, casing, errors) {
         ]))
     };
 }
-async function enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, providedDynamicFieldIds, providedFieldIds, shouldPrompt, errors) {
+async function enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, providedDynamicFieldIds, providedFieldIds, shouldPrompt, errors, promptStreams) {
     const fieldById = new Map(fields.map((field) => [field.id, field]));
     const dynamicFieldById = new Map(dynamicFields.map((field) => [field.id, field]));
+    const activeBranches = new Map();
     const getAvailableBranchParameters = (branch) => [
         ...branch.fieldIds
             .map((fieldId) => fieldById.get(fieldId))
@@ -2977,12 +3201,16 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
             .map((field) => field.optionPathDisplay)
     ];
     for (const variant of variants) {
+        if (variant.parent !== undefined && activeBranches.get(variant.parent.id) !== variant.parent.branchId) {
+            continue;
+        }
         let selectedBranchId = resolvedFieldValues.get(variant.controlFieldId);
         if (selectedBranchId === undefined && shouldPrompt) {
             const controlField = fieldById.get(variant.controlFieldId);
             if (controlField !== undefined) {
-                selectedBranchId = await promptForField(controlField);
+                selectedBranchId = await promptForField(controlField, promptStreams);
                 resolvedFieldValues.set(controlField.id, selectedBranchId);
+                providedFieldIds.add(controlField.id);
                 if (!controlField.synthetic) {
                     setNestedValue(params, controlField.path, selectedBranchId);
                 }
@@ -3037,16 +3265,33 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
         if (hasInvalidBranchParameter) {
             continue;
         }
+        activeBranches.set(variant.id, selectedBranch.branchId);
+        for (const fieldId of selectedBranch.fieldIds) {
+            const field = fieldById.get(fieldId);
+            if (field?.variantId !== variant.id || !field.hasDefault || getNestedValue(params, field.path) !== undefined) {
+                continue;
+            }
+            const value = cloneDefaultValue(field.defaultValue);
+            resolvedFieldValues.set(field.id, value);
+            setNestedValue(params, field.path, value);
+        }
+        for (const fieldId of selectedBranch.dynamicFieldIds) {
+            const field = dynamicFieldById.get(fieldId);
+            if (field?.variantId !== variant.id || !field.hasDefault || getNestedValue(params, field.path) !== undefined) {
+                continue;
+            }
+            setNestedValue(params, field.path, cloneDefaultValue(field.defaultValue));
+        }
         for (const fieldId of selectedBranch.requiredFieldIds) {
             const field = fieldById.get(fieldId);
-            if (field === undefined || field.synthetic) {
+            if (field?.variantId !== variant.id || field.synthetic) {
                 continue;
             }
             if (getNestedValue(params, field.path) !== undefined) {
                 continue;
             }
             if (shouldPrompt) {
-                const promptedValue = await promptForField(field);
+                const promptedValue = await promptForField(field, promptStreams);
                 resolvedFieldValues.set(field.id, promptedValue);
                 setNestedValue(params, field.path, promptedValue);
                 providedFieldIds.add(field.id);
@@ -3059,7 +3304,7 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
         }
         for (const fieldId of selectedBranch.requiredDynamicFieldIds) {
             const field = dynamicFieldById.get(fieldId);
-            if (field === undefined) {
+            if (field?.variantId !== variant.id) {
                 continue;
             }
             if (getNestedValue(params, field.path) !== undefined) {
@@ -3074,18 +3319,27 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
 }
 async function resolveParams(fields, dynamicFields, variants, positionalValues, optionValues, rawArgv, casing, presetPath, shouldPrompt, missingParameterContext, promptStreams) {
     const params = {};
+    const errors = [];
+    const dynamicResults = parseDynamicValues(dynamicFields, rawArgv, casing, errors);
+    const positionalTokens = [...positionalValues, ...dynamicResults.positionals];
+    const positionalFields = fields.filter((field) => field.positionalIndex !== undefined);
+    if (!positionalFields.some((field) => field.variadicPosition === true) &&
+        positionalTokens.length > positionalFields.length) {
+        throw new UserError(`Unexpected arguments: ${positionalTokens.slice(positionalFields.length).map((token) => JSON.stringify(token)).join(", ")}.`);
+    }
     const presetValues = typeof presetPath === "string" && presetPath.length > 0
-        ? await loadPresetValues(fields, presetPath)
-        : {};
+        ? await loadPresetValues(fields, dynamicFields, presetPath)
+        : { fields: {}, dynamic: new Map() };
     const providedFieldIds = new Set();
     const resolvedFieldValues = new Map();
-    const errors = [];
     for (const field of fields) {
         let value;
         let resolvedMissing = false;
         let source;
         if (field.positionalIndex !== undefined) {
-            const positionalValue = positionalValues[field.positionalIndex];
+            const positionalValue = field.variadicPosition === true
+                ? positionalTokens.slice(field.positionalIndex)
+                : positionalTokens[field.positionalIndex];
             if (field.schema.kind === "array") {
                 if (Array.isArray(positionalValue) && positionalValue.length > 0) {
                     const itemSchema = unwrapOptional(field.schema.item);
@@ -3096,7 +3350,7 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
                     source = "positional";
                 }
             }
-            else if (typeof positionalValue === "string" && positionalValue.length > 0) {
+            else if (typeof positionalValue === "string") {
                 value = parseFieldInputValue(positionalValue, field.schema, field.displayPath);
                 source = "positional";
             }
@@ -3122,8 +3376,8 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             source = "option";
         }
         if (value === undefined &&
-            Object.prototype.hasOwnProperty.call(presetValues, field.optionAttribute)) {
-            value = presetValues[field.optionAttribute];
+            Object.prototype.hasOwnProperty.call(presetValues.fields, field.optionAttribute)) {
+            value = presetValues.fields[field.optionAttribute];
             source = "preset";
         }
         if (source === "option") {
@@ -3178,8 +3432,8 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             value = await promptForField(field, promptStreams);
             source = "prompt";
         }
-        if (value === undefined && field.hasDefault) {
-            value = field.defaultValue;
+        if (value === undefined && field.hasDefault && field.variantId === undefined) {
+            value = cloneDefaultValue(field.defaultValue);
             source = "default";
         }
         if (value === undefined) {
@@ -3192,6 +3446,14 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             });
             continue;
         }
+        if (field.schema.kind === "json") {
+            const validation = validateSchema(field.schema, value);
+            if (!validation.ok) {
+                errors.push(...validation.issues.map((issue) => formatFieldValidationIssue(issue, field.displayPath)));
+                continue;
+            }
+            value = validation.value;
+        }
         resolvedFieldValues.set(field.id, value);
         if (source !== undefined && source !== "default") {
             providedFieldIds.add(field.id);
@@ -3200,16 +3462,15 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             setNestedValue(params, field.path, value);
         }
     }
-    const dynamicResults = dynamicFields.length > 0
-        ? parseDynamicValues(dynamicFields, rawArgv, casing, errors)
-        : {
-            providedFieldIds: new Set(),
-            values: new Map()
-        };
     for (const field of dynamicFields) {
         let value = dynamicResults.values.get(field.id);
-        if (value === undefined && field.hasDefault) {
-            value = field.defaultValue;
+        if (presetValues.dynamic.has(field.id)) {
+            if (value === undefined)
+                value = presetValues.dynamic.get(field.id);
+            dynamicResults.providedFieldIds.add(field.id);
+        }
+        if (value === undefined && field.hasDefault && field.variantId === undefined) {
+            value = cloneDefaultValue(field.defaultValue);
         }
         if (value === undefined) {
             if (field.optional || field.variantId !== undefined) {
@@ -3223,17 +3484,24 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
         }
         setNestedValue(params, field.path, value);
     }
-    await enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, dynamicResults.providedFieldIds, providedFieldIds, shouldPrompt, errors);
+    await enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, dynamicResults.providedFieldIds, providedFieldIds, shouldPrompt, errors, promptStreams);
     throwValidationErrors(errors);
     return params;
 }
 function getResolvedFlags(command) {
-    const flags = command.optsWithGlobals();
+    const flags = {};
+    const commands = [];
+    for (let current = command; current !== null; current = current.parent) {
+        commands.unshift(current);
+    }
+    for (const current of commands) {
+        Object.assign(flags, current.opts());
+    }
     return flags;
 }
 async function executeCommand(state, rootUsageName, services, requirementOptions, runtimeFetch, humanInLoop, runtimeEnv, runtimeFs, outputEmitter, outputFormats, promptStreams, diagnosticsOptions, onErrorReportContext) {
     const logger = createLogger(outputEmitter);
-    const optionValues = state.actionCommand.optsWithGlobals();
+    const optionValues = getResolvedFlags(state.actionCommand);
     const resolvedFlags = optionValues;
     const output = resolveOutput(resolvedFlags);
     const primitives = {
@@ -3280,9 +3548,15 @@ async function executeCommand(state, rootUsageName, services, requirementOptions
     let runtimeSecrets;
     let resolvedParams;
     try {
-        await withOutputFormat(output, async () => {
+        await withOutputFormat(toDesignSystemOutput(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, missingParameterContext, promptStreams);
+            const paramsSchema = state.command.params;
+            if (paramsSchema !== undefined && paramsSchema[nativeJsonSchema] !== undefined) {
+                const validation = validateSchema(paramsSchema, params);
+                if (!validation.ok)
+                    throwValidationErrors(validation.issues.map((issue) => formatFieldValidationIssue(issue, "")));
+            }
             resolvedParams = params;
             runtimeSecrets = runtime.secrets;
             const context = {
@@ -3314,7 +3588,7 @@ async function executeCommand(state, rootUsageName, services, requirementOptions
                     }
                 });
                 const interrupt = () => {
-                    void stream.cancel(new UserError("Operation cancelled."));
+                    void stream.cancel(new UserError("Operation cancelled.")).catch(() => undefined);
                 };
                 process.once("SIGINT", interrupt);
                 try {
@@ -3343,8 +3617,7 @@ async function executeCommand(state, rootUsageName, services, requirementOptions
             }
             if (state.command.confirm &&
                 !state.command.humanInLoop &&
-                !resolvedFlags.yes &&
-                process.stdin.isTTY) {
+                shouldPrompt) {
                 for (const field of state.fields) {
                     const value = field.path.reduce((current, segment) => current && typeof current === "object"
                         ? current[segment]
@@ -3355,10 +3628,10 @@ async function executeCommand(state, rootUsageName, services, requirementOptions
                 }
                 const proceed = await confirm({
                     message: "Proceed?",
-                    initialValue: true
+                    initialValue: true,
+                    ...promptStreams
                 });
                 if (isCancel(proceed)) {
-                    cancel("Operation cancelled.");
                     throw new UserError("Operation cancelled.");
                 }
                 if (proceed !== true) {
@@ -3371,11 +3644,12 @@ async function executeCommand(state, rootUsageName, services, requirementOptions
             if (output === "rich" && runtime.isFixture) {
                 writeRichHeader(`${state.command.name} (fixture)`);
             }
-            if (isHumanInLoopPending(result)) {
-                renderHumanInLoopPending(result, rootUsageName);
+            const pendingApproval = isHumanInLoopPending(result);
+            if (pendingApproval && output === "rich") {
+                renderHumanInLoopPending(result, rootUsageName, outputEmitter);
                 return;
             }
-            const renderStatus = renderCLIResult(state.command, state.commandPath, result, output, primitives, outputFormats, outputEmitter === undefined
+            const renderStatus = renderCLIResult(pendingApproval ? { ...state.command, render: undefined } : state.command, state.commandPath, result, output, primitives, outputFormats, outputEmitter === undefined
                 ? undefined
                 : (chunk) => outputEmitter(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk), outputEmitter);
             if (renderStatus.mcpError) {
@@ -3610,7 +3884,7 @@ function renderHttpError(error, options) {
 }
 async function handleRunError(error, options) {
     const logger = createLogger(options.outputEmitter);
-    await withOutputFormat(options.output, async () => {
+    await withOutputFormat(toDesignSystemOutput(options.output), async () => {
         if (isUserError(error)) {
             renderCliErrorPattern(options.userErrorPattern === "definition"
                 ? {
@@ -3910,26 +4184,30 @@ function getDefaultCommanderCommandName(command) {
         ? candidate._defaultCommandName
         : undefined;
 }
-function configureCommanderSuggestionOutput(command) {
+function configureCommanderSuggestionOutput(command, version) {
     command.exitOverride();
+    command.enablePositionalOptions();
+    command.helpOption(false);
+    if (version !== undefined && !command.options.some((option) => option.long === "--version")) {
+        command.version(version, "--version");
+    }
     command.configureOutput({
         // Every Commander error throws through exitOverride and is rendered once by handleRunError
         // in the design-system error pattern; writing it here as well double-reports one mistake.
         outputError: () => { }
     });
-    command.commands.forEach((child) => configureCommanderSuggestionOutput(child));
+    command.commands.forEach((child) => configureCommanderSuggestionOutput(child, version));
 }
 export async function runCLI(roots, options = {}) {
     enableSourceMaps();
     const controls = resolveCLIControls(options.controls);
-    const argv = controls.verbose
-        ? normalizeVerboseAlias([...(options.argv ?? process.argv)])
-        : [...(options.argv ?? process.argv)];
+    let argv = [...(options.argv ?? process.argv)];
     const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
     let lastActionCommand;
     let resolvedCommandPath = "";
     let program;
     let version;
+    let proxyCleanup;
     let userErrorPattern = "definition";
     let errorReportContext;
     try {
@@ -3937,7 +4215,9 @@ export async function runCLI(roots, options = {}) {
         const root = mergeApprovalsRoot(normalizedRoot, options);
         assertHumanInLoopWired(root, options.humanInLoop);
         if (hasMcpProxyConfig(root)) {
-            await (await importOptionalModule(optionalModulePaths.mcpProxy)).resolveMcpProxies(root, { projectRoot: options.projectRoot });
+            const proxyRuntime = await importOptionalModule(optionalModulePaths.mcpProxy);
+            await proxyRuntime.resolveMcpProxies(root, { projectRoot: options.projectRoot });
+            proxyCleanup = { dispose: proxyRuntime.disposeMcpProxies, root };
         }
         const casing = options.casing ?? "kebab";
         const services = (options.services ?? {});
@@ -3954,11 +4234,6 @@ export async function runCLI(roots, options = {}) {
             env: options.env
         };
         validateServices(services);
-        if (hasHelpFlag(argv)) {
-            userErrorPattern = "usage";
-            await renderGeneratedHelp(root, argv, { ...options, version });
-            return;
-        }
         if (argv.length <= 2 && root.default?.scope.includes("cli") !== true) {
             userErrorPattern = "usage";
             await renderGeneratedHelp(root, argv, { ...options, version });
@@ -3971,6 +4246,7 @@ export async function runCLI(roots, options = {}) {
         program.addHelpCommand(false);
         const presetsEnabled = options.presets === true;
         const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled, version !== undefined, controls);
+        const fieldLoaders = new Map();
         addGlobalOptions(program, presetsEnabled, controls);
         if (version !== undefined) {
             program.version(version, "--version");
@@ -3996,7 +4272,7 @@ export async function runCLI(roots, options = {}) {
             .filter((candidate) => isNodeVisibleInScope(candidate, "cli"))
             .map((candidate) => candidate.name));
         for (const child of root.children) {
-            const command = createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled, controls);
+            const command = createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled, controls, fieldLoaders);
             if (command === null) {
                 continue;
             }
@@ -4005,25 +4281,42 @@ export async function runCLI(roots, options = {}) {
                 (command.name() === root.default.name || command.aliases().includes(root.default.name));
             addCommanderChild(program, command, isDefaultChild, rootChildNames);
         }
-        configureCommanderSuggestionOutput(program);
+        configureCommanderSuggestionOutput(program, version);
+        const prepared = prepareCliArguments(program, argv, fieldLoaders, casing, controls);
+        argv = prepared.argv;
+        if (prepared.helpArgv !== undefined) {
+            userErrorPattern = "usage";
+            await renderGeneratedHelp(root, prepared.helpArgv, { ...options, version });
+            return;
+        }
+        for (const loadFields of fieldLoaders.values()) {
+            loadFields();
+        }
         const unknownCommand = findUnknownCommanderCommand(program, argv);
         if (unknownCommand !== undefined) {
-            createLogger().error(appendUsagePointer(formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand), {
-                rootUsageName,
-                commandPath: unknownCommand.commandPath
-            }));
-            process.exitCode = 1;
+            await withOutputFormat(toDesignSystemOutput(resolveOutputFromArgv(argv, controls.outputFormats)), async () => {
+                renderCliErrorPattern({
+                    kind: "usage",
+                    message: formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand),
+                    rootUsageName,
+                    commandPath: unknownCommand.commandPath
+                }, options.outputEmitter);
+            });
             return;
         }
         userErrorPattern = "usage";
         await program.parseAsync(argv);
     }
     catch (error) {
+        const resolvedFlags = lastActionCommand ? getResolvedFlags(lastActionCommand) : undefined;
         if (error instanceof ApprovalDeclinedError) {
-            renderApprovalDeclined(error);
+            await withOutputFormat(toDesignSystemOutput(resolvedFlags !== undefined
+                ? resolveOutput(resolvedFlags)
+                : resolveOutputFromArgv(argv, controls.outputFormats)), async () => {
+                renderCliErrorPattern({ kind: "runtime-user", message: error.message }, options.outputEmitter);
+            });
             return;
         }
-        const resolvedFlags = lastActionCommand ? getResolvedFlags(lastActionCommand) : undefined;
         const report = await writeErrorReport({
             argv,
             command: errorReportContext?.command,
@@ -4059,4 +4352,15 @@ export async function runCLI(roots, options = {}) {
             userErrorPattern: errorReportContext?.params === undefined ? userErrorPattern : "runtime-user"
         });
     }
+    finally {
+        if (proxyCleanup !== undefined) {
+            try {
+                await proxyCleanup.dispose(proxyCleanup.root);
+            }
+            catch (error) {
+                process.exitCode = 1;
+                process.stderr.write(`Failed to close MCP proxy connections: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
+    }
 }