blockpatch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 blockpatch contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,118 @@
+# blockpatch
+
+`blockpatch` v0 applies one anchored text move patch. It is not a generic diff tool, an AST refactor tool, a formatter, or a fuzzy matcher.
+
+The core invariant is simple: locate an exact source payload by surrounding anchors, remove those exact original bytes, and insert those same bytes at an independently located target anchor.
+
+## Install
+
+```sh
+npx blockpatch check patch.blockpatch
+npx blockpatch apply patch.blockpatch
+bunx blockpatch apply patch.blockpatch --dry-run
+npm install -g blockpatch
+```
+
+For local development:
+
+```sh
+bun install
+bun test
+bun run build
+bun run publish:dry
+```
+
+## Commands
+
+```sh
+blockpatch check patch.blockpatch
+blockpatch apply patch.blockpatch
+blockpatch apply patch.blockpatch --dry-run
+```
+
+`check` parses the patch and verifies it against the target file without writing. `apply --dry-run` does the same validation through the apply path without writing.
+
+## V0 Format
+
+```text
+*** Begin BlockPatch
+*** Move File: src/example.ts
+*** Source Before
+function alpha() {
+}
+
+*** Source Payload
+function movedThing() {
+  console.log("keep me exact");
+}
+
+*** Source After
+function omega() {
+}
+
+*** Target After
+constructor() {
+}
+
+*** End BlockPatch
+```
+
+`*** Target Before` is also supported:
+
+```text
+*** Target Before
+function omega() {
+}
+```
+
+Only one target marker is allowed.
+
+## Section Bytes
+
+Patch markers are ASCII lines. Section bytes are the bytes between one marker line and the next marker line, excluding the line ending immediately before the next marker.
+
+That means:
+
+- To encode section content ending in a newline, leave a blank line before the next marker.
+- To encode section content without a trailing newline, put the next marker on the following line without a blank line.
+- Source and target matching is byte-for-byte. No regex, no trimming, no indentation handling.
+
+## Semantics
+
+For one patch:
+
+1. Parse the `.blockpatch` file.
+2. Read `*** Move File` as bytes.
+3. Locate exactly one source match for `Source Before + Source Payload + Source After`.
+4. If that exact source is not found, locate a source envelope from `Source Before` to the next `Source After`; if exactly one envelope exists, fail with payload mismatch.
+5. Locate exactly one target anchor from `Target Before` or `Target After`.
+6. Fail if the target anchor overlaps the source payload bytes.
+7. Remove the original source payload bytes.
+8. Insert those exact original bytes before or after the target anchor.
+9. Write atomically by writing a temp file in the same directory, then renaming it over the original.
+
+## Failure Rules
+
+`blockpatch` exits non-zero and does not modify the file when:
+
+- the patch file is malformed
+- source anchors are missing
+- source anchors or full source are ambiguous
+- the located source payload does not exactly match `Source Payload`
+- the target anchor is missing
+- the target anchor is ambiguous
+- the target anchor overlaps the source payload
+- file I/O fails before the atomic rename
+
+## Intentionally Out Of Scope
+
+V0 does not implement:
+
+- fuzzy matching
+- AST parsing
+- code formatting
+- multi-file patches
+- copy operations
+- generated diffs
+- line numbers
+- regex anchors

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,350 @@
+#!/usr/bin/env node
+
+// src/cli.ts
+import { resolve as resolve2 } from "node:path";
+
+// src/errors.ts
+class BlockPatchError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BlockPatchError";
+    this.code = code;
+  }
+}
+function fail(code, message) {
+  throw new BlockPatchError(code, message);
+}
+
+// src/engine.ts
+import { randomBytes } from "node:crypto";
+import { chmod, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+// src/parser.ts
+var beginLine = "*** Begin BlockPatch";
+var sourceBeforeLine = "*** Source Before";
+var sourcePayloadLine = "*** Source Payload";
+var sourceAfterLine = "*** Source After";
+var targetBeforeLine = "*** Target Before";
+var targetAfterLine = "*** Target After";
+var endLine = "*** End BlockPatch";
+var moveFilePrefix = "*** Move File: ";
+function parseBlockPatch(input) {
+  const markers = collectMarkers(input);
+  const sequence = markers.map((marker) => marker.name);
+  const targetIndex = sequence.findIndex((name) => name === "targetBefore" || name === "targetAfter");
+  if (targetIndex === -1) {
+    fail("parse_error", "Patch must contain *** Target Before or *** Target After");
+  }
+  const expectedPrefix = ["begin", "moveFile", "sourceBefore", "sourcePayload", "sourceAfter"];
+  const expectedSuffix = ["end"];
+  const expected = [...expectedPrefix, sequence[targetIndex], ...expectedSuffix];
+  if (sequence.length !== expected.length || sequence.some((name, index) => name !== expected[index])) {
+    fail("parse_error", "Patch markers must appear in the v0 order");
+  }
+  const moveFile = markers[1];
+  const path = moveFile.value?.trim();
+  if (!path) {
+    fail("parse_error", "*** Move File must include a path");
+  }
+  const sourceBefore = section(input, markers[2], markers[3]);
+  const sourcePayload = section(input, markers[3], markers[4]);
+  const sourceAfter = section(input, markers[4], markers[5]);
+  const targetAnchor = section(input, markers[5], markers[6]);
+  const target = {
+    kind: markers[5].name === "targetBefore" ? "before" : "after",
+    anchor: targetAnchor
+  };
+  if (sourceBefore.length === 0) {
+    fail("parse_error", "*** Source Before must not be empty");
+  }
+  if (sourcePayload.length === 0) {
+    fail("parse_error", "*** Source Payload must not be empty");
+  }
+  if (sourceAfter.length === 0) {
+    fail("parse_error", "*** Source After must not be empty");
+  }
+  if (target.anchor.length === 0) {
+    fail("parse_error", "*** Target Before/After must not be empty");
+  }
+  return {
+    type: "move",
+    path,
+    sourceBefore,
+    sourcePayload,
+    sourceAfter,
+    target
+  };
+}
+function collectMarkers(input) {
+  const markers = [];
+  let position = 0;
+  while (position <= input.length) {
+    const lineStart = position;
+    const lf = input.indexOf(10, position);
+    const lineEnd = lf === -1 ? input.length : lf;
+    const contentStart = lf === -1 ? input.length : lf + 1;
+    const textEnd = lineEnd > lineStart && input[lineEnd - 1] === 13 ? lineEnd - 1 : lineEnd;
+    const line = input.subarray(lineStart, textEnd).toString("utf8");
+    const marker = markerForLine(line, lineStart, contentStart);
+    if (marker !== undefined) {
+      markers.push(marker);
+    }
+    if (lf === -1) {
+      break;
+    }
+    position = lf + 1;
+  }
+  if (markers.length === 0) {
+    fail("parse_error", "Patch does not contain BlockPatch markers");
+  }
+  return markers;
+}
+function markerForLine(line, lineStart, contentStart) {
+  if (line === beginLine)
+    return { name: "begin", lineStart, contentStart };
+  if (line.startsWith(moveFilePrefix)) {
+    return { name: "moveFile", value: line.slice(moveFilePrefix.length), lineStart, contentStart };
+  }
+  if (line === sourceBeforeLine)
+    return { name: "sourceBefore", lineStart, contentStart };
+  if (line === sourcePayloadLine)
+    return { name: "sourcePayload", lineStart, contentStart };
+  if (line === sourceAfterLine)
+    return { name: "sourceAfter", lineStart, contentStart };
+  if (line === targetBeforeLine)
+    return { name: "targetBefore", lineStart, contentStart };
+  if (line === targetAfterLine)
+    return { name: "targetAfter", lineStart, contentStart };
+  if (line === endLine)
+    return { name: "end", lineStart, contentStart };
+  return;
+}
+function section(input, marker, nextMarker) {
+  let end = nextMarker.lineStart;
+  if (end > marker.contentStart && input[end - 1] === 10) {
+    end -= 1;
+    if (end > marker.contentStart && input[end - 1] === 13) {
+      end -= 1;
+    }
+  }
+  return Buffer.from(input.subarray(marker.contentStart, end));
+}
+
+// src/engine.ts
+async function checkPatchFile(patchPath, options = {}) {
+  return runPatchFile(patchPath, { ...options, dryRun: true });
+}
+async function applyPatchFile(patchPath, options = {}) {
+  return runPatchFile(patchPath, options);
+}
+async function runPatchFile(patchPath, options) {
+  const cwd = options.cwd ?? process.cwd();
+  const patchBytes = await readFile(resolve(cwd, patchPath));
+  const patch = parseBlockPatch(patchBytes);
+  const changedPath = await applyMovePatch(patch, cwd, options.dryRun ?? false);
+  return { changed: [changedPath] };
+}
+async function applyMovePatch(patch, cwd, dryRun) {
+  const absolutePath = resolve(cwd, patch.path);
+  const original = await readFile(absolutePath);
+  const selection = selectMove(original, patch);
+  const next = applyMove(original, selection);
+  if (!dryRun && !next.equals(original)) {
+    await writeAtomic(absolutePath, next);
+  }
+  return patch.path;
+}
+function selectMove(file, patch) {
+  const source = findSourceRange(file, patch);
+  const target = findTarget(file, patch);
+  if (rangesOverlap(source, target.range)) {
+    fail("target_overlaps_source", `Target anchor for ${patch.path} overlaps the source block`);
+  }
+  return {
+    source,
+    target,
+    payload: Buffer.from(file.subarray(source.start, source.end))
+  };
+}
+function applyMove(file, selection) {
+  const withoutSource = Buffer.concat([
+    file.subarray(0, selection.source.start),
+    file.subarray(selection.source.end)
+  ]);
+  const targetIndex = selection.target.insertIndex > selection.source.end ? selection.target.insertIndex - selection.payload.length : selection.target.insertIndex;
+  return Buffer.concat([
+    withoutSource.subarray(0, targetIndex),
+    selection.payload,
+    withoutSource.subarray(targetIndex)
+  ]);
+}
+function findSourceRange(file, patch) {
+  const fullSource = Buffer.concat([patch.sourceBefore, patch.sourcePayload, patch.sourceAfter]);
+  const fullMatches = indexesOf(file, fullSource);
+  if (fullMatches.length === 1) {
+    const start = fullMatches[0] + patch.sourceBefore.length;
+    return { start, end: start + patch.sourcePayload.length };
+  }
+  if (fullMatches.length > 1) {
+    fail("source_ambiguous", `Source block is ambiguous in ${patch.path}; matched ${fullMatches.length} locations`);
+  }
+  const envelopes = findSourceEnvelopes(file, patch);
+  if (envelopes.length === 1) {
+    fail("payload_mismatch", `Source payload does not match located source anchors in ${patch.path}`);
+  }
+  if (envelopes.length > 1) {
+    fail("source_ambiguous", `Source anchors are ambiguous in ${patch.path}; matched ${envelopes.length} locations`);
+  }
+  fail("source_not_found", `Source anchors were not found in ${patch.path}`);
+}
+function findSourceEnvelopes(file, patch) {
+  const beforeMatches = indexesOf(file, patch.sourceBefore);
+  const afterMatches = indexesOf(file, patch.sourceAfter);
+  const ranges = [];
+  for (const beforeStart of beforeMatches) {
+    const payloadStart = beforeStart + patch.sourceBefore.length;
+    const afterStart = afterMatches.find((candidate) => candidate >= payloadStart);
+    if (afterStart !== undefined) {
+      ranges.push({ start: payloadStart, end: afterStart });
+    }
+  }
+  return ranges;
+}
+function findTarget(file, patch) {
+  const matches = indexesOf(file, patch.target.anchor);
+  if (matches.length === 0) {
+    fail("target_not_found", `Target anchor was not found in ${patch.path}`);
+  }
+  if (matches.length > 1) {
+    fail("target_ambiguous", `Target anchor is ambiguous in ${patch.path}; matched ${matches.length} locations`);
+  }
+  const start = matches[0];
+  const end = start + patch.target.anchor.length;
+  return {
+    range: { start, end },
+    insertIndex: patch.target.kind === "before" ? start : end
+  };
+}
+function indexesOf(haystack, needle) {
+  if (needle.length === 0) {
+    return [];
+  }
+  const indexes = [];
+  let index = haystack.indexOf(needle);
+  while (index !== -1) {
+    indexes.push(index);
+    index = haystack.indexOf(needle, index + 1);
+  }
+  return indexes;
+}
+function rangesOverlap(left, right) {
+  return left.start < right.end && right.start < left.end;
+}
+async function writeAtomic(path, bytes) {
+  const info = await stat(path);
+  const dir = dirname(path);
+  const base = basename(path);
+  const temp = join(dir, `.${base}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+  try {
+    await writeFile(temp, bytes, { flag: "wx" });
+    await chmod(temp, info.mode);
+    await rename(temp, path);
+  } catch (error) {
+    await unlink(temp).catch(() => {
+      return;
+    });
+    throw error;
+  }
+}
+
+// src/cli.ts
+async function main(argv) {
+  const options = parseArgs(argv);
+  if (options.command === "help") {
+    printHelp();
+    return 0;
+  }
+  if (options.command === "version") {
+    console.log("blockpatch 0.1.0");
+    return 0;
+  }
+  if (options.patchPath === undefined) {
+    throw new BlockPatchError("missing_patch", "Missing patch file path");
+  }
+  const result = options.command === "check" ? await checkPatchFile(options.patchPath, { cwd: options.cwd }) : await applyPatchFile(options.patchPath, {
+    cwd: options.cwd,
+    dryRun: options.dryRun
+  });
+  const verb = options.command === "check" || options.dryRun ? "would change" : "changed";
+  for (const path of result.changed) {
+    console.log(`${verb} ${path}`);
+  }
+  return 0;
+}
+function parseArgs(argv) {
+  const args = [...argv];
+  const first = args.shift();
+  if (first === undefined || first === "help" || first === "--help" || first === "-h") {
+    return { command: "help", cwd: process.cwd(), dryRun: false };
+  }
+  if (first === "version" || first === "--version" || first === "-v") {
+    return { command: "version", cwd: process.cwd(), dryRun: false };
+  }
+  if (first !== "apply" && first !== "check") {
+    throw new BlockPatchError("unknown_command", `Unknown command: ${first}`);
+  }
+  let cwd = process.cwd();
+  let dryRun = false;
+  let patchPath;
+  while (args.length > 0) {
+    const arg = args.shift();
+    if (arg === "--dry-run") {
+      dryRun = true;
+      continue;
+    }
+    if (arg === "--cwd") {
+      const value = args.shift();
+      if (value === undefined) {
+        throw new BlockPatchError("missing_cwd", "Missing value for --cwd");
+      }
+      cwd = resolve2(value);
+      continue;
+    }
+    if (arg?.startsWith("--cwd=")) {
+      cwd = resolve2(arg.slice("--cwd=".length));
+      continue;
+    }
+    if (arg?.startsWith("-")) {
+      throw new BlockPatchError("unknown_option", `Unknown option: ${arg}`);
+    }
+    if (patchPath !== undefined) {
+      throw new BlockPatchError("too_many_args", `Unexpected argument: ${arg}`);
+    }
+    patchPath = arg;
+  }
+  if (first === "check" && dryRun) {
+    throw new BlockPatchError("invalid_option", "--dry-run is only valid with apply");
+  }
+  return { command: first, patchPath, cwd, dryRun };
+}
+function printHelp() {
+  console.log(`blockpatch
+
+Usage:
+  blockpatch check <patch.blockpatch> [--cwd <dir>]
+  blockpatch apply <patch.blockpatch> [--cwd <dir>] [--dry-run]
+  blockpatch version
+`);
+}
+main(process.argv.slice(2)).then((code) => {
+  process.exitCode = code;
+}, (error) => {
+  if (error instanceof BlockPatchError) {
+    console.error(`blockpatch: ${error.message}`);
+    process.exitCode = 1;
+    return;
+  }
+  throw error;
+});

package/dist/engine.d.ts

@@ -0,0 +1,19 @@
+import type { ApplyOptions, ApplyResult, BlockPatch } from "./types";
+interface ByteRange {
+    start: number;
+    end: number;
+}
+interface TargetSelection {
+    range: ByteRange;
+    insertIndex: number;
+}
+interface MoveSelection {
+    source: ByteRange;
+    target: TargetSelection;
+    payload: Buffer;
+}
+export declare function checkPatchFile(patchPath: string, options?: ApplyOptions): Promise<ApplyResult>;
+export declare function applyPatchFile(patchPath: string, options?: ApplyOptions): Promise<ApplyResult>;
+export declare function selectMove(file: Buffer, patch: BlockPatch): MoveSelection;
+export declare function applyMove(file: Buffer, selection: MoveSelection): Buffer;
+export {};

package/dist/errors.d.ts

@@ -0,0 +1,5 @@
+export declare class BlockPatchError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+}
+export declare function fail(code: string, message: string): never;

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { applyMove, applyPatchFile, checkPatchFile, selectMove } from "./engine";
+export { BlockPatchError } from "./errors";
+export { parseBlockPatch } from "./parser";
+export type { ApplyOptions, ApplyResult, BlockPatch, TargetAnchor, TargetKind } from "./types";

package/dist/index.js

@@ -0,0 +1,263 @@
+// src/engine.ts
+import { randomBytes } from "node:crypto";
+import { chmod, readFile, rename, stat, unlink, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+// src/errors.ts
+class BlockPatchError extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "BlockPatchError";
+    this.code = code;
+  }
+}
+function fail(code, message) {
+  throw new BlockPatchError(code, message);
+}
+
+// src/parser.ts
+var beginLine = "*** Begin BlockPatch";
+var sourceBeforeLine = "*** Source Before";
+var sourcePayloadLine = "*** Source Payload";
+var sourceAfterLine = "*** Source After";
+var targetBeforeLine = "*** Target Before";
+var targetAfterLine = "*** Target After";
+var endLine = "*** End BlockPatch";
+var moveFilePrefix = "*** Move File: ";
+function parseBlockPatch(input) {
+  const markers = collectMarkers(input);
+  const sequence = markers.map((marker) => marker.name);
+  const targetIndex = sequence.findIndex((name) => name === "targetBefore" || name === "targetAfter");
+  if (targetIndex === -1) {
+    fail("parse_error", "Patch must contain *** Target Before or *** Target After");
+  }
+  const expectedPrefix = ["begin", "moveFile", "sourceBefore", "sourcePayload", "sourceAfter"];
+  const expectedSuffix = ["end"];
+  const expected = [...expectedPrefix, sequence[targetIndex], ...expectedSuffix];
+  if (sequence.length !== expected.length || sequence.some((name, index) => name !== expected[index])) {
+    fail("parse_error", "Patch markers must appear in the v0 order");
+  }
+  const moveFile = markers[1];
+  const path = moveFile.value?.trim();
+  if (!path) {
+    fail("parse_error", "*** Move File must include a path");
+  }
+  const sourceBefore = section(input, markers[2], markers[3]);
+  const sourcePayload = section(input, markers[3], markers[4]);
+  const sourceAfter = section(input, markers[4], markers[5]);
+  const targetAnchor = section(input, markers[5], markers[6]);
+  const target = {
+    kind: markers[5].name === "targetBefore" ? "before" : "after",
+    anchor: targetAnchor
+  };
+  if (sourceBefore.length === 0) {
+    fail("parse_error", "*** Source Before must not be empty");
+  }
+  if (sourcePayload.length === 0) {
+    fail("parse_error", "*** Source Payload must not be empty");
+  }
+  if (sourceAfter.length === 0) {
+    fail("parse_error", "*** Source After must not be empty");
+  }
+  if (target.anchor.length === 0) {
+    fail("parse_error", "*** Target Before/After must not be empty");
+  }
+  return {
+    type: "move",
+    path,
+    sourceBefore,
+    sourcePayload,
+    sourceAfter,
+    target
+  };
+}
+function collectMarkers(input) {
+  const markers = [];
+  let position = 0;
+  while (position <= input.length) {
+    const lineStart = position;
+    const lf = input.indexOf(10, position);
+    const lineEnd = lf === -1 ? input.length : lf;
+    const contentStart = lf === -1 ? input.length : lf + 1;
+    const textEnd = lineEnd > lineStart && input[lineEnd - 1] === 13 ? lineEnd - 1 : lineEnd;
+    const line = input.subarray(lineStart, textEnd).toString("utf8");
+    const marker = markerForLine(line, lineStart, contentStart);
+    if (marker !== undefined) {
+      markers.push(marker);
+    }
+    if (lf === -1) {
+      break;
+    }
+    position = lf + 1;
+  }
+  if (markers.length === 0) {
+    fail("parse_error", "Patch does not contain BlockPatch markers");
+  }
+  return markers;
+}
+function markerForLine(line, lineStart, contentStart) {
+  if (line === beginLine)
+    return { name: "begin", lineStart, contentStart };
+  if (line.startsWith(moveFilePrefix)) {
+    return { name: "moveFile", value: line.slice(moveFilePrefix.length), lineStart, contentStart };
+  }
+  if (line === sourceBeforeLine)
+    return { name: "sourceBefore", lineStart, contentStart };
+  if (line === sourcePayloadLine)
+    return { name: "sourcePayload", lineStart, contentStart };
+  if (line === sourceAfterLine)
+    return { name: "sourceAfter", lineStart, contentStart };
+  if (line === targetBeforeLine)
+    return { name: "targetBefore", lineStart, contentStart };
+  if (line === targetAfterLine)
+    return { name: "targetAfter", lineStart, contentStart };
+  if (line === endLine)
+    return { name: "end", lineStart, contentStart };
+  return;
+}
+function section(input, marker, nextMarker) {
+  let end = nextMarker.lineStart;
+  if (end > marker.contentStart && input[end - 1] === 10) {
+    end -= 1;
+    if (end > marker.contentStart && input[end - 1] === 13) {
+      end -= 1;
+    }
+  }
+  return Buffer.from(input.subarray(marker.contentStart, end));
+}
+
+// src/engine.ts
+async function checkPatchFile(patchPath, options = {}) {
+  return runPatchFile(patchPath, { ...options, dryRun: true });
+}
+async function applyPatchFile(patchPath, options = {}) {
+  return runPatchFile(patchPath, options);
+}
+async function runPatchFile(patchPath, options) {
+  const cwd = options.cwd ?? process.cwd();
+  const patchBytes = await readFile(resolve(cwd, patchPath));
+  const patch = parseBlockPatch(patchBytes);
+  const changedPath = await applyMovePatch(patch, cwd, options.dryRun ?? false);
+  return { changed: [changedPath] };
+}
+async function applyMovePatch(patch, cwd, dryRun) {
+  const absolutePath = resolve(cwd, patch.path);
+  const original = await readFile(absolutePath);
+  const selection = selectMove(original, patch);
+  const next = applyMove(original, selection);
+  if (!dryRun && !next.equals(original)) {
+    await writeAtomic(absolutePath, next);
+  }
+  return patch.path;
+}
+function selectMove(file, patch) {
+  const source = findSourceRange(file, patch);
+  const target = findTarget(file, patch);
+  if (rangesOverlap(source, target.range)) {
+    fail("target_overlaps_source", `Target anchor for ${patch.path} overlaps the source block`);
+  }
+  return {
+    source,
+    target,
+    payload: Buffer.from(file.subarray(source.start, source.end))
+  };
+}
+function applyMove(file, selection) {
+  const withoutSource = Buffer.concat([
+    file.subarray(0, selection.source.start),
+    file.subarray(selection.source.end)
+  ]);
+  const targetIndex = selection.target.insertIndex > selection.source.end ? selection.target.insertIndex - selection.payload.length : selection.target.insertIndex;
+  return Buffer.concat([
+    withoutSource.subarray(0, targetIndex),
+    selection.payload,
+    withoutSource.subarray(targetIndex)
+  ]);
+}
+function findSourceRange(file, patch) {
+  const fullSource = Buffer.concat([patch.sourceBefore, patch.sourcePayload, patch.sourceAfter]);
+  const fullMatches = indexesOf(file, fullSource);
+  if (fullMatches.length === 1) {
+    const start = fullMatches[0] + patch.sourceBefore.length;
+    return { start, end: start + patch.sourcePayload.length };
+  }
+  if (fullMatches.length > 1) {
+    fail("source_ambiguous", `Source block is ambiguous in ${patch.path}; matched ${fullMatches.length} locations`);
+  }
+  const envelopes = findSourceEnvelopes(file, patch);
+  if (envelopes.length === 1) {
+    fail("payload_mismatch", `Source payload does not match located source anchors in ${patch.path}`);
+  }
+  if (envelopes.length > 1) {
+    fail("source_ambiguous", `Source anchors are ambiguous in ${patch.path}; matched ${envelopes.length} locations`);
+  }
+  fail("source_not_found", `Source anchors were not found in ${patch.path}`);
+}
+function findSourceEnvelopes(file, patch) {
+  const beforeMatches = indexesOf(file, patch.sourceBefore);
+  const afterMatches = indexesOf(file, patch.sourceAfter);
+  const ranges = [];
+  for (const beforeStart of beforeMatches) {
+    const payloadStart = beforeStart + patch.sourceBefore.length;
+    const afterStart = afterMatches.find((candidate) => candidate >= payloadStart);
+    if (afterStart !== undefined) {
+      ranges.push({ start: payloadStart, end: afterStart });
+    }
+  }
+  return ranges;
+}
+function findTarget(file, patch) {
+  const matches = indexesOf(file, patch.target.anchor);
+  if (matches.length === 0) {
+    fail("target_not_found", `Target anchor was not found in ${patch.path}`);
+  }
+  if (matches.length > 1) {
+    fail("target_ambiguous", `Target anchor is ambiguous in ${patch.path}; matched ${matches.length} locations`);
+  }
+  const start = matches[0];
+  const end = start + patch.target.anchor.length;
+  return {
+    range: { start, end },
+    insertIndex: patch.target.kind === "before" ? start : end
+  };
+}
+function indexesOf(haystack, needle) {
+  if (needle.length === 0) {
+    return [];
+  }
+  const indexes = [];
+  let index = haystack.indexOf(needle);
+  while (index !== -1) {
+    indexes.push(index);
+    index = haystack.indexOf(needle, index + 1);
+  }
+  return indexes;
+}
+function rangesOverlap(left, right) {
+  return left.start < right.end && right.start < left.end;
+}
+async function writeAtomic(path, bytes) {
+  const info = await stat(path);
+  const dir = dirname(path);
+  const base = basename(path);
+  const temp = join(dir, `.${base}.${process.pid}.${randomBytes(8).toString("hex")}.tmp`);
+  try {
+    await writeFile(temp, bytes, { flag: "wx" });
+    await chmod(temp, info.mode);
+    await rename(temp, path);
+  } catch (error) {
+    await unlink(temp).catch(() => {
+      return;
+    });
+    throw error;
+  }
+}
+export {
+  selectMove,
+  parseBlockPatch,
+  checkPatchFile,
+  applyPatchFile,
+  applyMove,
+  BlockPatchError
+};

package/dist/parser.d.ts

@@ -0,0 +1,2 @@
+import type { BlockPatch } from "./types";
+export declare function parseBlockPatch(input: Buffer): BlockPatch;

package/dist/types.d.ts

@@ -0,0 +1,20 @@
+export type TargetKind = "before" | "after";
+export interface BlockPatch {
+    type: "move";
+    path: string;
+    sourceBefore: Buffer;
+    sourcePayload: Buffer;
+    sourceAfter: Buffer;
+    target: TargetAnchor;
+}
+export interface TargetAnchor {
+    kind: TargetKind;
+    anchor: Buffer;
+}
+export interface ApplyOptions {
+    cwd?: string;
+    dryRun?: boolean;
+}
+export interface ApplyResult {
+    changed: string[];
+}

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "blockpatch",
+  "version": "0.1.0",
+  "description": "Anchored text block relocation patches",
+  "type": "module",
+  "license": "MIT",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "bin": {
+    "blockpatch": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "test": "bun test",
+    "build": "bun build ./src/cli.ts ./src/index.ts --target=node --outdir=dist && tsc -p tsconfig.build.json",
+    "prepublishOnly": "bun test && bun run build",
+    "publish:dry": "npm publish --dry-run"
+  },
+  "devDependencies": {
+    "@types/bun": "latest",
+    "typescript": "^5.8.3"
+  },
+  "engines": {
+    "node": ">=20"
+  }
+}