@pi-unipi/utility 0.1.1 → 0.2.1

package/src/lifecycle/process.ts

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

package/src/tools/batch.ts

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

package/src/tools/env.ts

@@ -0,0 +1,134 @@
+/**
+ * @pi-unipi/utility — Environment Info Tool
+ *
+ * Show environment information for debugging.
+ */
+
+import { existsSync, readdirSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { homedir } from "node:os";
+import type { EnvironmentInfo } from "../types.js";
+
+/** Collect environment information */
+export function getEnvironmentInfo(): EnvironmentInfo {
+  const unipiModules: string[] = [];
+  const configPaths: string[] = [];
+  const extensionPaths: string[] = [];
+
+  // Try to discover unipi modules from node_modules
+  try {
+    const nodeModules = resolve(process.cwd(), "node_modules");
+    if (existsSync(nodeModules)) {
+      const scopePath = join(nodeModules, "@pi-unipi");
+      if (existsSync(scopePath)) {
+        for (const entry of readdirSync(scopePath)) {
+          if (entry.startsWith(".")) continue;
+          const pkgPath = join(scopePath, entry, "package.json");
+          if (existsSync(pkgPath)) {
+            unipiModules.push(`@pi-unipi/${entry}`);
+          }
+        }
+      }
+    }
+  } catch {
+    // Best effort
+  }
+
+  // Config paths
+  const globalConfig = join(homedir(), ".unipi", "config");
+  const projectConfig = resolve(process.cwd(), ".unipi", "config");
+
+  if (existsSync(globalConfig)) {
+    configPaths.push(globalConfig);
+  }
+  if (existsSync(projectConfig)) {
+    configPaths.push(projectConfig);
+  }
+
+  // Extension paths (pi-specific)
+  try {
+    const piDir = join(homedir(), ".pi");
+    if (existsSync(piDir)) {
+      extensionPaths.push(piDir);
+    }
+  } catch {
+    // Best effort
+  }
+
+  return {
+    nodeVersion: process.version,
+    piVersion: getPiVersion(),
+    os: `${process.platform} ${process.arch}`,
+    platform: process.platform,
+    unipiModules,
+    configPaths,
+    extensionPaths,
+  };
+}
+
+/** Try to determine Pi version */
+function getPiVersion(): string {
+  try {
+    // Try to read from pi's package
+    const piPkg = resolve(
+      process.cwd(),
+      "node_modules",
+      "@mariozechner",
+      "pi-coding-agent",
+      "package.json",
+    );
+    if (existsSync(piPkg)) {
+      const { readFileSync } = require("node:fs");
+      const pkg = JSON.parse(readFileSync(piPkg, "utf-8"));
+      return pkg.version || "unknown";
+    }
+  } catch {
+    // Best effort
+  }
+  return "unknown";
+}
+
+/** Format environment info as markdown */
+export function formatEnvironmentInfo(info: EnvironmentInfo): string {
+  const lines = [
+    "## 🖥️ Environment",
+    "",
+    `| Key | Value |`,
+    `|-----|-------|`,
+    `| Node.js | ${info.nodeVersion} |`,
+    `| Pi | ${info.piVersion} |`,
+    `| OS | ${info.os} |`,
+    `| Platform | ${info.platform} |`,
+    "",
+    "### Unipi Modules",
+    "",
+  ];
+
+  if (info.unipiModules.length === 0) {
+    lines.push("*No @pi-unipi modules detected in node_modules.*");
+  } else {
+    for (const mod of info.unipiModules) {
+      lines.push(`- ${mod}`);
+    }
+  }
+
+  lines.push("", "### Config Paths", "");
+  if (info.configPaths.length === 0) {
+    lines.push("*No config paths found.*");
+  } else {
+    for (const path of info.configPaths) {
+      lines.push(`- \`${path}\``);
+    }
+  }
+
+  lines.push("", "### Extension Paths", "");
+  if (info.extensionPaths.length === 0) {
+    lines.push("*No extension paths found.*");
+  } else {
+    for (const path of info.extensionPaths) {
+      lines.push(`- \`${path}\``);
+    }
+  }
+
+  return lines.join("\n");
+}