> For the complete documentation index, see [llms.txt](https://cristiandis.gitbook.io/ntix/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cristiandis.gitbook.io/ntix/ntix-documentation/docs-it/how-it-works.md).

# Come funziona

## Come funziona

### Pipeline

```mermaid
flowchart LR
    subgraph Input
        A[config.lua] --> B[ConfigLoader]
    end
    subgraph Diff
        B --> C[DiffEngine]
        C --> D[DiffResult]
    end
    subgraph Apply
        D --> E[ExecutionEngine]
        E --> F[winget]
        E --> G[chocolatey]
        E --> H[scoop]
    end
    subgraph State
        E --> I[StateService]
        I --> J[state.json]
    end
```

### ConfigLoader

Legge uno script Lua e lo valuta usando [mlua](https://github.com/mlua-rs/mlua) con un runtime Lua 5.4 incorporato. Il file di configurazione deve restituire una tabella con `opzioni` e `pkgs` chiavi.

Il loader supporta:

* `import()` - includere altri file Lua, con unione e deduplicazione automatiche
* Risoluzione dei percorsi relativi - le importazioni vengono risolte in relazione al file che le importa
* Unione profonda - le tabelle delle opzioni vengono unite ricorsivamente; gli array dei pacchetti vengono deduplicati per ID (vince l'ultimo)

### DiffEngine

Confronta lo stato desiderato (configurazione) con lo stato attuale (pacchetti installati + file di stato NTIX) per produrre un `DiffResult` con questi elenchi:

| Elenco              | Significato                                                                             |
| ------------------- | --------------------------------------------------------------------------------------- |
| `to_install`        | Pacchetti nella configurazione ma non ancora installati (o versione non corrispondente) |
| `to_upgrade`        | Pacchetti non bloccati con una versione più recente disponibile (solo con `--upgrade`)  |
| `to_adopt`          | Pacchetti installati non ancora tracciati da NTIX (solo con `--adopt`)                  |
| `to_untracked`      | Pacchetti installati non tracciati da NTIX (solo informativo)                           |
| `to_skip`           | Pacchetti già alla versione desiderata                                                  |
| `to_remove`         | Pacchetti tracciati da NTIX ma non più nella configurazione (orfani)                    |
| `buckets_to_add`    | Bucket Scoop configurati ma non presenti nel sistema                                    |
| `buckets_to_remove` | Bucket Scoop tracciati da NTIX ma non più configurati                                   |

Azioni del file di configurazione (`config_files_to_create`, `config_files_to_update`, `config_files_no_longer_managed`) vengono calcolate separatamente, solo quando il chiamante le abilita con `-c`/`--apply-configs`.

Inoltre, `warnings` raccoglie note non fatali, come un gestore abilitato ma non installato, oppure un pacchetto che non è stato possibile verificare.

Prima di elencare i pacchetti, NTIX verifica che esistano nei rispettivi gestori. Un pacchetto **confermato come inesistente** viene rimosso da `to_install` e aggiunto a `warnings`; un pacchetto che **non può essere verificato** (ad esempio una query di ricerca fallita) viene mantenuto in `to_install` ma contrassegnato con un avviso.

### Gestione dello stato

NTIX tiene traccia di ciò che gestisce in un file di stato JSON in `%LOCALAPPDATA%/ntix/state.json`.

```json
{
  "version": 2,
  "winget": { "Google.Chrome": "latest", "7zip.7zip": "23.01" },
  "chocolatey": { "ripgrep": "latest" },
  "scoop": { "fd": "latest", "bat": "latest" },
  "scoopBuckets": { "main": null },
  "configFiles": { "C:/Users/you/.gitconfig": "9f86d081884c7d65..." }
}
```

* **Scritture atomiche** - lo stato viene scritto in un file temporaneo e poi spostato al posto giusto, prevenendo la corruzione
* **Rilevamento degli orfani** - i pacchetti nel file di stato ma non nella configurazione vengono contrassegnati per la rimozione
* **Logica di ritentativo** - le scritture su file vengono ritentate (con backoff lineare) fino a 3 volte in caso di errore
* **Bucket Scoop** - i bucket aggiunti da NTIX vengono registrati sotto `scoopBuckets`
* **File di configurazione** - i file gestiti vengono registrati sotto `configFiles`, indicizzati per percorso di destinazione e valorizzati con l'hash del contenuto

### File di lock

Solo uno `ntix apply` può essere eseguito alla volta. Un file di lock in `%LOCALAPPDATA%/ntix/apply.lock` impedisce l'esecuzione concorrente. Su Windows viene aperto senza condivisione, quindi un secondo processo non riesce ad acquisirlo. Il file di lock memorizza `PID@UnixTimestamp`; se un lock è obsoleto, il messaggio di errore indica il file così può essere eliminato manualmente.

### Rilevamento dei gestori di pacchetti

NTIX usa `PackageManagerDetector` per verificare quali gestori sono disponibili:

* winget - controllato e installato automaticamente tramite App Installer se mancante e abilitato
* Chocolatey - verificato eseguendo `choco --version`
* Scoop - verificato eseguendo `scoop --version`