doc-control 0.0.1__py3-none-any.whl

doc_control/__init__.py

@@ -0,0 +1,4 @@
+"""doc-control: deterministic, LLM-first control of Word documents."""
+
+__version__ = "0.0.1"
+API_VERSION = "1.0"

doc_control/__main__.py

@@ -0,0 +1,3 @@
+from doc_control.cli import main
+
+raise SystemExit(main())

doc_control/cli.py

@@ -0,0 +1,93 @@
+"""Command-line front door: `doc-control <op> [--json '<request>' | --json - < request.json]`.
+
+`doc-control help <op>` is shorthand for `doc-control help --json '{"op": "<op>"}'`, and
+`--help` / `-h` are aliases of `help`. `doc-control mcp` serves the same operations as an
+MCP server on stdio (see `doc_control.mcp`).
+
+Never prompts and never reads stdin unless asked with `--json -`, so an agent whose
+stdin is an open pipe cannot hang it. Prints exactly one JSON envelope on stdout. Exit codes:
+0 success, 1 operation error, 2 usage error (unknown op or invalid request).
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from doc_control.envelope import Reply, failure, success
+from doc_control.errors import DocControlError, ErrorCode
+from doc_control.registry import Operation, load_operations
+
+_USAGE_CODES = {ErrorCode.SCHEMA_INVALID}
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = sys.argv[1:] if argv is None else argv
+    registry = load_operations()
+    op = args[0] if args else "help"
+    if op == "mcp":
+        from doc_control.mcp import serve
+
+        return serve()
+    if op in ("--version", "version"):
+        op = "capabilities"
+    elif op in ("--help", "-h"):
+        op = "help"
+    rest = args[1:]
+    try:
+        if op == "help" and len(rest) == 1 and not rest[0].startswith("-"):
+            request: dict[str, Any] = {"op": rest[0]}
+        else:
+            request = _read_request(rest)
+    except DocControlError as err:
+        envelope, code = failure(op, err), 2
+    else:
+        envelope, code = execute(registry, op, request)
+    print(json.dumps(envelope, ensure_ascii=False))
+    return code
+
+
+def execute(
+    registry: dict[str, Operation], op: str, request: dict[str, Any]
+) -> tuple[dict[str, Any], int]:
+    """Run one operation; return its envelope and the CLI exit code. Never raises."""
+    try:
+        if op not in registry:
+            raise DocControlError(ErrorCode.SCHEMA_INVALID, f"unknown operation: {op}", op=op)
+        out = registry[op].run(request)
+        if isinstance(out, Reply):
+            return success(
+                op, out.result, doc=out.doc, warnings=out.warnings, next_cursor=out.next_cursor
+            ), 0
+        return success(op, out), 0
+    except DocControlError as err:
+        return failure(op, err), 2 if err.code in _USAGE_CODES else 1
+    except Exception as err:  # never leak a traceback instead of an envelope
+        internal = DocControlError(ErrorCode.INTERNAL, f"{type(err).__name__}: {err}")
+        return failure(op, internal), 1
+
+
+def _read_request(rest: list[str]) -> dict[str, Any]:
+    raw: str | None = None
+    if rest[:1] == ["--json"]:
+        if len(rest) < 2:
+            raise DocControlError(ErrorCode.SCHEMA_INVALID, "--json needs a value")
+        raw = sys.stdin.read() if rest[1] == "-" else rest[1]
+        if len(rest) > 2:
+            raise DocControlError(ErrorCode.SCHEMA_INVALID, f"unexpected arguments: {rest[2:]}")
+    elif rest:
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, f"unexpected arguments: {rest}")
+    if not raw or not raw.strip():
+        return {}
+    try:
+        value = json.loads(raw)
+    except json.JSONDecodeError as err:
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, f"request is not JSON: {err}") from err
+    if not isinstance(value, dict):
+        raise DocControlError(ErrorCode.SCHEMA_INVALID, "request must be a JSON object")
+    return value
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

doc_control/envelope.py

@@ -0,0 +1,40 @@
+"""The response envelope every operation returns."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from doc_control import API_VERSION
+from doc_control.errors import DocControlError
+
+
+@dataclass(frozen=True)
+class Reply:
+    """What a handler returns when it fills more of the envelope than ``result``."""
+
+    result: dict[str, Any]
+    doc: dict[str, Any] | None = None
+    warnings: list[str] = field(default_factory=list)
+    next_cursor: str | None = None
+
+
+def success(
+    op: str,
+    result: dict[str, Any],
+    *,
+    doc: dict[str, Any] | None = None,
+    warnings: list[str] | None = None,
+    next_cursor: str | None = None,
+) -> dict[str, Any]:
+    out: dict[str, Any] = {"api": API_VERSION, "ok": True, "op": op}
+    if doc is not None:
+        out["doc"] = doc
+    out["result"] = result
+    out["warnings"] = warnings or []
+    out["next"] = next_cursor
+    return out
+
+
+def failure(op: str, error: DocControlError) -> dict[str, Any]:
+    return {"api": API_VERSION, "ok": False, "op": op, "error": error.to_dict()}

doc_control/errors.py

@@ -0,0 +1,72 @@
+"""Stable error codes, each with a one-line hint on what to do next."""
+
+from __future__ import annotations
+
+from enum import StrEnum
+from typing import Any
+
+
+class ErrorCode(StrEnum):
+    DOC_NOT_FOUND = "DOC_NOT_FOUND"
+    NOT_A_DOCX = "NOT_A_DOCX"
+    DOC_LOCKED = "DOC_LOCKED"
+    DOC_CHANGED_ON_DISK = "DOC_CHANGED_ON_DISK"
+    SCHEMA_INVALID = "SCHEMA_INVALID"
+    ADDRESS_INVALID = "ADDRESS_INVALID"
+    STALE_ADDRESS = "STALE_ADDRESS"
+    ANCHOR_NOT_FOUND = "ANCHOR_NOT_FOUND"
+    ANCHOR_AMBIGUOUS = "ANCHOR_AMBIGUOUS"
+    UNSUPPORTED_CONTENT = "UNSUPPORTED_CONTENT"
+    BATCH_CONFLICT = "BATCH_CONFLICT"
+    VERIFY_FAILED_RESTORED = "VERIFY_FAILED_RESTORED"
+    COMMENT_NOT_FOUND = "COMMENT_NOT_FOUND"
+    STYLE_NOT_FOUND = "STYLE_NOT_FOUND"
+    STYLE_CONFLICT = "STYLE_CONFLICT"
+    RECIPE_INVALID = "RECIPE_INVALID"
+    HISTORY_NOT_FOUND = "HISTORY_NOT_FOUND"
+    INTERNAL = "INTERNAL"
+
+
+HINTS: dict[ErrorCode, str] = {
+    ErrorCode.DOC_NOT_FOUND: "Check the path; it is resolved relative to the current directory.",
+    ErrorCode.NOT_A_DOCX: "Pass a Word .docx file; .doc and other formats are not supported.",
+    ErrorCode.DOC_LOCKED: "Word has the file open: save and close it in Word, then retry.",
+    ErrorCode.DOC_CHANGED_ON_DISK: "The file changed since you read it: re-read, then retry.",
+    ErrorCode.SCHEMA_INVALID: "Run `doc-control help <op>` to see the request schema.",
+    ErrorCode.ADDRESS_INVALID: "Use an address from a read result, e.g. p142#a7b2c3d4.",
+    ErrorCode.STALE_ADDRESS: "Re-read the paragraph (para.get) or resolve its anchor, then retry.",
+    ErrorCode.ANCHOR_NOT_FOUND: "Widen the quote or its context, or search with find.",
+    ErrorCode.ANCHOR_AMBIGUOUS: "Pick one of the candidates, or add prefix/suffix context.",
+    ErrorCode.UNSUPPORTED_CONTENT: (
+        "Edit around fields, hyperlinks or controls; encrypted or ZIP64 packages are not"
+        " supported: save a normal copy in Word."
+    ),
+    ErrorCode.BATCH_CONFLICT: "Split overlapping operations into separate batches.",
+    ErrorCode.VERIFY_FAILED_RESTORED: "Nothing was changed; report the request that caused it.",
+    ErrorCode.COMMENT_NOT_FOUND: "List comments with comments.list and use an existing id.",
+    ErrorCode.STYLE_NOT_FOUND: "List styles with styles.list and use an existing id.",
+    ErrorCode.STYLE_CONFLICT: "Rename the style or merge it with style.merge.",
+    ErrorCode.RECIPE_INVALID: "Fix the recipe so it only uses the documented keys.",
+    ErrorCode.HISTORY_NOT_FOUND: "List history with history.list and use an existing op id.",
+    ErrorCode.INTERNAL: "Unexpected error; nothing was written. Report it with the request.",
+}
+
+
+class DocControlError(Exception):
+    """An error with a stable code; the CLI turns it into an error envelope."""
+
+    def __init__(self, code: ErrorCode, message: str, **details: Any) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.details = details
+
+    def to_dict(self) -> dict[str, Any]:
+        out: dict[str, Any] = {
+            "code": self.code.value,
+            "message": self.message,
+            "hint": HINTS[self.code],
+        }
+        if self.details:
+            out["details"] = self.details
+        return out

doc_control/mcp.py

@@ -0,0 +1,94 @@
+"""MCP front door: `doc-control mcp` serves every registered operation as a tool, on stdio.
+
+A thin wrapper over the operation registry (decision D-8): one tool per operation, the
+operation's JSON Schema as the tool's input schema, and the usual response envelope as
+the tool result. The transport is newline-delimited JSON-RPC 2.0 on stdin/stdout, which
+is all a tools-only MCP server needs, so this stays standard library only.
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import IO, Any
+
+from doc_control import __version__
+from doc_control.cli import execute
+from doc_control.registry import Operation, load_operations
+
+# Protocol revisions this server speaks; the newest is offered to a client that asks for another.
+PROTOCOL_VERSIONS = ("2025-06-18", "2025-03-26", "2024-11-05")
+
+
+def tool_name(op: str) -> str:
+    """Operation names have dots (`para.move`); many MCP clients only accept [A-Za-z0-9_-]."""
+    return op.replace(".", "_")
+
+
+def _tools(registry: dict[str, Operation]) -> list[dict[str, Any]]:
+    return [
+        {
+            "name": tool_name(op.name),
+            "description": op.summary,
+            "inputSchema": op.schema,
+            "annotations": {"readOnlyHint": op.kind == "read"},
+        }
+        for op in sorted(registry.values(), key=lambda o: o.name)
+    ]
+
+
+def handle(registry: dict[str, Operation], message: Any) -> dict[str, Any] | None:
+    """Answer one JSON-RPC message; None for a notification."""
+    if not isinstance(message, dict) or not isinstance(message.get("method"), str):
+        return _error(None, -32600, "invalid request")
+    if "id" not in message:
+        return None
+    msg_id, method = message["id"], message["method"]
+    params = message.get("params")
+    params = params if isinstance(params, dict) else {}
+    if method == "initialize":
+        asked = params.get("protocolVersion")
+        result: dict[str, Any] = {
+            "protocolVersion": asked if asked in PROTOCOL_VERSIONS else PROTOCOL_VERSIONS[0],
+            "capabilities": {"tools": {}},
+            "serverInfo": {"name": "doc-control", "version": __version__},
+        }
+    elif method == "ping":
+        result = {}
+    elif method == "tools/list":
+        result = {"tools": _tools(registry)}
+    elif method == "tools/call":
+        ops = {tool_name(name): name for name in registry}
+        name, arguments = params.get("name"), params.get("arguments", {})
+        if name not in ops or not isinstance(arguments, dict):
+            return _error(msg_id, -32602, f"unknown tool or invalid arguments: {name}")
+        envelope, _ = execute(registry, ops[name], arguments)
+        result = {
+            "content": [{"type": "text", "text": json.dumps(envelope, ensure_ascii=False)}],
+            "isError": not envelope["ok"],
+        }
+    else:
+        return _error(msg_id, -32601, f"method not found: {method}")
+    return {"jsonrpc": "2.0", "id": msg_id, "result": result}
+
+
+def _error(msg_id: Any, code: int, message: str) -> dict[str, Any]:
+    return {"jsonrpc": "2.0", "id": msg_id, "error": {"code": code, "message": message}}
+
+
+def serve(stdin: IO[bytes] | None = None, stdout: IO[bytes] | None = None) -> int:
+    """Serve until stdin closes. Bytes in and out, so the encoding is UTF-8 on every platform."""
+    stdin = sys.stdin.buffer if stdin is None else stdin
+    stdout = sys.stdout.buffer if stdout is None else stdout
+    registry = load_operations()
+    for line in stdin:
+        if not line.strip():
+            continue
+        try:
+            reply = handle(registry, json.loads(line))
+        except ValueError:
+            reply = _error(None, -32700, "parse error")
+        if reply is not None:
+            stdout.write(json.dumps(reply, ensure_ascii=False).encode() + b"\n")
+            stdout.flush()
+    return 0

doc_control/model/__init__.py

@@ -0,0 +1 @@
+"""Document model: the paragraph index, addresses and ranges."""

doc_control/model/address.py

@@ -0,0 +1,113 @@
+"""Paragraph addresses ``p<n>#<fp>`` and the ranges built on them.
+
+``n`` is the 1-based index over the main story's paragraphs and ``fp`` the first
+8 hex digits of BLAKE2s over the paragraph's visible text, NFC-normalised.
+
+Forms accepted by :func:`parse_range` (offsets are characters of the visible
+text, the end exclusive)::
+
+    p142#a7b2a7b2                          the whole paragraph
+    p142#a7b2a7b2:10-15                    inside one paragraph
+    p142#a7b2a7b2:10..p144#0c9e0c9e:3      across paragraphs (the end paragraph is later)
+    p142#a7b2a7b2.s3                       the third sentence (resolved by segmentation)
+
+Parsing is strict: numbers have no leading zeros and no sign. Upper-case hex is
+accepted and lower-cased, so ``str(parse_range(s)) == s`` for every canonical
+``s``. Anything else raises ``DocControlError(ADDRESS_INVALID)``.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import re
+import unicodedata
+from dataclasses import dataclass
+
+from doc_control.errors import DocControlError, ErrorCode
+
+FINGERPRINT_LENGTH = 8
+
+# Bounded digit runs keep int() clear of Python's digit-conversion limit.
+_NUM = r"(?:0|[1-9][0-9]{0,11})"
+_POS = r"[1-9][0-9]{0,11}"
+_HEX = rf"[0-9a-fA-F]{{{FINGERPRINT_LENGTH}}}"
+_RANGE = re.compile(
+    rf"p(?P<n1>{_POS})#(?P<f1>{_HEX})"
+    rf"(?::(?P<a>{_NUM})-(?P<b>{_NUM})"
+    rf"|:(?P<c>{_NUM})\.\.p(?P<n2>{_POS})#(?P<f2>{_HEX}):(?P<d>{_NUM})"
+    rf"|\.s(?P<s>{_POS}))?"
+)
+
+
+def fingerprint(text: str) -> str:
+    """The 8-hex-digit fingerprint of a paragraph's visible ``text``."""
+    data = unicodedata.normalize("NFC", text).encode("utf-8")
+    return hashlib.blake2s(data).hexdigest()[:FINGERPRINT_LENGTH]
+
+
+@dataclass(frozen=True)
+class Address:
+    """``p<number>#<fp>``: a paragraph position plus a fingerprint of its text."""
+
+    number: int
+    fp: str
+
+    def __str__(self) -> str:
+        return f"p{self.number}#{self.fp}"
+
+
+@dataclass(frozen=True)
+class AddressRange:
+    """A parsed range. ``start`` and ``end`` are equal unless it crosses paragraphs.
+
+    Offsets are ``None`` for a whole paragraph or a sentence; ``sentence`` is the
+    1-based sentence number, only set for the ``.s<k>`` form.
+    """
+
+    start: Address
+    end: Address
+    start_offset: int | None = None
+    end_offset: int | None = None
+    sentence: int | None = None
+
+    def __str__(self) -> str:
+        if self.sentence is not None:
+            return f"{self.start}.s{self.sentence}"
+        if self.start_offset is None or self.end_offset is None:
+            return str(self.start)
+        if self.start == self.end:
+            return f"{self.start}:{self.start_offset}-{self.end_offset}"
+        return f"{self.start}:{self.start_offset}..{self.end}:{self.end_offset}"
+
+
+def _invalid(text: object, why: str) -> DocControlError:
+    return DocControlError(ErrorCode.ADDRESS_INVALID, f"{text!r} {why}", address=str(text))
+
+
+def parse_address(text: str) -> Address:
+    """Parse a bare paragraph address (no offsets, no sentence)."""
+    rng = parse_range(text)
+    if rng.sentence is not None or rng.start_offset is not None:
+        raise _invalid(text, "is not a bare paragraph address like p142#a7b2a7b2")
+    return rng.start
+
+
+def parse_range(text: str) -> AddressRange:
+    """Parse any address or range form listed in the module docstring."""
+    m = _RANGE.fullmatch(text) if isinstance(text, str) else None
+    if m is None:
+        raise _invalid(text, "is not an address or range like p142#a7b2a7b2:10-15")
+    start = Address(int(m["n1"]), m["f1"].lower())
+    if m["s"] is not None:
+        return AddressRange(start, start, sentence=int(m["s"]))
+    if m["a"] is not None:
+        a, b = int(m["a"]), int(m["b"])
+        if a > b:
+            raise _invalid(text, "ends before it starts")
+        return AddressRange(start, start, a, b)
+    if m["c"] is not None:
+        end = Address(int(m["n2"]), m["f2"].lower())
+        if end.number <= start.number:
+            raise _invalid(text, "must end in a later paragraph than it starts")
+        return AddressRange(start, end, int(m["c"]), int(m["d"]))
+    return AddressRange(start, start)