╭─ kapsel [pwsh] ~/Projects/Kapsel 14:32:05
╰─ ❯ git checkout -b feature/dynamic-specs
✔ 0  git checkout -b feature/dynamic-specs  ⏱ 24ms

🌟 Overview

Developers daily oscillate between disparate operating systems, suffering from fragmented terminal ergonomics:

• Muscle memory collisions (rm -rf vs Remove-Item, cat vs type, ls -la vs dir /a);
• Fragile global dotfiles polluting .bashrc, config.fish, or $PROFILE;
• Inconsistent autocompletion engines across shells.

Kapsel solves this by introducing a non-invasive, sandboxed terminal capsule. It operates as an ergonomic execution layer that intercepts and enhances command-line interactions with zero global system pollution—delivering sub-millisecond asynchronous autocompletion, Linux-first universal mapping, and automated environment isolation.

🚀 Key Features

1. Dual-State Execution Multiplexer

• Native Execution Layer (Default Mode): Direct, zero-overhead passthrough for all system executables (git, docker, npm, cargo, python, vim). Retains full TTY interaction, real-time signal handling, and standard stream piping.
• Unified Capsule Pipeline (kps <cmd> / kapsel <cmd>): A single entry point for universal commands, plugin utilities, and system configurations. Strips execution prefixes and translates cross-platform commands into host-optimized primitives on the fly.
• Asynchronous Deep Autosuggestions: Muted inline history prediction powered by a persistent, isolated SQLite statistical store (~/.kapsel/history.db). Accept suggestions instantaneously with → (Right Arrow).

2. Multi-Shell Dynamic Autocompletion (Carapace Powered)

• 1,000+ Command Coverage: Direct integration with Carapace enables multi-shell, multi-level argument and context completion (git branches/tags, docker containers/images, kubectl pods, npm scripts).
• Zero-Setup Bootstrapping: On first launch, Kapsel silently bootstraps the official platform binary into ~/.kapsel/bin/ with zero administrative/root permissions.

3. Dual Root Specification & Collision Sentinel

• Namespaced Root Trees (kps.yaml & kapsel.yaml): Dynamically compiles core built-ins and plugin specifications into isolated root trees under kps and kapsel.
• Host Namespace Collision Sentinel: Strictly guards host shell built-ins (alias, help, install, history, profile, ps, kill, dir). Commands with potential host collisions are sealed within the kps namespace—guaranteeing native shell commands (e.g. PowerShell's Get-Alias) remain 100% unhijacked.
• Deep Parameter Completions: Typing kps alias add <Tab> delivers rich multi-level flag completion (--from, --to, --shell, --global) in any terminal.

4. Modular, Crash-Proof Plugin Subsystem

• Decoupled Architecture: Plugins operate in isolated memory boundaries. A malfunctioning plugin can never crash Kapsel Core.
• Declarative Spec Standard: Every plugin defines independent declarative YAML specifications adhering to Carapace specifications.

5. Minimalist Boxed Terminal Aesthetics

• Card Framing: Clear visual demarcation of command inputs and outputs using modern boxed framing (╭─ ❯ and ╰─).
• Telemetry Feedback: Instantaneous display of execution exit codes (✔ 0 or ✘ exit 1) and precise wall-clock elapsed time (⏱ 38ms).
• Native Multilingual Engine (i18n): Full localization across 7 languages (en, zh_CN, ja, es, fr, de, ru).

⚡ Quick Installation

Choose the installation method that best fits your environment:

• 📦 Package Managers (PyPI / Scoop / Homebrew / APT)
• 💾 Precompiled Standalone Binaries
• 🌐 Automated Toolchain Installers
• 🛠️ Build from Source

🇨🇳 China Mainland Users: If you are located in China and require high-speed mirror acceleration (ghproxy, Tsinghua PyPI mirror, domestic download scripts), please refer to README_zh.md or docs/INSTALLATION.md.

1. 📦 Package Managers

PyPI (Python 3.9+)

# Recommended: Isolated environment via pipx (prevents global Python pollution)
pipx install kapsel-cli

# Or standard pip installation
pip install --upgrade kapsel-cli

Windows: Scoop

# Add Kapsel official bucket and install
scoop bucket add kapsel https://github.com/MrEiu/scoop-bucket
scoop install kapsel

macOS & Linux: Homebrew

# Add Kapsel official tap and install
brew tap MrEiu/tap
brew install kapsel

Debian & Ubuntu: APT & DPKG (.deb)

curl -LO https://github.com/MrEiu/Kapsel/releases/latest/download/kapsel_amd64.deb
sudo dpkg -i kapsel_amd64.deb || sudo apt-get install -f -y

2. 💾 Precompiled Standalone Binaries (Zero Dependencies)

No Python runtime or external package managers required. Simply extract and run:

💡 Usage Tip: Extract the archive and place kapsel (or kapsel.exe) and kps (or kps.exe) into any directory in your system PATH (such as ~/.kapsel/bin or /usr/local/bin).

3. 🌐 Automated Toolchain Installers

A unified single-command installer that automatically detects your OS platform, runs intelligent environment preflight inspections, and configures Kapsel with your preferred edition:

# macOS & Linux (Bash / Zsh):
curl -fsSL https://raw.githubusercontent.com/MrEiu/Kapsel/master/scripts/install.sh | bash

# Windows (PowerShell):
irm https://raw.githubusercontent.com/MrEiu/Kapsel/master/scripts/install.ps1 | iex

⚡ Intelligent Fast-Path & Preflight: The installer first inspects your existing Python runtime, Kapsel version, Carapace engine, PATH configurations, and installed plugins. Anything already up to date is skipped automatically (finishing in < 1 second).

📦 Available Editions:

• Lightweight Edition (--lite / -Lite): Core Kapsel CLI + Carapace completion engine (~20MB, ultra fast bootstrap).
• Full Edition (--full / -Full, default): Core + system package manager (Scoop / Homebrew / apt) + all 11 official plugins.

4. 🛠️ Build from Source

Ideal for developers wishing to contribute to Kapsel core or develop custom plugins:

git clone https://github.com/MrEiu/Kapsel.git
cd Kapsel
pip install -e .
kps completion sync

🧩 Official Plugin Ecosystem

Kapsel maintains a modular, decoupled plugin suite designed to satisfy modern engineering workflows:

📊 Feature Matrix & Comparison

📖 Commands Reference

Interactive Shell Mode (kapsel / kps)

Launch Kapsel as an interactive shell session:

kapsel

Within the capsule session, the following unified commands are available:

help                   Display Kapsel manual, interaction mechanisms, and command cheat sheet
status                 Inspect OS environment, active host shell, Git branch, and sandbox status
upgrade [plugin]       Two-stage upgrade check for Kapsel Core and official plugins with changelogs
search [-a]            Search and discover official plugins with versions and install states
enable <plugin>        Activate and enable an installed plugin, syncing autocompletions
disable <plugin>       Disable an active plugin without deleting local files
config                 Inspect or edit core configuration (~/.kapsel/config.yaml)
  config path          Print physical configuration file path
  config edit          Open configuration in default external editor
  config get <key>     Retrieve value for a configuration key
  config set <k> <v>   Update configuration value from terminal
  config reload        Hot-reload configuration from disk without session restart
completion             Manage, inspect, and synchronize declarative Carapace specifications
  completion ls        List active completion specifications, scopes, and mount states
  completion sync      Force compile and synchronize dual root specs (kps.yaml and kapsel.yaml)
  completion new <cmd> Scaffold a new declarative specification template
  completion path      Display active spec directories
datadir                Inspect or safely relocate data storage sandbox directory
language <lang>        Switch active UI language (en, zh_CN, ja, es, fr, de, ru)
toggle                 Toggle Kapsel default terminal mode (open on first call, close on second)
clear                  Clear terminal screen and re-render header banner
exit                   Cleanly exit Kapsel and return to native host shell

One-Shot External Execution

Execute any capsule or plugin command directly from your standard shell:

# Management & Diagnostics
kps status
kps completion ls
kps config edit

# Plugin commands
kps portal ls
kps shore get
kps init use node@22

# Cross-platform mapped commands
kps rm -rf dist/
kps ls -la

🔒 Directory Sandboxing & State Model

Kapsel adheres strictly to the Zero-Pollution Guarantee. All data, binaries, caches, and logs reside exclusively within the user sandbox directory:

~/.kapsel/
├── config.yaml          # System-wide UI configuration (colors, card borders, language)
├── history.db           # Persistent SQLite database storing command history and stats
├── bin/                 # User-space standalone binary tools (carapace, zoxide, mise, chsrc...)
├── specs/               # User custom declarative autocompletion specifications
├── plugins/             # Installed official and community plugin packages
└── logs/                # Session logs and crash diagnostics

🧪 Testing & Quality Assurance

The Kapsel codebase enforces thorough test coverage with strict type checks and isolated fixtures:

# Clone the repository
git clone https://github.com/MrEiu/Kapsel.git
cd Kapsel

# Install test dependencies
pip install -e ".[test]"

# Run full test suite
pytest tests/ -v

All 79 automated unit tests validate spec manager discovery, collision sentinel blocking, carapace integration, plugin lifecycles, and i18n resolution.

🤝 Contributing & Community

Contributions are welcome!

• Check out issues to find tasks or report bugs.
• For developing or submitting plugins, refer to the Plugins Guide.

📄 License

Kapsel is open-source software licensed under the MIT License.