O que Executar faz?
Um site só está pronto quando é visto em execução. O código-fonte diz o que alguém pretendia; o navegador diz o que uma pessoa realmente obtém. Esta skill é o caminho mais curto entre uma pasta e uma página renderizada.
Execute
node <pasta-da-skill>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
--detectimprime o que encontrou e não inicia nada. Faça isso primeiro quando a pasta for desconhecida.--portcomeça a procurar na porta indicada e pega a próxima porta livre, para que dois projetos possam ser executados ao mesmo tempo.--openabre o navegador padrão.--shot out.pngrenderiza a página com 1440 pixels de largura, altura total, usando Playwright.--stopmata a árvore de processos a partir de.run/state.json.
Ele escreve .run/state.json (pid, porta, url, comando) e .run/server.log ao lado do projeto. Esses dois arquivos são toda a transferência entre o início e a parada.
O que ele detecta
| Encontra | Executa |
|---|---|
package.json com dev, start, serve ou preview | npm run <esse script> em uma porta livre, com PORT definida |
index.html na raiz | python -m http.server nessa pasta |
public/index.html, dist/index.html, build/index.html | um servidor estático enraizado na saída compilada |
| Um arquivo de configuração mas sem scripts | relata e para: o projeto precisa de seu próprio comando |
go.mod, Cargo.toml, pubspec.yaml | relata e para: use o próprio comando de execução do projeto |
Detalhes específicos de frameworks, portas padrão e modos de falha que vale a pena conhecer: references/stacks.md.
Lendo o resultado
O script prova três coisas e nada mais: um processo foi iniciado, uma porta respondeu, uma página foi renderizada. O que ele não pode lhe dizer:
- se o layout está correto em 375, 768 e 1440 (use
sitecraft/scripts/verify.mjspara isso) - se o console está limpo (não é capturado aqui;
verify.mjscaptura) - se a página da qual tirou a captura de tela é a página que o usuário queria (verifique a URL em relação à rota que você solicitou)
Portanto, o ciclo é: serve.mjs --shot, olhe a imagem com seus próprios olhos, corrija, tire novamente. Três renderizações é o limite para uma passagem; além disso, o problema é o plano, não o CSS.
Regras
- Nunca deixe um servidor em execução. Pare-o quando a verificação for concluída, ou diga claramente que ele ainda está ativo e em qual porta. Um servidor de desenvolvimento perdido na máquina do usuário é uma bagunça que ele precisa limpar.
- Não inicie o que você não pode parar. Se o projeto precisar de Docker, um banco de dados ou uma chave de API paga, diga isso antes de iniciar qualquer coisa.
- Informe a URL real.
localhost:4173, não "o aplicativo". Se a porta mudou porque 4173 estava ocupada, diga a nova. - Leia o log antes de adivinhar. Uma falha na inicialização é quase sempre uma dependência ausente, uma variável de ambiente faltando ou uma porta já em uso.
.run/server.logtem a resposta, e citar o erro real é melhor que uma teoria. - Sem instalações sem avisar. Se
node_modulesestiver faltando,npm installgeralmente é a solução, e também é uma mutação do projeto deles. Faça, depois diga que foi executado, ou pergunte uma vez quando a instalação for grande. - Estático sobre framework. Quando uma saída compilada existe e está atualizada, servir
dist/é mais rápido e mais fiel do que o servidor de desenvolvimento.
Quando não vai iniciar
- Leia
.run/server.loge cite o primeiro erro real, não a última linha. - Dependências ausentes:
npm installno projeto, depois tente novamente. - Variável de ambiente ausente: procure por
.env.example, nomeie o que é necessário, e pare se um valor for secreto e estiver ausente. - Porta já em uso: o script já avança para a próxima porta livre; uma porta fixa na configuração do framework é a causa habitual quando ainda falha.
- Etapa de compilação necessária: execute
npm run buildprimeiro, depois sirvadist/. - Nativo ou containerizado: devolva o comando que o projeto documenta. Nem toda stack é um script.
Lista de verificação
- Detectou a stack em vez de assumir uma
- Iniciou e viu uma resposta HTTP real, não apenas um processo gerado
- Informou a URL e porta exatas
- Olhou para uma captura de tela, não apenas para o log
- Verificou se a rota corresponde à página que era esperada
- Parou, ou disse que ainda está em execução e onde
- Citou o erro real quando falhou