docs(01-03): complete Zod schema builder plan

- SUMMARY.md created for Plan 03 - STATE.md updated: progress 75%, decisions logged, session recorded - ROADMAP.md updated: phase 1 at 3/4 SUMMARY files
2026-03-26 10:22:28 +01:00
parent eaeae32849
commit 5a4bb475c1
3 changed files with 114 additions and 7 deletions
@@ -0,0 +1,104 @@
+---
+phase: 01-foundation
+plan: "03"
+subsystem: schema
+tags: [typescript, zod, validation, registry, tdd, vitest]
+
+# Dependency graph
+requires:
+  - 01-02 (BACKEND_REGISTRY, BackendType, FieldDef — src/schemas/registry.ts)
+provides:
+  - BACKEND_SCHEMAS constant with Zod schemas for azureblob, s3, s3-compatible (src/schemas/index.ts)
+  - BackendFormValues<T> utility type inferring TypeScript type from schema
+affects:
+  - Phase 3 (form validation — useForm resolver will use BACKEND_SCHEMAS[backendType])
+  - Phase 2 (type-safe form data via BackendFormValues before config generation)
+
+# Tech tracking
+tech-stack:
+  added: []
+  patterns:
+    - "Programmatic schema derivation: loop over BACKEND_REGISTRY to build z.object() — never hardcode field names in Zod schemas"
+    - "Registry-as-truth invariant: adding a field to BACKEND_REGISTRY automatically adds it to runtime validation"
+
+key-files:
+  created:
+    - src/schemas/index.ts
+  modified: []
+
+key-decisions:
+  - "buildZodSchema loops over BACKEND_REGISTRY[backendType] — field names never appear in Zod code, only in the registry"
+  - "required: true fields map to z.string().min(1) with label-based error message; optional fields map to z.string().optional()"
+  - "BACKEND_SCHEMAS exported as const object — TypeScript can narrow to the specific backend's schema type at call sites"
+
+patterns-established:
+  - "Schema-from-registry pattern: all Zod shape derivation goes through buildZodSchema(backendType)"
+
+requirements-completed: []
+
+# Metrics
+duration: 1min
+completed: 2026-03-26
+---
+
+# Phase 01 Plan 03: Zod Schema Builder Summary
+
+**Programmatic Zod schema builder that derives all validation from BACKEND_REGISTRY — adding a registry field automatically adds it to runtime validation, with no hardcoded field names in Zod code**
+
+## Performance
+
+- **Duration:** ~1 min
+- **Started:** 2026-03-26T09:20:32Z
+- **Completed:** 2026-03-26T09:21:21Z
+- **Tasks:** 1
+- **Files modified:** 1
+
+## Accomplishments
+
+- `buildZodSchema(backendType)` derives a `z.object()` shape entirely from `BACKEND_REGISTRY[backendType]` — no field names appear in `index.ts` itself
+- Required fields become `z.string().min(1, '{label} is required')`, optional fields become `z.string().optional()`
+- `BACKEND_SCHEMAS` exported as a const with typed entries for all three backends
+- `BackendFormValues<T>` utility type infers the TypeScript type from the appropriate schema via `z.infer`
+- All 8 tests in `index.test.ts` pass GREEN; `registry.test.ts` (7 tests) remains GREEN — full 15-test count
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Implement schema builder and BACKEND_SCHEMAS** - `eaeae32` (feat)
+
+**Plan metadata:** _(committed after SUMMARY.md — see final commit)_
+
+_Note: TDD — RED confirmed ("Cannot find module './index'"), then GREEN in single implementation commit._
+
+## Files Created/Modified
+
+- `src/schemas/index.ts` — buildZodSchema function, BACKEND_SCHEMAS constant, BackendFormValues type
+
+## Decisions Made
+
+- Used `z.string().min(1, ...)` for required fields rather than plain `z.string()` — provides a user-facing error message that includes the field label, useful when this schema is wired to react-hook-form in Phase 3
+- `as const` on BACKEND_SCHEMAS enables TypeScript to narrow the exact schema type per backend key (no `ZodObject<any>` widening)
+
+## Deviations from Plan
+
+None - plan executed exactly as written.
+
+## Issues Encountered
+
+None. The only full-suite "failure" (`reducer.test.ts`) is the intentional Wave 0 RED stub from Plan 02, documented there — not a regression.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- `src/schemas/index.ts` ready for Plan 04 context and Phase 3 form wiring
+- `BACKEND_SCHEMAS[backendType]` can be passed directly to `zodResolver()` from `@hookform/resolvers/zod`
+- `BackendFormValues<T>` provides the type-safe form data shape for Phase 2 config generation
+- Only remaining RED stub: `src/store/reducer.test.ts` — addressed in Plan 04
+
+---
+*Phase: 01-foundation*
+*Completed: 2026-03-26*