@aaroncql/pim-agent 0.0.1

package/src/shared/GitignoreFilter.ts

@@ -0,0 +1,142 @@
+import { readFile, stat } from "node:fs/promises";
+import { dirname, isAbsolute, parse, relative, resolve } from "node:path";
+import ignore, { type Ignore } from "ignore";
+import { FsErrors } from "./FsErrors";
+import { Paths } from "./Paths";
+
+type IgnoreMatcher = {
+  readonly baseDirectory: string;
+  readonly matcher: Ignore;
+};
+
+export class GitignoreFilter {
+  private static readonly alwaysIgnoredPatterns = [
+    ".git/",
+    "node_modules/",
+    "dist/",
+    "build/",
+    "out/",
+    "target/",
+    "coverage/",
+    ".next/",
+    ".cache/",
+    ".turbo/",
+    ".vercel/",
+    ".svelte-kit/",
+  ] as const;
+
+  private readonly matchers: readonly IgnoreMatcher[];
+
+  private constructor(matchers: readonly IgnoreMatcher[]) {
+    this.matchers = matchers;
+  }
+
+  public static async for(root: string): Promise<GitignoreFilter> {
+    const absoluteRoot = resolve(root);
+    const rootDirectory =
+      await GitignoreFilter.containingDirectory(absoluteRoot);
+    const directories =
+      await GitignoreFilter.gitignoreDirectories(rootDirectory);
+    const contents = await Promise.all(
+      directories.map((directory) => GitignoreFilter.readGitignore(directory))
+    );
+    const matchers: IgnoreMatcher[] = [
+      {
+        baseDirectory: rootDirectory,
+        matcher: ignore().add([...GitignoreFilter.alwaysIgnoredPatterns]),
+      },
+    ];
+
+    for (const [index, directory] of directories.entries()) {
+      const body = contents[index];
+
+      if (body !== undefined) {
+        matchers.push({
+          baseDirectory: directory,
+          matcher: ignore().add(body),
+        });
+      }
+    }
+
+    return new GitignoreFilter(matchers);
+  }
+
+  public ignores(absolutePath: string): boolean {
+    if (!isAbsolute(absolutePath)) {
+      throw new Error(`Expected absolute path: ${absolutePath}`);
+    }
+
+    for (const { baseDirectory, matcher } of this.matchers) {
+      const candidate = this.relativePath(baseDirectory, absolutePath);
+
+      if (candidate !== undefined && matcher.ignores(candidate)) {
+        return true;
+      }
+    }
+
+    return false;
+  }
+
+  private static async containingDirectory(path: string): Promise<string> {
+    const metadata = await stat(path);
+
+    return metadata.isDirectory() ? path : dirname(path);
+  }
+
+  private static async gitignoreDirectories(
+    root: string
+  ): Promise<readonly string[]> {
+    const directories: string[] = [];
+    const filesystemRoot = parse(root).root;
+    let current = root;
+
+    while (true) {
+      directories.push(current);
+
+      if (await Bun.file(resolve(current, ".git")).exists()) {
+        break;
+      }
+
+      if (current === filesystemRoot) {
+        break;
+      }
+
+      current = dirname(current);
+    }
+
+    return directories;
+  }
+
+  private static async readGitignore(
+    directory: string
+  ): Promise<string | undefined> {
+    const path = resolve(directory, ".gitignore");
+
+    try {
+      return await readFile(path, "utf8");
+    } catch (error) {
+      if (FsErrors.code(error) === "ENOENT") {
+        return undefined;
+      }
+
+      throw error;
+    }
+  }
+
+  private relativePath(
+    baseDirectory: string,
+    absolutePath: string
+  ): string | undefined {
+    const candidate = relative(baseDirectory, absolutePath);
+
+    if (
+      candidate.length === 0 ||
+      candidate.startsWith("..") ||
+      isAbsolute(candidate)
+    ) {
+      return undefined;
+    }
+
+    return Paths.toForwardSlashes(candidate);
+  }
+}

package/src/shared/GlobExclusions.ts

@@ -0,0 +1,23 @@
+import { relative } from "node:path";
+import { Paths } from "./Paths";
+
+export class GlobExclusions {
+  public static compile(
+    exclude: readonly string[] | undefined
+  ): readonly Bun.Glob[] {
+    return (exclude ?? []).map((pattern) => new Bun.Glob(pattern));
+  }
+
+  public static ignores(
+    globs: readonly Bun.Glob[],
+    root: string,
+    path: string
+  ): boolean {
+    if (globs.length === 0) {
+      return false;
+    }
+
+    const candidate = Paths.toForwardSlashes(relative(root, path));
+    return globs.some((glob) => glob.match(candidate));
+  }
+}

package/src/shared/Levenshtein.ts

@@ -0,0 +1,33 @@
+export class Levenshtein {
+  public static distance(left: string, right: string): number {
+    if (left === right) {
+      return 0;
+    }
+    if (left.length === 0 || right.length === 0) {
+      return Math.max(left.length, right.length);
+    }
+
+    let previous = Array.from(
+      { length: right.length + 1 },
+      (_, index) => index
+    );
+    let current = Array.from({ length: right.length + 1 }, () => 0);
+
+    for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+      current[0] = leftIndex;
+
+      for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+        const cost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+        current[rightIndex] = Math.min(
+          previous[rightIndex]! + 1,
+          current[rightIndex - 1]! + 1,
+          previous[rightIndex - 1]! + cost
+        );
+      }
+
+      [previous, current] = [current, previous];
+    }
+
+    return previous[right.length] ?? 0;
+  }
+}

package/src/shared/Lines.test.ts

@@ -0,0 +1,25 @@
+import { describe, expect, test } from "bun:test";
+import { Lines } from "./Lines";
+
+describe("Lines.continuationLine", () => {
+  test("resumes on the partial last line when the cut is mid-line", () => {
+    expect(Lines.continuationLine("a\nb\nc")).toBe(3);
+  });
+
+  test("resumes on the next line when the cut lands on a newline", () => {
+    expect(Lines.continuationLine("a\nb\n")).toBe(3);
+  });
+
+  test("treats a single unterminated line as line 1", () => {
+    expect(Lines.continuationLine("a")).toBe(1);
+  });
+
+  test("never returns below 1 for empty input", () => {
+    expect(Lines.continuationLine("")).toBe(1);
+  });
+
+  test("counts normalized newlines (CRLF and CR)", () => {
+    expect(Lines.continuationLine("a\r\nb\r\nc")).toBe(3);
+    expect(Lines.continuationLine("a\rb")).toBe(2);
+  });
+});

package/src/shared/Lines.ts

@@ -0,0 +1,77 @@
+export class Lines {
+  public static readonly utf8Bom = "\uFEFF";
+  public static readonly utf8BomBytes = new Uint8Array([0xef, 0xbb, 0xbf]);
+
+  public static normalize(content: string): string {
+    return Lines.stripUtf8Bom(content)
+      .replaceAll("\r\n", "\n")
+      .replaceAll("\r", "\n");
+  }
+
+  public static split(content: string): readonly string[] {
+    const normalized = Lines.normalize(content);
+
+    if (normalized.length === 0) {
+      return [];
+    }
+
+    const parts = normalized.split("\n");
+
+    if (parts.at(-1) === "") {
+      parts.pop();
+    }
+
+    return parts;
+  }
+
+  public static hasTrailingNewline(content: string): boolean {
+    return Lines.normalize(content).endsWith("\n");
+  }
+
+  /**
+   * Given a truncated head prefix of a larger file, the 1-based line to resume
+   * reading at so the (possibly mid-line) cut point is re-read in full. Matches
+   * how `read` numbers lines via `split`, so the hint lands on the right line.
+   */
+  public static continuationLine(head: string): number {
+    const { lines, hasTrailingNewline } = Lines.splitWithTrailingNewline(head);
+    return Math.max(1, lines.length + (hasTrailingNewline ? 1 : 0));
+  }
+
+  public static splitWithTrailingNewline(content: string): {
+    readonly lines: readonly string[];
+    readonly hasTrailingNewline: boolean;
+  } {
+    const normalized = Lines.normalize(content);
+
+    if (normalized.length === 0) {
+      return { lines: [], hasTrailingNewline: false };
+    }
+
+    const parts = normalized.split("\n");
+    const hasTrailingNewline = parts.at(-1) === "";
+
+    if (hasTrailingNewline) {
+      parts.pop();
+    }
+
+    return { lines: parts, hasTrailingNewline };
+  }
+
+  public static stripUtf8Bom(content: string): string {
+    return content.startsWith(Lines.utf8Bom) ? content.slice(1) : content;
+  }
+
+  public static hasUtf8Bom(bytes: Uint8Array): boolean {
+    return (
+      bytes[0] === Lines.utf8BomBytes[0] &&
+      bytes[1] === Lines.utf8BomBytes[1] &&
+      bytes[2] === Lines.utf8BomBytes[2]
+    );
+  }
+
+  public static async isBinary(file: Bun.BunFile): Promise<boolean> {
+    const bytes = new Uint8Array(await file.slice(0, 8192).arrayBuffer());
+    return bytes.includes(0);
+  }
+}

package/src/shared/McpClient.test.ts

@@ -0,0 +1,235 @@
+import { expect, test } from "bun:test";
+import { McpClient } from "./McpClient";
+
+type MockFetch = (
+  input: Parameters<typeof fetch>[0],
+  init?: Parameters<typeof fetch>[1]
+) => ReturnType<typeof fetch>;
+
+type CapturedRequest = {
+  readonly url: string;
+  readonly headers: Headers;
+  readonly body: Readonly<Record<string, unknown>>;
+};
+
+const captureRequest = async (
+  input: Parameters<typeof fetch>[0],
+  init: Parameters<typeof fetch>[1] | undefined
+): Promise<CapturedRequest> => {
+  if (input instanceof Request) {
+    const text = await input.clone().text();
+
+    return {
+      url: input.url,
+      headers: input.headers,
+      body: JSON.parse(text) as Readonly<Record<string, unknown>>,
+    };
+  }
+
+  return {
+    url: String(input),
+    headers: new Headers(init?.headers),
+    body: JSON.parse(String(init?.body)) as Readonly<Record<string, unknown>>,
+  };
+};
+
+const okToolCallResponse = (result: unknown): Response =>
+  Response.json({ jsonrpc: "2.0", id: 2, result });
+
+test("performs the initialize → initialized → tools/call round trip", async () => {
+  const requests: CapturedRequest[] = [];
+  const fetcher: MockFetch = async (input, init) => {
+    const request = await captureRequest(input, init);
+    requests.push(request);
+
+    if (request.body["method"] === "initialize") {
+      return Response.json(
+        { jsonrpc: "2.0", id: 1, result: {} },
+        { headers: { "mcp-session-id": "session-json" } }
+      );
+    }
+
+    if (request.body["method"] === "notifications/initialized") {
+      return new Response(null, { status: 202 });
+    }
+
+    return okToolCallResponse({ ok: true });
+  };
+  const client = new McpClient({
+    endpoint: "https://mcp.test/mcp",
+    headers: { "x-api-key": "test-key" },
+    fetch: fetcher,
+  });
+
+  await expect(
+    client.callTool({ name: "demo_tool", arguments: { x: 1 } })
+  ).resolves.toEqual({ ok: true });
+
+  expect(requests.map((request) => request.url)).toEqual([
+    "https://mcp.test/mcp",
+    "https://mcp.test/mcp",
+    "https://mcp.test/mcp",
+  ]);
+  expect(requests[1]?.headers.get("mcp-session-id")).toBe("session-json");
+  expect(requests[2]?.headers.get("mcp-session-id")).toBe("session-json");
+  expect(requests[0]?.headers.get("x-api-key")).toBe("test-key");
+  for (const request of requests) {
+    expect(request.headers.get("mcp-protocol-version")).toBe("2025-06-18");
+  }
+  expect(requests[0]?.body).toEqual({
+    jsonrpc: "2.0",
+    id: 1,
+    method: "initialize",
+    params: {
+      protocolVersion: "2025-06-18",
+      clientInfo: {
+        name: "pim-agent",
+        version: "0.0.0",
+      },
+      capabilities: {},
+    },
+  });
+  expect(requests[2]?.body).toEqual({
+    jsonrpc: "2.0",
+    id: 2,
+    method: "tools/call",
+    params: {
+      name: "demo_tool",
+      arguments: { x: 1 },
+    },
+  });
+});
+
+test("parses SSE responses", async () => {
+  const ssePayload = [
+    "event: message",
+    `data: ${JSON.stringify({
+      jsonrpc: "2.0",
+      id: 2,
+      result: { ok: true },
+    })}`,
+    "",
+    "",
+  ].join("\n");
+  const fetcher: MockFetch = async (input, init) => {
+    const request = await captureRequest(input, init);
+
+    if (request.body["method"] === "initialize") {
+      return Response.json(
+        { jsonrpc: "2.0", id: 1, result: {} },
+        { headers: { "mcp-session-id": "session-sse" } }
+      );
+    }
+
+    if (request.body["method"] === "notifications/initialized") {
+      return new Response(null, { status: 202 });
+    }
+
+    return new Response(ssePayload, {
+      headers: { "content-type": "text/event-stream" },
+    });
+  };
+  const client = new McpClient({
+    endpoint: "https://mcp.test/mcp",
+    fetch: fetcher,
+  });
+
+  await expect(
+    client.callTool({ name: "demo_tool", arguments: {} })
+  ).resolves.toEqual({ ok: true });
+});
+
+test("throws clean errors for HTTP failures", async () => {
+  const fetcher: MockFetch = async () =>
+    new Response("upstream unavailable and not useful beyond this excerpt", {
+      status: 503,
+    });
+  const client = new McpClient({
+    endpoint: "https://mcp.test/mcp",
+    fetch: fetcher,
+  });
+
+  await expect(
+    client.callTool({ name: "demo_tool", arguments: {} })
+  ).rejects.toThrow("MCP request failed with HTTP 503: upstream unavailable");
+});
+
+test("throws clean errors for JSON-RPC failures", async () => {
+  const fetcher: MockFetch = async (input, init) => {
+    const request = await captureRequest(input, init);
+
+    if (request.body["method"] === "initialize") {
+      return Response.json(
+        { jsonrpc: "2.0", id: 1, result: {} },
+        { headers: { "mcp-session-id": "session-error" } }
+      );
+    }
+
+    if (request.body["method"] === "notifications/initialized") {
+      return new Response(null, { status: 202 });
+    }
+
+    return Response.json({
+      jsonrpc: "2.0",
+      id: 2,
+      error: { code: -32602, message: "Invalid input." },
+    });
+  };
+  const client = new McpClient({
+    endpoint: "https://mcp.test/mcp",
+    fetch: fetcher,
+  });
+
+  await expect(
+    client.callTool({ name: "demo_tool", arguments: {} })
+  ).rejects.toThrow("MCP JSON-RPC error: Invalid input.");
+});
+
+test("sends cancellation notification on aborted calls", async () => {
+  const abortController = new AbortController();
+  const requests: CapturedRequest[] = [];
+  const fetcher: MockFetch = async (input, init) => {
+    const request = await captureRequest(input, init);
+    requests.push(request);
+
+    if (request.body["method"] === "initialize") {
+      return Response.json(
+        { jsonrpc: "2.0", id: 1, result: {} },
+        { headers: { "mcp-session-id": "session-abort" } }
+      );
+    }
+
+    if (request.body["method"] === "notifications/initialized") {
+      return new Response(null, { status: 202 });
+    }
+
+    if (request.body["method"] === "tools/call") {
+      abortController.abort();
+      throw new DOMException("Aborted", "AbortError");
+    }
+
+    return new Response(null, { status: 202 });
+  };
+  const client = new McpClient({
+    endpoint: "https://mcp.test/mcp",
+    fetch: fetcher,
+  });
+
+  await expect(
+    client.callTool({
+      name: "demo_tool",
+      arguments: {},
+      signal: abortController.signal,
+    })
+  ).rejects.toThrow("MCP request aborted.");
+
+  expect(requests.at(-1)?.body).toEqual({
+    jsonrpc: "2.0",
+    method: "notifications/cancelled",
+    params: {
+      requestId: 2,
+      reason: "Tool call aborted.",
+    },
+  });
+  expect(requests.at(-1)?.headers.get("mcp-session-id")).toBe("session-abort");
+});