pi-graphite 0.0.1 → 0.1.1

package/README.md

@@ -1,3 +1,76 @@
 # pi-graphite
 
-Reserved package name for 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.
+
+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.
+
+## Requirements
+
+- `gt` CLI installed and authenticated (`gt auth`).
+- A pi runtime that loads npm or local pi packages.
+
+## Install
+
+```bash
+# global
+pi install npm:pi-graphite
+
+# project-local
+pi install -l npm:pi-graphite
+
+# from a local checkout
+pi install /path/to/pi-graphite
+# or, for one session
+pi -e /path/to/pi-graphite
+```
+
+## 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`).
+
+## Intentional non-goals (in Layer A)
+
+- No `graphite_raw` passthrough. Use bash for arbitrary `gt` flags.
+- No workflow orchestration (plan → apply across multiple commands).
+- No wrapping of `gt add/cherry-pick/rebase/reset/restore` passthroughs.
+- No wrapping of browser/help commands (`dash`, `docs`, `guide`, `changelog`,
+  `feedback`, `demo`, `completion`, `fish`).
+- `gt reorder` (editor-only) and `gt split --by-commit / --by-hunk`
+  (interactive-only) are intentionally not exposed.
+
+Layer B (workflow tools) and Layer C (raw escape hatch) are planned, not built.
+
+## License
+
+MIT

package/package.json

@@ -1,20 +1,31 @@
 {
   "name": "pi-graphite",
-  "version": "0.0.1",
-  "description": "Reserved package name for pi-graphite.",
-  "main": "index.js",
+  "version": "0.1.1",
+  "description": "Structured pi tools for the Graphite (gt) CLI.",
+  "keywords": [
+    "pi",
+    "pi-package",
+    "graphite",
+    "gt",
+    "stacked-prs"
+  ],
+  "license": "MIT",
   "files": [
-    "index.js",
+    "src",
     "README.md",
     "LICENSE"
   ],
+  "pi": {
+    "extensions": [
+      "./src/index.ts"
+    ]
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-ai": "*",
+    "@earendil-works/pi-coding-agent": "*",
+    "typebox": "*"
+  },
   "scripts": {
     "test": "node -e \"console.log('no tests')\""
-  },
-  "keywords": [
-    "pi",
-    "graphite"
-  ],
-  "author": "",
-  "license": "MIT"
+  }
 }

package/src/index.ts

@@ -0,0 +1,65 @@
+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";
+
+/**
+ * pi-graphite — Layer A (Domain Resource).
+ *
+ * Registers structured tools that wrap the Graphite (`gt`) CLI:
+ *
+ *   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
+ *
+ * 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.
+ */
+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);
+}

package/src/lib/exec.ts

@@ -0,0 +1,132 @@
+import { spawn, type ChildProcessByStdio } from "node:child_process";
+import type { Readable } from "node:stream";
+import { resolve as resolvePath } from "node:path";
+
+export interface GtRunOptions {
+  cwd: string;
+  signal?: AbortSignal;
+  /** Extra env vars merged into process.env */
+  env?: Record<string, string>;
+}
+
+export interface GtRunResult {
+  command: string;
+  args: string[];
+  cwd: string;
+  exitCode: number;
+  stdout: string;
+  stderr: string;
+  timedOut: boolean;
+  spawnError?: string;
+}
+
+const ANSI = /\x1b\[[0-9;]*[a-zA-Z]/g;
+const MAX_BYTES = 50 * 1024;
+const MAX_LINES = 2000;
+
+export function stripAnsi(s: string): string {
+  return s.replace(ANSI, "");
+}
+
+export function truncateOutput(s: string): string {
+  if (s.length <= MAX_BYTES) {
+    const lines = s.split("\n");
+    if (lines.length <= MAX_LINES) return s;
+    const kept = lines.slice(0, MAX_LINES).join("\n");
+    return `${kept}\n... [truncated: ${lines.length - MAX_LINES} more lines]`;
+  }
+  const kept = s.slice(0, MAX_BYTES);
+  return `${kept}\n... [truncated: ${s.length - MAX_BYTES} more bytes]`;
+}
+
+/**
+ * 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.
+ * - Does not inject --quiet (we want stderr diagnostics).
+ */
+export async function runGt(
+  rawArgs: string[],
+  opts: GtRunOptions,
+): Promise<GtRunResult> {
+  const cwd = resolvePath(opts.cwd);
+  const args = ["--cwd", cwd, "--no-interactive"];
+  args.push(...rawArgs);
+
+  return new Promise<GtRunResult>((resolve) => {
+    let child: ChildProcessByStdio<null, Readable, Readable>;
+    try {
+      child = spawn("gt", args, {
+        cwd,
+        env: { ...process.env, ...(opts.env ?? {}) },
+        stdio: ["ignore", "pipe", "pipe"],
+      });
+    } catch (e) {
+      resolve({
+        command: "gt",
+        args,
+        cwd,
+        exitCode: -1,
+        stdout: "",
+        stderr: "",
+        timedOut: false,
+        spawnError: (e as Error).message,
+      });
+      return;
+    }
+
+    let stdout = "";
+    let stderr = "";
+    let killed = false;
+
+    child.stdout?.on("data", (d) => {
+      stdout += d.toString();
+      if (stdout.length > MAX_BYTES * 4) stdout = stdout.slice(-MAX_BYTES * 2);
+    });
+    child.stderr?.on("data", (d) => {
+      stderr += d.toString();
+      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 {}
+    };
+    opts.signal?.addEventListener("abort", onAbort, { once: true });
+
+    child.on("error", (err) => {
+      resolve({
+        command: "gt",
+        args,
+        cwd,
+        exitCode: -1,
+        stdout: stripAnsi(stdout),
+        stderr: stripAnsi(stderr),
+        timedOut: false,
+        spawnError: err.message,
+      });
+    });
+
+    child.on("close", (code) => {
+      opts.signal?.removeEventListener("abort", onAbort);
+      resolve({
+        command: "gt",
+        args,
+        cwd,
+        exitCode: code ?? -1,
+        stdout: truncateOutput(stripAnsi(stdout)),
+        stderr: truncateOutput(stripAnsi(stderr)),
+        timedOut: killed,
+      });
+    });
+  });
+}

package/src/lib/result.ts

@@ -0,0 +1,80 @@
+import type { GtRunResult } from "./exec";
+
+export interface GtHints {
+  notInGitRepo?: boolean;
+  notInitialized?: boolean;
+  notAuthenticated?: boolean;
+  conflictHalted?: boolean;
+  checkedOutElsewhere?: { branch?: string; worktree?: string };
+  restackNeeded?: boolean;
+  trunkOutOfSync?: boolean;
+  branchNotTracked?: boolean;
+  noChangesStaged?: boolean;
+  prMissing?: boolean;
+}
+
+const PATTERNS: Array<[keyof GtHints | "checkedOutElsewhere", RegExp]> = [
+  ["notInGitRepo", /not (a|in a) git repository/i],
+  ["notInitialized", /run\s+`?gt\s+init`?|graphite (is )?not (yet )?initialized/i],
+  ["notAuthenticated", /run\s+`?gt\s+auth`?|auth token|not authenticated|unauthorized/i],
+  ["conflictHalted", /merge\s+conflict|rebase\s+conflict|halted|run\s+`?gt\s+continue`?/i],
+  ["restackNeeded", /needs?\s+to\s+be\s+restacked|run\s+`?gt\s+restack`?/i],
+  ["trunkOutOfSync", /trunk\s+is\s+out\s+of\s+sync|out\s+of\s+sync\s+trunk/i],
+  ["branchNotTracked", /not\s+tracked\s+by\s+graphite|untracked\s+branch/i],
+  ["noChangesStaged", /no\s+(staged\s+)?changes\s+to\s+(commit|amend)/i],
+  ["prMissing", /no\s+pull\s+request|pr\s+not\s+found/i],
+  ["checkedOutElsewhere", /checked\s+out\s+in\s+(another|the)\s+worktree/i],
+];
+
+export function parseHints(r: GtRunResult): GtHints {
+  const text = `${r.stdout}\n${r.stderr}`;
+  const hints: GtHints = {};
+  for (const [key, re] of PATTERNS) {
+    if (re.test(text)) {
+      if (key === "checkedOutElsewhere") {
+        const m = text.match(/branch\s+`?([^\s`'"]+)`?[^\n]*checked\s+out\s+in[^\n]*?(\S+\/[^\s)]+)?/i);
+        hints.checkedOutElsewhere = { branch: m?.[1], worktree: m?.[2] };
+      } else {
+        (hints as Record<string, unknown>)[key] = true;
+      }
+    }
+  }
+  return hints;
+}
+
+export interface FormattedResult {
+  ok: boolean;
+  result: GtRunResult;
+  hints: GtHints;
+}
+
+export function formatResult(r: GtRunResult): FormattedResult {
+  return {
+    ok: r.exitCode === 0 && !r.spawnError && !r.timedOut,
+    result: r,
+    hints: parseHints(r),
+  };
+}
+
+/** Render a formatted result into a single text block for the LLM. */
+export function renderText(label: string, f: FormattedResult): string {
+  const r = f.result;
+  const lines: string[] = [];
+  lines.push(`$ gt ${r.args.join(" ")}`);
+  lines.push(`# cwd=${r.cwd}  exit=${r.exitCode}${r.timedOut ? "  (aborted)" : ""}`);
+  if (r.spawnError) lines.push(`# spawn-error: ${r.spawnError}`);
+  if (r.stdout.trim()) {
+    lines.push("--- stdout ---");
+    lines.push(r.stdout.replace(/\s+$/, ""));
+  }
+  if (r.stderr.trim()) {
+    lines.push("--- stderr ---");
+    lines.push(r.stderr.replace(/\s+$/, ""));
+  }
+  const hintKeys = Object.keys(f.hints);
+  if (hintKeys.length) {
+    lines.push("--- hints ---");
+    lines.push(JSON.stringify(f.hints));
+  }
+  return `[${label}] ${f.ok ? "ok" : "fail"}\n${lines.join("\n")}`;
+}

package/src/lib/schema.ts

@@ -0,0 +1,50 @@
+import { Type, type Static } from "typebox";
+import { StringEnum } from "@earendil-works/pi-ai";
+
+export { Type, StringEnum };
+export type { Static };
+
+/** Stage mode shared by create / modify. */
+export const StageMode = StringEnum([
+  "none",
+  "all",
+  "update",
+  "patch",
+] as const);
+
+export function stageArgs(mode: "none" | "all" | "update" | "patch"): string[] {
+  switch (mode) {
+    case "none":
+      return [];
+    case "all":
+      return ["--all"];
+    case "update":
+      return ["--update"];
+    case "patch":
+      return ["--patch"];
+  }
+}
+
+/** Common cwd param. Required so we always pass an absolute path to gt. */
+export const CwdParam = Type.String({
+  description: "Absolute path to the repository working directory.",
+});
+
+/** Helper to require an explicit ack flag for irreversible/remote ops. */
+export function requireConfirm(
+  flag: boolean | undefined,
+  what: string,
+): void {
+  if (!flag) {
+    throw new Error(
+      `Refused: ${what} would mutate remote or destructive state. Pass the matching confirm flag (e.g. confirmRemote: true) to proceed.`,
+    );
+  }
+}
+
+/** Shape returned to the LLM by every tool. */
+export type ToolReturn = {
+  content: Array<{ type: "text"; text: string }>;
+  details: Record<string, unknown>;
+  isError?: boolean;
+};