Flight Ticket Search

#!/usr/bin/env python3
"""Free flight ticket search helper for the k-skill flight-ticket-search skill.

Uses fast-flights (Google Flights public surface scraper) in an isolated user cache venv.
No API key, login, CAPTCHA bypass, purchase, or booking automation.
"""
from __future__ import annotations

import argparse
import json
import os
import re
import statistics
import shutil
import subprocess
import sys
import time
from dataclasses import asdict
from datetime import date, datetime, timedelta
from pathlib import Path
from typing import Any, Iterable
from urllib.parse import urlencode

PINNED_FAST_FLIGHTS = "fast-flights==2.2"
CACHE_ROOT = Path.home() / ".cache" / "k-skill" / "flight-ticket-search"
VENV_DIR = CACHE_ROOT / "venv"


def ensure_runtime() -> None:
    """Install fast-flights into a private cache venv, then re-exec there."""
    if os.environ.get("FLIGHT_TICKET_SEARCH_BOOTSTRAPPED") == "1":
        return

    py = VENV_DIR / "bin" / "python"

    def candidate_python_executables() -> list[str]:
        candidates = [sys.executable]
        candidates.extend(
            found for name in ("python3.13", "python3.12", "python3.11", "python3")
            if (found := shutil.which(name))
        )
        seen: set[str] = set()
        unique: list[str] = []
        for candidate in candidates:
            resolved = str(Path(candidate).resolve())
            if resolved not in seen:
                seen.add(resolved)
                unique.append(candidate)
        return unique

    def create_venv() -> None:
        CACHE_ROOT.mkdir(parents=True, exist_ok=True)
        errors: list[str] = []
        for python in candidate_python_executables():
            shutil.rmtree(VENV_DIR, ignore_errors=True)
            try:
                subprocess.check_call([python, "-m", "venv", str(VENV_DIR)])
                return
            except (OSError, subprocess.CalledProcessError) as exc:
                errors.append(f"{python}: {exc}")
        raise RuntimeError(
            "Unable to create flight-ticket-search venv with available Python interpreters: "
            + "; ".join(errors)
        )

    def venv_has_fast_flights() -> bool:
        if not py.exists():
            return False
        return subprocess.run(
            [str(py), "-c", "import fast_flights"],
            stdout=subprocess.DEVNULL,
            stderr=subprocess.DEVNULL,
            check=False,
        ).returncode == 0

    if not py.exists():
        create_venv()

    if not venv_has_fast_flights():
        try:
            subprocess.check_call([str(py), "-m", "ensurepip", "--upgrade"])
            subprocess.check_call([
                str(py),
                "-m",
                "pip",
                "install",
                "--disable-pip-version-check",
                "-q",
                PINNED_FAST_FLIGHTS,
            ])
        except (OSError, subprocess.CalledProcessError):
            # Recover from interrupted or pip-less cache venvs before surfacing a hard failure.
            shutil.rmtree(VENV_DIR, ignore_errors=True)
            create_venv()
            subprocess.check_call([str(py), "-m", "ensurepip", "--upgrade"])
            subprocess.check_call([
                str(py),
                "-m",
                "pip",
                "install",
                "--disable-pip-version-check",
                "-q",
                PINNED_FAST_FLIGHTS,
            ])


    env = os.environ.copy()
    env["FLIGHT_TICKET_SEARCH_BOOTSTRAPPED"] = "1"
    os.execve(str(py), [str(py), __file__, *sys.argv[1:]], env)


def parse_date(s: str) -> date:
    return datetime.strptime(s, "%Y-%m-%d").date()


def positive_int(value: str) -> int:
    parsed = int(value)
    if parsed < 1:
        raise argparse.ArgumentTypeError("must be a positive integer")
    return parsed


def nonnegative_int(value: str) -> int:
    parsed = int(value)
    if parsed < 0:
        raise argparse.ArgumentTypeError("must be zero or a positive i