mattpocock/wizard

Was macht wizard?

Ein Wizard ist ein Bash-Skript, das einen Menschen Schritt für Schritt durch eine manuelle Prozedur führt, die von Hand mühsam und einem KI-Assistenten jedes Mal aufs Neue zu erklären ist. Es öffnet jede URL, sagt genau, was zu klicken und zu kopieren ist, erfasst die Werte, schreibt sie an den richtigen Ort (.env, GitHub Secrets), bestätigt jeden Schritt und zeigt an, wie viele Schritte noch übrig sind. Es kann Drittanbieterdienste konfigurieren, eine einmalige Migration durchführen oder das Projekt von einem Zustand in einen anderen überführen.

Die benutzerfreundliche Oberfläche wurde bereits in template.sh gelöst: schrittweiser Fortschritt, Bestätigungshürden, plattformunabhängiges URL-Öffnen (inklusive WSL), versteckte Eingabe von Secrets, idempotentes Aktualisieren von .env, Schreiben von gh secret/gh variable und eine abschließende Zusammenfassung. Ihre Aufgabe ist nur, die Prozedur abzugrenzen und ihre Schritte zu erstellen. Der Teil oberhalb der STAGES-Markierung ist in jedem Wizard identisch; diese Konsistenz ist der entscheidende Punkt: Niemals von Hand bearbeiten.

Ein Wizard ist standardmäßig flüchtig: Er wird für einen einzigen Durchlauf erstellt, in einem scripts/- oder temporären Verzeichnis gespeichert und nach Abschluss gelöscht. Committen Sie ihn nur, wenn der Benutzer einen wiederholbaren Einrichtungspfad wünscht, der im Repository verbleiben soll.

Ablauf

1. Abgrenzung der Prozedur

Ermitteln Sie jeden manuellen Schritt, den der Mensch ausführen muss, und jeden dabei erfassten Wert. Lesen Sie zuerst das Repository, fragen Sie nicht ohne Vorbereitung:

• Für Einrichtung: .env, .env.example, .env.*, README, docker-compose*, Framework-Konfiguration und .github/workflows/* (jeder secrets.*- / vars.*-Verweis ist ein Wert, den der Wizard erzeugen muss).
• Für eine Migration oder Umstellung: den aktuellen Zustand, den Zielzustand und die irreversiblen Aktionen dazwischen.

Zeigen Sie dem Benutzer anschließend die geordnete Liste der Schritte und die dabei erfassten Werte und holen Sie Bestätigung ein: Er kann Schritte hinzufügen, entfernen oder umsortieren.

Abgeschlossen, wenn: jeder Schritt in der richtigen Reihenfolge benannt ist und Sie für jeden erfassten Wert wissen, (a) woher der Mensch ihn bekommt, (b) wohin er geschrieben wird (.env, ein GitHub Secret, beides oder nirgendwo; einige Schritte sind reine Aktionen), und (c) ob er geheim ist (versteckte Eingabe) oder öffentlich.

2. Weg jedes Schrittes abbilden

Schreiben Sie für jeden Schritt den genauen Weg, den ein Mensch geht: Welche URL geöffnet, was dort getan, wo ein Wert angezeigt wird, welche Variable er füllt – z. B. „Dashboard → Entwickler → API-Schlüssel → Testschlüssel anzeigen → kopieren“. Wenn Sie die aktuelle Benutzeroberfläche oder den genauen Befehl nicht kennen, sagen Sie dies und fragen Sie den Benutzer oder prüfen Sie die Dokumentation: Erfinden Sie niemals Schritte, die es möglicherweise nicht gibt.

Abgeschlossen, wenn: jeder Schritt auf konkrete Anweisungen zurückgeht, die ein Fremder befolgen könnte.

3. Wizard erstellen

Kopieren Sie template.sh an den Zielpfad. Ersetzen Sie das Beispiel durch je ein stage pro Schritt, in Abhängigkeitsreihenfolge. Verwenden Sie die Bibliothekshilfsfunktionen: stage, say/step, open_url, ask/ask_secret, write_env, set_secret/set_var, pause/confirm. Setzen Sie TOTAL_STAGES auf die Anzahl der von Ihnen erstellten Schritte.

Halten Sie die von der Vorlage gesetzte Messlatte: Öffnen Sie die URL, bevor Sie nach ihrem Wert fragen, verwenden Sie ask_secret für alles Geheime, write_env für jeden gespeicherten Wert, set_secret nur für die Werte, die CI tatsächlich benötigt, und confirm vor jeder irreversiblen Aktion. Jedes stage löscht den Bildschirm, sodass nur der aktuelle Schritt sichtbar ist: Halten Sie einen Schritt auf eine fokussierte Aufgabe beschränkt, damit nichts, was der Mensch braucht, aus dem Bild scrollt. Berühren Sie nicht die Bibliothek oberhalb der Markierung.

4. Verifizieren und übergeben

• bash -n <Skript>; führen Sie shellcheck aus, falls verfügbar.
• chmod +x <Skript>.
• Führen Sie es nicht selbst vollständig aus: Es öffnet Browser und wartet auf Benutzereingaben. Prüfen Sie stattdessen statisch: Jeder Wert aus Schritt 1 wird erfasst und landet dort, wo Schritt 1 es vorgesehen hat, und jeder set_secret-Name entspricht exakt einem secrets.*-Verweis in CI.
• Teilen Sie dem Benutzer mit, wie er es ausführt. Wenn es ein wiederholbarer Einrichtungspfad ist, committen Sie es und verlinken Sie es in der README, sodass die nächste Person das Skript ausführt, anstatt einen KI-Assistenten zu fragen.