2 Commits

Author	SHA1	Message	Date
shankar0123	38f1200f26	fix(api,codegen): ARCH-001-A — Phase 1 Orval codegen + 2 new CI guards (large diff) ... Sprint 5 unified-master-audit closure. Pre-fix: - api/openapi.yaml: 7,788 LOC of hand-authored spec. - web/src/api/generated/: directory did NOT exist (the Phase-5 scaffolding never had its first generation run). - scripts/ci-guards/openapi-codegen-drift.sh: skip-when-absent (line 33-39 — informational scaffold). - api/openapi.yaml info.version: '2.0.0', latest tag: v2.1.7 (a 7-version drift between spec and ship). Net effect: every new route required three coordinated edits (Go handler, openapi.yaml, frontend client.ts), payload-level breaking changes shipped unnoticed, and downstream API client integration cost was permanent. Phase 1 fix (the audit's literal scope): 1. **Run Orval**, commit the generated tree. 316 files / ~1.8 MB under web/src/api/generated/, tags-split layout (one directory per OpenAPI tag), TanStack Query client mode. All output routes through web/src/api/mutator.ts which delegates to the existing fetchJSON in client.ts so auth/CSRF/401-event semantics stay in one place. 2. **Fix two spec defects** the first orval run surfaced: - YAML duplicate-key bug at L77-89 — SCEP's description was misplaced under OIDC. Restored to its own tag entry. - Missing #/components/schemas/Error referenced by three operations. Aliased to the existing ErrorResponse schema. 3. **Flip the codegen-drift guard from skip-when-absent to hard-gate.** A missing generated/ directory now fails the build with an actionable restore command. The existing regenerate-and-diff path stays as before. 4. **New openapi-version-tag-parity CI guard.** Asserts openapi.yaml info.version equals the latest v* git tag. Falls back to api.github.com when the local clone is shallow. Bumped openapi.yaml info.version 2.0.0 → 2.1.7 in the same commit so the new guard greens out. 5. **CI workflow** updated to fetch tags on the frontend job's checkout so the parity guard reads them locally (the GH API fallback still works but adds a network round-trip). Verified locally: - openapi-codegen-drift.sh: clean (re-generation produces byte-identical tree to what's tracked). - openapi-version-tag-parity.sh: clean (2.1.7 == v2.1.7). - tsc --noEmit: exit 0 across the entire frontend (the generated tree's responseType field threaded through the mutator's CertctlFetchOptions cleanly). - Existing Vitest suite: 141/141 pass on the three sampled suites (AuthProvider + client + IssuerHierarchyPage). Follow-on work (NOT in this commit): - Per-consumer migration: pages flip from client.ts imports to generated/ imports one at a time. Both styles share fetchJSON semantics, so the migration is incremental. - Server-side oapi-codegen handler stubs (Phase 2 from the audit's fix language) — separate sprint. Closes ARCH-001-A.	2026-05-16 05:19:22 +00:00
shankar0123	3c81531398	ci: OpenAPI parity reconciliation + codegen scaffolding (Phase 5 — ARCH-H1 / ARCH-M6) ... Phase 5 reconciliation: the audit's headline framing 'ARCH-H1 = 62-route OpenAPI gap' was a measurement scoping error. Every one of the 209 unique router routes is already accounted for — 154 in api/openapi.yaml, 55 in api/openapi-handler-exceptions.yaml. The existing openapi-handler-parity.sh CI guard already enforces this and passes clean today. The audit subtracted operation-count from route-count without accounting for the documented exceptions YAML. Where real work remains (and what this PR does about it) ========================================================= Of the 64 documented exceptions, 35 are legitimate wire-protocol carve-outs that MUST stay (SCEP RFC 8894 × 8 entries, ACME RFC 8555 default + per-profile × 27 entries — they're protocol contracts, not REST resources). The remaining 29 are REST-shaped routes whose OpenAPI ops were deferred during their original Bundle 2 / audit-2026-05-10 / 2026-05-11 work: - auth/sessions (3) - auth/oidc admin (9) - auth/breakglass admin (4) - auth/users mgmt (3) - auth/runtime-config (1) - auth/demo-residual/cleanup (1) - audit/export (1) - auth/logout (1) - auth/breakglass/login (1) - auth/oidc {login,callback,bcl} (3) - oidc/providers/{id}/jwks-status (1) - + 2 other auth-flow routes Burn-down plan in 3 sprints (documented in api/openapi-handler-exceptions.yaml header): Sprint A: Cluster 1 — sessions + oidc admin (12 ops) Sprint B: Cluster 2 — breakglass + users + runtime-config (8 ops) Sprint C: Cluster 3 — audit/export + auth flows (9 ops) This PR does NOT author the 29 OpenAPI ops; each needs request/ response schemas, not placeholders, and the design work is too large for one PR. The reconciliation here is documentation + a CI guard that will fail any future schema-drift, plus the scaffolding needed for sub-phase 5b. Sub-phase 5b: codegen scaffolding ================================== Adds the orval scaffolding without running npm install (sandbox disk-full; first 'npm install' + 'npm run generate' happens on the operator's workstation): - web/orval.config.ts — codegen config emits react-query hooks from api/openapi.yaml into web/src/api/generated/ - web/package.json — adds orval@^7.0.0 devDep + 'generate' npm script - web/CODEGEN.md — operator-facing migration doc: first-time setup, per-consumer migration pattern, burn-down plan, CI-guard rules - scripts/ci-guards/openapi-codegen-drift.sh — blocks the build when api/openapi.yaml changes but web/src/api/generated/ wasn't regenerated alongside. Currently no-op (the directory doesn't exist yet); activates from the first 'npm run generate' run. The legacy web/src/api/client.ts stays in tree per the phase prompt's 'do not delete in same PR as codegen' rule. Consumers migrate one page at a time as their OpenAPI ops land; client.ts deletion is a SEPARATE follow-up PR after the last consumer migrates. Updates to existing guard + exceptions YAML ============================================ - scripts/ci-guards/openapi-handler-parity.sh header rewritten with the Phase 5 reconciliation numbers (220/158/64/0) and the wire-protocol vs REST-deferred classification. - api/openapi-handler-exceptions.yaml header rewritten with the 35/29 split + the 3-sprint burn-down plan. Each exception entry is unchanged; the header now documents which entries are permanent (wire-protocol) vs temporary (REST-deferred). Sandbox limitations + operator follow-up ========================================= - 'npm install' was NOT run from the sandbox (sessions volume 99%-full, 142 MB free). The operator runs 'cd web && npm install' on their workstation; this lands orval@^7.0.0 in node_modules, then 'cd web && npm run generate' produces the initial web/src/api/generated/ tree. - First per-consumer migration (suggested: web/src/pages/AuthSettings or one of the operator-decision pages) lands in a follow-up PR after npm install completes. - The 29-op OpenAPI burn-down is a 2-sprint effort tracked under ARCH-H1 in cowork/certctl-architecture-diligence-audit.html. All CI guards (openapi-handler-parity, openapi-codegen-drift, plus every existing guard) verified clean by running each individually. Closes: - cowork/certctl-architecture-diligence-audit.html#fix-ARCH-H1 (reconciliation: gap is 0 with exceptions accounted for; burn-down plan documented for follow-up sprints) - cowork/certctl-architecture-diligence-audit.html#fix-ARCH-M6 (codegen scaffolding shipped; client.ts deletion follows in a subsequent PR after consumers migrate)	2026-05-13 20:24:20 +00:00