blockpatch 0.1.0 → 1.1.0

package/CONTRIBUTING.md

@@ -0,0 +1,26 @@
+# Contributing
+
+`blockpatch` is intentionally small. The core invariant is: no fuzz, no AST parsing, and no regeneration of moved bytes.
+
+Changes should preserve these rules:
+
+- context and payload matching stay byte-exact
+- moved bytes come from the source file, not from formatted or regenerated text
+- line numbers are review hints, not match authority
+- agent-facing output stays deterministic and structured
+
+Before sending changes, run:
+
+```sh
+bun run typecheck
+bun test
+bun run build
+npm run smoke:dist
+npm run pack:dry
+```
+
+Before publishing an unpublished version, also run:
+
+```sh
+npm run publish:dry
+```

package/README.md

@@ -1,118 +1,175 @@
 # 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.
+[![CI](https://github.com/cheese-melted/blockpatch/actions/workflows/ci.yml/badge.svg)](https://github.com/cheese-melted/blockpatch/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/blockpatch.svg)](https://www.npmjs.com/package/blockpatch)
 
-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.
+Cut/paste for agents: hash-verified block moves that read like unified diffs.
+
+`blockpatch` emits reviewable unified-diff-shaped patches for exact, hash-verified payload moves. In a paired move, the source hunk removes exact bytes and the target hunk adds the same exact bytes, so `blockpatch` moves the original source bytes instead of regenerating them. Generated patches are intended to be compatible with `patch --fuzz=0` where possible, while `blockpatch apply` accepts a strict subset and deliberately rejects fuzzy, heuristic, or ambiguous application.
 
 ## Install
 
 ```sh
-npx blockpatch check patch.blockpatch
-npx blockpatch apply patch.blockpatch
-bunx blockpatch apply patch.blockpatch --dry-run
 npm install -g blockpatch
+blockpatch --help
 ```
 
-For local development:
+Or run without installing:
 
 ```sh
-bun install
-bun test
-bun run build
-bun run publish:dry
+npx blockpatch --help
 ```
 
-## Commands
+## Usage
 
-```sh
-blockpatch check patch.blockpatch
-blockpatch apply patch.blockpatch
-blockpatch apply patch.blockpatch --dry-run
-```
+`blockpatch` is a deterministic move planner/apply layer for coding agents:
 
-`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.
+1. Send a JSON move request to `blockpatch move --json - --diff`.
+2. Show the emitted `.blockpatch` to the user for review.
+3. Apply the reviewed patch with `blockpatch apply`.
+4. Retry the `.blockpatch`, not the original JSON request.
 
-## V0 Format
+Example: move `movedThing` from `src/foo.ts` into `src/bar.ts`, starting from this tree:
 
-```text
-*** Begin BlockPatch
-*** Move File: src/example.ts
-*** Source Before
-function alpha() {
+```ts
+// before: src/foo.ts
+export function keepThing() {
+  return 7;
 }
 
-*** Source Payload
-function movedThing() {
-  console.log("keep me exact");
+export function movedThing() {
+  return 42;
 }
 
-*** Source After
-function omega() {
-}
+// before: src/bar.ts
+export const target = "here";
+```
+
+The JSON request selects the source bytes and target anchors. Ask `blockpatch` to plan the byte-exact move and emit the reviewable patch:
 
-*** Target After
-constructor() {
+```sh
+blockpatch move --json - --diff <<'JSON' > patch.blockpatch
+{
+  "src": "src/foo.ts",
+  "src_start": "\nexport function movedThing() {\n",
+  "src_end": "}\n",
+  "dst": "src/bar.ts",
+  "target_before": "export const target = \"here\";\n"
 }
+JSON
+```
 
-*** End BlockPatch
+`patch.blockpatch` now carries the move as a unified-diff-shaped document:
+
+```diff
+diff --blockpatch a/src/foo.ts b/src/foo.ts
+blockpatch version 1
+blockpatch move id=move-1 role=source payload-sha256=bb03c42613e9289c043d2fced7ce2d8c87410cdb15fa48341ce79fa409d45303
+--- a/src/foo.ts
++++ b/src/foo.ts
+
+@@ -3,5 +3,1 @@ blockpatch-source id=move-1
+ }
+-
+-export function movedThing() {
+-  return 42;
+-}
+
+diff --blockpatch a/src/bar.ts b/src/bar.ts
+blockpatch version 1
+blockpatch move id=move-1 role=target payload-sha256=bb03c42613e9289c043d2fced7ce2d8c87410cdb15fa48341ce79fa409d45303
+--- a/src/bar.ts
++++ b/src/bar.ts
+
+@@ -1,1 +1,5 @@ blockpatch-target id=move-1
+ export const target = "here";
++
++export function movedThing() {
++  return 42;
++}
 ```
 
-`*** Target Before` is also supported:
+`move --diff` validates the source delimiters and target anchors, hashes the selected payload, self-checks the rendered patch against the current tree in memory, and prints it without writing to the tree.
+
+Review the patch, then apply it:
 
-```text
-*** Target Before
-function omega() {
+```sh
+blockpatch apply patch.blockpatch
+```
+
+```
+changed src/foo.ts
+changed src/bar.ts
+```
+
+`apply` checks the payload hash, requires the source block and target anchors to each match exactly once in the current tree, and replaces each changed file atomically. The tree now matches the requested final state:
+
+```ts
+// after: src/foo.ts
+export function keepThing() {
+  return 7;
+}
+
+// after: src/bar.ts
+export const target = "here";
+
+export function movedThing() {
+  return 42;
 }
 ```
 
-Only one target marker is allowed.
+Retrying the same `patch.blockpatch` against this tree reports `already_applied`: the patch carries the payload and hash, so a retry validates the final state instead of reselecting bytes from a changed tree.
 
-## Section Bytes
+The same handshake covers whole-file creation and removal via `mode: "create_file"` and `mode: "remove_file"`; those patches use strict `/dev/null` file headers.
 
-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.
+## Common Commands
 
-That means:
+```sh
+blockpatch check patch.blockpatch
+blockpatch apply patch.blockpatch --dry-run
+blockpatch apply patch.blockpatch
+blockpatch plan --json -
+blockpatch move --json -
+```
+
+`check` parses a patch and verifies it against the target tree without writing. `apply --dry-run` validates through the apply path without writing. `apply` writes the verified result.
+
+`move --json -` applies a move request directly; with `--diff` it only prints the rendered patch. `plan --json -` runs the same planner but returns a JSON envelope with validation metadata and the patch in its `patch` field — the agent-facing form shown in [Commands](docs/commands.md). JSON over stdin is the most reliable form because it avoids shell quoting problems.
+
+When using `--cwd`, operation paths inside patches and move JSON are relative to `--cwd`; input patch and move JSON filenames are normal CLI paths, relative to your shell working directory unless absolute.
 
-- 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.
+## Docs
 
-## Semantics
+- [Commands](docs/commands.md): supported CLI forms and flags.
+- [Patch spec](docs/spec.md): canonical `.blockpatch` artifact format, hunk syntax, `/dev/null`, byte rules, move JSON requests, JSON output, and error codes.
+- [Behavior](docs/behavior.md): exact matching, idempotence, path containment, failure rules, and write behavior.
+- [Conformance](conformance/): runnable `.blockpatch` cases for checking another implementation.
 
-For one patch:
+## Examples
 
-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.
+- [same-file relocation](examples/same-file-relocation/)
+- [cross-file relocation](examples/cross-file-relocation/)
+- [insert existing file](examples/insert-existing-file/)
+- [delete existing file](examples/delete-existing-file/)
+- [create file](examples/create-file/)
+- [remove file](examples/remove-file/)
+- [reverse](examples/reverse/)
+- [failure: ambiguous target](examples/failure-ambiguous-target/)
 
-## Failure Rules
+Each example has a `patch.blockpatch`, a runnable `work/` directory, and `expected/` output for successful cases.
 
-`blockpatch` exits non-zero and does not modify the file when:
+## Conformance
+
+Run the published conformance cases against a blockpatch-compatible CLI:
+
+```sh
+npx -p blockpatch blockpatch-conformance ./my-implementation
+```
 
-- 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
+The runner checks apply/check behavior, retry idempotence, reverse application, byte preservation, and expected structured failures.
 
-## Intentionally Out Of Scope
+## Scope
 
-V0 does not implement:
+`blockpatch` intentionally does not implement fuzzy matching, AST parsing, code formatting, copy operations, regex anchors, multiple independent moves in one patch document, or arbitrary generated diffs from before/after snapshots.
 
-- fuzzy matching
-- AST parsing
-- code formatting
-- multi-file patches
-- copy operations
-- generated diffs
-- line numbers
-- regex anchors
+`apply` preserves patch body bytes exactly, but `plan`/`move --json` are text-oriented and intended for source files, not arbitrary binary payloads: JSON requests and rendered patches are UTF-8.

package/conformance/README.md

@@ -0,0 +1,29 @@
+# blockpatch conformance
+
+These cases exercise the public `.blockpatch` apply/check contract for independent implementations.
+
+Run against an installed implementation:
+
+```sh
+npx -p blockpatch blockpatch-conformance ./my-implementation
+```
+
+The shorter `npx blockpatch-conformance ./my-implementation` spelling would require publishing a separate npm package named `blockpatch-conformance`; this repository currently ships the runner as a `blockpatch` package binary.
+
+Run against this repository after building:
+
+```sh
+npm run build
+node conformance/runner.mjs node dist/cli.js
+```
+
+The runner invokes the implementation as:
+
+```sh
+<implementation> check <patch.blockpatch> --cwd <work> --json-output
+<implementation> apply <patch.blockpatch> --cwd <work> --json-output
+```
+
+Successful cases also verify retry idempotence and `apply --reverse`. Failure cases verify the expected JSON error code and that the work tree remains byte-identical.
+
+Set `BLOCKPATCH_CONFORMANCE_KEEP=1` to keep the temporary work directory after a failure.

package/conformance/cases/ambiguous-source/case.json

@@ -0,0 +1,8 @@
+{
+  "expect": "fail",
+  "error_code": "source_ambiguous",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=f721166071c491fd38ac82a8432ecc349f39f537a969054ab2c8d3175c731e7e\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-move me\n omega\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n target\n+move me\n",
+  "files": {
+    "file.txt": "alpha\nmove me\nomega\ntarget\nalpha\nmove me\nomega\n"
+  }
+}

package/conformance/cases/ambiguous-target/case.json

@@ -0,0 +1,8 @@
+{
+  "expect": "fail",
+  "error_code": "target_ambiguous",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=f721166071c491fd38ac82a8432ecc349f39f537a969054ab2c8d3175c731e7e\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-move me\n omega\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n target\n+move me\n",
+  "files": {
+    "file.txt": "alpha\nmove me\nomega\ntarget\ntarget\n"
+  }
+}

package/conformance/cases/create-file/case.json

@@ -0,0 +1,8 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch /dev/null b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=072a398e62ad50e40613b98e57f3e3236a471dcbd7c2b9f190440c22adc16a0f\n--- /dev/null\n+++ b/file.txt\n\n@@ -0,0 +1,1 @@ blockpatch-target id=move-1\n+created file\n",
+  "files": {},
+  "expected_files": {
+    "file.txt": "created file\n"
+  }
+}

package/conformance/cases/crlf/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=10d316fe0179a4ccaa97a509f75294785f941d7f9b0656684844edcdf1b5a01a\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\r\n-move me\r\n omega\r\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n target\r\n+move me\r\n",
+  "files": {
+    "file.txt": "alpha\r\nmove me\r\nomega\r\ntarget\r\n"
+  },
+  "expected_files": {
+    "file.txt": "alpha\r\nomega\r\ntarget\r\nmove me\r\n"
+  }
+}

package/conformance/cases/cross-file-relocation/case.json

@@ -0,0 +1,12 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/source.txt b/source.txt\nblockpatch version 1\nblockpatch move id=move-1 role=source payload-sha256=a990c0da5571138b0e2363af883a399fe214a137ad809c67f6530c618967a4e6\n--- a/source.txt\n+++ b/source.txt\n\n@@ -1,5 +1,2 @@ blockpatch-source id=move-1\n alpha()\n-function movedThing() {\n-  return 42;\n-}\n omega()\n\ndiff --blockpatch a/target.txt b/target.txt\nblockpatch version 1\nblockpatch move id=move-1 role=target payload-sha256=a990c0da5571138b0e2363af883a399fe214a137ad809c67f6530c618967a4e6\n--- a/target.txt\n+++ b/target.txt\n\n@@ -1,3 +1,6 @@ blockpatch-target id=move-1\n class Target {\n   method() {}\n+function movedThing() {\n+  return 42;\n+}\n }\n",
+  "files": {
+    "source.txt": "alpha()\nfunction movedThing() {\n  return 42;\n}\nomega()\n",
+    "target.txt": "class Target {\n  method() {}\n}\n"
+  },
+  "expected_files": {
+    "source.txt": "alpha()\nomega()\n",
+    "target.txt": "class Target {\n  method() {}\nfunction movedThing() {\n  return 42;\n}\n}\n"
+  }
+}

package/conformance/cases/delete-existing-file/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=5dbe6af8d3a2a31f6696ebdae9e590977a19b827ec8e0a22ea1e3decf1a79b77\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-remove me\n omega\n",
+  "files": {
+    "file.txt": "alpha\nremove me\nomega\n"
+  },
+  "expected_files": {
+    "file.txt": "alpha\nomega\n"
+  }
+}

package/conformance/cases/insert-existing-file/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=cbfeef0cd60ab2c01e036d23082a1f19ea3f5153d9cffde8790ad0152a3830f5\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,2 +1,3 @@ blockpatch-target id=move-1\n alpha\n+inserted line\n omega\n",
+  "files": {
+    "file.txt": "alpha\nomega\n"
+  },
+  "expected_files": {
+    "file.txt": "alpha\ninserted line\nomega\n"
+  }
+}

package/conformance/cases/no-trailing-newline/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=f721166071c491fd38ac82a8432ecc349f39f537a969054ab2c8d3175c731e7e\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-move me\n omega\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n+move me\n target\n\\n",
+  "files": {
+    "file.txt": "alpha\nmove me\nomega\ntarget"
+  },
+  "expected_files": {
+    "file.txt": "alpha\nomega\nmove me\ntarget"
+  }
+}

package/conformance/cases/remove-file/case.json

@@ -0,0 +1,9 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt /dev/null\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=4da5a83256114db88b111676cf3b2f4a04f202d3d7fc99417cac1ba5145713e2\n--- a/file.txt\n+++ /dev/null\n\n@@ -1,1 +0,0 @@ blockpatch-source id=move-1\n-obsolete file\n",
+  "files": {
+    "file.txt": "obsolete file\n"
+  },
+  "expected_files": {},
+  "expected_absent": ["file.txt"]
+}

package/conformance/cases/same-file-relocation/case.json

@@ -0,0 +1,10 @@
+{
+  "expect": "pass",
+  "patch": "diff --blockpatch a/file.txt b/file.txt\nblockpatch version 1\nblockpatch move id=move-1 payload-sha256=f721166071c491fd38ac82a8432ecc349f39f537a969054ab2c8d3175c731e7e\n--- a/file.txt\n+++ b/file.txt\n\n@@ -1,3 +1,2 @@ blockpatch-source id=move-1\n alpha\n-move me\n omega\n\n@@ -4,1 +4,2 @@ blockpatch-target id=move-1\n target\n+move me\n",
+  "files": {
+    "file.txt": "alpha\nmove me\nomega\ntarget\n"
+  },
+  "expected_files": {
+    "file.txt": "alpha\nomega\ntarget\nmove me\n"
+  }
+}

package/conformance/runner.mjs

@@ -0,0 +1,221 @@
+#!/usr/bin/env node
+import { spawnSync } from "node:child_process";
+import { constants } from "node:fs";
+import { access, mkdir, mkdtemp, readdir, readFile, rm, writeFile } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { dirname, isAbsolute, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const conformanceRoot = dirname(fileURLToPath(import.meta.url));
+const casesRoot = join(conformanceRoot, "cases");
+const invocationCwd = process.cwd();
+const keepTemp = process.env.BLOCKPATCH_CONFORMANCE_KEEP === "1";
+const implementationArgv = process.argv.slice(2);
+
+if (implementationArgv.length === 0 || implementationArgv[0] === "--help" || implementationArgv[0] === "-h") {
+  printUsage();
+  process.exit(implementationArgv.length === 0 ? 2 : 0);
+}
+
+const implementation = normalizeImplementation(implementationArgv);
+const tempRoot = await mkdtemp(join(tmpdir(), "blockpatch-conformance-"));
+
+try {
+  const caseNames = await readCaseNames();
+  for (const caseName of caseNames) {
+    await runCase(caseName);
+    console.log(`ok ${caseName}`);
+  }
+  console.log(`ok ${caseNames.length} conformance cases`);
+} catch (error) {
+  console.error(error instanceof Error ? error.message : String(error));
+  if (keepTemp) {
+    console.error(`kept temp directory: ${tempRoot}`);
+  }
+  process.exitCode = 1;
+} finally {
+  if (!keepTemp) {
+    await rm(tempRoot, { recursive: true, force: true });
+  }
+}
+
+function printUsage() {
+  console.error("Usage: blockpatch-conformance <blockpatch-command> [args...]");
+  console.error("");
+  console.error("Examples:");
+  console.error("  blockpatch-conformance blockpatch");
+  console.error("  blockpatch-conformance node dist/cli.js");
+}
+
+function normalizeImplementation(argv) {
+  const [command, ...args] = argv;
+  const resolvedCommand = looksPathLike(command) ? resolve(invocationCwd, command) : command;
+  return { command: resolvedCommand, args };
+}
+
+function looksPathLike(command) {
+  return command.startsWith(".") || command.includes("/") || command.includes("\\") || isAbsolute(command);
+}
+
+async function readCaseNames() {
+  const entries = await readdir(casesRoot, { withFileTypes: true });
+  return entries
+    .filter((entry) => entry.isDirectory())
+    .map((entry) => entry.name)
+    .sort();
+}
+
+async function runCase(caseName) {
+  const caseDefinition = JSON.parse(await readFile(join(casesRoot, caseName, "case.json"), "utf8"));
+  const caseRoot = join(tempRoot, caseName);
+  const workRoot = join(caseRoot, "work");
+  const patchPath = join(caseRoot, "patch.blockpatch");
+  await mkdir(workRoot, { recursive: true });
+  await writeCaseFiles(workRoot, caseDefinition.files ?? {});
+  await writeFile(patchPath, Buffer.from(requiredString(caseDefinition.patch, caseName, "patch"), "utf8"));
+
+  const initialFiles = caseDefinition.files ?? {};
+  const expectedFiles = caseDefinition.expected_files ?? initialFiles;
+  const expectedAbsent = caseDefinition.expected_absent ?? [];
+  const expect = caseDefinition.expect ?? "pass";
+
+  if (expect === "pass") {
+    await expectSuccess(caseName, "check", [patchPath, "--cwd", workRoot]);
+    await expectTree(caseName, workRoot, initialFiles, []);
+    await expectSuccess(caseName, "apply", [patchPath, "--cwd", workRoot]);
+    await expectTree(caseName, workRoot, expectedFiles, expectedAbsent);
+    await expectSuccess(caseName, "retry", [patchPath, "--cwd", workRoot]);
+    await expectTree(caseName, workRoot, expectedFiles, expectedAbsent);
+    await expectSuccess(caseName, "reverse", [patchPath, "--cwd", workRoot, "--reverse"]);
+    await expectTree(caseName, workRoot, initialFiles, []);
+    return;
+  }
+
+  if (expect === "fail") {
+    await expectFailure(caseName, "check", [patchPath, "--cwd", workRoot], caseDefinition.error_code);
+    await expectTree(caseName, workRoot, initialFiles, []);
+    await expectFailure(caseName, "apply", [patchPath, "--cwd", workRoot], caseDefinition.error_code);
+    await expectTree(caseName, workRoot, initialFiles, []);
+    return;
+  }
+
+  throw new Error(`${caseName}: unknown expect value ${JSON.stringify(expect)}`);
+}
+
+async function expectSuccess(caseName, label, args) {
+  const result = runBlockpatch(commandArgs(label, args));
+  if (result.status !== 0) {
+    throw commandError(caseName, label, result);
+  }
+  const json = parseJson(caseName, label, result.stdout);
+  if (json.ok !== true) {
+    throw new Error(`${caseName}: ${label} returned non-ok JSON ${JSON.stringify(json)}`);
+  }
+}
+
+async function expectFailure(caseName, label, args, errorCode) {
+  const result = runBlockpatch(commandArgs(label, args));
+  if (result.status === 0) {
+    throw new Error(`${caseName}: ${label} succeeded but expected failure`);
+  }
+  const json = parseJson(caseName, label, result.stderr || result.stdout);
+  if (json.ok !== false) {
+    throw new Error(`${caseName}: ${label} failure returned non-error JSON ${JSON.stringify(json)}`);
+  }
+  if (errorCode !== undefined && json.error?.code !== errorCode) {
+    throw new Error(`${caseName}: ${label} expected error ${errorCode}, got ${String(json.error?.code)}`);
+  }
+}
+
+function commandArgs(label, args) {
+  return [label === "check" ? "check" : "apply", ...args];
+}
+
+function runBlockpatch(args) {
+  return spawnSync(implementation.command, [...implementation.args, ...args, "--json-output"], {
+    cwd: invocationCwd,
+    encoding: "utf8",
+    maxBuffer: 1024 * 1024,
+    shell: process.platform === "win32"
+  });
+}
+
+function commandError(caseName, label, result) {
+  if (result.error !== undefined) {
+    return result.error;
+  }
+  return new Error(
+    `${caseName}: ${label} failed\n` +
+      `exit: ${String(result.status)}\n` +
+      `stdout:\n${result.stdout}\n` +
+      `stderr:\n${result.stderr}`
+  );
+}
+
+function parseJson(caseName, label, text) {
+  try {
+    return JSON.parse(text);
+  } catch (error) {
+    throw new Error(`${caseName}: ${label} did not return JSON: ${text.trim()}\n${String(error)}`);
+  }
+}
+
+async function writeCaseFiles(root, files) {
+  for (const [path, text] of Object.entries(files)) {
+    const absolute = join(root, path);
+    await mkdir(dirname(absolute), { recursive: true });
+    await writeFile(absolute, Buffer.from(requiredString(text, path, "file text"), "utf8"));
+  }
+}
+
+async function expectTree(caseName, root, expectedFiles, expectedAbsent) {
+  const actualPaths = await listFiles(root);
+  const expectedPaths = Object.keys(expectedFiles).sort();
+  assertEqual(caseName, "file list", actualPaths, expectedPaths);
+
+  for (const [path, text] of Object.entries(expectedFiles)) {
+    const expected = Buffer.from(requiredString(text, path, "expected file text"), "utf8");
+    const actual = await readFile(join(root, path));
+    if (!actual.equals(expected)) {
+      throw new Error(`${caseName}: ${path} bytes differ`);
+    }
+  }
+
+  for (const path of expectedAbsent) {
+    try {
+      await access(join(root, path), constants.F_OK);
+    } catch {
+      continue;
+    }
+    throw new Error(`${caseName}: expected ${path} to be absent`);
+  }
+}
+
+async function listFiles(root, prefix = "") {
+  const entries = await readdir(join(root, prefix), { withFileTypes: true });
+  const paths = [];
+  for (const entry of entries) {
+    const path = prefix === "" ? entry.name : `${prefix}/${entry.name}`;
+    if (entry.isDirectory()) {
+      paths.push(...await listFiles(root, path));
+    } else if (entry.isFile()) {
+      paths.push(path);
+    }
+  }
+  return paths.sort();
+}
+
+function requiredString(value, label, field) {
+  if (typeof value !== "string") {
+    throw new Error(`${label}: ${field} must be a string`);
+  }
+  return value;
+}
+
+function assertEqual(caseName, label, actual, expected) {
+  const actualJson = JSON.stringify(actual);
+  const expectedJson = JSON.stringify(expected);
+  if (actualJson !== expectedJson) {
+    throw new Error(`${caseName}: ${label} expected ${expectedJson}, got ${actualJson}`);
+  }
+}