@weotro/dx 0.1.19 → 0.1.21

package/README.md

@@ -103,6 +103,57 @@ DX_CONFIG_DIR=/path/to/your-repo/dx/config dx status
 
 ### 1) dx/config/commands.json
 
+#### 自定义命令参数透传
+
+在选中的可执行叶节点声明 `allowPassthrough: true`，然后用第一个独立的 `--`
+分开 DX 选项和子命令参数：
+
+```sh
+dx release plan --prod -- --brands zh --targets backend --ref v0.2.205
+```
+
+最小 `commands.json`（脚本由目标项目提供）：
+
+```json
+{
+  "release": {
+    "plan": {
+      "production": {
+        "command": "node scripts/release/cli.mjs plan --environment production",
+        "allowPassthrough": true
+      }
+    }
+  }
+}
+```
+
+字段契约：
+
+| 字段 | 类型 / 默认值 | 作用 |
+| --- | --- | --- |
+| `allowPassthrough` | boolean / `false` | 只有严格的 `true` 开启透传；必须放在环境选择后的 `command` 叶节点，父节点不继承 |
+| `command` | string | 现有 Bash 命令；用户参数逐项转义后追加在末尾，固定参数在前 |
+
+适用于通用配置处理器执行的自定义命令，包括 `release plan/run` 这类内置命令族的扩展 action，
+以及任意非内置顶层命令。`concurrent`、`sequential`、`internal` 配置暂不支持透传，
+即使声明 `allowPassthrough: true` 也会拒绝非空参数；不会向多个子任务广播。
+内置 `test/db/env` 等仍使用各自已有的参数契约，此字段不会覆盖内置处理器。
+
+迁移时，为确实需要接收参数的叶节点增加该字段，并将业务参数移到 `--` 后。
+未开启或不支持透传的配置收到非空子参数时会非零退出，不再静默丢弃后执行默认命令。
+没有子参数或仅有末尾 `--` 时保留旧行为；省略分隔符的未知选项继续报错。
+
+第一个 `--` 后的顺序、重复项、空字符串、特殊字符和第二个 `--` 均保留。
+其中的 `--prod`、`-Y`、`--help`、`--version`、`--config-dir` 不影响 DX 自身。
+危险操作仍须通过原确认流程；子命令退出失败时 DX 非零退出。
+DX 不校验业务参数含义，拼错的 key、品牌、目标、ref 由子脚本严格校验。
+
+建议 `command` 只调用一个脚本；包含管道、多个语句或末尾注释的 shell 文本应先移入脚本，
+确保追加参数由明确的入口接收。不要在命令中自行拼接用户输入。
+
+回归验证：`pnpm test --runInBand test/configured-passthrough.test.js`，测试使用真实
+`bin/dx.js` 和临时 probe，校验实际子进程 argv、拒绝时未启动子进程及失败退出。
+
 这是核心文件，定义了 dx 各命令要执行的 shell 命令，也承载帮助信息配置。
 
 它支持：

package/bin/dx.js

@@ -8,7 +8,9 @@ function parseConfigDir(argv) {
   const envValue = process.env.DX_CONFIG_DIR
   if (envValue) return String(envValue)
 
-  const args = Array.isArray(argv) ? argv : []
+  const raw = Array.isArray(argv) ? argv : []
+  const separator = raw.indexOf('--')
+  const args = separator === -1 ? raw : raw.slice(0, separator)
   const idx = args.indexOf('--config-dir')
   if (idx !== -1 && idx + 1 < args.length) return String(args[idx + 1])
   for (const token of args) {
@@ -22,7 +24,14 @@ function stripConfigDirArgs(argv) {
   const out = []
   for (let i = 0; i < args.length; i++) {
     const token = args[i]
+    if (token === '--') {
+      out.push(...args.slice(i))
+      break
+    }
     if (token === '--config-dir') {
+      if (args[i + 1] === undefined || args[i + 1] === '--') {
+        throw new Error('--config-dir 需要在 -- 分隔符前提供配置目录')
+      }
       i++
       continue
     }

package/lib/cli/dx-cli.js

@@ -11,7 +11,7 @@ import {
   resolveTargetRequiredVars,
 } from '../env-policy.js'
 import { FLAG_DEFINITIONS, parseFlags } from './flags.js'
-import { getCleanArgs, getCleanArgsWithConsumedValues } from './args.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'
@@ -189,12 +189,14 @@ class DxCli {
   }
 
   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)
     }
   }
 
@@ -220,6 +222,9 @@ class DxCli {
       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)
@@ -234,7 +239,17 @@ class DxCli {
     } else if (config.sequential && Array.isArray(config.commands)) {
       await this.handleSequentialCommands(config.commands, environment)
     } else {
-      await this.executeCommand(config)
+      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 <命令路径> [环境标志] -- <子命令参数>。')
     }
   }
 
@@ -389,6 +404,14 @@ class DxCli {
 
       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}`)
@@ -810,6 +833,7 @@ class DxCli {
 
   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(', ')}`)
@@ -937,7 +961,8 @@ class DxCli {
   }
 
   // 执行单个命令
-  async executeCommand(config, overrideFlags) {
+  async executeCommand(config, overrideFlags, passthroughArgs = []) {
+    this.validateConfiguredPassthrough(config, passthroughArgs)
     if (!config) {
       logger.error('无效的命令配置')
       return
@@ -1022,6 +1047,7 @@ class DxCli {
       env: config.env || {},
       skipEnvValidation: Boolean(config.skipEnvValidation),
       forcePortCleanup: Boolean(config.forcePortCleanup),
+      passthroughArgs,
     }
 
     await execManager.executeCommand(rawCommand, options)

package/lib/cli/help-model.js

@@ -84,19 +84,31 @@ export function getGlobalHelpModel(commands = {}, context = {}) {
 export function getCommandHelpModel(commands = {}, commandName, context = {}) {
   const commandConfig = commands?.[commandName] ?? {}
   const commandHelp = getCommandHelpConfig(commands, commandName)
+  const notes = [...normalizeArray(commandHelp?.notes)]
+  if (hasPassthroughCommand(commandConfig)) {
+    notes.push(`自定义 command 叶节点设置 allowPassthrough: true 后可透传参数：dx ${commandName} <命令路径> [环境标志] -- <子命令参数>；未开启或组合/internal 命令收到额外参数会报错。`)
+  }
 
   return {
     name: commandName,
     summary: resolveSummary(commandConfig, commandHelp) || BUILTIN_SUMMARIES[commandName] || '',
     usage: resolveUsage(commandName, commandHelp, commandConfig),
     args: normalizeArray(commandHelp?.args),
-    notes: normalizeArray(commandHelp?.notes),
+    notes,
     examples: normalizeArray(commandHelp?.examples),
     options: normalizeArray(commandHelp?.options),
     targets: resolveVisibleTargets(commands, commandName, commandConfig, context),
   }
 }
 
+function hasPassthroughCommand(node) {
+  if (!isPlainObject(node)) return false
+  if (node.command || node.internal || node.concurrent || node.sequential) {
+    return Boolean(node.command && node.allowPassthrough === true && !node.internal && !node.concurrent && !node.sequential)
+  }
+  return Object.entries(node).some(([key, value]) => key !== 'help' && hasPassthroughCommand(value))
+}
+
 export function resolveSummary(node = {}, help = null) {
   return help?.summary || node?.help?.summary || node?.description || ''
 }

package/lib/exec.js

@@ -66,6 +66,7 @@ export class ExecManager {
       ports = [],
       skipEnvValidation = false,
       forcePortCleanup = false,
+      passthroughArgs = [],
     } = options
 
     // 在执行前同步环境，确保 Nx/构建工具拿到规范的 NODE_ENV
@@ -186,7 +187,12 @@ export class ExecManager {
       }
     }
 
-    logger.command(fullCommand)
+    // Quote for the bash executor, after command classification so child data
+    // cannot change environment selection or trigger port-cleanup heuristics.
+    const executionCommand = passthroughArgs.length > 0
+      ? `${fullCommand} ${passthroughArgs.map(arg => `'${arg.replace(/'/g, "'\\''")}'`).join(' ')}`
+      : fullCommand
+    logger.command(executionCommand)
 
     // 执行命令（可能重试）
     let lastError = null
@@ -253,7 +259,7 @@ export class ExecManager {
           }
         }
 
-        const result = await this.spawnCommand(fullCommand, {
+        const result = await this.spawnCommand(executionCommand, {
           cwd: cwd || process.cwd(),
           stdio,
           env: sanitizeChildEnv({

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weotro/dx",
-  "version": "0.1.19",
+  "version": "0.1.21",
   "type": "module",
   "license": "MIT",
   "repository": {