@varlet/release 2.1.0 → 2.2.0

package/README.md

@@ -20,151 +20,335 @@
 
 > `Varlet Release` requires `Node.js` ^20.19.0 || >=22.12.0 and `esm` only.
 
-## Installation
+## Quick Start
+
+Install dependencies:
 
 ```shell
-pnpm add @varlet/release -D
+pnpm add @varlet/release simple-git-hooks -D
+```
+
+Add the following configuration to `package.json`:
+
+```json
+{
+  "scripts": {
+    "prepare": "simple-git-hooks",
+    "release": "vr release",
+    "changelog": "vr changelog"
+  },
+  "simple-git-hooks": {
+    "commit-msg": "pnpm exec vr commit-lint $1",
+    "post-merge": "pnpm exec vr lockfile-check --install"
+  }
+}
 ```
 
+Now you can:
+
+- Write commits following the [Conventional Commits](https://www.conventionalcommits.org/) format, `commit-lint` will automatically validate them.
+- After pulling or merging code, `lockfile-check` will automatically detect lockfile changes (`pnpm-lock.yaml`, `yarn.lock`, `package-lock.json`) and reinstall dependencies.
+- Run `pnpm release` to start the interactive release workflow.
+
 ## Usage
 
-### Core Workflow
+### Features Overview
 
-When executing `vr release`, the following sequence of lifecycles occurs automatically:
+- [release](#release) - Automatically complete the standard workflow from version modification to publishing and creating git tags.
+- [publish](#publish) - Execute the npm publish process independently, usually suitable for CI/CD environments.
+- [changelog](#changelog) - Automatically generate formatted changelogs based on Git Commit conventions.
+- [commit-lint](#commit-lint) - Validate whether the Git Commit Message adheres to specifications, helping teams unify commit formats.
+- [lockfile-check](#lockfile-check) - Check the status of the project's lockfile and provide dependency update mechanisms when changes occur.
 
-1. Select/Confirm the **version** to publish interactively
-2. Execute the user-defined `task` function (optional, e.g., to rebuild projects based on the new version)
-3. Update the `package.json` **version** programmatically
-4. Generate the **Changelog**
-5. **Git Commit** & **Git Tag**
-6. **Publish** to npm
+---
 
-### Using Command
+### release
 
-```shell
-# Release all packages and run the full workflow
-npx vr release
+**Description**: The core functional collection for package release, integrating all release preparation and subsequent operations.
 
-# Specify remote name
-npx vr release -r origin
-# or
-npx vr release --remote origin
+**Use cases**: Used when a new version needs to be released and all workspace changes have been committed. It guides through the publication via an intuitive command-line interaction.
 
-# Just generate changelogs
-npx vr changelog
+**Core Workflow**:
 
-# Specify changelog filename
-npx vr changelog -f changelog.md
-# or
-npx vr changelog --file changelog.md
+1. Interactively prompt and confirm the new version number (automatically calculate patch, minor, major upgrades).
+2. Execute the user-customized `task` function (e.g., modifying files, bundling assets).
+3. Automatically update the version number in the project's `package.json`.
+4. Generate the `Changelog` for the corresponding version.
+5. Automatically complete the Git commit and create a new version Tag.
+6. Publish the updated packages to npm.
 
-# Lint commit message
-npx vr commit-lint -p .git/COMMIT_EDITMSG
+**CLI Commands**:
 
-# Publish to npm, which can be called in the ci environment
-npx vr publish
+_Flags Reference_:
 
-# Check if lockfile has been updated
-npx vr lockfile-sync-check
+```text
+Usage: vr release [flags...]
 
-# Auto install dependencies if lockfile changed
-npx vr lockfile-sync-check -i
+Flags:
+      --remote string                 Remote repository name  # default: 'origin'
+      --skip-npm-publish              Skip npm publish
+      --skip-changelog                Skip generating changelog
+      --skip-git-tag                  Skip git tag
+      --npm-tag string                npm tag
+      --check-remote-version          Check remote version
 ```
 
-### Git Hooks Integration (Best Practice)
+_Example_:
 
-It is highly recommended to use `commit-lint` with `simple-git-hooks` or `husky` in `package.json` to automatically check developers' commit messages before committing:
+```shell
+# Release all packages and execute the full workflow
+pnpm exec vr release
+
+# Skip npm publishing
+pnpm exec vr release --skip-npm-publish
+# Skip generating changelog
+pnpm exec vr release --skip-changelog
+# Check remote version, interrupt execution if the identical version already exists
+pnpm exec vr release --check-remote-version
+
+# Specify the git remote name for pushing tags (useful when multiple remotes are configured, e.g. upstream, fork)
+pnpm exec vr release --remote upstream
+```
 
-```json
-{
-  "simple-git-hooks": {
-    "commit-msg": "npx vr commit-lint -p $1"
-  }
-}
+**Node API**:
+
+```typescript
+import { release } from '@varlet/release'
+
+release({
+  remote?: string              // Remote repository name, defaults to 'origin'
+  npmTag?: string              // NPM tag to publish, such as 'next', 'alpha'
+  cwd?: string                 // Working directory, defaults to process.cwd()
+  skipNpmPublish?: boolean     // Whether to skip the npm publish process
+  skipChangelog?: boolean      // Whether to skip changelog generation
+  skipGitTag?: boolean         // Whether to skip git tag creation
+  checkRemoteVersion?: boolean // Whether to check remote version to avoid conflicts
+  task?(newVersion: string, oldVersion: string): Promise<void> // Custom task executed during the release
+})
 ```
 
-### Configuration
+_Example: Add custom handling logic_
 
-#### release
+```javascript
+import { release } from '@varlet/release'
 
-```
-Usage: vr release [flags...]
+async function task(newVersion, oldVersion) {
+  // Execute building or file writing operations here
+  await doBuild()
+}
 
-Flags:
-  -r, --remote <string>             Remote name
-  -s, --skip-npm-publish            Skip npm publish
-      --skip-changelog              Skip generate changelog
-      --skip-git-tag                Skip git tag
-  -t, --npm-tag <string>            Npm tag
-  -c, --check-remote-version        Check remote version
+release({ task })
 ```
 
-#### publish
+---
 
-```
+### publish
+
+**Description**: Publish the package independently to the npm registry.
+
+**Use cases**: Applicable in scenarios where manual version selection, changelog generation, or git tags are not needed, often used in CI/CD pipelines to trigger automated publication based on specific processes.
+
+**Core Workflow**: Read the version number from the current package.json and run the corresponding publish process.
+
+**CLI Commands**:
+
+_Flags Reference_:
+
+```text
 Usage: vr publish [flags...]
 
 Flags:
-  -c, --check-remote-version        Check remote version
-  -t, --npm-tag <string>            Npm tag
+      --check-remote-version          Check remote version
+      --npm-tag string                npm tag
+```
+
+_Example_:
+
+```shell
+# Publish directly to npm
+pnpm exec vr publish
+
+# Check if the same version already exists due to network or other reasons, and abort if so
+pnpm exec vr publish --check-remote-version
+# Specify the npm dist-tag
+pnpm exec vr publish --npm-tag alpha
 ```
 
-#### changelog
+**Node API**:
 
+```typescript
+import { publish } from '@varlet/release'
+
+publish({
+  preRelease?: boolean         // Pre-release indicator, will add the '--tag alpha' option
+  checkRemoteVersion?: boolean // Check if the same version exists on the remote npm before publishing
+  npmTag?: string              // NPM tag to publish
+  cwd?: string                 // Working directory, defaults to process.cwd()
+})
 ```
+
+---
+
+### changelog
+
+**Description**: Automatically generate Markdown-formatted changelogs based on standard Commit history.
+
+**Use cases**: Useful for updating the `CHANGELOG.md` file independently without triggering the full release process.
+
+**Core Workflow**: Traverse the Git commit history and format the output classified by predefined conventional commit rules (e.g., feat, fix).
+
+**CLI Commands**:
+
+_Flags Reference_:
+
+```text
 Usage: vr changelog [flags...]
 
 Flags:
-  -c, --release-count <number>      Release count, default 0
-  -f, --file <string>               Changelog filename
+      --release-count number          Release count  # default: 0
+      --file string                   Changelog filename  # default: 'CHANGELOG.md'
 ```
 
-#### commit-lint
+_Example_:
 
+```shell
+# Generate changelogs for all history and output as CHANGELOG.md in the current directory
+pnpm exec vr changelog
+
+# Specify the generated changelog filename
+pnpm exec vr changelog --file my-changelog.md
+# Limit the range of release versions to generate changelogs for (0 means all)
+pnpm exec vr changelog --release-count 0
+```
+
+**Node API**:
+
+```typescript
+import { changelog } from '@varlet/release'
+
+changelog({
+  cwd?: string                 // Working directory, defaults to process.cwd()
+  releaseCount?: number        // Number of recent releases to include in the log, defaults to 0 (all)
+  file?: string                // Output changelog filename, defaults to 'CHANGELOG.md'
+  showTypes?: string[]         // Commit types to display, defaults to ['feat', 'fix', 'perf', 'revert', 'refactor']
+  outputUnreleased?: boolean   // Whether to output unreleased changes
+  writerOpt?: object           // Specific configuration for conventional-changelog-writer
+})
 ```
-Usage: vr commit-lint [flags...]
+
+---
+
+### commit-lint
+
+**Description**: Validate Git commit message formats.
+
+**Use cases**: Used in combination with `git hooks` to enforce high-quality commit descriptions, ensuring the quality of the changelog.
+
+**Core Workflow**: Read the commit file. If it matches the configured regex, the process continues; otherwise, it prints specific failure messages and aborts the commit.
+
+**CLI Commands**:
+
+_Parameters Reference_:
+
+```text
+Usage: vr commit-lint <commit-message-path> [flags...]
+
+Parameters:
+  <commit-message-path>             Git commit message path (required)
 
 Flags:
-  -p, --commit-message-path <string>  Git commit message path
-  -r, --commit-message-re <string>    Validate the regular of whether the commit message passes
-  -e, --error-message <string>        Validation failed to display error messages
-  -w, --warning-message <string>      Validation failed to display warning messages
+      --commit-message-re string      Validate the regex for commit message
+      --error-message string          Error message displayed on validation failure
+      --warning-message string        Warning message displayed on validation failure
 ```
 
-#### lockfile-sync-check
+_Example_:
 
+```shell
+# Check if the commit message at the given path is standard
+pnpm exec vr commit-lint .git/COMMIT_EDITMSG
+
+# Customize regex validation and prompt message
+pnpm exec vr commit-lint .git/COMMIT_EDITMSG --commit-message-re "^feat: .*" --error-message "Commit validation failed"
 ```
-Usage: vr lockfile-sync-check [flags...]
 
-Flags:
-  -m, --package-manager <string>    Package manager (npm, yarn, pnpm), default pnpm
-  -i, --install                     Auto install dependencies if lockfile changed
+_It is recommended to integrate with `simple-git-hooks` or `husky` in `package.json`:_
+
+```json
+{
+  "simple-git-hooks": {
+    "commit-msg": "pnpm exec vr commit-lint $1"
+  }
+}
 ```
 
-### Node API Custom Handle
+**Node API**:
 
-You can write your own release scripts with Internal Node.js API instead of CLI.
+```typescript
+import { commitLint } from '@varlet/release'
 
-#### Example
+commitLint({
+  commitMessagePath: string            // Required: Path to Git commit message file
+  commitMessageRe?: string | RegExp    // Regex to validate the commit message format
+  errorMessage?: string                // Error message printed upon failure
+  warningMessage?: string              // Supplemental warning information printed upon failure
+})
+```
+
+---
+
+### lockfile-check
+
+**Description**: Detect and visually output in the console whether the lockfile of frontend dependencies has been modified, and automatically install dependencies by default to keep in sync.
+
+**Use cases**: Recommended to use after Git operations such as pulling updates (`git pull`), switching branches (`git checkout`), or merging code. It helps detect if upstream dependency lockfiles (like `pnpm-lock.yaml`) have changed. If a change is detected, it will automatically invoke a package manager's installation command to synchronize the local environment with upstream instantly, preventing obscure bugs caused by outdated dependencies.
+
+**Core Workflow**: Execute a Git diff comparing the project's lockfile (e.g. `pnpm-lock.yaml` or corresponding environment lockfile) from the original HEAD. Print its modification status in the console. Furthermore, trigger the package manager to reinstall dependencies to sync with upstream by default, or skip installation if directed by the command options.
 
-```js
-import { changelog, release } from '@varlet/release'
+**CLI Commands**:
 
-// Run the core release workflow directly
-release()
+_Flags Reference_:
+
+```text
+Usage: vr lockfile-check [flags...]
+
+Flags:
+      --package-manager string        Package manager (npm, yarn, pnpm)  # default: 'pnpm'
+      --skip-install                  Skip install dependencies when lockfile changed
 ```
 
-You can pass in a custom `task` function that will be called after the package version is updated but before the remaining publish steps.
+_Example_:
 
-```js
-import { changelog, release } from '@varlet/release'
+```shell
+# Check the synchronization status of the current lockfile and install dependencies if changed
+pnpm exec vr lockfile-check
 
-async function task(newVersion, oldVersion) {
-  await doSomething1()
-  await doSomething2()
+# Check current status but skip installation even if updates exist
+pnpm exec vr lockfile-check --skip-install
+
+# Specify other package managers for checking
+pnpm exec vr lockfile-check --package-manager npm
+```
+
+_It is also recommended to integrate with `simple-git-hooks` or `husky` in `package.json` (e.g. trigger checks and installations automatically during the `post-merge` or `post-checkout` hooks):_
+
+```json
+{
+  "simple-git-hooks": {
+    "post-merge": "pnpm exec vr lockfile-check"
+  }
 }
+```
 
-release({ task })
+**Node API**:
+
+```typescript
+import { lockfileCheck } from '@varlet/release'
+
+lockfileCheck({
+  packageManager?: 'npm' | 'yarn' | 'pnpm' // Choose package manager, defaults to 'pnpm'
+  skipInstall?: boolean                    // Whether to skip installation if lockfile is out of sync
+})
 ```
 
 ## License

package/README.zh-CN.md

@@ -20,151 +20,335 @@
 
 > `Varlet Release` 需要 `Node.js` ^20.19.0 || >=22.12.0，并且仅支持 `esm`。
 
-## 安装
+## 快速开始
+
+安装依赖：
 
 ```shell
-pnpm add @varlet/release -D
+pnpm add @varlet/release simple-git-hooks -D
 ```
 
-## 使用
+在 `package.json` 中添加以下配置：
 
-### 核心工作流
+```json
+{
+  "scripts": {
+    "prepare": "simple-git-hooks",
+    "release": "vr release",
+    "changelog": "vr changelog"
+  },
+  "simple-git-hooks": {
+    "commit-msg": "pnpm exec vr commit-lint $1",
+    "post-merge": "pnpm exec vr lockfile-check --install"
+  }
+}
+```
 
-执行 `vr release` 时，背后会自动完成以下流程（保障每一步的严谨性）：
+现在你可以：
 
-1. 交互式选择/确认要发布的版本号
-2. 执行用户自定义的额外 `task` 操作（可选，如重新构建以注入新版本号）
-3. 自动修改工程中的版本号信息
-4. 自动生成符合规范的 Changelog
-5. Git 提交 (Commit) 与打标签 (Tag)
-6. 发布至 npm
+- 按照 [Conventional Commits](https://www.conventionalcommits.org/) 规范编写提交信息，`commit-lint` 会自动校验。
+- 拉取或合并代码后，`lockfile-check` 会自动检测 lockfile 变化（`pnpm-lock.yaml`、`yarn.lock`、`package-lock.json`）并重新安装依赖。
+- 运行 `pnpm release` 启动交互式发布流程。
 
-### 命令行使用
+## 使用
 
-```shell
-# 发布所有包并执行完整工作流程
-npx vr release
+### 功能概览
 
-# 指定远程仓库名称
-npx vr release -r origin
-# 或
-npx vr release --remote origin
+- [release](#release) - 自动完成从版本号变更到发布、打标签的标准工作流。
+- [publish](#publish) - 单独执行 npm 发布流程，通常适用于 CI/CD 环境。
+- [changelog](#changelog) - 根据 Git Commit 规范自动生成格式化的变更日志。
+- [commit-lint](#commit-lint) - 校验 Git Commit Message 是否符合规范，帮助团队统一提交格式。
+- [lockfile-check](#lockfile-check) - 检查项目 lockfile 状态并在变化时提供更新依赖机制。
 
-# 仅生成变更日志
-npx vr changelog
+---
 
-# 指定变更日志文件名
-npx vr changelog -f changelog.md
-# 或
-npx vr changelog --file changelog.md
+### release
 
-# 检测 commit message 是否符合规范
-npx vr commit-lint -p .git/COMMIT_EDITMSG
+**作用**：包版本发布的核心功能集合，集成和串联了所有的发布准备及后续操作。
 
-# 发布到 npm（通常在 CI/CD 中执行）
-npx vr publish
+**使用场景**：在项目需要发布新版本且工作区变更已全部提交时使用。通过直观的命令行交互完成发布。
 
-# 检查 lockfile 是否已更新
-npx vr lockfile-sync-check
+**核心流程**：
 
-# 如果 lockfile 发生变化则自动安装依赖
-npx vr lockfile-sync-check -i
-```
+1. 交互式提示并确认发布版本号（自动计算 patch、minor 等升级维度）。
+2. 执行用户自定义的 `task` 函数（例如修改文件，打包构建）。
+3. 自动更新项目中 `package.json` 的版本号。
+4. 生成对应该版本的 `Changelog`。
+5. 自动完成 Git 提交动作并且打上新版本标签 (Tag)。
+6. 自动将更新后的包发布至 npm。
 
-### Git Hooks 集成 (推荐最佳实践)
+**CMD 命令**：
 
-建议在 `package.json` 中配合 `simple-git-hooks` 或 `husky` 使用 `commit-lint`，在开发者提交代码时自动触发校验：
+_标志参考_：
 
-```json
-{
-  "simple-git-hooks": {
-    "commit-msg": "npx vr commit-lint -p $1"
-  }
-}
+```text
+用法: vr release [标志...]
+
+标志:
+      --remote string                 远程仓库名称  # 默认: 'origin'
+      --skip-npm-publish              跳过 npm 发布
+      --skip-changelog                跳过生成变更日志
+      --skip-git-tag                  跳过 git tag
+      --npm-tag string                npm tag
+      --check-remote-version          检查远程版本
 ```
 
-### 配置参考
+_使用示例_：
+
+```shell
+# 发布所有包并执行完整工作流程
+pnpm exec vr release
 
-#### release
+# 跳过 npm 发布
+pnpm exec vr release --skip-npm-publish
+# 跳过生成变更日志
+pnpm exec vr release --skip-changelog
+# 检查远程版本，若已存在相同版本则中断执行
+pnpm exec vr release --check-remote-version
 
+# 指定推送 tag 的 git remote 名称（适用于配置了多个 remote 的场景，如 upstream、fork 等）
+pnpm exec vr release --remote upstream
 ```
-用法: vr release [标志...]
 
-标志:
-  -r, --remote <string>             远程仓库名称
-  -s, --skip-npm-publish            跳过 npm 发布
-      --skip-changelog              跳过生成变更日志
-      --skip-git-tag                跳过 git tag
-  -t, --npm-tag <string>            npm tag
-  -c, --check-remote-version        检查远程版本
+**Node 调用**：
+
+```typescript
+import { release } from '@varlet/release'
+
+release({
+  remote?: string              // 远程仓库名称，默认为 'origin'
+  npmTag?: string              // 发布的 npm tag，如 'next'、'alpha'
+  cwd?: string                 // 工作目录，默认为 process.cwd()
+  skipNpmPublish?: boolean     // 是否跳过 npm publish 过程
+  skipChangelog?: boolean      // 是否跳过生成变更日志
+  skipGitTag?: boolean         // 是否跳过构建 git tag 过程
+  checkRemoteVersion?: boolean // 是否检查远程版本，保证不发生版本冲突
+  task?(newVersion: string, oldVersion: string): Promise<void> // 发布过程中执行的自定义任务
+})
 ```
 
-#### publish
+_例：增加自定义处理逻辑_
 
+```javascript
+import { release } from '@varlet/release'
+
+async function task(newVersion, oldVersion) {
+  // 在此处执行构建或写入文件的操作
+  await doBuild()
+}
+
+release({ task })
 ```
+
+---
+
+### publish
+
+**作用**：单独将包发布至 npm 仓库。
+
+**使用场景**：适用于无需手动选择版本、生成 Changelog 或打 Git Tag 的场景，常用于在 CI/CD 流水线中针对特定过程触发自动化发布。
+
+**核心流程**：读取当前 package.json 中的版本号，运行对应的 publish 流程。
+
+**CMD 命令**：
+
+_标志参考_：
+
+```text
 用法: vr publish [标志...]
 
 标志:
-  -c, --check-remote-version        检查远程版本
-  -t, --npm-tag <string>            npm tag
+      --check-remote-version          检查远程版本
+      --npm-tag string                npm tag
 ```
 
-#### changelog
+_使用示例_：
 
+```shell
+# 直接发布到 npm
+pnpm exec vr publish
+
+# 检查由于网络等原因是否已存在相同版本，存在则放弃发布
+pnpm exec vr publish --check-remote-version
+# 指定 npm 的 dist-tag
+pnpm exec vr publish --npm-tag alpha
+```
+
+**Node 调用**：
+
+```typescript
+import { publish } from '@varlet/release'
+
+publish({
+  preRelease?: boolean         // 预发布标示，将添加 '--tag alpha' 选项
+  checkRemoteVersion?: boolean // 发布前检查远程 npm 上是否已存在相同版本
+  npmTag?: string              // 发布的 npm tag
+  cwd?: string                 // 工作目录，默认为 process.cwd()
+})
 ```
+
+---
+
+### changelog
+
+**作用**：基于规范的 Commit 历史自动生成 Markdown 格式的变更日志。
+
+**使用场景**：单独更新 `CHANGELOG.md` 记录，单点生成所需日志。
+
+**核心流程**：遍历 Git 提交历史，依据预设的 conventional commit 规则分类（如 feat、fix 等），格式化输出。
+
+**CMD 命令**：
+
+_标志参考_：
+
+```text
 用法: vr changelog [标志...]
 
 标志:
-  -c, --release-count <number>      发布数量，默认 0
-  -f, --file <string>               变更日志文件名
+      --release-count number          发布数量  # 默认: 0
+      --file string                   变更日志文件名  # 默认: 'CHANGELOG.md'
 ```
 
-#### commit-lint
+_使用示例_：
+
+```shell
+# 生成所有历史的变更日志并在当前目录输出为 CHANGELOG.md
+pnpm exec vr changelog
 
+# 指定生成的变更日志文件名
+pnpm exec vr changelog --file my-changelog.md
+# 限定发布版本的范围数量以生成变更日志 (0 为全量)
+pnpm exec vr changelog --release-count 0
 ```
-用法: vr commit-lint [标志...]
+
+**Node 调用**：
+
+```typescript
+import { changelog } from '@varlet/release'
+
+changelog({
+  cwd?: string                 // 工作目录，默认为 process.cwd()
+  releaseCount?: number        // 输出日志涉及的最近发布的版本数量，默认为 0（全部）
+  file?: string                // 输出的日志文件名，默认为 'CHANGELOG.md'
+  showTypes?: string[]         // 显示的 commit 类型，默认 ['feat', 'fix', 'perf', 'revert', 'refactor']
+  outputUnreleased?: boolean   // 是否输出 unreleased 版本变更
+  writerOpt?: object           // conventional-changelog-writer 具体配置参数
+})
+```
+
+---
+
+### commit-lint
+
+**作用**：校验 Git 提交信息格式。
+
+**使用场景**：结合 `git hooks` 一同工作，强制保障书写高质量的提交说明以保证 Changelog 质量。
+
+**核心流程**：读取提交文件，若是符合配置的正则格式则通过处理，否则打印具体的失败信息报错，并终止提交。
+
+**CMD 命令**：
+
+_参数参考_：
+
+```text
+用法: vr commit-lint <commit-message-path> [标志...]
+
+参数:
+  <commit-message-path>             Git commit message 路径（必填）
 
 标志:
-  -p, --commit-message-path <string>  Git commit message 路径
-  -r, --commit-message-re <string>    验证 commit message 是否通过的正则表达式
-  -e, --error-message <string>        验证失败时显示的错误信息
-  -w, --warning-message <string>      验证失败时显示的警告信息
+      --commit-message-re string      验证 commit message 是否通过的正则表达式
+      --error-message string          验证失败时显示的错误信息
+      --warning-message string        验证失败时显示的警告信息
 ```
 
-#### lockfile-sync-check
+_使用示例_：
+
+```shell
+# 检测指路径的 commit message 是否符合规范
+pnpm exec vr commit-lint .git/COMMIT_EDITMSG
 
+# 定制指定的校验正则表达式和提示信息
+pnpm exec vr commit-lint .git/COMMIT_EDITMSG --commit-message-re "^feat: .*" --error-message "提交校验失败"
 ```
-用法: vr lockfile-sync-check [标志...]
 
-标志:
-  -m, --package-manager <string>    包管理器 (npm, yarn, pnpm)，默认 pnpm
-  -i, --install                     如果 lockfile 发生变化则自动安装依赖
+_建议配合并在 `package.json` 中的 `simple-git-hooks` 或 `husky` 一同集成运作：_
+
+```json
+{
+  "simple-git-hooks": {
+    "commit-msg": "pnpm exec vr commit-lint $1"
+  }
+}
+```
+
+**Node 调用**：
+
+```typescript
+import { commitLint } from '@varlet/release'
+
+commitLint({
+  commitMessagePath: string            // 必选：Git commit message 文件路径
+  commitMessageRe?: string | RegExp    // 验证 msg 格式的正则表达式
+  errorMessage?: string                // 验证失败时打印的提示文本
+  warningMessage?: string              // 验证失败时打印的补充警告文档链接
+})
 ```
 
-### Node API 自定义处理
+---
+
+### lockfile-check
 
-除了命令行，你也可以使用 Node.js API 结合内部逻辑编写发布脚本。
+**作用**：检测并在控制台直观地输出前端依赖包的 lockfile 文件是否发生变更，并默认自动安装依赖以保持同步。
 
-#### 示例代码
+**使用场景**：通常在进行 `git 操作` (如 `git pull`拉取最新代码、`git checkout`切换分支、或合并代码) 之后使用。它能帮助你检测上游的依赖锁文件（如 `pnpm-lock.yaml`）是否发生了变动。如果检测到有变更，默认会自动执行 install 安装命令，从而确保本地环境快速与上游依赖保持一致，避免因依赖版本陈旧导致的疑难 bug。
 
-```js
-import { changelog, release } from '@varlet/release'
+**核心流程**：比对项目原始游标的锁文件（如 pnpm-lock.yaml 或对应环境的 lockfile）的 Git diff，在控制台输出其是否存在变动；默认会触发包管理器的依赖重装程序以同步上游，也可以通过指令跳过安装。
 
-// 执行默认发布流程
-release()
+**CMD 命令**：
+
+_标志参考_：
+
+```text
+用法: vr lockfile-check [标志...]
+
+标志:
+      --package-manager string        包管理器 (npm, yarn, pnpm)  # 默认: 'pnpm'
+      --skip-install                  当 lockfile 发生变化时跳过安装依赖
 ```
 
-你可以传入一个 `task` 函数，在版本号变更之后、发布到 npm 等后续操作之前被调用。
+_使用示例_：
 
-```js
-import { changelog, release } from '@varlet/release'
+```shell
+# 检查当前 lockfile 的同步状态，若有变化则自动安装依赖
+pnpm exec vr lockfile-check
 
-async function task(newVersion, oldVersion) {
-  await doSomething1()
-  await doSomething2()
+# 检查当前状态，即使有更新也跳过安装
+pnpm exec vr lockfile-check --skip-install
+
+# 指定其他包管理器进行检查
+pnpm exec vr lockfile-check --package-manager npm
+```
+
+_建议配合并在 `package.json` 中的 `simple-git-hooks` 或 `husky` 一同集成运作（例如在拉取代码的 `post-merge` 或 `post-checkout` 阶段自动触发检查与安装）：_
+
+```json
+{
+  "simple-git-hooks": {
+    "post-merge": "pnpm exec vr lockfile-check"
+  }
 }
+```
 
-release({ task })
+**Node 调用**：
+
+```typescript
+import { lockfileCheck } from '@varlet/release'
+
+lockfileCheck({
+  packageManager?: 'npm' | 'yarn' | 'pnpm' // 选择包管理器，默认为 'pnpm'
+  skipInstall?: boolean                    // 检测到 lock 不同步时是否跳过安装
+})
 ```
 
 ## 许可证

package/dist/cli.js

@@ -1,11 +1,11 @@
 #!/usr/bin/env node
-import { c as release, i as lockfileCheck, p as commitLint, s as publish, u as changelog } from "./src-_TFLfQjD.js";
+import { c as release, i as lockfileCheck, p as commitLint, s as publish, u as changelog } from "./src-JMmGEAWu.js";
 import { cli, command } from "cleye";
 //#endregion
 //#region src/cli.ts
 cli({
 	name: "vr",
-	version: "2.1.0",
+	version: "2.2.0",
 	commands: [
 		command({
 			name: "release",
@@ -76,13 +76,8 @@ cli({
 		}, (argv) => changelog(argv.flags)),
 		command({
 			name: "commit-lint",
+			parameters: ["<commitMessagePath>"],
 			flags: {
-				commitMessagePath: {
-					type: String,
-					alias: "p",
-					default: "",
-					description: "Git commit message path"
-				},
 				commitMessageRe: {
 					type: String,
 					alias: "r",
@@ -100,7 +95,12 @@ cli({
 				}
 			},
 			help: { description: "Lint commit message" }
-		}, (argv) => commitLint(argv.flags)),
+		}, (argv) => commitLint({
+			commitMessagePath: argv._.commitMessagePath,
+			commitMessageRe: argv.flags.commitMessageRe,
+			errorMessage: argv.flags.errorMessage,
+			warningMessage: argv.flags.warningMessage
+		})),
 		command({
 			name: "lockfile-check",
 			flags: {
@@ -110,10 +110,10 @@ cli({
 					default: "pnpm",
 					description: "Package manager (npm, yarn, pnpm), default pnpm"
 				},
-				install: {
+				skipInstall: {
 					type: Boolean,
-					alias: "i",
-					description: "Auto install dependencies if lockfile changed"
+					alias: "s",
+					description: "Skip install dependencies when lockfile changed"
 				}
 			},
 			help: { description: "Check if lockfile has been updated and optionally install dependencies" }

package/dist/index.d.ts

@@ -84,7 +84,7 @@ declare function commitLint(options: CommitLintCommandOptions): void;
 type PackageManager = "npm" | "yarn" | "pnpm";
 interface LockfileCheckOptions {
   packageManager?: PackageManager;
-  install?: boolean;
+  skipInstall?: boolean;
 }
 declare function getLockfilePath(packageManager: PackageManager): string;
 declare function checkLockfileSync(packageManager: PackageManager): Promise<boolean>;

package/dist/index.js

@@ -1,2 +1,2 @@
-import { a as getPackageJsons, c as release, d as COMMIT_HEADER_RE, f as COMMIT_MESSAGE_RE, h as isVersionCommitMessage, i as lockfileCheck, l as updateVersion, m as getCommitMessage, n as getLockfilePath, o as isSameVersion, p as commitLint, r as installDependencies, s as publish, t as checkLockfileSync, u as changelog } from "./src-_TFLfQjD.js";
+import { a as getPackageJsons, c as release, d as COMMIT_HEADER_RE, f as COMMIT_MESSAGE_RE, h as isVersionCommitMessage, i as lockfileCheck, l as updateVersion, m as getCommitMessage, n as getLockfilePath, o as isSameVersion, p as commitLint, r as installDependencies, s as publish, t as checkLockfileSync, u as changelog } from "./src-JMmGEAWu.js";
 export { COMMIT_HEADER_RE, COMMIT_MESSAGE_RE, changelog, checkLockfileSync, commitLint, getCommitMessage, getLockfilePath, getPackageJsons, installDependencies, isSameVersion, isVersionCommitMessage, lockfileCheck, publish, release, updateVersion };

package/dist/{src-_TFLfQjD.js → src-JMmGEAWu.js}

@@ -39,9 +39,7 @@ Allowed types:
 - revert
 - merge
 - wip
-
-Commit message reference: https://docs.google.com/document/d/1QrDFcIiPjSLDn3EL15IJygNPiHORgU1_OOAqWjiDU5Y
-参考阮一峰Commit message编写指南: https://www.ruanyifeng.com/blog/2016/01/commit_message_change_log.html`;
+`;
 function isVersionCommitMessage(message) {
 	return Boolean(message.startsWith("v") && semver.valid(message.slice(1)));
 }
@@ -353,10 +351,10 @@ function computeExpectVersion(currentVersion, type) {
 }
 async function getReleaseType(currentVersion) {
 	return unwrapPromptResult(await select({
-		message: "Please select release type",
+		message: `Please select release type, current version ${currentVersion}`,
 		options: RELEASE_TYPES.map((type) => {
 			return {
-				label: `${type} (${currentVersion} → ${computeExpectVersion(currentVersion, type)})`,
+				label: `${type} (${computeExpectVersion(currentVersion, type)})`,
 				value: type
 			};
 		})
@@ -460,10 +458,18 @@ async function installDependencies(packageManager) {
 async function lockfileCheck(options = {}) {
 	try {
 		const pkgManager = options.packageManager || "pnpm";
-		const installFlag = options.install || false;
+		const skipInstallFlag = options.skipInstall || false;
+		if (![
+			"npm",
+			"yarn",
+			"pnpm"
+		].includes(pkgManager)) {
+			logger.error(`Unsupported package manager: ${pkgManager}`);
+			return;
+		}
 		if (await checkLockfileSync(pkgManager)) {
 			logger.warn("Lockfile has been updated!");
-			if (installFlag) await installDependencies(pkgManager);
+			if (!skipInstallFlag) await installDependencies(pkgManager);
 		}
 	} catch (error) {
 		logger.error("Error checking lockfile sync:", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@varlet/release",
-  "version": "2.1.0",
+  "version": "2.2.0",
   "description": "publish all packages, generate changelogs and check commit messages",
   "keywords": [
     "changelog",