Comece pelo estado observável
Confirme a raiz e os arquivos antes de mudar algo: pwd, ls -la e cat package.json reduzem erros de diretório. Depois veja os scripts com npm run, pacotes de primeiro nível com npm ls e comandos disponíveis com help ou which.
Se um processo já está ativo, jobs mostra o identificador; parar e reiniciar o job correto é mais seguro do que abrir vários servidores para a mesma tarefa.
pwd
ls -la
cat package.json
npm run
npm ls
which npm
jobsSintoma, próxima verificação
“Comando não encontrado”: rode help ou which e use npm exec para um binário local. “Script não existe”: compare o nome com npm run. “Pacote nativo”: leia o aviso do instalador e execute esse fluxo num ambiente Node com suporte ao binário.
“Preview parado”: confirme jobs, reinicie apenas o job do servidor e abra a URL retornada. “Arquivo não aparece”: salve, confira a raiz e busque pelo caminho; arquivos em node_modules, .git, dist e .odete são ignorados pela navegação recursiva.
| Sintoma | Verificação |
|---|---|
| script ausente | npm run |
| binário local | npm exec nome ou which nome |
| servidor ativo | jobs |
| porta/Preview | URL mostrada pelo servidor |
| erro de texto | grep -rn "termo" src |
| limite Swift | Problems e Swift Playgrounds |
Quando mudar de ambiente
Mude para um Mac ou CI quando encontrar addon nativo, build Astro/Next, compilação Swift, integração de sistema ou qualquer API Node que o runtime não implemente. Registrar o comando, a saída e a versão do pacote torna a reprodução objetiva.
Antes de reportar um bug, reduza o caso: comando digitado, diretório do projeto, trecho mínimo e saída completa. Isso separa uma limitação conhecida da Odete de um erro específico do projeto.