npm package: @kinngyo/np
Description: npm 包发布助手 - 交互式版本管理与发布工具
Author: kinngyo
Latest version: 0.0.5

# @kinngyo/np

npm 包发布助手 - 交互式版本管理与发布工具

## 功能特性

- 🔍 自动检测远程版本，智能推荐版本号
- 🎯 交互式版本选择，支持 semver 所有版本类型
- 🔒 发布前 Git 工作区检查，确保代码已提交
- 🔕 静默模式，适用于 CI/CD 环境
- 📦 支持 npm 私有包发布
- 🏷️ 自动识别预发布版本标识

## 免安装使用 (推荐)

```sh
# 查看帮助
npx @kinngyo/np --help

# 查看版本
npx @kinngyo/np --version

# 交互式发布
npx @kinngyo/np

# 直接发布当前版本
npx @kinngyo/np publish

# 跳过 Git 检查发布
npx @kinngyo/np --skip-git-check

# 静默模式（只显示错误）
npx @kinngyo/np --silent
```

## 安装

```sh
# yarn
yarn add @kinngyo/np -D

# npm
npm i @kinngyo/np --save-dev
```

## 命令使用

```sh
# 查看帮助
np --help

# 查看版本
np --version

# 交互式发布（选择版本 → 发布）
np

# 直接发布当前版本（不修改版本号）
np publish

# 跳过 Git 检查发布
np --skip-git-check

# 静默模式
np --silent

# 完整参数示例
np --remote=false --tag=beta --access=public --registry=https://registry.npmjs.org/
```

### 命令参数

| 参数             | 类型    | 必填 | 可选值             | 说明                          | 默认值        |
| ---------------- | ------- | ---- | ------------------ | ----------------------------- | ------------- |
| -h, --help       | -       | 否   | -                  | 显示帮助信息                  | -             |
| -v, --version    | -       | 否   | -                  | 显示版本号                    | -             |
| -r, --root       | string  | 否   | -                  | 运行根目录                    | process.cwd() |
| --remote         | boolean | 否   | -                  | 是否远程查询版本              | true          |
| --prid           | string  | 否   | -                  | 预览版标识 (alpha/beta/rc 等) | 自动识别      |
| --tag            | string  | 否   | -                  | 发布 tag 标签                 | 自动识别      |
| --access         | string  | 否   | public, restricted | 包访问权限                    | -             |
| --registry       | string  | 否   | -                  | 发布源                        | -             |
| --skip-git-check | boolean | 否   | -                  | 跳过 Git 工作区检查           | false         |
| --silent         | boolean | 否   | -                  | 静默模式，只显示错误信息      | false         |

### 子命令

| 命令         | 说明                                     |
| ------------ | ---------------------------------------- |
| `np`         | 交互式发布，自动检测版本并提示选择新版本 |
| `np publish` | 直接发布当前版本，不修改版本号           |

## API 使用

```ts
import NpmPublish from '@kinngyo/np'

const np = new NpmPublish(options?: Partial<NpmPublishOption>)

// 执行 Git 发布前检查
await np.performGitChecks()

// 获取远程最新版本
await np.getRemoteVersion()

// 创建版本选择（返回推荐的基础版本和是否直接发布）
const { version, directPublish } = await np.createVersion(remoteVersion)

// 选择具体的发布版本号
await np.createReleaseVersion(version)

// 更新 package.json 中的 version
await np.updatePackageJson(version)

// 发布到 npm
await np.publish(version)
```

## 类型定义

```ts
interface NpmPublishOption {
    /* 工作目录 */
    root: string
    /* 是否远程查询版本 */
    remote: boolean
    /* 预览版标识 */
    prid: string
    /* 发布 tag 标签 */
    tag: string
    /* 包访问权限 */
    access: 'public' | 'restricted'
    /* 发布源 */
    registry: string
    /* 是否跳过 Git 检查 */
    skipGitCheck: boolean
}
```

## publishConfig 配置

支持通过 `package.json` 中的 `publishConfig` 设置默认配置：

```json
{
    "publishConfig": {
        "registry": "https://registry.npmjs.org/",
        "access": "public",
        "tag": "beta"
    }
}
```

### 配置优先级

```
命令行参数 > publishConfig
```

## 版本发布流程

```
开始
  │
  ▼
Git 工作区检查 ──(未通过)──▶ 报错退出
  │
  │ (通过或跳过)
  ▼
查询远程最新版本
  │
  ▼
比对本地/远程版本
  │
  ├─ 远程未发布 ──▶ 询问是否直接发布本地版本
  │
  ├─ 本地 > 远程 ──▶ 询问基于哪个版本升级
  │
  ├─ 本地 = 远程 ──▶ 必须升级版本号
  │
  └─ 本地 < 远程 ──▶ 强制基于远程版本升级
  │
  ▼
选择具体版本号 (patch/minor/major/prerelease 等)
  │
  ▼
更新 package.json
  │
  ▼
执行 npm publish
  │
  ▼
完成
```

## 注意事项

1. **登录状态**：请确保已执行 `npm login` 完成登录
2. **Git 检查**：默认会检查 Git 工作区是否干净，有未提交更改时会报错
3. **跳过检查**：如需跳过 Git 检查，请使用 `--skip-git-check` 参数
4. **非 Git 项目**：如果项目未关联 Git 或 Git 未安装，会自动跳过 Git 检查

## License

MIT