dsh-github-flow 0.4.0 → 0.6.0

package/lib/executor.d.ts

@@ -1,10 +1,13 @@
-import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig, GitLocalStatus, GitCommitLog, GitCommitEntry, GitBranchesResult } from './types.js';
+import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig, GitLocalStatus, GitCommitLog, GitCommitEntry, GitBranchesResult, AssociatedRepoItem, PrDetailData, IssueDetailData } from './types.js';
 import type { ProxyManager } from './proxy.js';
 import { parseGhVersion, compareGhVersions } from './executor/version-utils.js';
 import { spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput } from './executor/process-utils.js';
-import { parseGitStatusOutput, parseGitLogLines, parseGitBranchLines } from './executor/git-parser.js';
+import { parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText, parseRemoteUrls, parseGitConfig, resolveRemoteTarget, parseGithubUrl, parseRemoteHost, classifyRepoLayout, pickGithubRemote, splitUnifiedDiff } from './executor/git-parser.js';
+import type { ParsedGitConfig, ParsedRemote } from './executor/git-parser.js';
 import { getPlatformInstallGuide, getGhUpgradeHint } from './executor/platform-guide.js';
-export { parseGhVersion, compareGhVersions, spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput, parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, getPlatformInstallGuide, getGhUpgradeHint, };
+import { classifyGhError, describeDeterministicError, isRetryableError, permissionRemedy, isPermissionError, type GhErrorKind } from './executor/error-classifier.js';
+export { parseGhVersion, compareGhVersions, spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput, parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, parseUncommittedDiff, parseGitStatText, parseRemoteUrls, parseGitConfig, resolveRemoteTarget, parseGithubUrl, parseRemoteHost, classifyRepoLayout, pickGithubRemote, splitUnifiedDiff, getPlatformInstallGuide, getGhUpgradeHint, classifyGhError, describeDeterministicError, isRetryableError, permissionRemedy, isPermissionError, };
+export type { GhErrorKind, ParsedGitConfig, ParsedRemote };
 export declare class GhExecutor {
     ghPath: string;
     defaultTimeoutMs: number;
@@ -114,6 +117,31 @@ export declare class GhExecutor {
      * 符合 global-overview 端点「工作区探测不发网络」的性能红线。
      */
     getLocalGitStatus(cwd?: string): Promise<GitLocalStatus | null>;
+    /**
+     * 分页获取本地未提交文件列表（无网络开销，纯本地毫秒级响应）
+     */
+    getUncommittedFiles(cwd?: string, limit?: number, skip?: number): Promise<{
+        items: Array<{
+            status: string;
+            path: string;
+        }>;
+        totalCount: number;
+        hasMore: boolean;
+    }>;
+    /**
+     * 获取指定文件的未提交 Git Diff 对比（Unified Diff 格式）。
+     * 严格实施路径穿越安全校验；支持已跟踪修改文件、暂存文件与未跟踪新增文件（??）。
+     */
+    getFileDiff(cwd: string | undefined, relativePath: string): Promise<{
+        ok: boolean;
+        filePath: string;
+        status?: string;
+        diff?: string;
+        additions?: number;
+        deletions?: number;
+        isBinary?: boolean;
+        error?: string;
+    }>;
     /**
      * 本地 Git 提交记录（三段一次返回：本地领先 / 远程领先 / 最近提交）。
      *
@@ -157,6 +185,57 @@ export declare class GhExecutor {
         currentBranch?: string;
         error?: string;
     }>;
+    /**
+     * 推导当前工作区可供用户切换的全部关联 GitHub 仓库列表。
+     *
+     * 数据来源（纯本地+拓扑合成，零新增网络开销）：
+     * 1. 扫描本地 .git/config 的所有 GitHub remote（如 origin, upstream 等）；
+     * 2. 若当前仓库为 Fork 且存在 parent（上游），合并上游仓库（支持本地未配 upstream 的情形）；
+     * 3. 标识当前基准 (isCurrent) 及角色 (fork, upstream, origin, parent)。
+     */
+    getAssociatedRepos(cwd?: string, currentRepo?: RepoMetadata | null, currentUser?: string | null): AssociatedRepoItem[];
+    /**
+     * 设置当前工作区的默认基准 GitHub 仓库（调用官方 `gh repo set-default` 并在本地 git config 持久化）。
+     *
+     * 为什么调用 gh repo set-default：
+     * 1. 它会在 .git/config 写入 `remote.<name>.gh-resolved = base`，这是官方的持久化事实源；
+     * 2. 执行后，不仅本插件的 Web 驾驶舱，外部系统终端中运行的 gh pr, gh issue, gh run 也将 100% 对齐；
+     * 3. 严格做参数格式校验，仅允许合法的 owner/repo 或合法 remote 别名，杜绝命令注入。
+     */
+    setDefaultRepo(cwd: string | undefined, targetRepoOrRemote: string): Promise<{
+        ok: boolean;
+        target?: string;
+        error?: string;
+    }>;
+    /**
+     * 获取 Pull Request 完整详情与变更 Diff 数据（用于 PR 在线审阅与代码比对）。
+     *
+     * 架构设计：
+     * 1. 严格参数白名单校验（PR 编号必须为正整数，repo 必须为合法 owner/repo 格式）；
+     * 2. 并行拉取元数据 (gh pr view) 与 Unified Diff (gh pr diff)；
+     * 3. 在内存通过 splitUnifiedDiff 对 Diff 原文按修改文件切片索引，
+     *    前端点击任一文件即可 0ms 呈现代码行级增删对比，绝无二次网络往返。
+     */
+    getPrDetail(cwd?: string, prNumber?: number | string, repo?: string): Promise<{
+        ok: boolean;
+        data?: PrDetailData;
+        error?: string;
+    }>;
+    /**
+     * 获取 Issue 完整详情（供 IssueDetailModal 在线查看消费）。
+     *
+     * 架构设计：
+     * 1. 严格参数白名单（编号必须为正整数，repo 必须为 owner/repo 形态）——与
+     *    getPrDetail 同一套规则，杜绝任何形式的命令/路径注入；
+     * 2. 单次 `gh issue view --json` 往返即可拿到正文、评论时间线、里程碑与关联 PR，
+     *    不拆成多路并发（Issue 没有 diff 这类重载荷，多开进程反而增加失败面）；
+     * 3. 老版本 gh 遇未知字段会整体失败，因此保留 BASE 字段集降级链。
+     */
+    getIssueDetail(cwd?: string, issueNumber?: number | string, repo?: string): Promise<{
+        ok: boolean;
+        data?: IssueDetailData;
+        error?: string;
+    }>;
     /** 生成当前操作系统平台的推荐安装引导与命令 */
     private getPlatformInstallGuide;
     /**
@@ -176,13 +255,77 @@ export declare class GhExecutor {
      */
     private probeAuth;
     /**
-     * 仅从本地 .git/config 解析仓库身份，绝不发起网络请求。
+     * 从 `refs/remotes/<remote>/HEAD` 符号引用中读取仓库默认分支。
+     *
+     * 为什么只认这一个来源（其余全部实测排除）：
+     *   - `packed-refs` 只存具体 sha，不含 symbolic ref —— 读不到；
+     *   - 当前 HEAD 指向的是**用户 checkout 的分支**，不是仓库默认分支，语义错误；
+     *   - 猜 main/master —— 无依据，宁可回落固定值也不猜。
+     *
+     * @returns 分支名；文件不存在（未 fetch 过）或内容不是符号引用时返回 null，
+     *          由调用方回落到既有默认值（保持原有行为，不引入新错误）
+     */
+    readDefaultBranchFromRef(remoteName: string, cwd?: string): string | null;
+    /**
+     * 解析工作区真实的 git 目录的**两个**路径：局部目录与共享仓库目录。
+     *
+     * 为什么必须分开：worktree 的 `HEAD` 在局部目录（`.git/worktrees/<name>/HEAD`），
+     * 而 `config` 在共享目录（`commondir` 指向处）。只解析其中一个必然读错：
+     *   - 只读局部 → 找不到 config（remote 配置在共享目录）
+     *   - 只读共享 → 拿到**主工作树**的分支名，进而按错误分支查 `branch.*.remote`
+     *
+     * 实测：主工作树 HEAD 是 `ref: refs/heads/master`，worktree 的是 `ref: refs/heads/feat`。
+     *
+     * 常规仓库两者指向同一目录。
+     *
+     * @returns 两个绝对路径；非 Git 目录/指针不可解析时返回 null（绝不抛错）
+     */
+    resolveGitDirInfo(cwd?: string): {
+        localDir: string;
+        commonDir: string;
+    } | null;
+    /**
+     * 解析工作区真实的 git 目录（共享仓库目录）。
+     * 薄封装自 resolveGitDirInfo：读 `config` 的场景（远程指纹）只需要共享目录。
+     */
+    resolveGitDirPath(cwd?: string): string | null;
+    /**
+     * remote 配置指纹：全部 remote url 去重、排序、拼接后取 SHA-256 前 12 位。
+     *
+     * 为什么不用身份解析做缓存失效判定：身份解析要回答「变成了什么」，
+     * 一旦解析器对某种 config 布局有偏差（如双 remote 时取错 remote 段），
+     * 比对就永远失配——缓存再也不命中，每次请求都重拉全部 gh 子进程。
+     * 指纹只回答「变了没有」，不依赖任何语义理解，因此对该类偏差免疫。
+     *
+     * 反例（实测）：`git remote rename origin upstream` 后 `git remote add origin <fork>`，
+     * config 里 upstream 段排在 origin 段前，取「第一个 github.com 匹配」会拿到上游，
+     * 而 git 权威解析（branch.<name>.remote → origin）拿到的是 fork。
+     *
+     * @returns 12 位十六进制指纹；仅当「非 Git 目录 / config 不可读」时返回 null
+     *          （调用方据此保守判定为「未变更」，绝不因探测失败误清空缓存）。
+     *          注意：**config 可读但没有任何 remote 时返回的是空集合的哈希，不是 null**——
+     *          「仓库没有远程」是一个确定事实，它与「读不到配置」必须区分开：
+     *          否则用户删光 remote 后指纹恒为 null，旧快照再也无法失效。
+     */
+    getRemoteFingerprint(cwd?: string): string | null;
+    /**
+     * 读取并解析工作区的 git 远程视图（`.git/config` + `HEAD`）。
+     * 内部方法：把「两个路径各读哪个文件」的细节收敛在一处，
+     * 避免各调用点自己拼路径读错 worktree 的文件。
+     */
+    private readParsedGitConfig;
+    /**
+     * 仅从本地 `.git/config` 解析仓库身份，绝不发起网络请求。
      *
      * 为什么需要它：全局驾驶舱要为每个工作区认识别仓库，而 getRepoMetadata 会调用
      * `gh repo view` 走网络。实测 5 个工作区时该端点冷启动 20.5 秒，其中绝大部分耗在这 5 次
      * 网络往返上——而有界并发根本救不了它，因为瓶颈是网络延迟而不是进程排队。
      * 工作区矩阵只需要「这个目录属于哪个仓库」这一身份信息，本地 .git/config 已经完整具备，
      * 描述/star 数等富字段是当前仓库详情才需要的。这一步把每个工作区从 1 次网络往返降为 0。
+     *
+     * 解析口径与 git 一致（三级回落），不再「取 config 里第一个 github.com 匹配」——
+     * 后者在 `git remote rename origin upstream` + `add origin <fork>` 的布局下会取到上游，
+     * 而 git 认的是 origin（实测）。
      */
     getRepoIdentityFromLocal(cwd?: string): RepoMetadata | null;
     /**