@volcanic-dev/tephra 0.2.0 → 0.3.0

package/README.md

@@ -1,6 +1,6 @@
 # Tephra
 
-**A clipboard for AI agents.** Tephra is an MCP server that lets a model copy an exact character range from a file — start `(line, char)` to end `(line, char)` — and paste it at an exact position somewhere else. Byte-for-byte, no retyping, no transcription drift, no tokens spent regenerating code that already exists.
+**A clipboard for AI agents.** When a model moves code by regenerating it, it retypes 200 lines from memory — and sometimes what lands isn't quite what left. That transcription drift is a correctness bug, not just a token cost. Tephra is an MCP server for byte-exact copy and paste: name whole lines (or exact `(line, char)` ranges), copy them byte-for-byte, paste them at an exact position anywhere else. **Your agent will never subtly mangle code it's moving.**
 
 The clipboard is a **private in-process buffer, deliberately not the OS clipboard**. An agent can never read what you last copied (passwords, tokens, anything) and can never overwrite what you're about to paste. Nothing touches disk; the buffer dies with the session.
 
@@ -18,9 +18,9 @@ npx -y @volcanic-dev/tephra
 
 | Tool | What it does |
 |------|--------------|
-| `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. |
+| `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. |
 | `peek` | List the slots that hold text, or show one slot's size and preview. |
 
 ## Named slots
@@ -37,9 +37,11 @@ Cutting or pasting lines shifts the numbering of everything below the edit — t
 
 ## Addressing
 
-- Lines and characters are **1-indexed**: the first character of a file is `(1, 1)`.
-- Copy/cut ranges are **inclusive on both ends**: copying `(2, 5)` → `(2, 7)` yields exactly 3 characters.
-- To copy whole lines 10–14: start `(10, 1)`, end `(14, <length of line 14>)`.
+Models read line numbers well and count characters badly, so the common case never counts:
+
+- **Whole lines** (the usual move): `{start_line: 10, end_line: 14, whole_lines: true}`. Linewise, vim-style — the trailing newline comes along, so a cut lifts the lines out cleanly and a paste at `{line: 42}` drops them in as complete lines.
+- Character positions are optional refinements: omitted `end_char` means end-of-line, omitted `start_char` (or paste `char`) means column 1.
+- When given, everything is **1-indexed** and ranges are **inclusive on both ends**: copying `(2, 5)` → `(2, 7)` yields exactly 3 characters.
 - A file ending in a newline has an addressable empty final line, so appending at end-of-file is `paste` at `(lastLine, 1)`.
 - Out-of-range positions return the line's real length and a preview of it, so an agent can self-correct in one step.
 

package/package.json

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

@@ -2,11 +2,17 @@
 // @tephra-server
 // Tephra — an MCP server that gives AI agents a clipboard of their own.
 //
-// Models are bad at retyping: moving 80 lines of code by regenerating them
-// invites transcription drift and burns tokens. Tephra lets an agent name an
-// exact range — start (line, char) to end (line, char), both 1-indexed and
-// inclusive — copy it byte-for-byte, and paste it at an exact position in
-// another file.
+// Models are bad at retyping: regenerating 200 lines to move them invites
+// transcription drift — a correctness bug, not just a token cost. Tephra
+// lets an agent name an exact range — whole lines, or (line, char) to
+// (line, char), 1-indexed and inclusive — copy it byte-for-byte, and paste
+// it at an exact position in another file.
+//
+// Models are also bad at counting characters within a line, so character
+// positions are optional everywhere: whole_lines ranges take line numbers
+// only (linewise, including the trailing newline, so cuts leave no empty
+// husk), an omitted end_char means end-of-line, an omitted start_char or
+// paste char means column 1.
 //
 // The clipboard is a private in-process buffer, deliberately NOT the OS
 // clipboard: an agent must not be able to read whatever the human last
@@ -153,6 +159,8 @@ function shiftNote(afterLine, delta) {
 // 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).
+// whole_lines ranges are linewise: they include the end line's terminator,
+// so cutting them removes the lines entirely instead of leaving empty husks.
 function resolveRanges(text, lines, ranges, forCut) {
   const resolved = ranges.map((r, idx) => {
     const label = ranges.length === 1 ? 'range' : `range ${idx + 1}`
@@ -161,10 +169,25 @@ function resolveRanges(text, lines, ranges, forCut) {
       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
+    let startOff
+    let endOff
+    if (r.whole_lines) {
+      if (r.start_char !== undefined || r.end_char !== undefined) {
+        throw new PositionError(`${label}: whole_lines ranges take only start_line and end_line — omit start_char and end_char.`)
+      }
+      startOff = lineAt(lines, r.start_line, `${label} start`).start
+      lineAt(lines, r.end_line, `${label} end`)
+      endOff = r.end_line < lines.length ? lines[r.end_line].start : text.length
+    } else {
+      startOff = r.start_char === undefined
+        ? lineAt(lines, r.start_line, `${label} start`).start
+        : charOffset(text, lines, r.start_line, r.start_char, `${label} start`, 0)
+      endOff = r.end_char === undefined
+        ? lineAt(lines, r.end_line, `${label} end`).contentEnd
+        : 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}).`)
+      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)
     return { ...r, idx, label, slot, startOff, endOff }
@@ -185,8 +208,13 @@ function resolveRanges(text, lines, ranges, forCut) {
   return resolved
 }
 
+function rangeDesc(r) {
+  if (r.whole_lines) return r.start_line === r.end_line ? `line ${r.start_line}` : `lines ${r.start_line}–${r.end_line}`
+  return `${r.start_line}:${r.start_char ?? 1} → ${r.end_line}:${r.end_char ?? 'end-of-line'}`
+}
+
 function rangeSummary(r, snippet) {
-  return `slot "${r.slot}": ${describe(snippet)} (${r.start_line}:${r.start_char} → ${r.end_line}:${r.end_char}) — ${inlinePreview(snippet)}`
+  return `slot "${r.slot}": ${describe(snippet)} (${rangeDesc(r)}) — ${inlinePreview(snippet)}`
 }
 
 function ok(message) {
@@ -206,7 +234,7 @@ async function guarded(fn) {
 }
 
 // @tephra-tools
-const server = new McpServer({ name: 'tephra', version: '0.2.0' })
+const server = new McpServer({ name: 'tephra', version: '0.3.0' })
 
 const expectSchema = z
   .string()
@@ -217,9 +245,10 @@ const expectSchema = z
 
 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)'),
+  start_char: z.number().int().optional().describe('Character position on start_line of the first character (1-indexed). Omit to start at the beginning of the line.'),
   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)'),
+  end_char: z.number().int().optional().describe('Character position on end_line of the last character (1-indexed, inclusive). Omit to run to the end of the line. Prefer omitting over counting characters.'),
+  whole_lines: z.boolean().optional().describe('Take start_line through end_line as complete lines, INCLUDING the trailing newline (so cutting removes the lines entirely, leaving no empty line behind). With this set, omit start_char/end_char. Preferred for any whole-line move.'),
   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,
 })
@@ -238,9 +267,9 @@ server.registerTool(
   {
     title: 'Copy ranges to clipboard',
     description:
-      "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. ' +
+      "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. " +
       'The clipboard is private to this session, not the operating system clipboard.',
     inputSchema: rangesSchema,
@@ -254,7 +283,7 @@ server.registerTool(
       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 ${describe(snippets[0])} from ${file} (${rangeDesc(r)}) 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')}`)
     }),
@@ -266,6 +295,7 @@ server.registerTool(
     title: 'Cut ranges to clipboard',
     description:
       'Same as copy, but also removes the ranges from the source file (they must not overlap). ' +
+      'For moving whole lines, set whole_lines: true — the trailing newline comes along, so the lines are removed entirely with no empty line left behind. ' +
       '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,
@@ -285,7 +315,7 @@ server.registerTool(
       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])}`)
+        return ok(`Cut ${describe(snippets[0])} from ${file} (${rangeDesc(r)}) 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(
@@ -314,7 +344,7 @@ server.registerTool(
         .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)'),
+            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.'),
             slot: z.string().min(1).max(64).default('default').describe('Clipboard slot to paste from (defaults to "default")'),
             expect: expectSchema,
           }),