mattpocock/wizard

Que fait wizard ?

Un wizard est un script bash qui guide un humain, étape par étape, à travers une procédure manuelle fastidieuse à réaliser à la main et fastidieuse à ré-expliquer à une IA à chaque fois. Il ouvre chaque URL, indique exactement quoi cliquer et copier, capture les valeurs, les écrit là où elles doivent être (.env, secrets GitHub), confirme à chaque étape, et indique combien d'étapes restent. Il peut configurer des services tiers, exécuter une migration ponctuelle, ou faire passer le projet d'un état à un autre.

L'expérience utilisateur agréable est déjà résolue par template.sh : progression étape par étape, portes de confirmation, ouverture de liens multiplateforme (y compris WSL), saisie cachée des secrets, mise à jour idempotente du .env, écriture gh secret/gh variable, et un résumé de fin. Votre seul travail consiste à délimiter la procédure et à rédiger ses étapes. La bibliothèque au-dessus du marqueur STAGES est identique dans chaque wizard ; cette cohérence est le point essentiel : ne la modifiez jamais à la main.

Un wizard est éphémère par défaut : conçu pour une seule exécution, sauvegardé dans un chemin temporaire ou scripts/, supprimé une fois le travail terminé. Ne le versionnez que lorsque l'utilisateur souhaite un chemin d'installation reproductible destiné à rester dans le dépôt.

Processus

1. Délimiter la procédure

Déterminez chaque étape manuelle que l'humain doit effectuer et chaque valeur qui sera capturée en cours de route. Lisez d'abord le dépôt, ne posez pas de questions à froid :

• Pour l'installation : .env, .env.example, .env.*, README, docker-compose*, la configuration du framework, et .github/workflows/* (chaque référence secrets.* / vars.* est une valeur que le wizard doit produire).
• Pour une migration ou une transition : l'état actuel, l'état cible, et les actions irréversibles entre les deux.

Ensuite, montrez à l'utilisateur la liste ordonnée des étapes et les valeurs que chacune produit, puis demandez confirmation : il peut ajouter, supprimer ou réordonner.

Terminé lorsque : chaque étape est nommée dans l'ordre, et pour chaque valeur capturée vous savez (a) où l'humain l'obtient, (b) où elle est écrite (.env, un secret GitHub, les deux, ou nulle part ; certaines étapes sont de pures actions), et (c) si elle est secrète (saisie cachée) ou publique.

2. Cartographier le parcours de chaque étape

Pour chaque étape, écrivez le chemin précis que l'humain suit : quelle URL ouvrir, quoi faire là, où la valeur est affichée, quelle variable elle remplit, par exemple : « Tableau de bord → Développeurs → Clés API → Révéler la clé de test → copier ». Là où vous ne connaissez pas réellement l'interface utilisateur actuelle ou la commande exacte, dites-le et demandez à l'utilisateur ou consultez la documentation : n'inventez jamais des étapes qui pourraient ne pas exister.

Terminé lorsque : chaque étape se traduit par des instructions concrètes qu'un inconnu pourrait suivre.

3. Rédiger le wizard

Copiez template.sh vers le chemin cible. Remplacez l'exemple d'étape par une stage par étape, dans l'ordre des dépendances. Utilisez les fonctions d'aide de la bibliothèque : stage, say/step, open_url, ask/ask_secret, write_env, set_secret/set_var, pause/confirm. Définissez TOTAL_STAGES au nombre d'étapes que vous avez écrites.

Respectez le standard défini par le template : ouvrez l'URL avant de demander sa valeur, utilisez ask_secret pour tout ce qui est secret, write_env pour chaque valeur persistée, set_secret uniquement pour les valeurs dont le CI a réellement besoin, et confirm avant toute action irréversible. Chaque stage efface l'écran pour que seule l'étape en cours soit visible : gardez une étape sur une seule tâche ciblée afin que rien de ce dont l'humain a besoin ne défile hors de l'écran. Ne touchez pas à la bibliothèque au-dessus du marqueur.

4. Vérifier et transmettre

• bash -n <script> ; exécutez shellcheck si disponible.
• chmod +x <script>.
• Ne l'exécutez pas vous-même de bout en bout : il ouvre des navigateurs et se bloque sur la saisie humaine. Tracez-le statiquement à la place : chaque valeur de l'étape 1 est capturée et atterrit là où l'étape 1 l'a dit, et chaque nom de set_secret correspond exactement à une référence secrets.* dans le CI.
• Dites à l'utilisateur comment l'exécuter. S'il s'agit d'un chemin d'installation reproductible, versionnez-le et liez-le depuis le README afin que la prochaine personne exécute le script au lieu de demander à une IA.