@thincoder/core 0.9.1

package/tools/git-ext.mjs

@@ -0,0 +1,173 @@
+/**
+ * git-ext.mjs — git 工具 F7 扩展 action（clone/init/rebase/remote/clean/switch/apply/worktree/
+ * archive/blame/mv）+ 共享 git 辅助函数（validateRef/runGitStrict/filterLines/snapshotBefore，
+ * 供 git.mjs 核心 action 复用——500 行硬限拆分）。CLI 与 VS Code 两端同构（镜像，修改须两端同批）。
+ */
+import { runGit, truncate } from "./shared.mjs"
+import { execFileSync } from "node:child_process"
+
+/** Keep only output lines matching a regex (git filter, case-insensitive). */
+export function filterLines(output, filter) {
+  if (!filter) return output
+  try {
+    const re = new RegExp(filter, "i")
+    const lines = output.split("\n").filter((l) => re.test(l))
+    return lines.length ? lines.join("\n") : `(no lines matched filter "${filter}")`
+  } catch (e) {
+    return `Error: filter regex invalid: ${e.message}`
+  }
+}
+
+/** Run git and report failure (stderr + exit code) instead of swallowing it.
+ *  Used by write ops (commit/push/rm) where a silent "" would masquerade as success. */
+export function runGitStrict(cwd, cmdArgs, config = []) {
+  try {
+    const out = execFileSync("git", [...config, ...cmdArgs], { cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }).trim().replace(/\r/g, "")
+    return { ok: true, out }
+  } catch (e) {
+    return { ok: false, out: String(e.stdout || "").trim(), err: String(e.stderr || e.message || "").trim() }
+  }
+}
+
+/** Validate a git ref / branch / tag / remote name (no option injection, no whitespace). */
+export function validateRef(ref, what = "git ref") {
+  if (!/^[A-Za-z0-9._/~^@][A-Za-z0-9._/~^@{}-]*$/.test(ref)) throw new Error(`Invalid ${what}: ${ref}`)
+  return ref
+}
+
+/** Normalize args.config into `-c key=value` pairs (git -c overrides, e.g. a proxy).
+ *  Values are execFileSync array args (no shell injection) — still reject newlines/empty. */
+export function gitConfigArgs(config) {
+  if (config == null) return []
+  if (!Array.isArray(config)) throw new Error("config must be an array of \"key=value\" strings")
+  const out = []
+  for (const c of config) {
+    if (typeof c !== "string" || !c.trim() || c.includes("\n")) throw new Error(`invalid git -c config entry: ${String(c).slice(0, 60)}`)
+    out.push("-c", c)
+  }
+  return out
+}
+
+/** Snapshot the working tree before a destructive op (reset --hard / checkout file / restore /
+ *  stash pop / branch|tag delete / clean / rebase). Best-effort — a snapshot failure must not
+ *  block the op (the approval/permission layer is the real gate). Returns a note line or "". */
+export async function snapshotBefore(ctx, label) {
+  try {
+    const { createCheckpoint, isGitRepo } = await import("../git/checkpoint.mjs")
+    if (!isGitRepo(ctx.cwd)) return ""
+    const cp = await createCheckpoint(ctx.cwd)
+    return `[snapshot ${cp.id} created before ${label}]\n`
+  } catch {
+    return ""
+  }
+}
+
+/** F7 扩展 action 主入口（git 工具 switch 的 fall-through 组委托到这里）。 */
+export async function executeExtAction(args, ctx) {
+  switch (args.action) {
+    case "clone": {
+      // Clone a repo into a NEW directory — non-destructive (never touches existing work).
+      if (!args.remote) return "Error: clone requires remote (URL or local path)"
+      const cmdArgs = ["clone", args.remote]
+      if (args.path) cmdArgs.push(args.path)
+      const r = runGitStrict(ctx.cwd, cmdArgs, gitConfigArgs(args.config))
+      return r.ok ? truncate(r.out || `Cloned ${args.remote}`) : truncate(`git clone failed: ${r.err || r.out}`)
+    }
+    case "init": {
+      const r = runGitStrict(ctx.cwd, ["init"])
+      return r.ok ? truncate(r.out || "Initialized empty git repository") : truncate(`git init failed: ${r.err || r.out}`)
+    }
+    case "rebase": {
+      // Belt-and-braces snapshot: bare rebase refuses uncommitted changes (unless
+      // --autostash), but --autostash restore-failure / interrupted-rebase scenarios
+      // can leave the working tree damaged — the snapshot makes that recoverable.
+      // The snapshot line is included on FAILURE too: a rejected rebase (unstaged
+      // changes) is exactly when the model must know its work is protected (F1 loop).
+      const snap = await snapshotBefore(ctx, "rebase")
+      const sub = args.rebaseAction ?? "start"
+      const cmdArgs = ["rebase"]
+      if (sub === "abort") cmdArgs.push("--abort")
+      else if (sub === "continue") cmdArgs.push("--continue")
+      else { if (!args.ref) return "Error: rebase requires ref (branch/commit to rebase onto)"; cmdArgs.push(validateRef(args.ref)) }
+      const r = runGitStrict(ctx.cwd, cmdArgs)
+      return r.ok ? truncate(snap + (r.out || `Rebase ${sub} complete`)) : truncate(snap + `git rebase failed: ${r.err || r.out} — use rebaseAction=abort to abort`)
+    }
+    case "remote": {
+      const sub = args.remoteAction ?? "list"
+      if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["remote", "-v"]) || "(no remotes)", args.filter))
+      if (!args.remote) return `Error: remote ${sub} requires remote (name)`
+      validateRef(args.remote, "remote name")
+      if (sub === "add" || sub === "set-url") {
+        if (!args.remoteUrl) return `Error: remote ${sub} requires remoteUrl`
+        const r = runGitStrict(ctx.cwd, ["remote", sub === "add" ? "add" : "set-url", args.remote, args.remoteUrl])
+        return r.ok ? `Remote ${args.remote} ${sub === "add" ? "added" : "URL set"}` : truncate(`git remote ${sub} failed: ${r.err || r.out}`)
+      }
+      if (sub === "remove") {
+        const r = runGitStrict(ctx.cwd, ["remote", "remove", args.remote])
+        return r.ok ? `Remote ${args.remote} removed` : truncate(`git remote remove failed: ${r.err || r.out}`)
+      }
+      return "Error: remote requires remoteAction — use: list | add | remove | set-url"
+    }
+    case "clean": {
+      // Destructive: removes untracked files/dirs — snapshot first (guard parity).
+      // dryRun (-n) is a preview: no deletion, no snapshot.
+      const snap = args.dryRun ? "" : await snapshotBefore(ctx, "clean")
+      const cmdArgs = ["clean", args.dryRun ? "-n" : "-f", "-d"]
+      const r = runGitStrict(ctx.cwd, cmdArgs)
+      return r.ok ? truncate(snap + (r.out || (args.dryRun ? "Nothing to clean (dry run)" : "Clean complete"))) : truncate(snap + `git clean failed: ${r.err || r.out}`)
+    }
+    case "switch": {
+      if (!args.name) return "Error: switch requires name (branch)"
+      validateRef(args.name, "branch")
+      const cmdArgs = ["switch"]
+      if (args.create) cmdArgs.push("-c")
+      cmdArgs.push(args.name)
+      const r = runGitStrict(ctx.cwd, cmdArgs)
+      return r.ok ? truncate(r.out || `Switched to branch ${args.name}`) : truncate(`git switch failed: ${r.err || r.out}`)
+    }
+    case "apply": {
+      // Apply a patch — non-destructive (fails cleanly on conflict, applies nothing).
+      if (!args.path) return "Error: apply requires path (patch file)"
+      const r = runGitStrict(ctx.cwd, ["apply", "--", args.path])
+      return r.ok ? truncate(r.out || `Applied ${args.path}`) : truncate(`git apply failed: ${r.err || r.out}`)
+    }
+    case "worktree": {
+      const sub = args.worktreeAction ?? "list"
+      if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["worktree", "list"]) || "(no worktrees)", args.filter))
+      if (sub === "add") {
+        if (!args.path) return "Error: worktree add requires path (new worktree directory)"
+        const cmdArgs = ["worktree", "add", args.path]
+        if (args.ref) cmdArgs.push(validateRef(args.ref))
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(r.out || `Worktree added at ${args.path}`) : truncate(`git worktree add failed: ${r.err || r.out}`)
+      }
+      if (sub === "remove") {
+        if (!args.path) return "Error: worktree remove requires path"
+        const r = runGitStrict(ctx.cwd, ["worktree", "remove", args.path])
+        return r.ok ? truncate(r.out || `Worktree removed: ${args.path}`) : truncate(`git worktree remove failed: ${r.err || r.out}`)
+      }
+      return "Error: worktree requires worktreeAction — use: list | add | remove"
+    }
+    case "archive": {
+      // Write a tar of a commit/branch — non-destructive (output file only).
+      if (!args.path) return "Error: archive requires path (output file)"
+      const cmdArgs = ["archive", "--format=tar", "-o", args.path]
+      if (args.ref) cmdArgs.push(validateRef(args.ref))
+      else cmdArgs.push("HEAD")
+      const r = runGitStrict(ctx.cwd, cmdArgs)
+      return r.ok ? truncate(r.out || `Archived ${args.ref ?? "HEAD"} to ${args.path}`) : truncate(`git archive failed: ${r.err || r.out}`)
+    }
+    case "blame": {
+      if (!args.path) return "Error: blame requires path (file)"
+      const out = runGit(ctx.cwd, ["blame", "--", args.path])
+      return truncate(out || `(no blame output for ${args.path})`)
+    }
+    case "mv": {
+      if (!args.path || !args.dest) return "Error: mv requires path (source) and dest (destination)"
+      const r = runGitStrict(ctx.cwd, ["mv", "--", args.path, args.dest])
+      return r.ok ? truncate(r.out || `Moved ${args.path} → ${args.dest}`) : truncate(`git mv failed: ${r.err || r.out}`)
+    }
+    default:
+      throw new Error(`Unknown ext action: ${args.action}`)
+  }
+}

package/tools/git.mjs

@@ -0,0 +1,415 @@
+import {
+  DESC,
+  truncate,
+  runGit,
+  gitFailureMessage
+} from "./shared.mjs";
+import { execFileSync } from "node:child_process";
+import { resolve } from "node:path";
+import { filterLines, runGitStrict, validateRef, gitConfigArgs, snapshotBefore, executeExtAction } from "./git-ext.mjs";
+import { executeCheckpointAction } from "./git-checkpoint.mjs";
+import { discoverRepos, MANIFEST_REL } from "../manifest.mjs";
+
+
+/** Run git PRESERVING per-line leading whitespace. runGit trims the WHOLE output, which
+ *  strips a porcelain line's leading " " (the unstaged marker) and misclassifies an
+ *  unstaged-only first line as staged. status uses this so the staged/unstaged column survives.
+ *  #55 fail-closed：失败不再吞成 ""（曾把非仓 / 任意失败渲染成 `(clean — no changes)`）——
+ *  溢出保留部分输出；其余 ⇒ throw（消息契约 = `shared.mjs` `gitFailureMessage`）。 */
+function runGitRaw(cwd, cmdArgs, config = []) {
+  try {
+    return execFileSync("git", [...config, ...cmdArgs], { cwd, encoding: "utf8", maxBuffer: 10 * 1024 * 1024, stdio: ["ignore", "pipe", "pipe"] }).replace(/\r/g, "").replace(/\n$/, "")
+  } catch (e) {
+    if (e.code === "ERR_CHILD_PROCESS_STDIO_MAXBUFFER" && e.stdout) return String(e.stdout).replace(/\r/g, "")
+    throw new Error(gitFailureMessage(e, cmdArgs, cwd))
+  }
+}
+
+
+
+
+/** Resolve workdir relative to cwd — no boundary assertion
+ *  (§10.1 2026-09-02: workspace confinement removed; git itself is not
+ *  directory-limited — same boundary as bash). */
+function resolveBaseDir(cwd, workdir) {
+  if (!workdir || typeof workdir !== "string") return cwd
+  return resolve(cwd, workdir)
+}
+
+// ─── 仓发现（§6.13 · #62——单源 = `manifest.mjs` `discoverRepos`，禁第二份实现）───────────────
+/** 动作面例外：`init` / `clone` 以 **cwd 为落点**——不做发现（`init` 在无仓处天然合法；`clone` 的
+ *  落点 = cwd 相对路径——判据同 `init`），否则「在此处建仓 / 克隆」被静默搬进别仓；
+ *  二者仍可经显式 `workdir` 指落点。 */
+const NO_REPO_DISCOVERY = new Set(["init", "clone"])
+
+/** 歧义（多态）消息：候选全列（绝对路径、按名排序）+ 指引显式 `workdir`——不猜（§6.13 解析序行 5）。 */
+function ambiguousRepoMessage(candidates, cwd) {
+  return `Ambiguous git repo at ${cwd}: ${candidates.length} subdirectories carry .git and ${MANIFEST_REL} — ` +
+    `pass workdir to run git in the intended one (no silent pick):\n` + candidates.map((c) => `- ${c}`).join("\n")
+}
+
+// ─── 审批门注入缝（#59——「只读判定 / 审批门按端注入」，形态参 §2.13.5 注入缝）────────
+/**
+ * 审批门注入位（**缺省不覆盖** = 无审批面：全部动作照常执行——CLI 语义，零行为变；端装配层
+ * 可覆盖为本端审批 / 只读判定。核内零端名分支（契约 5——本档只认 `gate` 函数名）。
+ * 契约：`gate(args, ctx) → string | null | Promise<同>`——非空字符串 = 拒执行（该串原样作为
+ * 工具结果返回）；null / undefined / 其他值 = 放行。每个 execute 恰问一次（workdir 归一后）。
+ */
+let injectedApproval = null
+export function configureGitApproval(impl) {
+  injectedApproval = impl && typeof impl.gate === "function" ? impl.gate : null
+}
+/** 撤销注入（测试与端装配生命周期用——缺省态 = 无审批门）。 */
+export function resetGitApproval() { injectedApproval = null }
+
+
+
+export const gitTool = {
+  name: "git",
+  description: DESC("git"),
+  parameters: {
+    type: "object",
+    properties: {
+      action: { type: "string", enum: ["diff", "status", "log", "show", "checkpoint", "add", "rm", "commit", "push", "tag", "branch", "checkout", "restore", "stash", "fetch", "pull", "reset", "revert", "merge", "cherry-pick", "ls-remote", "clone", "init", "rebase", "remote", "clean", "switch", "apply", "worktree", "archive", "blame", "mv"], description: "diff / status / log / show / checkpoint / add / rm / commit / push / tag / branch / checkout / restore / stash / fetch / pull / reset / revert / merge / cherry-pick / ls-remote / clone / init / rebase / remote / clean / switch / apply / worktree / archive / blame / mv — clean/rebase 操作前自动快照，checkpointAction=rewind 恢复" },
+      // diff/log params
+      staged: { type: "boolean", description: "(diff) Show staged changes instead of working tree" },
+      path: { type: "string", description: "(diff/log/add/commit/checkout/restore/checkpoint:cat/versions/rewind/rm/apply/archive/blame/mv/worktree) File or directory to scope to / stage / restore（checkout/restore 操作前自动快照，checkpointAction=rewind 恢复）— add/rm/commit: space-separated for multiple（git add a b c——2026-09-05 发版痛点；含空格的文件名会被按多路径拆分——请用 bash git 处理）" },
+      ref: { type: "string", description: "(diff/show/checkout/reset/revert/merge/cherry-pick/tag:create/branch:create/rebase/worktree:add/archive) Commit/branch/ref; (push/pull/fetch) the branch or tag (space-separated for multiple)" },
+      count: { type: "number", description: "(log) Number of commits (default 10)" },
+      oneline: { type: "boolean", description: "(log) One-line-per-commit format" },
+      message: { type: "string", description: "(commit) Commit message — required for commit; (stash:push) stash message" },
+      filter: { type: "string", description: "Optional: keep only status/diff/log output lines matching this regex (case-insensitive)" },
+      // write-op params
+      name: { type: "string", description: "(branch/tag) The branch or tag name (create/delete/switch)" },
+      remote: { type: "string", description: "(push/fetch/pull) Remote name (e.g. origin). Default: current upstream" },
+      workdir: { type: "string", description: "Run git in this subdirectory (monorepo / multi-repo). Path relative to cwd — no directory restriction. Default: the discovered project repo root（缺省 = 发现的项目仓根；显式 workdir 优先）" },
+      config: { type: "array", items: { type: "string" }, description: "(network actions: push/fetch/pull/ls-remote) git -c overrides, e.g. [\"http.proxy=http://10.2.2.112:3128\"] for blocked remotes" },
+      tags: { type: "boolean", description: "(push) Also push all tags (--tags)" },
+      mode: { type: "string", enum: ["soft", "mixed", "hard"], description: "(reset) reset mode — hard snapshots the tree first + needs confirmation（操作前自动快照，checkpointAction=rewind 恢复）" },
+      tagAction: { type: "string", enum: ["list", "create", "delete"], description: "(tag) list tags / create one / delete one（delete 操作前自动快照，checkpointAction=rewind 恢复）" },
+      branchAction: { type: "string", enum: ["list", "create", "delete", "switch"], description: "(branch) list branches / create / delete / switch to one（delete 操作前自动快照，checkpointAction=rewind 恢复）" },
+      stashAction: { type: "string", enum: ["push", "pop", "list"], description: "(stash) push (stash now) / pop (apply+drop) / list（pop 操作前自动快照，checkpointAction=rewind 恢复）" },
+      // checkpoint params
+      checkpointAction: { type: "string", enum: ["list", "create", "rewind", "cat", "versions"], description: "(checkpoint) list snapshots / create one / restore by id / read file from snapshot / list a file's historical versions（rewind 可恢复操作前状态，恢复前自动快照可逆）" },
+      checkpointId: { type: "string", description: "(checkpoint) Snapshot id — required for rewind and cat; optional for list (shows file tree)" },
+      // F7 new-action params
+      remoteAction: { type: "string", enum: ["list", "add", "remove", "set-url"], description: "(remote) list remotes / add / remove / set-url" },
+      remoteUrl: { type: "string", description: "(remote add/set-url) Remote URL (https/git/ssh or local path)" },
+      rebaseAction: { type: "string", enum: ["start", "abort", "continue"], description: "(rebase) start (ref required) / abort / continue（操作前自动快照，checkpointAction=rewind 恢复）" },
+      dryRun: { type: "boolean", description: "(clean) preview only (-n) — no deletion, no snapshot; real clean 操作前自动快照，checkpointAction=rewind 恢复" },
+      create: { type: "boolean", description: "(switch) create the branch then switch (-c)" },
+      dest: { type: "string", description: "(mv) destination path (file or directory)" },
+      worktreeAction: { type: "string", enum: ["list", "add", "remove"], description: "(worktree) list / add (path, ref) / remove (path)" },
+    },
+    required: ["action"],
+  },
+  readonly: false,
+  async execute(args, ctx) {
+    // workdir: run git in a subdirectory (monorepo / multi-repo). Shadow ctx.cwd so
+    // every action + snapshotBefore + checkpoint resolves against the workdir.
+    if (args.workdir) ctx = { ...ctx, cwd: resolveBaseDir(ctx.cwd, args.workdir) }
+    // 仓发现（§6.13 · #62）：缺省路径（无 workdir）⇒ 单源 = `discoverRepos`——工作区根（非仓）⇒
+    // 唯一带 manifest 子仓：重定向 `ctx.cwd` + 结果首行注记；零 ⇒ 原值落 §6.12 fail-closed（零
+    // 行为变）；多 ⇒ throw（列候选 + 指 workdir，不猜）。判据 = workdir 真值在场（与上行同源——
+    // 空串与缺省同判）；`init` / `clone` 例外不做发现。self / none 态 ctx 对象引用透传（不 clone）。
+    let repoNote = ""
+    if (!args.workdir && !NO_REPO_DISCOVERY.has(args.action)) {
+      const discovered = discoverRepos(ctx.cwd)
+      if (discovered.kind === "ambiguous") throw new Error(ambiguousRepoMessage(discovered.candidates, ctx.cwd))
+      if (discovered.kind === "unique") {
+        ctx = { ...ctx, cwd: discovered.root }
+        repoNote = `(repo: ${discovered.root})`
+      }
+    }
+    // #59：审批门（端注入面）——缺省无门（CLI 语义）；非空字符串返回 ⇒ 拒执行（拒串原样、不加注记）。
+    if (injectedApproval) {
+      const refusal = await injectedApproval(args, ctx)
+      if (typeof refusal === "string" && refusal.length > 0) return refusal
+    }
+    const out = await gitActionCore.dispatch(args, ctx)
+    return repoNote ? `${repoNote}\n${out}` : out
+  },
+}
+
+/** git 动作执行体（本批自 `execute()` 抽出——§6.13 落位表行 2：两函数均 <300 行；switch 体原样搬、
+ *  **不用 `this`**（端装配面 `{...coreGitTool}` 展开装饰，`this` 绑定不可依赖））。ctx 已经过 workdir
+ *  归一与仓发现（`execute()` 头部）——本函数只做动作派发，零发现语义。 */
+const gitActionCore = {
+  async dispatch(args, ctx) {
+    // git -c overrides (proxy etc.) — only network actions need them; passing to every
+    // action would be harmless but noisy. cfgArgs stays [] for local ops.
+    const cfgArgs = gitConfigArgs(args.config)
+    switch (args.action) {
+      case "diff": {
+        const ref = args.ref ?? "HEAD"
+        if (!/^[A-Za-z0-9._/~^@][A-Za-z0-9._/~^@{}-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
+        const flags = args.staged ? ["--staged"] : []
+        const paths = args.path ? [args.path] : []
+        const out = runGit(ctx.cwd, ["diff", ...flags, ref, "--", ...paths])
+        return truncate(filterLines(out || "(no changes)", args.filter))
+      }
+      case "status": {
+        // Preserve per-line leading whitespace — porcelain " M"/"M " staged/unstaged markers are
+        // significant (runGit trims the whole output's leading space, corrupting an unstaged-first-line).
+        const porcelain = runGitRaw(ctx.cwd, ["status", "--porcelain"])
+        if (!porcelain) return "(clean — no changes)"
+
+        const staged = []
+        const unstaged = []
+        const untracked = []
+        const conflicts = []
+        for (const line of porcelain.split("\n")) {
+          if (!line) continue
+          const clean = line.replace(/\r/g, "")
+          const m = clean.match(/^(..?)\s+(.+)$/)
+          if (!m) continue
+          const [, status, rawFile] = m
+          const file = status.includes("R") && rawFile.includes(" -> ") ? rawFile.replace(" -> ", " → ") : rawFile
+          const idx = status[0] ?? " "
+          const wt = status[1] ?? " "
+          if (idx === "U" || wt === "U" || (idx === "A" && wt === "A")) {
+            conflicts.push(file)
+          } else if (idx === "?" && wt === "?") {
+            untracked.push(file)
+          } else {
+            if (idx !== " " && idx !== "?") staged.push(idx + " " + file)
+            if (wt !== " " && wt !== "?") unstaged.push(wt + " " + file)
+          }
+        }
+        const parts = []
+        if (staged.length) parts.push("Staged (" + staged.length + "):\n" + staged.join("\n"))
+        if (unstaged.length) parts.push("Unstaged (" + unstaged.length + "):\n" + unstaged.join("\n"))
+        if (untracked.length) parts.push("Untracked (" + untracked.length + "):\n" + untracked.join("\n"))
+        if (conflicts.length) parts.push("Conflicts (" + conflicts.length + "):\n" + conflicts.join("\n"))
+        return truncate(filterLines(parts.join("\n\n"), args.filter))
+      }
+      case "log": {
+        const parsed = Number.parseInt(args.count, 10)
+        const n = Number.isFinite(parsed) && parsed > 0 ? Math.min(parsed, 200) : 10
+        const isOneline = args.oneline
+        const cmdArgs = isOneline
+          ? ["log", "-" + n, "--oneline"]
+          : ["log", "-" + n, "--format=%h %ad %an %s", "--date=short"]
+        if (args.path) cmdArgs.push("--", args.path)
+        const out = runGit(ctx.cwd, cmdArgs)
+        return truncate(filterLines(out || "(no commits)", args.filter))
+      }
+      case "show": {
+        const ref = args.ref ?? "HEAD"
+        if (!/^[A-Za-z0-9._/~^@][A-Za-z0-9._/~^@{}-]*$/.test(ref)) throw new Error(`Invalid git ref: ${ref}`)
+        const out = runGit(ctx.cwd, ["show", "--stat", ref])
+        return truncate(out || "(no such commit)")
+      }
+      case "rm": {
+        if (!args.path) return "Error: rm requires path (the file/directory to untrack, relative to repo root)"
+        const paths = args.path.split(/\s+/).filter(Boolean)
+        const r = runGitStrict(ctx.cwd, ["rm", "--cached", "-r", "--", ...paths])
+        return r.ok ? truncate(r.out || `Untracked ${paths.join(" ")} (kept on disk)`) : truncate(`git rm failed: ${r.err || r.out}`)
+      }
+      case "commit": {
+        if (!args.message) return "Error: commit requires message"
+        // F-3 (QUICKFIX-BATCH-2)：path 给定（含空串——空/空白 trim 后空一律明确错误，绝不
+        // 回落 add -A）→ git commit --only <paths>——从工作树取列文件提交（忽略索引他批——
+        // 原子——不再先 add）。空格分隔唯一形态（含空格文件名不支持）。无 path（缺省）→ add
+        // -A 全量（单代理语义保留）。
+        const parts = []
+        let commit
+        if (args.path !== undefined && args.path !== null) {
+          const trimmed = args.path.trim()
+          if (!trimmed) return "Error: commit path is empty/whitespace — give at least one file path (space-separated)"
+          commit = runGitStrict(ctx.cwd, ["commit", "--only", "-m", args.message, "--", ...trimmed.split(/\s+/)])
+        } else {
+          const add = runGitStrict(ctx.cwd, ["add", "-A"])
+          if (!add.ok) return truncate(`git add failed: ${add.err || add.out || "(no output)"}`)
+          if (add.out) parts.push(add.out)
+          commit = runGitStrict(ctx.cwd, ["commit", "-m", args.message])
+        }
+        if (commit.ok) {
+          if (commit.out) parts.push(commit.out)
+          // F6: commit = new safety baseline — clear this project's checkpoints
+          // (best-effort per NF7: a failed cleanup never blocks the commit result).
+          try {
+            const { deleteCheckpointsForCwd } = await import("../git/checkpoint.mjs")
+            await deleteCheckpointsForCwd(ctx.cwd)
+            parts.push("(checkpoints cleared — commit is a new safety baseline)")
+          } catch (e) {
+            parts.push(`(checkpoint cleanup skipped: ${e.message})`)
+          }
+        }
+        else parts.push(`git commit failed: ${commit.err || "(no output)"}`)
+        return truncate(parts.join("\n") || "(commit produced no output)")
+      }
+      case "push": {
+        const cmdArgs = ["push"]
+        if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
+        if (args.ref) for (const r of args.ref.split(/\s+/).filter(Boolean)) cmdArgs.push(validateRef(r, "ref"))
+        if (args.tags) cmdArgs.push("--tags")
+        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
+        return r.ok ? truncate(r.out || "(push complete — no output)") : truncate(`git push failed: ${r.err || r.out || "(no output)"}`)
+      }
+      case "ls-remote": {
+        // Lightweight remote-ref check (which refs a remote has) — network action,
+        // read-only, no snapshot. Config plumbing for blocked/gated remotes.
+        const cmdArgs = ["ls-remote"]
+        if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
+        if (args.ref) for (const r of args.ref.split(/\s+/).filter(Boolean)) cmdArgs.push(validateRef(r, "ref"))
+        const out = runGit(ctx.cwd, cmdArgs, cfgArgs)
+        if (!out) return "(no refs / remote unreachable)"
+        return truncate(filterLines(out, args.filter))
+      }
+      case "add": {
+        // Granular staging: stage `path` when given, else all changes (add -A).
+        // 多路径：空格分隔（ref 先例 L175——2026-09-05 发版痛点——git add 单路径被迫 N 次调用）
+        const paths = args.path ? args.path.split(/\s+/).filter(Boolean) : null
+        const cmdArgs = paths?.length ? ["add", "--", ...paths] : ["add", "-A"]
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(r.out || `Staged ${paths?.join(" ") || "all changes"}`) : truncate(`git add failed: ${r.err || r.out}`)
+      }
+      case "tag": {
+        const sub = args.tagAction
+        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["tag", "-l"]) || "(no tags)", args.filter))
+        if (sub === "create") {
+          if (!args.name) return "Error: tag create requires name"
+          validateRef(args.name, "tag")
+          const cmdArgs = ["tag", args.name]
+          if (args.ref) cmdArgs.push(validateRef(args.ref))
+          const r = runGitStrict(ctx.cwd, cmdArgs)
+          return r.ok ? `Tag ${args.name} created` : truncate(`git tag failed: ${r.err || r.out}`)
+        }
+        if (sub === "delete") {
+          if (!args.name) return "Error: tag delete requires name"
+          validateRef(args.name, "tag")
+          const snap = await snapshotBefore(ctx, `tag delete ${args.name}`)
+          const r = runGitStrict(ctx.cwd, ["tag", "-d", args.name])
+          return r.ok ? truncate(snap + `Tag ${args.name} deleted`) : truncate(`git tag -d failed: ${r.err || r.out}`)
+        }
+        return "Error: tag requires tagAction — use: list | create | delete"
+      }
+      case "branch": {
+        const sub = args.branchAction
+        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["branch", "--all", "-vv"]) || "(no branches)", args.filter))
+        if (sub === "create") {
+          if (!args.name) return "Error: branch create requires name"
+          validateRef(args.name, "branch")
+          const cmdArgs = ["branch", args.name]
+          if (args.ref) cmdArgs.push(validateRef(args.ref))
+          const r = runGitStrict(ctx.cwd, cmdArgs)
+          return r.ok ? `Branch ${args.name} created` : truncate(`git branch failed: ${r.err || r.out}`)
+        }
+        if (sub === "switch") {
+          if (!args.name) return "Error: branch switch requires name"
+          validateRef(args.name, "branch")
+          const r = runGitStrict(ctx.cwd, ["checkout", args.name])
+          return r.ok ? `Switched to branch ${args.name}` : truncate(`git checkout ${args.name} failed: ${r.err || r.out}`)
+        }
+        if (sub === "delete") {
+          if (!args.name) return "Error: branch delete requires name"
+          validateRef(args.name, "branch")
+          const snap = await snapshotBefore(ctx, `branch delete ${args.name}`)
+          const r = runGitStrict(ctx.cwd, ["branch", "-d", args.name])
+          return r.ok ? truncate(snap + `Branch ${args.name} deleted`) : truncate(`git branch -d failed: ${r.err || r.out}`)
+        }
+        return "Error: branch requires branchAction — use: list | create | delete | switch"
+      }
+      case "checkout": {
+        if (args.path) {
+          // Restore file from index (discards working-tree changes to it) — destructive: snapshot first.
+          const snap = await snapshotBefore(ctx, `checkout -- ${args.path}`)
+          const r = runGitStrict(ctx.cwd, ["checkout", "--", args.path])
+          return r.ok ? truncate(snap + `Restored ${args.path}`) : truncate(`git checkout -- ${args.path} failed: ${r.err || r.out}`)
+        }
+        if (args.ref) {
+          validateRef(args.ref, "ref")
+          const r = runGitStrict(ctx.cwd, ["checkout", args.ref])
+          return r.ok ? truncate(r.out || `Checked out ${args.ref}`) : truncate(`git checkout ${args.ref} failed: ${r.err || r.out}`)
+        }
+        return "Error: checkout requires ref (branch/commit) or path (file to restore)"
+      }
+      case "restore": {
+        if (!args.path) return "Error: restore requires path"
+        const snap = await snapshotBefore(ctx, `restore ${args.path}`)
+        const cmdArgs = ["restore"]
+        if (args.staged) cmdArgs.push("--staged")
+        cmdArgs.push("--", args.path)
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(snap + `Restored ${args.path}`) : truncate(`git restore failed: ${r.err || r.out}`)
+      }
+      case "stash": {
+        const sub = args.stashAction
+        if (sub === "list") return truncate(filterLines(runGit(ctx.cwd, ["stash", "list"]) || "(no stashes)", args.filter))
+        if (sub === "push") {
+          const cmdArgs = ["stash", "push"]
+          if (args.message) cmdArgs.push("-m", args.message)
+          const r = runGitStrict(ctx.cwd, cmdArgs)
+          return r.ok ? truncate(r.out || "Stashed") : truncate(`git stash push failed: ${r.err || r.out}`)
+        }
+        if (sub === "pop") {
+          const snap = await snapshotBefore(ctx, "stash pop")
+          const r = runGitStrict(ctx.cwd, ["stash", "pop"])
+          return r.ok ? truncate(snap + (r.out || "Popped")) : truncate(`git stash pop failed: ${r.err || r.out}`)
+        }
+        return "Error: stash requires stashAction — use: push | pop | list"
+      }
+      case "fetch": {
+        const cmdArgs = ["fetch"]
+        if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
+        if (args.ref) cmdArgs.push(validateRef(args.ref, "ref"))
+        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
+        return r.ok ? truncate(r.out || "(fetch complete — no output)") : truncate(`git fetch failed: ${r.err || r.out}`)
+      }
+      case "pull": {
+        const cmdArgs = ["pull"]
+        if (args.remote) cmdArgs.push(validateRef(args.remote, "remote"))
+        if (args.ref) cmdArgs.push(validateRef(args.ref, "ref"))
+        const r = runGitStrict(ctx.cwd, cmdArgs, cfgArgs)
+        return r.ok ? truncate(r.out || "(pull complete — no output)") : truncate(`git pull failed: ${r.err || r.out}`)
+      }
+      case "reset": {
+        const mode = args.mode ?? "mixed"
+        if (!["soft", "mixed", "hard"].includes(mode)) return "Error: reset mode must be soft | mixed | hard"
+        let snap = ""
+        if (mode === "hard") snap = await snapshotBefore(ctx, "reset --hard") // destructive: drops working-tree changes
+        const cmdArgs = ["reset", `--${mode}`]
+        if (args.ref) cmdArgs.push(validateRef(args.ref))
+        const r = runGitStrict(ctx.cwd, cmdArgs)
+        return r.ok ? truncate(snap + (r.out || `Reset (${mode}) complete`)) : truncate(`git reset failed: ${r.err || r.out}`)
+      }
+      case "revert": {
+        const ref = validateRef(args.ref ?? "HEAD")
+        const r = runGitStrict(ctx.cwd, ["revert", "--no-edit", ref])
+        return r.ok ? truncate(r.out || `Reverted ${ref}`) : truncate(`git revert failed: ${r.err || r.out}`)
+      }
+      case "merge": {
+        if (!args.ref) return "Error: merge requires ref (branch/commit to merge)"
+        validateRef(args.ref, "ref")
+        const r = runGitStrict(ctx.cwd, ["merge", "--no-edit", args.ref])
+        return r.ok ? truncate(r.out || `Merged ${args.ref}`) : truncate(`git merge failed: ${r.err || r.out} — resolve conflicts, then commit`)
+      }
+      case "cherry-pick": {
+        if (!args.ref) return "Error: cherry-pick requires ref (commit)"
+        validateRef(args.ref, "ref")
+        const r = runGitStrict(ctx.cwd, ["cherry-pick", args.ref])
+        return r.ok ? truncate(r.out || `Cherry-picked ${args.ref}`) : truncate(`git cherry-pick failed: ${r.err || r.out}`)
+      }
+      // F7 扩展 action + checkpoint：实现拆在 git-ext.mjs / git-checkpoint.mjs（500 行硬限）
+      case "clone":
+      case "init":
+      case "rebase":
+      case "remote":
+      case "clean":
+      case "switch":
+      case "apply":
+      case "worktree":
+      case "archive":
+      case "blame":
+      case "mv":
+        return executeExtAction(args, ctx)
+      case "checkpoint":
+        return executeCheckpointAction(args, ctx)
+
+      default:
+        return `Unknown action '${args.action}'. Use: diff | status | log | show | checkpoint | add | rm | commit | push | tag | branch | checkout | restore | stash | fetch | pull | reset | revert | merge | cherry-pick | ls-remote | clone | init | rebase | remote | clean | switch | apply | worktree | archive | blame | mv`
+    }
+  },
+}
+