@aaroncql/pim-agent 0.0.1

package/src/extensions/grep/render.ts

@@ -0,0 +1,243 @@
+import { OutputBudget } from "../../shared/OutputBudget";
+import { Paths } from "../../shared/Paths";
+import type { GrepLineRange, GrepMatch } from "./grep";
+import type { GrepOutputMode, GrepPathFormat } from "./schema";
+
+export type RenderOutcome = {
+  readonly body: string;
+  readonly totalItems: number;
+  readonly visibleItems: number;
+  readonly truncated: boolean;
+  readonly fileCount: number;
+  readonly totalMatches: number;
+  readonly itemNoun: string;
+};
+
+export type RenderOptions = {
+  readonly cwd: string;
+  readonly pathFormat: GrepPathFormat;
+  readonly context: number;
+};
+
+const renderers: Record<
+  GrepOutputMode,
+  {
+    readonly itemNoun: string;
+    readonly toLines: (
+      matches: readonly GrepMatch[],
+      options: RenderOptions
+    ) => readonly string[];
+  }
+> = {
+  files_with_matches: { itemNoun: "files", toLines: renderFiles },
+  content: { itemNoun: "lines", toLines: renderContent },
+  count: { itemNoun: "files", toLines: renderCounts },
+};
+
+export function renderMatches(
+  matches: readonly GrepMatch[],
+  outputMode: GrepOutputMode,
+  headLimit: number,
+  options: RenderOptions
+): RenderOutcome {
+  const totalMatches = matches.reduce(
+    (sum, match) => sum + matchCount(match),
+    0
+  );
+  const { itemNoun, toLines } = renderers[outputMode];
+  const lines = toLines(matches, options);
+
+  if (lines.length === 0) {
+    return {
+      body: "No matches.",
+      totalItems: 0,
+      visibleItems: 0,
+      truncated: false,
+      fileCount: 0,
+      totalMatches: 0,
+      itemNoun,
+    };
+  }
+
+  const headCapped = lines.slice(0, headLimit);
+  const { visible } = OutputBudget.applyByteCap(headCapped);
+  const truncated = visible.length < lines.length;
+
+  return {
+    body: visible.join("\n"),
+    totalItems: lines.length,
+    visibleItems: visible.length,
+    truncated,
+    fileCount: matches.length,
+    totalMatches,
+    itemNoun,
+  };
+}
+
+export type TitleOptions = {
+  readonly pattern: string | undefined;
+  readonly path: string | undefined;
+  readonly glob: string | undefined;
+  readonly cwd: string;
+  readonly fileCount?: number;
+};
+
+export function formatTitle(options: TitleOptions): string {
+  const pattern = formatPattern(options.pattern);
+  const resolvedPath =
+    options.path === undefined
+      ? undefined
+      : Paths.resolve(options.path, options.cwd);
+  const target = Paths.titleOr(resolvedPath, options.cwd, ".");
+  const glob = options.glob ? ` ${options.glob}` : "";
+  const suffix =
+    options.fileCount === undefined
+      ? ""
+      : ` (${options.fileCount} ${options.fileCount === 1 ? "file" : "files"})`;
+  return `${pattern} in ${target}${glob}${suffix}`;
+}
+
+function formatPattern(pattern: string | undefined): string {
+  return pattern === undefined ? "..." : `/${pattern}/`;
+}
+
+function renderFiles(
+  matches: readonly GrepMatch[],
+  options: RenderOptions
+): readonly string[] {
+  return byRecency(matches).map((match) => formatPath(match.filePath, options));
+}
+
+function renderContent(
+  matches: readonly GrepMatch[],
+  options: RenderOptions
+): readonly string[] {
+  if (options.context > 0) {
+    return byRecency(matches).flatMap((match) =>
+      renderContextContent(match, options)
+    );
+  }
+
+  return byRecency(matches).flatMap((match) =>
+    match.lines.map(
+      (line) =>
+        `${formatPath(match.filePath, options)}:${line.lineNumber}:${OutputBudget.truncateLine(line.text)}`
+    )
+  );
+}
+
+function renderContextContent(
+  match: GrepMatch,
+  options: RenderOptions
+): readonly string[] {
+  const path = formatPath(match.filePath, options);
+  const blocks = contextBlocks(
+    match.ranges,
+    match.fileLines.length,
+    options.context
+  );
+  const lines: string[] = [];
+
+  for (const [blockIndex, block] of blocks.entries()) {
+    if (blockIndex > 0) {
+      lines.push("--");
+    }
+
+    for (
+      let lineNumber = block.startLineNumber;
+      lineNumber <= block.endLineNumber;
+      lineNumber += 1
+    ) {
+      const marker = isMatchLine(match.ranges, lineNumber) ? ">" : " ";
+      const text = OutputBudget.truncateLine(
+        match.fileLines[lineNumber - 1] ?? ""
+      );
+      lines.push(`${marker} ${path}:${lineNumber}:${text}`);
+    }
+  }
+
+  return lines;
+}
+
+function renderCounts(
+  matches: readonly GrepMatch[],
+  options: RenderOptions
+): readonly string[] {
+  return [...matches]
+    .sort(
+      (left, right) =>
+        matchCount(right) - matchCount(left) ||
+        right.mtime - left.mtime ||
+        comparePaths(left.filePath, right.filePath)
+    )
+    .map(
+      (match) => `${formatPath(match.filePath, options)}:${matchCount(match)}`
+    );
+}
+
+function contextBlocks(
+  ranges: readonly GrepLineRange[],
+  lineCount: number,
+  context: number
+): readonly GrepLineRange[] {
+  const blocks: GrepLineRange[] = [];
+
+  for (const range of ranges) {
+    const expanded = {
+      startLineNumber: Math.max(1, range.startLineNumber - context),
+      endLineNumber: Math.min(lineCount, range.endLineNumber + context),
+    };
+    const previous = blocks.at(-1);
+
+    if (
+      previous !== undefined &&
+      expanded.startLineNumber <= previous.endLineNumber + 1
+    ) {
+      blocks[blocks.length - 1] = {
+        startLineNumber: previous.startLineNumber,
+        endLineNumber: Math.max(previous.endLineNumber, expanded.endLineNumber),
+      };
+    } else {
+      blocks.push(expanded);
+    }
+  }
+
+  return blocks;
+}
+
+function matchCount(match: GrepMatch): number {
+  return match.ranges.length;
+}
+
+function isMatchLine(
+  ranges: readonly GrepLineRange[],
+  lineNumber: number
+): boolean {
+  return ranges.some(
+    (range) =>
+      lineNumber >= range.startLineNumber && lineNumber <= range.endLineNumber
+  );
+}
+
+function formatPath(filePath: string, options: RenderOptions): string {
+  return options.pathFormat === "absolute"
+    ? filePath
+    : Paths.displayRelative(filePath, options.cwd);
+}
+
+function byRecency(matches: readonly GrepMatch[]): readonly GrepMatch[] {
+  return [...matches].sort(
+    (left, right) =>
+      right.mtime - left.mtime || comparePaths(left.filePath, right.filePath)
+  );
+}
+
+function comparePaths(left: string, right: string): number {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}

package/src/extensions/grep/schema.ts

@@ -0,0 +1,92 @@
+import { StringEnum } from "@earendil-works/pi-ai";
+import { type Static, Type } from "typebox";
+
+export const GREP_HEAD_LIMIT_MAX = 1000;
+export const GREP_CONTEXT_MAX = 20;
+
+export const GREP_OUTPUT_MODES = [
+  "files_with_matches",
+  "content",
+  "count",
+] as const;
+
+export const GREP_PATH_FORMATS = ["relative", "absolute"] as const;
+
+export const grepSchema = Type.Object({
+  pattern: Type.String({
+    description: "JavaScript regex source, without /.../ delimiters.",
+  }),
+  path: Type.Optional(
+    Type.String({
+      description:
+        "Absolute or relative path to file/directory (resolved against cwd). Defaults to cwd.",
+    })
+  ),
+  glob: Type.Optional(
+    Type.String({
+      description:
+        "Relative glob filter under path when path is a directory. Gitignored files and dotfiles are skipped during directory scans unless includeIgnored/includeDotfiles is true.",
+    })
+  ),
+  exclude: Type.Optional(
+    Type.Array(Type.String(), {
+      description:
+        "Glob patterns to exclude from directory searches, relative to path (eg. **/*.test.ts or dist/**).",
+    })
+  ),
+  outputMode: Type.Optional(
+    StringEnum(GREP_OUTPUT_MODES, {
+      description:
+        "`files_with_matches` (default): returns file paths. `content`: returns path:line:text. `count`: returns path:count.",
+    })
+  ),
+  matchAcrossLines: Type.Optional(
+    Type.Boolean({
+      description:
+        "Search whole files so one match can span line breaks. Defaults to false.",
+    })
+  ),
+  context: Type.Optional(
+    Type.Integer({
+      minimum: 0,
+      maximum: GREP_CONTEXT_MAX,
+      description:
+        "For outputMode='content', include this many lines before and after each match. Defaults to 0.",
+    })
+  ),
+  includeDotfiles: Type.Optional(
+    Type.Boolean({
+      description:
+        "Include dot-prefixed files and directories such as .env or .github during directory scans. Defaults to false.",
+    })
+  ),
+  includeIgnored: Type.Optional(
+    Type.Boolean({
+      description:
+        "Include gitignored and normally ignored paths such as node_modules during directory scans. Defaults to false.",
+    })
+  ),
+  pathFormat: Type.Optional(
+    StringEnum(GREP_PATH_FORMATS, {
+      description:
+        "`relative` (default): output paths relative to cwd when possible. `absolute`: output absolute paths.",
+    })
+  ),
+  caseInsensitive: Type.Optional(
+    Type.Boolean({
+      description: "Search case-insensitively. Defaults to false.",
+    })
+  ),
+  headLimit: Type.Optional(
+    Type.Integer({
+      minimum: 1,
+      maximum: GREP_HEAD_LIMIT_MAX,
+      description: `Maximum returned items. Defaults to ${GREP_HEAD_LIMIT_MAX}.`,
+    })
+  ),
+});
+
+export type GrepInput = Static<typeof grepSchema>;
+
+export type GrepOutputMode = (typeof GREP_OUTPUT_MODES)[number];
+export type GrepPathFormat = (typeof GREP_PATH_FORMATS)[number];

package/src/extensions/read/index.ts

@@ -0,0 +1,84 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Paths } from "../../shared/Paths";
+import { Renderer } from "../../shared/Renderer";
+import { Tools } from "../../shared/Tools";
+import { buildReadRange, readFile } from "./read";
+import { formatTitlePath } from "./render";
+import { type ReadInput, readSchema } from "./schema";
+
+const PREVIEW_LINES = 10;
+
+export default function (pi: ExtensionAPI): void {
+  Tools.register(pi, {
+    name: "read",
+    label: "read",
+    description:
+      "Read a local UTF-8 text file. Output is `LINE:CONTENT` with no space after the colon. Capped at 32KB per call; lines longer than 2000 chars are truncated.",
+    promptSnippet: "Read text files.",
+    parameters: readSchema,
+    renderShell: "self",
+    executionMode: "parallel",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { path, start, end } = params as ReadInput;
+
+      if (signal?.aborted) {
+        throw new Error("Read aborted before execution.");
+      }
+
+      const range = buildReadRange(start, end);
+      const absolutePath = Paths.resolve(path, ctx.cwd);
+      const outcome = await readFile(absolutePath, range);
+
+      const content: Array<{ type: "text"; text: string }> = [
+        { type: "text", text: outcome.body },
+      ];
+
+      if (outcome.truncatedByEnd && outcome.nextStart !== undefined) {
+        content.push({
+          type: "text",
+          text: `[read tool: showing lines ${outcome.visibleStart}-${outcome.visibleEnd} of ${outcome.totalLines}; call read again with start=${outcome.nextStart} to continue.]`,
+        });
+      }
+
+      return {
+        content,
+        details: {
+          absolutePath,
+          totalLines: outcome.totalLines,
+          visibleStart: outcome.visibleStart,
+          visibleEnd: outcome.visibleEnd,
+          truncatedByByteCap: outcome.truncatedByByteCap,
+          truncatedByEnd: outcome.truncatedByEnd,
+          hadBom: outcome.hadBom,
+          ...(outcome.nextStart === undefined
+            ? {}
+            : { nextStart: outcome.nextStart }),
+        },
+      };
+    },
+    renderCall(args, theme, context) {
+      const input = (args ?? {}) as Partial<ReadInput>;
+      const title = formatTitlePath({
+        path: input.path,
+        cwd: context.cwd,
+        start: input.start,
+        end: input.end,
+      });
+      return Renderer.renderToolCallTitle({
+        label: "Read",
+        title,
+        theme,
+        context,
+      });
+    },
+    renderResult(result, options, theme, context) {
+      return Renderer.renderBorderedResult({
+        result,
+        options,
+        theme,
+        context,
+        previewLines: PREVIEW_LINES,
+      });
+    },
+  });
+}

package/src/extensions/read/read.test.ts

@@ -0,0 +1,177 @@
+import { chmod, mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "bun:test";
+import { OutputBudget } from "../../shared/OutputBudget";
+import { buildReadRange, readFile } from "./read";
+
+const MAX_LINE_LENGTH = OutputBudget.maxLineLength;
+
+const tempRoots: string[] = [];
+
+const tempRoot = async (): Promise<string> => {
+  const root = await mkdtemp(join(tmpdir(), "pim-read-tool-"));
+  tempRoots.push(root);
+  return root;
+};
+
+afterAll(async () => {
+  await Promise.all(
+    tempRoots.map((root) => rm(root, { force: true, recursive: true }))
+  );
+});
+
+describe("readFile", () => {
+  test("emits inclusive LINE:CONTENT ranges", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta\ngamma", "utf8");
+
+    const outcome = await readFile(path, buildReadRange(2, 2));
+    expect(outcome.body).toBe("2:beta");
+    expect(outcome.totalLines).toBe(3);
+    expect(outcome.visibleStart).toBe(2);
+    expect(outcome.visibleEnd).toBe(2);
+    expect(outcome.truncatedByByteCap).toBe(false);
+    expect(outcome.truncatedByEnd).toBe(true);
+    expect(outcome.nextStart).toBe(3);
+  });
+
+  test("does not surface a phantom final line for files ending in a newline", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta\ngamma\n", "utf8");
+
+    const outcome = await readFile(path, buildReadRange(undefined, undefined));
+    expect(outcome.body).toBe(["1:alpha", "2:beta", "3:gamma"].join("\n"));
+    expect(outcome.totalLines).toBe(3);
+    expect(outcome.truncatedByEnd).toBe(false);
+  });
+
+  test("strips UTF-8 BOM from output and reports it in details", async () => {
+    const root = await tempRoot();
+    const path = join(root, "bom.txt");
+    await writeFile(path, "\uFEFFalpha\nbeta", "utf8");
+
+    const outcome = await readFile(path, buildReadRange(undefined, undefined));
+    expect(outcome.body).toBe("1:alpha\n2:beta");
+    expect(outcome.hadBom).toBe(true);
+  });
+
+  test("truncates very long individual lines", async () => {
+    const root = await tempRoot();
+    const path = join(root, "long-line.txt");
+    await writeFile(path, `${"x".repeat(MAX_LINE_LENGTH + 10)}\nshort`, "utf8");
+
+    const outcome = await readFile(path, buildReadRange(1, 1));
+    expect(outcome.body).toBe(
+      `1:${"x".repeat(MAX_LINE_LENGTH)}... (line truncated to ${MAX_LINE_LENGTH} chars)`
+    );
+  });
+
+  test("throws on empty files and out-of-range starts", async () => {
+    const root = await tempRoot();
+    const path = join(root, "empty.txt");
+    await writeFile(path, "", "utf8");
+
+    await expect(
+      readFile(path, buildReadRange(undefined, undefined))
+    ).rejects.toThrow("File is empty. Use the write tool to create content.");
+
+    const populated = join(root, "small.txt");
+    await writeFile(populated, "alpha\nbeta", "utf8");
+    await expect(
+      readFile(populated, buildReadRange(99, undefined))
+    ).rejects.toThrow(
+      "Start 99 is beyond end of file (2 lines total). Use start=1 to read from the beginning, or start=2 to read the last line."
+    );
+  });
+
+  test("rejects directories and binary files", async () => {
+    const root = await tempRoot();
+    const nested = join(root, "nested");
+    const binary = join(root, "data.bin");
+
+    await mkdir(nested);
+    await Bun.write(binary, new Uint8Array([1, 0, 2]));
+
+    await expect(
+      readFile(nested, buildReadRange(undefined, undefined))
+    ).rejects.toThrow(`Path is a directory: ${nested}`);
+
+    await expect(
+      readFile(binary, buildReadRange(undefined, undefined))
+    ).rejects.toThrow("Read only supports UTF-8 text files");
+  });
+
+  test("returns missing-file error with sibling suggestions", async () => {
+    const root = await tempRoot();
+    const missing = join(root, "note.txt");
+    await writeFile(join(root, "notes.txt"), "alpha", "utf8");
+
+    await expect(
+      readFile(missing, buildReadRange(undefined, undefined))
+    ).rejects.toThrow(/Did you mean one of these\?[\s\S]*notes\.txt/);
+  });
+
+  test("surfaces permission-denied as a structured error", async () => {
+    if (process.getuid?.() === 0) {
+      return;
+    }
+
+    const root = await tempRoot();
+    const path = join(root, "locked.txt");
+    await writeFile(path, "secret", "utf8");
+    await chmod(path, 0o000);
+
+    try {
+      await expect(
+        readFile(path, buildReadRange(undefined, undefined))
+      ).rejects.toThrow(`Permission denied reading ${path}.`);
+    } finally {
+      await chmod(path, 0o644);
+    }
+  });
+
+  test("applies a 32 KiB head-only byte cap and reports pagination metadata", async () => {
+    const root = await tempRoot();
+    const path = join(root, "long.txt");
+    const lines = Array.from(
+      { length: 80 },
+      (_, index) => `${index + 1}: ${"x".repeat(500)}`
+    );
+    await writeFile(path, lines.join("\n"), "utf8");
+
+    const outcome = await readFile(path, buildReadRange(undefined, undefined));
+    expect(Buffer.byteLength(outcome.body, "utf8")).toBeLessThanOrEqual(
+      32 * 1024
+    );
+    expect(outcome.truncatedByByteCap).toBe(true);
+    expect(outcome.truncatedByEnd).toBe(true);
+    expect(outcome.nextStart).toBe(outcome.visibleEnd + 1);
+    expect(outcome.totalLines).toBe(80);
+  });
+});
+
+describe("buildReadRange", () => {
+  test("rejects end before start", () => {
+    expect(() => buildReadRange(5, 4)).toThrow(
+      "Read end line 4 must be >= start line 5."
+    );
+  });
+
+  test("rejects non-positive integers", () => {
+    expect(() => buildReadRange(0, undefined)).toThrow(
+      "Read start 0 must be a positive integer."
+    );
+    expect(() => buildReadRange(undefined, -1)).toThrow(
+      "Read end -1 must be a positive integer."
+    );
+  });
+
+  test("defaults start to 1", () => {
+    expect(buildReadRange(undefined, undefined)).toEqual({
+      start: 1,
+    });
+  });
+});