@procedures/git 0.0.0-stage → 0.2.0

package/src/procedures/git/stash.ts

@@ -0,0 +1,255 @@
+/**
+ * git.stash.* procedures
+ *
+ * Stash operations for saving and restoring work in progress.
+ * Includes export/import for snapshot storage.
+ */
+
+import { gitArg } from "./args.js";
+import { git, GitError, type GitContext } from "./run.js";
+import type {
+  GitStashListInput,
+  GitStashListOutput,
+  GitStashPushInput,
+  GitStashPushOutput,
+  GitStashPopInput,
+  GitStashPopOutput,
+  GitStashApplyInput,
+  GitStashApplyOutput,
+  GitStashDropInput,
+  GitStashDropOutput,
+  GitStashExportInput,
+  GitStashExportOutput,
+  GitStashImportInput,
+  GitStashImportOutput,
+  GitStashEntry,
+} from "../../types.js";
+
+/**
+ * True when git stopped on a merge conflict. Git writes "CONFLICT (content): ..." to stdout,
+ * so the message alone (which has stderr) does not show it. (Before, the procedures examined
+ * only the message, and never reported a conflict.)
+ */
+function isConflict(error: unknown): boolean {
+  return error instanceof GitError && /conflict/i.test(`${error.stdout}\n${error.stderr}`);
+}
+
+/** The message of a git failure. An abort is not a git failure: it throws again. */
+function failure(error: unknown): string {
+  if (!(error instanceof GitError)) throw error;
+  return error.message;
+}
+
+function stashRef(index: number | undefined): string {
+  return index !== undefined ? `stash@{${index}}` : "stash@{0}";
+}
+
+/**
+ * List all stashes
+ */
+export async function gitStashList(input: GitStashListInput, ctx: GitContext = {}): Promise<GitStashListOutput> {
+  const cwd = input.cwd || process.cwd();
+
+  let output: string;
+  try {
+    // Get stash list with format: stash@{n}: WIP on branch: message
+    output = await git(["stash", "list", "--format=%H%x00%gd%x00%gs"], { cwd, signal: ctx.signal });
+  } catch (error) {
+    // No stashes or not a git repo
+    failure(error);
+    return { stashes: [], count: 0 };
+  }
+
+  const stashes: GitStashEntry[] = [];
+  for (const line of output.split("\n").filter(Boolean)) {
+    const parts = line.split("\0");
+    const hash = parts[0] || "";
+    const ref = parts[1] || "";
+    const message = parts[2] || "";
+    // Extract index from stash@{n}
+    const indexMatch = ref.match(/stash@\{(\d+)\}/);
+    const index = indexMatch && indexMatch[1] ? parseInt(indexMatch[1], 10) : 0;
+
+    stashes.push({
+      index,
+      ref,
+      hash,
+      message,
+    });
+  }
+
+  return { stashes, count: stashes.length };
+}
+
+/**
+ * Push changes to stash
+ */
+export async function gitStashPush(input: GitStashPushInput, ctx: GitContext = {}): Promise<GitStashPushOutput> {
+  const cwd = input.cwd || process.cwd();
+  const run = { cwd, signal: ctx.signal };
+
+  const args: string[] = ["stash", "push"];
+
+  if (input.message) {
+    args.push("-m", input.message);
+  }
+
+  if (input.includeUntracked) {
+    args.push("--include-untracked");
+  }
+
+  if (input.keepIndex) {
+    args.push("--keep-index");
+  }
+
+  if (input.paths && input.paths.length > 0) {
+    args.push("--");
+    args.push(...input.paths);
+  }
+
+  try {
+    const output = await git(args, run);
+
+    // Check if anything was stashed
+    if (output.includes("No local changes to save")) {
+      return { stashed: false, message: "No local changes to save" };
+    }
+
+    // Get the ref of the new stash
+    const refOutput = (await git(["stash", "list", "-1", "--format=%gd"], run)).trim();
+
+    return {
+      stashed: true,
+      ref: refOutput || "stash@{0}",
+      message: input.message || "WIP",
+    };
+  } catch (error) {
+    return { stashed: false, message: failure(error) || "Failed to stash" };
+  }
+}
+
+/**
+ * Pop stash (apply and remove)
+ */
+export async function gitStashPop(input: GitStashPopInput, ctx: GitContext = {}): Promise<GitStashPopOutput> {
+  const cwd = input.cwd || process.cwd();
+  const ref = stashRef(input.index);
+
+  try {
+    await git(["stash", "pop", gitArg("ref", ref)], { cwd, signal: ctx.signal });
+    return { applied: true, ref, dropped: true };
+  } catch (error) {
+    // Check if it's a conflict
+    if (isConflict(error)) {
+      return { applied: false, ref, dropped: false, conflict: true };
+    }
+    failure(error);
+    return { applied: false, ref, dropped: false };
+  }
+}
+
+/**
+ * Apply stash without removing
+ */
+export async function gitStashApply(input: GitStashApplyInput, ctx: GitContext = {}): Promise<GitStashApplyOutput> {
+  const cwd = input.cwd || process.cwd();
+  const ref = stashRef(input.index);
+
+  try {
+    await git(["stash", "apply", gitArg("ref", ref)], { cwd, signal: ctx.signal });
+    return { applied: true, ref };
+  } catch (error) {
+    if (isConflict(error)) {
+      return { applied: false, ref, conflict: true };
+    }
+    failure(error);
+    return { applied: false, ref };
+  }
+}
+
+/**
+ * Drop a stash
+ */
+export async function gitStashDrop(input: GitStashDropInput, ctx: GitContext = {}): Promise<GitStashDropOutput> {
+  const cwd = input.cwd || process.cwd();
+  const ref = stashRef(input.index);
+
+  try {
+    await git(["stash", "drop", gitArg("ref", ref)], { cwd, signal: ctx.signal });
+    return { dropped: true, ref };
+  } catch (error) {
+    failure(error);
+    return { dropped: false, ref };
+  }
+}
+
+/**
+ * Export a stash as a patch (for snapshot storage)
+ */
+export async function gitStashExport(input: GitStashExportInput, ctx: GitContext = {}): Promise<GitStashExportOutput> {
+  const cwd = input.cwd || process.cwd();
+  const run = { cwd, signal: ctx.signal };
+  const ref = stashRef(input.index);
+
+  try {
+    // Get the stash as a patch
+    const patch = await git(["stash", "show", "-p", gitArg("ref", ref)], run);
+
+    // Get metadata
+    const metadata = (await git(["stash", "list", "-1", "--format=%H%x00%gs", ref], run)).trim();
+    const metaParts = metadata.split("\0");
+    const hash = metaParts[0] || "";
+    const message = metaParts[1] || "";
+
+    // Get untracked files if present (stash^3 contains untracked files if any)
+    let untrackedPatch = "";
+    try {
+      untrackedPatch = await git(["show", `${ref}^3`, "--format=", "--name-only"], run);
+    } catch (error) {
+      // No untracked files in this stash
+      failure(error);
+    }
+
+    return {
+      ref,
+      hash,
+      message,
+      patch,
+      hasUntracked: untrackedPatch.length > 0,
+      untrackedPatch: untrackedPatch || undefined,
+    };
+  } catch (error) {
+    throw new Error(`Failed to export stash ${ref}: ${failure(error)}`);
+  }
+}
+
+/**
+ * Import a stash from a patch (for snapshot restore)
+ * Note: This creates a new stash, it doesn't recreate the exact stash state
+ */
+export async function gitStashImport(input: GitStashImportInput, ctx: GitContext = {}): Promise<GitStashImportOutput> {
+  const cwd = input.cwd || process.cwd();
+  const run = { cwd, signal: ctx.signal };
+
+  try {
+    // Apply the patch to working directory
+    await git(["apply", "--3way"], { ...run, input: input.patch });
+
+    // Stash the changes with the original message
+    const message = input.message || "Imported stash";
+    const args = ["stash", "push", "-m", message];
+
+    if (input.includeUntracked) {
+      args.push("--include-untracked");
+    }
+
+    await git(args, run);
+
+    // Get the new stash ref
+    const ref = (await git(["stash", "list", "-1", "--format=%gd"], run)).trim();
+
+    return { imported: true, ref: ref || "stash@{0}" };
+  } catch (error) {
+    return { imported: false, error: failure(error) || "Failed to import stash" };
+  }
+}

package/src/procedures/git/status.ts

@@ -0,0 +1,98 @@
+/**
+ * git.status procedure
+ *
+ * Get git status
+ *
+ * One call of `git status --porcelain=v2 --branch -z` gives the branch, the ahead and behind
+ * counts and the files. With `-z`, git writes each path as it is: no quotes, and a rename gives
+ * its old path in a separate field (deep dive WRP-7). Before, the procedure read the quoted form,
+ * so a path with a space kept its quotes, and a rename gave the text "old -> new" as the path.
+ */
+
+import { git, zFields, type GitContext } from "./run.js";
+import type { GitStatusInput, GitStatusOutput, GitStatusFile } from "../../types.js";
+
+/** The status of one entry, from its two status letters (index, then work tree). */
+function classify(xy: string): Pick<GitStatusFile, "status" | "staged"> {
+  const index = xy[0];
+  const worktree = xy[1];
+  if (index === "A") return { status: "added", staged: true };
+  if (index === "D") return { status: "deleted", staged: true };
+  if (index === "R") return { status: "renamed", staged: true };
+  if (index === "C") return { status: "copied", staged: true };
+  if (index === "M" || index === "T") return { status: "modified", staged: true };
+  if (worktree === "D") return { status: "deleted", staged: false };
+  if (worktree === "A") return { status: "added", staged: false };
+  if (worktree === "R") return { status: "renamed", staged: false };
+  return { status: "modified", staged: false };
+}
+
+/** The text after the first `count` space-separated fields of a line. */
+function afterFields(line: string, count: number): string {
+  let at = 0;
+  for (let i = 0; i < count; i++) at = line.indexOf(" ", at) + 1;
+  return line.slice(at);
+}
+
+/**
+ * Get git status
+ */
+export async function gitStatus(input: GitStatusInput, ctx: GitContext = {}): Promise<GitStatusOutput> {
+  const output = await git(["status", "--porcelain=v2", "--branch", "-z"], { cwd: input.cwd, signal: ctx.signal });
+
+  let branch = "HEAD";
+  let ahead = 0;
+  let behind = 0;
+  const files: GitStatusFile[] = [];
+  const lines: string[] = [];
+
+  const fields = zFields(output);
+  for (let i = 0; i < fields.length; i++) {
+    const field = fields[i]!;
+    if (field.startsWith("# branch.head ")) {
+      const head = field.slice("# branch.head ".length);
+      branch = head === "(detached)" ? "HEAD" : head;
+    } else if (field.startsWith("# branch.ab ")) {
+      const match = /\+(\d+) -(\d+)/.exec(field);
+      ahead = Number(match?.[1] ?? 0);
+      behind = Number(match?.[2] ?? 0);
+    } else if (field.startsWith("1 ")) {
+      // 1 XY sub mH mI mW hH hI path
+      const xy = field.slice(2, 4);
+      const path = afterFields(field, 8);
+      files.push({ path, ...classify(xy) });
+      lines.push(`${xy.replace(/\./g, " ")} ${path}`);
+    } else if (field.startsWith("2 ")) {
+      // 2 XY sub mH mI mW hH hI Xscore path, then the old path in the next field
+      const xy = field.slice(2, 4);
+      const path = afterFields(field, 9);
+      const from = fields[++i] ?? "";
+      files.push({ path, from, ...classify(xy) });
+      lines.push(`${xy.replace(/\./g, " ")} ${from} -> ${path}`);
+    } else if (field.startsWith("u ")) {
+      // An unmerged path: u XY sub m1 m2 m3 mW h1 h2 h3 path
+      const xy = field.slice(2, 4);
+      const path = afterFields(field, 10);
+      files.push({ path, status: "modified", staged: false });
+      lines.push(`${xy} ${path}`);
+    } else if (field.startsWith("? ")) {
+      const path = field.slice(2);
+      files.push({ path, status: "untracked", staged: false });
+      lines.push(`?? ${path}`);
+    } else if (field.startsWith("! ")) {
+      const path = field.slice(2);
+      files.push({ path, status: "ignored", staged: false });
+      lines.push(`!! ${path}`);
+    }
+  }
+
+  const result: GitStatusOutput = {
+    branch,
+    ahead,
+    behind,
+    files,
+    clean: files.length === 0,
+  };
+  if (input.short) result.lines = lines;
+  return result;
+}

package/src/procedures/git.ts

@@ -0,0 +1,5 @@
+/**
+ * Git procedures barrel export
+ */
+
+export * from "./git/index.js";

package/src/register.ts

@@ -0,0 +1,11 @@
+/**
+ * Importing this file registers the procedures of @procedures/git, and of the modules that it
+ * requires, in the global registry: `import "@procedures/git/register"`. The package root and the
+ * `./module` entry register nothing (ARCHITECTURE-PROPOSALS-2026-10, P9).
+ */
+
+import { registerGitProcedures } from "./module.js";
+
+export * from "./module.js";
+
+registerGitProcedures();