@aaroncql/pim-agent 0.0.1

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

@@ -0,0 +1,168 @@
+import { expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { AutocompleteProvider } from "@earendil-works/pi-tui";
+import type { FileCandidate } from "./catalog";
+import { createFilePickerProviderFactory } from "./index";
+
+const file = (path: string): FileCandidate => ({
+  insertPath: path,
+  displayPath: path,
+  matchHaystack: path,
+  isDirectory: false,
+});
+
+const currentProvider: AutocompleteProvider = {
+  async getSuggestions() {
+    return null;
+  },
+
+  applyCompletion(lines, cursorLine, cursorCol) {
+    return { lines, cursorLine, cursorCol };
+  },
+};
+
+const autocompleteOptions = (): { readonly signal: AbortSignal } => ({
+  signal: new AbortController().signal,
+});
+
+const flushPromises = async (): Promise<void> => {
+  await Promise.resolve();
+  await Promise.resolve();
+};
+
+test("relative @ autocomplete refreshes in the background after using the session cache", async () => {
+  let catalog: readonly FileCandidate[] = [file("old.ts")];
+  let loads = 0;
+  const factory = createFilePickerProviderFactory({
+    loadRelativeCatalog: async () => {
+      loads += 1;
+      return catalog;
+    },
+  });
+  const provider = factory(currentProvider);
+
+  await flushPromises();
+  expect(loads).toBe(1);
+
+  catalog = [file("new.ts")];
+  const stale = await provider.getSuggestions(
+    ["@new"],
+    0,
+    4,
+    autocompleteOptions()
+  );
+
+  expect(stale).toBeNull();
+  expect(loads).toBe(2);
+
+  await flushPromises();
+  const fresh = await provider.getSuggestions(
+    ["@new"],
+    0,
+    4,
+    autocompleteOptions()
+  );
+
+  expect(fresh?.items.map((item) => item.value)).toContain("@new.ts");
+});
+
+test("relative catalog cache survives provider rebuilds", async () => {
+  let catalog: readonly FileCandidate[] = [file("old.ts")];
+  const factory = createFilePickerProviderFactory({
+    loadRelativeCatalog: async () => catalog,
+  });
+  const firstProvider = factory(currentProvider);
+
+  await flushPromises();
+  catalog = [file("new.ts")];
+  await firstProvider.getSuggestions(["@new"], 0, 4, autocompleteOptions());
+  await flushPromises();
+
+  const rebuiltProvider = factory(currentProvider);
+  const fresh = await rebuiltProvider.getSuggestions(
+    ["@new"],
+    0,
+    4,
+    autocompleteOptions()
+  );
+
+  expect(fresh?.items.map((item) => item.value)).toContain("@new.ts");
+});
+
+test("relative catalog refreshes are coalesced", async () => {
+  let resolveLoad: ((catalog: readonly FileCandidate[]) => void) | undefined;
+  let loads = 0;
+  const factory = createFilePickerProviderFactory({
+    loadRelativeCatalog: () => {
+      loads += 1;
+      return new Promise((resolve) => {
+        resolveLoad = resolve;
+      });
+    },
+  });
+  const provider = factory(currentProvider);
+
+  await provider.getSuggestions(["@a"], 0, 2, autocompleteOptions());
+  await provider.getSuggestions(["@ab"], 0, 3, autocompleteOptions());
+
+  expect(loads).toBe(1);
+  resolveLoad?.([file("ab.ts")]);
+  await flushPromises();
+});
+
+test("refresh failure preserves the last good relative cache", async () => {
+  let shouldFail = false;
+  const factory = createFilePickerProviderFactory({
+    loadRelativeCatalog: async () => {
+      if (shouldFail) {
+        throw new Error("boom");
+      }
+      return [file("old.ts")];
+    },
+  });
+  const provider = factory(currentProvider);
+
+  await flushPromises();
+  shouldFail = true;
+  await provider.getSuggestions(["@old"], 0, 4, autocompleteOptions());
+  await flushPromises();
+
+  const result = await provider.getSuggestions(
+    ["@old"],
+    0,
+    4,
+    autocompleteOptions()
+  );
+
+  expect(result?.items.map((item) => item.value)).toContain("@old.ts");
+});
+
+test("absolute @ autocomplete also refreshes the relative catalog", async () => {
+  const workspace = await mkdtemp(join(tmpdir(), "pim-file-picker-absolute-"));
+  try {
+    let loads = 0;
+    const factory = createFilePickerProviderFactory({
+      loadRelativeCatalog: async () => {
+        loads += 1;
+        return [file("old.ts")];
+      },
+    });
+    const provider = factory(currentProvider);
+
+    await flushPromises();
+    expect(loads).toBe(1);
+
+    await provider.getSuggestions(
+      [`@${workspace}`],
+      0,
+      workspace.length + 1,
+      autocompleteOptions()
+    );
+
+    expect(loads).toBe(2);
+  } finally {
+    await rm(workspace, { force: true, recursive: true });
+  }
+});

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

@@ -0,0 +1,119 @@
+import type {
+  AutocompleteProviderFactory,
+  ExtensionAPI,
+} from "@earendil-works/pi-coding-agent";
+import type { AutocompleteProvider } from "@earendil-works/pi-tui";
+import { type FileCandidate, loadRelative } from "./catalog";
+import { rank } from "./ranker";
+
+const MAX_VISIBLE_ROWS = 50;
+const AT_PREFIX = /(?:^|\s)@(\S*)$/;
+
+export type FilePickerProviderFactoryOptions = {
+  readonly loadRelativeCatalog: () => Promise<readonly FileCandidate[]>;
+};
+
+export function createFilePickerProviderFactory(
+  options: FilePickerProviderFactoryOptions
+): AutocompleteProviderFactory {
+  let cachedRelative: readonly FileCandidate[] | undefined;
+  let relativeRefresh: Promise<void> | undefined;
+
+  const refreshRelative = (): void => {
+    relativeRefresh ??= options
+      .loadRelativeCatalog()
+      .then((catalog) => {
+        cachedRelative = catalog;
+      })
+      .catch(() => {
+        if (cachedRelative === undefined) {
+          cachedRelative = [];
+        }
+      })
+      .finally(() => {
+        relativeRefresh = undefined;
+      });
+  };
+
+  refreshRelative();
+
+  return (current: AutocompleteProvider): AutocompleteProvider => ({
+    async getSuggestions(lines, cursorLine, cursorCol, autocompleteOptions) {
+      const line = lines[cursorLine] ?? "";
+      const beforeCursor = line.slice(0, cursorCol);
+
+      const atMatch = beforeCursor.match(AT_PREFIX);
+      if (!atMatch) {
+        return current.getSuggestions(
+          lines,
+          cursorLine,
+          cursorCol,
+          autocompleteOptions
+        );
+      }
+
+      const query = atMatch[1] ?? "";
+      refreshRelative();
+
+      const items = await rank(query, {
+        cachedRelative,
+        limit: MAX_VISIBLE_ROWS,
+      });
+      if (items === undefined) {
+        return current.getSuggestions(
+          lines,
+          cursorLine,
+          cursorCol,
+          autocompleteOptions
+        );
+      }
+      if (items.length === 0) {
+        return null;
+      }
+      return {
+        items: items.map((item) => ({
+          ...item,
+          value: `@${item.value}`,
+        })),
+        prefix: `@${query}`,
+      };
+    },
+
+    applyCompletion(lines, cursorLine, cursorCol, item, prefix) {
+      const result = current.applyCompletion(
+        lines,
+        cursorLine,
+        cursorCol,
+        item,
+        prefix
+      );
+      // Pi cancels autocomplete after Tab; for directories we want to keep
+      // drilling, so re-enter Tab on the next tick.
+      if (typeof item.value === "string" && item.value.endsWith("/")) {
+        setTimeout(() => {
+          try {
+            process.stdin.emit("data", "\t");
+          } catch {}
+        }, 0);
+      }
+      return result;
+    },
+
+    shouldTriggerFileCompletion(lines, cursorLine, cursorCol) {
+      return (
+        current.shouldTriggerFileCompletion?.(lines, cursorLine, cursorCol) ??
+        true
+      );
+    },
+  });
+}
+
+export default function (pi: ExtensionAPI): void {
+  pi.on("session_start", (_event, ctx) => {
+    ctx.ui.addAutocompleteProvider(
+      createFilePickerProviderFactory({
+        loadRelativeCatalog: () => loadRelative({ root: ctx.cwd }),
+      })
+    );
+  });
+}

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

@@ -0,0 +1,94 @@
+import { afterEach, beforeEach, expect, test } from "bun:test";
+import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import type { FileCandidate } from "./catalog";
+import { rank } from "./ranker";
+
+let workspace: string;
+
+beforeEach(async () => {
+  workspace = await mkdtemp(join(tmpdir(), "pim-file-ranker-"));
+});
+
+afterEach(async () => {
+  await rm(workspace, { force: true, recursive: true });
+});
+
+const file = (path: string): FileCandidate => ({
+  insertPath: path,
+  displayPath: path,
+  matchHaystack: path,
+  isDirectory: false,
+});
+
+test("relative query with no cache returns undefined (fallback)", async () => {
+  const result = await rank("foo", { cachedRelative: undefined });
+
+  expect(result).toBeUndefined();
+});
+
+test("relative query with cache fuzzy-ranks the cached catalog", async () => {
+  const cachedRelative: readonly FileCandidate[] = [
+    file("src/util/log.ts"),
+    file("src/util/clock.ts"),
+    file("README.md"),
+  ];
+
+  const result = await rank("clk", { cachedRelative });
+
+  expect(result).toBeDefined();
+  expect(result?.[0]?.value).toBe("src/util/clock.ts");
+});
+
+test("empty relative query returns cached catalog in given order", async () => {
+  const cachedRelative: readonly FileCandidate[] = [
+    file("a.ts"),
+    file("b.ts"),
+    file("c.ts"),
+  ];
+
+  const result = await rank("", {
+    cachedRelative,
+    limit: 2,
+  });
+
+  expect(result?.map((item) => item.value)).toEqual(["a.ts", "b.ts"]);
+});
+
+test("absolute query lists the resolved directory", async () => {
+  await mkdir(join(workspace, "sub"), { recursive: true });
+  await writeFile(join(workspace, "sub", "alpha.ts"), "a");
+  await writeFile(join(workspace, "sub", "beta.ts"), "b");
+
+  const result = await rank(`${join(workspace, "sub")}/`, {
+    cachedRelative: undefined,
+  });
+
+  expect(result?.map((item) => item.label)).toEqual(["alpha.ts", "beta.ts"]);
+});
+
+test("absolute query with residual fuzzy-ranks within the directory", async () => {
+  await mkdir(join(workspace, "sub"), { recursive: true });
+  await writeFile(join(workspace, "sub", "alpha.ts"), "a");
+  await writeFile(join(workspace, "sub", "beta.ts"), "b");
+
+  const result = await rank(`${join(workspace, "sub")}/be`, {
+    cachedRelative: undefined,
+  });
+
+  expect(result?.[0]?.label).toBe("beta.ts");
+});
+
+test("directory candidates carry trailing slash in value and label", async () => {
+  await mkdir(join(workspace, "sub"), { recursive: true });
+  await mkdir(join(workspace, "sub", "child"), { recursive: true });
+
+  const result = await rank(`${join(workspace, "sub")}/`, {
+    cachedRelative: undefined,
+  });
+
+  const child = result?.find((item) => item.label === "child/");
+  expect(child).toBeDefined();
+  expect(child?.value.endsWith("/child/")).toBe(true);
+});

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

@@ -0,0 +1,76 @@
+import { basename } from "node:path";
+import type { AutocompleteItem } from "@earendil-works/pi-tui";
+import {
+  FuzzyMatcher,
+  type FuzzyCandidate,
+  type FuzzyIndex,
+} from "../../shared/FuzzyMatcher";
+import { type FileCandidate, loadAbsolute } from "./catalog";
+
+export type FileRankOptions = {
+  readonly cachedRelative: readonly FileCandidate[] | undefined;
+  readonly limit?: number;
+};
+
+const isAbsoluteQuery = (query: string): boolean =>
+  query.startsWith("/") || query.startsWith("~");
+
+let cachedIndex:
+  | {
+      readonly source: readonly FileCandidate[];
+      readonly index: FuzzyIndex<FileCandidate>;
+    }
+  | undefined;
+
+const indexFor = (
+  candidates: readonly FileCandidate[]
+): FuzzyIndex<FileCandidate> => {
+  if (cachedIndex?.source === candidates) {
+    return cachedIndex.index;
+  }
+  const fuzzy: FuzzyCandidate<FileCandidate>[] = candidates.map(
+    (candidate) => ({
+      item: candidate,
+      haystacks: [candidate.matchHaystack],
+    })
+  );
+  const index = FuzzyMatcher.prepare(fuzzy);
+  cachedIndex = { source: candidates, index };
+  return index;
+};
+
+export async function rank(
+  query: string,
+  options: FileRankOptions
+): Promise<AutocompleteItem[] | undefined> {
+  if (isAbsoluteQuery(query)) {
+    const { candidates, residualQuery } = await loadAbsolute({ query });
+    return rankCandidates(candidates, residualQuery, options.limit);
+  }
+
+  if (options.cachedRelative === undefined) {
+    return undefined;
+  }
+
+  return rankCandidates(options.cachedRelative, query, options.limit);
+}
+
+const rankCandidates = (
+  candidates: readonly FileCandidate[],
+  query: string,
+  limit: number | undefined
+): AutocompleteItem[] => {
+  const hits = indexFor(candidates).find(query, { limit });
+  return hits.map((hit) => toItem(hit.item));
+};
+
+const toItem = (candidate: FileCandidate): AutocompleteItem => {
+  const suffix = candidate.isDirectory ? "/" : "";
+  const value = `${candidate.insertPath}${suffix}`;
+  const label = `${basename(candidate.insertPath)}${suffix}`;
+  return {
+    value,
+    label,
+    description: `${candidate.displayPath}${suffix}`,
+  };
+};

package/src/extensions/footer/git.test.ts

@@ -0,0 +1,76 @@
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "bun:test";
+import { EMPTY_GIT, fetchGitStatus, parseGitStatus } from "./git";
+
+const tempRoots: string[] = [];
+
+const tempRoot = async (): Promise<string> => {
+  const root = await mkdtemp(join(tmpdir(), "pim-footer-git-"));
+  tempRoots.push(root);
+  return root;
+};
+
+afterAll(async () => {
+  await Promise.all(
+    tempRoots.map((root) => rm(root, { force: true, recursive: true }))
+  );
+});
+
+describe("parseGitStatus", () => {
+  test("parses clean branch status", () => {
+    expect(
+      parseGitStatus(
+        [
+          "# branch.oid 123456",
+          "# branch.head main",
+          "# branch.upstream origin/main",
+          "# branch.ab +0 -0",
+        ].join("\n")
+      )
+    ).toEqual({
+      branch: "main",
+      dirty: false,
+      ahead: 0,
+      behind: 0,
+    });
+  });
+
+  test("parses dirty state and ahead/behind counts", () => {
+    expect(
+      parseGitStatus(
+        [
+          "# branch.oid 123456",
+          "# branch.head feature/footer",
+          "# branch.upstream origin/feature/footer",
+          "# branch.ab +12 -3",
+          "1 .M N... 100644 100644 100644 abc abc src/file.ts",
+          "? scratch.txt",
+        ].join("\n")
+      )
+    ).toEqual({
+      branch: "feature/footer",
+      dirty: true,
+      ahead: 12,
+      behind: 3,
+    });
+  });
+
+  test("labels detached heads explicitly", () => {
+    expect(parseGitStatus("# branch.head (detached)\n")).toEqual({
+      branch: "detached",
+      dirty: false,
+      ahead: 0,
+      behind: 0,
+    });
+  });
+});
+
+describe("fetchGitStatus", () => {
+  test("returns empty git state outside a git repository", async () => {
+    const root = await tempRoot();
+
+    expect(await fetchGitStatus(root)).toEqual(EMPTY_GIT);
+  });
+});

package/src/extensions/footer/git.ts

@@ -0,0 +1,87 @@
+import { type FSWatcher, watch } from "node:fs";
+import { join } from "node:path";
+
+export type GitState = {
+  readonly branch: string | null;
+  readonly dirty: boolean;
+  readonly ahead: number;
+  readonly behind: number;
+};
+
+export const EMPTY_GIT: GitState = {
+  branch: null,
+  dirty: false,
+  ahead: 0,
+  behind: 0,
+};
+
+export function parseGitStatus(text: string): GitState {
+  let branch: string | null = null;
+  let ahead = 0;
+  let behind = 0;
+  let dirty = false;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("# branch.head ")) {
+      const head = line.slice("# branch.head ".length);
+      branch = head === "(detached)" ? "detached" : head;
+    } else if (line.startsWith("# branch.ab ")) {
+      const m = /\+(\d+)\s+-(\d+)/.exec(line);
+      if (m) {
+        ahead = Number(m[1]);
+        behind = Number(m[2]);
+      }
+    } else if (line.length > 0 && !line.startsWith("#")) {
+      dirty = true;
+    }
+  }
+  return { branch, dirty, ahead, behind };
+}
+
+export function watchGitDir(cwd: string, onChange: () => void): () => void {
+  let timer: ReturnType<typeof setTimeout> | null = null;
+  const fire = (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+    }
+    timer = setTimeout(() => {
+      timer = null;
+      onChange();
+    }, 200);
+  };
+  let watcher: FSWatcher | null = null;
+  try {
+    watcher = watch(join(cwd, ".git"), { persistent: false }, fire);
+    watcher.on("error", () => {});
+  } catch {
+    // not a git repo, .git missing, or .git is a worktree gitfile — skip
+  }
+  return (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (watcher !== null) {
+      try {
+        watcher.close();
+      } catch {}
+    }
+  };
+}
+
+export async function fetchGitStatus(cwd: string): Promise<GitState> {
+  try {
+    const proc = Bun.spawn(["git", "status", "--porcelain=v2", "--branch"], {
+      cwd,
+      stdout: "pipe",
+      stderr: "ignore",
+    });
+    const text = await new Response(proc.stdout).text();
+    await proc.exited;
+    if (proc.exitCode !== 0) {
+      return EMPTY_GIT;
+    }
+    return parseGitStatus(text);
+  } catch {
+    return EMPTY_GIT;
+  }
+}