apply-edit 0.1.0 → 0.2.0

package/README.md

@@ -4,6 +4,8 @@ Apply the `oldString` → `newString` edits that language models produce, withou
 
 Coding agents ask a model for the exact text to replace. Models drift: wrong indentation, tabs for spaces, a trailing space, CRLF versus LF, typographic quotes, literal `\n` sequences. Exact matching then fails, and fuzzy matching quietly edits the wrong place. This package sits between the two: it tolerates the drift that can be resolved unambiguously, refuses everything else with a precise report, and never widens or relocates an edit.
 
+It also reads the other shape models return edits in: SEARCH/REPLACE blocks, in the aider, Cline and Roo Code dialects.
+
 Zero runtime dependencies. Strings in, strings out; no filesystem access. ESM, CommonJS and TypeScript declarations. Node 22+ and browsers.
 
 ```sh
@@ -61,6 +63,39 @@ The rules that make it safe to use in a loop:
 
 `applyEdits(text, edits)` resolves every edit against the original text, refuses overlapping edits, and applies all of them or none. `findEdit(text, oldString)` locates without changing anything.
 
+## SEARCH/REPLACE blocks
+
+Many agents prompt for edits as marker-delimited blocks instead of JSON. Three dialects are in wide use and they are not compatible: aider uses `<<<<<<< SEARCH` with the filename on a preceding line, Cline uses `------- SEARCH` / `+++++++ REPLACE`, and Roo Code adds `:start_line:` hints and backslash-escaped markers. `applyBlocks` reads all three and applies them through the same matcher.
+
+```js
+import {applyBlocks} from 'apply-edit';
+
+const payload = `------- SEARCH
+  const timeout = 500;
+=======
+  const timeout = 2_000;
++++++++ REPLACE`;
+
+const result = applyBlocks(file, payload);
+result.dialect;  // 'cline'
+result.text;     // the file with the edit applied
+```
+
+The dialect is detected from the markers and can be pinned with `{dialect: 'roo'}`. A payload that names several files is refused unless you say which one you are editing:
+
+```js
+applyBlocks(file, payload, {file: 'src/server.ts'});
+```
+
+Everything the matcher does for a single edit applies here: indentation drift is re-indented to the file, CRLF and BOM are preserved, an ambiguous block is refused with its candidate locations, and a Roo `:start_line:` hint selects between otherwise identical candidates. An unterminated block is reported rather than half-applied. An empty SEARCH section replaces the whole file, as Cline defines it.
+
+Use `parseBlocks` when you want the edits without applying them, for review or for routing across files:
+
+```js
+const {dialect, edits, problems} = parseBlocks(message, {files: knownPaths});
+// edits: [{file, oldString, newString, line?, endLine?, block: {line}}]
+```
+
 ## API
 
 ### `applyEdit(text, edit, options?)`
@@ -79,18 +114,36 @@ Returns `{ok: true, text, applied, lineEnding, bom}` or the first failure with i
 
 Returns `{ok: true, strategy, matches, lineEnding, bom}` or a failure.
 
+### `applyBlocks(text, blocks, options?)`
+
+`blocks`: the model message containing SEARCH/REPLACE blocks. `options` accepts the `applyEdit` options plus `{dialect?: 'aider' | 'cline' | 'roo', file?: string, files?: string[]}`. `file` selects which file's blocks to apply and is the default for blocks without a filename header; `files` helps resolve a header against known paths.
+
+Returns the `applyEdits` result with `dialect` added, or a failure whose `code` is one of the matcher codes or `parse` (with `problems`), `multiple-files` (with `files`), `no-blocks-for-file`.
+
+### `parseBlocks(text, options?)`
+
+Returns `{dialect, edits, problems}` without touching any file text. Each edit is `{file, oldString, newString, line?, endLine?, block: {line}}`; each problem is `{line, reason, detail}` with `reason` `missing-divider` or `missing-terminator`.
+
+### `detectDialect(text)`
+
+Returns `'aider'`, `'cline'`, `'roo'`, or `null` when the text contains no blocks.
+
 ## Limits
 
 - Escaped-sequence recovery is heuristic when the code itself contains literal backslash sequences; ambiguous inputs are refused rather than guessed.
 - Re-indentation maps replacement lines to matched lines by trimmed content and follows the previous anchor for new lines. Blocks that mix tabs and spaces within one line may keep the model's indentation; `reindented` and the diff tell you.
 - Matching is line-oriented above the exact tier. Reordered or paraphrased lines are misses, reported through `closest`.
 - This library does not read or write files, lock, or check that a file changed since it was read. Keep those in the tool.
-- Unified diffs, SEARCH/REPLACE block parsing and model-assisted correction are out of scope.
+- Dialect detection is a convenience: aider and Roo Code share markers, so a payload that uses Roo escaping without any Roo-only construct reads as aider. Pin `dialect` when you control the prompt.
+- Filename headers follow aider's heuristics and are only as good as what the model wrote; `parseBlocks` reports the name it took, and `applyBlocks` refuses a payload spanning several files rather than guessing.
+- Unified diffs and model-assisted correction are out of scope.
 
 ## Why not the usual fallback ladder
 
 On a seeded corpus of 1,942 constructed edits over 12 real source files (drifted indentation, tabs, trailing whitespace, CRLF, typographic punctuation, escaped newlines, plus decoys, duplicates, stale blocks and non-contiguous input), this implementation applied 1,286 edits with the expected output and made 0 wrong-location or false applications. A transcription of a widely copied nine-replacer fallback ladder applied 116 edits wrongly (mostly stale blocks silently overwritten) and produced 302 outputs with the model's wrong indentation inserted verbatim; the closest published library made 144 to 333 wrong applications depending on its fuzz setting. Method and numbers are in [docs/comparison.md](docs/comparison.md). The corpus is synthetic and seeded, built from real files; it is not a sample of model output.
 
+For the block parsing, a second corpus of 2,613 cases over 73 real source files in all three dialects (indentation drift, trailing whitespace, CRLF, BOM, absent and ambiguous search text, near misses, marker lines inside content, escaped markers, multi-block payloads in and out of order, line hints) was run against Cline's `constructNewFileContent`, `diff-apply` 1.0.6, aider's `editblock_coder` and a hand-rolled baseline. This package applied 2,010 payloads with the expected output, refused the 603 that must be refused, and made 0 wrong applications; the alternatives made 536, 67 and 14 wrong applications respectively on the dialects they support, and silently resolved 201, 134 and 67 ambiguous payloads. Method, per-category numbers and the reproduction commands are in [docs/blocks.md](docs/blocks.md). The corpus generator ships in `test/corpus/` and runs on every build.
+
 ## License
 
 MIT

package/dist/index.cjs

@@ -478,4 +478,189 @@ function applyEdits(text, edits, options = {}) {
   return {ok: true, text: splice(text, pieces), applied, lineEnding: doc.lineEnding, bom: doc.bom !== ''};
 }
 
-module.exports = {findEdit, applyEdit, applyEdits};
+// ---------------------------------------------------------------------------
+// SEARCH/REPLACE blocks: the shape models return when an agent prompts for edits as marker-delimited blocks.
+// Grammars follow aider (Aider-AI/aider), Cline (cline/cline) and Roo Code (RooCodeInc/Roo-Code).
+
+const DIALECTS = {
+  aider: {start: /^<{5,9} SEARCH>?\s*$/, divider: /^={5,9}\s*$/, end: /^>{5,9} REPLACE\s*$/, header: true, dividerEnds: true},
+  cline: {start: /^(?:-{3,}|<{3,}) SEARCH>?\s*$/, divider: /^={3,}\s*$/, end: /^(?:\+{3,}|>{3,}) REPLACE>?\s*$/},
+  roo: {start: /^<{7} SEARCH>?\s*$/, divider: /^={7}\s*$/, end: /^>{7} REPLACE\s*$/, hints: true, escapes: true},
+};
+const FENCE_LINE = /^\s*(?:```|~~~)/;
+const START_HINT = /^:start_line:\s*(\d+)\s*$/;
+const END_HINT = /^:end_line:\s*(\d+)\s*$/;
+const HINT_SEPARATOR = /^-{7}\s*$/;
+const CLINE_MARKER = /^(?:-{3,} SEARCH>?|\+{3,} REPLACE>?|<{3,4} SEARCH>?|>{3,4} REPLACE>?)\s*$/;
+const ROO_ONLY = /^(?::start_line:|:end_line:|\\(?:<{7}|>{7}|={7}|-{7}))/m;
+const ESCAPED_MARKER = /^\\(?=(?:<{3,}|>{3,}|={3,}|-{3,}|\+{3,}|:start_line:|:end_line:))/;
+
+function detectDialect(text) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  let aider = 0;
+  let cline = 0;
+  let roo = 0;
+  for (const raw of text.split('\n')) {
+    const line = raw.trimEnd();
+    if (CLINE_MARKER.test(line)) { cline++; continue; }
+    if (DIALECTS.roo.start.test(line)) { roo++; aider++; continue; }
+    if (DIALECTS.aider.start.test(line)) aider++;
+  }
+  if (cline > 0 && cline >= aider) return 'cline';
+  if (roo > 0 && ROO_ONLY.test(text)) return 'roo';
+  if (aider > 0) return 'aider';
+  if (cline > 0) return 'cline';
+  return null;
+}
+
+// Strips a repeated character from both ends without backtracking.
+function stripPaired(text, character) {
+  let start = 0;
+  let end = text.length;
+  while (start < end && text[start] === character) start++;
+  while (end > start && text[end - 1] === character) end--;
+  return start === 0 || end === text.length || start === end ? null : text.slice(start, end).trim();
+}
+
+function cleanHeader(line) {
+  let name = line.trim();
+  if (!name) return null;
+  name = name.replace(/^#+\s+/, '').replace(/[:,]$/, '');
+  if (name.startsWith('```') || name.startsWith('~~~')) {
+    // A fence carrying only a language token (```ts) names no file.
+    const rest = name.slice(3).trim();
+    name = /[./\\]/.test(rest) ? rest : '';
+  }
+  if (!name) return null;
+  for (let guard = 0; guard < 3; guard++) {
+    let unwrapped = null;
+    if (name.length > 4 && name.startsWith('**') && name.endsWith('**')) unwrapped = name.slice(2, -2).trim();
+    else if (name.length > 4 && name.startsWith('__') && name.endsWith('__')) unwrapped = name.slice(2, -2).trim();
+    else if (name.startsWith('`') && name.endsWith('`')) unwrapped = stripPaired(name, '`');
+    if (!unwrapped) break;
+    name = unwrapped;
+  }
+  if (!/^[\w./\\@+~-]+$/.test(name)) return null;
+  if (!/[./\\]/.test(name) && !/^[\w-]+$/.test(name)) return null;
+  return name;
+}
+
+function headerFilename(lines, at, known) {
+  const candidates = [];
+  for (let k = at - 1; k >= 0 && k >= at - 3; k--) {
+    const name = cleanHeader(lines[k]);
+    if (name) candidates.push(name);
+    if (!FENCE_LINE.test(lines[k]) && lines[k].trim() !== '') break;
+  }
+  if (candidates.length === 0) return null;
+  if (known && known.length) {
+    for (const name of candidates) if (known.includes(name)) return name;
+    for (const name of candidates) {
+      const match = known.find(file => file.endsWith('/' + name) || file.split(/[\\/]/).pop() === name);
+      if (match) return match;
+    }
+  }
+  return candidates.find(name => /\.[A-Za-z0-9]+$/.test(name)) ?? candidates[0];
+}
+
+/** Parse SEARCH/REPLACE blocks out of a model message into edits for applyEdits. */
+function parseBlocks(text, options = {}) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  const dialect = options.dialect ?? detectDialect(text) ?? 'aider';
+  const spec = DIALECTS[dialect];
+  if (!spec) throw new TypeError(`unknown dialect: ${options.dialect}`);
+  const known = Array.isArray(options.files) ? options.files : null;
+  const lines = text.split('\n');
+  const edits = [];
+  const problems = [];
+  let file = options.file ?? null;
+  let i = 0;
+  while (i < lines.length) {
+    if (!spec.start.test(lines[i].trimEnd())) { i++; continue; }
+    const opened = i;
+    if (spec.header) {
+      const named = headerFilename(lines, i, known);
+      if (named) file = named;
+    }
+    i++;
+    let line = null;
+    let endLine = null;
+    if (spec.hints) {
+      for (let guard = 0; guard < 2 && i < lines.length; guard++) {
+        const start = lines[i].trim().match(START_HINT);
+        const end = lines[i].trim().match(END_HINT);
+        if (start) { line = Number(start[1]); i++; continue; }
+        if (end) { endLine = Number(end[1]); i++; continue; }
+        break;
+      }
+      if (i < lines.length && HINT_SEPARATOR.test(lines[i].trim())) i++;
+    }
+    const search = [];
+    let divided = false;
+    while (i < lines.length) {
+      const candidate = lines[i].trimEnd();
+      if (spec.divider.test(candidate)) { divided = true; i++; break; }
+      if (spec.start.test(candidate) || spec.end.test(candidate)) break;
+      search.push(spec.escapes ? lines[i].replace(ESCAPED_MARKER, '') : lines[i]);
+      i++;
+    }
+    if (!divided) {
+      problems.push({line: opened + 1, reason: 'missing-divider', detail: `The block opened at line ${opened + 1} has no divider line.`});
+      continue;
+    }
+    const replace = [];
+    let closed = false;
+    while (i < lines.length) {
+      const candidate = lines[i].trimEnd();
+      if (spec.end.test(candidate)) { closed = true; i++; break; }
+      if (spec.start.test(candidate)) break;
+      if (spec.dividerEnds && spec.divider.test(candidate)) { closed = true; i++; break; }
+      replace.push(spec.escapes ? lines[i].replace(ESCAPED_MARKER, '') : lines[i]);
+      i++;
+    }
+    if (!closed) {
+      problems.push({line: opened + 1, reason: 'missing-terminator', detail: `The block opened at line ${opened + 1} has no REPLACE marker.`});
+      continue;
+    }
+    const edit = {file, oldString: search.join('\n'), newString: replace.join('\n'), block: {line: opened + 1}};
+    if (line !== null) edit.line = line;
+    if (endLine !== null) edit.endLine = endLine;
+    edits.push(edit);
+  }
+  return {dialect, edits, problems};
+}
+
+/** Parse SEARCH/REPLACE blocks and apply them to one file's text. */
+function applyBlocks(text, blocks, options = {}) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  const parsed = parseBlocks(blocks, options);
+  if (parsed.problems.length) {
+    return {ok: false, code: 'parse', message: parsed.problems[0].detail, dialect: parsed.dialect, problems: parsed.problems};
+  }
+  if (parsed.edits.length === 0) {
+    return {ok: false, code: 'parse', message: 'No SEARCH/REPLACE blocks were found.', dialect: parsed.dialect, problems: []};
+  }
+  const target = options.file ?? null;
+  const selected = target === null ? parsed.edits : parsed.edits.filter(edit => edit.file === null || edit.file === target);
+  const others = new Set(parsed.edits.filter(edit => !selected.includes(edit)).map(edit => edit.file));
+  if (target === null) {
+    const named = new Set(parsed.edits.map(edit => edit.file).filter(Boolean));
+    if (named.size > 1) {
+      return {ok: false, code: 'multiple-files', message: `The blocks target ${named.size} files (${[...named].join(', ')}); pass the file option to choose one.`, dialect: parsed.dialect, files: [...named]};
+    }
+  }
+  if (selected.length === 0) {
+    return {ok: false, code: 'no-blocks-for-file', message: `No blocks target ${target}; the payload targets ${[...others].join(', ') || 'no named file'}.`, dialect: parsed.dialect};
+  }
+  // An empty search section means "replace the whole file", as Cline defines it.
+  const whole = selected.find(edit => edit.oldString === '');
+  if (whole) return {ok: true, text: whole.newString, applied: [{index: selected.indexOf(whole), strategy: 'whole-file', matches: [], reindented: false, warnings: []}], lineEnding: prepare(text).lineEnding, bom: text.startsWith(''), dialect: parsed.dialect};
+  const result = applyEdits(text, selected.map(edit => {
+    const out = {oldString: edit.oldString, newString: edit.newString};
+    if (edit.line !== undefined) out.line = edit.line;
+    return out;
+  }), options);
+  return {...result, dialect: parsed.dialect};
+}
+
+module.exports = {findEdit, applyEdit, applyEdits, detectDialect, parseBlocks, applyBlocks};

package/dist/index.d.cts

@@ -113,3 +113,60 @@ export function applyEdit(text: string, edit: Edit, options?: Options): ApplyRes
 export function applyEdits(text: string, edits: Edit[], options?: Options): ApplyEditsResult | Failure;
 /** Locate oldString without changing anything. */
 export function findEdit(text: string, oldString: string, options?: Options): FindResult | Failure;
+
+/** SEARCH/REPLACE marker dialect. */
+export type Dialect = 'aider' | 'cline' | 'roo';
+
+export interface ParseOptions {
+  /** Pin the dialect instead of detecting it. */
+  dialect?: Dialect;
+  /** File the blocks apply to; also used as the default when a block carries no filename header. */
+  file?: string;
+  /** Known file paths, used to resolve a filename header (aider dialect). */
+  files?: readonly string[];
+}
+
+export interface ParsedBlock {
+  /** Filename from the header (aider), the `file` option, or null. */
+  file: string | null;
+  oldString: string;
+  newString: string;
+  /** `:start_line:` hint (Roo dialect). */
+  line?: number;
+  /** `:end_line:` hint (Roo dialect). */
+  endLine?: number;
+  /** Where the block starts in the parsed text, 1-based. */
+  block: {line: number};
+}
+
+export interface BlockProblem {
+  /** 1-based line of the block that could not be read. */
+  line: number;
+  reason: 'missing-divider' | 'missing-terminator';
+  detail: string;
+}
+
+export interface ParseResult {
+  dialect: Dialect;
+  edits: ParsedBlock[];
+  problems: BlockProblem[];
+}
+
+export interface BlockFailure {
+  ok: false;
+  code: 'parse' | 'multiple-files' | 'no-blocks-for-file';
+  message: string;
+  dialect: Dialect;
+  problems?: BlockProblem[];
+  files?: string[];
+}
+
+/** Detect which SEARCH/REPLACE dialect a message uses, or null when it contains no blocks. */
+export function detectDialect(text: string): Dialect | null;
+
+/** Parse SEARCH/REPLACE blocks out of a model message into edits for applyEdits. */
+export function parseBlocks(text: string, options?: ParseOptions): ParseResult;
+
+/** Parse SEARCH/REPLACE blocks and apply them to one file's text. */
+export function applyBlocks(text: string, blocks: string, options?: ParseOptions & Options): (ApplyEditsResult & {dialect: Dialect}) | (Failure & {dialect: Dialect}) | BlockFailure;
+

package/dist/index.d.mts

@@ -113,3 +113,60 @@ export function applyEdit(text: string, edit: Edit, options?: Options): ApplyRes
 export function applyEdits(text: string, edits: Edit[], options?: Options): ApplyEditsResult | Failure;
 /** Locate oldString without changing anything. */
 export function findEdit(text: string, oldString: string, options?: Options): FindResult | Failure;
+
+/** SEARCH/REPLACE marker dialect. */
+export type Dialect = 'aider' | 'cline' | 'roo';
+
+export interface ParseOptions {
+  /** Pin the dialect instead of detecting it. */
+  dialect?: Dialect;
+  /** File the blocks apply to; also used as the default when a block carries no filename header. */
+  file?: string;
+  /** Known file paths, used to resolve a filename header (aider dialect). */
+  files?: readonly string[];
+}
+
+export interface ParsedBlock {
+  /** Filename from the header (aider), the `file` option, or null. */
+  file: string | null;
+  oldString: string;
+  newString: string;
+  /** `:start_line:` hint (Roo dialect). */
+  line?: number;
+  /** `:end_line:` hint (Roo dialect). */
+  endLine?: number;
+  /** Where the block starts in the parsed text, 1-based. */
+  block: {line: number};
+}
+
+export interface BlockProblem {
+  /** 1-based line of the block that could not be read. */
+  line: number;
+  reason: 'missing-divider' | 'missing-terminator';
+  detail: string;
+}
+
+export interface ParseResult {
+  dialect: Dialect;
+  edits: ParsedBlock[];
+  problems: BlockProblem[];
+}
+
+export interface BlockFailure {
+  ok: false;
+  code: 'parse' | 'multiple-files' | 'no-blocks-for-file';
+  message: string;
+  dialect: Dialect;
+  problems?: BlockProblem[];
+  files?: string[];
+}
+
+/** Detect which SEARCH/REPLACE dialect a message uses, or null when it contains no blocks. */
+export function detectDialect(text: string): Dialect | null;
+
+/** Parse SEARCH/REPLACE blocks out of a model message into edits for applyEdits. */
+export function parseBlocks(text: string, options?: ParseOptions): ParseResult;
+
+/** Parse SEARCH/REPLACE blocks and apply them to one file's text. */
+export function applyBlocks(text: string, blocks: string, options?: ParseOptions & Options): (ApplyEditsResult & {dialect: Dialect}) | (Failure & {dialect: Dialect}) | BlockFailure;
+

package/dist/index.mjs

@@ -476,3 +476,188 @@ export function applyEdits(text, edits, options = {}) {
   }
   return {ok: true, text: splice(text, pieces), applied, lineEnding: doc.lineEnding, bom: doc.bom !== ''};
 }
+
+// ---------------------------------------------------------------------------
+// SEARCH/REPLACE blocks: the shape models return when an agent prompts for edits as marker-delimited blocks.
+// Grammars follow aider (Aider-AI/aider), Cline (cline/cline) and Roo Code (RooCodeInc/Roo-Code).
+
+const DIALECTS = {
+  aider: {start: /^<{5,9} SEARCH>?\s*$/, divider: /^={5,9}\s*$/, end: /^>{5,9} REPLACE\s*$/, header: true, dividerEnds: true},
+  cline: {start: /^(?:-{3,}|<{3,}) SEARCH>?\s*$/, divider: /^={3,}\s*$/, end: /^(?:\+{3,}|>{3,}) REPLACE>?\s*$/},
+  roo: {start: /^<{7} SEARCH>?\s*$/, divider: /^={7}\s*$/, end: /^>{7} REPLACE\s*$/, hints: true, escapes: true},
+};
+const FENCE_LINE = /^\s*(?:```|~~~)/;
+const START_HINT = /^:start_line:\s*(\d+)\s*$/;
+const END_HINT = /^:end_line:\s*(\d+)\s*$/;
+const HINT_SEPARATOR = /^-{7}\s*$/;
+const CLINE_MARKER = /^(?:-{3,} SEARCH>?|\+{3,} REPLACE>?|<{3,4} SEARCH>?|>{3,4} REPLACE>?)\s*$/;
+const ROO_ONLY = /^(?::start_line:|:end_line:|\\(?:<{7}|>{7}|={7}|-{7}))/m;
+const ESCAPED_MARKER = /^\\(?=(?:<{3,}|>{3,}|={3,}|-{3,}|\+{3,}|:start_line:|:end_line:))/;
+
+export function detectDialect(text) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  let aider = 0;
+  let cline = 0;
+  let roo = 0;
+  for (const raw of text.split('\n')) {
+    const line = raw.trimEnd();
+    if (CLINE_MARKER.test(line)) { cline++; continue; }
+    if (DIALECTS.roo.start.test(line)) { roo++; aider++; continue; }
+    if (DIALECTS.aider.start.test(line)) aider++;
+  }
+  if (cline > 0 && cline >= aider) return 'cline';
+  if (roo > 0 && ROO_ONLY.test(text)) return 'roo';
+  if (aider > 0) return 'aider';
+  if (cline > 0) return 'cline';
+  return null;
+}
+
+// Strips a repeated character from both ends without backtracking.
+function stripPaired(text, character) {
+  let start = 0;
+  let end = text.length;
+  while (start < end && text[start] === character) start++;
+  while (end > start && text[end - 1] === character) end--;
+  return start === 0 || end === text.length || start === end ? null : text.slice(start, end).trim();
+}
+
+function cleanHeader(line) {
+  let name = line.trim();
+  if (!name) return null;
+  name = name.replace(/^#+\s+/, '').replace(/[:,]$/, '');
+  if (name.startsWith('```') || name.startsWith('~~~')) {
+    // A fence carrying only a language token (```ts) names no file.
+    const rest = name.slice(3).trim();
+    name = /[./\\]/.test(rest) ? rest : '';
+  }
+  if (!name) return null;
+  for (let guard = 0; guard < 3; guard++) {
+    let unwrapped = null;
+    if (name.length > 4 && name.startsWith('**') && name.endsWith('**')) unwrapped = name.slice(2, -2).trim();
+    else if (name.length > 4 && name.startsWith('__') && name.endsWith('__')) unwrapped = name.slice(2, -2).trim();
+    else if (name.startsWith('`') && name.endsWith('`')) unwrapped = stripPaired(name, '`');
+    if (!unwrapped) break;
+    name = unwrapped;
+  }
+  if (!/^[\w./\\@+~-]+$/.test(name)) return null;
+  if (!/[./\\]/.test(name) && !/^[\w-]+$/.test(name)) return null;
+  return name;
+}
+
+function headerFilename(lines, at, known) {
+  const candidates = [];
+  for (let k = at - 1; k >= 0 && k >= at - 3; k--) {
+    const name = cleanHeader(lines[k]);
+    if (name) candidates.push(name);
+    if (!FENCE_LINE.test(lines[k]) && lines[k].trim() !== '') break;
+  }
+  if (candidates.length === 0) return null;
+  if (known && known.length) {
+    for (const name of candidates) if (known.includes(name)) return name;
+    for (const name of candidates) {
+      const match = known.find(file => file.endsWith('/' + name) || file.split(/[\\/]/).pop() === name);
+      if (match) return match;
+    }
+  }
+  return candidates.find(name => /\.[A-Za-z0-9]+$/.test(name)) ?? candidates[0];
+}
+
+/** Parse SEARCH/REPLACE blocks out of a model message into edits for applyEdits. */
+export function parseBlocks(text, options = {}) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  const dialect = options.dialect ?? detectDialect(text) ?? 'aider';
+  const spec = DIALECTS[dialect];
+  if (!spec) throw new TypeError(`unknown dialect: ${options.dialect}`);
+  const known = Array.isArray(options.files) ? options.files : null;
+  const lines = text.split('\n');
+  const edits = [];
+  const problems = [];
+  let file = options.file ?? null;
+  let i = 0;
+  while (i < lines.length) {
+    if (!spec.start.test(lines[i].trimEnd())) { i++; continue; }
+    const opened = i;
+    if (spec.header) {
+      const named = headerFilename(lines, i, known);
+      if (named) file = named;
+    }
+    i++;
+    let line = null;
+    let endLine = null;
+    if (spec.hints) {
+      for (let guard = 0; guard < 2 && i < lines.length; guard++) {
+        const start = lines[i].trim().match(START_HINT);
+        const end = lines[i].trim().match(END_HINT);
+        if (start) { line = Number(start[1]); i++; continue; }
+        if (end) { endLine = Number(end[1]); i++; continue; }
+        break;
+      }
+      if (i < lines.length && HINT_SEPARATOR.test(lines[i].trim())) i++;
+    }
+    const search = [];
+    let divided = false;
+    while (i < lines.length) {
+      const candidate = lines[i].trimEnd();
+      if (spec.divider.test(candidate)) { divided = true; i++; break; }
+      if (spec.start.test(candidate) || spec.end.test(candidate)) break;
+      search.push(spec.escapes ? lines[i].replace(ESCAPED_MARKER, '') : lines[i]);
+      i++;
+    }
+    if (!divided) {
+      problems.push({line: opened + 1, reason: 'missing-divider', detail: `The block opened at line ${opened + 1} has no divider line.`});
+      continue;
+    }
+    const replace = [];
+    let closed = false;
+    while (i < lines.length) {
+      const candidate = lines[i].trimEnd();
+      if (spec.end.test(candidate)) { closed = true; i++; break; }
+      if (spec.start.test(candidate)) break;
+      if (spec.dividerEnds && spec.divider.test(candidate)) { closed = true; i++; break; }
+      replace.push(spec.escapes ? lines[i].replace(ESCAPED_MARKER, '') : lines[i]);
+      i++;
+    }
+    if (!closed) {
+      problems.push({line: opened + 1, reason: 'missing-terminator', detail: `The block opened at line ${opened + 1} has no REPLACE marker.`});
+      continue;
+    }
+    const edit = {file, oldString: search.join('\n'), newString: replace.join('\n'), block: {line: opened + 1}};
+    if (line !== null) edit.line = line;
+    if (endLine !== null) edit.endLine = endLine;
+    edits.push(edit);
+  }
+  return {dialect, edits, problems};
+}
+
+/** Parse SEARCH/REPLACE blocks and apply them to one file's text. */
+export function applyBlocks(text, blocks, options = {}) {
+  if (typeof text !== 'string') throw new TypeError('text must be a string');
+  const parsed = parseBlocks(blocks, options);
+  if (parsed.problems.length) {
+    return {ok: false, code: 'parse', message: parsed.problems[0].detail, dialect: parsed.dialect, problems: parsed.problems};
+  }
+  if (parsed.edits.length === 0) {
+    return {ok: false, code: 'parse', message: 'No SEARCH/REPLACE blocks were found.', dialect: parsed.dialect, problems: []};
+  }
+  const target = options.file ?? null;
+  const selected = target === null ? parsed.edits : parsed.edits.filter(edit => edit.file === null || edit.file === target);
+  const others = new Set(parsed.edits.filter(edit => !selected.includes(edit)).map(edit => edit.file));
+  if (target === null) {
+    const named = new Set(parsed.edits.map(edit => edit.file).filter(Boolean));
+    if (named.size > 1) {
+      return {ok: false, code: 'multiple-files', message: `The blocks target ${named.size} files (${[...named].join(', ')}); pass the file option to choose one.`, dialect: parsed.dialect, files: [...named]};
+    }
+  }
+  if (selected.length === 0) {
+    return {ok: false, code: 'no-blocks-for-file', message: `No blocks target ${target}; the payload targets ${[...others].join(', ') || 'no named file'}.`, dialect: parsed.dialect};
+  }
+  // An empty search section means "replace the whole file", as Cline defines it.
+  const whole = selected.find(edit => edit.oldString === '');
+  if (whole) return {ok: true, text: whole.newString, applied: [{index: selected.indexOf(whole), strategy: 'whole-file', matches: [], reindented: false, warnings: []}], lineEnding: prepare(text).lineEnding, bom: text.startsWith(''), dialect: parsed.dialect};
+  const result = applyEdits(text, selected.map(edit => {
+    const out = {oldString: edit.oldString, newString: edit.newString};
+    if (edit.line !== undefined) out.line = edit.line;
+    return out;
+  }), options);
+  return {...result, dialect: parsed.dialect};
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apply-edit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Apply LLM-generated oldString/newString edits safely: tolerant matching with ambiguity refusal, match reports, re-indentation and CRLF/BOM preservation.",
   "type": "module",
   "main": "./dist/index.cjs",
@@ -43,7 +43,7 @@
   ],
   "scripts": {
     "build": "node scripts/build.mjs",
-    "test": "node --test test/api.test.mjs test/issues.test.mjs",
+    "test": "node --test test/api.test.mjs test/issues.test.mjs test/blocks.test.mjs test/corpus.test.mjs",
     "test:types": "tsc -p test/tsconfig.json",
     "test:pack": "node scripts/test-pack.mjs",
     "verify": "npm run build && npm test && npm run test:types && npm run test:pack",