// Low-level git primitives shared by the workspace probe/merge/cleanup helpers.
// Extracted from workspace-probe.ts so that giant keeps shrinking (epic #291) and the
// `git -C` invocation lives in one place.

import { execProcess } from "./process";
import type { ExecResult } from "./process";

type GitResult = Pick<ExecResult, "ok" | "stdout" | "stderr" | "exitCode" | "timedOut">;

interface GitOptions {
  timeoutMs?: number;
  timeoutLabel?: string;
  signal?: AbortSignal;
  /** Override the child's environment (default: inherit `process.env`, the existing behavior for
   * every caller that omits this). #1145 round-6 — the ONLY current use is the hermetic
   * gitignore-guard materialization (integrated-land-gates.ts), which must run with every
   * ambient git config source (global/system/command-scope) scrubbed; every other caller is
   * unaffected by this option existing. */
  env?: Record<string, string | undefined>;
}

/** Run `git -C cwd <args>` and capture trimmed stdout/stderr; never throws. */
export async function git(args: string[], cwd: string, options: GitOptions = {}): Promise<GitResult> {
  return await execProcess(["git", "-C", cwd, ...args], options);
}

/** Run `git -C cwd <args>` and preserve stdout exactly for path-safe parsers. */
export async function gitRaw(args: string[], cwd: string, options: GitOptions = {}): Promise<GitResult> {
  return await execProcess(["git", "-C", cwd, ...args], { ...options, trimStdout: false });
}

/** Like {@link git} but throws on a non-zero exit, returning stdout on success. */
export async function requireGit(args: string[], cwd: string): Promise<string> {
  const result = await git(args, cwd);
  if (!result.ok) throw new Error(result.stderr || `git ${args.join(" ")} failed`);
  return result.stdout;
}