singularity-forge/.plans/issue-524-git2-migration.md

Issue #524: Move Git Operations to Rust via git2 Crate

Current State

• git2 crate (v0.20) already a dependency with vendored libgit2
• 7 read-only functions already native in git.rs + native-git-bridge.ts:
  • git_current_branch, git_main_branch, git_branch_exists
  • git_has_merge_conflicts, git_working_tree_status, git_has_changes
  • git_commit_count_between
• ~73 execSync/execFileSync git calls remain across 14 TypeScript files
• All native functions follow the same pattern: native-first with execSync fallback

Scope

This plan covers Phase 1: migrate all remaining read operations and high-value write operations to native git2. Push operations stay as execSync (credential handling too complex for git2). The "Additional Rust Opportunities" (state derivation, JSONL parser) are out of scope for this PR.

---

Phase 1: New Native Read Functions (git.rs)

1.1 — git_is_repo(path: String) -> bool

Replaces: git rev-parse --git-dir (3 calls in auto.ts, guided-flow.ts, doctor.ts) Implementation: Repository::open(path).is_ok()

1.2 — git_has_staged_changes(repo_path: String) -> bool

Replaces: git diff --cached --stat (2 calls in git-service.ts) Implementation: Diff index vs HEAD tree, check if delta count > 0

1.3 — git_diff_stat(repo_path, from_ref?, to_ref?) -> GitDiffStat

Replaces: git diff --stat HEAD, git diff --stat --cached HEAD (session-forensics.ts) Returns: { files_changed: u32, insertions: u32, deletions: u32, summary: String } Implementation: Diff between two trees/index/workdir, count deltas

1.4 — git_diff_name_status(repo_path, from_ref, to_ref, pathspec?) -> Vec<GitNameStatus>

Replaces: git diff --name-status main...branch -- .gsd/ (worktree-manager.ts, 3 calls) Returns: Vec<{ status: String, path: String }> Implementation: Tree-to-tree diff with pathspec filter

1.5 — git_diff_numstat(repo_path, from_ref, to_ref) -> Vec<GitNumstat>

Replaces: git diff --numstat main branch (worktree-manager.ts, 1 call) Returns: Vec<{ added: u32, removed: u32, path: String }>

1.6 — git_diff_content(repo_path, from_ref, to_ref, pathspec?, exclude?) -> String

Replaces: git diff main...branch -- .gsd/ and -- . :(exclude).gsd/ (worktree-manager.ts, 2 calls) Returns: Unified diff string

1.7 — git_log_oneline(repo_path, from_ref, to_ref) -> Vec<GitLogEntry>

Replaces: git log --oneline main..branch (worktree-manager.ts, 1 call) Returns: Vec<{ sha: String, message: String }>

1.8 — git_worktree_list(repo_path) -> Vec<GitWorktreeEntry>

Replaces: git worktree list --porcelain (worktree-manager.ts, 2 calls) Returns: Vec<{ path: String, branch: String, is_bare: bool }> Implementation: Repository::worktrees() + individual worktree info

1.9 — git_branch_list(repo_path, pattern?) -> Vec<String>

Replaces: git branch --list milestone/*, git branch --list gsd/* (doctor.ts, commands.ts, 3 calls) Returns: Branch names matching pattern

1.10 — git_branch_list_merged(repo_path, target, pattern?) -> Vec<String>

Replaces: git branch --merged main --list gsd/* (commands.ts, 1 call) Returns: Branch names merged into target

1.11 — git_ls_files(repo_path, pathspec) -> Vec<String>

Replaces: git ls-files "<exclusion>" (doctor.ts, 1 call) Implementation: Read index, filter by pathspec

1.12 — git_for_each_ref(repo_path, prefix) -> Vec<String>

Replaces: git for-each-ref refs/gsd/snapshots/ --format=%(refname) (commands.ts, 1 call) Implementation: repo.references_glob(prefix/*)

1.13 — git_conflict_files(repo_path) -> Vec<String>

Replaces: git diff --name-only --diff-filter=U (auto-worktree.ts, 1 call) Implementation: Read index conflicts

1.14 — git_batch_info(repo_path) -> GitBatchInfo

NEW batch function: status + branch + diff summary in ONE call Returns: { branch: String, has_changes: bool, status: String, staged_count: u32, unstaged_count: u32 }

---

Phase 2: New Native Write Functions (git.rs)

2.1 — git_init(path, branch?) -> void

Replaces: git init -b <branch> (auto.ts, guided-flow.ts, 2 calls) Implementation: Repository::init() + set initial branch

2.2 — git_add_all(repo_path) -> void

Replaces: git add -A (auto-worktree.ts, git-service.ts, 4 calls) Implementation: Add all to index via repo.index().add_all()

2.3 — git_add_paths(repo_path, paths: Vec<String>) -> void

Replaces: git add -- <file> (auto-worktree.ts, git-service.ts, 3 calls) Implementation: Add specific paths to index

2.4 — git_reset_paths(repo_path, paths: Vec<String>) -> void

Replaces: git reset HEAD -- <path> (git-service.ts, in loop) Implementation: Reset index entries to HEAD for specific paths

2.5 — git_commit(repo_path, message, options?) -> String

Replaces: git commit -m <msg>, git commit --no-verify -F - (11+ calls across files) Returns: Commit SHA Implementation: Write index as tree → create commit → update HEAD Options: { allow_empty: bool }

2.6 — git_checkout_branch(repo_path, branch) -> void

Replaces: git checkout <branch> (auto-worktree.ts, 1 call) Implementation: Set HEAD + checkout tree

2.7 — git_checkout_theirs(repo_path, paths: Vec<String>) -> void

Replaces: git checkout --theirs -- <file> (auto-worktree.ts, in loop) Implementation: Resolve index conflict with "theirs" strategy

2.8 — git_merge_squash(repo_path, branch) -> GitMergeResult

Replaces: git merge --squash <branch> (auto-worktree.ts, worktree-manager.ts, 3 calls) Returns: { success: bool, conflicts: Vec<String> } Implementation: Find merge base → merge trees → apply to index

2.9 — git_merge_abort(repo_path) -> void

Replaces: git merge --abort (git-self-heal.ts, worktree-command.ts, 2 calls) Implementation: Reset to ORIG_HEAD, clean merge state

2.10 — git_rebase_abort(repo_path) -> void

Replaces: git rebase --abort (git-self-heal.ts, 1 call)

2.11 — git_reset_hard(repo_path) -> void

Replaces: git reset --hard HEAD (git-self-heal.ts, 1 call) Implementation: repo.reset(HEAD, Hard)

2.12 — git_branch_delete(repo_path, branch, force: bool) -> void

Replaces: git branch -D/-d <branch> (5 calls across files) Implementation: repo.find_branch().delete()

2.13 — git_branch_force_reset(repo_path, branch, target) -> void

Replaces: git branch -f <branch> <target> (worktree-manager.ts, 1 call)

2.14 — git_rm_cached(repo_path, paths: Vec<String>, recursive: bool) -> Vec<String>

Replaces: git rm --cached -r --ignore-unmatch (git-service.ts, doctor.ts, gitignore.ts, 6 calls) Returns: List of removed paths

2.15 — git_rm_force(repo_path, paths: Vec<String>) -> void

Replaces: git rm --force -- <file> (auto-worktree.ts, 1 call)

2.16 — git_worktree_add(repo_path, path, branch, create_from?) -> void

Replaces: git worktree add commands (worktree-manager.ts, 2 calls) Implementation: repo.worktree() API

2.17 — git_worktree_remove(repo_path, path, force: bool) -> void

Replaces: git worktree remove --force (worktree-manager.ts, doctor.ts, 3 calls)

2.18 — git_worktree_prune(repo_path) -> void

Replaces: git worktree prune (worktree-manager.ts, 3 calls)

2.19 — git_revert_commit(repo_path, sha, no_commit: bool) -> void

Replaces: git revert --no-commit <sha> (undo.ts, 1 call)

2.20 — git_revert_abort(repo_path) -> void

Replaces: git revert --abort (undo.ts, 1 call)

2.21 — git_update_ref(repo_path, refname, target?) -> void

Replaces: git update-ref <ref> HEAD and git update-ref -d <ref> (git-service.ts, commands.ts, 2 calls) When target is null/empty, deletes the ref.

---

Phase 3: TypeScript Bridge Updates (native-git-bridge.ts)

Add bridge functions for ALL new native functions, each with:

1. Native-first implementation
2. execSync fallback for when native module unavailable
3. Proper error handling
4. Type definitions

---

Phase 4: Consumer Migration

Update each TypeScript file to use native bridge functions:

4.1 — git-service.ts

• smartStage() → use nativeAddAll() + nativeResetPaths()
• commit() → use nativeCommit()
• autoCommit() → use nativeHasStagedChanges()
• createSnapshot() → use nativeUpdateRef()
• Runtime file cleanup → use nativeRmCached()
• runPreMergeCheck() → use nativeReadFile() or keep fs.readFileSync (not git)

4.2 — worktree-manager.ts

• getMainBranch() → use nativeDetectMainBranch() (already exists!)
• createWorktree() → use nativeWorktreeAdd(), nativeBranchForceReset()
• listWorktrees() → use nativeWorktreeList()
• removeWorktree() → use nativeWorktreeRemove(), nativeWorktreePrune(), nativeBranchDelete()
• diffWorktreeGSD() → use nativeDiffNameStatus()
• diffWorktreeAll() → use nativeDiffNameStatus()
• diffWorktreeNumstat() → use nativeDiffNumstat()
• getWorktreeGSDDiff() → use nativeDiffContent()
• getWorktreeCodeDiff() → use nativeDiffContent()
• getWorktreeLog() → use nativeLogOneline()
• mergeWorktreeToMain() → use nativeMergeSquash() + nativeCommit()

4.3 — auto-worktree.ts

• getCurrentBranch() → use nativeGetCurrentBranch() (already exists!)
• autoCommitDirtyState() → use nativeWorkingTreeStatus() + nativeAddAll() + nativeCommit()
• mergeMilestoneToMain() → use native merge, checkout, commit, branch delete

4.4 — auto.ts

• git rev-parse --git-dir → use nativeIsRepo()
• git init -b → use nativeInit()
• git add -A .gsd .gitignore && git commit → use nativeAddPaths() + nativeCommit()

4.5 — auto-supervisor.ts

• detectWorkingTreeActivity() → use nativeHasChanges() (already exists!)

4.6 — git-self-heal.ts

• abortAndReset() → use nativeMergeAbort() + nativeRebaseAbort() + nativeResetHard()

4.7 — guided-flow.ts

• Same pattern as auto.ts for init + bootstrap

4.8 — doctor.ts

• git rev-parse --git-dir → use nativeIsRepo()
• git worktree remove --force → use nativeWorktreeRemove()
• git branch --list milestone/* → use nativeBranchList()
• git branch -D → use nativeBranchDelete()
• git ls-files → use nativeLsFiles()
• git rm --cached → use nativeRmCached()
• git branch --format... → use nativeBranchList()

4.9 — gitignore.ts

• untrackRuntimeFiles() → use nativeRmCached()

4.10 — commands.ts

• handleCleanupBranches() → use nativeBranchList(), nativeBranchListMerged(), nativeBranchDelete()
• handleCleanupSnapshots() → use nativeForEachRef(), nativeUpdateRef()

4.11 — undo.ts

• git revert --no-commit → use nativeRevertCommit()
• git revert --abort → use nativeRevertAbort()

4.12 — session-forensics.ts

• getGitChanges() → use nativeWorkingTreeStatus() + nativeDiffStat()

4.13 — worktree-command.ts

• git merge --abort → use nativeMergeAbort()

---

Kept as execSync (out of scope)

• git push <remote> <branch> — Credential handling too complex for git2
• cat package.json — Not a git command (already just fs.readFileSync)
• npm test / custom commands — Not git operations

---

Implementation Order

1. Rust functions (git.rs) — all read functions first, then write functions
2. TypeScript bridge (native-git-bridge.ts) — add all new bridge functions
3. Consumer migration — update each .ts file to use bridge functions
4. Remove dead code — delete local runGit() helpers from files that no longer need them
5. Testing — build native module, run CI, verify all operations work

---

Risk Mitigation

• Every native function has an execSync fallback in the bridge
• Write operations are tested by existing integration tests
• git2's vendored libgit2 matches git CLI behavior for standard operations
• The loadNative() pattern means if ANY native function crashes, ALL functions fall back to CLI

Expected Impact

• ~70 execSync calls eliminated when native module is available
• Zero process spawns for git operations in the common path
• Batch operations (git_batch_info) reduce 3-4 calls to 1
• Type-safe errors instead of parsing stderr strings
• Consistent cross-platform behavior via libgit2