Lokal entwickeln
Mit new-tool.py und dev-proxy.py ein Werkzeug auf dem eigenen Rechner bauen und ansehen.
Im Klon des Repositorys liegen zwei Skripte. new-tool.py macht aus einer Collection ein Werkzeug, dev-proxy.py zeigt es im Browser, mit den Daten deiner Instanz. Beide brauchen Python 3 und sonst nichts. So siehst du jede Änderung sofort, ohne Push.
Der Weg in vier Befehlen
cd flow-tools
git pull --rebase origin draft
./new-tool.py aufgaben
./dev-proxy.py --tool tools/aufgaben
Öffne danach http://127.0.0.1:3000/ im Browser. Gefällt dir der Stand, lieferst du ihn als Entwurf aus:
git add . && git commit -m "aufgaben" && git push
Ein Werkzeug erzeugen: new-tool.py
./new-tool.py <collection> kopiert die Vorlage tools/example/ nach tools/<collection>/, setzt Name und Titel, trägt die Collection in tool.json unter uses ein und richtet app.js auf sie aus.
Das Skript holt dabei das Schema der Collection von der Instanz. Ein vertippter Name, ein fehlendes Leserecht und ein abgelaufenes Token fallen so gleich auf und nicht erst im Browser.
| Option | Bedeutung |
|---|---|
--name | Name des Verzeichnisses und der Adresse. Vorgabe: der Name der Collection |
--title | Titel des Werkzeugs. Vorgabe: der Titel der Collection |
--into | Zielverzeichnis. Vorgabe: tools |
--backend | Adresse der Instanz, ausserhalb eines Klons |
--token-file | Datei mit dem Zugriffstoken |
Die Vorlage ist generisch: Sie liest das Schema und baut Formular und Tabelle daraus. Ein Feld, das später dazukommt, erscheint von selbst. Was dein Werkzeug anders haben soll, änderst du in app.js und style.css.
Das Werkzeug ansehen: dev-proxy.py
./dev-proxy.py --tool tools/<name> liefert die Dateien aus deinem Verzeichnis aus und reicht jeden Aufruf unter /api/ an die Instanz weiter. Dabei setzt der Proxy dein Zugriffstoken ein.
| Option | Bedeutung |
|---|---|
--tool | Verzeichnis des Werkzeugs (Pflicht) |
--port | Port auf deinem Rechner. Vorgabe: 3000 |
--check | prüft nur die Auslieferungsregeln und startet nichts |
--backend | Adresse der Instanz, ausserhalb eines Klons |
--token-file | Datei mit dem Zugriffstoken |
Der Code deines Werkzeugs bleibt, wie die Instanz ihn ausliefert. Er schickt JSON an relative Pfade. Auf deinem Rechner setzt der Proxy das Token, in der Instanz reist das Sitzungscookie mit. Eine Unterscheidung „lokal oder nicht“ brauchst du im Code nicht.
Der Proxy setzt dieselbe Inhaltsrichtlinie wie die Instanz. Ein Inline-Skript scheitert also schon lokal.
Woher Adresse und Token kommen
In einem Klon brauchen beide Skripte weder --backend noch ein Token: Sie lesen die Adresse der Instanz aus git remote get-url origin, und das Token ebenfalls, wenn es dort in der Adresse steht. So richtet es setup.sh ein.
Ausserhalb eines Klons gibst du beides an:
export FLOW_TOKEN=flowpac_pat_...
./new-tool.py aufgaben --backend https://<instanz>
./dev-proxy.py --tool tools/aufgaben --backend https://<instanz>
Warum es einen Proxy braucht
Ein Werkzeug und die Datenschnittstelle müssen dieselbe Herkunft haben. Ein fetch von einem anderen Port bekommt das Sitzungscookie nicht, und die Instanz antwortet mit Absicht ohne CORS-Köpfe. Der Proxy legt deshalb beides auf eine Herkunft: deine Dateien und die Schnittstelle unter http://127.0.0.1:3000.
Warum der Proxy nur auf 127.0.0.1 lauscht
Der Proxy unterschreibt jeden Aufruf mit deinem Token. Wer ihn erreicht, handelt in der Instanz unter deinem Namen. Er lauscht deshalb nur auf der Rückschleife deines Rechners. Auf einer Adresse im Netz wäre er ein offener Zugang zur Instanz. Ändere das nicht, und leite den Port nicht weiter.
Was lokal anders ist
Fehler im Browser meldet flow.js nur unter /t/<name>/ an die Instanz. Lokal stehen sie in der Konsole des Browsers.