@weotro/dx 0.1.0

package/lib/cli/commands/db.js

@@ -0,0 +1,231 @@
+import { logger } from '../../logger.js'
+import { confirmManager } from '../../confirm.js'
+import { envManager } from '../../env.js'
+import { getPassthroughArgs } from '../args.js'
+
+export async function handleDatabase(cli, args) {
+  const action = args[0]
+  if (!action) {
+    logger.error('请指定数据库操作: generate, migrate, deploy, reset, seed, format, script')
+    process.exitCode = 1
+    return
+  }
+
+  const dbConfig = cli.commands.db[action]
+  if (!dbConfig) {
+    logger.error(`未找到数据库操作: ${action}`)
+    process.exitCode = 1
+    return
+  }
+
+  const environment = cli.determineEnvironment()
+  const envKey = cli.normalizeEnvKey(environment)
+
+  // 创建迁移只允许在开发环境进行，避免 AI/用户在非开发环境误执行
+  if (action === 'migrate' && envKey && envKey !== 'development') {
+    const envFlag = cli.getEnvironmentFlagExample(envKey) || `--${envKey}`
+    logger.error('dx db migrate 仅允许在 --dev 环境下创建迁移')
+    logger.info('请使用 `dx db migrate --dev --name <migration-name>` 创建新迁移。')
+    logger.info(`非开发环境请改用: ${cli.invocation} db deploy ${envFlag}`)
+    process.exitCode = 1
+    return
+  }
+
+  // 处理 script 子命令
+  if (action === 'script') {
+    const scriptName = args[1]
+    if (!scriptName) {
+      logger.error('请指定要运行的脚本名称')
+      logger.info('用法: dx db script <script-name> [环境标志]')
+      logger.info('示例: dx db script fix-email-verified-status --dev')
+      process.exitCode = 1
+      return
+    }
+    return await handleDatabaseScript(cli, scriptName, envKey, dbConfig)
+  }
+
+  logger.step(`执行数据库操作: ${action} (${environment})`)
+
+  // 处理嵌套配置
+  let config = dbConfig
+  if (typeof config === 'object' && !config.command) {
+    // 严格按显式环境选择配置，不做环境回退
+    if (config[envKey]) config = config[envKey]
+    else config = null
+  }
+
+  if (!config) {
+    logger.error(`数据库操作 ${action} 未提供 ${cli.getEnvironmentFlagExample(envKey) || envKey} 环境配置`)
+    process.exitCode = 1
+    return
+  }
+
+  // 危险操作确认
+  if (config.dangerous) {
+    const confirmed = await confirmManager.confirmDatabaseOperation(
+      action,
+      envManager.getEnvironmentDescription(environment),
+      cli.flags.Y,
+    )
+
+    if (!confirmed) {
+      logger.info('操作已取消')
+      return
+    }
+  }
+
+  // 支持为 migrate 传入迁移名：--name/-n
+  let command = config.command
+  if (action === 'migrate' && envKey === 'development') {
+    const allArgs = cli.args
+    let migrationName = null
+    // 优先解析显式标志 --name/-n
+    const nameIdx = allArgs.indexOf('--name')
+    const shortIdx = allArgs.indexOf('-n')
+    if (nameIdx !== -1 && nameIdx + 1 < allArgs.length) {
+      migrationName = allArgs[nameIdx + 1]
+    } else if (shortIdx !== -1 && shortIdx + 1 < allArgs.length) {
+      migrationName = allArgs[shortIdx + 1]
+    }
+
+    if (!migrationName) {
+      logger.error('开发环境执行 migrate 时必须通过 --name 或 -n 指定迁移名称（禁止位置参数）')
+      logger.info('原因: 缺少迁移名会进入 Prisma 的交互式输入流程，脚本将被阻塞。')
+      logger.info(`正确示例: ${cli.invocation} db migrate --dev --name init-user-table`)
+      logger.info(`如仅需应用已有迁移，请使用 ${cli.invocation} db deploy --dev。`)
+      logger.info(`提示: 执行 ${cli.invocation} help db 查看完整用法与更多示例。`)
+      process.exitCode = 1
+      return
+    }
+
+    const escaped = String(migrationName).replace(/(["`\\$])/g, '\\$1')
+    // 将参数传递给 Nx 下游 prisma：需要通过 -- 分割
+    command = `${command} -- --name "${escaped}"`
+    logger.info(`使用迁移名: ${migrationName}`)
+  }
+
+  // 对以下数据库操作固定禁用 Nx 缓存，避免命中缓存导致未实际执行：generate/migrate/deploy/reset/seed
+  const disableCacheActions = new Set(['generate', 'migrate', 'deploy', 'reset', 'seed'])
+  const extraEnv = disableCacheActions.has(action) ? { NX_CACHE: 'false' } : {}
+  if (disableCacheActions.has(action)) {
+    logger.info('为数据库操作禁用 Nx 缓存: NX_CACHE=false')
+    // 为每个子命令注入 --skip-nx-cache（支持 && || ; 拼接的多命令）
+    command = command
+      .split(/(\s*&&\s*|\s*\|\|\s*|\s*;\s*)/)
+      .map(part => {
+        // 保留分隔符原样
+        if (/^(\s*&&\s*|\s*\|\|\s*|\s*;\s*)$/.test(part)) return part
+        // 跳过空字符串
+        if (!part.trim()) return part
+        // 只对 npx nx 命令注入
+        if (!part.includes('npx nx')) return part
+        // 在 -- 之前插入，或追加到末尾
+        if (part.includes(' -- ')) {
+          return part.replace(' -- ', ' --skip-nx-cache -- ')
+        }
+        return `${part} --skip-nx-cache`
+      })
+      .join('')
+  }
+
+  if (action === 'reset' && envKey !== 'production') {
+    extraEnv.PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION = 'yes'
+    logger.info('非生产环境重置数据库，已自动确认危险操作: PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION=yes')
+  }
+
+  await cli.executeCommand(
+    { ...config, command, env: { ...(config.env || {}), ...extraEnv } },
+    cli.createExecutionFlags(environment),
+  )
+}
+
+export async function handleDatabaseScript(cli, scriptName, envKey, dbConfig) {
+  // 自动去除 .ts 扩展名（如果用户提供了）
+  const cleanScriptName = scriptName.endsWith('.ts') ? scriptName.slice(0, -3) : scriptName
+
+  // 基础路径校验，避免路径遍历
+  if (
+    cleanScriptName.includes('/') ||
+    cleanScriptName.includes('\\') ||
+    cleanScriptName.includes('..')
+  ) {
+    logger.error(`脚本名称不能包含路径分隔符或父目录引用: ${cleanScriptName}`)
+    process.exitCode = 1
+    return
+  }
+
+  const { existsSync } = await import('fs')
+  const { join, resolve, relative } = await import('path')
+  const scriptsRoot = join(process.cwd(), 'apps/backend/prisma/scripts')
+  const scriptPath = resolve(scriptsRoot, `${cleanScriptName}.ts`)
+
+  if (relative(scriptsRoot, scriptPath).startsWith('..')) {
+    logger.error(`脚本路径解析结果已超出允许目录: ${scriptPath}`)
+    process.exitCode = 1
+    return
+  }
+
+  if (!existsSync(scriptPath)) {
+    logger.error(`脚本文件不存在: ${scriptPath}`)
+    logger.info('可用的脚本文件位于: apps/backend/prisma/scripts/')
+    process.exitCode = 1
+    return
+  }
+
+  const environment = envKey
+  logger.step(`执行数据库脚本: ${cleanScriptName} (${environment})`)
+  logger.info(`脚本路径: ${scriptPath}`)
+
+  // 处理嵌套配置
+  let config = dbConfig
+  if (typeof config === 'object' && !config.command) {
+    if (config[envKey]) config = config[envKey]
+    else config = null
+  }
+
+  if (!config) {
+    logger.error(`数据库脚本 ${scriptName} 未提供 ${cli.getEnvironmentFlagExample(envKey) || envKey} 环境配置`)
+    process.exitCode = 1
+    return
+  }
+
+  // 危险操作确认
+  if (config.dangerous && envKey === 'production') {
+    const confirmed = await confirmManager.confirmDatabaseOperation(
+      `script: ${cleanScriptName}`,
+      envManager.getEnvironmentDescription(environment),
+      cli.flags.Y,
+    )
+
+    if (!confirmed) {
+      logger.info('操作已取消')
+      return
+    }
+  }
+
+  // 替换命令中的脚本名称占位符
+  let command = config.command.replace('{SCRIPT_NAME}', cleanScriptName)
+
+  // 获取 -- 后面的 passthrough 参数并追加到命令
+  const passthroughArgs = getPassthroughArgs(cli.args)
+  if (passthroughArgs.length > 0) {
+    const escapedArgs = passthroughArgs.map(arg => {
+      // 对包含空格或特殊字符的参数加引号
+      if (/[\s"'`$\\]/.test(arg)) {
+        return `"${arg.replace(/(["`\\$])/g, '\\$1')}"`
+      }
+      return arg
+    })
+    command = `${command} ${escapedArgs.join(' ')}`
+    logger.info(`传递给脚本的参数: ${passthroughArgs.join(' ')}`)
+  }
+
+  // 为脚本执行禁用 Nx 缓存
+  const extraEnv = { NX_CACHE: 'false' }
+  logger.info('为数据库脚本禁用 Nx 缓存: NX_CACHE=false')
+
+  await cli.executeCommand(
+    { ...config, command, env: { ...(config.env || {}), ...extraEnv } },
+    cli.createExecutionFlags(environment),
+  )
+}

package/lib/cli/commands/deploy.js

@@ -0,0 +1,175 @@
+import { logger } from '../../logger.js'
+import { envManager } from '../../env.js'
+import { validateEnvironment } from '../../validate-env.js'
+
+export function mergeLayeredDeployEnv(layeredEnv, manager, runtimeEnv = process.env) {
+  const vercelCriticalKeys = new Set([
+    'VERCEL_TOKEN',
+    'VERCEL_ORG_ID',
+    'VERCEL_PROJECT_ID_FRONT',
+    'VERCEL_PROJECT_ID_ADMIN',
+    'VERCEL_PROJECT_ID_MERCHANT',
+    'VERCEL_PROJECT_ID_TELEGRAM_BOT',
+  ])
+
+  for (const [key, value] of Object.entries(layeredEnv)) {
+    if (vercelCriticalKeys.has(key)) {
+      const currentValue = runtimeEnv[key]
+      const currentUsable =
+        currentValue !== undefined && currentValue !== null && !manager.isPlaceholderEnvValue(currentValue)
+      const incomingIsPlaceholder = manager.isPlaceholderEnvValue(value)
+
+      // 保留外部显式注入的真实凭据，避免被 .env.<env> 的占位符回退污染。
+      if (currentUsable && incomingIsPlaceholder) continue
+
+      runtimeEnv[key] = value
+      continue
+    }
+
+    const currentValue = runtimeEnv[key]
+    if (!currentValue || manager.isPlaceholderEnvValue(currentValue)) {
+      runtimeEnv[key] = value
+    }
+  }
+}
+
+export function parseTelegramWebhookFlags(argv = []) {
+  const args = Array.isArray(argv) ? argv : []
+
+  const idx = args.indexOf('--webhook-path')
+  const webhookPath = idx !== -1 && idx + 1 < args.length ? args[idx + 1] : undefined
+
+  const dryRun = args.includes('--webhook-dry-run') ? true : undefined
+
+  // 默认值由下游决定（当前为默认严格），这里仅处理显式覆盖
+  const strict = args.includes('--strict-webhook')
+    ? true
+    : args.includes('--no-strict-webhook')
+      ? false
+      : undefined
+
+  return {
+    webhookPath,
+    dryRun,
+    strict,
+  }
+}
+
+export async function handleDeploy(cli, args) {
+  const target = args[0]
+  const deployTargets = Object.keys(cli.commands.deploy || {})
+  if (!target) {
+    logger.error(
+      deployTargets.length > 0
+        ? `请指定部署目标: ${deployTargets.join(', ')}`
+        : '请指定部署目标',
+    )
+    logger.info(`用法: ${cli.invocation} deploy <target> [环境标志]`)
+    logger.info(`示例: ${cli.invocation} deploy front --staging`)
+    process.exitCode = 1
+    return
+  }
+
+  const normalizedTarget = String(target).toLowerCase()
+  if (!cli.commands.deploy?.[normalizedTarget]) {
+    logger.error(`未找到部署目标: ${target}`)
+    if (deployTargets.length > 0) {
+      logger.info(`可用目标: ${deployTargets.join(', ')}`)
+    }
+    logger.info(`用法: ${cli.invocation} deploy <target> [环境标志]`)
+    process.exitCode = 1
+    return
+  }
+
+  if (cli.flags.test || cli.flags.e2e) {
+    logger.error('deploy 命令仅支持 --dev/--staging/--prod 环境标志')
+    process.exitCode = 1
+    return
+  }
+
+  const selectedEnvs = []
+  if (cli.flags.dev) selectedEnvs.push('development')
+  if (cli.flags.staging) selectedEnvs.push('staging')
+  if (cli.flags.prod) selectedEnvs.push('production')
+
+  if (selectedEnvs.length > 1) {
+    logger.error('deploy 命令不支持同时传入多个环境标志')
+    logger.info('请使用 --dev、--staging 或 --prod 中的一个')
+    process.exitCode = 1
+    return
+  }
+
+  const targetConfig = cli.commands.deploy?.[normalizedTarget]
+  const artifactInternal = targetConfig?.internal
+  const isBackendArtifactDeploy = artifactInternal === 'backend-artifact-deploy'
+  const isGenericArtifactDeploy = artifactInternal === 'artifact-deploy'
+  const isArtifactDeploy = isBackendArtifactDeploy || isGenericArtifactDeploy
+  const environment = selectedEnvs[0] || (isArtifactDeploy ? 'development' : 'staging')
+
+  if (isBackendArtifactDeploy) {
+    const { runBackendArtifactDeploy } = await import('../../backend-artifact-deploy.js')
+    await runBackendArtifactDeploy({
+      cli,
+      target: normalizedTarget,
+      args,
+      environment,
+    })
+    return
+  }
+
+  if (isGenericArtifactDeploy) {
+    const { runArtifactDeploy } = await import('../../artifact-deploy.js')
+    await runArtifactDeploy({
+      cli,
+      target: normalizedTarget,
+      args,
+      environment,
+    })
+    return
+  }
+
+  cli.ensureRepoRoot()
+
+  // 只执行基础环境校验（检查 .env 文件结构），跳过后端环境变量校验
+  // Vercel 部署所需的环境变量由 vercel-deploy.js 自行校验
+  try {
+    validateEnvironment()
+  } catch (error) {
+    logger.error(error.message)
+    process.exitCode = 1
+    return
+  }
+
+  // 加载环境变量层，但不校验后端必需变量
+  const layeredEnv = envManager.collectEnvFromLayers(null, environment)
+  if (envManager.latestEnvWarnings && envManager.latestEnvWarnings.length > 0) {
+    envManager.latestEnvWarnings.forEach(message => {
+      logger.warn(message)
+    })
+  }
+
+  // 默认仅在缺失/占位时覆盖；Vercel 关键变量额外避免“真实值被占位符覆盖”的回退污染。
+  mergeLayeredDeployEnv(layeredEnv, envManager, process.env)
+  envManager.syncEnvironments(environment)
+
+  const { deployToVercel } = await import('../../vercel-deploy.js')
+
+  if (normalizedTarget === 'front') {
+    process.env.FRONT_I18N_PROFILE = cli.flags.BR ? 'br' : 'default'
+  }
+
+  const telegramWebhook = normalizedTarget === 'telegram-bot'
+    ? parseTelegramWebhookFlags(cli.args)
+    : null
+
+  const strictContext = process.env.DX_VERCEL_STRICT_CONTEXT != null
+    ? !['0', 'false', 'no'].includes(String(process.env.DX_VERCEL_STRICT_CONTEXT).toLowerCase())
+    : true
+
+  await deployToVercel(normalizedTarget, {
+    environment,
+    telegramWebhook,
+    strictContext,
+    targetConfig: targetConfig?.vercel,
+  })
+}

package/lib/cli/commands/env.js

@@ -0,0 +1,120 @@
+import { logger } from '../../logger.js'
+import {
+  describeEnvProfiles,
+  executeWithEnvProfile,
+  validateEnvProfile,
+} from '../../env-profile.js'
+import { getPassthroughArgs } from '../args.js'
+import { COMMAND_NOT_HANDLED } from '../command-result.js'
+
+function hasExplicitEnvironment(flags = {}) {
+  return Boolean(flags.dev || flags.staging || flags.prod || flags.test || flags.e2e)
+}
+
+function normalizeDxEnvironmentFlag(flag) {
+  switch (flag) {
+    case '--dev':
+      return 'development'
+    case '--staging':
+      return 'staging'
+    case '--prod':
+      return 'production'
+    case '--test':
+      return 'test'
+    case '--e2e':
+      return 'e2e'
+    default:
+      return null
+  }
+}
+
+function prepareChildCommand(cli, command, args, environment) {
+  if (command !== 'dx') return { command, args }
+
+  const explicit = args
+    .map(normalizeDxEnvironmentFlag)
+    .filter(Boolean)
+  const mismatched = explicit.find(value => value !== environment)
+  if (mismatched) {
+    throw new Error(`env profile 环境为 ${environment}，但内部 dx 命令指定了 ${mismatched}`)
+  }
+  if (explicit.length > 0) return { command, args }
+
+  const separator = args.indexOf('--')
+  const flag = cli.getEnvironmentFlag(environment)
+  if (separator === -1) return { command, args: [...args, flag] }
+  return {
+    command,
+    args: [...args.slice(0, separator), flag, ...args.slice(separator)],
+  }
+}
+
+function requireExplicitEnvironment(cli, action) {
+  if (!hasExplicitEnvironment(cli.flags)) {
+    throw new Error(`dx env ${action} 必须显式指定 --staging 或 --prod（也可使用 --dev）`)
+  }
+  const environment = cli.determineEnvironment()
+  if (environment === 'test' || environment === 'e2e') {
+    throw new Error(`dx env ${action} 不支持 ${environment} profile`)
+  }
+  return environment
+}
+
+export async function handleEnv(cli, args = []) {
+  const [action, profile, ...extras] = args
+
+  if (action === 'status') {
+    if (profile || extras.length > 0) throw new Error('用法: dx env status')
+    const rows = describeEnvProfiles({ projectRoot: cli.projectRoot, configDir: cli.configDir })
+    logger.table(
+      rows.map(row => [
+        row.profile,
+        row.label,
+        row.environment,
+        row.exists ? '存在' : '缺失',
+        row.mode,
+        row.active ? '当前已装配' : '-',
+      ]),
+      ['PROFILE', '名称', '环境', '私有配置', '权限', '状态'],
+    )
+    return
+  }
+
+  if (action !== 'validate' && action !== 'exec') {
+    return COMMAND_NOT_HANDLED
+  }
+  if (!profile || extras.length > 0) throw new Error(`dx env ${action} 需要且仅需要一个 profile 名称`)
+  const environment = requireExplicitEnvironment(cli, action)
+
+  if (action === 'validate') {
+    const result = validateEnvProfile({
+      projectRoot: cli.projectRoot,
+      configDir: cli.configDir,
+      profile,
+      environment,
+    })
+    logger.success(
+      `env profile 校验通过: ${result.profile}/${result.environment}（${result.keyCount} 个本地键）`,
+    )
+    return
+  }
+
+  const passthrough = getPassthroughArgs(cli.args)
+  if (passthrough.length === 0) throw new Error('dx env exec 必须在 -- 后提供要执行的命令')
+  const prepared = prepareChildCommand(cli, passthrough[0], passthrough.slice(1), environment)
+  logger.command([prepared.command, ...prepared.args].join(' '))
+  const code = await executeWithEnvProfile({
+    projectRoot: cli.projectRoot,
+    configDir: cli.configDir,
+    profile,
+    environment,
+    command: prepared.command,
+    args: prepared.args,
+  })
+  if (code !== 0) {
+    process.exitCode = code
+    logger.error(`env profile 命令执行失败，退出码 ${code}；临时 env 已清理`)
+    return
+  }
+  logger.success('env profile 命令执行成功，临时 env 已清理')
+}

package/lib/cli/commands/export.js

@@ -0,0 +1,39 @@
+import { logger } from '../../logger.js'
+
+export async function handleExport(cli, args) {
+  const target = args[0]
+  if (!target) {
+    logger.error('请指定导出目标')
+    logger.info(`用法: ${cli.invocation} export <target> [环境标志]`)
+    process.exitCode = 1
+    return
+  }
+
+  const exportConfig = cli.commands.export?.[target]
+  if (!exportConfig) {
+    const targets = Object.keys(cli.commands.export || {})
+    logger.error(`未找到导出目标: ${target}`)
+    if (targets.length > 0) {
+      logger.info(`可用目标: ${targets.join(', ')}`)
+    }
+    process.exitCode = 1
+    return
+  }
+
+  const environment = cli.determineEnvironment()
+  const envKey = cli.normalizeEnvKey(environment)
+  let config = exportConfig
+  if (typeof config === 'object' && !config.command) {
+    if (config[envKey]) config = config[envKey]
+    else config = null
+  }
+
+  if (!config) {
+    logger.error(`导出目标 ${target} 未提供 ${cli.getEnvironmentFlagExample(envKey) || envKey} 环境配置`)
+    process.exitCode = 1
+    return
+  }
+
+  logger.step(`导出 ${target} (${environment})`)
+  await cli.executeCommand(config)
+}

package/lib/cli/commands/package.js

@@ -0,0 +1,22 @@
+import { logger } from '../../logger.js'
+
+export async function handlePackage(cli, args) {
+  const target = args[0] || 'backend'
+  if (target !== 'backend') {
+    logger.error(`暂不支持打包目标: ${target}`)
+    logger.info(`当前仅支持 ${cli.invocation} package backend`)
+    process.exitCode = 1
+    return
+  }
+
+  cli.ensureRepoRoot()
+
+  const environment = cli.determineEnvironment()
+  const passthroughFlags = cli.args.filter(token =>
+    ['--skip-build', '--keep-workdir'].includes(token),
+  )
+
+  logger.step(`打包 ${target} (${environment})`)
+  const { runBackendPackage } = await import('../../backend-package.js')
+  await runBackendPackage([`--env=${environment}`, ...passthroughFlags])
+}

package/lib/cli/commands/release.js

@@ -0,0 +1,55 @@
+import { existsSync, readFileSync, writeFileSync } from 'node:fs'
+import { join } from 'node:path'
+import { logger } from '../../logger.js'
+import { COMMAND_NOT_HANDLED } from '../command-result.js'
+
+export async function handleRelease(cli, args = []) {
+  const action = args[0]
+  const version = args[1]
+
+  if (action !== 'version') {
+    return COMMAND_NOT_HANDLED
+  }
+
+  if (!version) {
+    logger.error(`请提供要发布的版本号，例如: ${cli.invocation} release version 1.2.3`)
+    process.exitCode = 1
+    return
+  }
+
+  cli.ensureRepoRoot()
+
+  const semverPattern = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z-.]+)?(?:\+[0-9A-Za-z-.]+)?$/
+  if (!semverPattern.test(version)) {
+    logger.warn(`版本号 ${version} 不符合常见语义化版本格式，仍将继续更新`)
+  }
+
+  const packageFiles = [
+    'apps/backend/package.json',
+    'apps/front/package.json',
+    'apps/admin-front/package.json',
+  ]
+
+  logger.step(`统一更新版本号 -> ${version}`)
+
+  for (const relativePath of packageFiles) {
+    const fullPath = join(process.cwd(), relativePath)
+    if (!existsSync(fullPath)) {
+      logger.warn(`跳过，未找到文件: ${relativePath}`)
+      continue
+    }
+
+    try {
+      const raw = readFileSync(fullPath, 'utf8')
+      const pkg = JSON.parse(raw)
+      const previous = pkg.version || '0.0.0'
+      pkg.version = version
+      writeFileSync(fullPath, `${JSON.stringify(pkg, null, 2)}\n`, 'utf8')
+      logger.info(`更新 ${relativePath}: ${previous} -> ${version}`)
+    } catch (error) {
+      logger.error(`更新 ${relativePath} 失败: ${error?.message || String(error)}`)
+    }
+  }
+
+  logger.success(`版本号已同步为 ${version}`)
+}