feat(shared): expose shared services on stable localhost ports for GUI clients

[gustavobertoi]

Requested from live testing: reach the shared engines (Postgres/MinIO/Redis/…) from host GUI clients like DataGrip, TablePlus, an S3 browser, or the RabbitMQ management UI — without a duplicate stack per repo.

Commands

• devstack shared expose [services...] — publish the shared engines on stable 127.0.0.1 host ports. No args = every exposable engine; name services to scope it.
• devstack shared ports — read-only projection: ports + copy-paste connection strings (lock-free).
• devstack shared expose --off — back to DNS-only.

Design (spec 03 host-reachability)

• Opt-in, loopback-only. Default stays "no host ports" (DNS over devstack_shared). Exposure is an up-time compose overlay (compose.expose.yaml) — the deterministic, golden-asserted generated compose is untouched (same posture as the provisioning overlay).
• No-collision by construction. Ports are ledger-allocated (FreeHostPort), stable across runs, in a distinct 5xxxx range so the expose overlay and the 4xxxx provisioning overlay never publish the same host port. Kafka is the one deliberate exception (host clients must use the fixed advertised 127.0.0.1:49092). A unit test enforces the invariant.
• Persistent. The up saga re-applies the overlay so host ports survive up/down. Refused on a remote backend (a remote bridge isn't host-routable).
• Useful surface. Per engine it publishes the primary protocol port + secondary UI ports (MinIO console, RabbitMQ management, NATS monitor) and prints a client-ready connection string (the admin DSN + a reminder that per-project DBs use the documented per-project dev creds).

Example

$ devstack shared expose
SERVICE                    PORT      ADDRESS            CONNECT
shared-postgres            postgres  127.0.0.1:55432    postgres://devstack:devstack@127.0.0.1:55432/postgres?sslmode=disable
shared-minio               s3        127.0.0.1:59000    http://127.0.0.1:59000
shared-minio (console)     console   127.0.0.1:59001    http://127.0.0.1:59001

per-project database: postgres://<project>:<project>@127.0.0.1:55432/<project>?sslmode=disable

Tests

• Unit: overlay write/read round-trip, instance resolution (all/named/rejects non-engines), per-engine connection URLs, the expose-vs-provision no-collision invariant, CLI table/JSON/quiet rendering, command registration.
• Verified live on WSL2: shared ports projection; the overlay merges cleanly with the running shared compose (docker compose config); a host psql client reaches shared-postgres on the published loopback port (HOST-CONNECT-OK PostgreSQL 18.4).
• Determinism/golden unchanged; orchestrate + cli suites green.

🤖 Generated with Claude Code