pim-agent 0.0.1 → 0.10.0

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

@@ -0,0 +1,84 @@
+const maxBytes = 32 * 1024;
+const maxLineLength = 2000;
+
+function truncateLine(line: string): string {
+  if (line.length <= maxLineLength) {
+    return line;
+  }
+
+  return `${line.slice(0, maxLineLength)}... (line truncated to ${maxLineLength} chars)`;
+}
+
+function truncateUtf8(
+  content: string,
+  limit: number = maxBytes
+): {
+  readonly body: string;
+  readonly returnedBytes: number;
+  readonly totalBytes: number;
+  readonly truncated: boolean;
+} {
+  const totalBytes = Buffer.byteLength(content, "utf8");
+
+  if (totalBytes <= limit) {
+    return {
+      body: content,
+      returnedBytes: totalBytes,
+      totalBytes,
+      truncated: false,
+    };
+  }
+
+  const encoded = new TextEncoder().encode(content);
+  let cut = limit;
+  while (cut > 0 && ((encoded[cut] ?? 0) & 0xc0) === 0x80) {
+    cut -= 1;
+  }
+
+  const body = new TextDecoder("utf-8").decode(encoded.subarray(0, cut));
+
+  return { body, returnedBytes: cut, totalBytes, truncated: true };
+}
+
+function applyByteCap(
+  items: readonly string[],
+  options: {
+    readonly maxBytes?: number;
+    readonly separator?: string;
+  } = {}
+): {
+  readonly visible: readonly string[];
+  readonly droppedItems: number;
+} {
+  const limit = options.maxBytes ?? maxBytes;
+  const separator = options.separator ?? "\n";
+  const separatorBytes = Buffer.byteLength(separator, "utf8");
+  const visible: string[] = [];
+  let bytes = 0;
+
+  for (const item of items) {
+    const itemBytes = Buffer.byteLength(item, "utf8");
+    const cost = visible.length === 0 ? itemBytes : separatorBytes + itemBytes;
+
+    if (visible.length > 0 && bytes + cost > limit) {
+      break;
+    }
+
+    visible.push(item);
+    bytes += cost;
+
+    if (bytes >= limit) {
+      break;
+    }
+  }
+
+  return { visible, droppedItems: items.length - visible.length };
+}
+
+export const OutputBudget = {
+  maxBytes,
+  maxLineLength,
+  truncateLine,
+  truncateUtf8,
+  applyByteCap,
+};

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

@@ -0,0 +1,40 @@
+export const ADD_FILE_MARKER = "*** Add File: ";
+export const DELETE_FILE_MARKER = "*** Delete File: ";
+export const UPDATE_FILE_MARKER = "*** Update File: ";
+export const MOVE_TO_MARKER = "*** Move to:";
+
+const FILE_MARKERS = [
+  ADD_FILE_MARKER,
+  DELETE_FILE_MARKER,
+  UPDATE_FILE_MARKER,
+] as const;
+
+function firstPath(input: string): string | undefined {
+  for (const raw of input.split("\n")) {
+    const line = raw.trim();
+    for (const marker of FILE_MARKERS) {
+      if (line.startsWith(marker)) {
+        return cleanPath(line.slice(marker.length));
+      }
+    }
+  }
+  return undefined;
+}
+
+export function cleanPath(raw: string): string {
+  let path = raw.trim();
+  if (path.startsWith("@")) {
+    path = path.slice(1).trim();
+  }
+  if (path.length >= 2) {
+    const first = path[0]!;
+    const last = path.at(-1)!;
+    if ((first === '"' || first === "'" || first === "`") && first === last) {
+      path = path.slice(1, -1);
+    }
+  }
+  return path;
+}
+
+/** Fault-tolerant scan of V4A patch text for renderers; unrecognized lines are ignored. */
+export const PatchSummary = { firstPath };

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

@@ -0,0 +1,80 @@
+import { chmod, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { isAbsolute, relative, resolve as pathResolve, sep } from "node:path";
+
+function pimHomeDir(): string {
+  return expandHome(process.env.PIM_HOME_DIR ?? "~/.pim");
+}
+
+async function ensurePimHome(): Promise<string> {
+  const dir = pimHomeDir();
+  await mkdir(dir, { recursive: true, mode: 0o700 });
+  await chmod(dir, 0o700);
+  return dir;
+}
+
+function resolve(value: string, baseDir: string): string {
+  const expanded = expandHome(value);
+  return isAbsolute(expanded) ? expanded : pathResolve(baseDir, expanded);
+}
+
+function toForwardSlashes(path: string): string {
+  return sep === "/" ? path : path.split(sep).join("/");
+}
+
+function expandHome(value: string): string {
+  if (value === "~") {
+    return homedir();
+  }
+
+  if (value.startsWith("~/")) {
+    return pathResolve(homedir(), value.slice(2));
+  }
+
+  return value;
+}
+
+function abbreviateHome(path: string): string {
+  const home = homedir();
+  return home && path.startsWith(home) ? `~${path.slice(home.length)}` : path;
+}
+
+function displayRelative(path: string, cwd: string): string {
+  const rel = relative(cwd, path);
+
+  if (rel === "" || rel.startsWith("..") || isAbsolute(rel)) {
+    return path;
+  }
+
+  return rel;
+}
+
+function compare(left: string, right: string): number {
+  if (left < right) {
+    return -1;
+  }
+  if (left > right) {
+    return 1;
+  }
+  return 0;
+}
+
+function titleOr(
+  path: string | undefined,
+  cwd: string,
+  placeholder = "..."
+): string {
+  return path ? displayRelative(path, cwd) : placeholder;
+}
+
+export const Paths = {
+  pimHomeDir,
+  ensurePimHome,
+  resolve,
+  toForwardSlashes,
+  expandHome,
+  abbreviateHome,
+  displayRelative,
+  titleOr,
+  compare,
+};

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

@@ -0,0 +1,128 @@
+import { join } from "node:path";
+import { type Static, Type } from "typebox";
+import { Value } from "typebox/value";
+
+import { Fs } from "./Fs";
+import { Paths } from "./Paths";
+
+const Schema = Type.Object({
+  extensions: Type.Object(
+    {
+      toggles: Type.Record(Type.String(), Type.Boolean(), { default: {} }),
+    },
+    { default: { toggles: {} } }
+  ),
+  exa: Type.Object(
+    {
+      apiKey: Type.Optional(Type.String()),
+    },
+    { default: {} }
+  ),
+  jina: Type.Object(
+    {
+      apiKey: Type.Optional(Type.String()),
+    },
+    { default: {} }
+  ),
+  firecrawl: Type.Object(
+    {
+      apiKey: Type.Optional(Type.String()),
+    },
+    { default: {} }
+  ),
+  read: Type.Object(
+    {
+      dedupImages: Type.Boolean({ default: true }),
+    },
+    { default: { dedupImages: true } }
+  ),
+});
+
+type Settings = Static<typeof Schema>;
+
+let loaded: Promise<Settings> | undefined;
+let loadedPath: string | undefined;
+const writes = Fs.serialised();
+
+function path(): string {
+  return join(Paths.pimHomeDir(), "settings.json");
+}
+
+function load(): Promise<Settings> {
+  const settingsPath = path();
+  if (loadedPath !== settingsPath) {
+    loaded = undefined;
+    loadedPath = settingsPath;
+  }
+  loaded ??= (async () => {
+    const raw = await Fs.readJsonOr<unknown>(settingsPath, {});
+    const filled = Value.Default(Schema, raw);
+    return Value.Check(Schema, filled) ? filled : Value.Create(Schema);
+  })();
+  return loaded;
+}
+
+async function getExaApiKey(): Promise<string | undefined> {
+  return (
+    normalize(process.env["EXA_API_KEY"]) ??
+    normalize((await get("exa")).apiKey)
+  );
+}
+
+async function getJinaApiKey(): Promise<string | undefined> {
+  return (
+    normalize(process.env["JINA_API_KEY"]) ??
+    normalize((await get("jina")).apiKey)
+  );
+}
+
+async function getFirecrawlApiKey(): Promise<string | undefined> {
+  return (
+    normalize(process.env["FIRECRAWL_API_KEY"]) ??
+    normalize((await get("firecrawl")).apiKey)
+  );
+}
+
+function normalize(value: string | undefined): string | undefined {
+  const trimmed = value?.trim();
+  return trimmed === undefined || trimmed.length === 0 ? undefined : trimmed;
+}
+
+async function get<K extends keyof Settings>(key: K): Promise<Settings[K]> {
+  return (await load())[key];
+}
+
+function set<K extends keyof Settings>(
+  key: K,
+  value: Settings[K]
+): Promise<void> {
+  return update(key, () => value);
+}
+
+function update<K extends keyof Settings>(
+  key: K,
+  mutate: (current: Settings[K]) => Settings[K]
+): Promise<void> {
+  return writes.run(async () => {
+    const current = await load();
+    const next: Settings = { ...current, [key]: mutate(current[key]) };
+    if (!Value.Check(Schema, next)) {
+      throw new Error(`Invalid value for pim setting "${String(key)}"`);
+    }
+    const settingsPath = path();
+    loaded = Promise.resolve(next);
+    loadedPath = settingsPath;
+    await Paths.ensurePimHome();
+    await Fs.writeJson(settingsPath, next);
+  });
+}
+
+export const PimSettings = {
+  path,
+  getExaApiKey,
+  getJinaApiKey,
+  getFirecrawlApiKey,
+  get,
+  set,
+  update,
+};

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

@@ -0,0 +1,93 @@
+import { Fs } from "./Fs";
+import { createKy } from "./Http";
+
+const REGISTRY = "https://registry.npmjs.org";
+const DEFAULT_TIMEOUT_MS = 5_000;
+
+type Manifest = {
+  readonly name: string;
+  readonly version: string;
+};
+
+type LatestOptions = {
+  readonly fetch?: typeof fetch;
+  readonly timeoutMs?: number;
+};
+
+async function read(url: URL): Promise<Manifest> {
+  const pkg = await Fs.readJsonOr<Partial<Manifest> | null>(url, null);
+  return {
+    name: typeof pkg?.name === "string" ? pkg.name : "?",
+    version: typeof pkg?.version === "string" ? pkg.version : "?",
+  };
+}
+
+function self(): Promise<Manifest> {
+  return read(new URL("../../../../package.json", import.meta.url));
+}
+
+async function current(): Promise<string> {
+  return (await self()).version;
+}
+
+/** The npm package this pim was published as. */
+async function name(): Promise<string> {
+  return (await self()).name;
+}
+
+/** The pi that ships inside pim's install tree. */
+async function pi(): Promise<string> {
+  return (
+    await read(
+      new URL(
+        import.meta.resolve("@earendil-works/pi-coding-agent/package.json")
+      )
+    )
+  ).version;
+}
+
+async function latest(
+  options: LatestOptions = {}
+): Promise<string | undefined> {
+  const pkg = await self();
+  const client = createKy(options.fetch);
+  try {
+    const release = await client(
+      `${REGISTRY}/${pkg.name.replace("/", "%2f")}/latest`,
+      {
+        timeout: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+        headers: { accept: "application/json" },
+      }
+    ).json<{ readonly version?: unknown }>();
+    return typeof release.version === "string" && release.version.trim()
+      ? release.version.trim()
+      : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
+function core(version: string): readonly number[] | undefined {
+  const parts = version.trim().split(/[-+]/)[0]!.split(".");
+  const numbers = parts.map(Number);
+  return parts.length === 3 &&
+    numbers.every((part) => Number.isInteger(part) && part >= 0)
+    ? numbers
+    : undefined;
+}
+
+function isNewer(candidate: string, installed: string): boolean {
+  const left = core(candidate);
+  const right = core(installed);
+  if (!left || !right) {
+    return candidate.trim() !== installed.trim();
+  }
+  for (const [index, part] of left.entries()) {
+    if (part !== right[index]) {
+      return part > right[index]!;
+    }
+  }
+  return installed.includes("-") && !candidate.includes("-");
+}
+
+export const PimVersion = { current, name, pi, latest, isNewer };

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

@@ -0,0 +1,26 @@
+async function mapPooled<T, R>(
+  items: readonly T[],
+  limit: number,
+  fn: (item: T, index: number) => Promise<R>
+): Promise<R[]> {
+  const results: R[] = Array.from({ length: items.length });
+  let next = 0;
+
+  const worker = async (): Promise<void> => {
+    while (next < items.length) {
+      const index = next;
+      next += 1;
+      results[index] = await fn(items[index] as T, index);
+    }
+  };
+
+  await Promise.all(
+    Array.from({ length: Math.min(Math.max(limit, 1), items.length) }, worker)
+  );
+
+  return results;
+}
+
+export const Pool = {
+  mapPooled,
+};

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

@@ -0,0 +1,50 @@
+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(
+  cmd: ReadonlyArray<string>,
+  options: ProcOptions = {}
+): Promise<ProcResult> {
+  const proc = Bun.spawn([...cmd], {
+    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(),
+  ]);
+  const code = await proc.exited;
+  clearTimeout(timer);
+  return { code, stdout, stderr, timedOut };
+}
+
+export const Proc = { run };

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

@@ -0,0 +1,50 @@
+export type RateLimiterOptions = {
+  readonly maxRequests: number;
+  readonly windowMs: number;
+  readonly now?: () => number;
+  readonly sleep?: (ms: number) => Promise<void>;
+};
+
+export class RateLimiter {
+  private readonly maxRequests: number;
+  private readonly windowMs: number;
+  private readonly now: () => number;
+  private readonly sleep: (ms: number) => Promise<void>;
+  private readonly timestamps: number[] = [];
+  private tail: Promise<void> = Promise.resolve();
+
+  public constructor(options: RateLimiterOptions) {
+    this.maxRequests = Math.max(1, options.maxRequests);
+    this.windowMs = options.windowMs;
+    this.now = options.now ?? Date.now;
+    this.sleep = options.sleep ?? ((ms) => Bun.sleep(ms));
+  }
+
+  public acquire(): Promise<void> {
+    const reserved = this.tail.then(() => this.reserve());
+    this.tail = reserved.catch(() => {});
+
+    return reserved;
+  }
+
+  private async reserve(): Promise<void> {
+    while (true) {
+      const now = this.now();
+      const threshold = now - this.windowMs;
+
+      while (this.timestamps.length > 0 && this.timestamps[0]! <= threshold) {
+        this.timestamps.shift();
+      }
+
+      if (this.timestamps.length < this.maxRequests) {
+        this.timestamps.push(now);
+
+        return;
+      }
+
+      const waitMs = this.timestamps[0]! + this.windowMs - now;
+
+      await this.sleep(Math.max(0, waitMs));
+    }
+  }
+}