@pi-archimedes/footer 2.0.0 → 2.1.0

package/README.md

@@ -0,0 +1,46 @@
+# @pi-archimedes/footer
+
+A status bar that shows what matters — at a glance, without getting in the way.
+
+Your terminal is already full of information. The footer gives you exactly what you need to know about your session — where you are, what model you're using, how many tokens you've burned, and how close you are to the context limit — all in one clean line at the bottom. When subagents run, their costs merge seamlessly into the same view.
+
+## What you get
+
+- **Session context at a glance** — directory, git branch (with clean/dirty indicator), active model, thinking level, and worktree
+- **Token stats** — input ↑, output ↓, cache read/write, and real-dollar cost, all in one compact display
+- **Context window bar** — color-coded progress bar (green → yellow → red) showing how much of your context window is used
+- **Smart layout** — single line on wide terminals, auto-splits to two lines when space is tight (threshold configurable)
+- **Unified subagent costs** — when subagents run, their token usage and cost merge into the main footer automatically
+
+## Install
+
+```bash
+pi install npm:@pi-archimedes/footer
+```
+
+Or install full meta package:
+
+```bash
+pi install npm:pi-archimedes
+```
+
+## Usage
+
+Footer renders automatically at the bottom of the Pi TUI. No commands to run.
+
+On wide terminals, the footer displays as a single clean line containing all session context, token usage, cost, and context window progress. When the terminal width falls below the configured split threshold, the footer automatically splits into two lines to keep all information clear and readable without clipping.
+
+## Settings
+
+| Setting | Type | Default | Description |
+|---------|------|---------|-------------|
+| `splitThreshold` | number | `150` | Minimum terminal width (columns) to display footer on a single line. Below this width, the footer splits into two lines. |
+
+Settings are stored in `~/.pi/agent/settings.json` under the `archimedes.footer` namespace.
+
+## Integration
+
+When installed via meta package, footer consumes cost events from subagents through the core bus, giving a unified token/cost view. Standalone install shows only the main agent's stats.
+
+
+← Back to [pi-archimedes](../../README.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-archimedes/footer",
-  "version": "2.0.0",
+  "version": "2.1.0",
   "type": "module",
   "keywords": [
     "pi-package"
@@ -15,7 +15,7 @@
     "./config": "./src/config.ts"
   },
   "dependencies": {
-    "@pi-archimedes/core": "2.0.0"
+    "@pi-archimedes/core": "2.1.0"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=0.1.0",

package/src/utils/git.test.ts

@@ -0,0 +1,123 @@
+import { describe, it, expect, vi, afterEach } from "vitest";
+import * as fc from "fast-check";
+
+// ── Type alias ──────────────────────────────────────────────────────────────
+
+interface GitStatus {
+  staged: number;
+  unstaged: number;
+  untracked: number;
+  ahead: number;
+  behind: number;
+}
+
+// ── Tests (vi.resetModules + dynamic import to isolate module state) ────────
+
+describe("getGitStatus", () => {
+  let getGitStatus: () => GitStatus;
+  let getWorktreeBranch: () => string | null;
+
+  async function loadModule(mockExecSync: ReturnType<typeof vi.fn>) {
+    vi.resetModules();
+
+    vi.doMock("child_process", () => ({
+      execSync: mockExecSync,
+    }));
+
+    vi.doMock("fs", () => ({
+      realpathSync: vi.fn((p: string) => p),
+    }));
+
+    const mod = await import("./git.js");
+    getGitStatus = mod.getGitStatus;
+    getWorktreeBranch = mod.getWorktreeBranch;
+  }
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+  });
+
+  it("empty output returns zero status", async () => {
+    const mockExecSync = vi.fn(() => "");
+    await loadModule(mockExecSync);
+    const result = getGitStatus();
+    expect(result).toEqual({ staged: 0, unstaged: 0, untracked: 0, ahead: 0, behind: 0 });
+  });
+
+  it("parse scored format lines", async () => {
+    const mockExecSync = vi.fn(() => "1 AM file1.txt\n1  M file2.txt\n");
+    await loadModule(mockExecSync);
+    const result = getGitStatus();
+    // AM: index=A (staged), workTree=M (unstaged) → 1 staged, 1 unstaged
+    // " M": index=space (not staged), workTree=M (unstaged) → 1 unstaged
+    expect(result.staged).toBe(1);
+    expect(result.unstaged).toBe(2);
+  });
+
+  it("parse unscored format lines (note: trim() strips leading space)", async () => {
+    // TODO: parseGitOutput calls output.trim() which strips leading whitespace.
+    // This means unscored lines like " M file.txt" (index=space, workTree=M,
+    // meaning unstaged modification) become "M file.txt" after trim, and are
+    // incorrectly parsed as index=M (staged), workTree=space.
+    // This test codifies the current (buggy) behavior so future fixes to
+    // remove trim() won't break silently — update both the implementation
+    // and this test together when fixing.
+    const mockExecSync = vi.fn(() => "M  file.txt\nA  staged.txt\n");
+    await loadModule(mockExecSync);
+    const result = getGitStatus();
+    // "M ": index=M (staged), workTree=space → 1 staged
+    // "A ": index=A (staged), workTree=space → 1 staged
+    expect(result.staged).toBe(2);
+    expect(result.unstaged).toBe(0);
+  });
+
+  it("parse untracked lines", async () => {
+    const mockExecSync = vi.fn(() => "?  untracked1.txt\n?  untracked2.txt\n");
+    await loadModule(mockExecSync);
+    const result = getGitStatus();
+    expect(result.untracked).toBe(2);
+  });
+
+  it("parse branch summary (ahead/behind)", async () => {
+    const mockExecSync = vi.fn(() => "## main...origin/main 3 2\n");
+    await loadModule(mockExecSync);
+    const result = getGitStatus();
+    expect(result.ahead).toBe(3);
+    expect(result.behind).toBe(2);
+  });
+
+  it("malformed lines ignored gracefully", async () => {
+    const mockExecSync = vi.fn(() => "this is not valid\n\n  \n1 AM valid.txt\n");
+    await loadModule(mockExecSync);
+    const result = getGitStatus();
+    // Only the valid scored line should be parsed
+    expect(result.staged).toBe(1);
+    expect(result.unstaged).toBe(1);
+  });
+
+  it("getWorktreeBranch returns null when not in worktree", async () => {
+    const mockExecSync = vi.fn(() => "head ref/heads/main\nworktree /path/to/repo\n");
+    await loadModule(mockExecSync);
+    const result = getWorktreeBranch();
+    expect(result).toBeNull();
+  });
+
+  it("property: getGitStatus never throws (catches execSync errors gracefully)", async () => {
+    const mockExecSync = vi.fn(() => { throw new Error("git not found"); });
+    await loadModule(mockExecSync);
+    expect(() => getGitStatus()).not.toThrow();
+    const result = getGitStatus();
+    expect(result).toEqual({ staged: 0, unstaged: 0, untracked: 0, ahead: 0, behind: 0 });
+  });
+
+  it("property: parseGitOutput handles arbitrary git porcelain output without throwing", async () => {
+    await fc.assert(
+      fc.asyncProperty(fc.string({ maxLength: 500 }), async (output) => {
+        const mockExecSync = vi.fn(() => output);
+        await loadModule(mockExecSync);
+        expect(() => getGitStatus()).not.toThrow();
+      }),
+      { verbose: false },
+    );
+  });
+});

package/src/utils/stats.test.ts

@@ -0,0 +1,229 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import * as fc from "fast-check";
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+interface MessageUsage {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+  cost: { total: number };
+}
+
+interface AssistantMessage {
+  role: "assistant";
+  usage: MessageUsage;
+}
+
+interface UserMessage {
+  role: "user";
+  content: string;
+}
+
+interface SessionEntry {
+  type: "message";
+  message: AssistantMessage | UserMessage;
+}
+
+interface MockContext {
+  sessionManager: {
+    getEntries: () => SessionEntry[];
+  };
+  getContextUsage: () => { contextWindow?: number; percent?: number } | undefined;
+  model?: { contextWindow?: number };
+}
+
+function makeAssistantEntry(usage: MessageUsage): SessionEntry {
+  return {
+    type: "message",
+    message: { role: "assistant", usage },
+  };
+}
+
+function makeUserEntry(): SessionEntry {
+  return {
+    type: "message",
+    message: { role: "user", content: "hello" },
+  };
+}
+
+function makeCtx(entries: SessionEntry[], contextUsage?: { contextWindow?: number; percent?: number }, modelContextWindow?: number): any {
+  return {
+    sessionManager: { getEntries: () => entries },
+    getContextUsage: () => contextUsage,
+    model: modelContextWindow ? { contextWindow: modelContextWindow } : undefined,
+  };
+}
+
+// ── Tests (vi.resetModules + dynamic import to isolate module state) ────────
+
+describe("getTokenUsageStats", () => {
+  let getTokenUsageStats: typeof import("./stats.js").getTokenUsageStats;
+  let invalidateStatsCache: typeof import("./stats.js").invalidateStatsCache;
+
+  async function loadModule() {
+    vi.resetModules();
+    const mod = await import("./stats.js");
+    getTokenUsageStats = mod.getTokenUsageStats;
+    invalidateStatsCache = mod.invalidateStatsCache;
+  }
+
+  it("empty entries returns zero stats", async () => {
+    await loadModule();
+    const ctx = makeCtx([]);
+    const result = getTokenUsageStats(ctx);
+    expect(result).toEqual({
+      totalInput: 0,
+      totalOutput: 0,
+      totalCacheRead: 0,
+      totalCacheWrite: 0,
+      totalCost: 0,
+    });
+  });
+
+  it("single assistant message accumulates correctly", async () => {
+    await loadModule();
+    const usage = { input: 100, output: 50, cacheRead: 200, cacheWrite: 100, cost: { total: 0.05 } };
+    const ctx = makeCtx([makeAssistantEntry(usage)]);
+    const result = getTokenUsageStats(ctx);
+    expect(result).toEqual({
+      totalInput: 100,
+      totalOutput: 50,
+      totalCacheRead: 200,
+      totalCacheWrite: 100,
+      totalCost: 0.05,
+    });
+  });
+
+  it("multiple messages sum correctly", async () => {
+    await loadModule();
+    const ctx = makeCtx([
+      makeAssistantEntry({ input: 100, output: 50, cacheRead: 10, cacheWrite: 5, cost: { total: 0.01 } }),
+      makeAssistantEntry({ input: 200, output: 100, cacheRead: 20, cacheWrite: 10, cost: { total: 0.02 } }),
+    ]);
+    const result = getTokenUsageStats(ctx);
+    expect(result).toEqual({
+      totalInput: 300,
+      totalOutput: 150,
+      totalCacheRead: 30,
+      totalCacheWrite: 15,
+      totalCost: 0.03,
+    });
+  });
+
+  it("non-assistant messages ignored", async () => {
+    await loadModule();
+    const ctx = makeCtx([
+      makeUserEntry(),
+      makeAssistantEntry({ input: 100, output: 50, cacheRead: 0, cacheWrite: 0, cost: { total: 0.01 } }),
+      makeUserEntry(),
+    ]);
+    const result = getTokenUsageStats(ctx);
+    expect(result.totalInput).toBe(100);
+    expect(result.totalOutput).toBe(50);
+  });
+
+  it("cache returns same result within TTL", async () => {
+    await loadModule();
+    const ctx = makeCtx([
+      makeAssistantEntry({ input: 100, output: 50, cacheRead: 0, cacheWrite: 0, cost: { total: 0.01 } }),
+    ]);
+    const first = getTokenUsageStats(ctx);
+    const second = getTokenUsageStats(ctx);
+    expect(first).toBe(second); // same reference (cached)
+  });
+
+  it("invalidateStatsCache clears cache", async () => {
+    await loadModule();
+    const ctx = makeCtx([
+      makeAssistantEntry({ input: 100, output: 50, cacheRead: 0, cacheWrite: 0, cost: { total: 0.01 } }),
+    ]);
+    const first = getTokenUsageStats(ctx);
+    invalidateStatsCache();
+    const second = getTokenUsageStats(ctx);
+    expect(first).toEqual(second);
+    expect(first).not.toBe(second); // different reference (cache cleared)
+  });
+
+  it("property: stats are monotonic (adding entries never decreases totals)", async () => {
+    await loadModule();
+    fc.assert(
+      fc.property(
+        fc.array(
+          fc.record({
+            input: fc.nat({ max: 1000 }),
+            output: fc.nat({ max: 1000 }),
+            cacheRead: fc.nat({ max: 1000 }),
+            cacheWrite: fc.nat({ max: 1000 }),
+            cost: fc.double({ min: 0, max: 1 }),
+          }),
+        ),
+        (usages) => {
+          const entries: SessionEntry[] = [];
+          let prev = { totalInput: 0, totalOutput: 0, totalCacheRead: 0, totalCacheWrite: 0, totalCost: 0 };
+          for (const u of usages) {
+            entries.push(makeAssistantEntry({ input: u.input, output: u.output, cacheRead: u.cacheRead, cacheWrite: u.cacheWrite, cost: { total: u.cost } }));
+            const ctx = makeCtx(entries);
+            const curr = getTokenUsageStats(ctx);
+            // Monotonic: each total >= previous
+            if (
+              curr.totalInput < prev.totalInput ||
+              curr.totalOutput < prev.totalOutput ||
+              curr.totalCacheRead < prev.totalCacheRead ||
+              curr.totalCacheWrite < prev.totalCacheWrite ||
+              curr.totalCost < prev.totalCost
+            ) {
+              throw new Error(`Monotonicity violated: ${JSON.stringify(prev)} -> ${JSON.stringify(curr)}`);
+            }
+            prev = curr;
+          }
+        },
+      ),
+      { verbose: false },
+    );
+  });
+});
+
+describe("getContextWindowInfo", () => {
+  let getContextWindowInfo: typeof import("./stats.js").getContextWindowInfo;
+
+  async function loadModule() {
+    vi.resetModules();
+    const mod = await import("./stats.js");
+    getContextWindowInfo = mod.getContextWindowInfo;
+  }
+
+  it("computes percentage correctly", async () => {
+    await loadModule();
+    const ctx = makeCtx(
+      [makeAssistantEntry({ input: 500, output: 500, cacheRead: 0, cacheWrite: 0, cost: { total: 0 } })],
+      { contextWindow: 10000, percent: 10 },
+    );
+    const result = getContextWindowInfo(ctx);
+    expect(result.percent).toBe("10.0");
+    expect(result.percentValue).toBe(10);
+    expect(result.windowSize).toBe(10000);
+  });
+
+  it("handles missing context window", async () => {
+    await loadModule();
+    const ctx = makeCtx([], undefined);
+    const result = getContextWindowInfo(ctx);
+    expect(result.percent).toBe("?");
+    expect(result.percentValue).toBe(0);
+    expect(result.windowSize).toBe(0);
+  });
+
+  it("computes percentage from tokens when contextUsage.percent missing", async () => {
+    await loadModule();
+    const ctx = makeCtx(
+      [makeAssistantEntry({ input: 500, output: 500, cacheRead: 0, cacheWrite: 0, cost: { total: 0 } })],
+      { contextWindow: 10000 },
+    );
+    const result = getContextWindowInfo(ctx);
+    expect(result.percent).toBe("?");
+    expect(result.percentValue).toBe(10);
+    expect(result.windowSize).toBe(10000);
+  });
+});