@weotro/dx 0.1.0

package/lib/cli/flags.js

@@ -0,0 +1,123 @@
+export const FLAG_DEFINITIONS = {
+  _global: [
+    { flag: '--dev' },
+    { flag: '--prod' },
+    { flag: '--staging' },
+    { flag: '--test' },
+    { flag: '--e2e' },
+    { flag: '--no-env-check' },
+    { flag: '-Y' },
+    { flag: '--yes' },
+    { flag: '-v' },
+    { flag: '--verbose' },
+    { flag: '-h' },
+    { flag: '--help' },
+    { flag: '-V' },
+    { flag: '--version' },
+    { flag: '--parallel' },
+    { flag: '-P' },
+  ],
+  db: [
+    { flag: '--name', expectsValue: true },
+    { flag: '-n', expectsValue: true },
+  ],
+  test: [
+    { flag: '-t', expectsValue: true },
+    { flag: '--name', expectsValue: true },
+    { flag: '--test-name-pattern', expectsValue: true },
+  ],
+  package: [
+    { flag: '--skip-build' },
+    { flag: '--keep-workdir' },
+  ],
+  worktree: [
+    { flag: '--base', expectsValue: true },
+    { flag: '-b', expectsValue: true },
+    { flag: '--all' },
+  ],
+  lint: [
+    { flag: '--fix' },
+  ],
+  deploy: [
+    { flag: '--BR' },
+    { flag: '--build-only' },
+    { flag: '--artifact', expectsValue: true },
+    { flag: '--skip-migration' },
+    { flag: '--webhook-path', expectsValue: true },
+    { flag: '--webhook-dry-run' },
+    { flag: '--strict-webhook' },
+    { flag: '--no-strict-webhook' },
+  ],
+}
+
+export function parseFlags(args = []) {
+  const flags = {}
+
+  for (let index = 0; index < args.length; index += 1) {
+    const flag = args[index]
+    if (flag === '--') break
+    if (!flag.startsWith('-')) continue
+    switch (flag) {
+      case '--dev':
+        flags.dev = true
+        break
+      case '--prod':
+        flags.prod = true
+        break
+      case '--staging':
+        flags.staging = true
+        break
+      case '--test':
+        flags.test = true
+        break
+      case '--e2e':
+        flags.e2e = true
+        break
+      case '-Y':
+      case '--yes':
+        flags.Y = true
+        break
+      case '-v':
+      case '--verbose':
+        flags.verbose = true
+        break
+      case '-h':
+      case '--help':
+        flags.help = true
+        break
+      case '-V':
+      case '--version':
+        flags.version = true
+        break
+      case '--no-env-check':
+        flags.noEnvCheck = true
+        break
+      case '--fix':
+        flags.fix = true
+        break
+      case '--parallel':
+      case '-P':
+        flags.parallel = true
+        break
+      case '--all':
+        flags.all = true
+        break
+      case '--BR':
+        flags.BR = true
+        break
+      case '--build-only':
+        flags.buildOnly = true
+        break
+      case '--artifact':
+        flags.artifact = args[index + 1]
+        break
+      case '--skip-migration':
+        flags.skipMigration = true
+        break
+      default:
+        break
+    }
+  }
+
+  return flags
+}

package/lib/cli/help-model.js

@@ -0,0 +1,222 @@
+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',
+])
+const BUILTIN_SUMMARIES = {
+  env: '安全校验并临时装配本地品牌环境配置',
+}
+
+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) || BUILTIN_SUMMARIES[commandName] || '',
+    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 'env':
+      return 'dx env status | validate <profile> [环境标志] | exec <profile> [环境标志] -- <command>'
+    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)
+}

package/lib/cli/help-renderer.js

@@ -0,0 +1,137 @@
+function normalizeArray(value) {
+  return Array.isArray(value) ? value : []
+}
+
+function pushSection(lines, title, entries = []) {
+  const normalizedEntries = entries.filter(Boolean)
+  if (normalizedEntries.length === 0) return
+
+  lines.push('', title, ...normalizedEntries)
+}
+
+function formatExample(example = {}, indent = '  ') {
+  const command = typeof example.command === 'string' ? example.command : ''
+  const description = typeof example.description === 'string' ? example.description : ''
+
+  if (!command) return ''
+  if (!description) return `${indent}${command}`
+  return `${indent}${command}  # ${description}`
+}
+
+function formatOption(option = {}, indent = '  ') {
+  const flags = normalizeArray(option.flags).filter(Boolean).join(', ')
+  const description = typeof option.description === 'string' ? option.description : ''
+
+  if (!flags && !description) return ''
+  if (!description) return `${indent}${flags}`
+  return `${indent}${flags}  ${description}`
+}
+
+function getVisibleTargets(targets = []) {
+  return normalizeArray(targets).filter(target => target?.nodeType !== 'orchestration-node')
+}
+
+function formatTarget(target = {}, width = 0) {
+  const name = typeof target.name === 'string' ? target.name : ''
+  const summary = typeof target.summary === 'string' ? target.summary : ''
+  const lines = []
+
+  if (!name) return lines
+
+  lines.push(summary ? `  ${name.padEnd(width)}  ${summary}` : `  ${name}`)
+
+  normalizeArray(target.notes).forEach(note => {
+    if (!note) return
+    lines.push(`    提示: ${note}`)
+  })
+
+  normalizeArray(target.options).forEach(option => {
+    const rendered = formatOption(option, '    选项: ')
+    if (rendered) lines.push(rendered)
+  })
+
+  normalizeArray(target.examples).forEach(example => {
+    const rendered = formatExample(example, '    示例: ')
+    if (rendered) lines.push(rendered)
+  })
+
+  return lines
+}
+
+export function renderGlobalHelp(model = {}) {
+  const lines = []
+  const invocation = model.invocation || 'dx'
+  const title = [model.title, model.summary].filter(Boolean).join(' - ') || model.title || model.summary
+  const commands = normalizeArray(model.commands)
+  const commandWidth = Math.max(0, ...commands.map(command => String(command?.name || '').length))
+
+  if (title) {
+    lines.push('', title)
+  }
+
+  pushSection(lines, '用法:', [`  ${invocation} <命令> [选项] [参数...]`])
+  pushSection(
+    lines,
+    '命令:',
+    commands.map(command => {
+      const name = String(command?.name || '')
+      const summary = String(command?.summary || '')
+      if (!name) return ''
+      return summary ? `  ${name.padEnd(commandWidth)}  ${summary}` : `  ${name}`
+    }),
+  )
+  pushSection(lines, '选项:', normalizeArray(model.globalOptions).map(option => formatOption(option)))
+  pushSection(lines, '示例:', normalizeArray(model.examples).map(example => formatExample(example)))
+
+  lines.push('', `运行 ${invocation} help <命令> 查看子命令的详细用法和示例`)
+
+  return lines.join('\n')
+}
+
+export function renderCommandHelp(model = {}) {
+  const name = typeof model.name === 'string' ? model.name : ''
+  const usage = typeof model.usage === 'string' ? model.usage : ''
+  const args = normalizeArray(model.args)
+  const notes = normalizeArray(model.notes)
+  const options = normalizeArray(model.options)
+  const examples = normalizeArray(model.examples)
+  const targets = getVisibleTargets(model.targets)
+  const targetWidth = Math.max(0, ...targets.map(target => String(target?.name || '').length))
+  const lines = []
+
+  if (name) {
+    lines.push('', `${name} 命令用法:`)
+  }
+
+  if (usage) {
+    lines.push(`  ${usage}`)
+  }
+
+  if (model.summary) {
+    pushSection(lines, '摘要:', [`  ${model.summary}`])
+  }
+
+  pushSection(
+    lines,
+    '参数说明:',
+    args.map(arg => {
+      const argName = typeof arg.name === 'string' ? arg.name : ''
+      const description = typeof arg.description === 'string' ? arg.description : ''
+
+      if (!argName && !description) return ''
+      if (!description) return `  ${argName}`
+      return `  ${argName}: ${description}`
+    }),
+  )
+
+  pushSection(
+    lines,
+    '可用 target:',
+    targets.flatMap(target => formatTarget(target, targetWidth)),
+  )
+  pushSection(lines, '选项:', options.map(option => formatOption(option)))
+  pushSection(lines, '提示:', notes.map(note => (note ? `  ${note}` : '')))
+  pushSection(lines, '示例:', examples.map(example => formatExample(example)))
+
+  return lines.join('\n')
+}