175 lines
12 KiB
Markdown
175 lines
12 KiB
Markdown
# 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.
|