Metadata-Version: 2.4
Name: pipewatch
Version: 0.1.0
Summary: Self-learning CI/CD pipeline observability. Zero config. One command.
Project-URL: Homepage, https://github.com/SaqibInTech/pipewatch
Project-URL: Documentation, https://github.com/SaqibInTech/pipewatch#readme
Project-URL: Repository, https://github.com/SaqibInTech/pipewatch
Project-URL: Issues, https://github.com/SaqibInTech/pipewatch/issues
Author: Saqib
License-Expression: MIT
License-File: LICENSE
Keywords: cicd,devops,drift-detection,monitoring,observability,pipeline
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Build Tools
Classifier: Topic :: Software Development :: Quality Assurance
Classifier: Topic :: System :: Monitoring
Requires-Python: >=3.11
Requires-Dist: click>=8.1.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pyyaml>=6.0
Requires-Dist: rich>=13.0.0
Requires-Dist: scipy>=1.12.0
Requires-Dist: structlog>=24.1.0
Provides-Extra: dev
Requires-Dist: mypy>=1.8.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=5.0.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: respx>=0.21.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

<p align="center">
  <strong>P I P E W A T C H</strong><br>
  <em>Your pipeline is drifting. You just don't know it yet.</em>
</p>

<p align="center">
  <a href="https://github.com/SaqibInTech/pipewatch/actions"><img src="https://github.com/SaqibInTech/pipewatch/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
  <a href="https://pypi.org/project/pipewatch/"><img src="https://img.shields.io/pypi/v/pipewatch" alt="PyPI"></a>
  <a href="https://pypi.org/project/pipewatch/"><img src="https://img.shields.io/pypi/pyversions/pipewatch" alt="Python"></a>
  <a href="LICENSE"><img src="https://img.shields.io/github/license/SaqibInTech/pipewatch" alt="License"></a>
</p>

---

Self-learning CI/CD pipeline observability CLI. Connects to your CI/CD platform, learns what "normal" looks like using robust statistics, and alerts you when things drift — duration regressions, failure spikes, flaky tests, dependency bloat.

**Zero config. One command. Local-first.**

## Why Pipewatch?

- Your deploy pipeline was 4 minutes last month. Now it's 7. Nobody noticed.
- Test failures crept from 2% to 12% over three weeks. No alert fired.
- A "flaky" test has been randomly failing for months. Everyone ignores it.

Pipewatch catches these problems automatically by building statistical baselines and flagging anomalies — no thresholds to configure, no dashboards to watch.

## Install

```bash
pip install pipewatch
```

Requires Python 3.11+.

## Quick Start

```bash
# 1. Connect to your GitHub repo and build a baseline
export GITHUB_TOKEN=ghp_...
pipewatch init --provider github --repo owner/repo

# 2. Check pipeline health
pipewatch status

# 3. Start watching for drift
pipewatch watch

# 4. Get a full health report
pipewatch doctor
```

## Commands

| Command | Description |
|---------|-------------|
| `pipewatch init` | Connect to a CI/CD platform and build initial baseline |
| `pipewatch watch` | Monitor pipeline for drift in real-time |
| `pipewatch status` | Show current pipeline health summary |
| `pipewatch diagnose <run-id>` | Deep-dive analysis of a specific run |
| `pipewatch doctor` | Generate a full health report (markdown) |
| `pipewatch compare <branch-a> <branch-b>` | Compare pipeline behavior between branches |
| `pipewatch budget --stage <name> --max <duration>` | Set time budgets per stage |
| `pipewatch notify --slack <url>` | Configure Slack/Discord/webhook alerts |
| `pipewatch providers` | List supported CI/CD platforms |

### Examples

```bash
# Initialize from GitHub Actions
pipewatch init --provider github --repo myorg/myapp --runs 100

# Watch with custom interval
pipewatch watch --interval 10m

# Diagnose a slow run
pipewatch diagnose 12345678

# Compare main vs feature branch
pipewatch compare main feature/new-api

# Set a 3-minute budget on the "test" stage
pipewatch budget --stage test --max 3m

# Get a health report as markdown (great for PR comments)
pipewatch doctor --output report.md

# Set up Slack notifications
pipewatch notify --slack https://hooks.slack.com/services/...

# Set up Discord notifications
pipewatch notify --discord https://discord.com/api/webhooks/...
```

## How It Works

1. **Learn** — `pipewatch init` fetches historical runs and computes per-stage statistical baselines using median + MAD (Median Absolute Deviation), which are resistant to outliers.

2. **Detect** — `pipewatch watch` polls for new runs and flags anomalies using Modified Z-scores. No hardcoded thresholds — the baseline adapts to your pipeline.

3. **Diagnose** — When drift is detected, Pipewatch correlates it to recent commits, dependency changes, and config updates to suggest probable causes.

4. **Alert** — Send drift alerts to Slack, Discord, or any webhook endpoint.

## Architecture

```
~/.pipewatch/
├── config.yml    # Provider config (no tokens stored)
└── data.db       # SQLite — all data stays local
```

All analysis uses robust statistics — no ML, no cloud APIs, no training data needed:

- **Baseline**: Rolling median + MAD (outlier-resistant)
- **Drift detection**: Modified Z-score
- **Trend detection**: Mann-Kendall test
- **Flaky tests**: Bayesian flip-rate analysis

## Supported Platforms

| Platform | Status |
|----------|--------|
| GitHub Actions | Supported |
| GitLab CI | Coming Soon |
| Jenkins | Coming Soon |
| CircleCI | Coming Soon |
| Bitbucket Pipelines | Coming Soon |

Want to add a provider? It's a single Python file — see [CONTRIBUTING.md](CONTRIBUTING.md).

## Notifications

Pipewatch can send drift alerts to:

- **Slack** — Rich block-formatted messages
- **Discord** — Color-coded embeds with fields
- **Generic Webhook** — JSON payload to any endpoint

```bash
# Configure multiple channels
pipewatch notify --slack https://hooks.slack.com/...
pipewatch notify --discord https://discord.com/api/webhooks/...
pipewatch notify --webhook https://your-api.com/alerts

# List configured channels
pipewatch notify --list

# Remove a channel
pipewatch notify --remove slack
```

## Configuration

Pipewatch stores config in `~/.pipewatch/config.yml`. Most settings have sensible defaults:

```yaml
provider: github
repo: owner/repo

baseline:
  window: 50        # Number of runs for baseline computation
  refresh: daily     # How often to recompute baselines

detection:
  z_threshold: 3.0   # Modified Z-score threshold for drift alerts
  trend_window: 20    # Runs to consider for trend detection
  flaky_threshold: 0.1

stages:
  ignore:
    - cleanup        # Stages to exclude from monitoring
  budgets:
    test: 3m         # Time budgets per stage
    build: 5m

notifications:
  channels:
    - type: slack
      webhook: https://hooks.slack.com/...
      events: [drift, failure_spike, flaky_escalation]
```

## Contributing

Contributions are welcome! The easiest way to contribute is adding a new CI/CD provider — each one is a single Python file implementing the `PipelineProvider` interface.

See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions and guidelines.

## License

MIT — see [LICENSE](LICENSE) for details.
