@aliou/pi-processes 0.6.4 → 0.7.1

package/src/manager.test.ts

@@ -0,0 +1,331 @@
+import { afterEach, describe, expect, it } from "vitest";
+import type { ManagerEvent } from "./constants";
+import { ProcessManager } from "./manager";
+
+function waitForEnd(manager: ProcessManager, id: string): Promise<void> {
+  return new Promise((resolve) => {
+    const unsub = manager.onEvent((e) => {
+      if (e.type === "process_ended" && e.info.id === id) {
+        unsub();
+        resolve();
+      }
+    });
+  });
+}
+
+function collectEvents(manager: ProcessManager): ManagerEvent[] {
+  const events: ManagerEvent[] = [];
+  // Unsubscribe not stored; manager.cleanup() in afterEach clears all listeners.
+  manager.onEvent((e) => events.push(e));
+  return events;
+}
+
+describe("process_output_changed", () => {
+  let manager: ProcessManager;
+
+  afterEach(() => {
+    manager.cleanup();
+  });
+
+  it("emits process_output_changed on stdout", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+    const info = manager.start("test", "echo hello", "/tmp");
+    await waitForEnd(manager, info.id);
+
+    const outputEvents = events.filter(
+      (e) => e.type === "process_output_changed",
+    );
+    expect(outputEvents.length).toBeGreaterThanOrEqual(1);
+    expect(outputEvents[0]).toEqual({
+      type: "process_output_changed",
+      id: info.id,
+    });
+  });
+
+  it("emits process_output_changed on stderr", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+    const info = manager.start("test", "echo err >&2", "/tmp");
+    await waitForEnd(manager, info.id);
+
+    const outputEvents = events.filter(
+      (e) => e.type === "process_output_changed",
+    );
+    expect(outputEvents.length).toBeGreaterThanOrEqual(1);
+    expect(outputEvents[0]).toEqual({
+      type: "process_output_changed",
+      id: info.id,
+    });
+  });
+
+  it("throttles rapid output", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+    const info = manager.start("test", "seq 1 200", "/tmp");
+    await waitForEnd(manager, info.id);
+
+    const outputEvents = events.filter(
+      (e) => e.type === "process_output_changed",
+    );
+    // Should be significantly fewer than 200 due to throttling
+    expect(outputEvents.length).toBeGreaterThanOrEqual(1);
+    expect(outputEvents.length).toBeLessThan(50);
+  });
+
+  it("stdout and stderr share one throttle bucket", async () => {
+    manager = new ProcessManager();
+
+    // Dual-stream burst: writes to both stdout and stderr rapidly
+    const events2 = collectEvents(manager);
+    const info2 = manager.start(
+      "dual",
+      "bash -c 'for i in $(seq 1 50); do echo out$i; echo err$i >&2; done'",
+      "/tmp",
+    );
+    await waitForEnd(manager, info2.id);
+    const dualCount = events2.filter(
+      (e) => e.type === "process_output_changed",
+    ).length;
+
+    // Both streams share one throttle bucket, so total events should be low
+    expect(dualCount).toBeLessThan(30);
+  });
+
+  it("trailing emit fires after burst ends", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+    const info = manager.start("test", "seq 1 100", "/tmp");
+    await waitForEnd(manager, info.id);
+
+    // There should be at least one output event, and a process_ended event
+    const outputEvents = events.filter(
+      (e) => e.type === "process_output_changed",
+    );
+    const endEvents = events.filter((e) => e.type === "process_ended");
+    expect(outputEvents.length).toBeGreaterThanOrEqual(1);
+    expect(endEvents.length).toBe(1);
+  });
+
+  it("final output event before process_ended", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+    const info = manager.start("test", "echo hello", "/tmp");
+    await waitForEnd(manager, info.id);
+
+    let lastOutputIdx = -1;
+    for (let i = events.length - 1; i >= 0; i--) {
+      if (events[i].type === "process_output_changed") {
+        lastOutputIdx = i;
+        break;
+      }
+    }
+    const endIdx = events.findIndex((e) => e.type === "process_ended");
+
+    expect(lastOutputIdx).toBeGreaterThanOrEqual(0);
+    expect(endIdx).toBeGreaterThanOrEqual(0);
+    expect(lastOutputIdx).toBeLessThan(endIdx);
+  });
+
+  it("no output events for silent process", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+    const info = manager.start("test", "true", "/tmp");
+    await waitForEnd(manager, info.id);
+
+    // Wait a bit for any stale trailing emits
+    await new Promise((r) => setTimeout(r, 200));
+
+    const outputEvents = events.filter(
+      (e) => e.type === "process_output_changed",
+    );
+    expect(outputEvents.length).toBe(0);
+  });
+
+  it("no stale events after clearFinished", async () => {
+    manager = new ProcessManager();
+    const info = manager.start("test", "seq 1 50", "/tmp");
+    await waitForEnd(manager, info.id);
+
+    manager.clearFinished();
+
+    const lateEvents: ManagerEvent[] = [];
+    manager.onEvent((e) => lateEvents.push(e));
+
+    await new Promise((r) => setTimeout(r, 200));
+
+    const staleOutput = lateEvents.filter(
+      (e) => e.type === "process_output_changed",
+    );
+    expect(staleOutput.length).toBe(0);
+  });
+
+  it("events carry correct process id with multiple processes", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+
+    const info1 = manager.start("proc1", "echo one", "/tmp");
+    const info2 = manager.start("proc2", "echo two", "/tmp");
+
+    await Promise.all([
+      waitForEnd(manager, info1.id),
+      waitForEnd(manager, info2.id),
+    ]);
+
+    const outputEvents = events.filter(
+      (e) => e.type === "process_output_changed",
+    );
+
+    for (const e of outputEvents) {
+      if (e.type === "process_output_changed") {
+        expect([info1.id, info2.id]).toContain(e.id);
+      }
+    }
+
+    // Both processes should have at least one output event
+    const ids = new Set(
+      outputEvents
+        .filter(
+          (e): e is Extract<ManagerEvent, { type: "process_output_changed" }> =>
+            e.type === "process_output_changed",
+        )
+        .map((e) => e.id),
+    );
+    expect(ids.has(info1.id)).toBe(true);
+    expect(ids.has(info2.id)).toBe(true);
+  });
+});
+
+describe("process_watch_matched", () => {
+  let manager: ProcessManager;
+
+  afterEach(() => {
+    manager.cleanup();
+  });
+
+  it("fires once by default on first matching line", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+
+    const info = manager.start(
+      "watch-once",
+      "bash -c 'echo ready; echo ready; echo ready'",
+      "/tmp",
+      {
+        logWatches: [{ pattern: "ready" }],
+      },
+    );
+
+    await waitForEnd(manager, info.id);
+
+    const matches = events.filter((e) => e.type === "process_watch_matched");
+    expect(matches).toHaveLength(1);
+
+    const first = matches[0];
+    if (first.type === "process_watch_matched") {
+      expect(first.match.processId).toBe(info.id);
+      expect(first.match.source).toBe("stdout");
+      expect(first.match.watch.repeat).toBe(false);
+      expect(first.match.line).toBe("ready");
+    }
+  });
+
+  it("supports repeat watches", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+
+    const info = manager.start(
+      "watch-repeat",
+      "bash -c 'echo done; echo done; echo done'",
+      "/tmp",
+      {
+        logWatches: [{ pattern: "done", repeat: true }],
+      },
+    );
+
+    await waitForEnd(manager, info.id);
+
+    const matches = events.filter((e) => e.type === "process_watch_matched");
+    expect(matches).toHaveLength(3);
+  });
+
+  it("respects stream scoping", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+
+    const info = manager.start(
+      "watch-stream",
+      "bash -c 'echo out; echo err >&2'",
+      "/tmp",
+      {
+        logWatches: [{ pattern: "err", stream: "stderr" }],
+      },
+    );
+
+    await waitForEnd(manager, info.id);
+
+    const matches = events.filter((e) => e.type === "process_watch_matched");
+    expect(matches).toHaveLength(1);
+
+    const match = matches[0];
+    if (match.type === "process_watch_matched") {
+      expect(match.match.source).toBe("stderr");
+      expect(match.match.line).toBe("err");
+    }
+  });
+
+  it("stream both matches stdout and stderr", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+
+    const info = manager.start(
+      "watch-both",
+      "bash -c 'echo marker; echo marker >&2'",
+      "/tmp",
+      {
+        logWatches: [{ pattern: "marker", stream: "both", repeat: true }],
+      },
+    );
+
+    await waitForEnd(manager, info.id);
+
+    const matches = events.filter((e) => e.type === "process_watch_matched");
+    expect(matches).toHaveLength(2);
+
+    const sources = new Set(
+      matches
+        .filter(
+          (e): e is Extract<ManagerEvent, { type: "process_watch_matched" }> =>
+            e.type === "process_watch_matched",
+        )
+        .map((e) => e.match.source),
+    );
+
+    expect(sources.has("stdout")).toBe(true);
+    expect(sources.has("stderr")).toBe(true);
+  });
+
+  it("matches trailing partial line at process end", async () => {
+    manager = new ProcessManager();
+    const events = collectEvents(manager);
+
+    const info = manager.start("watch-trailing", "printf ready", "/tmp", {
+      logWatches: [{ pattern: "ready" }],
+    });
+
+    await waitForEnd(manager, info.id);
+
+    const matches = events.filter((e) => e.type === "process_watch_matched");
+    expect(matches).toHaveLength(1);
+  });
+
+  it("throws for invalid watch regex", () => {
+    manager = new ProcessManager();
+
+    expect(() =>
+      manager.start("bad-watch", "echo ok", "/tmp", {
+        logWatches: [{ pattern: "(" }],
+      }),
+    ).toThrowError(/Invalid log watch pattern/);
+  });
+});

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");