@robota-sdk/agent-command 3.0.0-beta.79 → 3.0.0-beta.81

package/src/git/git-command-module.ts

@@ -0,0 +1,139 @@
+/**
+ * BEHAVIOR-2437: `/git` — one command whose `execute` parses its verb (`status` | `diff` | `commit`),
+ * with the three verbs on `subcommands` for `/help` and autocomplete. Host-only (`modelInvocable:
+ * false`); the confirmation lives in the `commit` verb, because `requiresPermission` is not enforced
+ * on the user path (`SystemCommandExecutor.executeCommand` calls `execute` directly).
+ */
+import { executeGitCommit } from './git-commit.js';
+import { executeGitDiff } from './git-diff.js';
+import { createGitProcess } from './git-process.js';
+import { executeGitStatus } from './git-status.js';
+
+import type { IGitProcessPort } from './git-process.js';
+import type {
+  ICommandHostUserInteraction,
+  ICommandHostWorkspace,
+  ICommandModule,
+  ISystemCommand,
+} from '@robota-sdk/agent-framework';
+import type { ICommand, ICommandResult, ICommandSource } from '@robota-sdk/agent-interface-command';
+
+export const GIT_COMMAND_DESCRIPTION =
+  'Show the git status, view a diff, or commit the staged changes after confirming';
+export const GIT_COMMAND_ARGUMENT_HINT =
+  'status | diff [--staged | <rev> | <a>..<b>] [-- <path> ...] | commit [<subject>]';
+export const GIT_COMMAND_USAGE =
+  'Usage: /git status | /git diff [--staged | <rev> | <a>..<b>] [-- <path> ...] | /git commit [<subject>]';
+
+const SOURCE = 'git';
+
+function verbEntry(name: string, description: string, argumentHint?: string): ICommand {
+  return {
+    name,
+    description,
+    source: SOURCE,
+    modelInvocable: false,
+    ...(argumentHint ? { argumentHint } : {}),
+  };
+}
+
+export function createGitCommandEntry(): ICommand {
+  return {
+    name: 'git',
+    displayName: 'Git',
+    description: GIT_COMMAND_DESCRIPTION,
+    source: SOURCE,
+    modelInvocable: false,
+    argumentHint: GIT_COMMAND_ARGUMENT_HINT,
+    subcommands: [
+      verbEntry('status', 'Show the branch and the staged, unstaged and untracked paths'),
+      verbEntry(
+        'diff',
+        'Show the unstaged diff, the staged diff, or a diff against one or two revisions',
+        '[--staged | <rev> | <a>..<b>] [-- <path> ...]',
+      ),
+      verbEntry(
+        'commit',
+        'Commit the staged changes with a Conventional Commits subject, after confirming',
+        '[<subject>]',
+      ),
+    ],
+  };
+}
+
+/** What the verbs need from the host: the working directory and the ask-the-user port. */
+export type TGitCommandContext = Pick<ICommandHostWorkspace, 'getCwd'> &
+  ICommandHostUserInteraction;
+
+export async function executeGitCommand(
+  context: TGitCommandContext,
+  args: string,
+  port: IGitProcessPort = createGitProcess(),
+): Promise<ICommandResult> {
+  const trimmed = args.trim();
+  const split = trimmed.search(/\s/);
+  const verb = split === -1 ? trimmed : trimmed.slice(0, split);
+  const rest = split === -1 ? '' : trimmed.slice(split + 1).trim();
+  const cwd = context.getCwd();
+
+  switch (verb) {
+    case 'status':
+      if (rest.length > 0) {
+        return {
+          success: false,
+          message: `\`/git status\` takes no arguments.\n${GIT_COMMAND_USAGE}`,
+        };
+      }
+      return executeGitStatus(port, cwd);
+    case 'diff':
+      return executeGitDiff(port, cwd, rest);
+    case 'commit':
+      return executeGitCommit(port, cwd, rest, context.getUserInteraction());
+    default:
+      return {
+        success: false,
+        message:
+          verb.length === 0
+            ? GIT_COMMAND_USAGE
+            : `Unknown /git verb "${verb}".\n${GIT_COMMAND_USAGE}`,
+      };
+  }
+}
+
+function createGitSystemCommand(port: IGitProcessPort): ISystemCommand {
+  const entry = createGitCommandEntry();
+  return {
+    name: entry.name,
+    displayName: entry.displayName,
+    description: entry.description,
+    argumentHint: entry.argumentHint,
+    example: '/git status',
+    subcommands: entry.subcommands,
+    requiresPermission: true,
+    userInvocable: true,
+    modelInvocable: false,
+    lifecycle: 'blocking',
+    execute: (context, args) => executeGitCommand(context, args, port),
+  };
+}
+
+export class GitCommandSource implements ICommandSource {
+  readonly name = SOURCE;
+
+  getCommands(): ICommand[] {
+    return [createGitCommandEntry()];
+  }
+}
+
+export interface IGitCommandModuleOptions {
+  /** The process seam; the production `createGitProcess()` by default, injectable for tests. */
+  port?: IGitProcessPort;
+}
+
+export function createGitCommandModule(options: IGitCommandModuleOptions = {}): ICommandModule {
+  return {
+    name: 'agent-command-git',
+    commandSources: [new GitCommandSource()],
+    systemCommands: [createGitSystemCommand(options.port ?? createGitProcess())],
+  };
+}

package/src/git/git-commit.ts

@@ -0,0 +1,251 @@
+/**
+ * BEHAVIOR-2437: `/git commit [<subject>]` — the staged set, and only ever the staged set.
+ *
+ * No `-a`, no `add`, no paths. Nothing staged is answered with guidance that says why; the subject
+ * is held to the Conventional Commits v1.0.0 MUST rules and nothing more (the commitlint conventions
+ * are warnings, never refusals); the confirmation lists the message and exactly the files
+ * `git diff --cached --name-status` reports; an absent `IUserInteraction` is a cancellation — the
+ * `/doctor repair` precedent — never a guess. Only after "Yes" does `git commit -m <subject>` run.
+ */
+import { confirmAction, isConfirmed, textAction } from '@robota-sdk/agent-core';
+
+import { gitFailureMessage } from './git-process.js';
+import { parseStatusPorcelainV2, GIT_STATUS_ARGS } from './git-status.js';
+
+import type { IGitProcessPort } from './git-process.js';
+import type { IUserInteraction } from '@robota-sdk/agent-core';
+import type { ICommandResult } from '@robota-sdk/agent-interface-command';
+
+const GIT_COMMIT_CONVENTIONAL_TYPES: readonly string[] = [
+  'build',
+  'chore',
+  'ci',
+  'docs',
+  'feat',
+  'fix',
+  'perf',
+  'refactor',
+  'revert',
+  'style',
+  'test',
+];
+const GIT_COMMIT_SUBJECT_LIMIT = 72;
+
+export type TConventionalSubjectCheck =
+  { ok: true; warnings: readonly string[] } | { ok: false; reason: string };
+
+/** `<type>[(scope)][!]: <description>` — the MUST rules, and only those. */
+const CONVENTIONAL_SUBJECT = /^([^\s():!]+)(\(([^\s()]+)\))?(!)?: (.*)$/;
+
+export function validateConventionalSubject(subject: string): TConventionalSubjectCheck {
+  if (subject.trim().length === 0) return { ok: false, reason: 'the subject is empty' };
+  const separator = subject.indexOf(': ');
+  if (separator === -1) {
+    return {
+      ok: false,
+      reason:
+        'the subject has no `: ` type separator — the form is `<type>[(scope)][!]: <description>`',
+    };
+  }
+  const match = CONVENTIONAL_SUBJECT.exec(subject);
+  if (!match) {
+    return {
+      ok: false,
+      reason:
+        'the part before `: ` must be a type word with an optional `(scope)` and `!` — the form is `<type>[(scope)][!]: <description>`',
+    };
+  }
+  const type = match[1] ?? '';
+  const description = match[5] ?? '';
+  if (description.trim().length === 0) {
+    return { ok: false, reason: 'the description after `: ` is empty' };
+  }
+  const warnings: string[] = [];
+  if (!GIT_COMMIT_CONVENTIONAL_TYPES.includes(type)) {
+    warnings.push(
+      `type "${type}" is not one of the conventional types (${GIT_COMMIT_CONVENTIONAL_TYPES.join(', ')})`,
+    );
+  }
+  if (subject.length > GIT_COMMIT_SUBJECT_LIMIT) {
+    warnings.push(
+      `the subject is ${subject.length} characters; ${GIT_COMMIT_SUBJECT_LIMIT} is the conventional limit`,
+    );
+  }
+  if (subject.endsWith('.')) warnings.push('the subject ends with a period');
+  return { ok: true, warnings };
+}
+
+/** The inline subject: an optional leading `-m`, then one matching pair of outer quotes stripped. */
+export function normalizeCommitSubject(args: string): string {
+  let subject = args.trim();
+  if (subject === '-m') return '';
+  if (subject.startsWith('-m ')) subject = subject.slice('-m '.length).trim();
+  if (
+    subject.length >= 2 &&
+    (subject.startsWith('"') || subject.startsWith("'")) &&
+    subject.endsWith(subject[0] ?? '')
+  ) {
+    subject = subject.slice(1, -1).trim();
+  }
+  return subject;
+}
+
+function cancelled(message: string): ICommandResult {
+  return { success: false, message, data: { git: 'commit', committed: false } };
+}
+
+async function askSubject(ui: IUserInteraction): Promise<string | undefined> {
+  const response = await ui.ask(
+    textAction('git-commit-subject', 'Commit message', {
+      description: 'Conventional Commits form: <type>[(scope)][!]: <description>',
+      placeholder: 'feat: describe the change',
+    }),
+  );
+  if (response.type !== 'answer') return undefined;
+  const text = response.text ?? response.values[0] ?? '';
+  return normalizeCommitSubject(text);
+}
+
+type TStagedCheck = { staged: true } | { staged: false; result: ICommandResult };
+
+/** Step 1 — the staged set decides everything; exit 1 means something is staged. */
+async function checkStaged(port: IGitProcessPort, cwd: string): Promise<TStagedCheck> {
+  const staged = await port.run(['diff', '--cached', '--quiet'], { cwd });
+  if (staged.kind === 'failed' || (staged.exitCode !== 0 && staged.exitCode !== 1)) {
+    return {
+      staged: false,
+      result: {
+        success: false,
+        message: gitFailureMessage('diff --cached', staged) ?? 'git failed',
+      },
+    };
+  }
+  if (staged.exitCode === 1) return { staged: true };
+  const status = await port.run(GIT_STATUS_ARGS, { cwd });
+  const failure = gitFailureMessage('status', status);
+  if (failure !== undefined || status.kind !== 'exited') {
+    return { staged: false, result: { success: false, message: failure ?? 'git status failed' } };
+  }
+  const summary = parseStatusPorcelainV2(status.stdout);
+  return {
+    staged: false,
+    result: {
+      success: false,
+      message: `Nothing is staged (${summary.unstaged.length} unstaged, ${summary.untracked.length} untracked). Stage files with \`git add\` or \`/shell git add ...\` and run \`/git commit\` again.`,
+      data: {
+        git: 'commit',
+        committed: false,
+        unstaged: summary.unstaged.length,
+        untracked: summary.untracked.length,
+      },
+    },
+  };
+}
+
+type TSubjectResolution = { subject: string } | { result: ICommandResult };
+
+/** Step 2 — the subject: inline, or asked for as free text; then the MUST rules. */
+async function resolveSubject(
+  args: string,
+  ui: IUserInteraction | undefined,
+): Promise<TSubjectResolution> {
+  let subject = normalizeCommitSubject(args);
+  if (subject.length === 0) {
+    if (ui === undefined) {
+      return {
+        result: cancelled(
+          'Commit cancelled: a commit message was needed and none could be asked for (no interactive session). Run `/git commit <subject>`.',
+        ),
+      };
+    }
+    const asked = await askSubject(ui);
+    if (asked === undefined || asked.length === 0)
+      return { result: cancelled('Commit cancelled.') };
+    subject = asked;
+  }
+  return { subject };
+}
+
+/** Step 3 — what is confirmed is what is committed: the listing comes from git, not from a guess. */
+async function confirmCommit(
+  port: IGitProcessPort,
+  cwd: string,
+  subject: string,
+  warnings: readonly string[],
+  ui: IUserInteraction | undefined,
+): Promise<
+  { confirmed: true; files: readonly string[] } | { confirmed: false; result: ICommandResult }
+> {
+  if (ui === undefined) {
+    return {
+      confirmed: false,
+      result: cancelled(
+        'Commit cancelled: a confirmation was needed and none could be asked for (no interactive session).',
+      ),
+    };
+  }
+  const listing = await port.run(['diff', '--cached', '--name-status'], { cwd });
+  const listingFailure = gitFailureMessage('diff --cached --name-status', listing);
+  if (listingFailure !== undefined || listing.kind !== 'exited') {
+    return {
+      confirmed: false,
+      result: { success: false, message: listingFailure ?? 'git failed' },
+    };
+  }
+  const files = listing.stdout
+    .split('\n')
+    .filter((line) => line.length > 0)
+    .map((line) => line.replace(/\t/g, ' '));
+  const description = [
+    `Message: ${subject}`,
+    ...warnings.map((warning) => `Warning: ${warning}`),
+    `Staged (${files.length}):`,
+    ...files.map((file) => `  ${file}`),
+  ].join('\n');
+  const response = await ui.ask(
+    confirmAction('git-commit', `Commit ${files.length} staged file(s)?`, {
+      description,
+      defaultYes: false,
+    }),
+  );
+  if (!isConfirmed(response)) return { confirmed: false, result: cancelled('Commit cancelled.') };
+  return { confirmed: true, files };
+}
+
+export async function executeGitCommit(
+  port: IGitProcessPort,
+  cwd: string,
+  args: string,
+  ui: IUserInteraction | undefined,
+): Promise<ICommandResult> {
+  const staged = await checkStaged(port, cwd);
+  if (!staged.staged) return staged.result;
+
+  const resolved = await resolveSubject(args, ui);
+  if (!('subject' in resolved)) return resolved.result;
+  const { subject } = resolved;
+  const check = validateConventionalSubject(subject);
+  if (!check.ok) {
+    return {
+      success: false,
+      message: `Commit refused: ${check.reason}.`,
+      data: { git: 'commit', committed: false, subject },
+    };
+  }
+
+  const confirmation = await confirmCommit(port, cwd, subject, check.warnings, ui);
+  if (!confirmation.confirmed) return confirmation.result;
+
+  // Step 4 — exactly `commit -m <subject>`: never `-a`, never `add`.
+  const commit = await port.run(['commit', '-m', subject], { cwd });
+  const failure = gitFailureMessage('commit', commit);
+  if (failure !== undefined || commit.kind !== 'exited') {
+    return { success: false, message: failure ?? 'git commit failed' };
+  }
+  const firstLine = commit.stdout.split('\n').find((line) => line.trim().length > 0) ?? '';
+  return {
+    success: true,
+    message: `Committed: ${firstLine.length > 0 ? firstLine : subject}`,
+    data: { git: 'commit', committed: true, subject, files: confirmation.files },
+  };
+}

package/src/git/git-diff.ts

@@ -0,0 +1,129 @@
+/**
+ * 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

@@ -0,0 +1,169 @@
+/**
+ * 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})`;
+}