@aria-cli/tools 1.0.0

package/tests/executors/path-containment.test.ts

@@ -0,0 +1,51 @@
+/**
+ * @aria/tools - isPathWithinBase unit tests
+ *
+ * Tests the security-critical path containment check directly.
+ */
+
+import { describe, it, expect } from "vitest";
+import { isPathWithinBase } from "../../src/executors/utils.js";
+
+describe("isPathWithinBase", () => {
+  it("should accept exact base match", () => {
+    expect(isPathWithinBase("/home/user/project", "/home/user/project")).toBe(true);
+  });
+
+  it("should accept child paths", () => {
+    expect(isPathWithinBase("/home/user/project/src/index.ts", "/home/user/project")).toBe(true);
+  });
+
+  it("should accept deeply nested child paths", () => {
+    expect(isPathWithinBase("/home/user/project/src/a/b/c/d.ts", "/home/user/project")).toBe(true);
+  });
+
+  it("should reject sibling directories", () => {
+    expect(isPathWithinBase("/home/user/other", "/home/user/project")).toBe(false);
+  });
+
+  it("should reject prefix-collision paths (base-evil)", () => {
+    expect(isPathWithinBase("/home/user/project-evil/file.ts", "/home/user/project")).toBe(false);
+  });
+
+  it("should reject parent directory", () => {
+    expect(isPathWithinBase("/home/user", "/home/user/project")).toBe(false);
+  });
+
+  it("should handle trailing separator on base", () => {
+    expect(isPathWithinBase("/home/user/project/file.ts", "/home/user/project/")).toBe(true);
+  });
+
+  it("should handle trailing separator on both", () => {
+    expect(isPathWithinBase("/home/user/project/", "/home/user/project/")).toBe(true);
+  });
+
+  it("should handle root as base", () => {
+    // Root as base allows everything — this is the correct behavior for "/"
+    expect(isPathWithinBase("/any/path", "/")).toBe(true);
+  });
+
+  it("should reject completely unrelated paths", () => {
+    expect(isPathWithinBase("/tmp/something", "/home/user/project")).toBe(false);
+  });
+});

package/tests/executors/process-registry.test.ts

@@ -0,0 +1,505 @@
+/**
+ * @aria/tools - SpawnedProcessRegistry tests
+ *
+ * Tests for tracking and killing spawned child processes.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { spawn } from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { SpawnedProcessRegistry } from "../../src/executors/process-registry.js";
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+const SIGTERM_IGNORING_NODE_SCRIPT =
+  "const fs = require('node:fs'); process.on('SIGTERM', () => {}); fs.writeFileSync(process.env.READY_FILE, 'ready'); setInterval(() => {}, 1000);";
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Spawn a detached sleep process for testing. Returns its PID.
+ * Caller is responsible for cleanup.
+ */
+function spawnSleepProcess(seconds = 60): number {
+  const proc = spawn("sleep", [String(seconds)], {
+    detached: true,
+    stdio: "ignore",
+  });
+  proc.unref();
+  return proc.pid!;
+}
+
+async function waitForFile(filePath: string, timeoutMs = 5_000): Promise<void> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (fs.existsSync(filePath)) {
+      return;
+    }
+    await sleep(25);
+  }
+  throw new Error(`Timed out waiting for ${filePath}`);
+}
+
+async function spawnSigtermIgnoringNodeProcess(): Promise<{ pid: number; tempDir: string }> {
+  const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "aria-proc-reg-"));
+  const readyFile = path.join(tempDir, "ready");
+  const proc = spawn(process.execPath, ["-e", SIGTERM_IGNORING_NODE_SCRIPT], {
+    detached: true,
+    stdio: "ignore",
+    env: {
+      ...process.env,
+      READY_FILE: readyFile,
+    },
+  });
+  proc.unref();
+  await waitForFile(readyFile);
+  return { pid: proc.pid!, tempDir };
+}
+
+describe("SpawnedProcessRegistry", () => {
+  let registry: SpawnedProcessRegistry;
+  const pidsToCleanup: number[] = [];
+  const tempDirsToCleanup: string[] = [];
+
+  beforeEach(() => {
+    registry = new SpawnedProcessRegistry();
+  });
+
+  afterEach(() => {
+    // Clean up any spawned processes
+    for (const pid of pidsToCleanup) {
+      try {
+        process.kill(pid, "SIGKILL");
+      } catch {
+        // Process may already be dead
+      }
+    }
+    pidsToCleanup.length = 0;
+    for (const tempDir of tempDirsToCleanup) {
+      fs.rmSync(tempDir, { recursive: true, force: true });
+    }
+    tempDirsToCleanup.length = 0;
+  });
+
+  describe("add/remove/has", () => {
+    it("tracks added PIDs", () => {
+      registry.add(1234);
+      expect(registry.has(1234)).toBe(true);
+      expect(registry.size).toBe(1);
+    });
+
+    it("removes PIDs", () => {
+      registry.add(1234);
+      registry.remove(1234);
+      expect(registry.has(1234)).toBe(false);
+      expect(registry.size).toBe(0);
+    });
+
+    it("handles removing non-existent PID gracefully", () => {
+      registry.remove(9999);
+      expect(registry.size).toBe(0);
+    });
+
+    it("tracks multiple PIDs", () => {
+      registry.add(100);
+      registry.add(200);
+      registry.add(300);
+      expect(registry.size).toBe(3);
+      expect(registry.getAll()).toEqual(expect.arrayContaining([100, 200, 300]));
+    });
+
+    it("deduplicates same PID", () => {
+      registry.add(1234);
+      registry.add(1234);
+      expect(registry.size).toBe(1);
+    });
+  });
+
+  describe("getAll", () => {
+    it("returns empty array when no PIDs tracked", () => {
+      expect(registry.getAll()).toEqual([]);
+    });
+
+    it("returns snapshot of tracked PIDs", () => {
+      registry.add(10);
+      registry.add(20);
+      const pids = registry.getAll();
+      expect(pids).toHaveLength(2);
+      expect(pids).toContain(10);
+      expect(pids).toContain(20);
+    });
+  });
+
+  describe("process metadata", () => {
+    it("stores metadata for tracked processes", () => {
+      registry.add(1234, {
+        command: "sleep",
+        args: ["60"],
+        cwd: "/tmp/test",
+        interactive: false,
+      });
+
+      const processes = registry.listProcesses();
+      expect(processes).toHaveLength(1);
+      expect(processes[0]).toMatchObject({
+        pid: 1234,
+        command: "sleep",
+        args: ["60"],
+        cwd: "/tmp/test",
+        interactive: false,
+        status: "running",
+      });
+      expect(typeof processes[0].startedAt).toBe("string");
+      expect(processes[0].runtimeMs).toBeGreaterThanOrEqual(0);
+    });
+  });
+
+  describe("killAll", () => {
+    it("returns empty array when no PIDs tracked", async () => {
+      const killed = await registry.killAll();
+      expect(killed).toEqual([]);
+    });
+
+    it("kills a real spawned process", async () => {
+      const pid = spawnSleepProcess();
+      pidsToCleanup.push(pid);
+
+      expect(isProcessAlive(pid)).toBe(true);
+
+      registry.add(pid);
+      const killed = await registry.killAll();
+
+      expect(killed).toContain(pid);
+
+      // Wait for process to actually die
+      await sleep(200);
+      expect(isProcessAlive(pid)).toBe(false);
+    }, 10000);
+
+    it("kills multiple real processes", async () => {
+      const pid1 = spawnSleepProcess();
+      const pid2 = spawnSleepProcess();
+      pidsToCleanup.push(pid1, pid2);
+
+      registry.add(pid1);
+      registry.add(pid2);
+
+      expect(isProcessAlive(pid1)).toBe(true);
+      expect(isProcessAlive(pid2)).toBe(true);
+
+      await registry.killAll();
+
+      await sleep(200);
+      expect(isProcessAlive(pid1)).toBe(false);
+      expect(isProcessAlive(pid2)).toBe(false);
+    }, 10000);
+
+    it("clears the registry after killAll", async () => {
+      registry.add(999999999); // Non-existent PID
+      await registry.killAll();
+      expect(registry.size).toBe(0);
+    });
+
+    it("handles already-dead processes gracefully", async () => {
+      const pid = spawnSleepProcess();
+      pidsToCleanup.push(pid);
+
+      registry.add(pid);
+
+      // Kill the process before calling killAll
+      process.kill(pid, "SIGKILL");
+      await sleep(100);
+
+      // Should not throw
+      const killed = await registry.killAll();
+      expect(killed).toContain(pid);
+      expect(registry.size).toBe(0);
+    }, 10000);
+
+    it("waits for a SIGTERM-resistant process to exit after SIGKILL escalation", async () => {
+      const resistantProcess = await spawnSigtermIgnoringNodeProcess();
+      const { pid, tempDir } = resistantProcess;
+      pidsToCleanup.push(pid);
+      tempDirsToCleanup.push(tempDir);
+      registry.add(pid, {
+        command: process.execPath,
+        args: ["-e", SIGTERM_IGNORING_NODE_SCRIPT],
+      });
+
+      const startedAt = Date.now();
+      const killed = await registry.killAll();
+      const elapsedMs = Date.now() - startedAt;
+
+      expect(killed).toContain(pid);
+      expect(elapsedMs).toBeGreaterThanOrEqual(1900);
+      expect(isProcessAlive(pid)).toBe(false);
+      expect(registry.getProcess(pid)).toMatchObject({
+        pid,
+        status: "exited",
+        signal: "SIGKILL",
+      });
+    }, 15000);
+
+    it("preserves the leader signal when escalation only kills a trailing child", async () => {
+      const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "aria-proc-leader-signal-"));
+      const childPidFile = path.join(tempDir, "child.pid");
+      tempDirsToCleanup.push(tempDir);
+
+      const proc = spawn(
+        process.execPath,
+        [
+          "-e",
+          [
+            "const { spawn } = require('node:child_process');",
+            "const fs = require('node:fs');",
+            "const child = spawn(process.execPath, ['-e', \"process.on('SIGTERM', () => {}); setInterval(() => {}, 1000);\"] , { stdio: 'ignore' });",
+            "fs.writeFileSync(process.env.CHILD_PID_FILE, String(child.pid));",
+            "setInterval(() => {}, 1000);",
+          ].join(" "),
+        ],
+        {
+          detached: true,
+          stdio: "ignore",
+          env: {
+            ...process.env,
+            CHILD_PID_FILE: childPidFile,
+          },
+        },
+      );
+      proc.unref();
+      const pid = proc.pid!;
+      pidsToCleanup.push(pid);
+      await waitForFile(childPidFile);
+
+      registry.add(pid, {
+        command: process.execPath,
+        args: ["-e", "leader-dies-child-resists"],
+      });
+
+      await registry.killAll();
+
+      expect(registry.getProcess(pid)).toMatchObject({
+        pid,
+        status: "exited",
+        signal: "SIGTERM",
+      });
+    }, 15_000);
+
+    it("signals detached process groups so child processes do not survive teardown", async () => {
+      const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), "aria-proc-group-"));
+      const childPidFile = path.join(tempDir, "child.pid");
+      tempDirsToCleanup.push(tempDir);
+
+      const proc = spawn(
+        "sh",
+        ["-c", 'sleep 60 & child=$!; echo "$child" > "$CHILD_PID_FILE"; wait "$child"'],
+        {
+          detached: true,
+          stdio: "ignore",
+          env: {
+            ...process.env,
+            CHILD_PID_FILE: childPidFile,
+          },
+        },
+      );
+      proc.unref();
+      const pid = proc.pid!;
+      pidsToCleanup.push(pid);
+      await waitForFile(childPidFile);
+      const childPid = Number.parseInt(fs.readFileSync(childPidFile, "utf8").trim(), 10);
+
+      registry.add(pid, {
+        command: "sh",
+        args: ["-c", 'sleep 60 & child=$!; echo "$child" > "$CHILD_PID_FILE"; wait "$child"'],
+      });
+
+      expect(isProcessAlive(pid)).toBe(true);
+      expect(isProcessAlive(childPid)).toBe(true);
+
+      await registry.killAll();
+      await sleep(200);
+
+      expect(isProcessAlive(pid)).toBe(false);
+      expect(isProcessAlive(childPid)).toBe(false);
+    }, 15000);
+
+    it("auto-reaps tracked detached groups after the leader exits and the trailing child drains naturally", async () => {
+      const proc = spawn(
+        process.execPath,
+        [
+          "-e",
+          [
+            "const { spawn } = require('node:child_process');",
+            "const child = spawn('sleep', ['1'], { stdio: 'ignore' });",
+            "child.unref();",
+            "setTimeout(() => process.exit(0), 20);",
+          ].join(" "),
+        ],
+        {
+          detached: true,
+          stdio: "ignore",
+        },
+      );
+      proc.unref();
+      const pid = proc.pid!;
+      pidsToCleanup.push(pid);
+
+      registry.add(pid, {
+        command: process.execPath,
+        args: ["-e", "leader-exits-before-child-drains"],
+      });
+
+      expect(registry.has(pid)).toBe(true);
+
+      await sleep(1_500);
+
+      expect(registry.has(pid)).toBe(false);
+      expect(registry.getProcess(pid)).toMatchObject({
+        pid,
+        status: "exited",
+      });
+    }, 15_000);
+  });
+
+  describe("normal exit removes PID", () => {
+    it("process that exits normally can be deregistered before killAll", async () => {
+      // Spawn a process that exits quickly
+      const proc = spawn("true", [], {
+        detached: true,
+        stdio: "ignore",
+      });
+      proc.unref();
+      const pid = proc.pid!;
+      pidsToCleanup.push(pid);
+
+      registry.add(pid);
+
+      // Wait for process to exit
+      await sleep(200);
+
+      // Simulate what the shell executor does: remove on exit
+      registry.remove(pid);
+
+      expect(registry.has(pid)).toBe(false);
+      expect(registry.size).toBe(0);
+    });
+  });
+
+  describe("waitForExit", () => {
+    it("returns not_found for unknown PID", async () => {
+      const result = await registry.waitForExit(424242, 100);
+
+      expect(result.status).toBe("not_found");
+      expect(result.pid).toBe(424242);
+      expect(result.timedOut).toBe(false);
+    });
+
+    it("returns immediate running timeout when timeout is zero", async () => {
+      registry.add(4343, { command: "sleep", args: ["60"] });
+
+      const result = await registry.waitForExit(4343, 0);
+      expect(result.status).toBe("running");
+      expect(result.pid).toBe(4343);
+      expect(result.timedOut).toBe(true);
+      expect(result.process).toMatchObject({
+        pid: 4343,
+        status: "running",
+      });
+
+      registry.remove(4343, { signal: "SIGKILL" });
+    });
+
+    it("resolves when tracked process exits", async () => {
+      registry.add(7777, { command: "sleep", args: ["1"] });
+      const waitPromise = registry.waitForExit(7777, 1000);
+
+      setTimeout(() => {
+        registry.remove(7777, { exitCode: 0 });
+      }, 50);
+
+      const result = await waitPromise;
+      expect(result.status).toBe("exited");
+      expect(result.pid).toBe(7777);
+      expect(result.timedOut).toBe(false);
+      expect(result.process).toMatchObject({
+        pid: 7777,
+        status: "exited",
+        exitCode: 0,
+      });
+    });
+
+    it("resolves quickly when process exits during waiter registration race window", async () => {
+      const pid = 7878;
+      registry.add(pid, { command: "sleep", args: ["1"] });
+
+      const internals = registry as unknown as { active: { get(targetPid: number): unknown } };
+      const activeMap = internals.active;
+      const originalGet = activeMap.get.bind(activeMap);
+      let injected = false;
+
+      activeMap.get = ((targetPid: number) => {
+        const record = originalGet(targetPid);
+        if (!injected && targetPid === pid) {
+          injected = true;
+          registry.remove(pid, { exitCode: 0 });
+        }
+        return record;
+      }) as typeof activeMap.get;
+
+      try {
+        const startedAt = Date.now();
+        const result = await registry.waitForExit(pid, 250);
+        const elapsedMs = Date.now() - startedAt;
+
+        expect(result.status).toBe("exited");
+        expect(result.timedOut).toBe(false);
+        expect(result.process).toMatchObject({
+          pid,
+          status: "exited",
+          exitCode: 0,
+        });
+        expect(elapsedMs).toBeLessThan(120);
+      } finally {
+        activeMap.get = originalGet;
+      }
+    });
+
+    it("returns timeout when process stays running", async () => {
+      registry.add(8888, { command: "sleep", args: ["60"] });
+
+      const result = await registry.waitForExit(8888, 50);
+      expect(result.status).toBe("running");
+      expect(result.pid).toBe(8888);
+      expect(result.timedOut).toBe(true);
+      expect(result.process).toMatchObject({
+        pid: 8888,
+        status: "running",
+      });
+
+      registry.remove(8888, { signal: "SIGKILL" });
+    });
+
+    it("returns cached exit info when process already exited", async () => {
+      registry.add(9999, { command: "true" });
+      registry.remove(9999, { exitCode: 0 });
+
+      const result = await registry.waitForExit(9999, 100);
+      expect(result.status).toBe("exited");
+      expect(result.pid).toBe(9999);
+      expect(result.timedOut).toBe(false);
+      expect(result.process).toMatchObject({
+        pid: 9999,
+        status: "exited",
+        exitCode: 0,
+      });
+    });
+  });
+});