ecluse integration
bocal has no dependency on any orchestrator and contains no orchestrator-specific code. It composes with ecluse (an ephemeral local-environment orchestrator) purely by convention, through three contracts bocal already exposes. This page is a practical guide; the full contract is specified in PRD-ecluse-integration.md in the repo.
The workflow neither tool does alone:
"Spin up a fresh isolated environment for this branch and load it with a specific named dataset a teammate captured."
ecluse gets you the empty, isolated environment; bocal fills it with known state.
Contract 1 — ports in, via env var
ecluse publishes each service's per-slot port as ECLUSE_<SERVICE>_PORT. Point each fixture service's port_env at it:
# fixture.toml
[[services]]
name = "postgres"
engine = "postgres"
port_env = "ECLUSE_POSTGRES_PORT" # bocal reads the per-slot port ecluse allocated
That's the entire wiring on bocal's side — no new code.
Contract 2 — hooks invoke bocal
# .ecluse.toml
[hooks]
post_up = "bocal restore customer-a --pull --yes" # pull-if-needed, then restore
# pre_down = "bocal save customer-a" # optional: capture on teardown
--pullfolds the pull into the restore while keeping the local store, so repeatedecluse ups across slots re-download nothing. It's the recommended hook form — no separatebocal pullstep to remember.--yesskips the confirmation prompt (a hook has no TTY). The preflight still runs — tooling, host/port reachability, target-DB existence, version compatibility, templating.--yesdoes not imply--allow-remote, so a hook can never silently restore over a remote DB (ecluse services are on loopback anyway).
The target database must already exist when post_up fires. The service ecluse brings up owns DB creation (the official Postgres image creates POSTGRES_DB on first boot); bocal only fills it. bocal's preflight catches a not-yet-created DB up front with an actionable error.
Contract 3 — env out, via file
bocal restore writes [env] to .bocal.env (a KEY=value file). bocal writes it and stops — loading it into the running processes is the orchestrator's (or your) job. Two supported mechanisms; pick one:
A — ecluse sources the file (if your ecluse supports it):
# .ecluse.toml
source_env = [".bocal.env"]
B — the dev command sources it (always works):
[[services]]
name = "api"
command = "set -a; . ./.bocal.env 2>/dev/null; set +a; npm run dev"
Per-slot values via templating
A fixture can't hardcode a value that depends on the per-slot port — most commonly a connection string. Use env templating:
# fixture.toml — [env]
DATABASE_URL = "postgres://localhost:{{ ECLUSE_POSTGRES_PORT }}/app"
On restore into a slot, bocal substitutes the resolved port, so .bocal.env carries the correct per-slot DATABASE_URL while the stored fixture stays slot-agnostic and shareable. To interpolate other ecluse-published vars, allowlist them via template_env in bocal.toml.
End-to-end
# Developer A — capture and share
ecluse up feat-demo # ports published as ECLUSE_*_PORT
# ... set up data in the running app ...
bocal save customer-a --tag v1
bocal push customer-a --tag v1
# Developer B — just spin up; the hook pulls and restores
ecluse up feat-demo # post_up runs `bocal restore customer-a --pull --yes`
For ephemeral CI with no persistent store, bocal restore customer-a --ci reads straight from the registry (implies --yes).