pi-graphite 0.5.0 → 0.6.0

package/README.md

@@ -9,8 +9,10 @@ graphite_status → (graphite_setup if needed) → graphite_sync → graphite_na
 ```
 
 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 / reorder). For those flows, run the underlying `gt`
+PR titles/bodies, fetch review comments, or perform interactive stack surgery
+(split / fold / squash / reorder). Reparenting a tracked branch IS supported
+via `graphite_move` (`gt move --source --onto`, non-interactive). For the
+remaining surgery flows, run the underlying `gt`
 or `gh` command yourself in your own terminal; the agent should not invoke
 them from bash, as their defaults open interactive prompts, hunk pickers,
 or editors that will hang non-interactive sessions.
@@ -48,6 +50,7 @@ agent loads it on demand.
 | `graphite_sync`          | Start-of-day / after-merge cleanup + restack                            | `gt sync`                                      |
 | `graphite_get`           | Pull a branch / stack from the remote                                   | `gt get <branch>`                              |
 | `graphite_navigate`      | Move around the stack                                                   | `gt checkout`, `gt up`/`down`/`top`/`bottom`   |
+| `graphite_move`          | Reparent a tracked branch + restack descendants (dry-run by default)    | `gt move --source --onto`                      |
 | `graphite_change`        | Create / amend a stacked branch                                         | `gt create -am`, `gt modify -am`, `gt modify --into`, `gt absorb` |
 | `graphite_submit`  | Push the entire stack and open/update PRs (dry-run by default)          | `gt submit --stack --no-edit --no-ai`          |
 | `graphite_recover`       | Continue / abort / undo / restack                                       | `gt continue`, `gt abort`, `gt undo`, `gt restack` |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-graphite",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Opinionated pi tools + skill for stacked PR workflows with the Graphite (gt) CLI.",
   "keywords": [
     "pi",
@@ -12,7 +12,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+ssh://git@github.com/tianrendong/pi-graphite.git"
+    "url": "git+https://github.com/tianrendong/pi-graphite.git"
   },
   "bugs": {
     "url": "https://github.com/tianrendong/pi-graphite/issues"

package/skills/graphite/SKILL.md

@@ -25,10 +25,14 @@ Do not use it for:
 - editing PR titles / bodies / labels / reviewers metadata — prefer a
   dedicated `gh` tool/extension; see the `gh` rule below
 - reading PR review comments or CI status — same
-- rewriting history beyond create/amend (split / fold / move / squash /
-  reorder). The extension does not expose stack surgery, and those
-  subcommands prompt interactively (base selectors, hunk pickers, editors)
-  and will hang. Ask the user to run them in their own terminal.
+- reparenting a tracked branch onto a different parent — use
+  `graphite_move` (it runs `gt move --source --onto` non-interactively and
+  rebases descendants). Do NOT use `track_branch --force` for this; that only
+  rewrites tracking metadata and leaves commits unrebased.
+- rewriting history beyond create/amend/move (split / fold / squash /
+  reorder). The extension does not expose those, and they prompt
+  interactively (base selectors, hunk pickers, editors) and will hang. Ask
+  the user to run them in their own terminal.
 
 ## Tools
 
@@ -41,6 +45,7 @@ The extension registers these tools. Prefer them over `gt`/`git`/`gh` in bash.
 | `graphite_sync` | `gt sync` — pull trunk, drop merged branches, restack |
 | `graphite_get` | `gt get <branch>` — pull a branch / stack from the remote |
 | `graphite_navigate` | `gt checkout` / `up` / `down` / `top` / `bottom` / trunk |
+| `graphite_move` | `gt move --source --onto` — reparent a tracked branch + restack descendants (dry-run by default) |
 | `graphite_change` | `gt create` / `gt modify` / `gt modify --into` / `gt absorb` |
 | `graphite_submit` | `gt submit --stack --no-edit` (dry-run by default) |
 | `graphite_recover` | `gt continue` / `gt abort` / `gt undo` / `gt restack` |
@@ -212,6 +217,24 @@ graphite_status({ cwd })
 Use `graphite_sync` instead when trunk itself may have advanced on the remote.
 If restack halts on a conflict, follow the conflict recipe.
 
+### Reparent a tracked branch onto a new parent
+
+When an existing tracked branch is stacked on the wrong parent and you need a
+real rebase (not just a metadata fix):
+
+```
+graphite_status({ cwd })                                  # confirm shapes
+graphite_move({ cwd, branch: "<branch>", parent: "<new-parent>" })   # dry-run plan
+# review the plan, then apply:
+graphite_move({ cwd, branch: "<branch>", parent: "<new-parent>", apply: true, confirmDestructive: true })
+```
+
+The move rebases `<branch>` and all of its descendants onto `<new-parent>`.
+If it halts on a conflict, follow the conflict recipe (resolve →
+`graphite_recover action="continue"`). To chain several reparents (e.g.
+rebuild a stack A→B→C), move the lowest branch first, then each next branch
+onto its new parent, running `graphite_status` between steps.
+
 ### Pull a branch / stack from the remote
 
 To check out a teammate's branch, or re-pull a branch that changed remotely:
@@ -261,6 +284,11 @@ graphite_recover({ cwd, action: "undo" })
 - **Restack vs sync.** Use `graphite_recover action="restack"` to rebase the
   stack onto each parent's latest commit when no remote pull is needed. Use
   `graphite_sync` when trunk may have advanced remotely (it pulls + restacks).
+- **Reparent with `graphite_move`, not `track_branch --force`.**
+  `graphite_move` runs `gt move --source --onto`, which rebases commits and
+  restacks descendants. `track_branch --force` only rewrites tracking
+  metadata and leaves the stack in an inconsistent shape. Always dry-run
+  first; `apply:true` requires `confirmDestructive:true`.
 - **Pull remote branches with `graphite_get`.** `graphite_sync` only touches
   trunk + already-tracked local branches; use `graphite_get` to download a
   branch/stack from the remote.

package/src/index.ts

@@ -5,6 +5,7 @@ import { registerSetup } from "./tools/setup";
 import { registerSync } from "./tools/sync";
 import { registerGet } from "./tools/get";
 import { registerNavigate } from "./tools/navigate";
+import { registerMove } from "./tools/move";
 import { registerChange } from "./tools/change";
 import { registerSubmit } from "./tools/submit";
 import { registerRecover } from "./tools/recover";
@@ -19,6 +20,7 @@ import { registerRecover } from "./tools/recover";
  *   graphite_sync          — start-of-day / after-merge cleanup + restack
  *   graphite_get           — pull a branch / stack from the remote
  *   graphite_navigate      — move to the branch / PR you want to mutate
+ *   graphite_move          — reparent an existing tracked branch (stack surgery)
  *   graphite_change        — create or amend a stacked branch
  *   graphite_submit  — push the whole stack and open/update PRs
  *   graphite_recover       — continue / abort / undo / restack
@@ -40,8 +42,10 @@ import { registerRecover } from "./tools/recover";
  *   `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.
+ *   touch PR titles/bodies, run reviews, or do interactive stack surgery
+ *   (split/fold/squash/reorder). Reparenting via `gt move` IS exposed
+ *   (graphite_move) because it is non-interactive with explicit
+ *   --source/--onto. Use the gt CLI or another tool for the rest.
  */
 export default function (pi: ExtensionAPI) {
   registerStatus(pi);
@@ -49,6 +53,7 @@ export default function (pi: ExtensionAPI) {
   registerSync(pi);
   registerGet(pi);
   registerNavigate(pi);
+  registerMove(pi);
   registerChange(pi);
   registerSubmit(pi);
   registerRecover(pi);

package/src/tools/move.ts

@@ -0,0 +1,155 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { assertSafeRef, flagEq, shellJoin } from "../lib/argv";
+import {
+  ensureAllSuccess,
+  ensureSuccess,
+  renderText,
+} from "../lib/result";
+import {
+  CwdParam,
+  Type,
+  requireConfirm,
+  type ToolReturn,
+} from "../lib/schema";
+
+/**
+ * graphite_move — `gt move --source <branch> --onto <parent>`.
+ *
+ * Reparent an existing, already-tracked branch onto a new parent and restack
+ * the moved branch plus all of its descendants. This is the safe stack-surgery
+ * primitive that was previously missing: track_branch --force only rewrites
+ * tracking metadata, it does NOT rebase commits, so it leaves the stack in an
+ * inconsistent shape. graphite_move performs a real rebase.
+ *
+ * Wrapper guarantees:
+ *   1. Dry-run plan first (apply defaults to false; no mutation).
+ *   2. Both `branch` and `parent` are explicit and required.
+ *   3. Ambiguous / nonsensical moves are rejected up front (empty refs,
+ *      flag-injection, branch == parent). gt rejects cycles itself.
+ *   4. On apply, gt rebases the moved branch and all descendants.
+ *   5. Conflicts surface as a failure with a conflictHalted hint, routing the
+ *      agent to graphite_recover continue/abort.
+ *   6. apply:true requires confirmDestructive:true.
+ *   7. On a successful apply, the resulting stack is shown (gt log --stack +
+ *      gt info) so the new shape is visible without a second call.
+ */
+export function registerMove(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_move",
+    label: "Graphite: move (reparent)",
+    description:
+      "Reparent an already-tracked branch onto a new parent and rebase it plus all descendants via `gt move --source <branch> --onto <parent>`. Defaults to a dry-run plan; pass apply:true with confirmDestructive:true to actually rebase. Unlike track_branch --force, this rewrites commits, not just tracking metadata.",
+    promptSnippet:
+      "graphite_move: reparent a tracked branch onto a new parent (`gt move --source --onto`)",
+    promptGuidelines: [
+      "Use graphite_move to reparent an existing tracked branch onto a different parent. It rebases the moved branch and all its descendants. Do NOT use graphite_setup track_branch --force for this — that only rewrites tracking metadata and leaves commits unrebased.",
+      "Always call graphite_move with apply:false (default) first to review the dry-run plan, then call again with apply:true and confirmDestructive:true to actually rebase.",
+      "Pass explicit branch and explicit parent. The wrapper never picks them interactively.",
+      "If the move halts on a conflict, follow the hint and use graphite_recover action=continue (or abort).",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      branch: Type.String({
+        description: "The already-tracked branch to reparent (gt move --source).",
+      }),
+      parent: Type.String({
+        description: "The new parent branch to move `branch` onto (gt move --onto).",
+      }),
+      apply: Type.Optional(
+        Type.Boolean({
+          description:
+            "false => dry-run plan only, no mutation (default). true => actually rebase (requires confirmDestructive).",
+        }),
+      ),
+      confirmDestructive: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      const branch = assertSafeRef(p.branch, "branch");
+      const parent = assertSafeRef(p.parent, "parent");
+      if (branch === parent) {
+        throw new Error(
+          `graphite_move: branch and parent are the same (${JSON.stringify(branch)}). ` +
+            `A branch cannot be its own parent.`,
+        );
+      }
+
+      const apply = p.apply === true;
+
+      // --- dry-run: show current stack + the planned operation, no mutation.
+      if (!apply) {
+        const log = await runGt(["log", "--stack"], { cwd: p.cwd, signal });
+        const [fl] = await ensureAllSuccess(
+          [{ label: "gt log --stack", result: log, requireStdout: true }],
+          p.cwd,
+        );
+        const planned = `gt ${shellJoin([
+          "move",
+          flagEq("--source", branch),
+          flagEq("--onto", parent),
+        ])}`;
+        const plan = [
+          `[graphite_move] dry-run (no changes made)`,
+          ``,
+          `Planned: reparent ${branch} onto ${parent}.`,
+          `This will rebase ${branch} and ALL of its descendants onto ${parent}.`,
+          `Command that would run: ${planned}`,
+          ``,
+          `To apply: call graphite_move again with apply:true and confirmDestructive:true.`,
+          `If it halts on a conflict, resolve files then graphite_recover action="continue".`,
+          ``,
+          `--- current stack ---`,
+          renderText("gt log --stack", fl),
+        ].join("\n");
+        return {
+          content: [{ type: "text", text: plan }],
+          details: { apply: false, branch, parent, log: fl },
+        };
+      }
+
+      // --- apply: real rebase. Destructive, so require confirmation.
+      requireConfirm(
+        p.confirmDestructive,
+        `gt move --source ${branch} --onto ${parent} (rebases the branch and its descendants)`,
+      );
+
+      const args = [
+        "move",
+        flagEq("--source", branch),
+        flagEq("--onto", parent),
+      ];
+      const label = `gt ${shellJoin(args)}`;
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = await ensureSuccess(label, r, p.cwd, { mutating: true });
+
+      // Requirement 7: show the resulting stack after a successful move.
+      const [log, info] = await Promise.all([
+        runGt(["log", "--stack"], { cwd: p.cwd, signal }),
+        runGt(["info"], { cwd: p.cwd, signal }),
+      ]);
+      const [fl, fi] = await ensureAllSuccess(
+        [
+          { label: "gt log --stack", result: log, requireStdout: true },
+          { label: "gt info", result: info, requireStdout: true },
+        ],
+        p.cwd,
+      );
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              renderText(label, f),
+              ``,
+              `--- stack after move ---`,
+              renderText("gt log --stack", fl),
+              renderText("gt info", fi),
+            ].join("\n"),
+          },
+        ],
+        details: { apply: true, branch, parent, result: f, log: fl, info: fi },
+      };
+    },
+  });
+}