Add scm-flow extension for pi

Author: flyinggrizzly

lib/pi/agent/extensions/scm-flow/README.md

@@ -0,0 +1,304 @@
+---
+summary: Positive intent→cmd layer over gt/git in Graphite repos. Replaces raw shell strings with structured tools.
+commands: [/scm-flow]
+tools:
+  - scm_add
+  - scm_restore
+  - scm_branch_create
+  - scm_branch_checkout
+  - scm_branch_rename
+  - scm_branch_delete
+  - scm_commit
+  - scm_reset
+  - scm_revert
+  - scm_cherry_pick
+  - scm_stack_log
+  - scm_stack_track
+  - scm_stack_restack
+  - scm_stack_sync
+  - scm_stack_submit
+category: workflow
+keywords: [git, graphite, gt, stacking, scm]
+status: scaffold
+---
+
+# scm-flow
+
+A positive intent→command layer over `gt`/`git` in Graphite-managed repos.
+
+## Why
+
+`prefer-graphite` blocks raw mutating `git` and tells the agent to use `gt`. That's the
+**negative** half. Logs from `~/.agents/var/logs/prefer-graphite/` showed the agent:
+
+- defaulted to `git add && git commit` despite the redirect (8 occurrences in 2 weeks)
+- obfuscated `git` invocations (`/usr/bin/git`, `g""it`) to bypass interception
+- iterated on `gt modify` flags (`-c`, `-a`, `-u`, `-F`, `--no-interactive`) to find the right combo
+- hit the **untracked-branch wall** on `gt branch info` / `gt log -s` and required rescue with `gt track -p main`
+- broke multi-line commit messages built via `cat /tmp/file && gt modify -m "$(cat …)"` across shell-call boundaries
+- couldn't tell `gt submit --no-edit` vs `--no-interactive` vs `--branch` vs `--stack` apart
+
+This extension adds the **positive** half: structured tools the agent calls with typed
+arguments. The tool layer absorbs the gt-flag soup, tmpfile lifecycle, and stack-aware
+state coordination.
+
+## Mental model
+
+The agent thinks in **git verbs** for ops on commits/branches:
+`scm_add`, `scm_restore`, `scm_branch_create`, `scm_branch_checkout`, `scm_commit`,
+`scm_reset`, `scm_revert`, etc.
+
+The agent uses **`scm_stack_*`** for graphite-native stack ops with no clean git equivalent:
+`scm_stack_log`, `scm_stack_track`, `scm_stack_restack`, `scm_stack_sync`, `scm_stack_submit`.
+
+## Components
+
+| File | Purpose |
+|---|---|
+| `index.ts` | Wires hooks, commands, and tool registration |
+| `detect.ts` | `isGraphiteRepo()` — walk-up + git-common-dir worktree detection, per-dir cache |
+| `parse.ts` | Quote-aware command parsing: `splitSubCommands`, `stripQuotedContent`, `stripHeredocBodies`, `isGitCommand`, `isShellDispatcher` |
+| `interceptor.ts` | `pi.on("tool_call")` hook: blocks raw mutating git with tool hints; passes through read-only ops; detects obfuscation |
+| `system-prompt.ts` | `buildSystemPromptAddition()` — injected via `before_agent_start` when in a graphite repo |
+| `tools/_helpers.ts` | Shared exec primitives, tmpfile lifecycle, stack-state detection |
+| `tools/_schemas.ts` | Shared TypeBox primitive schemas |
+| `tools/<verb>.ts` | One file per `scm_*` tool |
+
+## Tool → shell-op map
+
+### Git-aligned (commits / branches)
+
+| Tool | Shell op |
+|---|---|
+| `scm_add` | `git add [-N] <paths…>` |
+| `scm_restore` | staged: `git restore --staged <paths>` · worktree: `git restore [--source <ref>] <paths>` |
+| `scm_branch_create` | `git checkout -b <name> && gt track --parent <parent ?? current>` |
+| `scm_branch_checkout` | optional `gt get <name>`; then `gt co <name>` |
+| `scm_branch_rename` | `gt rename <new_name>` |
+| `scm_branch_delete` | `gt delete <name> -q [-f] [--upstack] [--downstack] [-c]` |
+| `scm_commit` | new: `gt modify -c [-u] -F <tmpfile> --no-interactive` · amend: `gt modify [-u] [-F tmpfile \| --no-edit] --no-interactive` |
+| `scm_reset` | `git reset --<mode> <target>`; if children & `auto_restack`: `gt restack` |
+| `scm_revert` | `git revert [-m N] <shas…>`; if children & `auto_restack`: `gt restack` |
+| `scm_cherry_pick` | `git cherry-pick <shas…>`; if children & `auto_restack`: `gt restack` |
+
+### gt-native (stack-as-graph)
+
+| Tool | Shell op |
+|---|---|
+| `scm_stack_log` | reads `.graphite_cache_persist` + `.graphite_pr_info` → recursive tree + orphans |
+| `scm_stack_track` | `gt track --parent <parent>` |
+| `scm_stack_restack` | `gt restack` (defers to `restack-workflow` on conflicts when detected via `pi.getAllTools()`) |
+| `scm_stack_sync` | `gt sync --no-interactive` + before/after cache diff (trunk advance, pruned, newly-valid) |
+| `scm_stack_submit` | `gt submit --no-interactive […]` + before/after `.graphite_pr_info` diff (per-branch action: created/updated/unchanged/failed) |
+
+## Locked design defaults
+
+- `scm_branch_create({allow_dirty: false})` — default false, errors on dirty worktree; `allow_dirty: true` carries changes over (matches git's default `checkout -b` semantics)
+- `scm_branch_checkout({fetch_if_missing: true})` — default true, auto-runs `gt get <name>` if branch missing locally
+- `scm_branch_checkout` target-untracked-in-graphite: **warn-return** (succeed, surface `tracked: false` in result)
+- `scm_commit({amend: true})` on already-pushed commits: **succeed** (matches git semantics; force-push handled later via `scm_stack_submit`)
+- `scm_stack_log` returns `{trunks: StackNode[], orphaned: StackNode[]}` — trunks recursive, orphans flat. Orphans surface branches in the graphite cache with `BAD_PARENT_NAME`/`INVALID_PARENT` (typically created via raw `git checkout -b` without `gt track`) so the agent sees them too; their `needs_restack` is always true.
+- `scm_commit` auto-appends `Co-authored-by: AI (Pi/<model-id>) <noreply@pi.dev>` to commit body unless `co_author: false`. Model id is read from `ctx.model.id` at execute time (eg `claude-sonnet-4-5`); falls back to `AI (Pi)` when unknown.
+- `scm_reset` / `scm_revert` default `auto_restack: true` — fires `gt restack` after if descendants exist; surfaces conflicts in result without resolving
+- `scm_stack_restack` runs `gt restack`; on conflicts, checks `pi.getAllTools()` for `restack_run` and emits an enhanced hint pointing at `restack-workflow`'s context-aware flow if it's loaded
+- `scm_stack_submit` / `scm_stack_sync` parse graphite's JSON cache (`.graphite_cache_persist`, `.graphite_pr_info`) before & after invocation — more robust than parsing the CLI's emoji-decorated stdout, which varies between gt releases
+
+## Commands
+
+| Command | Effect |
+|---|---|
+| `/scm-flow` | Toggle interceptor + tool registration on/off |
+| `/scm-flow on` | Force enable |
+| `/scm-flow off` | Force disable (raw git allowed; tools still registered but unused) |
+| `/scm-flow status` | Show toggle state + detected graphite repo root + system-prompt injection state |
+
+## Detection
+
+Auto-detects graphite repos via `isGraphiteRepo(cwd)`:
+
+1. Walks up from `cwd` looking for `.graphite/` directory
+2. Falls back to `git rev-parse --git-common-dir` + check for `.graphite_repo_config` (worktree layout, eg `~/world`)
+
+Results cached per resolved-cwd for the session.
+
+### Scope: `ctx.cwd`, not bash-effective cwd
+
+The interceptor evaluates `isGraphiteRepo(ctx.cwd)` where `ctx.cwd` is **pi's
+session cwd at the time the hook fires** — i.e. the directory pi was launched
+in (or last `/cd`'d to). It is NOT the bash command's effective cwd after any
+internal `cd <path> && …`.
+
+Consequence: every git command in a pi session inherits the graphite-or-not
+verdict of the launch directory. If pi was launched in `~/world/trees/root/src`
+(graphite), a bash call like `cd ~/nixfiles && git revert --abort` will still
+be intercepted as if it ran in `~/world`. The block message is correct from
+pi's project-context perspective, but may look surprising at the bash level.
+
+This matches `prefer-graphite`'s behavior. If you genuinely need to escape the
+interception for a one-off cross-repo command, run `/scm-flow off`, do the work,
+and re-enable with `/scm-flow on`.
+
+## Interception (carried from `prefer-graphite`, extended)
+
+### Passthrough (read-only + safe-no-stack-impact)
+
+`git status`, `git diff`, `git log`, `git show`, `git blame`, `git grep`, `git rev-parse`,
+`git describe`, `git ls-files`, `git ls-tree`, `git cat-file`, `git for-each-ref`,
+`git stash`, `git fetch`, `git worktree`, `git mv`, `git rm`, `git tag`, `git notes`,
+`git clean`, plus heuristic-classified pathspec-form `git reset <path>` and
+`git restore <path>` (no `HEAD`/`@`/`^`/`~`/`--soft`/`--mixed`/`--hard`/`--staged`/sha-ish args).
+
+### Redirect (mutating git → tool hint)
+
+| Raw | → Tool |
+|---|---|
+| `git add` | `scm_add` |
+| `git restore --staged …` / `git reset --staged …` | `scm_restore({staged: true})` |
+| `git checkout <branch>` / `git switch <branch>` | `scm_branch_checkout` |
+| `git checkout -b` / `git switch -c` | `scm_branch_create` |
+| `git checkout -B` | hard block — use `scm_branch_delete` + `scm_branch_create` |
+| `git branch -m` | `scm_branch_rename` |
+| `git branch -d/-D` | `scm_branch_delete` *(v1.1)* |
+| `git commit` | `scm_commit` |
+| `git commit --amend` | `scm_commit({amend: true})` |
+| `git push` | `scm_stack_submit` |
+| `git pull` | `scm_stack_sync` |
+| `git rebase` | `scm_stack_restack` |
+| `git reset HEAD~/sha/--hard …` | `scm_reset` |
+| `git revert` | `scm_revert` |
+| `git cherry-pick` | `scm_cherry_pick` *(v1.1)* |
+| `git merge` | `gt fold` (no tool — rare) |
+
+### Obfuscation block
+
+Hard-blocks: `/usr/bin/git`, `g""it`, `g\"\"it`, `\git`, `command git`.
+
+### Quoted arguments
+
+Text inside single- or double-quoted arguments is stripped before matching (prevents
+false allow/block from commit-message body or grep patterns). Shell dispatchers
+(`bash -c "…"`, `eval "…"`) are special-cased — their quoted arg IS the command.
+
+## System prompt injection
+
+When in a graphite repo (via `isGraphiteRepo(cwd)`), prepends a tool-mapping summary to
+the system prompt via `before_agent_start`. Inert in non-graphite repos.
+
+See `system-prompt.ts` for content.
+
+## Tests
+
+Tests use [vitest](https://vitest.dev) (same as `prefer-graphite`). They live
+alongside the modules they cover:
+
+| File | Tests | Style |
+|---|---|---|
+| `parse.test.ts` | 49 | pure-fn |
+| `interceptor.test.ts` | 45 | pure-fn |
+| `tools/_helpers.test.ts` | 17 | pure-fn |
+| `tools/stack_log.test.ts` | 21 | pure-fn |
+| `tools/stack_submit.test.ts` | 8 | pure-fn |
+| `tools/stack_sync.test.ts` | 7 | pure-fn |
+| `tools/commit.test.ts` | 13 | `vi.mock`'d |
+| `tools/branch_create.test.ts` | 15 | `vi.mock`'d |
+| `tools/branch_delete.test.ts` | 13 | `vi.mock`'d |
+| `tools/cherry_pick.test.ts` | 12 | `vi.mock`'d |
+
+### Running via vitest
+
+Vitest isn't shipped in the deployed pi binary; tests run in the pi monorepo's
+dev environment, where `npx vitest` (or `pnpm vitest`) is available.
+
+From inside a pi monorepo dev checkout:
+
+```bash
+# Symlink (or copy) this extension into the monorepo's extensions/ dir, then:
+npx vitest run extensions/scm-flow/
+
+# Or target a single file:
+npx vitest run extensions/scm-flow/interceptor.test.ts
+
+# Watch mode:
+npx vitest extensions/scm-flow/
+```
+
+This mirrors the `prefer-graphite` convention (see the comment block at the top
+of each test file).
+
+### Standalone smoke run (no vitest required)
+
+The pure-fn tests (`parse.test.ts`, `interceptor.test.ts`,
+`tools/_helpers.test.ts`) can be executed without vitest using a minimal stub:
+
+```bash
+cd /tmp && rm -rf scm-flow-smoke && mkdir scm-flow-smoke && cd scm-flow-smoke
+ln -sfn ~/nixfiles/lib/pi/agent/extensions/scm-flow src
+
+# Write a 30-line vitest stub at node_modules/vitest/{index.js,index.d.ts}
+# (describe/it/expect/beforeEach → node:assert; ignores vi.mock).
+# See the inline harness used during development.
+
+# Compile + run:
+npx tsc -p tsconfig.compile-tests.json
+node run-vitest-stub.mjs ./dist-tests/parse.test.js \
+  ./dist-tests/interceptor.test.js \
+  ./dist-tests/tools/_helpers.test.js
+```
+
+The `vi.mock`-based tests (`commit.test.ts`, `branch_create.test.ts`) cannot run
+under the stub — they need real vitest's module-mocking infrastructure.
+
+### Typecheck only
+
+```bash
+npx tsc -p .   # any tsconfig with strict + nodeNext resolution
+```
+
+A reference tsconfig that satisfies the imports (assuming `pi-coding-agent`
+0.74.x and `typebox` 1.1.x are wired into `node_modules/`):
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "strict": true,
+    "noEmit": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true
+  },
+  "include": ["**/*.ts"]
+}
+```
+
+### What to add when changing the extension
+
+| Change | Add a test in |
+|---|---|
+| Parse primitive (split, strip, dispatcher, obfuscation) | `parse.test.ts` |
+| Interceptor passthrough or redirect | `interceptor.test.ts` |
+| Tool result-shape or message-composition helper | `tools/_helpers.test.ts` |
+| New `scm_*` tool | new `tools/<tool>.test.ts` mirroring `commit.test.ts` (mocks `_helpers.js` via `vi.mock`, captures the registered tool via a fake `pi.registerTool`, asserts shell-op args + result shape) |
+
+## Status
+
+**v1.1 complete.** All 15 tools functional. Plumbing carries `prefer-graphite`'s
+tested helpers verbatim. Stack-* parsers read graphite's JSON cache rather than
+`gt` text output for stability.
+
+**Test coverage**: 154 standalone (pure-fn) tests pass. Mock-based tool tests
+(`commit`, `branch_create`, `branch_delete`, `cherry_pick`) add 53 more for
+guardrail and exec-shape verification — require real vitest to run.
+
+## Future (v1.2+)
+
+- `renderResult` collapsible TUI rendering (mirror `restack-workflow`'s
+  `renderExpandableToolResult` — needs `pi-tui` import that works at runtime
+  via pi's bundler but lacks local types; defer until needed)
+- Mock-based tests for the remaining tool execute() paths (currently:
+  `commit`, `branch_create`, `branch_delete`, `cherry_pick`; missing:
+  `branch_checkout`, `restore`, `reset`, `revert`, `stack_log`/`submit`/`sync`
+  execute paths, `stack_restack`, `stack_track`, `branch_rename`, `add`)
+- Live integration round in a worktree — try `scm_stack_submit` and
+  `scm_stack_sync` against an actual stack to validate the cache-diff approach