@saadjs/pi-git-status 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saad Bash
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,40 @@
+# @saadjs/pi-git-status
+
+Git status in Pi's footer, alongside other extensions' statuses.
+
+```text
+main • 3 changed • 2 untracked • +42 −17
+```
+
+Clean trees show `main • clean`. The status is hidden outside Git repositories or when Git is unavailable.
+
+## Install
+
+```bash
+pi install npm:@saadjs/pi-git-status
+```
+
+To try locally from the monorepo root:
+
+```bash
+pi -e ./extensions/git-status/index.ts
+```
+
+Use an absolute path to `index.ts` when running Pi in another repository.
+
+## Counts
+
+- **Branch:** current branch, or `detached`.
+- **Changed:** tracked files with staged or unstaged changes, counted once per file, including renames, conflicts, and submodule changes.
+- **Untracked:** individual untracked files; ignored files are excluded.
+- **+ / −:** net tracked-file line additions/deletions against `HEAD`. Untracked and binary contents are excluded.
+
+Counts cover the whole repository, even from a subdirectory. Refreshes on session start, after successful `edit`/`write` tools, and after agent completion.
+
+Custom footers must display extension statuses via `footerData.getExtensionStatuses()`.
+
+## Test
+
+```bash
+pnpm --filter @saadjs/pi-git-status test
+```

package/core.ts

@@ -0,0 +1,137 @@
+import { execFile } from "node:child_process";
+
+export interface GitStatus {
+  branch: string;
+  changed: number;
+  untracked: number;
+  added: number;
+  removed: number;
+}
+
+export interface WorkingTreeStatus {
+  branch: string;
+  unborn: boolean;
+  changed: number;
+  untracked: number;
+}
+
+/** Parse porcelain v1 -z, skipping the extra source path on rename/copy records. */
+export function parseWorkingTree(output: string): WorkingTreeStatus {
+  const records = output.split("\0");
+  const header = records.shift() ?? "";
+  const unborn = /^## (No commits yet on |Initial commit on )/.test(header);
+  const branch = header.startsWith("## HEAD (no branch)")
+    ? "detached"
+    : header
+        .replace(/^## (?:No commits yet on |Initial commit on )?/, "")
+        .split("...")[0]
+        .replace(/ \[.*\]$/, "");
+  let changed = 0;
+  let untracked = 0;
+
+  for (let i = 0; i < records.length; i++) {
+    const record = records[i];
+    if (!record) continue;
+    const status = record.slice(0, 2);
+    if (status === "??") untracked++;
+    else if (status !== "!!") changed++;
+    if (/[RC]/.test(status)) i++;
+  }
+
+  return { branch, unborn, changed, untracked };
+}
+
+/** Binary files report '-' instead of line counts; rename paths are separate NUL records. */
+export function parseNumstat(output: string): Pick<GitStatus, "added" | "removed"> {
+  const records = output.split("\0");
+  let added = 0;
+  let removed = 0;
+  for (let i = 0; i < records.length; i++) {
+    const match = /^(\d+|-)\t(\d+|-)\t([\s\S]*)$/.exec(records[i]);
+    if (!match) continue;
+    if (match[1] !== "-") added += Number(match[1]);
+    if (match[2] !== "-") removed += Number(match[2]);
+    if (match[3] === "") i += 2;
+  }
+  return { added, removed };
+}
+
+function git(cwd: string, args: string[], signal?: AbortSignal): Promise<string> {
+  return new Promise((resolve, reject) => {
+    const child = execFile(
+      "git",
+      ["-c", "color.ui=false", ...args],
+      {
+        cwd,
+        signal,
+        env: { ...process.env, GIT_OPTIONAL_LOCKS: "0" },
+        encoding: "utf8",
+        timeout: 5_000,
+        maxBuffer: 16 * 1024 * 1024,
+        windowsHide: true,
+      },
+      (error, stdout) => (error ? reject(error) : resolve(stdout)),
+    );
+    // hash-object --stdin needs EOF to hash the empty tree (including SHA-256 repos).
+    child.stdin?.end();
+  });
+}
+
+/** Net tracked-file changes against HEAD; untracked contents are deliberately excluded. */
+export async function readGitStatus(cwd: string, signal?: AbortSignal): Promise<GitStatus | null> {
+  try {
+    const status = parseWorkingTree(
+      await git(
+        cwd,
+        ["status", "--porcelain=v1", "-z", "--branch", "--untracked-files=all", "--renames"],
+        signal,
+      ),
+    );
+    // Before the first commit, compare the working tree to an empty tree instead of HEAD.
+    const base = status.unborn
+      ? (await git(cwd, ["hash-object", "-t", "tree", "--stdin"], signal)).trim()
+      : "HEAD";
+    const diff = await git(
+      cwd,
+      [
+        "diff",
+        "--numstat",
+        "-z",
+        "--no-ext-diff",
+        "--no-textconv",
+        "--no-relative",
+        "--find-renames",
+        base,
+        "--",
+      ],
+      signal,
+    );
+    return {
+      branch: status.branch,
+      changed: status.changed,
+      untracked: status.untracked,
+      ...parseNumstat(diff),
+    };
+  } catch {
+    // Not a repository, Git unavailable, timeout, or cancellation: don't leave stale counts.
+    return null;
+  }
+}
+
+type StatusColor = "text" | "accent" | "muted" | "success" | "error";
+
+export function formatGitStatus(
+  status: GitStatus,
+  color: (name: StatusColor, text: string) => string = (_name, text) => text,
+): string {
+  const separator = color("muted", " • ");
+  if (status.changed === 0 && status.untracked === 0) {
+    return color("text", status.branch) + separator + color("success", "clean");
+  }
+  return [
+    color("text", status.branch),
+    color(status.changed ? "accent" : "muted", `${status.changed} changed`),
+    color("muted", `${status.untracked} untracked`),
+    `${color(status.added ? "success" : "muted", `+${status.added}`)} ${color(status.removed ? "error" : "muted", `−${status.removed}`)}`,
+  ].join(separator);
+}

package/index.ts

@@ -0,0 +1,86 @@
+import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
+import { formatGitStatus, readGitStatus } from "./core.ts";
+
+const STATUS_KEY = "git-status";
+const DEBOUNCE_MS = 150;
+
+export default function (pi: ExtensionAPI) {
+  let stop: (() => void) | undefined;
+  let requestRefresh: ((ctx: ExtensionContext) => void) | undefined;
+
+  pi.on("session_start", (_event, ctx) => {
+    stop?.();
+    stop = undefined;
+    requestRefresh = undefined;
+    if (ctx.mode !== "tui" || !ctx.hasUI) return;
+
+    let context = ctx;
+    let disposed = false;
+    let busy = false;
+    let pending = false;
+    let lastText: string | undefined;
+    let debounce: ReturnType<typeof setTimeout> | undefined;
+    const controller = new AbortController();
+
+    async function refresh() {
+      if (disposed) return;
+      if (busy) {
+        pending = true;
+        return;
+      }
+      busy = true;
+      const current = context;
+      try {
+        const status = await readGitStatus(current.cwd, controller.signal);
+        if (disposed) return;
+        const text = status
+          ? formatGitStatus(status, (name, value) => current.ui.theme.fg(name, value))
+          : undefined;
+        if (text !== lastText) {
+          current.ui.setStatus(STATUS_KEY, text);
+          lastText = text;
+        }
+      } finally {
+        busy = false;
+        if (pending && !disposed) {
+          pending = false;
+          void refresh();
+        }
+      }
+    }
+
+    requestRefresh = (nextContext) => {
+      context = nextContext;
+      if (debounce) clearTimeout(debounce);
+      debounce = setTimeout(() => {
+        debounce = undefined;
+        void refresh();
+      }, DEBOUNCE_MS);
+      debounce.unref();
+    };
+
+    stop = () => {
+      if (disposed) return;
+      disposed = true;
+      if (debounce) clearTimeout(debounce);
+      controller.abort();
+      context.ui.setStatus(STATUS_KEY, undefined);
+    };
+    void refresh();
+  });
+
+  // Refresh after successful file mutations, not read-only tools or every shell call.
+  pi.on("tool_result", (event, ctx) => {
+    if (!event.isError && (event.toolName === "edit" || event.toolName === "write")) {
+      requestRefresh?.(ctx);
+    }
+  });
+  // Catch shell-made changes once the agent finishes.
+  pi.on("agent_end", (_event, ctx) => requestRefresh?.(ctx));
+
+  pi.on("session_shutdown", () => {
+    stop?.();
+    stop = undefined;
+    requestRefresh = undefined;
+  });
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@saadjs/pi-git-status",
+  "version": "0.1.0",
+  "description": "Live Git branch, changed files, and line counts in the Pi footer",
+  "keywords": [
+    "extension",
+    "footer",
+    "git",
+    "pi",
+    "pi-package",
+    "status"
+  ],
+  "license": "MIT",
+  "files": [
+    "index.ts",
+    "core.ts",
+    "README.md",
+    "LICENSE"
+  ],
+  "type": "module",
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "*"
+  },
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/*.test.ts"
+  }
+}