pim-agent 0.0.1 → 0.10.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 };