dsh-github-flow 0.2.1 → 0.4.0

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

@@ -0,0 +1,25 @@
+import type { GitLocalStatus, GitCommitEntry, GitBranchesResult } from '../types.js';
+/**
+ * 解析 `git status -sb --porcelain` 输出为结构化状态。
+ * 抽导出纯函数（parseGhVersion 同理）：三形态解析是易错边界区，单测钉死。
+ *
+ * 输出形态（实测）：
+ *   `## master...origin/master [ahead 2, behind 1]`  有 ahead/behind
+ *   `## master...origin/master`                       与远程同步
+ *   `## master` / `## HEAD (no branch)`               无 upstream（ahead/behind 未知=-1）
+ * 后续每行 `<XY> <path>` 为 porcelain 变更项（XY 两字符状态码，?? = untracked）。
+ */
+export declare function parseGitStatusOutput(output: string): GitLocalStatus | null;
+/**
+ * 解析 `git log` 输出为提交条目数组。
+ * 支持两种形态：
+ * 1. 结构化带详情：%x1e 为 commit 间分隔符，%x1f 为字段间分隔符（含 fullSha/email/date/body/stat）；
+ * 2. 简易管道符：%h|%an|%ar|%s 行格式（兼容旧单测输入）。
+ * 空输出返回 []。
+ */
+export declare function parseGitLogLines(output: string): GitCommitEntry[];
+/**
+ * 解析 git branch -a --sort=-committerdate 格式化输出。
+ * 格式为: %(refname:short)|%(HEAD)|%(upstream:short)|%(committerdate:relative)|%(objectname:short)|%(subject)
+ */
+export declare function parseGitBranchLines(output: string): GitBranchesResult;

package/lib/executor/git-parser.js

@@ -0,0 +1,143 @@
+/**
+ * 解析 `git status -sb --porcelain` 输出为结构化状态。
+ * 抽导出纯函数（parseGhVersion 同理）：三形态解析是易错边界区，单测钉死。
+ *
+ * 输出形态（实测）：
+ *   `## master...origin/master [ahead 2, behind 1]`  有 ahead/behind
+ *   `## master...origin/master`                       与远程同步
+ *   `## master` / `## HEAD (no branch)`               无 upstream（ahead/behind 未知=-1）
+ * 后续每行 `<XY> <path>` 为 porcelain 变更项（XY 两字符状态码，?? = untracked）。
+ */
+export function parseGitStatusOutput(output) {
+    const lines = (output || '').split('\n').filter((l) => l.length > 0);
+    if (lines.length === 0 || !lines[0].startsWith('## '))
+        return null;
+    const branchLine = lines[0].slice(3); // 去掉 '## ' 前缀
+    const hasUpstream = branchLine.includes('...');
+    const branchPart = hasUpstream ? branchLine.split('...')[0] : branchLine.split(' ')[0];
+    let ahead = -1;
+    let behind = -1;
+    if (hasUpstream) {
+        // ahead/behind 段在 upstream 之后（可能与 #id 同现：origin/master #12）。
+        // git 输出形态实测：`[ahead 2]` / `[behind 1]` / `[ahead 2, behind 1]`——
+        // 单括号内逗号分隔，behind 不必然前邻 '['（正则不可锚定 '['，否则
+        // `[ahead 2, behind 1]` 形态的 behind 永远漏解析——单测抓到的真实 Bug）
+        const trackingPart = branchLine.split('...')[1] || '';
+        ahead = 0;
+        behind = 0;
+        const aheadMatch = /ahead (\d+)/.exec(trackingPart);
+        const behindMatch = /behind (\d+)/.exec(trackingPart);
+        if (aheadMatch)
+            ahead = Number(aheadMatch[1]);
+        if (behindMatch)
+            behind = Number(behindMatch[1]);
+        // 仅 ahead 无 behind 时 behind=0（反之亦然）——git 输出只列非零侧
+    }
+    const dirtyFiles = [];
+    for (let i = 1; i < lines.length && dirtyFiles.length < 20; i++) {
+        const line = lines[i];
+        if (line.length < 4)
+            continue;
+        const status = line.slice(0, 2).trim() || 'M';
+        // 路径可能含空格（git 不加引号场景）；rename 形态 `R  old -> new` 取 new
+        let p = line.slice(3);
+        const renameArrow = p.indexOf(' -> ');
+        if (renameArrow >= 0)
+            p = p.slice(renameArrow + 4);
+        dirtyFiles.push({ status, path: p });
+    }
+    return {
+        branch: branchPart.replace(/\s*\(no branch\)$/, '') || 'HEAD',
+        ahead,
+        behind,
+        dirtyCount: Math.max(0, lines.length - 1),
+        hasUpstream,
+        dirtyFiles,
+    };
+}
+/**
+ * 解析 `git log` 输出为提交条目数组。
+ * 支持两种形态：
+ * 1. 结构化带详情：%x1e 为 commit 间分隔符，%x1f 为字段间分隔符（含 fullSha/email/date/body/stat）；
+ * 2. 简易管道符：%h|%an|%ar|%s 行格式（兼容旧单测输入）。
+ * 空输出返回 []。
+ */
+export function parseGitLogLines(output) {
+    const out = (output || '').trim();
+    if (!out)
+        return [];
+    if (out.includes('\x1e') || out.includes('\x1f')) {
+        const records = out.split('\x1e').filter((c) => c.trim().length > 0);
+        return records.map((chunk) => {
+            const parts = chunk.split('\x1f');
+            return {
+                sha: (parts[0] || '').trim(),
+                fullSha: (parts[1] || '').trim() || undefined,
+                author: (parts[2] || '').trim(),
+                email: (parts[3] || '').trim() || undefined,
+                date: (parts[4] || '').trim() || undefined,
+                relative: (parts[5] || '').trim(),
+                subject: (parts[6] || '').trim(),
+                body: (parts[7] || '').trim() || undefined,
+                stat: (parts[8] || '').trim() || undefined,
+            };
+        });
+    }
+    return out.split('\n').filter(Boolean).map((line) => {
+        const parts = line.split('|');
+        return {
+            sha: parts[0] || '',
+            author: parts[1] || '',
+            relative: parts[2] || '',
+            subject: parts.slice(3).join('|'),
+        };
+    });
+}
+/**
+ * 解析 git branch -a --sort=-committerdate 格式化输出。
+ * 格式为: %(refname:short)|%(HEAD)|%(upstream:short)|%(committerdate:relative)|%(objectname:short)|%(subject)
+ */
+export function parseGitBranchLines(output) {
+    const lines = output.split(/\r?\n/).map((l) => l.trim()).filter(Boolean);
+    let current = '';
+    const branches = [];
+    const seenNames = new Set();
+    for (const line of lines) {
+        const parts = line.split('|');
+        if (parts.length < 5)
+            continue;
+        const rawRef = parts[0].trim();
+        // 过滤掉指向 HEAD 的符号引用（如 origin/HEAD）
+        if (rawRef.includes('/HEAD') || rawRef === 'HEAD')
+            continue;
+        const isCurrent = parts[1].trim() === '*';
+        const upstream = parts[2].trim() || undefined;
+        const relativeTime = parts[3].trim() || '';
+        const shortSha = parts[4].trim() || '';
+        const subject = parts.slice(5).join('|').trim();
+        // 区分远程分支与本地分支
+        const isRemote = rawRef.startsWith('origin/') || rawRef.startsWith('remotes/');
+        const cleanName = rawRef.replace(/^remotes\//, '');
+        if (seenNames.has(cleanName))
+            continue;
+        seenNames.add(cleanName);
+        if (isCurrent) {
+            current = cleanName;
+        }
+        branches.push({
+            name: cleanName,
+            isCurrent,
+            isRemote,
+            upstream,
+            shortSha,
+            subject,
+            relativeTime,
+        });
+    }
+    // 若未从 * 解析到当前分支，默认以第一条本地分支兜底
+    if (!current && branches.length > 0) {
+        const local = branches.find((b) => !b.isRemote);
+        current = local ? local.name : branches[0].name;
+    }
+    return { current, branches };
+}

package/lib/executor/platform-guide.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 获取当前平台的推荐 gh 安装引导与命令。
+ * 覆盖 Windows (winget/scoop)、macOS (Homebrew/MacPorts)、Linux (apt/dnf)。
+ */
+export declare function getPlatformInstallGuide(): {
+    command: string;
+    altCommand: string;
+    downloadUrl: string;
+    description: string;
+};
+/**
+ * gh 升级命令按平台提示（复用三态状态机的平台判断口径）。
+ */
+export declare function getGhUpgradeHint(): string;

package/lib/executor/platform-guide.js

@@ -0,0 +1,40 @@
+/**
+ * 获取当前平台的推荐 gh 安装引导与命令。
+ * 覆盖 Windows (winget/scoop)、macOS (Homebrew/MacPorts)、Linux (apt/dnf)。
+ */
+export function getPlatformInstallGuide() {
+    const p = process.platform;
+    if (p === 'win32') {
+        return {
+            command: 'winget install --id GitHub.cli',
+            altCommand: 'scoop install gh',
+            downloadUrl: 'https://cli.github.com/',
+            description: '推荐使用 Windows Package Manager (winget) 一键安装，或下载官方 .msi 安装包。',
+        };
+    }
+    if (p === 'darwin') {
+        return {
+            command: 'brew install gh',
+            altCommand: 'port install gh',
+            downloadUrl: 'https://cli.github.com/',
+            description: '推荐使用 Homebrew 安装 GitHub CLI。',
+        };
+    }
+    return {
+        command: 'sudo apt install gh',
+        altCommand: 'sudo dnf install gh',
+        downloadUrl: 'https://cli.github.com/',
+        description: '推荐使用系统包管理器安装（Debian/Ubuntu 运行 apt，Fedora/CentOS 运行 dnf）。',
+    };
+}
+/**
+ * gh 升级命令按平台提示（复用三态状态机的平台判断口径）。
+ */
+export function getGhUpgradeHint() {
+    const p = process.platform;
+    if (p === 'win32')
+        return '升级命令：`winget upgrade GitHub.cli`（或从 https://cli.github.com/ 下载最新 .msi）。';
+    if (p === 'darwin')
+        return '升级命令：`brew upgrade gh`（或从 https://cli.github.com/ 下载最新安装包）。';
+    return '升级方式：更新系统包（Debian/Ubuntu: `sudo apt update && sudo apt install gh`；Fedora: `sudo dnf upgrade gh`），或见 https://cli.github.com/。';
+}

package/lib/executor/process-utils.d.ts

@@ -0,0 +1,51 @@
+/**
+ * spawn 形态的执行通道（stdin 可选注入）。
+ *
+ * 为什么存在：execFile 的 input 选项在本机（node 22.18.0 + Windows）实测从不写入
+ * 子进程 stdin——既无数据也无 EOF，管道永久悬空（gh secret set 等需要 stdin 的
+ * 命令会一直等到超时）。最小复现：execFile+input 对 `cmd /c more` 与 node 子进程
+ * 均挂起；而 spawn + stdin.end(data) 全部正常。此函数即为后者的工程化封装，
+ * 仅在调用方显式传入 stdin 时使用，其余路径保持 execFileAsync 零改动。
+ *
+ * 为什么超时要自己管：spawn 无 timeout 选项，用 kill + SIGTERM 兜底；
+ * 输出按 maxBuffer 手工聚合（上限与 execFile 路径一致，15MB）。
+ */
+export declare function spawnWithStdin(ghPath: string, args: string[], opts: {
+    cwd?: string;
+    timeout: number;
+    env: NodeJS.ProcessEnv;
+    stdin: string;
+}): Promise<{
+    stdout: string | Buffer;
+    stderr: string | Buffer;
+    killed: boolean;
+}>;
+/**
+ * 按码点安全截取字符串，等价于 String.prototype.slice 但对孤立的代理对（surrogate pair）做占位替换。
+ * 为什么必须这样截：本文件末尾会按 UTF-8 字节数截断，而 node:child_process 把 stdout 按字节缓冲区
+ * 切分后再 toString('utf8')，一个汉字被从中间切开时会变成 U+FFFD 替换字符。直接用 slice 会把半截
+ * 代理对留在结果里，导致下游 JSON.stringify 产出孤立转义序列、写入文件时编码报错。
+ */
+export declare function safeSlice(input: string, start: number, end?: number): string;
+/**
+ * 以 UTF-8 字节数（而非字符串长度）为口径，从两端保留内容。
+ * 为什么需要：maxOutputChars 数的是字符，中文一个字占 3 字节。只按字符限长时，
+ * 中文环境下真实放行的字节量可达标称值的数倍，Token 预算保护会失真。
+ * 采用二分查找定位截断点，避免对超大输出逐字符累加造成 O(n) 反复编码。
+ */
+export declare function cutByUtf8Bytes(input: string, headBytes: number, tailBytes: number): {
+    head: string;
+    tail: string;
+    keptHeadBytes: number;
+    keptTailBytes: number;
+    truncated: boolean;
+};
+/**
+ * 按「字符数 + UTF-8 字节数」双口径截断输出。
+ * 抽成纯函数是刻意的：截断逻辑是崩溃高发区（切碎多字节字符、误伤 JSON、把二进制流截成垃圾），
+ * 但通过真实 gh 命令很难稳定复现超限输出，抽出来才能用单元测试覆盖边界。
+ */
+export declare function truncateOutput(input: string, maxChars: number, maxBytes: number): {
+    text: string;
+    truncated: boolean;
+};

package/lib/executor/process-utils.js

@@ -0,0 +1,162 @@
+import { spawn } from 'node:child_process';
+/**
+ * spawn 形态的执行通道（stdin 可选注入）。
+ *
+ * 为什么存在：execFile 的 input 选项在本机（node 22.18.0 + Windows）实测从不写入
+ * 子进程 stdin——既无数据也无 EOF，管道永久悬空（gh secret set 等需要 stdin 的
+ * 命令会一直等到超时）。最小复现：execFile+input 对 `cmd /c more` 与 node 子进程
+ * 均挂起；而 spawn + stdin.end(data) 全部正常。此函数即为后者的工程化封装，
+ * 仅在调用方显式传入 stdin 时使用，其余路径保持 execFileAsync 零改动。
+ *
+ * 为什么超时要自己管：spawn 无 timeout 选项，用 kill + SIGTERM 兜底；
+ * 输出按 maxBuffer 手工聚合（上限与 execFile 路径一致，15MB）。
+ */
+export function spawnWithStdin(ghPath, args, opts) {
+    return new Promise((resolve, reject) => {
+        const child = spawn(ghPath, args, {
+            cwd: opts.cwd,
+            env: opts.env,
+            windowsHide: true,
+            stdio: ['pipe', 'pipe', 'pipe'],
+        });
+        const outChunks = [];
+        const errChunks = [];
+        let totalBytes = 0;
+        let killed = false;
+        let settled = false;
+        const timer = setTimeout(() => {
+            killed = true;
+            child.kill();
+        }, opts.timeout);
+        const settle = (err) => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (err)
+                reject(err);
+            else
+                resolve({ stdout: Buffer.concat(outChunks), stderr: Buffer.concat(errChunks), killed });
+        };
+        // 聚合上限：超出即杀（与 execFile maxBuffer 语义一致；gh 正常输出远小于此）
+        const MAX_BYTES = 15 * 1024 * 1024;
+        child.stdout?.on('data', (d) => {
+            totalBytes += d.length;
+            outChunks.push(d);
+            if (totalBytes > MAX_BYTES) {
+                killed = true;
+                child.kill();
+            }
+        });
+        child.stderr?.on('data', (d) => { errChunks.push(d); });
+        child.on('error', (err) => {
+            // spawn 失败（如 ENOENT）对齐 execFile 的错误形状：code 保留在 Error 上
+            const e = Object.assign(new Error(err.message), { code: err.code });
+            settle(e);
+        });
+        child.on('close', (code, signal) => {
+            if (killed) {
+                // 超时/超量被杀：对齐 execFile 的 Timeout 错误形状（err.killed + signal）
+                const e = Object.assign(new Error(`Command timed out after ${opts.timeout}ms`), { killed: true, signal: signal || 'SIGTERM' });
+                settle(e);
+                return;
+            }
+            if (code !== 0) {
+                const e = Object.assign(new Error(`Command failed with exit code ${code}`), { code, stderr: Buffer.concat(errChunks).toString('utf8').slice(0, 800) });
+                settle(e);
+                return;
+            }
+            settle();
+        });
+        // stdin 注入：end(data) 半关闭（写完即 EOF），子进程流式读取或一次性读取均可
+        child.stdin?.end(opts.stdin, (err) => {
+            if (err && !settled) {
+                const e = Object.assign(new Error(`stdin write failed: ${err.message}`), { code: 'EPIPE' });
+                settle(e);
+            }
+        });
+    });
+}
+/**
+ * 按码点安全截取字符串，等价于 String.prototype.slice 但对孤立的代理对（surrogate pair）做占位替换。
+ * 为什么必须这样截：本文件末尾会按 UTF-8 字节数截断，而 node:child_process 把 stdout 按字节缓冲区
+ * 切分后再 toString('utf8')，一个汉字被从中间切开时会变成 U+FFFD 替换字符。直接用 slice 会把半截
+ * 代理对留在结果里，导致下游 JSON.stringify 产出孤立转义序列、写入文件时编码报错。
+ */
+export function safeSlice(input, start, end) {
+    const chars = Array.from(input);
+    const from = Math.max(0, start);
+    const to = end === undefined ? chars.length : Math.max(from, end);
+    return chars.slice(from, to).map((c) => (c.length === 1 && c.charCodeAt(0) >= 0xd800 && c.charCodeAt(0) <= 0xdfff ? '\ufffd' : c)).join('');
+}
+/**
+ * 以 UTF-8 字节数（而非字符串长度）为口径，从两端保留内容。
+ * 为什么需要：maxOutputChars 数的是字符，中文一个字占 3 字节。只按字符限长时，
+ * 中文环境下真实放行的字节量可达标称值的数倍，Token 预算保护会失真。
+ * 采用二分查找定位截断点，避免对超大输出逐字符累加造成 O(n) 反复编码。
+ */
+export function cutByUtf8Bytes(input, headBytes, tailBytes) {
+    const encoder = new TextEncoder();
+    const totalBytes = encoder.encode(input).length;
+    if (totalBytes <= headBytes + tailBytes) {
+        return { head: input, tail: '', keptHeadBytes: totalBytes, keptTailBytes: 0, truncated: false };
+    }
+    const chars = Array.from(input);
+    const atByte = (limit, fromEnd) => {
+        let lo = 0;
+        let hi = chars.length;
+        let bytes = 0;
+        while (lo < hi) {
+            const mid = (lo + hi + 1) >> 1;
+            const slice = fromEnd ? chars.slice(chars.length - mid) : chars.slice(0, mid);
+            const size = encoder.encode(slice.join('')).length;
+            if (size <= limit) {
+                lo = mid;
+                bytes = size;
+            }
+            else {
+                hi = mid - 1;
+            }
+        }
+        return { count: lo, bytes };
+    };
+    const headPart = atByte(headBytes, false);
+    const tailPart = atByte(tailBytes, true);
+    return {
+        head: safeSlice(input, 0, headPart.count),
+        tail: safeSlice(input, chars.length - tailPart.count),
+        keptHeadBytes: headPart.bytes,
+        keptTailBytes: tailPart.bytes,
+        truncated: true,
+    };
+}
+/**
+ * 按「字符数 + UTF-8 字节数」双口径截断输出。
+ * 抽成纯函数是刻意的：截断逻辑是崩溃高发区（切碎多字节字符、误伤 JSON、把二进制流截成垃圾），
+ * 但通过真实 gh 命令很难稳定复现超限输出，抽出来才能用单元测试覆盖边界。
+ */
+export function truncateOutput(input, maxChars, maxBytes) {
+    // 双重口径限长：字符数守住 Token 预算，字节数守住真实传输量。
+    // 中文场景下两者会分别触发，因此两条路径的提示文案必须区分，避免用户按错误的配置项去调参。
+    if (input.length > maxChars) {
+        // 保留前 1/3 字符和尾部 1/2 字符，保留开头上下文和错误尾部
+        const headLen = Math.floor(maxChars * 0.35);
+        const tailLen = Math.floor(maxChars * 0.55);
+        const head = safeSlice(input, 0, headLen);
+        const tail = safeSlice(input, input.length - tailLen);
+        return {
+            text: `${head}\n\n... [⚠️ 提示：内容过长已由 DSH GitHub 插件截断中间部分，当前截取前 ${Math.round(headLen / 1024)}KB 与后 ${Math.round(tailLen / 1024)}KB] ...\n\n${tail}`,
+            truncated: true,
+        };
+    }
+    const byteCut = cutByUtf8Bytes(input, Math.floor(maxBytes * 0.35), Math.floor(maxBytes * 0.55));
+    if (byteCut.truncated) {
+        // 这里必须用「实际保留的字节数」而非 maxChars 推导值：字节口径触发时 maxChars 往往远大于
+        // 字节上限，早先版本照抄字符分支的算法，会报出与实际严重不符的「已保留 100KB」（实际仅数百字节）。
+        return {
+            text: `${byteCut.head}\n\n... [⚠️ 提示：内容超出 UTF-8 字节上限 (${maxBytes} bytes) 已截断中间部分，实际保留前 ${byteCut.keptHeadBytes} 字节与后 ${byteCut.keptTailBytes} 字节；如需放宽请调大配置项 maxOutputBytes] ...\n\n${byteCut.tail}`,
+            truncated: true,
+        };
+    }
+    return { text: input, truncated: false };
+}

package/lib/executor/version-utils.d.ts

@@ -0,0 +1,12 @@
+/**
+ * 从 `gh --version` 输出中解析语义化版本号。
+ * 抽成导出纯函数的原因与 truncateOutput 相同：解析逻辑是「看似简单实则易错」的边界区，
+ * 必须能用单元测试钉死（不匹配输入返回 null 而非抛错，调用方据此走 fail-open）。
+ */
+export declare function parseGhVersion(output: string): string | null;
+/**
+ * 数值分段比较两个 gh 版本：a>b 返回 1、a<b 返回 -1、相等返回 0。
+ * 为什么不能用字符串比较：`'2.96.0' < '2.100.0'` 在字典序下为 false（'1'<'9'），
+ * 这会把 2.100 误判为低于 2.96，导致可用命令被错误降级。逐段 Number 比较是唯一正确姿势。
+ */
+export declare function compareGhVersions(a: string, b: string): number;

package/lib/executor/version-utils.js

@@ -0,0 +1,27 @@
+/**
+ * 从 `gh --version` 输出中解析语义化版本号。
+ * 抽成导出纯函数的原因与 truncateOutput 相同：解析逻辑是「看似简单实则易错」的边界区，
+ * 必须能用单元测试钉死（不匹配输入返回 null 而非抛错，调用方据此走 fail-open）。
+ */
+export function parseGhVersion(output) {
+    const m = /gh version (\d+\.\d+\.\d+)/.exec(output || '');
+    return m ? m[1] : null;
+}
+/**
+ * 数值分段比较两个 gh 版本：a>b 返回 1、a<b 返回 -1、相等返回 0。
+ * 为什么不能用字符串比较：`'2.96.0' < '2.100.0'` 在字典序下为 false（'1'<'9'），
+ * 这会把 2.100 误判为低于 2.96，导致可用命令被错误降级。逐段 Number 比较是唯一正确姿势。
+ */
+export function compareGhVersions(a, b) {
+    const pa = a.split('.').map(Number);
+    const pb = b.split('.').map(Number);
+    for (let i = 0; i < Math.max(pa.length, pb.length); i++) {
+        const da = pa[i] ?? 0;
+        const db = pb[i] ?? 0;
+        if (da > db)
+            return 1;
+        if (da < db)
+            return -1;
+    }
+    return 0;
+}

package/lib/executor.d.ts

@@ -1,14 +1,10 @@
-import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig } from './types.js';
+import type { GhExecutionOptions, GhResult, AuthStatus, RepoMetadata, PluginConfig, GitLocalStatus, GitCommitLog, GitCommitEntry, GitBranchesResult } from './types.js';
 import type { ProxyManager } from './proxy.js';
-/**
- * 按「字符数 + UTF-8 字节数」双口径截断输出。
- * 抽成纯函数是刻意的：截断逻辑是崩溃高发区（切碎多字节字符、误伤 JSON、把二进制流截成垃圾），
- * 但通过真实 gh 命令很难稳定复现超限输出，抽出来才能用单元测试覆盖边界。
- */
-export declare function truncateOutput(input: string, maxChars: number, maxBytes: number): {
-    text: string;
-    truncated: boolean;
-};
+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 { getPlatformInstallGuide, getGhUpgradeHint } from './executor/platform-guide.js';
+export { parseGhVersion, compareGhVersions, spawnWithStdin, safeSlice, cutByUtf8Bytes, truncateOutput, parseGitStatusOutput, parseGitLogLines, parseGitBranchLines, getPlatformInstallGuide, getGhUpgradeHint, };
 export declare class GhExecutor {
     ghPath: string;
     defaultTimeoutMs: number;
@@ -22,6 +18,12 @@ export declare class GhExecutor {
      * 且热更新路径 updateConfig 能同步刷新。工具内以 `?? 20` 兜底保证旧配置兼容。
      */
     defaultListLimit: number;
+    /**
+     * 是否注入 AI_AGENT='dsh'（gh 官方 agent 识别信号，默认 true）。
+     * 挂在 executor 而非工具参数：注入点是「每次 gh 子进程拉起」这一全局咽喉，
+     * 与 GH_NO_UPDATE_NOTIFIER/NO_COLOR 同级，语义上属于执行层默认值。
+     */
+    agentEnvInjection: boolean;
     /**
      * 代理管理器引用（可选依赖）。
      * 注入后每次 gh 子进程拉起都会合并代理环境变量——这是「工具调用 + Web 页面数据
@@ -31,17 +33,22 @@ export declare class GhExecutor {
     private proxyManager?;
     /** 认证状态缓存。`gh auth status` 实测 5.4 秒，而它位于全局驾驶舱关键路径的最前面 */
     private authCache;
+    /**
+     * gh 版本号缓存。只缓存成功解析值（authCache 哲学：不确定结果不缓存）——
+     * 探测失败/未安装时不落缓存，用户装好 gh 后下一次探测立即生效。
+     */
+    private ghVersionCache;
     constructor(config?: PluginConfig);
     updateConfig(config?: PluginConfig): void;
     /** 注入代理管理器（main.ts 装配时调用一次；测试可注入 mock） */
     attachProxyManager(manager: ProxyManager): void;
     /**
-     * 智能解析最可靠的工作区物理路径：
-     * 1. 优先使用显式指定的有效 cwd（若包含 .git 目录）
-     * 2. 使用显式传入的 sessionId 或环境变量 DSH_SESSION_ID 精确反查工作区
-     * 3. 递归探测：若传入了 explicitCwd（如聚合父目录），自动检查其直系子目录中是否包含 Git 仓库
-     * 4. 匹配 ~/.dsh/storages/workspace.json 中最近活跃且存在 .git 的仓库工作区
-     * 5. 回退到 process.cwd()
+     * 解析命令实际执行的工作区根目录
+     * 严格遵循数据事实源与工作区物理所有权，消除越权篡改：
+     * 1. 显式路径第一优先级：调用方只要显式指定了路径，该物理路径即为唯一事实源，原样返回自身；
+     *    绝不递归扫描子目录、绝不越权篡改；无 Git 目录则让下游探测真实反映无 Git 状态；
+     * 2. 仅在未显式指定 cwd 时，才尝试使用 sessionId 或环境变量 DSH_SESSION_ID 反查工作区；
+     * 3. 仅在完全未指定 cwd 且无会话时（全局命令行调用），才兜底回退到最近活跃的 Git 工作区或 process.cwd()。
      */
     resolveWorkspaceCwd(explicitCwd?: string, explicitSessionId?: string): string;
     /**
@@ -57,9 +64,116 @@ export declare class GhExecutor {
      *   而 Web 面板每次挂载都会来问一次，重复执行实测要 5.4 秒，属于纯浪费。
      */
     checkAuth(cwd?: string, bypassCache?: boolean): Promise<AuthStatus>;
+    /**
+     * 获取当前 gh 版本号（带 30s TTL 缓存），失败返回 null。
+     * 底层直连 execFileAsync 而不走 this.run()：run() 会先解析工作区（可能读
+     * workspace.json 与目录扫描）再做截断/JSON 解析，对一次 10ms 的版本字符串
+     * 查询是纯开销；直连也彻底规避 runGuarded → 探测 → run 的递归风险。
+     */
+    getGhVersion(): Promise<string | null>;
+    /**
+     * 底层版本探测（独立方法而非内联：测试需要在不触发真实子进程的前提下
+     * 验证 getGhVersion 的缓存分支——覆写此方法即注入确定输出）。
+     * 直连 execFileAsync 而不走 this.run()：run() 会先解析工作区（可能读
+     * workspace.json 与目录扫描）再做截断/JSON 解析，对一次 10ms 的版本字符串
+     * 查询是纯开销；直连也彻底规避 runGuarded → 探测 → run 的递归风险。
+     */
+    protected probeGhVersionRaw(): Promise<string>;
+    /**
+     * 守卫执行器：按 gh 版本门槛路由「主命令 → 降级链路 → 升级指引」三态。
+     *
+     * 为什么是「检查+执行」一体的方法而非纯探测接口：检查与执行分离会在两者之间
+     * 留下竞隙（版本可能在间隙变化），且降级标注逻辑会被迫散落到每个工具的 if/else。
+     *
+     * fail-open 纪律：版本探测自身失败（null）时直接执行主命令——守卫是路由优化
+     * 不是安全边界，探测故障不应拦截业务；gh 未安装场景由主命令产出既有 ENOENT
+     * 安装引导，这里不重复造错误路径。
+     */
+    runGuarded<T = unknown>(args: string[], options?: GhExecutionOptions & {
+        /** 该能力要求的最低 gh 版本，如 '2.95.0'；缺省时等价于直接 run（渐进采用） */
+        minVersion?: string;
+        /** 人类可读能力名，用于错误信息，如 'gh repo read-file' */
+        capability?: string;
+        /** 版本不足时的降级链路（如 github_api contents 端点封装）；无则报错带升级指引 */
+        fallback?: () => Promise<GhResult<T>>;
+    }): Promise<GhResult<T> & {
+        degraded?: boolean;
+        degradedReason?: string;
+    }>;
+    /** gh 升级命令按平台提示（复用三态状态机的平台判断口径） */
+    private getGhUpgradeHint;
+    /**
+     * 本地 Git 状态只读探测（白名单通道）。
+     *
+     * 这是本插件首次执行 git（此前仅 gh）——git 存在大量写命令，风险等级高于 gh，
+     * 因此白名单不落在「命令名过滤」而落在「命令形态常量」：spawn 参数是下方
+     * 硬编码的数组字面量，无任何动态拼接路径，写操作物理不可达（cwd 之外零输入，
+     * 而 cwd 本身也是插件解析的工作区路径）。
+     *
+     * 零网络：status 基于 remote-tracking ref（上次 fetch 的快照），毫秒级本地读取，
+     * 符合 global-overview 端点「工作区探测不发网络」的性能红线。
+     */
+    getLocalGitStatus(cwd?: string): Promise<GitLocalStatus | null>;
+    /**
+     * 本地 Git 提交记录（三段一次返回：本地领先 / 远程领先 / 最近提交）。
+     *
+     * 白名单纪律与 getLocalGitStatus 同源：下方两个命令形态常量硬编码
+     * （log + 修订范围语法，range 段由 hasUpstream 守卫后才拼接且仅两个
+     * 固定形态 @{u}..HEAD / HEAD..@{u}——不含任何用户输入路径）。
+     * 领先/落后列表基于 remote-tracking ref（上次 fetch 快照），与 status
+     * 的 ahead/behind 计数同一数据口径；格式 %h|%an|%ar|%s 实测可结构化解析。
+     */
+    getGitCommitLog(cwd?: string, hasUpstream?: boolean, limit?: number): Promise<GitCommitLog | null>;
+    /**
+     * 分页获取最近提交记录（用于 Git 面板下滑触底继续加载）。
+     */
+    getGitRecentLog(cwd?: string, limit?: number, skip?: number): Promise<{
+        commits: GitCommitEntry[];
+        totalCount?: number;
+    }>;
+    /**
+     * 单条提交详情（点击提交行弹窗的数据源）。
+     * 白名单纪律延续：show 命令形态常量硬编码；sha 参数经 ^[0-9a-f]{4,40}$
+     * 十六进制校验后才拼接——这是 git 白名单通道首次接受「外部传入的单值」，
+     * 正则把值域锁死在纯十六进制（注入面为零：任何 shell 元字符/子命令
+     * 语法都不可能通过校验）。输出为 git show --stat 原文（含文件变更统计）。
+     */
+    getGitCommitDetail(cwd: string | undefined, sha: string): Promise<string | null>;
+    /**
+     * 纯本地读取工作区的所有 Git 分支（按提交时间倒序）。
+     * 包含当前 HEAD 分支标记、关联 upstream、最新提交简述与相对时间。
+     * 零网络往返，毫秒级本地管道输出。
+     */
+    getGitBranches(cwd?: string): Promise<GitBranchesResult | null>;
+    /**
+     * 安全切换当前工作区的 Git 分支。
+     * 三重安全防御纪律：
+     * 1. 目标工作区必须存在有效的 .git 目录；
+     * 2. 分支名称严格执行字符白名单校验，防命令行参数注入；
+     * 3. 检查工作区干净度（dirtyCount），若有未提交或未保存的变更直接阻断，杜绝代码被破坏性覆盖。
+     */
+    switchGitBranch(cwd: string | undefined, branchName: string): Promise<{
+        ok: boolean;
+        currentBranch?: string;
+        error?: string;
+    }>;
     /** 生成当前操作系统平台的推荐安装引导与命令 */
     private getPlatformInstallGuide;
-    /** 实际执行 `gh auth status` 并解析结果，不含缓存逻辑 */
+    /**
+     * 纯本地检测宿主机 GitHub CLI 配置文件中是否存在已配置的账号凭据。
+     * 零子进程、零网络往返，毫秒级读取，专供断网与网络卡顿时的 Fail-Safe 容灾降级。
+     */
+    checkLocalGhCredential(): {
+        user?: string;
+        hasToken: boolean;
+    } | null;
+    /**
+     * 实际执行认证探测并解析结果，不含外部缓存逻辑。
+     * 解耦本地安装态、本地凭据态与网络可达态：
+     * 1. 安装态通过 getGhVersion 本地轻量确认，网络超时/断网绝不篡改 installed 结论；
+     * 2. 本地凭据通过 checkLocalGhCredential 读取，断网时仍可识别人类账号；
+     * 3. 精准分流网络超时/异常（networkError）与真正的未认证（explicitLoggedOut）。
+     */
     private probeAuth;
     /**
      * 仅从本地 .git/config 解析仓库身份，绝不发起网络请求。