feat(transport): export site/instance selection end-to-end via CLI + ManagementActor (M8 B4)

src/ZB.MOM.WW.ScadaBridge.CLI/Commands/BundleCommands.cs

@@ -65,6 +65,10 @@ public static class BundleCommands
         // --api-keys option. Re-create keys and re-grant their method scopes on the
         // destination via the admin UI/CLI.
         var apiMethodsOption = NameListOption("--api-methods", "Comma-separated API-method names");
+        // M8 (B4): site/instance-scoped export. Sites accept a SiteIdentifier
+        // (preferred) or friendly Name per token; instances accept a UniqueName.
+        var sitesOption = NameListOption("--sites", "Comma-separated site identifiers or names");
+        var instancesOption = NameListOption("--instances", "Comma-separated instance unique-names");
         var includeDepsOption = new Option<bool>("--include-dependencies")
         {
             Description = "Pull transitive dependencies (referenced shared scripts, parents, composed members) into the bundle.",
@@ -88,6 +92,8 @@ public static class BundleCommands
         cmd.Add(notificationListsOption);
         cmd.Add(smtpConfigsOption);
         cmd.Add(apiMethodsOption);
+        cmd.Add(sitesOption);
+        cmd.Add(instancesOption);
         cmd.Add(includeDepsOption);
         cmd.Add(sourceEnvOption);
 
@@ -110,7 +116,9 @@ public static class BundleCommands
                 ApiMethodNames: result.GetValue(apiMethodsOption),
                 IncludeDependencies: includeDeps,
                 Passphrase: passphrase,
-                SourceEnvironment: sourceEnv);
+                SourceEnvironment: sourceEnv,
+                SiteNames: result.GetValue(sitesOption),
+                InstanceNames: result.GetValue(instancesOption));
 
             return await CommandHelpers.ExecuteCommandAsync(
                 result, urlOption, formatOption, usernameOption, passwordOption,
@@ -359,14 +367,26 @@ public static class BundleCommands
         {
             Description = description,
             CustomParser = arg =>
-            {
-                var token = arg.Tokens.Count == 0 ? null : arg.Tokens[0].Value;
-                if (string.IsNullOrWhiteSpace(token)) return null;
-                return token
-                    .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
-                    .ToArray();
-            },
+                ParseNameList(arg.Tokens.Count == 0 ? null : arg.Tokens[0].Value),
         };
         return opt;
     }
+
+    /// <summary>
+    /// Splits a comma-separated CLI value into a trimmed, empty-entry-free name
+    /// list (the shared shape used by every <c>--templates</c>/<c>--sites</c>/…
+    /// option). Returns <c>null</c> for a null/blank token so the management
+    /// command sees "not specified" rather than an empty list. Exposed
+    /// <c>internal</c> so the flag-parse tests can assert the split semantics
+    /// without reaching into the per-command local options.
+    /// </summary>
+    /// <param name="token">The raw comma-separated option value, or <c>null</c>.</param>
+    /// <returns>The parsed name array, or <c>null</c> when the token is null/blank.</returns>
+    internal static IReadOnlyList<string>? ParseNameList(string? token)
+    {
+        if (string.IsNullOrWhiteSpace(token)) return null;
+        return token
+            .Split(',', StringSplitOptions.RemoveEmptyEntries | StringSplitOptions.TrimEntries)
+            .ToArray();
+    }
 }

src/ZB.MOM.WW.ScadaBridge.Commons/Messages/Management/TransportCommands.cs

@@ -24,7 +24,13 @@ public sealed record ExportBundleCommand(
     IReadOnlyList<string>? ApiMethodNames,
     bool IncludeDependencies,
     string? Passphrase,
-    string SourceEnvironment);
+    string SourceEnvironment,
+    // Additive (M8 B4): site/instance-scoped selection. Sites resolve by
+    // SiteIdentifier (preferred) or Name; instances resolve by UniqueName.
+    // Defaulted null so every existing positional caller keeps compiling; the
+    // handler normalizes null to "select nothing" (or everything under All=true).
+    IReadOnlyList<string>? SiteNames = null,
+    IReadOnlyList<string>? InstanceNames = null);
 
 /// <summary>
 /// Bundle body returned as base64-encoded ZIP. <see cref="ByteCount"/> is the

src/ZB.MOM.WW.ScadaBridge.ManagementService/ManagementActor.cs

@@ -2305,6 +2305,7 @@ public class ManagementActor : ReceiveActor
         var externalRepo = sp.GetRequiredService<IExternalSystemRepository>();
         var notifRepo = sp.GetRequiredService<INotificationRepository>();
         var inboundRepo = sp.GetRequiredService<IInboundApiRepository>();
+        var siteRepo = sp.GetRequiredService<ISiteRepository>();
 
         var templates = await templateRepo.GetAllTemplatesAsync();
         var sharedScripts = await templateRepo.GetAllSharedScriptsAsync();
@@ -2314,6 +2315,10 @@ public class ManagementActor : ReceiveActor
         var smtpConfigs = await notifRepo.GetAllSmtpConfigurationsAsync();
         // Inbound API keys are not transported between environments (re-arch C4); only methods.
         var apiMethods = await inboundRepo.GetAllApiMethodsAsync();
+        // M8 (B4): site/instance-scoped selection. Sites match on SiteIdentifier
+        // (preferred) or Name; instances match on UniqueName.
+        var sites = await siteRepo.GetAllSitesAsync();
+        var instances = await templateRepo.GetAllInstancesAsync();
 
         int[] ResolveIds<T>(IReadOnlyList<T> all, IReadOnlyList<string>? names,
             Func<T, string> getName, Func<T, int> getId, string entityType)
@@ -2333,6 +2338,33 @@ public class ManagementActor : ReceiveActor
             return matched;
         }
 
+        // Sites accept EITHER the SiteIdentifier (preferred) or the friendly Name
+        // per requested token, so this needs a two-key matcher rather than the
+        // single-key ResolveIds above. Under All=true every site is included.
+        int[] ResolveSiteIds()
+        {
+            if (cmd.All) return sites.Select(s => s.Id).ToArray();
+            var names = cmd.SiteNames;
+            if (names is null || names.Count == 0) return Array.Empty<int>();
+            var matchedIds = new List<int>();
+            var unmatched = new List<string>();
+            foreach (var token in names)
+            {
+                var site = sites.FirstOrDefault(s =>
+                    string.Equals(s.SiteIdentifier, token, StringComparison.Ordinal))
+                    ?? sites.FirstOrDefault(s =>
+                        string.Equals(s.Name, token, StringComparison.Ordinal));
+                if (site is null) unmatched.Add(token);
+                else matchedIds.Add(site.Id);
+            }
+            if (unmatched.Count > 0)
+            {
+                throw new ManagementCommandException(
+                    $"Unknown site identifier/name(s): {string.Join(", ", unmatched.OrderBy(n => n, StringComparer.Ordinal))}.");
+            }
+            return matchedIds.Distinct().ToArray();
+        }
+
         var selection = new ExportSelection(
             TemplateIds: ResolveIds(templates, cmd.TemplateNames, t => t.Name, t => t.Id, "template"),
             SharedScriptIds: ResolveIds(sharedScripts, cmd.SharedScriptNames, s => s.Name, s => s.Id, "shared script"),
@@ -2343,7 +2375,11 @@ public class ManagementActor : ReceiveActor
             // preview row shows the Host value, so the CLI uses Host too.
             SmtpConfigurationIds: ResolveIds(smtpConfigs, cmd.SmtpConfigurationNames, s => s.Host, s => s.Id, "SMTP configuration"),
             ApiMethodIds: ResolveIds(apiMethods, cmd.ApiMethodNames, m => m.Name, m => m.Id, "API method"),
-            IncludeDependencies: cmd.IncludeDependencies);
+            IncludeDependencies: cmd.IncludeDependencies,
+            // M8 (B4): site/instance-scoped selection. Under All=true include every
+            // site + instance, mirroring how All includes every template/etc.
+            SiteIds: ResolveSiteIds(),
+            InstanceIds: ResolveIds(instances, cmd.InstanceNames, i => i.UniqueName, i => i.Id, "instance"));
 
         var exporter = sp.GetRequiredService<IBundleExporter>();
         await using var stream = await exporter.ExportAsync(

src/ZB.MOM.WW.ScadaBridge.Transport/Export/BundleExporter.cs

@@ -73,6 +73,10 @@ public sealed class BundleExporter : IBundleExporter
         var resolved = await _resolver.ResolveAsync(selection, cancellationToken).ConfigureAwait(false);
 
         // 2. Convert to the wire-shaped DTO (strips EF identity, refs-by-name).
+        //    M8 (B4): the resolver's site/dataConnection/instance closure is wired
+        //    through via object-initializer — without this the aggregate would
+        //    carry the empty defaults and the bundle would ship empty site/
+        //    instance arrays even when those were selected (review item I3).
         var aggregate = new EntityAggregate(
             TemplateFolders: resolved.TemplateFolders,
             Templates: resolved.Templates,
@@ -83,7 +87,12 @@ public sealed class BundleExporter : IBundleExporter
             NotificationLists: resolved.NotificationLists,
             SmtpConfigurations: resolved.SmtpConfigs,
             // Inbound API keys are not transported between environments (re-arch C4).
-            ApiMethods: resolved.ApiMethods);
+            ApiMethods: resolved.ApiMethods)
+        {
+            Sites = resolved.Sites,
+            DataConnections = resolved.DataConnections,
+            Instances = resolved.Instances,
+        };
         var contentDto = _entitySerializer.ToBundleContent(aggregate);
 
         // 3. Per-category summary counts — used for fast humanly-readable preview at import.

src/ZB.MOM.WW.ScadaBridge.Transport/Export/DependencyResolver.cs

@@ -196,6 +196,23 @@ public sealed class DependencyResolver
         // in `sites` after closure expansion, so ordering + dependsOn edges resolve names.
         var siteIdentifierById = sites.Values.ToDictionary(s => s.Id, s => s.SiteIdentifier);
 
+        // I1: when an instance/data-connection is selected directly with
+        // IncludeDependencies=false, its owning site is not packed (so it never
+        // lands in `sites`) and the manifest dep-edge would degrade to the raw id
+        // (Site:<rawId>) via SiteIdentifierOf's fallback. Resolve the identifier
+        // for any referenced-but-unpacked owning site so the manifest reads
+        // Site:<identifier> regardless of the deps flag — readability only, the
+        // site row itself stays out of the bundle.
+        var referencedSiteIds = instances.Values.Select(i => i.SiteId)
+            .Concat(dataConnections.Values.Select(c => c.SiteId))
+            .Distinct()
+            .Where(id => !siteIdentifierById.ContainsKey(id));
+        foreach (var siteId in referencedSiteIds)
+        {
+            var site = await _siteRepository.GetSiteByIdAsync(siteId, ct).ConfigureAwait(false);
+            if (site is not null) siteIdentifierById[site.Id] = site.SiteIdentifier;
+        }
+
         var orderedSites = sites.Values
             .OrderBy(s => s.SiteIdentifier, StringComparer.Ordinal)
             .ToList();