@aaroncql/pim-agent 0.0.1

package/src/extensions/grep/grep.ts

@@ -0,0 +1,215 @@
+import { FileScanner, type FileScanOptions } from "../../shared/FileScanner";
+import { FsErrors } from "../../shared/FsErrors";
+import { Lines } from "../../shared/Lines";
+
+const MATCH_CONCURRENCY = 32;
+
+export type GrepLine = {
+  readonly lineNumber: number;
+  readonly text: string;
+};
+
+export type GrepLineRange = {
+  readonly startLineNumber: number;
+  readonly endLineNumber: number;
+};
+
+export type GrepMatch = {
+  readonly filePath: string;
+  readonly mtime: number;
+  readonly lines: readonly GrepLine[];
+  readonly ranges: readonly GrepLineRange[];
+  readonly fileLines: readonly string[];
+};
+
+export type GrepMatcher = {
+  readonly regex: RegExp;
+  readonly matchAcrossLines: boolean;
+};
+
+export type GrepScanOptions = FileScanOptions;
+
+export function buildMatcher(options: {
+  readonly pattern: string;
+  readonly caseInsensitive: boolean;
+  readonly matchAcrossLines: boolean;
+}): GrepMatcher {
+  const flags = `${options.matchAcrossLines ? "s" : ""}${
+    options.caseInsensitive ? "i" : ""
+  }`;
+
+  try {
+    return {
+      regex: new RegExp(options.pattern, flags),
+      matchAcrossLines: options.matchAcrossLines,
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Invalid regular expression /${options.pattern}/${flags}: ${message}. Escape regex metacharacters for a literal search or simplify the pattern.`
+    );
+  }
+}
+
+export async function findMatches(
+  path: string,
+  glob: string | undefined,
+  matcher: GrepMatcher,
+  options: GrepScanOptions
+): Promise<readonly GrepMatch[]> {
+  const metadata = await FsErrors.statOrThrow(path);
+  const files = metadata.isFile()
+    ? [path]
+    : (await FileScanner.scan(path, glob ?? "**/*", options)).toSorted(
+        comparePaths
+      );
+  const results: GrepMatch[] = [];
+
+  for (let index = 0; index < files.length; index += MATCH_CONCURRENCY) {
+    const chunk = files.slice(index, index + MATCH_CONCURRENCY);
+    const chunkResults = await Promise.all(
+      chunk.map((filePath) => matchFile(filePath, matcher))
+    );
+
+    for (const match of chunkResults) {
+      if (match !== undefined) {
+        results.push(match);
+      }
+    }
+  }
+
+  return results;
+}
+
+async function matchFile(
+  filePath: string,
+  matcher: GrepMatcher
+): Promise<GrepMatch | undefined> {
+  const file = Bun.file(filePath);
+
+  if (await Lines.isBinary(file)) {
+    return undefined;
+  }
+
+  const content = Lines.normalize(await file.text());
+  const fileLines = Lines.split(content);
+  const ranges = matcher.matchAcrossLines
+    ? regexRanges(content, matcher.regex)
+    : matchLineByLine(fileLines, matcher.regex);
+
+  if (ranges.length === 0) {
+    return undefined;
+  }
+
+  return {
+    filePath,
+    mtime: file.lastModified,
+    lines: linesForRanges(fileLines, ranges),
+    ranges,
+    fileLines,
+  };
+}
+
+function matchLineByLine(
+  lines: readonly string[],
+  regex: RegExp
+): readonly GrepLineRange[] {
+  const ranges: GrepLineRange[] = [];
+
+  for (const [index, line] of lines.entries()) {
+    if (regex.test(line)) {
+      const lineNumber = index + 1;
+      ranges.push({ startLineNumber: lineNumber, endLineNumber: lineNumber });
+    }
+  }
+
+  return ranges;
+}
+
+function regexRanges(content: string, regex: RegExp): readonly GrepLineRange[] {
+  const globalRegex = new RegExp(regex.source, addFlag(regex.flags, "g"));
+  const ranges: GrepLineRange[] = [];
+
+  while (true) {
+    const match = globalRegex.exec(content);
+
+    if (match === null) {
+      break;
+    }
+
+    ranges.push(
+      lineRangeForOffsets(content, match.index, match.index + match[0].length)
+    );
+
+    if (match[0].length === 0) {
+      globalRegex.lastIndex += 1;
+    }
+  }
+
+  return ranges;
+}
+
+function addFlag(flags: string, flag: string): string {
+  return flags.includes(flag) ? flags : `${flags}${flag}`;
+}
+
+function lineRangeForOffsets(
+  content: string,
+  startOffset: number,
+  endOffset: number
+): GrepLineRange {
+  return {
+    startLineNumber: lineNumberForOffset(content, startOffset),
+    endLineNumber: lineNumberForOffset(
+      content,
+      Math.max(startOffset, endOffset - 1)
+    ),
+  };
+}
+
+function lineNumberForOffset(content: string, offset: number): number {
+  let lineNumber = 1;
+
+  for (let index = 0; index < offset && index < content.length; index += 1) {
+    if (content[index] === "\n") {
+      lineNumber += 1;
+    }
+  }
+
+  return lineNumber;
+}
+
+function linesForRanges(
+  fileLines: readonly string[],
+  ranges: readonly GrepLineRange[]
+): readonly GrepLine[] {
+  const seen = new Set<number>();
+  const lines: GrepLine[] = [];
+
+  for (const range of ranges) {
+    for (
+      let lineNumber = range.startLineNumber;
+      lineNumber <= range.endLineNumber;
+      lineNumber += 1
+    ) {
+      if (seen.has(lineNumber)) {
+        continue;
+      }
+
+      seen.add(lineNumber);
+      lines.push({ lineNumber, text: fileLines[lineNumber - 1] ?? "" });
+    }
+  }
+
+  return lines;
+}
+
+function comparePaths(left: string, right: string): number {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}

package/src/extensions/grep/index.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from "bun:test";
+import type {
+  AgentToolResult,
+  ExtensionAPI,
+  Theme,
+  ToolDefinition,
+} from "@earendil-works/pi-coding-agent";
+import registerGrep from "./index";
+
+const stubTheme = {
+  bold: (text: string) => text,
+  fg: (_color: string, text: string) => text,
+} as unknown as Theme;
+
+function registeredTool(): ToolDefinition {
+  let tool: ToolDefinition | undefined;
+  registerGrep({
+    registerTool(def: ToolDefinition): void {
+      tool = def;
+    },
+  } as unknown as ExtensionAPI);
+
+  if (tool === undefined) {
+    throw new Error("grep tool was not registered");
+  }
+  return tool;
+}
+
+describe("grep tool renderer", () => {
+  test("updates the visible call title with the file count when the result renders", () => {
+    const tool = registeredTool();
+    const args = { pattern: "alpha" };
+    const state = {};
+    const callContext = {
+      args,
+      toolCallId: "grep-1",
+      invalidate: () => {},
+      lastComponent: undefined,
+      state,
+      cwd: "/repo",
+      executionStarted: true,
+      argsComplete: true,
+      isPartial: false,
+      expanded: false,
+      showImages: true,
+      isError: false,
+    };
+    const callComponent = tool.renderCall!(args, stubTheme, callContext);
+
+    expect(callComponent.render(120).join("\n")).not.toContain("(2 files)");
+
+    const result: AgentToolResult<unknown> = {
+      content: [{ type: "text", text: "src/a.ts\nsrc/b.ts" }],
+      details: { fileCount: 2 },
+    };
+    tool.renderResult!(
+      result,
+      { expanded: false, isPartial: false },
+      stubTheme,
+      {
+        ...callContext,
+        lastComponent: undefined,
+      }
+    );
+
+    expect(callComponent.render(120).join("\n")).toContain("(2 files)");
+  });
+});

package/src/extensions/grep/index.ts

@@ -0,0 +1,158 @@
+import type { ExtensionAPI, Theme } from "@earendil-works/pi-coding-agent";
+import { Paths } from "../../shared/Paths";
+import {
+  Renderer,
+  type StatefulToolCallTitleContext,
+  type StatefulToolCallTitleState,
+} from "../../shared/Renderer";
+import { Tools } from "../../shared/Tools";
+import { buildMatcher, findMatches } from "./grep";
+import { formatTitle, renderMatches } from "./render";
+import {
+  GREP_HEAD_LIMIT_MAX,
+  type GrepInput,
+  type GrepOutputMode,
+  type GrepPathFormat,
+  grepSchema,
+} from "./schema";
+
+const PREVIEW_LINES = 10;
+const DEFAULT_OUTPUT_MODE: GrepOutputMode = "files_with_matches";
+const DEFAULT_PATH_FORMAT: GrepPathFormat = "relative";
+
+type GrepCallState = StatefulToolCallTitleState & {
+  fileCount?: number;
+};
+
+type GrepRenderContext = StatefulToolCallTitleContext & {
+  readonly args?: GrepInput;
+  readonly cwd: string;
+};
+
+function renderTitle(
+  input: Partial<GrepInput>,
+  theme: Theme,
+  context: GrepRenderContext
+) {
+  const state = context.state as GrepCallState;
+  const title = formatTitle({
+    pattern: input.pattern,
+    path: input.path,
+    glob: input.glob,
+    cwd: context.cwd,
+    fileCount: state.fileCount,
+  });
+  return Renderer.renderStatefulToolCallTitle({
+    label: "Grep",
+    title,
+    theme,
+    context,
+  });
+}
+
+export default function (pi: ExtensionAPI): void {
+  Tools.register(pi, {
+    name: "grep",
+    label: "grep",
+    description:
+      "Search UTF-8 text files with a JavaScript regex. Directory scans skip binary files, gitignored paths, and dotfiles unless requested; direct file paths are always searched. Use grep to search file contents instead of bash with grep, rg, ag, find -exec, or similar.",
+    parameters: grepSchema,
+    renderShell: "self",
+    executionMode: "parallel",
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const {
+        pattern,
+        path,
+        glob,
+        exclude,
+        outputMode,
+        matchAcrossLines,
+        context,
+        includeDotfiles,
+        includeIgnored,
+        pathFormat,
+        caseInsensitive,
+        headLimit,
+      } = params as GrepInput;
+
+      if (signal?.aborted) {
+        throw new Error("Grep aborted before execution.");
+      }
+
+      const resolvedPathFormat = pathFormat ?? DEFAULT_PATH_FORMAT;
+      const resolvedContext = context ?? 0;
+      const resolvedOutputMode = outputMode ?? DEFAULT_OUTPUT_MODE;
+      const limit = Math.min(
+        headLimit ?? GREP_HEAD_LIMIT_MAX,
+        GREP_HEAD_LIMIT_MAX
+      );
+      const matcher = buildMatcher({
+        pattern,
+        caseInsensitive: caseInsensitive ?? false,
+        matchAcrossLines: matchAcrossLines ?? false,
+      });
+      const absolutePath = Paths.resolve(path ?? ".", ctx.cwd);
+      const matches = await findMatches(absolutePath, glob, matcher, {
+        exclude,
+        includeDotfiles: includeDotfiles ?? false,
+        includeIgnored: includeIgnored ?? false,
+      });
+      const outcome = renderMatches(matches, resolvedOutputMode, limit, {
+        cwd: ctx.cwd,
+        pathFormat: resolvedPathFormat,
+        context: resolvedContext,
+      });
+      const content: Array<{ type: "text"; text: string }> = [
+        { type: "text", text: outcome.body },
+      ];
+
+      if (outcome.truncated) {
+        content.push({
+          type: "text",
+          text: `[grep tool: showing ${outcome.visibleItems} of ${outcome.totalItems} ${outcome.itemNoun}; narrow the pattern, scope to a specific path, or use a glob filter to reduce results.]`,
+        });
+      }
+
+      return {
+        content,
+        details: {
+          absolutePath,
+          outputMode: resolvedOutputMode,
+          exclude,
+          matchAcrossLines: matchAcrossLines ?? false,
+          context: resolvedContext,
+          includeDotfiles: includeDotfiles ?? false,
+          includeIgnored: includeIgnored ?? false,
+          pathFormat: resolvedPathFormat,
+          fileCount: outcome.fileCount,
+          totalMatches: outcome.totalMatches,
+          totalItems: outcome.totalItems,
+          visibleItems: outcome.visibleItems,
+          truncated: outcome.truncated,
+        },
+      };
+    },
+    renderCall(args, theme, context) {
+      return renderTitle((args ?? {}) as Partial<GrepInput>, theme, context);
+    },
+    renderResult(result, options, theme, context) {
+      const state = context.state as GrepCallState;
+      const details = result.details as
+        | { readonly fileCount?: number }
+        | undefined;
+
+      if (details?.fileCount !== undefined) {
+        state.fileCount = details.fileCount;
+        renderTitle(context.args ?? {}, theme, context);
+      }
+
+      return Renderer.renderBorderedResult({
+        result,
+        options,
+        theme,
+        context,
+        previewLines: PREVIEW_LINES,
+      });
+    },
+  });
+}

package/src/extensions/grep/render.test.ts

@@ -0,0 +1,269 @@
+import { describe, expect, test } from "bun:test";
+import { OutputBudget } from "../../shared/OutputBudget";
+import type { GrepMatch } from "./grep";
+import { formatTitle, renderMatches } from "./render";
+
+const fixture: readonly GrepMatch[] = [
+  {
+    filePath: "/repo/older.ts",
+    mtime: 1_000,
+    fileLines: ["alpha"],
+    ranges: [{ startLineNumber: 1, endLineNumber: 1 }],
+    lines: [{ lineNumber: 1, text: "alpha" }],
+  },
+  {
+    filePath: "/repo/newer.ts",
+    mtime: 2_000,
+    fileLines: ["intro", "alpha", "middle", "tail", "alphabet"],
+    ranges: [
+      { startLineNumber: 2, endLineNumber: 2 },
+      { startLineNumber: 5, endLineNumber: 5 },
+    ],
+    lines: [
+      { lineNumber: 2, text: "alpha" },
+      { lineNumber: 5, text: "alphabet" },
+    ],
+  },
+];
+
+const relativeOptions = {
+  cwd: "/repo",
+  pathFormat: "relative",
+  context: 0,
+} as const;
+
+const absoluteOptions = {
+  cwd: "/repo",
+  pathFormat: "absolute",
+  context: 0,
+} as const;
+
+describe("renderMatches", () => {
+  test("files_with_matches sorts by recency desc and renders relative paths", () => {
+    const outcome = renderMatches(
+      fixture,
+      "files_with_matches",
+      1000,
+      relativeOptions
+    );
+    expect(outcome.body).toBe("newer.ts\nolder.ts");
+    expect(outcome.fileCount).toBe(2);
+    expect(outcome.totalMatches).toBe(3);
+    expect(outcome.totalItems).toBe(2);
+    expect(outcome.truncated).toBe(false);
+  });
+
+  test("can render absolute paths", () => {
+    const outcome = renderMatches(
+      fixture,
+      "files_with_matches",
+      1000,
+      absoluteOptions
+    );
+    expect(outcome.body).toBe("/repo/newer.ts\n/repo/older.ts");
+  });
+
+  test("content emits path:line:text lines without markers when context is omitted", () => {
+    const outcome = renderMatches(fixture, "content", 1000, relativeOptions);
+    expect(outcome.body).toBe(
+      ["newer.ts:2:alpha", "newer.ts:5:alphabet", "older.ts:1:alpha"].join("\n")
+    );
+    expect(outcome.totalItems).toBe(3);
+  });
+
+  test("content can include context lines and distinguish matches", () => {
+    const outcome = renderMatches(fixture, "content", 1000, {
+      ...relativeOptions,
+      context: 1,
+    });
+    expect(outcome.body).toBe(
+      [
+        "  newer.ts:1:intro",
+        "> newer.ts:2:alpha",
+        "  newer.ts:3:middle",
+        "  newer.ts:4:tail",
+        "> newer.ts:5:alphabet",
+        "> older.ts:1:alpha",
+      ].join("\n")
+    );
+  });
+
+  test("content inserts separators between non-overlapping context blocks", () => {
+    const outcome = renderMatches(
+      [
+        {
+          filePath: "/repo/gapped.ts",
+          mtime: 3_000,
+          fileLines: ["1", "2", "hit", "4", "5", "6", "hit", "8", "9"],
+          ranges: [
+            { startLineNumber: 3, endLineNumber: 3 },
+            { startLineNumber: 7, endLineNumber: 7 },
+          ],
+          lines: [
+            { lineNumber: 3, text: "hit" },
+            { lineNumber: 7, text: "hit" },
+          ],
+        },
+      ],
+      "content",
+      1000,
+      { ...relativeOptions, context: 1 }
+    );
+
+    expect(outcome.body).toBe(
+      [
+        "  gapped.ts:2:2",
+        "> gapped.ts:3:hit",
+        "  gapped.ts:4:4",
+        "--",
+        "  gapped.ts:6:6",
+        "> gapped.ts:7:hit",
+        "  gapped.ts:8:8",
+      ].join("\n")
+    );
+  });
+
+  test("count sorts by match count desc, then mtime desc, then path asc", () => {
+    const outcome = renderMatches(fixture, "count", 1000, relativeOptions);
+    expect(outcome.body).toBe("newer.ts:2\nolder.ts:1");
+  });
+
+  test("flags truncation when results exceed headLimit", () => {
+    const outcome = renderMatches(fixture, "content", 2, relativeOptions);
+    expect(outcome.body).toBe("newer.ts:2:alpha\nnewer.ts:5:alphabet");
+    expect(outcome.truncated).toBe(true);
+    expect(outcome.visibleItems).toBe(2);
+    expect(outcome.totalItems).toBe(3);
+  });
+
+  test("returns a no-match outcome when there are no results", () => {
+    const outcome = renderMatches([], "content", 1000, relativeOptions);
+    expect(outcome.body).toBe("No matches.");
+    expect(outcome.truncated).toBe(false);
+    expect(outcome.fileCount).toBe(0);
+    expect(outcome.totalMatches).toBe(0);
+  });
+
+  test("truncates matched lines from minified files so a single hit cannot blow up the body", () => {
+    const minified = "a".repeat(50_000);
+    const outcome = renderMatches(
+      [
+        {
+          filePath: "/repo/dist/bundle.js",
+          mtime: 1_000,
+          fileLines: [minified],
+          ranges: [{ startLineNumber: 1, endLineNumber: 1 }],
+          lines: [{ lineNumber: 1, text: minified }],
+        },
+      ],
+      "content",
+      1000,
+      relativeOptions
+    );
+
+    expect(outcome.body).toContain(
+      `(line truncated to ${OutputBudget.maxLineLength} chars)`
+    );
+    expect(Buffer.byteLength(outcome.body, "utf8")).toBeLessThanOrEqual(
+      OutputBudget.maxBytes
+    );
+  });
+
+  test("byte cap drops trailing rendered lines when many matches each push toward the cap", () => {
+    const longText = "x".repeat(OutputBudget.maxLineLength);
+    const fileLines = Array.from({ length: 40 }, () => longText);
+    const ranges = fileLines.map((_, index) => ({
+      startLineNumber: index + 1,
+      endLineNumber: index + 1,
+    }));
+    const lines = fileLines.map((text, index) => ({
+      lineNumber: index + 1,
+      text,
+    }));
+
+    const outcome = renderMatches(
+      [
+        {
+          filePath: "/repo/big.txt",
+          mtime: 1_000,
+          fileLines,
+          ranges,
+          lines,
+        },
+      ],
+      "content",
+      1000,
+      relativeOptions
+    );
+
+    expect(outcome.truncated).toBe(true);
+    expect(outcome.visibleItems).toBeLessThan(outcome.totalItems);
+    expect(Buffer.byteLength(outcome.body, "utf8")).toBeLessThanOrEqual(
+      OutputBudget.maxBytes
+    );
+  });
+});
+
+describe("formatTitle", () => {
+  test("uses relative path under cwd and includes glob", () => {
+    const title = formatTitle({
+      pattern: "alpha",
+      path: "/repo/src",
+      glob: "**/*.ts",
+      cwd: "/repo",
+    });
+    expect(title).toBe("/alpha/ in src **/*.ts");
+  });
+
+  test("formats regex patterns with slashes", () => {
+    const title = formatTitle({
+      pattern: "^alpha$",
+      path: "/repo/src",
+      glob: undefined,
+      cwd: "/repo",
+    });
+    expect(title).toBe("/^alpha$/ in src");
+  });
+
+  test("falls back to '.' when path is omitted", () => {
+    const title = formatTitle({
+      pattern: "alpha",
+      path: undefined,
+      glob: undefined,
+      cwd: "/repo",
+    });
+    expect(title).toBe("/alpha/ in .");
+  });
+
+  test("resolves relative paths in titles", () => {
+    const title = formatTitle({
+      pattern: "alpha",
+      path: "src",
+      glob: undefined,
+      cwd: "/repo",
+    });
+    expect(title).toBe("/alpha/ in src");
+  });
+
+  test("appends pluralized file count when provided", () => {
+    const title = formatTitle({
+      pattern: "alpha",
+      path: "/repo/src",
+      glob: "**/*.ts",
+      cwd: "/repo",
+      fileCount: 3,
+    });
+    expect(title).toBe("/alpha/ in src **/*.ts (3 files)");
+  });
+
+  test("uses singular noun for a single file", () => {
+    const title = formatTitle({
+      pattern: "alpha",
+      path: undefined,
+      glob: undefined,
+      cwd: "/repo",
+      fileCount: 1,
+    });
+    expect(title).toBe("/alpha/ in . (1 file)");
+  });
+});