Route staging-identity CLI to its darc feed regardless of version shape

[mitchdenny]

Problem

On a staging build of Aspire, aspire add <pkg> behaves differently between C# and TypeScript (polyglot) apphosts:

// C#
aspire add foundry
✅ The package Aspire.Hosting.Foundry::13.4.0-preview.1.26280.6 was added successfully.

// TS
aspire add foundry
Select a version of Aspire.Hosting.Foundry:
> 13.3.5-preview.1.26270.6 (based on NuGet.config)
  daily

The TypeScript path never offers the matching staging version because the synthesized staging channel routes Aspire* to the shared dnceng/dotnet9 daily feed instead of the build's own SHA-specific darc-pub-microsoft-aspire-<commit> feed.

Root cause

In PackagingService.CreateStagingChannel, useSharedFeed was derived from the CLI build's version shape:

var useSharedFeed = !hasExplicitFeedOverride && stagingQuality is not PackageChannelQuality.Stable;

A prerelease-shaped staging build (e.g. 13.4.0-preview.1.26280.6) defaults to Both quality → useSharedFeed = true → the shared daily feed (which only carries main-branch daily packages). But darc publishes a per-commit darc-pub-microsoft-aspire-<commit> feed for every officially published release-branch build, prerelease- or stable-shaped. The old comment's assumption that "darc feeds only exist for stable builds" was wrong.

C# apphosts masked the bug because the darc feed is baked into their nuget.config (written from the channel's PackageMappings); polyglot apphosts resolve solely through the channel's feed, so they surfaced it.

Fix

Decouple feed provenance (identity) from version filtering (quality):

• Add ShouldUseSharedStagingFeed(hasExplicitFeedOverride, stagingQuality, identityChannel): a staging-identity CLI always resolves Aspire* from its own darc feed regardless of version shape. Explicit overrideStagingFeed and non-staging identities keep the prior quality-based routing unchanged, so only the prerelease-shaped staging case flips.
• Add an injectable cliInformationalVersionProvider constructor seam (mirroring the existing isStableShapedCliVersion seam) so the derived darc feed URL is deterministic and assertable in tests, instead of reading the nondeterministic test-host assembly version.
• Correct the misleading comments that claimed darc feeds only exist for stable-shaped builds.

Because GetChannelsAsync → CreateStagingChannel is the single source of truth for aspire add search, polyglot restore, and C# nuget.config writing, fixing it here unifies the C# and TypeScript code paths.

Tests

Full PackagingServiceTests suite: 70/70 passing. Notable additions:

• Prerelease-shaped staging identity → asserts the resolved Aspire* source is the darc-pub-microsoft-aspire-<hash> feed (not dotnet9), ConfigureGlobalPackagesFolder == true, PinnedVersion == null (the bug repro). Verified it fails before the fix (resolves dotnet9) and passes after (resolves darc).
• Stable-shaped staging identity → darc feed with Stable quality (guards Staging build of CLI bakes channel as stable, causing aspire init to drop nuget.config without staging feed (resolves wrong Aspire package versions) #17527).
• Staging identity + overrideStagingFeed → override wins.
• A PR/daily/staging/stable decision-table theory, an underivable-feed warning test, identity/quality symmetry asserts, and override-mechanism tests covering identity/version overrides, invalid-identity fallback, override precedence, build-metadata hyphen handling, the one-time warning, and the cached unavailable-reason path.

Notes

• Targets release/13.4.
• Side effects of the flip for prerelease staging are consistent with stable-shaped staging, which already used the darc feed: ConfigureGlobalPackagesFolder becomes true, and the CLI-version pin (only applied on the shared feed) is no longer applied since the darc feed carries only the matching build.

Relationship to #17744

#17744 reports an adjacent — but distinct — staging symptom that this PR does not fix:

• That repro is a stable-shaped staging CLI (13.4.0+<hash>) with channel: staging. Its debug log shows Resolved 'staging' channel: feed=<staging Aspire feed>, quality=Stable — i.e. the staging channel is already routed to the darc feed (the stable-shaped path this PR leaves unchanged). So the feed-provenance fix here has no effect on that run.
• Its symptom is that aspire add persists/reports the search-selected version (13.3.5-preview.1.26270.6, which came from the default based on NuGet.config channel) instead of the version restore actually resolved (13.4.0-preview.1.26280.4). The restore log proves 13.3.5-preview.1.26270.6 exists on no configured feed (NuGet bumped up to the next available version), so that value is the stale catalog/default-channel candidate, not a darc-feed hit.

That is a search-vs-restore version reconciliation gap (the persisted version should reflect what restore resolved), which is independent of which feed the staging channel points at. This PR is a prerequisite (the staging channel must point at the correct darc feed) but is not sufficient to close #17744; that should be tracked/fixed separately.

Validating staging feed routing locally

To make #17744 verifiable without an official build, this PR adds two PackagingService-scoped diagnostic overrides so a locally built CLI (which bakes a local identity and an unstamped version, and therefore never synthesizes a staging channel) can be made to behave exactly like a staging build for the purpose of staging feed-routing:

• overrideCliIdentityChannel — forces the identity used for staging-feed routing decisions only (validated via IdentityChannelReader.IsValidChannel; invalid values are ignored). It does not change the global identity used for hive/packages-directory lookups, so the blast radius stays limited to feed provenance.
• overrideCliInformationalVersion — forces the informational version that both the SHA derivation and the stable-shape/quality predicate read (e.g. 13.4.0-preview.1.26280.6+<commit>).

Both overrides are required to reach the darc path from a local build, and a one-time warning is emitted whenever either is active so a normal CLI invocation can't silently resolve packages from an overridden identity/feed. The full recipe (build locally, set channel: staging, set the two env vars, run aspire add <pkg> --debug, confirm the resolved darc feed) is documented in docs/cli-staging-validation.md.

A follow-up to lift the informational-version seam onto CliExecutionContext on main is tracked in #17750.

Helper scripts for staging/stable validation

To make the recipe one command — and to support a full interactive flow against an easy-to-get build — this PR also adds eng/scripts/debug-staging.{sh,ps1} and eng/scripts/debug-stable.{sh,ps1} (sharing a debug-aspire-channel core). Both target identity staging and the SHA-specific darc-pub-microsoft-aspire-<sha8> feed, differing only in version shape/quality:

Script	Version shape	Expected quality	Scenario
debug-staging	prerelease	Both	#17744
debug-stable	stable	Stable	#17527

Modes:

• default — runs aspire add <pkg> --debug in a throwaway dir and asserts the darc feed resolves (exit non-zero otherwise).
• --print-env / -PrintEnv — emits export/$env: lines to apply to the current shell so every aspire command behaves like the simulated build.
• --shell / -Shell — opens an interactive subshell with the overrides applied and the target CLI first on PATH, for a full aspire new/add/run flow; overrides vanish on exit. The subshell also points NUGET_PACKAGES at a per-SHA isolated cache (<temp>/aspire-debug-nuget/<sha8>) so simulated-staging restores can't contaminate (or be contaminated by) the global package cache.

--pr <N> installs that PR's full-bundle build first and targets it, so you can validate against a real installed CLI (not just a local source build). The interactive recipe and a per-identity validation matrix are documented in docs/cli-staging-validation.md, linked from docs/contributing.md.

[github-actions]

🚀 Dogfood this PR with:

⚠️ WARNING: Do not do this without first carefully reviewing the code of this PR to satisfy yourself it is safe.

curl -fsSL https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.sh | bash -s -- 17743

Or

• Run remotely in PowerShell:

iex "& { $(irm https://raw.githubusercontent.com/microsoft/aspire/main/eng/scripts/get-aspire-cli-pr.ps1) } 17743"

[github-actions]

Re-running the failed jobs in the CI workflow for this pull request because 5 jobs were identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

• Tests / Hosting-1 / Hosting-1 (windows-latest) - Job-level runner or infrastructure failure matched the transient allowlist.
• Tests / Cli.EndToEnd-JavaScriptPublishTests / Cli.EndToEnd-JavaScriptPublishTests (ubuntu-latest) - Failed step 'Run nuget dependent tests (Linux/macOS)' will be retried because the job log matched a configurable test-retry pattern: MCR registry rate limiting (HTTP 403)
• Tests / Cli / Cli (macos-latest) - Test execution failure will be retried because 1 failed test(s) matched transient test failure patterns (MCR registry rate limiting (HTTP 403)).
• Tests / Cli / Cli (ubuntu-latest) - Test execution failure will be retried because 1 failed test(s) matched transient test failure patterns (MCR registry rate limiting (HTTP 403)).
• Tests / Cli / Cli (windows-latest) - Test execution failure will be retried because 1 failed test(s) matched transient test failure patterns (MCR registry rate limiting (HTTP 403)).

Matched test failure patterns (1 test)

• Aspire.Cli.EndToEnd.Tests.JavaScriptPublishTests.AllPublishMethodsBuildDockerImages — MCR registry rate limiting (HTTP 403)

[Copilot]

Copilot encountered an error and was unable to review this pull request. You can try again by re-requesting a review.

[github-actions]

Re-running the failed jobs in the CI workflow for this pull request because 1 job was identified as retry-safe transient failures in the CI run attempt.
GitHub was asked to rerun all failed jobs for that attempt, and the rerun is being tracked in the rerun attempt.
The job links below point to the failed attempt jobs that matched the retry-safe transient failure rules.

• Tests / Cli.EndToEnd-KubernetesDeployWithValkeyTests / Cli.EndToEnd-KubernetesDeployWithValkeyTests (ubuntu-latest) - Test execution failure will be retried because 1 failed test(s) matched transient test failure patterns (Unable to access container registry during publish).

Matched test failure patterns (1 test)

• Aspire.Cli.EndToEnd.Tests.KubernetesDeployWithValkeyTests.DeployK8sWithValkey — Unable to access container registry during publish

[github-actions]

❌ CLI E2E Tests failed — 109 passed, 1 failed, 2 unknown (commit ca752ee)

❌ Failed Tests

Status	Test	Recording	Job	Artifacts
❌	DeployK8sWithValkey	Recording	#78716274148	Logs

View all recordings

Status	Test	Recording	Job	Artifacts
✅	AddPackageInteractiveWhileAppHostRunningDetached	Recording	#78716274742	Logs
✅	AddPackageWhileAppHostRunningDetached	Recording	#78716274742	Logs
✅	AgentCommands_AllHelpOutputs_AreCorrect	Recording	#78716274455	Logs
✅	AgentInitCommand_DefaultSelection_InstallsDefaultSkills	Recording	#78716274455	Logs
✅	AgentInitCommand_MigratesDeprecatedConfig	Recording	#78716274455	Logs
✅	AgentInitCommand_NonInteractive_BundleOnlySkillsBeyondCliCatalog_AreInstallable	Recording	#78716274455	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp	Recording	#78716274271	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_DevLocalhost	Recording	#78716274271	Logs
✅	AgentMcpListStructuredLogsReturnsLogsFromStarterApp_Isolated	Recording	#78716274271	Logs
✅	AllPublishMethodsBuildDockerImages	Recording	#78716274492	Logs
✅	AspireAddAndStartWorkAgainstLegacyAppHostTs	Recording	#78716274704	Logs
✅	AspireAddPackageVersionToDirectoryPackagesProps	Recording	#78716274759	Logs
✅	AspireInitSingleFileAppHostRunsViaDotnetRunAppHost	Recording	#78716274467	Logs
✅	AspireInitWithExistingAppHostDirRecreatesMissingNuGetConfigAndPreservesFiles	Recording	#78716274460	Logs
❔	AspireInitWithSolutionFileGeneratesAppHostThatBuildsAgainstChannelHive	Recording	#78716274460	Logs
✅	AspireStartUpdatesStaleTypeScriptAppHostPath	Recording	#78716274774	Logs
✅	AspireUpdateRemovesAppHostPackageVersionFromDirectoryPackagesProps	Recording	#78716274759	Logs
✅	AspireUpdateRemovesOrphanAppHostPackageVersionWhenSdkAlreadyCurrent	Recording	#78716274759	Logs
✅	Banner_DisplayedOnFirstRun	Recording	#78716274481	Logs
✅	Banner_DisplayedWithExplicitFlag	Recording	#78716274481	Logs
✅	Banner_NotDisplayedWithNoLogoFlag	Recording	#78716274481	Logs
✅	CertificatesClean_RemovesCertificates	Recording	#78716274677	Logs
✅	CertificatesTrust_WithNoCert_CreatesAndTrustsCertificate	Recording	#78716274677	Logs
✅	CertificatesTrust_WithUntrustedCert_TrustsCertificate	Recording	#78716274677	Logs
✅	ConfigSetGet_CreatesNestedJsonFormat	Recording	#78716274698	Logs
✅	CreateAndRunAspireStarterProject	Recording	#78716274794	Logs
✅	CreateAndRunAspireStarterProjectWithBundle	Recording	#78716274358	Logs
✅	CreateAndRunEmptyAppHostProject	Recording	#78716274684	Logs
✅	CreateAndRunJavaEmptyAppHostProject	Recording	#78716274307	Logs
✅	CreateAndRunJsReactProject	Recording	#78716274611	Logs
✅	CreateAndRunPolyglotAppHostWithDevLocalhostUrls	Recording	#78716274794	Logs
✅	CreateAndRunPythonReactProject	Recording	#78716274585	Logs
✅	CreateAndRunTypeScriptEmptyAppHostProject	Recording	#78716274443	Logs
✅	CreateAndRunTypeScriptStarterProject	Recording	#78716274674	Logs
✅	CreateJavaAppHostWithViteApp	Recording	#78716274822	Logs
✅	CreateTypeScriptAppHostWithViteApp_AllowsGuestAppPackageManagerToDiffer	Recording	#78716274558	Logs
✅	CreateTypeScriptAppHostWithViteApp_UsesConfiguredToolchain	Recording	#78716274558	Logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces	Recording	#78716274485	Logs
✅	DashboardRunWithAgentMcpListTracesReturnsNoTraces_DevLocalhost	Recording	#78716274485	Logs
✅	DashboardRunWithOtelTracesReturnsNoTraces	Recording	#78716274485	Logs
✅	DashboardRunWithOtelTracesReturnsNoTraces_DevLocalhost	Recording	#78716274485	Logs
✅	DeployK8sBasicApiService	Recording	#78716274638	Logs
✅	DeployK8sWithExternalHelmChart	Recording	#78716274465	Logs
✅	DeployK8sWithGarnet	Recording	#78716274378	Logs
✅	DeployK8sWithMongoDB	Recording	#78716274590	Logs
✅	DeployK8sWithMySql	Recording	#78716274540	Logs
✅	DeployK8sWithPostgres	Recording	#78716274725	Logs
✅	DeployK8sWithRabbitMQ	Recording	#78716274390	Logs
✅	DeployK8sWithRedis	Recording	#78716274576	Logs
✅	DeployK8sWithSqlServer	Recording	#78716274325	Logs
❌	DeployK8sWithValkey	Recording	#78716274148	Logs
✅	DeployTypeScriptAppToKubernetes	Recording	#78716274362	Logs
✅	DescribeCommandResolvesReplicaNames	Recording	#78716274615	Logs
✅	DescribeCommandShowsRunningResources	Recording	#78716274615	Logs
✅	DetachFormatJsonProducesValidJson	Recording	#78716274515	Logs
✅	DetachFormatJsonProducesValidJsonWhenRestartingExistingInstance	Recording	#78716274515	Logs
✅	DoPublishAndDeployListStepsWork	Recording	#78716274853	Logs
✅	DocsCommand_RendersInteractiveMarkdownFromLocalSource	Recording	#78716274789	Logs
✅	DoctorCommand_DetectsDeprecatedAgentConfig	Recording	#78716274455	Logs
✅	DoctorCommand_TypeScriptAppHostReportsMissingConfiguredToolchain	Recording	#78716274614	Logs
✅	DoctorCommand_WithSslCertDir_ShowsTrusted	Recording	#78716274614	Logs
✅	DoctorCommand_WithoutSslCertDir_ShowsPartiallyTrusted	Recording	#78716274614	Logs
✅	GatewayWithoutExternalEndpoint_FailsPublishWithGuidance	Recording	#78716274289	Logs
✅	GeneratedAspireDevScript_StartsWatchMode_WithConfiguredToolchain	Recording	#78716274558	Logs
✅	GlobalMigration_HandlesCommentsAndTrailingCommas	Recording	#78716274698	Logs
✅	GlobalMigration_HandlesMalformedLegacyJson	Recording	#78716274698	Logs
✅	GlobalMigration_PreservesAllValueTypes	Recording	#78716274698	Logs
✅	GlobalMigration_SkipsWhenNewConfigExists	Recording	#78716274698	Logs
✅	GlobalSettings_MigratedFromLegacyFormat	Recording	#78716274698	Logs
✅	IngressWithoutExternalEndpoint_FailsPublishWithGuidance	Recording	#78716274289	Logs
✅	InitTypeScriptAppHost_AugmentsExistingViteRepoInWorkspaceSubdirectory	Recording	#78716274558	Logs
✅	InteractiveCSharpInitCreatesExpectedFiles	Recording	#78716274740	Logs
✅	InvalidAppHostPathWithComments_IsHealedOnRun	Recording	#78716274786	Logs
✅	JavaScriptHostingApisRunFromTypeScriptAppHost	Recording	#78716274492	Logs
✅	LatestCliCanStartStableChannelAppHost	Recording	#78716274794	Logs
✅	LatestCliCanStartStableChannelTypeScriptAppHost	Recording	#78716274794	Logs
✅	LegacySettingsMigration_AdjustsRelativeAppHostPath	Recording	#78716274774	Logs
✅	LogsCommandShowsResourceLogs	Recording	#78716274522	Logs
✅	OtelLogsReturnsStructuredLogsFromStarterApp	Recording	#78716274780	Logs
✅	OtelLogsReturnsStructuredLogsFromStarterAppIsolated	Recording	#78716274780	Logs
✅	PsCommandListsRunningAppHost	Recording	#78716274379	Logs
✅	PsFormatJsonOutputsOnlyJsonToStdout	Recording	#78716274379	Logs
✅	PublishJavaScriptPatternsGeneratesExpectedDockerComposeArtifacts	Recording	#78716274683	Logs
✅	PublishWithConfigureEnvFileUpdatesEnvOutput	Recording	#78716274683	Logs
✅	PublishWithDockerComposeServiceCallbackSucceeds	Recording	#78716274683	Logs
✅	PublishWithoutOutputPathUsesAppHostDirectoryDefault	Recording	#78716274683	Logs
✅	ResourceCommand_FailedExecution_DisplaysAppHostLogPathAndLogContainsEntries	Recording	#78716274787	Logs
✅	ResourceCommand_SetAndDeleteParameterUpdatesDescribeOutput	Recording	#78716274787	Logs
✅	RestoreGeneratesSdkFiles	Recording	#78716274300	Logs
✅	RestoreGeneratesSdkFiles_WithConfiguredToolchain	Recording	#78716274730	Logs
✅	RestoreRefreshesGeneratedSdkAfterAddingIntegration	Recording	#78716274730	Logs
✅	RestoreSupportsConfigOnlyHelperPackageAndCrossPackageTypes	Recording	#78716274357	Logs
✅	RunFromParentDirectory_UsesExistingConfigNearAppHost	Recording	#78716274559	Logs
✅	RunReportsSyntaxErrorsForDotNetAppHost	Recording	#78716274374	Logs
✅	RunReportsSyntaxErrorsForTypeScriptAppHost	Recording	#78716274374	Logs
✅	SecretCrudOnDotNetAppHost	Recording	#78716274695	Logs
✅	SecretCrudOnTypeScriptAppHost	Recording	#78716274696	Logs
✅	StagingChannel_ConfigureAndVerifySettings_ThenSwitchChannels	Recording	#78716274399	Logs
✅	StartAndWaitForTypeScriptSqlServerAppHostWithNativeAssets	Recording	#78716274488	Logs
✅	StartReportsSyntaxErrorsForDotNetAppHost	Recording	#78716274374	Logs
✅	StartReportsSyntaxErrorsForTypeScriptAppHost	Recording	#78716274374	Logs
✅	StopAllAppHostsFromAppHostDirectory	Recording	#78716274701	Logs
✅	StopJavaPolyglotAppHostUsingApphostDirectory	Recording	#78716274646	Logs
✅	StopNonInteractiveSingleAppHost	Recording	#78716274701	Logs
✅	StopTypeScriptPolyglotAppHostUsingApphostDirectory	Recording	#78716274426	Logs
✅	StopWithNoRunningAppHostExitsSuccessfully	Recording	#78716274742	Logs
✅	TypeScriptAppHostRunDoesNotDeadlockWhenLazyOptionsInvokeAsyncCallback	Recording	#78716274443	Logs
✅	UnAwaitedChainsCompileWithAutoResolvePromises	Recording	#78716274730	Logs
❔	UpdateProjectChannelToStable_CSharpEmptyAppHost_PreservesAspireConfigChannel	Recording	#78716274391	Logs
✅	UpdateProjectChannelToStable_CSharpSingleFileInit_PreservesAspireConfigChannel	Recording	#78716274391	Logs
✅	UpdateProjectChannelToStable_TypeScriptSingleFileInit_PreservesAspireConfigChannel	Recording	#78716274391	Logs
✅	UpdateProjectChannelToStable_TypeScript_PreviewsStablePackagesAndPreservesChannel	Recording	#78716274391	Logs

---

_{📹 Recordings uploaded automatically from CI run #26708726647}

[aspire-repo-bot]

✅ No documentation update needed.

docs_optional → bug_fix_restores_documented_behavior

Triggered signals (1): pr_body_has_cli_flag_mention — fires on --debug (as in aspire add <pkg> --debug) mentioned in the PR body's contributor validation recipe. This refers to the existing --log-level Debug option already documented in aspire-add.mdx via the option-log-level.md include; no new flag was introduced.

Why no docs PR is needed: The PR is a bug fix that makes aspire add for polyglot (TypeScript) apphosts behave consistently with C# apphosts in staging builds — routing Aspire.* package resolution to the per-build darc-pub-microsoft-aspire- feed. The intended behavior was always documented (aspire add adds packages from configured sources); the bug was that polyglot apphosts used the wrong feed. The two new diagnostic env vars (overrideCliIdentityChannel, overrideCliInformationalVersion) are contributor-only tools that emit a one-time warning and are documented in the aspire repo's docs/cli-staging-validation.md, not intended for aspire.dev.