toolcraft 0.0.1

package/dist/cli.js

@@ -0,0 +1,1312 @@
+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 { getExpectedNumberDescription, isValidNumberSchemaValue } from "./number-schema.js";
+import { renderResult } from "./renderer.js";
+const RESERVED_SERVICE_NAMES = new Set(["params", "secrets", "fetch", "fs", "env", "progress"]);
+function inferProgramName(argv) {
+    const entrypoint = argv[1];
+    if (typeof entrypoint !== "string" || entrypoint.length === 0) {
+        return "agent-kit";
+    }
+    const parsed = path.parse(entrypoint);
+    return parsed.name.length > 0 ? parsed.name : "agent-kit";
+}
+function normalizeRoots(roots, argv) {
+    if (!Array.isArray(roots)) {
+        return roots;
+    }
+    return {
+        kind: "group",
+        name: inferProgramName(argv),
+        aliases: [],
+        secrets: {},
+        children: roots,
+    };
+}
+const HELP_FLAGS = new Set(["--help", "-h"]);
+function unwrapOptional(schema) {
+    if (schema.kind === "optional") {
+        return unwrapOptional(schema.inner);
+    }
+    return schema;
+}
+function splitWords(value) {
+    const words = [];
+    let current = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index] ?? "";
+        const lower = char.toLowerCase();
+        const upper = char.toUpperCase();
+        const isSeparator = char === "-" || char === "_" || char === " " || char === ".";
+        if (isSeparator) {
+            if (current.length > 0) {
+                words.push(current.toLowerCase());
+                current = "";
+            }
+            continue;
+        }
+        const isUppercase = char !== lower && char === upper;
+        const previous = value[index - 1];
+        const next = value[index + 1];
+        const previousIsLowercase = previous !== undefined && previous === previous.toLowerCase() && previous !== previous.toUpperCase();
+        const nextIsLowercase = next !== undefined && next === next.toLowerCase() && next !== next.toUpperCase();
+        if (isUppercase && current.length > 0 && (previousIsLowercase || nextIsLowercase)) {
+            words.push(current.toLowerCase());
+            current = char;
+            continue;
+        }
+        current += char;
+    }
+    if (current.length > 0) {
+        words.push(current.toLowerCase());
+    }
+    return words;
+}
+function formatSegment(segment, casing) {
+    const separator = casing === "snake" ? "_" : "-";
+    return splitWords(segment).join(separator);
+}
+function toOptionFlag(path, casing) {
+    return `--${path.map((segment) => formatSegment(segment, casing)).join(".")}`;
+}
+function toOptionAttribute(path, casing) {
+    return path
+        .map((segment) => {
+        const formatted = formatSegment(segment, casing);
+        if (casing === "snake") {
+            return formatted;
+        }
+        const words = formatted.split("-");
+        return words
+            .map((word, index) => index === 0 ? word : `${word[0]?.toUpperCase() ?? ""}${word.slice(1)}`)
+            .join("");
+    })
+        .join(".");
+}
+function toDisplayPath(path) {
+    return path.join(".");
+}
+function collectFields(schema, casing, path = [], inheritedOptional = false) {
+    const fields = [];
+    for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
+        const nextPath = [...path, key];
+        const optional = inheritedOptional || rawChildSchema.kind === "optional";
+        const childSchema = unwrapOptional(rawChildSchema);
+        if (childSchema.kind === "object") {
+            fields.push(...collectFields(childSchema, casing, nextPath, optional));
+            continue;
+        }
+        fields.push({
+            path: nextPath,
+            displayPath: toDisplayPath(nextPath),
+            optionAttribute: toOptionAttribute(nextPath, casing),
+            commanderOptionAttribute: toCommanderOptionAttribute(nextPath, casing),
+            optionFlag: toOptionFlag(nextPath, casing),
+            shortFlag: childSchema.short,
+            schema: childSchema,
+            description: childSchema.description,
+            optional,
+            hasDefault: childSchema.default !== undefined,
+            defaultValue: childSchema.default,
+        });
+    }
+    return fields;
+}
+function toCommanderOptionAttribute(path, casing) {
+    const optionAttribute = toOptionAttribute(path, casing);
+    const optionFlag = toOptionFlag(path, casing);
+    if (!GLOBAL_LONG_OPTION_FLAGS.has(optionFlag)) {
+        return optionAttribute;
+    }
+    return `param_${optionAttribute}`;
+}
+function assignPositionals(fields, positional) {
+    if (positional.length === 0) {
+        return fields;
+    }
+    const byPath = new Map(fields.map((field) => [field.displayPath, field]));
+    let variadicPositionSeen = false;
+    positional.forEach((name, index) => {
+        const field = byPath.get(name);
+        if (field === undefined) {
+            throw new UserError(`Positional parameter "${name}" does not exist in params.`);
+        }
+        if (field.schema.kind === "array") {
+            if (index !== positional.length - 1) {
+                throw new UserError(`Positional array parameter "${name}" must be the last positional.`);
+            }
+            variadicPositionSeen = true;
+        }
+        if (variadicPositionSeen && field.schema.kind !== "array") {
+            throw new UserError(`Positional parameter "${name}" cannot appear after a positional array.`);
+        }
+        field.positionalIndex = index;
+        field.variadicPosition = field.schema.kind === "array";
+    });
+    return fields;
+}
+function formatOptionFlags(field) {
+    const collidesWithGlobalFlag = GLOBAL_LONG_OPTION_FLAGS.has(field.optionFlag);
+    if (collidesWithGlobalFlag) {
+        if (field.shortFlag === undefined) {
+            throw new UserError(`Parameter "${field.displayPath}" uses reserved CLI flag "${field.optionFlag}". Add a short flag or rename the parameter.`);
+        }
+        return `-${field.shortFlag}`;
+    }
+    if (field.shortFlag === undefined) {
+        return field.optionFlag;
+    }
+    return `-${field.shortFlag}, ${field.optionFlag}`;
+}
+function formatPositionalToken(field) {
+    const optionalPositional = field.optional || field.hasDefault;
+    if (field.variadicPosition === true) {
+        return optionalPositional ? `[${field.displayPath}...]` : `<${field.displayPath}...>`;
+    }
+    return optionalPositional ? `[${field.displayPath}]` : `<${field.displayPath}>`;
+}
+function parseBooleanText(value, label) {
+    const normalized = value.trim().toLowerCase();
+    if (normalized === "true") {
+        return true;
+    }
+    if (normalized === "false") {
+        return false;
+    }
+    throw new InvalidArgumentError(`Invalid value for "${label}". Expected true or false.`);
+}
+function parseEnumValue(value, values, label) {
+    const match = values.find((candidate) => String(candidate) === value);
+    if (match === undefined) {
+        throw new InvalidArgumentError(`Invalid value for "${label}". Expected one of: ${values.map((candidate) => String(candidate)).join(", ")}.`);
+    }
+    return match;
+}
+function parseScalarValue(value, schema, label) {
+    switch (schema.kind) {
+        case "string":
+            return value;
+        case "number": {
+            const parsed = Number(value);
+            if (!isValidNumberSchemaValue(parsed, schema)) {
+                throw new InvalidArgumentError(`Invalid value for "${label}". Expected ${getExpectedNumberDescription(schema)}.`);
+            }
+            return parsed;
+        }
+        case "boolean":
+            return parseBooleanText(value, label);
+        case "enum":
+            return parseEnumValue(value, schema.values, label);
+        default:
+            throw new UserError(`Unsupported CLI schema kind "${schema.kind}".`);
+    }
+}
+function splitArrayInput(value) {
+    const items = [];
+    let current = "";
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index] ?? "";
+        if (char === ",") {
+            const trimmed = current.trim();
+            if (trimmed.length > 0) {
+                items.push(trimmed);
+            }
+            current = "";
+            continue;
+        }
+        current += char;
+    }
+    const trimmed = current.trim();
+    if (trimmed.length > 0) {
+        items.push(trimmed);
+    }
+    return items;
+}
+function parseArrayValue(value, schema, label) {
+    const itemSchema = unwrapOptional(schema.item);
+    if (itemSchema.kind === "array" || itemSchema.kind === "object") {
+        throw new UserError(`Array parameter "${label}" must use scalar items.`);
+    }
+    return splitArrayInput(value).map((item) => parseScalarValue(item, itemSchema, label));
+}
+function createOption(field) {
+    const flags = formatOptionFlags(field);
+    const collidesWithGlobalFlag = GLOBAL_LONG_OPTION_FLAGS.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 : parseBooleanText(value, field.displayPath));
+        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,
+                ...parseArrayValue(value, field.schema, 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));
+    return [option];
+}
+const GLOBAL_LONG_OPTION_FLAGS = new Set(["--preset", "--yes", "--output", "--verbose"]);
+function createCommanderOption(flags, description, field) {
+    const option = new Option(flags, description);
+    if (field.commanderOptionAttribute !== field.optionAttribute) {
+        option.attributeName = () => field.commanderOptionAttribute;
+    }
+    return option;
+}
+function hasHelpFlag(argv) {
+    return argv.some((token) => HELP_FLAGS.has(token));
+}
+function resolveHelpOutput(argv) {
+    for (let index = 0; index < argv.length; index += 1) {
+        const token = argv[index] ?? "";
+        if (token === "--output") {
+            const value = argv[index + 1];
+            if (value === "rich" || value === "md" || value === "json") {
+                return value;
+            }
+            if (value === "markdown") {
+                return "md";
+            }
+            continue;
+        }
+        if (token.startsWith("--output=")) {
+            const value = token.slice("--output=".length);
+            if (value === "rich" || value === "md" || value === "json") {
+                return value;
+            }
+            if (value === "markdown") {
+                return "md";
+            }
+        }
+    }
+    return "rich";
+}
+function isNodeVisibleInScope(node, scope) {
+    if (node.kind === "command") {
+        return node.scope.includes(scope);
+    }
+    return (getVisibleChildren(node, scope).length > 0 ||
+        Boolean(node.default && node.default.scope.includes(scope)) ||
+        node.scope === undefined ||
+        node.scope.includes(scope));
+}
+function getVisibleChildren(group, scope) {
+    return group.children.filter((child) => isNodeVisibleInScope(child, scope));
+}
+function findVisibleChild(group, token, scope) {
+    return getVisibleChildren(group, scope).find((child) => child.name === token || child.aliases.includes(token));
+}
+function resolveHelpTarget(root, argv, scope, rootDisplayName) {
+    const breadcrumb = [rootDisplayName ?? root.name];
+    let current = root;
+    for (const token of argv.slice(2)) {
+        if (token.startsWith("-") || token === "help") {
+            break;
+        }
+        if (current.kind !== "group") {
+            break;
+        }
+        const child = findVisibleChild(current, token, scope);
+        if (child === undefined) {
+            break;
+        }
+        breadcrumb.push(child.name);
+        current = child;
+    }
+    return {
+        breadcrumb,
+        node: current,
+    };
+}
+function describeSchemaType(schema) {
+    switch (schema.kind) {
+        case "string":
+            return "string";
+        case "number":
+            return "number";
+        case "boolean":
+            return "boolean";
+        case "enum":
+            return "value";
+        case "array":
+            return `${describeSchemaType(unwrapOptional(schema.item))}...`;
+        default:
+            throw new UserError("Unsupported CLI schema kind.");
+    }
+}
+function formatHelpFieldFlags(field) {
+    if (field.positionalIndex !== undefined) {
+        return formatPositionalToken(field);
+    }
+    if (field.schema.kind === "boolean") {
+        return `${formatOptionFlags(field)} [value]`;
+    }
+    return `${formatOptionFlags(field)} <${describeSchemaType(field.schema)}>`;
+}
+function appendHelpMetadata(description, metadata) {
+    if (metadata.length === 0) {
+        return description;
+    }
+    if (description.length === 0) {
+        return `(${metadata.join(", ")})`;
+    }
+    return `${description} (${metadata.join(", ")})`;
+}
+function formatHelpFieldDescription(field) {
+    const description = field.description ?? field.displayPath;
+    const metadata = [];
+    if (!field.optional && !field.hasDefault) {
+        metadata.push("required");
+    }
+    if (field.hasDefault) {
+        metadata.push(`default: ${formatResolvedValue(field.defaultValue)}`);
+    }
+    return appendHelpMetadata(description, metadata);
+}
+function formatSecretRows(secrets) {
+    return Object.values(secrets).map((secret) => ({
+        flags: secret.env,
+        description: formatSecretDescription(secret),
+    }));
+}
+function formatSecretDescription(secret) {
+    if (secret.description !== undefined && secret.description.length > 0) {
+        return secret.description;
+    }
+    return secret.optional === true ? "Optional secret" : "Required secret";
+}
+function formatCommandRows(group, scope) {
+    return getVisibleChildren(group, scope).map((child) => ({
+        name: child.aliases.length === 0 ? child.name : `${child.name} (${child.aliases.join(", ")})`,
+        description: child.description ?? "",
+    }));
+}
+function formatGlobalOptionRows(showVersion) {
+    const rows = [
+        {
+            flags: "--preset <path>",
+            description: "Load parameter defaults from a JSON file",
+        },
+        {
+            flags: "--yes",
+            description: "Accept defaults, skip prompts",
+        },
+        {
+            flags: "--output <format>",
+            description: "Output format (rich, md, json)",
+        },
+        {
+            flags: "-h, --help",
+            description: "Show help",
+        },
+    ];
+    if (showVersion) {
+        rows.push({
+            flags: "--version",
+            description: "Show version",
+        });
+    }
+    return rows;
+}
+function renderHelpSections(sections) {
+    return sections.filter((section) => section.length > 0).join("\n\n");
+}
+function buildUsageLine(breadcrumb, rootUsageName, suffix) {
+    if (rootUsageName === undefined) {
+        return undefined;
+    }
+    const subPath = breadcrumb.slice(1).join(" ");
+    return subPath ? `${rootUsageName} ${subPath} ${suffix}` : `${rootUsageName} ${suffix}`;
+}
+function renderGroupHelp(group, breadcrumb, scope, showVersion, rootUsageName) {
+    const sections = [];
+    const commandRows = formatCommandRows(group, scope);
+    if (commandRows.length > 0) {
+        sections.push(`${text.section("Commands:")}\n${formatCommandList(commandRows)}`);
+    }
+    sections.push(`${text.section("Global options:")}\n${formatOptionList(formatGlobalOptionRows(showVersion))}`);
+    return renderHelpDocument({
+        breadcrumb,
+        usageLine: buildUsageLine(breadcrumb, rootUsageName, "[options] [command]"),
+        description: group.description,
+        requiresAuth: group.requires?.auth === true,
+        sections,
+    });
+}
+function renderLeafHelp(command, breadcrumb, casing, rootUsageName) {
+    const sections = [];
+    const fields = assignPositionals(collectFields(command.params, casing), command.positional);
+    const optionRows = fields.map((field) => ({
+        flags: formatHelpFieldFlags(field),
+        description: formatHelpFieldDescription(field),
+    }));
+    if (optionRows.length > 0) {
+        sections.push(`${text.section("Options:")}\n${formatOptionList(optionRows)}`);
+    }
+    sections.push(`${text.section("Global options:")}\n${formatOptionList(formatGlobalOptionRows(false))}`);
+    const secretRows = formatSecretRows(command.secrets);
+    if (secretRows.length > 0) {
+        sections.push(`${text.section("Secrets (via environment):")}\n${formatOptionList(secretRows)}`);
+    }
+    const positionalFields = fields.filter((f) => f.positionalIndex !== undefined);
+    const usageSuffix = positionalFields.length > 0
+        ? `[options] ${positionalFields.map(formatPositionalToken).join(" ")}`
+        : "[options]";
+    return renderHelpDocument({
+        breadcrumb,
+        usageLine: buildUsageLine(breadcrumb, rootUsageName, usageSuffix),
+        description: command.description,
+        requiresAuth: command.requires?.auth === true,
+        sections,
+    });
+}
+function renderHelpDocument(input) {
+    const lines = [text.heading(input.breadcrumb.join(" ")), ""];
+    if (input.usageLine !== undefined) {
+        lines.push(`${text.section("Usage:")} ${text.usageCommand(input.usageLine)}`, "");
+    }
+    if (input.description !== undefined) {
+        lines.push(input.description);
+    }
+    if (input.requiresAuth) {
+        lines.push("Requires: authentication");
+    }
+    if (input.description !== undefined || input.requiresAuth) {
+        lines.push("");
+    }
+    lines.push(renderHelpSections(input.sections));
+    return `${lines.join("\n").trimEnd()}\n`;
+}
+async function renderGeneratedHelp(root, argv, options) {
+    const target = resolveHelpTarget(root, argv, "cli", options.rootDisplayName);
+    const output = resolveHelpOutput(argv);
+    const casing = options.casing ?? "kebab";
+    await withOutputFormat(output, async () => {
+        const rendered = target.node.kind === "group"
+            ? renderGroupHelp(target.node, target.breadcrumb, "cli", options.version !== undefined, options.rootUsageName)
+            : renderLeafHelp(target.node, target.breadcrumb, casing, options.rootUsageName);
+        process.stdout.write(rendered);
+    });
+}
+function createNodeCommand(node, casing, execute) {
+    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);
+        if (node.description !== undefined) {
+            command.description(node.description);
+        }
+        node.aliases.forEach((alias) => command.alias(alias));
+        command.addHelpCommand(false);
+        addGlobalOptions(command);
+        for (const field of fields) {
+            if (field.positionalIndex !== undefined) {
+                command.argument(formatPositionalToken(field));
+                continue;
+            }
+            for (const option of createOption(field)) {
+                command.addOption(option);
+            }
+        }
+        command.action(async (...args) => {
+            const actionCommand = args[args.length - 1];
+            const positionalValues = args.slice(0, -2);
+            await execute({
+                command: node,
+                fields,
+                positionalValues,
+                actionCommand,
+            });
+        });
+        return command;
+    }
+    if (!isNodeVisibleInScope(node, "cli")) {
+        return null;
+    }
+    const visibleChildren = node.children
+        .map((child) => createNodeCommand(child, casing, execute))
+        .filter((child) => child !== null);
+    const group = new CommanderCommand(node.name);
+    if (node.description !== undefined) {
+        group.description(node.description);
+    }
+    node.aliases.forEach((alias) => group.alias(alias));
+    group.addHelpCommand(false);
+    addGlobalOptions(group);
+    for (const child of visibleChildren) {
+        const isDefaultChild = node.default !== undefined &&
+            node.default.scope.includes("cli") &&
+            (child.name() === node.default.name || child.aliases().includes(node.default.name));
+        group.addCommand(child, isDefaultChild ? { isDefault: true } : undefined);
+    }
+    return group;
+}
+function addGlobalOptions(command) {
+    command
+        .option("--preset <path>", "Load parameter defaults from a JSON file.")
+        .option("--yes", "Accept defaults and skip prompts.")
+        .option("--output <format>", "Output format.", (value) => {
+        if (value === "rich" || value === "md" || value === "json") {
+            return value;
+        }
+        if (value === "markdown") {
+            return "md";
+        }
+        throw new InvalidArgumentError('Invalid value for "--output". Expected one of: rich, md, markdown, json.');
+    })
+        .option("--verbose", "Print stack traces for unexpected errors.");
+}
+function setNestedValue(target, path, value) {
+    let cursor = target;
+    for (let index = 0; index < path.length - 1; index += 1) {
+        const segment = path[index] ?? "";
+        const existing = cursor[segment];
+        if (typeof existing === "object" && existing !== null) {
+            cursor = existing;
+            continue;
+        }
+        const next = {};
+        cursor[segment] = next;
+        cursor = next;
+    }
+    const leaf = path[path.length - 1];
+    if (leaf !== undefined) {
+        cursor[leaf] = value;
+    }
+}
+function formatResolvedValue(value) {
+    if (Array.isArray(value)) {
+        return value.map((item) => String(item)).join(", ");
+    }
+    if (typeof value === "string") {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+async function promptForField(field) {
+    const schema = field.schema;
+    if (schema.kind === "enum") {
+        const options = schema.loadOptions
+            ? await schema.loadOptions()
+            : schema.values.map((value) => ({
+                label: schema.labels?.[String(value)] ?? String(value),
+                value,
+            }));
+        const selected = await select({
+            message: field.description ?? field.displayPath,
+            options,
+            initialValue: field.hasDefault ? field.defaultValue : undefined,
+        });
+        if (isCancel(selected)) {
+            cancel("Operation cancelled.");
+            throw new UserError("Operation cancelled.");
+        }
+        return selected;
+    }
+    if (field.schema.kind === "boolean") {
+        const selected = await confirm({
+            message: field.displayPath,
+            initialValue: field.hasDefault ? Boolean(field.defaultValue) : undefined,
+        });
+        if (isCancel(selected)) {
+            cancel("Operation cancelled.");
+            throw new UserError("Operation cancelled.");
+        }
+        return selected;
+    }
+    const entered = await promptText({
+        message: field.displayPath,
+        initialValue: field.hasDefault && field.defaultValue !== undefined
+            ? formatResolvedValue(field.defaultValue)
+            : undefined,
+    });
+    if (isCancel(entered)) {
+        cancel("Operation cancelled.");
+        throw new UserError("Operation cancelled.");
+    }
+    if (typeof entered !== "string") {
+        throw new UserError(`Missing required parameter "${field.displayPath}".`);
+    }
+    if (entered.trim().length === 0 && field.hasDefault) {
+        return field.defaultValue;
+    }
+    if (field.schema.kind === "array") {
+        return parseArrayValue(entered, field.schema, field.displayPath);
+    }
+    return parseScalarValue(entered, field.schema, field.displayPath);
+}
+function resolveOutput(resolvedFlags) {
+    if (resolvedFlags.json === true) {
+        return "json";
+    }
+    if (resolvedFlags.output !== undefined) {
+        return resolvedFlags.output;
+    }
+    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();
+    }
+    finally {
+        if (previous === undefined) {
+            delete process.env.OUTPUT_FORMAT;
+        }
+        else {
+            process.env.OUTPUT_FORMAT = previous;
+        }
+        resetOutputFormatCache();
+    }
+}
+function createFs() {
+    return {
+        readFile: async (path, encoding = "utf8") => readFile(path, { encoding }),
+        writeFile: async (path, contents) => {
+            await writeFile(path, contents);
+        },
+        exists: async (path) => {
+            try {
+                await access(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        },
+    };
+}
+function createEnv(values = process.env) {
+    return {
+        get(key) {
+            return values[key];
+        },
+    };
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasFieldValue(value) {
+    return value !== undefined;
+}
+function hasNestedField(fields, path) {
+    return fields.some((field) => path.length < field.path.length &&
+        path.every((segment, index) => field.path[index] === segment));
+}
+function describeExpectedPresetValue(schema) {
+    if (schema.kind === "array") {
+        return "an array";
+    }
+    if (schema.kind === "enum") {
+        return `one of: ${schema.values.map((value) => JSON.stringify(value)).join(", ")}`;
+    }
+    return `a ${schema.kind}`;
+}
+function validatePresetScalarValue(value, schema, fieldPath, presetPath) {
+    if (value === null && schema.nullable === true) {
+        return null;
+    }
+    switch (schema.kind) {
+        case "string":
+            if (typeof value !== "string") {
+                break;
+            }
+            return value;
+        case "number":
+            if (!isValidNumberSchemaValue(value, schema)) {
+                break;
+            }
+            return value;
+        case "boolean":
+            if (typeof value !== "boolean") {
+                break;
+            }
+            return value;
+        case "enum": {
+            const match = schema.values.find((candidate) => Object.is(candidate, value));
+            if (match !== undefined) {
+                return match;
+            }
+            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 !== "array") {
+        return validatePresetScalarValue(value, field.schema, field.displayPath, presetPath);
+    }
+    const itemSchema = unwrapOptional(field.schema.item);
+    if (itemSchema.kind === "array" || itemSchema.kind === "object") {
+        throw new UserError(`Array parameter "${field.displayPath}" must use scalar items.`);
+    }
+    if (!Array.isArray(value)) {
+        throw new UserError(`Preset file "${presetPath}" has an invalid value for "${field.displayPath}". Expected an array.`);
+    }
+    return value.map((item) => validatePresetScalarValue(item, itemSchema, field.displayPath, presetPath));
+}
+async function loadPresetValues(fields, presetPath) {
+    let rawPreset;
+    try {
+        rawPreset = await readFile(presetPath, {
+            encoding: "utf8",
+        });
+    }
+    catch (error) {
+        if (typeof error === "object" &&
+            error !== null &&
+            "code" in error &&
+            error.code === "ENOENT") {
+            throw new UserError(`Preset file "${presetPath}" was not found.`);
+        }
+        const message = error instanceof Error && error.message.length > 0
+            ? error.message
+            : "Unknown read error.";
+        throw new UserError(`Preset file "${presetPath}" could not be read: ${message}`);
+    }
+    let parsedPreset;
+    try {
+        parsedPreset = JSON.parse(rawPreset);
+    }
+    catch {
+        throw new UserError(`Preset file "${presetPath}" is not valid JSON.`);
+    }
+    if (!isPlainObject(parsedPreset)) {
+        throw new UserError(`Preset file "${presetPath}" must contain a JSON object.`);
+    }
+    const fieldByPath = new Map(fields.map((field) => [field.displayPath, field]));
+    const presetValues = {};
+    function visitObject(current, path) {
+        for (const [key, value] of Object.entries(current)) {
+            const nextPath = [...path, key];
+            const displayPath = toDisplayPath(nextPath);
+            const field = fieldByPath.get(displayPath);
+            if (field !== undefined) {
+                presetValues[field.optionAttribute] = validatePresetFieldValue(value, field, presetPath);
+                continue;
+            }
+            if (!hasNestedField(fields, nextPath)) {
+                throw new UserError(`Preset file "${presetPath}" contains unknown parameter "${displayPath}".`);
+            }
+            if (!isPlainObject(value)) {
+                throw new UserError(`Preset file "${presetPath}" has an invalid value for "${displayPath}". Expected an object.`);
+            }
+            visitObject(value, nextPath);
+        }
+    }
+    visitObject(parsedPreset, []);
+    return presetValues;
+}
+function isNumericFixtureSelector(value) {
+    if (value.length === 0) {
+        return false;
+    }
+    for (const char of value) {
+        if (char < "0" || char > "9") {
+            return false;
+        }
+    }
+    return true;
+}
+function normalizeHttpMethod(value) {
+    return (value ?? "GET").toUpperCase();
+}
+function isReadLikeMethod(name) {
+    const normalized = name.toLowerCase();
+    return (normalized === "get" ||
+        normalized === "head" ||
+        normalized === "options" ||
+        normalized.startsWith("read") ||
+        normalized.startsWith("get") ||
+        normalized.startsWith("find") ||
+        normalized.startsWith("list") ||
+        normalized.startsWith("load") ||
+        normalized.startsWith("fetch") ||
+        normalized.startsWith("query") ||
+        normalized.startsWith("exists") ||
+        normalized.startsWith("has"));
+}
+function isWriteLikeMethod(name) {
+    const normalized = name.toLowerCase();
+    return (normalized === "post" ||
+        normalized === "put" ||
+        normalized === "patch" ||
+        normalized === "delete" ||
+        normalized.startsWith("write") ||
+        normalized.startsWith("set") ||
+        normalized.startsWith("save") ||
+        normalized.startsWith("create") ||
+        normalized.startsWith("update") ||
+        normalized.startsWith("delete") ||
+        normalized.startsWith("remove") ||
+        normalized.startsWith("insert"));
+}
+function matchesFixtureValue(expected, actual) {
+    if (typeof expected === "string" && typeof actual === "string" && expected.endsWith("%")) {
+        return actual.startsWith(expected.slice(0, -1));
+    }
+    if (Array.isArray(expected)) {
+        if (!Array.isArray(actual) || expected.length !== actual.length) {
+            return false;
+        }
+        return expected.every((item, index) => matchesFixtureValue(item, actual[index]));
+    }
+    if (isPlainObject(expected)) {
+        if (!isPlainObject(actual)) {
+            return false;
+        }
+        return Object.entries(expected).every(([key, value]) => matchesFixtureValue(value, actual[key]));
+    }
+    return Object.is(expected, actual);
+}
+function getFetchUrl(input) {
+    if (typeof input === "string") {
+        return input;
+    }
+    if (input instanceof URL) {
+        return input.toString();
+    }
+    return input.url;
+}
+function createFixtureResponse(response) {
+    const status = response.status ?? 200;
+    const headers = new Headers(response.headers);
+    if (response.body === undefined) {
+        return new Response(null, {
+            status,
+            headers,
+        });
+    }
+    if (typeof response.body === "string") {
+        return new Response(response.body, {
+            status,
+            headers,
+        });
+    }
+    if (!headers.has("content-type")) {
+        headers.set("content-type", "application/json");
+    }
+    return new Response(JSON.stringify(response.body), {
+        status,
+        headers,
+    });
+}
+function createFixtureFetch(entries) {
+    return async (input, init) => {
+        const method = normalizeHttpMethod(init?.method ?? (input instanceof Request ? input.method : undefined));
+        const url = getFetchUrl(input);
+        const match = entries?.find((entry) => {
+            const requestMethod = normalizeHttpMethod(entry.request.method);
+            return requestMethod === method && entry.request.url === url;
+        });
+        if (match !== undefined) {
+            return createFixtureResponse(match.response);
+        }
+        if (isReadLikeMethod(method)) {
+            return null;
+        }
+        return new Response(null, {
+            status: 204,
+        });
+    };
+}
+function createFixtureFs(definition) {
+    const fsDefinition = isPlainObject(definition) ? definition : {};
+    const readFileEntries = isPlainObject(fsDefinition.readFile) ? fsDefinition.readFile : {};
+    const existsEntries = isPlainObject(fsDefinition.exists) ? fsDefinition.exists : {};
+    return {
+        readFile: async (filePath) => {
+            if (Object.prototype.hasOwnProperty.call(readFileEntries, filePath)) {
+                return String(readFileEntries[filePath]);
+            }
+            return null;
+        },
+        writeFile: async () => undefined,
+        exists: async (filePath) => {
+            if (Object.prototype.hasOwnProperty.call(existsEntries, filePath)) {
+                return Boolean(existsEntries[filePath]);
+            }
+            return Object.prototype.hasOwnProperty.call(readFileEntries, filePath);
+        },
+    };
+}
+function resolveFixtureMethodResult(methodName, definition, args) {
+    if (Array.isArray(definition)) {
+        for (const entry of definition) {
+            if (!isPlainObject(entry)) {
+                continue;
+            }
+            const explicitMatcher = isPlainObject(entry.request) ? entry.request : undefined;
+            const matcher = explicitMatcher ??
+                Object.fromEntries(Object.entries(entry).filter(([key]) => key !== "result" && key !== "response" && key !== "error"));
+            const firstArg = args[0];
+            let matched = false;
+            if (Array.isArray(matcher.args)) {
+                matched = matchesFixtureValue(matcher.args, args);
+            }
+            else if (Object.keys(matcher).length === 0) {
+                matched = true;
+            }
+            else if (isPlainObject(firstArg)) {
+                matched = matchesFixtureValue(matcher, firstArg);
+            }
+            else if (args.length === 1 && Object.keys(matcher).length === 1) {
+                const [[, expectedValue]] = Object.entries(matcher);
+                matched = matchesFixtureValue(expectedValue, firstArg);
+            }
+            if (!matched) {
+                continue;
+            }
+            if (entry.error !== undefined) {
+                throw new Error(String(entry.error));
+            }
+            if (Object.prototype.hasOwnProperty.call(entry, "result")) {
+                return Promise.resolve(entry.result);
+            }
+            if (Object.prototype.hasOwnProperty.call(entry, "response")) {
+                return Promise.resolve(entry.response);
+            }
+            return Promise.resolve(null);
+        }
+    }
+    if (isPlainObject(definition)) {
+        const firstArg = args[0];
+        if (typeof firstArg === "string" && Object.prototype.hasOwnProperty.call(definition, firstArg)) {
+            return Promise.resolve(definition[firstArg]);
+        }
+    }
+    if (isWriteLikeMethod(methodName)) {
+        return Promise.resolve(undefined);
+    }
+    return Promise.resolve(null);
+}
+function createFixtureService(definition) {
+    const methods = isPlainObject(definition) ? definition : {};
+    return new Proxy({}, {
+        get(_target, property) {
+            if (property === "then") {
+                return undefined;
+            }
+            const methodName = String(property);
+            return async (...args) => resolveFixtureMethodResult(methodName, methods[methodName], args);
+        },
+    });
+}
+function resolveFixturePath(commandPath) {
+    const parsed = path.parse(commandPath);
+    return path.join(parsed.dir, `${parsed.name}.fixture.json`);
+}
+function selectFixtureScenario(scenarios, selector) {
+    if (isNumericFixtureSelector(selector)) {
+        const index = Number(selector) - 1;
+        const scenario = scenarios[index];
+        if (scenario === undefined) {
+            throw new UserError(`Fixture scenario index ${selector} is out of range. Available scenarios: ${scenarios.length}.`);
+        }
+        return scenario;
+    }
+    const scenario = scenarios.find((entry) => entry.name === selector);
+    if (scenario === undefined) {
+        throw new UserError(`Fixture scenario "${selector}" was not found.`);
+    }
+    return scenario;
+}
+async function loadFixtureScenario(command, selector) {
+    const commandPath = getCommandSourcePath(command);
+    if (commandPath === undefined) {
+        throw new UserError(`Fixture mode could not determine the source file for command "${command.name}".`);
+    }
+    const fixturePath = resolveFixturePath(commandPath);
+    let rawFixture;
+    try {
+        rawFixture = await readFile(fixturePath, {
+            encoding: "utf8",
+        });
+    }
+    catch {
+        throw new UserError(`Fixture file not found for command "${command.name}". Expected ${fixturePath}.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(rawFixture);
+    }
+    catch {
+        throw new UserError(`Fixture file ${fixturePath} is not valid JSON.`);
+    }
+    if (!Array.isArray(parsed)) {
+        throw new UserError(`Fixture file ${fixturePath} must contain a JSON array of scenarios.`);
+    }
+    return selectFixtureScenario(parsed, selector);
+}
+function resolveFixtureSecrets(command) {
+    return Object.fromEntries(Object.keys(command.secrets).map((name) => [name, "fixture-secret"]));
+}
+function createFixtureEnvValues(command) {
+    const values = {
+        ...process.env,
+        POE_API_KEY: process.env.POE_API_KEY ?? "fixture-secret",
+    };
+    for (const secret of Object.values(command.secrets)) {
+        values[secret.env] = values[secret.env] ?? "fixture-secret";
+    }
+    return values;
+}
+async function resolveFixtureRuntime(command, services, requirementOptions) {
+    const selector = process.env.AGENT_KIT_FIXTURE;
+    if (selector === undefined || selector.length === 0) {
+        return {
+            env: createEnv(),
+            fetch: globalThis.fetch,
+            fs: createFs(),
+            isFixture: false,
+            requirementOptions,
+            secrets: resolveCommandSecrets(command),
+            services,
+        };
+    }
+    const scenario = await loadFixtureScenario(command, selector);
+    const scenarioServices = isPlainObject(scenario.services) ? scenario.services : {};
+    const customServiceNames = new Set([
+        ...Object.keys(services),
+        ...Object.keys(scenarioServices).filter((name) => !RESERVED_SERVICE_NAMES.has(name)),
+    ]);
+    const fixtureServices = Object.fromEntries([...customServiceNames].map((name) => [name, createFixtureService(scenarioServices[name])]));
+    const fixtureEnvValues = createFixtureEnvValues(command);
+    return {
+        env: createEnv(fixtureEnvValues),
+        fetch: createFixtureFetch(scenarioServices.fetch),
+        fs: createFixtureFs(scenarioServices.fs),
+        isFixture: true,
+        requirementOptions: {
+            ...requirementOptions,
+            env: fixtureEnvValues,
+        },
+        secrets: resolveFixtureSecrets(command),
+        services: fixtureServices,
+    };
+}
+function writeRichHeader(title) {
+    const padding = Math.max(12, 34 - title.length);
+    process.stdout.write(`── ${title} ${"─".repeat(padding)}\n`);
+}
+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.`);
+        }
+    }
+}
+async function resolveParams(fields, positionalValues, optionValues, presetPath, shouldPrompt) {
+    const params = {};
+    const presetValues = typeof presetPath === "string" && presetPath.length > 0
+        ? await loadPresetValues(fields, presetPath)
+        : {};
+    for (const field of fields) {
+        let value;
+        if (field.positionalIndex !== undefined) {
+            const positionalValue = positionalValues[field.positionalIndex];
+            if (field.schema.kind === "array") {
+                if (Array.isArray(positionalValue) && positionalValue.length > 0) {
+                    const itemSchema = unwrapOptional(field.schema.item);
+                    if (itemSchema.kind === "array" || itemSchema.kind === "object") {
+                        throw new UserError(`Array parameter "${field.displayPath}" must use scalar items.`);
+                    }
+                    value = positionalValue.map((item) => parseScalarValue(String(item), itemSchema, field.displayPath));
+                }
+            }
+            else if (typeof positionalValue === "string" && positionalValue.length > 0) {
+                value = parseScalarValue(positionalValue, field.schema, field.displayPath);
+            }
+        }
+        if (value === undefined &&
+            Object.prototype.hasOwnProperty.call(optionValues, field.commanderOptionAttribute) &&
+            hasFieldValue(optionValues[field.commanderOptionAttribute])) {
+            value = optionValues[field.commanderOptionAttribute];
+        }
+        if (value === undefined &&
+            field.commanderOptionAttribute === field.optionAttribute &&
+            Object.prototype.hasOwnProperty.call(optionValues, field.optionAttribute) &&
+            hasFieldValue(optionValues[field.optionAttribute])) {
+            value = optionValues[field.optionAttribute];
+        }
+        if (value === undefined &&
+            Object.prototype.hasOwnProperty.call(presetValues, field.optionAttribute)) {
+            value = presetValues[field.optionAttribute];
+        }
+        if (value === undefined && shouldPrompt && !field.optional) {
+            value = await promptForField(field);
+        }
+        if (value === undefined && field.hasDefault) {
+            value = field.defaultValue;
+        }
+        if (value === undefined) {
+            if (field.optional) {
+                continue;
+            }
+            throw new UserError(`Missing required parameter "${field.displayPath}".`);
+        }
+        setNestedValue(params, field.path, value);
+    }
+    return params;
+}
+function getResolvedFlags(command) {
+    const flags = command.optsWithGlobals();
+    return flags;
+}
+async function executeCommand(state, services, requirementOptions) {
+    const logger = createLogger();
+    const primitives = {
+        logger,
+        renderTable,
+        getTheme,
+        note,
+    };
+    const optionValues = state.actionCommand.optsWithGlobals();
+    const resolvedFlags = optionValues;
+    const output = resolveOutput(resolvedFlags);
+    const shouldPrompt = !resolvedFlags.yes && Boolean(process.stdin.isTTY);
+    const runtime = await resolveFixtureRuntime(state.command, services, requirementOptions);
+    const preflightContext = {
+        ...runtime.services,
+        secrets: runtime.secrets,
+        fetch: runtime.fetch,
+        fs: runtime.fs,
+        env: runtime.env,
+        progress(message) {
+            logger.info(message);
+        },
+    };
+    await withOutputFormat(output, async () => {
+        await assertCommandRequirements(state.command, preflightContext, runtime.requirementOptions);
+        const params = await resolveParams(state.fields, state.positionalValues, optionValues, resolvedFlags.preset, shouldPrompt);
+        const context = {
+            ...preflightContext,
+            params,
+        };
+        if (state.command.confirm && !resolvedFlags.yes && process.stdin.isTTY) {
+            for (const field of state.fields) {
+                const value = field.path.reduce((current, segment) => current && typeof current === "object"
+                    ? current[segment]
+                    : undefined, params);
+                if (value !== undefined) {
+                    logger.resolved(field.displayPath, formatResolvedValue(value));
+                }
+            }
+            const proceed = await confirm({
+                message: "Proceed?",
+                initialValue: true,
+            });
+            if (isCancel(proceed)) {
+                cancel("Operation cancelled.");
+                throw new UserError("Operation cancelled.");
+            }
+            if (proceed !== true) {
+                throw new UserError("Operation cancelled.");
+            }
+        }
+        const result = await state.command.handler(context);
+        if (output === "rich" && runtime.isFixture) {
+            writeRichHeader(`${state.command.name} (fixture)`);
+        }
+        renderResult(state.command, result, output, primitives);
+    });
+}
+function handleRunError(error, verbose) {
+    const logger = createLogger();
+    if (error instanceof UserError) {
+        logger.error(error.message);
+        process.exitCode = 1;
+        return;
+    }
+    if (error instanceof CommanderError) {
+        process.exitCode = error.exitCode;
+        if (error.code === "commander.helpDisplayed" || error.code === "commander.version") {
+            return;
+        }
+        return;
+    }
+    const message = error instanceof Error ? error.message : String(error);
+    logger.error(verbose ? message : `${message} Use --verbose for a stack trace.`);
+    if (verbose && error instanceof Error && error.stack) {
+        process.stderr.write(`${error.stack}\n`);
+    }
+    process.exitCode = 1;
+}
+export async function runCLI(roots, options = {}) {
+    const root = normalizeRoots(roots, process.argv);
+    const casing = options.casing ?? "kebab";
+    const services = (options.services ?? {});
+    const requirementOptions = {
+        apiVersion: options.apiVersion,
+    };
+    validateServices(services);
+    if (hasHelpFlag(process.argv)) {
+        await renderGeneratedHelp(root, process.argv, options);
+        return;
+    }
+    const program = new CommanderCommand();
+    program.name(root.name);
+    program.exitOverride();
+    program.showHelpAfterError();
+    program.addHelpCommand(false);
+    addGlobalOptions(program);
+    if (options.version !== undefined) {
+        program.version(options.version, "--version");
+    }
+    const execute = async (state) => {
+        try {
+            await executeCommand(state, services, requirementOptions);
+        }
+        catch (error) {
+            handleRunError(error, Boolean(getResolvedFlags(state.actionCommand).verbose));
+        }
+    };
+    for (const child of root.children) {
+        const command = createNodeCommand(child, casing, execute);
+        if (command === null) {
+            continue;
+        }
+        const isDefaultChild = root.default !== undefined &&
+            root.default.scope.includes("cli") &&
+            (command.name() === root.default.name || command.aliases().includes(root.default.name));
+        program.addCommand(command, isDefaultChild ? { isDefault: true } : undefined);
+    }
+    try {
+        await program.parseAsync(process.argv);
+    }
+    catch (error) {
+        handleRunError(error, process.argv.includes("--verbose"));
+    }
+}