nac-cli 0.1.0__py3-none-any.whl

nac/cli/passthrough.py

@@ -0,0 +1,117 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""Shared plumbing for forwarding extra CLI args to a wrapped tool and for
+delegating `--help`/`-h` to that tool's own help output.
+"""
+
+import logging
+import re
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import NoReturn
+
+import typer
+
+from nac.output import BOLD, color, format_command, utf8_env
+
+logger = logging.getLogger(__name__)
+
+# `options_metavar` replaces the bare `[OPTIONS]` in nac's own usage line so it
+# is clear that unrecognised arguments are forwarded to the wrapped tool.
+PASSTHROUGH_OPTIONS_METAVAR = "[OPTIONS] [PASSTHROUGH-ARGS]..."
+
+_ANSI = r"(?:\x1b\[[0-9;]*m|\s)*"
+# First Rich panel border (`╭─ Arguments ─╮` / `╭─ Options ─╮`), possibly
+# preceded by ANSI styling.
+_FIRST_PANEL_RE = re.compile(r"^(?:\x1b\[[0-9;]*m)*╭", re.MULTILINE)
+# First options section heading in terraform/tofu help (`Options:`,
+# `Plan Customization Options:`, ...).
+_FIRST_OPTIONS_HEADING_RE = re.compile(r"^[A-Za-z ]*Options:$", re.MULTILINE)
+_USAGE_PROG_RE = re.compile(
+    rf"(Usage:{_ANSI})(?:nac-validate|nac-test|terraform|tofu)(?: \[global options\](?: [a-z]+)?)?"
+)
+
+PASSTHROUGH_CONTEXT_SETTINGS = {
+    "allow_extra_args": True,
+    "ignore_unknown_options": True,
+    "help_option_names": [],
+}
+
+
+def wants_help(ctx: typer.Context) -> bool:
+    """Whether the leftover passthrough args include a help flag.
+
+    Safe to check anywhere in `ctx.args` (not just the first token) since
+    `ignore_unknown_options` guarantees nothing else has been pre-interpreted,
+    and none of the wrapped tools (nac-validate, nac-test, terraform/tofu)
+    have an unrelated `-h` short flag that could collide.
+    """
+    return "--help" in ctx.args or "-h" in ctx.args
+
+
+def _tool_help_body(text: str, usage_as: str) -> str:
+    """Reduce the wrapped tool's help to what nac's own help doesn't cover.
+
+    Rich-based tools (nac-validate, nac-test) print a usage line and a
+    description before their Arguments/Options panels, and terraform/tofu
+    print theirs before the first `... Options:` heading; both are dropped,
+    as nac already printed its own usage and description. If neither marker
+    is found, the full text is kept with its usage line rewritten to the
+    `nac <command>` form the user actually types.
+    """
+    start = _FIRST_PANEL_RE.search(text) or _FIRST_OPTIONS_HEADING_RE.search(text)
+    if start:
+        return text[start.start() :]
+    return _USAGE_PROG_RE.sub(lambda m: m.group(1) + usage_as, text, count=1)
+
+
+def show_help_and_exit(
+    ctx: typer.Context,
+    tool_argv: list[str],
+    *,
+    cwd: Path,
+    env: dict[str, str],
+    no_color: bool,
+    tool_label: str,
+    usage_as: str,
+) -> NoReturn:
+    """Print nac's own help for this subcommand, then the wrapped tool's
+    own `--help` output below a labeled separator, and exit with that
+    tool's code.
+
+    The tool's output is captured (its stdout is not a TTY) so that:
+    - color and terminal width are forced on for it when nac's own stdout is
+      a TTY (and color is not disabled), matching nac's own help rendering;
+    - its own usage/description header is dropped (see `_tool_help_body`),
+      since nac already printed its own, leaving just the options.
+    """
+    typer.echo(ctx.get_help())
+
+    child_env = utf8_env(env)
+    if sys.stdout.isatty():
+        child_env["COLUMNS"] = str(shutil.get_terminal_size().columns)
+        if not no_color:
+            child_env["FORCE_COLOR"] = "1"
+
+    logger.debug("Running %s", format_command(tool_argv))
+    proc = subprocess.run(
+        tool_argv,
+        cwd=cwd,
+        env=child_env,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.STDOUT,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+    )
+    text = _tool_help_body(proc.stdout, usage_as)
+
+    rule = f"── Passed through to {tool_label} "
+    rule += "─" * max(0, shutil.get_terminal_size().columns - len(rule))
+    typer.echo(color(BOLD, rule, no_color=no_color))
+    typer.echo()
+    typer.echo(text, nl=False)
+    raise typer.Exit(code=proc.returncode)

nac/cli/plan.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""`nac plan` -- saves a plan file and, optionally, plan.txt/plan.json."""
+
+import typer
+
+from nac import runner, terraform
+
+from .main import app, get_config, get_no_color, resolve_engine_or_exit
+from .options import Artifacts
+from .passthrough import (
+    PASSTHROUGH_CONTEXT_SETTINGS,
+    PASSTHROUGH_OPTIONS_METAVAR,
+    show_help_and_exit,
+    wants_help,
+)
+
+
+@app.command(
+    context_settings=PASSTHROUGH_CONTEXT_SETTINGS,
+    options_metavar=PASSTHROUGH_OPTIONS_METAVAR,
+)
+def plan(ctx: typer.Context, artifacts: Artifacts = False) -> None:
+    """Produce a saved plan file, optionally with plan.txt/plan.json artifacts.
+
+    Extra arguments are passed through to `terraform`/`tofu` (only to the
+    `plan` invocation itself, not to the `show` calls used for artifacts).
+    """
+    cfg = get_config(ctx)
+    engine, binary = resolve_engine_or_exit(cfg)
+    env = terraform.build_engine_env(engine, cfg.tools.terraform.version)
+    no_color = get_no_color(ctx)
+
+    if wants_help(ctx):
+        show_help_and_exit(
+            ctx,
+            [binary, "plan", "--help"],
+            cwd=cfg.working_dir,
+            env=env,
+            no_color=get_no_color(ctx),
+            tool_label=f"{engine} plan",
+            usage_as="nac plan",
+        )
+
+    code = runner.run_streaming(
+        terraform.build_plan_argv(binary, no_color=no_color) + ctx.args,
+        cwd=cfg.working_dir,
+        env=env,
+        no_color=no_color,
+    )
+    if code != 0:
+        raise typer.Exit(code=code)
+
+    if artifacts:
+        code = runner.run_streaming(
+            terraform.build_show_text_argv(binary, no_color=no_color),
+            cwd=cfg.working_dir,
+            env=env,
+            log_path=cfg.working_dir / "plan.txt",
+            no_color=no_color,
+        )
+        if code != 0:
+            raise typer.Exit(code=code)
+
+        code = runner.run_streaming(
+            terraform.build_show_json_argv(binary),
+            cwd=cfg.working_dir,
+            env=env,
+            log_path=cfg.working_dir / "plan.json",
+            no_color=no_color,
+        )
+        if code != 0:
+            raise typer.Exit(code=code)
+
+    raise typer.Exit(code=0)

nac/cli/setup.py

@@ -0,0 +1,179 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""`nac setup` -- verify prerequisites and report resolved tool versions."""
+
+import logging
+import os
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Literal
+
+import typer
+
+from nac import bootstrap, runner, terraform, tools
+from nac.exceptions import BootstrapError, EngineNotFoundError, NoEngineAvailableError
+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 .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"
+)
+MANUAL_INSTALL_MESSAGE = (
+    "Neither Terraform nor OpenTofu is installed. Install Terraform or "
+    "OpenTofu: https://developer.hashicorp.com/terraform/install or "
+    "https://opentofu.org/docs/intro/install/ -- or set "
+    "`tools.terraform.version` to have `nac` manage it via `tenv`."
+)
+
+
+def _is_interactive() -> bool:
+    return bool(sys.stdin.isatty())
+
+
+def _confirm_bootstrap(yes: bool) -> bool:
+    if yes:
+        return True
+    if not _is_interactive():
+        return False
+    return typer.confirm(
+        "Neither Terraform nor OpenTofu is installed. Install OpenTofu now?",
+        default=True,
+    )
+
+
+def _binary_version(binary: str, env: dict[str, str]) -> str:
+    argv = [binary, "version"]
+    logger.debug("Running %s", format_command(argv))
+    result = subprocess.run(
+        argv,
+        capture_output=True,
+        text=True,
+        encoding="utf-8",
+        errors="replace",
+        env=env,
+        check=False,
+    )
+    for line in (result.stdout or result.stderr or "").splitlines():
+        if line.strip():
+            return line.strip()
+    return "unknown"
+
+
+def _is_cached_binary(binary: str) -> bool:
+    """True if `binary` lives under nac's bootstrap cache dir rather than PATH."""
+    try:
+        Path(binary).resolve().relative_to(bootstrap.cache_dir().resolve())
+    except ValueError:
+        return False
+    return True
+
+
+@app.command()
+def setup(ctx: typer.Context, yes: Yes = False, prewarm: Prewarm = False) -> None:
+    """Verify prerequisites and report resolved tool versions."""
+    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"]
+
+    if cfg.tools.terraform.version is not None and shutil.which("tenv") is None:
+        fail(TENV_NOT_FOUND)
+
+    try:
+        engine, binary = terraform.resolve_engine_binary(cfg.tools.terraform)
+        if cfg.tools.terraform.engine is not None:
+            detection = "explicit"
+        elif _is_cached_binary(binary):
+            detection = "bootstrap-installed"
+        else:
+            detection = "auto-detected"
+    except EngineNotFoundError as exc:
+        fail(str(exc))
+    except NoEngineAvailableError:
+        if not _confirm_bootstrap(yes):
+            fail(MANUAL_INSTALL_MESSAGE)
+        try:
+            binary_path = bootstrap.install(confirmed=True)
+        except BootstrapError as exc:
+            fail(str(exc))
+        engine, binary, detection = "tofu", str(binary_path), "bootstrap-installed"
+
+    env = terraform.build_engine_env(engine, cfg.tools.terraform.version)
+    lines.append(f"{engine}: {_binary_version(binary, env)} ({detection})")
+
+    manifest = get_manifest(ctx, cfg)
+    if manifest is not None:
+        lines.append(f"tested versions: {manifest.module} ({MANIFEST_FILE})")
+
+    missing_env = [name for name in cfg.env.required if name not in os.environ]
+    if missing_env:
+        fail("Missing required environment variable(s): " + ", ".join(missing_env))
+    if cfg.env.required:
+        lines.append("env.required: all present (" + ", ".join(cfg.env.required) + ")")
+
+    def _tool_summary_line(
+        name: Literal["nac-validate", "nac-test"], explicit: str | None
+    ) -> tuple[str, ToolSource, str | None]:
+        constraint = tools.tool_constraint(name, explicit, manifest)
+        source = tools.resolve_tool_source(name, constraint)
+        if source.mode == "local":
+            return f"{name}: v{source.version or 'unknown'} (local)", source, constraint
+        pin = constraint or "latest/unpinned"
+        if explicit is None and constraint is not None and manifest is not None:
+            pin += f", latest compatible with {manifest.module}"
+        suffix = (
+            f" -- local v{source.version} does not satisfy"
+            if source.version is not None
+            else ""
+        )
+        return f"{name}: {pin} (uvx{suffix})", source, constraint
+
+    validate_line, validate_source, validate_constraint = _tool_summary_line(
+        "nac-validate", cfg.tools.nac_validate
+    )
+    test_line, test_source, test_constraint = _tool_summary_line(
+        "nac-test", cfg.tools.nac_test
+    )
+    lines.append(validate_line)
+    lines.append(test_line)
+    warnings = [
+        *tool_warnings(manifest, "nac-validate", cfg.tools.nac_validate),
+        *tool_warnings(manifest, "nac-test", cfg.tools.nac_test),
+    ]
+
+    if prewarm:
+        base_env = apply_no_color_env(no_color)
+        if validate_source.mode != "local":
+            argv = tools.build_prewarm_argv("nac-validate", validate_constraint)
+            code = runner.run_streaming(
+                argv, cwd=cfg.working_dir, env=base_env, no_color=no_color
+            )
+            if code != 0:
+                raise typer.Exit(code=code)
+        if test_source.mode != "local":
+            argv = tools.build_prewarm_argv("nac-test", test_constraint)
+            code = runner.run_streaming(
+                argv, cwd=cfg.working_dir, env=base_env, no_color=no_color
+            )
+            if code != 0:
+                raise typer.Exit(code=code)
+
+    echo_summary("Setup Summary", lines, no_color=no_color)
+    emit_warnings(warnings, no_color=no_color)

nac/cli/test.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""`nac test` -- streams nac-test built from config."""
+
+import typer
+
+from nac import runner, tools
+from nac.output import apply_no_color_env
+
+from .main import app, get_config, get_no_color
+from .options import Artifacts
+from .passthrough import (
+    PASSTHROUGH_CONTEXT_SETTINGS,
+    PASSTHROUGH_OPTIONS_METAVAR,
+    show_help_and_exit,
+    wants_help,
+)
+from .versions import emit_warnings, get_manifest, note_on_failure, tool_warnings
+
+
+@app.command(
+    name="test",
+    context_settings=PASSTHROUGH_CONTEXT_SETTINGS,
+    options_metavar=PASSTHROUGH_OPTIONS_METAVAR,
+)
+def test_(ctx: typer.Context, artifacts: Artifacts = False) -> None:
+    """Run nac-test against the configured data/templates/filters/output.
+
+    Extra arguments are passed through to `nac-test`.
+    """
+    cfg = get_config(ctx)
+    no_color = get_no_color(ctx)
+    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,
+            tools.build_help_argv(
+                "nac-test",
+                tools.tool_constraint("nac-test", cfg.tools.nac_test, manifest),
+            ),
+            cwd=cfg.working_dir,
+            env=apply_no_color_env(no_color),
+            no_color=no_color,
+            tool_label="nac-test",
+            usage_as="nac test",
+        )
+
+    warnings = tool_warnings(manifest, "nac-test", cfg.tools.nac_test)
+    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,
+        cwd=cfg.working_dir,
+        env=apply_no_color_env(no_color),
+        log_path=log_path,
+        append=log_written,
+        no_color=no_color,
+    )
+    note_on_failure("test", code, warnings, no_color=no_color, log_path=log_path)
+    raise typer.Exit(code=code)

nac/cli/validate.py

@@ -0,0 +1,90 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""`nac validate` -- optional targeted render, then nac-validate."""
+
+import logging
+
+import typer
+
+from nac import runner, terraform, tools
+from nac.output import GREEN, apply_no_color_env, color, echo_summary
+
+from .main import app, get_config, get_no_color, resolve_engine_or_exit
+from .options import Artifacts
+from .passthrough import (
+    PASSTHROUGH_CONTEXT_SETTINGS,
+    PASSTHROUGH_OPTIONS_METAVAR,
+    show_help_and_exit,
+    wants_help,
+)
+from .versions import emit_warnings, get_manifest, note_on_failure, tool_warnings
+
+
+@app.command(
+    context_settings=PASSTHROUGH_CONTEXT_SETTINGS,
+    options_metavar=PASSTHROUGH_OPTIONS_METAVAR,
+)
+def validate(ctx: typer.Context, artifacts: Artifacts = False) -> None:
+    """Render (if configured) then validate the resolved data paths.
+
+    Extra arguments are passed through to `nac-validate`.
+    """
+    cfg = get_config(ctx)
+    no_color = get_no_color(ctx)
+    log_path = cfg.working_dir / "validate.txt" if artifacts else None
+    manifest = get_manifest(ctx, cfg)
+    constraint = tools.tool_constraint("nac-validate", cfg.tools.nac_validate, manifest)
+
+    if wants_help(ctx):
+        show_help_and_exit(
+            ctx,
+            tools.build_help_argv("nac-validate", constraint),
+            cwd=cfg.working_dir,
+            env=apply_no_color_env(no_color),
+            no_color=no_color,
+            tool_label="nac-validate",
+            usage_as="nac validate",
+        )
+
+    warnings = tool_warnings(manifest, "nac-validate", cfg.tools.nac_validate)
+    log_written = emit_warnings(warnings, no_color=no_color, log_path=log_path)
+
+    if cfg.render is not None and cfg.render.target is not None:
+        engine, binary = resolve_engine_or_exit(cfg)
+        env = terraform.build_engine_env(engine, cfg.tools.terraform.version)
+        quiet = not logging.getLogger().isEnabledFor(logging.INFO)
+        code = runner.run_streaming(
+            terraform.build_render_apply_argv(
+                binary, cfg.render.target, no_color=no_color
+            ),
+            cwd=cfg.working_dir,
+            env=env,
+            quiet=quiet,
+            log_path=log_path,
+            append=log_written,
+            no_color=no_color,
+        )
+        log_written = True
+        if code != 0:
+            raise typer.Exit(code=code)
+        if quiet:
+            echo_summary(
+                "Render Summary",
+                [
+                    f"Render: {color(GREEN, 'OK', no_color=no_color)} "
+                    f"({cfg.render.target})"
+                ],
+                no_color=no_color,
+            )
+
+    code = runner.run_streaming(
+        tools.build_validate_argv(cfg, manifest) + ctx.args,
+        cwd=cfg.working_dir,
+        env=apply_no_color_env(no_color),
+        log_path=log_path,
+        append=log_written,
+        no_color=no_color,
+    )
+    note_on_failure("validate", code, warnings, no_color=no_color, log_path=log_path)
+    raise typer.Exit(code=code)

nac/cli/versions.py

@@ -0,0 +1,92 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""Advisory checks of nac-validate/nac-test against the module's tested versions.
+
+`validate`/`test` check the tool they run (and `setup` both) and print a
+warning for versions outside the tested, semver-compatible range -- before
+the tool runs, plus a short note afterwards if it failed. Never changes
+exit codes.
+"""
+
+from pathlib import Path
+from typing import Literal, cast
+
+import typer
+
+from nac import tools
+from nac.config import NacConfig
+from nac.manifest import Manifest, load_manifest
+from nac.output import YELLOW, color
+
+_MANIFEST_KEY = "manifest"
+
+
+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])
+
+
+def tool_warnings(
+    manifest: Manifest | None,
+    tool: Literal["nac-validate", "nac-test"],
+    explicit: str | None,
+) -> list[str]:
+    """Warnings for nac-validate/nac-test.
+
+    Without an explicit `tools.*` constraint the tool is resolved to the
+    latest compatible release (see `tools.tool_constraint`), so there is
+    nothing to warn about. With one, the version is known only for a local
+    install or an exact pin -- a range resolved by uvx isn't checked.
+    """
+    if manifest is None or explicit is None or tool not in manifest.tools:
+        return []
+    source = tools.resolve_tool_source(tool, explicit)
+    version = source.version if source.mode == "local" else tools.exact_pin(explicit)
+    warning = manifest.check_tool(tool, version)
+    return [warning] if warning is not None else []
+
+
+def emit_warnings(
+    warnings: list[str],
+    *,
+    no_color: bool,
+    log_path: Path | None = None,
+    append: bool = False,
+) -> bool:
+    """Print warnings to stderr and, if given, write them to log_path.
+
+    Returns whether log_path was written, i.e. whether the next
+    `run_streaming` call for the same artifact must append to it.
+    """
+    for warning in warnings:
+        typer.echo(color(YELLOW, f"Warning: {warning}", no_color=no_color), err=True)
+    if not warnings or log_path is None:
+        return False
+    log_path.parent.mkdir(parents=True, exist_ok=True)
+    with log_path.open("a" if append else "w", encoding="utf-8") as fh:
+        fh.writelines(f"Warning: {warning}\n" for warning in warnings)
+    return True
+
+
+def note_on_failure(
+    command: str,
+    code: int,
+    warnings: list[str],
+    *,
+    no_color: bool,
+    log_path: Path | None = None,
+) -> None:
+    """After a failed run, point back at the version warnings printed earlier."""
+    if code == 0 or not warnings:
+        return
+    note = (
+        f"Note: `nac {command}` failed while using versions outside the tested "
+        "range (see warnings above); this may be related."
+    )
+    typer.echo(color(YELLOW, note, no_color=no_color), err=True)
+    if log_path is not None and log_path.is_file():
+        with log_path.open("a", encoding="utf-8") as fh:
+            fh.write(f"{note}\n")