@vmz/commander 0.0.0 → 0.1.19

package/README.md

@@ -1,3 +1,63 @@
-# @vmz/commander
+# `@vmz/commander`
 
-Placeholder package (0.0.0). Reserved for the VMZ project.
+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.

package/dist/index.d.ts

@@ -0,0 +1,101 @@
+/**
+ * `@vmz/commander` — i18n-first TypeScript CLI framework.
+ *
+ * Command / option second args are message ids. Natural language comes from a
+ * 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 { 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';
+/** Options bag passed to actions (`_` = positionals). */
+export type ParsedOptions = Record<string, string | boolean | string[]> & {
+    _: string[];
+};
+/** Command action after argv is parsed. */
+export type ActionHandler = (options: ParsedOptions, ...args: string[]) => void | number | Promise<void | number>;
+/** Registered option (structure only). */
+export type OptionDef = {
+    rawName: string;
+    helpId: string;
+    /** Canonical key in options bag (e.g. `out-dir`). */
+    key: string;
+    /** Long/short tokens without leading dashes (e.g. `out-dir`, `o`). */
+    aliases: string[];
+    /** True when the option takes a value (`<x>` / `[x]`). */
+    takesValue: boolean;
+    /** True when value is optional (`[x]`): bare flag ⇒ `true`. */
+    optionalValue: boolean;
+    /** True when the option may repeat (`--dirty <path>...` ⇒ `string[]`). */
+    repeatable: boolean;
+};
+/** Registered command node. */
+export type CommandDef = {
+    rawName: string;
+    helpId: string;
+    /** Match tokens from `rawName` split on `|`. */
+    names: string[];
+    options: OptionDef[];
+    action?: ActionHandler;
+    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;
+    action(handler: ActionHandler): this;
+    command(rawName: string, helpId: string): Command;
+    /** Leave remaining argv unparsed (for nested domain CLIs). */
+    passthrough(): this;
+}
+export interface Cli {
+    use(plugin: LocalizePlugin): this;
+    catalog(loader: CatalogLoader): this;
+    /**
+     * Load catalogs from a locales directory (`locales.json` + `<locale>/*.json`).
+     * Later `.use` overrides. Rebuilds at `parse` so `--locale` / env apply.
+     */
+    locales(root: string, opts?: {
+        envKeys?: string[];
+    }): this;
+    /** Global option (parsed before the command; merged into action options). */
+    option(rawName: string, helpId: string): this;
+    /**
+     * Optional short intro line(s) before derived command/option lists.
+     * Do **not** paste full usage here — help is derived from the command tree.
+     */
+    intro(introId: string): this;
+    /**
+     * @deprecated Use {@link intro}. Kept as alias so older call sites compile.
+     */
+    help(helpId: string): this;
+    command(rawName: string, helpId: string): Command;
+    parse(argv?: string[]): Promise<number>;
+}
+/** Derive command help from one node (children + options). */
+export declare function formatCommandHelp(cliName: string, def: CommandDef, t: LocalizePlugin['t'], path: string[], rootOptions?: OptionDef[]): string;
+/**
+ * Create a CLI named `name` (shown in usage).
+ */
+export declare function createCli(name: string): Cli;
+/**
+ * Dev/CI: every registered helpId must exist in `catalog` or commander English fallbacks.
+ */
+export declare function assertCatalogCoverage(cli: Cli, catalog: LocaleCatalog): void;
+/**
+ * Consume known root options; leave unknown flags and positionals in `rest`
+ * (unlike {@link parseOptions}, which throws on unknown options).
+ */
+export declare function peelKnownOptions(argv: string[], optionDefs: OptionDef[]): {
+    options: ParsedOptions;
+    rest: string[];
+};
+/** Strip `node` + script when callers pass full `process.argv`. */
+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:…`.
+ */
+export declare function parseOptions(argv: string[], optionDefs: OptionDef[]): ParsedOptions;

package/dist/index.js

@@ -0,0 +1,514 @@
+/**
+ * `@vmz/commander` — i18n-first TypeScript CLI framework.
+ *
+ * Command / option second args are message ids. Natural language comes from a
+ * pluggable Localize plugin or `.locales(root)`. Framework chrome/err ids are
+ * `commander.*` with tiny English fallbacks — no product language packs here.
+ */
+export { COMMANDER_FALLBACK_EN_US, clearLocalesCache, createLocalizeFromLocales, flattenCatalog, loadCatalog, loadLocalesManifest, resolveLocale, translate, translateWithFallback, } from './locales.js';
+import { COMMANDER_FALLBACK_EN_US, createLocalizeFromLocales, translate, translateWithFallback } from './locales.js';
+class CommandBuilder {
+    def;
+    constructor(rawName, helpId) {
+        assertHelpId(helpId, 'command');
+        this.def = {
+            rawName,
+            helpId,
+            names: splitNames(rawName),
+            options: [],
+            children: [],
+            passthrough: false,
+        };
+    }
+    option(rawName, helpId) {
+        assertHelpId(helpId, 'option');
+        this.def.options.push(parseOptionDef(rawName, helpId));
+        return this;
+    }
+    action(handler) {
+        this.def.action = handler;
+        return this;
+    }
+    passthrough() {
+        this.def.passthrough = true;
+        return this;
+    }
+    command(rawName, helpId) {
+        const child = new CommandBuilder(rawName, helpId);
+        this.def.children.push(child.def);
+        return child;
+    }
+}
+class CliBuilder {
+    name;
+    localize = null;
+    /** When set, `parse` rebuilds localize from this root (argv/env/`--locale`). */
+    localesRoot = null;
+    localesEnvKeys;
+    introId = null;
+    roots = [];
+    rootOptions = [];
+    constructor(name) {
+        this.name = name;
+    }
+    use(plugin) {
+        if (!plugin || typeof plugin.t !== 'function') {
+            throw new Error('@vmz/commander: LocalizePlugin.t is required');
+        }
+        this.localesRoot = null;
+        this.localesEnvKeys = undefined;
+        this.localize = wrapWithCommanderFallback(plugin);
+        return this;
+    }
+    catalog(loader) {
+        if (typeof loader !== 'function') {
+            throw new Error('@vmz/commander: catalog(loader) requires a 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 })');
+                }
+                return translateWithFallback(id, args, table);
+            },
+        });
+    }
+    locales(root, opts = {}) {
+        if (!root || typeof root !== 'string') {
+            throw new Error('@vmz/commander: locales(root) requires a non-empty path');
+        }
+        this.localesRoot = root;
+        this.localesEnvKeys = opts.envKeys;
+        if (!this.rootOptions.some((o) => o.key === 'locale')) {
+            this.rootOptions.push(parseOptionDef('--locale <id>', 'commander.opt.locale'));
+        }
+        // Eager plugin so missing-manifest fails early; parse rebuilds with argv.
+        this.localize = wrapWithCommanderFallback(createLocalizeFromLocales({ root, envKeys: opts.envKeys }));
+        return this;
+    }
+    option(rawName, helpId) {
+        assertHelpId(helpId, 'option');
+        this.rootOptions.push(parseOptionDef(rawName, helpId));
+        return this;
+    }
+    intro(introId) {
+        assertHelpId(introId, 'intro');
+        this.introId = introId;
+        return this;
+    }
+    help(helpId) {
+        return this.intro(helpId);
+    }
+    command(rawName, helpId) {
+        const cmd = new CommandBuilder(rawName, helpId);
+        this.roots.push(cmd);
+        return cmd;
+    }
+    /** Help ids registered on this CLI (for {@link assertCatalogCoverage}). */
+    collectHelpIds() {
+        const ids = [];
+        if (this.introId)
+            ids.push(this.introId);
+        for (const o of this.rootOptions)
+            ids.push(o.helpId);
+        const walk = (def) => {
+            ids.push(def.helpId);
+            for (const o of def.options)
+                ids.push(o.helpId);
+            for (const c of def.children)
+                walk(c);
+        };
+        for (const r of this.roots)
+            walk(r.def);
+        return [...new Set(ids)];
+    }
+    async parse(argvInput = process.argv) {
+        const argv0 = normalizeArgv(argvInput);
+        const { options: globalOpts, rest: argv } = peelKnownOptions(argv0, this.rootOptions);
+        let localize = this.localize;
+        if (this.localesRoot) {
+            const localeFlag = typeof globalOpts.locale === 'string' && globalOpts.locale ? globalOpts.locale : undefined;
+            localize = wrapWithCommanderFallback(createLocalizeFromLocales({
+                root: this.localesRoot,
+                locale: localeFlag,
+                argv: argv0,
+                env: process.env,
+                envKeys: this.localesEnvKeys,
+            }));
+        }
+        if (!localize) {
+            throw new Error(translate('commander.err.localize_required', undefined, COMMANDER_FALLBACK_EN_US));
+        }
+        const t = localize.t.bind(localize);
+        if (argv.length === 0 || isHelpToken(argv[0])) {
+            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 }));
+            console.log(this.formatRootHelp(t));
+            return 1;
+        }
+        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) {
+        const lines = [];
+        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)}`);
+        }
+        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)}`);
+            }
+        }
+        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));
+            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 (!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;
+        }
+        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;
+        }
+        for (const [k, v] of Object.entries(globalOpts)) {
+            if (k === '_')
+                continue;
+            if (options[k] === undefined)
+                options[k] = v;
+        }
+        const result = await def.action(options, ...options._);
+        if (typeof result === 'number')
+            return result;
+        return 0;
+    }
+}
+/** Derive command help from one node (children + options). */
+export function formatCommandHelp(cliName, def, t, path, rootOptions = []) {
+    const lines = [`${cliName} ${path.join(' ')} — ${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('');
+    }
+    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)}`);
+        }
+    }
+    return lines.join('\n').trimEnd();
+}
+/** Union options declared on root commands (dedupe by key, stable first-seen order). */
+function collectRootOptions(roots) {
+    const seen = new Set();
+    const out = [];
+    for (const root of roots) {
+        for (const o of root.options) {
+            if (seen.has(o.key))
+                continue;
+            seen.add(o.key);
+            out.push(o);
+        }
+    }
+    return out;
+}
+/**
+ * Create a CLI named `name` (shown in usage).
+ */
+export function createCli(name) {
+    if (!name || typeof name !== 'string') {
+        throw new Error('@vmz/commander: createCli(name) requires a non-empty program name');
+    }
+    return new CliBuilder(name);
+}
+/**
+ * Dev/CI: every registered helpId must exist in `catalog` or commander English fallbacks.
+ */
+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  ')}`);
+    }
+}
+function wrapWithCommanderFallback(plugin) {
+    return {
+        resolveLocale: plugin.resolveLocale?.bind(plugin),
+        t: (id, args) => {
+            const fromPlugin = plugin.t(id, args);
+            if (fromPlugin !== `{{${id}}}`)
+                return fromPlugin;
+            if (Object.prototype.hasOwnProperty.call(COMMANDER_FALLBACK_EN_US, id)) {
+                return translate(id, args, COMMANDER_FALLBACK_EN_US);
+            }
+            return fromPlugin;
+        },
+    };
+}
+/**
+ * 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 byAlias = new Map();
+    for (const def of optionDefs) {
+        for (const a of def.aliases)
+            byAlias.set(a, def);
+    }
+    const options = { _: [] };
+    const rest = [];
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--') {
+            rest.push(...argv.slice(i));
+            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) {
+                rest.push(a);
+                continue;
+            }
+            if (def.takesValue) {
+                if (eq !== -1) {
+                    assignOption(options, def, a.slice(eq + 1));
+                }
+                else {
+                    const next = argv[i + 1];
+                    if (next != null && !next.startsWith('-')) {
+                        assignOption(options, def, next);
+                        i += 1;
+                    }
+                    else if (def.optionalValue) {
+                        assignOption(options, def, true);
+                    }
+                    else {
+                        throw new Error(`missing_value:--${long}`);
+                    }
+                }
+            }
+            else {
+                assignOption(options, def, true);
+            }
+            continue;
+        }
+        if (a.startsWith('-') && a.length === 2) {
+            const short = a.slice(1);
+            const def = byAlias.get(short);
+            if (!def) {
+                rest.push(a);
+                continue;
+            }
+            if (def.takesValue) {
+                const next = argv[i + 1];
+                if (next != null && !next.startsWith('-')) {
+                    assignOption(options, def, next);
+                    i += 1;
+                }
+                else if (def.optionalValue) {
+                    assignOption(options, def, true);
+                }
+                else {
+                    throw new Error(`missing_value:-${short}`);
+                }
+            }
+            else {
+                assignOption(options, def, true);
+            }
+            continue;
+        }
+        rest.push(a);
+    }
+    return { options, rest };
+}
+/** Strip `node` + script when callers pass full `process.argv`. */
+export function normalizeArgv(argv) {
+    if (argv.length >= 2 && looksLikeNode(argv[0]) && looksLikeScript(argv[1])) {
+        return argv.slice(2);
+    }
+    return argv.slice();
+}
+function looksLikeNode(token) {
+    const base = token.replace(/\\/g, '/').split('/').pop() || '';
+    return base === 'node' || base === 'node.exe' || base.startsWith('node');
+}
+function looksLikeScript(token) {
+    return /\.(c?js|mjs|ts)$/i.test(token) || token.includes(`${'node_modules'}`) || token.endsWith('vmz');
+}
+function isHelpToken(token) {
+    return token === 'help' || token === '-h' || token === '--help';
+}
+function splitNames(rawName) {
+    return rawName
+        .split('|')
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+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`);
+    }
+    if (/\s/.test(helpId)) {
+        throw new Error(`@vmz/commander: ${kind} helpId must be a catalog key (no spaces); got ${JSON.stringify(helpId)}`);
+    }
+}
+/** Parse `--out-dir <dir>` / `-o, --out-dir <dir>` / `--dirty <path>...` into an OptionDef. */
+export function parseOptionDef(rawName, helpId) {
+    const repeatable = /\.\.\.\s*$/.test(rawName) || /\.\.\.>/.test(rawName) || /\.\.\.]/.test(rawName);
+    const optionalValue = /\[[^\]]+\]/.test(rawName);
+    const takesValue = optionalValue || /<[^>]+>/.test(rawName) || repeatable;
+    const cleaned = rawName
+        .replace(/\.\.\./g, '')
+        .replace(/<[^>]+>|\[[^\]]+\]/g, '')
+        .trim();
+    const parts = cleaned
+        .split(/[,\s]+/)
+        .map((p) => p.trim())
+        .filter(Boolean);
+    const aliases = [];
+    for (const p of parts) {
+        if (p.startsWith('--'))
+            aliases.push(p.slice(2));
+        else if (p.startsWith('-') && p.length > 1)
+            aliases.push(p.slice(1));
+    }
+    if (!aliases.length) {
+        throw new Error(`@vmz/commander: invalid option rawName ${JSON.stringify(rawName)}`);
+    }
+    const key = aliases.find((a) => a.length > 1) ?? aliases[0];
+    return { rawName, helpId, key, aliases, takesValue, optionalValue, repeatable };
+}
+/**
+ * Parse argv against registered options. Throws `unknown_option:…` / `missing_value:…`.
+ */
+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;
+}
+function assignOption(out, def, value) {
+    if (def.repeatable) {
+        const cur = out[def.key];
+        const list = Array.isArray(cur) ? cur : [];
+        list.push(String(value));
+        out[def.key] = list;
+        return;
+    }
+    out[def.key] = value;
+}

package/dist/locales.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Filesystem locales loading for `@vmz/commander`.
+ *
+ * Generic: any product passes a `localesRoot`. This package does **not** ship
+ * product language packs — only tiny English fallbacks for `commander.*` chrome/err ids.
+ */
+import type { LocaleCatalog, LocalizePlugin } from './types.js';
+export type LocalesManifest = {
+    defaultLocale: string;
+    locales: Array<{
+        id: string;
+        label?: string;
+        direction?: string;
+    }>;
+    fallback?: Record<string, string[]>;
+};
+/** Framework chrome / errors — products may override the same ids in their locales/. */
+export declare const COMMANDER_FALLBACK_EN_US: LocaleCatalog;
+export declare function loadLocalesManifest(root: string): LocalesManifest;
+/**
+ * Flatten nested JSON (`{ a: { b: "x" } }` → `a.b`) or pass through flat catalogs.
+ */
+export declare function flattenCatalog(node: unknown, prefix?: string): LocaleCatalog;
+/**
+ * Load (and cache) a locale catalog. Missing locales fall back via manifest.fallback
+ * then `defaultLocale`.
+ */
+export declare function loadCatalog(locale: string, root: string): LocaleCatalog;
+/** Clear caches (tests). */
+export declare function clearLocalesCache(): void;
+export declare function translate(id: string, args: Record<string, string> | undefined, catalog: LocaleCatalog): string;
+/**
+ * Resolve locale from `--locale` / env / manifest.
+ */
+export declare function resolveLocale(opts: {
+    argv?: string[];
+    env?: NodeJS.ProcessEnv;
+    manifest: LocalesManifest;
+    /** Env keys checked in order (default: LOCALE, LANG, LC_ALL). */
+    envKeys?: string[];
+}): string;
+/**
+ * Catalog lookup with commander framework English fallbacks.
+ */
+export declare function translateWithFallback(id: string, args: Record<string, string> | undefined, catalog: LocaleCatalog): string;
+export type CreateLocalizeFromLocalesOptions = {
+    root: string;
+    locale?: string;
+    env?: NodeJS.ProcessEnv;
+    argv?: string[];
+    /** Extra env keys prepended (e.g. `VMZ_LOCALE` for products). */
+    envKeys?: string[];
+    catalog?: LocaleCatalog;
+};
+/**
+ * Build a LocalizePlugin from a locales directory.
+ */
+export declare function createLocalizeFromLocales(opts: CreateLocalizeFromLocalesOptions): LocalizePlugin;

package/dist/locales.js

@@ -0,0 +1,172 @@
+/**
+ * Filesystem locales loading for `@vmz/commander`.
+ *
+ * Generic: any product passes a `localesRoot`. This package does **not** ship
+ * product language packs — only tiny English fallbacks for `commander.*` chrome/err ids.
+ */
+import { existsSync, readdirSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** 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',
+    '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()',
+};
+const catalogCache = new Map();
+const manifestCache = new Map();
+export function loadLocalesManifest(root) {
+    const cached = manifestCache.get(root);
+    if (cached)
+        return cached;
+    const file = path.join(root, 'locales.json');
+    if (!existsSync(file)) {
+        throw new Error(`@vmz/commander: missing locales manifest at ${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}`);
+    }
+    manifestCache.set(root, raw);
+    return raw;
+}
+/**
+ * Flatten nested JSON (`{ a: { b: "x" } }` → `a.b`) or pass through flat catalogs.
+ */
+export function flattenCatalog(node, prefix = '') {
+    const out = {};
+    if (node == null || typeof node !== 'object' || Array.isArray(node))
+        return out;
+    for (const [key, value] of Object.entries(node)) {
+        const id = prefix ? `${prefix}.${key}` : key;
+        if (typeof value === 'string') {
+            out[id] = value;
+        }
+        else if (value && typeof value === 'object' && !Array.isArray(value)) {
+            Object.assign(out, flattenCatalog(value, id));
+        }
+    }
+    return out;
+}
+function loadLocaleDir(root, localeId) {
+    const dir = path.join(root, localeId);
+    if (!existsSync(dir))
+        return {};
+    const out = {};
+    for (const name of readdirSync(dir).sort()) {
+        if (!name.endsWith('.json'))
+            continue;
+        const raw = JSON.parse(readFileSync(path.join(dir, name), 'utf8'));
+        Object.assign(out, flattenCatalog(raw));
+    }
+    return out;
+}
+/**
+ * Load (and cache) a locale catalog. Missing locales fall back via manifest.fallback
+ * then `defaultLocale`.
+ */
+export function loadCatalog(locale, root) {
+    const cacheKey = `${root}::${locale}`;
+    const hit = catalogCache.get(cacheKey);
+    if (hit)
+        return hit;
+    const manifest = loadLocalesManifest(root);
+    const chain = [locale, ...(manifest.fallback?.[locale] ?? []), manifest.defaultLocale];
+    const merged = {};
+    for (const id of [...new Set(chain)].reverse()) {
+        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}`);
+    }
+    catalogCache.set(cacheKey, merged);
+    return merged;
+}
+/** Clear caches (tests). */
+export function clearLocalesCache() {
+    catalogCache.clear();
+    manifestCache.clear();
+}
+export function translate(id, args, catalog) {
+    const template = catalog[id];
+    if (template == null)
+        return `{{${id}}}`;
+    return template.replace(/\{([a-zA-Z0-9_.-]+)\}/g, (_m, name) => {
+        if (args && Object.prototype.hasOwnProperty.call(args, name)) {
+            return args[name] ?? '';
+        }
+        return `{${name}}`;
+    });
+}
+/**
+ * Resolve locale from `--locale` / env / manifest.
+ */
+export function resolveLocale(opts) {
+    const env = opts.env ?? process.env;
+    const argv = opts.argv ?? [];
+    let fromFlag = '';
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        if (a === '--locale' && argv[i + 1] && !argv[i + 1].startsWith('-')) {
+            fromFlag = argv[i + 1];
+            break;
+        }
+        if (a.startsWith('--locale=')) {
+            fromFlag = a.slice('--locale='.length);
+            break;
+        }
+    }
+    const keys = opts.envKeys ?? ['LOCALE', 'LANG', 'LC_ALL'];
+    let fromEnv = '';
+    for (const k of keys) {
+        const v = env[k];
+        if (v) {
+            fromEnv = String(v).split('.')[0]?.replace(/_/g, '-') || '';
+            if (fromEnv)
+                break;
+        }
+    }
+    const raw = fromFlag || fromEnv;
+    if (!raw)
+        return opts.manifest.defaultLocale;
+    const lower = raw.toLowerCase();
+    const known = opts.manifest.locales.map((l) => l.id);
+    const exact = known.find((id) => id.toLowerCase() === lower);
+    if (exact)
+        return exact;
+    const lang = lower.split('-')[0];
+    const prefix = known.find((id) => id.toLowerCase().startsWith(lang));
+    if (prefix)
+        return prefix;
+    return opts.manifest.defaultLocale;
+}
+/**
+ * Catalog lookup with commander framework English fallbacks.
+ */
+export function translateWithFallback(id, args, catalog) {
+    if (Object.prototype.hasOwnProperty.call(catalog, id)) {
+        return translate(id, args, catalog);
+    }
+    if (Object.prototype.hasOwnProperty.call(COMMANDER_FALLBACK_EN_US, id)) {
+        return translate(id, args, COMMANDER_FALLBACK_EN_US);
+    }
+    return `{{${id}}}`;
+}
+/**
+ * Build a LocalizePlugin from a locales directory.
+ */
+export function createLocalizeFromLocales(opts) {
+    const env = opts.env ?? process.env;
+    const argv = opts.argv ?? [];
+    const manifest = loadLocalesManifest(opts.root);
+    const locale = typeof opts.locale === 'string' && opts.locale ? opts.locale : resolveLocale({ argv, env, manifest, envKeys: opts.envKeys });
+    const catalog = opts.catalog ?? loadCatalog(locale, opts.root);
+    return {
+        resolveLocale: () => locale,
+        t: (id, args) => translateWithFallback(id, args, catalog),
+    };
+}

package/dist/types.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Shared types for `@vmz/commander` (kept separate so locales.ts can import without cycles).
+ */
+/** 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}). */
+export type CatalogLoader = (locale: string) => LocaleCatalog | Promise<LocaleCatalog>;
+/**
+ * Pluggable localization. Products and end users supply their own `t` / locale policy.
+ * This package never ships official product language packs.
+ */
+export type LocalizePlugin = {
+    resolveLocale?: (ctx: {
+        argv: string[];
+        env: NodeJS.ProcessEnv;
+    }) => string;
+    t: (id: string, args?: Record<string, string>) => string;
+};

package/dist/types.js

@@ -0,0 +1,4 @@
+/**
+ * Shared types for `@vmz/commander` (kept separate so locales.ts can import without cycles).
+ */
+export {};

package/package.json

@@ -1,10 +1,38 @@
 {
   "name": "@vmz/commander",
-  "version": "0.0.0",
-  "description": "VMZ placeholder ?not for production use.",
+  "version": "0.1.19",
+  "type": "module",
+  "description": "i18n-first TypeScript CLI framework (command tree, locales loading, commander.* chrome)",
   "license": "MIT",
-  "private": false,
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
   "files": [
+    "dist",
     "README.md"
-  ]
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "test": "node --import ../../../scripts/test/resolve-ts-from-js.mjs --test --experimental-strip-types ./tests/locales.test.ts"
+  },
+  "keywords": [
+    "vmz",
+    "cli",
+    "i18n"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/doki-land/vmz-framework.git"
+  }
 }