feat(pack-a): hygraph integration scaffold + CI + OpenAPI snapshot + pre-commit

[google-labs-jules]

This submission includes the initial scaffolding for the Paform project, focusing on "Pack A" and setting up the development environment. It includes a new CI/CD pipeline, an OpenAPI generation script, pre-commit hooks, and all the necessary configuration files and code stubs for the Hygraph integration. All feedback from previous code reviews has been addressed, and all tests are now passing.

---

PR created automatically by Jules for task 7502178388292399123

[google-labs-jules]

👋 Jules, reporting for duty! I'm here to lend a hand with this pull request.

When you start a review, I'll add a 👀 emoji to each comment to let you know I've read it. I'll focus on feedback directed at me and will do my best to stay out of conversations between you and other bots or reviewers to keep the noise down.

I'll push a commit with your requested changes shortly after. Please note there might be a delay between these steps, but rest assured I'm on the job!

For more direct control, you can switch me to Reactive Mode. When this mode is on, I will only act on comments where you specifically mention me with @jules. You can find this option in the Pull Request section of your global Jules UI settings. You can always switch back!

---

For security, I will only act on instructions from the user who triggered this task.

[shayancoin]

•	Async Hygraph client (or thread‑wrapped) with jitter & Retry‑After
•	fetch_modules & fetch_systems
•	Webhook /api/sync/hygraph: raw‑body HMAC verify; idempotency (event_id + body_sha256)
•	Admin /api/sync/hygraph/pull: bearer token (API_WRITE_TOKEN)
•	Upserts: JSONB external_ids.hygraph_id unique; soft‑delete/last_seen_at
•	CORS allowlist via env; error envelope unified
•	Alembic migration for materials/modules/systems/sync_events (+ GIN indexes)
•	Tests: signature valid/invalid, duplicate, pagination, upsert, pull auth
•	.env.example includes API_WRITE_TOKEN, CORS_ALLOW_ORIGINS
•	OpenAPI snapshot updated

⸻

Precise next steps (in order)
1. Refactor client to async (patch above); add fetch_modules/fetch_systems.
2. Add routes (routes_sync.py): webhook + pull; wire require_write_token.
3. Implement service (hygraph_service.py): mapping (normalize per‑m²), upserts, idempotency.
4. Migrations: add SyncEvent, is_archived, JSONB indexes/uniques.
5. Tests: use respx to mock Hygraph; cover retries, pagination, and idempotency; route auth tests.
6. CI: ensure Postgres service + alembic upgrade head run before tests.
7. Docs: DATA_MODEL.md mapping; OPERATIONS.md webhook setup/runbook.
8. Flip PR from Draft → Ready, request reviews from CODEOWNERS.

[google-labs-jules]

• Async Hygraph client (or thread‑wrapped) with jitter & Retry‑After
• fetch_modules & fetch_systems
• Webhook /api/sync/hygraph: raw‑body HMAC verify; idempotency (event_id + body_sha256)
• Admin /api/sync/hygraph/pull: bearer token (API_WRITE_TOKEN)
• Upserts: JSONB external_ids.hygraph_id unique; soft‑delete/last_seen_at
• CORS allowlist via env; error envelope unified
• Alembic migration for materials/modules/systems/sync_events (+ GIN indexes)
• Tests: signature valid/invalid, duplicate, pagination, upsert, pull auth
• .env.example includes API_WRITE_TOKEN, CORS_ALLOW_ORIGINS
• OpenAPI snapshot updated

⸻

Precise next steps (in order)

1. Refactor client to async (patch above); add fetch_modules/fetch_systems.
2. Add routes (routes_sync.py): webhook + pull; wire require_write_token.
3. Implement service (hygraph_service.py): mapping (normalize per‑m²), upserts, idempotency.
4. Migrations: add SyncEvent, is_archived, JSONB indexes/uniques.
5. Tests: use respx to mock Hygraph; cover retries, pagination, and idempotency; route auth tests.
6. CI: ensure Postgres service + alembic upgrade head run before tests.
7. Docs: DATA_MODEL.md mapping; OPERATIONS.md webhook setup/runbook.
8. Flip PR from Draft → Ready, request reviews from CODEOWNERS.

Thank you for the detailed next steps. I will begin working on the implementation of Pack A as outlined. I will create a new plan to address these requirements.