Added validation and docs for commands in container API

[munishchouhan]

Summary

Updated TypeSpec API definitions and documentation to clarify that the commands field in CranOpts, CondaOpts, and PixiOpts requires valid Dockerfile instruction keywords
(e.g., RUN, CMD, ENTRYPOINT, USER).

Changes

• TypeSpec models: Updated documentation and examples for CranOpts, CondaOpts, and PixiOpts to show commands must start with Dockerfile keywords
• API docs: Updated commands field description and examples in docs/api.md
• DockerHelper (wave-utils/src/main/java/io/seqera/wave/util/DockerHelper.java):
• Added validateCommands(List<String>) method to validate command lists
• Added isValidDockerCommand(String) method to check individual commands
• Added getValidKeywords() method to expose the set of valid keywords
• Supports all 17 standard Dockerfile instruction keywords:
  • FROM, RUN, CMD, LABEL, EXPOSE, ENV, ADD, COPY
  • ENTRYPOINT, VOLUME, USER, WORKDIR, ARG, ONBUILD
  • STOPSIGNAL, HEALTHCHECK, SHELL
• Uses regex pattern matching (^\\s*([A-Z]+)\\b) to extract and validate keywords
• Throws IllegalArgumentException with detailed error message including command index

Integration Points

• CranHelper (src/main/groovy/io/seqera/wave/util/CranHelper.groovy):

  • Updated addCommands method to call DockerHelper.validateCommands()
  • Validation only applies when generating Dockerfiles, not Singularity files

• TemplateUtils (src/main/java/io/seqera/wave/util/TemplateUtils.java):

  • Updated addCommands method to call DockerHelper.validateCommands()
  • Affects CondaOpts (v1 and v2) and PixiOpts
  • Validation only applies when generating Dockerfiles, not Singularity files

Test Coverage

• DockerHelperTest (wave-utils/src/test/groovy/io/seqera/wave/util/DockerHelperTest.groovy):

  • Added comprehensive validation tests (lines 389-523)
  • Tests for all valid keywords
  • Tests for invalid commands (missing keywords, lowercase, wrong keywords)
  • Tests for null/empty command lists
  • Tests for various command formats (whitespace, tabs, multi-line)

• CranHelperTest (src/test/groovy/io/seqera/wave/util/CranHelperTest.groovy):

  • Added validation tests for CRAN-specific scenarios
  • Tests for both Dockerfile and Singularity format handling

• TemplateUtilsTest (src/test/groovy/io/seqera/wave/util/TemplateUtilsTest.groovy):

  • Added validation tests for CondaOpts and PixiOpts (lines 940-1056)
  • Tests for both valid and invalid command scenarios

Examples Updated

Before (would cause Docker build error)

{
  "cranOpts": {
    "commands": ["apt-get update"]
  }
}

After (valid)

{
  "cranOpts": {
    "commands": [
      "RUN apt-get update",
      "ENV MY_VAR=value",
      "USER root",
      "WORKDIR /app"
    ]
  }
}

[munishchouhan]

tested locally:

1. CONDA

wave % curl --location 'http://localhost:9090/v1alpha2/container' \
--header 'Content-Type: application/json' \
--data '{
"packages": {
"type": "CONDA",
"entries": [
"dplyr",
"ggplot2",
"bioc::GenomicRanges"
],
"channels": [
"cran",
"bioconductor"
],
"condaOpts": {
"rImage": "rocker/r-ver:4.4.1",
"basePackages": "littler r-cran-docopt",
"commands": [
"apt-get update",
"apt-get install -y libcurl4-openssl-dev"
]
}
},
"format": "d",
"containerPlatform": "linux/amd64"
}'
{"message":"Invalid Docker command at index 0: 'apt-get update'. Commands must start with a valid Dockerfile instruction keyword (e.g., RUN, CMD, ENV, COPY, etc.) - Error ID: 93147f3266bc"}

2. CRAN

curl --location 'http://localhost:9090/v1alpha2/container' \
--header 'Content-Type: application/json' \
--data '{
"packages": {
"type": "CRAN",
"entries": [
"dplyr",
"ggplot2",
"bioc::GenomicRanges"
],
"channels": [
"cran",
"bioconductor"
],
"cranOpts": {
"rImage": "rocker/r-ver:4.4.1",
"basePackages": "littler r-cran-docopt",
"commands": [
"apt-get update",
"apt-get install -y libcurl4-openssl-dev"
]
}
},
"format": "d",
"containerPlatform": "linux/amd64"
}'
{"message":"Invalid Docker command at index 0: 'apt-get update'. Commands must start with a valid Dockerfile instruction keyword (e.g., RUN, CMD, ENV, COPY, etc.) - Error ID: 26fba02a4f2e"}

[ewels]

Nice, thanks!