contree-cli 0.2.3__py3-none-any.whl

contree_cli/shell/__init__.py

@@ -0,0 +1,59 @@
+"""Start an interactive shell session.
+
+Launches a REPL where bare commands (e.g. `apt install curl`) are
+executed in the session container via `run --shell`, and prefixed
+commands (e.g. `contree ls /etc`) are dispatched as management
+commands.
+
+Built-in commands: cd, pwd, history, help, exit/quit.
+Tab completion for commands, flags, image paths, tags, and branches.
+"""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+
+from contree_cli import CLIENT, SESSION_STORE, ArgumentsProtocol, SetupResult
+from contree_cli.shell.completer import ShellCompleter
+from contree_cli.shell.history import load_history, save_history
+from contree_cli.shell.parser import build_shell_parser
+from contree_cli.shell.repl import ContreeShell
+
+
+@dataclass(frozen=True)
+class ShellArgs(ArgumentsProtocol):
+    @classmethod
+    def from_args(cls, ns: argparse.Namespace) -> ShellArgs:
+        return cls()
+
+
+def setup_parser(p: argparse.ArgumentParser) -> SetupResult:
+    """Register 'contree shell' subcommand."""
+    return cmd_shell, ShellArgs
+
+
+def cmd_shell(_args: ShellArgs) -> int | None:
+    """Build parser + completer, start REPL."""
+    parser, commands = build_shell_parser()
+
+    try:
+        client = CLIENT.get()
+    except LookupError:
+        client = None
+    try:
+        store = SESSION_STORE.get()
+    except LookupError:
+        store = None
+
+    completer = ShellCompleter(commands, client=client, store=store, root_parser=parser)
+    shell = ContreeShell(parser, completer)
+
+    if store is not None:
+        load_history(store)
+    try:
+        shell.run()
+    finally:
+        if store is not None:
+            save_history(store)
+
+    return None

contree_cli/shell/completer.py

@@ -0,0 +1,465 @@
+"""Tab completion for the interactive shell."""
+from __future__ import annotations
+
+import argparse
+import json
+import logging
+import shlex
+from typing import TYPE_CHECKING
+
+from contree_cli.output import FORMATTERS
+from contree_cli.shell.parser import CommandInfo, ShellArgumentParser, get_command_names
+from contree_cli.shell.trie import Handler, PrefixRouter
+
+if TYPE_CHECKING:
+    from contree_cli.client import ContreeClient
+    from contree_cli.session import ImageCache, SessionStore
+
+log = logging.getLogger(__name__)
+
+
+class ShellCompleter:
+    """Readline completer with PrefixRouter-based dispatch."""
+
+    def __init__(
+        self,
+        commands: dict[str, CommandInfo],
+        client: ContreeClient | None = None,
+        store: SessionStore | None = None,
+        root_parser: ShellArgumentParser | None = None,
+    ) -> None:
+        self._commands = commands
+        self._command_names = get_command_names()
+        self._client = client
+        self._store = store
+        self._root_parser = root_parser
+        self._matches: list[str] = []
+
+        self.router: PrefixRouter = PrefixRouter()
+        self._build_router()
+
+    def _build_router(self) -> None:
+        r = self.router
+
+        # Shell builtins with no argument completion
+        for name in ("exit", "quit", "pwd", "history", "clear"):
+            r[(name,)] = self._complete_noop
+
+        r[("help",)] = self._complete_help_names
+        r[("cd",)] = self._complete_dir_only
+
+        # Editors → container path
+        for name in ("vim", "vi", "nano"):
+            r[(name,)] = self._complete_container_path
+
+        # Bare aliases → container path (same as contree ls/cat)
+        r[("ls",)] = self._complete_container_path
+        r[("cat",)] = self._complete_container_path
+
+        # Contree subcommand argument completers
+        arg_map: dict[str, Handler] = {
+            "ls": self._complete_container_path,
+            "cat": self._complete_container_path,
+            "cp": self._complete_container_path,
+            "cd": self._complete_dir_only,
+            "use": self._complete_image,
+            "tag": self._complete_image,
+            "show": self._complete_operation,
+            "kill": self._complete_operation,
+        }
+
+        # Register all contree commands (names + aliases)
+        for name in self._command_names:
+            handler = arg_map.get(name, self._complete_noop)
+            r[("contree", name)] = handler
+
+        # Register subparser children so subcommand name completion works.
+        # E.g. "contree file <TAB>" should show "edit", "cp", etc.
+        for name, info in self._commands.items():
+            for sub_name in self._get_subcommand_names(info.parser):
+                key = ("contree", name, sub_name)
+                if key not in r:
+                    r[key] = self._complete_noop
+
+        # --format / -f — complete format names
+        r[("--format",)] = self._complete_format_name
+        r[("-f",)] = self._complete_format_name
+
+        # Nested subcommands with specific completers
+        r[("contree", "session", "use")] = self._complete_session_name
+        r[("contree", "session", "checkout")] = self._complete_branch
+        r[("contree", "session", "co")] = self._complete_branch
+        r[("contree", "session", "branch")] = self._complete_branch
+        r[("contree", "session", "br")] = self._complete_branch
+        r[("contree", "file", "edit")] = self._complete_container_path
+        r[("contree", "file", "e")] = self._complete_container_path
+
+    def complete(self, text: str, state: int) -> str | None:
+        """Readline completer function (called repeatedly with state=0,1,...)."""
+        if state == 0:
+            try:
+                import readline
+                line = readline.get_line_buffer()
+                begidx = readline.get_begidx()
+            except (ImportError, AttributeError):
+                line = text
+                begidx = 0
+            self._matches = self.compute_completions(text, line, begidx)
+        if state < len(self._matches):
+            return self._matches[state]
+        return None
+
+    def compute_completions(
+        self, text: str, line: str, begidx: int,
+    ) -> list[str]:
+        """Determine context and return matching completions."""
+        before_cursor = line[:begidx]
+        try:
+            tokens = shlex.split(before_cursor)
+        except ValueError:
+            return []
+
+        # No tokens yet → root child names
+        if not tokens:
+            return [
+                n + " " for n in self.router.children
+                if n.startswith(text)
+            ]
+
+        node, depth = self.router.resolve(tuple(tokens))
+        remaining = tuple(tokens[depth:])
+
+        # Flag-value completion: -f/--format <TAB> → format names
+        if tokens and tokens[-1] in ("-f", "--format"):
+            return self._complete_format_name((), text)
+
+        # Flags: look up the parser from commands dict
+        if text.startswith("-"):
+            parser = self._find_parser(tokens)
+            if parser is not None:
+                return self._complete_flags(parser, text)
+
+        # Children → subcommand name completion
+        if node.children:
+            matches = [
+                n + " " for n in node.children
+                if n.startswith(text)
+            ]
+            if matches:
+                return matches
+
+        # Handler with remaining tokens
+        if node.value is not None:
+            return node.value(remaining, text)
+
+        # Fallback: implicit run mode — path-like text gets path completion,
+        # anything else gets root command names as suggestions.
+        if self._looks_like_path(text):
+            return self._complete_container_path((), text)
+
+        return [
+            n + " " for n in self.router.children
+            if n.startswith(text)
+        ]
+
+    # ------------------------------------------------------------------
+    # Parser lookup for flag completion
+    # ------------------------------------------------------------------
+
+    def _find_parser(
+        self, tokens: list[str],
+    ) -> argparse.ArgumentParser | None:
+        """Find the argparse parser for the current command context."""
+        # Strip "contree" prefix if present
+        cmd_tokens = tokens[1:] if tokens and tokens[0] == "contree" else tokens
+        if not cmd_tokens:
+            return None
+        cmd_name = cmd_tokens[0]
+        if cmd_name not in self._commands:
+            return None
+        return self._commands[cmd_name].parser
+
+    # ------------------------------------------------------------------
+    # Completion handlers  (remaining, text) -> list[str]
+    # ------------------------------------------------------------------
+
+    def _complete_noop(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        return []
+
+    def _complete_help_names(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        """``help <name>`` — all known command / alias / shell names."""
+        all_names = sorted({*self._command_names, *self.router.children})
+        return [n + " " for n in all_names if n.startswith(text)]
+
+    def _complete_format_name(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        """Complete output format names (``--format json``, ``-f table``)."""
+        return [n + " " for n in sorted(FORMATTERS) if n.startswith(text)]
+
+    def _complete_dir_only(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        """Complete container directory paths (no files)."""
+        return self._complete_container_path_inner(text, dirs_only=True)
+
+    def _complete_container_path(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        """Complete a container file/directory path."""
+        return self._complete_container_path_inner(text)
+
+    @staticmethod
+    def _looks_like_path(text: str) -> bool:
+        """Return True when *text* looks like a filesystem path."""
+        return (
+            "/" in text
+            or text.startswith(".")
+            or text.startswith("~")
+        )
+
+    # ------------------------------------------------------------------
+    # Low-level helpers
+    # ------------------------------------------------------------------
+
+    @staticmethod
+    def _get_subcommand_names(
+        parser: argparse.ArgumentParser,
+    ) -> list[str]:
+        """Extract subcommand names from a parser (if it has subparsers)."""
+        for action in parser._actions:
+            if isinstance(action, argparse._SubParsersAction):
+                return list(action.choices.keys())
+        return []
+
+    def _complete_flags(
+        self, parser: argparse.ArgumentParser, text: str,
+    ) -> list[str]:
+        """Complete flag names from parser actions."""
+        flags: list[str] = []
+        for action in parser._actions:
+            for opt in action.option_strings:
+                if opt.startswith(text):
+                    flags.append(opt + " ")
+        return flags
+
+    def _complete_container_path_inner(
+        self, text: str, *, dirs_only: bool = False,
+    ) -> list[str]:
+        """Complete a container file path via the inspect API."""
+        if self._client is None or self._store is None:
+            return []
+
+        try:
+            session = self._store.session
+            if session is None:
+                return []
+            image_uuid = session.current_image
+        except (SystemExit, Exception):
+            return []
+
+        # Split into directory + prefix for the API query.
+        # resolve_path handles cwd joining and .. normalisation.
+        if "/" in text:
+            last_slash = text.rindex("/")
+            user_dir = text[: last_slash + 1] or "/"
+            prefix = text[last_slash + 1 :]
+            resolved = self._store.resolve_path(user_dir)
+            api_dir = resolved if resolved == "/" else resolved + "/"
+        else:
+            user_dir = ""
+            prefix = text
+            resolved = self._store.resolve_path("")
+            api_dir = resolved if resolved == "/" else resolved + "/"
+
+        entries = self._list_dir(image_uuid, api_dir)
+        if entries is None:
+            return []
+
+        results: list[str] = []
+        for entry in entries:
+            path = entry.get("path", "")
+            if not isinstance(path, str) or not path:
+                continue
+            is_dir = bool(entry.get("is_dir"))
+            if dirs_only and not is_dir:
+                continue
+            # API returns full paths like "/etc/hosts" — extract basename
+            name = path.rsplit("/", 1)[-1]
+            if not name.startswith(prefix):
+                continue
+            # Return the path as the user typed it (relative or absolute)
+            full = user_dir + name
+            if is_dir:
+                full += "/"
+            else:
+                full += " "
+            results.append(full)
+        return results
+
+    def _complete_image(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        """Complete image references (``tag:NAME`` or UUID).
+
+        When the user types a ``tag:`` prefix, matches are filtered
+        against the full ``tag:NAME`` candidate.  Otherwise bare text
+        is matched against tag names directly and the completion
+        inserts the ``tag:`` prefix for the user.
+        """
+        images = self._list_images()
+        if images is None:
+            return []
+
+        results: list[str] = []
+        for img in images:
+            tag = img.get("tag")
+            if isinstance(tag, str) and tag:
+                prefixed = f"tag:{tag}"
+                if text.startswith("tag:"):
+                    if prefixed.startswith(text):
+                        results.append(prefixed + " ")
+                elif tag.startswith(text):
+                    results.append(prefixed + " ")
+            uuid_str = img.get("uuid")
+            if isinstance(uuid_str, str) and uuid_str.startswith(text):
+                results.append(uuid_str + " ")
+        return results
+
+    def _complete_operation(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        """Complete operation UUIDs for ``show`` and ``kill``."""
+        ops = self._list_operations()
+        if ops is None:
+            return []
+        results: list[str] = []
+        for op in ops:
+            uuid_str = op.get("uuid")
+            if isinstance(uuid_str, str) and uuid_str.startswith(text):
+                results.append(uuid_str + " ")
+        return results
+
+    def _list_operations(self) -> list[dict[str, object]] | None:
+        """Fetch recent operations from the API (no caching)."""
+        if self._client is None:
+            return None
+        try:
+            resp = self.client.get(
+                "/v1/operations", params={"limit": "100"},
+            )
+            data = json.loads(resp.read())
+            return data.get("operations", [])  # type: ignore[no-any-return]
+        except Exception:
+            log.debug("Operation completion failed")
+            return None
+
+    def _complete_session_name(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        """Complete session names for ``session use``."""
+        if self._store is None:
+            return []
+        try:
+            sessions = self._store.list_sessions()
+        except Exception:
+            return []
+        results: list[str] = []
+        for s in sessions:
+            key = s.session_key
+            # Match full key
+            if key.startswith(text):
+                results.append(key + " ")
+            # Match suffix (last component after _)
+            suffix = key.rsplit("_", 1)[-1] if "_" in key else ""
+            if suffix and suffix != key and suffix.startswith(text):
+                results.append(suffix + " ")
+        return results
+
+    def _complete_branch(
+        self, remaining: tuple[str, ...], text: str,
+    ) -> list[str]:
+        """Complete branch names for ``session checkout/branch``."""
+        if self._store is None:
+            return []
+        try:
+            branches = self._store.list_branches()
+        except Exception:
+            return []
+        return [
+            name + " " for name, _active in branches
+            if name.startswith(text)
+        ]
+
+    @property
+    def client(self) -> ContreeClient:
+        if self._client is None:
+            raise RuntimeError("ContreeClient is not set")
+        return self._client
+
+    @property
+    def cache(self) -> ImageCache:
+        if self._store is None:
+            raise RuntimeError("SessionStore is not set")
+        return self._store.cache
+
+    def cached(
+        self, key: tuple[str, str],
+    ) -> list[dict[str, object]] | None:
+        """Return a cached value or ``None``."""
+        result = self.cache.get(key)
+        return result  # type: ignore[return-value]
+
+    def _list_images(self) -> list[dict[str, object]] | None:
+        """Fetch image list from the API, with persistent caching."""
+        if self._client is None or self._store is None:
+            return None
+
+        cache_key = ("", "images")
+        cached = self.cached(cache_key)
+        if cached is not None:
+            return cached
+
+        try:
+            resp = self.client.get(
+                "/v1/images", params={"limit": "100"},
+            )
+            data = json.loads(resp.read())
+            images: list[dict[str, object]] = data.get("images", [])
+            self.cache[cache_key] = images
+            return images
+        except Exception:
+            log.debug("Image completion failed")
+            return None
+
+    def _list_dir(
+        self, image_uuid: str, dir_path: str,
+    ) -> list[dict[str, object]] | None:
+        """List a container directory, with persistent caching."""
+        cache_key = (image_uuid, f"files:{dir_path}")
+
+        cached = self.cached(cache_key)
+        if cached is not None:
+            return cached
+
+        try:
+            from contree_cli.client import resolve_image
+            uuid = resolve_image(self.client, image_uuid)
+            resp = self.client.get(
+                f"/v1/inspect/{uuid}/list",
+                params={"path": dir_path},
+            )
+            data = json.loads(resp.read())
+            file_list: list[dict[str, object]] = data.get("files", [])
+            self.cache[cache_key] = file_list
+            return file_list
+        except Exception:
+            log.debug(
+                "Path completion failed for %s:%s",
+                image_uuid, dir_path,
+            )
+            return None

contree_cli/shell/history.py

@@ -0,0 +1,53 @@
+"""Readline history persistence backed by the session SQLite DB."""
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from contree_cli.session import SessionStore
+
+log = logging.getLogger(__name__)
+
+
+def load_history(store: SessionStore) -> None:
+    """Populate readline history from the session database."""
+    try:
+        import readline
+    except ImportError:
+        return
+
+    lines = store.load_shell_history()
+    for line in lines:
+        readline.add_history(line)
+    log.debug("Loaded %d history lines from session DB", len(lines))
+
+
+def save_history(store: SessionStore) -> None:
+    """Persist current readline history into the session database.
+
+    Compares what readline holds against what the DB already has and
+    appends only the new tail entries.  Then trims to the maximum.
+    """
+    try:
+        import readline
+    except ImportError:
+        return
+
+    total = readline.get_current_history_length()
+    existing = store.load_shell_history()
+    existing_count = len(existing)
+
+    # Readline history is 1-indexed.
+    new_count = total - existing_count
+    if new_count <= 0:
+        return
+
+    start = existing_count + 1
+    for i in range(start, total + 1):
+        item = readline.get_history_item(i)
+        if item is not None:
+            store.add_shell_history(item)
+
+    store.trim_shell_history()
+    log.debug("Saved %d new history lines to session DB", new_count)

contree_cli/shell/parser.py

@@ -0,0 +1,107 @@
+"""Shell-safe argument parser that raises instead of calling sys.exit()."""
+from __future__ import annotations
+
+import argparse
+from dataclasses import dataclass
+from typing import NoReturn
+
+from contree_cli import Handler
+from contree_cli.output import FORMATTERS
+from contree_cli.types import COMMAND_REGISTRY, ArgumentsFormatter, get_command_docs
+
+
+class ShellParseError(Exception):
+    """Raised instead of sys.exit() when argparse encounters bad input."""
+
+    def __init__(self, message: str, usage: str, status: int = 2) -> None:
+        super().__init__(message)
+        self.message = message
+        self.usage = usage
+        self.status = status
+
+
+class ShellArgumentParser(argparse.ArgumentParser):
+    """ArgumentParser that raises ShellParseError instead of calling sys.exit()."""
+
+    def exit(self, status: int = 0, message: str | None = None) -> NoReturn:
+        raise ShellParseError(message or "", usage="", status=status)
+
+    def error(self, message: str) -> NoReturn:
+        raise ShellParseError(message, usage=self.format_usage())
+
+
+@dataclass(frozen=True)
+class CommandInfo:
+    """Metadata about a registered shell command."""
+
+    name: str
+    handler: Handler
+    parser: ShellArgumentParser
+    aliases: list[str]
+
+
+def _ensure_registered() -> None:
+    """Import arguments module to trigger register() calls if needed."""
+    if not COMMAND_REGISTRY:
+        import contree_cli.arguments  # noqa: F401
+
+
+def build_shell_parser() -> tuple[ShellArgumentParser, dict[str, CommandInfo]]:
+    """Build a parser tree from the same setup_parser() functions used by the CLI.
+
+    Returns the root parser and a dict mapping command names (and aliases)
+    to their CommandInfo for use by the completer.
+    """
+    _ensure_registered()
+    root = ShellArgumentParser(prog="", add_help=False)
+    root.add_argument(
+        "-f", "--format",
+        dest="output_format",
+        default=None,
+        choices=sorted(FORMATTERS),
+    )
+    subparsers = root.add_subparsers(
+        dest="command",
+        parser_class=ShellArgumentParser,
+    )
+
+    commands: dict[str, CommandInfo] = {}
+
+    for name, help_text, setup_fn, aliases in COMMAND_REGISTRY:
+        if name == "shell":
+            continue
+        description, epilog = get_command_docs(setup_fn)
+        sub_parser = subparsers.add_parser(
+            name,
+            help=help_text,
+            aliases=aliases,
+            description=description,
+            epilog=epilog,
+            formatter_class=ArgumentsFormatter,
+        )
+        handler, loader = setup_fn(sub_parser)
+        sub_parser.set_defaults(handler=handler, load_args=loader)
+
+        info = CommandInfo(
+            name=name,
+            handler=handler,
+            parser=sub_parser,
+            aliases=aliases,
+        )
+        commands[name] = info
+        for alias in aliases:
+            commands[alias] = info
+
+    return root, commands
+
+
+def get_command_names() -> list[str]:
+    """Return all command names and aliases (for completion)."""
+    _ensure_registered()
+    names: list[str] = []
+    for name, _, _, aliases in COMMAND_REGISTRY:
+        if name == "shell":
+            continue
+        names.append(name)
+        names.extend(aliases)
+    return names