Skip to content

Node-based terminal manager for AI coding agents — tmux-backed terminals and parallel agent sessions as draggable nodes on an infinite pan/zoom canvas. macOS, Linux, and a browser Server Edition.

38.0 KB
Raw Blame
import { execFile, spawn } from 'child_process'
import fs from 'fs'
import os from 'os'
import path from 'path'
import { promisify } from 'util'
import { IPC } from '../shared/ipc'
import type { GitFileChange, GitResult, GitStatus } from '../shared/types'
import { loadGitHistoryFromExecutor } from '../shared/git-history'
import * as worktreeOps from '../shared/worktree-ops'
import type { WorktreeListResult } from '../shared/worktree'
import type { GitHistoryOptions, GitHistoryResult } from '../shared/git-history'
import { resolveGitRemote, runRemoteGit } from './remote-ssh/remote-git'
import { platform } from './platform'
import { directExecutableInvocation } from './exec-path'
import { ghPath } from './gh-path'
import { gitEnv } from './git-env'
import { worktreeTargetRefusal } from './worktree-target'
import {
  isValidCloneUrl,
  expandCloneUrl,
  deriveRepoDirName,
  parseCloneProgress,
  stripAnsiCodes
} from '../shared/clone-url'

const run = promisify(execFile)

// The environment every `git`/`gh` subprocess gets: the GUI-blind POSIX bin dirs prepended (macOS
// credential helpers), and GIT_TERMINAL_PROMPT=0 so auth failures error out fast instead of hanging
// on a prompt with no TTY. Both halves — and the reason the prepend must not happen on Windows
// (issue #583) — live in git-env.ts, which github/credentials.ts imports as well.
const GIT_ENV: NodeJS.ProcessEnv = gitEnv()

function ghInvocation(args: string[]): ReturnType<typeof directExecutableInvocation> {
  const gh = ghPath()
  return gh ? directExecutableInvocation(gh, args) : null
}

function ghRunnable(): boolean {
  return ghInvocation([]) !== null
}

// Single-flight registry for the one clone the app runs at a time. Module-scoped so a
// macOS window re-creation can't orphan it.
type ActiveClone = {
  child: import('child_process').ChildProcess | null
  clonePath: string
  aborted: boolean
}
let activeClone: ActiveClone | null = null

// `gh auth status` is a network-touching CLI call (it validates the token against the GitHub
// API — measured ~700ms even on a fast link) but auth state changes rarely, so cache it.
const GH_AUTH_TTL_MS = 10 * 60_000
let ghAuthedCache: { value: boolean; at: number } | null = null
let ghAuthedInFlight: Promise<boolean> | null = null

async function ghAuthed(opts?: { recheckNegative?: boolean }): Promise<boolean> {
  const invocation = ghInvocation(['auth', 'status'])
  if (!invocation) return false
  const now = Date.now()
  const trusted = ghAuthedCache && (ghAuthedCache.value || !opts?.recheckNegative)
  if (ghAuthedCache && trusted && now - ghAuthedCache.at < GH_AUTH_TTL_MS) return ghAuthedCache.value
  if (ghAuthedInFlight) return ghAuthedInFlight
  ghAuthedInFlight = (async () => {
    let value = false
    try {
      await run(invocation.executable, invocation.args, {
        ...invocation.options,
        env: GIT_ENV,
        maxBuffer: 1024 * 1024
      })
      value = true
    } catch {
      value = false
    }
    ghAuthedCache = { value, at: Date.now() }
    ghAuthedInFlight = null
    return value
  })()
  return ghAuthedInFlight
}

/**
 * Stale-while-revalidate view of `ghAuthed` for the status() hot path: `status()` must never
 * block the file list on a GitHub API round-trip. Returns the cached answer immediately (even
 * expired — auth state changes rarely, a stale answer beats a blank panel) and refreshes the
 * cache in the background so the panel's next refresh sees the real value. Only the very first
 * call ever (no cache at all) reports `false` while the probe runs; that flips one refresh later.
 */
function ghAuthedSwr(): boolean {
  if (!ghRunnable()) return false
  const fresh = !!ghAuthedCache && Date.now() - ghAuthedCache.at < GH_AUTH_TTL_MS
  if (!fresh) void ghAuthed().catch(() => {})
  return ghAuthedCache?.value ?? false
}

interface Exec {
  ok: boolean
  out: string
  err: string
}

async function git(cwd: string, args: string[]): Promise<Exec> {
  // SSH projects route every pure-git op over the project's ControlMaster. runRemoteGit returns
  // the same { ok, out, err } shape, so the rest of GitService is transport-agnostic. Local path
  // (and gh ops) are untouched when no remote owns this cwd.
  const ref = resolveGitRemote(cwd)
  if (ref) {
    const r = await runRemoteGit(ref, cwd, args, 20 * 1024 * 1024)
    return { ok: r.ok, out: r.out, err: r.err }
  }
  try {
    const { stdout } = await run('git', args, { cwd, env: GIT_ENV, maxBuffer: 20 * 1024 * 1024 })
    return { ok: true, out: stdout.replace(/\n$/, ''), err: '' }
  } catch (e) {
    const err = e as { stdout?: string; stderr?: string; message?: string }
    return { ok: false, out: (err.stdout ?? '').trim(), err: (err.stderr || err.message || '').trim() }
  }
}

/**
 * Is this repo answered by a REMOTE git (the `git` executor above routes over the project's
 * ControlMaster when `resolveGitRemote` claims the cwd)?
 *
 * It matters because the worktree ops are handed a `pathExists` — and the only `pathExists` this
 * process has is `fs.existsSync`, which can answer about THIS MACHINE and nothing else. Pairing a
 * remote git with a local stat is a loaded gun: every listed worktree's directory would come back
 * missing, so every entry is `prunable: true` ("everything is gone"), and the callers act on that
 * as fact — every bound group struck out as missing, `worktreeRemove` answering `worktreeGone` for
 * a worktree that is alive and well on the host (and the renderer then destroying its terminals'
 * tmux sessions and rewriting their persisted cwds).
 *
 * Worktrees are unsupported in SSH projects in v1 and the renderer gates all of these ops, so this
 * is unreachable today — it is the tripwire for whoever lifts that restriction. Until a remote
 * `pathExists` exists (a `test -e` over the ControlMaster), the ops REFUSE for a remote repo rather
 * than answer about the wrong machine: a refusal is a failed op, which every caller already handles,
 * and — crucially — is never dressed up as `worktreeGone`, so nothing is destroyed on a bad guess.
 */
const isRemoteRepo = (repoPath: string): boolean => !!resolveGitRemote(repoPath)

/**
 * What the worktree ops answer for a repo that lives on an SSH host. See `isRemoteRepo`.
 *
 * A plain failed op — and NEVER `worktreeGone`, which is the one field the renderer reads as proof
 * that a directory is gone (it destroys the descendant terminals' tmux sessions and rewrites their
 * persisted cwds on it). A refusal knows nothing about the host's filesystem, so it must not claim
 * to.
 */
const REMOTE_WORKTREE_REFUSAL = (): worktreeOps.WorktreeOpResult => ({
  ok: false,
  message: 'Worktrees are not supported in SSH projects. Nothing was changed.'
})

function parseRepoName(url: string, fallback: string): string {
  const m = url.match(/[:/]([^/:]+\/[^/]+?)(?:\.git)?$/)
  return m ? m[1] : fallback
}

/**
 * Reject branch/ref names that could smuggle CLI flags (leading `-`) or are not
 * valid git refs. Defends against argv flag injection on `git switch …`.
 */
function isValidRef(name: string): boolean {
  const n = name.trim()
  if (!n || n.startsWith('-')) return false
  return !/[\s~^:?*[\\]|\.\.|^\/|\/$|@\{/.test(n)
}

/** path -> {added, deleted} from `git diff --numstat` output. */
function parseNumstat(out: string): Map<string, { added: number; deleted: number }> {
  const map = new Map<string, { added: number; deleted: number }>()
  for (const line of out.split('\n').filter(Boolean)) {
    const [a, d, ...rest] = line.split('\t')
    const p = rest.join('\t')
    map.set(p, { added: Number(a) || 0, deleted: Number(d) || 0 })
  }
  return map
}

/**
 * Read the user's stored github.com HTTPS token from git's credential helper
 * (macOS keychain etc.) so we can hand it to `gh` as GH_TOKEN — letting someone
 * who can already push over HTTPS publish a new repo without a separate
 * `gh auth login`. Returns null if no HTTPS credential is stored (e.g. SSH-only).
 * Never logs the token. `git credential fill` reads the query from stdin.
 */
function githubTokenFromGitCredentials(cwd: string): Promise<string | null> {
  return new Promise((resolve) => {
    let out = ''
    // A STORED token only — never an interactive login. Git Credential Manager (the default helper
    // in Git for Windows, optional on macOS/Linux) opens a GUI sign-in for an empty store, which
    // `GIT_TERMINAL_PROMPT=0` does not suppress; Source Control retries publish every few seconds
    // while the user runs `gh auth login` (renderer/lib/publishFallback), so without this every
    // retry would stack another GCM window. Helpers other than GCM ignore the variable.
    const child = spawn('git', ['credential', 'fill'], {
      cwd: cwd || undefined,
      env: { ...GIT_ENV, GCM_INTERACTIVE: 'never' }
    })
    const timer = setTimeout(() => child.kill('SIGKILL'), 5000)
    child.stdout.on('data', (d) => {
      out += d.toString()
    })
    child.on('error', () => {
      clearTimeout(timer)
      resolve(null)
    })
    child.on('close', () => {
      clearTimeout(timer)
      const line = out.split('\n').find((l) => l.startsWith('password='))
      const token = line ? line.slice('password='.length).trim() : ''
      resolve(token || null)
    })
    // `git credential fill` can exit before reading the query (no helper configured, killed by
    // the timeout above) — the EPIPE arrives as an async 'error' EVENT on the pipe, not a throw
    // here, and unhandled it kills the main process (issue #382's class). The close handler
    // already resolves this call; the error never carries the token, so logging the code is safe.
    child.stdin.on('error', (e: NodeJS.ErrnoException) => {
      console.warn(`[git] credential-fill stdin write failed (${e.code ?? e})`)
    })
    child.stdin.write('protocol=https\nhost=github.com\n\n')
    child.stdin.end()
  })
}

/**
 * Per-project git operations using the system `git` (and `gh` for publishing).
 * The repo root is the active project's working directory.
 */
export class GitService {
  registerIpc(): void {
    platform().handle(IPC.gitStatus, (cwd: string) => this.status(cwd))
    platform().handle(IPC.gitInit, (cwd: string) => this.init(cwd))
    platform().handle(IPC.gitClone, (parentDir: string, url: string) => this.clone(parentDir, url))
    platform().handle(IPC.gitCloneAbort, () => this.cloneAbort())
    platform().handle(IPC.gitCloneDefaultParent, () => this.cloneDefaultParent())
    platform().handle(IPC.gitCommit, (cwd: string, message: string) => this.commit(cwd, message))
    platform().handle(IPC.gitPush, (cwd: string) => this.push(cwd))
    platform().handle(IPC.gitPull, (cwd: string) => this.pull(cwd))
    platform().handle(IPC.gitSync, (cwd: string) => this.sync(cwd))
    platform().handle(IPC.gitPublish, (cwd: string, name: string, isPrivate: boolean) =>
      this.publish(cwd, name, isPrivate)
    )
    platform().handle(IPC.gitStage, (cwd: string, paths: string[]) => this.stage(cwd, paths))
    platform().handle(IPC.gitUnstage, (cwd: string, paths: string[]) => this.unstage(cwd, paths))
    platform().handle(IPC.gitStageAll, (cwd: string) => this.stageAll(cwd))
    platform().handle(IPC.gitUnstageAll, (cwd: string) => this.unstageAll(cwd))
    platform().handle(IPC.gitDiff, (cwd: string, p: string, staged: boolean, untracked: boolean) =>
      this.diff(cwd, p, staged, untracked)
    )
    platform().handle(IPC.gitDiscard, (cwd: string, p: string, untracked: boolean) =>
      this.discard(cwd, p, untracked)
    )
    platform().handle(IPC.gitSwitchBranch, (cwd: string, name: string) =>
      this.switchBranch(cwd, name)
    )
    platform().handle(IPC.gitCreateBranch, (cwd: string, name: string) =>
      this.createBranch(cwd, name)
    )
    platform().handle(IPC.gitShowFile, (cwd: string, ref: string, p: string) =>
      this.showFile(cwd, ref, p)
    )
    platform().handle(IPC.gitHistory, (cwd: string, options) => this.history(cwd, options))
    platform().handle(IPC.gitCommitFiles, (cwd: string, oid: string) => this.commitFiles(cwd, oid))
    platform().handle(IPC.gitRemoteCommitUrl, (cwd: string, sha: string) =>
      this.remoteCommitUrl(cwd, sha)
    )
    platform().handle(IPC.gitMerge, (cwd: string, ref: string) => this.merge(cwd, ref))
    platform().handle(IPC.gitRebase, (cwd: string, onto: string) => this.rebase(cwd, onto))
    platform().handle(IPC.gitDeleteBranch, (cwd: string, name: string, force: boolean) =>
      this.deleteBranch(cwd, name, force)
    )
    platform().handle(IPC.gitRenameBranch, (cwd: string, newName: string) =>
      this.renameBranch(cwd, newName)
    )
    platform().handle(IPC.gitFetch, (cwd: string) => this.fetch(cwd))
    platform().handle(IPC.gitForcePush, (cwd: string) => this.forcePush(cwd))
    platform().handle(IPC.gitStashPush, (cwd: string) => this.stashPush(cwd))
    platform().handle(IPC.gitStashPop, (cwd: string) => this.stashPop(cwd))
    platform().handle(IPC.gitRevert, (cwd: string, oid: string) => this.revert(cwd, oid))
    platform().handle(IPC.gitBranchAt, (cwd: string, name: string, oid: string) =>
      this.branchAt(cwd, name, oid)
    )
    platform().handle(IPC.gitCheckoutCommit, (cwd: string, oid: string) =>
      this.checkoutCommit(cwd, oid)
    )
    platform().handle(IPC.gitRepoRoot, (cwd: string) => this.repoRoot(cwd))
    platform().handle(IPC.gitWorktreeList, (repoPath: string) => this.worktreeList(repoPath))
    platform().handle(IPC.gitWorktreeAdd, (repoPath: string, wtPath: string, branch: string, baseRef: string, isNew: boolean) =>
      this.worktreeAdd(repoPath, wtPath, branch, baseRef, isNew)
    )
    platform().handle(IPC.gitWorktreeMerge, (repoPath: string, branch: string, baseRef: string, push?: boolean) =>
      this.worktreeMerge(repoPath, branch, baseRef, push)
    )
    platform().handle(IPC.gitWorktreeRemove, (repoPath: string, wtPath: string, deleteBranch: boolean, pruneOnly?: boolean) =>
      this.worktreeRemove(repoPath, wtPath, deleteBranch, pruneOnly)
    )
  }

  repoRoot(cwd: string) {
    return worktreeOps.repoRoot(git, cwd)
  }
  worktreeList(repoPath: string): Promise<WorktreeListResult> {
    // A repo on an SSH host cannot be stat'd from here (see `isRemoteRepo`): answer "the read
    // failed", which is exactly what it is — NOT an empty list, which every caller would read as
    // "there are no worktrees".
    if (isRemoteRepo(repoPath)) return Promise.resolve({ ok: false, entries: [] })
    // `pathExists` is git's `prunable` flag's fallback for git < 2.36 (see worktree-ops): without
    // it, an old git reports a deleted worktree directory as healthy and every consumer of
    // `prunable` (staleness, orphan adoption) believes it. It answers about the LOCAL filesystem —
    // hence the remote refusal above, since `git` itself would route over ssh.
    //
    // The `{ ok, entries }` shape rides all the way out to the renderer on purpose: an `entries: []`
    // that came from a FAILED `git worktree list` is not "there are no worktrees", and the store on
    // the other side of this IPC would otherwise mark every bound group missing on one bad read.
    return worktreeOps.listWorktrees(git, repoPath, async (p) => fs.existsSync(p))
  }
  worktreeAdd(
    repoPath: string,
    wtPath: string,
    branch: string,
    baseRef: string,
    isNew: boolean
  ): Promise<worktreeOps.WorktreeOpResult> {
    // `wtPath` is computed from the LOCAL data dir, so adding it through a remote git would create a
    // worktree at a nonsense path on the host. Refuse (see `isRemoteRepo`).
    if (isRemoteRepo(repoPath)) return Promise.resolve(REMOTE_WORKTREE_REFUSAL())
    // Every caller's backstop (dialog, `open-worktree`, the issue card, a relay or browser client):
    // never into the repository's `.git`, never REDIRECTED by a symlink into a hidden folder of the
    // home directory (see `worktree-target.ts`). Judged on real paths, which no renderer can see.
    const refusal = worktreeTargetRefusal(wtPath, repoPath)
    if (refusal) return Promise.resolve({ ok: false, message: refusal })
    return worktreeOps.worktreeAdd(git, repoPath, wtPath, branch, baseRef, isNew)
  }
  worktreeMerge(
    repoPath: string,
    branch: string,
    baseRef: string,
    push = false
  ): Promise<worktreeOps.WorktreeOpResult> {
    if (isRemoteRepo(repoPath)) return Promise.resolve(REMOTE_WORKTREE_REFUSAL())
    // `pathExists` is git's `prunable` flag's fallback for git < 2.36 (see worktree-ops) — and the
    // only thing that stops a merge into a base checkout whose directory is gone. LOCAL-only: see
    // `isRemoteRepo` for why a remote repo is refused above instead of stat'd here.
    return worktreeOps.worktreeMerge(git, repoPath, branch, baseRef, push, async (p) => fs.existsSync(p))
  }
  worktreeRemove(
    repoPath: string,
    wtPath: string,
    deleteBranch: boolean,
    pruneOnly = false
  ): Promise<worktreeOps.WorktreeOpResult> {
    // Refuse — and note what the refusal does NOT say: `worktreeGone`. A local stat of a remote
    // worktree would claim exactly that, and the renderer treats it as proof the directory is gone.
    if (isRemoteRepo(repoPath)) return Promise.resolve(REMOTE_WORKTREE_REFUSAL())
    // `pathExists` is git's `prunable` flag's fallback for git < 2.36 (see worktree-ops). LOCAL-only
    // (see `isRemoteRepo`).
    return worktreeOps.worktreeRemove(git, repoPath, wtPath, os.homedir(), deleteBranch, pruneOnly, async (p) =>
      fs.existsSync(p)
    )
  }

  async status(cwd: string): Promise<GitStatus> {
    const empty: GitStatus = {
      hasRepo: false,
      repoName: '',
      branch: '',
      branches: [],
      ahead: 0,
      behind: 0,
      hasRemote: false,
      hasOrigin: false,
      hasUpstream: false,
      ghAvailable: ghRunnable(),
      ghAuthed: false,
      staged: [],
      changes: []
    }
    if (!cwd) return empty

    const inside = await git(cwd, ['rev-parse', '--is-inside-work-tree'])
    if (!inside.ok || inside.out.trim() !== 'true') {
      return { ...empty, repoName: path.basename(cwd) }
    }

    // These reads are independent of each other; run them concurrently instead of
    // serially spawning ~10 git processes one after the next. (`remote get-url origin`
    // simply fails to empty when there's no origin, so it needn't wait on `remote`.)
    // gh auth is deliberately NOT awaited here (ghAuthedSwr): it hits the GitHub API and
    // used to hold the whole status — i.e. the panel's first paint — hostage for ~700ms.
    const [branchR, branchesR, remoteBranchesR, remotesR, originR, countsR, upstreamR, cachedR, workR, porcelainR] =
      await Promise.all([
        git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD']),
        git(cwd, ['branch', '--format=%(refname:short)']),
        git(cwd, ['branch', '-r', '--format=%(refname:short)']),
        git(cwd, ['remote']),
        git(cwd, ['remote', 'get-url', 'origin']),
        git(cwd, ['rev-list', '--left-right', '--count', '@{upstream}...HEAD']),
        // Resolves only when the current branch has an upstream tracking ref —
        // distinguishes "never pushed (Publish Branch)" from "has upstream (Push/Pull/Sync)".
        git(cwd, ['rev-parse', '--abbrev-ref', '--symbolic-full-name', '@{upstream}']),
        git(cwd, ['diff', '--cached', '--numstat']),
        git(cwd, ['diff', '--numstat']),
        // -uall forces git to list every untracked file individually instead of collapsing an
        // entirely-untracked directory into one `?? dir/` entry (issue: SC panel showed a folder
        // row that, when clicked, opened a diff node against a directory). Still respects .gitignore.
        git(cwd, ['status', '--porcelain', '-uall'])
      ])
    const gh = ghAuthedSwr()

    const branch = branchR.out.trim() || 'HEAD'
    const branches = branchesR.out.split('\n').map((b) => b.trim()).filter(Boolean)
    // `<remote>/HEAD` is a symref to the remote's default branch, not a branch of its own.
    const remoteBranches = remoteBranchesR.out
      .split('\n')
      .map((b) => b.trim())
      .filter((b) => b && !/\/HEAD$/.test(b))
    const hasRemote = !!remotesR.out.trim()
    const hasUpstream = upstreamR.ok && !!upstreamR.out.trim()
    const originUrl = originR.out.trim()
    // `hasRemote` is true for ANY remote — a fork whose only remote is `upstream` included. Anything
    // that pushes to `origin` by name (the worktree merge does) must ask for origin itself.
    const hasOrigin = originR.ok && !!originUrl
    const repoName = originUrl ? parseRepoName(originUrl, path.basename(cwd)) : path.basename(cwd)

    let ahead = 0
    let behind = 0
    if (countsR.ok && countsR.out) {
      const [b, a] = countsR.out.trim().split(/\s+/)
      behind = Number(b) || 0
      ahead = Number(a) || 0
    }

    const cachedStat = parseNumstat(cachedR.out)
    const workStat = parseNumstat(workR.out)

    const staged: GitFileChange[] = []
    const changes: GitFileChange[] = []
    const porcelain = porcelainR.out
    for (const raw of porcelain.split('\n').filter(Boolean)) {
      const x = raw[0]
      const y = raw[1]
      let p = raw.slice(3)
      if (p.includes(' -> ')) p = p.split(' -> ')[1] // rename: use new path
      const unquoted = p.replace(/^"|"$/g, '')
      // Defense in depth against -uall: a directory-shaped entry (trailing '/') can never be
      // opened as a file diff, so drop it here rather than let it reach the diff-node click path.
      if (unquoted.endsWith('/')) continue

      if (x === '?' && y === '?') {
        changes.push({ path: unquoted, status: 'U', added: 0, deleted: 0 })
        continue
      }
      if (x !== ' ' && x !== '?') {
        const s = cachedStat.get(unquoted)
        staged.push({ path: unquoted, status: x, added: s?.added ?? 0, deleted: s?.deleted ?? 0 })
      }
      if (y !== ' ' && y !== '?') {
        const s = workStat.get(unquoted)
        changes.push({ path: unquoted, status: y, added: s?.added ?? 0, deleted: s?.deleted ?? 0 })
      }
    }

    return {
      hasRepo: true,
      repoName,
      branch,
      branches,
      remoteBranches,
      ahead,
      behind,
      hasRemote,
      hasOrigin,
      hasUpstream,
      ghAvailable: ghRunnable(),
      ghAuthed: gh,
      staged,
      changes
    }
  }

  async diff(cwd: string, p: string, staged: boolean, untracked: boolean): Promise<string> {
    if (!cwd || !p) return ''
    if (untracked) {
      // No-index diff against /dev/null shows the whole file as additions (exits 1).
      const r = await git(cwd, ['diff', '--no-index', '--', '/dev/null', p])
      return r.out || r.err
    }
    const args = staged ? ['diff', '--cached', '--', p] : ['diff', '--', p]
    const r = await git(cwd, args)
    return r.out
  }

  async discard(cwd: string, p: string, untracked: boolean): Promise<GitResult> {
    if (untracked) {
      const r = await git(cwd, ['clean', '-f', '--', p])
      return r.ok ? { ok: true, message: '' } : fail(r)
    }
    const r = await git(cwd, ['restore', '--source=HEAD', '--staged', '--worktree', '--', p])
    return r.ok ? { ok: true, message: '' } : fail(r)
  }

  async switchBranch(cwd: string, name: string): Promise<GitResult> {
    if (!isValidRef(name)) return { ok: false, message: 'Invalid branch name.' }
    const r = await git(cwd, ['switch', name.trim()])
    return r.ok ? { ok: true, message: `Switched to ${name.trim()}.` } : fail(r)
  }

  async showFile(cwd: string, ref: string, p: string): Promise<string> {
    if (!cwd || !p) return ''
    const spec = ref ? `${ref}:${p}` : `:${p}`
    const r = await git(cwd, ['show', spec])
    return r.ok ? r.out : ''
  }

  async history(cwd: string, options?: GitHistoryOptions | null): Promise<GitHistoryResult> {
    // A default parameter is not enough: over WS-RPC (Server Edition) the args array is
    // JSON-round-tripped, so the renderer's trailing `undefined` arrives as `null` and the default
    // never fires. Normalize explicitly, or every history call throws in the browser.
    const opts = options ?? {}
    if (!cwd) {
      return { items: [], hasIncomingChanges: false, hasOutgoingChanges: false, hasMore: false, limit: opts.limit ?? 50 }
    }
    // Adapt the shared executor (throws on failure) onto the ssh-routing `git()` runner — NOT a
    // direct local `run('git', …)`: for an SSH project the scope cwd is a REMOTE path, and local
    // git against it fails every history load (or, if the path happens to exist here, serves the
    // wrong machine's history). `git()` returns {ok,…} instead of throwing, so re-raise on !ok —
    // the loader's per-probe catches (upstream ref, merge-base, …) rely on failures throwing.
    return loadGitHistoryFromExecutor(
      async (args, dir) => {
        const r = await git(dir, args)
        if (!r.ok) throw new Error(r.err || `git ${args[0] ?? ''} failed`)
        return { stdout: r.out }
      },
      cwd,
      opts
    )
  }

  /** Files changed by a single commit (parent↔commit; `--root` so the initial commit shows). */
  async commitFiles(cwd: string, oid: string): Promise<GitFileChange[]> {
    if (!cwd || !/^[0-9a-fA-F]{7,64}$/.test(oid)) return []
    const [namesR, statR] = await Promise.all([
      git(cwd, ['diff-tree', '--no-commit-id', '--root', '-r', '-z', '--name-status', oid]),
      git(cwd, ['diff-tree', '--no-commit-id', '--root', '-r', '--numstat', oid])
    ])
    const stat = parseNumstat(statR.out)
    const files: GitFileChange[] = []
    const tokens = namesR.out.split('\0').filter(Boolean)
    for (let i = 0; i < tokens.length; ) {
      const status = tokens[i]![0] ?? 'M'
      if (status === 'R' || status === 'C') {
        const newPath = tokens[i + 2] ?? ''
        const s = stat.get(newPath)
        files.push({ path: newPath, status, added: s?.added ?? 0, deleted: s?.deleted ?? 0 })
        i += 3
      } else {
        const p = tokens[i + 1] ?? ''
        const s = stat.get(p)
        files.push({ path: p, status, added: s?.added ?? 0, deleted: s?.deleted ?? 0 })
        i += 2
      }
    }
    return files
  }

  /** Read the origin through the same local or managed-SSH git executor as every other git read. */
  async originUrl(cwd: string): Promise<string | null> {
    if (!cwd) return null
    const result = await git(cwd, ['remote', 'get-url', 'origin'])
    const url = result.out.trim()
    return result.ok && url ? url : null
  }

  /** Build a provider web URL for a commit from the origin remote; null if unsupported. */
  async remoteCommitUrl(cwd: string, sha: string): Promise<string | null> {
    if (!cwd || !/^[0-9a-fA-F]{7,64}$/.test(sha)) return null
    const r = await git(cwd, ['remote', 'get-url', 'origin'])
    if (!r.ok) return null
    const url = r.out.trim()
    const m =
      url.match(/^git@([^:]+):(.+?)(?:\.git)?$/) ||
      url.match(/^ssh:\/\/(?:[^@]+@)?([^/]+)\/(.+?)(?:\.git)?$/) ||
      url.match(/^https?:\/\/(?:[^@]+@)?([^/]+)\/(.+?)(?:\.git)?$/)
    if (!m) return null
    const host = m[1]
    const repoPath = m[2]
    if (/(^|\.)github\.com$/.test(host) || /(^|\.)gitlab\.com$/.test(host)) {
      return `https://${host}/${repoPath}/commit/${sha}`
    }
    if (/(^|\.)bitbucket\.org$/.test(host)) {
      return `https://${host}/${repoPath}/commits/${sha}`
    }
    return null
  }

  async createBranch(cwd: string, name: string): Promise<GitResult> {
    if (!name.trim()) return { ok: false, message: 'Branch name is empty.' }
    if (!isValidRef(name)) return { ok: false, message: 'Invalid branch name.' }
    const r = await git(cwd, ['switch', '-c', name.trim()])
    return r.ok ? { ok: true, message: `Created ${name.trim()}.` } : fail(r)
  }

  async merge(cwd: string, ref: string): Promise<GitResult> {
    if (!isValidRef(ref)) return { ok: false, message: 'Invalid branch name.' }
    const r = await git(cwd, ['merge', ref.trim()])
    return r.ok ? { ok: true, message: r.out || `Merged ${ref.trim()}.` } : fail(r)
  }

  async rebase(cwd: string, onto: string): Promise<GitResult> {
    if (!isValidRef(onto)) return { ok: false, message: 'Invalid branch name.' }
    const r = await git(cwd, ['rebase', onto.trim()])
    return r.ok ? { ok: true, message: r.out || `Rebased onto ${onto.trim()}.` } : fail(r)
  }

  async deleteBranch(cwd: string, name: string, force: boolean): Promise<GitResult> {
    if (!isValidRef(name)) return { ok: false, message: 'Invalid branch name.' }
    const r = await git(cwd, ['branch', force ? '-D' : '-d', name.trim()])
    return r.ok ? { ok: true, message: `Deleted ${name.trim()}.` } : fail(r)
  }

  async renameBranch(cwd: string, newName: string): Promise<GitResult> {
    if (!isValidRef(newName)) return { ok: false, message: 'Invalid branch name.' }
    const r = await git(cwd, ['branch', '-m', newName.trim()])
    return r.ok ? { ok: true, message: `Renamed to ${newName.trim()}.` } : fail(r)
  }

  async fetch(cwd: string): Promise<GitResult> {
    const r = await git(cwd, ['fetch', '--all', '--prune'])
    return r.ok ? { ok: true, message: r.out || 'Fetched.' } : fail(r)
  }

  async forcePush(cwd: string): Promise<GitResult> {
    const r = await git(cwd, ['push', '--force-with-lease'])
    return r.ok ? { ok: true, message: 'Force-pushed.' } : fail(r)
  }

  async stashPush(cwd: string): Promise<GitResult> {
    const r = await git(cwd, ['stash', 'push', '-u'])
    return r.ok ? { ok: true, message: r.out || 'Stashed.' } : fail(r)
  }

  async stashPop(cwd: string): Promise<GitResult> {
    const r = await git(cwd, ['stash', 'pop'])
    return r.ok ? { ok: true, message: r.out || 'Popped stash.' } : fail(r)
  }

  async revert(cwd: string, oid: string): Promise<GitResult> {
    if (!/^[0-9a-fA-F]{7,64}$/.test(oid)) return { ok: false, message: 'Invalid commit.' }
    const r = await git(cwd, ['revert', '--no-edit', oid])
    return r.ok ? { ok: true, message: r.out || 'Reverted.' } : fail(r)
  }

  async branchAt(cwd: string, name: string, oid: string): Promise<GitResult> {
    if (!isValidRef(name)) return { ok: false, message: 'Invalid branch name.' }
    if (!/^[0-9a-fA-F]{7,64}$/.test(oid)) return { ok: false, message: 'Invalid commit.' }
    const r = await git(cwd, ['switch', '-c', name.trim(), oid])
    return r.ok ? { ok: true, message: `Created ${name.trim()}.` } : fail(r)
  }

  async checkoutCommit(cwd: string, oid: string): Promise<GitResult> {
    if (!/^[0-9a-fA-F]{7,64}$/.test(oid)) return { ok: false, message: 'Invalid commit.' }
    const r = await git(cwd, ['checkout', '--detach', oid])
    return r.ok ? { ok: true, message: `Checked out ${oid.slice(0, 7)} (detached).` } : fail(r)
  }

  /**
   * Clone a repo into parentDir with live progress (IPC.gitCloneProgress) and abort
   * support. Resolves at the END of the clone; success message = the cloned path.
   * The target dir is claimed with a non-recursive mkdir: EEXIST is a friendly error,
   * and on failure/abort we only ever delete the directory WE created this run.
   */
  async clone(parentDir: string, rawUrl: string): Promise<GitResult> {
    if (activeClone) return { ok: false, message: 'A clone is already running.' }
    const url = expandCloneUrl(rawUrl ?? '')
    if (!parentDir || !url) return { ok: false, message: 'Folder and URL are required.' }
    if (!isValidCloneUrl(url)) return { ok: false, message: 'Invalid repository URL.' }
    const dirName = deriveRepoDirName(url)
    if (!dirName) return { ok: false, message: 'Could not derive a folder name from that URL.' }
    const clonePath = path.join(parentDir, dirName)
    // Reserve the single-flight slot synchronously, BEFORE the mkdir await, so a
    // concurrent clone() can't slip past the guard during the await. child is filled
    // in once spawned; cloneAbort() guards against the null window.
    const rec: ActiveClone = { child: null, clonePath, aborted: false }
    activeClone = rec
    try {
      await fs.promises.mkdir(clonePath) // non-recursive claim; also validates parent exists
    } catch (e) {
      activeClone = null
      const err = e as NodeJS.ErrnoException
      if (err.code === 'EEXIST') {
        return {
          ok: false,
          message: `Destination already exists: ${clonePath}. Pick another folder or open it directly.`
        }
      }
      return { ok: false, message: `Cannot create ${clonePath}: ${err.message}` }
    }
    return await new Promise<GitResult>((resolve) => {
      const child = spawn('git', ['clone', '--progress', '--', url, clonePath], {
        cwd: parentDir,
        env: GIT_ENV,
        stdio: ['ignore', 'ignore', 'pipe']
      })
      rec.child = child
      let tail = '' // last 4 KB of stderr for the error message
      child.stderr?.on('data', (d: Buffer) => {
        const text = d.toString('utf-8')
        tail = (tail + text).slice(-4096)
        const p = parseCloneProgress(text)
        if (p) platform().broadcast(IPC.gitCloneProgress, p)
      })
      // Failure/abort: remove the dir we claimed (never anything pre-existing).
      const finishFail = (message: string): void => {
        activeClone = null
        void fs.promises.rm(clonePath, { recursive: true, force: true })
        resolve({ ok: false, message })
      }
      child.on('error', (e) => finishFail(`git could not start: ${e.message}`))
      child.on('close', (code) => {
        if (rec.aborted) return finishFail('aborted')
        if (code === 0) {
          activeClone = null
          resolve({ ok: true, message: clonePath })
          return
        }
        const clean = stripAnsiCodes(tail)
        const lines = clean.split('\n').map((l) => l.trim()).filter(Boolean)
        const fatal = [...lines].reverse().find((l) => /^(fatal|error):/i.test(l))
        finishFail(fatal ?? lines.pop() ?? 'Clone failed.')
      })
    })
  }

  /** Abort the in-flight clone (no-op when idle). */
  cloneAbort(): void {
    if (!activeClone) return
    activeClone.aborted = true
    // child may be null during the reservation→spawn window; the close handler still
    // honors `aborted` once the process starts.
    activeClone.child?.kill('SIGTERM')
  }

  /** ~/projects when present, else the home dir. */
  cloneDefaultParent(): string {
    const p = path.join(os.homedir(), 'projects')
    try {
      if (fs.statSync(p).isDirectory()) return p
    } catch {
      /* fall through */
    }
    return os.homedir()
  }

  async init(cwd: string): Promise<GitResult> {
    if (!cwd) return { ok: false, message: 'No project folder set.' }
    const r = await git(cwd, ['init', '-b', 'main'])
    return r.ok ? { ok: true, message: 'Initialized repository.' } : fail(r)
  }

  async stage(cwd: string, paths: string[]): Promise<GitResult> {
    if (paths.length === 0) return { ok: true, message: '' }
    const r = await git(cwd, ['add', '--', ...paths])
    return r.ok ? { ok: true, message: '' } : fail(r)
  }

  async unstage(cwd: string, paths: string[]): Promise<GitResult> {
    if (paths.length === 0) return { ok: true, message: '' }
    const r = await git(cwd, ['restore', '--staged', '--', ...paths])
    return r.ok ? { ok: true, message: '' } : fail(r)
  }

  async stageAll(cwd: string): Promise<GitResult> {
    const r = await git(cwd, ['add', '-A'])
    return r.ok ? { ok: true, message: '' } : fail(r)
  }

  async unstageAll(cwd: string): Promise<GitResult> {
    const r = await git(cwd, ['reset'])
    return r.ok ? { ok: true, message: '' } : fail(r)
  }

  async commit(cwd: string, message: string): Promise<GitResult> {
    if (!message.trim()) return { ok: false, message: 'Commit message is empty.' }
    const c = await git(cwd, ['commit', '-m', message])
    return c.ok ? { ok: true, message: c.out || 'Committed.' } : fail(c)
  }

  async push(cwd: string): Promise<GitResult> {
    const r = await git(cwd, ['push'])
    if (r.ok) return { ok: true, message: 'Pushed.' }
    if (/no upstream|has no upstream|set-upstream/i.test(r.err)) {
      const branch = (await git(cwd, ['rev-parse', '--abbrev-ref', 'HEAD'])).out.trim() || 'main'
      const up = await git(cwd, ['push', '-u', 'origin', branch])
      return up.ok ? { ok: true, message: 'Pushed (set upstream).' } : fail(up)
    }
    return fail(r)
  }

  async pull(cwd: string): Promise<GitResult> {
    const r = await git(cwd, ['pull'])
    return r.ok ? { ok: true, message: r.out || 'Pulled.' } : fail(r)
  }

  async sync(cwd: string): Promise<GitResult> {
    const pull = await this.pull(cwd)
    if (!pull.ok) return pull
    return this.push(cwd)
  }

  async publish(cwd: string, name: string, isPrivate: boolean): Promise<GitResult> {
    const repo = (name || '').trim()
    // GitHub repo names (optionally `owner/repo`) are limited to these chars and
    // must not start with `-`, so gh can't read the value as an option flag.
    if (!repo || repo.startsWith('-') || !/^[A-Za-z0-9._/-]+$/.test(repo)) {
      return { ok: false, message: 'Invalid repository name.' }
    }
    const invocation = ghInvocation([
      'repo',
      'create',
      repo,
      isPrivate ? '--private' : '--public',
      '--source=.',
      '--push'
    ])
    if (!invocation) return { ok: false, message: 'GitHub CLI (gh) not found.' }
    // Prefer gh's own login; otherwise reuse the user's existing git HTTPS token
    // (the one that already lets them push) so publishing doesn't demand a separate
    // `gh auth login`. If neither is available, signal the UI to start a login.
    const env: NodeJS.ProcessEnv = { ...GIT_ENV }
    // A cached "not signed in" is re-asked here: publish is user-initiated, and the Source Control
    // panel retries it right after running `gh auth login` in a terminal — trusting a 10-minute-old
    // negative would make that retry fail for the rest of the TTL.
    if (!(await ghAuthed({ recheckNegative: true }))) {
      const token = await githubTokenFromGitCredentials(cwd)
      if (!token) {
        return { ok: false, message: 'Sign in to GitHub to publish.', needsAuth: true }
      }
      env.GH_TOKEN = token
    }
    try {
      await run(invocation.executable, invocation.args, {
        ...invocation.options,
        cwd,
        env,
        maxBuffer: 10 * 1024 * 1024
      })
      return { ok: true, message: 'Published to GitHub.' }
    } catch (e) {
      const err = e as { stderr?: string; message?: string }
      const msg = (err.stderr || err.message || 'gh failed').trim()
      // A reused token without repo-create scope (or an expired one) reads as an auth
      // failure — let the UI offer a full login rather than a dead-end error.
      if (/\b(401|403)\b|unauthor|forbidden|auth|token|scope|HTTP 4/i.test(msg)) {
        return { ok: false, message: msg, needsAuth: true }
      }
      return { ok: false, message: msg }
    }
  }
}

function fail(e: Exec): GitResult {
  return { ok: false, message: e.err || e.out || 'git command failed' }
}