tool-clean — Base v2

tool-clean è un tool CLI osservativo e dichiarativo per la gestione dei monitor.

Non applica configurazioni, non automatizza decisioni e non modifica il sistema.
Serve a rendere esplicite, persistenti e auditabili le intenzioni d’uso.

Technology stack

• Python 3.10+
• CLI-first tool (not a library)
• Local execution, no network dependencies
• SQLite for local persistence
• Cross-platform (OS-specific observation logic isolated)

Principi fondamentali

• Controllo umano totale
  Nessuna decisione autonoma, nessuna applicazione automatica.

• Osservazione prima dell’azione
  Il sistema osserva lo stato reale (monitor collegati) e lo rende persistente.

• Dichiarazione esplicita
  L’utente dichiara come intende usare un monitor tramite profili.

• Audit minimale e osservativo
  Ogni azione mutativa è tracciata (INFO / WARN / SECURITY), append-only.

Cosa fa tool-clean (Base v2)

tool-clean permette di:

• osservare i monitor collegati a una macchina
• identificarli in modo stabile
• assegnare etichette umane ai monitor
• creare profili dichiarativi
• associare un profilo a un monitor
• consultare lo stato corrente via CLI

tool-clean non applica configurazioni hardware o di sistema operativo.

Installazione (sviluppo)

Installazione in modalità editable:

pip install -e .

Verifica

tool-clean --help

Comandi Monitor

• scansione monitor

tool-clean monitor scan

• elenco monitor

tool-clean monitor list

• etichetta monitor

tool-clean monitor label <monitor_id> "<label>"

Comandi - Profile

• elenco profili

tool-clean profile list

• creazione profilo

tool-clean profile create "<name>" \
  --description "<descrizione opzionale>" \
  --settings '<json>'

• esempio

tool-clean profile create "Lavoro HP" \
  --description "Profilo lavoro per monitor esterno HP" \
  --settings '{"brightness":"70%","scale":"100%"}'

Assegnazione Profilo a Monitor

tool-clean profile assign <profile_id> <monitor_id>

Cosa tool-clean non fa

• non cambia luminosità
• non cambia risoluzione
• non interagisce con driver o sistema operativo
• non applica configurazioni
• non prende decisioni automatiche

tool-clean descrive e rende visibile l'intenzione, non la esegue.

Modello operativo

1. Il sistema osserva lo stato reale (monitor)
2. L’utente dichiara un profilo
3. L’utente associa il profilo a un monitor
4. L’informazione è persistente e auditabile
5. L’applicazione reale avviene fuori da tool-clean

Questo rende possibile governance IT, revisione e revoca consapevole.

Ambito della Base v2

La Base v2 è locale, autonoma e non federata.

Sono fuori scope:

• sincronizzazione tra nodi
• approvazione centralizzata
• revoca remota
• applicazione automatica delle configurazioni

Questi aspetti appartengono a versioni successive.

Stato del progetto

tool-clean Base v2 è una fondazione stabile:

• osservativa
• prevedibile
• senza comportamenti impliciti

Ogni estensione futura dovrà rispettare questi vincoli.