@codragraph/cli 1.6.4 → 2.1.0

package/skills/codragraph-git-history-rewrite.md

@@ -0,0 +1,174 @@
+---
+name: codragraph-git-history-rewrite
+description: "Use when rewriting commit history — squashing WIP commits, splitting a fat commit, removing a leaked secret, changing author info, or running git filter-repo / BFG. Covers interactive rebase, fixup/autosquash, splitting commits, and the safety rules for rewriting public history. Examples: \"squash my commits\", \"clean up history\", \"remove a leaked secret from history\", \"split this commit\", \"git filter-repo\""
+---
+
+# History Rewriting — Safely
+
+## When to Use
+
+- "Squash my last 5 WIP commits before opening a PR."
+- "Split this giant commit into 3 logical ones."
+- "Remove a leaked secret from history."
+- "Change the author of past commits."
+- "Drop a commit from the middle of the branch."
+
+## The cardinal rule
+
+**Never rewrite history that's been pushed to a shared branch.** Rewriting
+public history breaks every clone that pulled it. For shared branches:
+make a new commit that fixes/reverts the offending one. For your own
+branch (or any branch you alone work on), rewrite freely with
+`--force-with-lease`.
+
+## Interactive rebase
+
+```bash
+git rebase -i origin/main           # rebase your branch onto main, interactively
+# OR rebase the last N commits without changing the base:
+git rebase -i HEAD~N
+```
+
+You get an editor with one line per commit:
+
+```
+pick   abc1234 wip: hack on auth
+pick   def5678 wip: more auth
+pick   fed9876 fix typo
+pick   012abcd add real auth flow
+```
+
+Change `pick` to one of:
+
+| Command | Effect |
+|---|---|
+| `pick` | keep the commit as-is |
+| `reword` | keep the changes, edit the message |
+| `edit` | pause after applying so you can `git commit --amend` or split |
+| `squash` | merge into previous commit, edit combined message |
+| `fixup` | merge into previous commit, drop this commit's message |
+| `drop` | remove the commit entirely (its changes are gone) |
+| `exec <cmd>` | run a shell command after this commit (CI-style validation per commit) |
+
+Reorder lines to reorder commits. Save and exit; rebase replays them.
+
+## Fixup + autosquash workflow (the cleanest pattern)
+
+```bash
+# While developing, instead of "wip" commits, mark fixups against a target:
+git commit --fixup=<sha-of-target-commit>
+
+# At the end, squash all fixups in one go:
+git rebase -i --autosquash origin/main
+# → all `fixup!` commits are auto-placed and pre-marked. Just save.
+```
+
+This produces a clean, atomic-commit branch ready to PR — no manual
+reordering needed.
+
+## Splitting a fat commit
+
+```bash
+git rebase -i <commit>^             # interactive rebase starting AT the fat commit
+# Mark it `edit` and save.
+
+# Now you're paused at the fat commit. Reset to its parent, keep the changes:
+git reset HEAD^
+
+# Stage and commit each logical chunk separately:
+git add <files-for-part-1>
+git commit -m "first logical part"
+git add <files-for-part-2>
+git commit -m "second logical part"
+git add -A
+git commit -m "third logical part"
+
+# Resume the rebase:
+git rebase --continue
+```
+
+## Removing a leaked secret from history
+
+If a secret (API key, password, .env) was committed:
+
+1. **Rotate the secret first.** Once it's on a public remote, treat it as
+   leaked — even after history scrub.
+2. **Then scrub history with `git filter-repo`** (the modern replacement
+   for `filter-branch`):
+
+```bash
+# Install: pip install git-filter-repo (or pipx)
+
+# Remove a specific file from all history:
+git filter-repo --invert-paths --path path/to/leaked.env
+
+# Or remove a string/secret from blob contents:
+echo 'sk_live_abc***123==>REDACTED' > /tmp/replacements.txt
+git filter-repo --replace-text /tmp/replacements.txt
+
+# After filter-repo, the remote is forcibly out of sync. Coordinate with the
+# team and force-push:
+git push --force-with-lease origin --all
+git push --force-with-lease origin --tags
+```
+
+Alternative: BFG (`https://rtyley.github.io/bfg-repo-cleaner/`) is
+faster for large repos but more limited.
+
+> **Important:** GitHub caches blobs even after force-push. The blob is
+> still accessible by SHA URL for ~30 days unless you contact GitHub
+> Support to purge. Treat the secret as compromised.
+
+## Changing author info on past commits
+
+```bash
+# Most recent commit only:
+git commit --amend --author="New Name <new@email>"
+
+# Multiple commits with filter-repo:
+git filter-repo --commit-callback '
+  if commit.author_email == b"old@email":
+    commit.author_email = b"new@email"
+    commit.author_name = b"New Name"
+'
+```
+
+## Why CodraGraph helps here
+
+After any history rewrite, the structural diff against the pre-rewrite
+state proves you didn't accidentally drop or alter functional code:
+
+```bash
+# Before rewrite: snapshot the structural state
+codragraph commit -m "pre-rewrite snapshot"
+git rebase -i origin/main             # do the rewrite
+codragraph analyze                    # re-index after
+
+# Confirm structural equivalence (or see exactly what differs):
+codragraph diff <pre-snapshot-id> HEAD --semantic
+# → Should be empty if you only rewrote messages / order.
+# → If addedAPIs / removedAPIs appear, the rewrite changed semantics.
+```
+
+## Pitfalls
+
+| Pitfall | What goes wrong | Avoidance |
+|---|---|---|
+| Rewriting shared branch | Collaborators' clones diverge | Only rewrite local-or-personal branches |
+| `drop` instead of `fixup` | Lost changes silently | Verify with `codragraph diff` after the rebase |
+| Editing during rebase, forgetting `--continue` | Stuck in detached state | `git rebase --continue` after each manual step |
+| `git rebase --abort` after edits | Loses your edits | Stash before rebase if you have uncommitted work |
+| `filter-branch` (legacy) | Slow, error-prone, deprecated | Use `git filter-repo` |
+| Force-pushing after secret scrub without rotation | Secret still compromised | Rotate FIRST, scrub SECOND |
+
+## Checklist before any history rewrite
+
+```
+- [ ] Branch is NOT shared (or you have explicit team coordination)
+- [ ] Snapshot pre-state with `codragraph commit -m "pre-rewrite"`
+- [ ] Decide: interactive rebase (small) vs filter-repo (large/secrets)
+- [ ] Run the rewrite
+- [ ] Re-analyze + `codragraph diff` to verify no semantic surprises
+- [ ] Push with --force-with-lease
+- [ ] If secrets were involved: rotate FIRST, then scrub, then push
+```

package/skills/codragraph-git-rebase-vs-merge.md

@@ -0,0 +1,138 @@
+---
+name: codragraph-git-rebase-vs-merge
+description: "Use when deciding between rebase, merge, squash-merge, or rebase-and-merge for integrating a branch — both for local catch-up (pulling main into a feature branch) and for landing a PR. Examples: \"should I rebase or merge\", \"how do I integrate main into my branch\", \"squash vs rebase merge\", \"clean up my branch history before PR\""
+---
+
+# Rebase vs Merge — A Decision Guide
+
+## When to Use
+
+- "How do I bring main into my feature branch?"
+- "Should I squash this PR or merge it?"
+- "Should I rebase before pushing?"
+- "Which merge strategy do I pick on the GitHub PR button?"
+- Any time you have a branch and need to combine it with another.
+
+## The decision rule (read this first)
+
+| Situation | Use | Why |
+|---|---|---|
+| Branch is **local-only**, you want it to track main | `git pull --rebase` or `git rebase main` | Keeps your local history linear; nothing has been shared yet |
+| Branch is **shared** (already pushed, others may have pulled) | `git merge main` (or `--no-rebase`) | Rebase rewrites SHAs — collaborators' clones break |
+| You're about to **open a PR** and want clean history | `git rebase -i main` (interactive) | Squash WIP commits, reword messages, end with N tidy commits |
+| You're **landing a PR** with one logical change | **Squash-merge** on GitHub | One commit on main, clean log, PR description becomes the body |
+| You're landing a PR with multiple **already-tidy** commits | **Rebase-and-merge** on GitHub | Preserves your atomic commits; no merge bubble |
+| You're landing a long-running branch that **must show as a unit** | **Merge commit** on GitHub | Preserves the branch topology — useful for release branches |
+
+If you remember nothing else: **rebase what's only yours, merge what's already shared.**
+
+## Workflow: catching up a feature branch
+
+```bash
+# Local-only branch (fast-forward integration)
+git fetch origin
+git rebase origin/main          # replays your commits on top of main
+
+# Already pushed branch (avoid SHA churn for collaborators)
+git fetch origin
+git merge origin/main           # creates a merge commit — collaborators stay in sync
+
+# OR explicitly opt into rebase even on shared branches (coordinate first!)
+git rebase origin/main
+git push --force-with-lease     # SEE codragraph-git-force-push skill
+```
+
+## Workflow: cleaning up before opening a PR
+
+```bash
+git fetch origin
+git rebase -i origin/main       # interactive — squash, fixup, reword
+
+# Common interactive-rebase actions:
+#   pick   - keep commit
+#   reword - change message
+#   squash - merge into previous, edit combined message
+#   fixup  - merge into previous, drop this message
+#   drop   - remove the commit entirely
+```
+
+## Workflow: landing a PR (GitHub UI / `gh pr merge`)
+
+```bash
+# Squash-merge — one logical change, one commit on main:
+gh pr merge --squash --delete-branch
+
+# Rebase-and-merge — preserve your N commits as N commits on main:
+gh pr merge --rebase --delete-branch
+
+# Merge commit — preserve the branch as a unit (rare; use for releases):
+gh pr merge --merge --delete-branch
+```
+
+## Why CodraGraph helps here
+
+The hardest part of choosing a strategy isn't the mechanics — it's
+predicting whether your branch will conflict structurally with main.
+CodraGraph's `diff --semantic` tells you exactly which APIs / signatures
+changed on each side, so you can see *before* the merge whether your
+branch and main both touched the same callgraph regions.
+
+```
+codragraph diff main HEAD --semantic --json | jq '.semantic'
+→ added APIs / removed APIs / classified modifications on YOUR branch
+
+codragraph diff <last-shared-ancestor> main --semantic --json | jq '.semantic'
+→ what main has done since you forked
+```
+
+If both diffs touch overlapping symbols, prefer **merge** (preserves both
+sides as branches you can reason about) over rebase (which re-writes your
+side and may produce noisy conflicts).
+
+## Pitfalls
+
+| Pitfall | Symptom | Fix |
+|---|---|---|
+| Rebasing a shared branch | Collaborators report "diverged history", lost commits | Merge instead; don't rebase shared branches without coordination |
+| Squash-merge into long-running branch | Loses individual commit context | Use rebase-and-merge for branches that need history preserved |
+| `git pull` without `--rebase` flag on a feature branch | Random merge bubbles in your branch | Set `git config --global pull.rebase true` or always `pull --rebase` on feature branches |
+| Rebasing ON TOP of work in progress (uncommitted) | "Your local changes would be overwritten" | `git stash` first, rebase, `git stash pop` |
+
+## Checklist before merging a PR
+
+```
+- [ ] CI green (lint, tests, typecheck)
+- [ ] codragraph_detect_changes({scope: "compare", base_ref: "main"}) clean
+- [ ] codragraph diff main HEAD --semantic — review removed APIs
+- [ ] PR description matches the (would-be-squash) commit message
+- [ ] Decided strategy: squash (single change) vs rebase-and-merge (multiple atomic) vs merge (release/topology)
+- [ ] gh pr merge --squash --delete-branch  (or appropriate flag)
+```
+
+## Example: "Should I rebase or merge main into my 4-day-old branch?"
+
+```
+1. Check if the branch is shared:
+   git config branch.<your-branch>.remote
+   → "origin"  — yes, pushed.
+
+2. Check who else might have it:
+   gh api repos/{owner}/{repo}/pulls?head={your-branch} --jq '.[].user.login'
+   git log origin/<your-branch>..main --oneline | head
+   → no co-authors observed; just you and CI.
+
+3. Check structural conflict potential:
+   codragraph diff main <your-branch> --semantic
+   → 2 added APIs, 1 modified signature
+   codragraph diff <merge-base> main --semantic
+   → 0 changes touching the same files
+   → no structural conflict expected.
+
+4. Decision: rebase (it's effectively local) + force-with-lease.
+   git fetch origin
+   git rebase origin/main
+   # Resolve any conflicts file-by-file
+   git push --force-with-lease
+
+5. If structural conflict HAD been likely → merge, not rebase.
+```

package/skills/codragraph-git-recovery.md

@@ -0,0 +1,181 @@
+---
+name: codragraph-git-recovery
+description: "Use when work appears lost — bad reset, dropped commit, blown-away stash, deleted branch, broken merge, accidental rm in tracked files. Covers reflog spelunking, stash recovery, dangling-commit revival, and what's actually unrecoverable. Examples: \"I lost my commits\", \"deleted my branch\", \"reset --hard by mistake\", \"recover work\", \"reflog\""
+---
+
+# Lost-Work Recovery Playbook
+
+## When to Use
+
+- "I ran `git reset --hard` and lost my work"
+- "I deleted a branch — can I get it back?"
+- "I dropped a stash by accident"
+- "I rm'd a file and committed before I noticed"
+- "Help, I think I lost everything."
+
+## The first-aid rules
+
+1. **STOP committing.** Every new commit pushes the lost ones further into
+   the reflog. Don't `git gc`, don't clone fresh.
+2. **Don't close the terminal yet.** Some recovery paths (e.g.,
+   `ORIG_HEAD`) live until you run another mutating command.
+3. **Reflog is your friend.** Default expiry is 90 days for reachable
+   commits, 30 days for unreachable. You almost always have time.
+4. **Local-only state survives EVERYTHING except** explicit `git gc
+   --prune=now` and disk loss. Even `reset --hard` leaves the old SHAs
+   in the reflog.
+
+## Recovery paths by symptom
+
+### "I ran `git reset --hard` and lost commits"
+
+```bash
+git reflog                            # newest first
+# → look for "HEAD@{1}: commit: <message>" — that was you, before reset
+git reset --hard HEAD@{1}             # OR the explicit SHA
+```
+
+`ORIG_HEAD` is the convenience alias for "what HEAD was before the most
+recent destructive operation":
+
+```bash
+git reset --hard ORIG_HEAD            # undoes the last reset / merge / rebase
+```
+
+### "I deleted a branch (`git branch -D`) and want it back"
+
+```bash
+git reflog                            # the last entry of that branch is here
+# → look for "<branch>@{N}: ..." OR walk HEAD's history to find where you were
+git branch <branch> <sha>             # recreates the branch at the old tip
+```
+
+If the reflog entry for the branch is gone (rare), search dangling
+commits:
+
+```bash
+git fsck --lost-found
+# → "dangling commit <sha>" lines
+git show <sha>                        # inspect each candidate
+git branch <branch> <sha>             # restore the one you want
+```
+
+### "I dropped a stash with `stash drop` (or by accident)"
+
+```bash
+git fsck --unreachable | grep commit
+# → unreachable commits include dropped stashes
+git show <sha>                        # confirm it's the right stash
+git stash apply <sha>                 # apply it back (or stash branch <name> <sha>)
+```
+
+### "I committed a file I shouldn't have" (no remote push yet)
+
+```bash
+git reset --soft HEAD~1               # undo the commit, keep the changes staged
+git restore --staged <file>           # unstage the offending file
+echo "<file>" >> .gitignore
+git commit -m "<original message>"
+```
+
+If you already pushed:
+
+```bash
+git reset --soft HEAD~1
+git restore --staged <file>
+echo "<file>" >> .gitignore
+git commit -m "<original message>"
+git push --force-with-lease           # SEE codragraph-git-force-push skill
+```
+
+If the file contained secrets, `--force-with-lease` is NOT enough —
+rotate the secret first, then use `git filter-repo` or BFG to scrub
+history (see codragraph-git-history-rewrite).
+
+### "I deleted a file with `rm` (NOT git rm) and haven't committed"
+
+```bash
+git restore <file>                    # restores from index
+# OR if it was never tracked, you're out of luck — check editor backups / Time Machine
+```
+
+### "I have a broken merge in progress"
+
+```bash
+git merge --abort                     # cleanly back out
+git rebase --abort                    # for in-progress rebase
+git cherry-pick --abort               # for in-progress cherry-pick
+```
+
+If `--abort` doesn't work (rare):
+
+```bash
+git reset --merge ORIG_HEAD
+```
+
+## When recovery WON'T work
+
+| Situation | Recoverable? |
+|---|---|
+| Reset --hard within last 90 days (no `gc --prune=now`) | ✓ via reflog |
+| Branch deleted within last 30 days | ✓ via fsck or branch reflog |
+| Stash dropped within last 30 days | ✓ via fsck |
+| Untracked / unstaged files deleted with `rm` | ✗ git never saw them |
+| `.git/` dir deleted | ✗ catastrophic; restore from backup or remote |
+| `git gc --prune=now` after the disaster | ✗ unreachable objects gone |
+| Force-pushed-over commits AND local clone gone | ✗ unless GitHub Support recovers |
+
+## Recovery diagnostics
+
+```bash
+# What does my reflog look like?
+git reflog --all --date=iso | head -50
+
+# What dangling commits exist?
+git fsck --lost-found
+
+# What was HEAD recently?
+git reflog show HEAD --date=iso | head -10
+
+# What was BRANCH recently?
+git reflog show <branch> --date=iso | head -10
+
+# Where did this commit live? (by sha)
+git branch --contains <sha>
+git tag --contains <sha>
+```
+
+## Why CodraGraph helps after recovery
+
+Recovery is mechanical (reflog → reset). The real question is "did I
+actually get back what I lost?" CodraGraph's diff lets you compare:
+
+```bash
+# Compare your recovered tree to the suspected lost-work SHA:
+codragraph diff <recovered-head> <reflog-candidate-sha> --semantic
+
+# If you see addedAPIs in the candidate that aren't in your recovered HEAD,
+# the recovery is incomplete — try a different reflog entry.
+```
+
+For deleted branches with no clear "right" tip:
+
+```bash
+git fsck --lost-found
+# For each candidate dangling-commit SHA:
+codragraph diff main <dangling-sha> --semantic
+# Pick the one whose diff matches the work you remember doing.
+```
+
+## Checklist when in panic mode
+
+```
+- [ ] STOP committing / running git gc / reinstalling
+- [ ] git reflog | head -30 — see what's there
+- [ ] Identify the candidate SHA for the lost work
+- [ ] git show <sha> to verify it's the right thing
+- [ ] git reset --hard / git branch <name> <sha> / git stash apply <sha>
+- [ ] codragraph diff to verify the recovery captured the real work
+- [ ] Set up git config --global core.autocrlf and longer reflog expiry
+      (gc.reflogExpire) for the future
+```

package/skills/codragraph-git-worktree.md

@@ -0,0 +1,145 @@
+---
+name: codragraph-git-worktree
+description: "Use when working on multiple branches in parallel without re-cloning, juggling a long-running branch alongside hotfixes, or running CI/build on one branch while editing another. Covers `git worktree` setup, conventions, and gotchas. Examples: \"work on two branches at once\", \"git worktree\", \"hotfix without losing my context\", \"avoid stash-juggling\""
+---
+
+# Parallel Branches with `git worktree`
+
+## When to Use
+
+- "I'm in the middle of something and need to do a hotfix on main."
+- "I want CI to run on one branch while I edit another."
+- "I have N agents working on N branches simultaneously."
+- "I'm sick of `git stash` between branch switches."
+
+## The idea
+
+A *worktree* is a separate working directory backed by the same git
+repository. One `.git/`, many checkouts. Switching between branches no
+longer requires re-running build / re-installing deps / re-warming editor
+indexes — you just `cd` to a different directory.
+
+## Setup
+
+```bash
+# From inside your existing repo (e.g. ~/code/myrepo):
+git worktree add ../myrepo-hotfix main          # check out 'main' at ../myrepo-hotfix
+git worktree add ../myrepo-feat-x feat/x        # check out feat/x at ../myrepo-feat-x
+
+# List all worktrees:
+git worktree list
+# → /home/anit/code/myrepo            abc1234 [feature/foo]
+# → /home/anit/code/myrepo-hotfix     def5678 [main]
+# → /home/anit/code/myrepo-feat-x     fed9876 [feat/x]
+
+# Each is a real working directory. cd into it; git commands operate on its
+# checked-out branch automatically.
+cd ../myrepo-hotfix
+git status                                       # → on branch 'main'
+```
+
+## Conventions that scale
+
+```
+~/code/
+├── myrepo/                # main worktree (your "primary" branch's checkout)
+├── myrepo-hotfix/         # for emergency fixes off main
+├── myrepo-pr-143/         # parking a PR for review
+└── myrepo-bisect/         # dedicated to long-running bisects
+```
+
+Or co-locate inside the primary repo as siblings under `.worktrees/`:
+
+```bash
+mkdir -p .worktrees
+git worktree add .worktrees/hotfix main
+echo ".worktrees/" >> .gitignore                # don't index worktrees as files
+```
+
+## Removing worktrees
+
+```bash
+git worktree remove ../myrepo-hotfix
+# or, if the directory was already deleted manually:
+git worktree prune
+```
+
+## Why CodraGraph helps here
+
+Each worktree gets its own working directory but shares the `.git/`. This
+matters for indexing: CodraGraph indexes `.codragraph/` in the working
+directory, so each worktree gets its OWN index. That's actually useful:
+
+```bash
+# Two worktrees, two independent CodraGraph indexes.
+cd ~/code/myrepo                                  # primary, on feature/foo
+codragraph analyze                                # index of feature/foo
+
+cd ~/code/myrepo-hotfix                           # worktree, on main
+codragraph analyze                                # index of main
+
+# Now you can run cross-worktree impact analysis:
+codragraph_query({repo: "myrepo", query: "auth"})        # primary index
+codragraph_query({repo: "myrepo-hotfix", query: "auth"}) # main's index
+```
+
+This is especially handy for **migration tracking** (compare a
+long-running migration branch's structural state to current main without
+checking out and re-indexing repeatedly).
+
+## Pitfalls
+
+| Pitfall | What happens | Fix |
+|---|---|---|
+| Same branch checked out in two worktrees | git refuses; only one worktree per branch | Use a different branch in the second worktree (or `--detach`) |
+| Worktree dir deleted manually (no `worktree remove`) | git still tracks it as live | `git worktree prune` |
+| Hooks / config differ across worktrees | Worktrees share `.git/` but each has its own `.git/info/` and per-worktree config | Use `git config --worktree` for per-worktree settings |
+| Editor's "open repo" features confused | VS Code sometimes treats each worktree as its own repo | Open each worktree as a separate workspace; this is actually correct |
+| `npm install` in every worktree | Slow, duplicated `node_modules` | Use pnpm with shared store, or yarn berry's PnP |
+
+## Variants
+
+```bash
+# Detached HEAD worktree (no branch — useful for inspecting old commits):
+git worktree add --detach ../myrepo-old <commit-sha>
+
+# Lock a worktree (prevents `worktree prune` from cleaning it):
+git worktree lock ../myrepo-old
+
+# Move a worktree:
+git worktree move ../myrepo-old ../myrepo-archive
+```
+
+## Checklist
+
+```
+- [ ] Created worktree with a clear directory name and the right branch
+- [ ] Confirmed `git worktree list` shows all expected entries
+- [ ] Per-worktree CodraGraph index where relevant (codragraph analyze in each)
+- [ ] Editor opened per worktree (separate workspace each)
+- [ ] When done: git worktree remove <path> (or rm + git worktree prune)
+```
+
+## Example: "I need to ship a hotfix without losing my WIP"
+
+```bash
+# Currently on feature/big-refactor, 8 uncommitted files, half-broken.
+
+# 1. Create a worktree for the hotfix off main
+git worktree add ../myrepo-hotfix main
+
+# 2. cd over and do the work
+cd ../myrepo-hotfix
+git switch -c hotfix/null-pointer
+# ... edit, test, commit ...
+git push -u origin hotfix/null-pointer
+gh pr create --title "..." --body "..."
+gh pr merge --squash --delete-branch
+
+# 3. Clean up the worktree
+cd ../myrepo
+git worktree remove ../myrepo-hotfix
+
+# 4. Continue your refactor as if nothing happened
+git status                                       # still 8 uncommitted files, intact
+```