Skip to content

FRONTDOOR.md

Latest commit

 

History

History
58 lines (42 loc) · 2.7 KB

FRONTDOOR.md

File metadata and controls

58 lines (42 loc) · 2.7 KB
Raw

🚪 FRONTDOOR.md — onboarding health dashboard

Continuous, structured, deterministic dashboard of the repo's clone-to-working front door. Every finding carries a check in the Deterministic checks block below, so each status is verified by re-running a command, not asserted. Refresh this board whenever an onboarding-facing doc (README.md, ROUTER.md, AGENTS.md) or the repo structure changes.
Last audited 2026-07-21 (HEAD — what a cold clone gets)
Method front-door walk, read-only
Verdict ✅ Smooth — A newcomer reaches working successfully.

Health at a glance

Dimension Status One-liner
One front door ✅ README.md is the single canonical entry point
🔑 Leaked secrets ✅ 0 provider-format keys (tree + history spot-check)
First success works ✅ Tests pass successfully with 5/5, no accounts or keys required

Findings

Severity 🔴 high · 🟠 med · 🟡 low — Status ⬜ OPEN · ✅ FIXED

ID Area Sev Status Fix (doc-only)
FD-01 Install Path 🔴 ✅ Add missing alembic upgrade head step to README.md
FD-02 Install Path 🟠 ✅ Add uv installation prerequisite to README.md
FD-03 Config 🟠 ✅ Ensure local uv run pytest falls back to localhost:55432 for DATABASE_URL via conftest.py

Verified baselines (keep green)

  • ✅ Secrets clean — no provider-format key in the tracked tree or the history spot-check.
  • ✅ One front door — README.md is the single front door for human readers.
  • ✅ First success — uv run pytest passes successfully without any required API keys.

Deterministic checks — re-run to refresh

Empty output = all green. Any line printed names an OPEN finding.

# Run from the repo root.
EXPECTED_TESTS=5  # updated by hand after a manual pytest run

# FD-01 — README must mention alembic upgrade head
grep -q "alembic upgrade head" README.md || echo "FD-01 OPEN: README doesn't tell users to run migrations"

# FD-02 — README must mention uv installation
grep -q "https://docs.astral.sh/uv" README.md || echo "FD-02 OPEN: README doesn't point users to uv installation"

# FD-03 — conftest.py must set DATABASE_URL
grep -q "os.environ\[\"DATABASE_URL\"\]" tests/conftest.py || echo "FD-03 OPEN: conftest.py is missing the DATABASE_URL fallback"

# Baseline — secrets must stay clean
git grep -IE '(sk-[A-Za-z0-9]{20}|ghp_[A-Za-z0-9]{30}|AKIA[0-9A-Z]{16}|-----BEGIN [A-Z ]*PRIVATE KEY-----)' -- ':!*.xyz*' >/dev/null 2>&1 \
  && echo "BASELINE BROKEN: provider-format secret in the tracked tree — rotate then purge"