offbox 0.1.0__py3-none-any.whl

offbox/console.py

@@ -0,0 +1,63 @@
+import os
+import sys
+
+import typer
+from pydantic import BaseModel
+from rich.console import Console
+
+
+def _human(message: str, style: str = "") -> None:
+    Console(stderr=True, soft_wrap=True, no_color="NO_COLOR" in os.environ or not sys.stderr.isatty()).print(
+        message, style=style, markup=False, highlight=False
+    )
+
+
+def output(value: str) -> None:
+    print(value)
+
+
+def text(value: str) -> None:
+    sys.stdout.write(value)
+    sys.stdout.flush()
+
+
+def version(value: str) -> None:
+    output(value)
+
+
+def info(message: str) -> None:
+    _human(message)
+
+
+def success(message: str) -> None:
+    _human(f"✓ {message}", "green")
+
+
+def warn(message: str) -> None:
+    _human(f"! {message}", "yellow")
+
+
+def error(message: str, fix: str | None = None) -> None:
+    _human(f"✗ {message}", "red")
+    if fix:
+        _human(f"  Fix: {fix}")
+
+
+def step(message: str) -> None:
+    _human(f"→ {message}")
+
+
+def command(message: str) -> None:
+    _human(f"$ {message}", "dim")
+
+
+def interactive() -> bool:
+    return sys.stdin.isatty() and sys.stderr.isatty()
+
+
+def confirm(message: str) -> bool:
+    return bool(typer.confirm(message, default=True, err=True))
+
+
+def json_out(model: BaseModel) -> None:
+    output(model.model_dump_json())

offbox/doctor.py

@@ -0,0 +1,174 @@
+from pathlib import Path
+
+from pydantic import Field
+
+from offbox.config import Credentials, Model, UserConfig, default_host, load_config, load_credentials
+from offbox.errors import OffboxError, PreconditionError
+from offbox.host.auto import timer_status
+from offbox.host.timer import health as timer_health
+from offbox.host.timer import unit_problem
+from offbox.host.usage import utc_now
+from offbox.host.warnings import read_warnings
+from offbox.paths import Paths
+from offbox.project import load_project
+from offbox.runner import Runner
+from offbox.ssh import default_ssh_key
+from offbox.state import State, StateStore
+from offbox.tools import ToolDiscovery
+
+NO_DEFAULT_HOST = "No default host configured"
+
+
+class Check(Model):
+    name: str
+    ok: bool
+    message: str
+    fix: str | None = None
+
+
+class DoctorReport(Model):
+    checks: list[Check] = Field(default_factory=list[Check])
+
+    @property
+    def ok(self) -> bool:
+        return all(check.ok for check in self.checks)
+
+    @property
+    def exit_code(self) -> int:
+        return 0 if self.ok else 3
+
+
+def _failure(name: str, error: OffboxError) -> Check:
+    return Check(name=name, ok=False, message=error.message, fix=error.fix or "Correct the reported problem and retry offbox doctor.")
+
+
+def check_key(runner: Runner, key: Path, *, configured: bool = False) -> Check:
+    agent = runner.run(["ssh-add", "-l"], check=False, timeout=5)
+    if agent.returncode == 0 and agent.stdout.strip():
+        if not configured and not key.exists():
+            return Check(name="ssh-key", ok=True, message="SSH agent has a usable identity")
+        fingerprint_path = key if key.exists() else key.with_name(key.name + ".pub")
+        fingerprint = runner.run(["ssh-keygen", "-lf", str(fingerprint_path)], check=False, timeout=5)
+        fields = fingerprint.stdout.split()
+        if fingerprint.returncode == 0 and len(fields) > 1 and fields[1] in agent.stdout:
+            return Check(name="ssh-key", ok=True, message="SSH key is available in the agent")
+    if key.is_file():
+        unlocked = runner.run(["ssh-keygen", "-y", "-P", "", "-f", str(key)], check=False, timeout=5)
+        if unlocked.returncode == 0:
+            return Check(name="ssh-key", ok=True, message="SSH key is usable without a prompt")
+    return Check(
+        name="ssh-key",
+        ok=False,
+        message=f"SSH key is unavailable without a prompt: {key}",
+        fix=f"Generate {key} or load it with ssh-add {key}.",
+    )
+
+
+def diagnose(
+    paths: Paths, runner: Runner, *, project_root: Path | None = None, tools: ToolDiscovery | None = None, ssh_key: Path | None = None
+) -> DoctorReport:
+    report = DoctorReport()
+    discovery = tools or ToolDiscovery(runner, paths.cache)
+    for name in ("ssh", "git", "mutagen", "tofu"):
+        try:
+            tool = discovery.check(name)
+            source = ", downloaded by offbox" if tool.path.is_relative_to(paths.cache) else ""
+            report.checks.append(Check(name=name, ok=True, message=f"{tool.name} {tool.version} ({tool.path}{source})"))
+        except OffboxError as exc:
+            report.checks.append(_failure(name, exc))
+    user: UserConfig | None = None
+    state: State | None = None
+    try:
+        user = load_config(paths.user_config, UserConfig)
+        report.checks.append(Check(name="user-config", ok=True, message="User config parses"))
+    except OffboxError as exc:
+        report.checks.append(_failure("user-config", exc))
+    try:
+        root = project_root
+        if root is None:
+            root = Path.cwd()
+            git_available = any(check.name == "git" and check.ok for check in report.checks)
+            if git_available:
+                detected = runner.run(["git", "rev-parse", "--show-toplevel"], check=False, cwd=root, timeout=5)
+                if detected.returncode == 0 and detected.stdout.strip():
+                    root = Path(detected.stdout.strip())
+        load_project(paths, root)
+        report.checks.append(Check(name="project-config", ok=True, message="Project config parses"))
+    except OffboxError as exc:
+        report.checks.append(_failure("project-config", exc))
+    try:
+        credentials: Credentials = load_credentials(paths.credentials)
+        del credentials
+        report.checks.append(Check(name="credentials", ok=True, message="Credentials configuration is valid"))
+    except OffboxError as exc:
+        report.checks.append(_failure("credentials", exc))
+    try:
+        state = StateStore(paths.state).read()
+        report.checks.append(Check(name="state", ok=True, message="State validates"))
+    except OffboxError as exc:
+        report.checks.append(_failure("state", exc))
+    key = default_ssh_key()
+    configured_key = False
+    if user is not None and state is not None:
+        selected = default_host(user, state.default_host)
+        auto = sorted(name for name, preset in user.hosts.items() if preset.auto)
+        if selected is None and auto:
+            report.checks.append(
+                Check(name="host", ok=True, message=f"Auto-managed hosts are created on first offbox up: {', '.join(auto)}")
+            )
+        elif selected is None:
+            report.checks.append(Check(name="host", ok=False, message=NO_DEFAULT_HOST, fix="Run offbox setup."))
+        else:
+            host = state.hosts.get(selected)
+            if host is None and selected in auto:
+                report.checks.append(Check(name="host", ok=True, message=f"Auto-managed host {selected} is created on first offbox up"))
+            elif host is None:
+                report.checks.append(
+                    _failure(
+                        "host",
+                        PreconditionError(f"Default host {selected} is not registered", "Create the host or choose a registered host."),
+                    )
+                )
+            else:
+                configured_key = host.ssh_key is not None or (selected in user.hosts and user.hosts[selected].ssh_key is not None)
+                key = host.ssh_key or (user.hosts[selected].ssh_key if selected in user.hosts else None) or key
+                try:
+                    result = runner.run(
+                        ["ssh", "-o", "BatchMode=yes", "-o", "ConnectTimeout=3", f"offbox-{selected}", "--", "true"], check=False, timeout=5
+                    )
+                    report.checks.append(
+                        Check(
+                            name="host",
+                            ok=result.returncode == 0,
+                            message=f"Default host {selected} " + ("is reachable" if result.returncode == 0 else "is unreachable"),
+                            fix=None if result.returncode == 0 else f"Check connectivity with offbox host ssh {selected}.",
+                        )
+                    )
+                except OffboxError as exc:
+                    report.checks.append(_failure("host", exc))
+    if state is not None:
+        last_run, failure = timer_status(paths)
+        warning = timer_health(paths, utc_now(), last_run, failure)
+        if warning is None:
+            warning = unit_problem(paths)
+        if warning is not None:
+            report.checks.append(
+                Check(
+                    name="reaper",
+                    ok=False,
+                    message=warning,
+                    fix=f"Run offbox host reap --dry-run, check {paths.logs / 'reaper.log'} (macOS) or journalctl --user -u offbox-reap (Linux), "
+                    "then reinstall with offbox host reap --install-timer.",
+                )
+            )
+        for stored in read_warnings(paths):
+            report.checks.append(
+                Check(name="host-warning", ok=False, message=stored.message, fix=f"offbox host list --dismiss {stored.host} once checked.")
+            )
+    try:
+        if ssh_key is not None:
+            key, configured_key = ssh_key, True
+        report.checks.append(check_key(runner, key.expanduser(), configured=configured_key))
+    except OffboxError as exc:
+        report.checks.append(_failure("ssh-key", exc))
+    return report

offbox/drivers/base.py

@@ -0,0 +1,40 @@
+from pydantic import field_validator
+
+from offbox.config import Model
+from offbox.ssh import validate_address, validate_user
+
+
+class HostVariables(Model):
+    name: str
+    size: str
+    region: str
+    image: str
+    ssh_public_key: str
+    user_data: str
+    labels: dict[str, str]
+
+
+class ProviderOutputs(Model):
+    ip: str
+    ssh_user: str
+
+    @field_validator("ip")
+    @classmethod
+    def check_address(cls, value: str) -> str:
+        return validate_address(value)
+
+    @field_validator("ssh_user")
+    @classmethod
+    def check_user(cls, value: str) -> str:
+        return validate_user(value)
+
+
+class TofuOutput(Model):
+    value: str
+    type: str = "string"
+    sensitive: bool = False
+
+
+class TofuOutputs(Model):
+    ip: TofuOutput
+    ssh_user: TofuOutput

offbox/drivers/none.py

@@ -0,0 +1,114 @@
+import re
+from pathlib import PurePosixPath
+
+from pydantic import BaseModel, ConfigDict, Field, TypeAdapter, ValidationError
+
+from offbox import console
+from offbox.errors import ProviderError
+from offbox.runner import Result, Runner
+from offbox.ssh import ssh_argv
+from offbox.state import HostState
+
+
+class DockerResource(BaseModel):
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+    name: str = Field(alias="Name")
+    labels: dict[str, str] | None = Field(default=None, alias="Labels")
+
+
+class NetworkEndpoint(BaseModel):
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+    name: str = Field(alias="Name")
+
+
+class DockerNetwork(DockerResource):
+    containers: dict[str, NetworkEndpoint] | None = Field(default=None, alias="Containers")
+
+
+class DockerConfig(BaseModel):
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+    labels: dict[str, str] | None = Field(default=None, alias="Labels")
+
+
+class DockerContainer(BaseModel):
+    model_config = ConfigDict(extra="ignore", hide_input_in_errors=True)
+    id: str = Field(alias="Id")
+    name: str = Field(alias="Name")
+    config: DockerConfig = Field(alias="Config")
+
+
+def _verify_resource(name: str, labels: dict[str, str] | None, *, volume: bool = False) -> None:
+    values = labels or {}
+    env = values.get("offbox.env", "")
+    root = PurePosixPath(values.get("offbox.worktree", ""))
+    expected = f"offbox-{env}" + ("-docker" if volume else "")
+    if re.fullmatch(r"[a-z0-9][a-z0-9-]{0,36}", env) is None or not root.is_absolute() or name.lstrip("/") != expected:
+        raise ProviderError(
+            "Conflicting Docker ownership labels", "Inspect the host resources and their labels before retrying destruction."
+        )
+
+
+class NoneDriver:
+    def __init__(self, runner: Runner, host: HostState) -> None:
+        self.runner = runner
+        self.host = host
+
+    def _run(self, argv: list[str], *, check: bool = True) -> Result:
+        return self.runner.run(ssh_argv(self.host.name, argv), check=check, timeout=120)
+
+    def destroy(self) -> None:
+        containers = self._run(["docker", "ps", "-aq", "--no-trunc", "--filter", "label=offbox.env"]).stdout.split()
+        if any(re.fullmatch(r"[0-9a-f]{12,64}", value) is None for value in containers):
+            raise ProviderError("Docker returned invalid container identifiers", "Inspect the host Docker daemon before retrying.")
+        try:
+            if containers:
+                inspected = TypeAdapter(list[DockerContainer]).validate_json(
+                    self._run(["docker", "container", "inspect", *containers]).stdout
+                )
+                if {item.id for item in inspected} != set(containers) or len(inspected) != len(containers):
+                    raise ProviderError("Docker inventory changed", "Retry destruction after other Docker operations finish.")
+                for container in inspected:
+                    _verify_resource(container.name, container.config.labels)
+            volumes = self._run(["docker", "volume", "ls", "-q", "--filter", "label=offbox.env"]).stdout.split()
+            if any(re.fullmatch(r"offbox-[a-z0-9][a-z0-9-]{0,36}-docker", value) is None for value in volumes):
+                raise ProviderError("Docker returned unexpected volume names", "Inspect the host Docker volumes before retrying.")
+            if volumes:
+                inspected_volumes = TypeAdapter(list[DockerResource]).validate_json(
+                    self._run(["docker", "volume", "inspect", *volumes]).stdout
+                )
+                if {item.name for item in inspected_volumes} != set(volumes) or len(inspected_volumes) != len(volumes):
+                    raise ProviderError("Docker volume inventory changed", "Retry destruction after other Docker operations finish.")
+                for volume in inspected_volumes:
+                    _verify_resource(volume.name, volume.labels, volume=True)
+            network_result = self._run(["docker", "network", "inspect", "offbox"], check=False)
+            owned_network = False
+            if network_result.returncode == 0:
+                networks = TypeAdapter(list[DockerNetwork]).validate_json(network_result.stdout)
+                if len(networks) != 1 or networks[0].name != "offbox":
+                    raise ProviderError("Unexpected Docker network inventory", "Inspect the offbox network before retrying destruction.")
+                owned_network = (networks[0].labels or {}).get("offbox.managed") == "1"
+                if owned_network:
+                    attached = self._run(["docker", "ps", "-aq", "--no-trunc", "--filter", "network=offbox"]).stdout.split()
+                    if any(re.fullmatch(r"[0-9a-f]{64}", value) is None for value in attached):
+                        raise ProviderError("Invalid Docker network members", "Inspect network membership before retrying destruction.")
+                    if (set(attached) | set(networks[0].containers or {})) - set(containers):
+                        raise ProviderError(
+                            "Managed network has unrelated attached containers",
+                            f"Run offbox host ssh {self.host.name} -- docker ps -a --filter network=offbox; disconnect unrelated containers before retrying.",
+                        )
+                if not owned_network:
+                    console.info("Preserving the adopted or unlabelled Docker network offbox")
+            elif network_result.returncode != 1 or not any(
+                text in network_result.stderr.lower() for text in ("no such network", "not found")
+            ):
+                raise ProviderError("Cannot inspect the offbox network", "Check host connectivity and Docker before retrying destruction.")
+        except ValidationError as exc:
+            raise ProviderError("Invalid Docker ownership inventory", "Inspect the host resources before retrying destruction.") from exc
+        if containers:
+            self._run(["docker", "rm", "-f", *containers])
+        if volumes:
+            self._run(["docker", "volume", "rm", *volumes])
+        if owned_network:
+            self._run(["docker", "network", "rm", "offbox"])
+        self._run(["sudo", "-n", "rm", "-rf", "/srv/offbox", "/var/lib/offbox"])
+        self._run(["sudo", "-n", "rm", "-f", "/etc/sudoers.d/offbox", "/home/offbox/.ssh/authorized_keys"])

offbox/drivers/tofu.py

@@ -0,0 +1,59 @@
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from offbox import console
+from offbox.drivers.base import HostVariables, ProviderOutputs, TofuOutputs
+from offbox.errors import CommandFailed, ProviderError
+from offbox.logging import redact
+from offbox.runner import Result, Runner
+from offbox.ssh import write_private
+from offbox.timings import stage
+
+
+class TofuDriver:
+    def __init__(self, runner: Runner, workspace: Path, cache: Path, credentials: Mapping[str, str], executable: Path) -> None:
+        self.runner = runner
+        self.workspace = workspace
+        self.executable = str(executable)
+        plugins = cache / "tofu-plugins"
+        plugins.mkdir(parents=True, exist_ok=True, mode=0o700)
+        self.env = {
+            **credentials,
+            "TF_IN_AUTOMATION": "1",
+            "TF_INPUT": "0",
+            "TF_PLUGIN_CACHE_DIR": str(plugins),
+            "TF_CLI_ARGS": "-no-color",
+        }
+
+    def _run(self, args: Sequence[str]) -> Result:
+        result = self.runner.run([self.executable, *args], cwd=self.workspace, env=self.env, check=False, interruptible=True)
+        if result.returncode:
+            raise CommandFailed([self.executable, *args], result.returncode, redact(result.stderr, self.env))
+        return result
+
+    def create(self, variables: HostVariables) -> ProviderOutputs:
+        write_private(self.workspace / "offbox.auto.tfvars.json", variables.model_dump_json(indent=2))
+        console.step("Initialising provider")
+        with stage("Provider initialization"):
+            self._run(["init", "-input=false"])
+        console.step("Creating host")
+        with stage("VM provisioning"):
+            self._run(["apply", "-auto-approve", "-input=false"])
+        output = self._run(["output", "-json"])
+        try:
+            values = TofuOutputs.model_validate_json(output.stdout)
+            return ProviderOutputs(ip=values.ip.value, ssh_user=values.ssh_user.value)
+        except ValidationError as exc:
+            raise ProviderError(
+                "Provider returned invalid host outputs", "Check provider outputs; destroy the host before retrying."
+            ) from exc
+
+    def destroy(self) -> None:
+        console.step("Initialising provider")
+        with stage("Provider initialization"):
+            self._run(["init", "-input=false"])
+        console.step("Destroying host")
+        with stage("VM deletion"):
+            self._run(["destroy", "-auto-approve", "-input=false"])

offbox/errors.py

@@ -0,0 +1,45 @@
+from collections.abc import Sequence
+
+
+class OffboxError(Exception):
+    def __init__(self, message: str, fix: str | None = None, exit_code: int = 1) -> None:
+        super().__init__(message)
+        self.message = message
+        self.fix = fix
+        self.exit_code = exit_code
+
+
+class UsageError(OffboxError):
+    def __init__(self, message: str, fix: str | None = None) -> None:
+        super().__init__(message, fix, 2)
+
+
+class PreconditionError(OffboxError):
+    def __init__(self, message: str, fix: str | None = None) -> None:
+        super().__init__(message, fix, 3)
+
+
+class ConnectionError_(OffboxError):
+    def __init__(self, message: str, fix: str | None = None) -> None:
+        super().__init__(message, fix, 4)
+
+
+class CommandFailed(OffboxError):
+    def __init__(self, argv: Sequence[str], returncode: int, stderr_tail: str) -> None:
+        self.argv = list(argv)
+        self.returncode = returncode
+        self.stderr_tail = "\n".join(stderr_tail.splitlines()[-20:])
+        message = f"Command failed (exit {returncode}): {' '.join(argv)}"
+        if self.stderr_tail:
+            message += f"\n{self.stderr_tail}"
+        super().__init__(message, "Check the command output and try again.")
+
+
+class ProviderError(OffboxError):
+    pass
+
+
+class ProviderInterrupted(OffboxError):
+    def __init__(self, message: str, fix: str, *, killed: bool) -> None:
+        super().__init__(message, fix, 130)
+        self.killed = killed