ipeddle 0.1.0__py3-none-any.whl

ipeddle/package.py

@@ -0,0 +1,309 @@
+"""Turn SwiftPM build products into ``Payload/<App>.app`` and an ``.ipa``."""
+
+from __future__ import annotations
+
+import json
+import os
+import plistlib
+import re
+import shutil
+import stat
+import zipfile
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import ui
+from .config import AppConfig
+from .errors import IpeddleError
+from .fsutil import rmtree
+
+ZIP_EPOCH = (1980, 1, 1, 0, 0, 0)  # fixed timestamps -> reproducible .ipa
+
+ICON_SPECS = [
+    # (file name, pixels, idiom)
+    ("AppIcon60x60@2x.png", 120, "iphone"),
+    ("AppIcon60x60@3x.png", 180, "iphone"),
+    ("AppIcon76x76@2x~ipad.png", 152, "ipad"),
+    ("AppIcon83.5x83.5@2x~ipad.png", 167, "ipad"),
+]
+
+XCODE_VARS = re.compile(r"\$\(([A-Z_]+)(?::[a-z0-9]+)?\)|\$\{([A-Z_]+)\}")
+
+
+@dataclass
+class PackageReport:
+    app: Path
+    ipa: Path
+    warnings: list[str] = field(default_factory=list)
+    flattened_images: int = 0
+
+
+def substitute_vars(obj, env: dict):
+    if isinstance(obj, str):
+        return XCODE_VARS.sub(lambda m: env.get(m.group(1) or m.group(2), m.group(0)), obj)
+    if isinstance(obj, list):
+        return [substitute_vars(x, env) for x in obj]
+    if isinstance(obj, dict):
+        return {k: substitute_vars(v, env) for k, v in obj.items()}
+    return obj
+
+
+def make_info_plist(cfg: AppConfig, executable: str, bundle_id: str, min_os: str,
+                    sdk_version: str, icons: list[str]) -> dict:
+    name = cfg.display_name or executable
+    info = {
+        "CFBundleDevelopmentRegion": "en",
+        "CFBundleExecutable": executable,
+        "CFBundleIdentifier": bundle_id,
+        "CFBundleInfoDictionaryVersion": "6.0",
+        "CFBundleName": executable[:15],
+        "CFBundleDisplayName": name,
+        "CFBundlePackageType": "APPL",
+        "CFBundleShortVersionString": cfg.version,
+        "CFBundleVersion": cfg.build,
+        "CFBundleSupportedPlatforms": ["iPhoneOS"],
+        "DTPlatformName": "iphoneos",
+        "DTPlatformVersion": sdk_version,
+        "DTSDKName": f"iphoneos{sdk_version}",
+        "MinimumOSVersion": min_os,
+        "LSRequiresIPhoneOS": True,
+        "UIDeviceFamily": cfg.device_family,
+        "UIRequiredDeviceCapabilities": ["arm64"],
+        "UILaunchScreen": {},
+        "UISupportedInterfaceOrientations": [
+            "UIInterfaceOrientationPortrait",
+            "UIInterfaceOrientationLandscapeLeft",
+            "UIInterfaceOrientationLandscapeRight",
+        ],
+        "UISupportedInterfaceOrientations~ipad": [
+            "UIInterfaceOrientationPortrait",
+            "UIInterfaceOrientationPortraitUpsideDown",
+            "UIInterfaceOrientationLandscapeLeft",
+            "UIInterfaceOrientationLandscapeRight",
+        ],
+    }
+    if icons:
+        iphone = sorted({re.sub(r"@\dx.*", "", i) for i in icons if "~ipad" not in i})
+        ipad = sorted({re.sub(r"@\dx.*", "", i) for i in icons if "~ipad" in i})
+        info["CFBundleIcons"] = {"CFBundlePrimaryIcon": {"CFBundleIconFiles": iphone}}
+        if ipad:
+            info["CFBundleIcons~ipad"] = {"CFBundlePrimaryIcon": {"CFBundleIconFiles": iphone + ipad}}
+    if cfg.info_plist:
+        try:
+            with open(cfg.info_plist, "rb") as fh:
+                user = plistlib.load(fh)
+        except Exception as e:
+            raise IpeddleError(f"cannot read {cfg.info_plist}: {e}") from e
+        env = {
+            "PRODUCT_BUNDLE_IDENTIFIER": bundle_id,
+            "EXECUTABLE_NAME": executable,
+            "PRODUCT_NAME": executable,
+            "PRODUCT_MODULE_NAME": executable,
+            "MARKETING_VERSION": cfg.version,
+            "CURRENT_PROJECT_VERSION": cfg.build,
+            "DEVELOPMENT_LANGUAGE": "en",
+            "PRODUCT_BUNDLE_PACKAGE_TYPE": "APPL",
+            "IPHONEOS_DEPLOYMENT_TARGET": min_os,
+        }
+        user = substitute_vars(user, env)
+        for key in ("UIMainStoryboardFile", "UILaunchStoryboardName"):
+            if key in user:
+                ui.warn(f"Info.plist: dropping {key} (storyboards cannot be compiled on Linux); "
+                        "the launch screen comes from UILaunchScreen instead")
+                user.pop(key)
+        info.update(user)
+        # These must describe the binary we actually ship.
+        info["CFBundleExecutable"] = executable
+        info["MinimumOSVersion"] = min_os
+        info.setdefault("UILaunchScreen", {})
+    return info
+
+
+def make_icons(src: Path, app: Path, families: list[int]) -> list[str]:
+    """Write home-screen icons from one square PNG (resized when Pillow is
+    installed, copied as-is otherwise — iOS scales it)."""
+    try:
+        from PIL import Image  # type: ignore
+    except ImportError:
+        Image = None
+    names = []
+    for fname, px, idiom in ICON_SPECS:
+        if idiom == "ipad" and 2 not in families:
+            continue
+        out = app / fname
+        if Image is not None:
+            with Image.open(src) as im:
+                im = im.convert("RGBA")
+                bg = Image.new("RGB", im.size, (255, 255, 255))  # icons must be opaque
+                bg.paste(im, mask=im.split()[3])
+                bg.resize((px, px), Image.LANCZOS).save(out, "PNG")
+        else:
+            shutil.copyfile(src, out)
+        names.append(fname)
+    return names
+
+
+def find_appicon_in_catalogs(root: Path) -> Path | None:
+    best, best_px = None, 0
+    for setdir in root.rglob("*.appiconset"):
+        try:
+            contents = json.loads((setdir / "Contents.json").read_text())
+        except (OSError, ValueError):
+            contents = {"images": []}
+        for img in contents.get("images", []):
+            fn = img.get("filename")
+            if not fn or not (setdir / fn).is_file():
+                continue
+            try:
+                size = float(str(img.get("size", "0x0")).split("x")[0])
+                scale = float(str(img.get("scale", "1x")).rstrip("x"))
+            except ValueError:
+                size, scale = 0, 1
+            px = size * scale
+            if px > best_px:
+                best, best_px = setdir / fn, px
+    return best
+
+
+def flatten_asset_catalogs(bundle_root: Path, report: PackageReport) -> None:
+    """There is no ``actool`` on Linux.  Image sets become loose files
+    (``name.png``, ``name@2x.png`` ...), which ``UIImage(named:)`` and
+    SwiftUI's ``Image("name")`` find; everything else is reported."""
+    for cat in sorted(bundle_root.rglob("*.xcassets")):
+        if not cat.is_dir():
+            continue
+        dest = cat.parent
+        unsupported = set()
+        for setdir in cat.rglob("*"):
+            if not setdir.is_dir():
+                continue
+            kind = setdir.suffix
+            if kind == ".imageset":
+                try:
+                    contents = json.loads((setdir / "Contents.json").read_text())
+                except (OSError, ValueError):
+                    continue
+                name = setdir.stem
+                for img in contents.get("images", []):
+                    fn = img.get("filename")
+                    if not fn or not (setdir / fn).is_file():
+                        continue
+                    scale = str(img.get("scale", "1x"))
+                    suffix = "" if scale in ("1x", "") else "@" + scale
+                    ext = Path(fn).suffix
+                    out = dest / f"{name}{suffix}{ext}"
+                    if not out.exists():
+                        shutil.copyfile(setdir / fn, out)
+                        report.flattened_images += 1
+            elif kind in (".colorset", ".symbolset", ".dataset", ".textureset", ".imagestack"):
+                unsupported.add(kind)
+        rmtree(cat)
+        if unsupported:
+            report.warnings.append(
+                f"{cat.name}: {', '.join(sorted(unsupported))} entries are not supported without actool "
+                "(use code-defined colors/data instead)"
+            )
+
+
+def check_uncompilable(root: Path, report: PackageReport) -> None:
+    for pattern in ("*.storyboard", "*.xib"):
+        for f in root.rglob(pattern):
+            report.warnings.append(
+                f"{f.relative_to(root)}: Interface Builder files cannot be compiled on Linux "
+                "(no ibtool); build that UI in code"
+            )
+            rmtree(f)
+
+
+def _copy(src: Path, dst: Path) -> None:
+    if src.is_dir():
+        shutil.copytree(src, dst, symlinks=True, dirs_exist_ok=True)
+    else:
+        shutil.copy2(src, dst)
+
+
+def assemble_app(*, work: Path, products_dir: Path, executable: str, cfg: AppConfig,
+                 bundle_id: str, min_os: str, sdk_version: str, app_name: str) -> PackageReport:
+    payload = work / "Payload"
+    rmtree(payload)
+    app = payload / f"{app_name}.app"
+    app.mkdir(parents=True)
+    report = PackageReport(app=app, ipa=Path())
+
+    binary = products_dir / executable
+    if not binary.is_file():
+        raise IpeddleError(f"build finished but {binary} is missing")
+    shutil.copy2(binary, app / executable)
+    os.chmod(app / executable, 0o755)
+
+    # SwiftPM resource bundles (Bundle.module looks next to the executable).
+    for b in sorted(products_dir.glob("*.bundle")):
+        _copy(b, app / b.name)
+    # Dynamic frameworks / dylibs produced or vended by the package graph.
+    fw_dir = app / "Frameworks"
+    for fw in sorted(products_dir.glob("*.framework")):
+        fw_dir.mkdir(exist_ok=True)
+        _copy(fw, fw_dir / fw.name)
+        # Like Xcode's "Embed": build-time-only parts do not ship.
+        for part in ("Headers", "PrivateHeaders", "Modules", "_CodeSignature"):
+            rmtree(fw_dir / fw.name / part)
+    for dylib in sorted(products_dir.glob("*.dylib")):
+        fw_dir.mkdir(exist_ok=True)
+        _copy(dylib, fw_dir / dylib.name)
+    for extra in cfg.resources:
+        _copy(extra, app / extra.name)
+
+    icon = cfg.icon
+    if icon is None:
+        icon = find_appicon_in_catalogs(app)
+        if icon is not None:
+            ui.info(f"using app icon from asset catalog: {icon.name}")
+    flatten_asset_catalogs(app, report)
+    check_uncompilable(app, report)
+
+    icons = make_icons(icon, app, cfg.device_family) if icon else []
+    if not icon:
+        report.warnings.append("no app icon (set `icon` in ipeddle.toml); iOS will show a blank one")
+
+    info = make_info_plist(cfg, executable, bundle_id, min_os, sdk_version, icons)
+    with open(app / "Info.plist", "wb") as fh:
+        plistlib.dump(info, fh, fmt=plistlib.FMT_BINARY)
+    (app / "PkgInfo").write_bytes(b"APPL????")
+    return report
+
+
+def write_ipa(payload_parent: Path, ipa: Path) -> Path:
+    """Zip ``Payload/`` deterministically (sorted entries, fixed times)."""
+    ipa.parent.mkdir(parents=True, exist_ok=True)
+    tmp = ipa.with_name(ipa.name + ".tmp")
+    root = payload_parent
+    entries = []
+    for dirpath, dirnames, filenames in os.walk(root / "Payload"):
+        dirnames.sort()
+        rel_dir = Path(dirpath).relative_to(root)
+        entries.append((rel_dir, True))
+        for f in sorted(filenames):
+            entries.append((rel_dir / f, False))
+    with zipfile.ZipFile(tmp, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=6) as zf:
+        for rel, is_dir in entries:
+            full = root / rel
+            if is_dir:
+                zi = zipfile.ZipInfo(str(rel) + "/", ZIP_EPOCH)
+                zi.external_attr = (0o40755 << 16) | 0x10
+                zf.writestr(zi, b"")
+                continue
+            if full.is_symlink():
+                zi = zipfile.ZipInfo(str(rel), ZIP_EPOCH)
+                zi.create_system = 3
+                zi.external_attr = (stat.S_IFLNK | 0o777) << 16
+                zf.writestr(zi, os.readlink(full))
+                continue
+            mode = full.stat().st_mode
+            zi = zipfile.ZipInfo(str(rel), ZIP_EPOCH)
+            zi.create_system = 3
+            zi.external_attr = ((stat.S_IFREG | (0o755 if mode & 0o111 else 0o644)) << 16)
+            zi.compress_type = zipfile.ZIP_DEFLATED
+            with open(full, "rb") as fh, zf.open(zi, "w") as out:
+                shutil.copyfileobj(fh, out, 1 << 20)
+    os.replace(tmp, ipa)
+    return ipa

ipeddle/patcher.py

@@ -0,0 +1,247 @@
+"""Make a public iOS SDK usable for linking Swift apps that run on iOS 15+.
+
+Public SDK mirrors ship *reconstructed* ``.tbd`` stubs: they describe the
+libraries of the iOS version the SDK was taken from, without the
+``$ld$previous`` / install-name history that Xcode's stubs carry.  Two things
+go wrong when an app built against them runs on an older iOS:
+
+1. **Swift overlays.**  Up to iOS 17, the Swift half of a framework
+   (``Foundation``'s ``Data``, ``URLRequest``, ...) lived in an overlay dylib,
+   ``/usr/lib/swift/libswiftFoundation.dylib``.  From iOS 18 it lives inside
+   the framework and the overlay only re-exports it.  The reconstructed stubs
+   put the symbols in the framework, so the linker binds them there and the
+   app fails to launch on iOS 15-17.  Fix: every Swift symbol *owned by
+   module X* that a framework re-exported by ``libswiftX`` exports is moved
+   to ``libswiftX.tbd``.  Binding through the overlay works on every version
+   (it defines the symbol on old systems and re-exports it on new ones).
+
+2. **Split frameworks.**  Frameworks sometimes get split (``SwiftUICore`` was
+   carved out of ``SwiftUI`` in iOS 18).  Declarations that moved keep their
+   original mangling (``@_originallyDefinedIn``), so a symbol mangled as
+   owned by ``SwiftUI`` but exported by ``SwiftUICore`` really belongs to the
+   parent.  Fix: such symbols move back into the parent framework that
+   re-exports the child; the app then only depends on the parent.
+
+A third class, Swift symbols the stubs do not list at all, is handled at
+build time (see :func:`learn_missing`).
+
+Nothing here contains Apple data: every rule is applied to the SDK the user
+fetched, on the user's machine.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from collections import defaultdict
+from dataclasses import dataclass, field
+from pathlib import Path
+
+from . import tbd
+from .mangling import is_swift_symbol, owner_module
+
+PATCH_VERSION = 3
+REPORT_NAME = ".ipeddle-patches.json"
+
+
+@dataclass
+class PatchReport:
+    overlays: dict[str, int] = field(default_factory=dict)   # libswiftX -> moved count
+    merged: dict[str, int] = field(default_factory=dict)     # child -> moved count
+    learned: dict[str, list[str]] = field(default_factory=dict)  # libswiftX -> symbols
+    skipped: list[str] = field(default_factory=list)
+
+    def to_json(self) -> dict:
+        return {
+            "patch_version": PATCH_VERSION,
+            "overlays": self.overlays,
+            "merged": self.merged,
+            "learned": self.learned,
+            "skipped": self.skipped,
+        }
+
+    @classmethod
+    def load(cls, sdk: Path) -> PatchReport:
+        p = sdk / REPORT_NAME
+        try:
+            d = json.loads(p.read_text())
+        except (FileNotFoundError, ValueError):
+            return cls()
+        return cls(d.get("overlays", {}), d.get("merged", {}), d.get("learned", {}), d.get("skipped", []))
+
+    def save(self, sdk: Path) -> None:
+        (sdk / REPORT_NAME).write_text(json.dumps(self.to_json(), indent=2, sort_keys=True) + "\n")
+
+
+def known_modules(sdk: Path) -> frozenset[str]:
+    """Names of every Swift module the SDK ships (plus the standard library)."""
+    names = {"Swift"}
+    for pattern in ("System/Library/Frameworks/*.framework/Modules/*.swiftmodule",
+                    "usr/lib/swift/*.swiftmodule"):
+        names.update(p.name[: -len(".swiftmodule")] for p in sdk.glob(pattern))
+    return frozenset(names)
+
+
+def tbd_path(sdk: Path, install_name: str) -> Path | None:
+    """Locate the stub for an install name inside the SDK."""
+    rel = install_name.lstrip("/")
+    for cand in (sdk / (rel + ".tbd"), sdk / (os.path.splitext(rel)[0] + ".tbd")):
+        if cand.is_file():
+            return cand
+    return None
+
+
+def _doc_for(docs, install_name):
+    for d in docs:
+        if d.install_name == install_name:
+            return d
+    return docs[0] if docs else None
+
+
+def overlay_module(path: Path) -> str | None:
+    name = path.name
+    if name.startswith("libswift") and name.endswith(".tbd"):
+        return name[len("libswift"):-len(".tbd")] or None
+    return None
+
+
+def is_stub_overlay(docs, text: str = "") -> bool:
+    """A reconstructed overlay: it re-exports something and owns no Swift
+    (or only Swift that ipeddle itself put there)."""
+    if not docs:
+        return False
+    d = docs[0]
+    if not d.reexports:
+        return False
+    return tbd.MARKER in text or not any(is_swift_symbol(s) for s in d.exports)
+
+
+def move_symbols(src: Path, dst: Path, symbols, note: str) -> int:
+    symbols = sorted(set(symbols))
+    if not symbols:
+        return 0
+    tbd.write_atomic(dst, tbd.add_symbols(dst.read_text(), symbols, note=note))
+    tbd.write_atomic(src, tbd.hide_symbols(src.read_text(), symbols))
+    return len(symbols)
+
+
+def relocate_overlays(sdk: Path, report: PatchReport, known: frozenset[str]) -> None:
+    swift_dir = sdk / "usr/lib/swift"
+    if not swift_dir.is_dir():
+        report.skipped.append("no usr/lib/swift in SDK")
+        return
+    for ov in sorted(swift_dir.glob("libswift*.tbd")):
+        module = overlay_module(ov)
+        try:
+            docs = tbd.read(ov)
+        except tbd.TbdError:
+            report.skipped.append(f"unreadable {ov.name}")
+            continue
+        if not module or not is_stub_overlay(docs):
+            continue
+        moved = 0
+        for target in docs[0].reexports:
+            fw = tbd_path(sdk, target)
+            if fw is None:
+                continue
+            fdoc = _doc_for(tbd.read(fw), target)
+            if fdoc is None:
+                continue
+            owned = [s for s in fdoc.exports if is_swift_symbol(s) and owner_module(s, known) == module]
+            moved += move_symbols(fw, ov, owned, f"moved from {target} (Swift overlay of {module})")
+        if moved:
+            report.overlays[ov.name] = report.overlays.get(ov.name, 0) + moved
+
+
+def merge_split_frameworks(sdk: Path, report: PatchReport, known: frozenset[str]) -> None:
+    fw_root = sdk / "System/Library/Frameworks"
+    if not fw_root.is_dir():
+        return
+    for parent_tbd in sorted(fw_root.glob("*.framework/*.tbd")):
+        parent_module = parent_tbd.stem
+        try:
+            pdocs = tbd.read(parent_tbd)
+        except tbd.TbdError:
+            continue
+        if not pdocs:
+            continue
+        for child in pdocs[0].reexports:
+            if not child.startswith("/System/Library/Frameworks/"):
+                continue
+            ctbd = tbd_path(sdk, child)
+            if ctbd is None or ctbd == parent_tbd:
+                continue
+            cdoc = _doc_for(tbd.read(ctbd), child)
+            if cdoc is None:
+                continue
+            owned = [s for s in cdoc.exports if is_swift_symbol(s) and owner_module(s, known) == parent_module]
+            n = move_symbols(ctbd, parent_tbd, owned, f"originally defined in {parent_module}, moved back from {child}")
+            if n:
+                report.merged[Path(child).name] = report.merged.get(Path(child).name, 0) + n
+
+
+def apply_learned(sdk: Path, report: PatchReport) -> None:
+    for lib, syms in report.learned.items():
+        p = sdk / "usr/lib/swift" / lib
+        if p.is_file():
+            tbd.write_atomic(p, tbd.add_symbols(p.read_text(), syms, note="learned at link time"))
+
+
+def patch_sdk(sdk: Path) -> PatchReport:
+    """Apply every rule to a *derived* SDK copy (never to the pristine one)."""
+    report = PatchReport.load(sdk)
+    known = known_modules(sdk)
+    relocate_overlays(sdk, report, known)
+    merge_split_frameworks(sdk, report, known)
+    apply_learned(sdk, report)
+    report.save(sdk)
+    return report
+
+
+def overlays_exporting(sdk: Path, symbols) -> set[str]:
+    """Learned overlays (as ``-l`` names, e.g. ``swiftPhotosUI``) that now
+    export at least one of ``symbols``; an app needing them links them."""
+    report = PatchReport.load(sdk)
+    wanted = set(symbols)
+    return {lib[3:-4] for lib, syms in report.learned.items() if wanted & set(syms)}
+
+
+def learn_missing(sdk: Path, symbols) -> dict[str, list[str]]:
+    """Declare undefined Swift symbols in the overlay of their owning module.
+
+    Returns ``{overlay.tbd: [symbols]}`` for what was added.  Symbols whose
+    owner has no reconstructed overlay are left alone (they are real errors).
+    """
+    report = PatchReport.load(sdk)
+    by_lib: dict[str, set[str]] = defaultdict(set)
+    swift_dir = sdk / "usr/lib/swift"
+    known = known_modules(sdk)
+    for s in symbols:
+        if not is_swift_symbol(s):
+            continue
+        mod = owner_module(s, known)
+        if not mod:
+            continue
+        ov = swift_dir / f"libswift{mod}.tbd"
+        if not ov.is_file():
+            continue
+        try:
+            text = ov.read_text()
+            if not is_stub_overlay(tbd.parse(text), text):
+                continue
+        except tbd.TbdError:
+            continue
+        by_lib[ov.name].add(s)
+    added: dict[str, list[str]] = {}
+    for lib, syms in by_lib.items():
+        p = swift_dir / lib
+        before = tbd.read(p)[0].exports
+        new = sorted(syms - before)
+        if not new:
+            continue
+        tbd.write_atomic(p, tbd.add_symbols(p.read_text(), new, note="learned at link time"))
+        report.learned[lib] = sorted(set(report.learned.get(lib, [])) | set(new))
+        added[lib] = new
+    if added:
+        report.save(sdk)
+    return added

ipeddle/paths.py

@@ -0,0 +1,76 @@
+"""Where ipeddle keeps things, and its small persistent state file."""
+
+from __future__ import annotations
+
+import json
+import os
+from dataclasses import dataclass
+from pathlib import Path
+
+BUNDLE_NAME = "ipeddle-ios.artifactbundle"
+SWIFT_SDK_ID = "ipeddle-ios"
+TRIPLE = "arm64-apple-ios"
+
+
+@dataclass(frozen=True)
+class Home:
+    root: Path
+
+    @classmethod
+    def default(cls) -> Home:
+        env = os.environ.get("IPEDDLE_HOME")
+        if env:
+            return cls(Path(env).expanduser().resolve())
+        xdg = os.environ.get("XDG_DATA_HOME")
+        base = Path(xdg).expanduser() if xdg else Path.home() / ".local" / "share"
+        return cls((base / "ipeddle").resolve())
+
+    @property
+    def state_file(self) -> Path:
+        return self.root / "state.json"
+
+    @property
+    def toolchains(self) -> Path:
+        return self.root / "toolchains"
+
+    @property
+    def sources(self) -> Path:
+        return self.root / "sources"
+
+    @property
+    def sdk_dir(self) -> Path:
+        return self.root / "sdk"
+
+    @property
+    def resource_dir(self) -> Path:
+        return self.root / "resource"
+
+    @property
+    def swift_sdks(self) -> Path:
+        return self.root / "swift-sdks"
+
+    @property
+    def bundle(self) -> Path:
+        return self.swift_sdks / BUNDLE_NAME
+
+    @property
+    def module_cache(self) -> Path:
+        return self.root / "cache" / "modules"
+
+    @property
+    def downloads(self) -> Path:
+        return self.root / "downloads"
+
+    def load_state(self) -> dict:
+        try:
+            return json.loads(self.state_file.read_text())
+        except FileNotFoundError:
+            return {}
+        except ValueError:
+            return {}
+
+    def save_state(self, state: dict) -> None:
+        self.root.mkdir(parents=True, exist_ok=True)
+        tmp = self.state_file.with_suffix(".tmp")
+        tmp.write_text(json.dumps(state, indent=2, sort_keys=True) + "\n")
+        os.replace(tmp, self.state_file)

ipeddle/proc.py

@@ -0,0 +1,58 @@
+"""Subprocess helpers: always bounded, output captured or streamed."""
+
+from __future__ import annotations
+
+import os
+import shlex
+import signal
+import subprocess
+from pathlib import Path
+
+from . import ui
+from .errors import IpeddleError
+
+
+def run(cmd, *, cwd=None, env=None, timeout=600, check=True, capture=True, log: Path | None = None):
+    """Run ``cmd``; kill the whole process group on timeout.
+
+    With ``log`` set, output is written to that file (and the tail is shown
+    on failure).  Returns a CompletedProcess with ``stdout`` as text.
+    """
+    cmd = [str(c) for c in cmd]
+    ui.debug("$ " + shlex.join(cmd))
+    full_env = dict(os.environ)
+    if env:
+        full_env.update(env)
+    out_fh = None
+    if log is not None:
+        log.parent.mkdir(parents=True, exist_ok=True)
+        out_fh = open(log, "w")
+        stdout, stderr = out_fh, subprocess.STDOUT
+    elif capture:
+        stdout, stderr = subprocess.PIPE, subprocess.STDOUT
+    else:
+        stdout = stderr = None
+    try:
+        p = subprocess.Popen(cmd, cwd=cwd, env=full_env, stdout=stdout, stderr=stderr,
+                             text=True, start_new_session=True)
+    except FileNotFoundError as e:
+        raise IpeddleError(f"command not found: {cmd[0]}") from e
+    try:
+        out, _ = p.communicate(timeout=timeout)
+    except subprocess.TimeoutExpired:
+        try:
+            os.killpg(p.pid, signal.SIGKILL)
+        except ProcessLookupError:
+            pass
+        p.wait()
+        raise IpeddleError(f"timed out after {timeout}s: {shlex.join(cmd[:3])} ...")
+    finally:
+        if out_fh:
+            out_fh.close()
+    if log is not None:
+        out = log.read_text(errors="replace")
+    cp = subprocess.CompletedProcess(cmd, p.returncode, out or "", "")
+    if check and p.returncode != 0:
+        tail = "\n".join((out or "").splitlines()[-25:])
+        raise IpeddleError(f"command failed ({p.returncode}): {shlex.join(cmd[:4])} ...\n{tail}")
+    return cp