From dec5b51207cc3f9f3bddf83cdbe69e89e5e47231 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com>
Date: Fri, 18 Sep 2026 22:16:42 +0530
Subject: [PATCH 1/3] fix(output): check optional YAML renderer before
 reconciliation

---
 .github/workflows/tests.yml   |  6 +--
 docs/optional-integrations.md | 14 +++++++
 pyproject.toml                |  3 ++
 src/base_cli_demo/cli.py      | 15 +++++++
 tests/test_cli.py             | 31 +++++++++++++++
 tests/test_yaml_output.py     | 22 ++++++++++
 uv.lock                       | 75 ++++++++++++++++++++++++++++++++++-
 7 files changed, 162 insertions(+), 4 deletions(-)
 create mode 100644 tests/test_yaml_output.py

diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
index a96020f..ec5c1a5 100644
--- a/.github/workflows/tests.yml
+++ b/.github/workflows/tests.yml
@@ -38,6 +38,6 @@ jobs:
         with:
           python-version: "3.13"
       - name: Install optional integration extras
-        run: python -m pip install ".[dev,typer,rich,telemetry]"
-      - name: Run optional integration tests
-        run: python -m pytest -q tests/test_optional_scenarios.py
+        run: python -m pip install ".[dev,typer,rich,telemetry,yaml]"
+      - name: Run optional integration and YAML renderer tests
+        run: python -m pytest -q tests/test_optional_scenarios.py tests/test_yaml_output.py
diff --git a/docs/optional-integrations.md b/docs/optional-integrations.md
index 853ced1..abed9ca 100644
--- a/docs/optional-integrations.md
+++ b/docs/optional-integrations.md
@@ -57,3 +57,17 @@ does not attach argv, configuration, paths, or secrets.
 The focused tests run in both modes: the normal CI job exercises the minimal
 fallbacks, while the optional-integration CI job installs all three extras and
 exercises the enabled adapters.
+
+## YAML output
+
+YAML is an optional Base-CLI renderer. Install it explicitly before using
+`--format yaml`:
+
+```console
+$ python -m pip install "base-cli-demo[yaml]"
+$ northstar --quiet status --format yaml
+```
+
+Without the extra, Northstar reports the install command before running the
+consumer command, so a reconciliation cannot persist state and then fail while
+rendering its result.
diff --git a/pyproject.toml b/pyproject.toml
index 87c6b35..bf8e2af 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -25,6 +25,9 @@ typer = [
 rich = [
   "rich>=13.7,<15",
 ]
+yaml = [
+  "base-cli[yaml]>=0.4.3,<0.5",
+]
 telemetry = [
   "opentelemetry-api>=1.24,<2",
 ]
diff --git a/src/base_cli_demo/cli.py b/src/base_cli_demo/cli.py
index 8f625c1..8dcb132 100644
--- a/src/base_cli_demo/cli.py
+++ b/src/base_cli_demo/cli.py
@@ -5,6 +5,7 @@
 import json
 from collections.abc import Mapping
 from importlib.resources import files
+from importlib.util import find_spec
 from typing import Any
 
 import base_cli
@@ -19,6 +20,19 @@
 )
 
 
+def _check_format_dependency(
+    _context: click.Context, _parameter: click.Parameter, value: str
+) -> str:
+    """Reject unavailable optional renderers before command side effects."""
+
+    if value.lower() == "yaml" and find_spec("yaml") is None:
+        raise click.ClickException(
+            "YAML output requires the optional renderer; install it with "
+            "`python -m pip install 'base-cli-demo[yaml]'`."
+        )
+    return value
+
+
 def _load_services() -> tuple[dict[str, str], ...]:
     """Load and validate the application-owned deterministic fixture."""
 
@@ -124,6 +138,7 @@ def _format_option(function: Any) -> Any:
         default="text",
         show_default=True,
         help="Render text, CSV, TSV, YAML, JSON, or NDJSON.",
+        callback=_check_format_dependency,
     )(function)
 
 
diff --git a/tests/test_cli.py b/tests/test_cli.py
index ecdba6f..bead3d7 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -6,6 +6,8 @@
 from typing import Any
 
 import base_cli
+import base_cli_demo.cli as cli_module
+import pytest
 
 from base_cli_demo.cli import command
 
@@ -130,6 +132,35 @@ def test_reconcile_persists_state_and_cleans_temporary_input() -> None:
         assert list(root.rglob("reconciliation-input.json")) == []
 
 
+def test_yaml_without_optional_renderer_fails_before_reconciliation_state(
+    monkeypatch: Any,
+) -> None:
+    monkeypatch.setattr(cli_module, "find_spec", lambda _name: None)
+    with tempfile.TemporaryDirectory() as directory:
+        root = Path(directory)
+        result = invoke(["release", "reconcile", "--format", "yaml"], root)
+
+        assert result.exit_code == 1
+        assert "base-cli-demo[yaml]" in result.output
+        assert list(root.rglob("last-reconciliation.json")) == []
+
+
+def test_yaml_extra_renders_reconciliation_when_available() -> None:
+    try:
+        import yaml  # noqa: F401
+    except ImportError:
+        pytest.skip("PyYAML is installed by the optional yaml extra")
+
+    with tempfile.TemporaryDirectory() as directory:
+        result = invoke(
+            ["--dry-run", "release", "reconcile", "--format", "yaml"],
+            Path(directory),
+        )
+
+    assert result.exit_code == 0, result.output
+    assert "target_version: 2.5.0" in result.stdout
+
+
 def test_json_error_envelope_preserves_nonzero_exit_status() -> None:
     with tempfile.TemporaryDirectory() as directory:
         result = invoke(
diff --git a/tests/test_yaml_output.py b/tests/test_yaml_output.py
new file mode 100644
index 0000000..2647a49
--- /dev/null
+++ b/tests/test_yaml_output.py
@@ -0,0 +1,22 @@
+from __future__ import annotations
+
+import importlib.util
+
+import base_cli
+import pytest
+
+from base_cli_demo.cli import command
+
+
+def test_yaml_output_renders_with_the_optional_extra(tmp_path) -> None:
+    if importlib.util.find_spec("yaml") is None:
+        pytest.skip("PyYAML is installed by the optional yaml extra")
+
+    result = base_cli.testing.invoke(
+        command,
+        ["--quiet", "status", "--format", "yaml"],
+        home=tmp_path,
+    )
+
+    assert result.exit_code == 0, result.output
+    assert "service: orders-api" in result.stdout
diff --git a/uv.lock b/uv.lock
index de52faf..1bf416f 100644
--- a/uv.lock
+++ b/uv.lock
@@ -32,6 +32,11 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/7b/d3/8ad3a107480e55b9ac956a84460616d9152c4ca7055c50acec12ca40785e/base_cli-0.4.3-py3-none-any.whl", hash = "sha256:b4bf684d164b9fdf31d1d0176dfcb5359cedf9b22434d6f6a5483243e27c9b89", size = 123477, upload-time = "2026-08-29T04:19:07.27Z" },
 ]
 
+[package.optional-dependencies]
+yaml = [
+    { name = "pyyaml" },
+]
+
 [[package]]
 name = "base-cli-demo"
 version = "0.1.0"
@@ -56,10 +61,14 @@ telemetry = [
 typer = [
     { name = "typer" },
 ]
+yaml = [
+    { name = "base-cli", extra = ["yaml"] },
+]
 
 [package.metadata]
 requires-dist = [
     { name = "base-cli", specifier = ">=0.4.3,<0.5" },
+    { name = "base-cli", extras = ["yaml"], marker = "extra == 'yaml'", specifier = ">=0.4.3,<0.5" },
     { name = "build", marker = "extra == 'dev'", specifier = ">=1.2,<2" },
     { name = "click", specifier = ">=8.1,<9" },
     { name = "opentelemetry-api", marker = "extra == 'telemetry'", specifier = ">=1.24,<2" },
@@ -68,7 +77,7 @@ requires-dist = [
     { name = "twine", marker = "extra == 'dev'", specifier = ">=5,<7" },
     { name = "typer", marker = "extra == 'typer'", specifier = ">=0.12,<0.28" },
 ]
-provides-extras = ["dev", "typer", "rich", "telemetry"]
+provides-extras = ["dev", "typer", "rich", "yaml", "telemetry"]
 
 [[package]]
 name = "build"
@@ -651,6 +660,70 @@ wheels = [
     { url = "https://files.pythonhosted.org/packages/de/3d/8161f7711c017e01ac9f008dfddd9410dff3674334c233bde66e7ba65bbf/pywin32_ctypes-0.2.3-py3-none-any.whl", hash = "sha256:8a1513379d709975552d202d942d9837758905c8d01eb82b8bcc30918929e7b8", size = 30756, upload-time = "2024-08-14T10:15:33.187Z" },
 ]
 
+[[package]]
+name = "pyyaml"
+version = "6.0.3"
+source = { registry = "https://pypi.org/simple" }
+sdist = { url = "https://files.pythonhosted.org/packages/05/8e/961c0007c59b8dd7729d542c61a4d537767a59645b82a0b521206e1e25c2/pyyaml-6.0.3.tar.gz", hash = "sha256:d76623373421df22fb4cf8817020cbb7ef15c725b9d5e45f17e189bfc384190f", size = 130960, upload-time = "2025-09-25T21:33:16.546Z" }
+wheels = [
+    { url = "https://files.pythonhosted.org/packages/f4/a0/39350dd17dd6d6c6507025c0e53aef67a9293a6d37d3511f23ea510d5800/pyyaml-6.0.3-cp310-cp310-macosx_10_13_x86_64.whl", hash = "sha256:214ed4befebe12df36bcc8bc2b64b396ca31be9304b8f59e25c11cf94a4c033b", size = 184227, upload-time = "2025-09-25T21:31:46.04Z" },
+    { url = "https://files.pythonhosted.org/packages/05/14/52d505b5c59ce73244f59c7a50ecf47093ce4765f116cdb98286a71eeca2/pyyaml-6.0.3-cp310-cp310-macosx_11_0_arm64.whl", hash = "sha256:02ea2dfa234451bbb8772601d7b8e426c2bfa197136796224e50e35a78777956", size = 174019, upload-time = "2025-09-25T21:31:47.706Z" },
+    { url = "https://files.pythonhosted.org/packages/43/f7/0e6a5ae5599c838c696adb4e6330a59f463265bfa1e116cfd1fbb0abaaae/pyyaml-6.0.3-cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:b30236e45cf30d2b8e7b3e85881719e98507abed1011bf463a8fa23e9c3e98a8", size = 740646, upload-time = "2025-09-25T21:31:49.21Z" },
+    { url = "https://files.pythonhosted.org/packages/2f/3a/61b9db1d28f00f8fd0ae760459a5c4bf1b941baf714e207b6eb0657d2578/pyyaml-6.0.3-cp310-cp310-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:66291b10affd76d76f54fad28e22e51719ef9ba22b29e1d7d03d6777a9174198", size = 840793, upload-time = "2025-09-25T21:31:50.735Z" },
+    { url = "https://files.pythonhosted.org/packages/7a/1e/7acc4f0e74c4b3d9531e24739e0ab832a5edf40e64fbae1a9c01941cabd7/pyyaml-6.0.3-cp310-cp310-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:9c7708761fccb9397fe64bbc0395abcae8c4bf7b0eac081e12b809bf47700d0b", size = 770293, upload-time = "2025-09-25T21:31:51.828Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/ef/abd085f06853af0cd59fa5f913d61a8eab65d7639ff2a658d18a25d6a89d/pyyaml-6.0.3-cp310-cp310-musllinux_1_2_aarch64.whl", hash = "sha256:418cf3f2111bc80e0933b2cd8cd04f286338bb88bdc7bc8e6dd775ebde60b5e0", size = 732872, upload-time = "2025-09-25T21:31:53.282Z" },
+    { url = "https://files.pythonhosted.org/packages/1f/15/2bc9c8faf6450a8b3c9fc5448ed869c599c0a74ba2669772b1f3a0040180/pyyaml-6.0.3-cp310-cp310-musllinux_1_2_x86_64.whl", hash = "sha256:5e0b74767e5f8c593e8c9b5912019159ed0533c70051e9cce3e8b6aa699fcd69", size = 758828, upload-time = "2025-09-25T21:31:54.807Z" },
+    { url = "https://files.pythonhosted.org/packages/a3/00/531e92e88c00f4333ce359e50c19b8d1de9fe8d581b1534e35ccfbc5f393/pyyaml-6.0.3-cp310-cp310-win32.whl", hash = "sha256:28c8d926f98f432f88adc23edf2e6d4921ac26fb084b028c733d01868d19007e", size = 142415, upload-time = "2025-09-25T21:31:55.885Z" },
+    { url = "https://files.pythonhosted.org/packages/2a/fa/926c003379b19fca39dd4634818b00dec6c62d87faf628d1394e137354d4/pyyaml-6.0.3-cp310-cp310-win_amd64.whl", hash = "sha256:bdb2c67c6c1390b63c6ff89f210c8fd09d9a1217a465701eac7316313c915e4c", size = 158561, upload-time = "2025-09-25T21:31:57.406Z" },
+    { url = "https://files.pythonhosted.org/packages/6d/16/a95b6757765b7b031c9374925bb718d55e0a9ba8a1b6a12d25962ea44347/pyyaml-6.0.3-cp311-cp311-macosx_10_13_x86_64.whl", hash = "sha256:44edc647873928551a01e7a563d7452ccdebee747728c1080d881d68af7b997e", size = 185826, upload-time = "2025-09-25T21:31:58.655Z" },
+    { url = "https://files.pythonhosted.org/packages/16/19/13de8e4377ed53079ee996e1ab0a9c33ec2faf808a4647b7b4c0d46dd239/pyyaml-6.0.3-cp311-cp311-macosx_11_0_arm64.whl", hash = "sha256:652cb6edd41e718550aad172851962662ff2681490a8a711af6a4d288dd96824", size = 175577, upload-time = "2025-09-25T21:32:00.088Z" },
+    { url = "https://files.pythonhosted.org/packages/0c/62/d2eb46264d4b157dae1275b573017abec435397aa59cbcdab6fc978a8af4/pyyaml-6.0.3-cp311-cp311-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:10892704fc220243f5305762e276552a0395f7beb4dbf9b14ec8fd43b57f126c", size = 775556, upload-time = "2025-09-25T21:32:01.31Z" },
+    { url = "https://files.pythonhosted.org/packages/10/cb/16c3f2cf3266edd25aaa00d6c4350381c8b012ed6f5276675b9eba8d9ff4/pyyaml-6.0.3-cp311-cp311-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:850774a7879607d3a6f50d36d04f00ee69e7fc816450e5f7e58d7f17f1ae5c00", size = 882114, upload-time = "2025-09-25T21:32:03.376Z" },
+    { url = "https://files.pythonhosted.org/packages/71/60/917329f640924b18ff085ab889a11c763e0b573da888e8404ff486657602/pyyaml-6.0.3-cp311-cp311-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:b8bb0864c5a28024fac8a632c443c87c5aa6f215c0b126c449ae1a150412f31d", size = 806638, upload-time = "2025-09-25T21:32:04.553Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/6f/529b0f316a9fd167281a6c3826b5583e6192dba792dd55e3203d3f8e655a/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_aarch64.whl", hash = "sha256:1d37d57ad971609cf3c53ba6a7e365e40660e3be0e5175fa9f2365a379d6095a", size = 767463, upload-time = "2025-09-25T21:32:06.152Z" },
+    { url = "https://files.pythonhosted.org/packages/f2/6a/b627b4e0c1dd03718543519ffb2f1deea4a1e6d42fbab8021936a4d22589/pyyaml-6.0.3-cp311-cp311-musllinux_1_2_x86_64.whl", hash = "sha256:37503bfbfc9d2c40b344d06b2199cf0e96e97957ab1c1b546fd4f87e53e5d3e4", size = 794986, upload-time = "2025-09-25T21:32:07.367Z" },
+    { url = "https://files.pythonhosted.org/packages/45/91/47a6e1c42d9ee337c4839208f30d9f09caa9f720ec7582917b264defc875/pyyaml-6.0.3-cp311-cp311-win32.whl", hash = "sha256:8098f252adfa6c80ab48096053f512f2321f0b998f98150cea9bd23d83e1467b", size = 142543, upload-time = "2025-09-25T21:32:08.95Z" },
+    { url = "https://files.pythonhosted.org/packages/da/e3/ea007450a105ae919a72393cb06f122f288ef60bba2dc64b26e2646fa315/pyyaml-6.0.3-cp311-cp311-win_amd64.whl", hash = "sha256:9f3bfb4965eb874431221a3ff3fdcddc7e74e3b07799e0e84ca4a0f867d449bf", size = 158763, upload-time = "2025-09-25T21:32:09.96Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/33/422b98d2195232ca1826284a76852ad5a86fe23e31b009c9886b2d0fb8b2/pyyaml-6.0.3-cp312-cp312-macosx_10_13_x86_64.whl", hash = "sha256:7f047e29dcae44602496db43be01ad42fc6f1cc0d8cd6c83d342306c32270196", size = 182063, upload-time = "2025-09-25T21:32:11.445Z" },
+    { url = "https://files.pythonhosted.org/packages/89/a0/6cf41a19a1f2f3feab0e9c0b74134aa2ce6849093d5517a0c550fe37a648/pyyaml-6.0.3-cp312-cp312-macosx_11_0_arm64.whl", hash = "sha256:fc09d0aa354569bc501d4e787133afc08552722d3ab34836a80547331bb5d4a0", size = 173973, upload-time = "2025-09-25T21:32:12.492Z" },
+    { url = "https://files.pythonhosted.org/packages/ed/23/7a778b6bd0b9a8039df8b1b1d80e2e2ad78aa04171592c8a5c43a56a6af4/pyyaml-6.0.3-cp312-cp312-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:9149cad251584d5fb4981be1ecde53a1ca46c891a79788c0df828d2f166bda28", size = 775116, upload-time = "2025-09-25T21:32:13.652Z" },
+    { url = "https://files.pythonhosted.org/packages/65/30/d7353c338e12baef4ecc1b09e877c1970bd3382789c159b4f89d6a70dc09/pyyaml-6.0.3-cp312-cp312-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:5fdec68f91a0c6739b380c83b951e2c72ac0197ace422360e6d5a959d8d97b2c", size = 844011, upload-time = "2025-09-25T21:32:15.21Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/9d/b3589d3877982d4f2329302ef98a8026e7f4443c765c46cfecc8858c6b4b/pyyaml-6.0.3-cp312-cp312-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:ba1cc08a7ccde2d2ec775841541641e4548226580ab850948cbfda66a1befcdc", size = 807870, upload-time = "2025-09-25T21:32:16.431Z" },
+    { url = "https://files.pythonhosted.org/packages/05/c0/b3be26a015601b822b97d9149ff8cb5ead58c66f981e04fedf4e762f4bd4/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_aarch64.whl", hash = "sha256:8dc52c23056b9ddd46818a57b78404882310fb473d63f17b07d5c40421e47f8e", size = 761089, upload-time = "2025-09-25T21:32:17.56Z" },
+    { url = "https://files.pythonhosted.org/packages/be/8e/98435a21d1d4b46590d5459a22d88128103f8da4c2d4cb8f14f2a96504e1/pyyaml-6.0.3-cp312-cp312-musllinux_1_2_x86_64.whl", hash = "sha256:41715c910c881bc081f1e8872880d3c650acf13dfa8214bad49ed4cede7c34ea", size = 790181, upload-time = "2025-09-25T21:32:18.834Z" },
+    { url = "https://files.pythonhosted.org/packages/74/93/7baea19427dcfbe1e5a372d81473250b379f04b1bd3c4c5ff825e2327202/pyyaml-6.0.3-cp312-cp312-win32.whl", hash = "sha256:96b533f0e99f6579b3d4d4995707cf36df9100d67e0c8303a0c55b27b5f99bc5", size = 137658, upload-time = "2025-09-25T21:32:20.209Z" },
+    { url = "https://files.pythonhosted.org/packages/86/bf/899e81e4cce32febab4fb42bb97dcdf66bc135272882d1987881a4b519e9/pyyaml-6.0.3-cp312-cp312-win_amd64.whl", hash = "sha256:5fcd34e47f6e0b794d17de1b4ff496c00986e1c83f7ab2fb8fcfe9616ff7477b", size = 154003, upload-time = "2025-09-25T21:32:21.167Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/08/67bd04656199bbb51dbed1439b7f27601dfb576fb864099c7ef0c3e55531/pyyaml-6.0.3-cp312-cp312-win_arm64.whl", hash = "sha256:64386e5e707d03a7e172c0701abfb7e10f0fb753ee1d773128192742712a98fd", size = 140344, upload-time = "2025-09-25T21:32:22.617Z" },
+    { url = "https://files.pythonhosted.org/packages/d1/11/0fd08f8192109f7169db964b5707a2f1e8b745d4e239b784a5a1dd80d1db/pyyaml-6.0.3-cp313-cp313-macosx_10_13_x86_64.whl", hash = "sha256:8da9669d359f02c0b91ccc01cac4a67f16afec0dac22c2ad09f46bee0697eba8", size = 181669, upload-time = "2025-09-25T21:32:23.673Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/16/95309993f1d3748cd644e02e38b75d50cbc0d9561d21f390a76242ce073f/pyyaml-6.0.3-cp313-cp313-macosx_11_0_arm64.whl", hash = "sha256:2283a07e2c21a2aa78d9c4442724ec1eb15f5e42a723b99cb3d822d48f5f7ad1", size = 173252, upload-time = "2025-09-25T21:32:25.149Z" },
+    { url = "https://files.pythonhosted.org/packages/50/31/b20f376d3f810b9b2371e72ef5adb33879b25edb7a6d072cb7ca0c486398/pyyaml-6.0.3-cp313-cp313-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:ee2922902c45ae8ccada2c5b501ab86c36525b883eff4255313a253a3160861c", size = 767081, upload-time = "2025-09-25T21:32:26.575Z" },
+    { url = "https://files.pythonhosted.org/packages/49/1e/a55ca81e949270d5d4432fbbd19dfea5321eda7c41a849d443dc92fd1ff7/pyyaml-6.0.3-cp313-cp313-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a33284e20b78bd4a18c8c2282d549d10bc8408a2a7ff57653c0cf0b9be0afce5", size = 841159, upload-time = "2025-09-25T21:32:27.727Z" },
+    { url = "https://files.pythonhosted.org/packages/74/27/e5b8f34d02d9995b80abcef563ea1f8b56d20134d8f4e5e81733b1feceb2/pyyaml-6.0.3-cp313-cp313-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:0f29edc409a6392443abf94b9cf89ce99889a1dd5376d94316ae5145dfedd5d6", size = 801626, upload-time = "2025-09-25T21:32:28.878Z" },
+    { url = "https://files.pythonhosted.org/packages/f9/11/ba845c23988798f40e52ba45f34849aa8a1f2d4af4b798588010792ebad6/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_aarch64.whl", hash = "sha256:f7057c9a337546edc7973c0d3ba84ddcdf0daa14533c2065749c9075001090e6", size = 753613, upload-time = "2025-09-25T21:32:30.178Z" },
+    { url = "https://files.pythonhosted.org/packages/3d/e0/7966e1a7bfc0a45bf0a7fb6b98ea03fc9b8d84fa7f2229e9659680b69ee3/pyyaml-6.0.3-cp313-cp313-musllinux_1_2_x86_64.whl", hash = "sha256:eda16858a3cab07b80edaf74336ece1f986ba330fdb8ee0d6c0d68fe82bc96be", size = 794115, upload-time = "2025-09-25T21:32:31.353Z" },
+    { url = "https://files.pythonhosted.org/packages/de/94/980b50a6531b3019e45ddeada0626d45fa85cbe22300844a7983285bed3b/pyyaml-6.0.3-cp313-cp313-win32.whl", hash = "sha256:d0eae10f8159e8fdad514efdc92d74fd8d682c933a6dd088030f3834bc8e6b26", size = 137427, upload-time = "2025-09-25T21:32:32.58Z" },
+    { url = "https://files.pythonhosted.org/packages/97/c9/39d5b874e8b28845e4ec2202b5da735d0199dbe5b8fb85f91398814a9a46/pyyaml-6.0.3-cp313-cp313-win_amd64.whl", hash = "sha256:79005a0d97d5ddabfeeea4cf676af11e647e41d81c9a7722a193022accdb6b7c", size = 154090, upload-time = "2025-09-25T21:32:33.659Z" },
+    { url = "https://files.pythonhosted.org/packages/73/e8/2bdf3ca2090f68bb3d75b44da7bbc71843b19c9f2b9cb9b0f4ab7a5a4329/pyyaml-6.0.3-cp313-cp313-win_arm64.whl", hash = "sha256:5498cd1645aa724a7c71c8f378eb29ebe23da2fc0d7a08071d89469bf1d2defb", size = 140246, upload-time = "2025-09-25T21:32:34.663Z" },
+    { url = "https://files.pythonhosted.org/packages/9d/8c/f4bd7f6465179953d3ac9bc44ac1a8a3e6122cf8ada906b4f96c60172d43/pyyaml-6.0.3-cp314-cp314-macosx_10_13_x86_64.whl", hash = "sha256:8d1fab6bb153a416f9aeb4b8763bc0f22a5586065f86f7664fc23339fc1c1fac", size = 181814, upload-time = "2025-09-25T21:32:35.712Z" },
+    { url = "https://files.pythonhosted.org/packages/bd/9c/4d95bb87eb2063d20db7b60faa3840c1b18025517ae857371c4dd55a6b3a/pyyaml-6.0.3-cp314-cp314-macosx_11_0_arm64.whl", hash = "sha256:34d5fcd24b8445fadc33f9cf348c1047101756fd760b4dacb5c3e99755703310", size = 173809, upload-time = "2025-09-25T21:32:36.789Z" },
+    { url = "https://files.pythonhosted.org/packages/92/b5/47e807c2623074914e29dabd16cbbdd4bf5e9b2db9f8090fa64411fc5382/pyyaml-6.0.3-cp314-cp314-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:501a031947e3a9025ed4405a168e6ef5ae3126c59f90ce0cd6f2bfc477be31b7", size = 766454, upload-time = "2025-09-25T21:32:37.966Z" },
+    { url = "https://files.pythonhosted.org/packages/02/9e/e5e9b168be58564121efb3de6859c452fccde0ab093d8438905899a3a483/pyyaml-6.0.3-cp314-cp314-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:b3bc83488de33889877a0f2543ade9f70c67d66d9ebb4ac959502e12de895788", size = 836355, upload-time = "2025-09-25T21:32:39.178Z" },
+    { url = "https://files.pythonhosted.org/packages/88/f9/16491d7ed2a919954993e48aa941b200f38040928474c9e85ea9e64222c3/pyyaml-6.0.3-cp314-cp314-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:c458b6d084f9b935061bc36216e8a69a7e293a2f1e68bf956dcd9e6cbcd143f5", size = 794175, upload-time = "2025-09-25T21:32:40.865Z" },
+    { url = "https://files.pythonhosted.org/packages/dd/3f/5989debef34dc6397317802b527dbbafb2b4760878a53d4166579111411e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_aarch64.whl", hash = "sha256:7c6610def4f163542a622a73fb39f534f8c101d690126992300bf3207eab9764", size = 755228, upload-time = "2025-09-25T21:32:42.084Z" },
+    { url = "https://files.pythonhosted.org/packages/d7/ce/af88a49043cd2e265be63d083fc75b27b6ed062f5f9fd6cdc223ad62f03e/pyyaml-6.0.3-cp314-cp314-musllinux_1_2_x86_64.whl", hash = "sha256:5190d403f121660ce8d1d2c1bb2ef1bd05b5f68533fc5c2ea899bd15f4399b35", size = 789194, upload-time = "2025-09-25T21:32:43.362Z" },
+    { url = "https://files.pythonhosted.org/packages/23/20/bb6982b26a40bb43951265ba29d4c246ef0ff59c9fdcdf0ed04e0687de4d/pyyaml-6.0.3-cp314-cp314-win_amd64.whl", hash = "sha256:4a2e8cebe2ff6ab7d1050ecd59c25d4c8bd7e6f400f5f82b96557ac0abafd0ac", size = 156429, upload-time = "2025-09-25T21:32:57.844Z" },
+    { url = "https://files.pythonhosted.org/packages/f4/f4/a4541072bb9422c8a883ab55255f918fa378ecf083f5b85e87fc2b4eda1b/pyyaml-6.0.3-cp314-cp314-win_arm64.whl", hash = "sha256:93dda82c9c22deb0a405ea4dc5f2d0cda384168e466364dec6255b293923b2f3", size = 143912, upload-time = "2025-09-25T21:32:59.247Z" },
+    { url = "https://files.pythonhosted.org/packages/7c/f9/07dd09ae774e4616edf6cda684ee78f97777bdd15847253637a6f052a62f/pyyaml-6.0.3-cp314-cp314t-macosx_10_13_x86_64.whl", hash = "sha256:02893d100e99e03eda1c8fd5c441d8c60103fd175728e23e431db1b589cf5ab3", size = 189108, upload-time = "2025-09-25T21:32:44.377Z" },
+    { url = "https://files.pythonhosted.org/packages/4e/78/8d08c9fb7ce09ad8c38ad533c1191cf27f7ae1effe5bb9400a46d9437fcf/pyyaml-6.0.3-cp314-cp314t-macosx_11_0_arm64.whl", hash = "sha256:c1ff362665ae507275af2853520967820d9124984e0f7466736aea23d8611fba", size = 183641, upload-time = "2025-09-25T21:32:45.407Z" },
+    { url = "https://files.pythonhosted.org/packages/7b/5b/3babb19104a46945cf816d047db2788bcaf8c94527a805610b0289a01c6b/pyyaml-6.0.3-cp314-cp314t-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl", hash = "sha256:6adc77889b628398debc7b65c073bcb99c4a0237b248cacaf3fe8a557563ef6c", size = 831901, upload-time = "2025-09-25T21:32:48.83Z" },
+    { url = "https://files.pythonhosted.org/packages/8b/cc/dff0684d8dc44da4d22a13f35f073d558c268780ce3c6ba1b87055bb0b87/pyyaml-6.0.3-cp314-cp314t-manylinux2014_s390x.manylinux_2_17_s390x.manylinux_2_28_s390x.whl", hash = "sha256:a80cb027f6b349846a3bf6d73b5e95e782175e52f22108cfa17876aaeff93702", size = 861132, upload-time = "2025-09-25T21:32:50.149Z" },
+    { url = "https://files.pythonhosted.org/packages/b1/5e/f77dc6b9036943e285ba76b49e118d9ea929885becb0a29ba8a7c75e29fe/pyyaml-6.0.3-cp314-cp314t-manylinux2014_x86_64.manylinux_2_17_x86_64.manylinux_2_28_x86_64.whl", hash = "sha256:00c4bdeba853cc34e7dd471f16b4114f4162dc03e6b7afcc2128711f0eca823c", size = 839261, upload-time = "2025-09-25T21:32:51.808Z" },
+    { url = "https://files.pythonhosted.org/packages/ce/88/a9db1376aa2a228197c58b37302f284b5617f56a5d959fd1763fb1675ce6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_aarch64.whl", hash = "sha256:66e1674c3ef6f541c35191caae2d429b967b99e02040f5ba928632d9a7f0f065", size = 805272, upload-time = "2025-09-25T21:32:52.941Z" },
+    { url = "https://files.pythonhosted.org/packages/da/92/1446574745d74df0c92e6aa4a7b0b3130706a4142b2d1a5869f2eaa423c6/pyyaml-6.0.3-cp314-cp314t-musllinux_1_2_x86_64.whl", hash = "sha256:16249ee61e95f858e83976573de0f5b2893b3677ba71c9dd36b9cf8be9ac6d65", size = 829923, upload-time = "2025-09-25T21:32:54.537Z" },
+    { url = "https://files.pythonhosted.org/packages/f0/7a/1c7270340330e575b92f397352af856a8c06f230aa3e76f86b39d01b416a/pyyaml-6.0.3-cp314-cp314t-win_amd64.whl", hash = "sha256:4ad1906908f2f5ae4e5a8ddfce73c320c2a1429ec52eafd27138b7f1cbe341c9", size = 174062, upload-time = "2025-09-25T21:32:55.767Z" },
+    { url = "https://files.pythonhosted.org/packages/f1/12/de94a39c2ef588c7e6455cfbe7343d3b2dc9d6b6b2f40c4c6565744c873d/pyyaml-6.0.3-cp314-cp314t-win_arm64.whl", hash = "sha256:ebc55a14a21cb14062aa4162f906cd962b28e2e9ea38f9b4391244cd8de4ae0b", size = 149341, upload-time = "2025-09-25T21:32:56.828Z" },
+]
+
 [[package]]
 name = "readme-renderer"
 version = "46.0"

From e211887fc76353774831f327b2d801f567344606 Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com>
Date: Fri, 18 Sep 2026 22:19:50 +0530
Subject: [PATCH 2/3] test(output): isolate optional YAML checks and
 documentation

---
 README.md                     |  2 ++
 docs/optional-integrations.md | 14 --------------
 docs/yaml-output.md           | 14 ++++++++++++++
 tests/test_cli.py             | 31 -------------------------------
 tests/test_yaml_output.py     | 20 +++++++++++++++++++-
 5 files changed, 35 insertions(+), 46 deletions(-)
 create mode 100644 docs/yaml-output.md

diff --git a/README.md b/README.md
index f6993ca..f8e9a69 100644
--- a/README.md
+++ b/README.md
@@ -60,6 +60,8 @@ boundary explained beside each scenario, see the
   the supported Base-CLI range and the installed-wheel CI gate.
 - The [optional integration scenarios](docs/optional-integrations.md) show
   Typer, Rich, and OpenTelemetry without making them core dependencies.
+- The [YAML output guide](docs/yaml-output.md) explains its optional renderer
+  extra and the preflight behavior when it is absent.
 - The [release process](docs/release-process.md) covers reproducible wheel and
   source-distribution validation separately from Base-CLI versioning.
 
diff --git a/docs/optional-integrations.md b/docs/optional-integrations.md
index abed9ca..853ced1 100644
--- a/docs/optional-integrations.md
+++ b/docs/optional-integrations.md
@@ -57,17 +57,3 @@ does not attach argv, configuration, paths, or secrets.
 The focused tests run in both modes: the normal CI job exercises the minimal
 fallbacks, while the optional-integration CI job installs all three extras and
 exercises the enabled adapters.
-
-## YAML output
-
-YAML is an optional Base-CLI renderer. Install it explicitly before using
-`--format yaml`:
-
-```console
-$ python -m pip install "base-cli-demo[yaml]"
-$ northstar --quiet status --format yaml
-```
-
-Without the extra, Northstar reports the install command before running the
-consumer command, so a reconciliation cannot persist state and then fail while
-rendering its result.
diff --git a/docs/yaml-output.md b/docs/yaml-output.md
new file mode 100644
index 0000000..79b400c
--- /dev/null
+++ b/docs/yaml-output.md
@@ -0,0 +1,14 @@
+# Optional YAML Output
+
+YAML is a supported Base-CLI renderer, but it is intentionally not part of the
+demo's minimal dependencies. Install the optional extra before using
+`--format yaml`:
+
+```console
+$ python -m pip install "base-cli-demo[yaml]"
+$ northstar --quiet status --format yaml
+```
+
+Without the extra, Northstar reports this install command before running the
+consumer command. In particular, a reconciliation does not persist local state
+and then fail while trying to render YAML.
diff --git a/tests/test_cli.py b/tests/test_cli.py
index bead3d7..ecdba6f 100644
--- a/tests/test_cli.py
+++ b/tests/test_cli.py
@@ -6,8 +6,6 @@
 from typing import Any
 
 import base_cli
-import base_cli_demo.cli as cli_module
-import pytest
 
 from base_cli_demo.cli import command
 
@@ -132,35 +130,6 @@ def test_reconcile_persists_state_and_cleans_temporary_input() -> None:
         assert list(root.rglob("reconciliation-input.json")) == []
 
 
-def test_yaml_without_optional_renderer_fails_before_reconciliation_state(
-    monkeypatch: Any,
-) -> None:
-    monkeypatch.setattr(cli_module, "find_spec", lambda _name: None)
-    with tempfile.TemporaryDirectory() as directory:
-        root = Path(directory)
-        result = invoke(["release", "reconcile", "--format", "yaml"], root)
-
-        assert result.exit_code == 1
-        assert "base-cli-demo[yaml]" in result.output
-        assert list(root.rglob("last-reconciliation.json")) == []
-
-
-def test_yaml_extra_renders_reconciliation_when_available() -> None:
-    try:
-        import yaml  # noqa: F401
-    except ImportError:
-        pytest.skip("PyYAML is installed by the optional yaml extra")
-
-    with tempfile.TemporaryDirectory() as directory:
-        result = invoke(
-            ["--dry-run", "release", "reconcile", "--format", "yaml"],
-            Path(directory),
-        )
-
-    assert result.exit_code == 0, result.output
-    assert "target_version: 2.5.0" in result.stdout
-
-
 def test_json_error_envelope_preserves_nonzero_exit_status() -> None:
     with tempfile.TemporaryDirectory() as directory:
         result = invoke(
diff --git a/tests/test_yaml_output.py b/tests/test_yaml_output.py
index 2647a49..fd927e4 100644
--- a/tests/test_yaml_output.py
+++ b/tests/test_yaml_output.py
@@ -1,14 +1,32 @@
 from __future__ import annotations
 
 import importlib.util
+from pathlib import Path
+from typing import Any
 
 import base_cli
+import base_cli_demo.cli as cli_module
 import pytest
 
 from base_cli_demo.cli import command
 
 
-def test_yaml_output_renders_with_the_optional_extra(tmp_path) -> None:
+def invoke(args: list[str], home: Path) -> Any:
+    return base_cli.testing.invoke(command, ["--quiet", *args], home=home)
+
+
+def test_yaml_without_optional_renderer_fails_before_reconciliation_state(
+    monkeypatch: pytest.MonkeyPatch, tmp_path: Path
+) -> None:
+    monkeypatch.setattr(cli_module, "find_spec", lambda _name: None)
+    result = invoke(["release", "reconcile", "--format", "yaml"], tmp_path)
+
+    assert result.exit_code == 1
+    assert "base-cli-demo[yaml]" in result.output
+    assert list(tmp_path.rglob("last-reconciliation.json")) == []
+
+
+def test_yaml_output_renders_with_the_optional_extra(tmp_path: Path) -> None:
     if importlib.util.find_spec("yaml") is None:
         pytest.skip("PyYAML is installed by the optional yaml extra")
 

From a53101729724a8b70609135dfbb243d1c783cfcf Mon Sep 17 00:00:00 2001
From: Ramesh Padmanabhaiah <22363102+codeforester@users.noreply.github.com>
Date: Sat, 19 Sep 2026 16:26:02 +0530
Subject: [PATCH 3/3] fix: preflight the real YAML renderer

---
 src/base_cli_demo/cli.py  | 21 +++++++++++++++------
 tests/test_yaml_output.py |  8 +++++---
 2 files changed, 20 insertions(+), 9 deletions(-)

diff --git a/src/base_cli_demo/cli.py b/src/base_cli_demo/cli.py
index 8dcb132..7d2925e 100644
--- a/src/base_cli_demo/cli.py
+++ b/src/base_cli_demo/cli.py
@@ -4,8 +4,8 @@
 
 import json
 from collections.abc import Mapping
+from importlib import import_module
 from importlib.resources import files
-from importlib.util import find_spec
 from typing import Any
 
 import base_cli
@@ -25,11 +25,20 @@ def _check_format_dependency(
 ) -> str:
     """Reject unavailable optional renderers before command side effects."""
 
-    if value.lower() == "yaml" and find_spec("yaml") is None:
-        raise click.ClickException(
-            "YAML output requires the optional renderer; install it with "
-            "`python -m pip install 'base-cli-demo[yaml]'`."
-        )
+    if value.lower() == "yaml":
+        try:
+            yaml = import_module("yaml")
+            safe_dump = getattr(yaml, "safe_dump", None)
+            if not callable(safe_dump):
+                raise ImportError("PyYAML does not expose safe_dump")
+            # Exercise the same serializer entry point used by Base-CLI so a
+            # broken or shadowing module is rejected before reconciliation.
+            safe_dump([], sort_keys=False, allow_unicode=True)
+        except Exception as exc:
+            raise click.ClickException(
+                "YAML output requires the optional renderer; install it with "
+                "`python -m pip install 'base-cli-demo[yaml]'`."
+            ) from exc
     return value
 
 
diff --git a/tests/test_yaml_output.py b/tests/test_yaml_output.py
index fd927e4..f4d3eec 100644
--- a/tests/test_yaml_output.py
+++ b/tests/test_yaml_output.py
@@ -5,7 +5,6 @@
 from typing import Any
 
 import base_cli
-import base_cli_demo.cli as cli_module
 import pytest
 
 from base_cli_demo.cli import command
@@ -18,11 +17,14 @@ def invoke(args: list[str], home: Path) -> Any:
 def test_yaml_without_optional_renderer_fails_before_reconciliation_state(
     monkeypatch: pytest.MonkeyPatch, tmp_path: Path
 ) -> None:
-    monkeypatch.setattr(cli_module, "find_spec", lambda _name: None)
+    def missing_renderer(_name: str) -> object:
+        raise ModuleNotFoundError("yaml")
+
+    monkeypatch.setattr("base_cli_demo.cli.import_module", missing_renderer)
     result = invoke(["release", "reconcile", "--format", "yaml"], tmp_path)
 
     assert result.exit_code == 1
-    assert "base-cli-demo[yaml]" in result.output
+    assert "base-cli-demo[yaml]" in result.output + getattr(result, "stderr", "")
     assert list(tmp_path.rglob("last-reconciliation.json")) == []