🛡️ Nota sulla Verifica del Core: La riga inferiore dei badge dedicati a sicurezza, isolamento dello sourcing, integrità delle sezioni e chaos test API viene eseguita rigorosamente ed esclusivamente sul file eseguibile core ./bash4llm per garantire Zero-Leakage, conformità all'Architettura Piatta e una resilienza superiore.

Bash4LLM⁺ — Wrapper CLI sicuro, Bash-first, modulare e interamente controllabile per l'interfacciamento con API LLM compatibili con OpenAI (con provider Groq incorporato di serie ed estendibile ad altri tramite moduli esterni).

Bash4LLM⁺ è uno script singolo, auto-contenuto, leggibile e progettato per non avere dipendenze esterne al di fuori dei comandi POSIX standard e delle utilità di base della shell.

Funziona in modo nativo su: Linux, macOS, WSL, Cygwin, Termux (Android) e BSD.

• Lista modelli dinamica ed esente da obsolescenza
  Ottenuta tramite interrogazione degli endpoint live (GET /v1/models). Nessun nome di modello è hardcoded all'interno del core script.
• Sicurezza e Sandboxing a livello di Filesystem
  Nessun uso di cartelle condivise globali come /tmp. File temporanei isolati tramite directory esclusive di processo (RUN_TMPDIR) con permessi restrittivi 700 (umask 077). Divieto assoluto dell'uso di eval.
• Cryptographic Vault incorporato (--vault)
  Integrazione opzionale basata su OpenSSL per conservare e gestire in modo sicuro le chiavi API sul filesystem. Le chiavi vengono cifrate con algoritmo AES-256-CBC mediante Master Password e derivazione della chiave PBKDF2 (100.000 iterazioni). Supporta una chiave di ripristino (Recovery Key) offline di emergenza e lo sblocco della sessione di shell (_B4L_RT_CTX) per evitare costanti richieste di password.
• Portabilità su Termux / Android
  Rilevamento automatico dell'ambiente Android Termux per aggirare i limiti del kernel o di SELinux sull'uso di flock. La gestione della concorrenza sui file viene deviata in modo trasparente sul meccanismo atomico di directory lock (mkdir).
• Sistema di Stato UI (ui_state)
  Il CORE espone in tempo reale metadati operativi in formato JSON atomico (scrittura protetta da lock) per agevolare l'integrazione strutturata con pannelli di controllo esterni, GUI o automazioni di terze parti (es. Home Assistant).
• Caching conversazionale e Session Engine avanzato
  Supporta sessioni multi-turn e gestione della cronologia dei thread in formato NDJSON. L'integrazione del modulo opzionale session-engine.sh consente la segmentazione automatica dei file storici (rotazione e compressione automatica dei blocchi superiori a 1MB) e caching in memoria con TTL per massimizzare la reattività.
• Estendibilità modulare
  Caricamento on-demand di provider esterni (Gemini, Hugging Face, Mistral) posizionati nella cartella degli extras, con isolamento dinamico delle sole definizioni delle funzioni e verifiche di integrità.

Bash4LLM⁺ richiede che i seguenti pacchetti siano disponibili nel PATH:

• bash (versione 4.0 o superiore)
• coreutils (stat, chmod, mkdir, ecc.)
• findutils
• util-linux
• awk
• curl
• jq

# 1. Clona il repository (solo l'ultimo commit per massima velocità)
git clone --depth 1 --branch main https://github.com/kamaludu/bash4llm.git repo-bash4llm  

# 2. Crea una cartella di lavoro ed estrai l'eseguibile
mkdir -p bash4llm
cp repo-bash4llm/bin/bash4llm bash4llm/
chmod +x bash4llm/bash4llm

# 3. Entra nella cartella e aggiorna i modelli 
cd bash4llm 
./bash4llm --refresh-models

# 4. Installazione degli Extras
./bash4llm --install-extras ../repo-bash4llm/extras/

Istruzioni di installazione dettagliate sono disponibili in INSTALL.

Prompt diretto:

./bash4llm "Fornisci una spiegazione sintetica del protocollo SSH."

Pipe di standard input:

cat codice.sh | ./bash4llm "Ottimizza questo script Bash"

Uso di un modello specifico:

./bash4llm -m llama-3.3-70b-versatile "Spiega il paradosso di Fermi."

Esecuzione simulata (Dry-Run):

./bash4llm --dry-run "Genera una risposta fittizia"

Uso di un provider esterno (se installato e configurato):

./bash4llm --provider gemini "Traduci in inglese il seguente testo"

Il binario principale bash4llm agisce come la Root of Trust del sistema. Per prevenirne la manomissione da parte di processi non autorizzati, applica i comandi di protezione rapidi per la tua piattaforma:

• Linux (GNU/Linux):

  sudo chown root:root /path/to/bash4llm && sudo chmod 755 /path/to/bash4llm
  sudo chattr +i /path/to/bash4llm  # Immutabilità Kernel

• macOS / BSD:

  sudo chown root:wheel /path/to/bash4llm && sudo chmod 755 /path/to/bash4llm
  sudo chflags schg /path/to/bash4llm  # Flag System Immutable

• Termux (Android):

  chmod 500 ~/bash4llm  # Sola lettura/esecuzione per l'utente sandbox

• WSL / Cygwin (Windows):

  setfacl -b /path/to/bash4llm 2>/dev/null  # Pulizia ACL Windows
  chmod 755 /path/to/bash4llm

📖 Guida Completa: Per istruzioni dettagliate, consulta il file: SECURITY.md.

Oltre alla standard CI/CD cross-platform, l'eseguibile ./bash4llm viene sottoposto a 5 audit automatizzati continui di sicurezza e architettura, focalizzati esclusivamente sul file sorgente del core:

1. Section Marker Integrity Audit: Valida la Flat Architecture a 23 Sezioni, verificando la simmetria al 100% dei tag, le ancore di coda e prevenendo il leak di sottosezioni ($N.X$).
2. Sourcing Isolation & Namespace Audit: Testa _cleanup_sourced_env per garantire che l'importazione via source di bash4llm in una shell interattiva lasci Zero Function Leaks nella memoria della shell padre.
3. Security & Process List Leak Audit: Esegue vere transazioni curl verso endpoint mock locali campionando ps aux ad intervalli di 5ms, dimostrando che le API Key Bearer non finiscono mai nella tabella dei processi di sistema. Applica e verifica il rispetto dei permessi POSIX 0700 e 0600 sul file system.
4. API Chaos & Resilience Mock Suite: Simula il fault-injection (errori HTTP 500, rate limit ed edge-case di completamento vuoto) utilizzando un Mock Server HTTP Python locale.
5. Extras SHA-256 Manifest Integrity: Verifica gli hash crittografici di tutte le estensioni rispetto a extras/manifest.sha256 per prevenire tampering o moduli corrotti.

Per facilitare l'integrazione di monitoraggio o automazione (come Home Assistant o pannelli grafici locali), Bash4LLM⁺ scrive in modo atomico metadati di stato aggiornati all'interno della cartella:

bash4llm.d/config/ui_state/

I file disponibili sono:

• threads/<thread_id>.json → Stato specifico del thread (active, msg_count, last_ts, title).
• threads/index.json → Indice strutturato contenente l'elenco dei thread attivi.
• last_api.json → Metadati dell'ultima chiamata effettuata (http_status, finish_reason, req_id, edgecase_detected).
• last_history.json → Dettagli sull'ultimo file salvato fisicamente nella cartella cronologia.
• provider_capabilities.json → Informazioni sul provider in uso (se supporta streaming, modelli, o refresh).

Bash4LLM⁺ è rilasciato sotto licenza GNU GPL v3.
Vedi il file LICENSE per maggiori dettagli.

• Autore: Cristian Evangelisti
• Email: opensource@cevangel.anonaddy.me
• Repository: GitHub kamaludu/bash4llm