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!

[pditommaso]

The problem with this PR is that encourages a fragmentation across singularity and and docker build, while we should try to limit as much as possible .

I think it would be better to limit commands attribute to only run commands in the container build ie. assuming RUN for Docker build and keep as it is for Singularity.

I've reverted by commit from master.

[munishchouhan]

The problem with this PR is that encourages a fragmentation across singularity and and docker build, while we should try to limit as much as possible .

I think it would be better to limit commands attribute to only run commands in the container build ie. assuming RUN for Docker build and keep as it is for Singularity.

I've reverted by commit from master.

Ok, SO only RUN command should be allowed in docker build?

[pditommaso]

It would be assumed the commands is one-liner that can run in the build process (without RUN prefix). However for backward compatibility, if RUN is provided, it will be stripped out