summercms/.planning/phases/02-api-parity-harness-bootstrap/02-PATTERNS.md

Phase 2 Pattern Map

Mapped: 2026-09-16

Planned file or area	Closest existing analog	Pattern to reuse
cmd/summer parity commands	cmd/summer/main.go, bonfire/command.go	Add three bonfire.Command values to toolCommands(), with Run(ctx, in, out) error, string flags, injected output, and colon names. Keep process exit handling in main().
CLI command tests	cmd/summer/main_test.go, bonfire/output_test.go	Assert command discovery and behavior through bonfire.NewRoot with injected writers; do not invoke a TTY or read real credentials.
tide framework library	No existing HTTP library in framework; internal/build is the closest separation example	Keep reusable types and behavior independent of Fonoteka route names. CLI calls package APIs; app corpus imports package by module path. Use context cancellation and explicit dependencies.
YAML fixture IO	internal/build/manifest.go	Strict decode, validate before use, deterministic output and atomic file write. Preserve raw JSON body text; reject unsafe relative paths for binary sidecars.
Proxy HTTP handling	Go net/http/httputil.ReverseProxy official API	Fixed upstream, Rewrite/SetURL, loopback listener, bounded body capture, restore body for forwarding. Avoid Director, which official docs deprecate.
Synthetic round-trip tests	internal/build/build_test.go, examples/hello/hello_test.go	Use temp directories and observable outputs. HTTP tests use httptest.Server; compare request/response bytes and CLI exit status.
App manifest and corpus	../fonoteka.go has no analog yet; PHP plugins/golem15/fonoteka/routes.php is source of truth	Create parity/manifest.yaml and parity/fixtures/{seed,nuxt,mcp,routes}. Route ids must encode HTTP method, full path pattern and auth group to distinguish repeated paths. Count 154 definitions.
App Postgres integration	No app code yet; Phase 1 scripts/check-phase1.sh demonstrates cross-module verification	parity/parity_test.go starts Testcontainers Postgres, runs a synthetic SQL-backed handler through httptest.Server, executes seed and route flows as subtests, and marks unported real routes pending. Later phases replace synthetic handler with app handler.
Phase-wide check script	scripts/check-phase1.sh	Run vet/test/race separately in root and sibling app module; root ./... does not traverse sibling modules. Reserve full coverage expansion for final plan.

Integration constraints

• bonfire.NewRoot accepts []bonfire.Command; no plugin registry or new CLI framework is needed.
• Framework go.mod currently has Cobra and Koanf but no YAML fixture or Testcontainers dependency. Add goccy/go-yaml to framework when needed; keep Testcontainers in app test module.
• The PHP source and existing Nuxt/MCP clients are read-only references for this phase. They are run against a fresh parity DB, not edited.
• ../fonoteka.go is a sibling repository. The executor needs write access there for app corpus and test files.