fix(cli): resolve CLI-014..016 — re-triage update-command contract, doc-surface drift, table-column union

tests/ScadaLink.CLI.Tests/TableHeaderUnionTests.cs

@@ -0,0 +1,91 @@
+using ScadaLink.CLI;
+using ScadaLink.CLI.Commands;
+
+namespace ScadaLink.CLI.Tests;
+
+/// <summary>
+/// Regression tests for CLI-016 — <c>WriteAsTable</c> previously derived the table
+/// header set from the first array element only, so any property unique to a later
+/// element was silently dropped from the rendered table.
+/// </summary>
+[Collection("Console")]
+public class TableHeaderUnionTests
+{
+    [Fact]
+    public void HandleResponse_TableFormat_HeterogeneousArray_IncludesAllColumns()
+    {
+        // The second element has a "Status" property the first lacks. The pre-fix code
+        // derived headers from items[0] only, so "Status" (and its value "Faulted")
+        // were dropped from the table entirely.
+        var writer = new StringWriter();
+        Console.SetOut(writer);
+
+        try
+        {
+            var json = "[{\"Id\":1,\"Name\":\"Alpha\"},{\"Id\":2,\"Name\":\"Beta\",\"Status\":\"Faulted\"}]";
+            var response = new ManagementResponse(200, json, null, null);
+            var exitCode = CommandHelpers.HandleResponse(response, "table");
+
+            Assert.Equal(0, exitCode);
+            var output = writer.ToString();
+            Assert.Contains("Status", output);
+            Assert.Contains("Faulted", output);
+        }
+        finally
+        {
+            Console.SetOut(new StreamWriter(Console.OpenStandardOutput()) { AutoFlush = true });
+        }
+    }
+
+    [Fact]
+    public void HandleResponse_TableFormat_HeterogeneousArray_PreservesFirstSeenColumnOrder()
+    {
+        // Column order must be the first-seen order across all elements: the first
+        // element contributes Id, Name; the second contributes Status after them.
+        var writer = new StringWriter();
+        Console.SetOut(writer);
+
+        try
+        {
+            var json = "[{\"Id\":1,\"Name\":\"Alpha\"},{\"Status\":\"Faulted\",\"Id\":2,\"Name\":\"Beta\"}]";
+            var response = new ManagementResponse(200, json, null, null);
+            var exitCode = CommandHelpers.HandleResponse(response, "table");
+
+            Assert.Equal(0, exitCode);
+            var output = writer.ToString();
+            var headerLine = output.Split('\n')[0];
+            Assert.True(headerLine.IndexOf("Id") < headerLine.IndexOf("Name"));
+            Assert.True(headerLine.IndexOf("Name") < headerLine.IndexOf("Status"));
+        }
+        finally
+        {
+            Console.SetOut(new StreamWriter(Console.OpenStandardOutput()) { AutoFlush = true });
+        }
+    }
+
+    [Fact]
+    public void HandleResponse_TableFormat_FirstElementHasExtraColumn_StillRendersAllRows()
+    {
+        // The reverse case: the first element has a property a later element lacks.
+        // The later row must still render (with an empty cell), and all columns kept.
+        var writer = new StringWriter();
+        Console.SetOut(writer);
+
+        try
+        {
+            var json = "[{\"Id\":1,\"Name\":\"Alpha\",\"Note\":\"first\"},{\"Id\":2,\"Name\":\"Beta\"}]";
+            var response = new ManagementResponse(200, json, null, null);
+            var exitCode = CommandHelpers.HandleResponse(response, "table");
+
+            Assert.Equal(0, exitCode);
+            var output = writer.ToString();
+            Assert.Contains("Note", output);
+            Assert.Contains("first", output);
+            Assert.Contains("Beta", output);
+        }
+        finally
+        {
+            Console.SetOut(new StreamWriter(Console.OpenStandardOutput()) { AutoFlush = true });
+        }
+    }
+}