plugsuits 1.0.0

package/src/tools/utils/execute/output-handler.ts

@@ -0,0 +1,101 @@
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const ANSI_ESCAPE_PREFIX = `${String.fromCharCode(27)}${String.fromCharCode(155)}`;
+const ANSI_ESCAPE_PATTERN = new RegExp(
+  `[${ANSI_ESCAPE_PREFIX}][[()#;?]*(?:[0-9]{1,4}(?:;[0-9]{0,4})*)?[0-9A-ORZcf-nqry=><]`,
+  "g"
+);
+const MULTIPLE_NEWLINE_PATTERN = /\n{3,}/g;
+
+export interface TruncationResult {
+  fullOutputPath?: string;
+  originalBytes: number;
+  originalLines: number;
+  text: string;
+  truncated: boolean;
+}
+
+export function stripAnsi(text: string): string {
+  return text.replace(ANSI_ESCAPE_PATTERN, "");
+}
+
+export function sanitizeOutput(text: string): string {
+  return stripAnsi(text)
+    .replace(/\r/g, "")
+    .replace(MULTIPLE_NEWLINE_PATTERN, "\n\n");
+}
+
+async function persistFullOutput(text: string): Promise<string> {
+  for (let attempt = 0; attempt < 3; attempt += 1) {
+    const tempPath = join(tmpdir(), `cea-output-${randomUUID()}.txt`);
+    try {
+      await writeFile(tempPath, text, { encoding: "utf-8", flag: "wx" });
+      return tempPath;
+    } catch (error) {
+      if (
+        typeof error === "object" &&
+        error !== null &&
+        "code" in error &&
+        (error as NodeJS.ErrnoException).code === "EEXIST"
+      ) {
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new Error("Failed to persist truncated output.");
+}
+
+export async function truncateOutput(
+  text: string,
+  options: { maxLines?: number; maxBytes?: number } = {}
+): Promise<TruncationResult> {
+  const maxLines = options.maxLines ?? 2000;
+  const maxBytes = options.maxBytes ?? 51_200;
+
+  const originalLines = text.split("\n").length;
+  const originalBytes = Buffer.byteLength(text);
+
+  if (originalLines <= maxLines && originalBytes <= maxBytes) {
+    return {
+      text,
+      truncated: false,
+      originalLines,
+      originalBytes,
+    };
+  }
+
+  const firstLineLimit = Math.max(1, Math.floor(maxLines * 0.2));
+  const lastLineLimit = Math.max(0, maxLines - 1 - firstLineLimit);
+
+  const lines = text.split("\n");
+  const firstLines = lines.slice(0, firstLineLimit);
+  const lastStart = Math.max(firstLines.length, lines.length - lastLineLimit);
+  const lastLines = lines.slice(lastStart);
+  const omittedLineCount = Math.max(
+    0,
+    lines.length - (firstLines.length + lastLines.length)
+  );
+
+  const tempPath = await persistFullOutput(text);
+
+  const truncatedText = [
+    ...firstLines,
+    `[...] ${omittedLineCount} lines omitted. Full output saved to ${tempPath}. Use read_file to view specific sections.`,
+    ...lastLines,
+  ]
+    .filter((line) => line.length > 0)
+    .join("\n");
+
+  return {
+    text: truncatedText,
+    truncated: true,
+    fullOutputPath: tempPath,
+    originalLines,
+    originalBytes,
+  };
+}

package/src/tools/utils/execute/process-manager.test.ts

@@ -0,0 +1,175 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import { spawn } from "node:child_process";
+import { existsSync, mkdtempSync, realpathSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { executeCommand, killProcessTree } from "./process-manager";
+import { getShell, getShellArgs } from "./shell-detection";
+
+const FIVE_SECONDS_MS = 5000;
+const SIGKILL_GRACE_MS = 1000;
+const ABORT_DELAY_MS = 50;
+const SHORT_TIMEOUT_MS = 100;
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: string }).code === code
+  );
+}
+
+function isProcessAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return hasErrnoCode(error, "EPERM");
+  }
+}
+
+function sleep(ms: number): Promise<void> {
+  return new Promise((resolve) => {
+    setTimeout(resolve, ms);
+  });
+}
+
+describe("process-manager", () => {
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "process-manager-test-"));
+  });
+
+  afterAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true, force: true });
+    }
+  });
+
+  it("returns exact command result for echo hello", async () => {
+    const result = await executeCommand("echo hello");
+
+    expect(result).toEqual({
+      exitCode: 0,
+      output: "hello\n",
+      cancelled: false,
+      timedOut: false,
+    });
+  });
+
+  it("returns non-zero exit code for failing command", async () => {
+    const result = await executeCommand("exit 1");
+
+    expect(result.exitCode).toBe(1);
+    expect(result.cancelled).toBe(false);
+    expect(result.timedOut).toBe(false);
+  });
+
+  it("executes commands in provided workdir", async () => {
+    const result = await executeCommand("pwd", { workdir: tempDir });
+    const actualWorkdir = realpathSync(result.output.trim());
+    const expectedWorkdir = realpathSync(tempDir);
+
+    expect(result.exitCode).toBe(0);
+    expect(actualWorkdir).toBe(expectedWorkdir);
+  });
+
+  it("uses stdin ignore by default", async () => {
+    const startedAt = Date.now();
+    const result = await executeCommand("cat", { timeoutMs: FIVE_SECONDS_MS });
+    const elapsed = Date.now() - startedAt;
+
+    expect(result.exitCode).toBe(0);
+    expect(result.timedOut).toBe(false);
+    expect(elapsed).toBeLessThan(FIVE_SECONDS_MS);
+  });
+
+  it("streams combined chunks through onChunk callback", async () => {
+    const streamedChunks: string[] = [];
+
+    const result = await executeCommand(
+      "printf 'stdout-chunk'; printf 'stderr-chunk' >&2",
+      {
+        onChunk: (chunk) => {
+          streamedChunks.push(chunk);
+        },
+      }
+    );
+
+    const streamedOutput = streamedChunks.join("");
+
+    expect(result.exitCode).toBe(0);
+    expect(result.output).toContain("stdout-chunk");
+    expect(result.output).toContain("stderr-chunk");
+    expect(streamedChunks.length).toBeGreaterThan(0);
+    expect(streamedOutput).toContain("stdout-chunk");
+    expect(streamedOutput).toContain("stderr-chunk");
+  });
+
+  it("sets timedOut=true and kills process within 5 seconds", async () => {
+    const startedAt = Date.now();
+    const result = await executeCommand("trap '' TERM; sleep 30", {
+      timeoutMs: SHORT_TIMEOUT_MS,
+    });
+    const elapsed = Date.now() - startedAt;
+
+    expect(result.timedOut).toBe(true);
+    expect(result.cancelled).toBe(false);
+    expect(result.exitCode).toBe(124);
+    expect(elapsed).toBeLessThan(FIVE_SECONDS_MS);
+  }, 10_000);
+
+  it("supports AbortSignal cancellation", async () => {
+    const controller = new AbortController();
+    const startedAt = Date.now();
+    const command = executeCommand("sleep 30", { signal: controller.signal });
+
+    setTimeout(() => {
+      controller.abort();
+    }, ABORT_DELAY_MS);
+
+    const result = await command;
+    const elapsed = Date.now() - startedAt;
+
+    expect(result.cancelled).toBe(true);
+    expect(result.timedOut).toBe(false);
+    expect(result.exitCode).toBe(130);
+    expect(elapsed).toBeLessThan(FIVE_SECONDS_MS);
+  }, 10_000);
+
+  it("killProcessTree terminates detached process groups", async () => {
+    const shell = getShell();
+    const shellArgs = getShellArgs(shell);
+    const child = spawn(shell, [...shellArgs, "trap '' TERM; sleep 30"], {
+      detached: true,
+      stdio: ["ignore", "ignore", "ignore"],
+    });
+
+    const pid = child.pid;
+    expect(pid).toBeDefined();
+
+    if (!pid) {
+      throw new Error("Expected detached child pid to be defined");
+    }
+
+    try {
+      await sleep(ABORT_DELAY_MS);
+      killProcessTree(pid);
+      await sleep(SIGKILL_GRACE_MS);
+
+      expect(isProcessAlive(pid)).toBe(false);
+    } finally {
+      killProcessTree(pid);
+    }
+  }, 10_000);
+
+  it("does not use spawnSync", async () => {
+    const source = await Bun.file(
+      new URL("./process-manager.ts", import.meta.url)
+    ).text();
+
+    expect(source.includes("spawnSync")).toBe(false);
+  });
+});

package/src/tools/utils/execute/process-manager.ts

@@ -0,0 +1,310 @@
+import { spawn } from "node:child_process";
+import { getFullWrappedCommand as wrapCommand } from "./noninteractive-wrapper";
+import { sanitizeOutput, truncateOutput } from "./output-handler";
+import { getShell, getShellArgs } from "./shell-detection";
+
+const DEFAULT_TIMEOUT_MS = 120_000;
+const SIGKILL_DELAY_MS = 200;
+const SPAWN_ERROR_EXIT_CODE = 1;
+const CANCELLED_EXIT_CODE = 130;
+const TIMEOUT_EXIT_CODE = 124;
+const MAX_IN_MEMORY_OUTPUT_BYTES = 2 * 1024 * 1024;
+const TRIMMED_BUFFER_TARGET_BYTES = 512 * 1024;
+const activeProcesses = new Set<number>();
+
+export interface ExecuteOptions {
+  onChunk?: (chunk: string) => void;
+  signal?: AbortSignal;
+  stdin?: "ignore" | "pipe";
+  timeoutMs?: number;
+  workdir?: string;
+}
+
+export interface ExecuteResult {
+  cancelled: boolean;
+  exitCode: number;
+  output: string;
+  timedOut: boolean;
+}
+
+function hasErrnoCode(error: unknown, code: string): boolean {
+  return (
+    typeof error === "object" &&
+    error !== null &&
+    "code" in error &&
+    (error as { code?: string }).code === code
+  );
+}
+
+function isProcessGroupAlive(pid: number): boolean {
+  if (pid <= 1) {
+    return false;
+  }
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch (error) {
+    return hasErrnoCode(error, "EPERM");
+  }
+}
+
+function safeKillProcessGroup(pid: number, signal: NodeJS.Signals): void {
+  if (pid <= 1) {
+    return;
+  }
+  try {
+    process.kill(-pid, signal);
+  } catch (error) {
+    if (hasErrnoCode(error, "ESRCH") || hasErrnoCode(error, "EPERM")) {
+      return;
+    }
+    throw error;
+  }
+}
+
+function resolveExitCode(
+  code: number | null,
+  timedOut: boolean,
+  cancelled: boolean,
+  spawnFailed: boolean
+): number {
+  if (typeof code === "number") {
+    return code;
+  }
+
+  if (timedOut) {
+    return TIMEOUT_EXIT_CODE;
+  }
+
+  if (cancelled) {
+    return CANCELLED_EXIT_CODE;
+  }
+
+  if (spawnFailed) {
+    return SPAWN_ERROR_EXIT_CODE;
+  }
+
+  return SPAWN_ERROR_EXIT_CODE;
+}
+
+function trimToLastBytes(
+  text: string,
+  maxBytes: number
+): { droppedBytes: number; text: string } {
+  const bytes = Buffer.from(text, "utf-8");
+  if (bytes.length <= maxBytes) {
+    return { text, droppedBytes: 0 };
+  }
+
+  const start = bytes.length - maxBytes;
+
+  return {
+    text: bytes.subarray(start).toString("utf-8"),
+    droppedBytes: start,
+  };
+}
+
+export function killProcessTree(pid: number, force = false): void {
+  if (pid <= 1) {
+    return;
+  }
+
+  safeKillProcessGroup(pid, "SIGTERM");
+
+  if (force) {
+    safeKillProcessGroup(pid, "SIGKILL");
+    return;
+  }
+
+  const handle = setTimeout(() => {
+    if (!isProcessGroupAlive(pid)) {
+      return;
+    }
+    safeKillProcessGroup(pid, "SIGKILL");
+  }, SIGKILL_DELAY_MS);
+  if (typeof handle === "object" && "unref" in handle) {
+    handle.unref();
+  }
+}
+
+export async function executeCommand(
+  command: string,
+  options: ExecuteOptions = {}
+): Promise<ExecuteResult> {
+  const {
+    workdir,
+    timeoutMs = DEFAULT_TIMEOUT_MS,
+    signal,
+    onChunk,
+    stdin = "ignore",
+  } = options;
+
+  if (signal?.aborted) {
+    return {
+      exitCode: CANCELLED_EXIT_CODE,
+      output: "",
+      cancelled: true,
+      timedOut: false,
+    };
+  }
+
+  const shell = getShell();
+  const shellArgs = getShellArgs(shell);
+  const wrappedCommand = wrapCommand(command);
+
+  return await new Promise<ExecuteResult>((resolve) => {
+    const child = spawn(shell, [...shellArgs, wrappedCommand], {
+      detached: true,
+      stdio: [stdin, "pipe", "pipe"],
+      cwd: workdir,
+      env: {
+        ...process.env,
+        TERM: "dumb",
+      },
+    });
+
+    child.unref();
+
+    if (child.pid) {
+      activeProcesses.add(child.pid);
+    }
+
+    const stdoutDecoder = new TextDecoder();
+    const stderrDecoder = new TextDecoder();
+    let bufferedOutput = "";
+    let droppedBytes = 0;
+
+    let timedOut = false;
+    let cancelled = false;
+    let spawnFailed = false;
+    let settled = false;
+
+    const timeoutHandle = setTimeout(() => {
+      timedOut = true;
+      if (child.pid) {
+        killProcessTree(child.pid);
+      }
+    }, timeoutMs);
+
+    const abortHandler = () => {
+      cancelled = true;
+      if (child.pid) {
+        killProcessTree(child.pid);
+      }
+    };
+
+    if (signal) {
+      signal.addEventListener("abort", abortHandler, { once: true });
+    }
+
+    const appendChunk = (chunk: Buffer, decoder: TextDecoder): void => {
+      const decoded = decoder.decode(chunk, { stream: true });
+      bufferedOutput += decoded;
+      if (
+        Buffer.byteLength(bufferedOutput, "utf-8") > MAX_IN_MEMORY_OUTPUT_BYTES
+      ) {
+        const trimmed = trimToLastBytes(
+          bufferedOutput,
+          TRIMMED_BUFFER_TARGET_BYTES
+        );
+        bufferedOutput = trimmed.text;
+        droppedBytes += trimmed.droppedBytes;
+      }
+      onChunk?.(decoded);
+    };
+
+    const flushDecoder = (decoder: TextDecoder): void => {
+      const remaining = decoder.decode();
+      if (!remaining) {
+        return;
+      }
+      bufferedOutput += remaining;
+      if (
+        Buffer.byteLength(bufferedOutput, "utf-8") > MAX_IN_MEMORY_OUTPUT_BYTES
+      ) {
+        const trimmed = trimToLastBytes(
+          bufferedOutput,
+          TRIMMED_BUFFER_TARGET_BYTES
+        );
+        bufferedOutput = trimmed.text;
+        droppedBytes += trimmed.droppedBytes;
+      }
+      onChunk?.(remaining);
+    };
+
+    const finish = (code: number | null): void => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+
+      if (child.pid) {
+        activeProcesses.delete(child.pid);
+      }
+
+      clearTimeout(timeoutHandle);
+      if (signal) {
+        signal.removeEventListener("abort", abortHandler);
+      }
+
+      flushDecoder(stdoutDecoder);
+      flushDecoder(stderrDecoder);
+
+      const sanitizedOutput = sanitizeOutput(bufferedOutput);
+      const withDroppedPrefix =
+        droppedBytes > 0
+          ? `[... ${droppedBytes} bytes omitted before completion due to output volume ...]\n${sanitizedOutput}`
+          : sanitizedOutput;
+      truncateOutput(withDroppedPrefix)
+        .then((truncatedOutput) => {
+          resolve({
+            exitCode: resolveExitCode(code, timedOut, cancelled, spawnFailed),
+            output: truncatedOutput.text,
+            cancelled,
+            timedOut,
+          });
+        })
+        .catch((error) => {
+          const errorMessage =
+            error instanceof Error
+              ? error.message
+              : "Failed to truncate output.";
+          resolve({
+            exitCode: resolveExitCode(code, timedOut, cancelled, spawnFailed),
+            output: `${withDroppedPrefix}\n${errorMessage}`,
+            cancelled,
+            timedOut,
+          });
+        });
+    };
+
+    child.stdout?.on("data", (chunk: Buffer) => {
+      appendChunk(chunk, stdoutDecoder);
+    });
+
+    child.stderr?.on("data", (chunk: Buffer) => {
+      appendChunk(chunk, stderrDecoder);
+    });
+
+    child.on("close", (code) => {
+      finish(code);
+    });
+
+    child.on("error", (error) => {
+      spawnFailed = true;
+      bufferedOutput += `${(error as Error).message}\n`;
+      finish(null);
+    });
+  });
+}
+
+export function cleanup(force = false): void {
+  for (const pid of activeProcesses) {
+    try {
+      killProcessTree(pid, force);
+    } catch {
+      // Best-effort cleanup: continue killing remaining processes
+    }
+  }
+  activeProcesses.clear();
+}

package/src/tools/utils/execute/shell-detection.test.ts

@@ -0,0 +1,112 @@
+import { describe, expect, test } from "bun:test";
+import { spawnSync } from "node:child_process";
+import { existsSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { platform, tmpdir } from "node:os";
+import { dirname, join } from "node:path";
+import { getShell, getShellArgs } from "./shell-detection";
+
+const SHELL_DETECTION_SCRIPT =
+  "import { getShell } from './shell-detection'; console.log(getShell());";
+const SHELL_DETECTION_CWD = join(
+  process.cwd(),
+  "packages",
+  "cea",
+  "src",
+  "tools",
+  "utils",
+  "execute"
+);
+
+function runShellDetectionWithEnv(shellPath: string): string {
+  const env = { ...process.env, SHELL: shellPath };
+  const result = spawnSync(process.execPath, ["-e", SHELL_DETECTION_SCRIPT], {
+    cwd: SHELL_DETECTION_CWD,
+    env,
+    encoding: "utf8",
+  });
+
+  if (result.status !== 0 || !result.stdout) {
+    throw new Error("Failed to evaluate getShell in child process");
+  }
+
+  return result.stdout.trim();
+}
+
+function createFakeShell(shellName: string): string {
+  const tempDir = mkdtempSync(join(tmpdir(), "shell-detection-"));
+  const shellPath = join(tempDir, shellName);
+  writeFileSync(shellPath, "#!/bin/sh\n");
+  return shellPath;
+}
+
+function removeFakeShell(shellPath: string): void {
+  rmSync(shellPath, { force: true });
+  rmSync(dirname(shellPath), { recursive: true, force: true });
+}
+
+function getFallbackCandidates(): string[] {
+  if (platform() === "darwin") {
+    return ["/bin/zsh", "/bin/bash", "/bin/sh"];
+  }
+
+  if (platform() === "linux") {
+    return ["/bin/bash", "/bin/sh"];
+  }
+
+  return ["C:\\Program Files\\Git\\bin\\bash.exe", "cmd.exe"];
+}
+
+describe("shell detection", () => {
+  test("returns a valid shell path", () => {
+    const shell = getShell();
+
+    expect(typeof shell).toBe("string");
+    expect(shell.length).toBeGreaterThan(0);
+    expect(existsSync(shell)).toBe(true);
+  });
+
+  test("returns cached shell path on repeated calls", () => {
+    const first = getShell();
+    const second = getShell();
+
+    expect(first).toBe(second);
+  });
+
+  test("uses explicit SHELL path when valid", () => {
+    const fakeShell = createFakeShell("zsh-shell");
+    try {
+      const shell = runShellDetectionWithEnv(fakeShell);
+      expect(shell).toBe(fakeShell);
+    } finally {
+      removeFakeShell(fakeShell);
+    }
+  });
+
+  test("falls back when SHELL is rejected", () => {
+    const fakeRejectedShell = createFakeShell("fish");
+    try {
+      const shell = runShellDetectionWithEnv(fakeRejectedShell);
+      const candidates = getFallbackCandidates();
+      const availableFallback = candidates.find((candidate) =>
+        existsSync(candidate)
+      );
+
+      if (availableFallback) {
+        expect(shell).toBe(availableFallback);
+      }
+      expect(shell).not.toBe(fakeRejectedShell);
+      expect(existsSync(shell)).toBe(true);
+    } finally {
+      removeFakeShell(fakeRejectedShell);
+    }
+  });
+
+  test("returns args for unix shell format", () => {
+    expect(getShellArgs("/bin/bash")).toEqual(["-c"]);
+    expect(getShellArgs("/usr/bin/sh")).toEqual(["-c"]);
+  });
+
+  test("returns args for cmd.exe", () => {
+    expect(getShellArgs("C:\\Windows\\System32\\cmd.exe")).toEqual(["/c"]);
+  });
+});