@aaroncql/pim-agent 0.0.1

package/src/extensions/edit/edit.test.ts

@@ -0,0 +1,285 @@
+import {
+  chmod,
+  link,
+  mkdtemp,
+  readFile,
+  rm,
+  stat,
+  symlink,
+  writeFile,
+} from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterAll, describe, expect, test } from "bun:test";
+import { editFile, formatEditSummary } from "./edit";
+import type { RawEdit } from "./schema";
+
+const tempRoots: string[] = [];
+
+const tempRoot = async (): Promise<string> => {
+  const root = await mkdtemp(join(tmpdir(), "pim-edit-tool-"));
+  tempRoots.push(root);
+  return root;
+};
+
+afterAll(async () => {
+  await Promise.all(
+    tempRoots.map((root) => rm(root, { force: true, recursive: true }))
+  );
+});
+
+describe("editFile", () => {
+  test("applies exact single edit", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta\ngamma", "utf8");
+
+    const outcome = await editFile(path, [
+      { oldString: "beta", newString: "delta" },
+    ]);
+
+    expect(await readFile(path, "utf8")).toBe("alpha\ndelta\ngamma");
+    expect(outcome.editCount).toBe(1);
+    expect(outcome.noops).toEqual([]);
+    expect(outcome.resolvedEdits[0]?.strategy).toBe("simple");
+    expect(formatEditSummary(path, outcome)).toBe(
+      `1 edit made to ${path}: lines 2.`
+    );
+  });
+
+  test("applies multi-edit batch against pre-batch content", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta\ngamma\ndelta", "utf8");
+
+    await editFile(path, [
+      { oldString: "beta", newString: "BETA" },
+      { oldString: "delta", newString: "DELTA" },
+    ]);
+
+    expect(await readFile(path, "utf8")).toBe("alpha\nBETA\ngamma\nDELTA");
+  });
+
+  test("rejects sequential transformations in one batch", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta", "utf8");
+
+    await expect(
+      editFile(path, [
+        { oldString: "beta", newString: "delta" },
+        { oldString: "delta", newString: "omega" },
+      ])
+    ).rejects.toThrow(/oldString was not found/);
+    expect(await readFile(path, "utf8")).toBe("alpha\nbeta");
+  });
+
+  test("rejects overlapping resolved ranges", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta\ngamma", "utf8");
+
+    await expect(
+      editFile(path, [
+        { oldString: "beta\ngamma", newString: "merged" },
+        { oldString: "gamma", newString: "changed" },
+      ])
+    ).rejects.toThrow(/target overlapping byte ranges/);
+    expect(await readFile(path, "utf8")).toBe("alpha\nbeta\ngamma");
+  });
+
+  test("replaceAll replaces all occurrences and lists every range", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "foo\nbar\nfoo", "utf8");
+
+    const outcome = await editFile(path, [
+      { oldString: "foo", newString: "baz", replaceAll: true },
+    ]);
+
+    expect(await readFile(path, "utf8")).toBe("baz\nbar\nbaz");
+    expect(outcome.ranges).toEqual(["1", "3"]);
+    expect(formatEditSummary(path, outcome)).toBe(
+      `1 edit made to ${path}: lines 1 and 3.`
+    );
+  });
+
+  test("replaceAll overlap with another edit is rejected", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "foo\nbar\nfoo", "utf8");
+
+    await expect(
+      editFile(path, [
+        { oldString: "foo", newString: "baz", replaceAll: true },
+        { oldString: "foo\nbar", newString: "merged" },
+      ])
+    ).rejects.toThrow(/target overlapping byte ranges/);
+  });
+
+  test("rejects duplicate edits", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta", "utf8");
+
+    const edit: RawEdit = { oldString: "beta", newString: "delta" };
+
+    await expect(editFile(path, [edit, edit])).rejects.toThrow(
+      /Edits 0 and 1 are identical/
+    );
+  });
+
+  test("rejects all-noop fuzzy batches and tracks partial noops", async () => {
+    const root = await tempRoot();
+    const noopPath = join(root, "noop.txt");
+    const partialPath = join(root, "partial.txt");
+    await writeFile(noopPath, "  beta", "utf8");
+    await writeFile(partialPath, "alpha\n  beta", "utf8");
+
+    await expect(
+      editFile(noopPath, [{ oldString: "beta ", newString: "  beta" }])
+    ).rejects.toThrow(/All edits were no-ops/);
+
+    const outcome = await editFile(partialPath, [
+      { oldString: "alpha", newString: "ALPHA" },
+      { oldString: "beta ", newString: "  beta" },
+    ]);
+
+    expect(await readFile(partialPath, "utf8")).toBe("ALPHA\n  beta");
+    expect(outcome.noops).toEqual([{ index: 1, range: "2" }]);
+  });
+
+  test("reports closest regions when oldString is not found", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "alpha\nbeta\ngamma", "utf8");
+
+    await expect(
+      editFile(path, [{ oldString: "betx", newString: "delta" }])
+    ).rejects.toThrow(/oldString was not found[\s\S]*lines 2/);
+  });
+
+  test("reports bare not found when nothing is close", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "aaaa\nbbbb", "utf8");
+
+    await expect(
+      editFile(path, [{ oldString: "zzzz", newString: "delta" }])
+    ).rejects.toThrow("oldString was not found in the file.");
+  });
+
+  test("rejects multiple matches without replaceAll", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "foo\nbar\nfoo", "utf8");
+
+    await expect(
+      editFile(path, [{ oldString: "foo", newString: "baz" }])
+    ).rejects.toThrow(/matched multiple regions/);
+  });
+
+  test("rejects escape drift after fuzzy match", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "  beta", "utf8");
+
+    await expect(
+      editFile(path, [{ oldString: "beta ", newString: "new\\nvalue" }])
+    ).rejects.toThrow(/newString contains literal escape text/);
+  });
+
+  test("preserves UTF-8 BOM when editing", async () => {
+    const root = await tempRoot();
+    const path = join(root, "bom.txt");
+    await writeFile(path, "\uFEFFalpha\nbeta", "utf8");
+
+    await editFile(path, [{ oldString: "beta", newString: "delta" }]);
+
+    const bytes = await Bun.file(path).bytes();
+    expect(Array.from(bytes.slice(0, 3))).toEqual([0xef, 0xbb, 0xbf]);
+    expect(await readFile(path, "utf8")).toBe("\uFEFFalpha\ndelta");
+  });
+
+  test("preserves CRLF line endings when editing", async () => {
+    const root = await tempRoot();
+    const path = join(root, "crlf.txt");
+    await writeFile(path, "alpha\r\nbeta\r\n", "utf8");
+
+    await editFile(path, [{ oldString: "beta", newString: "delta" }]);
+
+    expect(await readFile(path, "utf8")).toBe("alpha\r\ndelta\r\n");
+  });
+
+  test("updates symlink targets and preserves hard-link inodes plus mode", async () => {
+    const root = await tempRoot();
+    const target = join(root, "target.txt");
+    const linked = join(root, "linked.txt");
+    const alias = join(root, "alias.txt");
+
+    await writeFile(target, "alpha\nbeta", "utf8");
+    await chmod(target, 0o640);
+    await link(target, linked);
+    await symlink(target, alias);
+
+    const before = await stat(target);
+
+    await editFile(alias, [{ oldString: "beta", newString: "delta" }]);
+
+    const after = await stat(target);
+    expect(await readFile(target, "utf8")).toBe("alpha\ndelta");
+    expect(await readFile(linked, "utf8")).toBe("alpha\ndelta");
+    expect(after.ino).toBe(before.ino);
+    expect(Number(after.mode) & 0o777).toBe(0o640);
+  });
+
+  test("serializes concurrent edits on the same path", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    await writeFile(path, "0\n", "utf8");
+
+    const concurrent = await Promise.all([
+      editFile(path, [{ oldString: "0", newString: "0\n1" }]),
+      editFile(path, [{ oldString: "0", newString: "0\n2" }]),
+      editFile(path, [{ oldString: "0", newString: "0\n3" }]),
+    ]);
+
+    const final = await readFile(path, "utf8");
+    expect(final).toContain("0");
+    expect(concurrent).toHaveLength(3);
+  });
+
+  test("buildDiff splits distant edits into separate hunks", async () => {
+    const root = await tempRoot();
+    const path = join(root, "notes.txt");
+    const lines = Array.from(
+      { length: 200 },
+      (_, index) => `line ${index + 1}`
+    );
+    await writeFile(path, lines.join("\n"), "utf8");
+
+    const outcome = await editFile(path, [
+      { oldString: "line 1\nline 2", newString: "changed 1\nline 2" },
+      { oldString: "line 199\nline 200", newString: "line 199\nchanged 200" },
+    ]);
+
+    expect(outcome.diff?.hunks).toHaveLength(2);
+    expect(formatEditSummary(path, outcome)).toBe(
+      `2 edits made to ${path}: lines 1-2 and 199-200.`
+    );
+  });
+
+  test("rejects directories and binary files", async () => {
+    const root = await tempRoot();
+    const binary = join(root, "bin.dat");
+    await Bun.write(binary, new Uint8Array([0, 1, 2, 0, 4]));
+
+    await expect(
+      editFile(root, [{ oldString: "x", newString: "y" }])
+    ).rejects.toThrow(/Path is a directory/);
+
+    await expect(
+      editFile(binary, [{ oldString: "x", newString: "y" }])
+    ).rejects.toThrow(/binary file/);
+  });
+});

package/src/extensions/edit/edit.ts

@@ -0,0 +1,382 @@
+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 warnings: readonly string[];
+  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<void>>();
+
+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,
+    warnings: [],
+    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> {
+  if (metadata.nlink > 1) {
+    await Bun.write(canonicalPath, content);
+    return;
+  }
+  await Fs.writeAtomic(canonicalPath, content, Number(metadata.mode));
+}
+
+async function enqueue<T>(key: string, task: () => Promise<T>): Promise<T> {
+  const previous = editQueues.get(key) ?? Promise.resolve();
+  let release!: () => void;
+  const current = new Promise<void>((resolve) => {
+    release = resolve;
+  });
+
+  const queued = previous.then(
+    () => current,
+    () => current
+  );
+
+  editQueues.set(key, queued);
+
+  await previous.catch(() => undefined);
+
+  try {
+    return await task();
+  } finally {
+    release();
+
+    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)}`;
+}