@pi-unipi/footer 0.1.1

package/README.md

@@ -0,0 +1,206 @@
+# @pi-unipi/footer
+
+Persistent status bar for the Unipi extension suite.
+
+Subscribes to `UNIPI_EVENTS` and renders key stats from all unipi packages using pi's `setFooter` + `setWidget` APIs with responsive layout, presets, and per-segment toggling.
+
+## Features
+
+- **Persistent status bar** — always-visible footer showing key stats from all unipi packages
+- **Segment groups** — organized by package (core, compactor, memory, MCP, ralph, workflow, kanboard, notify)
+- **Presets** — default, minimal, compact, full, nerd, ascii
+- **Responsive layout** — adjusts to terminal width with secondary row overflow
+- **Per-segment toggling** — enable/disable individual segments or entire groups
+- **Theme integration** — uses pi's theme system with semantic colors
+- **Nerd Font support** — auto-detection with ASCII fallback
+- **Separator styles** — powerline, powerline-thin, slash, pipe, dot, ascii
+
+## Architecture
+
+```
+┌─────────────────────────────────────────────────────┐
+│  FooterRenderer (setFooter + setWidget)             │  ← Renders to screen
+│  - Responsive layout (top + secondary rows)          │
+│  - Preset system, separators, theming                │
+├─────────────────────────────────────────────────────┤
+│  FooterRegistry (segment groups)                     │  ← Manages segments
+│  - Subscribes to UNIPI_EVENTS                       │
+│  - Per-segment enable/disable                       │
+│  - Reactive data caching                            │
+├─────────────────────────────────────────────────────┤
+│  Event Sources (existing packages)                   │  ← Data providers
+│  - compactor, memory, workflow, ralph, mcp,          │
+│    kanboard, notify, core                           │
+└─────────────────────────────────────────────────────┘
+```
+
+## Usage
+
+The footer is automatically enabled when unipi loads. Use commands to control it:
+
+- `/unipi:footer` — toggle footer on/off
+- `/unipi:footer <preset>` — switch preset (default, minimal, compact, full, nerd, ascii)
+- `/unipi:footer sep:<style>` — change separator style (powerline, powerline-thin, slash, pipe, dot, ascii)
+- `/unipi:footer icon:<style>` — change icon style (nerd, emoji, text)
+- `/unipi:footer on` / `/unipi:footer off` — enable/disable explicitly
+- `/unipi:footer-settings` — open settings TUI for per-group/per-segment toggles
+
+## Segment Groups
+
+| Group | Segments | Default | Data Source |
+|-------|----------|---------|-------------|
+| **core** | `model`, `thinking`, `path`, `git`, `context_pct`, `cost`, `tokens_total`, `tokens_in`, `tokens_out`, `session`, `hostname`, `time` | ON (except hostname, time, tokens variants) | pi SDK (ctx.sessionManager, footerData) |
+| **compactor** | `session_events`, `compactions`, `tokens_saved`, `compression_ratio`, `indexed_docs`, `sandbox_runs`, `search_queries` | ON (key stats only) | `COMPACTOR_STATS_UPDATED` event |
+| **memory** | `project_count`, `total_count`, `consolidations` | ON | `MEMORY_STORED`/`DELETED`/`CONSOLIDATED` events |
+| **mcp** | `servers_total`, `servers_active`, `tools_total`, `servers_failed` | ON | `MCP_SERVER_STARTED`/`STOPPED`/`ERROR` events |
+| **ralph** | `active_loops`, `total_iterations`, `loop_status` | ON | `RALPH_LOOP_START`/`END`/`ITERATION_DONE` events |
+| **workflow** | `current_command`, `sandbox_level`, `command_duration` | ON | `WORKFLOW_START`/`END` events |
+| **kanboard** | `docs_count`, `tasks_done`, `tasks_total`, `task_pct` | ON | Kanboard registry (direct read) |
+| **notify** | `platforms_enabled`, `last_sent` | OFF | `NOTIFICATION_SENT` event |
+| **status_ext** | `extension_statuses` | ON | `footerData.getExtensionStatuses()` |
+
+## Presets
+
+| Preset | Description | Key Segments |
+|--------|-------------|-------------|
+| `default` | Balanced view | model, thinking, path, git, context, cost + compactor + memory + ralph |
+| `minimal` | Just the essentials | path, git, context |
+| `compact` | Core + key stats | model, git, cost, context + compactor + memory |
+| `full` | Everything | All segments from all groups |
+| `nerd` | Maximum detail for Nerd Font users | full + hostname + time + session + extensions |
+| `ascii` | Safe for any terminal | Core segments with ASCII icons |
+
+## Configuration
+
+Settings are stored in `~/.pi/agent/settings.json` under `unipi.footer`:
+
+```json
+{
+  "unipi": {
+    "footer": {
+      "enabled": true,
+      "preset": "default",
+      "separator": "powerline-thin",
+      "iconStyle": "nerd",
+      "groups": {
+        "compactor": {
+          "show": true,
+          "segments": {
+            "session_events": true,
+            "compactions": true,
+            "tokens_saved": true,
+            "compression_ratio": false,
+            "indexed_docs": false,
+            "sandbox_runs": false,
+            "search_queries": false
+          }
+        },
+        "memory": {
+          "show": true,
+          "segments": {
+            "project_count": true,
+            "total_count": true,
+            "consolidations": false
+          }
+        }
+      }
+    }
+  }
+}
+```
+
+## Responsive Layout
+
+```
+Wide terminal (>120 cols):
+  ┌─ model │ thinking │ path │ git │ context │ cost │ compactions │ tokens_saved │ project_count ─┐
+  └──────────────────────────────────────────────────────────────────────────────────────────────┘
+
+Narrow terminal (<120 cols):
+  ┌─ model │ thinking │ path │ git │ context │ cost ───────────────────────────────────────────────┐
+  └─ compactions │ tokens_saved │ project_count │ ralph │ workflow ────────────────────────────────┘
+```
+
+## Separator Styles
+
+| Style | Look | Description |
+|-------|------|-------------|
+| `powerline` | ◀ ▶ | Thick powerline arrows |
+| `powerline-thin` |   | Thin powerline arrows (default) |
+| `slash` | / | Slash separator |
+| `pipe` | \| | Pipe separator |
+| `dot` | · | Middle dot separator |
+| `ascii` | > < | ASCII angle brackets |
+
+## Icon Styles
+
+Three icon styles are available, controlled by `/unipi:footer icon:<style>` or the `iconStyle` setting:
+
+| Style | Description | Example |
+-------|-------------|--------|
+| `nerd` | Nerd Font glyphs (default, requires Nerd Font terminal) |  , ,  |
+| `emoji` | Unicode emoji/symbols (works on most terminals) | ⚡, ◧, $] |
+| `text` | Plain text abbreviations (works everywhere, most compact) | evt, cmp, $] |
+
+When `iconStyle` is not explicitly set, the footer auto-detects Nerd Font support and
+defaults to `nerd` if available, `emoji` otherwise.
+
+## Error Handling
+
+- **Event subscription failures:** Each handler wrapped in try/catch — one failing handler doesn't break others
+- **Data provider failures:** Segments hide when data unavailable (graceful degradation)
+- **Config parse failures:** Fall back to default preset with warning
+- **Module loading order:** Footer works even if packages load after it — late-arriving events update cache
+
+## Development
+
+```bash
+# Run tests
+pnpm test
+
+# Type check
+pnpm tsc --noEmit
+```
+
+## Package Structure
+
+```
+packages/footer/
+├── index.ts          # Re-exports
+├── types.ts          # Re-exports from src/types.ts
+├── package.json      # Package manifest
+├── tsconfig.json     # TypeScript config
+├── README.md         # This file
+├── src/
+│   ├── index.ts          # Extension entry point
+│   ├── types.ts          # Type definitions
+│   ├── config.ts         # Settings load/save
+│   ├── events.ts         # Event subscription wiring
+│   ├── commands.ts       # Command registration
+│   ├── presets.ts        # Preset definitions
+│   ├── registry/         # FooterRegistry
+│   │   └── index.ts
+│   ├── rendering/        # Rendering engine
+│   │   ├── renderer.ts   # FooterRenderer class
+│   │   ├── separators.ts # Separator system
+│   │   ├── theme.ts      # Theme color resolution
+│   │   └── icons.ts      # Icon system with Nerd Font detection
+│   ├── segments/         # Segment implementations
+│   │   ├── core.ts       # Core segments (model, path, git, etc.)
+│   │   ├── compactor.ts  # Compactor segments
+│   │   ├── memory.ts     # Memory segments
+│   │   ├── mcp.ts        # MCP segments
+│   │   ├── ralph.ts      # Ralph segments
+│   │   ├── workflow.ts   # Workflow segments
+│   │   ├── kanboard.ts   # Kanboard segments
+│   │   ├── notify.ts     # Notify segments
+│   │   └── status-ext.ts # Extension statuses segment
+│   └── tui/
+│       └── settings-tui.ts # Settings overlay TUI
+└── tests/               # Unit tests
+    ├── separators.test.ts
+    ├── registry.test.ts
+    ├── config.test.ts
+    ├── segments.test.ts
+    └── events.test.ts
+```

package/index.ts

@@ -0,0 +1,6 @@
+/**
+ * @pi-unipi/footer — Re-exports
+ */
+
+export { default } from "./src/index.js";
+export * from "./src/types.js";

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@pi-unipi/footer",
+  "version": "0.1.1",
+  "description": "Persistent status bar for Unipi — subscribes to UNIPI_EVENTS and renders key stats from all unipi packages",
+  "type": "module",
+  "license": "MIT",
+  "author": "Neuron Mr White",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Neuron-Mr-White/unipi.git",
+    "directory": "packages/footer"
+  },
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi-coding-agent",
+    "unipi",
+    "footer",
+    "status-bar"
+  ],
+  "files": [
+    "index.ts",
+    "src/**/*.ts",
+    "skills/**/*",
+    "README.md"
+  ],
+  "pi": {
+    "extensions": [
+      "src/index.ts"
+    ],
+    "skills": [
+      "skills"
+    ]
+  },
+  "scripts": {
+    "test": "node --experimental-strip-types --test tests/**/*.test.ts"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@pi-unipi/core": "*"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-coding-agent": "*",
+    "@mariozechner/pi-tui": "*"
+  },
+  "devDependencies": {
+    "@types/node": "^25.6.0",
+    "typescript": "^6.0.0"
+  }
+}

package/src/commands.ts

@@ -0,0 +1,204 @@
+/**
+ * @pi-unipi/footer — Commands
+ *
+ * Footer commands: /unipi:footer (toggle), /unipi:footer <preset>,
+ * /unipi:footer-settings.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { UNIPI_PREFIX, FOOTER_COMMANDS } from "@pi-unipi/core";
+import { loadFooterSettings, saveFooterSettings } from "./config.js";
+import { PRESET_NAMES } from "./presets.js";
+import { showFooterSettings } from "./tui/settings-tui.js";
+import type { FooterGroup, SeparatorStyle, IconStyle } from "./types.js";
+import { setIconStyle } from "./rendering/icons.js";
+
+/** Minimal autocomplete item (compatible with pi-tui AutocompleteItem) */
+interface ArgSuggestion {
+  value: string;
+  label: string;
+  description?: string;
+}
+
+/** All valid separator styles */
+const SEPARATOR_STYLES: SeparatorStyle[] = [
+  "powerline",
+  "powerline-thin",
+  "slash",
+  "pipe",
+  "dot",
+  "ascii",
+];
+
+/** All valid icon styles */
+const ICON_STYLES: IconStyle[] = [
+  "nerd",
+  "emoji",
+  "text",
+];
+
+/** Extension state interface */
+interface FooterState {
+  enabled: boolean;
+  renderer: {
+    setPreset(name: string): void;
+    setActive(active: boolean): void;
+    getPresetName(): string;
+    resetLayoutCache(): void;
+  };
+  piContext: unknown;
+}
+
+/**
+ * Register footer commands.
+ */
+export function registerCommands(
+  pi: ExtensionAPI,
+  state: FooterState,
+  groups?: FooterGroup[],
+): void {
+  // /unipi:footer — toggle or switch preset
+  pi.registerCommand(`${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER}`, {
+    description: "Toggle footer or switch preset (default, minimal, compact, full, nerd, ascii)",
+    getArgumentCompletions(argumentPrefix: string): ArgSuggestion[] | null {
+      const allOptions: ArgSuggestion[] = [
+        ...PRESET_NAMES.map(p => ({
+          value: p,
+          label: p,
+          description: `Switch to ${p} preset`,
+        })),
+        ...SEPARATOR_STYLES.map(s => ({
+          value: `sep:${s}`,
+          label: `sep:${s}`,
+          description: `Set separator style: ${s}`,
+        })),
+        ...ICON_STYLES.map(s => ({
+          value: `icon:${s}`,
+          label: `icon:${s}`,
+          description: `Set icon style: ${s}`,
+        })),
+        {
+          value: "on",
+          label: "on",
+          description: "Enable footer",
+        },
+        {
+          value: "off",
+          label: "off",
+          description: "Disable footer",
+        },
+      ];
+
+      if (!argumentPrefix) return allOptions;
+
+      const prefix = argumentPrefix.toLowerCase();
+      const filtered = allOptions.filter(o =>
+        o.value.toLowerCase().startsWith(prefix),
+      );
+      return filtered.length > 0 ? filtered : null;
+    },
+    handler: async (args, ctx) => {
+      if (!args?.trim()) {
+        // Toggle on/off
+        state.enabled = !state.enabled;
+        state.renderer.setActive(state.enabled);
+
+        if (state.enabled) {
+          ctx.ui.notify("Footer enabled", "info");
+        } else {
+          ctx.ui.setFooter(undefined);
+          ctx.ui.setWidget("footer-top", undefined);
+          ctx.ui.setWidget("footer-secondary", undefined);
+          ctx.ui.notify("Footer disabled", "info");
+        }
+
+        saveFooterSettings({ enabled: state.enabled });
+        return;
+      }
+
+      const arg = args.trim().toLowerCase();
+
+      // on / off
+      if (arg === "on") {
+        state.enabled = true;
+        state.renderer.setActive(true);
+        saveFooterSettings({ enabled: true });
+        ctx.ui.notify("Footer enabled", "info");
+        return;
+      }
+      if (arg === "off") {
+        state.enabled = false;
+        state.renderer.setActive(false);
+        ctx.ui.setFooter(undefined);
+        ctx.ui.setWidget("footer-top", undefined);
+        ctx.ui.setWidget("footer-secondary", undefined);
+        saveFooterSettings({ enabled: false });
+        ctx.ui.notify("Footer disabled", "info");
+        return;
+      }
+
+      // sep:<style> — change separator
+      if (arg.startsWith("sep:")) {
+        const style = arg.slice(4) as SeparatorStyle;
+        if (SEPARATOR_STYLES.includes(style)) {
+          saveFooterSettings({ separator: style });
+          state.renderer.resetLayoutCache();
+          ctx.ui.notify(`Separator: ${style}`, "info");
+          return;
+        }
+        ctx.ui.notify(`Unknown separator. Available: ${SEPARATOR_STYLES.join(", ")}`, "warning");
+        return;
+      }
+
+      // icon:<style> — change icon style
+      if (arg.startsWith("icon:")) {
+        const style = arg.slice(5) as IconStyle;
+        if (ICON_STYLES.includes(style)) {
+          saveFooterSettings({ iconStyle: style });
+          setIconStyle(style);
+          state.renderer.resetLayoutCache();
+          ctx.ui.notify(`Icon style: ${style}`, "info");
+          return;
+        }
+        ctx.ui.notify(`Unknown icon style. Available: ${ICON_STYLES.join(", ")}`, "warning");
+        return;
+      }
+
+      // Preset name
+      if (PRESET_NAMES.includes(arg)) {
+        state.renderer.setPreset(arg);
+        saveFooterSettings({ preset: arg });
+        ctx.ui.notify(`Footer preset: ${arg}`, "info");
+        return;
+      }
+
+      ctx.ui.notify(`Unknown argument. Use a preset (${PRESET_NAMES.join(", ")}), sep:<style>, icon:<style>, on, or off`, "info");
+    },
+  });
+
+  // /unipi:footer-settings — open settings TUI
+  pi.registerCommand(`${UNIPI_PREFIX}${FOOTER_COMMANDS.FOOTER_SETTINGS}`, {
+    description: "Open footer settings (toggle groups and segments)",
+    handler: async (_args, ctx) => {
+      if (!ctx.hasUI) {
+        ctx.ui.notify("Footer settings requires a TUI", "warning");
+        return;
+      }
+
+      if (groups && groups.length > 0) {
+        showFooterSettings(ctx, groups);
+      } else {
+        // Fallback: show text summary
+        const settings = loadFooterSettings();
+        const info = [
+          `Enabled: ${settings.enabled}`,
+          `Preset: ${state.renderer.getPresetName()}`,
+          `Separator: ${settings.separator}`,
+          `Icon: ${settings.iconStyle}`,
+          `Groups: ${Object.entries(settings.groups).filter(([, g]) => g.show).map(([id]) => id).join(", ")}`,
+        ].join("\n");
+        ctx.ui.notify(info, "info");
+      }
+    },
+  });
+}

package/src/config.ts

@@ -0,0 +1,177 @@
+/**
+ * @pi-unipi/footer — Configuration system
+ *
+ * Loads/saves footer settings from ~/.pi/agent/settings.json
+ * under the `unipi.footer` key.
+ */
+
+import * as fs from "node:fs";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { FooterSettings, FooterGroupSettings, SeparatorStyle, IconStyle } from "./types.js";
+import { UNIPI_SETTINGS_KEY } from "@pi-unipi/core";
+
+/** Default footer settings */
+export const DEFAULT_FOOTER_SETTINGS: FooterSettings = {
+  enabled: true,
+  preset: "default",
+  separator: "powerline-thin",
+  iconStyle: "nerd",
+  groups: {
+    core: { show: true, segments: {} },
+    compactor: { show: true, segments: {} },
+    memory: { show: true, segments: {} },
+    mcp: { show: true, segments: {} },
+    ralph: { show: true, segments: {} },
+    workflow: { show: true, segments: {} },
+    kanboard: { show: true, segments: {} },
+    notify: { show: false, segments: {} },
+    status_ext: { show: true, segments: {} },
+  },
+};
+
+/**
+ * Get the path to pi's settings.json
+ */
+function getSettingsPath(): string {
+  const agentDir = process.env.PI_AGENT_DIR || path.join(os.homedir(), ".pi", "agent");
+  return path.join(agentDir, "settings.json");
+}
+
+/**
+ * Read the raw settings.json file.
+ * Returns null if file doesn't exist or is malformed.
+ */
+function readSettingsFile(): Record<string, unknown> | null {
+  try {
+    const settingsPath = getSettingsPath();
+    if (!fs.existsSync(settingsPath)) return null;
+    const raw = fs.readFileSync(settingsPath, "utf-8");
+    return JSON.parse(raw) as Record<string, unknown>;
+  } catch (err) {
+    console.warn("[footer] Failed to read settings.json:", err);
+    return null;
+  }
+}
+
+/**
+ * Write settings back to settings.json.
+ */
+function writeSettingsFile(settings: Record<string, unknown>): boolean {
+  try {
+    const settingsPath = getSettingsPath();
+    const dir = path.dirname(settingsPath);
+    if (!fs.existsSync(dir)) {
+      fs.mkdirSync(dir, { recursive: true });
+    }
+    fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n", "utf-8");
+    return true;
+  } catch (err) {
+    console.warn("[footer] Failed to write settings.json:", err);
+    return false;
+  }
+}
+
+/**
+ * Load footer settings from settings.json.
+ * Falls back to defaults for any missing fields.
+ */
+export function loadFooterSettings(): FooterSettings {
+  const raw = readSettingsFile();
+  if (!raw) return { ...DEFAULT_FOOTER_SETTINGS };
+
+  try {
+    const unipi = raw[UNIPI_SETTINGS_KEY] as Record<string, unknown> | undefined;
+    if (!unipi) return { ...DEFAULT_FOOTER_SETTINGS };
+
+    const footer = unipi.footer as Record<string, unknown> | undefined;
+    if (!footer) return { ...DEFAULT_FOOTER_SETTINGS };
+
+    return {
+      enabled: typeof footer.enabled === "boolean" ? footer.enabled : DEFAULT_FOOTER_SETTINGS.enabled,
+      preset: typeof footer.preset === "string" ? footer.preset : DEFAULT_FOOTER_SETTINGS.preset,
+      separator: isValidSeparator(footer.separator) ? footer.separator as SeparatorStyle : DEFAULT_FOOTER_SETTINGS.separator,
+      iconStyle: isValidIconStyle(footer.iconStyle) ? footer.iconStyle as IconStyle : DEFAULT_FOOTER_SETTINGS.iconStyle,
+      groups: mergeGroupSettings(
+        DEFAULT_FOOTER_SETTINGS.groups,
+        footer.groups as Record<string, FooterGroupSettings> | undefined,
+      ),
+    };
+  } catch (err) {
+    console.warn("[footer] Failed to parse footer settings, using defaults:", err);
+    return { ...DEFAULT_FOOTER_SETTINGS };
+  }
+}
+
+/**
+ * Save footer settings to settings.json.
+ * Merges with existing settings (preserves other keys).
+ */
+export function saveFooterSettings(partial: Partial<FooterSettings>): boolean {
+  const raw = readSettingsFile() ?? {};
+  const unipi = (raw[UNIPI_SETTINGS_KEY] as Record<string, unknown>) ?? {};
+  const existing = (unipi.footer as Record<string, unknown>) ?? {};
+
+  unipi.footer = { ...existing, ...partial };
+  raw[UNIPI_SETTINGS_KEY] = unipi;
+
+  return writeSettingsFile(raw);
+}
+
+/**
+ * Get settings for a specific group.
+ * Falls back to defaults if group not configured.
+ */
+export function getGroupSettings(groupId: string): FooterGroupSettings {
+  const settings = loadFooterSettings();
+  return settings.groups[groupId] ?? { show: true, segments: {} };
+}
+
+/**
+ * Check if a specific segment is enabled.
+ * Respects both group-level and segment-level settings.
+ */
+export function isSegmentEnabled(groupId: string, segmentId: string): boolean {
+  const groupSettings = getGroupSettings(groupId);
+  if (!groupSettings.show) return false;
+  if (groupSettings.segments && segmentId in groupSettings.segments) {
+    return groupSettings.segments[segmentId] ?? true;
+  }
+  return true;
+}
+
+// ─── Helpers ────────────────────────────────────────────────────────────────
+
+function isValidSeparator(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const valid: string[] = ["powerline", "powerline-thin", "slash", "pipe", "dot", "ascii"];
+  return valid.includes(value);
+}
+
+function isValidIconStyle(value: unknown): boolean {
+  if (typeof value !== "string") return false;
+  const valid: string[] = ["nerd", "emoji", "text"];
+  return valid.includes(value);
+}
+
+function mergeGroupSettings(
+  defaults: Record<string, FooterGroupSettings>,
+  overrides: Record<string, FooterGroupSettings> | undefined,
+): Record<string, FooterGroupSettings> {
+  const result: Record<string, FooterGroupSettings> = { ...defaults };
+
+  if (!overrides) return result;
+
+  for (const [groupId, groupOverride] of Object.entries(overrides)) {
+    const defaultGroup = result[groupId] ?? { show: true, segments: {} };
+    result[groupId] = {
+      show: typeof groupOverride.show === "boolean" ? groupOverride.show : defaultGroup.show,
+      segments: {
+        ...defaultGroup.segments,
+        ...(groupOverride.segments ?? {}),
+      },
+    };
+  }
+
+  return result;
+}