contree-cli 0.2.3__py3-none-any.whl

contree_cli/shell/repl.py

@@ -0,0 +1,486 @@
+"""Interactive REPL for the contree shell."""
+from __future__ import annotations
+
+import contextlib
+import logging
+import os
+import shlex
+import sys
+
+from contree_cli import FORMATTER, IN_SHELL, SESSION_STORE, ArgumentsProtocol
+from contree_cli.client import ApiError
+from contree_cli.output import FORMATTERS, OutputFormatter
+from contree_cli.shell.completer import ShellCompleter
+from contree_cli.shell.parser import ShellArgumentParser, ShellParseError
+from contree_cli.types import Colors
+
+log = logging.getLogger(__name__)
+
+_PROMPT_BASE = "contree"
+
+# Bare names that are forwarded as contree management commands.
+_CONTREE_ALIASES = frozenset({"ls", "cat"})
+
+# Bare editor names that map to ``contree file edit`` with EDITOR override.
+_EDITOR_ALIASES = frozenset({"vim", "vi", "nano"})
+
+
+class ContreeShell:
+    """Interactive REPL that dispatches to existing command handlers.
+
+    Commands prefixed with ``contree`` are dispatched as management
+    commands via argparse (e.g. ``contree ls /etc``).  Everything else
+    is treated as an implicit ``run`` — the tokens are joined into a
+    shell expression and executed inside the current session container.
+
+    Several bare names are intercepted for convenience:
+
+    * ``ls``, ``cat`` — forwarded as the corresponding contree commands.
+    * ``vim``, ``vi``, ``nano`` — open ``contree file edit`` with the
+      host editor.
+    * ``cd`` — change the working directory for subsequent ``run``
+      commands (tracked in memory).
+    """
+
+    def __init__(
+        self,
+        parser: ShellArgumentParser,
+        completer: ShellCompleter,
+    ) -> None:
+        self._parser = parser
+        self._completer = completer
+        self._cwd = ""
+        self._prev_cwd = ""
+
+    def _print_status_line(self) -> None:
+        """Print the info line (session/image) above the input prompt."""
+        session_key = ""
+        image_uuid = ""
+        depth = 0
+        try:
+            store = SESSION_STORE.get()
+            session = store.session
+            if session is not None:
+                session_key = session.session_key
+                image_uuid = session.current_image
+                depth = store.history_depth()
+        except (LookupError, Exception):
+            pass
+        counter = Colors.CYAN(f"[{depth}]")
+        line = (
+            Colors.GRAY("session:") + Colors.YELLOW(session_key)
+            + " " + counter + " "
+            + Colors.GRAY("image:") + Colors.GREEN(image_uuid)
+        )
+        print(line)
+
+    @property
+    def _prompt(self) -> str:
+        """Short input prompt — only cwd and branch, no ANSI length issues."""
+        cwd = self._cwd or "/"
+        branch = ""
+        try:
+            session = SESSION_STORE.get().session
+            if session is not None:
+                branch = session.active_branch
+        except (LookupError, Exception):
+            pass
+        branch_part = Colors.MAGENTA(f"({branch})") + " " if branch else ""
+        return branch_part + Colors.BOLD_BLUE(cwd) + " $ "
+
+    def run(self) -> None:
+        """Main REPL loop: readline setup -> input(prompt) -> dispatch."""
+        token = IN_SHELL.set(True)
+        self._setup_readline()
+        self._load_cwd()
+        print("contree interactive shell (type 'help' for commands, Ctrl-D to exit)")
+        try:
+            while True:
+                try:
+                    self._print_status_line()
+                    line = input(self._prompt)
+                except KeyboardInterrupt:
+                    # Ctrl-C on empty prompt — print newline, continue
+                    print()
+                    continue
+                line = line.strip()
+                if not line:
+                    continue
+                self._execute(line)
+        except EOFError:
+            # Ctrl-D — clean exit
+            print()
+        finally:
+            IN_SHELL.reset(token)
+
+    # ------------------------------------------------------------------
+    # Dispatch
+    # ------------------------------------------------------------------
+
+    def _execute(self, line: str) -> None:
+        """Parse line and dispatch to the appropriate command handler."""
+        # Tokenize
+        try:
+            tokens = shlex.split(line)
+        except ValueError as exc:
+            print(f"Parse error: {exc}", file=sys.stderr)
+            return
+
+        if not tokens:
+            return
+
+        cmd = tokens[0]
+
+        # Builtins (no prefix needed)
+        if cmd in ("exit", "quit"):
+            raise EOFError
+        if cmd == "help":
+            if len(tokens) > 1:
+                arg = tokens[1]
+                if arg in ("--format", "-f"):
+                    self._print_format_help()
+                    return
+                self._dispatch_contree([arg, "--help"])
+            else:
+                self._print_shell_help()
+            return
+
+        if cmd == "clear":
+            sys.stdout.write("\033[2J\033[H")
+            sys.stdout.flush()
+            return
+
+        # --format / -f — persistent format switching
+        if cmd in ("--format", "-f"):
+            self._handle_format_command(tokens[1:])
+            return
+
+        # cd / pwd — in-memory working directory
+        if cmd == "cd":
+            self._handle_cd(tokens[1:])
+            return
+        if cmd == "pwd":
+            print(self._cwd or "/")
+            return
+        if cmd == "history":
+            self._handle_history(tokens[1:])
+            return
+
+        # ls / cat — forwarded as contree commands when simple and no
+        # pending file uploads; otherwise fall back to run so pending
+        # files are injected into the container.
+        if cmd in _CONTREE_ALIASES:
+            args = tokens[1:]
+            if (
+                not self._has_pending_files()
+                and self._is_simple_alias(cmd, args)
+            ):
+                resolved = [cmd] + [self._resolve_path(a) for a in args]
+                self._dispatch_contree(resolved)
+            else:
+                self._dispatch_run(tokens)
+            return
+
+        # vim / vi / nano — host editor via "file edit"
+        if cmd in _EDITOR_ALIASES:
+            self._dispatch_edit(cmd, tokens[1:])
+            return
+
+        # "contree ..." — explicit management command via argparse
+        if cmd == "contree":
+            if len(tokens) == 1:
+                self._print_shell_help()
+                return
+            # Truncate at --help/-h and dispatch help for the prefix
+            help_tokens: list[str] = []
+            for t in tokens[1:]:
+                if t in ("--help", "-h"):
+                    break
+                help_tokens.append(t)
+            if len(help_tokens) < len(tokens) - 1:
+                # --help/-h was found
+                if not help_tokens:
+                    self._print_shell_help()
+                else:
+                    self._dispatch_contree([help_tokens[0], "--help"])
+                return
+            if tokens[1] == "cd":
+                # Intercept cd to keep shell._cwd in sync
+                cd_args = tokens[2:]
+                if not cd_args:
+                    print(self._cwd or "/")
+                else:
+                    self._handle_cd(cd_args)
+            else:
+                self._dispatch_contree(tokens[1:])
+            return
+
+        # Everything else → implicit run in container
+        self._dispatch_run(tokens)
+
+    def _dispatch_contree(self, tokens: list[str]) -> None:
+        """Dispatch a contree management command via argparse."""
+        try:
+            ns = self._parser.parse_args(tokens)
+        except ShellParseError as exc:
+            # status=0 means --help was triggered (already printed)
+            if exc.status == 0:
+                return
+            if exc.usage:
+                print(exc.usage, file=sys.stderr, end="")
+            if exc.message:
+                print(f"error: {exc.message}", file=sys.stderr)
+            return
+
+        handler = ns.handler
+        loader: type[ArgumentsProtocol] = ns.load_args
+
+        # Per-command format override via -f/--format
+        fmt_token = None
+        fmt_name: str | None = getattr(ns, "output_format", None)
+        if fmt_name is not None:
+            fmt_token = FORMATTER.set(FORMATTERS[fmt_name]())
+
+        formatter = FORMATTER.get()
+
+        try:
+            handler(loader.from_args(ns))
+        except ApiError as exc:
+            print(f"API error: {exc}", file=sys.stderr)
+        except KeyboardInterrupt:
+            print()
+        except SystemExit:
+            # Some handlers may call sys.exit() — catch and continue
+            pass
+        except Exception as exc:
+            log.error("Command failed: %s", exc, exc_info=True)
+        finally:
+            formatter.flush()
+            if fmt_token is not None:
+                FORMATTER.reset(fmt_token)
+
+    def _dispatch_run(self, tokens: list[str]) -> None:
+        """Dispatch tokens as an implicit ``run`` in the container."""
+        from contree_cli.cli.run import RunArgs, cmd_run
+
+        args = RunArgs(command_args=tokens, shell=True, cwd=self._cwd)
+        formatter = FORMATTER.get()
+
+        try:
+            cmd_run(args)
+        except ApiError as exc:
+            print(f"API error: {exc}", file=sys.stderr)
+        except KeyboardInterrupt:
+            print()
+        except SystemExit:
+            pass
+        except Exception as exc:
+            log.error("Command failed: %s", exc, exc_info=True)
+        finally:
+            formatter.flush()
+
+    def _dispatch_edit(self, editor: str, args: list[str]) -> None:
+        """Open a container file in a host editor via ``file edit``."""
+        if not args:
+            print(f"Usage: {editor} <path>", file=sys.stderr)
+            return
+        resolved = self._resolve_path(args[0])
+        old_editor = os.environ.get("EDITOR")
+        os.environ["EDITOR"] = editor
+        try:
+            self._dispatch_contree(["file", "edit", resolved])
+        finally:
+            if old_editor is None:
+                os.environ.pop("EDITOR", None)
+            else:
+                os.environ["EDITOR"] = old_editor
+
+    # ------------------------------------------------------------------
+    # Path resolution helpers
+    # ------------------------------------------------------------------
+
+    _GLOB_CHARS = frozenset("*?[")
+
+    def _has_pending_files(self) -> bool:
+        """Return True when the session has files awaiting upload."""
+        try:
+            return bool(SESSION_STORE.get().pending_files())
+        except (LookupError, Exception):
+            return False
+
+    def _resolve_path(self, path: str) -> str:
+        """Resolve a container path via session store."""
+        if not path:
+            return path
+        return SESSION_STORE.get().resolve_path(path)
+
+    def _is_simple_alias(self, cmd: str, args: list[str]) -> bool:
+        """Check whether alias args are simple enough for contree dispatch.
+
+        Returns ``False`` (fall back to ``run``) when the arguments
+        contain flags, glob characters, or an unexpected number of
+        positional arguments for the given command.
+        """
+        for a in args:
+            if a.startswith("-"):
+                return False
+            if self._GLOB_CHARS & set(a):
+                return False
+        if cmd == "cat":
+            return len(args) == 1
+        if cmd == "ls":
+            return len(args) <= 1
+        return True
+
+    # ------------------------------------------------------------------
+    # cd — in-memory working directory
+    # ------------------------------------------------------------------
+
+    def _handle_cd(self, args: list[str]) -> None:
+        """Change the working directory for subsequent ``run`` commands."""
+        if not args:
+            # bare ``cd`` → reset to container WORKDIR
+            self._prev_cwd = self._cwd
+            self._cwd = ""
+            self._persist_cwd()
+            return
+
+        target = args[0]
+
+        if target == "-":
+            self._cwd, self._prev_cwd = self._prev_cwd, self._cwd
+            if self._cwd:
+                print(self._cwd)
+            self._persist_cwd()
+            return
+
+        new_cwd = SESSION_STORE.get().resolve_path(target)
+        self._prev_cwd = self._cwd
+        self._cwd = new_cwd
+        self._persist_cwd()
+
+    def _persist_cwd(self) -> None:
+        """Write the current working directory to session storage."""
+        try:
+            store = SESSION_STORE.get()
+            store.set_cwd(self._cwd)
+        except (LookupError, Exception):
+            pass
+
+    def _load_cwd(self) -> None:
+        """Restore the working directory from session storage."""
+        try:
+            store = SESSION_STORE.get()
+            self._cwd = store.get_cwd()
+        except (LookupError, Exception):
+            pass
+
+    # ------------------------------------------------------------------
+    # history — show shell history from SQLite
+    # ------------------------------------------------------------------
+
+    def _handle_history(self, args: list[str]) -> None:
+        """Print shell history from the session database."""
+        try:
+            store = SESSION_STORE.get()
+            lines = store.load_shell_history()
+        except (LookupError, Exception):
+            lines = []
+        if not lines:
+            print("(no history)")
+            return
+        # Optional: limit output with an argument (e.g. ``history 20``)
+        count = len(lines)
+        if args:
+            with contextlib.suppress(ValueError):
+                count = int(args[0])
+        for i, line in enumerate(lines[-count:], start=max(1, len(lines) - count + 1)):
+            print(f" {i:5d}  {line}")
+
+    # ------------------------------------------------------------------
+    # --format / -f — persistent format switching
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _format_name(formatter: OutputFormatter) -> str:
+        """Return the FORMATTERS key for *formatter*'s type."""
+        for name, cls in FORMATTERS.items():
+            if type(formatter) is cls:
+                return name
+        return type(formatter).__name__
+
+    def _handle_format_command(self, args: list[str]) -> None:
+        """Handle ``--format [NAME]`` as a shell builtin."""
+        if not args:
+            # Print current format name
+            print(self._format_name(FORMATTER.get()))
+            return
+        name = args[0]
+        if name not in FORMATTERS:
+            names = ", ".join(sorted(FORMATTERS))
+            print(
+                f"Unknown format {name!r}. Available: {names}",
+                file=sys.stderr,
+            )
+            return
+        FORMATTER.set(FORMATTERS[name]())
+
+    @staticmethod
+    def _print_format_help() -> None:
+        """Print help text for the --format / -f builtin."""
+        names = ", ".join(sorted(FORMATTERS))
+        print(
+            "Usage:\n"
+            "  --format            Show current output format\n"
+            "  --format NAME       Switch output format for the session\n"
+            f"\nAvailable formats: {names}\n"
+            "\nPer-command override: contree -f NAME <command>",
+        )
+
+    def _print_shell_help(self) -> None:
+        """Print full shell help including builtins and contree commands."""
+        fmt = ", ".join(sorted(FORMATTERS))
+        print(
+            "Shell builtins:\n"
+            "  help [CMD]          Show help (for CMD if given)\n"
+            "  exit / quit         Exit the shell (or Ctrl-D)\n"
+            "  clear               Clear the screen\n"
+            "  cd [PATH]           Change working directory (cd - to swap)\n"
+            "  pwd                 Print working directory\n"
+            "  history [N]         Show command history (last N lines)\n"
+            "  --format [NAME]     Show or switch output format\n"
+            f"                      Available: {fmt}\n"
+            "\n"
+            "Editor aliases:\n"
+            "  vim / vi / nano PATH   Edit a file via contree file edit\n"
+            "\n"
+            "Contree commands (prefix with 'contree' or use directly):\n"
+            "  ls [PATH]           List files in container image\n"
+            "  cat PATH            Show file content from image\n"
+            "  contree <CMD>       Run any contree management command\n"
+            "\n"
+            "Anything else is executed as a command inside the container.\n"
+            "\n"
+            "Use 'help CMD' for detailed help on a specific command.",
+        )
+
+    # ------------------------------------------------------------------
+    # Readline
+    # ------------------------------------------------------------------
+
+    def _setup_readline(self) -> None:
+        """Configure readline for tab completion."""
+        try:
+            import readline
+        except ImportError:
+            return
+
+        readline.set_completer(self._completer.complete)
+        readline.set_completer_delims(" \t\n")
+
+        # macOS uses libedit which has different bind syntax
+        doc = getattr(readline, "__doc__", "") or ""
+        if "libedit" in doc:
+            readline.parse_and_bind("bind ^I rl_complete")
+        else:
+            readline.parse_and_bind("tab: complete")

contree_cli/shell/trie.py

@@ -0,0 +1,113 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Iterator, MutableMapping
+
+Handler = Callable[..., list[str]]
+
+
+class PrefixRouter(MutableMapping[tuple[str, ...], Handler]):
+    """Dict-of-dicts trie mapping token paths to handler callables.
+
+    Keys are tuples of tokens, e.g. ``("contree", "session", "use")``.
+    Values are handler callables receiving ``(remaining, text) -> list[str]``.
+
+    The :meth:`resolve` method walks the trie as far as possible,
+    returning the deepest matching node and how many tokens were consumed.
+    """
+
+    __slots__ = ("_children", "_handler")
+
+    def __init__(self) -> None:
+        self._handler: Handler | None = None
+        self._children: dict[str, PrefixRouter] = {}
+
+    # -- Properties -----------------------------------------------------------
+
+    @property
+    def value(self) -> Handler | None:
+        """The handler stored at this node, or ``None``."""
+        return self._handler
+
+    @property
+    def children(self) -> dict[str, PrefixRouter]:
+        """Direct children mapping token → sub-router."""
+        return self._children
+
+    # -- MutableMapping interface ---------------------------------------------
+
+    def __getitem__(self, key: tuple[str, ...]) -> Handler:
+        node = self
+        for token in key:
+            try:
+                node = node._children[token]
+            except KeyError:
+                raise KeyError(key) from None
+        if node._handler is None:
+            raise KeyError(key)
+        return node._handler
+
+    def __setitem__(self, key: tuple[str, ...], value: Handler) -> None:
+        node = self
+        for token in key:
+            if token not in node._children:
+                node._children[token] = PrefixRouter()
+            node = node._children[token]
+        node._handler = value
+
+    def __delitem__(self, key: tuple[str, ...]) -> None:
+        node = self
+        for token in key:
+            try:
+                node = node._children[token]
+            except KeyError:
+                raise KeyError(key) from None
+        if node._handler is None:
+            raise KeyError(key)
+        node._handler = None
+
+    def __contains__(self, key: object) -> bool:
+        if not isinstance(key, tuple):
+            return False
+        node = self
+        for token in key:
+            if not isinstance(token, str):
+                return False
+            child = node._children.get(token)
+            if child is None:
+                return False
+            node = child
+        return node._handler is not None
+
+    def __iter__(self) -> Iterator[tuple[str, ...]]:
+        yield from self._iter_keys(())
+
+    def _iter_keys(
+        self, prefix: tuple[str, ...],
+    ) -> Iterator[tuple[str, ...]]:
+        if self._handler is not None:
+            yield prefix
+        for token, child in self._children.items():
+            yield from child._iter_keys((*prefix, token))
+
+    def __len__(self) -> int:
+        count = 1 if self._handler is not None else 0
+        for child in self._children.values():
+            count += len(child)
+        return count
+
+    def resolve(self, tokens: tuple[str, ...]) -> tuple[PrefixRouter, int]:
+        node = self
+        depth = 0
+        for token in tokens:
+            child = node._children.get(token)
+            if child is None:
+                break
+            node = child
+            depth += 1
+        return node, depth
+
+    def __repr__(self) -> str:
+        return (
+            f"PrefixRouter(handler={self._handler is not None}, "
+            f"children={list(self._children)})"
+        )

contree_cli/types.py

@@ -0,0 +1,87 @@
+from __future__ import annotations
+
+import argparse
+import sys
+from collections.abc import Callable
+from datetime import datetime, timezone
+from enum import Enum
+
+from contree_cli import SetupResult
+
+IS_A_TTY = sys.stderr.isatty()
+
+
+class ArgumentsFormatter(argparse.RawDescriptionHelpFormatter):
+    def _get_help_string(self, action: argparse.Action) -> str:
+        help_text = action.help or ""
+        if (
+            action.default not in (None, False, [], argparse.SUPPRESS)
+            and "%(default)" not in help_text
+        ):
+            help_text += " (default: %(default)s)"
+        return help_text
+
+
+def get_command_docs(setup_fn: SetupFn) -> tuple[str | None, str | None]:
+    """Extract description and epilog from the module that defines *setup_fn*.
+
+    The module's ``__doc__`` becomes the description; an optional
+    module-level ``EPILOG`` variable becomes the epilog.
+    """
+    mod = sys.modules.get(setup_fn.__module__)
+    if mod is None:
+        return None, None
+    return mod.__doc__, getattr(mod, "EPILOG", None)
+
+
+class Colors(Enum):
+    """
+    Each enum value is callable and can be used to wrap text in the corresponding color.
+
+        Example usage:
+            print(Colors.BOLD_RED("This is bold red text"))
+    """
+
+    DEFAULT = "\033[0m"
+    BOLD = "\033[1m"
+    BOLD_BLACK = "\033[1;30m"
+    BOLD_BLUE = "\033[1;34m"
+    BOLD_CYAN = "\033[1;36m"
+    BOLD_GRAY = "\033[1;90m"
+    BOLD_GREEN = "\033[1;32m"
+    BOLD_MAGENTA = "\033[1;35m"
+    BOLD_RED = "\033[1;31m"
+    BOLD_WHITE = "\033[1;37m"
+    BOLD_YELLOW = "\033[1;33m"
+    BLACK = "\033[30m"
+    BLUE = "\033[34m"
+    CYAN = "\033[36m"
+    GRAY = "\033[90m"
+    GREEN = "\033[32m"
+    MAGENTA = "\033[35m"
+    RED = "\033[31m"
+    WHITE = "\033[37m"
+    YELLOW = "\033[33m"
+
+    def __call__(self, text: str) -> str:
+        if not IS_A_TTY:
+            return text
+        return f"{self.value}{text}{Colors.DEFAULT.value}"
+
+if sys.version_info >= (3, 11):
+    def parse_datetime(value: str) -> datetime:
+        """Parse an ISO 8601 datetime string from the API."""
+        return datetime.fromisoformat(value).astimezone(tz=timezone.utc)
+else:
+    def parse_datetime(value: str) -> datetime:
+        """Parse an ISO 8601 datetime string from the API.
+
+        Python 3.10 ``fromisoformat`` does not accept the ``Z`` suffix.
+        """
+        if value.endswith("Z"):
+            value = value[:-1] + "+00:00"
+        return datetime.fromisoformat(value).astimezone(tz=timezone.utc)
+
+
+SetupFn = Callable[[argparse.ArgumentParser], SetupResult]
+COMMAND_REGISTRY: list[tuple[str, str, SetupFn, list[str]]] = []