kapsel-cli 0.1.0__py3-none-any.whl

kapsel/core/executor.py

@@ -0,0 +1,200 @@
+"""
+Kapsel command execution subsystem.
+Executes native and translated commands via host shell with timing and exit code capture.
+"""
+
+from dataclasses import dataclass
+import os
+from pathlib import Path
+import subprocess
+import sys
+import time
+from typing import Optional, Tuple
+
+from kapsel.storage.logger import logger
+
+
+@dataclass
+class ExecutionSummary:
+    command: str
+    exit_code: int
+    duration_ms: int
+    duration_str: str
+    success: bool
+    is_builtin: bool = False
+
+
+class CommandExecutor:
+    """Executes commands seamlessly through the host shell with full TUI/TTY passthrough."""
+
+    def __init__(self, shell_name: str = "pwsh", shell_path: Optional[str] = None):
+        self.shell_name = shell_name
+        self.shell_path = shell_path or shell_name
+        self._prev_dir: Optional[Path] = None
+
+    def set_shell(self, shell_name: str, shell_path: Optional[str]) -> None:
+        self.shell_name = shell_name
+        self.shell_path = shell_path or shell_name
+
+    def execute(self, cmd_string: str) -> ExecutionSummary:
+        """
+        Executes a command string.
+        Handles built-ins (cd, exit, clear) and delegates other commands to host shell.
+        """
+        cmd = cmd_string.strip()
+        if not cmd:
+            return ExecutionSummary(command="", exit_code=0, duration_ms=0, duration_str="0ms", success=True)
+
+        # 1. Check built-in commands
+        builtin_result = self._handle_builtin(cmd)
+        if builtin_result is not None:
+            return builtin_result
+
+        # 2. Host shell execution
+        t0 = time.perf_counter()
+        exit_code = 0
+        try:
+            exit_code = self._run_in_host_shell(cmd)
+        except KeyboardInterrupt:
+            print("\n^C")
+            exit_code = 130
+        except Exception as e:
+            logger.error(f"Error executing command '{cmd}': {e}")
+            print(f"Kapsel: execution error: {e}", file=sys.stderr)
+            exit_code = 1
+
+        t1 = time.perf_counter()
+        duration_ms = int((t1 - t0) * 1000)
+        duration_str = self.format_duration(duration_ms)
+
+        return ExecutionSummary(
+            command=cmd,
+            exit_code=exit_code,
+            duration_ms=duration_ms,
+            duration_str=duration_str,
+            success=(exit_code == 0),
+            is_builtin=False,
+        )
+
+    def _handle_builtin(self, cmd: str) -> Optional[ExecutionSummary]:
+        """Intercepts built-ins like cd, clear, cls."""
+        parts = cmd.split()
+        if not parts:
+            return None
+
+        primary = parts[0].lower()
+
+        # Builtin: cd
+        if primary == "cd":
+            t0 = time.perf_counter()
+            exit_code = self._execute_cd(parts[1:] if len(parts) > 1 else [])
+            t1 = time.perf_counter()
+            ms = int((t1 - t0) * 1000)
+            return ExecutionSummary(
+                command=cmd,
+                exit_code=exit_code,
+                duration_ms=ms,
+                duration_str=self.format_duration(ms),
+                success=(exit_code == 0),
+                is_builtin=True,
+            )
+
+        # Check kapsel/kps prefixed commands
+        if primary in ("kapsel", "kps"):
+            from kapsel.completion.kps import dispatch_kps
+            builtin_code = dispatch_kps(cmd)
+            if builtin_code is not None:
+                return ExecutionSummary(
+                    command=cmd,
+                    exit_code=builtin_code,
+                    duration_ms=0,
+                    duration_str="0ms",
+                    success=(builtin_code == 0),
+                    is_builtin=True,
+                )
+
+        # Builtin: clear / cls
+        if primary in ("clear", "cls"):
+            os.system("cls" if os.name == "nt" else "clear")
+            from kapsel.ui.banner import render_banner
+            render_banner()
+            return ExecutionSummary(
+                command=cmd,
+                exit_code=0,
+                duration_ms=0,
+                duration_str="0ms",
+                success=True,
+                is_builtin=True,
+            )
+
+        return None
+
+    def _execute_cd(self, args: list[str]) -> int:
+        current = Path.cwd()
+        if not args or args[0] in ("~", ""):
+            target = Path.home()
+        elif args[0] == "-":
+            if self._prev_dir:
+                target = self._prev_dir
+                print(target)
+            else:
+                print("kapsel: cd: OLDPWD not set", file=sys.stderr)
+                return 1
+        else:
+            # Handle quoted paths or joined arguments if spaces were present
+            raw_path = " ".join(args).strip("\"'")
+            target = Path(raw_path).expanduser()
+            if not target.is_absolute():
+                target = (current / target).resolve()
+
+        try:
+            if not target.exists():
+                print(f"kapsel: cd: {target}: No such file or directory", file=sys.stderr)
+                return 1
+            if not target.is_dir():
+                print(f"kapsel: cd: {target}: Not a directory", file=sys.stderr)
+                return 1
+
+            os.chdir(target)
+            self._prev_dir = current
+            return 0
+        except Exception as e:
+            print(f"kapsel: cd: {e}", file=sys.stderr)
+            return 1
+
+    def _run_in_host_shell(self, cmd: str) -> int:
+        """
+        Runs the command through the detected host shell binary.
+        Inherits stdin, stdout, stderr so interactive CLI programs (vim, fzf, git log) work seamlessly.
+        """
+        shell = self.shell_name.lower()
+        args = []
+
+        if shell in ("pwsh", "powershell"):
+            # PowerShell: execute via -NoLogo -Command
+            exe = self.shell_path if self.shell_path and Path(self.shell_path).exists() else (
+                "pwsh.exe" if shell == "pwsh" else "powershell.exe"
+            )
+            args = [exe, "-NoLogo", "-Command", cmd]
+        elif shell == "cmd":
+            exe = self.shell_path if self.shell_path and Path(self.shell_path).exists() else "cmd.exe"
+            args = [exe, "/c", cmd]
+        else:
+            # Unix shells (bash, zsh, fish, sh)
+            exe = self.shell_path if self.shell_path and Path(self.shell_path).exists() else "/bin/sh"
+            args = [exe, "-c", cmd]
+
+        # Use subprocess.run without pipes so it directly controls terminal TTY / console
+        proc = subprocess.run(args, shell=False)
+        return proc.returncode
+
+    @staticmethod
+    def format_duration(ms: int) -> str:
+        if ms < 1000:
+            return f"{ms}ms"
+        secs = ms / 1000.0
+        if secs < 60:
+            return f"{secs:.2f}s"
+        mins = int(secs // 60)
+        rem_secs = secs % 60
+        return f"{mins}m {rem_secs:.1f}s"

kapsel/core/i18n.py

@@ -0,0 +1,31 @@
+"""
+Backwards-compatibility forwarder for kapsel.i18n.
+"""
+
+from kapsel.i18n import (
+    DEFAULT_LANGUAGE,
+    DOMAIN,
+    SUPPORTED_LANGUAGES,
+    _,
+    detect_system_language,
+    get_current_language,
+    get_locales_dir,
+    get_translation,
+    ngettext,
+    normalize_language_code,
+    set_current_language,
+)
+
+__all__ = [
+    "DEFAULT_LANGUAGE",
+    "DOMAIN",
+    "SUPPORTED_LANGUAGES",
+    "_",
+    "ngettext",
+    "detect_system_language",
+    "get_current_language",
+    "get_locales_dir",
+    "get_translation",
+    "normalize_language_code",
+    "set_current_language",
+]

kapsel/core/plugin/__init__.py

@@ -0,0 +1,17 @@
+"""
+Kapsel Plugin System.
+Exposes base classes, metadata schemas, hooks, and manager.
+"""
+
+from kapsel.core.plugin.base import KapselPlugin, PluginManifest
+from kapsel.core.plugin.context import PluginContext
+from kapsel.core.plugin.hooks import HookType
+from kapsel.core.plugin.manager import PluginManager
+
+__all__ = [
+    "KapselPlugin",
+    "PluginManifest",
+    "PluginContext",
+    "HookType",
+    "PluginManager",
+]

kapsel/core/plugin/base.py

@@ -0,0 +1,53 @@
+"""
+Kapsel Plugin System - Base Specification.
+Defines the core abstract plugin interface and metadata models.
+"""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from typing import TYPE_CHECKING, Any, Dict, List, Optional
+
+if TYPE_CHECKING:
+    from kapsel.core.plugin.context import PluginContext
+
+
+@dataclass
+class PluginManifest:
+    """Metadata describing a Kapsel plugin."""
+    id: str
+    name: str
+    version: str
+    description: str = ""
+    author: str = ""
+    homepage: str = ""
+    min_kapsel_version: str = "0.1.0"
+    dependencies: List[str] = field(default_factory=list)
+    tags: List[str] = field(default_factory=list)
+
+
+class KapselPlugin(ABC):
+    """
+    Abstract base class that all Kapsel plugins must inherit from.
+    """
+    manifest: PluginManifest
+
+    def __init__(self, manifest: Optional[PluginManifest] = None):
+        if manifest:
+            self.manifest = manifest
+        elif not hasattr(self, "manifest"):
+            raise ValueError(f"Plugin {self.__class__.__name__} must define a manifest.")
+
+    @abstractmethod
+    def on_load(self, context: "PluginContext") -> None:
+        """
+        Called when the plugin is loaded into the Kapsel engine.
+        Use this method to register kps commands, hooks, and initialize state.
+        """
+        pass
+
+    def on_unload(self) -> None:
+        """
+        Called when the plugin is being unloaded or Kapsel is shutting down.
+        Clean up resources, open files, or network connections here.
+        """
+        pass

kapsel/core/plugin/catalog.py

@@ -0,0 +1,187 @@
+"""
+Kapsel Plugin System - Catalog & Discovery Engine.
+Manages repository subcommands dictionary and handles 'kapsel add update'.
+All comments and descriptions are in English.
+"""
+
+import json
+from pathlib import Path
+import re
+from typing import Dict, Optional
+from rich.console import Console
+from rich.table import Table
+
+from kapsel.storage.config import get_kapsel_dir
+
+
+DEFAULT_CATALOG: Dict[str, str] = {
+    "update": "Scan and update available plugin catalog and completion dictionary",
+    "ai": "Terminal AI assistant and setup wizard (aichat)",
+    "alias": "Cross-platform Linux command alias mapper",
+    "autopilot": "Background task queue and autonomous execution (Pueue)",
+    "fuck": "Intelligent console command error correction (thefuck)",
+    "help": "Fast interactive command cheat sheets (tealdeer)",
+    "install": "Unified cross-platform package manager (mpm)",
+    "profile": "Dotfiles and workspace sync roaming (chezmoi)",
+    "rec": "Snippet recorder and interactive runner (pet)",
+}
+
+
+def _resolve_catalog_paths():
+    """Returns candidate paths for catalog.json in order of priority."""
+    paths = []
+    # 1. Local workspace plugins folder
+    workspace_catalog = Path.cwd() / "plugins" / "catalog.json"
+    paths.append(workspace_catalog)
+
+    # 2. Global runtime data directory
+    global_catalog = get_kapsel_dir() / "plugins_catalog.json"
+    paths.append(global_catalog)
+
+    global_in_plugins = get_kapsel_dir() / "plugins" / "catalog.json"
+    paths.append(global_in_plugins)
+
+    return paths
+
+
+def load_plugin_catalog() -> Dict[str, str]:
+    """
+    Loads the subcommands dictionary from catalog.json in the repository or runtime data directory.
+    Falls back to scanning plugins/ or default catalog if not found.
+    """
+    for candidate in _resolve_catalog_paths():
+        if candidate.exists() and candidate.is_file():
+            try:
+                data = json.loads(candidate.read_text(encoding="utf-8"))
+                if isinstance(data, dict):
+                    # Ensure 'update' entry is always present
+                    data.setdefault("update", "Scan and update available plugin catalog and completion dictionary")
+                    return data
+            except Exception:
+                pass
+
+    # If file not present yet, return default catalog
+    return dict(DEFAULT_CATALOG)
+
+
+def _extract_plugin_description(plugin_dir: Path) -> str:
+    """Extracts a human-readable description for a plugin from manifest, pyproject.toml, or docstring."""
+    plugin_name = plugin_dir.name
+
+    # 1. Try reading manifest in plugin.py
+    plugin_py = plugin_dir / "plugin.py"
+    if plugin_py.exists():
+        try:
+            content = plugin_py.read_text(encoding="utf-8", errors="ignore")
+            m = re.search(r'description\s*=\s*["\']([^"\']+)["\']', content)
+            if m:
+                return m.group(1).strip()
+        except Exception:
+            pass
+
+    # 2. Try pyproject.toml
+    pyproject = plugin_dir / "pyproject.toml"
+    if pyproject.exists():
+        try:
+            content = pyproject.read_text(encoding="utf-8", errors="ignore")
+            m = re.search(r'description\s*=\s*["\']([^"\']+)["\']', content)
+            if m:
+                return m.group(1).strip()
+        except Exception:
+            pass
+
+    # 3. Try __init__.py docstring
+    init_py = plugin_dir / "__init__.py"
+    if init_py.exists():
+        try:
+            content = init_py.read_text(encoding="utf-8", errors="ignore")
+            doc_m = re.search(r'"""(.*?)"""', content, re.DOTALL)
+            if doc_m:
+                first_line = doc_m.group(1).strip().split("\n")[0].strip()
+                if first_line:
+                    return first_line
+        except Exception:
+            pass
+
+    return f"Plugin: {plugin_name}"
+
+
+def update_plugin_catalog(console: Optional[Console] = None) -> Dict[str, str]:
+    """
+    Scans the repository plugins/ folder, extracts plugin metadata,
+    updates catalog.json, and refreshes the in-memory command registry.
+    """
+    con = console or Console(legacy_windows=False)
+    catalog: Dict[str, str] = {
+        "update": "Scan and update available plugin catalog and completion dictionary"
+    }
+
+    # Search directories to scan
+    scan_dirs = []
+    workspace_plugins = Path.cwd() / "plugins"
+    if workspace_plugins.exists() and workspace_plugins.is_dir():
+        scan_dirs.append(workspace_plugins)
+
+    global_plugins = get_kapsel_dir() / "plugins"
+    if global_plugins.exists() and global_plugins.is_dir() and global_plugins not in scan_dirs:
+        scan_dirs.append(global_plugins)
+
+    discovered = 0
+    for s_dir in scan_dirs:
+        for item in sorted(s_dir.iterdir()):
+            if item.is_dir() and not item.name.startswith((".", "_")):
+                p_name = item.name.lower()
+                if p_name not in catalog:
+                    desc = _extract_plugin_description(item)
+                    catalog[p_name] = desc
+                    discovered += 1
+
+    # Save to workspace plugins/catalog.json if workspace plugins directory exists
+    if workspace_plugins.exists() and workspace_plugins.is_dir():
+        target_file = workspace_plugins / "catalog.json"
+        try:
+            target_file.write_text(json.dumps(catalog, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+        except Exception as e:
+            con.print(f"[yellow]Warning: Failed to write {target_file}:[/] {e}")
+
+    # Also save to global data directory cache
+    global_cache = get_kapsel_dir() / "plugins_catalog.json"
+    try:
+        global_cache.parent.mkdir(parents=True, exist_ok=True)
+        global_cache.write_text(json.dumps(catalog, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+    except Exception as e:
+        con.print(f"[yellow]Warning: Failed to write global cache {global_cache}:[/] {e}")
+
+    # Hot-reload in-memory registry subcommands for 'add' command
+    try:
+        from kapsel.completion.kps.registry import get_kps_registry
+        reg = get_kps_registry()
+        add_cmd = reg.get("add")
+        if add_cmd:
+            add_cmd.subcommands = dict(catalog)
+    except Exception:
+        pass
+
+    return catalog
+
+
+def render_catalog_table(catalog: Dict[str, str], console: Console) -> None:
+    """Renders the plugin catalog as a modern terminal table."""
+    table = Table(
+        title="[bold #00f0ff]📦 Kapsel Plugin Catalog (Subcommands Dictionary)[/]",
+        border_style="#0891b2",
+        header_style="bold #00f0ff",
+        show_header=True,
+    )
+    table.add_column("Command / Plugin", style="bold #a855f7", width=18)
+    table.add_column("Description", style="white")
+
+    for name, desc in catalog.items():
+        if name == "update":
+            table.add_row(f"[bold #10b981]{name}[/]", f"[dim italic]{desc}[/]")
+        else:
+            table.add_row(name, desc)
+
+    console.print()
+    console.print(table)
+    console.print(f"[dim]Total items: {len(catalog)} | Run [bold #00f0ff]kapsel add <plugin>[/] to enable any plugin.[/]\n")

kapsel/core/plugin/context.py

@@ -0,0 +1,71 @@
+"""
+Kapsel Plugin System - Context API.
+Provides controlled and safe access to host core services for plugins.
+"""
+
+from pathlib import Path
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+from kapsel.core.detector import EnvironmentDetector, detector
+from kapsel.core.plugin.hooks import HookType
+from kapsel.storage.config import KapselConfig
+from kapsel.storage.logger import logger
+
+
+class PluginContext:
+    """
+    The Host API context provided to a plugin during `on_load(context)`.
+    Enforces security boundaries and structured extension registration.
+    """
+
+    def __init__(
+        self,
+        plugin_id: str,
+        config: KapselConfig,
+        hook_registry: Dict[HookType, List[Callable]],
+        kps_command_register_fn: Callable[..., Any],
+        env_detector: Optional[EnvironmentDetector] = None,
+    ):
+        self.plugin_id = plugin_id
+        self._config = config
+        self._hook_registry = hook_registry
+        self._kps_command_register_fn = kps_command_register_fn
+        self.environment = env_detector or detector
+        self.logger = logger
+
+    @property
+    def plugin_data_dir(self) -> Path:
+        """Isolated persistent directory for this plugin to store files."""
+        base_dir = self._config.get_data_dir() / "plugins_data" / self.plugin_id
+        base_dir.mkdir(parents=True, exist_ok=True)
+        return base_dir
+
+    def register_kps_command(
+        self,
+        name: str,
+        handler: Callable[..., Optional[int]],
+        help_text: str,
+        subcommands: Optional[Dict[str, str]] = None,
+        usage: Optional[str] = None,
+        scope: str = "feature",
+    ) -> None:
+        """
+        Registers a new functional 'kps <name>' command (or system command if scope='system').
+        Automatically exposes it to autocompletion and CLI dispatching.
+        """
+        self._kps_command_register_fn(
+            name=name,
+            handler=handler,
+            help_text=help_text,
+            subcommands=subcommands,
+            usage=usage,
+            plugin_id=self.plugin_id,
+            scope=scope,
+        )
+
+    def register_hook(self, hook_type: HookType, callback: Callable) -> None:
+        """Registers an extension callback hook."""
+        if hook_type not in self._hook_registry:
+            self._hook_registry[hook_type] = []
+        self._hook_registry[hook_type].append(callback)
+        self.logger.debug(f"[Plugin:{self.plugin_id}] Hook registered: {hook_type.value}")

kapsel/core/plugin/hooks.py

@@ -0,0 +1,34 @@
+"""
+Kapsel Plugin System - Hooks Specification.
+Defines standard extension hook types and callback signatures.
+"""
+
+from enum import Enum
+from typing import Any, Callable, Dict, List, Optional, Tuple
+
+
+class HookType(str, Enum):
+    """Available extension hook points in Kapsel Core."""
+    # Triggered when core is ready, before user prompt
+    ON_READY = "on_ready"
+
+    # Injects extra completion candidates into prompt completion
+    # Signature: (text_before_cursor: str) -> List[dict]
+    # dict format: {"text": str, "display": str, "display_meta": str}
+    PROVIDE_COMPLETIONS = "provide_completions"
+
+    # Pre-execution filter/transformer (e.g. command translation/routing)
+    # Signature: (raw_command: str) -> Tuple[bool, str]
+    # Returns (is_handled, transformed_command)
+    FILTER_COMMAND = "filter_command"
+
+    # Triggered immediately before executing a command
+    # Signature: (command: str) -> None
+    ON_BEFORE_EXECUTE = "on_before_execute"
+
+    # Triggered after executing a command (e.g. for cloud sync or metrics)
+    # Signature: (command: str, exit_code: int, duration_ms: float) -> None
+    ON_AFTER_EXECUTE = "on_after_execute"
+
+    # Triggered during shell exit / cleanup
+    ON_SHUTDOWN = "on_shutdown"