feat(plugins): add step enable/disable and username impersonation support (#490)

* feat(plugins): add step enable/disable and username impersonation support

Issue #66: Add step enable/disable support
- Add `Enabled` property to PluginStepConfig (default: true)
- Use SetStateRequest to change step state after create/update
- Query includes StateCode to detect needed state changes

Issue #67: Support impersonation by username
- If RunAsUser is not a GUID, resolve by domainname or email
- Query systemuser with OR filter on DomainName/InternalEMailAddress
- Throw PpdsException with UserNotFound code if user not found

Closes #66
Closes #67

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix(plugins): address bot review feedback

- Remove redundant null check for impersonatingUserId (Copilot, Gemini)
- Add username.Trim() in ResolveUserIdAsync for robust whitespace handling (Gemini)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: joshsmithxrm

src/PPDS.Cli/Infrastructure/Errors/ErrorCodes.cs

@@ -216,5 +216,8 @@ public static class Plugin
 
         /// <summary>Entity has child components that must be removed first.</summary>
         public const string HasChildren = "Plugin.HasChildren";
+
+        /// <summary>Specified user for impersonation was not found.</summary>
+        public const string UserNotFound = "Plugin.UserNotFound";
     }
 }

src/PPDS.Cli/Plugins/Models/PluginRegistrationConfig.cs

@@ -256,11 +256,19 @@ public sealed class PluginStepConfig
 
     /// <summary>
     /// User context to run the plugin as.
-    /// Use "CallingUser" (default), "System", or a systemuser GUID.
+    /// Use "CallingUser" (default), "System", a systemuser GUID,
+    /// a domain name (e.g., "user@domain.com"), or an email address.
     /// </summary>
     [JsonPropertyName("runAsUser")]
     public string? RunAsUser { get; set; }
 
+    /// <summary>
+    /// Whether the step is enabled. Default is true.
+    /// When false, the step is registered but disabled (won't execute).
+    /// </summary>
+    [JsonPropertyName("enabled")]
+    public bool Enabled { get; set; } = true;
+
     /// <summary>
     /// Description of what this step does.
     /// </summary>

src/PPDS.Cli/Plugins/Registration/PluginRegistrationService.cs

@@ -1148,7 +1148,9 @@ public async Task<Guid> UpsertStepAsync(
         // Check if step exists by name
         var query = new QueryExpression(SdkMessageProcessingStep.EntityLogicalName)
         {
-            ColumnSet = new ColumnSet(SdkMessageProcessingStep.Fields.SdkMessageProcessingStepId),
+            ColumnSet = new ColumnSet(
+                SdkMessageProcessingStep.Fields.SdkMessageProcessingStepId,
+                SdkMessageProcessingStep.Fields.StateCode),
             Criteria = new FilterExpression
             {
                 Conditions =
@@ -1199,10 +1201,25 @@ public async Task<Guid> UpsertStepAsync(
         if (!string.IsNullOrEmpty(stepConfig.RunAsUser) &&
             !stepConfig.RunAsUser.Equals("CallingUser", StringComparison.OrdinalIgnoreCase))
         {
-            if (Guid.TryParse(stepConfig.RunAsUser, out var userId))
+            Guid? impersonatingUserId = null;
+
+            if (Guid.TryParse(stepConfig.RunAsUser, out var parsedGuid))
+            {
+                impersonatingUserId = parsedGuid;
+            }
+            else
             {
-                entity.ImpersonatingUserId = new EntityReference(SystemUser.EntityLogicalName, userId);
+                // Resolve username to GUID (by domain name or email)
+                impersonatingUserId = await ResolveUserIdAsync(stepConfig.RunAsUser, client, cancellationToken);
+                if (impersonatingUserId == null)
+                {
+                    throw new PpdsException(
+                        ErrorCodes.Plugin.UserNotFound,
+                        $"Could not resolve user '{stepConfig.RunAsUser}'. Specify a valid GUID, domain name, or email address.");
+                }
             }
+
+            entity.ImpersonatingUserId = new EntityReference(SystemUser.EntityLogicalName, impersonatingUserId.Value);
         }
 
         // Async auto-delete (only applies to async steps)
@@ -1211,23 +1228,41 @@ public async Task<Guid> UpsertStepAsync(
             entity.AsyncAutoDelete = true;
         }
 
+        Guid stepId;
         if (existing != null)
         {
-            entity.Id = existing.Id;
+            stepId = existing.Id;
+            entity.Id = stepId;
             await UpdateAsync(entity, client, cancellationToken);
 
             // Add to solution even on update (handles case where component exists but isn't in solution)
             if (!string.IsNullOrEmpty(solutionName))
             {
-                await AddToSolutionAsync(existing.Id, ComponentTypeSdkMessageProcessingStep, solutionName, cancellationToken);
+                await AddToSolutionAsync(stepId, ComponentTypeSdkMessageProcessingStep, solutionName, cancellationToken);
             }
 
-            return existing.Id;
+            // Handle state change for existing step if needed
+            var targetState = stepConfig.Enabled
+                ? sdkmessageprocessingstep_statecode.Enabled
+                : sdkmessageprocessingstep_statecode.Disabled;
+            var currentState = existing.GetAttributeValue<OptionSetValue>(SdkMessageProcessingStep.Fields.StateCode)?.Value ?? 0;
+            if (currentState != (int)targetState)
+            {
+                await SetStepStateAsync(stepId, targetState, client, cancellationToken);
+            }
         }
         else
         {
-            return await CreateWithSolutionAsync(entity, solutionName, client, cancellationToken);
+            stepId = await CreateWithSolutionAsync(entity, solutionName, client, cancellationToken);
+
+            // New steps are created enabled by default - disable if needed
+            if (!stepConfig.Enabled)
+            {
+                await SetStepStateAsync(stepId, sdkmessageprocessingstep_statecode.Disabled, client, cancellationToken);
+            }
         }
+
+        return stepId;
     }
 
     /// <summary>
@@ -2170,6 +2205,61 @@ private static async Task<Entity> RetrieveAsync(
         return await Task.Run(() => client.Retrieve(entityName, id, columnSet), cancellationToken);
     }
 
+    /// <summary>
+    /// Resolves a username (domain name or email) to a systemuser GUID.
+    /// </summary>
+    /// <param name="username">The username, domain name, or email address.</param>
+    /// <param name="client">The Dataverse client.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    /// <returns>The user's GUID, or null if not found.</returns>
+    private static async Task<Guid?> ResolveUserIdAsync(
+        string username,
+        IOrganizationService client,
+        CancellationToken cancellationToken)
+    {
+        username = username.Trim();
+        var query = new QueryExpression(SystemUser.EntityLogicalName)
+        {
+            ColumnSet = new ColumnSet(SystemUser.Fields.SystemUserId),
+            TopCount = 1
+        };
+
+        // Match by domain name OR internal email address
+        var filter = new FilterExpression(LogicalOperator.Or);
+        filter.AddCondition(SystemUser.Fields.DomainName, ConditionOperator.Equal, username);
+        filter.AddCondition(SystemUser.Fields.InternalEMailAddress, ConditionOperator.Equal, username);
+        query.Criteria.AddFilter(filter);
+
+        var result = await RetrieveMultipleAsync(query, client, cancellationToken);
+        return result.Entities.FirstOrDefault()?.Id;
+    }
+
+    /// <summary>
+    /// Sets the state of a plugin step (enabled or disabled).
+    /// </summary>
+    /// <param name="stepId">The step ID.</param>
+    /// <param name="state">The target state.</param>
+    /// <param name="client">The Dataverse client.</param>
+    /// <param name="cancellationToken">Cancellation token.</param>
+    private static async Task SetStepStateAsync(
+        Guid stepId,
+        sdkmessageprocessingstep_statecode state,
+        IOrganizationService client,
+        CancellationToken cancellationToken)
+    {
+        var statusCode = state == sdkmessageprocessingstep_statecode.Enabled
+            ? sdkmessageprocessingstep_statuscode.Enabled
+            : sdkmessageprocessingstep_statuscode.Disabled;
+
+        var request = new SetStateRequest
+        {
+            EntityMoniker = new EntityReference(SdkMessageProcessingStep.EntityLogicalName, stepId),
+            State = new OptionSetValue((int)state),
+            Status = new OptionSetValue((int)statusCode)
+        };
+        await ExecuteAsync(request, client, cancellationToken);
+    }
+
     #endregion
 }