dsh-ide-git 0.23.0 → 0.25.0

package/src/host/read.js

@@ -0,0 +1,348 @@
+/** dsh-ide-git host: read-only methods (status, log, detail, diff, compare). */
+
+import path from 'node:path'
+
+import { PanelError, badRequest, cwdOf, requireRef, requireRelativePath, clampInt } from './core.js'
+
+import {
+
+  git, runGit, repoRootOf, parseLog, LOG_FORMAT, decorate, parsePorcelain, classify, numstatOf,
+
+  ignoredEntriesOf, stashCountOf, worktreesOf, currentBranchOf, upstreamOf,
+
+  aheadBehindOf, originNameOf, sameDirectory, FIELD_SEP, RECORD_SEP,
+
+  MAX_DIFF_CHARS, gitLog, GIT_LOG_MAX_ENTRIES,
+
+} from './git.js'
+
+import { operationOf } from './undo.js'
+
+
+
+async function summary(payload) {
+  const cwd = cwdOf(payload)
+  const root = await repoRootOf(cwd, payload)
+  /* Two-phase changes (issue #11): with `stats: false` the two `diff
+     --numstat` passes — the most expensive step once a tree holds thousands
+     of changes — are skipped, `statsDeferred: true` announces that the +/-
+     numbers arrive through the `stats` method instead. The rows themselves
+     are complete without them; nothing is truncated. */
+  const deferStats = payload.stats === false
+  /* The branch chain (branch → upstream → ahead/behind) is sequential by
+     necessity; everything else is independent and runs concurrently, so a
+     large `status` scan no longer serialises behind five cheap calls
+     (issue #11: the sum of ~ten sequential commands became the max of two
+     chains). */
+  const [branchInfo, statusOut, unstagedStat, stagedStat, ignored, stashCount, worktrees, operation, head, originName] = await Promise.all([
+    (async () => {
+      const branch = await currentBranchOf(root)
+      const detached = branch === 'HEAD'
+      const upstream = detached ? null : await upstreamOf(root, branch)
+      const tracking = upstream === null ? { ahead: 0, behind: 0 } : await aheadBehindOf(root, upstream, branch)
+      return { branch, detached, upstream, tracking }
+    })(),
+    git(root, ['status', '--porcelain=v1', '-z', '--untracked-files=all']),
+    deferStats ? Promise.resolve(new Map()) : numstatOf(root, []),
+    deferStats ? Promise.resolve(new Map()) : numstatOf(root, ['--cached']),
+    payload.ignored === true ? ignoredEntriesOf(root) : { entries: [], truncated: false },
+    stashCountOf(root),
+    worktreesOf(root),
+    operationOf(root),
+    /* HEAD hash (v0.18.7): lets the client's poll notice OUTSIDE commits and
+       checkouts — the panel's own actions already refresh everything, but
+       nothing else watches the repo. Empty string on an unborn branch. */
+    git(root, ['rev-parse', 'HEAD']).then((out) => out.trim()).catch(() => ''),
+    originNameOf(root),
+  ])
+  const groups = classify(parsePorcelain(statusOut))
+  return {
+    repoRoot: root,
+    cwd,
+    branch: branchInfo.branch,
+    detached: branchInfo.detached,
+    upstream: branchInfo.upstream,
+    ahead: branchInfo.tracking.ahead,
+    behind: branchInfo.tracking.behind,
+    head: head,
+    /* The repository's own name (v0.19.1): the origin URL's leaf, so a
+       renamed clone still shows the real repo name, not the folder's. */
+    origin: originName,
+    changes: {
+      staged: decorate(groups.staged, stagedStat),
+      unstaged: decorate(groups.unstaged, unstagedStat),
+      untracked: decorate(groups.untracked, new Map()),
+      conflicted: decorate(groups.conflicted, new Map()),
+      ignored: ignored.entries,
+      ignoredTruncated: ignored.truncated,
+    },
+    statsDeferred: deferStats === true,
+    stashCount: stashCount,
+    worktrees: worktrees,
+    operation: operation,
+  }
+}
+
+/* The second phase of the two-phase changes (issue #11): the two numstat
+   passes, concurrent, packed as [path, additions, deletions, binary] rows so
+   they survive JSON. Paths are post-rename paths — exactly what `summary`
+   decorates its entries with. Read-only: deliberately not in WRITE_METHODS. */
+async function stats(payload) {
+  const root = await repoRootOf(cwdOf(payload), payload)
+  const [unstaged, staged] = await Promise.all([
+    numstatOf(root, []),
+    numstatOf(root, ['--cached']),
+  ])
+  const pack = (map) => {
+    const rows = []
+    for (const [path, stat] of map) rows.push([path, stat.additions, stat.deletions, stat.binary === true])
+    return rows
+  }
+  return { unstaged: pack(unstaged), staged: pack(staged) }
+}
+
+async function branches(payload) {
+  const cwd = cwdOf(payload)
+  const root = await repoRootOf(cwd, payload)
+  const branch = await currentBranchOf(root)
+  const format = ['%(refname)', '%(refname:short)', '%(objectname)', '%(objectname:short)', '%(HEAD)', '%(upstream:short)', '%(committerdate:iso-strict)', '%(contents:subject)', '%(symref)'].join(FIELD_SEP)
+  const out = await git(root, ['for-each-ref', '--format=' + format + RECORD_SEP, 'refs/heads', 'refs/remotes', 'refs/tags'])
+  const local = []
+  const remote = []
+  const tags = []
+  const worktrees = await worktreesOf(root)
+  const busy = new Map()
+  for (const tree of worktrees) {
+    if (tree.branch === null || tree.branch === '') continue
+    // `git worktree list` includes the checkout this repository lives in, so
+    // without this the CURRENT branch was flagged as occupied by its own working
+    // tree (reported on v0.3.11: main showed the marker while checked out here).
+    // Only a SECOND working tree holding a branch blocks checking it out here.
+    if (sameDirectory(tree.path, root)) continue
+    busy.set(tree.branch, tree.path)
+  }
+  for (const record of out.split(RECORD_SEP)) {
+    const trimmed = record.replace(/^\n+/, '')
+    if (trimmed.trim() === '') continue
+    const parts = trimmed.split(FIELD_SEP)
+    if (parts.length < 9) continue
+    const entry = {
+      name: parts[1],
+      hash: parts[2],
+      shortHash: parts[3],
+      head: parts[4] === '*',
+      upstream: parts[5] === '' ? null : parts[5],
+      date: parts[6],
+      subject: parts[7],
+      worktree: busy.get(parts[1]) === undefined ? null : busy.get(parts[1]),
+      ahead: 0,
+      behind: 0,
+    }
+    if (parts[0].startsWith('refs/heads/')) local.push(entry)
+    else if (parts[0].startsWith('refs/remotes/')) {
+      /* "<remote>/HEAD" is the symbolic pointer at a remote's default branch —
+         its %(refname:short) collapses to the BARE remote name, so it is not a
+         branch anyone can check out. It never becomes a row (the stray
+         "<remote>" entry used to pollute the remote tree and, grouped, it also
+         defeated the tree's single-remote prefix strip). */
+      if (/^refs\/remotes\/[^/]+\/HEAD$/.test(parts[0]) === false) remote.push(entry)
+    }
+    else if (parts[0].startsWith('refs/tags/')) tags.push({ name: entry.name, hash: entry.hash, shortHash: entry.shortHash, date: entry.date, subject: entry.subject })
+  }
+  for (const entry of local) {
+    if (entry.upstream === null) continue
+    const tracking = await aheadBehindOf(root, entry.upstream, entry.name)
+    entry.ahead = tracking.ahead
+    entry.behind = tracking.behind
+  }
+  local.sort((a, b) => (a.head === b.head ? a.name.localeCompare(b.name) : a.head ? -1 : 1))
+  remote.sort((a, b) => a.name.localeCompare(b.name))
+  tags.sort((a, b) => a.name.localeCompare(b.name))
+  const remotesOut = await runGit(root, ['remote'])
+  const remotes = remotesOut.code === 0 ? remotesOut.stdout.split('\n').map((line) => line.trim()).filter((line) => line !== '') : []
+  return { repoRoot: root, branch, local, remote, tags, remotes }
+}
+
+async function log(payload) {
+  const cwd = cwdOf(payload)
+  const root = await repoRootOf(cwd, payload)
+  const limit = clampInt(payload.limit, 1, 500, 100)
+  const skip = clampInt(payload.skip, 0, 1_000_000, 0)
+  const args = ['log', '--max-count=' + (limit + 1), '--skip=' + skip, '--date-order', '--pretty=format:' + LOG_FORMAT]
+  if (typeof payload.rev === 'string' && payload.rev.trim() !== '') args.push(requireRef(payload.rev, 'rev'))
+  if (typeof payload.path === 'string' && payload.path.trim() !== '') args.push('--', payload.path)
+  const out = await git(root, args)
+  const all = parseLog(out)
+  const hasMore = all.length > limit
+  return { repoRoot: root, commits: hasMore ? all.slice(0, limit) : all, hasMore, skip, limit }
+}
+/* The merge that carried `from` INTO `to`, newest first — the anchor the
+   branch tree's double-click-to-browse lands on (IDEA-style: double-click
+   branch 2, then branch 1, and 1's list opens scrolled to the merge commit
+   where 2 was merged in, so "2 has been merged here" is visible at a
+   glance even though 1 kept moving. No merge relationship -> null, and the
+   caller just opens the list at the top. Pure rev arithmetic, no network. */
+/* Who am I here: git config resolves user.name/email through its usual
+   cascade (repo-local overrides global), so the answer is per repository.
+   The client caches it per repo root for the whole panel lifetime — a git
+   identity rarely changes mid-session — and pins it to the top of the
+   author filter (v0.19.3), even when this branch has no commits by me:
+   picking it and seeing an empty list IS the answer ("I never committed
+   here"). Empty strings mean no identity is configured. */
+async function me(payload) {
+  const cwd = cwdOf(payload)
+  const root = await repoRootOf(cwd, payload)
+  const name = await runGit(root, ['config', 'user.name'])
+  const email = await runGit(root, ['config', 'user.email'])
+  return {
+    repoRoot: root,
+    name: name.code === 0 ? name.stdout.trim() : '',
+    email: email.code === 0 ? email.stdout.trim() : '',
+  }
+}
+
+async function mergePoint(payload) {
+  const cwd = cwdOf(payload)
+  const root = await repoRootOf(cwd, payload)
+  const from = requireRef(payload.from, 'from')
+  const to = requireRef(payload.to, 'to')
+  const out = await git(root, ['rev-list', '--merges', '--ancestry-path', '--max-count=1', from + '..' + to])
+  const hash = out.trim().split('\n')[0] || ''
+  return { repoRoot: root, hash: hash === '' ? null : hash }
+}
+
+async function commitDetail(payload) {
+  const cwd = cwdOf(payload)
+  const root = await repoRootOf(cwd, payload)
+  const hash = requireRef(payload.hash, 'hash')
+  const metaFormat = ['%H', '%h', '%P', '%an', '%ae', '%aI', '%s', '%b', '%D'].join(FIELD_SEP)
+  const metaOut = await git(root, ['show', '-s', '--format=' + metaFormat, hash])
+  const parts = metaOut.trim().split(FIELD_SEP)
+  const parents = parts[2] === undefined || parts[2].trim() === '' ? [] : parts[2].trim().split(' ')
+  const numstatOut = await git(root, ['show', '--numstat', '-z', '--format=', '-m', '--first-parent', hash])
+  const files = []
+  const records = numstatOut.split('\u0000')
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index]
+    if (record === '') continue
+    const firstTab = record.indexOf('\t')
+    const secondTab = record.indexOf('\t', firstTab + 1)
+    if (firstTab < 0 || secondTab < 0) continue
+    let filePath = record.slice(secondTab + 1)
+    let origPath
+    if (filePath === '') {
+      origPath = records[index + 1]
+      filePath = records[index + 2]
+      index += 2
+    }
+    const addRaw = record.slice(0, firstTab)
+    const delRaw = record.slice(firstTab + 1, secondTab)
+    const binary = addRaw === '-' || delRaw === '-'
+    files.push({
+      path: filePath === undefined ? '' : filePath,
+      origPath: origPath === undefined || origPath === '' ? undefined : origPath,
+      additions: binary ? 0 : Number.parseInt(addRaw, 10) || 0,
+      deletions: binary ? 0 : Number.parseInt(delRaw, 10) || 0,
+      binary,
+    })
+  }
+  return {
+    hash: parts[0],
+    shortHash: parts[1],
+    parents,
+    author: parts[3],
+    email: parts[4],
+    date: parts[5],
+    subject: parts[6],
+    body: parts[7] === undefined ? '' : parts[7],
+    refs: parts[8] === undefined || parts[8].trim() === '' ? [] : parts[8].split(',').map((ref) => ref.trim()).filter((ref) => ref !== ''),
+    files,
+  }
+}
+
+async function diff(payload) {
+  const cwd = cwdOf(payload)
+  const root = await repoRootOf(cwd, payload)
+  /* Untracked files have no index entry, so plain `git diff [--cached] -- path`
+     is legitimately empty for them — the panel's change list still shows the
+     file and the preview must not go blank. `--no-index /dev/null <file>`
+     produces the honest "new file" patch; its exit code is 1 when differences
+     exist, which is data, not failure (only >1 rejects). */
+  if (payload.untracked === true) {
+    const rel = requireRelativePath(payload.path)
+    const absolute = path.isAbsolute(rel) ? rel : path.join(root, rel)
+    /* --no-index reads the file for real, so unlike the plain `git diff --`
+       form an absolute path must NOT be allowed to escape the repository. */
+    if (absolute !== root && !absolute.startsWith(root + path.sep)) throw badRequest('path must stay inside the repository')
+    /* git quotes and C-escapes backslash paths inside the diff header (and
+       git ≥2.55 spells the a/ side with the real path instead of /dev/null);
+       passing forward slashes keeps the header unquoted, so the rewrite below
+       can match it verbatim. POSIX is a no-op. */
+    const headerPath = absolute.split(path.sep).join('/')
+    const result = await runGit(root, ['diff', '--no-color', '--no-ext-diff', '-U3', '--no-index', '--', '/dev/null', headerPath])
+    if (result.code !== 0 && result.code !== 1) {
+      const detail = result.stderr.trim() === '' ? result.stdout.trim() : result.stderr.trim()
+      throw new PanelError('git-failed', 'git diff --no-index failed: ' + (detail === '' ? 'exit ' + result.code : detail), 409)
+    }
+    /* --no-index spells the b/ side with the absolute path we passed; rewrite
+       the header lines back to the repository-relative spelling so the preview
+       reads like every other patch (body lines are left untouched). */
+    let out = result.stdout
+    if (out.indexOf(headerPath) >= 0 && out.indexOf('\n') !== -1) {
+      out = out.split('\n').map((line) => {
+        if (line.startsWith('diff --git ') && line.indexOf(headerPath) >= 0) return 'diff --git a/' + rel + ' b/' + rel
+        /* git ≥2.55 quotes the header and spells the a/ side with the real
+           path instead of /dev/null, so match on the path, not the prefix. */
+        if (line.startsWith('+++ ') && line.indexOf(headerPath) >= 0) return '+++ b/' + rel
+        return line
+      }).join('\n')
+    }
+    const truncated = out.length > MAX_DIFF_CHARS
+    return { patch: truncated ? out.slice(0, MAX_DIFF_CHARS) : out, truncated }
+  }
+  const args = ['diff', '--no-color', '--no-ext-diff', '-U3']
+  if (payload.staged === true) args.push('--cached')
+  if (typeof payload.hash === 'string' && payload.hash.trim() !== '') {
+    args.length = 0
+    args.push('show', '--no-color', '--no-ext-diff', '-U3', '--format=', requireRef(payload.hash, 'hash'))
+  }
+  if (typeof payload.path === 'string' && payload.path.trim() !== '') args.push('--', requireRelativePath(payload.path))
+  const out = await git(root, args)
+  const truncated = out.length > MAX_DIFF_CHARS
+  return { patch: truncated ? out.slice(0, MAX_DIFF_CHARS) : out, truncated }
+}
+
+/* The tail of the git run ring buffer (see runGit). Read-only, global. */
+async function gitLogs() {
+  return { entries: gitLog.slice(-GIT_LOG_MAX_ENTRIES) }
+}
+
+async function compare(payload) {
+  const cwd = cwdOf(payload)
+  const root = await repoRootOf(cwd, payload)
+  const base = requireRef(payload.base, 'base')
+  const head = requireRef(payload.head, 'head')
+  const stat = await git(root, ['diff', '--numstat', '-z', base + '...' + head])
+  const files = []
+  const records = stat.split('\u0000')
+  for (let index = 0; index < records.length; index += 1) {
+    const record = records[index]
+    if (record === '') continue
+    const firstTab = record.indexOf('\t')
+    const secondTab = record.indexOf('\t', firstTab + 1)
+    if (firstTab < 0 || secondTab < 0) continue
+    const addRaw = record.slice(0, firstTab)
+    const delRaw = record.slice(firstTab + 1, secondTab)
+    const binary = addRaw === '-' || delRaw === '-'
+    files.push({
+      path: record.slice(secondTab + 1),
+      additions: binary ? 0 : Number.parseInt(addRaw, 10) || 0,
+      deletions: binary ? 0 : Number.parseInt(delRaw, 10) || 0,
+      binary,
+    })
+  }
+  const logOut = await git(root, ['log', '--max-count=100', '--date-order', '--pretty=format:' + LOG_FORMAT, base + '..' + head])
+  return { base, head, files, commits: parseLog(logOut) }
+}
+
+export { summary, stats, branches, log, me, mergePoint, commitDetail, diff, gitLogs, compare }

package/src/host/repos.js

@@ -0,0 +1,222 @@
+/** dsh-ide-git host: repository discovery for the picker, plus git --version. */
+
+import { existsSync, realpathSync, readdirSync } from 'node:fs'
+
+import path from 'node:path'
+
+import { cwdOf } from './core.js'
+
+import { runGit, originNameOf } from './git.js'
+
+
+
+/** Directories never descended into while looking for repositories. */
+const REPO_SCAN_SKIP = new Set(['node_modules', 'dist', 'build', 'out', 'target', 'vendor', 'venv', '.venv', '__pycache__', 'coverage', 'tmp', 'temp'])
+
+/* `git submodule status --recursive` already reports every nesting level of a
+   repository in ONE call (paths arrive fully qualified), so the submodule walk
+   costs exactly one `status` per checkout; the lists stay bounded so a
+   pathological tree cannot flood the picker. */
+const SUBMODULE_LIST_LIMIT = 400
+const REPO_LIST_LIMIT = 60
+
+/** Slash-normalized path, for comparing paths that came from different
+ *  producers (git prints forward slashes; `path.join` prints backslashes on
+ *  Windows). Case-insensitive on Windows so the same checkout reached two ways
+ *  collapses to one row. */
+function pathIdentity(value) {
+  const normalized = value.replace(/\\/g, '/').replace(/\/+$/, '')
+  const key = process.platform === 'win32' ? normalized.toLowerCase() : normalized
+  /* realpath collapses producer spellings of one checkout: git's
+   * --show-toplevel resolves symlinks (/private/var on macOS) while a
+   * directory walk keeps the spelling it was handed (/var), and without this
+   * the same submodule arrived as two rows. An unresolvable path falls back
+   * to the slash-normalized form. */
+  try {
+    return realpathSync(key).replace(/\\/g, '/').replace(/\/+$/, '')
+  } catch {
+    return key
+  }
+}
+
+/** One repository row shipped to the client (`kind` drives the picker badge). */
+function repoRow(root, submodulePath, kind) {
+  return {
+    path: root.replace(/\\/g, '/'),
+    /** Full checkout name; a submodule carries its repo-relative path so two
+     *  same-named checkouts stay apart in a long list. */
+    name: submodulePath === undefined ? path.basename(root) : submodulePath,
+    label: submodulePath === undefined ? path.basename(root) : submodulePath.split('/').pop(),
+    branch: null,
+    /** The checkout's own repository name, cut from its origin URL (v0.19.2):
+     *  the picker shows this first and falls back to the directory name, with
+     *  the directory name as the small sub line whenever the two differ — so
+     *  two clones of one repository stay tellable apart. Filled in by the
+     *  scan below (an origin-less checkout keeps the empty string). */
+    origin: '',
+    kind,
+    ...(submodulePath === undefined ? {} : { submodulePath }),
+  }
+}
+
+/**
+ * Every checkout registered as a submodule under `root`, at any depth.
+ *
+ * Git itself is the source of truth: `git submodule status --recursive` lists
+ * the registered paths (relative to the parent repository) even for submodules
+ * that were never initialised, and `--recursive` walks EVERY nesting level in
+ * that one call — deeper entries arrive as fully qualified paths
+ * ("outer/inner"), so one `status` per checkout is the whole discovery. (An
+ * earlier revision also re-ran `status` inside every confirmed submodule; those
+ * calls could only re-list checkouts the recursive pass had already reported,
+ * which multiplied the process count on a workspace full of checkouts without
+ * producing a single new row.) A path that is present on disk and passes
+ * `rev-parse --show-toplevel` is a real, independent working tree — the parent
+ * only ever sees it as one gitlink line, so this is what makes it selectable
+ * as a repository of its own (the SourceTree behavior).
+ *
+ * The working-tree checks all run at once, because a repository with a dozen
+ * submodules otherwise costs a dozen sequential processes on every scan.
+ */
+async function collectSubmoduleRepos(root) {
+  const found = []
+  const listing = await runGit(root, ['submodule', 'status', '--recursive'])
+  if (listing.code !== 0) return found
+  const candidates = []
+  for (const raw of listing.stdout.split('\n')) {
+    if (candidates.length >= SUBMODULE_LIST_LIMIT) break
+    const line = raw.replace(/\r$/, '')
+    if (line.trim() === '') continue
+    /* `<state><sha> <path> (<describe>)`: the state prefix is ' ', '+', '-' or 'U'. */
+    const match = /^[\s+\-U]([0-9a-f]{4,64})\s+(.+?)(?:\s+\(.*\))?$/.exec(line)
+    const rel = (match === null ? line.trim().replace(/^[\s+\-U]\S*\s+/, '') : match[2]).trim().replace(/\\/g, '/')
+    if (rel === '') continue
+    const absolute = path.resolve(root, rel)
+    /* An uninitialised submodule has no `.git` yet: git still registers it, but
+       there is no working tree to bind the panel to. */
+    if (!existsSync(path.join(absolute, '.git'))) continue
+    candidates.push({ absolute, rel })
+  }
+  const tops = await Promise.all(candidates.map((entry) => runGit(entry.absolute, ['rev-parse', '--show-toplevel'])))
+  for (let index = 0; index < candidates.length; index += 1) {
+    const top = tops[index]
+    if (top.code !== 0) continue
+    const reported = top.stdout.trim().replace(/\\/g, '/').replace(/\/+$/, '')
+    found.push({ root: reported === '' ? candidates[index].absolute : reported, rel: candidates[index].rel })
+  }
+  return found
+}
+
+/* The whole discovery pass is cached in-process per cwd: one scan walks the
+   tree and spawns a git process per checkout, while the client re-POSTs `repos`
+   on every panel mount — a warm answer is what keeps switching back to the Git
+   page instant on a workspace full of checkouts. Entries are { at, rows };
+   REPOS_CACHE_TTL_MS is a module-level `let` so tests can pin it to 0 and
+   observe the always-rescan path.
+
+   The cache is deliberately NOT invalidated when a write method succeeds:
+   `repos` is a read-only discovery of which checkouts EXIST, and no write
+   method changes that set — a commit or a new branch does not conjure a
+   repository. A clone landing inside the 15s window simply stays invisible
+   until the next scan; that is an accepted trade, the client's background
+   refresh is the safety net. */
+export const repoScanCache = new Map()
+export let REPOS_CACHE_TTL_MS = 15000
+
+async function scanRepos(cwd) {
+  const cached = repoScanCache.get(cwd)
+  /* Hand back fresh row objects: the cache is shared by every caller, and a
+     consumer that decorates or reorders what it received must not write
+     through into the next request's answer. */
+  if (cached !== undefined && Date.now() - cached.at < REPOS_CACHE_TTL_MS) {
+    return { cached: true, rows: cached.rows.map((row) => ({ ...row })) }
+  }
+  const list = []
+  const self = await runGit(cwd, ['rev-parse', '--show-toplevel'])
+  const isRepo = self.code === 0
+  if (isRepo) {
+    const top = self.stdout.trim()
+    list.push(repoRow(top === '' ? cwd : top, undefined, 'workspace'))
+  }
+  for (const dir of findNestedRepos(cwd, 2)) list.push(repoRow(dir, undefined, 'nested'))
+  /* Submodules of EVERY discovered checkout, not only a workspace that is one:
+     a container workspace (a folder holding several checkouts — the usual
+     shape of a multi-repo project) reaches its repositories through the rows
+     above, and each of those may carry submodules of its own. Without this
+     pass the picker lists `eis` but none of the eight checkouts under it.
+     These rows are built LAST and the map below lets them win: the directory
+     scan can reach the same checkout through a plain path (a submodule whose
+     parent directory is not itself a repository), and the submodule row is the
+     better one — its name carries the repo-relative path. */
+  const roots = list.map((row) => row.path)
+  const submoduleLists = await Promise.all(roots.map((root) => collectSubmoduleRepos(root)))
+  for (const entries of submoduleLists) {
+    for (const entry of entries) list.push(repoRow(entry.root, entry.rel, 'nested'))
+  }
+  const byIdentity = new Map()
+  for (const row of list) byIdentity.set(pathIdentity(row.path), row)
+  const rows = [...byIdentity.values()]
+  rows.sort((a, b) => (a.kind === b.kind ? a.path.localeCompare(b.path) : a.kind === 'workspace' ? -1 : 1))
+  const capped = rows.slice(0, REPO_LIST_LIMIT).map((row) => ({ ...row }))
+  const branches = await Promise.all(capped.map((row) => branchOrNull(row.path)))
+  for (let index = 0; index < capped.length; index += 1) capped[index].branch = branches[index]
+  /* Origin names ride the same one-call-per-row pass as the branches: a local
+     `git remote get-url` read, cheap, and the 15s cache means repeated picker
+     opens pay for it once. */
+  const origins = await Promise.all(capped.map((row) => originNameOf(row.path)))
+  for (let index = 0; index < capped.length; index += 1) capped[index].origin = origins[index]
+  repoScanCache.set(cwd, { at: Date.now(), rows: capped })
+  return { cached: false, rows: capped.map((row) => ({ ...row })) }
+}
+
+/** Depth-capped search for repositories nested in a workspace. */
+function findNestedRepos(root, maxDepth) {
+  const found = []
+  const walk = (dir, depth) => {
+    if (found.length >= 40 || depth > maxDepth) return
+    let entries
+    try { entries = readdirSync(dir, { withFileTypes: true }) } catch { return }
+    for (const entry of entries) {
+      if (!entry.isDirectory() || entry.name.startsWith('.') || REPO_SCAN_SKIP.has(entry.name)) continue
+      const child = path.join(dir, entry.name)
+      if (existsSync(path.join(child, '.git'))) { found.push(child); continue }
+      if (depth < maxDepth) walk(child, depth + 1)
+    }
+  }
+  walk(root, 1)
+  return found
+}
+
+async function branchOrNull(root) {
+  const result = await runGit(root, ['rev-parse', '--abbrev-ref', 'HEAD'])
+  if (result.code !== 0) return null
+  const name = result.stdout.trim()
+  return name === '' ? null : name
+}
+
+/**
+ * Repositories this panel may bind to: the session workspace itself when it is
+ * one, repositories nested inside it (a sandbox holding many checkouts), and
+ * the submodules of every checkout discovered that way — git records each
+ * submodule as its own working tree with its own HEAD, index and branches, so
+ * it is a repository the panel can bind to like any other. The client turns
+ * this into the repo picker, and picking a row is all it takes: every later
+ * call carries that path as `repoRoot`, which is the working directory the git
+ * commands run in.
+ */
+async function repos(payload) {
+  const cwd = cwdOf(payload)
+  const { cached, rows } = await scanRepos(cwd)
+  /* `cached: true` rides a cache hit only; the client ignores it today, it just
+     makes the answer say where it came from. */
+  return { cwd, isRepo: rows.some((row) => row.kind === 'workspace'), repos: rows, ...(cached ? { cached: true } : {}) }
+}
+
+async function version() {
+  const result = await runGit(process.cwd(), ['--version'])
+  const raw = result.code === 0 ? result.stdout.trim() : ''
+  const match = /git version (\S+)/.exec(raw)
+  return { git: match === null ? raw : match[1], available: result.code === 0 }
+}
+
+export { repos, version }