@pi-unipi/utility 0.1.1 → 0.2.1

package/src/index.ts

@@ -0,0 +1,172 @@
+/**
+ * @pi-unipi/utility — Extension entry
+ *
+ * Comprehensive utilities suite for Pi coding agent:
+ * - Commands: continue, reload, status, cleanup, env, doctor
+ * - Tools: ctx_batch, ctx_env
+ * - Lifecycle: process management, stale cleanup
+ * - Cache: TTL cache with optional persistence
+ * - Analytics: lightweight event collection
+ * - Diagnostics: cross-module health checks
+ * - Display: terminal capabilities, width utilities
+ * - TUI: settings inspector pattern
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  UTILITY_COMMANDS,
+  UTILITY_TOOLS,
+  emitEvent,
+  getPackageVersion,
+} from "@pi-unipi/core";
+import { registerUtilityCommands } from "./commands.js";
+import { getLifecycle } from "./lifecycle/process.js";
+import { getAnalyticsCollector } from "./analytics/collector.js";
+import { registerInfoScreen } from "./info-screen.js";
+
+/** Package version */
+const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
+
+/** All commands registered by this module */
+const ALL_COMMANDS = [
+  UTILITY_COMMANDS.CONTINUE,
+  UTILITY_COMMANDS.RELOAD,
+  UTILITY_COMMANDS.STATUS,
+  UTILITY_COMMANDS.CLEANUP,
+  UTILITY_COMMANDS.ENV,
+  UTILITY_COMMANDS.DOCTOR,
+].map((cmd) => `unipi:${cmd}`);
+
+/** All tools registered by this module */
+const ALL_TOOLS = [UTILITY_TOOLS.BATCH, UTILITY_TOOLS.ENV];
+
+export default function (pi: ExtensionAPI) {
+  // Initialize lifecycle manager
+  const lifecycle = getLifecycle();
+
+  // Initialize analytics collector
+  const analytics = getAnalyticsCollector();
+
+  // Register cleanup on shutdown
+  lifecycle.registerCleanup(async () => {
+    analytics.disable();
+  });
+
+  // Register commands
+  registerUtilityCommands(pi);
+
+  // Register tools
+  registerUtilityTools(pi);
+
+  // Register info-screen group
+  registerInfoScreen(pi);
+
+  // Session lifecycle — announce module
+  pi.on("session_start", async () => {
+    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
+      name: MODULES.UTILITY,
+      version: VERSION,
+      commands: ALL_COMMANDS,
+      tools: ALL_TOOLS,
+    });
+
+    analytics.recordModuleLoad(MODULES.UTILITY, VERSION);
+  });
+
+  // Track command usage
+  pi.on("tool_call", async (event) => {
+    if (event.toolName.startsWith("unipi:")) {
+      analytics.recordCommand(event.toolName, MODULES.UTILITY, 0, true);
+    }
+  });
+
+  // Session shutdown cleanup
+  pi.on("session_shutdown", async () => {
+    await lifecycle.shutdown("session_shutdown");
+  });
+}
+
+/**
+ * Register utility tools.
+ */
+function registerUtilityTools(pi: ExtensionAPI): void {
+  // ctx_batch — atomic batch execution
+  pi.registerTool({
+    name: UTILITY_TOOLS.BATCH,
+    label: "Batch Execute",
+    description:
+      "Execute a batch of commands atomically with rollback support. " +
+      "Accepts an array of {type, name, args} objects. " +
+      "Options: failFast (default true), commandTimeoutMs, totalTimeoutMs.",
+    promptSnippet: "Run multiple commands as an atomic batch.",
+    parameters: {
+      type: "object",
+      properties: {
+        commands: {
+          type: "array",
+          items: {
+            type: "object",
+            properties: {
+              type: { type: "string", enum: ["command", "tool", "search"] },
+              name: { type: "string" },
+              args: { type: "object" },
+            },
+            required: ["type", "name"],
+          },
+        },
+        options: {
+          type: "object",
+          properties: {
+            failFast: { type: "boolean" },
+            commandTimeoutMs: { type: "number" },
+            totalTimeoutMs: { type: "number" },
+          },
+        },
+      },
+      required: ["commands"],
+    },
+    async execute(_toolCallId, params) {
+      const { commands, options } = params as unknown as {
+        commands: Array<{ type: string; name: string; args?: Record<string, unknown> }>;
+        options?: Record<string, unknown>;
+      };
+
+      // Tool implementation delegates to batch executor
+      // The actual executor must be provided by the host
+      return {
+        content: [
+          {
+            type: "text",
+            text:
+              "ctx_batch requires a command executor from the host environment. " +
+              `Received ${commands.length} commands. ` +
+              "Use BatchBuilder or executeBatch() directly in code.",
+          },
+        ],
+        details: { commands, options },
+      };
+    },
+  });
+
+  // ctx_env — environment info
+  pi.registerTool({
+    name: UTILITY_TOOLS.ENV,
+    label: "Environment Info",
+    description: "Show environment information: Node version, Pi version, OS, unipi modules, config paths.",
+    promptSnippet: "Get environment details for debugging.",
+    parameters: {
+      type: "object",
+      properties: {},
+    },
+    async execute() {
+      const { getEnvironmentInfo, formatEnvironmentInfo } = await import("./tools/env.js");
+      const info = getEnvironmentInfo();
+      return {
+        content: [{ type: "text", text: formatEnvironmentInfo(info) }],
+        details: info,
+      };
+    },
+  });
+}

package/src/info-screen.ts

@@ -0,0 +1,80 @@
+/**
+ * @pi-unipi/utility — Info-Screen Integration
+ *
+ * Registers utility stats group for the info-screen overlay.
+ */
+
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import {
+  UNIPI_EVENTS,
+  MODULES,
+  emitEvent,
+} from "@pi-unipi/core";
+import { getLifecycle } from "./lifecycle/process.js";
+import { getAnalyticsCollector } from "./analytics/collector.js";
+
+/** Info group ID */
+const GROUP_ID = "utility";
+
+/** Info group display name */
+const GROUP_NAME = "Utility";
+
+/**
+ * Register the utility info-screen group.
+ */
+export function registerInfoScreen(pi: ExtensionAPI): void {
+  // Announce group registration
+  emitEvent(pi, UNIPI_EVENTS.INFO_GROUP_REGISTERED, {
+    groupId: GROUP_ID,
+    groupName: GROUP_NAME,
+    module: MODULES.UTILITY,
+  });
+
+  // Listen for status requests
+  pi.on("session_start", async () => {
+    // Module is ready — data will be served on demand
+  });
+}
+
+/**
+ * Get current utility stats for info-screen display.
+ */
+export function getUtilityStats(): Record<string, unknown> {
+  const lifecycle = getLifecycle();
+  const analytics = getAnalyticsCollector();
+
+  const events = analytics.getEvents();
+  const rollup = analytics.getRollup();
+
+  return {
+    uptime: process.uptime(),
+    state: lifecycle.currentState,
+    isOrphaned: lifecycle.isOrphaned,
+    eventsToday: Object.values(rollup.events).reduce((a, b) => a + b, 0),
+    errorsToday: rollup.errorCount,
+    totalEvents: events.length,
+    nodeVersion: process.version,
+    platform: process.platform,
+  };
+}
+
+/**
+ * Format utility stats as markdown for display.
+ */
+export function formatUtilityStats(stats: Record<string, unknown>): string {
+  const lines = [
+    `**State:** ${stats.state}`,
+    `**Uptime:** ${Math.round((stats.uptime as number) / 60)}m`,
+    `**Events today:** ${stats.eventsToday}`,
+    `**Errors today:** ${stats.errorsToday}`,
+    `**Total events:** ${stats.totalEvents}`,
+    `**Node:** ${stats.nodeVersion}`,
+    `**Platform:** ${stats.platform}`,
+  ];
+
+  if (stats.isOrphaned) {
+    lines.push("⚠️ **Orphaned process detected**");
+  }
+
+  return lines.join("\n");
+}

package/src/lifecycle/cleanup.ts

@@ -0,0 +1,332 @@
+/**
+ * @pi-unipi/utility — Stale Cleanup Utility
+ *
+ * Cleans stale DBs, temp files, old sessions across all unipi modules.
+ */
+
+import { existsSync, statSync, readdirSync, unlinkSync, rmdirSync } from "node:fs";
+import { join, resolve, basename } from "node:path";
+import { homedir, tmpdir } from "node:os";
+import type { CleanupReport, CleanupResult, CleanupOptions } from "../types.js";
+
+/** Default options */
+const DEFAULTS: Required<CleanupOptions> = {
+  dbMaxAgeDays: 14,
+  tempMaxAgeDays: 7,
+  sessionMaxAgeDays: 30,
+  dryRun: false,
+};
+
+/** Expand ~ to home directory */
+function expandHome(path: string): string {
+  if (path.startsWith("~/")) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+/** Check if a file is older than maxAgeDays */
+function isStale(path: string, maxAgeDays: number): boolean {
+  try {
+    const stats = statSync(path);
+    const ageMs = Date.now() - stats.mtime.getTime();
+    return ageMs > maxAgeDays * 24 * 60 * 60 * 1000;
+  } catch {
+    return false;
+  }
+}
+
+/** Try to detect if a DB file has a zombie WAL lock */
+function hasWalLock(dbPath: string): boolean {
+  const walPath = dbPath + "-wal";
+  const shmPath = dbPath + "-shm";
+  // If WAL exists but journal mode isn't WAL, or WAL is very old, it's stale
+  if (existsSync(walPath)) {
+    try {
+      const walStats = statSync(walPath);
+      const ageMs = Date.now() - walStats.mtime.getTime();
+      return ageMs > 5 * 60 * 1000; // 5 min = stale WAL
+    } catch {
+      return false;
+    }
+  }
+  return false;
+}
+
+/** Clean stale database files in ~/.unipi/ */
+function cleanDbs(options: Required<CleanupOptions>): CleanupResult {
+  const result: CleanupResult = {
+    category: "db",
+    removed: 0,
+    bytesFreed: 0,
+    paths: [],
+  };
+
+  const unipiDir = expandHome("~/.unipi");
+  if (!existsSync(unipiDir)) return result;
+
+  const scanDir = (dir: string) => {
+    let entries: string[];
+    try {
+      entries = readdirSync(dir);
+    } catch {
+      return;
+    }
+
+    for (const entry of entries) {
+      const fullPath = join(dir, entry);
+      try {
+        const stats = statSync(fullPath);
+        if (stats.isDirectory()) {
+          scanDir(fullPath);
+          continue;
+        }
+
+        // Match SQLite DB files
+        if (
+          entry.endsWith(".db") ||
+          entry.endsWith(".sqlite") ||
+          entry.endsWith(".sqlite3")
+        ) {
+          if (isStale(fullPath, options.dbMaxAgeDays) || hasWalLock(fullPath)) {
+            result.bytesFreed += stats.size;
+            result.paths.push(fullPath);
+            if (!options.dryRun) {
+              try {
+                unlinkSync(fullPath);
+                // Also clean WAL/SHM companions
+                for (const suffix of ["-wal", "-shm", "-journal"]) {
+                  const companion = fullPath + suffix;
+                  if (existsSync(companion)) {
+                    unlinkSync(companion);
+                    result.bytesFreed += statSync(companion).size;
+                  }
+                }
+                result.removed++;
+              } catch {
+                // Best effort
+              }
+            } else {
+              result.removed++;
+            }
+          }
+        }
+      } catch {
+        // Skip unreadable entries
+      }
+    }
+  };
+
+  scanDir(unipiDir);
+  return result;
+}
+
+/** Clean temp files matching unipi patterns */
+function cleanTemps(options: Required<CleanupOptions>): CleanupResult {
+  const result: CleanupResult = {
+    category: "temp",
+    removed: 0,
+    bytesFreed: 0,
+    paths: [],
+  };
+
+  const patterns = [/^unipi-/, /^pi-/, /\.unipi\./];
+  const tmpDir = tmpdir();
+
+  let entries: string[];
+  try {
+    entries = readdirSync(tmpDir);
+  } catch {
+    return result;
+  }
+
+  for (const entry of entries) {
+    if (!patterns.some((p) => p.test(entry))) continue;
+
+    const fullPath = join(tmpDir, entry);
+    try {
+      const stats = statSync(fullPath);
+      if (!stats.isFile()) continue;
+
+      if (isStale(fullPath, options.tempMaxAgeDays)) {
+        result.bytesFreed += stats.size;
+        result.paths.push(fullPath);
+        if (!options.dryRun) {
+          try {
+            unlinkSync(fullPath);
+            result.removed++;
+          } catch {
+            // Best effort
+          }
+        } else {
+          result.removed++;
+        }
+      }
+    } catch {
+      // Skip unreadable
+    }
+  }
+
+  return result;
+}
+
+/** Clean stale session directories */
+function cleanSessions(options: Required<CleanupOptions>): CleanupResult {
+  const result: CleanupResult = {
+    category: "session",
+    removed: 0,
+    bytesFreed: 0,
+    paths: [],
+  };
+
+  const unipiDir = expandHome("~/.unipi");
+  const sessionsDir = join(unipiDir, "sessions");
+  if (!existsSync(sessionsDir)) return result;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(sessionsDir);
+  } catch {
+    return result;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(sessionsDir, entry);
+    try {
+      const stats = statSync(fullPath);
+      if (!stats.isDirectory()) continue;
+
+      if (isStale(fullPath, options.sessionMaxAgeDays)) {
+        result.bytesFreed += stats.size;
+        result.paths.push(fullPath);
+        if (!options.dryRun) {
+          try {
+            // Remove directory contents then directory
+            const removeRecursive = (dir: string) => {
+              const items = readdirSync(dir);
+              for (const item of items) {
+                const itemPath = join(dir, item);
+                const itemStats = statSync(itemPath);
+                if (itemStats.isDirectory()) {
+                  removeRecursive(itemPath);
+                } else {
+                  unlinkSync(itemPath);
+                }
+              }
+              rmdirSync(dir);
+            };
+            removeRecursive(fullPath);
+            result.removed++;
+          } catch {
+            // Best effort
+          }
+        } else {
+          result.removed++;
+        }
+      }
+    } catch {
+      // Skip unreadable
+    }
+  }
+
+  return result;
+}
+
+/** Clean stale cache files */
+function cleanCache(options: Required<CleanupOptions>): CleanupResult {
+  const result: CleanupResult = {
+    category: "cache",
+    removed: 0,
+    bytesFreed: 0,
+    paths: [],
+  };
+
+  const cacheDir = expandHome("~/.unipi/cache");
+  if (!existsSync(cacheDir)) return result;
+
+  let entries: string[];
+  try {
+    entries = readdirSync(cacheDir);
+  } catch {
+    return result;
+  }
+
+  for (const entry of entries) {
+    const fullPath = join(cacheDir, entry);
+    try {
+      const stats = statSync(fullPath);
+      if (!stats.isFile()) continue;
+
+      if (isStale(fullPath, options.tempMaxAgeDays)) {
+        result.bytesFreed += stats.size;
+        result.paths.push(fullPath);
+        if (!options.dryRun) {
+          try {
+            unlinkSync(fullPath);
+            result.removed++;
+          } catch {
+            // Best effort
+          }
+        } else {
+          result.removed++;
+        }
+      }
+    } catch {
+      // Skip unreadable
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Run full cleanup of stale files across all unipi modules.
+ */
+export function cleanupStale(options: CleanupOptions = {}): CleanupReport {
+  const opts: Required<CleanupOptions> = { ...DEFAULTS, ...options };
+
+  const results: CleanupResult[] = [
+    cleanDbs(opts),
+    cleanTemps(opts),
+    cleanSessions(opts),
+    cleanCache(opts),
+  ];
+
+  return {
+    timestamp: Date.now(),
+    results,
+    totalRemoved: results.reduce((sum, r) => sum + r.removed, 0),
+    totalBytesFreed: results.reduce((sum, r) => sum + r.bytesFreed, 0),
+  };
+}
+
+/** Format a cleanup report as markdown */
+export function formatCleanupReport(report: CleanupReport): string {
+  const lines = [
+    "## 🧹 Cleanup Report",
+    "",
+    `**Total removed:** ${report.totalRemoved} items`,
+    `**Space freed:** ${(report.totalBytesFreed / 1024 / 1024).toFixed(2)} MB`,
+    `**Timestamp:** ${new Date(report.timestamp).toISOString()}`,
+    "",
+  ];
+
+  for (const result of report.results) {
+    if (result.removed === 0) continue;
+    lines.push(
+      `### ${result.category.toUpperCase()}`,
+      `- Removed: ${result.removed}`,
+      `- Freed: ${(result.bytesFreed / 1024).toFixed(1)} KB`,
+      "",
+    );
+    for (const path of result.paths.slice(0, 10)) {
+      lines.push(`- \`${path}\``);
+    }
+    if (result.paths.length > 10) {
+      lines.push(`- ... and ${result.paths.length - 10} more`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n");
+}