server-motd 0.1.0__tar.gz

server_motd-0.1.0/.ansible-lint

@@ -0,0 +1,5 @@
+---
+profile: production
+exclude_paths:
+  - .github/
+  - docs/

server_motd-0.1.0/.gitattributes

@@ -0,0 +1,3 @@
+# Templates the role renders onto Linux hosts must keep LF endings, even in a
+# Windows checkout with core.autocrlf (Ansible reads the working tree).
+ansible/roles/server_motd/templates/** text eol=lf

server_motd-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,149 @@
+name: CI
+
+on:
+  push:
+    branches: [master]
+  pull_request:
+
+jobs:
+  test:
+    name: ${{ matrix.os }} py${{ matrix.python }}
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        include:
+          - { os: ubuntu-latest, python: "3.11" }
+          - { os: ubuntu-latest, python: "3.12" }
+          - { os: ubuntu-latest, python: "3.13" }
+          - { os: ubuntu-latest, python: "3.14" }
+          - { os: windows-latest, python: "3.11" }
+          - { os: windows-latest, python: "3.14" }
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      - run: pytest
+      - run: python -m build
+      - name: Console script runs
+        run: server-motd
+
+  ansible-lint:
+    name: ansible-lint
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install ansible-lint
+      - run: ansible-lint
+
+  debian-hook:
+    name: role and hook render
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build ansible-core
+      - run: python -m build --wheel
+      - name: Apply the role to the runner
+        env:
+          ANSIBLE_ROLES_PATH: ${{ github.workspace }}/ansible/roles
+          ANSIBLE_STDOUT_CALLBACK: default
+        run: |
+          wheel=$(ls "$PWD"/dist/*.whl)
+          ansible-playbook -i localhost, -c local -b ansible/ci-present.yml \
+            -e "ansible_python_interpreter=$(command -v python3)" \
+            -e "server_motd_package_src=$wheel"
+      - name: Second run is idempotent
+        env:
+          ANSIBLE_ROLES_PATH: ${{ github.workspace }}/ansible/roles
+        run: |
+          wheel=$(ls "$PWD"/dist/*.whl)
+          ansible-playbook -i localhost, -c local -b ansible/ci-present.yml \
+            -e "ansible_python_interpreter=$(command -v python3)" \
+            -e "server_motd_package_src=$wheel" | tee run2.log
+          grep -E "changed=0 .*failed=0" run2.log
+      - name: Config is valid and read-only to the service user
+        run: |
+          sudo stat -c '%U %G %a' /etc/server-motd/config.toml | grep -x 'root server-motd 640'
+          sudo -u server-motd /opt/server-motd/venv/bin/server-motd check
+      - name: MOTD renders through the hook
+        run: |
+          sudo /etc/update-motd.d/50-server-motd | tee motd.txt
+          grep -q "ci-host" motd.txt
+          sudo env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin run-parts --lsbsysinit /etc/update-motd.d | grep -q "ci-host"
+      - name: Hook exits 0 with the venv missing
+        run: |
+          sudo mv /opt/server-motd/venv /opt/server-motd/venv.off
+          sudo /etc/update-motd.d/50-server-motd
+          sudo mv /opt/server-motd/venv.off /opt/server-motd/venv
+      - name: state absent removes everything
+        env:
+          ANSIBLE_ROLES_PATH: ${{ github.workspace }}/ansible/roles
+        run: |
+          ansible-playbook -i localhost, -c local -b ansible/ci-absent.yml \
+            -e "ansible_python_interpreter=$(command -v python3)"
+          test ! -e /etc/update-motd.d/50-server-motd
+          test ! -e /opt/server-motd
+          test ! -e /etc/server-motd
+          ! getent passwd server-motd
+
+  debian-hook-custom-paths:
+    name: role and hook render (non-default paths)
+    runs-on: ubuntu-latest
+    env:
+      ANSIBLE_ROLES_PATH: ${{ github.workspace }}/ansible/roles
+      ANSIBLE_STDOUT_CALLBACK: default
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: python -m pip install build ansible-core
+      - run: python -m build --wheel
+      - name: Write the non-default role variables
+        run: |
+          cat > custom-paths.yml <<'EOF'
+          server_motd_user: motd-ci
+          server_motd_base_dir: /srv/motd-ci
+          server_motd_config_dir: /etc/motd-ci
+          EOF
+      - name: Apply the role with a custom user, base dir and config dir
+        run: |
+          wheel=$(ls "$PWD"/dist/*.whl)
+          ansible-playbook -i localhost, -c local -b ansible/ci-present.yml \
+            -e "ansible_python_interpreter=$(command -v python3)" \
+            -e "server_motd_package_src=$wheel" \
+            -e @custom-paths.yml
+      - name: Nothing landed at the default paths
+        run: |
+          test ! -e /opt/server-motd
+          test ! -e /etc/server-motd
+          ! getent passwd server-motd
+      - name: Config is valid and read-only to the custom user
+        run: |
+          sudo stat -c '%U %G %a' /etc/motd-ci/config.toml | grep -x 'root motd-ci 640'
+          sudo -u motd-ci /srv/motd-ci/venv/bin/server-motd check --config /etc/motd-ci/config.toml
+      - name: MOTD renders through the hook
+        run: |
+          sudo /etc/update-motd.d/50-server-motd | tee motd.txt
+          grep -q "ci-host" motd.txt
+          sudo env -i PATH=/usr/sbin:/usr/bin:/sbin:/bin run-parts --lsbsysinit /etc/update-motd.d | grep -q "ci-host"
+      - name: state absent removes the custom paths
+        run: |
+          ansible-playbook -i localhost, -c local -b ansible/ci-absent.yml \
+            -e "ansible_python_interpreter=$(command -v python3)" \
+            -e @custom-paths.yml
+          test ! -e /etc/update-motd.d/50-server-motd
+          test ! -e /srv/motd-ci
+          test ! -e /etc/motd-ci
+          ! getent passwd motd-ci

server_motd-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,152 @@
+name: Release
+
+# Tag-triggered release: build, publish to PyPI (trusted publishing, no
+# tokens), create a GitHub Release, then open a PR refreshing the role lockfile.
+# Maintainer prerequisites: docs/releasing.md.
+
+on:
+  push:
+    tags: ["v*"]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build and verify
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Tag matches pyproject version
+        run: |
+          version=$(python -c "import tomllib; print(tomllib.load(open('pyproject.toml','rb'))['project']['version'])")
+          if [ "v${version}" != "${GITHUB_REF_NAME}" ]; then
+            echo "Tag ${GITHUB_REF_NAME} does not match pyproject version ${version}" >&2
+            exit 1
+          fi
+      - name: Changelog has an entry for this version
+        run: grep -q "^## \[${GITHUB_REF_NAME#v}\]" CHANGELOG.md
+      - run: python -m pip install -e ".[dev]"
+      - run: ruff check .
+      - run: ruff format --check .
+      - run: mypy
+      - run: pytest
+      - run: python -m build
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+          if-no-files-found: error
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/server-motd/
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: GitHub Release
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Extract changelog section
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          awk -v v="$version" '
+            /^## \[/ { if (found) exit; if (index($0, "[" v "]")) { found = 1; next } }
+            found { print }
+          ' CHANGELOG.md > release-notes.md
+      - name: Create release
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          gh release create "$GITHUB_REF_NAME" dist/* \
+            --title "$GITHUB_REF_NAME" \
+            --notes-file release-notes.md \
+            --verify-tag
+
+  lockfile-pr:
+    name: Role lockfile PR
+    needs: publish-pypi
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+      pull-requests: write
+    env:
+      # Role lockfile; a placeholder until the first release fills it.
+      LOCKFILE: ansible/roles/server_motd/files/requirements.lock
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          ref: master
+      - name: Check for role lockfile
+        id: check
+        run: |
+          if [ -f "$LOCKFILE" ]; then
+            echo "present=true" >> "$GITHUB_OUTPUT"
+          else
+            echo "::notice::$LOCKFILE does not exist yet; skipping lockfile PR"
+            echo "present=false" >> "$GITHUB_OUTPUT"
+          fi
+      - if: steps.check.outputs.present == 'true'
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Regenerate lockfile
+        if: steps.check.outputs.present == 'true'
+        run: |
+          version="${GITHUB_REF_NAME#v}"
+          python -m pip install pip-tools
+          # The role always installs the figlet banner (MOTD layout decision).
+          echo "server-motd[figlet]==${version}" > requirements.in
+          # PyPI's index can lag a few minutes behind the upload.
+          # --strip-extras keeps the pin as "server-motd==", which the role checks for.
+          for attempt in 1 2 3 4 5 6; do
+            if pip-compile --quiet --generate-hashes --allow-unsafe --strip-extras \
+                --output-file "$LOCKFILE" requirements.in; then
+              break
+            fi
+            [ "$attempt" = 6 ] && exit 1
+            sleep 30
+          done
+          rm requirements.in
+      - name: Open pull request
+        if: steps.check.outputs.present == 'true'
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          if git diff --quiet -- "$LOCKFILE"; then
+            echo "Lockfile already current"
+            exit 0
+          fi
+          branch="release/lockfile-${GITHUB_REF_NAME}"
+          git config user.name "github-actions[bot]"
+          git config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          git checkout -b "$branch"
+          git add "$LOCKFILE"
+          git commit -m "Update role lockfile for ${GITHUB_REF_NAME}"
+          git push origin "$branch"
+          # Explicit --repo: this repo is a fork, and gh would otherwise target the parent.
+          gh pr create --repo "$GITHUB_REPOSITORY" --base master --head "$branch" \
+            --title "Update role lockfile for ${GITHUB_REF_NAME}" \
+            --body "Automated: refreshes the hash-pinned lockfile used by the Ansible role to install server-motd ${GITHUB_REF_NAME#v} from PyPI."

server_motd-0.1.0/.gitignore

@@ -0,0 +1,43 @@
+# User-specific stuff:
+.idea/*
+
+## File-based project format:
+*.iws
+
+# IntelliJ
+/out/
+
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# logs
+*.log*
+
+# databases
+*.db
+
+# configs
+*.cfg
+*.json
+
+# generators
+*.bat
+
+# locks
+locks/*
+
+# venv
+/venv/
+.claude/worktrees/
+
+# dev
+/.venv/
+/uv.lock
+.mypy_cache/
+.ruff_cache/
+.pytest_cache/
+/dist/
+*.egg-info/
+!tests/fixtures/**/*.json

server_motd-0.1.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+Hand-written. Versions follow `pyproject.toml` and stay 0.x until the v1 scope
+ships. Each release needs a `## [x.y.z]` heading here; the release workflow
+fails without one and uses the section as the GitHub Release notes.
+
+## [0.1.0]
+
+First release of `server-motd`, a from-scratch rewrite of the Cloudbox-MOTD
+fork as an independent project. Nothing is compatible with v1 (`config.json`,
+`/opt/motd`, the old fragment names); see `docs/migrating-from-v1.md`.
+
+- One pure-Python package for Python 3.11+, with `psutil` as its only required dependency; HTTP and XML-RPC use the standard library.
+- System modules: `ips`, `uptime`, `load`, `cpu`, `memory`, `disks`, `logins`, `processes` and `updates` (pending updates and reboot-required).
+- Service modules, each with any number of named instances: Tautulli, qBittorrent, SABnzbd, rTorrent, Sonarr, Radarr and Lidarr.
+- Modules are fetched concurrently, with a 3 s timeout per module and a 6 s total; a failing module is shown as unavailable instead of breaking the MOTD.
+- TOML config with an ordered `[[modules]]` list, per-module `warn`/`crit` thresholds, `${ENV_VAR}` and `*_file` secrets, and strict validation scoped to each module.
+- Built-in ANSI renderer: two-column boxed layout on wide terminals, a single column on narrow ones, several box styles (including ASCII), and an optional figlet banner (the `figlet` extra).
+- CLI: `server-motd`, `server-motd check`, `install-profile` and `uninstall-profile`, with `--config`, `--width`, `--color` and `--verbose`.
+- Debian/Ubuntu: an Ansible role (`ansible/roles/server_motd`) installs the package and the figlet banner from a hash-pinned lockfile into a root-owned venv, adds a single `update-motd.d` hook that runs as a dedicated user and always exits 0, writes `config.toml` as `root:<user> 0640`, and removes everything with `state: absent`. It never wipes the distro's other MOTD fragments.
+- Windows: a guarded block in the current user's PowerShell 7 and 5.1 profiles, with a per-user `%APPDATA%` config and a read-only `%ProgramData%` fallback.
+- Documentation: README with a golden-tested sample output, a tested example config covering every module kind, install guides for Debian and Windows, and pages on configuration, secrets, troubleshooting, releasing and migrating from v1.
+- Tautulli's bandwidth unit (assumed kbps) is not yet verified against a real server.
+- The legacy v1 bash/Python code is removed; it is kept in the `legacy-v1` git tag.

server_motd-0.1.0/CLAUDE.md

@@ -0,0 +1,13 @@
+# CLAUDE.md
+
+Run all Python through `uv`: `uv run --extra dev pytest` (dev tools are the `dev` extra), `uv run python …`, `uv tool` in place of pipx. `uv` works on the Windows host; a bare `python3` there is a Store stub that hangs or fails silently, and there is no `jq`. Ansible needs the Debian WSL distro, which has no `uv` installed.
+
+Plan and decisions: GitHub issue #1 (the wayfinder map) and `docs/adr/`. Before touching an external API, the Debian MOTD, or the Windows profile hook, read the matching note in `docs/research/`.
+
+The removed v1 bash/Python code lives in the local git tag `legacy-v1`; keep that tag local (never push it).
+
+## Agent skills
+
+- Issue tracker: GitHub Issues via `gh`. See `docs/agents/issue-tracker.md`.
+- Triage labels: `docs/agents/triage-labels.md`.
+- Domain docs (single-context): `GLOSSARY.md` and `docs/adr/`. See `docs/agents/domain.md`.

server_motd-0.1.0/GLOSSARY.md

@@ -0,0 +1,45 @@
+# server-motd
+
+A cross-platform login banner that shows a server's identity, system health and the status of the services it runs.
+
+## Language
+
+**Module**:
+One self-contained unit of MOTD output, either a system section or a service integration.
+_Avoid_: Plugin, fragment, section
+
+**Instance**:
+One named configuration of a service module, so the same service can appear more than once (e.g. two Sonarrs).
+_Avoid_: Profile, server entry
+
+**System module**:
+A module reporting on the host itself (uptime, memory, disks, pending updates).
+_Avoid_: Stat, system section
+
+**Service module**:
+A module reporting on an external application the host runs (Sonarr, qBittorrent, Tautulli).
+_Avoid_: Integration, provider
+
+**Banner**:
+The identity header at the top of the MOTD, showing the server's title.
+_Avoid_: Header, logo
+
+**Host integration**:
+The OS-specific hook that makes the MOTD print at login (`update-motd.d` on Debian-family, a PowerShell profile on Windows).
+_Avoid_: Installer, shim
+
+**Result**:
+What a module returns: a title, a list of rows and an overall status.
+_Avoid_: Output, section
+
+**Row**:
+One labelled value line within a result, with its own status.
+_Avoid_: Line, stat
+
+**Status**:
+The semantic health of a row or result (info, ok, warn, crit, unavailable); the renderer maps it to colour.
+_Avoid_: Level, severity, colour
+
+**Profile block**:
+The marked span `install-profile` writes into a PowerShell profile to run the MOTD at login; everything outside the markers belongs to the user.
+_Avoid_: Snippet, hook