npm package: @ricardopang/pf-cli
Description: PF-CLI - 从API自动生成TypeScript类型定义 + AI智能Git工作流助手
Author: RicardoPang
Latest version: 1.0.0

# PF-CLI

<div align="center">

```
   ____  _____      ____ _     ___
 |  _ \|  ___|    / ___| |   |_ _|
 | |_) | |_ _____| |   | |    | |
 |  __/|  _|_____| |___| |___ | |
 |_|   |_|        \____|_____|___|
```

[![npm version](https://img.shields.io/npm/v/@ricardopang/pf-cli.svg)](https://www.npmjs.com/package/@ricardopang/pf-cli)
[![License](https://img.shields.io/npm/l/@ricardopang/pf-cli.svg)](https://github.com/RicardoPang/pf-cli/blob/main/LICENSE)
[![Downloads](https://img.shields.io/npm/dm/@ricardopang/pf-cli.svg)](https://www.npmjs.com/package/@ricardopang/pf-cli)

**从API自动生成TypeScript类型定义 + AI智能Git工作流助手**

</div>

## 功能特性

- **API转类型**: 从任何REST API自动生成TypeScript接口定义
- **AI Git助手**: 智能分析代码变更，自动生成commit信息
- **完整Git工作流**: 一键完成 add -> commit -> pull -> push
- **交互式界面**: 友好的命令行交互体验
- **VSCode集成**: 支持一键在VSCode中打开生成的文件

## 安装

```bash
# npm
npm install -g @ricardopang/pf-cli

# pnpm
pnpm add -g @ricardopang/pf-cli

# yarn
yarn global add @ricardopang/pf-cli
```

## 快速开始

### 功能一：API转TypeScript类型

#### 交互式模式

```bash
pf-gen
```

按照提示输入：
1. API URL地址
2. 类型名称
3. 保存位置

#### 命令行模式

```bash
# 基础用法
pf-gen -u https://api.example.com/user -n User

# 指定保存路径
pf-gen -u https://api.example.com/posts -n BlogPost -p ./types

# 查看帮助
pf-gen --help
```

#### 参数说明

| 参数 | 简写 | 说明 | 默认值 |
|------|------|------|--------|
| `--url` | `-u` | API接口地址 | - |
| `--name` | `-n` | 生成的类型名称 | `ApiTypes` |
| `--path` | `-p` | 文件保存路径 | 当前目录 |
| `--version` | `-V` | 显示版本信息 | - |
| `--help` | `-h` | 显示帮助信息 | - |

#### 示例

```bash
# 生成用户类型
pf-gen -u https://jsonplaceholder.typicode.com/users/1 -n UserProfile
```

生成结果：

```typescript
export interface UserProfile {
    address:  Address;
    company:  Company;
    email:    string;
    id:       number;
    name:     string;
    phone:    string;
    username: string;
    website:  string;
}

export interface Address {
    city:    string;
    geo:     Geo;
    street:  string;
    suite:   string;
    zipcode: string;
}

export interface Geo {
    lat: string;
    lng: string;
}

export interface Company {
    bs:          string;
    catchPhrase: string;
    name:        string;
}
```

---

### 功能二：AI Git工作流助手

使用AI智能分析代码变更，自动生成commit信息，并执行完整的Git工作流。

```bash
pf-gen commit
# 或简写
pf-gen c
```

#### 工作流程

1. **Git Add** - 选择要添加的文件
   - 添加所有文件 (`git add .`)
   - 只添加已跟踪的修改文件 (`git add -u`)
   - 手动选择文件

2. **AI Commit** - AI分析变更生成commit信息
   - 自动分析代码变更
   - 生成中文commit信息（带emoji）
   - 支持确认或自定义修改

3. **Git Pull** - 自动拉取远程更新
   - 检测合并冲突
   - 自动跳过无远程分支的情况

4. **Git Push** - 推送到远程仓库
   - 自动设置上游分支

#### 配置OpenAI API

AI commit功能需要配置OpenAI API密钥：

```bash
# 方式一：环境变量
export OPENAI_API_KEY="sk-your-api-key"

# 方式二：在项目根目录创建 .env 文件
echo 'OPENAI_API_KEY=sk-your-api-key' > .env
```

如果未配置API密钥或API不可用，会自动回退到手动输入模式。

#### Commit信息格式

AI生成的commit信息遵循以下格式：

```
<emoji> <动作>: <具体内容>
```

示例：
- `🐛 修复: 用户登录时的空指针异常`
- `✨ 新增: OpenAI智能commit信息生成功能`
- `🎨 优化: 重构用户服务的代码结构`
- `📝 更新: 完善README文档说明`
- `🔧 配置: 添加ESLint规则配置`

## 完整命令参考

```bash
# 类型生成 - 交互式
pf-gen

# 类型生成 - 命令行
pf-gen -u <url> -n <name> [-p <path>]

# AI Git工作流
pf-gen commit
pf-gen c

# 版本信息
pf-gen --version
pf-gen -V

# 帮助信息
pf-gen --help
pf-gen -h
```

## 系统要求

- Node.js >= 14.0.0
- Git（用于Git工作流功能）
- VSCode（可选，用于自动打开文件）

## 依赖说明

| 依赖 | 用途 |
|------|------|
| commander | CLI参数解析 |
| inquirer | 交互式问答 |
| quicktype-core | TypeScript类型生成 |
| openai | AI commit信息生成 |
| chalk | 终端彩色输出 |
| ora | 加载动画 |
| figlet | ASCII艺术字 |
| shelljs | 跨平台Shell命令 |

## 常见问题

### Q: API请求失败怎么办？

确保API URL可访问，且返回有效的JSON数据。可以先在浏览器中测试URL。

### Q: AI commit功能不工作？

1. 检查是否配置了有效的 `OPENAI_API_KEY`
2. 确保API密钥有足够的配额
3. 如果API不可用，会自动回退到手动输入模式

### Q: 生成的类型不正确？

如果API返回数组，工具会自动取第一个元素作为类型推断样本。确保返回数据具有代表性。

### Q: Git push失败？

1. 检查是否有远程仓库权限
2. 如果是新分支，工具会自动设置上游分支
3. 如果有合并冲突，需要手动解决

## License

MIT

## 作者

RicardoPang

## 链接

- [GitHub](https://github.com/RicardoPang/pf-cli)
- [npm](https://www.npmjs.com/package/@ricardopang/pf-cli)
- [Issues](https://github.com/RicardoPang/pf-cli/issues)