Metadata-Version: 2.4
Name: milo-gh-actions-cost-audit
Version: 0.1.0
Summary: Lightning-paywalled FastAPI service — niche: GitHub Actions cost audit + optimization suggestions — free CLI + paid webhook alerts
Author-email: Milo Antaeus <miloantaeus@gmail.com>
License: MIT
Keywords: fastapi,l402,lightning,m2m,paywall,x402
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
Requires-Python: >=3.10
Requires-Dist: fastapi>=0.110
Requires-Dist: httpx>=0.27
Requires-Dist: milo-paywall-kit>=0.1.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: uvicorn[standard]>=0.30
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.21.0; extra == 'test'
Requires-Dist: pytest>=7.0.0; extra == 'test'
Description-Content-Type: text/markdown

# milo-gh-actions-cost-audit

> **Audit your GitHub Actions workflows for cost waste. Free CLI. Free public-repo API. Paid Lightning-rail webhook alerts.**

[![Lightning](https://img.shields.io/badge/Lightning-paywall-yellow)](#)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Audited](https://img.shields.io/badge/audited%20by-milo--gh--actions--cost--audit-success)](https://github.com/miloantaeus/milo-gh-actions-cost-audit)

## Why this exists

GitHub Actions billing is opaque until your card is charged. 7 rules — derived
from real-world overspend patterns (matrix.os explosion, missing cache,
no `timeout-minutes`, oversized runners, duplicate runs on push+pr,
unfiltered cron) — surface waste in under one second. Estimated savings per
issue are quoted in dollars per month.

No GitHub token required for public repos. No telemetry. MIT.

---

## 3 example usages

### 1. CLI (local file)

```bash
pip install milo-gh-actions-cost-audit
milo-gh-actions-cost-audit .github/workflows/ci.yml
```

```
milo-gh-actions-cost-audit — CI
===============================

Jobs: 1   Triggers: push, pull_request   Runs/mo (assumed): 30
Estimated monthly cost (if private repo): $190.80
Estimated annual cost: $2289.60

Found 5 issue(s):  high=3 med=2 low=0
Total potential monthly savings: $580.86  ($6970.32/yr)

1. [HIGH] macos-large-runner (oversized_runner)
   Jobs:  test
   Fix:   Job 'test' uses macos-latest-large. macos-latest-large is $0.32/min
          vs $0.08/min for macos-latest. ... Saves: $432.00/mo ($5184.00/yr)
... (truncated)
```

Exit code: `0` if no high-severity issues, `1` if 1+ high-severity issues.

### 2. Hosted API (free, public repo)

```bash
# Free POST — any workflow YAML
curl -X POST https://gh-cost.milo.dev/audit \
  -H "Content-Type: text/plain" \
  --data-binary @.github/workflows/ci.yml

# Free GET — public repo, rate-limited 10/IP/day
curl "https://gh-cost.milo.dev/audit?repo=vercel/next.js"
```

### 3. Webhook alerts (Lightning, 100 sats/month)

```bash
# 1. Request subscription — returns HTTP 402 with BOLT-11 invoice
curl -i -X POST https://gh-cost.milo.dev/webhook/subscribe \
  -H "Content-Type: application/json" \
  -d '{"repo": "your/repo", "webhook_url": "https://your-app.com/hook"}'

# 2. Pay the BOLT-11 in any Lightning wallet (Alby, Phoenix, Zeus, WoS)

# 3. Re-call with ?payment_hash=<hash-from-402>
curl -X POST "https://gh-cost.milo.dev/webhook/subscribe?payment_hash=<hash>" \
  -H "Content-Type: application/json" \
  -d '{"repo": "your/repo", "webhook_url": "https://your-app.com/hook"}'
```

You get a daily audit at 03:00 UTC. If any high-severity issue appears OR the
estimated monthly cost increases by >$5 from baseline, your `webhook_url` is
called with the full audit JSON.

---

## "Audited by" badge

Add this to your repo's README after auditing your workflows:

```markdown
[![Audited](https://img.shields.io/badge/audited%20by-milo--gh--actions--cost--audit-success)](https://github.com/miloantaeus/milo-gh-actions-cost-audit)
```

---

## Rules (current set)

| ID | Severity | What it catches |
| --- | --- | --- |
| `matrix-os-3plus` | med | `strategy.matrix.os` with 3+ OSes — usually you don't actually test OS compatibility |
| `no-timeout-minutes` | **high** | Missing `timeout-minutes:` — infinite-loop risk = unbounded billing |
| `no-actions-cache` | med | Job installs dependencies but lacks `actions/cache@v4` or `cache: true` |
| `macos-large-runner` | **high** | `macos-latest-large` ($0.32/min) when `macos-latest` ($0.08/min) usually works |
| `duplicate-job-on-pr-and-push` | **high** | Workflow triggers on both `push` (unrestricted) AND `pull_request` — 2x cost per PR commit |
| `ubuntu-latest-large-no-need` | med | 8/16-core runner without parallel build commands (`make -j`, `cargo --release`, etc.) |
| `schedule-without-condition` | low | `schedule:` cron without `paths:` filter on push/pr — needless baseline cron |

---

## Architecture

- Pure-Python parser (PyYAML); no external API calls for local audits.
- Public-repo audits use GitHub's unauthenticated REST API (60 req/hr/IP global cap).
- Lightning paywall via [`milo-paywall-kit`](../_milo_paywall_kit/) (LNBits/Alby compatible).
- FastAPI hosted endpoint deployable to Vercel/Fly/Railway.

---

## Tests

```bash
pip install -e ".[test]"
pytest -q
# 63 passed in 0.19s
```

---

## Self-deprecation criterion

Per Milo's market-truth doctrine, this SKU is deprecated if:
- **0 webhook subscribers convert in 60 days** (validates paid-tier demand), OR
- **0 GitHub-API audits in 30 days** (validates free-tier demand).

Either signal kills it without owner intervention.

---

## License

MIT.
