@neilurk12/pi-clean-footer 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# pi-clean-footer
+
+Clean adaptive footer extension for [pi](https://pi.dev).
+
+Shows a compact split footer:
+
+![pi-clean-footer example](./example.png)
+
+## Features
+
+- Smart short model names, plus thinking effort (`low`, `med`, `high`, `xhigh`)
+- Current directory basename only
+- Git branch + dirty file count, including untracked files
+- Event-driven git refresh after file-changing tools and user bash commands
+- Context usage as `used/max`
+- Cumulative active-branch token totals: input, output, total, cache read, cache write
+- Adaptive width tiers for narrow terminals
+- `/footer` toggle
+- `/footer refresh` force refresh
+
+## Install
+
+From local checkout:
+
+```bash
+pi install /absolute/path/to/pi-clean-footer
+```
+
+For project-local install, run from your project:
+
+```bash
+pi install -l /absolute/path/to/pi-clean-footer
+```
+
+For quick testing without installing:
+
+```bash
+pi -e /absolute/path/to/pi-clean-footer
+```
+
+Then reload pi resources:
+
+```text
+/reload
+```
+
+## Usage
+
+Toggle footer:
+
+```text
+/footer
+```
+
+Force git refresh:
+
+```text
+/footer refresh
+```
+
+Show active config paths and resolved config:
+
+```text
+/footer config
+```
+
+Reload config after editing JSON:
+
+```text
+/footer reload
+```
+
+## Configuration
+
+Config is optional. Defaults match the built-in package behavior.
+
+Load order:
+
+1. Global: `~/.pi/agent/clean-footer.json`
+2. Project: `.pi/clean-footer.json`
+
+Project config overrides global config. Nested `modelAliases` and `colors` are merged.
+
+Example:
+
+```json
+{
+  "enabled": true,
+  "showGit": true,
+  "showTokens": true,
+  "showCache": false,
+  "showContext": true,
+  "showDirectory": true,
+  "showEffort": true,
+  "gitRefreshDebounceMs": 500,
+  "contextWarningPercent": 70,
+  "contextDangerPercent": 85,
+  "modelAliases": {
+    "claude-sonnet-4-5-20250929": "sonnet-4.5",
+    "gpt-5.5-codex": "gpt-5.5"
+  },
+  "colors": {
+    "model": "accent",
+    "directory": "dim",
+    "git": "success",
+    "gitDirty": "warning",
+    "contextNormal": "success",
+    "contextWarning": "warning",
+    "contextDanger": "error",
+    "tokens": "muted",
+    "separator": "dim"
+  }
+}
+```
+
+Malformed JSON keeps defaults/last loaded behavior and reports an error through `/footer config` or at startup.
+
+## Package manifest
+
+This package declares its extension through `package.json`:
+
+```json
+{
+  "pi": {
+    "extensions": ["./src/index.ts"]
+  }
+}
+```
+
+## Development
+
+Type-check extension:
+
+```bash
+npx tsc --noEmit --skipLibCheck --moduleResolution Node16 --module Node16 --target ES2022 --types node src/index.ts
+```
+
+## Notes
+
+Extensions run with full system permissions. Review code before installing any pi package.

package/docs/superpowers/plans/2026-05-09-clean-footer-extension.md

@@ -0,0 +1,546 @@
+# Clean Footer Extension Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Build a project-local pi extension that replaces the built-in footer with a cleaner adaptive footer showing model/effort, directory, git state, context usage, and cumulative token/cache telemetry.
+
+**Architecture:** Implement one self-contained TypeScript extension at `.pi/extensions/clean-footer/index.ts`. Keep git state outside render and refresh it through debounced event handlers. Render computes lightweight session totals and adaptive layout from current width.
+
+**Tech Stack:** pi extension API, TypeScript, Node built-ins, `@earendil-works/pi-tui` width helpers, no external runtime deps.
+
+**Note:** Do not commit changes. Keep all work in workspace.
+
+---
+
+## File Structure
+
+- Create `.pi/extensions/clean-footer/index.ts`
+  - Registers footer command.
+  - Installs/removes custom footer.
+  - Tracks enabled state, git state, debounced refresh, thinking level.
+  - Formats model, effort, cwd basename, context, tokens, git state.
+  - Renders adaptive footer tiers.
+- Use existing `docs/superpowers/specs/2026-05-09-clean-footer-extension-design.md` as requirements reference.
+- No tests file initially; verification is manual because extension footer behavior depends on interactive pi TUI.
+
+---
+
+### Task 1: Create extension skeleton and default-on footer
+
+**Files:**
+
+- Create: `.pi/extensions/clean-footer/index.ts`
+
+- [ ] **Step 1: Create extension with command and lifecycle wiring**
+
+Create `.pi/extensions/clean-footer/index.ts` with:
+
+```typescript
+import type { AssistantMessage } from "@earendil-works/pi-ai";
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@earendil-works/pi-coding-agent";
+import { truncateToWidth, visibleWidth } from "@earendil-works/pi-tui";
+import { execFile } from "node:child_process";
+import path from "node:path";
+import { promisify } from "node:util";
+
+const execFileAsync = promisify(execFile);
+
+type GitState = {
+  inRepo: boolean;
+  branch?: string;
+  dirtyCount: number;
+};
+
+type Totals = {
+  input: number;
+  output: number;
+  cacheRead: number;
+  cacheWrite: number;
+};
+
+type FooterRuntime = {
+  enabled: boolean;
+  git: GitState;
+  thinkingLevel?: string;
+  refreshTimer?: NodeJS.Timeout;
+  requestRender?: () => void;
+};
+
+const runtime: FooterRuntime = {
+  enabled: true,
+  git: { inRepo: false, dirtyCount: 0 },
+};
+
+export default function (pi: ExtensionAPI) {
+  pi.registerCommand("footer", {
+    description: "Toggle or refresh the clean footer",
+    handler: async (args, ctx) => {
+      const command = args.trim();
+      if (command === "refresh") {
+        await refreshGit(ctx, true);
+        runtime.requestRender?.();
+        if (ctx.hasUI) ctx.ui.notify("Footer refreshed", "info");
+        return;
+      }
+
+      runtime.enabled = !runtime.enabled;
+      if (!ctx.hasUI) return;
+
+      if (runtime.enabled) {
+        installFooter(ctx);
+        await refreshGit(ctx, true);
+        ctx.ui.notify("Clean footer enabled", "info");
+      } else {
+        ctx.ui.setFooter(undefined);
+        ctx.ui.notify("Default footer restored", "info");
+      }
+    },
+  });
+
+  pi.on("session_start", async (_event, ctx) => {
+    runtime.thinkingLevel = normalizeThinkingLevel(pi.getThinkingLevel?.());
+    if (!ctx.hasUI || !runtime.enabled) return;
+    installFooter(ctx);
+    await refreshGit(ctx, true);
+  });
+
+  pi.on("session_shutdown", async (_event, ctx) => {
+    if (runtime.refreshTimer) clearTimeout(runtime.refreshTimer);
+    runtime.refreshTimer = undefined;
+    runtime.requestRender = undefined;
+    if (ctx.hasUI) ctx.ui.setFooter(undefined);
+  });
+
+  pi.on("thinking_level_select", (event) => {
+    runtime.thinkingLevel = normalizeThinkingLevel(event.level);
+    runtime.requestRender?.();
+  });
+
+  pi.on("model_select", () => {
+    runtime.requestRender?.();
+  });
+
+  pi.on("message_end", (event) => {
+    if (event.message.role === "assistant") runtime.requestRender?.();
+  });
+
+  pi.on("tool_execution_end", (event, ctx) => {
+    if (["bash", "edit", "write"].includes(event.toolName))
+      scheduleGitRefresh(ctx);
+    runtime.requestRender?.();
+  });
+
+  pi.on("user_bash", (_event, ctx) => {
+    scheduleGitRefresh(ctx);
+  });
+}
+```
+
+- [ ] **Step 2: Add no-op helper stubs so TypeScript names resolve**
+
+Append below the default export:
+
+```typescript
+function installFooter(ctx: ExtensionContext) {
+  if (!ctx.hasUI) return;
+
+  ctx.ui.setFooter((tui, theme) => {
+    runtime.requestRender = () => tui.requestRender();
+    return {
+      invalidate() {},
+      render(width: number): string[] {
+        return [
+          truncateToWidth(theme.fg("dim", "clean footer loading"), width),
+        ];
+      },
+    };
+  });
+}
+
+function normalizeThinkingLevel(level: unknown): string | undefined {
+  if (typeof level !== "string") return undefined;
+  const normalized = level.toLowerCase();
+  if (
+    ["low", "med", "medium", "high", "xhigh", "extra-high"].includes(normalized)
+  ) {
+    if (normalized === "medium") return "med";
+    if (normalized === "extra-high") return "xhigh";
+    return normalized;
+  }
+  return undefined;
+}
+
+async function refreshGit(ctx: ExtensionContext, immediate = false) {
+  runtime.git = { inRepo: false, dirtyCount: 0 };
+  if (immediate) runtime.requestRender?.();
+}
+
+function scheduleGitRefresh(ctx: ExtensionContext) {
+  if (runtime.refreshTimer) clearTimeout(runtime.refreshTimer);
+  runtime.refreshTimer = setTimeout(() => {
+    runtime.refreshTimer = undefined;
+    void refreshGit(ctx, true);
+  }, 500);
+}
+```
+
+- [ ] **Step 3: Verify skeleton loads**
+
+Run pi command manually from interactive session:
+
+```text
+/reload
+```
+
+Expected: no extension load error; footer changes to `clean footer loading`. `/footer` toggles back to built-in footer and again to clean footer.
+
+---
+
+### Task 2: Implement formatting helpers and telemetry totals
+
+**Files:**
+
+- Modify: `.pi/extensions/clean-footer/index.ts`
+
+- [ ] **Step 1: Replace loading render with computed segments**
+
+Replace `installFooter` with:
+
+```typescript
+function installFooter(ctx: ExtensionContext) {
+  if (!ctx.hasUI) return;
+
+  ctx.ui.setFooter((tui, theme) => {
+    runtime.requestRender = () => tui.requestRender();
+    return {
+      invalidate() {},
+      render(width: number): string[] {
+        const model = formatModelName(ctx.model?.id ?? "no-model");
+        const effort = runtime.thinkingLevel
+          ? ` • ${runtime.thinkingLevel}`
+          : "";
+        const modelSegment = theme.fg("accent", `${model}${effort}`);
+        const dirSegment = theme.fg("dim", path.basename(ctx.cwd));
+        const gitSegment = formatGitSegment(theme);
+        const ctxSegment = formatContextSegment(ctx, theme);
+        const tokenSegment = theme.fg(
+          "muted",
+          formatTokenSegment(getTotals(ctx), "full"),
+        );
+
+        const leftParts = [modelSegment, dirSegment, gitSegment].filter(
+          Boolean,
+        );
+        const left = leftParts.join(theme.fg("dim", " | "));
+        const right = [ctxSegment, tokenSegment]
+          .filter(Boolean)
+          .join(theme.fg("dim", " | "));
+        return [joinLeftRight(left, right, width)];
+      },
+    };
+  });
+}
+```
+
+- [ ] **Step 2: Add model/context/token helpers**
+
+Append helper functions:
+
+```typescript
+function formatModelName(modelId: string): string {
+  const lower = modelId.toLowerCase();
+  const withoutProvider = lower.includes("/") ? lower.split("/").pop()! : lower;
+
+  if (
+    withoutProvider.includes("claude") &&
+    withoutProvider.includes("sonnet")
+  ) {
+    if (withoutProvider.includes("4-5") || withoutProvider.includes("4.5"))
+      return "sonnet-4.5";
+    if (withoutProvider.includes("4")) return "sonnet-4";
+    return "sonnet";
+  }
+  if (withoutProvider.includes("claude") && withoutProvider.includes("opus"))
+    return "opus";
+  if (withoutProvider.includes("gpt-5"))
+    return withoutProvider.match(/gpt-5(?:[.-][a-z0-9]+)*/)?.[0] ?? "gpt-5";
+  if (withoutProvider.includes("gpt-4"))
+    return withoutProvider.match(/gpt-4(?:[.-][a-z0-9]+)*/)?.[0] ?? "gpt-4";
+  if (withoutProvider.includes("gemini"))
+    return withoutProvider.match(/gemini-[a-z0-9.-]+/)?.[0] ?? "gemini";
+
+  return withoutProvider.length > 24
+    ? `${withoutProvider.slice(0, 21)}…`
+    : withoutProvider;
+}
+
+function getTotals(ctx: ExtensionContext): Totals {
+  const totals: Totals = { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 };
+
+  for (const entry of ctx.sessionManager.getBranch()) {
+    if (entry.type !== "message" || entry.message.role !== "assistant")
+      continue;
+    const message = entry.message as AssistantMessage;
+    totals.input += message.usage?.input ?? 0;
+    totals.output += message.usage?.output ?? 0;
+    totals.cacheRead += message.usage?.cacheRead ?? 0;
+    totals.cacheWrite += message.usage?.cacheWrite ?? 0;
+  }
+
+  return totals;
+}
+
+function formatTokenSegment(
+  totals: Totals,
+  mode: "full" | "no-cache" | "total-only",
+): string {
+  const total = totals.input + totals.output;
+  if (mode === "total-only") return `Σ${formatCount(total)}`;
+  const base = `↑${formatCount(totals.input)} ↓${formatCount(totals.output)} Σ${formatCount(total)}`;
+  if (mode === "no-cache") return base;
+  return `${base} ↯${formatCount(totals.cacheRead)} ↥${formatCount(totals.cacheWrite)}`;
+}
+
+function formatContextSegment(
+  ctx: ExtensionContext,
+  theme: ExtensionContext["ui"]["theme"],
+): string {
+  const usage = ctx.getContextUsage?.();
+  const used = usage?.tokens ?? 0;
+  const max = ctx.model?.contextWindow;
+  const text = `ctx ${formatCount(used)}/${max ? formatCount(max) : "--"}`;
+
+  if (!max || max <= 0) return theme.fg("dim", text);
+  const ratio = used / max;
+  if (ratio >= 0.85) return theme.fg("error", text);
+  if (ratio >= 0.7) return theme.fg("warning", text);
+  return theme.fg("success", text);
+}
+
+function formatCount(value: number): string {
+  if (!Number.isFinite(value) || value <= 0) return "0";
+  if (value < 1_000) return `${Math.round(value)}`;
+  if (value < 1_000_000)
+    return `${(value / 1_000).toFixed(value < 10_000 ? 1 : 0)}k`;
+  return `${(value / 1_000_000).toFixed(1)}m`;
+}
+```
+
+- [ ] **Step 3: Add join helper**
+
+Append:
+
+```typescript
+function joinLeftRight(left: string, right: string, width: number): string {
+  if (!right) return truncateToWidth(left, width);
+  if (!left) return truncateToWidth(right, width);
+
+  const gap = width - visibleWidth(left) - visibleWidth(right);
+  if (gap >= 1) return truncateToWidth(left + " ".repeat(gap) + right, width);
+
+  const half = Math.max(1, Math.floor((width - 1) / 2));
+  return (
+    truncateToWidth(left, half) + " " + truncateToWidth(right, width - half - 1)
+  );
+}
+```
+
+- [ ] **Step 4: Verify model/dir/context/tokens render**
+
+Run:
+
+```text
+/reload
+```
+
+Expected: footer shows smart model name, effort when known, `footer` as dir basename, `ctx used/max`, and token segment. No git yet.
+
+---
+
+### Task 3: Implement git refresh and git rendering
+
+**Files:**
+
+- Modify: `.pi/extensions/clean-footer/index.ts`
+
+- [ ] **Step 1: Replace git stubs with real git commands**
+
+Replace `refreshGit` with:
+
+```typescript
+async function refreshGit(ctx: ExtensionContext, immediate = false) {
+  try {
+    const branchResult = await execFileAsync(
+      "git",
+      ["branch", "--show-current"],
+      {
+        cwd: ctx.cwd,
+        timeout: 2_000,
+      },
+    );
+    const statusResult = await execFileAsync("git", ["status", "--porcelain"], {
+      cwd: ctx.cwd,
+      timeout: 2_000,
+    });
+
+    const branch = branchResult.stdout.trim() || "detached";
+    const dirtyCount = statusResult.stdout.split("\n").filter(Boolean).length;
+    runtime.git = { inRepo: true, branch, dirtyCount };
+  } catch {
+    runtime.git = { inRepo: false, dirtyCount: 0 };
+  }
+
+  if (immediate) runtime.requestRender?.();
+}
+```
+
+- [ ] **Step 2: Add git segment formatter**
+
+Append:
+
+```typescript
+function formatGitSegment(
+  theme: ExtensionContext["ui"]["theme"],
+): string | undefined {
+  if (!runtime.git.inRepo || !runtime.git.branch) return undefined;
+  const branch = theme.fg("success", runtime.git.branch);
+  if (runtime.git.dirtyCount <= 0) return branch;
+  return `${branch} ${theme.fg("warning", `●${runtime.git.dirtyCount}`)}`;
+}
+```
+
+- [ ] **Step 3: Verify git hidden/visible behavior**
+
+Manual checks:
+
+```text
+/reload
+```
+
+Expected inside repo: footer shows `main` or current branch. Modify any file, then wait after tool/write or run `/footer refresh`; expected dirty count updates, including untracked files. Outside repo, expected git segment absent.
+
+---
+
+### Task 4: Implement adaptive width tiers
+
+**Files:**
+
+- Modify: `.pi/extensions/clean-footer/index.ts`
+
+- [ ] **Step 1: Replace render body with tiered render**
+
+Inside `installFooter` render, replace current segment assembly with:
+
+```typescript
+const model = formatModelName(ctx.model?.id ?? "no-model");
+const effort = runtime.thinkingLevel ? ` • ${runtime.thinkingLevel}` : "";
+const modelSegment = theme.fg("accent", `${model}${effort}`);
+const dirSegment = theme.fg("dim", path.basename(ctx.cwd));
+const gitSegment = formatGitSegment(theme);
+const ctxSegment = formatContextSegment(ctx, theme);
+const totals = getTotals(ctx);
+
+const leftFull = [modelSegment, dirSegment, gitSegment]
+  .filter(Boolean)
+  .join(theme.fg("dim", " | "));
+const leftMin = modelSegment;
+
+const full = joinLeftRight(
+  leftFull,
+  [ctxSegment, theme.fg("muted", formatTokenSegment(totals, "full"))].join(
+    theme.fg("dim", " | "),
+  ),
+  width,
+);
+if (visibleWidth(full) <= width && width >= 100) return [full];
+
+const medium = joinLeftRight(
+  leftFull,
+  [ctxSegment, theme.fg("muted", formatTokenSegment(totals, "no-cache"))].join(
+    theme.fg("dim", " | "),
+  ),
+  width,
+);
+if (visibleWidth(medium) <= width && width >= 80) return [medium];
+
+const small = joinLeftRight(
+  leftFull,
+  [
+    ctxSegment,
+    theme.fg("muted", formatTokenSegment(totals, "total-only")),
+  ].join(theme.fg("dim", " | ")),
+  width,
+);
+if (visibleWidth(small) <= width && width >= 60) return [small];
+
+const tiny = joinLeftRight(leftFull, ctxSegment, width);
+if (visibleWidth(tiny) <= width && width >= 40) return [tiny];
+
+return [joinLeftRight(leftMin, ctxSegment, width)];
+```
+
+- [ ] **Step 2: Verify all tiers by resizing terminal**
+
+Manual expected results:
+
+- Wide terminal: cache fields visible.
+- Medium terminal: cache fields disappear first.
+- Small terminal: only total tokens remain.
+- Tiny terminal: tokens disappear, context remains.
+- Minimum terminal: only model and context remain.
+
+---
+
+### Task 5: Polish behavior and self-review
+
+**Files:**
+
+- Modify: `.pi/extensions/clean-footer/index.ts`
+- Modify if needed: `docs/superpowers/plans/2026-05-09-clean-footer-extension.md`
+
+- [ ] **Step 1: Verify command behavior**
+
+Run manually:
+
+```text
+/footer
+/footer
+/footer refresh
+```
+
+Expected:
+
+- First `/footer`: default footer restored.
+- Second `/footer`: clean footer restored.
+- `/footer refresh`: git state refreshes and notification appears in UI.
+
+- [ ] **Step 2: Verify no render-time git calls**
+
+Inspect `.pi/extensions/clean-footer/index.ts` and confirm `execFileAsync("git", ...)` occurs only in `refreshGit`, never in `render`.
+
+- [ ] **Step 3: Verify spec coverage**
+
+Checklist:
+
+- [ ] Project-local extension exists at `.pi/extensions/clean-footer/index.ts`.
+- [ ] Footer enabled by default.
+- [ ] Footer splits left/right.
+- [ ] Model smart-shortening exists.
+- [ ] Effort displays beside model as `low/med/high/xhigh` when available.
+- [ ] Directory displays basename only.
+- [ ] Git hides outside repo.
+- [ ] Git shows branch plus dirty count including untracked.
+- [ ] Git refresh is event-driven and debounced.
+- [ ] Context shows `used/max` with `--` fallback.
+- [ ] Context warning thresholds are implemented.
+- [ ] Tokens show cumulative input/output/total/cache read/cache write.
+- [ ] Adaptive tiers hide fields in requested order.
+- [ ] `/footer` and `/footer refresh` work.
+- [ ] Non-UI contexts avoid throwing.
+
+- [ ] **Step 4: Keep workspace uncommitted**
+
+Do not run `git commit`. Leave created/modified files in workspace for user review.