feat!: serial expect/send automation with monitor mode

Rework the serial module from a single read-only expect into a
non-interactive automation engine driven entirely by up-front arguments,
suitable for scripts and machines.

Modes:
  - Monitor (no steps): stream the serial output to the client until the
    session is cancelled or -t elapses (a success).
  - Sequence (one or more steps): run expect / send / send-raw steps in
    order; the run fails on the first expect that times out.

Grammar: [-t <dur>] [-eol cr|lf|crlf|none] [-keep-escapes] [--] <step>... where
a step is expect <regex> / send <data> / send-raw <data>. send payloads support
the escapes \r \n \t \\ and \xNN (e.g. \x03 for Ctrl-C). Per-step progress is
reported to the client as "--- [n/total] matched/sent ... ---" markers. If the
last step is a send, output is shown briefly afterwards so the DUT's reply is
visible.

A 'delay' module option (with: delay, default 50ms; "0s" disables) paces input
by pausing before each send, for consoles that present a prompt before the tty
is ready to read.

By default terminal escape sequences (cursor moves, colour, queries) are
stripped from the output before it is shown or matched, so they don't break
expect patterns; pass -keep-escapes to forward the raw stream (e.g. binary
data).

Internals: a port interface plus a per-run engine with a 64 KiB rolling
match buffer (matches across reads, never newline-reset) and a tee that
forwards serial output to the client. Structured so an interactive
session.Console mode can be added later.

Also migrate the serial backend from the unmaintained tarm/serial to
go.bug.st/serial, and update the module README and example config.

BREAKING CHANGE: The serial module's invocation changed. It no longer accepts
a single optional expect regex; callers must pass an explicit step sequence.
For example, `serial "(?i)hello"` becomes `serial -- expect "(?i)hello"`.
Existing configs/scripts using the old form must be updated.

Signed-off-by: Jens Topp <jens.topp@blindspot.software>

Author: jenstopp

.golangci.yml

@@ -152,6 +152,7 @@ linters:
         - DeviceServiceClient
         - Formatter
         - gpio
+        - port
 
     lll:
       line-length: 140

go.mod

@@ -8,7 +8,7 @@ require (
 	github.com/go-playground/validator/v10 v10.30.2
 	github.com/google/go-cmp v0.7.0
 	github.com/stianeikeland/go-rpio/v4 v4.6.0
-	github.com/tarm/serial v0.0.0-20180830185346-98f6abe2eb07
+	go.bug.st/serial v1.7.1
 	golang.org/x/crypto v0.51.0
 	google.golang.org/protobuf v1.36.11
 	gopkg.in/yaml.v3 v3.0.1

go.sum

@@ -53,8 +53,8 @@ github.com/stianeikeland/go-rpio/v4 v4.6.0 h1:eAJgtw3jTtvn/CqwbC82ntcS+dtzUTgo5q
 github.com/stianeikeland/go-rpio/v4 v4.6.0/go.mod h1:A3GvHxC1Om5zaId+HqB3HKqx4K/AqeckxB7qRjxMK7o=
 github.com/stretchr/testify v1.8.4 h1:CcVxjf3Q8PM0mHUKJCdn+eZZtm5yQwehR5yeSVQQcUk=
 github.com/stretchr/testify v1.8.4/go.mod h1:sz/lmYIOXD/1dqDmKjjqLyZ2RngseejIcXlSw2iwfAo=
-github.com/tarm/serial v0.0.0-20180830185346-98f6abe2eb07 h1:UyzmZLoiDWMRywV4DUYb9Fbt8uiOSooupjTq10vpvnU=
-github.com/tarm/serial v0.0.0-20180830185346-98f6abe2eb07/go.mod h1:kDXzergiv9cbyO7IOYJZWg1U88JhDg3PB6klq9Hg2pA=
+go.bug.st/serial v1.7.1 h1:5aP8wYL0UjEYOVs3oPAGscjaSfRQLHtCvBFXNN/rwtc=
+go.bug.st/serial v1.7.1/go.mod h1:d0MmS16Qt9b1m06yoYRNUXhRRTJV5Qg2S5EKqQtnayQ=
 golang.org/x/crypto v0.51.0 h1:IBPXwPfKxY7cWQZ38ZCIRPI50YLeevDLlLnyC5wRGTI=
 golang.org/x/crypto v0.51.0/go.mod h1:8AdwkbraGNABw2kOX6YFPs3WM22XqI4EXEd8g+x7Oc8=
 golang.org/x/net v0.53.0 h1:d+qAbo5L0orcWAr0a9JweQpjXF19LMXJE8Ey7hwOdUA=

pkg/module/serial/README.md

@@ -2,31 +2,109 @@ The serial package provides a single module:
 
 # Serial
 
-This module establishes a serial connection to the DUT from the _dutagent_ and forwards the output.
+This module connects to the DUT's serial port from the _dutagent_, forwards the
+serial output it reads to the _dutctl_ client, and (optionally) drives a
+scripted `send`/`expect` sequence against the port.
+
+All input is supplied up front as arguments, which makes the module suitable for
+scripts and automated callers. With **no step arguments** it runs in **monitor**
+mode: it streams the serial output until the session is cancelled (or `-t`
+elapses). It does not use an interactive console (`session.Console`) yet.
 
 ```
 ARGUMENTS:
-	[-t <duration>] [<expect>]
-
-If a regex is provided, the module will wait for the regex to match on the serial output, 
-then exit with success.
-If no expect string is provided, the module will read from the serial port until it is terminated by a signal (e.g. Ctrl-C).
-The  expect string supports regular expressions. The optional -t flag specifies the maximum time to wait for the regex to match.
-The regex is passed to the shell as a single argument. The regex must not contain any newlines.
-Quote the regex if it contains spaces or special characters. E.g.: "(?i)hello\s+world!? dutctl"
+	[-t <duration>] [-eol cr|lf|crlf|none] [-keep-escapes]                 (monitor: stream output)
+	[-t <duration>] [-eol cr|lf|crlf|none] [-keep-escapes] [--] <step>...  (run a step sequence)
+
+	step := expect <regex> | send <data> | send-raw <data>
 ```
 
-The syntax of the regular expressions accepted is the syntax accepted by RE2 and described at https://golang.org/s/re2syntax.
+## Steps
 
-The module is read-only at that time and does not support sending bytes over the serial connection.
+Steps run in order, top to bottom. The run exits with success once all steps
+complete, and with failure on the first `expect` that times out (or on a serial
+error).
 
-See [serial-example-cfg.yml](./serial-example-cfg.yml) for examples. 
+| Step | Behaviour |
+|------|-----------|
+| `expect <re2>` | Wait until the serial output matches the [RE2] regular expression. A plain string is a valid regex that matches itself; escape regex metacharacters (`. $ * + ? ( ) [ ] { } ^ \| \`) to match them literally, e.g. `expect '192\.168\.0\.1'`. |
+| `send <data>` | Write `<data>` followed by the configured line ending (see `-eol`) to the port. |
+| `send-raw <data>` | Write `<data>` verbatim, with no line ending appended. |
 
-## Configuration Options
+`send`/`send-raw` data supports the escapes `\r` `\n` `\t` `\\` and `\xNN`
+(e.g. `\x03` for Ctrl-C). Each step value is a single argument, so quote values
+that contain spaces.
+
+If the last step is a `send`, the module keeps showing output for a moment
+afterwards so the DUT's reply to that final input is visible.
+
+## Monitor mode
+
+Invoking `serial` with **no step arguments** streams the serial output to the
+client until the session is cancelled (Ctrl-C / disconnect), or until `-t`
+elapses — reaching the `-t` deadline in monitor mode is a success. No matching
+is done.
+
+## Flags
+
+| Flag | Description |
+|------|-------------|
+| `-t <duration>` | Global timeout for the whole run (e.g. `30s`, `3m`). `0` (default) means no timeout. |
+| `-eol cr\|lf\|crlf\|none` | Line ending appended by `send`. Default `cr` (`\r`), which is what serial consoles expect on Enter. |
+| `-keep-escapes` | Keep terminal escape sequences in the output instead of stripping them (e.g. for binary data or exact-byte capture). |
+
+The `--` separator before the steps is optional; it is only needed if a step
+value would otherwise look like a flag.
+
+## Output and matching notes
+
+- Serial output is forwarded to the client whenever the module is reading the
+  port: in monitor mode, while an `expect` is waiting, and (if the last step is
+  a `send`) for a moment afterwards so its reply is visible. Between sends with
+  no following `expect` nothing is read, so nothing is forwarded. Step progress
+  is reported with `--- [n/total] matched/sent … ---` markers.
+- Terminal escape sequences (cursor moves, colour, queries) are stripped from
+  the output before it is shown or matched, so they don't interfere with
+  patterns. Pass `-keep-escapes` to keep them (for binary data or exact-byte
+  capture).
+- Expect matching uses a rolling window of the most recent **64 KiB** of
+  output, so a single pattern cannot span more than that.
+- Match on distinctive markers/prompts rather than `^`/`$` anchors — the rolling
+  buffer has no stable line-start or end-of-text.
+- The DUT may echo what you send, so an `expect` immediately after a `send` can
+  match your own input rather than the device's reply.
 
-| Option | Value  | Description                                            |
-|--------|--------|--------------------------------------------------------|
-| port   | string | Hostname or IP address of the DUT                      |
-| baud   | int    | Port number of the SSH server on the DUT (default: 22) |
+The syntax of the regular expressions accepted is the syntax accepted by RE2 and
+described at https://golang.org/s/re2syntax.
+
+## Examples
+
+```
+# Monitor the console (stream until cancelled).
+serial
+
+# Wait for a boot marker, then succeed.
+serial -- expect 'Welcome to'
+
+# Log in and run a command.
+serial -t 60s -- expect 'login:' send root expect 'Password:' send secret expect '# ' send reboot
+
+# Send Ctrl-C, then expect prompt.
+serial -- send-raw '\x03' expect '=>'
+
+# Reboot, then see the output that follows the final send.
+serial -- expect '# ' send reboot
+```
+
+See [serial-example-cfg.yml](./serial-example-cfg.yml) for a configuration
+example.
+
+## Configuration Options
 
+| Option | Value  | Description                                                         |
+|--------|--------|---------------------------------------------------------------------|
+| port   | string | Path to the serial device on the dutagent (e.g. `/dev/ttyUSB0`)     |
+| baud   | int    | Baud rate of the serial connection (default: 115200)                |
+| delay  | string | Pause before each send, e.g. `200ms` (default: 50ms; `0s` disables) |
 
+[RE2]: https://golang.org/s/re2syntax