Task #249 — Driver test-client CLIs: shared lib + Modbus CLI first

Mirrors the v1 otopcua-cli value prop (ad-hoc shell-level PLC validation) for
the Modbus-TCP driver, and lays down the shared scaffolding that AB CIP, AB
Legacy, S7, and TwinCAT CLIs will build on.

New projects:
  - src/ZB.MOM.WW.OtOpcUa.Driver.Cli.Common/ — DriverCommandBase (verbose
    flag + Serilog config) + SnapshotFormatter (single-tag + table +
    write-result renders with invariant-culture value formatting + OPC UA
    status-code shortnames + UTC-normalised timestamps).
  - src/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli/ — otopcua-modbus-cli executable.
    Commands: probe, read, write, subscribe. ModbusCommandBase carries the
    host/port/unit-id flags + builds ModbusDriverOptions with Probe.Enabled
    =false (CLI runs are one-shot; driver-internal keep-alive would race).

Commands + coverage:
  - probe              single FC03 + GetHealth() + pretty-print
  - read               region × address × type synth into one driver tag
  - write              same shape + --value parsed per --type
  - subscribe          polled-subscription stream until Ctrl+C

Tests (38 total):
  - 16 SnapshotFormatterTests covering: status-code shortnames, unknown
    codes fall back to hex, null value + timestamp placeholders, bool
    lowercase, float invariant culture, string quoting, write-result shape,
    aligned table columns, mismatched-length rejection, UTC normalisation.
  - 22 Modbus CLI tests:
      · ReadCommandTests.SynthesiseTagName (5 theory cases)
      · WriteCommandParseValueTests (17 cases: bool aliases, unknown rejected,
        Int16 bounds, UInt16/Bcd16 type, Float32/64 invariant culture,
        String passthrough, BitInRegister, Int32 MinValue, non-numeric reject)

Wiring:
  - ZB.MOM.WW.OtOpcUa.slnx grew 4 entries (2 src + 2 tests).
  - docs/Driver.Modbus.Cli.md — operator-facing runbook with examples per
    command + output format + typical workflows.

Regression: full-solution build clean; shared-lib tests 16/0, Modbus CLI tests
22/0.

Next up: repeat the pattern for AB CIP (shares ~40% more with Modbus via
libplctag), then AB Legacy, S7, TwinCAT. The shared base stays as-is unless
one of those exposes a gap the Modbus-first pass missed.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

tests/ZB.MOM.WW.OtOpcUa.Driver.Cli.Common.Tests/SnapshotFormatterTests.cs

@@ -0,0 +1,123 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.Cli.Common;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Cli.Common.Tests;
+
+[Trait("Category", "Unit")]
+public sealed class SnapshotFormatterTests
+{
+    private static readonly DateTime FixedTime =
+        new(2026, 4, 21, 12, 34, 56, 789, DateTimeKind.Utc);
+
+    [Fact]
+    public void Format_includes_tag_value_status_and_both_timestamps()
+    {
+        var snap = new DataValueSnapshot(42, 0u, FixedTime, FixedTime);
+        var output = SnapshotFormatter.Format("N7:0", snap);
+
+        output.ShouldContain("Tag:         N7:0");
+        output.ShouldContain("Value:       42");
+        output.ShouldContain("Status:      0x00000000 (Good)");
+        output.ShouldContain("Source Time: 2026-04-21T12:34:56.789Z");
+        output.ShouldContain("Server Time: 2026-04-21T12:34:56.789Z");
+    }
+
+    [Theory]
+    [InlineData(0x00000000u, "Good")]
+    [InlineData(0x80000000u, "Bad")]
+    [InlineData(0x80050000u, "BadCommunicationError")]
+    [InlineData(0x80060000u, "BadTimeout")]
+    [InlineData(0x80340000u, "BadNodeIdUnknown")]
+    [InlineData(0x40000000u, "Uncertain")]
+    public void FormatStatus_names_well_known_status_codes(uint status, string expectedName)
+    {
+        SnapshotFormatter.FormatStatus(status).ShouldContain(expectedName);
+    }
+
+    [Fact]
+    public void FormatStatus_unknown_codes_fall_back_to_hex_only()
+    {
+        // 0xDEADBEEF isn't in the shortlist — just render the hex form, no name.
+        SnapshotFormatter.FormatStatus(0xDEADBEEFu).ShouldBe("0xDEADBEEF");
+    }
+
+    [Fact]
+    public void FormatValue_renders_null_as_placeholder()
+    {
+        var snap = new DataValueSnapshot(null, 0x80050000u, null, FixedTime);
+        var output = SnapshotFormatter.Format("Orphan", snap);
+        output.ShouldContain("Value:       <null>");
+        output.ShouldContain("Source Time: -");  // null timestamp → dash
+    }
+
+    [Fact]
+    public void FormatValue_formats_booleans_lowercase()
+    {
+        var snap = new DataValueSnapshot(true, 0u, FixedTime, FixedTime);
+        SnapshotFormatter.Format("Coil", snap).ShouldContain("Value:       true");
+    }
+
+    [Fact]
+    public void FormatValue_formats_floats_invariant_culture()
+    {
+        // Guards against non-invariant decimal separators (e.g. comma on PL locales)
+        // that would break cross-platform log diffs.
+        var snap = new DataValueSnapshot(3.14f, 0u, FixedTime, FixedTime);
+        SnapshotFormatter.Format("F8:0", snap).ShouldContain("3.14");
+    }
+
+    [Fact]
+    public void FormatValue_quotes_strings()
+    {
+        var snap = new DataValueSnapshot("hello", 0u, FixedTime, FixedTime);
+        SnapshotFormatter.Format("Msg", snap).ShouldContain("\"hello\"");
+    }
+
+    [Fact]
+    public void FormatWrite_shows_status_with_tag_name()
+    {
+        var result = new WriteResult(0u);
+        SnapshotFormatter.FormatWrite("Scratch", result)
+            .ShouldBe("Write Scratch: 0x00000000 (Good)");
+    }
+
+    [Fact]
+    public void FormatTable_aligns_columns_and_includes_header_separator()
+    {
+        var names = new[] { "A", "LongerTag" };
+        var snaps = new[]
+        {
+            new DataValueSnapshot(1, 0u, FixedTime, FixedTime),
+            new DataValueSnapshot(2, 0u, FixedTime, FixedTime),
+        };
+        var table = SnapshotFormatter.FormatTable(names, snaps);
+
+        table.ShouldContain("TAG");
+        table.ShouldContain("VALUE");
+        table.ShouldContain("STATUS");
+        table.ShouldContain("SOURCE TIME");
+        table.ShouldContain("---"); // separator row
+        table.ShouldContain("LongerTag");
+        table.ShouldContain("0x00000000");
+    }
+
+    [Fact]
+    public void FormatTable_rejects_mismatched_lengths()
+    {
+        Should.Throw<ArgumentException>(() => SnapshotFormatter.FormatTable(
+            new[] { "A", "B" },
+            new[] { new DataValueSnapshot(1, 0u, FixedTime, FixedTime) }));
+    }
+
+    [Fact]
+    public void FormatTimestamp_normalises_local_kind_to_utc()
+    {
+        // Unspecified / Local times must land on UTC in the output — otherwise a CI box in
+        // UTC+X would emit diffs against dev-laptop runs.
+        var local = new DateTime(2026, 4, 21, 8, 0, 0, DateTimeKind.Local);
+        var formatted = SnapshotFormatter.FormatTimestamp(local);
+        formatted.ShouldEndWith("Z");
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Cli.Common.Tests/ZB.MOM.WW.OtOpcUa.Driver.Cli.Common.Tests.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <IsPackable>false</IsPackable>
+        <IsTestProject>true</IsTestProject>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.Cli.Common.Tests</RootNamespace>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="xunit.v3" Version="1.1.0"/>
+        <PackageReference Include="Shouldly" Version="4.3.0"/>
+        <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0"/>
+        <PackageReference Include="xunit.runner.visualstudio" Version="3.0.2">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\..\src\ZB.MOM.WW.OtOpcUa.Driver.Cli.Common\ZB.MOM.WW.OtOpcUa.Driver.Cli.Common.csproj"/>
+    </ItemGroup>
+
+</Project>

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Tests/ReadCommandTests.cs

@@ -0,0 +1,21 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Commands;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Tests;
+
+[Trait("Category", "Unit")]
+public sealed class ReadCommandTests
+{
+    [Theory]
+    [InlineData(ModbusRegion.HoldingRegisters, 100, ModbusDataType.UInt16, "HR[100]:UInt16")]
+    [InlineData(ModbusRegion.Coils, 0, ModbusDataType.Bool, "Coil[0]:Bool")]
+    [InlineData(ModbusRegion.DiscreteInputs, 42, ModbusDataType.Bool, "DI[42]:Bool")]
+    [InlineData(ModbusRegion.InputRegisters, 5, ModbusDataType.Int16, "IR[5]:Int16")]
+    [InlineData(ModbusRegion.HoldingRegisters, 200, ModbusDataType.Float32, "HR[200]:Float32")]
+    public void SynthesiseTagName_produces_stable_region_prefix_plus_address_plus_type(
+        ModbusRegion region, ushort address, ModbusDataType type, string expected)
+    {
+        ReadCommand.SynthesiseTagName(region, address, type).ShouldBe(expected);
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Tests/WriteCommandParseValueTests.cs

@@ -0,0 +1,90 @@
+using Shouldly;
+using Xunit;
+using ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Commands;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Tests;
+
+/// <summary>
+///     Covers the <c>--value</c> string → CLR type parser inside
+///     <see cref="WriteCommand.ParseValue"/>. This is the piece that guards against
+///     locale surprises (e.g. comma-as-decimal-separator on PL locales), so all numeric
+///     paths assert the invariant-culture path.
+/// </summary>
+[Trait("Category", "Unit")]
+public sealed class WriteCommandParseValueTests
+{
+    [Theory]
+    [InlineData("true", true)]
+    [InlineData("false", false)]
+    [InlineData("1", true)]
+    [InlineData("0", false)]
+    [InlineData("YES", true)]
+    [InlineData("No", false)]
+    [InlineData("on", true)]
+    [InlineData("off", false)]
+    public void ParseValue_Bool_accepts_common_aliases(string raw, bool expected)
+    {
+        WriteCommand.ParseValue(raw, ModbusDataType.Bool).ShouldBe(expected);
+    }
+
+    [Fact]
+    public void ParseValue_Bool_rejects_unknown_strings()
+    {
+        Should.Throw<CliFx.Exceptions.CommandException>(
+            () => WriteCommand.ParseValue("maybe", ModbusDataType.Bool));
+    }
+
+    [Fact]
+    public void ParseValue_Int16_parses_positive_and_negative()
+    {
+        WriteCommand.ParseValue("-32768", ModbusDataType.Int16).ShouldBe((short)-32768);
+        WriteCommand.ParseValue("32767", ModbusDataType.Int16).ShouldBe((short)32767);
+    }
+
+    [Fact]
+    public void ParseValue_UInt16_and_Bcd16_both_yield_ushort()
+    {
+        WriteCommand.ParseValue("65535", ModbusDataType.UInt16).ShouldBeOfType<ushort>();
+        WriteCommand.ParseValue("65535", ModbusDataType.Bcd16).ShouldBeOfType<ushort>();
+    }
+
+    [Fact]
+    public void ParseValue_Float32_uses_invariant_culture_period_as_decimal_separator()
+    {
+        WriteCommand.ParseValue("3.14", ModbusDataType.Float32).ShouldBe(3.14f);
+    }
+
+    [Fact]
+    public void ParseValue_Float64_handles_larger_precision()
+    {
+        var result = WriteCommand.ParseValue("2.718281828", ModbusDataType.Float64);
+        result.ShouldBeOfType<double>();
+        ((double)result).ShouldBe(2.718281828d, 0.0000001d);
+    }
+
+    [Fact]
+    public void ParseValue_String_returns_raw_string_unmodified()
+    {
+        WriteCommand.ParseValue("hello world", ModbusDataType.String).ShouldBe("hello world");
+    }
+
+    [Fact]
+    public void ParseValue_BitInRegister_accepts_bool_aliases()
+    {
+        WriteCommand.ParseValue("true", ModbusDataType.BitInRegister).ShouldBe(true);
+        WriteCommand.ParseValue("0", ModbusDataType.BitInRegister).ShouldBe(false);
+    }
+
+    [Fact]
+    public void ParseValue_Int32_parses_negative_max()
+    {
+        WriteCommand.ParseValue("-2147483648", ModbusDataType.Int32).ShouldBe(int.MinValue);
+    }
+
+    [Fact]
+    public void ParseValue_rejects_non_numeric_for_numeric_types()
+    {
+        Should.Throw<FormatException>(
+            () => WriteCommand.ParseValue("not-a-number", ModbusDataType.Int32));
+    }
+}

tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Tests/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Tests.csproj

@@ -0,0 +1,26 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+    <PropertyGroup>
+        <TargetFramework>net10.0</TargetFramework>
+        <Nullable>enable</Nullable>
+        <ImplicitUsings>enable</ImplicitUsings>
+        <IsPackable>false</IsPackable>
+        <IsTestProject>true</IsTestProject>
+        <RootNamespace>ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Tests</RootNamespace>
+    </PropertyGroup>
+
+    <ItemGroup>
+        <PackageReference Include="xunit.v3" Version="1.1.0"/>
+        <PackageReference Include="Shouldly" Version="4.3.0"/>
+        <PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.12.0"/>
+        <PackageReference Include="xunit.runner.visualstudio" Version="3.0.2">
+            <PrivateAssets>all</PrivateAssets>
+            <IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
+        </PackageReference>
+    </ItemGroup>
+
+    <ItemGroup>
+        <ProjectReference Include="..\..\src\ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli\ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.csproj"/>
+    </ItemGroup>
+
+</Project>