diff --git a/.planning/phases/05-cli-scaffolding/05-CONTEXT.md b/.planning/phases/05-cli-scaffolding/05-CONTEXT.md new file mode 100644 index 0000000..98ead3e --- /dev/null +++ b/.planning/phases/05-cli-scaffolding/05-CONTEXT.md @@ -0,0 +1,81 @@ +# Phase 5: CLI Scaffolding - Context + +**Gathered:** 2026-02-04 +**Status:** Ready for planning + + +## Phase Boundary + +Provide developer tools for rapid project setup: commands to scaffold plugins, themes, components, controllers, models, and migrations. Generated scaffolds follow project conventions and are immediately usable. + + + + +## Implementation Decisions + +### Command Design +- **Structure:** Noun-verb pattern: `summer plugin create`, `summer theme create`, etc. +- **Executable name:** `summer` +- **Naming format:** Author.Name dot notation for plugins, themes, components + - `summer plugin create Acme.Blog` + - `summer theme create Acme.Corporate` + - `summer component create Acme.Blog MyComponent` (explicit plugin required) +- **No shorthand aliases** — keep commands explicit +- **--dry-run option** — show what would be created without creating +- **No --force option** — error if target exists, user deletes manually +- **Version output:** Include Scala/JVM info: `SummerCMS 1.0.0 (Scala 3.x, JVM 21)` +- **Color output:** Colors by default, `--no-color` to disable + +### Output & Feedback +- **During scaffolding:** Progress bar for larger scaffolds +- **After completion:** Actionable next steps (what to edit, what to run) +- **Error style:** Concise with suggestion (error message + tip to fix) +- **Verbosity:** `-v` for verbose, `-q` for quiet + +### Generated Structure +- **Plugin scaffold:** Standard structure — Plugin.scala, manifest, empty directories for models/, controllers/, components/ +- **Theme scaffold:** Choice via `--template` flag (`--template=blank` or `--template=starter`) +- **Component scaffold:** Component class + default partial + component.yaml +- **Controller scaffold:** Full backend resource like WinterCMS — controller class, fields.yaml, columns.yaml, view partials +- **Model scaffold:** Model class + migration together (like WinterCMS) +- **Migration scaffold:** Standalone `summer migration create` command available +- **Migration naming:** Timestamp prefix: `20260204_120000_create_posts_table.scala` +- **File naming:** PascalCase for Scala classes +- **Directory structure:** + - Plugins: `plugins/author/pluginname/` (lowercase) + - Themes: `themes/author/themename/` (lowercase) +- **Inline guidance:** TODO comments showing where to add code + +### Interactive Mode +- **Missing args:** Prompt interactively when required arguments missing +- **Wizard mode:** `--wizard` flag for guided scaffold creation +- **No confirmation:** Create immediately (use `--dry-run` for preview) +- **CI environments:** `--no-interaction` flag to disable prompts (error on missing args) + +### Claude's Discretion +- Config file detection approach (follow WinterCMS patterns) +- Help output format and level of detail +- Input validation behavior during prompts +- Exact progress bar implementation + + + + +## Specific Ideas + +- "Full backend resource just like WinterCMS" — controller scaffold includes everything needed for admin CRUD +- "Model + migration just like WinterCMS" — model scaffolding creates both together + + + + +## Deferred Ideas + +None — discussion stayed within phase scope + + + +--- + +*Phase: 05-cli-scaffolding* +*Context gathered: 2026-02-04*