visync 0.1.0__py3-none-any.whl

visync/main.py

@@ -0,0 +1,1172 @@
+"""Visync - Ventoy Package Manager.
+
+Built with typer. Run `visync --help` for available commands.
+"""
+
+import contextlib
+import functools
+from pathlib import Path
+
+import typer
+from rich.markup import escape as _esc
+
+from visync.finder import (
+    find_installed_isos,
+    find_ventoy_drives,
+    get_iso_volume_id,
+    identify_distro,
+    keyword_hit,
+    load_all_metadata,
+    load_config,
+)
+from visync.output import (
+    console,
+    error,
+    failure_table,
+    header,
+    iso_table,
+    success,
+    warn,
+)
+from visync.output import info as output_info
+from visync.verify import extract_version_from_filename, run_directory_verify
+
+app = typer.Typer()
+
+# Set by the global --yes flag. Module-level rather than threaded through every
+# command because it is a single answer to a single question ("do not ask me
+# about anything unusual"), and the alternative — eight copies of the same
+# option — would let a script skip the check on one command and not another.
+_ASSUME_YES = False
+
+
+@app.callback()
+def main_callback(
+    assume_yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Answer yes to every confirmation, including using a --drive "
+        "that does not look like a Ventoy drive",
+    ),
+) -> None:
+    global _ASSUME_YES
+    _ASSUME_YES = assume_yes
+
+
+def _skip_confirmations(command_yes: bool = False) -> bool:
+    """True when the user has asked not to be asked.
+
+    Commands that prompt for deletion keep their own ``--yes`` so the natural
+    form (``visync remove --yes``) keeps working, and also honour the global
+    flag so ``visync --yes remove`` means the same thing. Both spellings answer
+    one question, so both are folded together here rather than at each site.
+    """
+    return command_yes or _ASSUME_YES
+
+
+def _parse_drives(raw: str | None) -> list[Path] | None:
+    """Parse comma-separated drive paths from CLI option."""
+    if not raw:
+        return None
+    return [Path(p.strip()) for p in raw.split(",") if p.strip()]
+
+
+def _get_drives(drives: list[Path] | None = None) -> list[Path]:
+    """Resolve Ventoy drive paths.
+
+    If *drives* is provided, validate and return them.
+    If exactly one drive is detected, return it.
+    If multiple drives are detected, prompt the user to select one or more.
+
+    An explicit path that does not look like a Ventoy drive requires
+    confirmation. Writes into the wrong directory are not recoverable: cleanup
+    unlinks ISOs it recognises there, so a typo in --drive can delete real
+    images. The global --yes flag skips the prompt.
+    """
+    if drives is not None:
+        validated = []
+        for d in drives:
+            if not d.is_dir():
+                error(f"Not a directory: {d}")
+                raise typer.Exit(1)
+            if not (d / ".visync").is_dir() and not (d / "ventoy").is_dir():
+                console.print(
+                    "  [yellow]⚠[/yellow] Commands can write ISOs here, and"
+                    " cleanup can [bold]delete[/bold] ISOs it recognises."
+                )
+                if _ASSUME_YES:
+                    warn(
+                        f"{d} is not a Ventoy/Visync-managed drive "
+                        "(no .visync/ and no ventoy/ directory) — proceeding "
+                        "because --yes was given."
+                    )
+                else:
+                    error(
+                        f"{d} is not a Ventoy/Visync-managed drive "
+                        "(no .visync/ and no ventoy/ directory)."
+                    )
+                    try:
+                        proceed = typer.confirm("Use this directory anyway?")
+                    except typer.Abort as exc:
+                        error("Aborted.")
+                        raise typer.Exit(1) from exc
+                    if not proceed:
+                        error("Aborted — nothing changed.")
+                        raise typer.Exit(1)
+            validated.append(d)
+        return validated
+
+    detected = find_ventoy_drives()
+    if not detected:
+        error("No Ventoy drives detected.")
+        raise typer.Exit(1)
+
+    if len(detected) == 1:
+        return detected
+
+    # Multiple drives — prompt user to select
+    console.print()
+    console.print("  [bold]Multiple Ventoy drives detected:[/bold]")
+    for i, d in enumerate(detected, 1):
+        console.print(f"    [cyan]{i}[/cyan]) {_esc(str(d))}")
+    console.print("  [dim]Enter numbers separated by commas (e.g. 1,3)[/dim]")
+    console.print()
+
+    while True:
+        try:
+            raw = typer.prompt("Select drive(s)")
+        except (typer.Abort, EOFError) as exc:
+            raise typer.Exit(1) from exc
+        try:
+            indices = [int(x.strip()) for x in raw.split(",") if x.strip()]
+            if not indices:
+                raise ValueError("empty")
+            selected = []
+            for idx in indices:
+                if 1 <= idx <= len(detected):
+                    selected.append(detected[idx - 1])
+                else:
+                    raise ValueError(f"invalid index {idx}")
+            return selected
+        except ValueError as e:
+            error(
+                f"Invalid input: {e}. Enter numbers 1-{len(detected)} separated by commas."
+            )
+
+
+def _drives_optional(drive: str | None) -> list[Path]:
+    """Resolve drives for read-only catalogue commands.
+
+    Unlike _get_drives this returns an empty list instead of failing when no
+    Ventoy drive is present. `search` and `info` answer questions about the
+    configured catalogue, which is exactly what someone wants to ask before
+    plugging the drive in; hard-failing meant the only way to browse the
+    catalogue was to have the drive mounted. An explicit --drive is still
+    validated normally, since naming a path that is not there is a typo.
+    """
+    explicit = _parse_drives(drive)
+    if explicit is not None:
+        return _get_drives(explicit)
+    return find_ventoy_drives()
+
+
+def _interruptible(fn):
+    """Turn Ctrl-C into a clean exit(130) instead of a traceback.
+
+    *fn* is the body of a command. Downloads already delete their own in-flight
+    .part file when interrupted (see download._discard_partial), so this only
+    has to stop the spinner, say what happened, and use the conventional exit
+    status for SIGINT. Previously the KeyboardInterrupt reached the interpreter
+    top level, which produced a traceback and — because the handler that was
+    supposed to tidy up lived in download.py's __main__ block, a path the CLI
+    never executes — left partial downloads behind on the drive.
+    """
+
+    @functools.wraps(fn)
+    def wrapper(*args, **kwargs):
+        try:
+            return fn(*args, **kwargs)
+        except KeyboardInterrupt:
+            console.print()
+            console.print(
+                "[red]✕ Interrupted.[/red] Partial downloads were removed; "
+                "nothing was changed on the drive."
+            )
+            raise typer.Exit(130) from None
+
+    return wrapper
+
+
+def _sync_one_drive(
+    drive: Path,
+    only: list[str] | None,
+    config: Path | None,
+    dry_run: bool = False,
+    force: bool = False,
+    clean: bool = False,
+    no_verify: bool = False,
+    use_buffer: bool = True,
+    reset_visync: bool = False,
+) -> list[tuple[str, str]]:
+    """Run the sync pipeline for one drive and report what could not be checked.
+
+    Returns the list of ``(clean_name, reason)`` failures so the caller can finish
+    its own bookkeeping before deciding on an exit code. The failure block is
+    printed here so install/update/sync all surface it identically.
+    """
+    from visync.download import sync_all_configured_distros
+
+    _dir, _downloaded, failures = sync_all_configured_distros(
+        dry_run=dry_run,
+        force=force,
+        clean=clean,
+        config_path=config,
+        only=only,
+        drive_override=drive,
+        use_buffer=use_buffer,
+        no_verify=no_verify,
+        reset_visync=reset_visync,
+    )
+    if failures:
+        console.print()
+        error(f"Sync finished with {len(failures)} problem(s):")
+        failure_table(failures)
+    return failures
+
+
+@app.command()
+@_interruptible
+def install(
+    name: str | None = typer.Argument(
+        default=None, help="Distro name or keyword to install"
+    ),
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to config file"
+    ),
+    drive: str | None = typer.Option(
+        None, "--drive", "-d", help="Ventoy drive path(s), comma-separated for multiple"
+    ),
+    file: Path | None = typer.Option(
+        None, "--file", "-i", help="File with one distro name per line"
+    ),
+    dry_run: bool = typer.Option(
+        False,
+        "--dry-run",
+        "-n",
+        help="Show what would be installed without downloading",
+    ),
+    no_verify: bool = typer.Option(
+        False, "--no-verify", help="Skip checksum verification after download"
+    ),
+    no_staging: bool = typer.Option(
+        False,
+        "--no-staging",
+        "--no-buffer",
+        help="Download directly to the Ventoy drive (skip staging buffer)",
+    ),
+) -> None:
+    """Download and install distros to the Ventoy drive.
+
+    Use a distro name directly, or pass a file with one name per line.
+    """
+    from visync.pm import mark_installed, matching_distros, resolve_distro
+
+    config_data = load_config(config)
+    target_drives = _get_drives(_parse_drives(drive))
+
+    # Build list of distros to install
+    names: list[str] = []
+    if file:
+        if not file.exists():
+            error(f"File not found: {file}")
+            raise typer.Exit(1)
+        names = [
+            line.strip()
+            for line in file.read_text().splitlines()
+            if line.strip() and not line.strip().startswith("#")
+        ]
+    elif name:
+        names = [name]
+    else:
+        error("Provide a distro name or --file")
+        raise typer.Exit(1)
+
+    # Resolve all names first
+    to_install: list[tuple[str, str]] = []  # (entry_id, clean_name)
+    for n in names:
+        entry_id = resolve_distro(n, config_data)
+        if not entry_id:
+            _, partials = matching_distros(n, config_data)
+            if partials:
+                candidate_names = ", ".join(
+                    sorted(
+                        config_data.get("distros", {}).get(p, {}).get("clean_name", p)
+                        for p in partials
+                    )
+                )
+                error(
+                    f"Ambiguous distro '{n}' — matches: {candidate_names}. Be specific."
+                )
+            else:
+                error(f"Unknown distro: '{n}'")
+            continue
+        distro_config = config_data.get("distros", {}).get(entry_id, {})
+        clean_name = distro_config.get("clean_name", entry_id)
+        to_install.append((entry_id, clean_name))
+
+    if not to_install:
+        error("No valid distros to install.")
+        raise typer.Exit(1)
+
+    # Prefer the staging buffer whenever it is usable; per-download disk space
+    # checks during the actual download remain the authoritative guard.
+    staging_dir = Path.home() / ".cache" / "visync" / "staging"
+    use_buffer = True
+    if not dry_run:
+        try:
+            staging_dir.mkdir(parents=True, exist_ok=True)
+        except OSError as e:
+            warn(f"Staging buffer unavailable: {e} — downloading directly to drive")
+            use_buffer = False
+
+    if no_staging:
+        use_buffer = False
+
+    for ventoy_root in target_drives:
+        if len(target_drives) > 1:
+            console.print()
+            header(f"Drive: {ventoy_root}")
+
+        existing = find_installed_isos(ventoy_root)
+        to_download: list[str] = []
+        failures: list[tuple[str, str]] = []
+
+        for entry_id, clean_name in to_install:
+            found = False
+            for iso_path in existing:
+                vid = get_iso_volume_id(iso_path)
+                if vid:
+                    distro = identify_distro(vid, iso_path.name)
+                else:
+                    distro = identify_distro("", iso_path.name)
+                if distro.lower() == clean_name.lower():
+                    warn(f"{clean_name} is already on the drive: {iso_path.name}")
+                    if not dry_run:
+                        mark_installed(
+                            ventoy_root,
+                            entry_id,
+                            version=extract_version_from_filename(iso_path.name) or "",
+                        )
+                    found = True
+                    break
+            if not found:
+                to_download.append(entry_id)
+
+        if not to_download:
+            output_info("All distros already on drive.")
+            continue
+
+        if dry_run:
+            output_info(f"Would download {len(to_download)} distro(s):")
+            for entry_id in to_download:
+                distro_config = config_data.get("distros", {}).get(entry_id, {})
+                console.print(
+                    f"    [cyan]→[/cyan] {_esc(str(distro_config.get('clean_name', entry_id)))}"
+                )
+            continue
+
+        output_info(f"Installing {len(to_download)} distro(s)...")
+        failures.extend(
+            _sync_one_drive(
+                drive=ventoy_root,
+                only=to_download,
+                config=config,
+                force=True,
+                use_buffer=use_buffer,
+                no_verify=no_verify,
+            )
+        )
+
+        # Mark installed if file is now on drive
+        for entry_id in to_download:
+            distro_config = config_data.get("distros", {}).get(entry_id, {})
+            clean_name = distro_config.get("clean_name", entry_id)
+            fresh = find_installed_isos(ventoy_root)
+            for iso_path in fresh:
+                vid = get_iso_volume_id(iso_path)
+                if vid:
+                    distro = identify_distro(vid, iso_path.name)
+                else:
+                    distro = identify_distro("", iso_path.name)
+                if distro.lower() == clean_name.lower():
+                    version = extract_version_from_filename(iso_path.name) or ""
+                    mark_installed(ventoy_root, entry_id, version=version)
+                    success(f"{clean_name} installed")
+                    break
+            else:
+                warn(f"{clean_name} — file not found on drive after download")
+
+        if failures:
+            raise typer.Exit(1)
+
+
+@app.command()
+def remove(
+    name: str = typer.Argument(help="Distro name or keyword to remove"),
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to config file"
+    ),
+    drive: str | None = typer.Option(
+        None, "--drive", "-d", help="Ventoy drive path(s), comma-separated for multiple"
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "-n", help="Show what would be removed without deleting"
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip the confirmation prompt (same as --yes before the command)",
+    ),
+) -> None:
+    """Remove a distro from the Ventoy drive."""
+    from visync.finder import remove_iso_metadata
+    from visync.pm import mark_removed, matching_distros, resolve_distro
+
+    config_data = load_config(config)
+    target_drives = _get_drives(_parse_drives(drive))
+    skip_confirm = _skip_confirmations(yes)
+
+    entry_id = resolve_distro(name, config_data)
+    if not entry_id:
+        _, partials = matching_distros(name, config_data)
+        if partials:
+            candidate_names = ", ".join(
+                sorted(
+                    config_data.get("distros", {}).get(p, {}).get("clean_name", p)
+                    for p in partials
+                )
+            )
+            error(
+                f"Ambiguous distro '{name}' — matches: {candidate_names}. Be specific."
+            )
+        else:
+            error(f"Unknown distro: '{name}'")
+        raise typer.Exit(1)
+
+    distro_config = config_data.get("distros", {}).get(entry_id, {})
+    clean_name = distro_config.get("clean_name", entry_id)
+
+    for ventoy_root in target_drives:
+        if len(target_drives) > 1:
+            console.print()
+            header(f"Drive: {ventoy_root}")
+
+        # Find matching files on drive before touching anything
+        existing = find_installed_isos(ventoy_root)
+        matches = []
+        for iso_path in existing:
+            vid = get_iso_volume_id(iso_path)
+            if vid:
+                distro = identify_distro(vid, iso_path.name)
+            else:
+                distro = identify_distro("", iso_path.name)
+            if distro.lower() == clean_name.lower():
+                matches.append(iso_path)
+
+        if not matches:
+            warn(f"No files found for {clean_name} on the drive.")
+            continue
+
+        if dry_run:
+            for iso_path in matches:
+                output_info(f"Would remove {iso_path.name}")
+            continue
+
+        if not skip_confirm:
+            console.print(
+                f"  About to delete {len(matches)} file(s) from {_esc(str(ventoy_root))}:"
+            )
+            for iso_path in matches:
+                console.print(f"    [red]✗[/red] {_esc(iso_path.name)}")
+            try:
+                confirmed = typer.confirm("Delete these file(s)?")
+            except typer.Abort as exc:
+                error("Aborted — nothing deleted.")
+                raise typer.Exit(1) from exc
+            if not confirmed:
+                output_info("Aborted — nothing deleted.")
+                continue
+
+        removed_count = 0
+        for iso_path in matches:
+            try:
+                iso_path.unlink(missing_ok=True)
+                remove_iso_metadata(ventoy_root, iso_path.name)
+                success(f"Removed {iso_path.name}")
+                removed_count += 1
+            except OSError as e:
+                error(f"Could not remove {iso_path.name}: {e}")
+
+        if removed_count:
+            mark_removed(ventoy_root, entry_id)
+            success(f"{clean_name} removed")
+
+
+@app.command()
+@_interruptible
+def update(
+    name: str | None = typer.Argument(
+        default=None, help="Distro to update (all if omitted)"
+    ),
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to config file"
+    ),
+    drive: str | None = typer.Option(
+        None, "--drive", "-d", help="Ventoy drive path(s), comma-separated for multiple"
+    ),
+    force: bool = typer.Option(False, "--force", "-f", help="Force re-download"),
+    clean: bool = typer.Option(False, "--clean", help="Remove old versions"),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "-n", help="Show what would be updated without downloading"
+    ),
+    no_verify: bool = typer.Option(
+        False, "--no-verify", help="Skip checksum verification after download"
+    ),
+    no_staging: bool = typer.Option(
+        False,
+        "--no-staging",
+        "--no-buffer",
+        help="Download directly to the Ventoy drive (skip staging buffer)",
+    ),
+    reset_visync: bool = typer.Option(
+        False,
+        "--reset-visync",
+        help="Allow the watchdog to wipe .visync/ if it exceeds 1 GiB "
+        "(destroys installed.json; metadata rebuilds on next sync)",
+    ),
+) -> None:
+    """Update installed distros to latest versions."""
+    from visync.pm import (
+        get_installed_ids,
+        mark_installed,
+        matching_distros,
+        resolve_distro,
+    )
+
+    config_data = load_config(config)
+    target_drives = _get_drives(_parse_drives(drive))
+
+    failures: list[tuple[str, str]] = []
+
+    for ventoy_root in target_drives:
+        if len(target_drives) > 1:
+            console.print()
+            header(f"Drive: {ventoy_root}")
+
+        if name:
+            entry_id = resolve_distro(name, config_data)
+            if not entry_id:
+                _, partials = matching_distros(name, config_data)
+                if partials:
+                    candidate_names = ", ".join(
+                        sorted(
+                            config_data.get("distros", {})
+                            .get(p, {})
+                            .get("clean_name", p)
+                            for p in partials
+                        )
+                    )
+                    error(
+                        f"Ambiguous distro '{name}' — matches: {candidate_names}. Be specific."
+                    )
+                else:
+                    error(f"Unknown distro: '{name}'")
+                raise typer.Exit(1)
+            only = [entry_id]
+        else:
+            only = get_installed_ids(ventoy_root)
+            if not only:
+                output_info("No distros installed. Use 'visync install <name>' first.")
+                continue
+
+        failures.extend(
+            _sync_one_drive(
+                drive=ventoy_root,
+                only=only,
+                config=config,
+                dry_run=dry_run,
+                force=force,
+                clean=clean,
+                no_verify=no_verify,
+                use_buffer=not no_staging,
+                reset_visync=reset_visync,
+            )
+        )
+
+        if not dry_run:
+            existing = find_installed_isos(ventoy_root)
+            for eid in only:
+                distro_config = config_data.get("distros", {}).get(eid, {})
+                clean_name = distro_config.get("clean_name", eid)
+                for iso_path in existing:
+                    vid = get_iso_volume_id(iso_path)
+                    distro = (
+                        identify_distro(vid, iso_path.name)
+                        if vid
+                        else identify_distro("", iso_path.name)
+                    )
+                    if distro.lower() == clean_name.lower():
+                        version = extract_version_from_filename(iso_path.name) or ""
+                        mark_installed(ventoy_root, eid, version=version)
+                        break
+
+    if failures:
+        raise typer.Exit(1)
+
+
+@app.command()
+def search(
+    query: str | None = typer.Argument(
+        default=None, help="Search query (lists all if omitted)"
+    ),
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to config file"
+    ),
+    drive: str | None = typer.Option(
+        None, "--drive", "-d", help="Ventoy drive path(s), comma-separated for multiple"
+    ),
+) -> None:
+    """Search available distros."""
+    from visync.pm import get_installed_ids, resolve_distro
+
+    config_data = load_config(config)
+    distros = config_data.get("distros", {})
+
+    if not distros:
+        warn("No distros configured.")
+        return
+
+    target_drives = _drives_optional(drive)
+
+    # Collect installed status across all drives
+    installed_by_drive: dict[Path, set[str]] = {}
+    for vr in target_drives:
+        installed_by_drive[vr] = set(get_installed_ids(vr))
+
+    if query:
+        entry_id = resolve_distro(query, config_data)
+        if entry_id:
+            s = distros[entry_id]
+            console.print()
+            console.print(
+                f"  [bold]{_esc(str(s.get('clean_name', entry_id)))}[/bold] [dim]({_esc(entry_id)})[/dim]"
+            )
+            console.print(f"    strategy: {s.get('strategy', '?')}")
+            if s.get("base_url"):
+                console.print(f"    url: {_esc(str(s['base_url']))}")
+            if not target_drives:
+                console.print(
+                    "    [dim]no Ventoy drive detected — install status unknown[/dim]"
+                )
+            for vr in target_drives:
+                status = (
+                    "installed" if entry_id in installed_by_drive[vr] else "available"
+                )
+                marker = (
+                    "[green]installed[/green]"
+                    if status == "installed"
+                    else "[dim]available[/dim]"
+                )
+                console.print(f"    {_esc(str(vr))}: {marker}")
+        else:
+            error(f"No match for '{query}'")
+        return
+
+    rows = []
+    for entry_id, s in sorted(distros.items()):
+        clean = s.get("clean_name", entry_id)
+        strategy = s.get("strategy", "?")
+        # Show which drives have it installed
+        drive_status = []
+        for vr in target_drives:
+            if entry_id in installed_by_drive[vr]:
+                drive_status.append("+")
+            else:
+                drive_status.append(" ")
+        rows.append((drive_status, clean, strategy))
+
+    console.print()
+    console.print("  [bold]Available distros:[/bold]")
+    if len(target_drives) > 1:
+        # Show drive headers
+        drive_labels = [f"D{i + 1}" for i in range(len(target_drives))]
+        console.print(
+            f"    {'':3} {'Name':<25} {'Strategy':<20} {' '.join(drive_labels)}"
+        )
+        console.print(
+            f"    {'':3} {'-' * 25} {'-' * 20} {' '.join(['--' for _ in target_drives])}"
+        )
+        for drive_status, name, strategy in rows:
+            markers = " ".join(
+                f"[green]{s}[/green]" if s == "+" else f"[dim]{s}[/dim]"
+                for s in drive_status
+            )
+            console.print(f"    {'':3} {_esc(name):<25} {_esc(strategy):<20} {markers}")
+    else:
+        for drive_status, name, strategy in rows:
+            if drive_status:
+                marker = (
+                    f"[green]{drive_status[0]}[/green]"
+                    if drive_status[0] == "+"
+                    else f"[dim]{drive_status[0]}[/dim]"
+                )
+                console.print(
+                    f"    {marker} {_esc(name)} [dim]({_esc(strategy)})[/dim]"
+                )
+            else:
+                console.print(f"      {_esc(name)} [dim]({_esc(strategy)})[/dim]")
+    console.print()
+    if target_drives:
+        console.print("  [dim]+ = installed[/dim]")
+    else:
+        console.print("  [dim]no Ventoy drive detected — showing catalogue only[/dim]")
+
+
+@app.command()
+def info(
+    name: str = typer.Argument(help="Distro name or keyword"),
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to config file"
+    ),
+    drive: str | None = typer.Option(
+        None, "--drive", "-d", help="Ventoy drive path(s), comma-separated for multiple"
+    ),
+) -> None:
+    """Show details about a distro."""
+    from visync.pm import get_installed_ids, resolve_distro
+
+    config_data = load_config(config)
+    distros = config_data.get("distros", {})
+
+    entry_id = resolve_distro(name, config_data)
+    if not entry_id:
+        error(f"Unknown distro: '{name}'")
+        raise typer.Exit(1)
+
+    s = distros[entry_id]
+    target_drives = _drives_optional(drive)
+
+    console.print()
+    console.print(f"  [bold]{_esc(str(s.get('clean_name', entry_id)))}[/bold]")
+    console.print(f"    entry_id:  {_esc(entry_id)}")
+    console.print(f"    strategy:  {s.get('strategy', '?')}")
+    if s.get("base_url"):
+        console.print(f"    base_url:  {_esc(str(s['base_url']))}")
+    if s.get("api_url"):
+        console.print(f"    api_url:   {_esc(str(s['api_url']))}")
+    console.print(f"    checksums: {s.get('checksum_format', 'none')}")
+
+    clean_name = s.get("clean_name", entry_id)
+    if not target_drives:
+        console.print("    [dim]no Ventoy drive detected — nothing to report on[/dim]")
+    for vr in target_drives:
+        installed = set(get_installed_ids(vr))
+        status = (
+            "[green]installed[/green]"
+            if entry_id in installed
+            else "[dim]available[/dim]"
+        )
+
+        existing = find_installed_isos(vr)
+        file_info = "[dim]not on drive[/dim]"
+        for iso_path in existing:
+            vid = get_iso_volume_id(iso_path)
+            if vid:
+                distro = identify_distro(vid, iso_path.name)
+            else:
+                distro = identify_distro("", iso_path.name)
+            if distro.lower() == clean_name.lower():
+                size_gb = iso_path.stat().st_size / (1024**3)
+                file_info = f"{iso_path.name} ({size_gb:.1f}G)"
+                break
+
+        if len(target_drives) > 1:
+            console.print(f"    [bold]{vr}[/bold]")
+        console.print(f"    status:    {status}")
+        console.print(f"    file:      {_esc(file_info)}")
+    console.print()
+
+
+@app.command()
+def autodetect(
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to config file"
+    ),
+    drive: str | None = typer.Option(
+        None, "--drive", "-d", help="Ventoy drive path(s), comma-separated for multiple"
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "-n", help="Show what would be detected without registering"
+    ),
+) -> None:
+    """Auto-detect ISOs on the drive and mark them as installed."""
+    from visync.pm import get_installed_ids, mark_installed
+
+    config_data = load_config(config)
+    target_drives = _get_drives(_parse_drives(drive))
+    distros = config_data.get("distros", {})
+
+    for ventoy_root in target_drives:
+        if len(target_drives) > 1:
+            console.print()
+            header(f"Drive: {ventoy_root}")
+
+        existing = find_installed_isos(ventoy_root)
+        # Read installed.json once per drive and keep it up to date as we
+        # register. Re-reading it inside the loop re-parsed the file for every
+        # ISO on the drive, and the only reason it was correct there was that
+        # mark_installed happened to write the new entry back out.
+        installed = set(get_installed_ids(ventoy_root))
+        found = 0
+        for iso_path in existing:
+            vid = get_iso_volume_id(iso_path)
+            if vid:
+                distro = identify_distro(vid, iso_path.name)
+            else:
+                distro = identify_distro("", iso_path.name)
+            if distro in ("Unknown OS", ""):
+                continue
+
+            # Find matching config entry — prefer exact clean_name match, then keyword in filename
+            entry_id = None
+            file_lower = iso_path.name.lower()
+            for eid, s in distros.items():
+                clean = s.get("clean_name", "")
+                if clean.lower() == distro.lower():
+                    entry_id = eid
+                    break
+            if not entry_id:
+                # Fallback: check if any config keyword appears in the filename
+                for eid, s in distros.items():
+                    keyword = s.get("keyword", "")
+                    if keyword and keyword_hit(keyword, file_lower):
+                        entry_id = eid
+                        break
+            if not entry_id or entry_id in installed:
+                continue
+
+            version = extract_version_from_filename(iso_path.name) or ""
+            if dry_run:
+                output_info(f"Would detect {distro}: {iso_path.name}")
+                found += 1
+            else:
+                mark_installed(ventoy_root, entry_id, version=version)
+                installed.add(entry_id)
+                success(f"Detected {distro}: {iso_path.name}")
+                found += 1
+
+        if found == 0:
+            output_info("No new distros detected (all already registered).")
+        else:
+            success(
+                f"{'Would detect' if dry_run else 'Marked'} {found} distro(s) as installed."
+            )
+
+
+@app.command("list")
+def list_isos(
+    drive: str | None = typer.Option(
+        None,
+        "--drive",
+        "-d",
+        help="Ventoy drive path(s), comma-separated for multiple",
+    ),
+) -> None:
+    """List ISOs on the Ventoy drive with distro, version, and size."""
+    # No --config here: this command reads the drive and the metadata sidecars,
+    # and identify_distro resolves against the installed catalogue. An accepted
+    # --config that changed nothing was worse than none, because a user who set
+    # it reasonably expected their file to be used.
+    target_drives = _get_drives(_parse_drives(drive))
+
+    for iso_dir in target_drives:
+        if len(target_drives) > 1:
+            console.print()
+            header(f"Drive: {iso_dir}")
+
+        iso_paths = find_installed_isos(iso_dir)
+        if not iso_paths:
+            warn("No ISO files found.")
+            continue
+
+        all_meta = load_all_metadata(iso_dir)
+
+        rows = []
+        total_gb_val = 0.0
+        for iso_path in sorted(iso_paths, key=lambda p: p.name):
+            meta = all_meta.get(iso_path.name)
+            if meta:
+                distro = identify_distro(meta.get("variant_stem", ""), iso_path.name)
+                version = meta.get("version") or "—"
+            else:
+                vid = get_iso_volume_id(iso_path)
+                distro = identify_distro(vid, iso_path.name)
+                version = extract_version_from_filename(iso_path.name) or "—"
+            # One stat per file: the total is accumulated here rather than
+            # recomputed in a second pass, which used to walk the drive twice.
+            size_gb = iso_path.stat().st_size / (1024**3)
+            total_gb_val += size_gb
+            rows.append((distro, version, f"{size_gb:.1f}G", iso_path.name))
+
+        iso_table(rows, total_gb_val)
+
+
+@app.command()
+@_interruptible
+def sync(
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to config file"
+    ),
+    drive: str | None = typer.Option(
+        None, "--drive", "-d", help="Ventoy drive path(s), comma-separated for multiple"
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "-n", help="Show what would be done without doing it"
+    ),
+    force: bool = typer.Option(
+        False, "--force", "-f", help="Force re-download even if version matches"
+    ),
+    clean: bool = typer.Option(
+        False,
+        "--clean",
+        help="Remove old versions of the same distro (dry-run by default)",
+    ),
+    # Named sync_all, not all: `all` is a builtin, and shadowing it inside the
+    # function body made `if all:` read like a filter on something else. The
+    # user-facing flag is unchanged.
+    sync_all: bool = typer.Option(
+        False, "--all", "-a", help="Sync all configured distros (not just installed)"
+    ),
+    no_verify: bool = typer.Option(
+        False, "--no-verify", help="Skip checksum verification after download"
+    ),
+    no_staging: bool = typer.Option(
+        False,
+        "--no-staging",
+        "--no-buffer",
+        help="Download directly to the Ventoy drive (skip staging buffer)",
+    ),
+    reset_visync: bool = typer.Option(
+        False,
+        "--reset-visync",
+        help="Allow the watchdog to wipe .visync/ if it exceeds 1 GiB "
+        "(destroys installed.json; metadata rebuilds on next sync)",
+    ),
+) -> None:
+    """Sync installed distros to the Ventoy drive."""
+    from visync.pm import get_installed_ids
+
+    target_drives = _get_drives(_parse_drives(drive))
+
+    failures: list[tuple[str, str]] = []
+
+    for drive_root in target_drives:
+        if len(target_drives) > 1:
+            console.print()
+            header(f"Drive: {drive_root}")
+
+        if sync_all:
+            only = None  # None = sync everything
+        else:
+            only = get_installed_ids(drive_root)
+            if not only:
+                output_info(
+                    "No distros installed. Use 'visync install <name>' or 'visync sync --all'."
+                )
+                continue
+
+        failures.extend(
+            _sync_one_drive(
+                drive=drive_root,
+                only=only,
+                config=config,
+                dry_run=dry_run,
+                force=force,
+                clean=clean,
+                no_verify=no_verify,
+                use_buffer=not no_staging,
+                reset_visync=reset_visync,
+            )
+        )
+
+    if failures:
+        raise typer.Exit(1)
+
+
+@app.command()
+def verify(
+    config: Path | None = typer.Option(
+        None, "--config", "-c", help="Path to config file"
+    ),
+    drive: str | None = typer.Option(
+        None,
+        "--drive",
+        "-d",
+        help="Ventoy drive path(s), comma-separated for multiple",
+    ),
+) -> None:
+    """Verify integrity of ISOs on the Ventoy drive."""
+    from visync.verify import VerifyStatus
+
+    config_data = load_config(config)
+    target_drives = _get_drives(_parse_drives(drive))
+
+    verified = failed = skipped = unavailable = 0
+    any_results = False
+
+    for iso_dir in target_drives:
+        if len(target_drives) > 1:
+            console.print()
+            header(f"Drive: {iso_dir}")
+
+        output_info(f"Verifying ISOs in {iso_dir} ...")
+        results = run_directory_verify(iso_dir, config_data)
+
+        if not results:
+            warn("No ISO files found.")
+            continue
+
+        any_results = True
+        for iso_path, distro, status in results:
+            label = f"{iso_path.name} ({distro})"
+            if status is VerifyStatus.VERIFIED:
+                success(label)
+                verified += 1
+            elif status is VerifyStatus.MISMATCH:
+                error(f"{label} — checksum mismatch")
+                failed += 1
+            elif status is VerifyStatus.UNAVAILABLE:
+                error(f"{label} — checksum could not be obtained (not verified)")
+                unavailable += 1
+            else:
+                output_info(f"{label} — no checksum config")
+                skipped += 1
+
+    if not any_results and len(target_drives) == 1:
+        return
+
+    console.print()
+    summary = f"Done: {verified} verified, {failed} failed"
+    if unavailable:
+        summary += f", {unavailable} unverified (source unreachable)"
+    summary += f", {skipped} skipped (no config)."
+    output_info(summary)
+    if failed or unavailable:
+        raise typer.Exit(1)
+
+
+@app.command("nuke-metadata")
+def nuke_metadata(
+    drive: str | None = typer.Option(
+        None, "--drive", "-d", help="Ventoy drive path(s), comma-separated for multiple"
+    ),
+    dry_run: bool = typer.Option(
+        False, "--dry-run", "-n", help="Show what would be deleted without deleting"
+    ),
+    yes: bool = typer.Option(
+        False,
+        "--yes",
+        "-y",
+        help="Skip the confirmation prompt (same as --yes before the command)",
+    ),
+) -> None:
+    """Delete all ISO metadata from .visync/metadata/.
+
+    Keeps installed.json and other state. Metadata rebuilds on next sync.
+    Only .json metadata files are eligible for deletion.
+    """
+    from visync.finder import _guard_json_only
+
+    target_drives = _get_drives(_parse_drives(drive))
+    skip_confirm = _skip_confirmations(yes)
+
+    for ventoy_root in target_drives:
+        if len(target_drives) > 1:
+            console.print()
+            header(f"Drive: {ventoy_root}")
+
+        metadata_dir = ventoy_root / ".visync" / "metadata"
+
+        if not metadata_dir.is_dir():
+            output_info("No metadata directory found.")
+            continue
+
+        json_files = []
+        skipped = []
+        for f in sorted(metadata_dir.iterdir()):
+            if f.is_file() and f.suffix == ".json":
+                json_files.append(f)
+            elif f.name != "." and f.is_file():
+                skipped.append(f)
+        total_size = sum(f.stat().st_size for f in json_files)
+
+        if not json_files:
+            output_info("Metadata directory is empty.")
+            continue
+
+        if dry_run:
+            output_info(
+                f"Would delete {len(json_files)} metadata file(s) ({total_size / 1024:.1f} KiB):"
+            )
+            for f in json_files:
+                console.print(f"    [cyan]→[/cyan] {_esc(f.name)}")
+            continue
+
+        if not skip_confirm:
+            console.print(
+                f"  About to delete {len(json_files)} metadata file(s) from {_esc(str(ventoy_root))}:"
+            )
+            for f in json_files:
+                console.print(f"    [red]✗[/red] {_esc(f.name)}")
+            try:
+                confirmed = typer.confirm("Delete these file(s)?")
+            except typer.Abort as exc:
+                error("Aborted — nothing deleted.")
+                raise typer.Exit(1) from exc
+            if not confirmed:
+                output_info("Aborted — nothing deleted.")
+                continue
+
+        deleted = 0
+        for f in json_files:
+            try:
+                _guard_json_only(f)
+                f.unlink()
+                deleted += 1
+            except ValueError as e:
+                warn(str(e))
+            except OSError as e:
+                warn(f"Could not remove {f.name}: {e}")
+        success(f"Deleted {deleted} metadata file(s) ({total_size / 1024:.1f} KiB)")
+
+        for f in skipped:
+            warn(f"Not metadata — left in place: {f.name}")
+        # The directory is not empty when non-metadata files were left in it,
+        # which is not an error — the caller has already reported them.
+        with contextlib.suppress(OSError):
+            metadata_dir.rmdir()
+        output_info("Metadata will rebuild on next sync.")
+
+
+@app.command()
+def version() -> None:
+    """Show the version of Visync."""
+    from . import __version__
+
+    typer.echo(f"Visync version: {__version__}")
+
+
+if __name__ == "__main__":
+    app()