Self-document CLI options and arguments

.github/workflows/build.yml

@@ -24,7 +24,14 @@ jobs:
         uses: actions/checkout@v4
 
       - name: 🙏 build
-        run: dotnet build -m:1
+        run: dotnet build -m:1 -bl
+
+      - name: 🐛 logs
+        uses: actions/upload-artifact@v3
+        if: runner.debug && always()
+        with:
+          name: logs
+          path: '*.binlog'
 
       - name: ⚙ azurite
         run: |
@@ -41,7 +48,7 @@ jobs:
           SLEET_CONNECTION: ${{ secrets.SLEET_CONNECTION }}
         if: env.SLEET_CONNECTION != ''
         run: |
-          dotnet tool install -g --version 4.0.18 sleet 
+          dotnet tool update sleet -g --allow-downgrade --version $(curl -s --compressed ${{ vars.SLEET_FEED_URL }} | jq '.["sleet:version"]' -r)
           sleet push bin --config none -f --verbose -p "SLEET_FEED_CONTAINER=nuget" -p "SLEET_FEED_CONNECTIONSTRING=${{ secrets.SLEET_CONNECTION }}" -p "SLEET_FEED_TYPE=azure" || echo "No packages found"
 
       - name: ⬆️ upload

src/Cli/Cli.csproj

@@ -39,4 +39,30 @@
     <ProjectProperty Include="PackageVersion" />
   </ItemGroup>
 
+  <Target Name="RenderHelp" AfterTargets="Build" Condition="$(DesignTimeBuild) != 'true'">
+    <WriteLinesToFile Lines="```shell" Overwrite="true" Encoding="UTF-8" File="help.md" />
+    <Exec Command="dotnet run --no-build -c:$(Configuration) -- --help --tos --unattended &gt;&gt; help.md" StdOutEncoding="UTF-8"
+          EnvironmentVariables="NO_COLOR=true" ContinueOnError="true">
+      <Output TaskParameter="ExitCode" PropertyName="MSBuildLastExitCode" />
+    </Exec>
+    <!-- Run again if it failed, but without the output redirect, for troubleshooting via build logs -->
+    <Exec Condition="$(MSBuildLastExitCode) != '0'"
+          Command="dotnet run --no-build -c:$(Configuration) -- --help --tos --unattended" StdOutEncoding="UTF-8"
+          EnvironmentVariables="NO_COLOR=true" />
+    <Error Text="Failed to get help output." Condition="'$(MSBuildLastExitCode)' != '0'" />
+    <WriteLinesToFile Lines="```" Overwrite="false" Encoding="UTF-8" File="help.md" />
+
+    <WriteLinesToFile Lines="```shell" Overwrite="true" Encoding="UTF-8" File="sync.md" />
+    <Exec Command="dotnet run --no-build -c:$(Configuration) -- sync --help --unattended &gt;&gt; sync.md" StdOutEncoding="UTF-8"
+          EnvironmentVariables="NO_COLOR=true" ContinueOnError="true">
+      <Output TaskParameter="ExitCode" PropertyName="MSBuildLastExitCode" />
+    </Exec>
+    <!-- Run again if it failed, but without the output redirect, for troubleshooting via build logs -->
+    <Exec Condition="$(MSBuildLastExitCode) != '0'"
+          Command="dotnet run --no-build -c:$(Configuration) -- sync --help --unattended" StdOutEncoding="UTF-8"
+          EnvironmentVariables="NO_COLOR=true" />
+    <Error Text="Failed to get help output." Condition="'$(MSBuildLastExitCode)' != '0'" />
+    <WriteLinesToFile Lines="```" Overwrite="false" Encoding="UTF-8" File="sync.md" />
+  </Target>
+
 </Project>

src/Cli/help.md

@@ -0,0 +1,19 @@
+USAGE:
+    sponsor [OPTIONS] <COMMAND>
+
+OPTIONS:
+    -h, --help    Prints help information
+
+COMMANDS:
+    config           Manages sponsorlink configuration                          
+    init             Initializes a sponsorable JWT manifest and signing keys    
+    list             Lists current user and organization sponsorships leveraging
+                     the GitHub CLI                                             
+    remove           Removes manifests and notifies issuers to remove backend   
+                     data too                                                   
+    sync             Synchronizes sponsorship manifests                         
+    view             Validates and displays the active sponsor manifests, if any
+    nuget            Emits the nuget.json manifest with all contributors to     
+                     active nuget packages                                      
+    check <TOKEN>    Checks the validity of a GitHub token                      
+```

src/Cli/readme.md

@@ -8,50 +8,13 @@ sponsor sync devlooped
 
 Sync options:
 
-```bash
-USAGE:
-    sponsor sync [account] [OPTIONS]
-
-ARGUMENTS:
-    [account]    Optional sponsored account(s) to synchronize
-
-OPTIONS:
-    -h, --help          Prints help information
-        --autosync      Enable or disable automatic synchronization of expired manifests
-    -l, --local         Sync only existing local manifests
-    -f, --force         Force sync, regardless of expiration of manifests found locally
-    -v, --validate      Whether to always validate local manifests using the issuer public key
-    -u, --unattended    Whether to prevent interactive credentials refresh
-        --with-token    Read GitHub authentication token from standard input for sync
-```
+<!-- include sync.md -->
 
 Other commands:
 
-```bash
-USAGE:
-    sponsor [OPTIONS] <COMMAND>
-
-OPTIONS:
-    -h, --help    Prints help information
-
-COMMANDS:
-    config    Manages sponsorlink configuration
-    init      Initializes a sponsorable JWT manifest and signing keys
-    list      Lists current user and organization sponsorships leveraging the GitHub CLI
-    remove    Removes all manifests and notifies issuers to remove backend data too
-    sync      Synchronizes sponsorship manifests
-    view      Validates and displays the active sponsor manifests, if any
-```
-
-
-### Stats
-
-Active SponsorLink sync usage by sponsorship kind:
-
-![User](https://img.shields.io/endpoint?color=ea4aaa&url=https%3A%2F%2Fsponsorlink.devlooped.com%2Fbadge%3Fuser)
-![Organization](https://img.shields.io/endpoint?color=green&url=https%3A%2F%2Fsponsorlink.devlooped.com%2Fbadge%3Forg)
-![Team](https://img.shields.io/endpoint?color=8A2BE2&url=https%3A%2F%2Fsponsorlink.devlooped.com%2Fbadge%3Fteam)
-![Contributor](https://img.shields.io/endpoint?color=blue&url=https%3A%2F%2Fsponsorlink.devlooped.com%2Fbadge%3Fcontrib)
+<!-- include help.md -->
 
 Learn more [about the tool](https://github.com/devlooped/SponsorLink/blob/main/docs/github/index.md#sponsor-manifest-sync) 
 and related [telemetry](https://github.com/devlooped/SponsorLink/blob/main/docs/github/index.md#telemetry).
+
+<!-- exclude -->

src/Cli/sync.md

@@ -0,0 +1,21 @@
+DESCRIPTION:
+Synchronizes sponsorship manifests
+
+USAGE:
+    sponsor sync [account] [OPTIONS]
+
+ARGUMENTS:
+    [account]    Optional sponsored account(s) to synchronize
+
+OPTIONS:
+    -h, --help          Prints help information                                 
+        --autosync      Enable or disable automatic synchronization of expired  
+                        manifests                                               
+    -l, --local         Sync only existing local manifests                      
+    -f, --force         Force sync, regardless of expiration of manifests found 
+                        locally                                                 
+    -v, --validate      Validate local manifests using the issuer public key    
+    -u, --unattended    Prevent interactive credentials refresh                 
+        --with-token    Read GitHub authentication token from standard input for
+                        sync                                                    
+```

src/Commands/App.cs

@@ -81,6 +81,9 @@ public static CommandApp Create(out IServiceProvider services)
 #if DEBUG
             config.AddCommand<CheckTokenCommand>("check");
 #endif
+
+            if (Environment.GetEnvironmentVariables().Contains("NO_COLOR"))
+                config.Settings.HelpProviderStyles = null;
         });
 
         services = registrar.Services.BuildServiceProvider();

src/Commands/CheckTokenCommand.cs

@@ -7,6 +7,7 @@
 
 namespace Devlooped.Sponsors;
 
+[Description("Checks the validity of a GitHub token.")]
 public class CheckTokenCommand(IGraphQueryClient graph, ICommandApp app, Config config) : GitHubAsyncCommand<CheckTokenCommand.CheckSettings>(app, config)
 {
     public class CheckSettings : ToSSettings