member-console/test/AGENTS.md

test/ — instructions for LLM agents

If you are an automated agent working in this repository, read this before starting Docker. The test stack uses fixed default host ports; multiple worktrees running it concurrently will collide unless each generates its own isolated configuration.

All commands in this doc assume your working directory is test/ — that's where compose, the env file, and the binary's expected secret paths all resolve from.

Required first step in any worktree

cd test
./bootstrap-stack.sh

The script:

• Derives a slug from this worktree's directory name (override with ./test/bootstrap-stack.sh my-slug).
• Allocates a deterministic port slot via FNV-32(slug) % 200. Probes for collisions and advances if any candidate port is already bound on the host.
• Copies test/secrets/ from the main worktree if missing locally (this directory is gitignored, so fresh worktrees do not inherit it).
• Writes test/.env with COMPOSE_PROJECT_NAME, host port assignments, and MC_* env vars that override test/mc-config.yaml via Viper.
• Prints the URL/port table the developer should use.
• Idempotent: re-running with test/.env already in place is a no-op that reprints the summary.

After bootstrap

docker compose up -d
set -a; . .env; set +a
go run .. start --config mc-config.yaml

Both keycloak-seed (creates realm users) and fedwiki-render (resolves real KC UUIDs and templates seed/fedwiki/*.tpl into testdata/fedwiki/) are compose services that run automatically as one-shots on up. fedwiki waits for both to complete before starting. Keycloak silently regenerates the id field on POST /users, so FedWiki identity cannot be pinned at commit time — it's rendered after each realm seed.

The member-console binary must run with test/ as its working directory because mc-config.yaml references secrets/stripe-* via relative paths. Compose auto-loads .env from the current directory, so no -f/--env-file flags are needed.

Use the URLs printed by bootstrap, not the defaults from test/mc-config.yaml — the YAML still says port: 8081, but the running process listens on whatever MC_PORT is in test/.env.

Walking the operator UI with data

The default workflow produces a clean, empty environment — good for fresh-user flows. To populate the operator panel (products, plan ladder, entitlement set, one active grant) for UX walkthroughs or operator-panel exploration, run the opt-in demo seeder from the repo root after bootstrap-stack.sh:

./test/seed-demo.sh

Idempotent — re-running is a no-op. Person rows for bob/carlos/diana are not seeded (Keycloak doesn't honor pinned sub IDs); log in once as each demo user to populate them. See seed/member-console-demo/README.md for the catalog and rationale.

Tearing down

./teardown-stack.sh

Brings the compose stack down with volumes, removes test/.env, test/secrets/, and test/testdata/. Returns the worktree to a clean state for the next experiment.

Keycloak user seeding

seed/keycloak/seed-keycloak.sh creates users via POST /admin/realms/{realm}/partialImport, not POST /admin/realms/{realm}/users. Keycloak 26.x silently drops the id field on the latter (server-side ID assignment for least-privilege admin operations); partialImport preserves pinned IDs and is the supported escape hatch. See OpenSpec change 2026-05-11-keycloak-id-pinning-fix for the empirical confirmation and design rationale.

Temporal namespace

The compose stack sets SKIP_DEFAULT_NAMESPACE_CREATION=true on the temporal service, so a one-shot temporal-seed service registers the default namespace via the internal frontend on first up. If member-console fails with Namespace default is not found, the seed service didn't run yet — docker compose ... up -d temporal-seed and re-check docker compose ... logs temporal-seed.

Constraints

• Do not run Stripe webhook scenarios in parallel across stacks. All stacks share the same Stripe test account via test/secrets/stripe-*. Webhook delivery to one stack is global to that account; running two stacks through webhook flows simultaneously gives undefined results.
• Do not edit test/.env by hand. Re-run bootstrap (after deleting the file) if you need to change ports.
• Do not remove the ${VAR:-default} fallbacks from compose.yaml. They preserve the single-stack default workflow when no .env is present.

What bootstrap-stack.sh writes to test/.env

COMPOSE_PROJECT_NAME=<slug>
SLOT=<0..199>

POSTGRES_PORT, VALKEY_PORT, KEYCLOAK_PORT,
TEMPORAL_PORT, TEMPORAL_UI_PORT, FEDWIKI_PORT

KC_HOSTNAME, MC_BASE_URL, TEMPORAL_UI_URL

MC_PORT, MC_DB_DSN, MC_VALKEY_ADDR,
MC_OIDC_IDP_ISSUER_URL, MC_TEMPORAL_HOST,
MC_TEMPORAL_OAUTH_TOKEN_URL

Compose reads the first three blocks. Viper reads the MC_* block via the existing SetEnvPrefix("MC") + AutomaticEnv() configuration in cmd/root.go.