@procedures/git 0.0.0-stage → 0.2.0

package/src/procedures/git/branch.ts

@@ -0,0 +1,61 @@
+/**
+ * git.branch procedure
+ *
+ * Branch operations
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import type { GitBranchInput, GitBranchOutput, GitBranchInfo } from "../../types.js";
+
+/**
+ * Branch operations
+ */
+export async function gitBranch(input: GitBranchInput, ctx: GitContext = {}): Promise<GitBranchOutput> {
+  const { name, delete: del, list, remote, cwd } = input;
+  const run = { cwd, signal: ctx.signal };
+
+  // Get current branch
+  const current = (await git(["rev-parse", "--abbrev-ref", "HEAD"], run)).trim();
+
+  // Delete branch
+  if (del && name) {
+    await git(["branch", "-d", gitArg("name", name)], run);
+    return { deleted: name, current };
+  }
+
+  // Create branch
+  if (name && !list) {
+    await git(["branch", gitArg("name", name)], run);
+    return { created: name, current };
+  }
+
+  // List branches
+  const args = ["branch"];
+  if (remote) args.push("-a");
+  // The full ref name tells local from remote branches: a local "feature/x" also contains "/"
+  args.push("--format=%(refname)|%(refname:short)|%(HEAD)|%(upstream:short)");
+
+  const output = await git(args, run);
+  const branches: GitBranchInfo[] = output
+    .split("\n")
+    .filter(Boolean)
+    .map(line => {
+      const parts = line.split("|");
+      const fullName = parts[0] ?? "";
+      const branchName = parts[1] ?? "";
+      const head = parts[2] ?? "";
+      const trackingVal = parts[3];
+      const result: GitBranchInfo = {
+        name: branchName.replace(/^remotes\//, ""),
+        current: head === "*",
+        remote: fullName.startsWith("refs/remotes/"),
+      };
+      if (trackingVal) {
+        result.tracking = trackingVal;
+      }
+      return result;
+    });
+
+  return { branches, current };
+}

package/src/procedures/git/checkout.ts

@@ -0,0 +1,27 @@
+/**
+ * git.checkout procedure
+ *
+ * Checkout branch or files
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import type { GitCheckoutInput, GitCheckoutOutput } from "../../types.js";
+
+/**
+ * Checkout branch or files
+ */
+export async function gitCheckout(input: GitCheckoutInput, ctx: GitContext = {}): Promise<GitCheckoutOutput> {
+  const { ref, create, paths, cwd } = input;
+
+  const args: string[] = ["checkout"];
+  if (create) args.push("-b");
+  args.push(gitArg("ref", ref));
+  if (paths && paths.length > 0) {
+    args.push("--", ...paths);
+  }
+
+  await git(args, { cwd, signal: ctx.signal });
+
+  return { ref, created: create };
+}

package/src/procedures/git/clone.ts

@@ -0,0 +1,33 @@
+/**
+ * git.clone procedure
+ *
+ * Clone repository
+ */
+
+import { join, basename } from "node:path";
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import type { GitCloneInput, GitCloneOutput } from "../../types.js";
+
+/**
+ * Clone repository
+ */
+export async function gitClone(input: GitCloneInput, ctx: GitContext = {}): Promise<GitCloneOutput> {
+  const { url, dest, branch, depth, cwd } = input;
+
+  // Determine destination directory
+  const destDir = dest || basename(url, ".git").replace(/\.git$/, "");
+  const fullPath = cwd ? join(cwd, destDir) : destDir;
+
+  const args: string[] = ["clone"];
+  if (branch) args.push("-b", branch);
+  if (depth) args.push("--depth", String(depth));
+  args.push("--", gitArg("url", url), gitArg("dest", destDir));
+
+  await git(args, { cwd, signal: ctx.signal });
+
+  // Get the branch that was checked out
+  const clonedBranch = (await git(["rev-parse", "--abbrev-ref", "HEAD"], { cwd: fullPath, signal: ctx.signal })).trim();
+
+  return { path: fullPath, branch: clonedBranch };
+}

package/src/procedures/git/commit.ts

@@ -0,0 +1,46 @@
+/**
+ * git.commit procedure
+ *
+ * Create commit
+ */
+
+import { git, type GitContext } from "./run.js";
+import type { GitCommitInput, GitCommitOutput } from "../../types.js";
+
+/**
+ * Create commit
+ */
+export async function gitCommit(input: GitCommitInput, ctx: GitContext = {}): Promise<GitCommitOutput> {
+  const { message, all, amend, cwd } = input;
+  const run = { cwd, signal: ctx.signal };
+
+  // Check if there's anything to commit (unless amending)
+  if (!amend) {
+    const status = (await git(["status", "--porcelain"], run)).trim();
+    if (!status && !all) {
+      // Nothing staged and not using -a, skip commit
+      return { hash: "", message: "", author: "", date: "", skipped: true };
+    }
+    // If using -a, check if there are any modified files
+    if (all) {
+      const hasChanges = status.length > 0;
+      if (!hasChanges) {
+        return { hash: "", message: "", author: "", date: "", skipped: true };
+      }
+    }
+  }
+
+  const args: string[] = ["commit"];
+  if (all) args.push("-a");
+  if (amend) args.push("--amend");
+  args.push("-m", message);
+
+  await git(args, run);
+
+  // Get commit info
+  const format = "--format=%H%n%s%n%an%n%ci";
+  const info = (await git(["log", "-1", format], run)).trim();
+  const [hash = "", msg = "", author = "", date = ""] = info.split("\n");
+
+  return { hash, message: msg, author, date };
+}

package/src/procedures/git/diff.ts

@@ -0,0 +1,62 @@
+/**
+ * git.diff procedure
+ *
+ * Show changes
+ *
+ * The counts come from `git diff --numstat -z`. With `-z`, each path is exact, and a rename gives
+ * the old and the new path in separate fields (deep dive WRP-7). Before, the procedure split each
+ * line at whitespace: a path with a space lost its end, and a rename gave its old path only.
+ */
+
+import { gitArg } from "./args.js";
+import { git, zFields, type GitContext } from "./run.js";
+import type { GitDiffInput, GitDiffOutput, GitDiffFile } from "../../types.js";
+
+/** This function reads the output of `git diff --numstat -z`. */
+export function parseNumstat(output: string): GitDiffFile[] {
+  const files: GitDiffFile[] = [];
+  const fields = zFields(output);
+  for (let i = 0; i < fields.length; i++) {
+    const [add = "0", del = "0", ...rest] = fields[i]!.split("\t");
+    // A binary file has "-" for both counts
+    const additions = add === "-" ? 0 : parseInt(add, 10);
+    const deletions = del === "-" ? 0 : parseInt(del, 10);
+    const path = rest.join("\t");
+    if (path === "") {
+      // A rename or a copy: the old path, then the new path, in the next two fields
+      const from = fields[++i] ?? "";
+      const to = fields[++i] ?? "";
+      files.push({ path: to, from, additions, deletions });
+    } else {
+      files.push({ path, additions, deletions });
+    }
+  }
+  return files;
+}
+
+/**
+ * Show changes
+ */
+export async function gitDiff(input: GitDiffInput, ctx: GitContext = {}): Promise<GitDiffOutput> {
+  const { staged, ref, paths, stat, cwd } = input;
+  const run = { cwd, signal: ctx.signal };
+
+  const selection: string[] = [];
+  if (staged) selection.push("--cached");
+  if (ref) selection.push(gitArg("ref", ref));
+  const pathspec = paths && paths.length > 0 ? ["--", ...paths] : [];
+
+  const files = parseNumstat(await git(["diff", ...selection, "--numstat", "-z", ...pathspec], run));
+  const result: GitDiffOutput = {
+    files,
+    additions: files.reduce((sum, file) => sum + file.additions, 0),
+    deletions: files.reduce((sum, file) => sum + file.deletions, 0),
+  };
+
+  // Include full diff if not stat-only
+  if (!stat) {
+    result.diff = await git(["diff", ...selection, ...pathspec], run);
+  }
+
+  return result;
+}

package/src/procedures/git/fetch.ts

@@ -0,0 +1,32 @@
+/**
+ * git.fetch procedure
+ *
+ * Fetch from remote without merging
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import type { GitFetchInput, GitFetchOutput } from "../../types.js";
+
+/**
+ * Fetch from remote
+ */
+export async function gitFetch(input: GitFetchInput, ctx: GitContext = {}): Promise<GitFetchOutput> {
+  const { branch, all, prune, cwd } = input;
+  const remoteName = input.remote ?? "origin";
+
+  const args: string[] = ["fetch"];
+  if (all) {
+    args.push("--all");
+  } else {
+    args.push(gitArg("remote", remoteName));
+    if (branch) {
+      args.push(gitArg("branch", branch));
+    }
+  }
+  if (prune) args.push("--prune");
+
+  await git(args, { cwd, signal: ctx.signal });
+
+  return { remote: remoteName, fetched: true };
+}

package/src/procedures/git/index.ts

@@ -0,0 +1,22 @@
+export { gitStatus } from "./status.js";
+export { gitAdd } from "./add.js";
+export { gitCommit } from "./commit.js";
+export { gitPush } from "./push.js";
+export { gitPull } from "./pull.js";
+export { gitClone } from "./clone.js";
+export { gitCheckout } from "./checkout.js";
+export { gitBranch } from "./branch.js";
+export { gitLog } from "./log.js";
+export { gitDiff } from "./diff.js";
+export { gitInit } from "./init.js";
+export { gitRemote, gitRemoteSet } from "./remote.js";
+export { gitFetch } from "./fetch.js";
+export {
+  gitStashList,
+  gitStashPush,
+  gitStashPop,
+  gitStashApply,
+  gitStashDrop,
+  gitStashExport,
+  gitStashImport,
+} from "./stash.js";

package/src/procedures/git/init.ts

@@ -0,0 +1,43 @@
+/**
+ * git.init procedure
+ *
+ * Initialize a git repository
+ */
+
+import { join, resolve } from "node:path";
+import type { ProcedureContext } from "@procedures/client";
+import { git } from "./run.js";
+import type { GitInitInput, GitInitOutput } from "../../types.js";
+
+interface FsExistsOutput { exists: boolean; path: string; }
+
+/**
+ * Initialize a git repository
+ */
+export async function gitInit(input: GitInitInput, ctx: ProcedureContext): Promise<GitInitOutput> {
+  const cwd = input.cwd ? resolve(input.cwd) : process.cwd();
+
+  // Check if already a git repo
+  const gitDir = join(cwd, ".git");
+  const existsResult = await ctx.client.call<{ path: string }, FsExistsOutput>(
+    ["fs", "exists"],
+    { path: gitDir }
+  );
+  const alreadyExists = existsResult.exists;
+
+  if (!alreadyExists) {
+    const args: string[] = ["init"];
+    if (input.bare) {
+      args.push("--bare");
+    }
+    if (input.initialBranch) {
+      args.push(`--initial-branch=${input.initialBranch}`);
+    }
+    await git(args, { cwd, signal: ctx.signal });
+  }
+
+  return {
+    path: cwd,
+    created: !alreadyExists,
+  };
+}

package/src/procedures/git/log.ts

@@ -0,0 +1,40 @@
+/**
+ * git.log procedure
+ *
+ * Show commit log
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import type { GitLogInput, GitLogOutput, GitLogCommit } from "../../types.js";
+
+// Control characters that do not occur in a name, an email, a date or a subject
+const FIELD = "\x1f";
+const RECORD = "\x1e";
+
+/**
+ * Show commit log
+ */
+export async function gitLog(input: GitLogInput, ctx: GitContext = {}): Promise<GitLogOutput> {
+  const { count, ref, cwd } = input;
+
+  const format = `--format=${["%H", "%h", "%an", "%ae", "%ci", "%s"].join("%x1f")}%x1e`;
+  const args = ["log", `-n${count}`, format];
+  if (ref) args.push(gitArg("ref", ref));
+
+  const output = await git(args, { cwd, signal: ctx.signal });
+  const commits: GitLogCommit[] = output
+    .split(RECORD)
+    .map((record) => record.replace(/^\n/, ""))
+    .filter((record) => record.length > 0)
+    .map((record) => {
+      const [hash = "", shortHash = "", author = "", email = "", date = "", message = ""] = record.split(FIELD);
+      return { hash, shortHash, author, email, date, message };
+    });
+
+  const result: GitLogOutput = { commits };
+  if (input.oneline) {
+    result.lines = commits.map((commit) => `${commit.shortHash} ${commit.message}`);
+  }
+  return result;
+}

package/src/procedures/git/predicates.ts

@@ -0,0 +1,90 @@
+/**
+ * Git predicate procedures
+ *
+ * Simple boolean predicates for conditional execution.
+ * These return true/false based on git repository state.
+ */
+
+import { git, GitError, type GitContext } from "./run.js";
+
+export interface GitPredicateInput {
+  /** Working directory (default: process.cwd()) */
+  cwd?: string | undefined;
+}
+
+export interface GitPredicateOutput {
+  /** The predicate result */
+  value: boolean;
+}
+
+/**
+ * The output of a git command, or null when git fails (for example outside a repository).
+ * An aborted signal still throws.
+ */
+async function gitOrNull(args: string[], cwd: string | undefined, ctx: GitContext): Promise<string | null> {
+  try {
+    return (await git(args, { cwd, signal: ctx.signal })).trim();
+  } catch (error) {
+    if (error instanceof GitError) return null;
+    throw error;
+  }
+}
+
+/**
+ * Check if there are any changes (unstaged, staged, or untracked)
+ */
+export async function gitHasChanges(input: GitPredicateInput, ctx: GitContext = {}): Promise<GitPredicateOutput> {
+  const status = await gitOrNull(["status", "--porcelain"], input.cwd, ctx);
+  return { value: status !== null && status.length > 0 };
+}
+
+/**
+ * Check if there are any staged changes ready to commit
+ */
+export async function gitHasStagedChanges(input: GitPredicateInput, ctx: GitContext = {}): Promise<GitPredicateOutput> {
+  // git diff --cached shows only staged changes
+  const diff = await gitOrNull(["diff", "--cached", "--name-only"], input.cwd, ctx);
+  return { value: diff !== null && diff.length > 0 };
+}
+
+/**
+ * Check if there are any unstaged changes (modified or deleted files)
+ */
+export async function gitHasUnstagedChanges(input: GitPredicateInput, ctx: GitContext = {}): Promise<GitPredicateOutput> {
+  // git diff shows only unstaged changes to tracked files
+  const diff = await gitOrNull(["diff", "--name-only"], input.cwd, ctx);
+  return { value: diff !== null && diff.length > 0 };
+}
+
+/**
+ * Check if there are any untracked files
+ */
+export async function gitHasUntrackedFiles(input: GitPredicateInput, ctx: GitContext = {}): Promise<GitPredicateOutput> {
+  // List untracked files only
+  const untracked = await gitOrNull(["ls-files", "--others", "--exclude-standard"], input.cwd, ctx);
+  return { value: untracked !== null && untracked.length > 0 };
+}
+
+/**
+ * Check if there are local commits that haven't been pushed
+ */
+export async function gitHasLocalCommits(input: GitPredicateInput, ctx: GitContext = {}): Promise<GitPredicateOutput> {
+  // Get the upstream tracking branch
+  const upstream = await gitOrNull(["rev-parse", "--abbrev-ref", "@{upstream}"], input.cwd, ctx);
+  if (upstream !== null) {
+    // Count commits ahead of upstream
+    const count = await gitOrNull(["rev-list", "--count", `${upstream}..HEAD`], input.cwd, ctx);
+    if (count !== null) return { value: parseInt(count, 10) > 0 };
+  }
+  // No upstream or error - HEAD exists but no upstream: treat as having local commits
+  const head = await gitOrNull(["rev-parse", "HEAD"], input.cwd, ctx);
+  return { value: head !== null };
+}
+
+/**
+ * Check if the working directory is clean (no changes at all)
+ */
+export async function gitIsClean(input: GitPredicateInput, ctx: GitContext = {}): Promise<GitPredicateOutput> {
+  const result = await gitHasChanges(input, ctx);
+  return { value: !result.value };
+}

package/src/procedures/git/pull.ts

@@ -0,0 +1,45 @@
+/**
+ * git.pull procedure
+ *
+ * Pull from remote
+ */
+
+import { gitArg } from "./args.js";
+import { git, type GitContext } from "./run.js";
+import type { GitPullInput, GitPullOutput } from "../../types.js";
+
+/**
+ * Pull from remote
+ */
+export async function gitPull(input: GitPullInput, ctx: GitContext = {}): Promise<GitPullOutput> {
+  const { branch, rebase, cwd } = input;
+  const remoteName = input.remote ?? "origin";
+  const run = { cwd, signal: ctx.signal };
+
+  // Get current branch if not specified
+  const branchName = branch || (await git(["rev-parse", "--abbrev-ref", "HEAD"], run)).trim();
+
+  // Get current HEAD before pull
+  const beforeHead = (await git(["rev-parse", "HEAD"], run)).trim();
+
+  const args: string[] = ["pull"];
+  if (rebase) args.push("--rebase");
+  args.push(gitArg("remote", remoteName), gitArg("branch", branchName));
+
+  await git(args, run);
+
+  // Get new HEAD after pull
+  const afterHead = (await git(["rev-parse", "HEAD"], run)).trim();
+
+  // Count new commits
+  let commits = 0;
+  if (beforeHead !== afterHead) {
+    const count = (await git(["rev-list", "--count", `${beforeHead}..${afterHead}`], run)).trim();
+    commits = parseInt(count, 10) || 0;
+  }
+
+  // Check if it was fast-forward
+  const fastForward = !rebase && beforeHead !== afterHead;
+
+  return { remote: remoteName, branch: branchName, commits, fastForward };
+}

package/src/procedures/git/push.ts

@@ -0,0 +1,42 @@
+/**
+ * git.push procedure
+ *
+ * Push to remote
+ */
+
+import { gitArg } from "./args.js";
+import { git, GitError, type GitContext } from "./run.js";
+import type { GitPushInput, GitPushOutput } from "../../types.js";
+
+/**
+ * Push to remote
+ */
+export async function gitPush(input: GitPushInput, ctx: GitContext = {}): Promise<GitPushOutput> {
+  const { branch, force, setUpstream, cwd } = input;
+  const remoteName = input.remote ?? "origin";
+  const run = { cwd, signal: ctx.signal };
+
+  // Get current branch if not specified
+  const branchName = branch || (await git(["rev-parse", "--abbrev-ref", "HEAD"], run)).trim();
+
+  // Count commits to push
+  let commits = 0;
+  try {
+    const count = (await git(["rev-list", "--count", `${remoteName}/${branchName}..HEAD`], run)).trim();
+    commits = parseInt(count, 10) || 0;
+  } catch (error) {
+    // Remote branch may not exist yet
+    if (!(error instanceof GitError)) throw error;
+    const count = (await git(["rev-list", "--count", "HEAD"], run)).trim();
+    commits = parseInt(count, 10) || 0;
+  }
+
+  const args: string[] = ["push"];
+  if (setUpstream) args.push("-u");
+  if (force) args.push("--force");
+  args.push(gitArg("remote", remoteName), gitArg("branch", branchName));
+
+  await git(args, run);
+
+  return { remote: remoteName, branch: branchName, commits };
+}

package/src/procedures/git/remote.ts

@@ -0,0 +1,31 @@
+/**
+ * git.remote and git.remote.set
+ *
+ * git.remote reads the URL of a remote. git.remote.set replaces it, or adds the remote. Two
+ * procedures, so that a reader of the URL declares that it changes nothing (CAPABILITIES-2026-10).
+ */
+
+import { gitArg } from "./args.js";
+import { git, GitError, type GitContext } from "./run.js";
+import type { GitRemoteInput, GitRemoteOutput, GitRemoteSetInput } from "../../types.js";
+
+/** This function gives the URL of a remote. */
+export async function gitRemote(input: GitRemoteInput, ctx: GitContext = {}): Promise<GitRemoteOutput> {
+  const { name, cwd } = input;
+  const url = (await git(["remote", "get-url", gitArg("name", name)], { cwd, signal: ctx.signal })).trim();
+  return { name, url };
+}
+
+/** This function sets the URL of a remote, and adds the remote when it is missing. */
+export async function gitRemoteSet(input: GitRemoteSetInput, ctx: GitContext = {}): Promise<GitRemoteOutput> {
+  const { name, url, cwd } = input;
+  const run = { cwd, signal: ctx.signal };
+  try {
+    await git(["remote", "set-url", gitArg("name", name), gitArg("url", url)], run);
+  } catch (error) {
+    // The remote is missing: add it
+    if (!(error instanceof GitError)) throw error;
+    await git(["remote", "add", gitArg("name", name), gitArg("url", url)], run);
+  }
+  return { name, url };
+}

package/src/procedures/git/run.ts

@@ -0,0 +1,70 @@
+/**
+ * How the git procedures run git: through `runCommand` of client-shell (roadmap 2.2).
+ *
+ * Before, they called `execFileSync`: each git call blocked the event loop of the host (an MCP
+ * server or a warm `mark` server stopped all its other calls), and the signal of the call could
+ * not stop git. Now each call is async, the signal kills git, and the output has a limit.
+ */
+
+import { runCommand } from "@procedures/shell/command";
+import { GIT_MAX_BUFFER } from "./args.js";
+
+/** The part of the procedure context that the git procedures read. */
+export interface GitContext {
+  signal?: AbortSignal | undefined;
+}
+
+export interface GitRunOptions extends GitContext {
+  cwd?: string | undefined;
+  /** Text to write to the stdin of git (for example a patch for `git apply`). */
+  input?: string | undefined;
+}
+
+/** A git command that ended with an exit code other than 0. */
+export class GitError extends Error {
+  constructor(
+    readonly args: readonly string[],
+    readonly exitCode: number,
+    readonly stdout: string,
+    readonly stderr: string,
+  ) {
+    super(`git ${args.join(" ")} failed (exit ${exitCode}): ${(stderr || stdout).trim()}`);
+    this.name = "GitError";
+  }
+}
+
+/**
+ * This function runs `git <args>` and gives its stdout. It throws a `GitError` when git fails,
+ * and an `AbortError` when the signal aborts.
+ */
+export async function git(args: string[], options: GitRunOptions = {}): Promise<string> {
+  const result = await runCommand("git", {
+    args,
+    cwd: options.cwd,
+    signal: options.signal,
+    input: options.input,
+    maxOutputBytes: GIT_MAX_BUFFER,
+  });
+  if (result.aborted) {
+    const error = new Error(`git ${args[0]} was aborted`);
+    error.name = "AbortError";
+    throw error;
+  }
+  if (result.error) {
+    throw new Error(`git did not start: ${result.error}`);
+  }
+  if (result.truncated?.stdout) {
+    throw new Error(`The output of git ${args[0]} is longer than ${GIT_MAX_BUFFER} bytes`);
+  }
+  if (!result.success) {
+    throw new GitError(args, result.exitCode, result.stdout, result.stderr);
+  }
+  return result.stdout;
+}
+
+/** This function splits output that git wrote with `-z` into its fields. */
+export function zFields(output: string): string[] {
+  const fields = output.split("\0");
+  if (fields.at(-1) === "") fields.pop();
+  return fields;
+}