@ykdz/template 0.0.38 → 0.0.41

package/node_modules/@ykdz/cli-contract/dist/cli-contract.js

@@ -0,0 +1,1408 @@
+import { compileAtomicVariants, } from "#/atomic-variant-compiler";
+import { ContractDefinitionError, } from "#/contract-definition-error";
+import { ContractExecutionError } from "#/contract-execution-error";
+import { compileContractSchema, compileInputFields, projectFieldDescriptions, } from "#/contract-schema-compiler";
+import { copySingleLineText, isSingleLineText } from "#/description";
+import { deepFreeze } from "#/json-value";
+import { isIssuedTextProjection } from "#/outcome-fact";
+import { createCompletionWireSchema, createDataWireSchema, createFailureWireSchema, createStreamHeaderWireSchema, createStreamRecordWireSchema, createStreamSuccessWireSchema, createUsageFailureWireSchema, } from "#/outcome-wire";
+import { compileStreamRecords, } from "#/stream-variant-compiler";
+export { createCompletionFact, createDataFact, createFailureFact, createStreamRecordFact, createStreamSuccessFact, isIssuedOutcomeFact, text, } from "#/outcome-fact";
+const cliContractType = Symbol("CliContract.type");
+const executableCommandType = Symbol("ExecutableCommand.type");
+const helpCapabilities = new WeakSet();
+const outputCapabilities = new WeakSet();
+const versionCapabilities = new WeakSet();
+const compiledCliContracts = new WeakMap();
+// 类型约束与定义期检查共用已知属性，避免拼错的声明被静默丢弃。
+const definitionPropertyKeys = {
+    cli: [
+        "root",
+        "help",
+        "version",
+        "output",
+        "usageFailureExitCode",
+        "commands",
+    ],
+    group: [
+        "kind",
+        "parent",
+        "name",
+        "aliases",
+        "description",
+        "helpSupplement",
+        "handler",
+    ],
+    command: [
+        "kind",
+        "parent",
+        "name",
+        "aliases",
+        "description",
+        "helpSupplement",
+        "fields",
+        "input",
+        "success",
+        "failures",
+        "handler",
+        "usageConstraints",
+    ],
+    field: {
+        flag: [
+            "kind",
+            "longOption",
+            "shortAlias",
+            "negatedLongOption",
+            "description",
+        ],
+        option: ["kind", "longOption", "shortAlias", "description"],
+        positional: ["kind", "description"],
+    },
+    usage: {
+        requires: ["kind", "field", "requires"],
+        exclusive: ["kind", "fields"],
+        forbiddenCombination: ["kind", "values"],
+        value: ["field", "value"],
+    },
+    success: {
+        completion: ["kind", "text"],
+        data: ["kind", "variants"],
+        stream: ["kind", "records", "text"],
+    },
+    atomicVariant: ["description", "schema", "exitCode", "text"],
+    streamRecord: ["description", "schema", "text"],
+    capability: {
+        help: ["shortAlias", "headings", "wording"],
+        version: ["value", "description", "shortAlias"],
+        output: ["defaultFormat", "text", "compatibilityFlags"],
+    },
+};
+export function isCompiledExecutable(command) {
+    return command.kind === "rootCommand" || command.kind === "command";
+}
+export function helpCapability(definition = {}) {
+    assertKnownCapabilityOptions(definition, definitionPropertyKeys.capability.help, "help");
+    if (definition.shortAlias !== undefined && definition.shortAlias !== "-h") {
+        throw new TypeError("帮助短别名必须是 -h");
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- helpCapability 由本工厂签发并登记到 WeakSet，类型品牌不在运行时输出。
+    const capability = Object.freeze({
+        kind: "helpCapability",
+        longOption: "--help",
+        ...(definition.shortAlias === undefined
+            ? {}
+            : { shortAlias: definition.shortAlias }),
+        ...(definition.headings === undefined
+            ? {}
+            : { headings: copyHelpHeadings(definition.headings) }),
+        ...(definition.wording === undefined
+            ? {}
+            : { wording: copyHelpFactWording(definition.wording) }),
+    });
+    helpCapabilities.add(capability);
+    return capability;
+}
+function copyHelpHeadings(value) {
+    if (typeof value !== "object" || value === null || Array.isArray(value)) {
+        throw new TypeError("帮助标题必须是对象");
+    }
+    const allowed = new Set([
+        "usage",
+        "commands",
+        "arguments",
+        "options",
+        "constraints",
+        "supplement",
+    ]);
+    const headings = {};
+    for (const [key, heading] of Object.entries(value)) {
+        if (!allowed.has(key))
+            throw new TypeError("帮助标题包含未知段落");
+        headings[key] = copySingleLineText(heading, `帮助标题 ${key}`);
+    }
+    return Object.freeze(headings);
+}
+const helpTemplatePlaceholders = {
+    choices: ["choices"],
+    default: ["value"],
+    requires: ["field", "requires"],
+    exclusive: ["fields"],
+    forbiddenCombination: ["values"],
+};
+function copyHelpFactWording(value) {
+    if (!isPlainRecord(value)) {
+        throw new TypeError("帮助事实文案必须是对象");
+    }
+    const wording = {};
+    for (const [slot, raw] of Object.entries(value)) {
+        if (slot === "commandPlaceholder") {
+            const label = copySingleLineText(raw, "命令组占位词");
+            if (label.trim().length === 0 ||
+                label.includes("<") ||
+                label.includes(">")) {
+                throw new TypeError("命令组占位词无效");
+            }
+            wording[slot] = label;
+            continue;
+        }
+        if (!isHelpTemplateSlot(slot)) {
+            throw new TypeError(`帮助事实文案包含未知槽位 ${slot}`);
+        }
+        const template = copySingleLineText(raw, `帮助事实模板 ${slot}`);
+        const required = new Set(helpTemplatePlaceholders[slot]);
+        const placeholders = [
+            ...template.matchAll(/\{([A-Za-z][A-Za-z0-9]*)\}/g),
+        ].map((match) => match[1] ?? "");
+        const outside = template.replace(/\{[A-Za-z][A-Za-z0-9]*\}/g, "");
+        if (template.trim().length === 0 ||
+            outside.includes("{") ||
+            outside.includes("}") ||
+            placeholders.some((placeholder) => !required.has(placeholder)) ||
+            [...required].some((placeholder) => !placeholders.includes(placeholder))) {
+            throw new TypeError(`帮助事实模板 ${slot} 的占位符无效`);
+        }
+        wording[slot] = template;
+    }
+    return Object.freeze(wording);
+}
+function isHelpTemplateSlot(slot) {
+    return Object.hasOwn(helpTemplatePlaceholders, slot);
+}
+/**
+ * 在根契约显式装配版本提前请求，并自动覆盖整棵命令树。`value` 与可选
+ * `description` 均由消费者拥有；核心只注册固定 spelling、投影帮助并写出 value，
+ * 不读取包元数据、不添加前缀或默认说明，也不把版本当作命令输入。
+ */
+export function versionCapability(definition) {
+    assertKnownCapabilityOptions(definition, definitionPropertyKeys.capability.version, "version");
+    const value = copyVersionTextLine(definition.value);
+    const description = definition.description === undefined
+        ? undefined
+        : copyVersionLine(definition.description);
+    if (definition.shortAlias !== undefined && definition.shortAlias !== "-V") {
+        throw new TypeError("版本短别名必须是 -V");
+    }
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- versionCapability 由本工厂签发并登记到 WeakSet，类型品牌不在运行时输出。
+    const capability = Object.freeze({
+        kind: "versionCapability",
+        value,
+        ...(description === undefined ? {} : { description }),
+        ...(definition.shortAlias === undefined
+            ? {}
+            : { shortAlias: definition.shortAlias }),
+    });
+    versionCapabilities.add(capability);
+    return capability;
+}
+function copyVersionTextLine(value) {
+    if (typeof value !== "object" ||
+        value === null ||
+        !("kind" in value) ||
+        value.kind !== "line" ||
+        !("value" in value)) {
+        throw new TypeError("版本值必须是合法单行文本");
+    }
+    return copySingleLineText(value.value, "版本值");
+}
+function copyVersionLine(value, label = "版本描述") {
+    return copySingleLineText(value, label);
+}
+function compileHelpSupplement(command, value, issues) {
+    if (value === undefined)
+        return undefined;
+    if (!isIssuedTextProjection(value) || value.kind !== "lines") {
+        issues.push({ code: "invalidHelpSupplement", command });
+        return undefined;
+    }
+    return deepFreeze([...value.lines]);
+}
+function compileControls(definition) {
+    const version = isVersionCapability(definition.version)
+        ? definition.version
+        : undefined;
+    return deepFreeze({
+        help: {
+            longOption: definition.help.longOption,
+            ...(definition.help.shortAlias === undefined
+                ? {}
+                : { shortAlias: definition.help.shortAlias }),
+            ...(definition.help.headings === undefined
+                ? {}
+                : { headings: definition.help.headings }),
+            ...(definition.help.wording === undefined
+                ? {}
+                : { wording: definition.help.wording }),
+        },
+        ...(version === undefined
+            ? {}
+            : {
+                version: {
+                    longOption: "--version",
+                    ...(version.shortAlias === undefined
+                        ? {}
+                        : { shortAlias: version.shortAlias }),
+                    value: version.value,
+                    ...(version.description === undefined
+                        ? {}
+                        : { description: version.description }),
+                },
+            }),
+        output: {
+            defaultFormat: definition.output.defaultFormat,
+            formats: definition.output.formats,
+            ...(definition.output.formats.includes("text")
+                ? { selector: "--output-format" }
+                : {}),
+            ...(Object.keys(definition.output.compatibilityFlags).length === 0
+                ? {}
+                : { compatibilityFlags: definition.output.compatibilityFlags }),
+        },
+    });
+}
+/**
+ * 在根契约显式装配一次应用结果的输出格式能力，并自动覆盖整棵命令树。
+ * 它把 selector 与兼容 flag 保留为调用控制，不进入命令 input 或 handler；帮助、版本
+ * 与用法失败使用各自固定投影。`defaultFormat`、text 支持和兼容映射必须由消费者
+ * 显式选择，不能在命令节点另行装配格式或输出 profile。
+ */
+export function outputCapability(definition) {
+    assertKnownCapabilityOptions(definition, definitionPropertyKeys.capability.output, "output");
+    const formats = definition.defaultFormat === "text" || definition.text === true
+        ? ["structured", "text"]
+        : ["structured"];
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- outputCapability 由本工厂签发并登记到 WeakSet，类型品牌不在运行时输出。
+    const capability = Object.freeze({
+        kind: "outputCapability",
+        defaultFormat: definition.defaultFormat,
+        formats: Object.freeze(formats),
+        compatibilityFlags: Object.freeze(definition.compatibilityFlags === undefined
+            ? {}
+            : definition.compatibilityFlags),
+    });
+    outputCapabilities.add(capability);
+    return capability;
+}
+function assertKnownCapabilityOptions(definition, allowed, capability) {
+    for (const property of Object.keys(definition)) {
+        if (!allowed.includes(property)) {
+            throw new TypeError(`${capability} 能力包含未知属性 ${property}`);
+        }
+    }
+}
+/**
+ * 定义一个闭合 CLI 契约。根级 help 与 output 能力在此处一次装配，并据此约束根命令的结果投影；
+ * 动态声明仍会在定义期报告 `ContractDefinitionError`，不能以它替代静态可判定声明的类型检查。
+ * @see {@link https://github.com/YKDZ/cli-contract/tree/v0.2.1/packages/example | 端到端示例}
+ */
+export function defineCli() {
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 公共泛型定义接口由此运行时编译入口实现，类型参数只约束调用方。
+    const define = ((definition) => compileCli(definition));
+    Object.defineProperty(define, "command", {
+        configurable: true,
+        value: (command) => (definition) => Object.freeze({
+            [command]: Object.freeze({
+                ...definition,
+                [executableCommandType]: true,
+            }),
+        }),
+    });
+    return define;
+}
+function compileCli(definition) {
+    const issues = [];
+    collectUnknownDefinitionProperties(definition, issues);
+    const isHierarchy = definition.commands[definition.root]?.kind === "rootGroup";
+    const helpWording = helpCapabilities.has(definition.help)
+        ? definition.help.wording
+        : undefined;
+    if (isTextOutputEnabled(definition.output)) {
+        for (const slot of ["choices", "default"]) {
+            if (helpWording?.[slot] === undefined) {
+                reportMissingHelpFactTemplate(issues, definition.root, slot);
+            }
+        }
+    }
+    let orderedIds;
+    if (isHierarchy) {
+        collectCliBaseIssues(definition, issues);
+        orderedIds = orderHierarchy(definition, issues);
+        if (helpWording?.commandPlaceholder === undefined) {
+            reportMissingHelpFactTemplate(issues, definition.root, "commandPlaceholder");
+        }
+    }
+    else {
+        orderedIds =
+            collectRootDefinitionIssues(definition, issues) === undefined
+                ? []
+                : [definition.root];
+    }
+    if (isHierarchy && issues.length > 0) {
+        throw new ContractDefinitionError(
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- issues.length 已检查为正数，动态数组在此恢复非空元组类型。
+        issues);
+    }
+    const runtimeCommands = {};
+    const grammarNodes = [];
+    const manifestCommands = {};
+    const wire = {};
+    for (const id of orderedIds) {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- orderedIds 来自已验证的命令键或根键。
+        const node = definition.commands[id];
+        const aliases = Object.freeze([...(node.aliases ?? [])]);
+        const helpSupplement = compileHelpSupplement(id, node.helpSupplement, issues);
+        if (node.kind === "rootGroup" || node.kind === "commandGroup") {
+            const usage = deepFreeze({
+                command: id,
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 层级契约已在进入循环前检查 commandPlaceholder 必填。
+                synopsis: `${commandPath(id, definition.commands)} <${helpWording?.commandPlaceholder}>`,
+            });
+            const compiledNode = {
+                id,
+                kind: node.kind,
+                ...(node.parent === undefined ? {} : { parent: node.parent }),
+                name: node.name,
+                aliases,
+                description: node.description,
+                ...(helpSupplement === undefined ? {} : { helpSupplement }),
+                usage,
+            };
+            runtimeCommands[id] = compiledNode;
+            if (id !== definition.root) {
+                grammarNodes.push(deepFreeze({
+                    kind: "commandGroup",
+                    id,
+                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 非根命令组的 parent 已在层级定义检查中确认。
+                    parent: node.parent,
+                    name: node.name,
+                    aliases,
+                    description: node.description,
+                    ...(helpSupplement === undefined ? {} : { helpSupplement }),
+                    usage,
+                }));
+            }
+            manifestCommands[id] = deepFreeze({
+                kind: node.kind,
+                ...(node.parent === undefined ? {} : { parent: node.parent }),
+                name: node.name,
+                aliases,
+                description: node.description,
+                ...(helpSupplement === undefined ? {} : { helpSupplement }),
+            });
+            continue;
+        }
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 命令组分支已继续下一轮；其余节点按可执行定义编译。
+        const executable = node;
+        if (typeof executable.handler !== "function") {
+            issues.push({ code: "invalidCommandHandler", command: id });
+        }
+        const input = compileContractSchema(executable.input, { command: id, location: "input" }, issues);
+        const compiledSuccess = compileSuccess(id, executable.success, isTextOutputEnabled(definition.output), issues);
+        const compiledFailures = compileFailures(id, executable.failures, issues);
+        collectTextPresenterIssues(id, isTextOutputEnabled(definition.output), executable.success, executable.failures, issues);
+        const fields = input === undefined
+            ? []
+            : compileInputFields(executable.fields ?? {}, input.inputSchema, id, issues);
+        if (fields.some((field) => field.choices !== undefined) &&
+            helpWording?.choices === undefined) {
+            reportMissingHelpFactTemplate(issues, id, "choices");
+        }
+        if (fields.some((field) => field.default !== undefined) &&
+            helpWording?.default === undefined) {
+            reportMissingHelpFactTemplate(issues, id, "default");
+        }
+        const describedInput = input === undefined ? undefined : projectFieldDescriptions(input, fields);
+        collectControlFieldConflicts(id, fields, definition, issues);
+        const usageConstraints = compileUsageConstraints(executable.usageConstraints === undefined
+            ? []
+            : executable.usageConstraints, fields, id, issues);
+        for (const slot of new Set(usageConstraints.map((constraint) => constraint.kind))) {
+            if (helpWording?.[slot] === undefined) {
+                reportMissingHelpFactTemplate(issues, id, slot);
+            }
+        }
+        const usage = deepFreeze({
+            command: id,
+            synopsis: createUsageSynopsis(commandPath(id, definition.commands), fields),
+        });
+        runtimeCommands[id] = Object.freeze({
+            id,
+            kind: executable.kind,
+            ...(executable.parent === undefined ? {} : { parent: executable.parent }),
+            name: executable.name,
+            aliases,
+            description: executable.description,
+            ...(helpSupplement === undefined ? {} : { helpSupplement }),
+            fields,
+            usageConstraints,
+            usage,
+            input: executable.input,
+            success: compiledSuccess.runtime,
+            failures: compiledFailures.runtime,
+            handler: executable.handler,
+        });
+        if (executable.kind === "command") {
+            grammarNodes.push(deepFreeze({
+                kind: "command",
+                id,
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- kind 为 command 时，层级定义检查已确认 parent。
+                parent: executable.parent,
+                name: executable.name,
+                aliases,
+                description: executable.description,
+                ...(helpSupplement === undefined ? {} : { helpSupplement }),
+                fields,
+                ...(usageConstraints.length === 0 ? {} : { usageConstraints }),
+                usage,
+            }));
+        }
+        if (describedInput === undefined)
+            continue;
+        const manifestDetails = {
+            description: executable.description,
+            ...(helpSupplement === undefined ? {} : { helpSupplement }),
+            fields,
+            ...(usageConstraints.length === 0 ? {} : { usageConstraints }),
+            input: projectUsageConstraints(describedInput, usageConstraints),
+            success: compiledSuccess.manifest,
+            failures: compiledFailures.manifest,
+        };
+        manifestCommands[id] =
+            executable.kind === "command"
+                ? deepFreeze({
+                    kind: "command",
+                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- kind 为 command 时，层级定义检查已确认 parent。
+                    parent: executable.parent,
+                    name: executable.name,
+                    aliases,
+                    ...manifestDetails,
+                })
+                : deepFreeze({
+                    kind: "rootCommand",
+                    name: executable.name,
+                    ...manifestDetails,
+                });
+        wire[id] = deepFreeze({
+            ...compiledSuccess.wire,
+            ...(Object.keys(compiledFailures.wire).length === 0
+                ? {}
+                : { failure: compiledFailures.wire }),
+        });
+    }
+    if (issues.length > 0)
+        throw new ContractDefinitionError(
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- issues.length 已检查为正数，动态数组在此恢复非空元组类型。
+        issues);
+    const controls = compileControls(definition);
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 定义检查通过后根命令已在编译循环写入映射。
+    const rootCommand = runtimeCommands[definition.root];
+    const rootGrammar = isCompiledExecutable(rootCommand)
+        ? {
+            kind: "rootCommand",
+            id: rootCommand.id,
+            name: rootCommand.name,
+            description: rootCommand.description,
+            ...(rootCommand.helpSupplement === undefined
+                ? {}
+                : { helpSupplement: rootCommand.helpSupplement }),
+            fields: rootCommand.fields,
+            ...(rootCommand.usageConstraints.length === 0
+                ? {}
+                : { usageConstraints: rootCommand.usageConstraints }),
+            usage: rootCommand.usage,
+        }
+        : {
+            kind: "rootGroup",
+            id: rootCommand.id,
+            name: rootCommand.name,
+            aliases: rootCommand.aliases,
+            description: rootCommand.description,
+            ...(rootCommand.helpSupplement === undefined
+                ? {}
+                : { helpSupplement: rootCommand.helpSupplement }),
+            usage: rootCommand.usage,
+        };
+    const grammar = deepFreeze({
+        root: rootGrammar,
+        nodes: grammarNodes,
+        controls,
+    });
+    const manifest = deepFreeze({
+        schemaVersion: "3",
+        root: definition.root,
+        commands: manifestCommands,
+        controls,
+        usageFailure: {
+            exitCode: definition.usageFailureExitCode,
+            wire: createUsageFailureWireSchema(Object.values(runtimeCommands).map((command) => ({
+                command: command.id,
+                usage: command.usage.synopsis,
+                helpArgv: usageFailureHelpArgv(runtimeCommands, command.id),
+            }))),
+        },
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 根命令的 wire 已由同一编译循环写入映射。
+        wire: isHierarchy ? wire : wire[definition.root],
+    });
+    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 契约类型品牌由编译器签发，并登记到 compiledCliContracts。
+    const contract = Object.freeze({
+        grammar,
+        manifest,
+    });
+    compiledCliContracts.set(contract, {
+        contract,
+        root: definition.root,
+        usageFailureExitCode: definition.usageFailureExitCode,
+        commands: deepFreeze(runtimeCommands),
+    });
+    return contract;
+}
+function reportMissingHelpFactTemplate(issues, command, slot) {
+    if (issues.some((issue) => issue.code === "missingHelpFactTemplate" &&
+        issue.command === command &&
+        issue.slot === slot)) {
+        return;
+    }
+    issues.push({ code: "missingHelpFactTemplate", command, slot });
+}
+function collectUnknownProperties(value, path, allowed, issues) {
+    if (!isPlainRecord(value))
+        return;
+    for (const property of Object.keys(value)) {
+        if (!allowed.includes(property)) {
+            issues.push({
+                code: "unknownDefinitionProperty",
+                path: [...path, property],
+            });
+        }
+    }
+}
+function collectUnknownVariantProperties(definitions, path, allowed, issues) {
+    if (!isPlainRecord(definitions))
+        return;
+    for (const [variant, definition] of Object.entries(definitions)) {
+        collectUnknownProperties(definition, [...path, variant], allowed, issues);
+    }
+}
+function collectUnknownDefinitionProperties(definition, issues) {
+    collectUnknownProperties(definition, [], definitionPropertyKeys.cli, issues);
+    if (!isPlainRecord(definition.commands))
+        return;
+    for (const [command, node] of Object.entries(definition.commands)) {
+        const path = ["commands", command];
+        if (!isPlainRecord(node))
+            continue;
+        if (node.kind === "rootGroup" || node.kind === "commandGroup") {
+            collectUnknownProperties(node, path, definitionPropertyKeys.group, issues);
+            continue;
+        }
+        if (node.kind !== "rootCommand" && node.kind !== "command")
+            continue;
+        collectUnknownProperties(node, path, definitionPropertyKeys.command, issues);
+        if (isPlainRecord(node.fields)) {
+            for (const [field, fieldDefinition] of Object.entries(node.fields)) {
+                const fieldPath = [...path, "fields", field];
+                if (!isPlainRecord(fieldDefinition))
+                    continue;
+                const allowed = fieldDefinition.kind === "flag"
+                    ? definitionPropertyKeys.field.flag
+                    : fieldDefinition.kind === "valueOption" ||
+                        fieldDefinition.kind === "repeatableOption"
+                        ? definitionPropertyKeys.field.option
+                        : fieldDefinition.kind === "positional" ||
+                            fieldDefinition.kind === "variadicPositional"
+                            ? definitionPropertyKeys.field.positional
+                            : undefined;
+                if (allowed !== undefined) {
+                    collectUnknownProperties(fieldDefinition, fieldPath, allowed, issues);
+                }
+            }
+        }
+        if (Array.isArray(node.usageConstraints)) {
+            node.usageConstraints.forEach((constraint, index) => {
+                const constraintPath = [...path, "usageConstraints", String(index)];
+                if (!isPlainRecord(constraint))
+                    return;
+                const allowed = constraint.kind === "requires"
+                    ? definitionPropertyKeys.usage.requires
+                    : constraint.kind === "exclusive"
+                        ? definitionPropertyKeys.usage.exclusive
+                        : constraint.kind === "forbiddenCombination"
+                            ? definitionPropertyKeys.usage.forbiddenCombination
+                            : undefined;
+                if (allowed === undefined)
+                    return;
+                collectUnknownProperties(constraint, constraintPath, allowed, issues);
+                if (constraint.kind === "forbiddenCombination" &&
+                    Array.isArray(constraint.values)) {
+                    constraint.values.forEach((value, valueIndex) => collectUnknownProperties(value, [...constraintPath, "values", String(valueIndex)], definitionPropertyKeys.usage.value, issues));
+                }
+            });
+        }
+        if (isPlainRecord(node.success)) {
+            const successPath = [...path, "success"];
+            const success = node.success;
+            if (success.kind === "completion") {
+                collectUnknownProperties(success, successPath, definitionPropertyKeys.success.completion, issues);
+            }
+            else if (success.kind === "data") {
+                collectUnknownProperties(success, successPath, definitionPropertyKeys.success.data, issues);
+                collectUnknownVariantProperties(success.variants, [...successPath, "variants"], definitionPropertyKeys.atomicVariant, issues);
+            }
+            else if (success.kind === "stream") {
+                collectUnknownProperties(success, successPath, definitionPropertyKeys.success.stream, issues);
+                collectUnknownVariantProperties(success.records, [...successPath, "records"], definitionPropertyKeys.streamRecord, issues);
+            }
+        }
+        collectUnknownVariantProperties(node.failures, [...path, "failures"], definitionPropertyKeys.atomicVariant, issues);
+    }
+}
+export function getCompiledCli(contract) {
+    const compiled = compiledCliContracts.get(contract);
+    if (compiled === undefined) {
+        throw new ContractExecutionError([{ code: "invalidCliContract" }]);
+    }
+    return compiled;
+}
+function collectRootDefinitionIssues(definition, issues) {
+    collectCliBaseIssues(definition, issues);
+    const commandKeys = Object.keys(definition.commands);
+    const command = definition.commands[definition.root];
+    if (command === undefined || commandKeys.length !== 1) {
+        issues.push({
+            code: "invalidRootCommandSet",
+            root: definition.root,
+            // oxlint-disable-next-line unicorn/no-array-sort -- commandKeys 来自 Object.keys 且不再复用，原地排序不会影响命令对象。
+            receivedCommands: commandKeys.sort(),
+        });
+    }
+    if (command === undefined)
+        return undefined;
+    if (command.kind !== "rootCommand") {
+        issues.push({
+            code: "invalidRootCommandKind",
+            command: definition.root,
+            received: typeof command.kind === "string" ? command.kind : null,
+        });
+        return undefined;
+    }
+    if (command.name.length === 0) {
+        issues.push({
+            code: "missingCommandText",
+            command: definition.root,
+            field: "name",
+        });
+    }
+    if (!isSingleLineText(command.description)) {
+        issues.push({
+            code: "invalidDescription",
+            command: definition.root,
+            location: "command",
+            received: typeof command.description === "string" ? command.description : null,
+        });
+    }
+    return command;
+}
+function collectCliBaseIssues(definition, issues) {
+    if (!/^[a-z][A-Za-z0-9]*$/.test(definition.root)) {
+        issues.push({
+            code: "invalidCommandIdentity",
+            command: definition.root,
+        });
+    }
+    if (!helpCapabilities.has(definition.help)) {
+        issues.push({ code: "invalidCapability", capability: "help" });
+    }
+    if (definition.version !== undefined &&
+        !versionCapabilities.has(definition.version)) {
+        issues.push({ code: "invalidCapability", capability: "version" });
+    }
+    if (!outputCapabilities.has(definition.output)) {
+        issues.push({ code: "invalidCapability", capability: "output" });
+    }
+    else if (!definition.output.formats.includes(definition.output.defaultFormat)) {
+        issues.push({
+            code: "invalidOutputFormat",
+            expected: "structured|text",
+            received: typeof definition.output.defaultFormat === "string"
+                ? definition.output.defaultFormat
+                : null,
+        });
+    }
+    else if (!isPlainRecord(definition.output.compatibilityFlags)) {
+        issues.push({
+            code: "invalidOutputCompatibilityFlags",
+            received: outputCompatibilityFlagsKind(definition.output.compatibilityFlags),
+        });
+    }
+    else {
+        for (const [flag, format] of Object.entries(definition.output.compatibilityFlags)) {
+            if (!/^--[a-z0-9]+(?:-[a-z0-9]+)*$/.test(flag) ||
+                flag === "--help" ||
+                flag === "--output-format" ||
+                (isVersionCapability(definition.version) && flag === "--version") ||
+                !definition.output.formats.includes(format)) {
+                issues.push({
+                    code: "invalidOutputCompatibilityFlag",
+                    flag,
+                    received: typeof format === "string" ? format : null,
+                });
+            }
+        }
+    }
+    if (!Number.isInteger(definition.usageFailureExitCode) ||
+        definition.usageFailureExitCode < 1 ||
+        definition.usageFailureExitCode > 255) {
+        issues.push({
+            code: "invalidUsageFailureExitCode",
+            received: typeof definition.usageFailureExitCode === "number"
+                ? definition.usageFailureExitCode
+                : null,
+            minimum: 1,
+            maximum: 255,
+        });
+    }
+}
+function orderHierarchy(definition, issues) {
+    const ids = Object.keys(definition.commands);
+    if (!ids.some((id) => definition.commands[id]?.parent === definition.root)) {
+        issues.push({ code: "rootGroupWithoutChildren", command: definition.root });
+    }
+    for (const id of ids) {
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- id 来自 Object.keys(definition.commands)，此处读取同一对象。
+        const node = definition.commands[id];
+        if (!/^[a-z][A-Za-z0-9]*$/.test(id))
+            issues.push({ code: "invalidCommandIdentity", command: id });
+        if (node.name.length === 0)
+            issues.push({ code: "missingCommandText", command: id, field: "name" });
+        if (!isSingleLineText(node.description))
+            issues.push({
+                code: "invalidDescription",
+                command: id,
+                location: "command",
+                received: typeof node.description === "string" ? node.description : null,
+            });
+        if (id === definition.root && node.kind !== "rootGroup") {
+            issues.push({
+                code: "invalidRootCommandKind",
+                command: id,
+                received: node.kind,
+            });
+        }
+        if (id === definition.root && node.parent !== undefined) {
+            issues.push({
+                code: "invalidCommandParent",
+                command: id,
+                parent: node.parent,
+            });
+        }
+        if (id !== definition.root &&
+            (node.kind === "rootGroup" || node.kind === "rootCommand")) {
+            issues.push({
+                code: "invalidCommandNodeKind",
+                command: id,
+                received: node.kind,
+            });
+        }
+        if ((node.kind === "rootGroup" || node.kind === "commandGroup") &&
+            "handler" in node) {
+            issues.push({ code: "invalidCommandHandler", command: id });
+        }
+        if (id !== definition.root &&
+            (node.parent === undefined ||
+                definition.commands[node.parent] === undefined)) {
+            issues.push({
+                code: "invalidCommandParent",
+                command: id,
+                parent: node.parent ?? null,
+            });
+        }
+        else if (id !== definition.root &&
+            node.parent !== undefined &&
+            definition.commands[node.parent]?.kind !== "rootGroup" &&
+            definition.commands[node.parent]?.kind !== "commandGroup") {
+            issues.push({
+                code: "invalidCommandParent",
+                command: id,
+                parent: node.parent,
+            });
+        }
+        for (const spelling of [node.name, ...(node.aliases ?? [])]) {
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(spelling)) {
+                issues.push({ code: "invalidCommandSpelling", command: id, spelling });
+            }
+        }
+    }
+    const cycleMembers = ids.filter((id) => {
+        const visited = new Set();
+        let current = id;
+        while (current !== undefined &&
+            definition.commands[current] !== undefined) {
+            if (visited.has(current))
+                return true;
+            visited.add(current);
+            current = definition.commands[current]?.parent;
+        }
+        return false;
+    });
+    if (cycleMembers.length > 0)
+        issues.push({
+            code: "commandHierarchyCycle",
+            commands: Object.freeze(cycleMembers),
+        });
+    for (const parent of ids) {
+        const spellings = new Map();
+        for (const child of ids.filter((id) => definition.commands[id]?.parent === parent)) {
+            // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- child 来自同一命令对象的键集合。
+            const node = definition.commands[child];
+            for (const spelling of [node.name, ...(node.aliases ?? [])]) {
+                const owners = spellings.get(spelling) ?? [];
+                owners.push(child);
+                spellings.set(spelling, owners);
+            }
+        }
+        for (const [spelling, commands] of spellings) {
+            if (commands.length > 1) {
+                issues.push({
+                    code: "duplicateCommandSpelling",
+                    parent,
+                    spelling,
+                    commands: Object.freeze(commands),
+                });
+            }
+        }
+    }
+    const ordered = [];
+    const visit = (id) => {
+        if (ordered.includes(id))
+            return;
+        ordered.push(id);
+        for (const child of ids)
+            if (definition.commands[child]?.parent === id)
+                visit(child);
+    };
+    if (definition.commands[definition.root] !== undefined)
+        visit(definition.root);
+    return [...ordered, ...ids.filter((id) => !ordered.includes(id))];
+}
+function commandPath(id, commands) {
+    return commandPathTokens(id, commands).join(" ");
+}
+function commandPathTokens(id, commands) {
+    const names = [];
+    let current = id;
+    while (current !== undefined) {
+        const node = commands[current];
+        if (node === undefined)
+            break;
+        names.unshift(node.name);
+        current = node.parent;
+    }
+    return names;
+}
+export function usageFailureHelpArgv(commands, command) {
+    const path = [];
+    let current = commands[command];
+    while (current !== undefined) {
+        path.unshift(current.name);
+        current =
+            current.parent === undefined ? undefined : commands[current.parent];
+    }
+    return [...path, "--help"];
+}
+function compileUsageConstraints(definitions, fields, command, issues) {
+    const fieldsByKey = new Map(fields.map((field) => [field.key, field]));
+    const compiled = [];
+    if (!Array.isArray(definitions)) {
+        issues.push({
+            code: "invalidUsageConstraint",
+            command,
+            index: null,
+            aspect: "collection",
+            received: null,
+        });
+        return deepFreeze(compiled);
+    }
+    for (const [index, definition] of definitions.entries()) {
+        if (typeof definition !== "object" || definition === null) {
+            issues.push({
+                code: "invalidUsageConstraint",
+                command,
+                index,
+                aspect: "entry",
+                received: null,
+            });
+            continue;
+        }
+        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 定义条目已通过非 null 对象检查，此处读取动态属性。
+        const candidate = definition;
+        if (candidate.kind !== "requires" &&
+            candidate.kind !== "exclusive" &&
+            candidate.kind !== "forbiddenCombination") {
+            issues.push({
+                code: "invalidUsageConstraint",
+                command,
+                index,
+                aspect: "kind",
+                received: typeof candidate.kind === "string" ? candidate.kind : null,
+            });
+            continue;
+        }
+        if (candidate.kind === "requires") {
+            if (typeof candidate.field !== "string" ||
+                typeof candidate.requires !== "string") {
+                issues.push({
+                    code: "invalidUsageConstraint",
+                    command,
+                    index,
+                    aspect: "members",
+                    received: "requires",
+                });
+                continue;
+            }
+            const field = fieldsByKey.get(candidate.field);
+            const required = fieldsByKey.get(candidate.requires);
+            if (field === undefined)
+                issues.push({
+                    code: "unknownUsageConstraintField",
+                    command,
+                    constraint: "requires",
+                    index,
+                    member: "field",
+                    field: candidate.field,
+                });
+            if (required === undefined)
+                issues.push({
+                    code: "unknownUsageConstraintField",
+                    command,
+                    constraint: "requires",
+                    index,
+                    member: "requires",
+                    field: candidate.requires,
+                });
+            if (field !== undefined && required !== undefined) {
+                if (!isOptionalOption(field) || !isOptionalOption(required)) {
+                    for (const offendingField of [field, required])
+                        if (!isOptionalOption(offendingField))
+                            issues.push({
+                                code: "inapplicableUsageConstraintField",
+                                command,
+                                constraint: "requires",
+                                field: offendingField.key,
+                                kind: offendingField.kind,
+                            });
+                }
+                if (field.key === required.key)
+                    issues.push({
+                        code: "contradictoryUsageConstraint",
+                        command,
+                        constraint: "requires",
+                        fields: Object.freeze([field.key]),
+                    });
+                compiled.push(deepFreeze({
+                    kind: "requires",
+                    field: field.key,
+                    requires: required.key,
+                }));
+            }
+            continue;
+        }
+        if (candidate.kind === "exclusive") {
+            if (!Array.isArray(candidate.fields) ||
+                candidate.fields.length < 2 ||
+                !candidate.fields.every((field) => typeof field === "string")) {
+                issues.push({
+                    code: "invalidUsageConstraint",
+                    command,
+                    index,
+                    aspect: "members",
+                    received: "exclusive",
+                });
+                continue;
+            }
+            const selected = candidate.fields.map((key) => fieldsByKey.get(key));
+            for (const [fieldIndex, field] of selected.entries()) {
+                if (field === undefined) {
+                    issues.push({
+                        code: "unknownUsageConstraintField",
+                        command,
+                        constraint: "exclusive",
+                        index,
+                        member: "fields",
+                        // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- fields 已逐项检查为字符串，索引来自对应 selected 数组。
+                        field: candidate.fields[fieldIndex],
+                    });
+                }
+                else if (!isOptionalOption(field)) {
+                    issues.push({
+                        code: "inapplicableUsageConstraintField",
+                        command,
+                        constraint: "exclusive",
+                        field: field.key,
+                        kind: field.kind,
+                    });
+                }
+            }
+            const fieldsInConstraint = candidate.fields;
+            if (new Set(fieldsInConstraint).size !== fieldsInConstraint.length)
+                issues.push({
+                    code: "contradictoryUsageConstraint",
+                    command,
+                    constraint: "exclusive",
+                    fields: Object.freeze([...fieldsInConstraint]),
+                });
+            if (selected.every((field) => field !== undefined))
+                compiled.push(deepFreeze({
+                    kind: "exclusive",
+                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- fields 已检查至少两个字符串，冻结后保留非空元组长度。
+                    fields: Object.freeze([...fieldsInConstraint]),
+                }));
+            continue;
+        }
+        if (candidate.kind === "forbiddenCombination") {
+            if (!Array.isArray(candidate.values) ||
+                candidate.values.length < 2 ||
+                !candidate.values.every((value) => typeof value === "object" &&
+                    value !== null &&
+                    typeof value.field === "string" &&
+                    (typeof value.value === "string" ||
+                        typeof value.value === "boolean"))) {
+                issues.push({
+                    code: "invalidUsageConstraint",
+                    command,
+                    index,
+                    aspect: "members",
+                    received: "forbiddenCombination",
+                });
+                continue;
+            }
+            const values = [];
+            for (const value of candidate.values) {
+                // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- values 已逐项检查 field 和 value 的运行时类型。
+                const discreteValue = value;
+                const field = fieldsByKey.get(discreteValue.field);
+                if (field === undefined) {
+                    issues.push({
+                        code: "unknownUsageConstraintField",
+                        command,
+                        constraint: "forbiddenCombination",
+                        index,
+                        member: "values.field",
+                        field: discreteValue.field,
+                    });
+                    continue;
+                }
+                if (field.kind !== "flag" && field.kind !== "valueOption") {
+                    issues.push({
+                        code: "inapplicableUsageConstraintField",
+                        command,
+                        constraint: "forbiddenCombination",
+                        field: field.key,
+                        kind: field.kind,
+                    });
+                    continue;
+                }
+                if ((field.kind === "flag" && typeof discreteValue.value !== "boolean") ||
+                    (field.kind === "valueOption" &&
+                        typeof discreteValue.value !== "string")) {
+                    issues.push({
+                        code: "invalidUsageConstraintValue",
+                        command,
+                        field: field.key,
+                        expected: field.kind === "flag" ? "boolean" : "string",
+                    });
+                    continue;
+                }
+                values.push({ field: field.key, value: discreteValue.value });
+            }
+            const duplicateValueField = values.some((value, valueIndex) => values.findIndex(({ field }) => field === value.field) !== valueIndex);
+            if (duplicateValueField)
+                issues.push({
+                    code: "contradictoryUsageConstraint",
+                    command,
+                    constraint: "forbiddenCombination",
+                    fields: Object.freeze(values.map(({ field }) => field)),
+                });
+            if (values.length === candidate.values.length)
+                compiled.push(deepFreeze({
+                    kind: "forbiddenCombination",
+                    // oxlint-disable-next-line typescript/no-unsafe-type-assertion -- 源 values 至少两项，且映射长度相等才进入此分支。
+                    values: Object.freeze(values),
+                }));
+            continue;
+        }
+        issues.push({
+            code: "invalidUsageConstraint",
+            command,
+            index,
+            aspect: "kind",
+            received: null,
+        });
+    }
+    for (const constraint of compiled) {
+        if (constraint.kind !== "requires")
+            continue;
+        if (constraint.field === constraint.requires)
+            continue;
+        const exclusive = compiled.find((candidate) => candidate.kind === "exclusive" &&
+            candidate.fields.includes(constraint.field) &&
+            candidate.fields.includes(constraint.requires));
+        if (exclusive !== undefined)
+            issues.push({
+                code: "contradictoryUsageConstraint",
+                command,
+                constraint: "requires",
+                fields: Object.freeze([constraint.field, constraint.requires]),
+            });
+    }
+    return deepFreeze(compiled);
+}
+function isOptionalOption(field) {
+    return (!field.required &&
+        field.kind !== "positional" &&
+        field.kind !== "variadicPositional");
+}
+function projectUsageConstraints(schema, constraints) {
+    if (constraints.length === 0)
+        return schema;
+    const constraintSchemas = [];
+    for (const constraint of constraints) {
+        if (constraint.kind === "requires") {
+            constraintSchemas.push(Object.fromEntries([
+                ["if", { required: [constraint.field] }],
+                // oxlint-disable-next-line unicorn/no-thenable -- Draft 2020-12 固定关键字。
+                ["then", { required: [constraint.requires] }],
+            ]));
+            continue;
+        }
+        if (constraint.kind === "exclusive") {
+            constraintSchemas.push({
+                not: {
+                    anyOf: constraint.fields.flatMap((field, index) => constraint.fields.slice(index + 1).map((other) => ({
+                        required: [field, other],
+                    }))),
+                },
+            });
+            continue;
+        }
+        constraintSchemas.push({
+            not: {
+                allOf: constraint.values.map(({ field, value }) => ({
+                    properties: { [field]: { const: value } },
+                    required: [field],
+                })),
+            },
+        });
+    }
+    return deepFreeze({
+        inputSchema: {
+            ...schema.inputSchema,
+            allOf: [
+                ...(Array.isArray(schema.inputSchema.allOf)
+                    ? schema.inputSchema.allOf
+                    : []),
+                ...constraintSchemas,
+            ],
+        },
+        outputSchema: schema.outputSchema,
+    });
+}
+function compileFailures(command, failures, issues) {
+    const compiled = compileAtomicVariants(command, "failure", failures, 1, createFailureWireSchema, issues);
+    return {
+        runtime: compiled.runtime,
+        manifest: compiled.manifest,
+        wire: compiled.wire,
+    };
+}
+function collectTextPresenterIssues(command, textEnabled, success, failures, issues) {
+    if (success.kind === "completion") {
+        collectTextPresenterIssue(command, textEnabled, "completion", success, issues);
+    }
+    else if (success.kind === "data") {
+        for (const [variant, definition] of Object.entries(success.variants)) {
+            collectTextPresenterIssue(command, textEnabled, "data", definition, issues, variant);
+        }
+    }
+    else {
+        collectTextPresenterIssue(command, textEnabled, "streamSuccess", success, issues);
+        for (const [variant, definition] of Object.entries(success.records)) {
+            collectTextPresenterIssue(command, textEnabled, "record", definition, issues, variant);
+        }
+    }
+    for (const [variant, definition] of Object.entries(failures)) {
+        collectTextPresenterIssue(command, textEnabled, "failure", definition, issues, variant);
+    }
+}
+function isTextOutputEnabled(output) {
+    return isOutputCapability(output) && output.formats.includes("text");
+}
+function isOutputCapability(value) {
+    return (typeof value === "object" && value !== null && outputCapabilities.has(value));
+}
+function isVersionCapability(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        versionCapabilities.has(value));
+}
+function collectControlFieldConflicts(command, fields, definition, issues) {
+    const controls = new Map([
+        ["--help", "help"],
+    ]);
+    if (helpCapabilities.has(definition.help) &&
+        definition.help.shortAlias !== undefined) {
+        controls.set(definition.help.shortAlias, "help");
+    }
+    if (outputCapabilities.has(definition.output) &&
+        isPlainRecord(definition.output.compatibilityFlags)) {
+        for (const spelling of Object.keys(definition.output.compatibilityFlags)) {
+            controls.set(spelling, "outputFormat");
+        }
+        if (definition.output.formats.includes("text")) {
+            controls.set("--output-format", "outputFormat");
+        }
+    }
+    if (isVersionCapability(definition.version)) {
+        const version = definition.version;
+        controls.set("--version", "version");
+        if (version.shortAlias !== undefined) {
+            controls.set(version.shortAlias, "version");
+        }
+    }
+    for (const field of fields) {
+        if (field.kind === "positional" || field.kind === "variadicPositional") {
+            continue;
+        }
+        for (const spelling of [
+            field.longOption,
+            field.shortAlias,
+            ...(field.kind === "flag" ? [field.negatedLongOption] : []),
+        ]) {
+            const control = spelling === undefined ? undefined : controls.get(spelling);
+            if (spelling !== undefined && control !== undefined) {
+                issues.push({
+                    code: "fieldOptionConflictsWithControl",
+                    command,
+                    field: field.key,
+                    spelling,
+                    control,
+                });
+            }
+        }
+    }
+}
+function isPlainRecord(value) {
+    if (value === null || typeof value !== "object" || Array.isArray(value)) {
+        return false;
+    }
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}
+function outputCompatibilityFlagsKind(value) {
+    if (value === null)
+        return "null";
+    if (Array.isArray(value))
+        return "array";
+    return typeof value;
+}
+function collectTextPresenterIssue(command, textEnabled, location, definition, issues, variant) {
+    const hasPresenter = typeof definition.text === "function";
+    if (textEnabled === hasPresenter)
+        return;
+    issues.push({
+        code: textEnabled ? "missingTextPresenter" : "unexpectedTextPresenter",
+        command,
+        location,
+        ...(variant === undefined ? {} : { variant }),
+    });
+}
+function compileSuccess(command, success, textEnabled, issues) {
+    if (success.kind === "completion") {
+        return {
+            runtime: Object.freeze({
+                kind: "completion",
+                ...("text" in success ? { text: success.text } : {}),
+            }),
+            manifest: Object.freeze({ kind: "completion" }),
+            wire: Object.freeze({
+                completion: deepFreeze(createCompletionWireSchema(command)),
+            }),
+        };
+    }
+    if (success.kind === "stream") {
+        const records = compileStreamRecords(command, success.records, issues);
+        if (Object.keys(records.runtime).length === 0) {
+            issues.push({ code: "missingStreamRecord", command });
+        }
+        const header = deepFreeze(createStreamHeaderWireSchema(command));
+        const terminal = deepFreeze(createStreamSuccessWireSchema());
+        const recordWire = Object.fromEntries(Object.entries(records.wire).map(([variant, schema]) => [
+            variant,
+            deepFreeze(createStreamRecordWireSchema(variant, schema)),
+        ]));
+        return deepFreeze({
+            runtime: {
+                kind: "stream",
+                records: records.runtime,
+                ...("text" in success ? { text: success.text } : {}),
+            },
+            manifest: {
+                kind: "stream",
+                records: records.manifest,
+                ...(textEnabled
+                    ? { text: { recordFraming: "fragment" } }
+                    : {}),
+            },
+            wire: {
+                stream: {
+                    header,
+                    records: recordWire,
+                    terminal,
+                    line: deepFreeze({
+                        $schema: "https://json-schema.org/draft/2020-12/schema",
+                        oneOf: [header, ...Object.values(recordWire), terminal],
+                    }),
+                },
+            },
+        });
+    }
+    const variants = compileAtomicVariants(command, "data", success.variants, 0, createDataWireSchema, issues);
+    if (Object.keys(variants.runtime).length === 0) {
+        issues.push({ code: "missingDataVariant", command });
+    }
+    return deepFreeze({
+        runtime: { kind: "data", variants: variants.runtime },
+        manifest: {
+            kind: "data",
+            variants: variants.manifest,
+        },
+        wire: { data: variants.wire },
+    });
+}
+function createUsageSynopsis(commandName, fields) {
+    return [commandName, ...fields.map((field) => formatFieldUsage(field))].join(" ");
+}
+export function formatFieldUsage(field, includeShortAlias = false) {
+    const value = field.kind === "positional"
+        ? `<${field.key}>`
+        : field.kind === "variadicPositional"
+            ? `<${field.key}...>`
+            : field.kind === "flag"
+                ? [
+                    field.longOption,
+                    ...(includeShortAlias && field.shortAlias !== undefined
+                        ? [field.shortAlias]
+                        : []),
+                    field.negatedLongOption,
+                ]
+                    .filter((spelling) => spelling !== undefined)
+                    .join(includeShortAlias ? ", " : "|")
+                : `${[
+                    field.longOption,
+                    ...(includeShortAlias && field.shortAlias !== undefined
+                        ? [field.shortAlias]
+                        : []),
+                ].join(", ")} <${field.key}>`;
+    if (field.kind === "repeatableOption") {
+        return field.required ? `(${value})...` : `[${value}]...`;
+    }
+    return field.required ? value : `[${value}]`;
+}