openappx 0.6.0__py3-none-any.whl

openappx/__init__.py

@@ -0,0 +1,3 @@
+"""openappx — Linux-first Appx/MSIX packing toolkit."""
+
+__version__ = "0.6.0"

openappx/__main__.py

@@ -0,0 +1,3 @@
+from openappx.cli import main
+
+raise SystemExit(main())

openappx/blockmap.py

@@ -0,0 +1,240 @@
+"""AppxBlockMap generation (64 KiB SHA-256 blocks)."""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import os
+import struct
+import zlib
+from collections.abc import Sequence
+from dataclasses import dataclass
+from pathlib import Path
+
+BLOCK_SIZE = 64 * 1024
+HASH_METHOD = "http://www.w3.org/2001/04/xmlenc#sha256"
+NS = "http://schemas.microsoft.com/appx/2010/blockmap"
+
+# Files generated by the packer; never read from the layout as payload.
+SKIP_NAMES = frozenset(
+    {
+        "[Content_Types].xml",
+        "AppxBlockMap.xml",
+        "AppxSignature.p7x",
+        "AppxMetadata\\CodeIntegrity.cat",
+    }
+)
+
+
+@dataclass(frozen=True)
+class FileBlocks:
+    """One <File> entry: hashes over uncompressed blocks, sizes over compressed ones.
+
+    `compressed_sizes` is None for stored parts, where the format omits
+    Block/@Size entirely.
+    """
+
+    name: str
+    size: int
+    block_hashes: Sequence[bytes]
+    compressed_sizes: Sequence[int] | None = None
+
+
+def package_path(rel: Path) -> str:
+    return rel.as_posix().lstrip("/").replace("/", "\\")
+
+
+def hash_file_blocks(data: bytes) -> tuple[list[bytes], list[int]]:
+    """SHA-256 over each uncompressed 64 KiB block.
+
+    An empty file has no blocks at all — `<File Name="…" Size="0" LfhSize="…"/>`
+    with no children, as produced by Microsoft's own packer.
+    """
+    hashes: list[bytes] = []
+    sizes: list[int] = []
+    offset = 0
+    while offset < len(data):
+        chunk = data[offset : offset + BLOCK_SIZE]
+        hashes.append(hashlib.sha256(chunk).digest())
+        sizes.append(len(chunk))
+        offset += BLOCK_SIZE
+    return hashes, sizes
+
+
+def deflate_blocks(data: bytes, level: int = 6) -> tuple[bytes, list[int]]:
+    """Deflate `data` one 64 KiB block at a time.
+
+    Returns the raw deflate stream and the compressed length of each block.
+    Z_FULL_FLUSH terminates every block so its compressed extent is known — that
+    length is what Block/@Size reports. The final `flush()` emits a 2-byte
+    end-of-stream marker belonging to no block, which is why the block sizes sum
+    to slightly less than the entry's compressed size.
+    """
+    compressor = zlib.compressobj(level, zlib.DEFLATED, -zlib.MAX_WBITS)
+    stream = bytearray()
+    sizes: list[int] = []
+    for offset in range(0, len(data), BLOCK_SIZE):
+        block = compressor.compress(data[offset : offset + BLOCK_SIZE])
+        block += compressor.flush(zlib.Z_FULL_FLUSH)
+        stream += block
+        sizes.append(len(block))
+    stream += compressor.flush()
+    return bytes(stream), sizes
+
+
+def zip_local_header_size(name_utf8: bytes, extra: bytes = b"") -> int:
+    return 30 + len(name_utf8) + len(extra)
+
+
+LFH_SIGNATURE = 0x04034B50
+LFH_STRUCT = "<IHHHHHIIIHH"
+
+
+@dataclass(frozen=True)
+class LocalHeader:
+    """A ZIP local file header as actually written to the archive."""
+
+    name: bytes
+    flag_bits: int
+    size: int  # 30 + name length + extra length, i.e. the blockmap's LfhSize
+    extra_len: int
+
+
+def read_local_header(archive: bytes, offset: int) -> LocalHeader:
+    """Parse the local file header at `offset` in a raw ZIP archive.
+
+    Used to check declared LfhSize against reality: `zip_local_header_size`
+    assumes no extra fields, and nothing in `zipfile` guarantees that.
+    """
+    fields = struct.unpack(LFH_STRUCT, archive[offset : offset + 30])
+    sig, _ver, flag, _comp, _time, _date, _crc, _csize, _size, name_len, extra_len = (
+        fields
+    )
+    if sig != LFH_SIGNATURE:
+        raise ValueError(f"no local file header at offset {offset}")
+    return LocalHeader(
+        name=archive[offset + 30 : offset + 30 + name_len],
+        flag_bits=flag,
+        size=30 + name_len + extra_len,
+        extra_len=extra_len,
+    )
+
+
+def collect_files(root: Path) -> list[Path]:
+    files: list[Path] = []
+    for dirpath, _, filenames in os.walk(root):
+        for fn in filenames:
+            p = Path(dirpath) / fn
+            name = package_path(p.relative_to(root))
+            if name in SKIP_NAMES:
+                continue
+            files.append(p)
+    files.sort(key=lambda p: package_path(p.relative_to(root)).lower())
+    return files
+
+
+@dataclass(frozen=True)
+class PreparedFile:
+    """A payload file ready to be written: blockmap entry plus archive bytes."""
+
+    blocks: FileBlocks
+    payload: bytes  # what goes into the archive (deflated or verbatim)
+    deflated: bool
+
+
+def prepare_file(name: str, data: bytes, level: int = 6) -> PreparedFile:
+    """Hash and compress one payload file.
+
+    Deflate is used only when it actually pays off; otherwise the part is stored
+    and Block/@Size is omitted, matching what Microsoft's packer does for
+    already-compressed assets.
+    """
+    hashes, _ = hash_file_blocks(data)
+    stream, compressed_sizes = deflate_blocks(data, level)
+
+    if data and len(stream) < len(data):
+        return PreparedFile(
+            blocks=FileBlocks(name, len(data), hashes, compressed_sizes),
+            payload=stream,
+            deflated=True,
+        )
+    return PreparedFile(
+        blocks=FileBlocks(name, len(data), hashes, None),
+        payload=data,
+        deflated=False,
+    )
+
+
+def _xml_escape(s: str) -> str:
+    return (
+        s.replace("&", "&amp;")
+        .replace("<", "&lt;")
+        .replace(">", "&gt;")
+        .replace('"', "&quot;")
+    )
+
+
+def render_blockmap_xml(entries: Sequence[FileBlocks], lfh_sizes: dict) -> bytes:
+    lines = [
+        '<?xml version="1.0" encoding="UTF-8" standalone="no"?>',
+        f'<BlockMap xmlns="{NS}" HashMethod="{HASH_METHOD}">',
+    ]
+    for e in entries:
+        lfh = lfh_sizes[e.name]
+        head = f'  <File Name="{_xml_escape(e.name)}" Size="{e.size}" LfhSize="{lfh}"'
+        if not e.block_hashes:  # empty file: no blocks at all
+            lines.append(head + "/>")
+            continue
+
+        lines.append(head + ">")
+        for i, h in enumerate(e.block_hashes):
+            b64 = base64.b64encode(h).decode("ascii")
+            if e.compressed_sizes is None:  # stored part: no compressed length
+                lines.append(f'    <Block Hash="{b64}"/>')
+            else:
+                lines.append(
+                    f'    <Block Hash="{b64}" Size="{e.compressed_sizes[i]}"/>'
+                )
+        lines.append("  </File>")
+    lines.append("</BlockMap>")
+    return ("\r\n".join(lines) + "\r\n").encode("utf-8")
+
+
+def content_types_xml(package_paths: Sequence[str]) -> bytes:
+    defaults = {
+        "xml": "application/vnd.ms-appx.manifest+xml",
+        "png": "image/png",
+        "jpg": "image/jpeg",
+        "jpeg": "image/jpeg",
+        "json": "application/json",
+        "txt": "text/plain",
+        "dll": "application/x-msdownload",
+        "exe": "application/x-msdownload",
+        "winmd": "application/octet-stream",
+        "p7x": "application/vnd.ms-appx.signature",
+    }
+    for p in package_paths:
+        ext = Path(p.replace("\\", "/")).suffix.lstrip(".").lower()
+        if ext and ext not in defaults:
+            defaults[ext] = "application/octet-stream"
+
+    lines = [
+        '<?xml version="1.0" encoding="utf-8"?>',
+        '<Types xmlns="http://schemas.openxmlformats.org/package/2006/content-types">',
+    ]
+    for ext, ctype in sorted(defaults.items()):
+        lines.append(f'  <Default Extension="{ext}" ContentType="{ctype}"/>')
+    lines.append(
+        '  <Override PartName="/AppxManifest.xml" '
+        'ContentType="application/vnd.ms-appx.manifest+xml"/>'
+    )
+    lines.append(
+        '  <Override PartName="/AppxBlockMap.xml" '
+        'ContentType="application/vnd.ms-appx.blockmap+xml"/>'
+    )
+    lines.append(
+        '  <Override PartName="/AppxSignature.p7x" '
+        'ContentType="application/vnd.ms-appx.signature"/>'
+    )
+    lines.append("</Types>")
+    return ("\r\n".join(lines) + "\r\n").encode("utf-8")

openappx/bundle.py

@@ -0,0 +1,346 @@
+"""Build an `.msixbundle` from finished `.msix` packages.
+
+A bundle is the same OPC ZIP container as a package, and this module reuses the
+writer in `pack_core` unchanged. What differs is what goes inside, and every
+point below was read off Microsoft's own reference bundles
+(`src/test/testData/unpack/bundles` upstream), not derived from the schema:
+
+- The manifest is `AppxMetadata/AppxBundleManifest.xml`, root element `<Bundle>`
+  in the 2013 namespace — not `AppxManifest.xml`.
+- **`AppxBlockMap.xml` covers only that manifest.** A package blockmap hashes
+  every payload file; a bundle blockmap has exactly one `<File>`. The payload
+  packages carry their own blockmaps and their own signatures.
+- Payload packages are **stored**, never deflated. Their `Offset` in the bundle
+  manifest points at the file *data* — the local header offset plus `LfhSize` —
+  so it can only be filled in after the archive is laid out.
+- `[Content_Types].xml` maps `appx` and declares the `xml` default as
+  `bundlemanifest+xml`, where a package says `manifest+xml`.
+
+Deliberately not copied: the reference bundles write data descriptors after each
+entry (24 bytes, `PK\\x07\\x08`). They are optional, our writer emits none, and
+`pack_core.append_stored_part` refuses archives that have them.
+"""
+
+from __future__ import annotations
+
+import re
+import zipfile
+from dataclasses import dataclass
+from pathlib import Path
+
+from openappx.blockmap import (
+    _xml_escape,
+    prepare_file,
+    render_blockmap_xml,
+    zip_local_header_size,
+)
+from openappx.pack_core import (
+    _METHOD_DEFLATE,
+    _METHOD_STORE,
+    _Entry,
+    _write_central_directory,
+    _write_entry,
+    zip64_local_extra,
+)
+
+BUNDLE_MANIFEST = "AppxMetadata/AppxBundleManifest.xml"
+BUNDLE_NS = "http://schemas.microsoft.com/appx/2013/bundle"
+BLOCKMAP = "AppxBlockMap.xml"
+CONTENT_TYPES = "[Content_Types].xml"
+
+# The bundle version is the packages' version with the revision zeroed, which is
+# what MakeAppx does when it is not told otherwise.
+_VERSION_RE = re.compile(r"^(\d+)\.(\d+)\.(\d+)\.(\d+)$")
+
+
+@dataclass(frozen=True)
+class PackageEntry:
+    """One `.msix` about to go into a bundle, as its own manifest describes it."""
+
+    path: Path
+    name: str
+    publisher: str
+    version: str
+    architecture: str | None  # absent for a resource package
+    languages: tuple[str, ...]
+    resource_id: str
+    kind: str  # "application" or "resource"
+    signed: bool
+
+
+def _identity(manifest: str, attribute: str) -> str | None:
+    element = re.search(r"<Identity\b([^>]*)>", manifest)
+    if not element:
+        return None
+    found = re.search(rf'\b{attribute}\s*=\s*"([^"]*)"', element.group(1))
+    return found.group(1) if found else None
+
+
+def read_package(path: Path) -> PackageEntry:
+    """Describe a packed `.msix` well enough to list it in a bundle manifest."""
+    path = Path(path).resolve()
+    if not zipfile.is_zipfile(path):
+        raise ValueError(f"not a ZIP/MSIX container: {path}")
+    with zipfile.ZipFile(path) as zf:
+        names = zf.namelist()
+        if "AppxManifest.xml" not in names:
+            raise ValueError(f"{path.name} has no AppxManifest.xml")
+        manifest = zf.read("AppxManifest.xml").decode("utf-8", errors="replace")
+        signed = "AppxSignature.p7x" in names
+    # Comments in these manifests describe the very attributes being read.
+    manifest = re.sub(r"<!--.*?-->", "", manifest, flags=re.DOTALL)
+
+    missing = [
+        attribute
+        for attribute in ("Name", "Publisher", "Version")
+        if not _identity(manifest, attribute)
+    ]
+    if missing:
+        raise ValueError(f"{path.name}: Identity/@{', @'.join(missing)} missing")
+
+    languages = tuple(re.findall(r'<Resource\b[^>]*Language="([^"]+)"', manifest))
+    # `Identity/@ResourceId` is what makes a package a resource package — not the
+    # absence of <Applications>, which was the obvious guess and is wrong: a
+    # device answers 0x80080204 "its package type doesn't match the value found
+    # in the bundle manifest". Microsoft's own resource packages pair it with
+    # <Properties><ResourcePackage>true, and carry no ProcessorArchitecture.
+    resource_id = _identity(manifest, "ResourceId")
+    kind = "resource" if resource_id else "application"
+    architecture = _identity(manifest, "ProcessorArchitecture")
+    return PackageEntry(
+        path=path,
+        name=_identity(manifest, "Name") or "",
+        publisher=_identity(manifest, "Publisher") or "",
+        version=_identity(manifest, "Version") or "",
+        architecture=None if kind == "resource" else (architecture or "neutral"),
+        languages=languages or ("en-us",),
+        resource_id=resource_id or "",
+        kind=kind,
+        signed=signed,
+    )
+
+
+def bundle_version(packages: list[PackageEntry]) -> str:
+    """Highest package version with the revision zeroed, as MakeAppx does."""
+    parsed = [
+        tuple(int(n) for n in m.groups())
+        for m in (_VERSION_RE.match(p.version) for p in packages)
+        if m
+    ]
+    if not parsed:
+        return "1.0.0.0"
+    major, minor, build, _ = max(parsed)
+    return f"{major}.{minor}.{build}.0"
+
+
+def bundle_problems(packages: list[PackageEntry]) -> list[str]:
+    """Reasons these packages cannot go in one bundle (empty list => they can).
+
+    Identity has to agree: the bundle names one application, and a device
+    resolves the packages inside it against that single identity. Two packages
+    claiming the same architecture and resource are a mistake for the same
+    reason — nothing could choose between them.
+
+    Deliberately not required: an application package. A bundle of nothing but
+    resource packages is legal — upstream ships one as `ContainsOnlyResourcePackages`
+    — and is how language packs are distributed.
+    """
+    problems = []
+    names = {p.name for p in packages}
+    if len(names) > 1:
+        problems.append(
+            f"packages disagree on Identity/@Name: {', '.join(sorted(names))}"
+        )
+    publishers = {p.publisher for p in packages}
+    if len(publishers) > 1:
+        problems.append(
+            f"packages disagree on Identity/@Publisher: {', '.join(sorted(publishers))}"
+        )
+    seen: dict[tuple, Path] = {}
+    for p in packages:
+        key = (p.kind, p.architecture, p.resource_id)
+        if key in seen:
+            problems.append(
+                f"{p.path.name} and {seen[key].name} describe the same "
+                f"architecture and resource: "
+                f"{p.architecture or 'neutral'}/{p.resource_id}"
+            )
+        seen[key] = p.path
+    if not packages:
+        problems.append("a bundle needs at least one package")
+    return problems
+
+
+def unsigned_payloads(packages: list[PackageEntry]) -> list[str]:
+    """Payload packages carrying no signature of their own.
+
+    Not a `bundle_problems` entry, on purpose. Signing needs the optional
+    `[sign]` extra, and bundling must keep working without it — assembling the
+    container is mechanical. It is still a certain install failure, so the CLI
+    warns and `inspect` reports it on the finished bundle, which is where this
+    codebase puts checks that need the artefact to exist.
+
+    Signing the bundle is not enough: a device answers 0x800B0100 against the
+    *bundle*, which reads as if the bundle itself were unsigned. Measured by
+    signing one and not the other.
+    """
+    return sorted(p.path.name for p in packages if not p.signed)
+
+
+def render_bundle_manifest(
+    packages: list[PackageEntry], offsets: dict[str, int], version: str
+) -> bytes:
+    """The `<Bundle>` document, with each package's offset inside the archive.
+
+    Rendered as bytes for the same reason the blockmap is: reference tooling
+    compares byte for byte, and a serialiser would reorder attributes.
+    """
+    first = packages[0]
+    lines = [
+        '<?xml version="1.0" encoding="UTF-8" standalone="no"?>',
+        f'<Bundle SchemaVersion="2.0" xmlns="{BUNDLE_NS}">',
+        f'  <Identity Name="{_xml_escape(first.name)}" '
+        f'Publisher="{_xml_escape(first.publisher)}" Version="{version}"/>',
+        "  <Packages>",
+    ]
+    for p in packages:
+        attributes = [f'Type="{p.kind}"', f'Version="{p.version}"']
+        if p.architecture:
+            attributes.append(f'Architecture="{p.architecture}"')
+        # Only resource packages carry a ResourceId. A real Store bundle omits it
+        # on application packages, and a device that finds one there stops
+        # matching them by architecture — reporting that the bundle "does not
+        # have an appropriate application package for x64", measured.
+        if p.kind == "resource":
+            attributes.append(f'ResourceId="{_xml_escape(p.resource_id)}"')
+        attributes += [
+            f'FileName="{_xml_escape(p.path.name)}"',
+            f'Offset="{offsets[p.path.name]}"',
+            f'Size="{p.path.stat().st_size}"',
+        ]
+        lines.append(f"    <Package {' '.join(attributes)}>")
+        lines.append("      <Resources>")
+        for language in p.languages:
+            lines.append(f'        <Resource Language="{_xml_escape(language)}"/>')
+        lines.append("      </Resources>")
+        lines.append("    </Package>")
+    lines += ["  </Packages>", "</Bundle>"]
+    return ("\r\n".join(lines) + "\r\n").encode("utf-8")
+
+
+def bundle_content_types() -> bytes:
+    """`xml` defaults to bundlemanifest+xml here, where a package says manifest+xml."""
+    return (
+        "\r\n".join(
+            [
+                '<?xml version="1.0" encoding="utf-8"?>',
+                '<Types xmlns="http://schemas.openxmlformats.org/package/2006/'
+                'content-types">',
+                '  <Default Extension="appx" ContentType="application/vnd.ms-appx"/>',
+                '  <Default Extension="msix" ContentType="application/vnd.ms-appx"/>',
+                '  <Default Extension="xml" '
+                'ContentType="application/vnd.ms-appx.bundlemanifest+xml"/>',
+                '  <Override PartName="/AppxBlockMap.xml" '
+                'ContentType="application/vnd.ms-appx.blockmap+xml"/>',
+                '  <Override PartName="/AppxSignature.p7x" '
+                'ContentType="application/vnd.ms-appx.signature"/>',
+                "</Types>",
+            ]
+        )
+        + "\r\n"
+    ).encode("utf-8")
+
+
+def main(argv: list[str] | None = None) -> int:
+    import argparse
+    import sys
+
+    ap = argparse.ArgumentParser(
+        prog="openappx bundle",
+        description="Combine .msix packages into one .msixbundle",
+    )
+    ap.add_argument(
+        "--package",
+        action="append",
+        required=True,
+        type=Path,
+        dest="packages",
+        help="a packed .msix to include; repeat for each architecture",
+    )
+    ap.add_argument("--out", required=True, type=Path)
+    args = ap.parse_args(argv)
+
+    missing = [p for p in args.packages if not p.is_file()]
+    if missing:
+        for p in missing:
+            print(f"error: no such package: {p}", file=sys.stderr)
+        return 2
+    unsigned = unsigned_payloads([read_package(p) for p in args.packages])
+    if unsigned:
+        print(
+            "warning: these payload packages are unsigned, and a device will "
+            "refuse the bundle: " + ", ".join(unsigned),
+            file=sys.stderr,
+        )
+    try:
+        out = build_bundle(args.packages, args.out)
+    except ValueError as e:
+        print(f"error: {e}", file=sys.stderr)
+        return 2
+    print(
+        f"Wrote {out} ({out.stat().st_size} bytes) from {len(args.packages)} packages"
+    )
+    print("Reminder: sign the bundle itself — the packages inside are not enough.")
+    return 0
+
+
+def build_bundle(packages: list[Path], out: Path) -> Path:
+    """Write `out` as a bundle carrying `packages`, each stored verbatim."""
+    entries = [read_package(p) for p in packages]
+    problems = bundle_problems(entries)
+    if problems:
+        raise ValueError("; ".join(problems))
+
+    archive = bytearray()
+    written: list[_Entry] = []
+    offsets: dict[str, int] = {}
+    for entry in entries:
+        data = entry.path.read_bytes()
+        header_offset = len(archive)
+        written.append(
+            _write_entry(archive, entry.path.name, data, data, _METHOD_STORE)
+        )
+        # Offset is where the data starts, not where the record does.
+        offsets[entry.path.name] = header_offset + zip_local_header_size(
+            entry.path.name.encode("utf-8"), zip64_local_extra(len(data), len(data))
+        )
+
+    version = bundle_version(entries)
+    manifest = render_bundle_manifest(entries, offsets, version)
+    prepared = prepare_file(BUNDLE_MANIFEST.replace("/", "\\"), manifest)
+    lfh_size = zip_local_header_size(
+        BUNDLE_MANIFEST.encode("utf-8"),
+        zip64_local_extra(len(manifest), len(prepared.payload)),
+    )
+    # The blockmap covers this one file, so the package renderer does the job
+    # unchanged — the difference between a bundle and a package here is what is
+    # in the list, not how it is written.
+    blockmap = render_blockmap_xml([prepared.blocks], {prepared.blocks.name: lfh_size})
+
+    written.append(
+        _write_entry(
+            archive,
+            BUNDLE_MANIFEST,
+            prepared.payload,
+            manifest,
+            _METHOD_DEFLATE if prepared.deflated else _METHOD_STORE,
+        )
+    )
+    for name, data in ((CONTENT_TYPES, bundle_content_types()), (BLOCKMAP, blockmap)):
+        written.append(_write_entry(archive, name, data, data, _METHOD_STORE))
+
+    _write_central_directory(archive, written)
+    out = Path(out).resolve()
+    out.parent.mkdir(parents=True, exist_ok=True)
+    out.write_bytes(bytes(archive))
+    return out

openappx/cli.py

@@ -0,0 +1,56 @@
+"""Unified `openappx` console entrypoint."""
+
+from __future__ import annotations
+
+import sys
+
+
+def main(argv: list[str] | None = None) -> int:
+    argv = list(sys.argv[1:] if argv is None else argv)
+    if not argv or argv[0] in ("-h", "--help"):
+        print("usage: openappx <pack|bundle|unpack|sign|validate|inspect|deploy> …")
+        print("  openappx pack --root DIR --out FILE.msix")
+        print("  openappx bundle --package A.msix --package B.msix --out X.msixbundle")
+        print("  openappx unpack --package FILE.msix --out DIR")
+        print("  openappx sign --package FILE.msix --pfx CERT.pfx")
+        print("  openappx validate --root DIR")
+        print("  openappx inspect --package FILE.msix [--json]")
+        print("  openappx deploy --device URL --user NAME --package FILE.msix")
+        return 0 if argv else 2
+
+    cmd, rest = argv[0], argv[1:]
+    if cmd == "pack":
+        from openappx.pack import main as pack_main
+
+        return pack_main(rest)
+    if cmd == "bundle":
+        from openappx.bundle import main as bundle_main
+
+        return bundle_main(rest)
+    if cmd == "validate":
+        from openappx.validate import main as validate_main
+
+        return validate_main(rest)
+    if cmd == "inspect":
+        from openappx.inspect import main as inspect_main
+
+        return inspect_main(rest)
+    if cmd == "unpack":
+        from openappx.unpack import main as unpack_main
+
+        return unpack_main(rest)
+    if cmd == "sign":
+        from openappx.sign.cli import main as sign_main
+
+        return sign_main(rest)
+    if cmd == "deploy":
+        from openappx.deploy import main as deploy_main
+
+        return deploy_main(rest)
+
+    print(f"unknown command: {cmd}", file=sys.stderr)
+    return 2
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())