toolcraft 0.0.2 → 0.0.3

package/dist/cli.js

@@ -2,10 +2,14 @@ import { access, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Option } from "commander";
 import { cancel, confirm, createLogger, formatCommandList, formatOptionList, getTheme, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text, } from "@poe-code/design-system";
-import { UserError, assertCommandRequirements, getCommandSourcePath, resolveCommandSecrets } from "./index.js";
+import { ApprovalDeclinedError, UserError, assertCommandRequirements, getCommandSourcePath, resolveCommandSecrets } from "./index.js";
+import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
+import { invokeWithHumanInLoop } from "./human-in-loop/index.js";
+import { resolveMcpProxies } from "./mcp-proxy.js";
 import { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
 import { renderResult } from "./renderer.js";
 const RESERVED_SERVICE_NAMES = new Set(["params", "secrets", "fetch", "fs", "env", "progress"]);
+const NULL_OPTION_VALUE = Symbol("toolcraft.cli.null");
 function inferProgramName(argv) {
     const entrypoint = argv[1];
     if (typeof entrypoint !== "string" || entrypoint.length === 0) {
@@ -89,17 +93,198 @@ function toOptionAttribute(path, casing) {
 function toDisplayPath(path) {
     return path.join(".");
 }
-function collectFields(schema, casing, path = [], inheritedOptional = false) {
-    const fields = [];
+function toUnionKindControlPath(path) {
+    if (path.length === 0) {
+        return ["kind"];
+    }
+    const head = path.slice(0, -1);
+    const tail = path[path.length - 1] ?? "";
+    return [...head, `${tail}Kind`];
+}
+function toUnionKindDisplayPath(path) {
+    if (path.length === 0) {
+        return "kind";
+    }
+    const head = path.slice(0, -1);
+    const tail = path[path.length - 1] ?? "";
+    return [...head, `${tail}-kind`].join(".");
+}
+function createSyntheticEnumSchema(values) {
+    if (values.length === 0) {
+        throw new Error("Synthetic enum schema requires at least one value.");
+    }
+    return {
+        kind: "enum",
+        values: values,
+    };
+}
+function getRequiredBranchFingerprint(branch, casing) {
+    const requiredKeys = Object.entries(branch.shape)
+        .filter(([, schema]) => schema.kind !== "optional")
+        .map(([key]) => formatSegment(key, casing))
+        .sort();
+    return requiredKeys.join("+");
+}
+function collectFields(schema, casing, path = [], inheritedOptional = false, variantContext) {
+    const collected = {
+        dynamicFields: [],
+        fields: [],
+        variants: [],
+    };
     for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
         const nextPath = [...path, key];
-        const optional = inheritedOptional || rawChildSchema.kind === "optional";
+        const runtimeOptional = inheritedOptional || rawChildSchema.kind === "optional";
         const childSchema = unwrapOptional(rawChildSchema);
+        const requiredWhenActive = rawChildSchema.kind !== "optional" && childSchema.default === undefined;
         if (childSchema.kind === "object") {
-            fields.push(...collectFields(childSchema, casing, nextPath, optional));
+            const nested = collectFields(childSchema, casing, nextPath, runtimeOptional, variantContext);
+            collected.dynamicFields.push(...nested.dynamicFields);
+            collected.fields.push(...nested.fields);
+            collected.variants.push(...nested.variants);
+            continue;
+        }
+        if (childSchema.kind === "oneOf") {
+            const variantId = `${toDisplayPath(nextPath)}:oneOf`;
+            const branchIds = Object.keys(childSchema.branches);
+            const controlField = {
+                id: toDisplayPath([...nextPath, childSchema.discriminator]),
+                path: [...nextPath, childSchema.discriminator],
+                displayPath: toDisplayPath([...nextPath, childSchema.discriminator]),
+                optionAttribute: toOptionAttribute([...nextPath, childSchema.discriminator], casing),
+                commanderOptionAttribute: toCommanderOptionAttribute([...nextPath, childSchema.discriminator], casing),
+                optionFlag: toOptionFlag([...nextPath, childSchema.discriminator], casing),
+                shortFlag: undefined,
+                schema: createSyntheticEnumSchema(branchIds),
+                description: childSchema.description,
+                optional: runtimeOptional,
+                hasDefault: false,
+                defaultValue: undefined,
+                requiredWhenActive,
+            };
+            collected.fields.push(controlField);
+            const branches = [];
+            for (const [branchId, branchSchema] of Object.entries(childSchema.branches)) {
+                const branch = collectFields(branchSchema, casing, nextPath, true, {
+                    id: variantId,
+                    branchId,
+                });
+                collected.dynamicFields.push(...branch.dynamicFields);
+                collected.fields.push(...branch.fields);
+                collected.variants.push(...branch.variants);
+                branches.push({
+                    branchId,
+                    dynamicFieldIds: branch.dynamicFields.map((field) => field.id),
+                    fieldIds: branch.fields.map((field) => field.id),
+                    requiredDynamicFieldIds: branch.dynamicFields
+                        .filter((field) => field.requiredWhenActive)
+                        .map((field) => field.id),
+                    requiredFieldIds: branch.fields
+                        .filter((field) => field.requiredWhenActive)
+                        .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 controlField = {
+                id: controlDisplayPath,
+                path: controlPath,
+                displayPath: controlDisplayPath,
+                optionAttribute: toOptionAttribute(controlPath, casing),
+                commanderOptionAttribute: toCommanderOptionAttribute(controlPath, casing),
+                optionFlag: toOptionFlag(controlPath, casing),
+                shortFlag: undefined,
+                schema: createSyntheticEnumSchema(branchIds),
+                description: childSchema.description,
+                optional: runtimeOptional,
+                hasDefault: false,
+                defaultValue: undefined,
+                requiredWhenActive,
+                synthetic: true,
+            };
+            collected.fields.push(controlField);
+            const branches = [];
+            childSchema.branches.forEach((branchSchema, index) => {
+                const branchId = branchIds[index] ?? "";
+                const branch = collectFields(branchSchema, casing, nextPath, true, {
+                    id: variantId,
+                    branchId,
+                });
+                collected.dynamicFields.push(...branch.dynamicFields);
+                collected.fields.push(...branch.fields);
+                collected.variants.push(...branch.variants);
+                branches.push({
+                    branchId,
+                    dynamicFieldIds: branch.dynamicFields.map((field) => field.id),
+                    fieldIds: branch.fields.map((field) => field.id),
+                    requiredDynamicFieldIds: branch.dynamicFields
+                        .filter((field) => field.requiredWhenActive)
+                        .map((field) => field.id),
+                    requiredFieldIds: branch.fields
+                        .filter((field) => field.requiredWhenActive)
+                        .map((field) => field.id),
+                });
+            });
+            collected.variants.push({
+                id: variantId,
+                controlDisplayPath,
+                controlFieldId: controlField.id,
+                optional: runtimeOptional,
+                branches,
+            });
+            continue;
+        }
+        if (childSchema.kind === "record") {
+            collected.dynamicFields.push({
+                id: toDisplayPath(nextPath),
+                path: nextPath,
+                displayPath: toDisplayPath(nextPath),
+                optionPath: nextPath,
+                optionPathDisplay: `${toDisplayPath(nextPath)}.<key>`,
+                optionFlag: `${toOptionFlag(nextPath, casing)}.<key>`,
+                description: childSchema.description,
+                optional: runtimeOptional,
+                hasDefault: childSchema.default !== undefined,
+                defaultValue: childSchema.default,
+                requiredWhenActive,
+                schema: childSchema,
+                variantId: variantContext?.id,
+                variantBranchId: variantContext?.branchId,
+            });
+            continue;
+        }
+        if (childSchema.kind === "array" && unwrapOptional(childSchema.item).kind === "object") {
+            collected.dynamicFields.push({
+                id: toDisplayPath(nextPath),
+                path: nextPath,
+                displayPath: toDisplayPath(nextPath),
+                optionPath: nextPath,
+                optionPathDisplay: `${toDisplayPath(nextPath)}.<index>`,
+                optionFlag: `${toOptionFlag(nextPath, casing)}.<index>`,
+                description: childSchema.description,
+                optional: runtimeOptional,
+                hasDefault: childSchema.default !== undefined,
+                defaultValue: childSchema.default,
+                requiredWhenActive,
+                schema: childSchema,
+                variantId: variantContext?.id,
+                variantBranchId: variantContext?.branchId,
+            });
             continue;
         }
-        fields.push({
+        collected.fields.push({
+            id: toDisplayPath(nextPath),
             path: nextPath,
             displayPath: toDisplayPath(nextPath),
             optionAttribute: toOptionAttribute(nextPath, casing),
@@ -108,12 +293,15 @@ function collectFields(schema, casing, path = [], inheritedOptional = false) {
             shortFlag: childSchema.short,
             schema: childSchema,
             description: childSchema.description,
-            optional,
+            optional: runtimeOptional,
             hasDefault: childSchema.default !== undefined,
             defaultValue: childSchema.default,
+            requiredWhenActive,
+            variantId: variantContext?.id,
+            variantBranchId: variantContext?.branchId,
         });
     }
-    return fields;
+    return collected;
 }
 function toCommanderOptionAttribute(path, casing) {
     const optionAttribute = toOptionAttribute(path, casing);
@@ -185,10 +373,36 @@ function parseEnumValue(value, values, label) {
     }
     return match;
 }
+function validateStringPattern(value, schema, label) {
+    if (schema.pattern === undefined) {
+        return value;
+    }
+    if (!matchesStringPattern(value, schema.pattern)) {
+        throw new UserError(`Invalid value for "${label}": "${value}" does not match pattern "${schema.pattern}".`);
+    }
+    return value;
+}
+function matchesStringPattern(value, pattern) {
+    return new RegExp(pattern).test(value);
+}
+function parseJsonText(value, label) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        throw new InvalidArgumentError(`Invalid value for "${label}". Expected valid JSON.`);
+    }
+}
+function normalizeCommanderOptionValue(value) {
+    return value === NULL_OPTION_VALUE ? null : value;
+}
 function parseScalarValue(value, schema, label) {
+    if (value === "null" && schema.nullable === true) {
+        return null;
+    }
     switch (schema.kind) {
         case "string":
-            return value;
+            return validateStringPattern(value, schema, label);
         case "number": {
             const parsed = Number(value);
             if (!isValidNumberSchemaValue(parsed, schema)) {
@@ -200,9 +414,8 @@ function parseScalarValue(value, schema, label) {
             return parseBooleanText(value, label);
         case "enum":
             return parseEnumValue(value, schema.values, label);
-        default:
-            throw new UserError(`Unsupported CLI schema kind "${schema.kind}".`);
     }
+    throw new UserError("Unsupported CLI schema kind.");
 }
 function splitArrayInput(value) {
     const items = [];
@@ -226,6 +439,9 @@ function splitArrayInput(value) {
     return items;
 }
 function parseArrayValue(value, schema, label) {
+    if (value === "null" && schema.nullable === true) {
+        return null;
+    }
     const itemSchema = unwrapOptional(schema.item);
     if (itemSchema.kind === "array" || itemSchema.kind === "object") {
         throw new UserError(`Array parameter "${label}" must use scalar items.`);
@@ -235,6 +451,7 @@ function parseArrayValue(value, schema, label) {
 function createOption(field) {
     const flags = formatOptionFlags(field);
     const collidesWithGlobalFlag = GLOBAL_LONG_OPTION_FLAGS.has(field.optionFlag);
+    const commanderValue = (value) => (value === null ? NULL_OPTION_VALUE : value);
     if (field.schema.kind === "boolean") {
         if (collidesWithGlobalFlag) {
             return [createCommanderOption(flags, field.description, field)];
@@ -242,7 +459,7 @@ function createOption(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 : parseBooleanText(value, field.displayPath));
+        mainOption.argParser((value) => typeof value === "boolean" ? value : commanderValue(parseBooleanText(value, field.displayPath)));
         return [
             mainOption,
             createCommanderOption(`--no-${field.optionFlag.slice(2)}`, field.description, field),
@@ -250,17 +467,25 @@ function createOption(field) {
     }
     if (field.schema.kind === "array") {
         return [
-            createCommanderOption(`${flags} <value...>`, field.description, field).argParser((value, previous = []) => [
-                ...previous,
-                ...parseArrayValue(value, field.schema, field.displayPath),
-            ]),
+            createCommanderOption(`${flags} <value...>`, field.description, field).argParser((value, previous = []) => {
+                const parsed = parseArrayValue(value, field.schema, field.displayPath);
+                if (parsed === null) {
+                    return NULL_OPTION_VALUE;
+                }
+                return [...(previous ?? []), ...parsed];
+            }),
+        ];
+    }
+    if (field.schema.kind === "json") {
+        return [
+            createCommanderOption(`${flags} <json>`, field.description, field).argParser((value) => commanderValue(parseJsonText(value, field.displayPath))),
         ];
     }
     const option = createCommanderOption(`${flags} <value>`, field.description, field);
     if (field.schema.kind === "enum" && field.schema.values.every((value) => typeof value === "string")) {
         option.choices([...field.schema.values]);
     }
-    option.argParser((value) => parseScalarValue(value, field.schema, field.displayPath));
+    option.argParser((value) => commanderValue(parseScalarValue(value, field.schema, field.displayPath)));
     return [option];
 }
 const GLOBAL_LONG_OPTION_FLAGS = new Set(["--preset", "--yes", "--output", "--verbose"]);
@@ -348,6 +573,8 @@ function describeSchemaType(schema) {
             return "value";
         case "array":
             return `${describeSchemaType(unwrapOptional(schema.item))}...`;
+        case "json":
+            return "json";
         default:
             throw new UserError("Unsupported CLI schema kind.");
     }
@@ -381,6 +608,96 @@ function formatHelpFieldDescription(field) {
     }
     return appendHelpMetadata(description, metadata);
 }
+function describeDynamicFieldType(field) {
+    if (field.schema.kind === "record") {
+        const valueSchema = unwrapOptional(field.schema.value);
+        if (valueSchema.kind === "json") {
+            return "json";
+        }
+        if (valueSchema.kind === "array") {
+            return `${describeSchemaType(valueSchema)}`;
+        }
+        if (valueSchema.kind === "object") {
+            return "value";
+        }
+        return describeSchemaType(valueSchema);
+    }
+    return "value";
+}
+function formatDynamicHelpMetadata(field) {
+    const metadata = [];
+    if (!field.optional && !field.hasDefault) {
+        metadata.push("required");
+    }
+    if (field.hasDefault) {
+        metadata.push(`default: ${formatResolvedValue(field.defaultValue)}`);
+    }
+    return metadata;
+}
+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 displayPath = `${displayPrefix}.${key}`;
+        const description = childSchema.description ?? 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),
+            });
+            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"
+                ? `${optionFlag} [value]`
+                : `${optionFlag} <${describeSchemaType(childSchema)}>`,
+            description: appendHelpMetadata(description, metadata),
+        });
+    }
+    return rows;
+}
+function formatDynamicHelpFields(field, casing) {
+    const metadata = formatDynamicHelpMetadata(field);
+    if (field.schema.kind === "record") {
+        const valueSchema = unwrapOptional(field.schema.value);
+        if (valueSchema.kind === "object") {
+            return collectDynamicObjectHelpRows(valueSchema, casing, `${field.optionFlag}`, `${field.optionPathDisplay}`, metadata);
+        }
+    }
+    if (field.schema.kind === "array") {
+        const itemSchema = unwrapOptional(field.schema.item);
+        if (itemSchema.kind === "object") {
+            return collectDynamicObjectHelpRows(itemSchema, casing, `${field.optionFlag}`, `${field.optionPathDisplay}`, metadata);
+        }
+    }
+    return [{
+            flags: `${field.optionFlag} <${describeDynamicFieldType(field)}>`,
+            description: appendHelpMetadata(field.description ?? field.optionPathDisplay, metadata),
+        }];
+}
 function formatSecretRows(secrets) {
     return Object.values(secrets).map((secret) => ({
         flags: secret.env,
@@ -453,11 +770,12 @@ function renderGroupHelp(group, breadcrumb, scope, showVersion, rootUsageName) {
 }
 function renderLeafHelp(command, breadcrumb, casing, rootUsageName) {
     const sections = [];
-    const fields = assignPositionals(collectFields(command.params, casing), command.positional);
+    const collected = collectFields(command.params, casing);
+    const fields = assignPositionals(collected.fields, command.positional);
     const optionRows = fields.map((field) => ({
         flags: formatHelpFieldFlags(field),
         description: formatHelpFieldDescription(field),
-    }));
+    })).concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
     if (optionRows.length > 0) {
         sections.push(`${text.section("Options:")}\n${formatOptionList(optionRows)}`);
     }
@@ -506,19 +824,25 @@ async function renderGeneratedHelp(root, argv, options) {
         process.stdout.write(rendered);
     });
 }
-function createNodeCommand(node, casing, execute) {
+function createNodeCommand(node, casing, execute, pathSegments = []) {
+    const nextPathSegments = [...pathSegments, node.name];
     if (node.kind === "command") {
         if (!node.scope.includes("cli")) {
             return null;
         }
         const command = new CommanderCommand(node.name);
-        const fields = assignPositionals(collectFields(node.params, casing), node.positional);
+        const collected = collectFields(node.params, casing);
+        const fields = assignPositionals(collected.fields, node.positional);
         if (node.description !== undefined) {
             command.description(node.description);
         }
         node.aliases.forEach((alias) => command.alias(alias));
         command.addHelpCommand(false);
         addGlobalOptions(command);
+        command.allowExcessArguments(true);
+        if (collected.dynamicFields.length > 0) {
+            command.allowUnknownOption(true);
+        }
         for (const field of fields) {
             if (field.positionalIndex !== undefined) {
                 command.argument(formatPositionalToken(field));
@@ -533,9 +857,14 @@ function createNodeCommand(node, casing, execute) {
             const positionalValues = args.slice(0, -2);
             await execute({
                 command: node,
+                commandPath: nextPathSegments.join("."),
+                casing,
+                dynamicFields: collected.dynamicFields,
                 fields,
                 positionalValues,
+                rawArgv: actionCommand.args,
                 actionCommand,
+                variants: collected.variants,
             });
         });
         return command;
@@ -544,7 +873,7 @@ function createNodeCommand(node, casing, execute) {
         return null;
     }
     const visibleChildren = node.children
-        .map((child) => createNodeCommand(child, casing, execute))
+        .map((child) => createNodeCommand(child, casing, execute, nextPathSegments))
         .filter((child) => child !== null);
     const group = new CommanderCommand(node.name);
     if (node.description !== undefined) {
@@ -653,6 +982,12 @@ async function promptForField(field) {
     if (field.schema.kind === "array") {
         return parseArrayValue(entered, field.schema, field.displayPath);
     }
+    if (field.schema.kind === "json") {
+        if (entered === "null" && field.schema.nullable === true) {
+            return null;
+        }
+        return parseJsonText(entered, field.displayPath);
+    }
     return parseScalarValue(entered, field.schema, field.displayPath);
 }
 function resolveOutput(resolvedFlags) {
@@ -727,6 +1062,9 @@ function describeExpectedPresetValue(schema) {
     if (schema.kind === "array") {
         return "an array";
     }
+    if (schema.kind === "json") {
+        return "valid JSON";
+    }
     if (schema.kind === "enum") {
         return `one of: ${schema.values.map((value) => JSON.stringify(value)).join(", ")}`;
     }
@@ -741,6 +1079,9 @@ function validatePresetScalarValue(value, schema, fieldPath, presetPath) {
             if (typeof value !== "string") {
                 break;
             }
+            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)) {
@@ -759,12 +1100,13 @@ function validatePresetScalarValue(value, schema, fieldPath, presetPath) {
             }
             break;
         }
-        default:
-            throw new UserError(`Unsupported CLI schema kind "${schema.kind}".`);
     }
     throw new UserError(`Preset file "${presetPath}" has an invalid value for "${fieldPath}". Expected ${describeExpectedPresetValue(schema)}.`);
 }
 function validatePresetFieldValue(value, field, presetPath) {
+    if (field.schema.kind === "json") {
+        return value;
+    }
     if (field.schema.kind !== "array") {
         return validatePresetScalarValue(value, field.schema, field.displayPath, presetPath);
     }
@@ -1121,6 +1463,24 @@ function writeRichHeader(title) {
     const padding = Math.max(12, 34 - title.length);
     process.stdout.write(`── ${title} ${"─".repeat(padding)}\n`);
 }
+function isHumanInLoopPending(result) {
+    return (typeof result === "object" &&
+        result !== null &&
+        result.status === "pending-approval" &&
+        typeof result.approvalId === "string" &&
+        typeof result.message === "string" &&
+        typeof result.enqueuedAt === "string");
+}
+function renderHumanInLoopPending(pending) {
+    process.stdout.write(`✓ 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;
+}
 function validateServices(services) {
     for (const name of Object.keys(services)) {
         if (RESERVED_SERVICE_NAMES.has(name)) {
@@ -1128,13 +1488,336 @@ function validateServices(services) {
         }
     }
 }
-async function resolveParams(fields, positionalValues, optionValues, presetPath, shouldPrompt) {
+function getNestedValue(target, path) {
+    return path.reduce((current, segment) => current !== null && typeof current === "object"
+        ? current[segment]
+        : undefined, target);
+}
+function parseFieldInputValue(value, schema, label) {
+    if (schema.kind === "array") {
+        return parseArrayValue(value, schema, label);
+    }
+    if (schema.kind === "json") {
+        if (value === "null" && schema.nullable === true) {
+            return null;
+        }
+        return parseJsonText(value, label);
+    }
+    return parseScalarValue(value, schema, label);
+}
+function consumeFieldValue(args, index, schema, label, inlineValue) {
+    if (schema.kind === "boolean") {
+        if (inlineValue !== undefined) {
+            return {
+                nextIndex: index,
+                value: parseScalarValue(inlineValue, schema, label),
+            };
+        }
+        const next = args[index + 1];
+        if (next === "true" || next === "false" || (schema.nullable === true && next === "null")) {
+            return {
+                nextIndex: index + 1,
+                value: parseScalarValue(next, schema, label),
+            };
+        }
+        return {
+            nextIndex: index,
+            value: true,
+        };
+    }
+    if (inlineValue !== undefined) {
+        return {
+            nextIndex: index,
+            value: parseFieldInputValue(inlineValue, schema, label),
+        };
+    }
+    if (schema.kind === "array") {
+        const values = [];
+        let nextIndex = index;
+        let cursor = index + 1;
+        while (cursor < args.length) {
+            const token = args[cursor] ?? "";
+            if (token.startsWith("-")) {
+                break;
+            }
+            const parsed = parseArrayValue(token, schema, label);
+            if (parsed === null) {
+                return {
+                    nextIndex: cursor,
+                    value: null,
+                };
+            }
+            values.push(...parsed);
+            nextIndex = cursor;
+            cursor += 1;
+        }
+        if (values.length === 0) {
+            throw new InvalidArgumentError(`option '${label}' argument missing`);
+        }
+        return {
+            nextIndex,
+            value: values,
+        };
+    }
+    const next = args[index + 1];
+    if (next === undefined) {
+        throw new InvalidArgumentError(`option '${label}' argument missing`);
+    }
+    return {
+        nextIndex: index + 1,
+        value: parseFieldInputValue(next, schema, label),
+    };
+}
+function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displayPath = []) {
+    const unwrappedSchema = unwrapOptional(schema);
+    if (rawSegments.length === 0) {
+        if (unwrappedSchema.kind === "json" ||
+            unwrappedSchema.kind === "array" ||
+            unwrappedSchema.kind === "string" ||
+            unwrappedSchema.kind === "number" ||
+            unwrappedSchema.kind === "boolean" ||
+            unwrappedSchema.kind === "enum") {
+            return {
+                displayPath: toDisplayPath(displayPath),
+                path: outputPath,
+                schema: unwrappedSchema,
+            };
+        }
+        throw new UserError(`Unsupported dynamic CLI schema kind "${unwrappedSchema.kind}".`);
+    }
+    switch (unwrappedSchema.kind) {
+        case "object": {
+            const [head, ...rest] = rawSegments;
+            for (const [key, childSchema] of Object.entries(unwrappedSchema.shape)) {
+                if (formatSegment(key, casing) !== head) {
+                    continue;
+                }
+                return resolveDynamicLeaf(childSchema, rest, casing, [...outputPath, key], [...displayPath, key]);
+            }
+            throw new UserError(`Unknown parameter "${[...displayPath, head].join(".")}".`);
+        }
+        case "record": {
+            const [head, ...rest] = rawSegments;
+            return resolveDynamicLeaf(unwrappedSchema.value, rest, casing, [...outputPath, head ?? ""], [...displayPath, head ?? ""]);
+        }
+        case "array": {
+            const itemSchema = unwrapOptional(unwrappedSchema.item);
+            if (itemSchema.kind !== "object") {
+                throw new UserError(`Array parameter "${toDisplayPath(displayPath)}" must use object items.`);
+            }
+            const [head, ...rest] = rawSegments;
+            if (head === undefined || !isNumericFixtureSelector(head)) {
+                throw new UserError(`Array parameter "${toDisplayPath(displayPath)}" must use numeric indices.`);
+            }
+            return resolveDynamicLeaf(itemSchema, rest, casing, [...outputPath, head], [...displayPath, head]);
+        }
+        default:
+            throw new UserError(`Unknown parameter "${[...displayPath, ...rawSegments].join(".")}".`);
+    }
+}
+function finalizeDynamicValue(schema, value, displayPath) {
+    const unwrappedSchema = unwrapOptional(schema);
+    if (value === undefined) {
+        return undefined;
+    }
+    if (value === null && unwrappedSchema.nullable === true) {
+        return null;
+    }
+    switch (unwrappedSchema.kind) {
+        case "string":
+        case "number":
+        case "boolean":
+        case "enum":
+        case "json":
+            return value;
+        case "array": {
+            const itemSchema = unwrapOptional(unwrappedSchema.item);
+            if (itemSchema.kind !== "object") {
+                return value;
+            }
+            if (!isPlainObject(value)) {
+                throw new UserError(`Invalid value for "${displayPath}". Expected indexed object entries.`);
+            }
+            const entries = Object.entries(value);
+            const indices = entries.map(([key]) => Number(key)).sort((left, right) => left - right);
+            if (indices.some((index) => !Number.isInteger(index) || index < 0)) {
+                throw new UserError(`Array parameter "${displayPath}" must use numeric indices.`);
+            }
+            for (let index = 0; index < indices.length; index += 1) {
+                if (indices[index] !== index) {
+                    throw new UserError(`Array parameter "${displayPath}" must use contiguous indices starting at 0.`);
+                }
+            }
+            return indices.map((index) => finalizeDynamicValue(unwrappedSchema.item, value[String(index)], `${displayPath}.${index}`));
+        }
+        case "object": {
+            if (!isPlainObject(value)) {
+                throw new UserError(`Invalid value for "${displayPath}". Expected an object.`);
+            }
+            const result = {};
+            for (const [key, rawChildSchema] of Object.entries(unwrappedSchema.shape)) {
+                const childSchema = unwrapOptional(rawChildSchema);
+                const childValue = value[key];
+                const childDisplayPath = displayPath.length === 0 ? key : `${displayPath}.${key}`;
+                if (childValue === undefined) {
+                    if (childSchema.default !== undefined) {
+                        result[key] = childSchema.default;
+                        continue;
+                    }
+                    if (rawChildSchema.kind === "optional") {
+                        continue;
+                    }
+                    throw new UserError(`Missing required parameter "${childDisplayPath}".`);
+                }
+                result[key] = finalizeDynamicValue(rawChildSchema, childValue, childDisplayPath);
+            }
+            return result;
+        }
+        case "record": {
+            if (!isPlainObject(value)) {
+                throw new UserError(`Invalid value for "${displayPath}". Expected an object.`);
+            }
+            return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [
+                key,
+                finalizeDynamicValue(unwrappedSchema.value, entryValue, displayPath.length === 0 ? key : `${displayPath}.${key}`),
+            ]));
+        }
+        default:
+            throw new UserError(`Unsupported dynamic CLI schema kind "${unwrappedSchema.kind}".`);
+    }
+}
+function parseDynamicValues(dynamicFields, rawArgv, casing) {
+    const rawValues = new Map();
+    const providedFieldIds = new Set();
+    const sortedFields = [...dynamicFields].sort((left, right) => right.optionPath.length - left.optionPath.length);
+    for (let index = 0; index < rawArgv.length; index += 1) {
+        const token = rawArgv[index] ?? "";
+        if (!token.startsWith("--")) {
+            continue;
+        }
+        const negated = token.startsWith("--no-");
+        const normalized = negated ? `--${token.slice("--no-".length)}` : token;
+        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) {
+            throw new UserError(`Unknown parameter "${flagName}".`);
+        }
+        const optionPath = match.optionPath.map((segment) => formatSegment(segment, casing));
+        const remainder = flagPath.slice(optionPath.length);
+        const leaf = resolveDynamicLeaf(match.schema, remainder, casing);
+        const rawStore = rawValues.get(match.id) ?? {};
+        const label = `${match.displayPath}.${leaf.displayPath}`.replace(/^\./u, "");
+        const parsed = negated && leaf.schema.kind === "boolean"
+            ? {
+                nextIndex: index,
+                value: false,
+            }
+            : consumeFieldValue(rawArgv, index, leaf.schema, label, inlineValue);
+        setNestedValue(rawStore, leaf.path, parsed.value);
+        rawValues.set(match.id, rawStore);
+        providedFieldIds.add(match.id);
+        index = parsed.nextIndex;
+    }
+    return {
+        providedFieldIds,
+        values: new Map(dynamicFields
+            .filter((field) => rawValues.has(field.id))
+            .map((field) => [
+            field.id,
+            finalizeDynamicValue(field.schema.kind === "record" ? field.schema : field.schema, rawValues.get(field.id), field.displayPath),
+        ])),
+    };
+}
+async function enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, providedDynamicFieldIds, providedFieldIds, shouldPrompt) {
+    const fieldById = new Map(fields.map((field) => [field.id, field]));
+    const dynamicFieldById = new Map(dynamicFields.map((field) => [field.id, field]));
+    for (const variant of variants) {
+        let selectedBranchId = resolvedFieldValues.get(variant.controlFieldId);
+        if (selectedBranchId === undefined && shouldPrompt) {
+            const controlField = fieldById.get(variant.controlFieldId);
+            if (controlField !== undefined) {
+                selectedBranchId = await promptForField(controlField);
+                resolvedFieldValues.set(controlField.id, selectedBranchId);
+                if (!controlField.synthetic) {
+                    setNestedValue(params, controlField.path, selectedBranchId);
+                }
+            }
+        }
+        if (selectedBranchId === undefined) {
+            if (variant.optional) {
+                continue;
+            }
+            throw new UserError(`Missing required parameter "${variant.controlDisplayPath}".`);
+        }
+        const selectedBranch = variant.branches.find((branch) => branch.branchId === selectedBranchId);
+        if (selectedBranch === undefined) {
+            throw new UserError(`Invalid value for "${variant.controlDisplayPath}". Expected one of: ${variant.branches.map((branch) => branch.branchId).join(", ")}.`);
+        }
+        for (const branch of variant.branches) {
+            if (branch.branchId === selectedBranch.branchId) {
+                continue;
+            }
+            const invalidFieldId = branch.fieldIds.find((fieldId) => providedFieldIds.has(fieldId));
+            if (invalidFieldId !== undefined) {
+                const field = fieldById.get(invalidFieldId);
+                if (field !== undefined) {
+                    throw new UserError(`Parameter "${field.displayPath}" is not valid when "${variant.controlDisplayPath}" is "${selectedBranch.branchId}".`);
+                }
+            }
+            const invalidDynamicFieldId = branch.dynamicFieldIds.find((fieldId) => providedDynamicFieldIds.has(fieldId));
+            if (invalidDynamicFieldId !== undefined) {
+                const field = dynamicFieldById.get(invalidDynamicFieldId);
+                if (field !== undefined) {
+                    throw new UserError(`Parameter "${field.displayPath}" is not valid when "${variant.controlDisplayPath}" is "${selectedBranch.branchId}".`);
+                }
+            }
+        }
+        for (const fieldId of selectedBranch.requiredFieldIds) {
+            const field = fieldById.get(fieldId);
+            if (field === undefined || field.synthetic) {
+                continue;
+            }
+            if (getNestedValue(params, field.path) !== undefined) {
+                continue;
+            }
+            if (shouldPrompt) {
+                const promptedValue = await promptForField(field);
+                resolvedFieldValues.set(field.id, promptedValue);
+                setNestedValue(params, field.path, promptedValue);
+                providedFieldIds.add(field.id);
+                continue;
+            }
+            throw new UserError(`Missing required parameter "${field.displayPath}".`);
+        }
+        for (const fieldId of selectedBranch.requiredDynamicFieldIds) {
+            const field = dynamicFieldById.get(fieldId);
+            if (field === undefined) {
+                continue;
+            }
+            if (getNestedValue(params, field.path) !== undefined) {
+                continue;
+            }
+            throw new UserError(`Missing required parameter "${field.displayPath}".`);
+        }
+    }
+}
+async function resolveParams(fields, dynamicFields, variants, positionalValues, optionValues, rawArgv, casing, presetPath, shouldPrompt) {
     const params = {};
     const presetValues = typeof presetPath === "string" && presetPath.length > 0
         ? await loadPresetValues(fields, presetPath)
         : {};
+    const providedFieldIds = new Set();
+    const resolvedFieldValues = new Map();
     for (const field of fields) {
         let value;
+        let source;
         if (field.positionalIndex !== undefined) {
             const positionalValue = positionalValues[field.positionalIndex];
             if (field.schema.kind === "array") {
@@ -1144,32 +1827,39 @@ async function resolveParams(fields, positionalValues, optionValues, presetPath,
                         throw new UserError(`Array parameter "${field.displayPath}" must use scalar items.`);
                     }
                     value = positionalValue.map((item) => parseScalarValue(String(item), itemSchema, field.displayPath));
+                    source = "positional";
                 }
             }
             else if (typeof positionalValue === "string" && positionalValue.length > 0) {
-                value = parseScalarValue(positionalValue, field.schema, field.displayPath);
+                value = parseFieldInputValue(positionalValue, field.schema, field.displayPath);
+                source = "positional";
             }
         }
         if (value === undefined &&
             Object.prototype.hasOwnProperty.call(optionValues, field.commanderOptionAttribute) &&
             hasFieldValue(optionValues[field.commanderOptionAttribute])) {
-            value = optionValues[field.commanderOptionAttribute];
+            value = normalizeCommanderOptionValue(optionValues[field.commanderOptionAttribute]);
+            source = "option";
         }
         if (value === undefined &&
             field.commanderOptionAttribute === field.optionAttribute &&
             Object.prototype.hasOwnProperty.call(optionValues, field.optionAttribute) &&
             hasFieldValue(optionValues[field.optionAttribute])) {
-            value = optionValues[field.optionAttribute];
+            value = normalizeCommanderOptionValue(optionValues[field.optionAttribute]);
+            source = "option";
         }
         if (value === undefined &&
             Object.prototype.hasOwnProperty.call(presetValues, field.optionAttribute)) {
             value = presetValues[field.optionAttribute];
+            source = "preset";
         }
         if (value === undefined && shouldPrompt && !field.optional) {
             value = await promptForField(field);
+            source = "prompt";
         }
         if (value === undefined && field.hasDefault) {
             value = field.defaultValue;
+            source = "default";
         }
         if (value === undefined) {
             if (field.optional) {
@@ -1177,15 +1867,41 @@ async function resolveParams(fields, positionalValues, optionValues, presetPath,
             }
             throw new UserError(`Missing required parameter "${field.displayPath}".`);
         }
+        resolvedFieldValues.set(field.id, value);
+        if (source !== undefined && source !== "default") {
+            providedFieldIds.add(field.id);
+        }
+        if (!field.synthetic) {
+            setNestedValue(params, field.path, value);
+        }
+    }
+    const dynamicResults = dynamicFields.length > 0
+        ? parseDynamicValues(dynamicFields, rawArgv, casing)
+        : {
+            providedFieldIds: new Set(),
+            values: new Map(),
+        };
+    for (const field of dynamicFields) {
+        let value = dynamicResults.values.get(field.id);
+        if (value === undefined && field.hasDefault) {
+            value = field.defaultValue;
+        }
+        if (value === undefined) {
+            if (field.optional || field.variantId !== undefined) {
+                continue;
+            }
+            throw new UserError(`Missing required parameter "${field.displayPath}".`);
+        }
         setNestedValue(params, field.path, value);
     }
+    await enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, dynamicResults.providedFieldIds, providedFieldIds, shouldPrompt);
     return params;
 }
 function getResolvedFlags(command) {
     const flags = command.optsWithGlobals();
     return flags;
 }
-async function executeCommand(state, services, requirementOptions) {
+async function executeCommand(state, services, requirementOptions, runtimeOptions) {
     const logger = createLogger();
     const primitives = {
         logger,
@@ -1210,12 +1926,12 @@ async function executeCommand(state, services, requirementOptions) {
     };
     await withOutputFormat(output, async () => {
         await assertCommandRequirements(state.command, preflightContext, runtime.requirementOptions);
-        const params = await resolveParams(state.fields, state.positionalValues, optionValues, resolvedFlags.preset, shouldPrompt);
+        const params = await resolveParams(state.fields, state.dynamicFields, state.variants, state.positionalValues, optionValues, state.rawArgv, state.casing, resolvedFlags.preset, shouldPrompt);
         const context = {
             ...preflightContext,
             params,
         };
-        if (state.command.confirm && !resolvedFlags.yes && process.stdin.isTTY) {
+        if (state.command.confirm && !state.command.humanInLoop && !resolvedFlags.yes && process.stdin.isTTY) {
             for (const field of state.fields) {
                 const value = field.path.reduce((current, segment) => current && typeof current === "object"
                     ? current[segment]
@@ -1236,10 +1952,14 @@ async function executeCommand(state, services, requirementOptions) {
                 throw new UserError("Operation cancelled.");
             }
         }
-        const result = await state.command.handler(context);
+        const result = await invokeWithHumanInLoop(state.command, context, runtimeOptions, state.commandPath);
         if (output === "rich" && runtime.isFixture) {
             writeRichHeader(`${state.command.name} (fixture)`);
         }
+        if (isHumanInLoopPending(result)) {
+            renderHumanInLoopPending(result);
+            return;
+        }
         renderResult(state.command, result, output, primitives);
     });
 }
@@ -1265,9 +1985,16 @@ function handleRunError(error, verbose) {
     process.exitCode = 1;
 }
 export async function runCLI(roots, options = {}) {
-    const root = normalizeRoots(roots, process.argv);
+    const root = mergeApprovalsGroup(normalizeRoots(roots, process.argv));
+    await resolveMcpProxies(root);
     const casing = options.casing ?? "kebab";
     const services = (options.services ?? {});
+    const runtimeOptions = options.humanInLoop ?? {};
+    const servicesWithBuiltIns = {
+        ...services,
+        runtimeOptions,
+        root,
+    };
     const requirementOptions = {
         apiVersion: options.apiVersion,
     };
@@ -1285,13 +2012,10 @@ export async function runCLI(roots, options = {}) {
     if (options.version !== undefined) {
         program.version(options.version, "--version");
     }
+    let lastActionCommand;
     const execute = async (state) => {
-        try {
-            await executeCommand(state, services, requirementOptions);
-        }
-        catch (error) {
-            handleRunError(error, Boolean(getResolvedFlags(state.actionCommand).verbose));
-        }
+        lastActionCommand = state.actionCommand;
+        await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeOptions);
     };
     for (const child of root.children) {
         const command = createNodeCommand(child, casing, execute);
@@ -1307,6 +2031,10 @@ export async function runCLI(roots, options = {}) {
         await program.parseAsync(process.argv);
     }
     catch (error) {
-        handleRunError(error, process.argv.includes("--verbose"));
+        if (error instanceof ApprovalDeclinedError) {
+            renderApprovalDeclined(error);
+            return;
+        }
+        handleRunError(error, lastActionCommand ? Boolean(getResolvedFlags(lastActionCommand).verbose) : process.argv.includes("--verbose"));
     }
 }