toolcraft 0.0.60 → 0.0.61

package/dist/api-error-summary.d.ts

@@ -0,0 +1,53 @@
+export interface HttpErrorLike {
+    name: string;
+    message: string;
+    request: {
+        method: string;
+        url: string;
+        headers: Record<string, string>;
+        body?: unknown;
+    };
+    response: {
+        status: number;
+        statusText: string;
+        headers: Record<string, string>;
+        body: unknown;
+    };
+}
+export interface ApiErrorSummary {
+    status: number;
+    statusText: string;
+    requestMethod: string;
+    requestUrl: string;
+    requestId?: string;
+    code?: string;
+    message?: string;
+    fieldErrors?: Array<{
+        path: string;
+        message: string;
+    }>;
+    retryAfter?: string;
+    hint?: string;
+}
+export interface ToolcraftErrorEnvelope {
+    kind: "http";
+    message: string;
+    code?: string;
+    requestId?: string;
+    http: {
+        method: string;
+        url: string;
+        status: number;
+        statusText: string;
+    };
+    fieldErrors?: Array<{
+        path: string;
+        message: string;
+    }>;
+    retryAfter?: string;
+    hint?: string;
+    reportPath?: string;
+}
+export declare function isHttpErrorLike(error: unknown): error is HttpErrorLike;
+export declare function summarizeHttpError(error: HttpErrorLike): ApiErrorSummary;
+export declare function createHttpErrorEnvelope(error: HttpErrorLike, reportPath?: string): ToolcraftErrorEnvelope;

package/dist/api-error-summary.js

@@ -0,0 +1,162 @@
+import { redactHttpBody } from "./redaction.js";
+const REQUEST_ID_FIELDS = ["request_id", "requestId", "id"];
+const CODE_FIELDS = ["code", "error_code", "errorCode", "error"];
+const MESSAGE_FIELDS = ["message", "detail", "title", "error_description"];
+export function isHttpErrorLike(error) {
+    if (!isPlainObject(error)) {
+        return false;
+    }
+    if (typeof error.name !== "string" || typeof error.message !== "string") {
+        return false;
+    }
+    const request = error.request;
+    const response = error.response;
+    return (isPlainObject(request) &&
+        typeof request.method === "string" &&
+        typeof request.url === "string" &&
+        isStringRecord(request.headers) &&
+        isPlainObject(response) &&
+        typeof response.status === "number" &&
+        typeof response.statusText === "string" &&
+        isStringRecord(response.headers) &&
+        hasOwnProperty(response, "body"));
+}
+export function summarizeHttpError(error) {
+    const body = redactHttpBody(error.response.body);
+    const retryAfter = getHeader(error.response.headers, "retry-after");
+    const message = extractMessage(body);
+    const summary = {
+        status: error.response.status,
+        statusText: error.response.statusText,
+        requestMethod: error.request.method,
+        requestUrl: error.request.url,
+        ...(message === undefined ? {} : { message }),
+        ...optionalString("requestId", getHeader(error.response.headers, "x-request-id") ?? extractFirstString(body, REQUEST_ID_FIELDS)),
+        ...optionalString("code", extractCode(body)),
+        ...optionalString("retryAfter", retryAfter),
+        ...optionalArray("fieldErrors", extractFieldErrors(body)),
+        ...optionalString("hint", createHttpErrorHint(error.response.status, retryAfter))
+    };
+    return summary;
+}
+export function createHttpErrorEnvelope(error, reportPath) {
+    const summary = summarizeHttpError(error);
+    return {
+        kind: "http",
+        message: summary.message ?? error.message,
+        ...(summary.code === undefined ? {} : { code: summary.code }),
+        ...(summary.requestId === undefined ? {} : { requestId: summary.requestId }),
+        http: {
+            method: summary.requestMethod,
+            url: summary.requestUrl,
+            status: summary.status,
+            statusText: summary.statusText
+        },
+        ...(summary.fieldErrors === undefined ? {} : { fieldErrors: summary.fieldErrors }),
+        ...(summary.retryAfter === undefined ? {} : { retryAfter: summary.retryAfter }),
+        ...(summary.hint === undefined ? {} : { hint: summary.hint }),
+        ...(reportPath === undefined ? {} : { reportPath })
+    };
+}
+function createHttpErrorHint(status, retryAfter) {
+    if (status === 401 || status === 403) {
+        return "Check the configured API credentials and permissions.";
+    }
+    if ((status === 429 || status === 503) && retryAfter !== undefined) {
+        return `Retry after ${retryAfter}.`;
+    }
+    return undefined;
+}
+function extractMessage(body) {
+    if (!isPlainObject(body)) {
+        return undefined;
+    }
+    const graphqlMessage = extractGraphQlMessage(body);
+    if (graphqlMessage !== undefined) {
+        return graphqlMessage;
+    }
+    return extractFirstString(body, MESSAGE_FIELDS);
+}
+function extractCode(body) {
+    if (!isPlainObject(body)) {
+        return undefined;
+    }
+    const graphqlCode = extractGraphQlCode(body);
+    if (graphqlCode !== undefined) {
+        return graphqlCode;
+    }
+    return extractFirstString(body, CODE_FIELDS);
+}
+function extractGraphQlMessage(body) {
+    const [first] = Array.isArray(body.errors) ? body.errors : [];
+    return isPlainObject(first) && typeof first.message === "string" ? first.message : undefined;
+}
+function extractGraphQlCode(body) {
+    const [first] = Array.isArray(body.errors) ? body.errors : [];
+    if (!isPlainObject(first) || !isPlainObject(first.extensions)) {
+        return undefined;
+    }
+    return typeof first.extensions.code === "string" ? first.extensions.code : undefined;
+}
+function extractFieldErrors(body) {
+    if (!isPlainObject(body)) {
+        return undefined;
+    }
+    const candidates = [body.field_errors, body.fieldErrors, body.errors, body.non_field_errors];
+    const flattened = candidates.flatMap((candidate) => flattenFieldErrors(candidate, []));
+    return flattened.length === 0 ? undefined : flattened;
+}
+function flattenFieldErrors(value, path) {
+    if (typeof value === "string") {
+        return [{ path: formatPath(path), message: value }];
+    }
+    if (Array.isArray(value)) {
+        if (value.every((entry) => typeof entry === "string")) {
+            return value.map((message) => ({ path: formatPath(path), message }));
+        }
+        return value.flatMap((entry, index) => flattenFieldErrors(entry, [...path, String(index)]));
+    }
+    if (!isPlainObject(value)) {
+        return [];
+    }
+    return Object.entries(value).flatMap(([key, nested]) => flattenFieldErrors(nested, [...path, key]));
+}
+function formatPath(path) {
+    return path.length === 0 ? "error" : path.join(".");
+}
+function extractFirstString(body, fields) {
+    if (!isPlainObject(body)) {
+        return undefined;
+    }
+    for (const field of fields) {
+        const value = body[field];
+        if (typeof value === "string" && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function getHeader(headers, name) {
+    const lowerName = name.toLowerCase();
+    for (const [key, value] of Object.entries(headers)) {
+        if (key.toLowerCase() === lowerName && value.length > 0) {
+            return value;
+        }
+    }
+    return undefined;
+}
+function optionalString(name, value) {
+    return value === undefined ? {} : { [name]: value };
+}
+function optionalArray(name, value) {
+    return value === undefined ? {} : { [name]: value };
+}
+function isStringRecord(value) {
+    return isPlainObject(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function hasOwnProperty(value, name) {
+    return Object.prototype.hasOwnProperty.call(value, name);
+}

package/dist/cli.js

@@ -4,6 +4,7 @@ import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Opti
 import { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
 import { ApprovalDeclinedError, UserError, assertCommandRequirements, getCommandSourcePath, resolveCommandSecrets } from "./index.js";
 import { hasOwnErrorCode } from "./error-codes.js";
+import { summarizeHttpError } from "./api-error-summary.js";
 import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
 import { writeErrorReport } from "./error-report.js";
 import { invokeWithHumanInLoop } from "./human-in-loop/index.js";
@@ -746,7 +747,7 @@ function getHelpChildren(group, scope) {
 function findVisibleChild(group, token, scope) {
     return getVisibleChildren(group, scope).find((child) => child.name === token || child.aliases.includes(token));
 }
-function resolveHelpTarget(root, argv, scope, rootDisplayName) {
+function resolveHelpTarget(root, argv, scope, rootUsageName, rootDisplayName) {
     const breadcrumb = [rootDisplayName ?? root.name];
     let current = root;
     for (const token of argv.slice(2)) {
@@ -758,7 +759,7 @@ function resolveHelpTarget(root, argv, scope, rootDisplayName) {
         }
         const child = findVisibleChild(current, token, scope);
         if (child === undefined) {
-            break;
+            throw new UserError(formatUnknownHelpCommandMessage(current, token, scope, rootUsageName, breadcrumb));
         }
         breadcrumb.push(child.name);
         current = child;
@@ -768,6 +769,12 @@ function resolveHelpTarget(root, argv, scope, rootDisplayName) {
         node: current
     };
 }
+function formatUnknownHelpCommandMessage(group, input, scope, rootUsageName, breadcrumb) {
+    const suggestions = suggest(input, getHelpChildren(group, scope).map((child) => child.name));
+    const commandPath = breadcrumb.slice(1).join(" ");
+    const helpTarget = commandPath.length === 0 ? rootUsageName : `${rootUsageName} ${commandPath}`;
+    return `${formatSuggestionMessage(`Unknown command "${input}".`, suggestions)}\nRun ${helpTarget} --help for usage.`;
+}
 function formatHelpFieldFlags(field, globalLongOptionFlags) {
     if (field.positionalIndex !== undefined) {
         return formatPositionalToken(field);
@@ -1213,6 +1220,79 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
         sections
     });
 }
+function renderJsonHelp(target, root, casing, globalOptions, rootUsageName) {
+    const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion, globalOptions.controls);
+    const node = target.node;
+    if (node.kind === "group") {
+        const commandRows = formatCommandRows(node, "cli", casing, globalLongOptionFlags);
+        const isRoot = node === root;
+        return `${JSON.stringify({
+            schemaVersion: 1,
+            kind: "group",
+            name: target.breadcrumb.at(-1) ?? rootUsageName,
+            path: target.breadcrumb.filter((segment) => segment.length > 0),
+            usage: buildUsageLine(target.breadcrumb, rootUsageName, formatGroupUsageSuffix(node, "cli", casing, globalLongOptionFlags)),
+            ...(node.description === undefined ? {} : { description: node.description }),
+            commands: commandRows.map((row) => ({ name: row.name, description: row.description })),
+            options: isRoot
+                ? collectSchemaGlobalFieldRows(node, "cli", casing, globalLongOptionFlags).map((row) => ({
+                    name: row.flags.split(/[ ,]+/)[0]?.replace(/^--/, "") ?? row.flags,
+                    flags: row.flags.split(", "),
+                    type: "unknown",
+                    description: row.description,
+                    required: false
+                }))
+                : []
+        }, null, 2)}\n`;
+    }
+    const collected = collectFields(node.params, casing, globalLongOptionFlags);
+    const fields = assignPositionals(collected.fields, node.positional);
+    const positionalFields = fields.filter((field) => field.positionalIndex !== undefined);
+    const usageSuffix = positionalFields.length > 0
+        ? `[OPTIONS] ${positionalFields.map(formatPositionalToken).join(" ")}`
+        : "[OPTIONS]";
+    return `${JSON.stringify({
+        schemaVersion: 1,
+        kind: "command",
+        name: node.name,
+        path: target.breadcrumb.filter((segment) => segment.length > 0),
+        usage: buildUsageLine(target.breadcrumb, rootUsageName, usageSuffix),
+        ...(node.description === undefined ? {} : { description: node.description }),
+        options: fields
+            .filter((field) => field.global !== true)
+            .map((field) => formatJsonHelpOption(field, globalLongOptionFlags)),
+        secrets: Object.entries(node.secrets).map(([name, secret]) => ({
+            name,
+            env: secret.env,
+            required: secret.optional !== true,
+            ...(secret.description === undefined ? {} : { description: secret.description })
+        })),
+        examples: node.examples
+    }, null, 2)}\n`;
+}
+function formatJsonHelpOption(field, globalLongOptionFlags) {
+    return {
+        name: field.displayPath,
+        flags: formatHelpFieldFlags(field, globalLongOptionFlags).split(", "),
+        type: formatJsonHelpSchemaType(field.schema),
+        ...(field.description === undefined ? {} : { description: field.description }),
+        required: field.requiredWhenActive,
+        ...(field.hasDefault ? { default: field.defaultValue } : {}),
+        ...(field.positionalIndex === undefined ? {} : { positional: true })
+    };
+}
+function formatJsonHelpSchemaType(schema) {
+    if (schema.kind === "enum") {
+        return "enum";
+    }
+    if (schema.kind === "array") {
+        return "array";
+    }
+    if (schema.kind === "json") {
+        return "json";
+    }
+    return schema.kind;
+}
 function renderHelpDocument(input) {
     const title = input.breadcrumb.filter((segment) => segment.length > 0).join(" ") || input.rootUsageName;
     const description = input.description ?? "";
@@ -1235,11 +1315,19 @@ function renderHelpDocument(input) {
     return `${lines.join("\n").trimEnd()}\n`;
 }
 async function renderGeneratedHelp(root, argv, options) {
-    const target = resolveHelpTarget(root, argv, "cli", options.rootDisplayName);
     const output = resolveHelpOutput(argv);
     const casing = options.casing ?? "kebab";
     const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
+    const target = resolveHelpTarget(root, argv, "cli", rootUsageName, options.rootDisplayName);
     const controls = resolveCLIControls(options.controls);
+    if (output === "json") {
+        process.stdout.write(renderJsonHelp(target, root, casing, {
+            controls,
+            showVersion: options.version !== undefined,
+            presetsEnabled: options.presets === true
+        }, rootUsageName));
+        return;
+    }
     await withOutputFormat(output, async () => {
         const rendered = target.node.kind === "group"
             ? renderGroupHelp(target.node, target.breadcrumb, "cli", casing, {
@@ -2082,6 +2170,16 @@ function renderCliErrorPattern(pattern) {
         process.exitCode = 1;
         return;
     }
+    if (pattern.kind === "definition") {
+        logger.error(`Command definition error: ${pattern.error.message}\n` +
+            "This is a bug in the generated command definition, not in your command arguments.\n" +
+            "Run with --debug for a stack trace.");
+        if (pattern.debugStackMode !== undefined && pattern.error.stack) {
+            process.stderr.write(`${formatDebugStack(pattern.error.stack, pattern.debugStackMode)}\n`);
+        }
+        process.exitCode = 1;
+        return;
+    }
     if (pattern.kind === "toolcraft-bug") {
         logger.error(`toolcraft hit an internal invariant: ${pattern.error.message}\n` +
             `This is a bug in toolcraft or in the command definition; ` +
@@ -2755,7 +2853,7 @@ function isHttpErrorLike(error) {
     if (!isPlainObject(error)) {
         return false;
     }
-    if (error.name !== "HttpError" || typeof error.message !== "string") {
+    if (typeof error.name !== "string" || typeof error.message !== "string") {
         return false;
     }
     const request = error.request;
@@ -2902,6 +3000,7 @@ function formatHttpErrorSnippet(body) {
 }
 function renderHttpError(error, options) {
     const detailed = options.verbose || options.debugStackMode !== undefined;
+    const summary = summarizeHttpError(error);
     const lines = [
         styleHttpErrorLine(`Request:  ${error.request.method} ${error.request.url}`, text.muted)
     ];
@@ -2916,7 +3015,24 @@ function renderHttpError(error, options) {
         lines.push("", "Response headers:", ...formatHttpErrorHeaders(error.response.headers), "", "Response body:", indentHttpErrorBlock(formatHttpErrorBody(error.response.body)));
     }
     else {
-        lines.push("", `Response body: ${formatHttpErrorSnippet(error.response.body)}`, "Re-run with --verbose to see headers and full body.");
+        const summaryLines = [
+            summary.code === undefined ? undefined : `Code:     ${summary.code}`,
+            summary.message === undefined ? undefined : `Message:  ${summary.message}`,
+            summary.requestId === undefined ? undefined : `Request id: ${summary.requestId}`,
+            summary.retryAfter === undefined ? undefined : `Retry after: ${summary.retryAfter}`,
+            summary.hint === undefined ? undefined : `Hint:     ${summary.hint}`
+        ].filter((line) => line !== undefined);
+        if (summary.fieldErrors !== undefined && summary.fieldErrors.length > 0) {
+            summaryLines.push("", "Field errors:", ...summary.fieldErrors.map((fieldError) => `  ${fieldError.path}: ${fieldError.message}`));
+        }
+        lines.push("");
+        if (summaryLines.length > 0) {
+            lines.push(...summaryLines);
+        }
+        else {
+            lines.push(`Response body: ${formatHttpErrorSnippet(error.response.body)}`);
+        }
+        lines.push("Re-run with --verbose to see headers and full body.");
     }
     process.stderr.write(`${lines.join("\n")}\n`);
     const stack = error instanceof Error ? error.stack : undefined;
@@ -2928,17 +3044,23 @@ async function handleRunError(error, options) {
     const logger = createLogger();
     await withOutputFormat(options.output, async () => {
         if (error instanceof UserError) {
-            renderCliErrorPattern(options.userErrorPattern === "usage"
+            renderCliErrorPattern(options.userErrorPattern === "definition"
                 ? {
-                    kind: "usage",
-                    message: error.message,
-                    rootUsageName: options.rootUsageName,
-                    commandPath: options.commandPath
+                    kind: "definition",
+                    error,
+                    debugStackMode: options.debugStackMode
                 }
-                : {
-                    kind: "runtime-user",
-                    message: error.message
-                });
+                : options.userErrorPattern === "usage"
+                    ? {
+                        kind: "usage",
+                        message: error.message,
+                        rootUsageName: options.rootUsageName,
+                        commandPath: options.commandPath
+                    }
+                    : {
+                        kind: "runtime-user",
+                        message: error.message
+                    });
             return;
         }
         if (error instanceof Error && error.name === "ToolcraftBugError") {
@@ -3190,77 +3312,82 @@ function configureCommanderSuggestionOutput(command) {
 export async function runCLI(roots, options = {}) {
     enableSourceMaps();
     const argv = [...(options.argv ?? process.argv)];
-    const normalizedRoot = normalizeRoots(roots, argv);
-    const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
-    await resolveMcpProxies(root, { projectRoot: options.projectRoot });
-    const casing = options.casing ?? "kebab";
-    const services = (options.services ?? {});
-    const runtimeOptions = options.humanInLoop ?? {};
-    const runtimeFetch = options.fetch ?? globalThis.fetch;
-    const version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
     const rootUsageName = options.rootUsageName ?? inferProgramName(argv);
-    const controls = resolveCLIControls(options.controls);
-    const servicesWithBuiltIns = {
-        ...services,
-        runtimeOptions,
-        root
-    };
-    const requirementOptions = {
-        apiVersion: options.apiVersion
-    };
-    validateServices(services);
-    if (hasHelpFlag(argv)) {
-        await renderGeneratedHelp(root, argv, { ...options, version });
-        return;
-    }
-    const program = new CommanderCommand();
-    program.name(root.name);
-    program.exitOverride();
-    program.showHelpAfterError();
-    program.addHelpCommand(false);
-    const presetsEnabled = options.presets === true;
-    const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled, version !== undefined, controls);
-    addGlobalOptions(program, presetsEnabled, controls);
-    if (version !== undefined) {
-        program.version(version, "--version");
-    }
-    Reflect.set(program, "_toolcraftReservedChildNames", root.children
-        .filter((child) => !isNodeVisibleInScope(child, "cli"))
-        .flatMap((child) => getNodeCommandNames(child)));
     let lastActionCommand;
     let resolvedCommandPath = "";
+    let program;
+    let version;
+    let userErrorPattern = "definition";
     let errorReportContext;
-    const execute = async (state) => {
-        lastActionCommand = state.actionCommand;
-        resolvedCommandPath = formatCliCommandPath(state.commandPath);
-        await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, (context) => {
-            errorReportContext = context;
-        });
-    };
-    const rootChildNames = new Set(root.children
-        .filter((candidate) => isNodeVisibleInScope(candidate, "cli"))
-        .map((candidate) => candidate.name));
-    for (const child of root.children) {
-        const command = createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled, controls);
-        if (command === null) {
-            continue;
-        }
-        const isDefaultChild = root.default !== undefined &&
-            root.default.scope.includes("cli") &&
-            (command.name() === root.default.name || command.aliases().includes(root.default.name));
-        addCommanderChild(program, command, isDefaultChild, rootChildNames);
-    }
-    configureCommanderSuggestionOutput(program);
-    const unknownCommand = findUnknownCommanderCommand(program, argv);
-    if (unknownCommand !== undefined) {
-        createLogger().error(appendUsagePointer(formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand), {
-            rootUsageName,
-            commandPath: unknownCommand.commandPath
-        }));
-        process.exitCode = 1;
-        return;
-    }
     try {
+        const normalizedRoot = normalizeRoots(roots, argv);
+        const root = options.approvals === true ? mergeApprovalsGroup(normalizedRoot) : normalizedRoot;
+        await resolveMcpProxies(root, { projectRoot: options.projectRoot });
+        const casing = options.casing ?? "kebab";
+        const services = (options.services ?? {});
+        const runtimeOptions = options.humanInLoop ?? {};
+        const runtimeFetch = options.fetch ?? globalThis.fetch;
+        version = options.version ?? findEntrypointPackageMetadata(argv[1])?.version;
+        const controls = resolveCLIControls(options.controls);
+        const servicesWithBuiltIns = {
+            ...services,
+            runtimeOptions,
+            root
+        };
+        const requirementOptions = {
+            apiVersion: options.apiVersion
+        };
+        validateServices(services);
+        if (hasHelpFlag(argv)) {
+            userErrorPattern = "usage";
+            await renderGeneratedHelp(root, argv, { ...options, version });
+            return;
+        }
+        program = new CommanderCommand();
+        program.name(root.name);
+        program.exitOverride();
+        program.showHelpAfterError();
+        program.addHelpCommand(false);
+        const presetsEnabled = options.presets === true;
+        const globalLongOptionFlags = getGlobalLongOptionFlags(presetsEnabled, version !== undefined, controls);
+        addGlobalOptions(program, presetsEnabled, controls);
+        if (version !== undefined) {
+            program.version(version, "--version");
+        }
+        Reflect.set(program, "_toolcraftReservedChildNames", root.children
+            .filter((child) => !isNodeVisibleInScope(child, "cli"))
+            .flatMap((child) => getNodeCommandNames(child)));
+        const execute = async (state) => {
+            lastActionCommand = state.actionCommand;
+            resolvedCommandPath = formatCliCommandPath(state.commandPath);
+            await executeCommand(state, servicesWithBuiltIns, requirementOptions, runtimeFetch, runtimeOptions, (context) => {
+                errorReportContext = context;
+            });
+        };
+        const rootChildNames = new Set(root.children
+            .filter((candidate) => isNodeVisibleInScope(candidate, "cli"))
+            .map((candidate) => candidate.name));
+        for (const child of root.children) {
+            const command = createNodeCommand(child, casing, globalLongOptionFlags, execute, presetsEnabled, controls);
+            if (command === null) {
+                continue;
+            }
+            const isDefaultChild = root.default !== undefined &&
+                root.default.scope.includes("cli") &&
+                (command.name() === root.default.name || command.aliases().includes(root.default.name));
+            addCommanderChild(program, command, isDefaultChild, rootChildNames);
+        }
+        configureCommanderSuggestionOutput(program);
+        const unknownCommand = findUnknownCommanderCommand(program, argv);
+        if (unknownCommand !== undefined) {
+            createLogger().error(appendUsagePointer(formatUnknownCommandMessage(unknownCommand.input, unknownCommand.currentCommand), {
+                rootUsageName,
+                commandPath: unknownCommand.commandPath
+            }));
+            process.exitCode = 1;
+            return;
+        }
+        userErrorPattern = "usage";
         await program.parseAsync(argv);
     }
     catch (error) {
@@ -3296,7 +3423,7 @@ export async function runCLI(roots, options = {}) {
             argv,
             rootUsageName,
             commandPath: resolvedCommandPath,
-            userErrorPattern: errorReportContext?.params === undefined ? "usage" : "runtime-user"
+            userErrorPattern: errorReportContext?.params === undefined ? userErrorPattern : "runtime-user"
         });
     }
 }

package/dist/human-in-loop/approvals-commands.js

@@ -14,11 +14,7 @@ const showParams = S.Object({
     approvalId: S.String()
 });
 const runParams = S.Object({
-    approvalId: S.String(),
-    dryRun: S.Optional(S.Boolean({
-        description: "Preview the approval without prompting or executing it",
-        scope: ["cli"]
-    }))
+    approvalId: S.String()
 });
 export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
     name: "approvals",
@@ -76,10 +72,6 @@ export const approvalsGroup = markApprovalsBuiltIn(defineGroup({
             scope: runScope,
             params: runParams,
             handler: async ({ params, runtimeOptions, root }) => {
-                if (params.dryRun === true) {
-                    const { tasks } = await ensureApprovalList(runtimeOptions, { create: false });
-                    return tasks.get(params.approvalId);
-                }
                 return runApproval(params.approvalId, runtimeOptions, root);
             },
             render: {

package/dist/mcp.compile-check.js

@@ -8,7 +8,7 @@ const ignoredRoot = defineGroup({
             name: "usage",
             scope: ["mcp"],
             params: S.Object({
-                dryRun: S.Boolean(),
+                preview: S.Boolean(),
             }),
             handler: async ({ params }) => params,
         }),

package/dist/mcp.js

@@ -1,6 +1,7 @@
 import { access, lstat, readFile, rename, unlink, writeFile } from "node:fs/promises";
 import { createServer, JSON_RPC_ERROR_CODES, ToolError } from "tiny-stdio-mcp-server";
 import { toJsonSchema } from "toolcraft-schema";
+import { createHttpErrorEnvelope, isHttpErrorLike } from "./api-error-summary.js";
 import { ToolcraftBugError, UserError, assertCommandRequirements, resolveCommandSecrets } from "./index.js";
 import { writeErrorReport } from "./error-report.js";
 import { mergeApprovalsGroup } from "./human-in-loop/approvals-commands.js";
@@ -730,10 +731,17 @@ function toToolContent(result) {
     const fallbackText = JSON.stringify(fallbackValue);
     return [{ type: "text", text: fallbackText }];
 }
-function toToolError(error) {
+function toToolError(error, reportPath) {
     if (error instanceof ToolError) {
         return error;
     }
+    if (isHttpErrorLike(error)) {
+        const code = error.response.status >= 400 && error.response.status < 500
+            ? JSON_RPC_ERROR_CODES.INVALID_PARAMS
+            : JSON_RPC_ERROR_CODES.INTERNAL_ERROR;
+        const envelope = createHttpErrorEnvelope(error, reportPath);
+        return new ToolError(code, envelope.message, envelope);
+    }
     if (error instanceof UserError) {
         return new ToolError(JSON_RPC_ERROR_CODES.INVALID_PARAMS, error.message);
     }
@@ -798,7 +806,7 @@ function createResolvedMCPServer(root, options) {
                 if (error instanceof ApprovalDeclinedError) {
                     return renderDeclinedApproval(error);
                 }
-                await writeErrorReport({
+                const report = await writeErrorReport({
                     command: tool.command,
                     commandPath: tool.commandPath,
                     env: process.env,
@@ -808,7 +816,7 @@ function createResolvedMCPServer(root, options) {
                     projectRoot: options.projectRoot,
                     secrets
                 });
-                throw toToolError(error);
+                throw toToolError(error, report?.displayPath);
             }
         };
         if (tool.outputSchema === undefined) {

package/node_modules/toolcraft-design/dist/components/help-formatter-plain.js

@@ -100,7 +100,7 @@ export function formatColumns(opts) {
             return [`${firstIndent}${row.left}`];
         }
         const rightLines = wrapWords(row.right, rightWidth);
-        if (row.left.length > leftWidth) {
+        if (row.left.length >= leftWidth) {
             return [
                 `${firstIndent}${row.left}`,
                 ...rightLines.map((line) => `${continuationIndent}${line}`)

package/node_modules/toolcraft-design/dist/components/help-formatter.js

@@ -159,7 +159,7 @@ export function formatColumns(opts) {
             return [`${firstIndent}${row.left}`];
         }
         const rightLines = wrapWords(row.right, rightWidth);
-        if (visibleWidth(row.left) > leftWidth) {
+        if (visibleWidth(row.left) >= leftWidth) {
             return [
                 `${firstIndent}${row.left}`,
                 ...rightLines.map((line) => `${continuationIndent}${line}`)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.60",
+  "version": "0.0.61",
   "type": "module",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,7 +47,7 @@
     "postpack": "node ../../scripts/manage-bundled-workspace-deps.mjs cleanup . toolcraft-design @poe-code/frontmatter @poe-code/agent-mcp-config @poe-code/agent-human-in-loop @poe-code/task-list @poe-code/agent-defs @poe-code/config-mutations @poe-code/process-runner tiny-mcp-client mcp-oauth auth-store"
   },
   "dependencies": {
-    "toolcraft-schema": "0.0.60",
+    "toolcraft-schema": "0.0.61",
     "commander": "^14.0.3",
     "fast-string-width": "^3.0.2",
     "fast-wrap-ansi": "^0.2.0",