@mmmbuto/gemini-cli-termux 0.22.7-termux → 0.24.1-termux

package/bundle/docs/patches/CONTEXT_MEMORY_COMPARISON.md

@@ -0,0 +1,306 @@
+# Confronto: contextMemory.ts vs JIT Context Memory
+
+## Tabella Comparativa
+
+| Caratteristica          | contextMemory.ts (Termux)     | JIT Context Memory (Upstream) |
+| ----------------------- | ----------------------------- | ----------------------------- |
+| **Architettura**        | Dual JSON + Journal           | Lazy loader + Event system    |
+| **Persistenza**         | 3 file (base/user/journal)    | File .gemini.md esistenti     |
+| **Formato**             | JSON strutturato              | Markdown nativo               |
+| **Validazione**         | Ajv schema (UUID, date, enum) | Nessuna                       |
+| **Scoping**             | global/host/project           | None                          |
+| **Sensitivity filter**  | Sì (low/medium/high)          | No                            |
+| **Expiration**          | Sì (expiresAt)                | No                            |
+| **Journal append-only** | Sì (JSONL)                    | No                            |
+| **Compaction**          | Sì (automatica)               | No                            |
+| **MCP import**          | Sì (integrato)                | No                            |
+| **UI sync events**      | No                            | Sì (CoreEvent.MemoryChanged)  |
+| **Performance**         | Batch load + merge            | Lazy load                     |
+| **Complessità**         | Alta (~650 righe)             | Media (~150 righe)            |
+| **Configurabilità**     | Molto alta                    | Bassa (on/off)                |
+| **Portable**            | Sì (JSON)                     | No (dipende da file system)   |
+
+---
+
+## Analisi Dettagliata
+
+### 1. Architettura
+
+#### contextMemory.ts (Termux)
+
+```
+base.json (read-only, di default)
+  ↓
+user.json (read-write)
+  ↓
+user.journal.jsonl (append-only)
+  ↓
+merge + compaction → snapshot in user.json
+```
+
+**Vantaggi:**
+
+- Separazione netta tra base (amministratore) e user (utente)
+- Journal append-only per tracciabilità
+- Compaction automatica quando journal > 2MB
+- Merge-safe (più processi possono scrivere nel journal)
+
+#### JIT Context Memory (Upstream)
+
+```
+ContextManager.refresh()
+  ↓
+loadGlobalMemory() → .gemini/Instruction.md
+  ↓
+loadEnvironmentMemory() → *.gemini.md nel workspace
+  ↓
+getUserMemory() → getGlobalMemory() + getEnvironmentMemory()
+```
+
+**Vantaggi:**
+
+- Usa file .gemini.md esistenti (niente nuovi formati)
+- Lazy loading (carica solo quando serve)
+- Event system per UI sync
+- Semplice da capire
+
+---
+
+### 2. Formato Dati
+
+#### contextMemory.ts
+
+```json
+{
+  "version": 1,
+  "updatedAt": "2025-12-27T10:00:00Z",
+  "compactionMeta": {
+    "journalBytesProcessed": 1024,
+    "lastCompactedAt": "2025-12-27T09:00:00Z"
+  },
+  "entries": [
+    {
+      "id": "550e8400-e29b-41d4-a716-446655440000",
+      "text": "Preferisco Vim come editor",
+      "key": "editor:preference",
+      "scope": "global",
+      "tags": ["editor", "vim"],
+      "sensitivity": "low",
+      "expiresAt": "2026-12-27T10:00:00Z",
+      "confidence": 0.9,
+      "source": "tool"
+    }
+  ]
+}
+```
+
+**Pro:**
+
+- Schema validato (Ajv)
+- Tipi forte (UUID, date-time, enum)
+- Metadati ricchi (confidence, expiration, sensitivity)
+- Supporto per chiavi personalizzate (key)
+
+**Contro:**
+
+- Verboso
+- Non editabile a mano facilmente
+- Dipende da JSON parser
+
+#### JIT Context Memory
+
+```markdown
+# Instruction.md
+
+Preferisco Vim come editor.
+
+Uso Termux su Android.
+
+---
+```
+
+**Pro:**
+
+- Semplice
+- Editabile a mano
+- Nativo Gemini
+
+**Contro:**
+
+- Non strutturato
+- Nessuna validazione
+- Nessun metadato
+
+---
+
+### 3. Feature Uniche
+
+#### contextMemory.ts (Solo Termux)
+
+1. **Sensitivity Filter**
+
+```typescript
+function filterHighSensitivity(entries) {
+  return entries.filter((e) => e.sensitivity !== 'high');
+}
+```
+
+Evita di leakare informazioni sensibili all'LLM.
+
+2. **Expiration**
+
+```typescript
+if (e.expiresAt && Date.parse(e.expiresAt) < now) continue;
+```
+
+Le entry scadute vengono automaticamente ignorate.
+
+3. **Journal Append-Only**
+
+```typescript
+await fsp.appendFile(options.paths.journal, `${line}\n`, { mode: 0o600 });
+```
+
+Tracciabilità completa delle modifiche.
+
+4. **MCP Import**
+
+```typescript
+mcpImport: {
+  enabled: false,
+  categories: ['identity', 'infrastructure', 'projects', 'workflow', 'base'],
+  scope: 'global'
+}
+```
+
+Importa memoria da MCP server remoto.
+
+5. **Runtime Options**
+
+```typescript
+setRuntimeContextMemoryOptions(options);
+```
+
+Permette di cambiare configurazione a runtime.
+
+#### JIT Context Memory (Solo Upstream)
+
+1. **UI Sync Events**
+
+```typescript
+coreEvents.emit(CoreEvent.MemoryChanged, {
+  fileCount: this.loadedPaths.size,
+});
+```
+
+La UI si aggiorna quando la memoria cambia.
+
+2. **Lazy Loading** Carica solo quando serve, non all'avvio.
+
+3. **Workspace Integration** Integrato con `workspaceContext.getDirectories()`.
+
+---
+
+### 4. Performance
+
+#### contextMemory.ts
+
+- **Avvio**: Legge 3 file JSON (piccoli)
+- **Update**: Append al journal (O(1))
+- **Compaction**: Periodica (ogni 2MB journal)
+- **Memoria**: 50 entry max, 20KB max
+
+#### JIT Context Memory
+
+- **Avvio**: Scansione file system (\*.gemini.md)
+- **Update**: Riscrittura file .md
+- **Refresh**: Manuale (`/memory` o evento)
+- **Memoria**: Dipende da dimensione file .md
+
+**Vincitore**: contextMemory.ts per startup time, JIT per memoria usage.
+
+---
+
+### 5. Sicurezza
+
+#### contextMemory.ts
+
+```typescript
+fs.writeFileSync(filePath, payload, { mode: 0o600 }); // rw-------
+```
+
+- File con permessi 0600
+- Sensitivity filter
+- Validazione UUID
+- Sanitizzazione input
+
+#### JIT Context Memory
+
+- Nessuna misura specifica
+- Dipende da permessi file system
+
+**Vincitore**: contextMemory.ts
+
+---
+
+## Quale è Migliore?
+
+### Per Termux/Android: **contextMemory.ts** ⭐
+
+**Motivi:**
+
+1. Filesystem mobile è lento → JSON piccolo meglio di scansione .md
+2. Startup time critico su mobile → batch load più veloce
+3. Sensitivity filter → privacy su dispositivo personale
+4. MCP import → utile per integrazione con server MCP
+5. Compaction automatica → evita file grandi che occupano spazio
+
+### Per Desktop/Workstation: **JIT Context Memory** ⭐
+
+**Motivi:**
+
+1. Filesystem veloce → scansione .md non è problema
+2. Semplicità → utenti possono editare .gemini.md a mano
+3. UI sync → esperienza desktop più ricca
+4. Workspace integration → meglio per progetti multipli
+
+---
+
+## Conclusione
+
+| Scenario                  | Raccomandazione                                |
+| ------------------------- | ---------------------------------------------- |
+| **Termux/Android**        | contextMemory.ts                               |
+| **Desktop single-user**   | JIT Context Memory                             |
+| **Desktop multi-user**    | contextMemory.ts (per sensitivity filter)      |
+| **Sviluppo attivo**       | JIT Context Memory (più semplice da mantenere) |
+| **Produzione/Enterprise** | contextMemory.ts (più robusto)                 |
+
+### Per il Merge
+
+**Mantenere contextMemory.ts come feature Termux-exclusive.**
+
+Il sistema JIT è buono per desktop, ma contextMemory.ts è superiore per:
+
+- Dispositivi mobili (filesystem lento)
+- Privacy (sensitivity filter)
+- Integrazione MCP
+- Robustezza (validazione, compaction)
+
+JIT può essere usato come fallback opzionale per utenti che preferiscono il
+sistema upstream.
+
+```typescript
+if (!experimentalJitContext) {
+  // Termux-optimized: contextMemory.ts
+  const result = await loadContextMemory(contextMemoryOptions);
+} else {
+  // Upstream: JIT context
+  await contextManager.refresh();
+}
+```
+
+---
+
+**Autore**: DioNanos **Data**: 2025-12-27 **Verdetto**: contextMemory.ts è
+migliore per Termux, JIT è meglio per desktop

package/bundle/docs/patches/MERGE_TO_0.24_ANALYSIS.md

@@ -0,0 +1,321 @@
+# Merge Analysis: 0.22.7-termux → 0.24.0-nightly
+
+**Date**: 2025-12-27 **Current**: v0.22.7-termux **Target**:
+v0.24.0-nightly.20251227.37be16243 **Delta**: ~55 commits upstream
+
+---
+
+## Executive Summary
+
+Passare alla 0.24.0-nightly è **fattibile** ma richiede la risoluzione di
+conflitti in 5 file. Le patch Termux essenziali sono isolate e possono essere
+preservate.
+
+### Raccomandazione
+
+**Procedere con il merge alla 0.24.0-nightly** per le seguenti ragioni:
+
+1. **Feature upstream importanti**: JIT context, A2A client, extension
+   management, security fixes
+2. **Patch Termux preservabili**: Tutte le nostre patch sono in file separati o
+   isolati
+3. **Conflitti gestibili**: Solo 5 file con conflitti, tutti risolvibili
+
+---
+
+## Patch Termux da Preservare (Essential)
+
+| File/Feature                                        | Status      | Action Required                  |
+| --------------------------------------------------- | ----------- | -------------------------------- |
+| `packages/core/src/utils/termux-detect.ts`          | ✅ OK       | Nessuna azione (file nuovo)      |
+| `scripts/postinstall.cjs`                           | ✅ OK       | Ri-aggiungere in package.json    |
+| `scripts/termux-setup.sh`                           | ✅ OK       | Nessuna azione (file nuovo)      |
+| `scripts/termux-tools/`                             | ✅ OK       | Nessuna azione (directory nuova) |
+| `package.json` - `postinstall` script               | ⚠️ CONFLICT | Manuale: keep ours               |
+| `package.json` - `@esbuild/android-arm64`           | ⚠️ CONFLICT | Manuale: re-add                  |
+| `packages/cli/src/config/config.ts` - `isTermux()`  | ⚠️ CONFLICT | Manuale: merge both              |
+| `packages/core/src/index.ts` - termux-detect export | ✅ OK       | Verifica solo                    |
+
+---
+
+## File con Conflitti (5)
+
+### 1. package-lock.json
+
+**Risoluzione**: `git checkout --ours package-lock.json` e poi `npm install`
+
+### 2. package.json
+
+**Conflitto**:
+
+- Nome versione: `@google/gemini-cli` vs `@mmmbuto/gemini-cli-termux`
+- Version: `0.24.0-nightly` vs `0.24.0-termux`
+- Scripts: `postinstall` mancante upstream
+- Dependencies: `@esbuild/android-arm64` mancante upstream
+
+**Risoluzione**:
+
+```json
+{
+  "name": "@mmmbuto/gemini-cli-termux",
+  "version": "0.24.0-termux",
+  "repository": {
+    "url": "https://github.com/DioNanos/gemini-cli-termux.git"
+  },
+  "scripts": {
+    // ... upstream scripts ...
+    "postinstall": "node scripts/postinstall.cjs || true"
+  },
+  "files": ["bundle/", "scripts/postinstall.cjs", "README.md", "LICENSE"],
+  "dependencies": {
+    // ... upstream deps ...
+    "@esbuild/android-arm64": "^0.27.1"
+  }
+}
+```
+
+### 3. packages/cli/src/config/config.ts
+
+**Conflitto**: Context memory (nostra implementazione) vs JIT context (upstream)
+
+Upstream ha aggiunto `experimentalJitContext` in
+`settings.experimental?.jitContext`. La nostra implementazione context memory è
+più complessa (base/user/journal split).
+
+**Risoluzione**:
+
+```typescript
+// Mantenere entrambe le logiche con fallback
+const contextMemoryOptions = buildContextMemoryOptions(settings);
+const experimentalJitContext = settings.experimental?.jitContext ?? false;
+
+let memoryContent = '';
+let fileCount = 0;
+let filePaths: string[] = [];
+
+if (!experimentalJitContext) {
+  // Nostro context memory system
+  const result = await loadServerHierarchicalMemory(
+    cwd,
+    [],
+    debugMode,
+    quietMode,
+    memoryImportFormat,
+    memoryFileFiltering,
+    settings.context?.discoveryMaxDirs,
+    contextMemoryOptions,
+  );
+  memoryContent = result.memoryContent;
+  fileCount = result.fileCount;
+  filePaths = result.filePaths;
+} else {
+  // Upstream JIT context (minimal)
+  const result = await loadServerHierarchicalMemory(
+    cwd,
+    [],
+    debugMode,
+    quietMode,
+    memoryImportFormat,
+    memoryFileFiltering,
+    settings.context?.discoveryMaxDirs,
+  );
+  memoryContent = result.memoryContent;
+  fileCount = result.fileCount;
+  filePaths = result.filePaths;
+}
+```
+
+**Import da preservare**:
+
+```typescript
+import {
+  isTermux,
+  setRuntimeContextMemoryOptions,
+} from '@google/gemini-cli-core';
+```
+
+**Logica isTermux da preservare**:
+
+```typescript
+const allowedTools = argv.allowedTools || settings.tools?.allowed || [];
+if (isTermux() && !allowedTools.includes(SHELL_TOOL_NAME)) {
+  allowedTools.push(SHELL_TOOL_NAME);
+}
+```
+
+### 4. packages/core/src/config/config.ts
+
+**Conflitto**: Import type differences
+
+**Risoluzione**: Keep ours (include context memory types)
+
+### 5. packages/core/src/utils/shell-utils.ts
+
+**Conflitto**: web-tree-sitter import position
+
+Upstream ha spostato l'import dentro la funzione. Noi lo abbiamo in alto.
+
+**Risoluzione**: Keep upstream (la loro ottimizzazione è migliore)
+
+---
+
+## Feature Upstream Notevoli (0.22.7 → 0.24.0)
+
+| Commit      | Feature                              | Relevance to Termux |
+| ----------- | ------------------------------------ | ------------------- |
+| `37be16243` | Shell command allowlisting in policy | 🔒 Security         |
+| `563d81e08` | In-CLI extension install/uninstall   | 🆕 Feature          |
+| `02a36afc3` | A2A Client Manager                   | 🆕 Feature          |
+| `6be034392` | Automatic `/model` persistence       | 📱 UX               |
+| `3b1dbcd42` | Secrets sanitization                 | 🔒 Security         |
+| `e9a601c1f` | MCPServerConfig fix                  | 🔧 Bugfix           |
+| `e6344a8c2` | Project-level hook warnings          | 🔒 Security         |
+| `0a216b28f` | Fix EIO crash in readStdin           | 🐛 Bugfix           |
+| `8feeffb29` | Fix infinite relaunch loop           | 🐛 Bugfix           |
+| `2e229d3bb` | JIT context memory                   | 🚀 Performance      |
+
+---
+
+## Procedure di Merge
+
+### Step 1: Preparazione
+
+```bash
+cd ~/Dev/gemini-cli-termux
+git fetch upstream --tags
+git checkout -b merge-0.24.0-termux
+```
+
+### Step 2: Merge
+
+```bash
+git merge v0.24.0-nightly.20251227.37be16243 --no-edit
+```
+
+### Step 3: Risoluzione Conflitti
+
+```bash
+# 1. package-lock.json - keep ours
+git checkout --ours package-lock.json
+
+# 2. package.json - edit manuale
+# (vedere sezione sopra)
+
+# 3. packages/cli/src/config/config.ts - merge manuale
+# (vedere sezione sopra)
+
+# 4. packages/core/src/config/config.ts - keep ours
+git checkout --ours packages/core/src/config/config.ts
+
+# 5. packages/core/src/utils/shell-utils.ts - keep upstream
+git checkout --theirs packages/core/src/utils/shell-utils.ts
+```
+
+### Step 4: Verifica
+
+```bash
+# Verifica patch Termux
+bash scripts/check-termux-patches.sh
+
+# Verifica imports
+grep -r "isTermux" packages/cli/src/config/config.ts
+grep "termux-detect" packages/core/src/index.ts
+
+# Build test
+npm install --ignore-optional --ignore-scripts
+npm run build
+npm run bundle
+node bundle/gemini.js --version  # deve essere 0.24.0-termux
+```
+
+### Step 5: Commit
+
+```bash
+git add .
+git commit -m "merge: upstream v0.24.0-nightly + Termux patches preserved
+
+- Merged v0.24.0-nightly.20251227.37be16243 (55 commits)
+- Preserved Termux patches:
+  - termux-detect.ts utility
+  - postinstall.cjs message
+  - termux-setup.sh helper
+  - termux-tools/ integration
+  - isTermux() in config.ts
+  - Context memory system (base/user/journal)
+- Resolved conflicts in 5 files
+- Version bump to 0.24.0-termux
+"
+```
+
+### Step 6: Tag e Test
+
+```bash
+git tag v0.24.0-termux
+npm run bundle
+# Test su Termux
+```
+
+---
+
+## Aggiornamenti da Fare Post-Merge
+
+### docs/patches/README.md
+
+Aggiornare versione a 0.24.0-termux e aggiungere nuove feature upstream.
+
+### README.md
+
+Aggiornare versione expected da:
+
+```markdown
+gemini --version # expected: 0.22.2-termux (npm latest)
+```
+
+a:
+
+```markdown
+gemini --version # expected: 0.24.0-termux (npm latest)
+```
+
+### package.json (packages/cli)
+
+Aggiornare versione e sandboxImageUri.
+
+---
+
+## Rischio e Mitigazione
+
+| Rischio                   | Probabilità | Mitigazione                            |
+| ------------------------- | ----------- | -------------------------------------- |
+| Context memory regression | Bassa       | Test completo memory system            |
+| Shell tool breakage       | Bassa       | Verificare isTermux() logic            |
+| Build failure             | Molto bassa | --ignore-optional --ignore-scripts     |
+| npm publish issues        | Bassa       | Verificare files array in package.json |
+
+---
+
+## Checklist Pre-Merge
+
+- [ ] Backup del branch corrente (`git branch backup-pre-0.24`)
+- [ ] Fetch upstream tags
+- [ ] Verificare che `termux-detect.ts` è esportato in core/index.ts
+- [ ] Verificare che `postinstall.cjs` esiste
+- [ ] Verificare che `scripts/termux-tools/` è completo
+
+---
+
+## Checklist Post-Merge
+
+- [ ] Tutti i 5 conflitti risolti
+- [ ] `bash scripts/check-termux-patches.sh` passa
+- [ ] `npm run build` completa senza errori
+- [ ] `npm run bundle` crea `bundle/gemini.js`
+- [ ] `node bundle/gemini.js --version` mostra 0.24.0-termux
+- [ ] Test funzionali su Termux (shell, clipboard, etc.)
+- [ ] Aggiornato README.md
+- [ ] Aggiornato docs/patches/README.md
+- [ ] Creato tag v0.24.0-termux
+
+---
+
+**Autore**: DioNanos **Data**: 2025-12-27 **Stato**: Pronto per merge

package/bundle/docs/patches/README.md

@@ -0,0 +1,62 @@
+# Termux Patches (0.22.7-termux testing)
+
+Minimal changes to run `gemini-cli` on Android/Termux ARM64 without native deps.
+
+## Patch List
+
+1. **Clipboard (TERMUX\_\_PREFIX)** – On Termux set `TERMUX__PREFIX` from
+   `$PREFIX` so clipboardy detects Termux correctly.
+2. **Optional native modules** – Leave `node-pty`, `keytar`, `tree-sitter-bash`
+   in `optionalDependencies`; build failures are tolerated.
+3. **Core exports** – `packages/core/src/index.ts` re-exports stdio utilities,
+   hook/telemetry APIs, Termux detectors, and context-memory helpers so CLI
+   bundling succeeds on Termux.
+4. **Bundle** – Prebuilt `bundle/gemini.js` shipped in npm package
+   (ARM64/Android) with policy files under `bundle/policies/`.
+5. **is-in-ci override** – Prevents ink from detecting Termux as CI.
+6. **Punycode warning** – Suppresses deprecation warning on Android.
+7. **Termux detection** – `packages/core/src/utils/termux-detect.ts` utility.
+8. **Postinstall message** – Clear success message on Termux install.
+9. **Context memory revamp** – Dual JSON (base RO + user RW) plus journal
+   (`user.journal.jsonl`), auto-load toggles, primary selector, and MCP import
+   tool (disabled by default; base writes still gated).
+10. **Mobile-first settings** – Compact `/settings` rendering by default on
+    Termux; TTS toggle exposed (opt-in).
+11. **Shell parser fix** – Tree-sitter for bash loaded lazily after Base64
+    polyfill; resolves `Uint8Array.fromBase64` crash on Termux Node 22/24.
+
+## New in 0.22.7 (testing)
+
+- **Gemini 3 Flash preview** exposed in model list/help.
+- MCP import tool (`mcp_import_memory`) to pull remote MCP data into base/user
+  memories when enabled.
+- Context memory split (base/user/journal) with merge-safe compaction and
+  high-sensitivity auto-load filtering.
+- Mobile settings view default-on; TTS enable/disable switch.
+- Bash parser initialization hardened for Termux runtime (fixes
+  `run_shell_command` crashes).
+
+## New in 0.22.2
+
+- Termux-API tool discovery support (`scripts/termux-tools/`)
+- Improved installation experience (`scripts/postinstall.js`)
+- Helper scripts for build from source (`scripts/termux-setup.sh`)
+- Makefile targets: `termux-install`, `termux-clean`
+- Merge verification script (`scripts/check-termux-patches.sh`)
+
+## Expected Warnings
+
+- Missing native modules may log warnings on Termux; functionality remains
+  (non-PTY shell, plain token storage).
+
+## Scope
+
+No functional changes to upstream features; only compatibility/export fixes.
+
+## Merge Strategy
+
+All patches are designed to be merge-safe. See
+[docs/termux-api/MERGE_STRATEGY.md](../termux-api/MERGE_STRATEGY.md) for details
+on maintaining patches after upstream sync.
+
+**Version**: 0.22.7-termux (testing) / latest dist-tag: 0.22.2-termux