pim-agent 0.9.0 → 0.11.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/PiExtensions.ts

@@ -0,0 +1,228 @@
+import {
+  DefaultPackageManager,
+  type PackageSource,
+  type ResolvedResource,
+  SettingsManager,
+} from "@earendil-works/pi-coding-agent";
+import { basename, dirname, extname, relative } from "node:path";
+
+import { ExtensionToggles } from "./ExtensionToggles";
+import { Fs } from "./Fs";
+import { Paths } from "./Paths";
+
+/**
+ * Every origin an entry comes from, in the order a reader meets them: the
+ * roster is sorted by it, and a pane groups what it is handed without
+ * restating it.
+ */
+const EXTENSION_GROUPS = ["pim", "package", "user", "project"] as const;
+
+export type ExtensionGroup = (typeof EXTENSION_GROUPS)[number];
+
+export type ExtensionEntry = {
+  readonly id: string;
+  readonly label: string;
+  readonly group: ExtensionGroup;
+  readonly enabled: boolean;
+  /** Whether this process will write the toggle; a project-scoped entry is listed but not switched. */
+  readonly writable: boolean;
+};
+
+export type ExtensionScope = {
+  readonly cwd: string;
+  readonly agentDir: string;
+};
+
+type Resolution = {
+  readonly extensions: readonly ResolvedResource[];
+  readonly settingsManager: SettingsManager;
+};
+
+type PackageFilter = Exclude<PackageSource, string>;
+
+const FILTER_KEYS = ["extensions", "skills", "prompts", "themes"] as const;
+
+const writes = Fs.serialised();
+
+async function list(scope: ExtensionScope): Promise<readonly ExtensionEntry[]> {
+  const [off, { extensions }] = await Promise.all([
+    ExtensionToggles.disabled(),
+    resolve(scope),
+  ]);
+  const disabled = new Set(off);
+  const pim = ExtensionToggles.WEB.map((allowed) =>
+    pimEntry(allowed, !disabled.has(allowed.name))
+  );
+  const pi = extensions
+    .filter((resource) => resource.metadata.scope !== "temporary")
+    .map(piEntry)
+    .sort(byGroupThenLabel);
+  return [...pim, ...pi];
+}
+
+async function setEnabled(
+  id: string,
+  enabled: boolean,
+  scope: ExtensionScope
+): Promise<void> {
+  const pim = ExtensionToggles.WEB.find((entry) => `pim:${entry.name}` === id);
+  if (pim) {
+    await ExtensionToggles.setDisabled(pim.name, !enabled);
+    return;
+  }
+  if (!id.startsWith("pi:")) {
+    throw new Error(`Unknown extension "${id}"`);
+  }
+  await writes.run(() => writePiToggle(id.slice("pi:".length), enabled, scope));
+}
+
+// A fresh SettingsManager per write: `setExtensionPaths` persists its in-memory
+// copy, which another process may have superseded since we last read it.
+async function writePiToggle(
+  path: string,
+  enabled: boolean,
+  scope: ExtensionScope
+): Promise<void> {
+  const { extensions, settingsManager } = await resolve(scope);
+  const resource = extensions.find((candidate) => candidate.path === path);
+  if (!resource) {
+    throw new Error(`Unknown extension "pi:${path}"`);
+  }
+  const { metadata } = resource;
+  if (metadata.scope !== "user") {
+    throw new Error(
+      `"${path}" is ${metadata.scope}-scoped and cannot be switched from here`
+    );
+  }
+  if (metadata.origin === "package") {
+    togglePackage(
+      settingsManager,
+      metadata.source,
+      relative(metadata.baseDir ?? dirname(path), path),
+      enabled
+    );
+  } else {
+    toggleTopLevel(
+      settingsManager,
+      relative(metadata.baseDir ?? scope.agentDir, path),
+      enabled
+    );
+  }
+  await settingsManager.flush();
+  const failure = settingsManager.drainErrors()[0];
+  if (failure) {
+    throw new Error(`Failed to write pi settings: ${failure.error.message}`);
+  }
+}
+
+function toggleTopLevel(
+  settingsManager: SettingsManager,
+  pattern: string,
+  enabled: boolean
+): void {
+  const current = settingsManager.getGlobalSettings().extensions ?? [];
+  settingsManager.setExtensionPaths(withPattern(current, pattern, enabled));
+}
+
+function togglePackage(
+  settingsManager: SettingsManager,
+  source: string,
+  pattern: string,
+  enabled: boolean
+): void {
+  const packages = [...(settingsManager.getGlobalSettings().packages ?? [])];
+  const index = packages.findIndex((entry) => sourceOf(entry) === source);
+  const entry = packages[index];
+  if (entry === undefined) {
+    throw new Error(`No configured package provides "${source}"`);
+  }
+  const pkg: PackageFilter =
+    typeof entry === "string" ? { source: entry } : { ...entry };
+  const updated = withPattern(pkg.extensions ?? [], pattern, enabled);
+  pkg.extensions = updated.length > 0 ? updated : undefined;
+  packages[index] = FILTER_KEYS.some((key) => pkg[key] !== undefined)
+    ? pkg
+    : pkg.source;
+  settingsManager.setPackages(packages);
+}
+
+function withPattern(
+  current: readonly string[],
+  pattern: string,
+  enabled: boolean
+): string[] {
+  const kept = current.filter((entry) => stripMarker(entry) !== pattern);
+  return [...kept, `${enabled ? "+" : "-"}${pattern}`];
+}
+
+function stripMarker(entry: string): string {
+  return /^[!+-]/.test(entry) ? entry.slice(1) : entry;
+}
+
+function sourceOf(entry: PackageSource): string {
+  return typeof entry === "string" ? entry : entry.source;
+}
+
+async function resolve(scope: ExtensionScope): Promise<Resolution> {
+  const { cwd, agentDir } = scope;
+  const settingsManager = SettingsManager.create(cwd, agentDir);
+  const manager = new DefaultPackageManager({
+    cwd,
+    agentDir,
+    settingsManager,
+  });
+  // Without an answer, pi npm-installs every missing or drifted package, so a
+  // bare listing request would fire off an install.
+  const resolved = await manager.resolve(async () => "skip");
+  return { extensions: resolved.extensions, settingsManager };
+}
+
+function pimEntry(
+  allowed: (typeof ExtensionToggles.WEB)[number],
+  enabled: boolean
+): ExtensionEntry {
+  return {
+    id: `pim:${allowed.name}`,
+    label: allowed.label,
+    group: "pim",
+    enabled,
+    writable: true,
+  };
+}
+
+function piEntry(resource: ResolvedResource): ExtensionEntry {
+  const { path, metadata } = resource;
+  const fromPackage = metadata.origin === "package";
+  const group = fromPackage
+    ? "package"
+    : metadata.scope === "project"
+      ? "project"
+      : "user";
+  return {
+    id: `pi:${path}`,
+    label: fromPackage
+      ? metadata.source.replace(/^(?:npm|git):/, "")
+      : fileLabel(path),
+    group,
+    enabled: resource.enabled,
+    // Scope, not group: a package a project configures is written to the repo's
+    // settings, which a browser toggle never touches.
+    writable: metadata.scope === "user",
+  };
+}
+
+function fileLabel(path: string): string {
+  const base = basename(path, extname(path));
+  return base === "index" ? basename(dirname(path)) : base;
+}
+
+function byGroupThenLabel(left: ExtensionEntry, right: ExtensionEntry): number {
+  const byGroup =
+    EXTENSION_GROUPS.indexOf(left.group) -
+    EXTENSION_GROUPS.indexOf(right.group);
+  return byGroup === 0
+    ? Paths.compare(left.label.toLowerCase(), right.label.toLowerCase())
+    : byGroup;
+}
+
+export const PiExtensions = { list, setEnabled };

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 };