# PushGo MVP

小白一键把本地项目推送到 GitHub / Gitee / Gitea 的桌面应用（Electron + React + TypeScript + Vite）。

## 功能覆盖

- 启动自动检测 Git 安装状态与授权组件可用性
- 平台选择（GitHub / Gitee / Gitea）
- 项目文件夹仅支持“点击浏览”选择（已移除拖拽入口，提升跨平台稳定性）
- 仓库 URL 格式与平台匹配校验
- 系统浏览器授权（不使用内嵌网页）
- Gitea 在自建场景下优先按仓库 URL 域名发起登录/授权
- 自动执行 `git init` / `add -A` / `commit` / `remote` / `push`
- 推送默认 `main`，必要时自动回退 `master`
- 成功页支持复制仓库链接和浏览器打开
- 不保存历史记录（路径、URL、操作记录不落盘）
- 登录 token 仅保留在进程内存（关闭应用即失效）

## 技术栈

- Electron
- React + React Router
- TypeScript
- Vite
- Node `child_process` 调用本机 `git`

## 目录结构

```txt
src/
  main/        # Electron 主进程、服务层、IPC
  preload/     # 白名单桥接 API
  renderer/    # React UI 与流程页面
  shared/      # 前后端共享类型与通道常量
docs/
  ai-progress.md
  ai-handoff.md
  git-identity-setup.md
```

Git 身份设置教程：`docs/git-identity-setup.md`

## 本地运行

### 1) 安装依赖

```bash
npm install
```

### 2) 开发启动

```bash
npm run dev
```

### 3) 构建

```bash
npm run build
```

### 4) 打包

```bash
npm run package
```

## OAuth 配置（可选增强）

当前支持两种模式：

- 默认模式（未配置 OAuth env）：推送时走系统 git 凭据授权链路（如 Git Credential Manager）。首次通常会出现登录/授权窗口，后续会复用授权；若在平台端撤销授权会再次触发。
- 增强模式（配置 OAuth env）：走完整 OAuth 授权码流程并换取 token（仅内存保存，会话结束清空）。

说明：

- Gitea 域名优先级：`repoUrl > PUSHGO_GITEA_BASE_URL > https://gitea.com`。
- 若目标系统缺失 git 凭据助手，默认模式可能无法完成授权。

如需启用增强模式，请配置：

```bash
# GitHub OAuth App
export PUSHGO_GITHUB_CLIENT_ID=your_client_id
export PUSHGO_GITHUB_CLIENT_SECRET=your_client_secret

# Gitee OAuth App
export PUSHGO_GITEE_CLIENT_ID=your_client_id
export PUSHGO_GITEE_CLIENT_SECRET=your_client_secret

# Gitea OAuth App（可用自建域名）
export PUSHGO_GITEA_BASE_URL=https://gitea.com
export PUSHGO_GITEA_CLIENT_ID=your_client_id
export PUSHGO_GITEA_CLIENT_SECRET=your_client_secret
# 可选，默认 write:repository
export PUSHGO_GITEA_SCOPE=write:repository
```

授权回调采用本地临时端口（`http://127.0.0.1:{port}/oauth/callback`），请在 OAuth 应用配置中允许本地回调。

## IPC 通道

- `app:check-git`
- `auth:login`
- `auth:logout`
- `auth:status`
- `repo:validate-url`
- `git:select-folder`
- `push:run`
- `app:open-external`
- 事件：`push:progress`

## 错误提示策略

主流程使用统一中文错误对象：

```ts
{ code, message, actionText?, actionType? }
```

覆盖文档要求的核心错误码，包括：

- Git 未安装
- URL 格式错误 / 平台不匹配
- 授权取消 / 授权失败
- 仓库初始化失败
- 无变更提交
- 远端设置失败
- 推送鉴权失败 / 推送被拒绝
- 网络超时
- 未知错误

## 隐私与会话策略

- 不写入 localStorage 的历史数据
- 不落盘保存项目路径/仓库 URL 历史
- token 仅存内存 Map
- BrowserWindow 使用临时 session 分区（关闭应用即清空）

## 已知限制

- 默认模式依赖系统 git 凭据能力，若环境未安装/未启用可能无法完成首授。
- 若远端启用更严格策略（受保护分支、组织 SSO、强制签名），推送可能被拒绝。
- 当前为 MVP：不包含冲突可视化、分支管理、PR 流程等扩展能力。

## 故障排查（授权弹窗）

- 若你看到的是“终端要求用户名/密码”而不是浏览器授权弹窗，通常不是 `npm run dev` 本身的问题，而是当前 `git` 没有启用 `credential.helper`。
- 启动页会自动检测并尽量自动配置弹窗型凭据助手（GCM）；若仍未就绪会在页面顶部给出明确提示和跳转入口。
- 可用以下命令检查：

```bash
git config --get-all credential.helper
```

- 若为空，请安装并启用 Git Credential Manager（或在当前系统配置有效的 git 凭据助手）后重试。
- PushGo 在推送时会关闭终端口令提示并强制 GCM 交互模式；打包后无终端窗口时也应走浏览器/系统授权弹窗。