nac-cli 0.1.0__tar.gz → 0.2.0__tar.gz

{nac_cli-0.1.0 → nac_cli-0.2.0}/.github/workflows/release.yml

@@ -20,7 +20,7 @@ jobs:
       - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e  # v10.3.2
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
 
       - name: Check tag matches project version
         env:
@@ -102,7 +102,7 @@ jobs:
       id-token: write  # Required for PyPI trusted publishing
     steps:
       - name: Install uv
-        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e  # v10.3.2
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
 
       - name: Download distributions
         uses: actions/download-artifact@9000827ccba6bdab643e8b6fd33ac0654aef8333  # v8.0.2

{nac_cli-0.1.0 → nac_cli-0.2.0}/.github/workflows/test.yml

@@ -21,7 +21,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e  # v10.3.2
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
         with:
           enable-cache: true
 
@@ -49,7 +49,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1  # v7.0.1
 
       - name: Install uv
-        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e  # v10.3.2
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
         with:
           enable-cache: true
 
@@ -89,7 +89,7 @@ jobs:
           python-version: ${{ matrix.python }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@07a047e608db84b3d8c06cd9a7c7dcc9c355c18e  # v10.3.2
+        uses: astral-sh/setup-uv@68559e99cc807c1eb7e9238fd43a15bba460eec2  # v10.3.3
         with:
           enable-cache: true
 

nac_cli-0.2.0/CHANGELOG.md

@@ -0,0 +1,8 @@
+## 0.2.0
+
+- Only require `uv` when `nac-validate`/`nac-test` aren't installed locally in a satisfying version: `nac setup` no longer fails without `uv` if both tools resolve locally, and `nac validate`/`nac test` fail with a clear message (instead of a missing-executable error) when `uvx` would be needed but `uv` isn't on `PATH`
+- Enable `nac-validate`'s and `nac-test`'s `--artifacts` option (schema, rules and test templates packaged with the module or with bundles) by default via `NAC_VALIDATE_ARTIFACTS`/`NAC_TEST_ARTIFACTS`; versions without the option ignore it, and an existing value of the env var or a passed-through `--no-artifacts` takes precedence
+
+## 0.1.0
+
+- Initial release

nac_cli-0.2.0/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: nac-cli
+Version: 0.2.0
+Summary: An umbrella CLI wrapping terraform/tofu, nac-validate, and nac-test for Network-as-Code workflows.
+Project-URL: homepage, https://github.com/netascode/nac
+Project-URL: repository, https://github.com/netascode/nac
+Project-URL: documentation, https://github.com/netascode/nac
+Author-email: Daniel Schmidt <danischm@cisco.com>
+Maintainer-email: Daniel Schmidt <danischm@cisco.com>
+License: MPL-2.0
+License-File: LICENSE
+Keywords: automation,cli,nac,network-as-code,opentofu,terraform
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Mozilla Public License 2.0 (MPL 2.0)
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Software Development :: Build Tools
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.28
+Requires-Dist: packaging>=24
+Requires-Dist: platformdirs>=4.3
+Requires-Dist: pydantic>=2.9
+Requires-Dist: ruamel-yaml>=0.19.1
+Requires-Dist: typer>=0.25.1
+Provides-Extra: dev
+Requires-Dist: bandit[toml]>=1.9.1; extra == 'dev'
+Requires-Dist: pre-commit>=4.4.0; extra == 'dev'
+Requires-Dist: pytest-cov>=7.0.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.15.1; extra == 'dev'
+Requires-Dist: pytest>=9.0.1; extra == 'dev'
+Requires-Dist: ruff>=0.14.5; extra == 'dev'
+Requires-Dist: ty>=0.0.78; extra == 'dev'
+Description-Content-Type: text/markdown
+
+[![Tests](https://github.com/netascode/nac/actions/workflows/test.yml/badge.svg)](https://github.com/netascode/nac/actions/workflows/test.yml)
+![Python Support](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-informational "Python Support: 3.11, 3.12, 3.13, 3.14")
+
+# nac
+
+An umbrella CLI for Network-as-Code workflows, driven by a single `nac.yaml`
+config file.
+
+Every Network-as-Code repository runs the same workflow, regardless of the
+architecture: validate the data model, plan, apply and test. Each step uses a
+different tool with its own options: `terraform` or `tofu`, `nac-validate` and
+`nac-test`. `nac` is a single CLI for the whole workflow. The repository is
+described once in `nac.yaml`, and the same commands work on a laptop and in a
+CI/CD pipeline:
+
+```bash
+nac setup       # verify prerequisites and report resolved tool versions
+nac init        # terraform/tofu init
+nac validate    # nac-validate against the configured data paths
+nac plan        # terraform/tofu plan -> plan.tfplan
+nac apply       # apply the saved plan (or interactively, without one)
+nac test        # nac-test against the configured data/templates/output
+nac destroy     # destroy the managed infrastructure
+```
+
+Full documentation: https://netascode.cisco.com/docs/tools/nac/overview
+
+## How It Works
+
+- **One configuration file:** `nac.yaml` defines where the data model,
+  schema, rules and test templates are located, which Terraform engine to use
+  and which environment variables are required. Every field has a default, so
+  a repository following the `data/` and `tests/` conventions works without a
+  `nac.yaml` at all.
+- **Managed toolchain:** `nac-validate` and `nac-test` are used from a local
+  installation if one satisfies the configured version, or run via `uvx`
+  otherwise. If neither `terraform` nor `tofu` is installed, `nac setup` can
+  install OpenTofu.
+- **Tested versions:** a Network-as-Code Terraform module can declare the
+  `nac-validate` and `nac-test` versions it was tested with in
+  `nac/manifest.yaml`. `nac` then uses a compatible version by default and
+  warns about versions outside of the tested range.
+- **Pass-through:** arguments not known to `nac` are forwarded to the wrapped
+  tool, and the exit code of the wrapped tool is returned.
+
+## Installation
+
+`nac` is published on PyPI as **`nac-cli`**; the command it installs is `nac`.
+Install it with [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+uv tool install nac-cli
+```
+
+> [!WARNING]
+> Don't `pip install nac` or run `uvx nac` -- that is a different, unrelated
+> package.
+
+See the [installation docs](https://netascode.cisco.com/docs/tools/nac/installation/)
+for prerequisites, and [usage](https://netascode.cisco.com/docs/tools/nac/usage/)
+and [configuration](https://netascode.cisco.com/docs/tools/nac/configuration/)
+for the full command and `nac.yaml` reference.
+
+## License
+
+[MPL-2.0](LICENSE)

nac_cli-0.2.0/README.md

@@ -0,0 +1,66 @@
+[![Tests](https://github.com/netascode/nac/actions/workflows/test.yml/badge.svg)](https://github.com/netascode/nac/actions/workflows/test.yml)
+![Python Support](https://img.shields.io/badge/python-3.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-informational "Python Support: 3.11, 3.12, 3.13, 3.14")
+
+# nac
+
+An umbrella CLI for Network-as-Code workflows, driven by a single `nac.yaml`
+config file.
+
+Every Network-as-Code repository runs the same workflow, regardless of the
+architecture: validate the data model, plan, apply and test. Each step uses a
+different tool with its own options: `terraform` or `tofu`, `nac-validate` and
+`nac-test`. `nac` is a single CLI for the whole workflow. The repository is
+described once in `nac.yaml`, and the same commands work on a laptop and in a
+CI/CD pipeline:
+
+```bash
+nac setup       # verify prerequisites and report resolved tool versions
+nac init        # terraform/tofu init
+nac validate    # nac-validate against the configured data paths
+nac plan        # terraform/tofu plan -> plan.tfplan
+nac apply       # apply the saved plan (or interactively, without one)
+nac test        # nac-test against the configured data/templates/output
+nac destroy     # destroy the managed infrastructure
+```
+
+Full documentation: https://netascode.cisco.com/docs/tools/nac/overview
+
+## How It Works
+
+- **One configuration file:** `nac.yaml` defines where the data model,
+  schema, rules and test templates are located, which Terraform engine to use
+  and which environment variables are required. Every field has a default, so
+  a repository following the `data/` and `tests/` conventions works without a
+  `nac.yaml` at all.
+- **Managed toolchain:** `nac-validate` and `nac-test` are used from a local
+  installation if one satisfies the configured version, or run via `uvx`
+  otherwise. If neither `terraform` nor `tofu` is installed, `nac setup` can
+  install OpenTofu.
+- **Tested versions:** a Network-as-Code Terraform module can declare the
+  `nac-validate` and `nac-test` versions it was tested with in
+  `nac/manifest.yaml`. `nac` then uses a compatible version by default and
+  warns about versions outside of the tested range.
+- **Pass-through:** arguments not known to `nac` are forwarded to the wrapped
+  tool, and the exit code of the wrapped tool is returned.
+
+## Installation
+
+`nac` is published on PyPI as **`nac-cli`**; the command it installs is `nac`.
+Install it with [uv](https://docs.astral.sh/uv/getting-started/installation/):
+
+```bash
+uv tool install nac-cli
+```
+
+> [!WARNING]
+> Don't `pip install nac` or run `uvx nac` -- that is a different, unrelated
+> package.
+
+See the [installation docs](https://netascode.cisco.com/docs/tools/nac/installation/)
+for prerequisites, and [usage](https://netascode.cisco.com/docs/tools/nac/usage/)
+and [configuration](https://netascode.cisco.com/docs/tools/nac/configuration/)
+for the full command and `nac.yaml` reference.
+
+## License
+
+[MPL-2.0](LICENSE)

{nac_cli-0.1.0 → nac_cli-0.2.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nac-cli"
-version = "0.1.0"
+version = "0.2.0"
 description = "An umbrella CLI wrapping terraform/tofu, nac-validate, and nac-test for Network-as-Code workflows."
 license = { text = "MPL-2.0" }
 readme = "README.md"

nac_cli-0.2.0/release-notes.md

@@ -0,0 +1,3 @@
+
+- Only require `uv` when `nac-validate`/`nac-test` aren't installed locally in a satisfying version: `nac setup` no longer fails without `uv` if both tools resolve locally, and `nac validate`/`nac test` fail with a clear message (instead of a missing-executable error) when `uvx` would be needed but `uv` isn't on `PATH`
+- Enable `nac-validate`'s and `nac-test`'s `--artifacts` option (schema, rules and test templates packaged with the module or with bundles) by default via `NAC_VALIDATE_ARTIFACTS`/`NAC_TEST_ARTIFACTS`; versions without the option ignore it, and an existing value of the env var or a passed-through `--no-artifacts` takes precedence

{nac_cli-0.1.0 → nac_cli-0.2.0}/src/nac/cli/setup.py

@@ -25,10 +25,6 @@ from .versions import emit_warnings, get_manifest, tool_warnings
 
 logger = logging.getLogger(__name__)
 
-UV_NOT_FOUND = (
-    "`uv` not found on PATH -- install it: "
-    "https://docs.astral.sh/uv/getting-started/installation/"
-)
 TENV_NOT_FOUND = (
     "`tenv` not found on PATH -- required because `tools.terraform.version` "
     "is set. Install tenv: https://github.com/tofuutils/tenv"
@@ -89,9 +85,7 @@ def setup(ctx: typer.Context, yes: Yes = False, prewarm: Prewarm = False) -> Non
     cfg = get_config(ctx)
     no_color = get_no_color(ctx)
 
-    if shutil.which("uv") is None:
-        fail(UV_NOT_FOUND)
-    lines: list[str] = ["uv: found"]
+    lines: list[str] = []
 
     if cfg.tools.terraform.version is not None and shutil.which("tenv") is None:
         fail(TENV_NOT_FOUND)
@@ -151,6 +145,23 @@ def setup(ctx: typer.Context, yes: Yes = False, prewarm: Prewarm = False) -> Non
     test_line, test_source, test_constraint = _tool_summary_line(
         "nac-test", cfg.tools.nac_test
     )
+    uv_errors: list[str] = []
+    if validate_source.mode == "uvx":
+        uv_errors.append(
+            tools.uv_not_found_message(
+                "nac-validate", validate_source, validate_constraint
+            )
+        )
+    if test_source.mode == "uvx":
+        uv_errors.append(
+            tools.uv_not_found_message("nac-test", test_source, test_constraint)
+        )
+    if tools.uv_available():
+        lines.insert(0, "uv: found")
+    elif uv_errors:
+        fail("\n".join(uv_errors))
+    else:
+        lines.insert(0, "uv: not found (not needed, all tools resolve locally)")
     lines.append(validate_line)
     lines.append(test_line)
     warnings = [

{nac_cli-0.1.0 → nac_cli-0.2.0}/src/nac/cli/test.py

@@ -6,9 +6,9 @@
 import typer
 
 from nac import runner, tools
-from nac.output import apply_no_color_env
+from nac.exceptions import UvNotFoundError
 
-from .main import app, get_config, get_no_color
+from .main import app, fail, get_config, get_no_color
 from .options import Artifacts
 from .passthrough import (
     PASSTHROUGH_CONTEXT_SETTINGS,
@@ -34,15 +34,24 @@ def test_(ctx: typer.Context, artifacts: Artifacts = False) -> None:
     log_path = cfg.working_dir / "test.txt" if artifacts else None
     manifest = get_manifest(ctx, cfg)
 
-    if wants_help(ctx):
-        show_help_and_exit(
-            ctx,
+    try:
+        tool_argv = (
             tools.build_help_argv(
                 "nac-test",
                 tools.tool_constraint("nac-test", cfg.tools.nac_test, manifest),
-            ),
+            )
+            if wants_help(ctx)
+            else tools.build_test_argv(cfg, manifest) + ctx.args
+        )
+    except UvNotFoundError as exc:
+        fail(str(exc))
+
+    if wants_help(ctx):
+        show_help_and_exit(
+            ctx,
+            tool_argv,
             cwd=cfg.working_dir,
-            env=apply_no_color_env(no_color),
+            env=tools.build_tool_env("nac-test", no_color=no_color),
             no_color=no_color,
             tool_label="nac-test",
             usage_as="nac test",
@@ -52,9 +61,9 @@ def test_(ctx: typer.Context, artifacts: Artifacts = False) -> None:
     log_written = emit_warnings(warnings, no_color=no_color, log_path=log_path)
 
     code = runner.run_streaming(
-        tools.build_test_argv(cfg, manifest) + ctx.args,
+        tool_argv,
         cwd=cfg.working_dir,
-        env=apply_no_color_env(no_color),
+        env=tools.build_tool_env("nac-test", no_color=no_color),
         log_path=log_path,
         append=log_written,
         no_color=no_color,

{nac_cli-0.1.0 → nac_cli-0.2.0}/src/nac/cli/validate.py

@@ -8,9 +8,10 @@ import logging
 import typer
 
 from nac import runner, terraform, tools
-from nac.output import GREEN, apply_no_color_env, color, echo_summary
+from nac.exceptions import UvNotFoundError
+from nac.output import GREEN, color, echo_summary
 
-from .main import app, get_config, get_no_color, resolve_engine_or_exit
+from .main import app, fail, get_config, get_no_color, resolve_engine_or_exit
 from .options import Artifacts
 from .passthrough import (
     PASSTHROUGH_CONTEXT_SETTINGS,
@@ -36,12 +37,21 @@ def validate(ctx: typer.Context, artifacts: Artifacts = False) -> None:
     manifest = get_manifest(ctx, cfg)
     constraint = tools.tool_constraint("nac-validate", cfg.tools.nac_validate, manifest)
 
+    try:
+        tool_argv = (
+            tools.build_help_argv("nac-validate", constraint)
+            if wants_help(ctx)
+            else tools.build_validate_argv(cfg, manifest) + ctx.args
+        )
+    except UvNotFoundError as exc:
+        fail(str(exc))
+
     if wants_help(ctx):
         show_help_and_exit(
             ctx,
-            tools.build_help_argv("nac-validate", constraint),
+            tool_argv,
             cwd=cfg.working_dir,
-            env=apply_no_color_env(no_color),
+            env=tools.build_tool_env("nac-validate", no_color=no_color),
             no_color=no_color,
             tool_label="nac-validate",
             usage_as="nac validate",
@@ -79,9 +89,9 @@ def validate(ctx: typer.Context, artifacts: Artifacts = False) -> None:
             )
 
     code = runner.run_streaming(
-        tools.build_validate_argv(cfg, manifest) + ctx.args,
+        tool_argv,
         cwd=cfg.working_dir,
-        env=apply_no_color_env(no_color),
+        env=tools.build_tool_env("nac-validate", no_color=no_color),
         log_path=log_path,
         append=log_written,
         no_color=no_color,

{nac_cli-0.1.0 → nac_cli-0.2.0}/src/nac/exceptions.py

@@ -32,3 +32,7 @@ class BootstrapDeclinedError(BootstrapError):
 
 class ChecksumMismatchError(BootstrapError):
     """The downloaded archive's SHA-256 didn't match the published checksum."""
+
+
+class UvNotFoundError(NacError):
+    """A wrapped tool needs `uvx` (no usable local install) but uv isn't on PATH."""

{nac_cli-0.1.0 → nac_cli-0.2.0}/src/nac/tools.py

@@ -12,14 +12,17 @@ from packaging.specifiers import InvalidSpecifier, SpecifierSet
 from packaging.version import InvalidVersion, Version
 
 from nac.config import NacConfig, resolve_test_data, resolve_validate_data
+from nac.exceptions import UvNotFoundError
 from nac.manifest import Manifest, compatible_range
-from nac.output import format_command
+from nac.output import apply_no_color_env, format_command
 
 logger = logging.getLogger(__name__)
 
 _SPECIFIER_PREFIXES = ("==", "!=", ">=", "<=", "~=", ">", "<")
 _VERSION_RE = re.compile(r"\d+(?:\.\d+)+(?:[a-zA-Z0-9.\-+]*)?")
 
+UV_INSTALL_URL = "https://docs.astral.sh/uv/getting-started/installation/"
+
 
 def _pin_suffix(version: str) -> str:
     v = version.strip()
@@ -117,13 +120,42 @@ def resolve_tool_source(
     return ToolSource(mode="uvx", path=None, version=version)
 
 
+def uv_available() -> bool:
+    """Whether uv (which provides `uvx`) is on PATH."""
+    return shutil.which("uv") is not None
+
+
+def uv_not_found_message(
+    tool: Literal["nac-validate", "nac-test"],
+    source: ToolSource,
+    constraint: str | None,
+) -> str:
+    """Explain why `tool` needs uv and how to fix it (install uv or the tool)."""
+    if source.version is not None:
+        reason = f"local {tool} v{source.version} does not satisfy {constraint}"
+    else:
+        reason = f"{tool} is not installed locally"
+    wanted = f"{tool}{_pin_suffix(constraint)}" if constraint is not None else tool
+    return (
+        f"{reason}, so it would be run via `uvx`, but `uv` was not found on "
+        f"PATH -- install uv ({UV_INSTALL_URL}) or install {wanted} yourself."
+    )
+
+
 def _tool_prefix(
     tool: Literal["nac-validate", "nac-test"], constraint: str | None
 ) -> list[str]:
+    """Command prefix for `tool`: the local binary, else `uvx [--from ...]`.
+
+    Raises `UvNotFoundError` if `uvx` would be needed but isn't on PATH, so
+    `nac` works without uv as long as suitable local installs exist.
+    """
     source = resolve_tool_source(tool, constraint)
     if source.mode == "local":
         assert source.path is not None
         return [source.path]
+    if not uv_available():
+        raise UvNotFoundError(uv_not_found_message(tool, source, constraint))
     argv = ["uvx"]
     if constraint is not None:
         argv += ["--from", f"{tool}{_pin_suffix(constraint)}"]
@@ -156,6 +188,28 @@ def build_test_argv(cfg: NacConfig, manifest: Manifest | None = None) -> list[st
     return argv
 
 
+# Env vars turning on bundle/module artifact discovery in nac-validate/nac-test
+# (`--artifacts`). Set via env rather than the CLI flag so that tool versions
+# predating the option simply ignore it.
+_ARTIFACTS_ENV = {
+    "nac-validate": "NAC_VALIDATE_ARTIFACTS",
+    "nac-test": "NAC_TEST_ARTIFACTS",
+}
+
+
+def build_tool_env(
+    tool: Literal["nac-validate", "nac-test"], *, no_color: bool
+) -> dict[str, str]:
+    """Subprocess env for `tool`, with artifacts enabled by default.
+
+    A value already set in the environment wins, and a passed-through
+    `--no-artifacts` overrides the env var, so users can still opt out.
+    """
+    env = apply_no_color_env(no_color)
+    env.setdefault(_ARTIFACTS_ENV[tool], "true")
+    return env
+
+
 def build_prewarm_argv(
     tool: Literal["nac-validate", "nac-test"], version: str | None
 ) -> list[str]:

{nac_cli-0.1.0 → nac_cli-0.2.0}/tests/unit/test_cli_commands.py

@@ -41,7 +41,9 @@ def _tofu_on_path(mocker):
     """Make `tofu` resolve as the engine everywhere via a shared shutil.which."""
     mocker.patch(
         "shutil.which",
-        side_effect=_which({"tofu": "/usr/bin/tofu", "terraform": None}),
+        side_effect=_which(
+            {"tofu": "/usr/bin/tofu", "terraform": None, "uv": "/usr/bin/uv"}
+        ),
     )
 
 
@@ -108,7 +110,7 @@ def test_init_propagates_nonzero_exit_code(tmp_path, mocker, _tofu_on_path):
 @pytest.mark.unit
 def test_init_fails_cleanly_when_no_engine_available(tmp_path, mocker):
     config_path = _write_config(tmp_path, "")
-    mocker.patch("shutil.which", return_value=None)
+    mocker.patch("shutil.which", side_effect=_which({"uv": "/usr/bin/uv"}))
     run_streaming_mock = mocker.patch("nac.cli.init.runner.run_streaming")
 
     result = cli.invoke(app, ["--config", str(config_path), "init"])
@@ -125,7 +127,7 @@ def test_init_fails_cleanly_when_no_engine_available(tmp_path, mocker):
 @pytest.mark.unit
 def test_validate_without_render_target_skips_render_step(tmp_path, mocker):
     config_path = _write_config(tmp_path, "")
-    mocker.patch("shutil.which", return_value=None)
+    mocker.patch("shutil.which", side_effect=_which({"uv": "/usr/bin/uv"}))
     run_streaming_mock = mocker.patch(
         "nac.cli.validate.runner.run_streaming", return_value=0
     )
@@ -139,6 +141,42 @@ def test_validate_without_render_target_skips_render_step(tmp_path, mocker):
     assert "nac-validate" in argv
 
 
+@pytest.mark.unit
+def test_validate_without_uv_uses_local_install(tmp_path, mocker):
+    config_path = _write_config(tmp_path, "")
+    mocker.patch(
+        "shutil.which",
+        side_effect=_which({"nac-validate": "/usr/bin/nac-validate"}),
+    )
+    mocker.patch("nac.tools._local_tool_version", return_value="1.2.3")
+    run_streaming_mock = mocker.patch(
+        "nac.cli.validate.runner.run_streaming", return_value=0
+    )
+
+    result = cli.invoke(app, ["--config", str(config_path), "validate"])
+
+    assert result.exit_code == 0
+    argv = run_streaming_mock.call_args_list[0].args[0]
+    assert argv[0] == "/usr/bin/nac-validate"
+
+
+@pytest.mark.unit
+def test_validate_without_uv_or_local_install_fails_before_render(tmp_path, mocker):
+    config_path = _write_config(
+        tmp_path,
+        "render:\n  target: module.example\n  output: rendered/\n",
+    )
+    mocker.patch("shutil.which", side_effect=_which({"tofu": "/usr/bin/tofu"}))
+    run_streaming_mock = mocker.patch("nac.cli.validate.runner.run_streaming")
+
+    result = cli.invoke(app, ["--config", str(config_path), "validate"])
+
+    assert result.exit_code == 1
+    assert "nac-validate is not installed locally" in result.output
+    assert "`uv` was not found on PATH" in result.output
+    run_streaming_mock.assert_not_called()
+
+
 @pytest.mark.unit
 def test_validate_with_render_target_runs_render_then_validate(
     tmp_path, mocker, _tofu_on_path
@@ -575,7 +613,7 @@ def test_destroy_propagates_nonzero_exit_code(tmp_path, mocker, _tofu_on_path):
 @pytest.mark.unit
 def test_destroy_fails_cleanly_when_no_engine_available(tmp_path, mocker):
     config_path = _write_config(tmp_path, "")
-    mocker.patch("shutil.which", return_value=None)
+    mocker.patch("shutil.which", side_effect=_which({"uv": "/usr/bin/uv"}))
     run_streaming_mock = mocker.patch("nac.cli.destroy.runner.run_streaming")
 
     result = cli.invoke(app, ["--config", str(config_path), "destroy"])
@@ -592,7 +630,7 @@ def test_destroy_fails_cleanly_when_no_engine_available(tmp_path, mocker):
 @pytest.mark.unit
 def test_test_streams_test_argv_and_propagates_exit_code(tmp_path, mocker):
     config_path = _write_config(tmp_path, "")
-    mocker.patch("shutil.which", return_value=None)
+    mocker.patch("shutil.which", side_effect=_which({"uv": "/usr/bin/uv"}))
     run_streaming_mock = mocker.patch(
         "nac.cli.test.runner.run_streaming", return_value=0
     )
@@ -606,6 +644,19 @@ def test_test_streams_test_argv_and_propagates_exit_code(tmp_path, mocker):
     assert run_streaming_mock.call_args_list[0].kwargs.get("log_path") is None
 
 
+@pytest.mark.unit
+def test_test_without_uv_or_local_install_fails_cleanly(tmp_path, mocker):
+    config_path = _write_config(tmp_path, "")
+    mocker.patch("shutil.which", side_effect=_which({}))
+    run_streaming_mock = mocker.patch("nac.cli.test.runner.run_streaming")
+
+    result = cli.invoke(app, ["--config", str(config_path), "test"])
+
+    assert result.exit_code == 1
+    assert "nac-test is not installed locally" in result.output
+    run_streaming_mock.assert_not_called()
+
+
 @pytest.mark.unit
 def test_test_with_artifacts_writes_test_txt(tmp_path, mocker):
     config_path = _write_config(tmp_path, "")
@@ -654,7 +705,7 @@ def test_validate_extra_args_are_appended(tmp_path, mocker):
 @pytest.mark.unit
 def test_validate_help_shows_own_and_tool_help(tmp_path, mocker):
     config_path = _write_config(tmp_path, "")
-    mocker.patch("shutil.which", return_value=None)
+    mocker.patch("shutil.which", side_effect=_which({"uv": "/usr/bin/uv"}))
     run_mock = mocker.patch(
         "nac.cli.passthrough.subprocess.run",
         return_value=subprocess.CompletedProcess(
@@ -747,7 +798,7 @@ def test_test_extra_args_are_appended(tmp_path, mocker):
 @pytest.mark.unit
 def test_test_help_shows_own_and_tool_help(tmp_path, mocker):
     config_path = _write_config(tmp_path, "")
-    mocker.patch("shutil.which", return_value=None)
+    mocker.patch("shutil.which", side_effect=_which({"uv": "/usr/bin/uv"}))
     run_mock = mocker.patch(
         "nac.cli.passthrough.subprocess.run",
         return_value=subprocess.CompletedProcess(
@@ -943,3 +994,43 @@ def test_run_shows_nac_as_program_name_under_alias(mocker, capsys):
     out = strip_ansi(capsys.readouterr().out)
     assert "Usage: nac [OPTIONS]" in out
     assert "nac-cli" not in out
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    ("command", "env_var"),
+    [("validate", "NAC_VALIDATE_ARTIFACTS"), ("test", "NAC_TEST_ARTIFACTS")],
+)
+def test_tool_artifacts_enabled_by_default(
+    tmp_path, mocker, monkeypatch, command, env_var
+):
+    monkeypatch.delenv(env_var, raising=False)
+    config_path = _write_config(tmp_path, "")
+    run_streaming_mock = mocker.patch(
+        f"nac.cli.{command}.runner.run_streaming", return_value=0
+    )
+
+    result = cli.invoke(app, ["--config", str(config_path), command])
+
+    assert result.exit_code == 0
+    assert run_streaming_mock.call_args.kwargs["env"][env_var] == "true"
+
+
+@pytest.mark.unit
+@pytest.mark.parametrize(
+    ("command", "env_var"),
+    [("validate", "NAC_VALIDATE_ARTIFACTS"), ("test", "NAC_TEST_ARTIFACTS")],
+)
+def test_tool_artifacts_env_override_is_kept(
+    tmp_path, mocker, monkeypatch, command, env_var
+):
+    monkeypatch.setenv(env_var, "false")
+    config_path = _write_config(tmp_path, "")
+    run_streaming_mock = mocker.patch(
+        f"nac.cli.{command}.runner.run_streaming", return_value=0
+    )
+
+    result = cli.invoke(app, ["--config", str(config_path), command])
+
+    assert result.exit_code == 0
+    assert run_streaming_mock.call_args.kwargs["env"][env_var] == "false"