@ranger1/dx 0.1.96 → 0.1.98

package/README.md

@@ -4,6 +4,38 @@
 
 本工具通过项目内的 `dx/config/*` 配置文件来驱动命令执行：你可以把它理解成「带环境变量分层 + 校验 + 命令编排能力的脚本系统」。
 
+## 当前规范
+
+当前版本的 `dx` 已收敛到 strict 配置规范。
+
+这意味着：
+
+- 配置写错时直接报错，不再自动兼容旧写法
+- `help` 输出由 `dx/config/commands.json` 动态生成，不再依赖代码中的大段硬编码文案
+- 命令配置中的环境分支必须使用完整环境键
+
+当前推荐且受支持的环境键：
+
+- `development`
+- `staging`
+- `production`
+- `test`
+- `e2e`
+
+当前推荐且受支持的 CLI 环境标志：
+
+- `--dev`
+- `--staging`
+- `--prod`
+- `--test`
+- `--e2e`
+
+不再建议写法：
+
+- `dev` / `prod` 作为配置节点名
+- `--development` / `--production` / `--stage`
+- 任何旧配置回退、旧命令别名或自动输入修正
+
 ## 安装
 
 必须全局安装，并始终使用最新版本：
@@ -70,12 +102,14 @@ DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
 
 ### 1) dx/config/commands.json
 
-这是核心文件，定义了 dx 各命令要执行的 shell 命令，支持：
+这是核心文件，定义了 dx 各命令要执行的 shell 命令，也承载帮助信息配置。
+
+它支持：
 
 - 单命令：`{ "command": "..." }`
-- 并发：`{ "concurrent": true, "commands": ["build.front.dev", "build.admin.dev"] }`
-- 串行：`{ "sequential": true, "commands": ["build.backend.prod", "build.sdk"] }`
-- 环境分支：如 `build.backend.dev` / `build.backend.prod`（dx 会根据 `--dev/--prod/--staging/...` 选择）
+- 并发：`{ "concurrent": true, "commands": ["build.front.development", "build.admin.development"] }`
+- 串行：`{ "sequential": true, "commands": ["build.backend.production", "build.sdk"] }`
+- 环境分支：如 `build.backend.development` / `build.backend.production`（dx 会根据 `--dev/--prod/--staging/...` 选择）
 - dotenv 包裹：配置里带 `"app": "backend"` 时，dx 会按 `env-layers.json` 拼出 dotenv 层并用 `pnpm exec dotenv ... -- <command>` 执行
 
 常见字段（单命令配置）：
@@ -95,9 +129,39 @@ DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
 命令路径引用（并发/串行的 commands 数组）使用点号字符串，例如：
 
 ```json
-{ "concurrent": true, "commands": ["build.shared", "build.front.dev"] }
+{ "concurrent": true, "commands": ["build.shared", "build.front.development"] }
+```
+
+帮助配置示例：
+
+```json
+{
+  "help": {
+    "summary": "统一开发环境管理工具",
+    "globalOptions": [
+      { "flags": ["--dev"], "description": "使用 development 环境" },
+      { "flags": ["--prod"], "description": "使用 production 环境" }
+    ],
+    "commands": {
+      "start": {
+        "summary": "启动/桥接服务",
+        "notes": ["未指定 service 时默认使用开发套件，仅允许 --dev"],
+        "examples": [
+          { "command": "dx start backend --dev", "description": "启动后端开发服务" }
+        ]
+      }
+    }
+  }
+}
 ```
 
+约束：
+
+- 命令级帮助推荐放在 `help.commands.<command>`
+- target 级帮助推荐放在 `help.targets.<command>.<target>`
+- 帮助示例必须与真实命令树一致，不能写配置里不存在的 target
+- 运行时会校验 help 配置结构；坏配置会直接报错
+
 ### 2) dx/config/env-layers.json
 
 用于定义不同环境下加载哪些 `.env.*` 文件（顺序 = 覆盖优先级）。格式：
@@ -202,6 +266,15 @@ dx test e2e backend apps/backend/e2e/auth
 dx test e2e quantify apps/quantify/e2e/health/health.e2e-spec.ts
 ```
 
+关于 `help`：
+
+- `dx --help`
+- `dx help <command>`
+
+现在都优先从 `commands.json` 的 `help` 区域动态生成。
+
+如果某个命令还没有补充足够的 `help` 元数据，输出会回退到配置结构推导出的最小帮助，而不是旧的手写兼容文案。
+
 命令约束摘要：
 
 - 对声明了 `requiresPath: true` 的 E2E target，`dx test e2e <target>` 必须提供文件或目录路径，禁止无路径或 `all` 全量执行

package/lib/cli/commands/core.js

@@ -6,13 +6,8 @@ import { execManager } from '../../exec.js'
 import { showHelp, showCommandHelp } from '../help.js'
 
 export function handleHelp(cli, args = []) {
-  void cli
-  if (args[0]) showCommandHelp(args[0])
-  else showHelp()
-}
-
-export function handleDev(cli, args = []) {
-  return cli.reportDevCommandRemoved(args)
+  if (args[0]) showCommandHelp(args[0], cli)
+  else showHelp(cli)
 }
 
 export async function handleBuild(cli, args) {
@@ -24,12 +19,6 @@ export async function handleBuild(cli, args) {
 
   const buildConfig = cli.commands.build[target]
   if (!buildConfig) {
-    // 兼容用户误输入或快捷命令，把 "all./scripts/dx" 这类粘连错误拆分
-    const fixed = String(target).split(/\s|\t|\r|\n|\u00A0|\.|\//)[0]
-    if (fixed && cli.commands.build[fixed]) {
-      logger.warn(`自动修正构建目标: ${target} -> ${fixed}`)
-      return await handleBuild(cli, [fixed])
-    }
     logger.error(`未找到构建目标: ${target}`)
     process.exitCode = 1
     return
@@ -40,14 +29,12 @@ export async function handleBuild(cli, args) {
   // 处理嵌套配置
   let config = buildConfig
   if (typeof config === 'object' && !config.command) {
-    const supportsCurrentEnv = Boolean(
-      config[envKey] || (envKey === 'staging' && config.prod),
-    )
+    const supportsCurrentEnv = Boolean(config[envKey])
     if (explicitEnv && !supportsCurrentEnv) {
       const envFlag = cli.getEnvironmentFlagExample(envKey) || `--${envKey}`
       logger.error(`构建目标 ${target} 不支持 ${envFlag} 环境`)
       logger.info('显式传入环境标志时，必须是该 target 实际支持的环境。')
-      const available = ['dev', 'staging', 'prod', 'test', 'e2e']
+      const available = ['development', 'staging', 'production', 'test', 'e2e']
         .filter(key => key in config)
         .map(key => cli.getEnvironmentFlagExample(key) || `--${key}`)
       if (available.length > 0) {
@@ -61,10 +48,15 @@ export async function handleBuild(cli, args) {
       return
     }
 
-    // 如果是嵌套配置，尝试获取环境特定的配置（兼容 dev/prod 与 development/production 命名）
+    // 严格按显式环境选择配置，不做环境回退
     if (config[envKey]) config = config[envKey]
-    else if (envKey === 'staging' && config.prod) config = config.prod
-    else config = config.dev || config
+    else config = null
+  }
+
+  if (!config) {
+    logger.error(`构建目标 ${target} 未提供 ${cli.getEnvironmentFlagExample(envKey) || envKey} 环境配置`)
+    process.exitCode = 1
+    return
   }
 
   if (config.concurrent) {

package/lib/cli/commands/db.js

@@ -22,7 +22,7 @@ export async function handleDatabase(cli, args) {
   const envKey = cli.normalizeEnvKey(environment)
 
   // 创建迁移只允许在开发环境进行，避免 AI/用户在非开发环境误执行
-  if (action === 'migrate' && envKey && envKey !== 'dev') {
+  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>` 创建新迁移。')
@@ -49,10 +49,15 @@ export async function handleDatabase(cli, args) {
   // 处理嵌套配置
   let config = dbConfig
   if (typeof config === 'object' && !config.command) {
-    // 如果是嵌套配置，尝试获取环境特定的配置（兼容 dev/prod 与 development/production 命名）
+    // 严格按显式环境选择配置，不做环境回退
     if (config[envKey]) config = config[envKey]
-    else if (envKey === 'staging' && config.prod) config = config.prod
-    else config = config.dev || config
+    else config = null
+  }
+
+  if (!config) {
+    logger.error(`数据库操作 ${action} 未提供 ${cli.getEnvironmentFlagExample(envKey) || envKey} 环境配置`)
+    process.exitCode = 1
+    return
   }
 
   // 危险操作确认
@@ -71,7 +76,7 @@ export async function handleDatabase(cli, args) {
 
   // 支持为 migrate 传入迁移名：--name/-n
   let command = config.command
-  if (action === 'migrate' && envKey === 'dev') {
+  if (action === 'migrate' && envKey === 'development') {
     const allArgs = cli.args
     let migrationName = null
     // 优先解析显式标志 --name/-n
@@ -123,24 +128,14 @@ export async function handleDatabase(cli, args) {
       .join('')
   }
 
-  if (action === 'reset' && envKey !== 'prod') {
+  if (action === 'reset' && envKey !== 'production') {
     extraEnv.PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION = 'yes'
     logger.info('非生产环境重置数据库，已自动确认危险操作: PRISMA_USER_CONSENT_FOR_DANGEROUS_AI_ACTION=yes')
   }
 
-  const execFlags = { ...cli.flags }
-  ;['dev', 'development', 'prod', 'production', 'test', 'e2e', 'staging', 'stage'].forEach(
-    key => delete execFlags[key],
-  )
-  if (envKey === 'prod') execFlags.prod = true
-  else if (envKey === 'dev') execFlags.dev = true
-  else if (envKey === 'test') execFlags.test = true
-  else if (envKey === 'e2e') execFlags.e2e = true
-  else if (envKey === 'staging') execFlags.staging = true
-
   await cli.executeCommand(
     { ...config, command, env: { ...(config.env || {}), ...extraEnv } },
-    execFlags,
+    cli.createExecutionFlags(environment),
   )
 }
 
@@ -177,7 +172,7 @@ export async function handleDatabaseScript(cli, scriptName, envKey, dbConfig) {
     return
   }
 
-  const environment = envKey === 'dev' ? 'development' : envKey === 'prod' ? 'production' : envKey
+  const environment = envKey
   logger.step(`执行数据库脚本: ${cleanScriptName} (${environment})`)
   logger.info(`脚本路径: ${scriptPath}`)
 
@@ -185,12 +180,17 @@ export async function handleDatabaseScript(cli, scriptName, envKey, dbConfig) {
   let config = dbConfig
   if (typeof config === 'object' && !config.command) {
     if (config[envKey]) config = config[envKey]
-    else if (envKey === 'staging' && config.prod) config = config.prod
-    else config = config.dev || config
+    else config = null
+  }
+
+  if (!config) {
+    logger.error(`数据库脚本 ${scriptName} 未提供 ${cli.getEnvironmentFlagExample(envKey) || envKey} 环境配置`)
+    process.exitCode = 1
+    return
   }
 
   // 危险操作确认
-  if (config.dangerous && envKey === 'prod') {
+  if (config.dangerous && envKey === 'production') {
     const confirmed = await confirmManager.confirmDatabaseOperation(
       `script: ${cleanScriptName}`,
       envManager.getEnvironmentDescription(environment),
@@ -224,18 +224,8 @@ export async function handleDatabaseScript(cli, scriptName, envKey, dbConfig) {
   const extraEnv = { NX_CACHE: 'false' }
   logger.info('为数据库脚本禁用 Nx 缓存: NX_CACHE=false')
 
-  const execFlags = { ...cli.flags }
-  ;['dev', 'development', 'prod', 'production', 'test', 'e2e', 'staging', 'stage'].forEach(
-    key => delete execFlags[key],
-  )
-  if (envKey === 'prod') execFlags.prod = true
-  else if (envKey === 'dev') execFlags.dev = true
-  else if (envKey === 'test') execFlags.test = true
-  else if (envKey === 'e2e') execFlags.e2e = true
-  else if (envKey === 'staging') execFlags.staging = true
-
   await cli.executeCommand(
     { ...config, command, env: { ...(config.env || {}), ...extraEnv } },
-    execFlags,
+    cli.createExecutionFlags(environment),
   )
 }

package/lib/cli/commands/export.js

@@ -25,8 +25,13 @@ export async function handleExport(cli, args) {
   let config = exportConfig
   if (typeof config === 'object' && !config.command) {
     if (config[envKey]) config = config[envKey]
-    else if (envKey === 'staging' && config.prod) config = config.prod
-    else config = config.dev || config
+    else config = null
+  }
+
+  if (!config) {
+    logger.error(`导出目标 ${target} 未提供 ${cli.getEnvironmentFlagExample(envKey) || envKey} 环境配置`)
+    process.exitCode = 1
+    return
   }
 
   logger.step(`导出 ${target} (${environment})`)

package/lib/cli/commands/start.js

@@ -1,24 +1,11 @@
 import { logger } from '../../logger.js'
 
 export async function handleStart(cli, args) {
-  const service = args[0] || 'dev'
+  const service = args[0] || 'development'
 
   const environment = cli.determineEnvironment()
   const envKey = cli.normalizeEnvKey(environment)
-
-  let rawConfig = cli.commands.start[service]
-  let configNamespace = 'start'
-
-  if (!rawConfig && cli.commands.dev?.[service]) {
-    if (envKey !== 'dev') {
-      logger.error(`目标 ${service} 仅支持开发环境启动，请使用 --dev 或省略环境标志。`)
-      process.exitCode = 1
-      return
-    }
-    rawConfig = cli.commands.dev[service]
-    configNamespace = 'dev'
-    logger.info(`检测到 legacy "dev" 配置，已自动回退至 ${service} 开发脚本。`)
-  }
+  const rawConfig = cli.commands.start[service]
 
   if (!rawConfig) {
     logger.error(`未找到启动配置: ${service}`)
@@ -27,13 +14,17 @@ export async function handleStart(cli, args) {
   }
 
   let startConfig = rawConfig
-  if (configNamespace === 'start' && rawConfig && typeof rawConfig === 'object') {
-    if (rawConfig[envKey]) startConfig = rawConfig[envKey]
-    else if (envKey === 'staging' && rawConfig?.prod) startConfig = rawConfig.prod
+  const isRunnableConfig =
+    rawConfig &&
+    typeof rawConfig === 'object' &&
+    (rawConfig.command || rawConfig.internal || rawConfig.concurrent || rawConfig.sequential)
+
+  if (!isRunnableConfig && rawConfig && typeof rawConfig === 'object') {
+    startConfig = rawConfig[envKey] || null
   }
 
   if (!startConfig) {
-    logger.error(`启动目标 ${service} 未提供 ${environment} 环境配置。`)
+    logger.error(`启动目标 ${service} 未提供 ${cli.getEnvironmentFlagExample(envKey) || envKey} 环境配置。`)
     process.exitCode = 1
     return
   }
@@ -41,7 +32,7 @@ export async function handleStart(cli, args) {
   logger.step(`启动 ${service} 服务 (${environment})`)
 
   if (startConfig.concurrent && Array.isArray(startConfig.commands)) {
-    await cli.handleConcurrentCommands(startConfig.commands, configNamespace, envKey)
+    await cli.handleConcurrentCommands(startConfig.commands, 'start', envKey)
     return
   }
 
@@ -52,26 +43,16 @@ export async function handleStart(cli, args) {
 
   const ports = cli.collectStartPorts(service, startConfig, envKey)
 
-  if (envKey === 'dev' && ports.length > 0) {
+  if (envKey === 'development' && ports.length > 0) {
     logger.info(`开发环境自动清理端口: ${ports.join(', ')}`)
   }
 
   const configToExecute = {
     ...startConfig,
     ...(ports.length > 0 ? { ports } : {}),
-    ...(envKey === 'dev' ? { forcePortCleanup: true } : {}),
+    ...(envKey === 'development' ? { forcePortCleanup: true } : {}),
   }
 
   // 为执行阶段构造环境标志，确保 dotenv 选择正确层
-  const execFlags = { ...cli.flags }
-  ;['dev', 'development', 'prod', 'production', 'test', 'e2e', 'staging', 'stage'].forEach(
-    key => delete execFlags[key]
-  )
-  if (envKey === 'prod') execFlags.prod = true
-  else if (envKey === 'dev') execFlags.dev = true
-  else if (envKey === 'test') execFlags.test = true
-  else if (envKey === 'e2e') execFlags.e2e = true
-  else if (envKey === 'staging') execFlags.staging = true
-
-  await cli.executeCommand(configToExecute, execFlags)
+  await cli.executeCommand(configToExecute, cli.createExecutionFlags(environment))
 }

package/lib/cli/commands/worktree.js

@@ -64,8 +64,6 @@ export async function handleWorktree(cli, args) {
       break
 
     case 'del':
-    case 'delete':
-    case 'rm':
       // 互斥校验：--all 不能与 issue 编号同时使用
       // args[0] 是 action，args[1] 开始才是 issue 编号
       if (cli.flags.all && args.length > 1) {
@@ -131,12 +129,10 @@ export async function handleWorktree(cli, args) {
       break
 
     case 'list':
-    case 'ls':
       await worktreeManager.list()
       break
 
     case 'clean':
-    case 'prune':
       await worktreeManager.clean()
       break