build-dev-server

name	build-dev-server
description	Start or restart a project dev server on a specific or discovered port, wait until it is ready, and monitor it for automatic recovery. Use when the user asks to start, restart, keep alive, watch, or monitor a development server.

Build Dev Server

Start the dev server for the current project and keep it running. Run commands in the current working directory.

Determine Port

If the user provided a port, use it. Otherwise inspect project config such as vite.config.ts, app.config.ts, .env, package.json, justfile, or similar.

Always use the determined port. If occupied, kill the existing process instead of switching ports:

lsof -ti :<port> | xargs kill -9 2>/dev/null || true

Start Server

Discover the command from justfile, package.json, Makefile, or equivalent. Common commands:

• just dev
• pnpm dev
• npm run dev
• make dev

Run prerequisite builds first if the project needs them.

Start the server in a persistent background process or terminal session with PORT=<port> when the project honors that variable. Retain the process or session identifier so its output and state remain observable after startup.

Wait Until Ready

Poll:

for i in $(seq 1 30); do curl -sf http://localhost:<port>/ >/dev/null 2>&1 && echo ready && break; sleep 1; done

Report http://localhost:<port>/.

Monitor and Recover

After the server is ready, use the available recurring-monitoring or wait mechanism to check the same URL about once per minute. Keep monitoring until the user asks to stop or the surrounding task ends.

For each check:

• Confirm the server responds successfully on the determined port.
• If healthy, continue monitoring without sending repetitive status messages.
• If unhealthy, inspect the retained process output for the cause.
• Kill any stale process still occupying the port.
• Repeat prerequisite builds when they are required for startup.
• Restart the server in a new persistent process or session.
• Wait for readiness again and notify the user that recovery occurred.

Do not silently switch ports during recovery. If restart repeatedly fails, report the relevant output and stop retrying blindly.