@vmz/commander 0.3.6 → 0.3.8

package/README.md

@@ -1,67 +1,94 @@
-# `@vmz/commander`
-
-i18n-first TypeScript CLI framework under the `@vmz` scope. **Not** bound to `@vmz/vmz`.
-
-- Fluent registration; command / option second args are **message ids**
-- **Help is derived** from the command tree — do not paste Usage walls into catalogs
-- **Locales directory loading**: `locales.json` + `<locale>/*.json` → flatten → `LocalizePlugin`
-- Framework chrome/err ids are `commander.*` with tiny English fallbacks (products may override)
-- Interactive help uses a small ANSI theme for headings, commands, options, and errors; `NO_COLOR` disables it, `FORCE_COLOR` enables it outside a TTY
-- **No product language packs** in this package
-
-## Quick start
-
-```ts
-import { createCli } from '@vmz/commander';
-
-const cli = createCli('my-cli')
-  .locales(new URL('./locales', import.meta.url).pathname) // or absolute path
-  .intro('cli.intro')
-  .command('build', 'cli.cmd.build')
-  .option('--out-dir, -o <dir>', 'cli.opt.out-dir')
-  .action(async (options) => {
-    /* options._ positionals; options['out-dir'] … */
-  });
-
-await cli.parse(process.argv);
-```
-
-Locales layout (any product):
-
-```text
-<localesRoot>/
-  locales.json          # { defaultLocale, locales: [{ id }], fallback? }
-  en-US/*.json          # flat or nested → dotted ids
-  zh-CN/*.json          # optional
-```
-
-`.locales(root)` also registers root `--locale <id>` (peeled before the command). Later `.use(plugin)` overrides the locales plugin.
-
-## API surface
-
-| API | Role |
-|-----|------|
-| `createCli(name)` | Program name; help `{name}` |
-| `.command` / `.option` / `.action` / `.passthrough` | Command tree |
-| `.intro(id)` | Short banner only |
-| `.locales(root)` / `.use(plugin)` / `.catalog(loader)` | Localization (later `.use` wins) |
-| `.option` on CLI | Global flags (merged into action options) |
-| `.onDiagnostic(handler)` | Route structured action failures to a product-owned renderer |
-| `loadLocalesManifest` / `loadCatalog` / `flattenCatalog` | Filesystem catalog helpers |
-| `createLocalizeFromLocales` | Build a `LocalizePlugin` from a root |
-| `assertCatalogCoverage(cli, catalog)` | Dev/CI: registered helpIds must exist |
-| `COMMANDER_FALLBACK_EN_US` | Minimal `commander.ui.*` / `commander.err.*` / `commander.opt.locale` |
-
-`t` resolution: product catalog → `commander` English fallback → `{{id}}`.
-
-Action failures may throw a language-neutral diagnostic object with `code`, `args`, `path`, `span`, `severity`, and optional legacy `message`. The configured handler receives the structured row and resolved locale context. Without a handler, commander prints the legacy message or code. Plain `Error` exceptions are wrapped as `commander::action_failed` during migration. Commander does not own diagnostic formatting; products should connect `@vmz/diagnostic`.
-
-## Layering
-
-```text
-@vmz/commander  = CLI tree + locales loader + commander.* chrome
-@vmz/vmz        = product bin + command registration + locales/ content
-@vmz/diagnostic = diagnostic layout (caller injects catalog / t)
-```
-
-Do **not** create a separate `@vmz/i18n` package for official product strings.
+# `@vmz/commander`
+
+i18n-first TypeScript CLI framework under the `@vmz` scope. **Not** bound to `@vmz/vmz`.
+
+- Fluent registration; command / option second args are **message ids**
+- **Help is derived** from the command tree — do not paste Usage walls into catalogs
+- **Locales directory loading**: `locales.json` + `<locale>/*.json` → flatten → `LocalizePlugin`
+- Framework chrome/err ids are `commander.*` with tiny English fallbacks (products may override)
+- Interactive help uses a small ANSI theme for headings, commands, options, and errors; `NO_COLOR` disables it, `FORCE_COLOR` enables it outside a TTY
+- **No product language packs** in this package
+
+## Quick start
+
+```ts
+import { createCli } from '@vmz/commander';
+
+const cli = createCli('my-cli')
+  .locales(new URL('./locales', import.meta.url).pathname) // or absolute path
+  .intro('cli.intro')
+  .command('build', 'cli.cmd.build')
+  .option('--out-dir, -o <dir>', 'cli.opt.out-dir')
+  .action(async (options) => {
+    /* options._ positionals; options['out-dir'] … */
+  });
+
+await cli.parse(process.argv);
+```
+
+Locales layout (any product):
+
+```text
+<localesRoot>/
+  locales.json          # { defaultLocale, locales: [{ id }], fallback? }
+  en-US/*.json          # flat or nested → dotted ids
+  zh-CN/*.json          # optional
+```
+
+`.locales(root)` also registers root `--locale <id>` (peeled before the command). Later `.use(plugin)` overrides the locales plugin.
+
+## API surface
+
+| API | Role |
+|-----|------|
+| `createCli(name)` | Program name; help `{name}` |
+| `.command` / `.option` / `.action` / `.actionCtx` / `.passthrough` | Command tree |
+| `.intro(id)` | Short banner only |
+| `.locales(root)` / `.use(plugin)` / `.catalog(loader)` | Localization (later `.use` wins) |
+| `.option` on CLI | Global flags (merged into action options) |
+| `.onDiagnostic(handler)` | Route structured action failures to a product-owned renderer |
+| `loadLocalesManifest` / `loadCatalog` / `flattenCatalog` | Filesystem catalog helpers |
+| `createLocalizeFromLocales` | Build a `LocalizePlugin` from a root |
+| `assertCatalogCoverage(cli, catalog)` | Dev/CI: registered helpIds must exist |
+| `COMMANDER_FALLBACK_EN_US` | Minimal `commander.ui.*` / `commander.err.*` / `commander.opt.locale` |
+
+`t` resolution: product catalog → `commander` English fallback → `{{id}}`.
+
+## Option config
+
+`.option(rawName, helpId, config?)` accepts runtime constraints in addition to the `<value>` / `[value]` / `...` syntax:
+
+| Field | Behavior |
+|-------|----------|
+| `required` | Missing value before the action → structured parse error, exit code 2 |
+| `enum` | Value outside the set → structured parse error, exit code 2 (repeatable values are checked per item) |
+| `default` | Filled into `options[key]` when omitted (boolean, string, or array) |
+| `coerce` | Runs on the supplied raw value, thrown errors become exit code 2 |
+| `hidden` | Omitted from help, still parseable |
+| `example` | Rendered after the option in help |
+| `deprecated` | Annotated in help and emits a `commander::option_deprecated` warning when used |
+| `group` | Rendered under its own help section while ungrouped options keep the default section |
+
+Validation happens before the action handler runs. Failures carry stable `commander::*` codes plus structured `args`.
+
+## Command boundaries
+
+- `.actionCtx(handler)` receives `(options, args, ctx)`, with `ctx.help`, `ctx.stdout`, `ctx.stderr`, `ctx.fail`, `ctx.warn`, and `ctx.note`. `.action` and `.actionCtx` are mutually exclusive.
+- `--` ends option parsing. Every token after it is a raw positional and is merged into `options._` — options and help markers in the tail are never reinterpreted.
+- `--help` binds to the deepest command path reached before the marker, so `demo document check --help` and `help document check` show the same node.
+
+## Diagnostics
+
+Action failures may throw a language-neutral diagnostic object with `code`, `args`, `path`, `span`, `severity`, and optional legacy `message`. The configured handler receives the structured row and resolved locale context. Without a handler, commander renders the `code` through `t` with `args` interpolation, falling back to a real business message or the code. Plain `Error` exceptions are wrapped as `commander::action_failed` during migration. Commander does not own diagnostic formatting: products should connect `@vmz/diagnostic`.
+
+Framework hints use `commander.ui.hint.available_options` (`{command}`) and `commander.ui.hint.did_you_mean` (`{suggest}`), so product catalogs can translate them. The available-options hint names the full executable command (`demo run --help`) and falls back to the root command for unknown commands.
+
+## Layering
+
+```text
+@vmz/commander  = CLI tree + locales loader + commander.* chrome
+@vmz/vmz        = product bin + command registration + locales/ content
+@vmz/diagnostic = diagnostic layout (caller injects catalog / t)
+```
+
+Do **not** create a separate `@vmz/i18n` package for official product strings.

package/dist/index.d.ts

@@ -5,17 +5,19 @@
  * pluggable Localize plugin or `.locales(root)`. Framework chrome/err ids are
  * `commander.*` with tiny English fallbacks — no product language packs here.
  */
-export type { CatalogLoader, CommandDiagnostic, DiagnosticContext, DiagnosticHandler, LocaleCatalog, LocalizePlugin } from './types.js';
+export type { CatalogLoader, CommandContext, CommandDiagnostic, DiagnosticContext, DiagnosticHandler, LocaleCatalog, LocalizePlugin, OptionConfig } from './types.js';
 export { CliError } from './types.js';
 export { COMMANDER_FALLBACK_EN_US, clearLocalesCache, createLocalizeFromLocales, flattenCatalog, loadCatalog, loadLocalesManifest, resolveLocale, translate, translateWithFallback, } from './locales.js';
 export type { CreateLocalizeFromLocalesOptions, LocalesManifest } from './locales.js';
-import type { CatalogLoader, DiagnosticHandler, LocaleCatalog, LocalizePlugin } from './types.js';
+import type { CatalogLoader, CommandContext, DiagnosticHandler, LocaleCatalog, LocalizePlugin, OptionConfig } from './types.js';
 /** Options bag passed to actions (`_` = positionals). */
 export type ParsedOptions = Record<string, string | boolean | string[]> & {
     _: string[];
 };
-/** Command action after argv is parsed. */
+/** Command action after argv is parsed (legacy API — no context). */
 export type ActionHandler = (options: ParsedOptions, ...args: string[]) => void | number | Promise<void | number>;
+/** Command action with full framework context (preferred API — additive, no break). */
+export type ActionCtxHandler = (options: ParsedOptions, args: string[], ctx: CommandContext) => void | number | Promise<void | number>;
 /** Registered option (structure only). */
 export type OptionDef = {
     rawName: string;
@@ -30,6 +32,8 @@ export type OptionDef = {
     optionalValue: boolean;
     /** True when the option may repeat (`--dirty <path>...` ⇒ `string[]`). */
     repeatable: boolean;
+    /** Runtime constraints (enum / required / default / coerce / deprecated). */
+    config?: OptionConfig;
 };
 /** Registered command node. */
 export type CommandDef = {
@@ -38,14 +42,20 @@ export type CommandDef = {
     /** Match tokens from `rawName` split on `|`. */
     names: string[];
     options: OptionDef[];
+    /** Legacy action handler (no ctx). */
     action?: ActionHandler;
+    /** Phase 3 action handler (with ctx — preferred). */
+    actionCtx?: ActionCtxHandler;
     children: CommandDef[];
     /** If true, do not parse options; remaining argv is positionals / raw rest. */
     passthrough: boolean;
 };
 export interface Command {
-    option(rawName: string, helpId: string): this;
+    option(rawName: string, helpId: string, config?: OptionConfig): this;
+    /** Legacy API — handler receives `(options, ...args)` without ctx. */
     action(handler: ActionHandler): this;
+    /** Phase 3 API — handler receives `(options, args[], ctx)` with full command context. */
+    actionCtx(handler: ActionCtxHandler): this;
     command(rawName: string, helpId: string): Command;
     /** Leave remaining argv unparsed (for nested domain CLIs). */
     passthrough(): this;

package/dist/index.js

@@ -25,14 +25,127 @@ function colorEnabled() {
         return false;
     if (process.env.FORCE_COLOR && process.env.FORCE_COLOR !== '0')
         return true;
+    // Node.js reports `isTTY` as `undefined` in many Windows shells (PowerShell,
+    // Git Bash) even when the host (Windows Terminal, ConEmu, mintty) does emit
+    // ANSI. `tty.isatty(fd)` is reliable on every platform because it asks the
+    // OS directly. On top of that we also check well-known Windows-terminal
+    // env vars (`WT_SESSION`, `ConEmuANSI`, `ANSICON`) that legacy clients use
+    // to declare ANSI support. A `TERM=dumb` redirect still falls through.
+    const tty = tryImportTty();
+    if (tty && tty.isatty(process.stdout?.fd ?? 0))
+        return true;
+    if (tty && tty.isatty(process.stderr?.fd ?? 2))
+        return true;
+    if (process.env.WT_SESSION)
+        return true;
+    if (process.env.ConEmuANSI === 'ON')
+        return true;
+    if (process.env.ANSICON)
+        return true;
+    if (process.env.TERM && process.env.TERM !== 'dumb')
+        return true;
     return Boolean(process.stdout?.isTTY || process.stderr?.isTTY);
 }
+/** Dynamically resolve Node's `node:tty` module — safe in non-Node runners. */
+function tryImportTty() {
+    try {
+        // eslint-disable-next-line @typescript-eslint/no-require-imports
+        return require('node:tty');
+    }
+    catch {
+        return undefined;
+    }
+}
 function paint(value, ...colors) {
     return colorEnabled() && colors.length ? `${colors.map((color) => ANSI[color]).join('')}${value}${ANSI_RESET}` : value;
 }
 function errorText(value) {
     return paint(value, 'bold', 'red');
 }
+/**
+ * Render one help section (header + padded table).
+ *
+ * Both the root help and the command-node help share the same 3-line pattern:
+ * push section header (`paint(header, 'bold', 'blue')`), then a loop of
+ * `  ${paint(label.padEnd(colWidth), color)} ${t(helpId)}`.
+ *
+ * Returns `lines[]` so callers can spread-append without trailing-empty concerns.
+ */
+function renderHelpSectionWithHeader(t, header, rows, color, colWidth = 28) {
+    if (!rows.length)
+        return [];
+    const out = [paint(header, 'bold', 'blue')];
+    for (const r of rows) {
+        const label = r.suffix ? `${r.rawName} ${r.suffix}` : r.rawName;
+        out.push(`  ${paint(label.padEnd(colWidth), color)} ${t(r.helpId)}`);
+    }
+    return out;
+}
+function renderHelpSection(t, headerId, rows, color, colWidth = 28) {
+    return renderHelpSectionWithHeader(t, t(headerId), rows, color, colWidth);
+}
+/** Parse/validation diagnostics that get the framework-level "available options" hint. */
+const HINT_CODES = new Set([
+    'commander::unknown_command',
+    'commander::unknown_option',
+    'commander::missing_option_value',
+    'commander::parse_failed',
+    'commander::missing_required_option',
+    'commander::option_not_in_enum',
+    'commander::option_coerce_failed',
+]);
+/** Resolve a catalog id, treating `{{id}}` (unresolved) as absent. */
+function localizedOrId(t, id, args) {
+    const value = t(id, args);
+    return value === `{{${id}}}` ? '' : value;
+}
+/** Localized suffix appended to one option row in help. */
+function optionSuffix(t, def) {
+    const config = def.config;
+    if (!config)
+        return '';
+    const parts = [];
+    if (config.example)
+        parts.push(t('commander.ui.option_example', { example: config.example }));
+    if (config.deprecated) {
+        const label = typeof config.deprecated === 'string' && config.deprecated
+            ? (localizedOrId(t, config.deprecated) || config.deprecated)
+            : t('commander.ui.deprecated');
+        if (label)
+            parts.push(label);
+    }
+    return parts.join(' ');
+}
+/**
+ * Render option help, splitting grouped options into their own sections.
+ *
+ * Options without `group` keep the default `Options:` section. `hidden` options
+ * are omitted from help but remain parseable.
+ */
+function renderOptionSections(t, options, color) {
+    const visible = options.filter((o) => !o.config?.hidden);
+    const ungrouped = [];
+    const grouped = new Map();
+    for (const option of visible) {
+        const group = option.config?.group;
+        if (!group) {
+            ungrouped.push(option);
+            continue;
+        }
+        const list = grouped.get(group) ?? [];
+        list.push(option);
+        grouped.set(group, list);
+    }
+    const rows = (list) => list.map((o) => ({ rawName: o.rawName, helpId: o.helpId, suffix: optionSuffix(t, o) }));
+    const out = renderHelpSection(t, 'commander.ui.options', rows(ungrouped), color);
+    for (const [group, list] of grouped) {
+        const header = localizedOrId(t, group) || group;
+        if (out.length)
+            out.push('');
+        out.push(...renderHelpSectionWithHeader(t, header, rows(list), color));
+    }
+    return out;
+}
 class CommandBuilder {
     def;
     constructor(rawName, helpId) {
@@ -46,15 +159,26 @@ class CommandBuilder {
             passthrough: false,
         };
     }
-    option(rawName, helpId) {
+    option(rawName, helpId, config) {
         assertHelpId(helpId, 'option');
-        this.def.options.push(parseOptionDef(rawName, helpId));
+        const def = parseOptionDef(rawName, helpId);
+        if (config)
+            def.config = config;
+        this.def.options.push(def);
         return this;
     }
     action(handler) {
+        if (this.def.actionCtx)
+            throw CliError.configError('commander::config::action_conflict', { detail: 'Cannot set both .action() and .actionCtx()' });
         this.def.action = handler;
         return this;
     }
+    actionCtx(handler) {
+        if (this.def.action)
+            throw CliError.configError('commander::config::action_conflict', { detail: 'Cannot set both .action() and .actionCtx()' });
+        this.def.actionCtx = handler;
+        return this;
+    }
     passthrough() {
         this.def.passthrough = true;
         return this;
@@ -158,7 +282,11 @@ class CliBuilder {
     }
     async parse(argvInput = process.argv) {
         const argv0 = normalizeArgv(argvInput);
-        const { options: globalOpts, rest: argv } = peelKnownOptions(argv0, this.rootOptions);
+        const peeled = peelKnownOptions(argv0, this.rootOptions);
+        const globalOpts = peeled.options;
+        // A leading separator at program level only marks the end of global
+        // options. Keep the following command token dispatchable.
+        const argv = peeled.rest[0] === '--' ? peeled.rest.slice(1) : peeled.rest;
         let localize = this.localize;
         if (this.localesRoot) {
             const localeFlag = typeof globalOpts.locale === 'string' && globalOpts.locale ? globalOpts.locale : undefined;
@@ -178,32 +306,84 @@ class CliBuilder {
             locale: localize.resolveLocale?.({ argv: argv0, env: process.env }) ?? 'en-US',
             t,
         };
-        if (argv.length === 0 || isHelpToken(argv[0])) {
+        // `help <cmd> ...` 路由：把 help 后面的 token 当命令路径查找帮助
+        if (argv.length && argv[0] === 'help') {
+            const pathTokens = argv.slice(1);
+            return this.routeHelp(pathTokens, t, diagnosticContext);
+        }
+        if (argv.length === 0 || argv.every(isHelpToken)) {
             console.log(this.formatRootHelp(t));
             return 0;
         }
         const cmdToken = argv[0];
         const matched = this.roots.find((c) => c.def.names.includes(cmdToken));
         if (!matched) {
-            return this.emitAndHelp({ code: 'commander::unknown_command', severity: 'error', args: { cmd: cmdToken } }, diagnosticContext, t, this.formatRootHelp(t), 2);
+            // 未知命令：加上 suggestion
+            const names = this.roots.flatMap((r) => r.def.names);
+            const suggest = closestMatch(cmdToken, names);
+            this.emitDiagnostic({
+                code: 'commander::unknown_command',
+                severity: 'error',
+                args: suggest ? { cmd: cmdToken, suggest } : { cmd: cmdToken },
+            }, diagnosticContext, t);
+            return 2;
         }
         return await this.dispatch(matched.def, argv.slice(1), t, [cmdToken], globalOpts, diagnosticContext);
     }
-    /** Emit a diagnostic through `onDiagnostic` when registered, else console.error. */
+    /** 路由 `help <cmd> [subcmd] ...` 到对应命令的帮助文本。 */
+    routeHelp(pathTokens, t, _ctx) {
+        if (!pathTokens.length) {
+            console.log(this.formatRootHelp(t));
+            return 0;
+        }
+        let pool = this.roots.map((r) => r.def);
+        let matched;
+        let consumed = 0;
+        for (const tok of pathTokens) {
+            const found = pool?.find((c) => c.names.includes(tok));
+            if (!found)
+                break;
+            matched = found;
+            consumed += 1;
+            pool = found.children;
+        }
+        if (!matched) {
+            // 路径里没有一个有效命令 → 仍显示根帮助
+            console.log(this.formatRootHelp(t));
+            return 0;
+        }
+        const path = pathTokens.slice(0, consumed);
+        console.log(formatCommandHelp(this.name, matched, t, path, this.rootOptions));
+        return 0;
+    }
+    /** Emit a diagnostic through `onDiagnostic` when registered, else console.error with a short hint. */
     emitDiagnostic(diag, ctx, t) {
         if (this.diagnosticHandler) {
             this.diagnosticHandler(diag, ctx);
         }
         else {
-            const msg = diag.message ?? (diag.code ? t(diag.code, diag.args) : '');
-            console.error(errorText(msg || diag.code || String(diag)));
+            const code = diag.code ?? '';
+            // Catalog template wins so structured args stay interpolated (`--oops`).
+            // A business message is only a fallback for codes without a template.
+            const fromCatalog = code ? localizedOrId(t, code, diag.args) : '';
+            const businessMessage = diag.message && diag.message !== code ? diag.message : '';
+            const msg = fromCatalog || businessMessage || code || String(diag);
+            console.error(errorText(msg));
+        }
+        // hint 和 suggestion 是框架级 UI，无论 handler 是否存在都统一追加
+        if (diag.code && HINT_CODES.has(diag.code)) {
+            // unknown_command: hint 指向根命令（因为命令不存在）
+            // 其他: hint 指向完整的可执行命令路径
+            const cmd = typeof diag.args?.cmd === 'string' ? diag.args.cmd.trim() : '';
+            const hintTarget = diag.code === 'commander::unknown_command' || !cmd
+                ? this.name
+                : `${this.name} ${cmd}`;
+            console.error(paint(t('commander.ui.hint.available_options', { command: hintTarget }), 'dim'));
+        }
+        const suggest = typeof diag.args?.suggest === 'string' ? diag.args.suggest : '';
+        if (suggest) {
+            console.error(paint(t('commander.ui.hint.did_you_mean', { suggest }), 'dim'));
         }
-    }
-    /** Emit diagnostic, show help text, return exit code. Shorthand for parse/dispatch error paths. */
-    emitAndHelp(diag, ctx, t, helpText, exitCode) {
-        this.emitDiagnostic(diag, ctx, t);
-        console.log(helpText);
-        return exitCode;
     }
     /** Derived root help: optional intro + commands/options from the registration tree. */
     formatRootHelp(t) {
@@ -211,51 +391,81 @@ class CliBuilder {
         if (this.introId) {
             lines.push(t(this.introId), '');
         }
-        lines.push(paint(t('commander.ui.usage', { name: this.name }), 'bold', 'cyan'), '', paint(t('commander.ui.commands'), 'bold', 'blue'));
-        for (const c of this.roots) {
-            lines.push(`  ${paint(c.def.rawName.padEnd(28), 'green')} ${t(c.def.helpId)}`);
-        }
+        lines.push(paint(t('commander.ui.usage', { name: this.name }), 'bold', 'cyan'));
+        lines.push('');
+        lines.push(...renderHelpSection(t, 'commander.ui.commands', this.roots.map((c) => ({ rawName: c.def.rawName, helpId: c.def.helpId })), 'green'));
         const opts = [
             ...this.rootOptions,
             ...collectRootOptions(this.roots.map((c) => c.def)).filter((o) => !this.rootOptions.some((r) => r.key === o.key)),
         ];
-        if (opts.length) {
-            lines.push('', paint(t('commander.ui.options'), 'bold', 'blue'));
-            for (const o of opts) {
-                lines.push(`  ${paint(o.rawName.padEnd(28), 'yellow')} ${t(o.helpId)}`);
-            }
+        const optionSection = renderOptionSections(t, opts, 'yellow');
+        if (optionSection.length) {
+            lines.push('');
+            lines.push(...optionSection);
         }
         return lines.join('\n');
     }
     async dispatch(def, rest, t, path, globalOpts, diagnosticContext) {
-        if (rest.length && isHelpToken(rest[0])) {
-            console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions));
-            return 0;
+        // `--` ends option parsing. Keep head (options + command tokens) separate
+        // from tail (raw positionals) before help scanning or option parsing.
+        const separatorAt = rest.indexOf('--');
+        const head = separatorAt === -1 ? rest : rest.slice(0, separatorAt);
+        const tail = separatorAt === -1 ? [] : rest.slice(separatorAt + 1);
+        // Resolve the deepest command node before interpreting help markers, so
+        // `demo document check --help` binds to `check` instead of `document`.
+        let target = def;
+        const targetPath = path.slice();
+        const remaining = head.slice();
+        while (target.children.length && remaining.length) {
+            const token = remaining[0];
+            if (token.startsWith('-') || isHelpToken(token))
+                break;
+            const child = target.children.find((c) => c.names.includes(token));
+            if (!child)
+                break;
+            target = child;
+            targetPath.push(token);
+            remaining.shift();
         }
-        if (def.children.length && rest.length && !rest[0].startsWith('-')) {
-            const childTok = rest[0];
-            const child = def.children.find((c) => c.names.includes(childTok));
-            if (child) {
-                return await this.dispatch(child, rest.slice(1), t, [...path, childTok], globalOpts, diagnosticContext);
-            }
-            if (!def.action) {
-                return this.emitAndHelp({ code: 'commander::unknown_command', severity: 'error', args: { cmd: [...path, childTok].join(' ') } }, diagnosticContext, t, formatCommandHelp(this.name, def, t, path, this.rootOptions), 2);
-            }
+        // 扫描 --help / -h（只扫命令路径之后的 head，`--` 之后的 tail 不参与）
+        if (hasHelpToken(remaining)) {
+            console.log(formatCommandHelp(this.name, target, t, targetPath, this.rootOptions));
+            return 0;
         }
-        if (!def.action) {
-            if (rest.length) {
-                return this.emitAndHelp({ code: 'commander::unknown_command', severity: 'error', args: { cmd: [...path, ...rest].join(' ') } }, diagnosticContext, t, formatCommandHelp(this.name, def, t, path, this.rootOptions), 2);
+        if (!target.action && !target.actionCtx) {
+            if (remaining.length || tail.length) {
+                const childNames = target.children.flatMap((c) => c.names);
+                const unknownToken = remaining[0];
+                const suggest = unknownToken && !unknownToken.startsWith('-')
+                    ? closestMatch(unknownToken, childNames)
+                    : '';
+                const cmd = [...targetPath, ...remaining, ...tail].join(' ');
+                this.emitDiagnostic({
+                    code: 'commander::unknown_command',
+                    severity: 'error',
+                    args: suggest ? { cmd, suggest } : { cmd },
+                }, diagnosticContext, t);
+                return 2;
             }
-            console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions));
+            console.log(formatCommandHelp(this.name, target, t, targetPath, this.rootOptions));
             return 0;
         }
         let options;
+        let usedOptions = new Set();
         try {
-            options = def.passthrough ? { _: rest.slice() } : parseOptions(rest, def.options);
+            if (target.passthrough) {
+                options = { _: [...remaining, ...tail] };
+            }
+            else {
+                ({ options, used: usedOptions } = parseOptionsDetailed(remaining, target.options));
+                options._.push(...tail);
+            }
         }
         catch (err) {
             const cliErr = CliError.from(err, 'commander::parse_failed');
-            return this.emitAndHelp({ code: cliErr.code, severity: 'error', args: cliErr.args, message: cliErr.message }, diagnosticContext, t, formatCommandHelp(this.name, def, t, path, this.rootOptions), cliErr.exitCode);
+            const args = { ...(cliErr.args ?? {}), cmd: targetPath.join(' ') };
+            this.emitDiagnostic({ code: cliErr.code, severity: 'error', args, message: cliErr.message }, diagnosticContext, t);
+            return cliErr.exitCode;
         }
         for (const [k, v] of Object.entries(globalOpts)) {
             if (k === '_')
@@ -263,8 +473,29 @@ class CliBuilder {
             if (options[k] === undefined)
                 options[k] = v;
         }
+        for (const option of target.options) {
+            const deprecated = option.config?.deprecated;
+            if (!deprecated || !usedOptions.has(option))
+                continue;
+            const args = { option: option.key };
+            if (typeof deprecated === 'string' && deprecated) {
+                args.detail = localizedOrId(t, deprecated) || deprecated;
+            }
+            this.emitDiagnostic({ code: 'commander::option_deprecated', severity: 'warning', args }, diagnosticContext, t);
+        }
         try {
-            const result = await def.action(options, ...options._);
+            let result;
+            if (target.actionCtx) {
+                const ctx = this.buildCommandContext(target, targetPath, diagnosticContext.locale, t);
+                result = await target.actionCtx(options, options._, ctx);
+            }
+            else if (target.action) {
+                result = await target.action(options, ...options._);
+            }
+            else {
+                console.log(formatCommandHelp(this.name, target, t, targetPath, this.rootOptions));
+                return 0;
+            }
             if (typeof result === 'number')
                 return result;
             return 0;
@@ -272,26 +503,51 @@ class CliBuilder {
         catch (err) {
             const diagnostic = normalizeDiagnostic(err);
             this.emitDiagnostic(diagnostic, diagnosticContext, t);
+            // CliError.exitCode is POSIX-correct (2 for parse/validation, 1 for config/action)
+            if (err instanceof CliError)
+                return err.exitCode;
             return 1;
         }
     }
+    /** Build a CommandContext for .actionCtx() handlers. */
+    buildCommandContext(def, path, locale, t) {
+        const self = this;
+        const name = path.join(' ');
+        return {
+            commandPath: [this.name, ...path],
+            commandName: name,
+            locale,
+            t,
+            help: () => console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions)),
+            stderr: (...msgs) => { for (const m of msgs)
+                console.error(m); },
+            stdout: (...msgs) => { for (const m of msgs)
+                console.log(m); },
+            fail: (code, args) => {
+                self.emitDiagnostic({ code, severity: 'error', args: args ?? {}, message: args ? (args.message ?? '') : '' }, { locale, t }, t);
+                throw CliError.configError(code, args ?? {});
+            },
+            warn: (code, args) => {
+                self.emitDiagnostic({ code, severity: 'warning', args: args ?? {}, message: args ? (args.message ?? '') : '' }, { locale, t }, t);
+            },
+            note: (code, args) => {
+                self.emitDiagnostic({ code, severity: 'advice', args: args ?? {}, message: args ? (args.message ?? '') : '' }, { locale, t }, t);
+            },
+        };
+    }
 }
 /** Derive command help from one node (children + options). */
 export function formatCommandHelp(cliName, def, t, path, rootOptions = []) {
-    const lines = [paint(`${cliName} ${path.join(' ')}`, 'bold', 'cyan') + ` — ${t(def.helpId)}`, ''];
+    const lines = [paint(`${cliName} ${path.join(' ')}`, 'bold', 'cyan') + ` — ${t(def.helpId)}`];
     if (def.children.length) {
-        lines.push(paint(t('commander.ui.commands'), 'bold', 'blue'));
-        for (const c of def.children) {
-            lines.push(`  ${paint(c.rawName.padEnd(28), 'green')} ${t(c.helpId)}`);
-        }
         lines.push('');
+        lines.push(...renderHelpSection(t, 'commander.ui.commands', def.children.map((c) => ({ rawName: c.rawName, helpId: c.helpId })), 'green'));
     }
     const opts = [...rootOptions, ...def.options.filter((o) => !rootOptions.some((r) => r.key === o.key))];
-    if (opts.length) {
-        lines.push(paint(t('commander.ui.options'), 'bold', 'blue'));
-        for (const o of opts) {
-            lines.push(`  ${paint(o.rawName.padEnd(28), 'yellow')} ${t(o.helpId)}`);
-        }
+    const optionSection = renderOptionSections(t, opts, 'yellow');
+    if (optionSection.length) {
+        lines.push('');
+        lines.push(...optionSection);
     }
     return lines.join('\n').trimEnd();
 }
@@ -359,6 +615,8 @@ function parseArgvCore(argv, optionDefs, strict) {
     }
     const options = { _: [] };
     const rest = [];
+    /** Options explicitly supplied on the command line (defaults are not "used"). */
+    const used = new Set();
     const handleMissing = (flagName) => {
         if (strict) {
             throw CliError.parseError('commander::missing_option_value', { option: flagName });
@@ -376,30 +634,37 @@ function parseArgvCore(argv, optionDefs, strict) {
     for (let i = 0; i < argv.length; i++) {
         const a = argv[i];
         if (a === '--') {
-            rest.push(...argv.slice(i));
+            // Strict parsing consumes the separator. Permissive peeling must keep
+            // both `--` and its tail so dispatch can split head/tail and never
+            // interpret tail tokens as options or help markers.
+            if (strict)
+                rest.push(...argv.slice(i + 1));
+            else
+                rest.push('--', ...argv.slice(i + 1));
             break;
         }
+        // help token 不在这里 skip：让它进 rest，由上层 dispatch 的 hasHelpToken 路由
         if (a.startsWith('--')) {
             const eq = a.indexOf('=');
             const long = eq === -1 ? a.slice(2) : a.slice(2, eq);
             const def = byAlias.get(long);
             if (!def) {
-                if (!handleUnknown(`--${long}`))
+                if (!handleUnknown(a))
                     continue;
                 continue;
             }
             if (def.takesValue) {
                 if (eq !== -1) {
-                    assignOption(options, def, a.slice(eq + 1));
+                    assignOption(options, def, used, a.slice(eq + 1));
                 }
                 else {
                     const next = argv[i + 1];
                     if (next != null && !next.startsWith('-')) {
-                        assignOption(options, def, next);
+                        assignOption(options, def, used, next);
                         i += 1;
                     }
                     else if (def.optionalValue) {
-                        assignOption(options, def, true);
+                        assignOption(options, def, used, true);
                     }
                     else {
                         if (!handleMissing(`--${long}`))
@@ -409,26 +674,27 @@ function parseArgvCore(argv, optionDefs, strict) {
                 }
             }
             else {
-                assignOption(options, def, true);
+                assignOption(options, def, used, true);
             }
             continue;
         }
-        if (a.startsWith('-') && a.length === 2) {
+        // 短参数：-x 或 -xyz（多字符），只要不以 -- 开头且以 - 开头且长度 > 1 就认作短选项
+        if (a.startsWith('-') && a.length > 1) {
             const short = a.slice(1);
             const def = byAlias.get(short);
             if (!def) {
-                if (!handleUnknown(`-${short}`))
+                if (!handleUnknown(a))
                     continue;
                 continue;
             }
             if (def.takesValue) {
                 const next = argv[i + 1];
                 if (next != null && !next.startsWith('-')) {
-                    assignOption(options, def, next);
+                    assignOption(options, def, used, next);
                     i += 1;
                 }
                 else if (def.optionalValue) {
-                    assignOption(options, def, true);
+                    assignOption(options, def, used, true);
                 }
                 else {
                     if (!handleMissing(`-${short}`))
@@ -437,20 +703,21 @@ function parseArgvCore(argv, optionDefs, strict) {
                 }
             }
             else {
-                assignOption(options, def, true);
+                assignOption(options, def, used, true);
             }
             continue;
         }
         rest.push(a);
     }
-    return { options, rest };
+    return { options, rest, used };
 }
 /**
  * Consume known root options; leave unknown flags and positionals in `rest`
  * (unlike {@link parseOptions}, which throws on unknown options).
  */
 export function peelKnownOptions(argv, optionDefs) {
-    return parseArgvCore(argv, optionDefs, false);
+    const { options, rest } = parseArgvCore(argv, optionDefs, false);
+    return { options, rest };
 }
 /** Strip `node` + script when callers pass full `process.argv`. */
 export function normalizeArgv(argv) {
@@ -524,7 +791,9 @@ function normalizeDiagnostic(error) {
             };
         }
     }
-    return { severity: 'error', code: 'commander::action_failed', message: error instanceof Error ? error.message : String(error) };
+    const text = error instanceof Error ? error.message : String(error);
+    // 同时放 message 和 detail：不同产品 catalog 模板可能用 {message} 或 {detail}
+    return { severity: 'error', code: 'commander::action_failed', args: { message: text, detail: text }, message: text };
 }
 /**
  * Parse argv against registered options (strict mode).
@@ -534,11 +803,66 @@ function normalizeDiagnostic(error) {
  * Non-option tokens become positionals under `options._`.
  */
 export function parseOptions(argv, optionDefs) {
-    const { options, rest } = parseArgvCore(argv, optionDefs, true);
+    return parseOptionsDetailed(argv, optionDefs).options;
+}
+/** Strict parse plus which option defs were actually supplied (for deprecation warnings). */
+function parseOptionsDetailed(argv, optionDefs) {
+    const { options, rest, used } = parseArgvCore(argv, optionDefs, true);
     options._.push(...rest);
-    return options;
+    applyOptionConfig(options, optionDefs, used);
+    return { options, used };
 }
-function assignOption(out, def, value) {
+/**
+ * Apply `.option(..., config)` runtime constraints (default / required / enum / coerce).
+ *
+ * Runs before any action handler executes and throws {@link CliError.parseError}
+ * (exit code 2) so callers receive structured `code` + `args` diagnostics.
+ */
+function applyOptionConfig(options, optionDefs, used) {
+    for (const def of optionDefs) {
+        const config = def.config;
+        if (!config)
+            continue;
+        const provided = used.has(def);
+        if (!provided && config.default !== undefined) {
+            options[def.key] = Array.isArray(config.default) ? config.default.slice() : config.default;
+        }
+        const value = options[def.key];
+        if (config.required && value === undefined) {
+            throw CliError.parseError('commander::missing_required_option', { option: def.key });
+        }
+        if (value === undefined)
+            continue;
+        if (config.enum && provided) {
+            const values = Array.isArray(value) ? value : [value];
+            for (const item of values) {
+                if (typeof item !== 'string')
+                    continue;
+                if (!config.enum.includes(item)) {
+                    throw CliError.parseError('commander::option_not_in_enum', {
+                        option: def.key,
+                        value: item,
+                        allowed: config.enum.join(', '),
+                    });
+                }
+            }
+        }
+        if (config.coerce && provided) {
+            try {
+                options[def.key] = config.coerce(value);
+            }
+            catch (err) {
+                throw CliError.parseError('commander::option_coerce_failed', {
+                    option: def.key,
+                    value: Array.isArray(value) ? value.join(', ') : String(value),
+                    detail: err instanceof Error ? err.message : String(err),
+                });
+            }
+        }
+    }
+}
+function assignOption(out, def, used, value) {
+    used.add(def);
     if (def.repeatable) {
         const cur = out[def.key];
         const list = Array.isArray(cur) ? cur : [];
@@ -548,3 +872,58 @@ function assignOption(out, def, value) {
     }
     out[def.key] = value;
 }
+/** 扫描 argv 是否包含 help token（跳过 -- 后面的内容）。 */
+function hasHelpToken(argv) {
+    for (const tok of argv) {
+        if (tok === '--')
+            return false;
+        if (isHelpToken(tok))
+            return true;
+    }
+    return false;
+}
+/**
+ * 简单 Levenshtein 距离：找最接近的候选字符串。
+ * 返回值是建议的命令名（可能有多个用逗号连接），找不到返回空字符串。
+ */
+function closestMatch(input, candidates) {
+    if (!input || !candidates.length)
+        return '';
+    const lower = input.toLowerCase();
+    let best = [];
+    for (const c of candidates) {
+        const d = levenshtein(lower, c.toLowerCase());
+        // 只接受距离 ≤ 3 且不超过输入长度 60% 的候选，避免把完全不相关的命令也建议出来
+        const threshold = Math.max(2, Math.floor(input.length * 0.6) + 1);
+        if (d <= threshold) {
+            best.push({ name: c, dist: d });
+        }
+    }
+    if (!best.length)
+        return '';
+    best.sort((a, b) => a.dist - b.dist);
+    // 只返回 top 1：多候选用逗号分隔看起来像一个命令
+    return best[0].name;
+}
+function levenshtein(a, b) {
+    const m = a.length;
+    const n = b.length;
+    if (m === 0)
+        return n;
+    if (n === 0)
+        return m;
+    // 只维护两行，节省内存
+    let prev = new Array(n + 1);
+    let curr = new Array(n + 1);
+    for (let j = 0; j <= n; j++)
+        prev[j] = j;
+    for (let i = 1; i <= m; i++) {
+        curr[0] = i;
+        for (let j = 1; j <= n; j++) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            curr[j] = Math.min(curr[j - 1] + 1, prev[j] + 1, prev[j - 1] + cost);
+        }
+        [prev, curr] = [curr, prev];
+    }
+    return prev[n];
+}

package/dist/locales.js

@@ -12,6 +12,10 @@ export const COMMANDER_FALLBACK_EN_US = {
     'commander.ui.usage': 'Usage: {name} <command> [options]',
     'commander.ui.commands': 'Commands:',
     'commander.ui.options': 'Options:',
+    'commander.ui.option_example': '(e.g. {example})',
+    'commander.ui.deprecated': '(deprecated)',
+    'commander.ui.hint.available_options': "Run '{command} --help' for available options.",
+    'commander.ui.hint.did_you_mean': "Did you mean '{suggest}'?",
     'commander.opt.locale': 'Locale id',
     // Legacy dotted ids (product catalogs may override these).
     'commander.err.unknown_command': 'unknown command `{cmd}`',
@@ -23,6 +27,10 @@ export const COMMANDER_FALLBACK_EN_US = {
     'commander::unknown_option': 'unknown option `{option}`',
     'commander::missing_option_value': 'missing value for `{option}`',
     'commander::parse_failed': 'parse failed: {detail}',
+    'commander::missing_required_option': 'missing required option `{option}`',
+    'commander::option_not_in_enum': 'invalid value `{value}` for `{option}` (allowed: {allowed})',
+    'commander::option_coerce_failed': 'invalid value `{value}` for `{option}`: {detail}',
+    'commander::option_deprecated': 'option `{option}` is deprecated',
     'commander::action_failed': 'action failed: {detail}',
     'commander::config::invalid_cli_name': 'invalid CLI name: {detail}',
     'commander::config::localize_required': 'call .use(LocalizePlugin) or .locales(root) before parse()',

package/dist/types.d.ts

@@ -59,3 +59,56 @@ export type DiagnosticContext = {
 };
 /** Product-owned sink. Formatting remains outside commander. */
 export type DiagnosticHandler = (diagnostic: CommandDiagnostic, context: DiagnosticContext) => void;
+/**
+ * Option registration config (additive — `.option(rawName, helpId, config?)`).
+ *
+ * Existing `parseOptionDef(rawName)` already extracts `<required>` / `[optional]` / `...repeatable`
+ * from the raw name string. This config adds runtime constraints that cannot be expressed in the DSL.
+ */
+export type OptionConfig = {
+    /** 默认值（不传时 options[key] = default） */
+    default?: string | boolean | string[];
+    /** 允许值集合；parse 时 strict 校验（失败 exit code 2） */
+    enum?: string[];
+    /** 是否必须（parse 时缺失 → CliError，exit code 2） */
+    required?: boolean;
+    /** 自定义转换（parse 后对值执行，coerce 失败 → CliError.exitCode 2） */
+    coerce?: (raw: string | boolean | string[]) => unknown;
+    /** 帮助文本中的简短示例（显示在 `--profile <name>` 后） */
+    example?: string;
+    /** 选项分组（帮助里的 section header） */
+    group?: string;
+    /** 标记 deprecated — 帮助里划线显示，调用时走 warn */
+    deprecated?: boolean | string;
+    /** 标记 hidden — 不显示在帮助（但仍可解析） */
+    hidden?: boolean;
+};
+/**
+ * Command action context — constructed by the framework before dispatching to `.actionCtx()`.
+ *
+ * Provides everything a command handler needs without re-parsing argv or re-discovering
+ * product internals. Error paths (`fail` / `warn` / `note`) route through the configured
+ * DiagnosticHandler (or stderr fallback) so downstream code never needs ad-hoc `console.error`.
+ */
+export type CommandContext = {
+    /** 完整命令路径（根命令在 [0]）— e.g. `['vmz', 'application', 'check']` */
+    commandPath: string[];
+    /** 命令路径的人类可读串 — e.g. `'vmz application check'` */
+    commandName: string;
+    /** 当前 locale id — e.g. `'en-US'` */
+    locale: string;
+    /** 产品 LocalizePlugin.t — action 可以用它渲染 helpId / 错误 id */
+    t: LocalizePlugin['t'];
+    /** 打印当前命令的帮助文本（框架级，从 command tree 自动派生） */
+    help: () => void;
+    /** 写入 stderr（正常错误输出） */
+    stderr: (...msgs: string[]) => void;
+    /** 写入 stdout（正常进度 / 结果输出） */
+    stdout: (...msgs: string[]) => void;
+    /** 框架级 fail：走 onDiagnostic + 退出码 2（parse/validation 错误） */
+    fail: (code: string, args?: Record<string, string>) => never;
+    /** 框架级 warn：走 onDiagnostic（warning severity，不退出） */
+    warn: (code: string, args?: Record<string, string>) => void;
+    /** 框架级 note：走 onDiagnostic（advice severity，不退出） */
+    note: (code: string, args?: Record<string, string>) => void;
+};

package/dist/types.js

@@ -38,6 +38,7 @@ export class CliError extends Error {
         if (err instanceof CliError)
             return err;
         const message = err instanceof Error ? err.message : String(err);
-        return new CliError({ code: fallbackCode, exitCode: 1, cause: err, args: { detail: message } });
+        // 同时放 message 和 detail：不同产品 catalog 模板可能用 {message} 或 {detail}
+        return new CliError({ code: fallbackCode, exitCode: 1, cause: err, args: { detail: message, message } });
     }
 }

package/package.json

@@ -35,9 +35,9 @@
   },
   "scripts": {
     "build": "tsc -p tsconfig.json",
-    "test": "node --import ../../../scripts/test/resolve-ts-from-js.mjs --test --experimental-strip-types ./tests/locales.test.ts"
+    "test": "node --import ../../../scripts/test/resolve-ts-from-js.mjs --test --experimental-strip-types ./tests/*.test.ts"
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.3.6"
+  "version": "0.3.8"
 }