borescope 0.1.0.dev0__py3-none-any.whl

borescope/shell/commands/base.py

@@ -0,0 +1,81 @@
+"""Command base class, result type, and the auto-discovery registry."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, ClassVar
+
+if TYPE_CHECKING:
+    from ..context import ShellContext
+
+
+@dataclass
+class Result:
+    """The outcome of running a command stage."""
+
+    output: str = ""
+    error: str = ""
+    code: int = 0
+
+    @classmethod
+    def ok(cls, output: str = "") -> Result:
+        return cls(output=output, code=0)
+
+    @classmethod
+    def fail(cls, error: str, code: int = 1) -> Result:
+        return cls(error=error, code=code)
+
+
+class ExitShell(Exception):  # noqa: N818 - control-flow signal, not an error
+    """Raised by ``exit`` to leave the REPL cleanly."""
+
+    def __init__(self, code: int = 0):
+        super().__init__(code)
+        self.code = code
+
+
+class Command:
+    """Base class for all built-in commands.
+
+    Subclasses set ``name`` (and optionally ``aliases``) and implement
+    :meth:`run`. They are auto-discovered by :func:`build_registry`, so adding a
+    command is just defining a subclass — no registration boilerplate.
+    """
+
+    name: ClassVar[str] = ""
+    aliases: ClassVar[tuple[str, ...]] = ()
+    summary: ClassVar[str] = ""
+    usage: ClassVar[str] = ""
+    # Streaming commands write directly to the terminal and cannot appear in a
+    # pipe (e.g. `logs --follow`, `tail -f`).
+    streaming: ClassVar[bool] = False
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        raise NotImplementedError
+
+
+def _iter_command_classes(root: type[Command]) -> list[type[Command]]:
+    found: list[type[Command]] = []
+    for sub in root.__subclasses__():
+        found.extend(_iter_command_classes(sub))
+        if getattr(sub, "name", ""):
+            found.append(sub)
+    return found
+
+
+def build_registry() -> dict[str, Command]:
+    """Instantiate every discovered command, keyed by name and alias."""
+    # Importing the package registers all Command subclasses.
+    from . import import_all
+
+    import_all()
+
+    registry: dict[str, Command] = {}
+    for klass in _iter_command_classes(Command):
+        instance = klass()
+        registry[klass.name] = instance
+        for alias in klass.aliases:
+            registry[alias] = instance
+    return registry

borescope/shell/commands/basic.py

@@ -0,0 +1,117 @@
+"""Shell-state and trivial commands: cd, pwd, echo, env, exit, clear, help."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .. import pathutils
+from .base import Command, ExitShell, Result
+
+if TYPE_CHECKING:
+    from ..context import ShellContext
+
+
+class Cd(Command):
+    name = "cd"
+    summary = "Change the current directory"
+    usage = "cd [dir]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        target = args[0] if args else "~"
+        path = pathutils.resolve(ctx.cwd, target, home=ctx.home)
+        try:
+            infos = ctx.transport.list_files(path, itself=True)
+        except Exception as exc:  # noqa: BLE001
+            return Result.fail(f"cd: {target}: {exc}")
+        if infos and getattr(infos[0].type, "name", "") != "DIRECTORY":
+            return Result.fail(f"cd: not a directory: {target}")
+        ctx.chdir(path)
+        return Result()
+
+
+class Pwd(Command):
+    name = "pwd"
+    summary = "Print the current directory"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        return Result.ok(ctx.cwd)
+
+
+class Echo(Command):
+    name = "echo"
+    summary = "Write arguments to output"
+    usage = "echo [args...]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        return Result.ok(" ".join(args))
+
+
+class Env(Command):
+    name = "env"
+    summary = "Show the shell's tracked environment"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        lines = [f"{key}={value}" for key, value in sorted(ctx.env.items())]
+        return Result.ok("\n".join(lines))
+
+
+class Exit(Command):
+    name = "exit"
+    aliases = ("quit",)
+    summary = "Leave borescope"
+    usage = "exit [code]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        code = 0
+        if args:
+            try:
+                code = int(args[0])
+            except ValueError:
+                code = 1
+        raise ExitShell(code)
+
+
+class Clear(Command):
+    name = "clear"
+    summary = "Clear the screen"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        return Result.ok("\033[H\033[2J")
+
+
+class Help(Command):
+    name = "help"
+    aliases = ("?",)
+    summary = "List available commands"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        from .base import build_registry
+
+        seen: dict[str, Command] = {}
+        for name, cmd in build_registry().items():
+            if cmd.name == name:  # skip aliases
+                seen[name] = cmd
+        width = max((len(n) for n in seen), default=0)
+        lines = [
+            f"  {name.ljust(width)}  {cmd.summary}"
+            for name, cmd in sorted(seen.items())
+        ]
+        header = (
+            "Built-in commands (anything else: 'exec <cmd> ...' runs it in the "
+            "container):"
+        )
+        return Result.ok(header + "\n" + "\n".join(lines))

borescope/shell/commands/execcmd.py

@@ -0,0 +1,36 @@
+"""The ``exec`` escape hatch — run any binary that's already in the container."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from .base import Command, Result
+
+if TYPE_CHECKING:
+    from ..context import ShellContext
+
+
+class Exec(Command):
+    name = "exec"
+    summary = "Run a program inside the container (escape hatch)"
+    usage = "exec <command> [args...]"
+
+    def run(
+        self, ctx: ShellContext, args: list[str], stdin: str | None = None
+    ) -> Result:
+        if not args:
+            return Result.fail("exec: usage: exec <command> [args...]")
+        from ops import pebble
+
+        try:
+            process = ctx.transport.exec(args, working_dir=ctx.cwd, stdin=stdin)
+            out, err = process.wait_output()
+        except pebble.ExecError as exc:
+            return Result(
+                output=exc.stdout or "",
+                error=exc.stderr or "",
+                code=exc.exit_code or 1,
+            )
+        except Exception as exc:  # noqa: BLE001
+            return Result.fail(f"exec: {exc}")
+        return Result(output=out or "", error=err or "", code=0)