toolcraft 0.0.11 → 0.0.12

package/dist/cli.js

@@ -1,7 +1,7 @@
 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 { cancel, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "@poe-code/design-system";
 import { ApprovalDeclinedError, UserError, assertCommandRequirements, getCommandSourcePath, resolveCommandSecrets } from "./index.js";
 import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
 import { invokeWithHumanInLoop } from "./human-in-loop/index.js";
@@ -28,7 +28,7 @@ function normalizeRoots(roots, argv) {
         name: inferProgramName(argv),
         aliases: [],
         secrets: {},
-        children: roots,
+        children: roots
     };
 }
 const HELP_FLAGS = new Set(["--help", "-h"]);
@@ -56,7 +56,9 @@ function splitWords(value) {
         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 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());
@@ -116,7 +118,7 @@ function createSyntheticEnumSchema(values) {
     }
     return {
         kind: "enum",
-        values: values,
+        values: values
     };
 }
 function getRequiredBranchFingerprint(branch, casing) {
@@ -130,7 +132,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
     const collected = {
         dynamicFields: [],
         fields: [],
-        variants: [],
+        variants: []
     };
     for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
         const nextPath = [...path, key];
@@ -160,14 +162,14 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 optional: runtimeOptional,
                 hasDefault: false,
                 defaultValue: undefined,
-                requiredWhenActive,
+                requiredWhenActive
             };
             collected.fields.push(controlField);
             const branches = [];
             for (const [branchId, branchSchema] of Object.entries(childSchema.branches)) {
                 const branch = collectFields(branchSchema, casing, globalLongOptionFlags, nextPath, true, {
                     id: variantId,
-                    branchId,
+                    branchId
                 });
                 collected.dynamicFields.push(...branch.dynamicFields);
                 collected.fields.push(...branch.fields);
@@ -181,7 +183,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                         .map((field) => field.id),
                     requiredFieldIds: branch.fields
                         .filter((field) => field.requiredWhenActive)
-                        .map((field) => field.id),
+                        .map((field) => field.id)
                 });
             }
             collected.variants.push({
@@ -189,7 +191,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 controlDisplayPath: controlField.displayPath,
                 controlFieldId: controlField.id,
                 optional: runtimeOptional,
-                branches,
+                branches
             });
             continue;
         }
@@ -212,7 +214,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 hasDefault: false,
                 defaultValue: undefined,
                 requiredWhenActive,
-                synthetic: true,
+                synthetic: true
             };
             collected.fields.push(controlField);
             const branches = [];
@@ -220,7 +222,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 const branchId = branchIds[index] ?? "";
                 const branch = collectFields(branchSchema, casing, globalLongOptionFlags, nextPath, true, {
                     id: variantId,
-                    branchId,
+                    branchId
                 });
                 collected.dynamicFields.push(...branch.dynamicFields);
                 collected.fields.push(...branch.fields);
@@ -234,7 +236,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                         .map((field) => field.id),
                     requiredFieldIds: branch.fields
                         .filter((field) => field.requiredWhenActive)
-                        .map((field) => field.id),
+                        .map((field) => field.id)
                 });
             });
             collected.variants.push({
@@ -242,7 +244,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 controlDisplayPath,
                 controlFieldId: controlField.id,
                 optional: runtimeOptional,
-                branches,
+                branches
             });
             continue;
         }
@@ -261,7 +263,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 requiredWhenActive,
                 schema: childSchema,
                 variantId: variantContext?.id,
-                variantBranchId: variantContext?.branchId,
+                variantBranchId: variantContext?.branchId
             });
             continue;
         }
@@ -280,7 +282,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
                 requiredWhenActive,
                 schema: childSchema,
                 variantId: variantContext?.id,
-                variantBranchId: variantContext?.branchId,
+                variantBranchId: variantContext?.branchId
             });
             continue;
         }
@@ -299,7 +301,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
             defaultValue: childSchema.default,
             requiredWhenActive,
             variantId: variantContext?.id,
-            variantBranchId: variantContext?.branchId,
+            variantBranchId: variantContext?.branchId
         });
     }
     return collected;
@@ -460,10 +462,12 @@ function createOption(field, globalLongOptionFlags) {
         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 : commanderValue(parseBooleanText(value, field.displayPath)));
+        mainOption.argParser((value) => typeof value === "boolean"
+            ? value
+            : commanderValue(parseBooleanText(value, field.displayPath)));
         return [
             mainOption,
-            createCommanderOption(`--no-${field.optionFlag.slice(2)}`, field.description, field),
+            createCommanderOption(`--no-${field.optionFlag.slice(2)}`, field.description, field)
         ];
     }
     if (field.schema.kind === "array") {
@@ -474,16 +478,17 @@ function createOption(field, globalLongOptionFlags) {
                     return NULL_OPTION_VALUE;
                 }
                 return [...(previous ?? []), ...parsed];
-            }),
+            })
         ];
     }
     if (field.schema.kind === "json") {
         return [
-            createCommanderOption(`${flags} <json>`, field.description, field).argParser((value) => commanderValue(parseJsonText(value, field.displayPath))),
+            createCommanderOption(`${flags} <json>`, field.description, field).argParser((value) => commanderValue(parseJsonText(value, field.displayPath)))
         ];
     }
     const option = createCommanderOption(`${flags} <value>`, field.description, field);
-    if (field.schema.kind === "enum" && field.schema.values.every((value) => typeof value === "string")) {
+    if (field.schema.kind === "enum" &&
+        field.schema.values.every((value) => typeof value === "string")) {
         option.choices([...field.schema.values]);
     }
     option.argParser((value) => commanderValue(parseScalarValue(value, field.schema, field.displayPath)));
@@ -491,7 +496,9 @@ function createOption(field, globalLongOptionFlags) {
 }
 const ALWAYS_GLOBAL_LONG_OPTION_FLAGS = ["--yes", "--output", "--verbose"];
 function getGlobalLongOptionFlags(presetsEnabled) {
-    return new Set(presetsEnabled ? ["--preset", ...ALWAYS_GLOBAL_LONG_OPTION_FLAGS] : ALWAYS_GLOBAL_LONG_OPTION_FLAGS);
+    return new Set(presetsEnabled
+        ? ["--preset", ...ALWAYS_GLOBAL_LONG_OPTION_FLAGS]
+        : ALWAYS_GLOBAL_LONG_OPTION_FLAGS);
 }
 function createCommanderOption(flags, description, field) {
     const option = new Option(flags, description);
@@ -562,35 +569,23 @@ function resolveHelpTarget(root, argv, scope, rootDisplayName) {
     }
     return {
         breadcrumb,
-        node: current,
+        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))}...`;
-        case "json":
-            return "json";
-        default:
-            throw new UserError("Unsupported CLI schema kind.");
-    }
-}
 function formatHelpFieldFlags(field, globalLongOptionFlags) {
     if (field.positionalIndex !== undefined) {
         return formatPositionalToken(field);
     }
     if (field.schema.kind === "boolean") {
-        return `${formatOptionFlags(field, globalLongOptionFlags)} [value]`;
+        if (field.defaultValue === true) {
+            return `--no-${field.optionFlag.slice(2)}`;
+        }
+        return formatOptionFlags(field, globalLongOptionFlags);
     }
-    return `${formatOptionFlags(field, globalLongOptionFlags)} <${describeSchemaType(field.schema)}>`;
+    return `${formatOptionFlags(field, globalLongOptionFlags)} <${describeHelpValueToken(field.schema, {
+        displayPath: field.displayPath,
+        optionFlag: field.optionFlag
+    })}>`;
 }
 function appendHelpMetadata(description, metadata) {
     if (metadata.length === 0) {
@@ -612,6 +607,90 @@ function formatHelpFieldDescription(field) {
     }
     return appendHelpMetadata(description, metadata);
 }
+function describeKnownStringFormat(format) {
+    switch (format) {
+        case "date":
+            return "date";
+        case "date-time":
+            return "datetime";
+        case "uri":
+            return "url";
+        case "email":
+            return "email";
+        default:
+            return undefined;
+    }
+}
+function describeKnownStringPattern(pattern) {
+    if (pattern === undefined) {
+        return undefined;
+    }
+    if (pattern === "^\\d{4}-\\d{2}-\\d{2}$") {
+        return "YYYY-MM-DD";
+    }
+    if (pattern.startsWith("^\\d{4}-\\d{2}-\\d{2}T")) {
+        return "YYYY-MM-DDTHH:MM:SS";
+    }
+    return undefined;
+}
+function stripLongOptionPrefix(optionFlag) {
+    return optionFlag.startsWith("--") ? optionFlag.slice(2) : optionFlag;
+}
+function getLastSegment(value, separator) {
+    const segments = value.split(separator);
+    return segments[segments.length - 1] ?? value;
+}
+function matchesFieldNameSuffix(name, suffix) {
+    const lowerName = name.toLowerCase();
+    const lowerSuffix = suffix.toLowerCase();
+    return (lowerName === lowerSuffix ||
+        name.endsWith(suffix) ||
+        lowerName.endsWith(`-${lowerSuffix}`) ||
+        lowerName.endsWith(`_${lowerSuffix}`));
+}
+function describeFieldNameValueToken(displayPath, optionFlag) {
+    const displayName = getLastSegment(displayPath, ".");
+    const optionName = getLastSegment(stripLongOptionPrefix(optionFlag), ".");
+    const candidates = [displayName, optionName];
+    const suffixTokens = [
+        ["Path", "path"],
+        ["Paths", "path"],
+        ["File", "path"],
+        ["Files", "path"],
+        ["Url", "url"],
+        ["Email", "email"],
+        ["Name", "name"],
+        ["Id", "id"]
+    ];
+    for (const [suffix, token] of suffixTokens) {
+        if (candidates.some((candidate) => matchesFieldNameSuffix(candidate, suffix))) {
+            return token;
+        }
+    }
+    return undefined;
+}
+function describeHelpValueToken(schema, field) {
+    if (schema.kind === "array") {
+        const itemSchema = unwrapOptional(schema.item);
+        if (itemSchema.kind === "array" || itemSchema.kind === "object") {
+            return "value...";
+        }
+        return `${describeHelpValueToken(itemSchema, field)}...`;
+    }
+    if (schema.kind === "json") {
+        return "json";
+    }
+    if (schema.kind === "string") {
+        const metadataToken = describeKnownStringFormat(schema.format) ?? describeKnownStringPattern(schema.pattern);
+        if (metadataToken !== undefined) {
+            return metadataToken;
+        }
+    }
+    if (schema.kind === "enum") {
+        return "value";
+    }
+    return describeFieldNameValueToken(field.displayPath, field.optionFlag) ?? "value";
+}
 function describeDynamicFieldType(field) {
     if (field.schema.kind === "record") {
         const valueSchema = unwrapOptional(field.schema.value);
@@ -619,12 +698,18 @@ function describeDynamicFieldType(field) {
             return "json";
         }
         if (valueSchema.kind === "array") {
-            return `${describeSchemaType(valueSchema)}`;
+            return describeHelpValueToken(valueSchema, {
+                displayPath: field.optionPathDisplay,
+                optionFlag: field.optionFlag
+            });
         }
         if (valueSchema.kind === "object") {
             return "value";
         }
-        return describeSchemaType(valueSchema);
+        return describeHelpValueToken(valueSchema, {
+            displayPath: field.optionPathDisplay,
+            optionFlag: field.optionFlag
+        });
     }
     return "value";
 }
@@ -663,10 +748,10 @@ function collectDynamicObjectHelpRows(schema, casing, optionPrefix, displayPrefi
                         hasDefault: false,
                         defaultValue: undefined,
                         requiredWhenActive: false,
-                        schema: childSchema,
-                    },
+                        schema: childSchema
+                    }
                 })}>`,
-                description: appendHelpMetadata(description, metadata),
+                description: appendHelpMetadata(description, metadata)
             });
             continue;
         }
@@ -676,9 +761,14 @@ function collectDynamicObjectHelpRows(schema, casing, optionPrefix, displayPrefi
         }
         rows.push({
             flags: childSchema.kind === "boolean"
-                ? `${optionFlag} [value]`
-                : `${optionFlag} <${describeSchemaType(childSchema)}>`,
-            description: appendHelpMetadata(description, metadata),
+                ? childSchema.default === true
+                    ? `--no-${optionFlag.slice(2)}`
+                    : optionFlag
+                : `${optionFlag} <${describeHelpValueToken(childSchema, {
+                    displayPath,
+                    optionFlag
+                })}>`,
+            description: appendHelpMetadata(description, metadata)
         });
     }
     return rows;
@@ -697,15 +787,17 @@ function formatDynamicHelpFields(field, casing) {
             return collectDynamicObjectHelpRows(itemSchema, casing, `${field.optionFlag}`, `${field.optionPathDisplay}`, metadata);
         }
     }
-    return [{
+    return [
+        {
             flags: `${field.optionFlag} <${describeDynamicFieldType(field)}>`,
-            description: appendHelpMetadata(field.description ?? field.optionPathDisplay, metadata),
-        }];
+            description: appendHelpMetadata(field.description ?? field.optionPathDisplay, metadata)
+        }
+    ];
 }
 function formatSecretRows(secrets) {
     return Object.values(secrets).map((secret) => ({
         flags: secret.env,
-        description: formatSecretDescription(secret),
+        description: formatSecretDescription(secret)
     }));
 }
 function formatSecretDescription(secret) {
@@ -728,46 +820,39 @@ function formatCommandParameterTokens(command, casing, globalLongOptionFlags) {
         .map((field) => wrapOptionalCommandParameterToken(formatHelpFieldFlags(field, globalLongOptionFlags), field.positionalIndex === undefined && (field.optional || field.hasDefault)))
         .concat(collected.dynamicFields.flatMap((field) => formatCommandDynamicParameterTokens(field, casing)));
 }
-function formatCommandRowName(node, depth, casing, globalLongOptionFlags) {
+function formatCommandRowName(node, casing, globalLongOptionFlags) {
     const baseName = node.aliases.length === 0 ? node.name : `${node.name} (${node.aliases.join(", ")})`;
-    const parameterTokens = node.kind === "command" ? formatCommandParameterTokens(node, casing, globalLongOptionFlags) : [];
+    const parameterTokens = node.kind === "command"
+        ? formatCommandParameterTokens(node, casing, globalLongOptionFlags)
+        : [];
     const name = parameterTokens.length === 0 ? baseName : `${baseName} ${parameterTokens.join(" ")}`;
-    return `${"  ".repeat(depth)}${name}`;
+    return name;
 }
-function formatCommandRows(group, scope, casing, globalLongOptionFlags, depth = 0) {
-    return getVisibleChildren(group, scope).flatMap((child) => {
-        const row = {
-            name: formatCommandRowName(child, depth, casing, globalLongOptionFlags),
-            description: child.description ?? "",
-        };
-        if (child.kind === "command") {
-            return [row];
-        }
-        return [row, ...formatCommandRows(child, scope, casing, globalLongOptionFlags, depth + 1)];
-    });
+function formatCommandRows(group, scope, casing, globalLongOptionFlags) {
+    return getVisibleChildren(group, scope).map((child) => ({
+        name: formatCommandRowName(child, casing, globalLongOptionFlags),
+        description: child.description ?? ""
+    }));
 }
-function formatGlobalOptionRows(showVersion, presetsEnabled) {
+function formatGlobalOptionRows(ctx) {
     const rows = [];
-    if (presetsEnabled) {
+    if (ctx.presetsEnabled) {
         rows.push({
             flags: "--preset <path>",
-            description: "Load parameter defaults from a JSON file",
+            description: "Load parameter defaults from a JSON file"
         });
     }
     rows.push({
         flags: "--yes",
-        description: "Accept defaults, skip prompts",
+        description: "Accept defaults, skip prompts"
     }, {
         flags: "--output <format>",
-        description: "Output format (rich, md, json)",
-    }, {
-        flags: "-h, --help",
-        description: "Show help",
+        description: "Output format: rich, md, json."
     });
-    if (showVersion) {
+    if (ctx.showVersion) {
         rows.push({
             flags: "--version",
-            description: "Show version",
+            description: "Show version"
         });
     }
     return rows;
@@ -775,45 +860,58 @@ function formatGlobalOptionRows(showVersion, presetsEnabled) {
 function renderHelpSections(sections) {
     return sections.filter((section) => section.length > 0).join("\n\n");
 }
+function formatHelpCommandList(rows) {
+    return process.stdout.isTTY === false
+        ? helpFormatterPlain.formatCommandList(rows)
+        : formatCommandList(rows);
+}
+function formatHelpOptionList(rows) {
+    return process.stdout.isTTY === false
+        ? helpFormatterPlain.formatOptionList(rows)
+        : formatOptionList(rows);
+}
 function buildUsageLine(breadcrumb, rootUsageName, suffix) {
-    if (rootUsageName === undefined) {
-        return undefined;
-    }
-    const subPath = breadcrumb.slice(1).join(" ");
-    return subPath ? `${rootUsageName} ${subPath} ${suffix}` : `${rootUsageName} ${suffix}`;
+    const visibleBreadcrumb = breadcrumb.filter((segment) => segment.length > 0);
+    const usageBreadcrumb = breadcrumb[0] === "" ? [rootUsageName, ...visibleBreadcrumb] : visibleBreadcrumb;
+    const subPath = usageBreadcrumb.slice(1).join(" ");
+    const tokens = [rootUsageName, subPath, suffix].filter((segment) => segment.length > 0);
+    return tokens.join(" ");
 }
-function renderGroupHelp(group, breadcrumb, scope, casing, showVersion, presetsEnabled, rootUsageName) {
+function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUsageName) {
     const sections = [];
-    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled);
+    const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled);
     const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags);
     if (commandRows.length > 0) {
-        sections.push(`${text.section("Commands:")}\n${formatCommandList(commandRows)}`);
+        sections.push(`${text.sectionHeader("Commands")}\n${formatHelpCommandList(commandRows)}`);
     }
-    sections.push(`${text.section("Global options:")}\n${formatOptionList(formatGlobalOptionRows(showVersion, presetsEnabled))}`);
+    sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(formatGlobalOptionRows(globalOptions))}`);
     return renderHelpDocument({
         breadcrumb,
-        usageLine: buildUsageLine(breadcrumb, rootUsageName, "[options] [command]"),
+        rootUsageName,
+        usageLine: buildUsageLine(breadcrumb, rootUsageName, "[command] [options]"),
         description: group.description,
         requiresAuth: group.requires?.auth === true,
-        sections,
+        sections
     });
 }
-function renderLeafHelp(command, breadcrumb, casing, presetsEnabled, rootUsageName) {
+function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageName) {
     const sections = [];
-    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled);
+    const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled);
     const collected = collectFields(command.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, command.positional);
-    const optionRows = fields.map((field) => ({
+    const optionRows = fields
+        .map((field) => ({
         flags: formatHelpFieldFlags(field, globalLongOptionFlags),
-        description: formatHelpFieldDescription(field),
-    })).concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
+        description: formatHelpFieldDescription(field)
+    }))
+        .concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
     if (optionRows.length > 0) {
-        sections.push(`${text.section("Options:")}\n${formatOptionList(optionRows)}`);
+        sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(optionRows)}`);
     }
-    sections.push(`${text.section("Global options:")}\n${formatOptionList(formatGlobalOptionRows(false, presetsEnabled))}`);
+    sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(formatGlobalOptionRows(globalOptions))}`);
     const secretRows = formatSecretRows(command.secrets);
     if (secretRows.length > 0) {
-        sections.push(`${text.section("Secrets (via environment):")}\n${formatOptionList(secretRows)}`);
+        sections.push(`${text.sectionHeader("Secrets (environment)")}\n${formatHelpOptionList(secretRows)}`);
     }
     const positionalFields = fields.filter((f) => f.positionalIndex !== undefined);
     const usageSuffix = positionalFields.length > 0
@@ -821,24 +919,29 @@ function renderLeafHelp(command, breadcrumb, casing, presetsEnabled, rootUsageNa
         : "[options]";
     return renderHelpDocument({
         breadcrumb,
+        rootUsageName,
         usageLine: buildUsageLine(breadcrumb, rootUsageName, usageSuffix),
         description: command.description,
         requiresAuth: command.requires?.auth === true,
-        sections,
+        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);
-    }
+    const title = input.breadcrumb.filter((segment) => segment.length > 0).join(" ") || input.rootUsageName;
+    const description = input.description ?? "";
+    const sentenceEndIndex = description.indexOf(". ");
+    const headingDescription = sentenceEndIndex === -1 ? description : description.slice(0, sentenceEndIndex + 1);
+    const remainingDescription = sentenceEndIndex === -1 ? "" : description.slice(sentenceEndIndex + 2);
+    const heading = headingDescription.length > 0 ? `${title} — ${headingDescription}` : title;
+    const lines = [text.heading(heading), ""];
+    if (remainingDescription.length > 0) {
+        lines.push(remainingDescription, "");
+    }
+    lines.push(`Usage: ${text.usageCommand(input.usageLine)}`, "");
     if (input.requiresAuth) {
         lines.push("Requires: authentication");
     }
-    if (input.description !== undefined || input.requiresAuth) {
+    if (input.requiresAuth) {
         lines.push("");
     }
     lines.push(renderHelpSections(input.sections));
@@ -848,10 +951,17 @@ async function renderGeneratedHelp(root, argv, options) {
     const target = resolveHelpTarget(root, argv, "cli", options.rootDisplayName);
     const output = resolveHelpOutput(argv);
     const casing = options.casing ?? "kebab";
+    const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
     await withOutputFormat(output, async () => {
         const rendered = target.node.kind === "group"
-            ? renderGroupHelp(target.node, target.breadcrumb, "cli", casing, options.version !== undefined, options.presets === true, options.rootUsageName)
-            : renderLeafHelp(target.node, target.breadcrumb, casing, options.presets === true, options.rootUsageName);
+            ? renderGroupHelp(target.node, target.breadcrumb, "cli", casing, {
+                showVersion: options.version !== undefined,
+                presetsEnabled: options.presets === true
+            }, rootUsageName)
+            : renderLeafHelp(target.node, target.breadcrumb, casing, {
+                showVersion: options.version !== undefined,
+                presetsEnabled: options.presets === true
+            }, rootUsageName);
         process.stdout.write(rendered);
     });
 }
@@ -896,7 +1006,7 @@ function createNodeCommand(node, casing, globalLongOptionFlags, execute, presets
                 presetsEnabled,
                 rawArgv: actionCommand.args,
                 actionCommand,
-                variants: collected.variants,
+                variants: collected.variants
             });
         });
         return command;
@@ -973,12 +1083,12 @@ async function promptForField(field) {
             ? await schema.loadOptions()
             : schema.values.map((value) => ({
                 label: schema.labels?.[String(value)] ?? String(value),
-                value,
+                value
             }));
         const selected = await select({
             message: field.description ?? field.displayPath,
             options,
-            initialValue: field.hasDefault ? field.defaultValue : undefined,
+            initialValue: field.hasDefault ? field.defaultValue : undefined
         });
         if (isCancel(selected)) {
             cancel("Operation cancelled.");
@@ -989,7 +1099,7 @@ async function promptForField(field) {
     if (field.schema.kind === "boolean") {
         const selected = await confirm({
             message: field.displayPath,
-            initialValue: field.hasDefault ? Boolean(field.defaultValue) : undefined,
+            initialValue: field.hasDefault ? Boolean(field.defaultValue) : undefined
         });
         if (isCancel(selected)) {
             cancel("Operation cancelled.");
@@ -1001,7 +1111,7 @@ async function promptForField(field) {
         message: field.displayPath,
         initialValue: field.hasDefault && field.defaultValue !== undefined
             ? formatResolvedValue(field.defaultValue)
-            : undefined,
+            : undefined
     });
     if (isCancel(entered)) {
         cancel("Operation cancelled.");
@@ -1036,7 +1146,7 @@ function resolveOutput(resolvedFlags) {
 const DESIGN_SYSTEM_OUTPUT_BY_MODE = {
     rich: "terminal",
     md: "markdown",
-    json: "json",
+    json: "json"
 };
 function toDesignSystemOutput(output) {
     return DESIGN_SYSTEM_OUTPUT_BY_MODE[output];
@@ -1072,14 +1182,14 @@ function createFs() {
             catch {
                 return false;
             }
-        },
+        }
     };
 }
 function createEnv(values = process.env) {
     return {
         get(key) {
             return values[key];
-        },
+        }
     };
 }
 function isPlainObject(value) {
@@ -1157,19 +1267,14 @@ async function loadPresetValues(fields, presetPath) {
     let rawPreset;
     try {
         rawPreset = await readFile(presetPath, {
-            encoding: "utf8",
+            encoding: "utf8"
         });
     }
     catch (error) {
-        if (typeof error === "object" &&
-            error !== null &&
-            "code" in error &&
-            error.code === "ENOENT") {
+        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.";
+        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;
@@ -1282,13 +1387,13 @@ function createFixtureResponse(response) {
     if (response.body === undefined) {
         return new Response(null, {
             status,
-            headers,
+            headers
         });
     }
     if (typeof response.body === "string") {
         return new Response(response.body, {
             status,
-            headers,
+            headers
         });
     }
     if (!headers.has("content-type")) {
@@ -1296,7 +1401,7 @@ function createFixtureResponse(response) {
     }
     return new Response(JSON.stringify(response.body), {
         status,
-        headers,
+        headers
     });
 }
 function createFixtureFetch(entries) {
@@ -1314,7 +1419,7 @@ function createFixtureFetch(entries) {
             return null;
         }
         return new Response(null, {
-            status: 204,
+            status: 204
         });
     };
 }
@@ -1335,7 +1440,7 @@ function createFixtureFs(definition) {
                 return Boolean(existsEntries[filePath]);
             }
             return Object.prototype.hasOwnProperty.call(readFileEntries, filePath);
-        },
+        }
     };
 }
 function resolveFixtureMethodResult(methodName, definition, args) {
@@ -1379,7 +1484,8 @@ function resolveFixtureMethodResult(methodName, definition, args) {
     }
     if (isPlainObject(definition)) {
         const firstArg = args[0];
-        if (typeof firstArg === "string" && Object.prototype.hasOwnProperty.call(definition, firstArg)) {
+        if (typeof firstArg === "string" &&
+            Object.prototype.hasOwnProperty.call(definition, firstArg)) {
             return Promise.resolve(definition[firstArg]);
         }
     }
@@ -1397,7 +1503,7 @@ function createFixtureService(definition) {
             }
             const methodName = String(property);
             return async (...args) => resolveFixtureMethodResult(methodName, methods[methodName], args);
-        },
+        }
     });
 }
 function resolveFixturePath(commandPath) {
@@ -1428,7 +1534,7 @@ async function loadFixtureScenario(command, selector) {
     let rawFixture;
     try {
         rawFixture = await readFile(fixturePath, {
-            encoding: "utf8",
+            encoding: "utf8"
         });
     }
     catch {
@@ -1452,7 +1558,7 @@ function resolveFixtureSecrets(command) {
 function createFixtureEnvValues(command) {
     const values = {
         ...process.env,
-        POE_API_KEY: process.env.POE_API_KEY ?? "fixture-secret",
+        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";
@@ -1469,14 +1575,14 @@ async function resolveFixtureRuntime(command, services, requirementOptions) {
             isFixture: false,
             requirementOptions,
             secrets: resolveCommandSecrets(command),
-            services,
+            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)),
+        ...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);
@@ -1487,10 +1593,10 @@ async function resolveFixtureRuntime(command, services, requirementOptions) {
         isFixture: true,
         requirementOptions: {
             ...requirementOptions,
-            env: fixtureEnvValues,
+            env: fixtureEnvValues
         },
         secrets: resolveFixtureSecrets(command),
-        services: fixtureServices,
+        services: fixtureServices
     };
 }
 function writeRichHeader(title) {
@@ -1544,25 +1650,25 @@ function consumeFieldValue(args, index, schema, label, inlineValue) {
         if (inlineValue !== undefined) {
             return {
                 nextIndex: index,
-                value: parseScalarValue(inlineValue, schema, label),
+                value: parseScalarValue(inlineValue, schema, label)
             };
         }
         const next = args[index + 1];
         if (next === "true" || next === "false" || (schema.nullable === true && next === "null")) {
             return {
                 nextIndex: index + 1,
-                value: parseScalarValue(next, schema, label),
+                value: parseScalarValue(next, schema, label)
             };
         }
         return {
             nextIndex: index,
-            value: true,
+            value: true
         };
     }
     if (inlineValue !== undefined) {
         return {
             nextIndex: index,
-            value: parseFieldInputValue(inlineValue, schema, label),
+            value: parseFieldInputValue(inlineValue, schema, label)
         };
     }
     if (schema.kind === "array") {
@@ -1578,7 +1684,7 @@ function consumeFieldValue(args, index, schema, label, inlineValue) {
             if (parsed === null) {
                 return {
                     nextIndex: cursor,
-                    value: null,
+                    value: null
                 };
             }
             values.push(...parsed);
@@ -1590,7 +1696,7 @@ function consumeFieldValue(args, index, schema, label, inlineValue) {
         }
         return {
             nextIndex,
-            value: values,
+            value: values
         };
     }
     const next = args[index + 1];
@@ -1599,7 +1705,7 @@ function consumeFieldValue(args, index, schema, label, inlineValue) {
     }
     return {
         nextIndex: index + 1,
-        value: parseFieldInputValue(next, schema, label),
+        value: parseFieldInputValue(next, schema, label)
     };
 }
 function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displayPath = []) {
@@ -1614,7 +1720,7 @@ function resolveDynamicLeaf(schema, rawSegments, casing, outputPath = [], displa
             return {
                 displayPath: toDisplayPath(displayPath),
                 path: outputPath,
-                schema: unwrappedSchema,
+                schema: unwrappedSchema
             };
         }
         throw new UserError(`Unsupported dynamic CLI schema kind "${unwrappedSchema.kind}".`);
@@ -1713,7 +1819,7 @@ function finalizeDynamicValue(schema, value, displayPath) {
             }
             return Object.fromEntries(Object.entries(value).map(([key, entryValue]) => [
                 key,
-                finalizeDynamicValue(unwrappedSchema.value, entryValue, displayPath.length === 0 ? key : `${displayPath}.${key}`),
+                finalizeDynamicValue(unwrappedSchema.value, entryValue, displayPath.length === 0 ? key : `${displayPath}.${key}`)
             ]));
         }
         default:
@@ -1751,7 +1857,7 @@ function parseDynamicValues(dynamicFields, rawArgv, casing) {
         const parsed = negated && leaf.schema.kind === "boolean"
             ? {
                 nextIndex: index,
-                value: false,
+                value: false
             }
             : consumeFieldValue(rawArgv, index, leaf.schema, label, inlineValue);
         setNestedValue(rawStore, leaf.path, parsed.value);
@@ -1765,8 +1871,8 @@ function parseDynamicValues(dynamicFields, rawArgv, casing) {
             .filter((field) => rawValues.has(field.id))
             .map((field) => [
             field.id,
-            finalizeDynamicValue(field.schema.kind === "record" ? field.schema : field.schema, rawValues.get(field.id), field.displayPath),
-        ])),
+            finalizeDynamicValue(field.schema.kind === "record" ? field.schema : field.schema, rawValues.get(field.id), field.displayPath)
+        ]))
     };
 }
 async function enforceVariantConstraints(params, fields, dynamicFields, variants, resolvedFieldValues, providedDynamicFieldIds, providedFieldIds, shouldPrompt) {
@@ -1913,7 +2019,7 @@ async function resolveParams(fields, dynamicFields, variants, positionalValues,
         ? parseDynamicValues(dynamicFields, rawArgv, casing)
         : {
             providedFieldIds: new Set(),
-            values: new Map(),
+            values: new Map()
         };
     for (const field of dynamicFields) {
         let value = dynamicResults.values.get(field.id);
@@ -1941,7 +2047,7 @@ async function executeCommand(state, services, requirementOptions, runtimeOption
         logger,
         renderTable,
         getTheme,
-        note,
+        note
     };
     const optionValues = state.actionCommand.optsWithGlobals();
     const resolvedFlags = optionValues;
@@ -1956,16 +2062,19 @@ async function executeCommand(state, services, requirementOptions, runtimeOption
         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.dynamicFields, state.variants, state.positionalValues, optionValues, state.rawArgv, state.casing, state.presetsEnabled ? resolvedFlags.preset : undefined, shouldPrompt);
         const context = {
             ...preflightContext,
-            params,
+            params
         };
-        if (state.command.confirm && !state.command.humanInLoop && !resolvedFlags.yes && process.stdin.isTTY) {
+        if (state.command.confirm &&
+            !state.command.humanInLoop &&
+            !resolvedFlags.yes &&
+            process.stdin.isTTY) {
             for (const field of state.fields) {
                 const value = field.path.reduce((current, segment) => current && typeof current === "object"
                     ? current[segment]
@@ -1976,7 +2085,7 @@ async function executeCommand(state, services, requirementOptions, runtimeOption
             }
             const proceed = await confirm({
                 message: "Proceed?",
-                initialValue: true,
+                initialValue: true
             });
             if (isCancel(proceed)) {
                 cancel("Operation cancelled.");
@@ -1994,7 +2103,10 @@ async function executeCommand(state, services, requirementOptions, runtimeOption
             renderHumanInLoopPending(result);
             return;
         }
-        renderResult(state.command, result, output, primitives);
+        const renderStatus = renderResult(state.command, result, output, primitives);
+        if (renderStatus.mcpError) {
+            process.exitCode = 1;
+        }
     });
 }
 function handleRunError(error, verbose) {
@@ -2028,10 +2140,10 @@ export async function runCLI(roots, options = {}) {
     const servicesWithBuiltIns = {
         ...services,
         runtimeOptions,
-        root,
+        root
     };
     const requirementOptions = {
-        apiVersion: options.apiVersion,
+        apiVersion: options.apiVersion
     };
     validateServices(services);
     if (hasHelpFlag(process.argv)) {
@@ -2072,6 +2184,8 @@ export async function runCLI(roots, options = {}) {
             renderApprovalDeclined(error);
             return;
         }
-        handleRunError(error, lastActionCommand ? Boolean(getResolvedFlags(lastActionCommand).verbose) : process.argv.includes("--verbose"));
+        handleRunError(error, lastActionCommand
+            ? Boolean(getResolvedFlags(lastActionCommand).verbose)
+            : process.argv.includes("--verbose"));
     }
 }