NextLevelApex

NextLevelApex is a security-focused macOS setup orchestrator for running repeatable workstation and DNS-stack tasks with drift detection, health tracking, diagnostics, and report generation.

Who This Is For

• Developers automating macOS bootstrap and maintenance
• Operators managing local Cloudflared/Pi-hole workflows
• Teams that need repeatable CLI + API orchestration with auditability

High-Level Architecture

• Canonical CLI orchestrator: nextlevelapex/main2.py (exposed as nlx)
• Compatibility shim for legacy module invocations: nextlevelapex/main.py
• Task registry and guarded discovery: nextlevelapex/core/registry.py
• State tracking and drift detection: nextlevelapex/core/state.py
• Atomic report generation: nextlevelapex/core/report.py
• API wrapper: nextlevelapex/api/main.py (FastAPI)
• Canonical web GUI (read-only v1): dashboard/ (Next.js)

Supported Platforms

• Primary runtime target: macOS (Darwin)
• Development and most tests: macOS/Linux
• install-sudoers is intentionally macOS-only

Prerequisites

• Python 3.11+
• Poetry
• Optional for DNS stack tasks: Homebrew, Colima, Docker

Installation

git clone https://github.com/Doogie201/NextLevelApex.git
cd NextLevelApex
poetry install

Quickstart

List commands:

poetry run nlx --help

Run orchestrator in dry-run mode without generating reports:

poetry run nlx --dry-run --no-reports

Inspect discovered task states:

poetry run nlx list-tasks

Generate reports from current state:

poetry run nlx report

Run the API server:

poetry run uvicorn nextlevelapex.api.main:app --reload

Run the canonical GUI dashboard:

npm --prefix dashboard install
npm --prefix dashboard run dev -- --hostname 127.0.0.1 --port 4010

GUI v1 is read-only: it supports diagnose + dry-run workflows only and ships no mutation endpoints.

Security Posture

NextLevelApex is hardened around least privilege and trust-boundary control:

• Task provenance gates block untrusted module execution.
• Remediation shell actions are allowlisted (no arbitrary shell payload execution).
• install-sudoers validates interface and username formats, renders deterministic sudoers rules, and validates syntax with visudo before install.
• Sudoers verification fails closed if includedir cannot be verified non-interactively.
• State and reports use atomic writes to reduce corruption risk.

See also:

• SECURITY.md
• SECURITY_NOTES.md

Development and Validation

poetry run pytest -q
poetry run ruff check .
poetry run black --check .
poetry run isort --check-only .
poetry run mypy .

Git Worktree Setup

Poetry creates a separate virtualenv for each project path. When using git worktree, each worktree needs its own poetry install:

git worktree add ../my-worktree main
cd ../my-worktree
bash scripts/dev-setup.sh   # installs Poetry deps + dashboard deps

Or manually:

poetry install               # Python deps + nlx entrypoint
npm --prefix dashboard ci    # dashboard deps

Without this, you will see:

• Warning: 'nlx' is an entry point defined in pyproject.toml, but it's not installed as a script
• ModuleNotFoundError: No module named 'typer' (or other deps)

Troubleshooting

• ModuleNotFoundError for dependencies:
  • Run poetry install then use poetry run ... or activate Poetry's environment.
  • In a git worktree, you must run poetry install in each worktree separately.
• Warning: 'nlx' is an entry point ... not installed as a script:
  • Run poetry install to register the entrypoint.
• install-sudoers cannot verify includedir:
  • Run sudo visudo and ensure one of these exists:
    • #includedir /private/etc/sudoers.d
    • #includedir /etc/sudoers.d
• Selective task execution:
  • Use --task filters to target specific tasks.

Contributing

See CONTRIBUTING.md for branching, checks, and PR expectations.

License

This project is licensed under the MIT License. See LICENSE.