Bring Pinning to PowerShell Cmdlets

.github/actions/spelling/expect.txt

@@ -29,6 +29,7 @@ appdata
 appinstallertest
 applic
 appname
+appone
 appshutdown
 APPTERMINATION
 archs
@@ -339,6 +340,7 @@ megamorf
 microsoftentraid
 microsoftentraidforazureblobstorage
 midl
+migratepintable
 minidump
 MINORVERSION
 missingdependency

src/AppInstallerCLICore/Argument.cpp

@@ -203,6 +203,8 @@ namespace AppInstaller::CLI
             return { type, "blocking"_liv, ArgTypeCategory::None, ArgTypeExclusiveSet::PinType };
         case Execution::Args::Type::PinInstalled:
             return { type, "installed"_liv, ArgTypeCategory::None };
+        case Execution::Args::Type::PinNote:
+            return { type, "note"_liv, ArgTypeCategory::None };
 
         // Error command
         case Execution::Args::Type::ErrorInput:

src/AppInstallerCLICore/Commands/PinCommand.cpp

@@ -23,6 +23,7 @@ namespace AppInstaller::CLI
             std::make_unique<PinRemoveCommand>(FullName()),
             std::make_unique<PinListCommand>(FullName()),
             std::make_unique<PinResetCommand>(FullName()),
+            std::make_unique<PinShowCommand>(FullName()),
         });
     }
 
@@ -65,6 +66,7 @@ namespace AppInstaller::CLI
             Argument::ForType(Args::Type::Force),
             Argument{ Args::Type::BlockingPin, Resource::String::PinAddBlockingArgumentDescription, ArgumentType::Flag },
             Argument{ Args::Type::PinInstalled, Resource::String::PinInstalledArgumentDescription, ArgumentType::Flag },
+            Argument{ Args::Type::PinNote, Resource::String::PinNoteArgumentDescription, ArgumentType::Standard },
         };
     }
 
@@ -343,4 +345,36 @@ namespace AppInstaller::CLI
                 Workflow::ReportPins;
         }
     }
+
+    std::vector<Argument> PinShowCommand::GetArguments() const
+    {
+        return {
+            Argument::ForType(Args::Type::Query),
+            Argument::ForType(Args::Type::Id),
+            Argument::ForType(Args::Type::Name),
+            Argument::ForType(Args::Type::Exact),
+        };
+    }
+
+    Resource::LocString PinShowCommand::ShortDescription() const
+    {
+        return { Resource::String::PinShowCommandShortDescription };
+    }
+
+    Resource::LocString PinShowCommand::LongDescription() const
+    {
+        return { Resource::String::PinShowCommandLongDescription };
+    }
+
+    Utility::LocIndView PinShowCommand::HelpLink() const
+    {
+        return s_PinCommand_HelpLink;
+    }
+
+    void PinShowCommand::ExecuteInternal(Execution::Context& context) const
+    {
+        context <<
+            Workflow::OpenPinningIndex(/* readOnly */ true) <<
+            Workflow::ShowPinDetails;
+    }
 }

src/AppInstallerCLICore/Commands/PinCommand.h

@@ -87,4 +87,19 @@ namespace AppInstaller::CLI
     protected:
         void ExecuteInternal(Execution::Context& context) const override;
     };
+
+    struct PinShowCommand final : public Command
+    {
+        PinShowCommand(std::string_view parent) : Command("show", parent) {}
+
+        std::vector<Argument> GetArguments() const override;
+
+        Resource::LocString ShortDescription() const override;
+        Resource::LocString LongDescription() const override;
+
+        Utility::LocIndView HelpLink() const override;
+
+    protected:
+        void ExecuteInternal(Execution::Context& context) const override;
+    };
 }

src/AppInstallerCLICore/ExecutionArgs.h

@@ -122,6 +122,7 @@ namespace AppInstaller::CLI::Execution
             GatedVersion, // Differs from Version in that this supports wildcards
             BlockingPin,
             PinInstalled,
+            PinNote, // User-provided note to attach to a pin
 
             // Error command
             ErrorInput,

src/AppInstallerCLICore/Resources.h

@@ -530,13 +530,16 @@ namespace AppInstaller::CLI::Resource
         WINGET_DEFINE_RESOURCE_STRINGID(PinCannotOpenIndex);
         WINGET_DEFINE_RESOURCE_STRINGID(PinCommandLongDescription);
         WINGET_DEFINE_RESOURCE_STRINGID(PinCommandShortDescription);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinDateAdded);
         WINGET_DEFINE_RESOURCE_STRINGID(PinDoesNotExist);
         WINGET_DEFINE_RESOURCE_STRINGID(PinExistsOverwriting);
         WINGET_DEFINE_RESOURCE_STRINGID(PinExistsUseForceArg);
         WINGET_DEFINE_RESOURCE_STRINGID(PinInstalledArgumentDescription);
         WINGET_DEFINE_RESOURCE_STRINGID(PinInstalledSource);
         WINGET_DEFINE_RESOURCE_STRINGID(PinListCommandLongDescription);
         WINGET_DEFINE_RESOURCE_STRINGID(PinListCommandShortDescription);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinNote);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinNoteArgumentDescription);
         WINGET_DEFINE_RESOURCE_STRINGID(PinNoPinsExist);
         WINGET_DEFINE_RESOURCE_STRINGID(PinRemoveCommandLongDescription);
         WINGET_DEFINE_RESOURCE_STRINGID(PinRemoveCommandShortDescription);
@@ -546,6 +549,15 @@ namespace AppInstaller::CLI::Resource
         WINGET_DEFINE_RESOURCE_STRINGID(PinResetSuccessful);
         WINGET_DEFINE_RESOURCE_STRINGID(PinResettingAll);
         WINGET_DEFINE_RESOURCE_STRINGID(PinResetUseForceArg);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowCommandLongDescription);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowCommandShortDescription);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowLabelDateAdded);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowLabelId);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowLabelNote);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowLabelSource);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowLabelType);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowLabelVersion);
+        WINGET_DEFINE_RESOURCE_STRINGID(PinShowNoMatchFound);
         WINGET_DEFINE_RESOURCE_STRINGID(PinType);
         WINGET_DEFINE_RESOURCE_STRINGID(PinVersion);
         WINGET_DEFINE_RESOURCE_STRINGID(PlatformArgumentDescription);

src/AppInstallerCLICore/Workflows/PinFlow.cpp

@@ -3,7 +3,9 @@
 #include "pch.h"
 #include "Resources.h"
 #include "PinFlow.h"
+#include "ShowFlow.h"
 #include "TableOutput.h"
+#include <AppInstallerDateTime.h>
 #include <winget/PinningData.h>
 #include <winget/RepositorySearch.h>
 #include <winget/PackageVersionSelection.h>
@@ -197,9 +199,21 @@ namespace AppInstaller::CLI::Workflow
 
         if (!pinsToAddOrUpdate.empty())
         {
-            for (const auto& pin : pinsToAddOrUpdate)
+            std::string dateAdded = Utility::TimePointToString(
+                std::chrono::system_clock::now(),
+                Utility::TimeFacet::Year | Utility::TimeFacet::Month | Utility::TimeFacet::Day |
+                Utility::TimeFacet::Hour | Utility::TimeFacet::Minute | Utility::TimeFacet::Second);
 
+            std::optional<std::string> note;
+            if (context.Args.Contains(Execution::Args::Type::PinNote))
             {
+                note = std::string{ context.Args.GetArg(Execution::Args::Type::PinNote) };
+            }
+
+            for (auto& pin : pinsToAddOrUpdate)
+            {
+                pin.SetDateAdded(dateAdded);
+                pin.SetNote(note);
                 pinningData.AddOrUpdatePin(pin);
             }
 
@@ -335,4 +349,103 @@ namespace AppInstaller::CLI::Workflow
             context.Reporter.Info() << Resource::String::PinNoPinsExist << std::endl;
         }
     }
+
+    void ShowPinDetails(Execution::Context& context)
+    {
+        auto& pinningData = context.Get<Execution::Data::PinningData>();
+        auto allPins = pinningData.GetAllPins();
+
+        // Apply filtering based on provided arguments
+        bool hasId = context.Args.Contains(Execution::Args::Type::Id);
+        bool hasName = context.Args.Contains(Execution::Args::Type::Name);
+        bool hasQuery = context.Args.Contains(Execution::Args::Type::Query);
+        bool exactMatch = context.Args.Contains(Execution::Args::Type::Exact);
+
+        std::vector<Pinning::Pin> matchingPins;
+        for (const auto& pin : allPins)
+        {
+            const auto& packageId = pin.GetKey().PackageId;
+
+            if (hasId)
+            {
+                std::string_view idArg = context.Args.GetArg(Execution::Args::Type::Id);
+                bool match = exactMatch
+                    ? Utility::CaseInsensitiveEquals(packageId, idArg)
+                    : Utility::CaseInsensitiveContainsSubstring(packageId, idArg);
+                if (!match)
+                {
+                    continue;
+                }
+            }
+            else if (hasName || hasQuery)
+            {
+                // Without an open source, we can only match against PackageId
+                std::string_view queryArg = hasName
+                    ? context.Args.GetArg(Execution::Args::Type::Name)
+                    : context.Args.GetArg(Execution::Args::Type::Query);
+                bool match = exactMatch
+                    ? Utility::CaseInsensitiveEquals(packageId, queryArg)
+                    : Utility::CaseInsensitiveContainsSubstring(packageId, queryArg);
+                if (!match)
+                {
+                    continue;
+                }
+            }
+
+            matchingPins.push_back(pin);
+        }
+
+        if (matchingPins.empty())
+        {
+            context.Reporter.Info() << Resource::String::PinShowNoMatchFound << std::endl;
+            AICLI_TERMINATE_CONTEXT(APPINSTALLER_CLI_ERROR_PIN_DOES_NOT_EXIST);
+        }
+
+        auto info = context.Reporter.Info();
+        bool firstPin = true;
+        for (const auto& pin : matchingPins)
+        {
+            if (!firstPin)
+            {
+                info << std::endl;
+            }
+            firstPin = false;
+
+            const auto& pinKey = pin.GetKey();
+
+            // ID
+            ShowSingleLineField(info, Resource::String::PinShowLabelId, Utility::LocIndView{ pinKey.PackageId });
+
+            // Source
+            if (!pinKey.SourceId.empty() && !pinKey.IsForInstalled())
+            {
+                ShowSingleLineField(info, Resource::String::PinShowLabelSource, Utility::LocIndView{ pinKey.SourceId });
+            }
+
+            // Type
+            std::string pinTypeStr{ ToString(pin.GetType()) };
+            ShowSingleLineField(info, Resource::String::PinShowLabelType, Utility::LocIndView{ pinTypeStr });
+
+            // Version (gated version string; empty for pinning/blocking pins)
+            std::string gatedVersionStr = pin.GetGatedVersion().ToString();
+            if (!gatedVersionStr.empty())
+            {
+                ShowSingleLineField(info, Resource::String::PinShowLabelVersion, Utility::LocIndView{ gatedVersionStr });
+            }
+
+            // Date Added
+            const auto& dateAdded = pin.GetDateAdded();
+            if (!dateAdded.empty())
+            {
+                ShowSingleLineField(info, Resource::String::PinShowLabelDateAdded, Utility::LocIndView{ dateAdded });
+            }
+
+            // Note (only shown if present)
+            const auto& note = pin.GetNote();
+            if (note.has_value() && !note->empty())
+            {
+                ShowSingleLineField(info, Resource::String::PinShowLabelNote, Utility::LocIndView{ *note });
+            }
+        }
+    }
 }

src/AppInstallerCLICore/Workflows/PinFlow.h

@@ -54,6 +54,14 @@ namespace AppInstaller::CLI::Workflow
     // Outputs: None
     void ReportPins(Execution::Context& context);
 
+    // Shows details for a single matching pin (for `winget pin show`).
+    // Filters the pinning index by query/name/id/exact args and outputs
+    // detailed field-by-field info (Name, ID, Version, Source, Type, Date Added, Note).
+    // Required Args: None (at least one of --query/--name/--id expected)
+    // Inputs: PinningIndex
+    // Outputs: None
+    void ShowPinDetails(Execution::Context& context);
+
     // Resets all the existing pins.
     // Required Args: None
     // Inputs: None

src/AppInstallerCLIPackage/Package.appxmanifest

@@ -86,6 +86,8 @@
               </com:Class>
               <com:Class Id="29B19238-81AD-4A8E-A2FC-ADF17C38CAEB" DisplayName="EditPackageCatalogOptions Server">
               </com:Class>
+              <com:Class Id="B3A61CCB-A3D0-497D-B300-A904904EEA56" DisplayName="PinPackageOptions Server">
+              </com:Class>
             </com:ExeServer>
           </com:ComServer>
         </com:Extension>

src/AppInstallerCLIPackage/Shared/Strings/en-us/winget.resw

@@ -1648,6 +1648,10 @@ Please specify one of them using the --source option to proceed.</value>
   <data name="PinInstalledArgumentDescription" xml:space="preserve">
     <value>Pin a specific installed version</value>
   </data>
+  <data name="PinNoteArgumentDescription" xml:space="preserve">
+    <value>Optional note to store with the pin</value>
+    <comment>Description for the --note argument used with `winget pin add`</comment>
+  </data>
   <data name="PinInstalledSource" xml:space="preserve">
     <value>Installed</value>
     <comment>Value used in a table to indicate that a package comes from the list of packages installed in the machine</comment>
@@ -1913,6 +1917,48 @@ Please specify one of them using the --source option to proceed.</value>
     <value>Pinned version</value>
     <comment>Table header for the version to which a package is pinned; meaning it should not update from that version.</comment>
   </data>
+  <data name="PinDateAdded" xml:space="preserve">
+    <value>Date added</value>
+    <comment>Label shown in the pin show output for when the pin was added or last updated.</comment>
+  </data>
+  <data name="PinNote" xml:space="preserve">
+    <value>Note</value>
+    <comment>Label shown in the pin show output for the user-provided note stored with the pin.</comment>
+  </data>
+  <data name="PinShowCommandShortDescription" xml:space="preserve">
+    <value>Show details about a pin</value>
+  </data>
+  <data name="PinShowCommandLongDescription" xml:space="preserve">
+    <value>Show detailed information about a specific pin, including the package ID, version, type, date added, and any note stored with the pin.</value>
+  </data>
+  <data name="PinShowLabelDateAdded" xml:space="preserve">
+    <value>Date added:</value>
+    <comment>Label shown in the `winget pin show` output for when the pin was added or last updated.</comment>
+  </data>
+  <data name="PinShowLabelId" xml:space="preserve">
+    <value>Id:</value>
+    <comment>Label shown in the `winget pin show` output for the package identifier.</comment>
+  </data>
+  <data name="PinShowLabelNote" xml:space="preserve">
+    <value>Note:</value>
+    <comment>Label shown in the `winget pin show` output for the user-provided note stored with the pin.</comment>
+  </data>
+  <data name="PinShowLabelSource" xml:space="preserve">
+    <value>Source:</value>
+    <comment>Label shown in the `winget pin show` output for the package source.</comment>
+  </data>
+  <data name="PinShowLabelType" xml:space="preserve">
+    <value>Pin type:</value>
+    <comment>Label shown in the `winget pin show` output for the type of pin (e.g., Pinning, Gating, Blocking).</comment>
+  </data>
+  <data name="PinShowLabelVersion" xml:space="preserve">
+    <value>Pinned version:</value>
+    <comment>Label shown in the `winget pin show` output for the version string of a gating pin.</comment>
+  </data>
+  <data name="PinShowNoMatchFound" xml:space="preserve">
+    <value>No pin found matching the specified criteria.</value>
+    <comment>Shown when `winget pin show` finds no matching pin.</comment>
+  </data>
   <data name="ConfigurationDescriptionWasTruncated" xml:space="preserve">
     <value>&lt;See the log file for additional details&gt;</value>
     <comment>The brackets are intended to make the value stand out from other text which it will follow. Any locale appropriate mechanism that achieves this is acceptable.</comment>