karnel-termux 4.13.9 → 4.13.11

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.9-0078D4?style=for-the-badge" alt="Version">
+    <img src="https://img.shields.io/badge/version-4.13.11-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">
@@ -166,6 +166,10 @@ user's permissions. They are not sandboxed. Registry plugins have reviewed
 metadata and are staged, validated, and atomically activated, but you should
 still review code you do not trust.
 
+Each Karnel release pins and verifies one reviewed registry snapshot. New
+registry entries become available after updating Karnel to a release that
+includes that snapshot.
+
 Installing an arbitrary GitHub repository requires both `--unsafe` and an
 interactive confirmation:
 
@@ -304,7 +308,7 @@ karnel install ai --opencode --ollama         # Install specific agents
 | **Cursor CLI** | `--cursor-cli` | Official Cursor AI agent adapted for Termux (glibc) |
 | **Oh-My-Pi** | `--oh-my-pi` | Enhanced Pi agent with native Rust addons |
 | **Goose CLI** | `--goose` | AI agent framework by Block (native Termux musl) |
-| **Factory Droid** | `--droid` | Enterprise AI agent (via proot-distro Ubuntu) |
+| **Factory Droid** | `--droid` | Enterprise AI agent (Ubuntu proot-distro with pinned npm package) |
 | **Supercode CLI** | `--supercode-cli` | Supercode CLI — official npm package |
 | **Puter CLI** | `--puter` | Puter CLI for sites and workers |
 | **KeelCode** | `--keelcode` | Hosted coding-agent CLI |

package/docs/ARCHITECTURE.md

@@ -0,0 +1,131 @@
+# Karnel Architecture
+
+## Project Structure
+
+```
+karnel-termux/
+├── karnel/
+│   ├── bin/karnel              # Entry point (bash script, in PATH)
+│   ├── cli/
+│   │   ├── karnel.sh           # Main CLI dispatcher (TUI + command routing)
+│   │   └── commands/           # Each subcommand is a separate file
+│   │       ├── help.sh
+│   │       ├── install.sh
+│   │       ├── doctor.sh       # Doctor command + inline checks
+│   │       ├── doctor/         # Doctor code subsystem (4 modules)
+│   │       ├── brain.sh
+│   │       ├── env.sh
+│   │       ├── pg.sh
+│   │       ├── voice.sh
+│   │       ├── init.sh
+│   │       ├── deploy.sh
+│   │   ├── ... (27 .sh files + doctor/ subdir)
+│   ├── modules/                # Module orchestrators
+│   │       ├── ai.sh           # AI agent installer
+│   │       ├── lang.sh         # Language installer
+│   │       ├── db.sh           # Database installer
+│   │       ├── dev.sh          # Dev tools installer
+│   │       └── ...
+│   ├── tools/                  # Individual tool installers
+│   │   ├── ai/                 # 41 AI agents
+│   │   ├── lang/               # 8 languages
+│   │   ├── db/                 # 5 databases
+│   │   ├── dev/                # 22 dev tools
+│   │   ├── editor/             # Code editor
+│   │   ├── npm/                # Global npm packages
+│   │   ├── shell/              # ZSH plugins
+│   │   ├── ui/                 # Termux UI
+│   │   ├── auto/               # Automation
+│   │   ├── deploy/             # Deploy CLIs
+│   │   ├── network/            # 2 network tools (dark, dedsec-network)
+│   │   ├── utils/              # 12 utility tools (fconv, notes, zork, SuperFile, etc.)
+│   │   └── osint/              # Robin OSINT integration
+│   └── utils/                  # Shared utilities
+│       ├── bootstrap.sh        # Import mechanism, shell detection
+│       ├── banner.sh           # ASCII banners
+│       ├── colors.sh           # ANSI color definitions
+│       ├── log.sh              # Logging (info, warn, error, success, box)
+│       ├── env.sh              # Environment configuration (XDG paths, UI opts)
+│       └── version.sh          # Version comparison utilities
+├── install.sh                  # Bootstrap installer
+├── package.json                # npm publishing
+├── scripts/npm-install.js      # postinstall hook
+├── assets/                     # Images, logos
+├── tests/                      # Test scripts
+└── docs/                       # Documentation
+```
+
+## Import Mechanism
+
+Karnel uses a custom `import()` function instead of `source`:
+
+```bash
+import() {
+  local base="${KARNEL_PATH}"
+  local resolved="${1/@/$base}.sh"
+  local canonical
+  canonical="$(realpath "$resolved" 2>/dev/null || readlink -f "$resolved" 2>/dev/null || echo "$resolved")"
+  if [[ "$canonical" != "$base"/* ]] || [[ "$canonical" == *".."* ]]; then
+    echo "karnel: import error: path traversal denied: $1" >&2
+    return 1
+  fi
+  if [[ ! -f "$canonical" ]]; then
+    echo "karnel: import error: $canonical not found" >&2
+    return 1
+  fi
+  source "$canonical"
+}
+
+# Usage:
+import "@/utils/log"
+import "@/cli/commands/doctor/code"
+```
+
+The `@` symbol is replaced with `$KARNEL_PATH`. This avoids hardcoded paths.
+
+### Critical Scope Implication
+
+Because `import()` calls `source` from within a function, any `declare` statement
+at the top level of a sourced file creates a **local** variable scoped to `import()`,
+not a global. This is a common source of bugs.
+
+**Rules:**
+- `declare -A` at top level → **local** to `import()` ❌
+- `declare -gA` inside a function → **global** ✅
+- `VAR=value` updates the nearest dynamically scoped variable
+- `local var` inside a function → **local** ✅
+
+Persistent imported state should use `declare -g` explicitly rather than relying
+on the caller's dynamic scope.
+
+## Module System
+
+Each module (`lang`, `db`, `ai`, `dev`, etc.) has:
+
+1. A **module orchestrator** in `karnel/modules/<name>.sh` — handles installation logic
+2. Individual **tool installers** in `karnel/tools/<name>/<tool>/install.sh` — each installs one tool
+
+Robin uses a managed layout because its configuration and investigations are
+persistent user data:
+
+- Source checkout: `$KARNEL_TOOLS/osint/robin/app`
+- Virtual environment: `$KARNEL_TOOLS/osint/robin/.venv`
+- Provider configuration: `$KARNEL_CONFIG/robin/.env`
+- Investigations: `$KARNEL_DATA/robin/investigations`
+- PID and logs: `$KARNEL_RUN` and `$KARNEL_LOGS`
+
+The upstream release and commit are pinned in `tools/osint/robin/common.sh`.
+Candidate source and virtualenv trees are verified before replacing the active
+installation. Uninstall does not delete persistent data.
+
+### Tool Installer Pattern
+
+```bash
+_tool_dependencies() { ... }    # Declare dependencies
+_tool_install() { ... }          # Install the tool
+_tool_postinstall() { ... }      # Post-installation setup
+```
+
+## Doctor Subsystem Architecture
+
+See [Doctor System](./doctor/README.md) for the complete breakdown of the doctor code analysis engine.

package/docs/CHANGELOG.md

@@ -0,0 +1,194 @@
+# Documentation Changelog
+
+## 4.13.11 - 2026-08-10
+
+- Hardened installers to preserve user-managed commands and data, with atomic
+  staging for downloaded payloads and native binaries.
+- Added verified plugin registry snapshots, npm release pinning, and regression
+  contracts for installers, ownership, and package postinstall behavior.
+- Added Android-compatible Railway installation through Ubuntu Proot and
+  verified Railway and Netlify CLI installation on Termux.
+- Synchronized CLI, GitHub README, npm metadata, and site documentation.
+- Corrected the portable npm postinstall fixture used by release validation.
+
+## 4.13.10 - 2026-08-06
+
+- Included root documentation in the npm package and synchronized help, TUI, and release assets.
+
+## 4.13.9 - 2026-08-06
+
+- Completed tool documentation coverage and corrected CLI references, commands, flags, links, and catalog counts.
+
+## 4.13.8 - 2026-08-06
+
+- Added KeelCode through the official `@keelcode-ai/keelcode` npm package.
+- Added SuperFile built from pinned upstream source `v1.5.0`.
+
+## 4.13.7 - 2026-08-04
+
+### Plugin System
+
+- Registry entries may now share a repository when each uses a distinct plugin
+  path, enabling multiple reviewed plugins from the official registry source.
+- Plugin removal acquires the lifecycle lock before recovery and deletion,
+  preventing a concurrent update from restoring a removed plugin.
+- Registry downloads refuse HTTPS-to-HTTP redirect downgrades.
+
+## 4.13.6 - 2026-08-03
+
+### Fixes
+
+- Reject missing values for `karnel voice --lang` before argument parsing can
+  consume another option.
+- Harden plugin command validation by rejecting hidden, non-shell, symlinked,
+  and undeclared command entries.
+- Permit the documented root plugin path (`"path": "."`) in reviewed registry
+  entries while retaining traversal protection.
+- Clarified CLI help, deployment requirements, and site documentation so they
+  match current behavior.
+
+## 4.13.5 - 2026-08-01
+
+### Release hardening
+
+- `karnel update karnel` now resolves the latest GitHub release tag, downloads the
+  tag-pinned `karnel-termux-install.sh` and `.sha256` assets, verifies the SHA-256
+  checksum before running, and only then falls back to git/npm/pnpm. The Release
+  workflow attaches both immutable installer assets to each tag.
+- GitHub Releases are created before npm publishing, so a failing npm publish no
+  longer blocks the release.
+- The site catalog CI now verifies that the generated catalog has not drifted from
+  a pinned CLI checkout (`generate-catalog.mjs --check`).
+
+### Fixes
+
+- Repaired the Freebuff installer (release tag, asset name, download URL, binary
+  rename) and verified install/update on Termux aarch64.
+- `karnel list` detects Kiro, KiloCode, and Cursor via any of their binaries.
+- Added troubleshooting documentation covering npm tokens, releases, Vercel, and
+  update failures.
+- Synchronized documentation with the 39-entry AI registry and the 4 deploy CLIs.
+
+## 4.9.0 - 2026-07-20
+
+### New modules
+
+- Added `network` module with 2 tools: dark (Dark Web OSINT Tor crawler) and
+  dedsec-network (multi-purpose network scanner/OSINT/pentest).
+- Added `utils` module with 11 utility scripts: fconv, filecheck, websites,
+  notes, treex, passman, applaunch, splash, httptmux, zork, and qrcode.
+
+### Documentation
+
+- Created READMEs for all 13 new tools under `karnel/tools/network/` and
+  `karnel/tools/utils/`.
+- Updated `open.sh` with `network` and `utils` targets for browser docs.
+- Updated root README, docs index, CLI reference, and architecture docs with
+  the new module counts and tool descriptions.
+- Bumped version to 4.9.0.
+
+## 4.8.0 - 2026-07-18
+
+### Robin OSINT
+
+- Added the `osint` module and `karnel robin` lifecycle command.
+- Pinned Robin `v2.8` and validated its source commit before activation.
+- Added a transactional source/venv installation path for Termux aarch64.
+- Separated application code, provider configuration, and investigations.
+- Added safe migration from the original single-directory layout.
+- Added process identity validation, Streamlit readiness checks, Tor probes,
+  versioned responsible-use acknowledgement, and explicit data purge.
+- Added `karnel start robin`, global status integration, and
+  `karnel doctor robin [--network]`.
+
+### Quality and release
+
+- Expanded catalog documentation from 24 to 32 development tools.
+- Added complete Bash/Zsh syntax validation, Robin contract tests, ShellCheck
+  error gating, npm package inspection, CI, and release automation.
+- Corrected competing stderr redirections in three installers.
+
+## Unreleased - 2026-07-16
+
+### Doctor command surface
+
+- Added `karnel doctor code` alongside the existing Termux diagnostics.
+- Kept exactly two operational Doctor subcommands: `termux` and `code`.
+- Removed the stale `karnel doctor fix` entry from the main help. Termux fixes remain
+  available through `karnel doctor termux --fix`.
+- Synchronized the Doctor AI probe and documentation with the 39-entry registry,
+  including Copilot-Termux.
+
+### Code analysis engine
+
+- Added project detection for 25 language and ecosystem labels.
+- Added a registry with 76 check definitions and 68 distinct tool labels.
+- Added quick, standard, and deep modes with 64, 74, and 76 definitions,
+  respectively.
+- Added text reports and clean JSON output.
+- Added safe and unclassified auto-fix modes.
+- Added bounded subproject discovery through four directory levels.
+
+### Correctness fixes
+
+- Declared persistent arrays with `declare -g`/`declare -gA` so they survive the
+  function-scoped `import()` mechanism.
+- Replaced space-delimited tool output with one registry record per line.
+- Added a parser that preserves shell pipelines inside registry commands.
+- Fixed file discovery that incorrectly expected NUL-delimited `find` output.
+- Run language checks and fixes inside the matching manifest directory while
+  keeping cross-language checks at the requested project root.
+- Preserve command exit statuses, including silent failures and timeouts.
+- Quote sample file paths with Bash `%q` before shell execution.
+- Prevent `npx` checks from downloading packages by using `--no-install`.
+- Resolve compound tool labels such as `npm audit`, `go test`, `cargo test`, and
+  `docker compose` to their real executables.
+- Run gofmt over discovered Go files instead of passing a directory, and send
+  javac output to the temporary directory instead of `/dev/null`.
+- Parse Python files through `ast` instead of `compileall`, preventing diagnostics
+  from creating `__pycache__` artifacts in the analyzed project.
+- Run cross-language checks once per project instead of once per detected language.
+- Skip placeholder-based checks when no compatible sample file exists.
+- Apply fixes only to findings, preserve the target directory, and report failed
+  fix commands accurately.
+- Match fixes by both tool and category so tools with multiple checks do not apply
+  unrelated corrections.
+- Emit standalone JSON with the analyzed directory, result count, category,
+  severity, and details.
+- Record the requested target directory in text reports instead of `$PWD`.
+
+### Detection fixes
+
+- Preserve the root directory through recursive scans so subprojects are registered.
+- Scan `.github/workflows` and detect GitHub Actions YAML files.
+- Merge YAML detection so GitHub Actions is no longer shadowed by Ansible rules.
+- Recognize scoped Angular and NestJS packages.
+- Associate framework names with their language for terminal display.
+- Detect Python for all supported Python manifest variants.
+- Normalize manifest records for JavaScript, Django, CMake, Maven, Gradle, and .NET.
+
+### Termux diagnostics
+
+- Made `--quick` stop after essential system and package checks instead of running
+  the extended network and I/O probes.
+- Added explicit timeouts to Termux information and battery probes so a missing or
+  unresponsive Termux:API service cannot block the full diagnostic run.
+- Generate the Markdown report after auto-fixes so the `Fixed` count is accurate.
+- Use explicit `skipped` values for quick-mode sections in the report.
+- Fixed Python cache cleanup so version-directory globs expand correctly.
+- Quote packages returned by `pip check` before reinstalling them.
+
+### Verification
+
+- Expanded `tests/smoke.sh` from 10 to 14 checks.
+- Added syntax coverage for nested Doctor modules.
+- Added registry count and pipeline-parsing regression tests.
+- Added GitHub Actions, Python manifest, TypeScript, and NestJS detection tests.
+- Verified clean JSON with Python's standard JSON parser.
+- Verified modified shell files with ShellCheck at style severity.
+
+## Security note
+
+Doctor executes third-party analysis tools in the selected project. Review tool
+configuration and use version control before enabling fixes. `npx` checks do not
+install missing packages automatically.

package/docs/README.md

@@ -0,0 +1,31 @@
+# Karnel Termux Documentation
+
+> Modular Dev Environment for Termux — install languages, databases, AI agents, editors, and more with one command
+
+## Quick Links
+
+- [CLI Commands](./cli/README.md) — All `karnel` subcommands
+- [Doctor System](./doctor/README.md) — Environment diagnosis and code analysis
+- [Troubleshooting](./troubleshooting.md) — Common issues and fixes
+- [Architecture Overview](./ARCHITECTURE.md)
+- [Bug Fixes & Changelog](./CHANGELOG.md)
+- [Official Documentation Site](https://karneltermux.vercel.app/karnel/doctor)
+
+## 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,
+5 databases, 22 dev tools, 12 utility tools, 2 network tools, 6 games, responsible OSINT, and more.
+
+## Sections
+
+- **[CLI Commands](./cli/README.md)** — Full reference for every `karnel` subcommand
+- **[Doctor System](./doctor/README.md)** — How `karnel doctor` works, code analysis engine, environment checks
+- **[Robin OSINT](../karnel/tools/osint/robin/README.md)** — Responsible use, lifecycle, data locations, and troubleshooting
+- **[Network Tools](../karnel/tools/network/dark/README.md)** — dark, dedsec-network
+- **[KeelCode](../karnel/tools/ai/keelcode/README.md)** — Hosted coding-agent CLI: `karnel install ai --keelcode`
+- **[SuperFile](../karnel/tools/utils/superfile/README.md)** — Terminal file manager: `karnel install utils --superfile`
+- **[Utility Scripts](../karnel/tools/utils/fconv/README.md)** — fconv, notes, treex, SuperFile, passman, applaunch, splash, httptmux, zork, qrcode and more
+- **[Supabase CLI](./cli/README.md#supabase--remote-project-helpers)** — `karnel supabase` remote-project helpers
+- **[Architecture](./ARCHITECTURE.md)** — Project structure, module system, import mechanism
+- **[Changelog](./CHANGELOG.md)** — Version history, bug fixes, known issues