soybeanjs/cli

README

@soybeanjs/cli

简体中文 | English

SoybeanJS 的命令行工具集，用于统一 Git 提交、依赖升级、Changelog 生成、版本发布和项目清理等日常工作流。

安装

pnpm add -D @soybeanjs/cli
# 或者
npm i -D @soybeanjs/cli
# 或者
yarn add -D @soybeanjs/cli

安装后，推荐通过 pnpm soy <command> 调用命令；也可使用 npx soy <command>。

常用工作流

提交代码

pnpm soy git-commit

依次选择提交类型、提交范围并填写描述，即可生成符合 Conventional Commits 的提交信息。描述以 ! 开头时会标记为破坏性变更。

升级依赖

pnpm soy ncu
pnpm install

ncu 使用 npm-check-updates 更新 package.json 中的依赖版本；在 workspace 项目中会自动启用 workspace 模式。完成后重新安装依赖，并运行项目的构建和测试命令验证变更。

生成 Changelog

# 根据最近的 tag 生成变更日志
pnpm soy changelog

# 基于所有 tag 重建变更日志
pnpm soy changelog --total

发布版本

pnpm soy release

发布流程会交互式更新版本号、执行 pnpm soy changelog、创建 chore(projects): release v<version> 提交和 Git tag，并推送到远端。执行前确保工作区干净且待发布的改动均已提交。

Warning

当前 release 命令默认推送提交和 tag。请在执行前确认分支、远端和发布内容均正确。

清理项目产物

pnpm soy cleanup

默认清理规则包含 dist、node_modules 以及 npm、Yarn、pnpm 的 lock 文件。若只想清理指定目录，可通过 --cleanupDir 传入逗号分隔的 glob：

pnpm soy cleanup --cleanupDir "**/dist,**/coverage"

命令参考

命令

命令	说明
`cleanup`	按 glob 清理目录和文件。默认包含构建产物、依赖目录和 lock 文件。
`ncu`	使用 npm-check-updates 升级依赖；workspace 项目会自动传入 `-w`。
`git-commit`	交互式创建符合 Conventional Commits 的 Git 提交。
`git-commit-verify`	校验 `.git/COMMIT_EDITMSG`，适合配置在 `commit-msg` hook 中。
`changelog`	从 Git tag 和提交历史生成 `CHANGELOG.md`。
`release`	交互式更新版本、生成 Changelog、创建提交和 tag，并推送到远端。
`config <set\|get\|path>`	设置、查看或定位全局配置。
`update-pkg`	已废弃，请使用 `ncu`。

选项

选项	适用命令	说明
`-e, --execute [command]`	`release`	指定版本更新后、创建提交前执行的命令；默认是 `pnpm soy changelog`。
`-t, --total`	`changelog`	使用全部 Git tag 生成 Changelog。
`-c, --cleanupDir <dir>`	`cleanup`	覆盖本次执行的清理 glob；多个值用逗号分隔。
`-l, --lang <lang>`	`git-commit`、`git-commit-verify`	将本次 CLI 输出设为 `zh-cn` 或 `en-us`。
`-v, --version`	全局	显示版本号。
`-h, --help`	全局	显示帮助信息。

提交信息格式

git-commit 生成的格式如下。scope 可以省略；若描述以 ! 开头，则会在冒号前保留 ! 以标记破坏性变更。

<type>(<scope>)<!>: <description>

feat(components): add new Button component
fix(utils)!: change API signature

默认提交类型：feat、fix、docs、style、refactor、perf、optimize、test、build、ci、chore、revert。

默认提交范围：projects、packages、components、hooks、utils、types、styles、deps、release、other。

全局配置命令

命令	说明
`pnpm soy config set --set-lang <zh-cn\|en-us>`	将默认显示语言写入 `~/.soybeanrc`。
`pnpm soy config get`	输出当前合并后的配置。
`pnpm soy config path`	输出全局配置文件路径。

配置

配置按以下优先级合并：命令行参数、项目配置、全局配置、内置默认值。项目配置可使用以下文件名，推荐 TypeScript：

soybean.config.ts
soybean.config.js
soybean.config.mjs
soybean.config.json
package.json 中的 soybean 字段

使用 defineConfig 可获得类型提示：

// soybean.config.ts
import { defineConfig } from '@soybeanjs/cli';

export default defineConfig({
  lang: 'zh-cn',
  cleanupDirs: ['**/dist', '**/.cache', '**/coverage', '**/node_modules', '!node_modules/**'],
  gitCommit: {
    types: [['wip', '工作进行中']],
    scopes: [
      ['ui', 'UI 组件'],
      ['api', 'API 接口']
    ]
  }
});

配置项

配置项	类型	说明
`cwd`	`string`	项目根目录，默认为 `process.cwd()`。
`lang`	`'zh-cn' \| 'en-us'`	CLI 默认显示语言。
`cleanupDirs`	`string[]`	`cleanup` 使用的 glob 规则。
`ncuCommandArgs`	`string[]`	传递给 npm-check-updates 的参数；设置后会覆盖自动生成的默认参数。
`changelogOptions`	`Partial<ChangelogOption>`	传递给 Changelog 生成器的选项。
`gitCommitVerifyIgnores`	`RegExp[]`	追加到默认忽略列表的提交信息校验规则。
`gitCommit.types`	`[string, string][]`	自定义提交类型；默认追加到内置类型。
`gitCommit.typesAppend`	`boolean`	设为 `false` 时，完全替换内置提交类型。
`gitCommit.scopes`	`[string, string][]`	自定义提交范围；默认追加到内置范围。
`gitCommit.scopesAppend`	`boolean`	设为 `false` 时，完全替换内置提交范围。

AI Skill

本仓库提供 soybean-cli skill，帮助 AI 编程助手在 SoybeanJS 项目中正确使用 soy 命令处理提交、发布、Changelog、依赖升级和清理等日常任务。

发布到 GitHub 后，通过以下命令安装：

npx skills add soybeanjs/cli

安装时选择 soybean-cli。Skill 源码位于 skills/soybean-cli。

License

MIT

README

@soybeanjs/cli

简体中文 | English

SoybeanJS 的命令行工具集，用于统一 Git 提交、依赖升级、Changelog 生成、版本发布和项目清理等日常工作流。

安装

pnpm add -D @soybeanjs/cli
# 或者
npm i -D @soybeanjs/cli
# 或者
yarn add -D @soybeanjs/cli

安装后，推荐通过 pnpm soy <command> 调用命令；也可使用 npx soy <command>。

常用工作流

提交代码

pnpm soy git-commit

依次选择提交类型、提交范围并填写描述，即可生成符合 Conventional Commits 的提交信息。描述以 ! 开头时会标记为破坏性变更。

升级依赖

pnpm soy ncu
pnpm install

生成 Changelog

# 根据最近的 tag 生成变更日志
pnpm soy changelog

# 基于所有 tag 重建变更日志
pnpm soy changelog --total

发布版本

pnpm soy release

Warning

当前 release 命令默认推送提交和 tag。请在执行前确认分支、远端和发布内容均正确。

清理项目产物

pnpm soy cleanup

默认清理规则包含 dist、node_modules 以及 npm、Yarn、pnpm 的 lock 文件。若只想清理指定目录，可通过 --cleanupDir 传入逗号分隔的 glob：

pnpm soy cleanup --cleanupDir "**/dist,**/coverage"

命令参考

命令

命令	说明
`cleanup`	按 glob 清理目录和文件。默认包含构建产物、依赖目录和 lock 文件。
`ncu`	使用 npm-check-updates 升级依赖；workspace 项目会自动传入 `-w`。
`git-commit`	交互式创建符合 Conventional Commits 的 Git 提交。
`git-commit-verify`	校验 `.git/COMMIT_EDITMSG`，适合配置在 `commit-msg` hook 中。
`changelog`	从 Git tag 和提交历史生成 `CHANGELOG.md`。
`release`	交互式更新版本、生成 Changelog、创建提交和 tag，并推送到远端。
`config <set\|get\|path>`	设置、查看或定位全局配置。
`update-pkg`	已废弃，请使用 `ncu`。

选项

选项	适用命令	说明
`-e, --execute [command]`	`release`	指定版本更新后、创建提交前执行的命令；默认是 `pnpm soy changelog`。
`-t, --total`	`changelog`	使用全部 Git tag 生成 Changelog。
`-c, --cleanupDir <dir>`	`cleanup`	覆盖本次执行的清理 glob；多个值用逗号分隔。
`-l, --lang <lang>`	`git-commit`、`git-commit-verify`	将本次 CLI 输出设为 `zh-cn` 或 `en-us`。
`-v, --version`	全局	显示版本号。
`-h, --help`	全局	显示帮助信息。

提交信息格式

git-commit 生成的格式如下。scope 可以省略；若描述以 ! 开头，则会在冒号前保留 ! 以标记破坏性变更。

<type>(<scope>)<!>: <description>

feat(components): add new Button component
fix(utils)!: change API signature

默认提交类型：feat、fix、docs、style、refactor、perf、optimize、test、build、ci、chore、revert。

默认提交范围：projects、packages、components、hooks、utils、types、styles、deps、release、other。

全局配置命令

命令	说明
`pnpm soy config set --set-lang <zh-cn\|en-us>`	将默认显示语言写入 `~/.soybeanrc`。
`pnpm soy config get`	输出当前合并后的配置。
`pnpm soy config path`	输出全局配置文件路径。

配置

配置按以下优先级合并：命令行参数、项目配置、全局配置、内置默认值。项目配置可使用以下文件名，推荐 TypeScript：

soybean.config.ts
soybean.config.js
soybean.config.mjs
soybean.config.json
package.json 中的 soybean 字段

使用 defineConfig 可获得类型提示：

// soybean.config.ts
import { defineConfig } from '@soybeanjs/cli';

export default defineConfig({
  lang: 'zh-cn',
  cleanupDirs: ['**/dist', '**/.cache', '**/coverage', '**/node_modules', '!node_modules/**'],
  gitCommit: {
    types: [['wip', '工作进行中']],
    scopes: [
      ['ui', 'UI 组件'],
      ['api', 'API 接口']
    ]
  }
});

配置项

配置项	类型	说明
`cwd`	`string`	项目根目录，默认为 `process.cwd()`。
`lang`	`'zh-cn' \| 'en-us'`	CLI 默认显示语言。
`cleanupDirs`	`string[]`	`cleanup` 使用的 glob 规则。
`ncuCommandArgs`	`string[]`	传递给 npm-check-updates 的参数；设置后会覆盖自动生成的默认参数。
`changelogOptions`	`Partial<ChangelogOption>`	传递给 Changelog 生成器的选项。
`gitCommitVerifyIgnores`	`RegExp[]`	追加到默认忽略列表的提交信息校验规则。
`gitCommit.types`	`[string, string][]`	自定义提交类型；默认追加到内置类型。
`gitCommit.typesAppend`	`boolean`	设为 `false` 时，完全替换内置提交类型。
`gitCommit.scopes`	`[string, string][]`	自定义提交范围；默认追加到内置范围。
`gitCommit.scopesAppend`	`boolean`	设为 `false` 时，完全替换内置提交范围。

AI Skill

本仓库提供 soybean-cli skill，帮助 AI 编程助手在 SoybeanJS 项目中正确使用 soy 命令处理提交、发布、Changelog、依赖升级和清理等日常任务。

发布到 GitHub 后，通过以下命令安装：

npx skills add soybeanjs/cli

安装时选择 soybean-cli。Skill 源码位于 skills/soybean-cli。

License

MIT

soybeanjs/cli(opens in a new tab)

README

@soybeanjs/cli

目录

安装

常用工作流

提交代码

升级依赖

生成 Changelog

发布版本

清理项目产物

命令参考

命令

选项

提交信息格式

全局配置命令

配置

配置项

推荐脚本

AI Skill

License

README

@soybeanjs/cli

目录

安装

常用工作流

提交代码

升级依赖

生成 Changelog

发布版本

清理项目产物

命令参考

命令

选项

提交信息格式

全局配置命令

配置

配置项

推荐脚本

AI Skill

License