racket-wiki/HANDOFF.md

Overdracht racket-wiki

Bijgewerkt: 25 augustus 2026

Project in het kort

racket-wiki is een kleine, zelfgehoste wiki met:

• een Racket-backend op web-server-lib;
• PostgreSQL als opslag voor gebruikers, sessies, pagina's, versies, bijlagen en concept maps (CMaps);
• een frontend in gewone HTML, CSS en JavaScript, zonder npm- of bundlerstap;
• EasyMDE/Marked voor Markdown, DOMPurify voor sanitizing, highlight.js voor code en diff2html voor versieverschillen;
• lokale, tijdens setup gedownloade frontendbibliotheken, zodat normaal gebruik geen CDN nodig heeft.

De ontwikkelversie is 0.2.122 (info.rkt). De huidige PostgreSQL-schemaversie is 22 (private/migrations.rkt).

Belangrijk: huidige werkboom

De branch is main en volgt origin/main. De laatste commit is:

20c1584 Lots of changes to the cmap stuff

Er staan belangrijke, nog niet gecommitte wijzigingen voor versie 0.2.100 in de werkboom en die moeten worden behouden. Bij de laatste inventarisatie waren onder meer gewijzigd of toegevoegd:

HANDOFF.md
README.md
architecture/pages/data-en-versies.md
architecture/pages/gedrag.md
architecture/pages/testbaarheid.md
info.rkt
private/cmap-storage.rkt
private/migrations.rkt
private/people.rkt
scrbl/racket-wiki.scrbl
server.rkt
static/cmap/cmap-racket-wiki.js
static/cmap/cmap.css
static/index.html
static/js/wiki.js
static/cmap/model/markdown-exporter.js
test/cmap-export.test.js
translate.rkt

Voer dus geen reset, checkout of brede formattering uit voordat deze wijzigingen zijn beoordeeld en veilig gecommitte. wiki-data/ en compiled/ zijn lokale/gegenereerde directories en staan in .gitignore.

Snel starten

Benodigd:

• Racket met de dependencies uit info.rkt (crypto-lib, db-lib, net-lib, net-cookies-lib, openssl-lib en web-server-lib);
• PostgreSQL; de database moet vooraf bestaan en de opgegeven rol moet tabellen en indexen mogen maken;
• internettoegang tijdens de eerste setup om de vastgepinde browserbibliotheken te downloaden.

In deze ontwikkelomgeving is Racket 9.1 gebruikt. Start vanuit de projectroot:

racket main.rkt --data ./wiki-data --port 8080

Open daarna http://127.0.0.1:8080/. Een incomplete installatie gaat automatisch naar /setup. Daar worden de databaseverbinding, migraties, frontendbestanden en eerste administrator geregeld. Luisteren op alle interfaces kan met:

racket main.rkt --data ./wiki-data --listen '*' --port 8080

Gebruik achter HTTPS altijd --secure-cookie. Andere relevante opties zijn --title, --language en|nl en de hersteloptie --create-admin USER PASSWORD.

De database-instellingen, inclusief eventueel het wachtwoord, staan in wiki-data/database.rktd. Dit bestand hoort niet in Git of in logs. De applicatie probeert het bestand met mode 0600 aan te maken.

Als alleen de browserdependencies hersteld moeten worden:

racket setup-vendor.rkt --data ./wiki-data

Codekaart

Pad	Verantwoordelijkheid
main.rkt	CLI en programmatische entrypoints start en start-wiki
server.rkt	HTTP-routering, setup/loginpagina's en alle JSON/API-handlers
private/config.rkt	runtimeconfiguratie en paden onder de datadirectory
private/setup.rkt	eerste websetup en herstelcontrole
private/database.rkt	PostgreSQL-configuratie, verbindingen en migratiestart
private/migrations.rkt	geordende, transactionele databaseschemamigraties
private/storage.rkt	pagina's, historie, zoeken, todo's, bookmarks, aliassen en uploads
private/cmap-storage.rkt	opslag, historie, zoeken en gebruikstellingen voor CMaps
private/auth.rkt	wachtwoorden, sessies, CSRF, rollen en password-reset-tokens
private/mail.rkt	SMTP-instellingen en resetmails
translate.rkt	Engelse/Nederlandse server- en frontendvertalingen
static/index.html	skelet van de ingelogde single-page-interface
static/js/wiki.js	applicatiestatus, API-calls, pagina-editor en CMap-hostintegratie
static/cmap/	lokaal onderhouden CMap-renderer, editorlaag en styling
architecture/	importeerbare Nederlandse architectuurpagina's en twee CMaps
scrbl/racket-wiki.scrbl	package/API-documentatie in Scribble

De browserfrontend heeft bewust geen buildstap. Wijzig bronbestanden rechtstreeks en test ze in de browser. Externe browserlibraries staan runtime onder wiki-data/static/vendor/; wijzig die niet als applicatiebron.

Belangrijke invarianten

• Er is geen anonieme wiki-toegang. reader leest, editor schrijft en admin beheert gebruikers en instellingen.
• Schrijvende API-calls vereisen naast een sessie ook de CSRF-token.
• Pagina's hebben een aparte namespace en stabiele slug; de combinatie is uniek. Een titelwijziging verandert de slug niet.
• Elke paginasave wijzigt pages en schrijft in dezelfde transactie een onveranderlijke page_versions-rij.
• Pagina-updates en CMap-updates gebruiken optimistic locking en horen bij een verouderde basisversie HTTP 409 te geven.
• Pagina's en CMaps worden gearchiveerd (soft delete); histories blijven behouden. Een volledige CMap vereist titel- en versiebevestiging en kan onder Admin → Gearchiveerde CMaps worden hersteld.
• Bijlagen staan als BYTEA in PostgreSQL. Alleen vertrouwde rasterformaten worden inline geserveerd; andere bestanden worden downloads.
• Markdown gaat vóór invoegen in de DOM door DOMPurify.
• Verhoog current-schema-version alleen samen met een nieuwe, opeenvolgende migratie. Een database met een nieuwer schema dan de code moet geweigerd blijven.

Lopend werk: 0.2.100

De laatste commit bevat de CMap-uitbreidingen van 0.2.95–0.2.99. De niet-gecommitte 0.2.100-reeks voegt hieraan toe:

• Markdown-export met instelbare diepte voor gekoppelde CMaps, optionele wikipagina's en CMap-tags, samenvattingen en uitleg;
• wiki-brede persoonstags met een activeerbaar/deactiveerbaar personenregister (schema 13).

Migratie 12 schoont oude CMap-autosavehistorie op en beperkt herkenbare handmatige saves tot vijf. Migratie 13 maakt het personenregister en neemt bestaande persoonstags uit CMaps over. Migraties 14–17 vormden de tussenstappen naar gedeelde conceptidentiteit. Migratie 18 normaliseert de actuele CMap-documenten definitief op getrimde, hoofdletterongevoelige conceptnaam: alle ids worden fysiek herschreven, dubbele definities worden verwijderd, de repository wordt opnieuw opgebouwd en de tijdelijke aliastabel wordt verwijderd. Migratie 19 verwijdert daarna alle gedupliceerde conceptinhoud uit plaatsingsitems. Migratie 20 reduceert ook concepts[] in actuele CMap-documenten tot {id}-verwijzingen; alleen concept_definitions bewaart nog inhoud. migrate-cmap-subpages.rkt is een aparte contentmigratie voor oudere inline sub-CMaps; dit is geen databaseschemamigratie.

Gebruik die contentmigratie altijd eerst als dry-run:

racket migrate-cmap-subpages.rkt --data ./wiki-data
racket migrate-cmap-subpages.rkt --data ./wiki-data --apply

Zonder --apply wordt niets gewijzigd. Met --apply gebeurt de omzetting in één PostgreSQL-transactie. Maak desondanks eerst een databasebackup en beoordeel de gemelde slugs.

Testen en huidige verificatiestatus

De automatische testdekking is beperkt. Op 22 augustus 2026 zijn de volgende controles succesvol uitgevoerd:

raco test private/people.rkt architecture/import.rkt
# 13 tests passed

raco make main.rkt server.rkt setup-vendor.rkt \
  migrate-cmap-subpages.rkt architecture/import.rkt

node --check static/js/wiki.js
node --check static/cmap/model/markdown-exporter.js
node --check static/js/combobox.js
node --check static/cmap/cmap.js
node --check static/cmap/cmap-racket-wiki.js

node --test test/cmap-export.test.js

Er is nog geen geautomatiseerde backendintegratietest tegen PostgreSQL en geen browsertestsuite. De huidige 0.2.100-werkboom is dus wel compileerbaar en syntactisch geldig, maar nog niet in deze overdracht end-to-end gevalideerd.

Voer vóór commit/release minimaal deze smoke tests uit op een kopie of aparte testdatabase:

1. Verse /setup, login/logout en de drie rollen.
2. Pagina maken, wijzigen, hernoemen, history bekijken, conflict (409), namespace-link en upload.
3. CMap maken, autosave, expliciet opslaan, snapshot maken/verwijderen en historylimiet controleren.
4. Een concept meerdere keren en in meerdere CMaps plaatsen; controleer tellingen en het paneel op de gekoppelde wikipagina.
5. Een inline sub-CMap met de dry-run en daarna --apply migreren; controleer parent, derived view en oude histories.
6. Start-CMap, verborgen concepten, linked copy/paste, undo/redo en beschadigde relatie zonder endpoint controleren.
7. Zoekresultaten, bookmarks, todo's, aliassen en adminoverzichten nalopen.
8. Indien mail relevant is: SMTP-test en de volledige vergeten-wachtwoordflow.

Architectuurdocumentatie importeren

Valideren en wijzigingen vooraf bekijken:

racket architecture/import.rkt --data ./wiki-data --dry-run

Importeren:

racket architecture/import.rkt --data ./wiki-data --author "Naam ontwikkelaar"

De import is herhaalbaar en gebruikt source hashes. Lokaal aangepaste geïmporteerde pagina's/CMaps worden standaard overgeslagen. Gebruik --overwrite-modified alleen na controle van hun histories.

Mailconfiguratie

Password-resetmail kan via de admininterface/database of via omgevingsvariabelen worden ingesteld. Ondersteund zijn:

RACKET_WIKI_PUBLIC_URL
RACKET_WIKI_SMTP_HOST
RACKET_WIKI_SMTP_PORT
RACKET_WIKI_SMTP_FROM
RACKET_WIKI_SMTP_USER
RACKET_WIKI_SMTP_PASSWORD
RACKET_WIKI_SMTP_TLS
RACKET_WIKI_SMTP_ACCEPT_UNTRUSTED_CERTIFICATES
RACKET_WIKI_RESET_LIMIT

Accepteer onbetrouwbare certificaten alleen bewust voor een vertrouwde lokale SMTP-server. Zet secrets nooit in documentatie, commits of testoutput.

Aanbevolen eerstvolgende stap

Maak eerst een databasebackup en test de niet-gecommitte 0.2.100-reeks met bovenstaande smoke tests. Beoordeel daarna de diff als één samenhangende CMap-wijziging en commit pas wanneer migratie 13, Markdown-export en personenbeheer op representatieve data zijn geverifieerd.

Voor functionele details en releasehistorie is README.md de uitgebreidste bron. De bestanden onder architecture/pages/ beschrijven ontwerpbeslissingen en kwaliteitsafspraken; architecture/pages/code-regels.md is de beste start voor projectconventies.