manuheart 0.1.1__tar.gz

manuheart-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,78 @@
+name: Publish Python package
+
+on:
+  workflow_dispatch:
+  release:
+    types: [published]
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    name: Build distribution artifacts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build tooling
+        run: python -m pip install --upgrade build twine
+
+      - name: Build wheel and sdist
+        run: python -m build
+
+      - name: Check distribution metadata
+        run: python -m twine check dist/*
+
+      - name: Upload distribution artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist/*
+          if-no-files-found: error
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist
+
+      - name: Publish package to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: build
+    if: github.event_name == 'release' && github.event.release.prerelease == false
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+      contents: read
+    steps:
+      - name: Download distribution artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: python-package-distributions
+          path: dist
+
+      - name: Publish package to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

manuheart-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+.venv/
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+*.egg-info/
+dist/
+build/
+
+# Example/smoke-test runtime outputs
+examples/deployment-test/tmp/
+examples/deployment-test/var/
+examples/localhost/var/
+examples/synthetic-compat/var/

manuheart-0.1.1/CHANGELOG.md

@@ -0,0 +1,68 @@
+# Changelog
+
+## v0.1.1 - PyPI trusted publishing release
+
+Status: public package publishing release.
+
+### Changed
+
+- Added GitHub Actions trusted publishing workflow for TestPyPI and PyPI.
+- Added PyPI/TestPyPI trusted-publisher setup documentation.
+- Changed README documentation links to absolute GitHub URLs so they render correctly on PyPI.
+- Added package project URLs for repository and changelog.
+- Added local release tooling extras for `build` and `twine`.
+
+### Verification
+
+- TestPyPI trusted publishing for `manuheart==0.1.0` was verified before this release.
+- `manuheart[yaml]==0.1.0` installed successfully from TestPyPI with real PyPI as dependency fallback.
+
+## v0.1.0 - Internal baseline
+
+Status: internal/private baseline; not a public release.
+
+### Added
+
+- Python package and CLI for Manuheart health checks.
+- JSON configuration as the primary supported config format.
+- Optional YAML configuration support via the `yaml` extra.
+- Typed domain models for hosts, groups, systems, statuses, checks, reports, and config.
+- ICMP checker backed by `icmplib`.
+- HTTP/S checker backed by `httpx`, with configurable `HEAD`/`GET` behavior and safe `HEAD` to `GET` fallback.
+- Clean typed JSON reports for `hoststatus`, `groupstatus`, and `sysstatus`.
+- Previous-state loading from clean Python reports and legacy-shaped Bash reports.
+- Host/group/system `unknown`, grace, critical-group, and rollup semantics.
+- Per-host checker error isolation and missing-checker warnings.
+- Warning-aware previous-state degradation.
+- Semantic config warnings for valid-but-suspicious health models.
+- API override validation.
+- Minimal check/daemon logging through `runtime.log_file` and `runtime.log_level`.
+- Checker diagnostic details in host reports, with normalization and length bounding.
+- Shared report metadata (`run_id`, `generated_at`) across report files.
+- Public API extension types for injected checkers, clocks, sleepers, daemon event callbacks, config overrides, and previous state.
+- CLI commands: `check`, `daemon`, and `validate-config`.
+- Public deployment smoke config using harmless well-known endpoints.
+- Local QA gates for linting, typing, tests, localhost Bash/Python comparison, dependency audit, and clean install smoke.
+
+### Removed / intentionally not included
+
+- Legacy Bash config parsing as a product surface.
+- Drop-in Bash replacement requirement.
+- Public PyPI or public repository release posture.
+- Real infrastructure fixtures or reports.
+- Bounded check concurrency; deferred until real deployment scale justifies it.
+
+### Verification for baseline
+
+The baseline is considered releasable internally only after the documented release-readiness gate passes:
+
+```bash
+.venv/bin/python -m ruff check src tests scripts
+.venv/bin/python -m mypy src/manuheart
+.venv/bin/python -m pytest -q
+.venv/bin/python scripts/check_localhost_compatibility.py
+.venv/bin/python scripts/check_dependency_security.py
+.venv/bin/python -m manuheart validate-config --config examples/deployment-test/public-smoke.json
+.venv/bin/python -m manuheart check --config examples/deployment-test/public-smoke.json
+.venv/bin/python scripts/check_clean_install.py
+```

manuheart-0.1.1/PKG-INFO

@@ -0,0 +1,107 @@
+Metadata-Version: 2.4
+Name: manuheart
+Version: 0.1.1
+Summary: Python rewrite of the Manuheart health checker
+Project-URL: Repository, https://github.com/RusDavies/manuheart-python
+Project-URL: Changelog, https://github.com/RusDavies/manuheart-python/blob/main/CHANGELOG.md
+Author: Russ Davies
+License: MIT
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: icmplib>=3.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: mypy>=1.10; extra == 'dev'
+Requires-Dist: pip-audit>=2.10; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Requires-Dist: twine>=5.1; extra == 'dev'
+Requires-Dist: types-pyyaml>=6.0; extra == 'dev'
+Provides-Extra: release
+Requires-Dist: build>=1.2; extra == 'release'
+Requires-Dist: twine>=5.1; extra == 'release'
+Provides-Extra: yaml
+Requires-Dist: pyyaml>=6.0; extra == 'yaml'
+Description-Content-Type: text/markdown
+
+# Manuheart Python
+
+## Quick start
+
+Install for local development:
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev,yaml]'
+```
+
+Validate the example config:
+
+```bash
+.venv/bin/python -m manuheart validate-config --config examples/localhost/manuheart.json
+```
+
+Run one check cycle:
+
+```bash
+.venv/bin/python -m manuheart check --config examples/localhost/manuheart.json
+```
+
+Run the public deployment smoke config:
+
+```bash
+.venv/bin/python -m manuheart check --config examples/deployment-test/public-smoke.json
+```
+
+Run daemon mode:
+
+```bash
+.venv/bin/python -m manuheart daemon --config examples/localhost/manuheart.json
+```
+
+Use the library API:
+
+```python
+from manuheart.api import CheckerMap, load_config, run_check, write_reports
+
+config = load_config("examples/localhost/manuheart.json")
+result = run_check(config)
+write_reports(result)
+```
+
+Typed extension points such as `CheckerMap`, `ClockSource`, `SleepFunction`, and
+`DaemonEventCallback` are exported from `manuheart.api` for callers that inject custom
+checkers, clocks, daemon sleepers, or daemon event hooks.
+
+Library callers can also pass `previous_state=` to `run_check()` for in-memory state
+continuity, or `load_previous=False` when they want a single cycle that deliberately avoids
+reading previous report files.
+
+Run the local verification gate:
+
+```bash
+.venv/bin/python -m ruff check src tests scripts
+.venv/bin/python -m mypy src/manuheart
+.venv/bin/python -m pytest -q
+.venv/bin/python scripts/check_localhost_compatibility.py
+.venv/bin/python scripts/check_dependency_security.py
+.venv/bin/python scripts/check_clean_install.py
+```
+
+## Docs
+
+- [Scope](https://github.com/RusDavies/manuheart-python/blob/main/docs/scope.md)
+- [Requirements](https://github.com/RusDavies/manuheart-python/blob/main/docs/requirements.md)
+- [Architecture and deployment notes](https://github.com/RusDavies/manuheart-python/blob/main/docs/architecture-deployment-notes.md)
+- [Health state semantics](https://github.com/RusDavies/manuheart-python/blob/main/docs/health-state-semantics.md)
+- [Deployment test config](https://github.com/RusDavies/manuheart-python/blob/main/docs/deployment-test-config.md)
+- [Release posture](https://github.com/RusDavies/manuheart-python/blob/main/docs/release-posture.md)
+- [PyPI trusted publishing setup](https://github.com/RusDavies/manuheart-python/blob/main/docs/release/pypi-trusted-publishing.md)
+- [Security and privacy notes](https://github.com/RusDavies/manuheart-python/blob/main/docs/security-privacy-notes.md)
+- [Changelog](https://github.com/RusDavies/manuheart-python/blob/main/CHANGELOG.md)
+- [QA evidence](https://github.com/RusDavies/manuheart-python/blob/main/docs/qa-evidence.md)
+- [Implementation checklist](https://github.com/RusDavies/manuheart-python/blob/main/docs/implementation-checklist.md)
+- [Bash implementation understanding](https://github.com/RusDavies/manuheart-python/blob/main/docs/bash-implementation-understanding.md)
+- [Python architecture proposal](https://github.com/RusDavies/manuheart-python/blob/main/docs/python-architecture-proposal.md)
+- [Localhost compatibility differences](https://github.com/RusDavies/manuheart-python/blob/main/docs/localhost-compatibility-differences.md)
+- [Fixture intake policy](https://github.com/RusDavies/manuheart-python/blob/main/docs/fixture-intake-policy.md)

manuheart-0.1.1/README.md

@@ -0,0 +1,81 @@
+# Manuheart Python
+
+## Quick start
+
+Install for local development:
+
+```bash
+python -m venv .venv
+.venv/bin/python -m pip install -e '.[dev,yaml]'
+```
+
+Validate the example config:
+
+```bash
+.venv/bin/python -m manuheart validate-config --config examples/localhost/manuheart.json
+```
+
+Run one check cycle:
+
+```bash
+.venv/bin/python -m manuheart check --config examples/localhost/manuheart.json
+```
+
+Run the public deployment smoke config:
+
+```bash
+.venv/bin/python -m manuheart check --config examples/deployment-test/public-smoke.json
+```
+
+Run daemon mode:
+
+```bash
+.venv/bin/python -m manuheart daemon --config examples/localhost/manuheart.json
+```
+
+Use the library API:
+
+```python
+from manuheart.api import CheckerMap, load_config, run_check, write_reports
+
+config = load_config("examples/localhost/manuheart.json")
+result = run_check(config)
+write_reports(result)
+```
+
+Typed extension points such as `CheckerMap`, `ClockSource`, `SleepFunction`, and
+`DaemonEventCallback` are exported from `manuheart.api` for callers that inject custom
+checkers, clocks, daemon sleepers, or daemon event hooks.
+
+Library callers can also pass `previous_state=` to `run_check()` for in-memory state
+continuity, or `load_previous=False` when they want a single cycle that deliberately avoids
+reading previous report files.
+
+Run the local verification gate:
+
+```bash
+.venv/bin/python -m ruff check src tests scripts
+.venv/bin/python -m mypy src/manuheart
+.venv/bin/python -m pytest -q
+.venv/bin/python scripts/check_localhost_compatibility.py
+.venv/bin/python scripts/check_dependency_security.py
+.venv/bin/python scripts/check_clean_install.py
+```
+
+## Docs
+
+- [Scope](https://github.com/RusDavies/manuheart-python/blob/main/docs/scope.md)
+- [Requirements](https://github.com/RusDavies/manuheart-python/blob/main/docs/requirements.md)
+- [Architecture and deployment notes](https://github.com/RusDavies/manuheart-python/blob/main/docs/architecture-deployment-notes.md)
+- [Health state semantics](https://github.com/RusDavies/manuheart-python/blob/main/docs/health-state-semantics.md)
+- [Deployment test config](https://github.com/RusDavies/manuheart-python/blob/main/docs/deployment-test-config.md)
+- [Release posture](https://github.com/RusDavies/manuheart-python/blob/main/docs/release-posture.md)
+- [PyPI trusted publishing setup](https://github.com/RusDavies/manuheart-python/blob/main/docs/release/pypi-trusted-publishing.md)
+- [Security and privacy notes](https://github.com/RusDavies/manuheart-python/blob/main/docs/security-privacy-notes.md)
+- [Changelog](https://github.com/RusDavies/manuheart-python/blob/main/CHANGELOG.md)
+- [QA evidence](https://github.com/RusDavies/manuheart-python/blob/main/docs/qa-evidence.md)
+- [Implementation checklist](https://github.com/RusDavies/manuheart-python/blob/main/docs/implementation-checklist.md)
+- [Bash implementation understanding](https://github.com/RusDavies/manuheart-python/blob/main/docs/bash-implementation-understanding.md)
+- [Python architecture proposal](https://github.com/RusDavies/manuheart-python/blob/main/docs/python-architecture-proposal.md)
+- [Localhost compatibility differences](https://github.com/RusDavies/manuheart-python/blob/main/docs/localhost-compatibility-differences.md)
+- [Fixture intake policy](https://github.com/RusDavies/manuheart-python/blob/main/docs/fixture-intake-policy.md)

manuheart-0.1.1/TODO.md

@@ -0,0 +1,99 @@
+# TODO
+
+## Product process / Class 2 internal tool setup
+
+- [x] Create lightweight product/problem framing.
+- [x] Define requirements and acceptance criteria.
+- [x] Capture UX/workflow notes if a UI exists.
+- [x] Capture security/privacy notes.
+- [x] Capture lightweight architecture/deployment notes.
+- [x] Create implementation checklist.
+- [x] Record basic QA evidence for completed work.
+- [x] Add rollback/disable note.
+- [x] Add AI-agent operation boundary note, unless Russ explicitly exempts it.
+
+## Project discovery
+
+- [x] Define scope: what Manuheart Python is responsible for.
+- [x] Capture baseline inventory, current access assumptions, and dependencies.
+- [x] Add README quick start for library API usage and CLI usage.
+- [x] Add Bash-vs-Python output compatibility check for localhost fixtures.
+- [x] Identify initial implementation or audit tasks.
+- [x] Prioritize remediation/build items with Russ.
+
+
+## Python rewrite backlog
+
+- [x] Understand the original Bash implementation and document its behavior.
+- [x] Propose a clean Python architecture for the rewrite.
+- [x] Create Python project skeleton with `pyproject.toml`, `src/manuheart/`, and `tests/`.
+- [x] Define the initial public library API contract in `src/manuheart/api.py`.
+- [x] Add API smoke tests proving the package and public API import cleanly.
+- [x] Port sample localhost config fixtures from `manuheart-bash`.
+- [x] Implement typed domain models for hosts, groups, systems, statuses, and checks.
+- [x] Remove legacy Bash config, group, and host parser support after product reframe.
+- [x] Implement first-class JSON configuration parser using the same normalized domain model.
+- [x] Implement optional YAML configuration parser, preferably behind a `yaml` package extra.
+- [x] Add equivalence tests proving JSON and YAML config can describe the same health model.
+- [x] Implement pure health rollup logic with fake-checker tests.
+- [x] Implement CLI/API override application for config values and add precedence tests.
+- [x] Implement real ICMP and HTTP(S) checkers.
+- [x] Implement previous-state loading and atomic JSON report writing.
+- [x] Implement CLI commands as thin adapters over the public API.
+- [x] Add tests proving CLI behavior matches API behavior for equivalent inputs.
+- [x] Add smoke test for one-shot localhost run.
+- [x] Add daemon mode only after one-shot mode is solid.
+
+
+## Compatibility-first readiness backlog
+
+- [x] Preserve report filenames and top-level keys while converting inner fields to cleaner typed JSON.
+- [x] Use Pythonic snake_case field names in clean typed report records.
+- [x] Implement clean typed report output as the default Python report format.
+- [x] Keep report status fields as enum-like strings (`up`, `down`, `unknown`).
+- [x] Keep report timestamp fields as consistently ISO-8601 strings.
+- [x] Add tests proving report fields use typed JSON values where practical.
+- [x] Decide whether safe real-world Bash configs can be used as compatibility fixtures.
+- [x] Add broader synthetic compatibility fixtures after exact localhost output matching is resolved.
+- [x] Add expanded synthetic fixtures for multi-host, HTTP/S, optional group, and failure-grace scenarios.
+- [x] Tighten localhost Bash-vs-Python compatibility check to identify and document migration-relevant output differences.
+- [x] Keep real-world fixture intake blocked unless Russ separately approves sanitized configs.
+- [x] Document accepted compatibility differences between Bash and Python outputs.
+- [x] Decide whether to add an explicit legacy-compatible report mode after clean typed output is established.
+- [x] Add clean-venv install/package smoke test.
+- [x] Decide remote repository and publishing/release posture.
+
+## Code analysis improvement backlog
+
+- [x] Implement documented host/group/system `unknown` and grace state semantics.
+- [x] Add stricter structured config validation for unknown keys and numeric bounds.
+- [x] Catch per-host checker crashes in the health engine and convert them to non-`up` check results.
+- [x] Surface previous-state/report read degradation as warnings.
+- [x] Clarify or adjust relative path semantics for status files.
+- [x] Tighten public API typing around checker maps, clocks, sleepers, and daemon callbacks.
+- [x] Add checker detail fields to host reports.
+- [ ] Consider bounded check concurrency after real deployment scale requires it.
+- [x] Harden previous-state loading against malformed report values.
+- [x] Add stricter structured JSON/YAML config validation and clearer `ConfigError` messages.
+- [x] Make HTTP checking less HEAD-only, via configurable method or safe GET fallback.
+- [x] Improve CLI error handling for `check` and `daemon` operational failures.
+- [x] Improve daemon observability and graceful shutdown behaviour.
+- [x] Reuse or inject HTTP clients for efficiency and cleaner checker tests.
+- [x] Add static typing gate and package typing marker (`py.typed`).
+- [x] Add dependency/security review gate before release.
+
+## Follow-up code review polish
+
+- [x] Add semantic config warnings for valid-but-suspicious health models.
+- [x] Validate public API override value types and bounds.
+- [x] Implement minimal check/daemon logging using `runtime.log_file` and `runtime.log_level`.
+- [x] Bound and normalize checker detail text before storing it in host reports.
+- [x] Add report-set metadata with matching `run_id` and `generated_at` across host/group/system reports.
+- [x] Add public API support for injected previous state or intentionally skipping disk previous-state loading.
+
+## Release readiness
+
+- [x] Add internal `v0.1.0` changelog/release notes.
+- [x] Confirm release-readiness gate includes lint, typecheck, tests, compatibility, dependency audit, public smoke validate/check, and clean install smoke.
+- [x] Add GitHub Actions trusted-publishing workflow for TestPyPI/PyPI.
+- [x] Document PyPI/TestPyPI pending trusted-publisher setup fields.

manuheart-0.1.1/docs/ai-agent-operation-boundary.md

@@ -0,0 +1,26 @@
+# AI-Agent Operation Boundary
+
+Status: Draft.
+
+## Agents may do autonomously
+
+- Inspect source, tests, docs, and local fixtures.
+- Create branches and commits for implementation work.
+- Add or update tests.
+- Run local verification gates.
+- Update internal docs and TODO items.
+- Add compatibility checks that do not touch external systems.
+
+## Human approval required
+
+- Deploying Manuheart Python to shared infrastructure.
+- Replacing or deleting the Bash implementation.
+- Changing real monitored host lists.
+- Publishing the package externally.
+- Sending alerts/messages externally.
+- Accepting compatibility gaps or known broken health reporting.
+- Handling secrets or sensitive infrastructure credentials.
+
+## Default operating mode
+
+Prefer local implementation, tests, and documentation work. Treat deployment and real monitoring changes as human-approved actions only.

manuheart-0.1.1/docs/architecture-deployment-notes.md

@@ -0,0 +1,53 @@
+# Architecture and Deployment Notes
+
+Status: Draft.
+
+## Architecture
+
+Manuheart Python is a reusable Python library with a CLI adapter.
+
+Core layers:
+
+- `manuheart.api`: public import surface.
+- `manuheart.config`: JSON/YAML config loading and normalization.
+- `manuheart.models`: typed domain models.
+- `manuheart.health`: health-state update and rollup engine.
+- `manuheart.checkers`: ICMP/HTTP checker adapters backed by Python libraries.
+- `manuheart.state`: previous compatibility-report state loading.
+- `manuheart.reporting`: compatibility JSON report serialization and atomic writes.
+- `manuheart.cli`: command-line adapter over the public API.
+
+The health engine should remain independent of config file format and CLI parsing.
+
+## Runtime dependencies
+
+- Python 3.11+.
+- `httpx` for HTTP/S checks.
+- `icmplib` for ICMP checks.
+- Optional `PyYAML` for YAML configuration.
+
+## Deployment modes
+
+### Recommended: supervised one-shot
+
+Run `manuheart check --config <file>` from cron, systemd timer, CI, or another supervisor. This gives bounded lifecycle, simple logs, and straightforward rollback.
+
+### Optional: daemon
+
+Run `manuheart daemon --config <file>` only when built-in scheduling is specifically useful. Prefer an external supervisor for restart policy and lifecycle management.
+
+## Report outputs
+
+The tool writes compatibility JSON reports:
+
+- `hoststatus`
+- `groupstatus`
+- `sysstatus`
+
+Writes are atomic temp-file-and-replace operations.
+
+## Repository and release posture
+
+Current posture: internal-only with a private GitHub remote. No public repository, public package publication, or shared-infrastructure deployment should happen without explicit Russ approval. See `docs/release-posture.md`.
+
+For deployment smoke testing without real infrastructure, use `examples/deployment-test/public-smoke.json`; see `docs/deployment-test-config.md`.

manuheart-0.1.1/docs/baseline-inventory.md

@@ -0,0 +1,33 @@
+# Baseline Inventory, Access, and Dependencies
+
+Status: Draft.
+
+## Repositories / folders
+
+- Python rewrite: `projects/manuheart-python`.
+- Bash source reference: `projects/manuheart-bash`.
+
+## Current Python package
+
+- Package name: `manuheart`.
+- Source layout: `src/manuheart`.
+- Public API: `manuheart.api`.
+- CLI entry point: `manuheart = manuheart.cli:main`.
+
+## Runtime dependencies
+
+- Python 3.11+.
+- `httpx`.
+- `icmplib`.
+- Optional `PyYAML` via `manuheart[yaml]`.
+
+## Development dependencies
+
+- `pytest`.
+- `ruff`.
+
+## Access assumptions
+
+- Work is local/internal unless Russ approves deployment or publishing.
+- No external messaging, alerting, or infrastructure changes are authorized by default.
+- ICMP checks may require platform/network permissions depending on environment; current implementation uses unprivileged `icmplib` by default.