feat: host aspire.config.json JSON Schema at versioned aspire.dev URLs (#743)

* feat: host aspire.config.json schema at versioned aspire.dev URLs

- Add src/data/schemas/ with index.json and initial aspire-config.13.2.3.schema.json
- Add scripts/update-schemas.ts to fetch + version schemas from microsoft/aspire
- Add src/utils/cli-config-schema.ts and cli-config-schema-types.ts utility modules
- Add Astro endpoints: schema.json.ts (latest) and schema/[version].json.ts (versioned)
- Add tests/unit/cli-config-schema.vitest.test.ts with 10 schema integrity tests
- Update package.json: add update:schemas script and test:unit:cli-config-schema

Agent-Logs-Url: https://github.com/microsoft/aspire.dev/sessions/da65b293-931e-4c52-a1cb-0f9f082d8c39

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

* fix: address code review feedback on schema utils and versioned endpoint

Agent-Logs-Url: https://github.com/microsoft/aspire.dev/sessions/da65b293-931e-4c52-a1cb-0f9f082d8c39

Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>

* feat: add JSON Schema support for aspire.config.json and update middleware for schema redirection

Co-authored-by: Copilot <copilot@github.com>

* feat: enhance schema handling with atomic index writes and add e2e tests for schema endpoints

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: IEvangelist <7679720+IEvangelist@users.noreply.github.com>
Co-authored-by: David Pine <david.pine@microsoft.com>
Co-authored-by: Copilot <copilot@github.com>

Author: 3 people

src/frontend/package.json

@@ -29,21 +29,23 @@
     "astro": "pnpm git-env && astro",
     "test": "pnpm test:unit && pnpm test:e2e",
     "test:all": "pnpm lint && pnpm test",
-    "test:unit": "pnpm test:unit:contracts && pnpm test:unit:components && pnpm test:unit:docs && pnpm test:unit:api-markdown && pnpm test:unit:ts-api && pnpm test:unit:twoslash-types && pnpm test:unit:structured-data",
+    "test:unit": "pnpm test:unit:contracts && pnpm test:unit:components && pnpm test:unit:docs && pnpm test:unit:api-markdown && pnpm test:unit:ts-api && pnpm test:unit:twoslash-types && pnpm test:unit:structured-data && pnpm test:unit:cli-config-schema",
     "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/ts-api-routes.vitest.test.ts tests/unit/ts-api-search.vitest.test.ts",
     "test:unit:twoslash-types": "vitest run --config vitest.config.ts tests/unit/twoslash-types-generator.vitest.test.ts",
     "test:unit:contracts": "vitest run --config vitest.config.ts tests/unit/analytics-script-contracts.vitest.test.ts",
     "test:unit:components": "vitest run --config vitest.config.ts tests/unit/custom-components.vitest.test.ts tests/unit/site-tour.vitest.test.ts",
     "test:unit:docs": "vitest run --config vitest.config.ts tests/unit/filetree-format.vitest.test.ts",
     "test:unit:structured-data": "vitest run --config vitest.config.ts tests/unit/structured-data.vitest.test.ts",
+    "test:unit:cli-config-schema": "vitest run --config vitest.config.ts tests/unit/cli-config-schema.vitest.test.ts",
     "test:e2e:api-markdown": "playwright test --config playwright.api-markdown.config.mjs",
     "test:e2e": "playwright test",
     "test:e2e:install": "playwright install chromium",
     "test:e2e:serve": "pnpm git-env && pnpm check-data && astro dev --host 127.0.0.1 --port 4321",
     "lint": "pnpm git-env && pnpm exec astro sync && eslint . --max-warnings 0",
     "format": "prettier -w --cache --plugin prettier-plugin-astro .",
     "update:all": "pnpm update:integrations && pnpm update:github-stats && pnpm update:samples",
+    "update:schemas": "tsx ./scripts/update-schemas.ts",
     "update:integrations": "tsx ./scripts/update-integrations.ts",
     "update:ts-api": "tsx ./scripts/update-ts-api.ts",
     "update:github-stats": "tsx ./scripts/update-github-stats.ts",

src/frontend/scripts/update-schemas.ts

@@ -0,0 +1,163 @@
+/**
+ * Fetches the aspire-config JSON Schema from microsoft/aspire and saves a
+ * versioned copy under src/data/schemas/, then updates the version index.
+ *
+ * Usage:
+ *   pnpm update:schemas                     # fetch latest non-prerelease
+ *   pnpm update:schemas -- --version 13.2.3 # pin to a specific version tag
+ */
+
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+
+import { fetchWithProxy as fetch } from './fetch-with-proxy';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const FRONTEND_ROOT = path.resolve(__dirname, '..');
+
+const ASPIRE_REPO = 'microsoft/aspire';
+const SCHEMA_SOURCE_PATH = 'extension/schemas/aspire-config.schema.json';
+const SCHEMAS_DIR = path.join(FRONTEND_ROOT, 'src', 'data', 'schemas');
+const INDEX_FILE = path.join(SCHEMAS_DIR, 'index.json');
+
+const SITE_ORIGIN = 'https://aspire.dev';
+const SCHEMA_BASE_PATH = '/reference/cli/configuration/schema';
+
+interface GitHubRelease {
+  tag_name: string;
+  prerelease: boolean;
+  draft: boolean;
+}
+
+interface SchemaIndex {
+  latest: string;
+  versions: string[];
+}
+
+function getErrorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+function schemaFileName(version: string): string {
+  return `aspire-config.${version}.schema.json`;
+}
+
+function schemaFilePath(version: string): string {
+  return path.join(SCHEMAS_DIR, schemaFileName(version));
+}
+
+/** Fetch the latest non-prerelease, non-draft tag from microsoft/aspire. */
+async function fetchLatestReleaseVersion(): Promise<string> {
+  const url = `https://api.github.com/repos/${ASPIRE_REPO}/releases`;
+  const headers: Record<string, string> = {
+    'User-Agent': 'aspire-schema-updater',
+    Accept: 'application/vnd.github.v3+json',
+  };
+  if (process.env.GITHUB_TOKEN) {
+    headers['Authorization'] = `token ${process.env.GITHUB_TOKEN}`;
+  }
+
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch releases: ${res.status} ${res.statusText}`);
+  }
+
+  const releases = (await res.json()) as GitHubRelease[];
+  const stable = releases.find((r) => !r.prerelease && !r.draft);
+  if (!stable) {
+    throw new Error('No stable release found in microsoft/aspire');
+  }
+
+  // Tag names are like "v13.2.3" — strip the leading "v"
+  return stable.tag_name.replace(/^v/, '');
+}
+
+/** Fetch the raw schema JSON from microsoft/aspire at the given tag. */
+async function fetchSchemaAtTag(tag: string): Promise<Record<string, unknown>> {
+  const rawUrl =
+    `https://raw.githubusercontent.com/${ASPIRE_REPO}/v${tag}/${SCHEMA_SOURCE_PATH}`;
+  const res = await fetch(rawUrl, {
+    headers: { 'User-Agent': 'aspire-schema-updater' },
+  });
+  if (!res.ok) {
+    throw new Error(`Failed to fetch schema at tag v${tag}: ${res.status} ${res.statusText}`);
+  }
+  return (await res.json()) as Record<string, unknown>;
+}
+
+/** Read the current index, or return an empty one if it doesn't exist yet. */
+function readIndex(): SchemaIndex {
+  if (!fs.existsSync(INDEX_FILE)) {
+    return { latest: '', versions: [] };
+  }
+  return JSON.parse(fs.readFileSync(INDEX_FILE, 'utf-8')) as SchemaIndex;
+}
+
+/** Write the index atomically by writing a temp file and renaming into place. */
+function writeIndex(index: SchemaIndex): void {
+  fs.mkdirSync(SCHEMAS_DIR, { recursive: true });
+
+  const contents = JSON.stringify(index, null, 2) + '\n';
+  const tempFile = path.join(
+    SCHEMAS_DIR,
+    `${path.basename(INDEX_FILE)}.${process.pid}.${Date.now()}.tmp`,
+  );
+
+  try {
+    fs.writeFileSync(tempFile, contents, 'utf-8');
+    fs.renameSync(tempFile, INDEX_FILE);
+  } catch (error) {
+    if (fs.existsSync(tempFile)) {
+      fs.unlinkSync(tempFile);
+    }
+    throw error;
+  }
+}
+
+async function main(): Promise<void> {
+  // Resolve the target version
+  const versionArg = process.argv.indexOf('--version');
+  let version: string;
+  if (versionArg >= 0 && process.argv[versionArg + 1]) {
+    version = process.argv[versionArg + 1].replace(/^v/, '');
+    console.log(`📌 Using pinned version: ${version}`);
+  } else {
+    console.log(`🔍 Fetching latest release from ${ASPIRE_REPO}…`);
+    version = await fetchLatestReleaseVersion();
+    console.log(`✅ Latest stable release: ${version}`);
+  }
+
+  const outFile = schemaFilePath(version);
+
+  if (fs.existsSync(outFile)) {
+    console.log(`ℹ️  Schema for v${version} already exists at ${path.relative(FRONTEND_ROOT, outFile)}`);
+  } else {
+    console.log(`⬇️  Fetching schema from microsoft/aspire @ v${version}…`);
+    const schema = await fetchSchemaAtTag(version);
+
+    // Update $id to point to the versioned aspire.dev URL
+    schema['$id'] = `${SITE_ORIGIN}${SCHEMA_BASE_PATH}/${version}.json`;
+
+    fs.mkdirSync(SCHEMAS_DIR, { recursive: true });
+    fs.writeFileSync(outFile, JSON.stringify(schema, null, 2) + '\n', 'utf-8');
+    console.log(`✅ Saved schema to ${path.relative(FRONTEND_ROOT, outFile)}`);
+  }
+
+  // Update the index
+  const index = readIndex();
+
+  if (!index.versions.includes(version)) {
+    index.versions.push(version);
+    index.versions.sort((a, b) => a.localeCompare(b, undefined, { numeric: true }));
+  }
+  index.latest = version;
+
+  writeIndex(index);
+  console.log(`✅ Updated ${path.relative(FRONTEND_ROOT, INDEX_FILE)} — latest: ${version}, versions: [${index.versions.join(', ')}]`);
+}
+
+main().catch((error: unknown) => {
+  console.error('❌ Error:', getErrorMessage(error));
+  process.exit(1);
+});

src/frontend/src/content/docs/reference/cli/configuration.mdx

@@ -22,10 +22,11 @@ focuses on the settings surfaced through `aspire config`.
 
 ## Example `aspire.config.json`
 
-```json title="aspire.config.json"
+```json title="aspire.config.json" {2}
 {
+  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
   "appHost": {
-    "path": "./src/MyApp.AppHost/MyApp.AppHost.csproj"
+    "path": "./apphost.ts"
   },
   "channel": "staging",
   "features": {
@@ -36,6 +37,83 @@ focuses on the settings surfaced through `aspire config`.
 }
 ```
 
+:::tip[The highlighted `$schema` property is additive]
+By default, the configuration files do not include the `$schema` property. You can add it manually to enable editor support for JSON Schema.
+:::
+
+## JSON Schema support
+
+Aspire publishes a JSON Schema for `aspire.config.json` so editors can provide
+completions, validation, and hover documentation while you edit the file.
+
+Two URLs are available:
+
+- **Latest** — always points to the newest published schema:
+
+  ```text title="Latest schema URL"
+  https://aspire.dev/reference/cli/configuration/schema.json
+  ```
+
+  [`schema.json`](/reference/cli/configuration/schema.json)
+
+- **Versioned** — pins to a specific Aspire release (for example, `13.2.3`):
+
+  ```text title="Versioned schema URL"
+  https://aspire.dev/reference/cli/configuration/schema/13.2.3.json
+  ```
+
+  [`schema/13.2.3.json`](/reference/cli/configuration/schema/13.2.3.json)
+
+### Reference the schema from `aspire.config.json`
+
+Most editors automatically pick up a schema when the JSON file declares a
+top-level `$schema` property:
+
+```json title="aspire.config.json" ins={2}
+{
+  "$schema": "https://aspire.dev/reference/cli/configuration/schema.json",
+  "appHost": {
+    "path": "./apphost.ts"
+  }
+}
+```
+
+:::note
+Use the versioned URL (for example, `.../schema/13.2.3.json`) when you want
+schema behavior to stay stable alongside a pinned Aspire CLI version, and use
+the unversioned `schema.json` when you want to always validate against the
+latest release.
+:::
+
+### Associate the schema in Visual Studio Code
+
+If you prefer not to commit a `$schema` property, you can associate the schema
+with `aspire.config.json` in your user or workspace `settings.json`:
+
+```json title=".vscode/settings.json"
+{
+  "json.schemas": [
+    {
+      "fileMatch": ["aspire.config.json"],
+      "url": "https://aspire.dev/reference/cli/configuration/schema.json"
+    }
+  ]
+}
+```
+
+VS Code also honors the `$schema` property automatically, so either approach
+enables completions and validation in the built-in JSON language service.
+
+### Other editors
+
+Any editor or tool that understands JSON Schema Draft 2020-12 can consume the
+hosted schema — including JetBrains IDEs (**Settings → Languages & Frameworks →
+Schemas and DTDs → JSON Schema Mappings**), Neovim with
+[`jsonls`](https://github.com/microsoft/vscode-json-languageservice), and
+command-line validators such as
+[`ajv`](https://ajv.js.org/) or [`check-jsonschema`](https://github.com/python-jsonschema/check-jsonschema).
+Point the tool at either the latest or versioned URL above.
+
 ## Settings surfaced by `aspire config`
 
 Use `aspire config list` to see the values that are currently set, and use
@@ -44,11 +122,11 @@ can configure.
 
 <Include relativePath="reference/cli/includes/config-settings-table.md" />
 
-<Aside type="tip">
-  Some feature flags shown by `aspire config list --all` may correspond to
-  preview, migration, or hidden functionality. Treat the output of your
-  installed CLI as the authoritative source for what can be configured.
-</Aside>
+:::tip
+Some feature flags shown by `aspire config list --all` may correspond to
+preview, migration, or hidden functionality. Treat the output of your
+installed CLI as the authoritative source for what can be configured.
+:::
 
 ## Toggle preview feature experiences