pim-agent 0.0.1 → 0.9.0

package/packages/core/src/extensions/edit/edit.ts

@@ -0,0 +1,366 @@
+import type { Stats } from "node:fs";
+import { realpath, stat } from "node:fs/promises";
+import {
+  EditMatcher,
+  type EditMatchStrategy,
+  type EditRange,
+} from "../../shared/EditMatcher";
+import { DiffLines, type ToolDiff } from "../../shared/DiffLines";
+import { Fs } from "../../shared/Fs";
+import { FsErrors } from "../../shared/FsErrors";
+import { Lines } from "../../shared/Lines";
+import type { RawEdit } from "./schema";
+
+export type NoopEdit = {
+  readonly index: number;
+  readonly range: string;
+};
+
+export type ResolvedEditMetadata = {
+  readonly index: number;
+  readonly ranges: readonly string[];
+  readonly strategy: EditMatchStrategy;
+  readonly matchCount: number;
+  readonly replaceAll: boolean;
+};
+
+export type EditOutcome = {
+  readonly editCount: number;
+  readonly noops: readonly NoopEdit[];
+  readonly ranges: readonly string[];
+  readonly resolvedEdits: readonly ResolvedEditMetadata[];
+  readonly diff?: ToolDiff;
+};
+
+type ParsedEdit = {
+  readonly index: number;
+  readonly oldString: string;
+  readonly newString: string;
+  readonly replaceAll: boolean;
+};
+
+type ResolvedEdit = {
+  readonly index: number;
+  readonly ranges: readonly EditRange[];
+  readonly newString: string;
+  readonly strategy: EditMatchStrategy;
+  readonly matchCount: number;
+  readonly replaceAll: boolean;
+};
+
+type Mutation = {
+  readonly index: number;
+  readonly range: EditRange;
+  readonly newString: string;
+};
+
+const CONTEXT_LINES = 2;
+const MAX_EDIT_BYTES = 8 * 1024 * 1024;
+
+const editQueues = new Map<string, Promise<unknown>>();
+
+export async function editFile(
+  absolutePath: string,
+  rawEdits: readonly RawEdit[]
+): Promise<EditOutcome> {
+  let canonicalPath: string;
+  try {
+    canonicalPath = await realpath(absolutePath);
+  } catch (error) {
+    if (FsErrors.code(error) === "ENOENT") {
+      throw new Error(await FsErrors.renderMissing(absolutePath));
+    }
+    throw error;
+  }
+
+  return enqueue(canonicalPath, () =>
+    performEdit(absolutePath, canonicalPath, rawEdits)
+  );
+}
+
+async function performEdit(
+  displayPath: string,
+  canonicalPath: string,
+  rawEdits: readonly RawEdit[]
+): Promise<EditOutcome> {
+  const edits = parseEdits(rawEdits);
+  const metadata = await stat(canonicalPath);
+
+  if (metadata.isDirectory()) {
+    throw new Error(`Path is a directory: ${displayPath}.`);
+  }
+
+  if (metadata.size > MAX_EDIT_BYTES) {
+    throw new Error(
+      `Path exceeds the ${MAX_EDIT_BYTES}-byte edit cap (${metadata.size} bytes): ${displayPath}.`
+    );
+  }
+
+  assertNoDuplicateEdits(edits);
+
+  const file = Bun.file(canonicalPath);
+  const bytes = await file.bytes();
+
+  if (bytes.subarray(0, 8192).includes(0)) {
+    throw new Error(
+      `Path is a binary file: ${displayPath}. Edit only supports UTF-8 text files.`
+    );
+  }
+
+  const hadBom = Lines.hasUtf8Bom(bytes);
+  const originalContent = Lines.stripUtf8Bom(
+    new TextDecoder("utf-8").decode(bytes)
+  );
+  const lineEnding = originalContent.includes("\r\n") ? "\r\n" : "\n";
+  const normalizedEdits = edits.map((edit) => ({
+    ...edit,
+    oldString: normalizeEditString(edit.oldString, lineEnding),
+    newString: normalizeEditString(edit.newString, lineEnding),
+  }));
+  const resolved = normalizedEdits.map((edit) =>
+    resolveEdit(originalContent, edit)
+  );
+  const allMutations = resolved.flatMap((edit) =>
+    edit.ranges.map((range) => ({
+      index: edit.index,
+      range,
+      newString: edit.newString,
+    }))
+  );
+
+  const sortedMutations = sortMutations(allMutations);
+  assertNoOverlaps(sortedMutations);
+
+  const isNoop = (mutation: Mutation) =>
+    originalContent.slice(mutation.range[0], mutation.range[1]) ===
+    mutation.newString;
+
+  const lineRangeCache = new Map<string, string>();
+  const lineRange = (range: EditRange): string => {
+    const key = `${range[0]}:${range[1]}`;
+    let cached = lineRangeCache.get(key);
+    if (cached === undefined) {
+      cached = EditMatcher.lineRangeFor(originalContent, range);
+      lineRangeCache.set(key, cached);
+    }
+    return cached;
+  };
+
+  const noops: NoopEdit[] = [];
+  const effectiveMutations: Mutation[] = [];
+  for (const mutation of sortedMutations) {
+    if (isNoop(mutation)) {
+      noops.push({ index: mutation.index, range: lineRange(mutation.range) });
+    } else {
+      effectiveMutations.push(mutation);
+    }
+  }
+
+  if (effectiveMutations.length === 0) {
+    throw new Error(renderAllNoopError(noops));
+  }
+
+  const nextContent = EditMatcher.applyAll(originalContent, effectiveMutations);
+
+  await writeFileAtomic(
+    canonicalPath,
+    hadBom ? `${Lines.utf8Bom}${nextContent}` : nextContent,
+    metadata
+  );
+
+  const original = Lines.splitWithTrailingNewline(originalContent);
+  const next = Lines.splitWithTrailingNewline(nextContent);
+  const diff = DiffLines.buildToolDiff(
+    displayPath,
+    original,
+    next,
+    CONTEXT_LINES
+  );
+
+  const resolvedEdits = resolved.map((edit) => ({
+    index: edit.index,
+    ranges: edit.ranges.map((range) => lineRange(range)),
+    strategy: edit.strategy,
+    matchCount: edit.matchCount,
+    replaceAll: edit.replaceAll,
+  }));
+
+  return {
+    editCount: edits.length,
+    noops,
+    ranges: effectiveMutations.map((mutation) => lineRange(mutation.range)),
+    resolvedEdits,
+    ...(diff === undefined ? {} : { diff }),
+  };
+}
+
+function parseEdits(rawEdits: readonly RawEdit[]): readonly ParsedEdit[] {
+  if (rawEdits.length === 0) {
+    throw new Error("Expected non-empty edits array.");
+  }
+
+  return rawEdits.map((raw, index) => {
+    if (raw.oldString === raw.newString) {
+      throw new Error(`Edit ${index}: oldString and newString are identical.`);
+    }
+
+    return {
+      index,
+      oldString: raw.oldString,
+      newString: raw.newString,
+      replaceAll: raw.replaceAll ?? false,
+    };
+  });
+}
+
+function normalizeEditString(text: string, lineEnding: "\n" | "\r\n"): string {
+  const normalized = Lines.normalize(text);
+  return lineEnding === "\n" ? normalized : normalized.replaceAll("\n", "\r\n");
+}
+
+function resolveEdit(content: string, edit: ParsedEdit): ResolvedEdit {
+  try {
+    const outcome = EditMatcher.resolve(
+      content,
+      edit.oldString,
+      edit.replaceAll
+    );
+    const ranges = "ranges" in outcome ? outcome.ranges : [outcome.range];
+
+    for (const range of ranges) {
+      EditMatcher.assertNoEscapeDrift(
+        outcome.strategy,
+        edit.newString,
+        content.slice(range[0], range[1])
+      );
+    }
+
+    return {
+      index: edit.index,
+      ranges,
+      newString: edit.newString,
+      strategy: outcome.strategy,
+      matchCount: outcome.matchCount,
+      replaceAll: edit.replaceAll,
+    };
+  } catch (error) {
+    if (error instanceof EditMatcher.NotFoundError) {
+      throw new Error(EditMatcher.renderNotFound(error));
+    }
+
+    throw error;
+  }
+}
+
+function assertNoDuplicateEdits(edits: readonly ParsedEdit[]): void {
+  const seen = new Map<string, number>();
+
+  for (const [index, edit] of edits.entries()) {
+    const key = duplicateKey(edit);
+    const previous = seen.get(key);
+
+    if (previous !== undefined) {
+      throw new Error(
+        `Edits ${previous} and ${index} are identical. Remove one.`
+      );
+    }
+
+    seen.set(key, index);
+  }
+}
+
+function duplicateKey(edit: ParsedEdit): string {
+  return JSON.stringify({
+    oldString: edit.oldString,
+    newString: edit.newString,
+    replaceAll: edit.replaceAll,
+  });
+}
+
+function sortMutations(mutations: readonly Mutation[]): readonly Mutation[] {
+  return [...mutations].sort((left, right) => {
+    if (left.range[0] !== right.range[0]) {
+      return left.range[0] - right.range[0];
+    }
+
+    return left.range[1] - right.range[1];
+  });
+}
+
+function assertNoOverlaps(sorted: readonly Mutation[]): void {
+  for (let index = 1; index < sorted.length; index += 1) {
+    const previous = sorted[index - 1]!;
+    const current = sorted[index]!;
+
+    if (previous.range[1] > current.range[0]) {
+      throw new Error(renderOverlapError(previous, current));
+    }
+  }
+}
+
+function renderOverlapError(left: Mutation, right: Mutation): string {
+  return [
+    `Edits ${left.index} and ${right.index} target overlapping byte ranges.`,
+    `- Edit ${left.index}: range ${left.range[0]}-${left.range[1]}`,
+    `- Edit ${right.index}: range ${right.range[0]}-${right.range[1]}`,
+    "Combine into a single edit, or drop one.",
+  ].join("\n");
+}
+
+function renderAllNoopError(noops: readonly NoopEdit[]): string {
+  return [
+    "All edits were no-ops. The file already contains the requested replacement content.",
+    "",
+    ...noops.map(
+      (noop) =>
+        `- Edit ${noop.index}: matched range ${noop.range} already equals newString.`
+    ),
+    "",
+    "Re-read the file and widen oldString if you meant to replace adjacent duplicated content.",
+  ].join("\n");
+}
+
+async function writeFileAtomic(
+  canonicalPath: string,
+  content: string,
+  metadata: Stats
+): Promise<void> {
+  await Fs.writeKeepingLinks(canonicalPath, content, {
+    mode: Number(metadata.mode),
+    nlink: metadata.nlink,
+  });
+}
+
+async function enqueue<T>(key: string, task: () => Promise<T>): Promise<T> {
+  const previous = editQueues.get(key) ?? Promise.resolve();
+  const queued = previous.then(task, task);
+  editQueues.set(key, queued);
+
+  try {
+    return await queued;
+  } finally {
+    if (editQueues.get(key) === queued) {
+      editQueues.delete(key);
+    }
+  }
+}
+
+export function formatEditSummary(
+  displayPath: string,
+  outcome: EditOutcome
+): string {
+  const noun = outcome.editCount === 1 ? "edit" : "edits";
+  return `${outcome.editCount} ${noun} made to ${displayPath}: lines ${joinHuman(outcome.ranges)}.`;
+}
+
+function joinHuman(items: readonly string[]): string {
+  if (items.length === 0) {
+    return "unknown";
+  }
+
+  if (items.length === 1) {
+    return items[0] ?? "unknown";
+  }
+
+  return `${items.slice(0, -1).join(", ")} and ${items.at(-1)}`;
+}

package/packages/core/src/extensions/edit/index.ts

@@ -0,0 +1,36 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Paths } from "../../shared/Paths";
+import { Tools } from "../../shared/Tools";
+import { editFile, formatEditSummary } from "./edit";
+import { editView } from "./render";
+import { type EditInput, editSchema } from "./schema";
+
+export default function (pi: ExtensionAPI): void {
+  Tools.register(pi, {
+    name: "edit",
+    label: "edit",
+    description:
+      "Replace strings in a UTF-8 text file. " +
+      "Prefer edit over write for changes to existing files.",
+    parameters: editSchema,
+    renderShell: "self",
+    effect: { kind: "writesPaths", paths: ({ path }) => [path] },
+    executionMode: "sequential",
+    async execute(_id, params, signal, _onUpdate, ctx) {
+      const { path, edits } = params as EditInput;
+
+      if (signal?.aborted) {
+        throw new Error("Edit aborted before execution.");
+      }
+
+      const absolutePath = Paths.resolve(path, ctx.cwd);
+      const outcome = await editFile(absolutePath, edits);
+
+      return {
+        content: [{ type: "text", text: formatEditSummary(path, outcome) }],
+        details: outcome,
+      };
+    },
+    toViewModel: editView,
+  });
+}

package/packages/core/src/extensions/edit/render.ts

@@ -0,0 +1,16 @@
+import type { ToolViewInput } from "../../shared/Tools";
+import { DiffBlocks } from "../../view/DiffBlocks";
+import type { ToolView } from "../../view/ViewBlock";
+import type { EditOutcome } from "./edit";
+import type { editSchema } from "./schema";
+
+type EditViewInput = ToolViewInput<typeof editSchema, EditOutcome>;
+
+export function editView({ args, result, cwd }: EditViewInput): ToolView {
+  return DiffBlocks.fileView({
+    label: "Edit",
+    path: typeof args?.path === "string" ? args.path : undefined,
+    cwd,
+    diff: result?.details?.diff,
+  });
+}

package/packages/core/src/extensions/edit/schema.ts

@@ -0,0 +1,37 @@
+import { type Static, Type } from "typebox";
+
+export const editSchema = Type.Object({
+  path: Type.String({
+    description: "Absolute or relative path to file (resolved against cwd).",
+  }),
+  edits: Type.Array(
+    Type.Object(
+      {
+        oldString: Type.String({
+          description:
+            "Use the actual file content without the `LINE:` prefix from read output. Must be unique unless replaceAll=true. Include enough surrounding context for uniqueness.",
+        }),
+        newString: Type.String({
+          description:
+            "Replacement text. Empty string deletes the matched range.",
+        }),
+        replaceAll: Type.Optional(
+          Type.Boolean({
+            description:
+              "If true, replaces every occurrence of oldString. Defaults to false.",
+          })
+        ),
+      },
+      { additionalProperties: false }
+    ),
+    {
+      minItems: 1,
+      description:
+        "Non-empty atomic batch of edits. Batched edits resolve against the initial file state and must not overlap. For sequential transformations where edit 2 depends on edit 1's result, use separate tool calls.",
+    }
+  ),
+});
+
+export type EditInput = Static<typeof editSchema>;
+
+export type RawEdit = EditInput["edits"][number];

package/packages/core/src/extensions/glob/glob.ts

@@ -0,0 +1,34 @@
+import { FileScanner, type FileScanOptions } from "../../shared/FileScanner";
+import { FsErrors } from "../../shared/FsErrors";
+
+export type GlobMatch = {
+  readonly path: string;
+  readonly mtime: number;
+};
+
+export type GlobScanOptions = FileScanOptions;
+
+export async function findFiles(
+  root: string,
+  pattern: string,
+  options: GlobScanOptions
+): Promise<readonly GlobMatch[]> {
+  const metadata = await FsErrors.statOrThrow(root);
+
+  if (!metadata.isDirectory()) {
+    throw new Error(
+      `Glob path must be a directory: ${root}. Drop "path" and put the filename in "pattern", or use the read tool to inspect a single file.`
+    );
+  }
+
+  const paths = await FileScanner.scan(root, pattern, options);
+  const matches: GlobMatch[] = paths.map((path) => ({
+    path,
+    mtime: Bun.file(path).lastModified,
+  }));
+
+  return matches.sort(
+    (left, right) =>
+      right.mtime - left.mtime || left.path.localeCompare(right.path)
+  );
+}

package/packages/core/src/extensions/glob/index.ts

@@ -0,0 +1,83 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+import { Paths } from "../../shared/Paths";
+import { Tools } from "../../shared/Tools";
+import { findFiles } from "./glob";
+import { globView, renderFiles } from "./render";
+import {
+  GLOB_HEAD_LIMIT_MAX,
+  type GlobInput,
+  type GlobPathFormat,
+  globSchema,
+} from "./schema";
+
+const DEFAULT_PATH_FORMAT: GlobPathFormat = "relative";
+
+export default function (pi: ExtensionAPI): void {
+  Tools.register(pi, {
+    name: "glob",
+    label: "glob",
+    description:
+      "Find files by glob pattern under a directory, sorted newest first. " +
+      "Skips gitignored paths and dotfiles unless requested. " +
+      "Use glob to enumerate files instead of bash with find, fd, ls -R, or similar.",
+    parameters: globSchema,
+    renderShell: "self",
+    effect: { kind: "readOnly" },
+    executionMode: "parallel",
+    async execute(_toolCallId, params, signal, _onUpdate, ctx) {
+      const {
+        pattern,
+        path,
+        exclude,
+        includeDotfiles,
+        includeIgnored,
+        pathFormat,
+        headLimit,
+      } = params as GlobInput;
+
+      if (signal?.aborted) {
+        throw new Error("Glob aborted before execution.");
+      }
+
+      const limit = headLimit ?? GLOB_HEAD_LIMIT_MAX;
+      const resolvedPathFormat = pathFormat ?? DEFAULT_PATH_FORMAT;
+      const absolutePath = Paths.resolve(path ?? ".", ctx.cwd);
+      const matches = await findFiles(absolutePath, pattern, {
+        exclude,
+        includeDotfiles: includeDotfiles ?? false,
+        includeIgnored: includeIgnored ?? false,
+      });
+      const outcome = renderFiles(matches, limit, {
+        cwd: ctx.cwd,
+        pathFormat: resolvedPathFormat,
+      });
+      const content: Array<{ type: "text"; text: string }> = [
+        { type: "text", text: outcome.body },
+      ];
+
+      if (outcome.truncated) {
+        content.push({
+          type: "text",
+          text: `[glob tool: showing ${outcome.visibleItems} of ${outcome.totalItems} entries; narrow the pattern or scope to a specific path to reduce results.]`,
+        });
+      }
+
+      return {
+        content,
+        details: {
+          absolutePath,
+          pattern,
+          exclude,
+          includeDotfiles: includeDotfiles ?? false,
+          includeIgnored: includeIgnored ?? false,
+          pathFormat: resolvedPathFormat,
+          fileCount: matches.length,
+          totalItems: outcome.totalItems,
+          visibleItems: outcome.visibleItems,
+          truncated: outcome.truncated,
+        },
+      };
+    },
+    toViewModel: globView,
+  });
+}

package/packages/core/src/extensions/glob/render.ts

@@ -0,0 +1,72 @@
+import { Format } from "../../shared/Format";
+import { Renderer } from "../../shared/Renderer";
+import { SearchRender, type SearchList } from "../../shared/SearchRender";
+import type { ToolViewInput } from "../../shared/Tools";
+import type { ToolView, ViewBlock } from "../../view/ViewBlock";
+import type { GlobMatch } from "./glob";
+import type {
+  GlobDetails,
+  GlobInput,
+  GlobPathFormat,
+  globSchema,
+} from "./schema";
+
+export type RenderOutcome = SearchList;
+
+export type RenderOptions = {
+  readonly cwd: string;
+  readonly pathFormat: GlobPathFormat;
+};
+
+export function renderFiles(
+  matches: readonly GlobMatch[],
+  headLimit: number,
+  options: RenderOptions
+): RenderOutcome {
+  return SearchRender.capList(
+    matches.map((match) => SearchRender.formatPath(match.path, options)),
+    headLimit
+  );
+}
+
+type GlobViewInput = ToolViewInput<typeof globSchema, GlobDetails>;
+
+export function globView({ args, result, cwd }: GlobViewInput): ToolView {
+  const input = (args ?? {}) as Partial<GlobInput>;
+  const fileCount = result?.details?.fileCount;
+  return {
+    label: "Glob",
+    icon: "search",
+    title: [
+      {
+        kind: "text",
+        text: SearchRender.subjectTitle({
+          subject: input.pattern ?? "...",
+          path: input.path,
+          cwd,
+        }),
+      },
+      ...(fileCount === undefined
+        ? []
+        : ([
+            {
+              kind: "text",
+              tone: "muted",
+              text: Format.count(fileCount, "file"),
+            },
+          ] as const)),
+    ],
+    body: formatBody(result),
+  };
+}
+
+function formatBody(result: GlobViewInput["result"]): readonly ViewBlock[] {
+  const text = Renderer.firstText(result);
+  if (text === "") {
+    return [];
+  }
+  if (result?.details?.fileCount === 0) {
+    return [{ kind: "text", text }];
+  }
+  return text.split("\n").map((path) => ({ kind: "file", path }));
+}