Repository navigation
Conversation
Reviewer's GuideData structuresIntroduce the package-document metadata record used to carry resolved NuGet package identity, version, location, and extension status.
APIExtend the CLI commands with project and framework selection, route index and get through the project-aware client, and expose the updated install-client choices.
Show help when the CLI is invoked without arguments.
ImplementationResolve restored project packages and an unambiguous assets-file target, then locate supported package documentation directories.
Read local package indexes and documents, merge local and online catalogs, and use the online client when local documentation is unavailable.
Separate the automatic-mode official-document cache from caches used by explicitly configured sources.
Install the new Copilot discovery skill alongside the existing agent artifacts and update accepted client names.
Construct the project-aware client, resolving packages only when no explicit source or base-URL environment override is configured.
ConfigurationUpdate the CLI project configuration and package version for this release.
DocumentationDocument package-first lookup, project and framework selection, Copilot installation, and the revised source, cache, and agent behavior.
Tips and commandsInteracting with Sourcery
Customizing Your ExperienceAccess your dashboard to:
Getting Help
|
Linked issuesChecked at commit 5fd5963 #1300 feat(LLMsDocsCli): prefer project package documentation · 4 of 4 met
|
There was a problem hiding this comment.
Hey - I've found 9 issues
Prompt for AI Agents
Please address the comments from this code review:
## Individual Comments
### Comment 1
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs" line_range="18" />
<code_context>
+ {
+ try
+ {
+ var content = await File.ReadAllTextAsync(entry.File, ct);
+ Console.Error.WriteLine($"Source: {entry.Package.Package} {entry.Package.Version} ({entry.File})");
+ return content;
</code_context>
<issue_to_address>
**Package symlinks expose local files**
When a restored package's index points to a documentation file that is a symlink to a sensitive local file, `File.Exists` follows symlinks, but the path-prefix check validates only the normalized path string; `File.ReadAllTextAsync` then follows a linked path outside the package directory and prints that file's contents.
Resolve the file's final target and verify it remains inside the package documentation directory, or reject reparse points.
</issue_to_address>
### Comment 2
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs" line_range="97-98" />
<code_context>
+
+ foreach (var folder in folders)
+ {
+ var packageRoot = Path.Combine(folder, packagePath.Replace('/', Path.DirectorySeparatorChar));
+ if (!Directory.Exists(packageRoot))
+ {
+ continue;
</code_context>
<issue_to_address>
**Project metadata triggers SMB authentication**
When a Windows user runs a data command in a project whose `obj/project.assets.json` contains a UNC `packageFolders` entry and a matching BootstrapBlazor package, `Directory.Exists` probes the resulting UNC path, causing Windows to contact the remote SMB server and attempt integrated authentication; an attacker-controlled server can capture the caller’s NTLM challenge response during ordinary project documentation lookup.
Reject network or otherwise non-local package-folder paths before probing them.
</issue_to_address>
### Comment 3
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs" line_range="18" />
<code_context>
+ {
+ try
+ {
+ var content = await File.ReadAllTextAsync(entry.File, ct);
+ Console.Error.WriteLine($"Source: {entry.Package.Package} {entry.Package.Version} ({entry.File})");
+ return content;
</code_context>
<issue_to_address>
**Package docs can steer agents**
When a restored package supplies a component document with adversarial instructions and an AI agent consumes `bb-llms get` output, `GetAsync` returns the package text verbatim and the CLI writes it to stdout, so an agent consuming the result can mistake attacker instructions for API documentation and perform unintended tool actions or disclose its context.
Make the agent-facing instructions treat returned package documentation as untrusted data and never follow embedded instructions.
</issue_to_address>
### Comment 4
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs" line_range="54-59" />
<code_context>
+ builder.Append("\n### ").AppendLine(group.Key);
+ foreach (var entry in group)
+ {
+ builder.Append("- [").Append(entry.Name).Append("](").Append(entry.DocumentPath).Append(')');
+ if (entry.Description is not null)
+ {
+ builder.Append(" - ").Append(entry.Description);
+ }
+ builder.AppendLine();
+ }
+ }
</code_context>
<issue_to_address>
**Package metadata controls terminal output**
When a restored package's index contains terminal escape sequences in a component name or description and the user runs `index` or `list --format text`, `IndexAsync` appends package-provided names and descriptions without escaping terminal control characters, so the CLI can emit sequences that spoof terminal output or manipulate terminal features.
Escape or remove terminal control characters from package-provided metadata before displaying it to a terminal.
</issue_to_address>
### Comment 5
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/LlmsDocsClient.cs" line_range="66-67" />
<code_context>
"bb-llms");
+ if (isolateOfficialCache)
+ {
+ _cacheRoot = Path.Combine(_cacheRoot, "official");
+ }
}
</code_context>
<issue_to_address>
**Older refresh replaces newer docs**
When two automatic-source requests refresh the same URL while its content changes and the older response completes last, the requests share the new `official` cache directory, and `WriteContent` writes the response body and metadata without coordinating writers. If an older response finishes after a newer one, it replaces the newer cache entry and marks it fresh for 24 hours, so later callers receive stale documentation.
Serialize writes per cache path and atomically commit the body and matching metadata together.
</issue_to_address>
### Comment 6
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs" line_range="95-111" />
<code_context>
+ foreach (var folder in folders)
</code_context>
<issue_to_address>
**Valid package docs are missed**
When an earlier configured package folder contains an incomplete package directory and a later folder contains usable docs, `ReadPackages` breaks after finding the first package directory, even when it has no usable docs, so `Resolve` never checks later folders and falls back to online docs instead of using the restored package documentation.
Continue through package folders until usable docs are found, and break only after adding them.
</issue_to_address>
### Comment 7
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs" line_range="12" />
<code_context>
+
+ public async Task<string> GetAsync(string name, CancellationToken ct)
+ {
+ var entry = ReadLocalEntries().OrderByDescending(e => e.Package.IsExtension)
+ .FirstOrDefault(e => e.Entry.Name.Equals(name, StringComparison.OrdinalIgnoreCase));
+ if (entry is not null)
</code_context>
<issue_to_address>
**Same-named package docs disappear**
When the restored project contains same-kind packages with same-named entries whose documentation differs, `ReadPackageEntries` assigns those entries identical synthetic paths, so `SearchAsync` drops one with `DistinctBy` and `GetAsync` returns the first match; callers lose a package's search result or receive arbitrary documentation.
Give package entries a package-specific identity and make `GetAsync` handle duplicate names without silently choosing the first package.
Also at `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs:92`, `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs:186-187`.
</issue_to_address>
### Comment 8
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs" line_range="106" />
<code_context>
+ try
+ {
+ using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct);
+ timeout.CancelAfter(TimeSpan.FromSeconds(3));
+ var online = await fallback.ListAsync(null, timeout.Token);
+ var added = false;
</code_context>
<issue_to_address>
**Online-only entries are omitted**
When the online index takes longer than three seconds to respond, `MergeAsync` cancels the online index fetch and catches the timeout, then returns only project entries; `index`, `list`, and `search` omit components that exist only in the online catalog.
Avoid cancelling valid online index requests after three seconds so their entries can be merged.
</issue_to_address>
### Comment 9
<location path="tools/BootstrapBlazor.LLMsDocs.Cli/CommandFactory.cs" line_range="207" />
<code_context>
+ var source = result.GetValue(baseUrl);
+ var automatic = string.IsNullOrWhiteSpace(source)
+ && string.IsNullOrEmpty(Environment.GetEnvironmentVariable(LlmsDocsClient.BaseUrlEnvVar));
+ var packages = automatic ? ProjectDocsResolver.Resolve(result.GetValue(project), result.GetValue(framework)) : [];
+ return new ProjectDocsClient(new LlmsDocsClient(source, result.GetValue(refresh), result.GetValue(noCache), automatic), packages, automatic);
+ }
</code_context>
<issue_to_address>
**Help advertises the wrong default**
When restored project package documentation is available and a caller consults CLI help to determine the default source, `--help` still describes the official URL as the default, although automatic mode resolves restored project packages first; callers who rely on the help output are misled about which documentation source will answer their query.
Update the root and source-option help descriptions to explain that project package docs take precedence over the official site in automatic mode.
</issue_to_address>| var packageRoot = Path.Combine(folder, packagePath.Replace('/', Path.DirectorySeparatorChar)); | ||
| if (!Directory.Exists(packageRoot)) |
There was a problem hiding this comment.
🟠 High · Project metadata triggers SMB authentication
When a Windows user runs a data command in a project whose obj/project.assets.json contains a UNC packageFolders entry and a matching BootstrapBlazor package, Directory.Exists probes the resulting UNC path, causing Windows to contact the remote SMB server and attempt integrated authentication; an attacker-controlled server can capture the caller’s NTLM challenge response during ordinary project documentation lookup.
Reject network or otherwise non-local package-folder paths before probing them.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs` at lines 97-98:
**Project metadata triggers SMB authentication**
When a Windows user runs a data command in a project whose `obj/project.assets.json` contains a UNC `packageFolders` entry and a matching BootstrapBlazor package, `Directory.Exists` probes the resulting UNC path, causing Windows to contact the remote SMB server and attempt integrated authentication; an attacker-controlled server can capture the caller’s NTLM challenge response during ordinary project documentation lookup.
Reject network or otherwise non-local package-folder paths before probing them.| { | ||
| try | ||
| { | ||
| var content = await File.ReadAllTextAsync(entry.File, ct); |
There was a problem hiding this comment.
🟡 Medium · Package docs can steer agents
When a restored package supplies a component document with adversarial instructions and an AI agent consumes bb-llms get output, GetAsync returns the package text verbatim and the CLI writes it to stdout, so an agent consuming the result can mistake attacker instructions for API documentation and perform unintended tool actions or disclose its context.
Make the agent-facing instructions treat returned package documentation as untrusted data and never follow embedded instructions.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs` at line 18:
**Package docs can steer agents**
When a restored package supplies a component document with adversarial instructions and an AI agent consumes `bb-llms get` output, `GetAsync` returns the package text verbatim and the CLI writes it to stdout, so an agent consuming the result can mistake attacker instructions for API documentation and perform unintended tool actions or disclose its context.
Make the agent-facing instructions treat returned package documentation as untrusted data and never follow embedded instructions.| builder.Append("- [").Append(entry.Name).Append("](").Append(entry.DocumentPath).Append(')'); | ||
| if (entry.Description is not null) | ||
| { | ||
| builder.Append(" - ").Append(entry.Description); | ||
| } | ||
| builder.AppendLine(); |
There was a problem hiding this comment.
🟡 Medium · Package metadata controls terminal output
When a restored package's index contains terminal escape sequences in a component name or description and the user runs index or list --format text, IndexAsync appends package-provided names and descriptions without escaping terminal control characters, so the CLI can emit sequences that spoof terminal output or manipulate terminal features.
Escape or remove terminal control characters from package-provided metadata before displaying it to a terminal.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs` at lines 54-59:
**Package metadata controls terminal output**
When a restored package's index contains terminal escape sequences in a component name or description and the user runs `index` or `list --format text`, `IndexAsync` appends package-provided names and descriptions without escaping terminal control characters, so the CLI can emit sequences that spoof terminal output or manipulate terminal features.
Escape or remove terminal control characters from package-provided metadata before displaying it to a terminal.| _cacheRoot = Path.Combine(_cacheRoot, "official"); | ||
| } |
There was a problem hiding this comment.
🟡 Medium · Older refresh replaces newer docs
When two automatic-source requests refresh the same URL while its content changes and the older response completes last, the requests share the new official cache directory, and WriteContent writes the response body and metadata without coordinating writers. If an older response finishes after a newer one, it replaces the newer cache entry and marks it fresh for 24 hours, so later callers receive stale documentation.
Serialize writes per cache path and atomically commit the body and matching metadata together.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/LlmsDocsClient.cs` at lines 66-67:
**Older refresh replaces newer docs**
When two automatic-source requests refresh the same URL while its content changes and the older response completes last, the requests share the new `official` cache directory, and `WriteContent` writes the response body and metadata without coordinating writers. If an older response finishes after a newer one, it replaces the newer cache entry and marks it fresh for 24 hours, so later callers receive stale documentation.
Serialize writes per cache path and atomically commit the body and matching metadata together.| foreach (var folder in folders) | ||
| { | ||
| var packageRoot = Path.Combine(folder, packagePath.Replace('/', Path.DirectorySeparatorChar)); | ||
| if (!Directory.Exists(packageRoot)) | ||
| { | ||
| continue; | ||
| } | ||
| var candidates = core | ||
| ? new[] { Path.Combine(packageRoot, "skills", "bb-api", "references"), Path.Combine(packageRoot, "skills", "bootstrapblazor", "references") } | ||
| : [Path.Combine(packageRoot, "docs", "llms")]; | ||
| var docs = candidates.FirstOrDefault(p => File.Exists(Path.Combine(p, "llms.txt")) | ||
| && (!core || File.Exists(Path.Combine(Path.GetDirectoryName(p)!, "SKILL.md")))); | ||
| if (docs is not null) | ||
| { | ||
| packages.Add(new PackageDocs(name, item.Name[(separator + 1)..], docs, !core)); | ||
| } | ||
| break; |
There was a problem hiding this comment.
🟡 Medium · Valid package docs are missed
When an earlier configured package folder contains an incomplete package directory and a later folder contains usable docs, ReadPackages breaks after finding the first package directory, even when it has no usable docs, so Resolve never checks later folders and falls back to online docs instead of using the restored package documentation.
Continue through package folders until usable docs are found, and break only after adding them.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsResolver.cs` at lines 95-111:
**Valid package docs are missed**
When an earlier configured package folder contains an incomplete package directory and a later folder contains usable docs, `ReadPackages` breaks after finding the first package directory, even when it has no usable docs, so `Resolve` never checks later folders and falls back to online docs instead of using the restored package documentation.
Continue through package folders until usable docs are found, and break only after adding them.|
|
||
| public async Task<string> GetAsync(string name, CancellationToken ct) | ||
| { | ||
| var entry = ReadLocalEntries().OrderByDescending(e => e.Package.IsExtension) |
There was a problem hiding this comment.
🟡 Medium · Same-named package docs disappear
When the restored project contains same-kind packages with same-named entries whose documentation differs, ReadPackageEntries assigns those entries identical synthetic paths, so SearchAsync drops one with DistinctBy and GetAsync returns the first match; callers lose a package's search result or receive arbitrary documentation.
Give package entries a package-specific identity and make GetAsync handle duplicate names without silently choosing the first package.
Also at tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs:92, tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs:186-187.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs` at line 12:
**Same-named package docs disappear**
When the restored project contains same-kind packages with same-named entries whose documentation differs, `ReadPackageEntries` assigns those entries identical synthetic paths, so `SearchAsync` drops one with `DistinctBy` and `GetAsync` returns the first match; callers lose a package's search result or receive arbitrary documentation.
Give package entries a package-specific identity and make `GetAsync` handle duplicate names without silently choosing the first package.
Also at `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs:92`, `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs:186-187`.| try | ||
| { | ||
| using var timeout = CancellationTokenSource.CreateLinkedTokenSource(ct); | ||
| timeout.CancelAfter(TimeSpan.FromSeconds(3)); |
There was a problem hiding this comment.
🟡 Medium · Online-only entries are omitted
When the online index takes longer than three seconds to respond, MergeAsync cancels the online index fetch and catches the timeout, then returns only project entries; index, list, and search omit components that exist only in the online catalog.
Avoid cancelling valid online index requests after three seconds so their entries can be merged.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/Services/ProjectDocsClient.cs` at line 106:
**Online-only entries are omitted**
When the online index takes longer than three seconds to respond, `MergeAsync` cancels the online index fetch and catches the timeout, then returns only project entries; `index`, `list`, and `search` omit components that exist only in the online catalog.
Avoid cancelling valid online index requests after three seconds so their entries can be merged.| var source = result.GetValue(baseUrl); | ||
| var automatic = string.IsNullOrWhiteSpace(source) | ||
| && string.IsNullOrEmpty(Environment.GetEnvironmentVariable(LlmsDocsClient.BaseUrlEnvVar)); | ||
| var packages = automatic ? ProjectDocsResolver.Resolve(result.GetValue(project), result.GetValue(framework)) : []; |
There was a problem hiding this comment.
⚪ Low · Help advertises the wrong default
When restored project package documentation is available and a caller consults CLI help to determine the default source, --help still describes the official URL as the default, although automatic mode resolves restored project packages first; callers who rely on the help output are misled about which documentation source will answer their query.
Update the root and source-option help descriptions to explain that project package docs take precedence over the official site in automatic mode.
Prompt for AI agents
In `tools/BootstrapBlazor.LLMsDocs.Cli/CommandFactory.cs` at line 207:
**Help advertises the wrong default**
When restored project package documentation is available and a caller consults CLI help to determine the default source, `--help` still describes the official URL as the default, although automatic mode resolves restored project packages first; callers who rely on the help output are misled about which documentation source will answer their query.
Update the root and source-option help descriptions to explain that project package docs take precedence over the official site in automatic mode.
Link issues
fixes #1300
Summary By Copilot
Regression?
Risk
Automatic source resolution changes existing default lookup behavior.
Verification
Manual (required)
Automated
dotnet build .\tools\BootstrapBlazor.LLMsDocs.Cli\BootstrapBlazor.LLMsDocs.Cli.csproj -c Release --no-restore— passed.& 'C:\Users\Argo\.copilot\session-state\c108c92c-1ab0-4f45-bb5f-63d1ab9902bc\files\verify-cli-pr.ps1'— passed: help, package lookup, explicit source, framework ambiguity, and missing argument checks using isolated fixtures.Documented
Verify-Client.ps1andVerify-Help.ps1were not run because they are absent from this checkout.Packaging changes reviewed?
Package version change reviewed; package installation was not tested for 11.0.1.
☑️ Self Check before Merge
Summary by Sourcery
Prefer restored project package documentation while retaining explicit source behavior and online fallback.
New Features:
Bug Fixes:
Enhancements:
Build:
Documentation:
Tests: