¿Qué hace run?
Un sitio no está terminado hasta que se ha visto en ejecución. El código fuente dice lo que alguien pretendía; el navegador dice lo que una persona recibe. Este skill es el camino más corto entre una carpeta y una página renderizada.
Ejecútalo
node <carpeta del skill>/scripts/serve.mjs <dir> [--port 4173] [--open] [--shot out.png] [--stop] [--detect]
--detectimprime lo que encontró y no inicia nada. Hazlo primero cuando la carpeta no sea familiar.--portempieza a buscar ahí y toma el siguiente puerto libre, así dos proyectos pueden ejecutarse a la vez.--openabre el navegador predeterminado.--shot out.pngrenderiza la página a 1440 de ancho, altura completa, mediante Playwright.--stopmata el árbol de procesos desde.run/state.json.
Escribe .run/state.json (pid, puerto, url, comando) y .run/server.log junto al proyecto. Esos dos archivos son toda la transferencia entre el inicio y la parada.
Lo que detecta
| Encuentra | Ejecuta |
|---|---|
package.json con dev, start, serve o preview | npm run <ese script> en un puerto libre, con PORT establecido |
index.html en la raíz | python -m http.server en esa carpeta |
public/index.html, dist/index.html, build/index.html | un servidor estático enraizado en la salida de la compilación |
| Un archivo de configuración pero sin scripts | lo reporta y se detiene: el proyecto necesita su propio comando |
go.mod, Cargo.toml, pubspec.yaml | lo reporta y se detiene: usa el comando de ejecución del proyecto |
Detalles específicos del framework, puertos predeterminados y los modos de fallo que vale la pena conocer: references/stacks.md.
Leyendo el resultado
El script prueba tres cosas y nada más: un proceso inició, un puerto respondió, una página se renderizó. Lo que no puede decirte:
- si el diseño es correcto a 375, 768 y 1440 (usa
sitecraft/scripts/verify.mjspara eso) - si la consola está limpia (no se captura aquí;
verify.mjsla captura) - si la página de la que tomó captura es la página que el usuario quería (verifica la URL contra la ruta que solicitaste)
Así que el bucle es: serve.mjs --shot, mira la imagen con tus propios ojos, corrige, vuelve a tomar captura. Tres renderizados es el límite por pasada; más allá, el problema es el plan, no el CSS.
Reglas
- Nunca dejes un servidor corriendo. Detenlo cuando la verificación esté hecha, o di claramente que sigue activo y en qué puerto. Un servidor de desarrollo perdido en la máquina del usuario es un lío que tienen que limpiar.
- No empieces lo que no puedas detener. Si el proyecto necesita Docker, una base de datos o una clave de API de pago, dilo antes de iniciar cualquier cosa.
- Reporta la URL real.
localhost:4173, no "la aplicación". Si el puerto se movió porque el 4173 estaba ocupado, di el nuevo. - Lee el registro antes de adivinar. Un inicio fallido casi siempre es una dependencia faltante, una variable de entorno faltante o un puerto ya ocupado.
.run/server.logtiene la respuesta, y citar el error real es mejor que una teoría. - Nada de instalaciones sin decirlo. Si falta
node_modules,npm installsuele ser lo correcto, y también es una mutación de su proyecto. Hazlo, luego di que se ejecutó, o pregunta una vez cuando la instalación sea grande. - Estático antes que framework. Cuando existe una salida de compilación y está actualizada, servir
dist/es más rápido y fiable que el servidor de desarrollo.
Cuando no iniciará
- Lee
.run/server.logy cita el primer error real, no la última línea. - Dependencias faltantes:
npm installen el proyecto, luego reintenta. - Variables de entorno faltantes: busca
.env.example, nombra lo que es necesario, y detente si un valor es secreto y está ausente. - Puerto ya ocupado: el script ya avanza al siguiente puerto libre; un puerto fijo en la configuración del framework suele ser la causa cuando aún falla.
- Paso de compilación requerido: ejecuta
npm run buildprimero, luego sirvedist/. - Nativo o contenedorizado: devuelve el comando que el proyecto documenta. No todos los stacks son un script.
Lista de verificación
- Detectó la pila en lugar de asumir una
- Lo inició y vio una respuesta HTTP real, no solo un proceso iniciado
- Reportó la URL y el puerto exactos
- Miró una captura de pantalla, no solo el registro
- Verificó que la ruta coincida con la página que se quería
- Lo detuvo, o dijo que sigue corriendo y dónde
- Citó el error real cuando falló