kodi/markdown_to_skillstown
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat(oa): add training-dir workflow and save flow for OnlineAcademy runner

Browse Source 
Introduce a simpler training-based workflow for the OnlineAcademy Playwright runner.

Changes included:
- support --training-dir and automatic loading of content.md and training.json
- support --env-file so OA credentials no longer need manual shell sourcing
- resolve asset paths relative to the training directory
- improve human-readable review and execute output with step-by-step progress
- keep the browser open after execute when no save flag is used
- add optional --save flow that clicks 'Opslaan als' and then chooses 'Concept'
- add a concrete user guide for preparing and running training imports
- update handover documentation to reflect the current repo structure and workflow
- align the repo around trainings/<name>/content.md, training.json and assets/
- remove reliance on older pilot/test material in the documented main flow
This commit is contained in:
Nico Martijn Hendriks
2026-05-09 11:29:35 +02:00
parent 8435e62e9a
commit 410f37a008
226 changed files with 1011 additions and 2226 deletions
Download Patch File Download Diff File Expand all files Collapse all files
HANDOVER.md
+118 -195
View File
@@ -103,7 +103,8 @@ Wel:
- intern trainingsmodel
- UI-plan
- zichtbare Playwright runner
- reviewstop vóór save
- review en execute via de editor-UI
- optionele save via `Opslaan als` -> `Concept`
Reden:
- minder risico in productie
@@ -115,8 +116,30 @@ Reden:
### Input / referentie
- [create-md-format.md](/Users/nico/skillstown/create-md-format.md)
- [body.html](/Users/nico/skillstown/body.html)
- [GEBRUIKSHANDLEIDING-IMPORT.md](/Users/nico/skillstown/GEBRUIKSHANDLEIDING-IMPORT.md)
### Gebruikersinvoer volgens huidige werkwijze
De beoogde gebruikersflow is nu:
- per training een eigen map onder `/Users/nico/skillstown/trainings/`
- vaste bestandsnamen binnen die map:
- `content.md`
- `training.json`
- `assets/`
Concreet voorbeeld dat nu is ingericht:
- [trainings/hoofdstuk-04-basisqueries/content.md](/Users/nico/skillstown/trainings/hoofdstuk-04-basisqueries/content.md)
- [trainings/hoofdstuk-04-basisqueries/training.json](/Users/nico/skillstown/trainings/hoofdstuk-04-basisqueries/training.json)
- [trainings/hoofdstuk-04-basisqueries/assets](/Users/nico/skillstown/trainings/hoofdstuk-04-basisqueries/assets)
Belangrijk:
- de runner ondersteunt nu direct `--training-dir <map>`
- daarbij wordt automatisch `content.md` en `training.json` gebruikt
- de URL wordt dus standaard uit `training.json` gelezen
- credentials kunnen via `--env-file .env` worden geladen zonder `source .env`
### Scripts
@@ -130,30 +153,43 @@ Reden:
Zichtbare Playwright runner met:
- reviewmodus
- execute-modus
- optionele `--save` flag
- login
- inlezen van `.env` via `--env-file`
- inlezen van `training.json` via `--training-dir`
- editorverificatie
- pagina-aanmaak
- blokinsertie/invulling
- asset-resolutie relatief aan `content.md`
- menselijk leesbare voortgangsmeldingen
- DOM-snapshot voor detectie van nieuw ingevoegde blokken
- drop-targeting op de onderkant van het laatste bestaande blok
- reviewstop vóór save
### Testdata
- [pilot-mvp.md](/Users/nico/skillstown/pilot-mvp.md)
- [pilot-multi-response.md](/Users/nico/skillstown/pilot-multi-response.md)
- [pilot-image.md](/Users/nico/skillstown/pilot-image.md)
- [pilot-table.md](/Users/nico/skillstown/pilot-table.md)
- [pilot-table-large.md](/Users/nico/skillstown/pilot-table-large.md)
- [pilot-open-question.md](/Users/nico/skillstown/pilot-open-question.md)
- [pilot-chapters.md](/Users/nico/skillstown/pilot-chapters.md)
- [pilot-chapters-large.md](/Users/nico/skillstown/pilot-chapters-large.md)
- [create-md-format.onlineacademy.json](/Users/nico/skillstown/create-md-format.onlineacademy.json)
- [pilot-mvp.onlineacademy.json](/Users/nico/skillstown/pilot-mvp.onlineacademy.json)
- execute zonder save laat het scherm open voor handmatige controle
- save klikt `Opslaan als` en kiest daarna `Concept`
### Config
- [package.json](/Users/nico/skillstown/package.json)
- [\.env](/Users/nico/skillstown/.env)
De runner verwacht credentials via environment variables:
- `OA_EMAIL`
- `OA_PASSWORD`
Praktisch worden die lokaal in `.env` gezet en tijdens een run automatisch ingelezen met:
```bash
node onlineacademy-playwright-runner.mjs \
--training-dir trainings/hoofdstuk-04-basisqueries \
--env-file .env
```
Zonder deze stap stopt de runner met:
```text
Error: Zet OA_EMAIL en OA_PASSWORD in /Users/nico/skillstown/.env of in de omgeving.
```
## Wat werkt al
@@ -162,6 +198,8 @@ Reden:
- Markdown parsing werkt
- dry-run JSON generatie werkt
- plan/validatie-export werkt
- trainingsmap-structuur werkt
- `.env` en `training.json` worden automatisch ingelezen via flags
### Live in de zichtbare browser
@@ -169,6 +207,9 @@ Bewezen:
- login werkt
- editorherkenning werkt
- reviewmodus zonder mutaties werkt
- menselijk leesbare statusuitvoer werkt
- execute zonder `--save` laat het scherm nu open voor handmatige controle
- execute met `--save` bewaart nu via `Opslaan als` -> `Concept`
- nieuwe pagina `Intro` aanmaken werkt
- paginatitel invullen werkt
- drag/drop insertie van blokken werkt aantoonbaar stabieler wanneer op de onderkant van het laatste bestaande blok wordt gedropt
@@ -207,140 +248,24 @@ Bewezen:
- de execute-flow maakt nu altijd een nieuw hoofdstuk aan via `Nieuw hoofdstuk`
- automatisch aangemaakte eerste pagina in nieuwe hoofdstukken hernoemen en hergebruiken
- extra pagina's per hoofdstuk aanmaken wanneer Markdown meer pagina's bevat
- er is niet opgeslagen
- asset-paden in trainingsmappen werken nu correct via relatieve resolutie vanaf `content.md`
- save via `Opslaan als` -> `Concept` werkt nu
## Artifacts / bewijs
Belangrijkste artifacts:
De repo is opgeschoond; oude pilots en artifacts zijn verwijderd.
- [editor-ready.png](/Users/nico/skillstown/artifacts/oa-runner/editor-ready.png)
Editor succesvol geladen.
Huidige relevante artifacts worden per run geschreven naar:
- [page-1-structure.png](/Users/nico/skillstown/artifacts/oa-runner/page-1-structure.png)
Nieuwe pagina `Intro` succesvol aangemaakt.
- `artifacts/<trainingsnaam>/`
- [page-1-block-1-text.png](/Users/nico/skillstown/artifacts/oa-runner/page-1-block-1-text.png)
Tekstblok zichtbaar ingevoegd en gevuld.
Daar vind je typisch:
- [page-1-block-2-heading.png](/Users/nico/skillstown/artifacts/oa-runner/page-1-block-2-heading.png)
Oud artifact uit een eerdere run waarin blokvolgorde/targeting nog niet stabiel was.
- [page-1-block-2-quote.png](/Users/nico/skillstown/artifacts/oa-runner/page-1-block-2-quote.png)
Quoteblok succesvol ingevuld in een latere geharde run.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner/review-stop.png)
Laat de huidige reviewstop zien vóór save, met de blokken in de goede volgorde bovenaan zichtbaar.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner/validation.json)
Pilot na drag/drop-hardening:
- [page-1-block-3-quote.png](/Users/nico/skillstown/artifacts/oa-runner-pilot/page-1-block-3-quote.png)
Laat zien dat `text`, `heading` en `quote` in natuurlijke volgorde onder elkaar staan.
- [page-1-block-4-multiple-choice.png](/Users/nico/skillstown/artifacts/oa-runner-pilot/page-1-block-4-multiple-choice.png)
Laat zien dat daarna ook `multiple-choice` onder het quote-blok is ingevoegd en dat de vraag is ingevuld.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-pilot/review-stop.png)
Bevestigt de pagina-opbouw in volgorde `text` -> `heading` -> `quote` -> `multiple-choice`, zonder save.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-pilot/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-pilot/validation.json)
Pilot voor `multiple-choice` afwerking:
- [page-1-block-4-multiple-choice.png](/Users/nico/skillstown/artifacts/oa-runner-mc/page-1-block-4-multiple-choice.png)
Laat zien dat de meerkeuzevraag nu met exact 2 antwoorden uit Markdown is ingevuld, met het correcte antwoord geselecteerd.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-mc/review-stop.png)
Laat zien dat ook de feedback/toelichting is ingevuld en dat de run weer stopt vóór save.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-mc/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-mc/validation.json)
Pilot voor `multiple-response` afwerking:
- [page-1-block-1-multiple-response.png](/Users/nico/skillstown/artifacts/oa-runner-mr/page-1-block-1-multiple-response.png)
Laat zien dat de multi-antwoordvraag nu exact 3 antwoorden uit Markdown overneemt, met 2 correcte checkboxen geselecteerd.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-mr/review-stop.png)
Laat zien dat ook de toelichting is ingevuld en dat de run weer stopt vóór save.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-mr/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-mr/validation.json)
Pilot voor `image` afwerking:
- [page-1-block-1-image.png](/Users/nico/skillstown/artifacts/oa-runner-image/page-1-block-1-image.png)
Laat zien dat de afbeelding is geüpload en dat `Titel`, `Onderschrift` en `Alternatieve tekst` zijn ingevuld.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-image/review-stop.png)
Laat zien dat de image-run ook weer stopt vóór save.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-image/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-image/validation.json)
Pilot voor `table` verkenning:
- [page-1-block-1-table.png](/Users/nico/skillstown/artifacts/oa-runner-table/page-1-block-1-table.png)
Laat zien dat `Titel`, `Top header`, kolomuitbreiding, rijuitbreiding en de volledige celvulling nu werken voor de tabelpilot.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-table/review-stop.png)
Laat zien dat de tabel-run ook stopt vóór save.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-table/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-table/validation.json)
- [failure-state.png](/Users/nico/skillstown/artifacts/oa-runner-table/failure-state.png)
Artifact uit een tussenrun waarin de plusknoppen voor kolom/rij-uitbreiding nog niet betrouwbaar werden geraakt.
Pilot voor grotere `table` validatie:
- [page-1-block-1-table.png](/Users/nico/skillstown/artifacts/oa-runner-table-large/page-1-block-1-table.png)
Laat zien dat de tabel ook opschaalt naar 4 kolommen en 10 regels totaal, inclusief volledige celvulling uit Markdown.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-table-large/review-stop.png)
Laat zien dat ook de grotere tabel-run stopt vóór save.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-table-large/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-table-large/validation.json)
Pilot voor `open-question` afwerking:
- [page-1-block-1-open-question.png](/Users/nico/skillstown/artifacts/oa-runner-open-question/page-1-block-1-open-question.png)
Laat zien dat de open vraag en de toelichting correct uit Markdown zijn ingevuld.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-open-question/review-stop.png)
Laat zien dat ook de open-vraag-run stopt vóór save.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-open-question/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-open-question/validation.json)
Pilot voor hoofdstukaanmaak:
- [chapter-2-structure.png](/Users/nico/skillstown/artifacts/oa-runner-chapters/chapter-2-structure.png)
Laat zien dat een tweede hoofdstuk wordt toegevoegd en dat de automatisch aangemaakte eerste pagina daarvan wordt hernoemd en gevuld.
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-chapters/review-stop.png)
Laat zien dat de tweekoppige hoofdstukpilot stopt vóór save.
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-chapters/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-chapters/validation.json)
Pilot voor grotere hoofdstukvalidatie:
- [review-stop.png](/Users/nico/skillstown/artifacts/oa-runner-chapters-large/review-stop.png)
Laat zien dat 4 hoofdstukken met wisselende aantallen pagina's goed worden opgebouwd:
- `Hoofdstuk Alfa`: 1 pagina
- `Hoofdstuk Bravo`: 3 pagina's
- `Hoofdstuk Charlie`: 2 pagina's
- `Hoofdstuk Delta`: 4 pagina's
- [chapter-2-structure.png](/Users/nico/skillstown/artifacts/oa-runner-chapters-large/chapter-2-structure.png)
- [chapter-3-structure.png](/Users/nico/skillstown/artifacts/oa-runner-chapters-large/chapter-3-structure.png)
- [chapter-4-structure.png](/Users/nico/skillstown/artifacts/oa-runner-chapters-large/chapter-4-structure.png)
- [plan.json](/Users/nico/skillstown/artifacts/oa-runner-chapters-large/plan.json)
- [validation.json](/Users/nico/skillstown/artifacts/oa-runner-chapters-large/validation.json)
- `plan.json`
- `validation.json`
- `editor-ready.png`
- `review-stop.png` of `after-save.png`
- `failure-state.png` als een run mislukt
## Belangrijkste observatie over drag/drop
@@ -377,13 +302,12 @@ Pragmatische koerswijziging:
## Huidige tekortkomingen
Nog niet robuust:
- de nieuwe drop-strategie en execute-flow zijn live gevalideerd voor pilots met `text`, `heading`, `quote`, `multiple-choice`, `multiple-response`, `image`, `table`, `open-question` en hoofdstukken/pagina's
- de execute-flow is nu gevalideerd voor de gebruikte bloksets in `hoofdstuk-04-basisqueries`
- scoped targeting per bloktype blijft verder hardening nodig hebben voor bredere bloksets en afwijkende editorstates
- de nieuwe "altijd nieuw hoofdstuk"-strategie moet nog live opnieuw gevalideerd worden
Nog niet opgepakt:
- matching-pairs UI-flow
- save-flow
- functionele bevestiging van succesvol opslaan nog explicieter maken in de output
- opschonen van oude, ongebruikte delete-helpers in de runner
## Veiligheidsafspraken
@@ -392,13 +316,13 @@ Tot nu toe gehanteerd:
- headed browser
- slow motion
- reviewmodus zonder mutaties
- execute stopt vóór save
- execute zonder `--save` stopt vóór save en laat het scherm open
- geen directe backend writes
- artifacts per stap
- execute-flow gebruikt nu geen delete-acties meer
Bewust nog niet gedaan:
- automatisch opslaan
- extra verificatie van succesvol opslaan na klik op `Opslaan als` -> `Concept`
- API writes
- bulkimport in productie
@@ -410,88 +334,87 @@ Aanbevolen aanvullende veiligheidsafspraak:
In `/Users/nico/skillstown`:
Benodigd op macOS:
- Terminal
- Node.js
- npm
Installeren:
```bash
npm install
```
Credentials lokaal in `.env` zetten:
```dotenv
OA_EMAIL=jouw.email@voorbeeld.nl
OA_PASSWORD=jouwWachtwoordHier
```
Dry-run parser:
```bash
node markdown-to-onlineacademy-json.mjs pilot-mvp.md
```
Zichtbare review-run zonder mutaties:
```bash
# verwacht een lokaal `.env` bestand met ten minste:
# OA_EMAIL='...'
# OA_PASSWORD='...'
```
Credentials laden uit `.env`:
```bash
set -a
source .env
set +a
node markdown-to-onlineacademy-json.mjs trainings/hoofdstuk-04-basisqueries/content.md
```
Zichtbare review-run zonder mutaties:
```bash
node onlineacademy-playwright-runner.mjs \
--markdown pilot-mvp.md \
--url 'https://create.onlineacademy.nl/8602e048-d7ee-4764-aafb-43412d0f65f3/edit?idsVersion=6'
--training-dir trainings/hoofdstuk-04-basisqueries \
--env-file .env
```
Zichtbare review-run op een trainingsmap volgens de nieuwe gebruikersstructuur:
```bash
node onlineacademy-playwright-runner.mjs \
--training-dir trainings/hoofdstuk-04-basisqueries \
--env-file .env
```
Zichtbare execute-run tot reviewstop, zonder save:
```bash
set -a; source .env; set +a
node onlineacademy-playwright-runner.mjs \
--markdown pilot-mvp.md \
--url 'https://create.onlineacademy.nl/8602e048-d7ee-4764-aafb-43412d0f65f3/edit?idsVersion=6' \
--training-dir trainings/hoofdstuk-04-basisqueries \
--env-file .env \
--execute \
--output-dir artifacts/oa-runner-pilot
--output-dir artifacts/hoofdstuk-04-basisqueries
```
Zichtbare execute-run zonder save:
```bash
set -a
source .env
set +a
node onlineacademy-playwright-runner.mjs \
--markdown pilot-mvp.md \
--url 'https://create.onlineacademy.nl/8602e048-d7ee-4764-aafb-43412d0f65f3/edit?idsVersion=6' \
--training-dir trainings/hoofdstuk-04-basisqueries \
--env-file .env \
--execute
```
Zichtbare execute-run met save-klik:
```bash
node onlineacademy-playwright-runner.mjs \
--training-dir trainings/hoofdstuk-04-basisqueries \
--env-file .env \
--execute \
--save
```
## Directe volgende stap
Niet meer werken met "laatste blok = nieuw blok".
Pragmatische vervolgstappen:
Hardeningvoorstel:
1. `multiple-choice` volledig afmaken:
Status: afgerond voor de pilot-run.
2. `multiple-response`
Status: afgerond voor de pilot-run.
3. `image`
Status: afgerond voor de pilot-run.
4. `table`
Status: afgerond voor de pilot-run.
5. `open-question`
Status: afgerond voor de pilot-run.
6. hoofdstukaanmaak
Status: afgerond voor de pilot-run, maar execute-flow is inmiddels vereenvoudigd naar "altijd nieuw hoofdstuk" en moet daarop opnieuw live gevalideerd worden.
7. verdere hardening voor andere bloktypes en editorvarianten
8. save-flow
1. save-bevestiging explicieter maken in de output
2. package scripts laten aansluiten op de huidige `--training-dir` flow
3. ondersteuning uitbreiden voor extra bloktypes zoals `matching-pairs`
4. oude, ongebruikte helpers verder opschonen
## Eindconclusie
De drag/drop Playwright-route is technisch haalbaar en veiliger passend bij deze productiecontext dan direct backend writes.
De basis is gelegd en live gevalideerd. De veiligste huidige koers is om in execute-runs alleen nieuwe hoofdstukken op te bouwen en geen bestaande content te verwijderen. Verdere hardening blijft nodig op blokpositie, veldtargeting en uiteindelijk de save-flow voordat dit betrouwbaar genoeg is voor herhaalbaar gebruik.
De basis is gelegd en live gevalideerd. De huidige flow ondersteunt nu review, execute zonder save en execute met save via `Opslaan als` -> `Concept`, vanuit een vaste trainingsmap-structuur met `content.md`, `training.json` en `assets/`.