cadMasterCLI/doc_contribution/CONTRIBUTING_SCRIPTS.md

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").

<#
.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)].

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 :

<!-- 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.