[docs] Add aspire ls command reference documentation

[aspire-repo-bot]

Documents changes from microsoft/aspire#17688

Author: @aspire-repo-bot (backport authored by bot; original fix by @davidfowl team)

Target branch: Targeting release/13.4 based on the source PR milestone 13.4 (target_resolution: exact_match).

Why this PR is needed

The aspire ls command (which discovers AppHost project candidates) had five bugs fixed in microsoft/aspire#17688 (backport of #17631 to release/13.4). The key user-facing behavioral change is:

• Streaming output ordering: aspire ls --format json --stream previously applied a sort after writing candidates to stdout (which had no effect on the streamed output). This was a bug — the sort only reordered the in-memory list, not what was already written. The fix clarifies that stream output is emitted in arrival order from parallel discovery (not sorted). Non-streaming --format json output remains sorted by path.
• Configuration validation errors: New error messages (ConfiguredAppHostPathHasInvalidCharacters, ConfiguredAppHostPathMustBeString, ConfigurationFileMustBeJsonObject) were added for invalid aspire.config.json / aspireSettings.json configuration.
• macOS path deduplication: Symlink resolution prevents duplicate entries (e.g. /tmp/... vs /private/tmp/... on macOS).

The aspire ls command had no documentation page on aspire.dev — this PR adds it.

Changes

New file

• src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx — New command reference page for aspire ls

Updated file

• src/frontend/config/sidebar/reference.topics.ts — Added aspire ls entry to the CLI commands sidebar (alphabetically between aspire init and aspire logs)

Documentation summary

The new page covers:

• Description of what aspire ls does (parallel AppHost discovery)
• Table output format (PATH, LANGUAGE, STATUS columns)
• --format json snapshot output (sorted by path)
• --format json --stream NDJSON streaming output (arrival order, not sorted)
• Guidance for sorting streamed output: aspire ls --format json --stream | jq -s 'sort_by(.path)'
• --all flag
• Configuration file path validation behavior
• Examples for all major use cases

Generated by PR Documentation Check for issue #17688 · ● 38.8M · ◷

[Copilot]

Pull request overview

Adds new Aspire CLI reference documentation for aspire ls, reflecting behavior changes from microsoft/aspire#17688 and wiring the page into the CLI commands sidebar.

Changes:

• Added a new command reference page for aspire ls (formats, streaming behavior, options, examples).
• Added aspire ls to the CLI commands sidebar list.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
src/frontend/src/content/docs/reference/cli/commands/aspire-ls.mdx	New aspire ls command reference page (discovery, output formats, streaming details, examples).
src/frontend/config/sidebar/reference.topics.ts	Adds aspire ls entry to the CLI commands sidebar.

---

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

[IEvangelist]

Automated docs-accuracy review — aspire ls reference page

Phase A — Claims verification

• Source-of-truth: microsoft/aspire@release/13.4 at 11bea2eb9fbb655614bcf9814c55c88a3fdd1126 (the same PR that ships these bug fixes: microsoft/aspire#17688).
• Claims extracted: 17 (verified 13 · verified-with-nuance 2 · contradicted 2 · unverifiable 0).

Phase B — doc-tester blind-user walkthrough

• Pages exercised: /reference/cli/commands/aspire-ls/ (new) and sidebar placement under reference/cli/commands.
• Couldn't reach a rendered preview (PR's frontend-build CI failed for unrelated getContributors.ts rate-limiting and no preview URL was posted; the worktree isn't on this PR's branch and spinning up the full Astro/Starlight site locally is out of scope for a single hourly tick). Walkthrough was performed against the rendered MDX content + the resolved <Include> partials, applying the doc-tester rubric for link conventions, teaching effectiveness, code completeness, and knowledge gaps.
• 0 critical · 5 warnings · 3 knowledge gaps · 7 passed checks.

Verdict: REQUEST_CHANGES — two factual contradictions in Phase A (legacy config filename, JSON language value). Phase B is clean of critical issues.

---

Phase A — Claim verification

Two inline comments are anchored to the lines that need to change (see line 32 and line 100/120 threads).

All 17 claims with evidence (click to expand)

#	Claim	Verdict	Evidence (path:line in microsoft/aspire@release/13.4)
C1	aspire ls is a top-level CLI command.	✅ verified	src/Aspire.Cli/Commands/LsCommand.cs:55 base("ls", ...); registered at src/Aspire.Cli/Commands/RootCommand.cs:244 Subcommands.Add(lsCommand).
C2	Synopsis is aspire ls [options].	✅ verified	LsCommand ctor + option declarations at LsCommand.cs:29–42.
C3	Discovers AppHost candidates in cwd + subdirectories with parallel discovery.	✅ verified	LsCommandDescription resx string matches; ProjectLocator.FindAppHostProjectFilesAsync uses Parallel.ForEachAsync.
C4	Legacy config file is aspireSettings.json with appHostPath.	❌ contradicted	Actual legacy file is .aspire/settings.json per src/Aspire.Cli/Utils/ConfigurationHelper.cs:86–89 (Path.Combine(workingDirectory, ".aspire", "settings.json")). Field name appHostPath is correct. Modern aspire.config.json + appHost.path is correct.
C5	When the configured file path is absent / invalid characters / non-string, a "warning is displayed".	⚠️ verified-with-nuance	The user-facing branch calls interactionService.DisplayError(...) (red error) for ConfiguredAppHostPathHasInvalidCharacters and ConfiguredAppHostPathMustBeString (ProjectLocator.cs:760, 773, 805). Only the silent logger branch uses LogWarning. Also: a missing config file is silent (no warning at all); only a present-but-invalid file produces visible output.
C6	--format <Json|Table> defaults to Table.	✅ verified	OutputFormat.cs declares Table = 0 first with (default) XML doc; Option<OutputFormat> in LsCommand.cs:29–32 has no explicit default so falls back to enum 0.
C7	--stream emits NDJSON and requires --format json.	✅ verified	Validator at LsCommand.cs:69–75 raises LsStreamRequiresJson ("The --stream option requires --format json."); streaming impl at LsCommand.cs:152–171.
C8	--all ignores .gitignore and built-in directory filters.	✅ verified	LsAllOptionDescription resx string is identical wording; AppHostDiscoveryScope.AllFiles semantics at src/Aspire.Cli/Projects/AppHostDiscoveryScope.cs:29–34.
C9	Table headers are PATH/LANGUAGE/STATUS (uppercase) and example paths are relative like ./src/MyApp.AppHost/….	⚠️ verified-with-nuance	Actual rendered headers from SharedCommandStrings.resx:167–175 are Path/Language/Status (mixed case). Actual Path column shows AppHostFile.FullName — absolute path — per LsCommand.cs:270–272. This follows the existing aspire-ps.mdx stylistic convention, so it's a documentation pattern question, not a code mismatch.
C10	JSON / NDJSON output emits "language": "C#".	❌ contradicted	Runtime value is KnownLanguageId.CSharp = "csharp" (lowercase). AppHostProjectCandidate is constructed with handler.LanguageId verbatim (ProjectLocator.cs:391, 424, 516, 527) — no display translation in the ls path. TypeScript hosts emit "typescript/nodejs".
C11	JSON shape is {path, language, status} with camelCase keys.	✅ verified	CandidateAppHostDisplayInfo class at LsCommand.cs:319–326; JsonSerializerOptions with JsonNamingPolicy.CamelCase at LsCommand.cs:316–318.
C12	Non-streaming JSON is sorted by path.	✅ verified	ProjectLocator.cs:171 candidates.Sort((x,y) => string.Compare(x.AppHostFile.FullName, y.AppHostFile.FullName, StringComparison.Ordinal));.
C13	Streaming NDJSON is in arrival order, not sorted.	✅ verified	LsCommand.cs:152–171 contains explicit // Do NOT sort here comment referencing the underlying issue.
C14	aspire ls --format json --stream | jq -s 'sort_by(.path)' is the recommended sort recipe.	✅ verified	Source comment at LsCommand.cs:161 documents this same jq pipeline as the intended user workflow.
C15	status value "buildable".	✅ verified	GetDisplayStatus at LsCommand.cs:297–305 returns "buildable" for AppHostProjectCandidateStatus.Buildable.
C16	Cross-refs to aspire-run and aspire-ps.	✅ verified	Both target pages exist under src/frontend/src/content/docs/reference/cli/commands/.
C17	<Include> partials for option-help, option-log-level, option-non-interactive, option-nologo, option-banner, option-wait.	✅ verified	All six files exist under src/frontend/src/content/docs/reference/cli/includes/.

---

Phase B — doc-tester blind-user report

Methodology note: Couldn't run Playwright against a rendered preview (see header). Walkthrough was performed against the raw aspire-ls.mdx content as Astro would render it, plus each <Include> partial. Findings below are confined to what a "blind" user reading this page on the rendered docs site would experience — they do not consult microsoft/aspire source.

Critical issues

None confirmable from documentation alone (a blind user can't independently verify CLI output without running the command).

Warnings

1. status enumeration is undocumented. The page shows "buildable" but never enumerates the other possible values. A user writing switch (item.status) has no idea what other branches to handle.
2. Scope of --all is hand-wavy. "Ignoring .gitignore and built-in directory filters" — what directories specifically? node_modules/, bin/, obj/, NuGet package cache? Without that list, users can't predict the option's blast radius.
3. Streamed example looks like a fixed contract. The two NDJSON lines on lines 119–122 illustrate "arrival order, not sorted" but a reader may infer the order is stable. A one-line "your line order will vary" would prevent that.
4. No link to the AppHost concept. The Description assumes the reader knows what an "AppHost project" is. A first-time reader landing here from search has no path back to /fundamentals/app-host/ or similar prerequisite content.
5. jq is shown without context. The sort recipe | jq -s 'sort_by(.path)' is correct but jq isn't a standard CLI on Windows / macOS by default. A one-liner that jq is a third-party tool (with a link) would help cross-platform readers.

Passed checks

• Page has frontmatter (title, description), all six required sections (Name, Synopsis, Description, Options, Examples, See also).
• All <Include relativePath="…"/> partials resolve to existing files.
• Sidebar entry is alphabetically correct (between aspire init and aspire logs).
• All site-relative links use trailing slashes (link rule ✅).
• Code fences consistently use title="Aspire CLI" / title="Output".
• import Include from '@components/Include.astro'; is used (no unused imports).
• No grammar/spelling/duplicate-component issues from the common-issues checklist.

Knowledge gaps (built-in knowledge I had to supply)

• What "buildable" implies. I knew this means "the project file is well-formed enough that we could attempt a build" — but the docs don't say that.
• What "directory filters" means in practice. I inferred node_modules, bin, obj because I'm familiar with the .NET / JS toolchains; a Python-first user wouldn't.
• What an "AppHost project candidate" is. I knew because of context; a reader landing cold needs a link out.

Recommendations

1. Enumerate every possible status value (and link to the source enum or a concept page) so scripts can switch on .status safely.
2. Spell out the specific directory filters --all bypasses (with examples).
3. Add "Your output line order may vary" to the streaming example.
4. Link the first occurrence of "AppHost project" to /fundamentals/app-host/ or the equivalent concept page.
5. Drop a parenthetical link explaining jq (e.g. "Requires jq — install via your package manager.").

---

Generated by the automated docs-from-code reviewer.

[IEvangelist]

⚠️ Persistent CI Failure — Content Issue in This PR

CI has been retriggered 6+ times and continues to fail. The failure is not a flaky CI issue — it is caused by a content problem introduced by this PR that must be fixed.

Failing test: ests/unit/seo-lengths.vitest.test.ts:281

The new file
eference/cli/commands/aspire-ls.mdx has an SEO title that is 26 characters long: "aspire ls command · Aspire". This exceeds the maximum allowed SEO title length enforced by the unit test.

Fix needed

Please shorten the page title/SEO title in �spire-ls.mdx so it falls within the allowed character limit. Retriggering CI will not resolve this.

[IEvangelist]

Applied the SEO title fix from #1134 (comment) in 93f8514. The page now has an explicit seoTitle, and the focused SEO length guard passes.

Also applied the review-level Phase B recommendations from the CHANGES_REQUESTED review in 93f8514: documented status values, clarified --all filter scope and the NuGet cache exception, linked the AppHost concept, added jq context, and noted streamed line order may vary.