mattpocock/wizard

Wizard (Asistente Guiado)

Un wizard (asistente guiado) es un script bash que guía a una persona, paso a paso, a través de un procedimiento manual tedioso de realizar a mano y de reexplicar a una IA cada vez. Abre cada URL, indica exactamente qué hacer clic y copiar, captura los valores, los escribe donde correspondan (.env, secretos de GitHub), confirma en cada etapa y muestra cuántas etapas quedan. Puede configurar servicios de terceros, ejecutar una migración única o mover el proyecto de un estado a otro.

La excelente experiencia de usuario ya está resuelta por template.sh: progreso por etapas, puertas de confirmación, apertura de URLs multiplataforma (incluyendo WSL), entrada oculta de secretos, escritura idempotente en .env, comandos gh secret/gh variable y un resumen final. Tu trabajo se limita a definir el procedimiento y redactar sus etapas. La parte de la librería que está por encima del marcador STAGES es idéntica en todos los asistentes; esa consistencia es el objetivo: no la edites a mano.

Un asistente es efímero por defecto: se crea para una ejecución, se guarda en una ruta temporal o en scripts/, y se elimina cuando el trabajo termina. Solo debes versionarlo cuando el usuario quiera un procedimiento de configuración repetible que deba permanecer en el repositorio.

Proceso

1. Definir el alcance del procedimiento

Determina cada paso manual que la persona debe realizar y cada valor que se capturará durante el proceso. Lee el repositorio primero, no preguntes en frío:

• Para configuración: .env, .env.example, .env.*, README, docker-compose*, configuración del framework y .github/workflows/* (cada referencia a secrets.* / vars.* es un valor que el asistente debe producir).
• Para una migración o transición: el estado actual, el estado objetivo y las acciones irreversibles entre ellos.

Luego muestra al usuario la lista ordenada de etapas y los valores que cada una produce, y confirma: pueden agregar, eliminar o reordenar.

Completado cuando: cada etapa está nombrada en orden, y para cada valor capturado sabes (a) dónde lo obtiene la persona, (b) dónde se escribe (.env, un secreto de GitHub, ambos, o ninguno; algunas etapas son solo acciones), y (c) si es secreto (entrada oculta) o público.

2. Mapear el recorrido de cada etapa

Para cada etapa, escribe la ruta precisa que sigue una persona: qué URL abrir, qué hacer allí, dónde se muestra un valor, qué variable completa: p. ej., "Dashboard → Desarrolladores → Claves API → Revelar clave de prueba → copiar". Cuando no conozcas realmente la interfaz de usuario actual o el comando exacto, indícalo y pregunta al usuario o consulta la documentación: nunca inventes pasos que puedan no existir.

Completado cuando: cada etapa se traduce a instrucciones concretas que un desconocido podría seguir.

3. Crear el asistente

Copia template.sh en la ruta de destino. Reemplaza la etapa de ejemplo con un bloque stage por cada paso, en orden de dependencias. Usa las funciones auxiliares de la librería: stage, say/step, open_url, ask/ask_secret, write_env, set_secret/set_var, pause/confirm. Establece TOTAL_STAGES al número de etapas que hayas escrito.

Mantén el nivel que establece la plantilla: abre la URL antes de pedir su valor, usa ask_secret para cualquier dato secreto, usa write_env para cada valor persistido, usa set_secret solo para los valores que CI realmente necesita, y usa confirm antes de cualquier acción irreversible. Cada stage limpia la pantalla para que solo se vea el paso actual: mantén cada etapa enfocada en una sola tarea para que nada de lo que la persona necesita se desplace fuera de la vista. No toques la parte de la librería que está por encima del marcador.

4. Verificar y entregar

• bash -n <script>; ejecuta shellcheck si está disponible.
• chmod +x <script>.
• No lo ejecutes de principio a fin tú mismo: abre navegadores y se bloquea esperando entrada humana. En su lugar, haz una traza estática: cada valor del paso 1 se captura y llega al lugar que se indicó en el paso 1, y cada nombre de set_secret coincide exactamente con una referencia secrets.* en CI.
• Indica al usuario cómo ejecutarlo. Si es un procedimiento de configuración repetible, guárdalo en el repositorio y enlázalo desde el README para que la siguiente persona ejecute el script en lugar de preguntar a una IA.