plugsuits 1.0.0

package/src/tools/execute/shell-interact.test.ts

@@ -0,0 +1,236 @@
+import { describe, expect, it } from "bun:test";
+import {
+  type InteractResult,
+  parseKeys,
+  shellInteractTool,
+} from "./shell-interact";
+
+async function interact(
+  keystrokes: string,
+  timeout_ms = 200
+): Promise<InteractResult> {
+  const execute = shellInteractTool.execute;
+  if (!execute) {
+    throw new Error("shellInteractTool.execute is undefined");
+  }
+
+  const result = await execute(
+    { keystrokes, timeout_ms },
+    {
+      toolCallId: `test-${Date.now()}`,
+      messages: [],
+      abortSignal: new AbortController().signal,
+    }
+  );
+
+  if (Symbol.asyncIterator in (result as object)) {
+    throw new Error("Unexpected async iterable result");
+  }
+
+  return result as InteractResult;
+}
+
+describe("shellInteractTool", () => {
+  describe("result shape", () => {
+    it("returns { success: true, output: string }", async () => {
+      const result = await interact("echo test");
+
+      expect(result.success).toBe(true);
+      expect(typeof result.output).toBe("string");
+      expect(result.output.length).toBeGreaterThan(0);
+    });
+
+    it("always succeeds regardless of keystrokes", async () => {
+      const result = await interact("anything at all");
+
+      expect(result.success).toBe(true);
+    });
+  });
+
+  describe("Ctrl+C guidance", () => {
+    it("returns Ctrl+C guidance for <Ctrl+C>", async () => {
+      const result = await interact("<Ctrl+C>");
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain("No retained terminal context exists");
+      expect(result.output).toContain("kill -SIGINT");
+    });
+
+    it("returns Ctrl+C guidance for <CTRL+C> (uppercase)", async () => {
+      const result = await interact("<CTRL+C>");
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain("kill -SIGINT");
+    });
+
+    it("returns Ctrl+C guidance for <C-c> (dash syntax)", async () => {
+      const result = await interact("<C-c>");
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain("kill -SIGINT");
+    });
+
+    it("returns Ctrl+C guidance for html-encoded &lt;Ctrl+C&gt;", async () => {
+      const result = await interact("&lt;Ctrl+C&gt;");
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain("kill -SIGINT");
+    });
+
+    it("Ctrl+C guidance mentions timeout", async () => {
+      const result = await interact("<Ctrl+C>");
+
+      expect(result.output).toContain("120s");
+    });
+  });
+
+  describe("generic guidance for other keystrokes", () => {
+    it("returns generic guidance for plain text", async () => {
+      const result = await interact("ls -la");
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain("No retained terminal context exists");
+      expect(result.output).toContain("shell_execute");
+      expect(result.output).not.toContain("kill -SIGINT");
+    });
+
+    it("returns generic guidance for Enter key", async () => {
+      const result = await interact("echo hello<Enter>");
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain("shell_execute");
+      expect(result.output).not.toContain("kill -SIGINT");
+    });
+
+    it("returns generic guidance for Ctrl+D", async () => {
+      const result = await interact("<Ctrl+D>");
+
+      expect(result.success).toBe(true);
+      expect(result.output).not.toContain("kill -SIGINT");
+    });
+
+    it("returns generic guidance for empty keystrokes", async () => {
+      const result = await interact("");
+
+      expect(result.success).toBe(true);
+      expect(result.output).toContain("shell_execute");
+    });
+
+    it("explains no retained terminal context exists", async () => {
+      const result = await interact("any command");
+
+      expect(result.output).toContain(
+        "No retained terminal context exists. Each shell_execute command runs independently."
+      );
+    });
+  });
+
+  describe("tool metadata", () => {
+    it("has description mentioning shell_execute", () => {
+      expect(shellInteractTool.description).toContain("shell_execute");
+    });
+
+    it("accepts keystrokes in inputSchema", () => {
+      expect(shellInteractTool.inputSchema).toBeDefined();
+    });
+  });
+
+  describe("parseKeys utility", () => {
+    it("parses plain text as individual characters", () => {
+      const result = parseKeys("abc");
+      expect(result).toEqual(["a", "b", "c"]);
+    });
+
+    it("parses <Enter> to Enter", () => {
+      const result = parseKeys("<Enter>");
+      expect(result).toEqual(["Enter"]);
+    });
+
+    it("parses <Ctrl+C> to C-c", () => {
+      const result = parseKeys("<Ctrl+C>");
+      expect(result).toEqual(["C-c"]);
+    });
+
+    it("parses <Tab> to Tab", () => {
+      const result = parseKeys("<Tab>");
+      expect(result).toEqual(["Tab"]);
+    });
+
+    it("parses <Escape> and <ESC>", () => {
+      expect(parseKeys("<Escape>")).toEqual(["Escape"]);
+      expect(parseKeys("<ESC>")).toEqual(["Escape"]);
+    });
+
+    it("parses <Up> <Down> <Left> <Right>", () => {
+      expect(parseKeys("<Up>")).toEqual(["Up"]);
+      expect(parseKeys("<Down>")).toEqual(["Down"]);
+      expect(parseKeys("<Left>")).toEqual(["Left"]);
+      expect(parseKeys("<Right>")).toEqual(["Right"]);
+    });
+
+    it("parses <Home> and <End>", () => {
+      expect(parseKeys("<Home>")).toEqual(["Home"]);
+      expect(parseKeys("<End>")).toEqual(["End"]);
+    });
+
+    it("parses <Backspace> and <Delete>", () => {
+      expect(parseKeys("<Backspace>")).toEqual(["BSpace"]);
+      expect(parseKeys("<Delete>")).toEqual(["DC"]);
+    });
+
+    it("parses <Space>", () => {
+      expect(parseKeys("<Space>")).toEqual(["Space"]);
+    });
+
+    it("parses mixed text and special keys", () => {
+      const result = parseKeys("echo<Space>hello<Enter>");
+      expect(result).toEqual([
+        "e",
+        "c",
+        "h",
+        "o",
+        "Space",
+        "h",
+        "e",
+        "l",
+        "l",
+        "o",
+        "Enter",
+      ]);
+    });
+
+    it("parses <C-c> dash syntax to C-c", () => {
+      const result = parseKeys("<C-c>");
+      expect(result).toEqual(["C-c"]);
+    });
+
+    it("parses <ctrl-c> dash syntax to C-c", () => {
+      const result = parseKeys("<ctrl-c>");
+      expect(result).toEqual(["C-c"]);
+    });
+
+    it("handles html-encoded &lt;Ctrl+C&gt;", () => {
+      const result = parseKeys("&lt;Ctrl+C&gt;");
+      expect(result).toEqual(["C-c"]);
+    });
+
+    it("preserves HTML entities in plain text (non-special)", () => {
+      const parsed = parseKeys(
+        "echo '&lt;entity-preserve-tag&gt; &amp; preserve-amp'"
+      );
+      expect(parsed.join("")).toBe(
+        "echo '&lt;entity-preserve-tag&gt; &amp; preserve-amp'"
+      );
+    });
+
+    it("treats unknown <token> as literal characters", () => {
+      const result = parseKeys("<unknown>");
+      expect(result.join("")).toBe("<unknown>");
+    });
+
+    it("parses <PageUp> and <PageDown>", () => {
+      expect(parseKeys("<PageUp>")).toEqual(["PPage"]);
+      expect(parseKeys("<PageDown>")).toEqual(["NPage"]);
+    });
+  });
+});

package/src/tools/execute/shell-interact.ts

@@ -0,0 +1,151 @@
+import { tool } from "ai";
+import { z } from "zod";
+import SHELL_INTERACT_DESCRIPTION from "./shell-interact.txt";
+
+const SPECIAL_KEYS: Record<string, string> = {
+  enter: "Enter",
+  tab: "Tab",
+  escape: "Escape",
+  esc: "Escape",
+  backspace: "BSpace",
+  delete: "DC",
+  del: "DC",
+  up: "Up",
+  down: "Down",
+  left: "Left",
+  right: "Right",
+  home: "Home",
+  end: "End",
+  pageup: "PPage",
+  pagedown: "NPage",
+  space: "Space",
+  "ctrl+c": "C-c",
+  "ctrl+d": "C-d",
+  "ctrl+z": "C-z",
+  "ctrl+l": "C-l",
+  "ctrl+a": "C-a",
+  "ctrl+e": "C-e",
+  "ctrl+k": "C-k",
+  "ctrl+u": "C-u",
+  "ctrl+w": "C-w",
+  "ctrl+r": "C-r",
+};
+
+const HTML_TOKEN_START = "&lt;";
+const HTML_TOKEN_END = "&gt;";
+const HTML_AMP_PATTERN = /&amp;/gi;
+const CTRL_DASH_SHORTCUT_PATTERN = /^c-[a-z]$/;
+const CTRL_DASH_PATTERN = /^ctrl-[a-z]$/;
+
+function normalizeSpecialToken(token: string): string {
+  const compact = token.toLowerCase().replace(/\s+/g, "");
+
+  if (CTRL_DASH_SHORTCUT_PATTERN.test(compact)) {
+    return `ctrl+${compact[2]}`;
+  }
+
+  if (CTRL_DASH_PATTERN.test(compact)) {
+    return `ctrl+${compact[5]}`;
+  }
+
+  return compact;
+}
+
+function mapSpecialToken(token: string): string | undefined {
+  const normalizedToken = normalizeSpecialToken(token);
+  return SPECIAL_KEYS[normalizedToken];
+}
+
+export function parseKeys(input: string): string[] {
+  const keys: string[] = [];
+  let i = 0;
+
+  while (i < input.length) {
+    const current = input[i];
+
+    if (current === "<") {
+      const closingIndex = input.indexOf(">", i + 1);
+      if (closingIndex !== -1) {
+        const token = input.slice(i + 1, closingIndex);
+        const mappedKey = mapSpecialToken(token);
+
+        if (mappedKey) {
+          keys.push(mappedKey);
+          i = closingIndex + 1;
+          continue;
+        }
+      }
+    }
+
+    if (input.startsWith(HTML_TOKEN_START, i)) {
+      const tokenStart = i + HTML_TOKEN_START.length;
+      const encodedClosingIndex = input.indexOf(HTML_TOKEN_END, tokenStart);
+      if (encodedClosingIndex !== -1) {
+        const encodedToken = input.slice(tokenStart, encodedClosingIndex);
+        const token = encodedToken.replace(HTML_AMP_PATTERN, "&");
+        const mappedKey = mapSpecialToken(token);
+
+        if (mappedKey) {
+          keys.push(mappedKey);
+          i = encodedClosingIndex + HTML_TOKEN_END.length;
+          continue;
+        }
+      }
+    }
+
+    keys.push(current);
+    i++;
+  }
+
+  return keys;
+}
+
+export interface InteractResult {
+  output: string;
+  success: boolean;
+}
+
+const DEFAULT_SHELL_EXECUTE_TIMEOUT_SEC = 120;
+
+const CTRL_C_GUIDANCE = [
+  "No retained terminal context exists. Each shell_execute command runs independently.",
+  `To interrupt a long-running command, wait for its timeout (default: ${DEFAULT_SHELL_EXECUTE_TIMEOUT_SEC}s) or use shell_execute to kill the process by PID:`,
+  '  shell_execute({ command: "kill -SIGINT <PID>" })',
+].join("\n");
+
+const GENERIC_GUIDANCE = [
+  "No retained terminal context exists. Each shell_execute command runs independently.",
+  "To run a command, use shell_execute directly:",
+  '  shell_execute({ command: "your command here" })',
+].join("\n");
+
+function hasCtrlC(parsedKeys: string[]): boolean {
+  return parsedKeys.includes("C-c");
+}
+
+export const shellInteractTool = tool({
+  description: SHELL_INTERACT_DESCRIPTION,
+
+  inputSchema: z.object({
+    keystrokes: z
+      .string()
+      .describe(
+        "Keystrokes to send. Use <SpecialKey> syntax. " +
+          "Examples: 'y<Enter>', '<Ctrl+C>', 'ls<Enter>'"
+      ),
+    timeout_ms: z
+      .number()
+      .optional()
+      .describe("Wait time after sending keys (default: 500)"),
+  }),
+
+  execute: ({ keystrokes }): Promise<InteractResult> => {
+    const parsedKeys = parseKeys(keystrokes);
+    const guidance = hasCtrlC(parsedKeys) ? CTRL_C_GUIDANCE : GENERIC_GUIDANCE;
+
+    return Promise.resolve({
+      success: true,
+      output: guidance,
+    });
+  },
+});

package/src/tools/execute/shell-interact.txt

@@ -0,0 +1,15 @@
+### shell_interact
+**Purpose**: Return guidance for interactive process handling
+
+**When to use**:
+- Prompt response guidance (`y<Enter>`, `n<Enter>`, `<Ctrl+C>`)
+- Recovering from long-running interactive workflows
+
+**Important constraint**:
+- This tool does not control a persistent terminal session
+- It returns instructions only; it does not execute commands
+
+**Notes**:
+- No terminal session is retained between calls
+- Use `shell_execute` for actual command execution
+- For interruption, use timeout handling or explicit `shell_execute` kill commands

package/src/tools/explore/glob-files.txt

@@ -0,0 +1,8 @@
+### glob_files
+**Purpose**: Find files matching glob patterns
+
+**When to use**:
+- Finding files by name/extension: `**/*.ts`, `src/**/*.json`
+- Locating config files and discovering structure
+
+**DO NOT use shell**: Prefer this over `find`, `ls`, `tree`

package/src/tools/explore/glob.test.ts

@@ -0,0 +1,217 @@
+import { afterAll, beforeAll, describe, expect, it } from "bun:test";
+import {
+  existsSync,
+  mkdirSync,
+  mkdtempSync,
+  rmSync,
+  writeFileSync,
+} from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { executeGlob } from "./glob";
+
+describe("executeGlob", () => {
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "glob-test-"));
+    writeFileSync(join(tempDir, "file1.ts"), "content1");
+    writeFileSync(join(tempDir, "file2.ts"), "content2");
+    writeFileSync(join(tempDir, "file3.js"), "content3");
+    mkdirSync(join(tempDir, "sub"));
+    writeFileSync(join(tempDir, "sub", "nested.ts"), "nested");
+  });
+
+  afterAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true });
+    }
+  });
+
+  describe("basic glob operations", () => {
+    it("returns structured response with matches", async () => {
+      const result = await executeGlob({ pattern: "**/*.ts", path: tempDir });
+
+      expect(result).toContain("OK - glob");
+      expect(result).toContain('pattern: "**/*.ts"');
+      expect(result).toContain("file_count:");
+      expect(result).toContain("sorted_by: mtime desc");
+      expect(result).toContain("======== glob results ========");
+      expect(result).toContain(".ts");
+      expect(result).toContain("======== end ========");
+    });
+
+    it("shows file count correctly", async () => {
+      const result = await executeGlob({ pattern: "**/*.ts", path: tempDir });
+
+      expect(result).toContain("file_count: 3");
+    });
+
+    it("returns no matches when pattern doesn't match", async () => {
+      const result = await executeGlob({ pattern: "**/*.xyz", path: tempDir });
+
+      expect(result).toContain("OK - glob (no matches)");
+      expect(result).toContain("file_count: 0");
+      expect(result).toContain("(no matches)");
+    });
+  });
+
+  describe("file listing format", () => {
+    it("does not include mtime for each file", async () => {
+      const result = await executeGlob({ pattern: "*.ts", path: tempDir });
+
+      expect(result).toContain(".ts");
+      expect(result).not.toContain(" | mtime: ");
+    });
+
+    it("does not include numbered list", async () => {
+      const result = await executeGlob({ pattern: "*.ts", path: tempDir });
+
+      expect(result).toContain(".ts");
+      expect(result).not.toContain("   1 |");
+      expect(result).not.toContain("   2 |");
+    });
+
+    it("includes full path", async () => {
+      const result = await executeGlob({ pattern: "*.ts", path: tempDir });
+
+      expect(result).toContain(tempDir);
+    });
+  });
+
+  describe("recursive search", () => {
+    it("finds files in subdirectories with **", async () => {
+      const result = await executeGlob({ pattern: "**/*.ts", path: tempDir });
+
+      expect(result).toContain("nested.ts");
+      expect(result).toContain("file_count: 3");
+    });
+
+    it("respects non-recursive patterns", async () => {
+      const result = await executeGlob({ pattern: "*.ts", path: tempDir });
+
+      expect(result).not.toContain("nested.ts");
+      expect(result).toContain("file_count: 2");
+    });
+  });
+
+  describe("metadata in response", () => {
+    it("includes all search parameters", async () => {
+      const result = await executeGlob({
+        pattern: "**/*",
+        path: tempDir,
+        respect_git_ignore: false,
+      });
+
+      expect(result).toContain('pattern: "**/*"');
+      expect(result).toContain("respect_git_ignore: false");
+      expect(result).toContain("truncated: false");
+    });
+  });
+
+  describe("ignore behavior", () => {
+    it("respects .ignore and .fdignore patterns", async () => {
+      const isolatedDir = mkdtempSync(join(tmpdir(), "glob-ignore-"));
+      try {
+        writeFileSync(join(isolatedDir, ".ignore"), "skip.ignore.txt\n");
+        writeFileSync(join(isolatedDir, ".fdignore"), "skip.fd.txt\n");
+        writeFileSync(join(isolatedDir, "keep.txt"), "keep");
+        writeFileSync(join(isolatedDir, "skip.ignore.txt"), "ignored");
+        writeFileSync(join(isolatedDir, "skip.fd.txt"), "ignored");
+
+        const result = await executeGlob({
+          pattern: "**/*.txt",
+          path: isolatedDir,
+        });
+
+        expect(result).toContain("file_count: 1");
+        expect(result).toContain("keep.txt");
+        expect(result).not.toContain("skip.ignore.txt");
+        expect(result).not.toContain("skip.fd.txt");
+      } finally {
+        if (existsSync(isolatedDir)) {
+          rmSync(isolatedDir, { recursive: true });
+        }
+      }
+    });
+
+    it("can bypass ignore rules when respect_git_ignore is false", async () => {
+      const isolatedDir = mkdtempSync(join(tmpdir(), "glob-ignore-off-"));
+      try {
+        writeFileSync(join(isolatedDir, ".ignore"), "skip.ignore.txt\n");
+        writeFileSync(join(isolatedDir, ".fdignore"), "skip.fd.txt\n");
+        writeFileSync(join(isolatedDir, "keep.txt"), "keep");
+        writeFileSync(join(isolatedDir, "skip.ignore.txt"), "ignored");
+        writeFileSync(join(isolatedDir, "skip.fd.txt"), "ignored");
+
+        const result = await executeGlob({
+          pattern: "**/*.txt",
+          path: isolatedDir,
+          respect_git_ignore: false,
+        });
+
+        expect(result).toContain("file_count: 3");
+        expect(result).toContain("keep.txt");
+        expect(result).toContain("skip.ignore.txt");
+        expect(result).toContain("skip.fd.txt");
+      } finally {
+        if (existsSync(isolatedDir)) {
+          rmSync(isolatedDir, { recursive: true });
+        }
+      }
+    });
+
+    it("applies parent .gitignore when searching from subdirectory", async () => {
+      const repoDir = mkdtempSync(join(tmpdir(), "glob-parent-gitignore-"));
+      const workspaceDir = join(repoDir, "workspace");
+      try {
+        mkdirSync(join(repoDir, ".git"));
+        mkdirSync(workspaceDir);
+        writeFileSync(join(repoDir, ".gitignore"), "/workspace/ignored.ts\n");
+        writeFileSync(join(workspaceDir, "ignored.ts"), "ignored");
+        writeFileSync(join(workspaceDir, "kept.ts"), "kept");
+
+        const result = await executeGlob({
+          pattern: "**/*.ts",
+          path: workspaceDir,
+        });
+
+        expect(result).toContain("file_count: 1");
+        expect(result).toContain("kept.ts");
+        expect(result).not.toContain("ignored.ts");
+      } finally {
+        if (existsSync(repoDir)) {
+          rmSync(repoDir, { recursive: true });
+        }
+      }
+    });
+
+    it("applies slashless nested .gitignore patterns to descendants", async () => {
+      const repoDir = mkdtempSync(join(tmpdir(), "glob-nested-gitignore-"));
+      const srcDir = join(repoDir, "src");
+      const nestedDir = join(srcDir, "nested");
+      try {
+        mkdirSync(join(repoDir, ".git"));
+        mkdirSync(srcDir);
+        mkdirSync(nestedDir);
+        writeFileSync(join(srcDir, ".gitignore"), "ignored.ts\n");
+        writeFileSync(join(srcDir, "ignored.ts"), "ignored");
+        writeFileSync(join(nestedDir, "ignored.ts"), "ignored");
+        writeFileSync(join(nestedDir, "kept.ts"), "kept");
+
+        const result = await executeGlob({
+          pattern: "**/*.ts",
+          path: repoDir,
+        });
+
+        expect(result).toContain("file_count: 1");
+        expect(result).toContain("kept.ts");
+        expect(result).not.toContain("ignored.ts");
+      } finally {
+        if (existsSync(repoDir)) {
+          rmSync(repoDir, { recursive: true });
+        }
+      }
+    });
+  });
+});