borescope 0.1.0b1__py3-none-any.whl

borescope/__init__.py

@@ -0,0 +1,13 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""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,13 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""``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,143 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""Command-line entry point for borescope."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+
+from . import __version__
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the top-level ``argparse`` parser."""
+    parser = argparse.ArgumentParser(
+        prog='borescope',
+        description=('A natural shell for debugging Juju Kubernetes workload containers.'),
+    )
+    parser.add_argument('unit', nargs='?', help="unit reference, for example '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, validate_container_name
+
+    if args.container is not None:
+        validate_container_name(args.container)
+    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:
+    """Run borescope from the command line and return the exit code."""
+    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 (for example '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,264 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""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+)$')
+
+# Juju container names are lowercase alphanumerics with internal hyphens. Validating
+# matters because the name is interpolated into a remote path and an ``env
+# PEBBLE_SOCKET=…`` argv that ``juju ssh`` ultimately hands to a shell.
+_CONTAINER_RE = re.compile(r'^[a-z0-9][a-z0-9-]*$')
+
+# 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 validate_container_name(name: str) -> str:
+    """Return *name* if it's a valid container name; raise :class:`DiscoveryError`."""
+    if not _CONTAINER_RE.match(name):
+        raise DiscoveryError(
+            f"'{name}' is not a valid container name "
+            '(lowercase letters, digits, and hyphens only).'
+        )
+    return name
+
+
+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 (for example '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=effective_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 '{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.
+        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 (that is, 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:
+        raise DiscoveryError(
+            f"could not reach Pebble in {target.unit} container '{target.container}': {exc}"
+        ) from exc
+
+    # borescope v1 relies on Pebble's `--format json` output (via shimmer). Older
+    # Pebbles (for example, 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:
+        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,23 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""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 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,88 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""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,11 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""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,16 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""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,57 @@
+# Copyright 2026 Tony Meyer
+# SPDX-License-Identifier: Apache-2.0
+
+"""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 (for example, ``("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