scripts/dev-stack.sh — one-shot local dev launcher (full stack + frontend, keep-alive)

[obchain]

Context

scripts/e2e-smoke.sh (PR #69) boots the M1 pipeline, runs five assertions, and tears everything down. Great for CI, useless for day-to-day development or visual demos where the operator wants the chart in a browser and live ticks streaming until they Ctrl-C.

This issue introduces a sibling script aimed at the inverse use case: boot every service (including the Next.js dev server), wait for healthy, print a single ready URL, and stay up until the operator kills it.

Scope

scripts/dev-stack.sh — bash, macOS-compatible (bash 3.2), no assertions, holds open on wait.

Boots in dependency order:

1. docker compose up -d — clickhouse + redis (no down -v, data persists across runs)
2. cargo build --release --bin volx-ingestion --bin volx-engine — pre-build
3. go build -o api/api-bin ./cmd/api — pre-build
4. Spawn volx-ingestion, volx-engine, api-bin as background processes, logs → /tmp/volx-dev-<service>.log
5. Spawn pnpm --dir frontend dev background, log → /tmp/volx-dev-frontend.log
6. Poll healthchecks: /ping (clickhouse), redis-cli PING, /v1/health (api), http://localhost:3000 (frontend)
7. Print: READY → http://localhost:3000/chart/bvol (or whichever default chart route the frontend exposes)
8. wait — block on background PIDs

On Ctrl-C / EXIT:

• pkill -f target/release/volx-ingestion, volx-engine, api-bin, frontend node process
• docker compose down (no -v — keep clickhouse data for next run)

Flags / env

Env	Default	Notes
LOGS	0	If 1, tail all four log files to stdout (multiplexed, prefixed by service)
SKIP_BUILD	0	If 1, skip cargo/go build (assume binaries fresh)
FRONTEND_PORT	3000	passthrough to pnpm dev

Acceptance criteria

• bash scripts/dev-stack.sh from repo root boots full stack, prints READY → http://..., blocks
• Browser navigated to the ready URL renders a chart that paints first candle within ~2 min and ticks live thereafter
• Ctrl-C tears down cleanly — docker ps empty for volx containers, no orphan rust/go/node processes
• Re-running immediately after teardown works (data persists in clickhouse volume, no stale-data issues since we are not asserting freshness)
• LOGS=1 streams all four log files to stdout, each line prefixed with [service]
• SKIP_BUILD=1 skips both build phases when binaries already exist
• README "End-to-end smoke" section grows a sibling "Local dev stack" entry with the one-line invocation

Out of scope

• Assertions (this is the inverse of e2e-smoke.sh — no pass/fail, just boot-and-hold)
• Hot-reload of rust/go services (would need cargo-watch / air; orthogonal)
• Production-mode frontend (pnpm build && pnpm start) — dev mode chosen for HMR + visual demo immediacy
• Browser auto-open (varies macOS/linux, leave to the operator)

Dependencies

• PR feat(scripts): M1 end-to-end smoke (Deribit → ingestion → engine → API → WS) #69 merged (provides the orchestration pattern + log path convention this script mirrors)
• M1 Frontend: Next.js 15 scaffold + Tailwind 4 + lightweight-charts #25/Frontend: landing page (live BVOL/EVOL + sparkline) #26/Frontend: /chart/[index] candle chart + live WS #27 (frontend exists and serves /chart/bvol)

Notes

The dependency on PR #69 is conceptual only — dev-stack.sh is a standalone file, not a refactor of the smoke script. Shared helpers can be extracted later if a third orchestrator appears.

Priority p2 because this is developer ergonomics, not on the M1 critical path. M1 closure is gated by #28 (CI), not this. But it ships alongside #28 as the visible artifact for "the local pipeline runs end-to-end and you can see it."