editbuffer 0.2.1__tar.gz → 0.2.2__tar.gz

{editbuffer-0.2.1/src/editbuffer.egg-info → editbuffer-0.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: editbuffer
-Version: 0.2.1
+Version: 0.2.2
 Summary: Selection-based mutable output buffer for LLM tools
 Author: averagedigital
 License-Expression: MIT
@@ -199,10 +199,10 @@ Install the optional server:
 pipx install 'editbuffer[mcp]'
 ```
 
-Until a PyPI release exists, install directly from GitHub:
+Or install with `uvx` without a persistent environment:
 
 ```bash
-pipx install 'editbuffer[mcp] @ git+https://github.com/averagedigital/editbuffer.git'
+uvx --from 'editbuffer[mcp]' editbuffer-mcp
 ```
 
 Connect it to Codex:
@@ -220,9 +220,14 @@ Claude Desktop and generic MCP client examples are in
 The server exposes:
 
 - `buffer_create`
+- `buffer_append`
 - `buffer_list`
 - `buffer_view`
 - `buffer_edit`
+- `buffer_replace`
+- `buffer_insert_before`
+- `buffer_insert_after`
+- `buffer_delete`
 - `buffer_history`
 - `buffer_rollback`
 - `buffer_commit`
@@ -232,6 +237,18 @@ The server exposes:
 Buffers are in-memory and live for the MCP server process. The MCP layer calls
 the same core API and does not implement separate edit semantics.
 
+Use the first-class selection tools for normal agent use:
+
+```json
+{
+  "buffer_id": "answer",
+  "target": {"type": "exact", "text": "old"},
+  "text": "new"
+}
+```
+
+`buffer_edit` remains available for raw JSON operations.
+
 `buffer_commit` remembers non-empty committed output as a reusable command.
 `command_history` returns the last 10 commands, newest first. `command_select`
 creates a new pending buffer from a previous command so the model can reuse it

{editbuffer-0.2.1 → editbuffer-0.2.2}/README.md

@@ -181,10 +181,10 @@ Install the optional server:
 pipx install 'editbuffer[mcp]'
 ```
 
-Until a PyPI release exists, install directly from GitHub:
+Or install with `uvx` without a persistent environment:
 
 ```bash
-pipx install 'editbuffer[mcp] @ git+https://github.com/averagedigital/editbuffer.git'
+uvx --from 'editbuffer[mcp]' editbuffer-mcp
 ```
 
 Connect it to Codex:
@@ -202,9 +202,14 @@ Claude Desktop and generic MCP client examples are in
 The server exposes:
 
 - `buffer_create`
+- `buffer_append`
 - `buffer_list`
 - `buffer_view`
 - `buffer_edit`
+- `buffer_replace`
+- `buffer_insert_before`
+- `buffer_insert_after`
+- `buffer_delete`
 - `buffer_history`
 - `buffer_rollback`
 - `buffer_commit`
@@ -214,6 +219,18 @@ The server exposes:
 Buffers are in-memory and live for the MCP server process. The MCP layer calls
 the same core API and does not implement separate edit semantics.
 
+Use the first-class selection tools for normal agent use:
+
+```json
+{
+  "buffer_id": "answer",
+  "target": {"type": "exact", "text": "old"},
+  "text": "new"
+}
+```
+
+`buffer_edit` remains available for raw JSON operations.
+
 `buffer_commit` remembers non-empty committed output as a reusable command.
 `command_history` returns the last 10 commands, newest first. `command_select`
 creates a new pending buffer from a previous command so the model can reuse it

{editbuffer-0.2.1 → editbuffer-0.2.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "editbuffer"
-version = "0.2.1"
+version = "0.2.2"
 description = "Selection-based mutable output buffer for LLM tools"
 readme = "README.md"
 requires-python = ">=3.11"

{editbuffer-0.2.1 → editbuffer-0.2.2}/src/editbuffer/mcp_server.py

@@ -5,6 +5,14 @@ from typing import Any
 from uuid import uuid4
 
 from .buffer import EditBuffer
+from .errors import (
+    AmbiguousTargetError,
+    EditBufferError,
+    FuzzyMatchError,
+    InvalidOperationError,
+    StaleVersionError,
+    TargetNotFoundError,
+)
 from .history import EditRecord
 
 
@@ -61,6 +69,12 @@ class BufferRegistry:
     def command_history(self) -> list[dict[str, Any]]:
         return list(self._commands)
 
+    def current_version(self, buffer_id: str | None) -> int | None:
+        if buffer_id is None:
+            return None
+        buffer = self._buffers.get(buffer_id)
+        return None if buffer is None else buffer.version
+
     def select_command(
         self,
         command_id: str,
@@ -140,7 +154,11 @@ def create_server() -> Any:
         buffer_id: str | None = None,
     ) -> dict[str, Any]:
         """Create an in-memory pending output buffer."""
-        return registry.create(content, buffer_id=buffer_id)
+        return _tool_result(
+            lambda: registry.create(content, buffer_id=buffer_id),
+            registry,
+            buffer_id=buffer_id,
+        )
 
     @server.tool()
     def buffer_list() -> list[dict[str, Any]]:
@@ -150,7 +168,7 @@ def create_server() -> Any:
     @server.tool()
     def buffer_view(buffer_id: str) -> dict[str, Any]:
         """View current content, version, snapshots, and commit state."""
-        return registry.view(buffer_id)
+        return _tool_result(lambda: registry.view(buffer_id), registry, buffer_id=buffer_id)
 
     @server.tool()
     def buffer_edit(
@@ -164,22 +182,79 @@ def create_server() -> Any:
         Operations: append, replace, insert_before, insert_after, delete, rollback.
         Targets: exact/context/range/fuzzy/block. Ambiguous edits fail without mutation.
         """
-        return registry.edit(buffer_id, operation)
+        return _tool_result(
+            lambda: registry.edit(buffer_id, operation),
+            registry,
+            buffer_id=buffer_id,
+        )
+
+    @server.tool()
+    def buffer_append(buffer_id: str, text: str) -> dict[str, Any]:
+        """Append text to a pending buffer."""
+        return _tool_result(
+            lambda: registry.edit(buffer_id, {"op": "append", "text": text}),
+            registry,
+            buffer_id=buffer_id,
+        )
+
+    @server.tool()
+    def buffer_replace(
+        buffer_id: str,
+        target: dict[str, Any],
+        text: str,
+    ) -> dict[str, Any]:
+        """Replace a selection with text. Target can be exact/context/range/fuzzy/block."""
+        return _selection_tool(registry, buffer_id, "replace", target, text)
+
+    @server.tool()
+    def buffer_insert_before(
+        buffer_id: str,
+        target: dict[str, Any],
+        text: str,
+    ) -> dict[str, Any]:
+        """Insert text before a selection. Target can be exact/context/range/fuzzy/block."""
+        return _selection_tool(registry, buffer_id, "insert_before", target, text)
+
+    @server.tool()
+    def buffer_insert_after(
+        buffer_id: str,
+        target: dict[str, Any],
+        text: str,
+    ) -> dict[str, Any]:
+        """Insert text after a selection. Target can be exact/context/range/fuzzy/block."""
+        return _selection_tool(registry, buffer_id, "insert_after", target, text)
+
+    @server.tool()
+    def buffer_delete(buffer_id: str, target: dict[str, Any]) -> dict[str, Any]:
+        """Delete a selection. Target can be exact/context/range/fuzzy/block."""
+        return _tool_result(
+            lambda: registry.edit(buffer_id, {"op": "delete", "target": target}),
+            registry,
+            buffer_id=buffer_id,
+        )
 
     @server.tool()
     def buffer_history(buffer_id: str) -> list[dict[str, Any]]:
         """Return the audit trail for successful edits."""
-        return registry.history(buffer_id)
+        return _tool_result(
+            lambda: registry.history(buffer_id),
+            registry,
+            buffer_id=buffer_id,
+        )
 
     @server.tool()
     def buffer_rollback(buffer_id: str, version: int) -> dict[str, Any]:
         """Restore a prior snapshot as a new audited version."""
-        return registry.rollback(buffer_id, version)
+        return _tool_result(
+            lambda: registry.rollback(buffer_id, version),
+            registry,
+            buffer_id=buffer_id,
+        )
 
     @server.tool()
     def buffer_commit(buffer_id: str) -> dict[str, Any]:
         """Commit final output, close the buffer, and remember it as a reusable command."""
-        return registry.commit(buffer_id)
+        return _tool_result(lambda: registry.commit(buffer_id), registry, buffer_id=buffer_id)
 
     @server.tool()
     def command_history() -> list[dict[str, Any]]:
@@ -192,11 +267,98 @@ def create_server() -> Any:
         buffer_id: str | None = None,
     ) -> dict[str, Any]:
         """Create a new pending buffer from a previous command instead of regenerating it."""
-        return registry.select_command(command_id, buffer_id=buffer_id)
+        return _tool_result(
+            lambda: registry.select_command(command_id, buffer_id=buffer_id),
+            registry,
+            buffer_id=buffer_id,
+        )
 
     return server
 
 
+def _selection_tool(
+    registry: BufferRegistry,
+    buffer_id: str,
+    op: str,
+    target: dict[str, Any],
+    text: str,
+) -> dict[str, Any]:
+    return _tool_result(
+        lambda: registry.edit(buffer_id, {"op": op, "target": target, "text": text}),
+        registry,
+        buffer_id=buffer_id,
+    )
+
+
+def _tool_result(
+    call: Any,
+    registry: BufferRegistry,
+    *,
+    buffer_id: str | None = None,
+) -> Any:
+    try:
+        return call()
+    except (EditBufferError, KeyError, ValueError) as error:
+        return {
+            "ok": False,
+            "error": _structured_error(
+                error,
+                current_version=registry.current_version(buffer_id),
+            ),
+        }
+
+
+def _structured_error(
+    error: Exception,
+    *,
+    current_version: int | None,
+) -> dict[str, Any]:
+    payload: dict[str, Any] = {
+        "type": _error_type(error),
+        "message": _message(error),
+    }
+    if current_version is not None:
+        payload["current_version"] = current_version
+    if isinstance(error, AmbiguousTargetError):
+        payload["candidates"] = [list(candidate) for candidate in error.candidates]
+    if isinstance(error, FuzzyMatchError):
+        payload["reason"] = error.reason
+        payload["candidates"] = [list(candidate) for candidate in error.candidates]
+    return payload
+
+
+def _error_type(error: Exception) -> str:
+    if isinstance(error, TargetNotFoundError):
+        return "target_not_found"
+    if isinstance(error, AmbiguousTargetError):
+        return "ambiguous_target"
+    if isinstance(error, FuzzyMatchError):
+        return "fuzzy_match"
+    if isinstance(error, StaleVersionError):
+        return "stale_version"
+    if isinstance(error, InvalidOperationError):
+        return "invalid_operation"
+    if isinstance(error, KeyError):
+        message = _message(error)
+        if message.startswith("unknown buffer:"):
+            return "unknown_buffer"
+        if message.startswith("unknown command:"):
+            return "unknown_command"
+        return "not_found"
+    if isinstance(error, ValueError):
+        message = _message(error)
+        if message.startswith("buffer already exists:"):
+            return "duplicate_buffer"
+        return "invalid_value"
+    return "editbuffer_error"
+
+
+def _message(error: Exception) -> str:
+    if isinstance(error, KeyError) and error.args:
+        return str(error.args[0])
+    return str(error)
+
+
 def main() -> None:
     create_server().run(transport="stdio")
 

{editbuffer-0.2.1 → editbuffer-0.2.2/src/editbuffer.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: editbuffer
-Version: 0.2.1
+Version: 0.2.2
 Summary: Selection-based mutable output buffer for LLM tools
 Author: averagedigital
 License-Expression: MIT
@@ -199,10 +199,10 @@ Install the optional server:
 pipx install 'editbuffer[mcp]'
 ```
 
-Until a PyPI release exists, install directly from GitHub:
+Or install with `uvx` without a persistent environment:
 
 ```bash
-pipx install 'editbuffer[mcp] @ git+https://github.com/averagedigital/editbuffer.git'
+uvx --from 'editbuffer[mcp]' editbuffer-mcp
 ```
 
 Connect it to Codex:
@@ -220,9 +220,14 @@ Claude Desktop and generic MCP client examples are in
 The server exposes:
 
 - `buffer_create`
+- `buffer_append`
 - `buffer_list`
 - `buffer_view`
 - `buffer_edit`
+- `buffer_replace`
+- `buffer_insert_before`
+- `buffer_insert_after`
+- `buffer_delete`
 - `buffer_history`
 - `buffer_rollback`
 - `buffer_commit`
@@ -232,6 +237,18 @@ The server exposes:
 Buffers are in-memory and live for the MCP server process. The MCP layer calls
 the same core API and does not implement separate edit semantics.
 
+Use the first-class selection tools for normal agent use:
+
+```json
+{
+  "buffer_id": "answer",
+  "target": {"type": "exact", "text": "old"},
+  "text": "new"
+}
+```
+
+`buffer_edit` remains available for raw JSON operations.
+
 `buffer_commit` remembers non-empty committed output as a reusable command.
 `command_history` returns the last 10 commands, newest first. `command_select`
 creates a new pending buffer from a previous command so the model can reuse it

{editbuffer-0.2.1 → editbuffer-0.2.2}/tests/test_mcp_stdio_eval.py

@@ -18,18 +18,23 @@ class McpStdioEvalTests(unittest.TestCase):
             async with _session() as session:
                 tools = await session.list_tools()
                 self.assertEqual(
-                    [tool.name for tool in tools.tools],
-                    [
+                    {tool.name for tool in tools.tools},
+                    {
                         "buffer_create",
+                        "buffer_append",
                         "buffer_list",
                         "buffer_view",
                         "buffer_edit",
+                        "buffer_replace",
+                        "buffer_insert_before",
+                        "buffer_insert_after",
+                        "buffer_delete",
                         "buffer_history",
                         "buffer_rollback",
                         "buffer_commit",
                         "command_history",
                         "command_select",
-                    ],
+                    },
                 )
                 cases = [
                     (
@@ -99,6 +104,59 @@ class McpStdioEvalTests(unittest.TestCase):
 
         asyncio.run(run())
 
+    def test_selection_edit_tools_are_first_class(self) -> None:
+        async def run() -> None:
+            async with _session() as session:
+                await _call(
+                    session,
+                    "buffer_create",
+                    {"buffer_id": "selection-tools", "content": "alpha beta"},
+                )
+                await _call(
+                    session,
+                    "buffer_replace",
+                    {
+                        "buffer_id": "selection-tools",
+                        "target": {"type": "exact", "text": "beta"},
+                        "text": "gamma",
+                    },
+                )
+                await _call(
+                    session,
+                    "buffer_insert_before",
+                    {
+                        "buffer_id": "selection-tools",
+                        "target": {"type": "exact", "text": "gamma"},
+                        "text": "new ",
+                    },
+                )
+                await _call(
+                    session,
+                    "buffer_insert_after",
+                    {
+                        "buffer_id": "selection-tools",
+                        "target": {"type": "exact", "text": "alpha"},
+                        "text": " old",
+                    },
+                )
+                await _call(
+                    session,
+                    "buffer_delete",
+                    {
+                        "buffer_id": "selection-tools",
+                        "target": {"type": "exact", "text": "old "},
+                    },
+                )
+                result = await _call(
+                    session,
+                    "buffer_append",
+                    {"buffer_id": "selection-tools", "text": "!"},
+                )
+
+                self.assertEqual(result["content"], "alpha new gamma!")
+
+        asyncio.run(run())
+
     def test_failure_modes_are_actionable_and_atomic(self) -> None:
         async def run() -> None:
             async with _session() as session:
@@ -116,7 +174,8 @@ class McpStdioEvalTests(unittest.TestCase):
                         },
                     },
                 )
-                self.assertIn("selection did not match", error)
+                self.assertEqual(error["type"], "target_not_found")
+                self.assertIn("selection did not match", error["message"])
                 self.assertEqual(
                     await _call(session, "buffer_view", {"buffer_id": "missing"}),
                     before,
@@ -134,7 +193,8 @@ class McpStdioEvalTests(unittest.TestCase):
                         },
                     },
                 )
-                self.assertIn("selection matched 2 targets", error)
+                self.assertEqual(error["type"], "ambiguous_target")
+                self.assertEqual(error["candidates"], [[0, 1], [2, 3]])
 
                 await _call(
                     session,
@@ -162,7 +222,9 @@ class McpStdioEvalTests(unittest.TestCase):
                         },
                     },
                 )
-                self.assertIn("expected version 0", error)
+                self.assertEqual(error["type"], "stale_version")
+                self.assertEqual(error["current_version"], 1)
+                self.assertIn("expected version 0", error["message"])
                 self.assertEqual(
                     (await _call(session, "buffer_view", {"buffer_id": "stale"}))["content"],
                     "abcd",
@@ -193,71 +255,80 @@ class McpStdioEvalTests(unittest.TestCase):
                         },
                     },
                 )
-                self.assertIn("fuzzy selection ambiguous", error)
+                self.assertEqual(error["type"], "fuzzy_match")
+                self.assertEqual(error["reason"], "ambiguous")
+                self.assertGreaterEqual(len(error["candidates"]), 2)
 
                 await _call(
                     session,
                     "buffer_create",
                     {"buffer_id": "blocks", "content": "``` editbuffer:id=x\na\n```\n``` editbuffer:id=x\nb\n```"},
                 )
-                self.assertIn(
-                    "selection matched 2 targets",
-                    await _call_error(
-                        session,
-                        "buffer_edit",
-                        {
-                            "buffer_id": "blocks",
-                            "operation": {
-                                "op": "delete",
-                                "target": {"type": "block", "block_id": "x"},
+                self.assertEqual(
+                    (
+                        await _call_error(
+                            session,
+                            "buffer_edit",
+                            {
+                                "buffer_id": "blocks",
+                                "operation": {
+                                    "op": "delete",
+                                    "target": {"type": "block", "block_id": "x"},
+                                },
                             },
-                        },
-                    ),
+                        )
+                    )["type"],
+                    "ambiguous_target",
                 )
-                self.assertIn(
-                    "selection did not match",
-                    await _call_error(
-                        session,
-                        "buffer_edit",
-                        {
-                            "buffer_id": "blocks",
-                            "operation": {
-                                "op": "delete",
-                                "target": {"type": "block", "block_id": "missing"},
+                self.assertEqual(
+                    (
+                        await _call_error(
+                            session,
+                            "buffer_edit",
+                            {
+                                "buffer_id": "blocks",
+                                "operation": {
+                                    "op": "delete",
+                                    "target": {"type": "block", "block_id": "missing"},
+                                },
                             },
-                        },
-                    ),
+                        )
+                    )["type"],
+                    "target_not_found",
                 )
-                self.assertIn(
-                    "unknown operation",
-                    await _call_error(
-                        session,
-                        "buffer_edit",
-                        {"buffer_id": "blocks", "operation": {"op": "move"}},
-                    ),
+                self.assertEqual(
+                    (
+                        await _call_error(
+                            session,
+                            "buffer_edit",
+                            {"buffer_id": "blocks", "operation": {"op": "move"}},
+                        )
+                    )["type"],
+                    "invalid_operation",
                 )
-                self.assertIn(
-                    "unknown version",
-                    await _call_error(
-                        session,
-                        "buffer_rollback",
-                        {"buffer_id": "blocks", "version": 99},
-                    ),
+                self.assertEqual(
+                    (
+                        await _call_error(
+                            session,
+                            "buffer_rollback",
+                            {"buffer_id": "blocks", "version": 99},
+                        )
+                    )["type"],
+                    "invalid_operation",
                 )
 
                 await _call(session, "buffer_create", {"buffer_id": "commit", "content": "done"})
                 await _call(session, "buffer_commit", {"buffer_id": "commit"})
-                self.assertIn(
-                    "buffer is already committed",
-                    await _call_error(
-                        session,
-                        "buffer_edit",
-                        {
-                            "buffer_id": "commit",
-                            "operation": {"op": "append", "text": "!"},
-                        },
-                    ),
+                error = await _call_error(
+                    session,
+                    "buffer_edit",
+                    {
+                        "buffer_id": "commit",
+                        "operation": {"op": "append", "text": "!"},
+                    },
                 )
+                self.assertEqual(error["type"], "invalid_operation")
+                self.assertIn("buffer is already committed", error["message"])
 
         asyncio.run(run())
 
@@ -285,8 +356,15 @@ async def _call(session: Any, name: str, arguments: dict[str, Any]) -> dict[str,
     return structured
 
 
-async def _call_error(session: Any, name: str, arguments: dict[str, Any]) -> str:
+async def _call_error(session: Any, name: str, arguments: dict[str, Any]) -> dict[str, Any]:
     result = await session.call_tool(name, arguments)
-    if not result.isError:
-        raise AssertionError(f"{name} unexpectedly succeeded: {result.structuredContent}")
-    return " ".join(getattr(block, "text", "") for block in result.content)
+    if result.isError:
+        text = " ".join(getattr(block, "text", "") for block in result.content)
+        raise AssertionError(f"{name} returned unstructured MCP error: {text}")
+    structured = result.structuredContent
+    if not isinstance(structured, dict) or structured.get("ok") is not False:
+        raise AssertionError(f"{name} unexpectedly succeeded: {structured}")
+    error = structured.get("error")
+    if not isinstance(error, dict):
+        raise AssertionError(f"{name} did not return a structured error: {structured}")
+    return error