## Italiano ### 1. Introduzione Benvenuto al Project Utility Dashboard! Questa applicazione è progettata per fornire un'interfaccia centralizzata e intuitiva per la gestione e l'esecuzione di una varietà di strumenti a riga di comando, script e applicazioni esterne, sia che siano memorizzati localmente sia che siano gestiti tramite repository Git. **Obiettivi Chiave:** * **Semplificare l'Esecuzione**: Avviare strumenti complessi con parametri multipli attraverso una GUI intuitiva. * **Organizzare gli Strumenti**: Mantenere tutte le utility usate di frequente in un unico posto facilmente accessibile. * **Gestire Strumenti Basati su Git**: Clonare, aggiornare ed eseguire facilmente strumenti direttamente da Git. * **Migliorare il Flusso di Lavoro**: Risparmiare tempo ricordando i parametri e fornendo un'esperienza di avvio coerente. ### 2. Installazione e Configurazione **(Questa sezione potrebbe richiedere personalizzazioni in base al tuo metodo di distribuzione)** * **Prerequisiti**: * Python 3.8+ * (Opzionale ma Raccomandato) Git installato e disponibile nel PATH di sistema per le funzionalità degli strumenti Git. * (Opzionale) Libreria Python `GitPython` (`pip install GitPython`) per le funzionalità complete di integrazione Git nel dashboard. Se non presente, gli elementi UI relativi a Git saranno disabilitati o mostreranno "GitPython Mancante". * **Esecuzione da Sorgente**: 1. Clona il repository `ProjectUtility`. 2. Installa le dipendenze: `pip install -r requirements.txt` (Dovrai creare questo file elencando `GitPython` se lo usi). 3. Avvia l'applicazione: `python -m projectutility` dalla radice del repository. * **Utilizzo di un Eseguibile PyInstaller**: 1. Scarica o compila `ProjectUtility.exe` (o l'eseguibile specifico per la piattaforma). 2. Posiziona l'eseguibile in una directory desiderata. 3. Al primo avvio, potrebbe creare sottodirectory `config/`, `logs/` e `managed_tools/` accanto all'eseguibile se non esistono. ### 3. Panoramica dell'Applicazione La finestra principale è suddivisa in diverse aree chiave: * **Barra dei Menu**: * **Tools (Strumenti)**: * `Update All Git Tools`: Tenta di clonare o scaricare aggiornamenti per tutti gli strumenti Git abilitati. * `Configure Selected Tool...`: Apre una finestra di dialogo per configurare lo strumento attualmente selezionato. * `Reload Tool List`: Rianalizza manualmente il registro degli strumenti e aggiorna l'elenco. * **Pannello "Available Tools" (Sinistra)**: Elenca tutti gli strumenti scoperti e abilitati. Cliccando su uno strumento lo si seleziona per la configurazione e l'esecuzione. * **Pannello "Tool Options" (In Alto a Destra, Scorrevole)**: * Mostra `Display Name` e `Description` dello strumento selezionato. * Mostra informazioni sullo stato Git se è uno strumento gestito tramite Git. * Genera dinamicamente widget di input per i `Parameters` definiti per lo strumento. * **Pannello "Output Log" (Al Centro a Destra)**: Mostra `stdout` e `stderr` degli strumenti in esecuzione, così come messaggi di stato dal dashboard stesso. * **Area Pulsante "Run" (In Basso a Destra)**: Contiene il pulsante "Run Tool". * **Pannello "Running Tools" (In Basso)**: Una vista ad albero che elenca tutti gli strumenti attualmente in esecuzione da parte del dashboard, mostrando il loro Run ID, Nome, Stato e PID. Permette la terminazione dei processi selezionati. ### 4. Configurazione degli Strumenti (`tools_registry.json`) La flessibilità del dashboard risiede nel file `projectutility/config/tools_registry.json` (o `[AppExecutableDir]/config/tools_registry.json` per le app "frozen"). Questo file JSON contiene un array di oggetti di definizione degli strumenti. **Anatomia di una Voce di Strumento:** ```json { "id": "id_univoco_strumento", // Obbligatorio, stringa univoca "display_name": "Il Mio Fantastico Strumento", // Obbligatorio, stringa mostrata nella GUI "description": "Questo strumento fa cose fantastiche.", // Opzionale, stringa "type": "local", // Obbligatorio: "local" o "git" "enabled": true, // Opzionale, booleano (default: true) "run_command": ["python", "scripts/mio_script.py"], // Obbligatorio, lista di stringhe "has_gui": false, // Obbligatorio, booleano (lo strumento ha una sua GUI?) "version": "1.0.1", // Opzionale, stringa // --- Per type: "local" --- "parameters": [ // Opzionale, lista di oggetti parametro { "name": "file_input", "label": "File di Input:", "type": "file", // es. string, integer, float, boolean, file, folder "required": true, "default": "default.txt", // Valore di default opzionale "description": "Percorso al file di dati di input.", // Tooltip opzionale "options": {"filter": [["File di Testo", "*.txt"], ["Tutti i File", "*.*"]]} // Opzionale, specifico per tipo } ], // --- Per type: "git" --- "git_url": "https://gitea.example.com/utente/mio_strumento_git.git", // Richiesto per "git" "git_ref": "main", // Opzionale, default "main" (branch, tag, o commit) "local_dir_name": "mio_clone_strumento_git", // Opzionale, nome directory in managed_tools/ "parameters_definition_file": "tool_params.json" // Opzionale, percorso a file JSON nella root del repo } ``` **Spiegazione dei Campi Chiave:** * `id`: Deve essere univoco per tutti gli strumenti. * `type`: * `local`: Per eseguibili nel PATH o script nella directory `tools/` dell'applicazione. * Directory `tools/` (per script): * Se eseguito da sorgente: `[RepoRoot]/tools/` * Se eseguito come eseguibile: `[AppExecutableDir]/_internal/tools/` (impacchettato da PyInstaller) * `git`: Per strumenti clonati e gestiti da un repository Git. Saranno clonati in `managed_tools/`. * `run_command`: * Il primo elemento è solitamente l'eseguibile (es. `python`, `powershell.exe`, `mia_app.exe`). * Gli elementi successivi sono argomenti. * Per script locali in `tools/`, usare percorsi relativi a `tools/`, es. `["python", "mia_sottodir_strumento/main.py"]`. Il dashboard risolve questo in un percorso assoluto. * `parameters`: Un array di oggetti, ognuno dei quali definisce un parametro di input per la GUI. * `name`: Chiave interna per il parametro. * `label`: Testo mostrato accanto al campo di input. * `type`: Determina il widget: `string`, `integer`, `float`, `boolean`, `file` (seleziona file), `folder` (seleziona directory). * `required`: `true` o `false`. * `default`: Un valore di default. * `description`: Testo del tooltip. * `options`: Configurazioni specifiche per tipo. Per `file`: `{"filter": [["Descrizione", "*.ext"]], "save_as": false}`. * `parameters_definition_file` (per strumenti `git`): Se specificato, è un percorso *relativo alla radice del repository Git clonato* a un file JSON. Questo file JSON deve avere un oggetto radice con una chiave `"parameters"` che è un array di oggetti parametro (stesso formato dei `parameters` inline). * `local_dir_name` (per strumenti `git`): Se omesso, viene usato l'`id` come nome della directory all'interno di `managed_tools/`. **Esempio: Script Python Locale** ```json { "id": "mio_script_locale", "display_name": "Mio Elaboratore Dati", "description": "Elabora dati CSV usando uno script Python locale.", "type": "local", "run_command": ["python", "elaborazione_dati/processor.py"], "has_gui": false, "parameters": [ {"name": "csv_input", "label": "CSV di Input:", "type": "file", "required": true, "options": {"filter": [["File CSV", "*.csv"]]}}, {"name": "cartella_output", "label": "Dir Output:", "type": "folder", "required": true}, {"name": "soglia", "label": "Soglia:", "type": "float", "required": false, "default": 0.5} ] } ``` *(Questo presume che `elaborazione_dati/processor.py` esista nella tua directory `tools/`).* **Esempio: Strumento Gestito da Git** ```json { "id": "fantastica_cli_git", "display_name": "Fantastica CLI (da Git)", "description": "Un'utility a riga di comando recuperata da Git.", "type": "git", "git_url": "https://gitea.example.com/utente/fantastica-cli.git", "git_ref": "v1.2.0", // Traccia un tag specifico "run_command": ["python", "fantastica_cli/main.py"], // Comando relativo alla root del repo clonato "has_gui": false, "parameters_definition_file": "params_config.json" // File nella root del repo fantastica-cli } ``` ### 5. Utilizzo del Dashboard 1. **Avvia l'Applicazione**. 2. **Seleziona uno Strumento**: Clicca sul nome di uno strumento nell'elenco "Available Tools" a sinistra. 3. **Rivedi e Inserisci i Parametri**: * La descrizione dello strumento ed eventuali informazioni sullo stato Git appariranno nell'area "Tool Options". * Verranno mostrati i campi di input per i parametri dello strumento. Compilali come richiesto. * I parametri obbligatori sono tipicamente indicati dalla GUI (es. un asterisco o uno stile distinto, anche se l'implementazione attuale si basa su `label*`). * Per tipi `file` o `folder`, usa il pulsante "Browse...". * Gli ultimi parametri utilizzati sono spesso precompilati. 4. **Avvia lo Strumento**: Clicca il pulsante "Run Tool". 5. **Monitora l'Output**: Osserva `stdout` e `stderr` nell'"Output Log". I messaggi possono essere colorati o formattati specialmente se lo strumento emette JSON strutturato. 6. **Gestisci gli Strumenti in Esecuzione**: * Il pannello "Running Tools" in basso mostra i processi attivi. * Per terminare uno strumento, selezionalo in questo pannello e clicca "Terminate Selected". ### 6. Gestione degli Strumenti Git * **Clonazione Iniziale**: Se uno strumento Git non è ancora stato clonato, selezionandolo nell'elenco potrebbe mostrare "Not Cloned". Tentare di "Aggiornare Tutti gli Strumenti Git" o aggiornarlo tramite la sua finestra "Configura Strumento Selezionato..." attiverà il processo di clonazione nella directory `managed_tools/`. * **Controllo dello Stato**: * Quando si seleziona uno strumento Git, il suo stato Git attuale (relativo al `git_ref` configurato su `origin`) viene recuperato e visualizzato. * Questo può essere aggiornato manualmente dalla finestra di configurazione dello strumento. * **Aggiornamento degli Strumenti**: * **Singolo Strumento**: Apri la finestra di dialogo "Configura Strumento Selezionato...", opzionalmente cambia il campo `Git Ref`, e clicca "Update This Tool". * **Tutti gli Strumenti**: Usa la voce di menu "Tools" > "Update All Git Tools". Questo itererà su tutti gli strumenti Git abilitati, recupererà le ultime modifiche da `origin` e tenterà di portarli al loro `git_ref` configurato. * **Output durante l'Aggiornamento**: I messaggi di avanzamento (clonazione, fetch, checkout) appariranno nell'"Output Log". ### 7. Finestra di Configurazione Strumento Accessibile tramite "Tools" > "Configure Selected Tool..." (quando uno strumento è selezionato). * **Campi Modificabili**: * `Display Name`: Cambia come lo strumento appare nell'elenco. * `Description`: Modifica il testo descrittivo dello strumento. * `Enabled`: Attiva/disattiva se lo strumento è attivo e scopribile. * `Git Ref` (solo per strumenti Git): Cambia il branch, tag o hash di commit che lo strumento deve tracciare. **Nota**: Il processo di aggiornamento tenterà di fare il checkout di questo nuovo riferimento. * **Info di Sola Lettura**: Mostra altri dettagli configurati come `Tool ID`, `Run Command`, `Git URL`. * **Stato Git (per strumenti Git)**: * Mostra lo stato dettagliato (riferimento locale corrente, hash, ecc.). * Pulsante `Refresh Status`: Ri-effettua il fetch dal remoto e aggiorna la visualizzazione dello stato. * Pulsante `Update This Tool`: Avvia un aggiornamento per questo strumento al suo `Git Ref` attualmente configurato (o appena inserito). * **Salvataggio**: Clicca "Save Changes" per rendere persistenti le modifiche a `tools_registry.json`. L'elenco principale degli strumenti si aggiornerà. ### 8. Risoluzione dei Problemi * **`ModuleNotFoundError: No module named 'projectutility'` (App "Frozen")**: * Assicurati che tutti i file `__init__.py` necessari siano presenti nelle directory del pacchetto sorgente (`projectutility/`, `projectutility/core/`, `projectutility/gui/`). * Controlla il tuo file `.spec` di PyInstaller: * `pathex` dovrebbe puntare alla directory radice del tuo progetto. * `hiddenimports` dovrebbe elencare `projectutility` e i suoi sottomoduli se non rilevati automaticamente. * `datas` deve includere correttamente i file non Python come gli script degli strumenti locali (directory `tools`) ed eventuale `tools_registry.json` di default che vuoi impacchettare. * **Strumento Non Trovato / "Non Disponibile"**: * **Strumenti Locali**: * Verifica `run_command` in `tools_registry.json`. * Se è un eseguibile (es. `notepad.exe`), assicurati che sia nel PATH di sistema. * Se è uno script, assicurati che il percorso dello script in `run_command` (es. `mia_dir_script/script.py`) sia corretto *relativamente alla directory `tools/`* e che la directory `tools/` (con lo script) sia correttamente impacchettata se si esegue l'app "frozen". * **Strumenti Git**: * Assicurati che `git_url` sia corretto e accessibile. * Controlla se lo strumento è stato clonato in `managed_tools/`. In caso contrario, prova ad aggiornarlo. * Verifica che il percorso `run_command` sia corretto *relativamente alla radice del repository Git clonato*. * Se viene utilizzato un `parameters_definition_file`, assicurati che il suo percorso sia corretto relativamente alla radice del repo clonato. * **Operazioni Git Fallite**: * Assicurati che Git sia installato e nel PATH. * Assicurati che `GitPython` sia installato nell'ambiente Python che il dashboard sta usando. * Controlla la connettività di rete al remote Git. * Esamina i messaggi nell'"Output Log" per errori Git specifici. * **Permesso Negato**: L'applicazione (o l'utente che la esegue) potrebbe non avere il permesso di eseguire uno script o accedere a una directory.