@cc123hh/gitee-cli 0.0.0-stage → 0.4.0

package/bin/gitee.js

@@ -0,0 +1,838 @@
+#!/usr/bin/env node
+"use strict";
+/**
+ * gitee — Gitee 仓库管理命令行工具（纯 Node 零依赖，调 Gitee OpenAPI v5）
+ *
+ * 用法示例：
+ *     gitee list                          # 列出我的仓库（按更新时间排序）
+ *     gitee info cc123hh/imgen-cli        # 查看某个仓库
+ *     gitee create my-tool -d "说明"       # 新建仓库（默认私有）
+ *     gitee public my-tool                # 设为公开
+ *     gitee delete my-tool -y             # 删除仓库
+ *     gitee push --public                 # 当前目录建仓并推送
+ *
+ * 配置优先级（高 → 低）：
+ *     1. 命令行参数（--token / --api / --proxy / --timeout，临时覆盖）
+ *     2. 内部配置文件（gitee set 写入，持久生效，推荐）
+ *     3. 环境变量（GITEE_TOKEN / GITEE_API / GITEE_PROXY）
+ *     4. 内置默认值
+ */
+const fs = require("fs");
+const path = require("path");
+const spawnSync = require("child_process").spawnSync;
+const readline = require("readline");
+const { homedir, normKey, loadConfig, saveConfig, displayValue,
+  resolveValue, showConfig } = require("../lib/config.js");
+const { requestOnce, TimeoutError } = require("../lib/httputil.js");
+const { parse } = require("../lib/args.js");
+
+const DEFAULT_API = "https://gitee.com/api/v5";
+const DEFAULT_TIMEOUT = 30;
+const EXIT_OK = 0, EXIT_USAGE = 2, EXIT_AUTH = 3, EXIT_API = 5, EXIT_GIT = 6;
+
+const CONFIG_PATH = path.join(homedir(), ".config", "gitee", "config.json");
+const CONFIG_KEYS = ["token", "api", "proxy", "timeout"];
+
+// --------------------------------------------------------------------------- //
+// 内部配置管理（gitee set / gitee unset）
+// --------------------------------------------------------------------------- //
+function configRows(cfg) {
+  return [
+    { label: "token", key: "token", env: "GITEE_TOKEN", default: null, secret: true, cfg },
+    { label: "api", key: "api", env: "GITEE_API", default: DEFAULT_API, cfg },
+    { label: "proxy", key: "proxy", env: "GITEE_PROXY", default: null, cfg },
+    { label: "timeout", key: "timeout", env: null, default: DEFAULT_TIMEOUT, cfg },
+  ];
+}
+
+function cmdSetConfig(opts) {
+  if (opts.key === undefined || opts.key === null) {
+    showConfig(configRows(loadConfig(CONFIG_PATH, CONFIG_KEYS)), CONFIG_PATH);
+    return EXIT_OK;
+  }
+  if (opts.value === undefined || opts.value === null) {
+    console.error(`用法：gitee set <key> <value>（可用 key：${CONFIG_KEYS.join(" / ")}，`
+      + "不带参数列出当前配置）");
+    return EXIT_USAGE;
+  }
+  const key = normKey(opts.key, CONFIG_KEYS);
+  if (!key) {
+    console.error(`错误：未知配置项 ${JSON.stringify(opts.key)}，可用：${CONFIG_KEYS.join(" / ")}`);
+    return EXIT_USAGE;
+  }
+  let value = opts.value;
+  if (key === "timeout") {
+    const n = Number(opts.value);
+    if (!Number.isInteger(n) || n <= 0) {
+      console.error(`错误：timeout 必须为正整数，收到 ${JSON.stringify(opts.value)}`);
+      return EXIT_USAGE;
+    }
+    value = n;
+  } else if (key === "api") {
+    value = opts.value.replace(/\/+$/, "");
+  }
+  const cfg = loadConfig(CONFIG_PATH, CONFIG_KEYS);
+  cfg[key] = value;
+  saveConfig(CONFIG_PATH, cfg);
+  console.log(`✅ 已写入 ${key} = ${displayValue(key === "token", value)}`);
+  console.log(`   配置文件：${CONFIG_PATH}`);
+  return EXIT_OK;
+}
+
+function cmdUnsetConfig(opts) {
+  const key = normKey(opts.key, CONFIG_KEYS);
+  if (!key) {
+    console.error(`错误：未知配置项 ${JSON.stringify(opts.key)}，可用：${CONFIG_KEYS.join(" / ")}`);
+    return EXIT_USAGE;
+  }
+  const cfg = loadConfig(CONFIG_PATH, CONFIG_KEYS);
+  if (!(key in cfg)) {
+    console.error(`错误：${opts.key} 未在内部配置中设置（配置文件：${CONFIG_PATH}）`);
+    return EXIT_USAGE;
+  }
+  delete cfg[key];
+  saveConfig(CONFIG_PATH, cfg);
+  console.log(`✅ 已删除配置项 ${key}`);
+  return EXIT_OK;
+}
+
+// --------------------------------------------------------------------------- //
+// HTTP 客户端
+// --------------------------------------------------------------------------- //
+class GiteeError extends Error {}
+
+class Client {
+  constructor(token, api, proxy, timeout) {
+    this.token = token;
+    this.api = api.replace(/\/+$/, "");
+    this.proxy = proxy;
+    this.timeout = timeout;
+  }
+
+  async _request(method, path, params, form) {
+    const q = new URLSearchParams();
+    for (const [k, v] of Object.entries(params || {})) q.set(k, String(v));
+    q.set("access_token", this.token);
+    const urlStr = `${this.api}${path}?${q.toString()}`;
+    const headers = {};
+    let body = null;
+    if (form) {
+      const f = new URLSearchParams();
+      for (const [k, v] of Object.entries(form)) f.set(k, String(v));
+      body = Buffer.from(f.toString(), "utf8");
+      headers["Content-Type"] = "application/x-www-form-urlencoded";
+    }
+    let res;
+    try {
+      res = await requestOnce({
+        urlStr, method, headers, body, proxy: this.proxy, timeoutSec: this.timeout,
+      });
+    } catch (e) {
+      const reason = e instanceof TimeoutError ? "timed out" : e.message;
+      throw new GiteeError(`网络错误：${reason}（可设置 GITEE_PROXY 走代理）`);
+    }
+    const text = res.body.toString("utf8");
+    if (res.status >= 400) {
+      const detail = text.slice(0, 300);
+      if (res.status === 401 || res.status === 403) {
+        throw new GiteeError(`鉴权失败（HTTP ${res.status}）：检查 GITEE_TOKEN 是否有效`
+          + ` / 权限是否足够。${detail}`);
+      }
+      if (res.status === 404) {
+        throw new GiteeError(`资源不存在（HTTP 404）：${path}`);
+      }
+      throw new GiteeError(`HTTP ${res.status}：${detail}`);
+    }
+    return text.trim() ? JSON.parse(text) : {};
+  }
+
+  get(path, params) { return this._request("GET", path, params); }
+  post(path, form) { return this._request("POST", path, null, form); }
+  patch(path, form) { return this._request("PATCH", path, null, form); }
+  delete(path) { return this._request("DELETE", path); }
+}
+
+// --------------------------------------------------------------------------- //
+// 终端对齐辅助
+// --------------------------------------------------------------------------- //
+function width(text) {
+  let n = 0;
+  for (const ch of text) n += ch.codePointAt(0) > 0x2e7f ? 2 : 1;
+  return n;
+}
+
+function pad(text, w) {
+  return text + " ".repeat(Math.max(0, w - width(text)));
+}
+
+// --------------------------------------------------------------------------- //
+// 命令实现
+// --------------------------------------------------------------------------- //
+async function cmdWhoami(client) {
+  const user = await client.get("/user");
+  console.log(`${user.login}  (${user.name || "未设置昵称"})`);
+  console.log(`  主页: ${user.html_url}`);
+  console.log(`  邮箱: ${user.email || "未公开"}`);
+  return EXIT_OK;
+}
+
+async function cmdList(client, opts) {
+  const repos = await client.get("/user/repos", {
+    sort: "updated", per_page: String(opts.limit), page: "1",
+  });
+  if (!repos.length) {
+    console.log("没有仓库");
+    return EXIT_OK;
+  }
+  if (opts.json) {
+    console.log(JSON.stringify(repos, null, 2));
+    return EXIT_OK;
+  }
+  const nameW = Math.max(...repos.map((r) => width(r.full_name || "")), 8) + 2;
+  const header = pad("仓库", nameW) + pad("可见性", 8) + "  ★    更新";
+  console.log(header);
+  console.log("-".repeat(width(header)));
+  for (const repo of repos) {
+    const vis = repo.private ? "私有" : "公开";
+    const stars = String(repo.stargazers_count ?? 0).padStart(3);
+    const updated = (repo.updated_at || "").slice(0, 16).replace("T", " ");
+    console.log(pad(repo.full_name || "", nameW) + pad(vis, 8) + `${stars}   ${updated}`);
+  }
+  return EXIT_OK;
+}
+
+async function splitRepo(name, client) {
+  // 把 'repo' 或 'owner/repo' 规范成 'owner/repo'
+  if (name.includes("/")) return name;
+  const user = await client.get("/user");
+  return `${user.login}/${name}`;
+}
+
+async function cmdInfo(client, opts) {
+  const full = await splitRepo(opts.repo, client);
+  const repo = await client.get(`/repos/${full}`);
+  console.log(`仓库:   ${repo.full_name}`);
+  console.log(`地址:   ${repo.html_url}`);
+  console.log(`可见性: ${repo.private ? "私有" : "公开"}`);
+  console.log(`描述:   ${repo.description || "（无）"}`);
+  console.log(`统计:   ★ ${repo.stargazers_count ?? 0}  `
+    + `Fork ${repo.forks_count ?? 0}  `
+    + `Watch ${repo.watchers_count ?? 0}`);
+  console.log(`默认分支: ${repo.default_branch}`);
+  console.log(`更新于: ${repo.updated_at}`);
+  return EXIT_OK;
+}
+
+async function cmdCreate(client, opts) {
+  const user = await client.get("/user");
+  const owner = user.login;
+  const form = { name: opts.name, private: opts.public ? "false" : "true" };
+  if (opts.description) form.description = opts.description;
+  const repo = await client.post("/user/repos", form);
+  const full = repo.full_name || `${owner}/${opts.name}`;
+  const actualPrivate = repo.private !== false;
+  console.log(`已创建: ${full}`);
+  if (opts.public && actualPrivate) {
+    console.log(`提示：Gitee 不允许空仓库直接设为公开，推送首个提交后执行 `
+      + `\`gitee public ${opts.name}\` 即可。`);
+  }
+  return EXIT_OK;
+}
+
+async function cmdSetVisibility(client, opts, privateMode) {
+  const full = await splitRepo(opts.repo, client);
+  await client.patch(`/repos/${full}`, {
+    name: full.split("/")[1],
+    private: privateMode ? "true" : "false",
+  });
+  const repo = await client.get(`/repos/${full}`);
+  console.log(`${full} 现在是${repo.private ? "私有" : "公开"}仓库`);
+  return EXIT_OK;
+}
+
+async function ask(question) {
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    return (await rl.question(question)).trim();
+  } finally {
+    rl.close();
+  }
+}
+
+async function cmdDelete(client, opts) {
+  const full = await splitRepo(opts.repo, client);
+  if (!opts.yes) {
+    const answer = await ask(`确认删除 ${full}？（不可恢复，输入 yes 继续）：`);
+    if (answer !== "yes") {
+      console.log("已取消");
+      return EXIT_OK;
+    }
+  }
+  await client.delete(`/repos/${full}`);
+  console.log(`已删除 ${full}`);
+  return EXIT_OK;
+}
+
+async function parseRepoArg(opts, client) {
+  const name = opts.repo !== undefined && opts.repo !== null
+    ? opts.repo
+    : path.basename(process.cwd());
+  return splitRepo(name, client);
+}
+
+async function cmdIssues(client, opts) {
+  const full = await parseRepoArg(opts, client);
+  const items = await client.get(`/repos/${full}/issues`, {
+    state: opts.state, per_page: String(opts.limit),
+  });
+  if (!items.length) {
+    console.log(`${full}: 没有 Issue`);
+    return EXIT_OK;
+  }
+  for (const it of items) {
+    const user = (it.user && it.user.login) || "?";
+    console.log(`#${String(it.number).padEnd(5)} [${String(it.state).padEnd(6)}] `
+      + `${it.title}  @${user}`);
+  }
+  return EXIT_OK;
+}
+
+async function cmdPrs(client, opts) {
+  const full = await parseRepoArg(opts, client);
+  const items = await client.get(`/repos/${full}/pulls`, {
+    state: opts.state, per_page: String(opts.limit),
+  });
+  if (!items.length) {
+    console.log(`${full}: 没有 Pull Request`);
+    return EXIT_OK;
+  }
+  for (const it of items) {
+    const user = (it.user && it.user.login) || "?";
+    console.log(`#${String(it.number).padEnd(5)} [${String(it.state).padEnd(6)}] `
+      + `${it.title}  @${user}`);
+  }
+  return EXIT_OK;
+}
+
+// Issue 编号是 Gitee 自动生成的字符串标识（如 IKVADU），不是数字
+const ISSUE_STATE_TEXT = {
+  open: "开启", progress: "进行中", closed: "已关闭", rejected: "已拒绝",
+};
+
+function issueStateText(state) {
+  return ISSUE_STATE_TEXT[state] || state || "?";
+}
+
+// 统一解析 issue 单条操作的位置参数：
+// - 两个位置参数：repo + 编号
+// - 只给一个：视为编号，仓库取当前目录同名仓库
+// - 编号容忍 # 前缀（用户习惯写 #IKVADU）
+function parseIssueArg(opts) {
+  let repo = opts.repo;
+  let number = opts.number;
+  const repoEmpty = repo === undefined || repo === null || repo === "";
+  const numEmpty = number === undefined || number === null || number === "";
+  if (numEmpty && repoEmpty) return null;
+  if (numEmpty) {
+    number = repo;
+    repo = undefined;
+  }
+  number = String(number).trim().replace(/^#/, "");
+  if (!number) return null;
+  return { repo: repo === undefined || repo === null ? "" : String(repo).trim(), number };
+}
+
+async function issueTarget(opts, client) {
+  const pos = parseIssueArg(opts);
+  if (!pos) return null;
+  const full = await splitRepo(pos.repo || path.basename(process.cwd()), client);
+  return { full, number: pos.number };
+}
+
+function issueUsageHint(action) {
+  return `错误：缺少 Issue 编号。用法：gitee ${action} [<仓库>] <编号>`
+    + `（仓库省略时取当前目录同名仓库）`;
+}
+
+function printIssue(it) {
+  console.log(`编号:   #${it.number}`);
+  console.log(`标题:   ${it.title}`);
+  console.log(`状态:   ${it.state}（${issueStateText(it.state)}）`);
+  console.log(`作者:   ${(it.user && it.user.login) || "?"}`);
+  const labels = (it.labels || []).map((l) => l.name || l).join(", ");
+  console.log(`标签:   ${labels || "（无）"}`);
+  console.log(`评论:   ${it.comments ?? 0} 条`);
+  console.log(`创建:   ${it.created_at}`);
+  console.log(`更新:   ${it.updated_at}`);
+  if (it.finished_at) console.log(`完成:   ${it.finished_at}`);
+  console.log(`链接:   ${it.html_url}`);
+  console.log("正文:");
+  console.log(it.body || "（无）");
+}
+
+async function cmdIssue(client, opts) {
+  const target = await issueTarget(opts, client);
+  if (!target) {
+    console.error(issueUsageHint("issue view"));
+    return EXIT_USAGE;
+  }
+  const it = await issueGet(client, target.full, target.number);
+  printIssue(it);
+  return EXIT_OK;
+}
+
+// ---------- Issue 写接口（路径不含 repo 段，仓库以表单参数 repo 传） ---------- //
+function issueOwnerRepo(full) {
+  const [owner, repoName] = full.split("/");
+  return { owner, repoName };
+}
+
+function issueGet(client, full, number) {
+  return client.get(`/repos/${full}/issues/${encodeURIComponent(number)}`);
+}
+
+function issuePatch(client, full, number, form) {
+  // 统一注入表单 repo：Gitee 更新接口路径不含 repo 段（与 GitHub 不同）
+  const { owner, repoName } = issueOwnerRepo(full);
+  return client.patch(`/repos/${owner}/issues/${encodeURIComponent(number)}`,
+    { repo: repoName, ...form });
+}
+
+// -b 正文 与 -f 文件正文 互斥；-f 读取 UTF-8 文件内容作为正文
+function resolveBodyArg(opts) {
+  if (opts.body !== undefined && opts.file !== undefined) {
+    console.error("错误：-b/--body 与 -f/--file 只能二选一");
+    return { error: true };
+  }
+  if (opts.file !== undefined) {
+    try {
+      return { body: fs.readFileSync(opts.file, "utf8") };
+    } catch (e) {
+      console.error(`错误：无法读取正文文件 ${opts.file}：${e.message}`);
+      return { error: true };
+    }
+  }
+  return { body: opts.body };
+}
+
+async function cmdIssueCreate(client, opts) {
+  if (!opts.title) {
+    console.error("错误：创建 Issue 需要 -t/--title 标题");
+    return EXIT_USAGE;
+  }
+  const bodyArg = resolveBodyArg(opts);
+  if (bodyArg.error) return EXIT_USAGE;
+  const full = await parseRepoArg(opts, client);
+  const { owner, repoName } = issueOwnerRepo(full);
+  const form = { repo: repoName, title: opts.title };
+  if (bodyArg.body !== undefined && bodyArg.body !== null) form.body = bodyArg.body;
+  if (opts.labels) form.labels = opts.labels;
+  if (opts.assignee) form.assignee = opts.assignee;
+  const it = await client.post(`/repos/${owner}/issues`, form);
+  console.log(`已创建: #${it.number} ${it.title}`);
+  console.log(`链接:   ${it.html_url}`);
+  return EXIT_OK;
+}
+
+async function cmdIssueEdit(client, opts) {
+  const target = await issueTarget(opts, client);
+  if (!target) {
+    console.error(issueUsageHint("issue edit"));
+    return EXIT_USAGE;
+  }
+  const bodyArg = resolveBodyArg(opts);
+  if (bodyArg.error) return EXIT_USAGE;
+  const form = {};
+  if (opts.title !== undefined) form.title = opts.title;
+  if (bodyArg.body !== undefined && bodyArg.body !== null) form.body = bodyArg.body;
+  if (opts.state !== undefined) form.state = opts.state;
+  if (opts.labels !== undefined) form.labels = opts.labels;
+  if (opts.assignee !== undefined) form.assignee = opts.assignee;
+  // 不带任何修改参数时按查看处理，避免空 PATCH 造成误解
+  if (!Object.keys(form).length) {
+    const it = await issueGet(client, target.full, target.number);
+    printIssue(it);
+    return EXIT_OK;
+  }
+  await issuePatch(client, target.full, target.number, form);
+  const it = await issueGet(client, target.full, target.number);
+  printIssue(it);
+  return EXIT_OK;
+}
+
+async function cmdIssueComment(client, opts) {
+  if (opts.message === undefined && opts.file === undefined) {
+    console.error("错误：评论内容用 -m/--message 给出（或 -f/--file 从文件读）");
+    return EXIT_USAGE;
+  }
+  const bodyArg = resolveBodyArg({ body: opts.message, file: opts.file });
+  if (bodyArg.error) return EXIT_USAGE;
+  if (!bodyArg.body) {
+    console.error("错误：评论内容不能为空");
+    return EXIT_USAGE;
+  }
+  const target = await issueTarget(opts, client);
+  if (!target) {
+    console.error(issueUsageHint("issue comment"));
+    return EXIT_USAGE;
+  }
+  const c = await client.post(
+    `/repos/${target.full}/issues/${encodeURIComponent(target.number)}/comments`,
+    { body: bodyArg.body });
+  console.log(`已评论: #${target.number}（评论 id ${c.id}）`);
+  if (c.html_url) console.log(`链接:   ${c.html_url}`);
+  return EXIT_OK;
+}
+
+async function cmdSetIssueState(client, opts, state, hint = "close") {
+  const target = await issueTarget(opts, client);
+  if (!target) {
+    console.error(issueUsageHint(hint));
+    return EXIT_USAGE;
+  }
+  const { full, number } = target;
+  await issuePatch(client, full, number, { state });
+  const it = await issueGet(client, full, number);
+  console.log(`#${it.number} [${issueStateText(it.state)}] ${it.title}`);
+  return EXIT_OK;
+}
+
+function runGit(args, cwd) {
+  const r = spawnSync("git", args, { cwd, encoding: "utf8" });
+  return { code: r.status, out: r.stdout || "", err: r.stderr || "" };
+}
+
+async function cmdPush(client, opts) {
+  const cwd = process.cwd();
+  const dotGit = path.join(cwd, ".git");
+  if (!fs.existsSync(dotGit) || !fs.statSync(dotGit).isDirectory()) {
+    console.error("当前目录不是 git 仓库（缺少 .git）");
+    return EXIT_GIT;
+  }
+  const user = await client.get("/user");
+  const owner = user.login;
+  const name = opts.name || path.basename(cwd);
+  const full = `${owner}/${name}`;
+
+  let exists = true;
+  try {
+    await client.get(`/repos/${full}`);
+  } catch (e) {
+    if (e instanceof GiteeError && e.message.includes("404")) {
+      exists = false;
+    } else {
+      throw e;
+    }
+  }
+  if (!exists) {
+    console.log(`仓库不存在，正在创建 ${full} …`);
+    await client.post("/user/repos", {
+      name,
+      private: opts.public ? "false" : "true",
+      description: opts.description || "",
+    });
+  }
+
+  const branch = runGit(["rev-parse", "--abbrev-ref", "HEAD"], cwd).out.trim() || "master";
+  const remoteUrl = `https://gitee.com/${full}.git`;
+  const authUrl = `https://oauth2:${client.token}@gitee.com/${full}.git`;
+
+  console.log(`推送 ${branch} → ${remoteUrl} …`);
+  const result = runGit(["push", authUrl, `${branch}:${branch}`], cwd);
+  if (result.code !== 0) {
+    // 令牌不落终端：git 报错输出可能带完整 auth_url，先把 token 打码
+    console.error(`推送失败：${result.err.trim().replaceAll(client.token, "***").slice(0, 500)}`);
+    return EXIT_GIT;
+  }
+  if (runGit(["remote", "get-url", "origin"], cwd).code !== 0) {
+    runGit(["remote", "add", "origin", remoteUrl], cwd);
+    console.log("已添加 remote origin");
+  }
+  if (opts.public) {
+    await client.patch(`/repos/${full}`, { name, private: "false" });
+    console.log("已设为公开");
+  }
+  console.log(`完成：https://gitee.com/${full}`);
+  return EXIT_OK;
+}
+
+// --------------------------------------------------------------------------- //
+// 子命令表与入口
+// --------------------------------------------------------------------------- //
+function clientOpts() {
+  return [
+    { long: "--token", dest: "token", arg: "value", help: "私人令牌（优先级最高，临时用别的账号时用；注意会进 shell 历史）" },
+    { long: "--api", dest: "api", arg: "value", help: "API 根地址（优先级：命令行 > gitee set > GITEE_API > 官方地址）" },
+    { long: "--proxy", dest: "proxy", arg: "value", help: "代理地址（优先级：命令行 > gitee set > GITEE_PROXY）" },
+    { long: "--timeout", dest: "timeout", arg: "int", help: "超时秒数（优先级：命令行 > gitee set > 30）" },
+  ];
+}
+
+function spec(usage, description, options, positionals) {
+  return { prog: "gitee", usage, description, options, positionals: positionals || [] };
+}
+
+const STATE_OPTS = [
+  { short: "-s", long: "--state", dest: "state", arg: "value", default: "open",
+    choices: ["open", "closed", "all"], help: "状态（默认 open）" },
+  { short: "-n", long: "--limit", dest: "limit", arg: "int", default: 20, help: "条数（默认 20）" },
+];
+
+// ---- Issue 动作族共用的选项与位置参数 ---- //
+const ISSUE_STATE_OPT = [
+  { short: "-s", long: "--state", dest: "state", arg: "value",
+    choices: ["open", "progressing", "closed"],
+    help: "状态：open 开启 / progressing 进行中 / closed 关闭" },
+];
+const ISSUE_BODY_OPTS = [
+  { short: "-b", long: "--body", dest: "body", arg: "value", help: "正文（与 -f 二选一）" },
+  { short: "-f", long: "--file", dest: "file", arg: "value", help: "从 UTF-8 文件读正文" },
+];
+const ISSUE_META_OPTS = [
+  { short: "-l", long: "--labels", dest: "labels", arg: "value",
+    help: "标签，逗号分隔（如 bug,docs）" },
+  { short: "-a", long: "--assignee", dest: "assignee", arg: "value", help: "负责人 username" },
+];
+const ISSUE_POS = [
+  { dest: "repo", required: false, help: "仓库名或 owner/repo（默认当前目录同名仓库）" },
+  { dest: "number", required: false, help: "Issue 编号（字符串标识，如 IKVADU，可带 #）" },
+];
+
+const ISSUE_FAMILY_HELP = `用法：gitee issue <动作> [参数]
+
+动作：
+  view     查看 Issue 详情    gitee issue view [<repo>] <编号>
+  create   创建 Issue         gitee issue create [<repo>] -t 标题 [-b|-f 正文] [-l 标签] [-a 负责人]
+  edit     修改 Issue         gitee issue edit [<repo>] <编号> [-t 标题] [-b|-f 正文] [-s 状态] [-l 标签] [-a 负责人]
+  open     重开 Issue         gitee issue open [<repo>] <编号>
+  close    关闭 Issue         gitee issue close [<repo>] <编号>
+  comment  加评论             gitee issue comment [<repo>] <编号> -m 内容|-f 文件
+
+用 gitee issue <动作> -h 查看各动作详情。`;
+
+const ISSUE_ACTIONS = {
+  view: {
+    run: (client, o) => cmdIssue(client, o),
+    spec: spec("用法：gitee issue view [<repo>] <编号>", "查看 Issue 详情",
+      clientOpts(), ISSUE_POS),
+  },
+  create: {
+    run: (client, o) => cmdIssueCreate(client, o),
+    spec: spec("用法：gitee issue create [<repo>] -t 标题 [-b 正文|-f 文件] [-l 标签] [-a 负责人]",
+      "创建 Issue（Gitee 无删除接口，建前想清楚）",
+      [{ short: "-t", long: "--title", dest: "title", arg: "value", required: true,
+          help: "标题（必填）" },
+        ...ISSUE_BODY_OPTS, ...ISSUE_META_OPTS, ...clientOpts()],
+      [{ dest: "repo", required: false, help: "仓库名或 owner/repo（默认当前目录同名仓库）" }]),
+  },
+  edit: {
+    run: (client, o) => cmdIssueEdit(client, o),
+    spec: spec("用法：gitee issue edit [<repo>] <编号> [-t 标题] [-b|-f 正文] [-s 状态] [-l 标签] [-a 负责人]",
+      "修改 Issue（不带任何修改参数时等于 view）",
+      [{ short: "-t", long: "--title", dest: "title", arg: "value", help: "新标题" },
+        ...ISSUE_BODY_OPTS, ...ISSUE_STATE_OPT, ...ISSUE_META_OPTS, ...clientOpts()],
+      ISSUE_POS),
+  },
+  open: {
+    run: (client, o) => cmdSetIssueState(client, o, "open", "issue open"),
+    spec: spec("用法：gitee issue open [<repo>] <编号>", "重开 Issue",
+      clientOpts(), ISSUE_POS),
+  },
+  close: {
+    run: (client, o) => cmdSetIssueState(client, o, "closed", "issue close"),
+    spec: spec("用法：gitee issue close [<repo>] <编号>", "关闭 Issue",
+      clientOpts(), ISSUE_POS),
+  },
+  comment: {
+    run: (client, o) => cmdIssueComment(client, o),
+    spec: spec("用法：gitee issue comment [<repo>] <编号> -m 内容|-f 文件", "给 Issue 加评论",
+      [{ short: "-m", long: "--message", dest: "message", arg: "value", help: "评论内容" },
+        { short: "-f", long: "--file", dest: "file", arg: "value",
+          help: "从 UTF-8 文件读评论内容（与 -m 二选一）" },
+        ...clientOpts()],
+      ISSUE_POS),
+  },
+};
+
+const SUBCOMMANDS = {
+  set: {
+    run: (opts) => cmdSetConfig(opts),
+    spec: spec("用法：gitee set [<key> <value>]",
+      "查看或写入内部配置（~/.config/gitee/config.json）",
+      [], [
+      { dest: "key", required: false, help: "配置项：token / api / proxy / timeout" },
+      { dest: "value", required: false, help: "要写入的值（不带任何参数时列出当前配置）" },
+    ]),
+    noAuth: true,
+  },
+  unset: {
+    run: (opts) => cmdUnsetConfig(opts),
+    spec: spec("用法：gitee unset <key>", "删除一项内部配置",
+      [], [{ dest: "key", required: true, help: "配置项：token / api / proxy / timeout" }]),
+    noAuth: true,
+  },
+  whoami: {
+    run: (client) => cmdWhoami(client),
+    spec: spec("用法：gitee whoami", "查看当前 token 对应的账号", clientOpts()),
+  },
+  list: {
+    run: (client, o) => cmdList(client, o),
+    spec: spec("用法：gitee list [-n 条数] [--json]", "列出我的仓库",
+      [...STATE_OPTS.slice(1), { long: "--json", dest: "json", help: "输出原始 JSON" },
+        ...clientOpts()]),
+  },
+  info: {
+    run: (client, o) => cmdInfo(client, o),
+    spec: spec("用法：gitee info <repo>", "查看仓库信息", clientOpts(),
+      [{ dest: "repo", required: true, help: "仓库名或 owner/repo" }]),
+  },
+  create: {
+    run: (client, o) => cmdCreate(client, o),
+    spec: spec("用法：gitee create <name> [-d 简介] [--public]", "新建仓库",
+      [{ short: "-d", long: "--description", dest: "description", arg: "value", help: "仓库简介" },
+        { long: "--public", dest: "public", help: "设为公开（空仓库需推送后生效）" },
+        ...clientOpts()],
+      [{ dest: "name", required: true, help: "仓库名" }]),
+  },
+  public: {
+    run: (client, o) => cmdSetVisibility(client, o, false),
+    spec: spec("用法：gitee public <repo>", "把仓库设为公开", clientOpts(),
+      [{ dest: "repo", required: true, help: "仓库名或 owner/repo" }]),
+  },
+  private: {
+    run: (client, o) => cmdSetVisibility(client, o, true),
+    spec: spec("用法：gitee private <repo>", "把仓库设为私有", clientOpts(),
+      [{ dest: "repo", required: true, help: "仓库名或 owner/repo" }]),
+  },
+  delete: {
+    run: (client, o) => cmdDelete(client, o),
+    spec: spec("用法：gitee delete <repo> [-y]", "删除仓库",
+      [{ short: "-y", long: "--yes", dest: "yes", help: "跳过确认" }, ...clientOpts()],
+      [{ dest: "repo", required: true, help: "仓库名或 owner/repo" }]),
+  },
+  issues: {
+    run: (client, o) => cmdIssues(client, o),
+    spec: spec("用法：gitee issues [<repo>] [-s 状态] [-n 条数]", "列出 Issue",
+      [...STATE_OPTS, ...clientOpts()],
+      [{ dest: "repo", required: false, help: "仓库名或 owner/repo（默认当前目录同名仓库）" }]),
+  },
+  issue: {
+    run: null, // 动作族：main 里按 argv[1] 分发到 ISSUE_ACTIONS
+    actions: ISSUE_ACTIONS,
+    spec: null,
+  },
+  close: {
+    run: (client, o) => cmdSetIssueState(client, o, "closed", "close"),
+    spec: spec("用法：gitee close [<repo>] <编号>", "关闭 Issue", clientOpts(),
+      [{ dest: "repo", required: false, help: "仓库名或 owner/repo（默认当前目录同名仓库）" },
+        { dest: "number", required: false, help: "Issue 编号（可带 #）" }]),
+  },
+  reopen: {
+    run: (client, o) => cmdSetIssueState(client, o, "open", "reopen"),
+    spec: spec("用法：gitee reopen [<repo>] <编号>", "重开 Issue", clientOpts(),
+      [{ dest: "repo", required: false, help: "仓库名或 owner/repo（默认当前目录同名仓库）" },
+        { dest: "number", required: false, help: "Issue 编号（可带 #）" }]),
+  },
+  prs: {
+    run: (client, o) => cmdPrs(client, o),
+    spec: spec("用法：gitee prs [<repo>] [-s 状态] [-n 条数]", "列出 Pull Request",
+      [...STATE_OPTS, ...clientOpts()],
+      [{ dest: "repo", required: false, help: "仓库名或 owner/repo（默认当前目录同名仓库）" }]),
+  },
+  push: {
+    run: (client, o) => cmdPush(client, o),
+    spec: spec("用法：gitee push [--name 名字] [-d 简介] [--public]", "当前目录建仓并推送",
+      [{ long: "--name", dest: "name", arg: "value", help: "仓库名（默认取目录名）" },
+        { short: "-d", long: "--description", dest: "description", arg: "value", help: "仓库简介" },
+        { long: "--public", dest: "public", help: "推送后设为公开" },
+        ...clientOpts()]),
+  },
+};
+
+const TOP_HELP = `gitee — Gitee 仓库管理命令行工具
+
+用法：gitee <子命令> [参数]
+
+子命令：
+  set / unset   内部配置管理（token / api / proxy / timeout）
+  whoami        查看当前 token 对应的账号
+  list          列出我的仓库
+  info <repo>   查看仓库信息
+  create        新建仓库
+  public/private 切换仓库可见性
+  delete        删除仓库
+  issues / prs  列出 Issue / Pull Request
+  issue         Issue 操作族：view / create / edit / open / close / comment
+                （无动作词时默认 view；顶层 close/reopen 等价 issue close/open）
+  close/reopen  关闭 / 重开 Issue
+  push          当前目录建仓并推送
+
+用 \`gitee <子命令> -h\` 查看各子命令详情。`;
+
+async function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  if (!cmd) {
+    console.error(`错误：缺少子命令\n\n${TOP_HELP}`);
+    process.exit(EXIT_USAGE);
+  }
+  if (cmd === "-h" || cmd === "--help" || cmd === "help") {
+    console.log(TOP_HELP);
+    process.exit(EXIT_OK);
+  }
+  const def = SUBCOMMANDS[cmd];
+  if (!def) {
+    console.error(`错误：未知子命令 ${JSON.stringify(cmd)}\n\n${TOP_HELP}`);
+    process.exit(EXIT_USAGE);
+  }
+  if (cmd === "-h") process.exit(EXIT_OK);
+
+  // issue 动作族：argv[1] 必须是动作词，切换到对应 spec（剩余 argv 从 2 起解析）
+  let spec = def.spec;
+  let action = null;
+  if (def.actions) {
+    if (argv[1] === undefined) {
+      console.error(`错误：缺少 issue 动作\n\n${ISSUE_FAMILY_HELP}`);
+      process.exit(EXIT_USAGE);
+    }
+    action = def.actions[argv[1]] || null;
+    if (!action) {
+      console.error(`错误：未知 issue 动作 ${JSON.stringify(argv[1])}\n\n${ISSUE_FAMILY_HELP}`);
+      process.exit(EXIT_USAGE);
+    }
+    spec = action.spec;
+  }
+  const { opts } = parse(spec, action ? argv.slice(2) : argv.slice(1));
+  if (def.noAuth) {
+    process.exit(await def.run(opts));
+  }
+
+  const cfg = loadConfig(CONFIG_PATH, CONFIG_KEYS);
+  const [tokenRaw] = resolveValue(opts.token, cfg.token, "GITEE_TOKEN", "");
+  const token = String(tokenRaw || "").trim();
+  if (!token) {
+    console.error("错误：未设置 Gitee 私人令牌，请先执行：gitee set token 你的令牌"
+      + "（或 export GITEE_TOKEN=你的令牌）");
+    process.exit(EXIT_AUTH);
+  }
+  const [apiRaw] = resolveValue(opts.api, cfg.api, "GITEE_API", DEFAULT_API);
+  const api = apiRaw.replace(/\/+$/, "");
+  const [proxy] = resolveValue(opts.proxy, cfg.proxy, "GITEE_PROXY", null);
+  const [timeout] = resolveValue(opts.timeout, cfg.timeout, null, DEFAULT_TIMEOUT);
+  const client = new Client(token, api, proxy, timeout);
+  try {
+    process.exit(await (action ? action.run(client, opts) : def.run(client, opts)));
+  } catch (e) {
+    if (e instanceof GiteeError) {
+      console.error(`错误：${e.message}`);
+      process.exit(EXIT_API);
+    }
+    console.error(`错误：${e.message}`);
+    process.exit(EXIT_API);
+  }
+}
+
+main().catch((e) => {
+  console.error(`错误：${e.message}`);
+  process.exit(EXIT_API);
+});