doc-control 0.0.1.dev0__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,80 @@
+"""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`.
+
+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 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 in ("--version", "version"):
+        op = "capabilities"
+    elif op in ("--help", "-h"):
+        op = "help"
+    try:
+        rest = args[1:]
+        if op == "help" and len(rest) == 1 and not rest[0].startswith("-"):
+            request: dict[str, Any] = {"op": rest[0]}
+        else:
+            request = _read_request(rest)
+        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):
+            envelope = success(
+                op, out.result, doc=out.doc, warnings=out.warnings, next_cursor=out.next_cursor
+            )
+        else:
+            envelope = success(op, out)
+        code = 0
+    except DocControlError as err:
+        envelope = failure(op, err)
+        code = 2 if err.code in _USAGE_CODES else 1
+    except Exception as err:  # never leak a traceback instead of an envelope
+        envelope = failure(op, DocControlError(ErrorCode.INTERNAL, f"{type(err).__name__}: {err}"))
+        code = 1
+    print(json.dumps(envelope, ensure_ascii=False))
+    return code
+
+
+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/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)