@weotro/dx 0.1.18 → 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.18",
+  "version": "0.1.21",
   "type": "module",
   "license": "MIT",
   "repository": {

package/skills/gh-dependabot-cleanup/SKILL.md

@@ -25,8 +25,9 @@ Use this skill to complete a Dependabot remediation loop with minimal manual inp
 5. Apply dependency changes (prefer overrides/resolutions for transitive alerts).
 6. Refresh lockfile.
 7. Run required project verification commands.
-8. For an authorized PR delivery, commit, push, and open a focused PR; a local remediation request finishes with the verified local changes.
-9. Report residual risk (unpatched alerts) in PR and final reply.
+8. For authorized issue and PR delivery, find and reuse a matching tracking issue or create one with the alert scope, remediation plan, and verification results. Commit, push, and open a focused PR linked to that issue. A local remediation request finishes with verified local changes and drafts for any requested delivery that still lacks authorization.
+9. If the user requests merging, continue through the merge workflow below using the existing authorization; opening a PR alone does not complete that request.
+10. Report the issue, PR, merge outcome, and residual risk using the final reply requirements below.
 
 ## Default Commands
 ```bash
@@ -51,7 +52,18 @@ pnpm install --lockfile-only
 
 ## PR Requirements
 Include these sections:
-1. Fixed alerts: alert id, package, target version
-2. Remaining alerts: alert id, reason (for example, no upstream patch)
-3. Verification: exact commands run and outcomes
-4. Risk note: what is deferred and why
+1. Tracking issue: issue number and URL; use `Closes #<issue>` only when the PR completes the issue's entire scope. Otherwise use `Refs #<issue>` and keep the remaining work tracked.
+2. Fixed alerts: alert id, package, target version
+3. Remaining alerts: alert id, reason (for example, no upstream patch)
+4. Verification: exact commands run and outcomes
+5. Risk note: what is deferred and why
+
+## Merge Workflow
+- Before merging, verify the PR's current head, required checks, review requirements, and mergeability. Follow the repository's merge strategy and branch protection; do not bypass required checks or reviews.
+- When merge is authorized and requirements pass, merge with `gh pr merge`, binding the operation to the verified head via `--match-head-commit`. If the head changes, verify the new head before retrying.
+- If checks or reviews block merging, resolve actionable failures within scope and recheck. Report any remaining blocker precisely. Enabling auto-merge or entering a merge queue is pending, not a completed merge.
+- After merging, verify the PR's `MERGED` state and merge commit, check the tracking issue's state, and fetch Dependabot alerts again. Report still-open alerts as observed; distinguish scan results that have not yet updated from confirmed remediation failures.
+
+## Final Reply Requirements
+Always explicitly mention both **Issue** and **PR**, including their numbers, URLs, and observed states. If either was not created or reused, say so and explain why; never substitute a Dependabot alert number for an issue number.
+State whether the PR was actually merged, with the merge commit when available, or give the concrete pending condition or blocker. Include verification results and remaining alerts. Do not claim completion of a requested merge based only on PR creation, auto-merge configuration, or queue entry.

package/skills/git-release/SKILL.md

@@ -11,6 +11,8 @@ description: 仅在显式调用 git-release 时使用：准备或执行版本发
 只读检索、本地草稿、可回滚编辑和常规测试可自主推断并继续；从相关文件和直接依赖开始，仅在证据不足或影响跨模块时扩大范围，复用仍有效的验证。
 仅在不可逆或难以回滚的修改缺少具体授权时，先完成预览、草稿与验证，再说明对象和影响并等待确认；会话中已有授权继续有效。缺少事实时先查证、标注假设并推进独立工作，确实无法确定操作目标时才询问。对外发送消息须有明确授权。
 
+用户显式调用本技能执行发布，即明确授权在本次目标仓库创建并推送目标版本的 tag，以及创建并发布对应的 GitHub Release。完成准备和验证后连续执行至发布结果核验，无需再次询问是否推送 tag 或创建 Release。用户明确限定为仅准备、草稿、审计或修改技能时，按该范围执行；本授权不包含覆盖冲突 tag、删除既有 Release 或额外的生产操作。
+
 ## 发布准备
 
 从当前 release 分支、用户指定版本或项目版本策略确定目标版本，说明来源。若项目采用 `release/vX.Y.Z`（也支持 alpha/beta/rc）则沿用；其他命名服从项目规则。没有版本策略时可以准备下一补丁版本的本地草稿，公开发布前核实目标。
@@ -27,7 +29,7 @@ description: 仅在显式调用 git-release 时使用：准备或执行版本发
 
 ## 创建发布
 
-推送 tag 和创建 Release 可能触发不可逆的制品发布或部署。在执行前核对目标仓库、版本、commit、发行说明及现有授权；授权已明确覆盖这些对象时直接继续，否则准备好具体结果再确认。
+执行前核对目标仓库、版本、commit 和发行说明，确认发布检查通过、目标 tag 无冲突，然后依据「执行边界与优先级」中的明确授权直接推送 tag 并创建 GitHub Release。发布流程可能自动触发制品发布或部署，不因此追加确认步骤；仅在目标无法确定、检查失败或远端状态冲突时暂停受阻操作并说明原因。
 
 按项目发布流程创建 tag、推送并创建 Release；例如：
 ```bash