karnel-termux 4.13.11 → 4.15.0

package/README.md

@@ -8,7 +8,7 @@
 
 <p align="center">
   <a href="https://github.com/israelmarques1024-dotcom/karnel-termux">
-    <img src="https://img.shields.io/badge/version-4.13.11-0078D4?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-4.15.0-0078D4?style=for-the-badge" alt="Version">
   </a>
   <a href="https://www.npmjs.com/package/karnel-termux">
     <img src="https://img.shields.io/npm/v/karnel-termux?style=for-the-badge&logo=npm&color=cb3837" alt="npm">
@@ -33,7 +33,7 @@
 
 Created by **Israel Marques**.
 
-- **41 AI agents** for coding — Claude, Gemini, OpenCode, KeelCode, Qoder, Ollama, Goose, Factory Droid, Cline, Puter, OmniRoute and more
+- **43 AI tools** — Claude, Gemini, OpenCode, Cactus, Hugging Face, Ollama, KeelCode, Goose, Factory Droid and more
 - **8 languages** — Node.js, Python, Go, Rust, C/C++, PHP, Perl, Bun
 - **5 databases** — PostgreSQL, MariaDB, SQLite, MongoDB, Redis
 - **22 dev tools** — gh, curl, fzf, bat, lsd, jq, tmux, openssh, snyk and more
@@ -56,10 +56,15 @@ Created by **Israel Marques**.
 
 ## Installation
 
-### Via curl (recommended)
+### Via checksummed GitHub release (recommended)
 
 ```bash
-bash -c "$(curl -fsSL https://raw.githubusercontent.com/israelmarques1024-dotcom/karnel-termux/main/install.sh)"
+version=4.15.0
+tmpdir=$(mktemp -d) && trap 'rm -rf "$tmpdir"' EXIT
+base="https://github.com/israelmarques1024-dotcom/karnel-termux/releases/download/v$version"
+curl -fsSL "$base/karnel-termux-install.sh" -o "$tmpdir/karnel-termux-install.sh"
+curl -fsSL "$base/karnel-termux-install.sh.sha256" -o "$tmpdir/karnel-termux-install.sh.sha256"
+(cd "$tmpdir" && sha256sum -c karnel-termux-install.sh.sha256) && bash "$tmpdir/karnel-termux-install.sh" --ref "v$version"
 ```
 
 ### Via npm
@@ -80,6 +85,10 @@ After installation, run:
 karnel
 ```
 
+In a terminal, running `karnel` without a command opens a curated menu for
+common workflows. The menu is not a complete inventory of CLI commands,
+aliases, or options; use `karnel help` and the CLI reference for the full set.
+
 ---
 
 ## Usage
@@ -104,7 +113,7 @@ karnel
 | `karnel start editor` | Start code-server (VS Code in browser) |
 | `karnel pg` | PostgreSQL manager |
 | `karnel init <template>` | Initialize projects with templates |
-| `karnel deploy` | Deploy projects (Vercel, Railway, Netlify, Supabase) |
+| `karnel deploy` | Run Vercel, Railway, Netlify, or Supabase CLI commands |
 | `karnel supabase` | Manage the Supabase CLI and remote-project helpers |
 | `karnel robin` | Manage the Robin OSINT service |
 | `karnel --version` | Show installed version |
@@ -115,7 +124,7 @@ karnel
 |--------|-------------|--------------|
 | `lang` | Node.js, Python, Go, Rust, C/C++, PHP, Perl, Bun | `karnel install lang` |
 | `db` | PostgreSQL, MariaDB, SQLite, MongoDB, Redis | `karnel install db` |
-| `ai` | 41 AI agents for coding, including KeelCode | `karnel install ai` |
+| `ai` | 43 AI tools, agents, and local inference clients | `karnel install ai` |
 | `editor` | code-server (VS Code in browser), Neovim, NvChad | `karnel install editor` |
 | `dev` | gh, curl, fzf, bat, lsd, jq and more | `karnel install dev` |
 | `npm` | TypeScript, NestJS CLI, Prettier and more | `karnel install npm` |
@@ -259,7 +268,7 @@ See the bundled reference with `karnel show osint --robin`.
 
 ---
 
-## AI Agents (41)
+## AI Tools (43)
 
 ```bash
 karnel install ai                             # Install all
@@ -278,6 +287,8 @@ karnel install ai --opencode --ollama         # Install specific agents
 | **OpenClaude** | `--openclaude` | Open source Claude Code alternative |
 | **OpenClaw** | `--openclaw` | Personal AI assistant |
 | **Ollama** | `--ollama` | Run open source LLMs locally |
+| **Cactus** | `--cactus` | On-device ARM64 inference through an isolated Ubuntu runtime |
+| **Hugging Face** | `--hugging-face` | Official Hugging Face Hub CLI (`hf`) |
 | **Codex CLI** | `--codex` | OpenAI coding agent |
 | **OpenCode** | `--opencode` | Open source terminal agent |
 | **MiMoCode** | `--mimocode` | Fast open source AI agent |
@@ -361,7 +372,9 @@ karnel brain sync                  # Sync with private GitHub
 
 ## karnel voice
 
-Capture audio from microphone, review in editor, copy to clipboard, and dispatch any AI agent with the transcribed prompt.
+Capture audio from the microphone, optionally review it in an editor, copy it
+to the clipboard, and dispatch an AI agent with the transcribed prompt. If an
+editor is unavailable or no TTY is attached, Karnel uses the raw transcript.
 
 ```bash
 karnel voice opencode              # Record -> edit -> opencode run
@@ -413,7 +426,7 @@ Microphone -> termux-speech-to-text -> editor (edit) -> clipboard -> AI agent
 
 - Termux:API: `pkg install termux-api`
 - App Termux:API: https://karneltermux.vercel.app/termux/api
-- Editor: `karnel install editor`
+- Editor (optional): `karnel install editor`; otherwise use `--raw` or the automatic raw fallback
 
 ---
 
@@ -465,7 +478,8 @@ karnel env ls                        # List variables
 
 ## karnel deploy
 
-Deploy your projects directly from terminal:
+Run an installed platform CLI through Karnel; arguments after the tool name are
+forwarded unchanged:
 
 ```bash
 karnel deploy vercel                  # Deploy to Vercel
@@ -545,7 +559,7 @@ karnel/
 │   │   └── karnel.sh    # Main CLI (with TUI)
 │   ├── modules/       # Module orchestrators
 │   ├── tools/         # Tool installers
-│   │   ├── ai/        # 41 AI agents
+│   │   ├── ai/        # 43 AI tools
 │   │   ├── lang/      # 8 languages
 │   │   ├── db/        # 5 databases
 │   │   ├── dev/       # 22 dev tools

package/docs/ARCHITECTURE.md

@@ -27,7 +27,7 @@ karnel-termux/
 │   │       ├── dev.sh          # Dev tools installer
 │   │       └── ...
 │   ├── tools/                  # Individual tool installers
-│   │   ├── ai/                 # 41 AI agents
+│   │   ├── ai/                 # 43 AI tools
 │   │   ├── lang/               # 8 languages
 │   │   ├── db/                 # 5 databases
 │   │   ├── dev/                # 22 dev tools
@@ -83,6 +83,11 @@ import "@/cli/commands/doctor/code"
 
 The `@` symbol is replaced with `$KARNEL_PATH`. This avoids hardcoded paths.
 
+`import()` is not an idempotent module loader: it calls `source` on every import
+and does not track files already loaded. Top-level assignments and other side
+effects therefore run again when the same file is imported more than once;
+imported files must tolerate repeated evaluation where callers can repeat them.
+
 ### Critical Scope Implication
 
 Because `import()` calls `source` from within a function, any `declare` statement

package/docs/CHANGELOG.md

@@ -1,5 +1,40 @@
 # Documentation Changelog
 
+## 4.15.0 - 2026-08-14
+
+- Replaced the unavailable GGA fork with the official Gentleman Guardian
+  Angel v2.10.1, pinned by commit, with Termux-safe staging, ownership
+  verification, rollback, and non-destructive uninstall.
+- Made backup/restore transactional: staged configs, ancestor symlink
+  rejection, signal-safe rollback, concurrent backup isolation, validated
+  snapshot names, and explicit package/configuration phase separation.
+- Hardened lifecycle ownership so pre-existing installs are never adopted,
+  arbitrary handler exit codes are treated as failures, and stale or empty
+  locks are recovered safely.
+- Pinned release/npm/installer together: the npm package carries a validated
+  `RELEASE_COMMIT`, the release workflow is serialized per tag and refuses
+  divergent partial publications, and the installer activates only a verified,
+  clean checkout.
+- Authenticated security and AI installers with fixed versions and official
+  SHA-256 checksums, safe archive extraction, staging, and rollback; unverifiable
+  upstream assets now fail closed instead of executing unauthenticated bytes.
+- Fixed the npm postinstall to distinguish the npm bin symlink from a complete
+  managed installation, and removed the deprecated `curl | bash` guidance.
+- Updated ShellCheck/syntax/test gates to 294 scripts and added regression
+  suites for backup, lifecycle, installer integrity, and AI installer hardening.
+
+## 4.14.0 - 2026-08-14
+
+- Added tested Cactus 2.0.1 support on ARM64 through Ubuntu Proot with an
+  isolated compatible Python runtime.
+- Added the official Hugging Face `hf` CLI in an isolated native Termux
+  environment, using HTTP transport when the optional Xet Android wheel is
+  unavailable.
+- Made the AI registry authoritative for TUI selection, route discovery, and
+  lifecycle dispatch, with contracts covering all 43 registered tools.
+- Fixed AI reinstall and uninstall error propagation, unknown status handling,
+  binary alias summaries, ownership checks, and stale tool counts.
+
 ## 4.13.11 - 2026-08-10
 
 - Hardened installers to preserve user-managed commands and data, with atomic

package/docs/README.md

@@ -14,7 +14,7 @@
 ## What is Karnel?
 
 Karnel Termux transforms your Android device into a complete development workstation.
-With a single CLI (`karnel`), you can install and manage 41 AI agents, 8 languages,
+With a single CLI (`karnel`), you can install and manage 43 AI tools, 8 languages,
 5 databases, 22 dev tools, 12 utility tools, 2 network tools, 6 games, responsible OSINT, and more.
 
 ## Sections

package/docs/cli/README.md

@@ -4,8 +4,9 @@
 karnel <command> [arguments]
 ```
 
-With no command, Karnel opens its interactive interface (TUI) when a terminal is
-available and prints help in noninteractive contexts.
+With no command, Karnel opens a curated interactive menu (TUI) when a terminal
+is available and prints help in noninteractive contexts. The menu exposes common
+workflows, not every command, alias, or option documented below.
 
 ---
 
@@ -22,7 +23,7 @@ karnel install <module> --tool1 --tool2  # Install specific tools only
 |-----------|-------------|
 | `lang`    | Node.js, Python, Go, Rust, C/C++, PHP, Perl, Bun |
 | `db`      | PostgreSQL, MariaDB, SQLite, MongoDB, Redis |
-| `ai`      | 41 AI agents (OpenCode, Claude Code, KeelCode, Codebuff, Freebuff, Qoder, AMP Code, Cursor CLI, Oh-My-Pi, Goose, Factory Droid, Puter, Ollama, etc.) |
+| `ai`      | 43 AI tools (OpenCode, Cactus, Hugging Face, Claude Code, KeelCode, Goose, Factory Droid, Ollama, etc.) |
 | `editor`  | code-server (VS Code in browser), Neovim, NvChad |
 | `dev`     | gh, curl, fzf, bat, lsd, jq, tmux, openssh, snyk (22 tools) |
 | `npm`     | TypeScript, NestJS CLI, Prettier, Vercel CLI, etc. |
@@ -42,7 +43,7 @@ karnel install <module> --tool1 --tool2  # Install specific tools only
 
 | Module    | Flags |
 |-----------|-------|
-| `ai`      | `--qwen-code`, `--gemini-cli`, `--claude-code`, `--mistral-vibe`, `--openclaude`, `--openclaw`, `--ollama`, `--codex`, `--opencode`, `--mimocode`, `--engram`, `--codegraph`, `--pi`, `--antigravity-cli`, `--minimax-cli`, `--gentle-ai`, `--gga`, `--hermes-agent`, `--kimi-code`, `--command-code`, `--codebuff`, `--freebuff`, `--kilocode-cli`, `--kiro`, `--crush`, `--cline`, `--odysseus`, `--kimchi-code`, `--omni-route`, `--ctx7`, `--openspec`, `--supercode-cli`, `--puter`, `--keelcode`, `--copilot-termux`, `--qoder`, `--ampcode`, `--cursor-cli`, `--oh-my-pi`, `--goose`, `--droid` |
+| `ai`      | `--qwen-code`, `--gemini-cli`, `--claude-code`, `--mistral-vibe`, `--openclaude`, `--openclaw`, `--ollama`, `--codex`, `--opencode`, `--mimocode`, `--engram`, `--codegraph`, `--pi`, `--antigravity-cli`, `--minimax-cli`, `--gentle-ai`, `--gga`, `--hermes-agent`, `--kimi-code`, `--command-code`, `--codebuff`, `--freebuff`, `--kilocode-cli`, `--kiro`, `--crush`, `--cline`, `--odysseus`, `--kimchi-code`, `--omni-route`, `--ctx7`, `--openspec`, `--supercode-cli`, `--puter`, `--keelcode`, `--copilot-termux`, `--qoder`, `--ampcode`, `--cursor-cli`, `--oh-my-pi`, `--goose`, `--droid`, `--cactus`, `--hugging-face` |
 | `db`      | `--postgresql`, `--mariadb`, `--sqlite`, `--mongodb`, `--redis` |
 | `dev`     | `--gh`, `--wget`, `--curl`, `--lsd`, `--bat`, `--proot`, `--ncurses`, `--tmate`, `--openssh`, `--tmux`, `--cloudflared`, `--translate`, `--html2text`, `--jq`, `--bc`, `--tree`, `--fzf`, `--imagemagick`, `--shfmt`, `--make`, `--udocker`, `--snyk` |
 | `lang`    | `--bun`, `--nodejs`, `--python`, `--perl`, `--php`, `--rust`, `--clang`, `--golang` |
@@ -136,7 +137,7 @@ binary/command name, and current install status.
 |-----------|-------|
 | `lang`    | 8 languages |
 | `db`      | 5 databases |
-| `ai`      | 41 AI agents |
+| `ai`      | 43 AI tools |
 | `editor`  | 3 editor components |
 | `dev`     | 22 development tools |
 | `npm`     | 11 npm global modules |
@@ -442,8 +443,9 @@ karnel env ls
 karnel voice [agent] [options]
 ```
 
-Captures audio via `termux-speech-to-text`, opens the transcript in `$EDITOR`,
-copies to clipboard, and dispatches the AI agent.
+Captures audio via `termux-speech-to-text`, optionally opens the transcript in
+`$EDITOR`, copies it to the clipboard, and dispatches the AI agent. If no editor
+is installed or no TTY is available, Karnel continues with the raw transcript.
 
 ### Agent targets
 
@@ -539,18 +541,21 @@ cd . && karnel init                   # Auto-detect
 
 ---
 
-## deploy — Deploy projects
+## deploy — Run deployment CLIs
 
 ```bash
 karnel deploy <tool> [args...]
 ```
 
-| Tool | Platform |
-|------|----------|
-| `vercel` | Vercel (passes remaining args to `vercel`) |
-| `railway` | Railway |
-| `netlify` | Netlify |
-| `supabase` | Supabase |
+`deploy` checks that the selected executable exists, then replaces Karnel with
+that CLI and forwards all remaining arguments.
+
+| Tool | Executable |
+|------|------------|
+| `vercel` | `vercel` |
+| `railway` | `railway` |
+| `netlify` | `netlify` |
+| `supabase` | `supabase`; this is a generic CLI pass-through, not a deployment action by itself |
 
 ```bash
 karnel deploy vercel
@@ -568,19 +573,19 @@ karnel deploy supabase
 karnel supabase <subcommand> [options]
 ```
 
-The top-level command manages Supabase CLI installation and remote-project
-workflows. It does not start the local Supabase stack on Termux; that requires
-Docker on a Linux host.
+The top-level command manages the pinned Supabase CLI installation and provides
+thin wrappers for linked-project workflows. It does not start the local Supabase
+stack on Termux; `supabase start` requires Docker on a Linux host.
 
 | Subcommand | Description |
 |------------|-------------|
-| `doctor` | Check CLI, project configuration, and API reachability |
-| `types` | Generate TypeScript types for a linked project |
-| `migrate` | Run `supabase db <args>` |
-| `link` | Run `supabase link <args>` |
-| `remote-start` / `remote` | Show the remote-development guide |
-| `remote-status` / `status` | Check Supabase status |
-| `install` / `uninstall` | Install or remove the Supabase CLI |
+| `doctor` | Check the CLI, `supabase/config.toml`, Docker expectations, and API reachability |
+| `types` | Run `supabase gen types typescript --linked`; extra arguments are not forwarded |
+| `migrate` | Forward arguments to `supabase db` |
+| `link` | Forward arguments to `supabase link` |
+| `remote-start` / `remote` | Print a guide for running the Docker-backed local stack on a Linux host |
+| `remote-status` / `status` | Run `supabase status`, which reports the local stack rather than hosted-project health |
+| `install` / `uninstall` | Install or remove Karnel's pinned Supabase CLI binary |
 
 ```bash
 karnel supabase install
@@ -589,6 +594,43 @@ karnel supabase types
 karnel supabase migrate push
 ```
 
+The downloaded Linux binary may still fail on Android because of unsupported
+system calls. The wrapper reports a `SIGSYS` failure and recommends PRoot or a
+Linux host; installation alone does not guarantee native Android compatibility.
+
+---
+
+## plugin — Plugin manager
+
+```bash
+karnel plugin <subcommand> [options]
+```
+
+| Subcommand | Description |
+|------------|-------------|
+| `search [query]` | Search the pinned approved registry snapshot |
+| `install <name>` | Install a plugin from that registry |
+| `install <owner/repo> --unsafe` | Install an unreviewed repository after confirmation |
+| `update <name>` | Atomically update an installed plugin |
+| `remove` / `uninstall <name>` | Remove an installed plugin |
+| `list` / `ls` | List installed plugins and their trust source |
+| `create` / `scaffold <name>` | Create and activate a validated local plugin scaffold |
+
+Search accepts `--command <name>`, `--compatible`, and `--capability <name>`.
+Capabilities are `network`, `filesystem-read`, `filesystem-write`, `process`,
+and `environment`. `--unsafe` applies only to `install` and `update`.
+
+Plugins are Bash code, run with the current user's permissions, and are not
+sandboxed. Registry review and manifest validation are not isolation boundaries.
+
+```bash
+karnel plugin search backup --compatible
+karnel plugin install karnel-hello
+karnel plugin install owner/repo --unsafe
+karnel plugin update karnel-hello
+karnel plugin remove karnel-hello
+```
+
 ---
 
 ## pg — PostgreSQL manager
@@ -659,23 +701,29 @@ karnel backup restore [file]
 ```
 
 Creates `$KARNEL_DATA/backups/termux-<timestamp>.tar.gz` with SHA256 checksum.
+Concurrent runs reserve distinct names atomically instead of overwriting a
+backup created in the same second.
 
 ### Included in backup
 
-- All packages (`dpkg --get-selections`)
-- Karnel tool manifest
-- Shell configs (`.bashrc`, `.zshrc`, `.profile`)
+- Package selections embedded under `metadata/packages.list` (`dpkg --get-selections`)
+- A catalog snapshot of tool installer directories, not a record of which tools are installed
+- Selected shell configs (`.bashrc`, `.zshrc`, `.profile`, `.zshenv`, `.inputrc`)
 - Termux configs (fonts, colors, properties)
-- SSH keys
-- `~/.config` app configs
-- APT repositories
+- SSH configuration, known hosts, authorized keys, and public keys; private keys are excluded
+- Selected `~/.config` application directories; `github-copilot`, `nvm`, `coc`, `Code`, and `yarn` are excluded, as are symbolic links and all `.env`, credential, auth, and token files matched by the backup filter
+- `$PREFIX/etc/apt/sources.list` only; files under `sources.list.d` and APT keys are not included
+
+Backups are gzip-compressed, not encrypted. API environment variables and SSH
+private keys are not exported, but copied application configuration can still
+contain credentials. Protect local and cloud copies as sensitive plaintext data.
 
 ### Options
 
 | Flag | Description |
 |------|-------------|
-| `--cloud` | Upload via `rclone` (remote named `karnel`) |
-| `snapshot <name>` | Create a named snapshot |
+| `--cloud` | Legacy plaintext upload; requires explicit `KARNEL_ALLOW_PLAINTEXT_CLOUD_BACKUP=1` acknowledgement |
+| `snapshot <name>` | Create a timestamped named snapshot using the same contents and secret filter as a full backup; names accept 1-64 letters, numbers, dots, underscores, or hyphens |
 | `list` / `ls` | List full backups and snapshots |
 | `info` / `show [file]` | Show a backup's contents (latest if omitted) |
 | `--cron` | Schedule a daily backup at 3:00 AM |
@@ -689,6 +737,11 @@ karnel backup snapshot before-update
 karnel backup list
 ```
 
+Cloud backup is disabled by default because the archive is not encrypted or
+signed. The legacy opt-in uploads both archive and checksum, but they share the
+same remote trust boundary. Package selections and the informational tool
+catalog are embedded in the archive.
+
 ---
 
 ## restore — Full Termux restore
@@ -699,22 +752,28 @@ karnel restore [--cloud] [--list] [<file>]
 
 ### What it restores
 
-- Shell configs to `~/`
+- Selected shell configs to `~/`
 - Termux configs
-- SSH keys
-- `~/.config` directory
-- APT sources
-- Package list (via `dpkg --set-selections` + `apt-get dselect-upgrade`)
-- Karnel tools (from manifest)
-
-Verifies SHA256 checksum automatically if available.
+- SSH configuration and public keys (legacy archives may also contain private keys)
+- The selected `.config` directories present in the archive
+- `$PREFIX/etc/apt/sources.list` when present
+- Embedded package selections (via `dpkg --set-selections` + `apt-get dselect-upgrade`)
+- The tool catalog is retained as metadata only; Karnel does not incorrectly reinstall every tool in the source catalog
+
+Requires and verifies the SHA256 checksum before extraction. Restore rejects
+archives containing traversal paths, links, devices, or other unsafe entries.
+Configuration is first merged into staging so unrelated existing files remain
+in place, then committed with local backups. A copy, move, or package-restore
+failure rolls configuration back instead of reporting a partial success.
+Package-manager operations themselves are not transactionally reversible by
+Karnel if `apt-get` changes package state before returning an error.
 
 ### Options
 
 | Argument | Description |
 |----------|-------------|
 | `<file>` | Path to a specific backup file |
-| `--cloud` | Download and restore via the `karnel` rclone remote |
+| `--cloud` | Legacy unauthenticated cloud restore; requires `KARNEL_ALLOW_UNAUTHENTICATED_CLOUD_RESTORE=1` |
 | `--list`, `-l` | List available full backups and snapshots |
 | `--help`, `-h` | Show help |