@playcraft/cli 0.1.42 → 0.1.43-beta

package/dist/workspace-runtime/workspaces/git.js

@@ -0,0 +1,670 @@
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { excludeFromGit } from './dependencies.js';
+import { copyFile, lstat, readFile, realpath, rm, stat, unlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { basename, dirname, join, relative, resolve, sep } from 'node:path';
+import { TURN_CHANGED_FILES_MAX, WORKSPACE_FILE_CONTENT_MAX, gitDiffSchema, gitFileContentSchema, gitGraphSchema, gitStatusSchema, workspaceRelativePathSchema, } from '@playcraft/common/cloud-workspace/runtime';
+const GIT_DIFF_MAX_BYTES = 1024 * 1024;
+const GIT_PREFIX = [
+    '-c',
+    'core.hooksPath=/dev/null',
+    '-c',
+    'commit.gpgsign=false',
+    '-c',
+    'safe.directory=*',
+];
+export class GitWorkspaceError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = 'GitWorkspaceError';
+    }
+}
+export async function probeGitBinary() {
+    try {
+        const result = await runGitProcess(tmpdir(), ['--version'], 4000);
+        return result.code === 0;
+    }
+    catch (error) {
+        return error instanceof GitWorkspaceError && error.code === 'git_binary_missing' ? false : false;
+    }
+}
+export async function readWorkspaceGitStatus(root) {
+    const rootReal = await ensureWorkspaceGit(root);
+    const branchResult = await gitAllowFail(rootReal, ['symbolic-ref', '--short', 'HEAD']);
+    const branch = branchResult.code === 0 ? branchResult.stdout.trim() || 'HEAD' : 'HEAD';
+    const upstream = await gitAllowFail(rootReal, ['rev-list', '--left-right', '--count', '@{upstream}...HEAD']);
+    let ahead = 0;
+    let behind = 0;
+    if (upstream.code === 0) {
+        const [left, right] = upstream.stdout.trim().split(/\s+/);
+        behind = Number.parseInt(left ?? '0', 10) || 0;
+        ahead = Number.parseInt(right ?? '0', 10) || 0;
+    }
+    const porcelain = await git(rootReal, ['status', '--porcelain=v1', '--untracked-files=all', '-z']);
+    const merge = await mergeState(rootReal);
+    // Line counts are a convenience; a repository without commits still lists its files.
+    const [staged, unstaged] = await Promise.all([
+        gitAllowFail(rootReal, ['diff', '--cached', '--numstat', '-z']),
+        gitAllowFail(rootReal, ['diff', '--numstat', '-z']),
+    ]);
+    const stagedCounts = staged.code === 0 ? parseNumstat(staged.stdout) : new Map();
+    const unstagedCounts = unstaged.code === 0 ? parseNumstat(unstaged.stdout) : new Map();
+    return gitStatusSchema.parse({
+        initialized: true,
+        branch,
+        ahead,
+        behind,
+        hasUpstream: upstream.code === 0,
+        ...merge,
+        files: parsePorcelain(porcelain).map((entry) => ({
+            ...entry,
+            ...(stagedCounts.has(entry.path) ? { staged: stagedCounts.get(entry.path) } : {}),
+            ...(unstagedCounts.has(entry.path) ? { unstaged: unstagedCounts.get(entry.path) } : {}),
+        })),
+    });
+}
+const SNAPSHOT_TIMEOUT_MS = 120_000;
+/**
+ * Writes the work tree, as `git add -A` would stage it, to a tree object without touching the
+ * repository's own index or history. A copy of the index keeps its stat cache, so unchanged files
+ * are not hashed again. Ignored files and credential files are left out of the snapshot.
+ */
+export async function snapshotWorkspaceTree(root) {
+    const rootReal = await existingWorkspaceGit(root);
+    const env = { GIT_INDEX_FILE: join(rootReal, '.git', `playcraft-snapshot-${randomUUID()}.index`) };
+    const run = async (args) => {
+        const result = await runGitProcess(rootReal, [...GIT_PREFIX, `--git-dir=${join(rootReal, '.git')}`,
+            `--work-tree=${rootReal}`, ...args], SNAPSHOT_TIMEOUT_MS, env);
+        if (result.code !== 0)
+            throw new GitWorkspaceError('git_command_failed', result.stderr.trim() || `git_exit_${result.code}`);
+        return result.stdout;
+    };
+    try {
+        await copyFile(join(rootReal, '.git', 'index'), env.GIT_INDEX_FILE).catch((error) => {
+            if (error.code !== 'ENOENT')
+                throw error;
+        });
+        await run(['add', '-A']);
+        const credentials = (await run(['ls-files', '-z'])).split('\0').filter((path) => path && isCredentialFile(path));
+        if (credentials.length)
+            await run(['rm', '--cached', '--quiet', '--', ...credentials]);
+        return (await run(['write-tree'])).trim();
+    }
+    finally {
+        await rm(env.GIT_INDEX_FILE, { force: true });
+    }
+}
+/** Keeps a turn's snapshots from being pruned, so its changes stay readable after Git cleans up. */
+export async function retainTurnSnapshots(root, turnId, before, after) {
+    const rootReal = await existingWorkspaceGit(root);
+    const name = turnId.replace(/[^A-Za-z0-9_-]/g, '_');
+    await git(rootReal, ['update-ref', `refs/playcraft/turns/${name}/before`, before]);
+    await git(rootReal, ['update-ref', `refs/playcraft/turns/${name}/after`, after]);
+}
+/** The files that differ between two snapshot trees, with line counts for text files. */
+export async function diffWorkspaceTrees(root, before, after) {
+    const rootReal = await existingWorkspaceGit(root);
+    const diff = (format) => git(rootReal, ['diff-tree', '-r', '-z', '--no-renames', format, before, after], 60000);
+    const [statuses, counts] = await Promise.all([diff('--name-status'), diff('--numstat')]);
+    const lines = new Map();
+    for (const entry of counts.split('\0')) {
+        const match = /^(\d+|-)\t(\d+|-)\t(.+)$/s.exec(entry);
+        if (!match)
+            continue;
+        const binary = match[1] === '-';
+        lines.set(match[3], { added: binary ? 0 : Number(match[1]), removed: binary ? 0 : Number(match[2]), binary });
+    }
+    const parts = statuses.split('\0');
+    const files = [];
+    for (let index = 0; index + 1 < parts.length; index += 2) {
+        const status = parts[index] === 'A' ? 'added' : parts[index] === 'D' ? 'deleted' : 'modified';
+        const path = parts[index + 1];
+        files.push({ path, status, ...(lines.get(path) ?? { added: 0, removed: 0, binary: false }) });
+    }
+    return { files: files.slice(0, TURN_CHANGED_FILES_MAX), truncated: files.length > TURN_CHANGED_FILES_MAX };
+}
+/**
+ * One file as stored in the last commit, in the index or in a turn snapshot. Reads the blob as is,
+ * without filters, so the browser compares exactly what Git holds.
+ */
+export async function readWorkspaceGitFile(root, path, ref) {
+    const rootReal = await ensureWorkspaceGit(root);
+    assertWorkspacePaths([path]);
+    const stage = { INDEX: 0, MERGE_BASE: 1, MERGE_OURS: 2, MERGE_THEIRS: 3 }[ref];
+    const object = stage === undefined ? `${ref}:${path}` : `:${stage}:${path}`;
+    const absent = gitFileContentSchema.parse({ path, ref, exists: false, binary: false, content: '' });
+    const size = await gitAllowFail(rootReal, ['cat-file', '-s', object]);
+    if (size.code !== 0)
+        return absent;
+    if (Number.parseInt(size.stdout.trim(), 10) > WORKSPACE_FILE_CONTENT_MAX) {
+        throw new GitWorkspaceError('git_file_too_large', path);
+    }
+    const blob = await gitAllowFail(rootReal, ['cat-file', 'blob', object]);
+    if (blob.code !== 0)
+        return absent;
+    // Git treats a NUL byte as the mark of binary content; so does the diff view.
+    const binary = blob.stdout.includes('\0');
+    return gitFileContentSchema.parse({ path, ref, exists: true, binary, content: binary ? '' : blob.stdout });
+}
+/** Adds the paths to the index, including deletions. */
+export async function stageWorkspaceGit(root, payload) {
+    const rootReal = await ensureWorkspaceGit(root);
+    assertWorkspacePaths(payload.paths);
+    await git(rootReal, ['--literal-pathspecs', 'add', '-A', '--', ...payload.paths]);
+}
+/** Returns the paths' index entries to the last commit, leaving the work tree alone. */
+export async function unstageWorkspaceGit(root, payload) {
+    const rootReal = await ensureWorkspaceGit(root);
+    assertWorkspacePaths(payload.paths);
+    const head = await gitAllowFail(rootReal, ['rev-parse', '--verify', '--quiet', 'HEAD']);
+    if (head.code === 0) {
+        await git(rootReal, ['--literal-pathspecs', 'restore', '--staged', '--', ...payload.paths]);
+    }
+    else {
+        // Before the first commit there is nothing to restore from; the entries are simply removed.
+        await git(rootReal, ['--literal-pathspecs', 'rm', '--cached', '-r', '-q', '--ignore-unmatch', '--', ...payload.paths]);
+    }
+}
+/**
+ * Throws away work-tree changes: tracked files return to their staged content, untracked files are
+ * deleted. Staged content is never touched, so a staged change survives a discard.
+ */
+export async function discardWorkspaceGit(root, payload) {
+    const rootReal = await ensureWorkspaceGit(root);
+    assertWorkspacePaths(payload.paths);
+    const others = await git(rootReal, ['--literal-pathspecs', 'ls-files', '--others', '--exclude-standard', '-z', '--', ...payload.paths]);
+    const untracked = new Set(others.split('\0').filter((path) => path.length > 0));
+    const tracked = payload.paths.filter((path) => !untracked.has(path));
+    if (tracked.length > 0) {
+        await git(rootReal, ['--literal-pathspecs', 'restore', '--worktree', '--', ...tracked]);
+    }
+    for (const path of untracked) {
+        const target = resolve(rootReal, path);
+        // The parent must resolve inside the workspace, so a symlinked directory cannot redirect the delete.
+        assertInsideRoot(rootReal, join(await realpath(dirname(target)), basename(target)));
+        if ((await lstat(target)).isDirectory())
+            throw new GitWorkspaceError('invalid_workspace_path', path);
+        await unlink(target);
+    }
+}
+function assertWorkspacePaths(paths) {
+    for (const relativePath of paths) {
+        if (!workspaceRelativePathSchema.safeParse(relativePath).success) {
+            throw new GitWorkspaceError('invalid_workspace_path', relativePath);
+        }
+    }
+}
+export async function readWorkspaceGitDiff(root) {
+    const rootReal = await ensureWorkspaceGit(root);
+    const vsHead = await gitAllowFail(rootReal, ['diff', '--no-color', 'HEAD']);
+    const patch = vsHead.code === 0
+        ? vsHead.stdout
+        : `${(await gitAllowFail(rootReal, ['diff', '--no-color'])).stdout}${(await gitAllowFail(rootReal, ['diff', '--no-color', '--cached'])).stdout}`;
+    if (Buffer.byteLength(patch, 'utf8') > GIT_DIFF_MAX_BYTES) {
+        throw new GitWorkspaceError('git_diff_too_large', '1MiB');
+    }
+    return gitDiffSchema.parse({ patch });
+}
+export async function readWorkspaceGitGraph(root) {
+    const rootReal = await ensureWorkspaceGit(root);
+    const log = await gitAllowFail(rootReal, ['log', '-n', '20', '--format=%H%x09%s%x09%cI']);
+    if (log.code !== 0)
+        return gitGraphSchema.parse({ commits: [] });
+    const commits = log.stdout
+        .split('\n')
+        .map((line) => line.trimEnd())
+        .filter((line) => line.length > 0)
+        .map((line) => {
+        const [sha, subject, committedAt] = splitLogLine(line);
+        return {
+            sha,
+            subject: subject.length > 0 ? subject : '(empty)',
+            committedAt: committedAt.length > 0 ? committedAt : new Date(0).toISOString(),
+        };
+    });
+    return gitGraphSchema.parse({ commits });
+}
+function splitLogLine(line) {
+    const first = line.indexOf('\t');
+    if (first < 0)
+        return [line, '', ''];
+    const second = line.indexOf('\t', first + 1);
+    if (second < 0)
+        return [line.slice(0, first), line.slice(first + 1), ''];
+    return [line.slice(0, first), line.slice(first + 1, second), line.slice(second + 1)];
+}
+/**
+ * Commit and push stay on the branch the workspace is bound to. A switch made in a shell or by an
+ * agent is reported, never followed, so work cannot land on another Remix.
+ */
+async function assertBoundBranch(rootReal, boundBranch) {
+    if (!boundBranch)
+        return;
+    const current = await gitAllowFail(rootReal, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    const branch = current.code === 0 ? current.stdout.trim() : '';
+    if (branch !== boundBranch) {
+        throw new GitWorkspaceError('workspace_branch_mismatch', branch || 'detached HEAD');
+    }
+}
+/**
+ * A push the remote refused for this ref is a definite outcome, unlike a lost response. Porcelain
+ * output marks the ref with "!" and says whether the remote has commits this checkout lacks.
+ */
+/**
+ * The gateway or the host refused the push over HTTP before any ref changed: no write access, the
+ * gateway's writes switched off, or no such repository. Like a protected-branch refusal, nothing
+ * was pushed and the commit is kept.
+ */
+function httpRefusal(stderr) {
+    return /returned error: (?:401|403|404)\b|Authentication failed|Access denied|could not read Username|repository '[^']*' not found/i.test(stderr)
+        ? 'git_push_rejected'
+        : undefined;
+}
+function pushRejection(stdout) {
+    const line = stdout.split('\n').find((item) => item.startsWith('!\t'));
+    if (!line)
+        return undefined;
+    if (/\[rejected\] \((?:non-fast-forward|fetch first)\)/.test(line))
+        return 'git_push_remote_ahead';
+    return 'git_push_rejected';
+}
+export async function commitWorkspaceGit(root, payload, boundBranch) {
+    const rootReal = await ensureWorkspaceGit(root);
+    await assertBoundBranch(rootReal, boundBranch);
+    // Adding a conflicted file would mark it resolved with its conflict markers in it.
+    if ((await unmergedPaths(rootReal)).length)
+        throw new GitWorkspaceError('git_conflicts_unresolved', 'unmerged');
+    if (payload.stagedOnly) {
+        // The index is the commit; nothing is added.
+    }
+    else if (payload.paths && payload.paths.length > 0) {
+        assertWorkspacePaths(payload.paths);
+        await git(rootReal, ['add', '--', ...payload.paths]);
+    }
+    else {
+        await git(rootReal, ['add', '-A']);
+    }
+    const cached = await gitAllowFail(rootReal, ['diff', '--cached', '--quiet']);
+    if (cached.code === 0) {
+        throw new GitWorkspaceError('nothing_to_commit', payload.message);
+    }
+    await git(rootReal, ['commit', '-m', payload.message], 20000);
+    return (await git(rootReal, ['rev-parse', 'HEAD'])).trim();
+}
+export async function pushWorkspaceGit(root, boundBranch) {
+    const rootReal = await ensureWorkspaceGit(root);
+    await assertBoundBranch(rootReal, boundBranch);
+    const origin = await gitAllowFail(rootReal, ['remote', 'get-url', 'origin']);
+    if (origin.code !== 0) {
+        throw new GitWorkspaceError('remote_not_configured', 'origin');
+    }
+    const ref = (await git(rootReal, ['symbolic-ref', '--quiet', 'HEAD'])).trim();
+    if (!ref.startsWith('refs/heads/'))
+        throw new GitWorkspaceError('git_command_failed', 'git_branch_required');
+    const commit = (await git(rootReal, ['rev-parse', '--verify', 'HEAD^{commit}'])).trim();
+    let pushed;
+    try {
+        pushed = await gitAllowFail(rootReal, ['push', '--porcelain', 'origin', `${commit}:${ref}`], 90000);
+    }
+    catch { /* A lost response does not prove the remote rejected the update. */ }
+    if (pushed?.code === 0)
+        return;
+    const rejected = pushed ? pushRejection(pushed.stdout) ?? httpRefusal(pushed.stderr) : undefined;
+    if (rejected)
+        throw new GitWorkspaceError(rejected, rejected);
+    try {
+        const remote = await gitAllowFail(rootReal, ['ls-remote', '--refs', 'origin', ref], 20000);
+        if (remote.code === 0 && remote.stdout.trim() === `${commit}\t${ref}`)
+            return;
+    }
+    catch { /* Preserve uncertainty; never replay a write automatically. */ }
+    throw new GitWorkspaceError('git_push_outcome_unknown', 'git_push_outcome_unknown');
+}
+/**
+ * Credential files a save never commits, even when `.gitignore` misses them: env files (their
+ * `.example` / `.sample` / `.template` stay), SSH keys, netrc and Git credential stores, and key
+ * or certificate bundles.
+ */
+const CREDENTIAL_FILE = /^(?:\.env(?:\.(?!(?:example|sample|template)$)[^/]+)?|id_(?:rsa|dsa|ecdsa|ed25519)|\.netrc|\.git-credentials|[^/]*\.(?:pem|key|p12|pfx))$/i;
+export function isCredentialFile(path) {
+    return CREDENTIAL_FILE.test(path.split('/').pop() ?? '');
+}
+/**
+ * Commits every change in the work tree (`git add -A`, credential files aside) and, when asked,
+ * pushes the branch. A save with nothing new commits nothing and pushes only what the remote
+ * lacks, so a commit whose push failed goes out with the next save.
+ */
+export async function saveWorkspaceGit(root, input) {
+    const rootReal = await ensureWorkspaceGit(root);
+    await assertBoundBranch(rootReal, input.boundBranch);
+    // A save during a merge would stage conflict markers as resolutions and conclude the merge. The
+    // user (or an agent) finishes the merge with an explicit commit; saves resume after it.
+    if ((await mergeState(rootReal)).merging)
+        return { pushed: false, withheld: [] };
+    await git(rootReal, ['add', '-A'], 60000);
+    const staged = (await git(rootReal, ['diff', '--cached', '--name-only', '-z'], 60000)).split('\0').filter(Boolean);
+    const withheld = staged.filter(isCredentialFile);
+    await unstage(rootReal, withheld);
+    const cached = await gitAllowFail(rootReal, ['diff', '--cached', '--quiet'], 60000);
+    if (cached.code !== 0 && cached.code !== 1) {
+        throw new GitWorkspaceError('git_command_failed', cached.stderr.trim() || 'git_diff_failed');
+    }
+    let commit;
+    if (cached.code === 1) {
+        await git(rootReal, [...(await commitIdentity(rootReal)), 'commit', '-q', '-m', input.message], 60000);
+        commit = (await git(rootReal, ['rev-parse', 'HEAD'])).trim();
+    }
+    if (!input.push || (await remoteHasHead(rootReal)))
+        return { ...(commit ? { commit } : {}), pushed: false, withheld };
+    await pushWorkspaceGit(rootReal, input.boundBranch);
+    await recordPushedHead(rootReal);
+    return { ...(commit ? { commit } : {}), pushed: true, withheld };
+}
+/**
+ * `git pull` with a merge, as VS Code runs it: fetch the bound branch from origin, then merge it.
+ * Uncommitted work is kept unless the incoming commits change the same files, in which case Git
+ * refuses before touching anything. Conflicts leave the merge in progress for the user to resolve.
+ */
+export async function pullWorkspaceGit(root, boundBranch) {
+    const rootReal = await ensureWorkspaceGit(root);
+    await assertBoundBranch(rootReal, boundBranch);
+    if ((await mergeState(rootReal)).merging)
+        throw new GitWorkspaceError('git_merge_in_progress', 'merge_in_progress');
+    if ((await gitAllowFail(rootReal, ['remote', 'get-url', 'origin'])).code !== 0) {
+        throw new GitWorkspaceError('remote_not_configured', 'origin');
+    }
+    const branch = (await gitAllowFail(rootReal, ['symbolic-ref', '--quiet', '--short', 'HEAD'])).stdout.trim();
+    const born = (await gitAllowFail(rootReal, ['rev-parse', '-q', '--verify', 'HEAD^{commit}'])).code === 0;
+    if (!branch || !born)
+        throw new GitWorkspaceError('git_command_failed', 'git_branch_required');
+    // A fork clone has no fetch refspec for its own branch, so the tracking ref is named here.
+    const remoteRef = `refs/remotes/origin/${branch}`;
+    const fetched = await gitAllowFail(rootReal, ['fetch', '--no-tags', 'origin', `+refs/heads/${branch}:${remoteRef}`], 90000);
+    if (fetched.code !== 0)
+        throw new GitWorkspaceError(httpRefusal(fetched.stderr) ?? 'git_fetch_failed', 'git_fetch_failed');
+    if ((await gitAllowFail(rootReal, ['merge-base', '--is-ancestor', remoteRef, 'HEAD'])).code === 0) {
+        return { outcome: 'up_to_date', conflicts: [] };
+    }
+    // The short name gives the merge commit the message `git pull` would write.
+    const merged = await gitAllowFail(rootReal, [...(await commitIdentity(rootReal)), 'merge', '--no-edit', `origin/${branch}`], 60000);
+    if (merged.code === 0)
+        return { outcome: 'merged', conflicts: [] };
+    const conflicts = await unmergedPaths(rootReal);
+    if (conflicts.length)
+        return { outcome: 'conflicts', conflicts };
+    if (/would be overwritten by merge|untracked working tree files would be (?:overwritten|removed)/i.test(`${merged.stdout}\n${merged.stderr}`)) {
+        throw new GitWorkspaceError('git_pull_local_changes', 'local_changes');
+    }
+    throw new GitWorkspaceError('git_command_failed', merged.stderr.trim() || 'git_merge_failed');
+}
+/** `git merge --abort`: the work tree and index return to how they were before the merge began. */
+export async function abortWorkspaceMerge(root) {
+    const rootReal = await ensureWorkspaceGit(root);
+    if (!(await mergeState(rootReal)).merging)
+        throw new GitWorkspaceError('git_merge_not_in_progress', 'no_merge');
+    await git(rootReal, ['merge', '--abort'], 60000);
+}
+/** Paths with unmerged index entries, that is, conflicts not yet marked resolved. */
+async function unmergedPaths(rootReal) {
+    const listed = await gitAllowFail(rootReal, ['diff', '--name-only', '--diff-filter=U', '-z']);
+    return listed.code === 0 ? listed.stdout.split('\0').filter(Boolean) : [];
+}
+async function mergeState(rootReal) {
+    try {
+        await stat(join(rootReal, '.git', 'MERGE_HEAD'));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+    const message = await readFile(join(rootReal, '.git', 'MERGE_MSG'), 'utf8').catch(() => '');
+    const text = message.split('\n').filter((line) => !line.startsWith('#')).join('\n').trim().slice(0, 4096);
+    return { merging: true, ...(text ? { mergeMessage: text } : {}) };
+}
+/**
+ * Connects a standalone checkout to the repository it was just given, keeping all its history and
+ * uncommitted work. The new repository holds one empty commit on `branch`; it becomes the base of an
+ * unborn checkout, or is merged into existing history, so the next push is a plain fast-forward.
+ * Credentials come from the workspace's configured helper and never enter the remote URL.
+ * Safe to run again after a failure part way.
+ */
+export async function attachWorkspaceRemote(root, repositoryUrl, branch) {
+    const rootReal = await ensureWorkspaceGit(root);
+    const origin = await gitAllowFail(rootReal, ['remote', 'get-url', 'origin']);
+    if (origin.code !== 0)
+        await git(rootReal, ['remote', 'add', 'origin', repositoryUrl]);
+    else if (origin.stdout.trim() !== repositoryUrl)
+        throw new GitWorkspaceError('remote_not_configured', 'origin_mismatch');
+    const remoteRef = `refs/remotes/origin/${branch}`;
+    const fetched = await gitAllowFail(rootReal, ['fetch', '--no-tags', 'origin', `+refs/heads/${branch}:${remoteRef}`], 90000);
+    if (fetched.code !== 0)
+        throw new GitWorkspaceError(httpRefusal(fetched.stderr) ?? 'git_command_failed', 'git_fetch_failed');
+    const current = (await gitAllowFail(rootReal, ['symbolic-ref', '--quiet', '--short', 'HEAD'])).stdout.trim();
+    const born = (await gitAllowFail(rootReal, ['rev-parse', '-q', '--verify', 'HEAD^{commit}'])).code === 0;
+    if (current !== branch) {
+        await git(rootReal, born ? ['branch', '-M', branch] : ['symbolic-ref', 'HEAD', `refs/heads/${branch}`]);
+    }
+    if (!born) {
+        // Nothing committed yet: start the branch at the remote commit; the files stay as changes.
+        await git(rootReal, ['update-ref', `refs/heads/${branch}`, remoteRef]);
+    }
+    else if ((await gitAllowFail(rootReal, ['merge-base', '--is-ancestor', remoteRef, 'HEAD'])).code !== 0) {
+        const merged = await gitAllowFail(rootReal, [...(await commitIdentity(rootReal)), 'merge', '--allow-unrelated-histories', '--no-edit', remoteRef], 60000);
+        if (merged.code !== 0) {
+            await gitAllowFail(rootReal, ['merge', '--abort']);
+            throw new GitWorkspaceError('git_command_failed', merged.stderr.trim() || 'git_merge_failed');
+        }
+    }
+    await git(rootReal, ['branch', `--set-upstream-to=origin/${branch}`, branch]);
+}
+async function unstage(rootReal, paths) {
+    if (paths.length === 0)
+        return;
+    const born = (await gitAllowFail(rootReal, ['rev-parse', '-q', '--verify', 'HEAD'])).code === 0;
+    for (let start = 0; start < paths.length; start += 100) {
+        const chunk = paths.slice(start, start + 100);
+        // Before the first commit there is no HEAD to reset to; dropping the entries does the same.
+        await git(rootReal, born ? ['reset', '-q', '--', ...chunk] : ['rm', '-q', '--cached', '--', ...chunk]);
+    }
+}
+/** A clone carries no committer; the sandbox image sets none either. */
+async function commitIdentity(rootReal) {
+    const email = await gitAllowFail(rootReal, ['config', 'user.email']);
+    if (email.code === 0 && email.stdout.trim())
+        return [];
+    return ['-c', 'user.name=PlayCraft Workspace', '-c', 'user.email=workspace@playcraft.local'];
+}
+/**
+ * The remote-tracking ref of the current branch. A fork clone has no fetch refspec for its own
+ * branch, so the ref is written here after a confirmed push.
+ */
+async function trackingRef(rootReal) {
+    const branch = (await gitAllowFail(rootReal, ['symbolic-ref', '--quiet', '--short', 'HEAD'])).stdout.trim();
+    return branch ? `refs/remotes/origin/${branch}` : undefined;
+}
+async function remoteHasHead(rootReal) {
+    const ref = await trackingRef(rootReal);
+    if (!ref)
+        return false;
+    const [head, tracked] = await Promise.all([
+        gitAllowFail(rootReal, ['rev-parse', '-q', '--verify', 'HEAD^{commit}']),
+        gitAllowFail(rootReal, ['rev-parse', '-q', '--verify', `${ref}^{commit}`]),
+    ]);
+    return head.code === 0 && tracked.code === 0 && head.stdout.trim() === tracked.stdout.trim();
+}
+async function recordPushedHead(rootReal) {
+    const ref = await trackingRef(rootReal);
+    if (ref)
+        await gitAllowFail(rootReal, ['update-ref', ref, 'HEAD']);
+}
+export async function ensureWorkspaceGit(root) {
+    const rootReal = await realpath(root);
+    if (!(await gitMarkerExists(rootReal))) {
+        const init = await gitAllowFail(rootReal, ['init']);
+        if (init.code !== 0) {
+            throw new GitWorkspaceError('git_command_failed', init.stderr.trim() || 'git_init_failed');
+        }
+        await git(rootReal, ['config', 'user.name', 'PlayCraft Workspace']);
+        await git(rootReal, ['config', 'user.email', 'workspace@playcraft.local']);
+    }
+    await assertWorkspaceGitRoot(rootReal);
+    await excludeFromGit(rootReal, '/.tmp/user_uploads/');
+    return rootReal;
+}
+/**
+ * The control user and the development user (terminal, Codex) both write this repository. Git
+ * creates directories with the writer's umask, so a directory one user made can refuse the
+ * other's objects. With `core.sharedRepository=group` Git makes new directories group-writable for
+ * both; the image puts the control user in the development group.
+ */
+export async function shareWorkspaceRepository(root) {
+    const rootReal = await existingWorkspaceGit(root);
+    const current = await gitAllowFail(rootReal, ['config', '--get', 'core.sharedRepository']);
+    if (current.stdout.trim() !== 'group')
+        await git(rootReal, ['config', 'core.sharedRepository', 'group']);
+}
+/** Turn snapshots never create a repository; a directory without one simply has no turn changes. */
+async function existingWorkspaceGit(root) {
+    const rootReal = await realpath(root);
+    if (!(await gitMarkerExists(rootReal)))
+        throw new GitWorkspaceError('git_command_failed', 'not_a_repository');
+    await assertWorkspaceGitRoot(rootReal);
+    return rootReal;
+}
+async function gitMarkerExists(rootReal) {
+    try {
+        await stat(join(rootReal, '.git'));
+        return true;
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return false;
+        throw error;
+    }
+}
+async function assertWorkspaceGitRoot(rootReal) {
+    const marker = join(rootReal, '.git');
+    const info = await stat(marker);
+    if (info.isDirectory()) {
+        assertInsideRoot(rootReal, await realpath(marker));
+        return;
+    }
+    if (info.isFile()) {
+        const text = await readFile(marker, 'utf8');
+        const match = /^gitdir:\s*(.+)$/m.exec(text);
+        if (!match)
+            throw new GitWorkspaceError('git_root_escape', 'invalid_gitdir');
+        const target = resolve(rootReal, match[1].trim());
+        assertInsideRoot(rootReal, await realpath(target));
+        return;
+    }
+    throw new GitWorkspaceError('git_root_escape', marker);
+}
+function assertInsideRoot(rootReal, target) {
+    const rel = relative(rootReal, target);
+    if (rel === '' || rel.startsWith(`..${sep}`) || rel === '..' || rel.startsWith('..')) {
+        throw new GitWorkspaceError('git_root_escape', target);
+    }
+}
+function parsePorcelain(raw) {
+    const parts = raw.split('\0').filter((part) => part.length > 0);
+    const files = [];
+    for (let i = 0; i < parts.length; i += 1) {
+        const entry = parts[i] ?? '';
+        if (entry.length < 3)
+            continue;
+        const indexStatus = entry[0] ?? ' ';
+        const worktreeStatus = entry[1] ?? ' ';
+        const pathPart = entry.slice(3);
+        if (indexStatus === 'R' || indexStatus === 'C' || worktreeStatus === 'R' || worktreeStatus === 'C') {
+            const dest = parts[i + 1] ?? pathPart;
+            i += 1;
+            files.push({ path: dest, indexStatus, worktreeStatus });
+            continue;
+        }
+        files.push({ path: pathPart, indexStatus, worktreeStatus });
+    }
+    return files;
+}
+/**
+ * `diff --numstat -z`: `added<TAB>removed<TAB>path<NUL>`, or for a rename an empty path followed by
+ * `old<NUL>new<NUL>`. Binary files report `-` and are left out.
+ */
+function parseNumstat(raw) {
+    const counts = new Map();
+    const parts = raw.split('\0');
+    for (let index = 0; index < parts.length; index += 1) {
+        const match = /^(\d+|-)\t(\d+|-)\t(.*)$/s.exec(parts[index] ?? '');
+        if (!match)
+            continue;
+        let path = match[3];
+        if (path === '') {
+            path = parts[index + 2] ?? '';
+            index += 2;
+        }
+        if (match[1] === '-' || !path)
+            continue;
+        counts.set(path, { added: Number(match[1]), removed: Number(match[2]) });
+    }
+    return counts;
+}
+async function git(root, args, timeoutMs = 15000) {
+    const result = await gitAllowFail(root, args, timeoutMs);
+    if (result.code !== 0) {
+        throw new GitWorkspaceError('git_command_failed', result.stderr.trim() || `git_exit_${result.code}`);
+    }
+    return result.stdout;
+}
+async function gitAllowFail(root, args, timeoutMs = 15000) {
+    return runGitProcess(root, [...GIT_PREFIX, `--git-dir=${join(root, '.git')}`, `--work-tree=${root}`, ...args], timeoutMs);
+}
+function gitEnv() {
+    const env = { ...process.env };
+    delete env.GIT_DIR;
+    delete env.GIT_WORK_TREE;
+    delete env.GIT_COMMON_DIR;
+    delete env.GIT_INDEX_FILE;
+    delete env.GIT_OBJECT_DIRECTORY;
+    delete env.GIT_ALTERNATE_OBJECT_DIRECTORIES;
+    env.GIT_OPTIONAL_LOCKS = '0';
+    env.GIT_TERMINAL_PROMPT = '0';
+    return env;
+}
+function runGitProcess(cwd, args, timeoutMs, env) {
+    return new Promise((resolve, reject) => {
+        const child = spawn('git', args, { cwd, env: { ...gitEnv(), ...env }, windowsHide: true });
+        // Chunks are decoded together; a character split across two chunks would otherwise be corrupted.
+        const stdout = [];
+        const stderr = [];
+        const timer = setTimeout(() => {
+            child.kill('SIGKILL');
+            reject(new GitWorkspaceError('git_command_failed', 'timeout'));
+        }, timeoutMs);
+        child.stdout.on('data', (chunk) => {
+            stdout.push(Buffer.from(chunk));
+        });
+        child.stderr.on('data', (chunk) => {
+            stderr.push(Buffer.from(chunk));
+        });
+        child.on('error', (error) => {
+            clearTimeout(timer);
+            if (error.code === 'ENOENT') {
+                reject(new GitWorkspaceError('git_binary_missing', 'git'));
+                return;
+            }
+            reject(error);
+        });
+        child.on('close', (code) => {
+            clearTimeout(timer);
+            resolve({
+                stdout: Buffer.concat(stdout).toString('utf8'),
+                stderr: Buffer.concat(stderr).toString('utf8'),
+                code: code ?? 1,
+            });
+        });
+    });
+}