visync 1.0.0__py3-none-any.whl

visync/finder.py

@@ -0,0 +1,699 @@
+"""
+Discover Ventoy drives and locate ISO files.
+
+Detects Ventoy volumes on Windows, macOS and Linux, reads ISO volume IDs
+from the file header, maps IDs to friendly distro names, and discovers
+.iso files under a directory.
+"""
+
+import contextlib
+import json
+import os
+import re
+import tomllib
+from datetime import UTC, datetime
+from pathlib import Path
+
+from rich.markup import escape as _escape
+
+from visync.output import console
+
+_CONFIG_CACHE: dict | None = None
+
+
+def reset_config_cache() -> None:
+    """Forget the cached config so the next load re-resolves from disk."""
+    global _CONFIG_CACHE
+    _CONFIG_CACHE = None
+
+
+def _packaged_config() -> Path:
+    """Path of the config shipped with the installed package.
+
+    Wheels install config.toml as visync/config.toml, beside the modules.
+    importlib.resources resolves it so a zip-imported package still works; the
+    filesystem path is returned because every caller treats the config as a real
+    file (open, rewrite, --config round-trips).
+
+    An editable install and a bare source checkout instead have config.toml at
+    the repository root, so that layout is returned as the fallback rather than
+    letting discovery fall through to the current working directory — otherwise
+    running from an unrelated directory would silently find no config.
+    """
+    beside_package = Path(__file__).parent / "config.toml"
+    if beside_package.is_file():
+        return beside_package
+
+    try:
+        from importlib.resources import files
+
+        resource = Path(str(files("visync").joinpath("config.toml")))
+        if resource.is_file():
+            return resource
+    except (ImportError, ModuleNotFoundError, FileNotFoundError, TypeError):
+        pass
+
+    # Editable install / source checkout: one level above the package.
+    return Path(__file__).parent.parent / "config.toml"
+
+
+def _config_candidates() -> list[Path]:
+    """Config search order: env override, user config, packaged config, cwd last."""
+    candidates = []
+    env_path = os.environ.get("VISYNC_CONFIG")
+    if env_path:
+        candidates.append(Path(env_path))
+    candidates.append(Path.home() / ".config" / "visync" / "config.toml")
+    candidates.append(_packaged_config())
+    candidates.append(Path.cwd() / "config.toml")
+    return candidates
+
+
+def load_config(config_path: Path | None = None) -> dict:
+    """Load configuration dictionary maps and distro settings from config.toml.
+
+    With no explicit path, resolves in a fixed order (env, user, packaged,
+    cwd-last) and caches the result so distro identification always agrees
+    with the config the command loaded — including an explicit --config.
+    """
+    global _CONFIG_CACHE
+    if config_path is None:
+        if _CONFIG_CACHE is not None:
+            return _CONFIG_CACHE
+        for candidate in _config_candidates():
+            if candidate.is_file():
+                config_path = candidate
+                break
+        else:
+            # No candidate existed. Report where we looked rather than falling
+            # through to a bare cwd path, which used to surface as the
+            # misleading "Failed to parse config.toml: ... No such file".
+            searched = ", ".join(str(c) for c in _config_candidates())
+            if os.environ.get("VISYNC_CONFIG"):
+                console.print(
+                    "  [yellow]⚠[/yellow] VISYNC_CONFIG is set but the file does "
+                    "not exist."
+                )
+            console.print(f"  [red]✗[/red] No config.toml found. Searched: {searched}")
+            console.print("  [dim]Set VISYNC_CONFIG or pass --config.[/dim]")
+            return {}
+    try:
+        with config_path.open("rb") as f:
+            data = tomllib.load(f)
+    except FileNotFoundError as e:
+        console.print(f"  [red]✗[/red] Config not found: {_escape(str(e))}")
+        return {}
+    except tomllib.TOMLDecodeError as e:
+        console.print(
+            f"  [red]✗[/red] Invalid TOML in {config_path}: {_escape(str(e))}"
+        )
+        return {}
+    except OSError as e:
+        console.print(f"  [red]✗[/red] Failed to read config.toml: {_escape(str(e))}")
+        return {}
+    _CONFIG_CACHE = data
+    return data
+
+
+def _mount_device(dev: str, detected: list[Path]) -> None:
+    """Try to mount a device temporarily and add its path if successful."""
+    import subprocess
+    import tempfile
+
+    mount_dir = Path(tempfile.mkdtemp(prefix="ventoy_"))
+    try:
+        subprocess.run(
+            ["mount", dev, str(mount_dir)],
+            capture_output=True,
+            timeout=10,
+        )
+        if mount_dir.is_dir() and any(mount_dir.iterdir()):
+            detected.append(mount_dir)
+    except Exception:  # noqa: S110 - mount without privileges fails; detection continues
+        pass
+    finally:
+        if not detected or not mount_dir.is_dir() or not any(mount_dir.iterdir()):
+            import shutil
+
+            shutil.rmtree(mount_dir, ignore_errors=True)
+
+
+def _udisksctl_mount(dev: str) -> Path | None:
+    """Mount a block device using udisksctl (no root required on most setups)."""
+    import subprocess
+
+    try:
+        result = subprocess.run(
+            ["udisksctl", "mount", "-b", dev],
+            capture_output=True,
+            text=True,
+            timeout=15,
+        )
+        if result.returncode == 0:
+            # Output: "Mounted /dev/sdX1 at /run/media/$USER/Ventoy"
+            for line in result.stdout.strip().splitlines():
+                if " at " in line:
+                    mount_point = line.split(" at ", 1)[-1].strip().rstrip(".")
+                    return Path(mount_point)
+            # Localized/unexpected output: ask the system where it landed
+            findmnt = subprocess.run(
+                ["findmnt", "-rn", "-o", "TARGET", "--source", dev],
+                capture_output=True,
+                text=True,
+                timeout=10,
+            )
+            if findmnt.returncode == 0 and findmnt.stdout.strip():
+                return Path(findmnt.stdout.strip().splitlines()[0])
+    except FileNotFoundError:
+        pass  # udisksctl not installed
+    except Exception:  # noqa: S110 - unmountable device is simply not a Ventoy drive
+        pass
+    return None
+
+
+def _try_mount_ventoy(partition: dict, detected: list[Path]) -> None:
+    """When Ventoy data partition is unmounted, find the dm-exposed device and mount it."""
+    for child in partition.get("children", []):
+        if child.get("mountpoint"):
+            continue
+        child_name = child.get("name", "")
+        child_type = child.get("type", "")
+        if not child_name:
+            continue
+        # dm devices live under /dev/mapper/<name>
+        if child_type == "dm":
+            dev_path = f"/dev/mapper/{child_name}"
+        else:
+            dev_path = f"/dev/{child_name}"
+        # Try udisksctl first (no root required)
+        mount_point = _udisksctl_mount(dev_path)
+        if mount_point:
+            detected.append(mount_point)
+            return
+        # Fallback to manual mount
+        _mount_device(dev_path, detected)
+        if detected:
+            return
+
+
+def find_ventoy_drives() -> list[Path]:
+    """Detect mounted Ventoy drives across Windows, macOS, and Linux.
+
+    Returns a list of Path objects pointing to the root of each detected
+    Ventoy drive. Index [0] for the primary drive.
+    """
+    import platform
+    import subprocess
+
+    system = platform.system()
+    detected_paths = []
+
+    if system == "Linux":
+        import json
+
+        cmd = ["lsblk", "-o", "NAME,TYPE,LABEL,MOUNTPOINT", "--json"]
+        result = subprocess.run(cmd, capture_output=True, text=True)
+
+        if result.returncode == 0 and result.stdout.strip():
+            try:
+                data = json.loads(result.stdout)
+                for device in data.get("blockdevices", []):
+                    for partition in device.get("children", []):
+                        label = partition.get("label")
+                        mount = partition.get("mountpoint")
+                        if label in ("Ventoy", "VTOYEFI"):
+                            if mount:
+                                detected_paths.append(Path(mount))
+                            elif label == "Ventoy":
+                                _try_mount_ventoy(partition, detected_paths)
+            except (json.JSONDecodeError, KeyError):
+                pass
+
+        # Fallback: blkid + findmnt (covers systems without lsblk)
+        if not detected_paths:
+            for lbl in ("Ventoy", "VTOYEFI"):
+                try:
+                    blkid_proc = subprocess.run(
+                        ["blkid", "-L", lbl], capture_output=True, text=True, timeout=10
+                    )
+                    if blkid_proc.returncode != 0 or not blkid_proc.stdout.strip():
+                        continue
+                    dev = blkid_proc.stdout.strip()
+                    mnt_proc = subprocess.run(
+                        ["findmnt", "-n", "-o", "TARGET", dev],
+                        capture_output=True,
+                        text=True,
+                        timeout=10,
+                    )
+                    if mnt_proc.returncode == 0 and mnt_proc.stdout.strip():
+                        detected_paths.append(Path(mnt_proc.stdout.strip()))
+                    elif lbl == "Ventoy":
+                        mount_point = _udisksctl_mount(dev)
+                        if mount_point:
+                            detected_paths.append(mount_point)
+                        else:
+                            _mount_device(dev, detected_paths)
+                except Exception:  # noqa: S112 - try the next candidate device
+                    continue
+
+    elif system == "Darwin":
+        import plistlib
+
+        cmd = ["diskutil", "list", "-plist"]
+        result = subprocess.run(cmd, capture_output=True)
+
+        if result.returncode != 0:
+            return []
+
+        try:
+            data = plistlib.loads(result.stdout)
+
+            for pool in data.get("AllDisksAndPartitions", []):
+                for partition in pool.get("Partitions", [pool]):
+                    volume_name = partition.get("VolumeName")
+                    mount_point = partition.get("MountPoint")
+
+                    if volume_name in ["Ventoy", "VTOYEFI"] and mount_point:
+                        detected_paths.append(Path(mount_point))
+        except Exception:
+            return []
+
+    elif system == "Windows":
+        import json
+
+        cmd = "@(Get-Volume | Where-Object {$_.FileSystemLabel -match 'Ventoy|VTOYEFI'} | Select-Object DriveLetter) | ConvertTo-Json"
+        result = subprocess.run(
+            ["powershell", "-Command", cmd], capture_output=True, text=True
+        )
+
+        if not result.stdout.strip():
+            return []
+
+        detected_paths = []
+        try:
+            drives_data = json.loads(result.stdout)
+            if isinstance(drives_data, dict):
+                drives_data = [drives_data]
+
+            detected_paths = [
+                Path(f"{drive['DriveLetter']}:\\")
+                for drive in drives_data
+                if drive.get("DriveLetter")
+            ]
+        except json.JSONDecodeError:
+            return []
+
+    else:
+        raise NotImplementedError(
+            f"Unsupported operating system: {system}\nThis script currently supports Windows, macOS, and Linux.\nTo add support for your OS, please contribute to github.com/hxmbl/visync"
+        )
+
+    return detected_paths
+
+
+def get_iso_volume_id(iso_path: Path) -> str:
+    """Read the unchangeable internal Volume Identifier of an ISO file."""
+    try:
+        with iso_path.open("rb") as f:
+            # Skip directly to the ISO 9660 primary descriptor header
+            f.seek(32808)
+            volume_id = f.read(32)
+            return volume_id.decode("utf-8", errors="ignore").strip("\x00 ")
+    except Exception:
+        return ""
+
+
+def _norm_tokens(text: str) -> str:
+    """Lowercase and collapse every non-alphanumeric run into single spaces."""
+    return re.sub(r"[^a-z0-9]+", " ", text.lower()).strip()
+
+
+def keyword_hit(keyword: str, text: str) -> bool:
+    """Whole-token match of *keyword* inside *text*.
+
+    'pop' matches 'pop-os_1.iso' or volume 'POP OS' but not 'popcorn'.
+    Multi-part keywords ('nixos-minimal') must appear as consecutive tokens.
+    """
+    kw = _norm_tokens(keyword)
+    if not kw:
+        return False
+    return re.search(rf"(?<!\w){re.escape(kw)}(?!\w)", _norm_tokens(text)) is not None
+
+
+def keyword_hit_loose(keyword: str, text: str) -> bool:
+    """Whole-token match of *keyword* with tokens allowed to be non-adjacent.
+
+    Needed where upstream inserts a version between the words: Ubuntu's volume
+    ID is ``Ubuntu 26.04.1 LTS amd64`` and its filename
+    ``ubuntu-26.04.1-desktop-amd64.iso``, so the keyword ``ubuntu-desktop``
+    never appears as consecutive tokens and the strict matcher cannot see it.
+    Every token of the keyword must still be present as a whole token, and in
+    order, so ``ubuntu-desktop`` does not match a Linux Mint desktop ISO.
+    """
+    tokens = _norm_tokens(keyword).split()
+    if not tokens:
+        return False
+    haystack = _norm_tokens(text).split()
+    position = 0
+    for token in tokens:
+        while position < len(haystack) and haystack[position] != token:
+            position += 1
+        if position == len(haystack):
+            return False
+        position += 1
+    return True
+
+
+def identify_distro(volume_id: str, file_name: str) -> str:
+    """Match the OS distribution using a cascading hybrid approach.
+
+    Checks strict Volume ID matches, contextual filename overrides for forks,
+    standalone keyword rules, and finally regex filename parsing as fallback.
+    """
+    import re
+
+    vol_lower = volume_id.lower().strip()
+    file_lower = file_name.lower().strip()
+
+    config = load_config()
+
+    # Check standalone matches first — they're more specific than base distros.
+    # Tried most-specific first: the raw TOML order is what decided specificity
+    # before, so reordering two lines silently changed which name won.
+    standalone_matches = config.get("standalone_matches", {})
+    for keyword, clean_name in sorted(
+        standalone_matches.items(), key=lambda kv: -len(_norm_tokens(kv[0]))
+    ):
+        if keyword_hit(keyword, vol_lower) or keyword_hit(keyword, file_lower):
+            return clean_name
+    # Second pass for keywords upstream splits with a version in the middle
+    # ("ubuntu-desktop" vs "ubuntu-26.04.1-desktop-amd64.iso"). Still whole-token
+    # and still longest-first, so 'ubuntu-desktop' cannot be beaten by 'pop'.
+    for keyword, clean_name in sorted(
+        standalone_matches.items(), key=lambda kv: -len(_norm_tokens(kv[0]))
+    ):
+        if keyword_hit_loose(keyword, vol_lower) or keyword_hit_loose(
+            keyword, file_lower
+        ):
+            return clean_name
+
+    base_distros = config.get("base_distros", {})
+    fork_overrides = config.get("fork_overrides", {})
+
+    for base_key, base_name in base_distros.items():
+        if keyword_hit(base_key, vol_lower):
+            for override_key, clean_name in fork_overrides.items():
+                parent, _, keyword = override_key.partition(".")
+                if parent == base_key and keyword_hit(keyword, file_lower):
+                    return clean_name
+            return base_name
+
+    if not file_lower.endswith(".iso"):
+        return "Unknown OS"
+
+    name_match = re.match(r"^([a-zA-Z_\-]+?)(?:[-_]v?\d|\.)", file_name)
+    if name_match:
+        return name_match.group(1).replace("-", " ").replace("_", " ").title().strip()
+
+    return "Unknown OS"
+
+
+def find_installed_isos(directory: Path) -> list[Path]:
+    """Find all ISO/IMG files under the given directory, ignoring macOS resource forks and .visync metadata."""
+    return [
+        p
+        for p in directory.rglob("*")
+        if p.suffix.lower() in (".iso", ".img")
+        and not p.name.startswith("._")
+        and ".visync" not in p.parts
+    ]
+
+
+# ── .visync metadata engine ──────────────────────────────────────
+
+
+def ensure_visync_dir(drive_root: Path) -> Path:
+    """Create .visync/metadata/ at the drive root if it doesn't exist. Returns the metadata dir."""
+    visync_dir = drive_root / ".visync"
+    metadata_dir = visync_dir / "metadata"
+    metadata_dir.mkdir(parents=True, exist_ok=True)
+    return metadata_dir
+
+
+def read_iso_metadata(drive_root: Path, filename: str) -> dict | None:
+    """Read cached JSON metadata for a given ISO filename. Returns None if not found or invalid."""
+    metadata_dir = drive_root / ".visync" / "metadata"
+    meta_file = metadata_dir / f"{filename}.json"
+    try:
+        with meta_file.open() as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return None
+    if not isinstance(data, dict):
+        return None
+    # Validate required keys exist
+    if "variant_stem" in data and "version" in data:
+        return data
+    return None
+
+
+def write_iso_metadata(
+    drive_root: Path,
+    filename: str,
+    variant_stem: str,
+    version: str,
+    sha256: str,
+    size: int = 0,
+) -> None:
+    """Write a JSON metadata manifest for a successfully synced ISO."""
+    metadata_dir = ensure_visync_dir(drive_root)
+    meta_file = metadata_dir / f"{filename}.json"
+    manifest = {
+        "variant_stem": variant_stem,
+        "version": version,
+        "sha256": sha256,
+        "size": size,
+        "sync_timestamp": datetime.now(UTC).isoformat(),
+    }
+    try:
+        tmp_file = meta_file.with_suffix(".json.tmp")
+        with tmp_file.open("w") as f:
+            json.dump(manifest, f, indent=2)
+        tmp_file.replace(meta_file)
+    except OSError as e:
+        console.print(
+            f"  [yellow]⚠[/yellow] Could not write metadata for {_escape(filename)}: {_escape(str(e))}"
+        )
+
+
+def remove_iso_metadata(drive_root: Path, filename: str) -> None:
+    """Delete the metadata file for a given ISO (called when an ISO is removed)."""
+    metadata_dir = drive_root / ".visync" / "metadata"
+    meta_file = metadata_dir / f"{filename}.json"
+    # The caller treats a failed delete as "metadata stays behind"; the watchdog
+    # will retry. Only OSError is swallowed, as before.
+    with contextlib.suppress(OSError):
+        meta_file.unlink(missing_ok=True)
+
+
+def load_all_metadata(drive_root: Path) -> dict[str, dict]:
+    """Bulk-load all ISO metadata from .visync/metadata/. Returns {filename: manifest}."""
+    metadata_dir = drive_root / ".visync" / "metadata"
+    if not metadata_dir.is_dir():
+        return {}
+    result = {}
+    for meta_file in metadata_dir.glob("*.json"):
+        if meta_file.name.startswith("._"):
+            continue
+        filename = meta_file.stem
+        data = read_iso_metadata(drive_root, filename)
+        if data:
+            result[filename] = data
+    return result
+
+
+# ── .visync watchdog ─────────────────────────────────────────────
+
+VISYNC_SIZE_LIMIT = 1_073_741_824  # 1 GiB
+_WATCHDOG_DIR_NAME = ".visync"
+# An allowlist, not a blocklist of ".iso"/".img": every deletion the watchdog can
+# perform is checked against this, so anything not listed here is refused. That
+# covers .iso and .img without naming them, and also covers a future file type
+# nobody thought to block.
+_WATCHDOG_ALLOWED_EXTENSIONS = {".json"}
+
+
+def _guard_json_only(path: Path) -> None:
+    """Assert that a file path is a permitted extension for metadata cleanup.
+
+    Raises ValueError immediately if the file is not a .json file.
+    This prevents accidental deletion of ISO or IMG files.
+    """
+    if path.suffix.lower() not in _WATCHDOG_ALLOWED_EXTENSIONS:
+        raise ValueError(
+            f"SAFETY BLOCK: refusing to delete '{path.name}' — "
+            f"only {_WATCHDOG_ALLOWED_EXTENSIONS} files are permitted. "
+            f"Blocked extension: {path.suffix}"
+        )
+
+
+def _guard_visync_path(target: Path) -> None:
+    """Assert that a directory path is exactly '.visync' and not drive root.
+
+    Raises ValueError immediately if:
+    - The path does not end with '.visync'
+    - The path IS the drive root itself
+    - The path name doesn't match exactly (prevents '../' traversal)
+    """
+    if target.name != _WATCHDOG_DIR_NAME:
+        raise ValueError(
+            f"SAFETY BLOCK: refusing to wipe '{target}' — "
+            f"target directory must be named exactly '{_WATCHDOG_DIR_NAME}'. "
+            f"Got name: '{target.name}'"
+        )
+    if not target.is_dir():
+        raise ValueError(
+            f"SAFETY BLOCK: refusing to wipe '{target}' — target is not a directory."
+        )
+    # Ensure it's a direct child, not a traversal to root
+    if target == target.parent:
+        raise ValueError(
+            f"SAFETY BLOCK: refusing to wipe '{target}' — "
+            f"target resolves to itself (would delete root)."
+        )
+
+
+def _dir_size(path: Path) -> int:
+    """Return total size in bytes of a directory tree."""
+    total = 0
+    try:
+        for entry in path.rglob("*"):
+            if entry.is_file():
+                total += entry.stat().st_size
+    except OSError:
+        pass
+    return total
+
+
+def visync_watchdog(drive_root: Path, *, allow_wipe: bool = False) -> None:
+    """Keep .visync/ under its size ceiling.
+
+    Stage 1 — deep clean (always): delete metadata whose ISO no longer exists on
+    the drive. This only removes ``.json`` orphans and is self-healing, so it
+    runs unattended.
+
+    Stage 2 — full wipe (opt-in, ``allow_wipe=True``): rmtree the directory.
+
+    Why stage 2 is opt-in: legitimate .visync/ state is installed.json plus one
+    ~236-byte manifest per ISO. Even a thousand ISOs is ~230 KiB against a
+    1 GiB ceiling, so being over budget is *never* legitimate and a wipe can
+    never repair a real problem — it can only destroy installed.json and every
+    registration. The realistic way to get here is a misconfigured
+    ``[iso] download_dir`` pointing under .visync/, which stages multi-GB ISOs
+    inside the directory. So by default we deep clean and then tell the user
+    exactly how to reclaim the space.
+
+    SAFETY: before any rmtree the target is validated to be exactly '.visync'
+    and not the drive root; a ValueError propagates immediately.
+    """
+    try:
+        visync_dir = drive_root / _WATCHDOG_DIR_NAME
+        if not visync_dir.is_dir():
+            return
+
+        size = _dir_size(visync_dir)
+        if size <= VISYNC_SIZE_LIMIT:
+            return
+
+        console.print(
+            f"  [yellow]⚠[/yellow] Watchdog: .visync/ is {size / (1024**2):.1f} MiB (limit: 1 GiB). Running deep clean..."
+        )
+        _deep_clean_metadata(drive_root)
+
+        size_after = _dir_size(visync_dir)
+        if size_after <= VISYNC_SIZE_LIMIT:
+            console.print(
+                f"  [green]✓[/green] Deep clean recovered space. .visync/ now {size_after / (1024**2):.1f} MiB."
+            )
+            return
+
+        if not allow_wipe:
+            console.print(
+                f"  [yellow]⚠[/yellow] Watchdog: .visync/ is still {size_after / (1024**2):.1f} MiB after deep clean."
+            )
+            console.print(
+                "  [dim]Not wiping automatically — this destroys installed.json and every"
+                " registration.[/dim]"
+            )
+            console.print(
+                "  [dim]Re-run with --reset-visync to wipe .visync/, or point"
+                f" {_escape('[iso]')} download_dir outside .visync/.[/dim]"
+            )
+            return
+
+        # GUARDRAIL: Validate target before any recursive deletion
+        _guard_visync_path(visync_dir)
+
+        console.print(
+            f"  [yellow]⚠[/yellow] Watchdog: wiping .visync/ ({size_after / (1024**2):.1f} MiB) as requested."
+        )
+        import shutil
+
+        try:
+            shutil.rmtree(visync_dir)
+            console.print(
+                "  [green]✓[/green] .visync/ wiped. Metadata will rebuild on next sync."
+            )
+        except OSError as e:
+            console.print(
+                f"  [yellow]⚠[/yellow] Could not wipe .visync/: {_escape(str(e))}"
+            )
+    except ValueError:
+        raise
+    except Exception as e:
+        console.print(f"  [yellow]⚠[/yellow] Watchdog error: {_escape(str(e))}")
+
+
+def _deep_clean_metadata(drive_root: Path) -> None:
+    """Remove metadata files whose corresponding ISO no longer exists on the drive.
+
+    SAFETY: Only files ending with '.json' inside the metadata directory
+    are eligible for deletion. A ValueError is raised immediately if any
+    non-.json file is encountered.
+    """
+    try:
+        metadata_dir = drive_root / _WATCHDOG_DIR_NAME / "metadata"
+        if not metadata_dir.is_dir():
+            return
+
+        existing_isos = {p.name for p in find_installed_isos(drive_root)}
+        removed = 0
+        skipped_non_json = 0
+        for meta_file in metadata_dir.iterdir():
+            # GUARDRAIL: Only allow .json files — anything else is left alone
+            if not meta_file.is_file():
+                continue
+            if meta_file.suffix.lower() not in _WATCHDOG_ALLOWED_EXTENSIONS:
+                skipped_non_json += 1
+                continue
+            _guard_json_only(meta_file)
+
+            iso_name = meta_file.stem  # .json filename = ISO filename
+            if iso_name not in existing_isos:
+                try:
+                    meta_file.unlink()
+                    removed += 1
+                except OSError as e:
+                    console.print(
+                        f"  [yellow]⚠[/yellow] Could not remove {_escape(meta_file.name)}: {_escape(str(e))}"
+                    )
+        if removed:
+            console.print(f"  [dim]Removed {removed} orphaned metadata file(s).[/dim]")
+        if skipped_non_json:
+            console.print(
+                f"  [yellow]⚠[/yellow] Skipped {skipped_non_json} non-metadata file(s) in .visync/metadata/."
+            )
+    except ValueError:
+        raise
+    except Exception as e:
+        console.print(f"  [yellow]⚠[/yellow] Deep clean error: {_escape(str(e))}")