summercms/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-01-SUMMARY.md

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	01	cli	scaffold make registry gormigrate bonfire pact wintercms	phase provides 01-framework-kernel-foundation make:plugin, plugin:add, summer build, party.Plugin, pact capabilities	six make commands that emit compiling Winter-shaped plugin artifacts generated per-plugin registry.gen.go accessors models-leaf sibling-import check in summer build pact Job, AdminController, HasLang, and HasMailTemplates contracts	04-02-i18n 04-03-mail 04-04-tests plugin-porting	added patterns embedded text/template stubs under internal/build/stubs atomic registry.gen.go refresh from generated leaf constructors models/ is a leaf package enforced at build time	created modified internal/build/registry.go internal/build/leaf.go internal/build/artifact.go internal/build/stubs/plugin.tmpl internal/build/stubs/registry.tmpl internal/build/stubs/artifacts.tmpl internal/build/scaffold.go internal/build/build.go internal/build/build_test.go cmd/summer/main.go cmd/summer/main_test.go pact/capabilities.go bonfire/command.go bonfire/root.go	registry.gen.go is regenerated by scanning Code generated by summer make files, not by rewriting plugin.go make:model table names are vendor_plugin_plural_snake with explicit gormigrate CREATE/DROP TABLE models sibling-import check runs in build.App before go build and reports plugin ID, file, and import	Generated plugin.go calls generatedModels/Migrations/Commands/Jobs/AdminControllers; handwritten plugins get a one-time accessor hint Stub sources render from named embedded templates and pass go/format before write	CLI-02	11 min	2026-09-18

Phase 4 Plan 01: CLI scaffolding Summary

Six summer make:* commands emit Winter-shaped, vet-clean plugin artifacts wired through registry.gen.go, and summer build rejects models/ sibling imports by plugin ID, file, and path

Performance

• Duration: 11 min
• Started: 2026-09-18T11:29:54Z
• Completed: 2026-09-18T11:41:29Z
• Tasks: 3
• Files modified: 14

Accomplishments

• make:plugin now scaffolds the Winter directory shape: root plugin.go/routes.go, leaf doc.go packages, embeddable config/, lang/en/, and views/mail/ assets, plus empty registry.gen.go accessors
• make:model, make:migration, make:command, make:job, and make:admin-controller write compiling stubs, infer plugin ID from plugin.go, refuse duplicates, and refresh sorted registry slices without touching handwritten plugin.go
• summer build inspects each manifest plugin's models/ imports before go build and fails when a sibling package is imported

Task Commits

Each task was committed atomically:

1. Task 1: Prove and create the compiling Winter-shaped plugin path - 1edf9d7 (feat)
2. Task 2: Generate model, migration, and command slices - d8c5650 (feat)
3. Task 3: Generate jobs and admin controllers, then enforce model imports - c87bbc3 (feat)

Plan metadata: (this commit)

Files Created/Modified

• pact/capabilities.go - Job, AdminController, HasLang, HasMailTemplates contracts
• internal/build/stubs/plugin.tmpl - named templates for plugin.go, routes.go, leaf doc.go, go.mod
• internal/build/stubs/registry.tmpl - generated registry accessors
• internal/build/stubs/artifacts.tmpl - model, migration, command, job, admin controller, YAML templates
• internal/build/scaffold.go - template-driven MakePlugin Winter layout
• internal/build/registry.go - deterministic atomic registry.gen.go generation and scan
• internal/build/artifact.go - MakeModel/Migration/Command/Job/AdminController
• internal/build/leaf.go - models sibling-import enforcement
• internal/build/build.go - runs the leaf check before go build
• cmd/summer/main.go - five new make commands plus --no-migration
• bonfire/command.go, bonfire/root.go - Bare flags so --no-migration needs no value
• internal/build/build_test.go - smoke, core artifacts, all-six, and leaf rejection tests

Decisions Made

• Registry ownership stays in generated files marked Code generated by summer make; handwritten plugin.go is never rewritten and existing plugins receive an accessor hint
• Model tables are {vendor}_{plugin}_{plural_snake} with timestamps and an explicit gormigrate create/drop migration; --no-migration omits only that file
• Job stubs implement pact.JobArgs.Kind and pact.Job.Work with an unexpected-type error and no River import
• Admin stubs implement ID/ModelName/ConfigDir and write controllers/<name>/fields.yaml plus columns.yaml

Deviations from Plan

Auto-fixed Issues

1. [Rule 3 - Blocking] Bare flag support for --no-migration

• Found during: Task 2 (make:model --no-migration)
• Issue: bonfire only registered cobra string flags, so --no-migration required a value and could not match D-13
• Fix: Added Flag.Bare and cobra NoOptDefVal=true so --no-migration is a valueless true flag
• Files modified: bonfire/command.go, bonfire/root.go, cmd/summer/main.go
• Verification: TestScaffoldCoreArtifacts omits only the model migration; go test ./bonfire still green
• Committed in: d8c5650 (Task 2 commit)

2. [Rule 2 - Missing Critical] Artifact helpers live in artifact.go

• Found during: Task 2
• Issue: Plan listed Make* work on scaffold.go; adding five generators there would bury path validation and registry refresh
• Fix: Keep MakePlugin in scaffold.go and put make:model/migration/command/job/admin-controller in internal/build/artifact.go
• Files modified: internal/build/artifact.go
• Verification: All make tests pass through the exported Make* APIs used by cmd/summer
• Committed in: d8c5650 / c87bbc3

---

Total deviations: 2 auto-fixed (1 blocking, 1 missing critical) Impact on plan: No behavior divergence from D-10–D-17. Bare flags were required for the documented --no-migration UX.

Issues Encountered

None

User Setup Required

None - no external service configuration required.

Next Phase Readiness

Ready for 04-02 (phrasebook / i18n). Generated plugins already implement pact.HasLang and pact.HasMailTemplates with embeddable assets. Unit-test coverage remains the last plan (04-04).

Verification

• go test ./internal/build ./cmd/summer -run 'TestScaffoldPluginSmoke|TestScaffoldCoreArtifacts|TestScaffoldAllArtifacts|TestModelsLeaf|TestToolCommandNames' -short -count=1 — PASS
• go vet ./... && go test ./... — PASS

Self-Check: PASSED

---

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