pi-graphite 0.2.2 → 0.3.0

package/src/tools/recover.ts

@@ -0,0 +1,147 @@
+import { spawn, type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import {
+  DEFAULT_COMMAND_TIMEOUT_MS,
+  killProcessGroup,
+  runGt,
+  safeNoninteractiveEnv,
+} from "../lib/exec";
+import { ensureSuccess, renderText } from "../lib/result";
+import { CwdParam, StringEnum, Type, type ToolReturn } from "../lib/schema";
+
+function runGit(
+  args: string[],
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<{ exitCode: number; stdout: string; stderr: string }> {
+  return new Promise((resolve) => {
+    let out = "";
+    let err = "";
+    let child: ChildProcessByStdio<null, Readable, Readable>;
+    try {
+      child = spawn("git", args, {
+        cwd,
+        env: safeNoninteractiveEnv(),
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+      });
+    } catch (e) {
+      resolve({ exitCode: -1, stdout: "", stderr: (e as Error).message });
+      return;
+    }
+    child.stdout.on("data", (d) => (out += d.toString()));
+    child.stderr.on("data", (d) => (err += d.toString()));
+    let killed = false;
+    const killChild = () => {
+      killed = true;
+      killProcessGroup(child, "SIGTERM");
+      setTimeout(() => killProcessGroup(child, "SIGKILL"), 1500).unref?.();
+    };
+    const timeout = setTimeout(killChild, DEFAULT_COMMAND_TIMEOUT_MS);
+    timeout.unref?.();
+    const onAbort = killChild;
+    signal?.addEventListener("abort", onAbort, { once: true });
+    child.on("error", (e) => {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+      resolve({ exitCode: -1, stdout: out, stderr: err + e.message });
+    });
+    child.on("close", (code) => {
+      clearTimeout(timeout);
+      signal?.removeEventListener("abort", onAbort);
+      resolve({
+        exitCode: killed ? -1 : (code ?? -1),
+        stdout: out,
+        stderr: err,
+      });
+    });
+  });
+}
+
+async function findUnresolvedConflictMarkers(
+  cwd: string,
+  signal?: AbortSignal,
+): Promise<string[]> {
+  const r = await runGit(["grep", "-l", "-E", "^<{7} "], cwd, signal);
+  if (r.exitCode > 1) return [];
+  return r.stdout.split("\n").map((s) => s.trim()).filter(Boolean);
+}
+
+/**
+ * graphite_recover — `gt continue` / `gt abort` / `gt undo`.
+ *
+ * After a conflict during sync/restack/create/modify, resolve the files
+ * (and `git add` them), then call action=continue. Never use
+ * `git rebase --continue` — Graphite needs to propagate the resolution to
+ * dependent branches.
+ */
+export function registerRecover(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_recover",
+    label: "Graphite: recover",
+    description:
+      "Recover from a halted Graphite operation or a recent mistake: continue (resume a paused gt command after resolving conflicts), abort (cancel the in-flight operation), or undo (revert the most recent gt mutation in this worktree). Always prefer this over `git rebase --continue`.",
+    promptSnippet:
+      "graphite_recover: continue / abort / undo — never use `git rebase --continue`",
+    promptGuidelines: [
+      "After resolving a rebase or cherry-pick conflict from a gt command, call graphite_recover action=continue (not `git rebase --continue`) so Graphite propagates the fix to dependent branches.",
+      "graphite_recover action=undo only undoes commands run from the current worktree.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum(["continue", "abort", "undo"] as const),
+      stageAll: Type.Optional(
+        Type.Boolean({
+          description: "action=continue: stage all changes first (--all).",
+        }),
+      ),
+      allowConflictMarkers: Type.Optional(
+        Type.Boolean({
+          description:
+            "action=continue: bypass the pre-flight check that refuses to continue when tracked files still contain `<<<<<<<` markers. Default false.",
+        }),
+      ),
+      force: Type.Optional(
+        Type.Boolean({
+          description: "action=abort|undo: skip confirmation (--force).",
+        }),
+      ),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
+      switch (p.action) {
+        case "continue": {
+          if (!p.allowConflictMarkers) {
+            const dirty = await findUnresolvedConflictMarkers(p.cwd, signal);
+            if (dirty.length) {
+              throw new Error(
+                `graphite_recover: refusing to continue — ${dirty.length} tracked file(s) still contain conflict markers (\`<<<<<<<\`):\n` +
+                  dirty.map((f) => `  - ${f}`).join("\n") +
+                  `\n\nResolve each file, then re-run. If markers are intentional, pass allowConflictMarkers:true.`,
+              );
+            }
+          }
+          args = ["continue"];
+          if (p.stageAll) args.push("--all");
+          break;
+        }
+        case "abort":
+          args = ["abort"];
+          if (p.force) args.push("--force");
+          break;
+        case "undo":
+          args = ["undo"];
+          if (p.force) args.push("--force");
+          break;
+      }
+      const label = `gt ${args.join(" ")}`;
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = await ensureSuccess(label, r, p.cwd);
+      return {
+        content: [{ type: "text", text: renderText(label, f) }],
+        details: { action: p.action, result: f },
+      };
+    },
+  });
+}

package/src/tools/setup.ts

@@ -0,0 +1,121 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { assertSafeRef, flagEq } from "../lib/argv";
+import { ensureSuccess, renderText } from "../lib/result";
+import {
+  CwdParam,
+  StringEnum,
+  Type,
+  requireConfirm,
+  type ToolReturn,
+} from "../lib/schema";
+
+/**
+ * graphite_setup — initialize a repo or adopt an existing git branch into
+ * Graphite tracking.
+ *
+ * This is a precondition tool, not a daily workflow tool. Use it only when
+ * graphite_status / graphite_change reports that Graphite is not initialized
+ * or the current branch is not tracked.
+ */
+export function registerSetup(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_setup",
+    label: "Graphite: setup",
+    description:
+      "Initialize Graphite in a repo or track an existing Git branch with an explicit Graphite parent. Use only when a repo/branch is not Graphite-ready. Tracking requires an explicit branch, explicit parent, and confirmParent:true.",
+    promptSnippet:
+      "graphite_setup: init_repo | track_branch for Graphite preconditions",
+    promptGuidelines: [
+      "Use graphite_setup only when graphite_status or another tool reports notInitialized or branchNotTracked.",
+      "For track_branch, never infer the parent silently. Ask the user if the intended parent is unclear, then pass confirmParent:true.",
+      "Do not use graphite_setup for untrack/freeze/unfreeze; those are outside the core workflow.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum(["init_repo", "track_branch"] as const),
+      trunk: Type.Optional(
+        Type.String({
+          description: "action=init_repo: trunk branch name (for example main or master).",
+        }),
+      ),
+      reset: Type.Optional(
+        Type.Boolean({
+          description:
+            "action=init_repo: pass --reset and untrack existing Graphite branches. Requires confirmDestructive:true.",
+        }),
+      ),
+      branch: Type.Optional(
+        Type.String({ description: "action=track_branch: existing Git branch to track." }),
+      ),
+      parent: Type.Optional(
+        Type.String({
+          description:
+            "action=track_branch: explicit Graphite parent branch. Required; do not guess if unclear.",
+        }),
+      ),
+      confirmParent: Type.Optional(
+        Type.Boolean({
+          description:
+            "action=track_branch: required true to confirm the supplied parent is intentional.",
+        }),
+      ),
+      force: Type.Optional(
+        Type.Boolean({
+          description:
+            "action=track_branch: pass --force to overwrite existing tracking metadata. Requires confirmDestructive:true.",
+        }),
+      ),
+      confirmDestructive: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
+
+      if (p.action === "init_repo") {
+        if (!p.trunk) {
+          throw new Error("graphite_setup action=init_repo requires `trunk`.");
+        }
+        if (p.reset) {
+          requireConfirm(
+            p.confirmDestructive,
+            "gt init --reset (untracks existing Graphite branches)",
+          );
+        }
+        args = ["init", flagEq("--trunk", assertSafeRef(p.trunk, "trunk"))];
+        if (p.reset) args.push("--reset");
+      } else {
+        if (!p.branch) {
+          throw new Error("graphite_setup action=track_branch requires `branch`.");
+        }
+        if (!p.parent) {
+          throw new Error("graphite_setup action=track_branch requires `parent`.");
+        }
+        if (p.confirmParent !== true) {
+          throw new Error(
+            "graphite_setup action=track_branch requires confirmParent:true. Confirm the intended Graphite parent with the user if unclear.",
+          );
+        }
+        if (p.force) {
+          requireConfirm(
+            p.confirmDestructive,
+            "gt track --force (overwrites existing tracking metadata)",
+          );
+        }
+        args = [
+          "track",
+          assertSafeRef(p.branch, "branch"),
+          flagEq("--parent", assertSafeRef(p.parent, "parent")),
+        ];
+        if (p.force) args.push("--force");
+      }
+
+      const label = `gt ${args.join(" ")}`;
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = await ensureSuccess(label, r, p.cwd);
+      return {
+        content: [{ type: "text", text: renderText(label, f) }],
+        details: { action: p.action, result: f },
+      };
+    },
+  });
+}

package/src/tools/status.ts

@@ -0,0 +1,55 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { ensureAllSuccess, renderText } from "../lib/result";
+import { CwdParam, Type, type ToolReturn } from "../lib/schema";
+
+/**
+ * graphite_status — single read-only entry point.
+ *
+ * Always returns:
+ *   gt log --stack    -> current stack tree
+ *   gt info           -> current branch summary (parent, PR url, restack hint)
+ *
+ * Run this before touching the stack.
+ */
+export function registerStatus(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_status",
+    label: "Graphite: status",
+    description:
+      "Read-only Graphite snapshot. Runs `gt log --stack` and `gt info` so you can see the current stack, the current branch's parent + PR, and any restack/conflict hints. Use this before any other graphite_* tool.",
+    promptSnippet:
+      "graphite_status: inspect current stack + current branch before mutating",
+    promptGuidelines: [
+      "Run graphite_status at the start of any Graphite workflow, and again whenever you are unsure where you are in the stack.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      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 },
+          { label: "gt info", result: info },
+        ],
+        p.cwd,
+      );
+      return {
+        content: [
+          {
+            type: "text",
+            text: [
+              renderText("gt log --stack", fl),
+              renderText("gt info", fi),
+            ].join("\n\n"),
+          },
+        ],
+        details: { log: fl, info: fi },
+      };
+    },
+  });
+}

package/src/tools/submit.ts

@@ -0,0 +1,127 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { assertSafeRef, flagEq } from "../lib/argv";
+import { ensureSuccess, renderText } from "../lib/result";
+import {
+  CwdParam,
+  Type,
+  requireConfirm,
+  type ToolReturn,
+} from "../lib/schema";
+
+/**
+ * graphite_submit_stack — the only blessed submit path.
+ *
+ * Wraps `gt submit --stack --no-edit --no-ai`. Defaults to --dry-run so the
+ * caller can review the plan. Actually pushing requires `apply:true` AND
+ * `confirmRemote:true`.
+ *
+ * No PR title/body fields, no editor, no browser, no gh, no
+ * current-branch-only submit. The skill calls out that the correct workflow
+ * is always to submit the entire stack.
+ */
+export function registerSubmitStack(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_submit_stack",
+    label: "Graphite: submit stack",
+    description:
+      "Push the entire current stack and create/update PRs via `gt submit --stack --no-edit`. Defaults to a dry-run plan; pass apply:true with confirmRemote:true to actually push. PR title/body editing is intentionally not exposed.",
+    promptSnippet:
+      "graphite_submit_stack: plan or apply `gt submit --stack` for the full stack",
+    promptGuidelines: [
+      "Always call graphite_submit_stack with apply:false (default) first to review the dry-run plan, then call again with apply:true and confirmRemote:true to actually push.",
+      "This extension does not edit PR titles/bodies. If you need to set them, do it outside this extension after the push.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      apply: Type.Optional(
+        Type.Boolean({
+          description:
+            "false => --dry-run (default). true => actually push (requires confirmRemote).",
+        }),
+      ),
+      confirmRemote: Type.Optional(Type.Boolean()),
+      draft: Type.Optional(
+        Type.Boolean({ description: "Create new PRs as drafts (--draft)." }),
+      ),
+      publish: Type.Optional(
+        Type.Boolean({ description: "Take PRs out of draft (--publish)." }),
+      ),
+      updateOnly: Type.Optional(
+        Type.Boolean({
+          description: "Only update existing PRs, do not create new ones (--update-only).",
+        }),
+      ),
+      mergeWhenReady: Type.Optional(
+        Type.Boolean({ description: "Enable auto-merge (--merge-when-ready)." }),
+      ),
+      rerequestReview: Type.Optional(
+        Type.Boolean({
+          description: "Re-request review from existing reviewers (--rerequest-review).",
+        }),
+      ),
+      reviewers: Type.Optional(
+        Type.Array(Type.String(), {
+          description: "User reviewers (--reviewers).",
+        }),
+      ),
+      teamReviewers: Type.Optional(
+        Type.Array(Type.String(), {
+          description: "Team reviewers (--team-reviewers).",
+        }),
+      ),
+      forcePush: Type.Optional(
+        Type.Boolean({
+          description:
+            "--force (instead of default --force-with-lease). Requires confirmRemote.",
+        }),
+      ),
+      ignoreOutOfSyncTrunk: Type.Optional(
+        Type.Boolean({
+          description: "Submit even if trunk is out of sync (--ignore-out-of-sync-trunk).",
+        }),
+      ),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      const apply = p.apply === true;
+      if (apply) {
+        requireConfirm(
+          p.confirmRemote,
+          "gt submit --stack (push branches + create/update PRs)",
+        );
+      }
+      if (p.forcePush) {
+        requireConfirm(p.confirmRemote, "gt submit --force");
+      }
+
+      const args = ["submit", "--stack"];
+      if (!apply) args.push("--dry-run");
+      args.push("--no-edit", "--no-ai");
+
+      if (p.updateOnly) args.push("--update-only");
+      if (p.draft) args.push("--draft");
+      if (p.publish) args.push("--publish");
+      if (p.mergeWhenReady) args.push("--merge-when-ready");
+      if (p.rerequestReview) args.push("--rerequest-review");
+
+      if (p.reviewers && p.reviewers.length) {
+        for (const rv of p.reviewers) assertSafeRef(rv, "reviewers[]");
+        args.push(flagEq("--reviewers", p.reviewers.join(",")));
+      }
+      if (p.teamReviewers && p.teamReviewers.length) {
+        for (const rv of p.teamReviewers) assertSafeRef(rv, "teamReviewers[]");
+        args.push(flagEq("--team-reviewers", p.teamReviewers.join(",")));
+      }
+      if (p.forcePush) args.push("--force");
+      if (p.ignoreOutOfSyncTrunk) args.push("--ignore-out-of-sync-trunk");
+
+      const label = `gt ${args.join(" ")}`;
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = await ensureSuccess(label, r, p.cwd);
+      return {
+        content: [{ type: "text", text: renderText(label, f) }],
+        details: { apply, result: f },
+      };
+    },
+  });
+}

package/src/tools/sync.ts

@@ -0,0 +1,79 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { runGt } from "../lib/exec";
+import { ensureSuccess, renderText } from "../lib/result";
+import {
+  CwdParam,
+  Type,
+  requireConfirm,
+  type ToolReturn,
+} from "../lib/schema";
+
+/**
+ * graphite_sync — the "start of day / after merge" workflow.
+ *
+ * Wraps `gt sync` only. Pulls trunk, deletes merged branches, restacks
+ * remaining branches. This is the canonical way to recover from merged PRs.
+ *
+ * Prefer this over manual restack when trunk may have moved or when PRs in
+ * the stack may have merged.
+ */
+export function registerSync(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_sync",
+    label: "Graphite: sync",
+    description:
+      "Pull trunk, delete merged branches, and restack remaining branches via `gt sync`. Run at session start and after any PR in the stack merges. Destructive flags (`force`, `deleteAll`) require `confirmDestructive`.",
+    promptSnippet:
+      "graphite_sync: `gt sync` — start-of-day + after-merge cleanup and restack",
+    promptGuidelines: [
+      "Run graphite_sync at the start of a session and any time PRs in the stack may have merged.",
+      "graphite_sync with force=true or deleteAll=true is destructive; pass confirmDestructive:true.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      restack: Type.Optional(
+        Type.Boolean({
+          description:
+            "Restack after fetching (default true; pass false for --no-restack).",
+        }),
+      ),
+      allTrunks: Type.Optional(
+        Type.Boolean({ description: "Sync all configured trunks (--all)." }),
+      ),
+      deleteAll: Type.Optional(
+        Type.Boolean({
+          description:
+            "Delete all merged/closed branches without prompting (--delete-all). Requires confirmDestructive.",
+        }),
+      ),
+      force: Type.Optional(
+        Type.Boolean({
+          description:
+            "Overwrite local branches with remote (--force). Requires confirmDestructive.",
+        }),
+      ),
+      confirmDestructive: Type.Optional(Type.Boolean()),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      if (p.force || p.deleteAll) {
+        requireConfirm(
+          p.confirmDestructive,
+          "gt sync with --force/--delete-all (may overwrite branches)",
+        );
+      }
+      const args = ["sync"];
+      if (p.allTrunks) args.push("--all");
+      if (p.deleteAll) args.push("--delete-all");
+      if (p.force) args.push("--force");
+      if (p.restack === false) args.push("--no-restack");
+
+      const label = `gt ${args.join(" ")}`;
+      const r = await runGt(args, { cwd: p.cwd, signal });
+      const f = await ensureSuccess(label, r, p.cwd);
+      return {
+        content: [{ type: "text", text: renderText(label, f) }],
+        details: { result: f },
+      };
+    },
+  });
+}