nac-cli 0.1.0__py3-none-any.whl

nac/config.py

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+# ValidateConfig.schema / NacConfig.validate intentionally use the same
+# 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 pathlib import Path
+from typing import Literal
+
+import pydantic
+import ruamel.yaml
+from pydantic import BaseModel, ConfigDict, model_validator
+
+from nac.exceptions import ConfigError
+
+warnings.filterwarnings(
+    "ignore",
+    message=r'Field name ".*" in ".*" shadows an attribute in parent "BaseModel"',
+    category=UserWarning,
+)
+
+DEFAULT_CONFIG_PATH = Path("nac.yaml")
+
+
+class DataConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    paths: list[str] = ["data/"]
+    defaults: str | None = None
+
+
+class RenderConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    target: str | None = None
+    output: str | None = None
+
+    @model_validator(mode="after")
+    def _target_requires_output(self) -> "RenderConfig":
+        if self.target is not None and self.output is None:
+            raise ValueError("render.output must be set when render.target is set")
+        return self
+
+
+class ValidateConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    schema: str | None = None  # ty: ignore[invalid-attribute-override]
+    rules: list[str] | None = None
+
+
+class TestConfig(BaseModel):
+    # Tells pytest not to try collecting this as a test class -- it's a
+    # config model that happens to be named after nac.yaml's `test:` key.
+    __test__ = False
+
+    model_config = ConfigDict(extra="forbid")
+
+    templates: str | None = None
+    filters: str | None = None
+    output: str = "tests/results"
+
+
+class TerraformToolConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    engine: Literal["tofu", "terraform"] | None = None
+    version: str | None = None
+
+
+class ToolsConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    terraform: TerraformToolConfig = TerraformToolConfig()
+    nac_validate: str | None = None
+    nac_test: str | None = None
+
+
+class EnvConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    required: list[str] = []
+
+
+class NacConfig(BaseModel):
+    model_config = ConfigDict(extra="forbid")
+
+    working_dir: Path = Path(".")
+    data: DataConfig = DataConfig()
+    render: RenderConfig | None = None
+    validate: ValidateConfig = ValidateConfig()  # ty: ignore[invalid-attribute-override]
+    test: TestConfig = TestConfig()
+    tools: ToolsConfig = ToolsConfig()
+    env: EnvConfig = EnvConfig()
+
+
+def load_config(path: Path | str = DEFAULT_CONFIG_PATH) -> 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.
+    """
+    path = Path(path)
+    raw: object = {}
+    if path.is_file():
+        yaml = ruamel.yaml.YAML(typ="safe")
+        try:
+            with path.open("r", encoding="utf-8") as fh:
+                raw = yaml.load(fh)
+        except ruamel.yaml.YAMLError as exc:
+            raise ConfigError(f"Failed to parse {path}: {exc}") from exc
+
+    if raw is None:
+        raw = {}
+    if not isinstance(raw, dict):
+        raise ConfigError(
+            f"Config file {path} must contain a YAML mapping at the top level"
+        )
+
+    try:
+        cfg = NacConfig.model_validate(raw)
+    except pydantic.ValidationError as exc:
+        raise ConfigError(_format_validation_error(path, exc)) from exc
+
+    return _apply_filesystem_defaults(cfg, path)
+
+
+def _format_validation_error(path: Path, exc: pydantic.ValidationError) -> str:
+    lines = [f"Invalid config file: {path}"]
+    for err in exc.errors():
+        loc = ".".join(str(part) for part in err["loc"]) or "<root>"
+        lines.append(f"  {loc}: {err['msg']}")
+    return "\n".join(lines)
+
+
+def _apply_filesystem_defaults(cfg: NacConfig, config_path: Path) -> NacConfig:
+    working_dir_abs = (config_path.parent / cfg.working_dir).resolve()
+
+    data = cfg.data
+    if data.defaults is None and (working_dir_abs / "defaults.yaml").is_file():
+        data = data.model_copy(update={"defaults": "defaults.yaml"})
+
+    test = cfg.test
+    if test.templates is None and (working_dir_abs / "tests" / "templates").is_dir():
+        test = test.model_copy(update={"templates": "tests/templates"})
+    if test.filters is None and (working_dir_abs / "tests" / "filters").is_dir():
+        test = test.model_copy(update={"filters": "tests/filters"})
+
+    return cfg.model_copy(
+        update={"working_dir": working_dir_abs, "data": data, "test": test}
+    )
+
+
+def resolve_validate_data(cfg: NacConfig) -> list[str]:
+    """Data paths for `nac validate`.
+
+    `render.output` if `render.target` is set, else `data.paths`.
+    """
+    if cfg.render is not None and cfg.render.target is not None:
+        if cfg.render.output is None:
+            raise ConfigError("render.output must be set when render.target is set")
+        return [cfg.render.output]
+    return list(cfg.data.paths)
+
+
+def resolve_test_data(cfg: NacConfig) -> list[str]:
+    """Data paths for `nac test`.
+
+    (`render.output` if `render` is configured, else `data.paths`) with
+    `data.defaults` appended whenever it's configured.
+    """
+    if cfg.render is not None:
+        base: list[str] = [cfg.render.output] if cfg.render.output is not None else []
+    else:
+        base = list(cfg.data.paths)
+    if cfg.data.defaults is not None:
+        base = [*base, cfg.data.defaults]
+    return base

nac/exceptions.py

@@ -0,0 +1,34 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+
+class NacError(Exception):
+    """Base class for all nac errors."""
+
+
+class ConfigError(NacError):
+    """Missing, malformed, or invalid nac.yaml."""
+
+
+class EngineNotFoundError(NacError):
+    """An explicitly-configured tools.terraform.engine binary is not on PATH."""
+
+
+class NoEngineAvailableError(NacError):
+    """Neither tofu nor terraform was found on PATH and no engine was configured."""
+
+
+class BootstrapError(NacError):
+    """Base class for OpenTofu zero-config bootstrap failures."""
+
+
+class UnsupportedPlatformError(BootstrapError):
+    """The current OS/architecture has no matching OpenTofu release asset."""
+
+
+class BootstrapDeclinedError(BootstrapError):
+    """Installation was not confirmed and no binary is already cached."""
+
+
+class ChecksumMismatchError(BootstrapError):
+    """The downloaded archive's SHA-256 didn't match the published checksum."""

nac/manifest.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""Tested-versions manifest shipped with a Network-as-Code Terraform module.
+
+A module may ship a `nac/manifest.yaml` (next to the rest of its nac-specific
+content: schema, rules, test templates) listing the nac-validate/nac-test
+versions it was tested with. terraform/tofu and provider versions are not
+part of it: the module's `versions.tf` already constrains those, and
+Terraform enforces them itself. After `terraform init`, `nac` finds it via
+`.terraform/modules/modules.json` and uses it purely as a hint: versions
+outside the tested, semver-compatible range produce a warning, never an
+error. A missing or unreadable manifest is silently ignored.
+"""
+
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Literal
+
+import pydantic
+import ruamel.yaml
+from packaging.specifiers import SpecifierSet
+from packaging.version import InvalidVersion, Version
+from pydantic import BaseModel, ConfigDict
+
+logger = logging.getLogger(__name__)
+
+MANIFEST_FILE = "nac/manifest.yaml"
+MODULES_JSON = Path(".terraform") / "modules" / "modules.json"
+_REGISTRY_HOSTS = ("registry.terraform.io/", "registry.opentofu.org/")
+
+
+class _ManifestFile(BaseModel):
+    # Unknown keys are ignored so newer manifests keep working with older nac.
+    model_config = ConfigDict(extra="ignore", coerce_numbers_to_str=True)
+
+    schema_version: Literal[1] = pydantic.Field(alias="schema")
+    tools: dict[str, str] = {}
+
+
+@dataclass(frozen=True)
+class Manifest:
+    """Tested versions for one module, keyed by tool name.
+
+    `module` is a human-readable label for messages, e.g.
+    `netascode/nac-nxos/nxos 0.3.0`.
+    """
+
+    module: str
+    tools: dict[str, str] = field(default_factory=dict)
+
+    def check_tool(self, name: str, actual: str | None) -> str | None:
+        """Warning message if `actual` is outside the tested range, else None."""
+        tested = self.tools.get(name)
+        if actual is None or tested is None:
+            return None
+        status = classify(actual, tested)
+        if status == "compatible":
+            logger.info(
+                "%s %s is newer than the version tested with %s (%s) but "
+                "semver-compatible",
+                name,
+                actual,
+                self.module,
+                tested,
+            )
+        if status != "untested":
+            return None
+        return (
+            f"{name} {actual} is outside the range tested with {self.module} "
+            f"(tested: {tested}, compatible: {compatible_range(tested)})"
+        )
+
+
+def compatible_range(tested: str) -> str | None:
+    """Semver-compatible range starting at `tested`.
+
+    Upward-only, up to the next major -- or the next minor for 0.x, where
+    a minor bump may be breaking. None if `tested` isn't a valid version.
+    """
+    try:
+        version = Version(tested)
+    except InvalidVersion:
+        return None
+    upper = f"{version.major + 1}" if version.major > 0 else f"0.{version.minor + 1}"
+    return f">={version},<{upper}"
+
+
+def classify(
+    actual: str, tested: str
+) -> Literal["tested", "compatible", "untested"] | None:
+    """How `actual` relates to `tested`; None if either isn't a valid version."""
+    spec = compatible_range(tested)
+    try:
+        actual_version = Version(actual)
+    except InvalidVersion:
+        return None
+    if spec is None:
+        return None
+    if actual_version == Version(tested):
+        return "tested"
+    if SpecifierSet(spec).contains(actual_version, prereleases=True):
+        return "compatible"
+    return "untested"
+
+
+def load_manifest(working_dir: Path) -> Manifest | None:
+    """Find and parse the manifest of an initialized module in working_dir.
+
+    Considers every module in `.terraform/modules/modules.json` that ships
+    a manifest, preferring the shallowest (so a local wrapper module around
+    a netascode module still works). Returns None if there is none or it
+    can't be read -- the manifest is only ever a hint.
+    """
+    try:
+        raw = json.loads((working_dir / MODULES_JSON).read_text(encoding="utf-8"))
+        modules = raw["Modules"]
+    except (OSError, ValueError, KeyError, TypeError):
+        return None
+    if not isinstance(modules, list):
+        return None
+
+    candidates = [
+        m for m in modules if isinstance(m, dict) and m.get("Key") and m.get("Dir")
+    ]
+    candidates.sort(key=lambda m: str(m["Key"]).count("."))
+    for module in candidates:
+        path = working_dir / str(module["Dir"]) / MANIFEST_FILE
+        if path.is_file():
+            manifest = _parse_manifest(path, _module_label(module))
+            if manifest is not None:
+                return manifest
+    return None
+
+
+def _module_label(module: dict[str, object]) -> str:
+    source = str(module.get("Source") or "")
+    version = str(module.get("Version") or "")
+    for host in _REGISTRY_HOSTS:
+        if source.startswith(host):
+            return f"{source[len(host) :]} {version}".strip()
+    return f"module.{module['Key']}"
+
+
+def _parse_manifest(path: Path, label: str) -> Manifest | None:
+    yaml = ruamel.yaml.YAML(typ="safe")
+    try:
+        with path.open("r", encoding="utf-8") as fh:
+            data = _ManifestFile.model_validate(yaml.load(fh))
+    except (OSError, ruamel.yaml.YAMLError, pydantic.ValidationError) as exc:
+        logger.debug("Ignoring unreadable manifest %s: %s", path, exc)
+        return None
+    return Manifest(module=label, tools=dict(data.tools))

nac/output.py

@@ -0,0 +1,113 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""Shared terminal output formatting, matching nac-validate's own summary
+box style (80-char `-` rule, bold header, green checkmarks) so a `nac`
+invocation reads as one coherent report.
+
+Color is on by default (matching a plain `terraform apply`); callers pass
+an explicit `no_color` bool -- resolved once per invocation from the
+`--no-color` flag / `NO_COLOR` env var in `nac.cli.main.get_no_color` --
+rather than this module re-reading the environment itself."""
+
+import os
+import re
+import shlex
+import subprocess
+import sys
+from collections.abc import Mapping, Sequence
+
+import typer
+
+SEP_WIDTH = 80
+BOLD = "\033[1m"
+GREEN = "\033[92m"
+YELLOW = "\033[93m"
+DIM = "\033[2m"
+_RESET = "\033[0m"
+
+_ANSI_ESCAPE_RE = re.compile(r"\x1B\[[0-?]*[ -/]*[@-~]")
+
+
+def color(code: str, text: str, *, no_color: bool = False) -> str:
+    """Wrap text in an ANSI color code, unless no_color is set.
+
+    Click strips these automatically when stdout isn't a TTY, so this
+    only needs to handle the explicit opt-out.
+    """
+    if no_color:
+        return text
+    return f"{code}{text}{_RESET}"
+
+
+def echo_summary(title: str, lines: list[str], *, no_color: bool = False) -> None:
+    """Print a status box: bold title between `-` rules, one
+    green-checkmarked line per entry in `lines`."""
+    sep = "─" * SEP_WIDTH
+    typer.echo(f"\n{color(BOLD, sep, no_color=no_color)}")
+    typer.echo(color(BOLD, title, no_color=no_color))
+    typer.echo(sep)
+    for line in lines:
+        typer.echo(f"  {color(GREEN, '✓', no_color=no_color)} {line}")
+    typer.echo(f"{sep}\n")
+
+
+def format_command(argv: Sequence[str]) -> str:
+    """Render argv as a single copy-pasteable command line, quoted for the
+    current platform's shell (POSIX sh, or cmd.exe-style on Windows)."""
+    if sys.platform == "win32":
+        return subprocess.list2cmdline(argv)
+    return shlex.join(argv)
+
+
+def echo_command(argv: Sequence[str], *, no_color: bool = False) -> None:
+    """Print the exact command nac is about to run, as a dim `$ ...` line.
+
+    Goes to stderr so it never mixes into a wrapped tool's stdout when that
+    is piped or redirected. stdout is flushed first so the line still lands
+    in order relative to output nac has already written there.
+    """
+    sys.stdout.flush()
+    typer.echo(color(DIM, f"$ {format_command(argv)}", no_color=no_color), err=True)
+
+
+def utf8_env(base_env: Mapping[str, str]) -> dict[str, str]:
+    """Copy of base_env that makes Python child processes (nac-validate,
+    nac-test) emit UTF-8 when piped; on Windows they would otherwise use the
+    ANSI code page and crash on characters like box-drawing glyphs."""
+    env = dict(base_env)
+    env.setdefault("PYTHONUTF8", "1")
+    env.setdefault("PYTHONIOENCODING", "utf-8")
+    return env
+
+
+def ensure_utf8_streams() -> None:
+    """Make our own stdout/stderr able to print the glyphs nac emits (─, ✓)
+    even when redirected on Windows, where the default is the ANSI code page."""
+    for stream in (sys.stdout, sys.stderr):
+        reconfigure = getattr(stream, "reconfigure", None)
+        if reconfigure is not None:
+            reconfigure(encoding="utf-8", errors="replace")
+
+
+def strip_ansi(text: str) -> str:
+    """Strip ANSI escape sequences, e.g. before writing subprocess output
+    to a log file artifact (plan.txt) so it stays clean, human-diffable
+    text even when the same output was streamed to the terminal in color."""
+    return _ANSI_ESCAPE_RE.sub("", text)
+
+
+def apply_no_color_env(
+    no_color: bool, base_env: Mapping[str, str] | None = None
+) -> dict[str, str]:
+    """Build a subprocess env dict, adding NO_COLOR when no_color is set.
+
+    Terraform/OpenTofu only ever look at the literal `-no-color` CLI flag
+    (never the NO_COLOR env var), so this is for forwarding the setting to
+    subprocesses that *do* honor the NO_COLOR convention -- nac-validate
+    and nac-test.
+    """
+    env = dict(base_env if base_env is not None else os.environ)
+    if no_color:
+        env["NO_COLOR"] = "1"
+    return env

nac/runner.py

@@ -0,0 +1,135 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+import codecs
+import logging
+import os
+import subprocess
+import sys
+from contextlib import nullcontext
+from pathlib import Path
+from typing import cast
+
+from nac.output import echo_command, strip_ansi, utf8_env
+
+logger = logging.getLogger(__name__)
+
+_READ_SIZE = 4096
+
+
+def _write_stdout(data: bytes) -> None:
+    """Pass the child's raw bytes through untouched.
+
+    Going via the binary buffer avoids the text layer's newline translation
+    (\r\n -> \r\r\n on Windows) and its locale encoding (cp1252 on Windows
+    cannot encode much of what terraform/tofu print).
+    """
+    sys.stdout.flush()
+    buffer = getattr(sys.stdout, "buffer", None)
+    if buffer is None:  # replaced stdout without a binary layer
+        sys.stdout.write(data.decode("utf-8", errors="replace"))
+        sys.stdout.flush()
+        return
+    buffer.write(data)
+    buffer.flush()
+
+
+def _log_env_overrides(env: dict[str, str]) -> None:
+    overrides = {k: v for k, v in env.items() if os.environ.get(k) != v}
+    if overrides:
+        logger.debug(
+            "Environment overrides: %s",
+            " ".join(f"{k}={v}" for k, v in sorted(overrides.items())),
+        )
+
+
+def run_streaming(
+    cmd: list[str],
+    cwd: Path,
+    env: dict[str, str],
+    log_path: Path | None = None,
+    quiet: bool = False,
+    append: bool = False,
+    no_color: bool = False,
+) -> int:
+    """Run cmd as a subprocess, streaming merged stdout+stderr in real time.
+
+    stdin is inherited from the parent so interactive prompts (e.g.
+    terraform's apply confirmation) still work. cmd[0] must already be a
+    resolved path — this function does no binary resolution itself.
+
+    Output is read in raw chunks via os.read (not line-by-line) -- a
+    line-buffered `for line in proc.stdout` blocks until a newline shows
+    up, so a prompt like terraform's trailing "Enter a value: " (no
+    newline, then it waits on stdin) would otherwise sit unflushed and
+    invisible until the next newline arrives.
+
+    When quiet is True, output is captured instead of being streamed live;
+    it is only written to stdout if the command exits non-zero, so a caller
+    can pair this with its own short status line on success while still
+    surfacing the real output on failure.
+
+    Output written to log_path always has ANSI escape codes stripped --
+    regardless of whether the terminal-facing copy was colored -- so log
+    file artifacts (e.g. plan.txt) stay clean, human-diffable text.
+
+    By default log_path is opened in truncate mode, so a stale artifact
+    from a previous, separate invocation never leaks into new output. Pass
+    append=True when this call is a continuation of an earlier
+    run_streaming call within the same invocation that already truncated
+    the same log_path (e.g. nac validate's render step followed by the
+    nac-validate call itself), so both calls' output lands in one file in
+    order. append has no effect when log_path is None.
+
+    The exact command line is always echoed first (to stderr, never to
+    log_path, so artifacts like plan.json stay pure tool output -- see
+    `echo_command`); the environment variables nac set or changed for the
+    child are logged at DEBUG, since they can affect behavior too (e.g. the
+    tenv version pin) but would be noise on every run.
+    """
+    child_env = utf8_env(env)
+    echo_command(cmd, no_color=no_color)
+    _log_env_overrides(child_env)
+
+    if log_path is not None:
+        log_path.parent.mkdir(parents=True, exist_ok=True)
+
+    mode = "a" if append else "w"
+    # newline="" keeps the child's own line endings: on Windows it already
+    # emits \r\n, which default newline translation would turn into \r\r\n.
+    log_cm = (
+        log_path.open(mode, encoding="utf-8", newline="")
+        if log_path is not None
+        else nullcontext()
+    )
+    with log_cm as log_file:
+        proc = subprocess.Popen(
+            cmd,
+            cwd=cwd,
+            env=child_env,
+            stdout=subprocess.PIPE,
+            stderr=subprocess.STDOUT,
+            stdin=None,
+            bufsize=0,
+        )
+        if proc.stdout is None:
+            raise RuntimeError("subprocess stdout was not piped")
+        decoder = codecs.getincrementaldecoder("utf-8")(errors="replace")
+        buffered: list[bytes] = []
+        fd = proc.stdout.fileno()
+        while True:
+            raw = os.read(fd, _READ_SIZE)
+            if not raw:
+                break
+            if quiet:
+                buffered.append(raw)
+            else:
+                _write_stdout(raw)
+            if log_file is not None:
+                log_file.write(strip_ansi(decoder.decode(raw)))
+        proc.wait()
+    if proc.returncode is None:
+        raise RuntimeError("subprocess did not report an exit code")
+    if quiet and proc.returncode != 0:
+        _write_stdout(b"".join(buffered))
+    return cast(int, proc.returncode)