enableai-cli

enableai-cli 是一个面向多包（monorepo）前端/SDK工程的命令行工具，用于统一初始化工程模板、构建流程、类型产物、发布流程与发布策略。
它解决的核心问题是：把“每个仓库都要手工搭一遍”的工程化步骤标准化，减少重复劳动与人为错误。

适用场景：

• 多包仓库（如 packages/*）需要统一 build/clean/dts/release/publish 流程
• 团队需要一套可复用的 Rollup + TypeScript + ESLint + Prettier + Vitest 初始化模板
• 需要支持“默认 dry-run、可回滚、可重试”的发布机制

目录

• 项目简介
• 安装
• 快速开始
• 配置说明（enableai.config.ts）
• init 命令详解
• release 命令详解
• publish 子命令详解
• 脚本示例
• 注意事项与常见问题
• 示例目录结构与典型输出

项目简介

enableai-cli 提供以下核心能力：

• init：初始化或补齐工程配置（enableai.config.ts、Rollup模板、脚本、依赖等）
• info：输出当前工作区配置与包扫描结果
• clean：清理根目录及子包产物目录
• barrels：批量生成 barrel 文件（index.ts）
• build：基于 Rollup 批量构建子包
• dts：批量生成与打包 .d.ts
• release：版本规划、变更记录、构建校验、Git提交打标、推送与发布
• release publish：独立发布步骤（可单独重试）

安装

环境要求

• Node.js 建议 >= 20.19
• 包管理器：pnpm

1. 本地调试开发方式（pnpm link）

在 enableai-cli 源码仓库中：

pnpm install
pnpm link --global

在目标项目中：

pnpm link --global @enableai/cli
enableai-cli --help

2. pack 安装方式

在 enableai-cli 源码仓库中打包：

pnpm pack
# 生成类似：enableai-cli-0.0.2.tgz

在目标项目中安装本地 tgz：

pnpm add -D /绝对路径/enableai-cli-0.0.2.tgz
pnpm exec enableai-cli --help

3. devDependency 安装方式

pnpm add -D @enableai/cli
pnpm exec enableai-cli --help

也可直接写入 package.json 脚本后执行 pnpm run xxx。

快速开始

1. 初始化项目

pnpm exec enableai-cli init

init 会交互式询问是否初始化 TypeScript / ESLint / Vitest，并自动补齐常用脚本与依赖。

2. 查看当前工作区信息

pnpm exec enableai-cli info

3. 常用构建命令

CLI 命令：

pnpm exec enableai-cli clean
pnpm exec enableai-cli barrels
pnpm exec enableai-cli build
pnpm exec enableai-cli dts

典型 scripts（init 会自动补齐缺失项）：

{
  "scripts": {
    "clean": "enableai-cli clean",
    "barrels": "enableai-cli barrels",
    "build:core": "enableai-cli build",
    "build:dts": "enableai-cli dts",
    "build": "pnpm run barrels && pnpm run build:core && pnpm run build:dts",
  }
}

配置说明（enableai.config.ts）

推荐写法

import { defineConfig } from '@enableai/cli/config'

export default defineConfig({
  packagesDirs: ['packages'],
  orderKey: 'order',
  defaultOrder: 9999,
  clean: {
    dirs: ['dist', 'temp'],
    files: ['BUILD_ID'],
  },
  rollup: {
    configFile: 'rollup.config.js',
    dtsConfigFile: 'rollup.dts.config.js',
  },
  publish: {
    registry: [
      'http://nexus.enableai.cn/repository/npm-host/',
      'https://registry.npmjs.org/',
    ],
    flags: ['--no-git-checks'],
  },
  barrels: {
    entries: [
      {
        options: {
          directory: ['packages/core/src'],
          name: 'index.ts',
          noSemicolon: true,
          singleQuotes: true,
          noHeader: true,
        },
        importOrder: ['^react', '<THIRD_PARTY_MODULES>', '^[./]'],
      },
    ],
  },
})

字段含义（核心）

• packagesDirs：包扫描目录列表，默认 ["packages"]
• orderKey：读取子包 package.json 的排序字段，默认 "order"
• defaultOrder：未设置排序字段时的默认值，默认 9999
• clean.dirs：清理目录（根目录与每个包目录都会清理）
• clean.files：仅清理根目录中的文件
• rollup.configFile/dtsConfigFile：init 复制 Rollup 模板时使用的目标文件名
• publish.registry：可配置单个或多个 registry
• publish.flags：发布时附加参数数组（透传给 pnpm publish）
• barrels：barrelsby 配置（透传）

Rollup 配置如何定制

• 直接修改根目录下的 rollup.config.js 与 rollup.dts.config.js。
• 重新执行 init 时，Rollup模板会被强制覆盖，请注意保留你的自定义改动。
• build 与 dts 命令会按项目中的 Rollup 配置文件执行构建。

publish.registry 与 publish.flags

• publish.registry 支持字符串或字符串数组
• 数组模式会按顺序逐个 registry 发布
• publish.flags 是默认发布参数，运行时会与命令行 --publish-flag 合并

init 命令详解

init 的执行逻辑（缺失才补齐，已有尽量跳过）：

1. 创建 enableai.config.ts（若不存在）
2. 强制复制 Rollup 模板
3. 补充根 scripts（clean/barrels/build:core/build:dts/build/release/release:publish）
4. 补充 Rollup 相关 devDependencies
5. 初始化基础模板（.gitignore、.prettierrc）
6. 如果检测到 .prettierrc 引用了 @trivago/prettier-plugin-sort-imports，补齐该依赖
7. 交互式可选初始化 TypeScript
8. 交互式可选初始化 ESLint
9. 交互式可选初始化 Vitest
10. 写回 package.json

1) Rollup 模板复制

会覆盖以下模板到项目根目录（或你在 rollup 配置里指定的文件名）：

• rollup.config.js
• rollup.dts.config.js
• postcss.config.js
• scripts/inline-enums.js

2) tsconfig 初始化（可选）

选择后会复制：

• tsconfig.json
• tsconfig.build-browser.json
• tsconfig.build-node.json
• packages/base.d.ts
• packages/global.d.ts

并尝试把 compilerOptions.paths 中的 @enableai-sdk-common/* 修正为 @<当前包名>/*。

3) ESLint 初始化（可选）

• 若检测到已有 ESLint 配置，会自动跳过
• 否则可交互选择是否写入 eslint.config.js
• 自动补齐 ESLint 相关依赖与脚本（lint、lint:fix）

4) Prettier 初始化（.prettierrc + 插件）

• 默认复制 .prettierrc
• 若 .prettierrc 中使用了 @trivago/prettier-plugin-sort-imports，自动补齐依赖

5) Vitest 初始化（可选）

• 复制 vitest.config.ts
• 增加测试脚本：test/test:run/test:watch/test:coverage
• 增加测试依赖：vitest、@vitest/coverage-v8

6) scripts 自动补齐规则

• 仅补齐“缺失项”
• 已存在同名脚本会保留原值，不强制改写

7) devDependencies 自动补齐

• 仅补齐“缺失依赖”
• 已存在同名依赖版本不覆盖

release 命令详解

1. dry-run（默认）

pnpm exec enableai-cli release

默认只输出发布计划，不修改任何文件，不执行 git/publish。

2. --apply（真正执行）

pnpm exec enableai-cli release --apply --bump patch

执行阶段包括：

• 可选脚本检查（fix/test/typecheck）
• Git 工作区干净检查
• 更新 root + 子包版本号
• 自动生成或更新 CHANGELOG.md
• 执行 clean/build/dts
• git add -A、git commit、git tag、git push、git push --tags
• 自动发布（release publish）

3. 版本来源规则

• 指定 --version x.y.z[-pre]：优先使用
• 指定 --bump patch|minor|major|prerelease：按当前版本计算
• 都不指定：交互选择

4. 自动生成 CHANGELOG.md

命令内部调用：

conventional-changelog -p angular -i CHANGELOG.md -s

请确保项目可执行 conventional-changelog（建议作为 devDependency 安装）。

5. git commit/tag/push

• commit message：release: v<version>
• tag：v<version>
• 推送分支与 tags

6. 自动 publish（dist-tag 与 prerelease）

• 若为 prerelease 或版本号含 -，dist-tag = next
• 否则 dist-tag = latest

7. rollback 规则

在 --apply 的“版本更新到 git push”阶段如失败，会执行回滚：

• 删除本地新 tag（若已创建）
• git reset --hard <发布前commit>
• git clean -fd

说明：发布步骤（release publish）在 git push 之后执行，发布失败时不会自动回滚已推送的 Git 变更。

8. release publish 子命令（可单独重试）

pnpm exec enableai-cli release publish

适用于以下场景：

• release --apply 前序已成功，但发布网络异常
• 只想重试发布，不重复打版本/打 tag/推送

publish 子命令详解

registry 支持多个

publish: {
  registry: [
    'http://nexus.enableai.cn/repository/npm-host/',
    'https://registry.npmjs.org/'
  ]
}

会按顺序逐个 registry 发布所有非 private 包。

additionalPublishFlags

命令行支持重复传参：

pnpm exec enableai-cli release publish --publish-flag="--access public" --publish-flag="--no-git-checks"

与 config.publish.flags 的合并规则

最终参数顺序：

1. config.publish.flags
2. CLI --publish-flag

即“配置在前，命令行在后”。同名参数冲突时，通常后者更容易生效。

脚本示例

常见命令示例

# 初始化
pnpm exec enableai-cli init

# 查看包扫描与配置
pnpm exec enableai-cli info

# 构建链路
pnpm exec enableai-cli clean
pnpm exec enableai-cli barrels
pnpm exec enableai-cli build
pnpm exec enableai-cli dts

# 仅看发布计划
pnpm exec enableai-cli release --bump minor

# 正式发布
pnpm exec enableai-cli release --apply --bump patch

# 指定版本发布
pnpm exec enableai-cli release --apply --version 1.2.3

# 发布时附加参数
pnpm exec enableai-cli release --apply --bump prerelease --publish-flag="--no-git-checks"

package.json scripts 示例

{
  "scripts": {
    "clean": "enableai-cli clean",
    "barrels": "enableai-cli barrels",
    "build:core": "enableai-cli build",
    "build:dts": "enableai-cli dts",
    "build": "pnpm run barrels && pnpm run build:core && pnpm run build:dts",
    "release": "enableai-cli release",
    "release:publish": "enableai-cli release publish"
  }
}

CI 集成示例（GitHub Actions）

name: release
on:
  workflow_dispatch:

jobs:
  dry-run:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install
      - run: pnpm exec enableai-cli release --bump patch

  apply-release:
    if: github.ref == 'refs/heads/main'
    needs: dry-run
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
        with:
          fetch-depth: 0
      - uses: pnpm/action-setup@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 20
      - run: pnpm install
      - run: pnpm exec enableai-cli release --apply --bump patch

注意事项与常见问题

• release --apply 要求 Git 工作区干净，否则会直接失败。
• init 会强制覆盖 Rollup 模板文件，二次执行前请备份自定义改动。
• release 默认会尝试执行 pnpm run fix/test/typecheck，若你没有这些脚本，可用 --no-fix --no-test --no-typecheck 跳过。
• publish 会跳过 package.json 中 private: true 的包。
• 未配置 publish.registry 时，默认使用： http://nexus.enableai.cn/repository/npm-host/
• 若 release --apply 在“发布前流程”失败，会本地回滚；若在 publish 阶段失败，请使用 release publish 单独重试。
• 若版本号格式不合法（非 x.y.z 或 x.y.z-xxx），发布会被拒绝。

示例目录结构与典型输出

示例目录结构

your-repo/
├─ package.json
├─ enableai.config.ts
├─ rollup.config.js
├─ rollup.dts.config.js
├─ tsconfig.json
├─ tsconfig.build-browser.json
├─ tsconfig.build-node.json
├─ eslint.config.js
├─ vitest.config.ts
├─ packages/
│  ├─ core/
│  │  ├─ package.json
│  │  ├─ src/
│  │  └─ dist/
│  └─ utils/
│     ├─ package.json
│     ├─ src/
│     └─ dist/
└─ scripts/
   └─ inline-enums.js

典型输出示例：info

根目录: /path/to/your-repo
{
  "rootDir": "...",
  "packagesDirs": ["packages"],
  "orderKey": "order",
  ...
}
包列表:
@your/core 1 /path/to/your-repo/packages/core
@your/utils 2 /path/to/your-repo/packages/utils

典型输出示例：release（dry-run）

发布计划（dry-run）
版本: 1.2.3 -> 1.2.4
发布标签: latest
包列表:
- @your/core (顺序: 1)
- @your/utils (顺序: 2)
步骤:
1. 脚本检查: fix=执行, test=执行, typecheck=执行
2. 检查 git 工作区是否干净
3. 更新 root/子包版本号
4. 生成/更新 CHANGELOG.md
5. 执行 enableai-cli clean
6. 执行 enableai-cli build
7. 执行 enableai-cli dts
8. 执行 git add -A
9. 执行 git commit -m "release: v1.2.4"
10. 执行 git tag v1.2.4
11. 执行 git push
12. 执行 git push --tags
13. 执行 enableai-cli release publish (发布标签: latest)