nac-cli 0.1.0__py3-none-any.whl

nac/__init__.py

@@ -0,0 +1,6 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+from importlib.metadata import version
+
+__version__ = version("nac-cli")

nac/__main__.py

@@ -0,0 +1,7 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+import nac.cli.main
+
+if __name__ == "__main__":
+    nac.cli.main.run()

nac/bootstrap.py

@@ -0,0 +1,181 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+import hashlib
+import io
+import platform
+import shutil
+import stat
+import sys
+import zipfile
+from pathlib import Path
+from typing import Any, cast
+
+import httpx
+import platformdirs
+
+from nac.exceptions import (
+    BootstrapDeclinedError,
+    BootstrapError,
+    ChecksumMismatchError,
+    UnsupportedPlatformError,
+)
+
+_OS_MAP = {
+    "darwin": "darwin",
+    "linux": "linux",
+    "win32": "windows",
+    "cygwin": "windows",
+}
+_ARCH_MAP = {
+    "x86_64": "amd64",
+    "amd64": "amd64",
+    "aarch64": "arm64",
+    "arm64": "arm64",
+    "i386": "386",
+    "i686": "386",
+    "x86": "386",
+    "armv7l": "arm",
+    "armv6l": "arm",
+}
+
+_GITHUB_API = "https://api.github.com/repos/opentofu/opentofu/releases"
+
+
+def cache_dir() -> Path:
+    return Path(platformdirs.user_cache_dir("nac"))
+
+
+def _binary_name() -> str:
+    return "tofu.exe" if sys.platform == "win32" else "tofu"
+
+
+def _cached_binary_path(version: str) -> Path:
+    return cache_dir() / "bin" / "tofu" / version / _binary_name()
+
+
+def find_cached_binary() -> Path | None:
+    """Return the first cached tofu binary found, or None. No network access."""
+    root = cache_dir() / "bin" / "tofu"
+    if not root.is_dir():
+        return None
+    name = _binary_name()
+    for version_dir in root.iterdir():
+        candidate = version_dir / name
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def detect_platform() -> tuple[str, str]:
+    """Return (os_name, arch_name) in OpenTofu's release-asset vocabulary."""
+    os_name = _OS_MAP.get(sys.platform)
+    arch_name = _ARCH_MAP.get(platform.machine().lower())
+    if os_name is None or arch_name is None:
+        raise UnsupportedPlatformError(
+            f"Unsupported platform for OpenTofu bootstrap: {sys.platform}/{platform.machine()}"
+        )
+    return os_name, arch_name
+
+
+def install(
+    version: str | None = None,
+    *,
+    confirmed: bool,
+    client: httpx.Client | None = None,
+) -> Path:
+    """Ensure a cached OpenTofu binary exists locally and return its path.
+
+    Never prompts — only gates on `confirmed`, which the caller (`nac
+    setup`) obtains via its own TTY-detection/prompting. If a binary is
+    already cached, it is returned immediately with no network call,
+    regardless of `confirmed`.
+    """
+    cached = find_cached_binary()
+    if cached is not None:
+        return cached
+
+    if not confirmed:
+        raise BootstrapDeclinedError(
+            "OpenTofu is not installed and installation was not confirmed."
+        )
+
+    owns_client = client is None
+    client = client or httpx.Client(timeout=30.0, follow_redirects=True)
+    try:
+        os_name, arch_name = detect_platform()
+        release = _get_release(client, version)
+        resolved_version = _tag_to_version(release["tag_name"])
+        dest = _cached_binary_path(resolved_version)
+
+        asset_name = f"tofu_{resolved_version}_{os_name}_{arch_name}.zip"
+        sums_name = f"tofu_{resolved_version}_SHA256SUMS"
+        archive_bytes = _download(client, _asset_url(release, asset_name))
+        sums_text = _download(client, _asset_url(release, sums_name)).decode()
+
+        expected = _parse_sha256sums(sums_text, asset_name)
+        actual = hashlib.sha256(archive_bytes).hexdigest()
+        if actual != expected:
+            raise ChecksumMismatchError(
+                f"Checksum mismatch for {asset_name}: expected {expected}, got {actual}"
+            )
+
+        _extract_binary(archive_bytes, dest, os_name)
+        return dest
+    finally:
+        if owns_client:
+            client.close()
+
+
+def _get_release(client: httpx.Client, version: str | None) -> dict[str, Any]:
+    url = (
+        f"{_GITHUB_API}/latest" if version is None else f"{_GITHUB_API}/tags/v{version}"
+    )
+    resp = client.get(url)
+    if resp.status_code != 200:
+        raise BootstrapError(
+            f"Failed to query OpenTofu releases ({resp.status_code}): {url}"
+        )
+    result: dict[str, Any] = resp.json()
+    return result
+
+
+def _tag_to_version(tag: str) -> str:
+    return tag[1:] if tag.startswith("v") else tag
+
+
+def _asset_url(release: dict[str, Any], name: str) -> str:
+    for asset in release.get("assets", []):
+        if asset.get("name") == name:
+            return cast(str, asset["browser_download_url"])
+    raise BootstrapError(f"Release asset not found: {name}")
+
+
+def _download(client: httpx.Client, url: str) -> bytes:
+    resp = client.get(url)
+    if resp.status_code != 200:
+        raise BootstrapError(f"Download failed ({resp.status_code}): {url}")
+    return resp.content
+
+
+def _parse_sha256sums(text: str, filename: str) -> str:
+    for line in text.splitlines():
+        parts = line.split()
+        if len(parts) >= 2 and parts[-1].lstrip("*") == filename:
+            return parts[0]
+    raise BootstrapError(f"No checksum entry for {filename} in SHA256SUMS")
+
+
+def _extract_binary(archive_bytes: bytes, dest: Path, os_name: str) -> None:
+    member = "tofu.exe" if os_name == "windows" else "tofu"
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    tmp = dest.with_name(dest.name + ".part")
+    with (
+        zipfile.ZipFile(io.BytesIO(archive_bytes)) as zf,
+        zf.open(member) as src,
+        tmp.open("wb") as out,
+    ):
+        shutil.copyfileobj(src, out)
+    if os_name != "windows":
+        tmp.chmod(tmp.stat().st_mode | stat.S_IEXEC | stat.S_IXGRP | stat.S_IXOTH)
+    tmp.replace(dest)

nac/cli/__init__.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+from typer.models import CommandInfo
+
+from . import apply, destroy, init, plan, setup, test, validate  # noqa: F401
+from .main import app
+
+# Registration order above is alphabetical (required by import sorting), but
+# the help output should mirror the setup -> init -> validate -> plan ->
+# apply -> test workflow, so reorder registered_commands explicitly.
+_WORKFLOW_ORDER = ("setup", "init", "validate", "plan", "apply", "test", "destroy")
+
+
+def _workflow_index(command: CommandInfo) -> int:
+    assert command.callback is not None
+    module = command.callback.__module__.rsplit(".", 1)[-1]
+    return _WORKFLOW_ORDER.index(module)
+
+
+app.registered_commands.sort(key=_workflow_index)

nac/cli/apply.py

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""`nac apply` -- applies a saved plan if present, else runs interactively."""
+
+import typer
+
+from nac import runner, terraform
+
+from .main import app, get_config, get_no_color, resolve_engine_or_exit
+from .options import Artifacts, AutoApprove
+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 apply(
+    ctx: typer.Context,
+    auto_approve: AutoApprove = False,
+    artifacts: Artifacts = False,
+) -> None:
+    """Apply a saved plan file if present, otherwise apply interactively.
+
+    Extra arguments are passed through to `terraform`/`tofu`.
+    """
+    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, "apply", "--help"],
+            cwd=cfg.working_dir,
+            env=env,
+            no_color=get_no_color(ctx),
+            tool_label=f"{engine} apply",
+            usage_as="nac apply",
+        )
+
+    plan_file = cfg.working_dir / terraform.DEFAULT_PLAN_FILE
+    used_plan_file = plan_file.is_file()
+    if used_plan_file:
+        argv = terraform.build_apply_argv(
+            binary, plan_file=terraform.DEFAULT_PLAN_FILE, no_color=no_color
+        )
+    else:
+        argv = terraform.build_apply_argv(
+            binary, auto_approve=auto_approve, no_color=no_color
+        )
+
+    code = runner.run_streaming(
+        argv + ctx.args,
+        cwd=cfg.working_dir,
+        env=env,
+        log_path=cfg.working_dir / "apply.txt" if artifacts else None,
+        no_color=no_color,
+    )
+    if used_plan_file and code == 0:
+        plan_file.unlink()
+    raise typer.Exit(code=code)

nac/cli/destroy.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""`nac destroy` -- streams `terraform destroy`."""
+
+import typer
+
+from nac import runner, terraform
+
+from .main import app, get_config, get_no_color, resolve_engine_or_exit
+from .options import Artifacts, AutoApprove
+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 destroy(
+    ctx: typer.Context,
+    auto_approve: AutoApprove = False,
+    artifacts: Artifacts = False,
+) -> None:
+    """Destroy the managed infrastructure (interactive unless --auto-approve).
+
+    Extra arguments are passed through to `terraform`/`tofu`.
+    """
+    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, "destroy", "--help"],
+            cwd=cfg.working_dir,
+            env=env,
+            no_color=get_no_color(ctx),
+            tool_label=f"{engine} destroy",
+            usage_as="nac destroy",
+        )
+
+    argv = terraform.build_destroy_argv(
+        binary, auto_approve=auto_approve, no_color=no_color
+    )
+
+    code = runner.run_streaming(
+        argv + ctx.args,
+        cwd=cfg.working_dir,
+        env=env,
+        log_path=cfg.working_dir / "destroy.txt" if artifacts else None,
+        no_color=no_color,
+    )
+    raise typer.Exit(code=code)

nac/cli/init.py

@@ -0,0 +1,52 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""`nac init` -- streams terraform/tofu init in working_dir."""
+
+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 init(ctx: typer.Context, artifacts: Artifacts = False) -> None:
+    """Initialize the Terraform/OpenTofu working directory.
+
+    Extra arguments are passed through to `terraform`/`tofu`.
+    """
+    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, "init", "--help"],
+            cwd=cfg.working_dir,
+            env=env,
+            no_color=no_color,
+            tool_label=f"{engine} init",
+            usage_as="nac init",
+        )
+
+    code = runner.run_streaming(
+        terraform.build_init_argv(binary, no_color=no_color) + ctx.args,
+        cwd=cfg.working_dir,
+        env=env,
+        log_path=cfg.working_dir / "init.txt" if artifacts else None,
+        no_color=no_color,
+    )
+    raise typer.Exit(code=code)

nac/cli/main.py

@@ -0,0 +1,104 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""CLI entry point for nac: global options, config loading, shared helpers."""
+
+import logging
+import os
+import sys
+from pathlib import Path
+from typing import NoReturn, cast
+
+import typer
+
+from nac import terraform
+from nac.config import DEFAULT_CONFIG_PATH, NacConfig, load_config
+from nac.exceptions import ConfigError, EngineNotFoundError, NoEngineAvailableError
+from nac.output import ensure_utf8_streams
+
+from .options import ConfigPath, NoColor, Verbosity, VerbosityLevel, Version
+
+app = typer.Typer(
+    add_completion=False,
+    help="An umbrella CLI wrapping terraform/tofu, nac-validate, and nac-test.",
+)
+
+
+def configure_logging(level: VerbosityLevel) -> None:
+    logging.basicConfig(
+        level=getattr(logging, level.value),
+        format="%(levelname)s - %(message)s",
+        stream=sys.stdout,
+        force=True,
+    )
+
+
+def fail(message: str, code: int = 1) -> NoReturn:
+    """Print a clean error message to stderr and exit with a non-zero code."""
+    typer.echo(message, err=True)
+    raise typer.Exit(code=code)
+
+
+def get_config(ctx: typer.Context) -> NacConfig:
+    """Load (once, lazily) and return the NacConfig for this invocation.
+
+    Deferred until a subcommand actually needs it -- rather than in the
+    app callback -- so `nac <subcommand> --help` works without a config
+    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.
+    """
+    if isinstance(ctx.obj, NacConfig):
+        return ctx.obj
+    try:
+        cfg = load_config(cast(Path, ctx.obj))
+    except ConfigError as exc:
+        fail(str(exc))
+    ctx.obj = cfg
+    return cfg
+
+
+def resolve_engine_or_exit(cfg: NacConfig) -> tuple[str, str]:
+    """Resolve the terraform/tofu binary, failing cleanly on any error.
+
+    Used by init/validate/plan/apply, none of which perform the
+    interactive FR-12 bootstrap prompt -- that is `nac setup`'s job.
+    """
+    try:
+        return terraform.resolve_engine_binary(cfg.tools.terraform)
+    except (EngineNotFoundError, NoEngineAvailableError) as exc:
+        fail(str(exc))
+
+
+def get_no_color(ctx: typer.Context) -> bool:
+    """Whether colored output should be suppressed for this invocation.
+
+    Resolved once by the app callback from the `--no-color` flag / NO_COLOR
+    env var and stashed on `ctx.meta` (Click's per-invocation scratch dict),
+    so it doesn't collide with `ctx.obj`'s lazy NacConfig loading above.
+    """
+    return bool(ctx.meta.get("no_color", False))
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    config: ConfigPath = DEFAULT_CONFIG_PATH,
+    verbosity: Verbosity = VerbosityLevel.WARNING,
+    no_color: NoColor = False,
+    version: Version = False,
+) -> None:
+    """An umbrella CLI wrapping terraform/tofu, nac-validate, and nac-test."""
+    ensure_utf8_streams()
+    configure_logging(verbosity)
+    ctx.meta["no_color"] = no_color or "NO_COLOR" in os.environ
+    ctx.obj = config
+
+
+def run() -> None:
+    """Console-script entry point for both `nac` and its `nac-cli` alias.
+
+    Pins the program name so help and usage always show `nac`, whichever
+    name it was invoked under.
+    """
+    app(prog_name="nac")

nac/cli/options.py

@@ -0,0 +1,114 @@
+# SPDX-License-Identifier: MPL-2.0
+# Copyright (c) 2026 Daniel Schmidt
+
+"""Annotated Typer option aliases shared across nac's subcommands."""
+
+from enum import StrEnum
+from pathlib import Path
+from typing import Annotated
+
+import typer
+
+from nac import __version__
+
+
+class VerbosityLevel(StrEnum):
+    DEBUG = "DEBUG"
+    INFO = "INFO"
+    WARNING = "WARNING"
+    ERROR = "ERROR"
+    CRITICAL = "CRITICAL"
+
+
+ConfigPath = Annotated[
+    Path,
+    typer.Option(
+        "--config",
+        help="Path to the nac.yaml config file.",
+        envvar="NAC_CONFIG",
+    ),
+]
+
+Verbosity = Annotated[
+    VerbosityLevel,
+    typer.Option(
+        "-v",
+        "--verbosity",
+        help="Verbosity level.",
+        envvar="NAC_VERBOSITY",
+        is_eager=True,
+    ),
+]
+
+AutoApprove = Annotated[
+    bool,
+    typer.Option(
+        "--auto-approve",
+        help="Skip interactive approval (apply: only without a saved plan).",
+    ),
+]
+
+Artifacts = Annotated[
+    bool,
+    typer.Option(
+        "--artifacts",
+        help=(
+            "Also write the command's output to <command>.txt in the "
+            "working dir (e.g. validate.txt, plan.txt/plan.json)."
+        ),
+    ),
+]
+
+Yes = Annotated[
+    bool,
+    typer.Option(
+        "--yes",
+        "--install",
+        help="Assume yes for confirmation prompts (e.g. the OpenTofu bootstrap install).",
+    ),
+]
+
+Prewarm = Annotated[
+    bool,
+    typer.Option(
+        "--prewarm",
+        help="Pre-warm the uvx cache for nac-validate/nac-test.",
+    ),
+]
+
+NoColor = Annotated[
+    bool,
+    typer.Option(
+        "--no-color",
+        help="Disable colored output (also honored via the NO_COLOR env var).",
+    ),
+]
+
+
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(f"nac {__version__}")
+        raise typer.Exit()
+
+
+Version = Annotated[
+    bool,
+    typer.Option(
+        "--version",
+        help="Show the version and exit.",
+        callback=_print_version,
+        is_eager=True,
+    ),
+]
+
+__all__ = [
+    "AutoApprove",
+    "Artifacts",
+    "ConfigPath",
+    "NoColor",
+    "Prewarm",
+    "Verbosity",
+    "VerbosityLevel",
+    "Version",
+    "Yes",
+]