@volcanic-dev/tephra 0.3.0 → 0.4.1

package/README.md

@@ -20,9 +20,17 @@ npx -y @volcanic-dev/tephra
 |------|--------------|
 | `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. Never overwrites — text shifts to make room. |
+| `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 beginning at 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.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@volcanic-dev/tephra",
-  "version": "0.3.0",
+  "version": "0.4.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

@@ -24,9 +24,12 @@
 // mismatch modifies nothing and reports where that text actually is now.
 // 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.
+// changes line numbering reports the shift. The commonest workflows are
+// single atomic calls: `move` is cut + paste with the server doing the
+// shift arithmetic, and a paste target with end_line/whole_lines REPLACES
+// a range instead of inserting.
 //
-// Tools: copy, cut, paste, peek.
+// Tools: copy, cut, paste, move, peek.
 
 import { readFile, writeFile } from 'node:fs/promises'
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
@@ -234,7 +237,7 @@ async function guarded(fn) {
 }
 
 // @tephra-tools
-const server = new McpServer({ name: 'tephra', version: '0.3.0' })
+const server = new McpServer({ name: 'tephra', version: '0.4.1' })
 
 const expectSchema = z
   .string()
@@ -328,30 +331,75 @@ server.registerTool(
     }),
 )
 
+// @tephra-paste-targets — a paste target either inserts at an anchor or, when
+// end_line/whole_lines is present, REPLACES a range with the slot contents.
+function resolveTarget(text, lines, t, label) {
+  const clip = slots.get(t.slot)
+  if (clip === undefined || clip.length === 0) {
+    throw new PositionError(`${label}: slot "${t.slot}" is empty — nothing to paste. ${slots.size > 0 ? `Slots that do hold text: ${slotList()}.` : 'Use copy or cut first.'}`)
+  }
+  const isReplace = t.end_line !== undefined || t.whole_lines === true
+  if (t.end_char !== undefined && t.end_line === undefined) {
+    throw new PositionError(`${label}: end_char requires end_line.`)
+  }
+  let off
+  let endOff
+  if (isReplace && t.whole_lines) {
+    if (t.end_char !== undefined) throw new PositionError(`${label}: whole_lines replacement takes only line and end_line — omit end_char.`)
+    off = lineAt(lines, t.line, label).start
+    const endLine = t.end_line ?? t.line
+    lineAt(lines, endLine, `${label} end`)
+    endOff = endLine < lines.length ? lines[endLine].start : text.length
+  } else if (isReplace) {
+    off = charOffset(text, lines, t.line, t.char, label, 1)
+    endOff = t.end_char === undefined
+      ? lineAt(lines, t.end_line, `${label} end`).contentEnd
+      : charOffset(text, lines, t.end_line, t.end_char, `${label} end`, 0) + 1
+    if (endOff <= off) throw new PositionError(`${label}: the range to replace is empty or reversed — the end does not come after the start.`)
+  } else {
+    off = charOffset(text, lines, t.line, t.char, label, 1)
+    endOff = off
+  }
+  if (t.expect !== undefined) verifyExpect(text, lines, off, t.expect, label)
+  return { off, endOff, clip, isReplace }
+}
+
+function targetDesc(t) {
+  if (!(t.end_line !== undefined || t.whole_lines === true)) return `${t.line}:${t.char}`
+  if (t.whole_lines) {
+    const endLine = t.end_line ?? t.line
+    return t.line === endLine ? `line ${t.line}` : `lines ${t.line}–${endLine}`
+  }
+  return `${t.line}:${t.char} → ${t.end_line}:${t.end_char ?? 'end-of-line'}`
+}
+
 server.registerTool(
   'paste',
   {
     title: 'Paste clipboard into file',
     description:
-      "Insert Tephra clipboard slot contents into a file at one or more exact positions. " +
-      'Text is inserted before the character at (line, char); char may be one past the end of the line to append to it. ' +
+      "Insert Tephra clipboard slot contents into a file at one or more exact positions, or replace ranges with them. " +
+      '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 pasting. ' +
-      'Existing text is never overwritten — it shifts to make room, and the result says how line numbers moved.',
+      'Pass `expect` (the text that currently begins at the position) to verify before touching anything; in replace mode it 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
         .array(
           z.object({
-            line: z.number().int().describe('Line to paste at (1-indexed)'),
-            char: z.number().int().default(1).describe('Character position to paste at (1-indexed; the clipboard is inserted before this character; line length + 1 means end of line). Omit to paste at the start of the line — the right choice when pasting whole lines.'),
+            line: z.number().int().describe('Line of the anchor (1-indexed); in replace mode, the first line of the range being replaced'),
+            char: z.number().int().default(1).describe('Character position of the anchor (1-indexed; text is inserted before this character; line length + 1 means end of line). Omit for column 1 — the right choice for whole lines.'),
+            end_line: z.number().int().optional().describe('Replace mode: replace from the anchor through this line (1-indexed, inclusive) with the slot contents instead of inserting'),
+            end_char: z.number().int().optional().describe('Replace mode: last character replaced on end_line (1-indexed, inclusive). Omit for end-of-line.'),
+            whole_lines: z.boolean().optional().describe('Replace mode: replace complete lines line..end_line (end_line defaults to line), INCLUDING the trailing newline. Omit char/end_char.'),
             slot: z.string().min(1).max(64).default('default').describe('Clipboard slot to paste from (defaults to "default")'),
             expect: expectSchema,
           }),
         )
         .min(1)
         .max(20)
-        .describe('One or more paste positions, all addressed against the file as it is right now — they are applied bottom-up, so earlier targets never invalidate later ones.'),
+        .describe('One or more paste/replace targets, all addressed against the file as it is right now — they are applied bottom-up, so earlier targets never invalidate later ones.'),
     },
   },
   async ({ file, targets }) =>
@@ -359,45 +407,134 @@ server.registerTool(
       const text = await readFile(file, 'utf8')
       const lines = indexLines(text)
       const resolved = targets.map((t, idx) => {
-        const label = targets.length === 1 ? 'paste position' : `target ${idx + 1}`
-        const clip = slots.get(t.slot)
-        if (clip === undefined || clip.length === 0) {
-          throw new PositionError(`${label}: slot "${t.slot}" is empty — nothing to paste. ${slots.size > 0 ? `Slots that do hold text: ${slotList()}.` : 'Use copy or cut first.'}`)
-        }
-        const off = charOffset(text, lines, t.line, t.char, label, 1)
-        if (t.expect !== undefined) verifyExpect(text, lines, off, t.expect, label)
-        return { ...t, idx, label, off, clip }
+        const label = targets.length === 1 ? 'paste target' : `target ${idx + 1}`
+        return { ...t, idx, label, ...resolveTarget(text, lines, t, label) }
       })
+      const byOff = [...resolved].sort((a, b) => a.off - b.off || a.idx - b.idx)
+      for (let i = 1; i < byOff.length; i++) {
+        if (byOff[i].off < byOff[i - 1].endOff) {
+          throw new PositionError(`${byOff[i].label} falls inside the range replaced by ${byOff[i - 1].label} — targets must not overlap. Nothing was modified.`)
+        }
+      }
       let out = text
       for (const t of [...resolved].sort((a, b) => b.off - a.off || b.idx - a.idx)) {
-        out = out.slice(0, t.off) + t.clip + out.slice(t.off)
+        out = out.slice(0, t.off) + t.clip + out.slice(t.endOff)
       }
       await writeFile(file, out, 'utf8')
       const finalLines = indexLines(out)
-      // final coordinates: shift each target by everything inserted above it
+      // final coordinates: shift each target by the net effect of everything applied above it
       const placed = resolved.map((t) => {
-        const delta = resolved.reduce((acc, o) => acc + (o.off < t.off || (o.off === t.off && o.idx < t.idx) ? o.clip.length : 0), 0)
+        const delta = resolved.reduce((acc, o) => acc + (o.off < t.off || (o.off === t.off && o.idx < t.idx) ? o.clip.length - (o.endOff - o.off) : 0), 0)
         return {
           t,
+          removed: text.slice(t.off, t.endOff),
           start: positionOf(finalLines, t.off + delta),
           end: positionOf(finalLines, t.off + delta + t.clip.length),
         }
       })
       if (placed.length === 1) {
-        const [{ t, start, end }] = placed
-        return ok(`Pasted ${describe(t.clip)} from slot "${t.slot}" into ${file} at ${t.line}:${t.char}. The inserted text now spans ${start.line}:${start.char} → ${end.line}:${end.char} (exclusive end).${shiftNote(t.line, newlineCount(t.clip))}\n\nPreview:\n${preview(t.clip)}`)
+        const [{ t, removed, start, end }] = placed
+        const span = `now spans ${start.line}:${start.char} → ${end.line}:${end.char} (exclusive end)`
+        if (t.isReplace) {
+          const anchorLine = t.whole_lines || t.end_char === undefined ? (t.end_line ?? t.line) : t.end_line
+          return ok(`Replaced ${targetDesc(t)} in ${file} (removed ${describe(removed)} — ${inlinePreview(removed)}) with slot "${t.slot}" (${describe(t.clip)}). The new text ${span}.${shiftNote(anchorLine, newlineCount(t.clip) - newlineCount(removed))}\n\nPreview:\n${preview(t.clip)}`)
+        }
+        return ok(`Pasted ${describe(t.clip)} from slot "${t.slot}" into ${file} at ${t.line}:${t.char}. The inserted text ${span}.${shiftNote(t.line, newlineCount(t.clip))}\n\nPreview:\n${preview(t.clip)}`)
       }
-      const addedLines = resolved.reduce((acc, t) => acc + newlineCount(t.clip), 0)
+      const netLines = placed.reduce((acc, { t, removed }) => acc + newlineCount(t.clip) - newlineCount(removed), 0)
       return ok(
-        `Pasted ${placed.length} targets into ${file}, applied bottom-up (file updated, ${finalLines.length} addressable lines):\n` +
-        placed.map(({ t, start, end }) => `- slot "${t.slot}" (${describe(t.clip)}) at ${t.line}:${t.char} → final span ${start.line}:${start.char} → ${end.line}:${end.char}`).join('\n') +
-        (addedLines > 0
-          ? `\n${addedLines} line${addedLines === 1 ? '' : 's'} of numbering inserted in total — line numbers below each paste have shifted down; recompute any positions you noted earlier before using them.`
+        `Applied ${placed.length} targets to ${file}, bottom-up (file updated, ${finalLines.length} addressable lines):\n` +
+        placed.map(({ t, removed, start, end }) =>
+          `- slot "${t.slot}" (${describe(t.clip)}) ${t.isReplace ? `replaced ${targetDesc(t)} (removed ${describe(removed)})` : `at ${t.line}:${t.char}`} → final span ${start.line}:${start.char} → ${end.line}:${end.char}`,
+        ).join('\n') +
+        (netLines !== 0
+          ? `\nNet line-numbering change: ${netLines > 0 ? '+' : ''}${netLines} — recompute any positions you noted earlier before using them.`
           : ''),
       )
     }),
 )
 
+server.registerTool(
+  'move',
+  {
+    title: 'Move ranges (atomic cut + paste)',
+    description:
+      '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. ' +
+      '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'),
+      ranges: rangesSchema.ranges,
+      to: z
+        .object({
+          file: z.string().optional().describe('Destination file (defaults to the source file)'),
+          line: z.number().int().describe('Destination line (1-indexed), in the destination file as it is NOW — do not adjust for the cut'),
+          char: z.number().int().default(1).describe('Destination character (1-indexed; the text is inserted before it; line length + 1 means end of line). Omit for column 1 — the right choice for whole lines.'),
+          expect: expectSchema,
+        })
+        .describe('Where the text goes; it is inserted before the character at (line, char)'),
+    },
+  },
+  async ({ file, ranges, to }) =>
+    guarded(async () => {
+      const text = await readFile(file, 'utf8')
+      const lines = indexLines(text)
+      const resolved = resolveRanges(text, lines, ranges, true)
+      const snippets = resolved.map((r) => text.slice(r.startOff, r.endOff))
+      const payload = snippets.join('')
+      const sameFile = to.file === undefined || to.file === file
+      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 (sameFile) {
+        for (const r of resolved) {
+          if (destOff > r.startOff && destOff < r.endOff) {
+            throw new PositionError(`destination ${to.line}:${to.char} falls inside ${r.label} (${rangeDesc(r)}) — a range cannot be moved into itself. Nothing was modified.`)
+          }
+        }
+      }
+      resolved.forEach((r, i) => slots.set(r.slot, snippets[i]))
+      let srcOut = text
+      for (const r of [...resolved].sort((a, b) => b.startOff - a.startOff)) {
+        srcOut = srcOut.slice(0, r.startOff) + srcOut.slice(r.endOff)
+      }
+      let start
+      let end
+      let destFinalCount
+      if (sameFile) {
+        const adjDest = destOff - resolved.reduce((acc, r) => acc + (r.endOff <= destOff ? r.endOff - r.startOff : 0), 0)
+        const out = srcOut.slice(0, adjDest) + payload + srcOut.slice(adjDest)
+        await writeFile(file, out, 'utf8')
+        const finalLines = indexLines(out)
+        destFinalCount = finalLines.length
+        start = positionOf(finalLines, adjDest)
+        end = positionOf(finalLines, adjDest + payload.length)
+      } else {
+        // insert into the destination before cutting the source, so a failure
+        // between the two writes duplicates text rather than losing it
+        const destOut = destText.slice(0, destOff) + payload + destText.slice(destOff)
+        await writeFile(to.file, destOut, 'utf8')
+        await writeFile(file, srcOut, 'utf8')
+        const finalLines = indexLines(destOut)
+        destFinalCount = finalLines.length
+        start = positionOf(finalLines, destOff)
+        end = positionOf(finalLines, destOff + payload.length)
+      }
+      const destName = sameFile ? file : to.file
+      const slotsDesc = resolved.length === 1 ? `slot "${resolved[0].slot}"` : `slots ${resolved.map((r) => `"${r.slot}"`).join(', ')}`
+      return ok(
+        `Moved ${describe(payload)} from ${file} (${resolved.map((r) => rangeDesc(r)).join(', ')}) to ${destName} ${to.line}:${to.char}. ` +
+        `It now spans ${start.line}:${start.char} → ${end.line}:${end.char} (final coordinates, exclusive end; ${sameFile ? 'file' : 'destination file'} has ${destFinalCount} addressable lines${sameFile ? '' : `; source file has ${indexLines(srcOut).length}`}). ` +
+        `Also stored in ${slotsDesc}.` +
+        '\nLine numbers around both the cut and the insertion have shifted — the span above is authoritative; recompute anything you noted earlier.' +
+        `\n\nPreview:\n${preview(payload)}`,
+      )
+    }),
+)
+
 server.registerTool(
   'peek',
   {