@pi-unipi/utility 2.6.0 → 2.6.2

package/src/display/capabilities.ts

@@ -1,214 +0,0 @@
-/**
- * @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 || "";
-
-  // Apple Terminal.app does NOT support 24-bit truecolor (longstanding
-  // limitation as of macOS 26). Force 256-colour even if some wrapper
-  // leaked COLORTERM=truecolor into the environment.
-  const isAppleTerminal = termProgram === "Apple_Terminal";
-
-  // Truecolor TERM_PROGRAM allow-list. Note: terminfo names like
-  // "xterm-256color" / "screen-256color" / "tmux-256color" advertise
-  // 256-colour, NOT truecolor — they must not appear here.
-  const truecolorTermPrograms = [
-    "iTerm.app",
-    "WezTerm",
-    "Alacritty",
-    "vscode",
-    "Hyper",
-    "Warp",
-    "ghostty",
-    "Ghostty",
-    "zed",
-    "Zed",
-    "cursor",
-    "Cursor",
-  ];
-
-  // Truecolor TERM tokens (the rare TERM that *does* advertise truecolor).
-  const truecolorTermTokens = ["truecolor", "24bit", "alacritty", "kitty", "wezterm"];
-
-  const hasTruecolor = isAppleTerminal
-    ? false
-    : env.COLORTERM === "truecolor" ||
-      env.COLORTERM === "24bit" ||
-      truecolorTermPrograms.includes(termProgram) ||
-      truecolorTermTokens.some((t) => term.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

@@ -1,226 +0,0 @@
-/**
- * @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);
-}

package/src/tools/batch.ts

@@ -1,229 +0,0 @@
-/**
- * @pi-unipi/utility — Batch Execution Tool
- *
- * Atomic batch of commands + searches with rollback on failure.
- */
-
-import type {
-  BatchCommand,
-  BatchOptions,
-  BatchResult,
-  BatchReport,
-} from "../types.js";
-
-/** Default options */
-const DEFAULTS: Required<BatchOptions> = {
-  failFast: true,
-  commandTimeoutMs: 30000,
-  totalTimeoutMs: 300000,
-};
-
-/** Executor function type — provided by the host environment */
-export type CommandExecutor = (
-  command: BatchCommand,
-) => Promise<unknown>;
-
-/** Rollback function type */
-export type RollbackFn = (
-  results: BatchResult[],
-) => Promise<void>;
-
-/**
- * Execute a batch of commands atomically.
- *
- * @param commands - Array of commands to execute
- * @param executor - Function that executes a single command
- * @param options - Batch execution options
- * @param rollback - Optional rollback function called on failure
- */
-export async function executeBatch(
-  commands: BatchCommand[],
-  executor: CommandExecutor,
-  options: BatchOptions = {},
-  rollback?: RollbackFn,
-): Promise<BatchReport> {
-  const opts = { ...DEFAULTS, ...options };
-  const results: BatchResult[] = [];
-  const startTime = Date.now();
-
-  // Total timeout guard
-  const totalDeadline = startTime + opts.totalTimeoutMs;
-
-  for (let i = 0; i < commands.length; i++) {
-    const command = commands[i];
-    const cmdStart = Date.now();
-
-    // Check total timeout
-    if (Date.now() > totalDeadline) {
-      const timeoutResult: BatchResult = {
-        command,
-        success: false,
-        error: `Total batch timeout exceeded (${opts.totalTimeoutMs}ms)`,
-        durationMs: Date.now() - cmdStart,
-      };
-      results.push(timeoutResult);
-
-      if (opts.failFast) {
-        const report = createReport(results, startTime, !!rollback);
-        if (rollback) {
-          await rollback(results).catch(() => {
-            // Best-effort rollback
-          });
-        }
-        return report;
-      }
-      continue;
-    }
-
-    // Execute with per-command timeout
-    try {
-      const result = await withTimeout(
-        executor(command),
-        opts.commandTimeoutMs,
-        `Command timeout exceeded (${opts.commandTimeoutMs}ms)`,
-      );
-
-      results.push({
-        command,
-        success: true,
-        result,
-        durationMs: Date.now() - cmdStart,
-      });
-    } catch (err) {
-      const errorResult: BatchResult = {
-        command,
-        success: false,
-        error: (err as Error).message,
-        durationMs: Date.now() - cmdStart,
-      };
-      results.push(errorResult);
-
-      if (opts.failFast) {
-        const report = createReport(results, startTime, !!rollback);
-        if (rollback) {
-          await rollback(results).catch(() => {
-            // Best-effort rollback
-          });
-        }
-        return report;
-      }
-    }
-  }
-
-  return createReport(results, startTime, false);
-}
-
-/** Create a batch report from results */
-function createReport(
-  results: BatchResult[],
-  startTime: number,
-  rolledBack: boolean,
-): BatchReport {
-  const allSuccess = results.every((r) => r.success);
-  return {
-    success: allSuccess && !rolledBack,
-    results,
-    totalDurationMs: Date.now() - startTime,
-    rolledBack,
-  };
-}
-
-/** Wrap a promise with a timeout */
-function withTimeout<T>(
-  promise: Promise<T>,
-  timeoutMs: number,
-  message: string,
-): Promise<T> {
-  return new Promise((resolve, reject) => {
-    const timer = setTimeout(() => {
-      reject(new Error(message));
-    }, timeoutMs);
-
-    promise
-      .then((value) => {
-        clearTimeout(timer);
-        resolve(value);
-      })
-      .catch((err) => {
-        clearTimeout(timer);
-        reject(err);
-      });
-  });
-}
-
-/** Format a batch report as markdown */
-export function formatBatchReport(report: BatchReport): string {
-  const lines = [
-    "## 📦 Batch Execution Report",
-    "",
-    `**Success:** ${report.success ? "✓ Yes" : "✗ No"}`,
-    `**Commands:** ${report.results.length}`,
-    `**Duration:** ${report.totalDurationMs}ms`,
-    report.rolledBack ? "**Rolled back:** Yes" : "",
-    "",
-  ].filter(Boolean);
-
-  for (let i = 0; i < report.results.length; i++) {
-    const r = report.results[i];
-    const icon = r.success ? "✓" : "✗";
-    lines.push(
-      `### ${i + 1}. ${icon} ${r.command.type}:${r.command.name}`,
-      `**Duration:** ${r.durationMs}ms`,
-    );
-    if (r.success) {
-      lines.push(`**Result:** \`${JSON.stringify(r.result).slice(0, 200)}\``);
-    } else {
-      lines.push(`**Error:** ${r.error}`);
-    }
-    lines.push("");
-  }
-
-  return lines.join("\n");
-}
-
-/** Create a simple command batch builder */
-export class BatchBuilder {
-  private commands: BatchCommand[] = [];
-  private opts: BatchOptions = {};
-  private rollbackFn?: RollbackFn;
-
-  /** Add a command to the batch */
-  addCommand(name: string, args?: Record<string, unknown>): this {
-    this.commands.push({ type: "command", name, args });
-    return this;
-  }
-
-  /** Add a tool call to the batch */
-  addTool(name: string, args?: Record<string, unknown>): this {
-    this.commands.push({ type: "tool", name, args });
-    return this;
-  }
-
-  /** Add a search to the batch */
-  addSearch(name: string, args?: Record<string, unknown>): this {
-    this.commands.push({ type: "search", name, args });
-    return this;
-  }
-
-  /** Set batch options */
-  withOptions(options: BatchOptions): this {
-    this.opts = { ...this.opts, ...options };
-    return this;
-  }
-
-  /** Set rollback function */
-  withRollback(rollback: RollbackFn): this {
-    this.rollbackFn = rollback;
-    return this;
-  }
-
-  /** Execute the batch */
-  async execute(executor: CommandExecutor): Promise<BatchReport> {
-    return executeBatch(this.commands, executor, this.opts, this.rollbackFn);
-  }
-
-  /** Get the command list */
-  getCommands(): readonly BatchCommand[] {
-    return this.commands;
-  }
-}