From 6ce67a5d5b95cba2a0dd7a06fddec40f641bd1c5 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Fri, 18 Sep 2026 13:42:00 +0200 Subject: [PATCH] docs(04-01): complete CLI scaffolding plan Tasks completed: 3/3 - Prove and create the compiling Winter-shaped plugin path - Generate model, migration, and command slices - Generate jobs and admin controllers, then enforce model imports SUMMARY: .planning/phases/04-cli-scaffolding-i18n-and-mail/04-01-SUMMARY.md Co-authored-by: Cursor --- .../04-01-SUMMARY.md | 147 ++++++++++++++++++ 1 file changed, 147 insertions(+) create mode 100644 .planning/phases/04-cli-scaffolding-i18n-and-mail/04-01-SUMMARY.md diff --git a/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-01-SUMMARY.md b/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-01-SUMMARY.md new file mode 100644 index 0000000..0ed9413 --- /dev/null +++ b/.planning/phases/04-cli-scaffolding-i18n-and-mail/04-01-SUMMARY.md @@ -0,0 +1,147 @@ +--- +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//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*