Metadata-Version: 2.4
Name: gavel-tools
Version: 0.1.0
Summary: The pre-publish check for open-source repos: secrets, structure, and a README proven to work on fresh installs.
Author: Jared
License: MIT
License-File: LICENSE
Keywords: cli,oss,pre-publish,release,secrets
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: Topic :: Utilities
Requires-Python: >=3.11
Requires-Dist: pydantic>=2.7
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Description-Content-Type: text/markdown

# Gavel

*The pre-publish check for open-source repos.*

One question before you push public: **does it work on a fresh install?**
Gavel answers it in seconds — deterministically, locally, with no account
and no network calls — and it fails loudly enough to gate CI.

## What it checks

| Check | FAILs on | WARNs on |
|---|---|---|
| **Secrets & credentials** | AWS/GitHub/OpenAI/Slack token patterns, private key blocks, high-entropy values assigned to secret-looking names | — |
| **Required files** | missing `LICENSE` or `README.md` | missing `.gitignore` |
| **Committed junk** | committed `.env` files | `__pycache__`, `node_modules`, `.venv`, `dist`, `build`, compiled artifacts, blobs > 5 MB |
| **README quality** | — | no install section, no usage section, no code blocks, suspiciously short |

In a git repo, gavel judges **exactly what a fresh clone contains** — the
tracked file set (`git ls-files`). Outside git, it walks the tree (minus VCS
internals).

## Install

From source (today):

```bash
git clone https://github.com/UpsettiSpegetti/gavel
cd gavel
pipx install .
```

From PyPI (once published):

```bash
pipx install gavel-tools  # gavel:skip -- not live until the PyPI publish
```

## Usage

```bash
gavel check .              # terminal report; exit 1 on any FAIL
gavel check . --out report.md   # also write a markdown report
gavel brief .              # emit the fresh-install review brief (see below)
gavel prove .              # execute the README's quickstart in a throwaway venv
```

## The prove runner

Rules can check that instructions *exist*. `gavel prove` checks that they
*work*: it lifts the commands from your README's install/usage sections and
runs them to find out whether the application works on a fresh install, inside
its own triggered virtual environment, locally hosted on your device. First
failure stops the chain and shows the output.

- Isolated: a throwaway venv is created for the run and deleted after.
- Guarded: destructive command shapes (curl-pipes, sudo, deletions) are
  skipped by denylist, and every step has a timeout.
- Declarative: a step marked `# gavel:skip` is reported as skipped, not run --
  for steps that only go live at publish time.
- Honest: it may use the network for dependency resolution, and it executes
  your README's commands -- that's the point. `gavel check` stays read-only;
  proof is the opt-in exception.

## The fresh-install review

Rules verify structure; `gavel prove` verifies execution. One question
remains that neither can settle: *does the README explain itself well enough
for a first-time installer to succeed?* That last step is judgment, so gavel
stays model-free and **emits a brief** (`gavel brief`) that any AI harness,
or any honest human, can answer:

1. With only this page, could you install and run this tool in five minutes?
2. What would you still not trust about it?
3. One-line verdict: SHIP or FIX FIRST.

The judgment belongs to the reviewer. The gate belongs to the rules.

## Suppressing a finding

A line containing `gavel:allow` is skipped by the secrets scan. Use it for
documented fixtures and examples — never to hide a real key; the marker is
visible in the diff forever.

## Safety stance

- Read-only. Gavel never writes to the repo it checks (reports go where you point `--out`).
- No network, no telemetry, no account. Uninstall is deleting the folder.
- Findings name the file and line — no vague anxiety, only actionable evidence.

## License

MIT — see [LICENSE](LICENSE).
