AI Dev Assistant

Instructions

Implementation Reference

• src/tools/terminalCommander.ts:146-268 (handler)

  The handler for the terminal_commander tool, responsible for command validation, shell spawning, and output formatting.

  async handler(args: {
    command: string;
    working_directory?: string;
    use_powershell?: boolean;
  }): Promise<string> {
    const { command, working_directory, use_powershell = false } = args;
  
    // ── Validation ──────────────────────────────────────────────────────────
    const validation = validateCommand(command);
    if (!validation.allowed) {
      return (
        `## ❌ Command Blocked\n\n` +
        `**Command:** \`${command}\`\n\n` +
        `**Reason:** ${validation.reason}\n\n` +
        `_If this command should be allowed, add it to the \`SAFE_COMMANDS_ALLOWLIST\` in \`src/tools/terminalCommander.ts\`._`
      );
    }
  
    // ── Working directory validation ─────────────────────────────────────────
    let cwd: string | undefined;
    if (working_directory) {
      cwd = path.resolve(working_directory);
      const fs = await import("fs");
      if (!fs.existsSync(cwd)) {
        return `ERROR: Working directory does not exist: ${cwd}`;
      }
    }
  
    // ── Spawn ────────────────────────────────────────────────────────────────
    const isWindows = process.platform === "win32";
    let shell: string;
    let shellArgs: string[];
  
    if (use_powershell) {
      shell = isWindows ? "powershell.exe" : "pwsh";
      shellArgs = ["-NonInteractive", "-Command", command];
    } else {
      shell = isWindows ? "cmd.exe" : "/bin/sh";
      shellArgs = isWindows ? ["/c", command] : ["-c", command];
    }
  
    const startTime = Date.now();
  
    const result = await new Promise<CommandResult>((resolve) => {
      const proc = spawn(shell, shellArgs, {
        cwd,
        windowsHide: true,
        env: process.env,
      });
  
      let stdout = "";
      let stderr = "";
      let timedOut = false;
  
      const killTimer = setTimeout(() => {
        timedOut = true;
        proc.kill("SIGKILL");
      }, TIMEOUT_MS);
  
      proc.stdout.on("data", (chunk: Buffer) => {
        stdout += chunk.toString();
        if (stdout.length > MAX_OUTPUT_BYTES) {
          stdout = stdout.slice(0, MAX_OUTPUT_BYTES) + "\n[OUTPUT TRUNCATED]";
          proc.kill("SIGKILL");
        }
      });
  
      proc.stderr.on("data", (chunk: Buffer) => {
        stderr += chunk.toString();
      });
  
      proc.on("close", (exitCode) => {
        clearTimeout(killTimer);
        resolve({
          command,
          workingDirectory: cwd ?? process.cwd(),
          stdout: stdout.trimEnd(),
          stderr: stderr.trimEnd(),
          exitCode,
          executionTimeMs: Date.now() - startTime,
          timedOut,
        });
      });
  
      proc.on("error", (err) => {
        clearTimeout(killTimer);
        resolve({
          command,
          workingDirectory: cwd ?? process.cwd(),
          stdout: "",
          stderr: `Failed to spawn shell: ${err.message}`,
          exitCode: -1,
          executionTimeMs: Date.now() - startTime,
          timedOut: false,
        });
      });
    });
  
    // ── Format output ────────────────────────────────────────────────────────
    const status = result.exitCode === 0 ? "✅ Success" : `⚠️ Exit Code ${result.exitCode}`;
    const lines: string[] = [
      `## Terminal Commander`,
      `**Command:** \`${result.command}\``,
      `**CWD:** ${result.workingDirectory}`,
      `**Shell:** ${use_powershell ? "PowerShell" : "CMD"}  |  **Status:** ${status}  |  **Time:** ${result.executionTimeMs}ms`,
    ];
  
    if (result.timedOut) {
      lines.push(`\n⏱️ **TIMED OUT** after ${TIMEOUT_MS / 1000} seconds.`);
    }
  
    if (result.stdout) {
      lines.push(`\n### Output\n\`\`\`\n${result.stdout}\n\`\`\``);
    } else {
      lines.push(`\n### Output\n*(empty)*`);
    }
  
    if (result.stderr) {
      lines.push(`\n### Stderr\n\`\`\`\n${result.stderr}\n\`\`\``);
    }
  
    return lines.join("\n");
  },

• src/tools/terminalCommander.ts:113-121 (registration)

  Tool registration for "terminal_commander" including metadata and schema.

  export function terminalCommanderTool() {
    return {
      name: "terminal_commander",
      description:
        "Executes a safe Windows CMD or PowerShell command on the local machine. " +
        "Protected by a strict allowlist — only pre-approved commands are permitted. " +
        "Dangerous patterns (rm -rf, del /s, format, shutdown, registry edits, etc.) are blocked even if the base command is allowed. " +
        "Allowed commands include: dir, git, node, npm, python, tsc, docker, ipconfig, and more. " +
        "Use this to run `git status`, `dir`, `npm install`, `tsc --noEmit`, etc.",