@pi-unipi/unipi 3.0.0-alpha.2 → 3.0.0-alpha.21

package/packages/utility/src/analytics/collector.ts

@@ -1,293 +0,0 @@
-/**
- * @pi-unipi/utility — Analytics Collector
- *
- * Lightweight metrics collection for all unipi modules.
- * Privacy-respecting: no file contents, no sensitive data.
- */
-
-import { randomUUID } from "node:crypto";
-import type {
-  AnalyticsEvent,
-  AnalyticsEventType,
-  AnalyticsRollup,
-  AnalyticsOptions,
-} from "../types.js";
-
-/** Default options */
-const DEFAULTS: Required<AnalyticsOptions> = {
-  dbPath: "~/.unipi/analytics/events.db",
-  maxEvents: 10000,
-  rollupEnabled: true,
-};
-
-/** In-memory event buffer */
-const eventBuffer: AnalyticsEvent[] = [];
-let bufferFlushTimer: ReturnType<typeof setInterval> | null = null;
-
-/** Generate a unique event ID */
-function generateId(): string {
-  return randomUUID();
-}
-
-/** Get today's date as YYYY-MM-DD */
-function today(): string {
-  return new Date().toISOString().slice(0, 10);
-}
-
-/**
- * AnalyticsCollector records events and provides rollup aggregation.
- * Uses in-memory buffering with periodic flush to avoid I/O overhead.
- */
-export class AnalyticsCollector {
-  private opts: Required<AnalyticsOptions>;
-  private enabled: boolean;
-
-  constructor(options: AnalyticsOptions = {}) {
-    this.opts = { ...DEFAULTS, ...options };
-    this.enabled = true;
-    this.startFlushTimer();
-  }
-
-  /** Disable collection */
-  disable(): void {
-    this.enabled = false;
-    this.stopFlushTimer();
-  }
-
-  /** Enable collection */
-  enable(): void {
-    this.enabled = true;
-    this.startFlushTimer();
-  }
-
-  /** Record an analytics event */
-  record(
-    type: AnalyticsEventType,
-    metadata?: Record<string, unknown>,
-  ): AnalyticsEvent {
-    if (!this.enabled) {
-      return {
-        id: generateId(),
-        type,
-        timestamp: Date.now(),
-        metadata,
-      };
-    }
-
-    const event: AnalyticsEvent = {
-      id: generateId(),
-      type,
-      timestamp: Date.now(),
-      metadata: this.sanitizeMetadata(metadata),
-    };
-
-    eventBuffer.push(event);
-
-    // Auto-flush if buffer is full
-    if (eventBuffer.length >= this.opts.maxEvents) {
-      this.flush().catch(() => {
-        // Best-effort flush
-      });
-    }
-
-    return event;
-  }
-
-  /** Record a command execution */
-  recordCommand(
-    command: string,
-    module: string,
-    durationMs: number,
-    success: boolean,
-  ): AnalyticsEvent {
-    return this.record("command_run", {
-      command,
-      module,
-      durationMs,
-      success,
-    });
-  }
-
-  /** Record a tool call */
-  recordTool(
-    tool: string,
-    module: string,
-    durationMs: number,
-    success: boolean,
-  ): AnalyticsEvent {
-    return this.record("tool_call", {
-      tool,
-      module,
-      durationMs,
-      success,
-    });
-  }
-
-  /** Record an error */
-  recordError(
-    module: string,
-    errorType: string,
-    message?: string,
-  ): AnalyticsEvent {
-    return this.record("error", {
-      module,
-      errorType,
-      message: message ? this.sanitizeString(message) : undefined,
-    });
-  }
-
-  /** Record a module load */
-  recordModuleLoad(module: string, version: string): AnalyticsEvent {
-    return this.record("module_load", { module, version });
-  }
-
-  /** Record a search operation */
-  recordSearch(
-    module: string,
-    query: string,
-    resultCount: number,
-  ): AnalyticsEvent {
-    return this.record("search", {
-      module,
-      query: this.sanitizeString(query),
-      resultCount,
-    });
-  }
-
-  /** Get all buffered events */
-  getEvents(): readonly AnalyticsEvent[] {
-    return eventBuffer;
-  }
-
-  /** Get events filtered by type */
-  getEventsByType(type: AnalyticsEventType): AnalyticsEvent[] {
-    return eventBuffer.filter((e) => e.type === type);
-  }
-
-  /** Compute daily rollup from buffered events */
-  getRollup(date?: string): AnalyticsRollup {
-    const targetDate = date ?? today();
-    const dayStart = new Date(targetDate).getTime();
-    const dayEnd = dayStart + 24 * 60 * 60 * 1000;
-
-    const dayEvents = eventBuffer.filter(
-      (e) => e.timestamp >= dayStart && e.timestamp < dayEnd,
-    );
-
-    const events: Record<AnalyticsEventType, number> = {
-      module_load: 0,
-      command_run: 0,
-      tool_call: 0,
-      error: 0,
-      compaction: 0,
-      search: 0,
-    };
-
-    let totalDurationMs = 0;
-    let errorCount = 0;
-
-    for (const e of dayEvents) {
-      events[e.type]++;
-      if (e.metadata?.durationMs) {
-        totalDurationMs += Number(e.metadata.durationMs);
-      }
-      if (e.type === "error" || e.metadata?.success === false) {
-        errorCount++;
-      }
-    }
-
-    return {
-      date: targetDate,
-      events,
-      totalDurationMs,
-      errorCount,
-    };
-  }
-
-  /** Export all events to JSON */
-  exportToJSON(): string {
-    return JSON.stringify(eventBuffer, null, 2);
-  }
-
-  /** Flush buffered events to storage (placeholder for future SQLite persistence) */
-  async flush(): Promise<number> {
-    const count = eventBuffer.length;
-    // TODO: persist to SQLite when sqlite3 is available
-    // For now, keep in memory but trim if over max
-    if (count > this.opts.maxEvents) {
-      eventBuffer.splice(0, count - this.opts.maxEvents);
-    }
-    return count;
-  }
-
-  /** Clear all buffered events */
-  clear(): void {
-    eventBuffer.length = 0;
-  }
-
-  // ─── Private ───────────────────────────────────────────────────────────────
-
-  private startFlushTimer(): void {
-    if (bufferFlushTimer) return;
-    bufferFlushTimer = setInterval(() => {
-      this.flush().catch(() => {
-        // Best-effort
-      });
-    }, 60000); // Flush every minute
-    if (bufferFlushTimer.unref) {
-      bufferFlushTimer.unref();
-    }
-  }
-
-  private stopFlushTimer(): void {
-    if (bufferFlushTimer) {
-      clearInterval(bufferFlushTimer);
-      bufferFlushTimer = null;
-    }
-  }
-
-  /** Sensitive key patterns to redact */
-  private static SENSITIVE_KEYS =
-    /api[_-]?key|apiKey|token|password|secret|auth|credential|private[_-]?key/i;
-
-  /** Remove sensitive data from metadata */
-  private sanitizeMetadata(
-    metadata?: Record<string, unknown>,
-  ): Record<string, unknown> | undefined {
-    if (!metadata) return undefined;
-    const sanitized: Record<string, unknown> = {};
-    for (const [key, value] of Object.entries(metadata)) {
-      if (AnalyticsCollector.SENSITIVE_KEYS.test(key)) {
-        sanitized[key] = "[REDACTED]";
-      } else if (typeof value === "string") {
-        sanitized[key] = this.sanitizeString(value);
-      } else {
-        sanitized[key] = value;
-      }
-    }
-    return sanitized;
-  }
-
-  /** Truncate long strings, remove potential secrets */
-  private sanitizeString(str: string): string {
-    // Truncate to 500 chars
-    let result = str.length > 500 ? str.slice(0, 500) + "…" : str;
-    // Redact common secret patterns in strings
-    result = result.replace(
-      /(api[_-]?key|apiKey|token|password|secret|auth)\s*[:=]\s*\S+/gi,
-      "$1: [REDACTED]",
-    );
-    return result;
-  }
-}
-
-/** Global singleton */
-let globalCollector: AnalyticsCollector | null = null;
-
-/** Get or create the global analytics collector */
-export function getAnalyticsCollector(options?: AnalyticsOptions): AnalyticsCollector {
-  if (!globalCollector) {
-    globalCollector = new AnalyticsCollector(options);
-  }
-  return globalCollector;
-}

package/packages/utility/src/info-screen.ts

@@ -1,80 +0,0 @@
-/**
- * @pi-unipi/utility — Info-Screen Integration
- *
- * Registers utility stats group for the info-screen overlay.
- */
-
-import type { ExtensionAPI } from "@earendil-works/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/packages/utility/src/lifecycle/process.ts

@@ -1,162 +0,0 @@
-/**
- * @pi-unipi/utility — Process Lifecycle Manager
- *
- * General-purpose process lifecycle management:
- * - Parent PID polling (orphan detection)
- * - Signal handlers for graceful shutdown
- * - Cleanup callbacks registry
- */
-
-import type {
-  CleanupFn,
-  LifecycleState,
-  ProcessLifecycleOptions,
-} from "../types.js";
-
-/** Default options */
-const DEFAULTS: Required<ProcessLifecycleOptions> = {
-  pollIntervalMs: 30000,
-  handleSignals: true,
-};
-
-/**
- * ProcessLifecycle manages the lifecycle of the utility process.
- * Detects orphan status via parent PID polling and provides
- * graceful shutdown with registered cleanup callbacks.
- */
-export class ProcessLifecycle {
-  private state: LifecycleState = "running";
-  private parentPid: number | null = null;
-  private pollTimer: ReturnType<typeof setInterval> | null = null;
-  private cleanups: Set<CleanupFn> = new Set();
-  private opts: Required<ProcessLifecycleOptions>;
-
-  constructor(options: ProcessLifecycleOptions = {}) {
-    this.opts = { ...DEFAULTS, ...options };
-    this.parentPid = process.ppid ?? null;
-
-    if (this.opts.handleSignals) {
-      this.installSignalHandlers();
-    }
-
-    this.startPolling();
-  }
-
-  /** Current lifecycle state */
-  get currentState(): LifecycleState {
-    return this.state;
-  }
-
-  /** Whether the process is shutting down */
-  get isShuttingDown(): boolean {
-    return this.state === "shutting_down";
-  }
-
-  /** Whether the process has been orphaned */
-  get isOrphaned(): boolean {
-    return this.state === "orphaned";
-  }
-
-  /** Register a cleanup function to run on shutdown */
-  registerCleanup(fn: CleanupFn): () => void {
-    this.cleanups.add(fn);
-    return () => {
-      this.cleanups.delete(fn);
-    };
-  }
-
-  /** Unregister a cleanup function */
-  unregisterCleanup(fn: CleanupFn): void {
-    this.cleanups.delete(fn);
-  }
-
-  /** Initiate graceful shutdown */
-  async shutdown(reason: string = "requested"): Promise<void> {
-    if (this.state !== "running") return;
-    this.state = "shutting_down";
-    this.stopPolling();
-
-    const fns = Array.from(this.cleanups);
-    this.cleanups.clear();
-
-    for (const fn of fns) {
-      try {
-        await fn();
-      } catch {
-        // Best-effort cleanup — don't let one failure stop others
-      }
-    }
-
-    this.state = "error";
-  }
-
-  /** Start parent PID polling for orphan detection */
-  private startPolling(): void {
-    if (this.pollTimer) return;
-
-    this.pollTimer = setInterval(() => {
-      this.checkParent();
-    }, this.opts.pollIntervalMs);
-
-    // Don't block process exit on the timer
-    if (this.pollTimer.unref) {
-      this.pollTimer.unref();
-    }
-  }
-
-  /** Stop polling */
-  private stopPolling(): void {
-    if (this.pollTimer) {
-      clearInterval(this.pollTimer);
-      this.pollTimer = null;
-    }
-  }
-
-  /** Check if parent process is still alive */
-  private checkParent(): void {
-    if (this.parentPid === null) return;
-
-    try {
-      // Sending signal 0 checks if process exists without affecting it
-      process.kill(this.parentPid, 0);
-    } catch {
-      // Parent is gone — we're orphaned
-      this.state = "orphaned";
-      this.stopPolling();
-      this.shutdown("orphaned").catch(() => {
-        // Ignore shutdown errors in orphan path
-      });
-    }
-  }
-
-  /** Install SIGTERM / SIGINT handlers */
-  private installSignalHandlers(): void {
-    const handler = (signal: string) => {
-      this.shutdown(signal).then(() => {
-        process.exit(0);
-      });
-    };
-
-    process.once("SIGTERM", () => handler("SIGTERM"));
-    process.once("SIGINT", () => handler("SIGINT"));
-  }
-}
-
-/** Global singleton instance */
-let globalLifecycle: ProcessLifecycle | null = null;
-
-/** Get or create the global lifecycle manager */
-export function getLifecycle(options?: ProcessLifecycleOptions): ProcessLifecycle {
-  if (!globalLifecycle) {
-    globalLifecycle = new ProcessLifecycle(options);
-  }
-  return globalLifecycle;
-}
-
-/** Dispose the global lifecycle manager */
-export function disposeLifecycle(): void {
-  if (globalLifecycle) {
-    globalLifecycle.shutdown("dispose").catch(() => {});
-    globalLifecycle = null;
-  }
-}