npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@composy/cli

v0.0.2

Published

Unified command line entry and tool router for the LDesign workspace

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 解析工具,开发态可回退到 monorepo tools/*
  • 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. 项目级高层命令

这些命令面向“我要完成一个工作流”:

  • init
  • build
  • dev
  • preview
  • deploy
  • test

说明:

  • 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 --coverage

2. 工具聚合命令

这些命令面向“我要看当前有哪些工具已经接入”:

  • doctor
  • tools

示例:

ldesign doctor --quick
ldesign doctor --ensure
ldesign tools list
ldesign tools matrix --json
ldesign tools run benchmark -- --help

tools list 与 tools matrix 会区分三种状态:

  • implemented:包或 helper 已经可以解析并执行
  • planned:能力已经登记到目录,但实现尚未完成
  • missing / unavailable:目录中存在记录,但当前环境无法解析对应包

Workbench 会明确出现在这个清单中:

ldesign tools workbench

在 tools/workbench 完成实现之前,该命令只返回 planned 状态说明,CLI 不会尝试执行不存在的包。

3. helper 型命令

这些命令把库能力包装成统一 CLI:

  • config
  • kit
  • monitor
  • node
  • project
  • runtime
  • tool-server
  • tool-ui
  • vscode

说明:

  • 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 check

4. 工具包代理命令

大多数已接入的 tools/* bin 包都可以直接通过 ldesign <tool> 调用,例如:

  • api
  • benchmark
  • builder
  • changelog
  • deps
  • docs
  • env
  • format
  • git
  • icons
  • launcher
  • mock
  • performance
  • release
  • security
  • translator
  • tsup
  • webfont
  • workspace

实际接入状态请以:

ldesign tools list
ldesign tools matrix

兼容别名仍然保留,但它们不是独立的工具包:

  • ldesign publisher 作为 release 别名转发到 @composy/release
  • ldesign submodule ... 转发到 @composy/git submodule ...

为准。

配置文件

CLI 默认会从当前工作目录搜索以下配置文件:

  • ldesign.config.ts
  • ldesign.config.mts
  • ldesign.config.js
  • ldesign.config.mjs
  • ldesign.config.cjs
  • ldesign.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 build

Lint 说明

本包使用 @antfu/eslint-config,但 lint 范围刻意收口到当前维护的源码与核心配置文件:

  • src/**
  • bin/**
  • .ldesign/pack.config.ts
  • .ldesign/eslint.config.js
  • eslint.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.js
  • dist/index.cjs
  • dist/index.d.ts
  • dist/commands/*.js
  • dist/core/*.d.ts
  • dist/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 确认所有包接入状态,再按需调用对应子命令。