@optima-chat/commerce-cli 1.0.0

package/dist/utils/helpText.js

@@ -0,0 +1,138 @@
+/**
+ * Add enhanced help text sections to a Commander command
+ *
+ * This utility adds LLM-friendly documentation including:
+ * - Real usage examples
+ * - JSON output structure
+ * - Related commands for workflow guidance
+ * - Important notes and best practices
+ *
+ * @param command - The Commander command to enhance
+ * @param options - Help text content options
+ * @returns The enhanced command (for chaining)
+ *
+ * @example
+ * ```typescript
+ * const cmd = new Command('create')
+ *   .description('Create a product')
+ *   .option('--title <string>', 'Product name (required)')
+ *   .option('--price <number>', 'Product price (required)');
+ *
+ * addEnhancedHelp(cmd, {
+ *   examples: [
+ *     '# Create a basic product',
+ *     '$ commerce product create --title "Mug" --price 29.99',
+ *     '',
+ *     '# Create with JSON output',
+ *     '$ commerce product create --title "Mug" --price 29.99 --json'
+ *   ],
+ *   output: {
+ *     example: JSON.stringify({
+ *       success: true,
+ *       data: { product_id: 'uuid', name: 'Mug', price: '29.99' }
+ *     }, null, 2)
+ *   },
+ *   relatedCommands: [
+ *     { command: 'product list', description: 'View created products' },
+ *     { command: 'upload image', description: 'Upload product images' }
+ *   ],
+ *   notes: [
+ *     'title and price are required parameters',
+ *     'Upload images first to get media IDs'
+ *   ]
+ * });
+ * ```
+ */
+export function addEnhancedHelp(command, options) {
+    command.addHelpText('after', () => {
+        let text = '';
+        // Add Examples section
+        if (options.examples && options.examples.length > 0) {
+            text += '\nExamples:\n';
+            options.examples.forEach((line) => {
+                text += `  ${line}\n`;
+            });
+        }
+        // Add Output section
+        if (options.output) {
+            text += '\nOutput (JSON):\n';
+            if (options.output.description) {
+                text += `  ${options.output.description}\n\n`;
+            }
+            // Indent JSON output
+            const lines = options.output.example.split('\n');
+            lines.forEach((line) => {
+                text += `  ${line}\n`;
+            });
+        }
+        // Add Related Commands section
+        if (options.relatedCommands && options.relatedCommands.length > 0) {
+            text += '\nRelated Commands:\n';
+            options.relatedCommands.forEach((rc) => {
+                const commandPadded = `commerce ${rc.command}`.padEnd(28);
+                text += `  ${commandPadded}${rc.description}\n`;
+            });
+        }
+        // Add Notes section
+        if (options.notes && options.notes.length > 0) {
+            text += '\nNotes:\n';
+            options.notes.forEach((note) => {
+                text += `  - ${note}\n`;
+            });
+        }
+        return text;
+    });
+    return command;
+}
+/**
+ * Standardized output format documentation for success responses
+ */
+export const OUTPUT_SUCCESS_TEMPLATE = {
+    success: true,
+    data: {
+        '...': 'Resource data here',
+    },
+    message: 'Optional success message',
+};
+/**
+ * Standardized output format documentation for error responses
+ */
+export const OUTPUT_ERROR_TEMPLATE = {
+    success: false,
+    error: {
+        code: 'ERROR_CODE',
+        message: 'Error description',
+    },
+};
+/**
+ * Helper to format option description with type and requirement info
+ *
+ * @param description - The option description
+ * @param type - The parameter type (string, number, uuid, etc.)
+ * @param required - Whether the parameter is required
+ * @param defaultValue - Default value if any
+ * @returns Formatted description
+ *
+ * @example
+ * ```typescript
+ * formatOptionDescription('Product name', 'string', true)
+ * // Returns: "Product name (required)"
+ *
+ * formatOptionDescription('Stock quantity', 'number', false, 0)
+ * // Returns: "Stock quantity (default: 0)"
+ * ```
+ */
+export function formatOptionDescription(description, type, required, defaultValue) {
+    let formatted = description;
+    if (type) {
+        formatted = `${formatted} <${type}>`;
+    }
+    if (required) {
+        formatted = `${formatted} (required)`;
+    }
+    else if (defaultValue !== undefined) {
+        formatted = `${formatted} (default: ${defaultValue})`;
+    }
+    return formatted;
+}
+//# sourceMappingURL=helpText.js.map

package/dist/utils/helpText.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"helpText.js","sourceRoot":"","sources":["../../src/utils/helpText.ts"],"names":[],"mappings":"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"}

package/dist/utils/interactive.d.ts

@@ -0,0 +1,60 @@
+/**
+ * 交互式环境检测工具
+ *
+ * 自动检测是否应该使用交互式提示（inquirer）
+ * 在非交互环境（AI、CI/CD）中返回 false
+ */
+/**
+ * 检测当前是否为交互式环境
+ *
+ * @returns true 如果在交互式终端环境，false 如果在非交互环境
+ *
+ * 检测逻辑：
+ * 0. OPTIMA_INTERACTIVE=1 - 显式启用（最高优先级）
+ * 1. process.stdin.isTTY - 标准输入是否为终端
+ * 2. CI 环境变量 - 是否在 CI/CD 环境
+ * 3. 显式禁用标志 - 用户手动禁用交互模式
+ */
+export declare function isInteractiveEnvironment(): boolean;
+/**
+ * 确保参数已提供，否则抛出验证错误
+ *
+ * 在非交互环境中使用此函数代替 inquirer.prompt()
+ *
+ * @param value - 参数值
+ * @param paramName - 参数名称（用于错误消息）
+ * @param friendlyName - 友好名称（用于错误消息）
+ * @returns 去除空格的参数值
+ * @throws ValidationError 如果值为空
+ *
+ * @example
+ * // 非交互模式下验证必需参数
+ * const title = requireParam(options.title, 'title', '商品名称');
+ * // 如果 options.title 为空，抛出：缺少必需参数: --title (商品名称)
+ */
+export declare function requireParam(value: string | undefined | null, paramName: string, friendlyName?: string): string;
+/**
+ * 确保数值参数已提供且有效
+ *
+ * @param value - 参数值
+ * @param paramName - 参数名称
+ * @param friendlyName - 友好名称
+ * @param min - 最小值（可选）
+ * @param max - 最大值（可选）
+ * @returns 解析后的数值
+ * @throws ValidationError 如果值无效
+ *
+ * @example
+ * // 验证价格参数（必须 > 0.01）
+ * const price = requireNumberParam(options.price, 'price', '商品价格', 0.01);
+ *
+ * @example
+ * // 验证库存参数（必须 >= 0）
+ * const stock = requireNumberParam(options.stock, 'stock', '库存数量', 0);
+ *
+ * @example
+ * // 验证重量参数（必须 0.1-1000 kg）
+ * const weight = requireNumberParam(options.weight, 'weight', '重量', 0.1, 1000);
+ */
+export declare function requireNumberParam(value: string | undefined | null, paramName: string, friendlyName?: string, min?: number, max?: number): number;
+//# sourceMappingURL=interactive.d.ts.map

package/dist/utils/interactive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.d.ts","sourceRoot":"","sources":["../../src/utils/interactive.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAIH;;;;;;;;;;GAUG;AACH,wBAAgB,wBAAwB,IAAI,OAAO,CAwClD;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,YAAY,CACxB,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAChC,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,GACtB,MAAM,CASR;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,kBAAkB,CAC9B,KAAK,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,EAChC,SAAS,EAAE,MAAM,EACjB,YAAY,CAAC,EAAE,MAAM,EACrB,GAAG,CAAC,EAAE,MAAM,EACZ,GAAG,CAAC,EAAE,MAAM,GACb,MAAM,CAiCR"}

package/dist/utils/interactive.js

@@ -0,0 +1,118 @@
+/**
+ * 交互式环境检测工具
+ *
+ * 自动检测是否应该使用交互式提示（inquirer）
+ * 在非交互环境（AI、CI/CD）中返回 false
+ */
+import { ValidationError } from './error.js';
+/**
+ * 检测当前是否为交互式环境
+ *
+ * @returns true 如果在交互式终端环境，false 如果在非交互环境
+ *
+ * 检测逻辑：
+ * 0. OPTIMA_INTERACTIVE=1 - 显式启用（最高优先级）
+ * 1. process.stdin.isTTY - 标准输入是否为终端
+ * 2. CI 环境变量 - 是否在 CI/CD 环境
+ * 3. 显式禁用标志 - 用户手动禁用交互模式
+ */
+export function isInteractiveEnvironment() {
+    // 检测 0：显式启用标志（最高优先级）
+    // 允许用户在 CI 环境中强制启用交互模式（用于调试）
+    if (process.env.OPTIMA_INTERACTIVE === '1') {
+        return true;
+    }
+    // 检测 1：标准输入是否为 TTY
+    // 非 TTY 场景：管道、重定向、AI 环境、后台进程
+    if (!process.stdin.isTTY) {
+        return false;
+    }
+    // 检测 2：CI 环境
+    // 常见 CI 环境变量
+    const ciEnvVars = [
+        'CI', // 通用 CI 标志
+        'CONTINUOUS_INTEGRATION', // Jenkins, Travis
+        'BUILD_ID', // Jenkins
+        'GITHUB_ACTIONS', // GitHub Actions
+        'GITLAB_CI', // GitLab CI
+        'CIRCLECI', // CircleCI
+        'TRAVIS', // Travis CI
+    ];
+    for (const envVar of ciEnvVars) {
+        if (process.env[envVar] === 'true' || process.env[envVar] === '1') {
+            return false;
+        }
+    }
+    // 检测 3：显式禁用标志
+    // 用户可以通过环境变量强制禁用交互模式
+    if (process.env.NON_INTERACTIVE === '1' ||
+        process.env.OPTIMA_NON_INTERACTIVE === 'true') {
+        return false;
+    }
+    // 默认：允许交互
+    return true;
+}
+/**
+ * 确保参数已提供，否则抛出验证错误
+ *
+ * 在非交互环境中使用此函数代替 inquirer.prompt()
+ *
+ * @param value - 参数值
+ * @param paramName - 参数名称（用于错误消息）
+ * @param friendlyName - 友好名称（用于错误消息）
+ * @returns 去除空格的参数值
+ * @throws ValidationError 如果值为空
+ *
+ * @example
+ * // 非交互模式下验证必需参数
+ * const title = requireParam(options.title, 'title', '商品名称');
+ * // 如果 options.title 为空，抛出：缺少必需参数: --title (商品名称)
+ */
+export function requireParam(value, paramName, friendlyName) {
+    if (!value || value.trim().length === 0) {
+        const displayName = friendlyName || paramName;
+        throw new ValidationError(`缺少必需参数: --${paramName} (${displayName})`, paramName);
+    }
+    return value.trim();
+}
+/**
+ * 确保数值参数已提供且有效
+ *
+ * @param value - 参数值
+ * @param paramName - 参数名称
+ * @param friendlyName - 友好名称
+ * @param min - 最小值（可选）
+ * @param max - 最大值（可选）
+ * @returns 解析后的数值
+ * @throws ValidationError 如果值无效
+ *
+ * @example
+ * // 验证价格参数（必须 > 0.01）
+ * const price = requireNumberParam(options.price, 'price', '商品价格', 0.01);
+ *
+ * @example
+ * // 验证库存参数（必须 >= 0）
+ * const stock = requireNumberParam(options.stock, 'stock', '库存数量', 0);
+ *
+ * @example
+ * // 验证重量参数（必须 0.1-1000 kg）
+ * const weight = requireNumberParam(options.weight, 'weight', '重量', 0.1, 1000);
+ */
+export function requireNumberParam(value, paramName, friendlyName, min, max) {
+    if (!value || value.trim().length === 0) {
+        const displayName = friendlyName || paramName;
+        throw new ValidationError(`缺少必需参数: --${paramName} (${displayName})`, paramName);
+    }
+    const numValue = parseFloat(value);
+    if (isNaN(numValue)) {
+        throw new ValidationError(`参数 --${paramName} 必须是有效数字: ${value}`, paramName);
+    }
+    if (min !== undefined && numValue < min) {
+        throw new ValidationError(`参数 --${paramName} 必须大于等于 ${min}`, paramName);
+    }
+    if (max !== undefined && numValue > max) {
+        throw new ValidationError(`参数 --${paramName} 必须小于等于 ${max}`, paramName);
+    }
+    return numValue;
+}
+//# sourceMappingURL=interactive.js.map

package/dist/utils/interactive.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"interactive.js","sourceRoot":"","sources":["../../src/utils/interactive.ts"],"names":[],"mappings":"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"}

package/dist/utils/output.d.ts

@@ -0,0 +1,82 @@
+import { Ora } from 'ora';
+/**
+ * 输出格式枚举
+ */
+export declare enum OutputFormat {
+    JSON = "json",
+    PRETTY = "pretty"
+}
+/**
+ * CLI 响应结构
+ */
+export interface CliResponse {
+    success: boolean;
+    data?: any;
+    error?: {
+        code: string;
+        message: string;
+        details?: any;
+    };
+    message?: string;
+}
+/**
+ * Mock Spinner（JSON 模式下不显示 spinner）
+ */
+declare class MockSpinner {
+    succeed(_message?: string): this;
+    fail(_message?: string): this;
+    stop(): this;
+    start(): this;
+    warn(_message?: string): this;
+    info(_message?: string): this;
+}
+/**
+ * 输出管理器
+ */
+export declare class OutputManager {
+    private _format?;
+    constructor();
+    /**
+     * 获取输出格式（延迟初始化）
+     */
+    private ensureFormat;
+    /**
+     * 初始化输出管理器（向后兼容，现在不需要了）
+     * @deprecated 不再需要显式调用
+     */
+    init(_programOpts: any): void;
+    /**
+     * 获取当前输出格式
+     */
+    getFormat(): OutputFormat;
+    /**
+     * 输出成功响应
+     */
+    success(data: any, message?: string): void;
+    /**
+     * 输出错误响应
+     */
+    error(error: Error | string, code?: string): never;
+    /**
+     * 创建 spinner（JSON 模式下返回 mock）
+     */
+    spinner(text: string): Ora | MockSpinner;
+    /**
+     * 判断是否为 JSON 模式
+     */
+    isJson(): boolean;
+    /**
+     * 判断是否为 Pretty 模式
+     */
+    isPretty(): boolean;
+    /**
+     * 输出简单消息（仅 Pretty 模式）
+     */
+    log(message: string, color?: 'green' | 'yellow' | 'red' | 'cyan' | 'gray'): void;
+}
+/**
+ * 全局输出管理器实例
+ */
+export declare const output: OutputManager;
+export {};
+//# sourceMappingURL=output.d.ts.map

package/dist/utils/output.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.d.ts","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"AACA,OAAY,EAAE,GAAG,EAAE,MAAM,KAAK,CAAC;AAE/B;;GAEG;AACH,oBAAY,YAAY;IACtB,IAAI,SAAS;IACb,MAAM,WAAW;CAClB;AAED;;GAEG;AACH,MAAM,WAAW,WAAW;IAC1B,OAAO,EAAE,OAAO,CAAC;IACjB,IAAI,CAAC,EAAE,GAAG,CAAC;IACX,KAAK,CAAC,EAAE;QACN,IAAI,EAAE,MAAM,CAAC;QACb,OAAO,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,GAAG,CAAC;KACf,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;GAEG;AACH,cAAM,WAAW;IACf,OAAO,CAAC,QAAQ,CAAC,EAAE,MAAM;IACzB,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM;IACtB,IAAI;IACJ,KAAK;IACL,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM;IACtB,IAAI,CAAC,QAAQ,CAAC,EAAE,MAAM;CACvB;AAED;;GAEG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,OAAO,CAAC,CAAe;;IAM/B;;OAEG;IACH,OAAO,CAAC,YAAY;IAoBpB;;;OAGG;IACH,IAAI,CAAC,YAAY,EAAE,GAAG;IAItB;;OAEG;IACH,SAAS,IAAI,YAAY;IAKzB;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI;IAgB1C;;OAEG;IACH,KAAK,CAAC,KAAK,EAAE,KAAK,GAAG,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,KAAK;IA2BlD;;OAEG;IACH,OAAO,CAAC,IAAI,EAAE,MAAM,GAAG,GAAG,GAAG,WAAW;IAQxC;;OAEG;IACH,MAAM,IAAI,OAAO;IAKjB;;OAEG;IACH,QAAQ,IAAI,OAAO;IAKnB;;OAEG;IACH,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,KAAK,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI;CAMjF;AAED;;GAEG;AACH,eAAO,MAAM,MAAM,eAAsB,CAAC"}

package/dist/utils/output.js

@@ -0,0 +1,151 @@
+import chalk from 'chalk';
+import ora from 'ora';
+/**
+ * 输出格式枚举
+ */
+export var OutputFormat;
+(function (OutputFormat) {
+    OutputFormat["JSON"] = "json";
+    OutputFormat["PRETTY"] = "pretty";
+})(OutputFormat || (OutputFormat = {}));
+/**
+ * Mock Spinner（JSON 模式下不显示 spinner）
+ */
+class MockSpinner {
+    succeed(_message) { return this; }
+    fail(_message) { return this; }
+    stop() { return this; }
+    start() { return this; }
+    warn(_message) { return this; }
+    info(_message) { return this; }
+}
+/**
+ * 输出管理器
+ */
+export class OutputManager {
+    _format;
+    constructor() {
+        // 延迟初始化，在第一次访问时确定格式
+    }
+    /**
+     * 获取输出格式（延迟初始化）
+     */
+    ensureFormat() {
+        if (this._format !== undefined) {
+            return;
+        }
+        // 优先级：CLI 参数 > 环境变量 > 默认值
+        const args = process.argv;
+        if (args.includes('--json')) {
+            this._format = OutputFormat.JSON;
+        }
+        else if (args.includes('--pretty')) {
+            this._format = OutputFormat.PRETTY;
+        }
+        else {
+            const envFormat = process.env.OPTIMA_CLI_FORMAT?.toLowerCase();
+            this._format = envFormat === 'pretty'
+                ? OutputFormat.PRETTY
+                : OutputFormat.JSON;
+        }
+    }
+    /**
+     * 初始化输出管理器（向后兼容，现在不需要了）
+     * @deprecated 不再需要显式调用
+     */
+    init(_programOpts) {
+        // 保留此方法以向后兼容，但不再需要
+    }
+    /**
+     * 获取当前输出格式
+     */
+    getFormat() {
+        this.ensureFormat();
+        return this._format;
+    }
+    /**
+     * 输出成功响应
+     */
+    success(data, message) {
+        this.ensureFormat();
+        if (this._format === OutputFormat.JSON) {
+            const response = {
+                success: true,
+                data,
+                ...(message && { message })
+            };
+            console.log(JSON.stringify(response, null, 2));
+        }
+        else {
+            // Pretty 模式：由调用方负责格式化输出
+            // 此方法在 Pretty 模式下不输出任何内容
+            // 调用方应该使用原有的格式化逻辑
+        }
+    }
+    /**
+     * 输出错误响应
+     */
+    error(error, code) {
+        this.ensureFormat();
+        const errorObj = typeof error === 'string' ? new Error(error) : error;
+        if (this._format === OutputFormat.JSON) {
+            const response = {
+                success: false,
+                error: {
+                    code: code || errorObj.name || 'UNKNOWN_ERROR',
+                    message: errorObj.message,
+                    ...(process.env.DEBUG === 'true' && {
+                        stack: errorObj.stack,
+                        details: errorObj.details
+                    })
+                }
+            };
+            console.log(JSON.stringify(response, null, 2));
+        }
+        else {
+            // Pretty 模式：使用原有错误处理
+            const { handleError } = require('./error.js');
+            handleError(errorObj);
+        }
+        // 确保函数永远不返回
+        process.exit(1);
+    }
+    /**
+     * 创建 spinner（JSON 模式下返回 mock）
+     */
+    spinner(text) {
+        this.ensureFormat();
+        if (this._format === OutputFormat.JSON) {
+            return new MockSpinner();
+        }
+        return ora(text).start();
+    }
+    /**
+     * 判断是否为 JSON 模式
+     */
+    isJson() {
+        this.ensureFormat();
+        return this._format === OutputFormat.JSON;
+    }
+    /**
+     * 判断是否为 Pretty 模式
+     */
+    isPretty() {
+        this.ensureFormat();
+        return this._format === OutputFormat.PRETTY;
+    }
+    /**
+     * 输出简单消息（仅 Pretty 模式）
+     */
+    log(message, color) {
+        if (this.isPretty()) {
+            const coloredMessage = color ? chalk[color](message) : message;
+            console.log(coloredMessage);
+        }
+    }
+}
+/**
+ * 全局输出管理器实例
+ */
+export const output = new OutputManager();
+//# sourceMappingURL=output.js.map

package/dist/utils/output.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"output.js","sourceRoot":"","sources":["../../src/utils/output.ts"],"names":[],"mappings":"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"}

package/dist/utils/validation.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Supported languages in BCP 47 format
+ */
+export declare const SUPPORTED_LANGUAGES: readonly ["en-US", "es-ES", "ja-JP", "vi-VN", "zh-CN"];
+/**
+ * Validates language code format (BCP 47: xx-XX)
+ * @param languageCode - The language code to validate
+ * @returns true if valid
+ * @throws ValidationError if invalid
+ */
+export declare function validateLanguageCode(languageCode: string): boolean;
+/**
+ * Get language code display name
+ */
+export declare function getLanguageName(code: string): string;
+//# sourceMappingURL=validation.d.ts.map

package/dist/utils/validation.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAEA;;GAEG;AACH,eAAO,MAAM,mBAAmB,wDAMtB,CAAC;AAEX;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAuBlE;AAED;;GAEG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CASpD"}

package/dist/utils/validation.js

@@ -0,0 +1,46 @@
+import { ValidationError } from './error.js';
+/**
+ * Supported languages in BCP 47 format
+ */
+export const SUPPORTED_LANGUAGES = [
+    'en-US',
+    'es-ES',
+    'ja-JP',
+    'vi-VN',
+    'zh-CN',
+];
+/**
+ * Validates language code format (BCP 47: xx-XX)
+ * @param languageCode - The language code to validate
+ * @returns true if valid
+ * @throws ValidationError if invalid
+ */
+export function validateLanguageCode(languageCode) {
+    const trimmed = languageCode.trim();
+    // Check BCP 47 format (xx-XX)
+    const bcp47Pattern = /^[a-z]{2}-[A-Z]{2}$/;
+    if (!bcp47Pattern.test(trimmed)) {
+        throw new ValidationError(`语言代码格式错误。请使用 BCP 47 格式（如 en-US, zh-CN）。\n` +
+            `支持的语言: ${SUPPORTED_LANGUAGES.join(', ')}`, 'lang');
+    }
+    // Check if it's in supported list
+    if (!SUPPORTED_LANGUAGES.includes(trimmed)) {
+        throw new ValidationError(`不支持的语言代码: ${trimmed}\n` +
+            `支持的语言: ${SUPPORTED_LANGUAGES.join(', ')}`, 'lang');
+    }
+    return true;
+}
+/**
+ * Get language code display name
+ */
+export function getLanguageName(code) {
+    const names = {
+        'en-US': 'English (US)',
+        'es-ES': 'Spanish (Spain)',
+        'ja-JP': 'Japanese',
+        'vi-VN': 'Vietnamese',
+        'zh-CN': 'Chinese (Simplified)',
+    };
+    return names[code] || code;
+}
+//# sourceMappingURL=validation.js.map

package/dist/utils/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/utils/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAE7C;;GAEG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAAG;IACjC,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;IACP,OAAO;CACC,CAAC;AAEX;;;;;GAKG;AACH,MAAM,UAAU,oBAAoB,CAAC,YAAoB;IACvD,MAAM,OAAO,GAAG,YAAY,CAAC,IAAI,EAAE,CAAC;IAEpC,8BAA8B;IAC9B,MAAM,YAAY,GAAG,qBAAqB,CAAC;IAC3C,IAAI,CAAC,YAAY,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,eAAe,CACvB,2CAA2C;YAC3C,UAAU,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC1C,MAAM,CACP,CAAC;IACJ,CAAC;IAED,kCAAkC;IAClC,IAAI,CAAC,mBAAmB,CAAC,QAAQ,CAAC,OAAc,CAAC,EAAE,CAAC;QAClD,MAAM,IAAI,eAAe,CACvB,aAAa,OAAO,IAAI;YACxB,UAAU,mBAAmB,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,EAC1C,MAAM,CACP,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC;AACd,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,IAAY;IAC1C,MAAM,KAAK,GAA2B;QACpC,OAAO,EAAE,cAAc;QACvB,OAAO,EAAE,iBAAiB;QAC1B,OAAO,EAAE,UAAU;QACnB,OAAO,EAAE,YAAY;QACrB,OAAO,EAAE,sBAAsB;KAChC,CAAC;IACF,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,IAAI,CAAC;AAC7B,CAAC"}