diff --git a/.planning/phases/02-api-parity-harness-bootstrap/02-02-SUMMARY.md b/.planning/phases/02-api-parity-harness-bootstrap/02-02-SUMMARY.md new file mode 100644 index 0000000..5d11ead --- /dev/null +++ b/.planning/phases/02-api-parity-harness-bootstrap/02-02-SUMMARY.md @@ -0,0 +1,154 @@ +--- +phase: 02-api-parity-harness-bootstrap +plan: 02 +subsystem: testing +tags: [tide, parity, proxy, capture, normalize, manifest, coverage] + +requires: + - phase: 02-api-parity-harness-bootstrap + provides: Version-1 tide Flow/Step, LoadFlow/SaveFlow, RecordFlow/ReplayFlow, parity:record and parity:replay +provides: + - Loopback httputil reverse proxy grouping named Nuxt/MCP sessions + - Named capture, private variable store, and credential scrub into placeholders + - Shape-aware JSON normalizer and D-13/D-14/D-15 comparison classes + - Generic manifest recorder with --next-batch 15 --resume and coverage table +affects: [02-03, 02-04, 02-05] + +tech-stack: + added: [] + patterns: + - ReverseProxy Rewrite/SetURL pins a loopback upstream; client Host is ignored + - Secrets live in a mode-0600 --vars file outside fixtures; YAML holds {{name}} placeholders + - Dates and integer ids are asserted then masked at compare time; slugs stay exact + - Manifest pending mismatches are measured; ported mismatches and --self-check fail the run + +key-files: + created: + - tide/proxy.go + - tide/rules.go + - tide/variables.go + - tide/normalize.go + - tide/manifest.go + - tide/report.go + - tide/proxy_test.go + - tide/rules_test.go + - tide/capture_test.go + - tide/normalize_test.go + - tide/diff_test.go + - tide/headers_test.go + - tide/flow_test.go + - tide/manifest_test.go + modified: + - tide/flow.go + - tide/fixture.go + - tide/record.go + - tide/replay.go + - tide/diff.go + - cmd/summer/parity.go + - cmd/summer/parity_test.go + - cmd/summer/main.go + +key-decisions: + - "Proxy bind and upstream must be loopback HTTP; incoming Host/URL never selects the PHP origin" + - "Capture rules and a private 0600 variable store drive {{jwt:alice}} substitution; unclassified credential shapes fail fixture writes" + - "Carbon *_at values must match +00:00 before masking; Z, string ids, null vs [] and missing keys fail at $.path" + - "154 is the app manifest's validated route count, not a framework constant; this workflow refuses --next-batch above 15" + +patterns-established: + - "Pattern: X-Parity-Session or --session names a flow written to nuxt/.yaml or mcp/.yaml" + - "Pattern: Replay continues after comparison diffs and skips only the remainder of a flow after a failed capture" + - "Pattern: --update is required to overwrite an existing case fixture; --resume skips valid hashed fixtures" + +requirements-completed: [QA-01, QA-02, QA-03] + +duration: 12min +completed: 2026-09-17 +--- + +# Phase 2 Plan 2: Capture Sessions and Manifest Coverage Summary + +**Loopback `parity:proxy` records scrubbed multi-step sessions, and `parity:record --manifest` resumes 15-route batches with a recorded/passing/failing/unrecorded coverage table** + +## Performance + +- **Duration:** 12 min +- **Started:** 2026-09-17T10:24:42Z +- **Completed:** 2026-09-17T10:36:58Z +- **Tasks:** 3 +- **Files modified:** 21 + +## Accomplishments + +- `parity:proxy` forwards a named session to a fixed loopback upstream, preserves cookies/redirects/bytes, and writes ordered flows without partial or credential-shaped fixtures +- Named captures populate a private `--vars` store; replay expands placeholders before send and scrubs JWT, `inv_` tokens, OAuth codes, PKCE verifiers and `auth_token` cookies +- Manifest mode records one-step route cases, refuses silent overwrite, resumes at most 15 unrecorded routes, and prints coverage; pending mismatches do not fail unless `--self-check` + +## Task Commits + +Each task was committed atomically: + +1. **Task 1: Capture a complete named session through the proxy** - `bb6a5a9` (feat) +2. **Task 2: Replay stateful flows with safe capture and strict differences** - `aa165fe` (feat) +3. **Task 3: Record manifest route cases and report complete coverage** - `24c1f43` (feat) + +**Plan metadata:** pending `docs(02-02)` commit + +## Files Created/Modified + +- `tide/proxy.go` - Loopback ReverseProxy, session grouping, overflow and flush +- `tide/rules.go` - Strict YAML capture rules keyed by method and path pattern +- `tide/variables.go` - Store, capture, placeholder expand and secret scrub +- `tide/normalize.go` - Carbon `+00:00` and integer id assertions before masking +- `tide/manifest.go` - Generic manifest load/validate/record/replay +- `tide/report.go` - Coverage table and recorded/passing/failing/unrecorded counts +- `tide/diff.go` / `tide/replay.go` / `tide/record.go` - Header allow-list, sidecar digest, continue-on-mismatch +- `cmd/summer/parity.go` - `parity:proxy` plus `--manifest`, `--vars`, `--next-batch`, `--self-check` + +## Decisions Made + +- Keep the proxy on plain HTTP loopback with `Rewrite`/`SetURL`; tests may override upstream only with a loopback httptest URL +- Persist seed captures only in `--vars` (mode 0600, outside the fixture tree); fixtures and logs hold placeholders +- Compare global Content-Type/pagination/CORS plus per-route Cache-Control, Pragma, WWW-Authenticate and Content-Disposition; never Date, Server or request ids +- `--next-batch` above 15 is refused; omitting the flag records all remaining synthetic routes so small tests stay simple + +## Deviations from Plan + +### Auto-fixed Issues + +None - plan executed as written. TDD_MODE=false used one green commit per task (tests + implementation together), matching 02-01. Toolchain `go1.27.0` was left untouched (no new module). SaveFlow still uses the dedicated YAML writer from 02-01. + +--- + +**Total deviations:** 0 auto-fixed +**Impact on plan:** None. 02-01 deviations (toolchain pin, SaveFlow encoder) were preserved. + +## Issues Encountered + +None. QA-01/QA-02/QA-03 remain phase-level: this plan delivers proxy sessions, strict diffs and a generic manifest runner, not the 154-route PHP corpus (Plan 03) or testcontainers (Plan 04). Frontmatter copies the plan's requirements list; they should not be treated as milestone-complete. + +## User Setup Required + +None - no external service configuration required. + +## Next Phase Readiness + +Ready for 02-03-PLAN.md (PHP capture and the app 154-route manifest). Public APIs added: `NewProxy`, `LoadRules`, `OpenStore`, `LoadManifest`, `RecordManifest`, `ReplayManifest`, `Coverage`. + +## Verification + +- Task 1: `go test ./tide ./cmd/summer -run 'TestProxy|TestParityCommands'` pass +- Task 2: `go test ./tide -run 'TestProxy|TestCapture|TestScrub|TestNormalize|TestDiff|TestHeaders|TestFlow'` pass +- Task 3: `go test ./tide ./cmd/summer -run 'TestManifest|TestCoverage|TestParityCommands'` pass +- Plan: `go vet ./...` and `go test ./...` exit 0 +- No Fonoteka/Płytarium route names in `tide` or `cmd/summer` production sources + +## Self-Check: PASSED + +- [x] Key files exist on disk +- [x] `git log --grep=02-02` returns Task 1, Task 2 and Task 3 commits +- [x] Task acceptance criteria re-run and pass +- [x] Plan verification commands pass + +--- +*Phase: 02-api-parity-harness-bootstrap* +*Completed: 2026-09-17*