pim-agent 0.0.1 → 0.9.0

package/packages/core/src/picker/catalog.ts

@@ -0,0 +1,220 @@
+import { readdir, stat } from "node:fs/promises";
+import { isAbsolute, join, parse, resolve, sep } from "node:path";
+import { FileEnumerator } from "../shared/FileEnumerator";
+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 gitSpawner?: GitSpawner;
+};
+
+export type LoadAbsoluteOptions = {
+  readonly query: string;
+};
+
+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[]>>();
+const COLLATOR = new Intl.Collator(undefined);
+
+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 = includeDot
+    ? entries
+    : entries.filter((entry) => !entry.name.startsWith("."));
+
+  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 spawner = options.gitSpawner ?? defaultGitSpawner;
+
+  const fastPath = await tryGitListFiles(root, spawner);
+  if (fastPath !== undefined) {
+    return finalizeRelative(fastPath);
+  }
+
+  const fallback = await scanWithGlob(root);
+  return finalizeRelative(fallback);
+}
+
+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[]> {
+  return FileEnumerator.enumerate(root, {
+    includeDotfiles: false,
+    includeIgnored: false,
+  });
+}
+
+function finalizeRelative(paths: readonly string[]): readonly FileCandidate[] {
+  const normalized = paths.map(Paths.toForwardSlashes);
+
+  // git ls-files only emits files; recover directories from their prefixes.
+  const directories = new Set<string>();
+  for (const path of normalized) {
+    for (
+      let slash = path.indexOf("/");
+      slash !== -1;
+      slash = path.indexOf("/", slash + 1)
+    ) {
+      directories.add(path.slice(0, slash));
+    }
+  }
+
+  const candidates = [
+    ...[...directories].map((path) => toRelativeCandidate(path, true)),
+    ...normalized.map((path) => toRelativeCandidate(path, false)),
+  ];
+  candidates.sort((a, b) => COLLATOR.compare(a.insertPath, b.insertPath));
+
+  return candidates;
+}
+
+function toRelativeCandidate(
+  path: string,
+  isDirectory: boolean
+): FileCandidate {
+  return {
+    insertPath: path,
+    displayPath: path,
+    matchHaystack: path,
+    isDirectory,
+  };
+}
+
+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;
+  }
+}

package/packages/core/src/picker/commandRanker.ts

@@ -0,0 +1,17 @@
+import type { PickerItem } from "./PickerItem";
+import { FuzzyMatcher, type FuzzyCandidate } from "../shared/FuzzyMatcher";
+
+export function rankCommands(
+  query: string,
+  items: readonly PickerItem[],
+  options: { readonly limit?: number } = {}
+): PickerItem[] {
+  const candidates: FuzzyCandidate<PickerItem>[] = items.map((item) => ({
+    item,
+    haystacks: [item.label, item.description ?? ""],
+  }));
+
+  const hits = FuzzyMatcher.rank(query, candidates, options);
+
+  return hits.map((hit) => hit.item);
+}

package/packages/core/src/picker/filePickerWorker.ts

@@ -0,0 +1,66 @@
+import { Errors } from "../shared/Errors";
+import type { FileCandidate } from "./catalog";
+import { loadRelative } from "./catalog";
+import type {
+  FilePickerWorkerRequest,
+  FilePickerWorkerResponse,
+} from "./filePickerWorkerMessages";
+import { rank } from "./ranker";
+
+let cachedRelative: readonly FileCandidate[] | undefined;
+
+const refreshRelative = async (id: number, root: string): Promise<void> => {
+  try {
+    cachedRelative = await loadRelative({ root });
+    self.postMessage({
+      id,
+      type: "refreshRelative",
+      ok: true,
+    } satisfies FilePickerWorkerResponse);
+  } catch (error) {
+    if (cachedRelative === undefined) {
+      cachedRelative = [];
+    }
+    self.postMessage({
+      id,
+      type: "refreshRelative",
+      ok: false,
+      error: Errors.describe(error),
+    } satisfies FilePickerWorkerResponse);
+  }
+};
+
+const rankSuggestions = async (
+  id: number,
+  query: string,
+  limit: number | undefined
+): Promise<void> => {
+  try {
+    const items = await rank(query, { cachedRelative, limit });
+    self.postMessage({
+      id,
+      type: "rank",
+      ok: true,
+      items,
+    } satisfies FilePickerWorkerResponse);
+  } catch (error) {
+    self.postMessage({
+      id,
+      type: "rank",
+      ok: false,
+      error: Errors.describe(error),
+    } satisfies FilePickerWorkerResponse);
+  }
+};
+
+self.onmessage = (event: MessageEvent<FilePickerWorkerRequest>): void => {
+  const message = event.data;
+  switch (message.type) {
+    case "refreshRelative":
+      void refreshRelative(message.id, message.root);
+      break;
+    case "rank":
+      void rankSuggestions(message.id, message.query, message.limit);
+      break;
+  }
+};

package/packages/core/src/picker/filePickerWorkerMessages.ts

@@ -0,0 +1,39 @@
+import type { PickerItem } from "./PickerItem";
+
+export type FilePickerWorkerRequest =
+  | {
+      readonly id: number;
+      readonly type: "refreshRelative";
+      readonly root: string;
+    }
+  | {
+      readonly id: number;
+      readonly type: "rank";
+      readonly query: string;
+      readonly limit?: number;
+    };
+
+export type FilePickerWorkerResponse =
+  | {
+      readonly id: number;
+      readonly type: "refreshRelative";
+      readonly ok: true;
+    }
+  | {
+      readonly id: number;
+      readonly type: "refreshRelative";
+      readonly ok: false;
+      readonly error: string;
+    }
+  | {
+      readonly id: number;
+      readonly type: "rank";
+      readonly ok: true;
+      readonly items: readonly PickerItem[] | undefined;
+    }
+  | {
+      readonly id: number;
+      readonly type: "rank";
+      readonly ok: false;
+      readonly error: string;
+    };

package/packages/core/src/picker/ranker.ts

@@ -0,0 +1,245 @@
+import { basename } from "node:path";
+import type { PickerItem } from "./PickerItem";
+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("~");
+const GLOBAL_FUZZY_QUERY_MIN_LENGTH = 3;
+
+const cachedIndexes = new WeakMap<
+  readonly FileCandidate[],
+  RelativeRankingIndex
+>();
+
+const indexFor = (
+  candidates: readonly FileCandidate[]
+): RelativeRankingIndex => {
+  const cached = cachedIndexes.get(candidates);
+  if (cached !== undefined) {
+    return cached;
+  }
+
+  const index = new RelativeRankingIndex(candidates);
+  cachedIndexes.set(candidates, index);
+  return index;
+};
+
+type LoweredCandidate = {
+  readonly candidate: FileCandidate;
+  readonly haystackLower: string;
+  readonly nameStart: number;
+};
+
+class RelativeRankingIndex {
+  private readonly childrenByDirectory = new Map<string, FileCandidate[]>();
+  private readonly loweredSource: readonly LoweredCandidate[];
+
+  private readonly scopedIndexes = new Map<string, FuzzyIndex<FileCandidate>>();
+  private globalIndex: FuzzyIndex<FileCandidate> | undefined;
+
+  public constructor(private readonly source: readonly FileCandidate[]) {
+    const lowered: LoweredCandidate[] = [];
+
+    for (const candidate of source) {
+      const slash = candidate.insertPath.lastIndexOf("/");
+      const directory =
+        slash === -1 ? "" : candidate.insertPath.slice(0, slash);
+      const children = this.childrenByDirectory.get(directory) ?? [];
+      children.push(candidate);
+      this.childrenByDirectory.set(directory, children);
+
+      lowered.push({
+        candidate,
+        haystackLower: candidate.matchHaystack.toLocaleLowerCase(),
+        nameStart: slash + 1,
+      });
+    }
+
+    this.loweredSource = lowered;
+  }
+
+  public rank(query: string, limit: number | undefined): PickerItem[] {
+    const scoped = this.scopedCandidates(query);
+    if (scoped !== undefined) {
+      return rankCandidates(
+        scoped.candidates,
+        scoped.residualQuery,
+        limit,
+        () => this.indexForScope(scoped.directory, scoped.candidates)
+      );
+    }
+
+    const literalHits = this.literalRank(query, limit);
+    if (literalHits !== undefined) {
+      return literalHits;
+    }
+
+    return rankCandidates(this.source, query, limit, () =>
+      this.indexForGlobal()
+    );
+  }
+
+  private scopedCandidates(query: string):
+    | {
+        readonly directory: string;
+        readonly residualQuery: string;
+        readonly candidates: readonly FileCandidate[];
+      }
+    | undefined {
+    const slash = query.lastIndexOf("/");
+    if (slash === -1) {
+      return undefined;
+    }
+
+    const directory = query.slice(0, slash);
+    const candidates = this.childrenByDirectory.get(directory);
+    if (candidates === undefined) {
+      return undefined;
+    }
+
+    return {
+      directory,
+      residualQuery: query.slice(slash + 1),
+      candidates,
+    };
+  }
+
+  private indexForScope(
+    directory: string,
+    candidates: readonly FileCandidate[]
+  ): FuzzyIndex<FileCandidate> {
+    const cached = this.scopedIndexes.get(directory);
+    if (cached !== undefined) {
+      return cached;
+    }
+
+    const index = prepareIndex(candidates, (candidate) =>
+      basename(candidate.insertPath)
+    );
+    this.scopedIndexes.set(directory, index);
+    return index;
+  }
+
+  private indexForGlobal(): FuzzyIndex<FileCandidate> {
+    this.globalIndex ??= prepareIndex(
+      this.source,
+      (candidate) => candidate.matchHaystack
+    );
+    return this.globalIndex;
+  }
+
+  private literalRank(
+    query: string,
+    limit: number | undefined
+  ): PickerItem[] | undefined {
+    const needle = query.trim().toLocaleLowerCase();
+    if (needle.length === 0 || query.includes("/")) {
+      return undefined;
+    }
+
+    const prefixHits: FileCandidate[] = [];
+    const substringHits: FileCandidate[] = [];
+    const limitSize = limit ?? Infinity;
+
+    for (const { candidate, haystackLower, nameStart } of this.loweredSource) {
+      if (
+        haystackLower.startsWith(needle) ||
+        haystackLower.startsWith(needle, nameStart)
+      ) {
+        prefixHits.push(candidate);
+      } else if (
+        substringHits.length < limitSize &&
+        haystackLower.includes(needle)
+      ) {
+        substringHits.push(candidate);
+      }
+
+      // Only prefix hits may end the scan early: a late prefix must not lose to an earlier substring.
+      if (prefixHits.length >= limitSize) {
+        break;
+      }
+    }
+
+    const hitCount = prefixHits.length + substringHits.length;
+    if (hitCount === 0) {
+      return undefined;
+    }
+
+    if (
+      prefixHits.length === 0 &&
+      needle.length >= GLOBAL_FUZZY_QUERY_MIN_LENGTH &&
+      hitCount < limitSize
+    ) {
+      return undefined;
+    }
+
+    return [...prefixHits, ...substringHits]
+      .slice(0, limit)
+      .map((candidate) => toItem(candidate));
+  }
+}
+
+export async function rank(
+  query: string,
+  options: FileRankOptions
+): Promise<PickerItem[] | undefined> {
+  if (isAbsoluteQuery(query)) {
+    const { candidates, residualQuery } = await loadAbsolute({ query });
+    return rankCandidates(candidates, residualQuery, options.limit);
+  }
+
+  if (options.cachedRelative === undefined) {
+    return undefined;
+  }
+
+  return indexFor(options.cachedRelative).rank(query, options.limit);
+}
+
+const rankCandidates = (
+  candidates: readonly FileCandidate[],
+  query: string,
+  limit: number | undefined,
+  index: () => FuzzyIndex<FileCandidate> = () => prepareIndex(candidates)
+): PickerItem[] => {
+  if (query.trim().length === 0) {
+    return candidates.slice(0, limit).map((candidate) => toItem(candidate));
+  }
+
+  const hits = index().find(query, { limit });
+  return hits.map((hit) => toItem(hit.item));
+};
+
+const prepareIndex = (
+  candidates: readonly FileCandidate[],
+  haystack: (candidate: FileCandidate) => string = (candidate) =>
+    candidate.matchHaystack
+): FuzzyIndex<FileCandidate> => {
+  const fuzzy: FuzzyCandidate<FileCandidate>[] = candidates.map(
+    (candidate) => ({
+      item: candidate,
+      haystacks: [haystack(candidate)],
+    })
+  );
+  return FuzzyMatcher.prepare(fuzzy);
+};
+
+const toItem = (candidate: FileCandidate): PickerItem => {
+  const suffix = candidate.isDirectory ? "/" : "";
+  const value = `${candidate.insertPath}${suffix}`;
+  const label = `${basename(candidate.insertPath)}${suffix}`;
+  return {
+    value,
+    label,
+    description: `${candidate.displayPath}${suffix}`,
+  };
+};

package/packages/core/src/picker/token.ts

@@ -0,0 +1,70 @@
+/** Which picker the caret is sitting in, if any. */
+export type PickerToken = {
+  readonly kind: "file" | "command";
+  readonly query: string;
+  /** Offset of the sigil itself, so a completion replaces it too. */
+  readonly start: number;
+};
+
+export const AT_PREFIX = /(?:^|\s)@(\S*)$/;
+export const SLASH_PREFIX = /^\/(\S*)$/;
+
+/** Offset of the sigil in an `AT_PREFIX` match, which also swallows the whitespace before it. */
+export function sigilOffset(match: RegExpMatchArray): number {
+  const matched = match[0] ?? "";
+  return (match.index ?? 0) + (matched.startsWith("@") ? 0 : 1);
+}
+
+export function isDirectoryItem(item: { readonly label: string }): boolean {
+  return item.label.endsWith("/");
+}
+
+export function activeToken(
+  text: string,
+  caret: number
+): PickerToken | undefined {
+  const lineStart = text.lastIndexOf("\n", Math.max(0, caret - 1)) + 1;
+  const beforeCaret = text.slice(lineStart, caret);
+
+  const slash = SLASH_PREFIX.exec(beforeCaret);
+  if (slash) {
+    return { kind: "command", query: slash[1] ?? "", start: lineStart };
+  }
+
+  const at = AT_PREFIX.exec(beforeCaret);
+  if (!at) {
+    return undefined;
+  }
+  return {
+    kind: "file",
+    query: at[1] ?? "",
+    start: lineStart + sigilOffset(at),
+  };
+}
+
+export function tokenKey(token: PickerToken | undefined): string {
+  return token === undefined ? "" : `${token.kind}\u0000${token.query}`;
+}
+
+export type Completion = {
+  readonly text: string;
+  readonly caret: number;
+  /** A directory keeps the picker open so the next segment can be drilled into. */
+  readonly keepOpen: boolean;
+};
+
+export function applyCompletion(
+  text: string,
+  caret: number,
+  token: PickerToken,
+  item: { readonly value: string; readonly label: string }
+): Completion {
+  const inserted = token.kind === "file" ? `@${item.value}` : `${item.value} `;
+  const head = text.slice(0, token.start);
+  const tail = text.slice(caret);
+  return {
+    text: `${head}${inserted}${tail}`,
+    caret: head.length + inserted.length,
+    keepOpen: token.kind === "file" && isDirectoryItem(item),
+  };
+}