@coze-arch/cli 0.0.1-alpha.912cd5 → 0.0.1-alpha.9c5406

package/lib/cli.js

@@ -5,12 +5,15 @@ 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 perf_hooks = require('perf_hooks');
+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');
 
@@ -124,7 +127,7 @@ const generateTemplatesHelpText = () => {
   return lines.join('\n');
 };
 
-function _nullishCoalesce$2(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } function _optionalChain$4(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) {
+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";
@@ -171,7 +174,7 @@ class Logger {
       return level;
     }
 
-    const envLevel = _optionalChain$4([process, 'access', _ => _.env, 'access', _2 => _2.LOG_LEVEL, 'optionalAccess', _3 => _3.toLowerCase, 'call', _4 => _4()]);
+    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];
     }
@@ -183,7 +186,7 @@ class Logger {
     // 简单检测：Node.js 环境且支持 TTY
     return (
       typeof process !== 'undefined' &&
-      _optionalChain$4([process, 'access', _5 => _5.stdout, 'optionalAccess', _6 => _6.isTTY]) === true &&
+      _optionalChain$3([process, 'access', _5 => _5.stdout, 'optionalAccess', _6 => _6.isTTY]) === true &&
       process.env.NO_COLOR === undefined
     );
   }
@@ -269,7 +272,330 @@ const createLogger = (options = {}) =>
 // 导出默认实例
 const logger = createLogger();
 
-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; }/* eslint-disable @typescript-eslint/no-explicit-any */
+/**
+ * 时间统计工具
+ */
+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
 
@@ -360,12 +686,12 @@ function safeJsonParse(
     const parsed = JSON.parse(String(input));
 
     // Optional validation
-    if (_optionalChain$3([options, 'optionalAccess', _ => _.validate])) {
+    if (_optionalChain$2([options, 'optionalAccess', _ => _.validate])) {
       if (options.validate(parsed)) {
         return parsed;
       } else {
         const validationError = new Error('JSON validation failed');
-        _optionalChain$3([options, 'access', _2 => _2.onError, 'optionalCall', _3 => _3(validationError, input)]);
+        _optionalChain$2([options, 'access', _2 => _2.onError, 'optionalCall', _3 => _3(validationError, input)]);
 
         if (options.throwOnValidationError) {
           throw validationError;
@@ -377,15 +703,15 @@ function safeJsonParse(
     return parsed;
   } catch (error) {
     // Re-throw validation errors when throwOnValidationError is true
-    if (error instanceof Error && error.message === 'JSON validation failed' && _optionalChain$3([options, 'optionalAccess', _4 => _4.throwOnValidationError])) {
+    if (error instanceof Error && error.message === 'JSON validation failed' && _optionalChain$2([options, 'optionalAccess', _4 => _4.throwOnValidationError])) {
       throw error;
     }
-    _optionalChain$3([options, 'optionalAccess', _5 => _5.onError, 'optionalCall', _6 => _6(error , input)]);
+    _optionalChain$2([options, 'optionalAccess', _5 => _5.onError, 'optionalCall', _6 => _6(error , input)]);
     return defaultValue;
   }
 }
 
-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; }
+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; }
 
 
 /**
@@ -475,13 +801,13 @@ const getCommandConfig = (
   // 根据命令名称映射到配置路径
   switch (commandName) {
     case 'dev':
-      commandConfig = _optionalChain$2([config, 'access', _ => _.dev, 'optionalAccess', _2 => _2.run]);
+      commandConfig = _optionalChain$1([config, 'access', _ => _.dev, 'optionalAccess', _2 => _2.run]);
       break;
     case 'build':
-      commandConfig = _optionalChain$2([config, 'access', _3 => _3.deploy, 'optionalAccess', _4 => _4.build]);
+      commandConfig = _optionalChain$1([config, 'access', _3 => _3.deploy, 'optionalAccess', _4 => _4.build]);
       break;
     case 'start':
-      commandConfig = _optionalChain$2([config, 'access', _5 => _5.deploy, 'optionalAccess', _6 => _6.run]);
+      commandConfig = _optionalChain$1([config, 'access', _5 => _5.deploy, 'optionalAccess', _6 => _6.run]);
       break;
     default:
       throw new Error(`Unknown command: ${commandName}`);
@@ -497,26 +823,51 @@ const getCommandConfig = (
   return commandConfig;
 };
 
-function _nullishCoalesce$1(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } } 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; }
+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 createLogManager = (logDir = '.coze-logs') => {
-  const ensureLogDir = () => {
-    if (!fs.existsSync(logDir)) {
-      fs.mkdirSync(logDir, { recursive: true });
-    }
-  };
+const LOG_FILE_NAME = 'dev.log';
 
-  const getLogPath = (logFile) => path.join(logDir, logFile);
+/**
+ * 获取日志目录
+ * 优先使用环境变量 COZE_LOG_DIR，否则使用 ~/.coze-logs
+ */
+const getLogDir = () =>
+  process.env.COZE_LOG_DIR || path.join(os.homedir(), '.coze-logs');
 
-  return {
-    createWriteStream: (logFile) => {
-      ensureLogDir();
-      return fs.createWriteStream(getLogPath(logFile), { flags: 'a' });
-    },
-  };
+/**
+ * 解析日志文件路径
+ * - 如果是绝对路径，直接使用
+ * - 如果是相对路径，基于 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' });
 };
 
 /**
@@ -534,16 +885,15 @@ const executeRun = async (
     const commandArgs = getCommandConfig(config, commandName);
 
     // 2. 准备日志
-    const logManager = createLogManager();
-    const logFile = options.logFile || `${commandName}.log`;
-    const logStream = logManager.createWriteStream(logFile);
+    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: ${logFile}`);
+    logger.info(`Log file: ${logFilePath}`);
 
     const childProcess = shelljs.exec(commandString, {
       async: true,
@@ -555,12 +905,12 @@ const executeRun = async (
     }
 
     // 将输出同时写入控制台和日志文件
-    _optionalChain$1([childProcess, 'access', _ => _.stdout, 'optionalAccess', _2 => _2.on, 'call', _3 => _3('data', (data) => {
+    _optionalChain([childProcess, 'access', _ => _.stdout, 'optionalAccess', _2 => _2.on, 'call', _3 => _3('data', (data) => {
       process.stdout.write(data);
       logStream.write(data);
     })]);
 
-    _optionalChain$1([childProcess, 'access', _4 => _4.stderr, 'optionalAccess', _5 => _5.on, 'call', _6 => _6('data', (data) => {
+    _optionalChain([childProcess, 'access', _4 => _4.stderr, 'optionalAccess', _5 => _5.on, 'call', _6 => _6('data', (data) => {
       process.stderr.write(data);
       logStream.write(data);
     })]);
@@ -572,11 +922,11 @@ const executeRun = async (
         logger.error(
           `Command exited with code ${_nullishCoalesce$1(code, () => ( 'unknown'))}${signal ? ` and signal ${signal}` : ''}`,
         );
-        logger.error(`Check log file for details: ${logFile}`);
+        logger.error(`Check log file for details: ${logFilePath}`);
         process.exit(code || 1);
       } else {
         logger.success('Command completed successfully');
-        logger.info(`Log file: ${logFile}`);
+        logger.info(`Log file: ${logFilePath}`);
       }
     });
 
@@ -618,78 +968,54 @@ const registerCommand$1 = program => {
       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);
-    });
-};
-
-/**
- * 时间统计工具
- */
-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;
+  // start 命令
+  program
+    .command('start')
+    .description('Start production server')
+    .option('--log-file <path>', 'Log file path')
+    .action(async options => {
+      await executeRun('start', options);
+    });
 };
 
 /**
- * 获取模板目录路径
- * @returns __templates__ 目录的绝对路径
+ * 在后台启动一个独立的子进程
+ * 类似于 `setsid command args >/dev/null 2>&1 &`
+ *
+ * @param command - 要执行的命令 (例如: 'npm', 'node', 'bash')
+ * @param args - 命令参数数组 (例如: ['run', 'dev'])
+ * @param options - 配置选项
+ * @returns 子进程的 PID
  */
-const getTemplatesDir = () => {
-  const templatesDir = path.resolve(__dirname, './__templates__');
-  logger.verbose(`Templates directory: ${templatesDir}`);
-  logger.verbose(`Templates directory exists: ${fs.existsSync(templatesDir)}`);
-  return templatesDir;
-};
+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 验证器实例
@@ -739,149 +1065,12 @@ const validateParams = (
   return params ;
 };
 
-/**
- * 加载模板配置文件
- * 支持 .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;
-};
-
 /**
  * 从 Commander 解析透传参数
  * 将 kebab-case 的 CLI 参数转换为 camelCase
  *
+ * 使用 minimist 解析 process.argv，自动处理类型转换
+ *
  * @param command - Commander 命令实例
  * @param knownOptions - 已知的选项集合（不需要透传的选项）
  * @returns 参数对象
@@ -890,20 +1079,34 @@ const parsePassThroughParams = (
   command,
   knownOptions = new Set(),
 ) => {
-  const rawOptions = command.opts();
+  // 使用 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 initial = {};
-  return Object.entries(rawOptions).reduce(
+  // 过滤掉已知选项和位置参数(_)
+  const filtered = Object.entries(parsed).reduce(
     (params, [key, value]) => {
-      if (knownOptions.has(key)) {
+      // 跳过 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);
-      return { ...params, [camelKey]: value };
+      // eslint-disable-next-line security/detect-object-injection -- camelKey is sanitized by camelCase
+      params[camelKey] = value;
+
+      return params;
     },
-    initial,
+    {},
   );
+
+  return filtered;
 };
 
 /**
@@ -1069,17 +1272,139 @@ const convertDotfileName = (filePath) => {
 };
 
 /**
- * 复制并处理模板文件到目标目录
+ * 执行文件渲染钩子
  *
- * @param templatePath - 模板目录路径
- * @param outputPath - 输出目录路径
+ * @param templateConfig - 模板配置
+ * @param fileInfo - 文件渲染信息
  * @param context - 模板上下文
+ * @returns 处理后的文件信息，或 null 表示跳过该文件
  */
-const processTemplateFiles = async (
-  templatePath,
-  outputPath,
+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}`);
@@ -1110,29 +1435,15 @@ const processTemplateFiles = async (
   }
 
   await Promise.all(
-    files.map(async file => {
-      const srcPath = path.join(templatePath, file);
-      const destFile = convertDotfileName(file);
-      const destPath = path.join(outputPath, destFile);
-
-      logger.verbose(
-        `  - Processing: ${file}${destFile !== file ? ` -> ${destFile}` : ''}`,
-      );
-
-      // 确保目标目录存在
-      await ensureDir(path.dirname(destPath));
-
-      if (shouldRenderFile(srcPath)) {
-        // 渲染文本文件
-        const rendered = await renderTemplate(srcPath, context);
-        await fs$1.writeFile(destPath, rendered, 'utf-8');
-        logger.verbose('    ✓ Rendered and written');
-      } else {
-        // 直接复制二进制文件
-        await fs$1.copyFile(srcPath, destPath);
-        logger.verbose('    ✓ Copied');
-      }
-    }),
+    files.map(file =>
+      processSingleFile({
+        file,
+        templatePath,
+        outputPath,
+        context,
+        templateConfig,
+      }),
+    ),
   );
 
   logger.verbose('✓ All files processed successfully');
@@ -1319,7 +1630,12 @@ const execute = async (
   const absoluteOutputPath = await prepareOutputDirectory(outputPath);
 
   // 6. 处理模板文件
-  await processTemplateFiles(templatePath, absoluteOutputPath, context);
+  await processTemplateFiles({
+    templatePath,
+    outputPath: absoluteOutputPath,
+    context,
+    templateConfig,
+  });
 
   // 7. 执行 onAfterRender 钩子
   await executeAfterRenderHook(templateConfig, context, absoluteOutputPath);
@@ -1327,7 +1643,7 @@ const execute = async (
   return absoluteOutputPath;
 };
 
-function _nullishCoalesce(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; }
+function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }
 /**
  * 运行 pnpm install
  */
@@ -1430,45 +1746,26 @@ const runGitInit = (projectPath) => {
 };
 
 /**
- * 运行开发服务器
+ * 运行开发服务器(后台模式)
+ * 启动后台子进程运行开发服务器，父进程可以直接退出
  */
 const runNpmDev = (projectPath) => {
-  logger.info('\nStarting development server...');
+  logger.info('\nStarting development server in background...');
   logger.info(`Executing: npm run dev in ${projectPath}`);
-  logger.info('Press Ctrl+C to stop the server\n');
 
-  // 使用 async: true 异步执行，不阻塞进程
-  const child = shelljs.exec('npm run dev', {
+  // 使用通用的后台执行函数启动开发服务器
+  const pid = spawnDetached('npm', ['run', 'dev'], {
     cwd: projectPath,
-    async: true,
-    silent: true, // 手动处理输出以便显示详细信息
+    verbose: false, // 不输出额外的进程信息，由 logger 统一处理
   });
 
-  if (child) {
-    // 输出 stdout
-    _optionalChain([child, 'access', _ => _.stdout, 'optionalAccess', _2 => _2.on, 'call', _3 => _3('data', (data) => {
-      process.stdout.write(data);
-    })]);
-
-    // 输出 stderr
-    _optionalChain([child, 'access', _4 => _4.stderr, 'optionalAccess', _5 => _5.on, 'call', _6 => _6('data', (data) => {
-      process.stderr.write(data);
-    })]);
-
-    // 监听错误
-    child.on('error', (error) => {
-      logger.error(`Failed to start dev server: ${error.message}`);
-      logger.error(`Error stack: ${error.stack}`);
-    });
-
-    // 监听退出
-    child.on('exit', (code, signal) => {
-      if (code !== 0 && code !== null) {
-        logger.error(
-          `Dev server exited with code ${code}${signal ? ` and signal ${signal}` : ''}`,
-        );
-      }
-    });
+  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}`);
   }
 };
 
@@ -1581,14 +1878,14 @@ const registerCommand = program => {
     });
 };
 
-var version = "0.0.1-alpha.912cd5";
+var version = "0.0.1-alpha.9c5406";
 var packageJson = {
 	version: version};
 
 const commands = [
   registerCommand,
   registerCommand$1,
-  // registerWarmupCommand,
+  registerCommand$2,
 ];
 
 const main = () => {