@ranger1/dx 0.1.78 → 0.1.79

package/README.md

@@ -188,7 +188,7 @@ dx 的命令由 `dx/config/commands.json` 驱动，并且内置了一些 interna
 
 ```bash
 dx start backend --dev
-dx start all
+dx start all --dev
 dx build backend --prod
 dx build sdk --dev
 dx db generate
@@ -196,9 +196,17 @@ dx db migrate --dev --name init
 dx db deploy --prod -Y
 dx deploy front --staging
 dx lint
-dx test e2e backend
+dx test e2e backend apps/backend/e2e/auth
 ```
 
+命令约束摘要：
+
+- `dx test e2e backend` 必须提供文件或目录路径，禁止无路径全量执行
+- `dx db migrate` 仅允许在 `--dev` 环境创建迁移；非开发环境请使用 `dx db deploy`
+- `dx start` 未指定服务时默认是开发套件，仅允许 `--dev`
+- `dx start` 下的单层目标（如 `stagewise-front`）默认仅支持 `--dev`
+- `dx build` 显式传入环境标志时，必须是该 target 实际支持的环境
+
 ### `dx start stack` 配置详解（PM2 交互式服务栈）
 
 从 `0.1.78` 起，`dx start stack` 推荐完全由 `dx/config/commands.json` 配置驱动，不再依赖硬编码服务列表。

package/lib/cli/commands/core.js

@@ -17,6 +17,8 @@ export async function handleBuild(cli, args) {
   const target = args[0] || 'all'
   const environment = cli.determineEnvironment()
   const envKey = cli.normalizeEnvKey(environment)
+  const explicitEnv =
+    Boolean(cli.flags.dev || cli.flags.prod || cli.flags.staging || cli.flags.test || cli.flags.e2e)
 
   const buildConfig = cli.commands.build[target]
   if (!buildConfig) {
@@ -36,6 +38,27 @@ export async function handleBuild(cli, args) {
   // 处理嵌套配置
   let config = buildConfig
   if (typeof config === 'object' && !config.command) {
+    const supportsCurrentEnv = Boolean(
+      config[envKey] || (envKey === 'staging' && config.prod),
+    )
+    if (explicitEnv && !supportsCurrentEnv) {
+      const envFlag = cli.getEnvironmentFlagExample(envKey) || `--${envKey}`
+      logger.error(`构建目标 ${target} 不支持 ${envFlag} 环境`)
+      logger.info('显式传入环境标志时，必须是该 target 实际支持的环境。')
+      const available = ['dev', 'staging', 'prod', 'test', 'e2e']
+        .filter(key => key in config)
+        .map(key => cli.getEnvironmentFlagExample(key) || `--${key}`)
+      if (available.length > 0) {
+        logger.info(`支持的环境: ${available.join(', ')}`)
+        logger.info(`示例: ${cli.invocation} build ${target} ${available[0]}`)
+        if (available.length > 1) {
+          logger.info(`示例: ${cli.invocation} build ${target} ${available[1]}`)
+        }
+      }
+      process.exitCode = 1
+      return
+    }
+
     // 如果是嵌套配置，尝试获取环境特定的配置（兼容 dev/prod 与 development/production 命名）
     if (config[envKey]) config = config[envKey]
     else if (envKey === 'staging' && config.prod) config = config.prod
@@ -81,7 +104,7 @@ export async function handleTest(cli, args) {
 
   // 如果提供了测试文件路径，使用专门的单文件测试配置
   if (testPath && type === 'e2e' && target === 'backend') {
-    let command = `pnpm --filter ./apps/backend run test:e2e:file ${testPath}`
+    let command = `npx nx test:e2e backend -- ${testPath}`
 
     // 如果指定了测试用例名称，添加 -t 参数
     if (testNamePattern) {

package/lib/cli/commands/db.js

@@ -21,12 +21,14 @@ export async function handleDatabase(cli, args) {
   const environment = cli.determineEnvironment()
   const envKey = cli.normalizeEnvKey(environment)
 
-  // 兼容旧用法：非 dev 环境使用 migrate 时给出明确提示，推荐改用 deploy
+  // 创建迁移只允许在开发环境进行，避免 AI/用户在非开发环境误执行
   if (action === 'migrate' && envKey && envKey !== 'dev') {
     const envFlag = cli.getEnvironmentFlagExample(envKey) || `--${envKey}`
-    logger.warn(`检测到在非开发环境执行 migrate: ${environment || envKey}`)
-    logger.info('建议仅在开发环境使用 `dx db migrate --dev --name <migration-name>` 创建迁移。')
-    logger.info(`如需在当前环境应用已有迁移，请使用: ${cli.invocation} db deploy ${envFlag}`)
+    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 子命令

package/lib/cli/dx-cli.js

@@ -456,6 +456,7 @@ class DxCli {
         ensureMax(1)
         break
       case 'build': {
+        this.validateBuildPositionals(positionalArgs)
         if (positionalArgs.length >= 2 && this.isEnvironmentToken(positionalArgs[1])) {
           this.reportEnvironmentFlagRequired(command, positionalArgs[1], positionalArgs)
         }
@@ -497,6 +498,7 @@ class DxCli {
         break
       }
       case 'test':
+        this.validateTestPositionals(positionalArgs)
         ensureMax(3)
         break
       case 'worktree': {
@@ -516,6 +518,7 @@ class DxCli {
         break
       }
       case 'start': {
+        this.validateStartPositionals(positionalArgs)
         const extras = positionalArgs.slice(1)
         const envToken = extras.find(token => this.isEnvironmentToken(token))
         if (envToken) {
@@ -604,6 +607,77 @@ class DxCli {
     return parts.concat(rest).join(' ')
   }
 
+  validateTestPositionals(positionalArgs) {
+    if (positionalArgs.length === 0) return
+
+    const [type = 'e2e', target = 'all', testPath] = positionalArgs
+
+    if (type === 'e2e' && target === 'backend' && !testPath) {
+      logger.error('dx test e2e backend 必须提供测试文件或目录路径')
+      logger.info(`示例: ${this.invocation} test e2e backend apps/backend/e2e/auth`)
+      logger.info(
+        `示例: ${this.invocation} test e2e backend apps/backend/e2e/auth/auth.login.e2e-spec.ts -t "should login"`,
+      )
+      logger.info('说明: 为避免误触发全量 E2E，backend E2E 仅允许按文件或目录增量执行')
+      process.exit(1)
+    }
+  }
+
+  validateStartPositionals(positionalArgs) {
+    const service = positionalArgs[0] || 'dev'
+    const environment = this.determineEnvironment()
+    const envKey = this.normalizeEnvKey(environment)
+
+    if (service === 'dev' && envKey !== 'dev') {
+      logger.error('dx start 在未指定服务时仅允许使用开发环境')
+      logger.info(`示例: ${this.invocation} start all --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 !== 'dev') {
+      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] || (envKey === 'staging' && buildConfig.prod))
+    if (supportsCurrentEnv) return
+
+    const envFlag = this.getEnvironmentFlagExample(envKey) || `--${envKey}`
+    logger.error(`构建目标 ${target} 不支持 ${envFlag} 环境`)
+    logger.info('显式传入环境标志时，必须是该 target 实际支持的环境。')
+    const available = ['dev', 'staging', 'prod', '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)
+  }
+
   reportDevCommandRemoved(args) {
     const target = args?.[0]
     logger.error('`dx dev` 命令已移除，统一使用 `dx start`。')

package/lib/cli/help.js

@@ -44,8 +44,9 @@ export function showHelp() {
     '  test [type] [target] [path] [-t pattern]  运行测试',
     '    type: e2e, unit (默认: e2e)',
     '    target: backend, all (默认: all)',
-    '    path: 测试文件路径 (可选，仅支持e2e backend)',
-    '    -t pattern: 指定测试用例名称模式 (可选，需要和path一起使用)',
+    '    path: 测试文件或目录路径 (必填，仅支持 e2e backend)',
+    '    -t pattern: 指定测试用例名称模式 (可选，需要和 path 一起使用)',
+    '    说明: backend E2E 禁止无路径全量执行',
     '',
     '  worktree [action] [num...] Git Worktree管理',
     '    action: make, del, list, clean',
@@ -90,9 +91,9 @@ export function showHelp() {
     '  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 test e2e backend apps/backend/e2e/auth     # 按目录运行后端 E2E',
+    '  dx test e2e backend apps/backend/e2e/activity/activity.admin.e2e-spec.ts  # 运行单个E2E测试文件',
+    '  dx test e2e backend apps/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',
@@ -131,6 +132,9 @@ build 命令用法:
   target: backend, front, admin, shared, mobile, sdk, all, affected
   环境标志: --dev、--staging、--prod、--test、--e2e（默认 --dev）
 
+限制说明:
+  显式传入环境标志时，必须是该 target 实际支持的环境；不支持时会直接报错
+
 常见示例:
   dx build backend --staging    # 使用 staging 环境变量构建后端 (prod 流程)
   dx build front --prod         # 强制以生产配置构建前端
@@ -159,6 +163,8 @@ db 命令用法:
 
 帮助提示:
   - 未提供迁移名称时命令会直接报错退出，避免 Prisma 进入交互式输入
+  - 仅允许在开发环境使用 \`dx db migrate --dev --name <migration-name>\` 创建迁移
+  - 非开发环境请使用 dx db deploy
   - 使用模式示例: dx db migrate --dev --name init-user-table
   - 如需仅执行已有迁移（本地/CI/生产），请使用 dx db deploy（无需 --name）
 
@@ -220,11 +226,38 @@ start 命令用法:
 环境说明:
   支持 --dev、--staging、--prod、--test、--e2e。--staging 会注入 .env.staging*. 层并复用 prod 启动流程
 
+限制说明:
+  未指定 service 时默认使用 dev 套件，仅允许 --dev
+  stagewise 等单层 start 目标默认视为开发态目标，仅允许 --dev
+
 常见示例:
   dx start backend --staging    # 使用 staging 配置启动后端 (生产模式流程)
   dx start stagewise-front      # Stagewise 桥接用户前端，端口 3001 -> 3002
 
 提示: service 省略时默认启动 dev 套件，可结合 --dev/--staging/--prod 标志使用。
+`)
+      return
+
+    case 'test':
+      console.log(`
+test 命令用法:
+  dx test [type] [target] [path] [-t pattern]
+
+参数说明:
+  type: e2e, unit (默认: e2e)
+  target: backend, all (默认: all)
+  path: 仅 e2e backend 支持，且必须提供文件或目录路径
+  -t pattern: 指定测试用例名称模式，需要和 path 一起使用
+
+限制说明:
+  backend E2E 禁止无路径全量执行，缺少 path 时命令会直接报错退出。
+
+常见示例:
+  dx test e2e backend apps/backend/e2e/auth
+  dx test e2e backend apps/backend/e2e/auth/auth.login.e2e-spec.ts
+  dx test e2e backend apps/backend/e2e/auth/auth.login.e2e-spec.ts -t "should login"
+  dx test unit front
+  dx test unit admin
 `)
       return
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ranger1/dx",
-  "version": "0.1.78",
+  "version": "0.1.79",
   "type": "module",
   "license": "MIT",
   "repository": {