nat-engine 1__py3-none-any.whl

mannf/product/setup_wizard.py

@@ -0,0 +1,873 @@
+# Copyright (C) 2026 Brad Guider
+# This file is part of NAT (Neural Agent Testing Framework).
+# Licensed under the AGPL-3.0. See LICENSE for details.
+# Commercial licensing available — see COMMERCIAL_LICENSE.md.
+
+"""Interactive setup wizard for NAT — guides users through full end-to-end configuration.
+
+This module implements a 7-phase interactive wizard that configures NAT from
+scratch, covering mode selection, spec ingestion, authentication, exporter
+setup (with live connection tests), and writing the ``.natrc`` config file.
+
+Non-interactive mode is also supported via the ``--non-interactive`` flag
+combined with environment variables (see :func:`run_setup_wizard`).
+
+Entry point::
+
+    async def run_setup_wizard(args: argparse.Namespace) -> int:
+        ...
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import logging
+import os
+import platform
+import shutil
+import subprocess
+import sys
+from pathlib import Path
+from typing import Any
+
+logger = logging.getLogger(__name__)
+
+# ---------------------------------------------------------------------------
+# Constants
+# ---------------------------------------------------------------------------
+
+_SEVERITY_CHOICES = ("critical", "high", "medium", "low", "info")
+
+_MODE_SAAS = "saas"
+_MODE_SELF_HOSTED = "self-hosted"
+_MODE_CLI = "cli"
+
+_AUTH_BEARER = "bearer"
+_AUTH_API_KEY = "api-key"
+_AUTH_OAUTH2 = "oauth2"
+_AUTH_NONE = "none"
+
+# Exporter-specific environment variable mappings
+# Maps exporter name -> {config_key: env_var_name}
+_EXPORTER_ENV_VARS: dict[str, dict[str, str]] = {
+    "jira": {
+        "base_url": "NAT_JIRA_BASE_URL",
+        "project_key": "NAT_JIRA_PROJECT_KEY",
+        "email": "NAT_JIRA_EMAIL",
+        "api_token": "NAT_JIRA_API_TOKEN",
+    },
+    "github-issues": {
+        "token": "NAT_GITHUB_TOKEN",
+        "repo": "NAT_GITHUB_REPO",
+    },
+    "gitlab": {
+        "gitlab_url": "NAT_GITLAB_URL",
+        "project_id": "NAT_GITLAB_PROJECT_ID",
+        "private_token": "NAT_GITLAB_TOKEN",
+    },
+    "linear": {
+        "api_key": "NAT_LINEAR_API_KEY",
+        "team_id": "NAT_LINEAR_TEAM_ID",
+    },
+    "azure-devops": {
+        "organization": "NAT_ADO_ORG",
+        "project": "NAT_ADO_PROJECT",
+        "pat": "NAT_ADO_PAT",
+    },
+    "shortcut": {
+        "api_token": "NAT_SHORTCUT_TOKEN",
+        "project_id": "NAT_SHORTCUT_PROJECT_ID",
+    },
+    "pagerduty": {
+        "routing_key": "NAT_PAGERDUTY_ROUTING_KEY",
+    },
+    "servicenow": {
+        "instance_url": "NAT_SERVICENOW_URL",
+        "username": "NAT_SERVICENOW_USER",
+        "password": "NAT_SERVICENOW_PASSWORD",
+    },
+    "webhook": {
+        "webhook_url": "NAT_WEBHOOK_URL",
+    },
+}
+
+# Human-readable prompts for exporter config fields
+_EXPORTER_FIELD_PROMPTS: dict[str, dict[str, str]] = {
+    "jira": {
+        "base_url": "Jira Cloud base URL (e.g. https://myco.atlassian.net)",
+        "project_key": "Jira project key (e.g. SEC)",
+        "email": "Atlassian account email",
+        "api_token": "Atlassian API token (from id.atlassian.com → Security → API tokens)",
+        "issue_type": "Issue type (default: Bug)",
+        "component": "Jira component name (optional)",
+    },
+    "github-issues": {
+        "token": "GitHub personal access token (PAT) with 'repo' scope",
+        "repo": "Repository in owner/repo format (e.g. myorg/myrepo)",
+        "labels": "Comma-separated extra labels (optional)",
+        "deduplicate": "Deduplicate issues? [true/false] (default: false)",
+    },
+    "gitlab": {
+        "gitlab_url": "GitLab instance URL (e.g. https://gitlab.com)",
+        "project_id": "GitLab project ID or namespace/project slug",
+        "private_token": "GitLab Personal Access Token with 'api' scope",
+        "labels": "Comma-separated extra labels (optional)",
+    },
+    "linear": {
+        "api_key": "Linear personal API key",
+        "team_id": "Linear team ID",
+        "project_id": "Linear project ID (optional)",
+    },
+    "azure-devops": {
+        "organization": "Azure DevOps organization name",
+        "project": "Azure DevOps project name",
+        "pat": "Personal Access Token with Work Items (Read & Write) scope",
+        "work_item_type": "Work item type (default: Bug)",
+    },
+    "shortcut": {
+        "api_token": "Shortcut API token",
+        "project_id": "Shortcut project ID (integer)",
+        "story_type": "Story type: bug, chore, or feature (default: bug)",
+    },
+    "pagerduty": {
+        "routing_key": "PagerDuty integration key (Events API v2 routing key)",
+        "source": "Source label (default: nat-security-scan)",
+    },
+    "servicenow": {
+        "instance_url": "ServiceNow instance URL (e.g. https://myco.service-now.com)",
+        "username": "ServiceNow username",
+        "password": "ServiceNow password",
+        "oauth_token": "OAuth bearer token (alternative to username/password, optional)",
+        "table": "Table: incident or change_request (default: incident)",
+    },
+    "webhook": {
+        "webhook_url": "Webhook URL (HTTP/HTTPS endpoint to POST findings to)",
+        "auth_header": "Authorization header value (optional, e.g. Bearer mytoken)",
+        "hmac_secret": "HMAC-SHA256 signing secret (optional)",
+        "batch_mode": "Send all findings in one POST? [true/false] (default: false)",
+    },
+}
+
+# Required fields per exporter (subset of above that must not be empty)
+_EXPORTER_REQUIRED_FIELDS: dict[str, list[str]] = {
+    "jira": ["base_url", "project_key", "email", "api_token"],
+    "github-issues": ["token", "repo"],
+    "gitlab": ["gitlab_url", "project_id", "private_token"],
+    "linear": ["api_key", "team_id"],
+    "azure-devops": ["organization", "project", "pat"],
+    "shortcut": ["api_token", "project_id"],
+    "pagerduty": ["routing_key"],
+    "servicenow": ["instance_url"],
+    "webhook": ["webhook_url"],
+}
+
+
+# ---------------------------------------------------------------------------
+# I/O helpers
+# ---------------------------------------------------------------------------
+
+
+def _print(msg: str = "") -> None:
+    print(msg)  # noqa: T201  # lgtm[py/clear-text-logging-sensitive-data]
+
+
+def _prompt(message: str, default: str = "", secret: bool = False) -> str:
+    """Prompt the user for input, optionally with a default value.
+
+    Parameters
+    ----------
+    message:
+        The prompt message to display.
+    default:
+        Default value shown in brackets.  Used if the user presses Enter.
+    secret:
+        If True, suppress echoing the input (for passwords/tokens).
+    """
+    if default:
+        display = f"{message} [{default}]: "
+    else:
+        display = f"{message}: "
+
+    if secret:
+        import getpass  # noqa: PLC0415
+        value = getpass.getpass(display)
+    else:
+        value = input(display)
+
+    return value.strip() or default
+
+
+def _prompt_choice(message: str, choices: list[str], default: str = "") -> str:
+    """Prompt the user to choose one of *choices*.
+
+    Accepts the choice number or the value directly.  Repeats until valid.
+    """
+    for i, choice in enumerate(choices, 1):
+        _print(f"  {i}. {choice}")
+
+    while True:
+        raw = _prompt(message, default=default)
+        # Accept numeric index
+        if raw.isdigit():
+            idx = int(raw) - 1
+            if 0 <= idx < len(choices):
+                return choices[idx]
+        # Accept the value directly (case-insensitive)
+        for choice in choices:
+            if raw.lower() == choice.lower():
+                return choice
+        _print(f"  ⚠️  Please enter a number (1–{len(choices)}) or one of {choices}")
+
+
+def _prompt_yes_no(message: str, default: bool = True) -> bool:
+    """Prompt for a yes/no answer."""
+    hint = "[Y/n]" if default else "[y/N]"
+    raw = _prompt(f"{message} {hint}").lower()
+    if not raw:
+        return default
+    return raw in ("y", "yes")
+
+
+# ---------------------------------------------------------------------------
+# Environment detection helpers
+# ---------------------------------------------------------------------------
+
+
+def _detect_docker() -> bool:
+    """Return True if Docker is available on the system PATH."""
+    return shutil.which("docker") is not None
+
+
+def _detect_existing_natrc() -> Path | None:
+    """Return the path to an existing .natrc file, or None."""
+    for candidate in (Path.cwd() / ".natrc", Path.home() / ".natrc"):
+        if candidate.is_file():
+            return candidate
+    return None
+
+
+def _detect_python_version() -> str:
+    return f"{sys.version_info.major}.{sys.version_info.minor}.{sys.version_info.micro}"
+
+
+# ---------------------------------------------------------------------------
+# Phase 1 — Environment detection
+# ---------------------------------------------------------------------------
+
+
+def _phase1_detect_environment() -> dict[str, Any]:
+    """Detect and display system environment information."""
+    _print()
+    _print("━" * 60)
+    _print("  Phase 1 — Environment Detection")
+    _print("━" * 60)
+
+    python_ver = _detect_python_version()
+    os_name = f"{platform.system()} {platform.release()}"
+    docker_ok = _detect_docker()
+    existing_rc = _detect_existing_natrc()
+
+    _print()
+    _print(f"  Python:  {python_ver}")
+    _print(f"  OS:      {os_name}")
+    _print(f"  Docker:  {'✅ available' if docker_ok else '❌ not found'}")
+    _print(
+        f"  .natrc:  {'✅ found at ' + str(existing_rc) if existing_rc else '❌ none found'}"
+    )
+    _print()
+
+    return {
+        "python_version": python_ver,
+        "os": os_name,
+        "docker_available": docker_ok,
+        "existing_natrc": existing_rc,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Phase 2 — Mode selection
+# ---------------------------------------------------------------------------
+
+
+def _phase2_select_mode(env: dict[str, Any], non_interactive: bool) -> dict[str, Any]:
+    """Prompt user for deployment mode and associated credentials."""
+    _print("━" * 60)
+    _print("  Phase 2 — Deployment Mode")
+    _print("━" * 60)
+    _print()
+
+    mode_config: dict[str, Any] = {}
+
+    if non_interactive:
+        raw_mode = os.environ.get("NAT_MODE", _MODE_CLI).lower()
+        if raw_mode not in (_MODE_SAAS, _MODE_SELF_HOSTED, _MODE_CLI):
+            logger.warning("Unknown NAT_MODE '%s' — defaulting to cli", raw_mode)
+            raw_mode = _MODE_CLI
+        mode_config["mode"] = raw_mode
+        if raw_mode == _MODE_SAAS:
+            mode_config["nat_api_key"] = os.environ.get("NAT_API_KEY", "")
+        elif raw_mode == _MODE_SELF_HOSTED:
+            mode_config["database_url"] = os.environ.get("DATABASE_URL", "")
+        _print(f"  Mode: {raw_mode} (from NAT_MODE env var)")
+        _print()
+        return mode_config
+
+    _print("  How will you use NAT?")
+    mode = _prompt_choice(
+        "  Choice",
+        [_MODE_SAAS, _MODE_SELF_HOSTED, _MODE_CLI],
+        default="1",
+    )
+    mode_config["mode"] = mode
+
+    if mode == _MODE_SAAS:
+        _print()
+        _print("  Enter your NAT API key (from app.nat-testing.io → Settings → API Keys):")
+        api_key = _prompt("  API key", secret=True)
+        mode_config["nat_api_key"] = api_key
+
+    elif mode == _MODE_SELF_HOSTED:
+        _print()
+        _print("  Self-hosted mode requires a PostgreSQL (or SQLite) database.")
+        db_url = _prompt(
+            "  DATABASE_URL",
+            default=os.environ.get("DATABASE_URL", "sqlite+aiosqlite:///./nat.db"),
+        )
+        mode_config["database_url"] = db_url
+
+        _print()
+        _print("  💡 Tip: run 'alembic upgrade head' to apply database migrations.")
+        if _prompt_yes_no("  Run Alembic migrations now?", default=False):
+            _run_alembic_upgrade()
+
+    _print()
+    return mode_config
+
+
+def _run_alembic_upgrade() -> None:
+    """Attempt to run 'alembic upgrade head' in a subprocess."""
+    try:
+        result = subprocess.run(  # noqa: S603, S607
+            ["alembic", "upgrade", "head"],
+            capture_output=True,
+            text=True,
+            timeout=60,
+        )
+        if result.returncode == 0:
+            _print("  ✅ Alembic migrations applied successfully.")
+        else:
+            _print(f"  ⚠️  Alembic exited with code {result.returncode}:")
+            _print(f"      {result.stderr.strip()}")
+    except FileNotFoundError:
+        _print("  ⚠️  'alembic' command not found — run it manually: alembic upgrade head")
+    except subprocess.TimeoutExpired:
+        _print("  ⚠️  Alembic timed out — run it manually: alembic upgrade head")
+    except Exception as exc:  # noqa: BLE001
+        _print(f"  ⚠️  Failed to run Alembic: {exc}")
+
+
+# ---------------------------------------------------------------------------
+# Phase 3 — Spec / ingestion setup
+# ---------------------------------------------------------------------------
+
+
+def _phase3_spec_setup(non_interactive: bool) -> dict[str, Any]:
+    """Prompt for API spec location, detect format, count endpoints."""
+    _print("━" * 60)
+    _print("  Phase 3 — API Spec / Ingestion Setup")
+    _print("━" * 60)
+    _print()
+
+    spec_config: dict[str, Any] = {}
+
+    if non_interactive:
+        spec_path = os.environ.get("NAT_SPEC_PATH", "")
+        base_url = os.environ.get("NAT_BASE_URL", "")
+    else:
+        _print("  Where is your API spec?")
+        _print("  (Accepts a file path or a URL)")
+        spec_path = _prompt("  Spec path or URL")
+        base_url = _prompt("  Base URL of your API (e.g. https://api.example.com)")
+
+    spec_config["spec_path"] = spec_path
+    spec_config["base_url"] = base_url
+
+    if spec_path:
+        detected = _try_detect_spec(spec_path)
+        if detected:
+            format_name = detected.get("format", "unknown")
+            endpoint_count = detected.get("endpoint_count", "?")
+            _print(
+                f"  ✅ Detected: {format_name} — {endpoint_count} endpoint(s)"
+            )
+            spec_config["detected_format"] = format_name
+            spec_config["endpoint_count"] = endpoint_count
+        else:
+            _print("  ⚠️  Could not detect spec format — will attempt auto-detection at scan time.")
+
+    _print()
+    return spec_config
+
+
+def _try_detect_spec(spec_path: str) -> dict[str, Any] | None:
+    """Attempt to detect the format and count of endpoints in *spec_path*.
+
+    Returns a dict with ``format`` and ``endpoint_count`` keys, or None.
+    """
+    try:
+        from mannf.product.ingestors.loader import get_ingestor_for_source  # noqa: PLC0415
+        from mannf.product.ingestors.models import IngestorSource  # noqa: PLC0415
+
+        # Build a minimal IngestorSource
+        if spec_path.startswith(("http://", "https://")):
+            source = IngestorSource(format="auto", url=spec_path)
+        else:
+            source = IngestorSource(format="auto", path=spec_path)
+
+        ingestor = get_ingestor_for_source(source)
+        if ingestor is None:
+            return None
+
+        # Run ingest in a nested event loop call
+        result = asyncio.get_event_loop().run_until_complete(
+            ingestor.ingest(source, {})
+        )
+        if result and result.success:
+            return {
+                "format": ingestor.display_name,
+                "endpoint_count": len(result.endpoints),
+            }
+    except Exception as exc:  # noqa: BLE001
+        logger.debug("Spec detection failed: %s", exc)
+
+    return None
+
+
+# ---------------------------------------------------------------------------
+# Phase 4 — Authentication
+# ---------------------------------------------------------------------------
+
+
+def _phase4_auth_setup(spec_config: dict[str, Any], non_interactive: bool) -> dict[str, Any]:
+    """Prompt for API authentication credentials."""
+    _print("━" * 60)
+    _print("  Phase 4 — API Authentication")
+    _print("━" * 60)
+    _print()
+
+    auth_config: dict[str, Any] = {}
+
+    if non_interactive:
+        token = os.environ.get("NAT_AUTH_TOKEN", "")
+        if token:
+            auth_config["auth_type"] = _AUTH_BEARER
+            auth_config["token"] = token
+        else:
+            auth_config["auth_type"] = _AUTH_NONE
+        _print(f"  Auth type: {auth_config['auth_type']} (from env vars)")
+        _print()
+        return auth_config
+
+    _print("  Does your API require authentication?")
+    auth_choices = [
+        "None — public API",
+        "Bearer token",
+        "API key header",
+        "OAuth2 client credentials",
+    ]
+    auth_choice = _prompt_choice("  Choice", auth_choices, default="1")
+
+    if "None" in auth_choice:
+        auth_config["auth_type"] = _AUTH_NONE
+    elif "Bearer" in auth_choice:
+        auth_config["auth_type"] = _AUTH_BEARER
+        auth_config["token"] = _prompt("  Bearer token", secret=True)
+    elif "API key" in auth_choice:
+        auth_config["auth_type"] = _AUTH_API_KEY
+        auth_config["api_key"] = _prompt("  API key value", secret=True)
+        auth_config["api_key_header"] = _prompt(
+            "  Header name", default="X-API-Key"
+        )
+    elif "OAuth2" in auth_choice:
+        auth_config["auth_type"] = _AUTH_OAUTH2
+        auth_config["client_id"] = _prompt("  Client ID")
+        auth_config["client_secret"] = _prompt("  Client secret", secret=True)
+        auth_config["token_url"] = _prompt("  Token URL (e.g. https://auth.example.com/oauth2/token)")
+
+    _print()
+    return auth_config
+
+
+# ---------------------------------------------------------------------------
+# Phase 5 — Export destination
+# ---------------------------------------------------------------------------
+
+
+def _phase5_exporter_setup(non_interactive: bool) -> dict[str, Any]:
+    """Prompt for exporter selection, config, and run a live connection test."""
+    _print("━" * 60)
+    _print("  Phase 5 — Export Destination")
+    _print("━" * 60)
+    _print()
+
+    from mannf.product.exporters import BUILTIN_EXPORTERS  # noqa: PLC0415
+
+    exporters = BUILTIN_EXPORTERS
+
+    if non_interactive:
+        exporter_name = os.environ.get("NAT_EXPORT", "").lower()
+        if not exporter_name:
+            _print("  No NAT_EXPORT set — skipping exporter configuration.")
+            _print()
+            return {}
+
+        exporter = next((e for e in exporters if e.name == exporter_name), None)
+        if exporter is None:
+            _print(f"  ⚠️  Unknown exporter '{exporter_name}' — skipping.")
+            _print()
+            return {}
+
+        # Build config from env vars
+        env_map = _EXPORTER_ENV_VARS.get(exporter_name, {})
+        exporter_config: dict[str, str] = {}
+        for key, env_var in env_map.items():
+            value = os.environ.get(env_var, "")
+            if value:
+                exporter_config[key] = value
+
+        return _finalize_exporter_config(exporter, exporter_config)
+
+    _print("  Which system should NAT export findings to?")
+    exporter_names = [f"{e.display_name} ({e.name})" for e in exporters]
+    exporter_names.append("Skip — no exporter")
+
+    choice = _prompt_choice("  Choice", exporter_names, default="1")
+
+    if "Skip" in choice:
+        _print()
+        return {}
+
+    # Find the selected exporter
+    selected_exporter = None
+    for exporter in exporters:
+        label = f"{exporter.display_name} ({exporter.name})"
+        if label == choice:
+            selected_exporter = exporter
+            break
+
+    if selected_exporter is None:
+        _print("  ⚠️  Could not identify exporter — skipping.")
+        _print()
+        return {}
+
+    _print()
+    _print(f"  Configuring: {selected_exporter.display_name}")
+    _print()
+
+    # Collect required fields
+    field_prompts = _EXPORTER_FIELD_PROMPTS.get(selected_exporter.name, {})
+    required_fields = _EXPORTER_REQUIRED_FIELDS.get(selected_exporter.name, [])
+    exporter_config = {}
+
+    for field_key, prompt_text in field_prompts.items():
+        is_required = field_key in required_fields
+        is_secret = any(word in field_key.lower() for word in ("token", "secret", "password", "pat", "key"))
+        prefix = "  * " if is_required else "    "
+        value = _prompt(f"{prefix}{prompt_text}", secret=is_secret)
+        if value:
+            exporter_config[field_key] = value
+
+    # Validate config
+    validation_errors = selected_exporter.validate_config(exporter_config)
+    if validation_errors:
+        _print()
+        _print("  ⚠️  Config validation errors:")
+        for err in validation_errors:
+            _print(f"       • {err}")
+        _print("  Proceeding anyway — you can fix these in your .natrc file.")
+
+    # Severity threshold
+    _print()
+    _print("  Minimum severity to export:")
+    severity = _prompt_choice("  Choice", list(_SEVERITY_CHOICES), default="2")
+    exporter_config["min_severity"] = severity
+
+    # Live connection test
+    _print()
+    if _prompt_yes_no("  Test connection now?", default=True):
+        _run_connection_test(selected_exporter, exporter_config)
+
+    return _finalize_exporter_config(selected_exporter, exporter_config)
+
+
+def _run_connection_test(exporter: Any, config: dict) -> None:
+    """Run test_connection() on *exporter* and print the result."""
+    _print("  🔌 Testing connection…")
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            # Already inside an async context — schedule as a task
+            import concurrent.futures  # noqa: PLC0415
+            future = asyncio.ensure_future(exporter.test_connection(config))
+            result = loop.run_until_complete(future)
+        else:
+            result = loop.run_until_complete(exporter.test_connection(config))
+    except Exception as exc:  # noqa: BLE001
+        _print(f"  ❌ Connection test raised an exception: {exc}")
+        return
+
+    if result.success:
+        _print(f"  ✅ {result.message}")
+    else:
+        _print(f"  ❌ {result.message}")
+        if result.details:
+            _print(f"     Details: {result.details}")
+
+
+def _finalize_exporter_config(exporter: Any, config: dict) -> dict[str, Any]:
+    """Wrap the exporter config with its name for storage in .natrc."""
+    return {
+        "exporter_name": exporter.name,
+        "exporter_config": config,
+    }
+
+
+# ---------------------------------------------------------------------------
+# Phase 6 — Write .natrc
+# ---------------------------------------------------------------------------
+
+
+def _phase6_write_natrc(
+    mode_config: dict[str, Any],
+    spec_config: dict[str, Any],
+    auth_config: dict[str, Any],
+    exporter_data: dict[str, Any],
+    non_interactive: bool,
+) -> Path | None:
+    """Serialize collected config to YAML and write .natrc."""
+    _print("━" * 60)
+    _print("  Phase 6 — Write Configuration")
+    _print("━" * 60)
+    _print()
+
+    try:
+        import yaml  # noqa: PLC0415
+    except ImportError:
+        _print("  ❌ PyYAML is not installed — cannot write .natrc.")
+        _print("     Install it with: pip install pyyaml")
+        _print()
+        return None
+
+    # Build the YAML config structure
+    config: dict[str, Any] = {}
+
+    # Mode
+    mode = mode_config.get("mode", _MODE_CLI)
+    config["mode"] = mode
+    if mode == _MODE_SAAS and mode_config.get("nat_api_key"):
+        config["nat_api_key"] = mode_config["nat_api_key"]
+    elif mode == _MODE_SELF_HOSTED and mode_config.get("database_url"):
+        config["database_url"] = mode_config["database_url"]
+
+    # Spec
+    if spec_config.get("spec_path"):
+        config["spec"] = spec_config["spec_path"]
+    if spec_config.get("base_url"):
+        config["base_url"] = spec_config["base_url"]
+
+    # Auth
+    auth_type = auth_config.get("auth_type", _AUTH_NONE)
+    if auth_type == _AUTH_BEARER and auth_config.get("token"):
+        config["auth"] = {"type": "bearer", "token": auth_config["token"]}
+    elif auth_type == _AUTH_API_KEY and auth_config.get("api_key"):
+        config["auth"] = {
+            "type": "api-key",
+            "key": auth_config["api_key"],
+            "header": auth_config.get("api_key_header", "X-API-Key"),
+        }
+    elif auth_type == _AUTH_OAUTH2:
+        config["auth"] = {
+            "type": "oauth2",
+            "client_id": auth_config.get("client_id", ""),
+            "client_secret": auth_config.get("client_secret", ""),
+            "token_url": auth_config.get("token_url", ""),
+        }
+
+    # Exporter
+    if exporter_data.get("exporter_name"):
+        exporter_cfg = dict(exporter_data.get("exporter_config", {}))
+        # Remove meta keys not part of exporter config
+        min_severity = exporter_cfg.pop("min_severity", "high")
+        config["export"] = exporter_data["exporter_name"]
+        config["export_config"] = exporter_cfg
+        config["export_min_severity"] = min_severity
+
+    yaml_text = yaml.dump(config, default_flow_style=False, allow_unicode=True, sort_keys=True)
+
+    # Determine destination
+    if non_interactive:
+        dest = Path.cwd() / ".natrc"
+    else:
+        _print("  Where should the config be saved?")
+        choices = [str(Path.cwd() / ".natrc"), str(Path.home() / ".natrc")]
+        dest_str = _prompt_choice("  Choice", choices, default="2")
+        dest = Path(dest_str)
+
+    # Warn about secrets
+    has_secrets = any(
+        k in config
+        for k in ("nat_api_key", "auth")
+    ) or bool(exporter_data.get("exporter_config"))
+
+    if has_secrets:
+        _print()
+        _print("  ⚠️  Your config contains credentials/secrets.")
+        _print("     Ensure the .natrc file has restricted permissions:")
+        _print("       chmod 600 " + str(dest))
+
+    # Write the file
+    try:
+        dest.write_text(yaml_text, encoding="utf-8")
+        _print()
+        _print(f"  ✅ Config written to {dest}")
+    except OSError as exc:
+        _print(f"  ❌ Failed to write config: {exc}")
+        _print()
+        return None
+
+    _print()
+    return dest
+
+
+# ---------------------------------------------------------------------------
+# Phase 7 — Verify + offer first run
+# ---------------------------------------------------------------------------
+
+
+def _phase7_verify_and_run(
+    natrc_path: Path | None,
+    spec_config: dict[str, Any],
+    non_interactive: bool,
+) -> int:
+    """Run validation checks and optionally kick off a first scan."""
+    _print("━" * 60)
+    _print("  Phase 7 — Verify & First Run")
+    _print("━" * 60)
+    _print()
+
+    all_ok = True
+
+    # Check 1: .natrc exists
+    if natrc_path and natrc_path.is_file():
+        _print(f"  ✅ Config file: {natrc_path}")
+    else:
+        _print("  ⚠️  No .natrc file was written.")
+        all_ok = False
+
+    # Check 2: spec provided
+    spec_path = spec_config.get("spec_path", "")
+    if spec_path:
+        _print(f"  ✅ Spec path: {spec_path}")
+    else:
+        _print("  ⚠️  No spec path configured — provide --spec when running nat scan.")
+        all_ok = False
+
+    # Check 3: base URL
+    base_url = spec_config.get("base_url", "")
+    if base_url:
+        _print(f"  ✅ Base URL: {base_url}")
+    else:
+        _print("  ⚠️  No base URL configured — provide --base-url when running nat scan.")
+
+    _print()
+
+    if all_ok and not non_interactive:
+        if _prompt_yes_no("  Run a scan now?", default=False):
+            _print()
+            _print("  🚀 Launching nat security-scan…")
+            _print()
+            cmd = ["nat", "security-scan"]
+            if spec_path:
+                cmd += ["--spec", spec_path]
+            if base_url:
+                cmd += ["--base-url", base_url]
+            try:
+                subprocess.run(cmd, check=False)  # noqa: S603
+            except FileNotFoundError:
+                _print("  ❌ 'nat' command not found — install nat-engine with pip.")
+                return 1
+
+    _print()
+    _print("  🎉 Setup complete!")
+    _print("     Run 'nat security-scan --help' to see all available options.")
+    _print()
+    return 0
+
+
+# ---------------------------------------------------------------------------
+# Main entry point
+# ---------------------------------------------------------------------------
+
+
+async def run_setup_wizard(args: argparse.Namespace) -> int:
+    """Main entry point for the interactive setup wizard.
+
+    Parameters
+    ----------
+    args:
+        Parsed CLI arguments.  The following attributes are read:
+
+        - ``non_interactive`` (bool) — skip all prompts, read from env vars.
+
+    Returns
+    -------
+    int
+        Exit code (0 = success, non-zero = error).
+    """
+    from mannf._version import __version__  # noqa: PLC0415
+
+    non_interactive: bool = getattr(args, "non_interactive", False)
+
+    _print()
+    _print("┏" + "━" * 58 + "┓")
+    _print(f"  🚀  NAT Setup Wizard  (nat-engine v{__version__})")
+    _print("┗" + "━" * 58 + "┛")
+
+    # Phase 1 — Detect environment
+    env = _phase1_detect_environment()
+
+    # Warn if an existing .natrc will be overwritten
+    if env.get("existing_natrc") and not non_interactive:
+        _print(f"  ⚠️  Existing config found at {env['existing_natrc']}")
+        if not _prompt_yes_no("  Overwrite existing config?", default=False):
+            _print("  Setup cancelled.  Existing config unchanged.")
+            _print()
+            return 0
+        _print()
+
+    # Phase 2 — Mode
+    mode_config = _phase2_select_mode(env, non_interactive)
+
+    # Phase 3 — Spec setup
+    spec_config = _phase3_spec_setup(non_interactive)
+
+    # Phase 4 — Auth
+    auth_config = _phase4_auth_setup(spec_config, non_interactive)
+
+    # Phase 5 — Exporter
+    exporter_data = _phase5_exporter_setup(non_interactive)
+
+    # Phase 6 — Write .natrc (run synchronously within async context)
+    natrc_path = await asyncio.get_event_loop().run_in_executor(
+        None,
+        _phase6_write_natrc,
+        mode_config,
+        spec_config,
+        auth_config,
+        exporter_data,
+        non_interactive,
+    )
+
+    # Phase 7 — Verify + optional first run
+    return _phase7_verify_and_run(natrc_path, spec_config, non_interactive)