editbuffer 0.2.1__py3-none-any.whl

editbuffer/__init__.py

@@ -0,0 +1,30 @@
+from .buffer import EditBuffer
+from .errors import (
+    AmbiguousTargetError,
+    EditBufferError,
+    FuzzyMatchError,
+    InvalidOperationError,
+    StaleVersionError,
+    TargetNotFoundError,
+    ValidationError,
+)
+from .history import EditHistory, EditRecord
+from .operations import EditOperation
+from .resolver import SelectionResolver
+from .selection import Selection
+
+__all__ = [
+    "AmbiguousTargetError",
+    "EditBuffer",
+    "EditBufferError",
+    "EditHistory",
+    "EditOperation",
+    "EditRecord",
+    "FuzzyMatchError",
+    "InvalidOperationError",
+    "Selection",
+    "SelectionResolver",
+    "StaleVersionError",
+    "TargetNotFoundError",
+    "ValidationError",
+]

editbuffer/blocks.py

@@ -0,0 +1,41 @@
+import re
+
+from .resolver import ResolvedSelection
+
+_FENCE = re.compile(
+    r"^(?P<fence>`{3,}|~{3,})[^\n]*\beditbuffer:id=(?P<id>[A-Za-z0-9_.-]+)[^\n]*\n",
+    re.MULTILINE,
+)
+_REGION = re.compile(
+    r"^<!--\s*editbuffer:block\s+(?P<id>[A-Za-z0-9_.-]+)\s*-->\s*\n",
+    re.MULTILINE,
+)
+_REGION_END = re.compile(r"^<!--\s*/editbuffer:block\s*-->", re.MULTILINE)
+
+
+def find_blocks(content: str, block_id: str) -> tuple[ResolvedSelection, ...]:
+    matches = list(_fenced_blocks(content, block_id))
+    matches.extend(_regions(content, block_id))
+    return tuple(sorted(matches, key=lambda match: match.start))
+
+
+def _fenced_blocks(content: str, block_id: str):
+    for opening in _FENCE.finditer(content):
+        if opening.group("id") != block_id:
+            continue
+        fence = re.escape(opening.group("fence"))
+        closing = re.search(rf"^{fence}[^\n]*(?:\n|$)", content[opening.end() :], re.MULTILINE)
+        if closing:
+            yield ResolvedSelection(
+                opening.end(),
+                opening.end() + closing.start(),
+            )
+
+
+def _regions(content: str, block_id: str):
+    for opening in _REGION.finditer(content):
+        if opening.group("id") != block_id:
+            continue
+        closing = _REGION_END.search(content, opening.end())
+        if closing:
+            yield ResolvedSelection(opening.end(), closing.start())

editbuffer/buffer.py

@@ -0,0 +1,178 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from typing import Any
+
+from .errors import InvalidOperationError
+from .history import EditHistory, EditRecord
+from .operations import EditOperation
+from .resolver import ResolvedSelection, SelectionResolver
+from .selection import Selection
+
+Validator = Callable[[str], None]
+
+
+class EditBuffer:
+    def __init__(
+        self,
+        content: str = "",
+        *,
+        validators: tuple[Validator, ...] = (),
+    ) -> None:
+        self._content = content
+        self._version = 0
+        self._committed = False
+        self._validators = validators
+        self._resolver = SelectionResolver()
+        self._snapshots = {0: content}
+        self.history = EditHistory()
+
+    @property
+    def version(self) -> int:
+        return self._version
+
+    @property
+    def committed(self) -> bool:
+        return self._committed
+
+    @property
+    def versions(self) -> tuple[int, ...]:
+        return tuple(self._snapshots)
+
+    def view(self) -> str:
+        return self._content
+
+    def append(self, text: str) -> EditRecord:
+        return self._apply(EditOperation("append", text=text))
+
+    def replace(
+        self,
+        target: Selection | Mapping[str, Any],
+        text: str,
+    ) -> EditRecord:
+        return self._apply(EditOperation("replace", self._selection(target), text))
+
+    def insert_before(
+        self,
+        target: Selection | Mapping[str, Any],
+        text: str,
+    ) -> EditRecord:
+        return self._apply(
+            EditOperation("insert_before", self._selection(target), text)
+        )
+
+    def insert_after(
+        self,
+        target: Selection | Mapping[str, Any],
+        text: str,
+    ) -> EditRecord:
+        return self._apply(
+            EditOperation("insert_after", self._selection(target), text)
+        )
+
+    def delete(self, target: Selection | Mapping[str, Any]) -> EditRecord:
+        return self._apply(EditOperation("delete", self._selection(target)))
+
+    def apply(
+        self,
+        operation: Mapping[str, Any] | EditOperation,
+    ) -> EditRecord:
+        return self._apply(
+            operation
+            if isinstance(operation, EditOperation)
+            else EditOperation.from_dict(operation)
+        )
+
+    def commit(self) -> str:
+        self._ensure_open()
+        self._committed = True
+        return self._content
+
+    def rollback(self, version: int) -> EditRecord:
+        return self._apply(EditOperation("rollback", version=version))
+
+    def _apply(self, operation: EditOperation) -> EditRecord:
+        self._ensure_open()
+        if operation.kind == "rollback":
+            return self._rollback(operation)
+        resolved = self._resolve(operation)
+        before = self._content[resolved.start : resolved.end]
+        after = _replacement(operation, before)
+        candidate = (
+            self._content[: resolved.start]
+            + after
+            + self._content[resolved.end :]
+        )
+        for validator in self._validators:
+            validator(candidate)
+
+        version_before = self._version
+        self._content = candidate
+        self._version += 1
+        self._snapshots[self._version] = candidate
+        record = EditRecord(
+            operation=operation,
+            start=resolved.start,
+            end=resolved.end,
+            before=before,
+            after=after,
+            version_before=version_before,
+            version_after=self._version,
+            confidence=resolved.confidence,
+        )
+        self.history.append(record)
+        return record
+
+    def _rollback(self, operation: EditOperation) -> EditRecord:
+        if operation.version not in self._snapshots:
+            raise InvalidOperationError(f"unknown version: {operation.version}")
+        candidate = self._snapshots[operation.version]
+        for validator in self._validators:
+            validator(candidate)
+        before = self._content
+        version_before = self._version
+        self._content = candidate
+        self._version += 1
+        self._snapshots[self._version] = candidate
+        record = EditRecord(
+            operation=operation,
+            start=0,
+            end=len(before),
+            before=before,
+            after=candidate,
+            version_before=version_before,
+            version_after=self._version,
+        )
+        self.history.append(record)
+        return record
+
+    def _resolve(self, operation: EditOperation) -> ResolvedSelection:
+        if operation.kind == "append":
+            end = len(self._content)
+            return ResolvedSelection(end, end)
+        if operation.target is None:
+            raise InvalidOperationError(f"{operation.kind} requires a target")
+        return self._resolver.resolve(
+            self._content,
+            operation.target,
+            version=self._version,
+        )
+
+    def _selection(self, value: Selection | Mapping[str, Any]) -> Selection:
+        return value if isinstance(value, Selection) else Selection.from_dict(value)
+
+    def _ensure_open(self) -> None:
+        if self._committed:
+            raise InvalidOperationError("buffer is already committed")
+
+
+def _replacement(operation: EditOperation, before: str) -> str:
+    if operation.kind == "append" or operation.kind == "replace":
+        return operation.text
+    if operation.kind == "insert_before":
+        return operation.text + before
+    if operation.kind == "insert_after":
+        return before + operation.text
+    if operation.kind == "delete":
+        return ""
+    raise InvalidOperationError(f"unknown operation: {operation.kind!r}")

editbuffer/cli.py

@@ -0,0 +1,138 @@
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import tempfile
+from pathlib import Path
+from typing import Any
+
+from .buffer import EditBuffer
+from .errors import EditBufferError, InvalidOperationError
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = _parser()
+    args = parser.parse_args(argv)
+    state_path = Path(args.state)
+
+    try:
+        if args.command == "new":
+            if state_path.exists():
+                raise InvalidOperationError(f"state already exists: {state_path}")
+            _save(state_path, {"initial": args.text, "operations": [], "committed": False})
+            return 0
+
+        state = _load(state_path)
+        buffer = _restore(state)
+        if args.command == "view":
+            print(buffer.view())
+        elif args.command == "history":
+            print(json.dumps(state["operations"], indent=2, ensure_ascii=False))
+        elif args.command == "commit":
+            result = buffer.commit()
+            state["committed"] = True
+            _save(state_path, state)
+            print(result)
+        elif args.command == "rollback":
+            operation = {"op": "rollback", "version": args.version}
+            buffer.apply(operation)
+            state["operations"].append(operation)
+            _save(state_path, state)
+        else:
+            operation = _operation(args)
+            buffer.apply(operation)
+            state["operations"].append(operation)
+            _save(state_path, state)
+        return 0
+    except (EditBufferError, OSError, ValueError, json.JSONDecodeError) as error:
+        parser.exit(2, f"editbuffer: {error}\n")
+
+
+def _parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(prog="editbuffer")
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    new = subparsers.add_parser("new")
+    new.add_argument("state")
+    new.add_argument("--text", default="")
+
+    append = subparsers.add_parser("append")
+    append.add_argument("state")
+    append.add_argument("text")
+
+    replace = subparsers.add_parser("replace")
+    replace.add_argument("state")
+    replace.add_argument("target", help="selection as JSON")
+    replace.add_argument("text")
+
+    apply = subparsers.add_parser("apply")
+    apply.add_argument("state")
+    apply.add_argument("operation", help="operation as JSON")
+
+    rollback = subparsers.add_parser("rollback")
+    rollback.add_argument("state")
+    rollback.add_argument("version", type=int)
+
+    for name in ("view", "history", "commit"):
+        command = subparsers.add_parser(name)
+        command.add_argument("state")
+    return parser
+
+
+def _operation(args: argparse.Namespace) -> dict[str, Any]:
+    if args.command == "append":
+        return {"op": "append", "text": args.text}
+    if args.command == "replace":
+        target = json.loads(args.target)
+        if not isinstance(target, dict):
+            raise InvalidOperationError("target must be a JSON object")
+        return {"op": "replace", "target": target, "text": args.text}
+    operation = json.loads(args.operation)
+    if not isinstance(operation, dict):
+        raise InvalidOperationError("operation must be a JSON object")
+    return operation
+
+
+def _load(path: Path) -> dict[str, Any]:
+    state = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(state, dict):
+        raise InvalidOperationError("state must be a JSON object")
+    return state
+
+
+def _restore(state: dict[str, Any]) -> EditBuffer:
+    initial = state.get("initial")
+    operations = state.get("operations")
+    if not isinstance(initial, str) or not isinstance(operations, list):
+        raise InvalidOperationError("invalid state file")
+    buffer = EditBuffer(initial)
+    for operation in operations:
+        if not isinstance(operation, dict):
+            raise InvalidOperationError("invalid operation in state file")
+        buffer.apply(operation)
+    if state.get("committed"):
+        buffer.commit()
+    return buffer
+
+
+def _save(path: Path, state: dict[str, Any]) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    handle = tempfile.NamedTemporaryFile(
+        "w",
+        encoding="utf-8",
+        dir=path.parent,
+        delete=False,
+    )
+    try:
+        with handle:
+            json.dump(state, handle, indent=2, ensure_ascii=False)
+            handle.write("\n")
+        os.replace(handle.name, path)
+    except BaseException:
+        Path(handle.name).unlink(missing_ok=True)
+        raise
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

editbuffer/errors.py

@@ -0,0 +1,35 @@
+class EditBufferError(Exception):
+    """Base error for editbuffer."""
+
+
+class TargetNotFoundError(EditBufferError):
+    pass
+
+
+class AmbiguousTargetError(EditBufferError):
+    def __init__(self, candidates: tuple[tuple[int, int], ...]) -> None:
+        self.candidates = candidates
+        super().__init__(f"selection matched {len(candidates)} targets: {candidates}")
+
+
+class FuzzyMatchError(EditBufferError):
+    def __init__(
+        self,
+        reason: str,
+        candidates: tuple[tuple[int, int, float], ...],
+    ) -> None:
+        self.reason = reason
+        self.candidates = candidates
+        super().__init__(f"fuzzy selection {reason}: {candidates}")
+
+
+class InvalidOperationError(EditBufferError):
+    pass
+
+
+class StaleVersionError(EditBufferError):
+    pass
+
+
+class ValidationError(EditBufferError):
+    pass

editbuffer/history.py

@@ -0,0 +1,33 @@
+from dataclasses import dataclass
+from collections.abc import Iterator
+
+from .operations import EditOperation
+
+
+@dataclass(frozen=True, slots=True)
+class EditRecord:
+    operation: EditOperation
+    start: int
+    end: int
+    before: str
+    after: str
+    version_before: int
+    version_after: int
+    confidence: float = 1.0
+
+
+class EditHistory:
+    def __init__(self) -> None:
+        self._records: list[EditRecord] = []
+
+    def append(self, record: EditRecord) -> None:
+        self._records.append(record)
+
+    def __len__(self) -> int:
+        return len(self._records)
+
+    def __getitem__(self, index: int) -> EditRecord:
+        return self._records[index]
+
+    def __iter__(self) -> Iterator[EditRecord]:
+        return iter(self._records)

editbuffer/mcp_server.py

@@ -0,0 +1,205 @@
+from __future__ import annotations
+
+from importlib import import_module
+from typing import Any
+from uuid import uuid4
+
+from .buffer import EditBuffer
+from .history import EditRecord
+
+
+class BufferRegistry:
+    def __init__(self) -> None:
+        self._buffers: dict[str, EditBuffer] = {}
+        self._commands: list[dict[str, Any]] = []
+        self._next_command_number = 1
+
+    def create(
+        self,
+        content: str = "",
+        *,
+        buffer_id: str | None = None,
+    ) -> dict[str, Any]:
+        identifier = buffer_id or uuid4().hex
+        if identifier in self._buffers:
+            raise ValueError(f"buffer already exists: {identifier}")
+        self._buffers[identifier] = EditBuffer(content)
+        return self.view(identifier)
+
+    def list_buffers(self) -> list[dict[str, Any]]:
+        return [
+            self._state(identifier, buffer)
+            for identifier, buffer in self._buffers.items()
+        ]
+
+    def view(self, buffer_id: str) -> dict[str, Any]:
+        return self._state(buffer_id, self._get(buffer_id))
+
+    def edit(self, buffer_id: str, operation: dict[str, Any]) -> dict[str, Any]:
+        buffer = self._get(buffer_id)
+        record = buffer.apply(operation)
+        result = self._state(buffer_id, buffer)
+        result["applied"] = _record(record)
+        return result
+
+    def history(self, buffer_id: str) -> list[dict[str, Any]]:
+        return [_record(record) for record in self._get(buffer_id).history]
+
+    def rollback(self, buffer_id: str, version: int) -> dict[str, Any]:
+        buffer = self._get(buffer_id)
+        record = buffer.rollback(version)
+        result = self._state(buffer_id, buffer)
+        result["applied"] = _record(record)
+        return result
+
+    def commit(self, buffer_id: str) -> dict[str, Any]:
+        buffer = self._get(buffer_id)
+        buffer.commit()
+        self._remember_command(buffer.view())
+        return self._state(buffer_id, buffer)
+
+    def command_history(self) -> list[dict[str, Any]]:
+        return list(self._commands)
+
+    def select_command(
+        self,
+        command_id: str,
+        *,
+        buffer_id: str | None = None,
+    ) -> dict[str, Any]:
+        for item in self._commands:
+            if item["command_id"] == command_id:
+                return self.create(item["command"], buffer_id=buffer_id)
+        raise KeyError(f"unknown command: {command_id}")
+
+    def _get(self, buffer_id: str) -> EditBuffer:
+        try:
+            return self._buffers[buffer_id]
+        except KeyError as error:
+            raise KeyError(f"unknown buffer: {buffer_id}") from error
+
+    def _state(self, buffer_id: str, buffer: EditBuffer) -> dict[str, Any]:
+        return {
+            "buffer_id": buffer_id,
+            "content": buffer.view(),
+            "version": buffer.version,
+            "versions": list(buffer.versions),
+            "committed": buffer.committed,
+        }
+
+    def _remember_command(self, command: str) -> None:
+        if not command.strip():
+            return
+        self._commands.insert(
+            0,
+            {
+                "command_id": f"cmd-{self._next_command_number}",
+                "command": command,
+            },
+        )
+        self._next_command_number += 1
+        del self._commands[10:]
+
+
+def _record(record: EditRecord) -> dict[str, Any]:
+    return {
+        "operation": record.operation.as_dict(),
+        "start": record.start,
+        "end": record.end,
+        "before": record.before,
+        "after": record.after,
+        "version_before": record.version_before,
+        "version_after": record.version_after,
+        "confidence": record.confidence,
+    }
+
+
+def create_server() -> Any:
+    try:
+        FastMCP = import_module("mcp.server.fastmcp").FastMCP
+    except ImportError as error:
+        raise RuntimeError(
+            "MCP support is not installed; run: pip install 'editbuffer[mcp]'"
+        ) from error
+
+    registry = BufferRegistry()
+    server = FastMCP(
+        "editbuffer",
+        instructions=(
+            "Use editbuffer for pending output that may need local corrections before "
+            "commit. Create one buffer, apply small selection-based edits, view when "
+            "needed, and commit only when final. Never retry ambiguous fuzzy edits "
+            "without narrowing the selection."
+        ),
+        json_response=True,
+    )
+
+    @server.tool()
+    def buffer_create(
+        content: str = "",
+        buffer_id: str | None = None,
+    ) -> dict[str, Any]:
+        """Create an in-memory pending output buffer."""
+        return registry.create(content, buffer_id=buffer_id)
+
+    @server.tool()
+    def buffer_list() -> list[dict[str, Any]]:
+        """List active pending output buffers."""
+        return registry.list_buffers()
+
+    @server.tool()
+    def buffer_view(buffer_id: str) -> dict[str, Any]:
+        """View current content, version, snapshots, and commit state."""
+        return registry.view(buffer_id)
+
+    @server.tool()
+    def buffer_edit(
+        buffer_id: str,
+        operation: dict[str, Any],
+    ) -> dict[str, Any]:
+        """Apply one JSON edit operation.
+
+        Example replace operation:
+        {"op": "replace", "target": {"type": "exact", "text": "old"}, "text": "new"}
+        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)
+
+    @server.tool()
+    def buffer_history(buffer_id: str) -> list[dict[str, Any]]:
+        """Return the audit trail for successful edits."""
+        return registry.history(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)
+
+    @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)
+
+    @server.tool()
+    def command_history() -> list[dict[str, Any]]:
+        """Return up to 10 most recently committed commands, newest first."""
+        return registry.command_history()
+
+    @server.tool()
+    def command_select(
+        command_id: str,
+        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 server
+
+
+def main() -> None:
+    create_server().run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()