visync 0.1.0__py3-none-any.whl

visync/net.py

@@ -0,0 +1,84 @@
+"""Network safety helpers shared by scraping, downloading, and verification."""
+
+import ipaddress
+import urllib.error
+import urllib.request
+from urllib.parse import urlparse
+
+_opener_installed = False
+
+# Names that unambiguously denote the local machine. Anything outside this set
+# must parse as an IP literal to earn the loopback exemption, which keeps
+# ambiguous spellings such as "127.1", the decimal form "2130706433", or a
+# lookalike host from slipping past as if they were loopback.
+_LOOPBACK_NAMES = frozenset({"localhost"})
+
+
+def _is_loopback(host: str | None) -> bool:
+    """True only for unambiguous loopback hosts.
+
+    Accepts the exact name "localhost", any "*.localhost" subdomain (RFC 6761
+    reserves the whole domain for loopback), and IPv4/IPv6 literals that
+    ipaddress classifies as loopback. Non-canonical and integer spellings of
+    127.0.0.1 are deliberately *not* treated as loopback: urllib would connect
+    to the local machine for them, so allowing them would hand out a cleartext
+    exemption for an address that merely looks local.
+
+    IPv4-mapped IPv6 (``::ffff:127.0.0.1``) is also excluded. It resolves to
+    loopback, but it is a distinct spelling that no legitimate local mirror
+    uses, so rejecting it costs nothing and removes an obfuscation avenue.
+    """
+    if not host:
+        return False
+    host = host.strip().strip("[]").lower()
+    if not host or host.endswith("."):
+        # A trailing dot is the fully-qualified form of the same name, but only
+        # for names; it is not valid on an IP literal and is not worth a
+        # second code path here.
+        host = host.rstrip(".")
+    if not host:
+        return False
+    if host in _LOOPBACK_NAMES or host.endswith(".localhost"):
+        return True
+    try:
+        address = ipaddress.ip_address(host)
+    except ValueError:
+        return False
+    if isinstance(address, ipaddress.IPv6Address) and address.ipv4_mapped:
+        return False
+    return address.is_loopback
+
+
+class SafeRedirectHandler(urllib.request.HTTPRedirectHandler):
+    """HTTPRedirectHandler that refuses to follow https -> cleartext redirects."""
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):
+        if (
+            urlparse(req.full_url).scheme == "https"
+            and urlparse(newurl).scheme != "https"
+        ):
+            raise urllib.error.URLError(
+                f"blocked insecure redirect downgrade: {req.full_url} -> {newurl}"
+            )
+        return super().redirect_request(req, fp, code, msg, headers, newurl)
+
+
+def install_safe_opener() -> None:
+    """Install the downgrade-safe opener once for the whole process."""
+    global _opener_installed
+    if _opener_installed:
+        return
+    urllib.request.install_opener(urllib.request.build_opener(SafeRedirectHandler()))
+    _opener_installed = True
+
+
+def require_https(url: str, what: str = "URL") -> None:
+    """Reject non-HTTPS fetch targets (unambiguous loopback exempt for testing).
+
+    The exemption exists so a local mirror or test server can be used during
+    development. It is deliberately narrow: only "localhost", "*.localhost" and
+    canonical loopback IP literals qualify.
+    """
+    parsed = urlparse(url)
+    if parsed.scheme != "https" and not _is_loopback(parsed.hostname):
+        raise ValueError(f"refusing {what} over non-HTTPS: {url}")

visync/output.py

@@ -0,0 +1,126 @@
+"""Rich-based output formatting for visync."""
+
+import threading
+
+from rich.console import Console
+from rich.markup import escape as _esc
+from rich.progress import (
+    BarColumn,
+    DownloadColumn,
+    Progress,
+    TextColumn,
+    TransferSpeedColumn,
+)
+from rich.status import Status
+from rich.table import Table
+
+console = Console()
+
+_status: Status | None = None
+_spin_lock = threading.Lock()
+
+
+def spin_start(msg: str) -> None:
+    """Start a global spinner at the bottom of the console."""
+    global _status
+    with _spin_lock:
+        if _status:
+            _status.stop()
+        _status = Status(msg, spinner="dots", console=console)
+        _status.start()
+
+
+def spin_update(msg: str) -> None:
+    """Update the global spinner message."""
+    with _spin_lock:
+        if _status:
+            _status.update(_esc(str(msg)))
+
+
+def spin_stop() -> None:
+    """Stop the global spinner."""
+    global _status
+    with _spin_lock:
+        if _status:
+            _status.stop()
+            _status = None
+
+
+def header(text: str) -> None:
+    console.print(f"\n[bold]{_esc(str(text))}[/bold]\n")
+
+
+def success(msg: str) -> None:
+    console.print(f"  [green]✓[/green] {_esc(str(msg))}")
+
+
+def info(msg: str) -> None:
+    console.print(f"  [dim]{_esc(str(msg))}[/dim]")
+
+
+def warn(msg: str) -> None:
+    console.print(f"  [yellow]⚠[/yellow] {_esc(str(msg))}")
+
+
+def error(msg: str) -> None:
+    console.print(f"  [red]✗[/red] {_esc(str(msg))}")
+
+
+def removed(msg: str) -> None:
+    # A plain hyphen, not an en dash: the CLI's glyphs are ✓ ⚠ ✗ - , and the
+    # en dash (U+2013) is a homoglyph for a hyphen that appears nowhere else in
+    # the output.
+    console.print(f"  [yellow]-[/yellow] {_esc(str(msg))}")
+
+
+def iso_table(rows: list[tuple[str, str, str, str]], total_gb: float) -> None:
+    """Render a rich table of ISO files. Cell values are markup-escaped."""
+    table = Table(
+        show_header=True,
+        header_style="bold",
+        pad_edge=False,
+        show_lines=False,
+    )
+    table.add_column("Distro", style="cyan", no_wrap=True)
+    table.add_column("Version", style="green")
+    table.add_column("Size", justify="right", style="magenta")
+    table.add_column("Filename", style="dim")
+
+    for distro, version, size, filename in rows:
+        table.add_row(_esc(distro), _esc(version), _esc(size), _esc(filename))
+
+    console.print(table)
+    console.print(f"\n  [dim]{len(rows)} ISO(s) — {total_gb:.1f} GiB total[/dim]")
+
+
+def failure_table(rows: list[tuple[str, str]]) -> None:
+    """Render (name, reason) pairs as an aligned, markup-escaped table.
+
+    A table (rather than hand-formatted lines) keeps long URLs and reasons from
+    wrapping back to column zero and destroying the indentation.
+    """
+    table = Table(
+        show_header=True,
+        header_style="bold",
+        pad_edge=False,
+        show_lines=False,
+        box=None,
+    )
+    table.add_column("Problem", style="red", no_wrap=True)
+    table.add_column("Reason", style="yellow")
+
+    for name, reason in rows:
+        table.add_row(_esc(str(name)), _esc(str(reason)))
+
+    console.print(table)
+
+
+def make_download_progress() -> Progress:
+    """Create a rich Progress bar for ISO downloads."""
+    return Progress(
+        TextColumn("[bold blue]{task.fields[filename]}[/bold blue]"),
+        BarColumn(),
+        DownloadColumn(),
+        TransferSpeedColumn(),
+        console=console,
+    )

visync/pm.py

@@ -0,0 +1,133 @@
+"""Package manager state and operations for visync.
+
+Tracks which distros are "installed" (wanted) on the Ventoy drive.
+State file: .visync/installed.json
+"""
+
+import json
+from datetime import UTC, datetime
+from pathlib import Path
+
+from visync.output import warn
+
+
+def _state_path(drive_root: Path) -> Path:
+    """Path to the installed.json state file."""
+    return drive_root / ".visync" / "installed.json"
+
+
+def load_installed(drive_root: Path) -> dict:
+    """Load the installed distros state. Returns {entry_id: {installed_at, version}}.
+
+    Corrupt or non-object JSON is treated as empty state (with a warning)
+    rather than crashing every subsequent command.
+    """
+    path = _state_path(drive_root)
+    if not path.exists():
+        return {}
+    try:
+        with path.open() as f:
+            data = json.load(f)
+    except (json.JSONDecodeError, OSError):
+        return {}
+    if not isinstance(data, dict):
+        warn(f"installed.json has unexpected shape ({type(data).__name__}) — ignoring")
+        return {}
+    return data
+
+
+def save_installed(drive_root: Path, installed: dict) -> None:
+    """Save the installed distros state atomically (tmp file + rename)."""
+    path = _state_path(drive_root)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    tmp_path = path.with_suffix(".json.tmp")
+    with tmp_path.open("w") as f:
+        json.dump(installed, f, indent=2)
+    tmp_path.replace(path)
+
+
+def mark_installed(drive_root: Path, entry_id: str, version: str = "") -> None:
+    """Mark a distro as installed."""
+    installed = load_installed(drive_root)
+    installed[entry_id] = {
+        "installed_at": datetime.now(UTC).isoformat(),
+        "version": version,
+    }
+    save_installed(drive_root, installed)
+
+
+def mark_removed(drive_root: Path, entry_id: str) -> None:
+    """Mark a distro as removed."""
+    installed = load_installed(drive_root)
+    installed.pop(entry_id, None)
+    save_installed(drive_root, installed)
+
+
+def get_installed_ids(drive_root: Path) -> list[str]:
+    """Return list of installed distro entry IDs."""
+    return list(load_installed(drive_root).keys())
+
+
+def _norm_query(text: str) -> str:
+    """Lowercase and collapse every run of non-alphanumerics to one space.
+
+    Lets ``ubuntu-desktop``, ``ubuntu_desktop``, ``Ubuntu Desktop`` and
+    ``UbuntuDesktop`` all reach the same entry. Reuses finder's normaliser so
+    query matching and filename matching cannot drift apart.
+    """
+    from visync.finder import _norm_tokens
+
+    return _norm_tokens(text)
+
+
+def matching_distros(query: str, config: dict) -> tuple[str | None, list[str]]:
+    """Match a user query to distro entry_ids.
+
+    Returns (exact_entry_id, partial_candidates). *exact_entry_id* is set for
+    an unambiguous exact match on entry_id, clean_name, or keyword, ignoring
+    case and separator style. *partial_candidates* lists every entry_id whose
+    entry_id or clean_name contains the query as a normalised substring.
+    """
+    query_norm = _norm_query(query)
+    if not query_norm:
+        return None, []
+    distros = config.get("distros", {})
+
+    for key in distros:
+        if _norm_query(key) == query_norm:
+            return key, []
+
+    for entry_id, settings in distros.items():
+        if _norm_query(settings.get("clean_name", "")) == query_norm:
+            return entry_id, []
+
+    keyword_hits = [
+        entry_id
+        for entry_id, settings in distros.items()
+        if _norm_query(settings.get("keyword", "")) == query_norm
+    ]
+    if len(keyword_hits) == 1:
+        return keyword_hits[0], []
+
+    partials = [
+        entry_id
+        for entry_id, settings in distros.items()
+        if query_norm in _norm_query(settings.get("clean_name", ""))
+        or query_norm in _norm_query(entry_id)
+    ]
+    return None, partials
+
+
+def resolve_distro(query: str, config: dict) -> str | None:
+    """Resolve a user query (name, keyword, partial match) to a distro entry_id.
+
+    Exact matches always win. Partial substring matches only resolve when
+    they are unique; ambiguous queries return None so callers can refuse
+    rather than act on an arbitrary pick.
+    """
+    exact, partials = matching_distros(query, config)
+    if exact:
+        return exact
+    if len(partials) == 1:
+        return partials[0]
+    return None