`aspire docs api get` returns stale signatures for TypeScript APIs

[joperezr]

aspire docs api get returns stale signatures for TypeScript APIs

Summary

aspire docs api get <id> (and aspire docs api search ... --language typescript) returns API signatures that do not match the actual generated TypeScript bindings in .aspire/modules/aspire.mts for the same Aspire SDK version. Following the documented signatures produces code that fails to compile.

The skill (aspireify) explicitly instructs agents to use aspire docs api search / aspire docs api get as the source of truth before writing AppHost code. When that source disagrees with the shipped SDK, agents produce broken code and only recover after hand-inspecting .aspire/modules/aspire.mts.

Reproduction

Repo state:

• Run aspire init --language typescript on Aspire CLI 13.4.0+6a8235582edcc92b676480612f82284843cb96e9.
• aspire add javascript (or any flow that pulls Aspire.Hosting.JavaScript).
• The bundled CLI reports the docs API at version 13.3.0; the generated SDK is 13.4.0.

Example 1 — addJavaScriptApp

aspire docs api get typescript/aspire.hosting.javascript/addjavascriptapp returns:

addJavaScriptApp(
    name: string,
    appDirectory: string,
    runScriptName?: string): JavaScriptAppResource

But .aspire/modules/aspire.mts defines:

addJavaScriptApp(
    name: string,
    appDirectory: string,
    options?: AddJavaScriptAppOptions): JavaScriptAppResourcePromise;

export interface AddJavaScriptAppOptions {
    runScriptName?: string;
}

Following the docs:

builder.addJavaScriptApp("api", "../services/api", "dev")
// TS2559: Type '"dev"' has no properties in common with type 'AddJavaScriptAppOptions'.

Example 2 — addViteApp

Docs return:

addViteApp(
    name: string,
    appDirectory: string,
    runScriptName?: string): ViteAppResource

Bindings:

addViteApp(name: string, appDirectory: string, options?: AddViteAppOptions): ViteAppResourcePromise;

export interface AddViteAppOptions {
    runScriptName?: string;
}

Example 3 — withHttpEndpoint

Docs return:

withHttpEndpoint(
    port?: number,
    targetPort?: number,
    name?: string,
    env?: string,
    isProxied?: boolean): IResourceWithEndpoints

Bindings:

withHttpEndpoint(options?: WithHttpEndpointOptions): ContainerResourcePromise;

export interface WithHttpEndpointOptions {
    port?: number;
    targetPort?: number;
    name?: string;
    env?: string;
    isProxied?: boolean;
}

Following the docs:

.withHttpEndpoint(undefined, undefined, "http", "PORT")
// TS2554: Expected 0-1 arguments, but got 4.

Pattern

The TS SDK appears to have migrated several builder methods from positional arguments to a single options object, but the aspire.dev reference docs (queried via aspire docs api) still show the pre-migration positional signatures. Likely all add* and several with* overloads on the JavaScript hosting package are affected.

The docs response also includes:

• Module: ... Version: 13.3.0 — the docs are pinned to the prior minor, even when the locally restored SDK is 13.4.x.
• The return-type field still says e.g. JavaScriptAppResource rather than JavaScriptAppResourcePromise.

Impact

• The aspireify skill instructs agents to "Verify APIs before writing AppHost code" with exactly these CLI commands. Trust is misplaced.
• Agents fail their first aspire start, dig through 50k+ lines of generated bindings to recover, and waste 30–60s of round-trip time per fix.
• New TS AppHost users (humans) hitting the docs site directly get the same stale signatures.

Proposed fixes

In priority order:

1. Version-pin the docs index to the locally restored SDK. When aspire docs api ... runs inside an AppHost workspace, it should resolve the version from aspire.config.json → sdk.version (or the .aspire/modules/aspire.mts source) and fetch docs for that version. Today it appears to always return the latest published doc set on aspire.dev, which lags by a minor.

2. Backfill aspire.dev API reference for 13.4 TS APIs. The options-object signatures shipped in 13.4; the reference site needs to catch up. Long-term this should be driven from the same TypeDoc/JSON output that produces .aspire/modules/aspire.mts, not a separate authoring pipeline.

3. Add a fallback rule to the aspireify skill at skills/aspireify/references/apphost-wiring.md "Looking up APIs and integrations" section:

   If aspire docs api get returns a signature that the TypeScript compiler rejects, open .aspire/modules/aspire.mts and search for the export name — the generated bindings are the ground truth for the locally restored SDK version. Report the docs-vs-bindings discrepancy back to the user (or file an issue) so docs can catch up.

4. Surface the version mismatch in the CLI output. If the docs index version differs from the local SDK version, aspire docs api get could print a warning line:

   ⚠️ Docs index is version 13.3.0; your local SDK is 13.4.0. Signatures may differ from the shipped bindings. Cross-check against .aspire/modules/aspire.mts if compilation fails.

Source-of-truth notes

• CLI source: microsoft/aspire → src/Aspire.Cli/ (look for DocsApi* / docs api command handlers).
• Skill source: microsoft/aspire-skills → skills/aspireify/references/apphost-wiring.md.
• Reference site content: wherever aspire.dev/reference/api/typescript/... is generated from.

Milestone

13.5