veltro-cli 0.15.7__py3-none-any.whl

veltro_cli/lib/doctor.py

@@ -0,0 +1,99 @@
+"""veltro doctor — host and install preflight."""
+
+from __future__ import annotations
+
+import sys
+from pathlib import Path
+from typing import TextIO
+
+from veltro_cli.lib.host import (
+    CheckResult,
+    check_clock_skew,
+    check_compose,
+    check_disk,
+    check_docker,
+    check_env_file,
+    check_host_minimums,
+    check_port_free,
+    check_public_url_dns,
+    check_python,
+    check_versions_env,
+    check_vm_max_map_count,
+)
+from veltro_cli.lib.paths import resolve_dir
+from veltro_cli.lib.products import resolve_selection
+from veltro_cli.lib.toml_config import VELTRO_TOML, read_config
+
+
+def run_doctor(
+    *,
+    directory: str | Path | None = None,
+    products: str | None = None,
+    public_url: str | None = None,
+    http_port: int = 80,
+    stream: TextIO | None = None,
+) -> int:
+    out = stream or sys.stdout
+    root = resolve_dir(directory)
+    cfg = read_config(root / VELTRO_TOML)
+    selected = resolve_selection(root, products)
+    public_url = public_url or (cfg.public_url if cfg else "http://localhost")
+
+    checks: list[CheckResult] = [
+        check_python(),
+        check_docker(),
+        check_compose(),
+        check_disk(root),
+        *check_host_minimums(),
+        check_vm_max_map_count(required=("chad" in selected)),
+        check_port_free(http_port),
+        check_versions_env(root),
+        check_env_file(root),
+        check_public_url_dns(public_url),
+        check_clock_skew(),
+    ]
+
+    # Identity is present even when no products are selected.
+    if (root / ".env").is_file():
+        checks.append(_identity_credentials_check(root, selected))
+
+    worst = 0
+    for check in checks:
+        mark = {"pass": "PASS", "warn": "WARN", "fail": "FAIL"}[check.status]
+        line = f"[{mark}] {check.name}: {check.detail}"
+        if check.remedy and check.status != "pass":
+            line += f"\n       fix: {check.remedy}"
+        print(line, file=out)
+        if check.status == "fail":
+            worst = 1
+    return worst
+
+
+def _identity_credentials_check(root: Path, products: tuple[str, ...] | None = None) -> CheckResult:
+    scripts = root / "scripts"
+    if str(scripts) not in sys.path:
+        sys.path.insert(0, str(scripts))
+    try:
+        import validate_identity_credentials as vic  # type: ignore
+    except ImportError:
+        return CheckResult(
+            "identity_credentials",
+            "warn",
+            "validate_identity_credentials.py not importable",
+        )
+    env_file = root / ".env"
+    missing = vic.missing(env_file, {}, products=products)
+    problems = (
+        list(missing)
+        + vic.dsn_problems(env_file, {})
+        + vic.session_secret_problems(env_file, {})
+        + vic.signing_passphrase_problems(env_file, {})
+    )
+    if problems:
+        return CheckResult(
+            "identity_credentials",
+            "fail",
+            "; ".join(problems[:3]) + ("…" if len(problems) > 3 else ""),
+            remedy="re-run `veltro install` or fill VELTRO_IDENTITY_* in .env",
+        )
+    return CheckResult("identity_credentials", "pass", "suite credentials present")

veltro_cli/lib/env_init.py

@@ -0,0 +1,93 @@
+"""Bootstrap .env from .env.example (Python port of scripts/init-env.sh)."""
+
+from __future__ import annotations
+
+import os
+import secrets
+import stat
+from pathlib import Path
+import tempfile
+
+from veltro_cli.lib.errors import VeltroCliError
+
+
+def _hex_secret(nbytes: int = 32) -> str:
+    return secrets.token_hex(nbytes)
+
+
+def generate_env_text(example_text: str) -> tuple[str, list[str]]:
+    """Replace secret placeholders and keep identity DSNs consistent."""
+    generated: list[str] = []
+    generated_values: dict[str, str] = {}
+    out_lines: list[str] = []
+    for line in example_text.splitlines(keepends=True):
+        if "=" in line and not line.lstrip().startswith("#"):
+            key, _, value = line.rstrip("\n").partition("=")
+            key = key.strip()
+            if key and value.startswith("change-me"):
+                if key == "OPENSEARCH_ADMIN_PASSWORD":
+                    # OpenSearch requires upper+lower+digit+special.
+                    secret = _hex_secret(24) + "Aa1@"
+                else:
+                    secret = _hex_secret(32)
+                out_lines.append(f"{key}={secret}\n")
+                generated.append(key)
+                generated_values[key] = secret
+                continue
+        out_lines.append(line if line.endswith("\n") else line + "\n")
+
+    text = "".join(out_lines)
+    dsn_passwords = {
+        "VELTRO_IDENTITY_MIGRATION_DATABASE_URL": "VELTRO_IDENTITY_OWNER_PASSWORD",
+        "VELTRO_IDENTITY_RUNTIME_DATABASE_URL": "VELTRO_IDENTITY_RUNTIME_PASSWORD",
+        "VELTRO_IDENTITY_IMPORTER_DATABASE_URL": "VELTRO_IDENTITY_IMPORTER_PASSWORD",
+        "VELTRO_IDENTITY_RECOVERY_DATABASE_URL": "VELTRO_IDENTITY_RECOVERY_PASSWORD",
+    }
+    lines: list[str] = []
+    for line in text.splitlines(keepends=True):
+        key, separator, value = line.partition("=")
+        password_key = dsn_passwords.get(key.strip()) if separator else None
+        password = generated_values.get(password_key or "")
+        if password and ":***@" in value:
+            line = f"{key}={value.replace(':***@', f':{password}@', 1)}"
+        lines.append(line)
+    return "".join(lines), generated
+
+
+def init_env(
+    root: Path,
+    *,
+    force: bool = False,
+    example_name: str = ".env.example",
+    env_name: str = ".env",
+) -> list[str]:
+    example = root / example_name
+    env_path = root / env_name
+    if not example.is_file():
+        raise VeltroCliError(
+            f"{example} not found",
+            remedy="run this from a Veltro install directory (after `veltro install`) or pass --dir",
+        )
+    if env_path.is_file() and not force:
+        raise VeltroCliError(
+            f"{env_path} already exists — refusing to overwrite",
+            remedy="re-run with --force to regenerate secrets",
+        )
+    text, generated = generate_env_text(example.read_text(encoding="utf-8"))
+    fd, temp_name = tempfile.mkstemp(prefix=f".{env_path.name}.", dir=env_path.parent)
+    temp_path = Path(temp_name)
+    try:
+        os.fchmod(fd, stat.S_IRUSR | stat.S_IWUSR)
+        stream = os.fdopen(fd, "w", encoding="utf-8")
+        fd = -1
+        with stream:
+            stream.write(text)
+            stream.flush()
+            os.fsync(stream.fileno())
+        os.replace(temp_path, env_path)
+    except BaseException:
+        if fd >= 0:
+            os.close(fd)
+        temp_path.unlink(missing_ok=True)
+        raise
+    return generated

veltro_cli/lib/errors.py

@@ -0,0 +1,40 @@
+"""Operator-facing CLI errors with remedy + support-bundle hint."""
+
+from __future__ import annotations
+
+
+class VeltroCliError(Exception):
+    """A named, operator-facing failure."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        remedy: str | None = None,
+        code: int = 1,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.remedy = remedy
+        self.code = code
+
+    def format(self) -> str:
+        lines = [f"error: {self.message}"]
+        if self.remedy:
+            lines.append(f"remedy: {self.remedy}")
+        lines.append("hint: run `veltro support-bundle` and attach the archive when asking for help")
+        return "\n".join(lines)
+
+
+
+
+def print_error(exc: BaseException, *, file=None) -> int:
+    import sys
+
+    out = file or sys.stderr
+    if isinstance(exc, VeltroCliError):
+        print(exc.format(), file=out)
+        return exc.code
+    print(f"error: {exc}", file=out)
+    print("hint: run `veltro support-bundle` and attach the archive when asking for help", file=out)
+    return 1

veltro_cli/lib/host.py

@@ -0,0 +1,346 @@
+"""Host preflight checks used by doctor and install."""
+
+from __future__ import annotations
+
+import os
+import re
+import shutil
+import socket
+import subprocess
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from email.utils import parsedate_to_datetime
+from pathlib import Path
+from typing import Any, Callable, Sequence
+
+from veltro_cli.lib.compose import which_docker
+
+# Minimum specs from the plan (README "Minimum specs").
+MIN_SPECS = {"vcpu": 4, "ram_gb": 16}
+OPENSEARCH_VM_MAX_MAP = 262144
+MIN_DISK_GB = 20
+COMPOSE_MIN = (2, 20)
+
+
+@dataclass(frozen=True)
+class CheckResult:
+    name: str
+    status: str  # pass | warn | fail
+    detail: str
+    remedy: str = ""
+
+    @property
+    def ok(self) -> bool:
+        return self.status != "fail"
+
+
+def _run(cmd: Sequence[str]) -> tuple[int, str, str]:
+    try:
+        p = subprocess.run(list(cmd), capture_output=True, text=True, check=False)
+    except FileNotFoundError:
+        return 127, "", f"{cmd[0]} not found"
+    return p.returncode, p.stdout or "", p.stderr or ""
+
+
+def check_python() -> CheckResult:
+    import sys
+
+    major, minor = sys.version_info[:2]
+    if (major, minor) >= (3, 10):
+        return CheckResult("python", "pass", f"{major}.{minor}")
+    return CheckResult(
+        "python",
+        "fail",
+        f"{major}.{minor}",
+        remedy="install Python ≥ 3.10",
+    )
+
+
+def check_docker() -> CheckResult:
+    path = which_docker()
+    if not path:
+        return CheckResult("docker", "fail", "not on PATH", remedy="install Docker Engine or Desktop")
+    code, out, err = _run([path, "version", "--format", "{{.Server.Version}}"])
+    if code != 0:
+        return CheckResult(
+            "docker",
+            "fail",
+            (err or out or "daemon not reachable").strip(),
+            remedy="start the Docker daemon",
+        )
+    return CheckResult("docker", "pass", out.strip() or path)
+
+
+def parse_compose_version(text: str) -> tuple[int, int] | None:
+    # docker compose version outputs like "Docker Compose version v2.29.1"
+    match = re.search(r"v?(\d+)\.(\d+)", text)
+    if not match:
+        return None
+    return int(match.group(1)), int(match.group(2))
+
+
+def check_compose() -> CheckResult:
+    path = which_docker()
+    if not path:
+        return CheckResult("compose", "fail", "docker missing", remedy="install Docker with Compose v2")
+    code, out, err = _run([path, "compose", "version"])
+    if code != 0:
+        return CheckResult(
+            "compose",
+            "fail",
+            (err or out or "compose plugin missing").strip(),
+            remedy="install Docker Compose ≥ 2.20 (compose plugin)",
+        )
+    version = parse_compose_version(out + err)
+    if version is None:
+        return CheckResult("compose", "warn", (out or err).strip() or "unknown version")
+    if version < COMPOSE_MIN:
+        return CheckResult(
+            "compose",
+            "fail",
+            f"{version[0]}.{version[1]}",
+            remedy="upgrade Docker Compose to ≥ 2.20 (required for `include:`)",
+        )
+    return CheckResult("compose", "pass", f"{version[0]}.{version[1]}")
+
+
+def check_disk(path: Path, *, min_gb: int = MIN_DISK_GB) -> CheckResult:
+    try:
+        usage = shutil.disk_usage(path if path.exists() else path.parent)
+    except OSError as exc:
+        return CheckResult("disk", "fail", str(exc), remedy="choose a writable --dir")
+    free_gb = usage.free / (1024**3)
+    if free_gb < min_gb:
+        return CheckResult(
+            "disk",
+            "fail",
+            f"{free_gb:.1f} GiB free",
+            remedy=f"free at least {min_gb} GiB on the install volume",
+        )
+    return CheckResult("disk", "pass", f"{free_gb:.1f} GiB free")
+
+
+def read_vm_max_map_count() -> int | None:
+    proc = Path("/proc/sys/vm/max_map_count")
+    if proc.is_file():
+        try:
+            return int(proc.read_text(encoding="utf-8").strip())
+        except ValueError:
+            return None
+    # macOS / other — Docker VM handles this; treat as N/A.
+    return None
+
+
+def check_vm_max_map_count(*, required: bool) -> CheckResult:
+    value = read_vm_max_map_count()
+    if value is None:
+        return CheckResult(
+            "vm.max_map_count",
+            "pass" if not required else "warn",
+            "not applicable on this host (Docker VM)",
+        )
+    if value < OPENSEARCH_VM_MAX_MAP:
+        return CheckResult(
+            "vm.max_map_count",
+            "fail" if required else "warn",
+            str(value),
+            remedy=f"sysctl -w vm.max_map_count={OPENSEARCH_VM_MAX_MAP}",
+        )
+    return CheckResult("vm.max_map_count", "pass", str(value))
+
+
+def check_port_free(port: int, host: str = "127.0.0.1") -> CheckResult:
+    """Best-effort free-port probe.
+
+    Connect-style first (is something listening?), then a bind attempt.
+    Permission errors on privileged ports are warnings on non-root hosts —
+    Docker can still publish them.
+    """
+    probe = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        probe.settimeout(0.3)
+        try:
+            probe.connect((host, port))
+        except (ConnectionRefusedError, TimeoutError, OSError):
+            in_use = False
+        else:
+            in_use = True
+    finally:
+        probe.close()
+    if in_use:
+        return CheckResult(
+            f"port:{port}",
+            "fail",
+            f"{host}:{port} already accepting connections",
+            remedy=f"free TCP port {port} or change VELTRO_HTTP_PORT",
+        )
+
+    sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+    try:
+        sock.setsockopt(socket.SOL_SOCKET, socket.SO_REUSEADDR, 1)
+        try:
+            sock.bind((host, port))
+        except PermissionError:
+            return CheckResult(
+                f"port:{port}",
+                "warn",
+                f"cannot bind {port} without privileges (will rely on Docker publish)",
+            )
+        except OSError as exc:
+            return CheckResult(
+                f"port:{port}",
+                "fail",
+                str(exc),
+                remedy=f"free TCP port {port} or change VELTRO_HTTP_PORT",
+            )
+        return CheckResult(f"port:{port}", "pass", f"{port} free")
+    finally:
+        sock.close()
+
+
+def check_versions_env(root: Path) -> CheckResult:
+    path = root / "versions.env"
+    if not path.is_file():
+        return CheckResult(
+            "versions.env",
+            "fail",
+            "missing",
+            remedy="restore versions.env from the release tarball / git checkout",
+        )
+    text = path.read_text(encoding="utf-8")
+    floating = []
+    for line in text.splitlines():
+        if "=" not in line or line.strip().startswith("#"):
+            continue
+        key, _, value = line.partition("=")
+        value = value.strip().strip('"').strip("'")
+        if value in {"latest", "dev"} or value.endswith(":latest"):
+            floating.append(f"{key.strip()}={value}")
+    if floating:
+        return CheckResult(
+            "versions.env",
+            "fail",
+            "floating tags: " + ", ".join(floating),
+            remedy="pin every image tag to an immutable release version",
+        )
+    return CheckResult("versions.env", "pass", "present, no floating tags")
+
+
+def check_env_file(root: Path) -> CheckResult:
+    path = root / ".env"
+    if not path.is_file():
+        return CheckResult(
+            ".env",
+            "fail",
+            "missing",
+            remedy="run `veltro install` or `python3 -m veltro_cli init-env`",
+        )
+    # Identity credentials are gated by validate_identity_credentials.
+    return CheckResult(".env", "pass", "present")
+
+
+def check_public_url_dns(url: str) -> CheckResult:
+    from urllib.parse import urlparse
+
+    parsed = urlparse(url)
+    host = parsed.hostname
+    if not host:
+        return CheckResult("dns", "fail", f"unparseable URL {url!r}", remedy="set a valid --public-url")
+    if host in {"localhost", "127.0.0.1", "::1"}:
+        return CheckResult("dns", "pass", f"{host} (loopback)")
+    try:
+        socket.getaddrinfo(host, parsed.port or 443)
+    except socket.gaierror as exc:
+        return CheckResult(
+            "dns",
+            "warn",
+            f"{host}: {exc}",
+            remedy="create a DNS A/AAAA record for PUBLIC_BASE_URL before enabling --tls auto",
+        )
+    return CheckResult("dns", "pass", host)
+
+def check_clock_skew(
+    *,
+    opener: Callable[..., Any] = urllib.request.urlopen,
+    now: Callable[[], datetime] = lambda: datetime.now(timezone.utc),
+    max_skew_seconds: int = 300,
+) -> CheckResult:
+    request = urllib.request.Request("https://api.github.com/", method="HEAD")
+    try:
+        with opener(request, timeout=5) as response:
+            date_header = response.headers.get("Date")
+    except Exception as exc:
+        return CheckResult(
+            "clock_skew",
+            "warn",
+            f"could not compare trusted time: {exc}",
+            remedy="verify NTP/time synchronization before enabling SSO",
+        )
+    if not date_header:
+        return CheckResult("clock_skew", "warn", "trusted response had no Date header")
+    try:
+        remote = parsedate_to_datetime(date_header).astimezone(timezone.utc)
+    except (TypeError, ValueError) as exc:
+        return CheckResult("clock_skew", "warn", f"invalid trusted Date header: {exc}")
+    skew = abs((now().astimezone(timezone.utc) - remote).total_seconds())
+    if skew > max_skew_seconds:
+        return CheckResult(
+            "clock_skew",
+            "fail",
+            f"{skew:.0f}s (maximum {max_skew_seconds}s)",
+            remedy="enable NTP/chrony and synchronize the host clock",
+        )
+    return CheckResult("clock_skew", "pass", f"{skew:.0f}s")
+
+
+def cpu_count() -> int:
+    return os.cpu_count() or 1
+
+
+def ram_gb() -> float | None:
+    # Linux
+    meminfo = Path("/proc/meminfo")
+    if meminfo.is_file():
+        for line in meminfo.read_text(encoding="utf-8").splitlines():
+            if line.startswith("MemTotal:"):
+                kb = int(line.split()[1])
+                return kb / (1024 * 1024)
+    # macOS
+    code, out, _ = _run(["sysctl", "-n", "hw.memsize"])
+    if code == 0 and out.strip().isdigit():
+        return int(out.strip()) / (1024**3)
+    return None
+
+
+def check_host_minimums() -> list[CheckResult]:
+    spec = MIN_SPECS
+    results: list[CheckResult] = []
+    cpus = cpu_count()
+    if cpus < spec["vcpu"]:
+        results.append(
+            CheckResult(
+                "cpu",
+                "warn",
+                f"{cpus} vCPU (recommended ≥ {spec['vcpu']})",
+                remedy="use a larger host for production",
+            )
+        )
+    else:
+        results.append(CheckResult("cpu", "pass", f"{cpus} vCPU"))
+    ram = ram_gb()
+    if ram is None:
+        results.append(CheckResult("ram", "warn", "unknown"))
+    elif ram < spec["ram_gb"]:
+        results.append(
+            CheckResult(
+                "ram",
+                "warn",
+                f"{ram:.1f} GiB (recommended ≥ {spec['ram_gb']})",
+                remedy="use a larger host for production",
+            )
+        )
+    else:
+        results.append(CheckResult("ram", "pass", f"{ram:.1f} GiB"))
+    return results