From be4f81eda586f9d89e5bcc8c3c3351f1bb19c4da Mon Sep 17 00:00:00 2001 From: Xavier <1859710+xavierjohn@users.noreply.github.com> Date: Sun, 4 Oct 2026 01:56:50 -0700 Subject: [PATCH 1/2] chore: upgrade AgentDocs tooling to preview.20 --- Directory.Packages.props | 2 +- README.md | 2 +- .../src/README.md | 4 ++-- Trellis.ServiceLevelIndicators.Asp/src/README.md | 4 ++-- Trellis.ServiceLevelIndicators/src/README.md | 4 ++-- build/test-guidance-packages.ps1 | 5 +++-- 6 files changed, 11 insertions(+), 10 deletions(-) diff --git a/Directory.Packages.props b/Directory.Packages.props index ed117f4..80cc2a1 100644 --- a/Directory.Packages.props +++ b/Directory.Packages.props @@ -12,7 +12,7 @@ - + diff --git a/README.md b/README.md index 4179c64..c6e7a04 100644 --- a/README.md +++ b/README.md @@ -366,7 +366,7 @@ run once from its Git root: ```powershell dotnet new tool-manifest --output .config -dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.19 --tool-manifest .config/dotnet-tools.json +dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.20 --tool-manifest .config/dotnet-tools.json dotnet tool run agentdocs init ``` diff --git a/Trellis.ServiceLevelIndicators.Asp.ApiVersioning/src/README.md b/Trellis.ServiceLevelIndicators.Asp.ApiVersioning/src/README.md index a265a77..411cdcb 100644 --- a/Trellis.ServiceLevelIndicators.Asp.ApiVersioning/src/README.md +++ b/Trellis.ServiceLevelIndicators.Asp.ApiVersioning/src/README.md @@ -1,4 +1,4 @@ -# Trellis.ServiceLevelIndicators.Asp.ApiVersioning +# Trellis.ServiceLevelIndicators.Asp.ApiVersioning [![NuGet Package](https://img.shields.io/nuget/v/Trellis.ServiceLevelIndicators.Asp.ApiVersioning.svg)](https://www.nuget.org/packages/Trellis.ServiceLevelIndicators.Asp.ApiVersioning) @@ -55,7 +55,7 @@ run from its Git root: ```powershell dotnet new tool-manifest --output .config -dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.19 --tool-manifest .config/dotnet-tools.json +dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.20 --tool-manifest .config/dotnet-tools.json dotnet tool run agentdocs init ``` diff --git a/Trellis.ServiceLevelIndicators.Asp/src/README.md b/Trellis.ServiceLevelIndicators.Asp/src/README.md index aae38bc..69d0522 100644 --- a/Trellis.ServiceLevelIndicators.Asp/src/README.md +++ b/Trellis.ServiceLevelIndicators.Asp/src/README.md @@ -1,4 +1,4 @@ -# Trellis.ServiceLevelIndicators.Asp +# Trellis.ServiceLevelIndicators.Asp [![NuGet Package](https://img.shields.io/nuget/v/Trellis.ServiceLevelIndicators.Asp.svg)](https://www.nuget.org/packages/Trellis.ServiceLevelIndicators.Asp) @@ -212,7 +212,7 @@ run from its Git root: ```powershell dotnet new tool-manifest --output .config -dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.19 --tool-manifest .config/dotnet-tools.json +dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.20 --tool-manifest .config/dotnet-tools.json dotnet tool run agentdocs init ``` diff --git a/Trellis.ServiceLevelIndicators/src/README.md b/Trellis.ServiceLevelIndicators/src/README.md index f361afd..e1ab653 100644 --- a/Trellis.ServiceLevelIndicators/src/README.md +++ b/Trellis.ServiceLevelIndicators/src/README.md @@ -1,4 +1,4 @@ -# Trellis.ServiceLevelIndicators +# Trellis.ServiceLevelIndicators [![NuGet Package](https://img.shields.io/nuget/v/Trellis.ServiceLevelIndicators.svg)](https://www.nuget.org/packages/Trellis.ServiceLevelIndicators) @@ -125,7 +125,7 @@ run from its Git root: ```powershell dotnet new tool-manifest --output .config -dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.19 --tool-manifest .config/dotnet-tools.json +dotnet tool install Trellis.AgentDocs --version 0.1.0-preview.20 --tool-manifest .config/dotnet-tools.json dotnet tool run agentdocs init ``` diff --git a/build/test-guidance-packages.ps1 b/build/test-guidance-packages.ps1 index 65bc96e..0a8307a 100644 --- a/build/test-guidance-packages.ps1 +++ b/build/test-guidance-packages.ps1 @@ -91,9 +91,10 @@ try { $readmeReader = [System.IO.StreamReader]::new($readmeEntry.Open()) try { $readme = $readmeReader.ReadToEnd() } finally { $readmeReader.Dispose() } - if ($readme -notmatch '(?m)^dotnet tool install Trellis\.AgentDocs --version \S+ --tool-manifest \.config/dotnet-tools\.json\r?$' -or + $installCommand = "dotnet tool install Trellis.AgentDocs --version $toolVersion --tool-manifest .config/dotnet-tools.json" + if ([regex]::Matches($readme, "(?m)^$([regex]::Escape($installCommand))\r?$").Count -ne 1 -or -not $readme.Contains('dotnet tool run agentdocs init ')) { - throw "$id NuGet readme must explain how to install and initialize AgentDocs." + throw "$id NuGet readme must pin Trellis.AgentDocs $toolVersion and explain how to initialize it." } # Restoring a package never activates its guide: the readme must describe approval and sync. if (-not $readme.Contains('approvedPackages') -or -not $readme.Contains('dotnet tool run agentdocs sync')) { From 14dc8a5dac180bab25a1139f85aa8b52fb31b39d Mon Sep 17 00:00:00 2001 From: Xavier <1859710+xavierjohn@users.noreply.github.com> Date: Sun, 4 Oct 2026 08:41:44 -0700 Subject: [PATCH 2/2] Reject conflicting AgentDocs install commands --- build/test-guidance-packages.ps1 | 30 +++++++++++++++++++++++++++--- 1 file changed, 27 insertions(+), 3 deletions(-) diff --git a/build/test-guidance-packages.ps1 b/build/test-guidance-packages.ps1 index 0a8307a..eeb7438 100644 --- a/build/test-guidance-packages.ps1 +++ b/build/test-guidance-packages.ps1 @@ -4,6 +4,14 @@ param([string] $PackagesDirectory = (Join-Path (Join-Path $PSScriptRoot '..') 'a $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest +function Test-AgentDocsInstallCommand { + param([string] $Readme, [string] $ExpectedCommand) + + $commands = [regex]::Matches($Readme, + '(?im)^[\t ]*dotnet[\t ]+tool[\t ]+install[\t ]+Trellis\.AgentDocs(?=[\t \r\n]|$)[^\r\n]*\r?$') + return $commands.Count -eq 1 -and $commands[0].Value.TrimEnd("`r") -ceq $ExpectedCommand +} + $references = [ordered]@{ 'Trellis.ServiceLevelIndicators' = 'trellis-api-sli.md' 'Trellis.ServiceLevelIndicators.Asp' = 'trellis-api-sli-asp.md' @@ -15,6 +23,23 @@ $references = [ordered]@{ # is published in lockstep with the tool. $props = [xml] (Get-Content -LiteralPath (Join-Path (Join-Path $PSScriptRoot '..') 'Directory.Packages.props') -Raw) $toolVersion = $props.SelectSingleNode('//PackageVersion[@Include="Trellis.AgentDocs.Packaging"]').Version +$installCommand = "dotnet tool install Trellis.AgentDocs --version $toolVersion --tool-manifest .config/dotnet-tools.json" +$staleCommand = $installCommand.Replace($toolVersion, '0.0.0') +$installCases = @( + @{ Name = 'correct LF'; Readme = "$installCommand`n"; Expected = $true }, + @{ Name = 'correct CRLF'; Readme = "$installCommand`r`n"; Expected = $true }, + @{ Name = 'missing'; Readme = ''; Expected = $false }, + @{ Name = 'stale only'; Readme = $staleCommand; Expected = $false }, + @{ Name = 'duplicate correct'; Readme = "$installCommand`n$installCommand"; Expected = $false }, + @{ Name = 'conflicting version'; Readme = "$installCommand`n$staleCommand"; Expected = $false }, + @{ Name = 'indented conflicting version'; Readme = "$installCommand`n $staleCommand"; Expected = $false } +) +foreach ($case in $installCases) { + if ((Test-AgentDocsInstallCommand -Readme $case.Readme -ExpectedCommand $installCommand) -ne $case.Expected) { + throw "AgentDocs install-command regression failed: $($case.Name)." + } +} +Write-Host 'PASS AgentDocs single-command and version-pin regression cases' $toolDirectory = Join-Path ([System.IO.Path]::GetTempPath()) "agentdocs-validate-$([guid]::NewGuid().ToString('N'))" $install = & dotnet tool install Trellis.AgentDocs --version $toolVersion --tool-path $toolDirectory 2>&1 if ($LASTEXITCODE -ne 0) { throw "Could not install Trellis.AgentDocs $toolVersion for validation:`n$($install | Out-String)" } @@ -91,10 +116,9 @@ try { $readmeReader = [System.IO.StreamReader]::new($readmeEntry.Open()) try { $readme = $readmeReader.ReadToEnd() } finally { $readmeReader.Dispose() } - $installCommand = "dotnet tool install Trellis.AgentDocs --version $toolVersion --tool-manifest .config/dotnet-tools.json" - if ([regex]::Matches($readme, "(?m)^$([regex]::Escape($installCommand))\r?$").Count -ne 1 -or + if (-not (Test-AgentDocsInstallCommand -Readme $readme -ExpectedCommand $installCommand) -or -not $readme.Contains('dotnet tool run agentdocs init ')) { - throw "$id NuGet readme must pin Trellis.AgentDocs $toolVersion and explain how to initialize it." + throw "$id NuGet readme must contain exactly one Trellis.AgentDocs install command pinned to $toolVersion and explain how to initialize it." } # Restoring a package never activates its guide: the readme must describe approval and sync. if (-not $readme.Contains('approvedPackages') -or -not $readme.Contains('dotnet tool run agentdocs sync')) {