kapsel-cli 0.2.1__tar.gz → 0.3.8__tar.gz

kapsel_cli-0.3.8/PKG-INFO

@@ -0,0 +1,620 @@
+Metadata-Version: 2.4
+Name: kapsel-cli
+Version: 0.3.8
+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
+Project-URL: Homepage, https://github.com/MrEiu/Kapsel
+Project-URL: Documentation, https://github.com/MrEiu/Kapsel#readme
+Project-URL: Repository, https://github.com/MrEiu/Kapsel
+Project-URL: Issues, https://github.com/MrEiu/Kapsel/issues
+Project-URL: Changelog, https://github.com/MrEiu/Kapsel/releases
+Keywords: terminal,shell,cli,multiplexer,autocompletion,cross-platform,developer-tools,carapace,productivity,powershell,bash,zsh
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Operating System :: Microsoft :: Windows
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Operating System :: MacOS
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Shells
+Classifier: Topic :: System :: System Shells
+Classifier: Topic :: Terminals
+Classifier: Topic :: Utilities
+Classifier: Topic :: Software Development :: User Interfaces
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Requires-Dist: prompt_toolkit>=3.0.40
+Requires-Dist: rich>=13.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: psutil>=5.9.0
+Requires-Dist: shellingham>=1.5.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0.0; extra == "test"
+
+<div align="center">
+
+# ⚡ Kapsel
+
+**A cross-platform terminal capsule for a cleaner, more consistent command-line experience.**
+
+[![PyPI Version](https://img.shields.io/pypi/v/kapsel-cli?color=3776AB&logo=pypi&logoColor=white&style=flat-square)](https://pypi.org/project/kapsel-cli/)
+[![Python Version](https://img.shields.io/badge/Python-3.9%20%7C%203.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-3776AB.svg?style=flat-square&logo=python&logoColor=white)](https://pypi.org/project/kapsel-cli/)
+[![Platform Support](https://img.shields.io/badge/Platform-Windows%20%7C%20macOS%20%7C%20Linux-4D4D4D.svg?style=flat-square&logo=linux&logoColor=white)](https://github.com/MrEiu/Kapsel)
+[![License](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](LICENSE)
+
+[Quick Start](#-quick-start) ·
+[Features](#-features) ·
+[Plugins](#-plugin-ecosystem) ·
+[Installation](#-installation) ·
+[Architecture](#-architecture) ·
+[Documentation](#-documentation)
+
+[🇨🇳 简体中文](README_zh.md) ·
+[🇯🇵 日本語](README_ja.md) ·
+[🇷🇺 Русский](README_ru.md) ·
+[🇩🇪 Deutsch](README_de.md) ·
+[🇪🇸 Español](README_es.md) ·
+[🇫🇷 Français](README_fr.md) ·
+[🇵🇱 Polski](README_pl.md)
+
+</div>
+
+---
+
+## 📺 Kapsel in Action
+
+```text
+╭─ kapsel [pwsh] ~/Projects/Kapsel 14:32:05
+╰─ ❯ git checkout -b feature/dynamic-specs
+✔ 0  git checkout -b feature/dynamic-specs  ⏱ 24ms
+```
+
+> **Wrap complexity, expose simplicity.**
+>
+> Keep using your native shell and system executables as usual, while Kapsel
+> adds a unified command layer, context-aware completion, inline suggestions,
+> and an extensible plugin environment — all contained inside `~/.kapsel/`.
+
+---
+
+## 💡 Why Kapsel?
+
+Terminal workflows are still heavily shaped by the host operating system and
+the shell being used.
+
+The same everyday task may require different commands on Windows, macOS, and
+Linux. Shell configuration is fragmented across files such as `.bashrc`,
+`.zshrc`, and PowerShell profiles, while completion systems and developer
+utilities often need to be installed and configured independently.
+
+Kapsel adds a non-invasive capsule layer around your existing terminal:
+
+| Problem | Traditional Setup | Kapsel |
+| :--- | :--- | :--- |
+| **Cross-platform commands** | Different commands and syntax across operating systems | Linux-first unified command layer |
+| **Shell configuration** | Global profile files and shell-specific scripts | Self-contained state under `~/.kapsel/` |
+| **Completion** | Separate setup for each shell and tool | Context-aware completion through Carapace |
+| **Developer utilities** | Multiple unrelated tools with different configuration | Unified plugin environment under `kps` |
+| **Extensibility** | Shell-specific integrations | Isolated plugin architecture |
+
+Kapsel does not replace your shell or your system executables. It sits beside
+them and provides an additional, consistent execution environment.
+
+---
+
+## ✨ Features
+
+### 🌐 Native & Cross-Platform Execution
+
+Use your normal system commands directly:
+
+```bash
+git
+docker
+python
+npm
+cargo
+vim
+```
+
+At the same time, Kapsel provides a Linux-first command layer for common
+cross-platform operations:
+
+```bash
+ls -la
+cat package.json
+rm -rf ./dist
+grep -r "TODO" .
+```
+
+Native shell built-ins remain protected from accidental interception.
+
+---
+
+### ⚡ Context-Aware Autocompletion
+
+Kapsel integrates with [Carapace](https://carapace.sh) for rich,
+multi-level command completion.
+
+Completion can understand commands, arguments, flags, and context such as:
+
+- Git branches and tags
+- Docker containers and images
+- Kubernetes resources
+- npm scripts
+- Other supported CLI specifications
+
+Completion specifications are managed declaratively and can be extended
+through plugins or custom specifications.
+
+---
+
+### 💡 Inline Command Suggestions
+
+Kapsel maintains a local SQLite history store and provides asynchronous
+history-based suggestions while you type.
+
+Press `→` to accept a suggestion.
+
+History and related runtime state remain inside the Kapsel sandbox.
+
+---
+
+### 🛡️ Zero-Pollution Environment
+
+Kapsel keeps its own configuration, binaries, history, completion
+specifications, plugins, and logs under:
+
+```text
+~/.kapsel/
+```
+
+It is designed to avoid modifying your existing shell configuration files,
+including:
+
+```text
+.bashrc
+.zshrc
+config.fish
+PowerShell profiles
+```
+
+Your host shell remains yours.
+
+---
+
+### 🧩 Modular Plugin Architecture
+
+Kapsel provides a plugin runtime under the `kps` namespace.
+
+Plugins can add commands, integrations, workflows, completion specifications,
+and external developer tools without becoming part of the Kapsel core.
+
+Official plugins and community plugins share the same extensible architecture.
+
+---
+
+### 🎨 Interactive Terminal Experience
+
+The interactive capsule provides a compact command presentation with:
+
+```text
+╭─ ...
+╰─ ❯ ...
+✔ 0  ...  ⏱ 24ms
+```
+
+Execution status and elapsed time are shown directly after commands, while
+the interface can be localized across multiple languages.
+
+---
+
+# 🚀 Quick Start
+
+## 1. Install
+
+The recommended installation method is:
+
+```bash
+pipx install kapsel-cli
+```
+
+Or:
+
+```bash
+pip install --upgrade kapsel-cli
+```
+
+## 2. Start Kapsel
+
+```bash
+kapsel
+```
+
+You can now use your terminal normally:
+
+```bash
+git status
+docker ps
+python --version
+```
+
+And use Kapsel's cross-platform command layer when needed:
+
+```bash
+ls -la
+cat package.json
+rm -rf ./temp
+```
+
+## 3. Use Kapsel Commands
+
+Kapsel utilities are available through `kps`:
+
+```bash
+kps status
+kps config
+kps portal
+kps ai
+```
+
+For example:
+
+```bash
+kps portal work
+kps ai "explain git rebase"
+kps shore get
+```
+
+## 4. One-Shot Execution
+
+You do not need to enter the interactive capsule to use Kapsel.
+
+From your existing shell:
+
+```bash
+kps status
+kps portal
+kps ai "find large files"
+```
+
+This makes `kps` suitable for scripts, aliases, shell workflows, and
+individual commands.
+
+---
+
+# 🧩 Plugin Ecosystem
+
+Kapsel is designed as a plugin-oriented terminal environment rather than a
+fixed collection of built-in commands.
+
+The ecosystem is divided into **official plugins** and **community plugins**.
+
+## Official Plugins
+
+Kapsel currently provides the following official plugins:
+
+| Plugin | Command | Description | Powered by |
+| :--- | :--- | :--- | :--- |
+| **`portal`** | `kps portal` / `z` | Fast directory navigation with frecency-based selection | [zoxide](https://github.com/ajeetdsouza/zoxide) |
+| **`ai`** | `kps ai` | Terminal AI assistant for generating, explaining, and working with commands | OpenAI / Claude / Ollama |
+| **`init`** | `kps init` | Runtime and toolchain management for Node, Python, Go, Rust, and more | [mise](https://github.com/jdx/mise) |
+| **`shore`** | `kps shore` | Package and OS mirror detection and switching | [chsrc](https://github.com/AkihiroSuda/chsrc) |
+| **`install`** | `kps install` | Unified software installation across multiple package managers | [mpm](https://github.com/MrEiu/mpm) |
+| **`alias`** | `kps alias` | Cross-platform command alias translation | Native Engine |
+| **`autopilot`** | `kps autopilot` | Background task queues and long-running jobs | [pueue](https://github.com/Nukesor/pueue) |
+| **`help`** | `kps help <cmd>` | Practical command documentation and cheat sheets | [tealdeer](https://github.com/dbrgn/tealdeer) |
+| **`fuck`** | `kps fuck` | Automatic command correction and syntax fixing | [thefuck](https://github.com/nvbn/thefuck) |
+| **`profile`** | `kps profile` | Dotfile and workstation configuration management | [chezmoi](https://github.com/twpayne/chezmoi) |
+| **`rec`** | `kps rec` | CLI snippet bookmarking, parameterization, and execution | [pet](https://github.com/knqyf263/pet) |
+
+Official plugins are maintained as separate components so that the core
+runtime can remain small and focused.
+
+---
+
+## 🌍 Community Plugins
+
+Kapsel is intended to grow beyond the official plugin collection.
+
+Community developers can create plugins that extend Kapsel with:
+
+- New commands
+- External tools
+- Developer workflows
+- Service integrations
+- Custom completion specifications
+- Automation utilities
+
+Community submissions can be contributed through the
+**[Kapsel Plugin Repository](https://github.com/MrEiu/plugins)**.
+
+See the plugin documentation for development requirements, specifications,
+and contribution guidelines.
+
+> The official plugin collection is curated by the Kapsel maintainers.
+> Community plugins are developed and maintained by their respective
+> contributors.
+
+---
+
+# 📦 Installation
+
+## Recommended
+
+### pipx
+
+```bash
+pipx install kapsel-cli
+```
+
+### pip
+
+```bash
+pip install --upgrade kapsel-cli
+```
+
+---
+
+## One-Line Automated Installers
+
+### macOS & Linux
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/MrEiu/Kapsel/master/scripts/install.sh | bash
+```
+
+### Windows PowerShell
+
+```powershell
+irm https://raw.githubusercontent.com/MrEiu/Kapsel/master/scripts/install.ps1 | iex
+```
+
+The installers detect the host platform and configure Kapsel and its
+completion environment automatically.
+
+---
+
+## Standalone Binaries
+
+Precompiled releases are available for platforms that do not use Python:
+
+| Platform / Architecture | Release Artifact |
+| :--- | :--- |
+| **Windows x86_64** | `kapsel-windows-x86_64.zip` |
+| **Linux x86_64** | `kapsel-linux-x86_64.tar.gz` |
+| **macOS Universal** | `kapsel-macos-universal.tar.gz` |
+| **Debian / Ubuntu** | `kapsel_amd64.deb` |
+
+See **[GitHub Releases](https://github.com/MrEiu/Kapsel/releases/latest)** for
+the latest artifacts.
+
+---
+
+## Package Managers
+
+Kapsel is also available through:
+
+- **Scoop**
+- **Homebrew**
+- **Debian / Ubuntu packages**
+
+See **[Installation Guide](docs/INSTALLATION.md)** for platform-specific
+instructions and mirrors.
+
+---
+
+## Build from Source
+
+```bash
+git clone https://github.com/MrEiu/Kapsel.git
+cd Kapsel
+pip install -e .
+kps completion sync
+```
+
+---
+
+# ⚙️ Configuration
+
+Kapsel stores its main configuration at:
+
+```text
+~/.kapsel/config.yaml
+```
+
+Configuration can be inspected and changed directly from the terminal:
+
+```bash
+kps config
+```
+
+Open the configuration file:
+
+```bash
+kps config edit
+```
+
+Change individual values:
+
+```bash
+kps config set ui.enable_banner false
+kps config set interaction.autosuggest_sensitivity 0.2
+```
+
+Configuration can be reloaded without restarting the interactive session.
+
+See **[Configuration Guide](docs/configuration.md)** for the complete
+configuration reference.
+
+---
+
+# 🏛️ Architecture
+
+Kapsel is designed as a non-invasive execution layer around the host shell.
+
+```text
+                     Host Terminal
+                           │
+                           ▼
+                ┌─────────────────────┐
+                │       Kapsel        │
+                │                     │
+                │  Command Dispatcher │
+                │  Completion Engine  │
+                │  Plugin Registry    │
+                │  History / State    │
+                └──────────┬──────────┘
+                           │
+                 ┌─────────┴─────────┐
+                 ▼                   ▼
+          Native Executables     Kapsel Commands
+          git / docker / ...      kps <command>
+```
+
+## Dual-State Execution
+
+Kapsel separates two execution paths:
+
+**Native execution**
+
+System executables are passed through to the host environment with normal
+TTY interaction, signals, streams, and process behavior.
+
+**Kapsel execution**
+
+Kapsel-managed commands are dispatched through the `kps` namespace and plugin
+registry.
+
+This separation allows Kapsel to enhance terminal workflows without replacing
+the host shell itself.
+
+---
+
+## Collision-Safe Namespaces
+
+Kapsel maintains explicit command namespaces so that utilities such as:
+
+```text
+alias
+help
+install
+history
+profile
+ps
+kill
+dir
+```
+
+do not silently replace or hijack native shell built-ins.
+
+For commands that may collide with the host environment, Kapsel keeps them
+inside the `kps` namespace.
+
+---
+
+## Zero-Pollution State
+
+All Kapsel-managed state is contained in:
+
+```text
+~/.kapsel/
+├── config.yaml          # Configuration
+├── history.db           # Persistent command history
+├── bin/                 # User-space runtime binaries
+├── specs/               # Completion specifications
+├── plugins/             # Installed plugins
+└── logs/                # Diagnostic and session logs
+```
+
+This keeps Kapsel's runtime state separate from your system and shell
+configuration.
+
+---
+
+# 📚 Documentation
+
+Detailed documentation is maintained separately from the project overview.
+
+| Document | Description |
+| :--- | :--- |
+| [Installation Guide](docs/INSTALLATION.md) | Platform-specific installation and setup |
+| [Configuration](docs/configuration.md) | Configuration options and runtime settings |
+| [Commands](docs/commands.md) | Complete command and option reference |
+| [Plugins](docs/plugins.md) | Plugin architecture and usage |
+| [Plugin Development](https://github.com/MrEiu/plugins) | Creating and submitting plugins |
+| [Architecture](docs/architecture.md) | Internal architecture and design |
+
+---
+
+# 🧪 Development & Testing
+
+Clone the repository:
+
+```bash
+git clone https://github.com/MrEiu/Kapsel.git
+cd Kapsel
+```
+
+Install the development and test dependencies:
+
+```bash
+pip install -e ".[test]"
+```
+
+Run the test suite:
+
+```bash
+pytest tests/ -v
+```
+
+---
+
+# 🤝 Contributing
+
+Contributions to Kapsel are welcome.
+
+There are several ways to contribute:
+
+### Core
+
+Bug fixes, improvements, documentation, tests, and new capabilities for the
+Kapsel core.
+
+### Plugins
+
+Create new plugins or improve existing ones through the
+**[Kapsel Plugin Repository](https://github.com/MrEiu/plugins)**.
+
+### Documentation
+
+Improve examples, guides, translations, and developer documentation.
+
+Before making substantial changes, please open an issue to discuss the
+proposed direction.
+
+---
+
+# 📄 License
+
+Kapsel is open-source software licensed under the
+**[MIT License](LICENSE)**.
+
+---
+
+<div align="center">
+
+**Kapsel — Wrap complexity, expose simplicity.**
+
+Built by [MrEiu](https://github.com/MrEiu) and open-source contributors.
+
+</div>