runspec-playbook 0.1.0__tar.gz

runspec_playbook-0.1.0/.gitignore

@@ -0,0 +1,61 @@
+# Python
+__pycache__/
+*.py[cod]
+*.pyo
+*.pyd
+.Python
+*.egg
+*.egg-info/
+dist/
+build/
+.eggs/
+.venv/
+venv/
+env/
+.env
+pip-wheel-metadata/
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+htmlcov/
+.coverage
+coverage.xml
+*.cover
+
+# Node
+node_modules/
+dist/
+*.js.map
+.npm
+
+# Go
+*.exe
+*.test
+*.out
+vendor/
+
+# IDE
+.idea/
+.vscode/
+*.iml
+*.iws
+*.ipr
+.DS_Store
+Thumbs.db
+
+# Docs
+site/
+
+# Misc
+*.log
+*.tmp
+
+# External reference repos (cloned locally, not committed)
+chainlit-docs/
+.chainlit/
+
+# Claude Code local config (machine-specific)
+.claude/launch.json
+
+# Stray committed test venv (removed from tracking)
+.venv-test/

runspec_playbook-0.1.0/CHANGELOG.md

@@ -0,0 +1,28 @@
+# runspec-playbook Changelog
+
+## [0.1.0] — 2026-06-30
+
+Initial release.
+
+One runnable, **`run-playbook`** (confirm), that deploys a Python package by
+running a **bundled Ansible playbook locally** on the target host:
+
+- The runspec-console reaches the host over its own SSH connection (the host
+  from `runspec_hosts.toml`) and invokes `run-playbook` there. The playbook runs
+  against `localhost` (`ansible_connection=local`), so **Ansible uses no SSH of
+  its own** — the `ansible-pull` pattern, driven by the console instead of cron.
+- Arguments: positional `package` (supports `name[extras]`) and `version`
+  (composed into `name[extras]==version`), a `playbook` choice over the bundled
+  playbooks, `--check` (Ansible check-mode dry run), repeatable `--extra-var
+  key=value`, `--tags`/`--skip-tags`, and `-v/--verbosity`.
+- Secrets (Nexus credentials, etc.) are passed as **environment variables**
+  injected by the console from the OS keychain — never packaged, never on the
+  command line, never in the audit log. The playbook reads them with
+  `lookup('env', 'NAME')`.
+- Driven by `ansible-runner` (the programmatic runner AWX/AAP use): returns
+  structured JSON (`status`, `rc`, `changed`, per-result `stats`) into the
+  console audit record.
+
+Built to be copied into a private corporate package: depend on it (or vendor
+the wrapper), drop your own per-host playbooks under `runspec_playbook/playbooks/`,
+and publish to your internal index. See `docs/design/console-ansible-deploy.md`.

runspec_playbook-0.1.0/PKG-INFO

@@ -0,0 +1,11 @@
+Metadata-Version: 2.4
+Name: runspec-playbook
+Version: 0.1.0
+Summary: Run bundled Ansible playbooks locally on a host the runspec-console is already connected to — no Ansible SSH, one host list (runspec_hosts.toml)
+Requires-Python: >=3.10
+Requires-Dist: ansible-core>=2.16
+Requires-Dist: ansible-runner>=2.3
+Requires-Dist: runspec>=0.38.0
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff==0.15.20; extra == 'dev'

runspec_playbook-0.1.0/README.md

@@ -0,0 +1,106 @@
+# runspec-playbook
+
+Run **bundled Ansible playbooks locally** on a host the runspec-console is
+already connected to — no second SSH stack, one host list.
+
+```
+runspec-console ──SSH──▶ host ──▶ run-playbook ──▶ ansible-runner (connection: local) ──▶ your playbook
+        (runspec_hosts.toml)                                          (acts on localhost — no SSH)
+```
+
+This is the `ansible-pull` pattern, driven by the console instead of cron. The
+console reaches each host over its own SSH connection and runs `run-playbook`
+there; Ansible then executes the playbook against `localhost`, so it opens no
+SSH of its own. Everything the console already owns per host keeps applying —
+connection, credentials, denylist, audit — while Ansible supplies the playbook
+richness (idempotent modules, handlers, templates, `become:`, `--check`).
+
+> **When this fits:** your playbooks are **per-host** (provisioning/config of
+> the box they run on). Local execution means each host only knows about
+> itself, so anything that coordinates *across* hosts — `delegate_to`,
+> `run_once`, reading another host's `hostvars`, `serial:` rolling deploys —
+> needs a real Ansible control node and is out of scope here.
+
+**Deployment is the worked example, not the limit.** The mechanism runs *any*
+per-host playbook — patching, config enforcement, an audit/report pass, a
+restart — and the shipped `run-playbook` runnable is just the deploy-shaped one
+(package + version). Add a `patch.yml` / `audit.yml` under `playbooks/` and a
+matching runnable (or a generic playbook-name + extra-vars runnable) the same
+way; see "Making it your own" below.
+
+## The runnable
+
+| Arg | | Description |
+|---|---|---|
+| `package` | positional 1 | Package to deploy; supports extras, e.g. `myapp` or `myapp[postgres,redis]`. |
+| `version` | positional 2 | Exact version; composed into `<package>==<version>`. |
+| `--playbook` | choice | Which bundled playbook to run (default `deploy`). |
+| `--check` / `-C` | flag | Dry run — Ansible check mode (report, don't apply). |
+| `--extra-var k=v` | repeatable | Extra Ansible variables, merged after the `deploy_*` vars. |
+| `--tags` / `--skip-tags` | str | Comma-separated Ansible tag filters. |
+| `--verbosity` / `-v` | int 0–4 | Ansible verbosity. |
+
+```bash
+run-playbook myapp 1.4.2
+run-playbook 'myapp[postgres]' 1.4.2 --check
+run-playbook myapp 1.4.2 --extra-var venv_path=/opt/myapp/venv -v
+```
+
+The runnable always passes these variables to the playbook: `deploy_package`,
+`deploy_version`, `deploy_package_spec`. It returns JSON
+(`status`, `rc`, `changed`, `stats`) — and follows the Ansible `changed`
+convention so it reads cleanly in the console history/analytics.
+
+## Secrets
+
+**Do not package a `.env` of secrets.** A wheel/sdist on your index is readable
+by anyone with read access, package data is not encrypted, and it would land on
+every host's disk in `site-packages`. Bake only **non-secret** config (an index
+host, a default venv path) into a playbook variable.
+
+Instead use the console's existing **Credentials → env var** channel. Secrets
+live in the OS keychain (Windows Credential Manager / macOS Keychain / Secret
+Service); only metadata is stored on disk. At run time the console injects them
+as plain environment variables derived from the credential's label + kind, and
+this runnable forwards the environment to the playbook. Read them in tasks with
+`lookup('env', 'NAME')`.
+
+Name the credential so the convention yields the names your playbook expects:
+
+| Credential label | Kind | Env vars injected |
+|---|---|---|
+| `Nexus` | token | `NEXUS_TOKEN`, `NEXUS_PAT` |
+| `Nexus` | userpass | `NEXUS_USERNAME`, `NEXUS_USER`, `NEXUS_PASSWORD` |
+| `Deploy Key` | token | `DEPLOY_KEY_TOKEN`, `DEPLOY_KEY_PAT` |
+
+Select one or more credentials in the run dialog (the **Forms** tab) — these are
+the GitLab CI/CD variables you have today, now sourced from the keychain instead
+of a CI settings page. For an unattended run, a **schedule** with
+`action = "runnable"` runs `run-playbook` with no operator present (scheduling
+*is* the authorization); in-scope credentials auto-apply on the agent path.
+
+> A file-based secret is only acceptable if it is **Ansible Vault** (encrypted)
+> — and the vault password itself should still arrive via an injected env var
+> (e.g. `ANSIBLE_VAULT_PASSWORD_FILE` pointing at a tiny script that echoes it),
+> not be packaged.
+
+## Making it your own
+
+This package is a reference. To adopt it:
+
+1. Replace `runspec_playbook/playbooks/deploy.yml` with your existing per-host
+   playbooks (keep `hosts: all` — the inventory is `localhost`). Vendor any
+   required collections under a `collections/` dir for an index-only / air-gapped
+   install rather than fetching from Galaxy at run time.
+2. Rename the package and publish it to your internal index from your existing
+   GitLab CI — CI keeps building and publishing; the console just deploys.
+3. Install it (and `ansible-core`) into the same venv as runspec on each host
+   (e.g. via the console's `install-into-venv` runnable), so `run-playbook`
+   surfaces in the console alongside your other runnables.
+
+See `docs/design/console-ansible-deploy.md` for the full design and rationale.
+
+## Requirements
+
+`runspec`, `ansible-core`, and `ansible-runner` on the host. Zero of these need
+to be reachable at run time once installed.

runspec_playbook-0.1.0/pyproject.toml

@@ -0,0 +1,37 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "runspec-playbook"
+version = "0.1.0"
+requires-python = ">=3.10"
+description = "Run bundled Ansible playbooks locally on a host the runspec-console is already connected to — no Ansible SSH, one host list (runspec_hosts.toml)"
+dependencies = [
+    "runspec>=0.38.0",
+    "ansible-core>=2.16",
+    "ansible-runner>=2.3",
+]
+
+[project.scripts]
+run-playbook = "runspec_playbook.run_playbook:main_run_playbook"
+
+[project.optional-dependencies]
+dev = [
+    "ruff==0.15.20",
+    "pytest>=8.0",
+]
+
+# Ship the runnable interface and the bundled playbooks as package data.
+[tool.hatch.build.targets.wheel]
+packages = ["runspec_playbook"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 200
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "UP", "B", "SIM"]

runspec_playbook-0.1.0/runspec_playbook/__init__.py

@@ -0,0 +1,24 @@
+"""runspec-playbook — run bundled Ansible playbooks locally, driven by the console.
+
+Public helpers are re-exported so a private corporate wrapper can import the
+pure logic (and bake in its own index/venv conventions) without going through
+the CLI:
+
+    from runspec_playbook import compose_package_spec, run_ansible
+"""
+
+from runspec_playbook.run_playbook import (
+    compose_package_spec,
+    main_run_playbook,
+    parse_extra_vars,
+    run_ansible,
+    summarize_stats,
+)
+
+__all__ = [
+    "compose_package_spec",
+    "main_run_playbook",
+    "parse_extra_vars",
+    "run_ansible",
+    "summarize_stats",
+]

runspec_playbook-0.1.0/runspec_playbook/playbooks/deploy.yml

@@ -0,0 +1,56 @@
+---
+# Example deploy playbook for runspec-playbook.
+#
+# Runs LOCALLY on the target host: the inventory pins ansible_connection=local,
+# so Ansible uses NO SSH of its own. The runspec-console already reached this
+# host (over its own SSH, from runspec_hosts.toml) and invoked the run-playbook
+# runnable here; this playbook then acts on localhost.
+#
+# Variables provided automatically by the run-playbook runnable:
+#   deploy_package        e.g. "myapp" or "myapp[postgres]"
+#   deploy_version        e.g. "1.4.2"
+#   deploy_package_spec   e.g. "myapp[postgres]==1.4.2"
+# Override anything else with --extra-var key=value.
+#
+# Secrets (Nexus credentials, etc.) arrive as ENVIRONMENT VARIABLES injected by
+# the runspec-console from the OS keychain at run time — never packaged, never
+# on the command line, never in the audit log. Read them with
+# lookup('env', 'NAME'). Name the console credential so the label→env-var
+# convention yields the names this playbook expects (a token credential
+# labelled "Nexus" → NEXUS_TOKEN/NEXUS_PAT; a userpass "Nexus" → NEXUS_USERNAME).
+#
+# Replace the body below with your existing per-host playbook — the only
+# requirement for local execution is `hosts: all` (the inventory is localhost).
+- name: Deploy {{ deploy_package_spec }} locally
+  hosts: all
+  gather_facts: true
+  vars:
+    # Strip any [extras] suffix to derive a plain application name.
+    app_name: "{{ deploy_package | regex_replace('\\[.*$', '') }}"
+    venv_path: "/opt/{{ app_name }}/venv"
+  tasks:
+    - name: Ensure the venv parent directory exists
+      become: true
+      ansible.builtin.file:
+        path: "{{ venv_path | dirname }}"
+        state: directory
+        mode: "0755"
+
+    - name: Install {{ deploy_package_spec }} into {{ venv_path }} (idempotent)
+      become: true
+      ansible.builtin.pip:
+        name: "{{ deploy_package_spec }}"
+        state: present
+        virtualenv: "{{ venv_path }}"
+        virtualenv_command: python3 -m venv
+      environment:
+        # Point pip at Nexus using the injected credential env vars. If no
+        # credential is present, fall back to an already-exported PIP_INDEX_URL,
+        # or omit to use the system default index.
+        PIP_INDEX_URL: >-
+          {{
+            ('https://' ~ lookup('env', 'NEXUS_USERNAME') ~ ':' ~ lookup('env', 'NEXUS_TOKEN')
+             ~ '@nexus.example.com/repository/pypi/simple')
+            if lookup('env', 'NEXUS_TOKEN')
+            else (lookup('env', 'PIP_INDEX_URL') | default(omit, true))
+          }}

runspec_playbook-0.1.0/runspec_playbook/run_playbook.py

@@ -0,0 +1,178 @@
+"""run-playbook — deploy a package by running a bundled Ansible playbook locally.
+
+The runspec-console reaches the target host over its own SSH connection (the
+host from ``runspec_hosts.toml``) and runs this runnable there. The playbook is
+then executed against ``localhost`` with ``ansible_connection=local``, so
+Ansible itself opens no SSH connection. Per-host concerns the console already
+owns — connection, credentials (injected as env vars), denylist, audit — keep
+applying; Ansible supplies the playbook richness (idempotent modules, handlers,
+templates, ``become:``, ``--check``).
+
+The pure helpers (``compose_package_spec``/``parse_extra_vars``/
+``summarize_stats``) are factored out so they unit-test without Ansible, and the
+single Ansible call goes through ``run_ansible`` so tests can substitute it.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import runspec as rs
+
+
+def compose_package_spec(package: str, version: str) -> str:
+    """Combine a package (optionally with extras) and a pinned version.
+
+    ``"myapp"`` + ``"1.4.2"`` → ``"myapp==1.4.2"``; extras are preserved:
+    ``"myapp[postgres]"`` + ``"1.4.2"`` → ``"myapp[postgres]==1.4.2"``.
+    """
+    package = package.strip()
+    version = version.strip()
+    if not package:
+        raise ValueError("package is required")
+    if not version:
+        return package
+    return f"{package}=={version}"
+
+
+def parse_extra_vars(items: list[str]) -> dict[str, str]:
+    """Parse ``--extra-var key=value`` items into a dict (split on the first =)."""
+    out: dict[str, str] = {}
+    for item in items:
+        if "=" not in item:
+            raise ValueError(f"--extra-var must be key=value, got: {item!r}")
+        key, value = item.split("=", 1)
+        out[key.strip()] = value
+    return out
+
+
+def summarize_stats(stats: dict[str, Any]) -> dict[str, int]:
+    """Reduce ansible-runner's per-host stats to friendly fleet-wide totals."""
+
+    def total(key: str) -> int:
+        section = stats.get(key) or {}
+        return sum(section.values()) if isinstance(section, dict) else 0
+
+    return {
+        "ok": total("ok"),
+        "changed": total("changed"),
+        "failed": total("failures"),
+        "unreachable": total("dark"),
+        "skipped": total("skipped"),
+    }
+
+
+def run_ansible(
+    playbook_name: str,
+    extravars: dict[str, Any],
+    *,
+    check: bool,
+    verbosity: int,
+    tags: str | None,
+    skip_tags: str | None,
+    envvars: dict[str, str],
+) -> dict[str, Any]:
+    """Run a bundled playbook against localhost via ansible-runner.
+
+    The bundled ``playbooks/`` tree is copied into a throwaway private data dir
+    so artefacts never litter the host. ``envvars`` is forwarded verbatim so the
+    console-injected secrets reach the playbook (read there with
+    ``lookup('env', 'NAME')``); this function never logs them.
+    """
+    import shutil
+    from importlib.resources import as_file, files
+
+    import ansible_runner
+
+    source = files("runspec_playbook") / "playbooks"
+    with as_file(source) as playbooks_dir, tempfile.TemporaryDirectory(prefix="runspec-playbook-") as data_dir:
+        project = Path(data_dir) / "project"
+        shutil.copytree(playbooks_dir, project)
+        if not (project / f"{playbook_name}.yml").is_file():
+            raise FileNotFoundError(f"bundled playbook not found: {playbook_name}.yml")
+
+        kwargs: dict[str, Any] = {
+            "private_data_dir": data_dir,
+            "playbook": f"{playbook_name}.yml",
+            # One inline host pinned to the local connection — no SSH, no remote inventory.
+            "inventory": {"all": {"hosts": {"localhost": {"ansible_connection": "local"}}}},
+            "extravars": extravars,
+            "envvars": envvars,
+            "verbosity": verbosity,
+            "quiet": True,
+        }
+        if tags:
+            kwargs["tags"] = tags
+        if skip_tags:
+            kwargs["skip_tags"] = skip_tags
+        if check:
+            kwargs["cmdline"] = "--check"
+
+        runner = ansible_runner.run(**kwargs)
+        return {"status": runner.status, "rc": runner.rc, "stats": runner.stats or {}}
+
+
+def main_run_playbook() -> None:
+    spec = rs.parse("run-playbook")
+    package = str(spec.package.value)
+    version = str(spec.version.value)
+    playbook_name = str(spec.playbook.value)
+    check = bool(spec.check.value)
+    verbosity = int(spec.verbosity.value)
+    tags = spec.tags.value
+    skip_tags = spec.skip_tags.value
+    extra_items = spec.extra_var.value or []
+
+    try:
+        package_spec = compose_package_spec(package, version)
+        extravars: dict[str, Any] = {
+            "deploy_package": package,
+            "deploy_version": version,
+            "deploy_package_spec": package_spec,
+            **parse_extra_vars(extra_items),
+        }
+    except ValueError as exc:
+        print(json.dumps({"error": str(exc)}))
+        sys.exit(2)
+
+    try:
+        result = run_ansible(
+            playbook_name,
+            extravars,
+            check=check,
+            verbosity=verbosity,
+            tags=tags,
+            skip_tags=skip_tags,
+            # The console already curated this environment (it added the selected
+            # credentials' env vars); forward it so the playbook can read them.
+            envvars=dict(os.environ),
+        )
+    except ModuleNotFoundError as exc:
+        print(json.dumps({"error": f"ansible-runner is not installed ({exc}). Install ansible-core and ansible-runner on this host."}))
+        sys.exit(1)
+    except FileNotFoundError as exc:
+        print(json.dumps({"error": str(exc)}))
+        sys.exit(1)
+
+    summary = summarize_stats(result.get("stats") or {})
+    status = result.get("status")
+    rc = int(result.get("rc") or 0)
+    print(
+        json.dumps(
+            {
+                "package": package_spec,
+                "playbook": playbook_name,
+                "check": check,
+                "status": status,
+                "rc": rc,
+                "changed": summary["changed"] > 0,
+                "stats": summary,
+            }
+        )
+    )
+    sys.exit(0 if status == "successful" else (rc or 1))

runspec_playbook-0.1.0/runspec_playbook/runspec.toml

@@ -0,0 +1,75 @@
+[config]
+autonomy-default = "confirm"
+
+[config.logging]
+# Per-invocation audit files — one {runnable}.{utc-ts}.{run_id}.log per deploy.
+# Multi-writer safe for shared venvs (view/compact/prune with `runspec logs`),
+# and the data the runspec-console history/analytics tabs read.
+store = "per-run"
+
+# ── Deploy a package via a bundled Ansible playbook ──────────────────────────────
+#
+# This runnable runs ENTIRELY ON THE LOCAL HOST. The runspec-console reaches the
+# host over its own SSH connection (the host listed in runspec_hosts.toml) and
+# invokes this runnable there; the playbook is then executed against localhost
+# (inventory pins ansible_connection=local), so Ansible uses NO SSH of its own.
+# This is the `ansible-pull` pattern driven by the console instead of cron.
+#
+# Secrets (e.g. Nexus credentials) are passed as ENVIRONMENT VARIABLES injected
+# by the console from the OS keychain — never packaged, never on the command
+# line, never in the audit log. See README.md → "Secrets".
+
+[run-playbook]
+description = "Deploy a Python package by running a bundled Ansible playbook locally on this host. Installs <package>[extras]==<version> from the configured index and runs the playbook's steps. Uses no Ansible SSH — the console already reached this host; the playbook acts on localhost (connection: local)."
+autonomy    = "confirm"
+output      = "json"
+examples    = [
+    "run-playbook myapp 1.4.2",
+    "run-playbook 'myapp[postgres]' 1.4.2 --check",
+    { cmd = "run-playbook myapp 1.4.2 --extra-var venv_path=/opt/myapp/venv -v", description = "Override the target venv and show task output" },
+]
+
+[run-playbook.args.package]
+type        = "str"
+position    = 1
+description = "Package to deploy. Supports extras, e.g. 'myapp' or 'myapp[postgres,redis]'."
+
+[run-playbook.args.version]
+type        = "str"
+position    = 2
+description = "Exact version to install (e.g. '1.4.2'). Pinned — composed into '<package>==<version>'."
+
+[run-playbook.args.playbook]
+type        = "choice"
+options     = ["deploy"]
+default     = "deploy"
+description = "Which bundled playbook to run (one of the playbooks shipped inside this package)."
+
+[run-playbook.args.check]
+type        = "flag"
+short       = "-C"
+default     = false
+description = "Dry run: execute the playbook in Ansible check mode — report what would change without applying it."
+
+[run-playbook.args.extra-var]
+type        = "str"
+multiple    = true
+required    = false
+description = "Extra Ansible variable as key=value (repeatable, e.g. --extra-var venv_path=/opt/app/venv). Merged into extra-vars after the deploy_* variables."
+
+[run-playbook.args.tags]
+type        = "str"
+required    = false
+description = "Comma-separated Ansible --tags: run only tasks with these tags."
+
+[run-playbook.args.skip-tags]
+type        = "str"
+required    = false
+description = "Comma-separated Ansible --skip-tags: skip tasks with these tags."
+
+[run-playbook.args.verbosity]
+type        = "int"
+short       = "-v"
+default     = 0
+range       = [0, 4]
+description = "Ansible verbosity, 0–4 (like -v … -vvvv)."

runspec_playbook-0.1.0/tests/test_run_playbook.py

@@ -0,0 +1,120 @@
+"""Tests for run-playbook.
+
+The pure helpers are tested directly. The end-to-end path is exercised
+in-process with a stubbed ``run_ansible`` (so no Ansible install is needed):
+``rs.parse`` still reads the bundled runspec.toml because the finder walks up
+from the calling module's directory.
+"""
+
+import json
+
+import pytest
+
+from runspec_playbook import run_playbook
+
+# ── pure helpers ──────────────────────────────────────────────────────────────
+
+
+def test_compose_package_spec_plain() -> None:
+    assert run_playbook.compose_package_spec("myapp", "1.4.2") == "myapp==1.4.2"
+
+
+def test_compose_package_spec_preserves_extras() -> None:
+    assert run_playbook.compose_package_spec("myapp[postgres,redis]", "1.4.2") == "myapp[postgres,redis]==1.4.2"
+
+
+def test_compose_package_spec_requires_package() -> None:
+    with pytest.raises(ValueError):
+        run_playbook.compose_package_spec("", "1.0.0")
+
+
+def test_parse_extra_vars_splits_on_first_equals() -> None:
+    assert run_playbook.parse_extra_vars(["venv_path=/opt/x/venv", "url=https://h/p?a=b"]) == {
+        "venv_path": "/opt/x/venv",
+        "url": "https://h/p?a=b",
+    }
+
+
+def test_parse_extra_vars_rejects_bare_token() -> None:
+    with pytest.raises(ValueError):
+        run_playbook.parse_extra_vars(["novalue"])
+
+
+def test_summarize_stats_totals_across_hosts() -> None:
+    stats = {
+        "ok": {"localhost": 3},
+        "changed": {"localhost": 2},
+        "failures": {"localhost": 1},
+        "dark": {},
+    }
+    assert run_playbook.summarize_stats(stats) == {
+        "ok": 3,
+        "changed": 2,
+        "failed": 1,
+        "unreachable": 0,
+        "skipped": 0,
+    }
+
+
+# ── end-to-end (stubbed Ansible) ────────────────────────────────────────────────
+
+
+def _stub_runner(monkeypatch, captured, *, status="successful", rc=0, stats=None):
+    def fake_run_ansible(playbook_name, extravars, *, check, verbosity, tags, skip_tags, envvars):
+        captured.update(
+            playbook_name=playbook_name,
+            extravars=extravars,
+            check=check,
+            verbosity=verbosity,
+            tags=tags,
+            skip_tags=skip_tags,
+        )
+        return {"status": status, "rc": rc, "stats": stats if stats is not None else {"changed": {"localhost": 1}, "ok": {"localhost": 2}}}
+
+    monkeypatch.setattr(run_playbook, "run_ansible", fake_run_ansible)
+
+
+def test_main_builds_spec_and_reports_change(monkeypatch, capsys) -> None:
+    captured: dict = {}
+    _stub_runner(monkeypatch, captured)
+    monkeypatch.setattr("sys.argv", ["run-playbook", "myapp[pg]", "1.2.3", "--check", "--extra-var", "venv_path=/opt/x/venv"])
+
+    with pytest.raises(SystemExit) as exc:
+        run_playbook.main_run_playbook()
+    assert exc.value.code == 0
+
+    out = json.loads(capsys.readouterr().out)
+    assert out["package"] == "myapp[pg]==1.2.3"
+    assert out["changed"] is True
+    assert out["check"] is True
+    assert out["status"] == "successful"
+    assert out["stats"]["changed"] == 1
+
+    assert captured["extravars"]["deploy_package_spec"] == "myapp[pg]==1.2.3"
+    assert captured["extravars"]["deploy_package"] == "myapp[pg]"
+    assert captured["extravars"]["venv_path"] == "/opt/x/venv"
+    assert captured["check"] is True
+
+
+def test_main_propagates_failure_exit_code(monkeypatch, capsys) -> None:
+    captured: dict = {}
+    _stub_runner(monkeypatch, captured, status="failed", rc=2, stats={"failures": {"localhost": 1}})
+    monkeypatch.setattr("sys.argv", ["run-playbook", "myapp", "9.9.9"])
+
+    with pytest.raises(SystemExit) as exc:
+        run_playbook.main_run_playbook()
+    assert exc.value.code == 2
+
+    out = json.loads(capsys.readouterr().out)
+    assert out["status"] == "failed"
+    assert out["changed"] is False
+    assert out["stats"]["failed"] == 1
+
+
+def test_main_reports_bad_extra_var(monkeypatch, capsys) -> None:
+    monkeypatch.setattr("sys.argv", ["run-playbook", "myapp", "1.0.0", "--extra-var", "oops"])
+    with pytest.raises(SystemExit) as exc:
+        run_playbook.main_run_playbook()
+    assert exc.value.code == 2
+    out = json.loads(capsys.readouterr().out)
+    assert "key=value" in out["error"]