@vmz/commander 0.3.5 → 0.3.6

package/README.md

@@ -1,63 +1,67 @@
-# `@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)
-- **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) |
-| `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}}`.
-
-## 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` / `.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.

package/dist/index.d.ts

@@ -5,10 +5,11 @@
  * 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, CommandDiagnostic, DiagnosticContext, DiagnosticHandler, LocaleCatalog, LocalizePlugin } 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, DiagnosticHandler, LocaleCatalog, LocalizePlugin } from './types.js';
 /** Options bag passed to actions (`_` = positionals). */
 export type ParsedOptions = Record<string, string | boolean | string[]> & {
     _: string[];
@@ -71,6 +72,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 +99,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,34 @@
  * 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;
+    return Boolean(process.stdout?.isTTY || process.stderr?.isTTY);
+}
+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');
+}
 class CommandBuilder {
     def;
     constructor(rawName, helpId) {
@@ -45,6 +71,7 @@ class CliBuilder {
     /** When set, `parse` rebuilds localize from this root (argv/env/`--locale`). */
     localesRoot = null;
     localesEnvKeys;
+    diagnosticHandler;
     introId = null;
     roots = [];
     rootOptions = [];
@@ -53,7 +80,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 +89,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 +103,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 +132,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 = [];
@@ -138,9 +171,13 @@ 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);
+        const diagnosticContext = {
+            locale: localize.resolveLocale?.({ argv: argv0, env: process.env }) ?? 'en-US',
+            t,
+        };
         if (argv.length === 0 || isHelpToken(argv[0])) {
             console.log(this.formatRootHelp(t));
             return 0;
@@ -148,11 +185,25 @@ class CliBuilder {
         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 }));
-            console.log(this.formatRootHelp(t));
-            return 1;
+            return this.emitAndHelp({ code: 'commander::unknown_command', severity: 'error', args: { cmd: cmdToken } }, diagnosticContext, t, this.formatRootHelp(t), 2);
+        }
+        return await this.dispatch(matched.def, argv.slice(1), t, [cmdToken], globalOpts, diagnosticContext);
+    }
+    /** Emit a diagnostic through `onDiagnostic` when registered, else console.error. */
+    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)));
         }
-        return await this.dispatch(matched.def, argv.slice(1), t, [cmdToken], globalOpts);
+    }
+    /** 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) {
@@ -160,23 +211,23 @@ class CliBuilder {
         if (this.introId) {
             lines.push(t(this.introId), '');
         }
-        lines.push(t('commander.ui.usage', { name: this.name }), '', t('commander.ui.commands'));
+        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(`  ${c.def.rawName.padEnd(28)} ${t(c.def.helpId)}`);
+            lines.push(`  ${paint(c.def.rawName.padEnd(28), 'green')} ${t(c.def.helpId)}`);
         }
         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'));
+            lines.push('', paint(t('commander.ui.options'), 'bold', 'blue'));
             for (const o of opts) {
-                lines.push(`  ${o.rawName.padEnd(28)} ${t(o.helpId)}`);
+                lines.push(`  ${paint(o.rawName.padEnd(28), 'yellow')} ${t(o.helpId)}`);
             }
         }
         return lines.join('\n');
     }
-    async dispatch(def, rest, t, path, globalOpts) {
+    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;
@@ -185,37 +236,26 @@ class CliBuilder {
             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);
+                return await this.dispatch(child, rest.slice(1), t, [...path, childTok], globalOpts, diagnosticContext);
             }
             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;
+                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);
             }
         }
         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);
+            }
             console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions));
-            return rest.length ? 1 : 0;
+            return 0;
         }
         let options;
         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),
-                }));
-            }
-            else {
-                console.error(msg);
-            }
-            console.log(formatCommandHelp(this.name, def, t, path, this.rootOptions));
-            return 1;
+            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);
         }
         for (const [k, v] of Object.entries(globalOpts)) {
             if (k === '_')
@@ -223,27 +263,34 @@ class CliBuilder {
             if (options[k] === undefined)
                 options[k] = v;
         }
-        const result = await def.action(options, ...options._);
-        if (typeof result === 'number')
-            return result;
-        return 0;
+        try {
+            const result = await def.action(options, ...options._);
+            if (typeof result === 'number')
+                return result;
+            return 0;
+        }
+        catch (err) {
+            const diagnostic = normalizeDiagnostic(err);
+            this.emitDiagnostic(diagnostic, diagnosticContext, t);
+            return 1;
+        }
     }
 }
 /** 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'));
+        lines.push(paint(t('commander.ui.commands'), 'bold', 'blue'));
         for (const c of def.children) {
-            lines.push(`  ${c.rawName.padEnd(28)} ${t(c.helpId)}`);
+            lines.push(`  ${paint(c.rawName.padEnd(28), 'green')} ${t(c.helpId)}`);
         }
         lines.push('');
     }
     const opts = [...rootOptions, ...def.options.filter((o) => !rootOptions.some((r) => r.key === o.key))];
     if (opts.length) {
-        lines.push(t('commander.ui.options'));
+        lines.push(paint(t('commander.ui.options'), 'bold', 'blue'));
         for (const o of opts) {
-            lines.push(`  ${o.rawName.padEnd(28)} ${t(o.helpId)}`);
+            lines.push(`  ${paint(o.rawName.padEnd(28), 'yellow')} ${t(o.helpId)}`);
         }
     }
     return lines.join('\n').trimEnd();
@@ -267,7 +314,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 +325,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 +343,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,6 +359,20 @@ export function peelKnownOptions(argv, optionDefs) {
     }
     const options = { _: [] };
     const rest = [];
+    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 === '--') {
@@ -318,7 +384,8 @@ export function peelKnownOptions(argv, optionDefs) {
             const long = eq === -1 ? a.slice(2) : a.slice(2, eq);
             const def = byAlias.get(long);
             if (!def) {
-                rest.push(a);
+                if (!handleUnknown(`--${long}`))
+                    continue;
                 continue;
             }
             if (def.takesValue) {
@@ -335,7 +402,9 @@ export function peelKnownOptions(argv, optionDefs) {
                         assignOption(options, def, true);
                     }
                     else {
-                        throw new Error(`missing_value:--${long}`);
+                        if (!handleMissing(`--${long}`))
+                            continue;
+                        continue;
                     }
                 }
             }
@@ -348,7 +417,8 @@ export function peelKnownOptions(argv, optionDefs) {
             const short = a.slice(1);
             const def = byAlias.get(short);
             if (!def) {
-                rest.push(a);
+                if (!handleUnknown(`-${short}`))
+                    continue;
                 continue;
             }
             if (def.takesValue) {
@@ -361,7 +431,9 @@ export function peelKnownOptions(argv, optionDefs) {
                     assignOption(options, def, true);
                 }
                 else {
-                    throw new Error(`missing_value:-${short}`);
+                    if (!handleMissing(`-${short}`))
+                        continue;
+                    continue;
                 }
             }
             else {
@@ -373,6 +445,13 @@ export function peelKnownOptions(argv, optionDefs) {
     }
     return { options, rest };
 }
+/**
+ * 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);
+}
 /** Strip `node` + script when callers pass full `process.argv`. */
 export function normalizeArgv(argv) {
     if (argv.length >= 2 && looksLikeNode(argv[0]) && looksLikeScript(argv[1])) {
@@ -398,10 +477,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,82 +504,39 @@ 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,
+            };
+        }
+    }
+    return { severity: 'error', code: 'commander::action_failed', message: error instanceof Error ? error.message : String(error) };
+}
 /**
- * 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();
-    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;
-        }
-        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}`);
-                    }
-                }
-            }
-            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}`);
-                }
-            }
-            else {
-                assignOption(out, def, true);
-            }
-            continue;
-        }
-        out._.push(a);
-    }
-    return out;
+    const { options, rest } = parseArgvCore(argv, optionDefs, true);
+    options._.push(...rest);
+    return options;
 }
 function assignOption(out, def, value) {
     if (def.repeatable) {

package/dist/locales.js

@@ -6,16 +6,29 @@
  */
 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.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::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 +38,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 +94,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,22 @@ 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;

package/dist/types.js

@@ -1,4 +1,43 @@
 /**
  * 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);
+        return new CliError({ code: fallbackCode, exitCode: 1, cause: err, args: { detail: message } });
+    }
+}

package/package.json

@@ -39,5 +39,5 @@
   },
   "type": "module",
   "types": "./dist/index.d.ts",
-  "version": "0.3.5"
+  "version": "0.3.6"
 }