From 3ddac4fa8f97968cf8a70eae82208c1b52dd8e4d Mon Sep 17 00:00:00 2001 From: Glenn Goossens <48956933+glgoose@users.noreply.github.com> Date: Tue, 1 Sep 2026 16:47:35 +0200 Subject: [PATCH] README: verplaats dev-stub en naamgeving naar AGENTS.md README is voor gebruikers; dev-workflow instructies horen daar niet in. CLAUDE.md verwijst met @AGENTS.md naar het vendor-agnostische bestand. --- AGENTS.md | 67 +++++++++++++++++++++ CLAUDE.md | 1 + README.md | 64 -------------------- scripts/bipp-budgetcode/README.md | 2 +- scripts/iexpense-search/README.md | 2 +- scripts/peoplesoft-excel-download/README.md | 2 +- scripts/select-search/README.md | 2 +- 7 files changed, 72 insertions(+), 68 deletions(-) create mode 100644 AGENTS.md create mode 100644 CLAUDE.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..f3bd653 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,67 @@ +# ua-userscripts + +Dev-conventies voor dit script-repo: dev-stub workflow en naamgeving. + +## Dev-stub vs. gebruik + +De file in `scripts/` is de bron van waarheid voor de code. Wat in Tampermonkey staat is dus +óf een loader die naar die file wijst, óf een kopie die van de raw-URL komt. Nooit een met de +hand geplakte kopie, want dan zijn er twee waarheden die stil uit elkaar lopen. + +| spoor | wat er in Tampermonkey staat | grootte | `@version` | +| ----------- | --------------------------------------- | ----------------- | ----------- | +| **dev** | stub met `@require file:///...` | een paar honderd byte | `1.0.0-dev` | +| **gebruik** | volledige kopie via de raw-URL | de echte grootte | `1.0.0` | + +De grootte in het dashboard zegt dus in welk spoor een rij zit. + +### Een dev-stub maken + +```sh +bin/dev-stub bipp-budgetcode +``` + +De stub gaat meteen naar het klembord. In Tampermonkey neem je het potlood van de bestaande +rij, dan Cmd+A, Cmd+V, Cmd+S. Via de `+`-tab krijg je een tweede rij in plaats van een +bijgewerkte, want Tampermonkey herkent een script aan `@namespace` plus `@name`. + +`bin/dev-stub --list` toont de scriptmappen, `--no-copy` slaat het klembord over. + +Drie dingen die aan die stub vasthangen: + +- **De metadata komt uit de stub, niet uit de required file.** `@match`, `@grant` en `@run-at` + moeten er dus in staan; het `==UserScript==`-blok van de file zelf wordt genegeerd. `dev-stub` + neemt die velden over uit het echte script, zodat de twee niet uit elkaar lopen. +- **`@updateURL` staat op `none`.** Die velden weglaten volstaat niet: Tampermonkey onthoudt de + download-URL van de oorspronkelijke installatie apart van het meta-blok, dus een rij die ooit + van de raw-URL kwam biedt daarna alsnog een update aan die je stub overschrijft. In + `determineMetaURL` gaat `@updateURL` vóór die onthouden URL, en `none` breekt de check af. + `@downloadURL` mag daardoor gewoon blijven staan: die wordt nooit meer bereikt, en levert wel + het GitHub-icoon op in de overzichtslijst, want de herkomst wordt uit die URL afgeleid. + `dev-stub` zet allebei zelf in de stub. Controleren doe je niet in Settings: het veld + **Update URL** daar is `downloadURL` onder een misleidend label (`file_url = downloadURL || + fileURL`), en `@updateURL` heeft in dat scherm geen veld. Het toont dus de raw-URL, ook als + `none` netjes is overgenomen. Controleer in plaats daarvan het gedrag: klik in de + werkbalk-popup op **Check for userscript updates** en er hoort geen enkel dialoogvenster te + komen. +- **De stub moet mee met elke `@version`-bump.** De code komt via `@require` uit de repo, dus + functioneel merk je er niets van, maar de Version-kolom wijst anders een oude versie aan en + die kolom is nu net waarmee je dev van gebruik onderscheidt. Draai `bin/dev-stub` opnieuw en + plak. + +Lokale bestanden lezen mag Tampermonkey alleen als **Allow access to file URLs** aanstaat, bij +`chrome://extensions` onder Details. + +### Naamgeving + +`: `, met de toepassing zoals je ze zelf noemt (`BIPP`, `iExpense`, +`PeopleSoft`), daarna de dubbele punt en een kleine-letter naamwoordgroep zonder punt. Het +dashboard sorteert op naam, dus zo staan de scripts van dezelfde toepassing bij elkaar. + +- Geen `[DEV]` in de naam. Dat groepeert op ontwikkelstatus in plaats van op toepassing, en de + Version-kolom zegt met `-dev` al hetzelfde. +- Geen technische slug in de naam. Die staat in het repo-pad en in `@homepageURL`. +- Draait een script op meerdere sites, dan `Algemeen: ...`. +- Mapnaam en bestandsnaam in kebab-case, zelfde volgorde: `-`. + +Hoog `@version` op bij elke wijziging, anders krijgt niemand de update binnen. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..43c994c --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1 @@ +@AGENTS.md diff --git a/README.md b/README.md index c38c46a..6175085 100644 --- a/README.md +++ b/README.md @@ -34,70 +34,6 @@ evenmin: die doe je per toestel opnieuw. `chrome://extensions` of `edge://extensions` en zet **Developer mode** (Ontwikkelaarsmodus) aan. -## Ontwikkelen - -De file in `scripts/` is de bron van waarheid voor de code. Wat in Tampermonkey staat is dus -óf een loader die naar die file wijst, óf een kopie die van de raw-URL komt. Nooit een met de -hand geplakte kopie, want dan zijn er twee waarheden die stil uit elkaar lopen. - -| spoor | wat er in Tampermonkey staat | grootte | `@version` | -| ----------- | --------------------------------------- | ----------------- | ----------- | -| **dev** | stub met `@require file:///...` | een paar honderd byte | `1.0.0-dev` | -| **gebruik** | volledige kopie via de raw-URL | de echte grootte | `1.0.0` | - -De grootte in het dashboard zegt dus in welk spoor een rij zit. - -### Een dev-stub maken - -```sh -bin/dev-stub bipp-budgetcode -``` - -De stub gaat meteen naar het klembord. In Tampermonkey neem je het potlood van de bestaande -rij, dan Cmd+A, Cmd+V, Cmd+S. Via de `+`-tab krijg je een tweede rij in plaats van een -bijgewerkte, want Tampermonkey herkent een script aan `@namespace` plus `@name`. - -`bin/dev-stub --list` toont de scriptmappen, `--no-copy` slaat het klembord over. - -Drie dingen die aan die stub vasthangen: - -- **De metadata komt uit de stub, niet uit de required file.** `@match`, `@grant` en `@run-at` - moeten er dus in staan; het `==UserScript==`-blok van de file zelf wordt genegeerd. `dev-stub` - neemt die velden over uit het echte script, zodat de twee niet uit elkaar lopen. -- **`@updateURL` staat op `none`.** Die velden weglaten volstaat niet: Tampermonkey onthoudt de - download-URL van de oorspronkelijke installatie apart van het meta-blok, dus een rij die ooit - van de raw-URL kwam biedt daarna alsnog een update aan die je stub overschrijft. In - `determineMetaURL` gaat `@updateURL` vóór die onthouden URL, en `none` breekt de check af. - `@downloadURL` mag daardoor gewoon blijven staan: die wordt nooit meer bereikt, en levert wel - het GitHub-icoon op in de overzichtslijst, want de herkomst wordt uit die URL afgeleid. - `dev-stub` zet allebei zelf in de stub. Controleren doe je niet in Settings: het veld - **Update URL** daar is `downloadURL` onder een misleidend label (`file_url = downloadURL || - fileURL`), en `@updateURL` heeft in dat scherm geen veld. Het toont dus de raw-URL, ook als - `none` netjes is overgenomen. Controleer in plaats daarvan het gedrag: klik in de - werkbalk-popup op **Check for userscript updates** en er hoort geen enkel dialoogvenster te - komen. -- **De stub moet mee met elke `@version`-bump.** De code komt via `@require` uit de repo, dus - functioneel merk je er niets van, maar de Version-kolom wijst anders een oude versie aan en - die kolom is nu net waarmee je dev van gebruik onderscheidt. Draai `bin/dev-stub` opnieuw en - plak. - -Lokale bestanden lezen mag Tampermonkey alleen als **Allow access to file URLs** aanstaat, bij -`chrome://extensions` onder Details. - -### Naamgeving - -`: `, met de toepassing zoals je ze zelf noemt (`BIPP`, `iExpense`, -`PeopleSoft`), daarna de dubbele punt en een kleine-letter naamwoordgroep zonder punt. Het -dashboard sorteert op naam, dus zo staan de scripts van dezelfde toepassing bij elkaar. - -- Geen `[DEV]` in de naam. Dat groepeert op ontwikkelstatus in plaats van op toepassing, en de - Version-kolom zegt met `-dev` al hetzelfde. -- Geen technische slug in de naam. Die staat in het repo-pad en in `@homepageURL`. -- Draait een script op meerdere sites, dan `Algemeen: ...`. -- Mapnaam en bestandsnaam in kebab-case, zelfde volgorde: `-`. - -Hoog `@version` op bij elke wijziging, anders krijgt niemand de update binnen. - ## Licentie [GPL-3.0-or-later](LICENSE). Gebruiken en aanpassen mag vrij. Verspreid je een diff --git a/scripts/bipp-budgetcode/README.md b/scripts/bipp-budgetcode/README.md index c28f6d8..4506735 100644 --- a/scripts/bipp-budgetcode/README.md +++ b/scripts/bipp-budgetcode/README.md @@ -77,7 +77,7 @@ Eén bestand, geen build, geen dependencies. Hoog `@version` op bij elke wijzigi niemand de update binnen. Tijdens het ontwikkelen laad je het script via een dev-stub in plaats van een geplakte kopie, -zie [Ontwikkelen](../../README.md#ontwikkelen). +zie [Ontwikkelen](../../AGENTS.md#dev-stub-vs-gebruik). ```sh node --check bipp-budgetcode.user.js diff --git a/scripts/iexpense-search/README.md b/scripts/iexpense-search/README.md index 1da89d9..8f52996 100644 --- a/scripts/iexpense-search/README.md +++ b/scripts/iexpense-search/README.md @@ -37,7 +37,7 @@ Eén bestand, geen build, geen dependencies. Hoog `@version` op bij elke wijzigi niemand de update binnen. Tijdens het ontwikkelen laad je het script via een dev-stub in plaats van een geplakte kopie, -zie [Ontwikkelen](../../README.md#ontwikkelen). +zie [Ontwikkelen](../../AGENTS.md#dev-stub-vs-gebruik). ```sh node --check iexpense-search.user.js diff --git a/scripts/peoplesoft-excel-download/README.md b/scripts/peoplesoft-excel-download/README.md index 3d5ba36..2258c1a 100644 --- a/scripts/peoplesoft-excel-download/README.md +++ b/scripts/peoplesoft-excel-download/README.md @@ -52,7 +52,7 @@ Deze aanpak omzeilt de server volledig: wat je op je scherm ziet is wat in het b Eén bestand, geen build. De enige dependency komt via `@require` binnen. Tijdens het ontwikkelen laad je het script via een dev-stub in plaats van een geplakte kopie, -zie [Ontwikkelen](../../README.md#ontwikkelen). +zie [Ontwikkelen](../../AGENTS.md#dev-stub-vs-gebruik). ```sh node --check peoplesoft-excel-download.user.js diff --git a/scripts/select-search/README.md b/scripts/select-search/README.md index 3f8de39..f1f99a1 100644 --- a/scripts/select-search/README.md +++ b/scripts/select-search/README.md @@ -112,7 +112,7 @@ Hoog bij elke wijziging `@version` op in `src/userscript-header.txt`, anders kri update binnen. Tijdens het ontwikkelen laad je het script via een dev-stub in plaats van een geplakte kopie, -zie [Ontwikkelen](../../README.md#ontwikkelen). Draai eerst `./build.sh`, want de stub wijst +zie [Ontwikkelen](../../AGENTS.md#dev-stub-vs-gebruik). Draai eerst `./build.sh`, want de stub wijst naar `select-search.user.js`. ## Licentie