kapsel-cli 0.3.6__tar.gz → 0.5.2__tar.gz

{kapsel_cli-0.3.6 → kapsel_cli-0.5.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: kapsel-cli
-Version: 0.3.6
+Version: 0.5.2
 Summary: Next-generation cross-platform terminal capsule & ergonomic shell multiplexer with context-aware command translation and 1,000+ CLI completions.
 Author-email: MrEiu <k648888@vip.qq.com>
 License: MIT

{kapsel_cli-0.3.6 → kapsel_cli-0.5.2}/kapsel/__init__.py

@@ -3,4 +3,4 @@ Kapsel: Cross-platform adaptive smart terminal capsule.
 Wrap complexity, expose simplicity.
 """
 
-__version__ = "0.3.6"
+__version__ = "0.5.2"

{kapsel_cli-0.3.6 → kapsel_cli-0.5.2}/kapsel/cli.py

@@ -48,13 +48,8 @@ def main(args: Optional[List[str]] = None) -> int:
             )
         return result.execution.exit_code
 
-    is_toggle_start = False
-    if clean_args and clean_args[0] == "toggle":
-        is_toggle_start = True
-        clean_args = clean_args[1:]
-
-    # If other positional subcommands passed (e.g. kapsel status, kapsel help, kapsel add, kapsel config, kapsel datadir)
-    if clean_args and not is_toggle_start:
+    # If positional subcommands passed (e.g. kapsel toggle, kapsel status, kapsel help, kapsel add, kapsel config, kapsel datadir)
+    if clean_args:
         engine = DualStateEngine()
         full_cmd = "kapsel " + " ".join(clean_args)
         result = engine.dispatch(full_cmd)
@@ -66,6 +61,10 @@ def main(args: Optional[List[str]] = None) -> int:
             )
         return result.execution.exit_code
 
+    # Do not start interactive shell in non-interactive / piped environments
+    if not sys.stdin.isatty() and not os.environ.get("KAPSEL_FORCE_TTY"):
+        return 0
+
     # Launch interactive shell (Kapsel Default Mode)
     engine = DualStateEngine()
     console = Console(legacy_windows=False)
@@ -76,9 +75,7 @@ def main(args: Optional[List[str]] = None) -> int:
 
     os.environ["KAPSEL_ACTIVE"] = "1"
 
-    if is_toggle_start:
-        console.print("[bold #10b981]✔ Kapsel active.[/] [dim]Type 'toggle' or 'exit' to quit.[/]\n")
-    elif engine.config.enable_banner and not no_banner:
+    if engine.config.enable_banner and not no_banner:
         render_banner()
 
     prompt_session = KapselPrompt(engine)
@@ -101,7 +98,7 @@ def main(args: Optional[List[str]] = None) -> int:
             continue
 
         normalized = " ".join(stripped.lower().split())
-        if normalized in ("exit", "quit", "toggle", "kapsel toggle", "kps toggle"):
+        if normalized in ("exit", "quit", "bye"):
             os.environ.pop("KAPSEL_ACTIVE", None)
             console.print("[dim]Exited Kapsel.[/]")
             break
@@ -143,9 +140,6 @@ def kps_cli() -> int:
         print(f"Kapsel v{__version__}")
         return 0
 
-    if argv[0] == "toggle":
-        return main(["toggle"])
-
     # 1. Fast dispatch to registered built-in or plugin kps commands
     cmd_line = " ".join(argv)
     builtin_exit = dispatch_kps(cmd_line)

{kapsel_cli-0.3.6 → kapsel_cli-0.5.2}/kapsel/completion/kps/builtins/__init__.py

@@ -114,8 +114,13 @@ def register_builtins(registry: "KpsCommandRegistry") -> None:
     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",
+        help_text="Toggle Kapsel as default terminal startup shell (auto-launch on opening terminal)",
+        subcommands={
+            "on": "Enable Kapsel as default terminal startup shell in shell profile",
+            "off": "Disable Kapsel default startup and restore host shell",
+            "status": "Check current default terminal startup configuration",
+        },
+        usage="kapsel toggle [on|off|status]",
         scope="system",
     )
 
@@ -187,4 +192,20 @@ def register_builtins(registry: "KpsCommandRegistry") -> None:
         scope="system",
     )
 
+    # 11. dir & rm (Directional navigation & file management)
+    from kapsel.completion.kps.builtins.dir_nav import handle_dir_command, handle_rm_command
+    registry.register(
+        name="dir",
+        handler=handle_dir_command,
+        help_text="Preview directories and view Ctrl+Arrow navigation shortcuts",
+        usage="kapsel dir",
+        scope="system",
+    )
+    registry.register(
+        name="rm",
+        handler=handle_rm_command,
+        help_text="Safely permanently delete a file or directory with explicit confirmation",
+        usage="kapsel rm <file_or_directory>",
+        scope="system",
+    )
 

{kapsel_cli-0.3.6 → kapsel_cli-0.5.2}/kapsel/completion/kps/builtins/add.py

@@ -9,93 +9,72 @@ import importlib.util
 from pathlib import Path
 import shutil
 import sys
-from typing import List, Optional
+from typing import List, Optional, Tuple
 from rich.console import Console
 from rich.panel import Panel
+from rich.table import Table
 
 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:
+def _install_single_plugin(
+    target_raw: str,
+    con: Console,
+    is_dev: bool = False,
+    is_batch: bool = False,
+) -> Tuple[bool, str]:
     """
-    Handles 'kapsel add <plugin_name>' system command.
-    Enables local plugins, triggers their standalone install.py, and registers them into config.yaml.
+    Installs a single plugin by name or path:
+    1. Resolves source directory (dev local, user global, or remote fetch).
+    2. Copies to user global plugins directory.
+    3. Adds to config.yaml enabled plugins list.
+    4. Triggers standalone install.py if present.
+    Returns (success: bool, message: str).
     """
-    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
-
-    cfg = load_config()
-    is_dev = getattr(cfg, "is_dev", False)
-
-    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:
-    # In release mode, bare names like 'install' will never be hijacked by local folders.
-    # Only treat as a local directory if explicit path syntax is used (./, ../, /, \) or in dev mode.
+    source_path = Path(target_raw).expanduser()
     has_path_qualifier = any(sep in target_raw for sep in ("/", "\\")) or target_raw.startswith(".")
 
     if (has_path_qualifier or is_dev) and source_path.exists() and source_path.is_dir():
-        # User specified an explicit directory path (or in dev mode where local directory takes priority)
         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
+            err = f"Source directory '{source_path}' does not contain '__init__.py'."
+            con.print(f"[bold #f43f5e]Error:[/] {err}")
+            return False, err
 
-        # 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 is_dev and dev_plugin_dir.exists() and dev_plugin_dir.is_dir() and (dev_plugin_dir / "__init__.py").exists():
-            # If present in local dev directory (dev mode only), sync 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:
-            # 3. Not found locally: Automatically fetch from official remote repository
             from kapsel.core.plugin.fetcher import fetch_plugin_from_remote
-
             if fetch_plugin_from_remote(target_name, dest_plugin_dir, con):
                 plugin_dir = dest_plugin_dir
             else:
-                con.print(f"[bold #f43f5e]Error:[/] Plugin '[white]{target_name}[/]' could not be installed.")
-                con.print(f"[dim]Expected location:[/] {dest_plugin_dir}")
-                con.print("[dim]To install a custom plugin, specify its local path or place it into your global plugins directory.[/]\n")
-                return 1
+                err = f"Plugin '{target_name}' could not be installed."
+                con.print(f"[bold #f43f5e]Error:[/] {err}")
+                if not is_batch:
+                    con.print(f"[dim]Expected location:[/] {dest_plugin_dir}")
+                    con.print("[dim]To install a custom plugin, specify its local path or place it into your global plugins directory.[/]\n")
+                return False, err
 
-    # 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
+        err = f"Plugin directory '{plugin_dir}' does not contain a valid '__init__.py'."
+        con.print(f"[bold #f43f5e]Error:[/] {err}")
+        return False, err
 
     # Add to config.yaml enabled plugins list
     cfg = load_config()
@@ -105,7 +84,6 @@ def handle_add_command(args: List[str], console: Optional[Console] = None) -> in
         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:
@@ -132,6 +110,109 @@ def handle_add_command(args: List[str], console: Optional[Console] = None) -> in
 
     msg = f"[bold #10b981]✔ Plugin '[#00f0ff]{target_name}[/]' (v{ver}) successfully added and enabled![/]\n\n"
     msg += f"[dim]Location: {plugin_dir}[/]"
+    return True, msg
+
+
+def _handle_add_all(con: Console, is_dev: bool = False) -> int:
+    """
+    Sequentially installs and runs installation scripts for all official Kapsel plugins.
+    """
+    from kapsel.core.plugin.catalog import load_plugin_catalog_rich, DEFAULT_CATALOG
+    catalog = load_plugin_catalog_rich()
+    if not catalog:
+        catalog = {k: {"description": v} for k, v in DEFAULT_CATALOG.items()}
+
+    plugin_names = set()
+    for k in catalog.keys():
+        if k not in ("update", "all") and not k.startswith(("_", "$")):
+            plugin_names.add(k)
+
+    dev_plugins_dir = Path.cwd() / "plugins"
+    if is_dev and dev_plugins_dir.is_dir():
+        for item in dev_plugins_dir.iterdir():
+            if item.is_dir() and (item / "__init__.py").exists():
+                if item.name.lower() not in ("update", "all"):
+                    plugin_names.add(item.name.lower())
+
+    ordered_plugins = sorted(plugin_names)
+    total = len(ordered_plugins)
+
+    con.print(f"\n[bold #00f0ff]============================================================[/]")
+    con.print(f"[bold #00f0ff]   📦 Kapsel Batch Plugin Installer: {total} Plugins Found   [/]")
+    con.print(f"[bold #00f0ff]============================================================[/]\n")
+
+    succeeded: List[str] = []
+    failed: List[str] = []
+
+    for idx, name in enumerate(ordered_plugins, 1):
+        con.print(f"[bold #00f0ff]━━━ [{idx}/{total}] Adding & Installing Plugin: [white]{name}[/] ━━━[/]")
+        try:
+            ok, msg = _install_single_plugin(name, con, is_dev=is_dev, is_batch=True)
+            if ok:
+                succeeded.append(name)
+                con.print(f"  [bold #10b981]✔ Added & configured successfully[/]\n")
+            else:
+                failed.append(name)
+                con.print(f"  [bold #f43f5e]✘ Installation failed[/]\n")
+        except Exception as e:
+            failed.append(name)
+            con.print(f"  [bold #f43f5e]✘ Unexpected error during '{name}' install:[/] {e}\n")
+
+    # Summary table
+    table = Table(title="[bold #00f0ff]📊 Batch Installation Summary[/]", border_style="#0891b2")
+    table.add_column("Plugin", style="#00f0ff")
+    table.add_column("Status", style="white")
+
+    for name in ordered_plugins:
+        if name in succeeded:
+            table.add_row(name, "[bold #10b981]✔ Installed & Enabled[/]")
+        else:
+            table.add_row(name, "[bold #f43f5e]✘ Failed[/]")
+
+    con.print(table)
+    summary_color = "#10b981" if not failed else "#f59e0b"
+    con.print(f"\n[{summary_color}]Batch Completed:[/] [white]{len(succeeded)} succeeded[/], "
+              f"[{'#f43f5e' if failed else 'white'}]{len(failed)} failed[/].\n")
+    return 0 if succeeded else 1
+
+
+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.
+    Supports 'kapsel add all' to sequentially install all available plugins.
+    """
+    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> | all | update (e.g. kapsel add all)[/]\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
+
+    cfg = load_config()
+    is_dev = getattr(cfg, "is_dev", False)
+
+    # Handle 'kapsel add all' to sequentially install all available plugins
+    if target_raw.lower() == "all":
+        return _handle_add_all(con, is_dev=is_dev)
+
+    # Handle single plugin installation
+    success, msg = _install_single_plugin(target_raw, con, is_dev=is_dev, is_batch=False)
+    if success:
+        con.print(Panel(msg, title="[bold #00f0ff]🔌 Plugin System[/]", border_style="#0891b2", expand=False))
+        return 0
+    else:
+        return 1
 
-    con.print(Panel(msg, title="[bold #00f0ff]🔌 Plugin System[/]", border_style="#0891b2", expand=False))
-    return 0

kapsel_cli-0.5.2/kapsel/completion/kps/builtins/dir_nav.py

@@ -0,0 +1,318 @@
+"""
+Kapsel Directional Navigation & Native File Management Suite (方向键原生交互与文件管理).
+Completely avoids bottom_toolbar for maximum terminal compatibility.
+Uses native floating completion menus and prompt-line interactions:
+- Ctrl+Right: Opens native floating completion dropdown for subdirectories (cd <dir>/).
+- Ctrl+Left: Double-tap returns to parent directory ('cd ..').
+- Ctrl+Up: Populates 'touch ' on prompt line for cross-platform empty file creation.
+- Ctrl+Down: Double-tap populates 'kapsel rm ' with native completion dropdown + explicit terminal confirmation.
+All comments and docstrings are in English.
+"""
+
+from pathlib import Path
+import os
+import shutil
+import time
+from typing import List, Optional, Tuple
+
+from prompt_toolkit.application.run_in_terminal import run_in_terminal
+from prompt_toolkit.buffer import CompletionState
+from prompt_toolkit.completion import Completion
+from rich.console import Console
+from rich.table import Table
+
+
+# Double-tap timers
+_LAST_CTRL_LEFT_TIME: float = 0.0
+_LAST_CTRL_DOWN_TIME: float = 0.0
+DOUBLE_TAP_TIMEOUT: float = 2.0
+
+
+def list_subdirectories(cwd: Optional[Path] = None, show_hidden: bool = False) -> List[Path]:
+    """Lists subdirectories within cwd, sorted alphabetically case-insensitively."""
+    target = cwd or Path.cwd()
+    try:
+        dirs = [
+            p for p in target.iterdir()
+            if p.is_dir() and (show_hidden or not p.name.startswith("."))
+        ]
+        dirs.sort(key=lambda p: p.name.lower())
+        return dirs
+    except Exception:
+        return []
+
+
+def list_all_items(cwd: Optional[Path] = None, show_hidden: bool = False) -> List[Path]:
+    """Lists all files and subdirectories within cwd for deletion selection."""
+    target = cwd or Path.cwd()
+    try:
+        items = [
+            p for p in target.iterdir()
+            if (show_hidden or not p.name.startswith("."))
+        ]
+        items.sort(key=lambda p: (not p.is_dir(), p.name.lower()))
+        return items
+    except Exception:
+        return []
+
+
+def create_empty_file(cwd: Path, filename: str) -> Tuple[bool, str]:
+    """Safely creates a new empty file in the given directory."""
+    clean_name = filename.strip().strip("\"'")
+    if not clean_name:
+        return False, "文件名不能为空 (Filename cannot be empty)"
+
+    target = cwd / clean_name
+    try:
+        if target.exists():
+            return False, f"目标已存在 (Item already exists): {clean_name}"
+        target.parent.mkdir(parents=True, exist_ok=True)
+        target.touch()
+        return True, f"✔ 空文件已创建 (Created): {clean_name}"
+    except Exception as e:
+        return False, f"✖ 创建失败 (Creation error): {e}"
+
+
+def delete_item_permanently(target_path: Path) -> Tuple[bool, str]:
+    """Permanently deletes a file or directory without backup."""
+    try:
+        if not target_path.exists():
+            return False, f"目标不存在 (Item not found): {target_path.name}"
+        if target_path.is_dir():
+            shutil.rmtree(target_path)
+        else:
+            target_path.unlink()
+        return True, f"✔ 已永久删除 (Permanently deleted): {target_path.name}"
+    except Exception as e:
+        return False, f"✖ 删除失败 (Deletion error): {e}"
+
+
+# -----------------------------------------------------------------------------
+# 1. Ctrl+Right: Native Floating Completion Dropdown for Subdirectories
+# -----------------------------------------------------------------------------
+def trigger_subfolder_completion(buffer, cwd: Optional[Path] = None) -> bool:
+    """
+    Populates 'cd ' into buffer and immediately activates prompt_toolkit's
+    native floating completion dropdown populated with subdirectories.
+    """
+    target_cwd = cwd or Path.cwd()
+    dirs = list_subdirectories(target_cwd)
+
+    if not dirs:
+        run_in_terminal(lambda: print("\n\x1b[38;5;245m[📁 提示: 当前目录下暂无子文件夹]\x1b[0m"))
+        return False
+
+    # Ensure buffer has 'cd ' prefix
+    raw = buffer.text.strip()
+    if not raw or raw == "cd":
+        buffer.text = "cd "
+        buffer.cursor_position = 3
+    elif not buffer.text.endswith(" "):
+        buffer.text += " "
+        buffer.cursor_position = len(buffer.text)
+
+    completions = []
+    for d in dirs:
+        name = d.name
+        text_insert = f'"{name}"' if " " in name else name
+        completions.append(Completion(
+            text=text_insert,
+            start_position=0,
+            display=f"📁 {name}/",
+            display_meta="[目录 - Enter选入,再按Enter进入]",
+        ))
+
+    buffer.complete_state = CompletionState(
+        original_document=buffer.document,
+        completions=completions,
+        complete_index=0,
+    )
+    return True
+
+
+# -----------------------------------------------------------------------------
+# 2. Ctrl+Left: Double-Tap Parent Directory Return (cd ..)
+# -----------------------------------------------------------------------------
+def handle_ctrl_left_double_tap(buffer, on_cd_parent=None) -> bool:
+    """
+    Double-tap check for returning to parent directory (cd ..).
+    1st tap: Shows light inline notice.
+    2nd tap (< 2.0s): Executes 'cd ..'.
+    """
+    global _LAST_CTRL_LEFT_TIME
+    now = time.time()
+    if now - _LAST_CTRL_LEFT_TIME <= DOUBLE_TAP_TIMEOUT:
+        _LAST_CTRL_LEFT_TIME = 0.0
+        if on_cd_parent is not None:
+            on_cd_parent()
+        else:
+            buffer.text = "cd .."
+            buffer.cursor_position = len(buffer.text)
+            buffer.validate_and_handle()
+        return True
+    else:
+        _LAST_CTRL_LEFT_TIME = now
+        run_in_terminal(lambda: print("\n\x1b[38;5;245m[📁 提示: 再按一次 Ctrl+Left 返回父目录 (..)]\x1b[0m"))
+        return False
+
+
+# -----------------------------------------------------------------------------
+# 3. Ctrl+Up: Create New Empty File Prompt Line
+# -----------------------------------------------------------------------------
+def trigger_create_file(buffer) -> None:
+    """Populates 'touch ' into prompt line for easy cross-platform file creation."""
+    buffer.text = "touch "
+    buffer.cursor_position = 6
+
+
+# -----------------------------------------------------------------------------
+# 4. Ctrl+Down: Double-Tap Item Deletion with Native Completion & Confirmation
+# -----------------------------------------------------------------------------
+def handle_ctrl_down_double_tap(buffer, cwd: Optional[Path] = None) -> bool:
+    """
+    Double-tap check for item deletion.
+    1st tap: Shows caution notice.
+    2nd tap (< 2.0s): Populates 'kapsel rm ' and triggers native floating completions.
+    """
+    global _LAST_CTRL_DOWN_TIME
+    now = time.time()
+    if now - _LAST_CTRL_DOWN_TIME <= DOUBLE_TAP_TIMEOUT:
+        _LAST_CTRL_DOWN_TIME = 0.0
+        target_cwd = cwd or Path.cwd()
+        items = list_all_items(target_cwd)
+
+        if not items:
+            run_in_terminal(lambda: print("\n\x1b[38;5;203m[⚠️ 提示: 当前目录下无任何文件或文件夹]\x1b[0m"))
+            return False
+
+        buffer.text = "kapsel rm "
+        buffer.cursor_position = len(buffer.text)
+
+        completions = []
+        for it in items:
+            name = it.name
+            icon = "📁 " if it.is_dir() else "📄 "
+            type_label = "[目录]" if it.is_dir() else "[文件]"
+            text_insert = f'"{name}"' if " " in name else name
+            completions.append(Completion(
+                text=text_insert,
+                start_position=0,
+                display=f"{icon}{name}",
+                display_meta=f"{type_label} 永久删除",
+            ))
+
+        buffer.complete_state = CompletionState(
+            original_document=buffer.document,
+            completions=completions,
+            complete_index=0,
+        )
+        return True
+    else:
+        _LAST_CTRL_DOWN_TIME = now
+        run_in_terminal(lambda: print("\n\x1b[38;5;203m[⚠️ 谨慎操作: 再按一次 Ctrl+Down 进入删除选择]\x1b[0m"))
+        return False
+
+
+# -----------------------------------------------------------------------------
+# CLI Handlers: 'kapsel rm' (strict confirmation) and 'kapsel dir'
+# -----------------------------------------------------------------------------
+def handle_rm_command(args: List[str], console: Optional[Console] = None) -> int:
+    """CLI handler for 'kapsel rm' with strict interactive double confirmation."""
+    con = console or Console(legacy_windows=False)
+    if not args or args[0] in ("-h", "--help", "help"):
+        con.print("[dim]Usage: kapsel rm <file_or_directory>[/]")
+        return 0
+
+    raw_path = " ".join(args).strip().strip("\"'")
+    target = Path(raw_path)
+    if not target.is_absolute():
+        target = (Path.cwd() / target).resolve()
+
+    if not target.exists():
+        con.print(f"[bold #f43f5e]✖ 目标不存在: {raw_path}[/]")
+        return 1
+
+    item_type = "目录 (及其中所有内容)" if target.is_dir() else "文件"
+    con.print(f"\n[bold #f43f5e]🚨 永久删除警告[/]: 即将永久彻底删除 {item_type} [bold white]{target.name}[/]！")
+    con.print("[dim]该操作不可逆，且不保留回收站备份。[/]")
+
+    try:
+        reply = input("👉 请输入 y 确认删除 (输入其他键放弃): ").strip().lower()
+    except (KeyboardInterrupt, EOFError):
+        con.print("\n[dim]操作已取消。[/]")
+        return 0
+
+    if reply in ("y", "yes"):
+        ok, msg = delete_item_permanently(target)
+        if ok:
+            con.print(f"[bold #10b981]{msg}[/]\n")
+            return 0
+        else:
+            con.print(f"[bold #f43f5e]{msg}[/]\n")
+            return 1
+    else:
+        con.print("[dim]操作已放弃，未做任何更改。[/]\n")
+        return 0
+
+
+def handle_dir_command(args: List[str], console: Optional[Console] = None) -> int:
+    """CLI entry point for 'kapsel dir' / 'kps dir'."""
+    con = console or Console(legacy_windows=False)
+
+    if args and args[0] in ("-h", "--help", "help"):
+        con.print("\n[bold #00f0ff]📁 Kapsel Directional Navigation & File Management (`kapsel dir`)[/]")
+        con.print("[dim]Inspect directories and view keyboard shortcuts for rapid prompt navigation.[/]\n")
+        table = Table(border_style="#0891b2", title="[bold #38bdf8]⚡ Directional Hotkeys (Ctrl + Arrows)[/]")
+        table.add_column("Shortcut", style="bold #00f0ff", width=16)
+        table.add_column("Action", style="white", width=24)
+        table.add_column("Details & Safety Mechanism", style="dim", overflow="fold")
+
+        table.add_row(
+            "Ctrl + Right (→)",
+            "Browse & Enter Subfolder",
+            "Opens native floating dropdown; ↑/↓ select; 1st Enter loads 'cd', 2nd Enter enters folder.",
+        )
+        table.add_row(
+            "Ctrl + Left (←)",
+            "Return to Parent (cd ..)",
+            "Double-tap safety (按两下): 1st tap warns, 2nd tap within 2s returns to parent.",
+        )
+        table.add_row(
+            "Ctrl + Up (↑)",
+            "Create Empty File",
+            "Single press populates 'touch '; type filename and Enter to create.",
+        )
+        table.add_row(
+            "Ctrl + Down (↓)",
+            "Permanent Deletion",
+            "Double-tap opens delete dropdown; terminal prompts explicit (y/N) confirmation.",
+        )
+        con.print(table)
+        con.print()
+        return 0
+
+    cwd = Path.cwd()
+    dirs = list_subdirectories(cwd)
+    all_items = list_all_items(cwd)
+    files = [p for p in all_items if not p.is_dir()]
+
+    con.print(f"\n[bold #00f0ff]📂 Current Directory:[/] [bold white]{cwd}[/]")
+    con.print(f"[dim]Contains {len(dirs)} subdirectories and {len(files)} files.[/]\n")
+
+    table = Table(border_style="#0891b2")
+    table.add_column("Type", justify="center", width=8)
+    table.add_column("Name", style="bold white")
+    table.add_column("Size / Info", style="dim", justify="right", width=14)
+
+    for d in dirs:
+        table.add_row("[bold #38bdf8]📁 DIR[/]", f"[bold #00f0ff]{d.name}/[/]", "-")
+    for f in files[:25]:
+        size = f"{f.stat().st_size} B" if f.exists() else "-"
+        table.add_row("[dim]📄 FILE[/]", f.name, size)
+
+    if len(files) > 25:
+        table.add_row("[dim]...[/]", f"[dim]({len(files) - 25} more files not shown)[/]", "")
+
+    con.print(table)
+    con.print("[dim]💡 Tip: Press [bold #00f0ff]Ctrl+Right[/] in prompt to open the floating subfolder dropdown![/]\n")
+    return 0