@volcanic-dev/tephra 0.1.0 → 0.2.0

package/README.md

@@ -18,10 +18,22 @@ npx -y @volcanic-dev/tephra
 
 | Tool | What it does |
 |------|--------------|
-| `copy` | Copy `(start_line, start_char)` → `(end_line, end_char)` from a file to the clipboard. Both ends inclusive, 1-indexed. Newlines inside the range are included. |
-| `cut` | Same as `copy`, but removes the range from the source file. |
-| `paste` | Insert the clipboard into a file before the character at `(line, char)`. `char` may be line length + 1 to append to a line. Never overwrites — text shifts to make room. |
-| `peek` | Show the clipboard's current size and a preview. |
+| `copy` | Copy one or more ranges `{start_line, start_char, end_line, 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). |
+| `paste` | Insert clipboard slots into a file at one or more targets `{line, char, slot?, expect?}` — before the character at `(line, char)`; `char` may be line length + 1 to append to a line. Never overwrites — text shifts to make room. |
+| `peek` | List the slots that hold text, or show one slot's size and preview. |
+
+## 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.
+
+## Staying robust as line numbers shift
+
+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.
+- **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.1.0",
+  "version": "0.2.0",
   "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

@@ -13,6 +13,13 @@
 // 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.
+// 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.
+//
 // Tools: copy, cut, paste, peek.
 
 import { readFile, writeFile } from 'node:fs/promises'
@@ -20,8 +27,14 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { z } from 'zod'
 
-// @tephra-buffer — the private clipboard; in-memory only, per-session
-let clipboard = ''
+// @tephra-buffer — the private clipboard; in-memory only, per-session.
+// Named slots let an agent hold several snippets at once (gather many
+// ranges, then paste them in any order) without round-tripping content.
+const slots = new Map()
+
+function slotList() {
+  return [...slots.entries()].map(([name, text]) => `"${name}" (${describe(text)})`).join(', ')
+}
 
 // @tephra-positions — 1-indexed (line, char) ↔ absolute offset math
 // indexLines keeps a trailing empty line when the file ends with \n, so
@@ -57,8 +70,8 @@ function charOffset(text, lines, line, char, label, maxExtra) {
   const len = L.contentEnd - L.start
   const max = len + maxExtra
   if (!Number.isInteger(char) || char < 1 || char > max) {
-    const preview = text.slice(L.start, L.contentEnd)
-    const shown = preview.length > 80 ? `${preview.slice(0, 80)}…` : preview
+    const previewText = text.slice(L.start, L.contentEnd)
+    const shown = previewText.length > 80 ? `${previewText.slice(0, 80)}…` : previewText
     throw new PositionError(
       `${label}: char ${char} is out of range on line ${line}, which has ${len} character${len === 1 ? '' : 's'}` +
       (maxExtra ? ` (valid: 1–${max}, where ${max} means end of line)` : ` (valid: 1–${Math.max(max, 1)})`) +
@@ -68,34 +81,112 @@ function charOffset(text, lines, line, char, label, maxExtra) {
   return L.start + (char - 1)
 }
 
+// positionOf: absolute offset → 1-indexed { line, char }
+function positionOf(lines, off) {
+  let lo = 0
+  let hi = lines.length - 1
+  while (lo < hi) {
+    const mid = (lo + hi + 1) >> 1
+    if (lines[mid].start <= off) lo = mid
+    else hi = mid - 1
+  }
+  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.
+function verifyExpect(text, lines, off, expect, label) {
+  if (text.startsWith(expect, off)) return
+  const at = positionOf(lines, off)
+  const actual = text.slice(off, off + Math.min(Math.max(expect.length, 20), 80))
+  const found = []
+  let total = 0
+  let i = text.indexOf(expect)
+  while (i !== -1) {
+    total++
+    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))}.`
+  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) {
+    msg += ` The expected text appears ${total} times: at ${found.map((p) => `${p.line}:${p.char}`).join(', ')}${total > found.length ? ', …' : ''}. Pick the right one and re-aim.`
+  } else {
+    msg += ' The expected text does not appear anywhere in the file — re-read the file before retrying.'
+  }
+  throw new PositionError(`${msg} Nothing was modified.`)
+}
+
 // @tephra-preview — head/tail preview so results stay small even for big copies
 function preview(text) {
   if (text.length <= 300) return text
   return `${text.slice(0, 200)}\n… [${text.length - 300} chars omitted] …\n${text.slice(-100)}`
 }
 
+function inlinePreview(text) {
+  return JSON.stringify(text.length <= 60 ? text : `${text.slice(0, 45)}…${text.slice(-10)}`)
+}
+
 function describe(text) {
   const lines = text.length === 0 ? 0 : text.split('\n').length
   return `${text.length} chars, ${lines} line${lines === 1 ? '' : 's'}`
 }
 
-// endPosition: (line, char) of the character right after `text` inserted at (line, char)
-function endPosition(startLine, startChar, text) {
-  const parts = text.split('\n')
-  if (parts.length === 1) return { line: startLine, char: startChar + text.length }
-  return { line: startLine + parts.length - 1, char: parts[parts.length - 1].length + 1 }
+function newlineCount(text) {
+  let n = 0
+  for (let i = 0; i < text.length; i++) if (text[i] === '\n') n++
+  return n
 }
 
-// @tephra-extract — shared range extraction for copy/cut
-async function extractRange(file, startLine, startChar, endLine, endChar) {
-  const text = await readFile(file, 'utf8')
-  const lines = indexLines(text)
-  const startOff = charOffset(text, lines, startLine, startChar, 'start', 0)
-  const endOff = charOffset(text, lines, endLine, endChar, 'end', 0)
-  if (endOff < startOff) {
-    throw new PositionError(`The end position (line ${endLine}, char ${endChar}) comes before the start position (line ${startLine}, char ${startChar}).`)
+// @tephra-shift — cut/paste change the file's line numbering; say so explicitly,
+// so agents (and other agents coordinating on the same file) can recalibrate
+// instead of acting on stale positions.
+function shiftNote(afterLine, delta) {
+  if (delta === 0) return ''
+  const dir = delta > 0 ? 'down' : 'up'
+  return `\nLine numbers have shifted: every line that was below line ${afterLine} moved ${dir} by ${Math.abs(delta)} (former line ${afterLine + 1} is now line ${afterLine + 1 + delta}). Recompute any positions you noted earlier before using them.`
+}
+
+// @tephra-extract — shared range resolution for copy/cut. All ranges are
+// addressed against the same read of the file; cut applies them bottom-up so
+// none invalidates another. Multi-range calls must name a distinct slot per
+// range (defaulting them all to "default" would silently overwrite).
+function resolveRanges(text, lines, ranges, forCut) {
+  const resolved = ranges.map((r, idx) => {
+    const label = ranges.length === 1 ? 'range' : `range ${idx + 1}`
+    let slot = r.slot
+    if (slot === undefined) {
+      if (ranges.length > 1) throw new PositionError(`${label}: when passing multiple ranges, every range must name its own slot (otherwise they would overwrite each other).`)
+      slot = 'default'
+    }
+    const startOff = charOffset(text, lines, r.start_line, r.start_char, `${label} start`, 0)
+    const endOff = charOffset(text, lines, r.end_line, r.end_char, `${label} end`, 0) + 1 // end is inclusive
+    if (endOff <= startOff) {
+      throw new PositionError(`${label}: the end position (line ${r.end_line}, char ${r.end_char}) comes before the start position (line ${r.start_line}, char ${r.start_char}).`)
+    }
+    if (r.expect !== undefined) verifyExpect(text, lines, startOff, r.expect, label)
+    return { ...r, idx, label, slot, startOff, endOff }
+  })
+  const seen = new Map()
+  for (const r of resolved) {
+    if (seen.has(r.slot)) throw new PositionError(`${r.label} and ${seen.get(r.slot)} both target slot "${r.slot}" — one would overwrite the other. Use distinct slots.`)
+    seen.set(r.slot, r.label)
+  }
+  if (forCut) {
+    const byOff = [...resolved].sort((a, b) => a.startOff - b.startOff)
+    for (let i = 1; i < byOff.length; i++) {
+      if (byOff[i].startOff < byOff[i - 1].endOff) {
+        throw new PositionError(`${byOff[i - 1].label} and ${byOff[i].label} overlap — cut ranges must be disjoint. Nothing was modified.`)
+      }
+    }
   }
-  return { text, startOff, endOff: endOff + 1 } // end is inclusive
+  return resolved
+}
+
+function rangeSummary(r, snippet) {
+  return `slot "${r.slot}": ${describe(snippet)} (${r.start_line}:${r.start_char} → ${r.end_line}:${r.end_char}) — ${inlinePreview(snippet)}`
 }
 
 function ok(message) {
@@ -115,52 +206,95 @@ async function guarded(fn) {
 }
 
 // @tephra-tools
-const server = new McpServer({ name: 'tephra', version: '0.1.0' })
+const server = new McpServer({ name: 'tephra', version: '0.2.0' })
+
+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.')
+
+const rangeItem = z.object({
+  start_line: z.number().int().describe('Line of the first character (1-indexed)'),
+  start_char: z.number().int().describe('Character position on start_line of the first character (1-indexed)'),
+  end_line: z.number().int().describe('Line of the last character (1-indexed, inclusive)'),
+  end_char: z.number().int().describe('Character position on end_line of the last character (1-indexed, inclusive)'),
+  slot: z.string().min(1).max(64).optional().describe('Clipboard slot to store this range in. Optional for a single range (defaults to "default"); required, and distinct, when passing multiple ranges.'),
+  expect: expectSchema,
+})
 
-const rangeSchema = {
-  file: z.string().describe('Absolute path of the file to copy from'),
-  start_line: z.number().int().describe('Line of the first character to copy (1-indexed)'),
-  start_char: z.number().int().describe('Character position on start_line of the first character to copy (1-indexed)'),
-  end_line: z.number().int().describe('Line of the last character to copy (1-indexed, inclusive)'),
-  end_char: z.number().int().describe('Character position on end_line of the last character to copy (1-indexed, inclusive)'),
+const rangesSchema = {
+  file: z.string().describe('Absolute path of the file to read from'),
+  ranges: z
+    .array(rangeItem)
+    .min(1)
+    .max(20)
+    .describe('One or more ranges, all addressed against the file as it is right now — they are applied bottom-up, so earlier ranges never invalidate later ones.'),
 }
 
 server.registerTool(
   'copy',
   {
-    title: 'Copy range to clipboard',
+    title: 'Copy ranges to clipboard',
     description:
-      "Copy an exact character range from a file to Tephra's clipboard, byte-for-byte. " +
-      'The range runs from (start_line, start_char) through (end_line, end_char), inclusive on both ends; ' +
-      'newlines inside the range are included. Use this instead of retyping text you intend to move or duplicate. ' +
+      "Copy one or more exact character ranges from a file into Tephra's clipboard slots, byte-for-byte. " +
+      'Each range runs (start_line, start_char) → (end_line, end_char), inclusive on both ends, 1-indexed; newlines inside a range are included. ' +
+      'Use this instead of retyping text you intend to move or duplicate. ' +
+      "Pass `expect` (the range's first characters) to verify the coordinates still match the content before copying. " +
       'The clipboard is private to this session, not the operating system clipboard.',
-    inputSchema: rangeSchema,
+    inputSchema: rangesSchema,
   },
-  async ({ file, start_line, start_char, end_line, end_char }) =>
+  async ({ file, ranges }) =>
     guarded(async () => {
-      const { text, startOff, endOff } = await extractRange(file, start_line, start_char, end_line, end_char)
-      const snippet = text.slice(startOff, endOff)
-      clipboard = snippet
-      return ok(`Copied ${describe(snippet)} from ${file} (${start_line}:${start_char} → ${end_line}:${end_char}) to the clipboard.\n\nPreview:\n${preview(snippet)}`)
+      const text = await readFile(file, 'utf8')
+      const lines = indexLines(text)
+      const resolved = resolveRanges(text, lines, ranges, false)
+      const snippets = resolved.map((r) => text.slice(r.startOff, r.endOff))
+      resolved.forEach((r, i) => slots.set(r.slot, snippets[i]))
+      if (resolved.length === 1) {
+        const [r] = resolved
+        return ok(`Copied ${describe(snippets[0])} from ${file} (${r.start_line}:${r.start_char} → ${r.end_line}:${r.end_char}) to slot "${r.slot}".\n\nPreview:\n${preview(snippets[0])}`)
+      }
+      return ok(`Copied ${resolved.length} ranges from ${file}:\n${resolved.map((r, i) => `- ${rangeSummary(r, snippets[i])}`).join('\n')}`)
     }),
 )
 
 server.registerTool(
   'cut',
   {
-    title: 'Cut range to clipboard',
+    title: 'Cut ranges to clipboard',
     description:
-      'Same as copy, but also removes the range from the source file. ' +
-      'The range is inclusive on both ends. The file is written back immediately.',
-    inputSchema: rangeSchema,
+      'Same as copy, but also removes the ranges from the source file (they must not overlap). ' +
+      'Ranges are removed bottom-up, so every range is addressed against the file exactly as you last read it. The file is written back immediately. ' +
+      'CAUTION: removing lines shifts the line numbers of everything below a cut — the result says by how much; recompute stale positions before reusing them.',
+    inputSchema: rangesSchema,
   },
-  async ({ file, start_line, start_char, end_line, end_char }) =>
+  async ({ file, ranges }) =>
     guarded(async () => {
-      const { text, startOff, endOff } = await extractRange(file, start_line, start_char, end_line, end_char)
-      const snippet = text.slice(startOff, endOff)
-      clipboard = snippet
-      await writeFile(file, text.slice(0, startOff) + text.slice(endOff), 'utf8')
-      return ok(`Cut ${describe(snippet)} from ${file} (${start_line}:${start_char} → ${end_line}:${end_char}) to the clipboard. The file has been updated.\n\nPreview:\n${preview(snippet)}`)
+      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))
+      resolved.forEach((r, i) => slots.set(r.slot, snippets[i]))
+      let out = text
+      for (const r of [...resolved].sort((a, b) => b.startOff - a.startOff)) {
+        out = out.slice(0, r.startOff) + out.slice(r.endOff)
+      }
+      await writeFile(file, out, 'utf8')
+      const finalCount = indexLines(out).length
+      if (resolved.length === 1) {
+        const [r] = resolved
+        return ok(`Cut ${describe(snippets[0])} from ${file} (${r.start_line}:${r.start_char} → ${r.end_line}:${r.end_char}) to slot "${r.slot}". The file has been updated (${finalCount} addressable lines).${shiftNote(r.end_line, -newlineCount(snippets[0]))}\n\nPreview:\n${preview(snippets[0])}`)
+      }
+      const removedLines = snippets.reduce((acc, s) => acc + newlineCount(s), 0)
+      return ok(
+        `Cut ${resolved.length} ranges from ${file}, applied bottom-up (file updated, ${finalCount} addressable lines):\n` +
+        resolved.map((r, i) => `- ${rangeSummary(r, snippets[i])}`).join('\n') +
+        (removedLines > 0
+          ? `\n${removedLines} line${removedLines === 1 ? '' : 's'} of numbering removed in total — line numbers below each cut have shifted up; recompute any positions you noted earlier before using them.`
+          : ''),
+      )
     }),
 )
 
@@ -169,25 +303,68 @@ server.registerTool(
   {
     title: 'Paste clipboard into file',
     description:
-      "Insert Tephra's clipboard contents into a file at an exact position. " +
-      'The clipboard text is inserted before the character at (line, char); char may be one past the end of the line to append to it. ' +
-      'Existing text is never overwritten — it shifts to make room.',
+      "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. ' +
+      '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.',
     inputSchema: {
       file: z.string().describe('Absolute path of the file to paste into'),
-      line: z.number().int().describe('Line to paste at (1-indexed)'),
-      char: z.number().int().describe('Character position to paste at (1-indexed; the clipboard is inserted before this character; line length + 1 means end of line)'),
+      targets: z
+        .array(
+          z.object({
+            line: z.number().int().describe('Line to paste at (1-indexed)'),
+            char: z.number().int().describe('Character position to paste at (1-indexed; the clipboard is inserted before this character; line length + 1 means end of line)'),
+            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.'),
     },
   },
-  async ({ file, line, char }) =>
+  async ({ file, targets }) =>
     guarded(async () => {
-      const clip = clipboard
-      if (clip.length === 0) return fail('The clipboard is empty — nothing to paste. Use copy or cut first.')
       const text = await readFile(file, 'utf8')
       const lines = indexLines(text)
-      const off = charOffset(text, lines, line, char, 'paste position', 1)
-      await writeFile(file, text.slice(0, off) + clip + text.slice(off), 'utf8')
-      const end = endPosition(line, char, clip)
-      return ok(`Pasted ${describe(clip)} into ${file} at ${line}:${char}. The inserted text now spans ${line}:${char} → ${end.line}:${end.char} (exclusive end).\n\nPreview:\n${preview(clip)}`)
+      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 }
+      })
+      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)
+      }
+      await writeFile(file, out, 'utf8')
+      const finalLines = indexLines(out)
+      // final coordinates: shift each target by everything inserted 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)
+        return {
+          t,
+          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 addedLines = resolved.reduce((acc, t) => acc + newlineCount(t.clip), 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.`
+          : ''),
+      )
     }),
 )
 
@@ -195,13 +372,22 @@ server.registerTool(
   'peek',
   {
     title: 'Peek at clipboard',
-    description: "Show what is currently on Tephra's clipboard (size and a preview) without modifying anything.",
-    inputSchema: {},
+    description:
+      "Show what is currently on Tephra's clipboard without modifying anything. " +
+      "With a slot name: that slot's size and a preview. Without: a listing of every slot that holds text.",
+    inputSchema: {
+      slot: z.string().min(1).max(64).optional().describe('Slot to inspect; omit to list all slots'),
+    },
   },
-  async () =>
+  async ({ slot }) =>
     guarded(async () => {
-      if (clipboard.length === 0) return ok('The clipboard is empty.')
-      return ok(`Clipboard holds ${describe(clipboard)}.\n\nPreview:\n${preview(clipboard)}`)
+      if (slot !== undefined) {
+        const clip = slots.get(slot)
+        if (clip === undefined || clip.length === 0) return ok(`Slot "${slot}" is empty.`)
+        return ok(`Slot "${slot}" holds ${describe(clip)}.\n\nPreview:\n${preview(clip)}`)
+      }
+      if (slots.size === 0) return ok('The clipboard is empty — no slots hold text.')
+      return ok(`Slots holding text: ${slotList()}. Pass a slot name to peek to see its contents.`)
     }),
 )