Installation npm en Sandbox

Quand utiliser cette skill

Utilisez cette skill chaque fois que :

• Vous devez installer des packages npm pour la première fois dans une nouvelle session sandbox
• package.json ou package-lock.json a changé et vous devez réinstaller
• Vous rencontrez des crashs de binaires natifs avec des erreurs comme SIGILL, SIGSEGV, mmap, ou unaligned sysNoHugePageOS
• Le répertoire node_modules est manquant ou corrompu

Prérequis

• Un environnement sandbox Docker avec un workspace monté via virtiofs
• Node.js et npm disponibles dans le conteneur
• Un fichier package.json dans le workspace cible

Contexte

Les workspaces sandbox Docker sont généralement montés via virtiofs (synchronisation de fichiers entre l'hôte et la VM Linux). Les binaires natifs Go et Rust (esbuild, lightningcss, rollup, etc.) crashent avec des erreurs d'alignement mmap quand ils sont exécutés depuis virtiofs sur aarch64. La solution consiste à installer sur le système de fichiers ext4 local du conteneur et à créer un symlink vers le workspace.

Installation étape par étape

Exécutez le script d'installation fourni depuis la racine du workspace :

bash scripts/install.sh

Options courantes

Ce que fait le script

1. Copie package.json, package-lock.json, et .npmrc (s'il existe) dans un répertoire ext4 local
2. Exécute npm ci (ou npm install s'il n'y a pas de lockfile) sur le système de fichiers local
3. Crée un symlink de node_modules vers le workspace
4. Vérifie les binaires natifs connus (esbuild, rollup, lightningcss, vite) s'ils sont présents
5. Installe optionnellement les navigateurs Playwright et les dépendances système (utilise sudo si disponible)

Si la vérification échoue, exécutez le script à nouveau — les crashs peuvent être intermittents lors de la configuration initiale.

Vérification post-installation

Une fois le script terminé, vérifiez que votre chaîne d'outils fonctionne. Par exemple :

npm test             # Exécuter les tests du projet
npm run build        # Construire le projet
npm run dev          # Démarrer le serveur de dev

Notes importantes

• Le répertoire d'installation local (ex. /home/agent/project-deps) est local au conteneur et N'EST PAS synchronisé vers l'hôte
• Le symlink node_modules apparaît comme un lien cassé sur l'hôte — c'est inoffensif car node_modules est généralement gitignored
• Exécuter npm ci ou npm install sur l'hôte remplace naturellement le symlink par un répertoire réel
• Après tout changement de package.json ou package-lock.json, réexécutez le script d'installation
• N'exécutez PAS npm ci ou npm install directement dans le workspace monté — les binaires natifs crasheront

Dépannage

Compatibilité Vite

Si votre projet utilise Vite, vous devrez peut-être autoriser le chemin symlinké dans server.fs.allow. Ajoutez le répertoire parent de la cible du symlink (ex. /home/agent/project-deps/) à votre configuration Vite pour que Vite puisse servir les fichiers via le symlink.