Split host-only Community Toolkit integration docs

[IEvangelist]

Important

This PR is ready for review, but it should be rebased and merged after #1376 because the series shares redirects, mappings, sidebar entries, and logo behavior.

Summary

• Replace the standalone Deno, Java, k6, Perl, PowerShell, Rust, and SQL Database Projects pages with 14 focused get-started and host pages; these host-only integrations intentionally have no connect pages.
• Add seven legacy redirects and reconcile the sidebar, package mappings, and generated icon safelist.
• Document the verified C# and TypeScript AppHost APIs with complete synchronized runnable examples, while precisely identifying only the source-backed ATS export exceptions.
• Keep every hero logo contained and use theme-specific Deno artwork.

Validation

• Verified source, tests, generated API baselines, [AspireExport] metadata, and TypeScript modules against CommunityToolkit/Aspire commit b9d40479805b74ea20b7dc57cb659d46e6f11c43.
• Fresh external C# and TypeScript AppHost samples restored and compiled/type-checked for all seven integrations.
• Focused redirect, metadata, SEO, twoslash, mapping, and data checks pass; all 14 routes and seven redirects pass browser checks.
• Combined landing rehearsal passes 8 focused suites/153 tests, 248 logo renders, and 199 synchronized AppHost tab groups with zero browser failures or console errors.

No local pnpm build was run.

[Copilot]

Pull request overview

This PR restructures several Community Toolkit host-only integration docs (Deno, Java, k6, Perl, PowerShell, Rust, SQL Database Projects) by replacing the prior single-page entries with paired get-started and AppHost reference pages, and then updates routing/mapping so the gallery, sidebar, and legacy links point at the new structure.

Changes:

• Replaces legacy single-page integration docs with new *-get-started.mdx and *-host.mdx pages for the listed host-only integrations (and removes the old landing pages).
• Updates docs routing infrastructure: integration docs mapping (integration-docs.json), sidebar topics, and redirects to preserve old URLs.
• Adjusts icon safelist entries.

Reviewed changes

Copilot reviewed 25 out of 25 changed files in this pull request and generated 17 comments.

Show a summary per file

File	Description
src/frontend/src/data/integration-docs.json	Updates package→docs href mapping to point at new get-started routes.
src/frontend/src/content/docs/integrations/frameworks/rust/rust-host.mdx	Adds Rust AppHost reference page.
src/frontend/src/content/docs/integrations/frameworks/rust/rust-get-started.mdx	Adds Rust get-started page.
src/frontend/src/content/docs/integrations/frameworks/rust.mdx	Removes legacy Rust single-page doc.
src/frontend/src/content/docs/integrations/frameworks/powershell/powershell-host.mdx	Adds PowerShell AppHost reference page.
src/frontend/src/content/docs/integrations/frameworks/powershell/powershell-get-started.mdx	Adds PowerShell get-started page.
src/frontend/src/content/docs/integrations/frameworks/powershell.mdx	Removes legacy PowerShell single-page doc.
src/frontend/src/content/docs/integrations/frameworks/perl/perl-host.mdx	Adds Perl AppHost reference page.
src/frontend/src/content/docs/integrations/frameworks/perl/perl-get-started.mdx	Adds Perl get-started page.
src/frontend/src/content/docs/integrations/frameworks/perl.mdx	Removes legacy Perl single-page doc.
src/frontend/src/content/docs/integrations/frameworks/java/java-host.mdx	Adds Java AppHost reference page.
src/frontend/src/content/docs/integrations/frameworks/java/java-get-started.mdx	Adds Java get-started page.
src/frontend/src/content/docs/integrations/frameworks/java.mdx	Removes legacy Java single-page doc.
src/frontend/src/content/docs/integrations/frameworks/deno/deno-host.mdx	Adds Deno AppHost reference page (theme-aware logo).
src/frontend/src/content/docs/integrations/frameworks/deno/deno-get-started.mdx	Adds Deno get-started page (theme-aware logo).
src/frontend/src/content/docs/integrations/frameworks/deno-apps.mdx	Removes legacy Deno single-page doc.
src/frontend/src/content/docs/integrations/devtools/sql-projects/sql-projects-host.mdx	Adds SQL Database Projects AppHost reference page.
src/frontend/src/content/docs/integrations/devtools/sql-projects/sql-projects-get-started.mdx	Adds SQL Database Projects get-started page.
src/frontend/src/content/docs/integrations/devtools/sql-projects.mdx	Removes legacy SQL Database Projects single-page doc.
src/frontend/src/content/docs/integrations/devtools/k6/k6-host.mdx	Adds k6 AppHost reference page.
src/frontend/src/content/docs/integrations/devtools/k6/k6-get-started.mdx	Adds k6 get-started page.
src/frontend/src/content/docs/integrations/devtools/k6.mdx	Removes legacy k6 single-page doc.
src/frontend/config/sidebar/integrations.topics.ts	Updates sidebar to nest each integration under get-started + host reference entries.
src/frontend/config/redirects.mjs	Adds legacy redirects from old slugs to new get-started pages.
src/frontend/.starlight-icons/safelist.json	Removes several safelisted icons (folder/file-type ids).

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[aspire-repo-bot]

Frontend HTML artifact ready

The latest frontend build uploaded the frontend-dist artifact for PR #1377. Use the VS Code button below to open this PR with GitHub Artifacts Explorer and browse the built HTML locally.

This comment updates automatically when a new frontend build artifact is uploaded.

[IEvangelist]

📋 Docs-accuracy review (doc-pr-reviewer)

Verdict: COMMENT — non-blocking. The documentation is accurate against source and renders cleanly; only benign scoping nuances are noted below.

Summary

Source of truth (Phase A)	CommunityToolkit/Aspire @ b9d40479805b74ea20b7dc57cb659d46e6f11c43 (the commit this PR states it verified against)
Docs head reviewed	microsoft/aspire.dev PR #1377 @ c33bbc676ba751b0d67e56e8f104fd642f728b35
Claims extracted	87 — ✅ 69 verified · 🟡 18 verified-with-nuance · ❔ 0 unverifiable · ❌ 0 contradicted
Phase B (doc-tester)	14 new pages + 7 redirects exercised on a local pnpm dev server → 0 critical, 0 warnings

No contradicted or unverifiable claims were found, so there are no inline change requests. Core Aspire APIs referenced by the samples (WithReference, WaitFor, WithHttpEndpoint, WithBindMount, WithExternalHttpEndpoints, TS AppHost generation, etc.) live in microsoft/aspire rather than the Community Toolkit and were treated as standard/core — most of the "verified-with-nuance" verdicts are just that attribution note, not a documentation defect.

---

Phase A — Claim verification

0 contradicted · 0 unverifiable. Every C#/TypeScript API, package id, CLI command, config key, endpoint/port, redirect, and mapping was matched string-for-string against the Community Toolkit source at the pinned commit. A sample of the more specific claims was independently re-verified against source, e.g.:

• k6 — K6Port = 6565, .WithHttpEndpoint(targetPort: K6Port, …), .WithHttpHealthCheck("/health"), WithK6OtlpEnvironment copying OTEL_* → K6_OTEL_*. ✔️
• Java — [AspireExport("addJavaAppWithJar")] overload + JarPath ([AspireExport(ExposeProperties = true)]); WithMavenBuild/WithGradleBuild defaults clean package / clean build. ✔️
• PowerShell — defaults PSLanguageMode.ConstrainedLanguage, minRunspaces = 1, maxRunspaces = 5, with [AspireExportIgnore] on the PSLanguageMode overload (matches the "not TS-exported; string bridge validates enum names" note). ✔️
• SQL Database Projects — AddSqlProject, AddSqlPackage<TPackage> (C#-only generic), WithDacpac, WithDacDeployOptions / WithConfigureDacDeployOptions (C#-only), WithSkipWhenDeployed. ✔️
• Perl — WithLocalLib env (PERL5LIB, PERL_LOCAL_LIB_ROOT, PERL_MM_OPT, PERL_MB_OPT), WithPerlCertificateTrust (SSL_CERT_FILE, PERL_LWP_SSL_CA_FILE, MOJO_CA_FILE), WithPerlbrew. ✔️
• Host-only / no-connect claim — confirmed: the CTK src/ tree ships only hosting packages for k6, SqlDatabaseProjects, Deno, Java, Perl, PowerShell and Rust; there is no companion CommunityToolkit.Aspire.<X> client package, so "these host-only integrations intentionally have no connect pages" holds.
• Config/data — all 7 redirects, the sidebar topic slugs, and the integration-docs.json package→route mappings point at the 14 new files, which all exist.

🟡 Nuance worth a glance (non-blocking)

• frameworks/perl/perl-get-started.mdx (~L51-57): the prerequisites imply cpanm is needed for project dependencies. Per source, project-dependency installation via Carton does not require cpanm — you may want to phrase it as "cpanm is required for WithCpanMinus, WithLocalLib, or non-Carton project dependencies."
• A few "verified-with-nuance" items assert an absence (e.g., PowerShell scripts have "no WithWorkingDirectory", host-only integrations emit "no publish artifact"). These are correct as evidenced by the absence of the corresponding API / publish callback in source, rather than by an explicit source statement — flagging only so the wording isn't read as an explicitly-documented guarantee.

Full per-claim catalog (87 claims, with path:line evidence)

Source read: CommunityToolkit/Aspire @ b9d40479805b74ea20b7dc57cb659d46e6f11c43.

k6-get-started.mdx — k6-gs-01 ✅ (K6Resource.cs:11-22, K6BuilderExtensions.cs:58-63) · k6-gs-02 🟡 (container/script verified; reference config is core) · k6-gs-03 ✅ (CommunityToolkit.Aspire.Hosting.k6.csproj) · k6-gs-04 🟡 (AddK6/WithScript verified; WithBindMount core) · k6-gs-05 🟡 (endpoint/script/OTLP verified; service discovery core)

k6-host.mdx — k6-host-01 🟡 (package + aspire add k6 mapping) · k6-host-02 ✅ (K6BuilderExtensions.cs:42-63, image docker.io/grafana/k6) · k6-host-03 ✅ (port 6565, /health, OTLP, PrimaryEndpoint) · k6-host-04 ✅ (enableBrowserExtensions, port) · k6-host-05 ✅ (WithScript VUs/duration validation, K6PublicApiTests.cs) · k6-host-06 ✅ (WithK6OtlpEnvironment) · k6-host-07 🟡 (normal container; publishing core)

sql-projects-get-started.mdx — sql-gs-01 ✅ (SqlProjectPublishService.cs) · sql-gs-02 ✅ (host-only deployment task) · sql-gs-03 ✅ (MSBuild.Sdk.SqlProj/Microsoft.Build.Sql, Projects.*) · sql-gs-04 🟡 (CTK APIs verified; AddSqlServer/AddDatabase core) · sql-gs-05 ✅

sql-projects-host.mdx — sql-host-01 🟡 · sql-host-02 ✅ · sql-host-03 ✅ · sql-host-04 ✅ (relative DACPAC resolution; generic overload C#-only) · sql-host-05 ✅ (AddSqlPackage<TPackage>, default tools/<id>.dacpac, not TS-exported) · sql-host-06 ✅ (WithDacDeployOptions / WithConfigureDacDeployOptions C#-only) · sql-host-07 ✅ (WithSkipWhenDeployed, checksum, TS dacpacPath()/dacDeployOptionsPath()/skipWhenDeployed()) · sql-host-08 ✅ (withConnectionReference; needs Database/Initial Catalog) · sql-host-09 ✅ (Running→Finished exit 0; Deploy command)

deno-get-started.mdx — deno-gs-01 ✅ (AddDenoApp/AddDenoTask, deno run/deno task) · deno-gs-02 ✅ · deno-gs-03 🟡 · deno-gs-04 🟡 (permissionFlags verified; listener app-owned) · deno-gs-05 ✅

deno-host.mdx — deno-host-01 ✅ · deno-host-02 ✅ (AddDenoApp signature, default ../<name>, DENO_ENV) · deno-host-03 ✅ (taskName="start", deno task <taskName>) · deno-host-04 ✅ (WithDenoPackageInstallation, installer <name>-deno-install) · deno-host-05 🟡 (executable + service discovery; endpoint/health core) · deno-host-06 🟡 (installer run-mode/excluded; publish inferred from absence)

java-get-started.mdx — java-gs-01 ✅ · java-gs-02 ✅ · java-gs-03 ✅ (WithMavenGoal, SERVER_PORT) · java-gs-04 ✅

java-host.mdx — java-host-01 ✅ · java-host-02 ✅ (mvnw/gradlew defaults; reject JAR+Maven/Gradle) · java-host-03 ✅ (addJavaAppWithJar, JarPath, jarPath(), setJarPath()) · java-host-04 ✅ (WithMavenBuild/WithGradleBuild defaults, WithWrapperPath) · java-host-05 ✅ (WithJvmArgs→JAVA_TOOL_OPTIONS, WithOtelAgent) · java-host-06 ✅ (AddJavaContainerApp) · java-host-07 🟡 (SERVER_PORT/command verified; endpoints core) · java-host-08 ✅ (deprecated compat APIs not TS-exported)

perl-get-started.mdx — perl-gs-01 ✅ · perl-gs-02 🟡 (Carton path can skip cpanm) · perl-gs-03 ✅ (AddPerlScript, WithLocalLib) · perl-gs-04 ✅

perl-host.mdx — perl-host-01 ✅ · perl-host-02 ✅ (AddPerlScript/AddPerlApi/AddPerlModule/AddPerlExecutable) · perl-host-03 ✅ · perl-host-04 🟡 · perl-host-05 ✅ (local::lib env vars) · perl-host-06 ✅ (WithPerlCertificateTrust env vars) · perl-host-07 ✅ (WithPackage/WithCpanMinus/WithProjectDependencies) · perl-host-08 ✅ (WithCarton+WithPackage mutually exclusive; WithPerlbrew Linux-only) · perl-host-09 ✅ (Dockerfile publish, Carton stages)

powershell-get-started.mdx — ps-gs-01 ✅ · ps-gs-02 ✅ (aspire add communitytoolkit-powershell; in-process, no pwsh) · ps-gs-03 ✅ (AddPowerShell, AddScript) · ps-gs-04 ✅

powershell-host.mdx — ps-host-01 ✅ · ps-host-02 ✅ (ConstrainedLanguage, 1..5; PSLanguageMode TS-ignored) · ps-host-03 🟡 (no WithWorkingDirectory — by absence) · ps-host-04 ✅ (pool WithReference → read-only PS variable) · ps-host-05 🟡 (auto parent wait verified; wait APIs core) · ps-host-06 ✅ (Stop-script action; no endpoints/health)

rust-get-started.mdx — rust-gs-01 ✅ · rust-gs-02 ✅ (aspire add communitytoolkit-rust) · rust-gs-03 🟡 (AddRustApp verified; endpoint APIs core) · rust-gs-04 ✅

rust-host.mdx — rust-host-01 ✅ · rust-host-02 ✅ (AddRustApp → cargo run) · rust-host-03 ✅ (args after cargo run) · rust-host-04 ✅ (AddBaconApp → bacon run) · rust-host-05 🟡 (OTLP/no-custom-commands verified; endpoints/references core) · rust-host-06 ✅ (Dockerfile publish; build context = working dir)

Config/data — config-01 ✅ (7 redirects → existing targets) · config-02 ✅ (sidebar slugs exist) · config-03 ✅ (integration-docs.json package→route) · config-04 ✅ (safelist parses) · config-05 ✅ (no connect pages — hosting-only in CTK src/)

---

Phase B — doc-tester results (blind rendering validation)

Served PR #1377 head (c33bbc67) from a local pnpm dev server and navigated exclusively with a browser (no source code consulted). Routes exercised: all 14 new pages and all 7 redirects, plus tab-synchronization and theme-logo behavior.

Category	Passed	Failed	Warnings
Page renders (HTTP 200 + correct <title>)	14	0	0
Legacy redirects (301 → new *-get-started route)	7	0	0
Hero integration logos load (non-zero dimensions)	14	0	0
Community Toolkit badge present	14	0	0
Twoslash / expressive-code error markers	0 found	—	0
Broken images (non-SVG)	0	—	0
Console errors	0	—	0

Critical issues

None.

Warnings

None.

Passed checks

• All 14 pages render with the expected title, the ⭐ Community Toolkit badge, a logical heading hierarchy, and their hero logo (e.g. k6 374×362, Perl camel 1500×1500, PowerShell/Rust/Deno/SQL 100×100, Java 54×100).
• All 7 redirects return 301 to the correct new route (deno-apps → deno/deno-get-started, java/perl/powershell/rust → …/*-get-started, k6 → k6/k6-get-started, sql-projects → sql-projects/sql-projects-get-started).
• Synchronized AppHost tabs work — the four aspire-lang (C# / TypeScript) tab groups on the Deno host page all switched to TypeScript when one was toggled, while the independent aspire-install group stayed put.
• Theme-aware Deno artwork is wired via the theme-image class (light/dark variants), matching the PR's "theme-specific Deno artwork" note.
• No console errors on any page; no expressive-code/twoslash error markers; no broken raster images.
• Internal cross-links between each integration's get-started and host page (and to /get-started/*, /reference/cli/*, /deployment/*, /integrations/overview/) resolve to real routes.
• Get-started prose reads well for a newcomer: intro → "how it works" → prerequisites → first resource (C#/TypeScript) → see also.

Recommendations

• Minor (mirrors the Phase A nuance): on the Perl get-started page, clarify that cpanm is only required for WithCpanMinus/WithLocalLib/non-Carton project dependencies.

Knowledge gaps / scope limitations

• Runtime execution was not performed. This review validated rendering, structure, links, redirects, and tab behavior in the browser, and verified every API/config claim against Community Toolkit source (Phase A). It did not re-run the actual AppHost samples end-to-end, which would require installing the Deno, JDK+Maven/Gradle, Perl+cpanm/Carton, PowerShell SDK, Rust/Cargo+Bacon, k6, and SqlPackage toolchains. The PR body states fresh external C#/TypeScript samples were restored and compiled/type-checked for all seven integrations; that build evidence was taken as-is and not independently reproduced here.

---

_{Automated review via the doc-pr-reviewer skill (Phase A: claim verification vs. source · Phase B: doc-tester browser validation). No files in the PR, the docs repo, or any source clone were modified.}