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>

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli/Commands/ProbeCommand.cs

@@ -0,0 +1,55 @@
+using CliFx.Attributes;
+using CliFx.Infrastructure;
+using ZB.MOM.WW.OtOpcUa.Driver.Cli.Common;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Commands;
+
+/// <summary>
+///     Probes a Modbus-TCP endpoint: opens a socket via <see cref="ModbusDriver"/>'s
+///     <c>InitializeAsync</c>, issues a single FC03 at the configured probe address, and
+///     prints the driver's <c>GetHealth()</c>. Fastest way to answer "is the PLC up + talking
+///     Modbus on this host:port?".
+/// </summary>
+[Command("probe", Description = "Verify the Modbus-TCP endpoint is reachable and speaks Modbus.")]
+public sealed class ProbeCommand : ModbusCommandBase
+{
+    [CommandOption("probe-address", Description =
+        "Holding-register address used as the cheap-read probe (default 0). Some PLCs lock " +
+        "register 0 — set this to a known-good address on your device.")]
+    public ushort ProbeAddress { get; init; }
+
+    public override async ValueTask ExecuteAsync(IConsole console)
+    {
+        ConfigureLogging();
+        var ct = console.RegisterCancellationHandler();
+
+        // Build with one probe tag + Probe.Enabled=false so InitializeAsync connects the
+        // transport, we issue a single read to verify the device responds, then shut down.
+        var probeTag = new ModbusTagDefinition(
+            Name: "__probe",
+            Region: ModbusRegion.HoldingRegisters,
+            Address: ProbeAddress,
+            DataType: ModbusDataType.UInt16);
+        var options = BuildOptions([probeTag]);
+
+        await using var driver = new ModbusDriver(options, DriverInstanceId);
+        try
+        {
+            await driver.InitializeAsync("{}", ct);
+            var snapshot = await driver.ReadAsync(["__probe"], ct);
+            var health = driver.GetHealth();
+
+            await console.Output.WriteLineAsync($"Host:         {Host}:{Port} (unit {UnitId})");
+            await console.Output.WriteLineAsync($"Health:       {health.State}");
+            if (health.LastError is { } err)
+                await console.Output.WriteLineAsync($"Last error:   {err}");
+            await console.Output.WriteLineAsync();
+            await console.Output.WriteLineAsync(
+                SnapshotFormatter.Format($"HR[{ProbeAddress}]", snapshot[0]));
+        }
+        finally
+        {
+            await driver.ShutdownAsync(CancellationToken.None);
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli/Commands/ReadCommand.cs

@@ -0,0 +1,95 @@
+using CliFx.Attributes;
+using CliFx.Infrastructure;
+using ZB.MOM.WW.OtOpcUa.Driver.Cli.Common;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Commands;
+
+/// <summary>
+///     Read one Modbus register / coil. Operator specifies the address via
+///     <c>--region</c> + <c>--address</c> + <c>--type</c>; the CLI synthesises a single
+///     <see cref="ModbusTagDefinition"/>, spins up the driver, reads once, prints the snapshot,
+///     and shuts down. Multi-register types (Int32 / Float32 / String / BCD32) respect
+///     <c>--byte-order</c> the same way real driver configs do.
+/// </summary>
+[Command("read", Description = "Read a single Modbus register or coil.")]
+public sealed class ReadCommand : ModbusCommandBase
+{
+    [CommandOption("region", 'r', Description =
+        "Coils / DiscreteInputs / InputRegisters / HoldingRegisters", IsRequired = true)]
+    public ModbusRegion Region { get; init; }
+
+    [CommandOption("address", 'a', Description =
+        "Zero-based address within the region.", IsRequired = true)]
+    public ushort Address { get; init; }
+
+    [CommandOption("type", 't', Description =
+        "Bool / Int16 / UInt16 / Int32 / UInt32 / Int64 / UInt64 / Float32 / Float64 / " +
+        "BitInRegister / String / Bcd16 / Bcd32", IsRequired = true)]
+    public ModbusDataType DataType { get; init; }
+
+    [CommandOption("byte-order", Description =
+        "BigEndian (default, spec ABCD) or WordSwap (CDAB). Ignored for single-register types.")]
+    public ModbusByteOrder ByteOrder { get; init; } = ModbusByteOrder.BigEndian;
+
+    [CommandOption("bit-index", Description =
+        "For type=BitInRegister: bit 0-15 LSB-first.")]
+    public byte BitIndex { get; init; }
+
+    [CommandOption("string-length", Description =
+        "For type=String: character count (2 per register, rounded up).")]
+    public ushort StringLength { get; init; }
+
+    [CommandOption("string-byte-order", Description =
+        "For type=String: HighByteFirst (standard) or LowByteFirst (DirectLOGIC et al).")]
+    public ModbusStringByteOrder StringByteOrder { get; init; } = ModbusStringByteOrder.HighByteFirst;
+
+    public override async ValueTask ExecuteAsync(IConsole console)
+    {
+        ConfigureLogging();
+        var ct = console.RegisterCancellationHandler();
+
+        var tagName = SynthesiseTagName(Region, Address, DataType);
+        var tag = new ModbusTagDefinition(
+            Name: tagName,
+            Region: Region,
+            Address: Address,
+            DataType: DataType,
+            Writable: false,
+            ByteOrder: ByteOrder,
+            BitIndex: BitIndex,
+            StringLength: StringLength,
+            StringByteOrder: StringByteOrder);
+        var options = BuildOptions([tag]);
+
+        await using var driver = new ModbusDriver(options, DriverInstanceId);
+        try
+        {
+            await driver.InitializeAsync("{}", ct);
+            var snapshot = await driver.ReadAsync([tagName], ct);
+            await console.Output.WriteLineAsync(SnapshotFormatter.Format(tagName, snapshot[0]));
+        }
+        finally
+        {
+            await driver.ShutdownAsync(CancellationToken.None);
+        }
+    }
+
+    /// <summary>
+    ///     Builds a human-readable tag name matching the operator's conceptual model
+    ///     (<c>HR[100]</c>, <c>Coil[5]</c>, <c>IR[42]</c>) — the driver treats the name
+    ///     purely as a lookup key, so any stable string works.
+    /// </summary>
+    internal static string SynthesiseTagName(
+        ModbusRegion region, ushort address, ModbusDataType type)
+    {
+        var prefix = region switch
+        {
+            ModbusRegion.Coils => "Coil",
+            ModbusRegion.DiscreteInputs => "DI",
+            ModbusRegion.InputRegisters => "IR",
+            ModbusRegion.HoldingRegisters => "HR",
+            _ => "Reg",
+        };
+        return $"{prefix}[{address}]:{type}";
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli/Commands/SubscribeCommand.cs

@@ -0,0 +1,92 @@
+using CliFx.Attributes;
+using CliFx.Infrastructure;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.Cli.Common;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Commands;
+
+/// <summary>
+///     Long-running poll of one Modbus register via the driver's <c>ISubscribable</c> surface
+///     (under the hood: <c>PollGroupEngine</c>). Prints each data-change event until the
+///     operator Ctrl+C's the CLI. Useful for watching a changing PLC signal during
+///     commissioning or while reproducing a customer bug.
+/// </summary>
+[Command("subscribe", Description = "Watch a Modbus register via polled subscription until Ctrl+C.")]
+public sealed class SubscribeCommand : ModbusCommandBase
+{
+    [CommandOption("region", 'r', Description =
+        "Coils / DiscreteInputs / InputRegisters / HoldingRegisters", IsRequired = true)]
+    public ModbusRegion Region { get; init; }
+
+    [CommandOption("address", 'a', Description = "Zero-based address within the region.", IsRequired = true)]
+    public ushort Address { get; init; }
+
+    [CommandOption("type", 't', Description =
+        "Bool / Int16 / UInt16 / Int32 / UInt32 / Int64 / UInt64 / Float32 / Float64 / " +
+        "BitInRegister / String / Bcd16 / Bcd32", IsRequired = true)]
+    public ModbusDataType DataType { get; init; }
+
+    [CommandOption("interval-ms", 'i', Description =
+        "Publishing interval in milliseconds (default 1000). The PollGroupEngine enforces " +
+        "a floor of ~250ms; values below it get rounded up.")]
+    public int IntervalMs { get; init; } = 1000;
+
+    [CommandOption("byte-order", Description =
+        "BigEndian (default) or WordSwap.")]
+    public ModbusByteOrder ByteOrder { get; init; } = ModbusByteOrder.BigEndian;
+
+    public override async ValueTask ExecuteAsync(IConsole console)
+    {
+        ConfigureLogging();
+        var ct = console.RegisterCancellationHandler();
+
+        var tagName = ReadCommand.SynthesiseTagName(Region, Address, DataType);
+        var tag = new ModbusTagDefinition(
+            Name: tagName,
+            Region: Region,
+            Address: Address,
+            DataType: DataType,
+            Writable: false,
+            ByteOrder: ByteOrder);
+        var options = BuildOptions([tag]);
+
+        await using var driver = new ModbusDriver(options, DriverInstanceId);
+        ISubscriptionHandle? handle = null;
+        try
+        {
+            await driver.InitializeAsync("{}", ct);
+
+            // Route every data-change event to the CliFx console (not System.Console — the
+            // analyzer flags it + IConsole is the testable abstraction).
+            driver.OnDataChange += (_, e) =>
+            {
+                var line = $"[{DateTime.UtcNow:HH:mm:ss.fff}] " +
+                    $"{e.FullReference} = {SnapshotFormatter.FormatValue(e.Snapshot.Value)} " +
+                    $"({SnapshotFormatter.FormatStatus(e.Snapshot.StatusCode)})";
+                console.Output.WriteLine(line);
+            };
+
+            handle = await driver.SubscribeAsync([tagName], TimeSpan.FromMilliseconds(IntervalMs), ct);
+
+            await console.Output.WriteLineAsync(
+                $"Subscribed to {tagName} @ {IntervalMs}ms. Ctrl+C to stop.");
+            try
+            {
+                await Task.Delay(System.Threading.Timeout.InfiniteTimeSpan, ct);
+            }
+            catch (OperationCanceledException)
+            {
+                // Expected on Ctrl+C — fall through to the unsubscribe in finally.
+            }
+        }
+        finally
+        {
+            if (handle is not null)
+            {
+                try { await driver.UnsubscribeAsync(handle, CancellationToken.None); }
+                catch { /* teardown best-effort */ }
+            }
+            await driver.ShutdownAsync(CancellationToken.None);
+        }
+    }
+}

src/ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli/Commands/WriteCommand.cs

@@ -0,0 +1,118 @@
+using System.Globalization;
+using CliFx.Attributes;
+using CliFx.Infrastructure;
+using ZB.MOM.WW.OtOpcUa.Core.Abstractions;
+using ZB.MOM.WW.OtOpcUa.Driver.Cli.Common;
+
+namespace ZB.MOM.WW.OtOpcUa.Driver.Modbus.Cli.Commands;
+
+/// <summary>
+///     Write one value to a Modbus coil or holding register. Mirrors <see cref="ReadCommand"/>'s
+///     region / address / type flags + adds <c>--value</c>. Input parsing respects the
+///     declared <c>--type</c> so you can write <c>--value=3.14 --type=Float32</c> without
+///     hex-encoding floats. The write is non-idempotent by default (driver's
+///     <c>WriteIdempotent=false</c>) — replay is the operator's choice, not the driver's.
+/// </summary>
+[Command("write", Description = "Write a single Modbus coil or holding register.")]
+public sealed class WriteCommand : ModbusCommandBase
+{
+    [CommandOption("region", 'r', Description =
+        "Coils or HoldingRegisters (the only writable regions per the protocol spec).",
+        IsRequired = true)]
+    public ModbusRegion Region { get; init; }
+
+    [CommandOption("address", 'a', Description =
+        "Zero-based address within the region.", IsRequired = true)]
+    public ushort Address { get; init; }
+
+    [CommandOption("type", 't', Description =
+        "Bool / Int16 / UInt16 / Int32 / UInt32 / Int64 / UInt64 / Float32 / Float64 / " +
+        "BitInRegister / String / Bcd16 / Bcd32", IsRequired = true)]
+    public ModbusDataType DataType { get; init; }
+
+    [CommandOption("value", 'v', Description =
+        "Value to write. Parsed per --type (booleans accept true/false/0/1).",
+        IsRequired = true)]
+    public string Value { get; init; } = default!;
+
+    [CommandOption("byte-order", Description =
+        "BigEndian (default, ABCD) or WordSwap (CDAB). Ignored for single-register types.")]
+    public ModbusByteOrder ByteOrder { get; init; } = ModbusByteOrder.BigEndian;
+
+    [CommandOption("bit-index", Description =
+        "For type=BitInRegister: which bit of the holding register (0-15, LSB-first).")]
+    public byte BitIndex { get; init; }
+
+    [CommandOption("string-length", Description =
+        "For type=String: character count (2 per register, rounded up).")]
+    public ushort StringLength { get; init; }
+
+    [CommandOption("string-byte-order", Description =
+        "For type=String: HighByteFirst (standard) or LowByteFirst (DirectLOGIC).")]
+    public ModbusStringByteOrder StringByteOrder { get; init; } = ModbusStringByteOrder.HighByteFirst;
+
+    public override async ValueTask ExecuteAsync(IConsole console)
+    {
+        ConfigureLogging();
+        var ct = console.RegisterCancellationHandler();
+
+        if (Region is not (ModbusRegion.Coils or ModbusRegion.HoldingRegisters))
+            throw new CliFx.Exceptions.CommandException(
+                $"Region '{Region}' is read-only in the Modbus spec; writes require Coils or HoldingRegisters.");
+
+        var tagName = ReadCommand.SynthesiseTagName(Region, Address, DataType);
+        var tag = new ModbusTagDefinition(
+            Name: tagName,
+            Region: Region,
+            Address: Address,
+            DataType: DataType,
+            Writable: true,
+            ByteOrder: ByteOrder,
+            BitIndex: BitIndex,
+            StringLength: StringLength,
+            StringByteOrder: StringByteOrder);
+        var options = BuildOptions([tag]);
+
+        var parsed = ParseValue(Value, DataType);
+
+        await using var driver = new ModbusDriver(options, DriverInstanceId);
+        try
+        {
+            await driver.InitializeAsync("{}", ct);
+            var results = await driver.WriteAsync([new WriteRequest(tagName, parsed)], ct);
+            await console.Output.WriteLineAsync(SnapshotFormatter.FormatWrite(tagName, results[0]));
+        }
+        finally
+        {
+            await driver.ShutdownAsync(CancellationToken.None);
+        }
+    }
+
+    /// <summary>
+    ///     Parse the operator's <c>--value</c> string into the CLR type the driver expects
+    ///     for the declared <see cref="ModbusDataType"/>. Uses invariant culture everywhere
+    ///     so <c>3.14</c> and <c>3,14</c> don't swap meaning between runs.
+    /// </summary>
+    internal static object ParseValue(string raw, ModbusDataType type) => type switch
+    {
+        ModbusDataType.Bool or ModbusDataType.BitInRegister => ParseBool(raw),
+        ModbusDataType.Int16 => short.Parse(raw, CultureInfo.InvariantCulture),
+        ModbusDataType.UInt16 or ModbusDataType.Bcd16 => ushort.Parse(raw, CultureInfo.InvariantCulture),
+        ModbusDataType.Int32 => int.Parse(raw, CultureInfo.InvariantCulture),
+        ModbusDataType.UInt32 or ModbusDataType.Bcd32 => uint.Parse(raw, CultureInfo.InvariantCulture),
+        ModbusDataType.Int64 => long.Parse(raw, CultureInfo.InvariantCulture),
+        ModbusDataType.UInt64 => ulong.Parse(raw, CultureInfo.InvariantCulture),
+        ModbusDataType.Float32 => float.Parse(raw, CultureInfo.InvariantCulture),
+        ModbusDataType.Float64 => double.Parse(raw, CultureInfo.InvariantCulture),
+        ModbusDataType.String => raw,
+        _ => throw new CliFx.Exceptions.CommandException($"Unsupported DataType '{type}' for write."),
+    };
+
+    private static bool ParseBool(string raw) => raw.Trim().ToLowerInvariant() switch
+    {
+        "1" or "true" or "on" or "yes" => true,
+        "0" or "false" or "off" or "no" => false,
+        _ => throw new CliFx.Exceptions.CommandException(
+            $"Boolean value '{raw}' is not recognised. Use true/false, 1/0, on/off, or yes/no."),
+    };
+}