@aliou/pi-processes 0.6.3 → 0.7.0

package/src/manager.ts

@@ -14,6 +14,8 @@ import type { Writable } from "node:stream";
 import {
   type KillResult,
   LIVE_STATUSES,
+  type LogWatch,
+  type LogWatchStream,
   type ManagerEvent,
   type ProcessInfo,
   type ProcessStatus,
@@ -23,12 +25,24 @@ import {
 import { isProcessGroupAlive, killProcessGroup } from "./utils";
 import { spawnCommand } from "./utils/command-executor";
 
+interface ResolvedWatch {
+  index: number;
+  pattern: string;
+  regex: RegExp;
+  stream: LogWatchStream;
+  repeat: boolean;
+  fired: boolean;
+}
+
 interface ManagedProcess extends ProcessInfo {
   process: ChildProcess;
   stdin: Writable | null;
   stdinClosed: boolean;
   lastSignalSent: NodeJS.Signals | null;
   combinedFile: string;
+  stdoutPendingLine: string;
+  stderrPendingLine: string;
+  watches: ResolvedWatch[];
 }
 
 interface ProcessManagerOptions {
@@ -43,6 +57,9 @@ export class ProcessManager {
   private watcher: ReturnType<typeof setInterval> | null = null;
   private getConfiguredShellPath: () => string | undefined;
 
+  private lastOutputEmitAt: Map<string, number> = new Map();
+  private pendingOutputEmit: Map<string, NodeJS.Timeout> = new Map();
+
   constructor(options?: ProcessManagerOptions) {
     this.logDir = join(tmpdir(), `pi-processes-${Date.now()}`);
     mkdirSync(this.logDir, { recursive: true });
@@ -59,6 +76,48 @@ export class ProcessManager {
     this.events.emit("event", event);
   }
 
+  private notifyOutputChanged(id: string): void {
+    const now = Date.now();
+    const lastEmit = this.lastOutputEmitAt.get(id) ?? 0;
+    const elapsed = now - lastEmit;
+
+    if (elapsed >= 100) {
+      this.lastOutputEmitAt.set(id, now);
+      this.emit({ type: "process_output_changed", id });
+      return;
+    }
+
+    if (!this.pendingOutputEmit.has(id)) {
+      const delay = 100 - elapsed;
+      const timeout = setTimeout(() => {
+        this.pendingOutputEmit.delete(id);
+        // Invariant: every path that removes a process from `this.processes`
+        // must call `clearOutputChangedState(id)` first, which clears this
+        // timeout. This guard is a safety net, not a primary mechanism.
+        if (!this.processes.has(id)) return;
+        this.lastOutputEmitAt.set(id, Date.now());
+        this.emit({ type: "process_output_changed", id });
+      }, delay);
+      this.pendingOutputEmit.set(id, timeout);
+    }
+  }
+
+  private flushPendingOutputChanged(id: string): void {
+    const timeout = this.pendingOutputEmit.get(id);
+    if (!timeout) return;
+    clearTimeout(timeout);
+    this.pendingOutputEmit.delete(id);
+    this.lastOutputEmitAt.set(id, Date.now());
+    this.emit({ type: "process_output_changed", id });
+  }
+
+  private clearOutputChangedState(id: string): void {
+    const timeout = this.pendingOutputEmit.get(id);
+    if (timeout) clearTimeout(timeout);
+    this.pendingOutputEmit.delete(id);
+    this.lastOutputEmitAt.delete(id);
+  }
+
   private transition(managed: ManagedProcess, next: ProcessStatus): void {
     if (managed.status === next) return;
     managed.status = next;
@@ -107,6 +166,9 @@ export class ProcessManager {
         managed.endTime = Date.now();
       }
 
+      this.flushPendingOutputChanged(managed.id);
+      this.flushPendingLines(managed);
+
       if (managed.lastSignalSent) {
         managed.success = false;
         managed.exitCode = null;
@@ -125,6 +187,7 @@ export class ProcessManager {
     cwd: string,
     options?: StartOptions,
   ): ProcessInfo {
+    const resolvedWatches = this.resolveLogWatches(options?.logWatches);
     const id = `proc_${++this.counter}`;
     const stdoutFile = join(this.logDir, `${id}-stdout.log`);
     const stderrFile = join(this.logDir, `${id}-stderr.log`);
@@ -159,6 +222,9 @@ export class ProcessManager {
       stdin: child.stdin,
       stdinClosed: false,
       lastSignalSent: null,
+      stdoutPendingLine: "",
+      stderrPendingLine: "",
+      watches: resolvedWatches,
     };
 
     this.processes.set(id, managed);
@@ -179,15 +245,11 @@ export class ProcessManager {
     child.stdout?.on("data", (data: Buffer) => {
       try {
         appendFileSync(stdoutFile, data);
-        const lines = data.toString().split("\n");
-        // The last element after split is either empty (if data ended with \n)
-        // or a partial line. We write all parts with the prefix and newline.
-        const tagged = lines
-          .map((line, i) =>
-            i < lines.length - 1 ? `1:${line}\n` : line ? `1:${line}\n` : "",
-          )
-          .join("");
+        const lines = this.extractCompleteLines(managed, "stdout", data);
+        const tagged = lines.map((line) => `1:${line}\n`).join("");
         if (tagged) appendFileSync(combinedFile, tagged);
+        this.matchWatches(managed, "stdout", lines);
+        this.notifyOutputChanged(id);
       } catch {
         // Ignore
       }
@@ -196,13 +258,11 @@ export class ProcessManager {
     child.stderr?.on("data", (data: Buffer) => {
       try {
         appendFileSync(stderrFile, data);
-        const lines = data.toString().split("\n");
-        const tagged = lines
-          .map((line, i) =>
-            i < lines.length - 1 ? `2:${line}\n` : line ? `2:${line}\n` : "",
-          )
-          .join("");
+        const lines = this.extractCompleteLines(managed, "stderr", data);
+        const tagged = lines.map((line) => `2:${line}\n`).join("");
         if (tagged) appendFileSync(combinedFile, tagged);
+        this.matchWatches(managed, "stderr", lines);
+        this.notifyOutputChanged(id);
       } catch {
         // Ignore
       }
@@ -215,6 +275,9 @@ export class ProcessManager {
       managed.endTime = Date.now();
       managed.success = code === 0;
 
+      this.flushPendingOutputChanged(id);
+      this.flushPendingLines(managed);
+
       if (signal) {
         this.transition(managed, "killed");
       } else {
@@ -233,6 +296,8 @@ export class ProcessManager {
         managed.exitCode = -1;
         managed.success = false;
         managed.endTime = Date.now();
+        this.flushPendingOutputChanged(id);
+        this.flushPendingLines(managed);
         this.transition(managed, "exited");
       }
     });
@@ -254,22 +319,6 @@ export class ProcessManager {
     return managed ? this.toProcessInfo(managed) : null;
   }
 
-  find(query: string): ProcessInfo | null {
-    const byId = this.processes.get(query);
-    if (byId) return this.toProcessInfo(byId);
-
-    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,
@@ -405,6 +454,8 @@ export class ProcessManager {
       managed.success = false;
     }
 
+    this.flushPendingOutputChanged(id);
+    this.flushPendingLines(managed);
     this.transition(managed, "killed");
     return { ok: true, info: this.toProcessInfo(managed) };
   }
@@ -468,6 +519,7 @@ export class ProcessManager {
         // Ignore
       }
 
+      this.clearOutputChangedState(id);
       this.processes.delete(id);
       cleared++;
     }
@@ -501,6 +553,12 @@ export class ProcessManager {
   cleanup(): void {
     this.stopWatcher();
 
+    for (const timeout of this.pendingOutputEmit.values()) {
+      clearTimeout(timeout);
+    }
+    this.pendingOutputEmit.clear();
+    this.lastOutputEmitAt.clear();
+
     for (const p of this.processes.values()) {
       if (!LIVE_STATUSES.has(p.status)) continue;
       try {
@@ -531,6 +589,132 @@ export class ProcessManager {
     }
   }
 
+  private resolveLogWatches(input?: LogWatch[]): ResolvedWatch[] {
+    if (!input || input.length === 0) return [];
+
+    return input.map((watch, index) => {
+      const pattern = watch.pattern?.trim();
+      if (!pattern) {
+        throw new Error(`logWatches[${index}].pattern is required`);
+      }
+
+      let regex: RegExp;
+      try {
+        regex = new RegExp(pattern);
+      } catch (error) {
+        const message =
+          error instanceof Error ? error.message : "invalid regular expression";
+        throw new Error(
+          `Invalid log watch pattern at logWatches[${index}]: ${message}`,
+        );
+      }
+
+      const stream = watch.stream ?? "both";
+      if (stream !== "stdout" && stream !== "stderr" && stream !== "both") {
+        throw new Error(
+          `Invalid logWatches[${index}].stream: ${stream}. Expected stdout, stderr, or both`,
+        );
+      }
+
+      return {
+        index,
+        pattern,
+        regex,
+        stream,
+        repeat: watch.repeat ?? false,
+        fired: false,
+      };
+    });
+  }
+
+  private extractCompleteLines(
+    managed: ManagedProcess,
+    source: "stdout" | "stderr",
+    data: Buffer,
+  ): string[] {
+    const chunk = data.toString();
+    const pending =
+      source === "stdout"
+        ? managed.stdoutPendingLine
+        : managed.stderrPendingLine;
+    const merged = pending + chunk;
+    const parts = merged.split(/\r?\n/);
+    const completeLines = parts.slice(0, -1);
+    const nextPending = parts[parts.length - 1] ?? "";
+
+    if (source === "stdout") {
+      managed.stdoutPendingLine = nextPending;
+    } else {
+      managed.stderrPendingLine = nextPending;
+    }
+
+    return completeLines;
+  }
+
+  private flushPendingLines(managed: ManagedProcess): void {
+    if (managed.stdoutPendingLine) {
+      try {
+        appendFileSync(
+          managed.combinedFile,
+          `1:${managed.stdoutPendingLine}\n`,
+        );
+      } catch {
+        // Ignore
+      }
+      this.matchWatches(managed, "stdout", [managed.stdoutPendingLine]);
+      managed.stdoutPendingLine = "";
+    }
+
+    if (managed.stderrPendingLine) {
+      try {
+        appendFileSync(
+          managed.combinedFile,
+          `2:${managed.stderrPendingLine}\n`,
+        );
+      } catch {
+        // Ignore
+      }
+      this.matchWatches(managed, "stderr", [managed.stderrPendingLine]);
+      managed.stderrPendingLine = "";
+    }
+  }
+
+  private matchWatches(
+    managed: ManagedProcess,
+    source: "stdout" | "stderr",
+    lines: string[],
+  ): void {
+    if (managed.watches.length === 0 || lines.length === 0) return;
+
+    for (const line of lines) {
+      for (const watch of managed.watches) {
+        if (!watch.repeat && watch.fired) continue;
+        if (watch.stream !== "both" && watch.stream !== source) continue;
+
+        if (!watch.regex.test(line)) continue;
+
+        watch.fired = true;
+
+        this.emit({
+          type: "process_watch_matched",
+          match: {
+            processId: managed.id,
+            processName: managed.name,
+            processCommand: managed.command,
+            source,
+            line,
+            watch: {
+              index: watch.index,
+              pattern: watch.pattern,
+              stream: watch.stream,
+              repeat: watch.repeat,
+            },
+          },
+        });
+      }
+    }
+  }
+
   private readTailLines(filePath: string, lines: number): string[] {
     try {
       const content = readFileSync(filePath, "utf-8");

package/src/tools/actions/debug.ts

@@ -0,0 +1,148 @@
+import { ToolCallHeader } from "@aliou/pi-utils-ui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
+import type { ExecuteResult, ProcessInfo } from "../../constants";
+
+interface DebugParams {
+  preview?: "start" | "list" | "output" | "logs" | "error";
+}
+
+export function renderDebugCall(
+  args: DebugParams,
+  theme: Theme,
+): ToolCallHeader {
+  return new ToolCallHeader(
+    {
+      toolName: "Process",
+      action: "debug_preview",
+      mainArg: args.preview,
+    },
+    theme,
+  );
+}
+
+function mockProcess(overrides?: Partial<ProcessInfo>): ProcessInfo {
+  const now = Date.now();
+  return {
+    id: "proc_42",
+    name: "demo-server",
+    pid: 4242,
+    command: "pnpm dev --port 3000",
+    cwd: "/tmp/demo",
+    startTime: now - 12_000,
+    endTime: null,
+    status: "running",
+    exitCode: null,
+    success: null,
+    stdoutFile: "/tmp/pi-processes-demo/proc_42-stdout.log",
+    stderrFile: "/tmp/pi-processes-demo/proc_42-stderr.log",
+    alertOnSuccess: false,
+    alertOnFailure: true,
+    alertOnKill: false,
+    ...overrides,
+  };
+}
+
+/**
+ * Temporary no-side-effect previews for process tool renderers.
+ * Remove before release.
+ */
+export function executeDebugPreview(params: DebugParams): ExecuteResult {
+  const preview = params.preview ?? "start";
+
+  if (preview === "start") {
+    const process = mockProcess();
+    const message = [
+      `Started "${process.name}" (${process.id}, PID: ${process.pid})`,
+      "Log files:",
+      `  stdout: ${process.stdoutFile}`,
+      `  stderr: ${process.stderrFile}`,
+    ].join("\n");
+    return {
+      content: [{ type: "text", text: message }],
+      details: {
+        action: "start",
+        success: true,
+        message,
+        process,
+      },
+    };
+  }
+
+  if (preview === "list") {
+    const processes = [
+      mockProcess(),
+      mockProcess({
+        id: "proc_11",
+        name: "builder",
+        pid: 1011,
+        command: "pnpm build --watch",
+      }),
+      mockProcess({
+        id: "proc_10",
+        name: "tests",
+        pid: 1010,
+        command: "pnpm test",
+        status: "exited",
+        success: false,
+        endTime: Date.now() - 3_000,
+        exitCode: 1,
+      }),
+    ];
+
+    return {
+      content: [{ type: "text", text: "Debug preview: list" }],
+      details: {
+        action: "list",
+        success: true,
+        message: "Debug preview: list",
+        processes,
+      },
+    };
+  }
+
+  if (preview === "output") {
+    return {
+      content: [{ type: "text", text: "Debug preview: output" }],
+      details: {
+        action: "output",
+        success: true,
+        message:
+          '"demo-server" (proc_42) [running]: 4 stdout lines, 2 stderr lines',
+        output: {
+          status: "running",
+          stdout: [
+            "starting...",
+            "loading config",
+            "ready on http://localhost:3000",
+            "watching for changes",
+          ],
+          stderr: [
+            "warn: deprecated option in config",
+            "error: simulated stack trace line",
+          ],
+        },
+        logFiles: {
+          stdoutFile: "/tmp/pi-processes-demo/proc_42-stdout.log",
+          stderrFile: "/tmp/pi-processes-demo/proc_42-stderr.log",
+        },
+      },
+    };
+  }
+
+  if (preview === "logs") {
+    return {
+      content: [{ type: "text", text: "Debug preview: logs" }],
+      details: {
+        action: "logs",
+        success: true,
+        message: "Debug preview: logs",
+        logFiles: {
+          stdoutFile: "/tmp/pi-processes-demo/proc_42-stdout.log",
+          stderrFile: "/tmp/pi-processes-demo/proc_42-stderr.log",
+        },
+      },
+    };
+  }
+
+  throw new Error("Invalid logWatches[0].pattern: Unterminated group");
+}

package/src/tools/actions/index.ts

@@ -1,16 +1,30 @@
-import type { ExtensionContext } from "@mariozechner/pi-coding-agent";
-import type { ExecuteResult } from "../../constants";
+import { ToolBody, ToolCallHeader } from "@aliou/pi-utils-ui";
+import type {
+  AgentToolResult,
+  ExtensionContext,
+  Theme,
+  ToolRenderResultOptions,
+} from "@mariozechner/pi-coding-agent";
+import type { Component } from "@mariozechner/pi-tui";
+import type {
+  ExecuteResult,
+  ProcessAction,
+  ProcessesDetails,
+} from "../../constants";
 import type { ProcessManager } from "../../manager";
 import { executeClear } from "./clear";
-import { executeKill } from "./kill";
-import { executeList } from "./list";
-import { executeLogs } from "./logs";
-import { executeOutput } from "./output";
-import { executeStart } from "./start";
-import { executeWrite } from "./write";
+import { executeDebugPreview, renderDebugCall } from "./debug";
+import { executeKill, renderKillCall } from "./kill";
+import { executeList, renderListResult } from "./list";
+import { executeLogs, renderLogsCall, renderLogsResult } from "./logs";
+import { executeOutput, renderOutputCall, renderOutputResult } from "./output";
+import { executeStart, renderStartCall, renderStartResult } from "./start";
+import { executeWrite, renderWriteCall } from "./write";
+
+const DEBUG_PREVIEW_ENABLED = process.env.PI_PROCESSES_DEBUG_PREVIEW === "1";
 
 interface ActionParams {
-  action: string;
+  action: ProcessAction | string;
   command?: string;
   name?: string;
   id?: string;
@@ -19,6 +33,12 @@ interface ActionParams {
   alertOnSuccess?: boolean;
   alertOnFailure?: boolean;
   alertOnKill?: boolean;
+  logWatches?: Array<{
+    pattern: string;
+    stream?: "stdout" | "stderr" | "both";
+    repeat?: boolean;
+  }>;
+  preview?: "start" | "list" | "output" | "logs" | "error";
 }
 
 export async function executeAction(
@@ -41,14 +61,89 @@ export async function executeAction(
       return executeClear(manager);
     case "write":
       return executeWrite(params, manager);
+    case "debug_preview":
+      if (!DEBUG_PREVIEW_ENABLED) {
+        throw new Error(
+          "Action 'debug_preview' is disabled. Set PI_PROCESSES_DEBUG_PREVIEW=1 to enable.",
+        );
+      }
+      return executeDebugPreview(params);
     default:
       return {
         content: [{ type: "text", text: `Unknown action: ${params.action}` }],
         details: {
-          action: params.action,
+          action: params.action as ProcessAction,
           success: false,
           message: `Unknown action: ${params.action}`,
         },
       };
   }
 }
+
+export function renderActionCall(
+  args: ActionParams,
+  theme: Theme,
+): Component | undefined {
+  switch (args.action) {
+    case "start":
+      return renderStartCall(args, theme);
+    case "output":
+      return renderOutputCall(args, theme);
+    case "logs":
+      return renderLogsCall(args, theme);
+    case "kill":
+      return renderKillCall(args, theme);
+    case "write":
+      return renderWriteCall(args, theme);
+    case "debug_preview":
+      return renderDebugCall(args, theme);
+    default:
+      return new ToolCallHeader(
+        { toolName: "Process", action: args.action },
+        theme,
+      );
+  }
+}
+
+export function renderActionResult(
+  result: AgentToolResult<ProcessesDetails>,
+  options: ToolRenderResultOptions,
+  theme: Theme,
+): Component | undefined {
+  const { details } = result;
+
+  if (!details) {
+    return undefined;
+  }
+
+  switch (details.action) {
+    case "start":
+      return renderStartResult(result, options, theme);
+    case "list":
+      return renderListResult(result, options, theme);
+    case "output":
+      return renderOutputResult(result, options, theme);
+    case "logs":
+      return renderLogsResult(result, options, theme);
+    case "kill":
+    case "write":
+    case "clear":
+    case "debug_preview":
+      // Default rendering for these actions
+      return new ToolBody(
+        {
+          fields: [
+            {
+              label: "Result",
+              value: details.message,
+              showCollapsed: true,
+            },
+          ],
+        },
+        options,
+        theme,
+      );
+    default:
+      return undefined;
+  }
+}

package/src/tools/actions/kill.ts

@@ -1,3 +1,5 @@
+import { ToolCallHeader } from "@aliou/pi-utils-ui";
+import type { Theme } from "@mariozechner/pi-coding-agent";
 import type { ExecuteResult } from "../../constants";
 import type { ProcessManager } from "../../manager";
 
@@ -5,6 +7,17 @@ interface KillParams {
   id?: string;
 }
 
+export function renderKillCall(args: KillParams, theme: Theme): ToolCallHeader {
+  return new ToolCallHeader(
+    {
+      toolName: "Process",
+      action: "kill",
+      mainArg: args.id,
+    },
+    theme,
+  );
+}
+
 export async function executeKill(
   params: KillParams,
   manager: ProcessManager,
@@ -20,7 +33,7 @@ export async function executeKill(
     };
   }
 
-  const proc = manager.find(params.id);
+  const proc = manager.get(params.id);
   if (!proc) {
     const message = `Process not found: ${params.id}`;
     return {
@@ -53,7 +66,7 @@ export async function executeKill(
   if (result.reason === "timeout") {
     const message =
       `SIGTERM timed out for "${proc.name}" (${proc.id}). ` +
-      "Run /process:list and press x on terminate_timeout to force kill (SIGKILL).";
+      "Run /ps and press x on terminate_timeout to force kill (SIGKILL).";
     return {
       content: [{ type: "text", text: message }],
       details: {