@cc123hh/gitee-cli 0.0.0-stage → 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 cc123hh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,236 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+<h1 align="center">gitee</h1>
+
+<p align="center">
+  <img src="https://gitee.com/cc123hh/gitee-cli/raw/main/docs/banner.jpg" alt="gitee banner" width="760">
+</p>
+
+<p align="center">
+  <img src="https://gitee.com/cc123hh/gitee-cli/raw/main/docs/badges/python.svg" alt="python 3.8+">
+  <img src="https://gitee.com/cc123hh/gitee-cli/raw/main/docs/badges/platform.svg" alt="platform">
+  <img src="https://gitee.com/cc123hh/gitee-cli/raw/main/docs/badges/deps.svg" alt="dependencies">
+  <img src="https://gitee.com/cc123hh/gitee-cli/raw/main/docs/badges/tests.svg" alt="tests">
+  <img src="https://gitee.com/cc123hh/gitee-cli/raw/main/docs/badges/license.svg" alt="license">
+</p>
+
+<p align="center">
+  <b>在终端里把 Gitee 管起来：建仓、推送、看 Issue，一条命令。</b><br>
+  零依赖 · 跨平台 · 单文件脚本 · 直接调 Gitee OpenAPI v5
+</p>
+
+---
+
+## 📑 目录
+
+- [快速开始](#-快速开始)
+- [特性](#-特性)
+- [安装](#-安装)
+- [配置](#-配置)
+- [命令一览](#-命令一览)
+- [常见问题](#-常见问题)
+- [License](#license)
+
+## 🚀 快速开始
+
+```console
+$ gitee list
+仓库                                             可见性    ★    更新
+--------------------------------------------------------------------
+cc123hh/imgen-cli                                公开      0   2026-11-04 13:15
+cc123hh/emb-cli                                  公开      0   2026-11-04 12:40
+cc123hh/private-notes                            私有      0   2026-11-03 21:08
+
+$ gitee info emb-cli
+仓库:   cc123hh/emb-cli
+地址:   https://gitee.com/cc123hh/emb-cli
+可见性: 公开
+统计:   ★ 0  Fork 0  Watch 1
+默认分支: main
+
+$ cd ~/Scripts/new-tool && gitee push --public -d "我的新工具"
+仓库不存在，正在创建 cc123hh/new-tool …
+推送 main → https://gitee.com/cc123hh/new-tool.git …
+已添加 remote origin
+已设为公开
+完成：https://gitee.com/cc123hh/new-tool
+```
+
+## ✨ 特性
+
+| | |
+|---|---|
+| 🪶 **零依赖** | Python 版只用标准库；npm 版纯 Node 内置模块，双实现 |
+| 🖥️ **跨平台** | macOS / Linux / Windows，安装脚本全覆盖 |
+| 📦 **仓库管理** | 列出、查看、创建、删除、公开/私有切换 |
+| 🚀 **建仓推送一体** | `gitee push` 自动建仓 + 推送 + 设可见性 |
+| 📋 **Issue / PR** | 命令行直接看列表与状态 |
+| 🀄 **中文对齐** | 表格按中日韩字符显示宽度排版，不乱 |
+| 🔒 **令牌不落库** | 只从 `GITEE_TOKEN` 读取 |
+
+## 📥 安装
+
+> 前提：Python 3.8+（npm 版为纯 JS，只需 Node ≥ 16）
+
+### macOS / Linux
+
+```bash
+git clone https://gitee.com/cc123hh/gitee-cli.git
+cd gitee-cli
+./install.sh
+```
+
+### Windows
+
+```powershell
+git clone https://gitee.com/cc123hh/gitee-cli.git
+cd gitee-cli
+powershell -ExecutionPolicy Bypass -File .\install.ps1
+```
+
+免安装直接用：`gitee.cmd list`
+
+### 所有平台（pipx）
+
+```bash
+pipx install git+https://gitee.com/cc123hh/gitee-cli.git
+```
+
+### 所有平台（npm / pnpm）
+
+纯 Node 实现（无需 Python），装完即得 `gitee` 命令：
+
+```bash
+pnpm add -g @cc123hh/gitee-cli    # 或 npm i -g @cc123hh/gitee-cli
+```
+
+## ⚙️ 配置
+
+优先级（高 → 低）：**命令行参数（`--token` / `--api` / `--proxy` / `--timeout`）> 内部配置文件 > 环境变量 > 内置默认值**
+
+推荐用内部配置持久化（不依赖环境变量注入，GUI 进程 / 非交互 shell 也稳定可用）：
+
+```bash
+gitee set                       # 查看当前配置及来源（token 自动脱敏）
+gitee set token <TOKEN>         # 设置私人令牌（写入 ~/.config/gitee/config.json，600 权限）
+gitee set proxy <URL>           # 设置代理
+gitee unset token               # 删除某项
+```
+
+环境变量作为兜底层仍然支持：
+
+```bash
+# 必需（除非已 gitee set token）：私人令牌（https://gitee.com/profile/personal_access_tokens）
+export GITEE_TOKEN="你的令牌"
+
+# 可选
+export GITEE_API="https://gitee.com/api/v5"
+export GITEE_PROXY="http://127.0.0.1:7890"
+```
+
+Windows：`setx GITEE_TOKEN "你的令牌"`
+
+> 令牌权限建议只勾：`projects`（仓库读写）、`pull_requests`、`issues`。
+
+## 🧰 命令一览
+
+### 账号
+
+```bash
+gitee whoami
+```
+
+### 仓库
+
+```bash
+gitee list                       # 我的仓库（按更新时间）
+gitee list -n 50 --json          # 更多条数 / 原始 JSON
+gitee info emb-cli               # 详情
+gitee create my-tool -d "简介"    # 新建（默认私有）
+gitee create my-tool --public    # 尝试公开（空仓库需推送后生效）
+gitee public my-tool             # 设为公开
+gitee private my-tool            # 设为私有
+gitee delete my-tool -y          # 删除（-y 跳过确认）
+```
+
+### 一键建仓并推送
+
+```bash
+cd ~/Scripts/mytool
+gitee push --public -d "我的小工具"
+```
+
+会自动：检查仓库是否存在 → 不存在则创建 → `git push` → 添加 `origin` → 需要时设为公开。
+
+### Issue / Pull Request
+
+```bash
+gitee issues emb-cli                          # 列出 Issue
+gitee issues emb-cli -s all -n 50
+gitee issue view emb-cli IKVADU               # 查看详情
+gitee issue create emb-cli -t "发现bug" -b "复现步骤" -l bug -a 用户名   # 创建
+gitee issue edit emb-cli IKVADU -t "新标题" -b "新正文" -l bug,docs     # 修改
+gitee issue edit emb-cli IKVADU -f 正文.md     # 正文从 UTF-8 文件读（与 -b 互斥）
+gitee issue close emb-cli IKVADU              # 关闭（open 为重开）
+gitee issue comment emb-cli IKVADU -m "已修复"   # 加评论
+gitee close emb-cli IKVADU                    # 顶层快捷：关闭 / 重开
+gitee reopen emb-cli IKVADU
+gitee prs emb-cli
+```
+
+`repo` 参数写 `仓库名` 会自动补上你的用户名，也可以写完整的 `owner/repo`；
+Issue 相关命令省略 `repo` 时取当前目录同名仓库，只写编号也能定位
+（如 `gitee issue view IKVADU`）。Issue 编号是 Gitee 生成的字符串标识
+（如 `IKVADU`），带不带 `#` 前缀都可以（shell 里 `#` 要加引号）。
+Gitee 无删除 Issue 的接口（已实测 405），`issue delete` 不提供。
+
+## 📋 参数
+
+| 参数 | 适用命令 | 说明 |
+|---|---|---|
+| `-n/--limit` | list / issues / prs | 返回条数 |
+| `--json` | list | 输出原始 JSON |
+| `-s/--state` | issues / prs / issue | 列表筛选 `open`/`closed`/`all`；`issue edit` 修改状态 `open`/`progressing`/`closed` |
+| `-t/--title` | issue create / edit | 标题（create 必填） |
+| `-b/--body` | issue create / edit | 正文（与 `-f` 互斥） |
+| `-f/--file` | issue create / edit / comment | 从 UTF-8 文件读正文/评论 |
+| `-l/--labels` | issue create / edit | 标签，逗号分隔 |
+| `-a/--assignee` | issue create / edit | 负责人 username |
+| `-m/--message` | issue comment | 评论内容 |
+| `-y/--yes` | delete | 跳过确认 |
+| `-d/--description` | create / push | 仓库简介 |
+| `--public` | create / push | 目标可见性 |
+| `--name` | push | 仓库名（默认取目录名） |
+| `--api/--proxy/--timeout` | 全部 | 覆盖环境变量 |
+
+## ❓ 常见问题
+
+<details>
+<summary><b>提示鉴权失败（401/403）？</b></summary>
+
+检查 `GITEE_TOKEN` 是否有效、是否勾选 `projects` 权限；令牌过期请重新生成。
+</details>
+
+<details>
+<summary><b>创建时选了公开，结果还是私有？</b></summary>
+
+Gitee 限制空仓库不能设为公开。推送首个提交后再执行 `gitee public 仓库名`；用 `gitee push --public` 会自动在推送后切换。
+</details>
+
+<details>
+<summary><b>push 报「不是 git 仓库」？</b></summary>
+
+`gitee push` 不会替你 `git init`，只负责建仓与推送。请先初始化并提交。
+</details>
+
+<details>
+<summary><b>表格里中文对不齐？</b></summary>
+
+已按 `unicodedata.east_asian_width` 计算显示宽度；若终端字体非等宽仍可能有偏差，属字体问题。
+</details>
+
+## 🤝 贡献
+
+欢迎 Issue / PR。
+
+## License
+
+[MIT](https://gitee.com/cc123hh/gitee-cli/blob/main/LICENSE)