licos-dev-sdk 0.4.1__tar.gz → 0.4.2__tar.gz

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.2}/.gitignore

@@ -34,6 +34,8 @@ crates/industrial/industrial-stack.env
 *.log
 *.pid
 .licos
+# Keep project template metadata in version control.
+!/tools/licos-ai-cli/lib/__templates__/*/.licos
 .tmp
 .playwright-cli
 
@@ -41,6 +43,8 @@ crates/industrial/industrial-stack.env
 crates/industrial/bin/
 
 tools/android-sdk-cache/*.zip
+tools/android-sdk-cache/*.tar.xz
+tools/android-sdk-cache/*.tar.gz
 tools/codegraph-cache/*.tgz
 tools/codegraph-cache/*.tgz
 

licos_dev_sdk-0.4.2/DOCX.md

@@ -0,0 +1,60 @@
+# Word SDK / CLI 0.4.2
+
+Cloud document execution stays in `licos-dev-sdk` and `licos-dev`. CLI commands
+only parse arguments and call the SDK; no additional Agent-native Word tools are
+registered. Existing `docx`, `docx-template`, `docx-read`, `docx-edit` commands and
+their Python APIs retain their invocation contracts.
+
+| CLI command | SDK function | Input |
+| --- | --- | --- |
+| `docx-structure` | `read_docx_structure` | File, blocks/paragraphs, page |
+| `docx-target` | `read_docx_target` | File, exact target, text cursor |
+| `docx-replace` | `replace_docx_text` | Source/output, revision, target, search/replacement |
+| `docx-delete-blocks` | `delete_docx_blocks` | Source/output, revision, inclusive block range |
+| `docx-edit-structure` | `edit_docx_structure` | Source/output, revision, small operations array |
+| `docx-table-set` | `set_docx_cell` | Source/output, revision, table/row/column, text |
+| `docx-table-insert-rows` | `insert_docx_rows` | Source/output, revision, table, insertion point, template row, rows |
+| `docx-verify` | `verify_docx` | File, optional positional assertions |
+
+## Contract
+
+- `target` has exactly one shape: `{"block":1}`, `{"paragraph":1}`, or
+  `{"table":1,"row":1,"column":1}`. Indices start at 1. Paragraph indices include
+  empty paragraphs and paragraphs inside tables; a body table occupies one block.
+  A merged cell must use its anchor coordinate. Existing `docx-read.paragraph`
+  is a legacy display ordinal; use its new `target` for editing.
+- `revision` is the SHA256 of the source `word/document.xml` bytes. Reads and edits
+  return it. Every new editing entry point requires the source revision; the
+  next batch uses the output and its returned revision.
+- Batch structure operations contain only `replace_text` with `target/search/replace`
+  or `delete_blocks` with `from/to`. All targets refer to the input snapshot.
+  Invalid, missing, duplicate or removed targets fail before publishing output.
+- `docx-replace` expects one exact match within one paragraph in the selected
+  target. It supports text split across runs and preserves surrounding formatting.
+  `--replace-file` carries long replacement text; simple replacements need no JSON.
+- `docx-table-insert-rows --input rows.json` accepts scalar row arrays such as
+  `[["pump","set",2],["valve",null,3]]`. Row count is derived; each merged physical
+  cell is filled once. Row/cell/paragraph/run styles come from `--template-row`.
+  Templates that intersect vertical merges are rejected explicitly.
+- New editing commands default to refusing an existing output, including the
+  source itself. `--overwrite` explicitly allows replacement. Body edits are
+  atomic and keep all other ZIP part payloads unchanged. Existing `docx-edit`
+  retains its existing overwrite behavior and additionally supports `template_row`.
+- Structure previews set `content_truncated`; `docx-target` retrieves exact text
+  without stripping whitespace and provides `next_text_offset` until `has_more=false`.
+  No partial JSON repair or automatic argument completion is performed.
+- Verification without assertions checks structure only: `content_verified=false`.
+  Positional assertions use `equals`, `contains` or `absent`. A mismatch produces
+  `verified=false` and CLI exit code 2. Layout and page breaks require visual review.
+
+## Verification
+
+Run Python tests serially with the current source on `PYTHONPATH`:
+
+```text
+python -m pytest tools/licos-dev-sdk/tests/test_docx_structure.py tools/licos-dev-cli/tests/test_docx_commands.py
+```
+
+Runtime acceptance must exercise skill discovery, file input, CLI execution and
+independent DOCX verification through both AgentRuntime and CodexRuntime. The CLI
+help size check measures discoverability; it is not a universal model schema limit.

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: licos-dev-sdk
-Version: 0.4.1
+Version: 0.4.2
 Summary: LICOS Dev SDK - file generation and model capability clients
 Requires-Python: >=3.10
 Requires-Dist: beautifulsoup4>=4.12

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "licos-dev-sdk"
-version = "0.4.1"
+version = "0.4.2"
 description = "LICOS Dev SDK - file generation and model capability clients"
 requires-python = ">=3.10"
 dependencies = [

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.2}/src/licos_dev_sdk/__init__.py

@@ -29,6 +29,14 @@ def __getattr__(name: str):
         "create_docx": ("document", "create_docx"),
         "create_docx_from_template": ("document", "create_docx_from_template"),
         "edit_docx": ("document", "edit_docx"),
+        "read_docx_structure": ("document_docx_structure", "read_docx_structure"),
+        "read_docx_target": ("document_docx_structure", "read_docx_target"),
+        "edit_docx_structure": ("document_docx_structure", "edit_docx_structure"),
+        "replace_docx_text": ("document_docx_structure", "replace_docx_text"),
+        "delete_docx_blocks": ("document_docx_structure", "delete_docx_blocks"),
+        "verify_docx": ("document_docx_structure", "verify_docx"),
+        "set_docx_cell": ("document_docx_table_actions", "set_docx_cell"),
+        "insert_docx_rows": ("document_docx_table_actions", "insert_docx_rows"),
         "read_pdf": ("document_read", "read_pdf"),
         "read_docx": ("document_read", "read_docx"),
         "read_xlsx": ("document_read", "read_xlsx"),
@@ -100,6 +108,8 @@ def __getattr__(name: str):
 
 
 __all__ = [
+    "read_docx_structure", "read_docx_target", "edit_docx_structure",
+    "replace_docx_text", "delete_docx_blocks", "verify_docx", "set_docx_cell", "insert_docx_rows",
     "create_json", "create_xml", "create_yaml",
     "create_zip", "create_tar_gz",
     "create_qrcode", "create_barcode", "create_watermark",

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.2}/src/licos_dev_sdk/document_docx_edit.py

@@ -4,19 +4,16 @@ from __future__ import annotations
 
 from copy import deepcopy
 from pathlib import Path
-import os
 import re
-import tempfile
 from typing import Any
-from zipfile import ZIP_DEFLATED, ZipFile
 
 from docx.oxml.ns import qn
 from lxml import etree
 
 from .document_docx_table import TableCell, TableModel, parse_table
+from .document_docx_package import DocxPackage
 
 
-_DOCUMENT_XML = "word/document.xml"
 _HEX_COLOR = re.compile(r"^[0-9A-Fa-f]{6}$")
 
 
@@ -24,6 +21,9 @@ def edit_docx_tables(
     source: str | Path,
     output: str | Path,
     operations: list[dict[str, Any]],
+    *,
+    revision: str | None = None,
+    overwrite: bool = True,
 ) -> str:
     """Apply explicit table operations to a DOCX package."""
 
@@ -38,42 +38,16 @@ def edit_docx_tables(
     if not all(isinstance(operation, dict) for operation in operations):
         raise TypeError("every DOCX edit operation must be an object")
 
-    with ZipFile(source_path, "r") as archive:
-        if _DOCUMENT_XML not in archive.namelist():
-            raise ValueError("DOCX package does not contain word/document.xml")
-        root = etree.fromstring(archive.read(_DOCUMENT_XML))
-        for operation_number, operation in enumerate(operations, start=1):
-            try:
-                _apply_operation(root, operation)
-            except (KeyError, TypeError, ValueError) as exc:
-                name = operation.get("op", "<missing>")
-                raise ValueError(
-                    f"DOCX operation {operation_number} ({name}) failed: {exc}"
-                ) from exc
-
-        output_path.parent.mkdir(parents=True, exist_ok=True)
-        handle, temporary_name = tempfile.mkstemp(
-            prefix=f".{output_path.stem}-",
-            suffix=".docx",
-            dir=output_path.parent,
-        )
-        os.close(handle)
-        temporary_path = Path(temporary_name)
+    package = DocxPackage(source_path)
+    if revision is not None:
+        package.require_revision(revision)
+    for operation_number, operation in enumerate(operations, start=1):
         try:
-            with ZipFile(temporary_path, "w", ZIP_DEFLATED) as destination:
-                for info in archive.infolist():
-                    payload = archive.read(info.filename)
-                    if info.filename == _DOCUMENT_XML:
-                        payload = etree.tostring(
-                            root,
-                            xml_declaration=True,
-                            encoding="UTF-8",
-                            standalone=True,
-                        )
-                    destination.writestr(info, payload)
-            os.replace(temporary_path, output_path)
-        finally:
-            temporary_path.unlink(missing_ok=True)
+            _apply_operation(package.root, operation)
+        except (KeyError, TypeError, ValueError) as exc:
+            name = operation.get("op", "<missing>")
+            raise ValueError(f"DOCX operation {operation_number} ({name}) failed: {exc}") from exc
+    package.save(output_path, overwrite=overwrite)
     return str(output_path)
 
 
@@ -327,12 +301,28 @@ def _insert_rows(table: Any, model: TableModel, operation: dict[str, Any]) -> No
     values = operation.get("rows", [])
     if values and (not isinstance(values, list) or len(values) != count):
         raise ValueError("rows must contain exactly count row arrays")
+    template = None
+    if "template_row" in operation:
+        template = _row(model, _positive(operation, "template_row")).element
+        if any(cell.row_span > 1 for row in model.rows for cell in row.cells
+               if cell.row <= operation["template_row"] < cell.row + cell.row_span):
+            raise ValueError("template_row cannot intersect a vertical merge")
     reference = model.rows[before - 1].element if before <= len(model.rows) else None
     for index in range(count):
         row_values = values[index] if values else []
         if not isinstance(row_values, list):
             raise TypeError("each inserted row must be an array")
-        row_element = _blank_row(model.column_count, row_values)
+        if template is None:
+            row_element = _blank_row(model.column_count, row_values)
+        else:
+            row_element = deepcopy(template)
+            cells = list(row_element.iterchildren(qn("w:tc")))
+            if len(row_values) != len(cells):
+                raise ValueError("template rows must provide one value per physical cell; merged cells are filled once")
+            for cell, value in zip(cells, row_values):
+                if value is not None and type(value) not in (str, int, float, bool):
+                    raise TypeError("DOCX row values must be strings, numbers, booleans or null")
+                _set_cell_content(cell, {"value": "" if value is None else value})
         if reference is None:
             table.append(row_element)
         else:

licos_dev_sdk-0.4.2/src/licos_dev_sdk/document_docx_package.py

@@ -0,0 +1,57 @@
+"""Read and replace the DOCX body without rewriting other package parts."""
+
+from __future__ import annotations
+
+from hashlib import sha256
+import os
+from pathlib import Path
+import tempfile
+from zipfile import ZipFile
+
+from lxml import etree
+
+DOCUMENT_XML = "word/document.xml"
+
+
+class DocxPackage:
+    def __init__(self, source: str | Path):
+        self.path = Path(source).expanduser().resolve()
+        if self.path.suffix.lower() != ".docx":
+            raise ValueError("source must be a .docx file")
+        with ZipFile(self.path) as archive:
+            self.comment = archive.comment
+            self.parts = [(info, archive.read(info.filename)) for info in archive.infolist()]
+        xml = next((data for info, data in self.parts if info.filename == DOCUMENT_XML), None)
+        if xml is None:
+            raise ValueError("DOCX package does not contain word/document.xml")
+        self.revision = sha256(xml).hexdigest()
+        self.root = etree.fromstring(xml, etree.XMLParser(resolve_entities=False, no_network=True))
+
+    def require_revision(self, revision: str) -> None:
+        if revision != self.revision:
+            raise ValueError("document revision changed; read the source again and use its current revision")
+
+    def save(self, output: str | Path, *, overwrite: bool = False) -> dict:
+        path = Path(output).expanduser().resolve()
+        if path.suffix.lower() != ".docx":
+            raise ValueError("output must be a .docx file")
+        if path.exists() and not overwrite:
+            raise FileExistsError(f"output exists: {path}; explicitly enable overwrite to replace it")
+        xml = etree.tostring(self.root, xml_declaration=True, encoding="UTF-8", standalone=True)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        handle, temporary = tempfile.mkstemp(prefix=f".{path.stem}-", suffix=".docx", dir=path.parent)
+        os.close(handle)
+        temporary_path = Path(temporary)
+        try:
+            with ZipFile(temporary_path, "w") as archive:
+                archive.comment = self.comment
+                for info, data in self.parts:
+                    archive.writestr(info, xml if info.filename == DOCUMENT_XML else data)
+            if overwrite:
+                os.replace(temporary_path, path)
+            else:
+                # Publish atomically without overwriting a concurrently created output.
+                os.link(temporary_path, path)
+        finally:
+            temporary_path.unlink(missing_ok=True)
+        return {"path": str(path), "revision": sha256(xml).hexdigest()}

licos_dev_sdk-0.4.2/src/licos_dev_sdk/document_docx_structure.py

@@ -0,0 +1,219 @@
+"""Small, revision-bound DOCX operations for SDK and CLI callers."""
+
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any
+import re
+
+from docx.oxml.ns import qn
+from lxml import etree
+
+from .document_docx_package import DocxPackage
+from .document_docx_table import parse_table
+
+TEXT_TAGS = {qn("w:t"): None, qn("w:tab"): "\t", qn("w:br"): "\n", qn("w:cr"): "\n"}
+
+
+def _index(value: int, name: str, minimum: int = 1) -> int:
+    if type(value) is not int or value < minimum:
+        raise ValueError(f"{name} must be an integer >= {minimum}")
+    return value
+
+
+def _paragraph_text(paragraph: Any) -> str:
+    return "".join((node.text or "") if node.tag == qn("w:t") else TEXT_TAGS[node.tag]
+                   for node in paragraph.iter() if node.tag in TEXT_TAGS)
+
+
+def _text(element: Any) -> str:
+    return "\n".join(_paragraph_text(p) for p in element.iter(qn("w:p")))
+
+
+class _Structure:
+    def __init__(self, root: Any):
+        self.body = root.find(qn("w:body"))
+        if self.body is None:
+            raise ValueError("DOCX body is missing")
+        self.blocks = [child for child in self.body if child.tag != qn("w:sectPr")]
+        self.paragraphs = list(self.body.iter(qn("w:p")))
+        self.tables = list(self.body.iterchildren(qn("w:tbl")))
+
+    def target(self, target: dict[str, int]) -> Any:
+        if not isinstance(target, dict):
+            raise TypeError("target must be an object")
+        keys = set(target)
+        if keys == {"block"} or keys == {"paragraph"}:
+            kind = next(iter(keys))
+            collection = self.blocks if kind == "block" else self.paragraphs
+            number = _index(target[kind], kind)
+            if number > len(collection):
+                raise ValueError(f"{kind} {number} does not exist")
+            return collection[number - 1]
+        if keys == {"table", "row", "column"}:
+            table, row, column = (_index(target[key], key) for key in ("table", "row", "column"))
+            if table > len(self.tables):
+                raise ValueError(f"table {table} does not exist")
+            cell = parse_table(self.tables[table - 1], include_nested=False).cell_at(row, column)
+            if cell is None:
+                raise ValueError(f"cell {target} does not exist")
+            if (cell.row, cell.column) != (row, column):
+                raise ValueError(f"use the merged cell anchor: table={table}, row={cell.row}, column={cell.column}")
+            return cell.element
+        raise ValueError("target must contain only block, only paragraph, or table+row+column")
+
+
+def read_docx_structure(source: str | Path, *, scope: str = "blocks", offset: int = 1,
+                        limit: int = 20, max_chars: int = 200) -> dict:
+    """Read stable one-based targets; paragraph numbering includes table paragraphs."""
+    _index(offset, "offset")
+    _index(limit, "limit")
+    _index(max_chars, "max_chars")
+    if scope not in {"blocks", "paragraphs"}:
+        raise ValueError("scope must be blocks or paragraphs")
+    package = DocxPackage(source)
+    structure = _Structure(package.root)
+    elements = structure.blocks if scope == "blocks" else structure.paragraphs
+    items = []
+    for number, element in enumerate(elements[offset - 1:offset - 1 + limit], offset):
+        text = _text(element)
+        items.append({"target": {scope[:-1]: number}, "type": etree.QName(element).localname,
+                      "text": text[:max_chars], "content_truncated": len(text) > max_chars})
+    next_offset = offset + len(items)
+    return {"path": str(package.path), "revision": package.revision, "scope": scope,
+            "coordinate_systems": {"block": "top-level body blocks; a table is one block",
+                                   "paragraph": "all body paragraphs, including paragraphs in tables"},
+            "block_count": len(structure.blocks), "paragraph_count": len(structure.paragraphs),
+            "table_count": len(structure.tables), "items": items, "has_more": next_offset <= len(elements),
+            "next_offset": next_offset if next_offset <= len(elements) else None}
+
+
+def read_docx_target(source: str | Path, target: dict[str, int], *, text_offset: int = 0,
+                     max_chars: int = 8000) -> dict:
+    """Read a target's text with an explicit continuation cursor, without stripping whitespace."""
+    _index(text_offset, "text_offset", 0)
+    _index(max_chars, "max_chars")
+    package = DocxPackage(source)
+    text = _text(_Structure(package.root).target(target))
+    part = text[text_offset:text_offset + max_chars]
+    end = text_offset + len(part)
+    return {"path": str(package.path), "revision": package.revision, "target": target,
+            "text": part, "text_offset": text_offset, "total_characters": len(text),
+            "has_more": end < len(text), "next_text_offset": end if end < len(text) else None}
+
+
+def _replacement_nodes(value: str) -> list:
+    nodes = []
+    for part in re.split("(\n|\t)", value):
+        if not part:
+            continue
+        node = etree.Element(qn("w:br" if part == "\n" else "w:tab" if part == "\t" else "w:t"))
+        if part not in {"\n", "\t"}:
+            node.text = part
+            node.set(qn("xml:space"), "preserve")
+        nodes.append(node)
+    return nodes
+
+
+def _replace(target: Any, search: str, replacement: str) -> None:
+    if not isinstance(search, str) or not search or not isinstance(replacement, str):
+        raise ValueError("search must be a non-empty string and replace must be a string")
+    matches = []
+    for paragraph in target.iter(qn("w:p")):
+        text = _paragraph_text(paragraph)
+        start = text.find(search)
+        while start >= 0:
+            matches.append((paragraph, start))
+            start = text.find(search, start + 1)
+    if len(matches) != 1:
+        raise ValueError(f"search must match exactly once within one target paragraph; found {len(matches)}; "
+                         f"target text={_text(target)[:200]!r}")
+    paragraph, start = matches[0]
+    end, offset, inserted = start + len(search), 0, False
+    for node in [n for n in paragraph.iter() if n.tag in TEXT_TAGS]:
+        value = (node.text or "") if node.tag == qn("w:t") else TEXT_TAGS[node.tag]
+        next_offset = offset + len(value)
+        if next_offset > start and offset < end:
+            new_value = value[:max(0, start - offset)] + ("" if inserted else replacement) + value[min(len(value), end - offset):]
+            parent, index = node.getparent(), node.getparent().index(node)
+            parent.remove(node)
+            for added in _replacement_nodes(new_value):
+                parent.insert(index, added)
+                index += 1
+            inserted = True
+        offset = next_offset
+
+
+def edit_docx_structure(source: str | Path, output: str | Path, *, revision: str,
+                        operations: list[dict], overwrite: bool = False) -> dict:
+    """Apply up to 200 edits against one read snapshot, atomically preserving other parts."""
+    if not isinstance(operations, list) or not 1 <= len(operations) <= 200:
+        raise ValueError("operations must be an array with 1-200 entries")
+    package = DocxPackage(source)
+    package.require_revision(revision)
+    structure = _Structure(package.root)
+    resolved = []
+    for index, operation in enumerate(operations, 1):
+        if not isinstance(operation, dict):
+            raise TypeError(f"operation {index} must be an object")
+        if operation.get("op") == "replace_text" and set(operation) == {"op", "target", "search", "replace"}:
+            resolved.append((operation, [structure.target(operation["target"])]))
+        elif operation.get("op") == "delete_blocks" and set(operation) == {"op", "from", "to"}:
+            first, last = _index(operation["from"], "from"), _index(operation["to"], "to")
+            if first > last or last > len(structure.blocks):
+                raise ValueError(f"operation {index}: invalid block range")
+            resolved.append((operation, structure.blocks[first - 1:last]))
+        else:
+            raise ValueError(f"operation {index}: expected replace_text(op,target,search,replace) or delete_blocks(op,from,to)")
+    for index, (operation, elements) in enumerate(resolved, 1):
+        try:
+            for element in elements:
+                if structure.body not in element.iterancestors():
+                    raise ValueError("target was removed by an earlier operation")
+                if operation["op"] == "replace_text":
+                    _replace(element, operation["search"], operation["replace"])
+                else:
+                    if next(element.iter(qn("w:sectPr")), None) is not None:
+                        raise ValueError("block contains section properties; deleting it would change section layout")
+                    structure.body.remove(element)
+        except ValueError as exc:
+            raise ValueError(f"operation {index} ({operation['op']}), target={operation.get('target')}: {exc}") from exc
+    return {**package.save(output, overwrite=overwrite), "applied_operations": len(operations)}
+
+
+def replace_docx_text(source: str | Path, output: str | Path, *, revision: str,
+                      target: dict[str, int], search: str, replacement: str, overwrite: bool = False) -> dict:
+    return edit_docx_structure(source, output, revision=revision, overwrite=overwrite,
+                               operations=[{"op": "replace_text", "target": target, "search": search, "replace": replacement}])
+
+
+def delete_docx_blocks(source: str | Path, output: str | Path, *, revision: str,
+                       first: int, last: int, overwrite: bool = False) -> dict:
+    return edit_docx_structure(source, output, revision=revision, overwrite=overwrite,
+                               operations=[{"op": "delete_blocks", "from": first, "to": last}])
+
+
+def verify_docx(source: str | Path, *, expectations: list[dict] | None = None) -> dict:
+    """Check package structure and exact positions; absent assertions do not certify content."""
+    package = DocxPackage(source)
+    structure = _Structure(package.root)
+    for table in structure.tables:
+        parse_table(table)
+    expectations = [] if expectations is None else expectations
+    if not isinstance(expectations, list):
+        raise TypeError("expectations must be an array")
+    mismatches = []
+    for index, expectation in enumerate(expectations, 1):
+        if not isinstance(expectation, dict) or not {"target", "text"} <= set(expectation) or set(expectation) - {"target", "text", "mode"}:
+            raise ValueError(f"expectation {index} requires target,text and optional mode")
+        expected, mode = expectation["text"], expectation.get("mode", "equals")
+        if not isinstance(expected, str) or mode not in {"equals", "contains", "absent"}:
+            raise ValueError(f"expectation {index}: text must be a string; mode must be equals, contains or absent")
+        actual = _text(structure.target(expectation["target"]))
+        passed = actual == expected if mode == "equals" else expected in actual if mode == "contains" else expected not in actual
+        if not passed:
+            mismatches.append({"index": index, "target": expectation["target"], "mode": mode, "expected": expected,
+                               "actual": actual[:1000], "actual_truncated": len(actual) > 1000})
+    return {"path": str(package.path), "revision": package.revision, "structure_verified": True,
+            "content_verified": bool(expectations) and not mismatches, "verified": not mismatches,
+            "expectation_count": len(expectations), "mismatches": mismatches}

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.2}/src/licos_dev_sdk/document_docx_table.py

@@ -197,6 +197,7 @@ def table_row_items(
                 max_chars=max_chars,
                 include_styles=include_styles,
             )
+            value["target"] = {"table": table_number, "row": cell.row, "column": cell.column}
             cells.append(value)
             truncated = truncated or cell_truncated
         item: dict[str, Any] = {

licos_dev_sdk-0.4.2/src/licos_dev_sdk/document_docx_table_actions.py

@@ -0,0 +1,33 @@
+"""Focused table actions with explicit coordinates and revision checks."""
+
+from pathlib import Path
+
+from .document_docx_edit import _apply_operation
+from .document_docx_package import DocxPackage
+from .document_docx_structure import _Structure, _index
+
+
+def set_docx_cell(source: str | Path, output: str | Path, *, revision: str,
+                  table: int, row: int, column: int, text: str, overwrite: bool = False) -> dict:
+    if not isinstance(text, str):
+        raise TypeError("text must be a string")
+    package = DocxPackage(source)
+    package.require_revision(revision)
+    _Structure(package.root).target({"table": table, "row": row, "column": column})
+    _apply_operation(package.root, {"op": "set_cell", "table": table, "row": row, "column": column, "text": text})
+    return package.save(output, overwrite=overwrite)
+
+
+def insert_docx_rows(source: str | Path, output: str | Path, *, revision: str,
+                     table: int, before: int, rows: list[list], template_row: int,
+                     overwrite: bool = False) -> dict:
+    """Clone a template row for each row of scalar values; count is derived from rows."""
+    for name, value in (("table", table), ("before", before), ("template_row", template_row)):
+        _index(value, name)
+    if not isinstance(rows, list) or not 1 <= len(rows) <= 200:
+        raise ValueError("rows must contain 1-200 row arrays")
+    package = DocxPackage(source)
+    package.require_revision(revision)
+    _apply_operation(package.root, {"op": "insert_rows", "table": table, "before": before,
+                                   "template_row": template_row, "count": len(rows), "rows": rows})
+    return {**package.save(output, overwrite=overwrite), "inserted_rows": len(rows)}

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.2}/src/licos_dev_sdk/document_read.py

@@ -182,6 +182,8 @@ def _read_docx(
     from docx.text.paragraph import Paragraph
 
     from .document_docx_table import parse_table, table_row_items
+    from hashlib import sha256
+    from zipfile import ZipFile
 
     document = Document(str(path))
     items: list[dict[str, Any]] = []
@@ -189,7 +191,7 @@ def _read_docx(
     paragraph_number = 0
     table_number = 0
 
-    for child in document.element.body.iterchildren():
+    for block_number, child in enumerate(document.element.body.iterchildren(), 1):
         tag = child.tag.rsplit("}", 1)[-1]
         if tag == "p":
             paragraph = Paragraph(child, document)
@@ -202,6 +204,7 @@ def _read_docx(
                 {
                     "type": "paragraph",
                     "paragraph": paragraph_number,
+                    "target": {"block": block_number},
                     "style": paragraph.style.name if paragraph.style is not None else None,
                     "text": text,
                     "content_truncated": truncated,
@@ -225,6 +228,8 @@ def _read_docx(
     result["paragraph_count"] = paragraph_number
     result["table_count"] = table_number
     result["warnings"] = warnings
+    with ZipFile(path) as archive:
+        result["revision"] = sha256(archive.read("word/document.xml")).hexdigest()
     return result
 
 

licos_dev_sdk-0.4.2/tests/test_docx_structure.py

@@ -0,0 +1,204 @@
+from pathlib import Path
+from zipfile import ZipFile
+
+from docx import Document
+from docx.oxml import OxmlElement
+from docx.oxml.ns import qn
+import pytest
+
+from licos_dev_sdk import (
+    read_docx, read_docx_structure, read_docx_target, replace_docx_text,
+    edit_docx_structure, delete_docx_blocks, verify_docx, set_docx_cell, insert_docx_rows,
+)
+
+
+@pytest.fixture
+def source(tmp_path):
+    path = tmp_path / "template.docx"
+    doc = Document()
+    doc.add_paragraph("")
+    p = doc.add_paragraph()
+    p.add_run("甲方账号：").bold = True
+    p.add_run("12").italic = True
+    p.add_run("3456")
+    table = doc.add_table(rows=2, cols=3)
+    table.cell(0, 0).merge(table.cell(0, 1)).text = "名称"
+    table.cell(0, 2).text = "数量"
+    table.cell(1, 0).text = "模板"
+    table.cell(1, 1).text = "单位"
+    table.cell(1, 2).text = "1"
+    table.cell(1, 0).paragraphs[0].runs[0].bold = True
+    shade = OxmlElement("w:shd")
+    shade.set(qn("w:fill"), "AABBCC")
+    table.cell(1, 0)._tc.get_or_add_tcPr().append(shade)
+    doc.add_paragraph("附录")
+    doc.add_paragraph("附件说明")
+    doc.sections[0].header.paragraphs[0].text = "保留页眉"
+    doc.save(path)
+    return path
+
+
+def rev(path):
+    return read_docx_structure(path)["revision"]
+
+
+def assert_parts_preserved(source, output):
+    with ZipFile(source) as before, ZipFile(output) as after:
+        assert before.namelist() == after.namelist()
+        for name in before.namelist():
+            if name != "word/document.xml":
+                assert before.read(name) == after.read(name), name
+
+
+def test_targets_distinguish_blocks_empty_paragraphs_and_table_paragraphs(source):
+    blocks = read_docx_structure(source, limit=3)
+    assert blocks["items"][0]["target"] == {"block": 1}
+    assert blocks["items"][2]["type"] == "tbl"
+    assert blocks["next_offset"] == 4
+    paragraphs = read_docx_structure(source, scope="paragraphs", offset=3, limit=1)
+    assert paragraphs["items"][0]["text"] == "名称"
+    assert paragraphs["items"][0]["target"] == {"paragraph": 3}
+    legacy = read_docx(source)
+    assert legacy["items"][0]["paragraph"] == 1  # preserve existing read numbering
+    assert legacy["items"][0]["target"] == {"block": 2}
+    assert legacy["items"][1]["cells"][0]["target"] == {"table": 1, "row": 1, "column": 1}
+    assert legacy["revision"] == blocks["revision"]
+
+
+def test_replace_spanning_runs_preserves_formatting_original_and_other_parts(source, tmp_path):
+    original = source.read_bytes()
+    output = tmp_path / "filled.docx"
+    report = replace_docx_text(source, output, revision=rev(source), target={"block": 2},
+                               search="123456", replacement="998877")
+    p = Document(output).paragraphs[1]
+    assert p.text == "甲方账号：998877"
+    assert p.runs[0].bold and p.runs[1].italic
+    assert report["revision"] == rev(output) != rev(source)
+    assert source.read_bytes() == original
+    assert_parts_preserved(source, output)
+
+
+def test_batch_targets_refer_to_input_snapshot_and_reject_removed_targets(source, tmp_path):
+    output = tmp_path / "batch.docx"
+    edit_docx_structure(source, output, revision=rev(source), operations=[
+        {"op": "delete_blocks", "from": 1, "to": 1},
+        {"op": "replace_text", "target": {"block": 2}, "search": "123456", "replace": "新账号"},
+    ])
+    assert Document(output).paragraphs[0].text == "甲方账号：新账号"
+    with pytest.raises(ValueError, match="removed"):
+        edit_docx_structure(source, tmp_path / "invalid.docx", revision=rev(source), operations=[
+            {"op": "delete_blocks", "from": 1, "to": 2},
+            {"op": "replace_text", "target": {"block": 2}, "search": "123456", "replace": "x"},
+        ])
+    assert not (tmp_path / "invalid.docx").exists()
+
+
+def test_delete_appendix_and_exact_cell_verification(source, tmp_path):
+    output = tmp_path / "no-appendix.docx"
+    delete_docx_blocks(source, output, revision=rev(source), first=4, last=5)
+    assert [p.text for p in Document(output).paragraphs] == ["", "甲方账号：123456"]
+    assert verify_docx(output)["content_verified"] is False
+    assert verify_docx(output, expectations=[{"target": {"block": 2}, "text": "123456", "mode": "contains"}])["content_verified"]
+    failed = verify_docx(output, expectations=[{"target": {"table": 1, "row": 2, "column": 1}, "text": "123456", "mode": "contains"}])
+    assert not failed["verified"]
+    assert failed["mismatches"][0]["actual"] == "模板"
+    assert_parts_preserved(source, output)
+
+
+def test_stale_revision_and_existing_output_leave_files_unchanged(source, tmp_path):
+    output = tmp_path / "existing.docx"
+    output.write_bytes(b"existing")
+    original = source.read_bytes()
+    with pytest.raises(ValueError, match="revision"):
+        delete_docx_blocks(source, output, revision="old", first=4, last=5, overwrite=True)
+    assert output.read_bytes() == b"existing"
+    with pytest.raises(FileExistsError):
+        delete_docx_blocks(source, source, revision=rev(source), first=4, last=5)
+    assert source.read_bytes() == original
+    delete_docx_blocks(source, source, revision=rev(source), first=4, last=5, overwrite=True)
+    assert read_docx_structure(source)["block_count"] == 3
+
+
+@pytest.mark.parametrize("target", [{"block": 2, "paragraph": 2}, {"block": True}, {"table": 1, "row": 1}, {"table": 1, "row": 1, "column": 2}])
+def test_invalid_or_non_anchor_targets_are_not_guessed(source, target):
+    with pytest.raises(ValueError):
+        read_docx_target(source, target)
+
+
+def test_exact_text_read_continues_across_long_whitespace_and_unicode(tmp_path):
+    source = tmp_path / "long.docx"
+    text = "  中文🙂\tA\n" * 90 + "  "
+    doc = Document()
+    doc.add_paragraph(text)
+    doc.save(source)
+    assert read_docx_structure(source, max_chars=10)["items"][0]["content_truncated"]
+    chunks, offset = [], 0
+    while True:
+        read = read_docx_target(source, {"paragraph": 1}, text_offset=offset, max_chars=37)
+        chunks.append(read["text"])
+        if not read["has_more"]:
+            break
+        offset = read["next_text_offset"]
+    assert "".join(chunks) == text
+
+
+def test_replace_tabs_newlines_and_empty_replacement(source, tmp_path):
+    output = tmp_path / "multiline.docx"
+    replace_docx_text(source, output, revision=rev(source), target={"paragraph": 2}, search="123456", replacement="A\tB\nC")
+    assert Document(output).paragraphs[1].text == "甲方账号：A\tB\nC"
+    replace_docx_text(output, output, revision=rev(output), target={"paragraph": 2}, search="A\tB\nC", replacement="", overwrite=True)
+    assert Document(output).paragraphs[1].text == "甲方账号："
+
+
+def test_clone_template_rows_preserves_styles_and_fills_scalars(source, tmp_path):
+    output = tmp_path / "rows.docx"
+    report = insert_docx_rows(source, output, revision=rev(source), table=1, before=3, template_row=2,
+                              rows=[["泵", "台", 2], ["阀", None, True]])
+    assert report["inserted_rows"] == 2
+    table = Document(output).tables[0]
+    assert table.cell(2, 0).text == "泵"
+    assert table.cell(2, 0).paragraphs[0].runs[0].bold
+    assert 'w:fill="AABBCC"' in table.cell(2, 0)._tc.xml
+    assert table.cell(3, 1).text == ""
+    assert_parts_preserved(source, output)
+    merged = tmp_path / "merged-rows.docx"
+    insert_docx_rows(source, merged, revision=rev(source), table=1, before=2, template_row=1, rows=[["合并", 3]])
+    assert Document(merged).tables[0].cell(1, 0).text == Document(merged).tables[0].cell(1, 1).text == "合并"
+
+
+@pytest.mark.parametrize("rows", [[["too", "short"]], [[{}, "unit", 1]], [["a", "b", 1, "extra"]], []])
+def test_invalid_template_rows_do_not_create_output(source, tmp_path, rows):
+    with pytest.raises((ValueError, TypeError)):
+        insert_docx_rows(source, tmp_path / "bad.docx", revision=rev(source), table=1, before=3, template_row=2, rows=rows)
+    assert not (tmp_path / "bad.docx").exists()
+
+
+def test_vertical_merge_clone_and_section_delete_are_rejected(tmp_path):
+    source = tmp_path / "sections.docx"
+    doc = Document()
+    table = doc.add_table(rows=2, cols=2)
+    table.cell(0, 0).merge(table.cell(1, 0)).text = "group"
+    doc.add_section()
+    doc.save(source)
+    with pytest.raises(ValueError, match="vertical merge"):
+        insert_docx_rows(source, tmp_path / "bad.docx", revision=rev(source), table=1, before=3, template_row=1, rows=[["a", "b"]])
+    with pytest.raises(ValueError, match="section properties"):
+        delete_docx_blocks(source, tmp_path / "bad.docx", revision=rev(source), first=2, last=2)
+    assert not (tmp_path / "bad.docx").exists()
+
+
+def test_repeated_text_and_unknown_batch_fields_fail_without_writing(source, tmp_path):
+    for operations in [
+        [{"op": "replace_text", "target": {"block": 2}, "search": "missing", "replace": "new"}],
+        [{"op": "delete_blocks", "from": 4, "to": 5, "ignore": True}],
+    ]:
+        with pytest.raises(ValueError):
+            edit_docx_structure(source, tmp_path / "bad.docx", revision=rev(source), operations=operations)
+        assert not (tmp_path / "bad.docx").exists()
+
+
+def test_simple_cell_set_uses_revision_and_preserves_style(source, tmp_path):
+    output = tmp_path / "cell.docx"
+    set_docx_cell(source, output, revision=rev(source), table=1, row=2, column=1, text="新值")
+    assert Document(output).tables[0].cell(1, 0).text == "新值"
+    assert Document(output).tables[0].cell(1, 0).paragraphs[0].runs[0].bold