refactor!: change naming of dutagent config items

Renames YAML field names in dutagent configuration:
modules → uses and options → with for improved clarity and consistency
with common workflow syntax patterns.

Changes:
- Added YAML tags to Modules and Options struct fields to map new field names
- Updated documentation tables and descriptions to reflect new field names
- Migrated all example configuration files to new syntax

BREAKING CHANGE: The dutagent configuration changed. Existing configurations
must be updated in the following way:
From
commands:
  - name: example
    modules:
      - name: flash
        options:
          file: firmware.bin
To
commands:
  - name: example
    uses:
      - name: flash
        with:
          file: firmware.bin

The old field names (modules, options) are no longer supported.

Signed-off-by: Fabian Wienand <fabian.wienand@9elements.com>

Author: RiSKeD

cmds/exp/contrib/config-1.yaml

@@ -6,6 +6,6 @@ devices:
     cmds:
       status:
         desc: "Report status"
-        modules:
+        uses:
           - module: dummy-status
             main: true

cmds/exp/contrib/config-2.yaml

@@ -6,11 +6,11 @@ devices:
     cmds:
       status:
         desc: "Report status"
-        modules:
+        uses:
           - module: dummy-status
             main: true
       repeat:
         desc: "Repeat input"
-        modules:
+        uses:
           - module: dummy-repeat
             main: true

contrib/dutagent-cfg-example.yaml

@@ -6,36 +6,36 @@ devices:
     cmds:
       status:
         desc: "Report status"
-        modules:
+        uses:
           - module: dummy-status
             main: true
   device2:
     desc: "Device 2"
     cmds:
       status:
         desc: "Report status"
-        modules:
+        uses:
           - module: dummy-status
             main: true
       repeat:
         desc: "Repeat input"
-        modules:
+        uses:
           - module: dummy-repeat
             main: true
   device3:
     desc: "Device 3"
     cmds:
       status:
         desc: "Report status"
-        modules:
+        uses:
           - module: dummy-status
             main: true
       file-transfer:
         desc: "Transfer a file"
-        modules:
+        uses:
           - module: dummy-status
-            args: 
+            args:
               - foo
               - bar
           - module: dummy-ft
-            main: true
+            main: true

docs/dutagent-config.md

@@ -34,7 +34,7 @@ could look like.
 | Attribute   | Type                 | Default | Description                                                                                                                                                                                                                                                                                                                                                                                                                                            | Mandatory |
 |-------------|----------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-----------|
 | description | string               |         | Command description                                                                                                                                                                                                                                                                                                                                                                                                                                    | no        |
-| Modules     | [] [Module](#Module) |         | A command may be composed of multiple steps to achieve its purpose. The list of modules represent these steps.The order of this list is important, though. Exactly one of the modules must be set as the main module. All arguments to a command are passed to its main module. The main modules usage information is also used as the command help text. If a Command is composed of only one module, this module becomes the main module implicitly. | yes       |
+| uses     | [] [Module](#Module) |         | A command may be composed of multiple steps to achieve its purpose. The list of modules represent these steps.The order of this list is important, though. Exactly one of the modules must be set as the main module. All arguments to a command are passed to its main module. The main modules usage information is also used as the command help text. If a Command is composed of only one module, this module becomes the main module implicitly. | yes       |
 
 ### Module
 
@@ -43,10 +43,10 @@ could look like.
 | module    | string         |         | The module's name also serves as its identifier and must be unique.                                                                                                                                | yes                               |
 | main      | bool           | false   | All arguments to a command are passed to its main module. The main modules usage information is also used as the command help text. Can be omitted, if only one modules exists within the command. | exactly once per command          |
 | args      | []string       | nil     | If a module is **not** an commands main module, it does not get any arguments passed at runtime, instead arguments can be passed here.                                                             | no, only applies if `main` is set |
-| options   | map[string]any |         | A module can be configured via key-value pairs. The type of the value is generic and depends on the implementation of the module.                                                                  | yes                               |
+| with   | map[string]any |         | A module can be configured via key-value pairs. The type of the value is generic and depends on the implementation of the module.                                                                  | yes                               |
 
 > [!IMPORTANT]  
-> Refer to option keys of a module in all-lowercase representation of the modules exported fields.
+> Refer to `with` keys of a module in all-lowercase representation of the module's exported fields.
 > See the respective module's documentation for details.
 
 ### Example config file

docs/module_guide.md

@@ -57,9 +57,8 @@ _ "github.com/BlindspotSoftware/dutctl/pkg/module/dummy"
 ```
 
 ## Configuration
-
-A module can be dynamically configured when starting a _dutagent_ using the option map in the
-[_dutagent_ configuration](./dutagent-config.md#module). A module must be of type `struct` and have the options as
+A module can be dynamically configured when starting a _dutagent_ using the `with` map in the
+[_dutagent_ configuration](./dutagent-config.md#module). A module must be of type `struct` and have the configuration as
 fields. The parser will set the struct fields to match the map keys.
 
 For example, a module like the one below, registered with `ID` = `"my-module"`.
@@ -81,15 +80,15 @@ devices:
     cmds:
       some-cmd:
         desc: My cool module
-        modules:
+        uses:
           - module: my-module
-            options:
+            with:
               foo: 42
 ```
 
 > [!IMPORTANT]  
-> It is imperative that the module's documentation and Help() function provide a good explanation of its options.
-> The option map in the configuration file is generic (string → any type), so it is important that the user knows what
+> It is imperative that the module's documentation and Help() function provide a good explanation of its configuration.
+> The `with` map in the configuration file is generic (string → any type), so it is important that the user knows what
 > values are expected.
 
 The [project's dummy modules](../pkg/module/dummy/dummy_status.go) show all the details of a complete implementation.

pkg/dut/dut.go

@@ -90,7 +90,7 @@ type Device struct {
 // modules and are executed in the order they are defined.
 type Command struct {
 	Desc    string
-	Modules []Module
+	Modules []Module `yaml:"uses"`
 }
 
 // commandAlias is used when parsing YAML to avoid recursion.
@@ -153,7 +153,7 @@ type ModuleConfig struct {
 	Name    string `yaml:"module"`
 	Main    bool
 	Args    []string
-	Options map[string]any
+	Options map[string]any `yaml:"with"`
 }
 
 // UnmarshalYAML unmarshals a Module from a YAML node and adds custom validation.
@@ -178,7 +178,7 @@ func (m *Module) UnmarshalYAML(node *yaml.Node) error {
 		return err
 	}
 
-	// validate Module options
+	// validate Module configuration
 	validate := validator.New()
 
 	err = validate.Struct(m.Module)

pkg/module/agent/README.md

@@ -18,7 +18,7 @@ The agent-status module can be used in a command like so.
 cmds:
       system-info:
         desc: "This simple command reports information about the dutagent system via the agent-status module."
-        modules:
+        uses:
           - module: agent-status
             main: true
 ```

pkg/module/file/file-example-cfg.yml

@@ -8,10 +8,10 @@ devices:
       # Upload any file - preserves directory structure
       upload:
         desc: "Upload file to device"
-        modules:
+        uses:
           - module: file
             main: true
-            options:
+            with:
               operation: "upload"
         # Usage:
         #   dutctl example-device upload ./build/firmware.bin
@@ -23,10 +23,10 @@ devices:
       # Upload with destination configured - arg becomes source
       upload-script:
         desc: "Upload and install a script"
-        modules:
+        uses:
           - module: file
             main: true
-            options:
+            with:
               operation: "upload"
               destination: "/opt/scripts/install.sh"
               permission: "0755" # Make it executable
@@ -37,10 +37,10 @@ devices:
       # Download with source configured - arg becomes destination
       fetch-logs:
         desc: "Download logs from device"
-        modules:
+        uses:
           - module: file
             main: true
-            options:
+            with:
               operation: "download"
               source: "/var/log.txt"
         # Usage:
@@ -50,10 +50,10 @@ devices:
       # Upload with both paths configured - no arg allowed
       upload-config:
         desc: "Upload configuration file with fixed paths"
-        modules:
+        uses:
           - module: file
             main: true
-            options:
+            with:
               operation: "upload"
               source: "./configs/device.conf"
               destination: "/etc/device/device.conf"

pkg/module/flash/flash-example-cfg.yml

@@ -7,9 +7,9 @@ devices:
       flash:
         desc: |
           Basic demo of the Flash module.
-        modules:
+        uses:
           - module: flash
             main: true
-            options:
+            with:
               tool: "/usr/sbin/flashprog"
               programmer: "dediprog"

pkg/module/gpio/gpio-example-cfg.yml

@@ -6,24 +6,24 @@ devices:
     cmds:
       fire:
         desc: "Push the big red button"
-        modules:
+        uses:
           - module: gpio-button
             main: true
-            options:
+            with:
               pin: 9
       reset:
         desc: "Reset the rocket"
-        modules:
+        uses:
           - module: gpio-button
             main: true
-            options:
+            with:
               pin: 10
               activelow: true
       light:
         desc: "Turn on the light"
-        modules:
+        uses:
           - module: gpio-switch
             main: true
-            options:
+            with:
               pin: 11
               initial: on