idp-qa

name	idp-qa
description	Integration coherence verification guide for Narwhal IDP Portal. Performs API response shape vs frontend type cross-verification, routing consistency checks, role-based access control validation, and cache key conflict detection. Use this skill for verification, testing, QA, bug checks, or consistency checks. Triggers on 'verify', 'test', 'QA', 'check bugs', 'consistency'.

IDP Portal QA Verification

Integration coherence verification procedures for the Narwhal IDP Portal. Systematically detects boundary mismatches at connection points, even when individual modules are correct.

Verification Procedure

Step 1: API vs Frontend Response Shape Cross-Verification

Compare each API route's NextResponse.json() call with the corresponding component's fetch type.

1. Extract object shapes passed to NextResponse.json() in src/app/api/*/route.ts
2. Check the response type/access pattern in components calling that API
3. Compare whether shapes match
4. Verify wrapping (if API returns { items: [...] }, does the component unwrap .items?)

API-Component mappings (single source of truth — keep updated when adding new API routes):

API Route	Response Shape	Consumer Component
/api/metrics	{ cpu, memory, nodes, pods }	cluster-metrics.tsx
/api/argocd	{ total, synced, outOfSync, degraded, healthy }	argocd-status.tsx
/api/alerts	Alert[]	alerts-widget.tsx
/api/settings/users	KeycloakUser[]	users-table.tsx
/api/settings/routes	ApisixRoute[]	routes-table.tsx
/api/tools/health	per-service health status	tools-grid.tsx
/api/onboarding/kubeconfig	YAML text	kubeconfig-download.tsx

Step 2: Routing Consistency Verification

1. Extract URL patterns from src/app/(dashboard)/*/page.tsx file paths
   - (dashboard) → removed from URL
   - Result: /, /tools, /settings, /onboarding
2. Collect all menuItems[].href values from src/components/nav.tsx
3. Verify each href matches an actual page path
4. Also verify Link, router.push values within components

Step 3: Role-Based Access Control Verification

1. Check Nav menuItems roles arrays:
   - /: cluster-admin, developer, viewer
   - /tools: cluster-admin, developer, viewer
   - /settings: cluster-admin
   - /onboarding: cluster-admin, developer, viewer
2. Check PLATFORM_TOOLS[].roles in src/lib/tools.ts
3. Verify settings page data access is restricted to cluster-admin
4. Check if API routes have auth/permission checks

Step 4: Cache Key Conflict Check

1. Extract cache key strings from cacheGet/cacheSet calls in src/lib/*.ts
2. Check for collisions (same key, different data)
3. For dynamic keys (prom:{query}), check for overlapping queries

Step 5: Build Verification

pnpm build

Record build pass/fail and errors/warnings in the report. Note: build pass ≠ runtime correctness, so Steps 1-4 boundary verification is more important.

Report Format

# QA Verification Report

## Summary
- Passed: N
- Failed: N
- Unverified: N

## Failed Items

### [Item Name]
- Location: [file:line] vs [file:line]
- Issue: [specific mismatch description]
- Fix: [file, line, and change details]
- Severity: CRITICAL / WARNING / INFO