@pi-unipi/utility 0.1.1 → 0.2.1

package/src/diagnostics/engine.ts

@@ -0,0 +1,298 @@
+/**
+ * @pi-unipi/utility — Diagnostics Engine
+ *
+ * Cross-module diagnostics runner with health check plugins.
+ */
+
+import { existsSync, accessSync, constants } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import type {
+  DiagnosticCheck,
+  DiagnosticPlugin,
+  DiagnosticsReport,
+  HealthStatus,
+} from "../types.js";
+
+/** Expand ~ to home directory */
+function expandHome(path: string): string {
+  if (path.startsWith("~/")) {
+    return join(homedir(), path.slice(2));
+  }
+  return path;
+}
+
+/** Check if a path is readable */
+function isReadable(path: string): boolean {
+  try {
+    accessSync(path, constants.R_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Check if a path is writable */
+function isWritable(path: string): boolean {
+  try {
+    accessSync(path, constants.W_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// ─── Built-in Diagnostic Plugins ─────────────────────────────────────────────
+
+/** Check core directories exist and are accessible */
+const coreDirectoriesPlugin: DiagnosticPlugin = {
+  name: "core_directories",
+  module: "@pi-unipi/core",
+  async run(): Promise<DiagnosticCheck[]> {
+    const dirs = [
+      { path: "~/.unipi", required: true },
+      { path: "~/.unipi/memory", required: false },
+      { path: "~/.unipi/cache", required: false },
+      { path: "~/.unipi/analytics", required: false },
+    ];
+
+    const checks: DiagnosticCheck[] = [];
+    const start = Date.now();
+
+    for (const dir of dirs) {
+      const fullPath = expandHome(dir.path);
+      const exists = existsSync(fullPath);
+      const readable = exists && isReadable(fullPath);
+      const writable = exists && isWritable(fullPath);
+
+      let status: HealthStatus;
+      let message: string;
+      let suggestion: string | undefined;
+
+      if (!exists) {
+        if (dir.required) {
+          status = "error";
+          message = `Required directory missing: ${dir.path}`;
+          suggestion = `Create it: mkdir -p ${dir.path}`;
+        } else {
+          status = "warning";
+          message = `Optional directory missing: ${dir.path}`;
+          suggestion = `Create it if needed: mkdir -p ${dir.path}`;
+        }
+      } else if (!writable) {
+        status = "error";
+        message = `Directory not writable: ${dir.path}`;
+        suggestion = `Check permissions: chmod u+w ${dir.path}`;
+      } else {
+        status = "healthy";
+        message = `Directory OK: ${dir.path}`;
+      }
+
+      checks.push({
+        name: `dir_${dir.path.replace(/[^a-z0-9]/g, "_")}`,
+        module: "@pi-unipi/core",
+        status,
+        message,
+        suggestion,
+        durationMs: Date.now() - start,
+      });
+    }
+
+    return checks;
+  },
+};
+
+/** Check config files are valid JSON */
+const configFilesPlugin: DiagnosticPlugin = {
+  name: "config_files",
+  module: "@pi-unipi/core",
+  async run(): Promise<DiagnosticCheck[]> {
+    const configs = [
+      "~/.unipi/config/mcp/servers.json",
+      ".unipi/config/mcp/servers.json",
+    ];
+
+    const checks: DiagnosticCheck[] = [];
+
+    for (const configPath of configs) {
+      const start = Date.now();
+      const fullPath = expandHome(configPath);
+
+      if (!existsSync(fullPath)) {
+        checks.push({
+          name: `config_${basename(configPath)}`,
+          module: "@pi-unipi/core",
+          status: "unknown",
+          message: `Config not found: ${configPath}`,
+          durationMs: Date.now() - start,
+        });
+        continue;
+      }
+
+      try {
+        const content = await import("node:fs").then((fs) =>
+          fs.readFileSync(fullPath, "utf-8"),
+        );
+        JSON.parse(content);
+        checks.push({
+          name: `config_${basename(configPath)}`,
+          module: "@pi-unipi/core",
+          status: "healthy",
+          message: `Config valid: ${configPath}`,
+          durationMs: Date.now() - start,
+        });
+      } catch (err) {
+        checks.push({
+          name: `config_${basename(configPath)}`,
+          module: "@pi-unipi/core",
+          status: "error",
+          message: `Invalid JSON in ${configPath}: ${(err as Error).message}`,
+          suggestion: `Fix or remove the config file`,
+          durationMs: Date.now() - start,
+        });
+      }
+    }
+
+    return checks;
+  },
+};
+
+/** Check Node.js environment */
+const nodeEnvironmentPlugin: DiagnosticPlugin = {
+  name: "node_environment",
+  module: "@pi-unipi/core",
+  async run(): Promise<DiagnosticCheck[]> {
+    const start = Date.now();
+    const checks: DiagnosticCheck[] = [];
+
+    // Node version
+    const nodeVersion = process.version;
+    const major = parseInt(nodeVersion.slice(1).split(".")[0], 10);
+    const nodeCheck: DiagnosticCheck = {
+      name: "node_version",
+      module: "@pi-unipi/core",
+      status: major >= 18 ? "healthy" : "warning",
+      message: `Node.js ${nodeVersion}`,
+      suggestion: major < 18 ? "Upgrade to Node.js 18+ for best compatibility" : undefined,
+      durationMs: Date.now() - start,
+    };
+    checks.push(nodeCheck);
+
+    // Memory usage
+    const memStart = Date.now();
+    const usage = process.memoryUsage();
+    const heapUsedMB = Math.round(usage.heapUsed / 1024 / 1024);
+    const heapTotalMB = Math.round(usage.heapTotal / 1024 / 1024);
+    checks.push({
+      name: "memory_usage",
+      module: "@pi-unipi/core",
+      status: heapUsedMB > 512 ? "warning" : "healthy",
+      message: `Heap: ${heapUsedMB} MB / ${heapTotalMB} MB`,
+      suggestion: heapUsedMB > 512 ? "High memory usage detected — consider restarting" : undefined,
+      durationMs: Date.now() - memStart,
+    });
+
+    return checks;
+  },
+};
+
+// ─── Diagnostics Engine ──────────────────────────────────────────────────────
+
+/** Registry of diagnostic plugins */
+const plugins: DiagnosticPlugin[] = [
+  coreDirectoriesPlugin,
+  configFilesPlugin,
+  nodeEnvironmentPlugin,
+];
+
+/** Register a custom diagnostic plugin */
+export function registerDiagnosticPlugin(plugin: DiagnosticPlugin): void {
+  plugins.push(plugin);
+}
+
+/** Run all diagnostic checks and generate a report */
+export async function runDiagnostics(): Promise<DiagnosticsReport> {
+  const timestamp = Date.now();
+  const checks: DiagnosticCheck[] = [];
+
+  for (const plugin of plugins) {
+    try {
+      const pluginChecks = await plugin.run();
+      checks.push(...pluginChecks);
+    } catch (err) {
+      checks.push({
+        name: `${plugin.name}_error`,
+        module: plugin.module,
+        status: "error",
+        message: `Plugin failed: ${(err as Error).message}`,
+        durationMs: 0,
+      });
+    }
+  }
+
+  const summary = {
+    healthy: checks.filter((c) => c.status === "healthy").length,
+    warning: checks.filter((c) => c.status === "warning").length,
+    error: checks.filter((c) => c.status === "error").length,
+    unknown: checks.filter((c) => c.status === "unknown").length,
+  };
+
+  let overall: HealthStatus;
+  if (summary.error > 0) {
+    overall = "error";
+  } else if (summary.warning > 0) {
+    overall = "warning";
+  } else if (summary.healthy > 0) {
+    overall = "healthy";
+  } else {
+    overall = "unknown";
+  }
+
+  return {
+    timestamp,
+    overall,
+    checks,
+    summary,
+  };
+}
+
+/** Format a diagnostics report as markdown */
+export function formatDiagnosticsReport(report: DiagnosticsReport): string {
+  const lines = [
+    "## 🔍 Diagnostics Report",
+    "",
+    `**Overall:** ${report.overall.toUpperCase()}`,
+    `**Checks:** ${report.summary.healthy} healthy, ${report.summary.warning} warning, ${report.summary.error} error, ${report.summary.unknown} unknown`,
+    `**Timestamp:** ${new Date(report.timestamp).toISOString()}`,
+    "",
+  ];
+
+  // Group by status (errors first)
+  const byStatus = {
+    error: report.checks.filter((c) => c.status === "error"),
+    warning: report.checks.filter((c) => c.status === "warning"),
+    unknown: report.checks.filter((c) => c.status === "unknown"),
+    healthy: report.checks.filter((c) => c.status === "healthy"),
+  };
+
+  for (const [status, checks] of Object.entries(byStatus)) {
+    if (checks.length === 0) continue;
+    lines.push(`### ${status.toUpperCase()} (${checks.length})`, "");
+    for (const check of checks) {
+      lines.push(`- **${check.name}** (${check.module})`);
+      lines.push(`  ${check.message}`);
+      if (check.suggestion) {
+        lines.push(`  💡 ${check.suggestion}`);
+      }
+      lines.push("");
+    }
+  }
+
+  return lines.join("\n");
+}
+
+/** Get basename for diagnostic naming */
+function basename(path: string): string {
+  const parts = path.split(/[/\\]/);
+  return parts[parts.length - 1] || path;
+}

package/src/display/capabilities.ts

@@ -0,0 +1,200 @@
+/**
+ * @pi-unipi/utility — Terminal Capabilities Detection
+ *
+ * Detect terminal features for optimal rendering:
+ * - Color support (basic, 256, truecolor)
+ * - Nerd Font detection
+ * - Unicode support
+ * - Terminal dimensions
+ */
+
+import type { TerminalCapabilities } from "../types.js";
+
+/** Cached capabilities per process */
+let cachedCapabilities: TerminalCapabilities | null = null;
+let cacheTimestamp = 0;
+const CACHE_TTL_MS = 5000; // Re-detect every 5s
+
+/** Detect color support level */
+function detectColorSupport(): { color: boolean; truecolor: boolean } {
+  const env = process.env;
+
+  // No color
+  if (env.NO_COLOR || env.NODE_DISABLE_COLORS) {
+    return { color: false, truecolor: false };
+  }
+
+  // Force color
+  if (env.FORCE_COLOR) {
+    const level = parseInt(env.FORCE_COLOR, 10);
+    return {
+      color: level >= 1,
+      truecolor: level >= 3,
+    };
+  }
+
+  // CI environments typically support colors
+  if (env.CI) {
+    return { color: true, truecolor: false };
+  }
+
+  // Terminal emulator detection
+  const term = env.TERM || "";
+  const termProgram = env.TERM_PROGRAM || "";
+
+  // Truecolor support
+  const truecolorTerms = [
+    "truecolor",
+    "24bit",
+    "xterm-256color",
+    "screen-256color",
+    "tmux-256color",
+    "alacritty",
+    "kitty",
+    "wezterm",
+    "iTerm",
+    "ghostty",
+  ];
+
+  const hasTruecolor =
+    env.COLORTERM === "truecolor" ||
+    env.COLORTERM === "24bit" ||
+    truecolorTerms.some((t) => term.includes(t) || termProgram.includes(t));
+
+  // Basic color support
+  const hasColor =
+    hasTruecolor ||
+    term.includes("color") ||
+    term.includes("ansi") ||
+    term.includes("xterm") ||
+    term.includes("screen") ||
+    term.includes("tmux") ||
+    termProgram.length > 0;
+
+  return { color: hasColor, truecolor: hasTruecolor };
+}
+
+/** Detect Nerd Font support */
+function detectNerdFont(): boolean {
+  const env = process.env;
+
+  // Explicit override
+  if (env.NERD_FONT === "1" || env.NERD_FONT === "true") {
+    return true;
+  }
+  if (env.NERD_FONT === "0" || env.NERD_FONT === "false") {
+    return false;
+  }
+
+  // Terminal emulator hints
+  const termProgram = env.TERM_PROGRAM || "";
+  const knownNerdFontTerminals = [
+    "iTerm.app",
+    "WezTerm",
+    "Alacritty",
+    "Kitty",
+    "Ghostty",
+    "Warp",
+  ];
+
+  if (knownNerdFontTerminals.some((t) => termProgram.includes(t))) {
+    return true;
+  }
+
+  // Default to false for safety
+  return false;
+}
+
+/** Detect Unicode support level */
+function detectUnicode(): "none" | "basic" | "full" {
+  const env = process.env;
+
+  // Explicit override
+  if (env.UNICODE === "0" || env.NO_UNICODE) {
+    return "none";
+  }
+
+  // LANG/LC_ALL hints
+  const locale = env.LANG || env.LC_ALL || env.LC_CTYPE || "";
+  if (locale.includes("UTF-8") || locale.includes("utf8")) {
+    return "full";
+  }
+
+  // Windows CMD typically has limited Unicode
+  if (process.platform === "win32" && !env.WT_SESSION) {
+    return "basic";
+  }
+
+  // Default to basic (safe middle ground)
+  return "basic";
+}
+
+/** Get terminal dimensions */
+function getTerminalSize(): { width: number; height: number } {
+  const stdout = process.stdout;
+  if (stdout && stdout.isTTY) {
+    const cols = stdout.columns || 80;
+    const rows = stdout.rows || 24;
+    return { width: cols, height: rows };
+  }
+  return { width: 80, height: 24 };
+}
+
+/**
+ * Detect terminal capabilities.
+ * Results are cached for CACHE_TTL_MS to avoid repeated detection.
+ */
+export function detectCapabilities(): TerminalCapabilities {
+  const now = Date.now();
+  if (cachedCapabilities && now - cacheTimestamp < CACHE_TTL_MS) {
+    // Update dimensions even when cached (they change on resize)
+    const size = getTerminalSize();
+    return {
+      ...cachedCapabilities,
+      width: size.width,
+      height: size.height,
+    };
+  }
+
+  const colorSupport = detectColorSupport();
+  const size = getTerminalSize();
+
+  cachedCapabilities = {
+    color: colorSupport.color,
+    truecolor: colorSupport.truecolor,
+    nerdFont: detectNerdFont(),
+    unicode: detectUnicode(),
+    width: size.width,
+    height: size.height,
+  };
+
+  cacheTimestamp = now;
+  return cachedCapabilities;
+}
+
+/** Force re-detection of capabilities */
+export function refreshCapabilities(): TerminalCapabilities {
+  cachedCapabilities = null;
+  cacheTimestamp = 0;
+  return detectCapabilities();
+}
+
+/** Check if a specific capability is available */
+export function hasCapability(
+  cap: keyof TerminalCapabilities,
+): boolean {
+  const caps = detectCapabilities();
+  const value = caps[cap];
+  if (typeof value === "boolean") {
+    return value;
+  }
+  if (typeof value === "string") {
+    return value !== "none";
+  }
+  return false;
+}
+
+/** Get safe icon based on Nerd Font availability */
+export function getIcon(nerdFont: string, fallback: string): string {
+  return detectCapabilities().nerdFont ? nerdFont : fallback;
+}

package/src/display/width.ts

@@ -0,0 +1,226 @@
+/**
+ * @pi-unipi/utility — Width Management Utilities
+ *
+ * Safe width clamping, line wrapping, and line collapsing.
+ * Handles ANSI escape sequences correctly.
+ */
+
+import type { WidthOptions } from "../types.js";
+
+/** ANSI escape sequence regex */
+const ANSI_REGEX =
+  /\u001b\[[\d;]*[a-zA-Z]|\u001b\][^\u0007]*\u0007|\u001b\[[\d;]*[\u0020-\u002f]*[\u0030-\u007e]/g;
+
+/** Strip ANSI escape sequences from text */
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_REGEX, "");
+}
+
+/** Get visual width of text (excluding ANSI codes) */
+export function visualWidth(text: string): number {
+  return stripAnsi(text).length;
+}
+
+/** Default width options */
+const DEFAULT_WIDTH_OPTS: Required<WidthOptions> = {
+  ellipsis: "…",
+  breakWords: false,
+};
+
+/**
+ * Clamp text to maxWidth visual characters.
+ * Preserves ANSI sequences at the end of truncated text.
+ */
+export function clampWidth(
+  text: string,
+  maxWidth: number,
+  options: WidthOptions = {},
+): string {
+  const opts = { ...DEFAULT_WIDTH_OPTS, ...options };
+  const plain = stripAnsi(text);
+
+  if (plain.length <= maxWidth) {
+    return text;
+  }
+
+  // Need to truncate while preserving ANSI
+  const ellipsisWidth = visualWidth(opts.ellipsis);
+  const targetWidth = maxWidth - ellipsisWidth;
+
+  if (targetWidth <= 0) {
+    return opts.ellipsis.slice(0, maxWidth);
+  }
+
+  // Walk through text, tracking ANSI state
+  let visualCount = 0;
+  let result = "";
+  let inAnsi = false;
+  let ansiBuffer = "";
+
+  for (const char of text) {
+    if (char === "\u001b") {
+      inAnsi = true;
+      ansiBuffer = char;
+      continue;
+    }
+
+    if (inAnsi) {
+      ansiBuffer += char;
+      // Check if ANSI sequence is complete
+      if (/[a-zA-Z\u0007]/.test(char) || (ansiBuffer.startsWith("\u001b]") && char === "\u0007")) {
+        inAnsi = false;
+        result += ansiBuffer;
+        ansiBuffer = "";
+      }
+      continue;
+    }
+
+    if (visualCount < targetWidth) {
+      result += char;
+      visualCount++;
+    } else {
+      break;
+    }
+  }
+
+  // Add any pending ANSI sequences and reset
+  if (ansiBuffer) {
+    result += ansiBuffer;
+  }
+  result += "\u001b[0m"; // Reset ANSI
+  result += opts.ellipsis;
+
+  return result;
+}
+
+/**
+ * Wrap text into lines of maxWidth visual characters.
+ * Respects word boundaries unless breakWords is true.
+ */
+export function wrapLines(
+  text: string,
+  maxWidth: number,
+  options: WidthOptions = {},
+): string[] {
+  const opts = { ...DEFAULT_WIDTH_OPTS, ...options };
+  const lines: string[] = [];
+  const paragraphs = text.split("\n");
+
+  for (const paragraph of paragraphs) {
+    if (visualWidth(paragraph) <= maxWidth) {
+      lines.push(paragraph);
+      continue;
+    }
+
+    const words = paragraph.split(/(\s+)/);
+    let currentLine = "";
+    let currentWidth = 0;
+
+    for (const word of words) {
+      const wordWidth = visualWidth(word);
+
+      if (wordWidth === 0) {
+        // Whitespace-only word
+        currentLine += word;
+        continue;
+      }
+
+      if (currentWidth + wordWidth > maxWidth) {
+        if (currentLine) {
+          lines.push(currentLine);
+          currentLine = "";
+          currentWidth = 0;
+        }
+
+        // Word itself might be longer than maxWidth
+        if (!opts.breakWords && wordWidth > maxWidth) {
+          // Break the long word
+          let remaining = word;
+          while (visualWidth(remaining) > maxWidth) {
+            let chunk = "";
+            let chunkWidth = 0;
+            for (const char of remaining) {
+              const charWidth = visualWidth(char);
+              if (chunkWidth + charWidth > maxWidth) {
+                break;
+              }
+              chunk += char;
+              chunkWidth += charWidth;
+            }
+            lines.push(chunk);
+            remaining = remaining.slice(chunk.length);
+          }
+          if (remaining) {
+            currentLine = remaining;
+            currentWidth = visualWidth(remaining);
+          }
+        } else {
+          currentLine = word;
+          currentWidth = wordWidth;
+        }
+      } else {
+        currentLine += word;
+        currentWidth += wordWidth;
+      }
+    }
+
+    if (currentLine) {
+      lines.push(currentLine);
+    }
+  }
+
+  return lines;
+}
+
+/**
+ * Collapse consecutive empty lines down to maxEmpty.
+ */
+export function collapseLines(
+  lines: string[],
+  maxEmpty: number = 1,
+): string[] {
+  const result: string[] = [];
+  let emptyCount = 0;
+
+  for (const line of lines) {
+    const isEmpty = stripAnsi(line).trim().length === 0;
+
+    if (isEmpty) {
+      emptyCount++;
+      if (emptyCount <= maxEmpty) {
+        result.push(line);
+      }
+    } else {
+      emptyCount = 0;
+      result.push(line);
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Pad text to target width with spaces.
+ * Respects ANSI sequences.
+ */
+export function padWidth(text: string, targetWidth: number): string {
+  const currentWidth = visualWidth(text);
+  if (currentWidth >= targetWidth) {
+    return text;
+  }
+  return text + " ".repeat(targetWidth - currentWidth);
+}
+
+/**
+ * Center text within target width.
+ */
+export function centerWidth(text: string, targetWidth: number): string {
+  const currentWidth = visualWidth(text);
+  if (currentWidth >= targetWidth) {
+    return text;
+  }
+  const padding = targetWidth - currentWidth;
+  const left = Math.floor(padding / 2);
+  const right = padding - left;
+  return " ".repeat(left) + text + " ".repeat(right);
+}