[ListSort, Polish] Compile-time drift guard, code cleanup, and docs

- Add static_assert on SortField::Available at enum definition site to
  catch new values that bypass constructor handling.
- Replace invalid-sort assertion with FAIL_FAST_MSG for clearer diagnostics.
- Collapse two consecutive sortFields.empty() checks into a single branch.
- Format SortablePackageEntry constructor arguments one-per-line.
- Add --query example to list.md Example queries section.

Author: Madhusudhan-MSFT

src/AppInstallerCLICore/Workflows/WorkflowBase.cpp

@@ -485,40 +485,39 @@ namespace AppInstaller::CLI::Workflow
                     }
                     else
                     {
-                        // Invalid values should not reach here; ValidateArgumentsInternal
-                        // rejects them with an error before workflow execution begins.
-                        THROW_HR(E_UNEXPECTED);
+                        // Invalid values should not reach here; ValidateArguments
+                        // rejects them with a CommandException before workflow execution begins.
+                        FAIL_FAST_MSG("Unexpected sort field value reached workflow; validation should have caught this.");
                     }
                 }
             }
             else
             {
                 sortFields = User().Get<Setting::OutputSortOrder>();
 
-                // When the free-text query argument is present and the user has NOT
-                // configured a sort preference in settings, preserve relevance ordering.
-                // Only the positional query argument populates searchRequest.Query and
-                // produces meaningful relevance ranking; filter arguments like --id,
-                // --name, --tag etc. use exact/substring matching where all results
-                // have equivalent relevance.
-                // If the user explicitly configured output.sortOrder, respect it even
-                // with queries — that is an explicit user preference.
-                if (sortFields.empty() && context.Args.Contains(Execution::Args::Type::Query))
-                {
-                    return;
-                }
-
-                // No settings configured and no query — apply default sort by name
-                // so that output is deterministic and user-friendly.
                 if (sortFields.empty())
                 {
+                    if (context.Args.Contains(Execution::Args::Type::Query))
+                    {
+                        // When the free-text query argument is present and the user has NOT
+                        // configured a sort preference in settings, preserve relevance ordering.
+                        // Only the positional query argument populates searchRequest.Query and
+                        // produces meaningful relevance ranking; filter arguments like --id,
+                        // --name, --tag etc. use exact/substring matching where all results
+                        // have equivalent relevance.
+                        // If the user explicitly configured output.sortOrder, respect it even
+                        // with queries — that is an explicit user preference.
+                        return;
+                    }
+
+                    // No settings configured and no query — apply default sort by name
+                    // so that output is deterministic and user-friendly.
                     sortFields.emplace_back(SortField::Name);
                 }
             }
 
-            // Empty sort fields or relevance-only means no sorting
-            if (sortFields.empty() ||
-                (sortFields.size() == 1 && sortFields[0] == SortField::Relevance))
+            // Relevance-only means preserve source ordering — no sorting needed.
+            if (sortFields.size() == 1 && sortFields[0] == SortField::Relevance)
             {
                 return;
             }
@@ -544,9 +543,12 @@ namespace AppInstaller::CLI::Workflow
                 [mask](const InstalledPackagesTableLine& line, size_t index) {
                     return SortablePackageEntry(
                         index,
-                        line.Name.get(), line.Id.get(),
-                        line.InstalledVersion.get(), line.AvailableVersion.get(),
-                        line.Source.get(), mask);
+                        line.Name.get(),
+                        line.Id.get(),
+                        line.InstalledVersion.get(),
+                        line.AvailableVersion.get(),
+                        line.Source.get(),
+                        mask);
                 },
                 sortFields, direction);
         }

src/AppInstallerCLITests/AppInstallerCLITests.vcxproj

@@ -302,7 +302,7 @@
     <ClCompile Include="TestConfiguration.cpp" />
     <ClCompile Include="TestRestRequestHandler.cpp" />
     <ClCompile Include="TestSettings.cpp" />
-    <ClCompile Include="ListSort.cpp" />
+    <ClCompile Include="PackageTableSortHelper.cpp" />
     <ClCompile Include="TestSource.cpp" />
     <ClCompile Include="UninstallFlow.cpp" />
     <ClCompile Include="UpdateFlow.cpp" />

src/AppInstallerCLITests/AppInstallerCLITests.vcxproj.filters

@@ -236,7 +236,7 @@
     <ClCompile Include="TestRestRequestHandler.cpp">
       <Filter>Source Files</Filter>
     </ClCompile>
-    <ClCompile Include="ListSort.cpp">
+    <ClCompile Include="PackageTableSortHelper.cpp">
       <Filter>Source Files\CLI</Filter>
     </ClCompile>
     <ClCompile Include="UserSettings.cpp">

src/AppInstallerCLITests/Command.cpp

@@ -4,7 +4,9 @@
 #include "TestCommon.h"
 #include <Command.h>
 #include <AppInstallerStrings.h>
+#include <Commands/ListCommand.h>
 #include <Commands/RootCommand.h>
+#include <winget/UserSettings.h>
 
 using namespace std::string_literals;
 using namespace std::string_view_literals;
@@ -665,3 +667,55 @@ TEST_CASE("ParseArguments_PositionalWithTooManyValues", "[command]")
 
     REQUIRE_COMMAND_EXCEPTION(command.ParseArguments(inv, args), CLI::Resource::String::ExtraPositionalError(Utility::LocIndView{ values.back() }));
 }
+
+TEST_CASE("EnsureListSortFieldCountMatchesLimit", "[command]")
+{
+    // Verifies that the ListCommand --sort argument count limit matches
+    // the number of valid SortField enum values. If a new SortField is
+    // added but SetCountLimit is not updated (or vice versa), this fails.
+    ListCommand listCmd("");
+    auto args = listCmd.GetArguments();
+
+    size_t sortLimit = 0;
+    for (const auto& arg : args)
+    {
+        if (arg.ExecArgType() == Execution::Args::Type::Sort)
+        {
+            sortLimit = arg.Limit();
+            break;
+        }
+    }
+    REQUIRE(sortLimit > 0);
+
+    // Every valid sort field string must convert successfully.
+    std::vector<std::string_view> allFieldNames = {
+        "relevance", "name", "id", "version", "source", "available"
+    };
+
+    REQUIRE(allFieldNames.size() == sortLimit);
+
+    for (const auto& name : allFieldNames)
+    {
+        auto field = Settings::ConvertToSortField(name);
+        REQUIRE(field.has_value());
+    }
+}
+
+TEST_CASE("ValidateArguments_StandardArgExceedsCountLimit", "[command]")
+{
+    Args args;
+    TestCommand command({
+            Argument{ "sort", 's', Args::Type::Sort, DefaultDesc, ArgumentType::Standard }.SetCountLimit(6),
+        });
+
+    // All 6 valid sort fields plus a duplicate — 7 total exceeds the limit of 6.
+    Invocation inv{ std::vector<std::string>{
+        "--sort", "name", "--sort", "id", "--sort", "version",
+        "--sort", "source", "--sort", "available", "--sort", "relevance",
+        "--sort", "name" } };
+
+    command.ParseArguments(inv, args);
+    REQUIRE(args.GetCount(Args::Type::Sort) == 7);
+
+    REQUIRE_COMMAND_EXCEPTION(command.ValidateArguments(args), CLI::Resource::String::TooManyArgError(ArgumentCommon::ForType(Args::Type::Sort).Name));
+}