@weotro/dx 0.1.21 → 0.2.0

package/lib/cli/dx-cli.js

@@ -1,1098 +0,0 @@
-import { readFileSync, existsSync } from 'node:fs'
-import { join } from 'node:path'
-import { execSync } from 'node:child_process'
-import { logger } from '../logger.js'
-import { envManager } from '../env.js'
-import { execManager } from '../exec.js'
-import { validateEnvironment } from '../validate-env.js'
-import {
-  loadEnvPolicy,
-  resolvePolicyTargetId,
-  resolveTargetRequiredVars,
-} from '../env-policy.js'
-import { FLAG_DEFINITIONS, parseFlags } from './flags.js'
-import { getCleanArgs, getCleanArgsWithConsumedValues, getPassthroughArgs } from './args.js'
-import { showHelp, showCommandHelp } from './help.js'
-import { buildStrictHelpValidationContext, validateHelpConfig } from './help-schema.js'
-import { appendNxVerboseFlag } from './nx-command.js'
-import { getPackageVersion } from '../version.js'
-import { confirmManager } from '../confirm.js'
-import {
-  handleHelp,
-  handleBuild,
-  handleTest,
-  handleLint,
-  handleClean,
-  handleCache,
-  handleInstall,
-  handleStatus,
-} from './commands/core.js'
-import { handleStart } from './commands/start.js'
-import { handleDeploy } from './commands/deploy.js'
-import { handleDatabase } from './commands/db.js'
-import { handleWorktree } from './commands/worktree.js'
-import { handlePackage } from './commands/package.js'
-import { handleExport } from './commands/export.js'
-import { handleContracts } from './commands/contracts.js'
-import { handleRelease } from './commands/release.js'
-import { handleEnv } from './commands/env.js'
-import { COMMAND_NOT_HANDLED } from './command-result.js'
-
-class DxCli {
-  constructor(options = {}) {
-    this.projectRoot = options.projectRoot || process.env.DX_PROJECT_ROOT || process.cwd()
-    this.configDir = options.configDir || process.env.DX_CONFIG_DIR || join(this.projectRoot, 'dx', 'config')
-    this.invocation = options.invocation || 'dx'
-
-    this.commands = this.loadCommands()
-
-    this.args = process.argv.slice(2)
-    this.flags = parseFlags(this.args)
-    this.command = this.args[0]
-    this.subcommand = this.args[1]
-    this.environment = this.args[2]
-    this.worktreeManager = null
-    this.envCache = null
-    this.commandHandlers = {
-      help: args => handleHelp(this, args),
-      start: args => handleStart(this, args),
-      build: args => handleBuild(this, args),
-      test: args => handleTest(this, args),
-      lint: args => handleLint(this, args),
-      clean: args => handleClean(this, args),
-      cache: args => handleCache(this, args),
-      install: args => handleInstall(this, args),
-      status: args => handleStatus(this, args),
-      deploy: args => handleDeploy(this, args),
-      db: args => handleDatabase(this, args),
-      worktree: args => handleWorktree(this, args),
-      package: args => handlePackage(this, args),
-      export: args => handleExport(this, args),
-      contracts: args => handleContracts(this, args),
-      release: args => handleRelease(this, args),
-    }
-    if (this.hasEnvProfileConfig()) {
-      this.commandHandlers.env = args => handleEnv(this, args)
-    }
-    this.registerConfiguredCommandHandlers()
-
-    this.flagDefinitions = FLAG_DEFINITIONS
-    this.validateLoadedHelpConfig()
-  }
-
-  // 加载命令配置
-  loadCommands() {
-    try {
-      const configPath = join(this.configDir, 'commands.json')
-      return JSON.parse(readFileSync(configPath, 'utf8'))
-    } catch (error) {
-      logger.error(`无法加载命令配置文件: ${join(this.configDir, 'commands.json')}`)
-      logger.error(error?.message || String(error))
-      process.exit(1)
-    }
-  }
-
-  validateLoadedHelpConfig() {
-    validateHelpConfig(this.commands, buildStrictHelpValidationContext(this))
-  }
-
-  // 检测并安装依赖
-  async ensureDependencies() {
-    const nodeModulesPath = join(process.cwd(), 'node_modules')
-
-    // 检查 node_modules 是否存在且包含关键依赖
-    if (!existsSync(nodeModulesPath) || !existsSync(join(nodeModulesPath, '.pnpm'))) {
-      logger.warn('检测到依赖未安装，正在自动安装...')
-      logger.info('将以 NODE_ENV=development 安装完整依赖（含 devDependencies）')
-      try {
-        execSync('pnpm install --frozen-lockfile', {
-          stdio: 'inherit',
-          cwd: process.cwd(),
-          env: {
-            ...process.env,
-            NODE_ENV: 'development', // 确保安装完整依赖（含 devDependencies）
-          },
-        })
-        logger.success('依赖安装完成')
-      } catch (error) {
-        logger.error('依赖安装失败，请手动执行: pnpm install')
-        process.exit(1)
-      }
-    }
-  }
-
-  requiresProjectDependencies() {
-    if (this.command !== 'deploy') return true
-    const targetConfig = this.commands?.deploy?.[this.subcommand]
-    if (targetConfig?.internal === 'artifact-deploy') return false
-    if (!this.flags.artifact) return true
-    return targetConfig?.internal !== 'backend-artifact-deploy'
-  }
-
-  // 每次启动时执行的检查流程
-  async runStartupChecks() {
-    // 0. 跳过 db 命令的启动检查
-    // 原因：ensurePrismaClient() 会调用 `dx db generate`，如果不跳过会导致无限递归
-    // db 命令本身不需要 Prisma Client 或环境变量验证即可执行
-    if (this.command === 'db') return
-    // 通用 artifact target 的构建与部署生命周期完全由自身命令定义，
-    // 不应隐式安装 pnpm 依赖、生成 Prisma Client 或校验 backend 环境。
-    if (
-      this.command === 'deploy'
-      && this.commands?.deploy?.[this.subcommand]?.internal === 'artifact-deploy'
-    ) return
-
-    // 1. 在 worktree 中自动同步根目录的 .env.*.local 文件
-    try {
-      const worktreeManager = await this.getWorktreeManager()
-      worktreeManager.syncEnvFilesFromMainRoot()
-    } catch (error) {
-      logger.warn(`自动同步 env 文件失败: ${error.message}`)
-    }
-
-    // 2. 检测 Prisma Client 是否存在，不存在则执行 db generate
-    await this.ensurePrismaClient()
-
-    // 3. 验证环境变量（尊重多种跳过机制）
-    // 跳过条件：
-    // - 命令配置了 skipEnvValidation: true（如 lint）
-    // - 子命令配置了 skipEnvValidation: true（如 build.shared）
-    // - 用户指定了 --no-env-check 标志
-    // - 环境变量 AI_SKIP_ENV_CHECK=true（CI 场景）
-    // - CI 环境（CI=1）- 由 exec.js 中的 executeCommand 进行精细检查
-    // - Vercel 构建环境（VERCEL=1）
-    const commandConfig = this.getCommandConfig(this.command)
-    const subcommandConfig = this.subcommand ? commandConfig?.[this.subcommand] : null
-    const isVercelEnv = String(process.env.VERCEL || '').toLowerCase() === '1'
-    // 兼容 GitHub Actions (CI=true) 和其他 CI 系统 (CI=1)
-    const isCIEnv = ['true', '1'].includes(String(process.env.CI || '').toLowerCase())
-    const skipEnvValidation =
-      commandConfig?.skipEnvValidation ||
-      subcommandConfig?.skipEnvValidation ||
-      this.flags.noEnvCheck ||
-      String(process.env.AI_SKIP_ENV_CHECK || '').toLowerCase() === 'true' ||
-      isCIEnv ||
-      isVercelEnv
-
-    if (!skipEnvValidation) {
-      await this.validateEnvVars()
-    }
-  }
-
-  // 获取命令配置
-  getCommandConfig(command) {
-    return this.commands[command]
-  }
-
-  hasEnvProfileConfig() {
-    return existsSync(join(this.configDir, 'env-profiles.json'))
-  }
-
-  registerConfiguredCommandHandlers() {
-    this.configuredCommandNames = new Set()
-    for (const [commandName, config] of Object.entries(this.commands || {})) {
-      if (commandName === 'help') continue
-      if (this.commandHandlers[commandName]) continue
-      if (!this.isExecutableConfigTree(config)) continue
-
-      this.commandHandlers[commandName] = args => this.handleConfiguredCommand(commandName, args)
-      this.configuredCommandNames.add(commandName)
-    }
-  }
-
-  isExecutableConfigTree(node) {
-    if (!node || typeof node !== 'object' || Array.isArray(node)) return false
-    if (node.command || node.internal || node.concurrent || node.sequential) return true
-
-    return Object.entries(node).some(([key, value]) => {
-      if (key === 'help' || key === 'description' || key === 'args') return false
-      if (key === 'app' || key === 'ports' || key === 'dangerous') return false
-      return this.isExecutableConfigTree(value)
-    })
-  }
-
-  async handleConfiguredCommand(commandName, args = []) {
-    const environment = this.determineEnvironment()
-    const config = this.resolveConfiguredCommand(commandName, args, environment)
-
-    if (!config) {
-      const path = [commandName, ...args].join('.')
-      logger.error(`未找到命令配置: ${path}`)
-      process.exitCode = 1
-      return
-    }
-
-    const passthroughArgs = getPassthroughArgs(this.args)
-    this.validateConfiguredPassthrough(config, passthroughArgs)
-
-    if (config.dangerous) {
-      const operation = config.description || [commandName, ...args].join(' ')
-      const confirmed = await confirmManager.confirmDangerous(operation, environment, this.flags.Y)
-      if (!confirmed) {
-        logger.warn('操作已取消')
-        return
-      }
-    }
-
-    if (config.concurrent && Array.isArray(config.commands)) {
-      await this.handleConcurrentCommands(config.commands, null, environment)
-    } else if (config.sequential && Array.isArray(config.commands)) {
-      await this.handleSequentialCommands(config.commands, environment)
-    } else {
-      await this.executeCommand(config, undefined, passthroughArgs)
-    }
-  }
-
-  validateConfiguredPassthrough(config, args) {
-    if (args.length === 0) return
-    if (config?.internal || config?.concurrent || config?.sequential || !config?.command) {
-      throw new Error('此命令类型不支持 -- 参数透传；仅普通 command 叶节点支持，请移除额外参数或改用独立脚本命令。')
-    }
-    if (config.allowPassthrough !== true) {
-      throw new Error('此命令未启用参数透传；请在选中的 command 叶节点设置 allowPassthrough: true，并使用 dx <命令路径> [环境标志] -- <子命令参数>。')
-    }
-  }
-
-  resolveConfiguredCommand(commandName, args = [], environment) {
-    let config = this.commands?.[commandName]
-    if (!config) return null
-
-    for (const arg of args) {
-      if (!config || typeof config !== 'object' || Array.isArray(config)) return null
-      config = config[arg]
-      if (!config) return null
-    }
-
-    if (environment && config && typeof config === 'object' && !Array.isArray(config)) {
-      const envKey = this.normalizeEnvKey(environment)
-      if (config[envKey]) config = config[envKey]
-    }
-
-    return config
-  }
-
-  // 检测并生成 Prisma Client
-  async ensurePrismaClient() {
-    // 仅对真正安装了 @prisma/client 的项目执行检查。
-    // 依据「node_modules/@prisma/client/package.json 是否存在」判断项目是否使用 Prisma，
-    // 避免在纯文档站、纯前端等未引入 Prisma 的项目上误触发生成流程，
-    // 进而报出形如「未找到 db.generate 命令配置」的误导性错误。
-    const prismaClientDir = join(process.cwd(), 'node_modules', '@prisma', 'client')
-    if (!existsSync(join(prismaClientDir, 'package.json'))) {
-      return
-    }
-
-    // pnpm 结构下检测 @prisma/client 生成的 default.js 文件
-    const prismaClientPath = join(prismaClientDir, 'default.js')
-
-    if (!existsSync(prismaClientPath)) {
-      const environment = this.determineEnvironment()
-      logger.step('检测到 Prisma Client 未生成，正在生成...')
-      try {
-        const generateConfig = this.commands?.db?.generate
-        if (!generateConfig?.command) {
-          throw new Error('未找到 db.generate 命令配置，请检查 dx/config/commands.json')
-        }
-
-        await execManager.executeCommand(generateConfig.command, {
-          app: generateConfig.app || 'backend',
-          flags: this.createExecutionFlags(environment),
-          // Prisma generate 不应卡在环境变量校验上
-          skipEnvValidation: true,
-        })
-        logger.success('Prisma Client 生成完成')
-      } catch (error) {
-        logger.error('Prisma Client 生成失败')
-        logger.error(error?.message || String(error))
-        process.exit(1)
-      }
-    }
-  }
-
-  // 验证环境变量
-  async validateEnvVars() {
-    const environment = this.determineEnvironment()
-
-    if (this.envCache?.environment === environment) {
-      return this.envCache.layeredEnv
-    }
-
-    try {
-      validateEnvironment()
-
-      const layeredEnv = envManager.collectEnvFromLayers('backend', environment)
-      if (envManager.latestEnvWarnings && envManager.latestEnvWarnings.length > 0) {
-        envManager.latestEnvWarnings.forEach(message => {
-          logger.warn(message)
-        })
-      }
-
-      // CI 环境跳过后端环境变量校验（CI 中 build backend 只生成 OpenAPI，不需要数据库连接）
-      // 非 CI 环境下，检查 backend 组的环境变量
-      if (process.env.CI !== '1') {
-        const effectiveEnv = { ...process.env, ...layeredEnv }
-        const policy = loadEnvPolicy(envManager.configDir)
-        const targetId = resolvePolicyTargetId(policy, 'backend')
-        if (!targetId) {
-          throw new Error('缺少 appToTarget.backend 配置（dx 内置逻辑需要 backend target）')
-        }
-        const requiredVars = resolveTargetRequiredVars(policy, targetId, environment)
-        if (requiredVars.length > 0) {
-          const { valid, missing, placeholders } = envManager.validateRequiredVars(
-            requiredVars,
-            effectiveEnv,
-          )
-          if (!valid) {
-            const problems = ['环境变量校验未通过']
-            if (missing.length > 0) {
-              problems.push(`缺少必填环境变量: ${missing.join(', ')}`)
-            }
-            if (placeholders.length > 0) {
-              problems.push(`以下环境变量仍为占位值或空串: ${placeholders.join(', ')}`)
-            }
-            if (missing.length > 0 || placeholders.length > 0) {
-              problems.push(`请在 .env.${environment} / .env.${environment}.local 中补齐配置`)
-            }
-            throw new Error(problems.join('\n'))
-          }
-        }
-      }
-
-      this.envCache = { environment, layeredEnv }
-      return layeredEnv
-    } catch (error) {
-      logger.error('环境变量验证失败')
-      logger.error(error.message)
-      process.exit(1)
-    }
-  }
-
-  // 获取环境对应的命令行 flag
-  getEnvironmentFlag(environment) {
-    switch (environment) {
-      case 'production':
-        return '--prod'
-      case 'staging':
-        return '--staging'
-      case 'test':
-        return '--test'
-      case 'e2e':
-        return '--e2e'
-      case 'development':
-      default:
-        return '--dev'
-    }
-  }
-
-  // 主执行方法
-  async run() {
-    try {
-      if (this.flags.version) {
-        console.log(getPackageVersion())
-        return
-      }
-
-      // 显示帮助
-      if (this.flags.help || !this.command) {
-        if (this.flags.help && this.command && this.command !== 'help') {
-          showCommandHelp(this.command, this)
-        } else {
-          showHelp(this)
-        }
-        return
-      }
-
-      this.validateInputs()
-
-      // Reject unsupported custom argv before dependency installation or startup hooks.
-      if (this.configuredCommandNames.has(this.command)) {
-        const consumed = this.validateFlags(this.command, this.getAllowedFlags(this.command))
-        const [, ...args] = getCleanArgsWithConsumedValues(this.args, consumed)
-        const config = this.resolveConfiguredCommand(this.command, args, this.determineEnvironment())
-        this.validateConfiguredPassthrough(config, getPassthroughArgs(this.args))
-      }
-
-      // Fail fast for unknown commands before dependency/env startup checks.
-      if (this.command && !this.commandHandlers[this.command]) {
-        logger.error(`未知命令: ${this.command}`)
-        showHelp(this)
-        process.exit(1)
-      }
-
-      // Commands that should work without env/dependency checks.
-      // - help: printing help should never require env vars.
-      // - status: should be available even when env is incomplete.
-      // - release: only edits package.json versions.
-      const skipStartupChecks = new Set(['help', 'status', 'release'])
-      if (this.command === 'env' && this.hasEnvProfileConfig()) skipStartupChecks.add('env')
-      if (skipStartupChecks.has(this.command)) {
-        await this.routeCommand()
-        return
-      }
-
-      // 在执行命令前先校验参数与选项
-      if (this.requiresProjectDependencies()) await this.ensureDependencies()
-      await this.runStartupChecks()
-
-      // 设置详细模式
-      if (this.flags.verbose) {
-        logger.debug('启用详细输出模式')
-      }
-
-      // 路由到对应的命令处理器
-      await this.routeCommand()
-
-    } catch (error) {
-      logger.error('命令执行失败')
-      logger.error(error.message)
-
-      if (this.flags.verbose) {
-        console.error(error.stack)
-      }
-
-      process.exit(1)
-    }
-  }
-
-  // 命令路由
-  async routeCommand() {
-    const command = getCleanArgs(this.args)[0]
-
-    const allowedFlags = this.getAllowedFlags(command)
-    const consumedFlagValueIndexes = this.validateFlags(command, allowedFlags)
-    const cleanArgs = getCleanArgsWithConsumedValues(this.args, consumedFlagValueIndexes)
-    const [, ...subArgs] = cleanArgs
-
-    if (!command) {
-      showHelp(this)
-      return
-    }
-
-    const handler = this.commandHandlers[command]
-    if (!handler) return
-
-    const result = await handler(subArgs)
-    if (result === COMMAND_NOT_HANDLED) {
-      if (this.isExecutableConfigTree(this.commands?.[command])) {
-        await this.handleConfiguredCommand(command, subArgs)
-        return
-      }
-
-      logger.error(`未找到命令: ${[command, ...subArgs].join(' ')}`)
-      showCommandHelp(command, this)
-      process.exitCode = 1
-    }
-  }
-
-  // 校验原始输入，禁止未识别的选项或多余参数
-  validateInputs() {
-    const cleanArgs = getCleanArgs(this.args)
-    const command = cleanArgs[0]
-    const allowedFlags = this.getAllowedFlags(command)
-    const consumedFlagValueIndexes = this.validateFlags(command, allowedFlags)
-
-    // 收集所有位置参数（不含命令本身、选项及其值）
-    const positionalArgs = []
-    let commandConsumed = false
-    let afterDoubleDash = false
-    for (let i = 0; i < this.args.length; i++) {
-      const token = this.args[i]
-      if (token === '--') {
-        afterDoubleDash = true
-        continue
-      }
-      if (afterDoubleDash) continue
-      if (token.startsWith('-')) continue
-      if (consumedFlagValueIndexes.has(i)) continue
-
-      if (!commandConsumed && command) {
-        // 跳过命令本身
-        commandConsumed = true
-        continue
-      }
-
-      positionalArgs.push(token)
-    }
-
-    if (!command) {
-      if (positionalArgs.length > 0) {
-        this.reportExtraPositionals('全局', positionalArgs)
-      }
-      return
-    }
-
-    this.validatePositionalArgs(command, positionalArgs)
-  }
-
-  // 获取命令允许的选项
-  getAllowedFlags(command) {
-    const allowed = new Map()
-    const applyDefs = defs => {
-      defs?.forEach(({ flag, expectsValue }) => {
-        if (!flag) return
-        allowed.set(flag, { expectsValue: Boolean(expectsValue) })
-      })
-    }
-
-    applyDefs(this.flagDefinitions._global)
-    if (command && this.flagDefinitions[command]) {
-      applyDefs(this.flagDefinitions[command])
-    }
-
-    return allowed
-  }
-
-  // 校验选项合法性并返回被选项消耗的参数下标集合
-  validateFlags(command, allowedFlags) {
-    const consumedIndexes = new Set()
-    const doubleDashIndex = this.args.indexOf('--')
-
-    for (let i = 0; i < this.args.length; i++) {
-      if (doubleDashIndex !== -1 && i >= doubleDashIndex) break
-      const token = this.args[i]
-      if (!token.startsWith('-')) continue
-
-      const spec = allowedFlags.get(token)
-      if (!spec) {
-        this.reportUnknownFlag(command, token, allowedFlags)
-        process.exit(1)
-      }
-
-      if (spec.expectsValue) {
-        const next = this.args[i + 1]
-        if (next === undefined || next.startsWith('-')) {
-          logger.error(`选项 ${token} 需要提供参数值`)
-          process.exit(1)
-        }
-        consumedIndexes.add(i + 1)
-      }
-    }
-
-    return consumedIndexes
-  }
-
-  // 根据命令定义校验位置参数
-  validatePositionalArgs(command, positionalArgs) {
-    const ensureMax = (max) => {
-      if (positionalArgs.length > max) {
-        this.reportExtraPositionals(command, positionalArgs.slice(max))
-      }
-    }
-
-    switch (command) {
-      case 'help':
-        ensureMax(1)
-        break
-      case 'build': {
-        this.validateBuildPositionals(positionalArgs)
-        if (positionalArgs.length >= 2 && this.isEnvironmentToken(positionalArgs[1])) {
-          this.reportEnvironmentFlagRequired(command, positionalArgs[1], positionalArgs)
-        }
-        ensureMax(1)
-        break
-      }
-      case 'package': {
-        if (positionalArgs.length >= 2 && this.isEnvironmentToken(positionalArgs[1])) {
-          this.reportEnvironmentFlagRequired(command, positionalArgs[1], positionalArgs)
-        }
-        ensureMax(1)
-        break
-      }
-      case 'db': {
-        if (positionalArgs.length === 0) return
-        const action = positionalArgs[0]
-        const extras = positionalArgs.slice(1)
-        const envToken = extras.find(token => this.isEnvironmentToken(token))
-        if (envToken) {
-          this.reportEnvironmentFlagRequired(command, envToken, positionalArgs)
-        }
-
-        if (action === 'migrate') {
-          if (extras.length > 0) {
-            this.reportExtraPositionals(command, extras)
-          }
-        } else if (action === 'deploy') {
-          if (extras.length > 0) {
-            this.reportExtraPositionals(command, extras)
-          }
-        } else if (action === 'script') {
-          // script 子命令需要一个脚本名称参数
-          if (extras.length > 1) {
-            this.reportExtraPositionals(command, extras.slice(1))
-          }
-        } else if (extras.length > 0) {
-          this.reportExtraPositionals(command, extras)
-        }
-        break
-      }
-      case 'test':
-        this.validateTestPositionals(positionalArgs)
-        if ((positionalArgs[0] || 'e2e') !== 'unit') {
-          ensureMax(3)
-        }
-        break
-      case 'worktree': {
-        if (positionalArgs.length === 0) return
-        const action = positionalArgs[0]
-        if (action === 'del') {
-          return
-        }
-        if (action === 'make') {
-          ensureMax(3)
-          break
-        }
-        if (action === 'list' || action === 'clean') {
-          ensureMax(1)
-          break
-        }
-        break
-      }
-      case 'start': {
-        this.validateStartPositionals(positionalArgs)
-        const extras = positionalArgs.slice(1)
-        const envToken = extras.find(token => this.isEnvironmentToken(token))
-        if (envToken) {
-          this.reportEnvironmentFlagRequired(command, envToken, positionalArgs)
-        }
-        ensureMax(1)
-        break
-      }
-      case 'lint':
-        ensureMax(0)
-        break
-      case 'clean':
-        ensureMax(1)
-        break
-      case 'cache':
-        ensureMax(1)
-        break
-      case 'status':
-        ensureMax(0)
-        break
-      default:
-        // 默认放行，具体命令内部再校验
-        break
-    }
-  }
-
-  isEnvironmentToken(token) {
-    if (!token) return false
-    const value = String(token).toLowerCase()
-    return (
-      value === 'dev' ||
-      value === 'prod' ||
-      value === 'staging' ||
-      value === 'test' ||
-      value === 'e2e'
-    )
-  }
-
-  reportEnvironmentFlagRequired(command, token, positionalArgs = []) {
-    const normalizedFlag = this.getEnvironmentFlagExample(token)
-    logger.error(`命令 ${command} 不再支持通过位置参数指定环境: ${token}`)
-    logger.info('请使用带前缀的环境标志，例如 --dev、--staging、--prod、--test 或 --e2e。')
-    const suggestion = normalizedFlag
-      ? this.buildEnvironmentSuggestion(command, normalizedFlag, positionalArgs, token)
-      : null
-    if (suggestion) {
-      logger.info(`建议命令: ${suggestion}`)
-    } else if (normalizedFlag) {
-      logger.info(`示例: ${this.invocation} ${command} ... ${normalizedFlag}`)
-    }
-    logger.info('未显式指定环境时将默认使用 --dev。')
-    process.exit(1)
-  }
-
-  getEnvironmentFlagExample(token) {
-    switch (String(token || '').toLowerCase()) {
-      case 'dev':
-      case 'development':
-        return '--dev'
-      case 'prod':
-      case 'production':
-        return '--prod'
-      case 'staging':
-        return '--staging'
-      case 'test':
-        return '--test'
-      case 'e2e':
-        return '--e2e'
-      default:
-        return null
-    }
-  }
-
-  buildEnvironmentSuggestion(command, normalizedFlag, positionalArgs, token) {
-    const parts = [this.invocation, command]
-    const rest = Array.isArray(positionalArgs) ? [...positionalArgs] : []
-    if (rest.length > 0) {
-      const matchIndex = rest.findIndex(arg => String(arg).toLowerCase() === String(token).toLowerCase())
-      if (matchIndex !== -1) rest.splice(matchIndex, 1)
-    }
-    if (!rest.includes(normalizedFlag)) {
-      rest.push(normalizedFlag)
-    }
-    return parts.concat(rest).join(' ')
-  }
-
-  validateTestPositionals(positionalArgs) {
-    const [type = 'e2e', target = 'all', testPath] = positionalArgs
-
-    if (type !== 'e2e') return
-
-    if (target === 'all') {
-      logger.error('dx test e2e all 不受支持，请指定 target 和测试文件或目录路径')
-      process.exit(1)
-    }
-
-    const testConfig = this.commands?.test?.[type]?.[target]
-    if (!testConfig) return
-    if (!testConfig.requiresPath) return
-
-    if (!testPath) {
-      logger.error(`dx test e2e ${target} 必须提供测试文件或目录路径`)
-      logger.info(`示例: ${this.invocation} test e2e ${target} apps/${target}/e2e/health`)
-      process.exit(1)
-    }
-
-    if (testPath === 'all') {
-      logger.error(`dx test e2e ${target} 不支持 all，必须提供测试文件或目录路径`)
-      process.exit(1)
-    }
-  }
-
-  validateStartPositionals(positionalArgs) {
-    const service = positionalArgs[0] || 'development'
-    const environment = this.determineEnvironment()
-    const envKey = this.normalizeEnvKey(environment)
-
-    if (service === 'development' && envKey !== 'development') {
-      logger.error('dx start 在未指定服务时仅允许使用开发环境')
-      logger.info(`示例: ${this.invocation} start --dev`)
-      logger.info(`示例: ${this.invocation} start backend --prod`)
-      process.exit(1)
-    }
-
-    const startConfig = this.commands?.start?.[service]
-    if (!startConfig) return
-
-    // 对 start 下的单层 command 配置，默认视为开发态目标，仅允许 --dev。
-    if (startConfig.command && envKey !== 'development') {
-      logger.error(`启动目标 ${service} 仅支持开发环境`)
-      logger.info(`示例: ${this.invocation} start ${service} --dev`)
-      process.exit(1)
-    }
-  }
-
-  validateBuildPositionals(positionalArgs) {
-    const target = positionalArgs[0] || 'all'
-    const environment = this.determineEnvironment()
-    const envKey = this.normalizeEnvKey(environment)
-    const explicitEnv = Boolean(
-      this.flags.dev || this.flags.prod || this.flags.staging || this.flags.test || this.flags.e2e,
-    )
-
-    if (!explicitEnv) return
-
-    const buildConfig = this.commands?.build?.[target]
-    if (!buildConfig || buildConfig.command) return
-
-    const supportsCurrentEnv = Boolean(buildConfig[envKey])
-    if (supportsCurrentEnv) return
-
-    const envFlag = this.getEnvironmentFlagExample(envKey) || `--${envKey}`
-    logger.error(`构建目标 ${target} 不支持 ${envFlag} 环境`)
-    logger.info('显式传入环境标志时，必须是该 target 实际支持的环境。')
-    const available = ['development', 'staging', 'production', 'test', 'e2e']
-      .filter(key => key in buildConfig)
-      .map(key => this.getEnvironmentFlagExample(key) || `--${key}`)
-    if (available.length > 0) {
-      logger.info(`支持的环境: ${available.join(', ')}`)
-      logger.info(`示例: ${this.invocation} build ${target} ${available[0]}`)
-      if (available.length > 1) {
-        logger.info(`示例: ${this.invocation} build ${target} ${available[1]}`)
-      }
-    }
-    process.exit(1)
-  }
-
-  reportExtraPositionals(command, extras) {
-    const list = extras.join(', ')
-    if (command === '全局') {
-      logger.error(`检测到未识别的参数: ${list}`)
-    } else {
-      logger.error(`命令 ${command} 存在未识别的额外参数: ${list}`)
-    }
-    const hint = command && command !== '全局' ? `${this.invocation} help ${command}` : `${this.invocation} --help`
-    logger.info(`提示: 执行 ${hint} 或 ${this.invocation} --help 查看命令用法`)
-    if (command && command !== '全局') {
-      logger.info(`示例: ${this.invocation} ${command} --help`)
-    }
-    process.exit(1)
-  }
-
-  reportUnknownFlag(command, flag, allowedFlags) {
-    logger.error(`检测到未识别的选项: ${flag}`)
-    logger.info('自定义命令参数请放在 -- 后，并在 command 叶节点设置 allowPassthrough: true。')
-    const supported = Array.from(allowedFlags.keys())
-    if (supported.length > 0) {
-      logger.info(`支持的选项: ${supported.join(', ')}`)
-    } else if (command) {
-      logger.info(`命令 ${command} 不接受额外选项`)
-    }
-    const hint = command ? `${this.invocation} help ${command}` : `${this.invocation} --help`
-    logger.info(`提示: 执行 ${hint} 或 ${this.invocation} --help 查看命令用法`)
-    if (command) {
-      logger.info(`示例: ${this.invocation} ${command} --help`)
-    }
-  }
-
-  // 校验是否在仓库根目录执行
-  ensureRepoRoot() {
-    const cwd = process.cwd()
-
-    const markers = ['pnpm-workspace.yaml', 'package.json', 'apps']
-    const missing = markers.filter(p => !existsSync(join(cwd, p)))
-    if (missing.length) {
-      logger.error(`请从仓库根目录运行此命令。缺少标识文件/目录: ${missing.join(', ')}`)
-      process.exit(1)
-    }
-
-    const commandsPath = join(this.configDir, 'commands.json')
-    if (!existsSync(commandsPath)) {
-      logger.error(`未找到命令配置文件: ${commandsPath}`)
-      process.exit(1)
-    }
-  }
-
-  async getWorktreeManager() {
-    if (!this.worktreeManager) {
-      const { default: worktreeManager } = await import('../worktree.js')
-      this.worktreeManager = worktreeManager
-    }
-    return this.worktreeManager
-  }
-
-  // 并发命令处理
-  async handleConcurrentCommands(commandPaths, baseCommand, environment) {
-    const commands = []
-
-    for (const path of commandPaths) {
-      const config = this.resolveCommandPath(
-        path,
-        baseCommand,
-        this.normalizeEnvKey(environment)
-      )
-      if (!config) {
-        logger.warn(`未解析到命令配置: ${path} (${environment || '-'})`)
-        continue
-      }
-      commands.push({
-        command: config.command,
-        options: {
-          app: config.app,
-          ports: config.ports,
-          flags: this.flags,
-        },
-      })
-    }
-
-    if (commands.length > 0) {
-      await execManager.executeConcurrent(commands)
-    }
-  }
-
-  // 顺序命令处理
-  async handleSequentialCommands(commandPaths, environment) {
-    for (const path of commandPaths) {
-      const config = this.resolveCommandPath(path, null, this.normalizeEnvKey(environment))
-      if (!config) {
-        logger.warn(`未解析到命令配置: ${path} (${environment || '-'})`)
-        continue
-      }
-
-      // 支持在顺序执行中嵌套并发/顺序配置
-      if (config.concurrent && Array.isArray(config.commands)) {
-        await this.handleConcurrentCommands(config.commands, null, environment)
-      } else if (config.sequential && Array.isArray(config.commands)) {
-        await this.handleSequentialCommands(config.commands, environment)
-      } else {
-        await this.executeCommand(config)
-      }
-    }
-  }
-
-  // 解析命令路径
-  resolveCommandPath(path, baseCommand, environment) {
-    const parts = path.split('.')
-    let config = this.commands
-
-    for (const part of parts) {
-      config = config[part]
-      if (!config) break
-    }
-
-    // 如果有环境参数，尝试获取对应环境的配置
-    if (environment && config) {
-      const envKey = this.normalizeEnvKey(environment)
-      if (config[envKey]) config = config[envKey]
-    }
-
-    return config
-  }
-
-  collectStartPorts(service, startConfig, envKey) {
-    const portSet = new Set()
-
-    if (startConfig && Array.isArray(startConfig.ports)) {
-      startConfig.ports.forEach(port => {
-        this.addPortToSet(portSet, port)
-      })
-    }
-
-    return Array.from(portSet)
-  }
-
-  addPortToSet(target, port) {
-    const numeric = Number(port)
-    if (Number.isFinite(numeric) && numeric > 0) {
-      target.add(numeric)
-    }
-  }
-
-  // 执行单个命令
-  async executeCommand(config, overrideFlags, passthroughArgs = []) {
-    this.validateConfiguredPassthrough(config, passthroughArgs)
-    if (!config) {
-      logger.error('无效的命令配置')
-      return
-    }
-
-    const withTempEnv = async fn => {
-      const envPatch = config?.env && typeof config.env === 'object' ? config.env : null
-      if (!envPatch) return await fn()
-
-      const previous = {}
-      for (const [key, value] of Object.entries(envPatch)) {
-        previous[key] = Object.prototype.hasOwnProperty.call(process.env, key)
-          ? process.env[key]
-          : undefined
-        process.env[key] = String(value)
-      }
-
-      try {
-        return await fn()
-      } finally {
-        for (const [key, oldValue] of Object.entries(previous)) {
-          if (oldValue === undefined) delete process.env[key]
-          else process.env[key] = oldValue
-        }
-      }
-    }
-
-    // internal runners (for projects that only ship scripts/config)
-    if (config.internal) {
-      if (config.internal === 'sdk-build') {
-        await withTempEnv(async () => {
-          const { runSdkBuild } = await import('../sdk-build.js')
-          await runSdkBuild(Array.isArray(config.args) ? config.args : [])
-        })
-        return
-      }
-      if (config.internal === 'backend-package') {
-        await withTempEnv(async () => {
-          const { runBackendPackage } = await import('../backend-package.js')
-          await runBackendPackage(Array.isArray(config.args) ? config.args : [])
-        })
-        return
-      }
-
-      if (config.internal === 'start-dev') {
-        await withTempEnv(async () => {
-          const { runStartDev } = await import('../start-dev.js')
-          await runStartDev(Array.isArray(config.args) ? config.args : [])
-        })
-        return
-      }
-
-      if (config.internal === 'pm2-stack') {
-        await withTempEnv(async () => {
-          const { runPm2Stack } = await import('./commands/stack.js')
-          const stackConfig = config.stack && typeof config.stack === 'object' ? config.stack : {}
-          await runPm2Stack(stackConfig)
-        })
-        return
-      }
-
-      throw new Error(`未知 internal runner: ${config.internal}`)
-    }
-
-    if (!config.command) {
-      logger.error('无效的命令配置: 缺少 command/internal')
-      return
-    }
-
-    const effectiveFlags = overrideFlags || this.flags
-    let rawCommand = String(config.command).trim()
-    if (effectiveFlags.verbose) {
-      rawCommand = appendNxVerboseFlag(rawCommand)
-    }
-
-    const options = {
-      app: config.app,
-      flags: effectiveFlags,
-      cwd: config.cwd,
-      ports: config.ports || [],
-      // 允许上游在 config.env 中注入环境变量（例如 NX_CACHE=false）
-      env: config.env || {},
-      skipEnvValidation: Boolean(config.skipEnvValidation),
-      forcePortCleanup: Boolean(config.forcePortCleanup),
-      passthroughArgs,
-    }
-
-    await execManager.executeCommand(rawCommand, options)
-  }
-
-  // 确定环境
-  determineEnvironment() {
-    return envManager.detectEnvironment(this.flags)
-  }
-
-  // 规范化环境键到命令配置使用的命名（development/staging/production/test/e2e）
-  normalizeEnvKey(env) {
-    switch (String(env || '').toLowerCase()) {
-      case 'development':
-        return 'development'
-      case 'production':
-        return 'production'
-      case 'staging':
-        return 'staging'
-      case 'test':
-        return 'test'
-      case 'e2e':
-        return 'e2e'
-      default:
-        return env
-    }
-  }
-
-  createExecutionFlags(environment) {
-    const envKey = this.normalizeEnvKey(environment)
-    const execFlags = { ...this.flags }
-
-    ;['dev', 'prod', 'staging', 'test', 'e2e'].forEach(key => {
-      delete execFlags[key]
-    })
-
-    if (envKey === 'production') execFlags.prod = true
-    else if (envKey === 'development') execFlags.dev = true
-    else if (envKey === 'test') execFlags.test = true
-    else if (envKey === 'e2e') execFlags.e2e = true
-    else if (envKey === 'staging') execFlags.staging = true
-
-    return execFlags
-  }
-
-}
-
-export { DxCli }