@aria-cli/tools 1.0.0

package/tests/executors/shell.test.ts

@@ -0,0 +1,690 @@
+/**
+ * @aria/tools - Shell executor tests
+ */
+
+import { describe, it, expect, beforeEach, afterEach } from "vitest";
+import { spawn as spawnChild } from "node:child_process";
+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 { SpawnedProcessRegistry } from "../../src/executors/process-registry.js";
+import {
+  executeBash,
+  executeExec,
+  executeSpawn,
+  executeKill,
+  executeWaitProcess,
+} from "../../src/executors/shell.js";
+import { waitForChildExit, waitForFile } from "../helpers/async-waits.js";
+
+// Helper to create a unique temp directory for each test
+// Uses realpath to resolve symlinks (e.g., /var -> /private/var on macOS)
+const createTempDir = async (): Promise<string> => {
+  const tempDir = await fs.mkdtemp(path.join(os.tmpdir(), "aria-shell-test-"));
+  return fs.realpath(tempDir);
+};
+
+// Helper to clean up temp directory
+const cleanupTempDir = async (dir: string): Promise<void> => {
+  await fs.rm(dir, { recursive: true, force: true });
+};
+
+// Helper to create a context
+const createContext = (
+  workingDir: string,
+  env: Record<string, string> = {},
+  processRegistry?: SpawnedProcessRegistry,
+): ToolContext => ({
+  workingDir,
+  env,
+  processRegistry,
+  confirm: async () => true,
+});
+
+const shellQuote = (value: string): string => `'${value.replace(/'/g, `'\"'\"'`)}'`;
+
+describe("Shell Executors", () => {
+  let tempDir: string;
+  let ctx: ToolContext;
+  let processRegistry: SpawnedProcessRegistry;
+
+  beforeEach(async () => {
+    tempDir = await createTempDir();
+    processRegistry = new SpawnedProcessRegistry();
+    ctx = createContext(tempDir, {}, processRegistry);
+  });
+
+  afterEach(async () => {
+    await cleanupTempDir(tempDir);
+  });
+
+  describe("executeBash", () => {
+    it("should execute a simple command", async () => {
+      const result = await executeBash({ command: 'echo "hello world"' }, ctx);
+
+      expect(result.success).toBe(true);
+      expect(result.data).toMatchObject({
+        stdout: expect.stringContaining("hello world"),
+      });
+    });
+
+    it("should capture stdout correctly", async () => {
+      const result = await executeBash({ command: 'echo "line1"; echo "line2"' }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout).toContain("line1");
+      expect(data.stdout).toContain("line2");
+    });
+
+    it("should capture stderr correctly", async () => {
+      const result = await executeBash({ command: 'echo "error message" >&2' }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stderr: string };
+      expect(data.stderr).toContain("error message");
+    });
+
+    it("should return exit code", async () => {
+      const result = await executeBash({ command: "exit 0" }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { exitCode: number };
+      expect(data.exitCode).toBe(0);
+    });
+
+    it("should handle non-zero exit code", async () => {
+      const result = await executeBash({ command: "exit 42" }, ctx);
+
+      expect(result.success).toBe(false);
+      const data = result.data as { exitCode: number };
+      expect(data.exitCode).toBe(42);
+    });
+
+    it("should handle command failure", async () => {
+      const result = await executeBash({ command: "nonexistent_command_12345" }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.data).toBeDefined();
+    });
+
+    it("should use working directory", async () => {
+      const result = await executeBash({ command: "pwd" }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe(tempDir);
+    });
+
+    it("should support custom cwd option", async () => {
+      const subDir = path.join(tempDir, "subdir");
+      await fs.mkdir(subDir);
+
+      const result = await executeBash({ command: "pwd", cwd: subDir }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe(subDir);
+    });
+
+    it("should use environment variables from context", async () => {
+      const envCtx = createContext(tempDir, { MY_VAR: "test_value" });
+
+      const result = await executeBash({ command: "echo $MY_VAR" }, envCtx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe("test_value");
+    });
+
+    it("should support custom environment variables in input", async () => {
+      const result = await executeBash(
+        { command: "echo $CUSTOM_VAR", env: { CUSTOM_VAR: "custom_value" } },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe("custom_value");
+    });
+
+    it("should timeout long-running commands", async () => {
+      const result = await executeBash({ command: "sleep 10", timeout: 100 }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message?.toLowerCase()).toContain("time");
+    });
+
+    it("should create files in working directory", async () => {
+      await executeBash({ command: "touch testfile.txt" }, ctx);
+
+      const exists = await fs
+        .access(path.join(tempDir, "testfile.txt"))
+        .then(() => true)
+        .catch(() => false);
+      expect(exists).toBe(true);
+    });
+
+    it("should support shell features like pipes", async () => {
+      const result = await executeBash({ command: 'echo "hello world" | grep world' }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout).toContain("world");
+    });
+
+    it("should support shell features like redirection", async () => {
+      await executeBash({ command: 'echo "content" > output.txt' }, ctx);
+
+      const content = await fs.readFile(path.join(tempDir, "output.txt"), "utf-8");
+      expect(content.trim()).toBe("content");
+    });
+
+    it("should ignore inherited GIT_* context vars from process.env", async () => {
+      const originalGitEnv = {
+        GIT_DIR: process.env.GIT_DIR,
+        GIT_WORK_TREE: process.env.GIT_WORK_TREE,
+        GIT_INDEX_FILE: process.env.GIT_INDEX_FILE,
+      };
+
+      process.env.GIT_DIR = "/tmp/not-a-repo";
+      process.env.GIT_WORK_TREE = "/tmp/not-a-repo";
+      process.env.GIT_INDEX_FILE = "/tmp/not-a-repo/index";
+
+      try {
+        const init = await executeBash({ command: "git init" }, ctx);
+        expect(init.success).toBe(true);
+
+        const write = await executeBash({ command: 'echo "# Test" > README.md' }, ctx);
+        expect(write.success).toBe(true);
+
+        const status = await executeBash({ command: "git status --porcelain" }, ctx);
+        expect(status.success).toBe(true);
+        const data = status.data as { stdout: string };
+        expect(data.stdout).toContain("README.md");
+      } finally {
+        if (originalGitEnv.GIT_DIR === undefined) {
+          delete process.env.GIT_DIR;
+        } else {
+          process.env.GIT_DIR = originalGitEnv.GIT_DIR;
+        }
+        if (originalGitEnv.GIT_WORK_TREE === undefined) {
+          delete process.env.GIT_WORK_TREE;
+        } else {
+          process.env.GIT_WORK_TREE = originalGitEnv.GIT_WORK_TREE;
+        }
+        if (originalGitEnv.GIT_INDEX_FILE === undefined) {
+          delete process.env.GIT_INDEX_FILE;
+        } else {
+          process.env.GIT_INDEX_FILE = originalGitEnv.GIT_INDEX_FILE;
+        }
+      }
+    });
+  });
+
+  describe("executeExec", () => {
+    it("should execute a program directly", async () => {
+      const result = await executeExec({ program: "echo", args: ["hello", "world"] }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe("hello world");
+    });
+
+    it("should handle program without arguments", async () => {
+      const result = await executeExec({ program: "pwd" }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe(tempDir);
+    });
+
+    it("should return exit code", async () => {
+      const result = await executeExec({ program: "true" }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { exitCode: number };
+      expect(data.exitCode).toBe(0);
+    });
+
+    it("should handle non-zero exit code", async () => {
+      const result = await executeExec({ program: "false" }, ctx);
+
+      expect(result.success).toBe(false);
+      const data = result.data as { exitCode: number };
+      expect(data.exitCode).toBe(1);
+    });
+
+    it("should handle non-existent program", async () => {
+      const result = await executeExec({ program: "nonexistent_program_12345" }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBeDefined();
+    });
+
+    it("should use working directory", async () => {
+      const result = await executeExec({ program: "pwd" }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe(tempDir);
+    });
+
+    it("should support custom cwd option", async () => {
+      const subDir = path.join(tempDir, "subdir");
+      await fs.mkdir(subDir);
+
+      const result = await executeExec({ program: "pwd", cwd: subDir }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe(subDir);
+    });
+
+    it("should use environment variables from context", async () => {
+      const envCtx = createContext(tempDir, { MY_VAR: "exec_value" });
+
+      const result = await executeExec(
+        { program: "/bin/sh", args: ["-c", "echo $MY_VAR"] },
+        envCtx,
+      );
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe("exec_value");
+    });
+
+    it("should support custom environment variables in input", async () => {
+      const result = await executeExec(
+        {
+          program: "/bin/sh",
+          args: ["-c", "echo $CUSTOM_VAR"],
+          env: { CUSTOM_VAR: "custom_exec_value" },
+        },
+        ctx,
+      );
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe("custom_exec_value");
+    });
+
+    it("should timeout long-running programs", async () => {
+      const result = await executeExec({ program: "sleep", args: ["10"], timeout: 100 }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message?.toLowerCase()).toContain("time");
+    });
+
+    it("should not interpret shell metacharacters", async () => {
+      // This should print the literal string, not execute the command
+      const result = await executeExec({ program: "echo", args: ["$(whoami)"] }, ctx);
+
+      expect(result.success).toBe(true);
+      const data = result.data as { stdout: string };
+      expect(data.stdout.trim()).toBe("$(whoami)");
+    });
+  });
+
+  describe("executeSpawn", () => {
+    it("should spawn a background process and return PID", async () => {
+      let pid: number | undefined;
+      try {
+        const result = await executeSpawn({ program: "sleep", args: ["30"] }, ctx);
+
+        expect(result.success).toBe(true);
+        const data = result.data as { pid: number };
+        pid = data.pid;
+        expect(typeof data.pid).toBe("number");
+        expect(data.pid).toBeGreaterThan(0);
+      } finally {
+        // Clean up the spawned process
+        if (pid) {
+          try {
+            process.kill(pid, "SIGTERM");
+          } catch {
+            // Process may already be dead
+          }
+        }
+      }
+    });
+
+    it("should detach the process", async () => {
+      let pid: number | undefined;
+      try {
+        const result = await executeSpawn({ program: "sleep", args: ["30"] }, ctx);
+
+        expect(result.success).toBe(true);
+        const data = result.data as { pid: number };
+        pid = data.pid;
+
+        // Process should be running
+        const isRunning = () => {
+          try {
+            process.kill(data.pid, 0); // Signal 0 just checks if process exists
+            return true;
+          } catch {
+            return false;
+          }
+        };
+
+        expect(isRunning()).toBe(true);
+      } finally {
+        // Clean up
+        if (pid) {
+          try {
+            process.kill(pid, "SIGTERM");
+          } catch {
+            // Process may already be dead
+          }
+        }
+      }
+    });
+
+    it("should use working directory", async () => {
+      // Create a script that writes pwd to a file using realpath -s to resolve symlinks
+      const scriptPath = path.join(tempDir, "write_pwd.sh");
+      await fs.writeFile(scriptPath, "#!/bin/bash\npwd -P > pwd_output.txt", { mode: 0o755 });
+      const outputPath = path.join(tempDir, "pwd_output.txt");
+      const waitForOutput = waitForFile(outputPath, 10_000);
+
+      const result = await executeSpawn({ program: "/bin/bash", args: [scriptPath] }, ctx);
+
+      expect(result.success).toBe(true);
+      await waitForOutput;
+      const pwdOutput = await fs.readFile(outputPath, "utf-8");
+      expect(pwdOutput.trim()).toBe(tempDir);
+    }, 15_000);
+
+    it("should support custom cwd option", async () => {
+      const subDir = path.join(tempDir, "subdir");
+      await fs.mkdir(subDir);
+
+      const scriptPath = path.join(tempDir, "write_pwd.sh");
+      await fs.writeFile(scriptPath, "#!/bin/bash\npwd -P > pwd_output.txt", { mode: 0o755 });
+      const outputPath = path.join(subDir, "pwd_output.txt");
+      const waitForOutput = waitForFile(outputPath, 10_000);
+
+      const spawnResult = await executeSpawn(
+        { program: "/bin/bash", args: [scriptPath], cwd: subDir },
+        ctx,
+      );
+      expect(spawnResult.success).toBe(true);
+      await waitForOutput;
+      const pwdOutput = await fs.readFile(outputPath, "utf-8");
+      expect(pwdOutput.trim()).toBe(subDir);
+    }, 15_000);
+
+    it("should use environment variables from context", async () => {
+      const envCtx = createContext(tempDir, { SPAWN_VAR: "spawn_value" });
+
+      const scriptPath = path.join(tempDir, "write_env.sh");
+      await fs.writeFile(scriptPath, "#!/bin/bash\necho $SPAWN_VAR > env_output.txt", {
+        mode: 0o755,
+      });
+      const outputPath = path.join(tempDir, "env_output.txt");
+      const waitForOutput = waitForFile(outputPath);
+
+      await executeSpawn({ program: "/bin/bash", args: [scriptPath] }, envCtx);
+      await waitForOutput;
+      const envOutput = await fs.readFile(outputPath, "utf-8");
+      expect(envOutput.trim()).toBe("spawn_value");
+    });
+
+    it("should handle non-existent program", async () => {
+      const result = await executeSpawn({ program: "nonexistent_program_12345" }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBeDefined();
+    });
+  });
+
+  describe("executeKill", () => {
+    it("should kill a running process", async () => {
+      const child = spawnChild("sleep", ["60"], { stdio: "ignore" });
+      const pid = child.pid;
+      expect(typeof pid).toBe("number");
+      expect(pid).toBeGreaterThan(0);
+
+      try {
+        expect(() => process.kill(pid!, 0)).not.toThrow();
+
+        // Kill the process
+        const killResult = await executeKill({ pid: pid! }, ctx);
+
+        expect(killResult.success).toBe(true);
+        await waitForChildExit(child);
+        expect(() => process.kill(pid!, 0)).toThrow();
+      } finally {
+        // Ensure cleanup even if test fails
+        try {
+          process.kill(pid!, "SIGKILL");
+        } catch {
+          // Process may already be dead
+        }
+      }
+    });
+
+    it("should support custom signal", async () => {
+      const child = spawnChild("sleep", ["60"], { stdio: "ignore" });
+      const pid = child.pid;
+      expect(typeof pid).toBe("number");
+      expect(pid).toBeGreaterThan(0);
+
+      try {
+        // Kill with SIGKILL
+        const killResult = await executeKill({ pid: pid!, signal: "SIGKILL" }, ctx);
+
+        expect(killResult.success).toBe(true);
+        await waitForChildExit(child);
+        expect(() => process.kill(pid!, 0)).toThrow();
+      } finally {
+        // Ensure cleanup even if test fails
+        try {
+          process.kill(pid!, "SIGKILL");
+        } catch {
+          // Process may already be dead
+        }
+      }
+    });
+
+    it("should return error for non-existent PID", async () => {
+      // Use a very high PID that's unlikely to exist
+      const result = await executeKill({ pid: 999999999 }, ctx);
+
+      expect(result.success).toBe(false);
+      expect(result.message).toBeDefined();
+    });
+
+    it("should return error for invalid signal", async () => {
+      // Spawn a process
+      const spawnResult = await executeSpawn({ program: "sleep", args: ["60"] }, ctx);
+      const spawnData = spawnResult.data as { pid: number };
+      const pid = spawnData.pid;
+
+      try {
+        const result = await executeKill({ pid, signal: "INVALID_SIGNAL" }, ctx);
+
+        expect(result.success).toBe(false);
+        expect(result.message).toBeDefined();
+      } finally {
+        // Clean up
+        try {
+          process.kill(pid, "SIGTERM");
+        } catch {
+          // Process may already be dead
+        }
+      }
+    });
+  });
+
+  describe("integration: spawn and kill", () => {
+    it("should spawn a process and kill it by PID", async () => {
+      // Spawn a long-running process
+      const spawnResult = await executeSpawn({ program: "sleep", args: ["300"] }, ctx);
+
+      expect(spawnResult.success).toBe(true);
+      const { pid } = spawnResult.data as { pid: number };
+
+      try {
+        // Verify it's running
+        let isRunning = true;
+        try {
+          process.kill(pid, 0);
+        } catch {
+          isRunning = false;
+        }
+        expect(isRunning).toBe(true);
+
+        // Kill it
+        const killCtx = createContext(tempDir);
+        const killResult = await executeKill({ pid, signal: "SIGKILL" }, killCtx);
+        expect(killResult.success).toBe(true);
+        const waitResult = await executeWaitProcess({ pid, timeoutMs: 5_000 }, ctx);
+        expect(waitResult.success).toBe(true);
+      } finally {
+        // Ensure cleanup even if test fails
+        try {
+          process.kill(pid, "SIGKILL");
+        } catch {
+          // Process may already be dead
+        }
+      }
+    });
+  });
+
+  describe("abort signal", () => {
+    describe("executeBash", () => {
+      it("should return cancelled when signal is pre-aborted", async () => {
+        const ac = new AbortController();
+        ac.abort();
+        const abortCtx = { ...ctx, abortSignal: ac.signal };
+
+        const result = await executeBash({ command: 'echo "should not run"' }, abortCtx);
+
+        expect(result.success).toBe(false);
+        expect(result.message).toBe("Command cancelled");
+      });
+
+      it("should cancel a running command when signal fires", async () => {
+        const ac = new AbortController();
+        const abortCtx = { ...ctx, abortSignal: ac.signal };
+        const readyFile = path.join(tempDir, "bash-abort-ready");
+        const waitForReady = waitForFile(readyFile);
+        const resultPromise = executeBash(
+          { command: `touch ${shellQuote(readyFile)}; sleep 30` },
+          abortCtx,
+        );
+
+        await waitForReady;
+        ac.abort();
+
+        const result = await resultPromise;
+
+        expect(result.success).toBe(false);
+        expect(result.message).toBe("Command cancelled");
+      });
+    });
+
+    describe("executeExec", () => {
+      it("should return cancelled when signal is pre-aborted", async () => {
+        const ac = new AbortController();
+        ac.abort();
+        const abortCtx = { ...ctx, 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 process on abort", async () => {
+        const ac = new AbortController();
+        const abortCtx = { ...ctx, abortSignal: ac.signal };
+        const readyFile = path.join(tempDir, "exec-abort-ready");
+        const waitForReady = waitForFile(readyFile);
+        const resultPromise = executeExec(
+          {
+            program: "/bin/sh",
+            args: ["-c", `touch ${shellQuote(readyFile)}; sleep 30`],
+          },
+          abortCtx,
+        );
+
+        await waitForReady;
+        ac.abort();
+
+        const result = await resultPromise;
+
+        expect(result.success).toBe(false);
+        expect(result.message).toBe("Command cancelled");
+      });
+
+      it("should include partial output on abort", async () => {
+        const ac = new AbortController();
+        const abortCtx = { ...ctx, abortSignal: ac.signal };
+        const readyFile = path.join(tempDir, "exec-partial-ready");
+        const waitForReady = waitForFile(readyFile);
+
+        const resultPromise = executeExec(
+          {
+            program: "/bin/sh",
+            args: ["-c", `echo "partial output"; touch ${shellQuote(readyFile)}; sleep 30`],
+          },
+          abortCtx,
+        );
+
+        await waitForReady;
+        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");
+      }, 10000);
+    });
+
+    describe("executeSpawn", () => {
+      it("should return cancelled when signal is pre-aborted", async () => {
+        const ac = new AbortController();
+        ac.abort();
+        const abortCtx = { ...ctx, abortSignal: ac.signal };
+
+        const result = await executeSpawn({ program: "sleep", args: ["30"] }, abortCtx);
+
+        expect(result.success).toBe(false);
+        expect(result.message).toBe("Command cancelled");
+      });
+
+      it("should kill spawned process on abort", async () => {
+        const ac = new AbortController();
+        const abortCtx = { ...ctx, abortSignal: ac.signal };
+
+        const result = await executeSpawn({ program: "sleep", args: ["30"] }, abortCtx);
+        expect(result.success).toBe(true);
+        const data = result.data as { pid: number };
+        const pid = data.pid;
+
+        try {
+          // Process should be running
+          expect(() => process.kill(pid, 0)).not.toThrow();
+
+          // Abort the signal
+          ac.abort();
+          const waitResult = await executeWaitProcess({ pid, timeoutMs: 5_000 }, abortCtx);
+          expect(waitResult.success).toBe(true);
+          expect(() => process.kill(pid, 0)).toThrow();
+        } finally {
+          try {
+            process.kill(pid, "SIGKILL");
+          } catch {
+            // Process may already be dead
+          }
+        }
+      }, 10000);
+    });
+  });
+});