Files

Jakub Zych 9a69353220 docs(04-04): complete unit tests and Mailpit plan

Tasks completed: 3/3
- Close scaffold and CLI command boundary coverage
- Close translation lookup and catalog boundary coverage
- Close mail safety, driver, and Mailpit receipt coverage

SUMMARY: .planning/phases/04-cli-scaffolding-i18n-and-mail/04-04-SUMMARY.md
Co-authored-by: Cursor <cursoragent@cursor.com>

2026-09-18 14:13:14 +02:00

6.4 KiB

Raw Blame History

phase, plan, subsystem, tags, requires, provides, affects, tech-stack, key-files, key-decisions, patterns-established, requirements-completed, duration, completed

phase

plan

subsystem

tags

requires

provides

affects

tech-stack

key-files

key-decisions

patterns-established

requirements-completed

duration

completed

04-cli-scaffolding-i18n-and-mail

testing

scaffold

phrasebook

postcard

mailpit

testcontainers

i18n

phase	provides
04-cli-scaffolding-i18n-and-mail	six make commands, phrasebook Translator, postcard Mailer and drivers

adversarial unit coverage for CLI scaffolding, catalog lookup, and mail safety

Mailpit testcontainer SMTP receipt via HTTP API

scripts/check-phase4.sh root/hello/race/SMTP sign-off gate

plugin-porting

05-data-layer

added

patterns

copied hello workspace drives public make/build APIs then go build and go vet

Mailpit receipt is asserted through a separate HTTP API after go-mail SMTP send

testing.Short skips only Mailpit; missing Docker fails the full test

created

modified

postcard/templates_test.go

postcard/smtp_test.go

postcard/mailpit_test.go

scripts/check-phase4.sh

internal/build/build_test.go

cmd/summer/main_test.go

phrasebook/translator_test.go

party/registry_test.go

examples/hello/hello_test.go

Mailpit image is axllent/mailpit:v1.31.1; receipt is polled from /api/v1/messages then /api/v1/message/{ID}

fstest.MapFS WalkDir cannot host '..' keys; malformed lang paths are extra-segment and wrong-suffix files

Phase gate scripts refuse missing Docker instead of skipping SMTP

Hello activation tests obtain Translator from backpack and pass towel.WithLocale

CLI-02

I18N-01

I18N-03

8min

2026-09-18

Phase 4 Plan 04: Unit tests and Mailpit Summary

Adversarial coverage for six make artifacts, pl/en phrasebook lookup, and postcard mail, plus a real Mailpit SMTP receipt and scripts/check-phase4.sh

Performance

Duration: 8 min
Started: 2026-09-18T12:04:31Z
Completed: 2026-09-18T12:12:42Z
Tasks: 3
Files modified: 9

Accomplishments

Copied hello-app tests generate all six artifacts, compile and vet the workspace, reject malformed names/traversal/duplicates, and leave handwritten plugin.go untouched
Phrasebook catalog tests cover nested groups, invalid YAML/pipes, compass app.locale/fallback_locale, and hello activation through towel.WithLocale
Postcard memory tests preserve To/Cc/Bcc/ReplyTo and keep unsafe HTML out; SMTP TLS stays explicit; Mailpit HTTP API proves go-mail receipt; scripts/check-phase4.sh is the phase gate

Task Commits

Each task was committed atomically:

Task 1: Close scaffold and CLI command boundary coverage - 85bdb51 (test)
Task 2: Close translation lookup and catalog boundary coverage - 918e941 (test)
Task 3: Close mail safety, driver, and Mailpit receipt coverage - 9f6fbad (test)

Plan metadata: (this commit)

Files Created/Modified

internal/build/build_test.go - exact paths, workspace build/vet, malformed artifact names
cmd/summer/main_test.go - five make argument forms, --no-migration, public CLI execution
phrasebook/translator_test.go - catalog, pipe, locale-config, and substitution boundaries
party/registry_test.go - activation errors name plugin, file, and key
examples/hello/hello_test.go - backpack translator via towel.WithLocale; unknown mail template
postcard/templates_test.go - recipients, HTML safety, registration ownership
postcard/smtp_test.go - TLS policy and credential-free SMTP errors
postcard/mailpit_test.go - TestSMTPMailpit against axllent/mailpit:v1.31.1
scripts/check-phase4.sh - root vet/test, hello vet/test, focused race; Docker required

Decisions Made

Mailpit receipt is observed through the HTTP API after SMTP send, not by trusting Send's return value
testing.Short skips only the Mailpit container test; a full go test ./postcard -run TestSMTPMailpit fails when Docker is unavailable
Malformed lang-path cases use extra segments and wrong suffixes because fstest.MapFS WalkDir recurses on .. keys

Deviations from Plan

Auto-fixed Issues

1. [Rule 1 - Bug] fstest.MapFS cannot walk .. fixture keys

Found during: Task 2 (path traversal catalog case)
Issue: lang/en/../pl/lang.yaml in fstest.MapFS caused WalkDir to recurse until a stack overflow
Fix: Cover malformed paths with extra-segment, .yml, and non-lang/ prefixes; parseLangPath still rejects .. when it appears in a cleaned path
Files modified: phrasebook/translator_test.go
Verification: go test ./phrasebook -short -count=1 PASS
Committed in: 918e941 (Task 2 commit)

2. [Rule 3 - Blocking] cobra help omits optional-arg descriptions

Found during: Task 1 (CLI argument-form assertions)
Issue: make:migration --help prints [plugin] [name], not the Arg Description vendor.plugin
Fix: Assert the real Usage forms [plugin] [name] and --no-migration; keep vendor.plugin on required make:plugin
Files modified: cmd/summer/main_test.go
Verification: go test ./cmd/summer -run TestToolCommandNames -count=1 PASS
Committed in: 85bdb51 (Task 1 commit)

Total deviations: 2 auto-fixed (1 bug, 1 blocking) Impact on plan: No production API changes. Tests cover the same contracts with fixtures cobra and fstest can actually execute.

Issues Encountered

None

User Setup Required

None - no external service configuration required. Mailpit runs in Docker via testcontainers; production SMTP stays in mail.* / SUMMER_MAIL__.

Next Phase Readiness

Phase complete, ready for next step. Scaffolding, phrasebook, and postcard contracts now have failing-when-broken tests including a real SMTP receipt. scripts/check-phase4.sh is the sign-off gate and requires Docker.

Verification

go test ./internal/build ./cmd/summer -run 'TestScaffoldAllArtifacts|TestModelsLeaf|TestToolCommandNames' -short -count=1 — PASS
go test ./phrasebook ./party -short -count=1 && go -C examples/hello test ./... — PASS
go test ./postcard -run 'TestMail|TestSMTPMailpit' -short -count=1 — PASS (Mailpit skipped under -short)
go test ./postcard -run TestSMTPMailpit -count=1 — PASS (Docker/Mailpit receipt)
./scripts/check-phase4.sh — PASS (root vet/test including Mailpit, hello vet/test, race)

Self-Check: PASSED

Phase: 04-cli-scaffolding-i18n-and-mail Completed: 2026-09-18

6.4 KiB Raw Blame History