@volcanic-dev/tephra 0.4.0 → 0.5.1

package/README.md

@@ -18,14 +18,19 @@ npx -y @volcanic-dev/tephra
 
 | Tool | What it does |
 |------|--------------|
-| `copy` | Copy one or more ranges `{start_line, end_line, whole_lines?, start_char?, end_char?, slot?, expect?}` from a file into clipboard slots. Both ends inclusive, 1-indexed. Newlines inside a range are included. |
+| `copy` | Copy one or more ranges `{start_line, end_line, whole_lines?, start_char?, end_char?, slot?, expect}` from a file into clipboard slots. Both ends inclusive, 1-indexed. Newlines inside a range are included. |
 | `cut` | Same as `copy`, but removes the ranges from the source file (ranges must be disjoint). Whole-line cuts take the newline too — no empty line left behind. |
-| `paste` | Insert clipboard slots into a file at one or more targets `{line, char?, slot?, expect?}` — before the character at `(line, char)`; `char` defaults to 1 and may be line length + 1 to append to a line. Add `end_line` (or `whole_lines: true`) to **replace** that range with the slot instead — the result shows exactly what was removed. |
-| `move` | Cut + paste in **one atomic call**: `move(file, ranges, to: {file?, line, char?, expect?})`. Source ranges *and* destination are all given in the file's current coordinates — the server does the shift arithmetic, so "move lines 120–184 to line 200" just works even though the cut renumbers line 200. Cross-file moves allowed. |
+| `paste` | Insert clipboard slots into a file at one or more targets `{line, char?, slot?, expect}` — before the character at `(line, char)`; `char` defaults to 1 and may be line length + 1 to append to a line. Add `end_line` (or `whole_lines: true`) to **replace** that range with the slot instead — the result shows exactly what was removed. |
+| `move` | Cut + paste in **one atomic call**: `move(file, ranges, to: {file?, line, char?, expect})`. Source ranges *and* destination are all given in the file's current coordinates — the server does the shift arithmetic, so "move lines 120–184 to line 200" just works even though the cut renumbers line 200. Cross-file moves allowed. |
 | `peek` | List the slots that hold text, or show one slot's size and preview. |
 
 The commonest workflows are one call each: relocate code with `move`, overwrite a stale block with a replace-mode `paste`, duplicate with `copy` + `paste`.
 
+Two semantics worth knowing precisely:
+
+- **`move` destinations.** A destination *inside* a moved range is a loud error (a range can't move into itself; nothing is modified). A destination *between* moved ranges is well-defined gather-at-point semantics: unmoved text keeps its relative order and the concatenated payload lands exactly at the destination — moving lines 2–3 and 6–7 of an 8-line file to line 5 yields `1, 4, 2, 3, 6, 7, 5, 8`. A destination at a moved range's own boundary is an in-place move (no change).
+- **`expect` in replace mode anchors at the START of the replaced range.** It is a position check, not a content-of-range check: it verifies the text adjacent to the anchor (and may extend past the range's end), so pass the stale block's first characters — you don't need to reproduce the whole span you're overwriting.
+
 ## Named slots
 
 Every range and target takes an optional `slot` (default `"default"`). Gather many snippets in one pass — each into its own slot — then paste them in any order, any number of times. Multi-range calls must name a distinct slot per range.
@@ -35,7 +40,7 @@ Every range and target takes an optional `slot` (default `"default"`). Gather ma
 Cutting or pasting lines shifts the numbering of everything below the edit — the classic way agents (especially several agents on one file) end up acting on stale coordinates. Tephra attacks this three ways:
 
 - **Bottom-up batches.** All ranges/targets in one call are addressed against the file *as you last read it* and applied from the bottom of the file up, so none invalidates another. One read, one call, no arithmetic.
-- **`expect` anchors — coordinates are hints, content is truth.** Pass the text you believe is at the position (up to 200 chars). On mismatch, nothing is modified and the error reports what is actually there and where your expected text lives now (`"the content has moved; re-aim at 43:12"`), so recovery is one round-trip. This catches *every* source of drift, including edits made outside Tephra.
+- **`expect` anchors — required, because coordinates never travel alone.** Every position named to `copy`, `cut`, `paste`, or `move` must come with a few characters of adjacent text (up to 200 chars): the text starting at the position, or the text ending at it (natural for appends). On mismatch, nothing is modified and the error reports what is actually there and where your expected text lives now, so recovery is one round-trip. This makes stale coordinates fail **closed** (loud no-op) instead of open (silent wrong edit), and it catches *every* source of drift, including edits made outside Tephra — even a hallucinated expect fails safe. The one waiver: pasting into an empty file, where nothing exists to verify against and nothing can drift.
 - **Shift reports.** Every cut and paste result states how line numbers moved (`"former line 4 is now line 3"`) and the file's new addressable line count, so positions noted earlier can be recomputed instead of silently going stale.
 
 ## Addressing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volcanic-dev/tephra",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "MCP server that gives AI agents a clipboard of their own: copy an exact line:char range from a file, paste it anywhere — byte-for-byte, without touching the OS clipboard.",
   "license": "MIT",
   "type": "module",

package/server.js

@@ -19,9 +19,15 @@
 // copied (passwords, tokens) or overwrite what they're about to paste.
 // Nothing is written to disk; the buffer dies with the session.
 //
-// Coordinates are hints; content is truth. Any range or paste target can
-// carry an `expect` anchor that is verified before anything is touched — a
-// mismatch modifies nothing and reports where that text actually is now.
+// Coordinates are hints; content is truth — and coordinates never travel
+// alone: every position named to Tephra (copy/cut/paste/move) requires an
+// `expect` anchor, a few characters adjacent to it, verified before anything
+// is touched. A mismatch modifies nothing and reports where that text
+// actually is now. Stale coordinates therefore fail closed (loud no-op)
+// instead of open (silent wrong edit). The anchor may match forward (text
+// starting at the position) or backward (text ending at it — natural for
+// appends); only pasting into an empty file waives it, since nothing exists
+// to verify against.
 // Batched ranges/targets are applied bottom-up, so one read of a file
 // yields coordinates that stay valid for the whole call, and any edit that
 // changes line numbering reports the shift. The commonest workflows are
@@ -102,11 +108,19 @@ function positionOf(lines, off) {
   return { line: lo + 1, char: off - lines[lo].start + 1 }
 }
 
-// @tephra-verify — expect anchors: verify content before acting. On mismatch
-// nothing is modified; the error reports what IS at the position and where
-// the expected text actually lives now, so the agent re-aims in one step.
+// @tephra-verify — expect anchors: verify content before acting. Two-sided
+// adjacency: the anchor may match the text starting at the position or the
+// text ending at it (so appends at end-of-line/file are satisfiable). On
+// mismatch nothing is modified; the error reports what IS at the position
+// and where the expected text actually lives now, so the agent re-aims in
+// one step.
+function expectRequired(label, hint) {
+  return new PositionError(`${label}: expect is required — pass a few characters you believe are adjacent to the position (${hint}). Coordinates are treated as hints; expect is what stops a stale one from touching the wrong text.`)
+}
+
 function verifyExpect(text, lines, off, expect, label) {
   if (text.startsWith(expect, off)) return
+  if (off >= expect.length && text.slice(off - expect.length, off) === expect) return
   const at = positionOf(lines, off)
   const actual = text.slice(off, off + Math.min(Math.max(expect.length, 20), 80))
   const found = []
@@ -117,7 +131,7 @@ function verifyExpect(text, lines, off, expect, label) {
     if (found.length < 5) found.push(positionOf(lines, i))
     i = text.indexOf(expect, i + 1)
   }
-  let msg = `${label}: the file does not have the expected text at ${at.line}:${at.char}. It has ${JSON.stringify(actual)} there, not ${JSON.stringify(expect.slice(0, 80))}.`
+  let msg = `${label}: the expected text ${JSON.stringify(expect.slice(0, 80))} is not adjacent to ${at.line}:${at.char} — it neither begins nor ends there. Forward from that position the file has ${JSON.stringify(actual)}.`
   if (total === 1) {
     msg += ` The expected text IS in the file, at ${found[0].line}:${found[0].char} — the content has moved; re-aim there.`
   } else if (total > 1) {
@@ -192,7 +206,8 @@ function resolveRanges(text, lines, ranges, forCut) {
     if (endOff <= startOff) {
       throw new PositionError(`${label}: the range from ${rangeDesc(r)} is empty or reversed — the end does not come after the start.`)
     }
-    if (r.expect !== undefined) verifyExpect(text, lines, startOff, r.expect, label)
+    if (r.expect === undefined) throw expectRequired(label, "e.g. the range's first characters")
+    verifyExpect(text, lines, startOff, r.expect, label)
     return { ...r, idx, label, slot, startOff, endOff }
   })
   const seen = new Map()
@@ -237,14 +252,14 @@ async function guarded(fn) {
 }
 
 // @tephra-tools
-const server = new McpServer({ name: 'tephra', version: '0.4.0' })
+const server = new McpServer({ name: 'tephra', version: '0.5.1' })
 
 const expectSchema = z
   .string()
   .min(1)
   .max(200)
   .optional()
-  .describe('Verification anchor: the text you believe is at this position (up to 200 chars). On mismatch nothing is modified and the error reports where that text actually is now. Strongly recommended whenever the file may have changed since you read it.')
+  .describe('Verification anchor — REQUIRED (only pasting into an empty file may omit it): a few characters adjacent to the position, either the text that starts at it (e.g. a range\'s first characters) or the text that ends at it (natural when appending). Up to 200 chars. On mismatch nothing is modified and the error reports where that text actually is now.')
 
 const rangeItem = z.object({
   start_line: z.number().int().describe('Line of the first character (1-indexed)'),
@@ -273,7 +288,7 @@ server.registerTool(
       "Copy one or more exact ranges from a file into Tephra's clipboard slots, byte-for-byte — use this instead of retyping text you intend to move or duplicate, so nothing gets subtly mangled in transit. " +
       'For whole lines (the common case), set whole_lines: true and give line numbers only. ' +
       'Character positions are optional: each range runs (start_line, start_char) → (end_line, end_char), inclusive on both ends, 1-indexed; omit start_char for column 1 and end_char for end-of-line rather than counting characters. ' +
-      "Pass `expect` (the range's first characters) to verify the coordinates still match the content before copying. " +
+      "Every range REQUIRES `expect` (its first characters) — verified before copying, so a stale coordinate fails loudly instead of copying the wrong text. " +
       'The clipboard is private to this session, not the operating system clipboard.',
     inputSchema: rangesSchema,
   },
@@ -360,7 +375,12 @@ function resolveTarget(text, lines, t, label) {
     off = charOffset(text, lines, t.line, t.char, label, 1)
     endOff = off
   }
-  if (t.expect !== undefined) verifyExpect(text, lines, off, t.expect, label)
+  // an empty file has nothing to verify against (and nothing can drift)
+  if (t.expect === undefined) {
+    if (text.length > 0) throw expectRequired(label, 'the text starting at the anchor, or ending at it when appending; only an empty destination file may omit expect')
+  } else {
+    verifyExpect(text, lines, off, t.expect, label)
+  }
   return { off, endOff, clip, isReplace }
 }
 
@@ -382,7 +402,8 @@ server.registerTool(
       'By default text is inserted before the character at (line, char) and nothing is overwritten; char defaults to 1 (right for whole lines) and may be one past the end of the line to append to it. ' +
       'REPLACE MODE: give end_line (plus optional end_char, or whole_lines: true for complete lines) and the slot contents replace that range instead — the result shows exactly what was removed. ' +
       'Multiple targets are applied bottom-up, so they all use the coordinates of the file as you last read it. ' +
-      'Pass `expect` (the text that currently begins at the position) to verify before touching anything.',
+      'Every target REQUIRES `expect` — text adjacent to the anchor (starting at it, or ending at it when appending to end of line/file); only an empty destination file may omit it. ' +
+      "In replace mode expect anchors at the START of the replaced range — a position check, which may extend past the range's end.",
     inputSchema: {
       file: z.string().describe('Absolute path of the file to paste into'),
       targets: z
@@ -462,6 +483,8 @@ server.registerTool(
       'Move one or more ranges to a destination in ONE atomic call — the compound of cut and paste. ' +
       'All coordinates, source ranges AND destination, are addressed against the file(s) exactly as they are right now: do not pre-adjust the destination for the lines the cut removes — the server does that arithmetic. ' +
       'The destination may be in a different file. Multiple ranges are concatenated at the destination in listed order, and the moved text is also stored in the clipboard slot(s). ' +
+      'The destination may sit between moved ranges (unmoved text keeps its relative order and the payload lands at that point) but never inside one — that is an error. ' +
+      'Every range and the destination REQUIRE `expect` (text adjacent to the position), verified before anything moves. ' +
       'For whole lines, set whole_lines: true on the range and give the destination as a line number only.',
     inputSchema: {
       file: z.string().describe('Absolute path of the source file'),
@@ -487,7 +510,11 @@ server.registerTool(
       const destText = sameFile ? text : await readFile(to.file, 'utf8')
       const destLines = sameFile ? lines : indexLines(destText)
       const destOff = charOffset(destText, destLines, to.line, to.char, 'destination', 1)
-      if (to.expect !== undefined) verifyExpect(destText, destLines, destOff, to.expect, 'destination')
+      if (to.expect === undefined) {
+        if (destText.length > 0) throw expectRequired('destination', 'the text starting at the destination, or ending at it when appending; only an empty destination file may omit expect')
+      } else {
+        verifyExpect(destText, destLines, destOff, to.expect, 'destination')
+      }
       if (sameFile) {
         for (const r of resolved) {
           if (destOff > r.startOff && destOff < r.endOff) {