@coze-arch/cli 0.0.1-alpha.035e0e

package/lib/cli.js

@@ -0,0 +1,1916 @@
+#!/usr/bin/env node
+'use strict';
+
+var commander = require('commander');
+var path = require('path');
+var fs = require('fs');
+var shelljs = require('shelljs');
+var perf_hooks = require('perf_hooks');
+var fs$1 = require('fs/promises');
+var os = require('os');
+var toml = require('@iarna/toml');
+var jsYaml = require('js-yaml');
+var child_process = require('child_process');
+var addFormats = require('ajv-formats');
+var Ajv = require('ajv');
+var minimist = require('minimist');
+var changeCase = require('change-case');
+var ejs = require('ejs');
+
+/**
+ * 读取 templates.json 配置
+ */
+const loadTemplatesConfig$1 = () => {
+  // 尝试多个可能的路径
+  const possiblePaths = [
+    // 生产模式：lib/cli.js 打包后
+    path.join(__dirname, '__templates__/templates.json'),
+    // 开发模式：src/utils/template-help.ts
+    path.join(__dirname, '../__templates__/templates.json'),
+  ];
+
+  for (const templatesPath of possiblePaths) {
+    try {
+      const content = fs.readFileSync(templatesPath, 'utf-8');
+      // eslint-disable-next-line no-restricted-syntax
+      return JSON.parse(content) ;
+    } catch (error) {
+      // 继续尝试下一个路径
+      continue;
+    }
+  }
+
+  // 所有路径都失败，返回 null
+  return null;
+};
+
+/**
+ * 格式化单个参数信息
+ */
+const formatParam = (paramName, param) => {
+  const parts = [];
+
+  // 参数名和类型
+  parts.push(`      --${paramName} <${param.type}>`);
+
+  // 描述
+  if (param.description) {
+    parts.push(`        ${param.description}`);
+  }
+
+  // 默认值
+  if (param.default !== undefined) {
+    parts.push(`        Default: ${param.default}`);
+  }
+
+  // 范围限制
+  if (param.minimum !== undefined || param.maximum !== undefined) {
+    const range = [];
+    if (param.minimum !== undefined) {
+      range.push(`min: ${param.minimum}`);
+    }
+    if (param.maximum !== undefined) {
+      range.push(`max: ${param.maximum}`);
+    }
+    parts.push(`        Range: ${range.join(', ')}`);
+  }
+
+  // 模式限制
+  if (param.pattern) {
+    parts.push(`        Pattern: ${param.pattern}`);
+  }
+
+  return parts.join('\n');
+};
+
+/**
+ * 生成模板帮助文本
+ */
+const generateTemplatesHelpText = () => {
+  const config = loadTemplatesConfig$1();
+
+  if (!config || config.templates.length === 0) {
+    return '';
+  }
+
+  const lines = [];
+
+  lines.push('\n📦 Available Templates:\n');
+  lines.push(`  ${'='.repeat(76)}`);
+
+  config.templates.forEach((template, index) => {
+    if (index > 0) {
+      lines.push(`  ${'-'.repeat(76)}`);
+    }
+
+    lines.push(`\n  Template: ${template.name}`);
+    lines.push(`    Description: ${template.description}`);
+
+    const params = Object.entries(template.paramsSchema);
+    if (params.length > 0) {
+      lines.push('    Parameters:');
+      params.forEach(([paramName, param]) => {
+        lines.push(formatParam(paramName, param));
+      });
+    }
+  });
+
+  lines.push(`\n  ${'='.repeat(76)}`);
+  lines.push('\n  Usage:');
+  lines.push(
+    '    coze init <directory> -t <template-name> [--param value ...]',
+  );
+  lines.push('\n  Example:');
+  lines.push('    coze init my-app -t nextjs --appName my-app --port 3000');
+  lines.push('');
+
+  return lines.join('\n');
+};
+
+function _nullishCoalesce$2(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain$3(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }var LogLevel; (function (LogLevel) {
+  const ERROR = 0; LogLevel[LogLevel["ERROR"] = ERROR] = "ERROR";
+  const WARN = 1; LogLevel[LogLevel["WARN"] = WARN] = "WARN";
+  const SUCCESS = 2; LogLevel[LogLevel["SUCCESS"] = SUCCESS] = "SUCCESS";
+  const INFO = 3; LogLevel[LogLevel["INFO"] = INFO] = "INFO";
+  const VERBOSE = 4; LogLevel[LogLevel["VERBOSE"] = VERBOSE] = "VERBOSE";
+})(LogLevel || (LogLevel = {}));
+
+
+
+
+
+
+
+const LOG_LEVEL_MAP = {
+  error: LogLevel.ERROR,
+  warn: LogLevel.WARN,
+  success: LogLevel.SUCCESS,
+  info: LogLevel.INFO,
+  verbose: LogLevel.VERBOSE,
+};
+
+const COLOR_CODES = {
+  reset: '\x1b[0m',
+  red: '\x1b[31m',
+  yellow: '\x1b[33m',
+  green: '\x1b[32m',
+  cyan: '\x1b[36m',
+  gray: '\x1b[90m',
+};
+
+class Logger {
+  
+  
+  
+
+  constructor(options = {}) {
+    this.level = this.parseLogLevel(options.level);
+    this.useColor = _nullishCoalesce$2(options.useColor, () => ( this.isColorSupported()));
+    this.prefix = options.prefix;
+  }
+
+   parseLogLevel(level) {
+    if (level !== undefined) {
+      return level;
+    }
+
+    const envLevel = _optionalChain$3([process, 'access', _ => _.env, 'access', _2 => _2.LOG_LEVEL, 'optionalAccess', _3 => _3.toLowerCase, 'call', _4 => _4()]);
+    if (envLevel && envLevel in LOG_LEVEL_MAP) {
+      return LOG_LEVEL_MAP[envLevel];
+    }
+
+    return LogLevel.INFO;
+  }
+
+   isColorSupported() {
+    // 简单检测：Node.js 环境且支持 TTY
+    return (
+      typeof process !== 'undefined' &&
+      _optionalChain$3([process, 'access', _5 => _5.stdout, 'optionalAccess', _6 => _6.isTTY]) === true &&
+      process.env.NO_COLOR === undefined
+    );
+  }
+
+   colorize(text, color) {
+    if (!this.useColor) {
+      return text;
+    }
+    return `${COLOR_CODES[color]}${text}${COLOR_CODES.reset}`;
+  }
+
+   log(options
+
+
+
+
+
+) {
+    if (options.level > this.level) {
+      return;
+    }
+
+    const icon = this.colorize(options.icon, options.color);
+    const prefix = this.prefix ? `${icon} ${this.prefix}` : icon;
+    console.log(prefix, options.message, ...(_nullishCoalesce$2(options.args, () => ( []))));
+  }
+
+  error(message, ...args) {
+    this.log({
+      level: LogLevel.ERROR,
+      icon: '✖',
+      color: 'red',
+      message,
+      args,
+    });
+  }
+
+  warn(message, ...args) {
+    this.log({
+      level: LogLevel.WARN,
+      icon: '⚠',
+      color: 'yellow',
+      message,
+      args,
+    });
+  }
+
+  success(message, ...args) {
+    this.log({
+      level: LogLevel.SUCCESS,
+      icon: '✓',
+      color: 'green',
+      message,
+      args,
+    });
+  }
+
+  info(message, ...args) {
+    this.log({
+      level: LogLevel.INFO,
+      icon: 'ℹ',
+      color: 'cyan',
+      message,
+      args,
+    });
+  }
+
+  verbose(message, ...args) {
+    this.log({
+      level: LogLevel.VERBOSE,
+      icon: '→',
+      color: 'gray',
+      message,
+      args,
+    });
+  }
+}
+
+// 创建 logger 实例的工厂函数
+const createLogger = (options = {}) =>
+  new Logger(options);
+
+// 导出默认实例
+const logger = createLogger();
+
+/**
+ * 时间统计工具
+ */
+class TimeTracker {
+  
+  
+
+  constructor() {
+    this.startTime = perf_hooks.performance.now();
+    this.lastTime = this.startTime;
+  }
+
+  /**
+   * 记录阶段耗时
+   * @param phaseName 阶段名称
+   */
+  logPhase(phaseName) {
+    const now = perf_hooks.performance.now();
+    const phaseTime = now - this.lastTime;
+    this.lastTime = now;
+
+    logger.verbose(`⏱ ${phaseName}: ${phaseTime.toFixed(2)}ms`);
+  }
+
+  /**
+   * 记录总耗时
+   */
+  logTotal() {
+    const totalTime = perf_hooks.performance.now() - this.startTime;
+    logger.verbose(`⏱ Total time: ${totalTime.toFixed(2)}ms`);
+  }
+
+  /**
+   * 获取当前耗时（不输出日志）
+   * @returns 从开始到现在的总耗时（毫秒）
+   */
+  getElapsedTime() {
+    return perf_hooks.performance.now() - this.startTime;
+  }
+}
+
+/**
+ * 获取模板配置文件路径
+ * @returns templates.json 的绝对路径
+ */
+const getTemplatesConfigPath = () => {
+  const configPath = path.resolve(getTemplatesDir(), 'templates.json');
+  logger.verbose(`Templates config path: ${configPath}`);
+  logger.verbose(`Config file exists: ${fs.existsSync(configPath)}`);
+  return configPath;
+};
+
+/**
+ * 获取模板目录路径
+ * @returns __templates__ 目录的绝对路径
+ */
+const getTemplatesDir = () => {
+  const templatesDir = path.resolve(__dirname, './__templates__');
+  logger.verbose(`Templates directory: ${templatesDir}`);
+  logger.verbose(`Templates directory exists: ${fs.existsSync(templatesDir)}`);
+  return templatesDir;
+};
+
+/**
+ * 加载模板配置文件
+ * 支持 .ts 和 .js 文件（通过 sucrase 注册）
+ *
+ * @param templatePath - 模板目录路径
+ * @returns 模板配置对象
+ */
+
+const loadTemplateConfig = async ( 
+  templatePath,
+) => {
+  logger.verbose(`Loading template config from: ${templatePath}`);
+
+  const tsConfigPath = path.join(templatePath, 'template.config.ts');
+  const jsConfigPath = path.join(templatePath, 'template.config.js');
+
+  logger.verbose('Checking for config files:');
+  logger.verbose(`  - TypeScript: ${tsConfigPath}`);
+  logger.verbose(`  - JavaScript: ${jsConfigPath}`);
+
+  let configPath;
+
+  const [tsExists, jsExists] = await Promise.all([
+    fs$1.access(tsConfigPath).then(
+      () => true,
+      () => false,
+    ),
+    fs$1.access(jsConfigPath).then(
+      () => true,
+      () => false,
+    ),
+  ]);
+
+  logger.verbose('Config file existence check:');
+  logger.verbose(`  - template.config.ts: ${tsExists}`);
+  logger.verbose(`  - template.config.js: ${jsExists}`);
+
+  if (tsExists) {
+    configPath = tsConfigPath;
+  } else if (jsExists) {
+    configPath = jsConfigPath;
+  } else {
+    throw new Error(
+      `Template config not found in ${templatePath}.\n` +
+        'Expected: template.config.ts or template.config.js',
+    );
+  }
+
+  logger.verbose(`Using config file: ${configPath}`);
+
+  // eslint-disable-next-line @typescript-eslint/no-require-imports, security/detect-non-literal-require -- Sucrase handles .ts files at runtime, path is validated above
+  const config = require(configPath);
+
+  logger.verbose('Template config loaded successfully');
+
+  return config.default || config;
+};
+
+/**
+ * 加载模板列表配置
+ *
+ * @param configPath - templates.json 配置文件路径
+ * @returns 模板列表配置
+ */
+const loadTemplatesConfig = async (
+  configPath,
+) => {
+  logger.verbose(`Loading templates config from: ${configPath}`);
+
+  const content = await fs$1.readFile(configPath, 'utf-8');
+  // eslint-disable-next-line no-restricted-syntax -- Static config file loaded at build time, safeJsonParse not needed
+  const config = JSON.parse(content) ;
+
+  logger.verbose(
+    `Found ${config.templates.length} templates: ${config.templates.map(t => t.name).join(', ')}`,
+  );
+
+  return config;
+};
+
+/**
+ * 根据模板名称查找模板元信息
+ *
+ * @param templatesConfig - 模板列表配置
+ * @param templateName - 模板名称
+ * @returns 模板元信息
+ */
+const findTemplate = (
+  templatesConfig,
+  templateName,
+) => {
+  const template = templatesConfig.templates.find(t => t.name === templateName);
+
+  if (!template) {
+    const availableTemplates = templatesConfig.templates
+      .map(t => t.name)
+      .join(', ');
+    throw new Error(
+      `Template "${templateName}" not found.\n` +
+        `Available templates: ${availableTemplates}\n` +
+        'Use --template <name> to specify a template.',
+    );
+  }
+
+  return template;
+};
+
+/**
+ * 获取模板的完整路径
+ *
+ * @param basePath - 模板目录（templates.json 所在目录）
+ * @param templateMetadata - 模板元信息
+ * @returns 模板完整路径
+ */
+const getTemplatePath = async (
+  basePath,
+  templateMetadata,
+) => {
+  logger.verbose('Resolving template path:');
+  logger.verbose(`  - Base path: ${basePath}`);
+  logger.verbose(`  - Template location: ${templateMetadata.location}`);
+
+  // location 是相对于 templates.json 文件的路径
+  const templatePath = path.join(basePath, templateMetadata.location);
+
+  logger.verbose(`  - Resolved path: ${templatePath}`);
+
+  try {
+    await fs$1.access(templatePath);
+    logger.verbose('  - Template directory exists: ✓');
+    // eslint-disable-next-line @coze-arch/use-error-in-catch -- Error handling done in throw statement
+  } catch (e) {
+    logger.error('  - Template directory does not exist: ✗');
+    throw new Error(`Template directory not found: ${templatePath}`);
+  }
+
+  return templatePath;
+};
+
+/**
+ * 对单个模板执行 pnpm install
+ */
+const warmupTemplate = (templatePath, templateName) => {
+  logger.info(`\nWarming up template: ${templateName}`);
+  logger.info(`  Path: ${templatePath}`);
+
+  const result = shelljs.exec('pnpm install', {
+    cwd: templatePath,
+    silent: true,
+  });
+
+  // 输出 stdout
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+
+  // 输出 stderr
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  if (result.code === 0) {
+    logger.success(`  ✓ ${templateName} warmed up successfully`);
+  } else {
+    const errorMessage = [
+      `pnpm install failed for ${templateName} with exit code ${result.code}`,
+      result.stderr ? `\nStderr:\n${result.stderr}` : '',
+      result.stdout ? `\nStdout:\n${result.stdout}` : '',
+    ]
+      .filter(Boolean)
+      .join('');
+
+    throw new Error(errorMessage);
+  }
+};
+
+/**
+ * 执行 warmup 命令的内部实现
+ */
+const executeWarmup = async (
+  options
+
+,
+
+  command,
+) => {
+  const timer = new TimeTracker();
+
+  try {
+    const { template: templateFilter } = options;
+
+    logger.info('Starting template warmup...');
+    timer.logPhase('Initialization');
+
+    // 加载模板配置
+    const configPath = getTemplatesConfigPath();
+    const templatesConfig = await loadTemplatesConfig(configPath);
+
+    logger.verbose(
+      `Found ${templatesConfig.templates.length} templates in config`,
+    );
+
+    // 过滤模板
+    const templatesToWarmup = templateFilter
+      ? templatesConfig.templates.filter(t => t.name === templateFilter)
+      : templatesConfig.templates;
+
+    if (templatesToWarmup.length === 0) {
+      if (templateFilter) {
+        logger.warn(`Template "${templateFilter}" not found`);
+        logger.info(
+          `Available templates: ${templatesConfig.templates.map(t => t.name).join(', ')}`,
+        );
+      } else {
+        logger.warn('No templates found');
+      }
+      return;
+    }
+
+    logger.info(
+      `\nWill warm up ${templatesToWarmup.length} template(s): ${templatesToWarmup.map(t => t.name).join(', ')}`,
+    );
+
+    // 获取模板基础路径
+    const basePath = configPath.replace(/\/templates\.json$/, '');
+
+    // 对每个模板执行 pnpm install
+    for (const templateMetadata of templatesToWarmup) {
+      const templatePath = await getTemplatePath(basePath, templateMetadata);
+      warmupTemplate(templatePath, templateMetadata.name);
+      timer.logPhase(`Warmup ${templateMetadata.name}`);
+    }
+
+    logger.success('\n✅ All templates warmed up successfully!');
+    logger.info(
+      '\nNext time you run `coze init`, it will be much faster as node_modules are pre-installed.',
+    );
+
+    timer.logTotal();
+  } catch (error) {
+    timer.logTotal();
+    logger.error('Failed to warmup templates:');
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+};
+
+/**
+ * 注册 warmup 命令到 program
+ */
+const registerCommand$2 = program => {
+  program
+    .command('warmup')
+    .description('Pre-install dependencies for templates to speed up init')
+    .option('-t, --template <name>', 'Warmup a specific template only')
+    .action(async (options, command) => {
+      await executeWarmup(options);
+    });
+};
+
+function _optionalChain$2(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }/* eslint-disable @typescript-eslint/no-explicit-any */
+// Safe JSON parsing utilities with type safety and error handling
+// Provides fallback values, validation, and error monitoring capabilities
+
+/**
+ * Options for safe JSON parsing
+ */
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+/**
+ * Safely parse JSON with error handling and type safety
+ *
+ * @example
+ * ```ts
+ * // Basic usage - returns unknown | undefined
+ * const data = safeJsonParse('{"a":1}'); // { a: 1 }
+ *
+ * // With default value - always returns T
+ * const config = safeJsonParse(str, {});
+ * const user = safeJsonParse(str, null);
+ *
+ * // With error reporting
+ * const data = safeJsonParse(input, null, {
+ *   onError: (error, input) => logger.error('Parse failed', { error, input })
+ * });
+ *
+ * // With validation
+ * const isUser = (data: unknown): data is User => ...;
+ * const user = safeJsonParse<User>(input, null, { validate: isUser });
+ * ```
+ */
+function safeJsonParse(
+  input,
+  defaultValueOrOptions,
+  optionsArg,
+) {
+  // Parse arguments
+  let defaultValue;
+  let options;
+
+  if (arguments.length === 2) {
+    // safeJsonParse(input, options) or safeJsonParse(input, defaultValue)
+    {
+      defaultValue = defaultValueOrOptions ;
+      options = undefined;
+    }
+  } else if (arguments.length === 3) {
+    // safeJsonParse(input, defaultValue, options)
+    defaultValue = defaultValueOrOptions ;
+    options = optionsArg;
+  }
+
+  // If input is already an object (and not null), return it directly
+  if (typeof input === 'object' && input !== null) {
+    return input ;
+  }
+
+  try {
+    const parsed = JSON.parse(String(input));
+
+    // Optional validation
+    if (_optionalChain$2([options, 'optionalAccess', _ => _.validate])) {
+      if (options.validate(parsed)) {
+        return parsed;
+      } else {
+        const validationError = new Error('JSON validation failed');
+        _optionalChain$2([options, 'access', _2 => _2.onError, 'optionalCall', _3 => _3(validationError, input)]);
+
+        if (options.throwOnValidationError) {
+          throw validationError;
+        }
+        return defaultValue;
+      }
+    }
+
+    return parsed;
+  } catch (error) {
+    // Re-throw validation errors when throwOnValidationError is true
+    if (error instanceof Error && error.message === 'JSON validation failed' && _optionalChain$2([options, 'optionalAccess', _4 => _4.throwOnValidationError])) {
+      throw error;
+    }
+    _optionalChain$2([options, 'optionalAccess', _5 => _5.onError, 'optionalCall', _6 => _6(error , input)]);
+    return defaultValue;
+  }
+}
+
+function _optionalChain$1(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+
+/**
+ * 检测并解析配置文件内容
+ *
+ * @param content - 文件内容
+ * @returns 解析后的配置对象
+ */
+const parseConfigContent = (content) => {
+  // 1. 尝试 TOML 格式 (默认)
+  try {
+    const config = toml.parse(content);
+    return config ;
+  } catch (error) {
+    // TOML 解析失败，继续尝试其他格式
+    // eslint-disable-next-line no-console
+    console.debug('TOML parse failed:', error);
+  }
+
+  // 2. 尝试 YAML 格式
+  try {
+    const config = jsYaml.load(content);
+    if (config && typeof config === 'object') {
+      return config ;
+    }
+  } catch (error) {
+    // YAML 解析失败，继续尝试其他格式
+    // eslint-disable-next-line no-console
+    console.debug('YAML parse failed:', error);
+  }
+
+  // 3. 尝试 JSON 格式
+  const config = safeJsonParse(content);
+  if (config) {
+    return config;
+  }
+
+  return null;
+};
+
+/**
+ * 加载 .coze 配置文件
+ *
+ * @param projectPath - 项目目录路径
+ * @returns .coze 配置对象
+ */
+const loadCozeConfig = async (
+  projectPath = process.cwd(),
+) => {
+  const cozeConfigPath = path.join(projectPath, '.coze');
+
+  let content;
+  try {
+    content = await fs$1.readFile(cozeConfigPath, 'utf-8');
+  } catch (error) {
+    throw new Error(
+      `.coze config file not found in ${projectPath}\n` +
+        'Please ensure you are in a project directory initialized with coze-coding.\n' +
+        `Error: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  const config = parseConfigContent(content);
+  if (!config) {
+    throw new Error(
+      'Failed to parse .coze config file.\n' +
+        'Please ensure the file is in valid TOML, YAML, or JSON format.',
+    );
+  }
+
+  return config;
+};
+
+/**
+ * 获取指定命令的配置
+ *
+ * @param config - .coze 配置对象
+ * @param commandName - 命令名称 (dev/build/start)
+ * @returns 命令配置数组
+ */
+const getCommandConfig = (
+  config,
+  commandName,
+) => {
+  let commandConfig;
+
+  // 根据命令名称映射到配置路径
+  switch (commandName) {
+    case 'dev':
+      commandConfig = _optionalChain$1([config, 'access', _ => _.dev, 'optionalAccess', _2 => _2.run]);
+      break;
+    case 'build':
+      commandConfig = _optionalChain$1([config, 'access', _3 => _3.deploy, 'optionalAccess', _4 => _4.build]);
+      break;
+    case 'start':
+      commandConfig = _optionalChain$1([config, 'access', _5 => _5.deploy, 'optionalAccess', _6 => _6.run]);
+      break;
+    default:
+      throw new Error(`Unknown command: ${commandName}`);
+  }
+
+  if (!commandConfig || commandConfig.length === 0) {
+    throw new Error(
+      `Command '${commandName}' is not configured in .coze file.\n` +
+        'Please add the corresponding configuration to your .coze file.',
+    );
+  }
+
+  return commandConfig;
+};
+
+function _nullishCoalesce$1(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain(ops) { let lastAccessLHS = undefined; let value = ops[0]; let i = 1; while (i < ops.length) { const op = ops[i]; const fn = ops[i + 1]; i += 2; if ((op === 'optionalAccess' || op === 'optionalCall') && value == null) { return undefined; } if (op === 'access' || op === 'optionalAccess') { lastAccessLHS = value; value = fn(value); } else if (op === 'call' || op === 'optionalCall') { value = fn((...args) => value.call(lastAccessLHS, ...args)); lastAccessLHS = undefined; } } return value; }
+
+/**
+ * 日志文件名常量
+ */
+const LOG_FILE_NAME = 'dev.log';
+
+/**
+ * 获取日志目录
+ * 优先使用环境变量 COZE_LOG_DIR，否则使用 ~/.coze-logs
+ */
+const getLogDir = () =>
+  process.env.COZE_LOG_DIR || path.join(os.homedir(), '.coze-logs');
+
+/**
+ * 解析日志文件路径
+ * - 如果是绝对路径，直接使用
+ * - 如果是相对路径，基于 getLogDir() + 相对路径
+ * - 如果为空，使用 getLogDir() + LOG_FILE_NAME
+ */
+const resolveLogFilePath = (logFile) => {
+  if (!logFile) {
+    return path.join(getLogDir(), LOG_FILE_NAME);
+  }
+
+  if (path.isAbsolute(logFile)) {
+    return logFile;
+  }
+
+  return path.join(getLogDir(), logFile);
+};
+
+/**
+ * 创建日志写入流
+ */
+const createLogStream = (logFilePath) => {
+  const logDir = path.dirname(logFilePath);
+
+  // 确保日志目录存在
+  if (!fs.existsSync(logDir)) {
+    fs.mkdirSync(logDir, { recursive: true });
+  }
+
+  // 使用 'w' 标志覆盖之前的日志
+  return fs.createWriteStream(logFilePath, { flags: 'w' });
+};
+
+/**
+ * 执行命令的内部实现
+ */
+const executeRun = async (
+  commandName,
+  options = {},
+) => {
+  try {
+    logger.info(`Running ${commandName} command...`);
+
+    // 1. 加载 .coze 配置
+    const config = await loadCozeConfig();
+    const commandArgs = getCommandConfig(config, commandName);
+
+    // 2. 准备日志
+    const logFilePath = resolveLogFilePath(options.logFile);
+    const logStream = createLogStream(logFilePath);
+
+    // 3. 执行命令
+    const commandString = commandArgs.join(' ');
+
+    logger.info(`Executing: ${commandString}`);
+    logger.info(`Working directory: ${process.cwd()}`);
+    logger.info(`Log file: ${logFilePath}`);
+
+    const childProcess = shelljs.exec(commandString, {
+      async: true,
+      silent: true, // 不自动输出，我们手动处理
+    });
+
+    if (!childProcess) {
+      throw new Error('Failed to create child process');
+    }
+
+    // 将输出同时写入控制台和日志文件
+    _optionalChain([childProcess, 'access', _ => _.stdout, 'optionalAccess', _2 => _2.on, 'call', _3 => _3('data', (data) => {
+      process.stdout.write(data);
+      logStream.write(data);
+    })]);
+
+    _optionalChain([childProcess, 'access', _4 => _4.stderr, 'optionalAccess', _5 => _5.on, 'call', _6 => _6('data', (data) => {
+      process.stderr.write(data);
+      logStream.write(data);
+    })]);
+
+    childProcess.on('close', (code, signal) => {
+      logStream.end();
+
+      if (code !== 0) {
+        logger.error(
+          `Command exited with code ${_nullishCoalesce$1(code, () => ( 'unknown'))}${signal ? ` and signal ${signal}` : ''}`,
+        );
+        logger.error(`Check log file for details: ${logFilePath}`);
+        process.exit(code || 1);
+      } else {
+        logger.success('Command completed successfully');
+        logger.info(`Log file: ${logFilePath}`);
+      }
+    });
+
+    childProcess.on('error', (error) => {
+      logger.error('Failed to execute command:');
+      logger.error(`Error: ${error.message}`);
+      if (error.stack) {
+        logger.error(`Stack trace:\n${error.stack}`);
+      }
+      logStream.end();
+      process.exit(1);
+    });
+  } catch (error) {
+    logger.error(`Failed to run ${commandName} command:`);
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+};
+
+/**
+ * 注册 dev/build/start 命令到 program
+ */
+const registerCommand$1 = program => {
+  // dev 命令
+  program
+    .command('dev')
+    .description('Start development server')
+    .option('--log-file <path>', 'Log file path')
+    .action(async options => {
+      await executeRun('dev', options);
+    });
+
+  // build 命令
+  program
+    .command('build')
+    .description('Build for production')
+    .option('--log-file <path>', 'Log file path')
+    .action(async options => {
+      await executeRun('build', options);
+    });
+
+  // start 命令
+  program
+    .command('start')
+    .description('Start production server')
+    .option('--log-file <path>', 'Log file path')
+    .action(async options => {
+      await executeRun('start', options);
+    });
+};
+
+/**
+ * 在后台启动一个独立的子进程
+ * 类似于 `setsid command args >/dev/null 2>&1 &`
+ *
+ * @param command - 要执行的命令 (例如: 'npm', 'node', 'bash')
+ * @param args - 命令参数数组 (例如: ['run', 'dev'])
+ * @param options - 配置选项
+ * @returns 子进程的 PID
+ */
+function spawnDetached(
+  command,
+  args,
+  options,
+) {
+  const { cwd, verbose = true } = options;
+  const isWindows = os.platform() === 'win32';
+
+  if (verbose) {
+    console.log(`Spawning detached process: ${command} ${args.join(' ')}`);
+    console.log(`Working directory: ${cwd}`);
+  }
+
+  // 使用 spawn 创建后台子进程
+  const child = child_process.spawn(command, args, {
+    cwd,
+    detached: !isWindows, // Windows 不完全支持 detached，但仍可以使用
+    stdio: 'ignore', // 忽略所有输入输出，让进程完全独立运行
+  });
+
+  // 分离父子进程引用，允许父进程退出而不等待子进程
+  child.unref();
+
+  if (verbose && child.pid) {
+    console.log(`Process started with PID: ${child.pid}`);
+  }
+
+  return child.pid;
+}
+
+/**
+ * 创建 AJV 验证器实例
+ */
+const createAjvInstance = () => {
+  const ajv = new Ajv({
+    useDefaults: true, // 自动应用默认值
+    coerceTypes: true, // 类型强制转换
+    removeAdditional: false, // 保留额外属性以便后续报错
+    allErrors: true, // 收集所有错误
+  });
+
+  addFormats(ajv);
+  return ajv;
+};
+
+/**
+ * 验证参数
+ *
+ * @param schema - JSON Schema 定义
+ * @param params - 待验证的参数
+ * @returns 验证后的参数（应用了默认值）
+ * @throws 验证失败时抛出错误
+ */
+const validateParams = (
+  schema,
+  params,
+) => {
+  const ajv = createAjvInstance();
+  const validate = ajv.compile(schema);
+
+  const isValid = validate(params);
+
+  if (!isValid) {
+    const errors = validate.errors || [];
+    const errorMessages = errors.map(err => {
+      const path = err.instancePath || '/';
+      const message = err.message || 'validation failed';
+      return `  - ${path}: ${message}`;
+    });
+
+    throw new Error(
+      `Parameter validation failed:\n${errorMessages.join('\n')}\n\nPlease check your parameters and try again.`,
+    );
+  }
+
+  return params ;
+};
+
+/**
+ * 从 Commander 解析透传参数
+ * 将 kebab-case 的 CLI 参数转换为 camelCase
+ *
+ * 使用 minimist 解析 process.argv，自动处理类型转换
+ *
+ * @param command - Commander 命令实例
+ * @param knownOptions - 已知的选项集合（不需要透传的选项）
+ * @returns 参数对象
+ */
+const parsePassThroughParams = (
+  command,
+  knownOptions = new Set(),
+) => {
+  // 使用 minimist 解析所有参数
+  // eslint-disable-next-line @typescript-eslint/no-magic-numbers -- slice(2) to skip node and script path
+  const parsed = minimist(process.argv.slice(2));
+
+  // 过滤掉已知选项和位置参数(_)
+  const filtered = Object.entries(parsed).reduce(
+    (params, [key, value]) => {
+      // 跳过 minimist 的位置参数数组
+      if (key === '_') {
+        return params;
+      }
+
+      // 跳过已知选项（支持原始格式和 camelCase 格式）
+      if (knownOptions.has(key) || knownOptions.has(changeCase.camelCase(key))) {
+        return params;
+      }
+
+      // 将 kebab-case 转换为 camelCase
+      const camelKey = changeCase.camelCase(key);
+      // eslint-disable-next-line security/detect-object-injection -- camelKey is sanitized by camelCase
+      params[camelKey] = value;
+
+      return params;
+    },
+    {},
+  );
+
+  return filtered;
+};
+
+/**
+ * 渲染 EJS 模板文件
+ *
+ * @param filePath - 模板文件路径
+ * @param context - 模板上下文
+ * @returns 渲染后的内容
+ */
+const renderTemplate = async (
+  filePath,
+  context,
+) => {
+  const content = await fs$1.readFile(filePath, 'utf-8');
+
+  try {
+    return ejs.render(content, context, {
+      filename: filePath,
+    });
+  } catch (error) {
+    throw new Error(
+      `Failed to render template ${filePath}:\n${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+};
+
+/**
+ * 判断文件是否需要渲染（是否为文本文件）
+ *
+ * @param filePath - 文件路径
+ * @returns 是否需要渲染
+ */
+const shouldRenderFile = (filePath) => {
+  const textExtensions = new Set([
+    '.js',
+    '.ts',
+    '.jsx',
+    '.tsx',
+    '.json',
+    '.css',
+    '.scss',
+    '.sass',
+    '.less',
+    '.html',
+    '.md',
+    '.txt',
+    '.yaml',
+    '.yml',
+    '.xml',
+    '.svg',
+    '.env',
+    '.gitignore',
+    '.npmrc',
+    '.eslintrc',
+    '.prettierrc',
+    '.babelrc',
+    '.sh',
+  ]);
+
+  const ext = path.extname(filePath).toLowerCase();
+
+  // 没有扩展名的文件（如 .coze）也尝试渲染
+  if (ext === '') {
+    return true;
+  }
+
+  return textExtensions.has(ext);
+};
+
+/**
+ * 判断文件是否应该被忽略（不复制到目标目录）
+ *
+ * @param filePath - 文件路径
+ * @returns 是否应该忽略
+ */
+const shouldIgnoreFile = (filePath) => {
+  const fileName = path.basename(filePath);
+  const pathParts = filePath.split(path.sep);
+
+  // 精确匹配的文件名
+  const exactMatch = ['template.config.ts', 'template.config.js', '.DS_Store'];
+
+  // 目录名（需要检查路径中是否包含）
+  const directoryPatterns = ['node_modules'];
+
+  // 检查精确匹配
+  if (exactMatch.includes(fileName)) {
+    return true;
+  }
+
+  // 检查路径中是否包含需要忽略的目录
+  return directoryPatterns.some(dir => pathParts.includes(dir));
+};
+
+/**
+ * 递归获取目录中的所有文件
+ *
+ * @param dir - 目录路径
+ * @param baseDir - 基础目录（用于计算相对路径）
+ * @returns 文件相对路径数组
+ */
+const getAllFiles = async (
+  dir,
+  baseDir = dir,
+) => {
+  logger.verbose(`Scanning directory: ${dir}`);
+
+  const entries = await fs$1.readdir(dir, { withFileTypes: true });
+
+  logger.verbose(`Found ${entries.length} entries in ${path.basename(dir)}`);
+
+  const results = await Promise.all(
+    entries.map(entry => {
+      const fullPath = path.join(dir, entry.name);
+      const relativePath = path.relative(baseDir, fullPath);
+
+      if (shouldIgnoreFile(relativePath)) {
+        logger.verbose(`  - Ignoring: ${entry.name}`);
+        return [];
+      }
+
+      if (entry.isDirectory()) {
+        logger.verbose(`  - Entering directory: ${entry.name}`);
+        return getAllFiles(fullPath, baseDir);
+      }
+
+      logger.verbose(`  - Found file: ${entry.name}`);
+      return [relativePath];
+    }),
+  );
+
+  return results.flat();
+};
+
+/**
+ * 确保目录存在
+ *
+ * @param dir - 目录路径
+ */
+const ensureDir = async (dir) => {
+  await fs$1.mkdir(dir, { recursive: true });
+};
+
+/**
+ * 转换模板文件名（白名单机制）
+ * 只对特定文件将 _ 开头转换为 . 开头
+ *
+ * @param filePath - 文件相对路径
+ * @returns 转换后的文件路径
+ */
+const convertDotfileName = (filePath) => {
+  // 白名单：需要从 _ 开头转换为 . 开头的文件
+  const dotfileWhitelist = ['_gitignore', '_npmrc'];
+
+  const fileName = path.basename(filePath);
+
+  // 只对白名单中的文件进行转换（如 _gitignore -> .gitignore）
+  if (dotfileWhitelist.includes(fileName)) {
+    return filePath.replace(/(^|\/|\\)_([^/\\]+)$/g, '$1.$2');
+  }
+
+  return filePath;
+};
+
+/**
+ * 执行文件渲染钩子
+ *
+ * @param templateConfig - 模板配置
+ * @param fileInfo - 文件渲染信息
+ * @param context - 模板上下文
+ * @returns 处理后的文件信息，或 null 表示跳过该文件
+ */
+const executeFileRenderHook = async (
+  templateConfig,
+  fileInfo,
+  context,
+) => {
+  if (!templateConfig.onFileRender) {
+    return fileInfo;
+  }
+
+  const result = await templateConfig.onFileRender(
+    fileInfo,
+    context,
+  );
+
+  // false: 跳过文件
+  if (result === false) {
+    return null;
+  }
+
+  // undefined/void: 使用默认内容
+  if (result === undefined || result === null) {
+    return fileInfo;
+  }
+
+  // string: 作为 content，其他不变
+  if (typeof result === 'string') {
+    return {
+      ...fileInfo,
+      content: result,
+    };
+  }
+
+  // FileRenderInfo: 使用新对象的信息
+  return result;
+};
+
+/**
+ * 处理单个文件
+ */
+const processSingleFile = async (options
+
+
+
+
+
+) => {
+  const { file, templatePath, outputPath, context, templateConfig } = options;
+
+  const srcPath = path.join(templatePath, file);
+  const destFile = convertDotfileName(file);
+
+  logger.verbose(
+    `  - Processing: ${file}${destFile !== file ? ` -> ${destFile}` : ''}`,
+  );
+
+  // 判断是否为二进制文件
+  const isBinary = !shouldRenderFile(srcPath);
+  let content;
+  let wasRendered = false;
+
+  if (isBinary) {
+    // 二进制文件，读取为 buffer 然后转为 base64
+    const buffer = await fs$1.readFile(srcPath);
+    content = buffer.toString('base64');
+  } else {
+    // 文本文件，渲染后的内容
+    content = await renderTemplate(srcPath, context);
+    wasRendered = true;
+  }
+
+  // 构造文件信息对象
+  const fileInfo = {
+    path: file,
+    destPath: destFile,
+    content,
+    isBinary,
+    wasRendered,
+  };
+
+  // 执行文件渲染钩子
+  const processedFileInfo = await executeFileRenderHook(
+    templateConfig,
+    fileInfo,
+    context,
+  );
+
+  // 如果返回 null，跳过该文件
+  if (processedFileInfo === null) {
+    logger.verbose('    ⊘ Skipped by onFileRender hook');
+    return;
+  }
+
+  // 使用处理后的目标路径
+  const finalDestPath = path.join(outputPath, processedFileInfo.destPath);
+
+  // 确保目标目录存在
+  await ensureDir(path.dirname(finalDestPath));
+
+  // 写入文件
+  if (processedFileInfo.isBinary) {
+    // 二进制文件：如果内容没变，直接复制；否则从 base64 解码写入
+    if (processedFileInfo.content === content) {
+      await fs$1.copyFile(srcPath, finalDestPath);
+      logger.verbose('    ✓ Copied (binary)');
+    } else {
+      const buffer = Buffer.from(processedFileInfo.content, 'base64');
+      await fs$1.writeFile(finalDestPath, buffer);
+      logger.verbose('    ✓ Written (binary, modified by hook)');
+    }
+  } else {
+    // 文本文件
+    await fs$1.writeFile(finalDestPath, processedFileInfo.content, 'utf-8');
+    logger.verbose('    ✓ Rendered and written');
+  }
+};
+
+/**
+ * 复制并处理模板文件到目标目录
+ */
+const processTemplateFiles = async (options
+
+
+
+
+) => {
+  const { templatePath, outputPath, context, templateConfig } = options;
+  logger.verbose('Processing template files:');
+  logger.verbose(`  - Template path: ${templatePath}`);
+  logger.verbose(`  - Output path: ${outputPath}`);
+
+  // 验证模板目录是否存在
+  try {
+    const stat = await fs$1.stat(templatePath);
+    logger.verbose(
+      `  - Template path exists: ${stat.isDirectory() ? 'directory' : 'file'}`,
+    );
+    if (!stat.isDirectory()) {
+      throw new Error(`Template path is not a directory: ${templatePath}`);
+    }
+  } catch (error) {
+    logger.error(
+      `  - Failed to access template path: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    throw error;
+  }
+
+  const files = await getAllFiles(templatePath);
+
+  logger.verbose(`  - Found ${files.length} files to process`);
+
+  if (files.length === 0) {
+    logger.warn('  - No files found in template directory!');
+    return;
+  }
+
+  await Promise.all(
+    files.map(file =>
+      processSingleFile({
+        file,
+        templatePath,
+        outputPath,
+        context,
+        templateConfig,
+      }),
+    ),
+  );
+
+  logger.verbose('✓ All files processed successfully');
+
+  // 单独处理 node_modules 目录（如果存在）
+  const sourceNodeModules = path.join(templatePath, 'node_modules');
+  const targetNodeModules = path.join(outputPath, 'node_modules');
+
+  if (fs.existsSync(sourceNodeModules)) {
+    logger.info('\nCopying node_modules from pre-warmed template...');
+    logger.verbose(`  From: ${sourceNodeModules}`);
+    logger.verbose(`  To: ${targetNodeModules}`);
+
+    const result = shelljs.exec(`cp -R "${sourceNodeModules}" "${targetNodeModules}"`, {
+      silent: true,
+    });
+
+    if (result.stdout) {
+      process.stdout.write(result.stdout);
+    }
+
+    if (result.stderr) {
+      process.stderr.write(result.stderr);
+    }
+
+    if (result.code === 0) {
+      logger.success('✓ node_modules copied successfully');
+    } else {
+      logger.warn(
+        `Failed to copy node_modules: ${result.stderr || 'unknown error'}`,
+      );
+      logger.info('Will need to run pnpm install manually');
+    }
+  }
+};
+
+/**
+ * 检查输出目录是否为空
+ * 注意:.git 目录会被忽略,允许在已初始化 git 的目录中创建项目
+ *
+ * @param outputPath - 输出目录路径
+ * @returns 是否为空
+ */
+const isOutputDirEmpty = async (
+  outputPath,
+) => {
+  try {
+    const entries = await fs$1.readdir(outputPath);
+    // 过滤掉 .git 目录,允许在已初始化 git 的目录中创建项目
+    const filteredEntries = entries.filter(entry => entry !== '.git');
+    return filteredEntries.length === 0;
+  } catch (e) {
+    // 目录不存在，视为空
+    return true;
+  }
+};
+
+/**
+ * 验证输出目录
+ *
+ * @param outputPath - 输出目录路径
+ * @throws 如果目录不为空则抛出错误
+ */
+const validateOutputDir = async (outputPath) => {
+  const isEmpty = await isOutputDirEmpty(outputPath);
+  if (!isEmpty) {
+    throw new Error(
+      `Output directory is not empty: ${outputPath}\n` +
+        'Please use an empty directory or remove existing files.',
+    );
+  }
+};
+
+/**
+ * 模板引擎执行选项
+ */
+
+
+
+
+
+
+/**
+ * 加载模板元数据和路径
+ */
+const loadTemplateMetadata = async (templateName) => {
+  const templatesConfigPath = getTemplatesConfigPath();
+  const templatesConfig = await loadTemplatesConfig(templatesConfigPath);
+  const templateMetadata = findTemplate(templatesConfig, templateName);
+  const templatesDir = getTemplatesDir();
+  const templatePath = await getTemplatePath(templatesDir, templateMetadata);
+
+  return { templatePath, templateMetadata };
+};
+
+/**
+ * 解析并验证模板参数
+ */
+const parseAndValidateParams = (
+  command,
+  templateConfig,
+) => {
+  const knownOptions = new Set([
+    'template',
+    't',
+    'output',
+    'o',
+    'skipInstall',
+    'skip-install',
+    'skipGit',
+    'skip-git',
+    'skipDev',
+    'skip-dev',
+  ]);
+  const userParams = parsePassThroughParams(command, knownOptions);
+
+  // 合并默认参数：defaultParams < schema defaults < userParams
+  const paramsWithDefaults = {
+    ...(templateConfig.defaultParams || {}),
+    ...userParams,
+  };
+
+  return validateParams(templateConfig.paramsSchema, paramsWithDefaults);
+};
+
+/**
+ * 执行生命周期钩子
+ */
+const executeBeforeRenderHook = async ( 
+  templateConfig,
+  context,
+) => {
+  if (!templateConfig.onBeforeRender) {
+    return context;
+  }
+  return (await templateConfig.onBeforeRender(context)) ;
+};
+
+/**
+ * 执行渲染后钩子
+ */
+const executeAfterRenderHook = async (
+  templateConfig,
+  context,
+  outputPath,
+) => {
+  if (templateConfig.onAfterRender) {
+    await templateConfig.onAfterRender(context, outputPath);
+  }
+};
+
+/**
+ * 准备输出目录
+ */
+const prepareOutputDirectory = async (outputPath) => {
+  const absolutePath = path.resolve(process.cwd(), outputPath);
+  await validateOutputDir(absolutePath);
+  return absolutePath;
+};
+
+/**
+ * 执行完整的模板渲染流程
+ */
+const execute = async (
+  options,
+) => {
+  const { templateName, outputPath, command } = options;
+
+  // 1. 加载模板
+  const { templatePath } = await loadTemplateMetadata(templateName);
+
+  // 2. 加载模板配置
+  const templateConfig = await loadTemplateConfig(templatePath);
+
+  // 3. 解析并验证参数
+  const validatedParams = parseAndValidateParams(command, templateConfig);
+
+  // 4. 执行 onBeforeRender 钩子
+  const context = await executeBeforeRenderHook(templateConfig, {
+    ...validatedParams,
+  });
+
+  // 5. 准备输出目录
+  const absoluteOutputPath = await prepareOutputDirectory(outputPath);
+
+  // 6. 处理模板文件
+  await processTemplateFiles({
+    templatePath,
+    outputPath: absoluteOutputPath,
+    context,
+    templateConfig,
+  });
+
+  // 7. 执行 onAfterRender 钩子
+  await executeAfterRenderHook(templateConfig, context, absoluteOutputPath);
+
+  return absoluteOutputPath;
+};
+
+function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
+/**
+ * 运行 pnpm install
+ */
+const runPnpmInstall = (projectPath) => {
+  logger.info('\nInstalling dependencies with pnpm...');
+  logger.info(`Executing: pnpm install in ${projectPath}`);
+
+  const result = shelljs.exec('pnpm install', {
+    cwd: projectPath,
+    silent: true, // 使用 silent 来捕获输出
+  });
+
+  // 输出 stdout
+  if (result.stdout) {
+    process.stdout.write(result.stdout);
+  }
+
+  // 输出 stderr
+  if (result.stderr) {
+    process.stderr.write(result.stderr);
+  }
+
+  if (result.code === 0) {
+    logger.success('Dependencies installed successfully!');
+  } else {
+    const errorMessage = [
+      `pnpm install failed with exit code ${result.code}`,
+      result.stderr ? `\nStderr:\n${result.stderr}` : '',
+      result.stdout ? `\nStdout:\n${result.stdout}` : '',
+    ]
+      .filter(Boolean)
+      .join('');
+
+    throw new Error(errorMessage);
+  }
+};
+
+/**
+ * 初始化 git 仓库并创建初始提交
+ * 如果目录中已存在 .git,则跳过初始化
+ */
+const runGitInit = (projectPath) => {
+  // 检查是否已存在 .git 目录
+  const gitDir = path.join(projectPath, '.git');
+  if (fs.existsSync(gitDir)) {
+    logger.info(
+      '\n💡 Git repository already exists, skipping git initialization',
+    );
+    return;
+  }
+
+  const runGitCommand = (command) => {
+    logger.info(`Executing: ${command}`);
+
+    const result = shelljs.exec(command, {
+      cwd: projectPath,
+      silent: true,
+    });
+
+    // 输出命令的结果
+    if (result.stdout) {
+      process.stdout.write(result.stdout);
+    }
+
+    if (result.stderr) {
+      process.stderr.write(result.stderr);
+    }
+
+    if (result.code !== 0) {
+      const errorMessage = [
+        `${command} failed with exit code ${result.code}`,
+        result.stderr ? `\nStderr:\n${result.stderr}` : '',
+        result.stdout ? `\nStdout:\n${result.stdout}` : '',
+      ]
+        .filter(Boolean)
+        .join('');
+
+      throw new Error(errorMessage);
+    }
+  };
+
+  try {
+    logger.info('\nInitializing git repository...');
+    runGitCommand('git init');
+
+    logger.info('Adding files to git...');
+    runGitCommand('git add .');
+
+    logger.info('Creating initial commit...');
+    runGitCommand('git commit -m "chore: initial commit"');
+
+    logger.success('Git repository initialized successfully!');
+  } catch (error) {
+    // Git 初始化失败不应该导致整个流程失败
+    logger.warn(
+      `Git initialization failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+    logger.info('You can manually initialize git later with: git init');
+  }
+};
+
+/**
+ * 运行开发服务器(后台模式)
+ * 启动后台子进程运行开发服务器，父进程可以直接退出
+ * 使用 CLI 自己的 dev 命令(定义在 run.ts)而不是直接运行 npm run dev
+ */
+const runDev = (projectPath) => {
+  logger.info('\nStarting development server in background...');
+
+  // 获取当前 CLI 的可执行文件路径
+  // process.argv[0] 是 node，process.argv[1] 是 CLI 入口文件
+  const cliPath = process.argv[1];
+
+  logger.info(`Executing: ${cliPath} dev in ${projectPath}`);
+
+  // 使用通用的后台执行函数启动开发服务器
+  // 调用 CLI 自己的 dev 命令
+  const pid = spawnDetached(process.argv[0], [cliPath, 'dev'], {
+    cwd: projectPath,
+    verbose: false, // 不输出额外的进程信息，由 logger 统一处理
+  });
+
+  logger.success('Development server started in background!');
+  if (pid) {
+    logger.info(`Process ID: ${pid}`);
+    logger.info(
+      '\nThe dev server is running independently. You can close this terminal.',
+    );
+    logger.info(`To stop the server later, use: kill ${pid}`);
+  }
+};
+
+/**
+ * 执行 init 命令的内部实现
+ */
+const executeInit = async (
+  options
+
+
+
+
+
+,
+  command,
+) => {
+  const timer = new TimeTracker();
+
+  try {
+    const {
+      template: templateName,
+      output: outputPath,
+      skipInstall,
+      skipGit,
+      skipDev,
+    } = options;
+
+    logger.info(`Initializing project with template: ${templateName}`);
+    timer.logPhase('Initialization');
+
+    // 执行模板引擎，返回绝对路径
+    const absoluteOutputPath = await execute({
+      templateName,
+      outputPath,
+      command,
+    });
+
+    timer.logPhase('Template engine execution');
+    logger.success('Project created successfully!');
+
+    // 如果没有跳过安装，检查是否需要运行 pnpm install
+    if (!skipInstall) {
+      const nodeModulesPath = path.join(absoluteOutputPath, 'node_modules');
+      const hasNodeModules = fs.existsSync(nodeModulesPath);
+
+      if (hasNodeModules) {
+        logger.info(
+          '\n💡 Using pre-warmed node_modules, skipping pnpm install',
+        );
+        timer.logPhase('Node modules (pre-warmed)');
+      } else {
+        runPnpmInstall(absoluteOutputPath);
+        timer.logPhase('Dependencies installation');
+      }
+    }
+
+    // 如果没有跳过 git，则初始化 git 仓库
+    if (!skipGit) {
+      runGitInit(absoluteOutputPath);
+      timer.logPhase('Git initialization');
+    }
+
+    // 如果没有跳过 dev，则启动开发服务器
+    if (!skipDev) {
+      runDev(absoluteOutputPath);
+      timer.logPhase('Dev server startup');
+    } else {
+      // 只有跳过 dev 时才显示 Next steps
+      logger.info('\nNext steps:');
+      logger.info(`  cd ${outputPath}`);
+      if (skipInstall) {
+        logger.info('  pnpm install');
+      }
+      if (skipGit) {
+        logger.info(
+          '  git init && git add . && git commit -m "initial commit"',
+        );
+      }
+      logger.info('  coze dev');
+    }
+
+    // 输出总耗时
+    timer.logTotal();
+  } catch (error) {
+    timer.logTotal();
+    logger.error('Failed to initialize project:');
+    logger.error(error instanceof Error ? error.message : String(error));
+    process.exit(1);
+  }
+};
+
+/**
+ * 注册 init 命令到 program
+ */
+const registerCommand = program => {
+  program
+    .command('init')
+    .description('Initialize a new project from a template')
+    .argument('[directory]', 'Output directory for the project')
+    .requiredOption('-t, --template <name>', 'Template name')
+    .option('-o, --output <path>', 'Output directory', process.cwd())
+    .option('--skip-install', 'Skip automatic pnpm install', false)
+    .option('--skip-git', 'Skip automatic git initialization', false)
+    .option('--skip-dev', 'Skip automatic dev server start', false)
+    .allowUnknownOption() // 允许透传参数
+    .action(async (directory, options, command) => {
+      // 位置参数优先级高于 --output 选项
+      const outputPath = _nullishCoalesce(directory, () => ( options.output));
+      await executeInit({ ...options, output: outputPath }, command);
+    });
+};
+
+var version = "0.0.1-alpha.035e0e";
+var packageJson = {
+	version: version};
+
+const commands = [
+  registerCommand,
+  registerCommand$1,
+  registerCommand$2,
+];
+
+const main = () => {
+  const program = new commander.Command();
+
+  program
+    .name('coze')
+    .description(
+      'Coze Coding CLI - Project template engine for frontend stacks',
+    )
+    .version(packageJson.version);
+
+  commands.forEach(initCmd => initCmd(program));
+
+  // 在 help 输出中添加模板信息
+  program.addHelpText('after', generateTemplatesHelpText());
+
+  program.parse(process.argv);
+};
+
+main();