# Guide de conception de scripts pour cadMasterCLI

Ce guide décrit les règles minimales pour qu'un script PowerShell soit correctement reconnu et piloté par cadMasterCLI : détection des paramètres, affichage de l'aide, types lisibles, etc.

---

## Règles minimales

### 1. Comment-based help obligatoire

Le script **doit** avoir un bloc `.SYNOPSIS` et un bloc `.PARAMETER` pour **chaque paramètre**.
cadMasterCLI lit ces blocs via `Get-Help` pour afficher les descriptions dans l'interface (bouton "Voir l'aide").

```powershell
<#
.SYNOPSIS
    Courte description en une ligne (affichée dans la liste de sélection).

.PARAMETER MonParam
    Description claire de ce que fait ce paramètre, ses valeurs attendues,
    son impact sur l'exécution du script.
#>
```

### 2. Bloc `param()` avec types et ValidateSet

- **Toujours typer** les paramètres : `[string]`, `[int]`, `[double]`, `[switch]`...
- **Utiliser `[ValidateSet(...)]`** pour les paramètres à choix limité — cadMasterCLI affichera automatiquement des **RadioButtons**.
- **Marquer les paramètres obligatoires** avec `[Parameter(Mandatory)]`.

```powershell
param(
    [Parameter(Mandatory)]
    [ValidateSet("Read", "Write")]
    [string]$Action,

    [Parameter(Mandatory)]
    [string]$CsvInput,

    [string]$Username = "admin"
)
```

### 3. Nommage des paramètres fichier/CSV

cadMasterCLI détecte automatiquement un paramètre comme **fichier** et affiche un bouton "Parcourir" si le nom contient l'un des mots-clés suivants :

| Mot-clé | Exemple de paramètre |
|---|---|
| `Path` | `$OutputPath` |
| `File` | `$InputFile` |
| `Csv` | `$CsvExport` |
| `Input` | `$CsvInput` |
| `Output` | `$OutputFile` |

Si le nom contient `Csv` ou `Input`, une zone de collage d'IPs avec conversion automatique en CSV est également proposée.

### 4. README bilingue FR/EN

Depuis cadMasterCLI v2, l'interface peut s'afficher en français ou en anglais. Pour que la documentation du script (panneau de gauche) suive la langue active, le `README.md` du dépôt peut contenir les deux versions dans un seul fichier, séparées par des marqueurs HTML :

```markdown
<!-- FR -->
# Nom du script

Description en français...

## Paramètres

- `MonParam` : ce que fait ce paramètre.

<!-- EN -->
# Script name

Description in English...

## Parameters

- `MonParam`: what this parameter does.
```

Règles :

- Les marqueurs `<!-- FR -->` et `<!-- EN -->` doivent être seuls sur leur ligne.
- L'ordre des sections n'a pas d'importance.
- Si une seule des deux langues est présente, cadMasterCLI l'affiche quelle que soit la langue active (pas d'erreur).
- **Rétro-compatibilité** : un `README.md` sans aucun marqueur continue de s'afficher tel quel dans les deux langues (comportement identique aux versions précédentes de cadMasterCLI).

Voir `_template_script.README.md` dans ce dépôt pour un exemple complet.

### 5. Structure du dépôt Gitea

Le dépôt doit contenir à sa racine :

```
MonScript/
├── MonScript.ps1       ← script principal (nom identique au dépôt recommandé)
├── README.md           ← documentation affichée dans cadMasterCLI avant exécution
└── modules/            ← (optionnel) modules PowerShell importés par le script
    └── MonModule.psm1
```

> cadMasterCLI télécharge tout le dépôt récursivement : les modules, configs et fichiers annexes sont préservés.

---

## Types reconnus et leur affichage

| Type PowerShell | Affiché dans l'interface |
|---|---|
| `[string]` | Texte |
| `[int]` / `[int32]` / `[int64]` | Nombre entier |
| `[double]` / `[single]` | Nombre décimal |
| `[bool]` | Vrai/Faux |
| `[datetime]` | Date |
| `[System.IO.FileInfo]` | Fichier |
| `[switch]` | Case à cocher |
| `[ValidateSet(...)]` | RadioButtons (un bouton par valeur) |

---

## Exemple minimal conforme

Voir `_template_script.ps1` (script) et `_template_script.README.md` (documentation bilingue) dans ce dépôt pour un squelette prêt à l'emploi.

Pour un exemple complet et fonctionnel, voir le script **DaliACLI**.