# Project Utility Dashboard

---

## English

### Overview

The **Project Utility Dashboard** is a Python-based desktop application designed to streamline the management and execution of various developer tools, scripts, and external programs. It offers a centralized Graphical User Interface (GUI) to discover, configure, and launch:

*   **Local Tools**: Scripts (Python, batch, shell, etc.) or executables stored on your machine.
*   **Git-Managed Tools**: Utilities and small projects fetched and kept up-to-date directly from Git repositories.

This dashboard is ideal for engineers and developers who frequently use a diverse set of command-line utilities or scripts and desire a more organized, user-friendly, and efficient workflow.

### Core Functionality

1.  **Tool Registry (`tools_registry.json`)**:
    *   The heart of the dashboard, this JSON file (located in `projectutility/config/`) defines all manageable tools.
    *   Each tool entry includes:
        *   `id`: A unique identifier.
        *   `display_name`: User-friendly name for the GUI.
        *   `description`: A brief explanation of the tool's purpose.
        *   `type`: Specifies if the tool is `local` or `git`.
        *   `run_command`: The command and initial arguments to execute the tool.
        *   `has_gui`: Indicates if the tool itself has a graphical interface (influences how it's launched).
        *   `enabled`: Toggles tool visibility and discoverability.
        *   `parameters` (for `local` tools): Inline definitions for command-line parameters the tool accepts.
        *   `parameters_definition_file` (for `git` tools): Path to a JSON file (relative to the Git repo root) defining parameters.
        *   `git_url`, `git_ref` (for `git` tools): Repository URL and the branch/tag/commit to track.
        *   `local_dir_name` (for `git` tools): Optional custom name for the local clone directory.

2.  **Discovery & UI**:
    *   On startup, the dashboard reads the registry and identifies available tools.
    *   The main window lists all enabled tools.
    *   Selecting a tool displays its description and dynamically generates input fields for its defined parameters.
    *   Previously used parameter values are remembered and pre-filled (`tool_state.json`).

3.  **Execution**:
    *   Users provide parameter values through the GUI.
    *   Clicking "Run Tool" launches the tool's command in a separate, non-blocking process.
    *   Real-time `stdout` and `stderr` from the tool are captured and displayed in the "Output Log" area.
    *   JSON-formatted output from tools (with specific keys like `type`, `level`, `message`, `progress`) can be interpreted for enhanced display (e.g., progress bars, colored log levels).

4.  **Process Management**:
    *   A "Running Tools" panel lists all active processes launched by the dashboard, showing their Run ID, name, status, and PID.
    *   Selected processes can be terminated.

5.  **Git Integration (Optional - requires `GitPython`)**:
    *   **Status Check**: For `git` tools, the dashboard can fetch updates from the remote and display the repository's status (e.g., up-to-date, behind, diverged). This is shown when a Git tool is selected and can be refreshed in the tool's configuration window.
    *   **Update Tools**:
        *   Individual Git tools can be updated to their configured `git_ref` via their configuration window.
        *   An "Update All Git Tools" option in the "Tools" menu attempts to clone or update all enabled Git tools.
    *   **Cloning**: If a `git` tool's local directory doesn't exist, the update process will first attempt to clone it from the specified `git_url`. Cloned repositories are stored in the `managed_tools/` directory.

6.  **Tool Configuration**:
    *   A modal dialog allows users to:
        *   Modify common fields like `display_name`, `description`, and `enabled` status.
        *   For `git` tools, change the `git_ref` to track a different branch, tag, or commit.
        *   View (but not edit in this window) other details like `run_command` or `git_url`.
        *   Refresh Git status and trigger updates for the specific tool.
    *   Changes are saved back to the `tools_registry.json` file.

### How It Works - Path Management

*   **Application Root**:
    *   When run as a script (`python -m projectutility`): The root of the cloned `ProjectUtility` repository.
    *   When run as a PyInstaller executable: The directory containing the executable.
*   **Configuration Files**:
    *   `tools_registry.json`: User-editable tool definitions. Expected in `[AppRoot]/config/`.
    *   `tool_state.json`: Stores last used parameters. Automatically managed in `[AppRoot]/config/`.
*   **Tool Directories**:
    *   `tools/`: For `local` tool scripts/files.
        *   Script Mode: `[AppRoot]/tools/`.
        *   Frozen Mode (PyInstaller): Bundled into `[AppExecutableDir]/_internal/tools/` (requires `--add-data "tools:tools"` in PyInstaller spec). Paths in `run_command` for local scripts are resolved relative to this.
    *   `managed_tools/`: For `git` tool clones. Always located in `[AppRoot]/managed_tools/`.
    *   `logs/`: For application logs. Always located in `[AppRoot]/logs/`.

### Target Users

*   Developers needing to execute a variety of build scripts, utility scripts, or helper applications.
*   Engineers managing and running multiple command-line tools with different parameters.
*   Teams looking for a standardized and user-friendly way to launch shared development utilities.

---

## Italiano

### Panoramica

Il **Project Utility Dashboard** è un'applicazione desktop basata su Python progettata per ottimizzare la gestione e l'esecuzione di vari strumenti di sviluppo, script e programmi esterni. Offre un'Interfaccia Utente Grafica (GUI) centralizzata per scoprire, configurare e avviare:

*   **Strumenti Locali**: Script (Python, batch, shell, ecc.) o eseguibili memorizzati sulla tua macchina.
*   **Strumenti Gestiti tramite Git**: Utility e piccoli progetti recuperati e mantenuti aggiornati direttamente da repository Git.

Questo dashboard è ideale per ingegneri e sviluppatori che utilizzano frequentemente un insieme diversificato di utility a riga di comando o script e desiderano un flusso di lavoro più organizzato, intuitivo ed efficiente.

### Funzionalità Fondamentali

1.  **Registro degli Strumenti (`tools_registry.json`)**:
    *   Il cuore del dashboard, questo file JSON (situato in `projectutility/config/`) definisce tutti gli strumenti gestibili.
    *   Ogni voce di strumento include:
        *   `id`: Un identificatore univoco.
        *   `display_name`: Nome intuitivo per la GUI.
        *   `description`: Una breve spiegazione dello scopo dello strumento.
        *   `type`: Specifica se lo strumento è `local` o `git`.
        *   `run_command`: Il comando e gli argomenti iniziali per eseguire lo strumento.
        *   `has_gui`: Indica se lo strumento stesso ha un'interfaccia grafica (influenza come viene avviato).
        *   `enabled`: Attiva/disattiva la visibilità e la scopribilità dello strumento.
        *   `parameters` (per strumenti `local`): Definizioni inline per i parametri a riga di comando accettati dallo strumento.
        *   `parameters_definition_file` (per strumenti `git`): Percorso a un file JSON (relativo alla radice del repository Git) che definisce i parametri.
        *   `git_url`, `git_ref` (per strumenti `git`): URL del repository e il branch/tag/commit da tracciare.
        *   `local_dir_name` (per strumenti `git`): Nome personalizzato opzionale per la directory di clone locale.

2.  **Scoperta e Interfaccia Utente**:
    *   All'avvio, il dashboard legge il registro e identifica gli strumenti disponibili.
    *   La finestra principale elenca tutti gli strumenti abilitati.
    *   Selezionando uno strumento vengono visualizzate la sua descrizione e i campi di input generati dinamicamente per i suoi parametri definiti.
    *   I valori dei parametri utilizzati in precedenza vengono ricordati e precompilati (`tool_state.json`).

3.  **Esecuzione**:
    *   Gli utenti forniscono i valori dei parametri tramite la GUI.
    *   Cliccando su "Run Tool" si avvia il comando dello strumento in un processo separato e non bloccante.
    *   `stdout` e `stderr` in tempo reale dello strumento vengono catturati e visualizzati nell'area "Output Log".
    *   L'output formattato JSON dagli strumenti (con chiavi specifiche come `type`, `level`, `message`, `progress`) può essere interpretato per una visualizzazione migliorata (es. barre di avanzamento, livelli di log colorati).

4.  **Gestione dei Processi**:
    *   Un pannello "Running Tools" elenca tutti i processi attivi avviati dal dashboard, mostrando il loro Run ID, nome, stato e PID.
    *   I processi selezionati possono essere terminati.

5.  **Integrazione Git (Opzionale - richiede `GitPython`)**:
    *   **Controllo Stato**: Per gli strumenti `git`, il dashboard può recuperare aggiornamenti dal remoto e visualizzare lo stato del repository (es. aggiornato, indietro, divergente). Questo viene mostrato quando si seleziona uno strumento Git e può essere aggiornato nella finestra di configurazione dello strumento.
    *   **Aggiornamento Strumenti**:
        *   Singoli strumenti Git possono essere aggiornati al loro `git_ref` configurato tramite la loro finestra di configurazione.
        *   Un'opzione "Update All Git Tools" nel menu "Tools" tenta di clonare o aggiornare tutti gli strumenti Git abilitati.
    *   **Clonazione**: Se la directory locale di uno strumento `git` non esiste, il processo di aggiornamento tenterà prima di clonarla dall'`git_url` specificato. I repository clonati sono memorizzati nella directory `managed_tools/`.

6.  **Configurazione Strumenti**:
    *   Una finestra di dialogo modale consente agli utenti di:
        *   Modificare campi comuni come `display_name`, `description` e stato `enabled`.
        *   Per gli strumenti `git`, cambiare il `git_ref` per tracciare un branch, tag o commit diverso.
        *   Visualizzare (ma non modificare in questa finestra) altri dettagli come `run_command` o `git_url`.
        *   Aggiornare lo stato Git e attivare aggiornamenti per lo strumento specifico.
    *   Le modifiche vengono salvate nel file `tools_registry.json`.

### Come Funziona - Gestione dei Percorsi

*   **Radice dell'Applicazione (AppRoot)**:
    *   Quando eseguito come script (`python -m projectutility`): La radice del repository `ProjectUtility` clonato.
    *   Quando eseguito come eseguibile PyInstaller: La directory contenente l'eseguibile.
*   **File di Configurazione**:
    *   `tools_registry.json`: Definizioni degli strumenti modificabili dall'utente. Previsto in `[AppRoot]/config/`.
    *   `tool_state.json`: Memorizza gli ultimi parametri utilizzati. Gestito automaticamente in `[AppRoot]/config/`.
*   **Directory degli Strumenti**:
    *   `tools/`: Per script/file di strumenti `local`.
        *   Modalità Script: `[AppRoot]/tools/`.
        *   Modalità Frozen (PyInstaller): Impacchettato in `[AppExecutableDir]/_internal/tools/` (richiede `--add-data "tools:tools"` nello spec di PyInstaller). I percorsi in `run_command` per gli script locali sono risolti relativamente a questa.
    *   `managed_tools/`: Per i cloni degli strumenti `git`. Sempre situato in `[AppRoot]/managed_tools/`.
    *   `logs/`: Per i log dell'applicazione. Sempre situato in `[AppRoot]/logs/`.

### Destinatari

*   Sviluppatori che necessitano di eseguire una varietà di script di build, script di utilità o applicazioni di supporto.
*   Ingegneri che gestiscono ed eseguono molteplici strumenti a riga di comando con parametri diversi.
*   Team che cercano un modo standardizzato e intuitivo per avviare utility di sviluppo condivise.
```

**Punti chiave di questa versione:**

*   **Struttura Chiara**: Suddivisione in "Overview", "Core Functionality", "How It Works - Path Management" e "Target Users" per una migliore leggibilità.
*   **Enfasi sul Flusso**: Spiega come le diverse parti del tool interagiscono (registro -> scoperta -> UI -> esecuzione -> gestione).
*   **Dettagli sulla Configurazione**: Approfondisce il ruolo e la struttura di `tools_registry.json`.
*   **Gestione dei Percorsi Esplicitata**: Chiarisce come i percorsi vengono gestiti in modalità script vs. frozen, il che è cruciale per la comprensione e il troubleshooting.
*   **Terminologia Consistente**: Utilizza termini come "AppRoot" per riferirsi alla directory base in modo dinamico.