pi-graphite 0.2.2 → 0.3.0

package/src/lib/exec.ts

@@ -5,8 +5,10 @@ import { resolve as resolvePath } from "node:path";
 export interface GtRunOptions {
   cwd: string;
   signal?: AbortSignal;
-  /** Extra env vars merged into process.env */
+  /** Extra env vars merged into process.env. Safety vars always win. */
   env?: Record<string, string>;
+  /** Hard timeout in ms. Default 120s. */
+  timeoutMs?: number;
 }
 
 export interface GtRunResult {
@@ -23,6 +25,47 @@ export interface GtRunResult {
 const ANSI = /\x1b\[[0-9;]*[a-zA-Z]/g;
 const MAX_BYTES = 50 * 1024;
 const MAX_LINES = 2000;
+export const DEFAULT_COMMAND_TIMEOUT_MS = 120_000;
+
+/** Env guardrails: disable editors, pagers, browsers. Must override caller env. */
+export const SAFE_NONINTERACTIVE_ENV: Record<string, string> = {
+  GT_EDITOR: "true",
+  TEST_GT_EDITOR: "true",
+  GIT_EDITOR: "true",
+  EDITOR: "true",
+  VISUAL: "true",
+  GIT_SEQUENCE_EDITOR: "true",
+  GT_PAGER: "",
+  GIT_PAGER: "cat",
+  PAGER: "cat",
+  LESS: "FRX",
+  BROWSER: "true",
+  GH_BROWSER: "true",
+  // gt-gh treats this as "invoked from Graphite Interactive" and forces
+  // non-interactive behavior regardless of argv. Other gt builds should
+  // ignore it if unsupported; keep --no-interactive argv guards too.
+  GRAPHITE_INTERACTIVE: "1",
+};
+
+export function safeNoninteractiveEnv(extra?: Record<string, string>): NodeJS.ProcessEnv {
+  return {
+    ...process.env,
+    ...(extra ?? {}),
+    ...SAFE_NONINTERACTIVE_ENV,
+  };
+}
+
+export function killProcessGroup(child: { pid?: number; kill(signal?: NodeJS.Signals): boolean }, signal: NodeJS.Signals): void {
+  try {
+    if (child.pid && process.platform !== "win32") {
+      process.kill(-child.pid, signal);
+      return;
+    }
+  } catch {}
+  try {
+    child.kill(signal);
+  } catch {}
+}
 
 export function stripAnsi(s: string): string {
   return s.replace(ANSI, "");
@@ -47,12 +90,27 @@ export function truncateOutput(s: string): string {
   return `${kept}\n... [truncated: ${s.length - MAX_BYTES} more bytes]`;
 }
 
+/**
+ * Tokens that re-enable interactive flows in gt and must never appear in
+ * rawArgs. Tool authors should not pass these directly, and user-supplied
+ * strings should be routed through argv helpers (assertSafeRef / flagEq)
+ * so values starting with `-` can never reach this list. We still scan
+ * defensively here as belt-and-braces.
+ */
+const FORBIDDEN_RAW_TOKENS = new Set<string>([
+  "--interactive",
+  "--interactive-rebase",
+]);
+
 /**
  * Run `gt` with structured args. Never builds a shell string.
  *
- * - Always injects --cwd <abs>.
- * - Always injects --no-interactive. No escape hatch by design: agent-driven
- *   tools must never block on a TTY prompt.
+ * - Always injects --cwd <abs> and --no-interactive at the *start*.
+ * - Also appends a trailing --no-interactive after rawArgs as defense in
+ *   depth: yargs lets a later `--interactive` override an earlier
+ *   `--no-interactive`, so we ensure --no-interactive is always the last
+ *   word on the global option.
+ * - Refuses to run if rawArgs contains a known interactive-toggle token.
  * - Does not inject --quiet (we want stderr diagnostics).
  */
 export async function runGt(
@@ -60,16 +118,32 @@ export async function runGt(
   opts: GtRunOptions,
 ): Promise<GtRunResult> {
   const cwd = resolvePath(opts.cwd);
+  for (const tok of rawArgs) {
+    // Match both `--interactive` and `--interactive=...` forms.
+    const head = tok.split("=", 1)[0];
+    if (FORBIDDEN_RAW_TOKENS.has(head)) {
+      throw new Error(
+        `runGt: refused to pass forbidden token ${JSON.stringify(tok)} to gt. ` +
+          `Interactive flows are disabled in this extension.`,
+      );
+    }
+  }
   const args = ["--cwd", cwd, "--no-interactive"];
   args.push(...rawArgs);
+  // Trailing --no-interactive wins against any later `--interactive` that
+  // might still slip in via an unaudited code path.
+  args.push("--no-interactive");
 
   return new Promise<GtRunResult>((resolve) => {
     let child: ChildProcessByStdio<null, Readable, Readable>;
     try {
       child = spawn("gt", args, {
         cwd,
-        env: { ...process.env, ...(opts.env ?? {}) },
+        // Force any editor/pager/browser invocation to no-op instead of
+        // hanging. Safety vars override opts.env by design.
+        env: safeNoninteractiveEnv(opts.env),
         stdio: ["ignore", "pipe", "pipe"],
+        detached: process.platform !== "win32",
       });
     } catch (e) {
       resolve({
@@ -88,6 +162,16 @@ export async function runGt(
     let stdout = "";
     let stderr = "";
     let killed = false;
+    let settled = false;
+
+    const killChild = () => {
+      killed = true;
+      killProcessGroup(child, "SIGTERM");
+      setTimeout(() => killProcessGroup(child, "SIGKILL"), 1500).unref?.();
+    };
+
+    const timeout = setTimeout(killChild, opts.timeoutMs ?? DEFAULT_COMMAND_TIMEOUT_MS);
+    timeout.unref?.();
 
     child.stdout?.on("data", (d) => {
       stdout += d.toString();
@@ -98,20 +182,14 @@ export async function runGt(
       if (stderr.length > MAX_BYTES * 4) stderr = stderr.slice(-MAX_BYTES * 2);
     });
 
-    const onAbort = () => {
-      killed = true;
-      try {
-        child.kill("SIGTERM");
-        setTimeout(() => {
-          try {
-            child.kill("SIGKILL");
-          } catch {}
-        }, 1500).unref?.();
-      } catch {}
-    };
+    const onAbort = killChild;
     opts.signal?.addEventListener("abort", onAbort, { once: true });
 
     child.on("error", (err) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
+      opts.signal?.removeEventListener("abort", onAbort);
       resolve({
         command: "gt",
         args,
@@ -119,12 +197,15 @@ export async function runGt(
         exitCode: -1,
         stdout: sanitizeBranding(stripAnsi(stdout)),
         stderr: sanitizeBranding(stripAnsi(stderr)),
-        timedOut: false,
+        timedOut: killed,
         spawnError: err.message,
       });
     });
 
     child.on("close", (code) => {
+      if (settled) return;
+      settled = true;
+      clearTimeout(timeout);
       opts.signal?.removeEventListener("abort", onAbort);
       resolve({
         command: "gt",

package/src/lib/result.ts

@@ -1,5 +1,5 @@
 import { spawn } from "node:child_process";
-import type { GtRunResult } from "./exec";
+import { DEFAULT_COMMAND_TIMEOUT_MS, killProcessGroup, safeNoninteractiveEnv, type GtRunResult } from "./exec";
 
 /**
  * Structured failure hints. Only populated when the underlying `gt` command
@@ -140,17 +140,33 @@ function execText(cmd: string, args: string[], cwd: string): Promise<string> {
     let out = "";
     let child;
     try {
-      child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "ignore"] });
+      child = spawn(cmd, args, {
+        cwd,
+        env: safeNoninteractiveEnv(),
+        stdio: ["ignore", "pipe", "ignore"],
+        detached: process.platform !== "win32",
+      });
     } catch {
       resolve("");
       return;
     }
+    const timeout = setTimeout(() => {
+      killProcessGroup(child, "SIGTERM");
+      setTimeout(() => killProcessGroup(child, "SIGKILL"), 1500).unref?.();
+    }, DEFAULT_COMMAND_TIMEOUT_MS);
+    timeout.unref?.();
     child.stdout.on("data", (d) => {
       out += d.toString();
       if (out.length > 4096) out = out.slice(-4096);
     });
-    child.on("error", () => resolve(""));
-    child.on("close", () => resolve(out));
+    child.on("error", () => {
+      clearTimeout(timeout);
+      resolve("");
+    });
+    child.on("close", () => {
+      clearTimeout(timeout);
+      resolve(out);
+    });
   });
 }
 
@@ -188,28 +204,28 @@ export async function enrichFailure(cwd: string, f: FormattedResult): Promise<vo
     const b = branch ?? "<current-branch>";
     const p = trunk ?? "<trunk>";
     parts.push(
-      `Current branch (${b}) is not tracked by Graphite. To track it, call: ` +
-        `graphite_branch_tracking({ action: "track", branch: "${b}", parent: "${p}" }). ` +
-        `Verify parent is correct before applying.`,
+      `Current branch (${b}) is not tracked by Graphite. To track it after verifying the intended parent, call: ` +
+        `graphite_setup({ action: "track_branch", branch: "${b}", parent: "${p}", confirmParent: true }). ` +
+        `Do not guess the parent if unclear; ask the user first.`,
     );
   }
   if (f.hints.notInitialized) {
     parts.push(
-      `Graphite not initialized in this repo. Call: graphite_repo({ action: "init", trunk: "<trunk-branch>" }).`,
+      `Graphite not initialized in this repo. Call: graphite_setup({ action: "init_repo", trunk: "<trunk-branch>" }).`,
     );
   }
   if (f.hints.conflictHalted) {
     parts.push(
       `A Graphite command is halted by a conflict. After resolving in git, call: ` +
-        `graphite_recovery({ action: "continue" }) (or "abort").`,
+        `graphite_recover({ action: "continue" }) (or "abort").`,
     );
   }
   if (f.hints.restackNeeded) {
-    parts.push(`Stack is out of date. Call: graphite_stack_restack().`);
+    parts.push(`Stack is out of date. Call: graphite_sync() to sync and restack.`);
   }
   if (f.hints.trunkOutOfSync) {
     parts.push(
-      `Trunk is out of sync with remote. Call: graphite_remote_sync({ action: "sync" }) first.`,
+      `Trunk is out of sync with remote. Call: graphite_sync() first.`,
     );
   }
   if (f.hints.notAuthenticated) {
@@ -221,7 +237,7 @@ export async function enrichFailure(cwd: string, f: FormattedResult): Promise<vo
     const b = f.hints.checkedOutElsewhere.branch ?? "<branch>";
     parts.push(
       `Branch ${b} is checked out in another worktree. Switch to that worktree, or use ` +
-        `\`graphite_branch_create({ onto: "${b}", ... })\` to stack a new branch on top.`,
+        `switch to a different branch with graphite_navigate before mutating the stack.`,
     );
   }
   if (f.hints.invalidArgument) {
@@ -231,7 +247,7 @@ export async function enrichFailure(cwd: string, f: FormattedResult): Promise<vo
   }
   if (f.hints.operatingOnTrunk) {
     parts.push(
-      `Operation refused on the trunk branch. Check out a non-trunk branch first (graphite_branch_navigate).`,
+      `Operation refused on the trunk branch. Check out a non-trunk branch first with graphite_navigate.`,
     );
   }
 

package/src/lib/schema.ts

@@ -9,10 +9,11 @@ export const StageMode = StringEnum([
   "none",
   "all",
   "update",
-  "patch",
 ] as const);
 
-export function stageArgs(mode: "none" | "all" | "update" | "patch"): string[] {
+export type StageModeValue = "none" | "all" | "update";
+
+export function stageArgs(mode: StageModeValue): string[] {
   switch (mode) {
     case "none":
       return [];
@@ -20,9 +21,9 @@ export function stageArgs(mode: "none" | "all" | "update" | "patch"): string[] {
       return ["--all"];
     case "update":
       return ["--update"];
-    case "patch":
-      return ["--patch"];
   }
+  const _exhaustive: never = mode;
+  return _exhaustive;
 }
 
 /** Common cwd param. Required so we always pass an absolute path to gt. */

package/src/tools/change.ts

@@ -0,0 +1,140 @@
+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,
+  type ToolReturn,
+} from "../lib/schema";
+
+/**
+ * graphite_change — the only blessed branch-mutation path.
+ *
+ *   action=create        gt create -am "<message>"   (new branch on top of current)
+ *   action=amend         gt modify -am "<message>"   (amend current branch's commit)
+ *   action=amend_into    gt modify --into <branch> -am "<message>"
+ *   action=absorb        gt absorb (dry-run by default)
+ *
+ * Always stages all changes (matches the golden-path `-am`). No editor, no
+ * patch/hunk picker, no AI metadata.
+ */
+export function registerChange(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_change",
+    label: "Graphite: change",
+    description:
+      "Create or amend a branch commit in the Graphite stack. action=create stacks a new branch on top of the current one. action=amend updates the current branch's commit. action=amend_into pushes staged hunks into a downstack branch. action=absorb auto-routes staged hunks to the correct commits (dry-run by default).",
+    promptSnippet:
+      "graphite_change: create | amend | amend_into | absorb — the only branch mutation tool",
+    promptGuidelines: [
+      "Use graphite_change action=create to start a new PR branch on top of the current branch. Always provide `message`.",
+      "Use graphite_change action=amend to update the current PR's commit. Always provide `message`.",
+      "Run graphite_status first to confirm you are on the intended branch.",
+      "graphite_change always stages all changes (matches `gt create -am` / `gt modify -am`). Stage selectively with `git add -p` outside this tool if you need a partial commit, then call graphite_change.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum([
+        "create",
+        "amend",
+        "amend_into",
+        "absorb",
+      ] as const),
+      message: Type.Optional(
+        Type.String({
+          description:
+            "Commit message. Required for create/amend/amend_into.",
+        }),
+      ),
+      name: Type.Optional(
+        Type.String({
+          description: "action=create: branch name (default generated from message).",
+        }),
+      ),
+      insert: Type.Optional(
+        Type.Boolean({
+          description:
+            "action=create: insert between current branch and its child, rebasing children (--insert).",
+        }),
+      ),
+      includeUntracked: Type.Optional(
+        Type.Boolean({
+          description:
+            "action=create|amend|amend_into: include untracked files (--update). Default false; staged + tracked-modified are always included via --all.",
+        }),
+      ),
+      into: Type.Optional(
+        Type.String({
+          description: "action=amend_into: target downstack branch to amend into.",
+        }),
+      ),
+      apply: Type.Optional(
+        Type.Boolean({
+          description:
+            "action=absorb: false (default) => --dry-run; true => --force (apply).",
+        }),
+      ),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
+      switch (p.action) {
+        case "create": {
+          if (!p.message) {
+            throw new Error("graphite_change action=create requires `message`.");
+          }
+          args = ["create"];
+          if (p.name) args.push(assertSafeRef(p.name, "name"));
+          args.push(flagEq("--message", p.message));
+          // `-am` semantics: always stage tracked modifications.
+          args.push("--all");
+          if (p.includeUntracked) args.push("--update");
+          if (p.insert) args.push("--insert");
+          args.push("--no-ai");
+          break;
+        }
+        case "amend": {
+          if (!p.message) {
+            throw new Error("graphite_change action=amend requires `message`.");
+          }
+          args = ["modify", "--all"];
+          if (p.includeUntracked) args.push("--update");
+          args.push(flagEq("--message", p.message));
+          break;
+        }
+        case "amend_into": {
+          if (!p.into) {
+            throw new Error("graphite_change action=amend_into requires `into`.");
+          }
+          if (!p.message) {
+            throw new Error(
+              "graphite_change action=amend_into requires `message`.",
+            );
+          }
+          args = ["modify", "--all"];
+          if (p.includeUntracked) args.push("--update");
+          args.push(flagEq("--into", assertSafeRef(p.into, "into")));
+          args.push(flagEq("--message", p.message));
+          break;
+        }
+        case "absorb": {
+          const apply = p.apply === true;
+          args = ["absorb"];
+          if (!apply) args.push("--dry-run");
+          else args.push("--force");
+          // Match `-am` style: include tracked modifications for absorb too.
+          args.push("--all");
+          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/navigate.ts

@@ -0,0 +1,99 @@
+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,
+  type ToolReturn,
+} from "../lib/schema";
+
+/**
+ * graphite_navigate — move around the current stack.
+ *
+ * Stacked PRs encode "which branch you are on = which PR you will modify",
+ * so navigation is a core part of the workflow. Use this before
+ * graphite_change to make sure you are on the right branch:
+ *   - to update an existing PR, checkout that PR's branch
+ *   - to add a child PR, navigate to its intended parent first
+ *   - to add a base PR, navigate to trunk
+ */
+export function registerNavigate(pi: ExtensionAPI) {
+  pi.registerTool({
+    name: "graphite_navigate",
+    label: "Graphite: navigate",
+    description:
+      "Move around the current Graphite stack: checkout a specific branch, jump to trunk, or step up/down/top/bottom. Use this before graphite_change so you are mutating the right PR.",
+    promptSnippet:
+      "graphite_navigate: checkout / trunk / up / down / top / bottom in the current stack",
+    promptGuidelines: [
+      "Before any graphite_change, confirm you are on the intended branch via graphite_status or graphite_navigate.",
+      "To create a child PR, navigate to its intended parent first. To create a base PR, navigate to trunk.",
+    ],
+    parameters: Type.Object({
+      cwd: CwdParam,
+      action: StringEnum([
+        "checkout",
+        "trunk",
+        "up",
+        "down",
+        "top",
+        "bottom",
+      ] as const),
+      branch: Type.Optional(
+        Type.String({ description: "action=checkout: branch to checkout." }),
+      ),
+      steps: Type.Optional(
+        Type.Integer({
+          minimum: 1,
+          description: "action=up|down: step count.",
+        }),
+      ),
+      to: Type.Optional(
+        Type.String({
+          description:
+            "action=up: target descendant when the current branch has multiple children (--to).",
+        }),
+      ),
+    }),
+    async execute(_id, p, signal): Promise<ToolReturn> {
+      let args: string[];
+      switch (p.action) {
+        case "checkout":
+          if (!p.branch) {
+            throw new Error(
+              "action=checkout requires `branch` (interactive selector disabled). Use action=trunk to jump to trunk.",
+            );
+          }
+          args = ["checkout", assertSafeRef(p.branch, "branch")];
+          break;
+        case "trunk":
+          args = ["checkout", "--trunk"];
+          break;
+        case "up":
+          args = ["up"];
+          if (p.steps != null) args.push(flagEq("--steps", p.steps));
+          if (p.to) args.push(flagEq("--to", assertSafeRef(p.to, "to")));
+          break;
+        case "down":
+          args = ["down"];
+          if (p.steps != null) args.push(flagEq("--steps", p.steps));
+          break;
+        case "top":
+          args = ["top"];
+          break;
+        case "bottom":
+          args = ["bottom"];
+          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 },
+      };
+    },
+  });
+}