@danneillouven/remote-workspace 0.0.0-stage → 0.1.0

package/runtime/server/src/modules/git/git-service.js

@@ -0,0 +1,597 @@
+import path from 'node:path';
+import { AppError } from "../../lib/errors.js";
+import { normalizeWorkspacePath } from "../filesystem/workspace-path.js";
+import { isBinaryDiff, LOG_FORMAT, parseLog, parseNameStatus, parseNumstat, parsePorcelainV2, splitDiffHunks } from "./git-parsers.js";
+const STATUS_MAX_BYTES = 16 * 1024 * 1024;
+// Nested repositories: how deep to look below the project folder, how many to report,
+// and directories that never hold the user's own repositories but can be huge.
+const NESTED_MAX_DEPTH = 6;
+const NESTED_MAX_REPOSITORIES = 30;
+const NESTED_SKIP_DIRS = ['node_modules', '.venv', 'venv', '.cache', '.next', '.nuxt', '__pycache__', 'Pods', 'target', 'vendor', '.terraform'];
+const NESTED_CACHE_MS = 15_000;
+// Global options for every invocation:
+//  - --literal-pathspecs: file names are never interpreted as glob/magic pathspecs.
+//  - core.quotepath=off: keep non-ASCII names verbatim in human-readable diff headers.
+//  - --no-pager: never block on a pager.
+const GIT_BASE = ['git', '--no-pager', '--literal-pathspecs', '-c', 'core.quotepath=off', '-c', 'color.ui=false'];
+// `git stash` uses pathspec magic internally (with --literal-pathspecs, `stash -u` saves
+// untracked files but leaves them in place). Stash commands never take user paths.
+const STASH_BASE = GIT_BASE.filter((arg) => arg !== '--literal-pathspecs');
+// Avoid taking optional index locks so status never contends with Git
+// commands the user is running in a terminal at the same time.
+const GIT_ENV = { GIT_OPTIONAL_LOCKS: '0', GIT_TERMINAL_PROMPT: '0' };
+// --no-ext-diff/--no-textconv: never run repository-configured helper programs.
+const DIFF_FLAGS = ['--no-color', '--no-ext-diff', '--no-textconv'];
+// Commits can run hooks (lint, tests), so give them longer than inspection commands.
+const COMMIT_TIMEOUT_MS = 120_000;
+// Pull, push, fetch: remote round-trips plus hooks (pre-push).
+const NETWORK_TIMEOUT_MS = 180_000;
+// Never let a repository or remote opt into transports that run commands.
+const NETWORK_FLAGS = ['-c', 'protocol.ext.allow=never', '-c', 'protocol.fd.allow=never'];
+// Credentials embedded in remote URLs (https://user:token@host) must never reach the browser.
+const stripCredentials = (text) => text.replace(/([a-z][a-z0-9+.-]*:\/\/)[^/@\s]+@/gi, '$1');
+/** The Git subcommand in an argument list (skipping `-c name=value` pairs). */
+const commandName = (args) => args.find((arg, index) => !arg.startsWith('-') && args[index - 1] !== '-c') ?? '';
+/** The most useful line of Git's stderr: fatal/error lines beat progress and "To <url>" chatter. */
+function errorSummary(stderr) {
+    const lines = stderr.split('\n').map((line) => line.trim()).filter(Boolean);
+    const line = lines.find((entry) => /^(fatal|error):/i.test(entry)) ?? lines.find((entry) => entry.startsWith('! ')) ?? lines[0] ?? '';
+    return stripCredentials(line);
+}
+// occ's default: diffs beyond this are cut before they reach an AI backend.
+const COMMIT_CONTEXT_MAX_DIFF = 10_000;
+/**
+ * Git through the native Git CLI: inspection plus staging and committing. All
+ * commands are argv vectors handed to a CommandRunner; paths are validated and
+ * always passed after `--`, so no user input is ever interpreted as an option or a pattern.
+ */
+export class GitService {
+    #runner;
+    #options;
+    #nested = null;
+    constructor(runner, options) {
+        this.#runner = runner;
+        this.#options = options;
+    }
+    async #git(cwd, args, maxOutputBytes, okExitCodes = [0], timeoutMs, base = GIT_BASE, input) {
+        const result = await this.#runner.run([...base, ...args], { cwd, env: GIT_ENV, maxOutputBytes, timeoutMs, input });
+        if (result.exitCode === 127)
+            throw new AppError('GIT_ERROR', 'Git is not installed on the workspace host.');
+        // A truncated read stops the process early, so its exit status is meaningless.
+        const failed = !result.stdoutTruncated && (result.exitCode === null || !okExitCodes.includes(result.exitCode));
+        if (failed) {
+            if (/not a git repository/i.test(result.stderr))
+                throw new AppError('NOT_A_REPOSITORY', 'The workspace is not a Git repository.');
+            if (/please tell me who you are|empty ident name/i.test(result.stderr)) {
+                throw new AppError('GIT_ERROR', 'Git has no author identity on the workspace host: set user.name and user.email with git config.');
+            }
+            if (/dubious ownership/i.test(result.stderr)) {
+                throw new AppError('GIT_ERROR', 'Git refused the repository because of "dubious ownership" (see git config safe.directory).');
+            }
+            if (/^CONFLICT/m.test(result.stdout.toString('utf8'))) {
+                throw new AppError('GIT_ERROR', 'There are merge conflicts. Resolve them, stage the files, then commit (or abort).');
+            }
+            throw new AppError('GIT_ERROR', `git ${commandName(args)} failed: ${errorSummary(result.stderr)}`.trim());
+        }
+        return result;
+    }
+    /** The repository containing the workspace root, if any (it may start above the root). */
+    async #findRepository() {
+        try {
+            const result = await this.#git(this.#options.workspaceRoot, ['rev-parse', '--show-toplevel', '--show-prefix'], 64 * 1024);
+            const [topLevel = '', prefix = ''] = result.stdout.toString('utf8').split('\n');
+            return { path: '', topLevel, prefix };
+        }
+        catch (error) {
+            if (error instanceof AppError && error.code === 'NOT_A_REPOSITORY')
+                return null;
+            throw error;
+        }
+    }
+    /**
+     * Workspace-relative directories below the root that contain a `.git` entry
+     * (nested clones, submodules, worktrees). `find` never follows symlinks, so
+     * results stay inside the workspace. Cached briefly: status refreshes are frequent.
+     */
+    #discoverNested() {
+        if (this.#nested && Date.now() - this.#nested.at < NESTED_CACHE_MS)
+            return this.#nested.result;
+        const skip = NESTED_SKIP_DIRS.flatMap((name, index) => (index === 0 ? ['-name', name] : ['-o', '-name', name]));
+        const argv = ['find', '.', '-maxdepth', String(NESTED_MAX_DEPTH + 1), '(', ...skip, ')', '-prune', '-o', '-name', '.git', '-print0', '-prune'];
+        const result = this.#runner
+            .run(argv, { cwd: this.#options.workspaceRoot, maxOutputBytes: 1024 * 1024, timeoutMs: 15_000 })
+            .then((output) => {
+            // find exits 1 when some directories are unreadable but still prints what it found.
+            if (output.exitCode !== 0 && output.exitCode !== 1 && !output.stdoutTruncated)
+                return { paths: [], truncated: false };
+            const paths = output.stdout
+                .toString('utf8')
+                .split('\0')
+                .filter((entry) => entry.startsWith('./') && entry !== './.git')
+                .map((entry) => path.posix.dirname(entry.slice(2)))
+                .filter((entry) => entry !== '.' && !entry.split('/').includes('..'))
+                .sort((a, b) => a.localeCompare(b));
+            return { paths: paths.slice(0, NESTED_MAX_REPOSITORIES), truncated: output.stdoutTruncated || paths.length > NESTED_MAX_REPOSITORIES };
+        })
+            .catch(() => ({ paths: [], truncated: false }));
+        this.#nested = { at: Date.now(), result };
+        return result;
+    }
+    /**
+     * A nested repository by workspace-relative path. Git silently walks up to a
+     * parent repository when a `.git` entry is invalid, so the top level must be
+     * exactly the requested directory (this also rejects paths through symlinks).
+     */
+    async #nestedRepository(relativePath) {
+        const expected = path.posix.join(this.#options.workspaceRoot, relativePath);
+        try {
+            const result = await this.#git(expected, ['rev-parse', '--show-toplevel'], 64 * 1024);
+            const topLevel = result.stdout.toString('utf8').split('\n')[0] ?? '';
+            return topLevel === expected ? { path: relativePath, topLevel, prefix: '' } : null;
+        }
+        catch {
+            return null;
+        }
+    }
+    #toWorkspacePath(repository, repoPath) {
+        if (repository.path !== '')
+            return `${repository.path}/${repoPath}`;
+        if (repository.prefix === '')
+            return repoPath;
+        return repoPath.startsWith(repository.prefix) ? repoPath.slice(repository.prefix.length) : null;
+    }
+    async #repositoryStatus(repository) {
+        const [statusResult, unstagedStats, stagedStats] = await Promise.all([
+            this.#git(repository.topLevel, ['status', '--porcelain=v2', '--branch', '-z', '--untracked-files=all'], STATUS_MAX_BYTES),
+            this.#git(repository.topLevel, ['diff', '--numstat', '-z', ...DIFF_FLAGS], STATUS_MAX_BYTES),
+            this.#git(repository.topLevel, ['diff', '--cached', '--numstat', '-z', ...DIFF_FLAGS], STATUS_MAX_BYTES),
+        ]);
+        const parsed = parsePorcelainV2(statusResult.stdout.toString('utf8'));
+        const unstagedCounts = parseNumstat(unstagedStats.stdout.toString('utf8'));
+        const stagedCounts = parseNumstat(stagedStats.stdout.toString('utf8'));
+        const truncated = statusResult.stdoutTruncated || parsed.changes.length > this.#options.maxChanges;
+        const changes = parsed.changes.slice(0, this.#options.maxChanges).map((change) => {
+            const counts = change.area === 'staged' ? stagedCounts.get(change.path) : change.area === 'unstaged' ? unstagedCounts.get(change.path) : undefined;
+            return {
+                ...change,
+                workspacePath: this.#toWorkspacePath(repository, change.path),
+                additions: counts?.additions ?? null,
+                deletions: counts?.deletions ?? null,
+            };
+        });
+        return {
+            path: repository.path,
+            branch: parsed.branch,
+            detached: parsed.detached,
+            commit: parsed.commit ? parsed.commit.slice(0, 12) : null,
+            upstream: parsed.upstream,
+            ahead: parsed.ahead,
+            behind: parsed.behind,
+            changes,
+            truncated,
+            error: null,
+        };
+    }
+    /** Status of the project's repository and of every repository nested inside the project folder. */
+    async status() {
+        const [root, nested] = await Promise.all([this.#findRepository(), this.#discoverNested()]);
+        const nestedRepositories = (await Promise.all(nested.paths.map((relativePath) => this.#nestedRepository(relativePath)))).filter((repository) => repository !== null);
+        const repositories = [...(root ? [root] : []), ...nestedRepositories];
+        const statuses = await Promise.all(repositories.map((repository) => this.#repositoryStatus(repository).catch((error) => {
+            // One unreadable repository (e.g. "dubious ownership") must not hide the others.
+            if (repository === root)
+                throw error;
+            return {
+                path: repository.path,
+                branch: null,
+                detached: false,
+                commit: null,
+                upstream: null,
+                ahead: 0,
+                behind: 0,
+                changes: [],
+                truncated: false,
+                error: error instanceof AppError ? error.message : 'Could not read this repository.',
+            };
+        })));
+        // A nested clone appears in its parent as one untracked folder; its own section shows the details.
+        const nestedFolders = new Set(nestedRepositories.map((repository) => `${repository.path}/`));
+        for (const status of statuses) {
+            status.changes = status.changes.filter((change) => !(change.area === 'untracked' && change.workspacePath && nestedFolders.has(change.workspacePath)));
+        }
+        return { repositories: statuses, repositoriesTruncated: nested.truncated };
+    }
+    /** The project's repository ('') or a verified nested one. */
+    async #repository(repo) {
+        const repoPath = normalizeWorkspacePath(repo ?? '');
+        const repository = repoPath === '' ? await this.#findRepository() : await this.#nestedRepository(repoPath);
+        if (!repository)
+            throw new AppError('NOT_A_REPOSITORY', 'Not a Git repository.');
+        return { repoPath, repository };
+    }
+    /** Resolve a commit id to its full hash; never passes unverified input on to other commands. */
+    async #commit(repository, commit) {
+        if (!/^[0-9a-f]{7,64}$/.test(commit))
+            throw new AppError('BAD_REQUEST', 'Invalid commit.');
+        const result = await this.#runner.run([...GIT_BASE, 'rev-list', '--parents', '-n', '1', `${commit}^{commit}`, '--'], {
+            cwd: repository.topLevel,
+            env: GIT_ENV,
+            maxOutputBytes: 64 * 1024,
+        });
+        const [hash, ...parents] = result.stdout.toString('utf8').trim().split(' ');
+        if (result.exitCode !== 0 || !hash)
+            throw new AppError('NOT_FOUND', 'Commit not found.');
+        return { hash, parents };
+    }
+    async #optional(cwd, args) {
+        const result = await this.#runner.run([...GIT_BASE, ...args], { cwd, env: GIT_ENV, maxOutputBytes: 64 * 1024 });
+        const value = result.stdout.toString('utf8').trim();
+        return result.exitCode === 0 && value ? value : null;
+    }
+    /**
+     * Commit history for the graph, newest first in topological order (as VS Code's Git
+     * extension requests it). By default the current branch and its upstream; `all` adds
+     * every branch, remote branch, and tag.
+     */
+    async log(query) {
+        const { repository } = await this.#repository(query.repo);
+        const limit = query.limit;
+        const [head, headRef] = await Promise.all([
+            this.#optional(repository.topLevel, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}']),
+            this.#optional(repository.topLevel, ['symbolic-ref', '-q', 'HEAD']),
+        ]);
+        if (!head)
+            return { items: [], hasMore: false, head: null, headRef, upstreamRef: null };
+        const upstreamRef = headRef ? await this.#optional(repository.topLevel, ['for-each-ref', '--format=%(upstream)', headRef]) : null;
+        const revisions = query.all ? ['--branches', '--remotes', '--tags', 'HEAD'] : ['HEAD', ...(upstreamRef ? [upstreamRef] : [])];
+        const result = await this.#git(repository.topLevel, ['log', `--format=${LOG_FORMAT}`, '-z', '--topo-order', '--decorate=full', '-n', String(limit + 1), ...revisions, '--'], STATUS_MAX_BYTES);
+        const items = parseLog(result.stdout.toString('utf8'));
+        return { items: items.slice(0, limit), hasMore: items.length > limit || result.stdoutTruncated, head, headRef, upstreamRef };
+    }
+    /** One commit with the files it changed against its first parent. */
+    async commitDetails(query) {
+        const { repository } = await this.#repository(query.repo);
+        const { hash, parents } = await this.#commit(repository, query.commit);
+        const [first] = parents;
+        // Root commits are compared with the empty tree.
+        const range = first ? [first, hash] : ['--root', hash];
+        const [info, nameStatus, numstat] = await Promise.all([
+            this.#git(repository.topLevel, ['log', `--format=${LOG_FORMAT}`, '-z', '--decorate=full', '-n', '1', hash, '--'], 1024 * 1024),
+            this.#git(repository.topLevel, ['diff-tree', '-r', '-M', '--no-commit-id', '--name-status', '-z', ...range, '--'], STATUS_MAX_BYTES),
+            this.#git(repository.topLevel, ['diff-tree', '-r', '-M', '--no-commit-id', '--numstat', '-z', ...range, '--'], STATUS_MAX_BYTES),
+        ]);
+        const item = parseLog(info.stdout.toString('utf8'))[0];
+        if (!item)
+            throw new AppError('NOT_FOUND', 'Commit not found.');
+        const counts = parseNumstat(numstat.stdout.toString('utf8'));
+        const entries = parseNameStatus(nameStatus.stdout.toString('utf8'));
+        const files = entries.slice(0, this.#options.maxChanges).map((entry) => ({
+            ...entry,
+            additions: counts.get(entry.path)?.additions ?? null,
+            deletions: counts.get(entry.path)?.deletions ?? null,
+        }));
+        return { ...item, files, truncated: nameStatus.stdoutTruncated || entries.length > this.#options.maxChanges };
+    }
+    /** Diff of one file in a commit, against the commit's first parent. */
+    async commitDiff(query) {
+        const { repoPath, repository } = await this.#repository(query.repo);
+        const { hash, parents } = await this.#commit(repository, query.commit);
+        const filePath = normalizeWorkspacePath(query.path);
+        const origPath = query.origPath ? normalizeWorkspacePath(query.origPath) : null;
+        if (filePath === '')
+            throw new AppError('BAD_REQUEST', 'A file path is required.');
+        const paths = ['--', ...(origPath ? [origPath] : []), filePath];
+        const [first] = parents;
+        const args = first ? ['diff', '-M', ...DIFF_FLAGS, first, hash, ...paths] : ['show', '--format=', '-M', ...DIFF_FLAGS, hash, ...paths];
+        const result = await this.#git(repository.topLevel, args, this.#options.maxDiffBytes);
+        const diff = result.stdout.toString('utf8');
+        return { repo: repoPath, commit: hash, path: filePath, diff, binary: isBinaryDiff(diff), truncated: result.stdoutTruncated };
+    }
+    async diff(query) {
+        const { repoPath, repository } = await this.#repository(query.repo);
+        // Paths are repository-relative; the same normalization rules forbid escaping the repository.
+        const filePath = normalizeWorkspacePath(query.path);
+        const origPath = query.origPath ? normalizeWorkspacePath(query.origPath) : null;
+        if (filePath === '')
+            throw new AppError('BAD_REQUEST', 'A file path is required.');
+        let args;
+        let okExitCodes = [0];
+        switch (query.area) {
+            case 'staged':
+                args = ['diff', '--cached', '-M', ...DIFF_FLAGS, '--', ...(origPath ? [origPath] : []), filePath];
+                break;
+            case 'unstaged':
+            case 'conflicted':
+                args = ['diff', ...DIFF_FLAGS, '--', filePath];
+                break;
+            case 'untracked':
+                // --no-index exits 1 when the files differ, which is always the case here.
+                args = ['diff', '--no-index', ...DIFF_FLAGS, '--', '/dev/null', filePath];
+                okExitCodes = [0, 1];
+                break;
+        }
+        const result = await this.#git(repository.topLevel, args, this.#options.maxDiffBytes, okExitCodes);
+        const diff = result.stdout.toString('utf8');
+        return { repo: repoPath, path: filePath, area: query.area, diff, binary: isBinaryDiff(diff), truncated: result.stdoutTruncated };
+    }
+    /** Repository-relative paths, validated like every other path. */
+    #paths(paths) {
+        const normalized = paths.map((entry) => normalizeWorkspacePath(entry));
+        if (normalized.some((entry) => entry === ''))
+            throw new AppError('BAD_REQUEST', 'A file path is required.');
+        return [...new Set(normalized)];
+    }
+    async #hasHead(repository) {
+        return (await this.#optional(repository.topLevel, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'])) !== null;
+    }
+    async #hasStagedChanges(repository) {
+        // --quiet exits 1 when there are differences.
+        const result = await this.#git(repository.topLevel, ['diff', '--cached', '--quiet', ...DIFF_FLAGS], 64 * 1024, [0, 1]);
+        return result.exitCode === 1;
+    }
+    /** `git add` the paths, including deletions. */
+    async stage(repo, paths) {
+        const { repository } = await this.#repository(repo);
+        await this.#git(repository.topLevel, ['add', '-A', '--', ...this.#paths(paths)], 64 * 1024);
+    }
+    /** Remove the paths from the index, keeping the working tree. */
+    async unstage(repo, paths) {
+        const { repository } = await this.#repository(repo);
+        const files = this.#paths(paths);
+        // Before the first commit there is no HEAD to restore from: drop the entries from the index instead.
+        const args = (await this.#hasHead(repository)) ? ['restore', '--staged', '--', ...files] : ['rm', '--cached', '-r', '-q', '--ignore-unmatch', '--', ...files];
+        await this.#git(repository.topLevel, args, 64 * 1024);
+    }
+    /** "Discard Changes": tracked files go back to their staged (or committed) content, untracked files are deleted. */
+    async discard(repo, paths) {
+        const { repository } = await this.#repository(repo);
+        const files = this.#paths(paths);
+        const listed = await this.#git(repository.topLevel, ['ls-files', '-z', '--', ...files], STATUS_MAX_BYTES);
+        const tracked = new Set(listed.stdout.toString('utf8').split('\0'));
+        const restore = files.filter((file) => tracked.has(file));
+        const remove = files.filter((file) => !tracked.has(file));
+        if (restore.length > 0)
+            await this.#git(repository.topLevel, ['restore', '--worktree', '--', ...restore], 64 * 1024);
+        if (remove.length > 0)
+            await this.#git(repository.topLevel, ['clean', '-f', '-q', '--', ...remove], 64 * 1024);
+    }
+    /** "Discard Block": reverse-apply one hunk of a file's working-tree diff, but only if the diff still contains it. */
+    async discardHunk(repo, filePath, hunk) {
+        const { repository } = await this.#repository(repo);
+        const [file = ''] = this.#paths([filePath]);
+        const result = await this.#git(repository.topLevel, ['diff', ...DIFF_FLAGS, '--', file], this.#options.maxDiffBytes);
+        if (result.stdoutTruncated)
+            throw new AppError('BAD_REQUEST', 'This diff is too large to discard part of it. Discard the whole file instead.');
+        const { header, hunks } = splitDiffHunks(result.stdout.toString('utf8'));
+        const wanted = hunk.replace(/\n$/, '');
+        if (!hunks.includes(wanted))
+            throw new AppError('CONFLICT', 'The file changed since the diff was shown. Refresh and try again.');
+        await this.#git(repository.topLevel, ['apply', '-R', '--whitespace=nowarn', '-'], 64 * 1024, [0], undefined, GIT_BASE, `${header}${wanted}\n`);
+    }
+    /**
+     * Commit the index (or, with `stageAll` and an empty index, every change). `all` stages
+     * everything first; `amend` rewrites the last commit (keeping its message when `message`
+     * is empty). Hooks run as usual.
+     */
+    async commit(repo, message, stageAll, { all = false, amend = false, signoff = false } = {}) {
+        const { repoPath, repository } = await this.#repository(repo);
+        if (amend && !(await this.#hasHead(repository)))
+            throw new AppError('BAD_REQUEST', 'There is no commit to amend yet.');
+        if (all)
+            await this.#git(repository.topLevel, ['add', '-A'], 64 * 1024);
+        if (!amend && !(await this.#hasStagedChanges(repository))) {
+            if (!stageAll && !all)
+                throw new AppError('BAD_REQUEST', 'There are no staged changes to commit.');
+            await this.#git(repository.topLevel, ['add', '-A'], 64 * 1024);
+            if (!(await this.#hasStagedChanges(repository)))
+                throw new AppError('BAD_REQUEST', 'There are no changes to commit.');
+        }
+        if (!amend && message === '')
+            throw new AppError('BAD_REQUEST', 'Enter a commit message.');
+        const args = ['commit', '--quiet', ...(amend ? ['--amend'] : []), ...(signoff ? ['--signoff'] : []), ...(message === '' ? ['--no-edit'] : ['-m', message])];
+        await this.#git(repository.topLevel, args, 1024 * 1024, [0], COMMIT_TIMEOUT_MS);
+        const commit = await this.#optional(repository.topLevel, ['rev-parse', 'HEAD']);
+        return { repo: repoPath, commit: commit ?? '' };
+    }
+    /**
+     * What an AI backend needs to describe the pending commit, gathered the way occ does:
+     * the staged diff (or, with nothing staged, the working tree plus untracked file names) and the branch.
+     */
+    async commitMessageContext(repo) {
+        const { repository } = await this.#repository(repo);
+        const cwd = repository.topLevel;
+        const staged = await this.#hasStagedChanges(repository);
+        const [diffResult, untracked, branch] = await Promise.all([
+            this.#git(cwd, ['diff', ...(staged ? ['--cached'] : []), ...DIFF_FLAGS], COMMIT_CONTEXT_MAX_DIFF + 1),
+            staged ? null : this.#git(cwd, ['ls-files', '--others', '--exclude-standard', '-z'], 1024 * 1024),
+            this.#optional(cwd, ['branch', '--show-current']),
+        ]);
+        let diff = diffResult.stdout.toString('utf8');
+        if (diff.length > COMMIT_CONTEXT_MAX_DIFF || diffResult.stdoutTruncated)
+            diff = `${diff.slice(0, COMMIT_CONTEXT_MAX_DIFF)}\n... (truncated)`;
+        const newFiles = untracked?.stdout.toString('utf8').split('\0').filter(Boolean) ?? [];
+        if (newFiles.length > 0)
+            diff += `${diff ? '\n\n' : ''}New untracked files:\n${newFiles.slice(0, 200).join('\n')}`;
+        if (diff.trim() === '')
+            throw new AppError('BAD_REQUEST', 'There are no changes to describe.');
+        return { branch: branch ?? 'HEAD', diff };
+    }
+    /** Branches, remotes, tags, and stashes, for the pickers of the "..." menu. */
+    async refs(repo) {
+        const { repository } = await this.#repository(repo);
+        const cwd = repository.topLevel;
+        const [refs, remotes, tags, stashes] = await Promise.all([
+            this.#git(cwd, ['for-each-ref', '--format=%(refname)%00%(HEAD)%00%(upstream:short)', 'refs/heads', 'refs/remotes'], STATUS_MAX_BYTES),
+            this.#git(cwd, ['remote', '-v'], 1024 * 1024),
+            this.#git(cwd, ['for-each-ref', '--sort=-creatordate', '--format=%(refname:strip=2)', 'refs/tags'], STATUS_MAX_BYTES),
+            this.#git(cwd, ['stash', 'list', '--format=%H%x00%gs'], 1024 * 1024),
+        ]);
+        const branches = refs.stdout
+            .toString('utf8')
+            .split('\n')
+            .filter(Boolean)
+            .map((line) => {
+            const [ref = '', head = '', upstream = ''] = line.split('\0');
+            const remote = ref.startsWith('refs/remotes/');
+            return { name: ref.slice(remote ? 'refs/remotes/'.length : 'refs/heads/'.length), remote, current: head === '*', upstream: upstream || null };
+        })
+            // origin/HEAD is a pointer, not a branch.
+            .filter((branch) => !(branch.remote && branch.name.endsWith('/HEAD')));
+        const remoteUrls = new Map();
+        for (const line of remotes.stdout.toString('utf8').split('\n')) {
+            const match = /^(\S+)\t(.*) \(fetch\)$/.exec(line);
+            if (match?.[1])
+                remoteUrls.set(match[1], match[2] ? stripCredentials(match[2]) : null);
+        }
+        return {
+            branches,
+            remotes: [...remoteUrls].map(([name, url]) => ({ name, url })),
+            tags: tags.stdout.toString('utf8').split('\n').filter(Boolean),
+            stashes: stashes.stdout
+                .toString('utf8')
+                .split('\n')
+                .filter(Boolean)
+                .map((line, index) => {
+                const [hash = '', message = ''] = line.split('\0');
+                return { index, hash, message };
+            }),
+        };
+    }
+    async #currentBranch(repository) {
+        const branch = await this.#optional(repository.topLevel, ['branch', '--show-current']);
+        if (!branch)
+            throw new AppError('BAD_REQUEST', 'Not on a branch (detached HEAD).');
+        return branch;
+    }
+    async #checkRefFormat(repository, name) {
+        const result = await this.#runner.run([...GIT_BASE, 'check-ref-format', '--branch', name], { cwd: repository.topLevel, env: GIT_ENV, maxOutputBytes: 64 * 1024 });
+        if (result.exitCode !== 0)
+            throw new AppError('BAD_REQUEST', `"${name}" is not a valid name.`);
+    }
+    /** The "..." menu and the sync button: one fixed argv per operation, names validated by the schema and Git. */
+    async operation(operation) {
+        const { repository } = await this.#repository(operation.repo);
+        const cwd = repository.topLevel;
+        const run = (args, okExitCodes = [0]) => this.#git(cwd, args, 1024 * 1024, okExitCodes, COMMIT_TIMEOUT_MS);
+        const stash = (args) => this.#git(cwd, ['stash', ...args], 1024 * 1024, [0], COMMIT_TIMEOUT_MS, STASH_BASE);
+        const network = (args) => this.#git(cwd, [...NETWORK_FLAGS, ...args], 1024 * 1024, [0], NETWORK_TIMEOUT_MS);
+        let commitMessage = null;
+        switch (operation.op) {
+            case 'fetch':
+                await network(['fetch', ...(operation.mode === 'prune' ? ['--prune'] : operation.mode === 'all' ? ['--all'] : [])]);
+                break;
+            case 'pull':
+                if (operation.branch && !operation.remote)
+                    throw new AppError('BAD_REQUEST', 'Choose a remote to pull from.');
+                await network(['pull', '--no-edit', ...(operation.rebase ? ['--rebase'] : []), ...(operation.remote ? [operation.remote] : []), ...(operation.branch ? [operation.branch] : [])]);
+                break;
+            case 'push': {
+                if (operation.remote) {
+                    await network(['push', operation.remote, await this.#currentBranch(repository)]);
+                    break;
+                }
+                const branch = await this.#currentBranch(repository);
+                const upstream = await this.#optional(cwd, ['rev-parse', '--abbrev-ref', `${branch}@{upstream}`]);
+                if (!upstream)
+                    throw new AppError('BAD_REQUEST', `The branch "${branch}" has no upstream. Publish it first.`);
+                await network(['push']);
+                break;
+            }
+            case 'publish':
+                await network(['push', '--set-upstream', operation.remote, await this.#currentBranch(repository)]);
+                break;
+            case 'sync':
+                await network(['pull', '--no-edit']);
+                await network(['push']);
+                break;
+            case 'checkout':
+                if (!operation.remote) {
+                    await run(['switch', operation.ref]);
+                    break;
+                }
+                {
+                    const slash = operation.ref.indexOf('/');
+                    const local = slash > 0 ? operation.ref.slice(slash + 1) : '';
+                    if (!local)
+                        throw new AppError('BAD_REQUEST', 'Choose a remote branch such as origin/main.');
+                    const exists = await this.#optional(cwd, ['rev-parse', '--verify', '--quiet', `refs/heads/${local}`]);
+                    await run(exists ? ['switch', local] : ['switch', '--create', local, '--track', `refs/remotes/${operation.ref}`]);
+                }
+                break;
+            case 'createBranch':
+                await this.#checkRefFormat(repository, operation.name);
+                await run(['switch', '--create', operation.name, ...(operation.from ? [operation.from] : [])]);
+                break;
+            case 'renameBranch':
+                await this.#checkRefFormat(repository, operation.name);
+                await run(['branch', '--move', await this.#currentBranch(repository), operation.name]);
+                break;
+            case 'deleteBranch':
+                await run(['branch', operation.force ? '-D' : '-d', operation.name]);
+                break;
+            case 'deleteRemoteBranch':
+                await network(['push', operation.remote, '--delete', `refs/heads/${operation.name}`]);
+                break;
+            case 'merge':
+                await run(['merge', '--no-edit', operation.ref]);
+                break;
+            case 'rebase':
+                await run(['rebase', operation.ref]);
+                break;
+            case 'abortRebase':
+                await run(['rebase', '--abort']);
+                break;
+            case 'undoCommit': {
+                if (!(await this.#hasHead(repository)))
+                    throw new AppError('BAD_REQUEST', 'There is no commit to undo.');
+                commitMessage = (await this.#optional(cwd, ['log', '-1', '--format=%B', 'HEAD'])) ?? null;
+                // Like VS Code: keep the changes staged; the first commit has no parent to reset to.
+                const parent = await this.#optional(cwd, ['rev-parse', '--verify', '--quiet', 'HEAD~1^{commit}']);
+                await run(parent ? ['reset', '--soft', 'HEAD~1'] : ['update-ref', '-d', 'HEAD']);
+                break;
+            }
+            case 'stageAll':
+                await run(['add', '-A']);
+                break;
+            case 'unstageAll':
+                await run((await this.#hasHead(repository)) ? ['reset', '-q'] : ['rm', '--cached', '-r', '-q', '--ignore-unmatch', '--', '.']);
+                break;
+            case 'discardAll':
+                // Staged changes stay; tracked files go back to the index, untracked files (not ignored ones) are deleted.
+                await run(['restore', '--worktree', '--', '.'], [0, 1]);
+                await run(['clean', '-f', '-d', '-q', '--', '.']);
+                break;
+            case 'addRemote':
+                await run(['remote', 'add', operation.name, operation.url]);
+                break;
+            case 'removeRemote':
+                await run(['remote', 'remove', operation.name]);
+                break;
+            case 'stash': {
+                const mode = operation.mode === 'untracked' ? ['--include-untracked'] : operation.mode === 'staged' ? ['--staged'] : [];
+                await stash(['push', ...mode, ...(operation.message ? ['--message', operation.message] : [])]);
+                break;
+            }
+            case 'stashApply':
+                await stash([operation.pop ? 'pop' : 'apply', ...(operation.index === undefined ? [] : [`stash@{${operation.index}}`])]);
+                break;
+            case 'stashDrop':
+                await stash(['drop', `stash@{${operation.index}}`]);
+                break;
+            case 'stashClear':
+                await stash(['clear']);
+                break;
+            case 'createTag':
+                await this.#checkRefFormat(repository, operation.name);
+                await run(operation.message ? ['tag', '--annotate', operation.name, '--message', operation.message] : ['tag', operation.name]);
+                break;
+            case 'deleteTag':
+                await run(['tag', '--delete', operation.name]);
+                break;
+            case 'deleteRemoteTag':
+                await network(['push', operation.remote, '--delete', `refs/tags/${operation.name}`]);
+                break;
+        }
+        return { commitMessage };
+    }
+}