toolcraft 0.0.129 → 0.0.131

package/composition.json

@@ -108,7 +108,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.129",
+      "version": "0.0.131",
       "license": "MIT"
     },
     {
@@ -118,7 +118,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.129",
+      "version": "0.0.131",
       "license": "MIT"
     },
     {

package/dist/cli.d.ts

@@ -7,8 +7,14 @@ export { renderErrorReport } from "./error-report.js";
 export type { ErrorReportRenderContext, ErrorReportRenderResult } from "./error-report.js";
 export { configureTheme };
 type Casing = "kebab" | "snake";
+export type CLIHelpDepth = "concise" | "extended";
 export interface CLIControls {
     debug?: boolean;
+    /**
+     * Group `--help` depth. `extended` (default) lists every nested action under the
+     * help target; `concise` lists only direct children.
+     */
+    help?: CLIHelpDepth;
     logLevel?: boolean;
     output?: boolean | CLIOutputControl;
     verbose?: boolean;

package/dist/cli.js

@@ -3,7 +3,7 @@ import { readFile } from "node:fs/promises";
 import path from "node:path";
 import { Command as CommanderCommand, CommanderError, InvalidArgumentError, Option } from "commander";
 import { validate as validateSchema } from "toolcraft-schema";
-import { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
+import { cancel, configureTheme, confirm, createLogger, formatCommandList, formatOptionList, getTheme, helpFormatterPlain, isCancel, note, promptText, renderHelpTokens, renderTable, resetOutputFormatCache, select, text } from "toolcraft-design";
 import { ApprovalDeclinedError, ToolcraftBugError, UserError, assertCommandRequirements, getCommandSourcePath, hasMcpProxyConfig, resolveCommandSecrets } from "./index.js";
 import { hasOwnErrorCode } from "./error-codes.js";
 import { writeErrorReport } from "./error-report.js";
@@ -663,6 +663,7 @@ function resolveCLIControls(controls) {
     validateOutputFormats(outputFormats);
     return {
         debug: controls?.debug === true,
+        help: controls?.help === "concise" ? "concise" : "extended",
         logLevel: controls?.logLevel === true,
         output: controls?.output === true || typeof controls?.output === "object",
         outputFormats,
@@ -843,12 +844,37 @@ function appendHelpMetadata(description, metadata) {
         return description;
     }
     if (description.length === 0) {
-        return `(${metadata.join(", ")})`;
+        return metadata.map((entry) => `(${entry})`).join(" ");
     }
-    return `${description} (${metadata.join(", ")})`;
+    return `${description} ${metadata.map((entry) => `(${entry})`).join(" ")}`;
+}
+function normalizeHelpEchoKey(value) {
+    let normalized = "";
+    for (const character of value.trim().toLowerCase()) {
+        if (character !== " " &&
+            character !== "\t" &&
+            character !== "\n" &&
+            character !== "\r" &&
+            character !== "_" &&
+            character !== "." &&
+            character !== "-") {
+            normalized += character;
+        }
+    }
+    return normalized;
+}
+function isEchoHelpDescription(description, name) {
+    if (description.length === 0) {
+        return false;
+    }
+    return normalizeHelpEchoKey(description) === normalizeHelpEchoKey(name);
+}
+function suppressEchoHelpDescription(description, name) {
+    return isEchoHelpDescription(description, name) ? "" : description;
 }
 function formatHelpFieldDescription(field) {
-    const description = field.description ?? field.displayPath;
+    const rawDescription = field.description ?? field.displayPath;
+    const description = suppressEchoHelpDescription(rawDescription, field.displayPath);
     const metadata = [];
     if (field.schema.kind === "enum" && field.schema.values.length <= 8) {
         const values = field.schema.values.map((value) => String(value)).join(", ");
@@ -1005,53 +1031,55 @@ function formatDynamicHelpMetadata(field) {
     }
     return metadata;
 }
+function createHelpOptionRow(flags, description) {
+    return {
+        flags,
+        flagTokens: tokenizeHelpFlags(flags),
+        description
+    };
+}
 function collectDynamicObjectHelpRows(schema, casing, optionPrefix, displayPrefix, metadata) {
     const rows = [];
     for (const [key, rawChildSchema] of Object.entries(schema.shape)) {
         const childSchema = unwrapOptional(rawChildSchema);
         const optionFlag = `${optionPrefix}.${formatSegment(key, casing)}`;
         const displayPath = `${displayPrefix}.${key}`;
-        const description = childSchema.description ?? displayPath;
+        const rawDescription = childSchema.description ?? displayPath;
+        const description = suppressEchoHelpDescription(rawDescription, displayPath);
         if (childSchema.kind === "object") {
             rows.push(...collectDynamicObjectHelpRows(childSchema, casing, optionFlag, displayPath, metadata));
             continue;
         }
         if (childSchema.kind === "record") {
-            rows.push({
-                flags: `${optionFlag}.<key> <${describeDynamicFieldType({
-                    ...{
-                        id: displayPath,
-                        path: [],
-                        displayPath,
-                        optionPath: [],
-                        optionPathDisplay: `${displayPath}.<key>`,
-                        optionFlag: `${optionFlag}.<key>`,
-                        optional: false,
-                        hasDefault: false,
-                        defaultValue: undefined,
-                        requiredWhenActive: false,
-                        schema: childSchema
-                    }
-                })}>`,
-                description: appendHelpMetadata(description, metadata)
-            });
+            rows.push(createHelpOptionRow(`${optionFlag}.<key> <${describeDynamicFieldType({
+                ...{
+                    id: displayPath,
+                    path: [],
+                    displayPath,
+                    optionPath: [],
+                    optionPathDisplay: `${displayPath}.<key>`,
+                    optionFlag: `${optionFlag}.<key>`,
+                    optional: false,
+                    hasDefault: false,
+                    defaultValue: undefined,
+                    requiredWhenActive: false,
+                    schema: childSchema
+                }
+            })}>`, appendHelpMetadata(description, metadata)));
             continue;
         }
         if (childSchema.kind === "array" && unwrapOptional(childSchema.item).kind === "object") {
             rows.push(...collectDynamicObjectHelpRows(unwrapOptional(childSchema.item), casing, `${optionFlag}.<index>`, `${displayPath}.<index>`, metadata));
             continue;
         }
-        rows.push({
-            flags: childSchema.kind === "boolean"
-                ? childSchema.default === true
-                    ? `--no-${optionFlag.slice(2)}`
-                    : optionFlag
-                : `${optionFlag} <${describeHelpValueToken(childSchema, {
-                    displayPath,
-                    optionFlag
-                })}>`,
-            description: appendHelpMetadata(description, metadata)
-        });
+        rows.push(createHelpOptionRow(childSchema.kind === "boolean"
+            ? childSchema.default === true
+                ? `--no-${optionFlag.slice(2)}`
+                : optionFlag
+            : `${optionFlag} <${describeHelpValueToken(childSchema, {
+                displayPath,
+                optionFlag
+            })}>`, appendHelpMetadata(description, metadata)));
     }
     return rows;
 }
@@ -1070,17 +1098,11 @@ function formatDynamicHelpFields(field, casing) {
         }
     }
     return [
-        {
-            flags: `${field.optionFlag} <${describeDynamicFieldType(field)}>`,
-            description: appendHelpMetadata(field.description ?? field.optionPathDisplay, metadata)
-        }
+        createHelpOptionRow(`${field.optionFlag} <${describeDynamicFieldType(field)}>`, appendHelpMetadata(suppressEchoHelpDescription(field.description ?? field.optionPathDisplay, field.optionPathDisplay), metadata))
     ];
 }
 function formatSecretRows(secrets) {
-    return Object.values(secrets).map((secret) => ({
-        flags: secret.env,
-        description: formatSecretDescription(secret)
-    }));
+    return Object.values(secrets).map((secret) => createHelpOptionRow(secret.env, formatSecretDescription(secret)));
 }
 function formatSecretDescription(secret) {
     if (secret.description !== undefined && secret.description.length > 0) {
@@ -1109,34 +1131,142 @@ function formatExampleCommand(breadcrumb, rootUsageName, params) {
 function formatExampleRows(examples, breadcrumb, rootUsageName) {
     return examples.map((example) => `${example.title}\n  ${formatExampleCommand(breadcrumb, rootUsageName, example.params)}`);
 }
-function wrapOptionalCommandParameterToken(token, optional) {
-    return optional ? `[${token}]` : token;
+const MAX_INLINE_OPTIONAL_PARAMETER_TOKENS = 8;
+function tokenizeHelpFlags(flags) {
+    const tokens = [];
+    let index = 0;
+    while (index < flags.length) {
+        if (flags[index] === " ") {
+            let end = index + 1;
+            while (end < flags.length && flags[end] === " ") {
+                end += 1;
+            }
+            tokens.push({ text: flags.slice(index, end), role: "literal" });
+            index = end;
+            continue;
+        }
+        if (flags[index] === "[" || flags[index] === "]") {
+            tokens.push({ text: flags[index], role: "dim" });
+            index += 1;
+            continue;
+        }
+        if (flags[index] === "<") {
+            const close = flags.indexOf(">", index);
+            if (close === -1) {
+                tokens.push({ text: flags.slice(index), role: "literal" });
+                break;
+            }
+            tokens.push({ text: flags.slice(index, close + 1), role: "argument" });
+            index = close + 1;
+            continue;
+        }
+        if (flags.startsWith("--", index) || (flags[index] === "-" && flags[index + 1] !== undefined && flags[index + 1] !== "-")) {
+            let end = index + 1;
+            while (end < flags.length && flags[end] !== " " && flags[end] !== "[" && flags[end] !== "]" && flags[end] !== "<") {
+                end += 1;
+            }
+            tokens.push({ text: flags.slice(index, end), role: "option" });
+            index = end;
+            continue;
+        }
+        // Enum literals (a|b) or bare words after a flag.
+        let end = index + 1;
+        while (end < flags.length && flags[end] !== " " && flags[end] !== "[" && flags[end] !== "]" && flags[end] !== "<") {
+            end += 1;
+        }
+        const piece = flags.slice(index, end);
+        tokens.push({
+            text: piece,
+            role: piece.includes("|") ? "literal" : piece.startsWith("+") ? "dim" : "literal"
+        });
+        index = end;
+    }
+    return tokens;
+}
+function wrapOptionalParameterTokens(tokens, optional) {
+    if (!optional) {
+        return tokens;
+    }
+    return [{ text: "[", role: "dim" }, ...tokens, { text: "]", role: "dim" }];
+}
+function createCommandParameterToken(text, optional) {
+    return {
+        text: optional ? `[${text}]` : text,
+        optional,
+        tokens: wrapOptionalParameterTokens(tokenizeHelpFlags(text), optional)
+    };
 }
 function formatCommandDynamicParameterTokens(field, casing) {
     const optional = field.optional || field.hasDefault;
-    return formatDynamicHelpFields(field, casing).map((row) => wrapOptionalCommandParameterToken(row.flags, optional));
+    return formatDynamicHelpFields(field, casing).map((row) => createCommandParameterToken(row.flags, optional));
 }
 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(formatCommandParameterFieldFlags(field, globalLongOptionFlags), field.positionalIndex === undefined && (field.optional || field.hasDefault)))
+        .map((field) => createCommandParameterToken(formatCommandParameterFieldFlags(field, globalLongOptionFlags), field.positionalIndex === undefined && (field.optional || field.hasDefault)))
         .concat(collected.dynamicFields.flatMap((field) => formatCommandDynamicParameterTokens(field, casing)));
 }
-function formatCommandRowName(node, casing, globalLongOptionFlags) {
+function collapseOptionalParameterTokens(parameterTokens) {
+    const optionalCount = parameterTokens.filter((token) => token.optional).length;
+    if (optionalCount <= MAX_INLINE_OPTIONAL_PARAMETER_TOKENS) {
+        return parameterTokens;
+    }
+    const required = parameterTokens.filter((token) => !token.optional);
+    const collapsedText = `+${optionalCount} options`;
+    return [
+        ...required,
+        {
+            text: `[${collapsedText}]`,
+            optional: true,
+            tokens: [
+                { text: "[", role: "dim" },
+                { text: collapsedText, role: "dim" },
+                { text: "]", role: "dim" }
+            ]
+        }
+    ];
+}
+function formatCommandRowNameTokens(node, casing, globalLongOptionFlags) {
     const baseName = node.aliases.length === 0 ? node.name : `${node.name} (${node.aliases.join(", ")})`;
+    const nameTokens = [{ text: baseName, role: "command" }];
     const parameterTokens = node.kind === "command"
-        ? formatCommandParameterTokens(node, casing, globalLongOptionFlags)
+        ? collapseOptionalParameterTokens(formatCommandParameterTokens(node, casing, globalLongOptionFlags))
         : [];
-    const name = parameterTokens.length === 0 ? baseName : `${baseName} ${parameterTokens.join(" ")}`;
-    return name;
+    for (const token of parameterTokens) {
+        nameTokens.push({ text: " ", role: "literal" }, ...token.tokens);
+    }
+    const name = parameterTokens.length === 0
+        ? baseName
+        : `${baseName} ${parameterTokens.map((token) => token.text).join(" ")}`;
+    return { name, nameTokens };
 }
-function formatCommandRows(group, scope, casing, globalLongOptionFlags) {
-    return getHelpChildren(group, scope).map((child) => ({
-        name: formatCommandRowName(child, casing, globalLongOptionFlags),
-        description: child.description ?? ""
-    }));
+function formatCommandRows(group, scope, casing, globalLongOptionFlags, help) {
+    const toRow = (child, depth) => {
+        const { name, nameTokens } = formatCommandRowNameTokens(child, casing, globalLongOptionFlags);
+        return {
+            name,
+            nameTokens,
+            description: suppressEchoHelpDescription(child.description ?? "", child.name),
+            kind: child.kind,
+            depth
+        };
+    };
+    if (help === "concise") {
+        return getHelpChildren(group, scope).map((child) => toRow(child, 0));
+    }
+    const rows = [];
+    const visit = (node, depth) => {
+        for (const child of getHelpChildren(node, scope)) {
+            rows.push(toRow(child, depth));
+            if (child.kind === "group") {
+                visit(child, depth + 1);
+            }
+        }
+    };
+    visit(group, 0);
+    return rows;
 }
 function formatGlobalOptionsLine(ctx) {
     const flags = [];
@@ -1176,10 +1306,7 @@ function collectSchemaGlobalFieldRows(group, scope, casing, globalLongOptionFlag
                 if (seen.has(dedupeKey)) {
                     continue;
                 }
-                seen.set(dedupeKey, {
-                    flags: formatHelpFieldFlags(field, globalLongOptionFlags),
-                    description: formatHelpFieldDescription(field)
-                });
+                seen.set(dedupeKey, createHelpOptionRow(formatHelpFieldFlags(field, globalLongOptionFlags), formatHelpFieldDescription(field)));
             }
             return;
         }
@@ -1203,6 +1330,23 @@ function formatHelpOptionList(rows) {
         ? helpFormatterPlain.formatOptionList(rows)
         : formatOptionList(rows);
 }
+function sortLeafHelpOptionFields(fields) {
+    const positionals = [];
+    const required = [];
+    const optional = [];
+    for (const field of fields) {
+        if (field.positionalIndex !== undefined) {
+            positionals.push(field);
+            continue;
+        }
+        if (!field.optional && !field.hasDefault) {
+            required.push(field);
+            continue;
+        }
+        optional.push(field);
+    }
+    return [...positionals, ...required, ...optional];
+}
 function buildUsageLine(breadcrumb, rootUsageName, suffix) {
     const visibleBreadcrumb = breadcrumb.filter((segment) => segment.length > 0);
     const usageBreadcrumb = breadcrumb[0] === "" ? [rootUsageName, ...visibleBreadcrumb] : visibleBreadcrumb;
@@ -1214,15 +1358,35 @@ function formatGroupUsageSuffix(group, scope, casing, globalLongOptionFlags) {
     if (group.default !== undefined &&
         group.default.hidden === true &&
         group.default.scope.includes(scope)) {
-        const parameterTokens = formatCommandParameterTokens(group.default, casing, globalLongOptionFlags);
-        return ["[command]", "[OPTIONS]", ...parameterTokens].join(" ");
+        const parameterTokens = collapseOptionalParameterTokens(formatCommandParameterTokens(group.default, casing, globalLongOptionFlags));
+        return ["[command]", "[OPTIONS]", ...parameterTokens.map((token) => token.text)].join(" ");
     }
     return "[command] [OPTIONS]";
 }
+function formatHelpDrillDownFooter(rootUsageName) {
+    return text.muted(`Run ${rootUsageName} <command> --help for full options.`);
+}
+function formatStyledUsageLine(usageLine) {
+    const parts = usageLine.split(" ").filter((part) => part.length > 0);
+    if (parts.length === 0) {
+        return text.usageCommand(usageLine);
+    }
+    const commandEnd = parts.findIndex((part) => part.startsWith("-") || part.startsWith("[") || part.startsWith("<"));
+    const commandParts = commandEnd === -1 ? parts : parts.slice(0, commandEnd);
+    const argParts = commandEnd === -1 ? [] : parts.slice(commandEnd);
+    const command = commandParts.join(" ");
+    if (argParts.length === 0) {
+        return text.usageCommand(command);
+    }
+    return `${text.usageCommand(command)} ${renderHelpTokens(argParts.flatMap((part, index) => [
+        ...(index === 0 ? [] : [{ text: " ", role: "literal" }]),
+        ...tokenizeHelpFlags(part)
+    ]))}`;
+}
 function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUsageName, isRoot) {
     const sections = [];
     const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion, globalOptions.controls);
-    const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags);
+    const commandRows = formatCommandRows(group, scope, casing, globalLongOptionFlags, globalOptions.controls.help);
     if (commandRows.length > 0) {
         sections.push(`${text.sectionHeader("Commands")}\n${formatHelpCommandList(commandRows)}`);
     }
@@ -1236,6 +1400,9 @@ function renderGroupHelp(group, breadcrumb, scope, casing, globalOptions, rootUs
             sections.push(builtInLine);
         }
     }
+    if (commandRows.length > 0) {
+        sections.push(formatHelpDrillDownFooter(rootUsageName));
+    }
     return renderHelpDocument({
         breadcrumb,
         rootUsageName,
@@ -1250,12 +1417,8 @@ function renderLeafHelp(command, breadcrumb, casing, globalOptions, rootUsageNam
     const globalLongOptionFlags = getGlobalLongOptionFlags(globalOptions.presetsEnabled, globalOptions.showVersion, globalOptions.controls);
     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)
-    }))
+    const optionRows = sortLeafHelpOptionFields(fields.filter((field) => field.global !== true))
+        .map((field) => createHelpOptionRow(formatHelpFieldFlags(field, globalLongOptionFlags), formatHelpFieldDescription(field)))
         .concat(collected.dynamicFields.flatMap((field) => formatDynamicHelpFields(field, casing)));
     if (optionRows.length > 0) {
         sections.push(`${text.sectionHeader("Options")}\n${formatHelpOptionList(optionRows)}`);
@@ -1288,7 +1451,7 @@ 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 commandRows = formatCommandRows(node, "cli", casing, globalLongOptionFlags, globalOptions.controls.help);
         const isRoot = node === root;
         return `${JSON.stringify({
             schemaVersion: 1,
@@ -1297,7 +1460,12 @@ function renderJsonHelp(target, root, casing, globalOptions, 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 })),
+            commands: commandRows.map((row) => ({
+                name: row.name,
+                description: row.description,
+                kind: row.kind,
+                depth: row.depth
+            })),
             options: isRoot
                 ? collectSchemaGlobalFieldRows(node, "cli", casing, globalLongOptionFlags).map((row) => ({
                     name: row.flags.split(/[ ,]+/)[0]?.replace(/^--/, "") ?? row.flags,
@@ -1368,7 +1536,7 @@ function renderHelpDocument(input) {
     if (remainingDescription.length > 0) {
         lines.push(remainingDescription, "");
     }
-    lines.push(`Usage: ${text.usageCommand(input.usageLine)}`, "");
+    lines.push(`Usage: ${formatStyledUsageLine(input.usageLine)}`, "");
     if (input.requiresAuth) {
         lines.push("Requires: authentication");
     }

package/dist/composition.json

@@ -108,7 +108,7 @@
     },
     {
       "name": "toolcraft",
-      "version": "0.0.129",
+      "version": "0.0.131",
       "license": "MIT"
     },
     {
@@ -118,7 +118,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.129",
+      "version": "0.0.131",
       "license": "MIT"
     },
     {

package/dist/design/help-formatter.d.ts

@@ -1,2 +1,2 @@
-export { helpFormatter } from "toolcraft-design/help-formatter";
-export type { CommandInfo, FormatColumnsOptions, OptionInfo } from "toolcraft-design/help-formatter";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList, styleHelpToken, joinHelpTokens, renderHelpTokens } from "toolcraft-design/help-formatter";
+export type { CommandInfo, FormatColumnsOptions, OptionInfo, HelpToken, HelpTokenRole } from "toolcraft-design/help-formatter";

package/dist/design/help-formatter.js

@@ -1 +1 @@
-export { helpFormatter } from "toolcraft-design/help-formatter";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList, styleHelpToken, joinHelpTokens, renderHelpTokens } from "toolcraft-design/help-formatter";

package/node_modules/tiny-stdio-mcp-server/dist/composition.json

@@ -8,7 +8,7 @@
     },
     {
       "name": "toolcraft-schema",
-      "version": "0.0.129",
+      "version": "0.0.131",
       "license": "MIT"
     }
   ]

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

@@ -1,3 +1,4 @@
+import { joinHelpTokens } from "./help-formatter.js";
 export function stripAnsi(value) {
     let output = "";
     for (let index = 0; index < value.length; index += 1) {
@@ -54,26 +55,49 @@ function splitWords(value) {
     }
     return words;
 }
-function wrapWords(value, width) {
-    const words = splitWords(value);
+function leadingWhitespace(value) {
+    let index = 0;
+    while (index < value.length && isWhitespace(value[index])) {
+        index += 1;
+    }
+    return { prefix: value.slice(0, index), rest: value.slice(index) };
+}
+function takePrefix(value, width) {
+    return { prefix: value.slice(0, width), rest: value.slice(width) };
+}
+function wrapWords(value, width, continuationWidth = width) {
+    // Preserve leading whitespace only on the first wrapped line so hang-indented
+    // left cells (command depth prefixes) do not re-indent every continuation.
+    const { prefix, rest } = leadingWhitespace(value);
+    const firstContentWidth = Math.max(1, width - prefix.length);
+    const words = splitWords(rest);
     if (words.length === 0) {
-        return [""];
+        return [prefix];
     }
     const lines = [];
     let line = "";
+    let isFirstLine = true;
     for (const word of words) {
-        if (!line) {
-            line = word;
-            continue;
-        }
-        if (line.length + 1 + word.length <= width) {
+        const limit = isFirstLine ? firstContentWidth : continuationWidth;
+        if (line && line.length + 1 + word.length <= limit) {
             line += ` ${word}`;
             continue;
         }
-        lines.push(line);
-        line = word;
+        if (line) {
+            lines.push(isFirstLine ? `${prefix}${line}` : line);
+            isFirstLine = false;
+            line = "";
+        }
+        let remaining = word;
+        while (remaining.length > (isFirstLine ? firstContentWidth : continuationWidth)) {
+            const chunk = takePrefix(remaining, isFirstLine ? firstContentWidth : continuationWidth);
+            lines.push(isFirstLine ? `${prefix}${chunk.prefix}` : chunk.prefix);
+            isFirstLine = false;
+            remaining = chunk.rest;
+        }
+        line = remaining;
     }
-    lines.push(line);
+    lines.push(isFirstLine ? `${prefix}${line}` : line);
     return lines;
 }
 export function formatColumns(opts) {
@@ -91,33 +115,43 @@ export function formatColumns(opts) {
     const indent = opts.indent ?? 2;
     const maxLeftContentWidth = Math.max(...rows.map((row) => row.left.length));
     const leftWidth = clamp(maxLeftContentWidth + gap, minLeftWidth, maxLeftWidth);
-    const rightWidth = Math.max(20, totalWidth - leftWidth - indent);
+    const rightWidth = Math.max(1, totalWidth - leftWidth - indent);
+    const leftWrapWidth = Math.max(1, totalWidth - indent);
     const firstIndent = " ".repeat(indent);
     const continuationIndent = " ".repeat(indent + leftWidth);
     return rows
         .flatMap((row) => {
+        let leftLeadingWidth = 0;
+        while (leftLeadingWidth < row.left.length && isWhitespace(row.left[leftLeadingWidth])) {
+            leftLeadingWidth += 1;
+        }
+        // Continuations hang under the left cell start (including depth prefix) by +2.
+        const leftHangIndent = " ".repeat(indent + leftLeadingWidth + 2);
+        const leftLines = wrapWords(row.left, leftWrapWidth, Math.max(1, totalWidth - leftHangIndent.length));
         if (row.right.length === 0) {
-            return [`${firstIndent}${row.left}`];
+            return leftLines.map((line, index) => index === 0 ? `${firstIndent}${line}` : `${leftHangIndent}${line}`);
         }
         const rightLines = wrapWords(row.right, rightWidth);
-        if (row.left.length >= leftWidth) {
-            return [
-                `${firstIndent}${row.left}`,
-                ...rightLines.map((line) => `${continuationIndent}${line}`)
-            ];
+        const leftFitsInColumn = row.left.length < leftWidth;
+        if (leftFitsInColumn && leftLines.length === 1) {
+            const firstLine = `${firstIndent}${padEndVisible(leftLines[0] ?? "", leftWidth)}${rightLines[0]}`;
+            const continuationLines = rightLines
+                .slice(1)
+                .map((line) => `${continuationIndent}${line}`);
+            return [firstLine, ...continuationLines];
         }
-        const firstLine = `${firstIndent}${padEndVisible(row.left, leftWidth)}${rightLines[0]}`;
-        const continuationLines = rightLines
-            .slice(1)
-            .map((line) => `${continuationIndent}${line}`);
-        return [firstLine, ...continuationLines];
+        const renderedLeft = leftLines.map((line, index) => index === 0 ? `${firstIndent}${line}` : `${leftHangIndent}${line}`);
+        const renderedRight = rightLines.map((line) => `${continuationIndent}${line}`);
+        return [...renderedLeft, ...renderedRight];
     })
         .join("\n");
 }
 export function formatCommandList(commands) {
     return formatColumns({
         rows: commands.map((cmd) => ({
-            left: cmd.name,
+            left: `${" ".repeat((cmd.depth ?? 0) * 2)}${cmd.nameTokens !== undefined && cmd.nameTokens.length > 0
+                ? joinHelpTokens(cmd.nameTokens)
+                : cmd.name}`,
             right: cmd.description
         }))
     });
@@ -125,7 +159,9 @@ export function formatCommandList(commands) {
 export function formatOptionList(options) {
     return formatColumns({
         rows: options.map((opt) => ({
-            left: opt.flags,
+            left: opt.flagTokens !== undefined && opt.flagTokens.length > 0
+                ? joinHelpTokens(opt.flagTokens)
+                : opt.flags,
             right: opt.description
         }))
     });

package/node_modules/toolcraft-design/dist/components/help-formatter.d.ts

@@ -1,9 +1,20 @@
+export type HelpTokenRole = "command" | "argument" | "option" | "literal" | "dim";
+export interface HelpToken {
+    text: string;
+    role: HelpTokenRole;
+}
 export interface CommandInfo {
     name: string;
+    /** Structured tokens for TTY/markdown styling. Plain `name` is used when absent. */
+    nameTokens?: HelpToken[];
     description: string;
+    /** Nesting depth relative to the help target. Depth 0 is a direct child. */
+    depth?: number;
 }
 export interface OptionInfo {
     flags: string;
+    /** Structured tokens for TTY/markdown styling. Plain `flags` is used when absent. */
+    flagTokens?: HelpToken[];
     description: string;
 }
 export interface FormatColumnsOptions {
@@ -18,6 +29,9 @@ export interface FormatColumnsOptions {
     indent?: number;
 }
 export declare function formatColumns(opts: FormatColumnsOptions): string;
+export declare function styleHelpToken(token: HelpToken): string;
+export declare function joinHelpTokens(tokens: HelpToken[]): string;
+export declare function renderHelpTokens(tokens: HelpToken[]): string;
 export declare function formatCommand(name: string, description: string): string;
 export declare function formatUsage(command: string, args?: string): string;
 export declare function formatOption(flags: string, description: string): string;
@@ -30,4 +44,7 @@ export declare const helpFormatter: {
     readonly formatOption: typeof formatOption;
     readonly formatCommandList: typeof formatCommandList;
     readonly formatOptionList: typeof formatOptionList;
+    readonly styleHelpToken: typeof styleHelpToken;
+    readonly joinHelpTokens: typeof joinHelpTokens;
+    readonly renderHelpTokens: typeof renderHelpTokens;
 };

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

@@ -1,3 +1,5 @@
+import { resolveOutputFormat } from "../internal/output-format.js";
+import { typography } from "../tokens/typography.js";
 import { text } from "./text.js";
 const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: "grapheme" });
 function normalizeInline(value) {
@@ -103,26 +105,67 @@ function splitWords(value) {
     }
     return words;
 }
-function wrapWords(value, width) {
-    const words = splitWords(value);
+function leadingWhitespaceWidth(value) {
+    let index = 0;
+    while (index < value.length && isWhitespace(value[index])) {
+        index += 1;
+    }
+    return { prefix: value.slice(0, index), rest: value.slice(index) };
+}
+function takeVisiblePrefix(value, width) {
+    let visible = 0;
+    let index = 0;
+    while (index < value.length) {
+        const controlEnd = readControlSequence(value, index);
+        if (controlEnd !== undefined) {
+            index = controlEnd;
+            continue;
+        }
+        const segment = graphemeSegmenter.segment(value.slice(index))[Symbol.iterator]().next().value;
+        const cluster = segment?.segment ?? value[index] ?? "";
+        const nextWidth = clusterWidth(cluster);
+        if (visible > 0 && visible + nextWidth > width) {
+            break;
+        }
+        visible += nextWidth;
+        index += cluster.length || 1;
+    }
+    return { prefix: value.slice(0, index), rest: value.slice(index) };
+}
+function wrapWords(value, width, continuationWidth = width) {
+    // Preserve leading whitespace only on the first wrapped line so hang-indented
+    // left cells (command depth prefixes) do not re-indent every continuation.
+    const { prefix, rest } = leadingWhitespaceWidth(value);
+    const prefixWidth = visibleWidth(prefix);
+    const firstContentWidth = Math.max(1, width - prefixWidth);
+    const words = splitWords(rest);
     if (words.length === 0) {
-        return [""];
+        return [prefix];
     }
     const lines = [];
     let line = "";
+    let isFirstLine = true;
     for (const word of words) {
-        if (!line) {
-            line = word;
-            continue;
-        }
-        if (visibleWidth(line) + 1 + visibleWidth(word) <= width) {
+        const limit = isFirstLine ? firstContentWidth : continuationWidth;
+        if (line && visibleWidth(line) + 1 + visibleWidth(word) <= limit) {
             line += ` ${word}`;
             continue;
         }
-        lines.push(line);
-        line = word;
+        if (line) {
+            lines.push(isFirstLine ? `${prefix}${line}` : line);
+            isFirstLine = false;
+            line = "";
+        }
+        let remaining = word;
+        while (visibleWidth(remaining) > (isFirstLine ? firstContentWidth : continuationWidth)) {
+            const chunk = takeVisiblePrefix(remaining, isFirstLine ? firstContentWidth : continuationWidth);
+            lines.push(isFirstLine ? `${prefix}${chunk.prefix}` : chunk.prefix);
+            isFirstLine = false;
+            remaining = chunk.rest;
+        }
+        line = remaining;
     }
-    lines.push(line);
+    lines.push(isFirstLine ? `${prefix}${line}` : line);
     return lines;
 }
 function validateLayoutValue(value, name) {
@@ -150,29 +193,74 @@ export function formatColumns(opts) {
     validateLayoutValue(indent, "indent");
     const maxLeftContentWidth = Math.max(...rows.map((row) => visibleWidth(row.left)));
     const leftWidth = clamp(maxLeftContentWidth + gap, minLeftWidth, maxLeftWidth);
-    const rightWidth = Math.max(20, totalWidth - leftWidth - indent);
+    const rightWidth = Math.max(1, totalWidth - leftWidth - indent);
+    const leftWrapWidth = Math.max(1, totalWidth - indent);
     const firstIndent = " ".repeat(indent);
     const continuationIndent = " ".repeat(indent + leftWidth);
     return rows
         .flatMap((row) => {
+        const leftLeading = leadingWhitespaceWidth(row.left).prefix;
+        // Continuations hang under the left cell start (including depth prefix) by +2.
+        const leftHangIndent = " ".repeat(indent + visibleWidth(leftLeading) + 2);
+        const leftLines = wrapWords(row.left, leftWrapWidth, Math.max(1, totalWidth - visibleWidth(leftHangIndent)));
         if (row.right.length === 0) {
-            return [`${firstIndent}${row.left}`];
+            return leftLines.map((line, index) => index === 0 ? `${firstIndent}${line}` : `${leftHangIndent}${line}`);
         }
         const rightLines = wrapWords(row.right, rightWidth);
-        if (visibleWidth(row.left) >= leftWidth) {
-            return [
-                `${firstIndent}${row.left}`,
-                ...rightLines.map((line) => `${continuationIndent}${line}`)
-            ];
+        const leftFitsInColumn = visibleWidth(row.left) < leftWidth;
+        if (leftFitsInColumn && leftLines.length === 1) {
+            const firstLine = `${firstIndent}${padEndVisible(leftLines[0] ?? "", leftWidth)}${rightLines[0]}`;
+            const continuationLines = rightLines
+                .slice(1)
+                .map((line) => `${continuationIndent}${line}`);
+            return [firstLine, ...continuationLines];
         }
-        const firstLine = `${firstIndent}${padEndVisible(row.left, leftWidth)}${rightLines[0]}`;
-        const continuationLines = rightLines
-            .slice(1)
-            .map((line) => `${continuationIndent}${line}`);
-        return [firstLine, ...continuationLines];
+        const renderedLeft = leftLines.map((line, index) => index === 0 ? `${firstIndent}${line}` : `${leftHangIndent}${line}`);
+        const renderedRight = rightLines.map((line) => `${continuationIndent}${line}`);
+        return [...renderedLeft, ...renderedRight];
     })
         .join("\n");
 }
+export function styleHelpToken(token) {
+    switch (token.role) {
+        case "command":
+            return text.command(token.text);
+        case "argument":
+            return styleArgumentToken(token.text);
+        case "option":
+            return text.option(token.text);
+        case "dim":
+            return styleDim(token.text);
+        case "literal":
+            return token.text;
+    }
+}
+function styleArgumentToken(content) {
+    // Token text already includes angle brackets. text.argument re-wraps in markdown,
+    // so strip first there; terminal/json keep the full `<value>` form.
+    const format = resolveOutputFormat();
+    if (format === "markdown" && content.startsWith("<") && content.endsWith(">")) {
+        return text.argument(content.slice(1, -1));
+    }
+    if (format === "json") {
+        return content;
+    }
+    return text.argument(content);
+}
+function styleDim(content) {
+    // Structural brackets stay unstyled in markdown/json; italicizing them as muted is wrong.
+    const format = resolveOutputFormat();
+    if (format === "json" || format === "markdown") {
+        return content;
+    }
+    return typography.dim(content);
+}
+export function joinHelpTokens(tokens) {
+    return tokens.map((token) => token.text).join("");
+}
+export function renderHelpTokens(tokens) {
+    return tokens.map((token) => styleHelpToken(token)).join("");
+}
 export function formatCommand(name, description) {
     return formatColumns({
         rows: [{ left: text.command(name), right: description }]
@@ -189,16 +277,24 @@ export function formatOption(flags, description) {
 }
 export function formatCommandList(commands) {
     return formatColumns({
-        rows: commands.map((cmd) => ({
-            left: text.command(cmd.name),
-            right: cmd.description
-        }))
+        rows: commands.map((cmd) => {
+            const depthPrefix = " ".repeat((cmd.depth ?? 0) * 2);
+            const styledName = cmd.nameTokens !== undefined && cmd.nameTokens.length > 0
+                ? renderHelpTokens(cmd.nameTokens)
+                : text.command(cmd.name);
+            return {
+                left: `${depthPrefix}${styledName}`,
+                right: cmd.description
+            };
+        })
     });
 }
 export function formatOptionList(options) {
     return formatColumns({
         rows: options.map((opt) => ({
-            left: text.option(opt.flags),
+            left: opt.flagTokens !== undefined && opt.flagTokens.length > 0
+                ? renderHelpTokens(opt.flagTokens)
+                : text.option(opt.flags),
             right: opt.description
         }))
     });
@@ -209,5 +305,8 @@ export const helpFormatter = {
     formatUsage,
     formatOption,
     formatCommandList,
-    formatOptionList
+    formatOptionList,
+    styleHelpToken,
+    joinHelpTokens,
+    renderHelpTokens
 };

package/node_modules/toolcraft-design/dist/components/index.d.ts

@@ -4,8 +4,8 @@ export type { Color } from "./color.js";
 export { symbols } from "./symbols.js";
 export { createLogger, logger } from "./logger.js";
 export type { LoggerOutput } from "./logger.js";
-export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./help-formatter.js";
-export type { CommandInfo, OptionInfo, FormatColumnsOptions } from "./help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList, styleHelpToken, joinHelpTokens, renderHelpTokens } from "./help-formatter.js";
+export type { CommandInfo, OptionInfo, FormatColumnsOptions, HelpToken, HelpTokenRole } from "./help-formatter.js";
 export { formatCommandNotFound } from "./command-errors.js";
 export { formatCommandNotFoundPanel } from "./command-errors.js";
 export { renderTable } from "./table.js";

package/node_modules/toolcraft-design/dist/components/index.js

@@ -2,7 +2,7 @@ export { text } from "./text.js";
 export { color } from "./color.js";
 export { symbols } from "./symbols.js";
 export { createLogger, logger } from "./logger.js";
-export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList, styleHelpToken, joinHelpTokens, renderHelpTokens } from "./help-formatter.js";
 export { formatCommandNotFound } from "./command-errors.js";
 export { formatCommandNotFoundPanel } from "./command-errors.js";
 export { renderTable } from "./table.js";

package/node_modules/toolcraft-design/dist/help-formatter.d.ts

@@ -1,2 +1,2 @@
-export { helpFormatter } from "./components/help-formatter.js";
-export type { CommandInfo, FormatColumnsOptions, OptionInfo } from "./components/help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList, styleHelpToken, joinHelpTokens, renderHelpTokens } from "./components/help-formatter.js";
+export type { CommandInfo, FormatColumnsOptions, OptionInfo, HelpToken, HelpTokenRole } from "./components/help-formatter.js";

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

@@ -1 +1 @@
-export { helpFormatter } from "./components/help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList, styleHelpToken, joinHelpTokens, renderHelpTokens } from "./components/help-formatter.js";

package/node_modules/toolcraft-design/dist/index.d.ts

@@ -12,9 +12,9 @@ export type { Color } from "./components/color.js";
 export { symbols } from "./components/symbols.js";
 export { createLogger, logger } from "./components/logger.js";
 export type { LoggerOutput } from "./components/logger.js";
-export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./components/help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList, styleHelpToken, joinHelpTokens, renderHelpTokens } from "./components/help-formatter.js";
 export * as helpFormatterPlain from "./components/help-formatter-plain.js";
-export type { CommandInfo, OptionInfo, FormatColumnsOptions } from "./components/help-formatter.js";
+export type { CommandInfo, OptionInfo, FormatColumnsOptions, HelpToken, HelpTokenRole } from "./components/help-formatter.js";
 export { formatCommandNotFound } from "./components/command-errors.js";
 export { formatCommandNotFoundPanel } from "./components/command-errors.js";
 export { renderTable } from "./components/table.js";

package/node_modules/toolcraft-design/dist/index.js

@@ -10,7 +10,7 @@ export { text } from "./components/text.js";
 export { color } from "./components/color.js";
 export { symbols } from "./components/symbols.js";
 export { createLogger, logger } from "./components/logger.js";
-export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList } from "./components/help-formatter.js";
+export { helpFormatter, formatColumns, formatCommand, formatUsage, formatOption, formatCommandList, formatOptionList, styleHelpToken, joinHelpTokens, renderHelpTokens } from "./components/help-formatter.js";
 export * as helpFormatterPlain from "./components/help-formatter-plain.js";
 export { formatCommandNotFound } from "./components/command-errors.js";
 export { formatCommandNotFoundPanel } from "./components/command-errors.js";

package/node_modules/toolcraft-schema/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft-schema",
-  "version": "0.0.129",
+  "version": "0.0.131",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "toolcraft",
-  "version": "0.0.129",
+  "version": "0.0.131",
   "license": "MIT",
   "type": "module",
   "main": "dist/index.js",
@@ -153,7 +153,7 @@
     "yaml"
   ],
   "optionalDependencies": {
-    "toolcraft-schema": "0.0.129",
+    "toolcraft-schema": "0.0.131",
     "toolcraft-design": "*",
     "@poe-code/frontmatter": "*",
     "@poe-code/agent-mcp-config": "*",