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.