@pi-unipi/utility 0.1.1 → 0.2.1

package/src/tui/settings-inspector.ts

@@ -0,0 +1,303 @@
+/**
+ * @pi-unipi/utility — Settings Inspector
+ *
+ * Reusable settings inspector overlay pattern.
+ * Split-pane layout: list left, editor right.
+ * Search/filter, keyboard navigation, JSON editing.
+ *
+ * Note: This is a data model and rendering helper. The actual TUI
+ * rendering depends on the host environment (pi's TUI API).
+ */
+
+import type {
+  SettingSchema,
+  SettingsInspectorState,
+} from "../types.js";
+
+/** Navigation actions */
+export type InspectorAction =
+  | { type: "navigate"; direction: "up" | "down" | "first" | "last" }
+  | { type: "search"; query: string }
+  | { type: "select"; index: number }
+  | { type: "edit"; value: unknown }
+  | { type: "toggle_edit" }
+  | { type: "save" }
+  | { type: "cancel" };
+
+/** Result of applying an action */
+export interface InspectorUpdate {
+  state: SettingsInspectorState;
+  changed: boolean;
+  saved: boolean;
+}
+
+/** Create initial inspector state */
+export function createSettingsInspector(
+  schemas: SettingSchema[],
+  initialValues?: Record<string, unknown>,
+): SettingsInspectorState {
+  const values: Record<string, unknown> = {};
+  for (const schema of schemas) {
+    values[schema.key] = initialValues?.[schema.key] ?? schema.default;
+  }
+
+  return {
+    schemas,
+    values,
+    selectedIndex: 0,
+    searchQuery: "",
+    editMode: false,
+  };
+}
+
+/** Get filtered schemas based on search query */
+export function getFilteredSchemas(
+  state: SettingsInspectorState,
+): SettingSchema[] {
+  if (!state.searchQuery.trim()) {
+    return state.schemas;
+  }
+
+  const query = state.searchQuery.toLowerCase();
+  return state.schemas.filter(
+    (s) =>
+      s.key.toLowerCase().includes(query) ||
+      s.description.toLowerCase().includes(query),
+  );
+}
+
+/** Get the currently selected schema */
+export function getSelectedSchema(
+  state: SettingsInspectorState,
+): SettingSchema | undefined {
+  const filtered = getFilteredSchemas(state);
+  return filtered[state.selectedIndex];
+}
+
+/** Get current value for a key */
+export function getValue(
+  state: SettingsInspectorState,
+  key: string,
+): unknown {
+  return state.values[key];
+}
+
+/** Apply an action to the inspector state */
+export function applyAction(
+  state: SettingsInspectorState,
+  action: InspectorAction,
+): InspectorUpdate {
+  const newState: SettingsInspectorState = {
+    ...state,
+    values: { ...state.values },
+  };
+  let changed = false;
+  let saved = false;
+
+  const filtered = getFilteredSchemas(newState);
+
+  switch (action.type) {
+    case "navigate": {
+      const maxIndex = Math.max(0, filtered.length - 1);
+      switch (action.direction) {
+        case "up":
+          newState.selectedIndex = Math.max(0, newState.selectedIndex - 1);
+          break;
+        case "down":
+          newState.selectedIndex = Math.min(maxIndex, newState.selectedIndex + 1);
+          break;
+        case "first":
+          newState.selectedIndex = 0;
+          break;
+        case "last":
+          newState.selectedIndex = maxIndex;
+          break;
+      }
+      changed = newState.selectedIndex !== state.selectedIndex;
+      break;
+    }
+
+    case "search": {
+      newState.searchQuery = action.query;
+      newState.selectedIndex = 0;
+      changed = true;
+      break;
+    }
+
+    case "select": {
+      const maxIndex = Math.max(0, filtered.length - 1);
+      newState.selectedIndex = Math.max(0, Math.min(maxIndex, action.index));
+      changed = newState.selectedIndex !== state.selectedIndex;
+      break;
+    }
+
+    case "edit": {
+      const selected = getSelectedSchema(newState);
+      if (selected) {
+        newState.values[selected.key] = action.value;
+        changed = true;
+      }
+      break;
+    }
+
+    case "toggle_edit": {
+      newState.editMode = !newState.editMode;
+      changed = true;
+      break;
+    }
+
+    case "save": {
+      saved = true;
+      changed = true;
+      break;
+    }
+
+    case "cancel": {
+      newState.editMode = false;
+      changed = true;
+      break;
+    }
+  }
+
+  return { state: newState, changed, saved };
+}
+
+/** Validate a value against its schema */
+export function validateValue(
+  schema: SettingSchema,
+  value: unknown,
+): string | undefined {
+  if (value === undefined || value === null) {
+    if (schema.required) {
+      return `Required field: ${schema.key}`;
+    }
+    return undefined;
+  }
+
+  switch (schema.type) {
+    case "string":
+      if (typeof value !== "string") {
+        return `Expected string for ${schema.key}`;
+      }
+      break;
+    case "number":
+      if (typeof value !== "number" || Number.isNaN(value)) {
+        return `Expected number for ${schema.key}`;
+      }
+      break;
+    case "boolean":
+      if (typeof value !== "boolean") {
+        return `Expected boolean for ${schema.key}`;
+      }
+      break;
+    case "object":
+      if (typeof value !== "object" || Array.isArray(value)) {
+        return `Expected object for ${schema.key}`;
+      }
+      break;
+    case "array":
+      if (!Array.isArray(value)) {
+        return `Expected array for ${schema.key}`;
+      }
+      break;
+  }
+
+  return undefined;
+}
+
+/** Validate all values against schemas */
+export function validateAll(
+  state: SettingsInspectorState,
+): Record<string, string> {
+  const errors: Record<string, string> = {};
+  for (const schema of state.schemas) {
+    const error = validateValue(schema, state.values[schema.key]);
+    if (error) {
+      errors[schema.key] = error;
+    }
+  }
+  return errors;
+}
+
+/** Export state values as JSON */
+export function exportToJSON(state: SettingsInspectorState): string {
+  return JSON.stringify(state.values, null, 2);
+}
+
+/** Import values from JSON string */
+export function importFromJSON(
+  state: SettingsInspectorState,
+  json: string,
+): { state: SettingsInspectorState; errors: Record<string, string> } {
+  let parsed: Record<string, unknown>;
+  try {
+    parsed = JSON.parse(json);
+  } catch (err) {
+    return {
+      state,
+      errors: { _parse: `Invalid JSON: ${(err as Error).message}` },
+    };
+  }
+
+  const newState: SettingsInspectorState = {
+    ...state,
+    values: { ...state.values },
+  };
+
+  const errors: Record<string, string> = {};
+  for (const schema of state.schemas) {
+    if (parsed[schema.key] !== undefined) {
+      const error = validateValue(schema, parsed[schema.key]);
+      if (error) {
+        errors[schema.key] = error;
+      } else {
+        newState.values[schema.key] = parsed[schema.key];
+      }
+    }
+  }
+
+  return { state: newState, errors };
+}
+
+/** Format a setting for display */
+export function formatSetting(
+  schema: SettingSchema,
+  value: unknown,
+): string {
+  const displayValue = value === undefined ? "(unset)" : JSON.stringify(value);
+  const requiredMark = schema.required ? "*" : "";
+  return `${schema.key}${requiredMark}: ${displayValue}\n  ${schema.description}`;
+}
+
+/** Render the inspector as markdown (for non-TUI environments) */
+export function renderAsMarkdown(
+  state: SettingsInspectorState,
+): string {
+  const filtered = getFilteredSchemas(state);
+  const lines = [
+    "## ⚙️ Settings",
+    "",
+    state.searchQuery ? `*Filter: "${state.searchQuery}"*` : "",
+    "",
+  ];
+
+  for (let i = 0; i < filtered.length; i++) {
+    const schema = filtered[i];
+    const value = state.values[schema.key];
+    const selected = i === state.selectedIndex ? "> " : "  ";
+    const required = schema.required ? " **(required)**" : "";
+
+    lines.push(
+      `${selected}**${schema.key}**${required} \`${schema.type}\``,
+      `    ${schema.description}`,
+      `    Value: \`${JSON.stringify(value)}\``,
+      "",
+    );
+  }
+
+  if (filtered.length === 0) {
+    lines.push("*No settings match your search.*");
+  }
+
+  return lines.join("\n");
+}

package/src/types.ts

@@ -0,0 +1,257 @@
+/**
+ * @pi-unipi/utility — Shared types
+ *
+ * Type definitions for utility modules: lifecycle, cache, analytics,
+ * diagnostics, display, TUI, and tools.
+ */
+
+// ─── Lifecycle ───────────────────────────────────────────────────────────────
+
+/** Cleanup function registered with the lifecycle manager */
+export type CleanupFn = () => void | Promise<void>;
+
+/** Process lifecycle state */
+export type LifecycleState = "running" | "shutting_down" | "orphaned" | "error";
+
+/** Options for ProcessLifecycle */
+export interface ProcessLifecycleOptions {
+  /** Polling interval in ms for parent PID checks (default: 30000) */
+  pollIntervalMs?: number;
+  /** Whether to install signal handlers (default: true) */
+  handleSignals?: boolean;
+}
+
+// ─── Cache ───────────────────────────────────────────────────────────────────
+
+/** Cache entry with metadata */
+export interface CacheEntry<V> {
+  value: V;
+  expiresAt: number;
+  createdAt: number;
+}
+
+/** TTL cache backend interface */
+export interface CacheBackend<K, V> {
+  get(key: K): Promise<V | undefined>;
+  set(key: K, value: V, ttlMs: number): Promise<void>;
+  has(key: K): Promise<boolean>;
+  delete(key: K): Promise<boolean>;
+  cleanupExpired(): Promise<number>;
+  clear(): Promise<void>;
+}
+
+/** TTL cache options */
+export interface TTLCacheOptions {
+  /** Use SQLite persistence (default: false) */
+  persistent?: boolean;
+  /** SQLite DB path (default: auto) */
+  dbPath?: string;
+  /** Default TTL in ms */
+  defaultTtlMs?: number;
+  /** Max entries in memory cache */
+  maxMemoryEntries?: number;
+}
+
+// ─── Analytics ───────────────────────────────────────────────────────────────
+
+/** Analytics event types */
+export type AnalyticsEventType =
+  | "module_load"
+  | "command_run"
+  | "tool_call"
+  | "error"
+  | "compaction"
+  | "search";
+
+/** Single analytics event record */
+export interface AnalyticsEvent {
+  id: string;
+  type: AnalyticsEventType;
+  timestamp: number;
+  module?: string;
+  command?: string;
+  tool?: string;
+  durationMs?: number;
+  success?: boolean;
+  metadata?: Record<string, unknown>;
+}
+
+/** Daily rollup of analytics events */
+export interface AnalyticsRollup {
+  date: string; // YYYY-MM-DD
+  events: Record<AnalyticsEventType, number>;
+  totalDurationMs: number;
+  errorCount: number;
+}
+
+/** Analytics collector options */
+export interface AnalyticsOptions {
+  /** SQLite DB path */
+  dbPath?: string;
+  /** Max events before auto-rollup (default: 10000) */
+  maxEvents?: number;
+  /** Enable daily rollup (default: true) */
+  rollupEnabled?: boolean;
+}
+
+// ─── Diagnostics ─────────────────────────────────────────────────────────────
+
+/** Health status for a single check */
+export type HealthStatus = "healthy" | "warning" | "error" | "unknown";
+
+/** Result of a single diagnostic check */
+export interface DiagnosticCheck {
+  name: string;
+  module: string;
+  status: HealthStatus;
+  message: string;
+  suggestion?: string;
+  durationMs: number;
+}
+
+/** Complete diagnostics report */
+export interface DiagnosticsReport {
+  timestamp: number;
+  overall: HealthStatus;
+  checks: DiagnosticCheck[];
+  summary: {
+    healthy: number;
+    warning: number;
+    error: number;
+    unknown: number;
+  };
+}
+
+/** Plugin for diagnostics engine */
+export interface DiagnosticPlugin {
+  name: string;
+  module: string;
+  run(): Promise<DiagnosticCheck[]>;
+}
+
+// ─── Display ─────────────────────────────────────────────────────────────────
+
+/** Detected terminal capabilities */
+export interface TerminalCapabilities {
+  /** Terminal supports basic colors */
+  color: boolean;
+  /** Terminal supports 256/truecolor */
+  truecolor: boolean;
+  /** Nerd Font detected */
+  nerdFont: boolean;
+  /** Unicode support level */
+  unicode: "none" | "basic" | "full";
+  /** Terminal width in columns */
+  width: number;
+  /** Terminal height in rows */
+  height: number;
+}
+
+/** Width management options */
+export interface WidthOptions {
+  /** Truncation indicator (default: "…") */
+  ellipsis?: string;
+  /** Whether to break words (default: false) */
+  breakWords?: boolean;
+}
+
+// ─── TUI ─────────────────────────────────────────────────────────────────────
+
+/** Settings schema entry */
+export interface SettingSchema {
+  key: string;
+  type: "string" | "number" | "boolean" | "object" | "array";
+  description: string;
+  default?: unknown;
+  required?: boolean;
+}
+
+/** Settings inspector state */
+export interface SettingsInspectorState {
+  schemas: SettingSchema[];
+  values: Record<string, unknown>;
+  selectedIndex: number;
+  searchQuery: string;
+  editMode: boolean;
+}
+
+// ─── Tools ───────────────────────────────────────────────────────────────────
+
+/** Single batch command entry */
+export interface BatchCommand {
+  type: "command" | "tool" | "search";
+  name: string;
+  args?: Record<string, unknown>;
+}
+
+/** Batch execution options */
+export interface BatchOptions {
+  /** Fail on first error (default: true) */
+  failFast?: boolean;
+  /** Timeout per command in ms (default: 30000) */
+  commandTimeoutMs?: number;
+  /** Total timeout in ms (default: 300000) */
+  totalTimeoutMs?: number;
+}
+
+/** Result of a single batch command */
+export interface BatchResult {
+  command: BatchCommand;
+  success: boolean;
+  result?: unknown;
+  error?: string;
+  durationMs: number;
+}
+
+/** Complete batch execution result */
+export interface BatchReport {
+  success: boolean;
+  results: BatchResult[];
+  totalDurationMs: number;
+  rolledBack: boolean;
+}
+
+/** Environment info returned by ctx_env */
+export interface EnvironmentInfo {
+  nodeVersion: string;
+  piVersion: string;
+  os: string;
+  platform: string;
+  unipiModules: string[];
+  configPaths: string[];
+  extensionPaths: string[];
+}
+
+// ─── Cleanup ─────────────────────────────────────────────────────────────────
+
+/** Result of a cleanup operation */
+export interface CleanupResult {
+  /** What was cleaned */
+  category: "db" | "temp" | "session" | "cache" | "log";
+  /** Items removed */
+  removed: number;
+  /** Bytes freed (approximate) */
+  bytesFreed: number;
+  /** Paths that were cleaned */
+  paths: string[];
+}
+
+/** Complete cleanup report */
+export interface CleanupReport {
+  timestamp: number;
+  results: CleanupResult[];
+  totalRemoved: number;
+  totalBytesFreed: number;
+}
+
+/** Cleanup options */
+export interface CleanupOptions {
+  /** Max age in days for DB files (default: 14) */
+  dbMaxAgeDays?: number;
+  /** Max age in days for temp files (default: 7) */
+  tempMaxAgeDays?: number;
+  /** Max age in days for sessions (default: 30) */
+  sessionMaxAgeDays?: number;
+  /** Dry run — report only (default: false) */
+  dryRun?: boolean;
+}

package/commands.ts

@@ -1,38 +0,0 @@
-/**
- * @pi-unipi/utility — Command registration
- *
- * Registers /unipi:continue command for clean agent continuation.
- */
-
-import type { ExtensionAPI, ExtensionContext } from "@mariozechner/pi-coding-agent";
-import { UNIPI_PREFIX, UTILITY_COMMANDS } from "@pi-unipi/core";
-
-/**
- * Register utility commands.
- */
-export function registerUtilityCommands(pi: ExtensionAPI): void {
-  pi.registerCommand(`${UNIPI_PREFIX}${UTILITY_COMMANDS.CONTINUE}`, {
-    description: "Continue the agent from where it left off without adding user context",
-    handler: async (_args: string, ctx: ExtensionContext) => {
-      if (!ctx.isIdle()) {
-        if (ctx.hasUI) {
-          ctx.ui.notify(
-            "Agent is busy. Press ESC to interrupt, then try again.",
-            "warning",
-          );
-        }
-        return;
-      }
-
-      // Send custom message to trigger a turn without polluting transcript
-      pi.sendMessage(
-        {
-          customType: "unipi-continue",
-          content: "",
-          display: false,
-        },
-        { triggerTurn: true },
-      );
-    },
-  });
-}

package/index.ts

@@ -1,34 +0,0 @@
-/**
- * @pi-unipi/utility — Extension entry
- *
- * Provides /unipi:continue command for clean agent continuation
- * without context pollution.
- */
-
-import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
-import {
-  UNIPI_EVENTS,
-  MODULES,
-  UTILITY_COMMANDS,
-  emitEvent,
-  getPackageVersion,
-} from "@pi-unipi/core";
-import { registerUtilityCommands } from "./commands.js";
-
-/** Package version */
-const VERSION = getPackageVersion(new URL(".", import.meta.url).pathname);
-
-export default function (pi: ExtensionAPI) {
-  // Register commands
-  registerUtilityCommands(pi);
-
-  // Session lifecycle — announce module
-  pi.on("session_start", async () => {
-    emitEvent(pi, UNIPI_EVENTS.MODULE_READY, {
-      name: MODULES.UTILITY,
-      version: VERSION,
-      commands: [`unipi:${UTILITY_COMMANDS.CONTINUE}`],
-      tools: [],
-    });
-  });
-}