@aliou/pi-processes 0.9.4 → 0.10.0

package/src/manager/index.ts

@@ -0,0 +1,182 @@
+import { EventEmitter } from "node:events";
+
+import type {
+  KillResult,
+  ManagerEvent,
+  ProcessInfo,
+  WriteResult,
+} from "../types";
+import { formatProcess } from "./internal-types";
+import { ProcessLogStore } from "./process-log-store";
+import { ProcessOutput } from "./process-output";
+import { ProcessRegistry } from "./process-registry";
+import { ProcessRuntimeController } from "./process-runtime-controller";
+
+interface ProcessManagerOptions {
+  getConfiguredShellPath?: () => string | undefined;
+}
+
+export class ProcessManager {
+  private events = new EventEmitter();
+
+  private registry: ProcessRegistry;
+  private logStore: ProcessLogStore;
+  private output: ProcessOutput;
+  private runtime: ProcessRuntimeController;
+
+  constructor(options?: ProcessManagerOptions) {
+    const emit = (event: ManagerEvent): void => {
+      this.events.emit("event", event);
+    };
+
+    this.registry = new ProcessRegistry();
+    this.logStore = new ProcessLogStore();
+
+    this.output = new ProcessOutput({
+      emit,
+      logStore: this.logStore,
+    });
+
+    this.runtime = new ProcessRuntimeController({
+      registry: this.registry,
+      logs: this.logStore,
+      output: this.output,
+      emit,
+      getConfiguredShellPath:
+        options?.getConfiguredShellPath ?? (() => undefined),
+    });
+  }
+
+  onEvent(listener: (event: ManagerEvent) => void): () => void {
+    this.events.on("event", listener);
+    return () => this.events.off("event", listener);
+  }
+
+  start(name: string, command: string, cwd: string): ProcessInfo {
+    const managed = this.runtime.start(name, command, cwd);
+    return formatProcess(managed);
+  }
+
+  list(): ProcessInfo[] {
+    return this.registry.list();
+  }
+
+  get(id: string): ProcessInfo | null {
+    return this.registry.getPublicInfo(id);
+  }
+
+  rename(id: string, name: string): ProcessInfo | null {
+    const info = this.registry.rename(id, name);
+    if (info) {
+      this.events.emit("event", {
+        type: "processes_changed",
+      } satisfies ManagerEvent);
+    }
+    return info;
+  }
+
+  getOutput(
+    id: string,
+    tailLines = 100,
+  ): { stdout: string[]; stderr: string[]; status: string } | null {
+    const managed = this.registry.getRecord(id);
+    if (!managed) return null;
+
+    return {
+      stdout: this.logStore.readTailLines(managed.stdoutFile, tailLines),
+      stderr: this.logStore.readTailLines(managed.stderrFile, tailLines),
+      status: managed.status,
+    };
+  }
+
+  getCombinedOutput(
+    id: string,
+    tailLines = 100,
+  ): Array<{ type: "stdout" | "stderr"; text: string }> | null {
+    const managed = this.registry.getRecord(id);
+    if (!managed) return null;
+    return this.logStore.getCombinedOutput(managed.combinedFile, tailLines);
+  }
+
+  /**
+   * Return output capped at 16 MiB per stream. Use getLogFiles() and stream
+   * the returned paths when an exact, unbounded read is required.
+   */
+  getFullOutput(id: string): { stdout: string; stderr: string } | null {
+    const managed = this.registry.getRecord(id);
+    if (!managed) return null;
+    return {
+      stdout: this.logStore.readFullFile(managed.stdoutFile),
+      stderr: this.logStore.readFullFile(managed.stderrFile),
+    };
+  }
+
+  getLogFiles(
+    id: string,
+  ): { stdoutFile: string; stderrFile: string; combinedFile: string } | null {
+    const managed = this.registry.getRecord(id);
+    if (!managed) return null;
+    return {
+      stdoutFile: managed.stdoutFile,
+      stderrFile: managed.stderrFile,
+      combinedFile: managed.combinedFile,
+    };
+  }
+
+  getFileSize(id: string): { stdout: number; stderr: number } | null {
+    const managed = this.registry.getRecord(id);
+    if (!managed) return null;
+    return this.logStore.getFileSize({
+      stdoutFile: managed.stdoutFile,
+      stderrFile: managed.stderrFile,
+      combinedFile: managed.combinedFile,
+    });
+  }
+
+  async kill(
+    id: string,
+    opts?: { signal?: NodeJS.Signals; timeoutMs?: number },
+  ): Promise<KillResult> {
+    return this.runtime.kill(id, opts);
+  }
+
+  writeToStdin(
+    id: string,
+    data: string,
+    opts?: { end?: boolean },
+  ): WriteResult {
+    return this.runtime.writeToStdin(id, data, opts);
+  }
+
+  killAll(): void {
+    this.runtime.killAll();
+  }
+
+  clearFinished(): number {
+    return this.runtime.clearFinished();
+  }
+
+  stopWatcher(): void {
+    this.runtime.stopWatcher();
+  }
+
+  cleanup(): void {
+    this.runtime.beginShutdown();
+    this.runtime.stopWatcher();
+    this.output.clearAll();
+    this.runtime.killAllLive();
+    this.logStore.cleanup();
+  }
+
+  [Symbol.dispose](): void {
+    this.cleanup();
+  }
+}
+
+export type {
+  KillResult,
+  ManagerEvent,
+  ProcessInfo,
+  ProcessStatus,
+  WriteResult,
+} from "../types";

package/src/manager/internal-types.ts

@@ -0,0 +1,130 @@
+import type { Writable } from "node:stream";
+
+import type {
+  ProcessEndReason,
+  ProcessInfo,
+  ProcessSignalInfo,
+  ProcessStatus,
+} from "../types";
+
+export interface ProcessLogPaths {
+  stdoutFile: string;
+  stderrFile: string;
+  combinedFile: string;
+}
+
+/**
+ * Stable process metadata and lifecycle status.
+ *
+ * This is the part of a managed process that can be safely projected into the
+ * public `ProcessInfo` API. It intentionally contains no Node handles, mutable
+ * stream buffers, or manager bookkeeping fields.
+ */
+interface ProcessPublicState {
+  id: string;
+  name: string;
+  pid: number;
+  command: string;
+  cwd: string;
+  startTime: number;
+  endTime: number | null;
+  status: ProcessStatus;
+  exitCode: number | null;
+  success: boolean | null;
+  stdoutFile: string;
+  stderrFile: string;
+  endReason: ProcessEndReason | null;
+  signal: ProcessSignalInfo | null;
+  errorMessage: string | null;
+}
+
+/**
+ * Process handles and signal bookkeeping used by runtime control.
+ *
+ * Only `ProcessRuntimeController` should need these fields. They are not safe
+ * to expose because they allow direct mutation/control outside manager methods.
+ */
+interface ProcessRuntimeState {
+  stdin: Writable | null;
+  stdinClosed: boolean;
+  lastSignalSent: NodeJS.Signals | null;
+  completionSequence: number | null;
+}
+
+/**
+ * Internal log storage details.
+ *
+ * `stdoutFile` and `stderrFile` are public because agents/users can inspect
+ * them. The combined log file is an implementation detail used by manager/UI
+ * read APIs, so it stays internal.
+ */
+interface ProcessLogState {
+  combinedFile: string;
+}
+
+/**
+ * Output parser state for incomplete line chunks.
+ *
+ * Node streams can split a single logical line across multiple chunks. These
+ * buffers let `ProcessOutput` emit only completed lines in events/logs.
+ */
+interface ProcessLineBufferState {
+  stdoutPendingLine: Buffer;
+  stderrPendingLine: Buffer;
+  /** The line head was emitted; discard the tail through the next newline. */
+  stdoutLineOverflowed: boolean;
+  /** The line head was emitted; discard the tail through the next newline. */
+  stderrLineOverflowed: boolean;
+}
+
+/**
+ * Output lines accumulated since the last `process_output_changed` event.
+ *
+ * `ProcessOutput` drains this buffer when it emits an output event. This
+ * gives extension code live lines without re-reading log files or polling.
+ */
+interface ProcessOutputEventBufferState {
+  appendedLines: Array<{ type: "stdout" | "stderr"; text: string }>;
+  droppedLineCount: number;
+}
+
+/**
+ * Internal mutable record owned by `ProcessManager`.
+ *
+ * This is intentionally broader than public `ProcessInfo`: it combines public
+ * lifecycle state with runtime handles, log implementation details, and output
+ * parser buffers. Callers must receive `ProcessInfo` snapshots instead, created
+ * by `formatProcess()` below.
+ */
+export interface ManagedProcessRecord
+  extends ProcessPublicState,
+    ProcessRuntimeState,
+    ProcessLogState,
+    ProcessLineBufferState,
+    ProcessOutputEventBufferState {}
+
+/**
+ * Convert an internal mutable record into the public process snapshot.
+ *
+ * Keep this function explicit instead of using object spread so new internal
+ * fields cannot accidentally leak into the public manager API.
+ */
+export function formatProcess(record: ManagedProcessRecord): ProcessInfo {
+  return {
+    id: record.id,
+    name: record.name,
+    pid: record.pid,
+    command: record.command,
+    cwd: record.cwd,
+    startTime: record.startTime,
+    endTime: record.endTime,
+    status: record.status,
+    exitCode: record.exitCode,
+    success: record.success,
+    stdoutFile: record.stdoutFile,
+    stderrFile: record.stderrFile,
+    endReason: record.endReason,
+    signal: record.signal,
+    errorMessage: record.errorMessage,
+  };
+}

package/src/manager/limits.ts

@@ -0,0 +1,15 @@
+/** Max bytes retained for an unterminated line before force-flush. */
+export const MAX_PENDING_LINE_BYTES = 64 * 1024;
+/** Max bytes retained for any single line in an event payload. */
+export const MAX_LINE_BYTES = 32 * 1024;
+/** Max lines carried in one process_output_changed payload. */
+export const MAX_LINES_PER_EMIT = 2000;
+/** Max bytes read when tailing a log file. */
+export const MAX_TAIL_READ_BYTES = 2 * 1024 * 1024;
+/** Max bytes retained per log file before truncate-and-restart. */
+export const MAX_LOG_FILE_BYTES = 64 * 1024 * 1024;
+export const TRUNCATION_SUFFIX = " … [line truncated]";
+/** Max finished process records retained after the grace period. */
+export const MAX_FINISHED_RECORDS = 50;
+/** Keep recently finished records available to the UI before reaping. */
+export const FINISHED_RECORD_GRACE_MS = 5 * 60 * 1000;