Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
17 changes: 15 additions & 2 deletions .agents/skills/update-integrations/SKILL.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ description: Update integration documentation links and API reference data by sy

This skill synchronizes the integration package catalog with documentation URL mappings and generates per-package API reference schemas. It ensures every NuGet package listed in the integrations data file has a corresponding documentation link and an up-to-date API reference JSON file.

> **Automation note:** The scheduled `update-integration-data` workflow (`.github/workflows/update-integration-data.yml`) runs this update deterministically — no agent/LLM. It executes `src/frontend/scripts/update-integration-data.ps1`, which runs `pnpm update:all`, detects `"version":` changes in `src/frontend/src/data/aspire-integrations.json`, and — only when a version actually moves — runs the C# and TypeScript API regeneration (and the twoslash bundle) before opening a PR via the Aspire bot GitHub App. You can reproduce the full flow locally with `pwsh src/frontend/scripts/update-integration-data.ps1` (add `-SkipRegen` for a fast data-only run). Use this skill for **manual or one-off runs that need judgment** — for example: adding a new integration, reconciling `integration-docs.json`, validating release-branch feed resolution, troubleshooting a regen failure flagged by the workflow's PR, or regenerating data outside the scheduled cadence.
> **Automation note:** The scheduled `update-integration-data` workflow (`.github/workflows/update-integration-data.yml`) runs this update deterministically — no agent/LLM. It executes `src/frontend/scripts/update-integration-data.ps1`, which runs `pnpm update:all`, detects `"version":` changes in `src/frontend/src/data/aspire-integrations.json`, and — only when a version actually moves — runs the C#, TypeScript, and Go API regeneration (and the twoslash bundle) before opening a PR via the Aspire bot GitHub App. You can reproduce the full flow locally with `pwsh src/frontend/scripts/update-integration-data.ps1` (add `-SkipRegen` for a fast data-only run). Use this skill for **manual or one-off runs that need judgment** — for example: adding a new integration, reconciling `integration-docs.json`, validating release-branch feed resolution, troubleshooting a regen failure flagged by the workflow's PR, or regenerating data outside the scheduled cadence.

## Overview

Expand All @@ -19,9 +19,10 @@ The aspire.dev site maintains three key data locations:
- **`src/frontend/src/data/integration-docs.json`** — Mappings from package names to site-relative documentation URLs.
- **`src/frontend/src/data/pkgs/`** — Per-package API reference JSON files (e.g. `Aspire.Hosting.Redis.13.1.2.json`) generated by the `PackageJsonGenerator` tool. These feed the auto-generated API reference pages at `/reference/api/`.
- **`src/frontend/src/data/ts-modules/`** — Per-package TypeScript API reference JSON files (e.g. `Aspire.Hosting.Redis.13.2.0.json`) generated by the `AtsJsonGenerator` tool. These feed the auto-generated TypeScript API reference pages at `/reference/api/typescript/`.
- **`src/frontend/src/data/go-modules/`** — Per-package Go API reference JSON files (e.g. `Aspire.Hosting.Redis.13.2.0.json`) generated by the `AtsJsonGenerator` tool in Go mode. These feed the auto-generated Go API reference pages at `/reference/api/go/`.
- **`src/frontend/src/data/twoslash/aspire.d.ts`** — A single consolidated TypeScript declaration bundle generated from the `ts-modules` JSON by `scripts/generate-twoslash-types.ts`. Consumed by `expressive-code-twoslash` to provide hover tooltips for TypeScript code samples in the docs. **Source-controlled** — commit the diff whenever `ts-modules` changes.

This skill keeps the documentation mappings in sync with the package catalog and regenerates both the C# and TypeScript API reference data.
This skill keeps the documentation mappings in sync with the package catalog and regenerates the C#, TypeScript, and Go API reference data.

## Prerequisites

Expand Down Expand Up @@ -290,6 +291,18 @@ After the JSON is refreshed, `update-ts-api` automatically chains `generate-twos
cd src/frontend && pnpm twoslash-types
```

### 5b. Generate Go API reference data

After the TypeScript data is refreshed, regenerate the Go API reference JSON files from the same package set:

```bash
pnpm --filter ./src/frontend run update:go-api
```

`update-go-api.ts` runs the same `generate-ts-api-json.ps1` script as `update:ts-api`, with `-Language go`. Each package is dumped with `aspire sdk dump` exactly as for TypeScript, and the `AtsJsonGenerator` Go mode then renders the dump with the names and signatures that `aspire sdk generate --language go` produces: a flat `aspire` package, `...*Options` structs for optional parameters, and `(T, error)` returns. Package selection, parallelism, retries, tolerated scanner diagnostics, and stale-version cleanup behave as described in 5a. Set `ASPIRE_API_GO_MODULES_DIR` to redirect the output; the orchestrator uses it to stage the output before publishing. Capabilities that have no concrete Go type are skipped, and the generator output lists them. There is no twoslash bundle for Go.

The generated Go JSON is normalized with `normalize-generated-api-data.ts`, like the other generated API data. See the `AtsJsonGenerator` README for the Go output format and its known limitations.

### 6. Verify all links

For every entry in the updated `integration-docs.json`:
Expand Down
1 change: 1 addition & 0 deletions .github/instructions/astro.instructions.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ Defined in `src/content.config.ts`:
- **i18n** — Starlight i18n loader for 15 locales
- **packages** — auto-generated API reference JSON from `src/data/pkgs/`
- **tsModules** — auto-generated TypeScript API reference JSON from `src/data/ts-modules/`
- **goModules** — auto-generated Go API reference JSON from `src/data/go-modules/`

Preserve Starlight's `docsLoader()`, `i18nLoader()`, `docsSchema()`, and `i18nSchema()` when extending content. Use `glob()` or `file()` from `astro/loaders` for additional file-backed collections, and query entries with type-safe `getCollection()` and `getEntry()` from `astro:content`. Import `z` from `astro/zod`, not `astro:content`; use Zod 4 helpers such as `z.email()` and `z.url()` for new email and URL schemas.

Expand Down
6 changes: 5 additions & 1 deletion .github/workflows/update-integration-data.yml
Original file line number Diff line number Diff line change
Expand Up @@ -24,7 +24,10 @@ jobs:
update:
name: Update integration data
runs-on: ubuntu-latest
timeout-minutes: 45
# Three generation passes (C#, TypeScript, Go) each scan every package, so
# the runtime scales with the number of languages. The TypeScript pass alone
# takes about ten minutes on a hosted runner.
timeout-minutes: 75
permissions:
contents: read
steps:
Expand Down Expand Up @@ -132,6 +135,7 @@ jobs:
src/frontend/src/assets/samples \
src/frontend/src/data/pkgs \
src/frontend/src/data/ts-modules \
src/frontend/src/data/go-modules \
src/frontend/src/data/twoslash/aspire.d.ts

if git diff --cached --quiet; then
Expand Down
4 changes: 2 additions & 2 deletions src/frontend/config/sidebar/community.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -22,11 +22,11 @@ export const communityTopics: StarlightSidebarTopicsUserConfig = {
icon: 'heart',
items: [
{
label: 'Aspire Community',
label: 'Aspire community',
translations: {
da: 'Aspire-fællesskab',
de: 'Aspire-Gemeinschaft',
en: 'Aspire Community',
en: 'Aspire community',
es: 'Comunidad de Aspire',
fr: 'Communauté Aspire',
hi: 'Aspire समुदाय',
Expand Down
4 changes: 2 additions & 2 deletions src/frontend/config/sidebar/deployment.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@ export const deploymentTopics: StarlightSidebarTopicsUserConfig = {
icon: 'rocket',
items: [
{
label: 'Aspire Deployment',
label: 'Aspire deployment',
translations: {
da: 'Aspire-udrulning',
de: 'Aspire-Bereitstellung',
en: 'Aspire Deployment',
en: 'Aspire deployment',
es: 'Despliegue de Aspire',
fr: 'Déploiement Aspire',
hi: 'Aspire तैनाती',
Expand Down
25 changes: 23 additions & 2 deletions src/frontend/config/sidebar/reference.topics.ts
Original file line number Diff line number Diff line change
Expand Up @@ -23,11 +23,11 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
icon: 'seti:json',
items: [
{
label: 'Aspire Reference',
label: 'Aspire reference',
translations: {
da: 'Aspire-reference',
de: 'Aspire-Referenz',
en: 'Aspire Reference',
en: 'Aspire reference',
es: 'Referencia de Aspire',
fr: 'Référence Aspire',
hi: 'Aspire संदर्भ',
Expand Down Expand Up @@ -170,6 +170,27 @@ export const referenceTopics: StarlightSidebarTopicsUserConfig[number] = {
},
link: '/reference/api/typescript/',
},
{
label: 'Search Go APIs',
translations: {
da: "Søg i Go API'er",
de: 'Go APIs durchsuchen',
en: 'Search Go APIs',
es: 'Buscar API de Go',
fr: 'Rechercher les API Go',
hi: 'Go एपीआई खोजें',
id: 'Cari API Go',
it: 'Cerca API Go',
ja: 'Go APIを検索する',
ko: 'Go API 검색',
'pt-BR': 'Pesquisar APIs Go',
ru: 'Поиск Go API',
tr: "Go API'leri Arayın",
uk: 'Пошук Go API',
'zh-CN': '搜索 Go API',
},
link: '/reference/api/go/',
},
],
},
{
Expand Down
2 changes: 2 additions & 0 deletions src/frontend/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@
"test:unit:api-reference": "vitest run --config vitest.config.ts tests/unit/api-reference.vitest.test.ts",
"test:unit:api-markdown": "vitest run --config vitest.config.ts tests/unit/api-markdown.vitest.test.ts",
"test:unit:ts-api": "vitest run --config vitest.config.ts tests/unit/api-reference-routes.vitest.test.ts tests/unit/browser-storage.vitest.test.ts tests/unit/locale-routes.vitest.test.ts tests/unit/ts-api-routes.vitest.test.ts tests/unit/ts-api-search.vitest.test.ts tests/unit/ts-api-sidebar.vitest.test.ts",
"test:unit:go-api": "vitest run --config vitest.config.ts tests/unit/api-reference-routes.vitest.test.ts tests/unit/browser-storage.vitest.test.ts tests/unit/locale-routes.vitest.test.ts tests/unit/go-api-routes.vitest.test.ts tests/unit/go-api-route-catalog.vitest.test.ts tests/unit/go-api-search.vitest.test.ts tests/unit/go-api-sidebar.vitest.test.ts tests/unit/go-api-markdown.vitest.test.ts tests/unit/go-modules.vitest.test.ts tests/unit/go-modules-cache.vitest.test.ts tests/unit/go-member-card.vitest.test.ts tests/unit/go-doc-text.vitest.test.ts tests/unit/go-doc-refs.vitest.test.ts tests/unit/go-doc-text-component.vitest.test.ts",
"test:unit:twoslash-types": "vitest run --config vitest.config.ts tests/unit/twoslash-types-generator.vitest.test.ts",
"test:unit:twoslash-blocks": "vitest run --config vitest.config.ts tests/unit/twoslash-blocks.vitest.test.ts",
"test:unit:contracts": "vitest run --config vitest.config.ts tests/unit/analytics-script-contracts.vitest.test.ts tests/unit/redirects.vitest.test.ts",
Expand All @@ -57,6 +58,7 @@
"update:schemas": "tsx ./scripts/update-schemas.ts",
"update:integrations": "tsx ./scripts/update-integrations.ts",
"update:ts-api": "tsx ./scripts/update-ts-api.ts",
"update:go-api": "tsx ./scripts/update-go-api.ts",
"update:github-stats": "tsx ./scripts/update-github-stats.ts",
"update:release-contributors": "tsx ./scripts/update-release-contributors.ts",
"update:samples": "tsx ./scripts/update-samples.ts",
Expand Down
22 changes: 17 additions & 5 deletions src/frontend/scripts/normalize-generated-api-data.ts
Original file line number Diff line number Diff line change
@@ -1,9 +1,10 @@
/**
* normalize-generated-api-data.ts — Enforces Aspire terminology in the generated
* C#/TypeScript API reference JSON (`src/data/pkgs/*.json`, `src/data/ts-modules/*.json`).
* C#/TypeScript/Go API reference JSON (`src/data/pkgs/*.json`, `src/data/ts-modules/*.json`,
* `src/data/go-modules/*.json`).
*
* The C# API JSON is produced by the .NET `PackageJsonGenerator`; the TS API JSON
* by `AtsJsonGenerator`. Both copy XML/JSDoc documentation text verbatim from the
* The C# API JSON is produced by the .NET `PackageJsonGenerator`; the TS and Go API
* JSON by `AtsJsonGenerator`. All copy XML/JSDoc documentation text verbatim from the
* upstream packages, so deprecated Aspire terminology leaks into the committed
* data and trips the Forbidden Words CI check (see `.github/forbidden-words.json`).
* This pass rewrites only prose fields, reusing the single source of truth in
Expand All @@ -18,9 +19,10 @@
* escaped string content yields exactly the correctly-escaped normalized value.
*
* Usage:
* tsx ./scripts/normalize-generated-api-data.ts # both areas
* tsx ./scripts/normalize-generated-api-data.ts # all areas
* tsx ./scripts/normalize-generated-api-data.ts --pkgs # C# API only
* tsx ./scripts/normalize-generated-api-data.ts --ts-modules # TS API only
* tsx ./scripts/normalize-generated-api-data.ts --go-modules # Go API only
*/

import fs from 'fs';
Expand All @@ -33,6 +35,7 @@ const __dirname = path.dirname(fileURLToPath(import.meta.url));
const DATA_DIR = path.resolve(__dirname, '..', 'src', 'data');
export const PKGS_DIR = path.join(DATA_DIR, 'pkgs');
export const TS_MODULES_DIR = path.join(DATA_DIR, 'ts-modules');
export const GO_MODULES_DIR = path.join(DATA_DIR, 'go-modules');

// Per-line matcher (multiline) for EITHER a documentation node's `kind` marker
// OR a prose string field. Groups:
Expand Down Expand Up @@ -133,7 +136,8 @@ export function normalizeApiDir(dir: string): {

function main(): void {
const args = process.argv.slice(2);
const explicit = args.includes('--pkgs') || args.includes('--ts-modules');
const explicit =
args.includes('--pkgs') || args.includes('--ts-modules') || args.includes('--go-modules');
const targets: Array<{ label: string; dir: string }> = [];
if (!explicit || args.includes('--pkgs')) {
targets.push({
Expand All @@ -151,6 +155,14 @@ function main(): void {
: TS_MODULES_DIR,
});
}
if (!explicit || args.includes('--go-modules')) {
targets.push({
label: 'go-modules',
dir: process.env.ASPIRE_API_GO_MODULES_DIR
? path.resolve(process.env.ASPIRE_API_GO_MODULES_DIR)
: GO_MODULES_DIR,
});
}

let total = 0;
for (const { label, dir } of targets) {
Expand Down
107 changes: 107 additions & 0 deletions src/frontend/scripts/update-go-api.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,107 @@
/**
* update-go-api.ts — Regenerates Go API reference data.
*
* Runs the AtsJsonGenerator tool in Go mode against the aspire sdk dump output.
* Requires: dotnet SDK and aspire CLI.
* Set ASPIRE_CLI_PATH to use an installed Aspire CLI that is not on PATH.
*
* By default, reads the generated C# package JSON files and generates
* data for the matching Aspire.Hosting* and CommunityToolkit.Aspire.Hosting*
* package/version sets, the same sets that update-ts-api.ts generates.
*
* Optionally pass an Aspire repo clone path to discover packages from source:
* tsx ./scripts/update-go-api.ts /path/to/aspire
* ASPIRE_REPO_PATH=../../../aspire tsx ./scripts/update-go-api.ts
*
* Usage:
* tsx ./scripts/update-go-api.ts # auto-detect from C# package JSON
* tsx ./scripts/update-go-api.ts /path/aspire # from repo clone
*/

import { execFileSync } from 'child_process';
import { existsSync } from 'fs';
import { dirname, resolve } from 'path';
import { fileURLToPath } from 'url';

import { GO_MODULES_DIR, normalizeApiDir } from './normalize-generated-api-data';

const __dirname = dirname(fileURLToPath(import.meta.url));
// The generator script serves both languages; -Language selects the output.
const SCRIPT_PATH = resolve(
__dirname,
'..',
'..',
'tools',
'AtsJsonGenerator',
'generate-ts-api-json.ps1'
);

function getErrorMessage(error: unknown): string {
return error instanceof Error ? error.message : String(error);
}

function checkPrerequisite(cmd: string, args: string[], name: string): boolean {
try {
execFileSync(cmd, args, { stdio: 'pipe' });
return true;
} catch {
console.error(`❌ ${name} not found. Please install it first.`);
return false;
}
}

function main(): void {
const aspireRepoPath = process.argv[2] ?? process.env.ASPIRE_REPO_PATH;
const aspireCliPath = process.env.ASPIRE_CLI_PATH?.trim() || 'aspire';

if (!checkPrerequisite('dotnet', ['--version'], 'dotnet SDK')) {
process.exit(1);
}
if (!checkPrerequisite(aspireCliPath, ['--version'], 'Aspire CLI')) {
process.exit(1);
}

const psArgs = [
'-NoProfile',
'-ExecutionPolicy',
'Bypass',
'-File',
SCRIPT_PATH,
'-Language',
'go',
];
if (aspireRepoPath) {
const resolvedPath = resolve(aspireRepoPath);
if (!existsSync(resolvedPath)) {
console.error(`❌ Aspire repo not found at: ${resolvedPath}`);
process.exit(1);
}
console.log(`🔄 Generating Go API reference data from ${resolvedPath}...`);
psArgs.push('-AspireRepoPath', resolvedPath);
} else {
console.log('🔄 Generating Go API reference data from installed Aspire CLI...');
}

const outputDir = process.env.ASPIRE_API_GO_MODULES_DIR
? resolve(process.env.ASPIRE_API_GO_MODULES_DIR)
: GO_MODULES_DIR;
if (process.env.ASPIRE_API_GO_MODULES_DIR) {
psArgs.push('-OutputDir', outputDir);
}

try {
execFileSync('pwsh', psArgs, { stdio: 'inherit', cwd: resolve(__dirname, '..') });
console.log('✅ Go API reference data updated.');
} catch (error: unknown) {
console.error('❌ Generation failed:', getErrorMessage(error));
process.exit(1);
}

// The generated JSON copies upstream XML documentation verbatim, so enforce
// Aspire terminology before it is committed (see normalize-generated-api-data.ts).
console.log('🔄 Normalizing Aspire terminology in go-modules JSON...');
const { changes } = normalizeApiDir(outputDir);
console.log(`✅ Normalized ${changes} occurrence(s) in go-modules JSON.`);
}

main();
Loading
Loading