@robota-sdk/agent-command 3.0.0-beta.82 → 3.0.0-beta.84

package/src/git/__tests__/git-process.test.ts

@@ -1,221 +0,0 @@
-/**
- * BEHAVIOR-2437 TC-04 — the seam against a REAL temporary repository: argv-only (metacharacters are
- * data), exit codes as data, stdin closed (a hook that reads it gets EOF), timeout / abort / missing
- * executable / oversized output as typed failures, and the hook-nesting environment policy.
- */
-import { execFileSync } from 'node:child_process';
-import { chmodSync, mkdtempSync, mkdirSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
-import { tmpdir } from 'node:os';
-import { join } from 'node:path';
-
-import { afterEach, describe, expect, it } from 'vitest';
-
-import { createGitProcess, gitEnvironment, GIT_ENV_DENYLIST } from '../git-process.js';
-
-const dirs: string[] = [];
-afterEach(() => {
-  for (const dir of dirs.splice(0)) rmSync(dir, { recursive: true, force: true });
-});
-
-function tempDir(prefix: string): string {
-  const dir = realpathSync(mkdtempSync(join(tmpdir(), prefix)));
-  dirs.push(dir);
-  return dir;
-}
-
-/** A hermetic environment: no user/system git config, no inherited hook-nesting variables. */
-function hermeticEnv(extra: Record<string, string> = {}): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = { PATH: process.env.PATH, HOME: tempDir('git-home-') };
-  env.GIT_CONFIG_NOSYSTEM = '1';
-  env.GIT_CONFIG_GLOBAL = join(env.HOME ?? '', 'gitconfig');
-  writeFileSync(env.GIT_CONFIG_GLOBAL, '[commit]\n\tgpgsign = false\n');
-  return { ...env, ...extra };
-}
-
-function git(cwd: string, env: NodeJS.ProcessEnv, ...args: string[]): string {
-  return execFileSync('git', args, {
-    cwd,
-    env,
-    encoding: 'utf8',
-    stdio: ['ignore', 'pipe', 'pipe'],
-  });
-}
-
-function initRepo(env: NodeJS.ProcessEnv, identity = true): string {
-  const repo = tempDir('git-seam-');
-  git(repo, env, 'init', '-q', '-b', 'main');
-  if (identity) {
-    git(repo, env, 'config', 'user.name', 'Seam Test');
-    git(repo, env, 'config', 'user.email', 'seam@example.com');
-  }
-  writeFileSync(join(repo, 'base.txt'), 'base\n');
-  git(repo, env, 'add', '--', 'base.txt');
-  if (identity) git(repo, env, 'commit', '-q', '-m', 'chore: base');
-  return repo;
-}
-
-function installHook(repo: string, name: string, body: string): void {
-  const hooks = join(repo, '.git', 'hooks');
-  mkdirSync(hooks, { recursive: true });
-  const path = join(hooks, name);
-  writeFileSync(path, `#!/bin/sh\n${body}\n`);
-  chmodSync(path, 0o755);
-}
-
-describe('gitEnvironment', () => {
-  it('strips the repository-redirecting variables and preserves identity and config by name', () => {
-    const source: NodeJS.ProcessEnv = {
-      PATH: '/usr/bin',
-      XDG_CONFIG_HOME: '/x',
-      GIT_CONFIG_GLOBAL: '/g',
-      GIT_AUTHOR_NAME: 'a',
-      GIT_AUTHOR_EMAIL: 'a@x',
-      GIT_COMMITTER_NAME: 'c',
-      GIT_COMMITTER_EMAIL: 'c@x',
-      EMAIL: 'e@x',
-      GPG_TTY: '/dev/tty',
-      GNUPGHOME: '/gnupg',
-      SSH_AUTH_SOCK: '/sock',
-    };
-    for (const key of GIT_ENV_DENYLIST) source[key] = `/elsewhere/${key}`;
-    const env = gitEnvironment(source);
-    for (const key of GIT_ENV_DENYLIST) expect(env).not.toHaveProperty(key);
-    for (const key of [
-      'PATH',
-      'XDG_CONFIG_HOME',
-      'GIT_CONFIG_GLOBAL',
-      'GIT_AUTHOR_NAME',
-      'GIT_AUTHOR_EMAIL',
-      'GIT_COMMITTER_NAME',
-      'GIT_COMMITTER_EMAIL',
-      'EMAIL',
-      'GPG_TTY',
-      'GNUPGHOME',
-      'SSH_AUTH_SOCK',
-    ]) {
-      expect(env[key]).toBe(source[key]);
-    }
-  });
-});
-
-describe('createGitProcess against a real repository', () => {
-  it('returns exit codes as data: diff --cached --quiet is 1 when staged, 0 when not', async () => {
-    const env = hermeticEnv();
-    const repo = initRepo(env);
-    const port = createGitProcess({ env });
-    expect(await port.run(['diff', '--cached', '--quiet'], { cwd: repo })).toMatchObject({
-      kind: 'exited',
-      exitCode: 0,
-    });
-    writeFileSync(join(repo, 'new.txt'), 'new\n');
-    git(repo, env, 'add', '--', 'new.txt');
-    expect(await port.run(['diff', '--cached', '--quiet'], { cwd: repo })).toMatchObject({
-      kind: 'exited',
-      exitCode: 1,
-    });
-  });
-
-  it('passes a subject and a path with shell metacharacters as ONE element each (shell: false)', async () => {
-    const env = hermeticEnv();
-    const repo = initRepo(env);
-    const port = createGitProcess({ env });
-    const path = 'a;b c$(touch pwned-path).txt';
-    const subject = 'feat: $(touch pwned) ; echo "quoted" `id` | cat > /dev/null';
-    writeFileSync(join(repo, path), 'x\n');
-    expect(await port.run(['add', '--', path], { cwd: repo })).toMatchObject({ exitCode: 0 });
-    expect(await port.run(['commit', '-m', subject], { cwd: repo })).toMatchObject({ exitCode: 0 });
-    const log = await port.run(['log', '-1', '--format=%s'], { cwd: repo });
-    expect(log).toMatchObject({ kind: 'exited', exitCode: 0, stdout: `${subject}\n` });
-    const status = await port.run(['status', '--porcelain=v2', '-z'], { cwd: repo });
-    expect(status).toMatchObject({ kind: 'exited', exitCode: 0 });
-    // Neither substitution ran: the tree holds only what git was told, and nothing named pwned.
-    if (status.kind === 'exited') expect(status.stdout).not.toContain('pwned');
-    const shown = await port.run(['show', '--name-only', '--format=', 'HEAD'], { cwd: repo });
-    if (shown.kind === 'exited') expect(shown.stdout.trim()).toBe(path);
-  });
-
-  it('closes stdin: a pre-commit hook that reads it sees EOF instead of hanging', async () => {
-    const env = hermeticEnv();
-    const repo = initRepo(env);
-    installHook(repo, 'pre-commit', 'cat > /dev/null\nexit 0');
-    writeFileSync(join(repo, 'new.txt'), 'new\n');
-    git(repo, env, 'add', '--', 'new.txt');
-    const port = createGitProcess({ env });
-    const outcome = await port.run(['commit', '-m', 'feat: hooked'], {
-      cwd: repo,
-      timeoutMs: 5000,
-    });
-    expect(outcome).toMatchObject({ kind: 'exited', exitCode: 0 });
-  });
-
-  it('kills a child that exceeds the timeout and reports failed: timeout', async () => {
-    const env = hermeticEnv();
-    const repo = initRepo(env);
-    installHook(repo, 'pre-commit', 'exec >/dev/null 2>&1\nsleep 5');
-    writeFileSync(join(repo, 'new.txt'), 'new\n');
-    git(repo, env, 'add', '--', 'new.txt');
-    const port = createGitProcess({ env });
-    const outcome = await port.run(['commit', '-m', 'feat: slow'], { cwd: repo, timeoutMs: 300 });
-    expect(outcome).toMatchObject({ kind: 'failed', reason: 'timeout' });
-    expect(git(repo, env, 'log', '--oneline').trim().split('\n')).toHaveLength(1);
-  });
-
-  it('reports an aborted signal as failed: aborted', async () => {
-    const env = hermeticEnv();
-    const repo = initRepo(env);
-    installHook(repo, 'pre-commit', 'exec >/dev/null 2>&1\nsleep 5');
-    writeFileSync(join(repo, 'new.txt'), 'new\n');
-    git(repo, env, 'add', '--', 'new.txt');
-    const port = createGitProcess({ env });
-    const controller = new AbortController();
-    const pending = port.run(['commit', '-m', 'feat: aborted'], {
-      cwd: repo,
-      timeoutMs: 10_000,
-      signal: controller.signal,
-    });
-    setTimeout(() => controller.abort(), 100);
-    expect(await pending).toMatchObject({ kind: 'failed', reason: 'aborted' });
-  });
-
-  it('reports a missing executable as failed: not-found', async () => {
-    const env = hermeticEnv();
-    const repo = initRepo(env);
-    const port = createGitProcess({ env, executable: join(repo, 'no-such-git') });
-    const outcome = await port.run(['status'], { cwd: repo });
-    expect(outcome).toMatchObject({ kind: 'failed', reason: 'not-found' });
-    if (outcome.kind === 'failed') expect(outcome.detail).toContain('ENOENT');
-  });
-
-  it('reports output past 16 MiB as failed: output-too-large', async () => {
-    const env = hermeticEnv();
-    const dir = tempDir('git-big-');
-    const fake = join(dir, 'big-git');
-    writeFileSync(fake, '#!/bin/sh\nhead -c 17000000 /dev/zero\n');
-    chmodSync(fake, 0o755);
-    const port = createGitProcess({ env, executable: fake });
-    const outcome = await port.run(['status'], { cwd: dir, timeoutMs: 20_000 });
-    expect(outcome).toMatchObject({ kind: 'failed', reason: 'output-too-large' });
-  });
-
-  it('a hook-exported GIT_DIR does not redirect the child; GIT_CONFIG_GLOBAL still carries identity', async () => {
-    const env = hermeticEnv();
-    const other = initRepo(env);
-    const repo = initRepo(env, false);
-    writeFileSync(
-      env.GIT_CONFIG_GLOBAL ?? '',
-      '[commit]\n\tgpgsign = false\n[user]\n\tname = Global Identity\n\temail = global@example.com\n',
-    );
-    // A hook-style environment: GIT_DIR points at ANOTHER repository.
-    const port = createGitProcess({
-      env: { ...env, GIT_DIR: join(other, '.git'), GIT_WORK_TREE: other },
-    });
-    const top = await port.run(['rev-parse', '--show-toplevel'], { cwd: repo });
-    expect(top).toMatchObject({ kind: 'exited', exitCode: 0, stdout: `${repo}\n` });
-    const commit = await port.run(['commit', '-m', 'feat: identity'], { cwd: repo });
-    expect(commit).toMatchObject({ kind: 'exited', exitCode: 0 });
-    const author = await port.run(['log', '-1', '--format=%an <%ae>'], { cwd: repo });
-    expect(author).toMatchObject({ stdout: 'Global Identity <global@example.com>\n' });
-    // The other repository is untouched: still exactly its base commit.
-    expect(git(other, env, 'log', '--oneline').trim().split('\n')).toHaveLength(1);
-  });
-});

package/src/git/__tests__/git-status.test.ts

@@ -1,117 +0,0 @@
-/** BEHAVIOR-2437 TC-01 — `/git status`: one porcelain-v2 call, parsed into the four groups. */
-import { describe, expect, it } from 'vitest';
-
-import { executeGitStatus, formatGitStatus, parseStatusPorcelainV2 } from '../git-status.js';
-
-import { exited, fakeGitPort } from './fake-git-port.js';
-
-const H = '0000000000000000000000000000000000000000';
-const rec = (parts: string[]): string => `${parts.join(' ')}\0`;
-/** Captured from a real `git status --porcelain=v2 -z --branch` run, plus the edge paths. */
-const FIXTURE =
-  rec(['#', 'branch.oid', H]) +
-  rec(['#', 'branch.head', 'main']) +
-  rec(['1', 'MM', 'N...', '100644', '100644', '100644', H, H, 'a.txt']) +
-  rec(['2', 'R.', 'N...', '100644', '100644', '100644', H, H, 'R100', 'new.txt']) +
-  'old.txt\0' +
-  rec(['1', '.M', 'N...', '100644', '100644', '100644', H, H, 'sp ace.txt']) +
-  rec(['1', 'A.', 'N...', '000000', '100644', '100644', H, H, 'quo"te.txt']) +
-  rec(['1', 'A.', 'N...', '000000', '100644', '100644', H, H, '한글 파일.txt']) +
-  rec(['?', 'untracked.txt']);
-
-describe('parseStatusPorcelainV2', () => {
-  it('yields the branch and the staged, unstaged and untracked sets, one element per path', () => {
-    const summary = parseStatusPorcelainV2(FIXTURE);
-    expect(summary.branch).toBe('main');
-    expect(summary.unborn).toBe(false);
-    // The MM entry is in BOTH sets; the rename pair stays a pair; each edge path is one element.
-    expect(summary.staged).toEqual([
-      'a.txt',
-      'new.txt (from old.txt)',
-      'quo"te.txt',
-      '한글 파일.txt',
-    ]);
-    expect(summary.unstaged).toEqual(['a.txt', 'sp ace.txt']);
-    expect(summary.untracked).toEqual(['untracked.txt']);
-    expect(summary.conflicted).toEqual([]);
-  });
-
-  it('reads an unborn branch and a detached HEAD', () => {
-    expect(
-      parseStatusPorcelainV2(
-        rec(['#', 'branch.oid', '(initial)']) + rec(['#', 'branch.head', 'main']),
-      ),
-    ).toMatchObject({ branch: 'main', unborn: true });
-    expect(parseStatusPorcelainV2(rec(['#', 'branch.head', '(detached)'])).branch).toBe(
-      '(detached)',
-    );
-  });
-
-  it('collects unmerged entries separately', () => {
-    const fixture = rec([
-      'u',
-      'UU',
-      'N...',
-      '100644',
-      '100644',
-      '100644',
-      '100644',
-      H,
-      H,
-      H,
-      'c.txt',
-    ]);
-    expect(parseStatusPorcelainV2(fixture).conflicted).toEqual(['c.txt']);
-  });
-});
-
-describe('formatGitStatus', () => {
-  it('prints the branch and each group with its count', () => {
-    expect(formatGitStatus(parseStatusPorcelainV2(FIXTURE))).toBe(
-      [
-        'On branch main',
-        'staged (4): a.txt, new.txt (from old.txt), quo"te.txt, 한글 파일.txt',
-        'unstaged (2): a.txt, sp ace.txt',
-        'untracked (1): untracked.txt',
-      ].join('\n'),
-    );
-  });
-});
-
-describe('executeGitStatus', () => {
-  it('runs exactly one porcelain-v2 call and reports the summary', async () => {
-    const port = fakeGitPort({ 'status --porcelain=v2 -z --branch': exited(FIXTURE) });
-    const result = await executeGitStatus(port, '/repo');
-    expect(port.calls).toEqual([['status', '--porcelain=v2', '-z', '--branch']]);
-    expect(result.success).toBe(true);
-    expect(result.message).toContain('On branch main');
-    expect(result.data).toMatchObject({ git: 'status', untracked: ['untracked.txt'] });
-  });
-
-  it('reports git’s own reason on exit 128 and makes no second call', async () => {
-    const port = fakeGitPort({
-      'status --porcelain=v2 -z --branch': exited(
-        '',
-        128,
-        'fatal: not a git repository (or any of the parent directories): .git\n',
-      ),
-    });
-    const result = await executeGitStatus(port, '/not-a-repo');
-    expect(result.success).toBe(false);
-    expect(result.message).toContain('fatal: not a git repository');
-    expect(port.calls).toHaveLength(1);
-  });
-
-  it('reports a spawn failure by its reason', async () => {
-    const port = fakeGitPort({
-      'status --porcelain=v2 -z --branch': {
-        kind: 'failed',
-        reason: 'not-found',
-        detail: 'git could not be run (ENOENT)',
-      },
-    });
-    const result = await executeGitStatus(port, '/repo');
-    expect(result.success).toBe(false);
-    expect(result.message).toContain('ENOENT');
-  });
-});

package/src/git/git-diff.ts

@@ -1,129 +0,0 @@
-/**
- * BEHAVIOR-2437: `/git diff` — a closed grammar, not a pass-through for git flags.
- *
- * `/git diff` (unstaged) · `/git diff --staged` (index vs HEAD) · `/git diff <rev>` (worktree vs rev)
- * · `/git diff <a>..<b>` (two revisions), each optionally followed by `-- <path>…`. Every revision is
- * verified with `rev-parse --verify --quiet --end-of-options <rev>^{commit}` before any diff runs;
- * any other `-` token is refused, because a flag is exactly how an argv element becomes an option.
- * In the argv git receives, `--end-of-options` precedes every user revision and `--` every path.
- */
-import { gitFailureMessage } from './git-process.js';
-
-import type { IGitProcessPort } from './git-process.js';
-import type { ICommandResult } from '@robota-sdk/agent-interface-command';
-
-export const GIT_DIFF_USAGE =
-  'Usage: /git diff [--staged | <rev> | <a>..<b>] [-- <path> ...] — other git flags are not accepted here.';
-
-export type TGitDiffTarget =
-  | { kind: 'worktree' }
-  | { kind: 'staged' }
-  | { kind: 'revision'; revision: string }
-  | { kind: 'range'; from: string; to: string };
-
-export interface IGitDiffArgs {
-  target: TGitDiffTarget;
-  paths: readonly string[];
-}
-
-export type TParseGitDiffArgs = { ok: true; args: IGitDiffArgs } | { ok: false; message: string };
-
-function refuse(reason: string): TParseGitDiffArgs {
-  return { ok: false, message: `${reason}\n${GIT_DIFF_USAGE}` };
-}
-
-export function parseGitDiffArgs(tokens: readonly string[]): TParseGitDiffArgs {
-  const separator = tokens.indexOf('--');
-  const head = separator === -1 ? tokens : tokens.slice(0, separator);
-  const paths = separator === -1 ? [] : tokens.slice(separator + 1);
-  if (separator !== -1 && paths.length === 0) return refuse('`--` must be followed by a path.');
-
-  const flag = head.find((token) => token.startsWith('-') && token !== '--staged');
-  if (flag !== undefined) return refuse(`\`${flag}\` is not accepted.`);
-  if (head.length > 1) return refuse(`Too many arguments: ${head.join(' ')}.`);
-
-  const token = head[0];
-  if (token === undefined) return { ok: true, args: { target: { kind: 'worktree' }, paths } };
-  if (token === '--staged') return { ok: true, args: { target: { kind: 'staged' }, paths } };
-  if (token.includes('..')) {
-    if (token.includes('...')) return refuse(`\`${token}\` is not a \`<a>..<b>\` range.`);
-    const parts = token.split('..');
-    const [from, to] = parts;
-    if (parts.length !== 2 || !from || !to) {
-      return refuse(`\`${token}\` is not a \`<a>..<b>\` range.`);
-    }
-    return { ok: true, args: { target: { kind: 'range', from, to }, paths } };
-  }
-  return { ok: true, args: { target: { kind: 'revision', revision: token }, paths } };
-}
-
-/** The revisions a target names, in the order they are verified. */
-function revisionsOf(target: TGitDiffTarget): readonly string[] {
-  switch (target.kind) {
-    case 'revision':
-      return [target.revision];
-    case 'range':
-      return [target.from, target.to];
-    default:
-      return [];
-  }
-}
-
-/** The `diff` argv for a parsed target, `--end-of-options` before revisions and `--` before paths. */
-export function gitDiffArgv(args: IGitDiffArgs): readonly string[] {
-  const argv = ['diff'];
-  switch (args.target.kind) {
-    case 'staged':
-      argv.push('--staged');
-      break;
-    case 'revision':
-      argv.push('--end-of-options', args.target.revision);
-      break;
-    case 'range':
-      argv.push('--end-of-options', `${args.target.from}..${args.target.to}`);
-      break;
-    default:
-      break;
-  }
-  if (args.paths.length > 0) argv.push('--', ...args.paths);
-  return argv;
-}
-
-function gitRevParseArgv(revision: string): readonly string[] {
-  return ['rev-parse', '--verify', '--quiet', '--end-of-options', `${revision}^{commit}`];
-}
-
-function tokenizeGitArgs(args: string): string[] {
-  return args.split(/\s+/).filter((token) => token.length > 0);
-}
-
-export async function executeGitDiff(
-  port: IGitProcessPort,
-  cwd: string,
-  args: string,
-): Promise<ICommandResult> {
-  const parsed = parseGitDiffArgs(tokenizeGitArgs(args));
-  if (!parsed.ok) return { success: false, message: parsed.message };
-
-  for (const revision of revisionsOf(parsed.args.target)) {
-    const outcome = await port.run(gitRevParseArgv(revision), { cwd });
-    if (outcome.kind === 'failed') {
-      return { success: false, message: gitFailureMessage('rev-parse', outcome) ?? 'git failed' };
-    }
-    if (outcome.exitCode !== 0) {
-      return { success: false, message: `Unknown revision: ${revision}` };
-    }
-  }
-
-  const outcome = await port.run(gitDiffArgv(parsed.args), { cwd });
-  const failure = gitFailureMessage('diff', outcome);
-  if (failure !== undefined || outcome.kind !== 'exited') {
-    return { success: false, message: failure ?? 'git diff failed' };
-  }
-  const diff = outcome.stdout.replace(/\n$/, '');
-  return {
-    success: true,
-    message: diff.length > 0 ? diff : 'No differences.',
-    data: { git: 'diff', target: parsed.args.target, paths: parsed.args.paths },
-  };
-}

package/src/git/git-process.ts

@@ -1,169 +0,0 @@
-/**
- * BEHAVIOR-2437: the one seam every `/git` verb runs git through.
- *
- * argv only — `execFile` with `shell: false`, so no user token is ever parsed as shell syntax; stdin
- * is closed at once, so a hook that reads it sees EOF instead of hanging; output is capped, the child
- * is bounded by a timeout, and every way a run can end is a typed outcome rather than a throw. Exit
- * codes are DATA: `diff --cached --quiet` answers with 1, and that is an answer, not an error.
- */
-import { execFile } from 'node:child_process';
-import { constants } from 'node:os';
-
-import type { ExecFileException } from 'node:child_process';
-
-export const GIT_DEFAULT_TIMEOUT_MS = 120_000;
-const BYTES_PER_KIB = 1024;
-const OUTPUT_CAP_MIB = 16;
-export const GIT_MAX_OUTPUT_BYTES = OUTPUT_CAP_MIB * BYTES_PER_KIB * BYTES_PER_KIB;
-/** The shell convention for a signal-terminated child: 128 + the signal number. */
-const SIGNAL_EXIT_BASE = 128;
-
-/**
- * Variables that redirect a git child to ANOTHER repository. Git exports them into hooks, so a
- * `/git` run started from inside a hook (or from any process that inherited one) would otherwise
- * operate on the wrong tree. Identity and configuration variables are deliberately NOT here — the
- * user's `GIT_CONFIG_GLOBAL`, `GIT_AUTHOR_*`, `GPG_TTY`, `SSH_AUTH_SOCK` … are what make the commit
- * theirs.
- */
-export const GIT_ENV_DENYLIST: readonly string[] = [
-  'GIT_DIR',
-  'GIT_WORK_TREE',
-  'GIT_INDEX_FILE',
-  'GIT_OBJECT_DIRECTORY',
-  'GIT_ALTERNATE_OBJECT_DIRECTORIES',
-  'GIT_COMMON_DIR',
-  'GIT_PREFIX',
-  'GIT_NAMESPACE',
-];
-
-export interface IGitProcessRunOptions {
-  cwd: string;
-  timeoutMs?: number;
-  signal?: AbortSignal;
-}
-
-/**
- * `not-found` covers every spawn failure — ENOENT, EACCES, ENOTDIR, … — with the code in `detail`;
- * the other three are the run's own bounds.
- */
-export type TGitProcessFailureReason = 'not-found' | 'timeout' | 'aborted' | 'output-too-large';
-
-export type TGitProcessOutcome =
-  | { kind: 'exited'; stdout: string; stderr: string; exitCode: number }
-  | { kind: 'failed'; reason: TGitProcessFailureReason; detail: string };
-
-export interface IGitProcessPort {
-  run(args: readonly string[], options: IGitProcessRunOptions): Promise<TGitProcessOutcome>;
-}
-
-export interface ICreateGitProcessOptions {
-  /** The executable to run; `git` on PATH by default. */
-  executable?: string;
-  /** The environment to derive the child's from; the live process environment by default. */
-  env?: NodeJS.ProcessEnv;
-}
-
-/** The child's environment: `source` minus the repository-redirecting variables. */
-export function gitEnvironment(source: NodeJS.ProcessEnv = process.env): NodeJS.ProcessEnv {
-  const env: NodeJS.ProcessEnv = {};
-  for (const [key, value] of Object.entries(source)) {
-    if (!GIT_ENV_DENYLIST.includes(key)) env[key] = value;
-  }
-  return env;
-}
-
-function failed(reason: TGitProcessFailureReason, detail: string): TGitProcessOutcome {
-  return { kind: 'failed', reason, detail };
-}
-
-function signalNumber(signal: NodeJS.Signals): number {
-  return constants.signals[signal] ?? 0;
-}
-
-function toOutcome(
-  error: ExecFileException | null,
-  stdout: string,
-  stderr: string,
-  context: { executable: string; timeoutMs: number; signal: AbortSignal | undefined },
-): TGitProcessOutcome {
-  if (error === null) return { kind: 'exited', stdout, stderr, exitCode: 0 };
-  if (context.signal?.aborted === true || error.name === 'AbortError') {
-    return failed('aborted', 'the run was aborted before git exited');
-  }
-  if (error.code === 'ERR_CHILD_PROCESS_STDIO_MAXBUFFER') {
-    return failed(
-      'output-too-large',
-      `git produced more than ${OUTPUT_CAP_MIB} MiB of output and was stopped`,
-    );
-  }
-  // Our own kill wins over whatever exit the child managed on the way down (a shell trap exiting
-  // 143 is still a timeout).
-  if (error.killed === true) {
-    return failed('timeout', `git did not exit within ${context.timeoutMs} ms and was stopped`);
-  }
-  if (typeof error.code === 'number')
-    return { kind: 'exited', stdout, stderr, exitCode: error.code };
-  if (error.signal) {
-    // RUNTIME-53 convention: a signal-terminated child reports 128 + the signal number.
-    return {
-      kind: 'exited',
-      stdout,
-      stderr,
-      exitCode: SIGNAL_EXIT_BASE + signalNumber(error.signal),
-    };
-  }
-  return failed(
-    'not-found',
-    `${context.executable} could not be run (${String(error.code ?? error.message)})`,
-  );
-}
-
-/** The production port: argv-only `execFile`, stdin closed, output capped, timeout bounded. */
-export function createGitProcess(options: ICreateGitProcessOptions = {}): IGitProcessPort {
-  const executable = options.executable ?? 'git';
-  return {
-    run(args, runOptions) {
-      const timeoutMs = runOptions.timeoutMs ?? GIT_DEFAULT_TIMEOUT_MS;
-      const env = gitEnvironment(options.env ?? process.env);
-      return new Promise<TGitProcessOutcome>((resolve) => {
-        const child = execFile(
-          executable,
-          [...args],
-          {
-            cwd: runOptions.cwd,
-            env,
-            shell: false,
-            encoding: 'utf8',
-            timeout: timeoutMs,
-            maxBuffer: GIT_MAX_OUTPUT_BYTES,
-            windowsHide: true,
-            ...(runOptions.signal ? { signal: runOptions.signal } : {}),
-          },
-          (error, stdout, stderr) =>
-            resolve(
-              toOutcome(error, stdout, stderr, {
-                executable,
-                timeoutMs,
-                signal: runOptions.signal,
-              }),
-            ),
-        );
-        // stdin is a pipe by default; closing it at once turns a hook's read into EOF.
-        child.stdin?.end();
-      });
-    },
-  };
-}
-
-/**
- * The reason a run did not produce a usable answer, for the verbs where a non-zero exit IS a failure.
- * `undefined` when the child exited 0.
- */
-export function gitFailureMessage(verb: string, outcome: TGitProcessOutcome): string | undefined {
-  if (outcome.kind === 'failed') return `git ${verb} failed: ${outcome.detail}`;
-  if (outcome.exitCode === 0) return undefined;
-  const stderr = outcome.stderr.trim();
-  return stderr.length > 0
-    ? `git ${verb} failed (exit ${outcome.exitCode}): ${stderr}`
-    : `git ${verb} failed (exit ${outcome.exitCode})`;
-}