From 5cf5c4f0dc9cfdcdec580ce107db7d241b739ef8 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Tue, 20 Oct 2026 23:58:13 +0200 Subject: [PATCH] docs(roadmap): add phase 32 console commands overhaul --- .planning/ROADMAP.md | 22 +++++++++++++++++++ .../32-console-commands-overhaul/.gitkeep | 1 + 2 files changed, 23 insertions(+) create mode 100644 .planning/phases/32-console-commands-overhaul/.gitkeep diff --git a/.planning/ROADMAP.md b/.planning/ROADMAP.md index fa2261e1..2bc1322c 100644 --- a/.planning/ROADMAP.md +++ b/.planning/ROADMAP.md @@ -1469,6 +1469,27 @@ Plans: Plans: - [ ] TBD (run /msd-plan-phase 31 to break down) +### Phase 32: Console commands overhaul + +**Goal:** Console commands in `summer` and in application binaries reach the bar set by Laravel's Artisan. The command logic stays; what changes is logging, the shared console layer in `bonfire`, and every command's help and output. A user sees what a command did, can ask for more or less of it, and learns from `--help` how to use it without opening the docs. Example of today's gap: `serve` prints raw `slog` lines from plugins and River mixed with styled `ℹ` lines, says nothing about what it booted (plugins, migrations state, mail driver, cache, realtime, scheduler), and has no way to see more or less. Logging today is one hard-coded `slog.NewTextHandler` at INFO in `sunscreen.Install`, with no level, format or destination config. +**Mode:** mvp +**Depends on:** none (framework `diary`, `bonfire` and the commands that modules and plugins register; can run in parallel with the 19.x phases) +**Repos:** `summercms.go`; shared plugin repos only for their commands' help text and logger names, without breaking changes to command names or flags; `sm-summercmsio-app` / `vue-summercmsio-app` for the landing site and roadmap presentation +**Planned shape:** 4 plans: (1) `diary` logging module, (2) `bonfire` global flags, help and `list`, (3) sweep of every command, (4) unit tests. Docs, landing-site and roadmap-presentation updates ride along or go to `/msd-quick` tasks. +**Requirements**: TBD +**Success Criteria** (what must be TRUE): + + 1. A new `diary` module (beach-themed README, root table row) owns the application's logging, modelled on Laravel's `config/logging.php`: `log.level` and `log.channel` config keys, channels for stderr, a `stack` of several channels, a daily file with retention and JSON output, a console handler that renders records in `bonfire`'s style with a component prefix, and named component loggers. `sunscreen` redaction wraps every channel; `sunscreen.Install` keeps working as a compatibility shim. Standard library only, or a decision note for any new dependency. + 2. `bonfire` provides global flags on every command, modelled on Artisan: `-v`/`-vv`/`-vvv`, `-q`/`--quiet`, `--no-ansi`/`--ansi`, `-n`/`--no-interaction` and `--env`. Verbosity sets the `diary` level at runtime, so framework and third-party logs (River, plugins) are hidden or formatted consistently at the default level and shown in full at `-vv`. + 3. Every command has a description, a long help with usage examples, and documented arguments and options with defaults. `list` output is grouped by namespace like `php artisan list`, and `summer help ` and ` help ` work. A test fails when a registered command lacks a description or examples. + 4. A sweep of all existing commands (framework modules and shared plugins) checks them against an Artisan feature checklist and fixes the gaps found, without changing command logic or breaking existing names and flags. The checklist covers confirmation with `--force` on destructive actions, `--pretend`/dry-run where it applies, progress bars and tables for bulk work, and `--json` output for scripting. Long-running commands such as `serve` and `queue:work` print a startup summary of what booted (environment, plugins, database and migrations state, queues, scheduler, mail, cache and realtime drivers, URLs) and report what they did on shutdown. One-shot commands end with a result line and a meaningful exit code. + 5. The `diary` and `bonfire` READMEs, the docs console and logging pages, the summercms.io landing site and its roadmap presentation reflect the new console. The new code has unit tests, delivered in the phase's last plan. + +**Plans:** 0 plans + +Plans: +- [ ] TBD (run /msd-plan-phase 32 to break down) + ## Progress **Execution Order:** @@ -1520,6 +1541,7 @@ Phases execute in numeric order: 1 → 2 → 3 → 4 → 5 → 6 → 7 → 8 → | 20. Demo instance with every shared plugin | 0/TBD | Not started | - | | 30. Płytarium cutover | 0/TBD | Not started | - | | 31. Chat polish against WavePath clients | 0/TBD | Not started | - | +| 32. Console commands overhaul | 0/TBD | Not started | - | ## Backlog diff --git a/.planning/phases/32-console-commands-overhaul/.gitkeep b/.planning/phases/32-console-commands-overhaul/.gitkeep new file mode 100644 index 00000000..8b137891 --- /dev/null +++ b/.planning/phases/32-console-commands-overhaul/.gitkeep @@ -0,0 +1 @@ +