JasperFx.Aspire: startup gates (A2)

[jeremydmiller]

Implements A2 from the design doc (.claude/docs/jasperfx-aspire-startup-gates-design.md), the orchestration-time complement to A1 (merged in #402). Ships in the same JasperFx.Aspire package.

Run a JasperFx provisioning verb as a run-to-completion resource that finishes before the service starts, wired via Aspire's WaitForCompletion:

var db = builder.AddPostgres("pg").AddDatabase("appdb");

builder.AddProject<Projects.Api>("api")
    .WithReference(db)
    .WaitFor(db)
    .WithJasperFxStartup("resources", "setup"); // runs to completion before "api" starts

Why this is low-risk vs A1

A1's hard problem was resolving a resource's environment inside a callback and spawning a child by hand. A2 has no such problem — each gate is a first-class Aspire resource pointing at the same project with the verb as args, so Aspire injects connection strings/env natively. The gate inherits the parent's references (declared before WithJasperFxStartup).

What's here

• WithJasperFxStartup (single-verb + fluent forms) + JasperFxStartupGate (ResourceName / Parallel / BlockOnFailure / RunWhen / ConfigureGate) + JasperFxStartupBuilder (Run / Check). Parent constraint is IResourceWithEnvironment, IResourceWithWaitSupport.
• Gate factory — AddProject(name, sameProjectPath) + WithArgs(verb, arg); clones the parent's reference/env annotations (EnvironmentCallbackAnnotation / WaitAnnotation / ResourceRelationshipAnnotation) onto the gate. Annotations are snapshotted before any wiring so the WaitForCompletion annotations added to the parent don't leak onto later gates.
• Ordering — sequential WaitForCompletion chaining in declaration order; Parallel opt-out.
• check-env is an opt-in blocking gate (Check() / WithJasperFxStartup("check-env")); RunWhen makes a gate environment-conditional; non-zero exit fails fast.
• Defaults: resources → setup, codegen → write (distinct from A1's codegen → preview).

Verification

• ✅ dotnet build jasperfx.slnx -c Release clean; VitePress docs build clean.
• ✅ 36 unit tests (20 new): pure helpers + app-model assertions over AddProject / WaitForCompletion / annotation-clone wiring via DistributedApplication.CreateBuilder — no Docker.
• ✅ Sample AppHost gains a resources setup + blocking check-env gate and compiles.
• ⚠️ Manual step: the live dashboard run (dotnet run --project src/AspireSample/AspireSample.AppHost) — confirm the gates show Finished and api starts only after them. The app-model tests cover the wiring; a live run can't be automated headlessly.

Spike findings (design step 0)

Validated against real Aspire 13.3.1: run-to-completion modeling of a project-with-verb-args, WaitForCompletion gating, and annotation cloning. Two corrections vs the draft API: the parent needs the IResourceWithWaitSupport constraint (not just IResourceWithEnvironment), and the wait annotation type is WaitAnnotation.

Docs

New "Startup gates" section on the Aspire dashboard integration page (/cli/aspire).

Downstream docs

Tracking issues for Marten / Wolverine / Polecat filed separately (design §9).

🤖 Generated with Claude Code