borescope 0.1.0.dev0__py3-none-any.whl

borescope/shell/commands/pebble.py

@@ -0,0 +1,388 @@
+"""Pebble-native subcommands, first-class (not hidden behind a ``pebble`` prefix).
+
+These are the operational value-add over a plain shell: ``services``, ``logs``,
+``plan``, ``checks``, ``notices`` and friends, as thin wrappers over the transport
+(an ``ops.pebble.Client``-shaped object).
+"""
+
+from __future__ import annotations
+
+import sys
+from typing import TYPE_CHECKING
+
+from ops import pebble
+
+from ._args import parse_args
+from .base import Command, Result
+
+if TYPE_CHECKING:
+    from ..context import ShellContext
+
+
+def _table(headers: list[str], rows: list[list[str]]) -> str:
+    widths = [len(h) for h in headers]
+    for row in rows:
+        for i, cell in enumerate(row):
+            widths[i] = max(widths[i], len(str(cell)))
+
+    def fmt(row: list[str]) -> str:
+        return "  ".join(str(cell).ljust(widths[i]) for i, cell in enumerate(row))
+
+    return "\n".join([fmt(headers), *(fmt(r) for r in rows)])
+
+
+def _enum_value(value: object) -> str:
+    return getattr(value, "value", str(value))
+
+
+# --------------------------------------------------------------------------- #
+# Services
+# --------------------------------------------------------------------------- #
+class Services(Command):
+    name = "services"
+    summary = "List services and their status"
+    usage = "services [name...]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        _, _, names = parse_args(args)
+        infos = ctx.transport.get_services(names or None)
+        if not infos:
+            return Result.ok("(no services)")
+        rows = [[i.name, _enum_value(i.startup), _enum_value(i.current)] for i in infos]
+        return Result.ok(_table(["Service", "Startup", "Current"], rows))
+
+
+class _ServiceAction(Command):
+    verb = ""
+    # English past tense — declared per subclass so we don't have to encode
+    # consonant-doubling rules ("stop" -> "Stopped", not "Stoped").
+    past = ""
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        _, _, names = parse_args(args)
+        if not names:
+            return Result.fail(f"{self.name}: usage: {self.name} <service...>")
+        method = getattr(ctx.transport, f"{self.verb}_services")
+        method(names)
+        return Result.ok(f"{self.past}: {', '.join(names)}")
+
+
+class Start(_ServiceAction):
+    name = "start"
+    verb = "start"
+    past = "Started"
+    summary = "Start services"
+    usage = "start <service...>"
+
+
+class Stop(_ServiceAction):
+    name = "stop"
+    verb = "stop"
+    past = "Stopped"
+    summary = "Stop services"
+    usage = "stop <service...>"
+
+
+class Restart(_ServiceAction):
+    name = "restart"
+    verb = "restart"
+    past = "Restarted"
+    summary = "Restart services"
+    usage = "restart <service...>"
+
+
+class Replan(Command):
+    name = "replan"
+    summary = "Apply the plan: stop/start services as the plan requires"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        ctx.transport.replan_services()
+        return Result.ok("Replanned.")
+
+
+# --------------------------------------------------------------------------- #
+# Plan
+# --------------------------------------------------------------------------- #
+class Plan(Command):
+    name = "plan"
+    summary = "Show the merged Pebble plan (YAML)"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        plan = ctx.transport.get_plan()
+        return Result.ok(plan.to_yaml().rstrip("\n"))
+
+
+# --------------------------------------------------------------------------- #
+# Logs (CLI-shaped: driven over the relay, not the ops API)
+# --------------------------------------------------------------------------- #
+class Logs(Command):
+    name = "logs"
+    summary = "Show service logs (-f / --follow to stream)"
+    usage = "logs [-f|--follow] [-n N] [service...]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        flags, values, services = parse_args(args, valued=("n",))
+        follow = "f" in flags or "follow" in flags
+        pebble_args = ["logs"]
+        if follow:
+            pebble_args.append("--follow")
+        if "n" in values:
+            pebble_args += ["-n", values["n"]]
+        pebble_args += services
+
+        argv, env, runner = self._relay(ctx)
+        argv = [*argv, *pebble_args]
+        if not follow:
+            result = runner.run(argv, env=env, timeout=30.0, check=False)
+            return Result(
+                output=result.stdout or "",
+                error=result.stderr or "",
+                code=result.returncode,
+            )
+        return self._follow(runner, argv, env)
+
+    @staticmethod
+    def _relay(ctx: ShellContext):
+        from ...transport.relay import pebble_relay
+
+        return pebble_relay(ctx.target)
+
+    @staticmethod
+    def _follow(runner, argv: list[str], env: dict[str, str]) -> Result:
+        process = runner.popen(
+            argv, stdin=None, stdout=sys.stdout, stderr=sys.stdout, text=True, env=env
+        )
+        try:
+            process.wait()
+        except KeyboardInterrupt:
+            process.terminate()
+            sys.stdout.write("\n")
+        return Result()
+
+
+# --------------------------------------------------------------------------- #
+# Checks / health
+# --------------------------------------------------------------------------- #
+class Checks(Command):
+    name = "checks"
+    summary = "List health checks and their status"
+    usage = "checks [name...]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        _, _, names = parse_args(args)
+        infos = ctx.transport.get_checks(names=names or None)
+        if not infos:
+            return Result.ok("(no checks)")
+        rows = [
+            [
+                i.name,
+                _enum_value(i.level),
+                _enum_value(i.status),
+                f"{i.failures}/{i.threshold}",
+            ]
+            for i in infos
+        ]
+        return Result.ok(_table(["Check", "Level", "Status", "Failures"], rows))
+
+
+class Health(Command):
+    name = "health"
+    summary = "Report overall health (all checks up?)"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        infos = ctx.transport.get_checks()
+        failing = [i.name for i in infos if _enum_value(i.status).lower() != "up"]
+        if not infos:
+            return Result.ok("healthy (no checks configured)")
+        if failing:
+            return Result(output=f"unhealthy: {', '.join(failing)} not up", code=1)
+        return Result.ok("healthy")
+
+
+# --------------------------------------------------------------------------- #
+# Notices
+# --------------------------------------------------------------------------- #
+class Notices(Command):
+    name = "notices"
+    summary = "List recent notices"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        notices = ctx.transport.get_notices()
+        if not notices:
+            return Result.ok("(no notices)")
+        rows = [
+            [
+                n.id,
+                _enum_value(n.type),
+                n.key,
+                str(n.occurrences),
+                n.last_repeated.isoformat() if n.last_repeated else "",
+            ]
+            for n in notices
+        ]
+        return Result.ok(_table(["ID", "Type", "Key", "Count", "Last"], rows))
+
+
+class Notice(Command):
+    name = "notice"
+    summary = "Show a single notice by ID"
+    usage = "notice <id>"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        if not args:
+            return Result.fail("notice: usage: notice <id>")
+        notice = ctx.transport.get_notice(args[0])
+        lines = [
+            f"ID:          {notice.id}",
+            f"Type:        {_enum_value(notice.type)}",
+            f"Key:         {notice.key}",
+            f"Occurrences: {notice.occurrences}",
+            f"First:       {notice.first_occurred.isoformat() if notice.first_occurred else ''}",
+            f"Last:        {notice.last_occurred.isoformat() if notice.last_occurred else ''}",
+        ]
+        if notice.last_data:
+            lines.append(f"Data:        {notice.last_data}")
+        return Result.ok("\n".join(lines))
+
+
+class Notify(Command):
+    name = "notify"
+    summary = "Record a custom notice"
+    usage = "notify <key> [data-key=value...]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        if not args:
+            return Result.fail("notify: usage: notify <key> [data-key=value...]")
+        key, *rest = args
+        data: dict[str, str] = {}
+        for item in rest:
+            name, _, value = item.partition("=")
+            data[name] = value
+        notice_id = ctx.transport.notify(
+            pebble.NoticeType.CUSTOM, key, data=data or None
+        )
+        return Result.ok(f"Recorded notice {notice_id}")
+
+
+# --------------------------------------------------------------------------- #
+# Changes / tasks
+# --------------------------------------------------------------------------- #
+def _all_changes(transport) -> list:
+    state = getattr(pebble.ChangeState, "ALL", None)
+    return transport.get_changes(select=state) if state else transport.get_changes()
+
+
+class Changes(Command):
+    name = "changes"
+    summary = "List recent changes"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        changes = _all_changes(ctx.transport)
+        if not changes:
+            return Result.ok("(no changes)")
+        rows = [
+            [
+                c.id,
+                _enum_value(c.status),
+                "ready" if c.ready else "doing",
+                c.summary,
+            ]
+            for c in changes
+        ]
+        return Result.ok(_table(["ID", "Status", "State", "Summary"], rows))
+
+
+class Tasks(Command):
+    name = "tasks"
+    summary = "Show tasks for a change (defaults to the most recent)"
+    usage = "tasks [change-id]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        if args:
+            change = ctx.transport.get_change(pebble.ChangeID(args[0]))
+        else:
+            changes = _all_changes(ctx.transport)
+            if not changes:
+                return Result.ok("(no changes)")
+            change = changes[-1]
+        rows = [
+            [_enum_value(t.status), t.summary] for t in getattr(change, "tasks", [])
+        ]
+        if not rows:
+            return Result.ok(f"Change {change.id}: (no tasks)")
+        header = f"Change {change.id}: {change.summary}"
+        return Result.ok(header + "\n" + _table(["Status", "Summary"], rows))
+
+
+# --------------------------------------------------------------------------- #
+# push / pull (explicit transfer, complementing cp/cat)
+# --------------------------------------------------------------------------- #
+class Pull(Command):
+    name = "pull"
+    summary = "Copy a file from the container to the local host"
+    usage = "pull <remote> <local>"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        _, _, paths = parse_args(args)
+        if len(paths) != 2:
+            return Result.fail("pull: usage: pull <remote> <local>")
+        from .. import pathutils
+
+        remote = pathutils.resolve(ctx.cwd, paths[0], home=ctx.home)
+        try:
+            with ctx.transport.pull(remote, encoding=None) as handle:
+                data = handle.read()
+            with open(paths[1], "wb") as out:
+                out.write(data if isinstance(data, bytes) else data.encode("utf-8"))
+        except Exception as exc:  # noqa: BLE001
+            return Result.fail(f"pull: {exc}")
+        return Result.ok(f"Pulled {paths[0]} -> {paths[1]}")
+
+
+class Push(Command):
+    name = "push"
+    summary = "Copy a local file into the container"
+    usage = "push <local> <remote>"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        _, _, paths = parse_args(args)
+        if len(paths) != 2:
+            return Result.fail("push: usage: push <local> <remote>")
+        from .. import pathutils
+
+        remote = pathutils.resolve(ctx.cwd, paths[1], home=ctx.home)
+        try:
+            with open(paths[0], "rb") as handle:
+                data = handle.read()
+            ctx.transport.push(remote, data, make_dirs=True)
+        except Exception as exc:  # noqa: BLE001
+            return Result.fail(f"push: {exc}")
+        return Result.ok(f"Pushed {paths[0]} -> {paths[1]}")

borescope/shell/completion.py

@@ -0,0 +1,77 @@
+"""Tab completion: built-in command names, and container-side filesystem paths."""
+
+from __future__ import annotations
+
+import shlex
+from collections.abc import Iterable, Iterator
+from typing import TYPE_CHECKING
+
+from prompt_toolkit.completion import Completer, Completion
+
+from . import pathutils
+
+if TYPE_CHECKING:
+    from prompt_toolkit.completion import CompleteEvent
+    from prompt_toolkit.document import Document
+
+    from .context import ShellContext
+
+
+class BorescopeCompleter(Completer):
+    """Complete the first token as a command name, later tokens as paths.
+
+    Path completion lists files inside the container via the transport. It only
+    fires on an explicit Tab (the session is created with
+    ``complete_while_typing=False``), so the ``juju ssh`` round-trip per request is
+    acceptable.
+    """
+
+    def __init__(self, command_names: Iterable[str], ctx: ShellContext):
+        self.command_names = sorted(set(command_names))
+        self.ctx = ctx
+
+    def get_completions(
+        self, document: Document, complete_event: CompleteEvent
+    ) -> Iterator[Completion]:
+        text = document.text_before_cursor
+        try:
+            tokens = shlex.split(text)
+        except ValueError:
+            tokens = text.split()
+
+        ends_with_space = text[-1:].isspace()
+        if ends_with_space:
+            word = ""
+            tokens_before = len(tokens)
+        else:
+            word = tokens[-1] if tokens else ""
+            tokens_before = len(tokens) - 1
+
+        if tokens_before <= 0:
+            for name in self.command_names:
+                if name.startswith(word):
+                    yield Completion(name, start_position=-len(word))
+            return
+
+        yield from self._complete_path(word)
+
+    def _complete_path(self, word: str) -> Iterator[Completion]:
+        ctx = self.ctx
+        if "/" in word:
+            dir_part, _, prefix = word.rpartition("/")
+            base = pathutils.resolve(ctx.cwd, dir_part or "/", home=ctx.home)
+        else:
+            prefix = word
+            base = ctx.cwd
+        try:
+            entries = ctx.transport.list_files(base)
+        except Exception:  # noqa: BLE001 - completion must never raise
+            return
+        for info in entries:
+            name = info.name
+            if not name.startswith(prefix):
+                continue
+            is_dir = getattr(getattr(info, "type", None), "name", "") == "DIRECTORY"
+            yield Completion(
+                name + ("/" if is_dir else ""), start_position=-len(prefix)
+            )

borescope/shell/context.py

@@ -0,0 +1,33 @@
+"""Per-session shell state."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from ..discovery import Target
+    from ..transport import Transport
+
+
+def _default_env() -> dict[str, str]:
+    return {"HOME": "/root", "PWD": "/"}
+
+
+@dataclass
+class ShellContext:
+    """The mutable state a command may read or update during a session."""
+
+    transport: Transport
+    target: Target
+    cwd: str = "/"
+    env: dict[str, str] = field(default_factory=_default_env)
+    last_exit: int = 0
+
+    @property
+    def home(self) -> str:
+        return self.env.get("HOME", "/root")
+
+    def chdir(self, path: str) -> None:
+        self.cwd = path
+        self.env["PWD"] = path

borescope/shell/history.py

@@ -0,0 +1,29 @@
+"""File-backed command history, keyed per controller/model/unit."""
+
+from __future__ import annotations
+
+import os
+import pathlib
+from typing import TYPE_CHECKING
+
+from prompt_toolkit.history import FileHistory, History, InMemoryHistory
+
+if TYPE_CHECKING:
+    from ..discovery import Target
+
+
+def history_path(target: Target) -> pathlib.Path:
+    base = os.environ.get("XDG_STATE_HOME") or os.path.join(
+        pathlib.Path.home(), ".local", "state"
+    )
+    return pathlib.Path(base, "borescope", "history", target.history_key)
+
+
+def history_for(target: Target) -> History:
+    """Return a per-target :class:`History`, falling back to in-memory on error."""
+    try:
+        path = history_path(target)
+        path.parent.mkdir(parents=True, exist_ok=True)
+        return FileHistory(str(path))
+    except OSError:  # pragma: no cover - unwritable home dir
+        return InMemoryHistory()

borescope/shell/parser.py

@@ -0,0 +1,91 @@
+"""Line parsing for the v1 shell.
+
+Deliberately tiny: one command at a time, with at most a single ``|`` between two
+stages. No subshells, ``&&``/``||``/``;``, redirection, or background jobs — that
+covers ~95% of debug-shell use at a fraction of the complexity, and the ``exec``
+escape hatch handles the rest by running a real binary in the container.
+"""
+
+from __future__ import annotations
+
+import re
+import shlex
+from collections.abc import Mapping
+
+from ..errors import BorescopeError
+
+_UNSUPPORTED = {
+    ";": "sequencing (;)",
+    "&": "background jobs (&)",
+    "&&": "'&&'",
+    "||": "'||'",
+    ">": "output redirection (>)",
+    ">>": "output redirection (>>)",
+    "<": "input redirection (<)",
+    "(": "subshells",
+    ")": "subshells",
+}
+
+_VAR = re.compile(r"\$(\w+)|\$\{(\w+)\}")
+
+
+class ParseError(BorescopeError):
+    """Raised when a line cannot be parsed under the v1 grammar."""
+
+
+def tokenize(line: str) -> list[str]:
+    """Split *line* into tokens, keeping shell operators as their own tokens."""
+    lexer = shlex.shlex(line, posix=True, punctuation_chars=True)
+    lexer.whitespace_split = True
+    try:
+        return list(lexer)
+    except ValueError as exc:  # e.g. unbalanced quotes
+        raise ParseError(str(exc)) from exc
+
+
+def parse_pipeline(line: str) -> list[list[str]]:
+    """Parse *line* into a list of stages, each a list of argv tokens.
+
+    Returns ``[]`` for a blank line. Raises :class:`ParseError` for unsupported
+    syntax or more than one pipe.
+    """
+    tokens = tokenize(line)
+    if not tokens:
+        return []
+
+    for tok in tokens:
+        if tok in _UNSUPPORTED:
+            raise ParseError(
+                f"{_UNSUPPORTED[tok]} is not supported in v1. "
+                "Use one command at a time (with at most a single '|')."
+            )
+
+    stages: list[list[str]] = []
+    current: list[str] = []
+    for tok in tokens:
+        if tok == "|":
+            stages.append(current)
+            current = []
+        else:
+            current.append(tok)
+    stages.append(current)
+
+    if len(stages) > 2:
+        raise ParseError("only a single pipe ('cmd1 | cmd2') is supported in v1.")
+    if any(not stage for stage in stages):
+        raise ParseError("syntax error near '|' (empty pipe stage).")
+    return stages
+
+
+def expand(token: str, env: Mapping[str, str]) -> str:
+    """Expand a leading ``~`` and ``$VAR`` / ``${VAR}`` references using *env*."""
+    if token == "~":
+        token = env.get("HOME", "/root")
+    elif token.startswith("~/"):
+        token = env.get("HOME", "/root") + token[1:]
+
+    def _sub(match: re.Match[str]) -> str:
+        name = match.group(1) or match.group(2)
+        return env.get(name, "")
+
+    return _VAR.sub(_sub, token)

borescope/shell/pathutils.py

@@ -0,0 +1,21 @@
+"""Container-side path helpers (POSIX semantics, regardless of the host OS)."""
+
+from __future__ import annotations
+
+import posixpath
+
+
+def resolve(cwd: str, path: str, *, home: str = "/root") -> str:
+    """Resolve *path* (relative to *cwd*) to an absolute, normalised path.
+
+    Handles ``~`` / ``~/…`` (against *home*), relative paths, and ``.`` / ``..``.
+    """
+    if not path:
+        return cwd
+    if path == "~":
+        path = home
+    elif path.startswith("~/"):
+        path = home + path[1:]
+    if not path.startswith("/"):
+        path = posixpath.join(cwd, path)
+    return posixpath.normpath(path)