@epxing/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,72 @@
-# Temporary Holding Version
+# @epxing/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+独立的工程开发工具，包含交互菜单、开发服务、工程与产品库构建、创建、Vue3 迁移、静态检查和升级技能安装。CLI 使用自己的版本号，目标平台由 `--epx-frame` 指定；发布包没有 npm 运行时依赖。启动、构建调用当前工程的脚本及本地依赖；迁移代码与框架仓库的 `tools/` 共用，打包时编译为独立 Node 程序。
+
+```powershell
+npm install -g @epxing/cli@0.2.0 --registry https://registry.npmjs.org/
+epx                             # ↑↓ + Enter 选择；Esc / Ctrl+C 取消
+epx dev --port 3000
+epx build --mode prd
+epx lib                         # 产品库整体构建；平台目录构建聚合组件库
+epx lib --lazy                  # 产品按需库（工程需支持此构建形态）
+epx create my-product --epx-frame <目标平台版本>
+epx migrate E:/products/old-product --epx-frame <目标平台版本>
+epx migrate E:/products/old-product --epx-frame <目标平台版本> --apply
+epx skill install --dir E:/products/my-product
+```
+
+如已全局安装旧的 `epx-frame` CLI，先用 `npm uninstall -g epx-frame` 释放 `epx` 命令。产品工程里的 `epx-frame` 依赖保留。工具不在安装阶段运行迁移、下载平台或改产品文件；产品仍需安装目标框架依赖才能开发和构建。
+
+使用 fnm/nvm 时，不同 Node 版本的全局包分别安装。切换到日常使用的 Node 版本后更新 CLI，再用 `epx help` 确认开头为 `@epxing/cli`、`epx --version` 确认版本。旧仓库的 `pnpm epx` 仍是该仓库自己的脚本。
+
+## 命令
+
+| 命令 | 行为 |
+| --- | --- |
+| `epx` / `epx menu` | 交互选择操作、工程目录、环境、端口和构建方式；管道支持数字输入 |
+| `epx dev` / `epx serve` | 使用工程 `dev`、`serve` 或 `start` 脚本启动服务 |
+| `epx build` | 使用工程的构建脚本；只有 `build:lib` 的产品自动构建产品库 |
+| `epx lib` / `epx build --lib` | 优先产品 `build:lib` / `lib`，平台使用完整 `build:component`；识别旧 `--target lib` 构建脚本 |
+| `epx lib --lazy` | 优先 `build:lib:lazy`，否则为产品库脚本设置 `LAZY_LIB=true`；工程需支持按需构建 |
+| `epx preview` | 使用 `preview` / `vite:preview`；没有脚本时使用工程本地 Vite |
+| `epx create` | 无参数进入创建引导，也可用参数直接创建 |
+| `epx migrate` / `epx upgrade` | 无参数引导：目标版本、迁移范围、预览、确认应用 |
+| `epx skill install` | 安装技能，支持自定义目录和明确覆盖 |
+| `epx scan` / `epx verify` | 迁移风险扫描 / 本地与线上组件清单校验 |
+| `epx lint [--fix]` / `epx circular` | 执行工程已有的代码检查、循环依赖检查脚本 |
+| `epx remote` / `epx pkg <包名\|all>` | 使用平台已有 `build:remote` / `build:pkg` / `build:pkgs` 脚本 |
+| `epx help` / `epx --version` | 帮助 / 工具版本 |
+
+工程命令支持 `--dir <目录>`，默认从当前目录向上找到最近的 `package.json`；不会改为 CLI 全局安装目录。没有项目脚本时，dev/build/preview 可使用项目已安装的 Vite，不会自动下载构建工具。工程仍需先安装自身依赖。
+
+`--mode/-m`、`--port/-p` 支持旧的 `-mprd`、`-p3000` 写法。build 优先匹配 `build:<mode>`；`localize` 也匹配 `build:local`，其余情况向构建脚本传入 `--mode`。平台 `build:component` 包含多步构建，不追加 `--mode`，环境由工程脚本统一配置。
+
+平台 `epx build` 保留 `--thin`、`--no-designer`、`--no-dashboard`；产品工程不接受平台裁剪选项。需向工程脚本透传其他参数时使用 `--`，如 `epx dev -- --host 0.0.0.0`。脚本原有的 pre/post 生命周期、自定义环境和多步构建会保留，失败退出码向上传递。
+
+`create` 和 `migrate --apply` 自动写入 `runtime: "vue3"`。带参数直接调用时 `--epx-frame` 必填，交互引导也会要求输入目标平台。迁移默认预览；apply 要求目标 Git 工作树干净。实际执行 `.vue` 转换时才按需安装并缓存 gogocode。标识表示迁移目标，仍需完成转换、构建和业务复测。
+
+`epx scan <目录>` 扫描静态风险，`epx verify <目录> --online <地址|文件>` 对照组件清单。技能安装到 `.claude/skills/epxing-frontend-vue3-migrate/`，可用 `--skills-dir` 指定其他客户端要求的位置。已有技能默认不覆盖；确认替换使用 `--force`。平台基类源码分析仍需准备对应版本源码或文档。
+
+在框架源码仓库发布工具，不需要构建平台 `lib/`：
+
+```powershell
+cd frontend/frame/packages/cli
+npm login --registry https://registry.npmjs.org/
+# 发布前调整为未发布过的新版本
+# npm version <新的CLI版本> --no-git-tag-version
+$previousPublicPublish = $env:EPX_PUBLISH_PUBLIC
+try {
+  $env:EPX_PUBLISH_PUBLIC = '1'
+  npm publish --access public --registry https://registry.npmjs.org/
+} finally {
+  $env:EPX_PUBLISH_PUBLIC = $previousPublicPublish
+}
+```
+
+发布账号需要拥有 `@epxing` 名称空间的发布权限，并完成 npm 要求的发布身份验证。`publishConfig` 固定公开发布到 npm 公网；上面的命令仅为这次操作启用共享守卫的显式公开发布开关，并在结束后恢复原值。`prepack` 自动构建工具并带入当前技能文件。可在框架根执行 `pnpm build:cli`，或在这里运行 `npm pack` 生成可独立安装的 tgz。技能与 CLI 同版本交付，平台升级不要求工具同步发版；工具规则、模板或技能更新时才发布新 CLI。新平台若改变接口或构建约定，仍需验证并更新相应工具规则。
+
+在框架根运行 `npm --prefix packages/cli test`，验证真实 tgz 的离线安装、无平台依赖运行、创建、迁移、扫描和技能安装。
+
+首次发布前，需创建或加入 npm 的 `epxing` 组织。可用 `npm org ls epxing --json --registry https://registry.npmjs.org/` 核对组织角色。若发布返回 `403 Two-factor authentication or granular access token with bypass 2fa enabled is required`，表示当前发布凭据未满足 npm 要求；仅 `npm whoami` 成功不代表可以发布。可在 npm 网站创建具有目标 scope 发布权限、启用 `Bypass 2FA` 的细粒度令牌，并配置到本机用户 npm 设置；令牌不写入项目或发布包。参见 [npm 发布身份验证要求](https://docs.npmjs.com/requiring-2fa-for-package-publishing-and-settings-modification/)。
+
+令牌的 `Packages and scopes` 权限应选择 `Read and write (publish and stage)`，范围覆盖 `@epxing`；`Read and write (stage only)` 无法直接发布。`Organizations` 里的读写权限只管理组织、团队和成员，不授予组织包的发布权限。首次创建包时需覆盖相应 scope。参见 [npm 令牌权限说明](https://docs.npmjs.com/creating-and-viewing-access-tokens/)。

package/dist/THIRD_PARTY_NOTICES.txt

@@ -0,0 +1,21 @@
+@babel/parser 7.29.3
+
+Copyright (C) 2012-2014 by various contributors (see AUTHORS)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/dist/cli.mjs

@@ -0,0 +1,230 @@
+#!/usr/bin/env node
+/* eslint-disable no-console -- CLI 输出 */
+import fs from 'node:fs'
+import path from 'node:path'
+import { spawnSync } from 'node:child_process'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { findProject, runProject } from './project.mjs'
+import { Prompts } from './prompts.mjs'
+
+const packageRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..')
+const payload = path.join(packageRoot, 'dist')
+const skillName = 'epxing-frontend-vue3-migrate'
+
+function takeOption (args, name) {
+  const index = args.findIndex(arg => arg === name || arg.startsWith(name + '='))
+  if (index < 0) return null
+  const arg = args[index]
+  if (arg.startsWith(name + '=')) {
+    args.splice(index, 1)
+    const value = arg.slice(name.length + 1)
+    if (!value) throw new Error(`${name} 缺少值`)
+    return value
+  }
+  const value = args[index + 1]
+  if (!value || value.startsWith('--')) throw new Error(`${name} 缺少值`)
+  args.splice(index, 2)
+  return value
+}
+
+function requireTarget (args) {
+  const target = takeOption(args, '--epx-frame')
+  if (!target) throw new Error('请用 --epx-frame 指定目标平台版本或包 spec；CLI 版本不作为平台版本。')
+  return target
+}
+
+function runTool (script, args, cwd) {
+  const result = spawnSync(process.execPath, [path.join(payload, 'tools', script), ...args], { cwd, stdio: 'inherit' })
+  if (result.error) throw result.error
+  return result.status ?? 1
+}
+
+function installSkill (args, cwd) {
+  const dir = path.resolve(cwd, takeOption(args, '--dir') || '.')
+  const custom = takeOption(args, '--skills-dir')
+  const force = args.includes('--force')
+  const unknown = args.filter(arg => arg !== '--force')
+  if (unknown.length) throw new Error(`不支持的参数：${unknown.join(' ')}`)
+  const dest = path.join(custom ? path.resolve(dir, custom) : path.join(dir, '.claude/skills'), skillName)
+  const files = ['SKILL.md', 'pitfalls.md']
+  if (!force && files.some(file => fs.existsSync(path.join(dest, file)))) {
+    throw new Error(`技能已存在：${dest}。如需替换，核对自定义内容后使用 --force。`)
+  }
+  // 先读齐资源，再写入，避免缺少发布资源时只安装一半。
+  const contents = files.map(file => fs.readFileSync(path.join(payload, 'skills', skillName, file)))
+  fs.mkdirSync(dest, { recursive: true })
+  files.forEach((file, index) => fs.writeFileSync(path.join(dest, file), contents[index]))
+  console.log(`✓ 已安装技能：${dest}`)
+  return 0
+}
+
+async function interactive (cwd, action) {
+  const prompts = new Prompts()
+  const dispatch = argv => { prompts.close(); return main(argv, cwd) }
+  const choices = pairs => pairs.map(([label, value]) => ({ label, value }))
+  const mode = async () => {
+    const value = await prompts.select('环境模式', choices([
+      ['使用工程默认环境', ''], ['dev', 'dev'], ['pre', 'pre'], ['ppe', 'ppe'], ['prd', 'prd'],
+      ['localize', 'localize'], ['development', 'development'], ['production', 'production'], ['输入其他模式', '*']
+    ]))
+    return value === '*' ? prompts.required('模式名称') : value
+  }
+  try {
+    console.log('@epxing/cli · 当前目录：' + cwd)
+    if (!action) {
+      action = await prompts.select('选择操作', choices([
+        ['dev      启动开发服务', 'dev'], ['build    工程打包', 'build'], ['lib      产品库 / 平台组件库打包', 'lib'],
+        ['preview  预览构建结果', 'preview'], ['create   创建产品 / 项目', 'create'], ['migrate  升级到 Vue 3', 'migrate'],
+        ['skill    安装升级技能', 'skill'], ['check    风险扫描 / 组件校验 / 代码检查', 'check'],
+        ['advanced 平台独立包 / 远程模块构建', 'advanced'], ['help     查看命令帮助', 'help'], ['exit     退出', 'exit']
+      ]))
+    }
+    if (action === 'exit') return 0
+    if (action === 'help') return dispatch(['help'])
+    if (action === 'create') {
+      const name = await prompts.required('产品名或目标路径')
+      const target = await prompts.required('目标 epx-frame 版本或包 spec')
+      const dir = await prompts.text('生成目录', name)
+      return dispatch(['create', name, '--dir', dir, '--epx-frame', target])
+    }
+    if (action === 'migrate') {
+      const dir = await prompts.required('待升级工程目录', '.')
+      const target = await prompts.required('目标 epx-frame 版本或包 spec')
+      const flags = await prompts.select('迁移范围', choices([
+        ['依赖与入口迁移', []], ['依赖、入口与 Vue 组件转换', ['--transform-vue']],
+        ['依赖、Vue 组件及 Vite 构建迁移', ['--transform-vue', '--to-vite']]
+      ]))
+      const args = ['migrate', dir, '--epx-frame', target, ...flags]
+      const preview = await main(args, cwd)
+      if (preview !== 0 || !(await prompts.confirm('应用以上迁移？要求 Git 工作树干净；默认不修改'))) return preview
+      return dispatch([...args, '--apply'])
+    }
+    if (action === 'skill') {
+      const dir = await prompts.required('安装到哪个项目', '.')
+      const location = await prompts.required('项目中的技能目录', '.claude/skills')
+      const dest = path.resolve(cwd, dir, location, skillName)
+      const args = ['skill', 'install', '--dir', dir, '--skills-dir', location]
+      if (['SKILL.md', 'pitfalls.md'].some(file => fs.existsSync(path.join(dest, file)))) {
+        if (!(await prompts.confirm(`技能已存在，替换 ${dest} 中的两个技能文件？`))) return 0
+        args.push('--force')
+      }
+      return dispatch(args)
+    }
+    if (action === 'check') {
+      action = await prompts.select('检查类型', choices([
+        ['源码迁移风险扫描', 'scan'], ['本地 / 线上组件清单核对', 'verify'], ['项目代码检查', 'lint'], ['项目循环依赖检查', 'circular']
+      ]))
+    }
+    if (action === 'advanced') {
+      action = await prompts.select('平台构建', choices([
+        ['business 远程模块', 'remote'], ['独立组件包', 'pkg']
+      ]))
+    }
+    const dir = await prompts.required('工程目录', '.')
+    if (action === 'scan' || action === 'verify') {
+      const online = action === 'verify' ? await prompts.text('线上 JS 地址或文件（留空仅列本地组件）') : ''
+      return dispatch([action, dir, ...(online ? ['--online', online] : [])])
+    }
+    const args = [action, '--dir', dir]
+    const project = findProject(path.resolve(cwd, dir))
+    const platformLib = action === 'lib' && project.scripts['build:component'] && !project.scripts['build:lib'] && !project.scripts.lib
+    if (['dev', 'build', 'lib', 'preview'].includes(action) && !platformLib) {
+      const selectedMode = await mode()
+      if (selectedMode) args.push('--mode', selectedMode)
+    }
+    if (action === 'dev' || action === 'preview') {
+      const port = await prompts.text('端口（留空使用工程默认值）')
+      if (port) args.push('--port', port)
+    }
+    if (action === 'build') {
+      if (project.pkg.name === 'epx-frame' || project.scripts['build:component']) {
+        if (await prompts.confirm('将 business 拆为远程模块，构建瘦平台？')) args.push('--thin')
+        if (await prompts.confirm('裁剪页面设计器？')) args.push('--no-designer')
+        if (await prompts.confirm('裁剪看板？')) args.push('--no-dashboard')
+      }
+    }
+    if (action === 'lib') {
+      if ((project.scripts['build:lib'] || project.scripts.lib) && await prompts.confirm('构建按需产品库？')) args.push('--lazy')
+    }
+    if (action === 'pkg') args.push(await prompts.required('包名或 all', 'all'))
+    if (action === 'lint' && await prompts.confirm('自动修复代码？')) args.push('--fix')
+    return dispatch(args)
+  } finally { prompts.close() }
+}
+
+export async function main (argv = process.argv.slice(2), cwd = process.env.INIT_CWD || process.cwd()) {
+  let [command, ...args] = argv
+  if (command === 'serve') command = 'dev'
+  if (command === 'upgrade') command = 'migrate'
+  const separator = args.indexOf('--')
+  if (args.slice(0, separator < 0 ? args.length : separator).some(arg => arg === '--help' || arg === '-h')) return main(['help'], cwd)
+  if (!command || command === 'menu') return interactive(cwd)
+  if (['create', 'migrate'].includes(command) && !args.length) return interactive(cwd, command)
+  if (['dev', 'build', 'lib', 'preview', 'remote', 'pkg', 'lint', 'circular'].includes(command)) return runProject(command, args, cwd)
+  if (['help', '--help', '-h'].includes(command)) {
+    console.log(`@epxing/cli · 工程开发与升级工具（独立于平台版本）
+
+  epx / epx menu             交互菜单（↑↓ + Enter；管道支持数字输入）
+  epx dev [-m <模式>] [-p <端口>] [--dir <工程目录>]
+  epx build [-m <模式>] [--thin] [--no-designer] [--no-dashboard] [--dir <目录>]
+  epx lib [--lazy] [-m <模式>] [--dir <目录>]  产品 build:lib / 平台 build:component
+  epx build --lib            同 epx lib
+  epx preview [-p <端口>] [--dir <目录>]
+  epx create <名称|路径> --epx-frame <目标版本> [--dir <目录>]
+  epx migrate [项目目录] --epx-frame <目标版本> [--apply] [--transform-vue] [--to-vite]
+  epx scan [项目目录]
+  epx verify [项目目录] [--online <线上JS地址|文件>]
+  epx skill install [--dir <项目目录>] [--skills-dir <技能目录>] [--force]
+  epx lint [--fix] [--dir <目录>]
+  epx circular [--dir <目录>]
+  epx remote [--dir <平台目录>]
+  epx pkg <包名|all> [--dir <平台目录>]
+  epx --version
+
+dev / build / lib 等执行当前工程的 package.json 脚本，使用工程本地依赖。
+工程命令可用 -- 后的参数透传给脚本；serve / upgrade 分别是 dev / migrate 的别名。
+create、migrate 不带参数时进入引导；直接带参数时 --epx-frame 必填。
+创建和升级自动写入 runtime: "vue3"。迁移默认 dry-run，--apply 才落盘。
+工具不会自动安装平台依赖；.vue 转换工具仅在执行 --apply --transform-vue 时下载并缓存。`)
+    return 0
+  }
+  if (['--version', '-v', 'version'].includes(command)) {
+    console.log(JSON.parse(fs.readFileSync(path.join(packageRoot, 'package.json'), 'utf8')).version)
+    return 0
+  }
+  if (command === 'skill') {
+    if (args.shift() !== 'install') throw new Error('用法：epx skill install [--dir <项目目录>]')
+    return installSkill(args, cwd)
+  }
+  if (command === 'create') {
+    const target = requireTarget(args)
+    const chosenDir = takeOption(args, '--dir')
+    const nameOrPath = args.shift()
+    if (!nameOrPath || args.length || nameOrPath.startsWith('-')) throw new Error('用法：epx create <名称|路径> --epx-frame <目标版本> [--dir <目录>]')
+    const dir = path.resolve(cwd, chosenDir || nameOrPath)
+    const name = /[\\/]/.test(nameOrPath) ? path.basename(path.resolve(cwd, nameOrPath)) : nameOrPath
+    const { scaffold } = await import(pathToFileURL(path.join(payload, 'tools/epx-create/scaffold.mjs')).href)
+    scaffold({ name, dir, epxFrameSpec: target })
+    return 0
+  }
+  if (command === 'migrate') {
+    const target = requireTarget(args)
+    const dirs = args.filter(arg => !arg.startsWith('-'))
+    if (dirs.length > 1) throw new Error('一次迁移一个项目目录')
+    const dir = dirs[0] || '.'
+    return runTool('epx-migrate/migrate.mjs', [path.resolve(cwd, dir), ...args.filter(arg => arg !== dir), '--epx-frame', target], cwd)
+  }
+  if (command === 'scan' || command === 'verify') {
+    const online = command === 'verify' ? takeOption(args, '--online') : null
+    if (args.length > 1 || args.some(arg => arg.startsWith('-'))) throw new Error(`用法：epx ${command} [项目目录]${command === 'verify' ? ' [--online <地址|文件>]' : ''}`)
+    const script = command === 'scan' ? 'detect-vue3-risks.mjs' : 'verify-components.mjs'
+    return runTool('epx-migrate/' + script, [path.resolve(cwd, args[0] || '.'), ...(online ? ['--online', online] : [])], cwd)
+  }
+  throw new Error(`未知命令：${command}，运行 epx help 查看用法。`)
+}
+
+let isMain = false
+try { isMain = !!process.argv[1] && fs.realpathSync(process.argv[1]) === fileURLToPath(import.meta.url) } catch (error) { /* 作为模块导入 */ }
+if (isMain) {
+  main().then(status => { process.exitCode = status }).catch(error => { console.error('✗ ' + error.message); process.exitCode = error.exitCode || 1 })
+}

package/dist/project.mjs

@@ -0,0 +1,178 @@
+/* eslint-disable no-console -- 输出项目命令 */
+import fs from 'node:fs'
+import path from 'node:path'
+import { createRequire } from 'node:module'
+import { spawn } from 'node:child_process'
+
+export function findProject (cwd) {
+  let dir = path.resolve(cwd)
+  if (!fs.existsSync(dir) || !fs.statSync(dir).isDirectory()) throw new Error(`工程目录不存在：${dir}`)
+  while (true) {
+    const file = path.join(dir, 'package.json')
+    if (fs.existsSync(file)) {
+      const pkg = JSON.parse(fs.readFileSync(file, 'utf8'))
+      return { dir, pkg, scripts: pkg.scripts || {} }
+    }
+    const parent = path.dirname(dir)
+    if (parent === dir) throw new Error(`未找到项目 package.json：${cwd}。请进入项目目录，或指定 --dir。`)
+    dir = parent
+  }
+}
+
+function npmEntry () {
+  const nodeDir = path.dirname(process.execPath)
+  const roots = [nodeDir, ...String(process.env.PATH || process.env.Path || '').split(path.delimiter)]
+  const candidates = [process.env.npm_execpath && /npm-cli\.js$/.test(process.env.npm_execpath) ? process.env.npm_execpath : null]
+  for (const dir of roots) {
+    if (!dir) continue
+    candidates.push(path.join(dir, 'node_modules/npm/bin/npm-cli.js'), path.resolve(dir, '../lib/node_modules/npm/bin/npm-cli.js'))
+    const executable = path.join(dir, 'npm')
+    try {
+      const real = fs.realpathSync(executable)
+      if (real.endsWith('.js')) candidates.push(real)
+    } catch (error) { /* 继续查找 */ }
+  }
+  const found = candidates.find(file => file && fs.existsSync(file))
+  if (!found) throw new Error('未找到 npm-cli.js。请使用带 npm 的 Node.js 环境运行 epx。')
+  return found
+}
+
+function execute (file, args, cwd, extraEnv) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(process.execPath, [file, ...args], { cwd, stdio: 'inherit', env: { ...process.env, ...extraEnv } })
+    const interrupt = () => child.kill('SIGINT')
+    const terminate = () => child.kill('SIGTERM')
+    const cleanup = () => {
+      process.removeListener('SIGINT', interrupt)
+      process.removeListener('SIGTERM', terminate)
+    }
+    process.on('SIGINT', interrupt)
+    process.on('SIGTERM', terminate)
+    child.once('error', error => { cleanup(); reject(error) })
+    child.once('exit', (code, signal) => { cleanup(); resolve(code ?? (signal === 'SIGINT' ? 130 : signal === 'SIGTERM' ? 143 : 1)) })
+  })
+}
+
+function localBinary (project, name) {
+  const require = createRequire(path.join(project.dir, 'package.json'))
+  try {
+    const manifest = require.resolve(name + '/package.json')
+    const pkg = JSON.parse(fs.readFileSync(manifest, 'utf8'))
+    const bin = typeof pkg.bin === 'string' ? pkg.bin : pkg.bin?.[name]
+    const file = bin && path.resolve(path.dirname(manifest), bin)
+    if (file && fs.existsSync(file)) return file
+  } catch (error) { /* 由调用方提示项目安装依赖 */ }
+  return null
+}
+
+function takeValue (args, flag, short) {
+  const index = args.findIndex(arg => arg === flag || arg.startsWith(flag + '=') || (short && (arg === short || arg.startsWith(short))))
+  if (index < 0) return null
+  const arg = args[index]
+  let value
+  if (arg.startsWith(flag + '=')) { value = arg.slice(flag.length + 1); args.splice(index, 1) } else if (short && arg.startsWith(short) && arg !== short) { value = arg.slice(short.length); args.splice(index, 1) } else {
+    value = args[index + 1]
+    if (!value || value.startsWith('-')) throw new Error(`${flag} 缺少值`)
+    args.splice(index, 2)
+  }
+  if (!value) throw new Error(`${flag} 缺少值`)
+  return value
+}
+
+export function parseProjectArgs (argv) {
+  const args = [...argv]
+  const separator = args.indexOf('--')
+  const forward = separator >= 0 ? args.splice(separator).slice(1) : []
+  const flag = name => { const index = args.indexOf(name); if (index < 0) return false; args.splice(index, 1); return true }
+  const result = {
+    dir: takeValue(args, '--dir'),
+    mode: takeValue(args, '--mode', '-m'),
+    port: takeValue(args, '--port', '-p'),
+    thin: flag('--thin'),
+    noDesigner: flag('--no-designer'),
+    noDashboard: flag('--no-dashboard'),
+    lazy: flag('--lazy'),
+    lib: flag('--lib'),
+    fix: flag('--fix'),
+    forward,
+    positional: args
+  }
+  if (result.mode && !/^[A-Za-z0-9][A-Za-z0-9_.-]*$/.test(result.mode)) throw new Error('mode 仅支持字母、数字、点、下划线和短横线')
+  if (result.port && (!/^\d+$/.test(result.port) || +result.port < 1 || +result.port > 65535)) throw new Error('端口需为 1–65535 的整数')
+  return result
+}
+
+export function projectPlan (command, options, project) {
+  const { scripts } = project
+  const pick = (...names) => names.find(name => name && typeof scripts[name] === 'string' && scripts[name].trim())
+  const args = []
+  const env = {}
+  let script
+  let binary
+  const platform = project.pkg.name === 'epx-frame' || !!scripts['build:component']
+  if (options.lib) {
+    if (command !== 'build') throw new Error('--lib 用于 epx build；也可直接使用 epx lib')
+    command = 'lib'
+  }
+  if (options.positional.length && !(command === 'pkg' && options.positional.length === 1 && !options.positional[0].startsWith('-'))) throw new Error(`不支持的参数：${options.positional.join(' ')}`)
+  if (options.port && !['dev', 'preview'].includes(command)) throw new Error('--port 仅用于 dev 或 preview')
+  if (options.lazy && command !== 'lib') throw new Error('--lazy 仅用于 lib 或 build --lib')
+  if (options.fix && command !== 'lint') throw new Error('--fix 仅用于 lint')
+  if ((options.thin || options.noDesigner || options.noDashboard) && (command !== 'build' || !platform)) throw new Error('平台裁剪选项仅用于平台源码中的 epx build')
+  if (options.mode && !['dev', 'build', 'lib', 'preview'].includes(command)) throw new Error('--mode 仅用于 dev、build、lib 或 preview')
+  if (command === 'dev') {
+    script = pick('dev', 'serve', 'start')
+    if (!script) binary = 'vite'
+  } else if (command === 'build') {
+    const modeScript = options.mode && pick('build:' + options.mode, options.mode === 'localize' && 'build:local')
+    script = modeScript || pick('build', 'build:lib')
+    if (!script) binary = 'vite'
+    if (modeScript) options = { ...options, mode: null }
+    if (options.thin) env.EXTERNALIZE_BUSINESS = 'true'
+    if (options.noDesigner) env.INCLUDE_DESIGNER = 'false'
+    if (options.noDashboard) env.INCLUDE_DASHBOARD = 'false'
+  } else if (command === 'lib') {
+    script = options.lazy ? pick('build:lib:lazy') : pick('build:lib', 'lib', 'build:component')
+    if (options.lazy && !script) {
+      script = pick('build:lib', 'lib')
+      env.LAZY_LIB = 'true'
+    }
+    if (!script && !options.lazy && /--target(?:=|\s+)lib\b/.test(scripts.build || '')) script = 'build'
+    if (!script) throw new Error('当前工程缺少库构建脚本。产品请提供 build:lib（按需库可用 build:lib:lazy），平台使用 build:component。')
+    if (script === 'build:component' && options.mode) throw new Error('平台聚合库包含多步构建，请在 build:component 中配置环境；epx lib 不向该聚合脚本追加 --mode。')
+  } else if (command === 'preview') {
+    script = pick('preview', 'vite:preview')
+    if (!script) binary = 'vite'
+  } else if (command === 'remote') script = pick('build:remote')
+  else if (command === 'pkg') {
+    const name = options.positional[0]
+    if (!name || !/^[a-z][a-z0-9-]*$/.test(name)) throw new Error('用法：epx pkg <包名|all> [--dir <平台目录>]')
+    script = name === 'all' ? pick('build:pkgs') : pick('build:pkg')
+    if (name !== 'all') env.PKG = name
+  } else if (command === 'lint') {
+    script = options.fix ? pick('lint:fix', 'lint') : pick('lint')
+    if (options.fix && script !== 'lint:fix') args.push('--fix')
+  } else if (command === 'circular') script = pick('circular')
+  if (!script && !binary) throw new Error(`当前工程未提供 ${command} 对应的 package.json 脚本`)
+  if (options.mode) args.push('--mode', options.mode)
+  if (options.port) args.push('--port', options.port)
+  args.push(...options.forward)
+  if (['build', 'lib', 'remote', 'pkg'].includes(command) && !process.env.NODE_OPTIONS) env.NODE_OPTIONS = '--max-old-space-size=8192'
+  return { command, script, binary, args, env }
+}
+
+export async function runProject (command, argv, cwd) {
+  const options = parseProjectArgs(argv)
+  const project = findProject(options.dir ? path.resolve(cwd, options.dir) : cwd)
+  const plan = projectPlan(command, options, project)
+  console.log(`项目：${project.pkg.name || project.dir}（${project.dir}）`)
+  if (plan.script) {
+    console.log(`→ npm run ${plan.script}${plan.args.length ? ' -- ' + plan.args.join(' ') : ''}`)
+    return execute(npmEntry(), ['run', plan.script, ...(plan.args.length ? ['--', ...plan.args] : [])], project.dir, plan.env)
+  }
+  const file = localBinary(project, plan.binary)
+  if (!file) throw new Error(`当前工程没有可用脚本或本地 ${plan.binary}，请先在工程内安装依赖并配置相应脚本。`)
+  const args = [...(command === 'dev' ? [] : [command]), ...plan.args]
+  console.log(`→ 本地 ${plan.binary} ${args.join(' ')}`)
+  return execute(file, args, project.dir, plan.env)
+}

package/dist/prompts.mjs

@@ -0,0 +1,86 @@
+import readline from 'node:readline'
+
+export class Cancelled extends Error {
+  constructor () { super('已取消'); this.exitCode = 130 }
+}
+
+// 非 TTY 共用一个输入队列，避免多步问答丢掉管道中提前到达的行。
+export class Prompts {
+  constructor (input = process.stdin, output = process.stdout) {
+    this.input = input
+    this.output = output
+    this.tty = !!(input.isTTY && output.isTTY && typeof input.setRawMode === 'function')
+    this.lines = []
+    this.closed = false
+    if (!this.tty) {
+      this.rl = readline.createInterface({ input, terminal: false })
+      this.rl.on('line', line => {
+        if (this.pending) { const pending = this.pending; this.pending = null; pending.resolve(line) } else this.lines.push(line)
+      })
+      this.rl.on('close', () => { this.closed = true; if (this.pending) { this.pending.reject(new Cancelled()); this.pending = null } })
+    }
+  }
+
+  close () { this.rl?.close() }
+
+  line () {
+    if (this.lines.length) return Promise.resolve(this.lines.shift())
+    if (this.closed) return Promise.reject(new Cancelled())
+    return new Promise((resolve, reject) => { this.pending = { resolve, reject } })
+  }
+
+  async text (question, defaultValue = '') {
+    const prompt = question + (defaultValue ? `（回车用 ${defaultValue}）` : '') + '：'
+    let answer
+    if (!this.tty) { this.output.write(prompt); answer = await this.line() } else {
+      answer = await new Promise((resolve, reject) => {
+        let settled = false
+        const rl = readline.createInterface({ input: this.input, output: this.output })
+        rl.once('close', () => { if (!settled) reject(new Cancelled()) })
+        rl.once('SIGINT', () => { settled = true; rl.close(); reject(new Cancelled()) })
+        rl.question(prompt, value => { settled = true; rl.close(); resolve(value) })
+      })
+    }
+    return answer.trim() || defaultValue
+  }
+
+  async required (question, defaultValue = '') {
+    while (true) { const value = await this.text(question, defaultValue); if (value) return value; this.output.write('此项不能为空。\n') }
+  }
+
+  async select (question, choices) {
+    if (!this.tty) {
+      this.output.write(question + '\n' + choices.map((choice, index) => `  ${index + 1}) ${choice.label}`).join('\n') + '\n')
+      while (true) {
+        const answer = await this.text('输入序号', '1')
+        if (/^\d+$/.test(answer) && choices[+answer - 1]) return choices[+answer - 1].value
+        this.output.write('请选择有效序号。\n')
+      }
+    }
+    return new Promise((resolve, reject) => {
+      let index = 0
+      let drawn = false
+      const draw = () => {
+        if (drawn) this.output.write(`\x1b[${choices.length + 1}A\x1b[0J`)
+        this.output.write(question + '（↑↓ 选择，Enter 确认，Esc 取消）\n')
+        choices.forEach((choice, i) => this.output.write(i === index ? `\x1b[36m❯ ${choice.label}\x1b[0m\n` : `  ${choice.label}\n`))
+        drawn = true
+      }
+      const cleanup = () => { this.input.removeListener('keypress', onKey); this.input.setRawMode(false); this.input.pause() }
+      const onKey = (text, key) => {
+        if (!key) return
+        if (key.name === 'up' || key.name === 'k') { index = (index - 1 + choices.length) % choices.length; draw() } else if (key.name === 'down' || key.name === 'j') { index = (index + 1) % choices.length; draw() } else if (key.name === 'return' || key.name === 'enter') { cleanup(); resolve(choices[index].value) } else if (key.name === 'escape' || (key.ctrl && key.name === 'c')) { cleanup(); this.output.write('\n'); reject(new Cancelled()) }
+      }
+      readline.emitKeypressEvents(this.input)
+      this.input.setRawMode(true)
+      this.input.resume()
+      this.input.on('keypress', onKey)
+      draw()
+    })
+  }
+
+  confirm (question, defaultValue = false) {
+    const choices = [{ label: '否', value: false }, { label: '是', value: true }]
+    return this.select(question, defaultValue ? choices.reverse() : choices)
+  }
+}