kapsel-cli 0.1.0__py3-none-any.whl

kapsel/completion/kps/builtins/status.py

@@ -0,0 +1,121 @@
+"""
+Kapsel Status Command.
+Renders comprehensive runtime environment, shell sniffing, and sandbox status dashboard.
+"""
+
+from datetime import datetime
+import os
+from pathlib import Path
+import platform
+import sys
+from typing import List, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from kapsel import __version__
+from kapsel.core.detector import detector
+from kapsel.i18n import _
+from kapsel.storage.config import load_config
+from kapsel.storage.logger import get_kapsel_dir
+from kapsel.ui.banner import ensure_utf8_io
+
+
+def handle_status(args: Optional[List[str]] = None, console: Optional[Console] = None) -> int:
+    """Renders the detailed Kapsel environment and runtime status dashboard."""
+    ensure_utf8_io()
+    con = console or Console(legacy_windows=False)
+
+    shell_name, shell_path = detector.detect_shell()
+    is_elevated, elevated_label = detector.is_elevated()
+    cwd_raw = Path.cwd()
+    cwd_fmt = detector.format_cwd(cwd_raw)
+    branch = detector.get_git_branch(cwd_raw)
+    cfg = load_config()
+    sandbox_dir = get_kapsel_dir()
+
+    # Status Grid
+    grid = Table.grid(expand=True, padding=(0, 2))
+    grid.add_column(style="bold #00f0ff", justify="right", width=18)
+    grid.add_column(style="#e4e4e7")
+    grid.add_column(style="bold #a855f7", justify="right", width=18)
+    grid.add_column(style="#e4e4e7")
+
+    admin_str = _("Admin")
+    priv_badge = (
+        f"[bold #10b981][{elevated_label}][/]"
+        if not is_elevated
+        else f"[bold #f59e0b][{elevated_label} ({admin_str})][/]"
+    )
+
+    none_str = _("None")
+    grid.add_row(
+        f"🖥️ {_('Platform:')}",
+        f"{platform.system()} {platform.release()} ({platform.machine()})",
+        f"🐚 {_('Host Shell:')}",
+        f"[bold #38bdf8]{shell_name}[/] [dim]({shell_path})[/]",
+    )
+
+    grid.add_row(
+        f"⚡ {_('Privilege:')}",
+        priv_badge,
+        f"🌿 {_('Git Branch:')}",
+        f"[bold #10b981]{branch}[/]" if branch else f"[dim]{none_str}[/]",
+    )
+
+    grid.add_row(
+        f"📂 {_('Working Dir:')}",
+        f"[dim]{cwd_fmt}[/]",
+        f"💊 {_('Kapsel Version:')}",
+        f"[bold #00f0ff]v{__version__}[/] (Python {sys.version.split()[0]})",
+    )
+
+    theme_name = cfg.theme.get("name", "cyber_dark") if isinstance(cfg.theme, dict) else str(cfg.theme)
+    border_status = _("On") if cfg.enable_card_border else _("Off")
+    grid.add_row(
+        f"📦 {_('Sandbox Dir:')}",
+        f"[dim]{sandbox_dir}[/]",
+        f"🎨 {_('Active Theme:')}",
+        f"[bold #a855f7]{theme_name}[/] [dim](Border: {border_status})[/]",
+    )
+
+    # Completion & Plugins info
+    from kapsel.completion.kps.registry import get_kps_registry
+    registry = get_kps_registry()
+    commands = registry.list_commands()
+
+    from kapsel.completion.carapace_engine import get_carapace_engine
+    carapace_eng = get_carapace_engine()
+    if carapace_eng.is_available():
+        tools_count = len(carapace_eng.get_supported_tools())
+        completer_label = f"[bold #10b981]{tools_count}+[/] Carapace specs"
+    else:
+        specs_dir = Path(__file__).resolve().parent.parent.parent / "specs"
+        spec_count = len(list(specs_dir.glob("*.json"))) if specs_dir.exists() else 0
+        completer_label = f"[dim]{spec_count} Fig specs[/]"
+
+    is_active = os.environ.get("KAPSEL_ACTIVE") == "1"
+    active_str = _("Active")
+    standby_str = _("Standby")
+    grid.add_row(
+        f"🎯 {_('Completer:')}",
+        completer_label,
+        f"⚙️ {_('Session Mode:')}",
+        f"[bold #10b981]🟢 {active_str}[/]" if is_active else f"[dim]⚪ {standby_str}[/]",
+    )
+
+    title_str = _("💊 KAPSEL System & Environment Status")
+    panel = Panel(
+        grid,
+        title=f"[bold #00f0ff]{title_str}[/]",
+        title_align="left",
+        border_style="#0891b2",
+        padding=(1, 2),
+    )
+
+    con.print()
+    con.print(panel)
+    con.print()
+    return 0

kapsel/completion/kps/builtins/toggle.py

@@ -0,0 +1,34 @@
+"""
+Kapsel Toggle Command: 'kapsel toggle'.
+Toggles Kapsel as the default terminal environment.
+Typing it once opens the interactive Kapsel capsule shell.
+Typing it a second time closes the shell and returns to the host terminal.
+All comments and descriptions are in English.
+"""
+
+import os
+from typing import List, Optional
+from rich.console import Console
+from rich.panel import Panel
+
+from kapsel.i18n import _
+from kapsel.ui.banner import ensure_utf8_io
+
+
+def handle_toggle_command(args: Optional[List[str]] = None, console: Optional[Console] = None) -> int:
+    """
+    Handles 'kapsel toggle' command.
+    Reports the toggle mechanism or current status.
+    """
+    ensure_utf8_io()
+    con = console or Console(legacy_windows=False)
+
+    is_active = os.environ.get("KAPSEL_ACTIVE") == "1"
+
+    if is_active:
+        msg = _("🔌 Kapsel session is active. Type 'kapsel toggle' or 'exit' to quit.")
+        con.print(f"[bold #00f0ff]{msg}[/]")
+    else:
+        msg = _("✔ Kapsel session is ready. Run 'kapsel toggle' to launch.")
+        con.print(f"[bold #10b981]{msg}[/]")
+    return 0

kapsel/completion/kps/dispatcher.py

@@ -0,0 +1,65 @@
+"""
+Kapsel Command Dispatcher.
+Dispatches 'kapsel <cmd>' and 'kps <cmd>' uniformly.
+Unified architecture ensures both prefixes share the exact same command pipeline.
+"""
+
+from typing import List, Optional
+from rich.console import Console
+
+from kapsel.completion.kps.registry import get_kps_registry
+from kapsel.i18n import _
+
+
+def dispatch_kps(command_line: str, console: Optional[Console] = None) -> Optional[int]:
+    """
+    Dispatches command lines starting with 'kapsel' or 'kps'.
+    Both 'kapsel <cmd>' and 'kps <cmd>' route to the unified command registry.
+    Returns exit code (int) if handled, or None if not recognized or not a kapsel/kps command.
+    """
+    stripped = command_line.strip()
+    if not stripped:
+        return 0
+
+    con = console or Console(legacy_windows=False)
+    registry = get_kps_registry()
+
+    # Determine command prefix and subcommand string
+    if stripped.startswith("kapsel "):
+        sub = stripped[7:].strip()
+    elif stripped == "kapsel":
+        sub = ""
+    elif stripped.startswith("kps "):
+        sub = stripped[4:].strip()
+    elif stripped == "kps":
+        sub = ""
+    else:
+        # Not a kapsel or kps command: do not intercept
+        return None
+
+    # Handle bare 'kapsel' or 'kps' -> Show comprehensive manual and commands
+    if not sub:
+        help_cmd = registry.get("help")
+        if help_cmd:
+            return help_cmd.handler([], con)
+        return 0
+
+    parts = sub.split()
+    cmd_name = parts[0].lower()
+    args = parts[1:]
+
+    # Check alias shortcuts
+    if cmd_name in ("?", "-h", "--help"):
+        cmd_name = "help"
+    elif cmd_name == "info":
+        cmd_name = "status"
+
+    # Route to unified command registry
+    cmd = registry.get(cmd_name)
+    if cmd:
+        return cmd.handler(args, con)
+
+    msg = _("kapsel: unknown command '{cmd}'. See 'kapsel help'.").format(cmd=cmd_name)
+    con.print(f"[bold #f43f5e]{msg}[/]")
+    return 1
+

kapsel/completion/kps/registry.py

@@ -0,0 +1,101 @@
+"""
+Kapsel Command Registry.
+Unified Single Source of Truth for system management ('kapsel <cmd>')
+and feature extension ('kps <cmd>') commands.
+Used by autocompletion engines and command line dispatchers.
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, List, Optional
+from rich.console import Console
+
+
+@dataclass
+class KpsCommand:
+    """
+    Represents a registered command in the Kapsel ecosystem.
+    Shared uniformly across 'kapsel <cmd>' and 'kps <cmd>'.
+    """
+    name: str
+    help_text: str
+    handler: Callable[[List[str], Optional[Console]], Optional[int]]
+    subcommands: Dict[str, str] = field(default_factory=dict)
+    usage: Optional[str] = None
+    plugin_id: Optional[str] = None
+    scope: str = "default"
+
+
+class KpsCommandRegistry:
+    """Central registry storing all Kapsel commands uniformly."""
+
+    def __init__(self):
+        # Keyed by command name (lowercase) to provide a unified command pipeline
+        self._commands: Dict[str, KpsCommand] = {}
+
+    def register(
+        self,
+        name: str,
+        handler: Callable[[List[str], Optional[Console]], Optional[int]],
+        help_text: str,
+        subcommands: Optional[Dict[str, str]] = None,
+        usage: Optional[str] = None,
+        plugin_id: Optional[str] = None,
+        scope: str = "default",
+    ) -> KpsCommand:
+        """Registers a command into the unified registry."""
+        clean_name = name.lower().strip()
+        cmd = KpsCommand(
+            name=clean_name,
+            help_text=help_text,
+            handler=handler,
+            subcommands=subcommands or {},
+            usage=usage,
+            plugin_id=plugin_id,
+            scope=scope,
+        )
+        self._commands[clean_name] = cmd
+        return cmd
+
+    def get(self, name: str, scope: Optional[str] = None) -> Optional[KpsCommand]:
+        """Retrieves a command by name from the unified registry."""
+        clean_name = name.lower().strip()
+        return self._commands.get(clean_name)
+
+    def list_commands(self) -> List[KpsCommand]:
+        """Returns all registered commands sorted by name."""
+        return sorted(self._commands.values(), key=lambda c: c.name)
+
+    def list_system_commands(self) -> List[KpsCommand]:
+        """Backward-compatibility alias returning all core built-in commands."""
+        return sorted(
+            [c for c in self._commands.values() if not c.plugin_id],
+            key=lambda c: c.name,
+        )
+
+    def list_feature_commands(self) -> List[KpsCommand]:
+        """Backward-compatibility alias returning all plugin-provided commands."""
+        return sorted(
+            [c for c in self._commands.values() if c.plugin_id],
+            key=lambda c: c.name,
+        )
+
+    def remove_by_plugin(self, plugin_id: str) -> None:
+        """Removes all commands registered by a specific plugin."""
+        self._commands = {
+            k: v for k, v in self._commands.items() if v.plugin_id != plugin_id
+        }
+
+
+# Global registry singleton
+_GLOBAL_REGISTRY: Optional[KpsCommandRegistry] = None
+
+
+def get_kps_registry() -> KpsCommandRegistry:
+    """Gets or initializes the global command registry."""
+    global _GLOBAL_REGISTRY
+    if _GLOBAL_REGISTRY is None:
+        _GLOBAL_REGISTRY = KpsCommandRegistry()
+        # Auto-register core built-in commands
+        from kapsel.completion.kps.builtins import register_builtins
+        register_builtins(_GLOBAL_REGISTRY)
+    return _GLOBAL_REGISTRY

kapsel/core/__init__.py

@@ -0,0 +1,28 @@
+"""
+Kapsel core engine package.
+"""
+
+from kapsel.core.detector import EnvironmentDetector, detector
+from kapsel.core.engine import DispatchResult, DualStateEngine
+from kapsel.core.executor import CommandExecutor, ExecutionSummary
+from kapsel.core.plugin import (
+    HookType,
+    KapselPlugin,
+    PluginContext,
+    PluginManager,
+    PluginManifest,
+)
+
+__all__ = [
+    "EnvironmentDetector",
+    "detector",
+    "CommandExecutor",
+    "ExecutionSummary",
+    "DualStateEngine",
+    "DispatchResult",
+    "KapselPlugin",
+    "PluginManifest",
+    "PluginContext",
+    "HookType",
+    "PluginManager",
+]

kapsel/core/detector.py

@@ -0,0 +1,162 @@
+"""
+Kapsel environment and shell sniffing detector.
+Identifies host shell, elevation level, current working directory, and Git branch.
+"""
+
+import ctypes
+import os
+from pathlib import Path
+import platform
+import sys
+from typing import Optional, Tuple
+
+import psutil
+import shellingham
+
+from kapsel.storage.logger import logger
+
+
+class EnvironmentDetector:
+    """Sniffs host shell, user privileges, Git state, and directory paths."""
+
+    KNOWN_SHELLS = {
+        "pwsh": "pwsh",
+        "pwsh.exe": "pwsh",
+        "powershell": "powershell",
+        "powershell.exe": "powershell",
+        "cmd": "cmd",
+        "cmd.exe": "cmd",
+        "bash": "bash",
+        "bash.exe": "bash",
+        "zsh": "zsh",
+        "fish": "fish",
+        "sh": "sh",
+    }
+
+    def __init__(self):
+        self._cached_shell: Optional[str] = None
+        self._cached_shell_path: Optional[str] = None
+
+    def detect_shell(self) -> Tuple[str, str]:
+        """
+        Detects the outer host shell name and executable path.
+        Returns (shell_name, executable_path), e.g. ('pwsh', 'C:\\...\\pwsh.exe').
+        """
+        if self._cached_shell and self._cached_shell_path:
+            return self._cached_shell, self._cached_shell_path
+
+        # 1. Try psutil process tree lookup (inspect parents of current process)
+        try:
+            current_proc = psutil.Process(os.getpid())
+            for parent in current_proc.parents():
+                name = parent.name().lower()
+                if name in self.KNOWN_SHELLS:
+                    canonical = self.KNOWN_SHELLS[name]
+                    try:
+                        exe = parent.exe()
+                    except Exception:
+                        exe = name
+                    self._cached_shell = canonical
+                    self._cached_shell_path = exe
+                    logger.debug(f"Detected host shell from parent process: {canonical} ({exe})")
+                    return canonical, exe
+        except Exception as e:
+            logger.debug(f"Process tree shell detection failed: {e}")
+
+        # 2. Try shellingham
+        try:
+            detected = shellingham.detect_shell()
+            if detected:
+                raw_name, raw_path = detected
+                canonical = self.KNOWN_SHELLS.get(raw_name.lower(), raw_name.lower())
+                self._cached_shell = canonical
+                self._cached_shell_path = raw_path
+                logger.debug(f"Detected host shell from shellingham: {canonical} ({raw_path})")
+                return canonical, raw_path
+        except Exception as e:
+            logger.debug(f"Shellingham detection failed: {e}")
+
+        # 3. Environment variable fallback
+        if platform.system() == "Windows":
+            comspec = os.environ.get("COMSPEC", "cmd.exe")
+            # If PSModulePath is set and contains pwsh
+            ps_module_path = os.environ.get("PSModulePath", "")
+            if "PowerShell\\7" in ps_module_path or "pwsh" in ps_module_path.lower():
+                self._cached_shell = "pwsh"
+                self._cached_shell_path = "pwsh.exe"
+            elif "WindowsPowerShell" in ps_module_path:
+                self._cached_shell = "powershell"
+                self._cached_shell_path = "powershell.exe"
+            else:
+                self._cached_shell = "cmd"
+                self._cached_shell_path = comspec
+        else:
+            shell_env = os.environ.get("SHELL", "/bin/sh")
+            base_name = Path(shell_env).name.lower()
+            self._cached_shell = self.KNOWN_SHELLS.get(base_name, base_name)
+            self._cached_shell_path = shell_env
+
+        logger.debug(f"Fallback shell detection: {self._cached_shell} ({self._cached_shell_path})")
+        return self._cached_shell, self._cached_shell_path
+
+    def is_elevated(self) -> Tuple[bool, str]:
+        """
+        Check if running with elevated privileges (Admin on Windows, Root on Unix).
+        Returns (is_elevated, label), e.g. (True, "Admin") or (False, "User").
+        """
+        try:
+            if platform.system() == "Windows":
+                is_admin = bool(ctypes.windll.shell32.IsUserAnAdmin())
+                return is_admin, "Admin" if is_admin else "User"
+            else:
+                is_root = (os.geteuid() == 0)
+                return is_root, "Root" if is_root else "User"
+        except Exception as e:
+            logger.debug(f"Elevation detection failed: {e}")
+            return False, "User"
+
+    def get_git_branch(self, path: Optional[Path] = None) -> Optional[str]:
+        """
+        Quickly inspects .git/HEAD in current or ancestor directories to extract the active branch.
+        Does not spawn external git processes, ensuring near-instant performance.
+        """
+        target = (path or Path.cwd()).resolve()
+        for directory in [target] + list(target.parents):
+            git_dir = directory / ".git"
+            if git_dir.is_file():
+                # Git worktree / submodule pointer
+                try:
+                    content = git_dir.read_text(encoding="utf-8").strip()
+                    if content.startswith("gitdir:"):
+                        ref_path = (directory / content.split(":", 1)[1].strip()).resolve()
+                        git_dir = ref_path
+                except Exception:
+                    pass
+
+            if git_dir.is_dir():
+                head_file = git_dir / "HEAD"
+                if head_file.exists():
+                    try:
+                        content = head_file.read_text(encoding="utf-8").strip()
+                        if content.startswith("ref: refs/heads/"):
+                            return content.replace("ref: refs/heads/", "").strip()
+                        elif content:
+                            return content[:7]  # Detached commit hash
+                    except Exception:
+                        pass
+        return None
+
+    def format_cwd(self, path: Optional[Path] = None) -> str:
+        """
+        Formats current working directory, abbreviating home directory to '~'.
+        """
+        p = (path or Path.cwd()).resolve()
+        home = Path.home().resolve()
+        try:
+            rel = p.relative_to(home)
+            return f"~/{rel.as_posix()}" if str(rel) != "." else "~"
+        except ValueError:
+            return str(p)
+
+
+detector = EnvironmentDetector()

kapsel/core/engine.py

@@ -0,0 +1,159 @@
+"""
+Kapsel Core Engine orchestrator.
+Manages state transitions, plugin lifecycle, command dispatching, and execution history.
+"""
+
+from dataclasses import dataclass
+from pathlib import Path
+import time
+from typing import Any, Optional, Tuple
+
+from kapsel.completion.kps.dispatcher import dispatch_kps
+from kapsel.completion.kps.registry import KpsCommandRegistry, get_kps_registry
+from kapsel.core.detector import EnvironmentDetector, detector
+from kapsel.core.executor import CommandExecutor, ExecutionSummary
+from kapsel.core.plugin.hooks import HookType
+from kapsel.i18n import _
+from kapsel.core.plugin.manager import PluginManager
+from kapsel.storage.config import KapselConfig, load_config
+from kapsel.storage.history import HistoryManager
+from kapsel.storage.logger import logger
+
+
+@dataclass
+class DispatchResult:
+    mode: str  # "kps" or "native"
+    raw_input: str
+    translated_cmd: Optional[str]
+    execution: ExecutionSummary
+
+
+class DualStateEngine:
+    """The central brain of Kapsel orchestrating dual-state execution, plugins, and state persistence."""
+
+    def __init__(
+        self,
+        config: Optional[KapselConfig] = None,
+        kps_registry: Optional[KpsCommandRegistry] = None,
+        history_mgr: Optional[HistoryManager] = None,
+        env_detector: Optional[EnvironmentDetector] = None,
+    ):
+        self.config = config or load_config()
+        self.history_mgr = history_mgr or HistoryManager()
+        self.detector = env_detector or detector
+        self.kps_registry = kps_registry or get_kps_registry()
+
+        # Detect host shell
+        self.shell_name, self.shell_path = self.detector.detect_shell()
+        self.is_elevated, self.elevated_label = self.detector.is_elevated()
+
+        # Initialize executor
+        self.executor = CommandExecutor(self.shell_name, self.shell_path)
+
+        # Initialize Plugin Subsystem
+        self.plugin_manager = PluginManager(
+            config=self.config,
+            kps_command_register_fn=self.kps_registry.register,
+            env_detector=self.detector,
+        )
+        self.plugin_manager.load_all_plugins()
+        self.plugin_manager.trigger_hook(HookType.ON_READY)
+
+    def reload(self) -> None:
+        """Reload configuration and refresh plugins."""
+        self.config = load_config()
+        self.plugin_manager.unload_all()
+        self.plugin_manager.load_all_plugins()
+
+    def is_kapsel_mode(self, text: str) -> bool:
+        """Determines if the current text line represents Kapsel Command Mode."""
+        stripped = text.strip()
+        return (
+            stripped in ("kapsel", "kps")
+            or stripped.startswith("kapsel ")
+            or stripped.startswith("kps ")
+        )
+
+    is_kps_mode = is_kapsel_mode
+
+    def dispatch(self, user_input: str) -> DispatchResult:
+        """
+        Dispatches input line either to Plugin Filter, Kapsel Builtin, or Native execution.
+        Records execution duration, status, and history in SQLite history.db.
+        """
+        stripped = user_input.strip()
+        cwd_str = str(Path.cwd())
+        start_time = time.time()
+
+        # 1. Plugin Pre-execution filter (e.g. mapping plugin intercepts and translates)
+        is_filtered, transformed_cmd = self.plugin_manager.filter_command(user_input)
+
+        if is_filtered:
+            mode = "kapsel"
+            cmd_to_run = transformed_cmd
+            exec_summary = self.executor.execute(cmd_to_run)
+            translated_cmd = cmd_to_run
+
+        elif self.is_kapsel_mode(user_input):
+            mode = "kapsel"
+            translated_cmd = None
+
+            # Try dispatching to core/plugin kps/kapsel subcommands
+            t0 = time.perf_counter()
+            handled_code = dispatch_kps(user_input)
+            t1 = time.perf_counter()
+            duration_ms = int((t1 - t0) * 1000)
+
+            if handled_code is not None:
+                exec_summary = ExecutionSummary(
+                    command=user_input,
+                    exit_code=handled_code,
+                    duration_ms=duration_ms,
+                    duration_str=f"{duration_ms}ms",
+                    success=(handled_code == 0),
+                    is_builtin=True,
+                )
+            else:
+                # Not a recognized builtin command
+                msg = _("kapsel: unknown command '{cmd}'. See 'kapsel help'.").format(cmd=user_input)
+                print(msg, file=sys.stderr)
+                exec_summary = ExecutionSummary(
+                    command=user_input,
+                    exit_code=1,
+                    duration_ms=0,
+                    duration_str="0ms",
+                    success=False,
+                    is_builtin=True,
+                )
+
+        else:
+            mode = "native"
+            translated_cmd = None
+            exec_summary = self.executor.execute(user_input)
+
+        # Record to history database
+        self.history_mgr.add_record(
+            command=user_input,
+            translated_cmd=translated_cmd,
+            mode=mode,
+            cwd=cwd_str,
+            shell=self.shell_name,
+            timestamp=start_time,
+            duration_ms=exec_summary.duration_ms,
+            exit_code=exec_summary.exit_code,
+        )
+
+        # Trigger plugin post-execution hook
+        self.plugin_manager.trigger_hook(
+            HookType.ON_AFTER_EXECUTE,
+            command=user_input,
+            exit_code=exec_summary.exit_code,
+            duration_ms=exec_summary.duration_ms,
+        )
+
+        return DispatchResult(
+            mode=mode,
+            raw_input=user_input,
+            translated_cmd=translated_cmd,
+            execution=exec_summary,
+        )