pi-minimal-footer 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -7,6 +7,16 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.0] - 2026-10-07
+
+### Added
+
+- Show Git upstream divergence next to the branch, for example ` main ↑2 ↓1`; `↑` is local commits to push and `↓` is upstream commits to pull
+
+### Changed
+
+- Query Git divergence asynchronously and omit it safely when the repository has no upstream or Git is unavailable
+
 ## [0.4.2] - 2026-10-07
 
 ### Fixed

package/README.md

@@ -14,7 +14,7 @@ An opinionated, compact one-line footer for [Pi](https://github.com/earendil-wor
 **Left**
 
 - Working directory: `~/git/project`
-- Git branch: ` main`
+- Git branch and upstream divergence: ` main ↑2 ↓1` (`↑` to push, `↓` to pull); counts appear when an upstream is configured
 
 **Right**
 
@@ -59,7 +59,8 @@ Edit `minFooter` in Pi's agent `settings.json` (normally `~/.pi/agent/settings.j
 ```
 
 - `showSkills` shows **extension status text**, not installed skills. The footer does not add the example statuses itself.
-- Set `powerlineSeparator` to `false` for plain spaces instead of `` / `` if your font lacks those glyphs. The git icon `` also needs a compatible font; hide it with `showGitBranch: false` if needed.
+- Set `powerlineSeparator` to `false` for plain spaces instead of `` / `` if your font lacks those glyphs. The git icon `` and sync arrows also need compatible glyphs; hide Git data with `showGitBranch: false` if needed.
+- Git sync counts are omitted for branches without an upstream, detached HEADs, and non-Git directories.
 - `maxUsageBarCells` caps the Braille bar length (excluding brackets and reset time). Use a positive integer, e.g. `4` for a compact bar; invalid values fall back to `10`.
 
 ## Reading the footer

package/VISION.md

@@ -8,11 +8,12 @@ The [README](README.md) is the user manual. This document records current design
 
 ## Layout contract
 
-- Directory and git branch form the left group, separated by ``.
+- Directory and git branch form the left group, separated by ``. Pi supplies the branch name; the extension asynchronously runs `git rev-list --left-right --count HEAD...@{upstream}` to append local/upstream divergence as `↑N`/`↓N` (push/pull). The counts are omitted when no upstream is configured, and Git work stays outside synchronous rendering so a slow repository cannot block the TUI.
 - Each extension status is its own `` tab. Preserve the supplied text; do not invent status labels, parentheses, or pipes.
 - Model, context, and subscription usage form the rightmost group, separated by ` · `. Model identifies the running engine; context describes its usage; the usage bar stays anchored at the right edge.
 - Powerline separators are dim. `powerlineSeparator: false` replaces them with a single space. Font availability cannot be detected reliably.
 - Measure terminal columns with `visibleWidth`, not string length. Preserve ANSI styling and wide-character accounting when truncating.
+- Git divergence refreshes on Pi's branch-change signal and normal footer state refreshes; it is best-effort and never allowed to prevent the footer from loading.
 
 ### Space allocation
 

package/extensions/index.ts

@@ -17,6 +17,8 @@ import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
 import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
 import { join, dirname, sep } from "node:path";
 import { homedir } from "node:os";
+import { promisify } from "node:util";
+import { execFile } from "node:child_process";
 import { BASE_BAR_CELLS, MAX_BAR_CELLS, UsageLimits } from "./lib/usage-limits.js";
 
 // ── Settings ──────────────────────────────────────────────────────────
@@ -36,6 +38,8 @@ interface Settings {
 
 type FooterSettings = NonNullable<Settings["minFooter"]>;
 
+const execFileAsync = promisify(execFile);
+
 const DEFAULT_SETTINGS: FooterSettings = {
   enabled: true,
   showGitBranch: true,
@@ -111,6 +115,32 @@ interface FooterState {
   cwd: string;
   model: string;
   context: string;
+  gitSync: string;
+}
+
+async function getGitSync(cwd: string): Promise<string> {
+  try {
+    // Pi exposes the branch name, but not upstream divergence. Keep this
+    // asynchronous and outside render() so a slow Git repository cannot block TUI rendering.
+    const { stdout } = await execFileAsync("git", ["-C", cwd, "rev-list", "--left-right", "--count", "HEAD...@{upstream}"], {
+      timeout: 1000,
+      maxBuffer: 1024,
+    });
+    // With HEAD...@{upstream}, left is local-only commits (push) and right
+    // is upstream-only commits (pull). An absent upstream is intentionally hidden.
+    const [ahead, behind] = stdout.trim().split(/\s+/).map(Number);
+    if (!Number.isInteger(ahead) || !Number.isInteger(behind)) return "";
+    return `${ahead ? ` ↑${ahead}` : ""}${behind ? ` ↓${behind}` : ""}`;
+  } catch {
+    // No repository, upstream, or reachable Git command: omit sync status.
+    return "";
+  }
+}
+
+async function updateGitSync(state: FooterState): Promise<void> {
+  const cwd = state.cwd;
+  const gitSync = await getGitSync(cwd);
+  if (state.cwd === cwd) state.gitSync = gitSync;
 }
 
 function updateState(ctx: ExtensionContext, state: FooterState): void {
@@ -203,7 +233,7 @@ function buildLine(
 export default function (pi: ExtensionAPI) {
   let config = readConfig();
   let enabled = config.enabled !== false;
-  const state: FooterState = { cwd: process.cwd(), model: "no-model", context: "?" };
+  const state: FooterState = { cwd: process.cwd(), model: "no-model", context: "?", gitSync: "" };
   let requestRender: (() => void) | null = null;
   let disposeFooter: (() => void) | null = null;
   const usageLimits = new UsageLimits(() => requestRender?.());
@@ -226,7 +256,12 @@ export default function (pi: ExtensionAPI) {
     }
 
     ctx.ui.setFooter((tui, theme, footerData) => {
-      const unsub = footerData.onBranchChange(() => tui.requestRender());
+      // Branch changes are Pi's invalidation signal; refresh the async Git
+      // divergence separately because footer rendering must remain synchronous.
+      const unsub = footerData.onBranchChange(() => {
+        void updateGitSync(state).then(() => tui.requestRender());
+        tui.requestRender();
+      });
       const request = () => tui.requestRender();
       requestRender = request;
       let disposed = false;
@@ -249,12 +284,13 @@ export default function (pi: ExtensionAPI) {
             ? [...footerData.getExtensionStatuses().values()].filter((s) => s.trim())
             : [];
           const branch = config.showGitBranch ? footerData.getGitBranch() : null;
+          const branchText = branch ? `${branch}${state.gitSync}` : "";
           const statusSeparator = config.powerlineSeparator ? theme.fg("dim", "  ") : " ";
           const line = buildLine(
             width,
             config.showPath ? theme.fg("dim", abbreviateHome(state.cwd, homedir())) : "",
             statuses.length ? statusSeparator + statuses.map((status) => theme.fg("dim", status)).join(statusSeparator) : "",
-            branch ? theme.fg("dim", ` ${branch}`) : "",
+            branchText ? theme.fg("dim", ` ${branchText}`) : "",
             config.showModel ? theme.bold(state.model) : "",
             config.showContext ? theme.fg("dim", theme.bold(state.context)) : "",
             (available, maxCells = BASE_BAR_CELLS) => usageLimits.line(available, theme, maxCells),
@@ -274,6 +310,7 @@ export default function (pi: ExtensionAPI) {
   /** Cheap refresh: update plain state and request one render. */
   function refresh(ctx: ExtensionContext): void {
     updateState(ctx, state);
+    void updateGitSync(state).then(() => requestRender?.());
     requestRender?.();
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-minimal-footer",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "An opinionated minimal footer extension for Pi — clean status line with path, extension statuses, model, and context usage.",
   "keywords": [
     "pi-package",