borescope 0.1.0.dev0__py3-none-any.whl

borescope/shell/repl.py

@@ -0,0 +1,133 @@
+"""The REPL: one process, one session, one command (or single pipe) at a time."""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from ..errors import BorescopeError
+from . import theme
+from .commands.base import ExitShell, Result, build_registry
+from .parser import ParseError, expand, parse_pipeline
+
+if TYPE_CHECKING:
+    from .context import ShellContext
+
+
+class Shell:
+    """Drives a Pebble through the command registry."""
+
+    def __init__(self, ctx: ShellContext):
+        self.ctx = ctx
+        self.registry = build_registry()
+        self._session = None
+
+    # -- execution ---------------------------------------------------------
+    def run_line(self, line: str) -> Result:
+        """Parse and run a single input line (may raise :class:`ExitShell`)."""
+        try:
+            stages = parse_pipeline(line)
+        except ParseError as exc:
+            return Result.fail(f"borescope: {exc}")
+        if not stages:
+            return Result()
+        return self._execute(stages)
+
+    def _execute(self, stages: list[list[str]]) -> Result:
+        if len(stages) == 1:
+            return self._run_stage(stages[0], None)
+
+        for stage in stages:
+            cmd = self.registry.get(stage[0])
+            if cmd is not None and cmd.streaming:
+                return Result.fail(f"borescope: '{stage[0]}' cannot be used in a pipe.")
+
+        left = self._run_stage(stages[0], None)
+        right = self._run_stage(stages[1], left.output)
+        return Result(
+            output=right.output, error=left.error + right.error, code=right.code
+        )
+
+    def _run_stage(self, tokens: list[str], stdin: str | None) -> Result:
+        tokens = [expand(tok, self.ctx.env) for tok in tokens]
+        name, *args = tokens
+        cmd = self.registry.get(name)
+        if cmd is None:
+            return Result.fail(
+                f"borescope: command not found: {name}\n"
+                f"  hint: 'exec {name} ...' runs it inside the container.",
+                code=127,
+            )
+        try:
+            return cmd.run(self.ctx, args, stdin)
+        except ExitShell:
+            raise
+        except BorescopeError as exc:
+            return Result.fail(f"{name}: {exc}")
+        except Exception as exc:  # noqa: BLE001 - surface backend errors as output
+            return Result.fail(f"{name}: {exc}")
+
+    def execute_and_emit(self, line: str) -> int:
+        """Run one line, print its output, and return the exit code (one-shot)."""
+        try:
+            result = self.run_line(line)
+        except ExitShell as exc:
+            return exc.code
+        self._emit(result)
+        return result.code
+
+    def _emit(self, result: Result) -> None:
+        if result.output:
+            sys.stdout.write(result.output)
+            if not result.output.endswith("\n"):
+                sys.stdout.write("\n")
+            sys.stdout.flush()
+        if result.error:
+            sys.stderr.write(result.error)
+            if not result.error.endswith("\n"):
+                sys.stderr.write("\n")
+            sys.stderr.flush()
+        self.ctx.last_exit = result.code
+
+    # -- interactive loop --------------------------------------------------
+    def loop(self) -> int:
+        session = self._ensure_session()
+        self._print_banner()
+        style = theme.style()
+        while True:
+            try:
+                line = session.prompt(theme.prompt_fragments(self.ctx), style=style)
+            except KeyboardInterrupt:
+                continue
+            except EOFError:
+                break
+            if not line.strip():
+                continue
+            try:
+                result = self.run_line(line)
+            except ExitShell as exc:
+                self.ctx.last_exit = exc.code
+                break
+            self._emit(result)
+        return self.ctx.last_exit
+
+    def _ensure_session(self):
+        if self._session is None:
+            from prompt_toolkit import PromptSession
+
+            from .completion import BorescopeCompleter
+            from .history import history_for
+
+            self._session = PromptSession(
+                history=history_for(self.ctx.target),
+                completer=BorescopeCompleter(self.registry.keys(), self.ctx),
+                complete_while_typing=False,
+            )
+        return self._session
+
+    def _print_banner(self) -> None:
+        target = self.ctx.target
+        where = target.unit + (f" ({target.container})" if target.container else "")
+        print(
+            f"borescope — connected to {where}. Type 'help' for commands, 'exit' to quit."
+        )

borescope/shell/theme.py

@@ -0,0 +1,35 @@
+"""A single small theme module: prompt shape and colours."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from prompt_toolkit.formatted_text import FormattedText
+from prompt_toolkit.styles import Style
+
+if TYPE_CHECKING:
+    from .context import ShellContext
+
+_STYLE = Style.from_dict(
+    {
+        "prompt.pebble": "ansicyan bold",
+        "prompt.path": "ansiblue",
+        "prompt.mark": "ansiyellow bold",
+    }
+)
+
+
+def style() -> Style:
+    return _STYLE
+
+
+def prompt_fragments(ctx: ShellContext) -> FormattedText:
+    """Render a bash-like prompt: ``pebble:<cwd>#``."""
+    return FormattedText(
+        [
+            ("class:prompt.pebble", "pebble"),
+            ("", ":"),
+            ("class:prompt.path", ctx.cwd),
+            ("class:prompt.mark", "# "),
+        ]
+    )

borescope/snapshot.py

@@ -0,0 +1,103 @@
+"""``borescope --snapshot`` — dump container state as JSON.
+
+Cheap to produce, useful for filing bugs and for feeding tools like
+``explain-my-model``. The shape is intended to be stable and consumable.
+"""
+
+from __future__ import annotations
+
+import json
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any
+
+import yaml
+
+from . import __version__
+
+if TYPE_CHECKING:
+    from .discovery import Target
+    from .transport import Transport
+
+
+def _value(obj: object) -> str:
+    return getattr(obj, "value", str(obj))
+
+
+def build_snapshot(
+    transport: Transport, target: Target, *, log_lines: int = 20
+) -> dict[str, Any]:
+    data: dict[str, Any] = {
+        "borescope_version": __version__,
+        "captured_at": datetime.now(UTC).isoformat(),
+        "unit": target.unit,
+        "container": target.container,
+        "model": target.model,
+        "controller": target.controller,
+    }
+
+    try:
+        data["system"] = {"version": transport.get_system_info().version}
+    except Exception as exc:  # noqa: BLE001
+        data["system_error"] = str(exc)
+
+    try:
+        data["services"] = [
+            {"name": s.name, "startup": _value(s.startup), "current": _value(s.current)}
+            for s in transport.get_services()
+        ]
+    except Exception as exc:  # noqa: BLE001
+        data["services_error"] = str(exc)
+
+    try:
+        plan = transport.get_plan()
+        data["plan"] = (
+            plan.to_dict()
+            if hasattr(plan, "to_dict")
+            else yaml.safe_load(plan.to_yaml())
+        )
+    except Exception as exc:  # noqa: BLE001
+        data["plan_error"] = str(exc)
+
+    try:
+        data["checks"] = [
+            {
+                "name": c.name,
+                "level": _value(c.level),
+                "status": _value(c.status),
+                "failures": c.failures,
+                "threshold": c.threshold,
+            }
+            for c in transport.get_checks()
+        ]
+    except Exception as exc:  # noqa: BLE001
+        data["checks_error"] = str(exc)
+
+    try:
+        data["notices"] = [
+            {
+                "id": n.id,
+                "type": _value(n.type),
+                "key": n.key,
+                "occurrences": n.occurrences,
+                "last_repeated": n.last_repeated.isoformat()
+                if n.last_repeated
+                else None,
+            }
+            for n in transport.get_notices()
+        ]
+    except Exception as exc:  # noqa: BLE001
+        data["notices_error"] = str(exc)
+
+    try:
+        from .transport.relay import run_pebble
+
+        result = run_pebble(target, ["logs", "-n", str(log_lines)])
+        data["recent_logs"] = (result.stdout or "").splitlines()
+    except Exception as exc:  # noqa: BLE001
+        data["logs_error"] = str(exc)
+
+    return data
+
+
+def snapshot_json(transport: Transport, target: Target, *, log_lines: int = 20) -> str:
+    return json.dumps(build_snapshot(transport, target, log_lines=log_lines), indent=2)

borescope/transport/__init__.py

@@ -0,0 +1,162 @@
+"""Transport layer (A) — "talk to a Pebble".
+
+A narrow interface the shell layer talks to, with two thin backends over an
+``ops.pebble.Client``-shaped object:
+
+- :func:`~borescope.transport.cli_transport.build_cli_transport` (v1 primary) — runs
+  the workload container's ``pebble`` via ``juju ssh``.
+- :func:`~borescope.transport.socket_transport.build_socket_transport` (secondary) —
+  the real ``ops.pebble.Client`` on a directly-reachable socket.
+
+The shell layer only ever sees :class:`Transport`, so the backend choice — and a
+future Go reimplementation of just this layer — stays contained.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from typing import TYPE_CHECKING, Any, Protocol
+
+if TYPE_CHECKING:
+    import datetime
+    from typing import BinaryIO, TextIO
+
+    import ops
+
+
+class Transport(Protocol):
+    """The subset of ``ops.pebble.Client`` borescope uses.
+
+    Both backends (``shimmer.PebbleCliClient`` and ``ops.pebble.Client``) satisfy
+    this structurally; it exists to document and contain the only surface that ever
+    touches Pebble.
+    """
+
+    # -- system / liveness -------------------------------------------------
+    def get_system_info(self) -> ops.pebble.SystemInfo: ...
+
+    # -- services ----------------------------------------------------------
+    def get_services(
+        self, names: Iterable[str] | None = None
+    ) -> list[ops.pebble.ServiceInfo]: ...
+    def start_services(
+        self, services: Iterable[str], timeout: float = 30.0, delay: float = 0.1
+    ) -> ops.pebble.ChangeID: ...
+    def stop_services(
+        self, services: Iterable[str], timeout: float = 30.0, delay: float = 0.1
+    ) -> ops.pebble.ChangeID: ...
+    def restart_services(
+        self, services: Iterable[str], timeout: float = 30.0, delay: float = 0.1
+    ) -> ops.pebble.ChangeID: ...
+    def replan_services(
+        self, timeout: float = 30.0, delay: float = 0.1
+    ) -> ops.pebble.ChangeID: ...
+    def send_signal(self, sig: int | str, services: Iterable[str]) -> None: ...
+
+    # -- plan / changes ----------------------------------------------------
+    def get_plan(self) -> ops.pebble.Plan: ...
+    def get_changes(
+        self,
+        select: ops.pebble.ChangeState = ...,
+        service: str | None = None,
+    ) -> list[ops.pebble.Change]: ...
+    def get_change(self, change_id: ops.pebble.ChangeID) -> ops.pebble.Change: ...
+
+    # -- checks ------------------------------------------------------------
+    def get_checks(
+        self,
+        level: ops.pebble.CheckLevel | None = None,
+        names: Iterable[str] | None = None,
+    ) -> list[ops.pebble.CheckInfo]: ...
+
+    # -- notices -----------------------------------------------------------
+    def get_notices(
+        self,
+        *,
+        users: Any = None,
+        user_id: int | None = None,
+        types: Iterable[Any] | None = None,
+        keys: Iterable[str] | None = None,
+    ) -> list[ops.pebble.Notice]: ...
+    def get_notice(self, id: str) -> ops.pebble.Notice: ...
+    def notify(
+        self,
+        type: ops.pebble.NoticeType,
+        key: str,
+        *,
+        data: dict[str, str] | None = None,
+        repeat_after: datetime.timedelta | None = None,
+    ) -> str: ...
+
+    # -- filesystem --------------------------------------------------------
+    def pull(
+        self, path: str, *, encoding: str | None = "utf-8"
+    ) -> BinaryIO | TextIO: ...
+    def push(
+        self,
+        path: str,
+        source: Any,
+        *,
+        encoding: str = "utf-8",
+        make_dirs: bool = False,
+        permissions: int | None = None,
+        user_id: int | None = None,
+        user: str | None = None,
+        group_id: int | None = None,
+        group: str | None = None,
+    ) -> None: ...
+    def list_files(
+        self, path: str, *, pattern: str | None = None, itself: bool = False
+    ) -> list[ops.pebble.FileInfo]: ...
+    def make_dir(
+        self,
+        path: str,
+        *,
+        make_parents: bool = False,
+        permissions: int | None = None,
+        user_id: int | None = None,
+        user: str | None = None,
+        group_id: int | None = None,
+        group: str | None = None,
+    ) -> None: ...
+    def remove_path(self, path: str, *, recursive: bool = False) -> None: ...
+
+    # -- exec --------------------------------------------------------------
+    def exec(
+        self, command: list[str], **kwargs: Any
+    ) -> ops.pebble.ExecProcess[Any]: ...
+
+
+def open_transport(
+    *,
+    unit: str,
+    container: str | None,
+    model: str | None = None,
+    juju_binary: str = "juju",
+    socket_path: str | None = None,
+    via: str = "ssh",
+) -> Transport:
+    """Open the appropriate transport.
+
+    If *socket_path* is given (a directly-reachable Pebble socket), use the fast
+    ``SocketTransport``; otherwise use the ``CliTransport`` relay (via ``juju ssh``
+    by default; ``via="exec"`` switches to ``juju exec`` for sites where ssh is
+    disabled).
+    """
+    if socket_path:
+        from .socket_transport import build_socket_transport
+
+        return build_socket_transport(socket_path)
+
+    from .cli_transport import build_cli_transport
+
+    return build_cli_transport(
+        unit=unit,
+        container=container,
+        model=model,
+        juju_binary=juju_binary,
+        via=via,
+    )
+
+
+__all__ = ["Transport", "open_transport"]

borescope/transport/cli_transport.py

@@ -0,0 +1,63 @@
+"""CliTransport — the v1 primary backend.
+
+Wraps ``shimmer.PebbleCliClient`` (a drop-in ``ops.pebble.Client`` over the Pebble
+CLI) with a :class:`~borescope.transport.runner.JujuSshRunner`. The runner reaches the
+workload's Pebble *through the charm container* (which always has a shell and has the
+workload's socket mounted), so this works even against shell-less rocks.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, cast
+
+from .runner import JujuExecRunner, JujuSshRunner
+
+if TYPE_CHECKING:
+    from . import Transport
+
+# The charm container's pebble binary (juju-injected; not on $PATH). The per-workload
+# socket path is owned by the runner (``/charm/containers/<name>/pebble.socket``).
+REMOTE_PEBBLE_BINARY = "/charm/bin/pebble"
+
+# Default per-call timeout. Higher than shimmer's local default (5 s) because each
+# call pays a ``juju`` round-trip (~0.2 s measured, plus juju client startup).
+DEFAULT_TIMEOUT = 30.0
+
+_RUNNERS = {"ssh": JujuSshRunner, "exec": JujuExecRunner}
+
+
+def build_cli_transport(
+    *,
+    unit: str,
+    container: str | None,
+    model: str | None = None,
+    juju_binary: str = "juju",
+    timeout: float = DEFAULT_TIMEOUT,
+    via: str = "ssh",
+) -> Transport:
+    """Build a CLI-relay transport for *unit*'s *container*.
+
+    *via* picks the Juju relay: ``"ssh"`` (default) uses ``juju ssh`` and works as a
+    streaming channel; ``"exec"`` uses ``juju exec`` (request/response) for sites
+    where interactive ssh is disabled.
+    """
+    # Imported lazily: shimmer pulls in ops.pebble, which we keep off the
+    # --help / --version cold-start path.
+    from shimmer import PebbleCliClient
+
+    try:
+        runner_cls = _RUNNERS[via]
+    except KeyError as exc:
+        raise ValueError(f"unknown --via {via!r}; choose 'ssh' or 'exec'") from exc
+    runner = runner_cls(unit, container, model=model, juju_binary=juju_binary)
+    # shimmer's client conforms structurally; cast past the overloaded `exec`
+    # signature the type checker can't match against the Transport protocol.
+    return cast(
+        "Transport",
+        PebbleCliClient(
+            socket_path=runner.pebble_socket or "",
+            pebble_binary=REMOTE_PEBBLE_BINARY,
+            runner=runner,
+            timeout=timeout,
+        ),
+    )

borescope/transport/relay.py

@@ -0,0 +1,77 @@
+"""Run raw ``pebble`` subcommands over the same relay the transport uses.
+
+A few Pebble CLI features (notably ``logs``) aren't part of the
+``ops.pebble.Client`` API surface, so they're driven by invoking the ``pebble``
+binary directly — remotely via ``juju ssh`` (the CLI relay), or locally against a
+reachable socket. Both the ``logs`` command and ``--snapshot`` share this.
+"""
+
+from __future__ import annotations
+
+import shutil
+import subprocess
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from ..discovery import Target
+
+
+# Juju injects pebble here in every k8s charm container, but does NOT put it on
+# $PATH. So in --here mode `shutil.which("pebble")` finds nothing — fall through
+# to this absolute location before giving up.
+_JUJU_PEBBLE = "/charm/bin/pebble"
+
+
+def _local_pebble_binary() -> str:
+    """Find the ``pebble`` binary for the local (socket) case.
+
+    Tries ``$PATH`` first (so a dev with a local Pebble install or snap works),
+    then the Juju-injected path inside a charm container.
+    """
+    found = shutil.which("pebble")
+    if found:
+        return found
+    import os
+
+    if os.path.exists(_JUJU_PEBBLE):
+        return _JUJU_PEBBLE
+    # Fall back to the bare name — subprocess will raise FileNotFoundError, which
+    # callers wrap into a clear "logs_error" / similar.
+    return "pebble"
+
+
+def pebble_relay(target: Target) -> tuple[list[str], dict[str, str] | None, Any]:
+    """Return ``(binary_prefix, env, runner)`` for running ``pebble <args>``.
+
+    ``runner`` is a shimmer ``Runner`` (``run``/``popen``); ``binary_prefix`` is the
+    argv that names the ``pebble`` binary (local ``["pebble"]`` or the remote path).
+    """
+    if target.socket_path:
+        import os
+
+        from shimmer import LocalSubprocessRunner
+
+        env = {**os.environ, "PEBBLE_SOCKET": target.socket_path}
+        return [_local_pebble_binary()], env, LocalSubprocessRunner()
+
+    from .cli_transport import _RUNNERS, REMOTE_PEBBLE_BINARY
+
+    # The runner injects the workload socket env itself (via the charm container),
+    # so no env is needed here. Pick the runner that matches the target's
+    # --via setting so `logs` / `--snapshot` use the same relay as everything else.
+    runner_cls = _RUNNERS.get(target.via, _RUNNERS["ssh"])
+    runner = runner_cls(
+        target.unit,
+        target.container,
+        model=target.model,
+        juju_binary=target.juju_binary,
+    )
+    return [REMOTE_PEBBLE_BINARY], None, runner
+
+
+def run_pebble(
+    target: Target, pebble_args: list[str], *, timeout: float = 30.0
+) -> subprocess.CompletedProcess[Any]:
+    """Run ``pebble <pebble_args>`` once and return the completed process."""
+    prefix, env, runner = pebble_relay(target)
+    return runner.run([*prefix, *pebble_args], env=env, timeout=timeout, check=False)