blockpatch 1.1.0 → 1.1.1

package/README.md

@@ -1,7 +1,7 @@
 # blockpatch
 
 [![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)
+[![npm version](https://img.shields.io/npm/v/blockpatch.svg?cacheSeconds=300)](https://www.npmjs.com/package/blockpatch)
 
 Cut/paste for agents: hash-verified block moves that read like unified diffs.
 

package/dist/cli.js

@@ -1953,7 +1953,8 @@ async function moveBlock(args, options = {}) {
         selection
       })
     ],
-    patch
+    patch,
+    warnings: insertionBoundaryWarnings(normalized.dst, normalized.targetBefore, selection.payload, normalized.targetAfter)
   };
 }
 function validateMoveArgs(value) {
@@ -2218,9 +2219,40 @@ async function insertPayload(args, validated, cwd, dryRun, options) {
         insert_index: target.insertIndex
       }
     ],
-    patch: renderedPatch
+    patch: renderedPatch,
+    warnings: insertionBoundaryWarnings(args.dst, args.targetBefore, args.payload, args.targetAfter)
   };
 }
+function insertionBoundaryWarnings(path, targetBefore, payload, targetAfter) {
+  const warnings = [];
+  if (targetBefore.length > 0 && payload.length > 0 && !endsWithLf(targetBefore) && !startsWithLf(payload)) {
+    warnings.push({
+      code: "adjacent_bytes",
+      message: "Insertion will place payload immediately after target_before with no newline or separator inserted by blockpatch",
+      path,
+      phase: "target",
+      boundary: "target_before+payload",
+      suggested_action: "include the intended newline in target_before or at the start of payload"
+    });
+  }
+  if (payload.length > 0 && targetAfter.length > 0 && !endsWithLf(payload) && !startsWithLf(targetAfter)) {
+    warnings.push({
+      code: "adjacent_bytes",
+      message: "Insertion will place target_after immediately after payload with no newline or separator inserted by blockpatch",
+      path,
+      phase: "target",
+      boundary: "payload+target_after",
+      suggested_action: "include the intended newline at the end of payload or at the start of target_after"
+    });
+  }
+  return warnings.length > 0 ? warnings : undefined;
+}
+function startsWithLf(bytes) {
+  return bytes[0] === 10;
+}
+function endsWithLf(bytes) {
+  return bytes[bytes.length - 1] === 10;
+}
 function verifyExpectedPayloadHash(args, payloadSha256) {
   if (args.expected_payload_sha256 !== undefined && args.expected_payload_sha256 !== payloadSha256) {
     fail("hash_mismatch", "expected_payload_sha256 does not match selected source payload", {
@@ -2671,12 +2703,25 @@ async function loadMoveArgs(options) {
   }
   const jsonBytes = options.moveJsonPath === "-" ? await readStdin() : await readFileChecked(resolve3(options.moveJsonPath), "move JSON file");
   try {
-    return JSON.parse(jsonBytes.toString("utf8"));
+    const parsed = JSON.parse(jsonBytes.toString("utf8"));
+    if (isEmptyObject(parsed)) {
+      throw new BlockPatchError("invalid_move_args", "Move JSON cannot be empty; provide src plus source selectors or payload and target anchors", {
+        field: "src",
+        suggested_action: "Use fields like src, src_start, src_end, dst, target_before, target_after, payload, or run blockpatch help"
+      });
+    }
+    return parsed;
   } catch (error) {
+    if (error instanceof BlockPatchError) {
+      throw error;
+    }
     const message = error instanceof Error ? error.message : String(error);
     throw new BlockPatchError("invalid_json", `Invalid move JSON: ${message}`);
   }
 }
+function isEmptyObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value) && Object.keys(value).length === 0;
+}
 function parseArgs(argv) {
   const args = [...argv];
   const outputFlags = takeLeadingOutputFlags(args);
@@ -2954,6 +2999,29 @@ Usage:
   blockpatch move --src /dev/null --dst <path> --payload <text> --target-before <text>
   blockpatch move --src <path> --src-start <text> --src-end <text> --dst /dev/null
   blockpatch version
+
+Move JSON fields:
+  src, dst, src_start, src_end, payload, target_before, target_after,
+  expected_payload_sha256, mode, dry_run
+
+Move selection:
+  src_start/src_end are byte-exact, newline-sensitive delimiters. The selected
+  payload starts at src_start and ends after the first following src_end.
+
+Target anchors:
+  target_before is the exact context immediately before the insertion point,
+  so insertion occurs after it. target_after is the exact context immediately
+  after the insertion point, so insertion occurs before it. With both anchors,
+  insertion occurs between them.
+
+Newlines:
+  blockpatch never adds separators. Include every intended newline in
+  src_start/src_end, payload, target_before, or target_after.
+
+Examples:
+  blockpatch move --json - --diff <<'JSON'
+  {"src":"src/a.ts","src_start":"function x() {\\n","src_end":"}\\n","dst":"src/b.ts","target_before":"class B {\\n"}
+  JSON
 `);
 }
 main(process.argv.slice(2)).then((code) => {

package/docs/commands.md

@@ -73,6 +73,10 @@ blockpatch move --src src/foo.ts --src-start $'\nfunction removeMe() {' --src-en
 
 Each flag sets the move JSON field of the same name and cannot be combined with `--json`. `mode` has no flag form, so whole-file `create_file`/`remove_file` requests are JSON-only. JSON avoids shell quoting problems, so it is usually the more reliable form for agents.
 
+`--target-before` means “this exact context is before the insertion point,” so the payload is inserted after that context. `--target-after` means “this exact context is after the insertion point,” so the payload is inserted before that context. These names describe the anchor's relationship to the insertion point; they do not mean “insert before this text” or “insert after this text.”
+
+`--src-start`, `--src-end`, `--target-before`, and `--target-after` are byte-exact and newline-sensitive. `src_start`/`src_end` select bytes from the beginning of `src_start` through the end of the first following `src_end`. `blockpatch` does not add separators, so include the newlines you want moved or inserted. If `target_before` does not end with `\n` and the payload does not start with `\n`, they will be joined directly.
+
 ## Output
 
 ```sh

package/docs/spec.md

@@ -212,6 +212,8 @@ Request shapes:
 - `payload` is only valid when `src` is `/dev/null`; it must be non-empty for in-file insertion.
 - `expected_payload_sha256` is optional.
 
+`src_start`, `src_end`, `target_before`, and `target_after` are byte-exact and newline-sensitive. Source selection starts at `src_start` and ends after the first following `src_end`; include any leading or trailing newline you want in the selected payload. `target_before` is the exact context before the insertion point, so insertion occurs after it. `target_after` is the exact context after the insertion point, so insertion occurs before it. `blockpatch` never inserts extra newlines or spacing between anchors and payload.
+
 Insertion:
 
 ```json
@@ -272,6 +274,14 @@ type ApplyResult = {
   status: "applied" | "noop" | "already_applied"
   strip_components?: number
   patch?: string
+  warnings?: Array<{
+    code: "adjacent_bytes"
+    message: string
+    path: string
+    phase: "target"
+    boundary: "target_before+payload" | "payload+target_after"
+    suggested_action: string
+  }>
   moves: Array<{
     id: string
     src: string
@@ -289,7 +299,7 @@ type ApplyResult = {
 
 `status` is `applied` for a normal computed move, `noop` for a computed move whose output bytes are identical, and `already_applied` when the command can prove the requested final state is already present. `strip_components` is present for `check` and `apply` JSON success output and reports the effective `-p` path-stripping count; it defaults to `1`.
 
-`patch` is present when `move --diff --json-output` is used. In `already_applied` relocation results, `source_range` is `null` because the source block is no longer present. For target-only insertions, `source_range` is `null`. For source-only deletions, `target_range` and `insert_index` are `null`. For path creation/removal, `src` or `dst` is the string `/dev/null`.
+`patch` is present when `move --diff --json-output` is used. `warnings` is present when a move validates but may surprise a caller, such as an insertion boundary where neither side contains a newline and the bytes will be joined directly. In `already_applied` relocation results, `source_range` is `null` because the source block is no longer present. For target-only insertions, `source_range` is `null`. For source-only deletions, `target_range` and `insert_index` are `null`. For path creation/removal, `src` or `dst` is the string `/dev/null`.
 
 With `--json-output`, errors print:
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blockpatch",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Hash-verified, reviewable block-move patches for coding agents",
   "packageManager": "bun@1.3.14",
   "type": "module",