pim-agent 0.0.1 → 0.9.0

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

@@ -0,0 +1,9 @@
+function describe(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function isAbort(error: unknown): boolean {
+  return error instanceof Error && error.name === "AbortError";
+}
+
+export const Errors = { describe, isAbort };

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

@@ -0,0 +1,130 @@
+import type { ExtensionFactory } from "@earendil-works/pi-coding-agent";
+
+import { PimSettings } from "./PimSettings";
+
+// Pi's `enabled` filter covers disk paths only, never inline factories: pim owns this roster.
+const EXTENSIONS = {
+  _init: "Splash screen, runtime guard, /clear",
+  "apply-patch": "apply_patch tool",
+  bash: "bash tool",
+  "command-picker": "Slash command and skill autocomplete",
+  edit: "edit tool",
+  "file-picker": "@-path autocomplete",
+  footer: "Powerline footer",
+  glob: "glob tool",
+  grep: "grep tool",
+  pim: "This menu",
+  read: "read tool",
+  "session-lease": "Cross-surface turn lease and /sync",
+  subagent: "subagent tool",
+  "system-prompt": "Pim system prompt",
+  todo: "todo tool",
+  tps: "Per-turn decode/prefill tps report",
+  "web-fetch": "web_fetch tool",
+  "web-search": "web_search tool",
+  "working-indicator": "Animated working indicator",
+  write: "write tool",
+} as const;
+
+export type PimExtensionName = keyof typeof EXTENSIONS;
+
+const NAMES = Object.keys(EXTENSIONS) as readonly PimExtensionName[];
+
+const DEFAULT_DISABLED: readonly PimExtensionName[] = ["todo", "tps"];
+
+const REQUIRED: readonly PimExtensionName[] = ["_init", "pim", "session-lease"];
+
+function isRequired(name: string): boolean {
+  return (REQUIRED as readonly string[]).includes(name);
+}
+
+function isKnown(name: string): name is PimExtensionName {
+  return name in EXTENSIONS;
+}
+
+function describe(name: PimExtensionName): string {
+  return EXTENSIONS[name];
+}
+
+// Gate inside the factory, not around the roster: pi re-invokes factories on `ctx.reload()`.
+function gate(
+  name: PimExtensionName,
+  factory: ExtensionFactory
+): ExtensionFactory {
+  return async (pi) => {
+    if (await isDisabled(name)) {
+      return;
+    }
+    await factory(pi);
+  };
+}
+
+async function disabled(): Promise<readonly PimExtensionName[]> {
+  const { toggles } = await PimSettings.get("extensions");
+  return NAMES.filter((name) => !enabled(name, toggles));
+}
+
+async function isDisabled(name: string): Promise<boolean> {
+  if (!isKnown(name)) {
+    return false;
+  }
+  const { toggles } = await PimSettings.get("extensions");
+  return !enabled(name, toggles);
+}
+
+// Serialized: each call is a read-modify-write of the same record.
+async function setDisabled(name: string, isOff: boolean): Promise<void> {
+  if (!isKnown(name)) {
+    throw new Error(`Unknown pim extension "${name}"`);
+  }
+  if (isOff && isRequired(name)) {
+    throw new Error(`"${name}" is required by pim and cannot be disabled`);
+  }
+  await PimSettings.update("extensions", ({ toggles }) => {
+    const next = { ...toggles };
+    if (!isOff === defaultEnabled(name)) {
+      delete next[name];
+    } else {
+      next[name] = !isOff;
+    }
+    return { toggles: next };
+  });
+}
+
+async function toggle(
+  name: string
+): Promise<{ readonly name: PimExtensionName; readonly disabled: boolean }> {
+  if (!isKnown(name)) {
+    throw new Error(`Unknown pim extension "${name}"`);
+  }
+  const isOff = !(await isDisabled(name));
+  await setDisabled(name, isOff);
+  return { name, disabled: isOff };
+}
+
+function defaultEnabled(name: PimExtensionName): boolean {
+  return !DEFAULT_DISABLED.includes(name);
+}
+
+function enabled(
+  name: PimExtensionName,
+  toggles: Readonly<Record<string, boolean>>
+): boolean {
+  if (isRequired(name)) {
+    return true;
+  }
+  return toggles[name] ?? defaultEnabled(name);
+}
+
+export const ExtensionToggles = {
+  REQUIRED,
+  NAMES,
+  isRequired,
+  isKnown,
+  describe,
+  gate,
+  disabled,
+  isDisabled,
+  setDisabled,
+  toggle,
+};

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

@@ -0,0 +1,361 @@
+import { readdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import ignore, { type Ignore } from "ignore";
+
+const CONCURRENCY = 32;
+
+export type EnumerateOptions = {
+  readonly includeDotfiles?: boolean;
+  readonly includeIgnored?: boolean;
+};
+
+type StackEntry = {
+  readonly abs: string;
+  readonly rel: string;
+  readonly inRepo: boolean;
+  readonly repoRootAbs: string;
+  readonly ignoreRules: string[];
+  readonly matcher: Ignore;
+};
+
+const EMPTY_MATCHER = ignore();
+
+type WalkContext = {
+  includeDotfiles: boolean;
+  useIgnore: boolean;
+  globalGitIgnore: string | undefined;
+  stack: StackEntry[];
+  result: string[];
+};
+
+async function readIgnoreFile(path: string): Promise<string | undefined> {
+  try {
+    return await Bun.file(path).text();
+  } catch {
+    return undefined;
+  }
+}
+
+function globalGitIgnorePath(): string | undefined {
+  const xdgConfigHome = process.env.XDG_CONFIG_HOME;
+  if (xdgConfigHome !== undefined && xdgConfigHome !== "") {
+    return join(xdgConfigHome, "git", "ignore");
+  }
+
+  const home = process.env.HOME;
+  if (home !== undefined && home !== "") {
+    return join(home, ".config", "git", "ignore");
+  }
+
+  return undefined;
+}
+
+function relFromBase(absPath: string, baseAbs: string): string | undefined {
+  if (absPath === baseAbs) {
+    return "";
+  }
+
+  const prefix = baseAbs.endsWith("/") ? baseAbs : `${baseAbs}/`;
+  if (!absPath.startsWith(prefix)) {
+    return undefined;
+  }
+
+  return absPath.slice(prefix.length);
+}
+
+function ignoreVerdict(
+  matcher: Ignore,
+  repoRootAbs: string,
+  absPath: string,
+  isDirectory: boolean
+): { ignored: boolean; unignored: boolean } {
+  const path = relFromBase(absPath, repoRootAbs);
+  if (path === undefined || path === "") {
+    return { ignored: false, unignored: false };
+  }
+  const result = matcher.test(isDirectory ? `${path}/` : path);
+  return { ignored: result.ignored, unignored: result.unignored };
+}
+
+function pushRules(out: string[], content: string): void {
+  for (const line of content.split(/\r?\n/)) {
+    if (line.trim() === "" || line.startsWith("#")) {
+      continue;
+    }
+    out.push(line);
+  }
+}
+
+// Gitignore anchoring: a pattern containing a non-trailing slash only gains the prefix; one
+// without also gains `**/`, or it stops matching below its own directory.
+function reanchorRules(
+  content: string,
+  basePrefix: string,
+  out: string[]
+): void {
+  for (const line of content.split(/\r?\n/)) {
+    if (line.trim() === "" || line.startsWith("#")) {
+      continue;
+    }
+
+    let negated = false;
+    let pattern = line;
+    if (pattern.startsWith("!")) {
+      negated = true;
+      pattern = pattern.slice(1);
+    }
+    if (pattern === "") {
+      continue;
+    }
+
+    let body: string;
+    if (pattern.startsWith("/")) {
+      body = basePrefix + pattern.slice(1);
+    } else {
+      const core = pattern.endsWith("/") ? pattern.slice(0, -1) : pattern;
+      body = core.includes("/")
+        ? basePrefix + pattern
+        : basePrefix + "**/" + pattern;
+    }
+
+    out.push(negated ? `!${body}` : body);
+  }
+}
+
+async function findRepoRoot(start: string): Promise<string | undefined> {
+  let dir = start;
+  for (;;) {
+    if (await Bun.file(join(dir, ".git")).exists()) {
+      return dir;
+    }
+    const parent = dirname(dir);
+    if (parent === dir) {
+      return undefined;
+    }
+    dir = parent;
+  }
+}
+
+// Precedence order: global excludes, then .git/info/exclude, then the repo's own .gitignore.
+async function repoBaseRules(
+  repoAbs: string,
+  globalGitIgnore: string | undefined
+): Promise<string[]> {
+  const rules: string[] = [];
+  if (globalGitIgnore !== undefined) {
+    pushRules(rules, globalGitIgnore);
+  }
+  const [infoExclude, repoGitIgnore] = await Promise.all([
+    readIgnoreFile(join(repoAbs, ".git", "info", "exclude")),
+    readIgnoreFile(join(repoAbs, ".gitignore")),
+  ]);
+  if (infoExclude !== undefined) {
+    pushRules(rules, infoExclude);
+  }
+  if (repoGitIgnore !== undefined) {
+    pushRules(rules, repoGitIgnore);
+  }
+  return rules;
+}
+
+async function processDir(
+  ctx: WalkContext,
+  currentDir: StackEntry
+): Promise<void> {
+  let entries;
+  try {
+    entries = await readdir(currentDir.abs, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  let inRepo = currentDir.inRepo;
+  let repoRootAbs = currentDir.repoRootAbs;
+  let rules = currentDir.ignoreRules;
+  let matcher = currentDir.matcher;
+
+  if (ctx.useIgnore) {
+    const hasDotGit = entries.some((e) => e.name === ".git");
+    if (hasDotGit) {
+      // A .git is a repo boundary: a child repo must not inherit its parent's rules.
+      inRepo = true;
+      repoRootAbs = currentDir.abs;
+      rules = await repoBaseRules(currentDir.abs, ctx.globalGitIgnore);
+      matcher = ignore().add(rules);
+    } else if (inRepo) {
+      const hasGitIgnore = entries.some(
+        (e) => e.isFile() && e.name === ".gitignore"
+      );
+      if (hasGitIgnore) {
+        const content = await readIgnoreFile(
+          join(currentDir.abs, ".gitignore")
+        );
+        if (content !== undefined) {
+          const dirRel = relFromBase(currentDir.abs, repoRootAbs);
+          const next = rules.slice();
+          if (dirRel === undefined || dirRel === "") {
+            pushRules(next, content);
+          } else {
+            reanchorRules(content, `${dirRel}/`, next);
+          }
+          rules = next;
+          matcher = ignore().add(rules);
+        }
+      }
+    }
+  }
+
+  for (const entry of entries) {
+    const name = entry.name;
+    const relPath = currentDir.rel === "" ? name : `${currentDir.rel}/${name}`;
+    const isDir = entry.isDirectory();
+    const isSymlink = entry.isSymbolicLink();
+
+    if (name === ".git") {
+      continue;
+    }
+
+    const needsAbs = isDir || (ctx.useIgnore && inRepo);
+    const childAbs = needsAbs ? join(currentDir.abs, name) : "";
+
+    const verdict =
+      ctx.useIgnore && inRepo
+        ? ignoreVerdict(matcher, repoRootAbs, childAbs, isDir)
+        : { ignored: false, unignored: false };
+
+    // A `!` negation re-includes a dotfile, as in git/fd.
+    if (
+      !ctx.includeDotfiles &&
+      name.charCodeAt(0) === 0x2e /* "." */ &&
+      !verdict.unignored
+    ) {
+      continue;
+    }
+
+    if (verdict.ignored) {
+      continue;
+    }
+
+    if (isDir) {
+      // Never follow symlinked dirs: cycles.
+      if (isSymlink) {
+        continue;
+      }
+
+      ctx.stack.push({
+        abs: childAbs,
+        rel: relPath,
+        inRepo,
+        repoRootAbs,
+        ignoreRules: rules,
+        matcher,
+      });
+      continue;
+    }
+
+    if (entry.isFile() || isSymlink) {
+      ctx.result.push(relPath);
+      continue;
+    }
+  }
+}
+
+// Refill from the shared stack on each completion; N worker loops would exit on the root-only
+// stack before any child was pushed and silently return a partial listing.
+function drain(ctx: WalkContext): Promise<void> {
+  let inFlight = 0;
+  return new Promise<void>((resolve, reject) => {
+    const pump = (): void => {
+      while (inFlight < CONCURRENCY && ctx.stack.length > 0) {
+        const currentDir = ctx.stack.pop()!;
+        inFlight++;
+        processDir(ctx, currentDir).then(() => {
+          inFlight--;
+          pump();
+        }, reject);
+      }
+      if (inFlight === 0 && ctx.stack.length === 0) {
+        resolve();
+      }
+    };
+    pump();
+  });
+}
+
+/** All files under `root` as root-relative POSIX paths; `.gitignore` is honored only inside a repo. */
+async function enumerate(
+  root: string,
+  opts?: EnumerateOptions
+): Promise<string[]> {
+  const includeDotfiles = opts?.includeDotfiles ?? false;
+  const includeIgnored = opts?.includeIgnored ?? false;
+  const useIgnore = !includeIgnored;
+
+  let globalGitIgnore: string | undefined;
+  if (useIgnore) {
+    const pathname = globalGitIgnorePath();
+    globalGitIgnore =
+      pathname === undefined ? undefined : await readIgnoreFile(pathname);
+  }
+
+  // Seed rules from a repo enclosing `root`; `root`'s own .gitignore is added by processDir.
+  let initialInRepo = false;
+  let initialRepoRootAbs = root;
+  let initialRules: string[] = [];
+  if (useIgnore) {
+    const repoRoot = await findRepoRoot(root);
+    if (repoRoot !== undefined && repoRoot !== root) {
+      initialInRepo = true;
+      initialRepoRootAbs = repoRoot;
+      initialRules = await repoBaseRules(repoRoot, globalGitIgnore);
+
+      // Shallowest first: gitignore precedence is by depth.
+      const intermediates: string[] = [];
+      let dir = dirname(root);
+      while (dir !== repoRoot && dir.length > repoRoot.length) {
+        intermediates.push(dir);
+        const parent = dirname(dir);
+        if (parent === dir) {
+          break;
+        }
+        dir = parent;
+      }
+      intermediates.reverse();
+
+      for (const dirAbs of intermediates) {
+        const content = await readIgnoreFile(join(dirAbs, ".gitignore"));
+        if (content !== undefined) {
+          const dirRel = relFromBase(dirAbs, repoRoot);
+          if (dirRel === undefined || dirRel === "") {
+            pushRules(initialRules, content);
+          } else {
+            reanchorRules(content, `${dirRel}/`, initialRules);
+          }
+        }
+      }
+    }
+  }
+
+  const ctx: WalkContext = {
+    includeDotfiles,
+    useIgnore,
+    globalGitIgnore,
+    stack: [
+      {
+        abs: root,
+        rel: "",
+        inRepo: initialInRepo,
+        repoRootAbs: initialRepoRootAbs,
+        ignoreRules: initialRules,
+        matcher: initialInRepo ? ignore().add(initialRules) : EMPTY_MATCHER,
+      },
+    ],
+    result: [],
+  };
+
+  await drain(ctx);
+
+  return ctx.result;
+}
+
+export const FileEnumerator = { enumerate };

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

@@ -0,0 +1,57 @@
+import { stat } from "node:fs/promises";
+import { join, resolve } from "node:path";
+import { FileEnumerator } from "./FileEnumerator";
+import { GlobExclusions } from "./GlobExclusions";
+
+export type FileScanOptions = {
+  readonly exclude?: readonly string[];
+  readonly includeDotfiles: boolean;
+  readonly includeIgnored: boolean;
+};
+
+async function scan(
+  root: string,
+  pattern: string,
+  options: FileScanOptions
+): Promise<readonly string[]> {
+  const absoluteRoot = resolve(root);
+  const relativePaths = await FileEnumerator.enumerate(absoluteRoot, {
+    includeDotfiles: options.includeDotfiles,
+    includeIgnored: options.includeIgnored,
+  });
+  const matcher = new Bun.Glob(await expandDirectory(absoluteRoot, pattern));
+  const excludes = GlobExclusions.compile(options.exclude);
+  const files: string[] = [];
+
+  for (const relativePath of relativePaths) {
+    if (!matcher.match(relativePath)) {
+      continue;
+    }
+    if (GlobExclusions.ignores(excludes, relativePath)) {
+      continue;
+    }
+    files.push(join(absoluteRoot, relativePath));
+  }
+
+  return files;
+}
+
+async function expandDirectory(
+  absoluteRoot: string,
+  pattern: string
+): Promise<string> {
+  const trimmed = pattern.replace(/^(?:\.\/)+/, "").replace(/\/+$/, "");
+
+  if (trimmed.length === 0) {
+    return "**/*";
+  }
+
+  try {
+    const metadata = await stat(resolve(absoluteRoot, trimmed));
+    return metadata.isDirectory() ? `${trimmed}/**/*` : pattern;
+  } catch {
+    return pattern;
+  }
+}
+
+export const FileScanner = { scan };

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

@@ -0,0 +1,107 @@
+import {
+  type FSWatcher,
+  readdirSync,
+  statSync,
+  watch as watchFs,
+} from "node:fs";
+import { basename, dirname, join } from "node:path";
+
+const POLL_MS = 1_000;
+
+function signatureOf(path: string): string {
+  const stats = statSync(path, { throwIfNoEntry: false });
+  return stats === undefined
+    ? "gone"
+    : `${stats.mtimeMs}:${stats.size}:${stats.ino}`;
+}
+
+/** Reports a change only once the path itself moved, so a watcher firing for its neighbours costs nothing. */
+function tracker(path: string, onChange: () => void): () => void {
+  let signature = signatureOf(path);
+  return (): void => {
+    const next = signatureOf(path);
+    if (next === signature) {
+      return;
+    }
+    signature = next;
+    onChange();
+  };
+}
+
+/**
+ * `fs.watch` reports nothing at all on some filesystems and network mounts, so
+ * the poll beside it is not optional. The poll also re-arms the watcher, which
+ * a directory that does not exist yet refuses to give.
+ */
+function follow(
+  watched: string,
+  entry: string | undefined,
+  onEvent: () => void,
+  onPoll: () => void,
+  pollMs: number
+): () => void {
+  let watcher: FSWatcher | undefined;
+  const arm = (): void => {
+    if (watcher !== undefined) {
+      return;
+    }
+    try {
+      watcher = watchFs(watched, { persistent: false }, (_event, changed) => {
+        if (entry === undefined || changed === null || changed === entry) {
+          onEvent();
+        }
+      });
+      watcher.on("error", () => {
+        watcher = undefined;
+      });
+    } catch {
+      watcher = undefined;
+    }
+  };
+  arm();
+  const timer = setInterval(() => {
+    arm();
+    onPoll();
+  }, pollMs);
+  timer.unref?.();
+  return (): void => {
+    clearInterval(timer);
+    try {
+      watcher?.close();
+    } catch {}
+  };
+}
+
+/** Fires when one file appears, grows, or goes away; the directory is watched, so the file need not exist yet. */
+function file(
+  path: string,
+  onChange: () => void,
+  pollMs: number = POLL_MS
+): () => void {
+  const check = tracker(path, onChange);
+  return follow(dirname(path), basename(path), check, check, pollMs);
+}
+
+/** Fires when a directory gains or loses an entry, or when anything inside it is written. */
+function directory(
+  path: string,
+  onChange: () => void,
+  pollMs: number = POLL_MS
+): () => void {
+  // Writing a file moves nothing on the directory holding it, so the poll answers only for entries coming and going.
+  return follow(path, undefined, onChange, tracker(path, onChange), pollMs);
+}
+
+/** The directories directly inside `path`, or none when it does not exist. */
+function subdirectories(path: string): readonly string[] {
+  try {
+    return readdirSync(path, { withFileTypes: true })
+      .filter((entry) => entry.isDirectory())
+      .map((entry) => join(path, entry.name));
+  } catch {
+    return [];
+  }
+}
+
+/** Watching paths other processes write: an `fs.watch` that may do nothing, backed by a poll that always does. */
+export const FileWatch = { file, directory, subdirectories };