Backport PR #1439: packageManifest CWS endpoint + v1/v2 config merge fix

Backports PepperDash/Essentials#1439 (merged to main at 6ceddcf5) onto
dev/v3-routing (v3.0.0-dev-v3-routing.40):

- New GET /packageManifest CWS route reporting Essentials/plugin/touchpanel
  UI package version info (GetPackageManifestRequestHandler).
- EssentialsConfig.Versions now round-trips via [JsonProperty("versions")].
- ConfigReader now detects v1 vs v2 config by presence of system/template
  nodes (previously any versions node caused the v1->v2 merge to be
  skipped), and re-applies the versions node after merge since
  PortalConfigReader.MergeConfigs does not carry it forward.
- Mobile control: track and validate UI client app versions
  (ConnectedClientVersionInfo, MobileControlSystemController changes merged
  cleanly from the PR).
- Directory.Build.props: adds PackageId AssemblyMetadata item (kept this
  branch's 3.0.0-local version).

Conflict resolution notes:
- This branch had already introduced its own AppVersion type (Version +
  RepoUrl only) for TouchpanelWrapperApp/UserInterfaces. Replaced it with
  the PR's unified NugetVersion (adds PackageId/RepoUrl/Name, all
  NullValueHandling.Ignore) to match main's schema, since AppVersion had
  no other references in the codebase.
- ConfigReader.LoadConfig on this branch had already fixed a double
  Stream.ReadToEnd() bug (reading fileContents once); kept that fix and
  layered the PR's v1/v2 detection fix + versions-node preservation on
  top of it, plus this branch's null-ConfigObject-after-merge guard.
- EssentialsWebApi.SetupRoutes: inserted the new packageManifest route
  into this branch's existing (longer) route list, which already
  includes routing-specific endpoints not present on main.

Builds clean (dotnet build on the full solution, 0 errors).

Not pushed - pending local hardware/config testing before push.

src/PepperDash.Essentials.Core/Config/Essentials/ConfigReader.cs

@@ -132,12 +132,14 @@ namespace PepperDash.Essentials.Core.Config;
                 {
                     var parsedConfig = JObject.Parse(fileContents);
 
-                    // Check if it's a v2 config (check for "version" node)
-                    // this means it's already merged by the Portal API
-                    // from the v2 config tool
-                    var isV2Config = parsedConfig["versions"] != null;
+                    // A config is v1 if it has separate "system" and "template" nodes that
+                    // need to be merged. A v2 config is already merged by the Portal API and
+                    // will not have "system"/"template" nodes. This is independent of whether
+                    // a "versions" node is present, which only carries version metadata and
+                    // can appear on either a v1 or v2 config.
+                    var isV1Config = parsedConfig["system"] != null && parsedConfig["template"] != null;
 
-                    if (isV2Config)
+                    if (!isV1Config)
                     {
                         Debug.LogMessage(LogEventLevel.Information, "Config file is a v2 format, no merge necessary.");
                         ConfigObject = parsedConfig.ToObject<EssentialsConfig>();
@@ -145,6 +147,8 @@ namespace PepperDash.Essentials.Core.Config;
                         return ConfigObject != null;
                     }
 
+                    Debug.LogMessage(LogEventLevel.Information, "Config file is a v1 format, merging system and template.");
+
                     // Extract SystemUrl and TemplateUrl into final config output
                     ConfigObject = PortalConfigReader.MergeConfigs(parsedConfig).ToObject<EssentialsConfig>();
 
@@ -163,6 +167,13 @@ namespace PepperDash.Essentials.Core.Config;
                     {
                         ConfigObject.TemplateUrl = parsedConfig["template_url"].Value<string>();
                     }
+
+                    // MergeConfigs does not carry the "versions" node forward, so it must be
+                    // applied separately to ensure it's preserved in the merged config.
+                    if (parsedConfig["versions"] != null)
+                    {
+                        ConfigObject.Versions = parsedConfig["versions"].ToObject<VersionData>();
+                    }
                 }
 
                 Debug.LogMessage(LogEventLevel.Information, "Successfully Loaded Merged Config");

src/PepperDash.Essentials.Core/Config/Essentials/EssentialsConfig.cs

@@ -16,9 +16,15 @@ namespace PepperDash.Essentials.Core.Config;
 /// </summary>
 public class EssentialsConfig : BasicConfig
 {
+    /// <summary>
+    /// Gets or sets the System URL for the Essentials configuration
+    /// </summary>
     [JsonProperty("system_url")]
     public string SystemUrl { get; set; }
 
+    /// <summary>
+    /// Gets or sets the Template URL for the Essentials configuration
+    /// </summary>
     [JsonProperty("template_url")]
     public string TemplateUrl { get; set; }
 
@@ -74,14 +80,21 @@ public class EssentialsConfig : BasicConfig
         }
     }
 
+    /// <summary>
+    /// Gets or sets the list of rooms (device configurations)
+    /// </summary>
     [JsonProperty("rooms")]
     public List<DeviceConfig> Rooms { get; set; }
 
     /// <summary>
     /// Gets or sets the Versions
     /// </summary>
+    [JsonProperty("versions")]
     public VersionData Versions { get; set; }
 
+    /// <summary>
+    /// Initializes a new instance of the <see cref="EssentialsConfig"/> class.
+    /// </summary>
     public EssentialsConfig()
         : base()
     {
@@ -98,13 +111,13 @@ public class VersionData
     /// Gets or sets the Essentials version
     /// </summary>
     [JsonProperty("essentials")]
-    public NugetVersion Essentials { get; set; }
+    public PackageVersion Essentials { get; set; }
 
     /// <summary>
     /// Gets or sets the list of UserInterfaces
     /// </summary>
     [JsonProperty("userInterfaces")]
-    public List<AppVersion> UserInterfaces { get; set; }
+    public List<PackageVersion> UserInterfaces { get; set; }
 
     /// <summary>
     /// Gets or sets the TouchpanelWrapperApp version
@@ -112,45 +125,29 @@ public class VersionData
     /// to run an HTML5 user interface.
     /// </summary>
     [JsonProperty("touchpanelWrapperApp")]
-    public AppVersion TouchpanelWrapperApp { get; set; }
+    public PackageVersion TouchpanelWrapperApp { get; set; }
 
     /// <summary>
     /// Gets or sets the list of Packages
     /// </summary>
     [JsonProperty("packages")]
-    public List<NugetVersion> Packages { get; set; }
+    public List<PackageVersion> Packages { get; set; }
 
     /// <summary>
     /// Initializes a new instance of the <see cref="VersionData"/> class.
     /// </summary>
     public VersionData()
     {
-        UserInterfaces = new List<AppVersion>();
-        TouchpanelWrapperApp = new AppVersion();
-        Packages = new List<NugetVersion>();
+        UserInterfaces = new List<PackageVersion>();
+        TouchpanelWrapperApp = new PackageVersion();
+        Packages = new List<PackageVersion>();
     }
 }
 
-public class AppVersion
-{
-    /// <summary>
-    /// Gets or sets the Version
-    /// </summary>
-    [JsonProperty("version")]
-    public string Version { get; set; }
-
-    /// <summary>
-    /// Gets or sets the RepoUrl
-    /// </summary>
-    [JsonProperty("repoUrl")]
-    public string RepoUrl { get; set; }
-}
-
-
 /// <summary>
-/// Represents a NugetVersion
+/// Represents a Package Version
 /// </summary>
-public class NugetVersion
+public class PackageVersion
 {
     /// <summary>
     /// Gets or sets the Version
@@ -161,14 +158,20 @@ public class NugetVersion
     /// <summary>
     /// Gets or sets the PackageId
     /// </summary>
-    [JsonProperty("packageId")]
+    [JsonProperty("packageId", NullValueHandling = NullValueHandling.Ignore)]
     public string PackageId { get; set; }
 
     /// <summary>
     /// Gets or sets the RepoUrl
     /// </summary>
-    [JsonProperty("repoUrl")]
+    [JsonProperty("repoUrl", NullValueHandling = NullValueHandling.Ignore)]
     public string RepoUrl { get; set; }
+
+    /// <summary>
+    /// Gets or sets the human-readable name
+    /// </summary>
+    [JsonProperty("name", NullValueHandling = NullValueHandling.Ignore)]
+    public string Name { get; set; }
 }
 
 /// <summary>
@@ -176,6 +179,9 @@ public class NugetVersion
 /// </summary>
 public class SystemTemplateConfigs
 {
+    /// <summary>
+    /// Gets or sets the System configuration
+    /// </summary>
     public EssentialsConfig System { get; set; }
 
     /// <summary>

src/PepperDash.Essentials.Core/Web/EssentialsWebApi.cs

@@ -90,6 +90,11 @@ public class EssentialsWebApi : EssentialsDevice
                 Name = "ReportVersions",
                 RouteHandler = new ReportVersionsRequestHandler()
             },
+            new HttpCwsRoute("packageManifest")
+            {
+                Name = "GetPackageManifest",
+                RouteHandler = new GetPackageManifestRequestHandler()
+            },
             new HttpCwsRoute("appdebug")
             {
                 Name = "AppDebug",

src/PepperDash.Essentials.Core/Web/RequestHandlers/GetPackageManifestRequestHandler.cs

@@ -0,0 +1,259 @@
+using System;
+using System.Linq;
+using System.Reflection;
+using Crestron.SimplSharp.WebScripting;
+using Newtonsoft.Json;
+using PepperDash.Core.Web.RequestHandlers;
+using PepperDash.Essentials.Core.Config;
+
+namespace PepperDash.Essentials.Core.Web.RequestHandlers
+{
+	/// <summary>
+	/// Represents a GetPackageManifestRequestHandler
+	/// </summary>
+	public class GetPackageManifestRequestHandler : WebApiBaseRequestHandler
+	{
+		/// <summary>
+		/// Constructor
+		/// </summary>
+		/// <remarks>
+		/// base(true) enables CORS support by default
+		/// </remarks>
+		public GetPackageManifestRequestHandler()
+			: base(true)
+		{
+		}
+
+		/// <summary>
+		/// Handles GET method requests
+		/// </summary>
+		/// <param name="context"></param>
+		protected override void HandleGet(HttpCwsContext context)
+		{
+			try
+			{
+				var result = CloneVersionData(ConfigReader.ConfigObject?.Versions) ?? new VersionData();
+
+				PopulateEssentials(result);
+				PopulatePackages(result);
+
+				var js = JsonConvert.SerializeObject(result, Formatting.Indented);
+
+				context.Response.StatusCode = 200;
+				context.Response.StatusDescription = "OK";
+				context.Response.ContentType = "application/json";
+				context.Response.ContentEncoding = System.Text.Encoding.UTF8;
+				context.Response.Write(js, false);
+				context.Response.End();
+			}
+			catch (Exception ex)
+			{
+				PepperDash.Core.Debug.LogMessage(ex, "Exception handling GET /packageManifest request");
+				context.Response.StatusCode = 500;
+				context.Response.StatusDescription = "Internal Server Error";
+				context.Response.End();
+			}
+		}
+
+		/// <summary>
+		/// Deep-copies the config's VersionData so the live config object is never mutated
+		/// </summary>
+		private static VersionData CloneVersionData(VersionData source)
+		{
+			if (source == null)
+			{
+				return null;
+			}
+
+			var json = JsonConvert.SerializeObject(source);
+			return JsonConvert.DeserializeObject<VersionData>(json);
+		}
+
+		/// <summary>
+		/// Enriches (or creates) the essentials entry from the loaded PepperDash.Essentials.Core assembly
+		/// </summary>
+		private static void PopulateEssentials(VersionData result)
+		{
+			var essentials = result.Essentials ?? new PackageVersion();
+
+			essentials.Version = Global.AssemblyVersion;
+
+			// The main program assembly (PackageId "PepperDashEssentials") is what's actually published
+			// to NuGet, but this handler lives in PepperDash.Essentials.Core, which can't reference that
+			// project's types directly (Essentials -> Core, not the reverse). PluginLoader.EssentialsAssembly.Assembly
+			// is unreliable (often left null - see PluginLoader.SetEssentialsAssembly), so look it up
+			// directly from the loaded AppDomain by its Directory.Build.props-embedded PackageId metadata
+			// (every project's .csproj sets its own PackageId explicitly), falling back to this handler's
+			// own (Core) assembly if it can't be found.
+			var essentialsAssembly = AppDomain.CurrentDomain.GetAssemblies()
+				.FirstOrDefault(a => string.Equals(GetAssemblyMetadataValue(a, "PackageId"), "PepperDashEssentials", StringComparison.OrdinalIgnoreCase))
+				?? typeof(GetPackageManifestRequestHandler).Assembly;
+
+			var repoUrl = TrimTrailingGit(GetAssemblyMetadataValue(essentialsAssembly, "RepositoryUrl"));
+			if (!string.IsNullOrEmpty(repoUrl))
+			{
+				essentials.RepoUrl = repoUrl;
+			}
+
+			var name = GetAssemblyProduct(essentialsAssembly);
+			if (!string.IsNullOrEmpty(name))
+			{
+				essentials.Name = name;
+			}
+
+			// Prefer the PackageId embedded via Directory.Build.props' AssemblyMetadata item (the
+			// authoritative source, matching the actual published PackageId) over any config-supplied
+			// or hardcoded value.
+			var reflectedPackageId = GetAssemblyMetadataValue(essentialsAssembly, "PackageId");
+			if (!string.IsNullOrEmpty(reflectedPackageId))
+			{
+				essentials.PackageId = reflectedPackageId;
+			}
+			else if (string.IsNullOrEmpty(essentials.PackageId))
+			{
+				essentials.PackageId = "PepperDashEssentials";
+			}
+
+			result.Essentials = essentials;
+		}
+
+		/// <summary>
+		/// Merges reflection data from loaded plugin assemblies with the config's packages list
+		/// </summary>
+		private static void PopulatePackages(VersionData result)
+		{
+			// Filter out null entries defensively - the packages list is deserialized from user-editable
+			// config JSON, so a malformed "packages": [null, ...] shouldn't throw and 500 the endpoint.
+			var configPackages = (result.Packages ?? new System.Collections.Generic.List<PackageVersion>())
+				.Where(p => p != null)
+				.ToList();
+			var matchedConfigPackages = new System.Collections.Generic.HashSet<PackageVersion>();
+			var mergedPackages = new System.Collections.Generic.List<PackageVersion>();
+
+			foreach (var loaded in PluginLoader.EssentialsPluginAssemblies.Where(a => a.Assembly != null))
+			{
+				var reflectedVersion = loaded.Version;
+				if (string.IsNullOrEmpty(reflectedVersion))
+				{
+					// Never emit an entry with no version - the extension's parser drops entries
+					// whose version isn't a string.
+					continue;
+				}
+
+				var reflectedRepoUrl = TrimTrailingGit(GetAssemblyMetadataValue(loaded.Assembly, "RepositoryUrl"));
+				var reflectedName = GetAssemblyProduct(loaded.Assembly);
+
+				// Plugins built from a Directory.Build.props that embeds
+				// <AssemblyMetadata Include="PackageId" Value="$(PackageId)" /> carry their PackageId
+				// directly - this is authoritative and should be preferred over the title/name fallback chain.
+				var reflectedPackageId = GetAssemblyMetadataValue(loaded.Assembly, "PackageId");
+
+				var assemblyTitle = GetAssemblyTitle(loaded.Assembly);
+				var assemblyName = loaded.Assembly.GetName().Name;
+				var assemblyNameNoSeriesSuffix = StripTrailingSeriesSuffix(assemblyName);
+
+				var match = configPackages.FirstOrDefault(p =>
+					!matchedConfigPackages.Contains(p) &&
+					!string.IsNullOrEmpty(p.PackageId) &&
+					(string.Equals(p.PackageId, reflectedPackageId, StringComparison.OrdinalIgnoreCase) ||
+					 string.Equals(p.PackageId, assemblyTitle, StringComparison.OrdinalIgnoreCase) ||
+					 string.Equals(p.PackageId, assemblyName, StringComparison.OrdinalIgnoreCase) ||
+					 string.Equals(p.PackageId, assemblyNameNoSeriesSuffix, StringComparison.OrdinalIgnoreCase)));
+
+				if (match != null)
+				{
+					matchedConfigPackages.Add(match);
+
+					mergedPackages.Add(new PackageVersion
+					{
+						Name = !string.IsNullOrEmpty(match.Name) ? match.Name : reflectedName,
+						RepoUrl = !string.IsNullOrEmpty(match.RepoUrl) ? match.RepoUrl : reflectedRepoUrl,
+						PackageId = !string.IsNullOrEmpty(reflectedPackageId) ? reflectedPackageId : match.PackageId,
+						Version = reflectedVersion
+					});
+				}
+				else
+				{
+					// Loaded but not present (or not matched) in config - emit the reflected PackageId
+					// when the assembly carries one, otherwise leave it null as before.
+					mergedPackages.Add(new PackageVersion
+					{
+						Name = reflectedName,
+						RepoUrl = reflectedRepoUrl,
+						PackageId = reflectedPackageId,
+						Version = reflectedVersion,						
+					});
+				}
+			}
+
+			// Configured but not currently loaded - pass through unchanged
+			mergedPackages.AddRange(configPackages.Where(p => !matchedConfigPackages.Contains(p)));
+
+			result.Packages = mergedPackages;
+		}
+
+		private static string GetAssemblyMetadataValue(Assembly assembly, string key)
+		{
+			if (assembly == null)
+			{
+				return null;
+			}
+
+			var match = assembly.GetCustomAttributes(typeof(AssemblyMetadataAttribute), false)
+				.Cast<AssemblyMetadataAttribute>()
+				.FirstOrDefault(a => string.Equals(a.Key, key, StringComparison.OrdinalIgnoreCase));
+
+			return match?.Value;
+		}
+
+		private static string GetAssemblyProduct(Assembly assembly)
+		{
+			if (assembly == null)
+			{
+				return null;
+			}
+
+			var attribute = assembly.GetCustomAttributes(typeof(AssemblyProductAttribute), false)
+				.FirstOrDefault() as AssemblyProductAttribute;
+
+			return attribute?.Product;
+		}
+
+		private static string GetAssemblyTitle(Assembly assembly)
+		{
+			if (assembly == null)
+			{
+				return null;
+			}
+
+			var attribute = assembly.GetCustomAttributes(typeof(AssemblyTitleAttribute), false)
+				.FirstOrDefault() as AssemblyTitleAttribute;
+
+			return attribute?.Title;
+		}
+
+		private static string StripTrailingSeriesSuffix(string assemblyName)
+		{
+			const string suffix = ".4Series";
+
+			if (string.IsNullOrEmpty(assemblyName) || !assemblyName.EndsWith(suffix, StringComparison.OrdinalIgnoreCase))
+			{
+				return assemblyName;
+			}
+
+			return assemblyName.Substring(0, assemblyName.Length - suffix.Length);
+		}
+
+		private static string TrimTrailingGit(string repoUrl)
+		{
+			const string suffix = ".git";
+
+			if (string.IsNullOrEmpty(repoUrl) || !repoUrl.EndsWith(suffix, StringComparison.OrdinalIgnoreCase))
+			{
+				return repoUrl;
+			}
+
+			return repoUrl.Substring(0, repoUrl.Length - suffix.Length);
+		}
+	}
+}