Skip to content

Development

Running the tests

pip install -e ".[dev]"
pytest                       # run the suite
pytest --cov --cov-report=term-missing   # with coverage (~94%)

Tests live in tests/ and mock SSH / subprocess, so they run anywhere — no cluster access needed.

Project layout

cluster-job-monitor/
  run.py                 # entry point (--once, --overview, --json, --demo, --config)
  core/collector.py      # UI-agnostic: SSH + squeue/sinfo -> Snapshot dataclasses
  mcp_server.py          # MCP wrapper exposing the capacity overview to agents
  tui/app.py             # Textual app (live loop, filters, keybindings)
  tui/render.py          # Rich renderables (shared by TUI, --once, --overview)
  tui/sample.py          # synthetic snapshot for --demo
  clusters.example.json  # config template (copy to clusters.json)

core/collector.py has no third-party dependencies and returns a Snapshot whose .to_dict() is JSON-ready — that's the seam for a future web/phone dashboard (push the dict to an authenticated endpoint and render it in a browser), without changing the collector.

Continuous integration

CI (GitHub Actions) runs the suite on Python 3.10–3.12 and reports coverage to Codecov. The coverage upload runs only on push (not on fork PRs), keeping id-token: write away from untrusted code.

Building these docs

This site is built with MkDocs and the Material theme.

pip install -r docs-requirements.txt
mkdocs serve            # live preview at http://127.0.0.1:8000
mkdocs build --strict   # what CI runs; fails on broken links/nav

On every push to main, the docs.yml workflow builds the site with --strict and deploys it to GitHub Pages.