vibegate 0.1.0a2

Deterministic production readiness gate for vibe-coded FastAPI repos.

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.0a2 (alpha).

Quickstart

1. Install from PyPI (recommended for meaningful results)

pip install "vibegate[dev]==0.1.0a2"

Optional with pipx:

pipx install "vibegate[dev]==0.1.0a2"

Minimal install (will fail if required tools are not present on PATH):

pip install vibegate==0.1.0a2

2. Initialize a repo

vibegate init .

3. Verify tooling

vibegate doctor .

4. Run the gate

vibegate check .

5. Review artifacts

VibeGate writes vibegate.yaml, .vibegate/suppressions.yaml, and generates artifacts/ plus evidence/. The report, fix pack, and JSONL evidence ledger are the audit trail for what ran and why it failed. artifacts/ and evidence/ are generated outputs and typically should not be committed.

Developer install

python -m pip install -e ".[dev]"

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

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

Run the gate after install:

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

Dev

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)

Troubleshooting

If vibegate.yaml fails schema validation, regenerate it or fix the required fields:

vibegate init . --force

This overwrites the existing vibegate.yaml. Or fix the required fields listed in the schema errors.

If you are pasting commands into zsh and # comments break execution, enable interactive comments with setopt interactivecomments.

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.