🧪🔒 API Contract, CI Judgment, and Runtime Hardening

[AdaInTheLab]

This is a foundational PR that introduces OpenAPI as a first-class contract for the Lab API, adds CI test enforcement (Carmel Judgment™), and hardens app startup so optional tooling never breaks tests or development.

Yes, it’s a large PR — intentionally. These changes are tightly related and land the system in a stable, coherent state instead of passing through half-wired intermediate steps.

---

✨ Why this exists

We’re moving toward a clear authoring and delivery pipeline:

Markdown → CLI → API → Admin UI

To support that safely, the API needed:

• a formal contract (OpenAPI)
• admin-only access to that contract
• validation that does not break tests or dev
• CI enforcement so broken changes never deploy

This PR establishes those boundaries cleanly.

---

🧩 What changed

API Contract & Docs

• Introduced OpenAPI spec as the API contract
• Exposed /openapi.json as an admin-only endpoint
• Removed server-side Swagger UI
• Docs UI now lives in the React admin app

Validation (Optional, Guarded)

• Added express-openapi-validator
• Validator is:
  • enabled only when the spec exists
  • disabled in test environments
• Missing docs no longer crash app startup

Runtime Hardening

• Fixed duplicate / unconditional middleware registration
• Clarified startup order and environment boundaries
• Ensured tests run against core API behavior only

CI (Carmel Judgment 😼)

• Added dedicated CI workflow to run tests on push / PR
• Deploys are gated on passing tests
• CI logs clearly communicate pass/fail state

---

🧪 Testing notes

• Validator is intentionally disabled in tests
• Tests now run against:
  • in-memory / isolated runtime behavior
  • without docs, auth tooling, or file system coupling
• CI runs the full test suite automatically

---

🧠 Design decisions (intentional)

• OpenAPI is treated as optional infrastructure, not a runtime dependency
• Admin auth uses existing GitHub Device Flow (no fake sessions)
• Large PR chosen to avoid merging half-configured states

---

🚧 Follow-ups (out of scope here)

• Polish admin docs UI
• Expand OpenAPI coverage
• CLI quality-of-life improvements (slug generation, dry-run, etc.)

Those will now be small, focused PRs thanks to this groundwork.

---

🐾 Verdict

Carmel has reviewed the tests.
Lyric has verified continuity.

This PR moves the API from “working” to trustworthy.