@aria-cli/tools 1.0.9 → 1.0.11

package/src/executors/process-registry.ts

@@ -1,570 +0,0 @@
-/**
- * @aria/tools - Spawned Process Registry
- *
- * Tracks PIDs of child processes spawned by shell executors.
- * Allows bulk cleanup (SIGTERM then SIGKILL) when a RunSession closes,
- * preventing orphaned processes from lingering.
- */
-
-/**
- * How long to wait after SIGTERM before escalating to SIGKILL (ms).
- */
-const SIGKILL_TIMEOUT_MS = 2000;
-const POST_KILL_POLL_INTERVAL_MS = 25;
-const PROCESS_REAP_POLL_INTERVAL_MS = 250;
-
-/**
- * Max number of exited-process snapshots to retain for observability.
- */
-const EXIT_HISTORY_LIMIT = 100;
-
-export interface TrackedProcessMetadata {
-  command?: string;
-  args?: string[];
-  cwd?: string;
-  interactive?: boolean;
-}
-
-export interface ProcessExitMetadata {
-  exitCode?: number | null;
-  signal?: string | null;
-}
-
-export interface ProcessInfoSnapshot {
-  pid: number;
-  command: string | null;
-  args: string[];
-  cwd: string | null;
-  interactive: boolean;
-  startedAt: string;
-  runtimeMs: number;
-  status: "running" | "exited";
-  exitCode: number | null;
-  signal: string | null;
-  endedAt: string | null;
-}
-
-export interface ProcessWaitResult {
-  pid: number;
-  status: "running" | "exited" | "not_found";
-  timedOut: boolean;
-  process?: ProcessInfoSnapshot;
-}
-
-interface ActiveProcessRecord {
-  pid: number;
-  command: string | null;
-  args: string[];
-  cwd: string | null;
-  interactive: boolean;
-  reapOnExit: boolean;
-  deferredExitCode: number | null;
-  deferredSignal: string | null;
-  startedAtMs: number;
-  startedAt: string;
-}
-
-interface ExitedProcessRecord extends ActiveProcessRecord {
-  exitCode: number | null;
-  signal: string | null;
-  endedAtMs: number;
-  endedAt: string;
-}
-
-/**
- * Registry that tracks spawned child process PIDs.
- *
- * Usage:
- * - Shell executors call `add(pid)` after spawning a process
- * - Shell executors call `remove(pid)` when a process exits normally
- * - RunSession calls `killAll()` during close() to clean up orphans
- */
-export class SpawnedProcessRegistry {
-  private readonly active = new Map<number, ActiveProcessRecord>();
-  private readonly exited = new Map<number, ExitedProcessRecord>();
-  private readonly waiters = new Map<number, Array<(record: ExitedProcessRecord) => void>>();
-  private readonly reapers = new Map<number, NodeJS.Timeout>();
-
-  /**
-   * Register a spawned process PID.
-   */
-  add(pid: number, metadata: TrackedProcessMetadata = {}): void {
-    const existing = this.active.get(pid);
-    if (existing) {
-      this.active.set(pid, {
-        ...existing,
-        command: metadata.command ?? existing.command,
-        args: metadata.args ? [...metadata.args] : existing.args,
-        cwd: metadata.cwd ?? existing.cwd,
-        interactive: metadata.interactive ?? existing.interactive,
-      });
-      return;
-    }
-
-    const startedAtMs = Date.now();
-    this.active.set(pid, {
-      pid,
-      command: metadata.command ?? null,
-      args: metadata.args ? [...metadata.args] : [],
-      cwd: metadata.cwd ?? null,
-      interactive: metadata.interactive ?? false,
-      reapOnExit: isTrackedProcessAlive(pid),
-      deferredExitCode: null,
-      deferredSignal: null,
-      startedAtMs,
-      startedAt: new Date(startedAtMs).toISOString(),
-    });
-    this.exited.delete(pid);
-    this.ensureReaper(pid);
-  }
-
-  /**
-   * Deregister a process PID (e.g., after normal exit).
-   */
-  remove(pid: number, exit: ProcessExitMetadata = {}): void {
-    const record = this.active.get(pid);
-    if (!record) {
-      const exitedRecord = this.exited.get(pid);
-      if (exitedRecord) {
-        this.exited.set(pid, {
-          ...exitedRecord,
-          exitCode: exitedRecord.exitCode ?? normalizeExitCode(exit.exitCode),
-          signal:
-            exitedRecord.exitCode !== null
-              ? exitedRecord.signal
-              : (exitedRecord.signal ?? normalizeSignal(exit.signal)),
-        });
-      }
-      return;
-    }
-
-    this.clearReaper(pid);
-    this.active.delete(pid);
-
-    const endedAtMs = Date.now();
-    const recordedExitCode = normalizeExitCode(exit.exitCode) ?? record.deferredExitCode;
-    const exitedRecord: ExitedProcessRecord = {
-      ...record,
-      exitCode: recordedExitCode,
-      signal: record.deferredSignal ?? normalizeSignal(exit.signal),
-      endedAtMs,
-      endedAt: new Date(endedAtMs).toISOString(),
-    };
-    this.exited.set(pid, exitedRecord);
-    this.pruneExitedHistory();
-
-    const waiters = this.waiters.get(pid);
-    if (waiters && waiters.length > 0) {
-      this.waiters.delete(pid);
-      for (const waiter of waiters) {
-        waiter(exitedRecord);
-      }
-    }
-  }
-
-  /**
-   * Check whether a PID is tracked.
-   */
-  has(pid: number): boolean {
-    return this.active.has(pid);
-  }
-
-  recordExitMetadata(pid: number, exit: ProcessExitMetadata = {}): void {
-    const record = this.active.get(pid);
-    if (!record) {
-      return;
-    }
-    record.deferredExitCode = normalizeExitCode(exit.exitCode);
-    record.deferredSignal = normalizeSignal(exit.signal);
-  }
-
-  /**
-   * Number of tracked PIDs.
-   */
-  get size(): number {
-    return this.active.size;
-  }
-
-  /**
-   * Return a snapshot of all tracked PIDs.
-   */
-  getAll(): number[] {
-    return [...this.active.keys()];
-  }
-
-  /**
-   * Return process snapshots for observability.
-   */
-  listProcesses(options: { includeExited?: boolean } = {}): ProcessInfoSnapshot[] {
-    const now = Date.now();
-    const snapshots: ProcessInfoSnapshot[] = [];
-    for (const pid of [...this.active.keys()]) {
-      this.reapIfExited(pid);
-    }
-
-    for (const record of this.active.values()) {
-      snapshots.push(this.toRunningSnapshot(record, now));
-    }
-
-    if (options.includeExited) {
-      for (const record of this.exited.values()) {
-        snapshots.push(this.toExitedSnapshot(record));
-      }
-    }
-
-    return snapshots.sort((a, b) => a.pid - b.pid);
-  }
-
-  /**
-   * Return a single process snapshot by PID.
-   */
-  getProcess(pid: number): ProcessInfoSnapshot | undefined {
-    this.reapIfExited(pid);
-    const activeRecord = this.active.get(pid);
-    if (activeRecord) {
-      return this.toRunningSnapshot(activeRecord);
-    }
-
-    const exitedRecord = this.exited.get(pid);
-    if (exitedRecord) {
-      return this.toExitedSnapshot(exitedRecord);
-    }
-
-    return undefined;
-  }
-
-  /**
-   * Wait for a tracked process to exit, up to timeoutMs.
-   */
-  async waitForExit(pid: number, timeoutMs = 30_000): Promise<ProcessWaitResult> {
-    this.reapIfExited(pid);
-    const exitedRecord = this.exited.get(pid);
-    if (exitedRecord) {
-      return {
-        pid,
-        status: "exited",
-        timedOut: false,
-        process: this.toExitedSnapshot(exitedRecord),
-      };
-    }
-
-    const activeRecord = this.active.get(pid);
-    if (!activeRecord) {
-      return {
-        pid,
-        status: "not_found",
-        timedOut: false,
-      };
-    }
-
-    if (timeoutMs <= 0) {
-      return {
-        pid,
-        status: "running",
-        timedOut: true,
-        process: this.toRunningSnapshot(activeRecord),
-      };
-    }
-
-    return new Promise((resolve) => {
-      let settled = false;
-
-      const settle = (result: ProcessWaitResult): void => {
-        if (settled) return;
-        settled = true;
-        resolve(result);
-      };
-
-      const removeWaiter = (target: (record: ExitedProcessRecord) => void): void => {
-        const existing = this.waiters.get(pid);
-        if (!existing) return;
-        const next = existing.filter((entry) => entry !== target);
-        if (next.length === 0) {
-          this.waiters.delete(pid);
-        } else {
-          this.waiters.set(pid, next);
-        }
-      };
-
-      const waiter = (record: ExitedProcessRecord): void => {
-        clearTimeout(timeoutId);
-        removeWaiter(waiter);
-        settle({
-          pid,
-          status: "exited",
-          timedOut: false,
-          process: this.toExitedSnapshot(record),
-        });
-      };
-
-      const timeoutId = setTimeout(() => {
-        const current = this.active.get(pid);
-        if (current) {
-          removeWaiter(waiter);
-          settle({
-            pid,
-            status: "running",
-            timedOut: true,
-            process: this.toRunningSnapshot(current),
-          });
-          return;
-        }
-
-        const exited = this.exited.get(pid);
-        if (exited) {
-          removeWaiter(waiter);
-          settle({
-            pid,
-            status: "exited",
-            timedOut: false,
-            process: this.toExitedSnapshot(exited),
-          });
-          return;
-        }
-
-        removeWaiter(waiter);
-        settle({
-          pid,
-          status: "not_found",
-          timedOut: false,
-        });
-      }, timeoutMs);
-
-      const existingWaiters = this.waiters.get(pid) ?? [];
-      existingWaiters.push(waiter);
-      this.waiters.set(pid, existingWaiters);
-
-      // Close the race window where remove() can happen between the initial
-      // active check above and waiter registration.
-      const exitedAfterRegistration = this.exited.get(pid);
-      if (exitedAfterRegistration) {
-        clearTimeout(timeoutId);
-        removeWaiter(waiter);
-        settle({
-          pid,
-          status: "exited",
-          timedOut: false,
-          process: this.toExitedSnapshot(exitedAfterRegistration),
-        });
-        return;
-      }
-
-      if (!this.active.has(pid)) {
-        clearTimeout(timeoutId);
-        removeWaiter(waiter);
-        settle({
-          pid,
-          status: "not_found",
-          timedOut: false,
-        });
-      }
-    });
-  }
-
-  /**
-   * Send SIGTERM to all tracked PIDs, then SIGKILL after a timeout
-   * for any that are still alive. Clears the registry afterwards.
-   *
-   * Returns the list of PIDs that were signalled.
-   */
-  async killAll(): Promise<number[]> {
-    const tracked = [...this.active.keys()];
-    if (tracked.length === 0) return [];
-
-    // Phase 1: SIGTERM all tracked processes
-    const alive: number[] = [];
-    const signaledTerm = new Set<number>();
-    for (const pid of tracked) {
-      if (isTrackedProcessAlive(pid)) {
-        if (sendSignalToTrackedProcess(pid, "SIGTERM")) {
-          alive.push(pid);
-          signaledTerm.add(pid);
-        }
-      }
-    }
-
-    if (alive.length === 0) {
-      for (const pid of tracked) {
-        this.remove(pid);
-      }
-      return tracked;
-    }
-
-    // Phase 2: Wait, then SIGKILL any survivors
-    await new Promise<void>((resolve) => setTimeout(resolve, SIGKILL_TIMEOUT_MS));
-
-    const signaledKill = new Set<number>();
-    for (const pid of alive) {
-      if (isTrackedProcessAlive(pid)) {
-        if (sendSignalToTrackedProcess(pid, "SIGKILL")) {
-          signaledKill.add(pid);
-        }
-      }
-    }
-
-    await waitForProcessesToExit([...signaledKill], SIGKILL_TIMEOUT_MS);
-
-    for (const pid of tracked) {
-      this.remove(pid, {
-        signal: signaledKill.has(pid) ? "SIGKILL" : signaledTerm.has(pid) ? "SIGTERM" : null,
-      });
-    }
-
-    return tracked;
-  }
-
-  private toRunningSnapshot(record: ActiveProcessRecord, now = Date.now()): ProcessInfoSnapshot {
-    return {
-      pid: record.pid,
-      command: record.command,
-      args: [...record.args],
-      cwd: record.cwd,
-      interactive: record.interactive,
-      startedAt: record.startedAt,
-      runtimeMs: Math.max(0, now - record.startedAtMs),
-      status: "running",
-      exitCode: null,
-      signal: null,
-      endedAt: null,
-    };
-  }
-
-  private toExitedSnapshot(record: ExitedProcessRecord): ProcessInfoSnapshot {
-    return {
-      pid: record.pid,
-      command: record.command,
-      args: [...record.args],
-      cwd: record.cwd,
-      interactive: record.interactive,
-      startedAt: record.startedAt,
-      runtimeMs: Math.max(0, record.endedAtMs - record.startedAtMs),
-      status: "exited",
-      exitCode: record.exitCode,
-      signal: record.signal,
-      endedAt: record.endedAt,
-    };
-  }
-
-  private pruneExitedHistory(): void {
-    while (this.exited.size > EXIT_HISTORY_LIMIT) {
-      const oldestPid = this.exited.keys().next().value as number | undefined;
-      if (oldestPid === undefined) {
-        break;
-      }
-      this.exited.delete(oldestPid);
-    }
-  }
-
-  private ensureReaper(pid: number): void {
-    if (!this.active.get(pid)?.reapOnExit) {
-      return;
-    }
-    if (this.reapers.has(pid)) {
-      return;
-    }
-
-    const timer = setInterval(() => {
-      this.reapIfExited(pid);
-    }, PROCESS_REAP_POLL_INTERVAL_MS);
-    timer.unref?.();
-    this.reapers.set(pid, timer);
-  }
-
-  private clearReaper(pid: number): void {
-    const timer = this.reapers.get(pid);
-    if (!timer) {
-      return;
-    }
-    clearInterval(timer);
-    this.reapers.delete(pid);
-  }
-
-  private reapIfExited(pid: number): boolean {
-    const record = this.active.get(pid);
-    if (!record) {
-      this.clearReaper(pid);
-      return false;
-    }
-
-    if (!record.reapOnExit) {
-      return false;
-    }
-
-    if (isTrackedProcessAlive(pid)) {
-      return false;
-    }
-
-    this.remove(pid);
-    return true;
-  }
-}
-
-/**
- * Check whether a process is still alive by sending signal 0.
- */
-function isProcessAlive(pid: number): boolean {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function isTrackedProcessAlive(pid: number): boolean {
-  if (pid > 0) {
-    try {
-      process.kill(-pid, 0);
-      return true;
-    } catch {
-      // Fall back to the tracked pid itself when the process group is gone or unsupported.
-    }
-  }
-
-  return isProcessAlive(pid);
-}
-
-function sendSignalToTrackedProcess(pid: number, signal: NodeJS.Signals): boolean {
-  try {
-    if (pid > 0) {
-      process.kill(-pid, signal);
-      return true;
-    }
-  } catch {
-    // Fall back to the tracked pid itself when there is no process group to target.
-  }
-
-  try {
-    process.kill(pid, signal);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function waitForProcessesToExit(pids: number[], timeoutMs: number): Promise<void> {
-  if (pids.length === 0) {
-    return;
-  }
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (pids.every((pid) => !isTrackedProcessAlive(pid))) {
-      return;
-    }
-    await new Promise<void>((resolve) => setTimeout(resolve, POST_KILL_POLL_INTERVAL_MS));
-  }
-}
-
-function normalizeExitCode(value: number | null | undefined): number | null {
-  if (typeof value !== "number" || Number.isNaN(value)) {
-    return null;
-  }
-  return value;
-}
-
-function normalizeSignal(value: string | null | undefined): string | null {
-  if (typeof value !== "string" || value.length === 0) {
-    return null;
-  }
-  return value;
-}

package/src/executors/pty-session-store.ts

@@ -1,43 +0,0 @@
-/**
- * PTYSessionStore — manages PTY sessions for interactive process I/O.
- * Separate from SpawnedProcessRegistry (which is a PID-only cleanup safety net).
- */
-import type { PTYSession } from "./pty.js";
-
-export class PTYSessionStore {
-  private sessions = new Map<number, PTYSession>();
-
-  add(pid: number, session: PTYSession): void {
-    this.sessions.set(pid, session);
-  }
-
-  get(pid: number): PTYSession | undefined {
-    return this.sessions.get(pid);
-  }
-
-  has(pid: number): boolean {
-    return this.sessions.has(pid);
-  }
-
-  remove(pid: number): void {
-    this.sessions.delete(pid);
-  }
-
-  async closeAll(): Promise<void> {
-    const sessions = Array.from(this.sessions.values());
-    this.sessions.clear();
-    await Promise.allSettled(
-      sessions.map((s) => {
-        try {
-          return Promise.resolve(s.close());
-        } catch {
-          return Promise.resolve();
-        }
-      }),
-    );
-  }
-
-  get size(): number {
-    return this.sessions.size;
-  }
-}