WinRepair

Tool CLI C# per la diagnosi e riparazione di crash, instabilità e driver issues su Windows.
Interfaccia console retro ASCII. Ogni azione correttiva viene proposta con spiegazione e richiede conferma esplicita prima dell'esecuzione.

---

Stato progetto

Fase	Stato
Design / spec	✅ Completato
Piano di implementazione	✅ Completato
Implementazione	✅ Completata (v1.0.0)
Build self-contained	✅ WinRepair/publish/WinRepair.exe (~66 MB)
Test	✅ 20/20 verdi

---

Documentazione progettuale

Documento	Path	Contenuto
Design Spec	docs/superpowers/specs/2026-06-26-winrepair-design.md	Obiettivo, architettura, UI, dettaglio 5 moduli, vincoli tecnici
Piano implementazione	docs/superpowers/plans/2026-06-26-winrepair-implementation.md	12 task con codice C# completo, test, comandi esatti

---

Come avviare lo sviluppo in una nuova sessione

1. Leggi il design spec per il contesto
2. Leggi il piano di implementazione — contiene tutto il codice, task per task
3. Esegui i task in ordine da Task 1 (scaffolding) a Task 12 (build finale)
4. Usa lo skill superpowers:subagent-driven-development oppure superpowers:executing-plans

Il piano è autosufficiente: ogni task include codice C# completo, nessun placeholder.

---

Architettura in breve

WinRepair/                          (.NET 8, Windows-only, single-file exe)
├── Program.cs                    entry point, menu loop
├── UI/                           ConsoleRenderer, Theme (retro ASCII + ANSI)
├── Core/                         IDiagnosticModule, DiagnosticResult, RepairAction, Orchestrator
├── Infrastructure/               WindowsCommandRunner, ElevationHelper, ReportWriter
└── Modules/
    ├── CrashAnalyzer/            minidump parsing, BugcheckDatabase, Driver Verifier
    ├── DriverScanner/            WMI Win32_PnPSignedDriver, IRQ, unsigned, outdated
    ├── SystemIntegrity/          SFC, DISM, WMI repo, Windows Update, BCD
    ├── DiskAnalyzer/             SMART avanzato, chkdsk, VSS
    └── EventLogAnalyzer/         Kernel-Power Event 41, crash loops, thermal

WinRepair.Tests/                    xUnit + FluentAssertions

Stack: .NET 8, Spectre.Console (unica dipendenza NuGet), System.Management per WMI
Build finale: dotnet publish --self-contained --single-file -r win-x64 → singolo .exe ~15-20MB

---

Funzionalità principali

5 moduli diagnostici

Modulo	Area	Comandi/API usate
CrashAnalyzer	BSOD, minidump, Driver Verifier	DbgHelp.dll (P/Invoke), Event 1001 BugCheck, verifier
DriverScanner	Driver unsigned, recenti, IRQ, outdated	WMI Win32_PnPSignedDriver, Win32_IRQResource, pnputil
SystemIntegrity	SFC, DISM, WMI, Windows Update, BCD	sfc, DISM, winmgmt, bootrec, bcdedit
DiskAnalyzer	SMART avanzato, filesystem, VSS	WMI MSStorageDriver_FailurePredictData, chkdsk, vssadmin
EventLogAnalyzer	Shutdown improvvisi, crash loop, thermal	EventLogReader, Kernel-Power Event 41, Event 7031/7034

Bugcheck database (CrashAnalyzer)

Mappatura codice → causa → azioni specifiche:

Codice	Nome	Fix principale
0x0000009F	Driver Power State Failure	Driver Verifier ACPI/USB, disabilita hybrid sleep
0x00000133	DPC Watchdog Violation	Driver Verifier storage/network, aggiorna driver NVMe
0x00000101	Clock Watchdog Timeout	Microcode update, test RAM
0x00000050	Page Fault in Non-paged Area	Test RAM (mdsched), SFC
0x0000007E	System Thread Exception	Driver Verifier /all, SFC
0x00000124	WHEA Uncorrectable Error	WHEA Event Log, test RAM (hardware fault)

Focus: arresti improvvisi senza avviso

Il modulo EventLogAnalyzer ricostruisce la timeline degli Event 41 (Kernel-Power) con gli eventi precedenti ogni shutdown, e il modulo CrashAnalyzer correla i minidump con i timestamp degli arresti.

Livelli di rischio azioni

Livello	Esempi
SAFE	sfc /verifyonly, powercfg /h off, mdsched, letture WMI
MODERATE	sfc /scannow, DISM /RestoreHealth, verifier /standard, reset WU Agent
HIGH	chkdsk /f /r, bootrec /rebuildbcd, verifier /all

---

Requisiti runtime

• Windows 10/11 (x64)
• Privilegi Administrator (richiesti all'avvio con auto-relaunch runas)
• .NET 8 non necessario → binario self-contained

---

Build ed esecuzione

Per compilare/eseguire dai sorgenti serve il .NET 8 SDK (net8.0-windows, solo Windows x64). L'utente finale non ne ha bisogno: il binario pubblicato è self-contained.

Dalla root della solution (C:\devpersonal\WinDiag):

# Ripristino dipendenze NuGet
dotnet restore

# Esecuzione diretta dai sorgenti (modalità interattiva)
dotnet run --project WinRepair

# Esecuzione passando i flag CLI (notare il -- che separa gli argomenti)
dotnet run --project WinRepair -- --scan-only
dotnet run --project WinRepair -- --scan-only --report

# Solo build (Debug)
dotnet build

# Test (xUnit + FluentAssertions)
dotnet test

# Build finale: singolo .exe self-contained (~66 MB) in WinRepair/publish/
dotnet publish WinRepair -c Release -r win-x64 --self-contained -o WinRepair/publish

Privilegi: la modalità interattiva propone l'auto-elevazione (runas). Per evitare il prompt UAC apri un terminale come amministratore prima di dotnet run. Console reale: il menu usa Console.ReadKey, quindi dotnet run va lanciato in un terminale interattivo. Per stdin/stdout rediretti (script/CI) usa --scan-only.

---

Flag CLI

Flag	Comportamento
(nessuno)	Modalità interattiva con menu
--scan-only	Solo analisi, nessuna azione proposta
--report	Salva automaticamente il report alla chiusura nella cartella di output configurata

---

Configurazione (appsettings.json)

File opzionale letto accanto all'eseguibile (con System.Text.Json, nessuna dipendenza NuGet aggiuntiva). Se assente o con valore vuoto, valgono i default.

Chiave	Default	Descrizione
OutputDirectory	%LOCALAPPDATA%\WinRepair	Cartella dove vengono salvati export driver e report di sessione. Supporta percorsi assoluti e variabili d'ambiente (es. %USERPROFILE%\Documents\WinRepair). Se il percorso non è scrivibile, si torna al default.

// appsettings.json
{ "OutputDirectory": "" }   // "" = %LOCALAPPDATA%\WinRepair

Override locale (sviluppo): crea appsettings.local.json accanto all'exe — ha la precedenza su appsettings.json ed è gitignorato (insieme a output/), così puoi far finire l'output in una cartella del progetto senza committare nulla:

// appsettings.local.json  (non committato)
{ "OutputDirectory": "C:\\devpersonal\\WinDiag\\output" }

Il file di log resta sempre in %LOCALAPPDATA%\WinRepair\winrepair.log, indipendentemente da OutputDirectory.

---

Decisioni di design prese durante il brainstorming

• Architettura: monolite modulare (vs multi-progetto o script-first) — un singolo .exe portabile
• Autonomia azioni: sempre con conferma esplicita, nessuna modalità automatica
• Driver Verifier: abilitato su subset mirato di driver sospetti, mai globale (/all) salvo caso 0x7E
• SMART: interpretazione attributi raw (non solo pass/fail) — reallocated sectors, pending, uncorrectable
• Event 41: ricostruzione timeline con 30 eventi precedenti ogni shutdown
• Report: .txt nella cartella di output configurata (default %LOCALAPPDATA%\WinRepair), opzionale a runtime — no JSON/HTML in v1.0
• Export driver: dal menu Driver Scanner si esporta l'inventario (tutti / solo obsoleti) in TXT o CSV; percorso configurabile via appsettings.json
• UX: stile retro (ASCII borders, palette verde/ambra su nero), Spectre.Console come unica lib UI

---

Modalità d'uso

Comando	Comportamento
WinRepair.exe	Menu interattivo (richiede console reale; propone auto-elevazione)
WinRepair.exe --scan-only	Batch non interattivo: esegue tutti i moduli, stampa i risultati, esce. Scriptabile (stdout redirigibile)
WinRepair.exe --scan-only --report	Come sopra + salva il report .txt nella cartella di output

Export inventario driver

Dal menu interattivo, dopo [2] Driver Scanner & Update, viene proposto l'export dell'inventario driver:

• [1] Tutti i driver, oppure [2] solo gli obsoleti (terzi, > 3 anni — stessa logica della diagnosi)
• formato TXT (leggibile) o CSV (per fogli di calcolo, con quoting RFC-4180)

Il file viene salvato nella cartella di output (vedi Configurazione) come WinRepair-Drivers-{All|Obsolete}-<timestamp>.{txt|csv}.

Avvio rapido come amministratore

Per lanciare l'interfaccia interattiva senza aprire manualmente un terminale elevato, usa il launcher incluso:

WinRepair-Admin.bat   (doppio click)

Il file WinRepair-Admin.bat si auto-eleva via UAC, poi avvia WinRepair\publish\WinRepair.exe se presente, altrimenti fa fallback su dotnet run dai sorgenti. Eventuali flag passati al .bat (es. --scan-only) vengono inoltrati all'app.

Log: ogni sessione scrive un log in %LOCALAPPDATA%\WinRepair\winrepair.log (avvio moduli, esecuzione azioni, errori) — utile per diagnosticare problemi.

Migliorie applicate in fase di implementazione

Rispetto al piano originale sono stati corretti questi difetti emersi durante build/test/esecuzione:

• Markup Spectre.Console: parentesi quadre letterali ([1], [R], tagline) nei menu/azioni venivano interpretate come tag di stile → crash a runtime. Ora escapate ([[1]]); test di regressione in ConsoleRendererTests.
• IRQ conflicts: Win32_IRQResource.IRQNumber è WMI uint; il is not int non matchava mai → feature morta. Corretto con conversione difensiva.
• Date driver: Win32_PnPSignedDriver.DriverDate è in formato CIM_DATETIME, non parsabile con DateTime.TryParse → controlli "recenti/datati" sempre vuoti. Ora via ManagementDateTimeConverter + display leggibile.
• WMI repository: il check flaggava come "inconsistent" sia l'accesso negato (no admin) sia output non inglese ("coerente") → falso positivo. Ora usa l'exit code (0 = coerente, locale-independent).
• Dipendenza mancante: aggiunto package System.Diagnostics.EventLog (i tipi EventLogReader/EventLogQuery sono forwarded lì).
• Modalità batch: --scan-only ora gira senza menu/keypress, fulfilling l'uso "sysadmin/script" della spec.
• Codice morto rimosso: chiamata Get-WindowsUpdateLog inutilizzata; azione VSS regsvr32 con quoting PowerShell rotto.

Round 2 (dopo test su crash reali)

• CrashAnalyzer non vedeva i crash: il parser cercava la signature MDMP (user-mode), ma i dump del kernel sono PAGEDU64/PAGEDUMP (BugCheckCode a 0x38/0x28). Inoltre filtrava sul provider BugCheck mentre quello reale è Microsoft-Windows-WER-SystemErrorReporting. Ora l'analisi primaria parsa il messaggio dell'Event 1001 (codice esatto, leggibile senza admin, locale-independent), raggruppa per codice e segnala i crash ricorrenti; parser binario dei dump come fallback. Verificato: 17 crash 0x7E ricorrenti correttamente classificati.
• Crash sull'esecuzione azioni "safe": .msc/ms-settings: non sono eseguibili con UseShellExecute=false → Win32Exception non gestita = app in crash. Aggiunto percorso Launch (ShellExecute) per target shell/GUI, e try/catch attorno a ogni esecuzione: un'azione non fa più crashare il tool.
• Input incoerente: il menu usava ReadKey (senza Invio) lasciando un \n nel buffer che la ReadLine successiva consumava, saltando la selezione dell'azione. Tutto l'input ora è ReadLine.
• Permessi minidump: senza admin la cartella Minidump dà accesso negato → ora segnalato esplicitamente ("relaunch as administrator") invece di "nessun problema".
• Logging: aggiunto file di log in %LOCALAPPDATA%\WinRepair\winrepair.log.

Limitazioni note

• Localizzazione SFC/DISM: il rilevamento di corruzione SFC/DISM si basa su stringhe inglesi dell'output. Su Windows con UI non inglese può dare falsi negativi (corruzione non rilevata). Mitigato per WMI via exit code; SFC/DISM restano string-based come da design del piano.
• Modalità interattiva: il menu richiede una console reale (Console.ReadKey); non utilizzabile con stdin/stdout rediretti. Per automazione usare --scan-only.
• Dimensione exe: ~66 MB (self-contained single-file senza trimming; il trimming romperebbe la reflection di WMI/System.Management).
• Verifica headless: menu interattivo e auto-relaunch admin non sono verificabili in CI; testati a mano i percorsi --scan-only/--report.

Out of scope v1.0

• Supporto remoto / macchine remote
• GUI grafica (WPF/WinForms)
• Integrazione SCCM / Intune
• Analisi performance (non crash-related)
• Report HTML o JSON