feat: Copy/archive input XML files into the output directory

[kdrienCG]

(Previously #4003)

This PR proposes to archive the XML input deck to the output directory, so that every set of results is accompanied by the exact input that produced it.

When GEOS is run with the new archive command line option (-a LEVEL), all XML input files (and every files that are included via the <Included> XML tag) are flattened into a single file in a timestamped directory.

Following suggestions from @rrsettgast and @bd713, the XML input files are "flattened" into a single XML file.

The following command line argument is added to specifiy the level of archiving wanted:

-a, --archive,  Archiving strategy's level:
                  0 = no archiving,
                  1 = XML inputs only (default),
                  2 = XML inputs and the XSD schema

---

Given a run like:

geosx -i foo.xml -o OUTPUT/ -a 2

The following is created:

.
└─ OUTPUT/   
   └─ archive_inputFiles/
      └─ 20260320_103034/
         ├─ input.xml
         └─ schema.xsd

---

Previous proposition

This PR proposes to automatically archive the XML input deck to the output directory, so that every set of results is accompanied by the exact input that produced it.

When GEOS is run with an output directory specified (-o <dir>), all XML input files (and every files that are included via the <Included> XML tag) are copied into the output directory with a timestamp.

---

Given a run like:

geosx -i foo.xml -o OUTPUT/

The following is created:

.
└─ OUTPUT/   
   └─ archive_inputFiles/
      └─ 20260320_103034/
         ├─ foo.xml
         │
         ├─ include1.xml
         │
         └─ some_subdir/
            └─ include2.xml

When included files are "behind" the input tree of the main XML, the following structure is proposed:

.
└─ OUTPUT/   
   └─ archive_inputFiles/
      └─ 20260320_103034/
         ├─ foo.xml
         │
         ├─ __one_level_behind_include.xml
         │
         ├─ __one_level_behind_folder/           
         |  └─ baz.xml
         │
         └─ ____two_level_behind_folder/      
            └─ buzz.xml

Files outside the input tree (reached via ../) are prefixed with __ for every ../ from foo.xml.

[herve-gross]

@bd713 moving this to the review queue

[bd713]

Thanks, @kdrienCG.

Could you also update the GEOS documentation accordingly?
Typically QuickStart.rst for the new CLI flag, and maybe worth a brief description under Advanced XML Features.

[MelReyCG]

As there is no unitTest, how did you test this feature?

[MelReyCG]

Don't you want to continue; here?

[MelReyCG]

Are you sure that you don't break something here? xmlWrapper::xmlNode is a wrapper around internal pugi data, I'm afraid you remove xmlWrapper::filePathString & xmlWrapper::charOffsetString definitively. Does it affect the line logging feature in GEOS_ERROR/GEOS_WARNING?

[kdrienCG]

stripMetadataAttributes() runs on a copy/separate XML doc (flatDoc). It should not affect the XML document used for input parsing

[MelReyCG]

Suggested change

	if( level == 0 || inputFileNames.empty() || outputDirectory.empty() )
	if( level <= 0 || inputFileNames.empty() || outputDirectory.empty() )

?

[MelReyCG]

I would add a note that it should not be called on multiple ranks