@pi-unipi/utility 0.2.8 → 2.0.0

package/README.md

@@ -1,94 +1,68 @@
 # @pi-unipi/utility
 
-Comprehensive utility suite for the Pi coding agent — part of the Unipi extension suite.
+Environment info, diagnostics, cleanup, name badge, and diff rendering. The grab-bag package for maintaining your development environment and making tool output readable.
 
-## Features
+The diff rendering is the standout feature — Shiki-powered syntax-highlighted diffs for `write` and `edit` tool output. Side-by-side view for edits, unified view for writes, with color presets and auto-fallback on narrow terminals.
 
-### Commands
+## Commands
 
 | Command | Description |
 |---------|-------------|
-| `/unipi:continue` | Continue agent without polluting context |
-| `/unipi:reload` | Explain how to reload extensions |
-| `/unipi:status` | Show status of all unipi modules |
-| `/unipi:cleanup` | Clean stale DBs, temp files, old sessions |
 | `/unipi:env` | Show environment info (Node, Pi, OS, paths) |
 | `/unipi:doctor` | Run diagnostics across all modules |
-| `/unipi:name-badge` | Toggle name badge overlay (shows session name) |
+| `/unipi:status` | Show status of all unipi modules |
+| `/unipi:cleanup` | Clean stale DBs, temp files, old sessions |
+| `/unipi:reload` | Explain how to reload extensions |
+| `/unipi:name-badge` | Toggle name badge overlay |
 | `/unipi:badge-gen` | Generate session name via LLM and enable badge |
-| `/unipi:util-settings` | **Unified settings** — badge + diff rendering config |
-| `/unipi:badge-settings` | Settings overlay (deprecated alias for `/unipi:util-settings`) |
+| `/unipi:util-settings` | Unified settings for badge and diff rendering |
 
-### Tools
+### Examples
 
-| Tool | Description |
-|------|-------------|
-| `ctx_batch` | Atomic batch execution with rollback support |
-| `ctx_env` | Environment inspection for debugging |
-| `write` | Write file with **syntax-highlighted diff** (when diff enabled) |
-| `edit` | Edit file with **split/unified diff view** (when diff enabled) |
+```
+/unipi:env                 # Show environment
+/unipi:doctor              # Run diagnostics
+/unipi:cleanup             # Clean stale files
+/unipi:cleanup --dry-run   # Preview what would be cleaned
+/unipi:name-badge          # Toggle the session name badge
+/unipi:badge-gen           # Generate a session name via LLM
+```
 
-### Modules (Programmatic API)
+## Special Triggers
 
-| Module | Path | Description |
-|--------|------|-------------|
-| **ProcessLifecycle** | `lifecycle/process` | Parent PID polling, orphan detection, signal handlers, cleanup registry |
-| **cleanupStale** | `lifecycle/cleanup` | Stale DB/temp/session/cache cleanup with dry-run support |
-| **TTLCache** | `cache/ttl-cache` | Memory or SQLite-backed TTL cache with auto-expiration |
-| **AnalyticsCollector** | `analytics/collector` | Privacy-respecting event collection with daily rollup |
-| **runDiagnostics** | `diagnostics/engine` | Cross-module health checks with plugin architecture |
-| **detectCapabilities** | `display/capabilities` | Terminal feature detection (color, Nerd Font, unicode) |
-| **Width Utilities** | `display/width` | ANSI-aware clamp, wrap, collapse, pad, center |
-| **SettingsInspector** | `tui/settings-inspector` | Reusable settings overlay data model |
-
-## Installation
-
-```bash
-pi install npm:@pi-unipi/utility
-```
+Utility registers with the info-screen dashboard, showing module status and diagnostic results. The footer subscribes to utility events for its extension status segment.
 
-Or install the full Unipi suite:
+The diff rendering feature wraps Pi's built-in `write` and `edit` tools. When enabled, these tools show syntax-highlighted diffs instead of plain output. This is a transparent replacement — the agent doesn't need to know about it.
 
-```bash
-pi install npm:@pi-unipi/unipi
-```
+## Agent Tools
 
-## Usage
+| Tool | Description |
+|------|-------------|
+| `ctx_batch` | Atomic batch execution with rollback support |
+| `ctx_env` | Environment inspection for debugging |
+| `write` | Write file with syntax-highlighted diff (when diff enabled) |
+| `edit` | Edit file with split/unified diff view (when diff enabled) |
 
-### Commands
+### Batch Execution
 
-```
-/unipi:continue           # Resume agent cleanly
-/unipi:cleanup             # Clean stale files
-/unipi:cleanup --dry-run   # Preview what would be cleaned
-/unipi:env                 # Show environment
-/unipi:doctor              # Run diagnostics
-```
+```typescript
+import { BatchBuilder } from "@pi-unipi/utility/tools/batch";
 
-### Name Badge
+const report = await new BatchBuilder()
+  .addCommand("search", { query: "refactor" })
+  .addTool("memory_search", { query: "patterns" })
+  .withOptions({ failFast: true, commandTimeoutMs: 30000 })
+  .execute(myExecutor);
 
-```
-/unipi:name-badge          # Toggle the session name badge on/off
-/unipi:badge-gen           # Generate a session name via LLM
+if (!report.success) {
+  console.log("Failed:", report.results.find(r => !r.success)?.error);
+}
 ```
 
-The badge is a persistent HUD overlay in the top-right corner showing the current session name.
-It auto-restores visibility on session restart.
+## Configurables
 
 ### Diff Rendering
 
-Shiki-powered, syntax-highlighted diffs for `write` and `edit` tool output. When enabled, the default tools are replaced with enhanced versions that show side-by-side or stacked diffs with syntax highlighting.
-
-**Features:**
-- Split view (side-by-side) for `edit` tool, auto-falls back to unified on narrow terminals
-- Unified view (stacked single-column) for `write` tool overwrites
-- 4 color presets: default, midnight, subtle, neon
-- LRU cache (192 entries) for Shiki highlights
-- Large diff fallback (skip highlighting above 80k chars)
-- Environment variable color overrides (`DIFF_ADD_BG`, `DIFF_REM_BG`, etc.)
-
-**Configuration:**
-
 ```
 /unipi:util-settings        # Open unified settings TUI
 ```
@@ -106,26 +80,38 @@ Or edit `.unipi/config/util-settings.json` directly:
 }
 ```
 
-**Diff themes:** default, midnight, subtle, neon
-**Shiki themes:** github-dark, dracula, one-dark-pro, catppuccin-mocha, nord, tokyo-night, and more
+| Setting | Default | Options |
+|---------|---------|---------|
+| `enabled` | true | true/false |
+| `theme` | "default" | default, midnight, subtle, neon |
+| `shikiTheme` | "github-dark" | github-dark, dracula, one-dark-pro, catppuccin-mocha, nord, tokyo-night |
+| `splitMinWidth` | 150 | Minimum terminal width for split view |
 
-### Batch Execution (Code)
+Environment variable overrides: `DIFF_ADD_BG`, `DIFF_REM_BG`, etc.
 
-```typescript
-import { BatchBuilder } from "@pi-unipi/utility/tools/batch";
+Features:
+- Split view (side-by-side) for `edit`, auto-falls back to unified on narrow terminals
+- Unified view (stacked) for `write` overwrites
+- LRU cache (192 entries) for Shiki highlights
+- Large diff fallback (skip highlighting above 80k chars)
 
-const report = await new BatchBuilder()
-  .addCommand("search", { query: "refactor" })
-  .addTool("memory_search", { query: "patterns" })
-  .withOptions({ failFast: true, commandTimeoutMs: 30000 })
-  .execute(myExecutor);
+### Name Badge
 
-if (!report.success) {
-  console.log("Failed:", report.results.find(r => !r.success)?.error);
-}
-```
+The badge is a persistent HUD overlay in the top-right corner showing the current session name. It auto-restores visibility on session restart.
+
+## Programmatic API
+
+| Module | Path | Description |
+|--------|------|-------------|
+| ProcessLifecycle | `lifecycle/process` | Parent PID polling, orphan detection, signal handlers |
+| cleanupStale | `lifecycle/cleanup` | Stale DB/temp/session/cache cleanup with dry-run |
+| TTLCache | `cache/ttl-cache` | Memory or SQLite-backed TTL cache |
+| AnalyticsCollector | `analytics/collector` | Privacy-respecting event collection with daily rollup |
+| runDiagnostics | `diagnostics/engine` | Cross-module health checks with plugin architecture |
+| detectCapabilities | `display/capabilities` | Terminal feature detection (color, Nerd Font, unicode) |
+| Width Utilities | `display/width` | ANSI-aware clamp, wrap, collapse, pad, center |
 
-### TTL Cache (Code)
+### TTL Cache
 
 ```typescript
 import { TTLCache } from "@pi-unipi/utility/cache/ttl-cache";
@@ -135,16 +121,7 @@ await cache.set("key", { data: "value" });
 const value = await cache.get("key");
 ```
 
-### Diagnostics (Code)
-
-```typescript
-import { runDiagnostics, formatDiagnosticsReport } from "@pi-unipi/utility/diagnostics/engine";
-
-const report = await runDiagnostics();
-console.log(formatDiagnosticsReport(report));
-```
-
-### Terminal Capabilities (Code)
+### Terminal Capabilities
 
 ```typescript
 import { detectCapabilities, getIcon } from "@pi-unipi/utility/display/capabilities";
@@ -154,64 +131,13 @@ console.log("Nerd Font:", caps.nerdFont);
 console.log(getIcon("󰘳", "[OK]")); // Uses Nerd Font if available
 ```
 
-## Architecture
-
-```
-packages/utility/src/
-├── index.ts              # Extension entry point
-├── commands.ts           # Command registration
-├── types.ts              # Shared types
-├── info-screen.ts        # Info-screen integration
-├── lifecycle/
-│   ├── process.ts        # Process lifecycle manager
-│   └── cleanup.ts        # Stale cleanup utility
-├── cache/
-│   └── ttl-cache.ts      # TTL cache (memory + SQLite)
-├── analytics/
-│   └── collector.ts      # Event collection + rollup
-├── diagnostics/
-│   └── engine.ts         # Health check engine
-├── display/
-│   ├── capabilities.ts   # Terminal detection
-│   └── width.ts          # Width utilities
-├── diff/
-│   ├── settings.ts       # Unified settings (badge + diff) read/write + migration
-│   ├── theme.ts          # Diff color presets, resolution chain, hex ↔ ANSI
-│   ├── parser.ts         # Diff parsing (structuredPatch, word diff analysis)
-│   ├── highlighter.ts    # Shiki singleton, LRU cache, language detection
-│   ├── renderer.ts       # Split/unified renderers, ANSI utilities
-│   └── wrapper.ts        # write/edit tool wrapping with diff output
-├── tui/
-│   ├── settings-inspector.ts  # Settings overlay model
-│   ├── name-badge.ts          # Name badge overlay component
-│   ├── name-badge-state.ts    # Name badge state manager
-│   ├── badge-settings.ts      # Badge settings (thin wrapper over diff/settings)
-│   └── util-settings-tui.ts  # Unified settings TUI (badge + diff)
-└── tools/
-    ├── batch.ts          # Batch execution
-    └── env.ts            # Environment info
-```
-
 ## Privacy
 
-The analytics collector is **privacy-respecting** by design:
-- No file contents are recorded
+The analytics collector is privacy-respecting:
+- No file contents recorded
 - No sensitive data (API keys, tokens, passwords) — redacted automatically
 - Strings truncated to 500 characters
-- All data stays local (in-memory by default, optional SQLite)
-
-## Dependencies
-
-- `@pi-unipi/core` — Shared constants, events, utilities
-- `@mariozechner/pi-coding-agent` — Pi extension API
-- `@sinclair/typebox` — Schema validation (peer dependency)
-- `diff` — Unified diff generation (for diff rendering)
-- `@shikijs/cli` — Shiki syntax highlighting (for diff rendering)
-- `sqlite3` — Optional, for persistent cache/analytics
-
-### Dev Dependencies
-
-- `@types/diff` — TypeScript types for the diff library
+- All data stays local
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pi-unipi/utility",
-  "version": "0.2.8",
+  "version": "2.0.0",
   "description": "Utility commands and tools for Pi coding agent — lifecycle, diagnostics, cache, analytics, display, batch execution",
   "type": "module",
   "license": "MIT",

package/src/commands.ts

@@ -109,7 +109,7 @@ export function registerNameBadgeCommands(
 
       // Redirect to unified settings
       ctx.ui.custom(
-        (tui: any, _theme: any, _keybindings: any, done: any) => {
+        (tui, _theme, _keybindings, done) => {
           const overlay = new UtilSettingsTui();
           overlay.onClose = () => done(undefined);
           overlay.requestRender = () => tui.requestRender();
@@ -145,7 +145,7 @@ export function registerNameBadgeCommands(
       }
 
       ctx.ui.custom(
-        (tui: any, _theme: any, _keybindings: any, done: any) => {
+        (tui, _theme, _keybindings, done) => {
           const overlay = new UtilSettingsTui();
           overlay.onClose = () => done(undefined);
           overlay.requestRender = () => tui.requestRender();

package/src/diff/highlighter.ts

@@ -249,7 +249,7 @@ export function normalizeShikiContrast(
 // ─── Shiki Highlighter ──────────────────────────────────────────────────────────
 
 /** Shiki highlighter instance (lazy singleton) */
-let shikiHighlighter: any = null;
+let shikiHighlighter: import("shiki").Highlighter | null = null;
 let shikiInitPromise: Promise<any> | null = null;
 
 /**

package/src/index.ts

@@ -12,7 +12,7 @@
  * - TUI: settings inspector pattern, name badge
  */
 
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ExtensionAPI, InputEvent, AgentEndEvent } from "@mariozechner/pi-coding-agent";
 import {
   UNIPI_EVENTS,
   MODULES,
@@ -44,7 +44,7 @@ let firstMessageSeen = false;
 let firstUserText = "";
 
 /** Stored UI context from first input, used to show badge overlay after agent responds */
-let firstInputCtx: any = null;
+let firstInputCtx: import("@mariozechner/pi-coding-agent").ExtensionContext | null = null;
 
 /** All commands registered by this module */
 const ALL_COMMANDS = [
@@ -124,7 +124,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   // First-message hook: capture user text for deferred badge generation
-  pi.on("input", async (_event: any, ctx: any) => {
+  pi.on("input", async (_event, ctx) => {
     // Only trigger on first user message
     if (firstMessageSeen) return;
     firstMessageSeen = true;
@@ -138,12 +138,14 @@ export default function (pi: ExtensionAPI) {
     if (sessionName) return;
 
     // Store first message text for later use in agent_end
-    firstUserText = typeof _event?.content === "string"
-      ? _event.content
-      : Array.isArray(_event?.content)
-        ? _event.content
-            .filter((c: any) => c.type === "text")
-            .map((c: any) => c.text)
+    // Note: InputEvent.text is the documented property; content may exist at runtime
+    const content = (_event as unknown as Record<string, unknown>).content;
+    firstUserText = typeof content === "string"
+      ? content
+      : Array.isArray(content)
+        ? (content as Array<Record<string, unknown>>)
+            .filter((c) => c.type === "text")
+            .map((c) => String(c.text))
             .join(" ")
         : "";
 
@@ -152,7 +154,7 @@ export default function (pi: ExtensionAPI) {
   });
 
   // After agent completes first response, generate badge name with full conversation context
-  pi.on("agent_end", async (event: any, _ctx: any) => {
+  pi.on("agent_end", async (event, _ctx) => {
     // Only act if we captured a first input and are waiting for badge generation
     if (!firstInputCtx) return;
     const ctx = firstInputCtx;
@@ -168,7 +170,7 @@ export default function (pi: ExtensionAPI) {
     }
 
     // Build conversation summary from full message history (user + assistant)
-    const messages: any[] = event?.messages ?? [];
+    const messages = event.messages;
     const summaryParts: string[] = [];
 
     // Include the user's first message
@@ -177,16 +179,17 @@ export default function (pi: ExtensionAPI) {
     }
 
     // Include assistant's response text
-    const assistantMsgs = messages.filter((m: any) => m.role === "assistant");
+    const assistantMsgs = messages.filter((m) => m.role === "assistant");
     for (const msg of assistantMsgs) {
-      if (Array.isArray(msg.content)) {
-        const textParts = msg.content
-          .filter((c: any) => c.type === "text")
-          .map((c: any) => c.text)
+      const content = msg.content;
+      if (Array.isArray(content)) {
+        const textParts = content
+          .filter((c): c is { type: "text"; text: string } => "text" in c && c.type === "text")
+          .map((c) => c.text)
           .join(" ");
         if (textParts) summaryParts.push(`Assistant: ${textParts}`);
-      } else if (typeof msg.content === "string" && msg.content) {
-        summaryParts.push(`Assistant: ${msg.content}`);
+      } else if (typeof content === "string" && content) {
+        summaryParts.push(`Assistant: ${content}`);
       }
     }