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
  • --pull folds the pull into the restore while keeping the local store, so repeated ecluse ups across slots re-download nothing. It's the recommended hook form — no separate bocal pull step to remember.
  • --yes skips the confirmation prompt (a hook has no TTY). The preflight still runs — tooling, host/port reachability, target-DB existence, version compatibility, templating. --yes does 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).