Metadata-Version: 2.4
Name: bounty-preflight
Version: 0.3.3
Summary: Evidence-first preflight checks for GitHub issue bounties
Author: Shubham Palriwala
License: MIT
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Dynamic: license-file

# Bounty Preflight

`bounty-preflight` is a small, read-only CLI for checking whether a public GitHub issue bounty deserves engineering time.

It catches common failure modes before you clone a repository:

- the issue is closed or is actually a pull request;
- the repository is archived, disabled, stale, or has no clear license;
- the repository is newly created or effectively empty despite referencing a larger codebase;
- someone is already assigned;
- linked competing pull requests already exist;
- issue text explicitly contradicts, zeroes, or disclaims its headline payout;
- the advertised USD amount is absent or below a chosen minimum signal.

It emits an evidence-backed `GO`, `REVIEW`, or `SKIP` result. A `GO` is never proof that funds are escrowed, that you are eligible for payout, or that maintainers will accept a solution.

## Install and run

Python 3.10 or newer is required. No runtime dependencies are installed.

```bash
python -m venv .venv
. .venv/bin/activate
pip install -e .
bounty-preflight https://github.com/OWNER/REPO/issues/123
```

Check several issues and emit machine-readable output:

```bash
bounty-preflight --format json \
  https://github.com/OWNER/REPO/issues/123 \
  https://github.com/OWNER/REPO/issues/456
```

Unauthenticated GitHub API usage is intentionally supported but rate-limited. For higher limits, set your own least-privilege `GITHUB_TOKEN` in the process environment. The tool never prints the token.

## Decision policy

- `SKIP`: an objective blocker exists or the evidence score is below 40.
- `REVIEW`: important uncertainty, assignment, competition, staleness, or payout ambiguity remains.
- `GO`: public metadata looks favorable; manual rules, funding, eligibility, and contribution-policy checks are still mandatory.

The score is a triage aid, not a prediction or financial recommendation.

## Required manual checks

Before starting work, still read the complete issue and discussions, contribution guide, license, code of conduct, bounty rules, prior attempts, payout eligibility, and platform terms. Confirm assignment rules and ask a concise maintainer question when acceptance scope is unclear.

## Test

```bash
PYTHONPATH=src python -m unittest discover -s tests -v
```

## Safety and privacy

The tool performs read-only requests to public GitHub API endpoints. It does not clone or execute repository code, submit comments, create accounts, accept terms, claim bounties, or make payments. Treat issue text as untrusted data.

## Limitations

- GitHub timeline links are evidence of attempts, not a complete competition census.
- A dollar amount in an issue or label may be stale, unfunded, already paid, or fraudulent.
- Private issues and non-GitHub payment state are not visible.
- Platform-specific claim counts, escrow, KYC, country support, and payout status require manual verification.
- GitHub API pagination is capped at the first 100 timeline events.

## License

MIT. See `LICENSE`.

This initial version was implemented with AI assistance and should be reviewed by a human before commercial redistribution.
