Export canonical TypeScript API data from the CLI

[Adam Ratzman (adamint)]

Adds aspire sdk export, which emits the TypeScript API surface for an exact Name@Version as JSON on stdout. This is the producer half of fixing #17608 — aspire.dev currently reconstructs TypeScript signatures itself in AtsJsonGenerator, so what the docs show drifts from what the generator actually emits.

The idea is that the generator becomes the only thing that decides what TypeScript looks like, and the docs site just renders what it's handed.

$ aspire sdk export --package Aspire.Hosting.Redis@13.5.0 --language typescript > redis.api.json

Pure JSON on stdout, logs on stderr, so it pipes cleanly.

What's here

• TypeScriptApiProjector — pulled the projection logic out of the code generator so the export and the generated .ts come from one place. 73 members moved, no behavior change (the .verified.ts snapshots are byte-identical across the whole branch).
• IApiReferenceExporter / ApiReferenceExportOptions in Aspire.TypeSystem, plus an exportApi RPC on RemoteHost.
• sdk export in the CLI.
• Schema v1 is versioned and additive-only. Each item carries owningAssembly, and every declaration fragment is self-contained, so a consumer can concatenate the fragments for a package plus its closure and get something that type-checks with no site-authored shims.

Bugs this turned up

Writing the tests first shook out four real ones, all with regression coverage:

1. AtsContextFilter reference closure — owned types were seeded into the included sets before the walk, so CollectReferencedType's "did I just add this?" guard short-circuited and never walked their members. Any filtered generateCode threw on HealthStatus. This one predates the branch.
2. Declaration fragments weren't self-contained — signatures name wrapper-less handle types as FooHandle via GetWrapperOrHandleName, but the stub pass derived a class name instead. So we declared a symbol nobody referenced and left the referenced one dangling. 7 unresolved names when you run tsc over the real output.
3. sdk export couldn't find a code generator — the scanner AppHost doesn't reference Aspire.Hosting.CodeGeneration.TypeScript; sdk generate adds it via ILanguageDiscovery and export didn't. Every invocation failed until I wired it up.
4. Augmentations claimed another package's type — addRedis shipped as interface:DistributedApplicationBuilder owned by Aspire.Hosting.Redis, which collides with core's item ID across a manifest and misattributes a core-owned type. Now augmentation:{name} with the real owner.

Making the version label true

The version on an export document is what consumers key published documentation on, and review surfaced that nothing was making it true. sdk export Package@Version could publish a surface that was not that version's, two ways:

• A CLI run from a repository checkout picks DotNetBasedAppHostServerProject, which replaces every first-party Aspire.Hosting.* package reference with the matching project under src/ and throws the requested version away. Asking a 13.5.0 checkout for 13.4.0 exported the checkout under the older number.
• A bare NuGet version is a minimum rather than an equality, so a version missing from the feed quietly restored as the next one up.

Both are now narrow contracts on the export path. IntegrationReference carries RequireExactVersion, and sdk export sets it on the requested package so an unavailable version fails with NU1102 instead of resolving upward. IAppHostServerProject.GetLocalProjectSubstitution reports the substitution a checkout would make, and sdk export refuses a version the checkout would not actually produce. Same-version local development, third-party exports, --source pinning, the core-package guard, and code generator restoration are unchanged, and run/dump keep the minimum-version form that lets transitive dependencies unify.

Three more holes turned up while writing that:

5. A first-party name did not mean the checkout could supply it — the repository scanner substituted src/<name>/<name>.csproj for every Aspire.Hosting* reference and, when that project was absent, dropped the reference outright. sdk export --package Aspire.Hosting.DoesNotExist@13.5.0-dev restored cleanly and published an empty module under a package id that has never existed. It now falls back to an exact package reference, which fails with NU1101 as it should.
6. The skew check trusted an overrideable value — it compared the request against IdentitySdkVersion, which ASPIRE_CLI_VERSION and the install sidecar exist to override, so ASPIRE_CLI_VERSION=99.0.0 published the current Redis source as 99.0.0. The checkout now states its own version line from eng/Versions.props, and an identity override, an unreadable version line, or a mismatch on either half rejects. Overrides keep working everywhere no substitution happens.
7. The restore-failure footer printed the raw version where restore was given a range, sending a reader looking for a resolution failure that [13.4.0] explains on sight.

PackageVersion on ApiReferenceExportOptions took the documentation half rather than the validation half. An exporter sees loaded assemblies, not the package resolution that produced them, so the DTO cannot tell an exact-but-wrong version from a right one. Exactness belongs where the restore is decided; the docs say the caller owns accuracy and point at sdk export, which rejects a floating or range version before the scanner is built.

sdk dump keeps requested-version semantics deliberately: it restores with a minimum-version reference, and --format ci — the format the checked-in *.ats.txt baselines use — carries no package versions at all, so nothing version-keyed is published from it. That distinction is now stated in code, in the output-format spec, and in a test.

Testing

• Aspire.Hosting.CodeGeneration.TypeScript.Tests 103/103, Aspire.Hosting.RemoteHost.Tests 467/467, Aspire.Cli.Tests 4801/4801 (33 skipped)
• Ran it for real against a repo-local AppHost: 1.1 MB for Aspire.Hosting, 27 KB for Aspire.Hosting.Redis, empty stderr, exit 0
• Concatenated the fragments and ran tsc --noEmit --strict with skipLibCheck off — 0 errors
• The generated XML cannot show what NuGet does with it, so the version pins are proven by restoring twice against an offline folder feed that holds 13.4.1 but not the requested 13.4.0: the plain reference resolves upward with NU1603 (confirmed against project.assets.json), and the exact reference fails with NU1102. Covered on both the repository scanner and the prebuilt closure paths, since the package-only install path never touches the scanner.

The generated Aspire.TypeSystem API baseline is regenerated via GenAPI, additive only.

Consumer side is microsoft/aspire.dev — it validates this exact output against fixtures produced by this branch.

Contributes to #17608

[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 -- 19032

Or

• Run remotely in PowerShell:

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

[Copilot]

Pull request overview

Adds canonical TypeScript API export through aspire sdk export, sharing projection logic with generated SDK output.

Changes:

• Adds the export model, serializer, RPC, and CLI command.
• Fixes ATS reference-closure handling.
• Adds schema, CLI, RPC, and regression tests.

Show a summary per file

File	Description
src/Aspire.Hosting.CodeGeneration.TypeScript/AtsTypeScriptCodeGenerator.cs	Uses shared projection and implements export.
src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiProjector.cs	Centralizes TypeScript API projection.
src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiModel.cs	Defines the export model.
src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiExportWriter.cs	Serializes schema v1.
src/Aspire.TypeSystem/IApiReferenceExporter.cs	Adds the exporter contract.
src/Aspire.TypeSystem/ApiReferenceExportOptions.cs	Adds package export options.
src/Aspire.TypeSystem/api/Aspire.TypeSystem.cs	Updates the generated API baseline.
src/Aspire.Hosting.RemoteHost/CodeGeneration/CodeGenerationService.cs	Exposes the export RPC.
src/Aspire.Hosting.RemoteHost/CodeGeneration/CodeGeneratorResolver.cs	Resolves exporters.
src/Aspire.Hosting.RemoteHost/Diagnostics/RemoteHostProfilingTelemetry.cs	Adds export telemetry.
src/Aspire.Hosting.RemoteHost/AtsContextFilter.cs	Expands referenced type closure.
src/Aspire.Hosting.RemoteHost/Aspire.Hosting.RemoteHost.csproj	Grants test internals access.
src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs	Implements sdk export.
src/Aspire.Cli/Commands/Sdk/SdkCommandPreparation.cs	Shares scanner preparation.
src/Aspire.Cli/Commands/Sdk/SdkDumpCommand.cs	Uses shared preparation.
src/Aspire.Cli/Commands/Sdk/SdkCommand.cs	Registers the subcommand.
src/Aspire.Cli/Projects/IAppHostRpcClient.cs	Adds the client contract.
src/Aspire.Cli/Projects/AppHostRpcClient.cs	Implements export RPC invocation.
src/Aspire.Cli/Program.cs	Registers command services.
tests/Aspire.Hosting.RemoteHost.Tests/CodeGeneration/ApiReferenceExportTests.cs	Tests RPC behavior.
tests/Aspire.Hosting.RemoteHost.Tests/AtsContextFilterTests.cs	Covers closure expansion.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/AtsTypeScriptCodeGeneratorTests.cs	Tests export parity and declarations.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/AtsTypeScriptCodeGeneratorTests.ApiExport.verified.json	Captures schema output.
tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/AtsTypeScriptCodeGeneratorTests.ApiDeclarations.verified.txt	Captures declaration fragments.
tests/Aspire.Cli.Tests/Commands/Sdk/SdkExportCommandTests.cs	Tests CLI behavior.
tests/Aspire.Cli.Tests/TestServices/FakeAppHostServerSession.cs	Extends the fake RPC client.
tests/Aspire.Cli.Tests/Utils/CliTestHelper.cs	Registers the command in tests.

Review details

Suppressed comments (3)

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:128

• The code generator is restored at the running CLI version rather than the requested package version. Exporting an older/newer package can therefore apply a different release's projection rules (or fail when --source contains only the requested release), so the result is not canonical for the requested Name@Version. Restore the generator at packageVersion, as normal AppHost generation does for its effective SDK version.

            integrations.Add(IntegrationReference.FromPackage(codeGenPackage, ExecutionContext.IdentityVersion));

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:76

• This command promises that every human-readable message goes to stderr, but it never switches InteractionService.Console from its default stdout route. As a result, preparation diagnostics and the --output success message can be written to stdout. Route the command's human output to stderr before any discovery or preparation work.

        var language = parseResult.GetValue(s_languageOption)!;

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:119

• An explicit Aspire.Hosting@Version is never restored here. Both scanner implementations ignore the sdkVersion argument, so a CLI running a different version scans its bundled/repository Aspire.Hosting assembly and then labels that surface with the requested version. The command therefore cannot honor its exact Name@Version contract for the core package; the scanner must load the requested core package version rather than skipping it.

            if (!string.Equals(packageName, CorePackageName, StringComparison.OrdinalIgnoreCase))
            {
                integrations.Add(reference);
            }

• Files reviewed: 25/27 changed files
• Comments generated: 4
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (3)

src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiProjector.cs:276

• This hardcodes the generated options-bag parameter name to options, while the source emitter calls GetPublicOptionsParameterName to avoid collisions. A capability that already has a parameter named options is therefore exported with a different—or even duplicate and invalid—signature from the generated .mts, defeating the canonical-source contract. Resolve and pass the collision-safe name here too.

        var parameterList = BuildPublicParameterList(
            requiredParams,
            hasOptionals,
            optionsTypeName,
            trailingCancellationToken: GetTrailingCancellationTokenParameter(optionalParams));

src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiProjector.cs:744

• The structured parameters array is still built from raw ATS parameters instead of the resolved public signature. For example, the checked-in export declares withOptionalString(options?: WithOptionalStringOptions) but reports value and enabled as its parameters. Any consumer rendering the structured fields will reconstruct the same stale positional API this PR is intended to eliminate. Build this list from the required parameters plus the resolved options-bag and trailing cancellation-token parameters.

        var parameters = capability.Parameters
            .Where(p => builderModel is null || p.Name != targetParamName)
            .Select(p => new TypeScriptApiParameter
            {
                Name = p.Name,
                DeclaredType = MapParameterToTypeScript(p),
                IsOptional = p.IsOptional || p.IsNullable,
                Summary = p.Documentation?.Summary
            })

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:194

• The new CLI command has only fake project/session/RPC tests; there is no CLI end-to-end test that starts the real scanner and validates the machine-output contract. That leaves package/codegen restoration, RPC registration, and stdout/stderr separation untested—the exact integration points this command introduces. Add a Hex1b CLI E2E test using a local-hive package that invokes sdk export, redirects stdout, parses the JSON, and verifies stderr remains separate.

        await using var session = await SdkCommandPreparation.PrepareSessionAsync(
            _appHostServerProjectFactory,
            _serverSessionFactory,
            InteractionService,
            _logger,
            "aspire-sdk-export-",
            sdkVersion,
            integrations,
            packageSource,
            cancellationToken);

• Files reviewed: 27/29 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (3)

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:135

• A non-core Aspire package can request any version here, but the scanner and TypeScript code-generation package are still pinned to the running CLI's IdentityVersion. Thus a 13.6 CLI exporting Aspire.Hosting.Redis@13.5.0 applies the 13.6 signature-shaping generator and labels the result as 13.5.0, recreating the version drift this command is intended to prevent. Either restore/run the matching SDK and generator or reject official Aspire.Hosting.* versions that differ from IdentitySdkVersion, as is already done for core.

            else
            {
                integrations.Add(reference);
            }

src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiProjector.cs:276

• ResolveMethodSignature always names the synthesized optional-parameter bag options, but the source emitter calls GetPublicOptionsParameterName to avoid collisions. Real generated APIs such as addCSharpApp and promptProgress therefore use optionsBag, while this export reports options, reintroducing the docs/generated-signature drift this PR is intended to remove. Compute and pass the same collision-safe name here.

        var parameterList = BuildPublicParameterList(
            requiredParams,
            hasOptionals,
            optionsTypeName,
            trailingCancellationToken: GetTrailingCancellationTokenParameter(optionalParams));

src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiProjector.cs:740

• The structured parameters array is built from the original ATS parameters rather than the public signature. For example, the snapshot declares addTestRedis(name, options?: AddTestRedisOptions) but serializes name and port, with no options parameter. Consumers using these schema fields will reconstruct the same stale positional API this export is meant to eliminate. Build this list from the required public parameters plus the synthesized options bag (and any separately emitted cancellation token).

        var parameters = capability.Parameters
            .Where(p => builderModel is null || p.Name != targetParamName)
            .Select(p => new TypeScriptApiParameter
            {
                Name = p.Name,

• Files reviewed: 27/29 changed files
• Comments generated: 1
• Review effort level: Balanced

[Copilot]

Review details

Suppressed comments (2)

src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiExportWriter.cs:130

• A parameterless [Obsolete] is represented by the projector as DeprecationMessage = string.Empty, but AddIfPresent drops empty strings here. The generated TypeScript still emits @deprecated, while the canonical JSON reports no deprecation at all. Serialize deprecated whenever the value is non-null; an empty string still carries the deprecation state.

        AddIfPresent(json, "deprecated", member.DeprecationMessage);

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:27

• The new user-visible command is covered only with fake IAppHostServerProject/RPC clients. That cannot catch failures in the packaged CLI's command registration, code-generator package restore, scanner startup, RPC transport, or the stdout/stderr piping contract—the integration path this command exists to provide. Add a CLI end-to-end test that runs the packaged/local-hive aspire sdk export, parses redirected stdout as JSON, and verifies stderr remains separate.

internal sealed class SdkExportCommand : BaseCommand

• Files reviewed: 38/41 changed files
• Comments generated: 2
• Review effort level: Balanced

[Adam Ratzman (adamint)]

Fixed in 2886db7 — AtsCapabilityScanner.PruneRegistriesToSurvivingCapabilities now runs after both filters in both scan paths. The ownership map alone was not enough: GetKnownAssemblyNames also reaches the assembly through context.Methods[].DeclaringType, so the method and property registries are pruned with it. Covered by ScanAssemblies_CapabilityLostToACollision_DropsItsAssemblyFromExportingAssemblyNames and TryResolveCanonicalAssemblyName_RejectsAnAssemblyWhoseCapabilitiesWereAllFiltered, both of which fail without the prune.

[Adam Ratzman (adamint)]

Reverted in 2886db7 — src/Aspire.TypeSystem/api/Aspire.TypeSystem.cs is now byte-identical to main. Note the four-argument constructor no longer exists either: ManifestContext was removed in d6d6a1b, so ApiReferenceExportOptions takes three arguments in source again.

[Copilot]

Review details

Suppressed comments (3)

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:166

• The requested integration is pinned, but the TypeScript generator is still selected at the running CLI's version. An installed 13.5 CLI can therefore export Aspire.Hosting.Redis@13.4.0 using the bundled 13.5 core surface and 13.5 projection rules; running the same request with a 13.4 CLI can produce different declarations even though both documents are keyed only as Redis 13.4.0. The checkout substitution guard does not run for the installed/prebuilt path. Either reject first-party package/CLI version skew, or make the generator/core version part of the restored and exported identity so Name@Version determines one canonical document.

        var codeGenPackage = await GetCodeGenerationPackageAsync(language, cancellationToken);
        if (codeGenPackage is not null)
        {
            integrations.Add(IntegrationReference.FromPackage(codeGenPackage, ExecutionContext.IdentityVersion));

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:400

• Writing directly to the destination truncates an existing export before the asynchronous write completes. Cancellation, disk-full, or another I/O failure can therefore leave a partial JSON file (and destroy a previously valid one), even though this command treats partial documents as unsafe to publish. Write to a uniquely created sibling file and atomically replace the destination only after the complete JSON has been flushed; clean up the temporary file on failure.

            await File.WriteAllTextAsync(outputFile.FullName, json, cancellationToken);

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:75

• This new user-visible CLI workflow has only mocked command tests and in-process RemoteHost tests. Those cannot catch failures in the installed CLI's DI registration, real scanner restore/startup, JSON-RPC transport, or actual stdout/stderr redirection—the end-to-end contract this command exposes. Add a CLI E2E test under tests/Aspire.Cli.EndToEnd.Tests that runs the packaged PR CLI against a known package/source, redirects stdout, parses the exported JSON, and verifies the exit code and clean output streams.

    protected override async Task<CommandResult> ExecuteAsync(ParseResult parseResult, CancellationToken cancellationToken)

• Files reviewed: 39/41 changed files
• Comments generated: 0 new
• Review effort level: Balanced

[Copilot]

Review details

• Files reviewed: 40/44 changed files
• Comments generated: 1
• Review effort level: Balanced

[Adam Ratzman (adamint)]

Confirmed and fixed in e30db3c. Both paths now go through a single ResolveEntryPointSignature, so the declaration carries client: AspireClientRpc first and keeps ATS optionals positional; ApiExportDeclaresEntryPointsWithTheSignatureTheGeneratorEmits asserts the exported declaration against the emitted export async function text. Reverting to ResolveMethodSignature reproduces function startThing(name: string, options?: ...).

[Adam Ratzman (adamint)]

Heads up on the four red Azure jobs — they're inherited from main, not from anything here.

Main tip 5e7a15c is self-inconsistent: src/Aspire.Hosting.Azure/AzureBicepResourceScope.cs declares CreateForSubscription/CreateForTenant (renamed in #18976), while tests/Aspire.Hosting.Azure.Tests/AzureBicepResourceScopeTests.cs on the same commit still calls ForSubscription/ForTenant. CI builds the merge of this branch into main, so Hosting.Azure and Hosting.Azure.Kubernetes fail to compile on both OSes with CS0117. This branch doesn't touch that file, and the merge base has the pre-rename names, so the merge takes main's copy unchanged.

#19148 is already open to fix it. These jobs should clear on the next run once it lands.

The earlier E2E reds were separate and transient — four jobs failed in Set up .NET Core, and TypeScriptCodegenValidationTests timed out after two minutes waiting for Created apphost.mts. All cleared on rerun.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Sébastien Ros (sebastienros)]

Here are all the things I checked to ensure this is the correct design. Everything looks good, good job!

Q: What existing command exports the ATS API surface?

A: aspire sdk dump --format ci. The workflows use it to generate checked-in .ats.txt baselines and detect breaking changes.

Q: Can the existing command output JSON?

A: Yes: aspire sdk dump --format json. This exports raw, language-neutral ATS metadata.

Q: Should this PR use sdk dump with another formatter?

A: Probably not. The PR exports the final language-specific generated API, not raw ATS. A separate sdk export command is clearer while still reusing the ATS scanner and generator projection logic.

Q: Does the PR support other polyglot languages?

A: Not currently. Only TypeScript implements IApiReferenceExporter.

Q: Why are custom exporter implementations required?

A: Each generator applies different naming, type mapping, nullability, options, async, fluent-wrapper, module, and declaration rules. Raw ATS does not describe the final generated API.

Q: Is language an argument to the new CLI command?

A: Yes, and it is required:

aspire sdk export --language typescript

The short form is -l typescript.

Q: What happens when another language is requested?

A: A known generator without an exporter fails with an IApiReferenceExporter error. An unknown language fails with “no code generator found.” Both return InvalidCommand, emit no JSON, and report the error on stderr.

Q: What is the generated JSON shape?

A: It is a versioned document containing schemaVersion, language, package identity, modules, documented items and members, structured parameters, and self-contained language declarations.

Q: Is the JSON schema different for each language?

A: The current contract allows each language provider to define its own schema. Only TypeScript defines one today.

Q: Could Aspire use a common schema?

A: Yes, and that is likely preferable for a unified polyglot documentation pipeline. Exporters would remain language-specific but map into shared DTOs, with language-specific syntax stored in declaration or extension fields. Defining this contract now would avoid incompatible schemas later.

[github-actions]

Retrying the failed CI jobs for this pull request from the CI run attempt. The rerun is being tracked in the rerun attempt.

[Copilot]

Review details

Suppressed comments (4)

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:166

• This code-generation package also determines the exported TypeScript surface, but a bare version is a NuGet minimum and may restore a newer generator when this exact CLI version is unavailable. The result would then be produced by a different generator while retaining the requested package label. Pin the code-generation package exactly on the export path as well.

        var codeGenPackage = await GetCodeGenerationPackageAsync(language, cancellationToken);
        if (codeGenPackage is not null)
        {
            integrations.Add(IntegrationReference.FromPackage(codeGenPackage, ExecutionContext.IdentityVersion));

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:156

• An installed 13.5 CLI accepts a first-party package such as Aspire.Hosting.Redis@13.4.0, then projects that exact assembly with the 13.5 core and TypeScript generator. Generator behavior is versioned too (this PR itself renames generated options interfaces), so the JSON does not represent the TypeScript surface emitted by the 13.4 SDK even though it is labeled 13.4. Reject first-party package/CLI version skew as the core-package path does, or load the matching core and generator versions.

                // Pin the requested version: a bare NuGet version is a minimum, so an unavailable
                // version would restore as a later one and be published under the wrong number.
                // Use packageName rather than reference.Name so the restored reference and the
                // exported label can never name the package differently.
                integrations.Add(IntegrationReference.FromExactPackage(packageName, reference.Version));

src/Aspire.Cli/Configuration/IntegrationReference.cs:99

• When exactness is requested, an explicit non-singleton range such as [13.2.0,13.3.0) is returned unchanged, so FromExactPackage can still float despite its contract. Passing through [13.2.0] is fine, but range/floating expressions should be rejected whenever forceExact or RequireExactVersion is true.

        // An explicit range the caller already wrote (`[1.2.3]`, `(1.0,2.0)`) is left alone: wrapping
        // it again would produce a syntactically invalid range.
        if (!(forceExact || RequireExactVersion) || Version.Length == 0 || Version[0] is '[' or '(')
        {
            return Version;

src/Aspire.Cli/Commands/Sdk/SdkCommandPreparation.cs:163

• If validation rejects this project, ownership never reaches AppHostServerSession, so an IDisposable implementation such as PrebuiltAppHostServer is not disposed and its bundle layout lease remains held. The same applies when preparation returns failure before a session is created. Track project ownership and dispose it on every pre-session exit/exception, transferring ownership only after the session is created.

            var appHostServerProject = await appHostServerProjectFactory.CreateAsync(tempDir, cancellationToken);

            if (validateProject?.Invoke(appHostServerProject) is string rejection)
            {
                interactionService.DisplayError(rejection);
                return null;

• Files reviewed: 40/44 changed files
• Comments generated: 1
• Review effort level: Balanced

[Adam Ratzman (adamint)]

Fixed in e30db3c: the qualifier now encodes separators instead of dropping them (. -> _, literal _ doubled, anything else _x<hex>), which is reversible and therefore injective. OptionsInterfaceQualifiersDistinguishAssembliesThatDifferOnlyBySeparatorPlacement covers your Contoso.Foo.Bar / Contoso.FooBar case and reproduces ContosoFooBar when the fix is reverted.

[Copilot]

Review details

Suppressed comments (2)

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:166

• The requested package is pinned, but its TypeScript projector is always restored at the running CLI's version. Therefore the same Package@Version produces different JSON depending on which CLI runs the command. This is already observable in this branch: the new projector qualifies non-core options names (for example RedisWithDataVolumeOptions), whereas an older CLI generated the unqualified name. A 13.5 CLI exporting Aspire.Hosting.Redis@13.4.0 consequently labels 13.5 projection rules as 13.4. Either require a compatible CLI/code-generator version, restore the generator that belongs to the exported SDK, or include the generator version in the exported identity.

            integrations.Add(IntegrationReference.FromPackage(codeGenPackage, ExecutionContext.IdentityVersion));

src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiExportWriter.cs:130

• An obsolete capability without a message is serialized as if it were not obsolete. The projector deliberately uses null for active members and string.Empty for [Obsolete] without a message, but AddIfPresent drops both null and empty strings. Preserve the empty deprecated field so consumers can distinguish those states.

        AddIfPresent(json, "deprecated", member.DeprecationMessage);

• Files reviewed: 40/44 changed files
• Comments generated: 1
• Review effort level: Balanced

[Adam Ratzman (adamint)]

Fixed in e30db3c: a qualifier starting with a digit is now prefixed with _, which cannot alias a name that already begins with an underscore because a literal _ encodes as a doubled one. Covered by OptionsInterfaceQualifiersEscapeAssemblyNamesThatStartWithADigit.

[Copilot]

Review details

Suppressed comments (2)

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:166

• This leaves the TypeScript code-generator package as a NuGet minimum even though that package defines every exported name and signature. If the matching version is absent but a later version is available, NuGet silently upgrades the generator and the command publishes that later projection under the requested package's unchanged Name@Version; the document does not record a generator version. Pin the generator package (and update the test that currently asserts it is floating), or include and validate the generator identity as part of the export contract.

        var codeGenPackage = await GetCodeGenerationPackageAsync(language, cancellationToken);
        if (codeGenPackage is not null)
        {
            integrations.Add(IntegrationReference.FromPackage(codeGenPackage, ExecutionContext.IdentityVersion));

tests/Aspire.Hosting.CodeGeneration.TypeScript.Tests/Snapshots/WithDataVolumeOptionsMerged.verified.ts:1

• This snapshot is not byte-identical: it renames an exported TypeScript interface from WithDataVolumeOptions to CodeGenerationTypeScriptTestsWithDataVolumeOptions, contrary to the PR description's “no behavior change” claim. Because consumers can name these exported interfaces directly, either preserve the existing generated names where there is no collision or update the PR contract and migration expectations to acknowledge the source-breaking generator change.

• Files reviewed: 40/44 changed files
• Comments generated: 1
• Review effort level: Balanced

[Adam Ratzman (adamint)]

Confirmed and fixed in e30db3c. IdentityVersionForged now tracks ASPIRE_CLI_VERSION specifically, so a sidecar-supplied version no longer trips the core guard; SdkExportOfTheCorePackageAcceptsASidecarSuppliedIdentity fails with exit code 1 when the check is reverted to the aggregate.

[Copilot]

Review details

Suppressed comments (3)

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:166

• The exported package is pinned to packageVersion, but its TypeScript surface is projected by the code-generation package at the running CLI's IdentityVersion. Generator behavior is version-dependent (this PR itself changes options-interface naming), so a newer CLI can export Aspire.Hosting.Redis@13.4.0 using 13.5 generator semantics and publish that result under the 13.4 package key. Either constrain exports to the matching SDK/generator version or include and validate the generator identity in the export contract; pinning only the integration does not make the documented TypeScript API canonical for Name@Version.

        // The code generator lives in a separate package that the scanner AppHost does not reference
        // by default, so without this the server loads no generators and every export fails with
        // "No code generator found". `sdk generate` adds the same package for the same reason.
        var codeGenPackage = await GetCodeGenerationPackageAsync(language, cancellationToken);
        if (codeGenPackage is not null)
        {
            integrations.Add(IntegrationReference.FromPackage(codeGenPackage, ExecutionContext.IdentityVersion));

src/Aspire.Hosting.CodeGeneration.TypeScript/TypeScriptApiExportWriter.cs:130

• An obsolete capability with no message is projected as DeprecationMessage = string.Empty, but AddIfPresent drops empty strings. The generated TypeScript emits a bare @deprecated tag for this case, while the canonical JSON omits deprecated entirely and documentation consumers treat the API as current. Preserve any non-null deprecation value, including the empty string.

        AddIfPresent(json, "deprecated", member.DeprecationMessage);

src/Aspire.Cli/Commands/Sdk/SdkExportCommand.cs:81

• Routing InteractionService here happens after Program.DisplayFirstTimeUseNoticeIfNeededAsync. That startup path only recognizes --format json/--json as machine-readable, so a first interactive sdk export can write the welcome banner to stdout before this method runs (and --output can unexpectedly write banner text to stdout too). Register the sdk export command shape in HasMachineReadableOutput and cover it in RootCommandTests, so the pure-JSON stdout contract holds before command execution begins.

        // This command always emits machine-readable JSON, so it has no --format option for
        // BaseCommand's json redirect to key off. Without this, preparation diagnostics and the
        // --output success message land on stdout and corrupt the document a caller is piping.
        // The JSON write overrides back to stdout explicitly, and an explicit override wins.
        InteractionService.Console = ConsoleOutput.Error;

• Files reviewed: 42/46 changed files
• Comments generated: 0 new
• Review effort level: Balanced