[substitutions] [packages] Address review feedback

- Seed `resolve_include` context with `command_line_substitutions` so
  `substitutions: !include ${var}.yaml` can reference CLI-provided vars
  in the include filename (parallels the `packages: !include` path).
- Validate shape of resolved substitutions in `do_packages_pass` and raise
  `cv.Invalid` under `CONF_SUBSTITUTIONS` instead of letting `UserDict()`
  fail with a low-level exception on a non-mapping.
- Fixture 17 exercises the CLI-templated include filename.

esphome/components/packages/__init__.py

@@ -517,11 +517,20 @@ def do_packages_pass(
         return config
 
     raw_substitutions = config.pop(CONF_SUBSTITUTIONS, {})
-    if isinstance(raw_substitutions, yaml_util.IncludeFile):
-        # Resolve `substitutions: !include file.yaml` before feeding into UserDict.
-        with cv.prepend_path(CONF_SUBSTITUTIONS):
+    with cv.prepend_path(CONF_SUBSTITUTIONS):
+        if isinstance(raw_substitutions, yaml_util.IncludeFile):
+            # Resolve `substitutions: !include file.yaml` before feeding into UserDict.
+            # Seed with command-line substitutions so `!include ${var}.yaml` can
+            # reference CLI-provided vars in the filename.
             raw_substitutions, _ = resolve_include(
-                raw_substitutions, [], ContextVars(), strict_undefined=False
+                raw_substitutions,
+                [],
+                ContextVars(command_line_substitutions or {}),
+                strict_undefined=False,
+            )
+        if not isinstance(raw_substitutions, dict):
+            raise cv.Invalid(
+                f"Substitutions must be a key to value mapping, got {type(raw_substitutions)}"
             )
     substitutions = UserDict(raw_substitutions)
     processor = _PackageProcessor(

esphome/components/substitutions/__init__.py

@@ -431,8 +431,13 @@ def do_substitution_pass(
     with cv.prepend_path(CONF_SUBSTITUTIONS):
         if isinstance(substitutions, IncludeFile):
             # Resolve `substitutions: !include file.yaml` before validating the shape.
+            # Seed with command-line substitutions so `!include ${var}.yaml` can
+            # reference CLI-provided vars in the filename.
             substitutions, _ = resolve_include(
-                substitutions, [], ContextVars(), strict_undefined=False
+                substitutions,
+                [],
+                ContextVars(command_line_substitutions or {}),
+                strict_undefined=False,
             )
         if not isinstance(substitutions, dict):
             raise cv.Invalid(

tests/unit_tests/fixtures/substitutions/17-substitutions_include_cli_var.approved.yaml

@@ -0,0 +1,6 @@
+substitutions:
+  subs_file: 15-substitutions_inc
+  wifi_password: sub_password
+wifi:
+  ssid: main_ssid
+  password: sub_password

tests/unit_tests/fixtures/substitutions/17-substitutions_include_cli_var.input.yaml

@@ -0,0 +1,8 @@
+command_line_substitutions:
+  subs_file: 15-substitutions_inc
+
+substitutions: !include ${subs_file}.yaml
+
+wifi:
+  ssid: main_ssid
+  password: $wifi_password