pi-graphite 0.2.2 → 0.3.0

package/README.md

@@ -1,11 +1,16 @@
 # pi-graphite
 
-Structured pi tools that wrap the [Graphite](https://graphite.com) `gt` CLI so
-agents (and humans) can drive stacked PR workflows safely from pi.
+Opinionated pi tools + skill that wrap the [Graphite](https://graphite.com)
+`gt` CLI for stacked PR workflows. Seven tools, one correct path.
 
-This package is **Layer A** of the planned design — one tool per Graphite
-domain resource (repo / stack / branch / PR / recovery), not one tool per `gt`
-subcommand and not a workflow orchestrator.
+```
+graphite_status → (graphite_setup if needed) → graphite_sync → graphite_navigate
+       → graphite_change → graphite_submit_stack (dry-run) → graphite_submit_stack (apply)
+```
+
+The extension wraps `gt` only. It deliberately does **not** call `gh`, edit PR
+titles/bodies, fetch review comments, or perform stack surgery
+(split/fold/move/squash). Use the `gt` or `gh` CLI directly for those.
 
 ## Requirements
 
@@ -27,37 +32,67 @@ pi install /path/to/pi-graphite
 pi -e /path/to/pi-graphite
 ```
 
+The package also ships a `graphite` skill (`skills/graphite/SKILL.md`) that pi
+auto-discovers. It describes the golden path and per-recipe tool calls; the
+agent loads it on demand.
+
 ## Registered tools
 
-| Tool                         | Resource | Wraps                                             |
-| ---------------------------- | -------- | ------------------------------------------------- |
-| `graphite_repo`              | repo     | `gt trunk`, `gt init`, `gt log short`             |
-| `graphite_stack_view`        | stack    | `gt log` / `gt log short` / `gt log long`         |
-| `graphite_stack_restack`     | stack    | `gt restack` (+ `--branch/--downstack/--upstack/--only`) |
-| `graphite_stack_reorganize`  | stack    | `gt move`, `gt fold`, `gt split --by-file`        |
-| `graphite_branch_inspect`    | branch   | `gt info` (+ `gt parent`, `gt children`)          |
-| `graphite_branch_create`     | branch   | `gt create`                                       |
-| `graphite_branch_update`     | branch   | `gt modify`, `gt absorb`, `gt squash`, `gt pop`, `gt rename`, `gt delete` |
-| `graphite_branch_tracking`   | branch   | `gt track`, `gt untrack`, `gt freeze`, `gt unfreeze` |
-| `graphite_branch_navigate`   | branch   | `gt checkout`, `gt up`, `gt down`, `gt top`, `gt bottom` |
-| `graphite_remote_sync`       | remote   | `gt sync`, `gt get`                               |
-| `graphite_pr_submit`         | PR       | `gt submit` (dry-run by default)                  |
-| `graphite_pr_lifecycle`      | PR       | `gt pr`, `gt merge`, `gt unlink`                  |
-| `graphite_recovery`          | recovery | `gt continue`, `gt abort`, `gt undo`              |
-
-## Conventions
-
-- Every tool requires an absolute `cwd`.
-- `gt` is invoked with `--cwd <cwd> --no-interactive` by default. No shell strings.
-- Remote / destructive operations require explicit ack flags:
-  - `graphite_pr_submit` defaults to `--dry-run`; `apply: true` needs `confirmRemote: true`.
-  - `graphite_pr_lifecycle action=merge` defaults to `--dry-run`; `apply: true` needs `confirmRemote: true`.
-  - `graphite_remote_sync` with `force` or `deleteAll` needs `confirmDestructive: true`.
-  - `graphite_branch_update action=delete close:true` needs `confirmRemote: true`.
-  - `graphite_stack_reorganize action=fold foldClose:true` needs `confirmRemote: true`.
-- Output is ANSI-stripped and truncated to ~50 KB / 2000 lines.
-- Stderr is parsed into structured `hints` (e.g. `notInitialized`, `conflictHalted`,
-  `checkedOutElsewhere`, `restackNeeded`, `trunkOutOfSync`).
+| Tool                     | Purpose                                                                 | Wraps                                          |
+| ------------------------ | ----------------------------------------------------------------------- | ---------------------------------------------- |
+| `graphite_status`        | Read-only snapshot: current stack + current branch + PR + restack hints | `gt log --stack`, `gt info`                    |
+| `graphite_setup`         | Initialize Graphite or track an existing Git branch with explicit parent | `gt init --trunk`, `gt track --parent`         |
+| `graphite_sync`          | Start-of-day / after-merge cleanup + restack                            | `gt sync`                                      |
+| `graphite_navigate`      | Move around the stack                                                   | `gt checkout`, `gt up`/`down`/`top`/`bottom`   |
+| `graphite_change`        | Create / amend a stacked branch                                         | `gt create -am`, `gt modify -am`, `gt modify --into`, `gt absorb` |
+| `graphite_submit_stack`  | Push the entire stack and open/update PRs (dry-run by default)          | `gt submit --stack --no-edit --no-ai`          |
+| `graphite_recover`       | Continue / abort / undo                                                 | `gt continue`, `gt abort`, `gt undo`           |
+
+## Golden path
+
+```text
+graphite_status
+graphite_setup                               # only if repo not initialized or branch untracked
+graphite_sync                                # at session start, or after merges
+graphite_navigate action=checkout branch=…   # move to the target PR / parent
+# user edits files
+graphite_change action=create message="…"     # or action=amend
+graphite_submit_stack apply=false             # review the dry-run plan
+graphite_submit_stack apply=true confirmRemote=true
+```
+
+Conflict path:
+
+```text
+# resolve files, git add them
+graphite_recover action=continue
+```
+
+Never run `git rebase --continue` after a gt command — use
+`graphite_recover action=continue` so Graphite propagates the resolution to
+dependent branches.
+
+## Conventions and guardrails
+
+- Every tool requires absolute `cwd`.
+- `gt` is invoked with `--cwd <cwd> --no-interactive`, no shell strings. Tools that support AI metadata pass `--no-ai`.
+- Editor / pager / browser env is forced safe (`GT_EDITOR=true`, `GT_PAGER=`,
+  `BROWSER=true`, …). Commands have a hard timeout.
+- Interactive editor / hunk / browser / reorder paths are not exposed.
+- `graphite_setup action=track_branch` requires explicit `branch`, explicit
+  `parent`, and `confirmParent:true`; do not guess parent if unclear.
+- `graphite_setup action=init_repo reset:true` needs `confirmDestructive:true`.
+- `graphite_submit_stack` defaults to `--dry-run`; `apply:true` also needs
+  `confirmRemote:true`. `--force` push also requires `confirmRemote:true`.
+- `graphite_sync` with `force` or `deleteAll` needs `confirmDestructive:true`.
+- `graphite_recover action=continue` refuses to proceed if tracked files
+  still contain `<<<<<<<` markers, unless `allowConflictMarkers:true`.
+- Output is ANSI-stripped, branded ("Graphite" not "Charcoal"), and truncated
+  to ~50 KB / 2000 lines.
+- Stderr is parsed into structured `hints`
+  (`notInitialized`, `conflictHalted`, `restackNeeded`, `trunkOutOfSync`,
+  `branchNotTracked`, `noChangesStaged`, `checkedOutElsewhere`,
+  `operatingOnTrunk`, …).
 
 ## License
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "pi-graphite",
-  "version": "0.2.2",
-  "description": "Structured pi tools for the Graphite (gt) CLI.",
+  "version": "0.3.0",
+  "description": "Opinionated pi tools + skill for stacked PR workflows with the Graphite (gt) CLI.",
   "keywords": [
     "pi",
     "pi-package",
@@ -12,12 +12,16 @@
   "license": "MIT",
   "files": [
     "src",
+    "skills",
     "README.md",
     "LICENSE"
   ],
   "pi": {
     "extensions": [
       "./src/index.ts"
+    ],
+    "skills": [
+      "./skills"
     ]
   },
   "peerDependencies": {

package/skills/graphite/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: graphite
+description: Manage stacked PRs with the Graphite (gt) CLI via the pi-graphite extension. Use when creating, updating, navigating, or pushing a Graphite stack, or when recovering from a halted gt command. Wraps `gt` only — does not touch PR titles/bodies, reviews, or stack surgery.
+---
+
+# Graphite (pi-graphite)
+
+This skill drives the [pi-graphite](https://www.npmjs.com/package/pi-graphite)
+extension. The extension is a deliberately small, opinionated wrapper around
+the Graphite (`gt`) CLI. There is exactly one correct workflow; follow it.
+
+## When to use
+
+Use this skill whenever the user wants to:
+
+- start work on a stacked-PR repo
+- create a new PR on top of the current branch
+- amend an existing PR with new changes
+- push the current stack to GitHub
+- sync after PRs merged on `main`
+- recover from a gt conflict
+
+Do not use it for:
+
+- editing PR titles / bodies / labels / reviewers metadata (use `gh` directly)
+- reading PR review comments or CI status (use `gh` directly)
+- rewriting history beyond create/amend (split/fold/move/squash) — use the
+  raw `gt` CLI via bash if the user explicitly asks; the extension does not
+  expose stack surgery
+
+## Tools
+
+The extension registers seven tools. Prefer them over `gt`/`git`/`gh` in bash.
+
+| Tool | Purpose |
+|---|---|
+| `graphite_status` | Read-only snapshot: current stack + current branch + PR + restack hint |
+| `graphite_setup` | Initialize Graphite or track an existing Git branch with explicit parent |
+| `graphite_sync` | `gt sync` — pull trunk, drop merged branches, restack |
+| `graphite_navigate` | `gt checkout` / `up` / `down` / `top` / `bottom` / trunk |
+| `graphite_change` | `gt create` / `gt modify` / `gt modify --into` / `gt absorb` |
+| `graphite_submit_stack` | `gt submit --stack --no-edit` (dry-run by default) |
+| `graphite_recover` | `gt continue` / `gt abort` / `gt undo` |
+
+All tools require an absolute `cwd`.
+
+## Golden path
+
+```
+graphite_status
+     ↓
+graphite_setup                      (only if repo not initialized or branch untracked)
+     ↓
+graphite_sync                       (start of session, or after PRs merged)
+     ↓
+graphite_navigate                   (move to the branch you want to mutate)
+     ↓
+graphite_change                     (create or amend)
+     ↓
+graphite_submit_stack apply=false   (review dry-run plan)
+     ↓
+graphite_submit_stack apply=true    (push, with confirmRemote=true)
+   confirmRemote=true
+```
+
+When a `gt` command halts on conflict:
+
+```
+resolve files in editor → git add <files> → graphite_recover action="continue"
+```
+
+Never run `git rebase --continue` after a Graphite-initiated rebase; use
+`graphite_recover action="continue"` so Graphite propagates the resolution
+to dependent branches.
+
+## Recipes
+
+### Initialize repo if Graphite is missing
+
+If a tool reports `notInitialized`:
+
+```
+# Ask user for trunk if unclear.
+graphite_setup({ cwd, action: "init_repo", trunk: "main" })
+graphite_status({ cwd })
+```
+
+If resetting existing Graphite metadata is explicitly intended:
+
+```
+graphite_setup({ cwd, action: "init_repo", trunk: "main", reset: true, confirmDestructive: true })
+```
+
+### Track existing Git branch if untracked
+
+If a tool reports `branchNotTracked`:
+
+1. Identify the intended Graphite parent branch.
+2. If parent is unclear, ask the user.
+3. Track only after parent is confirmed.
+
+```
+graphite_setup({
+  cwd,
+  action: "track_branch",
+  branch: "<existing-git-branch>",
+  parent: "<intended-parent-branch>",
+  confirmParent: true,
+})
+graphite_status({ cwd })
+```
+
+Never guess parent silently. Wrong parent means wrong stack shape.
+
+### Start a session
+
+```
+graphite_status({ cwd })
+graphite_sync({ cwd })          # pull trunk, drop merged, restack
+graphite_status({ cwd })        # confirm state
+```
+
+### Create a new PR on top of the current branch
+
+```
+graphite_status({ cwd })                     # confirm position
+# ... user makes code changes ...
+graphite_change({ cwd, action: "create", message: "..." })
+graphite_submit_stack({ cwd, apply: false })
+# review plan with user; then:
+graphite_submit_stack({ cwd, apply: true, confirmRemote: true })
+```
+
+### Update an existing PR
+
+```
+graphite_status({ cwd })
+graphite_navigate({ cwd, action: "checkout", branch: "<pr-branch>" })
+# ... user makes code changes ...
+graphite_change({ cwd, action: "amend", message: "..." })
+graphite_submit_stack({ cwd, apply: false })
+graphite_submit_stack({ cwd, apply: true, confirmRemote: true })
+```
+
+### Add a child PR off a specific parent
+
+```
+graphite_navigate({ cwd, action: "checkout", branch: "<parent-branch>" })
+# ... changes ...
+graphite_change({ cwd, action: "create", message: "..." })
+graphite_submit_stack({ cwd, apply: false })
+```
+
+### Land changes into a downstack branch
+
+```
+# Make the change locally (working tree dirty).
+graphite_change({ cwd, action: "amend_into", into: "<downstack-branch>", message: "..." })
+graphite_status({ cwd })
+graphite_submit_stack({ cwd, apply: false })
+```
+
+For larger reshuffles touching several downstack commits, prefer `absorb`:
+
+```
+graphite_change({ cwd, action: "absorb" })             # dry-run
+graphite_change({ cwd, action: "absorb", apply: true }) # apply
+```
+
+### After PRs in the stack merge
+
+```
+graphite_sync({ cwd })
+graphite_status({ cwd })
+```
+
+If `gt sync` halts on conflict, use the conflict recipe below.
+
+### Resolve a conflict
+
+1. Read the failing tool's `--- stderr ---` and `hints` block.
+2. Resolve markers in the listed files.
+3. `git add <files>` from bash.
+4. `graphite_recover({ cwd, action: "continue" })`.
+5. If you want to bail entirely: `graphite_recover({ cwd, action: "abort" })`.
+
+If you made a mistake with the last gt command:
+
+```
+graphite_recover({ cwd, action: "undo" })
+```
+
+## Rules
+
+- **Submit stacks, not branches.** `graphite_submit_stack` always passes
+  `--stack`. Do not look for a single-branch submit; if the user truly wants
+  to push only one branch, use `gt submit --branch=<name>` via bash and
+  explain why.
+- **Use `graphite_setup` only for preconditions.** Initialize missing repos
+  or track existing Git branches. Do not use it for daily branch creation;
+  use `graphite_change action="create"` instead.
+- **Never guess tracking parent.** `track_branch` requires explicit branch,
+  explicit parent, and `confirmParent:true`.
+- **Prefer `graphite_sync` over manual restack.** The extension does not
+  expose a standalone restack tool. Sync covers both pull + restack.
+- **Always dry-run first.** Show the user the dry-run plan from
+  `graphite_submit_stack apply=false` before pushing.
+- **`apply:true` requires `confirmRemote:true`.** The tool will refuse
+  otherwise. This is intentional friction.
+- **Destructive sync flags require `confirmDestructive:true`** (`force`,
+  `deleteAll`).
+- **Never use `git rebase --continue` after a gt command.** Use
+  `graphite_recover action="continue"`.
+- **This extension wraps gt only.** For PR body/title edits, review
+  comments, check runs, etc., shell out to `gh` directly in bash — do not
+  expect a tool from this extension.
+- **No interactive editor / browser / hunk picker.** All paths are
+  non-interactive; pass explicit messages.

package/src/index.ts

@@ -1,65 +1,52 @@
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
 
-import { registerRepo } from "./tools/repo";
-import {
-  registerStackView,
-  registerStackRestack,
-  registerStackReorganize,
-} from "./tools/stack";
-import {
-  registerBranchInspect,
-  registerBranchCreate,
-  registerBranchUpdate,
-  registerBranchTracking,
-  registerBranchNavigate,
-} from "./tools/branch";
-import { registerRemoteSync } from "./tools/remote";
-import { registerPrSubmit, registerPrLifecycle } from "./tools/pr";
-import { registerRecovery } from "./tools/recovery";
+import { registerStatus } from "./tools/status";
+import { registerSetup } from "./tools/setup";
+import { registerSync } from "./tools/sync";
+import { registerNavigate } from "./tools/navigate";
+import { registerChange } from "./tools/change";
+import { registerSubmitStack } from "./tools/submit";
+import { registerRecover } from "./tools/recover";
 
 /**
- * pi-graphite — Layer A (Domain Resource).
+ * pi-graphite — opinionated `gt` wrapper for stacked PR workflows.
  *
- * Registers structured tools that wrap the Graphite (`gt`) CLI:
+ * Seven workflow tools, one correct path:
  *
- *   graphite_repo
- *   graphite_stack_view
- *   graphite_stack_restack
- *   graphite_stack_reorganize
- *   graphite_branch_inspect
- *   graphite_branch_create
- *   graphite_branch_update
- *   graphite_branch_tracking
- *   graphite_branch_navigate
- *   graphite_remote_sync
- *   graphite_pr_submit
- *   graphite_pr_lifecycle
- *   graphite_recovery
+ *   graphite_status        — see where you are in the stack
+ *   graphite_setup         — init repo / track existing branch when needed
+ *   graphite_sync          — start-of-day / after-merge cleanup + restack
+ *   graphite_navigate      — move to the branch / PR you want to mutate
+ *   graphite_change        — create or amend a stacked branch
+ *   graphite_submit_stack  — push the whole stack and open/update PRs
+ *   graphite_recover       — continue / abort / undo after conflicts or mistakes
+ *
+ * Golden path:
+ *
+ *   status → (setup if needed) → sync → navigate → change → submit_stack(dry-run) → submit_stack(apply)
+ *
+ * Conflict path:
+ *
+ *   resolve files → graphite_recover continue
  *
  * Conventions:
  * - Every tool requires absolute `cwd`.
- * - `gt` is invoked with --cwd <cwd> --no-interactive by default.
- * - Remote / destructive operations require explicit `confirmRemote` /
- *   `confirmDestructive` flags. Submit/merge default to dry-run.
- * - Output is ANSI-stripped and truncated to ~50KB / 2000 lines.
+ * - `gt` is invoked with --cwd <cwd> --no-interactive by default; tools that support AI metadata pass --no-ai.
+ * - Editor / pager / browser env is forced safe; interactive editor / hunk /
+ *   browser flows are not exposed.
+ * - graphite_submit_stack defaults to --dry-run; apply requires
+ *   `apply:true` AND `confirmRemote:true`.
+ * - graphite_sync with force / deleteAll requires `confirmDestructive:true`.
+ * - This extension wraps `gt` only. It deliberately does not call `gh`,
+ *   touch PR titles/bodies, run reviews, or do stack surgery
+ *   (split/fold/move/squash). Use the gt CLI or another tool for those.
  */
 export default function (pi: ExtensionAPI) {
-  registerRepo(pi);
-
-  registerStackView(pi);
-  registerStackRestack(pi);
-  registerStackReorganize(pi);
-
-  registerBranchInspect(pi);
-  registerBranchCreate(pi);
-  registerBranchUpdate(pi);
-  registerBranchTracking(pi);
-  registerBranchNavigate(pi);
-
-  registerRemoteSync(pi);
-
-  registerPrSubmit(pi);
-  registerPrLifecycle(pi);
-
-  registerRecovery(pi);
+  registerStatus(pi);
+  registerSetup(pi);
+  registerSync(pi);
+  registerNavigate(pi);
+  registerChange(pi);
+  registerSubmitStack(pi);
+  registerRecover(pi);
 }

package/src/lib/argv.ts

@@ -0,0 +1,59 @@
+/**
+ * Argv construction helpers used by every gt tool to harden against
+ * argv/flag-injection from user-controlled strings.
+ *
+ * Threat model: tool parameters (branch, message, onto, target, ...) end up
+ * as argv tokens passed to `gt`. `gt`'s yargs parser will happily interpret
+ * any token that starts with `-` as an option — including `--interactive`,
+ * which silently overrides our earlier `--no-interactive` and re-enables
+ * TTY prompts. It will also swallow the *next* argv token as the value of a
+ * preceding option (e.g. `--message` `--interactive` => message is dropped,
+ * --interactive becomes a flag).
+ *
+ * Two defenses:
+ *
+ *  1) For positional/ref values (branch names, refs, paths, PR numbers) we
+ *     require that the value does not start with `-`. Git branch names
+ *     cannot validly start with `-`; pathspecs and PR numbers shouldn't for
+ *     these tools either.
+ *
+ *  2) For option *values* we emit `--flag=value` as a single argv token
+ *     instead of two tokens `--flag` `value`. yargs binds the value to the
+ *     option literally regardless of leading `-`, so the value can never be
+ *     re-parsed as a flag.
+ */
+
+export function assertSafeRef(value: string, label: string): string {
+  if (typeof value !== "string") {
+    throw new Error(`${label} must be a string.`);
+  }
+  if (value === "") {
+    throw new Error(`${label} must not be empty.`);
+  }
+  if (value === "--") {
+    throw new Error(`${label} must not be "--".`);
+  }
+  if (value.startsWith("-")) {
+    throw new Error(
+      `${label} must not start with "-" (got ${JSON.stringify(value)}). ` +
+        `Refused to prevent flag injection into the gt CLI.`,
+    );
+  }
+  return value;
+}
+
+/**
+ * Build a single argv token `--flag=value`. Use for option values supplied
+ * by the caller. The `=` form binds the value to the flag literally so a
+ * value like `--interactive` is preserved as data instead of being parsed
+ * as the next option.
+ */
+export function flagEq(flag: string, value: string | number): string {
+  if (!flag.startsWith("--")) {
+    throw new Error(`flagEq: flag must start with "--", got ${flag}`);
+  }
+  if (flag.includes("=")) {
+    throw new Error(`flagEq: flag must not already contain "=" (got ${flag}).`);
+  }
+  return `${flag}=${value}`;
+}