toolcraft 0.0.14 → 0.0.15

package/README.md

@@ -387,7 +387,7 @@ export function slackApprovalProvider(opts: {
 
 ## Errors
 
-Throw `UserError` for expected, user-facing failures. The CLI prints the message without a stack trace and sets exit code 1; MCP and SDK surface the message as the error body. Any other thrown error is treated as unexpected and shows a stack with `--verbose`.
+Throw `UserError` for expected, user-facing failures. The CLI prints the message without a stack trace and sets exit code 1; MCP and SDK surface the message as the error body. Any other thrown error is treated as unexpected and shows a stack with `--debug`.
 
 ## Migrating from a folder of scripts
 

package/dist/cli.js

@@ -300,6 +300,7 @@ function collectFields(schema, casing, globalLongOptionFlags, path = [], inherit
             hasDefault: childSchema.default !== undefined,
             defaultValue: childSchema.default,
             requiredWhenActive,
+            global: childSchema.global === true ? true : undefined,
             variantId: variantContext?.id,
             variantBranchId: variantContext?.branchId
         });
@@ -494,7 +495,7 @@ function createOption(field, globalLongOptionFlags) {
     option.argParser((value) => commanderValue(parseScalarValue(value, field.schema, field.displayPath)));
     return [option];
 }
-const ALWAYS_GLOBAL_LONG_OPTION_FLAGS = ["--yes", "--output", "--verbose"];
+const ALWAYS_GLOBAL_LONG_OPTION_FLAGS = ["--yes", "--output", "--debug"];
 function getGlobalLongOptionFlags(presetsEnabled) {
     return new Set(presetsEnabled
         ? ["--preset", ...ALWAYS_GLOBAL_LONG_OPTION_FLAGS]
@@ -817,6 +818,7 @@ function formatCommandParameterTokens(command, casing, globalLongOptionFlags) {
     const collected = collectFields(command.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, command.positional);
     return fields
+        .filter((field) => field.global !== true)
         .map((field) => wrapOptionalCommandParameterToken(formatHelpFieldFlags(field, globalLongOptionFlags), field.positionalIndex === undefined && (field.optional || field.hasDefault)))
         .concat(collected.dynamicFields.flatMap((field) => formatCommandDynamicParameterTokens(field, casing)));
 }
@@ -848,6 +850,9 @@ function formatGlobalOptionRows(ctx) {
     }, {
         flags: "--output <format>",
         description: "Output format: rich, md, json."
+    }, {
+        flags: "--debug",
+        description: "Print stack traces for unexpected errors."
     });
     if (ctx.showVersion) {
         rows.push({
@@ -857,6 +862,33 @@ function formatGlobalOptionRows(ctx) {
     }
     return rows;
 }
+function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags) {
+    const seen = new Map();
+    const visit = (node) => {
+        if (node.kind === "command") {
+            const collected = collectFields(node.params, casing, globalLongOptionFlags);
+            for (const field of collected.fields) {
+                if (field.global !== true) {
+                    continue;
+                }
+                const dedupeKey = `${field.optionFlag}|${field.shortFlag ?? ""}`;
+                if (seen.has(dedupeKey)) {
+                    continue;
+                }
+                seen.set(dedupeKey, {
+                    flags: formatHelpFieldFlags(field, globalLongOptionFlags),
+                    description: formatHelpFieldDescription(field)
+                });
+            }
+            return;
+        }
+        for (const child of getVisibleChildren(node, scope)) {
+            visit(child);
+        }
+    };
+    visit(group);
+    return [...seen.values()];
+}
 function renderHelpSections(sections) {
     return sections.filter((section) => section.length > 0).join("\n\n");
 }
@@ -877,18 +909,24 @@ function buildUsageLine(breadcrumb, rootUsageName, suffix) {
     const tokens = [rootUsageName, subPath, suffix].filter((segment) => segment.length > 0);
     return tokens.join(" ");
 }
-function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUsageName) {
+function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUsageName, isRoot) {
     const sections = [];
     const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled);
     const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags);
     if (commandRows.length > 0) {
         sections.push(`${text.sectionHeader("Commands")}\n${formatHelpCommandList(commandRows)}`);
     }
-    sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(formatGlobalOptionRows(globalOptions))}`);
+    if (isRoot) {
+        const globalRows = [
+            ...formatGlobalOptionRows(globalOptions),
+            ...collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlags)
+        ];
+        sections.push(`${text.sectionHeader("Global options")}\n${formatHelpOptionList(globalRows)}`);
+    }
     return renderHelpDocument({
         breadcrumb,
         rootUsageName,
-        usageLine: buildUsageLine(breadcrumb, rootUsageName, "[command] [options]"),
+        usageLine: buildUsageLine(breadcrumb, rootUsageName, "[command] [OPTIONS]"),
         description: group.description,
         requiresAuth: group.requires?.auth === true,
         sections
@@ -900,6 +938,7 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     const collected = collectFields(command.params, casing, globalLongOptionFlags);
     const fields = assignPositionals(collected.fields, command.positional);
     const optionRows = fields
+        .filter((field) => field.global !== true)
         .map((field) => ({
         flags: formatHelpFieldFlags(field, globalLongOptionFlags),
         description: formatHelpFieldDescription(field)
@@ -908,15 +947,14 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     if (optionRows.length > 0) {
         sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(optionRows)}`);
     }
-    sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(formatGlobalOptionRows(globalOptions))}`);
     const secretRows = formatSecretRows(command.secrets);
     if (secretRows.length > 0) {
         sections.push(`${text.sectionHeader("Secrets (environment)")}\n${formatHelpOptionList(secretRows)}`);
     }
     const positionalFields = fields.filter((f) => f.positionalIndex !== undefined);
     const usageSuffix = positionalFields.length > 0
-        ? `[options] ${positionalFields.map(formatPositionalToken).join(" ")}`
-        : "[options]";
+        ? `[OPTIONS] ${positionalFields.map(formatPositionalToken).join(" ")}`
+        : "[OPTIONS]";
     return renderHelpDocument({
         breadcrumb,
         rootUsageName,
@@ -957,7 +995,7 @@ async function renderGeneratedHelp(root, argv, options) {
             ? renderGroupHelp(target.node, target.breadcrumb, "cli", casing, {
                 showVersion: options.version !== undefined,
                 presetsEnabled: options.presets === true
-            }, rootUsageName)
+            }, rootUsageName, target.node === root)
             : renderLeafHelp(target.node, target.breadcrumb, casing, {
                 showVersion: options.version !== undefined,
                 presetsEnabled: options.presets === true
@@ -1047,7 +1085,7 @@ function addGlobalOptions(command, presetsEnabled) {
         }
         throw new InvalidArgumentError('Invalid value for "--output". Expected one of: rich, md, markdown, json.');
     })
-        .option("--verbose", "Print stack traces for unexpected errors.");
+        .option("--debug", "Print stack traces for unexpected errors.");
 }
 function setNestedValue(target, path, value) {
     let cursor = target;
@@ -2109,7 +2147,7 @@ async function executeCommand(state, services, requirementOptions, runtimeOption
         }
     });
 }
-function handleRunError(error, verbose) {
+function handleRunError(error, debug) {
     const logger = createLogger();
     if (error instanceof UserError) {
         logger.error(error.message);
@@ -2124,8 +2162,8 @@ function handleRunError(error, verbose) {
         return;
     }
     const message = error instanceof Error ? error.message : String(error);
-    logger.error(verbose ? message : `${message} Use --verbose for a stack trace.`);
-    if (verbose && error instanceof Error && error.stack) {
+    logger.error(debug ? message : `${message} Use --debug for a stack trace.`);
+    if (debug && error instanceof Error && error.stack) {
         process.stderr.write(`${error.stack}\n`);
     }
     process.exitCode = 1;
@@ -2185,7 +2223,7 @@ export async function runCLI(roots, options = {}) {
             return;
         }
         handleRunError(error, lastActionCommand
-            ? Boolean(getResolvedFlags(lastActionCommand).verbose)
-            : process.argv.includes("--verbose"));
+            ? Boolean(getResolvedFlags(lastActionCommand).debug)
+            : process.argv.includes("--debug"));
     }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.14",
+  "version": "0.0.15",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -49,7 +49,7 @@
     "mustache": "^4.2.0",
     "smol-toml": "^1.3.0",
     "tiny-stdio-mcp-server": "^0.1.0",
-    "toolcraft-schema": "^0.0.14",
+    "toolcraft-schema": "^0.0.15",
     "yaml": "^2.8.2"
   },
   "files": [