fix: forward CLI args through devopsos scaffold to underlying modules; clarify devopsos vs scaffold_* distinction

Co-authored-by: chefgs <7605658+chefgs@users.noreply.github.com>

Author: Copilot

cli/devopsos.py

@@ -241,20 +241,59 @@ def _sel(group): return selected_by_group.get(group, [])
         # Optionally, update Dockerfile (not strictly needed if it uses build args)
         typer.echo("Dockerfile uses build args; ensure it references the correct ARGs.")
 
-@app.command()
+@app.command(context_settings={"allow_extra_args": True, "ignore_unknown_options": True})
 def scaffold(
+    ctx: typer.Context,
     target: str = typer.Argument(..., help="What to scaffold: cicd | gha | gitlab | jenkins | argocd | sre | devcontainer"),
-    tool: str = typer.Option(None, help="Tool type (e.g., github, jenkins, argo, flux)"),
 ):
-    """Scaffold CI/CD or K8s resources."""
-    # Each scaffold module uses argparse internally and calls parse_args() which
-    # reads sys.argv.  When invoked via `python -m cli.devopsos scaffold <target>`
-    # sys.argv still contains the parent CLI tokens (e.g. ['devopsos.py', 'scaffold',
-    # 'gha']).  Temporarily strip those extra tokens so argparse inside each
-    # scaffold module only sees the program name and falls back to env-var / default
-    # values, then restore sys.argv afterwards.
+    """Scaffold CI/CD or K8s resources.
+
+    \b
+    ┌─ Two ways to invoke scaffold commands ──────────────────────────────────┐
+    │                                                                         │
+    │  1. Via the unified CLI (this command):                                 │
+    │       python -m cli.devopsos scaffold <TARGET> [OPTIONS]                │
+    │                                                                         │
+    │  2. Directly as a standalone module:                                    │
+    │       python -m cli.scaffold_<TARGET> [OPTIONS]                         │
+    │                                                                         │
+    │  Both forms are equivalent. Any OPTIONS you pass after TARGET are       │
+    │  forwarded verbatim to the underlying scaffold module.                  │
+    └─────────────────────────────────────────────────────────────────────────┘
+
+    \b
+    DIFFERENCE BETWEEN cli.devopsos AND cli.scaffold_*
+      cli.devopsos      — unified entry point; provides init, scaffold, and
+                          process-first commands under one roof.  Use this
+                          when you want a single consistent CLI.
+
+      cli.scaffold_*    — standalone, tool-specific generators (e.g.
+                          cli.scaffold_jenkins, cli.scaffold_argocd).  Each
+                          module can be run on its own via `python -m` and
+                          supports the full set of argparse options for that
+                          tool.  They are also the engine behind `devopsos
+                          scaffold <target>`.
+
+    \b
+    EXAMPLES
+      # Unified CLI — args forwarded to the Jenkins generator:
+      python -m cli.devopsos scaffold jenkins --type complete --languages python
+
+      # Direct module invocation — identical result:
+      python -m cli.scaffold_jenkins --type complete --languages python
+
+      # See all options available for a specific scaffold target:
+      python -m cli.scaffold_jenkins --help
+      python -m cli.scaffold_gha --help
+      python -m cli.scaffold_argocd --help
+    """
+    # Each scaffold module uses argparse internally and reads sys.argv.
+    # We temporarily replace sys.argv so argparse sees only the program name
+    # plus any extra arguments the user passed after the TARGET token.
+    # This lets `devopsos scaffold jenkins --type complete` work identically
+    # to `python -m cli.scaffold_jenkins --type complete`.
     _saved_argv = sys.argv[:]
-    sys.argv = sys.argv[:1]
+    sys.argv = sys.argv[:1] + ctx.args
     try:
         if target == "cicd":
             scaffold_cicd.main()

cli/test_cli.py

@@ -570,3 +570,88 @@ def test_process_first_specific_section_no_usage_footer():
             f"--section {section} should not show the usage footer"
         )
 
+
+# -- scaffold arg pass-through (cli.devopsos vs cli.scaffold_*) ------------
+
+def test_scaffold_help_explains_dual_invocation():
+    """`devopsos scaffold --help` documents both invocation forms and the difference."""
+    result = _run(["-m", "cli.devopsos", "scaffold", "--help"])
+    assert result.returncode == 0
+    text = _strip_ansi(result.stdout)
+    assert "cli.devopsos" in text, "help should mention cli.devopsos"
+    assert "cli.scaffold_" in text, "help should mention cli.scaffold_* modules"
+    assert "forwarded" in text.lower() or "forward" in text.lower(), (
+        "help should mention that extra args are forwarded"
+    )
+
+
+def test_scaffold_jenkins_args_forwarded_via_cli():
+    """`devopsos scaffold jenkins --type build --languages python` forwards args to scaffold_jenkins."""
+    with tempfile.TemporaryDirectory() as tmp:
+        out = os.path.join(tmp, "Jenkinsfile")
+        result = subprocess.run(
+            [
+                sys.executable, "-m", "cli.devopsos",
+                "scaffold", "jenkins",
+                "--type", "build",
+                "--languages", "python",
+                "--output", out,
+            ],
+            capture_output=True, text=True,
+            cwd=os.path.dirname(os.path.dirname(__file__)),
+        )
+        assert result.returncode == 0, result.stderr
+        assert "error: unrecognized arguments" not in result.stderr
+        assert os.path.isfile(out), "Jenkinsfile should have been created"
+        content = Path(out).read_text()
+        assert "pipeline" in content.lower() or "node" in content.lower(), (
+            "Jenkinsfile should contain pipeline content"
+        )
+
+
+def test_scaffold_gha_args_forwarded_via_cli():
+    """`devopsos scaffold gha --type build --name my-app` forwards args to scaffold_gha."""
+    with tempfile.TemporaryDirectory() as tmp:
+        out_dir = os.path.join(tmp, ".github", "workflows")
+        result = subprocess.run(
+            [
+                sys.executable, "-m", "cli.devopsos",
+                "scaffold", "gha",
+                "--type", "build",
+                "--name", "my-app",
+                "--output", out_dir,
+            ],
+            capture_output=True, text=True,
+            cwd=os.path.dirname(os.path.dirname(__file__)),
+        )
+        assert result.returncode == 0, result.stderr
+        assert "error: unrecognized arguments" not in result.stderr
+        wf_files = list(Path(out_dir).glob("*.yml"))
+        assert wf_files, "At least one workflow YAML should have been created"
+
+
+def test_scaffold_via_cli_matches_direct_module_output():
+    """Output from `devopsos scaffold gitlab` equals `python -m cli.scaffold_gitlab` (same defaults)."""
+    with tempfile.TemporaryDirectory() as tmp1, tempfile.TemporaryDirectory() as tmp2:
+        out1 = os.path.join(tmp1, ".gitlab-ci.yml")
+        out2 = os.path.join(tmp2, ".gitlab-ci.yml")
+
+        base_args = ["--name", "test-app", "--type", "build"]
+
+        result_unified = subprocess.run(
+            [sys.executable, "-m", "cli.devopsos", "scaffold", "gitlab"] + base_args + ["--output", out1],
+            capture_output=True, text=True,
+            cwd=os.path.dirname(os.path.dirname(__file__)),
+        )
+        result_direct = subprocess.run(
+            [sys.executable, "-m", "cli.scaffold_gitlab"] + base_args + ["--output", out2],
+            capture_output=True, text=True,
+            cwd=os.path.dirname(os.path.dirname(__file__)),
+        )
+
+        assert result_unified.returncode == 0, result_unified.stderr
+        assert result_direct.returncode == 0, result_direct.stderr
+        assert Path(out1).read_text() == Path(out2).read_text(), (
+            "Unified CLI and direct module should produce identical output"
+        )
+