Add Plugin CLI Tool

documentation/Plugins-System-Preview-Only/PluginTool-CLI.md

@@ -0,0 +1,28 @@
+## Plugintool CLI
+The `plugintool` cli can be used to generate plugin metadata files (`metadata.json` and `metadatacontents.json`) and pack plugin binaries into `.ptix` packages.
+
+### Usage
+#### Metadata Files Generation
+
+`plugintool metadata-gen [-s|--source <SOURCE_DIR>] [-o|--output <OUTPUT_DIR>] [-m|--manifest <MANIFEST_FILE>] [-w|--overwrite]` 
+
+- `-s|--source <SOURCE_DIR>` (Required)  
+  Specifies the directory containing the plugin binaries.
+- `-o|--output <OUTPUT_DIR>`  
+  Specifies the directory where the metadata files will be created. If not provided, the files will be created in the current directory.
+- `-m|--manifest <MANIFEST_FILE>`  
+  Specifies the path to the manifest file. If not provided, the tool will look for a `pluginManifest.json` file in the source directory.
+- `-w|--overwrite`  
+  Specifies whether to overwrite existing metadata files if they exist. It's only valid if the `-o|--output` option is specified.
+
+#### Package a Plugin
+`plugintool pack [-s|--source <SOURCE_DIR>] [-o|--output <OUTPUT_FILE_PATH>] [-m|--manifest <MANIFEST_FILE>] [-w|--overwrite]` `
+
+- `-s|--source <SOURCE_DIR>` (Required)  
+  Specifies the directory containing the plugin binaries.
+- `-o|--output <OUTPUT_FILE_PATH>`  
+  Specifies the path where the `.ptix` package will be created. If not provided, the package will be created in the current directory.
+- `-m|--manifest <MANIFEST_FILE>`  
+  Specifies the path to the manifest file. If not provided, the tool will look for a `pluginManifest.json` file in the source directory.
+- `-w|--overwrite`  
+  Specifies whether to overwrite existing metadata files if they exist. It's only valid if the `-o|--output` option is specified.

src/Microsoft.Performance.SDK.Runtime/TrackingVersionChecker.cs

@@ -0,0 +1,54 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Collections.Concurrent;
+using System.Collections.Generic;
+using NuGet.Versioning;
+
+namespace Microsoft.Performance.SDK.Runtime
+{
+    /// <summary>
+    ///     A <see cref="VersionChecker"/> that keeps track of the versions it has checked and whether they are supported.
+    /// </summary>
+    public class TrackingVersionChecker
+        : VersionChecker
+    {
+        private readonly ConcurrentDictionary<SemanticVersion, bool> checkedVersion;
+
+        /// <summary>
+        ///     Initializes a new instance of the <see cref="TrackingVersionChecker"/>
+        /// </summary>
+        public TrackingVersionChecker()
+        {
+            this.checkedVersion = new ConcurrentDictionary<SemanticVersion, bool>();
+        }
+
+        /// <summary>
+        ///     Gets the list of versions that have been checked by this instance.
+        /// </summary>
+        public IReadOnlyDictionary<SemanticVersion, bool> CheckedVersions
+        {
+            get
+            {
+                return this.checkedVersion;
+            }
+        }
+
+        /// <summary>
+        ///     Overrides the base implementation to keep track of the versions that have been checked.
+        /// </summary>
+        /// <param name="candidateVersion">
+        ///     The version to check.
+        /// </param>
+        /// <returns>
+        ///     <c>true</c> if the version is supported; <c>false</c> otherwise.
+        /// </returns>
+        public override bool IsVersionSupported(SemanticVersion candidateVersion)
+        {
+            bool supported = base.IsVersionSupported(candidateVersion);
+            this.checkedVersion.TryAdd(candidateVersion, supported);
+
+            return supported;
+        }
+    }
+}

src/PluginsSystem/Microsoft.Performance.Toolkit.Plugins.Core/Metadata/ContentsMetadata/DataSourceNameConstants.cs

@@ -0,0 +1,14 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Performance.Toolkit.Plugins.Core.Metadata
+{
+    /// <summary>
+    ///     Contains the names of the non-file data sources that are supported by the toolkit
+    /// </summary>
+    public static class DataSourceNameConstants
+    {
+        public const string DirectoryDataSourceName = "directory";
+        public const string ExtensionlessDataSourceName = "extensionless";
+    }
+}

src/PluginsSystem/Microsoft.Performance.Toolkit.Plugins.Runtime/Package/PackageConstants.cs

@@ -11,5 +11,6 @@ public static class PackageConstants
         public const string PluginMetadataFileName = "metadata.json";
         public const string PluginContentsMetadataFileName = "contentsmetadata.json";
         public const string PluginContentFolderName = "plugin/";
+        public const string PluginPackageExtension = ".ptix";
     }
 }

src/PluginsSystem/Tools/Microsoft.Performance.Toolkit.Plugins.Cli/Commands/Common/PackGenCommonArgs.cs

@@ -0,0 +1,22 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Performance.Toolkit.Plugins.Cli.Commands
+{
+    /// <summary>
+    ///     Common arguments for packgen commands.
+    /// </summary>
+    /// <param name="SourceDirectoryFullPath">
+    ///     The full path to the directory containing the plugin.
+    /// </param>
+    /// <param name="ManifestFileFullPath">
+    ///     The full path to the manifest file to use.
+    /// </param>
+    /// <param name="Overwrite">
+    ///     Whether or not to overwrite an existing output file.
+    /// </param>    
+    internal record PackGenCommonArgs(
+        string SourceDirectoryFullPath,
+        string? ManifestFileFullPath,
+        bool Overwrite);
+}

src/PluginsSystem/Tools/Microsoft.Performance.Toolkit.Plugins.Cli/Commands/Common/PackGenCommonCommand.cs

@@ -0,0 +1,68 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Logging;
+using Microsoft.Performance.Toolkit.Plugins.Cli.Manifest;
+using Microsoft.Performance.Toolkit.Plugins.Cli.Processing;
+
+namespace Microsoft.Performance.Toolkit.Plugins.Cli.Commands.Common
+{
+    /// <summary>
+    ///     Base class for commands that require the plugin to be processed.
+    /// </summary>
+    /// <typeparam name="TArgs">
+    ///     The type of arguments for the command.
+    /// </typeparam>
+    internal abstract class PackGenCommonCommand<TArgs>
+        : ICommand<TArgs>
+        where TArgs : PackGenCommonArgs
+    {
+        protected readonly IManifestLocatorFactory manifestLocatorFactory;
+        protected readonly IPluginArtifactsProcessor artifactsProcessor;
+        protected readonly ILogger<PackGenCommonCommand<TArgs>> logger;
+
+        protected PackGenCommonCommand(
+            IManifestLocatorFactory manifestLocatorFactory,
+            IPluginArtifactsProcessor artifactsProcessor,
+            ILogger<PackGenCommonCommand<TArgs>> logger)
+        {
+            this.manifestLocatorFactory = manifestLocatorFactory;
+            this.artifactsProcessor = artifactsProcessor;
+            this.logger = logger;
+        }
+
+        /// <inheritdoc />
+        public int Run(TArgs args)
+        {
+            if (!TryGetProcessedPluginResult(args, out ProcessedPluginResult? processedSource))
+            {
+                return 1;
+            }
+
+            return RunCore(args, processedSource!);
+        }
+
+        protected abstract int RunCore(TArgs args, ProcessedPluginResult processedSource);
+
+        private bool TryGetProcessedPluginResult(PackGenCommonArgs args, [NotNullWhen(true)] out ProcessedPluginResult? processedPluginResult)
+        {
+            processedPluginResult = null;
+            IManifestLocator manifestLocator = this.manifestLocatorFactory.Create(args);
+            if (!manifestLocator.TryLocate(out string? manifestFilePath))
+            {
+                this.logger.LogError("Failed to locate manifest file.");
+                return false;
+            }
+
+            var artifacts = new PluginArtifacts(args.SourceDirectoryFullPath, manifestFilePath);
+            if (!this.artifactsProcessor.TryProcess(artifacts, out processedPluginResult))
+            {
+                this.logger.LogError("Failed to process plugin artifacts.");
+                return false;
+            }
+
+            return true;
+        }
+    }
+}

src/PluginsSystem/Tools/Microsoft.Performance.Toolkit.Plugins.Cli/Commands/Common/PackGenCommonOptionsValidator.cs

@@ -0,0 +1,81 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+using System.Diagnostics.CodeAnalysis;
+using Microsoft.Extensions.Logging;
+using Microsoft.Performance.Toolkit.Plugins.Cli.Console.Verbs;
+
+namespace Microsoft.Performance.Toolkit.Plugins.Cli.Commands.Common
+{
+    /// <summary>
+    ///     Base class for validating common packgen options.
+    /// </summary>
+    /// <typeparam name="TOptions">
+    ///     The type of options to validate.
+    /// </typeparam>
+    /// <typeparam name="TArgs">
+    ///     The type of arguments to return.
+    /// </typeparam>
+    internal abstract class PackGenCommonOptionsValidator<TOptions, TArgs>
+        : IOptionsValidator<TOptions, TArgs>
+        where TOptions : PackGenCommonOptions
+        where TArgs : PackGenCommonArgs
+    {
+        protected readonly ILogger<PackGenCommonOptionsValidator<TOptions, TArgs>> logger;
+
+        protected PackGenCommonOptionsValidator(ILogger<PackGenCommonOptionsValidator<TOptions, TArgs>> logger)
+        {
+            this.logger = logger;
+        }
+
+        /// <inheritdoc />
+        public bool TryValidate(TOptions cliOptions, [NotNullWhen(true)] out TArgs? validatedAppArgs)
+        {
+            if (!TryValidateCommonOptions(cliOptions, out PackGenCommonArgs validatedCommonArgs))
+            {
+                validatedAppArgs = null;
+                return false;
+            }
+
+            return TryValidateCore(cliOptions, validatedCommonArgs, out validatedAppArgs);
+        }
+
+        protected abstract bool TryValidateCore(TOptions options, PackGenCommonArgs validatedCommonAppArgs, out TArgs? validatedAppArgs);
+
+        private bool TryValidateCommonOptions(
+            PackGenCommonOptions rawOptions,
+            out PackGenCommonArgs validatedAppArgs)
+        {
+            validatedAppArgs = null!;
+            if (string.IsNullOrWhiteSpace(rawOptions.SourceDirectory))
+            {
+                this.logger.LogError("Source directory must be specified. Use --source <path> or -s <path>.");
+                return false;
+            }
+
+            if (!Directory.Exists(rawOptions.SourceDirectory))
+            {
+                this.logger.LogError($"Source directory '{rawOptions.SourceDirectory}' does not exist.");
+                return false;
+            }
+
+            string sourceDirectoryFullPath = Path.GetFullPath(rawOptions.SourceDirectory);
+
+            // Validate manifest file path
+            string? manifestFileFullPath = null;
+            if (rawOptions.ManifestFilePath != null)
+            {
+                if (!File.Exists(rawOptions.ManifestFilePath))
+                {
+                    this.logger.LogError($"Manifest file '{rawOptions.ManifestFilePath}' does not exist.");
+                    return false;
+                }
+
+                manifestFileFullPath = Path.GetFullPath(rawOptions.ManifestFilePath);
+            }
+
+            validatedAppArgs = new PackGenCommonArgs(sourceDirectoryFullPath, manifestFileFullPath, rawOptions.Overwrite);
+            return true;
+        }
+    }
+}

src/PluginsSystem/Tools/Microsoft.Performance.Toolkit.Plugins.Cli/Commands/ICommand`1.cs

@@ -0,0 +1,26 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Performance.Toolkit.Plugins.Cli.Commands
+{
+    /// <summary>
+    ///     Represents a command that can be executed via the CLI.
+    /// </summary>
+    /// <typeparam name="TArgs">
+    ///     The type of arguments that the command accepts.
+    /// </typeparam>
+    internal interface ICommand<TArgs>
+        where TArgs : class
+    {
+        /// <summary>
+        ///     Executes the command.
+        /// </summary>
+        /// <param name="args">
+        ///     The arguments to the command.
+        /// </param>
+        /// <returns>
+        ///     The exit code of the command. A value of 0 indicates success. A value of 1 indicates failure.
+        /// </returns>
+        int Run(TArgs args);
+    }
+}

src/PluginsSystem/Tools/Microsoft.Performance.Toolkit.Plugins.Cli/Commands/MetadataGen/MetadataGenArgs.cs

@@ -0,0 +1,45 @@
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+namespace Microsoft.Performance.Toolkit.Plugins.Cli.Commands
+{
+    /// <summary>
+    ///     Represents the arguments for the <see cref="MetadataGenCommand"/>.
+    /// </summary>
+    /// <param name="SourceDirectoryFullPath">
+    ///     The full path to the directory containing the source code for the plugin.
+    /// </param>
+    /// <param name="ManifestFileFullPath">
+    ///     The full path to the manifest file for the plugin.
+    /// </param>
+    /// <param name="OutputDirectoryFullPath">
+    ///     The full path to the directory to write the generated metadata to.
+    /// </param>
+    /// <param name="Overwrite">
+    ///     Whether or not to overwrite existing files in the output directory.
+    /// </param>
+    internal record MetadataGenArgs(
+        string SourceDirectoryFullPath,
+        string? ManifestFileFullPath,
+        string? OutputDirectoryFullPath,
+        bool Overwrite)
+        : PackGenCommonArgs(
+            SourceDirectoryFullPath,
+            ManifestFileFullPath,
+            Overwrite)
+    {
+        /// <summary>
+        ///     Initializes a new instance of the <see cref="MetadataGenArgs"/> class.
+        /// </summary>
+        /// <param name="commonArgs">
+        ///     The common arguments.
+        /// </param>
+        /// <param name="outputDirectoryFullPath">
+        ///     The full path to the directory to write the generated metadata.
+        /// </param>
+        public MetadataGenArgs(PackGenCommonArgs commonArgs, string? outputDirectoryFullPath)
+            : this(commonArgs.SourceDirectoryFullPath, commonArgs.ManifestFileFullPath, outputDirectoryFullPath, commonArgs.Overwrite)
+        {
+        }
+    }
+}