helix

#!/usr/bin/env python3
"""helix — build and refresh the Helix Boot USB.

Resolves the newest upstream release of every tool in tools.toml, downloads and
verifies it into a local cache, then syncs the cache onto a Ventoy stick with a
generated boot menu. Standard library only (Python 3.11+).
"""
from __future__ import annotations

import argparse
import datetime as dt
import hashlib
import html
import importlib.util
import json
import os
import re
import shutil
import subprocess
import struct
import sys
import tarfile
import time
import urllib.error
import urllib.parse
import urllib.request
import xml.etree.ElementTree as ET
import zipfile
import zlib
from email.utils import parsedate_to_datetime
from pathlib import Path, PureWindowsPath

if sys.version_info < (3, 11):
    sys.exit("✗ helix needs Python 3.11 or newer (for tomllib).")
import tomllib  # noqa: E402

__version__ = "0.6.7"

REPO = Path(__file__).resolve().parent
def _env(name: str, default: str | None = None) -> str | None:
    """HELIX_<name>, or the CRESCUE_<name> it was called before the rename to Helix Boot."""
    return os.environ.get(f"HELIX_{name}") or os.environ.get(f"CRESCUE_{name}") or default


GITHUB_API = _env("GITHUB_API", "https://api.github.com")
SF_RSS = _env("SF_RSS", "https://sourceforge.net/projects/{project}/rss?path={path}")  # SourceForge rejects limit > 100
SF_DL = _env("SF_DL", "https://downloads.sourceforge.net/project/{project}{path}")
USER_AGENT = f"helix-boot/{__version__} (+https://github.com/Commanderx-code/helix-boot)"
# For the few sites that turn away anything but a browser (`user_agent = "browser"` on a tool)
BROWSER_UA = "Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:140.0) Gecko/20100101 Firefox/140.0"
KINDS = {"iso", "app", "ventoy", "file", "tree"}
SOURCES = {"github": ["repo"], "sourceforge": ["project", "path"], "url": ["url"], "page": ["page", "asset", "version"],
           "local": ["path"]}
HASH_BY_LEN = {32: "md5", 40: "sha1", 64: "sha256", 128: "sha512"}
STRENGTH = {"md5": 1, "sha1": 2, "sha256": 3, "sha512": 4}
STATE_DIR = ".helix-boot"
TAG_FILE = "helix-boot.tag"
STICK_LABEL = "HelixBoot"     # the volume name a new stick gets (Ventoy's own is "Ventoy")
# The stick's look (`helix theme`): ventoy/theme and ventoy/ventoy.json are built from these
THEME_SRC = f"{STATE_DIR}/theme"              # the theme as synced: presets, icon packs, your own icons
BASE_JSON = f"{STATE_DIR}/ventoy.base.json"   # the boot menu before the look is applied
LOOK_FILE = f"{STATE_DIR}/look.json"          # the choice
LOOK_DIR = f"{STATE_DIR}/look"                # your own background.png / splash.png, set on the stick
LOOK_DEFAULT = {"theme": "default", "icons": "auto", "background": "theme", "splash": "auto"}
HASHES = f"{STATE_DIR}/hashes.json"           # every app file's sha256 as it was put on (`helix verify`)
# Before the rename to Helix Boot: still written or read, so older sticks, launchers and
# Lazarus PE builds keep working
OLD_STATE_DIR = ".commander-rescue"
OLD_TAG_FILE = "commander-rescue.tag"
OLD_CACHE = "~/.cache/commander-rescue"
# Category ids from before the MediCat-style menu; local.toml entries using them keep working.
OLD_CATEGORIES = {"windows-pe": "live", "rescue": "live"}


# ── Output ────────────────────────────────────────────────────────────────
def _isatty(stream) -> bool:
    """Is this a terminal? A windowed program started from Explorer (HelixBoot.exe) has no
    console at all: its sys.stdout and sys.stderr are None."""
    return bool(stream) and getattr(stream, "isatty", lambda: False)()


class C:
    on = _isatty(sys.stdout) and not os.environ.get("NO_COLOR")
    G, Y, R, B, D, X = (
        ("\033[32m", "\033[33m", "\033[31m", "\033[1m", "\033[2m", "\033[0m") if on else ("",) * 6
    )


def ok(msg: str) -> None:
    print(f"{C.G}✓{C.X} {msg}")


def warn(msg: str) -> None:
    print(f"{C.Y}!{C.X} {msg}", file=sys.stderr)  # stderr: keeps `check --json` output clean


def bad(msg: str) -> None:
    print(f"{C.R}✗{C.X} {msg}", file=sys.stderr)


def info(msg: str) -> None:
    print(f"{C.D}•{C.X} {msg}")


def head(msg: str) -> None:
    print(f"\n{C.B}{msg}{C.X}")


class RescueError(Exception):
    """An error with a message meant for humans. No tracebacks."""


# ── Config ────────────────────────────────────────────────────────────────
class Config:
    def __init__(self, repo: Path = REPO, manifest: Path | None = None, assets: Path | None = None,
                 windows: bool | None = None):
        """repo: your folder (local.toml, byo/). assets: the shipped files (tools.toml, theme/,
        pe/launcher/), the same folder except in the Windows app, which carries them inside."""
        self.repo = repo
        self.assets = assets or repo
        self.windows = os.name == "nt" if windows is None else windows
        path = manifest or self.assets / "tools.toml"
        if not path.exists():
            raise RescueError(f"can't find {path}")
        try:
            data = tomllib.loads(path.read_text(encoding="utf-8"))
        except tomllib.TOMLDecodeError as e:
            raise RescueError(f"{path.name} has a syntax error: {e}") from None

        local = repo / "local.toml"
        overrides: dict = {}
        if local.exists() and manifest is None:
            try:
                ldata = tomllib.loads(local.read_text(encoding="utf-8"))
            except tomllib.TOMLDecodeError as e:
                raise RescueError(f"local.toml has a syntax error: {e}") from None
            overrides = ldata.get("overrides", {})
            data.setdefault("tool", []).extend(ldata.get("tool", []))
            data.setdefault("settings", {}).update(ldata.get("settings", {}))
            ldata_tools = ldata.get("tool", [])
        else:
            ldata_tools = []
        # Tools you switched off yourself, in local.toml. Not the ones that are off as shipped
        # (Kaspersky): another PC may have them on, and an update here mustn't remove theirs.
        self.switched_off = ({n for n, o in overrides.items() if o.get("enabled") is False}
                             | {t.get("name") for t in ldata_tools if t.get("enabled") is False})

        self.settings = data.get("settings", {})
        self.categories = {c["id"]: c for c in data.get("category", [])}
        self.tools: list[dict] = []
        seen = set()
        for t in data.get("tool", []):
            t = {**t, **overrides.get(t.get("name", ""), {})}
            if self.windows:  # `windows = { asset = [...] }` swaps in the Windows download
                t.update(t.get("windows", {}))
            self._validate(t, seen)
            seen.add(t["name"])
            self.tools.append(t)
        unknown = set(overrides) - seen
        if unknown:
            raise RescueError(f"local.toml overrides unknown tool(s): {', '.join(sorted(unknown))}")

        cache = _env("CACHE") or self.settings.get("cache_dir", "~/.cache/helix-boot")
        self.cache = Path(cache).expanduser()
        old = Path(OLD_CACHE).expanduser()
        # Only for a real run: code that loads a manifest itself (tests) must not move your cache
        if manifest is None and not self.cache.exists() and old.is_dir() and self.cache.name == "helix-boot":
            self.cache.parent.mkdir(parents=True, exist_ok=True)
            os.rename(old, self.cache)          # renamed with the project: move it over, don't re-download
        self.iso_root = self.settings.get("iso_root", "ISO")
        self.apps_root = self.settings.get("apps_root", "Apps")
        self.mac_root = self.settings.get("mac_root", "Mac")   # apps with platform = "mac"
        self.stick_label = str(self.settings.get("stick_label", STICK_LABEL))   # the name install gives a stick
        if not re.fullmatch(r"[A-Za-z0-9_-]{1,11}", self.stick_label):
            raise RescueError("stick_label must be 1 to 11 letters, digits, - or _ (it is the stick's volume name)")

    def _validate(self, t: dict, seen: set) -> None:
        name = t.get("name")
        where = f"tool '{name}'" if name else "a [[tool]] entry"
        if not name or not re.fullmatch(r"[a-z0-9][a-z0-9_-]*", name):
            raise RescueError(f"{where}: name must be lowercase letters, digits, - or _")
        if name in seen:
            raise RescueError(f"{where} is defined twice")
        if t.get("kind") not in KINDS:
            raise RescueError(f"{where}: kind must be one of {sorted(KINDS)}")
        for img, colour in (t.get("recolor") or {}).items():
            if not re.fullmatch(r"[0-9A-Fa-f]{6}", str(colour)):
                raise RescueError(f"{where}: recolor.{img} must be a hex colour like 2AA9BE")
        if t.get("ventoy_mode") and t.get("ventoy_mode") not in VENTOY_MODES:
            raise RescueError(f"{where}: ventoy_mode must be one of {sorted(VENTOY_MODES)}")
        if t.get("platform") not in (None, "mac") or (t.get("platform") and t["kind"] != "app"):
            raise RescueError(f"{where}: platform can only be \"mac\", on an app")
        if t["kind"] == "file":
            dest = t.get("dest") or ""
            if not dest or dest.startswith("/") or ".." in dest.split("/"):
                raise RescueError(f"{where}: a file needs 'dest', a path on the stick such as ventoy/x.img")
        if t["kind"] == "tree":
            for key in ("dest", "once"):
                v = t.get(key)
                if v is None or v.startswith("/") or ".." in v.split("/") or (key == "once" and not v):
                    raise RescueError(f"{where}: a tree needs 'dest' (\"\" for the stick's root) and 'once', "
                                      "the file whose presence means it's installed")
        src = t.get("source")
        if src not in SOURCES:
            raise RescueError(f"{where}: source must be one of {sorted(SOURCES)}")
        for key in SOURCES[src]:
            if key not in t:
                raise RescueError(f"{where}: source '{src}' needs '{key}'")
        if src in ("github", "sourceforge") and not (t.get("asset") or t.get("download_template")):
            raise RescueError(f"{where}: needs an 'asset' regex list (or a download_template)")
        if t["kind"] == "iso" and t.get("category") not in self.categories \
                and OLD_CATEGORIES.get(t.get("category")) in self.categories:
            t["category"] = OLD_CATEGORIES[t["category"]]
        if t["kind"] == "iso" and t.get("category") not in self.categories:
            raise RescueError(f"{where}: category '{t.get('category')}' isn't a [[category]] id")
        if src != "local" and not t.get("checksum"):
            raise RescueError(
                f"{where}: no checksum strategy. Add one, or checksum = [\"tofu\"] to accept "
                "unverified downloads explicitly."
            )
        for pat in t.get("asset", []) + [t.get("version") or "", t.get("extract") or ""]:
            try:
                re.compile(pat.replace("{name}", "x"))
            except re.error as e:
                raise RescueError(f"{where}: bad regex {pat!r}: {e}") from None

    def pc_id(self) -> str:
        """A random name for this PC, kept in its cache: a stick records which PC put each tool
        on it, so a PC tidies up after itself and leaves another PC's tools alone."""
        if not getattr(self, "_pc_id", None):
            f = self.cache / "pc-id"
            try:
                self._pc_id = f.read_text(encoding="utf-8").strip()
            except OSError:
                self._pc_id = ""
            if not re.fullmatch(r"[0-9a-f]{16}", self._pc_id):
                self._pc_id = os.urandom(8).hex()
                try:
                    self.cache.mkdir(parents=True, exist_ok=True)
                    f.write_text(self._pc_id + "\n", encoding="utf-8")
                except OSError:
                    pass        # a cache it can't write: a new name each run, so it only ever keeps
        return self._pc_id

    def enabled(self, names: list[str] | None = None, kinds: set[str] | None = None) -> list[dict]:
        if names:
            known = {t["name"] for t in self.tools}
            missing = [n for n in names if n not in known]
            if missing:
                raise RescueError(f"unknown tool(s): {', '.join(missing)} (see `helix list`)")
            picked = [t for t in self.tools if t["name"] in names]
        else:
            picked = [t for t in self.tools if t.get("enabled", True)]
        return [t for t in picked if not kinds or t["kind"] in kinds]


# ── HTTP ──────────────────────────────────────────────────────────────────
def _is_github_api(url: str) -> bool:
    """Is url on the GitHub API itself? Compared by parsed scheme, host and port, never by
    string prefix: https://api.github.com.example.net/ must not get the token."""
    u, api = urllib.parse.urlsplit(url), urllib.parse.urlsplit(GITHUB_API)
    try:
        same_port = u.port == api.port
    except ValueError:
        return False
    return (u.scheme == api.scheme and u.hostname is not None and u.hostname == api.hostname and same_port
            and (u.path == api.path or u.path.startswith(api.path.rstrip("/") + "/")))


def _request(url: str, headers: dict | None = None) -> urllib.request.Request:
    req = urllib.request.Request(url, headers={"User-Agent": USER_AGENT, **(headers or {})})
    if os.environ.get("GITHUB_TOKEN") and _is_github_api(url):
        # unredirected: urllib doesn't pass it on if GitHub redirects elsewhere
        req.add_unredirected_header("Authorization", f"Bearer {os.environ['GITHUB_TOKEN']}")
    return req


def _ua(tool: dict) -> dict | None:
    return {"User-Agent": BROWSER_UA} if tool.get("user_agent") == "browser" else None


def http_get(url: str, headers: dict | None = None, timeout: int = 60) -> bytes:
    """GET a page or API response. Server errors and timeouts are retried like downloads."""
    for delay in RETRY_DELAYS:
        try:
            return _http_get_once(url, headers, timeout)
        except _Transient as e:
            warn(f"{e} — retrying in {delay}s")
            time.sleep(delay)
    try:
        return _http_get_once(url, headers, timeout)
    except _Transient as e:
        raise RescueError(str(e)) from None


class _Transient(Exception):
    """A failure worth retrying: 5xx, timeout, dropped connection."""


def _http_get_once(url: str, headers: dict | None, timeout: int) -> bytes:
    host = urllib.parse.urlparse(url).netloc
    try:
        with urllib.request.urlopen(_request(url, headers), timeout=timeout) as r:
            return r.read()
    except urllib.error.HTTPError as e:
        if e.code >= 500:
            raise _Transient(f"HTTP {e.code} from {url}") from None
        if e.code in (403, 429) and _is_github_api(url):
            body = e.read().decode("utf-8", "replace")
            if "rate limit" in body.lower():
                raise RescueError(
                    "GitHub API rate limit hit. Set GITHUB_TOKEN (any read-only token) and retry."
                ) from None
            try:
                msg = json.loads(body).get("message", body)
            except ValueError:
                msg = body
            raise RescueError(f"GitHub refused the request ({e.code}): {msg.strip()[:200]}") from None
        if e.code == 404:
            raise FileNotFoundError(url) from None
        raise RescueError(f"HTTP {e.code} from {url}") from None
    except urllib.error.URLError as e:
        raise _Transient(f"couldn't reach {host}: {e.reason}") from None
    except (TimeoutError, ConnectionError) as e:
        raise _Transient(f"lost the connection to {host}: {e or 'timed out'}") from None


def _fmt_bytes(n: float) -> str:
    for unit in ("B", "KiB", "MiB", "GiB"):
        if n < 1024 or unit == "GiB":
            return f"{n:.1f} {unit}" if unit != "B" else f"{int(n)} B"
        n /= 1024
    return f"{n:.1f} GiB"


def _fmt_eta(seconds: float) -> str:
    s = int(seconds)
    return f"{s // 3600}h{s % 3600 // 60:02d}m" if s >= 3600 else f"{s // 60}m{s % 60:02d}s"


class Progress:
    """One status line on stderr for long copies. With a known total it shows the whole
    job (bar, bytes, speed, ETA); otherwise just the current file. Silent unless stderr
    is a terminal, so logs and the Windows app stay clean."""

    def __init__(self, total: int = 0, hook=None):
        self.total, self.done = total, 0
        self.hook = hook            # hook(percent): the Windows app's progress bar
        self.tty = _isatty(sys.stderr)
        self.start = self.last = time.monotonic()
        self.label, self.fsize, self.fdone, self.fstart = "", 0, 0, self.start

    def file(self, label: str, size: int) -> None:
        self.label, self.fsize, self.fdone, self.fstart = label, size, 0, time.monotonic()

    def add(self, n: int) -> None:
        self.done += n
        self.fdone += n
        now = time.monotonic()
        if (self.tty or self.hook) and now - self.last > 0.25:
            self.last = now
            if self.tty:
                print("\r" + self.line(now), end="", file=sys.stderr)
            if self.hook and self.total:
                self.hook(min(self.done * 100 // self.total, 100))

    def line(self, now: float) -> str:
        width = shutil.get_terminal_size((100, 20)).columns - 1
        if self.total:
            frac = min(self.done / self.total, 1.0)
            rate = self.done / max(now - self.start, 1e-6)
            fill = int(frac * 20)
            bar = "=" * fill + (">" if fill < 20 else "") + " " * max(19 - fill, 0)
            text = (f"  [{bar}] {frac * 100:3.0f}%  {_fmt_bytes(self.done)}/{_fmt_bytes(self.total)}"
                    f"  {_fmt_bytes(rate)}/s  ETA {_fmt_eta((self.total - self.done) / rate if rate else 0)}"
                    f"  {self.label}")
        else:
            rate = self.fdone / max(now - self.fstart, 1e-6)
            pct = self.fdone * 100 // self.fsize if self.fsize else 0
            text = (f"  -> {self.label} {pct:3d}%  {_fmt_bytes(self.fdone)}/{_fmt_bytes(self.fsize)}"
                    f"  {_fmt_bytes(rate)}/s")
        return text[:width].ljust(width)

    def clear(self) -> None:
        if self.tty:
            print("\r" + " " * (shutil.get_terminal_size((100, 20)).columns - 1) + "\r", end="", file=sys.stderr)


RETRY_DELAYS = (2, 5, 10)  # seconds to wait before each retry of a failed request


def download(url: str, dest: Path) -> None:
    """Download to dest, resuming a previous .part file when the server allows it.

    Server errors (5xx), timeouts and dropped connections are retried a few
    times: release hosts like GitHub's return the odd transient 500.
    """
    part = dest.with_name(dest.name + ".part")
    have = part.stat().st_size if part.exists() else 0
    headers = {"Range": f"bytes={have}-"} if have else {}
    for attempt, delay in enumerate((*RETRY_DELAYS, None)):
        try:
            resp = urllib.request.urlopen(_request(url, headers), timeout=60)
            break
        except urllib.error.HTTPError as e:
            if e.code == 416 and have:  # .part already complete
                os.replace(part, dest)
                return
            err = f"HTTP {e.code} from {url}"
            if e.code < 500:
                raise RescueError(f"download failed: {err}") from None
        except (urllib.error.URLError, TimeoutError, ConnectionError) as e:
            err = str(getattr(e, "reason", e))
        if delay is None:
            raise RescueError(f"download failed after {attempt + 1} tries: {err}")
        warn(f"{err} — retrying in {delay}s")
        time.sleep(delay)

    with resp:
        resumed = have and resp.status == 206
        if not resumed:
            have = 0
        total = resp.headers.get("Content-Length")
        total = int(total) + have if total else None
        done, last, start = have, 0.0, time.monotonic()
        tty = _isatty(sys.stderr)
        with open(part, "ab" if resumed else "wb") as f:
            while chunk := resp.read(1 << 20):
                f.write(chunk)
                done += len(chunk)
                now = time.monotonic()
                if tty and now - last > 0.25:
                    last = now
                    rate = (done - have) / max(now - start, 1e-6)
                    pct = f"{done * 100 // total:3d}%" if total else "    "
                    tot = f"/{_fmt_bytes(total)}" if total else ""
                    print(
                        f"\r  ↓ {_fmt_bytes(done)}{tot} {pct}  {_fmt_bytes(rate)}/s   ",
                        end="",
                        file=sys.stderr,
                    )
            f.flush()
            os.fsync(f.fileno())
        if tty:
            print("\r" + " " * 60 + "\r", end="", file=sys.stderr)
    if total and done != total:
        raise RescueError(f"download was cut short ({_fmt_bytes(done)} of {_fmt_bytes(total)}); run fetch again to resume")
    os.replace(part, dest)


def file_hash(path: Path, algo: str = "sha256", progress: "Progress | None" = None) -> str:
    h = hashlib.new(algo)
    with open(path, "rb") as f:
        while chunk := f.read(1 << 20):
            h.update(chunk)
            if progress:
                progress.add(len(chunk))
    return h.hexdigest()


def folder_hash(path: Path) -> str:
    """One sha256 for a folder: every file's path and content, so any change shows."""
    h = hashlib.sha256()
    for f in sorted(p for p in path.rglob("*") if p.is_file()):
        h.update(f"{f.relative_to(path).as_posix()}\0{file_hash(f)}\n".encode("utf-8"))
    return h.hexdigest()


def _uncached(path: Path) -> None:
    """Have the OS drop its cached copy of path, so hashing it next really reads the disk.
    Without this, verifying a file just written to a stick would read it back from RAM."""
    if hasattr(os, "posix_fadvise"):
        fd = os.open(path, os.O_RDONLY)
        try:
            os.posix_fadvise(fd, 0, 0, os.POSIX_FADV_DONTNEED)
        finally:
            os.close(fd)


def remote_id(url: str) -> str | None:
    """Identify an unversioned download by ETag / Last-Modified / size (HEAD request)."""
    req = _request(url)
    req.method = "HEAD"
    try:
        with urllib.request.urlopen(req, timeout=30) as r:
            parts = [r.headers.get("ETag"), r.headers.get("Last-Modified"), r.headers.get("Content-Length")]
    except (urllib.error.URLError, TimeoutError):
        return None
    return "|".join(p or "" for p in parts) if any(parts) else None


def is_current(prev: dict | None, res: dict) -> bool:
    if not prev or prev.get("source_file", prev.get("file")) != res["file"]:
        return False
    if res["version"] is not None:
        return prev.get("version") == res["version"]
    return res.get("remote_id") is not None and prev.get("remote_id") == res["remote_id"]


# ── Resolving the latest upstream release ─────────────────────────────────
def _pick(names: list[str], patterns: list[str]) -> list[str]:
    """Return matches for the first pattern that matches anything."""
    for pat in patterns:
        rx = re.compile(pat)
        hits = [n for n in names if rx.search(n)]
        if hits:
            return hits
    return []


def _version(tool: dict, filename: str, fallback: str | None) -> str:
    if tool.get("version_pin"):
        return str(tool["version_pin"])
    if tool.get("version"):
        m = re.search(tool["version"], filename)
        if m:
            return "-".join(g for g in m.groups() if g) if m.groups() else m.group(0)
    if fallback:
        return clean_tag(fallback)
    return dt.date.today().isoformat()


def clean_tag(tag: str) -> str:
    """'v8.10' → '8.10', 'version-1.4.0' → '1.4.0', 'rel_2024' → '2024'."""
    m = re.search(r"\d[\w.+-]*", tag)
    return m.group(0) if m else tag


def resolve(tool: dict, cfg: Config) -> dict:
    """Work out what the newest upstream file is, without downloading it."""
    src = tool["source"]
    res: dict = {"digest": None, "md5": None, "gh_assets": {}, "dir_url": None}

    if src == "github":
        try:
            raw = http_get(f"{GITHUB_API}/repos/{tool['repo']}/releases/latest",
                           {"Accept": "application/vnd.github+json"})
        except FileNotFoundError:
            raise RescueError(f"{tool['repo']} has no published releases on GitHub") from None
        rel = json.loads(raw)
        assets = {a["name"]: a for a in rel.get("assets", [])}
        if tool.get("download_template"):
            # GitHub only tells us the version; the file lives on the project's own site.
            ver = clean_tag(rel.get("tag_name") or "")
            url = tool["download_template"].format(version=ver, tag=rel.get("tag_name"))
            res.update(file=urllib.parse.unquote(url.rsplit("/", 1)[-1]), url=url,
                       dir_url=url.rsplit("/", 1)[0], tag=rel.get("tag_name"), gh_assets=assets)
            res["version"] = _version(tool, res["file"], ver)
            return res
        hits = _pick(list(assets), tool["asset"])
        if not hits:
            raise RescueError(
                f"no file in {tool['repo']} {rel.get('tag_name')} matches {tool['asset']} "
                f"(files: {', '.join(assets) or 'none'})"
            )
        a = assets[hits[0]]
        res.update(file=a["name"], url=a["browser_download_url"], size=a.get("size"),
                   gh_assets=assets, tag=rel.get("tag_name"))
        if (a.get("digest") or "").startswith("sha256:"):
            res["digest"] = a["digest"].split(":", 1)[1]
        res["version"] = _version(tool, a["name"], rel.get("tag_name"))

    elif src == "sourceforge":
        url = SF_RSS.format(project=tool["project"], path=urllib.parse.quote(tool["path"]))
        try:
            root = ET.fromstring(http_get(url))
        except FileNotFoundError:
            raise RescueError(f"SourceForge project '{tool['project']}' not found") from None
        except ET.ParseError:
            raise RescueError(f"SourceForge returned something that isn't RSS for {tool['project']}") from None
        entries = []
        for i, item in enumerate(root.iter("item")):
            title = (item.findtext("title") or "").strip()
            if not title:
                continue
            md5 = None
            for el in item.iter():
                if el.tag.endswith("hash") and el.get("algo") == "md5":
                    md5 = (el.text or "").strip().lower()
            try:
                when = parsedate_to_datetime(item.findtext("pubDate") or "").timestamp()
            except (TypeError, ValueError):
                when = -i  # RSS is newest-first; keep that order
            entries.append({"path": title, "name": title.rsplit("/", 1)[-1], "md5": md5, "when": when})
        hits = set(_pick([e["name"] for e in entries], tool["asset"]))
        cands = [e for e in entries if e["name"] in hits]
        if not cands:
            raise RescueError(f"no file in SourceForge {tool['project']}{tool['path']} matches {tool['asset']}")
        e = max(cands, key=lambda e: e["when"])
        quoted = urllib.parse.quote(e["path"])
        res.update(file=e["name"], url=SF_DL.format(project=tool["project"], path=quoted), md5=e["md5"],
                   dir_url=SF_DL.format(project=tool["project"], path=quoted.rsplit("/", 1)[0]))
        # Version: from the file name, else its release folder, else SourceForge's upload date
        folder = e["path"].rstrip("/").split("/")[-2] if e["path"].count("/") > 1 else None
        uploaded = dt.date.fromtimestamp(e["when"]).isoformat() if e["when"] > 0 else None
        res["version"] = _version(tool, e["name"], folder or uploaded)

    elif src == "url":
        # `file` names downloads whose URL doesn't end in one (redirect links like .../fwlink/?LinkId=…)
        name = tool.get("file") or urllib.parse.unquote(urllib.parse.urlparse(tool["url"]).path.rsplit("/", 1)[-1])
        if not name:
            raise RescueError(f"{tool['title']}: {tool['url']} doesn't end in a file name — add file = \"name.ext\"")
        res.update(file=name, url=tool["url"], dir_url=tool["url"].rsplit("/", 1)[0])
        res["version"] = _version(tool, name, None) if (tool.get("version") or tool.get("version_pin")) else None
        if res["version"] is None:
            res["remote_id"] = remote_id(tool["url"])

    elif src == "page":
        # A download page whose links carry the version (hdat2cd_76.iso, DGEng6201829_x64.zip)
        text = http_get(tool["page"], _ua(tool)).decode("utf-8", "replace")
        hrefs = [urllib.parse.urljoin(tool["page"], html.unescape(h))
                 for h in re.findall(r"""href\s*=\s*["']([^"']+)""", text, re.I)]
        hits: list[tuple[str, str]] = []
        for pat in tool["asset"]:  # first pattern that matches anything wins, as for releases
            hits = [(m.group(0), h) for h in hrefs if (m := re.search(pat, h))]
            if hits:
                break
        if not hits:
            raise RescueError(f"no link on {tool['page']} matches {tool['asset']}")
        name, url = max(hits, key=lambda nh: [int(n) for n in re.findall(r"\d+", _version(tool, nh[0], None))])
        res.update(file=name, url=url, dir_url=tool["page"], version=_version(tool, name, None))

    elif src == "local":
        p = (cfg.repo / Path(tool["path"]).expanduser()).resolve()
        res.update(file=p.name, url=None, path=p)
        res["version"] = (
            dt.date.fromtimestamp(p.stat().st_mtime).isoformat() if p.exists() else None
        )
    return res


# ── Checksums ─────────────────────────────────────────────────────────────
def parse_checksum_text(text: str, filename: str) -> tuple[str, str] | None:
    """Find the strongest hash for `filename` in a sha*sum / CHECKSUMS.TXT / BSD-style file."""
    hexrx = re.compile(r"\b([0-9a-fA-F]{128}|[0-9a-fA-F]{64}|[0-9a-fA-F]{40}|[0-9a-fA-F]{32})\b")
    best: tuple[str, str] | None = None
    lines = text.splitlines()
    for line in lines:
        if filename not in line:
            continue
        for h in hexrx.findall(line):
            algo = HASH_BY_LEN[len(h)]
            if not best or STRENGTH[algo] > STRENGTH[best[0]]:
                best = (algo, h.lower())
    if best:
        return best
    # single-file checksum (e.g. foo.iso.sha256 containing just the hash)
    allhex = hexrx.findall(text)
    if len(allhex) == 1:
        return HASH_BY_LEN[len(allhex[0])], allhex[0].lower()
    return None


def expected_hash(tool: dict, res: dict) -> tuple[str, str | None, str]:
    """Return (algo, hex, how) — algo 'tofu' means no upstream hash."""
    tried = []
    for strat in tool.get("checksum", []):
        if strat == "github-digest":
            tried.append("GitHub digest")
            if res.get("digest"):
                return "sha256", res["digest"], "GitHub sha256 digest"
        elif strat == "sf-md5":
            tried.append("SourceForge md5")
            if res.get("md5"):
                return "md5", res["md5"], "SourceForge md5 (integrity only)"
        elif strat == "tofu":
            return "tofu", None, "unverified (trust on first use)"
        elif isinstance(strat, dict) and "sha256" in strat:
            return "sha256", strat["sha256"].lower(), "pinned sha256"
        elif isinstance(strat, dict):
            if "asset" in strat:
                pat = strat["asset"].replace("{name}", re.escape(res["file"]))
                tried.append(f"release asset /{pat}/")
                hit = next((n for n in res.get("gh_assets", {}) if re.search(pat, n)), None)
                url = res["gh_assets"][hit]["browser_download_url"] if hit else None
            elif "sibling" in strat:
                tried.append(strat["sibling"])
                url = f"{res['dir_url']}/{urllib.parse.quote(strat['sibling'].format(name=res['file']))}" if res.get("dir_url") else None
            elif "url" in strat and "regex" in strat:  # a hash shown on a web page, next to the file name
                tried.append(strat["url"])
                try:
                    raw = html.unescape(http_get(strat["url"], _ua(tool)).decode("utf-8", "replace"))
                except (FileNotFoundError, RescueError):
                    continue
                text = re.sub(r"\s+", " ", re.sub(r"<[^>]+>", " ", raw))  # the page as it reads
                m = re.search(strat["regex"], text)
                if m and res["file"] in raw and len(m.group(1)) in HASH_BY_LEN:
                    algo = HASH_BY_LEN[len(m.group(1))]
                    return algo, m.group(1).lower(), f"{algo} from {urllib.parse.urlsplit(strat['url']).netloc}"
                continue
            elif "url" in strat:
                tried.append(strat["url"])
                url = strat["url"]
            else:
                raise RescueError(f"{tool['name']}: unknown checksum strategy {strat}")
            if not url:
                continue
            try:
                text = http_get(url).decode("utf-8", "replace")
            except (FileNotFoundError, RescueError):
                continue
            found = parse_checksum_text(text, res["file"])
            if found:
                return found[0], found[1], f"{found[0]} from {url.rsplit('/', 1)[-1]}"
        else:
            raise RescueError(f"{tool['name']}: unknown checksum strategy {strat!r}")
    raise RescueError(
        f"{tool['name']}: couldn't find an upstream checksum for {res['file']} "
        f"(tried: {', '.join(tried)}). Refusing to use an unverified download — add \"tofu\" "
        "to its checksum list if you accept that."
    )


# ── Lock file ─────────────────────────────────────────────────────────────
def load_lock(cfg: Config) -> dict:
    p = cfg.cache / "lock.json"
    return json.loads(p.read_text(encoding="utf-8")) if p.exists() else {}


def save_lock(cfg: Config, lock: dict) -> None:
    cfg.cache.mkdir(parents=True, exist_ok=True)
    tmp = cfg.cache / "lock.json.tmp"
    tmp.write_text(json.dumps(lock, indent=2, sort_keys=True) + "\n", encoding="utf-8")
    os.replace(tmp, cfg.cache / "lock.json")


def _safe_extract_tar(tar: tarfile.TarFile, dest: Path) -> None:
    if hasattr(tarfile, "data_filter"):
        tar.extractall(dest, filter="data")
        return
    root = dest.resolve()
    for m in tar.getmembers():
        target = (dest / m.name).resolve()
        if not str(target).startswith(str(root)) or m.issym() and os.path.isabs(m.linkname):
            raise RescueError(f"refusing unsafe path in archive: {m.name}")
    tar.extractall(dest)


def _top_dir(name: str) -> str | None:
    """First real folder of an archive member: 'ventoy-1.1.17' for both 'ventoy-1.1.17/x' and './ventoy-1.1.17/x'."""
    parts = [p for p in name.replace("\\", "/").split("/") if p not in ("", ".")]
    return parts[0] if parts else None


SAFE_NAME = re.compile(r"[a-z0-9][a-z0-9_-]*")   # tool names, so also the apps on a stick


def _safe_rel(rel: str, what: str = "path") -> str:
    """A path read from a pack, a zip or a stick, accepted only as a plain relative path:
    no root, no drive (C:, also on Linux), no '..', no ':' (NTFS streams)."""
    parts = re.split(r"[\\/]", rel) if isinstance(rel, str) else None
    if (not parts or not rel or rel[0] in "/\\" or ":" in rel or ".." in parts
            or PureWindowsPath(rel).anchor or Path(rel).is_absolute()):
        raise RescueError(f"refusing unsafe {what}: {rel!r}")
    return rel


def _inside(root: Path, rel: str, what: str = "path") -> Path:
    """root / rel for a rel read from a pack or a stick, refused unless it stays inside root."""
    dst = root / _safe_rel(rel, what)
    if not dst.resolve().is_relative_to(root.resolve()):
        raise RescueError(f"refusing {what} outside {root}: {rel!r}")
    return dst


def _safe_zip_members(zf: zipfile.ZipFile) -> list[zipfile.ZipInfo]:
    for m in zf.infolist():
        _safe_rel(m.filename, "path in zip")
    return zf.infolist()


def fetch_tool(cfg: Config, tool: dict, lock: dict, force: bool = False) -> str:
    """Fetch one tool. Returns 'new', 'current' or 'skipped'."""
    name = tool["name"]
    res = resolve(tool, cfg)
    prev = lock.get(name)

    if tool["source"] == "local":
        p: Path = res["path"]
        if not p.exists():
            lock.pop(name, None)  # file gone: drop it from the stick on the next sync
            if not tool.get("byo"):  # bring-your-own slots are simply empty until filled
                warn(f"{tool['title']}: {tool['path']} isn't built yet — skipping (see pe/README.md)")
            return "skipped"
        kind = "your own file" if tool.get("byo") else "local build"
        sha = folder_hash(p) if p.is_dir() else file_hash(p)
        if prev and prev.get("sha256") == sha:
            ok(f"{tool['title']} {res['version']} — {kind}, unchanged")
            return "current"
        lock[name] = {"version": res["version"], "file": p.name, "path": str(p), "sha256": sha,
                      "verified_by": kind, "fetched": dt.datetime.now().isoformat(timespec="seconds")}
        ok(f"{tool['title']} {res['version']} — {kind} registered")
        return "new"

    tdir = cfg.cache / name
    # final "." is what older versions recorded for Ventoy's ./-prefixed tarball: not really cached
    cached = bool(prev and prev.get("final") not in (None, "", ".") and (tdir / prev["final"]).exists())
    if not force and cached and is_current(prev, res):
        ok(f"{tool['title']} {prev['version']} — up to date")
        return "current"

    algo, want, how = expected_hash(tool, res)
    tdir.mkdir(parents=True, exist_ok=True)
    dest = tdir / res["file"]
    info(f"{tool['title']}: downloading {res['file']}")
    download(res["url"], dest)

    sha256 = file_hash(dest)
    if algo == "tofu":
        if (prev and prev.get("source_file") == res["file"] and prev.get("sha256_download")
                and prev["sha256_download"] != sha256 and res["version"] is not None
                and prev.get("version") == res["version"]):
            dest.unlink()
            raise RescueError(
                f"{tool['title']}: {res['file']} changed upstream without a version bump. That can be "
                "a silent re-release — or tampering. Check the vendor's site, then rerun with --force."
            )
    else:
        got = sha256 if algo == "sha256" else file_hash(dest, algo)
        if got != want:
            dest.unlink()
            raise RescueError(
                f"{tool['title']}: checksum MISMATCH for {res['file']} ({algo})\n"
                f"    expected {want}\n    got      {got}\n  The file was deleted. Try again; if it "
                "keeps happening, don't use it."
            )
    # SourceForge serves files, and checksum files next to them, from third-party mirrors; the
    # md5 in sourceforge.net's own feed is the independent check, so it must agree as well.
    if res.get("md5") and algo != "md5":
        got = file_hash(dest, "md5")
        if got != res["md5"].lower():
            dest.unlink()
            raise RescueError(
                f"{tool['title']}: {res['file']} doesn't match the md5 SourceForge publishes for it\n"
                f"    expected {res['md5'].lower()}\n    got      {got}\n  The file was deleted: a download "
                "mirror may have served a changed file. Try again later."
            )
        how += " + SourceForge md5"

    version = res["version"]
    if version is None:  # unversioned url source: version by content
        version = (prev["version"] if prev and prev.get("sha256_download") == sha256
                   else f"{dt.date.today().isoformat()}-{sha256[:8]}")

    final = res["file"]
    if tool.get("extract"):
        with zipfile.ZipFile(dest) as zf:
            members = [m for m in _safe_zip_members(zf) if re.search(tool["extract"], m.filename)]
            if not members:
                raise RescueError(f"{tool['title']}: nothing in {res['file']} matches {tool['extract']}")
            m = members[0]
            final = Path(m.filename).name
            with zf.open(m) as s, open(tdir / final, "wb") as d:
                shutil.copyfileobj(s, d)
    elif tool["kind"] == "ventoy" and zipfile.is_zipfile(dest):  # the Windows package
        with zipfile.ZipFile(dest) as zf:
            members = _safe_zip_members(zf)
            top = {t for t in map(_top_dir, (m.filename for m in members)) if t}
            zf.extractall(tdir, members=members)
        if len(top) != 1:
            raise RescueError(f"unexpected Ventoy archive layout: {sorted(top)}")
        final = top.pop()
    elif tool["kind"] == "tree":  # e.g. a PortableApps.com .paf.exe (NSIS): only 7-Zip opens those
        seven = shutil.which("7z") or shutil.which("7za") or shutil.which("7zz")
        if not seven:
            dest.unlink(missing_ok=True)
            raise RescueError(f"{tool['title']}: unpacking needs 7-Zip. Install it (e.g. sudo pacman -S 7zip) and fetch again.")
        final = f"tree-{re.sub(r'[^A-Za-z0-9._-]', '_', res['version'] or 'x')}"
        out = tdir / final
        shutil.rmtree(out, ignore_errors=True)
        r = subprocess.run([seven, "x", "-y", f"-o{out}", str(dest)], capture_output=True, text=True)
        if r.returncode:
            raise RescueError(f"{tool['title']}: 7-Zip couldn't unpack {res['file']}: {r.stderr.strip() or r.stdout[-300:]}")
        for f in sorted(out.rglob("*"), key=lambda f: -len(f.parts)):
            rel = f.relative_to(out).as_posix()
            if any(re.search(pat, rel) for pat in tool.get("drop", [])):
                shutil.rmtree(f) if f.is_dir() else f.unlink(missing_ok=True)
        if not (out / tool["once"]).exists():
            raise RescueError(f"{tool['title']}: {tool['once']} isn't in {res['file']}; the layout has changed")
    elif tool["kind"] == "ventoy":
        with tarfile.open(dest) as tar:
            top = {t for t in map(_top_dir, tar.getnames()) if t}  # Ventoy's tarball says ./ventoy-x/…
            _safe_extract_tar(tar, tdir)
        if len(top) != 1:
            raise RescueError(f"unexpected Ventoy archive layout: {sorted(top)}")
        final = top.pop()

    keep = {res["file"], final}
    for old in tdir.iterdir():
        if old.name not in keep and not old.name.endswith(".part"):
            shutil.rmtree(old) if old.is_dir() else old.unlink()

    lock[name] = {
        "version": version,
        "source_file": res["file"],
        "final": final,
        "sha256_download": sha256,
        "sha256": file_hash(tdir / final) if (tdir / final).is_file() else None,
        "verified_by": how,
        "url": res["url"],
        "remote_id": res.get("remote_id"),
        "fetched": dt.datetime.now().isoformat(timespec="seconds"),
    }
    marker = f"{C.Y}unverified{C.X}" if algo == "tofu" else f"{C.D}{how}{C.X}"
    ok(f"{tool['title']} {version} — {marker}")
    return "new"


# ── Commands ──────────────────────────────────────────────────────────────
def cmd_list(cfg: Config, args) -> int:
    rows = [("NAME", "KIND", "CATEGORY", "SOURCE", "ON")]
    for t in cfg.tools:
        cat = cfg.categories.get(t.get("category"), {}).get("title", "—")
        src = t.get("repo") or t.get("project") or t.get("url") or t.get("page") or t.get("path")
        rows.append((t["name"], t["kind"], cat, f"{t['source']}:{src}"[:52],
                     "yes" if t.get("enabled", True) else "no"))
    w = [max(len(r[i]) for r in rows) for i in range(5)]
    for i, r in enumerate(rows):
        line = "  ".join(c.ljust(w[j]) for j, c in enumerate(r))
        print(f"{C.B}{line}{C.X}" if i == 0 else line)
    return 0


def cmd_check(cfg: Config, args) -> int:
    lock = load_lock(cfg)
    out, updates, errors = {}, 0, 0
    for t in cfg.enabled(args.tools):
        try:
            res = resolve(t, cfg)
        except RescueError as e:
            errors += 1
            out[t["name"]] = {"error": str(e)}
            if not args.json:
                bad(f"{t['title']}: {e}")
            continue
        prev = lock.get(t["name"])
        have = prev.get("version") if prev else None
        latest = res["version"] or "unversioned download"
        if t["source"] == "local":
            hint = f"put your {'ISO' if t['kind'] == 'iso' else 'file'} at {t['path']}" if t.get("byo") else f"{t['path']} missing — see pe/README.md"
            latest = res["version"] or hint
            status = ("not provided" if t.get("byo") else "not built") if not res["version"] \
                else "up to date" if prev and prev.get("path") else "not fetched"
        else:
            status = "not fetched" if not have else "up to date" if is_current(prev, res) else "update"
        updates += status in ("update", "not fetched")
        out[t["name"]] = {"latest": res["version"], "file": res["file"], "have": have, "status": status}
        if not args.json:
            mark = {"up to date": ok, "update": warn, "not fetched": warn}.get(status, info)
            mark(f"{t['title']}: {status}  ({have or '—'} → {latest})" if status == "update"
                 else f"{t['title']}: {status}  ({latest})")
    if args.json:
        print(json.dumps(out, indent=2, sort_keys=True))
    elif not errors:
        print(f"\n{updates} to fetch." if updates else "\nEverything is current.")
    return 1 if errors else 0


UPDATES_FILE = "updates.json"      # in the cache: the last look upstream, for the Windows app


def tool_updates(cfg: Config, max_age: float = 6 * 3600, refresh: bool = False) -> dict:
    """Which tools have a newer release than this PC has fetched, for the app to mention.
    Looks upstream at most every max_age seconds (each look costs GitHub API calls, of which an
    unsigned-in PC gets 60 an hour); in between, compares the last look with what's been fetched."""
    path = cfg.cache / UPDATES_FILE
    try:
        saved = json.loads(path.read_text(encoding="utf-8"))
        age = time.time() - saved["at"]
    except (OSError, ValueError, KeyError, TypeError):
        saved, age = None, max_age
    if refresh or not saved or not 0 <= age < max_age:
        latest, failed = {}, 0
        for t in cfg.enabled([]):
            if t["source"] == "local":
                continue
            try:
                res = resolve(t, cfg)
            except RescueError:
                failed += 1
                continue
            latest[t["name"]] = {"version": res["version"], "file": res["file"], "remote_id": res.get("remote_id")}
        saved = {"at": time.time(), "latest": latest, "failed": failed}
        cfg.cache.mkdir(parents=True, exist_ok=True)
        path.write_text(json.dumps(saved, indent=1) + "\n", encoding="utf-8")
    lock, titles = load_lock(cfg), {t["name"]: t["title"] for t in cfg.enabled([])}
    newer = [{"name": n, "title": titles[n], "have": lock[n].get("version"), "latest": res["version"]}
             for n, res in sorted(saved["latest"].items(), key=lambda kv: titles.get(kv[0], "").lower())
             if n in titles and lock.get(n) and not is_current(lock[n], res)]
    return {"checked": dt.datetime.fromtimestamp(saved["at"]).isoformat(timespec="minutes"), "newer": newer,
            "failed": saved["failed"], "fetched": sum(n in lock for n in titles)}


def updates_text(found: dict) -> str:
    """One line about tool_updates, for the app's window."""
    if not found["fetched"]:
        return "Nothing is downloaded on this PC yet: Install or Update gets the latest of every tool."
    n = len(found["newer"])
    when = found["checked"].replace("T", " ")
    if not n:
        return f"Every tool is at its latest version (checked {when})." + \
            (f" {found['failed']} couldn't be checked." if found["failed"] else "")
    names = ", ".join(u["title"] for u in found["newer"][:4]) + (f" and {n - 4} more" if n > 4 else "")
    return f"Newer versions of {n} tool(s) are out: {names}. Update stick gets them (checked {when})."


def cmd_fetch(cfg: Config, args) -> int:
    lock = load_lock(cfg)
    tools = cfg.enabled(args.tools)
    head(f"Fetching {len(tools)} tool(s) into {cfg.cache}")
    failed = []
    for t in tools:
        try:
            fetch_tool(cfg, t, lock, force=args.force)
        except RescueError as e:
            bad(str(e))
            failed.append(t["name"])
        finally:
            save_lock(cfg, lock)
    if failed:
        bad(f"{len(failed)} failed: {', '.join(failed)}")
        return 1
    ok("All fetched and verified.")
    return 0


def _label_of(mount: Path) -> str | None:
    if os.name == "nt":
        import ctypes
        buf = ctypes.create_unicode_buffer(261)
        ok = ctypes.windll.kernel32.GetVolumeInformationW(str(mount.anchor), buf, 261, None, None, None, None, 0)
        return (buf.value or None) if ok else None
    try:
        src = subprocess.run(["findmnt", "-no", "SOURCE", "--target", str(mount)],
                             capture_output=True, text=True, check=True).stdout.strip()
        if not src.startswith("/dev/"):
            return None
        return subprocess.run(["lsblk", "-no", "LABEL", src], capture_output=True, text=True,
                              check=True).stdout.strip() or None
    except (OSError, subprocess.CalledProcessError):
        return None


def _png_size(path: Path) -> tuple[int, int] | None:
    """(width, height) from a PNG's header, or None if it isn't one."""
    try:
        with open(path, "rb") as f:
            head = f.read(24)
    except OSError:
        return None
    if head[:8] != b"\x89PNG\r\n\x1a\n" or head[12:16] != b"IHDR":
        return None
    return struct.unpack(">II", head[16:24])


def _icons(cfg: Config) -> set[str]:
    """Icon names available on the stick: the theme's own plus yours from byo/icons/."""
    theme = cfg.settings.get("theme")
    dirs = [cfg.assets / theme / "icons"] if theme else []
    return {f.stem for d in dirs + [cfg.repo / "byo" / "icons"] if d.is_dir() for f in d.glob("*.png")}


def _pack_icons(cfg: Config) -> set[str]:
    """Icon names in any icon pack (theme/icon-packs/<id>/, byo/icon-packs/<id>/)."""
    theme = cfg.settings.get("theme")
    roots = ([cfg.assets / theme / "icon-packs"] if theme else []) + [cfg.repo / "byo" / "icon-packs"]
    return {f.stem for r in roots if r.is_dir() for f in r.glob("*/*.png")}


def build_ventoy_json(cfg: Config, placed: list[dict], icons: set[str] = frozenset()) -> dict:
    alias, tips, classes, keys = [], [], [], []
    used = {p["category"] for p in placed} | {cid for cid, c in cfg.categories.items() if c.get("user")}
    for cid, c in cfg.categories.items():
        if cid in used:
            path = f"/{cfg.iso_root}/{c['dir']}"
            alias.append({"dir": path, "alias": f"{c['title']}  \u2192"})
            if c.get("description"):
                tips.append({"dir": path, "tip": c["description"]})
            if f"cat-{cid}" in icons:
                classes.append({"dir": path, "class": f"cat-{cid}"})
    for p in placed:
        img = f"/{cfg.iso_root}/{cfg.categories[p['category']]['dir']}/{p['file']}"
        only = {frozenset({"bios"}): "  [BIOS]", frozenset({"uefi"}): "  [UEFI]"}.get(frozenset(p.get("modes") or ()), "")
        alias.append({"image": img, "alias": f"{p['title']}{only}"})  # versions: `helix list` / `check`
        if p.get("description"):
            tips.append({"image": img, "tip": p["description"]})
        # Ventoy matches "key" as a substring that must be shorter than the file name, so
        # use the name without its extension; longest first, so one never shadows another.
        stem = p["file"].rsplit(".", 1)[0]
        if p.get("name") in icons and stem:
            keys.append({"key": stem, "class": p["name"]})
    classes += sorted(keys, key=lambda k: -len(k["key"]))
    doc: dict = {
        "control": [
            {"VTOY_DEFAULT_MENU_MODE": "1"},            # tree view: categories as folders
            {"VTOY_DEFAULT_SEARCH_ROOT": f"/{cfg.iso_root}"},
            {"VTOY_FILT_DOT_UNDERSCORE_FILE": "1"},
            {"VTOY_TREE_VIEW_MENU_STYLE": "1"},
        ],
        "menu_alias": alias,
    }
    if classes:
        doc["menu_class"] = classes
    theme = cfg.settings.get("theme")
    theme_dir = cfg.assets / theme if theme else None
    if tips:
        themed = theme_dir and theme_dir.is_dir()
        doc["menu_tip"] = {"left": "5%" if themed else "10%",
                           "top": "82%" if themed else "80%", "tips": tips,
                           "color": "#baabd3" if themed else "#7fb4ff"}
    if theme_dir and theme_dir.is_dir():
        doc["theme"] = {
            "file": "/ventoy/theme/theme.txt",
            "gfxmode": "1920x1080",
            "resolution_fit": 1,         # fall back to the screen's own mode if 1080p isn't offered
            "ventoy_left": "78%",
            "ventoy_top": "94%",
            "ventoy_color": "#baabd3",
            "fonts": [f"/ventoy/theme/{f.relative_to(theme_dir).as_posix()}"     # a preset may bring its own
                      for f in sorted(theme_dir.rglob("*.pf2")) if f.relative_to(theme_dir).parts[0] != "presets"],
        }
    return doc


def _flush_volume(mnt: Path) -> None:
    """Push everything written to the stick out of the OS cache."""
    if hasattr(os, "sync"):  # Linux / macOS
        os.sync()
        return
    if os.name == "nt":  # FlushFileBuffers on the volume (needs admin, which the Windows app has)
        try:
            import ctypes
            k32 = ctypes.windll.kernel32
            k32.CreateFileW.restype = ctypes.c_void_p
            h = k32.CreateFileW(f"\\\\.\\{mnt.drive}", 0x40000000, 0x3, None, 3, 0, None)
            if h not in (None, ctypes.c_void_p(-1).value):
                k32.FlushFileBuffers(ctypes.c_void_p(h))
                k32.CloseHandle(ctypes.c_void_p(h))
        except (OSError, AttributeError):
            pass  # files are fsynced as they're written; this is belt and braces


FLUSH_EVERY = 256 << 20  # fsync this often while copying, so progress tracks what's really on the stick


def _copy(src: Path, dst: Path, progress: Progress | None = None) -> None:
    dst.parent.mkdir(parents=True, exist_ok=True)
    tmp = dst.with_name(dst.name + ".part")
    with open(src, "rb") as s, open(tmp, "wb") as d:
        since = 0
        while chunk := s.read(8 << 20):
            d.write(chunk)
            since += len(chunk)
            if since >= FLUSH_EVERY:
                d.flush()
                os.fsync(d.fileno())
                since = 0
            if progress:
                progress.add(len(chunk))
        d.flush()
        os.fsync(d.fileno())
    os.replace(tmp, dst)


def _iso_has_file(f, want: list[str]) -> bool:
    """Is want (e.g. ["EFI", "BOOT", "BOOTX64.EFI"]) in the ISO 9660 filesystem open as f?"""
    f.seek(16 * 2048)
    pvd = f.read(2048)
    if pvd[0] != 1 or pvd[1:6] != b"CD001":
        return False
    lba, size = int.from_bytes(pvd[158:162], "little"), int.from_bytes(pvd[166:170], "little")
    for depth, part in enumerate(want):
        f.seek(lba * 2048)
        data, found = f.read(min(size, 1 << 20)), None
        i = 0
        while i < len(data):
            n = data[i]
            if n == 0:  # records never cross a sector: skip to the next one
                i = (i // 2048 + 1) * 2048
                continue
            name = data[i + 33:i + 33 + data[i + 32]].decode("ascii", "replace").split(";")[0].rstrip(".")
            if name.upper() == part.upper() and bool(data[i + 25] & 2) == (depth < len(want) - 1):
                found = (int.from_bytes(data[i + 2:i + 6], "little"), int.from_bytes(data[i + 10:i + 14], "little"))
                break
            i += n
        if not found:
            return False
        lba, size = found
    return True


def _boot_modes(path: Path) -> set[str] | None:
    """Which firmware can start this ISO: {"bios"}, {"uefi"} or both. None when it can't be
    told (not an ISO, no El Torito record), so a tool never gets a wrong label."""
    if path.suffix.lower() != ".iso":
        return None
    try:
        with open(path, "rb") as f:
            f.seek(17 * 2048)
            brvd = f.read(2048)
            if brvd[0] != 0 or brvd[1:6] != b"CD001" or not brvd[7:30].startswith(b"EL TORITO SPECIFICATION"):
                return None
            f.seek(int.from_bytes(brvd[0x47:0x4B], "little") * 2048)
            cat = f.read(2048)
            if cat[0] != 1:
                return None
            platforms = {cat[1]} if cat[32] == 0x88 else set()   # validation + default entry
            i = 64
            while i + 32 <= len(cat) and cat[i] in (0x90, 0x91):  # section headers
                plat, count, last = cat[i + 1], int.from_bytes(cat[i + 2:i + 4], "little"), cat[i] == 0x91
                i += 32
                for _ in range(count):
                    if i + 32 > len(cat):
                        break
                    if cat[i] == 0x88:
                        platforms.add(plat)
                    i += 32
                    while i + 32 <= len(cat) and cat[i] == 0x44:  # extension records
                        i += 32
                if last:
                    break
            modes = {"bios"} if 0 in platforms else set()
            if 0xEF in platforms or _iso_has_file(f, ["EFI", "BOOT", "BOOTX64.EFI"]):
                modes.add("uefi")
            return modes or None
    except (OSError, IndexError):
        return None


VENTOY_MODES = {"wimboot": "_VTWIMBOOT", "grub2": "_VTGRUB2", "memdisk": "_VTMEMDISK"}


def _stick_name(file: str, mode: str | None) -> str:
    """The file's name on the stick. Ventoy boots a file whose name ends in _VTWIMBOOT,
    _VTGRUB2 or _VTMEMDISK (before the extension) in that mode, with no key press."""
    if not mode:
        return file
    stem, dot, ext = file.rpartition(".")
    return f"{stem}{VENTOY_MODES[mode]}.{ext}" if dot else file + VENTOY_MODES[mode]


def _plan(cfg: Config, lock: dict) -> tuple[list[dict], list[tuple], list[str]]:
    """What belongs on the stick: (boot images, apps, titles of tools not fetched yet)."""
    placed, missing = [], []
    for t in cfg.enabled(kinds={"iso"}):
        entry = lock.get(t["name"])
        if not entry and t.get("byo"):  # an empty bring-your-own slot isn't "missing"
            continue
        src = (Path(entry["path"]) if entry and entry.get("path")
               else cfg.cache / t["name"] / entry["final"] if entry else None)
        if not src or not src.exists():
            missing.append(t["title"])
            continue
        name = _stick_name(src.name, t.get("ventoy_mode"))
        rel = f"{cfg.iso_root}/{cfg.categories[t['category']]['dir']}/{name}"
        placed.append({"rel": rel, "src": src, "file": name, "title": t["title"], "name": t["name"],
                       "version": entry["version"], "category": t["category"],
                       "description": t.get("description"), "sha256": entry.get("sha256"),
                       "local": t["source"] == "local", "modes": _boot_modes(src)})
    apps = []
    for t in cfg.enabled(kinds={"app"}):
        entry = lock.get(t["name"])
        if not entry:
            if not t.get("byo"):  # an empty bring-your-own slot isn't "missing"
                missing.append(t["title"])
            continue
        # Downloaded apps live in the cache; local / bring-your-own ones where you keep them
        src = Path(entry["path"]) if entry.get("path") else cfg.cache / t["name"] / entry["final"]
        if not src.exists():
            missing.append(t["title"])
            continue
        apps.append((t, entry, src))
    return placed, apps, missing


def _app_root(cfg: Config, t: dict) -> str:
    """The stick folder an app goes in: Apps, or Mac for `platform = "mac"` (tools to run on a
    working Mac; they stay as downloaded, since an unpacked .app doesn't survive exFAT)."""
    return cfg.mac_root if t.get("platform") == "mac" else cfg.apps_root


STICK_README = """Helix Boot: update this stick, or change how its boot menu looks, from any PC
============================================================================

Windows:  run HelixBoot.exe in this folder (it asks for admin rights).
          Pick the stick, then Update stick, Look... for themes and icons, or
          Check stick to find damaged files.
Linux:    bash HelixBoot.sh        (in a terminal, in this folder)
          It shows a menu: update the stick, change its look, check it.

Updating from here keeps every tool already on the stick, including ones this
PC has no copy of. Install ERASES whatever stick you pick: don't use it on this one.

Your own settings (local.toml) and tools (byo/) go beside the app you run. To
use the ones you already have, run Helix Boot from the folder that holds them.
https://github.com/Commanderx-code/helix-boot
"""


def _mac_readme(cfg: Config, apps: list[tuple]) -> bytes | None:
    """Mac/README.txt: what each Mac tool is, and how to open it."""
    mac = [(t, src) for t, _, src in apps if t.get("platform") == "mac"]
    if not mac:
        return None
    lines = ["Helix Boot: tools for a Mac", "===========================", "",
             "These run on a working Mac; nothing here boots one. Copy a tool's folder to the Mac",
             "first (the Desktop will do), then open the file in it: a .dmg or .pkg opens with a",
             "double-click, a .zip unpacks to the app. If macOS won't open an app because it can't",
             "check its developer, allow it under System Settings > Privacy & Security (Open Anyway);",
             "on macOS 14 and older, right-clicking the app and choosing Open does the same.", ""]
    for t, src in sorted(mac, key=lambda ts: ts[0]["title"].lower()):
        lines += [f"{t['title']}", f"    {t['name']}/{src.name}"]
        lines += [f"    {t['description']}"] if t.get("description") else []
        lines += [""]
    return "\n".join(lines).encode("utf-8")


def _trees(cfg: Config, lock: dict) -> list[tuple[dict, dict, Path]]:
    """Fetched `kind = "tree"` tools: (tool, lock entry, folder). A local tree is a folder as is."""
    out = []
    for t in cfg.enabled(kinds={"tree"}):
        entry = lock.get(t["name"])
        src = (Path(entry["path"]) if entry and entry.get("path")
               else cfg.cache / t["name"] / entry["final"] if entry and entry.get("final") else None)
        if src and src.is_dir():
            out.append((t, entry, src))
        else:
            warn(f"{t['title']}: not fetched yet — run `helix fetch` (skipping)")
    return out


PA_MARK = b"Helix Boot: restyled"     # in every image we write, so a patched file is recognised
PA_MARKS = (b"Helix Boot:", b"Commander Rescue:")      # this one and the one from before the rename


def _png_chunk(kind: bytes, data: bytes) -> bytes:
    return struct.pack(">I", len(data)) + kind + data + struct.pack(">I", zlib.crc32(kind + data) & 0xFFFFFFFF)


def _png_encode(width: int, height: int, rgba: bytes) -> bytes:
    rows = b"".join(b"\0" + rgba[y * width * 4:(y + 1) * width * 4] for y in range(height))
    return (b"\x89PNG\r\n\x1a\n" + _png_chunk(b"IHDR", struct.pack(">IIBBBBB", width, height, 8, 6, 0, 0, 0))
            + _png_chunk(b"IDAT", zlib.compress(rows, 9)) + _png_chunk(b"IEND", b""))


def _png_decode(png: bytes) -> tuple[int, int, bytearray] | None:
    """8-bit RGBA, non-interlaced PNG to (width, height, pixels); None for anything else."""
    i, idat, head = 8, b"", None
    while i + 8 <= len(png):
        n, kind = struct.unpack(">I4s", png[i:i + 8])
        if kind == b"IHDR":
            head = struct.unpack(">IIBBBBB", png[i + 8:i + 21])
        elif kind == b"IDAT":
            idat += png[i + 8:i + 8 + n]
        i += 12 + n
    if not head or head[2:5] != (8, 6, 0) or head[6] != 0:
        return None
    w, h = head[0], head[1]
    raw, stride, out = zlib.decompress(idat), w * 4, bytearray()
    prev = bytearray(stride)
    for y in range(h):
        ftype, line = raw[y * (stride + 1)], bytearray(raw[y * (stride + 1) + 1:(y + 1) * (stride + 1)])
        for x in range(stride):
            a = line[x - 4] if x >= 4 else 0
            b, c = prev[x], prev[x - 4] if x >= 4 else 0
            if ftype == 1:
                line[x] = (line[x] + a) & 255
            elif ftype == 2:
                line[x] = (line[x] + b) & 255
            elif ftype == 3:
                line[x] = (line[x] + (a + b) // 2) & 255
            elif ftype == 4:
                pa, pb, pc = abs(b - c), abs(a - c), abs(a + b - 2 * c)
                line[x] = (line[x] + (a if pa <= pb and pa <= pc else b if pb <= pc else c)) & 255
        out += line
        prev = line
    return w, h, out


def _pad_png(png: bytes, size: int) -> bytes | None:
    """png grown to exactly `size` bytes with a text chunk carrying PA_MARK, or None if too big."""
    text = b"Comment\0" + PA_MARK
    room = size - len(png) - 12                              # 12: a chunk's length, type and CRC
    if room < len(text):
        return None
    iend = len(png) - 12
    return png[:iend] + _png_chunk(b"tEXt", text + b" " * (room - len(text))) + png[iend:]


def _restyle_platform(exe: Path, backup: Path, recolor: dict | None = None) -> str:
    """Restyle the Platform's built-in images so themes look their own: the PortableApps.com
    logos it draws over the menu's bottom-right corner (imgPortableAppsLogo, and the white
    imgPortableAppsLogo2 for dark themes) become transparent, and each image named in
    `recolor` (e.g. imgLiveSearchIcon, the search box's magnifier) takes that colour, keeping
    its shape. They're PNGs in the main window's form data; each is rewritten at exactly its
    old byte length, so nothing else in the program moves. Returns 'patched', 'already' or
    why it couldn't."""
    if not exe.is_file():
        return "no Platform"
    orig = exe.read_bytes()
    slots: dict[str, tuple[int, int]] = {}
    for m in re.finditer(rb"\x06TImage[\x03-\x30]([A-Za-z0-9_]+)", orig):
        j = orig.find(b"\tTPngImage\x89PNG\r\n\x1a\n", m.end(), m.end() + 600)
        if j != -1:
            start = j + len(b"\tTPngImage")
            slots.setdefault(m.group(1).decode(), (start, orig.find(b"IEND", start) + 8))
    logos = [n for n in slots if re.fullmatch(r"imgPortableAppsLogo\d*", n)]
    if not logos:
        return "logo not found; the Platform has changed"
    wanted = {n: None for n in logos} | {n: c for n, c in (recolor or {}).items() if n in slots}
    data, changed = bytearray(orig), False
    for name, colour in wanted.items():
        start, stop = slots[name]
        now = bytes(data[start:stop])
        if colour is None:
            w, h = struct.unpack(">II", now[16:24])
            new = _pad_png(_png_encode(w, h, bytes(w * h * 4)), stop - start)
        else:
            img = _png_decode(now)
            if img is None:
                return f"{name} isn't a plain RGBA PNG"
            w, h, px = img
            r, g, b = (int(colour[i:i + 2], 16) for i in (0, 2, 4))
            for i in range(0, len(px), 4):
                px[i:i + 3] = bytes((r, g, b))
            new = _pad_png(_png_encode(w, h, bytes(px)), stop - start)
        if new is None:
            return f"{name} has no room for the change"
        if new != now:
            data[start:stop] = new
            changed = True
    missing = sorted(set(recolor or {}) - set(slots))
    if not changed:
        return "already"
    if not any(mark in orig for mark in PA_MARKS):           # keep the untouched original, not a patched one
        backup.parent.mkdir(parents=True, exist_ok=True)
        shutil.copy2(exe, backup)
    tmp = exe.with_name(exe.name + ".part")
    tmp.write_bytes(bytes(data))
    shutil.copystat(exe, tmp)
    os.replace(tmp, exe)                                     # a running copy keeps the old file
    return "patched" + (f" (not found: {', '.join(missing)})" if missing else "")


def _tree_patches(t: dict, base: Path, dry_run: bool) -> None:
    rel = t.get("hide_logo")
    if not rel or dry_run:
        return
    exe = base / rel
    result = _restyle_platform(exe, exe.parent / "Data" / (exe.name + ".original"), t.get("recolor"))
    if result.startswith("patched"):
        ok(f"{t['title']}: restyled (logo hidden{', icons recoloured' if t.get('recolor') else ''}; original kept in Data)"
           + result[len("patched"):])
    elif result not in ("already", "no Platform"):
        warn(f"{t['title']}: couldn't restyle it: {result}")


def _tree_files(src: Path) -> list[tuple[str, Path]]:
    return [(f.relative_to(src).as_posix(), f) for f in sorted(src.rglob("*")) if f.is_file()]


def _stick_extras(cfg: Config, placed: list[dict], apps: list[tuple]) -> list[tuple[str, Path | bytes]]:
    """The small files that go with the boot images: app launcher, theme, boot menu and
    `kind = "file"` tools such as Ventoy's wimboot plugin."""
    out: list[tuple[str, Path | bytes]] = []
    for c in cfg.categories.values():   # your own folders: a note in each, and a new stick has them too
        if c.get("user"):
            out.append((f"{cfg.iso_root}/{c['dir']}/HELIX-BOOT.txt", (
                f"{c['title']}: {c.get('description', '')}\r\n\r\n"
                "Put bootable images (.iso, .wim, .img, .vhd) here. The folder shows up in the\r\n"
                "boot menu as soon as it holds one; until then it stays hidden. Helix Boot never\r\n"
                "changes or removes anything in it except this note.\r\n").encode("utf-8")))
    lock = load_lock(cfg)
    for t in cfg.enabled(kinds={"file"}):
        entry = lock.get(t["name"])
        src = (Path(entry["path"]) if entry and entry.get("path")
               else cfg.cache / t["name"] / entry["final"] if entry else None)
        if src and src.is_file():
            out.append((t["dest"], src))
        elif src and src.is_dir():  # a local folder: its files go under dest, replacing older copies
            out += [(f"{t['dest']}/{f.relative_to(src).as_posix()}", f)
                    for f in sorted(src.rglob("*")) if f.is_file()]
        else:
            warn(f"{t['title']}: not fetched yet — run `helix fetch` (skipping)")
    # PE launcher index: "Title|relative\path\to.exe|description" per line (easy to parse from
    # cmd.exe, which reads the first two; the Lazarus launcher shows the description too)
    lines = [f"{t['title']}|{t['name']}\\{t.get('entry', '').replace('/', chr(92))}|"
             + " ".join(t.get("description", "").replace("|", "/").split())
             for t, _, _ in apps if t.get("entry")]
    out.append((f"{cfg.apps_root}/apps.txt", ("\r\n".join(lines) + "\r\n").encode("utf-8")))
    readme = _mac_readme(cfg, apps)
    if readme:
        out.append((f"{cfg.mac_root}/README.txt", readme))
    own = {rel.rpartition("/")[0] for rel, _ in out if rel.endswith(("/HelixBoot.exe", "/HelixBoot.sh"))}
    for folder in sorted(own):          # the apps on the stick itself: say what they are
        out.append((f"{folder}/README.txt", STICK_README.encode("utf-8")))
    launcher = cfg.assets / "pe" / "launcher"
    if launcher.is_dir():  # works from any WinPE, including Hiren's
        out += [(f"{cfg.apps_root}/{f.name}", f) for f in sorted(launcher.iterdir())
                if f.suffix.lower() in (".cmd", ".ps1")]
    lazarus = cfg.assets / "pe" / "lazarus"
    if lazarus.is_dir():  # the Lazarus launcher: Lazarus PE opens it at startup (Apps\LazarusStartup.cmd)
        out += [(f"{cfg.apps_root}/Lazarus/{f.name}", f) for f in sorted(lazarus.iterdir())
                if f.is_file() and f.suffix.lower() != ".md"]
    theme_src = cfg.assets / cfg.settings["theme"] if cfg.settings.get("theme") else None
    if theme_src and theme_src.is_dir():
        files: dict[str, Path | bytes] = {
            f.relative_to(theme_src).as_posix(): f for f in sorted(theme_src.rglob("*"))
            if f.is_file() and f.suffix not in (".py", ".pyc") and "__pycache__" not in f.parts}
        mine = cfg.repo / "byo" / "icons"      # your own icons win over the theme's and a preset's
        if mine.is_dir():
            files.update({f"mine/icons/{f.name}": f for f in sorted(mine.glob("*.png"))})
            big = [(f.name, *wh) for f in sorted(mine.glob("*.png")) if (wh := _png_size(f)) and max(wh) > 128]
            if big:   # GRUB decodes each icon at full size: big ones use up its memory, later ones vanish
                name, w, h = big[0]
                warn(f"{len(big)} of your icons in byo/icons/ are much bigger than the 40x40 Ventoy shows "
                     f"(e.g. {name}, {w}x{h}); at boot that can stop other icons appearing. "
                     "Shrink them with: theme/build-theme.py --fit-icons")
        packs = cfg.repo / "byo" / "icon-packs"           # your own icon packs, beside the theme's
        if packs.is_dir():
            files.update({f"icon-packs/{f.relative_to(packs).as_posix()}": f for f in sorted(packs.glob("*/*"))
                          if f.is_file() and f.suffix in (".png", ".toml")})
        if (cfg.repo / "byo" / "splash.png").is_file():   # your own picture before the menu
            files["mine/splash.png"] = cfg.repo / "byo" / "splash.png"
        splash = files.get("mine/splash.png") or files.get("splash.png")
        bar = SPLASH_BAR if "mine/splash.png" in files else _preset_meta(theme_src)["bar"]
        frames = _splash_frames(cfg, splash, bar) if splash else None
        if frames:   # its loading bar, ready-made: a PC without Pillow (a pack on Windows) still shows it
            files.update({f"splash/{f.name}": f for f in sorted(frames.glob("*.jpg"))})
            files["splash/for.txt"] = frames.name.encode()
        out += [(f"{THEME_SRC}/{rel}", f) for rel, f in files.items()]
    icons = _icons(cfg) if theme_src and theme_src.is_dir() else set()
    bare = [p["title"] for p in placed if icons and p["name"] not in icons]
    if bare:
        info(f"no menu icon for {', '.join(bare)}: `theme/build-theme.py --local` makes letter badges")
    # Ventoy reads UTF-8 but not \u escapes, so write non-ASCII (→, ü …) as is
    # the menu with every icon the stick could show; _apply_look keeps those its look has
    packs = _pack_icons(cfg) if icons else set()
    vjson = json.dumps(build_ventoy_json(cfg, placed, icons | packs), indent=2, ensure_ascii=False) + "\n"
    out.append((BASE_JSON, vjson.encode("utf-8")))
    return out


def _beside_vtoyefi(mnt: Path) -> bool:
    """Is mnt on a disk that also has Ventoy's own VTOYEFI partition? (Linux; elsewhere the
    caller checks, as the Windows app does.) That is a Ventoy stick whatever its name."""
    if os.name == "nt" or not shutil.which("lsblk") or not shutil.which("findmnt"):
        return False
    try:
        run = lambda *cmd: subprocess.run(cmd, capture_output=True, text=True, check=True).stdout   # noqa: E731
        src = run("findmnt", "-no", "SOURCE", "--target", str(mnt)).strip().split("[")[0]
        disk = run("lsblk", "-no", "PKNAME", src).split()
        return bool(disk) and "VTOYEFI" in run("lsblk", "-lno", "LABEL", f"/dev/{disk[0]}").split()
    except (OSError, subprocess.CalledProcessError):
        return False


def _open_stick(mnt: Path, init: bool, cfg: Config | None = None) -> tuple[Path, dict]:
    """Check the target is a Ventoy stick (or one we've filled before); return its state."""
    if not mnt.is_dir():
        raise RescueError(f"{mnt} isn't a mounted folder. Plug the stick in and pass its mount point.")
    state_dir = mnt / STATE_DIR
    if not state_dir.exists() and (mnt / OLD_STATE_DIR).is_dir():
        os.rename(mnt / OLD_STATE_DIR, state_dir)          # a stick from before the rename to Helix Boot
    if not state_dir.exists():
        label = _label_of(mnt)
        names = {"Ventoy", STICK_LABEL} | ({cfg.stick_label} if cfg else set())
        if not init and label not in names and not _beside_vtoyefi(mnt):
            raise RescueError(
                f"{mnt} doesn't look like a Ventoy stick (label: {label or 'unknown'}). "
                "If you're sure, rerun with --init."
            )
    state_path = state_dir / "state.json"
    return state_dir, json.loads(state_path.read_text(encoding="utf-8")) if state_path.exists() else {}


def _stale_split(state: dict, stale: list[str], placed: dict[str, str | None], off: set[str], me: str,
                 everything: bool, versioned: set[str] = frozenset()) -> tuple[list[str], list[str]]:
    """Which of the images this project put on the stick, and this run doesn't want, to remove
    and which to keep. One goes when this run brought the same tool again (a newer version, or
    the same file in another folder), when its tool is switched off here, or when this PC put it
    there itself and no longer has it. The rest are another PC's (its own tools, or one whose
    download failed here): they stay, so updating from a second PC doesn't strip the stick.
    `placed` is this run's images, stick path to tool name; `me` this PC; `everything` removes all;
    `versioned` the placed paths whose file is a download named after its version."""
    if everything:
        return list(stale), []
    tools, names = state.get("tools") or {}, {n for n in placed.values() if n}
    by = state.get("by") or {}

    def shape(rel: str) -> tuple[str, str]:        # its folder, and its name but for the numbers
        folder, _, name = rel.rpartition("/")
        return folder, re.sub(r"\d+", "#", name)

    # A stick from before tools were recorded: a stale file is an older download of a tool placed
    # now when it sits in the same folder under the same name but for its numbers. Only for
    # downloads: your own files (windows10.iso, windows11.iso) are different tools, not versions.
    shapes = {shape(rel) for rel in versioned}
    remove, keep = [], []
    for rel in stale:
        name = tools.get(rel)
        if by.get(rel) == me:
            gone = True
        elif name is not None:
            gone = name in names or name in off
        else:
            gone = shape(rel) in shapes
        (remove if gone else keep).append(rel)
    return remove, keep


def _carry_menu(doc: dict, old: dict, kept: list[str]) -> dict:
    """Keep the boot-menu names, tips and icons of images that stay on the stick though this PC
    doesn't know their tools: taken from the menu as the stick had it."""
    images = {f"/{rel}" for rel in kept}
    dirs = {f"/{rel.rpartition('/')[0]}" for rel in kept}
    stems = {rel.rpartition("/")[2].rsplit(".", 1)[0] for rel in kept}

    def ours(e: dict) -> bool:
        return e.get("image") in images or e.get("dir") in dirs or ("key" in e and e["key"] in stems)

    def add(have: list, extra: list) -> list:
        seen = {json.dumps({k: v for k, v in e.items() if k in ("image", "dir", "key")}, sort_keys=True) for e in have}
        return have + [e for e in extra if isinstance(e, dict) and ours(e)
                       and json.dumps({k: v for k, v in e.items() if k in ("image", "dir", "key")}, sort_keys=True) not in seen]

    if isinstance(old.get("menu_alias"), list):
        doc["menu_alias"] = add(doc.get("menu_alias", []), old["menu_alias"])
    old_tip = old.get("menu_tip") if isinstance(old.get("menu_tip"), dict) else {}
    if isinstance(old_tip.get("tips"), list):
        tips = add((doc.get("menu_tip") or {}).get("tips", []), old_tip["tips"])
        if tips:            # this PC's tools may have no tips at all: then where they go comes over too
            doc.setdefault("menu_tip", {k: v for k, v in old_tip.items() if k != "tips"})["tips"] = tips
    if isinstance(old.get("menu_class"), list):
        classes = add(doc.get("menu_class", []), old["menu_class"])
        if classes:         # Ventoy takes the first key that matches: longest first, as build_ventoy_json has them
            doc["menu_class"] = ([c for c in classes if "key" not in c]
                                 + sorted((c for c in classes if "key" in c), key=lambda c: -len(c["key"])))
    return doc


def _carry_extras(mnt: Path, extras: list[tuple[str, Path | bytes]], kept: list[str], kept_apps: list[str],
                  apps_root: str) -> list[tuple[str, Path | bytes]]:
    """The menu and the launcher's app list, with what is kept from the stick added back in."""
    out = []
    for rel, data in extras:
        try:
            if rel == BASE_JSON and kept and isinstance(data, bytes):
                old = mnt / BASE_JSON if (mnt / BASE_JSON).is_file() else mnt / "ventoy" / "ventoy.json"
                doc = _carry_menu(json.loads(data), json.loads(old.read_text(encoding="utf-8")), kept)
                data = (json.dumps(doc, indent=2, ensure_ascii=False) + "\n").encode("utf-8")
            elif rel == f"{apps_root}/apps.txt" and kept_apps and isinstance(data, bytes):
                lines = [ln for ln in (mnt / rel).read_text(encoding="utf-8").splitlines()
                         if ln.split("|")[1:2] and ln.split("|")[1].split("\\")[0] in kept_apps]
                data += ("\r\n".join(lines) + "\r\n").encode("utf-8") if lines else b""
        except (OSError, ValueError):
            pass        # nothing readable to carry over: the tools still boot, under their file names
        out.append((rel, data))
    return out


def _put_by(state: dict, me: str, files: set[str], wrote: set[str], kept: list[str],
            apps: set[str], wrote_apps: set[str], kept_apps: list[str]) -> dict:
    """Which PC put each image and app on the stick: this one for what it just wrote, whoever
    it was before for what was already there or is being kept."""
    by, apps_by = state.get("by") or {}, state.get("apps_by") or {}
    return {
        "by": {**{rel: by[rel] for rel in kept if rel in by},
               **{rel: me if rel in wrote else by.get(rel, me) for rel in files}},
        "apps_by": {**{n: apps_by[n] for n in kept_apps if n in apps_by},
                    **{n: me if n in wrote_apps else apps_by.get(n, me) for n in apps}},
    }


# What a run is about to do to a stick, collected while it works it out, so a dry run can say
# it in one piece and the apps can ask first (update_plan).
_PLAN: list[tuple[str, str, int]] | None = None


def _planned(action: str, what: str, size: int = 0) -> None:
    """Note one thing this run does: action is copy, remove or keep."""
    if _PLAN is not None:
        _PLAN.append((action, what, size))


def plan_text(plan: list[tuple[str, str, int]]) -> str:
    """A plan in plain words: what an update copies, removes and leaves alone."""
    def names(action: str) -> list[str]:
        return [what for a, what, _ in plan if a == action]

    def listed(items: list[str]) -> str:
        return ", ".join(items[:8]) + (f" and {len(items) - 8} more" if len(items) > 8 else "")

    copy, remove, keep, move = names("copy"), names("remove"), names("keep"), names("move")
    if not copy and not remove and not move:
        lines = ["Everything on the stick is already up to date."]
    else:
        lines = []
        if copy:
            size = sum(n for a, _, n in plan if a == "copy")
            lines.append(f"Copy {len(copy)}" + (f" ({_fmt_bytes(size)})" if size else "") + f": {listed(copy)}")
        if move:
            lines.append(f"Move {len(move)} to its new folder: {listed(move)}")
        lines.append(f"Remove {len(remove)}: {listed(remove)}" if remove else "Remove nothing.")
    if keep:
        lines.append(f"Keep {len(keep)} this PC has no copy of: {listed(keep)}")
    return "\n".join(lines)


def update_plan(cfg: Config, target: str, pack: str | None = None, prune_unknown: bool = False,
                init: bool = False) -> list:
    """What `sync` (or `unpack`, given a pack) would do to the stick, without doing it or
    printing anything: a list of (copy | remove | keep, what, bytes) for plan_text."""
    global _PLAN
    args = argparse.Namespace(target=target, pack=pack, init=init, dry_run=True, verify=False,
                              no_prune=False, prune_unknown=prune_unknown)
    _PLAN, streams = [], (sys.stdout, sys.stderr)
    try:
        with open(os.devnull, "w", encoding="utf-8") as quiet:
            sys.stdout = sys.stderr = quiet
            (cmd_unpack if pack else cmd_sync)(cfg, args)
        return _PLAN
    finally:
        (sys.stdout, sys.stderr), _PLAN = streams, None


def _keep_note(what: str, names: list[str]) -> None:
    for name in names:
        _planned("keep", name)
    if names:
        warn(f"keeping {len(names)} {what} this PC has no copy of: {', '.join(names)}. "
             "They stay on the stick as they are; --prune-unknown removes them.")


def _prune(mnt: Path, iso_root: str, stale: list[str], dry_run: bool) -> None:
    """Delete boot images this project put on the stick that are no longer wanted."""
    for rel in stale:
        p = (mnt / rel).resolve()
        if p.is_relative_to(mnt) and p.exists():
            info(f"removing old {rel}")
            _planned("remove", rel.rpartition("/")[2])
            if not dry_run:
                p.unlink()
    if not dry_run:  # category folders emptied by a rename or removal
        root = (mnt / iso_root).resolve()
        for d in sorted({(mnt / rel).parent for rel in stale}, key=lambda d: -len(d.parts)):
            if d.is_dir() and d.resolve() != root and d.resolve().is_relative_to(root) and not any(d.iterdir()):
                d.rmdir()


def _keep_edited_json(mnt: Path, state: dict) -> Path:
    """Back up a ventoy.json someone edited by hand, before it is rewritten; return its path."""
    vdir = mnt / "ventoy"
    vdir.mkdir(exist_ok=True)
    vjson = vdir / "ventoy.json"
    if vjson.exists() and state.get("ventoy_json_sha") != file_hash(vjson):
        backup = vdir / f"ventoy.json.bak-{dt.date.today().isoformat()}"
        shutil.copy2(vjson, backup)
        warn(f"your existing ventoy.json was backed up to ventoy/{backup.name}")
    return vjson


def _write_extras(cfg: Config, mnt: Path, state: dict, extras: list[tuple[str, Path | bytes]],
                  fresh_theme: bool) -> Path:
    """Write the launcher, theme and boot menu, keeping a copy of a ventoy.json someone edited.
    Only what differs is written: a refresh that changes nothing writes nothing here."""
    vjson = mnt / "ventoy" / "ventoy.json"
    changed = vjson.exists() and state.get("ventoy_json_sha") != file_hash(vjson)   # edited by hand: redo it
    _keep_edited_json(mnt, state)
    legacy = fresh_theme and any(rel.startswith("ventoy/theme/") for rel, _ in extras)
    if legacy:                      # a pack from before `helix theme`: its theme and menu are ready-made
        shutil.rmtree(mnt / THEME_SRC, ignore_errors=True)
        shutil.rmtree(mnt / "ventoy" / "theme", ignore_errors=True)
        (mnt / BASE_JSON).unlink(missing_ok=True)
    for rel, data in extras:
        dst = _inside(mnt, rel)
        dst.parent.mkdir(parents=True, exist_ok=True)
        try:
            if isinstance(data, bytes):
                if not (dst.is_file() and dst.stat().st_size == len(data) and dst.read_bytes() == data):
                    dst.write_bytes(data)
                    changed = True
            elif not _same_file(data, dst):
                shutil.copy2(data, dst)
                changed = True
        except PermissionError:
            if dst.name != APP_EXE:  # anything else that can't be written is a failed run, not a detail
                raise
            warn(f"{rel} is in use (it is the app doing this update), so it wasn't replaced: "
                 "it will be on the next update, or run Helix Boot from another folder")
    if fresh_theme and not legacy:
        changed |= _tidy_theme_source(cfg, mnt, state, {rel for rel, _ in extras})
    _apply_look(cfg, mnt, changed)
    return vjson


def _same_file(src: Path, dst: Path) -> bool:
    """Is dst already a copy of src? By size and time (copies keep the time; exFAT rounds it to
    2 s), which spares rewriting the big files on every refresh."""
    try:
        a, b = src.stat(), dst.stat()
    except OSError:
        return False
    return a.st_size == b.st_size and abs(a.st_mtime - b.st_mtime) <= 2


def _tidy_theme_source(cfg: Config, mnt: Path, state: dict, want: set[str]) -> bool:
    """After the theme on the stick was written: remove what this run didn't bring, in place.
    The stick's own icons and splash (from some PC's byo/) stay when this PC brings none and
    wasn't the one that put them there, so updating from a second PC doesn't swap them for the
    stock ones. Records in `state` whose each kind is; True when anything was removed."""
    me, src = cfg.pc_id(), mnt / THEME_SRC
    aside = mnt / STATE_DIR / "mine.keep"           # from 0.6.3/0.6.4, which moved them out of the way:
    if aside.is_dir():                              # a run cut short left them there. Put them back.
        for item in aside.iterdir():
            if not (src / "mine" / item.name).exists():
                (src / "mine").mkdir(parents=True, exist_ok=True)
                os.replace(item, src / "mine" / item.name)
        shutil.rmtree(aside, ignore_errors=True)
    by, keep = dict(state.get("mine_by") or {}), []
    for kind, sub in (("icons", "mine/icons"), ("splash", "mine/splash.png")):
        if any(rel.startswith(f"{THEME_SRC}/{sub}") for rel in want):
            by[kind] = me                           # this PC brings its own
        elif (src / sub).exists() and by.get(kind) != me:
            keep.append(f"{THEME_SRC}/{sub}")
            info(f"keeping the stick's own {kind}: this PC has none of its own")
        else:
            by.pop(kind, None)                      # this PC's own, which it no longer has
    state["mine_by"] = by
    removed = False
    for f in sorted(src.rglob("*"), reverse=True):  # a folder comes after what is in it
        rel = f.relative_to(mnt).as_posix()
        if f.is_dir():
            if not any(f.iterdir()):
                f.rmdir()
        elif rel not in want and not any(rel == k or rel.startswith(f"{k}/") for k in keep):
            f.unlink()
            removed = True
    return removed


# What `helix verify` checks apps against: each file's sha256, taken from the download or the
# pack it was copied from (never read back off the stick, where it may already be damaged).
def _zip_hashes(zf: zipfile.ZipFile, prefix: str = "") -> dict[str, str]:
    """sha256 of every file in a zip under prefix, named from there."""
    out = {}
    for m in zf.infolist():
        if m.is_dir() or not m.filename.startswith(prefix):
            continue
        h = hashlib.sha256()
        with zf.open(m) as f:
            while chunk := f.read(1 << 20):
                h.update(chunk)
        out[m.filename[len(prefix):]] = h.hexdigest()
    return out


def _load_hashes(mnt: Path) -> dict:
    try:
        data = json.loads((mnt / HASHES).read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return {}
    apps = data.get("apps") if isinstance(data, dict) else None
    return {n: a for n, a in (apps or {}).items()
            if isinstance(a, dict) and isinstance(a.get("files"), dict) and isinstance(a.get("dir"), str)}


def _save_hashes(mnt: Path, hashes: dict, app_state: dict) -> None:
    """Keep the records of the apps still on the stick (another PC's too)."""
    text = json.dumps({"apps": {n: h for n, h in sorted(hashes.items()) if n in app_state}},
                      separators=(",", ":"), sort_keys=True) + "\n"
    path = mnt / HASHES
    if not (path.is_file() and path.read_text(encoding="utf-8") == text):
        path.parent.mkdir(exist_ok=True)
        path.write_text(text, encoding="utf-8")


def _damaged(state: dict) -> tuple[set[str], set[str]]:
    """The boot images and apps `helix verify` found damaged, which the next update copies again."""
    d = state.get("damaged") if isinstance(state.get("damaged"), dict) else {}
    return ({x for x in d.get("images") or [] if isinstance(x, str)},
            {x for x in d.get("apps") or [] if isinstance(x, str)})


def _still_damaged(state: dict, mnt: Path, fixed_images: set[str], fixed_apps: set[str], app_state: dict) -> dict:
    """What's left of that list after an update: what it couldn't copy again (another PC's)."""
    images, apps = _damaged(state)
    left = {"images": sorted(r for r in images - fixed_images if (mnt / r).is_file()),
            "apps": sorted(a for a in apps - fixed_apps if a in app_state)}
    return {"damaged": left} if left["images"] or left["apps"] else {}


def _finish(mnt: Path, state_dir: Path, files: set[str], app_state: dict, vjson: Path, extra: dict) -> None:
    tag = f"Helix Boot {__version__}\r\nsynced {dt.datetime.now():%Y-%m-%d %H:%M}\r\n"
    for name in (TAG_FILE, OLD_TAG_FILE):                    # the old name for older launchers and PEs
        (mnt / name).write_text(tag, encoding="utf-8")
    state_dir.mkdir(exist_ok=True)
    (state_dir / "state.json").write_text(json.dumps({
        "files": sorted(files), "apps": app_state, "ventoy_json_sha": file_hash(vjson),
        "synced": dt.datetime.now().isoformat(timespec="seconds"), "helix": __version__, **extra,
    }, indent=2) + "\n", encoding="utf-8")
    info("flushing writes to the stick…")
    _flush_volume(mnt)


def cmd_sync(cfg: Config, args) -> int:
    global _PLAN
    if args.dry_run and _PLAN is None:
        _PLAN = []                      # a dry run ends by saying what it would do, in one piece
    mnt = Path(args.target).expanduser().resolve()
    state_dir, state = _open_stick(mnt, args.init, cfg)
    placed, apps, missing = _plan(cfg, load_lock(cfg))
    want_files = {p["rel"] for p in placed}
    for m in missing:
        warn(f"{m}: not fetched yet — run `helix fetch` (skipping)")

    stale = [f for f in state.get("files", []) if f not in want_files]
    off = cfg.switched_off                 # switched off in this PC's local.toml: those go
    unknown = getattr(args, "prune_unknown", False)
    head(f"Syncing to {mnt}{'  (dry run)' if args.dry_run else ''}")

    # A file that only changed folder (e.g. a category was renamed) is moved, not copied again.
    moved_from = {Path(f).name: f for f in stale}
    # What each image on the stick was, by sha256. Size alone can't tell two builds apart:
    # ISOs round to whole sectors, so a rebuilt Lazarus PE is often exactly as big as the last.
    recorded = state.get("images", {})
    images: dict[str, str] = {}
    bad_images, bad_apps = _damaged(state)                  # found by `helix verify`: copied again
    me, wrote, wrote_apps = cfg.pc_id(), set(), set()      # what this PC puts on the stick in this run
    moved: set[str] = set()                                 # old paths of images that only change folder
    for n, p in enumerate(placed, 1):
        dst = mnt / p["rel"]
        old = moved_from.get(p["file"])
        if old and not dst.exists():
            src_old = (mnt / old).resolve()
            if src_old.is_relative_to(mnt) and src_old.is_file() \
                    and src_old.stat().st_size == p["src"].stat().st_size:
                info(f"{p['title']}: moving {old} → {p['rel']}")
                moved.add(old)
                _planned("move", p["title"])
                if not args.dry_run:
                    dst.parent.mkdir(parents=True, exist_ok=True)
                    os.replace(src_old, dst)
                    wrote.add(p["rel"])
                else:
                    continue

        same = dst.exists() and dst.stat().st_size == p["src"].stat().st_size
        if same and p["sha256"]:
            if args.verify:
                same = file_hash(dst) == p["sha256"]
            elif p["rel"] in recorded:
                same = recorded[p["rel"]] == p["sha256"]
            elif p["local"]:    # no record yet (an older stick): a local build may have been rebuilt
                same = file_hash(dst) == p["sha256"]
        if same and p["rel"] in bad_images and not args.verify:
            same = False
        if same:
            images[p["rel"]] = p["sha256"]
            ok(f"{p['title']} {p['version']} — already on stick")
            continue
        info(f"{p['title']} {p['version']} → {p['rel']}")
        _planned("copy", f"{p['title']} {p['version']}", p["src"].stat().st_size)
        if not args.dry_run:
            prog = Progress()
            prog.file(f"({n}/{len(placed)}) {p['file']}", p["src"].stat().st_size)
            _copy(p["src"], dst, prog)
            if args.verify and p["sha256"]:
                _uncached(dst)
                prog.file(f"({n}/{len(placed)}) verifying {p['file']}", dst.stat().st_size)
                good = file_hash(dst, progress=prog) == p["sha256"]
                prog.clear()
                if not good:
                    raise RescueError(f"{p['rel']} doesn't match after copying — the stick may be failing.")
            prog.clear()
            images[p["rel"]] = p["sha256"]
            wrote.add(p["rel"])
            ok(f"{p['title']} copied")

    app_state = dict(state.get("apps", {}))
    app_root = mnt / cfg.apps_root
    hashes = _load_hashes(mnt)
    for t, entry, src in apps:
        root = mnt / _app_root(cfg, t)
        dst = root / t["name"]
        unzip = zipfile.is_zipfile(src) and t.get("platform") != "mac"
        rec = hashes.get(t["name"])
        if not args.dry_run and not (rec and rec.get("version") == entry["version"]):
            if unzip:
                with zipfile.ZipFile(src) as zf:
                    files = _zip_hashes(zf)
            else:
                files = {src.name: file_hash(src)}
            hashes[t["name"]] = {"version": entry["version"], "dir": f"{_app_root(cfg, t)}/{t['name']}",
                                 "files": files}
        if app_state.get(t["name"]) == entry["version"] and dst.exists() and t["name"] not in bad_apps:
            ok(f"{t['title']} {entry['version']} — already on stick")
            continue
        info(f"{t['title']} {entry['version']} → {_app_root(cfg, t)}/{t['name']}/")
        _planned("copy", f"{t['title']} {entry['version']}", src.stat().st_size)
        if args.dry_run:
            continue
        new = root / f".{t['name']}.new"
        shutil.rmtree(new, ignore_errors=True)
        new.mkdir(parents=True)
        if unzip:
            with zipfile.ZipFile(src) as zf:
                zf.extractall(new, members=_safe_zip_members(zf))
        else:
            shutil.copy2(src, new / src.name)
        if dst.exists():
            shutil.rmtree(dst)
        os.replace(new, dst)
        app_state[t["name"]] = entry["version"]
        wrote_apps.add(t["name"])
        ok(f"{t['title']} {'unpacked' if unzip else 'copied'}")

    enabled_apps = {t["name"] for t, _, _ in apps}
    kept_apps = []
    for name in [n for n in app_state if n not in enabled_apps]:
        if not SAFE_NAME.fullmatch(name):   # state.json is on the stick: anything could have written it
            warn(f"ignoring an app name in the stick's state that isn't one: {name!r}")
            app_state.pop(name)
            continue
        if name not in off and not unknown and (state.get("apps_by") or {}).get(name) != me:
            kept_apps.append(name)          # another PC's: this one just has no copy of it
            continue
        info(f"removing app no longer in the manifest: {name}")
        _planned("remove", name)
        if not args.dry_run:
            for root in (app_root, mnt / cfg.mac_root):
                shutil.rmtree(_inside(root, name, "app folder"), ignore_errors=True)
            app_state.pop(name)

    remove, kept = _stale_split(state, stale, {p["rel"]: p["name"] for p in placed}, off, me, unknown,
                                versioned={p["rel"] for p in placed if not p["local"]})
    remove = [rel for rel in remove if rel not in moved]        # moved to its new folder, not removed
    kept = [rel for rel in kept if (mnt / rel).is_file() and rel not in moved]
    if args.no_prune:
        kept += [rel for rel in remove if (mnt / rel).is_file()]
    elif remove or moved:           # (the folders that moved images left empty go too)
        _prune(mnt, cfg.iso_root, remove + ([] if args.dry_run else sorted(moved)), args.dry_run)
    _keep_note("boot image(s)", [rel.rpartition("/")[2] for rel in kept] if not args.no_prune else [])
    _keep_note("app(s)", kept_apps)

    # Trees (the PortableApps.com Platform) go on once and then look after themselves:
    # never overwritten with an older copy, never pruned.
    for t, entry, src in _trees(cfg, load_lock(cfg)):
        base = mnt / t["dest"]
        if (base / t["once"]).exists():
            ok(f"{t['title']} — already on stick (it updates itself)")
            _tree_patches(t, base, args.dry_run)                # again after a self-update
            continue
        files = _tree_files(src)
        info(f"{t['title']} {entry['version']} → /{t['dest']}")
        _planned("copy", f"{t['title']} {entry['version']}")
        if args.dry_run:
            continue
        prog = Progress(sum(f.stat().st_size for _, f in files))
        prog.file(t["title"], 0)
        for rel, f in files:
            _copy(f, base / rel, prog)
        prog.clear()
        ok(f"{t['title']} installed")
        _tree_patches(t, base, args.dry_run)

    if args.dry_run:
        print(f"\n{plan_text(_PLAN or [])}\nDry run — nothing was written.")
        return 0

    app_root.mkdir(exist_ok=True)
    _save_hashes(mnt, hashes, app_state)
    theme_src = cfg.assets / cfg.settings["theme"] if cfg.settings.get("theme") else None
    extras = _carry_extras(mnt, _stick_extras(cfg, placed, apps), kept, kept_apps, cfg.apps_root)
    vjson = _write_extras(cfg, mnt, state, extras, fresh_theme=bool(theme_src and theme_src.is_dir()))
    images.update({rel: recorded[rel] for rel in kept if rel in recorded})
    tools = {**{rel: n for rel, n in (state.get("tools") or {}).items() if rel in kept},
             **{p["rel"]: p["name"] for p in placed}}
    _finish(mnt, state_dir, want_files | set(kept), app_state, vjson, {
        "images": images, "tools": tools, "mine_by": state.get("mine_by") or {},
        **_still_damaged(state, mnt, wrote | (want_files if args.verify else set()), wrote_apps, app_state),
        **_put_by(state, me, want_files, wrote, kept, {t["name"] for t, _, _ in apps}, wrote_apps, kept_apps)})
    ok(f"Stick is up to date: {len(placed)} boot image(s), {len(apps)} app(s).")
    return 0


# ── Packs: the whole stick in one file ────────────────────────────────────
# A pack is a zip holding the stick exactly as `sync` would lay it out (under stick/),
# Ventoy and this project's own installer (under installer/), and PACK_META, which lists
# every boot image with its sha256. `unpack` streams it onto a stick, so no downloads are
# needed, and the bundled installer means the zip is all another machine needs.
PACK_META = "helix-boot-pack.json"
OLD_PACK_META = "commander-rescue-pack.json"   # packs made before the rename
PACK_FORMAT = 1
BUNDLED = ["helix", "tools.toml", "install.sh", "refresh.sh", "theme.sh", "check.sh", "scripts/common.sh", "LICENSE"]
BUNDLED_MARK = "installer/.bundled"   # tells install.sh / refresh.sh to look for the pack beside them
APP_REPO = "Commanderx-code/helix-boot"   # where HelixBoot.exe is released
APP_EXE = "HelixBoot.exe"
BUNDLED_README = """Helix Boot pack
===============

Everything for a Helix Boot USB stick, including your own tools. Keep it private.

On Windows: unzip just installer\\HelixBoot.exe (if this pack has it; otherwise download
it from https://github.com/Commanderx-code/helix-boot/releases) next to this zip and run
it. It finds {zip} beside it, and Install / Update copy everything from it offline.

On any Linux PC with Python 3.11+, unzip just the installer (a few MB) next to this zip:

    unzip {zip} 'installer/*'         (or: bsdtar -xf {zip} installer)

New stick (ERASES it; you choose the stick and confirm):

    installer/install.sh

Update a stick already made with Helix Boot:

    installer/refresh.sh

Both find {zip} beside the installer folder and copy everything from it, with no
downloads. If the zip has been moved or renamed, add --from /path/to/the.zip.
"""


def _zip_file(zf: zipfile.ZipFile, src: Path, arc: str, compress: int = zipfile.ZIP_DEFLATED) -> str:
    """Add src to the zip as arc; return its sha256, taken from the bytes as they went in."""
    zi = zipfile.ZipInfo.from_file(src, arc, strict_timestamps=False)
    zi.compress_type = compress
    h = hashlib.sha256()
    with open(src, "rb") as s, zf.open(zi, "w", force_zip64=True) as d:
        while chunk := s.read(8 << 20):
            h.update(chunk)
            d.write(chunk)
    return h.hexdigest()


def cmd_pack(cfg: Config, args) -> int:
    lock = load_lock(cfg)
    placed, apps, missing = _plan(cfg, lock)
    for m in missing:
        warn(f"{m}: not fetched yet — run `helix fetch` (leaving it out of the pack)")
    if not placed:
        raise RescueError("nothing to pack yet — run `helix fetch` first")
    out = Path(args.output or f"helix-boot-{dt.date.today().isoformat()}.zip").expanduser().resolve()
    if out.suffix.lower() != ".zip":
        raise RescueError(f"{out.name}: a pack must end in .zip")

    vt = next((t for t in cfg.tools if t["kind"] == "ventoy"), None)
    ventry = lock.get(vt["name"]) if vt else None
    vsrc = cfg.cache / vt["name"] / ventry["source_file"] if ventry and ventry.get("source_file") else None
    if not vsrc or not vsrc.is_file():
        warn("Ventoy isn't fetched, so this pack can refresh a stick but not set up a new one "
             "(`helix fetch ventoy` fixes that)")
        vsrc = None

    # A pack also sets up sticks from Windows: Ventoy's Windows package and the Windows app go in too.
    win_ventoy = app_exe = None
    if vt and vt.get("windows") and not cfg.windows:
        wtool = {k: v for k, v in vt.items() if k != "windows"} | vt["windows"]
        win_ventoy = _pack_download(cfg, wtool | {"name": f"{vt['name']}-windows", "title": "Ventoy for Windows"}, lock)
        if not win_ventoy:
            warn("Ventoy for Windows isn't available, so this pack can't set up a new stick from Windows")
    app_exe = _pack_download(cfg, {"name": "helixboot-exe", "title": APP_EXE, "kind": "file", "source": "github",
                                   "repo": APP_REPO, "asset": [f"^{re.escape(APP_EXE)}$"],
                                   "checksum": ["github-digest"]}, lock)
    if not app_exe:
        warn(f"no released {APP_EXE} to include; on Windows, download it from "
             f"https://github.com/{APP_REPO}/releases and put it beside the pack")

    size = sum(p["src"].stat().st_size for p in placed) + sum(s.stat().st_size for _, _, s in apps)
    size += sum(x[0].stat().st_size for x in (win_ventoy, app_exe) if x) + (vsrc.stat().st_size if vsrc else 0)
    out.parent.mkdir(parents=True, exist_ok=True)
    free = shutil.disk_usage(out.parent).free
    if size > free:
        raise RescueError(f"the pack needs {_fmt_bytes(size)} but {out.parent} has {_fmt_bytes(free)} free")

    head(f"Packing {len(placed)} boot image(s) and {len(apps)} app(s) into {out} (~{_fmt_bytes(size)})")
    part = out.with_name(out.name + ".part")
    isos = []
    try:
        with zipfile.ZipFile(part, "w", allowZip64=True) as zf:
            for p in placed:
                info(f"{p['title']} {p['version']} ({_fmt_bytes(p['src'].stat().st_size)})")
                sha = _zip_file(zf, p["src"], f"stick/{p['rel']}", zipfile.ZIP_STORED)  # ISOs don't compress
                if p["sha256"] and sha != p["sha256"] and not p["local"]:
                    raise RescueError(f"{p['title']}: the cached {p['file']} has changed since it was verified. "
                                      f"Run `helix fetch --force {p['name']}`.")
                isos.append({"rel": p["rel"], "name": p["name"], "local": p["local"], "title": p["title"],
                             "version": p["version"], "sha256": sha,
                             "size": p["src"].stat().st_size})
            for t, entry, src in apps:
                base = f"stick/{_app_root(cfg, t)}/{t['name']}"
                if zipfile.is_zipfile(src) and t.get("platform") != "mac":  # unpacked now, exactly as `sync` would
                    with zipfile.ZipFile(src) as zs:
                        for m in _safe_zip_members(zs):
                            if m.is_dir():
                                continue
                            zi = zipfile.ZipInfo(f"{base}/{m.filename}", m.date_time)
                            zi.compress_type = zipfile.ZIP_DEFLATED
                            with zs.open(m) as s, zf.open(zi, "w", force_zip64=True) as d:
                                shutil.copyfileobj(s, d, 8 << 20)
                else:
                    _zip_file(zf, src, f"{base}/{src.name}")
            extras = _stick_extras(cfg, placed, apps)
            for rel, data in extras:
                if isinstance(data, bytes):
                    zf.writestr(f"stick/{rel}", data, zipfile.ZIP_DEFLATED)
                else:
                    _zip_file(zf, data, f"stick/{rel}")
            trees = []
            for t, entry, src in _trees(cfg, lock):
                for rel, f in _tree_files(src):
                    _zip_file(zf, f, f"once/{t['name']}/{rel}")
                trees.append({"name": t["name"], "title": t["title"], "dest": t["dest"], "once": t["once"],
                              "version": entry["version"], "hide_logo": t.get("hide_logo"),
                              "recolor": t.get("recolor")})
            if vsrc:
                _zip_file(zf, vsrc, f"installer/{vsrc.name}", zipfile.ZIP_STORED)
            if win_ventoy:
                _zip_file(zf, win_ventoy[0], f"installer/{win_ventoy[0].name}", zipfile.ZIP_STORED)
            if app_exe:
                _zip_file(zf, app_exe[0], f"installer/{APP_EXE}")
            for rel in BUNDLED:  # keeps their executable bits, so `unzip` gives runnable scripts
                f = (cfg.assets if rel == "tools.toml" else REPO) / rel
                if f.is_file():
                    _zip_file(zf, f, f"installer/{rel}")
            zf.writestr(BUNDLED_MARK, f"{__version__}\n", zipfile.ZIP_DEFLATED)
            zf.writestr("installer/README.txt", BUNDLED_README.format(zip=out.name), zipfile.ZIP_DEFLATED)
            zf.writestr(PACK_META, json.dumps({
                "format": PACK_FORMAT, "helix": __version__,
                "created": dt.datetime.now().isoformat(timespec="seconds"),
                "iso_root": cfg.iso_root, "apps_root": cfg.apps_root, "isos": isos,
                "apps": {t["name"]: e["version"] for t, e, _ in apps},
                "app_roots": {t["name"]: _app_root(cfg, t) for t, _, _ in apps if _app_root(cfg, t) != cfg.apps_root},
                # switched off by hand where the pack was made: unpack removes these from a stick that has them
                "off": sorted(cfg.switched_off),
                "ventoy": {"file": f"installer/{vsrc.name}", "version": ventry["version"]} if vsrc else None,
                "ventoy_windows": ({"file": f"installer/{win_ventoy[0].name}", "version": win_ventoy[1]["version"]}
                                   if win_ventoy else None),
                "app": {"file": f"installer/{APP_EXE}", "version": app_exe[1]["version"]} if app_exe else None,
                "trees": trees,
                "fresh_theme": any(rel.startswith(f"{THEME_SRC}/") for rel, _ in extras),
            }, indent=2), zipfile.ZIP_DEFLATED)
    except BaseException:
        part.unlink(missing_ok=True)
        raise
    os.replace(part, out)
    ok(f"Pack written: {out} ({_fmt_bytes(out.stat().st_size)})")
    info("It holds your own tools as well, so keep it somewhere private. To use it here:")
    info(f"  new stick:      ./install.sh --from {out}")
    info(f"  existing stick: ./refresh.sh --from {out}")
    info(f"On another PC it needs nothing else: unzip {out.name} 'installer/*', then installer/install.sh")
    if app_exe:
        info(f"On Windows: put installer\\{APP_EXE} beside the pack and run it.")
    return 0


def _pack_download(cfg: Config, tool: dict, lock: dict) -> tuple[Path, dict] | None:
    """Fetch (or reuse from the cache) a file only packs carry, such as Ventoy for Windows.
    Returns (file, lock entry), or None when it can't be had (offline and never fetched)."""
    try:
        fetch_tool(cfg, tool, lock)
        save_lock(cfg, lock)
    except (RescueError, OSError) as e:
        warn(f"{tool['title']}: couldn't check for a newer one ({e})")
    entry = lock.get(tool["name"])
    f = cfg.cache / tool["name"] / entry["source_file"] if entry and entry.get("source_file") else None
    return (f, entry) if f and f.is_file() else None


def _read_pack(zf: zipfile.ZipFile) -> dict:
    names = set(zf.namelist())
    meta_name = next((n for n in (PACK_META, OLD_PACK_META) if n in names), None)
    if not meta_name:
        raise RescueError(f"not a Helix Boot pack (no {PACK_META} inside)")
    meta = json.loads(zf.read(meta_name))
    if meta.get("format") != PACK_FORMAT:
        raise RescueError(f"this pack is format {meta.get('format')}; this helix reads format {PACK_FORMAT}. "
                          "Update Helix Boot.")
    _safe_zip_members(zf)
    for rel in ([meta[k] for k in ("iso_root", "apps_root") if k in meta] + [i["rel"] for i in meta["isos"]]
                + list(meta.get("app_roots", {}).values())
                + [t[k] for t in meta.get("trees", []) for k in ("dest", "once") if t[k]]):
        _safe_rel(rel, "path in pack")
    for name in list(meta["apps"]) + [t["name"] for t in meta.get("trees", [])]:
        if not isinstance(name, str) or not SAFE_NAME.fullmatch(name):
            raise RescueError(f"refusing unsafe name in pack: {name!r}")
    return meta


def _open_pack(path: str) -> zipfile.ZipFile:
    p = Path(path).expanduser()
    if not p.is_file():
        raise RescueError(f"can't find the pack {p}")
    try:
        return zipfile.ZipFile(p)
    except zipfile.BadZipFile:
        raise RescueError(f"{p.name} isn't a zip file (or it's incomplete)") from None


def _unzip_to(zf: zipfile.ZipFile, member: str, dst: Path, progress: Progress | None = None) -> str:
    """Stream one member to dst (via a .part file, fsynced); return its sha256."""
    dst.parent.mkdir(parents=True, exist_ok=True)
    tmp = dst.with_name(dst.name + ".part")
    h = hashlib.sha256()
    try:
        with zf.open(member) as s, open(tmp, "wb") as d:  # zipfile checks the CRC as it reads
            since = 0
            while chunk := s.read(8 << 20):
                h.update(chunk)
                d.write(chunk)
                since += len(chunk)
                if since >= FLUSH_EVERY:
                    d.flush()
                    os.fsync(d.fileno())
                    since = 0
                if progress:
                    progress.add(len(chunk))
            d.flush()
            os.fsync(d.fileno())
    except zipfile.BadZipFile as e:
        tmp.unlink(missing_ok=True)
        raise RescueError(f"the pack is damaged ({member}: {e})") from None
    os.replace(tmp, dst)
    return h.hexdigest()


def cmd_unpack(cfg: Config, args) -> int:
    global _PLAN
    if args.dry_run and _PLAN is None:
        _PLAN = []
    mnt = Path(args.target).expanduser().resolve()
    state_dir, state = _open_stick(mnt, args.init, cfg)
    with _open_pack(args.pack) as zf:
        meta = _read_pack(zf)
        names = set(zf.namelist())
        iso_root, apps_root = meta["iso_root"], meta["apps_root"]
        want_files = {i["rel"] for i in meta["isos"]}
        head(f"Unpacking {Path(args.pack).name} (made {meta['created'][:10]}) to {mnt}"
             f"{'  (dry run)' if args.dry_run else ''}")

        dests = {i["rel"]: _inside(mnt, i["rel"], "boot image path") for i in meta["isos"]}
        bad_images, bad_apps = _damaged(state)          # found by `helix verify`: copied again
        todo = [i for i in meta["isos"]
                if not (dests[i["rel"]].is_file() and dests[i["rel"]].stat().st_size == i["size"])
                or (args.verify and file_hash(dests[i["rel"]]) != i["sha256"])
                or (i["rel"] in bad_images and not args.verify)]
        need = sum(i["size"] for i in todo)
        free = shutil.disk_usage(mnt).free
        if need > free and not args.dry_run:
            raise RescueError(f"the stick needs {_fmt_bytes(need)} free for this pack but has {_fmt_bytes(free)}")

        # Writing counts once; with --verify, reading each image back from the stick counts again.
        prog = Progress(need * (2 if args.verify else 1))
        for n, i in enumerate(meta["isos"], 1):
            if i not in todo:
                ok(f"{i['title']} {i['version']} — already on stick")
                continue
            info(f"{i['title']} {i['version']} → {i['rel']}")
            _planned("copy", f"{i['title']} {i['version']}", i["size"])
            if args.dry_run:
                continue
            if f"stick/{i['rel']}" not in names:
                raise RescueError(f"the pack is missing {i['rel']}")
            dst = dests[i["rel"]]
            name = Path(i["rel"]).name
            prog.file(f"({n}/{len(meta['isos'])}) {name}", i["size"])
            got = _unzip_to(zf, f"stick/{i['rel']}", dst, prog)
            if got != i["sha256"]:
                prog.clear()
                dst.unlink()
                raise RescueError(f"{i['title']}: the copy in the pack doesn't match its checksum. "
                                  "The pack is damaged; make a new one.")
            if args.verify:
                _uncached(dst)
                prog.file(f"({n}/{len(meta['isos'])}) verifying {name}", i["size"])
                good = file_hash(dst, progress=prog) == i["sha256"]
                if not good:
                    prog.clear()
                    raise RescueError(f"{i['rel']} doesn't match after copying — the stick may be failing.")
            prog.clear()
            ok(f"{i['title']} copied")

        app_state = dict(state.get("apps", {}))
        app_root = _inside(mnt, apps_root, "apps folder")
        roots = meta.get("app_roots", {})         # apps that go elsewhere than Apps: the Mac tools
        wrote_apps: set[str] = set()
        hashes = _load_hashes(mnt)
        for name, version in meta["apps"].items():
            root = _inside(mnt, roots.get(name, apps_root), "apps folder")
            dst = _inside(root, name, "app folder")
            prefix = f"stick/{roots.get(name, apps_root)}/{name}/"
            rec = hashes.get(name)
            fresh = not args.dry_run and not (rec and rec.get("version") == version)
            if app_state.get(name) == version and dst.exists() and name not in bad_apps:
                if fresh:
                    hashes[name] = {"version": version, "dir": f"{roots.get(name, apps_root)}/{name}",
                                    "files": _zip_hashes(zf, prefix)}
                ok(f"{name} {version} — already on stick")
                continue
            info(f"{name} {version} → {roots.get(name, apps_root)}/{name}/")
            _planned("copy", f"{name} {version}")
            if args.dry_run:
                continue
            new = root / f".{name}.new"
            shutil.rmtree(new, ignore_errors=True)
            files = {}
            for m in names:
                if m.startswith(prefix) and not m.endswith("/"):
                    files[m[len(prefix):]] = _unzip_to(zf, m, _inside(new, m[len(prefix):], "path in pack"))
            hashes[name] = {"version": version, "dir": f"{roots.get(name, apps_root)}/{name}", "files": files}
            if dst.exists():
                shutil.rmtree(dst)
            os.replace(new, dst)
            app_state[name] = version
            wrote_apps.add(name)
            ok(f"{name} unpacked")
        unknown, kept_apps = getattr(args, "prune_unknown", False), []
        off = {n for n in meta.get("off", []) if isinstance(n, str)}
        me = cfg.pc_id()
        for name in [n for n in app_state if n not in meta["apps"]]:
            if not SAFE_NAME.fullmatch(name):   # state.json is on the stick: anything could have written it
                warn(f"ignoring an app name in the stick's state that isn't one: {name!r}")
                app_state.pop(name)
                continue
            if name not in off and not unknown and (state.get("apps_by") or {}).get(name) != me:
                kept_apps.append(name)      # another PC's: the pack just doesn't have it
                continue
            info(f"removing app that isn't in this pack: {name}")
            _planned("remove", name)
            if not args.dry_run:
                for root in {apps_root, cfg.mac_root, *roots.values()}:
                    shutil.rmtree(_inside(_inside(mnt, root, "apps folder"), name, "app folder"), ignore_errors=True)
                app_state.pop(name)

        stale = [f for f in state.get("files", []) if f not in want_files]
        remove, kept = _stale_split(state, stale, {i["rel"]: i.get("name") for i in meta["isos"]}, off, me, unknown,
                                    versioned={i["rel"] for i in meta["isos"] if i.get("local") is False})
        kept = [rel for rel in kept if _inside(mnt, rel, "path in the stick's state").is_file()]
        if args.no_prune:
            kept += [rel for rel in remove if (mnt / rel).is_file()]
        elif remove:
            _prune(mnt, iso_root, remove, args.dry_run)
        _keep_note("boot image(s)", [rel.rpartition("/")[2] for rel in kept] if not args.no_prune else [])
        _keep_note("app(s)", kept_apps)

        for t in meta.get("trees", []):
            base = _inside(mnt, t["dest"], "tree folder") if t["dest"] else mnt   # "" is the stick's root
            if _inside(base, t["once"], "tree marker").exists():
                ok(f"{t['title']} — already on stick (it updates itself)")
                _tree_patches(t, base, args.dry_run)
                continue
            info(f"{t['title']} {t['version']} → /{t['dest']}")
            if args.dry_run:
                continue
            prefix = f"once/{t['name']}/"
            for m in sorted(names):
                if m.startswith(prefix) and not m.endswith("/"):
                    _unzip_to(zf, m, _inside(base, m[len(prefix):], "path in pack"))
            ok(f"{t['title']} installed")
            _tree_patches(t, base, args.dry_run)

        if args.dry_run:
            print(f"\n{plan_text(_PLAN or [])}\nDry run — nothing was written.")
            return 0

        app_root.mkdir(exist_ok=True)
        _save_hashes(mnt, hashes, app_state)
        app_dirs = tuple(f"stick/{roots.get(n, apps_root)}/{n}/" for n in meta["apps"])
        extras = [(m[len("stick/"):], zf.read(m)) for m in sorted(names)
                  if m.startswith("stick/") and not m.endswith("/") and m[len("stick/"):] not in want_files
                  and not m.startswith(app_dirs)]
        extras = _carry_extras(mnt, extras, kept, kept_apps, apps_root)
        vjson = _write_extras(cfg, mnt, state, extras, fresh_theme=meta.get("fresh_theme", False))
    tools = {**{rel: n for rel, n in (state.get("tools") or {}).items() if rel in kept},
             **{i["rel"]: i["name"] for i in meta["isos"] if i.get("name")}}
    _finish(mnt, state_dir, want_files | set(kept), app_state, vjson, {
        "pack": meta["created"], "tools": tools, "mine_by": state.get("mine_by") or {},
        "images": {**{rel: sha for rel, sha in (state.get("images") or {}).items() if rel in kept},
                   **{i["rel"]: i["sha256"] for i in meta["isos"]}},
        **_still_damaged(state, mnt, {i["rel"] for i in todo} | (want_files if args.verify else set()),
                         wrote_apps, app_state),
        **_put_by(state, me, want_files, {i["rel"] for i in todo}, kept, set(meta["apps"]), wrote_apps, kept_apps)})
    ok(f"Stick is up to date from the pack: {len(meta['isos'])} boot image(s), {len(meta['apps'])} app(s).")
    return 0


# ── Checking a stick ──────────────────────────────────────────────────────
# Cheap sticks go bad quietly. `verify` reads back everything this project put on a stick and
# compares it with what was put there: the boot images with the sha256s in state.json, the apps
# with hashes.json. It needs no cache or internet, so any PC can check any Helix Boot stick.
def check_stick(mnt: Path, hook=None) -> dict:
    """Read every boot image and app file back; return what's damaged, missing or unchecked.
    Damaged images and apps are noted on the stick, so the next update copies them again."""
    state_dir, state = _open_stick(mnt, init=True)
    if not state:
        raise RescueError(f"{mnt} has nothing from Helix Boot on it to check")
    images = {rel: sha for rel, sha in (state.get("images") or {}).items() if isinstance(sha, str)}
    apps = _load_hashes(mnt)
    todo = []                                       # (what, path, sha256, app or None)
    for rel, sha in sorted(images.items()):
        todo.append((rel, _inside(mnt, rel, "path in the stick's state"), sha, None))
    for name, rec in sorted(apps.items()):
        if name not in (state.get("apps") or {}):
            continue
        base = _inside(mnt, rec["dir"], "app folder")
        for rel, sha in sorted(rec["files"].items()):
            todo.append((f"{rec['dir']}/{rel}", _inside(base, rel, "app file"), sha, name))
    found = {"damaged": [], "missing": [], "changed": {}, "checked": 0,
             "unrecorded": sorted(n for n in (state.get("apps") or {}) if n not in apps),
             "images": len(images), "apps": len({a for *_, a in todo if a}), "menu": None}

    prog = Progress(sum(p.stat().st_size for _, p, _, _ in todo if p.is_file()), hook=hook)
    for what, path, sha, app in todo:
        if not path.is_file():
            found["missing"].append(what)
            continue
        prog.file(app or Path(what).name, path.stat().st_size)
        _uncached(path)                             # read the stick, not what the OS kept in memory
        good = file_hash(path, progress=prog) == sha
        found["checked"] += 1
        if good:
            continue
        if app:                                     # some tools save their settings in their folder
            found["changed"].setdefault(app, []).append(what)
        else:
            found["damaged"].append(what)
    prog.clear()
    try:
        json.loads((mnt / "ventoy" / "ventoy.json").read_text(encoding="utf-8"))
    except (OSError, ValueError) as e:
        found["menu"] = f"ventoy/ventoy.json can't be read ({e.__class__.__name__}): the boot menu won't work"

    # Noted for the next update. A missing file is noticed by any update anyway.
    bad = {"images": sorted(found["damaged"] + [m for m in found["missing"] if m in images]),
           "apps": sorted(set(found["changed"]) | {a for m in found["missing"] for a in [_app_of(m, apps)] if a})}
    if bad["images"] or bad["apps"] or "damaged" in state:
        state.pop("damaged", None)
        if bad["images"] or bad["apps"]:
            state["damaged"] = bad
        (state_dir / "state.json").write_text(json.dumps(state, indent=2) + "\n", encoding="utf-8")
        _flush_volume(mnt)
    return found


def _app_of(path: str, apps: dict) -> str | None:
    return next((n for n, rec in apps.items() if path.startswith(rec["dir"] + "/")), None)


def check_text(found: dict) -> str:
    """What `check_stick` found, in plain words."""
    lines = []
    if found["damaged"]:
        lines.append(f"✗ {len(found['damaged'])} boot image(s) are damaged: the stick may be failing.")
        lines += [f"    {Path(rel).name}" for rel in found["damaged"]]
    if found["missing"]:
        lines.append(f"✗ {len(found['missing'])} file(s) are missing:")
        lines += [f"    {rel}" for rel in found["missing"][:15]]
        if len(found["missing"]) > 15:
            lines.append(f"    … and {len(found['missing']) - 15} more")
    for app, files in sorted(found["changed"].items()):
        lines.append(f"! {app}: {len(files)} file(s) differ from when it was copied. Some tools save "
                     "their settings in their own folder; otherwise the stick may be failing.")
    if found["menu"]:
        lines.append(f"✗ {found['menu']}")
    if found["damaged"] or found["missing"] or found["changed"]:
        lines.append("  The next update copies those again (an app's saved settings go back to how they came). "
                     "If this keeps happening, replace the stick.")
    if not lines:
        lines.append(f"✓ Everything checks out: {found['images']} boot image(s) and {found['apps']} app(s), "
                     f"{found['checked']} file(s) read back.")
    if found["unrecorded"]:
        lines.append(f"• {len(found['unrecorded'])} app(s) were copied by an older Helix Boot and aren't "
                     "checked yet; the next update records them.")
    return "\n".join(lines)


def cmd_verify(cfg: Config, args) -> int:
    mnt = Path(args.target).expanduser().resolve()
    if not args.json:
        head(f"Checking {mnt} (reads the whole stick, so this takes a while)")
    found = check_stick(mnt)
    if args.json:
        print(json.dumps(found, indent=2))
    else:
        print(check_text(found))
    return 1 if found["damaged"] or found["missing"] or found["menu"] else 0


def _ventoy_from_pack(cfg: Config, pack: str, windows: bool | None = None) -> Path:
    """Unpack the pack's Ventoy installer into the cache (once) and return its folder."""
    windows = os.name == "nt" if windows is None else windows
    tool = "Ventoy2Disk.exe" if windows else "Ventoy2Disk.sh"
    with _open_pack(pack) as zf:
        meta = _read_pack(zf)
        # Linux packs carry both packages; the Windows one is a .zip, the Linux one a .tar.gz.
        v = next((v for v in (meta.get("ventoy"), meta.get("ventoy_windows"))
                  if v and v["file"].endswith(".zip") == windows), None)
        if not v:
            if windows and meta.get("ventoy"):
                raise RescueError("this pack has Ventoy for Linux only. Make it again with this version of "
                                  "Helix Boot to set up sticks from Windows.")
            raise RescueError("this pack has no Ventoy installer. Make it again after `helix fetch ventoy`.")
        dest = cfg.cache / "ventoy-from-pack" / f"{v['version']}-{'windows' if windows else 'linux'}"
        tops = [d for d in dest.iterdir() if d.is_dir()] if dest.is_dir() else []
        if len(tops) == 1 and (tops[0] / tool).exists():
            return tops[0]
        shutil.rmtree(dest, ignore_errors=True)
        dest.mkdir(parents=True)
        archive = dest / Path(v["file"]).name
        _unzip_to(zf, v["file"], archive)
    if zipfile.is_zipfile(archive):
        with zipfile.ZipFile(archive) as z:
            z.extractall(dest, members=_safe_zip_members(z))
    else:
        with tarfile.open(archive) as tar:
            _safe_extract_tar(tar, dest)  # keeps the tools' executable bits
    archive.unlink()
    tops = [d for d in dest.iterdir() if d.is_dir()]
    if len(tops) != 1:
        raise RescueError(f"unexpected Ventoy archive layout in the pack: {sorted(d.name for d in tops)}")
    return tops[0]


SPLASH_BEGIN = "#### helix-boot splash: begin ####"
SPLASH_END = "#### helix-boot splash: end ####"
SPLASH_ANCHOR = "#clear all input key before show main menu\n"   # in Ventoy's grub.cfg, just before its menu


SPLASH_FRAMES = 20   # the loading bar's steps: ventoy/theme/splash/00.jpg (empty) … 20.jpg (full)


def _splash_block(seconds: int) -> str:
    # GRUB's only timer counts whole seconds, so the bar is paced by drawing: each frame takes
    # about 1/20 s to load and show, and is drawn `seconds` times. A slow PC just takes longer.
    frames = " ".join(f"{k:02d}" for k in range(SPLASH_FRAMES + 1)) + f" {SPLASH_FRAMES:02d}" * 2
    return (f"{SPLASH_BEGIN}\n"
            "# Added by Helix Boot (helix splash): its picture for a moment before the menu, with a\n"
            "# loading bar when ventoy/theme/splash/ has the frames. ventoy/theme/splash.png on the\n"
            "# stick; remove it and this does nothing.\n"
            'if [ "$vtoy_display_mode" != "CLI" -a -f "$vtoy_iso_part/ventoy/theme/splash.png" ]; then\n'
            '    set helix_splash="$vtoy_iso_part/ventoy/theme/splash"\n'
            f'    if [ -f "$helix_splash/{SPLASH_FRAMES:02d}.jpg" ]; then\n'
            f"        for f in {frames}; do\n"
            f"            for r in {' '.join(str(i + 1) for i in range(seconds))}; do\n"
            '                background_image -m stretch "$helix_splash/$f.jpg"\n'
            "                clear\n"
            "            done\n"
            "        done\n"
            "    else\n"
            '        background_image -m stretch "$vtoy_iso_part/ventoy/theme/splash.png"\n'
            "        clear\n"
            f"        sleep --interruptible {seconds}\n"
            "    fi\n"
            "    background_image\n"
            "    unset helix_splash\n"
            "fi\n"
            f"{SPLASH_END}\n\n")


SPLASH_BAR = ("#00dceb", "#b55eff")   # the loading bar, left to right, unless a preset names its own


def _rgb(color: str) -> tuple[int, int, int]:
    return tuple(int(color[i:i + 2], 16) for i in (1, 3, 5))


def _splash_frames(cfg: Config, splash: Path, bar: tuple[str, str] = SPLASH_BAR) -> Path | None:
    """The splash with a loading bar filling up across it, as JPEG frames for the boot script
    (GRUB draws a 1080p JPEG about three times as fast as a PNG): the folder holding them, named
    after the picture and the bar's colours. Made once and kept in the cache. Needs Pillow;
    without it (None) the splash shows as a still picture."""
    out = cfg.cache / "splash" / _splash_key(splash, bar)
    names = [f"{k:02d}.jpg" for k in range(SPLASH_FRAMES + 1)]
    if not all((out / n).is_file() for n in names):
        try:
            from PIL import Image, ImageDraw, ImageFilter
        except ImportError:
            info("no loading bar on the splash: that needs Pillow (python-pillow / pip install pillow)")
            return None
        try:
            with Image.open(splash) as im:
                base = im.convert("RGB").resize((1920, 1080), Image.Resampling.LANCZOS).convert("RGBA")
        except OSError as e:
            warn(f"couldn't read {splash.name} for the loading bar: {e}")
            return None
        bw, bh, x0, y0 = 560, 8, 680, 1000          # bottom centre, as on the theme's splash.png
        left, right = _rgb(bar[0]), _rgb(bar[1])
        track = Image.new("RGBA", base.size)
        ImageDraw.Draw(track).rounded_rectangle((x0 - 2, y0 - 2, x0 + bw + 1, y0 + bh + 1), radius=6,
                                                fill=(8, 6, 20, 200), outline=(186, 171, 211, 90))
        base = Image.alpha_composite(base, track)
        grad = Image.new("RGB", (bw, bh))
        gd = ImageDraw.Draw(grad)
        for x in range(bw):
            t = x / (bw - 1)
            gd.line((x, 0, x, bh), fill=tuple(round(c + (d - c) * t) for c, d in zip(left, right)))
        tmp = out.with_name(out.name + ".part")
        shutil.rmtree(tmp, ignore_errors=True)
        tmp.mkdir(parents=True)
        for k, name in enumerate(names):
            img, fill = base, round(bw * k / SPLASH_FRAMES)
            if fill:
                glow = Image.new("RGBA", base.size)
                mask = Image.new("L", (fill, bh))
                ImageDraw.Draw(mask).rounded_rectangle((0, 0, fill - 1, bh - 1), radius=4, fill=255)
                glow.paste(grad.crop((0, 0, fill, bh)), (x0, y0), mask)
                img = Image.alpha_composite(Image.alpha_composite(img, glow.filter(ImageFilter.GaussianBlur(7))), glow)
            img.convert("RGB").save(tmp / name, quality=90, optimize=True)
        shutil.rmtree(out, ignore_errors=True)
        os.replace(tmp, out)
        kept = sorted((d for d in out.parent.iterdir() if d.is_dir()), key=lambda d: d.stat().st_mtime)
        for old in kept[:-8]:                       # frames for pictures no longer in use
            shutil.rmtree(old, ignore_errors=True)
    return out


def _splash_key(splash: Path, bar: tuple[str, str]) -> str:
    """Names a splash's frames: the picture, the bar's colours, and -1 for this bar's drawing."""
    return f"{file_hash(splash)[:16]}-{bar[0][1:]}{bar[1][1:]}-1"


# ── The stick's look ─────────────────────────────────────────────────────────
# Sync and unpack write the theme to .helix-boot/theme on the stick, as it is in the repo: the
# default, its presets (presets/<id>/), icon packs (icon-packs/<id>/) and your own pictures
# (mine/). ventoy/theme and ventoy/ventoy.json are built from that and the choice in look.json,
# so `helix theme` changes the look from any PC, and a refresh keeps it.

ICON_STYLES = ("grey",)       # ways the stick's icons can be redrawn (with Pillow); see _restyle_icons


def _restyle_icons(folder: Path, style: str) -> None:
    """Redraw every icon in a built theme's icons folder in a style. grey: shades of grey at
    full contrast, which turns a one-colour icon white. Without Pillow they stay as they are."""
    try:
        from PIL import Image
    except ImportError:
        info(f"the icons stay in colour: {style} icons need Pillow (python-pillow / pip install pillow)")
        return
    for f in sorted(folder.glob("*.png")):
        try:
            with Image.open(f) as im:
                im = im.convert("RGBA")
        except OSError:
            continue
        alpha = im.getchannel("A")
        grey = im.convert("RGB").convert("L")
        seen = [v for v, n in enumerate(grey.histogram(alpha.point(lambda a: 255 if a > 40 else 0))) if n]
        lo, hi = (seen[0], seen[-1]) if seen else (0, 255)
        if hi - lo < 40:        # one flat colour: its shape is the picture
            grey = grey.point(lambda v: 255)
        else:
            grey = grey.point(lambda v: 0 if v <= lo else 255 if v >= hi else round(255 * (v - lo) / (hi - lo)))
        Image.merge("RGBA", (grey, grey, grey, alpha)).save(f, optimize=True)


def _preset_meta(folder: Path) -> dict:
    """A theme folder's preset.toml: its title and the colours the menu and splash take from it."""
    meta = {"title": folder.name, "description": "", "muted": "#baabd3", "bar": SPLASH_BAR,
            "standalone": False, "plain": False, "icons": "", "tip": None, "version": None}
    try:
        got = tomllib.loads((folder / "preset.toml").read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return meta
    colour = re.compile(r"#[0-9a-fA-F]{6}")
    for key in ("title", "description"):
        if isinstance(got.get(key), str):
            meta[key] = got[key]
    if isinstance(got.get("muted"), str) and colour.fullmatch(got["muted"]):
        meta["muted"] = got["muted"]
    bar = got.get("bar")
    if isinstance(bar, list) and len(bar) == 2 and all(isinstance(c, str) and colour.fullmatch(c) for c in bar):
        meta["bar"] = (bar[0], bar[1])
    meta["standalone"] = got.get("standalone") is True      # its own layout: the theme isn't laid under it
    meta["plain"] = got.get("plain") is True                # the plain choice, in place of Ventoy's own look
    if got.get("icons") in ICON_STYLES:                     # how its icons are drawn, unless a pack is picked
        meta["icons"] = got["icons"]
    for key in ("tip", "version"):                          # where the tip and Ventoy's version go: [left, top]
        at = got.get(key)
        if isinstance(at, list) and len(at) == 2 and all(isinstance(v, str) and re.fullmatch(r"\d{1,3}%", v) for v in at):
            meta[key] = (at[0], at[1])
    return meta


def _look(mnt: Path) -> dict:
    """The stick's chosen look; anything missing or unreadable falls back to the default."""
    look = dict(LOOK_DEFAULT)
    try:
        got = json.loads((mnt / LOOK_FILE).read_text(encoding="utf-8"))
    except (OSError, ValueError):
        return look
    known = {"background": ("theme", "custom"), "splash": ("auto", "theme", "custom", "off")}
    if isinstance(got, dict):   # the stick is anyone's to edit: a theme or pack by name, the rest from a list
        look.update({k: v for k, v in got.items() if k in look and isinstance(v, str) and SAFE_NAME.fullmatch(v)
                     and v in known.get(k, (v,))})
    return look


def _look_choices(mnt: Path) -> tuple[dict[str, dict], dict[str, dict]]:
    """The themes and icon packs this stick can switch between, by id."""
    src = mnt / THEME_SRC
    themes = {"default": _preset_meta(src)}
    themes["default"]["title"] += " (default)" if (src / "preset.toml").is_file() else ""
    for d in sorted((src / "presets").glob("*/")):
        if SAFE_NAME.fullmatch(d.name) and d.name not in ("default", "off") and (d / "theme.txt").is_file():
            themes[d.name] = _preset_meta(d)
    if not any(t["plain"] for t in themes.values()):   # a plain preset stands in for Ventoy's own look
        themes["off"] = {"title": "Off", "description": "Ventoy's own look: no theme, no icons.", "plain": False}
    packs = {"auto": {"title": "Automatic", "description": "The theme's own style: logos in colour, or grey where it asks for that."},
             "logos": {"title": "Logos", "description": "The tools' own logos in colour, and your icons from byo/icons/."},
             "grey": {"title": "Greyscale", "description": "The same icons in shades of grey."}}
    for d in sorted((src / "icon-packs").glob("*/")):
        if SAFE_NAME.fullmatch(d.name) and d.name not in packs and d.name != "off":
            try:
                got = tomllib.loads((d / "pack.toml").read_text(encoding="utf-8"))
            except (OSError, ValueError):
                got = {}
            packs[d.name] = {"title": str(got.get("title") or d.name), "description": str(got.get("description") or "")}
    packs["off"] = {"title": "Off", "description": "No icons: just the names."}
    return themes, packs


def _theme_id(themes: dict[str, dict], wanted: str) -> str:
    """The theme a name stands for: itself; `off` is the plain preset where the theme has one
    (so "no theme" is a quiet theme rather than Ventoy's white one); anything unknown, the default."""
    if wanted in themes:
        return wanted
    return next((k for k, t in themes.items() if t["plain"]), "default") if wanted == "off" else "default"


def _build_look(cfg: Config, mnt: Path, look: dict, new: Path, frames: bool = True) -> dict:
    """Build the theme folder for a look into `new` (emptied first), from the theme on the stick;
    return the boot menu (ventoy.json) that goes with it."""
    src = mnt / THEME_SRC
    doc = json.loads((mnt / BASE_JSON).read_text(encoding="utf-8"))
    themes, packs = _look_choices(mnt)
    theme = _theme_id(themes, look["theme"])
    themed = theme != "off" and (src / "theme.txt").is_file()
    preset = src / "presets" / theme if themed and theme != "default" else None
    meta = _preset_meta(preset or src)
    icons = look["icons"] if look["icons"] in packs else "auto"
    style = "grey" if icons == "grey" else meta["icons"] if icons == "auto" else ""
    pack = src / "icon-packs" / icons if icons not in ("auto", "logos", "grey", "off") else None
    shutil.rmtree(new, ignore_errors=True)
    new.mkdir(parents=True)

    def lay(folder: Path, dest: Path, skip: tuple[str, ...] = ()) -> None:
        for f in sorted(folder.rglob("*")):
            rel = f.relative_to(folder)
            if f.is_file() and rel.parts[0] not in skip:
                (dest / rel).parent.mkdir(parents=True, exist_ok=True)
                shutil.copy2(f, dest / rel)

    apart = ("presets", "icon-packs", "mine", "splash", "icons", "splash.png", "preset.toml", "pack.toml")
    if themed:
        for layer in (None if meta["standalone"] else src, preset):
            if layer:
                lay(layer, new, skip=apart)
        if look["background"] == "custom" and (mnt / LOOK_DIR / "background.png").is_file():
            shutil.copy2(mnt / LOOK_DIR / "background.png", new / _desktop_image(new))
        if icons == "off":      # no gap where the icons were
            text = (new / "theme.txt").read_text(encoding="utf-8")
            text = re.sub(r"^(\s*(?:icon_width|icon_height|item_icon_space)\s*=\s*)\d+", r"\g<1>0", text, flags=re.M)
            (new / "theme.txt").write_text(text, encoding="utf-8")
        else:                   # later layers win: the theme's, the preset's, your own, the pack's
            for layer in (src / "icons", preset / "icons" if preset else None, src / "mine" / "icons", pack):
                if layer and layer.is_dir():
                    lay(layer, new / "icons", skip=apart)
            if style and (new / "icons").is_dir():
                _restyle_icons(new / "icons", style)
    # the splash: your own (set on the stick, or byo/splash.png), else the theme's
    mine, custom = src / "mine" / "splash.png", mnt / LOOK_DIR / "splash.png"
    own = preset / "splash.png" if preset and (preset / "splash.png").is_file() else src / "splash.png"
    yours = custom if look["splash"] == "custom" and custom.is_file() else mine if mine.is_file() else None
    pick = None if look["splash"] == "off" else own if look["splash"] == "theme" else yours or own
    if pick and pick.is_file() and (themed or pick != own):   # no theme: no splash of its either
        shutil.copy2(pick, new / "splash.png")
        bar = meta["bar"] if pick == own else SPLASH_BAR
        key = _splash_key(pick, bar) if frames else ""
        ready = src / "splash" if frames else None
        if frames and not ((ready / "for.txt").is_file()
                           and (ready / "for.txt").read_text(encoding="utf-8").strip() == key):
            ready = _splash_frames(cfg, pick, bar)
        if ready:
            (new / "splash").mkdir()
            for f in sorted(ready.glob("*.jpg")):
                shutil.copy2(f, new / "splash" / f.name)
    if "theme" in doc and not themed:           # Ventoy's own look, and where its tips go there
        del doc["theme"]
        if "menu_tip" in doc:
            doc["menu_tip"].update(left="10%", top="80%", color="#7fb4ff")
    elif "theme" in doc:
        doc["theme"]["ventoy_color"] = meta["muted"]
        doc["theme"]["fonts"] = [f"/ventoy/theme/{f.relative_to(new).as_posix()}" for f in sorted(new.rglob("*.pf2"))]
        if meta["version"]:
            doc["theme"]["ventoy_left"], doc["theme"]["ventoy_top"] = meta["version"]
        if "menu_tip" in doc:
            doc["menu_tip"]["color"] = meta["muted"]
            if meta["tip"]:
                doc["menu_tip"]["left"], doc["menu_tip"]["top"] = meta["tip"]
    have = {f.stem for f in (new / "icons").glob("*.png")}
    if "menu_class" in doc:
        doc["menu_class"] = [c for c in doc["menu_class"] if c.get("class") in have]
        if not doc["menu_class"]:
            del doc["menu_class"]
    return doc


def _desktop_image(theme: Path) -> str:
    """The background's file name in a theme folder, from its theme.txt."""
    name = re.search(r'^desktop-image:\s*"([^"/\\]+)"', (theme / "theme.txt").read_text(encoding="utf-8"), re.M)
    return name.group(1) if name else "background.png"


def _apply_look(cfg: Config, mnt: Path, changed: bool = True) -> None:
    """Build ventoy/theme and ventoy/ventoy.json from the theme on the stick and its look.
    `changed` False: what they are built from is as it was, so only rebuild if the look, this
    version or Pillow's presence (greyscale icons, the loading bar) differ from last time."""
    if not (mnt / BASE_JSON).is_file():
        return                     # filled by an older Helix Boot or pack: the menu is as it was written
    out = mnt / "ventoy" / "theme"
    (mnt / "ventoy").mkdir(exist_ok=True)
    look = _look(mnt)
    stamp = {"look": look, "helix": __version__, "pillow": importlib.util.find_spec("PIL") is not None}
    built = mnt / STATE_DIR / "built.json"
    try:
        same = json.loads(built.read_text(encoding="utf-8")) == stamp
    except (OSError, ValueError):
        same = False
    if same and not changed and (mnt / "ventoy" / "ventoy.json").is_file() \
            and (out.is_dir() or not (mnt / THEME_SRC / "theme.txt").is_file() or look["theme"] == "off"):
        return
    new = out.with_name("theme.helix-new")
    doc = _build_look(cfg, mnt, look, new)
    if any(new.iterdir()) or (mnt / THEME_SRC / "theme.txt").is_file():
        shutil.rmtree(out, ignore_errors=True)
    if any(new.iterdir()):
        os.replace(new, out)
    else:                          # no theme on the stick, or it and the splash are off
        new.rmdir()
    (mnt / "ventoy" / "ventoy.json").write_text(json.dumps(doc, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
    built.write_text(json.dumps(stamp) + "\n", encoding="utf-8")


def _own_picture(src: Path, dst: Path, dim: int = 0) -> None:
    """Your picture as the stick's background or splash: 1920x1080 (cropped to fill), optionally
    dimmed so the menu's text stays readable. Pillow does that; without it a PNG is taken as is."""
    dst.parent.mkdir(parents=True, exist_ok=True)
    try:
        from PIL import Image, ImageOps
    except ImportError:
        if dim or src.read_bytes()[:8] != b"\x89PNG\r\n\x1a\n":
            raise RescueError("resizing, dimming or converting a picture needs Pillow "
                              "(python-pillow / pip install pillow); a PNG can be used as it is") from None
        shutil.copy2(src, dst)
        return
    try:
        with Image.open(src) as im:
            img = ImageOps.fit(im.convert("RGB"), (1920, 1080), method=Image.Resampling.LANCZOS)
    except OSError as e:
        raise RescueError(f"{src} isn't a picture this can read: {e}") from None
    if dim:
        img = Image.blend(img, Image.new("RGB", img.size, (0, 0, 0)), dim / 100)
    tmp = dst.with_name(dst.name + ".part")
    img.save(tmp, format="PNG", optimize=True)
    os.replace(tmp, dst)


def look_report(mnt: Path, look: dict | None = None) -> dict:
    """A stick's look and what it can be changed to, for `helix theme --json` and the apps."""
    themes, packs = _look_choices(mnt)
    look = dict(look or _look(mnt))
    look["theme"] = _theme_id(themes, look["theme"])
    return {
        "look": look,
        "themes": [{"id": k, **{f: v[f] for f in ("title", "description")}} for k, v in themes.items()],
        "icon_packs": [{"id": k, **v} for k, v in packs.items()],
        "own_splash": (mnt / THEME_SRC / "mine" / "splash.png").is_file(),
        "custom": {w: (mnt / LOOK_DIR / f"{w}.png").is_file() for w in ("background", "splash")},
    }


def look_changes(mnt: Path, theme=None, icons=None, background=None, splash=None, dim: int = 0,
                 reset: bool = False) -> tuple[dict, dict[str, Path]]:
    """What the options ask for: the new look, and the pictures (background / splash) to take in."""
    if not (mnt / BASE_JSON).is_file():
        raise RescueError("this stick was filled by an older Helix Boot. Refresh it once with this "
                          "version (./refresh.sh), then choose its look.")
    themes, packs = _look_choices(mnt)
    look = dict(LOOK_DEFAULT if reset else _look(mnt))
    if theme:
        if theme not in themes and theme != "off":
            raise RescueError(f"no theme called {theme!r} on this stick. There are: {', '.join(themes)}")
        look["theme"] = _theme_id(themes, theme)
    if icons:
        if icons not in packs:
            raise RescueError(f"no icon pack called {icons!r} on this stick. There are: {', '.join(packs)}")
        look["icons"] = icons
    if not 0 <= dim <= 90:
        raise RescueError("--dim is a percentage from 0 to 90")
    pictures: dict[str, Path] = {}
    for what, value, kept in (("background", background, ("theme",)), ("splash", splash, ("auto", "theme", "off"))):
        if value in kept:
            look[what] = value
        elif value == "custom":         # the picture of yours already on the stick
            if not (mnt / LOOK_DIR / f"{what}.png").is_file():
                raise RescueError(f"--{what} custom: the stick has no {what} picture of yours yet; give a file")
            look[what] = "custom"
        elif value:
            picture = Path(value).expanduser()
            if not picture.is_file():
                raise RescueError(f"--{what}: {value} is neither a picture file nor one of: {', '.join(kept)}")
            pictures[what] = picture
            look[what] = "custom"
    if dim and "background" not in pictures:
        raise RescueError("--dim goes with --background PICTURE")
    return look, pictures


def set_look(cfg: Config, mnt: Path, look: dict, pictures: dict[str, Path] | None = None, dim: int = 0,
             force: bool = False) -> bool:
    """Put a look on the stick (False: it already has it). The choice is kept there."""
    pictures = pictures or {}
    state_dir, state = _open_stick(mnt, False, cfg)
    if look == _look(mnt) and not pictures and not force:
        return False
    for what, picture in pictures.items():
        _own_picture(picture, mnt / LOOK_DIR / f"{what}.png", dim if what == "background" else 0)
    vjson = _keep_edited_json(mnt, state)
    (mnt / STATE_DIR).mkdir(exist_ok=True)
    (mnt / LOOK_FILE).write_text(json.dumps(look, indent=2) + "\n", encoding="utf-8")
    _apply_look(cfg, mnt)
    if (state_dir / "state.json").is_file():       # the rewritten menu is ours, not a hand edit
        state["ventoy_json_sha"] = file_hash(vjson)
        (state_dir / "state.json").write_text(json.dumps(state, indent=2) + "\n", encoding="utf-8")
    _flush_volume(mnt)
    return True


# A saved look: one small zip with the choice and your own pictures and icons, to keep it safe
# or put it on another stick. Pictures only, checked before anything is written.
LOOK_SAVE = "helix-look.json"
LOOK_SAVE_FILES = re.compile(r"(look/(background|splash)|mine/splash|mine/icons/[A-Za-z0-9][A-Za-z0-9._-]{0,80})\.png")
LOOK_SAVE_MAX = 64 << 20             # a whole saved look; a picture is a few MB


def export_look(mnt: Path, out: Path) -> Path:
    """Save the stick's look to a zip."""
    if not (mnt / BASE_JSON).is_file():
        raise RescueError("this stick was filled by an older Helix Boot. Refresh it once with this version first.")
    files = [p for d in (mnt / LOOK_DIR, mnt / THEME_SRC / "mine") if d.is_dir() for p in sorted(d.rglob("*.png"))]
    out = out if out.suffix.lower() == ".zip" else out.with_name(out.name + ".zip")
    out.parent.mkdir(parents=True, exist_ok=True)
    tmp = out.with_name(out.name + ".part")
    with zipfile.ZipFile(tmp, "w", zipfile.ZIP_DEFLATED) as zf:
        zf.writestr(LOOK_SAVE, json.dumps({"format": 1, "look": _look(mnt), "helix": __version__,
                                           "saved": dt.date.today().isoformat()}, indent=2) + "\n")
        for p in files:
            base = mnt / LOOK_DIR if p.is_relative_to(mnt / LOOK_DIR) else mnt / THEME_SRC
            arc = ("look/" if base == mnt / LOOK_DIR else "") + p.relative_to(base).as_posix()
            if LOOK_SAVE_FILES.fullmatch(arc):
                zf.write(p, arc)
    os.replace(tmp, out)
    return out


def import_look(cfg: Config, mnt: Path, saved: Path) -> list[str]:
    """Put a saved look on the stick; return notes on what couldn't be used (a theme this stick lacks)."""
    if not (mnt / BASE_JSON).is_file():
        raise RescueError("this stick was filled by an older Helix Boot. Refresh it once with this version first.")
    try:
        zf = zipfile.ZipFile(saved)
    except (OSError, zipfile.BadZipFile):
        raise RescueError(f"{saved} isn't a saved Helix Boot look") from None
    with zf:
        try:
            meta = json.loads(zf.read(LOOK_SAVE))
        except (KeyError, ValueError):
            raise RescueError(f"{saved} isn't a saved Helix Boot look") from None
        members = [m for m in zf.infolist() if not m.is_dir() and m.filename != LOOK_SAVE]
        for m in members:
            if not LOOK_SAVE_FILES.fullmatch(m.filename):
                raise RescueError(f"{saved} holds something that isn't part of a look: {m.filename!r}")
        if sum(m.file_size for m in members) > LOOK_SAVE_MAX:
            raise RescueError(f"{saved} is too big to be a saved look")
        data = {m.filename: zf.read(m) for m in members}
    for name, blob in data.items():
        if not blob.startswith(b"\x89PNG\r\n\x1a\n"):
            raise RescueError(f"{saved}: {name} isn't a PNG picture")

    # The choice, as far as this stick has it: a theme or icon pack it lacks falls back to the default.
    got = meta.get("look") if isinstance(meta, dict) and isinstance(meta.get("look"), dict) else {}
    themes, packs = _look_choices(mnt)
    look, notes = dict(LOOK_DEFAULT), []
    for key, known in (("theme", set(themes) | {"off"}), ("icons", set(packs))):
        value = got.get(key)
        if isinstance(value, str) and value in known:
            look[key] = _theme_id(themes, value) if key == "theme" else value
        elif value:
            notes.append(f"this stick has no {key} {str(value)[:40]!r}: using the default")
    for key, known in (("background", ("theme", "custom")), ("splash", ("auto", "theme", "custom", "off"))):
        value = got.get(key)
        if value in known and (value != "custom" or f"look/{key}.png" in data):
            look[key] = value

    _open_stick(mnt, False, cfg)
    for d in (mnt / LOOK_DIR, mnt / THEME_SRC / "mine"):   # the saved look replaces your pictures and icons
        shutil.rmtree(d, ignore_errors=True)
    for name, blob in data.items():
        dst = mnt / (STATE_DIR + "/" + name if name.startswith("look/") else f"{THEME_SRC}/{name}")
        dst.parent.mkdir(parents=True, exist_ok=True)
        dst.write_bytes(blob)
    # Keep them on the next update unless that PC has icons or a splash of its own in byo/
    state_path = mnt / STATE_DIR / "state.json"
    state = json.loads(state_path.read_text(encoding="utf-8")) if state_path.is_file() else {}
    state["mine_by"] = {k: "saved look" for k, sub in (("icons", "mine/icons"), ("splash", "mine/splash.png"))
                        if (mnt / THEME_SRC / sub).exists()}
    state_path.write_text(json.dumps(state, indent=2) + "\n", encoding="utf-8")
    set_look(cfg, mnt, look, force=True)
    return notes


def look_preview(cfg: Config, mnt: Path, look: dict, out: Path, pictures: dict[str, Path] | None = None,
                 dim: int = 0, size: tuple[int, int] = (960, 540)) -> Path:
    """Draw how the boot menu would look with `look` (and a background picture not yet taken in),
    without touching the stick's menu. A close sketch from the real theme files, not a boot
    capture: Ventoy draws the real thing. Needs Pillow."""
    try:
        from PIL import Image, ImageDraw, ImageFont, ImageOps
    except ImportError:
        raise RescueError("a preview needs Pillow (python-pillow / pip install pillow)") from None
    W, H = 1920, 1080

    def font(px: int, bold: bool = False):
        for name in (("DejaVuSans-Bold.ttf", "segoeuib.ttf", "arialbd.ttf") if bold
                     else ("DejaVuSans.ttf", "segoeui.ttf", "arial.ttf")):
            try:
                return ImageFont.truetype(name, px)
            except OSError:
                continue
        try:
            return ImageFont.load_default(px)
        except TypeError:           # an older Pillow: its one small built-in font
            return ImageFont.load_default()

    work = cfg.cache / "look-preview"
    doc = _build_look(cfg, mnt, look, work, frames=False)
    rows = [a for a in doc.get("menu_alias", []) if "dir" in a] or doc.get("menu_alias", [])
    tips = (doc.get("menu_tip") or {}).get("tips") or []
    try:
        if "theme" not in doc:      # Ventoy's own look: light sky, grey box, plain text
            img = Image.new("RGB", (W, H), (236, 238, 242)).convert("RGBA")
            d = ImageDraw.Draw(img)
            d.text((W // 2, 150), "Ventoy", font=font(190, True), fill=(88, 166, 255), anchor="mm")
            d.rectangle((192, 440, 1728, 940), fill=(122, 126, 132))
            d.rectangle((250, 468, 1670, 500), fill=(84, 142, 196))
            for i, a in enumerate(rows[:14]):
                d.text((310, 484 + i * 30), a["alias"], font=font(22), fill=(232, 236, 240), anchor="lm")
            if tips:
                d.text((192, 864 + 90), tips[0]["tip"], font=font(20), fill=(127, 180, 255), anchor="lm")
            d.text((96, 1036), "1.1.x UEFI   www.ventoy.net   L:Language  F1:Help  F2:Browse  F3:TreeView",
                   font=font(20), fill=(60, 110, 200), anchor="lm")
        else:
            text = (work / "theme.txt").read_text(encoding="utf-8")

            def settings(block: str) -> dict:          # "#rrggbb" isn't a comment
                return {k: quoted or bare.strip() for k, quoted, bare in
                        re.findall(r'(\w+)\s*=\s*(?:"([^"\n]*)"|([^#\n}]*))', block)}

            def px(v: str, full: int) -> int:          # "5%", "40", "100%-70", "81%+24"
                m = re.fullmatch(r"\s*(?:(\d+(?:\.\d+)?)%)?\s*([+-]?\d+)?\s*", v)
                return round(float(m.group(1) or 0) * full / 100) + int(m.group(2) or 0) if m else 0

            def box(pattern: str, x: int, y: int, w: int, h: int) -> None:   # GRUB's nine-slice boxes
                prefix = pattern.split("*")[0]
                parts = {part: Image.open(f).convert("RGBA") for part in ("nw", "n", "ne", "w", "c", "e", "sw", "s", "se")
                         if (f := work / f"{prefix}{part}.png").is_file()}
                if not prefix or "c" not in parts or w <= 0 or h <= 0:
                    return
                (left, top) = parts["nw"].size if "nw" in parts else (0, 0)
                (right, bottom) = parts["se"].size if "se" in parts else (0, 0)
                xs, ys = (x, x + left, x + w - right), (y, y + top, y + h - bottom)
                ws, hs = (left, w - left - right, right), (top, h - top - bottom, bottom)
                for r, names in enumerate((("nw", "n", "ne"), ("w", "c", "e"), ("sw", "s", "se"))):
                    for c, part in enumerate(names):
                        if part in parts and ws[c] > 0 and hs[r] > 0:
                            img.alpha_composite(parts[part].resize((ws[c], hs[r])), (xs[c], ys[r]))

            menu = re.search(r"\+ boot_menu \{(.*?)\}", text, re.S)
            props = settings(menu.group(1) if menu else "")
            picture = (pictures or {}).get("background")
            with Image.open(picture or work / _desktop_image(work)) as im:
                img = ImageOps.fit(im.convert("RGB"), (W, H), method=Image.Resampling.LANCZOS)
            if picture and dim:
                img = Image.blend(img, Image.new("RGB", img.size, (0, 0, 0)), dim / 100)
            img = img.convert("RGBA")
            x, y = px(props.get("left", "5%"), W), px(props.get("top", "20%"), H)
            w, h = px(props.get("width", "49%"), W), px(props.get("height", "60%"), H)
            box(props.get("menu_pixmap_style", ""), x, y, w, h)
            pad, icon = px(props.get("item_padding", "0"), W), px(props.get("icon_width", "32"), W)
            gap, row_h = px(props.get("item_icon_space", "4"), W), px(props.get("item_height", "40"), H)
            step = row_h + px(props.get("item_spacing", "0"), H)
            size_of = lambda name: int(m.group(1)) if (m := re.search(r"(\d+)\s*$", props.get(name, ""))) else 18  # noqa: E731
            edge = 8 if props.get("menu_pixmap_style") else 0
            classes = {c["dir"]: c["class"] for c in doc.get("menu_class", []) if "dir" in c}
            d = ImageDraw.Draw(img)
            for i, a in enumerate(rows[:max(1, (h - 2 * edge) // step)]):
                ry = y + edge + i * step
                box(props.get("selected_item_pixmap_style" if i == 0 else "item_pixmap_style", ""),
                    x + edge, ry, w - 2 * edge - (16 if props.get("scrollbar") == "true" else 0), row_h)
                f = work / "icons" / f"{classes.get(a.get('dir'), '')}.png"
                if icon and f.is_file():
                    with Image.open(f) as im:
                        img.alpha_composite(im.convert("RGBA").resize((icon, icon), Image.Resampling.LANCZOS),
                                            (x + edge + pad, ry + (row_h - icon) // 2))
                d.text((x + edge + pad + (icon + gap if icon else 0), ry + row_h // 2), a["alias"],
                       font=font(size_of("selected_item_font" if i == 0 and "selected_item_font" in props else "item_font"),
                                 i == 0 and "Bold" in props.get("selected_item_font", "")),
                       fill=props.get("selected_item_color" if i == 0 else "item_color", "#ffffff"), anchor="lm")
            for block in re.findall(r"\+ image\s*\{(.*?)\}", text, re.S):          # e.g. Standby's power symbol
                at = settings(block)
                if (work / at.get("file", "")).is_file() and at.get("file"):
                    with Image.open(work / at["file"]) as im:
                        img.alpha_composite(im.convert("RGBA"), (px(at.get("left", "0"), W), px(at.get("top", "0"), H)))
            for block in text.split("+ hbox")[1:]:                                # Ventoy's hotkeys, the key hint
                at = settings(block)
                shown = {"@VTOY_HOTKEY_TIP@": "L:Language  F1:Help  F2:Browse  F3:TreeView  F4:Localboot  F5:Tools  F6:ExMenu"
                         }.get(at.get("text", ""), "" if at.get("text", "@").startswith("@") else at["text"])
                if shown:
                    d.text((px(at.get("left", "0"), W), px(at.get("top", "0"), H) + 10), shown, font=font(16),
                           fill=at.get("color", "#ffffff"), anchor="lm")
            muted, tip = doc["theme"].get("ventoy_color", "#baabd3"), doc.get("menu_tip") or {}
            if tips:
                d.text((px(tip.get("left", "5%"), W), px(tip.get("top", "82%"), H) + 10), tips[0]["tip"], font=font(16),
                       fill=tip.get("color", muted), anchor="lm")
            d.text((px(doc["theme"].get("ventoy_left", "78%"), W), px(doc["theme"].get("ventoy_top", "94%"), H) + 10),
                   "1.1.x UEFI  www.ventoy.net", font=font(16), fill=muted, anchor="lm")
        out.parent.mkdir(parents=True, exist_ok=True)
        img.convert("RGB").resize(size, Image.Resampling.LANCZOS).save(out)
    except OSError as e:
        raise RescueError(f"couldn't draw the preview: {e}") from None
    finally:
        shutil.rmtree(work, ignore_errors=True)
    return out


def _print_look(mnt: Path, report: dict, numbered: bool = False) -> None:
    look = report["look"]
    themes = {t["id"]: t for t in report["themes"]}
    packs = {p["id"]: p for p in report["icon_packs"]}
    stock = look["theme"] == "off"       # Ventoy's own look has no icons or background of ours
    splash = {"auto": "your own (byo/splash.png)" if report["own_splash"] else "the theme's",
              "theme": "the theme's", "custom": "your picture", "off": "none"}[look["splash"]]
    head(f"The look of {mnt}")
    for n, (label, value) in enumerate((
            ("theme", themes.get(look["theme"], themes["default"])["title"]),
            ("icons", "none (no theme)" if stock else packs.get(look["icons"], packs["auto"])["title"]),
            ("background", "Ventoy's" if stock else "your picture" if look["background"] == "custom" else "the theme's"),
            ("splash", "none (no theme)" if stock and splash == "the theme's" else splash)), 1):
        print(f"  {str(n) + ')  ' if numbered else ''}{label:<11} {value}")


def _look_menu(cfg: Config, mnt: Path) -> int:
    """Change the look by picking from numbered lists, until done."""
    def ask(prompt: str) -> str:
        try:
            return input(f"  {prompt} ").strip()
        except EOFError:
            return "q"

    def choose(title: str, options: list[tuple[str, str]]) -> str | None:
        head(title)
        for n, (_, text) in enumerate(options, 1):
            print(f"  {n})  {text}")
        got = ask("Which one? (Enter: leave it)")
        return options[int(got) - 1][0] if got.isdigit() and 0 < int(got) <= len(options) else None

    def picture(what: str) -> str | None:
        got = ask(f"The picture to use as the {what} (a file's path; Enter: leave it):").strip("'\"")
        if got and not Path(got).expanduser().is_file():
            warn(f"{got} isn't a file")
            return None
        return got or None

    while True:
        report = look_report(mnt)
        _print_look(mnt, report, numbered=True)
        print("  p)  preview it        r)  back to the default look        q)  done")
        pick = ask("Change which?").lower()
        change: dict = {}
        if pick in ("q", ""):
            return 0
        if pick == "1":
            change["theme"] = choose("Themes", [(t["id"], f"{t['title']}" + (f": {t['description']}" if t["description"] else ""))
                                                for t in report["themes"]])
        elif pick == "2":
            change["icons"] = choose("Icon packs", [(p["id"], f"{p['title']}: {p['description']}") for p in report["icon_packs"]])
        elif pick == "3":
            got = choose("Background", [("theme", "The theme's"), ("picture", "Your own picture…")])
            change["background"] = picture("background") if got == "picture" else got
            if got == "picture" and change["background"]:
                dim = ask("Darken it by how much, 0-90 %? (Enter: 40, so the menu stays readable)") or "40"
                change["dim"] = int(dim) if dim.isdigit() else 40
        elif pick == "4":
            got = choose("Splash, the picture before the menu", [
                ("auto", "Yours from byo/splash.png, else the theme's"), ("theme", "The theme's"),
                ("picture", "Your own picture…"), ("off", "None")])
            change["splash"] = picture("splash") if got == "picture" else got
        elif pick == "r":
            change["reset"] = True
        elif pick == "p":
            try:
                shown = look_preview(cfg, mnt, report["look"], cfg.cache / "look-preview.png")
            except RescueError as e:
                warn(str(e))
                continue
            ok(f"Preview: {shown}")
            opener = shutil.which("xdg-open") or shutil.which("open")
            if hasattr(os, "startfile"):
                os.startfile(shown)  # noqa: S606
            elif opener:
                subprocess.Popen([opener, str(shown)], stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
            continue
        change = {k: v for k, v in change.items() if v and (k != "dim" or change.get("background"))}
        if not change:
            continue
        try:
            look, pictures = look_changes(mnt, **change)
            if set_look(cfg, mnt, look, pictures, change.get("dim", 0)):
                ok("Look changed")
        except RescueError as e:
            warn(str(e))


def cmd_theme(cfg: Config, args) -> int:
    """Show or change a stick's look: a preset theme (or none), an icon pack (or none), your own
    background and splash. The choice is kept on the stick, so a refresh doesn't undo it."""
    mnt = Path(args.stick).expanduser().resolve()
    _open_stick(mnt, False, cfg)
    if getattr(args, "export", None):
        ok(f"Look saved to {export_look(mnt, Path(args.export).expanduser())}")
        return 0
    if getattr(args, "import_", None):
        for note in import_look(cfg, mnt, Path(args.import_).expanduser()):
            warn(note)
        ok(f"Look loaded onto {mnt}")
        _print_look(mnt, look_report(mnt))
        return 0
    look, pictures = look_changes(mnt, args.theme, args.icons, args.background, args.splash, args.dim, args.reset)
    if args.menu:
        return _look_menu(cfg, mnt)
    if args.preview:                    # a picture of it; the stick stays as it is
        shown = look_preview(cfg, mnt, look, Path(args.preview).expanduser(), pictures, args.dim)
        ok(f"Preview written: {shown}")
        return 0
    changed = set_look(cfg, mnt, look, pictures, args.dim)
    report = {**look_report(mnt, look), "changed": changed}
    if args.json:
        print(json.dumps(report, indent=2))
        return 0
    if changed:
        ok(f"Look changed on {mnt}")
    _print_look(mnt, report)
    head("Themes  (--theme ID)")
    for t in report["themes"]:
        print(f"  {t['id']:<11} {t['title']}" + (f": {t['description']}" if t["description"] else ""))
    head("Icon packs  (--icons ID)")
    for t in report["icon_packs"]:
        print(f"  {t['id']:<11} {t['title']}" + (f": {t['description']}" if t["description"] else ""))
    info("your own pictures: --background PICTURE [--dim 40], --splash PICTURE; --reset puts it all back")
    return 0


def cmd_splash(cfg: Config, args) -> int:
    """Show the theme's splash.png for a moment before the Ventoy menu. Ventoy has no setting
    for that, so this adds a few lines to its own boot script on the VTOYEFI partition (marked,
    and replaced or removed cleanly on the next run). A Ventoy install or upgrade rewrites that
    script; install.sh and refresh.sh run this afterwards."""
    efi = Path(args.efi).expanduser()
    script = efi / "grub" / "grub.cfg"
    if not script.is_file():
        raise RescueError(f"{efi} isn't Ventoy's boot partition (VTOYEFI): it has no grub/grub.cfg")
    before = script.read_bytes().decode("utf-8")
    text = re.sub(rf"{re.escape(SPLASH_BEGIN)}.*?{re.escape(SPLASH_END)}\n\n?", "", before, flags=re.S)
    try:
        seconds = int(cfg.settings.get("splash_seconds", 1))
    except (TypeError, ValueError):
        raise RescueError("splash_seconds in local.toml must be a whole number of seconds") from None
    if not 0 <= seconds <= 10:
        raise RescueError("splash_seconds must be between 0 (no splash) and 10")
    wanted = seconds > 0 and bool(cfg.settings.get("theme")) and not args.remove
    if wanted:
        if text.count(SPLASH_ANCHOR) != 1:   # a Ventoy this doesn't know: leave its boot script alone
            warn("this Ventoy's boot script isn't laid out as expected, so no splash was added")
            return 0
        text = text.replace(SPLASH_ANCHOR, _splash_block(seconds) + SPLASH_ANCHOR)
    if text == before:
        ok(f"Splash: {'already ' + str(seconds) + ' s before the menu' if wanted else 'none'}")
        return 0
    if args.dry_run:
        info(f"would {'set the splash to ' + str(seconds) + ' s' if wanted else 'remove the splash'}")
        return 0
    tmp = script.with_name("grub.cfg.helix-boot")
    tmp.write_bytes(text.encode("utf-8"))
    os.replace(tmp, script)
    ok(f"Splash: {seconds} s before the Ventoy menu" if wanted else "Splash removed")
    return 0


def cmd_ventoy_path(cfg: Config, args) -> int:
    if getattr(args, "from_pack", None):
        print(_ventoy_from_pack(cfg, args.from_pack))
        return 0
    lock = load_lock(cfg)
    t = next((t for t in cfg.tools if t["kind"] == "ventoy"), None)
    entry = lock.get(t["name"]) if t else None
    path = cfg.cache / t["name"] / entry["final"] if entry else None
    if not path or not any((path / f).exists() for f in ("Ventoy2Disk.sh", "Ventoy2Disk.exe")):
        raise RescueError("Ventoy isn't fetched yet — run `helix fetch ventoy`")
    print(path)
    return 0


def main(argv: list[str] | None = None) -> int:
    for stream in (sys.stdout, sys.stderr):  # line-buffered keeps a shared log in order; errors=replace
        if hasattr(stream, "reconfigure"):     # keeps ✓/✗ from crashing a non-UTF-8 Windows console
            stream.reconfigure(line_buffering=True, errors="replace")
    ap = argparse.ArgumentParser(prog="helix", description="Build and refresh the Helix Boot USB.")
    ap.add_argument("--version", action="version", version=f"helix {__version__}")
    sub = ap.add_subparsers(dest="cmd", required=True, metavar="command")

    sub.add_parser("list", help="show every tool in the manifest").set_defaults(fn=cmd_list)

    p = sub.add_parser("check", help="compare cached versions with upstream (no downloads)")
    p.add_argument("tools", nargs="*")
    p.add_argument("--json", action="store_true", help="machine-readable output")
    p.set_defaults(fn=cmd_check)

    p = sub.add_parser("fetch", help="download and verify the latest releases")
    p.add_argument("tools", nargs="*", help="only these tools (default: all enabled)")
    p.add_argument("--force", action="store_true", help="re-download even if up to date")
    p.set_defaults(fn=cmd_fetch)

    p = sub.add_parser("sync", help="copy the cache onto a mounted Ventoy stick")
    p.add_argument("target", help="mount point of the Ventoy data partition")
    p.add_argument("--init", action="store_true", help="adopt a stick not labelled 'Ventoy'")
    p.add_argument("--dry-run", action="store_true", help="show what would change")
    p.add_argument("--verify", action="store_true", help="hash files on the stick (slow)")
    p.add_argument("--no-prune", action="store_true", help="keep old versions on the stick")
    p.add_argument("--prune-unknown", action="store_true",
                   help="also remove tools on the stick that this PC has no copy of (by default they stay)")
    p.set_defaults(fn=cmd_sync)

    p = sub.add_parser("pack", help="put the whole stick (and Ventoy) into one .zip for offline use")
    p.add_argument("output", nargs="?", help="where to write it (default: helix-boot-<date>.zip here)")
    p.set_defaults(fn=cmd_pack)

    p = sub.add_parser("unpack", help="fill a mounted Ventoy stick from a pack")
    p.add_argument("pack", help="the .zip made by `helix pack`")
    p.add_argument("target", help="mount point of the Ventoy data partition")
    p.add_argument("--init", action="store_true", help="adopt a stick not labelled 'Ventoy'")
    p.add_argument("--dry-run", action="store_true", help="show what would change")
    p.add_argument("--verify", action="store_true", help="hash files on the stick (slow)")
    p.add_argument("--no-prune", action="store_true", help="keep old versions on the stick")
    p.add_argument("--prune-unknown", action="store_true",
                   help="also remove tools on the stick that this PC has no copy of (by default they stay)")
    p.set_defaults(fn=cmd_unpack)

    p = sub.add_parser("verify", help="read a stick back and find damaged or missing files (no downloads)")
    p.add_argument("target", help="mount point of the Ventoy data partition")
    p.add_argument("--json", action="store_true", help="machine-readable output")
    p.set_defaults(fn=cmd_verify)

    p = sub.add_parser("splash",help="show the splash picture before the Ventoy menu (on its VTOYEFI partition)")
    p.add_argument("efi", help="mount point of the stick's VTOYEFI partition")
    p.add_argument("--remove", action="store_true", help="take the splash out again")
    p.add_argument("--dry-run", action="store_true", help="show what would change")
    p.set_defaults(fn=cmd_splash)

    p = sub.add_parser("theme", help="show or change a stick's look: theme, icons, background, splash")
    p.add_argument("stick", help="mount point of the Ventoy data partition")
    p.add_argument("--theme", metavar="ID", help="a preset theme, or `default`; `off` is the plain one (Standby)")
    p.add_argument("--icons", metavar="ID", help="`auto` (the theme's own style, the default), `logos`, `grey`, an icon pack, or `off`")
    p.add_argument("--background", metavar="PICTURE", help="your own background, or `theme` for the theme's")
    p.add_argument("--dim", type=int, default=0, metavar="PERCENT",
                   help="darken your background this much (0-90), so the menu stays readable")
    p.add_argument("--splash", metavar="PICTURE",
                   help="your own splash; `theme` for the theme's, `auto` (yours from byo/, else the theme's), `off`")
    p.add_argument("--reset", action="store_true", help="back to the default look")
    p.add_argument("--menu", action="store_true", help="choose from numbered lists instead")
    p.add_argument("--preview", metavar="FILE",
                   help="don't change the stick: write a picture of how the menu would look")
    p.add_argument("--json", action="store_true", help="print the look and the choices as JSON")
    p.add_argument("--export", metavar="ZIP", help="save the look (and your own pictures and icons) to a zip")
    p.add_argument("--import", dest="import_", metavar="ZIP", help="put a saved look on the stick")
    p.set_defaults(fn=cmd_theme)

    p = sub.add_parser("setting", help="print one of the [settings], for the scripts (e.g. stick_label)")
    p.add_argument("name", choices=["stick_label", "iso_root", "apps_root", "mac_root"])
    p.set_defaults(fn=lambda cfg, a: print(getattr(cfg, a.name)) or 0)

    p = sub.add_parser("ventoy-path", help="print the extracted Ventoy folder")
    p.add_argument("--from", dest="from_pack", metavar="PACK", help="use the Ventoy inside a pack")
    p.set_defaults(fn=cmd_ventoy_path)

    args = ap.parse_args(argv)
    try:
        # HELIX_USER_DIR: your local.toml and byo/ live there instead of beside helix (HelixBoot.sh)
        mine = _env("USER_DIR")
        return args.fn(Config(repo=Path(mine).expanduser().resolve(), assets=REPO) if mine else Config(), args)
    except RescueError as e:
        bad(str(e))
        return 1
    except KeyboardInterrupt:
        print()
        warn("interrupted — partial downloads are kept and will resume next time")
        return 130


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