@composy/cli
v0.0.2
Published
Unified command line entry and tool router for the LDesign workspace
Maintainers
Readme
@composy/cli
@composy/cli 是 LDesign 工作区的统一命令行入口。它既提供 init、build、dev、doctor、tools
这类高层命令,也负责把 tools/* 中已经接入的 bin 工具和 helper 型库能力汇总到同一个 ldesign
命令下。
当前包的定位很明确:
- 作为用户面向的统一 CLI 入口
- 作为
tools/*包的命令分发与诊断层 - 作为
tools/cli自身的类型化、可构建、可验证的 Node.js 包
核心能力
- 统一命令入口:通过
ldesign <command>调用高层工作流和下游工具 - 工具路由:优先从
node_modules解析工具,开发态可回退到 monorepotools/* - helper 集成:对
configmate、kit、monitor、runtime、tool-server、tool-ui等真实库入口提供一致的 CLI 外壳 - 诊断与巡检:通过
ldesign doctor、ldesign tools list、ldesign tools matrix检查接入状态 - 类型安全:核心配置、上下文、错误模型和工具解析逻辑都带有完整 TypeScript 类型
- 多产物构建:使用
@composy/pack基于src目录所有运行时代码生成 ESM、CJS 与.d.ts
安装
pnpm add -D @composy/cli在当前仓库中开发时:
cd tools/cli
pnpm install快速开始
pnpm run build
node ./bin/cli.js --help
node ./bin/cli.js tools list
node ./bin/cli.js doctor --quick如果是在业务项目里直接使用:
pnpm add -D @composy/cli
ldesign init
ldesign build
ldesign tools list命令分层
1. 项目级高层命令
这些命令面向“我要完成一个工作流”:
initbuilddevpreviewdeploytest
说明:
build与dev会根据项目特征自动选择@composy/launcher或@composy/builder- 可通过
--tool builder或--tool launcher强制指定下游工具 - 其它参数会继续透传给真实工具
示例:
ldesign init --type ts
ldesign build
ldesign build --tool builder
ldesign dev --tool launcher
ldesign preview
ldesign test --coverage2. 工具聚合命令
这些命令面向“我要看当前有哪些工具已经接入”:
doctortools
示例:
ldesign doctor --quick
ldesign doctor --ensure
ldesign tools list
ldesign tools matrix --json
ldesign tools run benchmark -- --helptools list 与 tools matrix 会区分三种状态:
implemented:包或 helper 已经可以解析并执行planned:能力已经登记到目录,但实现尚未完成missing/unavailable:目录中存在记录,但当前环境无法解析对应包
Workbench 会明确出现在这个清单中:
ldesign tools workbench在 tools/workbench 完成实现之前,该命令只返回 planned 状态说明,CLI 不会尝试执行不存在的包。
3. helper 型命令
这些命令把库能力包装成统一 CLI:
configkitmonitornodeprojectruntimetool-servertool-uivscode
说明:
config、kit、monitor、runtime、tool-server、tool-ui会参与tools list/doctor的 helper 集成巡检vscode通过 CLI adapter 接入,既可直接使用ldesign vscode ...,也可使用ldesign tools vscode ...,并会出现在工具矩阵中node、project仍是可选外部库适配,保留直接命令入口
示例:
ldesign config inspect --path logLevel
ldesign node env
ldesign project info --json
ldesign runtime check4. 工具包代理命令
大多数已接入的 tools/* bin 包都可以直接通过 ldesign <tool> 调用,例如:
apibenchmarkbuilderchangelogdepsdocsenvformatgiticonslaunchermockperformancereleasesecuritytranslatortsupwebfontworkspace
实际接入状态请以:
ldesign tools list
ldesign tools matrix兼容别名仍然保留,但它们不是独立的工具包:
ldesign publisher作为 release 别名转发到@composy/releaseldesign submodule ...转发到@composy/git submodule ...
为准。
配置文件
CLI 默认会从当前工作目录搜索以下配置文件:
ldesign.config.tsldesign.config.mtsldesign.config.jsldesign.config.mjsldesign.config.cjsldesign.config.json.ldesignrc.json.ldesignrc.js.ldesignrc.mjs.ldesignrc.cjs
也可以显式指定:
ldesign build --config-file ./ldesign.config.ts最小配置示例:
import { defineConfig } from '@composy/cli'
export default defineConfig({
logLevel: 'info',
build: {
mode: 'production',
sourcemap: true,
analyze: false
},
dev: {
port: 5173,
host: '127.0.0.1',
open: true,
https: false
}
})配置校验策略:
- 缺失配置文件时使用默认空配置
- 显式指定但文件不存在时直接报错
- 配置值类型不合法时直接报错,不再静默降级
全局选项
所有命令都支持以下顶层选项:
--debug
--verbose
--silent
--cwd <dir>
--config-file <file>说明:
--cwd会在命令执行前切换工作目录--config-file会以当前cwd为基准解析相对路径--verbose会额外打印命令加载统计和性能摘要
子进程取消与超时
命令代理内部统一通过 runCommand()
启动下游进程,默认不启用 shell,并保持原有 stdio 继承行为。需要控制长任务时可以传入 timeoutMs 或
AbortSignal:
import { runCommand } from '@composy/cli'
const controller = new AbortController()
const result = await runCommand('pnpm', ['build'], {
cwd: process.cwd(),
timeoutMs: 5 * 60 * 1000,
signal: controller.signal
})
if (result.timedOut || result.aborted) {
// 根据 result.timedOut / result.aborted 输出可脚本化诊断
}timeoutMs 必须是正整数;超时或取消会终止子进程并在结果中保留 timedOut / aborted 标记。通过
runTool() 调用下游工具时,这些标记也会进入
CommandError.details,便于 CI 和上层自动化区分普通退出失败、超时与主动取消。
本地开发
常用脚本
pnpm run dev
pnpm run build
pnpm run clean
pnpm run typecheck
pnpm run lint:check
pnpm run lint:fix
pnpm test质量门禁
当前包的基线流程为:
pnpm run typecheck
pnpm run lint:check
pnpm test
pnpm run buildLint 说明
本包使用 @antfu/eslint-config,但 lint 范围刻意收口到当前维护的源码与核心配置文件:
src/**bin/**.ldesign/pack.config.ts.ldesign/eslint.config.jseslint.config.js
@composy/pack、ESLint 与 TypeScript 的权威配置集中在 .ldesign/;根目录的 eslint.config.js 和
tsconfig.json 是供 CLI/IDE 自动发现的薄转发入口。TypeScript 根入口还锚定包内 rootDir,供 pack
声明生成使用。
历史文档、测试产物、脚本草稿和缓存不会进入 lint 基线。
构建说明
当前构建通过 @composy/pack 驱动,配置文件位于:
构建策略:
- 以
src下的运行时代码为 entry - 排除
src/__tests__/**、*.test.ts、*.spec.ts - 生成 ESM / CJS /
.d.ts - 保留
commands、core、types、utils的模块级产物
构建后可在 dist/ 中看到例如:
dist/index.jsdist/index.cjsdist/index.d.tsdist/commands/*.jsdist/core/*.d.tsdist/utils/*.d.ts
npm 发布内容还包含 bin/、双语 README、CHANGELOG 与 MIT LICENSE。发布前可运行
npm pack --dry-run --ignore-scripts 核对最终 payload。
目录结构
tools/cli/
├─ bin/ # CLI 启动入口
├─ docs/ # 说明文档与历史记录
├─ src/
│ ├─ commands/ # 命令实现与代理
│ ├─ core/ # 注册中心、上下文、工具目录
│ ├─ types/ # 对外配置与选项类型
│ ├─ utils/ # 错误、日志、配置加载、工具解析
│ └─ __tests__/ # 单元测试
├─ .ldesign/ # pack、ESLint、TypeScript / doc 等本包权威配置
├─ eslint.config.js # 指向 .ldesign/ 的 CLI/IDE 发现 shim
├─ tsconfig.json # 指向 .ldesign/ 并锚定包内 rootDir
├─ dist/ # 构建输出
└─ package.json当前实现重点
这次版本收口后的关键实现包括:
index.ts统一处理 bootstrap 参数、配置加载和命令注册config-loader.ts修复了“显式配置文件缺失却静默降级”的问题tool-runner.ts与library-loader.ts共用包解析基础设施,减少重复逻辑build.ts/dev.ts对--tool做显式校验,避免非法值悄悄回退到默认工具- 顶层工具包统一通过
@composy/pack构建;旧的包级builder.config.ts不再属于 tools 构建契约
文档入口
通过 @composy/cli 统一接入
当前包就是统一入口本体,建议在业务项目里直接使用以下命令:
pnpm add -D @composy/cli
ldesign --help
ldesign tools list
ldesign tools matrix --json
ldesign doctor --quick建议先用 ldesign tools matrix 确认所有包接入状态,再按需调用对应子命令。
