# VibeGate

VibeGate runs deterministic readiness checks for vibe-coded FastAPI repos and produces an evidence ledger plus a deterministic Fix Pack of remediation patches.

Current version: **0.1.0a1** (alpha).

## Quickstart

1) Install locally

```bash
pipx install -e .
# or
uv tool install -e .
```

2) Initialize a repo

```bash
vibegate init .
```

3) Verify tooling

```bash
vibegate doctor .
```

4) Run the gate

```bash
vibegate check .
```

5) Review artifacts

Artifacts land in `artifacts/` and evidence in `evidence/`. The report, fix pack, and
JSONL evidence ledger are the audit trail for what ran and why it failed.

## Demo

Try the demos:

- `examples/fastapi-demo/` (fails: a test expectation mismatch)
- `examples/fastapi-demo-fixed/` (passes)

Each demo includes a `run_vibegate.sh` script that runs `python -m vibegate.cli check .`
and prints where artifacts and evidence land.

## Local dev

```bash
make install
make test
make lint
make format-check
make typecheck
make gate
```

Run the gate after install:

```bash
vibegate check .
# or, always works and is more explicit
python -m vibegate.cli check .
```

## Dev

```bash
python -m pip install -e ".[dev]"
pytest
```

## Continuous Integration

CI runs a fast Ubuntu job on every pull request targeting `main`, and runs a broader
OS matrix on pushes to `main` (plus manual workflow dispatches). Each job installs dev
dependencies, runs the test/check steps, and always uploads debugging artifacts from
`artifacts/` and `evidence/` to the workflow run's "Artifacts" section in GitHub Actions.

### Expected output files

Defaults (can be overridden by `vibegate.yaml`):

- `artifacts/vibegate_report.md`
- `artifacts/fixpack.json`
- `artifacts/fixpack.md`
- `evidence/vibegate.jsonl`

Configuration contract:

- `vibegate.yaml` (validated against `schema/vibegate.schema.json`)

## What runs

Baseline checks:

- Formatting: `ruff format --check`
- Lint: `ruff check --output-format json`
- Typecheck: `pyright --outputjson`
- Tests: `pytest -q`
- Dependency hygiene: lockfile required + `uv lock --check` when UV is detected
- Config sanity: deterministic scanning for debug/uvicorn reload/cors/secret patterns

Optional when the tool is on `PATH`:

- `bandit` (JSON output)
- `gitleaks` (JSON output)
- `osv-scanner` offline only when a local DB snapshot is configured

## Evidence & Fix Pack

Evidence is written as JSONL with `run_start`, `tool_exec`, `finding`, `suppression_applied`, and `run_summary` events. Each tool execution records argv, cwd, duration, exit code, and artifact hashes.

Fix Pack output (`fixpack.json` + `fixpack.md`) is deterministic and ordered by category: dependency hygiene → vulnerability → secrets → security → typecheck → lint → formatting → tests → config → runtime.

## CLI

- `vibegate check [REPO_ROOT]` (defaults to `.`; exit 0 on PASS, 1 on FAIL, 2 on config error)
- `vibegate init [REPO_ROOT]` (scaffold `vibegate.yaml`, `artifacts/`, `evidence/`, `.vibegate/`)
- `vibegate doctor [REPO_ROOT]` (report missing tools + version drift)
- `vibegate fixpack` (runs checks, emits fix pack only, still writes evidence)
- `vibegate verify` (alias of `check`)
- `vibegate prompt` (stub)

## How to add VibeGate to an existing FastAPI repo

1. Add `vibegate.yaml` at the repo root using the contract schema in `schema/vibegate.schema.json`.
2. Set `project.app_module` to your ASGI entrypoint (e.g. `app.main:app`).
3. Commit a lockfile (`uv.lock`, `poetry.lock`, or `pdm.lock`) and ensure it stays fresh.
4. Add `.vibegate/suppressions.yaml` if you need to suppress known findings with justification and expiry.
5. Run `vibegate check` locally and in CI, and review `artifacts/fixpack.md` for remediation steps.
