kapsel-cli 0.1.0__py3-none-any.whl

kapsel/completion/fig_engine.py

@@ -0,0 +1,215 @@
+"""
+Fig Completion Engine.
+AST context walker and token stream parser for Fig.Spec definitions.
+Supports deep multi-level subcommands (e.g. 'docker compose up'),
+flags/options (-f, --flag), and descriptions.
+"""
+
+import json
+from pathlib import Path
+import shlex
+from typing import Any, Dict, List, Optional, Tuple, Union
+
+from kapsel.completion.fig_schema import (
+    FigOption,
+    FigSpec,
+    FigSubcommand,
+    parse_fig_spec,
+)
+from kapsel.storage.logger import get_kapsel_dir, logger
+
+BUILTIN_SPECS_DIR = Path(__file__).parent / "specs"
+
+
+def get_user_specs_dir() -> Path:
+    d = get_kapsel_dir() / "registry" / "specs"
+    d.mkdir(parents=True, exist_ok=True)
+    return d
+
+
+class FigCandidate:
+    def __init__(self, insert_text: str, display_text: str, description: str, kind: str = "subcommand"):
+        self.insert_text = insert_text
+        self.display_text = display_text
+        self.description = description
+        self.kind = kind  # "subcommand" | "option" | "arg"
+
+    def __repr__(self):
+        return f"<FigCandidate {self.insert_text} ({self.kind}): {self.description}>"
+
+
+class FigEngine:
+    """
+    Main Fig-compatible completion engine.
+    Pre-indexes all available Fig.Spec JSON definitions and evaluates
+    current command line token streams with sub-millisecond response.
+    """
+
+    def __init__(self):
+        self._specs: Dict[str, FigSpec] = {}
+        self.reload_specs()
+
+    def reload_specs(self) -> None:
+        """Loads all builtin and user-defined Fig.Spec JSON files."""
+        specs = {}
+
+        # 1. Built-in specs
+        if BUILTIN_SPECS_DIR.exists():
+            for f in BUILTIN_SPECS_DIR.glob("*.json"):
+                try:
+                    with open(f, "r", encoding="utf-8") as fp:
+                        data = json.load(fp)
+                        spec = parse_fig_spec(data)
+                        specs[spec.name.lower()] = spec
+                except Exception as e:
+                    logger.error(f"Failed to parse builtin Fig spec {f}: {e}")
+
+        # 2. User/Community custom specs in ~/.kapsel/registry/specs/
+        user_dir = get_user_specs_dir()
+        for f in user_dir.glob("*.json"):
+            try:
+                with open(f, "r", encoding="utf-8") as fp:
+                    data = json.load(fp)
+                    spec = parse_fig_spec(data)
+                    specs[spec.name.lower()] = spec
+            except Exception as e:
+                logger.error(f"Failed to parse user Fig spec {f}: {e}")
+
+        self._specs = specs
+
+    def has_spec_for_tool(self, tool: str) -> bool:
+        return tool.lower() in self._specs
+
+    def list_known_tools(self) -> List[str]:
+        return sorted(self._specs.keys())
+
+    def get_spec(self, tool: str) -> Optional[FigSpec]:
+        return self._specs.get(tool.lower())
+
+    def tokenize_line(self, line: str) -> Tuple[List[str], str]:
+        """
+        Tokenizes command line before cursor.
+        Returns (completed_tokens, current_partial_token).
+        e.g. "git commit -m" -> (["git", "commit"], "-m")
+        e.g. "git commit "   -> (["git", "commit"], "")
+        """
+        if not line:
+            return [], ""
+
+        ends_with_space = line.endswith(" ")
+
+        # Use split preserving empty trailing if space
+        raw_tokens = line.split()
+        if ends_with_space:
+            return raw_tokens, ""
+        else:
+            if not raw_tokens:
+                return [], ""
+            return raw_tokens[:-1], raw_tokens[-1]
+
+    def get_completions(self, line_before_cursor: str) -> List[FigCandidate]:
+        """
+        Core evaluation algorithm:
+        Walks the Fig.Spec AST based on input tokens and returns context-relevant candidates.
+        """
+        completed, partial = self.tokenize_line(line_before_cursor)
+
+        if not completed and not partial:
+            return []
+
+        # If user is at the very first token (the root CLI command, e.g. "gi" -> "git")
+        if not completed:
+            results = []
+            prefix = partial.lower()
+            for tool_name, spec in self._specs.items():
+                if tool_name.startswith(prefix):
+                    results.append(
+                        FigCandidate(
+                            insert_text=tool_name,
+                            display_text=tool_name,
+                            description=spec.description,
+                            kind="subcommand",
+                        )
+                    )
+            return results
+
+        root_cmd = completed[0].lower()
+        spec = self.get_spec(root_cmd)
+        if not spec:
+            return []
+
+        # AST Context Traversal
+        current_subcommands = spec.subcommands
+        available_options: List[FigOption] = list(spec.options)
+
+        # Tokens after the root command
+        sub_tokens = completed[1:]
+
+        for tok in sub_tokens:
+            tok_lower = tok.lower()
+
+            # Check if this token matches a subcommand
+            matched_sub: Optional[FigSubcommand] = None
+            for sc in current_subcommands:
+                if tok_lower in [n.lower() for n in sc.name]:
+                    matched_sub = sc
+                    break
+
+            if matched_sub:
+                # Descend down AST
+                current_subcommands = matched_sub.subcommands
+                # Add options from this subcommand
+                available_options.extend(matched_sub.options)
+            else:
+                # Token was an option or argument, skip descending subcommands
+                pass
+
+        candidates: List[FigCandidate] = []
+        prefix = partial.lower()
+        seen_insert_texts = set()
+
+        # 1. If user is not specifically typing a flag ('-'), show Subcommands FIRST
+        if not partial.startswith("-"):
+            for sc in current_subcommands:
+                primary = sc.primary_name
+                if primary.lower().startswith(prefix) and primary not in seen_insert_texts:
+                    seen_insert_texts.add(primary)
+                    candidates.append(
+                        FigCandidate(
+                            insert_text=primary,
+                            display_text=primary,
+                            description=sc.description,
+                            kind="subcommand",
+                        )
+                    )
+
+        # 2. Evaluate Options (Flags)
+        # If user typed '-', show only options matching the flag prefix
+        # If user didn't type '-', show options below subcommands if prefix is empty
+        if partial.startswith("-") or partial == "":
+            for opt in available_options:
+                matched_names = [n for n in opt.name if n.lower().startswith(prefix)]
+                for opt_name in matched_names:
+                    if opt_name not in seen_insert_texts:
+                        seen_insert_texts.add(opt_name)
+                        candidates.append(
+                            FigCandidate(
+                                insert_text=opt_name,
+                                display_text=opt.display_names,
+                                description=opt.description,
+                                kind="option",
+                            )
+                        )
+
+        return candidates
+
+
+# Singleton engine instance
+_FIG_ENGINE: Optional[FigEngine] = None
+
+
+def get_fig_engine() -> FigEngine:
+    global _FIG_ENGINE
+    if _FIG_ENGINE is None:
+        _FIG_ENGINE = FigEngine()
+    return _FIG_ENGINE

kapsel/completion/fig_schema.py

@@ -0,0 +1,135 @@
+"""
+Fig.Spec declarative schema data models.
+100% aligned with withfig/autocomplete (and Amazon Q Developer CLI) schema:
+Spec -> Subcommands -> Options (Flags) -> Arguments
+"""
+
+from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional, Union
+
+
+@dataclass
+class FigArg:
+    name: str = ""
+    description: str = ""
+    is_optional: bool = False
+    is_variadic: bool = False
+    suggestions: List[str] = field(default_factory=list)
+
+
+@dataclass
+class FigOption:
+    name: List[str] = field(default_factory=list)  # e.g. ["-m", "--message"]
+    description: str = ""
+    args: Optional[FigArg] = None
+    is_persistent: bool = False
+
+    @property
+    def primary_name(self) -> str:
+        return self.name[0] if self.name else ""
+
+    @property
+    def display_names(self) -> str:
+        return ", ".join(self.name)
+
+
+@dataclass
+class FigSubcommand:
+    name: List[str] = field(default_factory=list)  # e.g. ["commit"] or ["checkout", "co"]
+    description: str = ""
+    subcommands: List["FigSubcommand"] = field(default_factory=list)
+    options: List[FigOption] = field(default_factory=list)
+    args: Optional[List[FigArg]] = None
+
+    @property
+    def primary_name(self) -> str:
+        return self.name[0] if self.name else ""
+
+
+@dataclass
+class FigSpec:
+    name: str = ""
+    description: str = ""
+    subcommands: List[FigSubcommand] = field(default_factory=list)
+    options: List[FigOption] = field(default_factory=list)
+    args: Optional[List[FigArg]] = None
+
+
+def parse_fig_arg(raw: Any) -> Optional[FigArg]:
+    if not raw:
+        return None
+    if isinstance(raw, str):
+        return FigArg(name=raw)
+    if isinstance(raw, dict):
+        return FigArg(
+            name=raw.get("name", ""),
+            description=raw.get("description", ""),
+            is_optional=raw.get("isOptional", False),
+            is_variadic=raw.get("isVariadic", False),
+            suggestions=raw.get("suggestions", []),
+        )
+    return None
+
+
+def parse_fig_option(raw: Dict[str, Any]) -> FigOption:
+    raw_name = raw.get("name", [])
+    if isinstance(raw_name, str):
+        names = [raw_name]
+    elif isinstance(raw_name, list):
+        names = [str(n) for n in raw_name]
+    else:
+        names = []
+
+    arg_data = raw.get("args")
+    parsed_arg = parse_fig_arg(arg_data)
+
+    return FigOption(
+        name=names,
+        description=raw.get("description", ""),
+        args=parsed_arg,
+        is_persistent=raw.get("isPersistent", False),
+    )
+
+
+def parse_fig_subcommand(raw: Dict[str, Any]) -> FigSubcommand:
+    raw_name = raw.get("name", [])
+    if isinstance(raw_name, str):
+        names = [raw_name]
+    elif isinstance(raw_name, list):
+        names = [str(n) for n in raw_name]
+    else:
+        names = []
+
+    subcmds = [parse_fig_subcommand(s) for s in raw.get("subcommands", []) if isinstance(s, dict)]
+    opts = [parse_fig_option(o) for o in raw.get("options", []) if isinstance(o, dict)]
+
+    raw_args = raw.get("args")
+    parsed_args = None
+    if isinstance(raw_args, list):
+        parsed_args = [parse_fig_arg(a) for a in raw_args if a]
+    elif isinstance(raw_args, (dict, str)):
+        parsed_args = [parse_fig_arg(raw_args)]
+
+    return FigSubcommand(
+        name=names,
+        description=raw.get("description", ""),
+        subcommands=subcmds,
+        options=opts,
+        args=parsed_args,
+    )
+
+
+def parse_fig_spec(raw: Dict[str, Any]) -> FigSpec:
+    name = raw.get("name", "")
+    if isinstance(name, list):
+        name = name[0] if name else ""
+
+    subcmds = [parse_fig_subcommand(s) for s in raw.get("subcommands", []) if isinstance(s, dict)]
+    opts = [parse_fig_option(o) for o in raw.get("options", []) if isinstance(o, dict)]
+
+    return FigSpec(
+        name=str(name),
+        description=raw.get("description", ""),
+        subcommands=subcmds,
+        options=opts,
+    )

kapsel/completion/importer.py

@@ -0,0 +1,92 @@
+"""
+Fig Spec Importer & Converter Service.
+Fetches and converts completion specs from withfig/autocomplete (or local files)
+directly into Kapsel Fig.Spec JSON format.
+"""
+
+import json
+from pathlib import Path
+import re
+import sys
+from typing import Optional
+import urllib.request
+
+GITHUB_RAW_BASE = "https://raw.githubusercontent.com/withfig/autocomplete/master/src"
+
+
+def fetch_remote_ts_spec(tool_name: str) -> Optional[str]:
+    url = f"{GITHUB_RAW_BASE}/{tool_name}.ts"
+    try:
+        req = urllib.request.Request(
+            url,
+            headers={"User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) Kapsel/0.2.0"},
+        )
+        with urllib.request.urlopen(req, timeout=10) as resp:
+            if resp.status == 200:
+                return resp.read().decode("utf-8")
+    except Exception:
+        pass
+    return None
+
+
+def parse_simple_ts_to_dict(tool_name: str, ts_content: str) -> dict:
+    """
+    Parses common Fig TypeScript completionSpec patterns into a clean JSON dict.
+    Extracts name, description, subcommands, options.
+    """
+    spec = {
+        "name": tool_name,
+        "description": f"{tool_name} command line tool",
+        "options": [],
+        "subcommands": [],
+    }
+
+    # Extract top-level description
+    desc_match = re.search(r'description:\s*["\']([^"\']+)["\']', ts_content)
+    if desc_match:
+        spec["description"] = desc_match.group(1)
+
+    # Extract subcommands: e.g. { name: "commit", description: "..." }
+    subcmd_blocks = re.findall(
+        r'\{\s*name:\s*["\']([a-zA-Z0-9_\-]+)["\'],\s*description:\s*["\']([^"\']+)["\']',
+        ts_content,
+    )
+    for name, desc in subcmd_blocks:
+        spec["subcommands"].append({
+            "name": name,
+            "description": desc,
+            "options": [],
+        })
+
+    # Extract options: name: ["-f", "--flag"] or name: "--flag"
+    opt_blocks = re.findall(
+        r'name:\s*(?:\[([^\]]+)\]|["\']([^"\']+)["\'])\s*,\s*description:\s*["\']([^"\']+)["\']',
+        ts_content,
+    )
+    for names_arr, single_name, desc in opt_blocks:
+        if names_arr:
+            names = [n.strip().strip('"\'') for n in names_arr.split(",") if n.strip()]
+        else:
+            names = [single_name]
+        spec["options"].append({
+            "name": names,
+            "description": desc,
+        })
+
+    return spec
+
+
+def import_fig_spec(tool_name: str, output_dir: Path) -> bool:
+    output_dir.mkdir(parents=True, exist_ok=True)
+    out_file = output_dir / f"{tool_name.lower()}.json"
+
+    ts_content = fetch_remote_ts_spec(tool_name)
+    if not ts_content:
+        return False
+
+    spec_data = parse_simple_ts_to_dict(tool_name, ts_content)
+
+    with open(out_file, "w", encoding="utf-8") as f:
+        json.dump(spec_data, f, ensure_ascii=False, indent=2)
+
+    return True

kapsel/completion/kps/__init__.py

@@ -0,0 +1,18 @@
+"""
+Kapsel Command Subsystem.
+Integrates command registration and dispatching with autocompletion.
+"""
+
+from kapsel.completion.kps.dispatcher import dispatch_kps
+from kapsel.completion.kps.registry import (
+    KpsCommand,
+    KpsCommandRegistry,
+    get_kps_registry,
+)
+
+__all__ = [
+    "KpsCommand",
+    "KpsCommandRegistry",
+    "get_kps_registry",
+    "dispatch_kps",
+]

kapsel/completion/kps/builtins/__init__.py

@@ -0,0 +1,92 @@
+"""
+Kapsel Core Built-in Commands Registration.
+Registers fundamental core commands: help, status, config, datadir, add, toggle.
+These can be invoked interchangeably via 'kapsel <cmd>' or 'kps <cmd>'.
+All comments and descriptions are in English.
+"""
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from kapsel.completion.kps.registry import KpsCommandRegistry
+
+
+def register_builtins(registry: "KpsCommandRegistry") -> None:
+    """Registers core commands into the KpsCommandRegistry."""
+    from kapsel.completion.kps.builtins.add import handle_add_command
+    from kapsel.completion.kps.builtins.config import handle_config_command
+    from kapsel.completion.kps.builtins.datadir import handle_datadir_command
+    from kapsel.completion.kps.builtins.help import handle_help
+    from kapsel.completion.kps.builtins.language import handle_language_command
+    from kapsel.completion.kps.builtins.status import handle_status
+    from kapsel.completion.kps.builtins.toggle import handle_toggle_command
+
+    # 1. help
+    registry.register(
+        name="help",
+        handler=handle_help,
+        help_text="Display Kapsel manual, interaction mechanisms, and command cheatsheet",
+        usage="kapsel help (or kps help)",
+    )
+
+    # 2. status
+    registry.register(
+        name="status",
+        handler=handle_status,
+        help_text="Display OS environment, active shell, Git branch, and sandbox status",
+        usage="kapsel status (or kps status)",
+    )
+
+    # 3. config
+    registry.register(
+        name="config",
+        handler=handle_config_command,
+        help_text="View or modify core configuration in config.yaml",
+        subcommands={
+            "path": "Print physical configuration file path",
+            "edit": "Open configuration in default external editor",
+            "get": "Read configuration value for a key",
+            "set": "Update configuration value for a key",
+            "reload": "Hot-reload configuration from disk",
+        },
+        usage="kapsel config [path|edit|get|set|reload]",
+    )
+
+    # 4. datadir
+    registry.register(
+        name="datadir",
+        handler=handle_datadir_command,
+        help_text="Inspect or relocate data storage sandbox directory",
+        subcommands={
+            "status": "Show current data directory and stats",
+            "path": "Print current data directory path",
+        },
+        usage="kapsel datadir [path]",
+    )
+
+    # 5. add <plugin_name>
+    from kapsel.core.plugin.catalog import load_plugin_catalog
+
+    registry.register(
+        name="add",
+        handler=handle_add_command,
+        help_text="Enable and register a plugin into Kapsel environment (e.g. kapsel add autopilot)",
+        subcommands=load_plugin_catalog(),
+        usage="kapsel add <plugin_name> (or: kapsel add update)",
+    )
+
+    # 6. toggle
+    registry.register(
+        name="toggle",
+        handler=handle_toggle_command,
+        help_text="Toggle Kapsel as default terminal mode (open on first call, close on second)",
+        usage="kapsel toggle (or kps toggle)",
+    )
+
+    # 7. language
+    registry.register(
+        name="language",
+        handler=handle_language_command,
+        help_text="View and switch active UI language (en, zh_CN, ja, es, fr, de, ru)",
+        usage="kapsel language [en|zh_CN|ja|es|fr|de|ru]",
+    )

kapsel/completion/kps/builtins/add.py

@@ -0,0 +1,121 @@
+"""
+Kapsel System Command: 'kapsel add <plugin_name>'.
+Enables and registers plugins into the Kapsel environment.
+Executes plugin-specific install.py scripts if provided by the plugin.
+All comments and descriptions are in English.
+"""
+
+import importlib.util
+from pathlib import Path
+import shutil
+import sys
+from typing import List, Optional
+from rich.console import Console
+from rich.panel import Panel
+
+from kapsel.storage.config import get_kapsel_dir, load_config, update_config_value
+from kapsel.ui.banner import ensure_utf8_io
+
+
+def handle_add_command(args: List[str], console: Optional[Console] = None) -> int:
+    """
+    Handles 'kapsel add <plugin_name>' system command.
+    Enables local plugins, triggers their standalone install.py, and registers them into config.yaml.
+    """
+    ensure_utf8_io()
+    con = console or Console(legacy_windows=False)
+
+    if not args:
+        con.print("[bold #f43f5e]Error:[/] Please specify a plugin name to add.")
+        con.print("[dim]Usage: kapsel add <plugin_name> (e.g. kapsel add install)[/]\n")
+        return 1
+
+    target_raw = args[0].strip()
+
+    # Handle 'kapsel add update' to scan and refresh catalog subcommands dictionary
+    if target_raw.lower() == "update":
+        from kapsel.core.plugin.catalog import update_plugin_catalog, render_catalog_table
+        con.print("[bold #00f0ff]🔄 Scanning repository plugins and updating catalog dictionary...[/]")
+        updated_catalog = update_plugin_catalog(con)
+        render_catalog_table(updated_catalog, con)
+        con.print("[bold #10b981]✔ Plugin catalog and subcommands completion dictionary successfully updated![/]\n")
+        return 0
+
+    source_path = Path(target_raw).expanduser()
+
+    global_plugins_dir = get_kapsel_dir() / "plugins"
+    global_plugins_dir.mkdir(parents=True, exist_ok=True)
+
+    # Determine plugin ID and source
+    if source_path.exists() and source_path.is_dir():
+        # User specified an explicit directory path (e.g. kapsel add ./plugins/install or /path/to/my-plugin)
+        target_name = source_path.name.lower()
+        dest_plugin_dir = global_plugins_dir / target_name
+
+        # Verify source has __init__.py
+        if not (source_path / "__init__.py").exists():
+            con.print(f"[bold #f43f5e]Error:[/] Source directory '{source_path}' does not contain '__init__.py'.")
+            return 1
+
+        # Install / sync to user global plugin directory
+        shutil.copytree(source_path, dest_plugin_dir, dirs_exist_ok=True)
+        plugin_dir = dest_plugin_dir
+
+    else:
+        # User specified a plugin name (e.g. kapsel add install)
+        target_name = target_raw.lower()
+        dest_plugin_dir = global_plugins_dir / target_name
+        dev_plugin_dir = Path.cwd() / "plugins" / target_name
+
+        if dev_plugin_dir.exists() and dev_plugin_dir.is_dir() and (dev_plugin_dir / "__init__.py").exists():
+            # If present in local dev directory, automatically sync / update it to global user directory
+            shutil.copytree(dev_plugin_dir, dest_plugin_dir, dirs_exist_ok=True)
+            plugin_dir = dest_plugin_dir
+        elif dest_plugin_dir.exists() and dest_plugin_dir.is_dir():
+            plugin_dir = dest_plugin_dir
+        else:
+            con.print(f"[bold #f43f5e]Error:[/] Plugin '[white]{target_name}[/]' not found in global plugin directory.")
+            con.print(f"[dim]Expected location:[/] {dest_plugin_dir}")
+            con.print("[dim]To install a plugin, specify its local path or place it into your global plugins directory.[/]\n")
+            return 1
+
+    # Verify that the final plugin directory contains __init__.py
+    if not (plugin_dir / "__init__.py").exists():
+        con.print(f"[bold #f43f5e]Error:[/] Plugin directory '{plugin_dir}' does not contain a valid '__init__.py'.")
+        return 1
+
+    # Add to config.yaml enabled plugins list
+    cfg = load_config()
+    current_enabled = cfg.enabled_plugins
+    if target_name not in current_enabled:
+        new_enabled = current_enabled + [target_name]
+        update_config_value("plugins", "enabled", new_enabled)
+
+    # Decoupled plugin dependency installation:
+    # Trigger standalone install.py if provided by the plugin
+    install_script = plugin_dir / "install.py"
+    if install_script.exists():
+        try:
+            bin_dir = get_kapsel_dir() / "bin"
+            bin_dir.mkdir(parents=True, exist_ok=True)
+
+            module_name = f"kapsel_installer_{target_name}"
+            spec = importlib.util.spec_from_file_location(module_name, install_script)
+            if spec and spec.loader:
+                installer_mod = importlib.util.module_from_spec(spec)
+                sys.modules[module_name] = installer_mod
+                spec.loader.exec_module(installer_mod)
+                install_fn = getattr(installer_mod, "install", None)
+                if callable(install_fn):
+                    con.print(f"[dim]Running installer for '[#00f0ff]{target_name}[/]'...[/]")
+                    success = install_fn(con, bin_dir)
+                    if not success:
+                        con.print(f"[yellow]Notice: Installation script for '{target_name}' finished with warnings.[/]")
+        except Exception as e:
+            con.print(f"[yellow]Warning: Failed to execute installer for '{target_name}':[/] {e}")
+
+    msg = f"[bold #10b981]✔ Plugin '[#00f0ff]{target_name}[/]' successfully added and enabled![/]\n\n"
+    msg += f"[dim]Location: {plugin_dir}[/]"
+
+    con.print(Panel(msg, title="[bold #00f0ff]🔌 Plugin System[/]", border_style="#0891b2", expand=False))
+    return 0