@ladbabynpm/picc-edit 0.1.0

package/src/diff.ts

@@ -0,0 +1,209 @@
+// =============================================================================
+// picc-write — src/diff.ts
+//
+//
+// Adaptors vs upstream:
+//   - `countLinesChanged` is made pure (returns `{ added, removed }`) — no
+//     analytics / LOC counters / logging.
+//   - A local structural `Hunk` type stands in for `diff`'s
+//     `StructuredPatchHunk` (avoid importing from `diff`'s internal types).
+// =============================================================================
+
+import { diffLines, structuredPatch } from "diff";
+
+export const CONTEXT_LINES = 3;
+
+/** Structural type matching `diff`'s `StructuredPatchHunk`. */
+export interface Hunk {
+  oldStart: number;
+  oldLines: number;
+  newStart: number;
+  newLines: number;
+  lines: string[];
+  [key: string]: unknown;
+}
+
+// For some reason, & confuses the diff library, so we replace it with a token,
+// then substitute it back in after the diff is computed.
+const AMPERSAND_TOKEN = "<<:AMPERSAND_TOKEN:>>";
+const DOLLAR_TOKEN = "<<:DOLLAR_TOKEN:>>";
+
+function escapeForDiff(s: string): string {
+  return s.replaceAll("&", AMPERSAND_TOKEN).replaceAll("$", DOLLAR_TOKEN);
+}
+
+function unescapeFromDiff(s: string): string {
+  return s.replaceAll(AMPERSAND_TOKEN, "&").replaceAll(DOLLAR_TOKEN, "$");
+}
+
+/**
+ * Count lines added and removed in a patch. For new files, pass the content
+ * string as the second parameter (all lines count as additions).
+ */
+export function countLinesChanged(
+  patch: Hunk[],
+  newFileContent?: string,
+): { added: number; removed: number } {
+  let numAdditions = 0;
+  let numRemovals = 0;
+
+  if (patch.length === 0 && newFileContent) {
+    numAdditions = newFileContent.split(/\r?\n/).length;
+  } else {
+    for (const hunk of patch) {
+      for (const line of hunk.lines) {
+        if (line.startsWith("+")) numAdditions++;
+        else if (line.startsWith("-")) numRemovals++;
+      }
+    }
+  }
+
+  return { added: numAdditions, removed: numRemovals };
+}
+
+/**
+ * Generate a display-oriented diff string using a **unified** line-number
+ * counter (the new file's line number for all lines).
+ *
+ * Numbering rules:
+ *   - Context: ` NNN content`, counter advances
+ *   - Added:   `+NNN content`, counter advances
+ *   - Removed: `-NNN content`, counter does NOT advance
+ *
+ * Context collapsing mirrors pi's `generateDiffString`: only up to
+ * `contextLines` lines are shown before/after a change; larger gaps are
+ * replaced with a ` ...` marker.
+ */
+export function generateDisplayDiff(
+  oldContent: string,
+  newContent: string,
+  contextLines: number = CONTEXT_LINES,
+): string {
+  const parts = diffLines(oldContent, newContent);
+  const output: string[] = [];
+
+  const oldLines = oldContent.split("\n");
+  const newLines = newContent.split("\n");
+  const maxLineNum = Math.max(oldLines.length, newLines.length);
+  const lineNumWidth = String(maxLineNum).length;
+
+  let newLineNum = 1;
+  let lastWasChange = false;
+
+  for (let i = 0; i < parts.length; i++) {
+    const part = parts[i];
+    const raw = part.value.split("\n");
+    if (raw[raw.length - 1] === "") {
+      raw.pop();
+    }
+
+    if (part.added || part.removed) {
+      for (const line of raw) {
+        const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+        if (part.added) {
+          output.push(`+${lineNum} ${line}`);
+          newLineNum++;
+        } else {
+          output.push(`-${lineNum} ${line}`);
+        }
+      }
+      lastWasChange = true;
+    } else {
+      // Context lines — collapse large gaps
+      const nextPartIsChange =
+        i < parts.length - 1 && (parts[i + 1].added || parts[i + 1].removed);
+      const hasLeadingChange = lastWasChange;
+      const hasTrailingChange = nextPartIsChange;
+
+      if (hasLeadingChange && hasTrailingChange) {
+        if (raw.length <= contextLines * 2) {
+          for (const line of raw) {
+            const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+            output.push(` ${lineNum} ${line}`);
+            newLineNum++;
+          }
+        } else {
+          const leading = raw.slice(0, contextLines);
+          const trailing = raw.slice(raw.length - contextLines);
+          const skipped = raw.length - leading.length - trailing.length;
+          for (const line of leading) {
+            const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+            output.push(` ${lineNum} ${line}`);
+            newLineNum++;
+          }
+          output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+          newLineNum += skipped;
+          for (const line of trailing) {
+            const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+            output.push(` ${lineNum} ${line}`);
+            newLineNum++;
+          }
+        }
+      } else if (hasLeadingChange) {
+        const shown = raw.slice(0, contextLines);
+        const skipped = raw.length - shown.length;
+        for (const line of shown) {
+          const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+          output.push(` ${lineNum} ${line}`);
+          newLineNum++;
+        }
+        if (skipped > 0) {
+          output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+          newLineNum += skipped;
+        }
+      } else if (hasTrailingChange) {
+        const skipped = Math.max(0, raw.length - contextLines);
+        if (skipped > 0) {
+          output.push(` ${"".padStart(lineNumWidth, " ")} ...`);
+          newLineNum += skipped;
+        }
+        for (const line of raw.slice(skipped)) {
+          const lineNum = String(newLineNum).padStart(lineNumWidth, " ");
+          output.push(` ${lineNum} ${line}`);
+          newLineNum++;
+        }
+      } else {
+        newLineNum += raw.length;
+      }
+      lastWasChange = false;
+    }
+  }
+
+  return output.join("\n");
+}
+
+/**
+ * Compute a structured patch between two contents, with `&`/`$` escaped
+ * through the diff algorithm and unescaped on the returned lines.
+ */
+export function getPatchFromContents({
+  filePath,
+  oldContent,
+  newContent,
+  ignoreWhitespace = false,
+}: {
+  filePath: string;
+  oldContent: string;
+  newContent: string;
+  ignoreWhitespace?: boolean;
+}): Hunk[] {
+  const result = structuredPatch(
+    filePath,
+    filePath,
+    escapeForDiff(oldContent),
+    escapeForDiff(newContent),
+    undefined,
+    undefined,
+    {
+      ignoreWhitespace,
+      context: CONTEXT_LINES,
+    },
+  );
+  if (!result) {
+    return [];
+  }
+  return result.hunks.map((h) => ({
+    ...h,
+    lines: h.lines.map(unescapeFromDiff),
+  }));
+}

package/src/edit.ts

@@ -0,0 +1,283 @@
+// =============================================================================
+// picc-edit — src/edit.ts
+//
+// Behavior:
+//   - Existing file: must have been read this session (readState) and not
+//     modified since that read. `old_string` is matched (with quote
+//     normalization), must be unique unless `replace_all`.
+//   - `old_string === ''` on a missing file = create; on a non-empty existing
+//     file = error.
+//   - Writes with explicit LF handling (the model's sent line endings are
+//     respected as-is — no repo resampling).
+//   - Returns an `EditOutcome` with a structured patch (leading tabs → 2
+//     spaces, for display only) + `originalFile`.
+// =============================================================================
+
+import { mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import {
+  FILE_MODIFIED_SINCE_READ_ERROR,
+  FILE_NOT_READ_ERROR,
+} from "./constants.js";
+import { getPatchFromContents, type Hunk } from "./diff.js";
+import {
+  applyEditToFile,
+  findActualString,
+  preserveQuoteStyle,
+} from "./editUtils.js";
+import {
+  convertLeadingTabsToSpaces,
+  findSimilarFile,
+  getFileModificationTime,
+  type LineEndingType,
+  readFileSyncWithMetadata,
+  writeTextContent,
+} from "./file.js";
+import { expandPath } from "./path.js";
+import { readStateGet, readStateSet } from "./readState.js";
+
+export type EditInput = {
+  file_path: string;
+  old_string: string;
+  new_string: string;
+  replace_all?: boolean;
+};
+
+export type EditOutcome = {
+  filePath: string;
+  oldString: string;
+  newString: string;
+  originalFile: string;
+  /** Post-edit file content, with leading tabs converted to 2 spaces (display
+   * space, same content as was written). Used by the TUI diff viewer. */
+  newFile: string;
+  structuredPatch: Hunk[];
+  replaceAll: boolean;
+};
+
+/**
+ * Format the "Added N lines, removed M lines" summary line shown above the
+ * diff in the TUI, matching Claude Code's FileEditToolUpdatedMessage. Numbers
+ * are pluralized and the removal verb is lowercase when additions are present.
+ */
+export function editSummaryText(
+  additions: number,
+  removals: number,
+): string {
+  const parts: string[] = [];
+  if (additions > 0) {
+    parts.push(`Added ${additions} line${additions === 1 ? "" : "s"}`);
+  }
+  if (removals > 0) {
+    parts.push(
+      `${additions > 0 ? "removed" : "Removed"} ${removals} line${removals === 1 ? "" : "s"}`,
+    );
+  }
+  return parts.length > 0 ? parts.join(", ") : "Applied";
+}
+
+/** Thrown for read-guard / edit-validation failures with a model-facing msg. */
+export class EditGuardError extends Error {
+  // biome-ignore lint/complexity/noUselessConstructor: kept for `instanceof` semantics.
+  constructor(message: string) {
+    super(message);
+  }
+}
+
+function isEnoent(e: unknown): boolean {
+  return (
+    typeof e === "object" &&
+    e !== null &&
+    (e as NodeJS.ErrnoException).code === "ENOENT"
+  );
+}
+
+/**
+ * Read the current file state for editing. Returns `fileExists: false` with
+ * empty content for a missing file; rethrows non-ENOENT errors.
+ */
+function readFileForEdit(
+  absoluteFilePath: string,
+): {
+  content: string;
+  fileExists: boolean;
+  encoding: BufferEncoding;
+  lineEndings: LineEndingType;
+} {
+  try {
+    const meta = readFileSyncWithMetadata(absoluteFilePath);
+    return {
+      content: meta.content,
+      fileExists: true,
+      encoding: meta.encoding,
+      lineEndings: meta.lineEndings,
+    };
+  } catch (e) {
+    if (isEnoent(e)) {
+      return {
+        content: "",
+        fileExists: false,
+        encoding: "utf8",
+        lineEndings: "LF",
+      };
+    }
+    throw e;
+  }
+}
+
+/**
+ * Execute an edit, enforcing the read-first / modified-since-read guards and
+ * the string-match rules. Returns an `EditOutcome` (the write already
+ * performed), or throws `EditGuardError` (guards / match errors) / a plain
+ * `Error` (filesystem / OS errors).
+ */
+export async function editOutcome(
+  input: EditInput,
+  cwd: string,
+): Promise<EditOutcome> {
+  const { old_string, new_string, replace_all = false } = input;
+
+  const fullFilePath = expandPath(input.file_path, cwd);
+  const dir = dirname(fullFilePath);
+
+  // Ensure parent directory exists (outside the critical section).
+  await mkdir(dir, { recursive: true });
+
+  // SECURITY: skip filesystem ops for UNC paths to prevent NTLM credential
+  // leaks (permission layer would otherwise handle them).
+  if (fullFilePath.startsWith("\\\\") || fullFilePath.startsWith("//")) {
+    throw new EditGuardError(
+      `Cannot edit network path: ${fullFilePath}`,
+    );
+  }
+
+  if (old_string === new_string) {
+    throw new EditGuardError(
+      "No changes to make: old_string and new_string are exactly the same.",
+    );
+  }
+
+  const { content: originalContent, fileExists, encoding } =
+    readFileForEdit(fullFilePath);
+
+  // File doesn't exist:
+  //   - empty old_string → new file creation (valid)
+  //   - else → error, with a similar-file suggestion
+  if (!fileExists) {
+    if (old_string === "") {
+      const updatedFile = applyEditToFile(
+        originalContent,
+        old_string,
+        new_string,
+        replace_all,
+      );
+      writeTextContent(fullFilePath, updatedFile, encoding, "LF");
+      readStateSet(fullFilePath, {
+        content: updatedFile,
+        timestamp: getFileModificationTime(fullFilePath),
+      });
+      const patch = getPatchFromContents({
+        filePath: fullFilePath,
+        oldContent: convertLeadingTabsToSpaces(originalContent),
+        newContent: convertLeadingTabsToSpaces(updatedFile),
+      });
+      return {
+        filePath: input.file_path,
+        oldString: old_string,
+        newString: new_string,
+        originalFile: originalContent,
+        newFile: convertLeadingTabsToSpaces(updatedFile),
+        structuredPatch: patch,
+        replaceAll: replace_all,
+      };
+    }
+    const similar = findSimilarFile(fullFilePath);
+    let message = `File does not exist. Note: your current working directory is ${cwd}.`;
+    if (similar) {
+      message += ` Did you mean ${similar}?`;
+    }
+    throw new EditGuardError(message);
+  }
+
+  // File exists with empty old_string — only valid if the file is empty.
+  if (old_string === "") {
+    if (originalContent.trim() !== "") {
+      throw new EditGuardError(
+        "Cannot create new file - file already exists.",
+      );
+    }
+  }
+
+  // Read guard (existing file).
+  const lastRead = readStateGet(fullFilePath);
+  if (!lastRead || lastRead.offset !== undefined || lastRead.limit !== undefined) {
+    throw new EditGuardError(FILE_NOT_READ_ERROR);
+  }
+  const lastWriteTime = getFileModificationTime(fullFilePath);
+  if (
+    lastWriteTime > lastRead.timestamp &&
+    originalContent !== lastRead.content
+  ) {
+    throw new EditGuardError(FILE_MODIFIED_SINCE_READ_ERROR);
+  }
+
+  // Match the string (with quote normalization).
+  const actualOldString = findActualString(originalContent, old_string);
+  if (!actualOldString) {
+    throw new EditGuardError(
+      `String to replace not found in file.\nString: ${old_string}`,
+    );
+  }
+
+  const matches = originalContent.split(actualOldString).length - 1;
+  if (matches > 1 && !replace_all) {
+    throw new EditGuardError(
+      `Found ${matches} matches of the string to replace, but replace_all is false. To replace all occurrences, set replace_all to true. To replace only one occurrence, please provide more context to uniquely identify the instance.\nString: ${old_string}`,
+    );
+  }
+
+  // Apply the edit (preserving the file's curly-quote style).
+  const actualNewString = preserveQuoteStyle(
+    old_string,
+    actualOldString,
+    new_string,
+  );
+  const updatedFile = applyEditToFile(
+    originalContent,
+    actualOldString,
+    actualNewString,
+    replace_all,
+  );
+
+  if (updatedFile === originalContent) {
+    throw new EditGuardError(
+      "Original and edited file match exactly. Failed to apply edit.",
+    );
+  }
+
+  // Write to disk with LF handling.
+  writeTextContent(fullFilePath, updatedFile, encoding, "LF");
+
+  // Record this edit as a fresh full read (invalidates stale re-edits).
+  readStateSet(fullFilePath, {
+    content: updatedFile,
+    timestamp: getFileModificationTime(fullFilePath),
+  });
+
+  const newFile = convertLeadingTabsToSpaces(updatedFile);
+  const structuredPatch = getPatchFromContents({
+    filePath: fullFilePath,
+    oldContent: convertLeadingTabsToSpaces(originalContent),
+    newContent: newFile,
+  });
+
+  return {
+    filePath: input.file_path,
+    oldString: actualOldString,
+    newString: actualNewString,
+    originalFile: originalContent,
+    newFile,
+    structuredPatch,
+    replaceAll: replace_all,
+  };
+}

package/src/editUtils.ts

@@ -0,0 +1,203 @@
+// Claude can't output curly quotes, so we define them as constants here for
+// Claude to use in the code. We normalize curly quotes to straight quotes
+// when applying edits.
+export const LEFT_SINGLE_CURLY_QUOTE = "\u2018";
+export const RIGHT_SINGLE_CURLY_QUOTE = "\u2019";
+export const LEFT_DOUBLE_CURLY_QUOTE = "\u201c";
+export const RIGHT_DOUBLE_CURLY_QUOTE = "\u201d";
+
+/**
+ * Normalizes quotes in a string by converting curly quotes to straight quotes.
+ */
+export function normalizeQuotes(str: string): string {
+  return str
+    .replaceAll(LEFT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(RIGHT_SINGLE_CURLY_QUOTE, "'")
+    .replaceAll(LEFT_DOUBLE_CURLY_QUOTE, '"')
+    .replaceAll(RIGHT_DOUBLE_CURLY_QUOTE, '"');
+}
+
+/**
+ * Strips trailing whitespace from each line in a string while preserving line
+ * endings.
+ */
+export function stripTrailingWhitespace(str: string): string {
+  const lines = str.split(/(\r\n|\n|\r)/);
+
+  let result = "";
+  for (let i = 0; i < lines.length; i++) {
+    const part = lines[i];
+    if (part !== undefined) {
+      if (i % 2 === 0) {
+        // Even indices are line content
+        result += part.replace(/\s+$/, "");
+      } else {
+        // Odd indices are line endings
+        result += part;
+      }
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Finds the actual string in the file content that matches the search string,
+ * accounting for quote normalization.
+ */
+export function findActualString(
+  fileContent: string,
+  searchString: string,
+): string | null {
+  // First try exact match
+  if (fileContent.includes(searchString)) {
+    return searchString;
+  }
+
+  // Try with normalized quotes
+  const normalizedSearch = normalizeQuotes(searchString);
+  const normalizedFile = normalizeQuotes(fileContent);
+
+  const searchIndex = normalizedFile.indexOf(normalizedSearch);
+  if (searchIndex !== -1) {
+    // Find the actual string in the file that matches
+    return fileContent.substring(searchIndex, searchIndex + searchString.length);
+  }
+
+  return null;
+}
+
+/**
+ * When old_string matched via quote normalization (curly quotes in file,
+ * straight quotes from model), apply the same curly quote style to new_string
+ * so the edit preserves the file's typography.
+ */
+export function preserveQuoteStyle(
+  oldString: string,
+  actualOldString: string,
+  newString: string,
+): string {
+  // If they're the same, no normalization happened
+  if (oldString === actualOldString) {
+    return newString;
+  }
+
+  // Detect which curly quote types were in the file
+  const hasDoubleQuotes =
+    actualOldString.includes(LEFT_DOUBLE_CURLY_QUOTE) ||
+    actualOldString.includes(RIGHT_DOUBLE_CURLY_QUOTE);
+  const hasSingleQuotes =
+    actualOldString.includes(LEFT_SINGLE_CURLY_QUOTE) ||
+    actualOldString.includes(RIGHT_SINGLE_CURLY_QUOTE);
+
+  if (!hasDoubleQuotes && !hasSingleQuotes) {
+    return newString;
+  }
+
+  let result = newString;
+
+  if (hasDoubleQuotes) {
+    result = applyCurlyDoubleQuotes(result);
+  }
+  if (hasSingleQuotes) {
+    result = applyCurlySingleQuotes(result);
+  }
+
+  return result;
+}
+
+function isOpeningContext(chars: string[], index: number): boolean {
+  if (index === 0) {
+    return true;
+  }
+  const prev = chars[index - 1];
+  return (
+    prev === " " ||
+    prev === "\t" ||
+    prev === "\n" ||
+    prev === "\r" ||
+    prev === "(" ||
+    prev === "[" ||
+    prev === "{" ||
+    prev === "\u2014" || // em dash
+    prev === "\u2013" // en dash
+  );
+}
+
+function applyCurlyDoubleQuotes(str: string): string {
+  const chars = [...str];
+  const result: string[] = [];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === '"') {
+      result.push(
+        isOpeningContext(chars, i)
+          ? LEFT_DOUBLE_CURLY_QUOTE
+          : RIGHT_DOUBLE_CURLY_QUOTE,
+      );
+    } else {
+      result.push(chars[i]!);
+    }
+  }
+  return result.join("");
+}
+
+function applyCurlySingleQuotes(str: string): string {
+  const chars = [...str];
+  const result: string[] = [];
+  for (let i = 0; i < chars.length; i++) {
+    if (chars[i] === "'") {
+      // Don't convert apostrophes in contractions (e.g., "don't", "it's")
+      const prev = i > 0 ? chars[i - 1] : undefined;
+      const next = i < chars.length - 1 ? chars[i + 1] : undefined;
+      const prevIsLetter = prev !== undefined && /\p{L}/u.test(prev);
+      const nextIsLetter = next !== undefined && /\p{L}/u.test(next);
+      if (prevIsLetter && nextIsLetter) {
+        // Apostrophe in a contraction — use right single curly quote
+        result.push(RIGHT_SINGLE_CURLY_QUOTE);
+      } else {
+        result.push(
+          isOpeningContext(chars, i)
+            ? LEFT_SINGLE_CURLY_QUOTE
+            : RIGHT_SINGLE_CURLY_QUOTE,
+        );
+      }
+    } else {
+      result.push(chars[i]!);
+    }
+  }
+  return result.join("");
+}
+
+/**
+ * Applies a single edit to `originalContent`, returning the updated content.
+ *
+ * The replace callback uses the function form (`() => replace`) so that
+ * special `$` sequences in `newString` (`$&`, `$1`, ...) are treated
+ * literally rather than as replacement patterns.
+ *
+ * When deleting a line (`newString === ''`), a trailing newline is stripped
+ * from the removed region so we don't leave a blank line behind.
+ */
+export function applyEditToFile(
+  originalContent: string,
+  oldString: string,
+  newString: string,
+  replaceAll: boolean = false,
+): string {
+  const f = replaceAll
+    ? (content: string, search: string, replace: string) =>
+        content.replaceAll(search, () => replace)
+    : (content: string, search: string, replace: string) =>
+        content.replace(search, () => replace);
+
+  if (newString !== "") {
+    return f(originalContent, oldString, newString);
+  }
+
+  const stripTrailingNewline =
+    !oldString.endsWith("\n") && originalContent.includes(oldString + "\n");
+
+  return stripTrailingNewline
+    ? f(originalContent, oldString + "\n", newString)
+    : f(originalContent, oldString, newString);
+}