Add --settings flag to pass a Maven settings.xml

Thread an optional settings.xml path through to every Maven invocation
via -s, exposed as a --settings CLI option on smelt and melt and a
[common] settings key in pombast.toml (resolved relative to the config
file). This lets callers supply mirrors, credentials, or per-repository
update policies without editing their user-wide ~/.m2/settings.xml.

The motivating case is stale "cached failure" resolution: a settings.xml
setting updatePolicy to interval:120 shrinks the retry window from the
24h default to 2h, so a transiently-missing dependency self-heals on a
subsequent run without forcing a full -U re-resolution on every
component and without waiting a full 24 hours for the recheck.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: ctrueden

src/pombast/cli/_app.py

@@ -71,6 +71,14 @@ def cli() -> None:
     default=None,
     help="Path to pombast.toml configuration file.",
 )
+@click.option(
+    "--settings",
+    "settings",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Maven settings.xml passed to every build via -s "
+    "(for mirrors, credentials, or repository update policies).",
+)
 @click.option(
     "--build-dir",
     "output_dir",
@@ -130,6 +138,7 @@ def smelt_cmd(
     exclude: tuple[str, ...],
     repository: tuple[str, ...],
     config: Path | None,
+    settings: Path | None,
     output_dir: Path,
     prune: bool,
     force: bool,
@@ -168,6 +177,7 @@ def smelt_cmd(
         includes=list(include),
         excludes=list(exclude),
         repositories=effective_repositories,
+        settings=settings or pombast_config.settings,
         output_dir=output_dir,
         prune=prune,
         force=force,
@@ -227,6 +237,14 @@ def smelt_cmd(
     default=None,
     help="Path to pombast.toml configuration file.",
 )
+@click.option(
+    "--settings",
+    "settings",
+    type=click.Path(exists=True, dir_okay=False, path_type=Path),
+    default=None,
+    help="Maven settings.xml passed to the mega-melt build via -s "
+    "(for mirrors, credentials, or repository update policies).",
+)
 @click.option(
     "--build-dir",
     "output_dir",
@@ -260,6 +278,7 @@ def melt_cmd(
     exclude: tuple[str, ...],
     repository: tuple[str, ...],
     config: Path | None,
+    settings: Path | None,
     output_dir: Path,
     force: bool,
     java_version: int | None,
@@ -290,6 +309,7 @@ def melt_cmd(
     melt_config = MeltConfig(
         bom=bom,
         repositories=effective_repositories,
+        settings=settings or pombast_config.settings,
         output_dir=output_dir,
         force=force,
         includes=list(include),

src/pombast/config/_settings.py

@@ -114,6 +114,7 @@ class PombastConfig:
     filter: FilterConfig = field(default_factory=FilterConfig)
     default_java: int | None = None
     repositories: dict[str, str] = field(default_factory=dict)
+    settings: Path | None = None  # Maven settings.xml passed to every build (-s)
     smelt_output: Path | None = None  # where `smelt` writes its JSON report
     skip_tests: list[str] = field(default_factory=list)
     remove_tests: dict[str, list[str]] = field(default_factory=dict)
@@ -197,6 +198,7 @@ def resolve(section: dict, key: str) -> Path | None:
             filter=filter_config,
             default_java=int(default_java) if default_java is not None else None,
             repositories=parse_repo_specs(common_data.get("repositories", [])),
+            settings=resolve(common_data, "settings"),
             smelt_output=resolve(smelt_data, "output"),
             skip_tests=smelt_data.get("skip-tests", []),
             remove_tests=data.get("remove-tests", {}),
@@ -234,6 +236,7 @@ class PipelineConfig:
     includes: list[str] = field(default_factory=list)
     excludes: list[str] = field(default_factory=list)
     repositories: dict[str, str] = field(default_factory=dict)
+    settings: Path | None = None
     output_dir: Path = field(default_factory=lambda: Path("target") / "pombast")
     success_cache_dir: Path | None = None
     prune: bool = False
@@ -251,6 +254,7 @@ class MeltConfig:
 
     bom: str
     repositories: dict[str, str] = field(default_factory=dict)
+    settings: Path | None = None
     output_dir: Path = field(default_factory=lambda: Path("target") / "pombast")
     force: bool = False
     includes: list[str] = field(default_factory=list)

src/pombast/core/_melt_pipeline.py

@@ -71,6 +71,7 @@ def run(self) -> MeltResult:
                 mega_melt_dir,
                 java_home=java_home,
                 extra_properties=maven_properties or None,
+                settings=self.config.settings,
             )
         except Exception as e:
             _log.error("Mega-melt failed: %s", e)

src/pombast/core/_pipeline.py

@@ -151,6 +151,7 @@ def run(self) -> ValidationReport:
                 **self.config.maven_properties,
             },
             test_binary=self.config.test_binary,
+            settings=self.config.settings,
         )
 
         # Precompute changed G:A set once for prune filtering.

src/pombast/maven/_builder.py

@@ -58,12 +58,14 @@ def __init__(
         success_cache: SuccessCache | None = None,
         extra_properties: dict[str, str] | None = None,
         test_binary: bool = True,
+        settings: Path | None = None,
     ) -> None:
         self.output_dir = output_dir
         self.ctx = ctx
         self.success_cache = success_cache or SuccessCache()
         self.extra_properties = extra_properties or {}
         self.test_binary = test_binary
+        self.settings = settings
 
     def build_and_test(
         self,
@@ -123,6 +125,7 @@ def build_and_test(
                 extra_properties=merged,
                 log_path=source_log_path,
                 color=True,
+                settings=self.settings,
             )
             duration = time.monotonic() - start
 
@@ -219,6 +222,7 @@ def _test_binary(
                 },
                 log_path=log_path,
                 color=True,
+                settings=self.settings,
             )
 
             if test_result.returncode == 0:
@@ -247,6 +251,8 @@ def _write_smelt_script(
         component = source.component
 
         mvn_args = ["--color", "always", "-Denforcer.skip"]
+        if self.settings is not None:
+            mvn_args += ["-s", str(self.settings)]
         for key, value in merged.items():
             mvn_args.append(f"-D{key}={value}")
         args_str = " ".join(shlex.quote(a) for a in mvn_args)

src/pombast/maven/_mega_melt.py

@@ -206,6 +206,7 @@ def run_mega_melt_validation(
     mega_melt_dir: Path,
     java_home: Path | None = None,
     extra_properties: dict[str, str] | None = None,
+    settings: Path | None = None,
 ) -> tuple[bool, Path, Path]:
     """Run mega-melt validation.
 
@@ -226,6 +227,7 @@ def run_mega_melt_validation(
         extra_properties=extra_properties,
         log_path=tree_log,
         skip_enforcer=False,
+        settings=settings,
     )
     if tree_result.returncode != 0:
         _log.warning("Mega-melt dependency:tree FAILED — see %s", tree_log)
@@ -239,6 +241,7 @@ def run_mega_melt_validation(
         extra_properties=extra_properties,
         log_path=build_log,
         skip_enforcer=False,
+        settings=settings,
     )
     success = build_result.returncode == 0
     level = _log.info if success else _log.warning

src/pombast/util/_process.py

@@ -44,6 +44,7 @@ def run_maven(
     timeout: int | None = None,
     skip_enforcer: bool = True,
     color: bool = False,
+    settings: Path | None = None,
 ) -> subprocess.CompletedProcess:
     """Run a Maven command.
 
@@ -57,12 +58,18 @@ def run_maven(
         skip_enforcer: If True (default), pass -Denforcer.skip to suppress
             enforcer rules. Set False for mega-melt validation where the
             enforcer is the point.
+        settings: If provided, a Maven settings.xml passed via ``-s``. Lets the
+            caller supply mirrors, credentials, or per-repository update
+            policies without touching their user-wide ``~/.m2/settings.xml``.
 
     Returns:
         CompletedProcess with stdout/stderr.
     """
     cmd = [_resolve_mvn()]
 
+    if settings is not None:
+        cmd.extend(["-s", str(settings)])
+
     if color:
         cmd.extend(["--color", "always"])