proofrun 0.1.1__tar.gz

proofrun-0.1.1/.github/workflows/ci.yaml

@@ -0,0 +1,86 @@
+name: CI
+
+on:
+  push:
+    branches:
+      - main
+      - master
+  pull_request:
+    branches:
+      - main
+      - master
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality & Tests
+    runs-on: ubuntu-latest
+
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Run code quality & coverage checks
+        run: make check
+
+      - name: Run integration scenarios
+        run: |
+          make run-profile
+          make run-auth
+          make run-chain
+          make run-crud
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: quality
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Build distributions
+        run: make build
+
+      - name: Verify distributions
+        run: |
+          ls -lh dist/
+          test -f dist/*.whl
+          test -f dist/*.tar.gz

proofrun-0.1.1/.github/workflows/release.yaml

@@ -0,0 +1,113 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+permissions:
+  contents: read
+
+jobs:
+  quality:
+    name: Quality & Tests
+    runs-on: ubuntu-latest
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Install dependencies
+        run: make install
+
+      - name: Run code quality checks
+        run: make check
+
+      - name: Run integration scenarios
+        run: |
+          make run-profile
+          make run-chain
+
+  build:
+    name: Build Package
+    runs-on: ubuntu-latest
+    needs: quality
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Set up uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          enable-cache: true
+          github-token: ${{ secrets.GITHUB_TOKEN }}
+
+      - name: Verify tag matches package version
+        run: |
+          TAG_VERSION="${GITHUB_REF_NAME#v}"
+          PKG_VERSION="$(grep -m1 '^version = ' pyproject.toml | cut -d'"' -f2)"
+          echo "tag: ${TAG_VERSION}  pyproject: ${PKG_VERSION}"
+          if [ "${TAG_VERSION}" != "${PKG_VERSION}" ]; then
+            echo "::error::Tag v${TAG_VERSION} does not match pyproject version ${PKG_VERSION}"
+            exit 1
+          fi
+
+      - name: Build distributions
+        run: make build
+
+      - name: Store distributions
+        uses: actions/upload-artifact@v4
+        with:
+          name: package-distributions
+          path: dist/
+
+  publish-to-pypi:
+    name: Publish to PyPI
+    runs-on: ubuntu-latest
+    needs: build
+    environment: release
+    permissions:
+      id-token: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: package-distributions
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    name: Create GitHub Release
+    runs-on: ubuntu-latest
+    needs: publish-to-pypi
+    permissions:
+      contents: write
+    steps:
+      - name: Download distributions
+        uses: actions/download-artifact@v4
+        with:
+          name: package-distributions
+          path: dist/
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        with:
+          files: dist/*
+          generate_release_notes: true

proofrun-0.1.1/.gitignore

@@ -0,0 +1,84 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+env.bak/
+venv.bak/
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# Distribution / packaging
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+MANIFEST
+
+# Test / coverage
+.pytest_cache/
+.coverage
+.coverage.*
+htmlcov/
+coverage.xml
+*.cover
+*.lcov
+.hypothesis/
+.tox/
+.nox/
+
+# Tool caches
+.ruff_cache/
+.pyright_cache/
+.mypy_cache/
+.pyre/
+.pytype/
+.dmypy.json
+dmypy.json
+
+# IDE / editors
+.idea/
+.vscode/
+.spyderproject
+.spyproject
+.ropeproject
+
+# Jupyter
+.ipynb_checkpoints/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Temporary files
+*.tmp
+*.temp
+*.swp
+*.swo
+*~
+tempCodeRunnerFile.py
+
+# Build / local tooling
+.pdm-python
+.pdm-build/
+.pixi/
+__pypackages__/
+
+# Local package/build metadata
+.python-version
+
+# PyPI credentials
+.pypirc
+
+
+FUTURE.md

proofrun-0.1.1/.pre-commit-config.yaml

@@ -0,0 +1,26 @@
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.8.0
+    hooks:
+      - id: ruff
+        args: [--fix]
+        stages: [pre-commit]
+
+      - id: ruff-format
+        stages: [pre-commit]
+
+  - repo: local
+    hooks:
+      - id: pyright
+        name: pyright
+        entry: uv run pyright
+        language: system
+        pass_filenames: false
+        stages: [pre-push]
+
+      - id: pytest
+        name: pytest
+        entry: uv run pytest -q
+        language: system
+        pass_filenames: false
+        stages: [pre-push]

proofrun-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Kishan Thanki
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

proofrun-0.1.1/Makefile

@@ -0,0 +1,67 @@
+.PHONY: install test coverage coverage-html lint format format-check typecheck check \
+	run-profile run-auth run-chain run-crud build clean full ci
+
+full: clean install check build
+
+install:
+	uv sync --group dev
+
+test:
+	uv run pytest -q
+
+coverage:
+	uv run pytest -q --cov=proofrun --cov-branch \
+		--cov-report=term-missing \
+		--cov-fail-under=100
+
+coverage-html:
+	uv run pytest -q --cov=proofrun --cov-branch \
+		--cov-report=html
+	@echo "Coverage report generated: htmlcov/index.html"
+
+lint:
+	uv run ruff check src/ tests/
+
+format:
+	uv run ruff format src/ tests/
+
+format-check:
+	uv run ruff format --check src/ tests/
+	uv run ruff check src/ tests/
+
+typecheck:
+	uv run pyright
+
+check: lint format-check typecheck coverage
+
+run-profile:
+	uv run proofrun scenarios/profile.yaml --once
+
+run-auth:
+	python scenarios/server.py & \
+	SERVER_PID=$$!; \
+	sleep 1; \
+	uv run proofrun scenarios/auth.yaml --once; \
+	EXIT_CODE=$$?; \
+	kill $$SERVER_PID 2>/dev/null || true; \
+	exit $$EXIT_CODE
+
+run-chain:
+	uv run proofrun scenarios/chain.yaml --once
+
+run-crud:
+	uv run proofrun scenarios/crud.yaml --once
+
+build:
+	uv build
+
+clean:
+	rm -rf dist/ \
+		.ruff_cache/ \
+		.pytest_cache/ \
+		.pyright_cache/ \
+		.coverage \
+		.coverage.* \
+		htmlcov/ \
+		__pycache__/ \
+		*.egg-info/

proofrun-0.1.1/PKG-INFO

@@ -0,0 +1,268 @@
+Metadata-Version: 2.5
+Name: proofrun
+Version: 0.1.1
+Summary: Synthetic API monitoring as code daemon.
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: fastjsonschema>=2.19.1
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: jsonpath-ng>=1.6.1
+Requires-Dist: orjson>=3.9.15
+Requires-Dist: pydantic>=2.6.0
+Requires-Dist: pyyaml>=6.0.1
+Requires-Dist: rich>=13.7.0
+Requires-Dist: typer>=0.11.0
+Requires-Dist: uvloop>=0.19.0
+Description-Content-Type: text/markdown
+
+<div align="center">
+
+# Proofrun
+
+**Write an API workflow in YAML. Run it locally, in CI, or as a monitor that only alerts when health changes.**
+
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue?logo=python&logoColor=white)](https://www.python.org/)
+[![CI](https://github.com/Kishan-Thanki/proof/actions/workflows/ci.yaml/badge.svg)](https://github.com/Kishan-Thanki/proof/actions/workflows/ci.yaml)
+[![Release](https://img.shields.io/github/v/release/Kishan-Thanki/proof?color=blue&logo=github)](https://github.com/Kishan-Thanki/proof/releases)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+
+</div>
+
+---
+
+Most monitors tell you an endpoint returned `200`. Proofrun tells you whether the
+*journey* works: log in, take the token from the response, use it on the next
+request, and check what comes back.
+
+When something breaks, you see exactly which step failed and why:
+
+<div align="center">
+  <img src="docs/demo-fail.svg" alt="Proofrun reporting a failed step in a login-then-fetch scenario" width="860">
+</div>
+
+And when everything is fine:
+
+<div align="center">
+  <img src="docs/demo-pass.svg" alt="Proofrun reporting a passing scenario" width="860">
+</div>
+
+**YAML in. HTTP checks out. No database, queue, or external service required.**
+
+- **One file describes the workflow.** Scenarios live in Git next to your code.
+- **Multi-step.** Values extracted from one response feed the next request.
+- **Runs anywhere.** Same file locally, in CI (exit code `0` / `1`), or as a daemon.
+- **Quiet by design.** In daemon mode you are alerted when health *changes*, not on every failed check.
+
+## Quickstart (30 seconds)
+
+**1. Install** (Python 3.11+):
+
+```bash
+pip install proofrun
+```
+
+Or with pip: `pipx install proofrun`
+
+**2. Create `health.yaml`:**
+
+```yaml
+version: "1.0"
+
+global:
+  base_url: "https://jsonplaceholder.typicode.com"
+
+scenarios:
+  - name: "Public API is up"
+    steps:
+      - name: "GET /posts/1"
+        request:
+          method: GET
+          path: /posts/1
+        expect:
+          status: 200
+          max_latency_ms: 2000
+```
+
+**3. Run it:**
+
+```bash
+proofrun health.yaml
+```
+
+That's it. Swap in your own `base_url` and paths. Add `--daemon` to keep it
+running.
+
+## A realistic example: log in, then use the token
+
+This is the scenario from the screenshots above. It logs in, extracts the
+access token with JSONPath, sends it as a `Bearer` header on the next request,
+extracts the user id from *that* response, and uses it in the URL of the third.
+
+```yaml
+version: "1.0"
+
+global:
+  base_url: "http://127.0.0.1:8099"
+  timeout_seconds: 5
+
+scenarios:
+  - name: "Login and fetch orders"
+    steps:
+      - name: "Log in"
+        request:
+          method: POST
+          path: /login
+          json:
+            email: "demo@example.com"
+            password: "demo-password"
+        expect:
+          status: 200
+          max_latency_ms: 1000
+        extract:
+          token: "$.access_token"         # saved as ${token}
+
+      - name: "Fetch profile"
+        request:
+          method: GET
+          path: /me
+          headers:
+            Authorization: "Bearer ${token}"    # used here
+        expect:
+          status: 200
+        extract:
+          user_id: "$.id"                 # saved as ${user_id}
+
+      - name: "Fetch orders"
+        request:
+          method: GET
+          path: "/users/${user_id}/orders"
+          headers:
+            Authorization: "Bearer ${token}"
+        expect:
+          status: 200
+          schema:                         # JSON Schema validation
+            type: array
+            minItems: 1
+```
+
+Steps run in order and stop at the first failure, so the report points at the
+step that actually broke. You can try this without any external service. The
+repo includes a tiny local API:
+
+```bash
+# terminal 1: start the demo API
+python scenarios/server.py
+
+# terminal 2: run the scenario (passes, exit code 0)
+proofrun scenarios/auth.yaml
+```
+
+Now break it on purpose. Restart the demo API with `--break`, which makes
+`GET /me` return `500`, and run the same scenario again:
+
+```bash
+python scenarios/server.py --break
+proofrun scenarios/auth.yaml       # fails, exit code 1
+```
+
+## What you can assert
+
+Each step's `expect` block supports:
+
+| Assertion | Example | Notes |
+| --- | --- | --- |
+| `status` | `status: 200` | Required. |
+| `max_latency_ms` | `max_latency_ms: 500` | Fails if the response is slower. |
+| `headers` | `headers: { Content-Type: "application/json" }` | Exact match. |
+| `schema` | inline JSON Schema, or a path to a file | Validates the JSON response body. |
+
+A step can also `extract` values with JSONPath for later steps. Besides your own
+variables, built-in dynamic values are available anywhere you can write `${...}`:
+`${$uuid}`, `${$timestamp}`, `${$timestamp_ms}`, `${$iso_timestamp}`,
+`${$random_int}`.
+
+Defaults you set under `global` (`base_url`, `timeout_seconds`, `headers`) apply
+to every step, and any step can override its own `headers` and `timeout`.
+
+## Run it continuously
+
+```bash
+proofrun monitors/api.yaml --daemon
+```
+
+In daemon mode Proofrun re-runs your scenarios on a loop and tracks each one as
+`HEALTHY` or `FAILING`.
+
+* **Alerts on change, not on repetition.** A webhook fires when a scenario starts
+failing and again when it recovers. A scenario that stays down does not
+re-alert on every cycle.
+* **Edit configs live.** Changes to the YAML are picked up without a restart. If
+an edit is invalid, Proofrun keeps running the last working configuration.
+* **Jittered schedule.** Sleep time varies by ±15% so checks don't all land on
+the same second.
+
+Send alerts to any HTTP endpoint:
+
+```bash
+proofrun monitors/api.yaml --daemon --webhook-url https://<your_domain>/hooks/proofrun
+
+# or
+
+export PROOFRUN_WEBHOOK_URL=https://<your_domain>/hooks/proofrun
+```
+
+The webhook receives plain JSON:
+
+```json
+{
+  "event": "scenario_failed",
+  "scenario": "Login and fetch orders",
+  "previous_status": "HEALTHY",
+  "status": "FAILING",
+  "details": "- Fetch profile: Status code mismatch: expected 200, got 500"
+}
+```
+
+`event` is `scenario_failed` or `scenario_recovered`.
+
+## Use it in CI
+
+Proofrun exits with `0` when every scenario passes and `1` when any fails, so it
+works as a smoke test or a scheduled check. For example, with GitHub Actions:
+
+```yaml
+name: API check
+on:
+  schedule:
+    - cron: "*/15 * * * *"
+  workflow_dispatch:
+
+jobs:
+  proofrun:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install proofrun
+      - run: proofrun monitors/api.yaml
+```
+
+A failing check fails the workflow run, and GitHub notifies you the way it
+notifies you about any failed workflow.
+
+## CLI
+
+```bash
+proofrun <config.yaml>                 # run once and exit (default)
+proofrun <config.yaml> --daemon        # run continuously
+proofrun <config.yaml> --interval 30   # override the daemon interval (seconds)
+proofrun <config.yaml> --daemon --webhook-url <url>
+proofrun --version
+```
+
+## License
+
+[MIT](LICENSE)