EPUB Ebooks skill for Claude Code

#!/usr/bin/env python3
"""Fast structural pre-check for EPUB files (stdlib only). Not a replacement for epubcheck.

Usage:
  python3 epub_lint.py book.epub [more.epub ...]

Checks:
  - mimetype is the first ZIP entry, stored uncompressed, exactly "application/epub+zip"
  - META-INF/container.xml points to an existing package document (OPF)
  - OPF metadata: unique identifier, title, language, dcterms:modified (EPUB 3)
  - every manifest href exists; files in the ZIP missing from the manifest
  - spine itemrefs resolve; EPUB 3 nav document present; cover image declared
  - XHTML/SVG/NCX/OPF files are well-formed XML
  - local href/src references inside content documents resolve
  - accessibility metadata (schema:accessMode, accessibilityFeature, accessibilityHazard,
    accessibilitySummary) present (warning only)

Exit 0 when no errors (warnings allowed), 1 when any error is found or the file is unreadable.
"""
import posixpath
import re
import sys
import zipfile
from urllib.parse import unquote, urldefrag
from xml.etree import ElementTree as ET

NS = {
    "c": "urn:oasis:names:tc:opendocument:xmlns:container",
    "opf": "http://www.idpf.org/2007/opf",
    "dc": "http://purl.org/dc/elements/1.1/",
}
XML_TYPES = ("application/xhtml+xml", "image/svg+xml", "application/x-dtbncx+xml")
A11Y = ["schema:accessMode", "schema:accessibilityFeature", "schema:accessibilityHazard", "schema:accessibilitySummary"]
REF_RE = re.compile(r'\b(?:href|src)\s*=\s*"([^"]+)"', re.I)


def lint(path):
    errors, warnings = [], []
    try:
        zf = zipfile.ZipFile(path)
    except (OSError, zipfile.BadZipFile) as e:
        return [f"cannot open as ZIP: {e}"], []
    infos = zf.infolist()
    names = set(zf.namelist())

    # mimetype
    if not infos or infos[0].filename != "mimetype":
        errors.append("first ZIP entry must be 'mimetype'")
    else:
        mi = infos[0]
        if mi.compress_type != zipfile.ZIP_STORED:
            errors.append("mimetype must be stored uncompressed (zip -X0)")
        if zf.read(mi) != b"application/epub+zip":
            errors.append("mimetype content must be exactly 'application/epub+zip' with no newline")
        if mi.extra:
            warnings.append("mimetype entry has a ZIP extra field; use 'zip -X' to avoid it")

    # container
    if "META-INF/container.xml" not in names:
        errors.append("missing META-INF/container.xml")
        return errors, warnings
    try:
        container = ET.fromstring(zf.read("META-INF/container.xml"))
    except ET.ParseError as e:
        return errors + [f"container.xml not well-formed: {e}"], warnings
    rootfile = container.find(".//c:rootfile", NS)
    if rootfile is None or not rootfile.get("full-path"):
        return errors + ["container.xml has no rootfile full-path"], warnings
    opf_path = rootfile.get("full-path")
    if opf_path not in names:
        return errors + [f"package document not found: {opf_path}"], warnings
    opf_dir = posixpath.dirname(opf_path)

    try:
        opf = ET.fromstring(zf.read(opf_path))
    except ET.ParseError as e:
        return errors + [f"{opf_path} not well-formed: {e}"], warnings
    version = opf.get("version", "?")
    uid_ref = opf.get("unique-identifier")

    md = opf.find("opf:metadata", NS)
    if md is None:
        return errors + ["OPF has no <metadata>"], warnings
    ids = md.findall("dc:identifier", NS)
    if not ids:
        errors.append("metadata: missing dc:identifier")
    elif uid_ref and not any(i.get("id") == uid_ref for i in ids):
        errors.append(f"metadata: unique-identifier '{uid_ref}' does not match any dc:identifier id")
    if not (md.findtext("dc:title", default="", namespaces=NS) or "").strip():
        errors.append("metadata: missing dc:title")
    if not (md.findtext("dc:language", default="", namespaces=NS) or "").strip():
        errors.append("metadata: missing dc:language")
    metas = md.findall("opf:meta", NS)
    props = {m.get("property"): (m.text or "").strip() for m in metas if m.get("property")}
    if version.startswith("3"):
        mod = props.get("dcterms:modified", "")
        if not mod:
            errors.append("metadata: EPUB 3 requires meta property='dcterms:modified'")
        elif not re.fullmatch(r"\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}Z", mod):
            errors.append(f"metadata: dcterms:modified must be CCYY-MM-DDThh:mm:ssZ, got '{mod}'")
        missing = [a for a in A11Y if a not in props]
        if missing:
            warnings.append("accessibility metadata missing: " + ", ".join(missing))
    if not md.findall("dc:creator", NS):
        warnings.append("metadata: no dc:creator (author)")

    # manifest
    manifest = {}
    man = opf.find("opf:manifest", NS)
    if man is None:
        return errors + ["OPF has no <manifest>"], warnings
    for item in man.findall("opf:item", NS):
        iid, href, mt = item.get("id"), item.get("href"), item.get("media-type", "")
        if not iid or not href:
            errors.append("manifest item without id or href")
            continue
        full = posixpath.normpath(posixpath.join(opf_dir, unquote(href)))
        manifest[iid] = (full, mt, item.get("properties", ""))
        if full not in names and not href.startswith(("http://", "https://")):
            errors.append(f"manifest href not in ZIP: {href}")

    declared = {v[0] for v in manifest.values()}
    for n in sorted(names):
        if n.endswith("/") or n == "mimetype" or n.startswith("META-INF/") or n == opf_path:
            continue
        if n not in declared:
            warnings.append(f"file not declared in manifest: {n}")

    if version.startswith("3"):
        if not any("nav" in p.split() for _, _, p in manifest.values()):
            errors.append("EPUB 3 manifest needs an item with properties='nav'")
        if not any("cover-image" in p.split() for _, _, p in manifest.values()):
            warnings.append("no manifest item with properties='cover-image'")

    # spine
    spine = opf.find("opf:spine", NS)
    if spine is None or not spine.findall("opf:itemref", NS):
        errors.append("spine is missing or empty")
    else:
        for ref in spine.findall("opf:itemref", NS):
            idref = ref.get("idref")
            if idref not in manifest:
                errors.append(f"spine itemref '{idref}' not in manifest")

    # well-formedness and local references
    for full, mt, _ in manifest.values():
        if full not in names:
            continue
        if mt in XML_TYPES:
            data = zf.read(full)
            try:
                ET.fromstring(data)
            except ET.ParseError as e:
                errors.append(f"not well-formed XML: {full}: {e}")
                continue
            if mt == "application/xhtml+xml":
                base = posixpath.dirname(full)
                for ref in REF_RE.findall(data.decode("utf-8", "replace")):
                    target, _frag = urldefrag(ref)
                    if not target or re.match(r"^[a-z][a-z0-9+.-]*:", target, re.I):
                        continue
                    tp = posixpath.normpath(posixpath.join(base, unquote(target)))
                    if tp not in names:
                        errors.append(f"broken reference in {full}: {ref}")
    return errors, warnings


def main():
    if len(sys.argv) < 2:
        print(__doc__)
        return 1
    failed = False
    for path in sys.argv[1:]:
        errors, warnings = lint(path)
        print(f"== {path}: {len(errors)} error(s), {len(warnings)} warning(s)")
        for e in errors:
            print(f"  ERROR   {e}")
        for w in warnings:
            print(f"  WARNING {w}")
        failed |= bool(errors)
    print("\nRun epubcheck for full validation before publishing.")
    return 1 if failed else 0


if __name__ == "__main__":
    sys.exit(main())