dsh-github-flow 0.5.0 → 0.6.0

package/lib/executor/error-classifier.d.ts

@@ -0,0 +1,55 @@
+/**
+ * gh 错误语义分类（确定性配置错误 vs 可重试的传输层故障）。
+ *
+ * 为什么必须区分：`gh` 失败时一律以非零退出码返回，调用方只能看到一段 stderr
+ * 文本。过去上层（Web 概览路由）把所有非零退出统一当成「网络错误」，于是
+ * 「仓库关闭了 Issues」这种永久性配置事实被伪装成网络抖动——既弹出误导性的
+ * 「网络连接失败」横幅，又触发 3 轮阶梯退避重试与每 5-10 分钟一轮的自动同步，
+ * 把确定性失败当成偶发抖动反复空烧。
+ *
+ * 判据全部来自 gh 2.96 实测 stderr：
+ *   - the 'o/r' repository has disabled issues
+ *   - the 'o/r' repository has discussions disabled
+ *   - GraphQL: Could not resolve to a Repository with the name 'o/r'. (repository)
+ *   - HTTP 403 / Not Found (HTTP 404)
+ *
+ * 纯文本判定，不做任何 I/O——它是 GhResult.errorKind 的唯一事实源。
+ */
+/** gh 失败结果的语义种类 */
+export type GhErrorKind = 
+/** 传输层故障（超时、DNS、连接重置、代理阻断）：值得重试，允许回退历史快照 */
+'transient'
+/** 确定性失败（仓库关闭 issues、仓库不存在、权限不足）：重试永远无意义 */
+ | 'deterministic'
+/** 命令失败但无明确归属，按可重试处理（保守不误杀） */
+ | 'unknown';
+/**
+ * 判定一次 gh 失败的语义种类。
+ *
+ * 优先级设计：确定性 > 限流放行 > 传输层 > unknown。
+ * 为什么不把「同时命中确定性与传输层」判为 transient：若仓库关闭了 Issues，
+ * 网络恢复后该命令依然失败。判成 transient 会让调用方每轮回退旧快照、
+ * 永远收敛不到正确状态。确定性一旦命中就该立刻停止重试。
+ */
+export declare function classifyGhError(errorText: string | undefined | null): GhErrorKind;
+/**
+ * 把确定性失败翻译成面向用户的友好说明。
+ * 返回 null 表示不属于确定性失败，调用方应走原有网络故障路径。
+ */
+export declare function describeDeterministicError(errorText: string | undefined | null): string | null;
+/** 该错误是否值得重试（供 UI 层决定是否走阶梯退避） */
+export declare function isRetryableError(errorText: string | undefined | null): boolean;
+export declare function isPermissionError(errorText: string | undefined | null): boolean;
+/**
+ * 把「权限不足」翻译成可操作的处置指引。
+ *
+ * 为什么不能只回一句「无权限」：Agent 与用户都需要知道**下一步做什么**。
+ * GitHub 的权限错误有明确解法路径（提权到 Triage/Write、或改用 fork 工作流），
+ * 把这条路径说出来，比让用户自己搜错误文本有用得多。
+ *
+ * @param errorText gh 的 stderr
+ * @param action 可选：正在执行的动作标识（如 'merge' / 'close' / 'add_label'），
+ *               用于在错误文本特征不足时精准匹配
+ * @returns 指引文本；非权限错误返回 null（不产生噪音）
+ */
+export declare function permissionRemedy(errorText: string | undefined | null, action?: string): string | null;

package/lib/executor/error-classifier.js

@@ -0,0 +1,199 @@
+/**
+ * gh 错误语义分类（确定性配置错误 vs 可重试的传输层故障）。
+ *
+ * 为什么必须区分：`gh` 失败时一律以非零退出码返回，调用方只能看到一段 stderr
+ * 文本。过去上层（Web 概览路由）把所有非零退出统一当成「网络错误」，于是
+ * 「仓库关闭了 Issues」这种永久性配置事实被伪装成网络抖动——既弹出误导性的
+ * 「网络连接失败」横幅，又触发 3 轮阶梯退避重试与每 5-10 分钟一轮的自动同步，
+ * 把确定性失败当成偶发抖动反复空烧。
+ *
+ * 判据全部来自 gh 2.96 实测 stderr：
+ *   - the 'o/r' repository has disabled issues
+ *   - the 'o/r' repository has discussions disabled
+ *   - GraphQL: Could not resolve to a Repository with the name 'o/r'. (repository)
+ *   - HTTP 403 / Not Found (HTTP 404)
+ *
+ * 纯文本判定，不做任何 I/O——它是 GhResult.errorKind 的唯一事实源。
+ */
+/**
+ * 确定性失败的 stderr 特征表。
+ *
+ * 为什么用特征串而不是退出码：gh 对上述场景统一返回 exit 1，退出码无法区分
+ * 「仓库关了 Issues」与「网线掉了」。文本特征是唯一可用的判据。
+ * 每条都必须来自实测输出——误判会把真实网络故障降级成静默空数据，比误报更糟。
+ */
+const DETERMINISTIC_PATTERNS = [
+    // 仓库级开关关闭（Issues / Discussions / Projects / Wiki）。
+    // 注意 gh 的措辞不统一（实测）：
+    //   issues      → "repository has disabled issues"
+    //   discussions → "repository has discussions disabled"
+    // 词序相反，所以两种形态都要覆盖，不能只写一种。
+    {
+        re: /repository has (?:disabled )?(issues|discussions|projects|wiki)(?: disabled)?/i,
+        reason: '该仓库未开启该项协作功能',
+    },
+    // 仓库不可达（不存在 / 无权限 / 已改名）：GraphQL 与 REST 两条通道
+    { re: /Could not resolve to a Repository/i, reason: '仓库不存在或当前账号无权访问' },
+    { re: /Not Found \(HTTP 404\)/i, reason: '仓库或资源不存在' },
+    // 分支 / PR / Issue 单体不存在
+    { re: /Branch not found/i, reason: '分支不存在' },
+    // GraphQL 通道的权限不足（实测形态）：
+    //   GraphQL: ItQianChen does not have the correct permissions to execute `AddLabelsToLabelable` (addLabelsToLabelable)
+    //   GraphQL: ItQianChen does not have the correct permissions to execute `DeleteIssue` (deleteIssue)
+    // 这类文本里没有 "HTTP 403"，若不单列会被归为 unknown，进而被当成可重试抖动——
+    // 而权限不足重试一万次也不会变。
+    { re: /does not have the correct permissions to execute/i, reason: '当前账号对该仓库的权限不足' },
+];
+/** 把「仓库未开启某项功能」翻译成点名说明（比笼统的“未开启协作功能”有用） */
+const DISABLED_FEATURE_LABEL = {
+    issues: 'Issues',
+    discussions: 'Discussions',
+    projects: 'Projects',
+    wiki: 'Wiki',
+};
+/**
+ * 限流类 403 必须先于通用 403 放行。
+ * 为什么单列：GitHub 的 `HTTP 403` 既可能是「无权限」（确定性），也可能是
+ * 「API rate limit exceeded / secondary rate limit」（几分钟后可恢复）。
+ * 把限流误判成确定性会让学生等一会儿就能好的请求被判死刑。
+ */
+const RATE_LIMIT_RE = /rate limit|secondary rate limit|abuse detection/i;
+/** 传输层故障特征（显式白名单，用于给出「可重试」的准确语义） */
+const TRANSIENT_PATTERNS = [
+    /命令执行超时/,
+    /\bETIMEDOUT\b/i,
+    /\bECONNRESET\b/i,
+    /\bECONNREFUSED\b/i,
+    /\bENOTFOUND\b/i,
+    /\bEAI_AGAIN\b/i,
+    /socket hang up/i,
+    /TLS handshake/i,
+    /proxyconnect/i,
+    /spawn EPERM/i,
+    /network is unreachable/i,
+    /Could not resolve host/i,
+    /no such host/i,
+];
+/**
+ * 判定一次 gh 失败的语义种类。
+ *
+ * 优先级设计：确定性 > 限流放行 > 传输层 > unknown。
+ * 为什么不把「同时命中确定性与传输层」判为 transient：若仓库关闭了 Issues，
+ * 网络恢复后该命令依然失败。判成 transient 会让调用方每轮回退旧快照、
+ * 永远收敛不到正确状态。确定性一旦命中就该立刻停止重试。
+ */
+export function classifyGhError(errorText) {
+    const text = String(errorText || '');
+    if (!text)
+        return 'unknown';
+    // 限流 403 先放行，避免被下面的通用 403 规则当成确定性失败
+    if (RATE_LIMIT_RE.test(text))
+        return 'transient';
+    for (const { re } of DETERMINISTIC_PATTERNS) {
+        if (re.test(text))
+            return 'deterministic';
+    }
+    // 通用 403 放在确定性表之后、transient 之前：无权限属于确定性
+    if (/HTTP 403/i.test(text))
+        return 'deterministic';
+    for (const re of TRANSIENT_PATTERNS) {
+        if (re.test(text))
+            return 'transient';
+    }
+    return 'unknown';
+}
+/**
+ * 把确定性失败翻译成面向用户的友好说明。
+ * 返回 null 表示不属于确定性失败，调用方应走原有网络故障路径。
+ */
+export function describeDeterministicError(errorText) {
+    const text = String(errorText || '');
+    if (!text)
+        return null;
+    if (RATE_LIMIT_RE.test(text))
+        return null;
+    // 先处理「仓库关闭某项功能」：点名到具体功能，比笼统措辞更容易让用户行动
+    const disabled = /repository has (?:disabled )?(issues|discussions|projects|wiki)(?: disabled)?/i.exec(text);
+    if (disabled) {
+        const label = DISABLED_FEATURE_LABEL[disabled[1].toLowerCase()] || disabled[1];
+        return `该仓库未开启 ${label}`;
+    }
+    for (const { re, reason } of DETERMINISTIC_PATTERNS) {
+        if (re.test(text))
+            return reason;
+    }
+    if (/HTTP 403/i.test(text))
+        return '当前账号无此操作权限';
+    return null;
+}
+/** 该错误是否值得重试（供 UI 层决定是否走阶梯退避） */
+export function isRetryableError(errorText) {
+    return classifyGhError(errorText) !== 'deterministic';
+}
+/**
+ * 判断一段错误是否属于「权限不足」（而非仓库配置、不存在等确定性错误）。
+ *
+ * 为什么单独判定：确定性错误里只有权限这一类有「解法路径」（提权 / 换 fork 工作流），
+ * 其余（仓库关了 Issues、分支不存在）说再多也没用。
+ */
+const PERMISSION_RE = /does not have the correct permissions to execute|HTTP 403|Resource not accessible|Forbidden|must have (?:admin|push|write|triage|maintain) (?:access|permissions?)/i;
+export function isPermissionError(errorText) {
+    const text = String(errorText || '');
+    if (!text)
+        return false;
+    // 限流也常以 403 出现，但它不是权限问题——放行会让用户去改权限，做无用功
+    if (RATE_LIMIT_RE.test(text))
+        return false;
+    return PERMISSION_RE.test(text);
+}
+/**
+ * 已知操作 → 所需权限档位 的映射。
+ *
+ * 键取自 GitHub 的 GraphQL mutation 名与 gh 子命令动词（实测捕获）。
+ * 为什么不用完整枚举：GitHub 有上百个 mutation，穷举既不可能也没必要——
+ * 未命中的一律走默认指引，仍然是对的。
+ */
+const ACTION_PERMISSION_MAP = [
+    {
+        // 同时覆盖 GraphQL mutation 名（AddLabelsToLabelable）与 CLI 参数形态
+        // （--add-label / --remove-label）——两者出现在不同层级的错误文本里。
+        re: /AddLabelsToLabelable|RemoveLabelsFromLabelable|UpdateIssue|CloseIssue|TransferIssue|add-?label|remove-?label|close-?issue|issue (?:edit|close|pin|lock|transfer)/i,
+        level: 'Triage',
+        hint: '管理他人 Issue/PR（加标签、关闭、指派）需要 Triage 及以上权限。可请仓库管理员授予，或改用评论表达意见。',
+    },
+    {
+        re: /mergePullRequest|MergePullRequest|\bmerge\b|CreateRef|createRef|\bpush\b|CreateCommitOnBranch/i,
+        level: 'Write',
+        hint: '合并 PR / 推送代码需要 Write 及以上权限。若是他人仓库，请先 fork 到自己的账号，在 fork 上提交后向上游发起 PR。',
+    },
+    {
+        re: /DeleteIssue|deleteIssue|DeleteRepository|deleteRepository|TransferRepository|\bdelete\b/i,
+        level: 'Admin',
+        hint: '物理删除与仓库级操作需要管理员权限。这类操作不可逆，请联系仓库管理员执行。',
+    },
+];
+/**
+ * 把「权限不足」翻译成可操作的处置指引。
+ *
+ * 为什么不能只回一句「无权限」：Agent 与用户都需要知道**下一步做什么**。
+ * GitHub 的权限错误有明确解法路径（提权到 Triage/Write、或改用 fork 工作流），
+ * 把这条路径说出来，比让用户自己搜错误文本有用得多。
+ *
+ * @param errorText gh 的 stderr
+ * @param action 可选：正在执行的动作标识（如 'merge' / 'close' / 'add_label'），
+ *               用于在错误文本特征不足时精准匹配
+ * @returns 指引文本；非权限错误返回 null（不产生噪音）
+ */
+export function permissionRemedy(errorText, action) {
+    if (!isPermissionError(errorText))
+        return null;
+    const haystack = `${String(errorText || '')} ${String(action || '')}`;
+    for (const { re, hint } of ACTION_PERMISSION_MAP) {
+        if (re.test(haystack))
+            return hint;
+    }
+    // 默认指引：不指定具体档位。
+    // 为什么：只知道「权限不足」时猜档位很容易猜错（我们实测就猜错过——
+    // READ 用户能建 Issue，而不是处处受限），说错比不说更糟。
+    return '当前账号对该仓库的权限不足。可运行 `gh auth status` 查看作用域，或请仓库管理员提升权限。';
+}

package/lib/executor/git-parser.d.ts

@@ -55,3 +55,127 @@ export interface GitStatParsedResult {
  * 提取文件路径与 `X files changed, Y insertions(+), Z deletions(-)` 汇总。
  */
 export declare function parseGitStatText(statText: string): GitStatParsedResult | null;
+/**
+ * 提取 `.git/config` 中所有 `[remote "..."]` 段内的 url。
+ *
+ * 为什么必须按段扫描而不是全文抓 `url = `：`[submodule "..."]` 段同样带 url
+ * （实测 `[submodule "lib"] url = https://github.com/x/y.git`）。全文正则会把
+ * 子模块的远程算进指纹，导致一次 `git submodule add` 就触发整个面板缓存的
+ * 无谓作废。子模块的 url 与本工作区关联哪个 GitHub 仓库毫无关系。
+ *
+ * 输出语义：保持文件中的出现顺序、已去重、不含空值。
+ * 排序交给调用方（指纹需要稳定顺序，但那是调用方的语义，纯函数不该替它决定）。
+ */
+export declare function parseRemoteUrls(configText: string): string[];
+/** 单个 remote 段的解析结果 */
+export interface ParsedRemote {
+    name: string;
+    url: string;
+}
+/** `.git/config` + `HEAD` 的解析结果，是「这个工作区关联哪个仓库」的唯一事实源 */
+export interface ParsedGitConfig {
+    /** 每个 remote 名对应的第一个 url（身份解析用；同名多 url 时取首个） */
+    remotes: ParsedRemote[];
+    /**
+     * 全部 remote url 行（指纹用）。
+     *
+     * 为什么与 remotes 分开：身份解析需要「remote 名 → url」的一对一映射，
+     * 而指纹需要「配置里出现过的所有 url」。同一个 remote 允许写多行 url
+     * （git 认首个，但配置确实是多行），若指纹也按名字去重，第二行 url 的
+     * 变化就检测不到——那会让「用户改了备用 url」这种情况静默漏检。
+     */
+    allUrls: string[];
+    /** 当前分支名（来自 HEAD 的 `ref: refs/heads/<name>`）；detached HEAD 时为 null */
+    currentBranch: string | null;
+    /** `branch.<currentBranch>.remote` 的值；无配置或无当前分支时为 null */
+    branchRemote: string | null;
+}
+/**
+ * 解析 `.git/config` 与 `HEAD`，产出与 git 语义一致的远程视图。
+ *
+ * 为什么把 HEAD 一起解析：`branch.<name>.remote` 的 `<name>` 是**当前分支**，
+ * 不知道当前分支就无法按 git 的规则选出 remote，只能退化成「取第一个」——
+ * 那正是本次要修的错误。
+ *
+ * @param configText `.git/config` 全文
+ * @param headText   HEAD 文件全文。worktree 场景必须传**局部 gitdir** 下的那个，
+ *                   传共享目录的会拿到主工作树分支名（实测两者不同）。
+ */
+export declare function parseGitConfig(configText: string, headText?: string | null): ParsedGitConfig;
+/**
+ * 按 git 的规则选出「这个工作区关联的 remote」。
+ *
+ * 优先级与 git 一致：
+ *   1. `branch.<当前分支>.remote` —— 当前分支显式跟踪的 remote
+ *   2. `origin`                  —— git 的默认远程
+ *   3. 第一个 remote              —— 兜底（保持既有行为）
+ *
+ * 特殊值 `.` 表示跟踪**本地分支**而非远程（实测可设置），跳过第 1 级——
+ * 拿 "." 去查 `[remote "."]` 必然查不到，且语义上它根本不是远程。
+ */
+export declare function resolveRemoteTarget(cfg: ParsedGitConfig): ParsedRemote | null;
+/**
+ * 从 remote url 中提取 GitHub 的 owner/repo。
+ *
+ * 覆盖形态（均实测于真实 clone / hand-written config）：
+ *   https://github.com/o/r.git
+ *   git@github.com:o/r.git
+ *   ssh://git@github.com/o/r.git
+ *   https://user:token@github.com/o/r.git
+ *   带尾斜杠 / 不带 .git
+ *
+ * 非 github.com 的 host 一律返回 null（GHE 不在支持范围）。
+ * 为什么绝不"猜一个"：错误身份比没有身份更有害——面板会显示一个
+ * 用户根本不认识的仓库，且所有后续判断都建立在错误前提上。
+ * 正则两端锚定，杜绝 `github.com.evil.com` 这类子串误匹配。
+ */
+export declare function parseGithubUrl(url: string): {
+    owner: string;
+    repo: string;
+} | null;
+/**
+ * 从 remote url 中提取 host（小写）。
+ *
+ * 覆盖：https://host/o/r、git@host:o/r、ssh://git@host:2222/o/r、带 token 的 https。
+ * 无法解析返回 null。
+ *
+ * 为什么不直接复用 parseGithubUrl：本函数要处理**任意 host**（GHE / GitLab），
+ * 用于判断「这个 remote 是不是 GitHub」，而不是「这个 remote 属于哪个 GitHub 仓库」。
+ */
+export declare function parseRemoteHost(url: string): string | null;
+/**
+ * 判断工作区处于哪种远程布局。
+ *
+ * 为什么需要分类而不是顺序盲扫：S2 的兜底逻辑按 `.git/config` 的书写顺序
+ * 挑第一个能解析出 GitHub 身份的 remote，而用户执行 `git remote rename` /
+ * `git remote add` 的先后会改变这个顺序——同一个工作区在两次配置操作后
+ * 可能解析出不同仓库。分类后每种布局的处置规则固定，与顺序无关。
+ *
+ * 分类只看 host 与 git 选中的 remote，不看 URL 的仓库名——后者是身份层的事。
+ */
+export declare function classifyRepoLayout(cfg: ParsedGitConfig): 'github-only' | 'github-mixed' | 'no-github' | 'no-remote';
+/**
+ * 在混合布局中确定性地选出一个 GitHub remote。
+ *
+ * 规则（与书写顺序无关）：
+ *   1. 名字为 `origin` 的优先
+ *   2. 否则按 remote 名字字典序最小的
+ *
+ * 为什么用字典序而不是「第一个出现的」：后者让同一个工作区的解析结果
+ * 依赖用户执行 git remote 命令的先后，属于不可复现的行为。
+ * 字典序是可复现、可断言的确定性规则。
+ */
+export declare function pickGithubRemote(cfg: ParsedGitConfig): ParsedRemote | null;
+/**
+ * 将整段 Git Unified Diff 纯文本按变动文件切分为字典映射。
+ *
+ * 为什么需要按文件切片：PR 可能会修改数十个文件，前端需要支持「点击某个文件即刻查看该文件改动」。
+ * 在内存做切片索引后，切换文件无需发起网络请求（0ms 响应），体验极致流畅。
+ *
+ * 键必须与 `gh pr view --json files` 返回的 `files[].path` **逐字一致**，
+ * 否则点击文件查不到 diff。因此需要处理 core.quotePath 的八进制转义。
+ *
+ * @param rawDiff gh pr diff 或 git diff 输出的原始文本
+ * @returns 映射字典：{ [filePath: string]: string (该文件的完整 diff 文本段) }
+ */
+export declare function splitUnifiedDiff(rawDiff: string): Record<string, string>;