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

{nac_cli-0.1.0 → nac_cli-0.2.1}/.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.1}/.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.1/CHANGELOG.md

@@ -0,0 +1,13 @@
+## 0.2.1
+
+- Read `nac.yaml` defaults from a `config` section in the module's `nac/manifest.yaml`: `render.resource` (relative to the module, e.g. `local_sensitive_file.model` becomes `module.nxos.local_sensitive_file.model`), `render.output` and `env.required`. Settings in the project's `nac.yaml` take precedence key by key, an explicit `null` turns a default off, and an invalid `config` section is ignored with a warning; `nac setup` lists the defaults taken from the module
+- Fail `nac validate` with a clear message if the render step didn't write `render.output` (e.g. because it doesn't match the module's `write_model_file`), and show the output path in the Render Summary
+
+## 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.1/PKG-INFO

@@ -0,0 +1,106 @@
+Metadata-Version: 2.5
+Name: nac-cli
+Version: 0.2.1
+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.1/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.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "nac-cli"
-version = "0.1.0"
+version = "0.2.1"
 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.1/release-notes.md

@@ -0,0 +1,3 @@
+
+- Read `nac.yaml` defaults from a `config` section in the module's `nac/manifest.yaml`: `render.resource` (relative to the module, e.g. `local_sensitive_file.model` becomes `module.nxos.local_sensitive_file.model`), `render.output` and `env.required`. Settings in the project's `nac.yaml` take precedence key by key, an explicit `null` turns a default off, and an invalid `config` section is ignored with a warning; `nac setup` lists the defaults taken from the module
+- Fail `nac validate` with a clear message if the render step didn't write `render.output` (e.g. because it doesn't match the module's `write_model_file`), and show the output path in the Render Summary

{nac_cli-0.1.0 → nac_cli-0.2.1}/src/nac/cli/main.py

@@ -12,12 +12,23 @@ from typing import NoReturn, cast
 import typer
 
 from nac import terraform
-from nac.config import DEFAULT_CONFIG_PATH, NacConfig, load_config
+from nac.config import (
+    DEFAULT_CONFIG_PATH,
+    NacConfig,
+    build_config,
+    merge_defaults,
+    read_raw_config,
+)
 from nac.exceptions import ConfigError, EngineNotFoundError, NoEngineAvailableError
+from nac.manifest import load_manifest
 from nac.output import ensure_utf8_streams
 
 from .options import ConfigPath, NoColor, Verbosity, VerbosityLevel, Version
 
+# ctx.meta keys set by get_config
+MANIFEST_META_KEY = "manifest"
+MODULE_DEFAULTS_META_KEY = "module_defaults"
+
 app = typer.Typer(
     add_completion=False,
     help="An umbrella CLI wrapping terraform/tofu, nac-validate, and nac-test.",
@@ -47,13 +58,27 @@ def get_config(ctx: typer.Context) -> NacConfig:
     file present. `ctx.obj` starts out holding the raw --config path and
     is replaced with the resolved NacConfig on first call, so repeated
     calls within the same invocation don't re-read the file.
+
+    nac.yaml settings the project leaves unset are filled from the `config`
+    section of the initialized module's manifest. The manifest and the
+    dotted keys taken from it are stashed on `ctx.meta`.
     """
     if isinstance(ctx.obj, NacConfig):
         return ctx.obj
+    path = cast(Path, ctx.obj)
     try:
-        cfg = load_config(cast(Path, ctx.obj))
+        raw = read_raw_config(path)
+        cfg = build_config(raw, path)
+        manifest = load_manifest(cfg.working_dir)
+        applied: list[str] = []
+        if manifest is not None and manifest.config:
+            merged, applied = merge_defaults(raw, manifest.config)
+            if applied:
+                cfg = build_config(merged, path)
     except ConfigError as exc:
         fail(str(exc))
+    ctx.meta[MANIFEST_META_KEY] = manifest
+    ctx.meta[MODULE_DEFAULTS_META_KEY] = applied
     ctx.obj = cfg
     return cfg
 

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

@@ -19,16 +19,12 @@ from nac.manifest import MANIFEST_FILE
 from nac.output import apply_no_color_env, echo_summary, format_command
 from nac.tools import ToolSource
 
-from .main import app, fail, get_config, get_no_color
+from .main import MODULE_DEFAULTS_META_KEY, app, fail, get_config, get_no_color
 from .options import Prewarm, Yes
 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)
@@ -120,7 +114,14 @@ def setup(ctx: typer.Context, yes: Yes = False, prewarm: Prewarm = False) -> Non
 
     manifest = get_manifest(ctx, cfg)
     if manifest is not None:
-        lines.append(f"tested versions: {manifest.module} ({MANIFEST_FILE})")
+        if manifest.tools:
+            lines.append(f"tested versions: {manifest.module} ({MANIFEST_FILE})")
+        module_defaults = ctx.meta.get(MODULE_DEFAULTS_META_KEY) or []
+        if module_defaults:
+            lines.append(
+                f"module defaults: {', '.join(module_defaults)} "
+                f"(from {manifest.module})"
+            )
 
     missing_env = [name for name in cfg.env.required if name not in os.environ]
     if missing_env:
@@ -151,6 +152,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.1}/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.1}/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",
@@ -68,20 +78,27 @@ def validate(ctx: typer.Context, artifacts: Artifacts = False) -> None:
         log_written = True
         if code != 0:
             raise typer.Exit(code=code)
+        output = cfg.render.output
+        if output is not None and not (cfg.working_dir / output).exists():
+            fail(
+                f"Render step `{cfg.render.target}` did not write `{output}`. "
+                "Check that `render.output` matches the file written by the "
+                "render target (for Network-as-Code modules: `write_model_file`)."
+            )
         if quiet:
             echo_summary(
                 "Render Summary",
                 [
                     f"Render: {color(GREEN, 'OK', no_color=no_color)} "
-                    f"({cfg.render.target})"
+                    f"({cfg.render.target} -> {output})"
                 ],
                 no_color=no_color,
             )
 
     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.1}/src/nac/cli/versions.py

@@ -19,14 +19,17 @@ from nac.config import NacConfig
 from nac.manifest import Manifest, load_manifest
 from nac.output import YELLOW, color
 
-_MANIFEST_KEY = "manifest"
+from .main import MANIFEST_META_KEY
 
 
 def get_manifest(ctx: typer.Context, cfg: NacConfig) -> Manifest | None:
-    """Load (once per invocation) the manifest of the initialized module."""
-    if _MANIFEST_KEY not in ctx.meta:
-        ctx.meta[_MANIFEST_KEY] = load_manifest(cfg.working_dir)
-    return cast("Manifest | None", ctx.meta[_MANIFEST_KEY])
+    """Load (once per invocation) the manifest of the initialized module.
+
+    Normally already loaded by `get_config`.
+    """
+    if MANIFEST_META_KEY not in ctx.meta:
+        ctx.meta[MANIFEST_META_KEY] = load_manifest(cfg.working_dir)
+    return cast("Manifest | None", ctx.meta[MANIFEST_META_KEY])
 
 
 def tool_warnings(

{nac_cli-0.1.0 → nac_cli-0.2.1}/src/nac/config.py

@@ -5,8 +5,9 @@
 # names as nac.yaml's own keys; pydantic only warns because they shadow
 # deprecated pydantic-v1 classmethods that this codebase never calls.
 import warnings
+from collections.abc import Mapping
 from pathlib import Path
-from typing import Literal
+from typing import Any, Literal
 
 import pydantic
 import ruamel.yaml
@@ -95,15 +96,28 @@ class NacConfig(BaseModel):
     env: EnvConfig = EnvConfig()
 
 
-def load_config(path: Path | str = DEFAULT_CONFIG_PATH) -> NacConfig:
+def load_config(
+    path: Path | str = DEFAULT_CONFIG_PATH,
+    *,
+    defaults: Mapping[str, Any] | None = None,
+) -> NacConfig:
     """Load, validate, and resolve conventions for a nac.yaml file.
 
     A missing file is treated as an empty config -- every field defaults,
-    so `nac` works with zero config present. Raises ConfigError (never a
-    raw pydantic/ruamel traceback) on malformed YAML or a schema
-    validation failure.
+    so `nac` works with zero config present. `defaults` (a module's
+    manifest `config`) fills in whatever the file doesn't set; see
+    `merge_defaults`. Raises ConfigError (never a raw pydantic/ruamel
+    traceback) on malformed YAML or a schema validation failure.
     """
     path = Path(path)
+    raw = read_raw_config(path)
+    if defaults is not None:
+        raw, _ = merge_defaults(raw, defaults)
+    return build_config(raw, path)
+
+
+def read_raw_config(path: Path) -> dict[str, Any]:
+    """The nac.yaml mapping as written, without validation or defaults."""
     raw: object = {}
     if path.is_file():
         yaml = ruamel.yaml.YAML(typ="safe")
@@ -119,7 +133,11 @@ def load_config(path: Path | str = DEFAULT_CONFIG_PATH) -> NacConfig:
         raise ConfigError(
             f"Config file {path} must contain a YAML mapping at the top level"
         )
+    return raw
 
+
+def build_config(raw: Mapping[str, Any], path: Path) -> NacConfig:
+    """Validate a raw nac.yaml mapping and apply filesystem conventions."""
     try:
         cfg = NacConfig.model_validate(raw)
     except pydantic.ValidationError as exc:
@@ -128,6 +146,40 @@ def load_config(path: Path | str = DEFAULT_CONFIG_PATH) -> NacConfig:
     return _apply_filesystem_defaults(cfg, path)
 
 
+def merge_defaults(
+    raw: Mapping[str, Any], defaults: Mapping[str, Any]
+) -> tuple[dict[str, Any], list[str]]:
+    """Fill `raw` (nac.yaml as written) with `defaults` (from a manifest).
+
+    Mappings are merged key by key; any other value set in `raw` -- lists
+    and an explicit `null` included -- wins as a whole. So
+    `render: {output: x.yaml}` keeps the module's render target, while
+    `render: null` or `render: {target: null}` turns it off.
+
+    Returns the merged mapping and the dotted keys taken from `defaults`.
+    """
+    merged = dict(raw)
+    applied: list[str] = []
+    for key, value in defaults.items():
+        if key not in raw:
+            merged[key] = value
+            applied.extend(_leaf_keys(key, value))
+        elif isinstance(raw[key], Mapping) and isinstance(value, Mapping):
+            merged[key], nested = merge_defaults(raw[key], value)
+            applied.extend(f"{key}.{leaf}" for leaf in nested)
+    return merged, applied
+
+
+def _leaf_keys(prefix: str, value: Any) -> list[str]:
+    if isinstance(value, Mapping) and value:
+        return [
+            leaf
+            for key, nested in value.items()
+            for leaf in _leaf_keys(f"{prefix}.{key}", nested)
+        ]
+    return [prefix]
+
+
 def _format_validation_error(path: Path, exc: pydantic.ValidationError) -> str:
     lines = [f"Invalid config file: {path}"]
     for err in exc.errors():

{nac_cli-0.1.0 → nac_cli-0.2.1}/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."""