@aliou/pi-processes 0.4.5 → 0.4.7

package/src/components/processes-component.ts

@@ -0,0 +1,450 @@
+import {
+  createPanelPadder,
+  renderPanelRule,
+  renderPanelTitleLine,
+} from "@aliou/pi-utils-ui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import { type Component, matchesKey, visibleWidth } from "@mariozechner/pi-tui";
+import { configLoader } from "../config";
+import type { ProcessInfo } from "../constants";
+import type { ProcessManager } from "../manager";
+import { stripAnsi } from "../utils";
+import { statusIcon, statusLabel } from "./status-format";
+
+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 formatBytes(bytes: number): string {
+  if (bytes >= 1024 * 1024) {
+    return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
+  }
+  if (bytes >= 1024) {
+    return `${(bytes / 1024).toFixed(1)}KB`;
+  }
+  return `${bytes}B`;
+}
+
+function truncate(str: string, maxLen: number): string {
+  if (maxLen <= 3) return str.slice(0, maxLen);
+  if (str.length <= maxLen) return str;
+  return `${str.slice(0, maxLen - 3)}...`;
+}
+
+export class ProcessesComponent implements Component {
+  private tui: { requestRender: () => void };
+  private theme: Theme;
+  private onClose: (processId?: string) => void;
+  private manager: ProcessManager;
+
+  private selectedIndex = 0;
+  private processScrollOffset = 0;
+  private logScrollOffset = 0;
+  private scrollInfo = { above: 0, below: 0 };
+  private cachedLines: string[] = [];
+  private cachedWidth = 0;
+  private unsubscribe: (() => void) | null = null;
+
+  constructor(
+    tui: { requestRender: () => void },
+    theme: Theme,
+    onClose: (processId?: string) => void,
+    manager: ProcessManager,
+  ) {
+    this.tui = tui;
+    this.theme = theme;
+    this.onClose = onClose;
+    this.manager = manager;
+
+    this.unsubscribe = this.manager.onEvent(() => {
+      this.invalidate();
+      this.tui.requestRender();
+    });
+  }
+
+  handleInput(data: string): boolean {
+    const processes = this.manager.list();
+
+    // Navigation
+    if (matchesKey(data, "down") || data === "j") {
+      if (processes.length > 0) {
+        this.selectedIndex = Math.min(
+          this.selectedIndex + 1,
+          processes.length - 1,
+        );
+        this.logScrollOffset = 0;
+        this.ensureProcessVisible(processes.length);
+        this.invalidate();
+        this.tui.requestRender();
+      }
+      return true;
+    }
+
+    if (matchesKey(data, "up") || data === "k") {
+      if (processes.length > 0) {
+        this.selectedIndex = Math.max(this.selectedIndex - 1, 0);
+        this.logScrollOffset = 0;
+        this.ensureProcessVisible(processes.length);
+        this.invalidate();
+        this.tui.requestRender();
+      }
+      return true;
+    }
+
+    // Scroll logs
+    if (data === "J") {
+      this.logScrollOffset = Math.max(0, this.logScrollOffset - 5);
+      this.invalidate();
+      this.tui.requestRender();
+      return true;
+    }
+
+    if (data === "K") {
+      this.logScrollOffset += 5;
+      this.invalidate();
+      this.tui.requestRender();
+      return true;
+    }
+
+    // Stream logs for selected process
+    if (matchesKey(data, "return")) {
+      if (processes.length > 0 && this.selectedIndex < processes.length) {
+        const proc = processes[this.selectedIndex];
+        if (proc) {
+          this.unsubscribe?.();
+          this.unsubscribe = null;
+          this.onClose(proc.id);
+        }
+      }
+      return true;
+    }
+
+    // Kill selected process
+    if (data === "x") {
+      if (processes.length > 0 && this.selectedIndex < processes.length) {
+        const proc = processes[this.selectedIndex];
+        if (proc?.status === "running") {
+          void this.manager.kill(proc.id, {
+            signal: "SIGTERM",
+            timeoutMs: 3000,
+          });
+        } else if (proc?.status === "terminate_timeout") {
+          void this.manager.kill(proc.id, {
+            signal: "SIGKILL",
+            timeoutMs: 200,
+          });
+        }
+      }
+      return true;
+    }
+
+    // Clear finished processes
+    if (data === "c" || data === "C") {
+      const cleared = this.manager.clearFinished();
+      if (cleared > 0) {
+        const remaining = this.manager.list();
+        if (this.selectedIndex >= remaining.length) {
+          this.selectedIndex = Math.max(0, remaining.length - 1);
+        }
+        this.ensureProcessVisible(remaining.length);
+        this.invalidate();
+        this.tui.requestRender();
+      }
+      return true;
+    }
+
+    // Close
+    if (matchesKey(data, "escape") || data === "q" || data === "Q") {
+      this.unsubscribe?.();
+      this.unsubscribe = null;
+      this.onClose();
+      return true;
+    }
+
+    return true;
+  }
+
+  private ensureProcessVisible(totalProcesses: number): void {
+    const maxVisibleProcesses =
+      configLoader.getConfig().processList.maxVisibleProcesses;
+    const visibleCount = Math.min(maxVisibleProcesses, totalProcesses);
+    if (this.selectedIndex < this.processScrollOffset) {
+      this.processScrollOffset = this.selectedIndex;
+    } else if (this.selectedIndex >= this.processScrollOffset + visibleCount) {
+      this.processScrollOffset = this.selectedIndex - visibleCount + 1;
+    }
+    this.processScrollOffset = Math.max(
+      0,
+      Math.min(this.processScrollOffset, totalProcesses - visibleCount),
+    );
+  }
+
+  invalidate(): void {
+    this.cachedWidth = 0;
+    this.cachedLines = [];
+  }
+
+  render(width: number): string[] {
+    if (width === this.cachedWidth && this.cachedLines.length > 0) {
+      return this.cachedLines;
+    }
+
+    const cfg = configLoader.getConfig().processList;
+    const maxVisibleProcesses = cfg.maxVisibleProcesses;
+    const maxPreviewLines = cfg.maxPreviewLines;
+
+    const theme = this.theme;
+    const dim = (s: string) => theme.fg("dim", s);
+    const accent = (s: string) => theme.fg("accent", s);
+    const warning = (s: string) => theme.fg("warning", s);
+
+    const lines: string[] = [];
+    const processes = this.manager.list();
+    const innerWidth = width - 2;
+
+    const padLine = createPanelPadder(width);
+
+    lines.push(renderPanelTitleLine("Background Processes", width, theme));
+
+    if (processes.length === 0) {
+      lines.push(padLine(""));
+      lines.push(padLine(dim("No background processes")));
+      lines.push(padLine(dim("Use the processes tool to start commands")));
+      lines.push(padLine(""));
+    } else {
+      const prefixWidth = 2;
+      const idWidth = 9;
+      const nameWidth = 15;
+      const statusWidth = 18;
+      const timeWidth = 8;
+      const sizeWidth = 8;
+
+      const hasProcessScroll = processes.length > maxVisibleProcesses;
+      const headerSuffixText = hasProcessScroll
+        ? ` [${this.processScrollOffset + 1}-${Math.min(this.processScrollOffset + maxVisibleProcesses, processes.length)}/${processes.length}]`
+        : "";
+      const headerSuffixLen = hasProcessScroll ? headerSuffixText.length : 0;
+
+      // Reserve space for scroll suffix in the command column
+      const cmdWidth = Math.max(
+        10,
+        innerWidth -
+          prefixWidth -
+          idWidth -
+          nameWidth -
+          statusWidth -
+          timeWidth -
+          sizeWidth -
+          headerSuffixLen,
+      );
+
+      lines.push(padLine(""));
+      const header =
+        "  " +
+        dim("ID".padEnd(idWidth)) +
+        dim("Name".padEnd(nameWidth)) +
+        dim("Command".padEnd(cmdWidth)) +
+        dim("Status".padEnd(statusWidth)) +
+        dim("Time".padEnd(timeWidth)) +
+        dim("Size".padStart(sizeWidth)) +
+        (hasProcessScroll ? dim(headerSuffixText) : "");
+      lines.push(padLine(header));
+      lines.push(renderPanelRule(width, theme));
+
+      const visibleProcessCount = Math.min(
+        maxVisibleProcesses,
+        processes.length,
+      );
+      const startIdx = this.processScrollOffset;
+      const endIdx = startIdx + visibleProcessCount;
+
+      for (let i = startIdx; i < endIdx; i++) {
+        const proc = processes[i];
+        if (!proc) continue;
+        const isSelected = i === this.selectedIndex;
+        const sizes = this.manager.getFileSize(proc.id);
+        const totalSize = sizes ? sizes.stdout + sizes.stderr : 0;
+
+        const statusText = this.formatStatus(proc);
+        const statusPadding =
+          statusWidth + (statusText.length - visibleWidth(statusText));
+
+        const row =
+          (isSelected
+            ? accent(proc.id.padEnd(idWidth))
+            : proc.id.padEnd(idWidth)) +
+          truncate(proc.name, nameWidth - 1).padEnd(nameWidth) +
+          truncate(proc.command, cmdWidth - 1).padEnd(cmdWidth) +
+          statusText.padEnd(statusPadding) +
+          formatRuntime(proc.startTime, proc.endTime).padEnd(timeWidth) +
+          formatBytes(totalSize).padStart(sizeWidth);
+
+        if (isSelected) {
+          lines.push(padLine(`${accent(">")} ${row}`));
+        } else {
+          lines.push(padLine(`  ${row}`));
+        }
+      }
+
+      for (let i = visibleProcessCount; i < maxVisibleProcesses; i++) {
+        lines.push(padLine(""));
+      }
+
+      if (this.selectedIndex < processes.length) {
+        const selected = processes[this.selectedIndex];
+        if (!selected) {
+          this.cachedLines = lines;
+          this.cachedWidth = width;
+          return this.cachedLines;
+        }
+        const output = this.manager.getOutput(selected.id, maxPreviewLines * 2);
+        const sizes = this.manager.getFileSize(selected.id);
+
+        lines.push(renderPanelRule(width, theme));
+
+        const logTitlePlain = `Output: ${selected.name} (${selected.id})`;
+        const sizeInfoPlain = sizes
+          ? ` stdout: ${formatBytes(sizes.stdout)}, stderr: ${formatBytes(sizes.stderr)}`
+          : "";
+        const combinedPlain = logTitlePlain + sizeInfoPlain;
+        // Truncate if combined exceeds innerWidth, prioritizing the title
+        if (combinedPlain.length <= innerWidth) {
+          const logTitle = `Output: ${accent(selected.name)} ${dim(`(${selected.id})`)}`;
+          const sizeInfo = sizes ? dim(sizeInfoPlain) : "";
+          lines.push(padLine(logTitle + sizeInfo));
+        } else {
+          const maxNameLen = Math.max(
+            8,
+            innerWidth -
+              (`Output:  (${selected.id})`.length + sizeInfoPlain.length),
+          );
+          const tName = truncate(selected.name, maxNameLen);
+          const logTitle = `Output: ${accent(tName)} ${dim(`(${selected.id})`)}`;
+          const sizeInfo = sizes ? dim(sizeInfoPlain) : "";
+          lines.push(padLine(logTitle + sizeInfo));
+        }
+        lines.push(padLine(""));
+
+        let renderedLines = 0;
+
+        if (output) {
+          const logLines: { type: "stdout" | "stderr"; text: string }[] = [];
+          for (const line of output.stdout) {
+            logLines.push({ type: "stdout", text: line });
+          }
+          for (const line of output.stderr) {
+            logLines.push({ type: "stderr", text: line });
+          }
+
+          if (logLines.length === 0) {
+            lines.push(padLine(dim("(no output yet)")));
+            renderedLines = 1;
+          } else {
+            const startIdx = Math.max(
+              0,
+              logLines.length - maxPreviewLines - this.logScrollOffset,
+            );
+            const endIdx = Math.max(0, logLines.length - this.logScrollOffset);
+            const visibleLines = logLines.slice(startIdx, endIdx);
+
+            this.scrollInfo.above = startIdx;
+            this.scrollInfo.below =
+              this.logScrollOffset > 0 ? logLines.length - endIdx : 0;
+
+            for (const line of visibleLines) {
+              const displayLine = truncate(
+                stripAnsi(line.text),
+                innerWidth - 2,
+              );
+              if (line.type === "stderr") {
+                lines.push(padLine(warning(displayLine)));
+              } else {
+                lines.push(padLine(displayLine));
+              }
+              renderedLines++;
+            }
+          }
+        }
+
+        while (renderedLines < maxPreviewLines) {
+          lines.push(padLine(""));
+          renderedLines++;
+        }
+      }
+    }
+
+    lines.push(renderPanelRule(width, theme));
+
+    const footerLeft =
+      `${dim("enter")} stream  ` +
+      `${dim("j/k")} select  ` +
+      `${dim("x")} term/kill  ` +
+      `${dim("c")} clear  ` +
+      `${dim("q")} quit`;
+
+    let footerRight = "";
+    if (this.scrollInfo.above > 0 || this.scrollInfo.below > 0) {
+      const parts: string[] = [];
+      if (this.scrollInfo.above > 0) {
+        parts.push(`↑${this.scrollInfo.above}`);
+      }
+      if (this.scrollInfo.below > 0) {
+        parts.push(`↓${this.scrollInfo.below}`);
+      }
+      footerRight = `${dim("J/K")} scroll ${dim(parts.join(" "))}`;
+    }
+
+    const footerLeftLen = visibleWidth(footerLeft);
+    const footerRightLen = visibleWidth(footerRight);
+    const footerGap = Math.max(2, innerWidth - footerLeftLen - footerRightLen);
+    const footer = footerLeft + " ".repeat(footerGap) + footerRight;
+
+    lines.push(padLine(footer));
+    lines.push(renderPanelRule(width, theme));
+
+    this.cachedLines = lines;
+    this.cachedWidth = width;
+
+    return this.cachedLines;
+  }
+
+  private formatStatus(proc: ProcessInfo): string {
+    const theme = this.theme;
+    const dim = (s: string) => theme.fg("dim", s);
+    const success = (s: string) => theme.fg("success", s);
+    const warning = (s: string) => theme.fg("warning", s);
+    const error = (s: string) => theme.fg("error", s);
+
+    const icon = statusIcon(proc.status, proc.success);
+    const label = statusLabel(proc);
+
+    switch (proc.status) {
+      case "running":
+        return success(`${icon} ${label}`);
+      case "terminating":
+        return warning(`${icon} ${label}`);
+      case "terminate_timeout":
+        return error(`${icon} ${label}`);
+      case "killed":
+        return warning(`${icon} ${label}`);
+      case "exited":
+        return proc.success
+          ? dim(`${icon} ${label}`)
+          : error(`${icon} ${label}`);
+      default:
+        return dim(`${icon} ${label}`);
+    }
+  }
+}

package/src/components/status-format.ts

@@ -0,0 +1,38 @@
+import type { ProcessInfo, ProcessStatus } from "../constants";
+
+export function statusLabel(proc: ProcessInfo): string {
+  switch (proc.status) {
+    case "running":
+      return "running";
+    case "terminating":
+      return "terminating";
+    case "terminate_timeout":
+      return "terminate_timeout";
+    case "killed":
+      return "killed";
+    case "exited":
+      return proc.success ? "exit(0)" : `exit(${proc.exitCode ?? "?"})`;
+    default:
+      return proc.status;
+  }
+}
+
+export function statusIcon(
+  status: ProcessStatus,
+  success: boolean | null,
+): string {
+  switch (status) {
+    case "running":
+      return "\u25CF"; // filled circle
+    case "terminating":
+      return "\u25CF"; // filled circle
+    case "terminate_timeout":
+      return "\u2717"; // x mark
+    case "exited":
+      return success ? "\u2713" : "\u2717";
+    case "killed":
+      return "\u2717";
+    default:
+      return "?";
+  }
+}

package/src/config.ts

@@ -0,0 +1,70 @@
+/**
+ * Configuration for the processes extension.
+ *
+ * Global: ~/.pi/agent/extensions/processes.json
+ * Memory: ephemeral overrides via /process:settings
+ */
+
+import { ConfigLoader } from "@aliou/pi-utils-settings";
+
+export interface ProcessesConfig {
+  processList?: {
+    /** Max visible processes in the /process:list TUI list. */
+    maxVisibleProcesses?: number;
+    /** Max log preview lines shown below the selected process. */
+    maxPreviewLines?: number;
+  };
+  output?: {
+    /** Default number of tail lines returned to the agent. */
+    defaultTailLines?: number;
+    /** Hard cap on output lines returned to the agent. */
+    maxOutputLines?: number;
+  };
+  execution?: {
+    /** Absolute shell path override. Leave unset to auto-resolve. */
+    shellPath?: string;
+  };
+  widget?: {
+    /** Show the status widget below the editor. */
+    showStatusWidget?: boolean;
+  };
+}
+
+export interface ResolvedProcessesConfig {
+  processList: {
+    maxVisibleProcesses: number;
+    maxPreviewLines: number;
+  };
+  output: {
+    defaultTailLines: number;
+    maxOutputLines: number;
+  };
+  execution: {
+    shellPath?: string;
+  };
+  widget: {
+    showStatusWidget: boolean;
+  };
+}
+
+const DEFAULT_CONFIG: ResolvedProcessesConfig = {
+  processList: {
+    maxVisibleProcesses: 8,
+    maxPreviewLines: 12,
+  },
+  output: {
+    defaultTailLines: 100,
+    maxOutputLines: 200,
+  },
+  execution: {},
+  widget: {
+    showStatusWidget: true,
+  },
+};
+
+export const configLoader = new ConfigLoader<
+  ProcessesConfig,
+  ResolvedProcessesConfig
+>("process", DEFAULT_CONFIG, {
+  scopes: ["global", "memory"],
+});

package/src/constants/index.ts

@@ -0,0 +1,11 @@
+export type {
+  ExecuteResult,
+  KillResult,
+  ManagerEvent,
+  ProcessesDetails,
+  ProcessInfo,
+  ProcessStatus,
+  StartOptions,
+} from "./types";
+
+export { LIVE_STATUSES, MESSAGE_TYPE_PROCESS_UPDATE } from "./types";

package/src/constants/types.ts

@@ -0,0 +1,65 @@
+// Custom message type for process update notifications
+export const MESSAGE_TYPE_PROCESS_UPDATE = "ad-process:update";
+
+export type ProcessStatus =
+  | "running"
+  | "terminating"
+  | "terminate_timeout"
+  | "exited"
+  | "killed";
+
+export const LIVE_STATUSES: ReadonlySet<ProcessStatus> = new Set([
+  "running",
+  "terminating",
+  "terminate_timeout",
+]);
+
+export interface ProcessInfo {
+  id: string;
+  name: string;
+  pid: number; // On Unix, this is also the PGID (process group leader)
+  command: string;
+  cwd: string;
+  startTime: number;
+  endTime: number | null;
+  status: ProcessStatus;
+  exitCode: number | null;
+  success: boolean | null; // null if running, true if exit code 0, false otherwise
+  stdoutFile: string;
+  stderrFile: string;
+  alertOnSuccess: boolean;
+  alertOnFailure: boolean;
+  alertOnKill: boolean;
+}
+
+export type ManagerEvent =
+  | { type: "process_started"; info: ProcessInfo }
+  | { type: "process_status_changed"; info: ProcessInfo; prev: ProcessStatus }
+  | { type: "process_ended"; info: ProcessInfo }
+  | { type: "processes_changed" };
+
+export type KillResult =
+  | { ok: true; info: ProcessInfo }
+  | { ok: false; info: ProcessInfo; reason: "not_found" | "timeout" | "error" };
+
+export interface StartOptions {
+  alertOnSuccess?: boolean;
+  alertOnFailure?: boolean;
+  alertOnKill?: boolean;
+}
+
+export interface ProcessesDetails {
+  action: string;
+  success: boolean;
+  message: string;
+  process?: ProcessInfo;
+  processes?: ProcessInfo[];
+  output?: { stdout: string[]; stderr: string[]; status: string };
+  logFiles?: { stdoutFile: string; stderrFile: string };
+  cleared?: number;
+}
+
+export interface ExecuteResult {
+  content: Array<{ type: "text"; text: string }>;
+  details: ProcessesDetails;
+}

package/src/hooks/cleanup.ts

@@ -0,0 +1,10 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ProcessManager } from "../manager";
+
+export function setupCleanupHook(pi: ExtensionAPI, manager: ProcessManager) {
+  pi.on("session_shutdown", () => {
+    manager.stopWatcher();
+    manager.shutdownKillAll();
+    manager.cleanup();
+  });
+}

package/src/hooks/index.ts

@@ -0,0 +1,18 @@
+import type { ExtensionAPI } from "@mariozechner/pi-coding-agent";
+import type { ProcessManager } from "../manager";
+import { setupCleanupHook } from "./cleanup";
+import { setupMessageRenderer } from "./message-renderer";
+import { setupProcessEndHook } from "./process-end";
+import { setupProcessWidget } from "./widget";
+
+export function setupProcessesHooks(pi: ExtensionAPI, manager: ProcessManager) {
+  setupCleanupHook(pi, manager);
+  setupProcessEndHook(pi, manager);
+
+  // Set up widget AFTER process-end so it chains onto the existing callback
+  const widget = setupProcessWidget(pi, manager);
+
+  setupMessageRenderer(pi);
+
+  return widget;
+}