pi-minimal-footer 0.4.2 → 0.5.1

package/CHANGELOG.md

@@ -7,6 +7,23 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.5.1] - 2026-10-07
+
+### Changed
+
+- Keep the whole Git section in normal text foreground while commits remain to push or pull, returning to dim when synced
+- Bold changed Git divergence arrows/counts for two user submissions; further changes restart the highlight, while tool turns and extension prompts do not consume it
+
+## [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
@@ -186,7 +203,9 @@ First npm-ready release.
 
 - Project scaffold — `extensions/index.ts` with basic footer structure, `package.json` with pi extension manifest, `README.md`, `LICENSE` (MIT)
 
-[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.4.2...HEAD
+[Unreleased]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.5.1...HEAD
+[0.5.1]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.5.0...v0.5.1
+[0.5.0]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.4.2...v0.5.0
 [0.4.2]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.4.1...v0.4.2
 [0.4.1]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/Ryu-CZ/pi-minimal-footer/compare/v0.3.3...v0.4.0

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: ` main ↑2 ↓1` (`↑` to push, `↓` to pull)
 
 **Right**
 
@@ -59,11 +59,15 @@ 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.
 - `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
 
+### Git
+
+Counts require a configured upstream. Unsynced branches use the theme's normal foreground; synced branches are dim. Changed counts stay bold until two subsequent user messages; further changes restart the highlight.
+
 ### Context
 
 `42/200k` means tokens used / context window. `?` means Pi has not reported usage yet, including immediately after compaction.

package/VISION.md

@@ -8,7 +8,7 @@ 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 ``.
 - 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.
@@ -36,6 +36,14 @@ Two cells give 6.25% steps; ten give 1.25%. Fill rounds to the nearest eighth-ce
 
 The bar and reset label have no intervening space. Reset formatting uses local clock time through 24 hours, remaining whole days/hours above 24 hours, and whole days above 10 days. Exactly 24 hours stays clock time; exactly 10 days is `↻10d0h`. Missing reset metadata leaves the bar visible without a label.
 
+## Git contract
+
+- Pi supplies the branch name. Query `git rev-list --left-right --count HEAD...@{upstream}` for `↑N` local-only and `↓N` upstream-only commits. Use local refs; never fetch automatically.
+- Query outside rendering with a one-second timeout so Git cannot block the TUI. Missing upstreams and command failures omit counts.
+- Refresh on branch-change signals and footer state updates. Ignore older query results to prevent stale counts from restarting highlights.
+- Use the theme's normal text foreground while unsynced, otherwise dim. A count change bolds the arrows/counts until two subsequent user submissions; further changes restart the window. Tool turns and extension prompts do not consume it.
+- Initial loading and working-directory changes establish an unhighlighted baseline. Zero counts hide the arrows entirely.
+
 ## Subscription usage contract
 
 Display only the selected provider's shortest applicable window. Subscription usage and model context usage are separate measurements.
@@ -95,12 +103,18 @@ For a manual install, copy `extensions/*` into `~/.pi/agent/extensions/`.
 - `extensions/index.ts`: settings, state refresh, layout, footer lifecycle, and `/minfooter`.
 - `extensions/lib/usage-limits.ts`: usage refresh, cache, cancellation, and bar/reset rendering.
 - `extensions/lib/usage-providers.ts`: authentication, endpoint selection, and response normalization.
-- `tests/`: loader-based lifecycle/layout regression tests and usage parsing tests.
+- `tests/`: lifecycle/layout regressions, Git highlighting with a temporary repository, and usage parsing tests.
 
 Settings live under `minFooter` in Pi's configured agent directory. Read them at session start or explicit toggle; ordinary refreshes use cached settings. Preserve unrelated settings on writes. Only install the footer in interactive terminal mode.
 
 ### Checking changes
 
-For behavior changes, run `npm run check` and `npm test`. Layout tests should cover narrow widths, ANSI text, wide Unicode, field priority, and both separator modes. Subscription usage changes should cover provider switches, timeouts, stale cache, partial updates, and malformed/missing metadata as applicable. Preview in a real terminal for font-dependent appearance; automated width checks cannot prove glyph availability.
+Run `npm run check` and `npm test` for behavior changes. Cover relevant cases:
+
+- Layout: narrow widths, ANSI/wide Unicode, field priority, and separator modes.
+- Git: divergence, synced styling, highlight expiry/restart, and user submissions versus tool turns.
+- Subscription usage: provider switches, timeouts, stale cache, partial updates, and malformed/missing metadata.
+
+Preview font-dependent appearance in a real terminal; width checks cannot prove glyph availability.
 
 Keep release notes in [CHANGELOG.md](CHANGELOG.md), and keep the README focused on installation and daily use. Preserve [upstream MIT attribution](extensions/lib/LICENSE) when changing adapted provider code.

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,10 +115,50 @@ interface FooterState {
   cwd: string;
   model: string;
   context: string;
+  gitSync: string;
+  gitInitialized: boolean;
+  gitHighlightInputs: number;
+  gitRequest: number;
+}
+
+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 request = ++state.gitRequest;
+  const gitSync = await getGitSync(cwd);
+  // Refresh events can overlap; an older result must not restart the highlight.
+  if (state.cwd !== cwd || request !== state.gitRequest) return;
+  if (state.gitInitialized && state.gitSync !== gitSync) state.gitHighlightInputs = 2;
+  state.gitSync = gitSync;
+  state.gitInitialized = true;
 }
 
 function updateState(ctx: ExtensionContext, state: FooterState): void {
-  state.cwd = ctx.cwd ?? process.cwd();
+  const cwd = ctx.cwd ?? process.cwd();
+  if (state.cwd !== cwd) {
+    state.gitSync = "";
+    state.gitInitialized = false;
+    state.gitHighlightInputs = 0;
+  }
+  state.cwd = cwd;
   state.model = ctx.model?.id ?? "no-model";
   const usage = ctx.getContextUsage();
   if (usage) {
@@ -203,7 +247,10 @@ 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: "",
+    gitInitialized: false, gitHighlightInputs: 0, gitRequest: 0,
+  };
   let requestRender: (() => void) | null = null;
   let disposeFooter: (() => void) | null = null;
   const usageLimits = new UsageLimits(() => requestRender?.());
@@ -226,7 +273,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 +301,15 @@ export default function (pi: ExtensionAPI) {
             ? [...footerData.getExtensionStatuses().values()].filter((s) => s.trim())
             : [];
           const branch = config.showGitBranch ? footerData.getGitBranch() : null;
+          const syncText = state.gitHighlightInputs > 0 ? theme.bold(state.gitSync) : state.gitSync;
+          const branchText = branch ? `${branch}${syncText}` : "";
           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}`) : "",
+            // Keep unsynced branches readable; bold counts separately mark recent changes.
+            branchText ? theme.fg(state.gitSync ? "text" : "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 +329,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?.();
   }
 
@@ -285,6 +341,13 @@ export default function (pi: ExtensionAPI) {
     install(ctx);
   });
 
+  // Count user submissions, not turn_end: one prompt can trigger many tool turns.
+  // Extension-generated prompts do not consume the user's highlight window.
+  pi.on("input", (event, ctx) => {
+    if (event.source !== "extension" && state.gitHighlightInputs > 0) state.gitHighlightInputs--;
+    refresh(ctx);
+  });
+
   pi.on("model_select", async (_event, ctx) => {
     selectUsage(ctx);
     refresh(ctx);

package/package.json

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