plugsuits 1.0.0

package/src/tools/explore/glob.ts

@@ -0,0 +1,137 @@
+import { stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { formatBlock, getIgnoreFilter } from "../utils/safety-utils";
+import GLOB_FILES_DESCRIPTION from "./glob-files.txt";
+
+const MAX_RESULTS = 500;
+const STAT_CONCURRENCY = 32;
+
+interface FileWithMtime {
+  mtime: Date;
+  path: string;
+}
+
+function insertTopByMtime(list: FileWithMtime[], item: FileWithMtime): void {
+  let insertAt = list.length;
+  for (let i = 0; i < list.length; i++) {
+    if (item.mtime.getTime() > list[i].mtime.getTime()) {
+      insertAt = i;
+      break;
+    }
+  }
+
+  list.splice(insertAt, 0, item);
+  if (list.length > MAX_RESULTS) {
+    list.pop();
+  }
+}
+
+const inputSchema = z.object({
+  pattern: z.string().describe("Glob pattern (e.g., '**/*.py', 'docs/*.md')"),
+  path: z
+    .string()
+    .optional()
+    .describe("Directory to search (default: current directory)"),
+  respect_git_ignore: z
+    .boolean()
+    .optional()
+    .default(true)
+    .describe(
+      "Respect ignore rules from .gitignore/.ignore/.fdignore (default: true)"
+    ),
+});
+
+export type GlobInput = z.input<typeof inputSchema>;
+
+export async function executeGlob({
+  pattern,
+  path,
+  respect_git_ignore = true,
+}: GlobInput): Promise<string> {
+  const searchDir = path ? resolve(path) : process.cwd();
+
+  const glob = new Bun.Glob(pattern);
+  const topFilesByMtime: FileWithMtime[] = [];
+  let totalMatches = 0;
+  let skippedUnreadable = 0;
+
+  const ignoreFilter = respect_git_ignore
+    ? await getIgnoreFilter(searchDir)
+    : null;
+
+  const pending = new Set<Promise<void>>();
+
+  const enqueueStat = (absolutePath: string): void => {
+    const task = stat(absolutePath)
+      .then((stats) => {
+        totalMatches += 1;
+        insertTopByMtime(topFilesByMtime, {
+          path: absolutePath,
+          mtime: stats.mtime,
+        });
+      })
+      .catch(() => {
+        skippedUnreadable += 1;
+      })
+      .finally(() => {
+        pending.delete(task);
+      });
+
+    pending.add(task);
+  };
+
+  for await (const file of glob.scan({
+    cwd: searchDir,
+    absolute: false,
+    onlyFiles: true,
+  })) {
+    if (ignoreFilter?.ignores(file)) {
+      continue;
+    }
+
+    const absolutePath = join(searchDir, file);
+    enqueueStat(absolutePath);
+
+    if (pending.size >= STAT_CONCURRENCY) {
+      await Promise.race(pending);
+    }
+  }
+
+  await Promise.all(pending);
+
+  const truncated = totalMatches > MAX_RESULTS;
+  const displayFiles = topFilesByMtime;
+
+  const output = [
+    totalMatches > 0 ? "OK - glob" : "OK - glob (no matches)",
+    `pattern: "${pattern}"`,
+    `path: ${path ?? "."}`,
+    `respect_git_ignore: ${respect_git_ignore}`,
+    `file_count: ${totalMatches}`,
+    `truncated: ${truncated}`,
+    `skipped_unreadable: ${skippedUnreadable}`,
+    "sorted_by: mtime desc",
+    "",
+  ];
+
+  if (displayFiles.length > 0) {
+    const body = displayFiles
+      .map((f) => {
+        return f.path;
+      })
+      .join("\n");
+    output.push(formatBlock("glob results", body));
+  } else {
+    output.push(formatBlock("glob results", "(no matches)"));
+  }
+
+  return output.join("\n");
+}
+
+export const globTool = tool({
+  description: GLOB_FILES_DESCRIPTION,
+  inputSchema,
+  execute: executeGlob,
+});

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

@@ -0,0 +1,12 @@
+### grep_files
+**Purpose**: Search file contents by regex or literal pattern
+
+**When to use**:
+- Finding function/variable usages
+- Locating specific code patterns and messages
+
+**Output format**:
+- Match lines are emitted as `path:{line_number}#{hash_id}|content`
+- The `{line_number}#{hash_id}` anchor is directly compatible with `edit_file` hashline refs
+
+**DO NOT use shell**: Prefer this over `grep`, `rg`, `ag`

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

@@ -0,0 +1,183 @@
+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 { computeLineHash } from "../utils/hashline";
+import { executeGrep } from "./grep";
+
+const HASHLINE_ALPHABET = "[ZPMQVRWSNKTXJBYH]{2}";
+
+describe("executeGrep", () => {
+  let tempDir: string;
+
+  beforeAll(() => {
+    tempDir = mkdtempSync(join(tmpdir(), "grep-test-"));
+    writeFileSync(join(tempDir, "file1.ts"), "const foo = 1;\nconst bar = 2;");
+    writeFileSync(
+      join(tempDir, "file2.ts"),
+      "function foo() {}\nfunction baz() {}"
+    );
+    mkdirSync(join(tempDir, "sub"));
+    writeFileSync(
+      join(tempDir, "sub", "nested.ts"),
+      "export const foo = 'nested';"
+    );
+  });
+
+  afterAll(() => {
+    if (existsSync(tempDir)) {
+      rmSync(tempDir, { recursive: true });
+    }
+  });
+
+  describe("basic search", () => {
+    it("returns structured response with matches", async () => {
+      const result = await executeGrep({ pattern: "foo", path: tempDir });
+
+      expect(result).toContain("OK - grep");
+      expect(result).toContain('pattern: "foo"');
+      expect(result).toContain("match_count:");
+      expect(result).toContain("truncated: false");
+      expect(result).toContain("======== grep results ========");
+      expect(result).toContain("foo");
+      expect(result).toMatch(
+        new RegExp(`file1\\.ts[:\\-]1#${HASHLINE_ALPHABET}\\|const foo = 1;`)
+      );
+      expect(result).toContain("======== end ========");
+    });
+
+    it("emits grep lines with line hash markers", async () => {
+      const result = await executeGrep({ pattern: "foo", path: tempDir });
+      const lineHash = computeLineHash(1, "const foo = 1;");
+
+      expect(result).toContain(`:1#${lineHash}|const foo = 1;`);
+      expect(result).toContain("file1.ts");
+      expect(result).toContain(":1#");
+      expect(result).not.toContain("file1.ts:1:const foo = 1;");
+    });
+
+    it("shows match count correctly", async () => {
+      const result = await executeGrep({ pattern: "foo", path: tempDir });
+
+      expect(result).toContain("match_count: 3");
+    });
+
+    it("returns no matches message when nothing found", async () => {
+      const result = await executeGrep({
+        pattern: "nonexistent_xyz_123",
+        path: tempDir,
+      });
+
+      expect(result).toContain("OK - grep (no matches)");
+      expect(result).toContain("match_count: 0");
+      expect(result).toContain("(no matches)");
+    });
+  });
+
+  describe("search options", () => {
+    it("respects include filter", async () => {
+      const result = await executeGrep({
+        pattern: "foo",
+        path: tempDir,
+        include: "file1.ts",
+      });
+
+      expect(result).toContain("file1.ts");
+      expect(result).not.toContain("file2.ts");
+    });
+
+    it("respects case_sensitive option", async () => {
+      writeFileSync(join(tempDir, "case.txt"), "FOO\nfoo\nFoo");
+
+      const sensitive = await executeGrep({
+        pattern: "foo",
+        path: tempDir,
+        include: "case.txt",
+        case_sensitive: true,
+      });
+
+      expect(sensitive).toContain("match_count: 1");
+
+      const insensitive = await executeGrep({
+        pattern: "foo",
+        path: tempDir,
+        include: "case.txt",
+        case_sensitive: false,
+      });
+
+      expect(insensitive).toContain("match_count: 3");
+    });
+
+    it("respects fixed_strings option", async () => {
+      writeFileSync(join(tempDir, "regex.txt"), "a.b\na-b\naxb");
+
+      const regex = await executeGrep({
+        pattern: "a.b",
+        path: tempDir,
+        include: "regex.txt",
+        fixed_strings: false,
+      });
+
+      expect(regex).toContain("match_count: 3");
+
+      const fixed = await executeGrep({
+        pattern: "a.b",
+        path: tempDir,
+        include: "regex.txt",
+        fixed_strings: true,
+      });
+
+      expect(fixed).toContain("match_count: 1");
+    });
+
+    it("formats context lines with hashline markers", async () => {
+      writeFileSync(
+        join(tempDir, "context.ts"),
+        "before line\nneedle target\nafter line"
+      );
+
+      const result = await executeGrep({
+        pattern: "needle",
+        path: tempDir,
+        include: "context.ts",
+        before: 1,
+        after: 1,
+      });
+
+      expect(result).toContain(
+        `:1#${computeLineHash(1, "before line")}|before line`
+      );
+      expect(result).toContain(
+        `:2#${computeLineHash(2, "needle target")}|needle target`
+      );
+      expect(result).toContain(
+        `:3#${computeLineHash(3, "after line")}|after line`
+      );
+      expect(result).not.toContain("context.ts-1-before line");
+      expect(result).not.toContain("context.ts:2:needle target");
+    });
+  });
+
+  describe("metadata in response", () => {
+    it("includes all search parameters", async () => {
+      const result = await executeGrep({
+        pattern: "test",
+        path: tempDir,
+        include: "*.ts",
+        case_sensitive: true,
+        fixed_strings: true,
+      });
+
+      expect(result).toContain('pattern: "test"');
+      expect(result).toContain("include: *.ts");
+      expect(result).toContain("case_sensitive: true");
+      expect(result).toContain("fixed_strings: true");
+    });
+  });
+});

package/src/tools/explore/grep.ts

@@ -0,0 +1,266 @@
+import { spawn } from "node:child_process";
+import { existsSync, statSync } from "node:fs";
+import { dirname, resolve } from "node:path";
+import { tool } from "ai";
+import { z } from "zod";
+import { ensureTool } from "../../utils/tools-manager";
+import { formatLineTag } from "../utils/hashline";
+import { formatBlock } from "../utils/safety-utils";
+import GREP_FILES_DESCRIPTION from "./grep-files.txt";
+
+const MAX_MATCHES = 20_000;
+/** Maximum bytes to buffer from ripgrep stdout before killing the process. */
+const MAX_STDOUT_BUFFER_BYTES = 10 * 1024 * 1024; // 10 MB
+/** Maximum bytes to buffer from ripgrep stderr. */
+const MAX_STDERR_BUFFER_BYTES = 64 * 1024; // 64 KB
+interface GrepResult {
+  matchCount: number;
+  matches: string;
+  truncated: boolean;
+}
+
+const RG_RESULT_LINE_PATTERN = /^(.*?)[:-](\d+)[:-](.*)$/;
+
+function formatHashlineCompatibleMatches(rawMatches: string): string {
+  if (!rawMatches) {
+    return rawMatches;
+  }
+
+  return rawMatches
+    .split("\n")
+    .map((line) => {
+      if (line.length === 0 || line === "--") {
+        return line;
+      }
+
+      const matched = line.match(RG_RESULT_LINE_PATTERN);
+      if (!matched) {
+        return line;
+      }
+
+      const [, filePath, lineNumberText, content] = matched;
+      const lineNumber = Number.parseInt(lineNumberText, 10);
+      if (!Number.isFinite(lineNumber) || lineNumber < 1) {
+        return line;
+      }
+
+      const tag = formatLineTag(lineNumber, content);
+      return `${filePath}:${tag}|${content}`;
+    })
+    .join("\n");
+}
+
+async function runRipgrep(args: string[], cwd: string): Promise<GrepResult> {
+  const rgPath = await ensureTool("rg");
+  if (!rgPath) {
+    throw new Error(
+      "ripgrep (rg) is not available. Please install it or check your PATH."
+    );
+  }
+
+  return new Promise((resolvePromise, reject) => {
+    const rg = spawn(rgPath, args, { cwd });
+
+    let stdout = "";
+    let stderr = "";
+    let bufferExceeded = false;
+
+    rg.stdout.on("data", (data: Buffer) => {
+      if (bufferExceeded) {
+        return;
+      }
+      stdout += data.toString();
+      if (Buffer.byteLength(stdout, "utf-8") > MAX_STDOUT_BUFFER_BYTES) {
+        bufferExceeded = true;
+        rg.kill();
+      }
+    });
+
+    rg.stderr.on("data", (data: Buffer) => {
+      if (Buffer.byteLength(stderr, "utf-8") < MAX_STDERR_BUFFER_BYTES) {
+        stderr += data.toString();
+      }
+    });
+
+    rg.on("close", (code) => {
+      if (bufferExceeded || code === 0 || code === 1) {
+        // When buffer was exceeded, truncate the string to a reasonable
+        // prefix before splitting to avoid doubling peak memory.
+        const lastNewline = stdout.lastIndexOf("\n", MAX_STDOUT_BUFFER_BYTES);
+        const raw = bufferExceeded
+          ? stdout.slice(
+              0,
+              lastNewline > 0 ? lastNewline : MAX_STDOUT_BUFFER_BYTES
+            )
+          : stdout;
+        const lines = raw.split("\n").filter((line) => line.length > 0);
+        const truncated = bufferExceeded || lines.length > MAX_MATCHES;
+        const result = truncated
+          ? lines.slice(0, MAX_MATCHES).join("\n")
+          : stdout.trim();
+
+        resolvePromise({
+          matches: result,
+          matchCount: Math.min(lines.length, MAX_MATCHES),
+          truncated,
+        });
+      } else {
+        const errorDetail =
+          stderr ||
+          "Check that regex pattern is valid and you have read permissions.";
+        reject(new Error(`Search failed (exit code ${code}): ${errorDetail}`));
+      }
+    });
+
+    rg.on("error", (err: NodeJS.ErrnoException) => {
+      const code = err.code ?? "UNKNOWN";
+      reject(
+        new Error(
+          `Failed to spawn ripgrep (${code}): ${err.message}. ` +
+            `Path: "${rgPath}", cwd: "${cwd}"`
+        )
+      );
+    });
+  });
+}
+
+const inputSchema = z.object({
+  pattern: z
+    .string()
+    .describe(
+      "Pattern to search (regex by default). " +
+        "Use '\\b' for word boundaries: '\\bfunctionName\\b'"
+    ),
+  path: z
+    .string()
+    .optional()
+    .describe("Directory to search (default: current directory)"),
+  include: z
+    .string()
+    .optional()
+    .describe("Filter files by glob (e.g., '*.ts', 'src/**')"),
+  case_sensitive: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Case-sensitive search (default: false)"),
+  fixed_strings: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Treat pattern as literal string (default: false)"),
+  context: z.number().optional().describe("Lines of context around matches"),
+  before: z.number().optional().describe("Lines before matches"),
+  after: z.number().optional().describe("Lines after matches"),
+  no_ignore: z
+    .boolean()
+    .optional()
+    .default(false)
+    .describe("Search .gitignore files too (default: false)"),
+});
+
+export type GrepInput = z.input<typeof inputSchema>;
+
+/**
+ * Resolve a path to a valid search directory.
+ * If path is a file, returns its parent directory.
+ * If path doesn't exist, throws an error.
+ */
+function resolveSearchDir(path: string | undefined): string {
+  if (!path) {
+    return process.cwd();
+  }
+
+  const resolved = resolve(path);
+
+  if (!existsSync(resolved)) {
+    throw new Error(`Path does not exist: ${resolved}`);
+  }
+
+  const stats = statSync(resolved);
+  if (stats.isFile()) {
+    // If a file path was provided, use its parent directory
+    return dirname(resolved);
+  }
+
+  if (!stats.isDirectory()) {
+    throw new Error(`Path is not a directory: ${resolved}`);
+  }
+
+  return resolved;
+}
+
+export async function executeGrep({
+  pattern,
+  path,
+  include,
+  case_sensitive = false,
+  fixed_strings = false,
+  context,
+  before,
+  after,
+  no_ignore = false,
+}: GrepInput): Promise<string> {
+  const searchDir = resolveSearchDir(path);
+
+  const args: string[] = ["--line-number", "--with-filename", "--color=never"];
+
+  if (!case_sensitive) {
+    args.push("--ignore-case");
+  }
+
+  if (fixed_strings) {
+    args.push("--fixed-strings");
+  }
+
+  if (include) {
+    args.push("--glob", include);
+  }
+
+  if (context !== undefined) {
+    args.push("--context", context.toString());
+  }
+
+  if (before !== undefined) {
+    args.push("--before-context", before.toString());
+  }
+
+  if (after !== undefined) {
+    args.push("--after-context", after.toString());
+  }
+
+  if (no_ignore) {
+    args.push("--no-ignore");
+  }
+
+  args.push("--", pattern, ".");
+
+  const result = await runRipgrep(args, searchDir);
+  const formattedMatches = formatHashlineCompatibleMatches(result.matches);
+
+  const output = [
+    result.matchCount > 0 ? "OK - grep" : "OK - grep (no matches)",
+    `pattern: "${pattern}"`,
+    `path: ${path ?? "."}`,
+    `include: ${include ?? "*"}`,
+    `case_sensitive: ${case_sensitive}`,
+    `fixed_strings: ${fixed_strings}`,
+    `match_count: ${result.matchCount}`,
+    `truncated: ${result.truncated}`,
+    "",
+  ];
+
+  if (result.matchCount > 0) {
+    output.push(formatBlock("grep results", formattedMatches));
+  } else {
+    output.push(formatBlock("grep results", "(no matches)"));
+  }
+
+  return output.join("\n");
+}
+
+export const grepTool = tool({
+  description: GREP_FILES_DESCRIPTION,
+  inputSchema,
+  execute: executeGrep,
+});