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

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.3}/.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.3/DOCX.md

@@ -0,0 +1,73 @@
+# Word SDK / CLI 0.4.3
+
+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.
+
+Use `licos-dev --version` to query the installed document CLI version.
+
+| CLI command | SDK function | Input |
+| --- | --- | --- |
+| `docx-structure` | `read_docx_structure` | File, blocks/paragraphs/tables, 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 and original document |
+
+## 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 or removed targets and ambiguous matches 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.
+  Choose exactly one of `--before N` (`before=N`) or `--append` (`append=True`).
+  Explicit append uses the current revision's row count. Table structure items
+  include `table`, `row_count`, `column_count` and a usable body block target.
+- 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 does not certify content: `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.
+  One CLI assertion can use a target with `--text` or `--text-file` and optional
+  `--mode`; use `--input` for multiple assertions, never both input forms.
+- `verify_docx(..., original=...)` / `docx-verify --original` compares every ZIP
+  part payload except `word/document.xml`, plus ordered section settings in the
+  body. It reports changed/added/missing parts and `preservation_verified`; a
+  failed comparison also sets `verified=false` / exit 2. The original must be a
+  separate unmodified file. This does not certify all body run formatting or
+  rendered layout, and does not substitute for positional content assertions.
+
+## 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.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: licos-dev-sdk
-Version: 0.4.1
+Version: 0.4.3
 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.3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "licos-dev-sdk"
-version = "0.4.1"
+version = "0.4.3"
 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.3}/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.3}/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.3/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.3/src/licos_dev_sdk/document_docx_preservation.py

@@ -0,0 +1,27 @@
+"""Compare untouched DOCX parts and section settings against an original file."""
+
+from docx.oxml.ns import qn
+from lxml import etree
+
+from .document_docx_package import DOCUMENT_XML, DocxPackage
+
+
+def compare_docx_preservation(current: DocxPackage, original: DocxPackage) -> dict:
+    if current.path.samefile(original.path):
+        raise ValueError("original must be a separate, unmodified document")
+    before = {info.filename: data for info, data in original.parts if info.filename != DOCUMENT_XML}
+    after = {info.filename: data for info, data in current.parts if info.filename != DOCUMENT_XML}
+    missing = sorted(before.keys() - after.keys())
+    added = sorted(after.keys() - before.keys())
+    changed = sorted(name for name in before.keys() & after.keys() if before[name] != after[name])
+
+    def sections(package):
+        return [etree.tostring(node, method="c14n", exclusive=True)
+                for node in package.root.iter(qn("w:sectPr"))]
+
+    sections_unchanged = sections(current) == sections(original)
+    return {"original": str(original.path), "compared_parts": len(before),
+            "excluded_parts": [DOCUMENT_XML], "missing_parts": missing,
+            "added_parts": added, "changed_parts": changed,
+            "section_properties_unchanged": sections_unchanged,
+            "verified": not (missing or added or changed) and sections_unchanged}

licos_dev_sdk-0.4.3/src/licos_dev_sdk/document_docx_structure.py

@@ -0,0 +1,232 @@
+"""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_preservation import compare_docx_preservation
+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", "tables"}:
+        raise ValueError("scope must be blocks, paragraphs or tables")
+    package = DocxPackage(source)
+    structure = _Structure(package.root)
+    elements = {"blocks": structure.blocks, "paragraphs": structure.paragraphs, "tables": structure.tables}[scope]
+    items = []
+    for number, element in enumerate(elements[offset - 1:offset - 1 + limit], offset):
+        text = _text(element)
+        item = {"target": {"paragraph" if scope == "paragraphs" else "block":
+                           number if scope != "tables" else structure.blocks.index(element) + 1},
+                "type": etree.QName(element).localname,
+                "text": text[:max_chars], "content_truncated": len(text) > max_chars}
+        if element.tag == qn("w:tbl"):
+            model = parse_table(element, include_nested=False)
+            item.update(table=structure.tables.index(element) + 1, row_count=len(model.rows),
+                        column_count=model.column_count)
+        items.append(item)
+    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,
+                original: str | Path | 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})
+    preservation = compare_docx_preservation(package, DocxPackage(original)) if original is not None else None
+    return {"path": str(package.path), "revision": package.revision, "structure_verified": True,
+            "content_verified": bool(expectations) and not mismatches,
+            "preservation_verified": preservation is not None and preservation["verified"],
+            "preservation": preservation,
+            "verified": not mismatches and (preservation is None or preservation["verified"]),
+            "expectation_count": len(expectations), "mismatches": mismatches}

{licos_dev_sdk-0.4.1 → licos_dev_sdk-0.4.3}/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.3/src/licos_dev_sdk/document_docx_table_actions.py

@@ -0,0 +1,46 @@
+"""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
+from .document_docx_table import parse_table
+
+
+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, rows: list[list], template_row: int,
+                     before: int | None = None, append: bool = False,
+                     overwrite: bool = False) -> dict:
+    """Clone styled rows at an explicit position or append to the current table."""
+    if type(append) is not bool:
+        raise TypeError("append must be a boolean")
+    if (before is not None) == append:
+        raise ValueError("provide exactly one of before and append=True")
+    for name, value in (("table", table), ("template_row", template_row)):
+        _index(value, name)
+    if before is not None:
+        _index(before, "before")
+    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)
+    if append:
+        tables = _Structure(package.root).tables
+        if table > len(tables):
+            raise ValueError(f"table {table} does not exist")
+        before = len(parse_table(tables[table - 1], include_nested=False).rows) + 1
+    _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.3}/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.3/tests/test_docx_structure.py

@@ -0,0 +1,288 @@
+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
+
+
+def test_table_discovery_returns_body_target_and_current_dimensions(source, tmp_path):
+    doc = Document(source)
+    doc.add_table(rows=3, cols=2)
+    doc.save(source)
+    first = read_docx_structure(source, scope="tables", limit=1)
+    item = first["items"][0]
+    assert (item["target"], item["table"], item["row_count"], item["column_count"]) == ({"block": 3}, 1, 2, 3)
+    assert read_docx_structure(source)["items"][2] == item
+    second = read_docx_structure(source, scope="tables", offset=first["next_offset"], limit=1)
+    item = second["items"][0]
+    assert (item["target"], item["table"], item["row_count"], item["column_count"]) == ({"block": 6}, 2, 3, 2)
+    assert not second["has_more"]
+    assert read_docx_target(source, item["target"])["text"] == item["text"]
+
+
+def test_explicit_append_uses_current_revision_and_preserves_merged_template(source, tmp_path):
+    first, second = tmp_path / "first.docx", tmp_path / "second.docx"
+    insert_docx_rows(source, first, revision=rev(source), table=1, append=True, template_row=2, rows=[["泵", "台", 2]])
+    insert_docx_rows(first, second, revision=rev(first), table=1, append=True, template_row=1, rows=[["合并尾行", 9]])
+    table = Document(second).tables[0]
+    assert len(table.rows) == 4
+    assert table.cell(2, 0).text == "泵" and table.cell(2, 0).paragraphs[0].runs[0].bold
+    assert table.cell(3, 0).text == table.cell(3, 1).text == "合并尾行"
+    assert_parts_preserved(source, second)
+    with pytest.raises(ValueError, match="revision"):
+        insert_docx_rows(first, tmp_path / "stale.docx", revision=rev(source), table=1, append=True, template_row=2, rows=[["a", "b", 1]])
+    assert not (tmp_path / "stale.docx").exists()
+
+
+@pytest.mark.parametrize("position", [{}, {"before": 3, "append": True}, {"before": True}, {"append": 1}])
+def test_insert_requires_one_explicit_position(source, tmp_path, position):
+    output = tmp_path / "bad.docx"
+    with pytest.raises((ValueError, TypeError)):
+        insert_docx_rows(source, output, revision=rev(source), table=1, template_row=2, rows=[["a", "b", 1]], **position)
+    assert not output.exists()
+
+
+def test_original_comparison_certifies_parts_and_sections_but_requires_content_assertions(source, tmp_path):
+    output = tmp_path / "edited.docx"
+    replace_docx_text(source, output, revision=rev(source), target={"block": 2}, search="123456", replacement="新账号")
+    report = verify_docx(output, original=source)
+    assert report["verified"] and report["preservation_verified"]
+    assert report["preservation"]["section_properties_unchanged"]
+    assert not report["content_verified"]
+    assert not verify_docx(output, original=source, expectations=[{"target": {"block": 2}, "text": "错误"}])["verified"]
+    with pytest.raises(ValueError, match="separate"):
+        verify_docx(output, original=output)
+
+
+@pytest.mark.parametrize("mutation,part,field", [
+    ("change", "word/header1.xml", "changed_parts"),
+    ("change", "word/styles.xml", "changed_parts"),
+    ("remove", "word/header1.xml", "missing_parts"),
+    ("add", "word/media/extra.png", "added_parts"),
+])
+def test_original_comparison_detects_changes_outside_body(source, tmp_path, mutation, part, field):
+    output = tmp_path / "changed.docx"
+    with ZipFile(source) as before, ZipFile(output, "w") as after:
+        for info in before.infolist():
+            if mutation == "remove" and info.filename == part:
+                continue
+            data = before.read(info.filename)
+            after.writestr(info, data + b" " if mutation == "change" and info.filename == part else data)
+        if mutation == "add":
+            after.writestr(part, b"image")
+    report = verify_docx(output, original=source)
+    assert not report["verified"] and not report["preservation_verified"]
+    assert report["preservation"][field] == [part]
+
+
+def test_original_comparison_detects_section_layout_changes(source, tmp_path):
+    from licos_dev_sdk.document_docx_package import DocxPackage
+
+    package = DocxPackage(source)
+    section = next(package.root.iter(qn("w:sectPr")))
+    section.find(qn("w:pgMar")).set(qn("w:left"), "999")
+    output = tmp_path / "layout.docx"
+    package.save(output)
+    report = verify_docx(output, original=source)
+    assert not report["verified"]
+    assert not report["preservation"]["section_properties_unchanged"]
+    assert report["preservation"]["changed_parts"] == []

licos_dev_sdk-0.4.3/tests/test_html_docx_features.py

@@ -0,0 +1,46 @@
+"""Exercise the public HTML-to-Word API with actual document parts and images."""
+
+import base64
+from zipfile import ZipFile
+
+from docx import Document
+from docx.oxml.ns import qn
+from PIL import Image
+
+from licos_dev_sdk import create_docx
+
+
+def test_html_generates_native_toc_merged_table_and_embedded_images(tmp_path):
+    picture = tmp_path / "figure.png"
+    Image.new("RGB", (80, 40), "#145DA0").save(picture)
+    encoded = base64.b64encode(picture.read_bytes()).decode("ascii")
+    html = f'''<html><head><style>
+      th {{ background-color: #145DA0; color: #ffffff; }}
+      td {{ border: 1px solid #333333; }}
+    </style></head><body>
+      <h1>测试报告</h1><h2>设备统计</h2><h3>设备清单</h3>
+      <table><tr><th colspan="2">设备</th><th>数量</th></tr>
+        <tr><td rowspan="2">泵组</td><td>离心泵</td><td>2</td></tr>
+        <tr><td>阀门</td><td>3</td></tr></table>
+      <p><img src="figure.png" width="160" alt="本地图片"></p>
+      <p><img src="data:image/png;base64,{encoded}" width="160" alt="内嵌图片"></p>
+    </body></html>'''
+    output = create_docx(html, "report", content_type="html", output_dir=str(tmp_path),
+                         asset_base_path=str(tmp_path), include_toc=True, header="内部资料", footer="测试页脚")
+    document = Document(output)
+    assert [p.text for p in document.paragraphs if p.style.name.startswith("Heading")] == ["测试报告", "设备统计", "设备清单"]
+    fields = [n.text for n in document.element.iter(qn("w:instrText"))]
+    assert any('TOC \\o "1-3"' in text for text in fields)
+    assert document.settings.element.find(qn("w:updateFields")).get(qn("w:val")) == "true"
+    table = document.tables[0]
+    assert len(table.rows) == 3 and len(table.columns) == 3
+    assert table.cell(0, 0)._tc is table.cell(0, 1)._tc
+    assert table.cell(1, 0)._tc is table.cell(2, 0)._tc
+    assert table.cell(2, 1).text == "阀门" and table.cell(2, 2).text == "3"
+    assert 'w:fill="145DA0"' in table.cell(0, 0)._tc.xml
+    assert len(document.inline_shapes) == 2
+    assert "内部资料" in document.sections[0].header.paragraphs[0].text
+    assert "测试页脚" in document.sections[0].footer.paragraphs[0].text
+    with ZipFile(output) as archive:
+        images = [archive.read(name) for name in archive.namelist() if name.startswith("word/media/")]
+    assert picture.read_bytes() in images