feat: start preflight guards and external-node event-port warnings

[rafa-stacks]

Summary

The follow-ups from #24: stacksup start now fails fast — before compose creates anything — when it would collide with another deployment, plus a config warning for a push-edge gap.

Port preflight

start test-binds every host port the deployment is about to publish. A taken port aborts with the owning service and the fix:

Error: host port 5432 (published by postgres) is already in use — another deployment
or process owns it; set or raise `port_offset` in stacks.toml, or stop whatever holds the port

Services already running are skipped (their ports are legitimately ours, so start/restart on a live stack stays idempotent), and single-service starts only check that service.

Project-name collision detection

Before starting, the deployment name is checked against docker compose ls --all. A project with the same name rendered from a different directory aborts the start — compose would otherwise silently adopt (and replace) that stack's containers, which was the worst failure mode of the pre-#24 world:

Error: deployment name `stacks` is already in use by a stack rendered from /other/dir/rendered/docker-compose.yml — set a distinct `name` in stacks.toml

Best-effort by design: if docker compose ls fails, start proceeds. The JSON matching is a pure function with unit tests (same file → us; different file → conflict; absent name / garbage JSON → no conflict).

Event-port warnings

When the node is external and the API or signer is managed, the apply-to-your-node warnings now also say that the API's event port (3700) / signer's endpoint (port 30000) is not published on this host, so an off-host node cannot push to it — run the node on this machine or expose the port via a compose override. Publishing these ports by default was deliberately avoided; it would poke holes in the #23 network isolation for every deployment to serve a niche topology.

Verified live

All three behaviors exercised against the built binary: a socket squatting 5432 → start refused pre-compose; two directories sharing the default name → second start refused naming the first's path; external node + managed API render → warning names port 3700.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Adds start-time preflight checks to prevent Docker Compose project name collisions and port conflicts, plus clearer warnings/docs for external-node event receiver ports.

Changes:

• Introduces published_ports() to enumerate host ports a deployment will publish (respecting port_offset).
• Adds start preflight guards for compose project collisions and for already-taken host ports, with unit tests.
• Expands configuration warnings and documents the new safety checks in the README.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 3 comments.

File	Description
src/utils/services.rs	Adds published_ports() helper used by docker start preflight checks.
src/utils/docker.rs	Adds project-collision detection and host-port test-binds before docker compose up, plus tests.
src/config/mod.rs	Improves warnings for external node + managed receivers by clarifying unpublished event ports.
README.md	Documents the new stacksup start collision/port preflight behavior.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.