@qnroa/qtype 0.0.1

package/dist/cli/i18n/shared.js

@@ -0,0 +1,142 @@
+/**
+ * i18n keys shared across commands.
+ *
+ * A key belongs here if:
+ *   - It's referenced by more than one command module (e.g. `opt.help`, `opt.path`)
+ *   - Or it's app-level (e.g. `app.description`, `msg.port.invalid`)
+ *
+ * Command-specific keys (used by only one command) live in that command's i18n.ts.
+ */
+// The zh-CN dictionary is the "type source of truth": its key set is the
+// full shared-key set. Every other locale (en-US, future additions) must
+// declare the exact same keys — enforced via `Record<keyof typeof zhCN, ...>`.
+export const zhCN = {
+    // ── app-level ────────────────────────────────────────
+    'app.description': 'QTYPE LLM Material CLI — 仓库管理 / 发布 / 内容检查',
+    'app.help.examples.title': '示例:',
+    'app.help.more.title': '更多:',
+    'app.help.more.perCommand': "每个命令都有 --help：qtype repo new --help",
+    'app.help.more.docs': '文档：https://www.npmjs.com/package/@qnroa/qtype',
+    'app.help.seeAlso.title': '相关命令:',
+    // ── common options ───────────────────────────────────
+    'opt.help': '显示帮助',
+    'opt.version': '显示版本号',
+    'opt.help.cmdDesc': '显示命令帮助',
+    'opt.lang': '仓库语言 (zh-CN | en-US)',
+    'opt.path': '仓库路径（默认当前目录）',
+    'opt.dryRun': '只报告需要补的文件，不写',
+    'opt.force': '覆盖已有文件',
+    'opt.port': '端口号',
+    'opt.dir': '静态站目录（默认 ./dist）',
+    'opt.repo': '仓库根目录（默认当前目录）',
+    // ── runtime messages ──────────────────────────────────
+    'msg.port.invalid': '端口号必须是 1-65535 的整数',
+    'msg.home.warn': '当前目录是 $HOME，不建议在家目录初始化仓库。建议先 `mkdir my-material && cd my-material`',
+    'msg.debug.stackHint': '设 DEBUG=1 查看堆栈',
+    'msg.err.hint': '提示:',
+    // ── KV / config errors (KvError code → translation) ────
+    'err.kv.key.invalid': "无效的 key: '{raw}'。格式应为点分，如 'cli.lang' / 'publish.password.enabled'",
+    'err.kv.unknown.key': "未知 key '{key}'。已注册: {known}",
+    'err.kv.storage.unavailable': "{scope} 存储不可用（{origin}），当前不在 qtype 仓库里？",
+    'err.kv.storage.parseFailed': "读取失败 {origin}：{reason}",
+    'err.kv.storage.writeFailed': "写入失败 {origin}：{reason}",
+    // ── Schema validator errors (validator return code → translation) ─
+    // KvStore injects `{key}` into vars
+    'err.schema.enum': "'{key}' 的值必须是 {allowed} 之一",
+    'err.schema.nonEmptyString': "'{key}' 必须是非空字符串",
+    'err.schema.bool': "'{key}' 必须是 true 或 false",
+    'err.schema.positiveInt': "'{key}' 必须是正整数",
+    'err.schema.absolutePath': "'{key}' 必须是以 '/' 开头的路径",
+    // ── config CLI command-specific errors (thrown by the action layer) ───
+    'err.config.scope.violation': "'{name}' 是 {allowed}-only，不能写 {attempted} 层",
+    'err.config.unset.ambiguous': "'{raw}' 在 user 和 repo 两层都有，请加 --global 或 --local 明确",
+    'err.config.scope.conflict': '--global 和 --local 互斥，只能给一个',
+    // ── generic fs / action errors ────────────────────────
+    'err.path.notExists': '路径不存在：{path}',
+    'err.file.notFound': '文件不存在：{path}',
+    'err.dir.notEmpty': '目录已存在且非空：{path}',
+    'err.dir.notExists': '目录不存在：{path}',
+    'err.file.exists': '{path} 已存在，加 --force 覆盖',
+    'err.notQtypeRepo': '{path} 不是 qtype 仓库（未找到 QTYPE.md）',
+    'err.repo.invalidName': "无效的仓库名 '{name}'：不能包含路径分隔符（/ 或 \\\\）或 '.' / '..'",
+    'hint.sync.dirExists': '如要在已有仓库上补齐缺失文件，用 `qtype repo sync`',
+    'hint.serve.buildFirst': '先运行 `qtype publish build`',
+    'hint.publish.initFirst': '先运行 `qtype publish init`',
+    'hint.runRepoNew': '先运行 `qtype repo new <name>` 或 `qtype publish init`',
+    // ── commander built-in error translations (see registry/commander-i18n.ts) ───
+    'err.cmd.unknownOption': "未知选项 '{arg1}'",
+    'err.cmd.unknownOption.suggest': "未知选项 '{arg1}'（你是不是想要 {arg2}？）",
+    'err.cmd.unknownCommand': "未知命令 '{arg1}'",
+    'err.cmd.unknownCommand.suggest': "未知命令 '{arg1}'（你是不是想要 {arg2}？）",
+    'err.cmd.missingArgument': "缺少必填参数 '{arg1}'",
+    'err.cmd.missingOption': "缺少必填选项 '{arg1}'",
+    'err.cmd.optionMissingArg': "选项 '{arg1}' 缺少参数值",
+    'err.cmd.invalidArg': "选项 '{arg1}' 的值 '{arg2}' 非法。{arg3}",
+    'err.cmd.conflict': "{arg1} 不能和 {arg2} 同时使用",
+    'err.cmd.tooManyArgs': "参数过多。预期 {arg2} 个，实际 {arg3} 个",
+};
+export const enUS = {
+    // ── app-level ────────────────────────────────────────
+    'app.description': 'QTYPE LLM Material CLI — repo / publish / content',
+    'app.help.examples.title': 'Examples:',
+    'app.help.more.title': 'More:',
+    'app.help.more.perCommand': 'Every command has --help: qtype repo new --help',
+    'app.help.more.docs': 'Docs: https://www.npmjs.com/package/@qnroa/qtype',
+    'app.help.seeAlso.title': 'See also:',
+    // ── common options ───────────────────────────────────
+    'opt.help': 'Show help',
+    'opt.version': 'Show version',
+    'opt.help.cmdDesc': 'Show command help',
+    'opt.lang': 'Repo language (zh-CN | en-US)',
+    'opt.path': 'Repo path (default: current directory)',
+    'opt.dryRun': 'Only report missing files, do not write',
+    'opt.force': 'Overwrite existing files',
+    'opt.port': 'Port number',
+    'opt.dir': 'Static site directory (default: ./dist)',
+    'opt.repo': 'Repo root (default: current directory)',
+    // ── runtime messages ──────────────────────────────────
+    'msg.port.invalid': 'Port must be an integer between 1 and 65535',
+    'msg.home.warn': 'Current directory is $HOME. Initializing a repo in home is not recommended. Try `mkdir my-material && cd my-material` first.',
+    'msg.debug.stackHint': 'Set DEBUG=1 to see the stack',
+    'msg.err.hint': 'hint:',
+    // ── KV / config errors (KvError code → translation) ────
+    'err.kv.key.invalid': "Invalid key: '{raw}'. Expected dot-separated segments (e.g. 'cli.lang' / 'publish.password.enabled')",
+    'err.kv.unknown.key': "Unknown key '{key}'. Registered: {known}",
+    'err.kv.storage.unavailable': '{scope} storage unavailable ({origin}); are you inside a qtype repo?',
+    'err.kv.storage.parseFailed': 'Failed to read {origin}: {reason}',
+    'err.kv.storage.writeFailed': 'Failed to write {origin}: {reason}',
+    // ── Schema validator errors ────
+    // KvStore injects `{key}` into vars
+    'err.schema.enum': "'{key}' must be one of: {allowed}",
+    'err.schema.nonEmptyString': "'{key}' must be a non-empty string",
+    'err.schema.bool': "'{key}' must be true or false",
+    'err.schema.positiveInt': "'{key}' must be a positive integer",
+    'err.schema.absolutePath': "'{key}' must be an absolute path starting with '/'",
+    // ── config CLI command-level errors ────
+    'err.config.scope.violation': "'{name}' is {allowed}-only, cannot write to {attempted} scope",
+    'err.config.unset.ambiguous': "'{raw}' exists in both user and repo scopes; use --global or --local",
+    'err.config.scope.conflict': '--global and --local are mutually exclusive',
+    // ── generic fs / action errors ────────────────────────
+    'err.path.notExists': 'Path does not exist: {path}',
+    'err.file.notFound': 'File not found: {path}',
+    'err.dir.notEmpty': 'Directory already exists and is not empty: {path}',
+    'err.dir.notExists': 'Directory does not exist: {path}',
+    'err.file.exists': '{path} already exists; add --force to overwrite',
+    'err.notQtypeRepo': '{path} is not a qtype repo (no QTYPE.md found)',
+    'err.repo.invalidName': "Invalid repo name '{name}': must not contain path separators (/ or \\\\) or be '.' / '..'",
+    'hint.sync.dirExists': 'To add missing files to an existing repo, use `qtype repo sync`',
+    'hint.serve.buildFirst': 'Run `qtype publish build` first',
+    'hint.publish.initFirst': 'Run `qtype publish init` first',
+    'hint.runRepoNew': 'Run `qtype repo new <name>` or `qtype publish init` first',
+    // ── commander built-in errors (see registry/commander-i18n.ts) ──
+    'err.cmd.unknownOption': "error: unknown option '{arg1}'",
+    'err.cmd.unknownOption.suggest': "error: unknown option '{arg1}' (did you mean {arg2}?)",
+    'err.cmd.unknownCommand': "error: unknown command '{arg1}'",
+    'err.cmd.unknownCommand.suggest': "error: unknown command '{arg1}' (did you mean {arg2}?)",
+    'err.cmd.missingArgument': "error: missing required argument '{arg1}'",
+    'err.cmd.missingOption': "error: required option '{arg1}' not specified",
+    'err.cmd.optionMissingArg': "error: option '{arg1}' argument missing",
+    'err.cmd.invalidArg': "error: option '{arg1}' argument '{arg2}' is invalid. {arg3}",
+    'err.cmd.conflict': "error: {arg1} cannot be used with {arg2}",
+    'err.cmd.tooManyArgs': "error: too many arguments. Expected {arg2}, got {arg3}",
+};

package/dist/cli/index.js

@@ -0,0 +1,79 @@
+#!/usr/bin/env node
+/**
+ * qtype CLI entry point.
+ *
+ * Only does 4 things:
+ *   1. Bootstrap side effect (builds userKv / repoKv singletons)
+ *   2. Create the program, attach top-level options
+ *   3. Mount all top-level commands (from `commands/index.ts`)
+ *   4. Parse argv
+ *
+ * Adding a new command doesn't require touching this file — just edit the
+ * `commands/index.ts` barrel.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { Command } from 'commander';
+import './bootstrap.js'; // Side effect: builds userKv / repoKv singletons
+import { t } from './i18n/index.js';
+import { bold, dim } from './utils/output.js';
+import { mountAll } from './registry/mount.js';
+import { formatTwoColumn, applyRootHelpConfig } from './registry/help.js';
+import { installI18nErrorOutput } from './registry/commander-i18n.js';
+import { allCommands } from './commands/index.js';
+function readVersion() {
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        path.resolve(here, '..', '..', 'package.json'),
+        path.resolve(here, '..', '..', '..', 'package.json'),
+    ];
+    for (const c of candidates) {
+        try {
+            const pkg = JSON.parse(fs.readFileSync(c, 'utf8'));
+            if (typeof pkg.version === 'string')
+                return pkg.version;
+        }
+        catch { /* try next */ }
+    }
+    return '0.0.0';
+}
+const VERSION = readVersion();
+// CLI UI language is resolved by i18n/index.ts at module load (env → config
+// → system locale). Values are BCP 47 codes (`zh-CN` / `en-US`); short
+// codes (`zh` / `en`) are accepted for backwards compatibility. Change
+// persistently with `qtype config set cli.lang <zh-CN|en-US> --global`.
+const program = new Command();
+program
+    .name('qtype')
+    .description(t('app.description'))
+    .version(VERSION, '-v, --version', t('opt.version'))
+    .helpOption('-h, --help', t('opt.help'))
+    .addHelpCommand('help [command]', t('opt.help.cmdDesc'));
+applyRootHelpConfig(program);
+installI18nErrorOutput(program);
+mountAll(program, allCommands);
+// Top-level Examples
+program.addHelpText('after', () => {
+    const examples = formatTwoColumn([
+        ['$ qtype repo new my-material', dim(t('repo.new.summary'))],
+        ['$ qtype init', dim(t('repo.sync.summary'))],
+        ['$ qtype publish build', dim(t('publish.build.summary'))],
+        ['$ qtype config list', dim(t('config.list.summary'))],
+    ]);
+    return ('\n' +
+        bold(t('app.help.examples.title')) +
+        '\n' +
+        examples +
+        '\n\n' +
+        bold(t('app.help.more.title')) +
+        '\n  ' +
+        t('app.help.more.perCommand') +
+        '\n  ' +
+        t('app.help.more.docs') +
+        '\n');
+});
+if (process.argv.length <= 2) {
+    program.help({ error: false });
+}
+program.parse();

package/dist/cli/registry/command.js

@@ -0,0 +1 @@
+export {};

package/dist/cli/registry/commander-i18n.js

@@ -0,0 +1,76 @@
+import { t } from '../i18n/index.js';
+const PATTERNS = [
+    {
+        regex: /^error: unknown option '([^']+)'(?:\s*\(did you mean (.+)\?\))?/,
+        key: 'err.cmd.unknownOption',
+        suggestKey: 'err.cmd.unknownOption.suggest',
+    },
+    {
+        regex: /^error: unknown command '([^']+)'(?:\s*\(did you mean (.+)\?\))?/,
+        key: 'err.cmd.unknownCommand',
+        suggestKey: 'err.cmd.unknownCommand.suggest',
+    },
+    {
+        regex: /^error: missing required argument '([^']+)'/,
+        key: 'err.cmd.missingArgument',
+    },
+    {
+        regex: /^error: required option '([^']+)' not specified/,
+        key: 'err.cmd.missingOption',
+    },
+    {
+        regex: /^error: option '([^']+)' argument missing/,
+        key: 'err.cmd.optionMissingArg',
+    },
+    {
+        regex: /^error: option '([^']+)' argument '([^']+)' is invalid\.?\s*(.*)$/,
+        key: 'err.cmd.invalidArg',
+    },
+    {
+        regex: /^error: (.+?) cannot be used with (.+?)$/,
+        key: 'err.cmd.conflict',
+    },
+    {
+        regex: /^error: too many arguments(?:\s+for '([^']+)')?\.\s*Expected (\d+) argument(?:s)? but got (\d+)\./,
+        key: 'err.cmd.tooManyArgs',
+    },
+];
+/**
+ * Translate a single commander error string. If no pattern matches, return
+ * the original.
+ */
+export function translateCommanderError(raw) {
+    const line = raw.replace(/\n$/, '').trim();
+    for (const p of PATTERNS) {
+        const m = p.regex.exec(line);
+        if (!m)
+            continue;
+        const vars = {};
+        for (let i = 1; i < m.length; i++) {
+            if (m[i] != null)
+                vars[`arg${i}`] = m[i];
+        }
+        // If there's a suggestKey and a suggestion was actually captured, use the suggest variant
+        const key = p.suggestKey && vars['arg2']
+            ? p.suggestKey
+            : p.key;
+        return t(key, vars);
+    }
+    return raw;
+}
+/**
+ * Attach a custom outputError to the program (and to every subcommand):
+ *   English original → translate → emit to stderr
+ *
+ * Note: each subcommand created by `Command.command()` has its own
+ * `_outputConfiguration`, but commander's subcommand **inherits** the parent's
+ * configuration (see `copyInheritedSettings` in command.js). So attaching at
+ * the top-level program is enough.
+ */
+export function installI18nErrorOutput(program) {
+    program.configureOutput({
+        outputError: (str, write) => {
+            write(translateCommanderError(str) + '\n');
+        },
+    });
+}

package/dist/cli/registry/help.js

@@ -0,0 +1,142 @@
+import { bold, dim } from '../utils/output.js';
+import { t } from '../i18n/index.js';
+/**
+ * Global help style. Tweaking these numbers = tweaking the help look of
+ * every command.
+ */
+export const HELP_STYLE = {
+    /** Fixed help width — does not follow terminal resize (so alignment tests stay stable). */
+    helpWidth: 100,
+    /** Minimum number of spaces between Examples' two columns. */
+    twoColumnGap: 3,
+    /** Sort options alphabetically (true) or by registration order (false). */
+    sortOptions: true,
+    /** Sort subcommands alphabetically (false keeps business order: new before sync). */
+    sortSubcommands: false,
+    /** Whether subcommand help re-lists global options (kubectl/gh: false). */
+    showGlobalOptions: false,
+    // ── Field length constraints (used by lint; not enforced at runtime) ──
+    summaryMax: 60,
+    describeMax: 120,
+    optionDescribeMax: 80,
+    exampleDescribeMax: 50,
+};
+/**
+ * Apply CommandModule metadata to a commander node.
+ *
+ * mount.ts calls this to translate summary, describe, long, examples,
+ * seeAlso etc. into commander's help output.
+ */
+export function applyHelpMetadata(cmd, mod) {
+    // summary serves as commander's description (the parent help's list item).
+    // commander also renders it again at the top of the subcommand's help —
+    // so below we use addHelpText('beforeAll') to inject the full describe
+    // and long, and suppress the duplication.
+    cmd.description(mod.summary());
+    cmd.configureHelp({
+        helpWidth: HELP_STYLE.helpWidth,
+        sortOptions: HELP_STYLE.sortOptions,
+        sortSubcommands: HELP_STYLE.sortSubcommands,
+        showGlobalOptions: HELP_STYLE.showGlobalOptions,
+        // In the subcommand list show only the command name, no `[options] [args]`
+        // usage hint. Industry convention (git/kubectl/gh/cargo): keep the
+        // parent's subcommand list clean — the usage hint only shows up on the
+        // `Usage:` line of `--help`.
+        subcommandTerm: (c) => c.name(),
+    });
+    // Top: if describe carries more content than summary, show an extra
+    // paragraph in the help header.
+    const desc = mod.describe();
+    if (desc !== mod.summary()) {
+        cmd.addHelpText('beforeAll', ''); // blank line separator
+        cmd.addHelpText('before', desc + '\n');
+    }
+    // Long description (multi-paragraph).
+    if (mod.long) {
+        const longText = mod.long();
+        if (longText.trim())
+            cmd.addHelpText('before', longText.trim() + '\n');
+    }
+    // Examples — structured array; the renderer aligns them itself
+    const examples = mod.examples?.();
+    if (examples && examples.length > 0) {
+        cmd.addHelpText('after', renderExamples(examples));
+    }
+    // See also
+    if (mod.seeAlso && mod.seeAlso.length > 0) {
+        cmd.addHelpText('after', renderSeeAlso(mod.seeAlso));
+    }
+    // Aliases
+    if (mod.aliases && mod.aliases.length > 0) {
+        for (const alias of mod.aliases)
+            cmd.alias(alias);
+    }
+}
+/**
+ * Help configuration for the root program. Mirrors applyHelpMetadata, but
+ * the latter requires a CommandModule and the root program doesn't have a
+ * matching module — hence a separate entry point.
+ */
+export function applyRootHelpConfig(program) {
+    program.configureHelp({
+        helpWidth: HELP_STYLE.helpWidth,
+        sortOptions: HELP_STYLE.sortOptions,
+        sortSubcommands: HELP_STYLE.sortSubcommands,
+        showGlobalOptions: HELP_STYLE.showGlobalOptions,
+        subcommandTerm: (c) => c.name(),
+    });
+}
+/** Two-column alignment: each row is [command, describe]. Command column width = longest command + gap. */
+export function formatTwoColumn(rows, gap = HELP_STYLE.twoColumnGap) {
+    if (rows.length === 0)
+        return '';
+    const maxLeft = Math.max(...rows.map(([l]) => visualWidth(l)));
+    return rows
+        .map(([l, r]) => {
+        const pad = ' '.repeat(maxLeft - visualWidth(l) + gap);
+        return `  ${l}${pad}${r}`;
+    })
+        .join('\n');
+}
+/**
+ * Compute the "visual width" of a string. CJK characters count as 2
+ * columns; ASCII counts as 1.
+ *
+ * Why this matters: if an example's describe is in Chinese, using
+ * `.length` to count characters severely underestimates width and
+ * alignment goes crooked. This implementation does the simplest CJK
+ * detection — good enough.
+ */
+function visualWidth(s) {
+    let w = 0;
+    for (const ch of s) {
+        const code = ch.codePointAt(0) ?? 0;
+        // Simple version: CJK Unified Ideographs + common full-width ranges
+        if ((code >= 0x1100 && code <= 0x115f) ||
+            (code >= 0x2e80 && code <= 0x9fff) ||
+            (code >= 0xa960 && code <= 0xa97f) ||
+            (code >= 0xac00 && code <= 0xd7a3) ||
+            (code >= 0xf900 && code <= 0xfaff) ||
+            (code >= 0xff00 && code <= 0xff60)) {
+            w += 2;
+        }
+        else {
+            w += 1;
+        }
+    }
+    return w;
+}
+function renderExamples(examples) {
+    const rows = examples.map((e) => [
+        e.command,
+        dim(e.describe()),
+    ]);
+    return '\n' + bold(t('app.help.examples.title')) + '\n' + formatTwoColumn(rows) + '\n';
+}
+function renderSeeAlso(items) {
+    return ('\n' +
+        bold(t('app.help.seeAlso.title')) +
+        '\n' +
+        items.map((i) => `  qtype ${i}`).join('\n') +
+        '\n');
+}

package/dist/cli/registry/mount.js

@@ -0,0 +1,71 @@
+/**
+ * mount(): hangs a CommandModule onto a commander Command.
+ *
+ * Responsibility split:
+ *   - This file: recursive mounting; handles "input" metadata like
+ *     args/options/action
+ *   - `help.ts`: handles help output (summary/describe/long/examples/seeAlso/...)
+ *   - `command.ts`: defines the CommandModule interface
+ *
+ * Command modules themselves **do not import commander** — this file is the
+ * sole glue layer.
+ */
+import { InvalidArgumentError, Option } from 'commander';
+import { extend, t } from '../i18n/index.js';
+import { wrapAction } from '../utils/output.js';
+import { applyHelpMetadata } from './help.js';
+/** Hang a single CommandModule onto a parent commander node. */
+export function mount(parent, mod) {
+    // 1. Merge i18n (must happen before reading any describe)
+    if (mod.messages)
+        extend(mod.messages);
+    const cmd = parent
+        .command(mod.name)
+        .helpOption('-h, --help', t('opt.help'));
+    // 2. Positional arguments
+    for (const a of mod.args ?? []) {
+        cmd.argument(a.flag, a.describe());
+    }
+    // 3. Options
+    for (const o of mod.options ?? []) {
+        cmd.addOption(buildOption(o));
+    }
+    // 4. Recurse into subcommands
+    for (const sub of mod.subcommands ?? []) {
+        mount(cmd, sub);
+    }
+    // 5. Help metadata (description / long / examples / seeAlso / aliases)
+    applyHelpMetadata(cmd, mod);
+    // 6. Action
+    if (mod.action) {
+        cmd.action(wrapAction(mod.action));
+    }
+    return cmd;
+}
+/** Mount the top-level command list onto the program. */
+export function mountAll(program, modules) {
+    for (const m of modules)
+        mount(program, m);
+}
+function buildOption(o) {
+    const opt = new Option(o.flags, o.describe());
+    if (o.choices)
+        opt.choices([...o.choices]);
+    if (o.defaultValue !== undefined)
+        opt.default(o.defaultValue);
+    if (o.parser)
+        opt.argParser(wrapParser(o.parser));
+    return opt;
+}
+function wrapParser(parser) {
+    return (v) => {
+        try {
+            return parser(v);
+        }
+        catch (e) {
+            if (e instanceof InvalidArgumentError)
+                throw e;
+            throw new InvalidArgumentError(e instanceof Error ? e.message : String(e));
+        }
+    };
+}

package/dist/cli/utils/output.js

@@ -0,0 +1,92 @@
+/**
+ * Unified CLI output utilities: colors, symbols, error exits.
+ */
+import { KvError } from '../../store/index.js';
+import { t } from '../i18n/index.js';
+const RESET = '\x1b[0m';
+const RED = '\x1b[31m';
+const YELLOW = '\x1b[33m';
+const GREEN = '\x1b[32m';
+const CYAN = '\x1b[36m';
+const DIM = '\x1b[2m';
+const BOLD = '\x1b[1m';
+// Detect whether the terminal supports color (disabled when not a TTY or when NO_COLOR is set)
+const supportsColor = process.stdout.isTTY === true && process.env.NO_COLOR == null;
+function colorize(code, text) {
+    if (!supportsColor)
+        return text;
+    return `${code}${text}${RESET}`;
+}
+/** Error message (red ✗) */
+export function error(message) {
+    console.error(`${colorize(RED, '✗')} ${message}`);
+}
+/** Warning message (yellow ⚠) */
+export function warn(message) {
+    console.warn(`${colorize(YELLOW, '⚠')} ${message}`);
+}
+/** Success message (green ✓) */
+export function success(message) {
+    console.log(`${colorize(GREEN, '✓')} ${message}`);
+}
+/** Info message (ℹ prefix, cyan) */
+export function info(message) {
+    console.log(`${colorize(CYAN, 'ℹ')} ${message}`);
+}
+/** Dim message (secondary information) */
+export function dim(message) {
+    return colorize(DIM, message);
+}
+/** Bold */
+export function bold(text) {
+    return colorize(BOLD, text);
+}
+/** Direct color helpers (used by some commands that need inline color). */
+export const green = (s) => colorize(GREEN, s);
+export const red = (s) => colorize(RED, s);
+export const yellow = (s) => colorize(YELLOW, s);
+export const cyan = (s) => colorize(CYAN, s);
+/**
+ * Report a fatal error and exit (exit code = 1).
+ * Format: red ✗ at the start, with an optional hint.
+ */
+export function fatal(message, hint) {
+    error(message);
+    if (hint)
+        console.error(`  ${dim(t('msg.err.hint'))} ${hint}`);
+    process.exit(1);
+}
+/**
+ * Wrap a command action so uncaught exceptions become friendly error
+ * output.
+ *
+ * - `KvError` gets special handling: goes through i18n (err.code → t()
+ *   dictionary lookup)
+ * - Other `Error`s use `message` directly
+ *
+ * No stack trace in production; set DEBUG=1 to print the stack for
+ * debugging.
+ */
+export function wrapAction(fn) {
+    return async (...args) => {
+        try {
+            await fn(...args);
+        }
+        catch (err) {
+            if (err instanceof KvError) {
+                error(t(err.code, err.vars));
+            }
+            else {
+                const e = err;
+                error(e.message || String(e));
+            }
+            if (process.env.DEBUG) {
+                console.error(dim(err.stack ?? ''));
+            }
+            else {
+                console.error(`  ${dim(t('msg.debug.stackHint'))}`);
+            }
+            process.exit(1);
+        }
+    };
+}

package/dist/cli/utils/paths.js

@@ -0,0 +1,13 @@
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * Resolve the path to a bundled resource (templates/, examples/) relative to
+ * the CLI's install location. Works both from source (src/cli/) and dist
+ * (dist/cli/).
+ */
+export function resolveBundle(relative) {
+    // this file at: src/cli/utils/paths.ts  → up 3 → package root
+    // this file at: dist/cli/utils/paths.js → up 3 → package root
+    const here = path.dirname(fileURLToPath(import.meta.url));
+    return path.resolve(here, '..', '..', '..', relative);
+}