borescope 0.1.0.dev0__py3-none-any.whl

borescope/__init__.py

@@ -0,0 +1,10 @@
+"""borescope - a natural shell for debugging Juju Kubernetes workload containers."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+try:
+    __version__ = version("borescope")
+except PackageNotFoundError:  # pragma: no cover - running from an uninstalled tree
+    __version__ = "0.0.0+unknown"
+
+__all__ = ["__version__"]

borescope/__main__.py

@@ -0,0 +1,10 @@
+"""``python -m borescope`` entry point."""
+
+from __future__ import annotations
+
+import sys
+
+from .cli import main
+
+if __name__ == "__main__":
+    sys.exit(main())

borescope/cli.py

@@ -0,0 +1,144 @@
+"""Command-line entry point for borescope."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="borescope",
+        description=(
+            "A natural shell for debugging Juju Kubernetes workload containers."
+        ),
+    )
+    parser.add_argument("unit", nargs="?", help="unit reference, e.g. 'myapp/0'")
+    parser.add_argument(
+        "--container", help="workload container name (default: first declared)"
+    )
+    parser.add_argument("-m", "--model", help="Juju model (default: current)")
+    parser.add_argument(
+        "-c",
+        "--command",
+        help="run a single command and exit (no REPL)",
+    )
+    parser.add_argument(
+        "--snapshot",
+        action="store_true",
+        help="dump container state as JSON and exit",
+    )
+    parser.add_argument(
+        "--socket",
+        help="talk directly to a Pebble unix socket (skip juju)",
+    )
+    parser.add_argument(
+        "--here",
+        action="store_true",
+        help=(
+            "run inside the charm container: auto-detect a workload's mounted "
+            "Pebble socket (use --container to pick when there are several)"
+        ),
+    )
+    parser.add_argument(
+        "--juju", default="juju", help="juju binary to invoke (default: juju)"
+    )
+    parser.add_argument(
+        "--via",
+        choices=("ssh", "exec"),
+        default="ssh",
+        help=(
+            "Juju relay for Mode B: 'ssh' (default, streaming) or 'exec' "
+            "(request/response — for sites where ssh is disabled)"
+        ),
+    )
+    parser.add_argument(
+        "--version", action="version", version=f"borescope {__version__}"
+    )
+    return parser
+
+
+def _build_target(args: argparse.Namespace):
+    from .discovery import Target, resolve_local_target, resolve_target
+
+    if args.here:
+        return resolve_local_target(container=args.container)
+    if args.socket:
+        unit = args.unit or "local"
+        app = unit.split("/")[0]
+        return Target(
+            unit=unit,
+            app=app,
+            container=args.container,
+            model=args.model,
+            juju_binary=args.juju,
+            socket_path=args.socket,
+        )
+    return resolve_target(
+        args.unit,
+        container=args.container,
+        model=args.model,
+        juju_binary=args.juju,
+        via=args.via,
+    )
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    if not args.unit and not args.socket and not args.here:
+        print(
+            "borescope: a unit reference is required (e.g. 'borescope myapp/0'), "
+            "or use --here when running inside a charm container.",
+            file=sys.stderr,
+        )
+        return 2
+
+    # Heavy imports happen only past argument parsing, keeping --help/--version fast.
+    from .errors import BorescopeError
+    from .shell import ShellContext
+    from .transport import open_transport
+
+    try:
+        target = _build_target(args)
+        transport = open_transport(
+            unit=target.unit,
+            container=target.container,
+            model=target.model,
+            juju_binary=target.juju_binary,
+            socket_path=target.socket_path,
+            via=target.via,
+        )
+        if args.snapshot:
+            from .snapshot import snapshot_json
+
+            print(snapshot_json(transport, target))
+            return 0
+
+        from .discovery import sanity_check
+
+        sanity_check(transport, target)
+    except BorescopeError as exc:
+        print(f"borescope: {exc}", file=sys.stderr)
+        return 1
+
+    from .shell import Shell
+
+    shell = Shell(ShellContext(transport=transport, target=target))
+
+    if args.command is not None:
+        return shell.execute_and_emit(args.command)
+
+    if not sys.stdin.isatty():
+        code = 0
+        for line in sys.stdin:
+            if line.strip():
+                code = shell.execute_and_emit(line.rstrip("\n"))
+        return code
+
+    return shell.loop()
+
+
+if __name__ == "__main__":  # pragma: no cover
+    sys.exit(main())

borescope/discovery.py

@@ -0,0 +1,256 @@
+"""Discovery layer (B) — "find the right Pebble".
+
+Turns a unit reference (``myapp/0``) plus optional ``--container`` / ``--model``
+into a :class:`Target` describing exactly which workload container's Pebble to talk
+to. Everything here uses only the user's Juju model access (``juju status``,
+``juju ssh`` to read the charm's ``metadata.yaml``) — never ``kubectl`` or
+cluster-admin — so borescope inherits Juju's authority for free.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass
+from typing import TYPE_CHECKING
+
+import yaml
+
+from . import juju
+from .errors import DiscoveryError, JujuError
+
+if TYPE_CHECKING:
+    from .transport import Transport
+
+_UNIT_RE = re.compile(r"^(?P<app>[a-z0-9][a-z0-9-]*)/(?P<num>\d+)$")
+
+# Charm agent metadata lives at a deterministic path inside the *charm* container
+# (which, unlike the workload rock, has a normal filesystem and `cat`).
+_META_FILES = ("metadata.yaml", "charmcraft.yaml")
+
+# Inside a Juju k8s charm container, each declared workload's Pebble socket is
+# mounted here, one subdirectory per container. This is what makes Mode A
+# (``--here``) possible without any Juju round-trip.
+_LOCAL_SOCKET_DIR = "/charm/containers"
+
+
+@dataclass(frozen=True)
+class Target:
+    """A fully-resolved Pebble target."""
+
+    unit: str
+    app: str
+    container: str | None
+    model: str | None
+    controller: str | None = None
+    juju_binary: str = "juju"
+    socket_path: str | None = None
+    # CLI-relay variant for Mode B: "ssh" (default) or "exec". Ignored when
+    # socket_path is set (Mode A uses the socket directly).
+    via: str = "ssh"
+
+    @property
+    def history_key(self) -> str:
+        """Stable per-controller/model/unit key for history files."""
+        parts = [self.controller or "_", self.model or "_", self.unit]
+        return "/".join(parts).replace("/", "_")
+
+
+def parse_unit_ref(ref: str) -> tuple[str, str]:
+    """Split ``app/n`` into ``(app, n)``; raise :class:`DiscoveryError` if malformed."""
+    match = _UNIT_RE.match(ref.strip())
+    if not match:
+        raise DiscoveryError(
+            f"'{ref}' is not a valid unit reference (expected e.g. 'myapp/0')."
+        )
+    return match.group("app"), match.group("num")
+
+
+def _agent_dir(app: str, num: str) -> str:
+    return f"unit-{app}-{num}"
+
+
+def discover_containers(
+    unit: str, app: str, num: str, *, model: str | None, juju_binary: str
+) -> list[str]:
+    """Return the workload container names declared in the charm's metadata.
+
+    Reads the charm's ``metadata.yaml`` (falling back to ``charmcraft.yaml``) from
+    the charm container — ``juju status`` does not list workload container names.
+    """
+    base = f"/var/lib/juju/agents/{_agent_dir(app, num)}/charm"
+    last_error: JujuError | None = None
+    for name in _META_FILES:
+        try:
+            raw = juju.run_juju(
+                # No ``--`` separator: juju's k8s ssh leaks it into the remote sh.
+                ["ssh", unit, "cat", f"{base}/{name}"],
+                model=model,
+                juju_binary=juju_binary,
+            )
+        except JujuError as exc:
+            last_error = exc
+            continue
+        try:
+            meta = yaml.safe_load(raw) or {}
+        except yaml.YAMLError:
+            continue
+        containers = meta.get("containers")
+        if isinstance(containers, dict):
+            return [str(name) for name in containers]
+    if last_error is not None:
+        raise DiscoveryError(
+            f"could not read charm metadata for {unit}: {last_error}"
+        ) from last_error
+    return []
+
+
+def resolve_target(
+    unit_ref: str,
+    *,
+    container: str | None = None,
+    model: str | None = None,
+    juju_binary: str = "juju",
+    via: str = "ssh",
+) -> Target:
+    """Resolve *unit_ref* to a :class:`Target`, confirming it exists and is on k8s."""
+    app, num = parse_unit_ref(unit_ref)
+    controller, current_model = juju.current_controller_model(juju_binary)
+    effective_model = model or current_model
+
+    status = juju.status_json(model=model, juju_binary=juju_binary)
+
+    model_type = (status.get("model") or {}).get("type")
+    if model_type == "iaas":
+        raise DiscoveryError(
+            f"{unit_ref} is on a machine (IAAS) model. borescope only supports "
+            "Kubernetes charms, which run Pebble; machine charms already have a "
+            "real shell. See the project scope."
+        )
+
+    apps = status.get("applications") or {}
+    if app not in apps:
+        raise DiscoveryError(
+            f"application '{app}' not found in model "
+            f"'{effective_model or '<current>'}'."
+        )
+    units = apps[app].get("units") or {}
+    if unit_ref not in units:
+        available = ", ".join(sorted(units)) or "none"
+        raise DiscoveryError(
+            f"unit '{unit_ref}' not found. Units of '{app}': {available}."
+        )
+
+    chosen = container
+    if chosen is None:
+        containers = discover_containers(
+            unit_ref, app, num, model=model, juju_binary=juju_binary
+        )
+        if not containers:
+            raise DiscoveryError(
+                f"no workload containers declared by '{app}'. Is this a "
+                "Kubernetes (sidecar) charm?"
+            )
+        # Default to the first declared workload container (open question #5).
+        chosen = containers[0]
+
+    return Target(
+        unit=unit_ref,
+        app=app,
+        container=chosen,
+        model=effective_model,
+        controller=controller,
+        juju_binary=juju_binary,
+        via=via,
+    )
+
+
+def discover_local_sockets(base: str = _LOCAL_SOCKET_DIR) -> dict[str, str]:
+    """Map workload container name → mounted Pebble socket path.
+
+    As seen from *inside the charm container*, where Juju mounts every workload's
+    socket at ``/charm/containers/<name>/pebble.socket``. Returns an empty mapping
+    if *base* isn't present (i.e. we're not in a charm container).
+    """
+    sockets: dict[str, str] = {}
+    try:
+        names = os.listdir(base)
+    except OSError:
+        return sockets
+    for name in sorted(names):
+        path = f"{base}/{name}/pebble.socket"
+        if os.path.exists(path):
+            sockets[name] = path
+    return sockets
+
+
+def resolve_local_target(
+    *, container: str | None = None, base: str = _LOCAL_SOCKET_DIR
+) -> Target:
+    """Resolve a :class:`Target` for borescope running *inside the charm container*.
+
+    Talks directly to a workload's mounted Pebble socket (Mode A) — no Juju, no
+    unit reference. Picks the socket named by *container*, or the sole one if the
+    charm declares just a single workload.
+    """
+    sockets = discover_local_sockets(base)
+    if not sockets:
+        raise DiscoveryError(
+            f"no Pebble sockets found under {base}. '--here' only works from inside "
+            "a Juju Kubernetes charm container, which mounts each workload's socket "
+            "there. From your workstation, run 'borescope <unit>' instead."
+        )
+    if container is not None:
+        socket = sockets.get(container)
+        if socket is None:
+            available = ", ".join(sockets)
+            raise DiscoveryError(
+                f"no Pebble socket for container '{container}' under {base}. "
+                f"Available: {available}."
+            )
+        chosen = container
+    elif len(sockets) == 1:
+        chosen, socket = next(iter(sockets.items()))
+    else:
+        available = ", ".join(sockets)
+        raise DiscoveryError(
+            f"this charm has multiple workload containers ({available}); "
+            "choose one with --container."
+        )
+    return Target(
+        unit="local",
+        app=chosen,
+        container=chosen,
+        model=None,
+        socket_path=socket,
+    )
+
+
+def sanity_check(transport: Transport, target: Target) -> None:
+    """Confirm the container's Pebble answers, and is new enough, before prompting."""
+    try:
+        info = transport.get_system_info()
+    except Exception as exc:  # noqa: BLE001 - surface any backend failure uniformly
+        raise DiscoveryError(
+            f"could not reach Pebble in {target.unit} "
+            f"container '{target.container}': {exc}"
+        ) from exc
+
+    # borescope v1 relies on Pebble's `--format json` output (via shimmer). Older
+    # Pebbles (e.g. v1.26, still shipped by current stable charms) lack it. Probe
+    # one structured read so we fail fast with a clear message rather than letting
+    # every read command die with a cryptic "unknown flag `format'".
+    try:
+        transport.get_services()
+    except Exception as exc:  # noqa: BLE001
+        message = str(exc).lower()
+        if "unknown flag" in message and "format" in message:
+            version = getattr(info, "version", "unknown")
+            raise DiscoveryError(
+                f"the Pebble in {target.unit} container '{target.container}' "
+                f"(version {version}) is too old for borescope: it lacks the "
+                "`--format json` output borescope relies on. borescope v1 needs a "
+                "newer Pebble (support for older Pebble may come later)."
+            ) from exc
+        # Any other failure here isn't necessarily fatal; reachability is already
+        # proven, so let the session start and let individual commands report.

borescope/errors.py

@@ -0,0 +1,26 @@
+"""borescope's error hierarchy."""
+
+from __future__ import annotations
+
+
+class BorescopeError(Exception):
+    """Base class for all borescope errors."""
+
+
+class DiscoveryError(BorescopeError):
+    """Raised when a unit/model/container cannot be resolved or reached."""
+
+
+class TransportError(BorescopeError):
+    """Raised when the chosen transport cannot talk to a Pebble."""
+
+
+class JujuError(BorescopeError):
+    """Raised when an underlying ``juju`` invocation fails."""
+
+    def __init__(
+        self, message: str, *, returncode: int | None = None, stderr: str = ""
+    ):
+        super().__init__(message)
+        self.returncode = returncode
+        self.stderr = stderr

borescope/juju.py

@@ -0,0 +1,89 @@
+"""Thin wrappers around the ``juju`` CLI.
+
+borescope never links Juju's Go/Python API libraries; it shells out to the user's
+``juju`` client. That keeps borescope inside the user's existing Juju authority — if
+they can run ``juju ssh`` to a unit, borescope works; if they can't, it fails the
+same way — and needs no ``kubectl`` / cluster-admin access.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+from typing import Any
+
+from .errors import JujuError
+
+DEFAULT_TIMEOUT = 30.0
+
+
+def run_juju(
+    args: list[str],
+    *,
+    model: str | None = None,
+    juju_binary: str = "juju",
+    input: str | None = None,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> str:
+    """Run ``juju <args>`` and return stdout, raising :class:`JujuError` on failure.
+
+    *model*, when given, is inserted as ``-m <model>`` immediately after the
+    subcommand (``args[0]``), matching how ``juju`` expects the flag.
+    """
+    cmd = [juju_binary, args[0]]
+    if model:
+        cmd += ["-m", model]
+    cmd += args[1:]
+    try:
+        result = subprocess.run(
+            cmd,
+            input=input,
+            # Detach stdin unless we're sending input: `juju ssh` forwards our stdin
+            # to the remote and would otherwise drain borescope's own piped-batch
+            # command stream during discovery, leaving the REPL loop nothing to read.
+            stdin=subprocess.DEVNULL if input is None else None,
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            check=True,
+        )
+    except FileNotFoundError as exc:
+        raise JujuError(
+            f"'{juju_binary}' not found on PATH. Install Juju and try again."
+        ) from exc
+    except subprocess.TimeoutExpired as exc:
+        raise JujuError(f"'{' '.join(cmd)}' timed out after {timeout}s") from exc
+    except subprocess.CalledProcessError as exc:
+        stderr = (exc.stderr or "").strip()
+        raise JujuError(
+            f"'{' '.join(cmd)}' failed: {stderr or 'unknown error'}",
+            returncode=exc.returncode,
+            stderr=stderr,
+        ) from exc
+    return result.stdout
+
+
+def current_controller_model(
+    juju_binary: str = "juju",
+) -> tuple[str | None, str | None]:
+    """Return ``(controller, model)`` from ``juju switch`` (either may be None)."""
+    try:
+        out = run_juju(["switch"], juju_binary=juju_binary).strip()
+    except JujuError:
+        return None, None
+    if not out:
+        return None, None
+    # `juju switch` prints "<controller>:<user>/<model>" (or "<controller>:<model>").
+    controller, _, model = out.partition(":")
+    return controller or None, (model or None)
+
+
+def status_json(
+    *, model: str | None = None, juju_binary: str = "juju"
+) -> dict[str, Any]:
+    """Return parsed ``juju status --format=json`` for *model*."""
+    out = run_juju(["status", "--format=json"], model=model, juju_binary=juju_binary)
+    try:
+        return json.loads(out)
+    except json.JSONDecodeError as exc:
+        raise JujuError("could not parse `juju status --format=json` output") from exc

borescope/shell/__init__.py

@@ -0,0 +1,8 @@
+"""Shell layer (C) — "drive the Pebble"."""
+
+from __future__ import annotations
+
+from .context import ShellContext
+from .repl import Shell
+
+__all__ = ["Shell", "ShellContext"]

borescope/shell/commands/__init__.py

@@ -0,0 +1,13 @@
+"""Built-in commands and the registry that discovers them."""
+
+from __future__ import annotations
+
+from .base import Command, ExitShell, Result, build_registry
+
+
+def import_all() -> None:
+    """Import every command module so its ``Command`` subclasses register."""
+    from . import basic, execcmd, filesystem, pebble  # noqa: F401
+
+
+__all__ = ["Command", "ExitShell", "Result", "build_registry", "import_all"]

borescope/shell/commands/_args.py

@@ -0,0 +1,54 @@
+"""A tiny getopt-ish argument splitter shared by the built-in commands.
+
+Not a full argparse — these are debug-shell commands, so we want forgiving,
+familiar behaviour (``-la``, ``-n10``, ``-n 10``, ``--follow``) without per-command
+boilerplate.
+"""
+
+from __future__ import annotations
+
+
+def parse_args(
+    args: list[str], valued: tuple[str, ...] = ()
+) -> tuple[set[str], dict[str, str], list[str]]:
+    """Split *args* into ``(flags, values, positionals)``.
+
+    *valued* names flags that take a value (e.g. ``("n",)`` for ``-n N`` /
+    ``("name",)`` for ``--name X``). Everything after ``--`` is positional.
+    """
+    flags: set[str] = set()
+    values: dict[str, str] = {}
+    positionals: list[str] = []
+
+    i = 0
+    while i < len(args):
+        arg = args[i]
+        if arg == "--":
+            positionals.extend(args[i + 1 :])
+            break
+        if arg.startswith("--"):
+            name = arg[2:]
+            if name in valued:
+                i += 1
+                values[name] = args[i] if i < len(args) else ""
+            else:
+                flags.add(name)
+        elif len(arg) > 1 and arg[0] == "-" and not arg[1].isdigit():
+            body = arg[1:]
+            j = 0
+            while j < len(body):
+                ch = body[j]
+                if ch in valued:
+                    rest = body[j + 1 :]
+                    if rest:
+                        values[ch] = rest
+                    else:
+                        i += 1
+                        values[ch] = args[i] if i < len(args) else ""
+                    break
+                flags.add(ch)
+                j += 1
+        else:
+            positionals.append(arg)
+        i += 1
+    return flags, values, positionals