davideandClaude Sonnet 5.5
6080a65edc
Test unitari e di processo per AG-01…AG-12 e UP-21, righe della matrice spuntate. Percorsi aggiornati in ROADMAP, ADR-0001 e TESTING; PROJECT_STATE con lo stato dei test e il debito sulla prova con agy reale. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
62 lines
5.1 KiB
Markdown
62 lines
5.1 KiB
Markdown
# ADR-0001 — GUI multipiattaforma in solo C# con Avalonia
|
|
|
|
- **Stato**: Accettata (implementata; restano due verifiche, vedi sotto)
|
|
- **Data**: 2026-10-15
|
|
- **Sostituisce**: la parte "GUI WinForms + WebView2 + `ui.html`" di [MVP.md](../MVP.md) (le sezioni interessate rimandano a questo ADR)
|
|
|
|
## Contesto
|
|
L'app nasce per Windows: GUI WinForms con un solo WebView2 che carica `ui.html` (HTML/CSS/JS), CLI in `Program.cs`. L'obiettivo ora è avere **un eseguibile standalone per Windows e Linux** nel modo più semplice, **scritto interamente in C#, senza HTML**.
|
|
|
|
Oggi non è possibile: WinForms e WebView2 sono solo Windows, il csproj punta a `net10.0-windows`, la cronologia usa `%LOCALAPPDATA%`. La CLI invece è già portabile.
|
|
|
|
## Criteri di decisione
|
|
1. Un solo codice sorgente, compilabile per `win-x64` e `linux-x64`.
|
|
2. Standalone: publish single-file self-contained, senza runtime né librerie da installare oltre a quanto offre un normale desktop.
|
|
3. Solo C# (e XAML per il layout): niente HTML/CSS/JS.
|
|
4. Mantenere la GUI a finestra (chat con barra laterale, markdown, selettori modello/effort).
|
|
5. Riuso massimo della logica esistente (`claude -p`, sessioni, cronologia JSON, Markdig).
|
|
|
|
## Opzioni considerate
|
|
| Opzione | Esito | Motivo |
|
|
|---|---|---|
|
|
| Mantenere WinForms + WebView2 | Scartata | Solo Windows, e richiede HTML. |
|
|
| Photino / WebView nativa | Scartata | Richiede HTML e, su Linux, webkit2gtk da installare: non standalone. |
|
|
| Server HTTP locale (Kestrel) + browser | Scartata | Portabile e semplice, ma la UI resta HTML e non è una finestra propria. |
|
|
| MAUI | Scartata | Nessun supporto desktop Linux ufficiale. |
|
|
| Terminal.Gui (TUI) | Alternativa | Puro C#, binario leggero, ma è un'interfaccia da terminale, non una finestra. |
|
|
| **Avalonia UI** | **Scelta** | GUI nativa, C# + XAML, render Skia, Windows e Linux, publish single-file self-contained. |
|
|
|
|
## Decisione
|
|
La GUI viene riscritta con **Avalonia UI**:
|
|
- Layout in XAML, logica in C# con `ViewModel` e binding. `ui.html`, il protocollo `WebMessage` e le dipendenze WinForms/WebView2 spariscono.
|
|
- Rendering markdown con un **renderer proprio** che trasforma l'albero di Markdig in controlli Avalonia (`src/agent-wiki-ui/Gui/MarkdownView.cs`), al posto della conversione in HTML. Si è scelto di non usare `Markdown.Avalonia` perché l'ultima versione pubblicata (11.0.x) è per Avalonia 11, mentre si usa Avalonia 12. I link `http(s)` si aprono nel browser di sistema.
|
|
- Un solo progetto con target `net10.0` (non più `net10.0-windows`). Due publish single-file self-contained: `win-x64` e `linux-x64`.
|
|
- La CLI (`Program.cs` con argomenti) resta com'è e funziona su entrambi i sistemi.
|
|
- La cronologia usa `Environment.SpecialFolder.LocalApplicationData` (`%LOCALAPPDATA%` su Windows, `~/.local/share` su Linux), sottocartella `<nome-app>/chats`. Il nome viene da un'unica costante (vedi [Nome del progetto](../README.md#nome-del-progetto)).
|
|
- La logica di avvio del processo (cartella dell'exe, stdin chiuso, `ArgumentList`) viene estratta in **un solo punto** condiviso da CLI e GUI, eliminando la duplicazione oggi segnalata in `AGENT.md` (già `CLAUDE.md`). Si lega all'astrazione "motore" di [ADR-0002](0002-motori-cli-claude-codex-antigravity.md).
|
|
- L'aspetto (token di colore, tipografia, accessibilità) resta definito in [MVP.md](../MVP.md) → "Design (UI/UX)", tradotto in risorse/stili Avalonia. Il tema segue il sistema (chiaro/scuro) tramite `ThemeVariant`.
|
|
|
|
## Conseguenze
|
|
**Positive**
|
|
- Un solo eseguibile per sistema, senza dipendenze di runtime.
|
|
- Nessun HTML/JS da mantenere; il vincolo STA di WinForms/WebView2 non c'è più.
|
|
- Pulizia della duplicazione CLI/GUI.
|
|
|
|
**Negative / costi**
|
|
- Riscrittura della sola parte GUI (`Gui.cs` + `ui.html`), più ampia di una soluzione basata sul browser.
|
|
- Eseguibile più pesante (include Avalonia/Skia).
|
|
- Perdita di alcune comodità del web: la resa del markdown (tabelle, blocchi di codice, pulsante Copia) dipende dalla libreria scelta e va riprodotta o adattata.
|
|
- Su Linux serve un desktop con X11 o XWayland e le librerie di base (fontconfig ecc.).
|
|
|
|
## Da verificare (prima di passare a "Accettata")
|
|
- [x] Rendering markdown: tabelle, citazioni, liste, codice, link ed enfasi verificati con uno screenshot headless in tema chiaro e scuro (libreria `Markdown.Avalonia` scartata, vedi Decisione).
|
|
- [x] Il publish single-file `linux-x64` (48 MB con compressione) parte; verificato su WSL2 con WSLg. **Da verificare** su una distribuzione desktop pulita.
|
|
- [x] Il publish single-file `win-x64` si compila e la CLI parte (provata da WSL tramite interoperabilità). **Da verificare** la GUI su Windows nativo.
|
|
- [x] `claude` viene trovato nel PATH su Linux e la CLI mantiene exit code e codice 127 (provato con un `claude` finto).
|
|
- [ ] Il tema chiaro/scuro segue il sistema anche su Linux (impostato con `RequestedThemeVariant="Default"`; non verificato su un desktop reale).
|
|
- [x] Le chat esistenti restano leggibili (stesso formato JSON). Se il nome cambia cambia anche la cartella dati: la vecchia cartella viene migrata (fatto per `LlmRun` → `agent-wiki-ui`).
|
|
|
|
## Riferimenti
|
|
- Piano di lavoro: [ROADMAP.md](../ROADMAP.md), Fase 5.
|
|
- Specifica funzionale della chat: [MVP.md](../MVP.md).
|