offbox 0.1.0__py3-none-any.whl

offbox/_data/providers/gcp/main.tf

@@ -0,0 +1,67 @@
+locals {
+  region = replace(var.region, "/-[a-z]$/", "")
+}
+
+resource "google_compute_network" "this" {
+  name                    = var.name
+  description             = "Offbox host ${var.name}"
+  auto_create_subnetworks = false
+  routing_mode            = "REGIONAL"
+}
+
+resource "google_compute_subnetwork" "this" {
+  name          = var.name
+  region        = local.region
+  network       = google_compute_network.this.id
+  ip_cidr_range = "10.90.0.0/24"
+}
+
+resource "google_compute_firewall" "this" {
+  name          = "${var.name}-ssh"
+  description   = "Offbox SSH and ICMP for ${var.name}"
+  network       = google_compute_network.this.name
+  direction     = "INGRESS"
+  source_ranges = ["0.0.0.0/0"]
+  target_tags   = [var.name]
+
+  allow {
+    protocol = "tcp"
+    ports    = ["22"]
+  }
+
+  allow {
+    protocol = "icmp"
+  }
+}
+
+resource "google_compute_instance" "this" {
+  name                = var.name
+  machine_type        = var.size
+  zone                = var.region
+  labels              = var.labels
+  tags                = [var.name]
+  deletion_protection = false
+
+  boot_disk {
+    auto_delete = true
+
+    initialize_params {
+      image  = var.image
+      size   = 50
+      type   = "pd-balanced"
+      labels = var.labels
+    }
+  }
+
+  network_interface {
+    subnetwork = google_compute_subnetwork.this.id
+
+    access_config {}
+  }
+
+  metadata = {
+    user-data              = var.user_data
+    enable-oslogin         = "FALSE"
+    block-project-ssh-keys = "TRUE"
+  }
+}

offbox/_data/providers/gcp/outputs.tf

@@ -0,0 +1,7 @@
+output "ip" {
+  value = google_compute_instance.this.network_interface[0].access_config[0].nat_ip
+}
+
+output "ssh_user" {
+  value = "offbox"
+}

offbox/_data/providers/gcp/provider.toml

@@ -0,0 +1,9 @@
+name = "gcp"
+description = "Google Compute Engine Ubuntu host"
+driver = "tofu"
+credentials_env = ["GOOGLE_PROJECT"]
+
+[defaults]
+size = "e2-standard-4"
+region = "us-east4-c"
+image = "ubuntu-os-cloud/ubuntu-2404-lts-amd64"

offbox/_data/providers/gcp/variables.tf

@@ -0,0 +1,33 @@
+variable "name" {
+  type = string
+}
+
+variable "size" {
+  type = string
+}
+
+variable "region" {
+  type = string
+
+  validation {
+    condition     = can(regex("^[a-z]+-[a-z]+[0-9]+-[a-z]$", var.region))
+    error_message = "The GCP region setting must be a zone, for example us-east4-c."
+  }
+}
+
+variable "image" {
+  type = string
+}
+
+variable "ssh_public_key" {
+  type = string
+}
+
+variable "user_data" {
+  type      = string
+  sensitive = true
+}
+
+variable "labels" {
+  type = map(string)
+}

offbox/_data/providers/gcp/versions.tf

@@ -0,0 +1,12 @@
+terraform {
+  required_version = ">= 1.6"
+
+  required_providers {
+    google = {
+      source  = "hashicorp/google"
+      version = ">= 8.7, < 8.8"
+    }
+  }
+}
+
+provider "google" {}

offbox/_data/providers/hetzner/.terraform.lock.hcl

@@ -0,0 +1,51 @@
+# Provider checksums for Terraform (registry.terraform.io) and OpenTofu (registry.opentofu.org).
+# Each tool verifies its own registry entry; init drops the other entry from the host workspace copy.
+# Regenerate both with "providers lock" for linux_amd64, linux_arm64, darwin_amd64 and darwin_arm64.
+
+provider "registry.terraform.io/hetznercloud/hcloud" {
+  version     = "1.68.0"
+  constraints = ">= 1.68.0, < 1.69.0"
+  hashes = [
+    "h1:2MU8gDe67KjqALpvzzRfWONH2c/8djL+yxTnym9/FjY=",
+    "h1:BrgHGuh9WEMd8CQefgdSqhcePf4CZPdovwlHNdo3h70=",
+    "h1:KOFp1JbzZ6Xj2K80QL7HGJM6oG+oEo7tx3lIx3d5POM=",
+    "h1:oxpWvl0qfZplr759glEx537EqkkAgtagBtNsI8V13H8=",
+    "zh:0c3c2eb5bad6e2853da46dd83ed9c93c547b79f2abe977d492da9cf9d7236a62",
+    "zh:0ccae6bb2daee7c30b55672645b31c50920839a8aadac502d187f105352c1b37",
+    "zh:11559d821030e5f4657b81153419f3c5e4f6389e8cc6f8086db2ebeb7aade6bc",
+    "zh:164012cca257951da2870e9a0a0eb0be2ebde26fd27e30081c8d7e8729467a6e",
+    "zh:1fc7fea548dc8a0211ee832b0f1be489301f431cdfb153effd2fda7f63c02073",
+    "zh:73855025066ec55230559296b5c92d441b1b6dc2ce27a1102ab1e17f60cdcf0e",
+    "zh:78bfcca5d613f3285c2e326e92865d08e24d0574e29201ce9c1df612aa912a10",
+    "zh:84d6972ef2d6e03dc416ab34c8e266e0958ff390c7ad87761180706658b31614",
+    "zh:a04f8e12811e000657151cd6eed5eb80ae1042b8123bfea28343147ceda40f96",
+    "zh:b825f6500592d30004b6de8547ca1fa7841e16da0571cee8a67782cb84ec65cd",
+    "zh:d6bc5f6f27453248889e5df967111a187405f1434175a90221853226d47484af",
+    "zh:e052ad7a40cf1f63588c2b435ce7a9baca5ef0e1f9dcb321a06756eb3d38751a",
+    "zh:ea1497399246a51f16e3ff4a13dfba4c95a49997c2da7850703a086e211b7435",
+  ]
+}
+
+provider "registry.opentofu.org/hetznercloud/hcloud" {
+  version     = "1.68.0"
+  constraints = ">= 1.68.0, < 1.69.0"
+  hashes = [
+    "h1:2MU8gDe67KjqALpvzzRfWONH2c/8djL+yxTnym9/FjY=",
+    "h1:BrgHGuh9WEMd8CQefgdSqhcePf4CZPdovwlHNdo3h70=",
+    "h1:KOFp1JbzZ6Xj2K80QL7HGJM6oG+oEo7tx3lIx3d5POM=",
+    "h1:oxpWvl0qfZplr759glEx537EqkkAgtagBtNsI8V13H8=",
+    "zh:0c3c2eb5bad6e2853da46dd83ed9c93c547b79f2abe977d492da9cf9d7236a62",
+    "zh:0ccae6bb2daee7c30b55672645b31c50920839a8aadac502d187f105352c1b37",
+    "zh:11559d821030e5f4657b81153419f3c5e4f6389e8cc6f8086db2ebeb7aade6bc",
+    "zh:164012cca257951da2870e9a0a0eb0be2ebde26fd27e30081c8d7e8729467a6e",
+    "zh:1fc7fea548dc8a0211ee832b0f1be489301f431cdfb153effd2fda7f63c02073",
+    "zh:73855025066ec55230559296b5c92d441b1b6dc2ce27a1102ab1e17f60cdcf0e",
+    "zh:78bfcca5d613f3285c2e326e92865d08e24d0574e29201ce9c1df612aa912a10",
+    "zh:84d6972ef2d6e03dc416ab34c8e266e0958ff390c7ad87761180706658b31614",
+    "zh:a04f8e12811e000657151cd6eed5eb80ae1042b8123bfea28343147ceda40f96",
+    "zh:b825f6500592d30004b6de8547ca1fa7841e16da0571cee8a67782cb84ec65cd",
+    "zh:d6bc5f6f27453248889e5df967111a187405f1434175a90221853226d47484af",
+    "zh:e052ad7a40cf1f63588c2b435ce7a9baca5ef0e1f9dcb321a06756eb3d38751a",
+    "zh:ea1497399246a51f16e3ff4a13dfba4c95a49997c2da7850703a086e211b7435",
+  ]
+}

offbox/_data/providers/hetzner/main.tf

@@ -0,0 +1,32 @@
+resource "hcloud_firewall" "this" {
+  name   = var.name
+  labels = var.labels
+
+  rule {
+    direction  = "in"
+    protocol   = "tcp"
+    port       = "22"
+    source_ips = ["0.0.0.0/0", "::/0"]
+  }
+
+  rule {
+    direction  = "in"
+    protocol   = "icmp"
+    source_ips = ["0.0.0.0/0", "::/0"]
+  }
+}
+
+resource "hcloud_server" "this" {
+  name         = var.name
+  image        = var.image
+  server_type  = var.size
+  location     = var.region
+  user_data    = var.user_data
+  labels       = var.labels
+  firewall_ids = [hcloud_firewall.this.id]
+
+  public_net {
+    ipv4_enabled = true
+    ipv6_enabled = true
+  }
+}

offbox/_data/providers/hetzner/outputs.tf

@@ -0,0 +1,7 @@
+output "ip" {
+  value = hcloud_server.this.ipv4_address
+}
+
+output "ssh_user" {
+  value = "offbox"
+}

offbox/_data/providers/hetzner/provider.toml

@@ -0,0 +1,9 @@
+name = "hetzner"
+description = "Hetzner Cloud Ubuntu host"
+driver = "tofu"
+credentials_env = ["HCLOUD_TOKEN"]
+
+[defaults]
+size = "ccx33"
+region = "fsn1"
+image = "ubuntu-24.04"

offbox/_data/providers/hetzner/variables.tf

@@ -0,0 +1,28 @@
+variable "name" {
+  type = string
+}
+
+variable "size" {
+  type = string
+}
+
+variable "region" {
+  type = string
+}
+
+variable "image" {
+  type = string
+}
+
+variable "ssh_public_key" {
+  type = string
+}
+
+variable "user_data" {
+  type      = string
+  sensitive = true
+}
+
+variable "labels" {
+  type = map(string)
+}

offbox/_data/providers/hetzner/versions.tf

@@ -0,0 +1,12 @@
+terraform {
+  required_version = ">= 1.6"
+
+  required_providers {
+    hcloud = {
+      source  = "hetznercloud/hcloud"
+      version = ">= 1.68, < 1.69"
+    }
+  }
+}
+
+provider "hcloud" {}

offbox/_data/providers/ssh/provider.toml

@@ -0,0 +1,4 @@
+name = "ssh"
+description = "An existing Ubuntu host reached over SSH"
+driver = "none"
+credentials_env = []

offbox/cli/__init__.py

@@ -0,0 +1,117 @@
+import logging
+from typing import Annotated
+
+import typer
+from typer._click import ClickException, Context
+from typer.core import TyperGroup
+from typer.exceptions import Abort, Exit
+
+from offbox import __version__, console
+from offbox.cli.config import register as register_config_command
+from offbox.cli.env import register as register_env_commands
+from offbox.cli.exec import register as register_exec_command
+from offbox.cli.host import app as host_app
+from offbox.cli.misc import register as register_misc_commands
+from offbox.cli.ports import register as register_ports_command
+from offbox.doctor import diagnose
+from offbox.errors import OffboxError
+from offbox.logging import configure, redact, register_exec_secrets
+from offbox.paths import Paths
+from offbox.runner import SubprocessRunner
+from offbox.timings import collect
+
+logger = logging.getLogger(__name__)
+
+
+class ErrorGroup(TyperGroup):
+    def make_context(self, info_name: str | None, args: list[str], parent: Context | None = None, **extra: object) -> Context:
+        paths = Paths.discover()
+        log_path = paths.log_file()
+        try:
+            register_exec_secrets(args)
+            paths.secure_roots()
+            configure(paths, [info_name or "offbox", *args])
+            return super().make_context(info_name, args, parent, **extra)
+        except ClickException as exc:
+            console.error(exc.format_message(), "Run offbox --help for valid arguments.")
+            raise Exit(exc.exit_code) from exc
+        except OSError as exc:
+            console.error(f"Cannot initialize log file {log_path}", "Check XDG_STATE_HOME permissions and available disk space.")
+            raise Exit(1) from exc
+
+    def invoke(self, ctx: Context) -> object:
+        with collect(ctx.params.get("timings") is True):
+            return self._invoke_with_errors(ctx)
+
+    def _invoke_with_errors(self, ctx: Context) -> object:
+        log_path = Paths.discover().log_file()
+        try:
+            return super().invoke(ctx)
+        except OffboxError as exc:
+            logger.exception("offbox failure")
+            console.error(redact(exc.message), redact(exc.fix) if exc.fix else "Check the log and retry.")
+            raise Exit(exc.exit_code) from exc
+        except ClickException as exc:
+            console.error(exc.format_message(), "Run offbox --help for valid arguments.")
+            raise Exit(exc.exit_code) from exc
+        except (Exit, Abort):
+            raise
+        except KeyboardInterrupt as exc:
+            logger.warning("offbox interrupted", exc_info=True)
+            console.warn("Interrupted")
+            raise Exit(130) from exc
+        except Exception as exc:
+            logger.exception("unexpected failure")
+            console.error(f"unexpected error, see {log_path}", "Check the log and report this error.")
+            raise Exit(1) from exc
+
+
+app = typer.Typer(no_args_is_help=True, add_completion=False, cls=ErrorGroup)
+app.add_typer(host_app, name="host")
+register_env_commands(app)
+register_exec_command(app)
+register_ports_command(app)
+register_misc_commands(app)
+register_config_command(app)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        console.version(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: Annotated[
+        bool, typer.Option("--version", callback=_version_callback, is_eager=True, help="Show the version and exit.")
+    ] = False,
+    verbose: Annotated[bool, typer.Option("--verbose", "-v", help="Echo commands with secrets redacted.")] = False,
+    timings: Annotated[bool, typer.Option("--timings", help="Show stage durations on stderr; excludes CLI startup.")] = False,
+) -> None:
+    ctx.obj = SubprocessRunner(verbose=verbose)
+
+
+@app.command()
+def version() -> None:
+    """Show the version and exit."""
+    console.version(__version__)
+
+
+@app.command()
+def doctor(ctx: typer.Context, json: Annotated[bool, typer.Option("--json", help="Emit a typed JSON report.")] = False) -> None:
+    """Check local tools, configuration and default host connectivity."""
+    runner = ctx.obj
+    if not isinstance(runner, SubprocessRunner):
+        raise OffboxError("Runner is unavailable", "Restart offbox.")
+    report = diagnose(Paths.discover(), runner)
+    if json:
+        console.json_out(report)
+    else:
+        for check in report.checks:
+            if check.ok:
+                console.success(check.message)
+            else:
+                console.error(check.message, check.fix)
+    raise typer.Exit(report.exit_code)

offbox/cli/config.py

@@ -0,0 +1,39 @@
+import json as jsonlib
+from typing import Annotated
+
+import typer
+
+from offbox import console
+from offbox.errors import OffboxError
+from offbox.naming import find_worktree
+from offbox.paths import Paths
+from offbox.project import report
+from offbox.runner import SubprocessRunner
+
+
+def config(ctx: typer.Context, json: Annotated[bool, typer.Option("--json", help="Emit a typed JSON report.")] = False) -> None:
+    """Show this worktree's effective settings, where each comes from and its OFFBOX_* variable."""
+    runner: object = ctx.find_root().obj
+    if not isinstance(runner, SubprocessRunner):
+        raise OffboxError("Runner is unavailable", "Restart offbox.")
+    paths = Paths.discover()
+    result = report(paths, find_worktree(runner).root)
+    if json:
+        console.json_out(result)
+        return
+    files = result.files
+    console.output("Sources, later wins: default < user < project < local < env")
+    for name, path, suffix in (("user", files.user, " [project]"), ("project", files.project, ""), ("local", files.local, "")):
+        console.output(f"  {name:<8} {path}{suffix}{'' if path.is_file() else ' (not present)'}")
+    console.output("")
+    rows = [
+        (setting.key, "unset" if setting.value is None else jsonlib.dumps(setting.value), setting.source, setting.env)
+        for setting in result.settings
+    ]
+    widths = [max(len(row[column]) for row in rows) for column in range(3)]
+    for key, value, source, env in rows:
+        console.output(f"{key:<{widths[0]}}  {value:<{widths[1]}}  {source:<{widths[2]}}  {env}")
+
+
+def register(app: typer.Typer) -> None:
+    app.command()(config)

offbox/cli/env.py

@@ -0,0 +1,109 @@
+import sys
+from typing import Annotated
+
+import typer
+
+from offbox import console
+from offbox.errors import OffboxError, PreconditionError
+from offbox.paths import Paths
+from offbox.runner import SubprocessRunner
+from offbox.runtime import Runtime
+
+
+def _runtime(ctx: typer.Context) -> Runtime:
+    value: object = ctx.find_root().obj
+    if not isinstance(value, SubprocessRunner):
+        raise OffboxError("Runner is unavailable", "Restart offbox.")
+    return Runtime(Paths.discover(), value)
+
+
+def _confirm(message: str, yes: bool, fix: str) -> None:
+    if yes:
+        return
+    if not sys.stdin.isatty():
+        raise PreconditionError("This operation requires --yes without a TTY", fix)
+    if not typer.confirm(message):
+        raise PreconditionError("Operation cancelled", "Run the command again when ready.")
+
+
+def up(
+    ctx: typer.Context,
+    host: Annotated[str | None, typer.Option("--host", help="Host for a new environment. Default: the default host.")] = None,
+    fresh: Annotated[
+        bool, typer.Option("--fresh", help="Recreate the container and delete its inner Docker data; source files are kept.")
+    ] = False,
+    no_stack: Annotated[bool, typer.Option("--no-stack", help="Skip starting the project's Compose stack.")] = False,
+    yes: Annotated[bool, typer.Option("--yes", help="Confirm --fresh without a prompt.")] = False,
+) -> None:
+    """Create or start this worktree's isolated environment."""
+    if fresh:
+        _confirm(
+            "Recreate this environment and delete its inner Docker data (images, volumes, containers)?",
+            yes,
+            "Run offbox up --fresh --yes.",
+        )
+    _runtime(ctx).up(host_name=host, fresh=fresh, no_stack=no_stack)
+
+
+def stop(ctx: typer.Context) -> None:
+    """Stop this environment while retaining its data."""
+    _runtime(ctx).stop()
+
+
+def rm(ctx: typer.Context, yes: Annotated[bool, typer.Option("--yes", help="Confirm without a prompt.")] = False) -> None:
+    """Remove this worktree's remote environment and Docker data."""
+    _confirm("Remove this worktree's remote environment and all its Docker data?", yes, "Run offbox rm --yes to confirm removal.")
+    _runtime(ctx).remove()
+
+
+def list_envs(ctx: typer.Context, json: Annotated[bool, typer.Option("--json", help="Emit a typed JSON report.")] = False) -> None:
+    """List environments and their live container status."""
+    report = _runtime(ctx).report()
+    if json:
+        console.json_out(report)
+    elif not report.envs:
+        console.info("No environments registered")
+    else:
+        for env in report.envs:
+            used = f"  last used {env.last_used.astimezone().strftime('%Y-%m-%d %H:%M')}" if env.last_used else ""
+            console.info(f"{env.name}  {env.host}  {env.status}  {env.worktree}{used}")
+            if env.fix:
+                console.warn(f"Fix: {env.fix}")
+
+
+def shell(ctx: typer.Context) -> None:
+    """Open an interactive shell inside this environment."""
+    if not sys.stdin.isatty() or not sys.stdout.isatty():
+        raise PreconditionError("An environment shell requires a TTY", "Run offbox shell in an interactive terminal.")
+    raise typer.Exit(_runtime(ctx).shell())
+
+
+def gc(
+    ctx: typer.Context,
+    dry_run: Annotated[bool, typer.Option("--dry-run", help="Show the plan without changing anything.")] = False,
+    yes: Annotated[bool, typer.Option("--yes", help="Apply the plan without a prompt.")] = False,
+) -> None:
+    """Remove stale or orphan environments and prune unused inner Docker data."""
+    runtime = _runtime(ctx)
+    plan = runtime.gc_plan()
+    for target in plan.targets:
+        console.info(f"Remove {target.host}/{target.worktree.name}: {target.reason}")
+    for target in plan.running:
+        console.info(f"Prune unused Docker data in {target.host}/{target.worktree.name}")
+    if dry_run:
+        console.info("Dry run; no resources changed")
+        return
+    if not plan.targets and not plan.running:
+        console.info("Nothing to clean up")
+        return
+    _confirm("Apply this garbage collection plan?", yes, "Run offbox gc --dry-run to review, then offbox gc --yes.")
+    runtime.collect(plan)
+
+
+def register(app: typer.Typer) -> None:
+    app.command()(up)
+    app.command()(stop)
+    app.command()(rm)
+    app.command("list")(list_envs)
+    app.command()(shell)
+    app.command()(gc)

offbox/cli/exec.py

@@ -0,0 +1,50 @@
+from typing import Annotated
+
+import typer
+from pydantic import TypeAdapter
+from typer._click import Context
+from typer.core import TyperCommand
+
+from offbox.errors import OffboxError, UsageError
+from offbox.execute import ExecOptions, Executor, parse_env
+from offbox.paths import Paths
+from offbox.runner import SubprocessRunner
+
+
+class ExecCommand(TyperCommand):
+    def parse_args(self, ctx: Context, args: list[str]) -> list[str]:
+        if "--" in args:
+            index = args.index("--")
+            ctx.meta["offbox_exec_command"] = tuple(args[index + 1 :])
+            args = args[:index]
+        return super().parse_args(ctx, args)
+
+    def collect_usage_pieces(self, ctx: Context) -> list[str]:
+        return [*super().collect_usage_pieces(ctx), "-- COMMAND [ARGS]..."]
+
+
+def execute(
+    ctx: typer.Context,
+    no_sync: Annotated[bool, typer.Option("--no-sync", help="Skip the source sync flush before running.")] = False,
+    tty: Annotated[bool, typer.Option("--tty", help="Allocate a remote TTY. Default: when stdin and stdout are terminals.")] = False,
+    no_tty: Annotated[bool, typer.Option("--no-tty", help="Never allocate a remote TTY.")] = False,
+    stdin: Annotated[bool, typer.Option("--stdin", help="Forward local stdin to a non-TTY command.")] = False,
+    env: Annotated[list[str] | None, typer.Option("--env", help="Set NAME=value in the command environment; repeatable.")] = None,
+) -> None:
+    """Run a command after -- inside this worktree's environment."""
+    if tty and no_tty:
+        raise UsageError("--tty and --no-tty are mutually exclusive", "Choose one TTY mode.")
+    command = TypeAdapter(list[str]).validate_python(ctx.meta.get("offbox_exec_command", ()))
+    if not command:
+        raise UsageError("A command is required after --", "Run offbox exec -- COMMAND [ARGS...].")
+    runner: object = ctx.find_root().obj
+    if not isinstance(runner, SubprocessRunner):
+        raise OffboxError("Runner is unavailable", "Restart offbox.")
+    options = ExecOptions(
+        command=command, tty=True if tty else False if no_tty else None, no_sync=no_sync, stdin=stdin, overrides=parse_env(env or [])
+    )
+    raise typer.Exit(Executor(Paths.discover(), runner).execute(options))
+
+
+def register(app: typer.Typer) -> None:
+    app.command("exec", cls=ExecCommand)(execute)