Conventies & harde regels

Drie dingen in deze repo zien er behulpzaam uit om "op te lossen" en zijn dat niet. Ze staan hier met de reden erbij, zodat je ze niet per ongeluk terugdraait.

Geen npm-workspaces

Harde regel

Voeg nooit een workspaces-veld toe aan een package.json op repo-niveau, en vervang nooit een registry-dependency door file:, link: of een symlink.

foundation is per 2026-08-17 bewust uit workspaces gehaald: 35 symlinks vervangen door echte installaties uit een npm-registry.

Kort: een symlink test de bron, een consument krijgt de tarball, en het verschil daartussen heeft hier maandenlang echte fouten verborgen gehouden. Het volledige argument staat in foundation/REGISTRY-ONLY.md en samengevat op Registry-only.

De poort bin/foundation no-symlinks — onderdeel van npm run verify — faalt hierop. Zie je hem rood, dan is dat het signaal, niet iets om te onderdrukken.

Uitzondering: solution-explorer/package.json heeft interne workspaces (solutions/*). Die zijn lokaal en vallen buiten deze regel.

Repo-topologie ≠ dependency-topologie

Dat dit één git-repo is, staat hier los van. Eén history en één plek om een wijziging over meerdere deelprojecten te doen — dat is de git-keuze. De npm-keuze is onafhankelijk.

De ontwikkellus is publicatiegebonden

Een wijziging in een kit is pas zichtbaar bij zijn afnemer na bump → publish → install. Dat is inherent aan het model, geen defect.

bin/local-registry up      # Verdaccio op :4873, vereist Docker
bin/foundation publish     # topologisch, idempotent
bin/foundation install
npm run verify
bin/local-registry down

Sla die stappen niet over en bouw er geen omweg omheen. → De ontwikkellus

Publicatie-zichtbaarheid

Twee regimes wonen naast elkaar:

Scope	Zichtbaarheid
@seifer-webapp-factory/* (34 packages)	restricted
@for-the-people-initiative/wireframe-kit	publiek

Onomkeerbaar

Zet nooit ongevraagd publishConfig.access om en publiceer nooit uit eigen beweging naar npmjs. Een package dat één keer publiek is geweest, kan niet met terugwerkende kracht privé worden voor wie het al gespiegeld heeft.

npm-zichtbaarheid geldt bovendien per package, niet per versie: een al-gepubliceerd package privé zetten breekt de schone npm ci van elke consument, ook als die op een oude versie gepind staat.

Grenzen tussen de stages

Elke stage leest de output van de vorige als read-only en schrijft alleen in zijn eigen laag. Geen enkele stage grijpt terug in de laag van een ander.

Concreet: de scaffolder verzint geen deploy-artefacten, en deployment schrijft geen app-code of productdefinitie. → Verantwoordelijkheden

.gitignore

Elk deelproject heeft zijn eigen .gitignore en die is leidend. De root-.gitignore is een vangnet.

De root-.gitignore bevat bewust geen dist/

Dat zou de heruitzonderingen !dist/test/ en !dist/health/ in design-system/ onbereikbaar maken.

Lockfiles in foundation/ en showcase/

Beide negeren package-lock.json, met de reden uitgeschreven in hun eigen .gitignore: Verdaccio herschrijft elke resolved-URL naar localhost:4873. Een gecommit lockfile zou dus naar een registry wijzen die op een andere machine niet bestaat.

Herstel dat niet zonder eerst US-058 op te lossen.

Servers opruimen

Start je een server om iets te controleren, stop hem daarna weer. Een blijvend draaiende Verdaccio is een val: je volgende "schone" install trekt uit een stale cache en lijkt te werken.