SXXXXXXX_ProjectUtility/doc/English-manual.md

Assolutamente! Creare un manuale utente completo richiederebbe un po' più di interazione e dettagli specifici sui tuoi "tool" d'esempio, ma posso fornirti una struttura solida e dei contenuti di base che potrai espandere.

Ecco una bozza per il manuale utente, anch'esso formattato per essere facilmente inserito in un file Markdown o convertito in altri formati.

# Project Utility Dashboard - User Manual

---

## English

### 1. Introduction

Welcome to the Project Utility Dashboard! This application is designed to provide a centralized and user-friendly interface for managing and running a variety of command-line tools, scripts, and external applications, whether they are stored locally or managed via Git repositories.

**Key Goals:**

*   **Simplify Execution**: Run complex tools with multiple parameters through an intuitive GUI.
*   **Organize Tools**: Keep all your frequently used utilities in one discoverable place.
*   **Manage Git-based Tools**: Easily clone, update, and run tools directly from Git.
*   **Improve Workflow**: Save time by remembering parameters and providing a consistent launch experience.

### 2. Installation & Setup

**(This section might need customization based on your distribution method)**

*   **Prerequisites**:
    *   Python 3.8+
    *   (Optional but Recommended) Git installed and available in your system's PATH for Git tool functionality.
    *   (Optional) `GitPython` Python library (`pip install GitPython`) for full Git integration features within the dashboard. If not present, Git-related UI elements will be disabled or show "GitPython Missing".
*   **Running from Source**:
    1.  Clone the `ProjectUtility` repository.
    2.  Install dependencies: `pip install -r requirements.txt` (You'll need to create this file listing `GitPython` if you use it).
    3.  Run the application: `python -m projectutility` from the repository root.
*   **Using a PyInstaller Executable**:
    1.  Download or build the `ProjectUtility.exe` (or platform-specific executable).
    2.  Place the executable in a desired directory.
    3.  On first run, it might create `config/`, `logs/`, and `managed_tools/` subdirectories alongside the executable if they don't exist.

### 3. Application Overview

The main window is divided into several key areas:

*   **Menu Bar**:
    *   **Tools**:
        *   `Update All Git Tools`: Attempts to clone or pull updates for all enabled Git tools.
        *   `Configure Selected Tool...`: Opens a dialog to configure the currently selected tool.
        *   `Reload Tool List`: Manually rescans the tool registry and updates the tool list.
*   **Available Tools Pane (Left)**: Lists all discovered and enabled tools. Clicking a tool selects it for configuration and execution.
*   **Tool Options Pane (Top-Right, Scrollable)**:
    *   Displays the selected tool's `Display Name` and `Description`.
    *   Shows Git status information if it's a Git-managed tool.
    *   Dynamically generates input widgets for the tool's defined `Parameters`.
*   **Output Log Pane (Middle-Right)**: Shows `stdout` and `stderr` from running tools, as well as status messages from the dashboard itself.
*   **Run Button Area (Bottom-Right)**: Contains the "Run Tool" button.
*   **Running Tools Pane (Bottom)**: A tree view listing all tools currently being executed by the dashboard, showing their Run ID, Name, Status, and PID. Allows termination of selected processes.

### 4. Configuring Tools (`tools_registry.json`)

The core of the dashboard's flexibility lies in the `projectutility/config/tools_registry.json` file (or `[AppExecutableDir]/config/tools_registry.json` for frozen apps). This JSON file contains an array of tool definition objects.

**Anatomy of a Tool Entry:**

```json
{
  "id": "unique_tool_id", // Mandatory, unique string
  "display_name": "My Awesome Tool", // Mandatory, string shown in GUI
  "description": "This tool does awesome things.", // Optional, string
  "type": "local", // Mandatory: "local" or "git"
  "enabled": true, // Optional, boolean (default: true)
  "run_command": ["python", "scripts/my_script.py"], // Mandatory, list of strings
  "has_gui": false, // Mandatory, boolean (does the tool have its own GUI?)
  "version": "1.0.1", // Optional, string
  // --- For type: "local" ---
  "parameters": [ // Optional, list of parameter objects
    {
      "name": "input_file",
      "label": "Input File:",
      "type": "file", // e.g., string, integer, float, boolean, file, folder
      "required": true,
      "default": "default.txt", // Optional default value
      "description": "Path to the input data file.", // Optional tooltip
      "options": {"filter": [["Text Files", "*.txt"], ["All Files", "*.*"]]} // Optional, type-specific
    }
  ],
  // --- For type: "git" ---
  "git_url": "https://gitea.example.com/user/my_git_tool.git", // Required for "git"
  "git_ref": "main", // Optional, default "main" (branch, tag, or commit)
  "local_dir_name": "my_git_tool_clone", // Optional, directory name in managed_tools/
  "parameters_definition_file": "tool_params.json" // Optional, path to JSON file in repo root
}

Key Fields Explained:

• id: Must be unique across all tools.
• type:
  • local: For executables in PATH or scripts within the application's tools/ directory.
    • tools/ directory (for scripts):
      • If run from source: [RepoRoot]/tools/
      • If run as executable: [AppExecutableDir]/_internal/tools/ (bundled by PyInstaller)
  • git: For tools cloned and managed from a Git repository. They will be cloned into managed_tools/.
• run_command:
  • The first element is usually the executable (e.g., python, powershell.exe, my_app.exe).
  • Subsequent elements are arguments.
  • For local scripts in tools/, use paths relative to tools/, e.g., ["python", "my_tool_subdir/main.py"]. The dashboard resolves this to an absolute path.
• parameters: An array of objects, each defining an input parameter for the GUI.
  • name: Internal key for the parameter.
  • label: Text shown next to the input field.
  • type: Determines the widget: string, integer, float, boolean, file (select file), folder (select directory).
  • required: true or false.
  • default: A default value.
  • description: Tooltip text.
  • options: Type-specific configurations. For file: {"filter": [["Description", "*.ext"]], "save_as": false}.
• parameters_definition_file (for git tools): If specified, this is a path relative to the root of the cloned Git repository to a JSON file. This JSON file must have a root object with a key "parameters" which is an array of parameter objects (same format as inline parameters).
• local_dir_name (for git tools): If omitted, the id is used as the directory name within managed_tools/.

Example: Local Python Script

{
  "id": "my_local_script",
  "display_name": "My Data Processor",
  "description": "Processes CSV data using a local Python script.",
  "type": "local",
  "run_command": ["python", "data_processing/processor.py"],
  "has_gui": false,
  "parameters": [
    {"name": "csv_input", "label": "Input CSV:", "type": "file", "required": true, "options": {"filter": [["CSV Files", "*.csv"]]}},
    {"name": "output_folder", "label": "Output Dir:", "type": "folder", "required": true},
    {"name": "threshold", "label": "Threshold:", "type": "float", "required": false, "default": 0.5}
  ]
}

(This assumes data_processing/processor.py exists within your tools/ directory).

Example: Git-Managed Tool

{
  "id": "awesome_git_cli",
  "display_name": "Awesome CLI (from Git)",
  "description": "A command-line utility fetched from Git.",
  "type": "git",
  "git_url": "https://gitea.example.com/user/awesome-cli.git",
  "git_ref": "v1.2.0", // Track a specific tag
  "run_command": ["python", "awesome_cli/main.py"], // Command relative to cloned repo root
  "has_gui": false,
  "parameters_definition_file": "params_config.json" // File in awesome-cli repo root
}

5. Using the Dashboard

1. Launch the Application.
2. Select a Tool: Click on a tool name in the "Available Tools" list on the left.
3. Review & Input Parameters:
   • The tool's description and any Git status information will appear in the "Tool Options" area.
   • Input fields for the tool's parameters will be shown. Fill them as required.
   • Required parameters are typically indicated by the GUI (e.g., an asterisk or distinct styling, though current implementation relies on label*).
   • For file or folder types, use the "Browse..." button.
   • Last used parameters are often pre-filled.
4. Run the Tool: Click the "Run Tool" button.
5. Monitor Output: Observe stdout and stderr in the "Output Log". Messages may be color-coded or specially formatted if the tool outputs structured JSON.
6. Manage Running Tools:
   • The "Running Tools" panel at the bottom shows active processes.
   • To terminate a tool, select it in this panel and click "Terminate Selected".

6. Managing Git Tools

• Initial Clone: If a Git tool has not been cloned yet, selecting it in the list might show "Not Cloned". Attempting to "Update All Git Tools" or updating it via its "Configure Selected Tool..." window will trigger the clone process into the managed_tools/ directory.
• Checking Status:
  • When a Git tool is selected, its current Git status (relative to the configured git_ref on origin) is fetched and displayed.
  • This can be manually refreshed from the tool's configuration window.
• Updating Tools:
  • Single Tool: Open the "Configure Selected Tool..." dialog, optionally change the Git Ref field, and click "Update This Tool".
  • All Tools: Use the "Tools" > "Update All Git Tools" menu item. This will iterate through all enabled Git tools, fetch latest changes from origin, and attempt to bring them to their configured git_ref.
• Output during Update: Progress messages (cloning, fetching, checking out) will appear in the "Output Log".

7. Tool Configuration Window

Accessed via "Tools" > "Configure Selected Tool..." (when a tool is selected).

• Editable Fields:
  • Display Name: Change how the tool appears in the list.
  • Description: Modify the tool's descriptive text.
  • Enabled: Toggle whether the tool is active and discoverable.
  • Git Ref (for Git tools only): Change the branch, tag, or commit hash the tool should track. Note: The update process will try to check out this new reference.
• Read-Only Info: Displays other configured details like Tool ID, Run Command, Git URL.
• Git Status (for Git tools):
  • Shows detailed status (current local ref, hashes, etc.).
  • Refresh Status button: Re-fetches from remote and updates status display.
  • Update This Tool button: Initiates an update for this tool to its currently configured (or newly entered) Git Ref.
• Saving: Click "Save Changes" to persist modifications to tools_registry.json. The main tool list will refresh.

8. Troubleshooting

• ModuleNotFoundError: No module named 'projectutility' (Frozen App):
  • Ensure all necessary __init__.py files are present in the source package directories (projectutility/, projectutility/core/, projectutility/gui/).
  • Check your PyInstaller .spec file:
    • pathex should point to your project's root directory.
    • hiddenimports should list projectutility and its submodules if not automatically detected.
    • datas must correctly include non-Python files like local tool scripts (tools directory) and any default tools_registry.json you want to bundle.
• Tool Not Found / "Unavailable":
  • Local Tools:
    • Verify run_command in tools_registry.json.
    • If it's an executable (e.g., notepad.exe), ensure it's in your system's PATH.
    • If it's a script, ensure the script path in run_command (e.g., my_script_dir/script.py) is correct relative to the tools/ directory and that the tools/ directory (with the script) is correctly bundled if running the frozen app.
  • Git Tools:
    • Ensure the git_url is correct and accessible.
    • Check if the tool has been cloned into managed_tools/. If not, try updating it.
    • Verify the run_command path is correct relative to the root of the cloned Git repository.
    • If a parameters_definition_file is used, ensure its path is correct relative to the cloned repo root.
• Git Operations Failing:
  • Ensure Git is installed and in PATH.
  • Ensure GitPython is installed in the Python environment the dashboard is using.
  • Check network connectivity to the Git remote.
  • Examine messages in the "Output Log" for specific Git errors.
• Permission Denied: The application (or the user running it) might not have permission to execute a script or access a directory.