@ranger1/dx 0.1.0

package/lib/cli/flags.js

@@ -0,0 +1,96 @@
+export const FLAG_DEFINITIONS = {
+  _global: [
+    { flag: '--dev' },
+    { flag: '--development' },
+    { flag: '--prod' },
+    { flag: '--production' },
+    { flag: '--staging' },
+    { flag: '--stage' },
+    { flag: '--test' },
+    { flag: '--e2e' },
+    { flag: '--no-env-check' },
+    { flag: '-Y' },
+    { flag: '--yes' },
+    { flag: '-v' },
+    { flag: '--verbose' },
+    { flag: '-h' },
+    { flag: '--help' },
+    { flag: '--parallel' },
+    { flag: '-P' },
+  ],
+  db: [
+    { flag: '--name', expectsValue: true },
+    { flag: '-n', expectsValue: true },
+  ],
+  test: [{ flag: '-t', expectsValue: true }],
+  package: [
+    { flag: '--skip-build' },
+    { flag: '--keep-workdir' },
+  ],
+  worktree: [
+    { flag: '--base', expectsValue: true },
+    { flag: '-b', expectsValue: true },
+    { flag: '--all' },
+  ],
+  lint: [
+    { flag: '--fix' },
+  ],
+}
+
+export function parseFlags(args = []) {
+  const flags = {}
+
+  for (const flag of args) {
+    if (flag === '--') break
+    if (!flag.startsWith('-')) continue
+    switch (flag) {
+      case '--dev':
+      case '--development':
+        flags.dev = true
+        break
+      case '--prod':
+      case '--production':
+        flags.prod = true
+        break
+      case '--staging':
+      case '--stage':
+        flags.staging = true
+        break
+      case '--test':
+        flags.test = true
+        break
+      case '--e2e':
+        flags.e2e = true
+        break
+      case '-Y':
+      case '--yes':
+        flags.Y = true
+        break
+      case '-v':
+      case '--verbose':
+        flags.verbose = true
+        break
+      case '-h':
+      case '--help':
+        flags.help = true
+        break
+      case '--no-env-check':
+        flags.noEnvCheck = true
+        break
+      case '--fix':
+        flags.fix = true
+        break
+      case '--parallel':
+      case '-P':
+        flags.parallel = true
+        break
+      case '--all':
+        flags.all = true
+        break
+      default:
+        break
+    }
+  }
+
+  return flags
+}

package/lib/cli/help.js

@@ -0,0 +1,209 @@
+export function showHelp() {
+  console.log(`
+DX CLI - 统一开发环境管理工具
+
+用法:
+  dx <命令> [选项] [参数...]
+
+命令:
+  start [service] [环境标志]  启动/桥接服务
+    service: backend, front, admin, all, dev, stack, stagewise-front, stagewise-admin (默认: dev)
+    stack: PM2 交互式服务栈管理（推荐）- 同时启动三个服务并提供交互式命令
+    环境标志: --dev, --staging, --prod, --test, --e2e（支持别名 --development、--production 等）
+    说明: 传入 --staging 时会加载 '.env.staging(.local)' 层，同时复用生产构建/启动流程
+
+  build [target] [环境标志]   构建应用
+    target: backend, shared, front, admin, mobile, all, sdk, affected (默认: all)
+    环境标志: --dev, --staging, --prod, --test, --e2e（未指定时默认 --dev）
+
+  deploy <target> [环境标志]  部署前端到 Vercel
+    target: front, admin, telegram-bot, all
+    环境标志: --dev, --staging, --prod（默认 --staging）
+
+  install                  安装依赖（使用 frozen-lockfile 确保版本一致）
+
+  package backend [环境标志]  构建后端部署包（生成 backend-<version>-<sha>.tar.gz）
+    环境标志: --dev, --staging, --prod, --test, --e2e（默认 --dev）
+    产物位置: dist/backend/backend-*.tar.gz
+    内含: dist/、node_modules(生产依赖)、prisma/、config/.env.runtime、bin/start.sh
+
+  db [action] [环境标志]      数据库操作
+    action: generate, migrate, deploy, reset, seed, format, script
+    用法示例:
+      dx db migrate --dev --name add_user_table   # 创建新的迁移（开发环境需指定名称）
+      dx db deploy --dev                          # 应用开发环境已有迁移
+      dx db deploy --prod                         # 生产环境迁移（复用 deploy 流程，需确认）
+      dx db script fix-email-verified-status --dev  # 运行数据库脚本（开发环境）
+      dx db script fix-pending-transfer-status --prod  # 运行数据库脚本（生产环境，需确认）
+      dx db script my-script --dev -- --arg1 --arg2  # 向脚本传递额外参数（-- 后面的部分）
+
+  test [type] [target] [path] [-t pattern]  运行测试
+    type: e2e, unit (默认: e2e)
+    target: backend, all (默认: all)
+    path: 测试文件路径 (可选，仅支持e2e backend)
+    -t pattern: 指定测试用例名称模式 (可选，需要和path一起使用)
+
+  worktree [action] [num...] Git Worktree管理
+    action: make, del, list, clean
+    num: issue编号 (make时需要1个，del时支持多个)
+    支持批量删除: dx worktree del 123 456 789
+    支持非交互式: dx worktree del 123 -Y
+  注意：该封装与原生 git worktree 行为不同，勿混用
+
+  lint                   运行代码检查
+
+  clean [target]         清理操作
+    target: all, deps (默认: all)
+
+  cache [action]         缓存清理
+    action: clear (默认: clear)
+
+  status                 查看系统状态
+
+选项:
+ --dev, --development   使用开发环境
+ --prod, --production   使用生产环境
+  --staging, --stage    使用预发环境（加载 .env.staging*.，复用生产流程）
+  --test                 使用测试环境
+  --e2e                  使用E2E测试环境
+  -Y, --yes              跳过所有确认提示
+  -v, --verbose          详细输出
+  -h, --help             显示此帮助信息
+
+示例:
+  dx start stack            # PM2 交互式服务栈（推荐）- 同时管理三个服务
+  dx start backend --dev    # 启动后端开发服务
+  dx start front --dev      # 启动用户前端开发服务
+  dx start admin --dev      # 启动管理后台开发服务
+  dx start all              # 同时启动所有开发服务（默认 --dev）
+  dx build all --prod       # 构建所有应用(生产环境)
+  dx db deploy --dev       # 应用开发环境数据库迁移
+  dx db reset --prod -Y     # 重置生产数据库(跳过确认)
+  dx test e2e backend                           # 运行后端E2E测试
+  dx test e2e backend e2e/activity/activity.admin.e2e-spec.ts  # 运行单个E2E测试文件
+  dx test e2e backend e2e/activity/activity.admin.e2e-spec.ts -t "should list all activity definitions"  # 运行特定测试用例
+  dx deploy front --staging # 部署前端到 Vercel（staging）
+  dx worktree make 88       # 为issue #88创建worktree
+  dx worktree del 88        # 删除issue #88的worktree
+  dx worktree del 88 89 90 -Y  # 批量删除多个worktree（非交互式）
+  dx worktree list          # 列出所有worktree
+  dx clean deps             # 清理并重新安装依赖
+  dx cache clear            # 清除 Nx 与依赖缓存
+
+  # Stagewise 桥接（固定端口，自动清理占用）
+  dx start stagewise-front      # 桥接 front: 3001 -> 3002（工作目录 apps/front）
+  dx start stagewise-admin      # 桥接 admin-front: 3500 -> 3501（工作目录 apps/admin-front）
+
+  # Start 用法示例
+  dx start backend --prod       # 以生产环境变量启动后端
+  dx start backend --dev        # 以开发环境变量启动后端
+  dx start backend --e2e        # 以 E2E 环境变量启动后端
+
+
+`)
+}
+
+export function showCommandHelp(command) {
+  const name = String(command || '').toLowerCase()
+
+  switch (name) {
+    case 'build':
+      console.log(`
+build 命令用法:
+  dx build <target> [环境标志]
+
+参数说明:
+  target: backend, front, admin, shared, mobile, sdk, all, affected
+  环境标志: --dev、--staging、--prod、--test、--e2e（默认 --dev）
+
+常见示例:
+  dx build backend --staging    # 使用 staging 环境变量构建后端 (prod 流程)
+  dx build front --prod         # 强制以生产配置构建前端
+  dx build mobile --staging     # 构建移动端 APK (staging 环境)
+  dx build mobile --prod        # 构建移动端 APK (生产环境)
+  dx build affected --dev       # 针对受影响项目执行开发态构建
+
+提示: 可通过 dx build <target> 分别构建受影响应用。
+`)
+      return
+
+    case 'db':
+      console.log(`
+db 命令用法:
+  dx db <action> [options]
+
+可选 action:
+  generate | migrate | deploy | reset | seed | format | script
+
+环境说明:
+  通过 --dev、--staging、--prod、--test、--e2e 指定 APP_ENV（默认 --dev）
+  --staging 会加载 .env.staging*. 文件，并复用 prod 的 Prisma / Nx 流程
+
+附加参数:
+  --name/-n <migration-name>    # 开发环境执行 migrate 必填，禁止通过位置参数传递
+
+帮助提示:
+  - 未提供迁移名称时命令会直接报错退出，避免 Prisma 进入交互式输入
+  - 使用模式示例: dx db migrate --dev --name init-user-table
+  - 如需仅执行已有迁移（本地/CI/生产），请使用 dx db deploy（无需 --name）
+
+script 子命令:
+  dx db script <script-name> [环境标志] [-- <脚本参数>...]
+  运行位于 apps/backend/prisma/scripts/ 目录下的数据库脚本
+
+  脚本参数说明:
+    使用 -- 分隔符后可传递任意参数给目标脚本
+    例如: dx db script my-script --dev -- --skip-cleanup --note="test"
+
+示例:
+  dx db migrate --dev --name init-user-table     # 创建新迁移（开发环境）
+  dx db deploy --dev                             # 应用开发环境已有迁移
+  dx db deploy --staging                         # 复用生产命令，加载 staging 环境变量
+  dx db reset --prod -Y                          # 生产环境重置 (需确认)
+  dx db script fix-email-verified-status --dev   # 运行数据库脚本（开发环境）
+  dx db script fix-pending-transfer-status --prod -Y  # 运行数据库脚本（生产环境，跳过确认）
+  dx db script guest-cleanup-verification --dev -- --help  # 查看脚本帮助
+  dx db script guest-cleanup-verification --dev -- --skip-cleanup --note="dry run"  # 传递脚本参数
+`)
+      return
+
+    case 'deploy':
+      console.log(`
+deploy 命令用法:
+  dx deploy <target> [环境标志]
+
+参数说明:
+  target: front, admin, telegram-bot, all
+  环境标志: --dev、--staging、--prod（默认 --staging）
+
+常见示例:
+  dx deploy front --staging           # 部署用户前端（staging）
+  dx deploy admin --prod              # 部署管理后台（生产）
+  dx deploy telegram-bot --staging    # 部署 Telegram Bot + 自动配置 Webhook
+  dx deploy all --staging             # 串行部署 front + admin
+`)
+      return
+
+    case 'start':
+      console.log(`
+start 命令用法:
+  dx start <service> [环境标志]
+
+服务说明:
+  service: backend, dev, stagewise-front, stagewise-admin
+
+环境说明:
+  支持 --dev、--staging、--prod、--test、--e2e。--staging 会注入 .env.staging*. 层并复用 prod 启动流程
+
+常见示例:
+  dx start backend --staging    # 使用 staging 配置启动后端 (生产模式流程)
+  dx start stagewise-front      # Stagewise 桥接用户前端，端口 3001 -> 3002
+
+提示: service 省略时默认启动 dev 套件，可结合 --dev/--staging/--prod 标志使用。
+`)
+      return
+
+    default:
+      showHelp()
+  }
+}

package/lib/cli/index.js

@@ -0,0 +1,4 @@
+export { DxCli } from './dx-cli.js'
+export { FLAG_DEFINITIONS, parseFlags } from './flags.js'
+export { getCleanArgs, getPassthroughArgs } from './args.js'
+export { showHelp, showCommandHelp } from './help.js'

package/lib/confirm.js

@@ -0,0 +1,213 @@
+import { createInterface } from 'node:readline'
+import { logger } from './logger.js'
+
+export class ConfirmManager {
+  constructor() {
+    this.rl = null
+  }
+
+  // 判断是否启用自动确认（CI 或显式环境变量）
+  isAutoYes(skipFlag = false) {
+    if (skipFlag) return true
+    const ci = String(process.env.CI || '').toLowerCase()
+    const autoYes = String(process.env.AI_CLI_YES || process.env.YES || '').toLowerCase()
+    // 常见 CI 环境会设置 CI=true；也支持自定义 AI_CLI_YES/YES 变量
+    return ci === 'true' || ci === '1' || autoYes === 'true' || autoYes === '1'
+  }
+
+  // 基础确认
+  async confirm(message, defaultValue = false, skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      logger.info(`跳过确认: ${message}`)
+      return true
+    }
+
+    const prompt = defaultValue ? `${message} [Y/n]: ` : `${message} [y/N]: `
+
+    return new Promise(resolve => {
+      this.rl = createInterface({
+        input: process.stdin,
+        output: process.stdout,
+      })
+
+      this.rl.question(prompt, answer => {
+        this.rl.close()
+
+        const normalized = answer.toLowerCase().trim()
+        if (normalized === '') {
+          resolve(defaultValue)
+        } else {
+          resolve(['y', 'yes', '是', 'true', '1'].includes(normalized))
+        }
+      })
+    })
+  }
+
+  // 危险操作确认
+  async confirmDangerous(operation, environment = 'unknown', skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      logger.warn(`跳过危险操作确认: ${operation}`)
+      return true
+    }
+
+    logger.separator()
+    logger.warn('警告: 即将执行危险操作')
+    console.log(`操作: ${operation}`)
+    console.log(`环境: ${environment}`)
+
+    if (environment === 'production' || environment === '生产环境') {
+      console.log(`🔥 此操作将在生产环境执行，可能导致数据丢失或服务中断`)
+      console.log(`🔥 请确保您已经：`)
+      console.log(`   1. 备份了重要数据`)
+      console.log(`   2. 通知了相关团队成员`)
+      console.log(`   3. 确认了操作的必要性`)
+    } else {
+      console.log(`此操作可能导致数据丢失，请谨慎操作`)
+    }
+
+    logger.separator()
+
+    // 对于生产环境，需要两次确认
+    if (environment === 'production' || environment === '生产环境') {
+      const firstConfirm = await this.confirm('您确定要在生产环境执行此危险操作吗？', false, false)
+      if (!firstConfirm) {
+        return false
+      }
+
+      console.log(`\n请再次确认，输入操作名称以继续: ${operation}`)
+      return new Promise(resolve => {
+        this.rl = createInterface({
+          input: process.stdin,
+          output: process.stdout,
+        })
+
+        this.rl.question('请输入操作名称: ', answer => {
+          this.rl.close()
+          resolve(answer.trim() === operation)
+        })
+      })
+    } else {
+      return this.confirm('确定要继续吗？', false, false)
+    }
+  }
+
+  // 批量操作确认
+  async confirmBatch(operations, skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      logger.info('跳过批量操作确认')
+      return true
+    }
+
+    logger.separator()
+    console.log('即将执行以下操作:')
+    operations.forEach((op, index) => {
+      console.log(`${index + 1}. ${op}`)
+    })
+    logger.separator()
+
+    return this.confirm('确认执行所有操作？', false, false)
+  }
+
+  // 端口冲突确认
+  async confirmPortCleanup(port, processes, skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      logger.info(`跳过端口清理确认: 端口 ${port}`)
+      return true
+    }
+
+    logger.warn(`端口 ${port} 被以下进程占用:`)
+    processes.forEach(pid => {
+      console.log(`  进程 ID: ${pid}`)
+    })
+
+    return this.confirm(`是否杀死这些进程以释放端口 ${port}？`, true, false)
+  }
+
+  // 环境切换确认
+  async confirmEnvironmentSwitch(from, to, skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      logger.info(`跳过环境切换确认: ${from} -> ${to}`)
+      return true
+    }
+
+    if (to === 'production' || to === '生产环境') {
+      logger.warn(`即将从 ${from} 切换到 ${to}`)
+      logger.warn('生产环境操作需要额外谨慎')
+      return this.confirm('确定要切换到生产环境吗？', false, false)
+    }
+
+    return this.confirm(`确定要从 ${from} 切换到 ${to} 吗？`, true, false)
+  }
+
+  // 文件覆盖确认
+  async confirmOverwrite(filePath, skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      logger.info(`跳过文件覆盖确认: ${filePath}`)
+      return true
+    }
+
+    logger.warn(`文件已存在: ${filePath}`)
+    return this.confirm('是否覆盖现有文件？', false, false)
+  }
+
+  // 清理操作确认
+  async confirmCleanup(targets, skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      logger.info('跳过清理操作确认')
+      return true
+    }
+
+    logger.warn('即将清理以下内容:')
+    targets.forEach(target => {
+      console.log(`  - ${target}`)
+    })
+
+    return this.confirm('确定要执行清理操作吗？', false, false)
+  }
+
+  // 服务启动确认（用于可能有端口冲突的情况）
+  async confirmServiceStart(service, port, skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      return true
+    }
+
+    return this.confirm(`确定要启动 ${service} 服务 (端口 ${port}) 吗？`, true, false)
+  }
+
+  // 版本发布确认
+  async confirmRelease(version, isProduction = false, skipFlag = false) {
+    if (this.isAutoYes(skipFlag)) {
+      logger.info(`跳过版本发布确认: ${version}`)
+      return true
+    }
+
+    if (isProduction) {
+      logger.warn(`即将发布生产版本: ${version}`)
+      logger.warn('此操作将创建正式发布标签')
+      return this.confirmDangerous(`发布版本 ${version}`, '生产环境', false)
+    } else {
+      return this.confirm(`确定要发布开发版本 ${version} 吗？`, true, false)
+    }
+  }
+
+  // 数据库操作确认
+  async confirmDatabaseOperation(operation, environment, skipFlag = false) {
+    const dangerousOps = ['reset', 'drop', 'migrate:reset', 'db:reset']
+    const isDangerous = dangerousOps.some(op => operation.includes(op))
+
+    if (isDangerous) {
+      return this.confirmDangerous(
+        `数据库操作: ${operation}`,
+        environment,
+        this.isAutoYes(skipFlag),
+      )
+    } else {
+      if (this.isAutoYes(skipFlag)) {
+        return true
+      }
+      return this.confirm(`确定要执行数据库操作: ${operation} (${environment}) 吗？`, true, false)
+    }
+  }
+}
+
+export const confirmManager = new ConfirmManager()