ADR-0004 — Aggiornamento dei CLI dalle Impostazioni

Stato: Proposta
Data: 2026-10-15
Collegato a: ADR-0002 (motori), INSTALL.md

Contesto

L'app usa i CLI già installati dall'utente. Un CLI vecchio può smettere di funzionare senza che l'app c'entri: su questa macchina Codex 0.144.3 ha come modello predefinito (~/.codex/config.toml) gpt-6-astra, che richiede un Codex più recente, e ogni messaggio con "Predefinito" fallisce con requires a newer version of Codex. L'unico rimedio è aggiornare il CLI, oggi da terminale, e l'utente non sa nemmeno che esiste una versione nuova.

Sulla macchina di sviluppo il 2026-10-15 i due CLI sono stati poi aggiornati (Codex 0.144.3 → 0.162.1, Claude Code 2.1.252 → 2.1.300) e Codex con il modello predefinito risponde: il problema si risolve aggiornando. Resta il bisogno di saperlo e di farlo dall'app.

Entrambi i CLI hanno un comando di aggiornamento che controlla e, se c'è una versione nuova, la installa: claude update (alias upgrade: "Check for updates and install if available") e codex update ("Update Codex to the latest version"). Verificato con --help il 2026-10-15; l'esecuzione reale non è ancora stata provata.

Criteri di decisione

L'app dice se c'è una versione nuova prima di proporre l'aggiornamento: evidenzia solo dove serve.
L'utente aggiorna un CLI alla volta, senza uscire dall'app.
L'app non tocca nulla senza un gesto esplicito (nessun aggiornamento automatico).
Si usa il comando ufficiale del CLI, non una procedura inventata dall'app.
Se l'aggiornamento non è possibile (installazione via gestore di pacchetti, permessi, rete) l'utente vede il motivo e il comando manuale giusto.
Funziona su Windows e Linux e non blocca la GUI.

Decisione

Nel riquadro Impostazioni, sezione Aggiornamenti: una riga per ogni CLI installato con nome, versione e pulsante Aggiorna. Ogni pulsante agisce solo su quel CLI.
Controllo prima dell'aggiornamento (sola lettura, nessuna installazione): l'app confronta la versione installata (<cli> --version) con l'ultima pubblicata.
- Claude Code: GET https://downloads.claude.ai/claude-code-releases/latest, testo con la versione (la stessa sorgente dell'installer nativo).
- Codex: GET https://api.github.com/repos/openai/codex/releases/latest, campo tag_name (es. rust-v0.162.1, si estrae 0.162.1).
- Antigravity: GET https://antigravity-cli-auto-updater-974169037036.us-central1.run.app, testo con Stable Version: X.Y.Z (la sorgente dell'auto-updater ufficiale presente nel binario agy).
- Le versioni si ricavano con il primo numero N.N.N del testo e si confrontano come versioni. Verificate il 2026-10-15 e 2026-10-18.
- Disponibile (ultima > installata): la riga mostra "Aggiornamento disponibile: X", il pulsante Aggiorna è evidenziato (colore d'accento) e un puntino d'accento compare sul pulsante Impostazioni. Aggiornato (uguale o più nuova): riga neutra con "Aggiornato", pulsante normale, nessun puntino; resta cliccabile per forzare update. Sconosciuto (rete assente, risposta non valida, timeout di 10 s): "Controllo non riuscito", pulsante normale, nessun errore invasivo.
- Quando si controlla: all'avvio, in background, e ogni volta che si apre il riquadro Impostazioni se l'ultimo controllo ha più di 5 minuti; subito dopo un aggiornamento. Mai in modo da rallentare la chat. Le richieste non inviano identificativi; l'app contatta solo gli indirizzi ufficiali sopra.
Flusso di un clic: legge la versione (<cli> --version), lancia <cli> update (stdin chiuso, output catturato, tempo massimo 10 minuti), rilegge la versione e mostra l'esito sulla riga:
- versione cambiata ⇒ "Aggiornato da X a Y";
- exit 0 e versione invariata ⇒ "Già aggiornato (X)";
- exit ≠ 0, tempo scaduto o eseguibile assente ⇒ errore con le ultime righe dell'output e il comando manuale adatto (sotto).
Pulsanti disabilitati mentre una risposta è in corso o un altro aggiornamento è attivo; la chat non parte durante l'aggiornamento.

Comando manuale scelto dal metodo di installazione, dedotto dal percorso reale dell'eseguibile (collegamenti simbolici risolti):

Percorso contiene	Metodo	Claude Code	Codex	Antigravity
`node_modules`, `.npm`	npm	`npm install -g @anthropic-ai/claude-code@latest`	`npm install -g @openai/codex@latest`	`agy update`
`Cellar`, `homebrew`, `linuxbrew`	Homebrew	`brew upgrade claude-code` (o `claude-code@latest`)	`brew upgrade --cask codex`	`brew upgrade agy`
`WinGet`, `WindowsApps`	WinGet	`winget upgrade Anthropic.ClaudeCode`	script PowerShell di INSTALL.md	`agy update`
altro	nativo/script	`claude update` da terminale	script di installazione di INSTALL.md	`agy update`

L'app mostra il comando, non lo esegue: un'installazione globale con npm o un gestore di pacchetti può richiedere permessi o scelte che spettano all'utente.

Dopo un aggiornamento riuscito le versioni mostrate si rileggono; la chat aperta non cambia.
L'aggiornamento di un CLI non rilancia la chat in corso: l'eventuale errore di versione già mostrato resta nella cronologia.

Opzioni considerate

Opzione	Esito	Motivo
Solo documentare `codex update`	Scartata	L'utente deve uscire dall'app e conoscere il comando.
Solo `update`, senza controllo preventivo	Scartata	Non dice se serve e non può evidenziare il pulsante: `update` controlla ma installa subito.
Controllo con `npm view`	Scartata	Richiede npm anche per installazioni native.
Aggiornamento automatico all'avvio	Scartata	Modifica programmi dell'utente senza un suo gesto.
Fallback automatico a npm/brew/winget	Scartata	Permessi (`sudo`), scelta del canale e rischi di installazioni doppie spettano all'utente.
Controllo con le sorgenti ufficiali (annuncio delle versioni) + pulsante per CLI con `update` ufficiale + comando manuale suggerito	Scelta	Ufficiale, sicura, uguale su Windows e Linux, evidenzia solo quando serve.

Conseguenze

Positive: il caso "richiede un Codex più recente" si risolve dall'app; l'esito è comprensibile; nessuna azione nascosta. Negative / costi: il controllo richiede rete e due indirizzi esterni (GitHub ha un limite di richieste anonime, per questo c'è la cache di 5 minuti); il canale scelto da Claude Code (latest o stable) può dare un "disponibile" che claude update non installa, e in quel caso l'esito dopo l'aggiornamento è "Già aggiornato"; l'esito dipende dal testo e dal comportamento dei comandi update dei CLI, che possono cambiare; su Windows l'aggiornamento di un eseguibile in uso da un'altra sessione può fallire; un controllo della versione senza installare non c'è.

Da verificare

Il controllo evidenzia correttamente in tutti i casi (installato più vecchio, uguale, più nuovo di latest) e senza rete.
Utente sul canale stable di Claude Code: il confronto con latest dà falsi "disponibile"; valutare di leggere anche /stable o autoUpdatesChannel.
Esecuzione reale di claude update e codex update su Linux e Windows, con installazione nativa e con npm: esito, exit code e testo. (Su Linux/WSL i due CLI risultano aggiornati alle ultime versioni; non è stato registrato l'output.)
Cosa stampano quando sono già aggiornati e quando falliscono per permessi.
Che --version di entrambi si possa leggere in un secondo dopo l'aggiornamento (nessun file bloccato).
Il tempo massimo di 10 minuti è adeguato (rete lenta).

Riferimenti

Passi: ROADMAP.md, Fase 4.
Matrice dei test: TESTING.md, righe UP.

7.7 KiB Raw Permalink Blame History