@aria-cli/tools 1.0.10 → 1.0.12

package/dist-cjs/executors/process-registry.js

@@ -0,0 +1,469 @@
+"use strict";
+/**
+ * @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.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SpawnedProcessRegistry = void 0;
+/**
+ * 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;
+/**
+ * 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
+ */
+class SpawnedProcessRegistry {
+    active = new Map();
+    exited = new Map();
+    waiters = new Map();
+    reapers = new Map();
+    /**
+     * Register a spawned process PID.
+     */
+    add(pid, metadata = {}) {
+        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, exit = {}) {
+        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 = {
+            ...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) {
+        return this.active.has(pid);
+    }
+    recordExitMetadata(pid, exit = {}) {
+        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() {
+        return this.active.size;
+    }
+    /**
+     * Return a snapshot of all tracked PIDs.
+     */
+    getAll() {
+        return [...this.active.keys()];
+    }
+    /**
+     * Return process snapshots for observability.
+     */
+    listProcesses(options = {}) {
+        const now = Date.now();
+        const snapshots = [];
+        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) {
+        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, timeoutMs = 30_000) {
+        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) => {
+                if (settled)
+                    return;
+                settled = true;
+                resolve(result);
+            };
+            const removeWaiter = (target) => {
+                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) => {
+                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() {
+        const tracked = [...this.active.keys()];
+        if (tracked.length === 0)
+            return [];
+        // Phase 1: SIGTERM all tracked processes
+        const alive = [];
+        const signaledTerm = new Set();
+        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((resolve) => setTimeout(resolve, SIGKILL_TIMEOUT_MS));
+        const signaledKill = new Set();
+        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;
+    }
+    toRunningSnapshot(record, now = Date.now()) {
+        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,
+        };
+    }
+    toExitedSnapshot(record) {
+        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,
+        };
+    }
+    pruneExitedHistory() {
+        while (this.exited.size > EXIT_HISTORY_LIMIT) {
+            const oldestPid = this.exited.keys().next().value;
+            if (oldestPid === undefined) {
+                break;
+            }
+            this.exited.delete(oldestPid);
+        }
+    }
+    ensureReaper(pid) {
+        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);
+    }
+    clearReaper(pid) {
+        const timer = this.reapers.get(pid);
+        if (!timer) {
+            return;
+        }
+        clearInterval(timer);
+        this.reapers.delete(pid);
+    }
+    reapIfExited(pid) {
+        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;
+    }
+}
+exports.SpawnedProcessRegistry = SpawnedProcessRegistry;
+/**
+ * Check whether a process is still alive by sending signal 0.
+ */
+function isProcessAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function isTrackedProcessAlive(pid) {
+    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, signal) {
+    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, timeoutMs) {
+    if (pids.length === 0) {
+        return;
+    }
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        if (pids.every((pid) => !isTrackedProcessAlive(pid))) {
+            return;
+        }
+        await new Promise((resolve) => setTimeout(resolve, POST_KILL_POLL_INTERVAL_MS));
+    }
+}
+function normalizeExitCode(value) {
+    if (typeof value !== "number" || Number.isNaN(value)) {
+        return null;
+    }
+    return value;
+}
+function normalizeSignal(value) {
+    if (typeof value !== "string" || value.length === 0) {
+        return null;
+    }
+    return value;
+}

package/dist-cjs/executors/pty-session-store.d.ts

@@ -0,0 +1,14 @@
+/**
+ * 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 declare class PTYSessionStore {
+    private sessions;
+    add(pid: number, session: PTYSession): void;
+    get(pid: number): PTYSession | undefined;
+    has(pid: number): boolean;
+    remove(pid: number): void;
+    closeAll(): Promise<void>;
+    get size(): number;
+}

package/dist-cjs/executors/pty-session-store.js

@@ -0,0 +1,34 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PTYSessionStore = void 0;
+class PTYSessionStore {
+    sessions = new Map();
+    add(pid, session) {
+        this.sessions.set(pid, session);
+    }
+    get(pid) {
+        return this.sessions.get(pid);
+    }
+    has(pid) {
+        return this.sessions.has(pid);
+    }
+    remove(pid) {
+        this.sessions.delete(pid);
+    }
+    async closeAll() {
+        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() {
+        return this.sessions.size;
+    }
+}
+exports.PTYSessionStore = PTYSessionStore;

package/dist-cjs/executors/pty.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @aria/tools - PTY executor for interactive terminal programs
+ *
+ * Provides PTY (pseudo-terminal) support for running interactive programs
+ * that require a terminal environment (like vim, less, etc.)
+ */
+import * as nodePty from "node-pty";
+/**
+ * Options for creating a PTY session.
+ */
+export interface PTYOptions {
+    /** Command to execute */
+    command: string;
+    /** Arguments to pass to the command */
+    args?: string[];
+    /** Working directory */
+    cwd?: string;
+    /** Environment variables */
+    env?: Record<string, string>;
+    /** Terminal columns (default: 80) */
+    cols?: number;
+    /** Terminal rows (default: 24) */
+    rows?: number;
+}
+/**
+ * Result of running a command in a PTY.
+ */
+export interface PTYResult {
+    /** All output from the command */
+    output: string;
+    /** Exit code of the process */
+    exitCode: number;
+}
+/**
+ * Error thrown when a PTY operation times out.
+ */
+export declare class PTYTimeoutError extends Error {
+    readonly output: string;
+    constructor(message: string, output: string);
+}
+/**
+ * Error thrown when a PTY operation fails.
+ */
+export declare class PTYError extends Error {
+    readonly output?: string | undefined;
+    constructor(message: string, output?: string | undefined);
+}
+/**
+ * A session wrapping a PTY process.
+ * Provides methods for interacting with the process and collecting output.
+ */
+export declare class PTYSession {
+    private static MAX_OUTPUT;
+    private _output;
+    private _isRunning;
+    private _exitCode;
+    private _exitPromise;
+    private _exitResolve;
+    private _pty;
+    private _dataDisposable;
+    private _exitDisposable;
+    constructor(pty: nodePty.IPty);
+    /**
+     * Write data to the terminal input.
+     */
+    write(data: string): void;
+    /**
+     * Resize the terminal.
+     */
+    resize(cols: number, rows: number): void;
+    /**
+     * Wait for a pattern to appear in the output.
+     * @param pattern String or RegExp to match
+     * @param timeoutMs Timeout in milliseconds (default: 5000)
+     * @returns The output accumulated up to and including the match
+     */
+    waitFor(pattern: string | RegExp, timeoutMs?: number): Promise<string>;
+    /**
+     * Wait for the process to exit.
+     * @param timeoutMs Timeout in milliseconds (default: 30000)
+     * @returns The complete output
+     */
+    waitForExit(timeoutMs?: number): Promise<string>;
+    /**
+     * Kill the process.
+     * @param signal Signal to send (default: SIGHUP on Unix)
+     */
+    kill(signal?: string): void;
+    /**
+     * Close the session and clean up resources.
+     */
+    close(): void;
+    /**
+     * Get the current output buffer.
+     */
+    get output(): string;
+    /**
+     * Check if the process is still running.
+     */
+    get isRunning(): boolean;
+    /**
+     * Get the process ID.
+     */
+    get pid(): number;
+    /**
+     * Get the exit code (undefined if still running).
+     */
+    get exitCode(): number | undefined;
+    /**
+     * Get the current terminal columns.
+     */
+    get cols(): number;
+    /**
+     * Get the current terminal rows.
+     */
+    get rows(): number;
+}
+/**
+ * Create a new PTY session.
+ * @param options Options for the PTY
+ * @returns A PTYSession wrapping the process
+ */
+export declare function createPTYSession(options: PTYOptions): Promise<PTYSession>;
+/**
+ * Run a command in a PTY and wait for it to complete.
+ * This is a convenience function for commands that don't require interaction.
+ *
+ * @param options Options for the PTY, with optional timeout
+ * @returns The output and exit code
+ */
+export declare function runInPTY(options: PTYOptions & {
+    timeoutMs?: number;
+}): Promise<PTYResult>;