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
@@ -431,6 +433,7 @@ Pherson
 pid
 pidl
 pidlist
+pintable
 PKCS
 pkgmgr
 pkindex

.github/copilot-instructions.md

@@ -133,6 +133,105 @@ void WorkflowTask(Execution::Context& context)
 - Parsing in `AppInstallerCommonCore/Manifest/`
 - Multi-file manifests: installer, locale, version, defaultLocale
 
+## SQLite Statement Builder
+
+**Always use `AppInstaller::SQLite::Builder::StatementBuilder` when writing SQLite database code. Never write raw SQL strings.**
+
+The builder is in `<winget/SQLiteStatementBuilder.h>` (namespace `AppInstaller::SQLite::Builder`). It generates type-safe, parameterized SQL and ensures symbolic names are used for tables and columns throughout.
+
+### Key conventions
+
+- Define table and column names as `constexpr std::string_view` constants, then pass them to the builder.
+- Use `ColumnBuilder` with chained modifiers (`.NotNull()`, `.Unique()`, `.Default(value)`) when creating tables.
+- Use `IntegerPrimaryKey()` for auto-increment rowid primary keys.
+- Use `Unbound` as a placeholder and bind values later via `Statement::Bind()`, or pass values directly to have them bound automatically.
+
+### Common operations
+
+```cpp
+using namespace AppInstaller::SQLite::Builder;
+
+// Symbolic names
+static constexpr std::string_view s_MyTable      = "my_table"sv;
+static constexpr std::string_view s_Col_Id       = "id"sv;
+static constexpr std::string_view s_Col_Name     = "name"sv;
+static constexpr std::string_view s_Col_Value    = "value"sv;
+
+// CREATE TABLE
+StatementBuilder builder;
+builder.CreateTable(s_MyTable).Columns({
+    IntegerPrimaryKey(),
+    ColumnBuilder(s_Col_Name, Type::Text).NotNull().Unique(),
+    ColumnBuilder(s_Col_Value, Type::Int64).NotNull().Default(0),
+});
+builder.Execute(connection);
+
+// SELECT
+StatementBuilder builder;
+builder.Select({ s_Col_Id, s_Col_Name })
+    .From(s_MyTable)
+    .Where(s_Col_Name).Equals(nameValue);
+auto stmt = builder.Prepare(connection);
+while (stmt.Step()) { /* stmt.GetColumn<T>(index) */ }
+
+// INSERT
+StatementBuilder builder;
+builder.InsertInto(s_MyTable)
+    .Columns({ s_Col_Name, s_Col_Value })
+    .Values(nameValue, intValue);
+builder.Execute(connection);
+
+// UPDATE
+StatementBuilder builder;
+builder.Update(s_MyTable).Set()
+    .Column(s_Col_Value).AssignValue(newValue)
+    .Where(s_Col_Id).Equals(rowId);
+builder.Execute(connection);
+
+// DELETE
+StatementBuilder builder;
+builder.DeleteFrom(s_MyTable)
+    .Where(s_Col_Id).Equals(rowId);
+builder.Execute(connection);
+
+// ALTER TABLE – add a column
+StatementBuilder builder;
+builder.AlterTable(s_MyTable).Add(s_Col_NewCol, Type::Text).NotNull().Default(0);
+builder.Execute(connection);
+```
+
+### Nullable values: `Equals()` vs `AssignValue()`
+
+Both accept `std::optional<T>`, but they behave differently when the optional is empty and must be used in the right context:
+
+| Method | Empty optional emits | Use in |
+|---|---|---|
+| `Equals(optional<T>)` | `IS NULL` | **WHERE** / filter clauses |
+| `AssignValue(optional<T>)` | `= ?` (binds NULL) | **UPDATE SET** assignments |
+
+Using `Equals(optional)` in an UPDATE SET clause is a bug — SQLite does not accept `col = IS NULL`.
+
+```cpp
+// ✅ Correct: Equals for WHERE filter, AssignValue for SET assignment
+std::optional<int64_t> maybeEpoch = ...;
+std::optional<std::string> maybeNote = ...;
+
+builder.Update(s_MyTable).Set()
+    .Column(s_Col_Name).AssignValue(requiredName)    // non-optional: AssignValue in SET
+    .Column(s_Col_Epoch).AssignValue(maybeEpoch)     // nullable: must use AssignValue in SET
+    .Column(s_Col_Note).AssignValue(maybeNote)       // nullable: must use AssignValue in SET
+    .Where(s_Col_Id).Equals(rowId);                  // filter: Equals is correct here
+
+// ✅ Correct: Equals(optional) in WHERE — emits "IS NULL" when empty
+builder.Select(s_Col_Id).From(s_MyTable)
+    .Where(s_Col_Note).Equals(maybeNote);            // → "WHERE note IS NULL" when empty
+```
+
+### Execution
+
+- `builder.Execute(connection)` — prepares, binds, and runs a statement that returns no rows.
+- `builder.Prepare(connection)` — returns a `SQLite::Statement`; call `.Step()` to iterate, `.GetColumn<T>(index)` to read values.
+
 ## Naming Conventions
 
 - **Namespace structure**: `AppInstaller::<Area>[::<Subarea>]`

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,18 @@ namespace AppInstaller::CLI::Workflow
 
         if (!pinsToAddOrUpdate.empty())
         {
-            for (const auto& pin : pinsToAddOrUpdate)
+            auto pinTime = std::chrono::system_clock::now();
 
+            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(pinTime);
+                pin.SetNote(note);
                 pinningData.AddOrUpdatePin(pin);
             }
 
@@ -335,4 +346,106 @@ 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.has_value())
+            {
+                std::string dateAddedStr = Utility::TimePointToString(*dateAdded,
+                    Utility::TimeFacet::Year | Utility::TimeFacet::Month | Utility::TimeFacet::Day |
+                    Utility::TimeFacet::Hour | Utility::TimeFacet::Minute | Utility::TimeFacet::Second);
+                ShowSingleLineField(info, Resource::String::PinShowLabelDateAdded, Utility::LocIndView{ dateAddedStr });
+            }
+
+            // Note (only shown if present)
+            const auto& note = pin.GetNote();
+            if (note.has_value() && !note->empty())
+            {
+                ShowSingleLineField(info, Resource::String::PinShowLabelNote, Utility::LocIndView{ *note });
+            }
+        }
+    }
 }