feat(r42playbooks): scenario generator — CLI/TUI/API over range42-catalog

.ansible-lint

@@ -0,0 +1,47 @@
+profile: basic
+
+skip_list:
+  # SCREAMING_SNAKE is the documented convention for infrastructure-wide vars
+  - var-naming[pattern]
+  # noun.verb role naming is the documented convention
+  - role-name
+  # generated scenario playbooks do not require play-level names
+  - name[play]
+  # pre-existing task naming convention: lowercase names throughout bundles
+  - name[casing]
+  # generated bundles include tasks without explicit names
+  - name[missing]
+  # Jinja template syntax in task names is intentional (loop items, vars)
+  - name[template]
+  # pre-existing {{ item.ID}} spacing in generated bundles — cosmetic only
+  - jinja[spacing]
+
+warn_list:
+  - yaml[line-length]
+  - yaml[empty-lines]
+  - yaml[trailing-spaces]
+  - risky-shell-pipe
+
+# catalog and cross-repo roles not checked out in CI — stub so syntax-check passes
+mock_roles:
+  - range42-ansible_roles-proxmox_controller
+  - ansible.utils
+  - indexer
+  - software.configure.docker-compose
+  - software.configure.firewalls
+  - software.configure.tailscale_disable_nftables
+  - software.install.nodejs_app_systemd
+  - software.install.symlinks_farm
+  - software.install.tailscale
+  - software.install.warmup.basic_packages
+  - software.install.warmup.dot_files
+  - software.install.wazuh-dashboard
+  - software.install.wazuh-filebeat-oss
+  - software.install.wazuh-indexer
+  - software.install.wazuh-manager
+  - systems.configure.add_user
+  - software.install.wazuh-agent
+
+# vars defined at runtime via inventory/group_vars — stub for CI syntax-check
+extra_vars:
+  global_vm_ssh_name: ci_mock

.github/dependabot.yml

@@ -0,0 +1,12 @@
+version: 2
+updates:
+  - package-ecosystem: pip
+    directory: /
+    schedule:
+      interval: weekly
+    labels: [dependencies]
+  - package-ecosystem: github-actions
+    directory: /
+    schedule:
+      interval: monthly
+    labels: [dependencies, ci]

.github/workflows/ci.yml

@@ -0,0 +1,34 @@
+name: CI
+on:
+  push:
+    branches: [main, dev, 'feat/**', 'fix/**']
+  pull_request:
+    branches: [main, dev]
+jobs:
+  ansible-lint:
+    name: Ansible Lint
+    runs-on: ubuntu-latest
+    container:
+      image: python:3.13-slim
+    steps:
+      - run: apt-get update && apt-get install -y --no-install-recommends git
+      - uses: actions/checkout@v6
+      - run: pip install --no-cache-dir ansible-lint
+      - run: ansible-lint bundles/
+
+  python:
+    name: Ruff + Pytest
+    runs-on: ubuntu-latest
+    container:
+      image: python:3.13-slim
+    steps:
+      - run: apt-get update && apt-get install -y --no-install-recommends git
+      - uses: actions/checkout@v6
+      - id: pycheck
+        run: test -f pyproject.toml && echo "exists=true" >> "$GITHUB_OUTPUT" || echo "exists=false" >> "$GITHUB_OUTPUT"
+      - if: "steps.pycheck.outputs.exists == 'true'"
+        run: pip install --no-cache-dir -e ".[dev]"
+      - if: "steps.pycheck.outputs.exists == 'true'"
+        run: ruff check --select ALL r42playbooks/
+      - if: "steps.pycheck.outputs.exists == 'true'"
+        run: pytest tests/ --tb=short -q

.gitignore

@@ -2,3 +2,23 @@
 **/secret/
 CLAUDE.md
 **/CLAUDE.md
+
+# Python (r42playbooks module)
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+.pytest_cache/
+.ruff_cache/
+.coverage
+htmlcov/
+dist/
+build/
+
+# Claude session files (local only — handoffs, design notes)
+.claude/
+
+# Scratch compiler artifacts (flat-workspace outputs, never committed)
+/topology.json
+/hosts.yml
+/expanded.json

pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "r42playbooks"
+version = "0.1.0"
+description = "range42 scenario generator — compose labs from the catalog into deployable scenarios/"
+readme = "r42playbooks/README.md"
+requires-python = ">=3.11"
+license = { text = "GPL-3.0-only" }
+dependencies = [
+  "pydantic>=2,<3",
+  "pyyaml>=6",
+]
+
+[project.optional-dependencies]
+cli = ["typer>=0.12"]
+tui = ["textual>=0.60"]
+dev = ["pytest>=8.3", "pytest-cov"]
+
+[project.scripts]
+r42playbooks = "r42playbooks.cli:app"
+r42playbooks-tui = "r42playbooks.tui.app:main"
+
+[tool.setuptools.packages.find]
+include = ["r42playbooks*"]
+
+[tool.setuptools.package-data]
+# Verbatim scenario boilerplate copied into every generated tree (e.g. the
+# 01_init_proxmox/ template-creation subtree — see render.py / plan H3).
+r42playbooks = ["assets/**/*"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"

r42playbooks/README.md

@@ -0,0 +1,104 @@
+# r42playbooks
+
+**Scenario generator for range42 — compose labs from the catalog.**
+
+`r42playbooks` lists the composable modules in `range42-catalog`, lets you compose a lab
+(CLI flags, a `scenario.r42.yml` spec, or the TUI), and **generates a real
+`scenarios/<name>/` directory** in the existing `demo_lab` format — deployable through the
+normal range42 flow (`range42-context deploy`) with no changes elsewhere.
+
+It is **not** the canonical topology engine for the gamenet "universal" playbook (that
+convergence is parked on a separate branch, issue #67). A generated scenario references
+catalog content **by name only** — Ansible roles resolve via `ANSIBLE_ROLES_PATH`, container
+stacks via `RANGE42_INVENTORY__DOCKER__*` — so the generated tree stays a thin recipe of names,
+never a copy of role code.
+
+## Install
+
+```bash
+pip install r42playbooks            # pure core only (pydantic + pyyaml + stdlib)
+pip install "r42playbooks[cli]"     # + Typer CLI
+pip install "r42playbooks[tui]"     # + Textual TUI
+```
+
+## CLI (`list` / `show` / `new` / `validate`)
+
+```bash
+# explore the catalog
+r42playbooks list boxes      --catalog ../range42-catalog
+r42playbooks list subnets    --catalog ../range42-catalog
+r42playbooks list policies   --catalog ../range42-catalog
+r42playbooks list roles      --catalog ../range42-catalog
+r42playbooks list containers --catalog ../range42-catalog
+r42playbooks show vuln-box   --catalog ../range42-catalog
+
+# compose + generate a scenario from flags
+r42playbooks new my_lab \
+    --subnet default-3zone --policy air-gap-ctf \
+    --box admin-wazuh --box vuln-box:count=5 \
+    --catalog ../range42-catalog -o scenarios/
+
+# or regenerate from a saved composition (written into every scenario)
+r42playbooks new my_lab --spec scenarios/my_lab/scenario.r42.yml \
+    --catalog ../range42-catalog -o scenarios/
+```
+
+## TUI
+
+```bash
+r42playbooks-tui ../range42-catalog
+```
+
+Pick a name, subnet layout, and network policy; add boxes (with a count); preview the
+allocation; generate.
+
+## Library (`import r42playbooks`)
+
+The stable surface is re-exported at the package root so a downstream tool
+(`r42deploy`/`r42runtime`, the range42 deployment CLI/TUI) can drive generation by import alone:
+
+```python
+import r42playbooks as r
+
+catalog = r.load_catalog("/path/to/range42-catalog")
+spec = r.load_spec("scenario.r42.yml")          # or r.ScenarioSpec.model_validate({...})
+
+problems = r.validate_refs(spec, catalog)        # typo guard — [] means every ref resolves
+if not problems:
+    root = r.render_scenario(spec, catalog=catalog, dest="scenarios/")
+    print(f"generated {root}")
+```
+
+Everything raises the `r42playbooks.core.errors` hierarchy (`TopologyError` and subclasses) —
+never a framework type. Frozen entry points: `load_catalog`, `list_roles`, `list_containers`,
+`validate_refs`, `load_spec`, `allocate`, `render_scenario(spec, *, catalog, dest, reserved=None)`.
+
+## What gets generated
+
+```
+scenarios/<name>/
+  scenario.r42.yml              # the composition (re-runnable)
+  main.yml / main_vms_only.yml  # import skeleton (only the emitted sections)
+  01_init_proxmox/templates/    # 9xxx Proxmox template creation (vendored, verbatim)
+  NN_<section>/                 # 02_admin / 03_student / 04_ctf, per composed box role
+    _main.yml                   # stage imports + per-VM global_* overrides
+    stage_00/<vm>.yml           # clone Proxmox template -> create VM
+    stage_01/<vm>.yml           # roles: [<catalog role NAMES>]  + <vm>.devkit/
+  manifest/scenario_vms.json    # allocated vm_id / ip (octet rule, _reserved.json aware)
+  templates/                    # ansible-inventory.j2, ssh-config.j2, ansible-vars.yml, vault-example.yml
+  <name>.setup.sh / .delete_all.sh / reset scripts
+```
+
+`secrets/` is **not** generated — it is a deploy-time symlink created by `range42-context use`.
+
+## Develop
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+.venv/bin/python -m pytest -q
+```
+
+See [`docs/r42playbooks-plan.md`](../docs/r42playbooks-plan.md) for the full build plan and status.
+
+GPL-3.0.

r42playbooks/__init__.py

@@ -0,0 +1,61 @@
+"""r42playbooks — range42 scenario generator.
+
+Lists composable ``range42-catalog`` modules, lets a user compose a lab (flags,
+a ``scenario.r42.yml`` spec, the CLI, or the TUI), and generates a real
+``scenarios/<name>/`` directory in the existing demo_lab format — deployable
+through the normal range42 flow with no changes elsewhere.
+
+The pure core (``r42playbooks.core``) is framework-agnostic; the stable surface
+(``r42playbooks.api``) is re-exported here so a downstream tool can drive
+generation by import alone::
+
+    import r42playbooks as r
+
+    catalog = r.load_catalog("/path/to/range42-catalog")
+    spec = r.load_spec("scenario.r42.yml")          # or r.ScenarioSpec.model_validate(...)
+    if not r.validate_refs(spec, catalog):
+        root = r.render_scenario(spec, catalog=catalog, dest="scenarios/")
+
+Everything raises the ``r42playbooks.core.errors`` hierarchy — never a framework
+type. CLI/TUI deps are optional extras (``pip install r42playbooks[cli]``, ``[tui]``).
+"""
+
+from r42playbooks.api import (
+    Allocation,
+    Catalog,
+    ReservedIndex,
+    ScenarioExistsError,
+    ScenarioSpec,
+    allocate,
+    dump_spec_atomic,
+    list_containers,
+    list_images,
+    list_roles,
+    load_catalog,
+    load_spec,
+    render_scenario,
+    validate_refs,
+)
+from r42playbooks.core.models import Topology
+
+__all__ = [
+    # generator surface (the stable import-only contract)
+    "load_catalog",
+    "list_images",
+    "list_roles",
+    "list_containers",
+    "validate_refs",
+    "load_spec",
+    "dump_spec_atomic",
+    "allocate",
+    "render_scenario",
+    "ScenarioSpec",
+    "Allocation",
+    "Catalog",
+    "ReservedIndex",
+    "ScenarioExistsError",
+    # legacy topology model (pre-pivot, kept for back-compat)
+    "Topology",
+    "__version__",
+]
+__version__ = "0.1.0"