@aaroncql/pim-agent 0.0.1

package/src/extensions/edit/index.ts

@@ -0,0 +1,54 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { type DiffRenderState, DiffView } from "../../shared/DiffView";
+import { Paths } from "../../shared/Paths";
+import { Tools } from "../../shared/Tools";
+import { editFile, formatEditSummary } from "./edit";
+import { type EditInput, editSchema } from "./schema";
+
+const ERROR_PREVIEW_LINES = 12;
+
+export default function (pi: ExtensionAPI): void {
+  Tools.register(pi, {
+    name: "edit",
+    label: "edit",
+    description:
+      "Replace strings in a UTF-8 text file. Prefer edit over write for changes to existing files.",
+    parameters: editSchema,
+    renderShell: "self",
+    executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { path, edits } = params as EditInput;
+
+      if (signal?.aborted) {
+        throw new Error("Edit aborted before execution.");
+      }
+
+      const absolutePath = Paths.resolve(path, ctx.cwd);
+      const outcome = await editFile(absolutePath, edits);
+
+      return {
+        content: [{ type: "text", text: formatEditSummary(path, outcome) }],
+        details: outcome,
+      };
+    },
+    renderCall(args, theme, context) {
+      const rawPath = typeof args?.path === "string" ? args.path : undefined;
+      return DiffView.renderDiffCall({
+        label: "Edit",
+        rawPath,
+        theme,
+        context: context as typeof context & { state: DiffRenderState },
+      });
+    },
+    renderResult(result, options, theme, context) {
+      return DiffView.renderDiffResult({
+        label: "Edit",
+        result,
+        options,
+        theme,
+        context: context as typeof context & { state: DiffRenderState },
+        previewLines: ERROR_PREVIEW_LINES,
+      });
+    },
+  });
+}

package/src/extensions/edit/schema.ts

@@ -0,0 +1,37 @@
+import { type Static, Type } from "typebox";
+
+export const editSchema = Type.Object({
+  path: Type.String({
+    description: "Absolute or relative path to file (resolved against cwd).",
+  }),
+  edits: Type.Array(
+    Type.Object(
+      {
+        oldString: Type.String({
+          description:
+            "Use the actual file content without the `LINE:` prefix from read output. Must be unique unless replaceAll=true. Include enough surrounding context for uniqueness.",
+        }),
+        newString: Type.String({
+          description:
+            "Replacement text. Empty string deletes the matched range.",
+        }),
+        replaceAll: Type.Optional(
+          Type.Boolean({
+            description:
+              "If true, replaces every occurrence of oldString. Defaults to false.",
+          })
+        ),
+      },
+      { additionalProperties: false }
+    ),
+    {
+      minItems: 1,
+      description:
+        "Non-empty atomic batch of edits. Batched edits resolve against the initial file state and must not overlap. For sequential transformations where edit 2 depends on edit 1's result, use separate tool calls.",
+    }
+  ),
+});
+
+export type EditInput = Static<typeof editSchema>;
+
+export type RawEdit = EditInput["edits"][number];

package/src/extensions/file-picker/catalog.test.ts

@@ -0,0 +1,263 @@
+import { afterEach, beforeEach, describe, expect, test } from "bun:test";
+import { mkdtemp, mkdir, rm, symlink, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import {
+  loadAbsolute,
+  loadRelative,
+  type GitSpawnResult,
+  type GitSpawner,
+} from "./catalog";
+
+let workspace: string;
+
+beforeEach(async () => {
+  workspace = await mkdtemp(join(tmpdir(), "pim-file-catalog-"));
+});
+
+afterEach(async () => {
+  await rm(workspace, { force: true, recursive: true });
+});
+
+const failingSpawner: GitSpawner = async () => ({
+  exitCode: 1,
+  stdout: "",
+});
+
+const succeedingSpawner = (files: readonly string[]): GitSpawner => {
+  return async () => ({
+    exitCode: 0,
+    stdout: files.join("\n"),
+  });
+};
+
+describe("loadRelative — fast path (git ls-files)", () => {
+  test("returns the listed files as forward-slash relative paths", async () => {
+    const candidates = await loadRelative({
+      root: workspace,
+      gitSpawner: succeedingSpawner([
+        "src/foo.ts",
+        "src/bar/baz.ts",
+        "README.md",
+      ]),
+    });
+
+    const paths = candidates.map((c) => c.displayPath);
+    expect(paths).toContain("README.md");
+    expect(paths).toContain("src/foo.ts");
+    expect(paths).toContain("src/bar/baz.ts");
+    for (const candidate of candidates) {
+      expect(candidate.isDirectory).toBe(false);
+      expect(candidate.insertPath).toBe(candidate.displayPath);
+      expect(candidate.matchHaystack).toBe(candidate.displayPath);
+    }
+  });
+
+  test("sorts ascending by relative path", async () => {
+    const candidates = await loadRelative({
+      root: workspace,
+      gitSpawner: succeedingSpawner(["zeta.ts", "alpha.ts", "mu.ts"]),
+    });
+
+    expect(candidates.map((c) => c.displayPath)).toEqual([
+      "alpha.ts",
+      "mu.ts",
+      "zeta.ts",
+    ]);
+  });
+
+  test("limit truncates after sort", async () => {
+    const candidates = await loadRelative({
+      root: workspace,
+      gitSpawner: succeedingSpawner(["c.ts", "a.ts", "b.ts", "d.ts"]),
+      limit: 2,
+    });
+
+    expect(candidates.map((c) => c.displayPath)).toEqual(["a.ts", "b.ts"]);
+  });
+});
+
+describe("loadRelative — fallback (Bun.Glob)", () => {
+  test("walks the directory and skips gitignored entries", async () => {
+    await writeFile(join(workspace, ".gitignore"), "ignored.txt\n");
+    await writeFile(join(workspace, "kept.ts"), "kept");
+    await writeFile(join(workspace, "ignored.txt"), "ignored");
+    await mkdir(join(workspace, "nested"), { recursive: true });
+    await writeFile(join(workspace, "nested", "deep.ts"), "deep");
+    await mkdir(join(workspace, "node_modules"), { recursive: true });
+    await writeFile(join(workspace, "node_modules", "junk.js"), "junk");
+
+    const candidates = await loadRelative({
+      root: workspace,
+      gitSpawner: failingSpawner,
+    });
+
+    const paths = candidates.map((c) => c.displayPath);
+    expect(paths).toContain("kept.ts");
+    expect(paths).toContain("nested/deep.ts");
+    expect(paths).not.toContain("ignored.txt");
+    expect(paths.some((p) => p.includes("node_modules"))).toBe(false);
+  });
+
+  test("empty workspace produces an empty list", async () => {
+    const candidates = await loadRelative({
+      root: workspace,
+      gitSpawner: failingSpawner,
+    });
+
+    expect(candidates).toEqual([]);
+  });
+});
+
+describe("loadRelative — coalescing", () => {
+  test("two concurrent calls with the same root share one spawn", async () => {
+    let invocations = 0;
+    const spawner: GitSpawner = async () => {
+      invocations += 1;
+      await new Promise((resolveSleep) => setTimeout(resolveSleep, 10));
+      return { exitCode: 0, stdout: "x.ts\n" } satisfies GitSpawnResult;
+    };
+
+    const [a, b] = await Promise.all([
+      loadRelative({ root: workspace, gitSpawner: spawner }),
+      loadRelative({ root: workspace, gitSpawner: spawner }),
+    ]);
+
+    expect(invocations).toBe(1);
+    expect(a).toBe(b);
+  });
+
+  test("subsequent call after settle re-runs the spawner", async () => {
+    let invocations = 0;
+    const spawner: GitSpawner = async () => {
+      invocations += 1;
+      return { exitCode: 0, stdout: "x.ts\n" };
+    };
+
+    await loadRelative({ root: workspace, gitSpawner: spawner });
+    await loadRelative({ root: workspace, gitSpawner: spawner });
+
+    expect(invocations).toBe(2);
+  });
+});
+
+describe("loadAbsolute", () => {
+  test("anchor at exact directory lists its children", async () => {
+    await mkdir(join(workspace, "sub"), { recursive: true });
+    await writeFile(join(workspace, "sub", "alpha.ts"), "a");
+    await writeFile(join(workspace, "sub", "beta.ts"), "b");
+    await mkdir(join(workspace, "sub", "child"), { recursive: true });
+
+    const result = await loadAbsolute({
+      query: `${join(workspace, "sub")}/`,
+    });
+
+    expect(result.residualQuery).toBe("");
+    const names = result.candidates.map((c) => c.matchHaystack);
+    expect(names).toEqual(["child", "alpha.ts", "beta.ts"]);
+    const child = result.candidates.find((c) => c.matchHaystack === "child");
+    expect(child?.isDirectory).toBe(true);
+    const alpha = result.candidates.find((c) => c.matchHaystack === "alpha.ts");
+    expect(alpha?.isDirectory).toBe(false);
+    expect(alpha?.insertPath).toBe(join(workspace, "sub", "alpha.ts"));
+  });
+
+  test("anchor at deepest existing prefix produces residual", async () => {
+    await mkdir(join(workspace, "sub"), { recursive: true });
+    await writeFile(join(workspace, "sub", "partial.ts"), "p");
+
+    const result = await loadAbsolute({
+      query: `${join(workspace, "sub")}/parti`,
+    });
+
+    expect(result.residualQuery).toBe("parti");
+    expect(result.candidates.map((c) => c.matchHaystack)).toEqual([
+      "partial.ts",
+    ]);
+  });
+
+  test("walks past a file that is an exact prefix to the parent directory", async () => {
+    await mkdir(join(workspace, "etc"), { recursive: true });
+    await writeFile(join(workspace, "etc", "passwd"), "fake");
+
+    const result = await loadAbsolute({
+      query: `${join(workspace, "etc", "passwd")}/foo`,
+    });
+
+    expect(result.residualQuery).toBe("passwd/foo");
+    expect(result.candidates.map((c) => c.matchHaystack)).toEqual(["passwd"]);
+  });
+
+  test("normalizes .. segments before walking", async () => {
+    await mkdir(join(workspace, "alpha"), { recursive: true });
+    await writeFile(join(workspace, "alpha", "x.ts"), "x");
+    await mkdir(join(workspace, "beta"), { recursive: true });
+
+    const result = await loadAbsolute({
+      query: `${join(workspace, "beta")}/../alpha/`,
+    });
+
+    expect(result.residualQuery).toBe("");
+    expect(result.candidates.map((c) => c.matchHaystack)).toEqual(["x.ts"]);
+  });
+
+  test("nonexistent suffix walks up to the deepest existing ancestor", async () => {
+    await mkdir(join(workspace, "real"), { recursive: true });
+    await writeFile(join(workspace, "real", "kept.ts"), "k");
+
+    const result = await loadAbsolute({
+      query: `${join(workspace, "real")}/nope/foo`,
+    });
+
+    expect(result.residualQuery).toBe("nope/foo");
+    expect(result.candidates.map((c) => c.matchHaystack)).toEqual(["kept.ts"]);
+  });
+
+  test("symlinked directory is treated as a directory anchor", async () => {
+    await mkdir(join(workspace, "real"), { recursive: true });
+    await writeFile(join(workspace, "real", "x.ts"), "x");
+    await symlink(join(workspace, "real"), join(workspace, "link"));
+
+    const result = await loadAbsolute({
+      query: `${join(workspace, "link")}/`,
+    });
+
+    expect(result.candidates.map((c) => c.matchHaystack)).toEqual(["x.ts"]);
+  });
+
+  test("dotfiles hidden unless residual starts with a dot", async () => {
+    await mkdir(join(workspace, "sub"), { recursive: true });
+    await writeFile(join(workspace, "sub", "visible.ts"), "v");
+    await writeFile(join(workspace, "sub", ".hidden"), "h");
+
+    const without = await loadAbsolute({
+      query: `${join(workspace, "sub")}/`,
+    });
+    expect(without.candidates.map((c) => c.matchHaystack)).toEqual([
+      "visible.ts",
+    ]);
+
+    const withDot = await loadAbsolute({
+      query: `${join(workspace, "sub")}/.h`,
+    });
+    expect(withDot.candidates.map((c) => c.matchHaystack)).toContain(".hidden");
+    expect(withDot.residualQuery).toBe(".h");
+  });
+
+  test("directories sort before files within the same anchor", async () => {
+    await mkdir(join(workspace, "sub"), { recursive: true });
+    await writeFile(join(workspace, "sub", "z-file.ts"), "z");
+    await mkdir(join(workspace, "sub", "a-dir"), { recursive: true });
+    await writeFile(join(workspace, "sub", "a-file.ts"), "a");
+
+    const result = await loadAbsolute({
+      query: `${join(workspace, "sub")}/`,
+    });
+
+    expect(result.candidates.map((c) => c.matchHaystack)).toEqual([
+      "a-dir",
+      "a-file.ts",
+      "z-file.ts",
+    ]);
+  });
+});

package/src/extensions/file-picker/catalog.ts

@@ -0,0 +1,219 @@
+import { readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, parse, relative, resolve, sep } from "node:path";
+import { GitignoreFilter } from "../../shared/GitignoreFilter";
+import { Paths } from "../../shared/Paths";
+
+export type FileCandidate = {
+  readonly insertPath: string;
+  readonly displayPath: string;
+  readonly matchHaystack: string;
+  readonly isDirectory: boolean;
+};
+
+export type AbsoluteCatalog = {
+  readonly candidates: readonly FileCandidate[];
+  readonly residualQuery: string;
+};
+
+export type GitSpawnResult = {
+  readonly exitCode: number;
+  readonly stdout: string;
+};
+
+export type GitSpawner = (
+  args: readonly string[],
+  options: { readonly cwd: string }
+) => Promise<GitSpawnResult>;
+
+export type LoadRelativeOptions = {
+  readonly root: string;
+  readonly limit?: number;
+  readonly gitSpawner?: GitSpawner;
+};
+
+export type LoadAbsoluteOptions = {
+  readonly query: string;
+};
+
+const DEFAULT_LIMIT = 10_000;
+
+const defaultGitSpawner: GitSpawner = async (args, options) => {
+  try {
+    const child = Bun.spawn(["git", ...args], {
+      cwd: options.cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+      stdin: "ignore",
+    });
+    const stdout = await new Response(child.stdout).text();
+    const exitCode = await child.exited;
+    return { exitCode, stdout };
+  } catch {
+    return { exitCode: -1, stdout: "" };
+  }
+};
+
+const inflightRelative = new Map<string, Promise<readonly FileCandidate[]>>();
+
+export function loadRelative(
+  options: LoadRelativeOptions
+): Promise<readonly FileCandidate[]> {
+  const root = resolve(options.root);
+  const existing = inflightRelative.get(root);
+  if (existing !== undefined) {
+    return existing;
+  }
+
+  const promise = runLoadRelative(root, options).finally(() => {
+    inflightRelative.delete(root);
+  });
+  inflightRelative.set(root, promise);
+  return promise;
+}
+
+export async function loadAbsolute(
+  options: LoadAbsoluteOptions
+): Promise<AbsoluteCatalog> {
+  const expanded = Paths.expandHome(options.query);
+  const normalized = isAbsolute(expanded) ? resolve(expanded) : expanded;
+  const anchor = await findAnchor(normalized);
+  const residualSlice = normalized.slice(anchor.length);
+  const residualQuery =
+    residualSlice.startsWith(sep) || residualSlice.startsWith("/")
+      ? residualSlice.slice(1)
+      : residualSlice;
+
+  let entries: { readonly name: string; readonly isDirectory: boolean }[];
+  try {
+    const dirents = await readdir(anchor, { withFileTypes: true });
+    entries = dirents.map((dirent) => ({
+      name: dirent.name,
+      isDirectory: dirent.isDirectory(),
+    }));
+  } catch {
+    return { candidates: [], residualQuery };
+  }
+
+  const includeDot = residualQuery.startsWith(".");
+  const filtered = entries.filter((entry) => {
+    if (!includeDot && entry.name.startsWith(".")) {
+      return false;
+    }
+    return true;
+  });
+
+  filtered.sort((a, b) => {
+    if (a.isDirectory !== b.isDirectory) {
+      return a.isDirectory ? -1 : 1;
+    }
+    return a.name.localeCompare(b.name, undefined, { sensitivity: "base" });
+  });
+
+  const candidates: FileCandidate[] = filtered.map((entry) => {
+    const fullPath = join(anchor, entry.name);
+    return {
+      insertPath: fullPath,
+      displayPath: fullPath,
+      matchHaystack: entry.name,
+      isDirectory: entry.isDirectory,
+    };
+  });
+
+  return { candidates, residualQuery };
+}
+
+async function runLoadRelative(
+  root: string,
+  options: LoadRelativeOptions
+): Promise<readonly FileCandidate[]> {
+  const limit = options.limit ?? DEFAULT_LIMIT;
+  const spawner = options.gitSpawner ?? defaultGitSpawner;
+
+  const fastPath = await tryGitListFiles(root, spawner);
+  if (fastPath !== undefined) {
+    return finalizeRelative(fastPath, limit);
+  }
+
+  const fallback = await scanWithGlob(root);
+  return finalizeRelative(fallback, limit);
+}
+
+async function tryGitListFiles(
+  root: string,
+  spawner: GitSpawner
+): Promise<readonly string[] | undefined> {
+  const result = await spawner(
+    ["ls-files", "--cached", "--others", "--exclude-standard"],
+    { cwd: root }
+  );
+
+  if (result.exitCode !== 0) {
+    return undefined;
+  }
+
+  return result.stdout.split("\n").filter((line) => line.length > 0);
+}
+
+async function scanWithGlob(root: string): Promise<readonly string[]> {
+  const filter = await GitignoreFilter.for(root);
+  const glob = new Bun.Glob("**/*");
+  const matches: string[] = [];
+
+  for await (const absolutePath of glob.scan({
+    cwd: root,
+    absolute: true,
+    onlyFiles: true,
+    dot: false,
+  })) {
+    if (!filter.ignores(absolutePath)) {
+      matches.push(Paths.toForwardSlashes(relative(root, absolutePath)));
+    }
+  }
+
+  return matches;
+}
+
+function finalizeRelative(
+  paths: readonly string[],
+  limit: number
+): readonly FileCandidate[] {
+  const normalized = paths.map(Paths.toForwardSlashes);
+  normalized.sort((a, b) => a.localeCompare(b));
+
+  const truncated =
+    normalized.length > limit ? normalized.slice(0, limit) : normalized;
+  return truncated.map((path) => ({
+    insertPath: path,
+    displayPath: path,
+    matchHaystack: path,
+    isDirectory: false,
+  }));
+}
+
+async function findAnchor(absolutePath: string): Promise<string> {
+  if (!isAbsolute(absolutePath)) {
+    return parse(process.cwd()).root;
+  }
+
+  const filesystemRoot = parse(absolutePath).root;
+  let current = absolutePath;
+
+  while (true) {
+    try {
+      const metadata = await stat(current);
+      if (metadata.isDirectory()) {
+        return current;
+      }
+    } catch {}
+
+    if (current === filesystemRoot) {
+      return filesystemRoot;
+    }
+
+    const parent = resolve(current, "..");
+    if (parent === current) {
+      return filesystemRoot;
+    }
+    current = parent;
+  }
+}