pim-agent 0.9.0 → 0.10.0

package/packages/core/src/shared/GitMonitor.ts

@@ -0,0 +1,221 @@
+import { join } from "node:path";
+
+import { FileWatch } from "./FileWatch";
+import { Git, type GitOutcome, type GitState } from "./Git";
+
+export type GitListener = (state: GitState) => void;
+
+/**
+ * What one operation under the lock says, and what it made where it made
+ * anything: a commit has a sha to hand back, a checkout has only its outcome.
+ */
+export type GitRun<T = never> = GitOutcome & { readonly value?: T };
+
+export type GitMonitorDeps = {
+  /** How long a fetch stands before another is worth its round trip. */
+  readonly fetchTtlMs?: number;
+  /** How often a watched repository is read for the edits `.git` never hears about. */
+  readonly pollMs?: number;
+  readonly status?: (cwd: string) => Promise<GitState>;
+  readonly fetch?: (cwd: string) => Promise<GitOutcome>;
+};
+
+type Entry = {
+  readonly cwd: string;
+  readonly listeners: Set<GitListener>;
+  state: GitState;
+  stop: (() => void) | undefined;
+  inFlight: Promise<GitState> | undefined;
+  pending: boolean;
+  fetchedAt: number;
+  locked: boolean;
+  /** How long the last read took, and when it ended: what the poll paces itself by. */
+  readMs: number;
+  readAt: number;
+};
+
+/** A checkout writes half the repository; one read has to stand for the burst. */
+const DEBOUNCE_MS = 200;
+
+const FETCH_TTL_MS = 30_000;
+
+/** A worktree edit touches nothing under `.git`, so the watch alone would never see it. */
+const POLL_MS = 2_000;
+
+/** A repository too big to read in a tick is read this many times its own cost apart. */
+const BACKOFF = 4;
+
+function same(a: GitState, b: GitState): boolean {
+  return (
+    a.branch === b.branch &&
+    a.dirtyCount === b.dirtyCount &&
+    a.ahead === b.ahead &&
+    a.behind === b.behind &&
+    a.revision === b.revision
+  );
+}
+
+/**
+ * One reader of one repository, however many sessions share it: it watches
+ * `.git` so a commit anywhere reaches every surface, coalesces the burst a
+ * checkout makes into a single read, and serialises the operations that write,
+ * which cannot run two at a time over one index.
+ */
+export class GitMonitor {
+  private readonly entries = new Map<string, Entry>();
+  private readonly deps: GitMonitorDeps;
+
+  public constructor(deps: GitMonitorDeps = {}) {
+    this.deps = deps;
+  }
+
+  /** Follows `cwd` until the returned stop is called; the listener hears only changes, after a read of its own. */
+  public watch(cwd: string, listener: GitListener): () => void {
+    const entry = this.entryOf(cwd);
+    entry.listeners.add(listener);
+    entry.stop ??= this.follow(entry);
+    void this.read(entry, false);
+    return () => {
+      entry.listeners.delete(listener);
+      if (entry.listeners.size === 0) {
+        entry.stop?.();
+        entry.stop = undefined;
+      }
+    };
+  }
+
+  /** The last state read, without waiting: a caller painting a frame takes what is known now. */
+  public stateOf(cwd: string): GitState {
+    return this.entries.get(cwd)?.state ?? Git.EMPTY;
+  }
+
+  /** Re-reads now; `fetch` also asks the remote, which is what ahead and behind are counted against. */
+  public async refresh(
+    cwd: string,
+    options: { readonly fetch?: boolean } = {}
+  ): Promise<GitState> {
+    const entry = this.entryOf(cwd);
+    const ttl = this.deps.fetchTtlMs ?? FETCH_TTL_MS;
+    if (
+      options.fetch === true &&
+      !entry.locked &&
+      Date.now() - entry.fetchedAt > ttl
+    ) {
+      entry.fetchedAt = Date.now();
+      await (this.deps.fetch ?? Git.fetch)(cwd).catch(() => undefined);
+    }
+    return await this.read(entry);
+  }
+
+  /** Runs one writing operation over `cwd`, refusing a second while it lasts and re-reading once it ends. */
+  public async run<T = never>(
+    cwd: string,
+    operation: () => Promise<GitRun<T>>
+  ): Promise<GitRun<T>> {
+    const entry = this.entryOf(cwd);
+    if (entry.locked) {
+      return {
+        ok: false,
+        error: "another git operation is already running in this directory",
+      };
+    }
+    entry.locked = true;
+    try {
+      return await operation();
+    } finally {
+      entry.locked = false;
+      await this.read(entry);
+    }
+  }
+
+  public dispose(): void {
+    for (const entry of this.entries.values()) {
+      entry.stop?.();
+    }
+    this.entries.clear();
+  }
+
+  private entryOf(cwd: string): Entry {
+    const found = this.entries.get(cwd);
+    if (found) {
+      return found;
+    }
+    const entry: Entry = {
+      cwd,
+      listeners: new Set(),
+      state: Git.EMPTY,
+      stop: undefined,
+      inFlight: undefined,
+      pending: false,
+      fetchedAt: 0,
+      locked: false,
+      readMs: 0,
+      readAt: 0,
+    };
+    this.entries.set(cwd, entry);
+    return entry;
+  }
+
+  private follow(entry: Entry): () => void {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    const stop = FileWatch.directory(join(entry.cwd, ".git"), () => {
+      clearTimeout(timer);
+      timer = setTimeout(() => {
+        void this.read(entry);
+      }, DEBOUNCE_MS);
+      timer.unref?.();
+    });
+    // `false`: a read already running is fresh enough for a tick, and a slow
+    // status must never queue another behind itself.
+    const poll = setInterval(() => {
+      if (Date.now() - entry.readAt < entry.readMs * BACKOFF) {
+        return;
+      }
+      void this.read(entry, false);
+    }, this.deps.pollMs ?? POLL_MS);
+    poll.unref?.();
+    return () => {
+      clearTimeout(timer);
+      clearInterval(poll);
+      stop();
+    };
+  }
+
+  /** `restart` re-reads behind a read already running: a change cannot be answered by a read that predates it, a new subscriber can. */
+  private read(entry: Entry, restart = true): Promise<GitState> {
+    if (entry.inFlight) {
+      entry.pending ||= restart;
+      return entry.inFlight;
+    }
+    const run = (async (): Promise<GitState> => {
+      const started = Date.now();
+      try {
+        let next = entry.state;
+        do {
+          entry.pending = false;
+          next = await (this.deps.status ?? Git.fetchStatus)(entry.cwd);
+        } while (entry.pending);
+        this.settle(entry, next);
+        return next;
+      } catch {
+        return entry.state;
+      } finally {
+        entry.inFlight = undefined;
+        entry.readAt = Date.now();
+        entry.readMs = entry.readAt - started;
+      }
+    })();
+    entry.inFlight = run;
+    return run;
+  }
+
+  private settle(entry: Entry, next: GitState): void {
+    if (same(entry.state, next)) {
+      return;
+    }
+    entry.state = next;
+    for (const listener of entry.listeners) {
+      listener(next);
+    }
+  }
+}

package/packages/core/src/shared/Levenshtein.ts

@@ -27,4 +27,57 @@ function distance(left: string, right: string): number {
   return previous[right.length] ?? 0;
 }
 
-export const Levenshtein = { distance };
+/**
+ * Damerau–Levenshtein, where a transposition is one edit rather than two, and
+ * a pair that cannot reach `max` answers `max + 1` without finishing the
+ * matrix — the shape a vocabulary scan wants, since almost every term it asks
+ * about is nowhere near.
+ */
+function damerau(left: string, right: string, max: number): number {
+  const over = max + 1;
+  if (left === right) {
+    return 0;
+  }
+  if (Math.abs(left.length - right.length) > max) {
+    return over;
+  }
+
+  const width = right.length + 1;
+  let before = Array.from({ length: width }, () => 0);
+  let previous = Array.from({ length: width }, (_, index) => index);
+  let current = Array.from({ length: width }, () => 0);
+
+  for (let leftIndex = 1; leftIndex <= left.length; leftIndex += 1) {
+    current[0] = leftIndex;
+    let best = leftIndex;
+
+    for (let rightIndex = 1; rightIndex <= right.length; rightIndex += 1) {
+      const cost = left[leftIndex - 1] === right[rightIndex - 1] ? 0 : 1;
+      let value = Math.min(
+        previous[rightIndex]! + 1,
+        current[rightIndex - 1]! + 1,
+        previous[rightIndex - 1]! + cost
+      );
+      if (
+        leftIndex > 1 &&
+        rightIndex > 1 &&
+        left[leftIndex - 1] === right[rightIndex - 2] &&
+        left[leftIndex - 2] === right[rightIndex - 1]
+      ) {
+        value = Math.min(value, before[rightIndex - 2]! + 1);
+      }
+      current[rightIndex] = value;
+      best = Math.min(best, value);
+    }
+
+    if (best > max) {
+      return over;
+    }
+    [before, previous, current] = [previous, current, before];
+  }
+
+  const found = previous[right.length]!;
+  return found > max ? over : found;
+}
+
+export const Levenshtein = { distance, damerau };

package/packages/core/src/shared/Proc.ts

@@ -1,12 +1,17 @@
 export type ProcOptions = {
   readonly cwd?: string | undefined;
   readonly stdout?: "pipe" | "inherit";
+  /** Merged over the process environment; a key set to `undefined` is removed from it. */
+  readonly env?: Readonly<Record<string, string | undefined>>;
+  /** Kills the child once it elapses, answering `timedOut`. */
+  readonly timeoutMs?: number;
 };
 
 export type ProcResult = {
   readonly code: number;
   readonly stdout: string;
   readonly stderr: string;
+  readonly timedOut: boolean;
 };
 
 async function run(
@@ -17,14 +22,29 @@ async function run(
     cwd: options.cwd,
     stdout: options.stdout ?? "pipe",
     stderr: "pipe",
+    // `undefined` is Bun's own "inherit this process's environment".
+    env:
+      options.env === undefined
+        ? undefined
+        : { ...process.env, ...options.env },
   });
+  let timedOut = false;
+  const timer =
+    options.timeoutMs === undefined
+      ? undefined
+      : setTimeout(() => {
+          timedOut = true;
+          proc.kill();
+        }, options.timeoutMs);
   const [stdout, stderr] = await Promise.all([
     proc.stdout instanceof ReadableStream
       ? new Response(proc.stdout).text()
       : "",
     new Response(proc.stderr).text(),
   ]);
-  return { code: await proc.exited, stdout, stderr };
+  const code = await proc.exited;
+  clearTimeout(timer);
+  return { code, stdout, stderr, timedOut };
 }
 
 export const Proc = { run };