@aliou/pi-processes 0.1.0

package/hooks/process-end.ts

@@ -0,0 +1,103 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+import { MESSAGE_TYPE_PROCESS_UPDATE } from "../constants";
+import type { ProcessInfo, ProcessManager } from "../manager";
+
+function formatRuntime(startTime: number, endTime: number | null): string {
+  const end = endTime ?? Date.now();
+  const ms = end - startTime;
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    return `${hours}h ${minutes % 60}m`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m ${seconds % 60}s`;
+  }
+  return `${seconds}s`;
+}
+
+interface ProcessUpdateDetails {
+  processId: string;
+  processName: string;
+  command: string;
+  status: "exited" | "killed";
+  exitCode: number | null;
+  success: boolean;
+  runtime: string;
+}
+
+export function setupProcessEndHook(pi: ExtensionAPI, manager: ProcessManager) {
+  let latestContext: ExtensionContext | null = null;
+
+  // Capture context from session events
+  pi.on("session_start", async (_event, ctx) => {
+    latestContext = ctx;
+  });
+
+  pi.on("turn_start", async (_event, ctx) => {
+    latestContext = ctx;
+  });
+
+  pi.on("turn_end", async (_event, ctx) => {
+    latestContext = ctx;
+  });
+
+  // Set callback for process end events
+  manager.onProcessEnd = (info: ProcessInfo) => {
+    // Check notification preferences
+    const shouldNotify =
+      (info.status === "killed" && info.notifyOnKill) ||
+      (info.status === "exited" && info.success && info.notifyOnSuccess) ||
+      (info.status === "exited" && !info.success && info.notifyOnFailure);
+
+    const runtime = formatRuntime(info.startTime, info.endTime);
+
+    // Build notification message
+    let message: string;
+    let level: "info" | "error" | "warning";
+
+    if (info.status === "killed") {
+      message = `Process '${info.name}' was terminated (${runtime})`;
+      level = "warning";
+    } else if (info.success) {
+      message = `Process '${info.name}' completed successfully (${runtime})`;
+      level = "info";
+    } else {
+      message = `Process '${info.name}' crashed with exit code ${info.exitCode ?? "?"} (${runtime})`;
+      level = "error";
+    }
+
+    // Always notify user via UI
+    if (latestContext?.hasUI) {
+      latestContext.ui.notify(message, level);
+    }
+
+    // Only send message to agent if notification preferences allow
+    if (shouldNotify) {
+      const details: ProcessUpdateDetails = {
+        processId: info.id,
+        processName: info.name,
+        command: info.command,
+        status: info.status as "exited" | "killed",
+        exitCode: info.exitCode,
+        success: info.success ?? false,
+        runtime,
+      };
+
+      pi.sendMessage(
+        {
+          customType: MESSAGE_TYPE_PROCESS_UPDATE,
+          content: message,
+          display: true,
+          details,
+        },
+        { triggerTurn: false },
+      );
+    }
+  };
+}

package/hooks/widget.ts

@@ -0,0 +1,144 @@
+import type {
+  ExtensionAPI,
+  ExtensionContext,
+} from "@mariozechner/pi-coding-agent";
+import type { ProcessInfo, ProcessManager } from "../manager";
+
+const WIDGET_ID = "processes-status";
+
+function formatRuntime(startTime: number, endTime: number | null): string {
+  const end = endTime ?? Date.now();
+  const ms = end - startTime;
+  const seconds = Math.floor(ms / 1000);
+  const minutes = Math.floor(seconds / 60);
+  const hours = Math.floor(minutes / 60);
+
+  if (hours > 0) {
+    return `${hours}h${minutes % 60}m`;
+  }
+  if (minutes > 0) {
+    return `${minutes}m${seconds % 60}s`;
+  }
+  return `${seconds}s`;
+}
+
+function formatProcessStatus(
+  proc: ProcessInfo,
+  theme: ExtensionContext["ui"]["theme"],
+): string {
+  const runtime = formatRuntime(proc.startTime, proc.endTime);
+  const name =
+    proc.name.length > 20 ? `${proc.name.slice(0, 17)}...` : proc.name;
+
+  if (proc.status === "running") {
+    return `${theme.fg("accent", name)} ${theme.fg("dim", runtime)}`;
+  }
+  if (proc.status === "killed") {
+    return `${theme.fg("warning", name)} ${theme.fg("dim", "killed")}`;
+  }
+  if (proc.success) {
+    return `${theme.fg("dim", name)} ${theme.fg("success", "done")}`;
+  }
+  return `${theme.fg("error", name)} ${theme.fg("error", `exit(${proc.exitCode ?? "?"})`)}`;
+}
+
+function renderWidget(
+  processes: ProcessInfo[],
+  theme: ExtensionContext["ui"]["theme"],
+): string[] {
+  if (processes.length === 0) {
+    return [];
+  }
+
+  const running = processes.filter((p) => p.status === "running");
+  const finished = processes.filter((p) => p.status !== "running");
+
+  const parts: string[] = [];
+
+  // Show running processes first
+  for (const proc of running) {
+    parts.push(formatProcessStatus(proc, theme));
+  }
+
+  // Show finished processes (most recent first, limit to 3)
+  const recentFinished = finished
+    .sort((a, b) => (b.endTime ?? 0) - (a.endTime ?? 0))
+    .slice(0, 3);
+
+  for (const proc of recentFinished) {
+    parts.push(formatProcessStatus(proc, theme));
+  }
+
+  // If there are more finished processes, show count
+  const hiddenCount = finished.length - recentFinished.length;
+  if (hiddenCount > 0) {
+    parts.push(theme.fg("dim", `+${hiddenCount} more`));
+  }
+
+  const prefix = theme.fg("dim", "processes: ");
+  return [prefix + parts.join(theme.fg("dim", " | "))];
+}
+
+export function setupProcessWidget(pi: ExtensionAPI, manager: ProcessManager) {
+  let latestContext: ExtensionContext | null = null;
+  let refreshInterval: ReturnType<typeof setInterval> | null = null;
+
+  function updateWidget() {
+    if (!latestContext?.hasUI) return;
+
+    const processes = manager.list();
+    const lines = renderWidget(processes, latestContext.ui.theme);
+
+    if (lines.length === 0) {
+      latestContext.ui.setWidget(WIDGET_ID, undefined);
+    } else {
+      latestContext.ui.setWidget(WIDGET_ID, lines, {
+        placement: "belowEditor",
+      });
+    }
+  }
+
+  function startRefresh() {
+    if (refreshInterval) return;
+    refreshInterval = setInterval(() => {
+      const hasRunning = manager.list().some((p) => p.status === "running");
+      if (hasRunning) {
+        updateWidget();
+      }
+    }, 1000);
+  }
+
+  function stopRefresh() {
+    if (refreshInterval) {
+      clearInterval(refreshInterval);
+      refreshInterval = null;
+    }
+  }
+
+  // Capture context and update widget
+  pi.on("session_start", async (_event, ctx) => {
+    latestContext = ctx;
+    updateWidget();
+    startRefresh();
+  });
+
+  pi.on("session_switch", async (_event, ctx) => {
+    latestContext = ctx;
+    updateWidget();
+  });
+
+  pi.on("session_shutdown", async () => {
+    stopRefresh();
+  });
+
+  // Chain into process end callback
+  const originalOnProcessEnd = manager.onProcessEnd;
+  manager.onProcessEnd = (info) => {
+    originalOnProcessEnd?.call(manager, info);
+    updateWidget();
+  };
+
+  return {
+    update: updateWidget,
+  };
+}

package/index.ts

@@ -0,0 +1,13 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import { setupProcessesCommands } from "./commands";
+import { setupProcessesHooks } from "./hooks";
+import { ProcessManager } from "./manager";
+import { setupProcessesTools } from "./tools";
+
+export default function (pi: ExtensionAPI) {
+  const manager = new ProcessManager();
+
+  setupProcessesHooks(pi, manager);
+  setupProcessesTools(pi, manager);
+  setupProcessesCommands(pi, manager);
+}

package/manager.ts

@@ -0,0 +1,405 @@
+import { type ChildProcess, spawn } from "node:child_process";
+import {
+  appendFileSync,
+  mkdirSync,
+  readFileSync,
+  rmSync,
+  statSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+export interface ProcessInfo {
+  id: string;
+  name: string; // Friendly name for display
+  pid: number;
+  command: string;
+  cwd: string;
+  startTime: number;
+  endTime: number | null;
+  status: "running" | "exited" | "killed";
+  exitCode: number | null;
+  success: boolean | null; // null if running, true if exit code 0, false otherwise
+  stdoutFile: string;
+  stderrFile: string;
+  notifyOnSuccess: boolean;
+  notifyOnFailure: boolean;
+  notifyOnKill: boolean;
+}
+
+interface ManagedProcess extends ProcessInfo {
+  process: ChildProcess;
+}
+
+// Generate a friendly name from command
+function inferName(command: string): string {
+  const cmd = command.toLowerCase();
+
+  // Dev servers
+  if (cmd.includes("dev") && cmd.includes("backend")) return "backend-dev";
+  if (cmd.includes("dev") && cmd.includes("frontend")) return "frontend-dev";
+  if (cmd.includes("dev") && cmd.includes("api")) return "api-dev";
+  if (
+    cmd.includes("pnpm dev") ||
+    cmd.includes("npm run dev") ||
+    cmd.includes("yarn dev")
+  )
+    return "dev-server";
+  if (cmd.includes("vite")) return "vite-dev";
+  if (cmd.includes("next dev")) return "next-dev";
+
+  // Build
+  if (cmd.includes("build")) return "build";
+  if (cmd.includes("compile")) return "compile";
+
+  // Tests
+  if (cmd.includes("test") || cmd.includes("jest") || cmd.includes("vitest"))
+    return "tests";
+
+  // Watch
+  if (cmd.includes("watch")) return "watcher";
+
+  // Logs
+  if (cmd.includes("tail")) return "log-tail";
+
+  // Docker
+  if (cmd.includes("docker-compose") || cmd.includes("docker compose"))
+    return "docker";
+
+  // Database
+  if (
+    cmd.includes("postgres") ||
+    cmd.includes("mysql") ||
+    cmd.includes("mongo")
+  )
+    return "database";
+
+  // Extract first meaningful word
+  const words = command.split(/\s+/);
+  const firstWord = (words[0] ?? "process")
+    .replace(/^\.\//, "")
+    .replace(/\.(sh|js|ts|py)$/, "");
+  return firstWord.slice(0, 20);
+}
+
+export class ProcessManager {
+  private processes: Map<string, ManagedProcess> = new Map();
+  private counter = 0;
+  private logDir: string;
+  onProcessEnd?: (info: ProcessInfo) => void;
+
+  constructor() {
+    this.logDir = join(tmpdir(), `pi-processes-${Date.now()}`);
+    mkdirSync(this.logDir, { recursive: true });
+  }
+
+  private emitProcessEnd(info: ProcessInfo): void {
+    this.onProcessEnd?.(info);
+  }
+
+  start(
+    command: string,
+    cwd: string,
+    name?: string,
+    options?: {
+      notifyOnSuccess?: boolean;
+      notifyOnFailure?: boolean;
+      notifyOnKill?: boolean;
+    },
+  ): ProcessInfo {
+    const id = `proc_${++this.counter}`;
+    const friendlyName = name || inferName(command);
+    const stdoutFile = join(this.logDir, `${id}-stdout.log`);
+    const stderrFile = join(this.logDir, `${id}-stderr.log`);
+
+    appendFileSync(stdoutFile, "");
+    appendFileSync(stderrFile, "");
+
+    const child = spawn(command, {
+      cwd,
+      shell: true,
+      stdio: ["ignore", "pipe", "pipe"],
+      detached: false,
+    });
+
+    const managed: ManagedProcess = {
+      id,
+      name: friendlyName,
+      pid: child.pid ?? -1,
+      command,
+      cwd,
+      startTime: Date.now(),
+      endTime: null,
+      status: "running",
+      exitCode: null,
+      success: null,
+      stdoutFile,
+      stderrFile,
+      notifyOnSuccess: options?.notifyOnSuccess ?? false,
+      notifyOnFailure: options?.notifyOnFailure ?? true,
+      notifyOnKill: options?.notifyOnKill ?? false,
+      process: child,
+    };
+
+    child.stdout?.on("data", (data: Buffer) => {
+      try {
+        appendFileSync(stdoutFile, data);
+      } catch {
+        // Ignore write errors
+      }
+    });
+
+    child.stderr?.on("data", (data: Buffer) => {
+      try {
+        appendFileSync(stderrFile, data);
+      } catch {
+        // Ignore write errors
+      }
+    });
+
+    child.on("close", (code, signal) => {
+      // Already handled (e.g., by checkRunningProcesses detecting external kill)
+      if (managed.status !== "running") {
+        return;
+      }
+      managed.exitCode = code;
+      managed.endTime = Date.now();
+      managed.success = code === 0;
+      managed.status = signal ? "killed" : "exited";
+      this.emitProcessEnd(this.toProcessInfo(managed));
+    });
+
+    child.on("error", (err) => {
+      try {
+        appendFileSync(stderrFile, `Process error: ${err.message}\n`);
+      } catch {
+        // Ignore
+      }
+      managed.status = "exited";
+      managed.exitCode = -1;
+      managed.success = false;
+      managed.endTime = Date.now();
+      this.emitProcessEnd(this.toProcessInfo(managed));
+    });
+
+    this.processes.set(id, managed);
+
+    return this.toProcessInfo(managed);
+  }
+
+  list(): ProcessInfo[] {
+    // Check if any "running" processes have actually exited
+    this.checkRunningProcesses();
+    return Array.from(this.processes.values()).map((p) =>
+      this.toProcessInfo(p),
+    );
+  }
+
+  get(id: string): ProcessInfo | null {
+    this.checkRunningProcesses();
+    const managed = this.processes.get(id);
+    return managed ? this.toProcessInfo(managed) : null;
+  }
+
+  // Find by ID or name (partial match)
+  find(query: string): ProcessInfo | null {
+    this.checkRunningProcesses();
+
+    // Exact ID match first
+    const byId = this.processes.get(query);
+    if (byId) return this.toProcessInfo(byId);
+
+    // Search by name (case insensitive, partial match)
+    const queryLower = query.toLowerCase();
+    for (const managed of this.processes.values()) {
+      if (managed.name.toLowerCase().includes(queryLower)) {
+        return this.toProcessInfo(managed);
+      }
+      if (managed.command.toLowerCase().includes(queryLower)) {
+        return this.toProcessInfo(managed);
+      }
+    }
+    return null;
+  }
+
+  getOutput(
+    id: string,
+    tailLines = 100,
+  ): { stdout: string[]; stderr: string[]; status: string } | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+
+    return {
+      stdout: this.readTailLines(managed.stdoutFile, tailLines),
+      stderr: this.readTailLines(managed.stderrFile, tailLines),
+      status: managed.status,
+    };
+  }
+
+  getFullOutput(id: string): { stdout: string; stderr: string } | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+
+    try {
+      return {
+        stdout: readFileSync(managed.stdoutFile, "utf-8"),
+        stderr: readFileSync(managed.stderrFile, "utf-8"),
+      };
+    } catch {
+      return { stdout: "", stderr: "" };
+    }
+  }
+
+  getLogFiles(id: string): { stdoutFile: string; stderrFile: string } | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+    return {
+      stdoutFile: managed.stdoutFile,
+      stderrFile: managed.stderrFile,
+    };
+  }
+
+  kill(id: string): boolean {
+    const managed = this.processes.get(id);
+    if (!managed) return false;
+
+    if (managed.status !== "running") {
+      return true;
+    }
+
+    // Disable kill notification since this is intentional
+    managed.notifyOnKill = false;
+
+    managed.status = "killed";
+    managed.endTime = Date.now();
+    managed.success = false;
+
+    try {
+      managed.process.kill("SIGTERM");
+
+      setTimeout(() => {
+        try {
+          if (!managed.process.killed) {
+            managed.process.kill("SIGKILL");
+          }
+        } catch {
+          // Process may already be dead
+        }
+      }, 3000);
+
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  // Clear finished processes (not running)
+  clearFinished(): number {
+    let cleared = 0;
+    for (const [id, managed] of this.processes) {
+      if (managed.status !== "running") {
+        // Clean up log files
+        try {
+          rmSync(managed.stdoutFile, { force: true });
+          rmSync(managed.stderrFile, { force: true });
+        } catch {
+          // Ignore
+        }
+        this.processes.delete(id);
+        cleared++;
+      }
+    }
+    return cleared;
+  }
+
+  killAll(): void {
+    for (const [id] of this.processes) {
+      this.kill(id);
+    }
+  }
+
+  // Check if a PID is still alive (works across platforms)
+  private isProcessAlive(pid: number): boolean {
+    try {
+      // Signal 0 checks if process exists without actually sending a signal
+      process.kill(pid, 0);
+      return true;
+    } catch (error) {
+      // If error code is ESRCH, process doesn't exist
+      // If error code is EPERM, process exists but we don't have permission (still alive)
+      const err = error as NodeJS.ErrnoException;
+      return err.code === "EPERM";
+    }
+  }
+
+  // Check all running processes and update status if they've exited
+  private checkRunningProcesses(): void {
+    for (const managed of this.processes.values()) {
+      if (managed.status === "running" && !this.isProcessAlive(managed.pid)) {
+        // Process is no longer alive but we didn't get the close event yet
+        // Mark it as exited with unknown exit code
+        managed.status = "exited";
+        managed.exitCode = null;
+        managed.success = false;
+        managed.endTime = Date.now();
+        this.emitProcessEnd(this.toProcessInfo(managed));
+      }
+    }
+  }
+
+  cleanup(): void {
+    this.killAll();
+    try {
+      rmSync(this.logDir, { recursive: true, force: true });
+    } catch {
+      // Ignore cleanup errors
+    }
+  }
+
+  private readTailLines(filePath: string, lines: number): string[] {
+    try {
+      const content = readFileSync(filePath, "utf-8");
+      const allLines = content.split("\n");
+      if (allLines.length > 0 && allLines[allLines.length - 1] === "") {
+        allLines.pop();
+      }
+      return allLines.slice(-lines);
+    } catch {
+      return [];
+    }
+  }
+
+  getFileSize(id: string): { stdout: number; stderr: number } | null {
+    const managed = this.processes.get(id);
+    if (!managed) return null;
+
+    try {
+      return {
+        stdout: statSync(managed.stdoutFile).size,
+        stderr: statSync(managed.stderrFile).size,
+      };
+    } catch {
+      return { stdout: 0, stderr: 0 };
+    }
+  }
+
+  private toProcessInfo(managed: ManagedProcess): ProcessInfo {
+    return {
+      id: managed.id,
+      name: managed.name,
+      pid: managed.pid,
+      command: managed.command,
+      cwd: managed.cwd,
+      startTime: managed.startTime,
+      endTime: managed.endTime,
+      status: managed.status,
+      exitCode: managed.exitCode,
+      success: managed.success,
+      stdoutFile: managed.stdoutFile,
+      stderrFile: managed.stderrFile,
+      notifyOnSuccess: managed.notifyOnSuccess,
+      notifyOnFailure: managed.notifyOnFailure,
+      notifyOnKill: managed.notifyOnKill,
+    };
+  }
+}

package/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "@aliou/pi-processes",
+  "version": "0.1.0",
+  "type": "module",
+  "private": false,
+  "keywords": [
+    "pi-package",
+    "pi-extension",
+    "pi",
+    "processes"
+  ],
+  "pi": {
+    "extensions": [
+      "./index.ts"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "files": [
+    "*.ts",
+    "commands",
+    "hooks",
+    "tools",
+    "README.md"
+  ],
+  "dependencies": {
+    "@sinclair/typebox": "^0.34.41"
+  },
+  "peerDependencies": {
+    "@mariozechner/pi-ai": ">=0.49.0",
+    "@mariozechner/pi-coding-agent": ">=0.49.0",
+    "@mariozechner/pi-tui": ">=0.49.0"
+  }
+}