kapsel-cli 0.1.0__py3-none-any.whl

kapsel/completion/kps/builtins/config.py

@@ -0,0 +1,184 @@
+"""
+Kapsel Config Command.
+Handles 'config', 'config path', 'config edit', 'config get', 'config set', 'config reload'.
+"""
+
+import os
+from pathlib import Path
+import platform
+import subprocess
+from typing import Any, List, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from kapsel.storage.config import (
+    KapselConfig,
+    get_config_path,
+    load_config,
+    update_config_value,
+)
+from kapsel.ui.banner import ensure_utf8_io
+
+
+def handle_config_command(args: List[str], console: Optional[Console] = None) -> int:
+    """Handles 'config [subcommand]' and renders rich output."""
+    ensure_utf8_io()
+    con = console or Console(legacy_windows=False)
+
+    config_path = get_config_path()
+    cfg = load_config()
+
+    if not args:
+        render_config_dashboard(cfg, config_path, con)
+        return 0
+
+    sub = args[0].lower()
+
+    if sub == "path":
+        print(str(config_path))
+        return 0
+
+    if sub == "edit":
+        con.print(f"[dim]Opening configuration file:[/] [bold #00f0ff]{config_path}[/]")
+        try:
+            if platform.system() == "Windows":
+                os.startfile(str(config_path))
+            elif platform.system() == "Darwin":
+                subprocess.run(["open", str(config_path)])
+            else:
+                subprocess.run(["xdg-open", str(config_path)])
+            con.print("[bold #10b981]✔ Opened in external editor[/]")
+        except Exception as e:
+            con.print(f"[bold #f43f5e]Failed to open editor: {e}[/]")
+            con.print(f"[dim]You can edit it manually at: {config_path}[/]")
+        return 0
+
+    if sub == "reload":
+        new_cfg = load_config(force_reload=True)
+        con.print(f"[bold #10b981]✔ Configuration reloaded.[/] (Theme: {new_cfg.theme.get('name')}, Tap: {new_cfg.interaction.get('autosuggest_tap_mode')})")
+        return 0
+
+    if sub in ("datadir", "migrate"):
+        from kapsel.commands.datadir import handle_datadir_command
+        return handle_datadir_command(args[1:], con)
+
+    if sub == "get":
+        if len(args) < 2:
+            con.print("[bold #f43f5e]Error: Please specify configuration key (e.g. config get interaction.autosuggest_tap_mode)[/]")
+            return 1
+        key_path = args[1]
+        val = get_nested_val(cfg.raw, key_path)
+        if val is None:
+            con.print(f"[dim]Config key '{key_path}' is not set (using default)[/]")
+        else:
+            con.print(f"[bold #00f0ff]{key_path}[/] = [bold #10b981]{val}[/]")
+        return 0
+
+    if sub == "set":
+        if len(args) < 3:
+            con.print("[bold #f43f5e]Error: Invalid format. Usage: config set <key.path> <value>[/]")
+            con.print("[dim]Example: config set interaction.autosuggest_tap_mode full[/]")
+            con.print("[dim]Example: config set interaction.autosuggest_sensitivity 0.15[/]")
+            return 1
+        key_path = args[1]
+        val_str = args[2]
+
+        parsed_val: Any = val_str
+        if val_str.lower() in ("true", "yes", "1", "on"):
+            parsed_val = True
+        elif val_str.lower() in ("false", "no", "0", "off"):
+            parsed_val = False
+        else:
+            try:
+                if "." in val_str:
+                    parsed_val = float(val_str)
+                else:
+                    parsed_val = int(val_str)
+            except ValueError:
+                parsed_val = val_str
+
+        success = update_config_value(key_path, parsed_val)
+        if success:
+            con.print(f"[bold #10b981]✔ Config updated:[/] [bold #00f0ff]{key_path}[/] = [bold #10b981]{parsed_val}[/]")
+            con.print("[dim]Saved to ~/.kapsel/config.yaml and reloaded.[/]")
+            return 0
+        else:
+            con.print(f"[bold #f43f5e]✘ Failed to update config. Check key path: '{key_path}'[/]")
+            return 1
+
+    con.print(f"[bold #f43f5e]Unknown config subcommand: '{sub}'.[/] See 'kapsel config --help'.")
+    return 1
+
+
+def get_nested_val(data: dict, path: str) -> Any:
+    keys = path.split(".")
+    curr = data
+    for k in keys:
+        if isinstance(curr, dict) and k in curr:
+            curr = curr[k]
+        else:
+            return None
+    return curr
+
+
+def render_config_dashboard(cfg: KapselConfig, config_path: Path, console: Console) -> None:
+    inter = cfg.interaction
+    ui_cfg = cfg.ui
+    theme_cfg = cfg.theme
+    cloud_cfg = cfg.raw.get("cloud", {})
+
+    grid = Table.grid(expand=True, padding=(0, 2))
+    grid.add_column(style="bold #00f0ff", justify="right", width=22)
+    grid.add_column(style="#e4e4e7")
+    grid.add_column(style="bold #a855f7", justify="right", width=22)
+    grid.add_column(style="#e4e4e7")
+
+    grid.add_row(
+        "🎯 Autosuggest Tap:",
+        f"[bold #10b981]{inter.get('autosuggest_tap_mode', 'word')}[/]",
+        "🎨 Active Theme:",
+        f"[bold #00f0ff]{theme_cfg.get('name', 'cyber_dark')}[/]",
+    )
+    grid.add_row(
+        "⚡ Hold Action:",
+        f"[bold #10b981]{inter.get('autosuggest_hold_action', 'full')}[/]",
+        "⏱ Card Border:",
+        f"[bold #10b981]{'On' if ui_cfg.get('enable_card_border') else 'Off'}[/]",
+    )
+    grid.add_row(
+        "⏲ Sensitivity:",
+        f"[bold #10b981]{inter.get('autosuggest_sensitivity', 0.25)}s[/]",
+        " Git Badge:",
+        f"[bold #10b981]{'On' if ui_cfg.get('show_git_branch') else 'Off'}[/]",
+    )
+    grid.add_row(
+        "🔢 Threshold Count:",
+        f"[bold #10b981]{inter.get('consecutive_press_threshold', 2)}[/]",
+        "🌐 Cloud Endpoint:",
+        f"[dim]{cloud_cfg.get('server_endpoint', 'http://127.0.0.1:8000')}[/]",
+    )
+
+    content = Table.grid(expand=True, padding=(1, 0))
+    content.add_column()
+
+    header = Text()
+    header.append("⚙️ KAPSEL Configuration Dashboard\n", style="bold #00f0ff")
+    header.append(f"Config path: {config_path}\n", style="dim #6b7280")
+    header.append("Run 'config edit' to open editor · Run 'config set <key> <val>' to update", style="italic #9ca3af")
+
+    content.add_row(header)
+    content.add_row(grid)
+
+    panel = Panel(
+        content,
+        border_style="#0891b2",
+        padding=(1, 2),
+        expand=False,
+    )
+
+    console.print()
+    console.print(panel)
+    console.print()

kapsel/completion/kps/builtins/datadir.py

@@ -0,0 +1,108 @@
+"""
+Kapsel Data Directory (datadir / migrate) Command Handler.
+Allows users to view, customize, and migrate Kapsel's data storage location.
+Automatically moves existing databases, configs, logs, and registry manifests.
+"""
+
+from pathlib import Path
+from typing import List, Optional
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from kapsel.storage.logger import (
+    POINTER_FILE,
+    get_default_kapsel_dir,
+    get_kapsel_dir,
+)
+from kapsel.storage.migrate import migrate_kapsel_data
+from kapsel.ui.banner import ensure_utf8_io
+
+
+def handle_datadir_command(args: List[str], console: Optional[Console] = None) -> int:
+    """Dispatches 'datadir' command: view or migrate storage location."""
+    ensure_utf8_io()
+    con = console or Console(legacy_windows=False)
+
+    if not args:
+        return show_current_datadir(con)
+
+    sub = args[0].strip()
+
+    if sub in ("help", "-h", "--help"):
+        render_datadir_help(con)
+        return 0
+
+    if sub in ("status", "show", "current", "path"):
+        return show_current_datadir(con)
+
+    # Any other argument is treated as the target migration path!
+    target_path = " ".join(args).strip().strip('"\'').strip()
+    return do_migration(target_path, con)
+
+
+def show_current_datadir(console: Console) -> int:
+    current = get_kapsel_dir()
+    default = get_default_kapsel_dir()
+    is_custom = current.resolve() != default.resolve()
+
+    # Calculate directory size
+    total_bytes = 0
+    file_count = 0
+    try:
+        for p in current.rglob("*"):
+            if p.is_file():
+                total_bytes += p.stat().st_size
+                file_count += 1
+    except Exception:
+        pass
+
+    size_str = f"{total_bytes / 1024:.1f} KB" if total_bytes < 1024 * 1024 else f"{total_bytes / (1024*1024):.2f} MB"
+
+    grid = Table.grid(padding=(0, 2))
+    grid.add_column(style="bold #00f0ff", width=18)
+    grid.add_column()
+
+    grid.add_row("📂 Data Directory:", f"[bold #10b981]{current}[/]")
+    grid.add_row(
+        "🏷️ Storage Mode:",
+        "[bold #a855f7]Custom Location[/]" if is_custom else "[dim]Default (~/.kapsel)[/]",
+    )
+    grid.add_row("📦 Storage Size:", f"{size_str} ({file_count} files/databases)")
+    if is_custom and POINTER_FILE.exists():
+        grid.add_row("📌 Pointer File:", f"[dim]{POINTER_FILE}[/]")
+
+    panel = Panel(
+        grid,
+        title="[bold #00f0ff]💊 Kapsel Data Directory[/]",
+        border_style="#0891b2",
+        padding=(1, 2),
+    )
+    console.print()
+    console.print(panel)
+    console.print("\n[dim]Usage:[/]")
+    console.print("  • Relocate data sandbox: [bold #00f0ff]kps datadir <new_path>[/] (e.g. kps datadir D:\\KapselData)")
+    console.print("  • Restore default:       [bold #00f0ff]kps datadir default[/]\n")
+    return 0
+
+
+def do_migration(target_path: str, console: Console) -> int:
+    console.print(f"\n[dim]Preparing migration to:[/] [bold #00f0ff]{target_path}[/]")
+    console.print("[dim]Moving databases, configs, and plugins...[/]")
+
+    success, msg = migrate_kapsel_data(target_path)
+    if success:
+        console.print(f"\n[bold #10b981]✔ {msg}[/]\n")
+        return 0
+    else:
+        console.print(f"\n[bold #f43f5e]✘ Migration failed: {msg}[/]\n")
+        return 1
+
+
+def render_datadir_help(console: Console) -> None:
+    console.print("\n[bold #00f0ff]kps datadir[/] - View or customize Kapsel storage location\n")
+    console.print("Usage:")
+    console.print("  kps datadir                 View current storage location and stats")
+    console.print("  kps datadir <new_path>      Migrate existing data to a new location")
+    console.print("  kps datadir default         Migrate data back to default (~/.kapsel)\n")

kapsel/completion/kps/builtins/help.py

@@ -0,0 +1,270 @@
+"""
+Kapsel Help Command (Data-Driven Renderer).
+Loads comprehensive, structured manual datasets from locale resources (defaults to English),
+formats rich visual tables and panels, dynamically integrates live registered plugins,
+and supports focused topic exploration.
+All comments and descriptions are in English.
+"""
+
+from typing import Any, Dict, 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.completion.kps.registry import get_kps_registry
+from kapsel.i18n import get_current_language, load_help_data
+from kapsel.ui.banner import ensure_utf8_io
+
+
+class HelpRenderer:
+    """
+    Data-driven renderer for the Kapsel manual and cheatsheet.
+    Decouples documentation content from Python code.
+    """
+
+    def __init__(self, console: Optional[Console] = None, lang: Optional[str] = None):
+        self.console = console or Console(legacy_windows=False)
+        self.lang = lang or get_current_language()
+        self.data = load_help_data(self.lang)
+        self.registry = get_kps_registry()
+
+    def render_full_manual(self) -> None:
+        """Renders the complete manual: Header, Modes, Quickstart, Commands, Shortcuts, and Tips."""
+        self.console.print()
+        self.render_header()
+        self.render_modes()
+        self.render_quickstart()
+        self.render_commands()
+        self.render_shortcuts()
+        self.render_tips()
+        self.console.print()
+
+    def render_header(self) -> None:
+        """Renders the title banner and architecture note."""
+        meta = self.data.get("meta", {})
+        title = meta.get("title", "KAPSEL")
+        subtitle = meta.get("subtitle", "User Manual & Fast Command Cheatsheet")
+        architecture = meta.get(
+            "architecture",
+            "Unified Command Pipeline: 'kapsel <cmd>' and 'kps <cmd>' share the exact same execution engine.",
+        )
+
+        header = Text()
+        header.append(f"💊 {title}  ", style="bold #00f0ff")
+        header.append(f"v{__version__}  ·  {subtitle}\n", style="dim #6b7280")
+        header.append(f"{architecture}\n", style="italic #9ca3af")
+        self.console.print(header)
+
+    def render_modes(self) -> None:
+        """Renders the Core Interaction Dual Modes table."""
+        section = self.data.get("modes", {})
+        title = section.get("title", "🚀 Core Interaction Dual Modes")
+        cols = section.get("columns", {})
+        rows = section.get("rows", [])
+
+        table = Table(
+            title=title,
+            box=None,
+            title_justify="left",
+            padding=(0, 2),
+            collapse_padding=True,
+        )
+        table.add_column(cols.get("mode", "Mode"), style="bold #00f0ff", width=22)
+        table.add_column(cols.get("trigger", "Trigger"), style="#e4e4e7", width=26)
+        table.add_column(cols.get("description", "Behavior & Capabilities"), style="dim #9ca3af")
+
+        for r in rows:
+            table.add_row(r.get("name", ""), r.get("trigger", ""), r.get("description", ""))
+
+        self.console.print(table)
+        self.console.print()
+
+    def render_quickstart(self) -> None:
+        """Renders the Quickstart workflow guide."""
+        section = self.data.get("quickstart", {})
+        title = section.get("title", "⚡ Quick Start Workflow")
+        items = section.get("items", [])
+
+        table = Table(title=title, box=None, title_justify="left", padding=(0, 2))
+        table.add_column("Workflow Step", style="bold #a855f7", width=26)
+        table.add_column("Command Line", style="bold #38bdf8", width=28)
+        table.add_column("Purpose", style="#e4e4e7")
+
+        for item in items:
+            table.add_row(item.get("step", ""), item.get("cmd", ""), item.get("desc", ""))
+
+        self.console.print(table)
+        self.console.print()
+
+    def render_commands(self) -> None:
+        """
+        Renders the Capsule Command Suite.
+        Merges documented core commands with dynamically registered plugin commands.
+        """
+        section = self.data.get("commands", {})
+        title = section.get("title", "⚙️ Capsule Command Suite (kapsel / kps)")
+        cols = section.get("columns", {})
+        builtin_rows = section.get("builtin_rows", [])
+
+        table = Table(title=title, box=None, title_justify="left", padding=(0, 2))
+        table.add_column(cols.get("command", "Command"), style="bold #00f0ff", width=22)
+        table.add_column(cols.get("description", "Description"), style="#e4e4e7")
+        table.add_column(cols.get("origin", "Origin"), style="dim #9ca3af", width=14)
+
+        # Track displayed command names to prevent duplicates
+        rendered_names = set()
+
+        # 1. First render structured localized descriptions for built-in rows
+        for r in builtin_rows:
+            raw_cmd = r.get("name", "")
+            table.add_row(raw_cmd, r.get("desc", ""), r.get("origin", "Core"))
+            # Normalize command identifier (e.g. 'kps help' -> 'help')
+            parts = raw_cmd.split()
+            cmd_id = parts[1] if len(parts) > 1 else parts[0]
+            rendered_names.add(cmd_id)
+
+        # 2. Dynamically append any installed plugin commands not in static docs
+        all_registered = self.registry.list_commands()
+        for cmd in all_registered:
+            if cmd.name not in rendered_names:
+                origin = f"[{cmd.plugin_id}]" if cmd.plugin_id else "Core"
+                table.add_row(f"kps {cmd.name}", cmd.help_text, origin)
+                rendered_names.add(cmd.name)
+
+        self.console.print(table)
+        self.console.print()
+
+    def render_shortcuts(self) -> None:
+        """Renders interactive keybindings and ergonomic shortcuts."""
+        section = self.data.get("shortcuts", {})
+        title = section.get("title", "⌨️ Interactive Keybindings & Ergonomics")
+        cols = section.get("columns", {})
+        items = section.get("items", [])
+
+        table = Table(title=title, box=None, title_justify="left", padding=(0, 2))
+        table.add_column(cols.get("key", "Key"), style="bold #38bdf8", width=22)
+        table.add_column(cols.get("description", "Action"), style="#e4e4e7")
+
+        for item in items:
+            table.add_row(item.get("key", ""), item.get("desc", ""))
+
+        self.console.print(table)
+        self.console.print()
+
+    def render_tips(self) -> None:
+        """Renders pro tips and best practices in an aesthetic panel."""
+        section = self.data.get("tips", {})
+        title = section.get("title", "💡 Pro Tips & Best Practices")
+        items = section.get("items", [])
+
+        if not items:
+            return
+
+        grid = Table.grid(padding=(0, 1))
+        grid.add_column(style="bold #00f0ff", width=3)
+        grid.add_column(style="#e4e4e7")
+
+        for tip in items:
+            grid.add_row("•", tip)
+
+        panel = Panel(
+            grid,
+            title=f"[bold #00f0ff]{title}[/]",
+            title_align="left",
+            border_style="#0891b2",
+            padding=(0, 2),
+            expand=False,
+        )
+        self.console.print(panel)
+
+    def render_topic(self, topic: str) -> bool:
+        """Renders a single focused topic (e.g. 'keys', 'modes', 'commands', or specific command)."""
+        clean = topic.strip().lower()
+
+        if clean in ("mode", "modes", "dual", "architecture"):
+            self.console.print()
+            self.render_header()
+            self.render_modes()
+            return True
+
+        if clean in ("quickstart", "start", "workflow"):
+            self.console.print()
+            self.render_header()
+            self.render_quickstart()
+            return True
+
+        if clean in ("commands", "cmd", "cmds", "suite"):
+            self.console.print()
+            self.render_header()
+            self.render_commands()
+            return True
+
+        if clean in ("key", "keys", "shortcuts", "bindings"):
+            self.console.print()
+            self.render_header()
+            self.render_shortcuts()
+            return True
+
+        if clean in ("tip", "tips", "protips"):
+            self.console.print()
+            self.render_header()
+            self.render_tips()
+            return True
+
+        # Check if user requested help for a specific registered command (e.g. 'kps help config')
+        cmd = self.registry.get(clean)
+        if cmd:
+            self.console.print()
+            grid = Table.grid(padding=(0, 2))
+            grid.add_column(style="bold #00f0ff", width=14)
+            grid.add_column(style="#e4e4e7")
+
+            origin_str = f"[{cmd.plugin_id}] Plugin" if cmd.plugin_id else "Core Built-in"
+            grid.add_row("Command:", f"[bold white]kapsel {cmd.name}[/] [dim](or: kps {cmd.name})[/]")
+            grid.add_row("Description:", cmd.help_text)
+            grid.add_row("Usage:", f"[bold #a855f7]{cmd.usage or f'kps {cmd.name} [options]'}[/]")
+            grid.add_row("Origin:", origin_str)
+
+            if cmd.subcommands:
+                grid.add_row("Subcommands:", "")
+                for sub, desc in cmd.subcommands.items():
+                    grid.add_row("", f"  [bold #38bdf8]{sub:<16}[/] [dim]{desc}[/]")
+
+            panel = Panel(
+                grid,
+                title=f"[bold #00f0ff]📖 Command Guide: {cmd.name}[/]",
+                border_style="#0891b2",
+                padding=(1, 2),
+                expand=False,
+            )
+            self.console.print(panel)
+            self.console.print()
+            return True
+
+        return False
+
+
+def handle_help(args: Optional[List[str]] = None, console: Optional[Console] = None) -> int:
+    """
+    Entrypoint for the 'help' command.
+    Dispatches to HelpRenderer for complete manual or focused sub-topic query.
+    """
+    ensure_utf8_io()
+    con = console or Console(legacy_windows=False)
+    renderer = HelpRenderer(con)
+
+    if not args:
+        renderer.render_full_manual()
+        return 0
+
+    target_topic = args[0]
+    handled = renderer.render_topic(target_topic)
+    if not handled:
+        con.print(f"[yellow]Notice:[/] Topic or command '[white]{target_topic}[/]' not found in help manual.")
+        con.print("[dim]Showing full manual instead:[/]")
+        renderer.render_full_manual()
+
+    return 0

kapsel/completion/kps/builtins/language.py

@@ -0,0 +1,83 @@
+"""
+Kapsel Language Command: 'kapsel language [lang]'.
+Displays active language or switches between supported world languages:
+- en: English (default)
+- zh_CN: Simplified Chinese
+- ja: Japanese
+- es: Spanish
+- fr: French
+- de: German
+- ru: Russian
+All comments and descriptions are in English.
+"""
+
+from typing import List, Optional
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+
+from kapsel.i18n import (
+    SUPPORTED_LANGUAGES,
+    _,
+    get_current_language,
+    normalize_language_code,
+    set_current_language,
+)
+from kapsel.ui.banner import ensure_utf8_io
+
+
+def handle_language_command(args: Optional[List[str]] = None, console: Optional[Console] = None) -> int:
+    """
+    Handles 'kapsel language' and 'kps language'.
+    Without arguments: displays supported languages table and active language badge.
+    With arguments: switches current language and persists setting to ~/.kapsel/config.yaml.
+    """
+    ensure_utf8_io()
+    con = console or Console(legacy_windows=False)
+    current_code = get_current_language()
+
+    if not args:
+        # Render language selection table
+        curr_info = SUPPORTED_LANGUAGES.get(current_code, {"name": current_code, "native": current_code})
+
+        grid = Table(title=f"🌐 {_('Available Languages')}", box=None, title_justify="left", padding=(0, 2))
+        grid.add_column(_("Code"), style="bold #00f0ff", width=12)
+        grid.add_column(_("Language"), style="#e4e4e7", width=22)
+        grid.add_column(_("Native Name"), style="bold #a855f7", width=20)
+        grid.add_column(_("Aliases"), style="dim #9ca3af")
+        grid.add_column(_("Status"), width=12)
+
+        for code, meta in SUPPORTED_LANGUAGES.items():
+            aliases_str = ", ".join(meta.get("aliases", []))
+            is_curr = (code == current_code)
+            status_str = f"[bold #10b981]✔ {_('Active')}[/]" if is_curr else ""
+            grid.add_row(code, meta["name"], meta["native"], aliases_str, status_str)
+
+        con.print()
+        con.print(grid)
+        con.print()
+        con.print(f"[dim]{_('Usage:')} [/][bold #38bdf8]kps language <code/alias>[/] [dim](e.g. 'kps language zh' or 'kps language ja')[/]\n")
+        return 0
+
+    target_raw = args[0].strip()
+    target_code = normalize_language_code(target_raw)
+
+    if not target_code or target_code not in SUPPORTED_LANGUAGES:
+        available = ", ".join(SUPPORTED_LANGUAGES.keys())
+        err_msg = _("Error: Unsupported language '{input}'. Available codes: {available}").format(
+            input=target_raw, available=available
+        )
+        con.print(f"[bold #f43f5e]{err_msg}[/]")
+        return 1
+
+    success = set_current_language(target_code, persist=True)
+    if success:
+        meta = SUPPORTED_LANGUAGES[target_code]
+        msg = _("✔ Language successfully switched to: {name} ({code})").format(
+            name=meta["native"], code=target_code
+        )
+        con.print(f"[bold #10b981]{msg}[/]")
+        return 0
+    else:
+        con.print(f"[bold #f43f5e]Failed to update language setting.[/]")
+        return 1