Script the zero-credential setup: one command from clone to runnable

[bharathm03]

The gap

There is no single command that takes a fresh clone to a state where you can run tests. Getting there today means reading DEVELOPMENT.md, starting a Postgres container by hand, and then running npm run setup — and nothing tells you which parts of the suite you can actually run until something fails.

This is narrower than it sounds, and worth stating precisely so nobody over-builds it.

Credentials are already a non-problem. scripts/dev-setup.ts writes per-service .env files with a generated BETTER_AUTH_SECRET, a shared RELAY_INTERNAL_SECRET, and stub values for GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET. No contributor needs a secret from us to build, test, or run the stack locally. That part works.

The one real external dependency is Postgres. npm run setup runs prisma migrate deploy and seeds plans plus a dev user, so it fails without a reachable PG_DATABASE_URL. The container command is documented, but documented is not scripted:

docker run -d --name antgrid-pg -p 5432:5432 \
  -e POSTGRES_USER=postgres -e POSTGRES_PASSWORD=postgres -e POSTGRES_DB=antgrid \
  postgres:16-alpine

So the gap is: the steps exist, they're just not automated, and the failure mode is a migration error rather than a useful message about what's missing.

What would close it

Roughly, in priority order — a partial fix is genuinely useful here, so please don't treat this as all-or-nothing:

1. Preflight in npm run setup. Before migrating, check what's present — Bun, a reachable PG_DATABASE_URL, optionally Flutter and a container runtime — and print a summary of what each missing piece costs you. Today an absent Postgres surfaces as Migration failed. Is Postgres running and PG_DATABASE_URL correct?, which is accurate but arrives after you've already committed to the command.

2. Offer to start Postgres. If a container runtime is available and nothing is listening on the configured port, offer the docker run above rather than printing it. Skip silently when there's no runtime — plenty of contributors have a system Postgres, and aspire/ deliberately does not require a container runtime.

3. Tell the contributor what they can run. The honest tiering is already in DEVELOPMENT.md and should be machine-checked, not just prose:

   • antgrid-wire, antgrid-relay, antgrid-bridge, packages/antgrid_relay_client, app — no credentials, no database
   • antgrid-web — needs Postgres
   • evals/ — needs real agent CLIs; will not run on a fork, and no workflow runs it

Constraints for whoever picks this up

• Never a bare bun test from the repo root. It recurses into evals/ and any stale worktree copies into one port space. Per-workspace bun run --filter <name> test only — filter names are not directory names.
• Must work on Linux, macOS and Windows. Windows contributors are a real constituency here and the setup script is where a POSIX-only assumption would hurt most.
• Keep it dependency-free — this runs before bun install has necessarily done anything useful.
• Don't make a container runtime mandatory. It is currently optional and should stay that way.

Why this is filed rather than fixed

It's a contributor-experience gap, and contributors are better placed than we are to notice where the current path is confusing. If you hit friction setting this repo up, the fix for that friction is exactly this issue — say so in a comment even if you don't want to write the patch.