Sandbox npm Install

Quando Usar Esta Funcionalidade

Use esta funcionalidade sempre que:

• Precisar instalar pacotes npm pela primeira vez em uma nova sessão de sandbox
• package.json ou package-lock.json mudaram e você precisa reinstalar
• Encontrar falhas em binários nativos com erros como SIGILL, SIGSEGV, mmap ou unaligned sysNoHugePageOS
• O diretório node_modules estiver faltando ou corrompido

Pré-requisitos

• Um ambiente de sandbox Docker com um workspace montado via virtiofs
• Node.js e npm disponíveis no contêiner
• Um arquivo package.json no workspace de destino

Contexto

Workspaces de sandbox Docker são tipicamente montados via virtiofs (sincronização de arquivos entre o host e a VM Linux). Binários nativos Go e Rust (esbuild, lightningcss, rollup, etc.) falham com erros de alinhamento mmap ao serem executados a partir do virtiofs em aarch64. A solução é instalar no sistema de arquivos ext4 local do contêiner e criar um link simbólico de volta para o workspace.

Instalação Passo a Passo

Execute o script de instalação empacotado a partir da raiz do workspace:

bash scripts/install.sh

Opções Comuns

O Que o Script Faz

1. Copia package.json, package-lock.json e .npmrc (se presentes) para um diretório ext4 local
2. Executa npm ci (ou npm install se não houver lockfile) no sistema de arquivos local
3. Cria um link simbólico node_modules de volta para o workspace
4. Verifica binários nativos conhecidos (esbuild, rollup, lightningcss, vite) se presentes
5. Opcionalmente, instala navegadores Playwright e dependências do sistema (usa sudo quando disponível)

Se a verificação falhar, execute o script novamente — falhas podem ser intermitentes durante a configuração inicial.

Verificação Pós-Instalação

Após a conclusão do script, verifique se sua toolchain funciona. Por exemplo:

npm test             # Run project tests
npm run build        # Build the project
npm run dev          # Start dev server

Observações Importantes

• O diretório de instalação local (por exemplo, /home/agent/project-deps) é local ao contêiner e NÃO é sincronizado de volta para o host
• O link simbólico node_modules aparece como um link quebrado no host — isso é inofensivo, pois node_modules geralmente é ignorado pelo git
• Executar npm ci ou npm install no host substitui naturalmente o link simbólico por um diretório real
• Após qualquer alteração em package.json ou package-lock.json, reexecute o script de instalação
• NÃO execute npm ci ou npm install diretamente no workspace montado — binários nativos falharão

Solução de Problemas

Compatibilidade com Vite

Se o seu projeto usa Vite, pode ser necessário permitir o caminho do link simbólico em server.fs.allow. Adicione o diretório pai do alvo do link simbólico (por exemplo, /home/agent/project-deps/) à sua configuração do Vite para que o Vite possa servir arquivos através do link simbólico.