npm package: @luckyday/npm-test-publisher
Description: A CLI tool to automatically publish test versions of npm packages with branch-based versioning
Latest version: 1.0.0

# npm-test-publisher

<div align="center">

[![npm version](https://img.shields.io/npm/v/npm-test-publisher.svg)](https://www.npmjs.com/package/npm-test-publisher)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/node/v/npm-test-publisher.svg)](https://nodejs.org/)

**一个智能的npm包测试版本发布工具**

自动根据git分支生成测试版本号，一键发布测试包到npm

[English](./README.md) | 中文

</div>

## ✨ 功能特性

- 🔍 **自动版本检测** - 智能查询npm上包的最新版本号
- 🌿 **分支感知** - 自动获取当前git分支名并生成对应版本号
- 📦 **智能版本生成** - 自动生成格式为 `最新版本-分支名-1` 的测试版本号
- 🚀 **一键发布** - 自动更新版本号、发布包、恢复原始版本号
- 🧪 **预览模式** - 支持 `--dry-run` 预览操作，安全可靠
- 🏷️ **标签支持** - 支持自定义npm标签发布（如 `beta`、`alpha` 等）
- 🔄 **自动恢复** - 发布后自动恢复 `package.json` 原始版本号
- ⚡ **零配置** - 开箱即用，无需复杂配置

## 🚀 快速开始

### 安装

```bash
# 全局安装（推荐）
npm install -g npm-test-publisher

# 或作为项目依赖安装
npm install --save-dev npm-test-publisher
```

### 基本使用

在包含 `package.json` 的项目目录中运行：

```bash
# 简单使用
npm-test-publish

# 或使用完整命令
npm-test-publish publish
```

## 📖 详细使用指南

### 版本号生成规则

工具会根据以下规则自动生成测试版本号：

1. **查询最新版本** - 从npm获取当前包的最新发布版本
2. **获取分支名** - 读取当前git分支名
3. **清理分支名** - 移除特殊字符，确保版本号合法
4. **生成版本号** - 格式：`最新版本-分支名-1`

### 使用示例

假设你的包当前最新版本是 `0.8.0`：

```bash
# 在 main 分支
$ npm-test-publish
🚀 Starting test version publish process...
Current git branch: main
Latest npm version: 0.8.0
Generated test version: 0.8.0-main-1
✅ Successfully published your-package@0.8.0-main-1

# 在 feature/new-api 分支
$ git checkout -b feature/new-api
$ npm-test-publish
🚀 Starting test version publish process...
Current git branch: feature/new-api
Latest npm version: 0.8.0
Generated test version: 0.8.0-feature-new-api-1
✅ Successfully published your-package@0.8.0-feature-new-api-1
```

### 高级选项

```bash
# 预览模式 - 查看将要发布的内容，不实际发布
npm-test-publish publish --dry-run

# 使用自定义标签发布
npm-test-publish publish --tag beta

# 组合使用
npm-test-publish publish --tag alpha --dry-run

# 查看帮助信息
npm-test-publish --help
```

## 🎯 使用场景

### 1. 功能分支测试

在开发新功能时，快速发布测试版本供团队测试：

```bash
git checkout -b feature/user-authentication
# 开发代码...
npm-test-publish  # 发布 1.2.0-feature-user-authentication-1
```

### 2. 修复分支验证

在修复bug时，发布测试版本验证修复效果：

```bash
git checkout -b bugfix/fix-login-issue
# 修复代码...
npm-test-publish  # 发布 1.2.0-bugfix-fix-login-issue-1
```

### 3. 预发布验证

在正式发布前，使用不同标签发布预发布版本：

```bash
npm-test-publish publish --tag beta  # 发布到 beta 标签
npm-test-publish publish --tag alpha # 发布到 alpha 标签
```

## 🔧 工作流程

```mermaid
graph TD
    A[开始] --> B[检查 package.json]
    B --> C[获取当前 git 分支]
    C --> D[查询 npm 最新版本]
    D --> E[生成测试版本号]
    E --> F[更新 package.json]
    F --> G[发布到 npm]
    G --> H[恢复原始版本号]
    H --> I[完成]
    
    B --> J[错误: 未找到 package.json]
    C --> K[错误: 不在 git 仓库]
    G --> L[错误: 发布失败]
    
    J --> M[退出]
    K --> M
    L --> N[恢复版本号]
    N --> M
```

## 📋 完整示例

让我们通过一个完整的示例来演示工具的使用：

### 1. 准备项目

```bash
# 创建一个新的npm包项目
mkdir my-awesome-package
cd my-awesome-package

# 初始化项目
npm init -y

# 安装工具
npm install -g npm-test-publisher
```

### 2. 设置git仓库

```bash
# 初始化git仓库
git init
git add .
git commit -m "Initial commit"

# 创建功能分支
git checkout -b feature/awesome-feature
```

### 3. 发布测试版本

```bash
# 预览将要发布的内容
npm-test-publish publish --dry-run

# 输出示例：
# 🚀 Starting test version publish process...
# Current git branch: feature/awesome-feature
# Latest npm version: 1.0.0
# Generated test version: 1.0.0-feature-awesome-feature-1
# [DRY RUN] Would publish version: 1.0.0-feature-awesome-feature-1

# 实际发布
npm-test-publish publish

# 输出示例：
# 🚀 Starting test version publish process...
# Current git branch: feature/awesome-feature
# Latest npm version: 1.0.0
# Generated test version: 1.0.0-feature-awesome-feature-1
# Updated package.json version to 1.0.0-feature-awesome-feature-1
# Publishing version 1.0.0-feature-awesome-feature-1 with tag test...
# ✅ Successfully published my-awesome-package@1.0.0-feature-awesome-feature-1 with tag test
# Restored original package.json version
```

### 4. 验证发布

```bash
# 查看发布的版本
npm view my-awesome-package versions --json

# 安装测试版本
npm install my-awesome-package@1.0.0-feature-awesome-feature-1
```

## ⚠️ 注意事项

### 前置条件

- ✅ 确保在git仓库中运行
- ✅ 确保已登录npm（运行 `npm login`）
- ✅ 确保包名在npm上可用或已发布过

### 安全特性

- 🔒 **自动恢复** - 无论发布成功与否，都会尝试恢复原始版本号
- 🧪 **预览模式** - 使用 `--dry-run` 可以安全预览操作
- 🛡️ **错误处理** - 完善的错误处理和提示信息

### 版本号限制

- 分支名中的特殊字符会被自动清理
- 生成的版本号符合semver规范
- 如果无法查询npm版本，将使用当前 `package.json` 中的版本

## 🛠️ 开发

### 构建项目

```bash
# 克隆仓库
git clone <repository-url>
cd npm-test-publisher

# 安装依赖
npm install

# 构建项目
npm run build

# 开发模式（监听文件变化）
npm run dev
```

### 测试

```bash
# 在测试项目中运行
npm-test-publish publish --dry-run
```

## 📄 许可证

MIT License - 详见 [LICENSE](LICENSE) 文件

## 🤝 贡献

欢迎提交 Issue 和 Pull Request！

1. Fork 本仓库
2. 创建你的特性分支 (`git checkout -b feature/AmazingFeature`)
3. 提交你的更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开一个 Pull Request

## 📞 支持

如果你遇到任何问题或有建议，请：

- 📧 提交 [Issue](https://github.com/your-username/npm-test-publisher/issues)
- 💬 参与 [讨论](https://github.com/your-username/npm-test-publisher/discussions)

---

<div align="center">

**让npm包测试发布变得简单高效！** ⚡

Made with ❤️ by [Your Name]

</div>