source-code-mgmt 1.1.1 → 1.8.0

package/lib/index.js

@@ -187,14 +187,47 @@ function sshDir() {
   return join(homedir(), '.ssh')
 }
 
-/** Full path to the ed25519 private key. */
+/**
+ * Scan ~/.ssh for ed25519 PUBLIC keys (`ssh-ed25519 ...`). Returns the base
+ * names (file name without the `.pub` suffix), sorted alphabetically.
+ */
+function findEd25519Keys() {
+  const dir = sshDir()
+  const names = []
+  let entries = []
+  try { entries = readdirSync(dir) } catch { return names }
+  for (const e of entries) {
+    if (!e.endsWith('.pub')) continue
+    try {
+      const content = readFileSync(join(dir, e), 'utf8')
+      if (/^\s*ssh-ed25519\s+/.test(content)) names.push(e.slice(0, -4))
+    } catch { /* unreadable pub — skip */ }
+  }
+  return names.sort()
+}
+
+/**
+ * Resolve the SSH key base name to use (file name without `.pub`):
+ *   - prefer the conventional `id_ed25519` when it exists;
+ *   - otherwise use the FIRST detected ed25519 key (supports a custom-named key);
+ *   - if none exists, return the default `id_ed25519` (the name a newly generated
+ *     key will get — the well-known standard name that SSH/Git tooling expect).
+ */
+function resolveKeyBase() {
+  const names = findEd25519Keys()
+  if (names.includes('id_ed25519')) return 'id_ed25519'
+  if (names.length > 0) return names[0]
+  return 'id_ed25519'
+}
+
+/** Full path to the ed25519 private key (base resolved from existing keys). */
 function privateKeyPath() {
-  return join(sshDir(), 'id_ed25519')
+  return join(sshDir(), resolveKeyBase())
 }
 
-/** Full path to the ed25519 public key. */
+/** Full path to the ed25519 public key (base resolved from existing keys). */
 function publicKeyPath() {
-  return join(sshDir(), 'id_ed25519.pub')
+  return join(sshDir(), resolveKeyBase() + '.pub')
 }
 
 /** Full path to ssh config. */
@@ -327,6 +360,7 @@ function providerCfg(provider) {
 
 /** SSH key & config & gh auth summary. */
 function checkSsh() {
+  const keyBase = resolveKeyBase()
   const hasKey = existsSync(privateKeyPath())
   const hasPub = existsSync(publicKeyPath())
   const hasConfig = existsSync(configPath())
@@ -354,6 +388,9 @@ function checkSsh() {
     pubContent,
     configContent,
     sshDir: sshDir(),
+    // 当前使用的密钥文件名（不含 .pub）：优先 id_ed25519，否则自动探测到的第一个 ed25519 密钥名。
+    keyBase,
+    keyName: hasPub ? keyBase : null,
     ghLoggedIn,
     ghAccount,
     // Per-provider SSH config presence (used by the panel's provider selector).
@@ -362,10 +399,12 @@ function checkSsh() {
   }
 }
 
-/** Generate ed25519 key with no passphrase (non-interactive). */
+/** Generate ed25519 key with no passphrase (non-interactive). Note: the
+ *  generated name is the conventional `id_ed25519` (the default when no key
+ *  exists). If an existing ed25519 key (any name) is present, it is reused. */
 function generateKey() {
   if (existsSync(privateKeyPath())) {
-    return { ok: true, alreadyExists: true, path: privateKeyPath() }
+    return { ok: true, alreadyExists: true, path: privateKeyPath(), keyBase: resolveKeyBase() }
   }
   try {
     mkdirSync(sshDir(), { recursive: true })
@@ -374,10 +413,11 @@ function generateKey() {
       ok: r.ok,
       alreadyExists: false,
       path: privateKeyPath(),
+      keyBase: resolveKeyBase(),
       error: r.ok ? undefined : (r.stderr || r.stdout).trim(),
     }
   } catch (error) {
-    return { ok: false, alreadyExists: false, path: privateKeyPath(), error: String(error) }
+    return { ok: false, alreadyExists: false, path: privateKeyPath(), keyBase: resolveKeyBase(), error: String(error) }
   }
 }
 
@@ -403,7 +443,7 @@ function writeSshConfig(provider) {
       '  Hostname ' + cfg.hostname,
       '  Port ' + cfg.port,
       '  User ' + cfg.gitUser,
-      '  IdentityFile ~/.ssh/id_ed25519',
+      '  IdentityFile ~/.ssh/' + resolveKeyBase(),
       '',
     ].join('\n')
     writeFileSync(configPath(), current + block, 'utf8')
@@ -610,23 +650,88 @@ function ignorePlan(dir) {
   return { large, entries }
 }
 
+/**
+ * Extract the repository owner (org/user) from a git remote URL, regardless of
+ * form (`https://host/owner/repo.git` or `git@host:owner/repo.git`). Returns
+ * the owner (lowercased) or undefined when it cannot be determined.
+ */
+function remoteOwner(url) {
+  if (typeof url !== 'string' || url === '') return undefined
+  // git@host:owner/repo.git
+  let m = /git@[^:]+:(.+?)\/([^/]+?)(?:\.git)?\/?$/.exec(url)
+  if (m) return m[1].toLowerCase()
+  // https://host/owner/repo.git  或  ssh://git@host/owner/repo.git
+  m = /(?:https?|ssh):\/\/[^\/]+\/(.+?)\/([^/]+?)(?:\.git)?\/?$/.exec(url)
+  if (m) return m[1].toLowerCase()
+  return undefined
+}
+
+/**
+ * The current logged-in owner for a platform: 'github' -> gh owner (Zhucy123),
+ * 'gitee' -> the Gitee token account (Zhucy2100). Returns undefined when the
+ * account isn't available.
+ *
+ * A short-lived (5s) in-process cache is layered on top so a single /repo
+ * request (which calls this up to 3 times via repoExists / providerRemoteName /
+ * repoVisibility) only hits the network ONCE, and rapid sequential refreshes
+ * stay instant.
+ */
+let ownerCache = { provider: undefined, value: undefined, ts: 0 }
+function providerOwner(provider) {
+  const p = provider === 'gitee' ? 'gitee' : 'github'
+  const now = Date.now()
+  if (ownerCache.provider === p && now - ownerCache.ts < 5000) return ownerCache.value
+  const value = p === 'gitee' ? giteeOwner() : ghOwner()
+  ownerCache = { provider: p, value, ts: now }
+  return value
+}
+
+/**
+ * Pick the git remote name that belongs to the given code-hosting platform AND
+ * to the CURRENT logged-in account (owner). This way switching to Gitee reads
+ * only gitee.com remotes, and a GitHub remote belonging to another user/org
+ * (e.g. deepseek-ai/deepseek-harness) is NOT treated as the user's own remote.
+ * Returns the remote name, or undefined when the folder has no remote for the
+ * current platform + account.
+ * @param {string} dir - local folder.
+ * @param {string} [provider] - 'github' (default) | 'gitee'.
+ */
+function providerRemoteName(dir, provider) {
+  const want = provider === 'gitee' ? /gitee\.com/i : /github\.com/i
+  const owner = providerOwner(provider)
+  if (owner === undefined) return undefined
+  const wantOwner = owner.toLowerCase()
+  const r = run(GIT, ['-C', dir, 'remote'])
+  if (!r.ok) return undefined
+  let matched = undefined
+  for (const name of r.stdout.split(/\r?\n/).filter((l) => l.trim() !== '')) {
+    const u = run(GIT, ['-C', dir, 'remote', 'get-url', name])
+    // 远程需属于所选平台 且 owner 等于当前账号，才视为「用户自己的远程」。
+    if (u.ok && want.test(u.stdout) && remoteOwner(u.stdout) === wantOwner) {
+      if (name === 'origin') return 'origin'
+      if (matched === undefined) matched = name
+    }
+  }
+  return matched
+}
+
 /**
  * Repo status for a selected folder: whether it is a git repo, remote,
  * branch, dirty count, tracked-over-100MB files, and new >100MB candidates.
  */
-function repoStatus(dir, provider = 'github') {
+function repoStatus(dir, provider = 'github', full = false) {
   const base = { ok: false, dir, isGitRepo: false, provider }
   if (!dir || !existsSync(dir)) return { ...base, error: 'folder does not exist' }
   if (!existsSync(join(dir, '.git'))) {
     // 不是 git 仓库：仍返回文件夹名和同名仓库检测，便于「新建仓库」直接使用。
     const defaultRepoName = baseName(dir)
-    const existence = repoExists(defaultRepoName, provider)
+    const ev = repoExistenceAndVisibility(defaultRepoName, provider)
     return {
       ...base,
       defaultRepoName,
-      repoExists: existence.checked ? existence.exists : undefined,
-      repoOwner: existence.owner,
-      visibility: existence.checked && existence.exists ? repoVisibility(defaultRepoName, provider) : undefined,
+      repoExists: ev.checked ? ev.exists : undefined,
+      repoOwner: ev.owner,
+      visibility: ev.checked && ev.exists ? ev.visibility : undefined,
       provider,
       error: 'not a git repository（尚未 git init，可用「新建仓库并推送」初始化为 git 仓库并上传）',
     }
@@ -643,6 +748,7 @@ function repoStatus(dir, provider = 'github') {
   // readable list, e.g. { "M " -> modified, "??" -> untracked, "A " -> added,
   // "D " -> deleted, "R " -> renamed }. Only the file/folder NAME is shown in
   // the panel, never the diff content.
+  // 两字母 XY：X(第 1 位)非空格且非 '?' = 已暂存(index)，Y(第 2 位)非空格 = 未暂存(worktree)。
   const changedFiles = statusLines.map((line) => {
     const code = line.slice(0, 2)
     let path = line.slice(3)
@@ -660,7 +766,11 @@ function repoStatus(dir, provider = 'github') {
       : /^D|^AD/.test(code) ? 'deleted'
       : /^R/.test(code) ? 'renamed'
       : 'modified'
-    return { type, path }
+    // code[0] 是 index/staged 状态列（' ' 或 '?' 表示未暂存/未跟踪）。
+    const staged = code[0] !== ' ' && code[0] !== '?'
+    // diff 内容不再在 /repo 里逐个生成（改动多时会跑 N 次 git diff，拖慢加载）；
+    // 改为点开「查看改动」弹窗里的文件行时，由 /repo-diff 单独按需请求。
+    return { type, path, staged }
   })
 
   // Tracked files that exceed 100MB (GitHub would reject a push of these).
@@ -684,32 +794,60 @@ function repoStatus(dir, provider = 'github') {
     (e) => !e.ignored && !trackedOverLimit.some((t) => t.path === e.source)
   )
 
-  // Default repo name = folder basename; and whether the same-name repo exists.
+  // Default repo name = folder basename; and whether the same-name repo exists
+  // (single network call for both existence + visibility).
   const defaultRepoName = baseName(dir)
-  const existence = repoExists(defaultRepoName, provider)
+  const ev = repoExistenceAndVisibility(defaultRepoName, provider)
+
+  // 按当前平台选择远程：Gitee 平台只看 gitee.com 的远程，GitHub 平台只看 github.com，
+  // 避免切到 Gitee 时仍显示 GitHub 远程、并把 ahead/behind 算到错误的远程上。
+  const remoteName = providerRemoteName(dir, provider)
+  const hasRemote = remoteName !== undefined
+  const remoteUrl = remoteName !== undefined
+    ? (() => {
+        const r = run(GIT, ['-C', dir, 'remote', 'get-url', remoteName])
+        return r.ok ? r.stdout.trim() : undefined
+      })()
+    : undefined
 
   const branchName = branch.ok ? branch.stdout.trim() : undefined
-  const hasRemote = run(GIT, ['-C', dir, 'remote', 'get-url', 'origin']).ok
 
   // ahead (unpushed local commits) / behind (remote commits not yet pulled),
-  // measured against origin/<branch>. A lightweight fetch keeps this fresh;
-  // a failed fetch is tolerated (falls back to the last known tracking ref).
+  // measured against <providerRemote>/<branch>.
+  //
+  // `full` mode performs a `git fetch` so ahead/behind reflect the LIVE remote
+  // state (used by the explicit "刷新状态" button). The default (fast) mode
+  // SKIPS the network fetch entirely — this is what makes switching workspaces
+  // and post-push refreshes feel instant; ahead/behind then fall back to the
+  // last known tracking ref (no fetch = no freshness, but no 1-20s stall).
   let ahead = 0
   let behind = 0
-  const upstream = hasRemote && branchName ? 'origin/' + branchName : undefined
+  const upstream = hasRemote && branchName ? remoteName + '/' + branchName : undefined
   if (upstream) {
-    if (run(GIT, ['-C', dir, 'fetch', 'origin', branchName, '--quiet'], { timeout: 20_000 }).ok) {
+    if (full) {
+      if (run(GIT, ['-C', dir, 'fetch', remoteName, branchName, '--quiet'], { timeout: 20_000 }).ok) {
+        const rb = run(GIT, ['-C', dir, 'rev-list', '--left-right', '--count', upstream + '...HEAD'])
+        if (rb.ok) {
+          const m = rb.stdout.trim().split(/\s+/)
+          behind = parseInt(m[0], 10) || 0   // left side = remote-only commits
+          ahead = parseInt(m[1], 10) || 0    // right side = HEAD-only commits
+        }
+      }
+    } else {
+      // Fast path: trust the existing local tracking ref (origin/<branch>) which
+      // was populated by any prior fetch. Avoids a blocking network call.
       const rb = run(GIT, ['-C', dir, 'rev-list', '--left-right', '--count', upstream + '...HEAD'])
       if (rb.ok) {
         const m = rb.stdout.trim().split(/\s+/)
-        behind = parseInt(m[0], 10) || 0   // left side = origin-only commits
-        ahead = parseInt(m[1], 10) || 0    // right side = HEAD-only commits
+        behind = parseInt(m[0], 10) || 0
+        ahead = parseInt(m[1], 10) || 0
       }
     }
   }
 
   // Short commit lists for the "同步" detail view: commits we have locally but
   // not on origin (ahead), and commits origin has that we don't yet (behind).
+  // Only computed in full mode (the detail view is a deliberate user action).
   const fmtLogLine = (l) => {
     // porcelain <hash> <subject>
     const sp = l.indexOf(' ')
@@ -720,23 +858,21 @@ function repoStatus(dir, provider = 'github') {
     const r = run(GIT, ['-C', dir, 'log', '--oneline', '-20', range])
     return r.ok ? r.stdout.split(/\r?\n/).filter((l) => l.trim() !== '').map(fmtLogLine) : []
   }
-  const aheadCommits = ahead > 0 ? logRange(upstream + '..HEAD') : []
-  const behindCommits = behind > 0 ? logRange('HEAD..' + upstream) : []
+  const aheadCommits = (full && ahead > 0) ? logRange(upstream + '..HEAD') : []
+  const behindCommits = (full && behind > 0) ? logRange('HEAD..' + upstream) : []
 
   return {
     ok: true,
     isGitRepo: true,
     dir,
     defaultRepoName,
-    repoExists: existence.checked ? existence.exists : undefined,
-    repoOwner: existence.owner,
+    repoExists: ev.checked ? ev.exists : undefined,
+    repoOwner: ev.owner,
     provider,
     branch: branchName,
     hasRemote,
-    remoteUrl: (() => {
-      const r = run(GIT, ['-C', dir, 'remote', 'get-url', 'origin'])
-      return r.ok ? r.stdout.trim() : undefined
-    })(),
+    remoteUrl,
+    remoteName,
     dirty: dirtyFiles > 0,
     dirtyCount: dirtyFiles,
     // Changed/added/deleted/renamed file names (with their status), empty when clean.
@@ -748,7 +884,7 @@ function repoStatus(dir, provider = 'github') {
     behindCommits,
     // Actual remote visibility (private/public) when the repo exists and the
     // account can view it; undefined when unknown (not token/logged in or repo absent).
-    visibility: existence.checked && existence.exists ? repoVisibility(defaultRepoName, provider) : undefined,
+    visibility: ev.checked && ev.exists ? ev.visibility : undefined,
     trackedOverLimit,
     ignoredLarge: ignoredLarge.slice(0, 200),
   }
@@ -1090,6 +1226,36 @@ function fmtMB(bytes) {
   return (bytes / (1024 * 1024)).toFixed(1) + ' MB'
 }
 
+/**
+ * Force-align the local folder to the remote branch: fetch origin then
+ * `git reset --hard origin/<branch>`. Any local-only commits / working-tree
+ * changes are discarded so local becomes an exact copy of the remote branch.
+/**
+ * Return the diff of a single changed file, on demand (the "查看改动" panel
+ * expands a file row and fetches this instead of bundling every diff into
+ * /repo, which would spawn N git processes and stall the load on large
+ * change sets). untracked files have no diff (git doesn't track them) and
+ * return an empty string.
+ * @param {string} dir - local folder.
+ * @param {string} path - repo-relative file path.
+ */
+function repoDiffFlow(dir, path) {
+  if (!dir || !existsSync(dir) || !existsSync(join(dir, '.git'))) {
+    return { ok: false, error: 'not a git repository' }
+  }
+  const p = String(path || '').trim()
+  if (!p) return { ok: false, error: '缺少文件路径' }
+  // Untracked files have no tracked diff.
+  const status = run(GIT, ['-C', dir, 'status', '--porcelain', '--', p])
+  const isUntracked = status.ok && /^\?\?/.test(status.stdout.trim().slice(0, 2))
+  if (isUntracked) return { ok: true, path: p, diff: '' }
+  let r = run(GIT, ['-C', dir, 'diff', '--', p])
+  if (r.ok && !r.stdout.trim()) {
+    r = run(GIT, ['-C', dir, 'diff', '--cached', '--', p])
+  }
+  return { ok: true, path: p, diff: r.ok ? r.stdout : '' }
+}
+
 /**
  * Force-align the local folder to the remote branch: fetch origin then
  * `git reset --hard origin/<branch>`. Any local-only commits / working-tree
@@ -1142,6 +1308,355 @@ function initGitFlow(dir) {
   return { ok: true, alreadyRepo: false, dir, branch: 'main' }
 }
 
+// ---------------------------------------------------------------------------
+// 本地 Git 工作流 —— 选择性暂存 / 提交 / 分支 / 历史 / revert / cherry-pick / 提交 diff。
+// 全部用本插件的 run() + GIT_SSH 注入实现（与 pushFlow 一致），不依赖第三方库。
+// ---------------------------------------------------------------------------
+
+/** Basic guard: the folder must exist and be a git repo; returns an error object or null. */
+function requireGitRepo(dir) {
+  if (!dir || !existsSync(dir)) return { error: 'folder does not exist' }
+  if (!existsSync(join(dir, '.git'))) return { error: 'not a git repository（尚未 git init）' }
+  return null
+}
+
+/**
+ * Stage paths (`git add`). `path` empty/null = stage everything (`git add -A`).
+ * @param {string} dir - local folder.
+ * @param {string} [path] - repo-relative path; empty = all.
+ */
+function stageFlow(dir, path) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const args = ['-C', dir, 'add', '-A']
+  if (path && String(path).trim() !== '') args.push('--', String(path).trim())
+  const r = run(GIT, args)
+  if (!r.ok) return { ok: false, error: (r.stderr || r.stdout).trim() || 'git add 失败' }
+  return { ok: true, path: path || null }
+}
+
+/**
+ * Unstage paths (`git reset`). `path` empty/null = unstage everything.
+ * @param {string} dir - local folder.
+ * @param {string} [path] - repo-relative path; empty = all.
+ */
+function unstageFlow(dir, path) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const args = ['-C', dir, 'reset', '-q']
+  if (path && String(path).trim() !== '') args.push('--', String(path).trim())
+  const r = run(GIT, args)
+  if (!r.ok) return { ok: false, error: (r.stderr || r.stdout).trim() || 'git reset 失败' }
+  return { ok: true, path: path || null }
+}
+
+/**
+ * Commit staged changes with the given message. `paths` (array) restricts the
+ * commit to those files (they are staged first via `git add -- <paths>`);
+ * when absent, commits whatever is already staged. If the repo has no local
+ * identity configured, it uses the same DSH User / dsh@localhost fallback that
+ * `pushFlow` uses, keeping behaviour consistent.
+ * @param {string} dir - local folder.
+ * @param {string} message - commit message.
+ * @param {string[]} [paths] - optional files to stage & commit.
+ */
+function commitFlow(dir, message, paths) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const msg = String(message || '').trim()
+  if (msg === '') return { ok: false, error: '提交信息不能为空' }
+
+  const ident = run(GIT, ['-C', dir, 'config', 'user.email'])
+  if (!ident.ok) {
+    run(GIT, ['-C', dir, 'config', 'user.name', 'DSH User'])
+    run(GIT, ['-C', dir, 'config', 'user.email', 'dsh@localhost'])
+  }
+
+  const list = Array.isArray(paths) ? paths.map((p) => String(p).trim()).filter(Boolean) : []
+  let stagedPaths = []
+  if (list.length > 0) {
+    // 只提交指定文件：先把这些文件 add 进暂存区。
+    const add = run(GIT, ['-C', dir, 'add', '--', ...list])
+    if (!add.ok) return { ok: false, error: (add.stderr || add.stdout).trim() || 'git add 失败' }
+    stagedPaths = list
+  } else {
+    // 提交整个暂存区：列出已暂存文件用于提示。
+    const st = run(GIT, ['-C', dir, 'diff', '--cached', '--name-only'])
+    stagedPaths = st.ok ? st.stdout.split(/\r?\n/).filter(Boolean) : []
+  }
+
+  // 无可提交内容时避免报错。
+  const hasChanges = run(GIT, ['-C', dir, 'diff', '--cached', '--quiet']).code !== 0
+  if (!hasChanges) return { ok: false, error: '没有已暂存（staged）的改动可提交', staged: 0 }
+
+  const commit = run(GIT, ['-C', dir, 'commit', '-m', msg])
+  if (!commit.ok) return { ok: false, error: (commit.stderr || commit.stdout).trim() || 'git commit 失败', staged: stagedPaths.length }
+
+  const rev = run(GIT, ['-C', dir, 'rev-parse', '--short', 'HEAD'])
+  return {
+    ok: true,
+    message: msg,
+    hash: rev.ok ? rev.stdout.trim() : undefined,
+    staged: stagedPaths.length,
+    paths: stagedPaths,
+  }
+}
+
+/**
+ * Push STAGED changes only: commit whatever is currently staged (using the
+ * given message, or an autogenerated one when empty), then push to origin.
+ * Unlike {@link pushFlow} it does NOT go on to stage untracked/unstaged files
+ * itself and does NOT overwrite the user's own commit message. When nothing is
+ * newly staged yet (e.g. the local branch already has commits ahead), it simply
+ * pushes those existing commits.
+ * @param {string} dir - local folder.
+ * @param {string} [message] - commit message used only when something is staged
+ *   and the caller supplies one; empty falls back to an autogenerated message.
+ */
+function pushStagedFlow(dir, message) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+
+  // Remote must exist before we can push.
+  const hasRemote = run(GIT, ['-C', dir, 'remote', 'get-url', 'origin']).ok
+  if (!hasRemote) {
+    return { ok: false, needsRemote: true, error: '尚未配置远程仓库 origin，请使用「新建仓库」创建远程仓库。' }
+  }
+
+  const msg = String(message || '').trim()
+  let committed = false
+  let commitHash
+  // Commit staged content only if there is anything staged right now.
+  const hasStaged = run(GIT, ['-C', dir, 'diff', '--cached', '--quiet']).code !== 0
+  if (hasStaged) {
+    const ident = run(GIT, ['-C', dir, 'config', 'user.email'])
+    if (!ident.ok) {
+      run(GIT, ['-C', dir, 'config', 'user.name', 'DSH User'])
+      run(GIT, ['-C', dir, 'config', 'user.email', 'dsh@localhost'])
+    }
+    const useMsg = msg || ('chore: update ' + baseName(dir))
+    const commit = run(GIT, ['-C', dir, 'commit', '-m', useMsg])
+    if (!commit.ok) return { ok: false, error: (commit.stderr || commit.stdout).trim() || 'git commit 失败' }
+    committed = true
+    const rev = run(GIT, ['-C', dir, 'rev-parse', '--short', 'HEAD'])
+    commitHash = rev.ok ? rev.stdout.trim() : undefined
+  }
+
+  const curBranch = run(GIT, ['-C', dir, 'rev-parse', '--abbrev-ref', 'HEAD'])
+  const branchName = curBranch.ok ? curBranch.stdout.trim() : 'main'
+  const push = run(GIT, ['-C', dir, 'push', '-u', 'origin', branchName], { timeout: 120_000 })
+  const pushed = push.ok
+  return {
+    ok: pushed,
+    needsRemote: false,
+    committed,
+    commitHash,
+    message: msg || (committed ? ('chore: update ' + baseName(dir)) : undefined),
+    branch: branchName,
+    pushed,
+    pushError: pushed ? undefined : (push.stderr || push.stdout).trim(),
+  }
+}
+
+/**
+ * List branches (current first) using `git for-each-ref`.
+ * @param {string} dir - local folder.
+ */
+function branchesFlow(dir) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const cur = run(GIT, ['-C', dir, 'rev-parse', '--abbrev-ref', 'HEAD'])
+  const current = cur.ok && cur.stdout.trim() !== 'HEAD' ? cur.stdout.trim() : cur.ok ? cur.stdout.trim() : 'HEAD'
+  const r = run(GIT, ['-C', dir, 'for-each-ref', '--format=%(refname:short)', 'refs/heads'])
+  const names = r.ok ? r.stdout.split(/\r?\n/).map((l) => l.trim()).filter((l) => l !== '') : []
+  if (!names.includes(current)) names.unshift(current)
+  return { ok: true, current, branches: names }
+}
+
+/**
+ * Checkout an existing branch.
+ * @param {string} dir - local folder.
+ * @param {string} branch - branch name to switch to.
+ */
+function checkoutFlow(dir, branch) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const b = String(branch || '').trim()
+  if (b === '') return { ok: false, error: '缺少分支名' }
+  const r = run(GIT, ['-C', dir, 'checkout', b])
+  if (!r.ok) return { ok: false, error: (r.stderr || r.stdout).trim() || '切换分支失败' }
+  return { ok: true, branch: b }
+}
+
+/**
+ * Recent commit history (newest first). Each row carries the short hash,
+ * full hash, subject, author and date.
+ * @param {string} dir - local folder.
+ * @param {number} [count] - how many commits (default 30).
+ */
+function logFlow(dir, count) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const n = Math.max(1, Math.min(500, parseInt(count, 10) || 30))
+  const r = run(GIT, ['-C', dir, '--no-pager', 'log', '-n', String(n), '--decorate=short',
+    '--pretty=format:%h%x1f%s%x1f%an%x1f%ai%x1f%H%x1f%D'])
+  if (!r.ok) {
+    // 空仓库（无提交）时 git log 报错——视为空历史，而不是失败。
+    if (/does not have any commits|bad revision|your current branch/i.test((r.stderr || r.stdout))) {
+      return { ok: true, commits: [] }
+    }
+    return { ok: false, error: (r.stderr || r.stdout).trim() || 'git log 失败' }
+  }
+  const commits = r.stdout.split(/\r?\n/).filter((l) => l.trim() !== '').map((line) => {
+    const [short, subject, author, date, full, refs] = line.split('\x1f')
+    return {
+      hash: short || '',
+      hashFull: full || short || '',
+      subject: subject || '',
+      author: author || '',
+      date: date || '',
+      refs: refs || '',
+    }
+  })
+  return { ok: true, commits }
+}
+
+/**
+ * Revert a commit onto the current branch (auto-generated message, no editor).
+ * @param {string} dir - local folder.
+ * @param {string} hash - commit hash to revert.
+ */
+function revertFlow(dir, hash) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const h = String(hash || '').trim()
+  if (h === '') return { ok: false, error: '缺少 commit hash' }
+  const r = run(GIT, ['-C', dir, 'revert', '--no-edit', h], { timeout: 60_000 })
+  if (!r.ok) return { ok: false, error: (r.stderr || r.stdout).trim() || 'revert 失败（可能有冲突，请手动处理）' }
+  return { ok: true, hash: h }
+}
+
+/**
+ * Cherry-pick a commit onto the current branch.
+ * @param {string} dir - local folder.
+ * @param {string} hash - commit hash to cherry-pick.
+ */
+function cherryPickFlow(dir, hash) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const h = String(hash || '').trim()
+  if (h === '') return { ok: false, error: '缺少 commit hash' }
+  const r = run(GIT, ['-C', dir, 'cherry-pick', h], { timeout: 60_000 })
+  if (!r.ok) return { ok: false, error: (r.stderr || r.stdout).trim() || 'cherry-pick 失败（可能有冲突，请手动处理）' }
+  return { ok: true, hash: h }
+}
+
+/**
+ * Full patch text of one commit (header suppressed). Merge commits diff
+ * against the first parent so a history click always has content.
+ * @param {string} dir - local folder.
+ * @param {string} hash - commit hash.
+ */
+function commitDiffFlow(dir, hash) {
+  const guard = requireGitRepo(dir)
+  if (guard) return { ok: false, error: guard.error }
+  const h = String(hash || '').trim()
+  if (h === '') return { ok: false, error: '缺少 commit hash' }
+  const r = run(GIT, ['-C', dir, 'show', '--no-ext-diff', '--no-color', '--format=', '-m', '--first-parent', h])
+  if (!r.ok) return { ok: false, error: (r.stderr || r.stdout).trim() || '读取提交 diff 失败' }
+  return { ok: true, hash: h, diff: r.stdout }
+}
+
+// ---------------------------------------------------------------------------
+// 工具安装（① 环境检查缺工具时的一键安装）——best-effort：按可用包管理器自动选取命令。
+// ---------------------------------------------------------------------------
+
+/**
+ * Whether a command exists (probe `--version`; for shell scripts use `command -v`).
+ * @param {string} bin - bare command name.
+ */
+function binExists(bin) {
+  if (bin === 'apt-get' || bin === 'dnf' || bin === 'yum') {
+    return run('sh', ['-c', 'command -v ' + bin]).ok
+  }
+  return run(bin, ['--version']).ok
+}
+
+/**
+ * Build the install command to run for `tool` on this machine, or null when no
+ * usable package manager is available. Returns arrays usable with `run`.
+ * @param {'git'|'gh'|'ssh'} tool
+ */
+function installCommand(tool) {
+  if (IS_WIN) {
+    // SSH 客户端：Windows 内置可选功能（需管理员），走 powershell。
+    if (tool === 'ssh') {
+      return { bin: 'powershell', args: ['-NoProfile', '-Command', 'Add-WindowsCapability -Online -Name OpenSSH.Client~~~~0.0.1.0'], label: 'Add-WindowsCapability -Online -Name OpenSSH.Client' }
+    }
+    const pkg = tool === 'git' ? 'Git.Git' : 'GitHub.cli'
+    if (binExists('winget')) {
+      return { bin: 'winget', args: ['install', '--id', pkg, '-e', '--source', 'winget', '--accept-package-agreements', '--accept-source-agreements'], label: 'winget install --id ' + pkg + ' -e' }
+    }
+    if (binExists('choco')) {
+      return { bin: 'choco', args: ['install', tool === 'git' ? 'git' : 'gh', '-y'], label: 'choco install ' + (tool === 'git' ? 'git' : 'gh') + ' -y' }
+    }
+    if (binExists('scoop')) {
+      return { bin: 'scoop', args: ['install', tool === 'git' ? 'git' : 'gh'], label: 'scoop install ' + (tool === 'git' ? 'git' : 'gh') }
+    }
+    return null
+  }
+  if (process.platform === 'darwin') {
+    const pkg = tool === 'git' ? 'git' : tool === 'gh' ? 'gh' : 'openssh'
+    if (binExists('brew')) return { bin: 'brew', args: ['install', pkg], label: 'brew install ' + pkg }
+    return null
+  }
+  // Linux：按可用包管理器选择。安装需 root，用 sudo（非交互 -n，避免挂起等待密码；已是 root 则直接跑）。
+  const pkg = tool === 'git' ? 'git' : tool === 'gh' ? 'gh' : 'openssh-client'
+  const isRoot = typeof process.getuid === 'function' && process.getuid() === 0
+  const sudo = !isRoot && binExists('sudo') ? 'sudo -n ' : ''
+  if (binExists('apt-get')) {
+    return { bin: 'sh', args: ['-c', sudo + 'apt-get install -y ' + pkg], label: 'sudo apt-get install -y ' + pkg }
+  }
+  if (binExists('dnf')) {
+    return { bin: 'sh', args: ['-c', sudo + 'dnf install -y ' + pkg], label: 'sudo dnf install -y ' + pkg }
+  }
+  if (binExists('pacman')) {
+    return { bin: 'sh', args: ['-c', sudo + 'pacman -S --noconfirm ' + pkg], label: 'sudo pacman -S ' + pkg }
+  }
+  return null
+}
+
+/**
+ * Install a missing tool (git / gh / ssh) using the best available package
+ * manager. Best-effort: reports the command it ran and its output.
+ * @param {string} tool - 'git' | 'gh' | 'ssh'.
+ */
+function installToolFlow(tool) {
+  const t = String(tool || '').trim().toLowerCase()
+  if (t !== 'git' && t !== 'gh' && t !== 'ssh') return { ok: false, error: '未知工具：' + tool }
+  // 已安装就直接返回，不重复安装。
+  const present = t === 'git' ? (GIT && GIT !== 'git')
+    : t === 'gh' ? (GH && GH !== 'gh')
+    : (SSH && SSH !== 'ssh' && SSH !== 'ssh.exe')
+  if (present) return { ok: true, alreadyInstalled: true, tool: t }
+
+  const cmd = installCommand(t)
+  if (!cmd) {
+    return { ok: false, error: '未找到可用的包管理器（' + (IS_WIN ? 'winget / choco / scoop' : process.platform === 'darwin' ? 'brew' : 'apt-get / dnf / pacman') + '）。请手动安装。', tool: t }
+  }
+  const r = run(cmd.bin, cmd.args, { timeout: 300_000 })
+  const output = (r.stdout + '\n' + r.stderr).trim()
+  // 安装后复查是否已装上。
+  const ok = r.ok && (t === 'git' ? (GIT && GIT !== 'git') : t === 'gh' ? (GH && GH !== 'gh') : !(SSH === 'ssh' || SSH === 'ssh.exe'))
+  return {
+    ok,
+    tool: t,
+    command: cmd.label,
+    output: output || (ok ? '安装成功' : '安装失败'),
+    needElevation: IS_WIN && t === 'ssh',
+  }
+}
+
 // ---------- route handlers ----------
 
 function json(res, status, payload) {
@@ -1304,19 +1819,25 @@ function pickDirDialog(initialDir) {
   return outLine !== '' && existsSync(outLine) ? outLine : undefined
 }
 
-/** Decode a `--C-Users-27775-workspace--` session dir name back to a Windows
- *  path (best-effort; segments are joined by '\'). Ambiguous when a folder
- *  name itself contains '-', which is why workspace.json is preferred. */
+/** Decode a session dir name back to a filesystem path (best-effort).
+ *  Windows names look like `--C-Users-27775-workspace--` (drive + '-' joined
+ *  segments → `\`); POSIX names like `--Users-name-workspace--` (segments → `/`).
+ *  Ambiguous when a folder name itself contains '-', which is why
+ *  workspace.json is preferred as the source of truth. */
 function decodeSessionDir(name) {
   if (typeof name !== 'string') return null
   const inner = name.replace(/^--/, '').replace(/--$/, '')
   if (inner === '') return null
-  // Split on '-'; first token is the drive letter.
   const parts = inner.split('-')
   if (parts.length === 0) return null
-  const drive = parts[0]
-  const rest = parts.slice(1).join('\\')
-  return drive + ':\\' + rest
+  if (IS_WIN) {
+    // Windows: first token is the drive letter, rest joined with '\'.
+    const drive = parts[0]
+    const rest = parts.slice(1).join('\\')
+    return drive + ':\\' + rest
+  }
+  // POSIX (macOS / Linux): absolute path, segments joined with '/'.
+  return '/' + parts.join('/')
 }
 
 /**
@@ -1325,18 +1846,18 @@ function decodeSessionDir(name) {
  * @param {string} name - repo name (without owner).
  * @param {string} [provider] - 'github' (default) | 'gitee'.
  */
-function repoExists(name, provider = 'github') {
+function repoExists(name, provider = 'github', owner) {
   if (provider === 'gitee') {
-    const owner = giteeOwner()
-    if (!owner || !name) return { owner, checked: false, provider: 'gitee' }
-    const api = giteeApi('GET', 'repos/' + owner + '/' + name)
-    if (!api.ok) return { owner, checked: false, provider: 'gitee', error: api.error }
-    return { owner, checked: true, exists: !giteeApiFailed(api.data), provider: 'gitee' }
-  }
-  const owner = ghOwner()
-  if (!owner || !name) return { owner, checked: false, provider: 'github' }
-  const r = run(GH, ['repo', 'view', owner + '/' + name, '--json', 'name'], { timeout: 20_000 })
-  return { owner, checked: true, exists: r.ok, provider: 'github' }
+    const o = owner || giteeOwner()
+    if (!o || !name) return { owner: o, checked: false, provider: 'gitee' }
+    const api = giteeApi('GET', 'repos/' + o + '/' + name)
+    if (!api.ok) return { owner: o, checked: false, provider: 'gitee', error: api.error }
+    return { owner: o, checked: true, exists: !giteeApiFailed(api.data), provider: 'gitee' }
+  }
+  const o = owner || ghOwner()
+  if (!o || !name) return { owner: o, checked: false, provider: 'github' }
+  const r = run(GH, ['repo', 'view', o + '/' + name, '--json', 'name'], { timeout: 20_000 })
+  return { owner: o, checked: true, exists: r.ok, provider: 'github' }
 }
 
 /**
@@ -1345,18 +1866,19 @@ function repoExists(name, provider = 'github') {
  * callers treat "unknown" as "no visibility info".
  * @param {string} name - repo name (without owner).
  * @param {string} [provider] - 'github' (default) | 'gitee'.
+ * @param {string} [owner] - pre-resolved owner (skips a network lookup).
  */
-function repoVisibility(name, provider = 'github') {
+function repoVisibility(name, provider = 'github', owner) {
   if (provider === 'gitee') {
-    const owner = giteeOwner()
-    if (!owner || !name) return undefined
-    const api = giteeApi('GET', 'repos/' + owner + '/' + name)
+    const o = owner || giteeOwner()
+    if (!o || !name) return undefined
+    const api = giteeApi('GET', 'repos/' + o + '/' + name)
     if (!api.ok || !api.data || giteeApiFailed(api.data)) return undefined
     return api.data.private === true ? 'private' : (api.data.private === false ? 'public' : undefined)
   }
-  const owner = ghOwner()
-  if (!owner || !name) return undefined
-  const r = run(GH, ['repo', 'view', owner + '/' + name, '--json', 'visibility'], { timeout: 20_000 })
+  const o = owner || ghOwner()
+  if (!o || !name) return undefined
+  const r = run(GH, ['repo', 'view', o + '/' + name, '--json', 'visibility'], { timeout: 20_000 })
   if (!r.ok) return undefined
   try {
     const parsed = JSON.parse(r.stdout)
@@ -1367,6 +1889,44 @@ function repoVisibility(name, provider = 'github') {
   }
 }
 
+/**
+ * One-shot check that returns BOTH whether a same-name repo exists AND its
+ * current visibility, using a SINGLE network call (GitHub `gh repo view` with
+ * both fields; Gitee `GET /repos/{owner}/{name}`). This collapses the two
+ * separate `repoExists` + `repoVisibility` calls that `repoStatus` used to make
+ * back-to-back, halving the remote round-trips for the common case.
+ * @param {string} name - repo name (without owner).
+ * @param {string} [provider] - 'github' (default) | 'gitee'.
+ * @param {string} [owner] - pre-resolved owner (skips a network lookup).
+ */
+function repoExistenceAndVisibility(name, provider = 'github', owner) {
+  if (provider === 'gitee') {
+    const o = owner || giteeOwner()
+    if (!o || !name) return { owner: o, checked: false, provider: 'gitee' }
+    const api = giteeApi('GET', 'repos/' + o + '/' + name)
+    if (!api.ok) return { owner: o, checked: false, provider: 'gitee', error: api.error }
+    const exists = !giteeApiFailed(api.data)
+    const visibility = exists && api.data
+      ? (api.data.private === true ? 'private' : (api.data.private === false ? 'public' : undefined))
+      : undefined
+    return { owner: o, checked: true, exists, visibility, provider: 'gitee' }
+  }
+  const o = owner || ghOwner()
+  if (!o || !name) return { owner: o, checked: false, provider: 'github' }
+  const r = run(GH, ['repo', 'view', o + '/' + name, '--json', 'name,visibility'], { timeout: 20_000 })
+  if (!r.ok) return { owner: o, checked: true, exists: false, visibility: undefined, provider: 'github' }
+  try {
+    const parsed = JSON.parse(r.stdout)
+    const v = String(parsed.visibility || '').toLowerCase()
+    return {
+      owner: o, checked: true, exists: true,
+      visibility: v === 'public' || v === 'private' ? v : undefined, provider: 'github',
+    }
+  } catch {
+    return { owner: o, checked: true, exists: true, visibility: undefined, provider: 'github' }
+  }
+}
+
 /**
  * Change a repo's visibility. GitHub mode uses gh; Gitee mode uses the Gitee
  * OpenAPI. Returns the new visibility on success.
@@ -1418,6 +1978,13 @@ export function apply(ctx) {
 
   const routes = {
     '/env': (req, res) => handle(req, res, async () => ({ ok: true, ...checkEnv() })),
+    '/install-tool': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return installToolFlow(body.tool)
+      })
+    },
     '/ssh': (req, res) => handle(req, res, async () => ({ ok: true, ...checkSsh() })),
     '/gen-key': async (req, res) => {
       if (req.method !== 'POST') return methodNotAllowed(res, req.method)
@@ -1502,12 +2069,85 @@ export function apply(ctx) {
         try {
           const q = new URL(req.url ?? '', 'http://localhost')
           const provider = q.searchParams.get('provider') || 'github'
-          return repoStatus(queryDir(req, fallbackDir), provider)
+          const full = q.searchParams.get('full') === '1'
+          return repoStatus(queryDir(req, fallbackDir), provider, full)
         } catch {
-          return repoStatus(queryDir(req, fallbackDir), 'github')
+          return repoStatus(queryDir(req, fallbackDir), 'github', false)
         }
       })
     },
+    '/repo-diff': async (req, res) => {
+      if (req.method !== 'GET') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const q = new URL(req.url ?? '', 'http://localhost')
+        const dir = q.searchParams.get('dir') || fallbackDir
+        const path = q.searchParams.get('path') || ''
+        return repoDiffFlow(dir, path)
+      })
+    },
+    '/stage': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return stageFlow(body.dir || fallbackDir, body.path)
+      })
+    },
+    '/unstage': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return unstageFlow(body.dir || fallbackDir, body.path)
+      })
+    },
+    '/commit': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return commitFlow(body.dir || fallbackDir, body.message, body.paths)
+      })
+    },
+    '/branches': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return branchesFlow(body.dir || fallbackDir)
+      })
+    },
+    '/checkout': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return checkoutFlow(body.dir || fallbackDir, body.branch)
+      })
+    },
+    '/log': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return logFlow(body.dir || fallbackDir, body.count)
+      })
+    },
+    '/revert': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return revertFlow(body.dir || fallbackDir, body.hash)
+      })
+    },
+    '/cherrypick': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return cherryPickFlow(body.dir || fallbackDir, body.hash)
+      })
+    },
+    '/commit-diff': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return commitDiffFlow(body.dir || fallbackDir, body.hash)
+      })
+    },
     '/push': async (req, res) => {
       if (req.method !== 'POST') return methodNotAllowed(res, req.method)
       await handle(req, res, async (req) => {
@@ -1515,6 +2155,13 @@ export function apply(ctx) {
         return pushFlow(body.dir || fallbackDir)
       })
     },
+    '/push-staged': async (req, res) => {
+      if (req.method !== 'POST') return methodNotAllowed(res, req.method)
+      await handle(req, res, async (req) => {
+        const body = JSON.parse((await readBody(req)) || '{}')
+        return pushStagedFlow(body.dir || fallbackDir, body.message)
+      })
+    },
     '/pull': async (req, res) => {
       if (req.method !== 'POST') return methodNotAllowed(res, req.method)
       await handle(req, res, async (req) => {