@vmz/commander 0.3.5 → 0.3.7

package/README.md

@@ -6,6 +6,7 @@ i18n-first TypeScript CLI framework under the `@vmz` scope. **Not** bound to `@v
 - **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
@@ -41,10 +42,11 @@ Locales layout (any product):
 | API | Role |
 |-----|------|
 | `createCli(name)` | Program name; help `{name}` |
-| `.command` / `.option` / `.action` / `.passthrough` | Command tree |
+| `.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 |
@@ -52,6 +54,35 @@ Locales layout (any product):
 
 `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

package/dist/index.d.ts

@@ -5,16 +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, 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, 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;
@@ -29,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 = {
@@ -37,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;
@@ -71,6 +82,8 @@ export interface Cli {
      */
     help(helpId: string): this;
     command(rawName: string, helpId: string): Command;
+    /** Route structured action failures to a product-owned renderer. */
+    onDiagnostic(handler: DiagnosticHandler): this;
     parse(argv?: string[]): Promise<number>;
 }
 /** Derive command help from one node (children + options). */
@@ -96,6 +109,10 @@ export declare function normalizeArgv(argv: string[]): string[];
 /** Parse `--out-dir <dir>` / `-o, --out-dir <dir>` / `--dirty <path>...` into an OptionDef. */
 export declare function parseOptionDef(rawName: string, helpId: string): OptionDef;
 /**
- * Parse argv against registered options. Throws `unknown_option:…` / `missing_value:…`.
+ * Parse argv against registered options (strict mode).
+ *
+ * Throws {@link CliError} with stable code `commander::unknown_option` /
+ * `commander::missing_option_value` (exit code 2) on validation failure.
+ * Non-option tokens become positionals under `options._`.
  */
 export declare function parseOptions(argv: string[], optionDefs: OptionDef[]): ParsedOptions;

package/dist/index.js

@@ -5,8 +5,147 @@
  * pluggable Localize plugin or `.locales(root)`. Framework chrome/err ids are
  * `commander.*` with tiny English fallbacks — no product language packs here.
  */
+export { CliError } from './types.js';
 export { COMMANDER_FALLBACK_EN_US, clearLocalesCache, createLocalizeFromLocales, flattenCatalog, loadCatalog, loadLocalesManifest, resolveLocale, translate, translateWithFallback, } from './locales.js';
+import { CliError } from './types.js';
 import { COMMANDER_FALLBACK_EN_US, createLocalizeFromLocales, translate, translateWithFallback } from './locales.js';
+const ANSI = {
+    bold: '\u001b[1m',
+    dim: '\u001b[2m',
+    cyan: '\u001b[36m',
+    blue: '\u001b[34m',
+    green: '\u001b[32m',
+    yellow: '\u001b[33m',
+    red: '\u001b[31m',
+};
+const ANSI_RESET = '\u001b[0m';
+/** Keep CI and redirected output plain while making interactive help scannable. */
+function colorEnabled() {
+    if (process.env.NO_COLOR !== undefined)
+        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) {
@@ -20,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;
@@ -45,6 +195,7 @@ class CliBuilder {
     /** When set, `parse` rebuilds localize from this root (argv/env/`--locale`). */
     localesRoot = null;
     localesEnvKeys;
+    diagnosticHandler;
     introId = null;
     roots = [];
     rootOptions = [];
@@ -53,7 +204,7 @@ class CliBuilder {
     }
     use(plugin) {
         if (!plugin || typeof plugin.t !== 'function') {
-            throw new Error('@vmz/commander: LocalizePlugin.t is required');
+            throw CliError.configError('commander::config::invalid_localize_plugin', { detail: 'LocalizePlugin.t is required' });
         }
         this.localesRoot = null;
         this.localesEnvKeys = undefined;
@@ -62,13 +213,13 @@ class CliBuilder {
     }
     catalog(loader) {
         if (typeof loader !== 'function') {
-            throw new Error('@vmz/commander: catalog(loader) requires a function');
+            throw CliError.configError('commander::config::catalog_loader_not_function');
         }
         return this.use({
             t: (id, args) => {
                 const table = loader('en-US');
                 if (table && typeof table.then === 'function') {
-                    throw new Error('@vmz/commander: async CatalogLoader via .catalog() is not supported; use .use({ t })');
+                    throw CliError.configError('commander::config::async_catalog_unsupported');
                 }
                 return translateWithFallback(id, args, table);
             },
@@ -76,7 +227,7 @@ class CliBuilder {
     }
     locales(root, opts = {}) {
         if (!root || typeof root !== 'string') {
-            throw new Error('@vmz/commander: locales(root) requires a non-empty path');
+            throw CliError.configError('commander::config::invalid_locales_root');
         }
         this.localesRoot = root;
         this.localesEnvKeys = opts.envKeys;
@@ -105,6 +256,12 @@ class CliBuilder {
         this.roots.push(cmd);
         return cmd;
     }
+    onDiagnostic(handler) {
+        if (typeof handler !== 'function')
+            throw CliError.configError('commander::config::diagnostic_handler_not_function');
+        this.diagnosticHandler = handler;
+        return this;
+    }
     /** Help ids registered on this CLI (for {@link assertCatalogCoverage}). */
     collectHelpIds() {
         const ids = [];
@@ -125,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;
@@ -138,21 +299,91 @@ class CliBuilder {
             }));
         }
         if (!localize) {
-            throw new Error(translate('commander.err.localize_required', undefined, COMMANDER_FALLBACK_EN_US));
+            throw CliError.configError('commander::config::localize_required');
         }
         const t = localize.t.bind(localize);
-        if (argv.length === 0 || isHelpToken(argv[0])) {
+        const diagnosticContext = {
+            locale: localize.resolveLocale?.({ argv: argv0, env: process.env }) ?? 'en-US',
+            t,
+        };
+        // `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) {
-            console.error(t('commander.err.unknown_command', { cmd: cmdToken }));
+            // 未知命令：加上 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);
+    }
+    /** 路由 `help <cmd> [subcmd] ...` 到对应命令的帮助文本。 */
+    routeHelp(pathTokens, t, _ctx) {
+        if (!pathTokens.length) {
             console.log(this.formatRootHelp(t));
-            return 1;
+            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 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'));
         }
-        return await this.dispatch(matched.def, argv.slice(1), t, [cmdToken], globalOpts);
     }
     /** Derived root help: optional intro + commands/options from the registration tree. */
     formatRootHelp(t) {
@@ -160,62 +391,81 @@ class CliBuilder {
         if (this.introId) {
             lines.push(t(this.introId), '');
         }
-        lines.push(t('commander.ui.usage', { name: this.name }), '', t('commander.ui.commands'));
-        for (const c of this.roots) {
-            lines.push(`  ${c.def.rawName.padEnd(28)} ${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('', t('commander.ui.options'));
-            for (const o of opts) {
-                lines.push(`  ${o.rawName.padEnd(28)} ${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) {
-        if (rest.length && isHelpToken(rest[0])) {
-            console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions));
+    async dispatch(def, rest, t, path, globalOpts, diagnosticContext) {
+        // `--` 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();
+        }
+        // 扫描 --help / -h（只扫命令路径之后的 head，`--` 之后的 tail 不参与）
+        if (hasHelpToken(remaining)) {
+            console.log(formatCommandHelp(this.name, target, t, targetPath, this.rootOptions));
             return 0;
         }
-        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);
+        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;
             }
-            if (!def.action) {
-                console.error(t('commander.err.unknown_command', { cmd: [...path, childTok].join(' ') }));
-                console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions));
-                return 1;
-            }
-        }
-        if (!def.action) {
-            console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions));
-            return rest.length ? 1 : 0;
+            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);
-        }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            if (msg.startsWith('unknown_option:')) {
-                console.error(t('commander.err.unknown_option', { option: msg.slice('unknown_option:'.length) }));
-            }
-            else if (msg.startsWith('missing_value:')) {
-                console.error(t('commander.err.missing_option_value', {
-                    option: msg.slice('missing_value:'.length),
-                }));
+            if (target.passthrough) {
+                options = { _: [...remaining, ...tail] };
             }
             else {
-                console.error(msg);
+                ({ options, used: usedOptions } = parseOptionsDetailed(remaining, target.options));
+                options._.push(...tail);
             }
-            console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions));
-            return 1;
+        }
+        catch (err) {
+            const cliErr = CliError.from(err, 'commander::parse_failed');
+            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 === '_')
@@ -223,28 +473,81 @@ class CliBuilder {
             if (options[k] === undefined)
                 options[k] = v;
         }
-        const result = await def.action(options, ...options._);
-        if (typeof result === 'number')
-            return result;
-        return 0;
+        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 {
+            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;
+        }
+        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 = [`${cliName} ${path.join(' ')} — ${t(def.helpId)}`, ''];
+    const lines = [paint(`${cliName} ${path.join(' ')}`, 'bold', 'cyan') + ` — ${t(def.helpId)}`];
     if (def.children.length) {
-        lines.push(t('commander.ui.commands'));
-        for (const c of def.children) {
-            lines.push(`  ${c.rawName.padEnd(28)} ${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(t('commander.ui.options'));
-        for (const o of opts) {
-            lines.push(`  ${o.rawName.padEnd(28)} ${t(o.helpId)}`);
-        }
+    const optionSection = renderOptionSections(t, opts, 'yellow');
+    if (optionSection.length) {
+        lines.push('');
+        lines.push(...optionSection);
     }
     return lines.join('\n').trimEnd();
 }
@@ -267,7 +570,7 @@ function collectRootOptions(roots) {
  */
 export function createCli(name) {
     if (!name || typeof name !== 'string') {
-        throw new Error('@vmz/commander: createCli(name) requires a non-empty program name');
+        throw CliError.configError('commander::config::invalid_cli_name', { detail: String(name) });
     }
     return new CliBuilder(name);
 }
@@ -278,7 +581,7 @@ export function assertCatalogCoverage(cli, catalog) {
     const ids = typeof cli.collectHelpIds === 'function' ? cli.collectHelpIds() : [];
     const missing = ids.filter((id) => !Object.prototype.hasOwnProperty.call(catalog, id) && !Object.prototype.hasOwnProperty.call(COMMANDER_FALLBACK_EN_US, id));
     if (missing.length) {
-        throw new Error(`@vmz/commander: catalog missing help ids:\n  ${missing.sort().join('\n  ')}`);
+        throw CliError.configError('commander::config::catalog_missing_help_ids', { ids: missing.sort().join(', ') });
     }
 }
 function wrapWithCommanderFallback(plugin) {
@@ -296,10 +599,15 @@ function wrapWithCommanderFallback(plugin) {
     };
 }
 /**
- * Consume known root options; leave unknown flags and positionals in `rest`
- * (unlike {@link parseOptions}, which throws on unknown options).
+ * Shared argv → { options, rest } parser used by both strict and permissive modes.
+ *
+ * - `strict: true` — throws {@link CliError} (exit code 2) on unknown option or
+ *   missing required value. Used by {@link parseOptions} before dispatching to an action.
+ * - `strict: false` — unknown flags / bare tokens stay in `rest`. Used by
+ *   {@link peelKnownOptions} so `.locales(root)` / other early-bound global options
+ *   never reject argv that belongs to a later subcommand.
  */
-export function peelKnownOptions(argv, optionDefs) {
+function parseArgvCore(argv, optionDefs, strict) {
     const byAlias = new Map();
     for (const def of optionDefs) {
         for (const a of def.aliases)
@@ -307,70 +615,108 @@ export function peelKnownOptions(argv, optionDefs) {
     }
     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 });
+        }
+        rest.push(flagName);
+        return true;
+    };
+    const handleUnknown = (token) => {
+        if (strict) {
+            throw CliError.parseError('commander::unknown_option', { option: token });
+        }
+        rest.push(token);
+        return true;
+    };
     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) {
-                rest.push(a);
+                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 {
-                        throw new Error(`missing_value:--${long}`);
+                        if (!handleMissing(`--${long}`))
+                            continue;
+                        continue;
                     }
                 }
             }
             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) {
-                rest.push(a);
+                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 {
-                    throw new Error(`missing_value:-${short}`);
+                    if (!handleMissing(`-${short}`))
+                        continue;
+                    continue;
                 }
             }
             else {
-                assignOption(options, def, true);
+                assignOption(options, def, used, true);
             }
             continue;
         }
         rest.push(a);
     }
+    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) {
+    const { options, rest } = parseArgvCore(argv, optionDefs, false);
     return { options, rest };
 }
 /** Strip `node` + script when callers pass full `process.argv`. */
@@ -398,10 +744,10 @@ function splitNames(rawName) {
 }
 function assertHelpId(helpId, kind) {
     if (!helpId || typeof helpId !== 'string' || !helpId.trim()) {
-        throw new Error(`@vmz/commander: ${kind} helpId must be a non-empty catalog key`);
+        throw CliError.configError('commander::config::help_id_empty', { kind });
     }
     if (/\s/.test(helpId)) {
-        throw new Error(`@vmz/commander: ${kind} helpId must be a catalog key (no spaces); got ${JSON.stringify(helpId)}`);
+        throw CliError.configError('commander::config::help_id_has_spaces', { kind, id: helpId });
     }
 }
 /** Parse `--out-dir <dir>` / `-o, --out-dir <dir>` / `--dirty <path>...` into an OptionDef. */
@@ -425,84 +771,98 @@ export function parseOptionDef(rawName, helpId) {
             aliases.push(p.slice(1));
     }
     if (!aliases.length) {
-        throw new Error(`@vmz/commander: invalid option rawName ${JSON.stringify(rawName)}`);
+        throw CliError.configError('commander::config::invalid_option_raw', { raw: rawName });
     }
     const key = aliases.find((a) => a.length > 1) ?? aliases[0];
     return { rawName, helpId, key, aliases, takesValue, optionalValue, repeatable };
 }
+function normalizeDiagnostic(error) {
+    if (error && typeof error === 'object') {
+        const value = error;
+        const candidate = value.diagnostic && typeof value.diagnostic === 'object' ? value.diagnostic : value;
+        if (typeof candidate.code === 'string' || typeof candidate.severity === 'string' || typeof candidate.path === 'string') {
+            return {
+                code: typeof candidate.code === 'string' ? candidate.code : undefined,
+                severity: typeof candidate.severity === 'string' ? candidate.severity : 'error',
+                args: candidate.args && typeof candidate.args === 'object' ? candidate.args : undefined,
+                path: typeof candidate.path === 'string' ? candidate.path : undefined,
+                span: candidate.span && typeof candidate.span === 'object' ? candidate.span : undefined,
+                message: typeof candidate.message === 'string' ? candidate.message : undefined,
+            };
+        }
+    }
+    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. Throws `unknown_option:…` / `missing_value:…`.
+ * Parse argv against registered options (strict mode).
+ *
+ * Throws {@link CliError} with stable code `commander::unknown_option` /
+ * `commander::missing_option_value` (exit code 2) on validation failure.
+ * Non-option tokens become positionals under `options._`.
  */
 export function parseOptions(argv, optionDefs) {
-    const byAlias = new Map();
+    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);
+    applyOptionConfig(options, optionDefs, used);
+    return { options, used };
+}
+/**
+ * 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) {
-        for (const a of def.aliases)
-            byAlias.set(a, def);
-    }
-    const out = { _: [] };
-    for (let i = 0; i < argv.length; i++) {
-        const a = argv[i];
-        if (a === '--') {
-            out._.push(...argv.slice(i + 1));
-            break;
+        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;
         }
-        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)
-                throw new Error(`unknown_option:--${long}`);
-            if (def.takesValue) {
-                if (eq !== -1) {
-                    assignOption(out, def, a.slice(eq + 1));
-                }
-                else {
-                    const next = argv[i + 1];
-                    if (next != null && !next.startsWith('-')) {
-                        assignOption(out, def, next);
-                        i += 1;
-                    }
-                    else if (def.optionalValue) {
-                        assignOption(out, def, true);
-                    }
-                    else {
-                        throw new Error(`missing_value:--${long}`);
-                    }
+        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(', '),
+                    });
                 }
             }
-            else {
-                assignOption(out, def, true);
-            }
-            continue;
         }
-        if (a.startsWith('-') && a.length === 2) {
-            const short = a.slice(1);
-            const def = byAlias.get(short);
-            if (!def)
-                throw new Error(`unknown_option:-${short}`);
-            if (def.takesValue) {
-                const next = argv[i + 1];
-                if (next != null && !next.startsWith('-')) {
-                    assignOption(out, def, next);
-                    i += 1;
-                }
-                else if (def.optionalValue) {
-                    assignOption(out, def, true);
-                }
-                else {
-                    throw new Error(`missing_value:-${short}`);
-                }
+        if (config.coerce && provided) {
+            try {
+                options[def.key] = config.coerce(value);
             }
-            else {
-                assignOption(out, def, true);
+            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),
+                });
             }
-            continue;
         }
-        out._.push(a);
     }
-    return out;
 }
-function assignOption(out, def, value) {
+function assignOption(out, def, used, value) {
+    used.add(def);
     if (def.repeatable) {
         const cur = out[def.key];
         const list = Array.isArray(cur) ? cur : [];
@@ -512,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

@@ -6,16 +6,37 @@
  */
 import { existsSync, readdirSync, readFileSync } from 'node:fs';
 import path from 'node:path';
+import { CliError } from './types.js';
 /** Framework chrome / errors — products may override the same ids in their locales/. */
 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}`',
     'commander.err.unknown_option': 'unknown option `{option}`',
     'commander.err.missing_option_value': 'missing value for `{option}`',
     'commander.err.localize_required': 'call .use(LocalizePlugin) or .locales(root) before parse()',
+    // New stable `::` codes — used when the framework itself emits diagnostics.
+    'commander::unknown_command': 'unknown command `{cmd}`',
+    '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()',
+    'commander::config::missing_locales_manifest': 'missing locales manifest at {file}',
+    'commander::config::invalid_locales_manifest': 'invalid locales manifest at {file}',
+    'commander::config::empty_locale_catalog': 'empty catalog for locale {locale} under {root}',
 };
 const catalogCache = new Map();
 const manifestCache = new Map();
@@ -25,11 +46,11 @@ export function loadLocalesManifest(root) {
         return cached;
     const file = path.join(root, 'locales.json');
     if (!existsSync(file)) {
-        throw new Error(`@vmz/commander: missing locales manifest at ${file}`);
+        throw CliError.configError('commander::config::missing_locales_manifest', { file });
     }
     const raw = JSON.parse(readFileSync(file, 'utf8'));
     if (!raw?.defaultLocale || !Array.isArray(raw.locales) || !raw.locales.length) {
-        throw new Error(`@vmz/commander: invalid locales manifest ${file}`);
+        throw CliError.configError('commander::config::invalid_locales_manifest', { file });
     }
     manifestCache.set(root, raw);
     return raw;
@@ -81,7 +102,7 @@ export function loadCatalog(locale, root) {
         Object.assign(merged, loadLocaleDir(root, id));
     }
     if (!Object.keys(merged).length) {
-        throw new Error(`@vmz/commander: empty catalog for locale ${JSON.stringify(locale)} under ${root}`);
+        throw CliError.configError('commander::config::empty_locale_catalog', { locale, root });
     }
     catalogCache.set(cacheKey, merged);
     return merged;

package/dist/types.d.ts

@@ -1,6 +1,30 @@
 /**
  * Shared types for `@vmz/commander` (kept separate so locales.ts can import without cycles).
  */
+/**
+ * Structured error thrown by `@vmz/commander` itself.
+ *
+ * Exit code contract (POSIX CLI conventions):
+ * - 2: parse / validation failure (unknown command, unknown/missing option).
+ * - 1: config / factory / action-handler failure.
+ */
+export declare class CliError extends Error {
+    /** Stable code (`commander::*`) consumed by callers; also doubles as catalog id. */
+    readonly code: string;
+    /** Exit code a framework user should return for this failure. */
+    readonly exitCode: number;
+    /** Structured catalog args (`{ name: value }`) for message interpolation. */
+    readonly args: Record<string, string>;
+    /** Optional root cause. */
+    readonly cause?: unknown;
+    private constructor();
+    /** Parse / validation failures (exit code 2). */
+    static parseError(code: string, args?: Record<string, string>): CliError;
+    /** Factory / configuration failures (exit code 1). */
+    static configError(code: string, args?: Record<string, string>): CliError;
+    /** Wrap an arbitrary exception as a CliError (exit code 1). */
+    static from(err: unknown, fallbackCode?: string): CliError;
+}
 /** Message id → template. Owned by the localize plugin / product, not this package. */
 export type LocaleCatalog = Record<string, string>;
 /** Load messages for one locale (sugar for building a {@link LocalizePlugin}). */
@@ -16,3 +40,75 @@ export type LocalizePlugin = {
     }) => string;
     t: (id: string, args?: Record<string, string>) => string;
 };
+/** Language-neutral diagnostic row accepted at a command boundary. */
+export type CommandDiagnostic = {
+    severity?: 'error' | 'warning' | 'advice' | string;
+    code?: string;
+    args?: Record<string, string>;
+    path?: string;
+    span?: {
+        start: number;
+        end: number;
+    };
+    message?: string;
+};
+/** Product-owned sink. Formatting remains in the product diagnostic package. */
+export type DiagnosticContext = {
+    locale: string;
+    t: LocalizePlugin['t'];
+};
+/** 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

@@ -1,4 +1,44 @@
 /**
  * Shared types for `@vmz/commander` (kept separate so locales.ts can import without cycles).
  */
-export {};
+/**
+ * Structured error thrown by `@vmz/commander` itself.
+ *
+ * Exit code contract (POSIX CLI conventions):
+ * - 2: parse / validation failure (unknown command, unknown/missing option).
+ * - 1: config / factory / action-handler failure.
+ */
+export class CliError extends Error {
+    /** Stable code (`commander::*`) consumed by callers; also doubles as catalog id. */
+    code;
+    /** Exit code a framework user should return for this failure. */
+    exitCode;
+    /** Structured catalog args (`{ name: value }`) for message interpolation. */
+    args;
+    /** Optional root cause. */
+    cause;
+    constructor(opts) {
+        super(opts.cause instanceof Error ? opts.cause.message : opts.code);
+        this.name = 'CliError';
+        this.code = opts.code;
+        this.exitCode = opts.exitCode;
+        this.args = opts.args ?? {};
+        this.cause = opts.cause;
+    }
+    /** Parse / validation failures (exit code 2). */
+    static parseError(code, args = {}) {
+        return new CliError({ code, exitCode: 2, args });
+    }
+    /** Factory / configuration failures (exit code 1). */
+    static configError(code, args = {}) {
+        return new CliError({ code, exitCode: 1, args });
+    }
+    /** Wrap an arbitrary exception as a CliError (exit code 1). */
+    static from(err, fallbackCode = 'commander::action_failed') {
+        if (err instanceof CliError)
+            return err;
+        const message = err instanceof Error ? err.message : String(err);
+        // 同时放 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.5"
+  "version": "0.3.7"
 }