magus-cli 7.12.2 → 7.14.0

package/src/services/git-write.ts

@@ -0,0 +1,615 @@
+/**
+ * git-write.ts — the git primitives `magus market` builds on.
+ *
+ * Every call goes through {@link runBounded} with an argv, never a shell, and
+ * with an environment in which git cannot prompt: `GIT_TERMINAL_PROMPT=0` and
+ * `GCM_INTERACTIVE=never`. Under the TUI an invisible credential prompt would
+ * otherwise sit until the deadline and read as a timeout; with prompting off,
+ * a private remote with no credentials fails at once and is classified `auth`.
+ *
+ * Nothing here runs `git status`: on a read path it rewrites the index stat
+ * cache, which turns a read into a write.
+ *
+ * Every function answers a {@link GitResult}. A failure carries a class, so a
+ * caller maps it to its own error code without parsing git's words again.
+ */
+
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { runBounded } from "../utils/spawn-bounded.js";
+
+/** What went wrong, in the terms a caller acts on. */
+export type GitFailure =
+	| "no-network"
+	| "auth"
+	| "denied"
+	| "rejected-non-ff"
+	| "rejected-protected"
+	| "timeout"
+	| "signing-timeout"
+	| "other";
+
+export type GitResult<T> =
+	| { ok: true; value: T }
+	| {
+			ok: false;
+			failure: GitFailure;
+			/** git's own words (stderr, else stdout), trimmed. */
+			message: string;
+			code: number | null;
+	  };
+
+/** Local reads: rev-parse, ls-tree, cat-file, hash-object, check-ignore. */
+const LOCAL_TIMEOUT_MS = 15_000;
+/** Anything that talks to a remote: clone, fetch, ls-remote, push. */
+const NETWORK_TIMEOUT_MS = 120_000;
+/** A commit may wait for a signing agent, which can need a human to approve. */
+const COMMIT_TIMEOUT_MS = 120_000;
+/** How many paths one hash-object or check-ignore call takes. */
+const PATH_BATCH = 200;
+
+/** The environment every git spawn runs with: the caller's, minus any prompt. */
+export function gitEnv(
+	base: NodeJS.ProcessEnv = process.env,
+): NodeJS.ProcessEnv {
+	return { ...base, GIT_TERMINAL_PROMPT: "0", GCM_INTERACTIVE: "never" };
+}
+
+/**
+ * Classify a failed git run. Order matters: an ssh auth failure ends with
+ * "Could not read from remote repository", which alone would read as a network
+ * problem, and a protected-branch refusal also says "declined".
+ */
+export function classifyGitFailure(
+	text: string,
+	opts: { timedOut: boolean; signing?: boolean },
+): GitFailure {
+	if (opts.timedOut) return opts.signing ? "signing-timeout" : "timeout";
+	if (
+		opts.signing &&
+		/failed to fill whole buffer|gpg failed to sign|signing failed|error: (gpg|ssh-keygen)/i.test(
+			text,
+		)
+	) {
+		return "signing-timeout";
+	}
+	if (/protected branch|GH006|GH013|branch is protected/i.test(text)) {
+		return "rejected-protected";
+	}
+	if (
+		/non-fast-forward|\(fetch first\)|Updates were rejected because the (tip|remote)/i.test(
+			text,
+		)
+	) {
+		return "rejected-non-ff";
+	}
+	if (
+		/terminal prompts disabled|could not read (Username|Password)|Authentication failed|Invalid username or password|HTTP Basic: Access denied|Permission denied \(publickey|Host key verification failed/i.test(
+			text,
+		)
+	) {
+		return "auth";
+	}
+	if (
+		/returned error: 403|Permission to \S+ denied|denied to \S+|write access to repository not granted|Repository not found|pre-receive hook declined/i.test(
+			text,
+		)
+	) {
+		return "denied";
+	}
+	if (
+		/Could not resolve host|Failed to connect|Connection (refused|timed out|reset)|Operation timed out|Network is unreachable|Could not read from remote repository|unable to access/i.test(
+			text,
+		)
+	) {
+		return "no-network";
+	}
+	return "other";
+}
+
+interface RunOpts {
+	cwd?: string;
+	timeoutMs?: number;
+	signal?: AbortSignal;
+	/** The command may sign, so a timeout is a signing timeout. */
+	signing?: boolean;
+	/** Extra exit codes that are answers, not failures (check-ignore's 1). */
+	okCodes?: readonly number[];
+}
+
+/** Run `git <args>`; ok on exit 0 (or an `okCodes` code), classified otherwise. */
+async function git(
+	args: string[],
+	opts: RunOpts = {},
+): Promise<GitResult<{ stdout: string; code: number }>> {
+	const r = await runBounded("git", args, {
+		cwd: opts.cwd,
+		env: gitEnv(),
+		timeoutMs: opts.timeoutMs ?? LOCAL_TIMEOUT_MS,
+		signal: opts.signal,
+	});
+	if (r.spawnError) {
+		return {
+			ok: false,
+			failure: "other",
+			message: `git could not be started: ${r.spawnError.message}`,
+			code: null,
+		};
+	}
+	if (r.aborted) {
+		return { ok: false, failure: "other", message: "aborted", code: r.code };
+	}
+	const code = r.code ?? -1;
+	if (!r.timedOut && (code === 0 || opts.okCodes?.includes(code))) {
+		return { ok: true, value: { stdout: r.stdout, code } };
+	}
+	const message =
+		r.stderr.trim() ||
+		r.stdout.trim() ||
+		(r.timedOut
+			? `git ${args[0]} did not finish in time`
+			: `git ${args[0]} failed`);
+	return {
+		ok: false,
+		failure: classifyGitFailure(`${r.stderr}\n${r.stdout}`, {
+			timedOut: r.timedOut,
+			signing: opts.signing,
+		}),
+		message,
+		code: r.code,
+	};
+}
+
+function map<T, U>(r: GitResult<T>, f: (v: T) => U): GitResult<U> {
+	return r.ok ? { ok: true, value: f(r.value) } : r;
+}
+
+function chunks<T>(items: readonly T[], size: number): T[][] {
+	const out: T[][] = [];
+	for (let i = 0; i < items.length; i += size)
+		out.push(items.slice(i, i + size));
+	return out;
+}
+
+// ─── Read-only ──────────────────────────────────────────────────────────────
+
+export interface RemoteHead {
+	/** The default branch, e.g. "main"; null for an empty repository. */
+	branch: string | null;
+	/** The default branch's commit; null for an empty repository. */
+	commit: string | null;
+}
+
+/**
+ * The remote's default branch and its commit, without a clone:
+ * `git ls-remote --symref <url> HEAD`.
+ */
+export async function lsRemoteHead(
+	url: string,
+	signal?: AbortSignal,
+): Promise<GitResult<RemoteHead>> {
+	const r = await git(["ls-remote", "--symref", "--", url, "HEAD"], {
+		timeoutMs: NETWORK_TIMEOUT_MS,
+		signal,
+	});
+	return map(r, ({ stdout }) => parseLsRemoteHead(stdout));
+}
+
+/** Parse `ls-remote --symref <url> HEAD` output. Exported for tests. */
+export function parseLsRemoteHead(stdout: string): RemoteHead {
+	let branch: string | null = null;
+	let commit: string | null = null;
+	for (const line of stdout.split("\n")) {
+		const sym = /^ref:\s+refs\/heads\/(\S+)\s+HEAD$/.exec(line.trim());
+		if (sym) {
+			branch = sym[1] ?? null;
+			continue;
+		}
+		const head = /^([0-9a-f]{40,64})\s+HEAD$/.exec(line.trim());
+		if (head) commit = head[1] ?? null;
+	}
+	return { branch, commit };
+}
+
+/** `git rev-parse --verify <rev>^{commit}` — the commit a revision names. */
+export async function revParse(
+	repo: string,
+	rev: string,
+): Promise<GitResult<string>> {
+	const r = await git(
+		["rev-parse", "--verify", "--end-of-options", `${rev}^{commit}`],
+		{
+			cwd: repo,
+		},
+	);
+	return map(r, ({ stdout }) => stdout.trim());
+}
+
+export interface TreeEntry {
+	/** Octal file mode: 100644, 100755, 120000 (symlink), 160000 (submodule). */
+	mode: string;
+	type: "blob" | "tree" | "commit";
+	oid: string;
+	/** Path from the repository root. */
+	path: string;
+}
+
+/**
+ * Every blob under `dir` (repository-root relative; "" for the whole tree) at
+ * `treeish`: `git ls-tree -r -z --full-tree <treeish> -- <dir>`.
+ */
+export async function lsTree(
+	repo: string,
+	treeish: string,
+	dir = "",
+): Promise<GitResult<TreeEntry[]>> {
+	const args = ["ls-tree", "-r", "-z", "--full-tree", treeish];
+	if (dir) args.push("--", dir);
+	const r = await git(args, { cwd: repo });
+	return map(r, ({ stdout }) => parseLsTree(stdout));
+}
+
+/** Parse `ls-tree -z` output. Exported for tests. */
+export function parseLsTree(stdout: string): TreeEntry[] {
+	const out: TreeEntry[] = [];
+	for (const record of stdout.split("\0")) {
+		if (!record) continue;
+		const tab = record.indexOf("\t");
+		if (tab < 0) continue;
+		const [mode, type, oid] = record.slice(0, tab).split(" ");
+		if (!mode || !type || !oid) continue;
+		out.push({
+			mode,
+			type: type as TreeEntry["type"],
+			oid,
+			path: record.slice(tab + 1),
+		});
+	}
+	return out;
+}
+
+/**
+ * The content of a blob, by object id or `<rev>:<path>`, as text:
+ * `git cat-file blob <object>`. For manifests and other text files.
+ */
+export async function catFile(
+	repo: string,
+	object: string,
+): Promise<GitResult<string>> {
+	const r = await git(["cat-file", "blob", object], { cwd: repo });
+	return map(r, ({ stdout }) => stdout);
+}
+
+/**
+ * The blob id of each file's bytes, without writing it to any object store:
+ * `git hash-object --no-filters -- <files>` (no `-w`). Paths are absolute or
+ * relative to `cwd`; the result is in the same order. No filter or line-ending
+ * rule of the repository at `cwd` applies, so the same bytes hash the same in
+ * a project and in a marketplace clone.
+ */
+export async function hashObject(
+	cwd: string,
+	files: readonly string[],
+): Promise<GitResult<string[]>> {
+	const out: string[] = [];
+	for (const batch of chunks(files, PATH_BATCH)) {
+		const r = await git(["hash-object", "--no-filters", "--", ...batch], {
+			cwd,
+		});
+		if (!r.ok) return r;
+		const ids = r.value.stdout.split("\n").filter(Boolean);
+		if (ids.length !== batch.length) {
+			return {
+				ok: false,
+				failure: "other",
+				message: `git hash-object returned ${ids.length} ids for ${batch.length} files`,
+				code: r.value.code,
+			};
+		}
+		out.push(...ids);
+	}
+	return { ok: true, value: out };
+}
+
+/**
+ * Which of `paths` the repository at `repo` ignores: `git check-ignore`.
+ * Exit 1 means none is ignored, which is an answer, not a failure. Tracked
+ * files are never reported, as git itself does not ignore them.
+ *
+ * Paths go on the argv and come back one per line: `-z` is accepted only with
+ * `--stdin`, which this runner cannot feed. `core.quotePath=false` keeps
+ * non-ASCII names as they are; a name holding a quote, backslash or control
+ * character still comes back C-quoted and is unquoted here.
+ */
+export async function checkIgnore(
+	repo: string,
+	paths: readonly string[],
+): Promise<GitResult<Set<string>>> {
+	const ignored = new Set<string>();
+	for (const batch of chunks(paths, PATH_BATCH)) {
+		const r = await git(
+			["-c", "core.quotePath=false", "check-ignore", "--", ...batch],
+			{ cwd: repo, okCodes: [1] },
+		);
+		if (!r.ok) return r;
+		for (const line of r.value.stdout.split("\n")) {
+			if (line) ignored.add(unquoteCPath(line));
+		}
+	}
+	return { ok: true, value: ignored };
+}
+
+const C_ESCAPES: Record<string, string> = {
+	a: "\x07",
+	b: "\b",
+	f: "\f",
+	n: "\n",
+	r: "\r",
+	t: "\t",
+	v: "\v",
+	'"': '"',
+	"\\": "\\",
+};
+
+/**
+ * Undo git's C-style quoting of a path (`"a\tb"`, `"caf\303\251"`); a path
+ * that is not quoted is returned as it is. Exported for tests.
+ */
+export function unquoteCPath(text: string): string {
+	if (text.length < 2 || !text.startsWith('"') || !text.endsWith('"')) {
+		return text;
+	}
+	const body = text.slice(1, -1);
+	const bytes: number[] = [];
+	const encoder = new TextEncoder();
+	for (let i = 0; i < body.length; i++) {
+		const ch = body[i] as string;
+		if (ch !== "\\") {
+			bytes.push(...encoder.encode(ch));
+			continue;
+		}
+		const next = body[i + 1] ?? "";
+		const octal = /^[0-7]{1,3}/.exec(body.slice(i + 1, i + 4));
+		if (octal) {
+			bytes.push(Number.parseInt(octal[0], 8));
+			i += octal[0].length;
+			continue;
+		}
+		bytes.push(...encoder.encode(C_ESCAPES[next] ?? next));
+		i += 1;
+	}
+	return new TextDecoder().decode(new Uint8Array(bytes));
+}
+
+/**
+ * The remote's URL as configured, before any `url.<base>.insteadOf` rewrite:
+ * `git config --get remote.<name>.url`. Null when the remote is not set.
+ */
+export async function remoteUrl(
+	repo: string,
+	remote = "origin",
+): Promise<GitResult<string | null>> {
+	const r = await git(["config", "--get", `remote.${remote}.url`], {
+		cwd: repo,
+		okCodes: [1],
+	});
+	return map(r, ({ stdout, code }) =>
+		code === 1 ? null : stdout.trim() || null,
+	);
+}
+
+// ─── Writing ────────────────────────────────────────────────────────────────
+
+/** `git clone <url> <dest>` with full history, which a push needs. */
+export async function cloneFull(
+	url: string,
+	dest: string,
+	signal?: AbortSignal,
+): Promise<GitResult<void>> {
+	const r = await git(["clone", "--", url, dest], {
+		timeoutMs: NETWORK_TIMEOUT_MS,
+		signal,
+	});
+	return map(r, () => undefined);
+}
+
+export interface TempClone {
+	dir: string;
+	/** Remove the clone. Safe to call more than once. */
+	dispose(): void;
+}
+
+/**
+ * A shallow clone with no checkout in a new directory under the OS temp dir:
+ * `git clone --depth 1 --no-checkout`. Read it with {@link catFile}
+ * (`HEAD:<path>`), then `dispose()` it in a `finally`. On failure the
+ * directory is already gone.
+ */
+export async function cloneShallowTemp(
+	url: string,
+	signal?: AbortSignal,
+): Promise<GitResult<TempClone>> {
+	const parent = fs.mkdtempSync(path.join(os.tmpdir(), "magus-market-"));
+	const dispose = () => fs.rmSync(parent, { recursive: true, force: true });
+	const dir = path.join(parent, "repo");
+	const r = await git(
+		["clone", "--depth", "1", "--no-checkout", "--", url, dir],
+		{
+			timeoutMs: NETWORK_TIMEOUT_MS,
+			signal,
+		},
+	);
+	if (!r.ok) {
+		dispose();
+		return r;
+	}
+	return { ok: true, value: { dir, dispose } };
+}
+
+/** `git fetch --prune <remote>`. */
+export async function fetch(
+	repo: string,
+	remote = "origin",
+	signal?: AbortSignal,
+): Promise<GitResult<void>> {
+	const r = await git(["fetch", "--prune", remote], {
+		cwd: repo,
+		timeoutMs: NETWORK_TIMEOUT_MS,
+		signal,
+	});
+	return map(r, () => undefined);
+}
+
+/** `git reset --hard <remote>/<branch>`. */
+export async function resetToRemote(
+	repo: string,
+	branch: string,
+	remote = "origin",
+): Promise<GitResult<void>> {
+	const r = await git(["reset", "--hard", `${remote}/${branch}`], {
+		cwd: repo,
+	});
+	return map(r, () => undefined);
+}
+
+/** `git clean -ffdx`: every untracked and ignored file, nested repos included. */
+export async function cleanAll(repo: string): Promise<GitResult<void>> {
+	const r = await git(["clean", "-ffdx"], { cwd: repo });
+	return map(r, () => undefined);
+}
+
+/**
+ * Stage exactly the given paths (additions, changes and deletions under them):
+ * `git add -A -- <paths>`. There is deliberately no "add everything".
+ */
+export async function addPaths(
+	repo: string,
+	paths: readonly string[],
+): Promise<GitResult<void>> {
+	if (paths.length === 0) {
+		return {
+			ok: false,
+			failure: "other",
+			message: "no paths to stage",
+			code: null,
+		};
+	}
+	for (const batch of chunks(paths, PATH_BATCH)) {
+		const r = await git(["add", "-A", "--", ...batch], { cwd: repo });
+		if (!r.ok) return r;
+	}
+	return { ok: true, value: undefined };
+}
+
+export interface StagedChange {
+	/** git's status letter: A, M, D, T, … */
+	status: string;
+	path: string;
+}
+
+/**
+ * What the index holds against HEAD: `git diff --cached --name-status
+ * --no-renames -z`. Renames are reported as a delete plus an add, so every
+ * path appears exactly once.
+ */
+export async function stagedChanges(
+	repo: string,
+): Promise<GitResult<StagedChange[]>> {
+	const r = await git(
+		["diff", "--cached", "--name-status", "--no-renames", "-z"],
+		{
+			cwd: repo,
+		},
+	);
+	return map(r, ({ stdout }) => parseNameStatus(stdout));
+}
+
+/** Parse `--name-status -z` output (no renames). Exported for tests. */
+export function parseNameStatus(stdout: string): StagedChange[] {
+	const parts = stdout.split("\0");
+	const out: StagedChange[] = [];
+	for (let i = 0; i + 1 < parts.length; i += 2) {
+		const status = parts[i];
+		const file = parts[i + 1];
+		if (!status || file === undefined || file === "") continue;
+		out.push({ status, path: file });
+	}
+	return out;
+}
+
+/**
+ * `git commit -m <message>`, answering the new commit. Bounded at two minutes
+ * because a signing agent may wait for a human; a timeout there is
+ * `signing-timeout`. Signing is never disabled.
+ */
+export async function commit(
+	repo: string,
+	message: string,
+): Promise<GitResult<string>> {
+	const r = await git(["commit", "--quiet", "-m", message], {
+		cwd: repo,
+		timeoutMs: COMMIT_TIMEOUT_MS,
+		signing: true,
+	});
+	if (!r.ok) return r;
+	return revParse(repo, "HEAD");
+}
+
+/** `git push [-u] <remote> <branch>`. */
+export async function push(
+	repo: string,
+	branch: string,
+	opts: { remote?: string; setUpstream?: boolean; signal?: AbortSignal } = {},
+): Promise<GitResult<void>> {
+	const args = ["push"];
+	if (opts.setUpstream) args.push("-u");
+	args.push(opts.remote ?? "origin", branch);
+	const r = await git(args, {
+		cwd: repo,
+		timeoutMs: NETWORK_TIMEOUT_MS,
+		signal: opts.signal,
+	});
+	return map(r, () => undefined);
+}
+
+/**
+ * Push a local ref to a named branch of a remote, which may be a URL:
+ * `git push <remote> <localRef>:refs/heads/<branch>`. For a pull-request
+ * branch, on the origin or on a fork.
+ */
+export async function pushRef(
+	repo: string,
+	remote: string,
+	localRef: string,
+	branch: string,
+	signal?: AbortSignal,
+): Promise<GitResult<void>> {
+	const r = await git(
+		["push", "--", remote, `${localRef}:refs/heads/${branch}`],
+		{
+			cwd: repo,
+			timeoutMs: NETWORK_TIMEOUT_MS,
+			signal,
+		},
+	);
+	return map(r, () => undefined);
+}
+
+/**
+ * Make `dir` a new repository on `branch` with `url` as its origin:
+ * `git init -b <branch>`, then `git remote add origin <url>`.
+ */
+export async function initWithRemote(
+	dir: string,
+	url: string,
+	branch = "main",
+): Promise<GitResult<void>> {
+	fs.mkdirSync(dir, { recursive: true });
+	const init = await git(["init", "--quiet", "-b", branch], { cwd: dir });
+	if (!init.ok) return init;
+	const remote = await git(["remote", "add", "--", "origin", url], {
+		cwd: dir,
+	});
+	return map(remote, () => undefined);
+}