JasperFx.Aspire — JasperFx CLI verbs as Aspire dashboard commands (A1)

[jeremydmiller]

Implements A1 from the design doc (.claude/docs/jasperfx-aspire-command-integration-design.md): a new JasperFx.Aspire hosting package that surfaces a JasperFx app's command-line verbs as clickable custom commands on the resource tile in the .NET Aspire dashboard.

builder.AddProject<Projects.Api>("api").WithJasperFxCommands();

Because Marten, Wolverine, and Polecat all build on the same JasperFx command infrastructure, this lights up for the entire Critter Stack with no per-product code.

What's here (Phase 1)

• WithJasperFxCommands / WithJasperFxCommand extensions + JasperFxCommandOptions / JasperFxCommandRegistration. Read-only verbs (check-env, describe, codegen preview) are added by default; mutating verbs (codegen write, resources, projections) require IncludeMutatingCommands and each get a confirmation prompt.
• JasperFxVerbCatalog — curated static metadata for the standard verbs (zero runtime coupling to the target). Unknown/product-specific verbs are accepted and treated as mutating (safe-by-default).
• JasperFxCommandExecutor — the dashboard callback runs in the AppHost, so it spawns a short-lived child of the same app (dotnet run --project <csproj> --no-build -- <verb>) with the resource's resolved environment (evaluated from its EnvironmentCallbackAnnotations — connection strings etc.) layered on the inherited AppHost env. Child stdout/stderr stream into the resource's dashboard logs via ResourceLoggerService; the exit code maps to the success/failure toast.

Aspire version

Targets net10.0 against Aspire.Hosting 13.3.1 (Aspire 13 is net10-first), using the 9.2+ CommandOptions WithCommand overload. The design doc said "pin to 9.x" — that predates Aspire's move to 13.x calendar versioning; 13.x is the current stable and the API is the same CommandOptions shape.

De-risking spike (design step 0)

The riskiest mechanic — resolving a resource's Aspire-managed environment inside the command callback — is validated at the API level: the whole surface (WithCommand/CommandOptions, EnvironmentCallbackContext evaluation, IValueProvider.GetValueAsync, ResourceLoggerService, KnownResourceStates) compiles against real Aspire 13.3.1, and the standalone sample (src/AspireSample) integrates it into a real AppHost.

Verification

• ✅ dotnet build jasperfx.sln -c Release clean.
• ✅ 16 unit tests (catalog selection/templating; executor ProcessStartInfo construction + exit-code mapping).
• ✅ Sample AppHost + API compile against the package.
• ⚠️ Manual step remaining: the dashboard click-through (dotnet run --project src/AspireSample/AspireSample.AppHost, click Check environment on the api tile) — the end-to-end env-resolution proof can't be automated headlessly. Steps in src/AspireSample/README.md.

The sample is intentionally out of jasperfx.sln so core CI isn't burdened with the Aspire AppHost SDK + Postgres hosting restore.

Deferred to follow-ups

• Phase 2: a machine-readable describe --json in JasperFx core so the catalog is discovered dynamically from the target (incl. product-specific/custom verbs) instead of curated.
• Downstream docs in Marten / Wolverine / Polecat (tracking issues filed separately).

🤖 Generated with Claude Code