@aria-cli/tools 1.0.0

package/tests/executors/shell-abort.test.ts

@@ -0,0 +1,416 @@
+/**
+ * @aria/tools - Shell executor abort signal tests
+ *
+ * Verifies that executeBash, executeExec, and executeSpawn respect
+ * AbortSignal for cancellation.
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import * as os from "node:os";
+import type { ToolContext } from "../../src/types.js";
+import { executeBash, executeExec, executeSpawn } from "../../src/executors/shell.js";
+
+const createTempDir = async (): Promise<string> => {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "aria-shell-abort-"));
+  return fs.realpath(tempDir);
+};
+
+const cleanupTempDir = async (dir: string): Promise<void> => {
+  await fs.rm(dir, { recursive: true, force: true });
+};
+
+const createContext = (workingDir: string, overrides?: Partial<ToolContext>): ToolContext => ({
+  workingDir,
+  env: {},
+  confirm: async () => true,
+  ...overrides,
+});
+
+const sleep = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+
+const waitForFile = async (filePath: string, timeoutMs = 5000): Promise<void> => {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    try {
+      await fs.access(filePath);
+      return;
+    } catch {
+      await sleep(25);
+    }
+  }
+  throw new Error(`Timed out waiting for file: ${filePath}`);
+};
+
+describe("Shell Executors - AbortSignal", () => {
+  let tempDir: string;
+  let ctx: ToolContext;
+
+  beforeEach(async () => {
+    tempDir = await createTempDir();
+    ctx = createContext(tempDir);
+  });
+
+  afterEach(async () => {
+    await cleanupTempDir(tempDir);
+  });
+
+  // =========================================================================
+  // executeBash
+  // =========================================================================
+
+  describe("executeBash", () => {
+    it("should not execute when signal is already aborted", async () => {
+      const ac = new AbortController();
+      ac.abort();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      const result = await executeBash({ command: 'echo "should not run"' }, abortCtx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBe("Command cancelled");
+      // No data should be present since command never ran
+      expect(result.data).toBeUndefined();
+    });
+
+    it("should abort a running bash command when signal fires", async () => {
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      // Start a command that will block indefinitely
+      const resultPromise = executeBash({ command: "sleep 300" }, abortCtx);
+
+      // Let the process start, then abort
+      await sleep(100);
+      ac.abort();
+
+      const result = await resultPromise;
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBe("Command cancelled");
+    });
+
+    it("should distinguish abort from timeout", async () => {
+      // First: timeout case (no abort signal)
+      const timeoutResult = await executeBash({ command: "sleep 10", timeout: 100 }, ctx);
+      expect(timeoutResult.success).toBe(false);
+      expect(timeoutResult.message?.toLowerCase()).toContain("time");
+
+      // Second: abort case (with abort signal, long timeout)
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+      const abortPromise = executeBash({ command: "sleep 300", timeout: 60_000 }, abortCtx);
+      await sleep(100);
+      ac.abort();
+
+      const abortResult = await abortPromise;
+      expect(abortResult.success).toBe(false);
+      expect(abortResult.message).toBe("Command cancelled");
+    });
+  });
+
+  // =========================================================================
+  // executeExec
+  // =========================================================================
+
+  describe("executeExec", () => {
+    it("should not execute when signal is already aborted", async () => {
+      const ac = new AbortController();
+      ac.abort();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      const result = await executeExec({ program: "echo", args: ["should not run"] }, abortCtx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBe("Command cancelled");
+    });
+
+    it("should kill running process when signal fires", async () => {
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      const resultPromise = executeExec({ program: "sleep", args: ["300"] }, abortCtx);
+
+      // Let the process start, then abort
+      await sleep(100);
+      ac.abort();
+
+      const result = await resultPromise;
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBe("Command cancelled");
+    });
+
+    it("should preserve partial stdout captured before abort", async () => {
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      // Write a script that outputs then blocks. Using a file-based approach
+      // avoids pipe buffering issues under load.
+      const scriptPath = path.join(tempDir, "partial.sh");
+      await fs.writeFile(scriptPath, '#!/bin/bash\necho "partial output"\nexec sleep 300\n', {
+        mode: 0o755,
+      });
+
+      const resultPromise = executeExec({ program: "/bin/bash", args: [scriptPath] }, abortCtx);
+
+      // Wait long enough for echo to flush, then abort
+      await sleep(500);
+      ac.abort();
+
+      const result = await resultPromise;
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBe("Command cancelled");
+      const data = result.data as { stdout: string };
+      expect(data.stdout).toContain("partial output");
+    }, 15000);
+
+    it("should abort the whole exec process tree without dropping prior stdout", async () => {
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      const readyFile = path.join(tempDir, "tree-ready");
+      const childPidFile = path.join(tempDir, "tree-child.pid");
+      const scriptPath = path.join(tempDir, "tree.sh");
+      await fs.writeFile(
+        scriptPath,
+        `#!/bin/bash
+sleep 300 &
+child_pid=$!
+echo "$child_pid" > "${childPidFile}"
+echo "partial output"
+touch "${readyFile}"
+wait "$child_pid"
+`,
+        { mode: 0o755 },
+      );
+
+      const resultPromise = executeExec({ program: "/bin/bash", args: [scriptPath] }, abortCtx);
+
+      await waitForFile(readyFile);
+      const childPid = Number.parseInt((await fs.readFile(childPidFile, "utf8")).trim(), 10);
+      expect(Number.isFinite(childPid)).toBe(true);
+
+      try {
+        ac.abort();
+
+        const result = await resultPromise;
+
+        expect(result.success).toBe(false);
+        expect(result.message).toBe("Command cancelled");
+        const data = result.data as { stdout: string };
+        expect(data.stdout).toContain("partial output");
+        expect(() => process.kill(childPid, 0)).toThrow();
+      } finally {
+        try {
+          process.kill(childPid, "SIGKILL");
+        } catch {
+          // child already terminated
+        }
+      }
+    }, 15000);
+
+    it("should timeout the whole exec process tree without dropping prior stdout", async () => {
+      const readyFile = path.join(tempDir, "timeout-tree-ready");
+      const childPidFile = path.join(tempDir, "timeout-tree-child.pid");
+      const childScriptPath = path.join(tempDir, "timeout-tree-child.sh");
+      const scriptPath = path.join(tempDir, "timeout-tree.sh");
+      await fs.writeFile(
+        childScriptPath,
+        `#!/bin/bash
+trap '' TERM
+while true; do
+  sleep 1
+done
+`,
+        { mode: 0o755 },
+      );
+      await fs.writeFile(
+        scriptPath,
+        `#!/bin/bash
+"${childScriptPath}" &
+child_pid=$!
+echo "$child_pid" > "${childPidFile}"
+echo "partial output"
+touch "${readyFile}"
+wait "$child_pid"
+`,
+        { mode: 0o755 },
+      );
+
+      // executeExec timeout starts at spawn(), not after script readiness.
+      // Give the script enough startup slack to publish the child PID and
+      // initial stdout before we assert timeout-driven tree teardown.
+      const resultPromise = executeExec(
+        {
+          program: "/bin/bash",
+          args: [scriptPath],
+          timeout: 2_000,
+        },
+        ctx,
+      );
+
+      await waitForFile(readyFile);
+      const childPid = Number.parseInt((await fs.readFile(childPidFile, "utf8")).trim(), 10);
+      expect(Number.isFinite(childPid)).toBe(true);
+
+      try {
+        const result = await resultPromise;
+
+        expect(result.success).toBe(false);
+        expect(result.message).toBe("Command timed out");
+        const data = result.data as { stdout: string };
+        expect(data.stdout).toContain("partial output");
+        expect(() => process.kill(childPid, 0)).toThrow();
+      } finally {
+        try {
+          process.kill(childPid, "SIGKILL");
+        } catch {
+          // child already terminated
+        }
+      }
+    }, 15000);
+
+    it("should include exit code in abort result data", async () => {
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      const resultPromise = executeExec({ program: "sleep", args: ["300"] }, abortCtx);
+
+      await sleep(100);
+      ac.abort();
+
+      const result = await resultPromise;
+
+      expect(result.success).toBe(false);
+      const data = result.data as { exitCode: number; stdout: string; stderr: string };
+      expect(data).toBeDefined();
+      expect(typeof data.exitCode).toBe("number");
+      expect(typeof data.stdout).toBe("string");
+      expect(typeof data.stderr).toBe("string");
+    });
+  });
+
+  // =========================================================================
+  // executeSpawn
+  // =========================================================================
+
+  describe("executeSpawn", () => {
+    it("should not spawn when signal is already aborted", async () => {
+      const ac = new AbortController();
+      ac.abort();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      const result = await executeSpawn({ program: "sleep", args: ["300"] }, abortCtx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBe("Command cancelled");
+    });
+
+    it("should kill spawned process when signal fires after spawn", async () => {
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      const result = await executeSpawn({ program: "sleep", args: ["300"] }, abortCtx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { pid: number };
+      const pid = data.pid;
+
+      try {
+        // Process should be running right after spawn
+        expect(() => process.kill(pid, 0)).not.toThrow();
+
+        // Fire the abort signal
+        ac.abort();
+
+        // Poll until the process is dead (SIGTERM + SIGKILL fallback)
+        let isDead = false;
+        for (let i = 0; i < 20; i++) {
+          await sleep(100);
+          try {
+            process.kill(pid, 0);
+          } catch {
+            isDead = true;
+            break;
+          }
+        }
+
+        expect(isDead).toBe(true);
+      } finally {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+          // Process may already be dead
+        }
+      }
+    }, 15000);
+
+    it("should succeed initially then abort handler kills the background process", async () => {
+      // executeSpawn returns success (with PID) immediately, then the abort
+      // handler kills it afterwards. This verifies the two-phase behavior.
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      const result = await executeSpawn({ program: "sleep", args: ["300"] }, abortCtx);
+
+      // Spawn should succeed
+      expect(result.success).toBe(true);
+      expect(result.message).toContain("PID");
+
+      const pid = (result.data as { pid: number }).pid;
+      try {
+        // After abort, process should eventually die
+        ac.abort();
+        await sleep(500);
+
+        let alive = true;
+        try {
+          process.kill(pid, 0);
+        } catch {
+          alive = false;
+        }
+        expect(alive).toBe(false);
+      } finally {
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+          // already dead
+        }
+      }
+    });
+  });
+
+  // =========================================================================
+  // Edge cases
+  // =========================================================================
+
+  describe("edge cases", () => {
+    it("should handle abort signal that is undefined (no signal)", async () => {
+      // Ensure executors work fine without any abort signal
+      const noSignalCtx = createContext(tempDir);
+      // abortSignal should be undefined by default
+      expect(noSignalCtx.abortSignal).toBeUndefined();
+
+      const result = await executeBash({ command: 'echo "works"' }, noSignalCtx);
+      expect(result.success).toBe(true);
+    });
+
+    it("should handle abort after command completes naturally (no-op)", async () => {
+      const ac = new AbortController();
+      const abortCtx = createContext(tempDir, { abortSignal: ac.signal });
+
+      // Run a quick command that finishes before abort
+      const result = await executeBash({ command: 'echo "done"' }, abortCtx);
+      expect(result.success).toBe(true);
+
+      // Abort after completion should be a no-op (no crash)
+      ac.abort();
+
+      // Verify context is still usable info-wise
+      expect(abortCtx.abortSignal?.aborted).toBe(true);
+    });
+  });
+});