Merge pull request #28 from miciav/feature/runner-controller-ui

Feature/runner controller UI

Author: miciav

.flake8

@@ -0,0 +1,31 @@
+[flake8]
+max-line-length = 88
+extend-ignore = E203, W503
+
+banned-modules =
+    lb_controller.ansible = Use lb_controller.api instead.
+    lb_controller.ansible.* = Use lb_controller.api instead.
+    lb_controller.ansible_executor = Use lb_controller.api instead.
+    lb_controller.controller = Use lb_controller.api instead.
+    lb_controller.controller_playbooks = Use lb_controller.api instead.
+    lb_controller.controller_runner = Use lb_controller.api instead.
+    lb_controller.controller_state = Use lb_controller.api instead.
+    lb_controller.controller_stop = Use lb_controller.api instead.
+    lb_controller.contracts = Use lb_controller.api instead.
+    lb_controller.interrupts = Use lb_controller.api instead.
+    lb_controller.journal = Use lb_controller.api instead.
+    lb_controller.journal_sync = Use lb_controller.api instead.
+    lb_controller.lifecycle = Use lb_controller.api instead.
+    lb_controller.paths = Use lb_controller.api instead.
+    lb_controller.pending = Use lb_controller.api instead.
+    lb_controller.stop_coordinator = Use lb_controller.api instead.
+    lb_controller.types = Use lb_controller.api instead.
+    lb_controller.services = Use lb_controller.api instead.
+    lb_controller.services.* = Use lb_controller.api instead.
+
+per-file-ignores =
+    lb_controller/*:I251
+    tests/unit/lb_controller/*:I251
+    tests/unit/common/test_lb_events_callback.py:I251
+    tests/unit/common/test_plugin_installer.py:I251
+    tests/e2e/test_plugin_git_install_e2e.py:I251

.github/social-preview.png

@@ -8,7 +8,7 @@ jobs:
   diagrams:
     runs-on: ubuntu-latest
     permissions:
-      contents: read
+      contents: write
       actions: write
     steps:
       - name: Checkout
@@ -31,7 +31,7 @@ jobs:
       - name: Generate diagrams
         run: |
           mkdir -p docs/diagrams
-          pyreverse -o png -p linux-benchmark lb_runner lb_controller lb_ui -S
+          pyreverse -o png -p linux-benchmark lb_runner lb_controller lb_app lb_ui lb_analytics lb_provisioner -S
           # pyreverse naming differs across pylint versions; glob and normalize.
           shopt -s nullglob
           classes_png=(classes*.png)
@@ -43,7 +43,7 @@ jobs:
           fi
           mv "${classes_png[0]}" docs/diagrams/classes.png
           mv "${packages_png[0]}" docs/diagrams/packages.png
-          pyreverse -o puml -p linux-benchmark lb_runner lb_controller lb_ui -S
+          pyreverse -o puml -p linux-benchmark lb_runner lb_controller lb_app lb_ui lb_analytics lb_provisioner -S
           classes_puml=(classes*.puml)
           packages_puml=(packages*.puml)
           if [ ${#classes_puml[@]} -eq 0 ] || [ ${#packages_puml[@]} -eq 0 ]; then
@@ -60,3 +60,10 @@ jobs:
           name: diagrams-${{ github.ref_name }}
           path: docs/diagrams
           if-no-files-found: error
+
+      - name: Attach diagrams to release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: |
+            docs/diagrams/*.png
+            docs/diagrams/*.puml

.github/workflows/diagrams.yml

@@ -22,7 +22,7 @@ jobs:
         with:
           python-version: "3.13"
       - name: Install deps
-        run: pip install -e ".[docs]"
+        run: pip install -e ".[docs,controller]"
       - name: Build site
         run: mkdocs build --strict
       - uses: actions/upload-pages-artifact@v3
@@ -36,4 +36,4 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
     steps:
       - id: deployment
-        uses: actions/deploy-pages@v4
+        uses: actions/deploy-pages@v4

.github/workflows/pages.yml

@@ -1,8 +1,10 @@
 # Repository Guidelines
 
 ## Project Structure & Module Organization
-- Core configuration now lives under `lb_runner/` (`benchmark_config.py`).
-- Runner code is under `lb_runner/`; controller under `lb_controller/`; UI under `lb_ui/`.
+- Core configuration lives under `lb_runner/` (`benchmark_config.py`).
+- Runner code is under `lb_runner/`; controller under `lb_controller/`; app-layer API under `lb_app/`; UI under `lb_ui/`.
+- Reporting and post-processing live under `lb_analytics/`; shared utilities in `lb_common/`; provisioning helpers in `lb_provisioner/`.
+- Use the stable APIs from `lb_runner.api`, `lb_controller.api`, and `lb_app.api` instead of importing deep modules.
 - Collectors sit in `lb_runner/metric_collectors/` (PSUtil, CLI, perf, eBPF) and workload plugins in `lb_runner/plugins/` (stress-ng, dd, fio, hpl), each with base abstractions plus concrete implementations.
 - Tests are under `tests/`; sample usage is in `example.py`. Output artifacts are written to `benchmark_results/`, `reports/`, and `data_exports/` (these may be absent until generated).
 
@@ -14,6 +16,7 @@
 ## Coding Style & Naming Conventions
 - Python 3.13, formatted with Black (line length 88) and linted with Flake8; type checking is strict via MyPy (no untyped defs, no implicit Optional). Pydocstyle runs with D100/D104/D203/D213 ignored; keep concise docstrings for public APIs.
 - Use `snake_case` for functions/variables/modules, `PascalCase` for classes, and `UPPER_SNAKE_CASE` for constants. Prefer well-named dataclasses for configs and keep CLI/tool shelling confined to collectors/generators.
+- Logging policy: configure logging via `lb_common.configure_logging()` in entrypoints. `lb_runner` does not auto-configure logging; callers should opt in to keep `LB_EVENT` output on stdout clean.
 
 ## Testing Guidelines
 - Framework: pytest; tests live in `tests/` with files `test_*.py`, classes `Test*`, functions `test_*`. Favor unit tests for collectors/generators with fake command outputs and small integration tests that exercise the controller.

AGENTS.md

@@ -1,67 +1,80 @@
-CLI Reference
-=============
+# CLI Reference
 
-> Note: the user-facing CLI lives in `lb_ui` (invoke via `lb` or `python -m lb_ui.cli`). Runner/controller packages no longer import the UI or expose separate entrypoints.
+> Note: the user-facing CLI lives in `lb_ui` (invoke via `lb` or `python -m lb_ui.cli`). Runner/controller packages do not expose separate entrypoints.
+
+## Setup
 
-Setup
------
 - Install in a venv: `uv venv && uv pip install -e .`
 - Make `lb` globally available (optional): `uv tool install -e .`
-- Enable shell completion: `lb --install-completion` (bash/zsh/fish) and restart your shell.
+- Enable shell completion: `lb --install-completion` (bash/zsh/fish)
+
+## Global flags
+
+- `--headless` forces headless output (useful in CI or pipes).
+
+## Config resolution
 
-Config resolution
------------------
 Order used by commands that need a config:
+
 1. `-c/--config` flag
 2. Saved default at `~/.config/lb/config_path` (set via `lb config set-default` or `lb config init`)
 3. `./benchmark_config.json` if present
 4. Built-in defaults
 
-Top-level commands
-------------------
-- `lb plugin list|ls [--select] [--enable NAME | --disable NAME] [-c FILE] [--set-default]`  
-  Show plugins with enabled state; optionally enable/disable a workload in the config or open an interactive selector (arrows + space). (`lb plugins` remains as a compatibility alias.)
-- `lb plugin select [-c FILE] [--set-default]`  
-  Directly open the interactive selector to toggle plugins with arrows + space.
-- `lb plugin install PATH|URL [--manifest FILE] [--force] [--regen-assets/--no-regen-assets]`  
-  Install a plugin from a .py file, directory, archive (.zip/.tar.gz), or git repository URL.
-- `lb plugin uninstall NAME [--purge-config/--keep-config] [--regen-assets/--no-regen-assets]`  
-  Remove a user plugin and optionally delete its config entries.
-- `lb hosts [-c FILE]`  
-  Show remote hosts from the resolved config.
-- `lb run [TEST ...] [-c FILE] [--run-id ID] [--remote/--no-remote] [--repetitions N]`
-  Run workloads locally or remotely (auto-follows config unless overridden). Use `--repetitions` to temporarily change how many times each workload runs.
-- `lb run ... --docker [--docker-image TAG] [--docker-engine docker|podman] [--docker-no-build] [--docker-no-cache]`  
-  Build/use the container image and run the CLI inside it. Mounts the repo read-only and writes artifacts to the container’s `benchmark_results`.
-- `lb runs list [--root PATH] [-c FILE]` / `lb runs show RUN_ID [--root PATH] [-c FILE]`  
-  List past runs stored under `benchmark_results/` and inspect a single run (hosts, workloads, paths).
-- `lb analyze [RUN_ID] [--root PATH] [--kind aggregate] [--workload NAME] [--host NAME]`  
-  Run post-processing analytics on an existing run. If `RUN_ID` or selectors are omitted and you are in an interactive TTY, prompts will guide selection.
-
-Config management (`lb config ...`)
------------------------------------
+## Top-level commands
+
+- `lb run [WORKLOAD ...] [-c FILE] [--run-id ID] [--resume [latest|ID]] [--remote/--no-remote] [--repetitions N] [--intensity LEVEL] [--setup/--no-setup] [--stop-file PATH] [--debug]`
+  Run workloads remotely via Ansible. Local execution is not supported by the CLI.
+- `lb run ... --docker [--docker-engine docker|podman] [--nodes N]`
+  Dev-only: provision containers and run via Ansible (requires `.lb_dev_cli` or `LB_ENABLE_TEST_CLI=1`).
+- `lb run ... --multipass [--nodes N]`
+  Dev-only: provision Multipass VMs and run via Ansible (requires `.lb_dev_cli` or `LB_ENABLE_TEST_CLI=1`).
+- `lb runs list [--root PATH] [-c FILE]` / `lb runs show RUN_ID [--root PATH] [-c FILE]`
+  Inspect stored runs under `benchmark_results/`.
+- `lb analyze [RUN_ID] [--root PATH] [--workload NAME] [--host NAME]`
+  Run analytics on an existing run (currently `aggregate`).
+- `lb plugin ...` / `lb plugins ...`
+  Inspect and manage workload plugins.
+- `lb config ...`
+  Create and manage benchmark configuration files.
+- `lb doctor ...`
+  Run prerequisite checks.
+- `lb test multipass ...` (dev-only)
+  Helper to run integration tests.
+
+## Plugin management (`lb plugin ...`)
+
+- `lb plugin list|ls [--select] [--enable NAME | --disable NAME] [-c FILE] [--set-default]`
+- `lb plugin select [-c FILE] [--set-default]`
+- `lb plugin install PATH|URL [--manifest FILE] [--force]`
+- `lb plugin uninstall NAME [--purge-config/--keep-config] [-c FILE]`
+
+## Config management (`lb config ...`)
+
 - `lb config init [-i] [--path FILE] [--set-default/--no-set-default]`
-  Create a config (prompt for a remote host with `-i`).
 - `lb config set-repetitions N [-c FILE] [--set-default/--no-set-default]`
-  Persist the desired number of repetitions to a config file (defaults to `~/.config/lb/config.json`).
 - `lb config set-default FILE` / `lb config unset-default` / `lb config show-default`
-- `lb config edit [-p FILE]`  
-  Open the config in `$EDITOR`.
-- `lb config workloads [-c FILE]`  
-  List workloads and enabled status.
-- `lb config enable-workload NAME [-c FILE] [--set-default]`  
-  (creates if missing)
+- `lb config edit [-p FILE]`
+- `lb config workloads [-c FILE]`
+- `lb config enable-workload NAME [-c FILE] [--set-default]`
 - `lb config disable-workload NAME [-c FILE] [--set-default]`
+- `lb config select-workloads [-c FILE] [--set-default]`
+
+## Doctor checks (`lb doctor ...`)
 
-Doctor checks (`lb doctor ...`)
--------------------------------
-- `lb doctor controller` — Python deps + ansible/ansible-runner + config resolution.
-- `lb doctor local-tools` — stress-ng, fio, sysstat tools, perf (needed only for local runs).
-- `lb doctor multipass` — check presence of multipass (optional).
-- `lb doctor all` — run all checks.
+- `lb doctor controller` - Python deps + Ansible requirements
+- `lb doctor local` - local workload tools (stress-ng, fio, sysstat)
+- `lb doctor multipass` - Multipass availability
+- `lb doctor all` - run all checks
+
+## Test helpers (`lb test ...`, dev installs only)
 
-Integration helper (`lb test ...`, dev installs only)
------------------------------------------------------
 - Available when `.lb_dev_cli` exists in the project root or `LB_ENABLE_TEST_CLI=1` is set.
-- `lb test multipass [-o DIR] [--vm-count {1,2}] [--multi-workloads] [-- EXTRA_PYTEST_ARGS...]`  
-  Runs the Multipass integration test. Artifacts go to `tests/results` by default (override with `-o` or `LB_TEST_RESULTS_DIR`). `--vm-count` (or `LB_MULTIPASS_VM_COUNT`) launches 1–2 VMs. Use `--multi-workloads` to run the stress_ng + dd + fio variant. Requires multipass + ansible/ansible-runner locally.
+- `lb test multipass [-o DIR] [--vm-count {1,2}] [--multi-workloads] [-- EXTRA_PYTEST_ARGS...]`
+
+## Environment variables
+
+- `LB_ENABLE_TEST_CLI=1` enables `lb test` and provisioning flags in the CLI.
+- `LB_USER_PLUGIN_DIR` overrides the user plugin install directory.
+- `LB_STOP_FILE` sets a stop sentinel path if `--stop-file` is omitted.
+- `LB_TEST_RESULTS_DIR`, `LB_MULTIPASS_VM_COUNT` customize test helpers.

CLI.md

@@ -0,0 +1,78 @@
+# Linux Benchmark Library (linux-benchmark-lib)
+
+## Project Overview
+`linux-benchmark-lib` is a robust, configurable Python library designed for benchmarking Linux compute nodes. It supports running repeatable workloads and collecting detailed system metrics under synthetic load.
+
+### Key Features
+*   **Operation Modes:**
+    *   **Agent (Local):** Lightweight installation for target nodes.
+    *   **Controller (Remote):** Full orchestration layer using Ansible for managing remote benchmarks.
+    *   **UI/CLI:** TUI-based interaction (via `rich` and `typer`).
+*   **Metric Collection:** PSUtil, Linux CLI tools, perf events, eBPF.
+*   **Workloads:** Plugin-based system (stress-ng, dd, fio, hpl, stream). Extensible via Python entry points.
+*   **Data Handling:** Aggregation using Pandas, reporting with Matplotlib/Seaborn.
+
+## Architecture
+*   `lb_runner/`: Core execution logic, workload plugins, and metric collectors.
+    *   `local_runner.py`: Orchestrates the benchmark workflow on a single node.
+*   `lb_controller/`: Remote orchestration, Ansible integration, and result handling.
+*   `lb_ui/`: CLI and TUI layer. **Note:** Runner/Controller modules do not import UI components.
+*   `lb_analytics/`: Data aggregation and reporting logic.
+*   `benchmark_results/`: Stores raw metric data.
+*   `reports/`: Generated text reports and plots.
+
+## Development & Usage
+
+### Setup
+The project uses `uv` for dependency management.
+
+```bash
+# Install core dependencies
+uv sync
+
+# Install controller extras (Ansible, plotting)
+uv sync --extra controller
+
+# Install dev dependencies
+uv sync --all-extras --dev
+```
+
+### Key Commands (`lb`)
+The CLI entry point is `lb` (or `python -m lb_ui.cli`).
+
+*   **Run Benchmarks:**
+    *   `lb run [workload_name]` (e.g., `lb run stress_ng`)
+    *   `lb run --remote` (uses configured remote hosts)
+*   **Plugin Management:**
+    *   `lb plugin list` (show status)
+    *   `lb plugin install <url/path>`
+*   **Configuration:**
+    *   `lb config init` (initialize config)
+    *   `lb config edit` (open in editor)
+*   **Diagnostics:**
+    *   `lb doctor all` (run health checks)
+
+### Testing
+Tests are managed with `pytest` and marked for different scopes.
+
+```bash
+# Run all tests
+uv run pytest tests/
+
+# Run specific types
+uv run pytest -m unit
+uv run pytest -m integration
+uv run pytest -m tui
+```
+
+### Coding Standards
+*   **Style:** `black` (line length 88), `flake8`.
+*   **Typing:** Strict `mypy` (Python 3.12+).
+*   **Docstrings:** `pydocstyle` (subset of rules).
+*   **Conventions:** `snake_case` for functions/vars, `PascalCase` for classes. Dataclasses for configuration.
+
+## File Structure Highlights
+*   `pyproject.toml`: Dependency and build configuration.
+*   `lb_runner/benchmark_config.py`: Configuration dataclasses.
+*   `lb_runner/plugins/`: Workload plugin implementations.
+*   `lb_controller/ansible/`: Ansible playbooks and roles.