tools/FileEditTool/ — Intelligent File Editing Tool

Contents

Architecture

flowchart TD
  A["Model tool_use: Edit"] --> B["validateInput()"]
  B -->|"ErrorCode 0-10"| C["Return validation error"]
  B -->|"valid"| D["checkPermissions()"]
  D -->|"deny"| E["Permission denied"]
  D -->|"allow"| F["call()"]
  F --> G["readFileForEdit()"]
  G --> H{"Staleness check"}
  H -->|"modified"| I["ErrorCode 8: re-read required"]
  H -->|"fresh"| J["findActualString()"]
  J --> K["preserveQuoteStyle()"]
  K --> L["getPatchForEdit()"]
  L --> M["writeTextContent()"]
  M --> N["LSP didChange + didSave"]
  N --> O["Return structuredPatch"]

Edit Validation Error Codes

flowchart LR
  V["validateInput()"] --> E0["0: old_str = new_str"]
  V --> E1["1: Permission denied"]
  V --> E2["2: UNC path"]
  V --> E3["3: File too large"]
  V --> E4["4: File not found"]
  V --> E5["5: File already exists"]
  V --> E6["6: Jupyter notebook"]
  V --> E7["7: File not read yet"]
  V --> E8["8: Modified since read"]
  V --> E9["9: String not found"]
  V --> E10["10: Multiple matches"]
  style E9 fill:#2a1a1a,stroke:#f85149
  style E10 fill:#2a1a1a,stroke:#f85149

Key Classes & Functions

Data Structures

Interactions

Atomicity & Critical Section

The edit pipeline is carefully structured to prevent race conditions. The critical section between staleness check and file write must be synchronous with no async yields:

1. Pre-critical (async allowed) — Skill discovery, directory creation, file history backup
2. Critical section (sync only) — Read file → check staleness → normalize quotes → apply edit → write to disk
3. Post-critical (async allowed) — LSP notifications, state updates, analytics logging, git diff

Source comments explicitly warn: “Do not add async operations between the staleness check and the write operation.”

Configuration

Directory Map

FileEditTool/
├── FileEditTool.ts     ← Main tool definition: call(), validateInput(), readFileForEdit()
├── UI.tsx              ← React components: userFacingName, diff rendering, rejection display
├── constants.ts        ← FILE_EDIT_TOOL_NAME, permission patterns, error messages
├── prompt.ts           ← System prompt: pre-read instruction, line prefix, replace_all docs
├── types.ts            ← Zod schemas: inputSchema, outputSchema, FileEditOutput, hunkSchema
└── utils.ts            ← Core logic: quote normalization, patch generation, edit equivalence

Deep-Dive Highlights

Core mechanisms from FileEditTool have been extracted into dedicated focus pages for in-depth exploration. Each page covers one algorithm, protocol, or subsystem with diagrams, code walks, and configuration details.

Deep-Dive Pages

Code Examples

Example: Quote-Aware String Matching

// utils.ts — Find actual string with curly-quote normalization
export function findActualString(
  fileContent: string,
  searchString: string,
): string | null {
  // 1. Try exact match first — most common case
  if (fileContent.includes(searchString)) {
    return searchString;
  }

  // 2. Normalize both sides: curly quotes → straight quotes
  const normalizedContent = normalizeQuotes(fileContent);
  const normalizedSearch = normalizeQuotes(searchString);

  const idx = normalizedContent.indexOf(normalizedSearch);
  if (idx === -1) return null;

  // 3. Extract actual substring from original file,
  //    preserving the curly quotes as they appear on disk
  return fileContent.substring(idx, idx + normalizedSearch.length);
}

// Preserve the file's quote style in the replacement text
export function preserveQuoteStyle(
  oldString: string,
  actualOldString: string,
  newString: string,
): string {
  // Detect which curly quotes the file uses
  // Apply same style to newString, handling:
  // - Opening vs closing context
  // - Apostrophes in contractions (letter + ' + letter)
  // - Single vs double quote types
  return transformedNewString;
}

Example: Atomic Edit Pipeline

// FileEditTool.ts — Core call() edit pipeline (simplified)
async call(input: FileEditInput, context): Promise<{ data: FileEditOutput }> {
  // Pre-edit: activate conditional skills (non-blocking)
  discoverSkillsForPath(input.file_path, context.dynamicSkillDirTriggers);

  // CRITICAL SECTION: no async yields between staleness check and write
  const { content, encoding, lineEndings } = readFileForEdit(input.file_path);

  // Staleness detection: timestamp-based, content fallback
  if (context.userModified(input.file_path)) {
    throw new Error(FILE_UNEXPECTEDLY_MODIFIED_ERROR);
  }

  // Quote normalization: find actual string preserving file's typography
  const actualOld = findActualString(content, input.old_string) ?? input.old_string;
  const actualNew = preserveQuoteStyle(input.old_string, actualOld, input.new_string);

  // Generate structured patch
  const { patch, updatedFile } = getPatchForEdit({
    filePath: input.file_path,
    fileContents: content,
    oldString: actualOld,
    newString: actualNew,
    replaceAll: input.replace_all,
  });

  // Write atomically with original encoding and line endings
  writeTextContent(input.file_path, updatedFile, { encoding, lineEndings });

  // Post-edit: LSP notifications (non-blocking failures)
  await lspManager.didChange(input.file_path, updatedFile);
  await lspManager.didSave(input.file_path);

  return { data: { filePath: input.file_path, structuredPatch: patch,
    originalFile: content, replaceAll: input.replace_all } };
}