# Guida Installazione Tooling SVG Fase 3 (Step-by-step)

Versione: 2026-04-22  
Ambito: installazione locale tooling CLI per `from-raster` ed export PNG/PDF  
Vincoli: no Python; Linux baseline Ubuntu

---

## 1) Obiettivo e tool coperti

Questa guida installa i tool usati in Fase 3:

- `inkscape` (fallback universale conversion/export)
- `vtracer` (raster -> SVG colore)
- `potrace` (raster -> SVG B/N)
- `rsvg-convert` (SVG -> PNG/PDF su Linux/Ubuntu)

Allineamento MVP Fase 3:

- skill/workflow target: `from-raster`, `export/to-png-batch`, `export/to-pdf`;
- checker runtime capability: `scripts/check-svg-tooling.js`;
- smoke Fase 3:
  - simulato policy: `scripts/smoke-svg-phase3.js`
  - runtime reale toolchain: `scripts/smoke-svg-phase3-runtime.js`
- policy Windows export: **Inkscape-only** (`rsvg-convert` non supportato su Windows).

Matrice decisionale host (default):

- Windows:
  - `from-raster`: `vtracer -> potrace -> inkscape`
  - `export PNG/PDF`: `inkscape`
- Ubuntu:
  - `from-raster`: `vtracer -> potrace -> inkscape`
  - `export PNG/PDF`: `rsvg-convert -> inkscape`

Regola trasversale:
- se nessun tool della chain e' disponibile, terminare con errore esplicito;
- non dichiarare successo in assenza di esecuzione reale.

---

## 2) Scelta rapida (raccomandata)

Se vuoi iniziare subito sviluppo Fase 3 su Windows:

1. installa `inkscape` (gia' gestito da setup, se disponibile via winget/choco);
2. installa `vtracer` da binario precompilato (gia' gestito da setup);
3. lascia `potrace` come opzionale iniziale.

Questa combinazione e' sufficiente per procedere con sviluppo e smoke principali.

Nota operativa:

- su Windows `rsvg-convert` non e' previsto nel perimetro MVP;
- in assenza di uno o piu' tool, il comportamento atteso e' errore/fallback esplicito (no fail silenziosi).

---

## 3) Windows - Procedura dettagliata

## 3.1 Prerequisiti

Verifica di avere:

```powershell
node -v
npm -v
```

Se usi lo script setup repository:

```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -InstallSvgTooling
```

Questo tenta installazione automatica di parte dei tool e poi mostra eventuali mancanti.
Per Windows, il setup prova a scaricare binari precompilati di `vtracer` e `potrace` in `tools/third-party` e ad aggiornare il `PATH` utente/sessione.
Inoltre stampa un riepilogo capability finale con stato per ciascun tool e messaggio esplicito se l'esecuzione e' bloccata da Group Policy (AppLocker/SRP).
Nelle versioni correnti prova anche auto-detect da path noti (es. `C:\Program Files\Inkscape\bin`, `tools\third-party\...\current`, `C:\msys64\...\bin`) e aggiorna il `PATH` utente/sessione quando trova un tool installato ma non risolvibile.
Ogni step di installazione automatica richiede conferma esplicita. Se rifiuti uno step, il setup prosegue assumendo installazione manuale e lo segnala nel riepilogo finale.

## 3.2 Installare vtracer (binario precompilato)

Percorso A (automatico consigliato):

```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -InstallSvgTooling
vtracer --version
```

Percorso B (manuale):

1. apri releases ufficiali: https://github.com/visioncortex/vtracer/releases
2. scarica asset Windows x64 precompilato
3. estrai ad esempio in `tools\third-party\vtracer\current`
4. aggiungi la cartella al `PATH` utente
5. verifica:

```powershell
vtracer --version
```

## 3.3 Installare Potrace (opzionale ma consigliato per B/N)

Percorso A (automatico consigliato, binario precompilato via setup):

```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -InstallSvgTooling
potrace --version
```

Percorso B (manuale, da sito ufficiale):

1. scarica binario Windows da https://potrace.sourceforge.net/
2. estrai, ad esempio in `C:\tools\potrace`
3. aggiungi la cartella al `PATH` utente
4. riapri terminale e verifica:

```powershell
potrace --version
```

## 3.4 Nota Windows su rsvg-convert

Nel perimetro corrente Fase 3, su Windows `rsvg-convert` non e' supportato.
Per export PNG/PDF usare `inkscape`.

---

## 4) Ubuntu - Procedura dettagliata

## 4.1 Setup automatico repository

Da root repo:

```bash
./setup.sh --install-svg-tooling
```

Il setup Ubuntu usa `apt-get` per installare:
- `potrace`
- `librsvg2-bin` (`rsvg-convert`)
- `inkscape`
- utility base (`curl`, `tar`, `gzip`, `unzip`, `ca-certificates`)

Quando `vtracer` non e' gia' disponibile nel PATH, il setup prova anche download di binario precompilato in:
- `tools/third-party/vtracer/current`

## 4.2 vtracer su Ubuntu (fallback manuale)

Se il download precompilato non riesce o la tua architettura non e' supportata:

```bash
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
cargo install vtracer --locked
```

---

## 5) Verifica finale capability

Esegui nel terminale dell'ambiente dove svilupperai:

```powershell
inkscape --version
vtracer --version
potrace --version
# Linux/Ubuntu only:
rsvg-convert --version
```

Smoke automatico Phase 3 (cross-platform via Node):

```bash
node scripts/smoke-svg-phase3-runtime.js
```

Se alcuni tool sono assenti:

- su Windows e' accettabile partire con `inkscape` (con `vtracer` raccomandato per raster colore);
- su Ubuntu e' raccomandato avere almeno `rsvg-convert` + `inkscape` per export affidabile;
- `vtracer` su Ubuntu e' raccomandato; se manca, usa fallback esplicito (`potrace`/`inkscape`) e correggi setup;
- le skill devono dichiarare fallback in modo esplicito.

## 5.1 Verifica checker/smoke MVP Fase 3

Eseguire nella root repository:

```powershell
node scripts/check-svg-tooling.js
node scripts/smoke-svg-phase3.js --profile no-tools
node scripts/smoke-svg-phase3.js --profile tools-present
node scripts/smoke-svg-phase3.js --profile windows-inkscape-first
node scripts/smoke-svg-phase3.js --profile linux-rsvg-first
```

Comportamento atteso:

- `check-svg-tooling` produce stato capability con campi `tools`, `selected`, `fallbacks`, `warnings`;
- profilo `no-tools`: errore esplicito atteso, nessun fallimento silenzioso;
- profilo `tools-present`: selezione tool coerente con disponibilita';
- profilo `windows-inkscape-first`: export PNG/PDF selezionato su `inkscape` (catena Windows inkscape-only).
- profilo `linux-rsvg-first`: export PNG/PDF selezionato su `rsvg-convert` con fallback `inkscape`.

---

## 6) Troubleshooting rapido

1. Comando non trovato dopo installazione:
- chiudi/riapri terminale;
- verifica `PATH`:

```powershell
$env:PATH
Get-Command vtracer, potrace, inkscape
```

2. `vtracer` non trovato dopo setup:
- controlla presenza file in `tools\third-party\vtracer\current\vtracer.exe`;
- verifica che la cartella sia nel `PATH` utente/sessione;
- riapri il terminale e riprova:

```powershell
vtracer --version
```

3. `rsvg-convert` su Windows:
- non previsto nel perimetro MVP; ignora questo controllo su host Windows.

4. Smoke Fase 3 fallisce per policy host:
- verifica che il profilo usato sia coerente con OS/tool disponibili;
- riesegui `node scripts/check-svg-tooling.js` e controlla `warnings`/`fallbacks`;
- correggi PATH o installazione tool mancanti, poi ripeti smoke.

5. Workflow B/N con `potrace` da consolidare:
- usa pipeline standard con script dedicato:

```bash
node skills/svg/tools/trace-bw-potrace.js --input <input.bmp> --output <out.svg>
```

- input supportati: `.bmp`, `.pbm`, `.pgm`, `.ppm`, `.pnm`;
- se l'input e' PNG/JPG, converti prima a BMP/PNM o usa fallback `vtracer`.

---

## 8) Nota riavvio server MCP

Questa guida copre tooling locale e smoke script.  
Se in futuro cambia il codice runtime capability lato server MCP, aggiungere una nota esplicita di riavvio server nella documentazione di rilascio e rieseguire i check nell'ambiente riavviato.

---

## 7) Fonti ufficiali

- VTracer releases: https://github.com/visioncortex/vtracer/releases
- Potrace official: https://potrace.sourceforge.net/