davideandClaude Sonnet 5.5
d4b6c3693a
Nuovo ADR-0005: su Windows l'eseguibile è senza console, così il doppio clic mostra solo la GUI, e la CLI riaggancia il terminale padre. L'alternativa a due file resta registrata. MVP, README e CLAUDE.md spiegano la conseguenza sull'exit code (disponibile solo se il chiamante attende il processo, con start /wait o Start-Process -Wait); TESTING.md aggiunge le righe WIN. Co-Authored-By: Claude Sonnet 5.5 <noreply@anthropic.com>
46 lines
3.8 KiB
Markdown
46 lines
3.8 KiB
Markdown
# ADR-0005 — Windows: eseguibile senza finestra di console
|
|
|
|
- **Stato**: Proposta
|
|
- **Data**: 2026-10-15
|
|
- **Collegato a**: [ADR-0001](0001-gui-multipiattaforma-avalonia.md) (GUI e piattaforme)
|
|
|
|
## Contesto
|
|
Su Windows l'eseguibile è di tipo "console" (`OutputType` `Exe`): con il doppio clic, oltre alla finestra della GUI si apre anche un terminale vuoto che resta aperto finché l'app gira. Il tipo console serve alla CLI (`agent-wiki-ui.exe "prompt"`), perché da terminale `cmd` e PowerShell aspettano la fine del programma, mostrano l'output e danno l'exit code. Un eseguibile "GUI" non ha console, ma allora la CLI perde queste proprietà. Su Linux il problema non esiste: nessuna finestra extra.
|
|
|
|
## Criteri di decisione
|
|
1. Doppio clic: solo la finestra della GUI.
|
|
2. La CLI deve continuare a mostrare l'output nel terminale da cui parte, anche con reindirizzamenti (`> file`, `| altro`).
|
|
3. Un solo file da distribuire, come per Linux.
|
|
4. Nessun cambiamento per Linux.
|
|
|
|
## Opzioni considerate
|
|
| Opzione | Esito | Motivo |
|
|
|---|---|---|
|
|
| Lasciare il tipo console e nascondere la finestra all'avvio (`FreeConsole`) | Scartata | La finestra compare comunque per un istante; con Windows Terminal come terminale predefinito può restare una scheda. |
|
|
| Due file: `agent-wiki-ui.exe` (senza console) e `agent-wiki-ui-cli.exe` (con console) | Alternativa valida | Nessuna perdita nella CLI (exit code corretto ovunque), ma due file da distribuire e da spiegare. Da riprendere se l'exit code della CLI diventa importante in Windows. |
|
|
| **Un solo `.exe` senza console; la CLI riaggancia il terminale padre** | **Scelta** | Un file, doppio clic pulito, output visibile nel terminale. |
|
|
|
|
## Decisione
|
|
- Il progetto usa `OutputType` **`WinExe`** (sottosistema Windows). Su Linux non cambia nulla.
|
|
- Con **argomenti** (modalità CLI) su Windows, `Core/ConsoleHost.cs` chiama `AttachConsole(ATTACH_PARENT_PROCESS)`: se parte da `cmd`, PowerShell o Windows Terminal l'app usa quel terminale. Se l'output standard non è già valido (non è reindirizzato) lo collega alla console (`CONOUT$`); se è un file o una pipe ereditati li lascia stare, così `> file` e `|` funzionano. Il motore avviato dopo eredita gli stessi handle.
|
|
- Senza terminale padre (doppio clic, avvio da un altro programma) l'attacco fallisce in silenzio e l'app prosegue.
|
|
- Senza argomenti (GUI) non si tocca la console.
|
|
|
|
## Conseguenze
|
|
**Positive**: il doppio clic mostra solo la finestra; un unico file; output e reindirizzamenti della CLI funzionano.
|
|
**Negative / costi — comportamento della CLI su Windows**:
|
|
- `cmd` e PowerShell **non aspettano** la fine di un programma a sottosistema Windows: il prompt torna subito e l'output compare dopo, mescolato al prompt.
|
|
- L'**exit code** non arriva a `%ERRORLEVEL%` né a `$LASTEXITCODE` in uso interattivo. Arriva se il chiamante aspetta il processo: `start /wait agent-wiki-ui.exe "prompt"` in `cmd`, `Start-Process -Wait -NoNewWindow` o `& .\agent-wiki-ui.exe "prompt" | Out-Host` in PowerShell, script e programmi che attendono il processo figlio. In pipeline (`| Out-Host`, `| more`) PowerShell attende.
|
|
- Su Linux e macOS il comportamento della CLI resta quello di sempre (exit code propagato, streaming).
|
|
- Il criterio di accettazione dell'MVP sull'exit code vale quindi, su Windows, solo se il chiamante attende il processo.
|
|
|
|
## Da verificare
|
|
- [ ] Doppio clic su Windows nativo: nessuna finestra di console.
|
|
- [ ] Da `cmd`, PowerShell e Windows Terminal: output visibile, reindirizzamento su file e pipe, exit code con `start /wait` e con `Start-Process -Wait`.
|
|
- [ ] Output corretto quando il processo è avviato da un altro programma senza terminale.
|
|
- [ ] Il sottosistema dell'eseguibile pubblicato risulta "Windows GUI" (controllato sull'intestazione PE).
|
|
|
|
## Riferimenti
|
|
- Passi: [ROADMAP.md](../ROADMAP.md), Fase 5.
|
|
- Righe di test: [TESTING.md](../TESTING.md), righe WIN.
|