kapsel-cli 0.1.0__py3-none-any.whl

kapsel/__init__.py

@@ -0,0 +1,6 @@
+"""
+Kapsel: Cross-platform adaptive smart terminal capsule.
+Wrap complexity, expose simplicity.
+"""
+
+__version__ = "0.1.0"

kapsel/cli.py

@@ -0,0 +1,162 @@
+"""
+Kapsel CLI entry point.
+Provides both the interactive TUI capsule shell (`kapsel`) and one-shot translator tool (`kps`).
+Includes 'kapsel toggle' to toggle Kapsel as the default terminal environment.
+All comments and descriptions are in English.
+"""
+
+import os
+import sys
+from typing import List, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+
+from kapsel import __version__
+from kapsel.completion.kps import dispatch_kps
+from kapsel.core.engine import DualStateEngine
+from kapsel.storage.logger import logger
+from kapsel.ui.banner import ensure_utf8_io, render_banner
+from kapsel.ui.card import render_execution_footer
+from kapsel.ui.prompt import KapselPrompt
+
+
+def main(args: Optional[List[str]] = None) -> int:
+    """Main interactive capsule shell loop and command runner."""
+    ensure_utf8_io()
+    if args is None:
+        args = sys.argv[1:]
+
+    # Handle quick flags
+    if args and args[0] in ("-v", "--version"):
+        print(f"Kapsel v{__version__}")
+        return 0
+
+    no_banner = "--no-banner" in args
+    clean_args = [a for a in args if a != "--no-banner"]
+
+    # Handle -c / --command
+    if clean_args and clean_args[0] in ("-c", "--command"):
+        cmd_str = " ".join(clean_args[1:])
+        engine = DualStateEngine()
+        result = engine.dispatch(cmd_str)
+        if engine.config.enable_card_border and not result.execution.is_builtin:
+            render_execution_footer(
+                summary=result.execution,
+                translation=result.translated_cmd,
+                config=engine.config,
+            )
+        return result.execution.exit_code
+
+    is_toggle_start = False
+    if clean_args and clean_args[0] == "toggle":
+        is_toggle_start = True
+        clean_args = clean_args[1:]
+
+    # If other positional subcommands passed (e.g. kapsel status, kapsel help, kapsel add, kapsel config, kapsel datadir)
+    if clean_args and not is_toggle_start:
+        engine = DualStateEngine()
+        full_cmd = "kapsel " + " ".join(clean_args)
+        result = engine.dispatch(full_cmd)
+        if engine.config.enable_card_border and not result.execution.is_builtin:
+            render_execution_footer(
+                summary=result.execution,
+                translation=result.translated_cmd,
+                config=engine.config,
+            )
+        return result.execution.exit_code
+
+    # Launch interactive shell (Kapsel Default Mode)
+    engine = DualStateEngine()
+    console = Console(legacy_windows=False)
+
+    os.environ["KAPSEL_ACTIVE"] = "1"
+
+    if is_toggle_start:
+        console.print("[bold #10b981]✔ Kapsel active.[/] [dim]Type 'toggle' or 'exit' to quit.[/]\n")
+    elif engine.config.enable_banner and not no_banner:
+        render_banner()
+
+    prompt_session = KapselPrompt(engine)
+
+    # Interactive REPL loop
+    while True:
+        try:
+            user_input = prompt_session.prompt()
+        except KeyboardInterrupt:
+            # User pressed Ctrl+C, reset prompt without exiting
+            print()
+            continue
+        except EOFError:
+            # User pressed Ctrl+D, cleanly exit
+            os.environ.pop("KAPSEL_ACTIVE", None)
+            print("\nExiting Kapsel. Bye! 💊")
+            break
+
+        stripped = user_input.strip()
+        if not stripped:
+            continue
+
+        normalized = " ".join(stripped.lower().split())
+        if normalized in ("exit", "quit", "toggle", "kapsel toggle", "kps toggle"):
+            os.environ.pop("KAPSEL_ACTIVE", None)
+            console.print("[dim]Exited Kapsel.[/]")
+            break
+
+        try:
+            result = engine.dispatch(user_input)
+            if engine.config.enable_card_border and not result.execution.is_builtin:
+                render_execution_footer(
+                    summary=result.execution,
+                    translation=result.translated_cmd,
+                    config=engine.config,
+                )
+        except Exception as e:
+            logger.exception(f"Unexpected error executing '{user_input}': {e}")
+            print(f"kapsel: unexpected error: {e}", file=sys.stderr)
+
+    return 0
+
+
+def kps_cli() -> int:
+    """
+    Direct CLI entry point for 'kps' command.
+    Allows running single commands from external shells:
+    e.g. `kps status` or `kps rm -rf node_modules`
+    """
+    ensure_utf8_io()
+    argv = sys.argv[1:]
+    if not argv:
+        # If run as bare 'kps', launch the full interactive shell
+        return main()
+
+    if argv[0] in ("-v", "--version"):
+        print(f"Kapsel v{__version__}")
+        return 0
+
+    if argv[0] == "toggle":
+        return main(["toggle"])
+
+    # 1. Fast dispatch to registered built-in or plugin kps commands
+    cmd_line = " ".join(argv)
+    builtin_exit = dispatch_kps(cmd_line)
+    if builtin_exit is not None:
+        return builtin_exit
+
+    # 2. Otherwise dispatch through engine (executes plugin filters or reports error)
+    full_line = "kps " + cmd_line
+    engine = DualStateEngine()
+    result = engine.dispatch(full_line)
+
+    if engine.config.enable_card_border and not result.execution.is_builtin:
+        render_execution_footer(
+            summary=result.execution,
+            translation=result.translated_cmd,
+            config=engine.config,
+        )
+
+    return result.execution.exit_code
+
+
+if __name__ == "__main__":
+    sys.exit(main())

kapsel/completion/__init__.py

@@ -0,0 +1,23 @@
+"""
+Kapsel Completion Subpackage.
+Fuses Fig.Spec declarative hierarchy with Kapsel's core command subsystem and plugin hooks.
+"""
+
+from kapsel.completion.carapace_engine import CarapaceCandidate, CarapaceEngine, get_carapace_engine
+from kapsel.completion.completer import DualStateCompleter
+from kapsel.completion.fig_engine import FigCandidate, FigEngine, get_fig_engine
+from kapsel.completion.fig_schema import FigArg, FigOption, FigSpec, FigSubcommand
+
+__all__ = [
+    "DualStateCompleter",
+    "CarapaceEngine",
+    "get_carapace_engine",
+    "CarapaceCandidate",
+    "FigEngine",
+    "get_fig_engine",
+    "FigCandidate",
+    "FigSpec",
+    "FigSubcommand",
+    "FigOption",
+    "FigArg",
+]

kapsel/completion/carapace_engine.py

@@ -0,0 +1,236 @@
+"""
+Carapace Dynamic Completion Engine for Kapsel.
+Bridges 'carapace-bin' to provide context-aware, multi-shell autocompletion
+for over 1,000+ commands (git, docker, kubectl, cargo, npm, etc.) with millisecond response.
+All comments and descriptions are in English.
+"""
+
+from dataclasses import dataclass
+import json
+import os
+from pathlib import Path
+import re
+import shlex
+import shutil
+import subprocess
+import sys
+from typing import Dict, List, Optional, Set, Tuple
+
+from kapsel.storage.config import get_kapsel_dir
+from kapsel.storage.logger import logger
+
+
+@dataclass
+class CarapaceCandidate:
+    """Represents a single autocompletion candidate returned by Carapace."""
+    value: str
+    display: str
+    description: str
+    style: str = ""
+    tag: str = ""
+
+
+_ANSI_ESCAPE_RE = re.compile(r"(\x1b|\x9b|`e)\[[0-?]*[ -/]*[@-~]")
+
+
+def _strip_ansi(text: str) -> str:
+    """Removes ANSI color and style escape codes from text."""
+    if not text:
+        return ""
+    return _ANSI_ESCAPE_RE.sub("", text).strip()
+
+
+def resolve_carapace_executable() -> Optional[str]:
+    """
+    Finds the carapace-bin executable in standard locations:
+    1. System PATH
+    2. Scoop shims / apps directory
+    3. Kapsel local bin directory (~/.kapsel/bin/carapace)
+    4. Cargo bin directory (~/.cargo/bin)
+    """
+    # 1. Direct Scoop app binary (avoids shim process wrapper overhead on Windows)
+    if sys.platform == "win32":
+        user_profile = Path(os.environ.get("USERPROFILE", Path.home()))
+        for candidate in [
+            user_profile / "scoop/apps/carapace-bin/current/carapace.exe",
+            user_profile / "scoop/shims/carapace.exe",
+            user_profile / ".cargo/bin/carapace.exe",
+            user_profile / "AppData/Local/Microsoft/WinGet/Links/carapace.exe",
+        ]:
+            if candidate.exists():
+                return str(candidate)
+
+    # 2. System PATH
+    which_p = shutil.which("carapace")
+    if which_p:
+        return which_p
+
+    # 3. Kapsel local bin
+    is_win = sys.platform == "win32"
+    local_bin = get_kapsel_dir() / "bin" / ("carapace.exe" if is_win else "carapace")
+    if local_bin.exists():
+        return str(local_bin)
+
+    return None
+
+
+class CarapaceEngine:
+    """
+    High-performance completion engine delegating to Carapace (carapace-bin).
+    Caches the list of 1,000+ supported tools and invokes JSON export for dynamic context.
+    """
+
+    def __init__(self, executable: Optional[str] = None):
+        self.executable: Optional[str] = executable or resolve_carapace_executable()
+        self._supported_tools: Optional[Set[str]] = None
+        self._completion_cache: Dict[Tuple[str, Tuple[str, ...], str], List[CarapaceCandidate]] = {}
+
+    def is_available(self) -> bool:
+        """Returns True if carapace-bin is installed and executable."""
+        return self.executable is not None and Path(self.executable).exists()
+
+    def get_supported_tools(self) -> Set[str]:
+        """
+        Returns the set of tool names supported by Carapace.
+        Lazy-loads via 'carapace --list' and caches in memory.
+        """
+        if self._supported_tools is not None:
+            return self._supported_tools
+
+        if not self.is_available():
+            self._supported_tools = set()
+            return self._supported_tools
+
+        try:
+            res = subprocess.run(
+                [self.executable, "--list"],
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=2.0,
+            )
+            if res.returncode == 0 and res.stdout.strip():
+                data = json.loads(res.stdout)
+                if isinstance(data, dict):
+                    self._supported_tools = set(data.keys())
+                    return self._supported_tools
+        except Exception as e:
+            logger.warning(f"Failed to load Carapace tools list: {e}")
+
+        self._supported_tools = set()
+        return self._supported_tools
+
+    def has_completer_for(self, tool: str) -> bool:
+        """Checks if Carapace has a completion specification for the given tool."""
+        normalized = tool.lower()
+        if normalized.endswith(".exe"):
+            normalized = normalized[:-4]
+        return normalized in self.get_supported_tools()
+
+    def get_completions(self, text_line: str) -> Tuple[List[CarapaceCandidate], str]:
+        """
+        Retrieves completion candidates from Carapace for the given command line.
+        Returns a tuple of (candidates, current_word_prefix).
+        """
+        if not self.is_available() or not text_line.strip():
+            return [], ""
+
+        stripped = text_line.lstrip()
+        ends_with_space = text_line.endswith(" ")
+
+        # Tokenize line respecting spaces
+        try:
+            # We use a custom parser or shlex to extract tokens
+            words = shlex.split(stripped)
+        except ValueError:
+            # Unterminated quote, fall back to simple whitespace split
+            words = stripped.split()
+
+        if not words:
+            return [], ""
+
+        first_tool = words[0].lower()
+        if first_tool.endswith(".exe"):
+            first_tool = first_tool[:-4]
+
+        if not self.has_completer_for(first_tool):
+            return [], ""
+
+        # Determine the current word prefix being completed
+        if ends_with_space:
+            prefix = ""
+            args_for_carapace = words + [""]
+        else:
+            prefix = words[-1]
+            args_for_carapace = words
+
+        # Check in-memory cache
+        cwd_str = str(Path.cwd())
+        cache_key = (first_tool, tuple(args_for_carapace), cwd_str)
+        if cache_key in self._completion_cache:
+            return self._completion_cache[cache_key], prefix
+
+        # Execute: carapace <tool> export <tool> <arg1> <arg2> ...
+        cmd = [self.executable, first_tool, "export"] + args_for_carapace
+
+        try:
+            res = subprocess.run(
+                cmd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                timeout=0.8,  # Robust timeout for process execution on Windows
+                cwd=cwd_str,
+            )
+            if res.returncode != 0 or not res.stdout.strip():
+                return [], prefix
+
+            data = json.loads(res.stdout)
+            values = data.get("values", [])
+            candidates: List[CarapaceCandidate] = []
+
+            for item in values:
+                if not isinstance(item, dict):
+                    continue
+                val = item.get("value", "")
+                disp = item.get("display", val)
+                desc = _strip_ansi(item.get("description", ""))
+                style = item.get("style", "")
+                tag = item.get("tag", "")
+
+                candidates.append(
+                    CarapaceCandidate(
+                        value=val,
+                        display=disp,
+                        description=desc,
+                        style=style,
+                        tag=tag,
+                    )
+                )
+
+            # Limit cache size to 256 entries
+            if len(self._completion_cache) > 256:
+                self._completion_cache.clear()
+            self._completion_cache[cache_key] = candidates
+
+            return candidates, prefix
+
+        except subprocess.TimeoutExpired:
+            logger.debug(f"Carapace completion timed out for: {text_line}")
+            return [], prefix
+        except Exception as e:
+            logger.debug(f"Error querying Carapace for '{text_line}': {e}")
+            return [], prefix
+
+
+_CARAPACE_ENGINE: Optional[CarapaceEngine] = None
+
+
+def get_carapace_engine() -> CarapaceEngine:
+    """Returns the singleton instance of CarapaceEngine."""
+    global _CARAPACE_ENGINE
+    if _CARAPACE_ENGINE is None:
+        _CARAPACE_ENGINE = CarapaceEngine()
+    return _CARAPACE_ENGINE

kapsel/completion/completer.py

@@ -0,0 +1,251 @@
+"""
+Kapsel Dual-State Completer (Carapace-Powered).
+Seamlessly fuses Carapace dynamic multi-shell completion (1,000+ commands)
+with Kapsel's core system management and plugin ecosystem.
+All comments and descriptions are in English.
+"""
+
+from typing import Any, Dict, Iterable, List, Optional, Tuple
+
+from prompt_toolkit.completion import CompleteEvent, Completer, Completion, PathCompleter
+from prompt_toolkit.document import Document
+
+from kapsel.completion.carapace_engine import CarapaceEngine, get_carapace_engine
+from kapsel.completion.fig_engine import FigEngine, get_fig_engine
+from kapsel.completion.kps.registry import KpsCommandRegistry, get_kps_registry
+from kapsel.core.i18n import _
+
+
+class DualStateCompleter(Completer):
+    """
+    Dual-State Carapace-Powered Completer:
+    - Native Mode: Deep multi-level context-aware autocompletion powered by Carapace
+                   (1,000+ tools: git branches/tags, docker flags/containers, npm scripts, etc.).
+    - Kapsel Mode ('kapsel <cmd>' / 'kps <cmd>'): Unified capsule commands (help, status, config,
+                   datadir, add, toggle, and plugin extensions).
+    """
+
+    def __init__(
+        self,
+        carapace_engine: Optional[CarapaceEngine] = None,
+        fig_engine: Optional[FigEngine] = None,
+        kps_registry: Optional[KpsCommandRegistry] = None,
+        current_shell: str = "pwsh",
+        plugin_manager: Optional[Any] = None,
+    ):
+        self.carapace_engine = carapace_engine or get_carapace_engine()
+        self.fig_engine = fig_engine or get_fig_engine()
+        self.kps_registry = kps_registry or get_kps_registry()
+        self.current_shell = current_shell
+        self.plugin_manager = plugin_manager
+        self.path_completer = PathCompleter(expanduser=True)
+
+    def set_shell(self, shell: str) -> None:
+        self.current_shell = shell
+
+    def get_completions(
+        self, document: Document, complete_event: CompleteEvent
+    ) -> Iterable[Completion]:
+        text_before = document.text_before_cursor
+        stripped = text_before.lstrip()
+
+        # 1. User is typing 'kapsel' or 'kps' (offer transition without trailing space)
+        if stripped in ("k", "ka", "kap", "kaps", "kapse", "kapsel"):
+            yield Completion(
+                text="kapsel",
+                start_position=-len(stripped),
+                display="kapsel",
+                display_meta="Kapsel command (help, status, config, add, ...)",
+            )
+            yield Completion(
+                text="kps",
+                start_position=-len(stripped),
+                display="kps",
+                display_meta="Kapsel command alias (kps)",
+            )
+            return
+        if stripped in ("kp", "kps"):
+            yield Completion(
+                text="kps",
+                start_position=-len(stripped),
+                display="kps",
+                display_meta="Kapsel command alias (kps)",
+            )
+            return
+
+        # 2. Unified Kapsel Command Mode: 'kapsel <cmd>' or 'kps <cmd>'
+        if stripped.startswith("kapsel "):
+            sub = stripped[7:]
+            yield from self._complete_kapsel_mode(sub)
+            return
+
+        if stripped.startswith("kps "):
+            sub = stripped[4:]
+            yield from self._complete_kapsel_mode(sub)
+            return
+
+        # 3. Native Mode: Carapace (1000+ tools), Fig fallback, builtins, & paths
+        yield from self._complete_native_mode(stripped, document, complete_event)
+
+    def _complete_kapsel_mode(self, query: str) -> Iterable[Completion]:
+        """Completes commands under unified 'kapsel ' and 'kps ' pipeline."""
+        ends_with_space = query.endswith(" ")
+        words = query.split()
+
+        if ends_with_space:
+            prefix = ""
+        else:
+            prefix = words[-1] if words else ""
+
+        available_cmds = self.kps_registry.list_commands()
+
+        # A. Completing primary command name (e.g. 'kapsel conf', 'kps ai', etc.)
+        if len(words) == 0 or (len(words) == 1 and not ends_with_space):
+            for cmd in available_cmds:
+                if cmd.name.startswith(prefix.lower()):
+                    icon = "🚀 " if cmd.plugin_id else "⚙️ "
+                    yield Completion(
+                        text=cmd.name,
+                        start_position=-len(prefix),
+                        display=cmd.name,
+                        display_meta=f"{icon}{cmd.help_text}",
+                    )
+
+        # B. Completing subcommands (e.g. 'kapsel config [edit|path|get|set]')
+        elif len(words) >= 1:
+            first_cmd_name = words[0].lower()
+            cmd = self.kps_registry.get(first_cmd_name)
+            if cmd and cmd.subcommands:
+                if len(words) == 1 and ends_with_space:
+                    sub_prefix = ""
+                elif len(words) == 2 and not ends_with_space:
+                    sub_prefix = words[1]
+                else:
+                    sub_prefix = ""
+
+                for subcmd, subdesc in cmd.subcommands.items():
+                    if subcmd.startswith(sub_prefix.lower()):
+                        yield Completion(
+                            text=subcmd,
+                            start_position=-len(sub_prefix),
+                            display=subcmd,
+                            display_meta=f"🔹 {subdesc}",
+                        )
+
+        # C. Plugin-provided dynamic completions (e.g. tldr cheat sheet caching)
+        if self.plugin_manager:
+            plugin_cands = self.plugin_manager.get_plugin_completions("kps " + query)
+            for cand in plugin_cands:
+                yield Completion(
+                    text=cand.get("text", ""),
+                    start_position=cand.get("start_position", -len(prefix)),
+                    display=cand.get("display", cand.get("text", "")),
+                    display_meta=cand.get("display_meta", "Plugin"),
+                )
+
+        # D. If user ran a native tool prefixed with kapsel/kps (e.g. 'kps git checkout')
+        if words:
+            first_tool = words[0].lower()
+            if self.carapace_engine.is_available() and self.carapace_engine.has_completer_for(first_tool):
+                yield from self._yield_carapace_completions(query)
+
+    def _complete_native_mode(
+        self, stripped: str, document: Document, complete_event: CompleteEvent
+    ) -> Iterable[Completion]:
+        parts = stripped.split()
+        first_tool = parts[0].lower() if parts else ""
+        if first_tool.endswith(".exe"):
+            first_tool = first_tool[:-4]
+
+        # A. Primary: Carapace Dynamic Completion (1,000+ commands with live context)
+        if parts and self.carapace_engine.is_available() and self.carapace_engine.has_completer_for(first_tool):
+            yield from self._yield_carapace_completions(stripped)
+            return
+
+        # B. Secondary: Fig.Spec fallback if tool was defined in Fig
+        if parts and self.fig_engine.has_spec_for_tool(first_tool):
+            yield from self._yield_fig_completions(stripped)
+            return
+
+        # C. Native Top-Level Builtins & High-Frequency Tools (when starting command line)
+        if len(parts) <= 1 and not stripped.endswith(" "):
+            curr_word = parts[0] if parts else ""
+            native_builtins = [
+                ("cd", _("Change directory")),
+                ("clear", _("Clear terminal screen")),
+                ("exit", _("Exit session")),
+                ("git", _("Git version control")),
+                ("docker", _("Docker container platform")),
+                ("scoop", _("Windows command-line installer")),
+                ("npm", _("Node.js package manager")),
+                ("cargo", _("Rust package manager")),
+                ("python", _("Python interpreter")),
+                ("kubectl", _("Kubernetes cluster CLI")),
+                ("pnpm", _("Fast disk space efficient package manager")),
+                ("yarn", _("Node.js package manager")),
+            ]
+            for cmd, desc in native_builtins:
+                if cmd.startswith(curr_word.lower()):
+                    yield Completion(
+                        text=cmd,
+                        start_position=-len(curr_word),
+                        display=cmd,
+                        display_meta=desc,
+                    )
+
+        # D. Plugin-provided completions for native mode (e.g. mapping plugins)
+        if self.plugin_manager:
+            plugin_cands = self.plugin_manager.get_plugin_completions(stripped)
+            for cand in plugin_cands:
+                yield Completion(
+                    text=cand.get("text", ""),
+                    start_position=cand.get("start_position", -len(parts[-1]) if parts else 0),
+                    display=cand.get("display", cand.get("text", "")),
+                    display_meta=cand.get("display_meta", "🔌 插件提供"),
+                )
+
+        # E. Filesystem Path Completion fallback
+        yield from self.path_completer.get_completions(document, complete_event)
+
+    def _yield_carapace_completions(self, text_line: str) -> Iterable[Completion]:
+        """Queries CarapaceEngine and yields structured, styled prompt_toolkit completions."""
+        candidates, prefix = self.carapace_engine.get_completions(text_line)
+        start_pos = -len(prefix)
+
+        for cand in candidates:
+            # Determine suitable icon based on argument type
+            if cand.value.startswith("-"):
+                icon = "🚩 "
+            elif "/" in cand.value or "\\" in cand.value:
+                icon = "📁 "
+            elif cand.tag in ("heads", "local branches", "remote branches", "tags"):
+                icon = "🌿 "
+            elif cand.tag in ("containers", "images", "volumes", "networks"):
+                icon = "🐳 "
+            else:
+                icon = "📦 "
+
+            tag_part = f"[{cand.tag}] " if cand.tag else ""
+            desc = f"{icon}{tag_part}{cand.description}".strip() if cand.description or cand.tag else f"{icon}{cand.value}"
+
+            yield Completion(
+                text=cand.value,
+                start_position=start_pos,
+                display=cand.display or cand.value,
+                display_meta=desc,
+            )
+
+    def _yield_fig_completions(self, text_line: str) -> Iterable[Completion]:
+        """Evaluates legacy Fig AST context and yields styled completions."""
+        completed, partial = self.fig_engine.tokenize_line(text_line)
+        candidates = self.fig_engine.get_completions(text_line)
+        start_pos = -len(partial) if partial else 0
+
+        for cand in candidates:
+            icon = "🚩 " if cand.kind == "option" else "📦 "
+            yield Completion(
+                text=cand.insert_text,
+                start_position=start_pos,
+                display=cand.display_text,
+                display_meta=f"{icon}{cand.description}",
+            )