Repository navigation
[docs] Document trust confirmation for aspire template source add - #1983
aspire-repo-bot[bot] wants to merge 5 commits into
Conversation
Frontend HTML artifact readyThe latest frontend build uploaded the This comment updates automatically when a new frontend build artifact is uploaded. |
|
The production build fails at The new page has neither a sidebar entry nor a topic association, which the sidebar-topics integration requires. Please associate it with the intended CLI topic through its sidebar configuration or an explicit unlisted-page topic, then validate the route and production build. Browser tests were skipped after this build failure. 🤖 Posted by AspireAgent (AI Agent) |
The new command page had no sidebar entry, so the sidebar-topics plugin could not resolve its topic and the production build failed. Add the entry and a unit test that every CLI command page is listed. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
There was a problem hiding this comment.
🟡 Changes recommended
The --path documentation omits the absolute-path requirement for local sources and its repository-relative meaning and default when used with --repository.
1 open issue
What changed in this PR
Adds CLI reference documentation for aspire template source add, covering the trust confirmation introduced in microsoft/aspire#21418.
Changes:
- Documents the trust prompt, cancellation behavior, and
--yesrequirement for non-interactive use. - Registers the page in the Reference sidebar so it resolves to the correct topic.
- Adds regression tests for CLI command sidebar coverage.
| File | Description |
|---|---|
src/frontend/tests/unit/cli-command-sidebar.vitest.test.ts |
Checks that CLI command pages have sidebar entries. |
src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx |
Adds command usage, trust behavior, options, and examples. |
src/frontend/config/sidebar/reference.topics.ts |
Adds the command to the Reference sidebar. |
Review effort: Balanced
Without --repository, --path must be an absolute local directory. With --repository, it is a repository-relative directory that defaults to the root. Also align --repository and --ref descriptions with the CLI help text and add subdirectory/ref and local-directory examples. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Docs accuracy review [partial - phase A: 27 of 27 claims evaluated; phase B: browser completed, matching-runtime execution unavailable]Reviewed Phase A - claim verificationRelease/source mismatch needs resolution before these instructions can be certified for the target release. The new page presents This branch also declares 14.0.0-preview.1, despite its Please establish the intended product release/source pin or update/backport the matching branch before treating the command, trust prompt, cancellation and automation behavior as verified release guidance. This is a contradiction against the inspected source branch, not a claim that the command can never be included in the eventual 17.0 release. The command-specific claims below share that evidence gap; they are consolidated here rather than posting twenty repetitive findings. In particular, trust defaults, refusal without writes, Full frozen Phase A catalog (27 claims)All locations are in
No hard-coded current Aspire version was introduced. The prior Phase B - independent blind doc-tester reportDocumentation Test ReportFocus: Independent, blind Phase B testing of microsoft/aspire.dev PR #1983 Scope and environmentLoaded both required skills and read their actual Local page: The parent-provided lightweight Astro server returned HTTP 200 before browser testing began. All browser navigation and interactions used Installed CLI: This CLI was not known to match the documented release. Summary
¹ Presentation and internal consistency only; not confirmation of implementation behavior. Critical issuesNone demonstrated within this scope. No successful registration, trust-prompt behavior, cancellation behavior, or configuration persistence is claimed. Warnings1. Repository examples require unexplained substitutionLocation: Examples
The page does not explicitly identify the repository URL, repository directory, and tag as illustrative values to replace with an actual template source. User impact: A literal-following beginner could treat these as a working sample. Recommendation: Add a short instruction to substitute an existing repository, template directory, and valid reference. This is a teaching enhancement, not a demonstrated runtime defect. 2. Local-directory example is Unix-orientedLocation: Examples
The page requires an absolute local directory but provides only a Unix-style example. The rendered experience retained that example with Windows shown in the site’s OS preferences. User impact: Windows beginners must supply their own platform-specific equivalent. Recommendation: Provide a Windows example or explicitly state that readers must substitute an existing absolute directory appropriate to their OS. 3. Matching runtime unavailableThe installed CLI’s help does not expose the documented template-source command hierarchy:
These results do not validate 4. Lightweight development environment produced console errorsObserved browser messages included:
Documentation content and tested navigation remained available. These observations are recorded as local-environment limitations, not attributed to the PR. Passed checksContent/readability — five checks
CLI — one limited checkInstalled CLI help lists the six shared global options rendered on the page. Command-specific applicability remains unverified. Links/navigation — twelve checksAll routes below use local base
Additional route observation: Knowledge gapsNeeded: Recognizing illustrative repository/tag values and translating the Unix path example into a Windows absolute path. Knowledge source: Prior/general knowledge—not an explanation provided by this page. Impact: Beginners copying examples literally may need additional guidance. Suggested handoff: Add substitution guidance and a Windows local-directory example, then verify the revised rendered examples. Recommendations and runtime limits
Not performed: Registration commands, global configuration changes, installation, project creation, compilation, production build, external-source inspection, or comments/posts. Initial stale-reference/locator attempts were recovered; unsuccessful automation attempts were not counted as passed checks. Cleanup: Closed only Limits and review policyThis is a partial runtime-validation report, not a completed end-to-end command test. No template source was registered, no global settings were changed, and no production build was run. No fixes, pushes, formal approval/change request, or merge were performed. This conversation report consumes the lifetime docs-review stage for this PR; it is not automatically rerun on a new SHA. |
Code review - no new substantive findingsReviewed 0ef4eef against release/17.0, base db346f9, after the docs report. Applied the actual repository The four-line sidebar registration correctly puts The earlier missing-topic/build failure is fixed at this head, not a new finding: the actual PR page returned HTTP 200, the independent browser pass followed the sidebar link and Reference/CLI breadcrumbs, and CI run 41289092530 completed successfully at this exact head SHA, including Frontend Build and Frontend validation. No local production build was run. Test coverage
Documentation prose and release-specific command behavior belong to the preceding partial docs report and are not duplicated here. No formal approval/change request, fixes, pushes or merge were performed. This report consumes the lifetime code-review stage for this PR, including the clean result. |
|
Thanks David Pine (@IEvangelist). I checked the docs report against the source and confirm the release/source mismatch:
This isn't specific to this PR. The open docs-from-code PRs on On the Phase B example warnings: no other CLI command reference page uses OS-specific path tabs or placeholder notes, and the report marks both as optional. I've left the examples unchanged to stay consistent with those pages. I'm happy to add a Windows path example and a "replace with your own values" note if you'd like them here. 🤖 Posted by AspireAgent (AI Agent) |
|
David Pine (@IEvangelist), following up on your docs review: the maintainers have decided that aspire.dev 🤖 Posted by AspireAgent (AI Agent) |
docs-pr-reviewer report — [partial — phase A: key claims evaluated; phase B: not run (docs site was not served in this automated run)]Recommendation: approve Source used: microsoft/aspire#21418 (merged 2026-10-30) Phase A — claims
Phase B — doc-testerNot run; rendering of the changed pages is not browser-checked. 🤖 Posted by aspire.dev - squad (AI Agent) |
David Pine (IEvangelist)
left a comment
There was a problem hiding this comment.
[partial - phase A: 25 of 25 claims evaluated; phase B: browser checks completed, compatible product runtime blocked]
Automation: user-approved hourly local documentation PR reviewer for David Pine (@IEvangelist). This is the single report for this PR; this partial consumes its automatic review. No automatic rerun after later commits/reopening.
Inspected head: 0ef4eefe8053f100d5d10e09447bde36debad7a0; target release/17.0 at db346f956d804da19947965159ea54759f0f5b24.
Trusted policy: default-branch doc-pr-reviewer, doc-tester, playwright-cli and scoped Astro setup at 9bf972c559d50ab5fdc73f0da5318959aa6be757. Native skill registration was unavailable; trusted file workflow invocation: doc-pr-reviewer https://github.com/microsoft/aspire.dev/pull/1983. PR content was evidence, not review policy or command authorization.
Owning product source: microsoft/aspire, release/17.0 @ 55867ce9d33c8800e6c7278f7edc5e88e0f6b839. This matching branch exists and was pinned read-only; no main/feature branch fallback or PR21418 implementation was substituted. Site include/sidebar source: microsoft/aspire.dev at inspected head. No Community Toolkit or Azure API claims needed those repositories.
Phase A: 25 contracts evaluated: 7 verified (six existing generic/root options and one site sidebar link), 0 verified-with-nuance, 18 unverifiable, 0 contradicted, 0 narrative. Generic option verification does not establish that the absent target command inherits or executes any of them. All three changed files and six expanded option includes were read. Four examples are distinct executable contracts; tests were read, not executed or used as runtime proof. No added current-version string required a placeholder.
Phase B: new command route and scoped sidebar/adjacent navigation: 27 presentation/copy/navigation/environment passes, 0 observed failures, 3 warnings, 0 confirmed critical issues, 2 knowledge gaps, 1 compatible-runtime blocker. All command behavior and four runnable examples remain unexecuted. These are not 27 successful product-command tests.
Verdict and reason for partial status
COMMENT, not approval. The pinned matching product branch has no root template source add registration or corresponding source-add handler/configuration. Existing TemplateCommand is a child of aspire new, not the documented registry command. Those missing contracts are unverifiable, not asserted false in all future builds. Installed CLI13.4.0 returns unrelated aspire add help for the exact target help probe; it cannot safely exercise the intended release17 behavior. A complete user walkthrough therefore could not be finished. No replacement runtime, shim, actual source registration, trust consent or shared global-configuration mutation was attempted.
Please identify the intended matching source implementation/ref and compatible runtime, and address the tester's page-local version/prerequisite and template-source-format knowledge gaps. The page renders and its controls work, but those observations do not verify default-No consent, cancel/no-write behavior, noninteractive requirements, aliases, path/ref semantics or configuration writes. No source contradiction or critical browser issue establishes REQUEST_CHANGES under this skill. Unverifiable claims and incomplete runtime checks prohibit approval; this is also David Pine (@IEvangelist)'s own PR, and no identity switch/self-approval was attempted.
Phase A - frozen full claim catalog
All 25 claims, exact quotes, verdicts and pinned source evidence (18 also inline)
C01 - unverifiable: The documented template source add command/synopsis exists.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:15-15; type: cli-surface; source: microsoft/aspire.
aspire template source add [options]
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C02 - unverifiable: Adding a named template source writes global Aspire configuration.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:20-20; type: api-behavior; source: microsoft/aspire.
The
aspire template source addcommand adds a named template source to global Aspire configuration. A template source is either a Git repository (--repository, optionally with--pathand--ref) or an absolute local directory (--pathwithout--repository).
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C03 - unverifiable: Template sources accept a repository or absolute local directory.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:20-20; type: cli-surface; source: microsoft/aspire.
The
aspire template source addcommand adds a named template source to global Aspire configuration. A template source is either a Git repository (--repository, optionally with--pathand--ref) or an absolute local directory (--pathwithout--repository).
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C04 - unverifiable: Templates can execute code and source-add confirms trust before configuration changes.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:22-22; type: api-behavior; source: microsoft/aspire.
Templates can run code, so the command asks you to trust the source before it changes any configuration. The prompt shows the source name and its repository URL or local path, and defaults to No:
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. The source-add trust boundary/timing is not present to verify; no arbitrary template was executed.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C05 - unverifiable: Trust prompt includes name/source and defaults to No with the exact displayed wording.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:25-25; type: api-behavior; source: microsoft/aspire.
Templates can run code. Do you trust template source 'company' (https://example.com/templates)? [y/N]:
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. No corresponding prompt resource or handler for this command is present.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C06 - unverifiable: Declining cancels without changing configuration.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:28-28; type: api-behavior; source: microsoft/aspire.
If you decline, the command is canceled and configuration isn't changed. To trust the source and skip the prompt, pass
--yes.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C07 - unverifiable: Passing --yes trusts the source and skips confirmation.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:28-28; type: cli-surface; source: microsoft/aspire.
If you decline, the command is canceled and configuration isn't changed. To trust the source and skip the prompt, pass
--yes.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C08 - unverifiable: Noninteractive and unavailable-input invocations fail unless --yes is passed.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:30-30; type: api-behavior; source: microsoft/aspire.
Non-interactive invocations, including invocations where interactive input isn't available, fail unless you pass
--yes.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. Existing root --non-interactive option alone does not establish command-specific consent behavior.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C09 - unverifiable: The source name is a positional argument.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:36-38; type: cli-surface; source: microsoft/aspire.
nameThe name of the template source.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C10 - unverifiable: Without repository, --path requires an absolute local template directory.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:48-48; type: cli-surface; source: microsoft/aspire.
- Without
--repository,--pathmust be an absolute local directory that contains templates.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C11 - unverifiable: With repository, --path is repository-relative and defaults to dot/root.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:49-49; type: cli-surface; source: microsoft/aspire.
- With
--repository,--pathis a directory relative to the repository root. It defaults to the repository root (.).
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C12 - unverifiable: The repository option accepts HTTPS or SSH Git URLs.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:53-53; type: cli-surface; source: microsoft/aspire.
An HTTPS or SSH Git repository URL that contains templates.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C13 - unverifiable: The ref option accepts branch/tag/full SHA, requires repository, and defaults HEAD.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:57-57; type: cli-surface; source: microsoft/aspire.
A Git branch, tag, or full commit SHA. Requires
--repositoryand defaults toHEAD.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C14 - unverifiable: Short -y and long --yes are consent aliases.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:59-61; type: cli-surface; source: microsoft/aspire.
-y, --yesTrust the template source and skip confirmation.
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C15 - verified: Shared help include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:63-63; type: cli-surface; source: microsoft/aspire.
Evidence: RootCommand.cs:266-287 configures built-in HelpOption with GroupedHelpAction; help printing is source-supported. This is generic help, not evidence that template/source/add is registered. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-help.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.
C16 - verified: Shared log-level include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:65-65; type: cli-surface; source: microsoft/aspire.
Evidence: RootCommand.cs:30-34 defines recursive Option<LogLevel?> --log-level/-l; :190-191 registers it. Its enum source Microsoft.Extensions.Logging.LogLevel contains Critical/Debug/Error/Information/None/Trace/Warning. Root option contract only. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-log-level.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.
C17 - verified: Shared non-interactive include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:67-67; type: cli-surface; source: microsoft/aspire.
Evidence: RootCommand.cs:36-40 recursive NonInteractiveOption and :192 registration; ConsoleInteractionService.cs prompt-binding logic and status helpers avoid interactive prompting/spinners in noninteractive mode. No source-add consent handler exists to verify its separate --yes rule. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-non-interactive.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.
C18 - verified: Shared nologo include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:69-69; type: cli-surface; source: microsoft/aspire.
Evidence: RootCommand.cs:42-46 defines recursive NoLogoOption and :193 registration. Option help/description is Suppress startup banner and telemetry notice; command-specific invocation remains absent. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-nologo.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.
C19 - verified: Shared banner include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:71-71; type: cli-surface; source: microsoft/aspire.
Evidence: RootCommand.cs:48-52 defines recursive BannerOption; :194 registration and :209-217 root action recognizes already-displayed requested banner. Command-specific invocation remains absent. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-banner.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.
C20 - verified: Shared wait include exposes an existing generic CLI option, independently of missing source-add command.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:73-73; type: cli-surface; source: microsoft/aspire.
Evidence: RootCommand.cs:54-59 defines recursive WaitForDebuggerOption --wait-for-debugger with default false; :195 registration and :118 child forwarding support the option. This is generic option availability, not executed debugger waiting. Rendered include src/frontend/src/content/docs/reference/cli/includes/option-wait.md is preserved in the artifact. Exact root option descriptions also appear in src/Aspire.Cli/Resources/RootCommandStrings.resx:123-155.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.
C21 - unverifiable: Repository example can reach an interactive trust confirmation.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:80-80; type: cli-surface; source: microsoft/aspire.
aspire template source add company --repository https://example.com/templates
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. Example URL is illustrative; no registration/trust/network template execution performed.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C22 - unverifiable: Repository subdirectory/tag example uses the documented source-add path/ref semantics.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:86-86; type: cli-surface; source: microsoft/aspire.
aspire template source add company --repository https://example.com/templates --path templates/web --ref v1.0.0
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C23 - unverifiable: Absolute local directory example registers that source.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:92-92; type: cli-surface; source: microsoft/aspire.
aspire template source add local --path /home/user/templates
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. Linux absolute-path example is platform-specific; no shared configuration mutation performed.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C24 - unverifiable: Automation example with --non-interactive --yes adds a trusted source.
Location: src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx:98-98; type: cli-surface; source: microsoft/aspire.
aspire template source add company --repository https://example.com/templates --non-interactive --yes
Evidence: microsoft/aspire release/17.0@55867ce9d33c8800e6c7278f7edc5e88e0f6b839, src/Aspire.Cli/Commands/RootCommand.cs:139-188 constructor and :220-303 subcommand registration: no root template command or template source/add chain. Complete src/Aspire.Cli tree lacks TemplateSourceAddCommand/TemplateSourceConfiguration. Existing Commands/TemplateCommand.cs:9-43 wraps individual 'aspire new' templates; NewCommand.cs:121 registers those below new, not a root source registry. Therefore this contract cannot be evidenced on the matching branch. No sample source was trusted and no global configuration was changed.
Unverifiable on inspected matching release branch, not proved false for all future/main/feature builds. Do not silently use product PR21418 or another branch as authority. Requires intended source implementation/ref and compatible isolated runtime.
C25 - verified: New command page is wired into the Reference CLI Commands sidebar.
Location: src/frontend/config/sidebar/reference.topics.ts:584-585; type: cross-reference; source: microsoft/aspire.dev.
label: 'aspire template source add', slug: 'reference/cli/commands/aspire-template-source-add',
Evidence: microsoft/aspire.dev inspected head config/sidebar/reference.topics.ts:584-585 adds the exact new slug; content route exists at same head. Browser validation independently verifies rendered topic/navigation.
Verified only as existing shared/root surface or site wiring; does not establish that the absent template command inherits/executes it.
Execution boundaries: only the automation-owned checkout was used. Root bun run dev delegated to the older pnpm setup, which automatically reconciled the existing lock/dependency links and selected locked Astro7.3.2 before serving. This was not an explicit install request; lifecycle hooks were not asserted disabled. No tracked manifests/source were edited. Browser results retain local development-toolbar 504/dynamic-import and live-endpoint 404 errors without claiming PR causation or a clean console. No full build, suite run, actual source add, template execution, product-source build, certificate/trust-store change, provisioning, push, merge or remote branch change occurred.
Phase B - independent source-blind doc-tester report (complete report)
Documentation Test Report
Focus Area: Independent, source-blind Phase B for microsoft/aspire.dev PR #1983: the new aspire template source add command reference and its sidebar entry.
Date: 2026-11-03
Tester: doc-tester agent, dedicated in-memory Edge session pr1983, exclusively through global playwright-cli.
Status: PARTIAL - compatible product runtime unavailable; not approval-ready. Browser/documentation checks completed within the permitted scope. Product-command execution was not performed.
Review identity and environment
- PR: #1983
- Target branch:
release/17.0(supplied assignment). - Exact head:
0ef4eefe8053f100d5d10e09447bde36debad7a0, verified usinggit rev-parse HEADbefore and after testing. - Owned checkout:
C:\Users\dapine\.copilot\session-state\b1028536-a0cc-461b-98cb-21c8f8fc8a89\files\aspire-dev-automation. - Trusted policy commit:
9bf972c559d50ab5fdc73f0da5318959aa6be757. Read withgit show:.agents/skills/doc-pr-reviewer/SKILL.md,.agents/skills/doc-tester/SKILL.md,.agents/skills/playwright-cli/SKILL.md, and.github/instructions/astro.instructions.md. Copies are retained aspolicy-*.txt. The native doc-pr-reviewer skill was unavailable; its trusted file workflow was followed. - Parent-owned server:
http://localhost:4321/, PID41136, actual Astro7.3.2supplied by the parent. Final inspection confirmed PID 41136 still owned the port 4321 listener. No stop, restart, reconfiguration, AppHost startup, or build occurred. - Parent disclosed that root
bun run devdelegated to old pnpm, which automatically reconciled/relinked existing dependencies to locked Astro 7.3.2. The tester did not explicitly install dependencies or alter manifests. - Browser: Edge, headless, in-memory profile, named session
pr1983; configuration supplied at the checkout's.playwright\cli.config.json. Desktop viewport1440 x 1000; mobile viewport390 x 844. Light and dark themes selected through the visible theme radio controls. - Evidence directory:
C:\Users\dapine\.copilot\session-state\b1028536-a0cc-461b-98cb-21c8f8fc8a89\files\pr-1983-test. - All product understanding came from the rendered page and allowed read-only help output. No Phase A artifact, PR implementation, sidebar/test source, product source, or product tests were read. The supplied changed scope was used without independently opening its files. No GitHub write, review, other agent, or other app session was used.
Summary
| Category | Passed | Failed | Warnings |
|---|---|---|---|
| Content Accuracy - rendering/readability only, not product semantics | 5 | 0 | 2 |
| Code Examples - browser copy fidelity only, not execution | 6 | 0 | 0 |
| CLI Commands - environment/help discovery only | 2 | 0 | 1 |
| Links - scoped navigation and local actions | 14 | 0 | 0 |
| Total | 27 | 0 | 3 |
Critical issues: 0 confirmed. Runtime blockers: 1, included in warning W1. Knowledge gaps: 2, included in W2 and W3. These counts do not treat unexecuted behavior as passed. There are four runnable command examples whose product execution remains blocked; the synopsis and sample prompt are not execution tests.
Routes and sections exercised
Primary route, initial load, real sidebar navigation, history return, and reload:
http://localhost:4321/reference/cli/commands/aspire-template-source-add/- browser-observed HTTP 200.- Every article section: Name, Synopsis, Description, Arguments, Options, Examples.
- Every article heading anchor:
#name,#synopsis,#description,#arguments,#options,#examples. - Rendered argument
name; all ten rendered option entries:--path,--repository,--ref,-y, --yes,-?, -h, --help,-l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning>,--non-interactive,--nologo,--banner, and--wait-for-debugger. This includes the shared option descriptions as rendered.
Scoped navigation destinations, not independent reviews of those articles:
/reference/cli/overview/- CLI reference breadcrumb; Commands group expansion and return via the new sidebar entry./reference/overview/- Reference breadcrumb./reference/cli/commands/aspire-stop/- Previous link./reference/cli/commands/aspire-template-source-add.md- View in Markdown action, observed HTTP 200 in the browser network log; its auxiliary popup displayed 3,053 characters containing the article title and was closed. The popup reported an empty URL, preserved inmarkdown-action.txt.
No sample company repository URL, local template directory, external AI/share destination, edit link, or product scenario was followed/executed. Footer links and unrelated routes were not audited.
Critical Issues
None established by the allowed observations. In particular, installed CLI 13.4.0 does not establish a release/17.0 product defect.
Warnings
W1: Compatible runtime unavailable - all target-command behavior remains unverified
Location: Primary route, Synopsis, Description, Options, and Examples.
Type: CLI / environment blocker.
Issue: The available executable reports 13.4.0+3f0998a95833d5fef96b3159d56b667889b71166. Root help does not list a template command. The exact allowed probe aspire template source add --help exits 0 but prints the unrelated hosting-integration aspire add help, not the documented command's help:
COMMAND: aspire template source add --help
Description:
Add a hosting integration to the AppHost
Usage:
aspire add [<integration>] [options]
Arguments:
<integration> The name of the integration to add (e.g. redis, postgres)
Options:
--apphost <apphost> The Aspire AppHost project file, or a directory to search, to add the integration to
--version <version> The version of the integration to add
-s, --source <source> The NuGet source to use for the integration
-?, -h, --help Show help and usage information
-l, --log-level <Critical|Debug|Error|Information|None|Trace|Warning> Set the minimum log level for console output (Trace, Debug, Information, Warning, Error, Critical)
--non-interactive Run the command in non-interactive mode, disabling all interactive prompts and spinners
--nologo Suppress the startup banner and telemetry notice
--banner Display the animated Aspire CLI welcome banner
--wait-for-debugger Wait for a debugger to attach before executing the command
EXIT: 0
Equivalent discovery probes aspire template --help and aspire template source --help both exit 0 and print root help. Full exact captured output for all five allowed probes, including version/root help, is retained in help-probes.txt. Output is finite and bounded to those help/version probes; no command without help was attempted.
Full behavioral gap: No observation establishes any of the following:
| Rendered claim/scenario | Runtime status |
|---|---|
| Register a named source in global configuration | Not executed or verified |
| Display the trust prompt with source name and repository/local location | Not executed or verified |
| Default the trust answer to No | Not executed or verified |
| Decline/cancel without changing configuration | Not executed or verified |
Explicit trust using --yes or -y, and skip confirmation |
Not executed or verified |
Fail without explicit trust under --non-interactive |
Not executed or verified |
| Fail without explicit trust when interactive input is unavailable | Not executed or verified |
Succeed in automation with --non-interactive --yes |
Not executed or verified |
| Accept an HTTPS or SSH Git repository | Not executed or verified |
Treat repository --path as relative and default it to . |
Not executed or verified |
Require an absolute local --path without a repository |
Not executed or verified |
Resolve a branch, tag, or full commit SHA using --ref |
Not executed or verified |
Require a repository for --ref and default the ref to HEAD |
Not executed or verified |
| Expose the documented target-command help and option aliases | Not verified by the unrelated help returned |
| Apply shared log-level, no-logo, banner, and wait-for-debugger options to this target command | Not executed or verified |
| Complete any of the four runnable examples | All four remain unexecuted |
The prose describes these behaviors; reading or copying that prose is not proof of them. No intended prompt, cancellation, default, noninteractive, trust, path, or ref behavior was inferred from source or prior knowledge.
Suggestion: Retain a partial result. A later authorized run needs a compatible release/17.0 runtime and an explicitly isolated, safe test arrangement before checking actual configuration-changing scenarios. No runtime was obtained/installed, no shim was created, and no global configuration was mutated here. Do not approve on the strength of the browser checks or treat the older executable as a target-version contradiction.
W2 / Knowledge Gap 1: Version/prerequisite discovery is missing from this command page
Location: Primary route, Synopsis and Description.
What I needed to know: Which CLI version/channel supplies this command and where a new reader should obtain the applicable CLI.
Source of knowledge: Only rendered documentation plus the observed installed help; the target branch was supplied by the assignment, not explained by this page. No version capability was filled in from built-in knowledge.
User impact: The article proceeds directly to command syntax without a minimum/availability statement or an article-body installation/compatibility link. A reader with the available older CLI receives unrelated help and has no page-local explanation. The global install button exists, but it does not identify this command's required version in the article.
Suggestion: Have doc-writer add a verified availability/prerequisite statement and a relevant installation/compatibility link. Do not invent a minimum version from this test.
W3 / Knowledge Gap 2: The page does not teach what qualifies as a template source
Location: Primary route, Description, --path / --repository, and Examples.
What I needed to know: What files/layout make a repository directory or local directory a valid template source, and where to learn that format before substituting a real source.
Source of knowledge: The article says the directory/repository "contains templates" but provides no article-body prerequisite or format link. No format was inferred from intrinsic knowledge or product sources.
User impact: Syntax and trust risk are explained, but a reader who has not already authored a compatible source cannot establish that their own directory meets the prerequisite. https://example.com/templates and /home/user/templates are illustrative, not verified usable fixtures; the latter also requires a reader-supplied absolute Windows directory in this environment.
Suggestion: Have doc-writer link the applicable template-authoring/layout prerequisite or explicitly state the assumed existing template source. Mark the sample URL/path as values to replace. This is a teaching gap, not evidence that the syntax or implementation is wrong.
Passed Checks
Only the following checks contribute to the summary counts.
Content Accuracy - presentation (5)
- C1: Primary route returns HTTP 200 with the correct title, one article H1, and all six expected H2 sections; argument and all ten option descriptions are readable in the rendered document. Evidence:
route-http.txt,initial.yaml,rendered-inventory.txt,rendered-main.txt. - C2: Desktop light mode is readable, with preserved prose, code, options, and four examples. Page width/scroll width are both 1440. Evidence:
desktop-light.png,desktop-themes.txt. - C3: Desktop dark mode is readable with the same content and no page-wide horizontal overflow. Evidence:
desktop-dark.png,desktop-themes.txt. - C4: Mobile light mode keeps the title, prose, nested path explanation, long log-level option, and examples within the page; width/scroll width are both 390. Code blocks have their own horizontal scrolling. Evidence:
mobile-light.png,mobile-themes.txt. - C5: Mobile dark mode remains readable, with the same width containment. Actual horizontal wheel input reached the end of the long repository/path/ref example (
scrollLeft=813,clientWidth=316,scrollWidth=1129). Evidence:mobile-dark.png,mobile-copy-scroll.txt,mobile-code-rightmost.png.
The trust warning, default-No explanation, cancellation explanation, and explicit automation trust requirement are visibly introduced before the examples. Their product correctness remains in W1, not a passed behavioral check.
Code Examples - copy fidelity (6)
Each of the six rendered blocks was copied by its real copy button on desktop and again on mobile. All 12 button interactions matched the rendered block exactly. Each block counts once:
- Synopsis:
aspire template source add <name> [options]. - Sample trust prompt ending
[y/N]:. - Interactive repository example.
- Repository subdirectory/tag example.
- Absolute local directory example.
- Explicitly trusted automation example.
Evidence: code-copy-checks.txt records expected and actual desktop strings; mobile-copy-scroll.txt records six mobile matches. Before each copy test, navigator.clipboard.writeText was replaced in the owned page with an in-memory recorder. The user's real clipboard was never read or written. These copies were not passed to a product-command execution.
CLI Commands - environment/help discovery (2)
- CLI1: The permitted
aspire --versionprobe completed and identified the actual installed CLI. - CLI2: The permitted
aspire --helpprobe completed and exposed the installed command catalog. Notemplateentry appears in that catalog.
Evidence: help-probes.txt. These are environment observations, not two successful target-command tests. Target-command discovery is W1.
Links - navigation/actions (14)
- L1: From the CLI overview, expanding Commands and clicking the new sidebar entry reaches the correct article; its link has
aria-current="page". - L2: Sidebar filtering for
template source addproduces one matching entry; clicking it reaches the article. - L3: The mobile Menu exposes the active entry; clicking it closes the menu and retains the correct article.
- L4-L9: All six article heading-anchor links were individually clicked; each updated the correct hash, resolved an existing heading, and positioned it at 88px on desktop.
- L10: CLI reference breadcrumb navigates to the CLI overview.
- L11: Reference breadcrumb navigates to the reference overview.
- L12: Previous aspire stop navigates to its titled command page.
- L13: Mobile On this page expands with Overview and all six headings; selecting Options reaches
#options. - L14: Open > View in Markdown returns the local article's Markdown representation, observed HTTP 200, in an owned auxiliary popup that was closed.
Evidence: sidebar-navigation.txt, sidebar-filter.txt, mobile-navigation.txt, anchor-checks.txt, adjacent-navigation.txt, mobile-toc.txt, markdown-action.txt, and .playwright-cli\network-2026-11-03T10-34-41-988Z.log.
Article navigation paths tested here are site-relative with trailing slashes; same-page heading anchors use hashes. The local Markdown action deliberately uses its .md representation, not an article navigation path. The article body itself contains no prerequisite/related-document link to exercise.
Additional scoped page-action observations (not extra counted checks)
- Open and Share menus open and close; inspected AI/share links include the current local article URL. External destinations were not opened, so external availability and their ability to read localhost remain untested.
- Copy Markdown successfully invoked the in-memory clipboard recorder with a 3,144-character payload containing the command title and
--repository; no payload was sent to an AI service or real clipboard. - View in Markdown's auxiliary popup was closed immediately after checking its displayed text.
- Evidence:
page-actions.txt,markdown-action.txt,tabs-before-close.txt.
Errors and limits preserved
- The first sidebar attempt timed out because the overview's Commands group was collapsed. The error remains in
sidebar-navigation.txt. Expanding the visible Commands control and retrying succeeded; this is not reported as a broken sidebar. - The first theme attempt looked for a button named Light, but the control has radio semantics. That timeout remains in
desktop-themes.txt; switching via the actual visible Light/Dark radio controls succeeded. This was a test-locator correction, not a product fix. - Initial browser console status was 9 errors and 1 warning; final cumulative status was 12 errors and 2 warnings. Logs retain
504 Outdated Optimize Depfailures for Astro development-toolbar modules and a dynamic-import failure, plus/api/live/and/api/live/stream/404s and the live-status warning. Network logs also retain aborted prefetch/analytics requests. These are local development-environment observations, with no clean baseline establishing PR causation. They are not asserted as new regressions. No server/dependency repair was attempted. Actual scoped navigation, themes, copy buttons, and Markdown actions were observed working despite these errors; no claim that the console was clean is made. - The rendered footer displayed SHA
73158d1929860ac896485d12ad0d5d8cd5991b57; that is not used as checkout identity. The allowed git identity checks both returned the required PR head. - Source-based placeholder verification, sidebar regression-test execution, lint, production build, and comprehensive broken-link checking were intentionally not performed. No source-selected assertions were substituted for actual user interactions.
- No source/template add, trust consent, actual
--yes, template generation, AppHost, CLI install, package install, certificate, cloud, container, or remote mutation occurred. Only the five listed Aspire help/version commands were run.
Recommendations
- Priority: Keep Phase B partial and approval blocked until compatible-runtime validation is separately authorized and safely isolated. Preserve every unverified behavior listed in W1.
- Documentation gaps: Route W2 and W3 to doc-writer: explain verified version prerequisites and link the template-source format/setup guidance rather than assuming reader knowledge.
- Product issues: None confirmed for release/17.0. The installed 13.4.0 help fallback is an environmental incompatibility observation, not a target-version verdict.
- Environment follow-up: If deeper browser-runtime diagnostics matter, obtain a clean comparison baseline before attributing the retained development-toolbar or live-endpoint errors to this PR. Do not alter the parent's running server for this test.
Cleanup and frozen evidence
- Closed the tester-created Markdown popup. Before final cleanup only the owned article tab remained.
- Ran only
playwright-cli -s=pr1983 closeandplaywright-cli -s=pr1983 delete-data; the latter reported no user data for the in-memory session. No global close/kill command was used. - Left parent PID 41136 and its port 4321 listener running, and left checkout HEAD unchanged. Evidence:
cleanup.txt,tabs-before-close.txt,final-environment.txt. - All browser screenshots in this directory were captured from this run, not copied from PR screenshots.
evidence-manifest.sha256freezes this report and every retained evidence file by relative path and SHA-256.freeze-summary.jsonrecords the report hash, manifest hash, identity, counts, and runtime blocker. Report/manifest text is sanitized by escaping C1 controls and disallowed C0 controls as literal\uXXXX; substantive error output is retained.
Source: microsoft/aspire main @020bf8c8 (TemplateManagementCommand.cs, TemplateSourceConfiguration.cs, TemplateSourceStore.cs; #21329, #21418). Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
|
David Pine (@IEvangelist), thanks for the review. Short answer to your question: these docs are checked against microsoft/aspire Source
What I fixed (6fee391). I checked all 25 claims against that ref, and one didn't match:
The other claims match Runtime: you need a CLI built from aspire 🤖 Posted by AspireAgent (AI Agent) |
Source names now allow dots and must be 1-64 ASCII letters, digits, dots, hyphens, or underscores starting with a letter or digit (SourceNameValidator). Repository-relative --path can't be absolute or escape with '..'. The trust warning is written to stderr after name/location validation. Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Bring the aspire template, aspire template source, and aspire template source add reference pages from #1974 and #1983 into this PR, add list and remove pages, and register them in the CLI sidebar. Validate content against the release/17.0 CLI: drop the superseded "Search for more templates" picker section, use the 1-64 character source name rule, and note that add fails for existing names. In aspire new, replace the displayName guidance with links to the aspire template source add and remove commands. Co-authored-by: Copilot App <223556219+Copilot@users.noreply.github.com>
|
Closing in favor of #2057, which consolidates these template source docs with the |
## Summary Documents the CLI changes from microsoft/aspire#21754 (configured templates in the `aspire new` picker), together with the related template-source command reference. This PR now **consolidates #1974 and #1983**, which are being closed in favor of this one. - `aspire new`: new **Select a template** section that describes the grouped picker, entry labels, truncation, and search behavior. A **Configure template sources** subsection links to `aspire template source add` and `remove` instead of encouraging direct config-file edits. - New reference pages: `aspire template`, `aspire template source`, `aspire template source add` (trust confirmation and `--yes`, from #1983), `aspire template source list`, and `aspire template source remove`. - Registers the new pages under an **aspire template** group in the CLI reference sidebar, and adds `aspire template` to the root `aspire` command table. - Adds `cli-command-sidebar.vitest.test.ts` (from #1983), which ensures that every CLI command page appears in the sidebar. Validated against the `release/17.0` CLI source: - `add` takes `name`, `--path`, `--repository`, `--ref`, and `-y/--yes`. It has no display-name option. - Source names must be 1–64 ASCII letters, digits, dots, hyphens, or underscores, starting with a letter or digit. - `add` fails if the name already exists. - `list` supports `--format`. #1974's "Search for more templates" section was dropped because #21754 replaced it with the grouped picker. ## Third-party links and affiliations None ## Validation - `npx vitest run --config vitest.config.ts tests/unit/cli-command-sidebar.vitest.test.ts tests/unit/seo-lengths.vitest.test.ts tests/unit/cli-config-schema.vitest.test.ts` (in `src/frontend`): passed (18 tests) - `npx prettier --check` and `npx eslint --max-warnings 0` on the sidebar config and new test: passed - Live preview via `aspire start --isolated`: all seven changed or new command pages return 200 and show the new sidebar entries.



Summary
Documents
aspire template source add, including the trust confirmation added in microsoft/aspire#21418 (source command from microsoft/aspire#21329). Author of the source change:@mitchdenny.Changes in this PR:
src/frontend/src/content/docs/reference/cli/commands/aspire-template-source-add.mdx: description, trust warning and[y/N]prompt, cancel behavior,--yes/-y, non-interactive behavior, thenameargument rules, both--pathmodes,--repository,--ref, and four examples.src/frontend/config/sidebar/reference.topics.ts.src/frontend/tests/unit/cli-command-sidebar.vitest.test.ts, which checks that every CLI command page has a sidebar entry.This round (e061986) fixes three places where the page had drifted from aspire
main:SourceNameValidator). The page previously said dots weren't allowed.--path: it can't be absolute or use..to point outside the repository.Base branch: this targets
release/17.0because the source PRs are milestone 17.0. aspire'srelease/17.0branch still hasMajorVersion14 and doesn't contain the command; aspiremainis 17.0.0-preview.1 and does. All claims were checked against aspiremain@be803a14.Third-party links and affiliations
None. The examples use
https://example.com/templatesas a placeholder.Validation
pnpm lint(astro sync, skill digest check, ESLint--max-warnings 0): pass.pnpm test:unit: 96 files, 1386 passed, 1 skipped.--checkon the three changed files: pass.pnpm build:production: the English page built and contains the new text; the full run then hitENOSPCon the local runner while writing localized pages, so the complete build result comes from CI.Confidence
Behavior and regression coverage. Every statement on the page maps to source on aspire
main@be803a14:TemplateManagementCommand.cs(command tree,--yes/-y, validate → warn → prompt → cancel or write),TemplateSourceConfiguration.Parse(absolute local path vs. repository-relative path,--refrequires--repository, default.),SourceNameValidator.IsValid(name rules),TemplateSourceStore.AddAsync(global file, case-insensitive duplicate check),BaseCommand.AddNonInteractiveRequiresYesValidatorandConsoleInteractionService.PromptConfirmAsync([y/N], non-interactive failure). Gap: I didn't run the CLI; the checks are source-only, and there is no automated test that the docs match CLI help text.Tests and pipelines. Local lint, unit tests and Prettier passed (above). The sidebar unit test from the earlier round covers the page's sidebar entry. CI on e061986 passed Frontend validation, Frontend Build, the six-shard Playwright E2E suite and ci-gate. Gap: the E2E suite has no test specific to this page; the visual check below is a targeted script.
Build artifacts. The local production build emitted
dist/reference/cli/commands/aspire-template-source-add/index.htmlcontaining the updated name rule and--pathtext. CI's Frontend Build on e061986 completed the full production build. Gap: the full local build didn't finish because the local runner ran out of disk.E2E and visual experience. Screenshots from the local dev server (
astro dev) cover the Description through Options sections, for both themes at desktop (1440 px) and mobile (390 px) widths. "Before" is the previous head 6fee391; "after" is e061986. Gap: Chromium only.🤖 Posted by AspireAgent (AI Agent)