dsh-git-ui 0.0.2 → 0.1.1

package/src/host/index.ts

@@ -1,96 +1,102 @@
 /**
- * dsh-git-ui host half: the `gitInfo` Remote service.
+ * dsh-git-ui host 适配层：Cordis/typert 壳。
  *
- * Cordis shell only — every behavior lives in `core.ts`/`actions.ts` behind
- * injected structural faces, so tests never need a cordis runtime. The class
- * is a plugin in its own right (class form), mounted by the bundle patch row
- * with the package name; the gateway exposes `gitInfo/snapshot` and
- * `gitInfo/run` through SRC discovery (`typertRemote` binding + `@Remote`
- * marker).
+ * 本文件是 host 端**唯一** import `@deepseek-ai/*` 的地方。职责：
+ *   1. 将 Cordis 服务（subprocess / sessions / sessionPersistence）适配为
+ *      结构化 `SnapshotDeps` 接口；
+ *   2. 调用 `createHostEndpoints(deps, config)` 获得纯业务端点；
+ *   3. 以 `@Remote` 装饰器将端点暴露给 typert Gateway。
+ *
+ * 业务逻辑全部在 `contracts/host-endpoints.ts` → `host/core.ts` /
+ * `host/actions.ts` / `host/queries.ts`，与框架无关。
  */
 import { Remote, TypertRemoteService } from '@deepseek-ai/dsh-typert-protocol'
 import type { Context } from '@deepseek-ai/cordis'
 import { realpath, stat } from 'node:fs/promises'
 import { createGitRunner, type SubprocessLike } from './git.ts'
-import { normalizeConfig, snapshotForSession, type GitStatusConfig, type SnapshotDeps } from './core.ts'
-import { runAction } from './actions.ts'
-import type { GitActionResult, GitActionRequest, GitSnapshotRequest, GitSnapshotResult } from './types.ts'
+import { normalizeConfig, type GitStatusConfig, type SnapshotDeps } from './core.ts'
+import { createHostEndpoints, type HostEndpoints } from '../contracts/host-endpoints.ts'
+import type { GitActionRequest, GitActionResult, GitQueryRequest, GitQueryResponse, GitSnapshotRequest, GitSnapshotResult } from './types.ts'
 
-export type { GitSnapshot, GitSnapshotResult, GitSnapshotFailure, GitSnapshotRequest, GitCommit, GitChange, GitAction, GitActionResult, GitActionRequest } from './types.ts'
+export type { GitSnapshot, GitSnapshotResult, GitSnapshotFailure, GitSnapshotRequest, GitCommit, GitChange, GitAction, GitActionResult, GitActionRequest, GitQuery, GitQueryResult, GitQueryRequest, GitQueryResponse, GitBranch, GitFileStat, GitRef } from './types.ts'
 export { normalizeConfig, DEFAULT_CONFIG } from './core.ts'
-export { parseStatusOutput, parseLogOutput, parseBranchOutput } from './parser.ts'
-export { isSafePath, runAction } from './actions.ts'
-
-/** Structural face of a live session header. */
-interface SessionLike {
-  readonly header?: { readonly cwd?: string }
-}
+export { parseStatusOutput, parseLogOutput, parseBranchOutput, parseNameStatusOutput } from './parser.ts'
+export { isSafePath, isValidBranchName, runAction } from './actions.ts'
+export { runQuery } from './queries.ts'
+export { createHostEndpoints, type HostEndpoints } from '../contracts/host-endpoints.ts'
 
-/** Structural face of the sessions service. */
+/** Cordis sessions 服务的结构化切片。 */
 interface SessionsLike {
-  get(id: string): SessionLike | undefined
+  get(id: string): { readonly header?: { readonly cwd?: string } } | undefined
 }
 
-/** Structural face of the session-persistence service. */
+/** Cordis sessionPersistence 服务的结构化切片。 */
 interface SessionPersistenceLike {
   inspect(id: string): Promise<{ readonly meta: { readonly cwd?: string } }>
 }
 
-/** The `gitInfo` service: `snapshot` (read) and `run` (management) endpoints. */
+/**
+ * gitInfo Remote 服务：Cordis 壳。
+ *
+ * 构造时从 Cordis Context 取出宿主服务，适配为 `SnapshotDeps`，再调用
+ * `createHostEndpoints` 获得纯业务端点。三个 `@Remote` 方法仅做委托。
+ */
 export class GitStatusService extends TypertRemoteService {
   static inject = ['subprocess', 'sessions', 'sessionPersistence']
 
-  private readonly config: GitStatusConfig
+  private readonly endpoints: HostEndpoints
 
   constructor(ctx: Context, config: unknown) {
     super(ctx, 'gitInfo')
-    this.config = normalizeConfig(config)
+    const normalizedConfig = normalizeConfig(config)
+    const deps = this.buildDeps(ctx, normalizedConfig)
+    this.endpoints = createHostEndpoints(deps, normalizedConfig)
   }
 
-  /** Adapter face shared by both endpoints (injected services + runner). */
-  private deps(signal?: AbortSignal): { readonly deps: SnapshotDeps } | { readonly failure: { readonly code: 'git-unavailable'; readonly detail: string } } {
-    const subprocess = this.ctx.get('subprocess') as SubprocessLike | undefined
+  /** 将 Cordis 服务适配为结构化 SnapshotDeps。 */
+  private buildDeps(ctx: Context, config: GitStatusConfig): SnapshotDeps {
+    const subprocess = ctx.get('subprocess') as SubprocessLike | undefined
     if (subprocess === undefined) {
-      return { failure: { code: 'git-unavailable', detail: 'subprocess service unavailable' } }
+      // 返回一个永远失败的 deps——端点调用会走到 git-unavailable 降级路径。
+      return {
+        run: { run: async () => { throw new Error('subprocess service unavailable') } },
+        fs: { realpath, stat },
+        sessions: { liveCwd: () => undefined, persistedMeta: async () => undefined },
+      }
     }
-    const sessions = this.ctx.get('sessions') as SessionsLike | undefined
-    const persistence = this.ctx.get('sessionPersistence') as SessionPersistenceLike | undefined
-    const runner = createGitRunner(subprocess, this.config.timeoutMs, this.config.maxStatusBytes)
+    const sessions = ctx.get('sessions') as SessionsLike | undefined
+    const persistence = ctx.get('sessionPersistence') as SessionPersistenceLike | undefined
     return {
-      deps: {
-        run: runner,
-        fs: { realpath, stat },
-        sessions: {
-          liveCwd: (id) => sessions?.get(id)?.header?.cwd,
-          persistedMeta: async (id) => {
-            if (persistence === undefined) return undefined
-            try {
-              const inspection = await persistence.inspect(id)
-              return { cwd: inspection.meta.cwd }
-            } catch {
-              return undefined
-            }
-          },
+      run: createGitRunner(subprocess, config.timeoutMs, config.maxStatusBytes),
+      fs: { realpath, stat },
+      sessions: {
+        liveCwd: (id) => sessions?.get(id)?.header?.cwd,
+        persistedMeta: async (id) => {
+          if (persistence === undefined) return undefined
+          try {
+            const inspection = await persistence.inspect(id)
+            return { cwd: inspection.meta.cwd }
+          } catch {
+            return undefined
+          }
         },
-        signal,
       },
     }
   }
 
   @Remote('snapshot')
   async snapshot(request: GitSnapshotRequest, signal?: AbortSignal): Promise<GitSnapshotResult> {
-    const adapted = this.deps(signal)
-    if ('failure' in adapted) return { ok: false, error: adapted.failure }
-    return snapshotForSession(adapted.deps, this.config, request.sessionId)
+    return this.endpoints.snapshot(request, signal)
   }
 
   @Remote('run')
   async run(request: GitActionRequest, signal?: AbortSignal): Promise<GitActionResult> {
-    const adapted = this.deps(signal)
-    if ('failure' in adapted) {
-      return { ok: false, error: { code: 'git-error', message: adapted.failure.detail } }
-    }
-    return runAction(adapted.deps, this.config, request)
+    return this.endpoints.run(request, signal)
+  }
+
+  @Remote('query')
+  async query(request: GitQueryRequest, signal?: AbortSignal): Promise<GitQueryResponse> {
+    return this.endpoints.query(request, signal)
   }
 }
 

package/src/host/parser.ts

@@ -3,7 +3,7 @@
  * No side effects and no I/O — fully unit-testable against literal fixtures
  * (verified against real `git status --porcelain=v1 -z --branch` output).
  */
-import type { GitChange, GitChangeStatus, GitCommit } from './types.ts'
+import type { GitChange, GitChangeStatus, GitCommit, GitRef, GraphCommit } from './types.ts'
 
 /** Parsed status counts plus the (possibly capped) change list. */
 export interface ParsedStatus {
@@ -75,11 +75,9 @@ export function parseStatusHeader(line: string): StatusHeader {
   return { branch: branch === '' ? null : branch, unborn: false, ahead, behind }
 }
 
-/** Map one porcelain XY pair to a change status. */
-function changeStatus(x: string, y: string): GitChangeStatus {
-  if (x === '?' && y === '?') return 'untracked'
-  if (x === 'U' || y === 'U' || (x !== ' ' && y !== ' ')) return 'conflicted'
-  switch (x) {
+/** 单列状态码 → 变更状态映射（真实冲突由 isConflicted 单独判定）。 */
+function singleStatus(code: string): GitChangeStatus {
+  switch (code) {
     case 'A': return 'added'
     case 'M': return 'modified'
     case 'D': return 'deleted'
@@ -90,11 +88,25 @@ function changeStatus(x: string, y: string): GitChangeStatus {
   }
 }
 
+/**
+ * 真实合并冲突：任一侧为 U（UU/AU/UD/UA/DU），或双方同添/同删（AA/DD）。
+ * 注意 MM/AM/MD 等「已暂存 + 工作区再改」是合法混合态而非冲突
+ * （旧规则「双列均非空即冲突」会把 MM 误报为冲突）。
+ */
+function isConflicted(x: string, y: string): boolean {
+  return x === 'U' || y === 'U' || (x === 'A' && y === 'A') || (x === 'D' && y === 'D')
+}
+
 /**
  * Parse the full `git status --porcelain=v1 -z --branch` output.
  * -z format: every entry (header and each `XY path`) is NUL-terminated; a
  * rename/copy entry emits `R  <new>\0<old>\0` so the following item is the
  * source path and must be consumed without becoming a change itself.
+ *
+ * 混合状态拆分（IDEA 式）：X、Y 均非空的合法对（MM/AM/MD/RM…）拆为
+ * 「已暂存侧 + 未暂存侧」两条 GitChange——UI 据此把同一文件分别列入
+ * 「已暂存更改」与「更改」两组，两侧可独立操作、差异基线唯一。
+ * 真实冲突（isConflicted）保持单条 conflicted 条目。
  */
 export function parseStatusOutput(output: string, maxChanges: number): ParsedStatus {
   const raw = output.split(NUL)
@@ -108,6 +120,17 @@ export function parseStatusOutput(output: string, maxChanges: number): ParsedSta
   const changes: GitChange[] = []
   let truncated = false
 
+  /** 收录一条变更条目；超出上限仅置截断标记（计数不受影响）。
+   * isDirectory 由 git 输出权威标记（未跟踪目录条目为 `dir/` 尾斜杠），
+   * 展示层依赖此字段，不再自行解析路径字符串。 */
+  const pushChange = (path: string, status: GitChangeStatus, isStaged: boolean): void => {
+    if (changes.length < maxChanges) {
+      changes.push({ path, status, staged: isStaged, isDirectory: path.endsWith('/') })
+    } else {
+      truncated = true
+    }
+  }
+
   for (let index = 1; index < segments.length; index += 1) {
     const entry = segments[index] ?? ''
     const x = entry[0] ?? ' '
@@ -120,14 +143,23 @@ export function parseStatusOutput(output: string, maxChanges: number): ParsedSta
     }
     if (x === '?' && y === '?') {
       untracked += 1
-    } else {
-      if (x !== ' ' && x !== '?') staged += 1
-      if (y !== ' ' && y !== '?') modified += 1
+      pushChange(path, 'untracked', false)
+      continue
     }
-    if (changes.length < maxChanges) {
-      changes.push({ path, status: changeStatus(x, y), staged: x !== ' ' && x !== '?' })
+    // 计数仍按 X/Y 两列分别累计；拆双条目不改变总数。
+    if (x !== ' ' && x !== '?') staged += 1
+    if (y !== ' ' && y !== '?') modified += 1
+
+    if (isConflicted(x, y)) {
+      // 冲突文件按单条展示（IDEA 冲突条目形态），归入已暂存组。
+      pushChange(path, 'conflicted', true)
+    } else if (x !== ' ' && y !== ' ') {
+      // 混合态：已暂存侧状态取 X，未暂存侧状态取 Y。
+      pushChange(path, singleStatus(x), true)
+      pushChange(path, singleStatus(y), false)
     } else {
-      truncated = true
+      const isStaged = x !== ' '
+      pushChange(path, singleStatus(isStaged ? x : y), isStaged)
     }
   }
 
@@ -166,6 +198,116 @@ export function parseLogOutput(output: string): readonly GitCommit[] {
   return commits
 }
 
+/**
+ * 解析带图的 log 输出：
+ * `%H%x1f%h%x1f%s%x1f%an%x1f%aI%x1f%P%x1f%D`
+ * 其中 `%P` 为空格分隔的父提交哈希（根提交为空），`%D` 为 ref 装饰。
+ * 返回适合分支图渲染器的 `GraphCommit[]`。
+ */
+export function parseGraphLogOutput(output: string, remotes: readonly string[] = []): readonly GraphCommit[] {
+  const commits: GraphCommit[] = []
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+    const [hash, shortHash, subject, author, dateIso, parentField, decoField] = line.split(LOG_SEP)
+    if (hash === undefined || hash === '') continue
+    const parents = (parentField ?? '')
+      .split(' ')
+      .filter((p) => p !== '')
+    commits.push({
+      hash,
+      shortHash: shortHash ?? '',
+      subject: subject ?? '',
+      author: author ?? '',
+      dateIso: dateIso ?? '',
+      parents,
+      refs: parseDecorations(decoField ?? '', remotes),
+    })
+  }
+  return commits
+}
+
+/**
+ * 解析 `%D` 装饰串，形如 `HEAD -> main, origin/main, tag: v1.0`；空串无 refs。
+ * 分类规则：`HEAD -> x` 为当前分支；`tag: t` 为标签；
+ * 带远程前缀（`<remote>/…`）为远程分支；其余为本地分支。
+ */
+export function parseDecorations(decorations: string, remotes: readonly string[]): readonly GitRef[] {
+  const trimmed = decorations.trim()
+  if (trimmed === '') return []
+  const refs: GitRef[] = []
+  for (const token of trimmed.split(', ')) {
+    if (token.startsWith('HEAD -> ')) {
+      refs.push({ kind: 'branch', name: token.slice(8), head: true })
+    } else if (token.startsWith('tag: ')) {
+      refs.push({ kind: 'tag', name: token.slice(5), head: false })
+    } else if (remotes.some((remote) => token === remote || token.startsWith(`${remote}/`))) {
+      refs.push({ kind: 'remote', name: token, head: false })
+    } else {
+      refs.push({ kind: 'branch', name: token, head: false })
+    }
+  }
+  return refs
+}
+
+/**
+ * 解析 `git show -s --format=%H%x1f%h%x1f%s%x1f%an%x1f%aI%x1f%b` 输出：
+ * 前五个字段为机器可读元数据，第六字段起为 %b 正文
+ * （%b 已排除 subject 首段落，天然无重复展示问题）。
+ */
+export function parseShowMeta(output: string): { readonly commit: GitCommit; readonly body: string } | null {
+  const trimmed = output.trimEnd()
+  if (trimmed === '') return null
+  const [hash, shortHash, subject, author, dateIso, ...bodyParts] = trimmed.split(LOG_SEP)
+  if (hash === undefined || hash === '') return null
+  return {
+    commit: {
+      hash,
+      shortHash: shortHash ?? '',
+      subject: subject ?? '',
+      author: author ?? '',
+      dateIso: dateIso ?? '',
+    },
+    body: bodyParts.join(LOG_SEP).trimEnd(),
+  }
+}
+
+/** `--name-status` 状态码 → 变更状态映射。 */
+function nameStatusCode(code: string): GitChangeStatus {
+  switch (code) {
+    case 'A': return 'added'
+    case 'D': return 'deleted'
+    case 'R': return 'renamed'
+    case 'T': return 'typechange'
+    case 'U': return 'conflicted'
+    default: return 'modified'
+  }
+}
+
+/**
+ * 解析 `git show --format= --name-status -z` 输出：NUL 分隔，
+ * `X\0path\0`，rename/copy 为 `R100\0old\0new\0`（取新路径）。
+ * -z 原始输出不引号化，非 ASCII 路径天然免疫乱码（旧 --stat 八进制转义问题的根因消除）。
+ */
+export function parseNameStatusOutput(output: string): readonly { readonly path: string; readonly status: GitChangeStatus }[] {
+  const raw = output.split(NUL)
+  const segments = raw[raw.length - 1] === '' ? raw.slice(0, -1) : raw
+  const rows: { path: string; status: GitChangeStatus }[] = []
+  for (let i = 0; i < segments.length; i += 1) {
+    const entry = segments[i] ?? ''
+    if (entry === '') continue
+    const code = entry[0] ?? ' '
+    if (code === 'R' || code === 'C') {
+      // rename/copy：old 在 i+1、new 在 i+2，展示取新路径。
+      rows.push({ path: segments[i + 2] ?? '', status: nameStatusCode(code) })
+      i += 2
+    } else {
+      rows.push({ path: segments[i + 1] ?? '', status: nameStatusCode(code) })
+      i += 1
+    }
+  }
+  return rows
+}
+
 /**
  * Parse `git branch --show-current` output: the branch name, or null when
  * empty (detached HEAD).
@@ -174,3 +316,4 @@ export function parseBranchOutput(output: string): string | null {
   const trimmed = output.trim()
   return trimmed === '' ? null : trimmed
 }
+

package/src/host/queries.ts

@@ -0,0 +1,289 @@
+/**
+ * Framework-free read-only query runner (history / diff / show / branches).
+ *
+ * Same layering as `core.ts`/`actions.ts`: structural injection, testable
+ * against real temporary repositories without a cordis runtime. Every query
+ * resolves the workspace once, then runs one or two read-only git commands
+ * against the repository root.
+ */
+import { resolveWorkspace, runCommand, type GitStatusConfig, type SnapshotDeps } from './core.ts'
+import { parseBranchOutput, parseGraphLogOutput, parseNameStatusOutput, parseShowMeta } from './parser.ts'
+import { isSafePath, operationError } from './actions.ts'
+import type { GitBranch, GitQueryRequest, GitQueryResponse } from './types.ts'
+
+/** Machine-readable log format for show queries (no parents). */
+const LOG_FORMAT = '%H%x1f%h%x1f%s%x1f%an%x1f%aI'
+/** 带图的 log 格式（%P = 父提交，%D = ref 装饰）。 */
+const GRAPH_FORMAT = '%H%x1f%h%x1f%s%x1f%an%x1f%aI%x1f%P%x1f%D'
+
+/** History page size cap (and default). 千条级 + 无限滚动。 */
+const MAX_HISTORY_LIMIT = 1000
+
+/** A ref is acceptable when non-empty and free of whitespace. */
+function isValidRef(ref: string): boolean {
+  return ref !== '' && !/\s/.test(ref)
+}
+
+/**
+ * 执行一条只读查询。结果均为 JSON 纯数据且有界
+ * （history 分页；diff 文本受 runner 的 spill/截断约束）。
+ * `config` 当前未用：保留以与 runAction 共享 runner 签名契约
+ * （deps, config, request），后续查询限流等调优可直接启用。
+ */
+export async function runQuery(
+  deps: SnapshotDeps,
+  config: GitStatusConfig,
+  request: GitQueryRequest,
+): Promise<GitQueryResponse> {
+  void config
+  const workspace = await resolveWorkspace(deps, request.sessionId)
+  if (!workspace.ok) return { ok: false, error: operationError(workspace.error).error }
+  const root = workspace.root
+  const query = request.query
+
+  switch (query.kind) {
+    case 'history':
+      return historyQuery(deps, root, query)
+    case 'diff':
+      return diffQuery(deps, root, query.path, query.base)
+    case 'show':
+      return showQuery(deps, root, query.ref)
+    case 'branches':
+      return branchesQuery(deps, root)
+    case 'tags':
+      return tagsQuery(deps, root)
+    case 'authors':
+      return authorsQuery(deps, root)
+  }
+}
+
+async function historyQuery(
+  deps: SnapshotDeps,
+  root: string,
+  query: Extract<GitQueryRequest['query'], { kind: 'history' }>,
+): Promise<GitQueryResponse> {
+  const safeLimit = Math.min(Math.max(Math.floor(query.limit), 0), MAX_HISTORY_LIMIT)
+  const safeSkip = Math.max(Math.floor(query.skip), 0)
+  if (query.ref !== undefined && !isValidRef(query.ref)) {
+    return { ok: false, error: { code: 'invalid-name', message: `invalid ref: ${query.ref}` } }
+  }
+  const search = query.search?.trim() ?? ''
+  const hexLike = /^[0-9a-f]{7,40}$/i.test(search)
+  // 哈希精准检索：仅定位目标提交自身（--no-walk 不遍历祖先）→ 单条目，
+  // 不再列出该提交的全部祖先；文本搜索走 --grep（-i -E，跨引用匹配）。
+  const scope = hexLike ? [] : query.ref === undefined ? ['--all'] : [query.ref]
+  const noWalk = hexLike ? ['--no-walk', search] : []
+  const filters: string[] = []
+  if (search !== '' && !hexLike) filters.push('--regexp-ignore-case', '--extended-regexp', `--grep=${search}`)
+  const author = query.author?.trim() ?? ''
+  if (author !== '') filters.push(`--author=${author}`)
+  const since = query.since?.trim() ?? ''
+  if (since !== '') filters.push(`--since=${since}`)
+
+  const log = await runCommand(
+    deps.run,
+    // -n/--skip 前置：git 的 `-n N` 出现在 `--no-walk` 之后会重置 no-walk
+    // （hexLike 会错误列出全部祖先），前置则 `-n 1000 --no-walk x` 恒返回单条。
+    ['git', 'log', ...filters, `--skip=${String(safeSkip)}`, '-n', String(safeLimit), ...noWalk, ...scope, `--format=${GRAPH_FORMAT}`],
+    root,
+    'log',
+    deps.signal,
+  )
+  if ('failure' in log) return { ok: false, error: operationError(log.failure).error }
+  if (log.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (log.run.exitCode !== 0) {
+    // 未出生仓库无提交：git log 以 128 此信息退出——稳定空历史，非错误。
+    if (log.run.stderr.includes('does not have any commits')) {
+      return { ok: true, value: { kind: 'history', commits: [], total: 0 } }
+    }
+    // 哈希无解析（未命中）或前缀不唯一（ambiguous）：稳定空结果（让用户输入更长前缀）。
+    if (hexLike && /unknown revision|bad revision|ambiguous/i.test(log.run.stderr)) {
+      return { ok: true, value: { kind: 'history', commits: [], total: 0 } }
+    }
+    return gitError('log', log.run.stderr, log.run.stdout)
+  }
+
+  // 过滤范围内的提交总数（best-effort）。
+  let total = 0
+  const count = await runCommand(deps.run, ['git', 'rev-list', '--count', ...noWalk, ...scope, ...filters], root, 'rev-list', deps.signal)
+  if ('run' in count && count.run.exitCode === 0) {
+    const parsed = Number(count.run.stdout.trim())
+    if (Number.isFinite(parsed) && parsed >= 0) total = parsed
+  }
+
+  // 远程名用于 %D 装饰的远程分支分类；失败时降级为空列表（其余按本地分支处理）。
+  let remotes: readonly string[] = []
+  const remoteRun = await runCommand(deps.run, ['git', 'remote'], root, 'remote', deps.signal)
+  if ('run' in remoteRun && remoteRun.run.exitCode === 0) {
+    remotes = remoteRun.run.stdout.split('\n').map((s) => s.trim()).filter((s) => s !== '')
+  }
+
+  return { ok: true, value: { kind: 'history', commits: parseGraphLogOutput(log.run.stdout, remotes), total } }
+}
+
+/**
+ * 单文件差异（变更界面对照查看用）。
+ * staged = --cached；worktree = 工作区对索引；
+ * 未版本管理文件 worktree 差异为空 → 回退 --no-index 与 /dev/null 对比（退出码 1 视为有差异的成功）。
+ */
+async function diffQuery(
+  deps: SnapshotDeps,
+  root: string,
+  path: string,
+  base: 'worktree' | 'staged',
+): Promise<GitQueryResponse> {
+  if (!isSafePath(path, root)) return { ok: false, error: { code: 'invalid-path', message: `unsafe path: ${path}` } }
+  // 使用 -U999999 显示完整文档上下文（而非仅变更 hunk），支持文档浏览体验。
+  const argv = base === 'staged'
+    ? ['git', 'diff', '--cached', '-U999999', '--', path]
+    : ['git', 'diff', '-U999999', '--', path]
+  const run = await runCommand(deps.run, argv, root, 'diff', deps.signal)
+  if ('failure' in run) return { ok: false, error: operationError(run.failure).error }
+  if (run.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (run.run.exitCode !== 0) return gitError('diff', run.run.stderr, run.run.stdout)
+  if (run.run.stdout !== '' || base === 'staged') {
+    return { ok: true, value: { kind: 'diff', path, text: run.run.stdout } }
+  }
+  // 空差异：可能是未版本管理文件——与 /dev/null 对比生成全增差异。
+  const ni = await runCommand(deps.run, ['git', 'diff', '--no-index', '-U999999', '--', '/dev/null', path], root, 'diff --no-index', deps.signal)
+  if ('failure' in ni) return { ok: false, error: operationError(ni.failure).error }
+  if (ni.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (ni.run.exitCode !== 0 && ni.run.exitCode !== 1) return gitError('diff', ni.run.stderr, ni.run.stdout)
+  return { ok: true, value: { kind: 'diff', path, text: ni.run.stdout } }
+}
+
+async function showQuery(deps: SnapshotDeps, root: string, ref: string): Promise<GitQueryResponse> {
+  if (!isValidRef(ref)) return { ok: false, error: { code: 'invalid-name', message: `invalid ref: ${ref}` } }
+  // -s 仅输出格式块：%b 为排除首段落后的正文，独立调用避免解析歧义。
+  const meta = await runCommand(
+    deps.run,
+    ['git', 'show', '-s', `--format=${LOG_FORMAT}%x1f%b`, ref],
+    root,
+    'show',
+    deps.signal,
+  )
+  if ('failure' in meta) return { ok: false, error: operationError(meta.failure).error }
+  if (meta.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (meta.run.exitCode !== 0) return gitError('show', meta.run.stderr, meta.run.stdout)
+
+  const stat = await runCommand(
+    deps.run,
+    ['git', '-c', 'core.quotePath=false', 'show', '--format=', '--name-status', '-z', ref],
+    root,
+    'show --name-status',
+    deps.signal,
+  )
+  if ('failure' in stat) return { ok: false, error: operationError(stat.failure).error }
+  if (stat.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (stat.run.exitCode !== 0) return gitError('show', stat.run.stderr, stat.run.stdout)
+
+  const parsed = parseShowMeta(meta.run.stdout)
+  return {
+    ok: true,
+    value: {
+      kind: 'show',
+      ref,
+      commit: parsed?.commit ?? null,
+      body: parsed?.body ?? '',
+      stats: parseNameStatusOutput(stat.run.stdout),
+    },
+  }
+}
+
+/** 作者列表（工具栏用户选择用），去重排序截断 100。 */
+async function authorsQuery(deps: SnapshotDeps, root: string): Promise<GitQueryResponse> {
+  const run = await runCommand(deps.run, ['git', 'log', '--all', '-n', '1000', '--format=%an'], root, 'log authors', deps.signal)
+  if ('failure' in run) return { ok: false, error: operationError(run.failure).error }
+  if (run.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (run.run.exitCode !== 0) return { ok: true, value: { kind: 'authors', authors: [] } }
+  const authors = [...new Set(run.run.stdout.split('\n').map((s) => s.trim()).filter((s) => s !== ''))].sort().slice(0, 100)
+  return { ok: true, value: { kind: 'authors', authors } }
+}
+
+/** 标签列表（左栏过滤树用），复用 tab 分隔解析。 */
+async function tagsQuery(deps: SnapshotDeps, root: string): Promise<GitQueryResponse> {
+  const FORMAT = '--format=%(refname:short)%09%(objectname:short)'
+  const run = await runCommand(deps.run, ['git', 'tag', FORMAT], root, 'tag', deps.signal)
+  if ('failure' in run) return { ok: false, error: operationError(run.failure).error }
+  if (run.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (run.run.exitCode !== 0) return gitError('tag', run.run.stderr, run.run.stdout)
+  return { ok: true, value: { kind: 'tags', tags: parseBranchList(run.run.stdout) } }
+}
+
+async function branchesQuery(deps: SnapshotDeps, root: string): Promise<GitQueryResponse> {
+  // 本地分支格式：name\thash\tupstream\ttrack（track 如 [ahead 2, behind 1]）。
+  // 远程分支无上游 → upstream/track 为空。
+  const LOCAL_FORMAT = '--format=%(refname:short)%09%(objectname:short)%09%(upstream:short)%09%(upstream:track)'
+  const REMOTE_FORMAT = '--format=%(refname:short)%09%(objectname:short)'
+  const local = await runCommand(deps.run, ['git', 'branch', LOCAL_FORMAT], root, 'branch', deps.signal)
+  if ('failure' in local) return { ok: false, error: operationError(local.failure).error }
+  if (local.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (local.run.exitCode !== 0) return gitError('branch', local.run.stderr, local.run.stdout)
+
+  const remote = await runCommand(deps.run, ['git', 'branch', '-r', REMOTE_FORMAT], root, 'branch -r', deps.signal)
+  if ('failure' in remote) return { ok: false, error: operationError(remote.failure).error }
+  if (remote.run.timedOut) return { ok: false, error: { code: 'timeout' } }
+  if (remote.run.exitCode !== 0) return gitError('branch -r', remote.run.stderr, remote.run.stdout)
+
+  const current = await runCommand(deps.run, ['git', 'branch', '--show-current'], root, 'branch', deps.signal)
+  const currentName = 'run' in current && current.run.exitCode === 0 ? parseBranchOutput(current.run.stdout) : null
+
+  // 默认分支：origin/HEAD 符号引用（如 origin/main）；失败降级 null。
+  let defaultBranch: string | null = null
+  const def = await runCommand(deps.run, ['git', 'symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'], root, 'symbolic-ref', deps.signal)
+  if ('run' in def && def.run.exitCode === 0) {
+    const value = def.run.stdout.trim()
+    const slash = value.indexOf('/')
+    defaultBranch = value === '' ? null : slash === -1 ? value : value.slice(slash + 1)
+  }
+
+  return {
+    ok: true,
+    value: {
+      kind: 'branches',
+      current: currentName,
+      defaultBranch,
+      local: parseBranchList(local.run.stdout),
+      remote: parseBranchList(remote.run.stdout).filter((branch) => !branch.name.endsWith('/HEAD')),
+    },
+  }
+}
+
+/**
+ * 解析 `%(refname:short)%09%(objectname:short)[%09%(upstream:short)%09%(upstream:track)]` 行。
+ * 本地分支含 4 字段（upstream + track），远程分支仅 2 字段（无上游）。
+ * track 格式：`[ahead N]`、`[behind N]`、`[ahead N, behind N]` 或空（无上游/已同步）。
+ */
+function parseBranchList(output: string): readonly GitBranch[] {
+  const branches: GitBranch[] = []
+  for (const line of output.split('\n')) {
+    if (line === '') continue
+    const parts = line.split('\t')
+    const name = parts[0]
+    const hash = parts[1]
+    if (name === undefined || name === '') continue
+    const track = parts[3] ?? ''
+    const aheadMatch = /ahead (\d+)/.exec(track)
+    const behindMatch = /behind (\d+)/.exec(track)
+    const ahead = aheadMatch ? Number(aheadMatch[1]) : 0
+    const behind = behindMatch ? Number(behindMatch[1]) : 0
+    branches.push({
+      name,
+      shortHash: hash === undefined || hash === '' ? null : hash,
+      ...(ahead > 0 ? { ahead } : {}),
+      ...(behind > 0 ? { behind } : {}),
+    })
+  }
+  return branches
+}
+
+function gitError(label: string, stderr: string, stdout: string): GitQueryResponse {
+  const message = stderr.trim() || stdout.trim()
+  return {
+    ok: false,
+    error: {
+      code: 'git-error',
+      message: message !== '' ? message : `git ${label} failed`,
+    },
+  }
+}