pim-agent 0.0.1 → 0.9.0

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

@@ -0,0 +1,74 @@
+function formatTokens(tokens: number): string {
+  if (tokens < 1000) {
+    return `${tokens}`;
+  }
+  if (tokens < 10_000) {
+    return `${(tokens / 1000).toFixed(1)}K`;
+  }
+  if (tokens < 1_000_000) {
+    return `${Math.round(tokens / 1000)}K`;
+  }
+  if (tokens < 10_000_000) {
+    return `${(tokens / 1_000_000).toFixed(1)}M`;
+  }
+  return `${Math.round(tokens / 1_000_000)}M`;
+}
+
+function formatElapsed(ms: number): string {
+  const totalSeconds = Math.max(0, Math.floor(ms / 1000));
+  const hours = Math.floor(totalSeconds / 3600);
+  const minutes = Math.floor((totalSeconds % 3600) / 60);
+  const seconds = totalSeconds % 60;
+  return hours > 0
+    ? `${hours}h ${minutes}m ${seconds}s`
+    : minutes > 0
+      ? `${minutes}m ${seconds}s`
+      : `${seconds}s`;
+}
+
+/** How full the context window reads, as a verdict each frontend colours. */
+export type ContextFill = "ok" | "warn" | "full";
+
+function contextFill(percent: number): ContextFill {
+  if (percent >= 70) {
+    return "full";
+  }
+  return percent > 40 ? "warn" : "ok";
+}
+
+function count(value: number, noun: string): string {
+  return `${value} ${noun}${value === 1 ? "" : "s"}`;
+}
+
+function scaleBytes(total: number): readonly [string, string] {
+  const [value, unit] =
+    total < 1024 * 1024 ? [total / 1024, "KB"] : [total / (1024 * 1024), "MB"];
+  return [value.toFixed(2).replace(/\.?0+$/u, ""), unit];
+}
+
+/** A byte count as a person reads it, unit spaced: `40 bytes`, `240 KB`, `1.5 MB`. */
+function bytes(total: number): string {
+  if (total < 1024) {
+    return `${total} bytes`;
+  }
+  const [value, unit] = scaleBytes(total);
+  return `${value} ${unit}`;
+}
+
+/** The same count where a title has no room for the space: `40B`, `240KB`, `1.5MB`. */
+function bytesCompact(total: number): string {
+  if (total < 1024) {
+    return `${total}B`;
+  }
+  const [value, unit] = scaleBytes(total);
+  return `${value}${unit}`;
+}
+
+export const Format = {
+  formatTokens,
+  formatElapsed,
+  contextFill,
+  count,
+  bytes,
+  bytesCompact,
+};

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

@@ -0,0 +1,91 @@
+import { chmod, mkdir, rename, stat } from "node:fs/promises";
+import { dirname } from "node:path";
+
+import { FsErrors } from "./FsErrors";
+
+async function readJsonOrEmpty<T>(filePath: string, fallback: T): Promise<T> {
+  try {
+    return (await Bun.file(filePath).json()) as T;
+  } catch (err) {
+    if (FsErrors.code(err) === "ENOENT") {
+      return fallback;
+    }
+    throw new Error(`Failed to parse ${filePath}: ${(err as Error).message}`);
+  }
+}
+
+async function readJsonOr<T>(source: string | URL, fallback: T): Promise<T> {
+  try {
+    return (await Bun.file(source).json()) as T;
+  } catch {
+    return fallback;
+  }
+}
+
+async function writeAtomic(
+  filePath: string,
+  data: string,
+  mode?: number
+): Promise<void> {
+  await mkdir(dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.tmp-${process.pid}-${Date.now()}`;
+  await Bun.write(tmp, data);
+  const resolvedMode = mode ?? (await existingMode(filePath));
+  if (resolvedMode !== undefined) {
+    await chmod(tmp, resolvedMode);
+  }
+  await rename(tmp, filePath);
+}
+
+async function writeJson(
+  filePath: string,
+  value: unknown,
+  mode = 0o600
+): Promise<void> {
+  await writeAtomic(filePath, `${JSON.stringify(value, null, 2)}\n`, mode);
+}
+
+async function writeKeepingLinks(
+  filePath: string,
+  content: string,
+  options: { readonly mode?: number; readonly nlink: number }
+): Promise<void> {
+  if (options.nlink > 1) {
+    await Bun.write(filePath, content);
+    return;
+  }
+  await writeAtomic(filePath, content, options.mode);
+}
+
+function serialised(): {
+  run: <T>(task: () => Promise<T>) => Promise<T>;
+} {
+  let queue: Promise<unknown> = Promise.resolve();
+  return {
+    run: <T>(task: () => Promise<T>): Promise<T> => {
+      const next = queue.then(task, task);
+      queue = next;
+      return next;
+    },
+  };
+}
+
+async function existingMode(filePath: string): Promise<number | undefined> {
+  try {
+    return (await stat(filePath)).mode & 0o777;
+  } catch (err) {
+    if (FsErrors.code(err) === "ENOENT") {
+      return undefined;
+    }
+    throw err;
+  }
+}
+
+export const Fs = {
+  readJsonOrEmpty,
+  readJsonOr,
+  writeAtomic,
+  writeJson,
+  writeKeepingLinks,
+  serialised,
+};

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

@@ -0,0 +1,67 @@
+import type { Stats } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import { basename, dirname, extname, join } from "node:path";
+
+function code(error: unknown): string | undefined {
+  return typeof error === "object" && error !== null && "code" in error
+    ? String((error as { code: unknown }).code)
+    : undefined;
+}
+
+async function statOrThrow(path: string): Promise<Stats> {
+  try {
+    return await stat(path);
+  } catch (error) {
+    const errorCode = code(error);
+
+    if (errorCode === "ENOENT") {
+      throw new Error(await renderMissing(path));
+    }
+
+    if (errorCode === "EACCES" || errorCode === "EPERM") {
+      throw new Error(`Permission denied accessing ${path}.`);
+    }
+
+    throw new Error(
+      `Cannot stat ${path}: ${errorCode ?? (error instanceof Error ? error.message : "unknown error")}.`
+    );
+  }
+}
+
+async function renderMissing(path: string): Promise<string> {
+  const suggestions = await suggestSiblings(path);
+  const headline = `Path not found: ${path}. Use glob to locate the file or directory, or verify the path.`;
+  if (suggestions.length === 0) {
+    return headline;
+  }
+  return [headline, "", "Did you mean one of these?", ...suggestions].join(
+    "\n"
+  );
+}
+
+async function suggestSiblings(path: string): Promise<readonly string[]> {
+  const dir = dirname(path);
+  const base = basename(path).toLowerCase();
+  const stem = base.slice(0, base.length - extname(base).length);
+
+  try {
+    const entries = await readdir(dir);
+    return entries
+      .filter((entry) => {
+        const lower = entry.toLowerCase();
+        const lowerStem = lower.slice(0, lower.length - extname(lower).length);
+        return (
+          lower.includes(base) ||
+          base.includes(lower) ||
+          (stem.length > 0 &&
+            (lowerStem.includes(stem) || stem.includes(lowerStem)))
+        );
+      })
+      .slice(0, 3)
+      .map((entry) => join(dir, entry));
+  } catch {
+    return [];
+  }
+}
+
+export const FsErrors = { code, statOrThrow, renderMissing };

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

@@ -0,0 +1,71 @@
+import { byLengthAsc, byStartAsc, Fzf } from "fzf";
+
+export type FuzzyCandidate<T> = {
+  readonly item: T;
+  readonly haystacks: readonly string[];
+};
+
+export type FuzzyHit<T> = {
+  readonly item: T;
+  readonly score: number;
+  readonly positions: ReadonlySet<number>;
+};
+
+export type FuzzyRankOptions = {
+  readonly limit?: number;
+};
+
+export type FuzzyIndex<T> = {
+  readonly find: (
+    query: string,
+    options?: FuzzyRankOptions
+  ) => readonly FuzzyHit<T>[];
+};
+
+const HAYSTACK_SEPARATOR = " ";
+
+function rank<T>(
+  query: string,
+  candidates: readonly FuzzyCandidate<T>[],
+  options: FuzzyRankOptions = {}
+): readonly FuzzyHit<T>[] {
+  return prepare(candidates).find(query, options);
+}
+
+function prepare<T>(candidates: readonly FuzzyCandidate<T>[]): FuzzyIndex<T> {
+  const fzf = new Fzf<readonly FuzzyCandidate<T>[]>(candidates, {
+    selector: (candidate) => candidate.haystacks.join(HAYSTACK_SEPARATOR),
+    tiebreakers: [byStartAsc, byLengthAsc],
+  });
+
+  let emptyHits: readonly FuzzyHit<T>[] | undefined;
+
+  return {
+    find: (query, options = {}) => {
+      const trimmed = query.trim();
+      const limit = options.limit ?? Infinity;
+      if (trimmed.length === 0) {
+        if (emptyHits === undefined) {
+          emptyHits = [...candidates]
+            .sort((a, b) =>
+              (a.haystacks[0] ?? "").localeCompare(b.haystacks[0] ?? "")
+            )
+            .map((candidate) => ({
+              item: candidate.item,
+              score: 0,
+              positions: new Set<number>(),
+            }));
+        }
+        return limit === Infinity ? emptyHits : emptyHits.slice(0, limit);
+      }
+      const hits = fzf.find(trimmed).map((result) => ({
+        item: result.item.item,
+        score: result.score,
+        positions: result.positions,
+      }));
+      return limit === Infinity ? hits : hits.slice(0, limit);
+    },
+  };
+}
+
+export const FuzzyMatcher = { rank, prepare };

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

@@ -0,0 +1,89 @@
+import { type FSWatcher, watch } from "node:fs";
+import { join } from "node:path";
+
+export type GitState = {
+  readonly branch: string | null;
+  /** Paths `git status` lists as changed; zero is a clean tree. */
+  readonly dirtyCount: number;
+  readonly ahead: number;
+  readonly behind: number;
+};
+
+const EMPTY: GitState = {
+  branch: null,
+  dirtyCount: 0,
+  ahead: 0,
+  behind: 0,
+};
+
+function parseStatus(text: string): GitState {
+  let branch: string | null = null;
+  let ahead = 0;
+  let behind = 0;
+  let dirtyCount = 0;
+  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("#")) {
+      dirtyCount++;
+    }
+  }
+  return { branch, dirtyCount, ahead, behind };
+}
+
+function watchDir(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 {}
+  return (): void => {
+    if (timer !== null) {
+      clearTimeout(timer);
+      timer = null;
+    }
+    if (watcher !== null) {
+      try {
+        watcher.close();
+      } catch {}
+    }
+  };
+}
+
+async function fetchStatus(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;
+    }
+    return parseStatus(text);
+  } catch {
+    return EMPTY;
+  }
+}
+
+/** The cwd's git state, for the TUI footer and the web's branch chip. */
+export const Git = { EMPTY, parseStatus, watchDir, fetchStatus };

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

@@ -0,0 +1,13 @@
+function compile(exclude: readonly string[] | undefined): readonly Bun.Glob[] {
+  return (exclude ?? []).map((pattern) => new Bun.Glob(pattern));
+}
+
+function ignores(globs: readonly Bun.Glob[], relativePath: string): boolean {
+  if (globs.length === 0) {
+    return false;
+  }
+
+  return globs.some((glob) => glob.match(relativePath));
+}
+
+export const GlobExclusions = { compile, ignores };

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

@@ -0,0 +1,14 @@
+import ky, { type KyInstance } from "ky";
+
+export type HttpFetch = (
+  input: Parameters<typeof fetch>[0],
+  init?: Parameters<typeof fetch>[1]
+) => ReturnType<typeof fetch>;
+
+/** Ky with retries off: its defaults retry GETs twice and honour `Retry-After` uncapped, stalling a tool for hours. */
+export function createKy(custom?: HttpFetch): KyInstance {
+  return ky.create({
+    retry: 0,
+    ...(custom === undefined ? {} : { fetch: custom as typeof fetch }),
+  });
+}

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

@@ -0,0 +1,36 @@
+/** The formats every provider we target accepts. */
+export type ImageMimeType =
+  | "image/png"
+  | "image/jpeg"
+  | "image/gif"
+  | "image/webp";
+
+const EXTENSIONS = {
+  "image/png": "png",
+  "image/jpeg": "jpg",
+  "image/gif": "gif",
+  "image/webp": "webp",
+} satisfies Record<ImageMimeType, string>;
+
+/** Both spellings of every format, so `.jpeg` names a picture as surely as `.jpg`. */
+const NAME_EXTENSIONS = new Set([
+  ...Object.values(EXTENSIONS),
+  ...Object.keys(EXTENSIONS).map((mimeType) => mimeType.slice("image/".length)),
+]);
+
+/** The format as a word, in the one spelling the notes, the UI and the cache filename all use. */
+function extensionOf(mimeType: ImageMimeType): string {
+  return EXTENSIONS[mimeType];
+}
+
+function isSupported(mimeType: string): mimeType is ImageMimeType {
+  return Object.hasOwn(EXTENSIONS, mimeType);
+}
+
+/** Whether a bare, lowercased extension is one of the spellings a picture goes by. */
+function namesExtension(extension: string): boolean {
+  return NAME_EXTENSIONS.has(extension);
+}
+
+/** The format table alone, free of Node so the browser can name a picture too. */
+export const ImageMime = { extensionOf, isSupported, namesExtension };