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

---
phase: 04-cli-scaffolding-i18n-and-mail
plan: 01
subsystem: cli
tags: [scaffold, make, registry, gormigrate, bonfire, pact, wintercms]

requires:
  - phase: 01-framework-kernel-foundation
    provides: make:plugin, plugin:add, summer build, party.Plugin, pact capabilities
provides:
  - 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
affects: [04-02-i18n, 04-03-mail, 04-04-tests, plugin-porting]

tech-stack:
  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

key-files:
  created:
    - 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
  modified:
    - 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

key-decisions:
  - "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"

patterns-established:
  - "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"

requirements-completed: [CLI-02]

duration: 11 min
completed: 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*