@ranger1/dx 0.1.96 → 0.1.98

package/lib/cli/dx-cli.js

@@ -13,10 +13,10 @@ import {
 import { FLAG_DEFINITIONS, parseFlags } from './flags.js'
 import { getCleanArgs, getCleanArgsWithConsumedValues } from './args.js'
 import { showHelp, showCommandHelp } from './help.js'
+import { buildStrictHelpValidationContext, validateHelpConfig } from './help-schema.js'
 import { getPackageVersion } from '../version.js'
 import {
   handleHelp,
-  handleDev,
   handleBuild,
   handleTest,
   handleLint,
@@ -51,7 +51,6 @@ class DxCli {
     this.envCache = null
     this.commandHandlers = {
       help: args => handleHelp(this, args),
-      dev: args => handleDev(this, args),
       start: args => handleStart(this, args),
       build: args => handleBuild(this, args),
       test: args => handleTest(this, args),
@@ -70,6 +69,7 @@ class DxCli {
     }
 
     this.flagDefinitions = FLAG_DEFINITIONS
+    this.validateLoadedHelpConfig()
   }
 
   // 加载命令配置
@@ -84,6 +84,10 @@ class DxCli {
     }
   }
 
+  validateLoadedHelpConfig() {
+    validateHelpConfig(this.commands, buildStrictHelpValidationContext(this))
+  }
+
   // 检测并安装依赖
   async ensureDependencies() {
     const nodeModulesPath = join(process.cwd(), 'node_modules')
@@ -160,8 +164,17 @@ class DxCli {
 
   // 检测并生成 Prisma Client
   async ensurePrismaClient() {
+    // 仅对真正安装了 @prisma/client 的项目执行检查。
+    // 依据「node_modules/@prisma/client/package.json 是否存在」判断项目是否使用 Prisma，
+    // 避免在纯文档站、纯前端等未引入 Prisma 的项目上误触发生成流程，
+    // 进而报出形如「未找到 db.generate 命令配置」的误导性错误。
+    const prismaClientDir = join(process.cwd(), 'node_modules', '@prisma', 'client')
+    if (!existsSync(join(prismaClientDir, 'package.json'))) {
+      return
+    }
+
     // pnpm 结构下检测 @prisma/client 生成的 default.js 文件
-    const prismaClientPath = join(process.cwd(), 'node_modules', '@prisma', 'client', 'default.js')
+    const prismaClientPath = join(prismaClientDir, 'default.js')
 
     if (!existsSync(prismaClientPath)) {
       const environment = this.determineEnvironment()
@@ -172,22 +185,9 @@ class DxCli {
           throw new Error('未找到 db.generate 命令配置，请检查 dx/config/commands.json')
         }
 
-        const envKey = this.normalizeEnvKey(environment)
-        const execFlags = { ...this.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 execManager.executeCommand(generateConfig.command, {
           app: generateConfig.app || 'backend',
-          flags: execFlags,
+          flags: this.createExecutionFlags(environment),
           // Prisma generate 不应卡在环境变量校验上
           skipEnvValidation: true,
         })
@@ -286,9 +286,9 @@ class DxCli {
       // 显示帮助
       if (this.flags.help || !this.command) {
         if (this.flags.help && this.command && this.command !== 'help') {
-          showCommandHelp(this.command)
+          showCommandHelp(this.command, this)
         } else {
-          showHelp()
+          showHelp(this)
         }
         return
       }
@@ -298,7 +298,7 @@ class DxCli {
       // Fail fast for unknown commands before dependency/env startup checks.
       if (this.command && !this.commandHandlers[this.command]) {
         logger.error(`未知命令: ${this.command}`)
-        showHelp()
+        showHelp(this)
         process.exit(1)
       }
 
@@ -346,7 +346,7 @@ class DxCli {
     const [, ...subArgs] = cleanArgs
 
     if (!command) {
-      showHelp()
+      showHelp(this)
       return
     }
 
@@ -504,14 +504,14 @@ class DxCli {
       case 'worktree': {
         if (positionalArgs.length === 0) return
         const action = positionalArgs[0]
-        if (['del', 'delete', 'rm'].includes(action)) {
+        if (action === 'del') {
           return
         }
-        if (['make'].includes(action)) {
+        if (action === 'make') {
           ensureMax(3)
           break
         }
-        if (['list', 'ls', 'clean', 'prune'].includes(action)) {
+        if (action === 'list' || action === 'clean') {
           ensureMax(1)
           break
         }
@@ -550,11 +550,8 @@ class DxCli {
     const value = String(token).toLowerCase()
     return (
       value === 'dev' ||
-      value === 'development' ||
       value === 'prod' ||
-      value === 'production' ||
       value === 'staging' ||
-      value === 'stage' ||
       value === 'test' ||
       value === 'e2e'
     )
@@ -570,18 +567,19 @@ class DxCli {
     if (suggestion) {
       logger.info(`建议命令: ${suggestion}`)
     } else if (normalizedFlag) {
-    logger.info(`示例: ${this.invocation} ${command} ... ${normalizedFlag}`)
+      logger.info(`示例: ${this.invocation} ${command} ... ${normalizedFlag}`)
     }
     logger.info('未显式指定环境时将默认使用 --dev。')
     process.exit(1)
   }
 
   getEnvironmentFlagExample(token) {
-    const key = this.normalizeEnvKey(token)
-    switch (key) {
+    switch (String(token || '').toLowerCase()) {
       case 'dev':
+      case 'development':
         return '--dev'
       case 'prod':
+      case 'production':
         return '--prod'
       case 'staging':
         return '--staging'
@@ -634,13 +632,13 @@ class DxCli {
   }
 
   validateStartPositionals(positionalArgs) {
-    const service = positionalArgs[0] || 'dev'
+    const service = positionalArgs[0] || 'development'
     const environment = this.determineEnvironment()
     const envKey = this.normalizeEnvKey(environment)
 
-    if (service === 'dev' && envKey !== 'dev') {
+    if (service === 'development' && envKey !== 'development') {
       logger.error('dx start 在未指定服务时仅允许使用开发环境')
-      logger.info(`示例: ${this.invocation} start all --dev`)
+      logger.info(`示例: ${this.invocation} start --dev`)
       logger.info(`示例: ${this.invocation} start backend --prod`)
       process.exit(1)
     }
@@ -649,7 +647,7 @@ class DxCli {
     if (!startConfig) return
 
     // 对 start 下的单层 command 配置，默认视为开发态目标，仅允许 --dev。
-    if (startConfig.command && envKey !== 'dev') {
+    if (startConfig.command && envKey !== 'development') {
       logger.error(`启动目标 ${service} 仅支持开发环境`)
       logger.info(`示例: ${this.invocation} start ${service} --dev`)
       process.exit(1)
@@ -669,13 +667,13 @@ class DxCli {
     const buildConfig = this.commands?.build?.[target]
     if (!buildConfig || buildConfig.command) return
 
-    const supportsCurrentEnv = Boolean(buildConfig[envKey] || (envKey === 'staging' && buildConfig.prod))
+    const supportsCurrentEnv = Boolean(buildConfig[envKey])
     if (supportsCurrentEnv) return
 
     const envFlag = this.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 buildConfig)
       .map(key => this.getEnvironmentFlagExample(key) || `--${key}`)
     if (available.length > 0) {
@@ -688,19 +686,6 @@ class DxCli {
     process.exit(1)
   }
 
-  reportDevCommandRemoved(args) {
-    const target = args?.[0]
-    logger.error('`dx dev` 命令已移除，统一使用 `dx start`。')
-    if (target) {
-      logger.info(`请执行: ${this.invocation} start ${target} --dev`)
-    } else {
-      logger.info(`示例: ${this.invocation} start backend --dev`)
-      logger.info(`      ${this.invocation} start front --dev`)
-      logger.info(`      ${this.invocation} start admin --dev`)
-    }
-    process.exit(1)
-  }
-
   reportExtraPositionals(command, extras) {
     const list = extras.join(', ')
     if (command === '全局') {
@@ -772,7 +757,7 @@ class DxCli {
         continue
       }
       commands.push({
-        command: this.applySdkOfflineFlag(config.command),
+        command: config.command,
         options: {
           app: config.app,
           ports: config.ports,
@@ -820,22 +805,11 @@ class DxCli {
     if (environment && config) {
       const envKey = this.normalizeEnvKey(environment)
       if (config[envKey]) config = config[envKey]
-      else if (envKey === 'staging' && config.prod) config = config.prod
     }
 
     return config
   }
 
-  // SDK 构建命令当前不再暴露 --online/--offline 模式，保留该方法仅为兼容旧调用
-  applySdkModeFlags(command) {
-    return command
-  }
-
-  // 向后兼容的别名
-  applySdkOfflineFlag(command) {
-    return command
-  }
-
   collectStartPorts(service, startConfig, envKey) {
     const portSet = new Set()
 
@@ -845,15 +819,6 @@ class DxCli {
       })
     }
 
-    if (envKey === 'dev') {
-      const legacyConfig = this.commands.dev?.[service]
-      if (legacyConfig && Array.isArray(legacyConfig.ports)) {
-        legacyConfig.ports.forEach(port => {
-          this.addPortToSet(portSet, port)
-        })
-      }
-    }
-
     return Array.from(portSet)
   }
 
@@ -936,28 +901,6 @@ class DxCli {
     }
 
     const rawCommand = String(config.command).trim()
-    // backward compat: old commands.json referenced scripts/lib/*.js in the project
-    if (rawCommand.startsWith('node scripts/lib/sdk-build.js')) {
-      const argsText = rawCommand.replace(/^node\s+scripts\/lib\/sdk-build\.js\s*/g, '')
-      const args = argsText ? argsText.split(/\s+/).filter(Boolean) : []
-      await withTempEnv(async () => {
-        const { runSdkBuild } = await import('../sdk-build.js')
-        await runSdkBuild(args)
-      })
-      return
-    }
-
-    if (rawCommand.startsWith('node scripts/lib/backend-package.js')) {
-      const argsText = rawCommand.replace(/^node\s+scripts\/lib\/backend-package\.js\s*/g, '')
-      const args = argsText ? argsText.split(/\s+/).filter(Boolean) : []
-      await withTempEnv(async () => {
-        const { runBackendPackage } = await import('../backend-package.js')
-        await runBackendPackage(args)
-      })
-      return
-    }
-
-    const command = this.applySdkOfflineFlag(rawCommand)
 
     const options = {
       app: config.app,
@@ -969,7 +912,7 @@ class DxCli {
       forcePortCleanup: Boolean(config.forcePortCleanup),
     }
 
-    await execManager.executeCommand(command, options)
+    await execManager.executeCommand(rawCommand, options)
   }
 
   // 确定环境
@@ -977,17 +920,14 @@ class DxCli {
     return envManager.detectEnvironment(this.flags)
   }
 
-  // 规范化环境键到命令配置使用的命名（dev/prod/test/e2e）
+  // 规范化环境键到命令配置使用的命名（development/staging/production/test/e2e）
   normalizeEnvKey(env) {
     switch (String(env || '').toLowerCase()) {
       case 'development':
-      case 'dev':
-        return 'dev'
+        return 'development'
       case 'production':
-      case 'prod':
-        return 'prod'
+        return 'production'
       case 'staging':
-      case 'stage':
         return 'staging'
       case 'test':
         return 'test'
@@ -998,6 +938,23 @@ class DxCli {
     }
   }
 
+  createExecutionFlags(environment) {
+    const envKey = this.normalizeEnvKey(environment)
+    const execFlags = { ...this.flags }
+
+    ;['dev', 'prod', 'staging', 'test', 'e2e'].forEach(key => {
+      delete execFlags[key]
+    })
+
+    if (envKey === 'production') execFlags.prod = true
+    else if (envKey === 'development') execFlags.dev = true
+    else if (envKey === 'test') execFlags.test = true
+    else if (envKey === 'e2e') execFlags.e2e = true
+    else if (envKey === 'staging') execFlags.staging = true
+
+    return execFlags
+  }
+
 }
 
 export { DxCli }

package/lib/cli/flags.js

@@ -1,11 +1,8 @@
 export const FLAG_DEFINITIONS = {
   _global: [
     { flag: '--dev' },
-    { flag: '--development' },
     { flag: '--prod' },
-    { flag: '--production' },
     { flag: '--staging' },
-    { flag: '--stage' },
     { flag: '--test' },
     { flag: '--e2e' },
     { flag: '--no-env-check' },
@@ -59,15 +56,12 @@ export function parseFlags(args = []) {
     if (!flag.startsWith('-')) continue
     switch (flag) {
       case '--dev':
-      case '--development':
         flags.dev = true
         break
       case '--prod':
-      case '--production':
         flags.prod = true
         break
       case '--staging':
-      case '--stage':
         flags.staging = true
         break
       case '--test':

package/lib/cli/help-model.js

@@ -0,0 +1,217 @@
+const ENVIRONMENT_KEYS = new Set(['development', 'production', 'staging', 'test', 'e2e'])
+const COMMAND_LIST_HIDDEN = new Set(['help'])
+const META_KEYS = new Set(['help', 'description', 'args', 'interactive', 'dangerous'])
+const INTERNAL_CONFIG_KEYS = new Set([
+  'services',
+  'urls',
+  'preflight',
+  'ecosystemConfig',
+  'pm2Bin',
+  'backendDeploy',
+  'artifactDeploy',
+  'telegramWebhook',
+])
+
+export function buildHelpRuntimeContext(cli = {}) {
+  return {
+    registeredCommands: getRegisteredCommands(cli),
+    knownFlags: getKnownFlags(cli),
+  }
+}
+
+export function getRegisteredCommands(cli = {}) {
+  const handlers = cli?.commandHandlers
+  if (!handlers || typeof handlers !== 'object') return []
+
+  return Object.keys(handlers).filter(name => !COMMAND_LIST_HIDDEN.has(name))
+}
+
+export function getKnownFlags(cli = {}) {
+  const definitions = cli?.flagDefinitions
+  const knownFlags = new Map()
+
+  if (!definitions || typeof definitions !== 'object') return knownFlags
+
+  for (const entries of Object.values(definitions)) {
+    if (!Array.isArray(entries)) continue
+    for (const entry of entries) {
+      if (!entry?.flag) continue
+      knownFlags.set(entry.flag, {
+        expectsValue: Boolean(entry.expectsValue),
+      })
+    }
+  }
+
+  return knownFlags
+}
+
+export function classifyCommandNode(node = {}) {
+  if (node?.help?.nodeType) return node.help.nodeType
+  if (looksLikeInternalConfigBag(node)) return 'internal-config-bag'
+  if (node?.command || node?.internal) return 'target-leaf'
+  if (node?.concurrent || node?.sequential) return 'orchestration-node'
+  if (looksLikeEnvContainer(node)) return 'env-container'
+  if (looksLikeCategoryNode(node)) return 'category-node'
+  return 'unknown-node'
+}
+
+export function isVisibleHelpNode(name, node, nodeType = classifyCommandNode(node)) {
+  void name
+
+  if (node?.help?.expose === false) return false
+  if (nodeType === 'internal-config-bag') return false
+  if (nodeType === 'category-node') return false
+  if (nodeType === 'orchestration-node') return node?.help?.expose === true
+  return true
+}
+
+export function getGlobalHelpModel(commands = {}, context = {}) {
+  const registeredCommands = Array.isArray(context?.registeredCommands)
+    ? context.registeredCommands
+    : []
+
+  return {
+    summary: commands?.help?.summary ?? '',
+    commands: registeredCommands.map(name => getCommandHelpModel(commands, name, context)),
+    globalOptions: normalizeArray(commands?.help?.globalOptions),
+    examples: normalizeArray(commands?.help?.examples),
+  }
+}
+
+export function getCommandHelpModel(commands = {}, commandName, context = {}) {
+  const commandConfig = commands?.[commandName] ?? {}
+  const commandHelp = getCommandHelpConfig(commands, commandName)
+
+  return {
+    name: commandName,
+    summary: resolveSummary(commandConfig, commandHelp),
+    usage: resolveUsage(commandName, commandHelp, commandConfig),
+    args: normalizeArray(commandHelp?.args),
+    notes: normalizeArray(commandHelp?.notes),
+    examples: normalizeArray(commandHelp?.examples),
+    options: normalizeArray(commandHelp?.options),
+    targets: resolveVisibleTargets(commands, commandName, commandConfig, context),
+  }
+}
+
+export function resolveSummary(node = {}, help = null) {
+  return help?.summary || node?.help?.summary || node?.description || ''
+}
+
+function resolveUsage(commandName, commandHelp = {}, commandConfig = {}) {
+  return commandHelp?.usage || generateUsage(commandName, commandConfig)
+}
+
+function generateUsage(commandName, commandConfig = {}) {
+  switch (commandName) {
+    case 'start':
+      return 'dx start <service> [环境标志]'
+    case 'build':
+    case 'package':
+      return `dx ${commandName} <target> [环境标志]`
+    case 'db':
+      return 'dx db <action> [name] [环境标志]'
+    case 'test':
+      return 'dx test [type] <target> [path]'
+    case 'deploy':
+    case 'clean':
+    case 'cache':
+      return `dx ${commandName} <target>`
+    case 'help':
+      return 'dx help [command]'
+    case 'worktree':
+      return 'dx worktree [action] [args...]'
+    case 'lint':
+    case 'status':
+      return `dx ${commandName}`
+    default:
+      return hasVisibleTargets(commandConfig) ? `dx ${commandName} <target>` : `dx ${commandName}`
+  }
+}
+
+function hasVisibleTargets(commandConfig) {
+  if (!isPlainObject(commandConfig)) return false
+
+  return Object.entries(commandConfig).some(([name, node]) => {
+    if (name === 'help') return false
+    return isVisibleHelpNode(name, node)
+  })
+}
+
+function resolveVisibleTargets(commands, commandName, commandConfig, context) {
+  void context
+
+  if (!isPlainObject(commandConfig)) return []
+
+  return Object.entries(commandConfig)
+    .filter(([name]) => name !== 'help')
+    .map(([name, node]) => {
+      const nodeType = classifyCommandNode(node)
+      if (!isVisibleHelpNode(name, node, nodeType)) return null
+
+      const targetHelp = getTargetHelpConfig(commands, commandName, name)
+
+      return {
+        name,
+        nodeType,
+        summary: resolveSummary(node, targetHelp),
+        notes: normalizeArray(targetHelp?.notes),
+        options: normalizeArray(targetHelp?.options),
+        examples: normalizeArray(targetHelp?.examples),
+      }
+    })
+    .filter(Boolean)
+}
+
+function getCommandHelpConfig(commands, commandName) {
+  const config = commands?.help?.commands?.[commandName]
+  return isPlainObject(config) ? config : {}
+}
+
+function getTargetHelpConfig(commands, commandName, targetName) {
+  const config = commands?.help?.targets?.[commandName]?.[targetName]
+  return isPlainObject(config) ? config : {}
+}
+
+function looksLikeInternalConfigBag(node) {
+  if (!isPlainObject(node)) return false
+  if (node.command || node.internal || node.concurrent || node.sequential) return false
+  if (looksLikeEnvContainer(node)) return false
+
+  const visibleKeys = getVisibleKeys(node)
+  if (visibleKeys.length === 0) return false
+
+  return visibleKeys.some(key => INTERNAL_CONFIG_KEYS.has(key))
+}
+
+function looksLikeEnvContainer(node) {
+  if (!isPlainObject(node)) return false
+  const visibleKeys = getVisibleKeys(node)
+  if (visibleKeys.length === 0) return false
+
+  const envKeys = visibleKeys.filter(key => ENVIRONMENT_KEYS.has(key))
+  return envKeys.length > 0 && envKeys.length === visibleKeys.length
+}
+
+function looksLikeCategoryNode(node) {
+  if (!isPlainObject(node)) return false
+  if (node.command || node.internal || node.concurrent || node.sequential) return false
+  if (looksLikeEnvContainer(node) || looksLikeInternalConfigBag(node)) return false
+
+  const visibleKeys = getVisibleKeys(node)
+  if (visibleKeys.length === 0) return false
+
+  return visibleKeys.every(key => isPlainObject(node[key]))
+}
+
+function getVisibleKeys(node) {
+  return Object.keys(node).filter(key => !META_KEYS.has(key))
+}
+
+function normalizeArray(value) {
+  return Array.isArray(value) ? value : []
+}
+
+function isPlainObject(value) {
+  return Boolean(value) && typeof value === 'object' && !Array.isArray(value)
+}