github/sandbox-npm-install

Que fait sandbox-npm-install ?

Installez des packages npm dans un environnement sandbox Docker. Utilisez cette compétence chaque fois que vous devez installer, réinstaller ou mettre à jour node_modules à l'intérieur d'un conteneur où l'espace de travail est monté via virtiofs. Les binaires natifs (esbuild, lightningcss, rollup) plantent sur virtiofs, donc les packages doivent être installés sur le système de fichiers local ext4 et liés symboliquement en retour.

Problème

Lorsque vous travaillez dans un conteneur où l'espace de travail est monté via virtiofs, les binaires natifs (par exemple, esbuild, lightningcss, rollup) peuvent planter avec une erreur de segmentation ou Illegal instruction. Cela se produit car virtiofs ne supporte pas pleinement les appels système nécessaires à ces binaires.

L'installation de packages node_modules directement dans l'espace de travail monté échouera ou plantera au moment de l'exécution pour tout package contenant des binaires natifs.

Solution

Cette compétence déplace l'installation de npm install vers un répertoire temporaire sur le système de fichiers local ext4 du conteneur. Ensuite, elle crée un lien symbolique entre ce répertoire local et le dossier node_modules dans l'espace de travail monté.

Cela permet à tous les packages npm de fonctionner correctement, y compris ceux avec des binaires natifs, sans modifier votre infrastructure ou votre code.

Fonctionnalités

• Installation automatique : Installe automatiquement les packages dans un répertoire local et les relie symboliquement.
• Détection intelligente : Détecte automatiquement si une installation échoue en raison de problèmes de virtiofs et applique la solution.
• Réinstallation forcée : Utilisez --force-reinstall pour forcer une nouvelle installation, même si les packages existent déjà.
• Gestion des processus : Tue les processus zombies et les relance si nécessaire.
• Cache de registre : Possibilité de spécifier un registre npm personnalisé avec --registry [URL].

Utilisation

# Utilisation standard (installation, réinstallation ou mise à jour)
npm install <packages>

# Réinstallation forcée
npm install --force-reinstall <packages>

# Installation avec un registre personnalisé
npm install --registry https://registry.npmjs.org <packages>

Prérequis

• Docker doit être en cours d'exécution.
• Le répertoire de l'espace de travail doit être monté via virtiofs.
• Node.js et npm doivent être installés dans le conteneur.

Comment cela fonctionne

1. La compétence vérifie si node_modules existe et est un lien symbolique. Si c'est le cas, elle vérifie si la cible est valide. Sinon, elle supprime le lien et crée un nouveau répertoire local.
2. Elle crée un répertoire temporaire (par exemple, /tmp/sandbox-npm-install-XXXXXX).
3. Elle exécute npm install dans ce répertoire temporaire.
4. Si l'installation échoue, elle tue les processus zombies et attend 5 secondes, puis réessaie une fois.
5. Si l'installation réussit, elle supprime node_modules dans l'espace de travail monté.
6. Elle crée un lien symbolique depuis node_modules de l'espace de travail vers le répertoire local installé.

Exemples

# Installer une dépendance de production
npm install express

# Installer une dépendance de développement
npm install --save-dev vitest

# Forcer la réinstallation de tous les packages
npm install --force-reinstall

# Installer depuis un registre distinct
npm install --registry https://npm.internal.company.com my-private-package

Compatibilité

• Fonctionne avec Claude Code, Cursor, Codex et d'autres agents IA avec accès à Docker.
• Fonctionne avec n'importe quel package npm (binaires natifs, dépendances, etc.).
• Fonctionne dans n'importe quel gestionnaire de packages compatible avec npm (par exemple, yarn, pnpm) mais utilise npm par défaut.

Dépannage

Problème : L'installation de packages échoue avec "Illegal instruction" ou une erreur de segmentation. Solution : L'espace de travail est probablement monté via virtiofs. Utilisez cette compétence pour déplacer l'installation vers le système de fichiers local.

Problème : node_modules est un lien symbolique cassé. Solution : Supprimez node_modules et réexécutez la commande npm install. Cette compétence créera un nouveau répertoire local et un lien symbolique.

Problème : Les packages semblent être installés mais ne sont pas trouvés. Solution : Assurez-vous que le répertoire temporaire existe toujours. Si le conteneur a été redémarré, vous devrez peut-être réinstaller.

Sécurité

• Aucune donnée externe n'est transmise ; tout reste dans l'environnement du conteneur.
• Aucune modification permanente de l'infrastructure n'est effectuée.
• Le répertoire temporaire est nettoyé après l'installation (sauf si --keep est spécifié).