@kamilio/wire 0.1.9 → 0.1.10

package/node_modules/toolcraft/dist/cli.js

@@ -1,13 +1,13 @@
-import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
+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 { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
-import { ApprovalDeclinedError, UserError, assertCommandRequirements, getCommandSourcePath, resolveCommandSecrets } from "./index.js";
+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 { 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 { assertHumanInLoopWired, mergeApprovalsRoot } from "./human-in-loop/wiring.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
 import { findEntrypointPackageMetadata } from "./package-metadata.js";
 import { redactHttpBody, redactHttpHeaderValue } from "./redaction.js";
@@ -18,21 +18,39 @@ import { renderSourceSnippet } from "./source-snippet.js";
 import { enableSourceMaps, formatDebugStack } from "./stack-trim.js";
 import { suggest } from "./suggest.js";
 import { throwValidationErrors } from "./validation-errors.js";
+import { RESERVED_SERVICE_NAMES, createEnv, createFs, validateServices } from "./runtime/io.js";
+import { createManagedStream } from "./stream.js";
+export { renderErrorReport } from "./error-report.js";
 configureTheme({ brand: "blue", label: "Toolcraft" });
 export { configureTheme };
-const RESERVED_SERVICE_NAMES = new Set([
-    "params",
-    "secrets",
-    "fetch",
-    "fs",
-    "env",
-    "diagnostics",
-    "progress",
-    "runtimeOptions",
-    "root"
-]);
-const RESERVED_SERVICE_NAMES_MESSAGE = "Available reserved names: params, secrets, fetch, fs, env, diagnostics, progress, runtimeOptions, root.";
 const NULL_OPTION_VALUE = Symbol("toolcraft.cli.null");
+const optionalModulePaths = {
+    mcpProxy: "./mcp-proxy.js"
+};
+function importOptionalModule(specifier) {
+    return import(specifier);
+}
+/**
+ * Returns the resolved CLI command surface as deterministic plain data.
+ *
+ * Schema version 1 is independent of human-facing help layout. Nodes and options retain
+ * declaration order, paths exclude the root name, non-CLI nodes are omitted, hidden commands
+ * remain present, and Toolcraft-controlled global options are reported separately. A future
+ * incompatible shape change will increment `schemaVersion`.
+ */
+export async function createCLICommandTreeSnapshot(roots, options = {}) {
+    const argv = [...(options.argv ?? ["node", "toolcraft"])];
+    const normalizedRoot = normalizeRoots(roots, argv);
+    const root = mergeApprovalsRoot(normalizedRoot, options);
+    const controls = resolveCLIControls(options.controls);
+    const presetsEnabled = options.presets === true;
+    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled, options.version !== undefined, controls);
+    return {
+        schemaVersion: 1,
+        globalOptions: createGlobalSnapshotOptions(presetsEnabled, options.version !== undefined, controls),
+        root: createSnapshotGroup(root, options.casing ?? "kebab", globalLongOptionFlags, [], false)
+    };
+}
 function inferProgramName(argv) {
     const entrypoint = argv[1];
     if (typeof entrypoint !== "string" || entrypoint.length === 0) {
@@ -94,17 +112,18 @@ function splitWords(value) {
     }
     return words;
 }
-function formatSegment(segment, casing) {
+/** @internal */
+export function formatCLIName(segment, casing) {
     const separator = casing === "snake" ? "_" : "-";
     return splitWords(segment).join(separator);
 }
 function toOptionFlag(path, casing) {
-    return `--${path.map((segment) => formatSegment(segment, casing)).join(".")}`;
+    return `--${path.map((segment) => formatCLIName(segment, casing)).join(".")}`;
 }
 function toOptionAttribute(path, casing) {
     return path
         .map((segment) => {
-        const formatted = formatSegment(segment, casing);
+        const formatted = formatCLIName(segment, casing);
         if (casing === "snake") {
             return formatted;
         }
@@ -146,7 +165,7 @@ function createSyntheticEnumSchema(values) {
 function getRequiredBranchFingerprint(branch, casing) {
     const requiredKeys = Object.entries(branch.shape)
         .filter(([, schema]) => schema.kind !== "optional")
-        .map(([key]) => formatSegment(key, casing))
+        .map(([key]) => formatCLIName(key, casing))
         .sort();
     return requiredKeys.join("+");
 }
@@ -185,10 +204,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,
@@ -209,20 +238,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,
@@ -238,10 +268,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, {
@@ -263,13 +303,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") {
@@ -320,7 +353,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
             longAliases: [...(childSchema.cliAliases ?? [])].map((alias) => alias.startsWith("--") ? alias : `--${alias}`),
             shortFlag: childSchema.short,
             schema: childSchema,
-            description: childSchema.description,
+            description: childSchema.cliDescription ?? childSchema.description,
             optional: runtimeOptional,
             hasDefault: childSchema.default !== undefined,
             defaultValue: childSchema.default,
@@ -378,6 +411,13 @@ function formatOptionFlags(field, globalLongOptionFlags) {
     }
     return [`-${field.shortFlag}`, field.optionFlag, ...field.longAliases].join(", ");
 }
+function formatMissingParameterMessage(field) {
+    const message = `Missing required parameter "${field.displayPath}".`;
+    if (field.schema.kind !== "enum") {
+        return message;
+    }
+    return `${message} Expected one of: ${field.schema.values.map((value) => String(value)).join(", ")}.`;
+}
 function formatPositionalToken(field) {
     const optionalPositional = field.optional || field.hasDefault;
     if (field.variadicPosition === true) {
@@ -393,23 +433,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}".`);
@@ -424,7 +465,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) {
@@ -548,8 +589,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;
         }
@@ -591,19 +632,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) {
-    return token.startsWith("-") && !isNegativeNumericArrayToken(token, schema);
+    if (token === "-" && unwrapOptional(schema.item).kind === "string") {
+        return false;
+    }
+    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) {
@@ -614,41 +702,69 @@ 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)
-        ];
-    }
-    if (field.schema.kind === "array") {
-        return [
-            createCommanderOption(`${flags} <value...>`, field.description, field).argParser((value, previous = []) => [...previous, value])
+    const flagGroups = collidesWithGlobalFlag
+        ? [formatOptionFlags(field, globalLongOptionFlags)]
+        : [
+            field.shortFlag === undefined ? field.optionFlag : `-${field.shortFlag}, ${field.optionFlag}`,
+            ...field.longAliases
         ];
-    }
-    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 ?? {}) : {};
+    validateOutputFormats(outputFormats);
     return {
         debug: controls?.debug === true,
+        help: controls?.help === "concise" ? "concise" : "extended",
         logLevel: controls?.logLevel === true,
-        output: controls?.output === true,
+        output: controls?.output === true || typeof controls?.output === "object",
+        outputFormats,
         verbose: controls?.verbose === true,
         yes: controls?.yes === true
     };
 }
+const BUILT_IN_OUTPUT_FORMATS = ["rich", "md", "markdown", "json"];
+function outputFormatNames(controls) {
+    return [...BUILT_IN_OUTPUT_FORMATS, ...Object.keys(controls.outputFormats)];
+}
+function validateOutputFormats(formats) {
+    for (const [name, renderer] of Object.entries(formats)) {
+        const hasWhitespace = name.split("").some((character) => character.trim() === "");
+        if (name.length === 0 || name.trim() !== name || hasWhitespace) {
+            throw new ToolcraftBugError(`Custom output format names must be non-empty and contain no whitespace: ${JSON.stringify(name)}.`);
+        }
+        if (BUILT_IN_OUTPUT_FORMATS.includes(name)) {
+            throw new ToolcraftBugError(`Custom output format "${name}" conflicts with a built-in format.`);
+        }
+        if (typeof renderer !== "function") {
+            throw new ToolcraftBugError(`Custom output format "${name}" must define a renderer function.`);
+        }
+    }
+}
 function getGlobalLongOptionFlags(presetsEnabled, versionEnabled, controls) {
     const flags = [];
     if (presetsEnabled) {
@@ -702,11 +818,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) {
@@ -804,13 +1010,44 @@ function appendHelpMetadata(description, metadata) {
         return description;
     }
     if (description.length === 0) {
-        return `(${metadata.join(", ")})`;
+        return metadata.map((entry) => `(${entry})`).join(" ");
     }
-    return `${description} (${metadata.join(", ")})`;
+    return `${description} ${metadata.map((entry) => `(${entry})`).join(" ")}`;
+}
+function normalizeHelpEchoKey(value) {
+    let normalized = "";
+    for (const character of value.trim().toLowerCase()) {
+        if (character !== " " &&
+            character !== "\t" &&
+            character !== "\n" &&
+            character !== "\r" &&
+            character !== "_" &&
+            character !== "." &&
+            character !== "-") {
+            normalized += character;
+        }
+    }
+    return normalized;
+}
+function isEchoHelpDescription(description, name) {
+    if (description.length === 0) {
+        return false;
+    }
+    return normalizeHelpEchoKey(description) === normalizeHelpEchoKey(name);
+}
+function suppressEchoHelpDescription(description, name) {
+    return isEchoHelpDescription(description, name) ? "" : description;
 }
 function formatHelpFieldDescription(field) {
-    const description = field.description ?? field.displayPath;
+    const rawDescription = field.description ?? field.displayPath;
+    const description = suppressEchoHelpDescription(rawDescription, field.displayPath);
     const metadata = [];
+    if (field.schema.kind === "enum" && field.schema.values.length <= 8) {
+        const values = field.schema.values.map((value) => String(value)).join(", ");
+        if (values.length <= 120) {
+            metadata.push(`values: ${values}`);
+        }
+    }
     if (!field.optional && !field.hasDefault) {
         metadata.push("required");
     }
@@ -960,53 +1197,55 @@ function formatDynamicHelpMetadata(field) {
     }
     return metadata;
 }
+function createHelpOptionRow(flags, description) {
+    return {
+        flags,
+        flagTokens: tokenizeHelpFlags(flags),
+        description
+    };
+}
 function collectDynamicObjectHelpRows(schema, casing, optionPrefix, displayPrefix, metadata) {
     const rows = [];
     for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
         const childSchema = unwrapOptional(rawChildSchema);
-        const optionFlag = `${optionPrefix}.${formatSegment(key, casing)}`;
+        const optionFlag = `${optionPrefix}.${formatCLIName(key, casing)}`;
         const displayPath = `${displayPrefix}.${key}`;
-        const description = childSchema.description ?? displayPath;
+        const rawDescription = childSchema.description ?? displayPath;
+        const description = suppressEchoHelpDescription(rawDescription, displayPath);
         if (childSchema.kind === "object") {
             rows.push(...collectDynamicObjectHelpRows(childSchema, casing, optionFlag, displayPath, metadata));
             continue;
         }
         if (childSchema.kind === "record") {
-            rows.push({
-                flags: `${optionFlag}.<key> <${describeDynamicFieldType({
-                    ...{
-                        id: displayPath,
-                        path: [],
-                        displayPath,
-                        optionPath: [],
-                        optionPathDisplay: `${displayPath}.<key>`,
-                        optionFlag: `${optionFlag}.<key>`,
-                        optional: false,
-                        hasDefault: false,
-                        defaultValue: undefined,
-                        requiredWhenActive: false,
-                        schema: childSchema
-                    }
-                })}>`,
-                description: appendHelpMetadata(description, metadata)
-            });
+            rows.push(createHelpOptionRow(`${optionFlag}.<key> <${describeDynamicFieldType({
+                ...{
+                    id: displayPath,
+                    path: [],
+                    displayPath,
+                    optionPath: [],
+                    optionPathDisplay: `${displayPath}.<key>`,
+                    optionFlag: `${optionFlag}.<key>`,
+                    optional: false,
+                    hasDefault: false,
+                    defaultValue: undefined,
+                    requiredWhenActive: false,
+                    schema: childSchema
+                }
+            })}>`, appendHelpMetadata(description, metadata)));
             continue;
         }
         if (childSchema.kind === "array" && unwrapOptional(childSchema.item).kind === "object") {
             rows.push(...collectDynamicObjectHelpRows(unwrapOptional(childSchema.item), casing, `${optionFlag}.<index>`, `${displayPath}.<index>`, metadata));
             continue;
         }
-        rows.push({
-            flags: childSchema.kind === "boolean"
-                ? childSchema.default === true
-                    ? `--no-${optionFlag.slice(2)}`
-                    : optionFlag
-                : `${optionFlag} <${describeHelpValueToken(childSchema, {
-                    displayPath,
-                    optionFlag
-                })}>`,
-            description: appendHelpMetadata(description, metadata)
-        });
+        rows.push(createHelpOptionRow(childSchema.kind === "boolean"
+            ? childSchema.default === true
+                ? `--no-${optionFlag.slice(2)}`
+                : optionFlag
+            : `${optionFlag} <${describeHelpValueToken(childSchema, {
+                displayPath,
+                optionFlag
+            })}>`, appendHelpMetadata(description, metadata)));
     }
     return rows;
 }
@@ -1025,17 +1264,11 @@ function formatDynamicHelpFields(field, casing) {
         }
     }
     return [
-        {
-            flags: `${field.optionFlag} <${describeDynamicFieldType(field)}>`,
-            description: appendHelpMetadata(field.description ?? field.optionPathDisplay, metadata)
-        }
+        createHelpOptionRow(`${field.optionFlag} <${describeDynamicFieldType(field)}>`, appendHelpMetadata(suppressEchoHelpDescription(field.description ?? field.optionPathDisplay, field.optionPathDisplay), metadata))
     ];
 }
 function formatSecretRows(secrets) {
-    return Object.values(secrets).map((secret) => ({
-        flags: secret.env,
-        description: formatSecretDescription(secret)
-    }));
+    return Object.values(secrets).map((secret) => createHelpOptionRow(secret.env, formatSecretDescription(secret)));
 }
 function formatSecretDescription(secret) {
     if (secret.description !== undefined && secret.description.length > 0) {
@@ -1064,34 +1297,160 @@ function formatExampleCommand(breadcrumb, rootUsageName, params) {
 function formatExampleRows(examples, breadcrumb, rootUsageName) {
     return examples.map((example) => `${example.title}\n  ${formatExampleCommand(breadcrumb, rootUsageName, example.params)}`);
 }
-function wrapOptionalCommandParameterToken(token, optional) {
-    return optional ? `[${token}]` : token;
+const MAX_INLINE_OPTIONAL_PARAMETER_TOKENS = 8;
+/** Mirrors the fallback width used by the design system's column layout. */
+const DEFAULT_HELP_TOTAL_WIDTH = 100;
+function tokenizeHelpFlags(flags) {
+    const tokens = [];
+    let index = 0;
+    while (index < flags.length) {
+        if (flags[index] === " ") {
+            let end = index + 1;
+            while (end < flags.length && flags[end] === " ") {
+                end += 1;
+            }
+            tokens.push({ text: flags.slice(index, end), role: "literal" });
+            index = end;
+            continue;
+        }
+        if (flags[index] === "[" || flags[index] === "]") {
+            tokens.push({ text: flags[index], role: "dim" });
+            index += 1;
+            continue;
+        }
+        if (flags[index] === "<") {
+            const close = flags.indexOf(">", index);
+            if (close === -1) {
+                tokens.push({ text: flags.slice(index), role: "literal" });
+                break;
+            }
+            tokens.push({ text: flags.slice(index, close + 1), role: "argument" });
+            index = close + 1;
+            continue;
+        }
+        if (flags.startsWith("--", index) ||
+            (flags[index] === "-" && flags[index + 1] !== undefined && flags[index + 1] !== "-")) {
+            let end = index + 1;
+            while (end < flags.length &&
+                flags[end] !== " " &&
+                flags[end] !== "[" &&
+                flags[end] !== "]" &&
+                flags[end] !== "<") {
+                end += 1;
+            }
+            tokens.push({ text: flags.slice(index, end), role: "option" });
+            index = end;
+            continue;
+        }
+        // Enum literals (a|b) or bare words after a flag.
+        let end = index + 1;
+        while (end < flags.length &&
+            flags[end] !== " " &&
+            flags[end] !== "[" &&
+            flags[end] !== "]" &&
+            flags[end] !== "<") {
+            end += 1;
+        }
+        const piece = flags.slice(index, end);
+        tokens.push({
+            text: piece,
+            role: piece.includes("|") ? "literal" : piece.startsWith("+") ? "dim" : "literal"
+        });
+        index = end;
+    }
+    return tokens;
+}
+function wrapOptionalParameterTokens(tokens, optional) {
+    if (!optional) {
+        return tokens;
+    }
+    return [{ text: "[", role: "dim" }, ...tokens, { text: "]", role: "dim" }];
+}
+function createCommandParameterToken(text, optional) {
+    return {
+        text: optional ? `[${text}]` : text,
+        optional,
+        tokens: wrapOptionalParameterTokens(tokenizeHelpFlags(text), optional)
+    };
 }
 function formatCommandDynamicParameterTokens(field, casing) {
     const optional = field.optional || field.hasDefault;
-    return formatDynamicHelpFields(field, casing).map((row) => wrapOptionalCommandParameterToken(row.flags, optional));
+    return formatDynamicHelpFields(field, casing).map((row) => createCommandParameterToken(row.flags, optional));
 }
 function formatCommandParameterTokens(command, casing, globalLongOptionFlags) {
     const collected = collectFields(command.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, command.positional);
     return fields
         .filter((field) => field.global !== true)
-        .map((field) => wrapOptionalCommandParameterToken(formatCommandParameterFieldFlags(field, globalLongOptionFlags), field.positionalIndex === undefined && (field.optional || field.hasDefault)))
+        .map((field) => createCommandParameterToken(formatCommandParameterFieldFlags(field, globalLongOptionFlags), field.positionalIndex === undefined && (field.optional || field.hasDefault)))
         .concat(collected.dynamicFields.flatMap((field) => formatCommandDynamicParameterTokens(field, casing)));
 }
-function formatCommandRowName(node, casing, globalLongOptionFlags) {
+function collapseOptionalParameterTokens(parameterTokens, inlineWidthBudget = Number.POSITIVE_INFINITY) {
+    const optionalCount = parameterTokens.filter((token) => token.optional).length;
+    if (optionalCount === 0) {
+        return parameterTokens;
+    }
+    const inlineWidth = parameterTokens.reduce((total, token) => total + token.text.length + 1, 0);
+    if (optionalCount <= MAX_INLINE_OPTIONAL_PARAMETER_TOKENS && inlineWidth <= inlineWidthBudget) {
+        return parameterTokens;
+    }
+    const required = parameterTokens.filter((token) => !token.optional);
+    const collapsedText = `+${optionalCount} options`;
+    return [
+        ...required,
+        {
+            text: `[${collapsedText}]`,
+            optional: true,
+            tokens: [
+                { text: "[", role: "dim" },
+                { text: collapsedText, role: "dim" },
+                { text: "]", role: "dim" }
+            ]
+        }
+    ];
+}
+function formatCommandRowNameTokens(node, casing, globalLongOptionFlags) {
     const baseName = node.aliases.length === 0 ? node.name : `${node.name} (${node.aliases.join(", ")})`;
+    const nameTokens = [{ text: baseName, role: "command" }];
+    // formatCommandList indents rows by two columns, so anything wider than the rest of the
+    // terminal wraps onto continuation lines and makes the command list unreadable.
+    const inlineWidthBudget = Math.max(0, (process.stdout.columns ?? DEFAULT_HELP_TOTAL_WIDTH) - 2 - baseName.length);
     const parameterTokens = node.kind === "command"
-        ? formatCommandParameterTokens(node, casing, globalLongOptionFlags)
+        ? collapseOptionalParameterTokens(formatCommandParameterTokens(node, casing, globalLongOptionFlags), inlineWidthBudget)
         : [];
-    const name = parameterTokens.length === 0 ? baseName : `${baseName} ${parameterTokens.join(" ")}`;
-    return name;
+    for (const token of parameterTokens) {
+        nameTokens.push({ text: " ", role: "literal" }, ...token.tokens);
+    }
+    const name = parameterTokens.length === 0
+        ? baseName
+        : `${baseName} ${parameterTokens.map((token) => token.text).join(" ")}`;
+    return { name, nameTokens };
 }
-function formatCommandRows(group, scope, casing, globalLongOptionFlags) {
-    return getHelpChildren(group, scope).map((child) => ({
-        name: formatCommandRowName(child, casing, globalLongOptionFlags),
-        description: child.description ?? ""
-    }));
+function formatCommandRows(group, scope, casing, globalLongOptionFlags, help) {
+    const toRow = (child, depth) => {
+        const { name, nameTokens } = formatCommandRowNameTokens(child, casing, globalLongOptionFlags);
+        return {
+            name,
+            nameTokens,
+            description: suppressEchoHelpDescription(child.description ?? "", child.name),
+            kind: child.kind,
+            depth
+        };
+    };
+    if (help === "concise") {
+        return getHelpChildren(group, scope).map((child) => toRow(child, 0));
+    }
+    const rows = [];
+    const visit = (node, depth) => {
+        for (const child of getHelpChildren(node, scope)) {
+            rows.push(toRow(child, depth));
+            if (child.kind === "group") {
+                visit(child, depth + 1);
+            }
+        }
+    };
+    visit(group, 0);
+    return rows;
 }
 function formatGlobalOptionsLine(ctx) {
     const flags = [];
@@ -1102,7 +1461,7 @@ function formatGlobalOptionsLine(ctx) {
         flags.push("--yes");
     }
     if (ctx.controls.output) {
-        flags.push("--output <format>");
+        flags.push(`--output <${outputFormatNames(ctx.controls).join("|")}>`);
     }
     if (ctx.controls.verbose) {
         flags.push("-v, --verbose");
@@ -1110,10 +1469,10 @@ function formatGlobalOptionsLine(ctx) {
     if (ctx.showVersion) {
         flags.push("--version");
     }
-    return flags.length > 0 ? `${text.section("Options:")} ${flags.join("  ")}` : "";
+    return flags.length > 0 ? `${text.section("Global Options:")} ${flags.join("  ")}` : "";
 }
 function formatLeafGlobalOptionsLine(ctx) {
-    return ctx.controls.verbose ? `${text.section("Options:")} -v, --verbose` : "";
+    return ctx.controls.verbose ? `${text.section("Global Options:")} -v, --verbose` : "";
 }
 function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags) {
     const seen = new Map();
@@ -1131,10 +1490,7 @@ function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlag
                 if (seen.has(dedupeKey)) {
                     continue;
                 }
-                seen.set(dedupeKey, {
-                    flags: formatHelpFieldFlags(field, globalLongOptionFlags),
-                    description: formatHelpFieldDescription(field)
-                });
+                seen.set(dedupeKey, createHelpOptionRow(formatHelpFieldFlags(field, globalLongOptionFlags), formatHelpFieldDescription(field)));
             }
             return;
         }
@@ -1158,6 +1514,18 @@ function formatHelpOptionList(rows) {
         ? helpFormatterPlain.formatOptionList(rows)
         : formatOptionList(rows);
 }
+function sortLeafHelpOptionFields(fields) {
+    const required = [];
+    const optional = [];
+    for (const field of fields) {
+        if (!field.optional && !field.hasDefault) {
+            required.push(field);
+            continue;
+        }
+        optional.push(field);
+    }
+    return [...required, ...optional];
+}
 function buildUsageLine(breadcrumb, rootUsageName, suffix) {
     const visibleBreadcrumb = breadcrumb.filter((segment) => segment.length > 0);
     const usageBreadcrumb = breadcrumb[0] === "" ? [rootUsageName, ...visibleBreadcrumb] : visibleBreadcrumb;
@@ -1169,28 +1537,51 @@ function formatGroupUsageSuffix(group, scope, casing, globalLongOptionFlags) {
     if (group.default !== undefined &&
         group.default.hidden === true &&
         group.default.scope.includes(scope)) {
-        const parameterTokens = formatCommandParameterTokens(group.default, casing, globalLongOptionFlags);
-        return ["[command]", "[OPTIONS]", ...parameterTokens].join(" ");
+        const parameterTokens = collapseOptionalParameterTokens(formatCommandParameterTokens(group.default, casing, globalLongOptionFlags));
+        return ["[command]", "[OPTIONS]", ...parameterTokens.map((token) => token.text)].join(" ");
     }
     return "[command] [OPTIONS]";
 }
+function formatHelpDrillDownFooter(rootUsageName) {
+    return text.muted(`Run ${rootUsageName} <command> --help for full options.`);
+}
+function formatStyledUsageLine(usageLine) {
+    const parts = usageLine.split(" ").filter((part) => part.length > 0);
+    if (parts.length === 0) {
+        return text.usageCommand(usageLine);
+    }
+    const commandEnd = parts.findIndex((part) => part.startsWith("-") || part.startsWith("[") || part.startsWith("<"));
+    const commandParts = commandEnd === -1 ? parts : parts.slice(0, commandEnd);
+    const argParts = commandEnd === -1 ? [] : parts.slice(commandEnd);
+    const command = commandParts.join(" ");
+    if (argParts.length === 0) {
+        return text.usageCommand(command);
+    }
+    return `${text.usageCommand(command)} ${renderHelpTokens(argParts.flatMap((part, index) => [
+        ...(index === 0 ? [] : [{ text: " ", role: "literal" }]),
+        ...tokenizeHelpFlags(part)
+    ]))}`;
+}
 function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUsageName, isRoot) {
     const sections = [];
     const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion, globalOptions.controls);
-    const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags);
+    const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags, globalOptions.controls.help);
     if (commandRows.length > 0) {
-        sections.push(`${text.sectionHeader("Commands")}\n${formatHelpCommandList(commandRows)}`);
+        sections.push(`${text.section("Commands:")}\n${formatHelpCommandList(commandRows)}`);
     }
     if (isRoot) {
         const schemaGlobalRows = collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags);
         const builtInLine = formatGlobalOptionsLine(globalOptions);
         if (schemaGlobalRows.length > 0) {
-            sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(schemaGlobalRows)}\n${builtInLine}`);
+            sections.push(`${text.section("Options:")}\n${formatHelpOptionList(schemaGlobalRows)}\n${builtInLine}`);
         }
         else {
             sections.push(builtInLine);
         }
     }
+    if (commandRows.length > 0) {
+        sections.push(formatHelpDrillDownFooter(rootUsageName));
+    }
     return renderHelpDocument({
         breadcrumb,
         rootUsageName,
@@ -1205,15 +1596,19 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion, globalOptions.controls);
     const collected = collectFields(command.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, command.positional);
-    const optionRows = fields
-        .filter((field) => field.global !== true)
-        .map((field) => ({
-        flags: formatHelpFieldFlags(field, globalLongOptionFlags),
-        description: formatHelpFieldDescription(field)
-    }))
+    const localFields = fields.filter((field) => field.global !== true);
+    const toHelpRow = (field) => createHelpOptionRow(formatHelpFieldFlags(field, globalLongOptionFlags), formatHelpFieldDescription(field));
+    const argumentRows = localFields
+        .filter((field) => field.positionalIndex !== undefined)
+        .map(toHelpRow);
+    const optionRows = sortLeafHelpOptionFields(localFields.filter((field) => field.positionalIndex === undefined))
+        .map(toHelpRow)
         .concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
+    if (argumentRows.length > 0) {
+        sections.push(`${text.section("Arguments:")}\n${formatHelpOptionList(argumentRows)}`);
+    }
     if (optionRows.length > 0) {
-        sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(optionRows)}`);
+        sections.push(`${text.section("Options:")}\n${formatHelpOptionList(optionRows)}`);
     }
     const builtInLine = formatLeafGlobalOptionsLine(globalOptions);
     if (builtInLine.length > 0) {
@@ -1221,10 +1616,10 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     }
     const secretRows = formatSecretRows(command.secrets);
     if (secretRows.length > 0) {
-        sections.push(`${text.sectionHeader("Secrets (environment)")}\n${formatHelpOptionList(secretRows)}`);
+        sections.push(`${text.section("Secrets (environment):")}\n${formatHelpOptionList(secretRows)}`);
     }
     if (command.examples.length > 0) {
-        sections.push(`${text.sectionHeader("Examples")}\n${formatExampleRows(command.examples, breadcrumb, rootUsageName).join("\n")}`);
+        sections.push(`${text.section("Examples:")}\n${formatExampleRows(command.examples, breadcrumb, rootUsageName).join("\n")}`);
     }
     const positionalFields = fields.filter((f) => f.positionalIndex !== undefined);
     const usageSuffix = positionalFields.length > 0
@@ -1243,7 +1638,7 @@ function renderJsonHelp(target, root, casing, globalOptions, rootUsageName) {
     const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion, globalOptions.controls);
     const node = target.node;
     if (node.kind === "group") {
-        const commandRows = formatCommandRows(node, "cli", casing, globalLongOptionFlags);
+        const commandRows = formatCommandRows(node, "cli", casing, globalLongOptionFlags, globalOptions.controls.help);
         const isRoot = node === root;
         return `${JSON.stringify({
             schemaVersion: 1,
@@ -1252,7 +1647,12 @@ function renderJsonHelp(target, root, casing, globalOptions, rootUsageName) {
             path: target.breadcrumb.filter((segment) => segment.length > 0),
             usage: buildUsageLine(target.breadcrumb, rootUsageName, formatGroupUsageSuffix(node, "cli", casing, globalLongOptionFlags)),
             ...(node.description === undefined ? {} : { description: node.description }),
-            commands: commandRows.map((row) => ({ name: row.name, description: row.description })),
+            commands: commandRows.map((row) => ({
+                name: row.name,
+                description: row.description,
+                kind: row.kind,
+                depth: row.depth
+            })),
             options: isRoot
                 ? collectSchemaGlobalFieldRows(node, "cli", casing, globalLongOptionFlags).map((row) => ({
                     name: row.flags.split(/[ ,]+/)[0]?.replace(/^--/, "") ?? row.flags,
@@ -1294,12 +1694,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";
@@ -1323,7 +1731,7 @@ function renderHelpDocument(input) {
     if (remainingDescription.length > 0) {
         lines.push(remainingDescription, "");
     }
-    lines.push(`Usage: ${text.usageCommand(input.usageLine)}`, "");
+    lines.push(`Usage: ${formatStyledUsageLine(input.usageLine)}`, "");
     if (input.requiresAuth) {
         lines.push("Requires: authentication");
     }
@@ -1333,21 +1741,22 @@ function renderHelpDocument(input) {
     lines.push(renderHelpSections(input.sections));
     return `${lines.join("\n").trimEnd()}\n`;
 }
-async function renderGeneratedHelp(root, argv, options) {
+async function renderGeneratedHelp(root, argv, options, invocation) {
+    const write = invocation?.write ?? ((chunk) => { process.stdout.write(chunk); });
     const output = resolveHelpOutput(argv);
     const casing = options.casing ?? "kebab";
     const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
     const target = resolveHelpTarget(root, argv, "cli", rootUsageName, options.rootDisplayName);
     const controls = resolveCLIControls(options.controls);
     if (output === "json") {
-        process.stdout.write(renderJsonHelp(target, root, casing, {
+        write(renderJsonHelp(target, root, casing, {
             controls,
             showVersion: options.version !== undefined,
             presetsEnabled: options.presets === true
         }, 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,
@@ -1359,21 +1768,20 @@ async function renderGeneratedHelp(root, argv, options) {
                 showVersion: options.version !== undefined,
                 presetsEnabled: options.presets === true
             }, rootUsageName);
-        process.stdout.write(rendered);
+        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);
         }
@@ -1381,33 +1789,64 @@ 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) {
-                command.argument(formatPositionalToken(field));
-                continue;
+        fieldLoaders.set(command, () => {
+            if (loadedFields !== undefined) {
+                return loadedFields;
+            }
+            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);
+                    }
+                }
             }
-            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 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("."),
+                    declarationPath: nextPathSegments,
+                    casing,
+                    dynamicFields: collected.dynamicFields,
+                    fields,
+                    positionalValues,
+                    presetsEnabled,
+                    rawArgv: unknownArgv,
+                    actionCommand,
+                    variants: collected.variants
+                });
             });
+            loadedFields = collected.dynamicFields;
+            return loadedFields;
         });
         return command;
     }
@@ -1418,7 +1857,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);
@@ -1476,6 +1915,155 @@ function getToolcraftReservedChildNames(command) {
 function getNodeCommandNames(node) {
     return [node.name, ...node.aliases].filter((name) => name.length > 0);
 }
+function createGlobalSnapshotOptions(presetsEnabled, versionEnabled, controls) {
+    const options = [
+        {
+            name: "help",
+            flags: ["-h", "--help"],
+            type: "boolean",
+            required: false,
+            hidden: false,
+            description: "Display help for command."
+        }
+    ];
+    if (presetsEnabled) {
+        options.push({
+            name: "preset",
+            flags: ["--preset"],
+            type: "string",
+            required: false,
+            hidden: true,
+            description: "Load parameter defaults from a JSON file."
+        });
+    }
+    if (controls.yes) {
+        options.push({
+            name: "yes",
+            flags: ["--yes"],
+            type: "boolean",
+            required: false,
+            hidden: true,
+            description: "Accept defaults and skip prompts."
+        });
+    }
+    if (controls.output) {
+        const choices = outputFormatNames(controls);
+        options.push({
+            name: "output",
+            flags: ["--output"],
+            type: "enum",
+            required: false,
+            hidden: true,
+            description: "Output format.",
+            choices
+        });
+    }
+    if (controls.debug) {
+        options.push({
+            name: "debug",
+            flags: ["--debug"],
+            type: "enum",
+            required: false,
+            hidden: true,
+            description: "Print stack traces for unexpected errors.",
+            choices: ["trim", "raw"]
+        });
+    }
+    if (controls.logLevel) {
+        options.push({
+            name: "logLevel",
+            flags: ["--log-level"],
+            type: "enum",
+            required: false,
+            hidden: true,
+            description: "Set runtime diagnostic log level.",
+            choices: [...LOG_LEVELS]
+        });
+    }
+    if (controls.verbose) {
+        options.push({
+            name: "verbose",
+            flags: ["-v", "--verbose"],
+            type: "boolean",
+            required: false,
+            hidden: true,
+            description: "Print detailed runtime diagnostics."
+        });
+    }
+    if (versionEnabled) {
+        options.push({
+            name: "version",
+            flags: ["--version"],
+            type: "boolean",
+            required: false,
+            hidden: false,
+            description: "Output the version number."
+        });
+    }
+    return options;
+}
+function createSnapshotGroup(group, casing, globalLongOptionFlags, pathSegments, isDefault) {
+    const children = group.children
+        .filter((child) => isNodeVisibleInScope(child, "cli"))
+        .map((child) => createSnapshotNode(child, casing, globalLongOptionFlags, [...pathSegments, child.name], group.default === child));
+    return {
+        kind: "group",
+        name: group.name,
+        path: pathSegments,
+        aliases: [...group.aliases],
+        hidden: false,
+        default: isDefault,
+        ...(group.description === undefined ? {} : { description: group.description }),
+        children
+    };
+}
+function createSnapshotNode(node, casing, globalLongOptionFlags, pathSegments, isDefault) {
+    if (node.kind === "group") {
+        return createSnapshotGroup(node, casing, globalLongOptionFlags, pathSegments, isDefault);
+    }
+    const collected = collectFields(node.params, casing, globalLongOptionFlags);
+    const fields = assignPositionals(collected.fields, node.positional);
+    validateUniqueOptionFlags(fields, globalLongOptionFlags);
+    return {
+        kind: "command",
+        name: node.name,
+        path: pathSegments,
+        aliases: [...node.aliases],
+        hidden: node.hidden,
+        default: isDefault,
+        ...(node.description === undefined ? {} : { description: node.description }),
+        options: [
+            ...fields.map((field) => createFieldSnapshotOption(field, globalLongOptionFlags)),
+            ...collected.dynamicFields.flatMap((field) => createDynamicSnapshotOptions(field, casing))
+        ]
+    };
+}
+function createFieldSnapshotOption(field, globalLongOptionFlags) {
+    return {
+        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 }),
+        ...(field.hasDefault ? { default: field.defaultValue } : {}),
+        ...(field.positionalIndex === undefined ? {} : { positional: true }),
+        ...(field.global === true ? { global: true } : {})
+    };
+}
+function createDynamicSnapshotOptions(field, casing) {
+    return formatDynamicHelpFields(field, casing).map((row) => ({
+        name: field.displayPath,
+        flags: [row.flags],
+        type: describeDynamicFieldType(field),
+        required: field.requiredWhenActive,
+        hidden: false,
+        ...(field.description === undefined ? {} : { description: field.description }),
+        ...(field.hasDefault ? { default: field.defaultValue } : {}),
+        dynamic: true
+    }));
+}
 function addGlobalOptions(command, presetsEnabled, controls) {
     const options = [];
     if (presetsEnabled) {
@@ -1485,15 +2073,21 @@ function addGlobalOptions(command, presetsEnabled, controls) {
         options.push(new Option("--yes", "Accept defaults and skip prompts."));
     }
     if (controls.output) {
-        options.push(new Option("--output <format>", "Output format.").argParser((value) => {
+        const choices = outputFormatNames(controls);
+        options.push(new Option("--output <format>", "Output format.")
+            .choices(choices)
+            .argParser((value) => {
             if (value === "rich" || value === "md" || value === "json") {
                 return value;
             }
             if (value === "markdown") {
                 return "md";
             }
-            throw new InvalidArgumentError(formatInvalidEnumMessage("--output", value, ["rich", "md", "markdown", "json"], {
-                candidates: ["rich", "markdown", "json"],
+            if (Object.hasOwn(controls.outputFormats, value)) {
+                return value;
+            }
+            throw new InvalidArgumentError(formatInvalidEnumMessage("--output", value, choices, {
+                candidates: ["rich", "markdown", "json", ...Object.keys(controls.outputFormats)],
                 threshold: 3
             }));
         }));
@@ -1592,7 +2186,17 @@ function enumOptionLabel(schema, value) {
     }
     return schema.labels[key] ?? key;
 }
-async function promptForField(field) {
+function withPromptStreams(options, streams) {
+    return {
+        ...options,
+        ...(streams.input === undefined ? {} : { input: streams.input }),
+        ...(streams.output === undefined ? {} : { output: streams.output })
+    };
+}
+function throwPromptCancellation() {
+    throw new UserError("Operation cancelled.");
+}
+async function promptForField(field, streams = {}) {
     const schema = field.schema;
     if (schema.kind === "enum") {
         const options = schema.loadOptions
@@ -1601,43 +2205,40 @@ async function promptForField(field) {
                 label: enumOptionLabel(schema, value),
                 value
             }));
-        const selected = await select({
+        const selected = await select(withPromptStreams({
             message: field.description ?? fieldPromptLabel(field),
             options,
             initialValue: field.hasDefault ? field.defaultValue : undefined
-        });
+        }, streams));
         if (isCancel(selected)) {
-            cancel("Operation cancelled.");
-            throw new UserError("Operation cancelled.");
+            throwPromptCancellation();
         }
         return selected;
     }
     if (field.schema.kind === "boolean") {
-        const selected = await confirm({
+        const selected = await confirm(withPromptStreams({
             message: fieldPromptLabel(field),
             initialValue: field.hasDefault ? Boolean(field.defaultValue) : undefined
-        });
+        }, streams));
         if (isCancel(selected)) {
-            cancel("Operation cancelled.");
-            throw new UserError("Operation cancelled.");
+            throwPromptCancellation();
         }
         return selected;
     }
-    const entered = await promptText({
+    const entered = await promptText(withPromptStreams({
         message: fieldPromptLabel(field),
         initialValue: field.hasDefault && field.defaultValue !== undefined
             ? formatResolvedValue(field.defaultValue)
             : undefined
-    });
+    }, streams));
     if (isCancel(entered)) {
-        cancel("Operation cancelled.");
-        throw new UserError("Operation cancelled.");
+        throwPromptCancellation();
     }
     if (typeof entered !== "string") {
         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);
@@ -1655,11 +2256,11 @@ function resolveOutput(resolvedFlags) {
         return "json";
     }
     if (resolvedFlags.output !== undefined) {
-        return resolvedFlags.output;
+        return resolvedFlags.output === "markdown" ? "md" : resolvedFlags.output;
     }
     return "rich";
 }
-function resolveOutputFromArgv(argv) {
+function resolveOutputFromArgv(argv, formats = {}) {
     for (let index = 0; index < argv.length; index += 1) {
         const token = argv[index] ?? "";
         if (token === "--json") {
@@ -1676,6 +2277,9 @@ function resolveOutputFromArgv(argv) {
             if (value === "markdown") {
                 return "md";
             }
+            if (value !== undefined && Object.hasOwn(formats, value)) {
+                return value;
+            }
             continue;
         }
         if (token.startsWith("--output=")) {
@@ -1686,61 +2290,21 @@ function resolveOutputFromArgv(argv) {
             if (value === "markdown") {
                 return "md";
             }
+            if (Object.hasOwn(formats, value)) {
+                return value;
+            }
         }
     }
     return "rich";
 }
-const DESIGN_SYSTEM_OUTPUT_BY_MODE = {
-    rich: "terminal",
-    md: "markdown",
-    json: "json"
-};
 function toDesignSystemOutput(output) {
-    return DESIGN_SYSTEM_OUTPUT_BY_MODE[output];
-}
-async function withOutputFormat(output, fn) {
-    const previous = process.env.OUTPUT_FORMAT;
-    process.env.OUTPUT_FORMAT = toDesignSystemOutput(output);
-    resetOutputFormatCache();
-    try {
-        return await fn();
+    if (output === "md") {
+        return "markdown";
     }
-    finally {
-        if (previous === undefined) {
-            delete process.env.OUTPUT_FORMAT;
-        }
-        else {
-            process.env.OUTPUT_FORMAT = previous;
-        }
-        resetOutputFormatCache();
+    if (output === "json") {
+        return "json";
     }
-}
-function createFs() {
-    return {
-        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
-        writeFile: async (path, contents, options) => {
-            await writeFile(path, contents, options);
-        },
-        exists: async (path) => {
-            try {
-                await access(path);
-                return true;
-            }
-            catch {
-                return false;
-            }
-        },
-        lstat: async (path) => lstat(path),
-        rename: async (fromPath, toPath) => rename(fromPath, toPath),
-        unlink: async (path) => unlink(path)
-    };
-}
-function createEnv(values = process.env) {
-    return {
-        get(key) {
-            return values[key];
-        }
-    };
+    return "terminal";
 }
 function isPlainObject(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
@@ -1772,20 +2336,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;
@@ -1813,6 +2379,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.`);
@@ -1828,7 +2397,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, {
@@ -1855,7 +2424,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];
@@ -1865,7 +2437,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)) {
@@ -1875,7 +2458,7 @@ async function loadPresetValues(fields, presetPath) {
         }
     }
     visitObject(parsedPreset, []);
-    return presetValues;
+    return { fields: presetValues, dynamic: dynamicValues };
 }
 function isNumericFixtureSelector(value) {
     if (value.length === 0) {
@@ -2143,16 +2726,16 @@ function createFixtureEnvValues(command) {
     }
     return values;
 }
-async function resolveFixtureRuntime(command, services, requirementOptions, runtimeFetch) {
-    const selector = process.env.TOOLCRAFT_FIXTURE;
+async function resolveFixtureRuntime(command, services, requirementOptions, runtimeFetch, runtimeEnv, runtimeFs, embedded = false) {
+    const selector = embedded ? undefined : process.env.TOOLCRAFT_FIXTURE;
     if (selector === undefined || selector.length === 0) {
         return {
-            env: createEnv(),
+            env: createEnv(runtimeEnv),
             fetch: runtimeFetch,
-            fs: createFs(),
+            fs: createFs(runtimeFs),
             isFixture: false,
             requirementOptions,
-            secrets: resolveCommandSecrets(command),
+            secrets: resolveCommandSecrets(command, runtimeEnv),
             services
         };
     }
@@ -2189,18 +2772,19 @@ function isHumanInLoopPending(result) {
         typeof result.message === "string" &&
         typeof result.enqueuedAt === "string");
 }
-function renderHumanInLoopPending(pending) {
-    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:   toolcraft approvals show ${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) {
-    const logger = createLogger();
+function renderCliErrorPattern(pattern, outputEmitter) {
+    const logger = createLogger(outputEmitter);
     if (pattern.kind === "usage") {
         logger.error(appendUsagePointer(pattern.message, {
             rootUsageName: pattern.rootUsageName,
@@ -2216,8 +2800,8 @@ function renderCliErrorPattern(pattern) {
     }
     if (pattern.kind === "definition") {
         logger.error(`Command definition error: ${pattern.error.message}\n` +
-            "This is a bug in the generated command definition, not in your command arguments.\n" +
-            "Run with --debug for a stack trace.");
+            "This is a bug in the generated command definition, not in your command arguments." +
+            (pattern.debugControlEnabled ? "\nRun with --debug for a stack trace." : ""));
         if (pattern.debugStackMode !== undefined && pattern.error.stack) {
             process.stderr.write(`${formatDebugStack(pattern.error.stack, pattern.debugStackMode)}\n`);
         }
@@ -2227,15 +2811,17 @@ function renderCliErrorPattern(pattern) {
     if (pattern.kind === "toolcraft-bug") {
         logger.error(`toolcraft hit an internal invariant: ${pattern.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.`);
+            `it cannot be worked around by changing argv.` +
+            (pattern.debugControlEnabled
+                ? ` Re-run with --debug for a stack trace and file an issue.`
+                : " File an issue."));
         if (pattern.debugStackMode !== undefined && pattern.error.stack) {
             process.stderr.write(`${formatDebugStack(pattern.error.stack, pattern.debugStackMode)}\n`);
         }
         process.exitCode = 1;
         return;
     }
-    logger.error(pattern.debugStackMode !== undefined
+    logger.error(pattern.debugStackMode !== undefined || !pattern.debugControlEnabled
         ? pattern.message
         : `${pattern.message} Use --debug for a stack trace.`);
     if (pattern.debugStackMode !== undefined && pattern.stack !== undefined) {
@@ -2243,15 +2829,8 @@ function renderCliErrorPattern(pattern) {
     }
     process.exitCode = 1;
 }
-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. ${RESERVED_SERVICE_NAMES_MESSAGE}`);
-        }
-    }
-}
 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);
 }
@@ -2294,7 +2873,7 @@ function parseOptionFieldValue(field, value, errors) {
         return { ok: true, value: parsedValue };
     }
     catch (error) {
-        if (error instanceof UserError || error instanceof InvalidArgumentError) {
+        if (isUserError(error) || error instanceof InvalidArgumentError) {
             errors.push({
                 path: field.displayPath,
                 message: error.message
@@ -2390,12 +2969,12 @@ function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displa
         case "object": {
             const [head, ...rest] = rawSegments;
             for (const [key, childSchema] of Object.entries(unwrappedSchema.shape)) {
-                if (formatSegment(key, casing) !== head) {
+                if (formatCLIName(key, casing) !== head) {
                     continue;
                 }
                 return resolveDynamicLeaf(childSchema, rest, casing, [...outputPath, key], [...displayPath, key], displayPathPrefix);
             }
-            throw new UserError(`Unknown parameter "${qualifyDisplayPath(displayPathPrefix, [...displayPath, head].join("."))}". ${formatAvailableList(Object.keys(unwrappedSchema.shape).map((key) => qualifyDisplayPath(displayPathPrefix, toDisplayPath([...displayPath, formatSegment(key, casing)]))))}`);
+            throw new UserError(`Unknown parameter "${qualifyDisplayPath(displayPathPrefix, [...displayPath, head].join("."))}". ${formatAvailableList(Object.keys(unwrappedSchema.shape).map((key) => qualifyDisplayPath(displayPathPrefix, toDisplayPath([...displayPath, formatCLIName(key, casing)]))))}`);
         }
         case "record": {
             const [head, ...rest] = rawSegments;
@@ -2418,6 +2997,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) {
@@ -2431,8 +3014,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") {
@@ -2480,7 +3069,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") {
@@ -2521,7 +3110,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) {
@@ -2532,13 +3121,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) => formatCLIName(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-");
@@ -2546,18 +3160,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"
@@ -2573,6 +3180,7 @@ function parseDynamicValues(dynamicFields, rawArgv, casing, errors) {
     }
     return {
         providedFieldIds,
+        positionals,
         values: new Map(dynamicFields
             .filter((field) => rawValues.has(field.id))
             .map((field) => [
@@ -2581,9 +3189,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))
@@ -2595,12 +3204,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);
                 }
@@ -2655,16 +3268,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);
@@ -2677,7 +3307,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) {
@@ -2690,19 +3320,48 @@ async function enforceVariantConstraints(params, fields, dynamicFields, variants
         }
     }
 }
-async function resolveParams(fields, dynamicFields, variants, positionalValues, optionValues, rawArgv, casing, presetPath, shouldPrompt) {
+async function resolveParams(fields, dynamicFields, variants, positionalValues, optionValues, rawArgv, casing, presetPath, shouldPrompt, missingParameterContext, promptStreams, parameterDefaults = {}) {
     const params = {};
+    const errors = [];
+    const dynamicResults = parseDynamicValues(dynamicFields, rawArgv, casing, errors);
+    const positionalTokens = [...positionalValues, ...dynamicResults.positionals];
+    const fieldRoot = (field) => field.synthetic
+        ? (field.path.length === 1 ? field.path[0].slice(0, -"Kind".length) : field.path[0])
+        : field.path[0];
+    const explicitRoots = new Set();
+    for (const field of fields) {
+        if (hasFieldValue(optionValues[field.commanderOptionAttribute]) ||
+            (field.positionalIndex !== undefined && positionalTokens[field.positionalIndex] !== undefined)) {
+            explicitRoots.add(fieldRoot(field));
+        }
+    }
+    for (const field of dynamicFields) {
+        if (dynamicResults.values.has(field.id))
+            explicitRoots.add(field.path[0]);
+    }
+    const defaultRoots = new Set(Object.keys(parameterDefaults).filter(key => !explicitRoots.has(key)));
+    for (const key of defaultRoots)
+        params[key] = cloneDefaultValue(parameterDefaults[key]);
+    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) {
+        if (defaultRoots.has(fieldRoot(field)))
+            continue;
         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);
@@ -2713,7 +3372,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";
             }
@@ -2739,8 +3398,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") {
@@ -2750,12 +3409,53 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             }
             value = parsed.value;
         }
+        if (value === undefined &&
+            field.optional &&
+            missingParameterContext !== undefined &&
+            field.schema.cli?.resolveMissing !== undefined) {
+            const resolution = await field.schema.cli.resolveMissing({
+                ...missingParameterContext,
+                params: { ...params }
+            });
+            const choices = resolution?.choices ?? [];
+            if (choices.length === 1) {
+                value = choices[0]?.value;
+                resolvedMissing = true;
+                source = "prompt";
+            }
+            else if (choices.length > 1) {
+                const selected = await select(withPromptStreams({
+                    message: resolution?.message ?? field.description ?? fieldPromptLabel(field),
+                    options: choices.map((choice) => ({
+                        label: choice.label,
+                        value: choice.value
+                    }))
+                }, promptStreams));
+                if (isCancel(selected)) {
+                    throwPromptCancellation();
+                }
+                value = selected;
+                resolvedMissing = true;
+                source = "prompt";
+            }
+        }
+        if (resolvedMissing) {
+            const validation = validateSchema(field.schema, value);
+            if (!validation.ok) {
+                errors.push(...validation.issues.map((issue) => ({
+                    path: field.displayPath,
+                    message: issue.message
+                })));
+                continue;
+            }
+            value = validation.value;
+        }
         if (value === undefined && shouldPrompt && !field.optional) {
-            value = await promptForField(field);
+            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) {
@@ -2764,10 +3464,18 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
             }
             errors.push({
                 path: field.displayPath,
-                message: `Missing required parameter "${field.displayPath}".`
+                message: formatMissingParameterMessage(field)
             });
             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);
@@ -2776,16 +3484,17 @@ 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) {
+        if (defaultRoots.has(field.path[0]))
+            continue;
         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) {
@@ -2799,36 +3508,61 @@ 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.filter(variant => !defaultRoots.has(fieldRoot(fields.find(field => field.id === variant.controlFieldId)))), 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, services, requirementOptions, runtimeFetch, runtimeOptions, diagnosticsOptions, onErrorReportContext) {
-    const logger = createLogger();
+async function executeCommand(state, rootUsageName, services, requirementOptions, runtimeFetch, humanInLoop, runtimeEnv, runtimeFs, outputEmitter, outputFormats, promptStreams, diagnosticsOptions, onErrorReportContext, invocation) {
+    const logger = createLogger(outputEmitter);
+    const optionValues = getResolvedFlags(state.actionCommand);
+    const resolvedFlags = optionValues;
+    const output = resolveOutput(resolvedFlags);
     const primitives = {
         logger,
         renderTable,
         getTheme,
-        note
+        note: invocation ? (message, title) => note(message, title, invocation.write) : note,
+        outputFormat: output
     };
-    const optionValues = state.actionCommand.optsWithGlobals();
-    const resolvedFlags = optionValues;
-    const output = resolveOutput(resolvedFlags);
     const diagnostics = createRuntimeLogger({
         level: resolvedFlags.logLevel ??
             (diagnosticsOptions.verboseControlEnabled && resolvedFlags.verbose
                 ? "trace"
                 : diagnosticsOptions.logLevel),
-        logger: diagnosticsOptions.logger ?? writeCLIDiagnosticEvent
+        logger: diagnosticsOptions.logger ?? (invocation
+            ? (event) => invocation.write(`${event.message}\n`, "stderr")
+            : writeCLIDiagnosticEvent)
     });
-    const shouldPrompt = !resolvedFlags.yes && Boolean(process.stdin.isTTY);
-    const runtime = await resolveFixtureRuntime(state.command, services, requirementOptions, runtimeFetch);
+    const promptInput = promptStreams.input ?? (invocation ? { isTTY: false } : process.stdin);
+    const promptOutput = promptStreams.output ?? (invocation ? { isTTY: false } : process.stdout);
+    const stdinTTY = Boolean(promptInput.isTTY);
+    const stdoutTTY = Boolean(promptOutput.isTTY);
+    const shouldPrompt = !resolvedFlags.yes && stdinTTY;
+    const missingParameterContext = !resolvedFlags.yes && output === "rich" && stdinTTY && stdoutTTY
+        ? {
+            commandPath: state.commandPath,
+            params: {},
+            output: "rich",
+            stdinTTY,
+            stdoutTTY
+        }
+        : undefined;
+    const runtime = await resolveFixtureRuntime(state.command, services, requirementOptions, runtimeFetch, runtimeEnv, runtimeFs, invocation !== undefined);
     const preflightContext = {
         ...runtime.services,
+        ...invocation?.capabilities,
+        ...(invocation ? { signal: invocation.signal } : {}),
         secrets: runtime.secrets,
         fetch: runtime.fetch,
         fs: runtime.fs,
@@ -2842,19 +3576,96 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
     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);
+        await withOutputFormat(toDesignSystemOutput(output), async () => {
+            if (!invocation)
+                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, invocation?.defaults?.[state.declarationPath.join("/")]);
+            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, "")));
+            }
+            if (invocation) {
+                const validation = validateSchema(state.command.params, params);
+                if (!validation.ok) {
+                    throwValidationErrors(validation.issues.map((issue) => formatFieldValidationIssue(issue, "")));
+                    return;
+                }
+                Object.assign(params, validation.value);
+                invocation.signal.throwIfAborted();
+                await assertCommandRequirements(state.command, { ...preflightContext, params }, runtime.requirementOptions);
+                if (state.command.confirm && !state.command.humanInLoop && !resolvedFlags.yes) {
+                    throw new UserError("Confirmation required; supply --yes to authorize this command.");
+                }
+            }
             resolvedParams = params;
             runtimeSecrets = runtime.secrets;
             const context = {
                 ...preflightContext,
                 params
             };
+            if (state.command.stream !== undefined) {
+                const stream = createManagedStream({
+                    eventSchema: state.command.stream.event,
+                    signal: invocation?.signal,
+                    onStatus(event) {
+                        diagnostics.emit({
+                            level: "info",
+                            message: event.message ?? event.type,
+                            category: "runtime"
+                        });
+                        if (output === "rich" && event.message !== undefined) {
+                            logger.info(event.message);
+                        }
+                    },
+                    async create(signal, status) {
+                        return await state.command.handler({
+                            ...context,
+                            signal,
+                            status,
+                            async refreshSecrets() {
+                                return resolveCommandSecrets(state.command, runtimeEnv);
+                            }
+                        });
+                    }
+                });
+                const interrupt = () => {
+                    void stream.cancel(new UserError("Operation cancelled.")).catch(() => undefined);
+                };
+                if (!invocation)
+                    process.once("SIGINT", interrupt);
+                try {
+                    for await (const event of stream) {
+                        invocation?.signal.throwIfAborted();
+                        if (output === "json") {
+                            const line = JSON.stringify(event);
+                            if (outputEmitter === undefined) {
+                                process.stdout.write(`${line}\n`);
+                            }
+                            else {
+                                outputEmitter(line);
+                            }
+                        }
+                        else {
+                            renderCLIResult(state.command, state.commandPath, event, output, primitives, outputFormats, invocation?.write ?? (outputEmitter === undefined
+                                ? undefined
+                                : (chunk) => outputEmitter(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk)), outputEmitter);
+                        }
+                        await invocation?.flush();
+                    }
+                    invocation?.signal.throwIfAborted();
+                }
+                finally {
+                    if (!invocation)
+                        process.removeListener("SIGINT", interrupt);
+                    await stream.cancel();
+                }
+                return;
+            }
             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]
@@ -2865,27 +3676,36 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
                 }
                 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) {
                     throw new UserError("Operation cancelled.");
                 }
             }
-            const result = await invokeWithHumanInLoop(state.command, context, runtimeOptions, state.commandPath);
+            const result = state.command.humanInLoop && humanInLoop !== undefined
+                ? await humanInLoop.invoke(state.command, context, state.commandPath)
+                : await state.command.handler(context);
             if (output === "rich" && runtime.isFixture) {
                 writeRichHeader(`${state.command.name} (fixture)`);
             }
-            if (isHumanInLoopPending(result)) {
-                renderHumanInLoopPending(result);
+            invocation?.signal.throwIfAborted();
+            const pendingApproval = isHumanInLoopPending(result);
+            if (pendingApproval && output === "rich") {
+                renderHumanInLoopPending(result, rootUsageName, outputEmitter);
                 return;
             }
-            const renderStatus = renderResult(state.command, result, output, primitives);
+            const renderStatus = renderCLIResult(pendingApproval ? { ...state.command, render: undefined } : state.command, state.commandPath, result, output, primitives, outputFormats, invocation?.write ?? (outputEmitter === undefined
+                ? undefined
+                : (chunk) => outputEmitter(chunk.endsWith("\n") ? chunk.slice(0, -1) : chunk)), outputEmitter);
             if (renderStatus.mcpError) {
-                process.exitCode = 1;
+                if (invocation)
+                    invocation.exitCode = 1;
+                else
+                    process.exitCode = 1;
             }
         });
     }
@@ -2899,6 +3719,25 @@ async function executeCommand(state, services, requirementOptions, runtimeFetch,
         throw error;
     }
 }
+function renderCLIResult(command, commandPath, result, output, primitives, outputFormats, write, emitExact) {
+    const customRenderer = outputFormats[output];
+    if (customRenderer === undefined) {
+        return renderResult(command, result, output, primitives, write);
+    }
+    const payload = customRenderer({ command, commandPath, primitives, result });
+    if (payload !== undefined && payload.length > 0) {
+        if (emitExact !== undefined) {
+            emitExact(payload);
+        }
+        else if (write === undefined) {
+            process.stdout.write(payload);
+        }
+        else {
+            write(payload);
+        }
+    }
+    return { mcpError: false };
+}
 function isStringRecord(value) {
     return isPlainObject(value) && Object.values(value).every((entry) => typeof entry === "string");
 }
@@ -3085,7 +3924,9 @@ function renderHttpError(error, options) {
         else {
             lines.push(`Response body: ${formatHttpErrorSnippet(error.response.body)}`);
         }
-        lines.push("Re-run with --verbose to see headers and full body.");
+        if (options.verboseControlEnabled) {
+            lines.push("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;
@@ -3094,13 +3935,14 @@ function renderHttpError(error, options) {
     }
 }
 async function handleRunError(error, options) {
-    const logger = createLogger();
-    await withOutputFormat(options.output, async () => {
-        if (error instanceof UserError) {
+    const logger = createLogger(options.outputEmitter);
+    await withOutputFormat(toDesignSystemOutput(options.output), async () => {
+        if (isUserError(error)) {
             renderCliErrorPattern(options.userErrorPattern === "definition"
                 ? {
                     kind: "definition",
                     error,
+                    debugControlEnabled: options.debugControlEnabled,
                     debugStackMode: options.debugStackMode
                 }
                 : options.userErrorPattern === "usage"
@@ -3113,15 +3955,16 @@ async function handleRunError(error, options) {
                     : {
                         kind: "runtime-user",
                         message: error.message
-                    });
+                    }, options.outputEmitter);
             return;
         }
         if (error instanceof Error && error.name === "ToolcraftBugError") {
             renderCliErrorPattern({
                 kind: "toolcraft-bug",
                 error,
+                debugControlEnabled: options.debugControlEnabled,
                 debugStackMode: options.debugStackMode
-            });
+            }, options.outputEmitter);
             return;
         }
         if (error instanceof CommanderError) {
@@ -3164,8 +4007,9 @@ async function handleRunError(error, options) {
             kind: "unexpected",
             message,
             stack: error instanceof Error ? error.stack : undefined,
+            debugControlEnabled: options.debugControlEnabled,
             debugStackMode: options.debugStackMode
-        });
+        }, options.outputEmitter);
     });
 }
 function formatCommanderErrorMessage(error) {
@@ -3384,7 +4228,7 @@ function isCommandNameCharacter(character) {
     const isLowercaseLetter = code >= 97 && code <= 122;
     const isUppercaseLetter = code >= 65 && code <= 90;
     const isDigit = code >= 48 && code <= 57;
-    return isLowercaseLetter || isUppercaseLetter || isDigit || character === "-" || character === "_";
+    return (isLowercaseLetter || isUppercaseLetter || isDigit || character === "-" || character === "_");
 }
 function getDefaultCommanderCommandName(command) {
     const candidate = command;
@@ -3392,57 +4236,65 @@ 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({
-        outputError: (message, write) => {
-            if (message.includes("unknown command") || message.includes("unknown option")) {
-                return;
-            }
-            write(message);
-        }
+        // 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();
+    await executeCLICommand(roots, options);
+}
+/** Shared parser, validation and dispatch; native callers supply a local runtime. */
+export async function executeCLICommand(roots, options, invocation) {
     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 {
         const normalizedRoot = normalizeRoots(roots, argv);
-        const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
-        await resolveMcpProxies(root, { projectRoot: options.projectRoot });
+        const root = mergeApprovalsRoot(normalizedRoot, options);
+        assertHumanInLoopWired(root, options.humanInLoop);
+        if (hasMcpProxyConfig(root)) {
+            if (invocation)
+                throw new UserError("MCP proxy discovery requires the standalone CLI; native library plugins support in-process handlers only.");
+            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 ?? {});
-        const runtimeOptions = options.humanInLoop ?? {};
+        const humanInLoop = options.humanInLoop;
         const runtimeFetch = options.fetch ?? globalThis.fetch;
-        version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
+        version = options.version ?? (invocation ? undefined : findEntrypointPackageMetadata(argv[1])?.version);
         const servicesWithBuiltIns = {
             ...services,
-            runtimeOptions,
+            humanInLoop,
             root
         };
         const requirementOptions = {
-            apiVersion: options.apiVersion
+            apiVersion: options.apiVersion,
+            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 });
+            await renderGeneratedHelp(root, argv, { ...options, version }, invocation);
             return;
         }
         program = new CommanderCommand();
@@ -3452,6 +4304,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");
@@ -3462,19 +4315,22 @@ export async function runCLI(roots, options = {}) {
         const execute = async (state) => {
             lastActionCommand = state.actionCommand;
             resolvedCommandPath = formatCliCommandPath(state.commandPath);
-            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, {
+            await executeCommand(state, rootUsageName, servicesWithBuiltIns, requirementOptions, runtimeFetch, humanInLoop, options.env, options.fs, options.outputEmitter, controls.outputFormats, {
+                input: options.promptInput,
+                output: options.promptOutput
+            }, {
                 logLevel: options.logLevel,
                 logger: options.logger,
                 verboseControlEnabled: controls.verbose
             }, (context) => {
                 errorReportContext = context;
-            });
+            }, invocation);
         };
         const rootChildNames = new Set(root.children
             .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;
             }
@@ -3483,25 +4339,60 @@ 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);
+        if (invocation) {
+            const configure = (command) => {
+                command.configureOutput({ writeOut: chunk => invocation.write(chunk), writeErr: chunk => invocation.write(chunk, "stderr") });
+                command.commands.forEach(configure);
+            };
+            configure(program);
+        }
+        const prepared = prepareCliArguments(program, argv, fieldLoaders, casing, controls);
+        argv = prepared.argv;
+        if (prepared.helpArgv !== undefined) {
+            userErrorPattern = "usage";
+            await renderGeneratedHelp(root, prepared.helpArgv, { ...options, version }, invocation);
+            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;
+            if (invocation)
+                throw new UserError(formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand));
+            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) {
-        if (error instanceof ApprovalDeclinedError) {
-            renderApprovalDeclined(error);
+        if (invocation) {
+            if (invocation.signal.aborted)
+                throw invocation.signal.reason;
+            invocation.exitCode = error instanceof CommanderError ? error.exitCode : 1;
+            if (!(error instanceof CommanderError && error.exitCode === 0)) {
+                invocation.write(`${error instanceof Error ? error.message : String(error)}\n`, "stderr");
+            }
             return;
         }
         const resolvedFlags = lastActionCommand ? getResolvedFlags(lastActionCommand) : undefined;
+        if (error instanceof ApprovalDeclinedError) {
+            await withOutputFormat(toDesignSystemOutput(resolvedFlags !== undefined
+                ? resolveOutput(resolvedFlags)
+                : resolveOutputFromArgv(argv, controls.outputFormats)), async () => {
+                renderCliErrorPattern({ kind: "runtime-user", message: error.message }, options.outputEmitter);
+            });
+            return;
+        }
         const report = await writeErrorReport({
             argv,
             command: errorReportContext?.command,
@@ -3518,16 +4409,35 @@ export async function runCLI(roots, options = {}) {
             process.stderr.write(`Saved error report to ${report.displayPath}\n`);
         }
         await handleRunError(error, {
-            debugStackMode: resolvedFlags !== undefined
-                ? resolveDebugStackMode(resolvedFlags.debug)
-                : getDebugStackModeFromArgv(argv),
-            output: resolvedFlags !== undefined ? resolveOutput(resolvedFlags) : resolveOutputFromArgv(argv),
+            debugControlEnabled: controls.debug,
+            debugStackMode: controls.debug
+                ? resolvedFlags !== undefined
+                    ? resolveDebugStackMode(resolvedFlags.debug)
+                    : getDebugStackModeFromArgv(argv)
+                : undefined,
+            output: resolvedFlags !== undefined
+                ? resolveOutput(resolvedFlags)
+                : resolveOutputFromArgv(argv, controls.outputFormats),
             verbose: resolvedFlags ? Boolean(resolvedFlags.verbose) : argv.includes("--verbose"),
+            verboseControlEnabled: controls.verbose,
             program,
             argv,
             rootUsageName,
             commandPath: resolvedCommandPath,
+            outputEmitter: options.outputEmitter,
             userErrorPattern: errorReportContext?.params === undefined ? userErrorPattern : "runtime-user"
         });
     }
+    finally {
+        await invocation?.flush();
+        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`);
+            }
+        }
+    }
 }