cadMasterCLI/README.md

<!-- FR -->
# cadMasterCLI

Outil de lancement simplifié de scripts PowerShell pour les automates Distech Controls Eclypse.

---

> **IMPORTANT : Ce projet est un développement personnel indépendant.**
>
> Ce projet a été développé par Charles-Arthur DAVID à titre personnel.
> Distech Controls n'est pas responsable de ce projet et ne le supporte pas.
> Aucune demande de support ne sera prise en charge par Distech Controls.
> Distech Controls ne fournit aucune garantie ni assistance technique pour ce projet.

---

## À quoi ça sert ?

cadMasterCLI est une interface graphique qui vous permet de **lancer des scripts d'automatisation** sans savoir utiliser le terminal, sans connaître PowerShell, et sans configuration technique.

Il suffit de :
1. Faire un clique-droit sur le fichier cadMasterCLI.ps1 et choisir "Exécuter avec Powershell"
2. Sélectionner le script que vous souhaitez exécuter dans la liste à gauche
3. Remplir les informations demandées (adresse IP, fichier CSV, etc.)
4. Cliquer sur **Lancer le script** et suivre le résultat dans le journal d'exécution intégré

Les scripts sont téléchargés automatiquement depuis un serveur centralisé (Gitea). Si vous n'avez pas accès au réseau, les scripts déjà utilisés restent disponibles en mode hors ligne. La liste des scripts disponibles est consultable sur [git.cadjou.net/ScriptPowerShell](https://git.cadjou.net/ScriptPowerShell).

L'interface est disponible en **français et en anglais**, et cadMasterCLI **vérifie et propose ses propres mises à jour** au démarrage.

---

## Prérequis

| Élément | Détail |
|---|---|
| Système d'exploitation | Windows 10 ou Windows 11 |
| PowerShell | Version 5.1 — **déjà inclus dans Windows 10/11, rien à installer** |
| Accès réseau | Nécessaire pour télécharger les scripts (hors ligne possible si déjà téléchargés) |

Aucun autre logiciel n'est nécessaire.

---

## Installation

Aucune installation requise. cadMasterCLI est un seul fichier `.ps1`.

1. Téléchargez le fichier `cadMasterCLI.ps1` et placez-le dans un dossier de votre choix, ou téléchargez [l'archive complète du projet (.zip)](https://git.cadjou.net/DistechControls/cadMasterCLI/archive/main.zip).
2. C'est tout.

---

## Premier lancement

### Étape 1 — Débloquer le fichier (première fois uniquement)

Windows peut bloquer les fichiers téléchargés depuis Internet. Pour lever ce blocage :

1. Faites un **clic droit** sur `cadMasterCLI.ps1`
2. Cliquez sur **Propriétés**
3. En bas de la fenêtre, cochez **Débloquer** si la case est présente
4. Cliquez sur **OK**

> Si la case "Débloquer" n'apparaît pas, l'étape n'est pas nécessaire.

### Étape 2 — Autoriser l'exécution des scripts (première fois uniquement)

Si un message d'erreur apparaît à propos de la "stratégie d'exécution" :

1. Appuyez sur la touche **Windows**, tapez `PowerShell`
2. Faites un clic droit sur **Windows PowerShell** → **Exécuter en tant qu'administrateur**
3. Copiez-collez la commande suivante et appuyez sur Entrée :

```
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```

4. Tapez `O` pour confirmer, puis fermez la fenêtre PowerShell.

### Étape 3 — Lancer cadMasterCLI

**Méthode simple :** faites un **clic droit** sur `cadMasterCLI.ps1` → **Exécuter avec PowerShell**.

**Méthode alternative :**
1. Ouvrez PowerShell (touche Windows → tapez `PowerShell` → Entrée)
2. Naviguez vers le dossier contenant le fichier, par exemple :
   ```
   cd C:\Outils\cadMasterCLI
   ```
3. Lancez le script :
   ```
   .\cadMasterCLI.ps1
   ```

---

## Utilisation

cadMasterCLI tient dans **une seule fenêtre** : la liste des scripts à gauche, et un panneau à droite qui affiche la documentation, le formulaire et le journal d'exécution du script sélectionné.

### 1. Choisir la langue de l'interface

Un bouton **FR / EN** en haut à droite de la fenêtre permet de basculer l'interface entre français et anglais à tout moment. Au premier lancement, la langue de Windows est détectée automatiquement ; votre choix est ensuite mémorisé pour les prochaines fois.

### 2. Sélectionner un script

La liste à gauche affiche en permanence tous les scripts disponibles, avec pour chacun :

| Élément | Signification |
|---|---|
| Nom | Nom du script |
| Date | Date de la dernière mise à jour sur le serveur |
| Badge vert **En cache** | Le script a déjà été téléchargé sur cet ordinateur |
| Badge orange **Nouveau** | Une mise à jour est disponible pour ce script |

Cliquez sur un script pour afficher sa documentation et son formulaire de paramètres dans le panneau de droite.

### 3. Remplir les paramètres

Le panneau de droite affiche :

- **À gauche** : la documentation du script (README), pour comprendre à quoi il sert et comment le remplir.
- **À droite** : le formulaire de paramètres à remplir, ainsi que le journal d'exécution en dessous.

**Types de champs :**

| Apparence | Ce qu'il faut faire |
|---|---|
| Champ texte blanc | Saisir une valeur (adresse IP, nom d'utilisateur, etc.) |
| Boutons ronds (RadioButtons) | Sélectionner une option parmi les choix proposés |
| Case à cocher | Activer ou désactiver une option |
| Bouton **Parcourir...** | Choisir un fichier CSV sur votre ordinateur |

Les champs marqués **Obligatoire** doivent impérativement être remplis avant de pouvoir lancer le script. Le bouton **Lancer le script** reste grisé tant que ces champs sont vides — il devient vert une fois tout renseigné.

Cliquez sur **[?] Voir l'aide** sous un champ pour afficher une description détaillée de ce paramètre.

**Panneau README :**
- Cliquez sur **Fermer README** pour masquer la documentation et agrandir le formulaire.
- Cliquez sur **Ouvrir README** pour la réafficher.
- Vous pouvez redimensionner le panneau README en faisant glisser la barre de séparation entre les deux zones.
- Si le README du script propose une version française et anglaise, la section affichée suit automatiquement la langue choisie dans l'interface.

### 4. Lancer le script et suivre l'exécution

Une fois tous les champs obligatoires remplis :

- Cliquez sur **Lancer le script** (bouton vert).
- Le script s'exécute en arrière-plan ; sa sortie s'affiche **en direct dans le journal d'exécution**, directement dans la fenêtre (plus de fenêtre de terminal séparée).
- Pendant l'exécution, la liste des scripts et les boutons sont désactivés ; ils redeviennent disponibles à la fin.
- Un message final indique si l'exécution s'est terminée avec succès ou en erreur.

Cliquez sur **Retour à la liste** pour revenir à la liste des scripts et en sélectionner un autre.

---

## Mise à jour automatique des scripts

Lorsqu'une nouvelle version d'un script est disponible sur le serveur, cadMasterCLI le signale avec un badge **Nouveau** dans la liste et vous propose de télécharger la mise à jour au moment où vous sélectionnez ce script.

Les scripts sont stockés localement dans le sous-dossier `scripts\` à côté de `cadMasterCLI.ps1`.

---

## Mise à jour automatique de cadMasterCLI lui-même

À chaque démarrage, cadMasterCLI vérifie s'il existe une version plus récente de lui-même sur le serveur.

- Si c'est le cas, une fenêtre vous propose de l'installer.
- En acceptant, la nouvelle version est téléchargée, remplace automatiquement le fichier `cadMasterCLI.ps1` actuel, et l'application redémarre toute seule.
- En refusant, l'application continue de démarrer normalement avec la version actuelle (la question sera reposée au prochain lancement).
- Si le serveur est inaccessible, aucune vérification n'est possible : cadMasterCLI démarre normalement, sans message d'erreur.

---

## Mode hors ligne

Si le serveur Gitea est inaccessible (pas de réseau), cadMasterCLI utilise automatiquement les scripts déjà téléchargés. Un message vous prévient que vous êtes en mode hors ligne.

---

## Cas d'erreurs fréquents

| Message | Cause probable | Solution |
|---|---|---|
| Erreur de stratégie d'exécution | PowerShell bloque les scripts | Voir **Étape 2** du premier lancement |
| Impossible de contacter Gitea | Pas d'accès réseau | Vérifiez votre connexion ou utilisez le mode hors ligne |
| Script introuvable en cache | Script jamais téléchargé + pas de réseau | Connectez-vous au réseau et relancez |
| Fichier bloqué par Windows | Script téléchargé depuis Internet | Voir **Étape 1** du premier lancement |

---

## Structure des fichiers

```
cadMasterCLI/
├── cadMasterCLI.ps1                          ← fichier principal à lancer
├── cadmastercli.config.json                  ← préférence de langue (créé automatiquement)
├── README.md                                 ← cette documentation
├── doc_contribution/
│   ├── CONTRIBUTING_SCRIPTS.md               ← guide pour créer de nouveaux scripts
│   ├── _template_script.ps1                  ← modèle de script
│   └── _template_script.README.md            ← modèle de README bilingue FR/EN
└── scripts/                                  ← scripts téléchargés (créé automatiquement)
    └── NomDuScript/
        └── NomDuScript.ps1
```

<!-- EN -->
# cadMasterCLI

Simplified PowerShell script launcher for Distech Controls Eclypse controllers.

---

> **IMPORTANT: This project is an independent personal development.**
>
> This project was developed by Charles-Arthur DAVID on a personal basis.
> Distech Controls is not responsible for this project and does not support it.
> No support request will be handled by Distech Controls.
> Distech Controls provides no warranty or technical assistance for this project.

---

## What is it for?

cadMasterCLI is a graphical interface that lets you **run automation scripts** without knowing how to use the terminal, without knowing PowerShell, and without any technical configuration.

Just:
1. Right-click the cadMasterCLI.ps1 file and choose "Run with PowerShell"
2. Select the script you want to run from the list on the left
3. Fill in the requested information (IP address, CSV file, etc.)
4. Click **Run script** and follow the result in the built-in execution log

Scripts are automatically downloaded from a centralized server (Gitea). If you don't have network access, previously used scripts remain available in offline mode. The list of available scripts can be browsed at [git.cadjou.net/ScriptPowerShell](https://git.cadjou.net/ScriptPowerShell).

The interface is available in **French and English**, and cadMasterCLI **checks for and offers its own updates** at startup.

---

## Requirements

| Item | Detail |
|---|---|
| Operating system | Windows 10 or Windows 11 |
| PowerShell | Version 5.1 — **already included in Windows 10/11, nothing to install** |
| Network access | Required to download scripts (offline use possible once already downloaded) |

No other software is required.

---

## Installation

No installation required. cadMasterCLI is a single `.ps1` file.

1. Download the `cadMasterCLI.ps1` file and place it in a folder of your choice, or download the [full project archive (.zip)](https://git.cadjou.net/DistechControls/cadMasterCLI/archive/main.zip).
2. That's it.

---

## First launch

### Step 1 — Unblock the file (first time only)

Windows may block files downloaded from the Internet. To lift this block:

1. **Right-click** on `cadMasterCLI.ps1`
2. Click **Properties**
3. At the bottom of the window, check **Unblock** if the checkbox is present
4. Click **OK**

> If the "Unblock" checkbox does not appear, this step is not necessary.

### Step 2 — Allow script execution (first time only)

If an error message appears about "execution policy":

1. Press the **Windows** key, type `PowerShell`
2. Right-click **Windows PowerShell** → **Run as administrator**
3. Copy-paste the following command and press Enter:

```
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```

4. Type `Y` to confirm, then close the PowerShell window.

### Step 3 — Launch cadMasterCLI

**Simple method:** **right-click** `cadMasterCLI.ps1` → **Run with PowerShell**.

**Alternative method:**
1. Open PowerShell (Windows key → type `PowerShell` → Enter)
2. Navigate to the folder containing the file, for example:
   ```
   cd C:\Outils\cadMasterCLI
   ```
3. Run the script:
   ```
   .\cadMasterCLI.ps1
   ```

---

## Usage

cadMasterCLI fits in **a single window**: the list of scripts on the left, and a panel on the right showing the documentation, form, and execution log of the selected script.

### 1. Choose the interface language

An **FR / EN** button at the top right of the window lets you switch the interface between French and English at any time. On first launch, the Windows language is detected automatically; your choice is then remembered for next time.

### 2. Select a script

The list on the left always shows all available scripts, each with:

| Item | Meaning |
|---|---|
| Name | Script name |
| Date | Date of the last update on the server |
| Green **Cached** badge | The script has already been downloaded on this computer |
| Orange **New** badge | An update is available for this script |

Click a script to display its documentation and parameter form in the right-hand panel.

### 3. Fill in the parameters

The right-hand panel shows:

- **On the left**: the script's documentation (README), to understand what it's for and how to fill it in.
- **On the right**: the parameter form to fill in, along with the execution log below.

**Field types:**

| Appearance | What to do |
|---|---|
| White text field | Enter a value (IP address, username, etc.) |
| Round buttons (RadioButtons) | Select one option among the choices offered |
| Checkbox | Enable or disable an option |
| **Browse...** button | Choose a CSV file on your computer |

Fields marked **Required** must be filled in before the script can be run. The **Run script** button stays greyed out while these fields are empty — it turns green once everything is filled in.

Click **[?] View help** below a field to display a detailed description of that parameter.

**README panel:**
- Click **Close README** to hide the documentation and expand the form.
- Click **Open README** to show it again.
- You can resize the README panel by dragging the divider between the two areas.
- If the script's README offers both a French and an English version, the section shown automatically follows the language chosen in the interface.

### 4. Run the script and follow execution

Once all required fields are filled in:

- Click **Run script** (green button).
- The script runs in the background; its output is displayed **live in the execution log**, directly in the window (no more separate terminal window).
- While running, the script list and buttons are disabled; they become available again at the end.
- A final message indicates whether the run finished successfully or with an error.

Click **Back to list** to return to the script list and select another one.

---

## Automatic script updates

When a new version of a script is available on the server, cadMasterCLI flags it with a **New** badge in the list and offers to download the update when you select that script.

Scripts are stored locally in the `scripts\` subfolder next to `cadMasterCLI.ps1`.

---

## Automatic update of cadMasterCLI itself

At every startup, cadMasterCLI checks whether a newer version of itself is available on the server.

- If so, a window offers to install it.
- If you accept, the new version is downloaded, automatically replaces the current `cadMasterCLI.ps1` file, and the application restarts on its own.
- If you decline, the application continues to start normally with the current version (you will be asked again at the next launch).
- If the server is unreachable, no check is possible: cadMasterCLI starts normally, without an error message.

---

## Offline mode

If the Gitea server is unreachable (no network), cadMasterCLI automatically uses previously downloaded scripts. A message informs you that you are in offline mode.

---

## Common error cases

| Message | Likely cause | Solution |
|---|---|---|
| Execution policy error | PowerShell is blocking scripts | See **Step 2** of first launch |
| Cannot contact Gitea | No network access | Check your connection or use offline mode |
| Script not found in cache | Script never downloaded + no network | Connect to the network and try again |
| File blocked by Windows | Script downloaded from the Internet | See **Step 1** of first launch |

---

## File structure

```
cadMasterCLI/
├── cadMasterCLI.ps1                          ← main file to run
├── cadmastercli.config.json                  ← language preference (created automatically)
├── README.md                                 ← this documentation
├── doc_contribution/
│   ├── CONTRIBUTING_SCRIPTS.md               ← guide for creating new scripts
│   ├── _template_script.ps1                  ← script template
│   └── _template_script.README.md            ← bilingual FR/EN README template
└── scripts/                                  ← downloaded scripts (created automatically)
    └── NomDuScript/
        └── NomDuScript.ps1
```