Publication npm sécurisée

La publication de @vevedh/qform-builder-layer s’effectue toujours à partir du tarball vérifié créé dans .artifacts/. Le script refuse une publication directe non validée.

Prérequis

• Node.js >= 22.14.0 ;
• Bun >= 1.3.0 ;
• accès au scope npm @vevedh ;
• arbre Git propre pour une publication réelle ;
• bun.lock régénéré et validé ;
• baselines Playwright et captures documentaires finalisées.

La revue manuelle d’accessibilité reste obligatoire uniquement pour la promotion vers 1.0.0-rc.1; elle ne bloque pas la publication npm de la version source 0.1.33.

Ne placez aucun token dans .npmrc, .env ou un fichier versionné. Utilisez npm login, une variable d’environnement fournie par le gestionnaire de secrets de la CI, ou une publication de confiance.

1. Régénérer le lockfile

bun install
bun run lockfile:check

La commande de publication s’arrête si le lockfile ne couvre pas exactement les dépendances de package.json.

2. Vérifier la référence M0

bun run m0:check
bun run security:workspace:check

Ces contrôles vérifient notamment :

• les métadonnées npm ;
• le README public ;
• les scripts de publication ;
• les exclusions Git et npm ;
• l’absence de secret dans le .npmrc commité.

3. Exécuter le préflight

bun run npm:publish:check

Cette commande lance les contrôles de qualité, crée le tarball npm et vérifie son manifeste ainsi que son SHA-256.

4. Simuler la publication

bun run npm:publish:dry-run

Pour la série 0.x, le tag par défaut est next. Un tag explicite peut être fourni :

bun run npm:publish:dry-run -- --tag latest

5. Publier

Poste de référence Windows 11

Le poste mainteneur de référence utilise Windows 11, Visual Studio Code et PowerShell 7, avec Docker Desktop installé. La publication npm est exécutée sur l’hôte Windows ; Docker Desktop n’est pas requis pour cette opération.

Après application d’une archive de patch, inspectez et commitez les fichiers source avant de lancer la publication réelle :

git status --short
git diff --check
git add .
git commit -m "chore(release): prepare @vevedh/qform-builder-layer@0.1.33"
git status --short

La dernière commande ne doit rien afficher. Le wrapper effectue désormais cette vérification avant les builds et tests longs et fournit la même procédure lorsqu’il détecte un arbre sale. Ne contournez pas le garde-fou et n’utilisez pas git reset --hard ou git clean -fd pour supprimer des changements non relus.

La publication exige une confirmation contenant exactement le nom et la version du package.

Sous Bash ou Zsh :

export NPM_PUBLISH_CONFIRM="@vevedh/qform-builder-layer@0.1.33"
bun run npm:publish

Sous PowerShell :

$env:NPM_PUBLISH_CONFIRM = '@vevedh/qform-builder-layer@0.1.33'
bun run npm:publish

Le script :

1. exige immédiatement un arbre Git propre pour une publication réelle ;
2. vérifie les exclusions confidentielles ;
3. rejoue release:publish:check, la gate automatisée de publication ;
4. vérifie l’identité et le SHA-256 du tarball ;
5. contrôle que la version n’existe pas déjà ;
6. publie avec --access public et le dist-tag choisi.

release:candidate:check reste une gate distincte : elle étend release:publish:check, génère le registre de preuves puis exige la revue humaine avant la promotion vers 1.0.0-rc.1. Ne renseignez jamais artificiellement release/manual-accessibility-review.json pour publier une version 0.x.

Résolution de Bun sous Windows

Le wrapper réutilise le chemin Bun fourni par npm_execpath lorsqu’il est lancé avec bun run. Un chemin peut aussi être imposé avec QFORM_BUN_EXECUTABLE. Si l’exécutable ne peut pas être lancé, la commande affiche maintenant l’erreur système au lieu de quitter sans diagnostic.

Résolution de npm sous Windows

Le wrapper ne lance jamais npm.cmd directement avec spawnSync, car Node.js 22 avec NVM for Windows peut retourner EINVAL sur ce wrapper batch. Il résout en priorité le CLI JavaScript npm et l’exécute avec node.exe :

1. QFORM_NPM_CLI_JS lorsqu’il est défini ;
2. npm_execpath uniquement lorsqu’il se termine par npm-cli.js ;
3. node_modules/npm/bin/npm-cli.js à côté de process.execPath.

Le même adaptateur est utilisé pour npm pack, npm whoami, npm view et npm publish. Validez-le indépendamment avec :

bun run npm:command:check
npm whoami

Pour une installation npm atypique :

$env:QFORM_NPM_CLI_JS = "C:\chemin\vers\node_modules\npm\bin\npm-cli.js"
bun run npm:command:check

Ne pointez jamais cette variable vers npm.cmd. Une erreur npm view réseau, TLS, proxy ou authentification bloque la publication ; seule une réponse explicite E404 signifie que la version n’existe pas encore.

Fichiers locaux confidentiels

Le .gitignore couvre les fichiers d’environnement, clés, certificats, dossiers de secrets et contextes de travail locaux. Si l’un de ces fichiers était déjà suivi par Git, retirez-le uniquement de l’index :

bun run sensitive:untrack
git status --short
git commit -m "chore(release): untrack local maintenance context"

La commande ne supprime pas les fichiers du disque : elle les retire seulement de l’index Git. Pour une correction manuelle équivalente :

git rm -r --cached --ignore-unmatch \
  AGENTS.md PROMPT_CONTEXT.md ANALYSE_STRUCTURE_REUTILISATION.md patch-memory

Vérifiez ensuite le diff avant de valider la modification.