devlyn-cli 0.5.2 → 0.5.4

package/optional-skills/dokkit/scripts/validate_docx.py

@@ -0,0 +1,142 @@
+#!/usr/bin/env python3
+"""Validate a modified DOCX working directory for XML well-formedness.
+
+Usage:
+    python validate_docx.py <work_dir>
+
+Checks:
+- All XML files are well-formed
+- Required files exist ([Content_Types].xml, word/document.xml)
+- No broken element nesting
+"""
+
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+
+REQUIRED_FILES = [
+    "[Content_Types].xml",
+    "word/document.xml",
+]
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".gif", ".webp"}
+
+
+def validate_xml_file(path: Path) -> list[str]:
+    """Check if an XML file is well-formed."""
+    errors = []
+    try:
+        ET.parse(path)
+    except ET.ParseError as e:
+        errors.append(f"{path}: XML parse error: {e}")
+    return errors
+
+
+def validate_image_relationships(work_dir: Path) -> list[str]:
+    """Verify that image media files, relationships, and Content_Types are consistent."""
+    errors = []
+
+    # 1. Collect actual image files in word/media/
+    media_dir = work_dir / "word" / "media"
+    media_images = set()
+    if media_dir.is_dir():
+        for f in media_dir.iterdir():
+            if f.suffix.lower() in IMAGE_EXTENSIONS:
+                media_images.add(f.name)
+
+    if not media_images:
+        return errors  # No images, nothing to validate
+
+    # 2. Parse relationships to find image references
+    rels_path = work_dir / "word" / "_rels" / "document.xml.rels"
+    rel_targets = set()
+    if rels_path.exists():
+        try:
+            tree = ET.parse(rels_path)
+            root = tree.getroot()
+            ns = {"r": "http://schemas.openxmlformats.org/package/2006/relationships"}
+            image_type = "http://schemas.openxmlformats.org/officeDocument/2006/relationships/image"
+            for rel in root.iter("{%s}Relationship" % ns["r"]):
+                if rel.get("Type") == image_type:
+                    target = rel.get("Target", "")
+                    # Target is like "media/image1.png"
+                    if target.startswith("media/"):
+                        rel_targets.add(target[len("media/"):])
+        except ET.ParseError:
+            pass  # XML error already caught by validate_xml_file
+
+    # 3. Check media files have corresponding relationships
+    for img in media_images:
+        if img not in rel_targets:
+            errors.append(f"Image file word/media/{img} has no relationship entry in document.xml.rels")
+
+    # 4. Check relationships point to existing files
+    for target in rel_targets:
+        if target not in media_images:
+            errors.append(f"Relationship references media/{target} but file does not exist in word/media/")
+
+    # 5. Check Content_Types has entries for image extensions used
+    ct_path = work_dir / "[Content_Types].xml"
+    if ct_path.exists():
+        try:
+            ct_tree = ET.parse(ct_path)
+            ct_root = ct_tree.getroot()
+            ct_ns = "http://schemas.openxmlformats.org/package/2006/content-types"
+            registered_exts = set()
+            for default in ct_root.iter(f"{{{ct_ns}}}Default"):
+                registered_exts.add(default.get("Extension", "").lower())
+
+            for img in media_images:
+                ext = img.rsplit(".", 1)[-1].lower() if "." in img else ""
+                if ext and ext not in registered_exts:
+                    # JPEG can be registered as either "jpeg" or "jpg"
+                    if ext in ("jpg", "jpeg") and ("jpg" in registered_exts or "jpeg" in registered_exts):
+                        continue
+                    errors.append(f"Image extension '.{ext}' (from {img}) not registered in [Content_Types].xml")
+        except ET.ParseError:
+            pass
+
+    return errors
+
+
+def main():
+    if len(sys.argv) != 2:
+        print("Usage: python validate_docx.py <work_dir>", file=sys.stderr)
+        sys.exit(1)
+
+    work_dir = Path(sys.argv[1])
+    if not work_dir.is_dir():
+        print(f"Error: Not a directory: {work_dir}", file=sys.stderr)
+        sys.exit(2)
+
+    errors = []
+
+    # Check required files
+    for req in REQUIRED_FILES:
+        if not (work_dir / req).exists():
+            errors.append(f"Missing required file: {req}")
+
+    # Validate all XML files
+    for xml_file in work_dir.rglob("*.xml"):
+        errors.extend(validate_xml_file(xml_file))
+
+    # Also check .rels files
+    for rels_file in work_dir.rglob("*.rels"):
+        errors.extend(validate_xml_file(rels_file))
+
+    # Validate image relationships
+    errors.extend(validate_image_relationships(work_dir))
+
+    if errors:
+        print(f"Validation FAILED — {len(errors)} error(s):", file=sys.stderr)
+        for err in errors:
+            print(f"  - {err}", file=sys.stderr)
+        sys.exit(1)
+    else:
+        print("DOCX validation passed.", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/optional-skills/dokkit/scripts/validate_hwpx.py

@@ -0,0 +1,281 @@
+#!/usr/bin/env python3
+"""Validate a modified HWPX working directory for XML well-formedness.
+
+Usage:
+    python validate_hwpx.py <work_dir>
+
+Checks:
+- All XML files are well-formed
+- mimetype file exists
+- Section files exist in Contents/
+"""
+
+import sys
+import xml.etree.ElementTree as ET
+from pathlib import Path
+
+
+IMAGE_EXTENSIONS = {".png", ".jpg", ".jpeg", ".bmp", ".tiff", ".gif", ".webp"}
+
+HP = "http://www.hancom.co.kr/hwpml/2011/paragraph"
+HC = "http://www.hancom.co.kr/hwpml/2011/core"
+HH = "http://www.hancom.co.kr/hwpml/2011/head"
+OPF = "http://www.idpf.org/2007/opf"
+
+# Required child element local names inside <hp:pic>
+REQUIRED_PIC_CHILDREN = {
+    "offset", "orgSz", "curSz", "flip", "rotationInfo", "renderingInfo",
+    "inMargin", "sz", "pos", "outMargin", "lineShape", "imgRect", "imgClip",
+    "imgDim",
+}
+
+# Elements that should NOT appear inside <hp:pic>
+SPURIOUS_PIC_ELEMENTS = {"picSz", "picOutline", "picRect", "caption", "shapeComment"}
+
+
+def validate_xml_file(path: Path) -> list[str]:
+    """Check if an XML file is well-formed."""
+    errors = []
+    try:
+        ET.parse(path)
+    except ET.ParseError as e:
+        errors.append(f"{path}: XML parse error: {e}")
+    return errors
+
+
+def _check_single_pic(pic: ET.Element, prefix: str, manifest_ids: set[str]) -> tuple[list[str], list[str]]:
+    """Validate a single <hp:pic> element against the 8 structural rules.
+
+    Returns (errors, warnings) lists.
+    """
+    errors = []
+    warnings = []
+
+    # Rule 1: <img> must use hc: namespace
+    hc_imgs = list(pic.iter(f"{{{HC}}}img"))
+    hp_imgs = list(pic.iter(f"{{{HP}}}img"))
+    if hp_imgs:
+        errors.append(f"{prefix}: <img> uses hp: namespace (must be hc:)")
+    if not hc_imgs and not hp_imgs:
+        errors.append(f"{prefix}: missing <img> element entirely")
+
+    # Rule 2: <imgRect> must have <hc:pt0..3> children
+    for imgRect in pic.iter(f"{{{HP}}}imgRect"):
+        pt_count = sum(1 for i in range(4) for _ in imgRect.iter(f"{{{HC}}}pt{i}"))
+        if pt_count < 4:
+            if imgRect.get("x1") is not None or imgRect.get("x2") is not None:
+                errors.append(
+                    f"{prefix}: <imgRect> uses inline attributes "
+                    f"(must have <hc:pt0..3> children)"
+                )
+            else:
+                errors.append(
+                    f"{prefix}: <imgRect> has {pt_count}/4 "
+                    f"required <hc:pt> children"
+                )
+
+    # Rule 3: Required child elements
+    child_local_names = set()
+    for child in pic:
+        tag = child.tag
+        local = tag.split("}")[1] if "}" in tag else tag
+        child_local_names.add(local)
+
+    missing = REQUIRED_PIC_CHILDREN - child_local_names
+    if missing:
+        errors.append(f"{prefix}: missing required children: {', '.join(sorted(missing))}")
+
+    # Rule 4: No spurious elements
+    spurious_found = SPURIOUS_PIC_ELEMENTS & child_local_names
+    if spurious_found:
+        warnings.append(f"{prefix}: spurious elements found: {', '.join(sorted(spurious_found))}")
+
+    # Rule 5: imgClip right/bottom should not be all zeros
+    for imgClip in pic.iter(f"{{{HP}}}imgClip"):
+        if imgClip.get("right", "0") == "0" and imgClip.get("bottom", "0") == "0":
+            warnings.append(f"{prefix}: <imgClip> right/bottom are both 0 (should be pixel dimensions)")
+
+    # Rule 6: lineShape attributes
+    for ls in pic.iter(f"{{{HP}}}lineShape"):
+        if ls.get("color", "") == "#000000":
+            warnings.append(f"{prefix}: <lineShape> color=\"#000000\" (should be \"none\")")
+        if ls.get("width", "") == "0":
+            warnings.append(f"{prefix}: <lineShape> width=\"0\" (should be \"283\")")
+
+    # Rule 7: Check manifest registration
+    for img in hc_imgs:
+        ref_id = img.get("binaryItemIDRef", "")
+        if ref_id and manifest_ids and ref_id not in manifest_ids:
+            errors.append(f"{prefix}: binaryItemIDRef=\"{ref_id}\" not found in content.hpf manifest")
+
+    # Rule 8: hp:pos attributes
+    for pos in pic.iter(f"{{{HP}}}pos"):
+        if pos.get("flowWithText", "") == "1":
+            warnings.append(f"{prefix}: <pos> flowWithText=\"1\" (should be \"0\")")
+        if pos.get("horzRelTo", "") == "PARA":
+            warnings.append(f"{prefix}: <pos> horzRelTo=\"PARA\" (should be \"COLUMN\")")
+
+    return errors, warnings
+
+
+def validate_pic_elements(work_dir: Path) -> list[str]:
+    """Validate <hp:pic> elements in section XML for correct structure."""
+    errors = []
+    warnings = []
+
+    contents_dir = work_dir / "Contents"
+    if not contents_dir.is_dir():
+        return errors
+
+    # Collect manifest IDs from content.hpf
+    manifest_ids = set()
+    content_hpf = contents_dir / "content.hpf"
+    if content_hpf.exists():
+        try:
+            tree = ET.parse(content_hpf)
+            for item in tree.getroot().iter(f"{{{OPF}}}item"):
+                if "BinData/" in item.get("href", ""):
+                    manifest_ids.add(item.get("id", ""))
+        except ET.ParseError as e:
+            errors.append(f"content.hpf: XML parse error (skipping manifest check): {e}")
+
+    for section_file in sorted(contents_dir.glob("section*.xml")):
+        try:
+            tree = ET.parse(section_file)
+            root = tree.getroot()
+        except ET.ParseError as e:
+            errors.append(f"{section_file.name}: XML parse error (skipping pic validation): {e}")
+            continue
+
+        for pic in root.iter(f"{{{HP}}}pic"):
+            prefix = f"{section_file.name} pic id={pic.get('id', '?')}"
+            pic_errors, pic_warnings = _check_single_pic(pic, prefix, manifest_ids)
+            errors.extend(pic_errors)
+            warnings.extend(pic_warnings)
+
+    # Check header.xml for spurious binDataItems referencing images
+    for header_path in work_dir.rglob("header.xml"):
+        try:
+            tree = ET.parse(header_path)
+            for _ in tree.getroot().iter(f"{{{HH}}}binDataItem"):
+                warnings.append(
+                    f"{header_path.name}: found <hh:binDataItem> "
+                    f"(images should be registered in content.hpf only)"
+                )
+        except ET.ParseError as e:
+            errors.append(f"{header_path.name}: XML parse error (skipping binDataItem check): {e}")
+
+    # Warnings are non-fatal but reported
+    for w in warnings:
+        errors.append(f"WARNING: {w}")
+
+    return errors
+
+
+def validate_image_references(work_dir: Path) -> list[str]:
+    """Verify that BinData image files are referenced in section XML files."""
+    errors = []
+
+    # 1. Collect actual image files in BinData/
+    bindata_dir = work_dir / "BinData"
+    bindata_images = set()
+    if bindata_dir.is_dir():
+        for f in bindata_dir.iterdir():
+            if f.suffix.lower() in IMAGE_EXTENSIONS:
+                bindata_images.add(f"BinData/{f.name}")
+
+    if not bindata_images:
+        return errors  # No images, nothing to validate
+
+    # 2. Scan section XML files for BinData references
+    contents_dir = work_dir / "Contents"
+    referenced_images = set()
+    if contents_dir.is_dir():
+        for section_file in contents_dir.glob("section*.xml"):
+            try:
+                tree = ET.parse(section_file)
+                root = tree.getroot()
+                # Search for binDataEmbedding elements referencing BinData/
+                for elem in root.iter():
+                    for attr_val in elem.attrib.values():
+                        if isinstance(attr_val, str) and attr_val.startswith("BinData/"):
+                            referenced_images.add(attr_val)
+            except ET.ParseError:
+                pass  # Already caught by validate_xml_file
+
+    # Also check header XML files
+    for xml_file in work_dir.rglob("*.xml"):
+        if xml_file.name.startswith("section"):
+            continue  # Already checked above
+        try:
+            tree = ET.parse(xml_file)
+            root = tree.getroot()
+            for elem in root.iter():
+                for attr_val in elem.attrib.values():
+                    if isinstance(attr_val, str) and attr_val.startswith("BinData/"):
+                        referenced_images.add(attr_val)
+        except ET.ParseError:
+            pass
+
+    # 3. Check BinData files have corresponding references
+    for img in bindata_images:
+        if img not in referenced_images:
+            errors.append(f"Image file {img} has no reference in section or header XML")
+
+    # 4. Check references point to existing files
+    for ref in referenced_images:
+        ref_path = work_dir / ref
+        if not ref_path.exists():
+            errors.append(f"XML references {ref} but file does not exist")
+
+    return errors
+
+
+def main():
+    if len(sys.argv) != 2:
+        print("Usage: python validate_hwpx.py <work_dir>", file=sys.stderr)
+        sys.exit(1)
+
+    work_dir = Path(sys.argv[1])
+    if not work_dir.is_dir():
+        print(f"Error: Not a directory: {work_dir}", file=sys.stderr)
+        sys.exit(2)
+
+    errors = []
+
+    # Check mimetype
+    mimetype_path = work_dir / "mimetype"
+    if not mimetype_path.exists():
+        errors.append("Missing required file: mimetype")
+
+    # Check for section files
+    contents_dir = work_dir / "Contents"
+    if not contents_dir.is_dir():
+        errors.append("Missing Contents/ directory")
+    else:
+        section_files = list(contents_dir.glob("section*.xml"))
+        if not section_files:
+            errors.append("No section*.xml files found in Contents/")
+
+    # Validate all XML files
+    for xml_file in work_dir.rglob("*.xml"):
+        errors.extend(validate_xml_file(xml_file))
+
+    # Validate image references
+    errors.extend(validate_image_references(work_dir))
+
+    # Validate <hp:pic> element structure
+    errors.extend(validate_pic_elements(work_dir))
+
+    if errors:
+        print(f"Validation FAILED — {len(errors)} error(s):", file=sys.stderr)
+        for err in errors:
+            print(f"  - {err}", file=sys.stderr)
+        sys.exit(1)
+    else:
+        print("HWPX validation passed.", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/optional-skills/dokkit/scripts/validate_state.py

@@ -0,0 +1,132 @@
+#!/usr/bin/env python3
+"""Validate .dokkit/state.json against the Dokkit state schema.
+
+Usage:
+    python validate_state.py <path-to-state.json>
+
+Exit codes:
+    0 — valid
+    1 — validation errors found
+    2 — file not found or invalid JSON
+"""
+
+import json
+import sys
+from pathlib import Path
+
+
+VALID_SOURCE_STATUSES = {"processing", "ready", "error"}
+VALID_DOC_STATUSES = {"filling", "review", "modified", "finalized"}
+VALID_FILE_TYPES = {
+    "pdf", "docx", "xlsx", "csv", "pptx", "hwp", "hwpx",
+    "png", "jpg", "jpeg", "txt", "md", "json", "html"
+}
+VALID_TEMPLATE_TYPES = {"docx", "hwpx"}
+VALID_EXPORT_FORMATS = {"docx", "hwpx", "pdf"}
+
+
+def validate(state: dict) -> list[str]:
+    """Validate state dict, return list of error messages."""
+    errors = []
+
+    # Root fields
+    if not isinstance(state.get("version"), str):
+        errors.append("Missing or invalid 'version' (expected string)")
+    if not isinstance(state.get("created"), str):
+        errors.append("Missing or invalid 'created' (expected ISO timestamp string)")
+    if not isinstance(state.get("sources"), list):
+        errors.append("Missing or invalid 'sources' (expected array)")
+    if "template" not in state:
+        errors.append("Missing 'template' field (expected object or null)")
+    if "analysis" not in state:
+        errors.append("Missing 'analysis' field (expected object or null)")
+    if "filled_document" not in state:
+        errors.append("Missing 'filled_document' field (expected object or null)")
+    if not isinstance(state.get("exports"), list):
+        errors.append("Missing or invalid 'exports' (expected array)")
+
+    # Validate sources
+    for i, src in enumerate(state.get("sources", [])):
+        prefix = f"sources[{i}]"
+        for field in ("id", "file_path", "file_type", "display_name",
+                       "content_path", "metadata_path", "summary", "status"):
+            if not isinstance(src.get(field), str):
+                errors.append(f"{prefix}: missing or invalid '{field}'")
+        if src.get("status") and src["status"] not in VALID_SOURCE_STATUSES:
+            errors.append(f"{prefix}: invalid status '{src['status']}' "
+                          f"(expected one of {VALID_SOURCE_STATUSES})")
+        if src.get("file_type") and src["file_type"] not in VALID_FILE_TYPES:
+            errors.append(f"{prefix}: unknown file_type '{src['file_type']}'")
+
+    # Validate template
+    tmpl = state.get("template")
+    if tmpl is not None:
+        for field in ("file_path", "file_type", "display_name", "work_dir"):
+            if not isinstance(tmpl.get(field), str):
+                errors.append(f"template: missing or invalid '{field}'")
+        if tmpl.get("file_type") and tmpl["file_type"] not in VALID_TEMPLATE_TYPES:
+            errors.append(f"template: invalid file_type '{tmpl['file_type']}' "
+                          f"(expected one of {VALID_TEMPLATE_TYPES})")
+
+    # Validate analysis
+    analysis = state.get("analysis")
+    if analysis is not None:
+        if not isinstance(analysis.get("path"), str):
+            errors.append("analysis: missing or invalid 'path'")
+        for field in ("total_fields", "mapped", "unmapped"):
+            if not isinstance(analysis.get(field), int):
+                errors.append(f"analysis: missing or invalid '{field}' (expected integer)")
+
+    # Validate filled_document
+    doc = state.get("filled_document")
+    if doc is not None:
+        if not isinstance(doc.get("status"), str):
+            errors.append("filled_document: missing or invalid 'status'")
+        elif doc["status"] not in VALID_DOC_STATUSES:
+            errors.append(f"filled_document: invalid status '{doc['status']}' "
+                          f"(expected one of {VALID_DOC_STATUSES})")
+
+    # Validate exports
+    for i, exp in enumerate(state.get("exports", [])):
+        prefix = f"exports[{i}]"
+        for field in ("format", "output_path"):
+            if not isinstance(exp.get(field), str):
+                errors.append(f"{prefix}: missing or invalid '{field}'")
+        if exp.get("format") and exp["format"] not in VALID_EXPORT_FORMATS:
+            errors.append(f"{prefix}: invalid format '{exp['format']}' "
+                          f"(expected one of {VALID_EXPORT_FORMATS})")
+
+    return errors
+
+
+def main():
+    if len(sys.argv) != 2:
+        print("Usage: python validate_state.py <path-to-state.json>", file=sys.stderr)
+        sys.exit(2)
+
+    path = Path(sys.argv[1])
+    if not path.exists():
+        print(f"Error: File not found: {path}", file=sys.stderr)
+        sys.exit(2)
+
+    try:
+        with open(path, encoding="utf-8") as f:
+            state = json.load(f)
+    except json.JSONDecodeError as e:
+        print(f"Error: Invalid JSON: {e}", file=sys.stderr)
+        sys.exit(2)
+
+    errors = validate(state)
+
+    if errors:
+        print(f"Validation FAILED — {len(errors)} error(s):", file=sys.stderr)
+        for err in errors:
+            print(f"  - {err}", file=sys.stderr)
+        sys.exit(1)
+    else:
+        print("Validation passed.", file=sys.stderr)
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "devlyn-cli",
-  "version": "0.5.2",
+  "version": "0.5.4",
   "description": "Claude Code configuration toolkit for teams",
   "bin": {
     "devlyn": "bin/devlyn.js"