From 3131d7f3e1bf26765fd71fbbb04201d5d5d6c115 Mon Sep 17 00:00:00 2001 From: Jakub Zych Date: Wed, 30 Sep 2026 22:18:00 +0200 Subject: [PATCH] docs(11.1-03): complete the Setup, Architecture, Plugins and Console docs plan --- .../11.1-03-SUMMARY.md | 246 ++++++++++++++++++ .../bonfire-duplicate-command-names.md | 2 +- 2 files changed, 247 insertions(+), 1 deletion(-) create mode 100644 .planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-03-SUMMARY.md diff --git a/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-03-SUMMARY.md b/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-03-SUMMARY.md new file mode 100644 index 0000000..8948d07 --- /dev/null +++ b/.planning/phases/11.1-summercms-documentation-for-humans-and-ai-agents/11.1-03-SUMMARY.md @@ -0,0 +1,246 @@ +--- +phase: 11.1-summercms-documentation-for-humans-and-ai-agents +plan: 03 +subsystem: docs +tags: [docs, wintercms, concept-map, examples, console, architecture, plugins] + +requires: + - phase: 11.1-02 + provides: "identifier, link, command, forbidden, fence and callout checkers; the theme; docs:serve; scripts/check-phase11.1.sh" + - phase: 11.1-01 + provides: "internal/docsite generator, docs:build, docs:sync, src= snippet extraction and bonfire ExampleCall" +provides: + - "docs/setup: introduction, installation (rewritten), configuration, coming-from-wintercms" + - "docs/architecture: introduction, go-modules-and-workspaces, application-lifecycle, request-lifecycle" + - "docs/plugins: registration, scheduling, extending, testing" + - "docs/console: introduction, setup-and-maintenance, scaffolding, writing-commands, utilities" + - "site.yaml sections setup, architecture, plugins, console, api" + - "Examples: party ExamplePlugin (with BlogPlugin in example_plugin_test.go), backpack ExampleApp_Publish, pact ExampleHasSchedule, festival ExampleBus_Fire, towel ExampleWithLocale, bonfire ExampleCatalog" + - "cmd/summer TestDocsRequiredPages with 18 required page URLs" +affects: [11.1-04, 11.1-05, 11.1-06] + +estimate_ref: "tokens 100000, tasks 3, confidence low" +actuals: + tokens: 23900 + tasks: 3 + commits: 4 +plan_head_before: f77b1d868890ed8e2762d71e6a64c94274615edf +plan_head_after: 8254fb91a92ae4a297ed536f8dac6145caa55372 + +tech-stack: + added: [] + patterns: + - "A plugin type that a page shows in full lives in its own example_plugin_test.go and is referenced as a whole-file src= fence; the Example that exercises it is a separate #Example fence" + - "Descriptions containing ': ' are double-quoted in frontmatter (goccy/go-yaml rejects them unquoted)" + - "Commands in docs are written as summer or ./bin/acme so the command checker verifies them; ./bin/ placeholders are never used because the checker cannot see them" + +key-files: + created: + - docs/setup/introduction.md + - docs/setup/configuration.md + - docs/setup/coming-from-wintercms.md + - docs/architecture/introduction.md + - docs/architecture/go-modules-and-workspaces.md + - docs/architecture/application-lifecycle.md + - docs/architecture/request-lifecycle.md + - docs/plugins/registration.md + - docs/plugins/scheduling.md + - docs/plugins/extending.md + - docs/plugins/testing.md + - docs/console/introduction.md + - docs/console/setup-and-maintenance.md + - docs/console/scaffolding.md + - docs/console/writing-commands.md + - docs/console/utilities.md + - modules/party/example_test.go + - modules/party/example_plugin_test.go + - modules/backpack/example_test.go + - modules/pact/example_test.go + - modules/festival/example_test.go + - modules/towel/example_test.go + - .planning/todos/pending/bonfire-duplicate-command-names.md + modified: + - docs/site.yaml + - docs/index.md + - docs/setup/installation.md + - modules/bonfire/example_test.go + - cmd/summer/docs_test.go + +key-decisions: + - "The Plugin.php-in-Go section shows the whole modules/party/example_plugin_test.go file, because a Go Example body cannot declare the four party.Plugin methods; ExamplePlugin is shown separately as the plan requires" + - "Hand-written Go fences are never used: a GORM-callback sketch and a Commands() sketch were replaced by prose rather than shipping unverified Go" + - "Pages describe bonfire as it is: command names are not checked for duplicates. The gap is logged as a todo; bonfire is not changed in this plan" + - "serve's default --addr (:8080) is documented as listening on every interface, with loopback shown in every example" + +patterns-established: + - "requiredPages in cmd/summer/docs_test.go is the list each content plan appends to" + - "Example files use package _test and the neutral acme.* plugin IDs" + +requirements-completed: [DOCS-01, DOCS-04, DOCS-06] + +coverage: + - id: D1 + description: "Coming from WinterCMS maps WinterCMS concepts to 50 distinct checked pkg.Ident spans, lists what is not provided and shows Plugin.php next to a verified Go plugin" + requirement: DOCS-06 + verification: + - kind: unit + ref: "cmd/summer/docs_test.go#TestDocsTree" + status: pass + - kind: unit + ref: "modules/party/example_test.go#ExamplePlugin" + status: pass + human_judgment: false + - id: D2 + description: "Setup, Architecture, Plugins and Console sections are in the sidebar in that order before API reference, and every page of this plan builds as .html and .md" + requirement: DOCS-01 + verification: + - kind: unit + ref: "cmd/summer/docs_test.go#TestDocsRequiredPages" + status: pass + - kind: unit + ref: "cmd/summer/docs_test.go#TestDocsAIOutputsInSync" + status: pass + - kind: unit + ref: "cmd/summer/docs_test.go#TestDocsBuildRealTree" + status: pass + human_judgment: false + - id: D3 + description: "Every Go fence in the new pages is a src= copy of an Example or test declaration that go test runs" + requirement: DOCS-04 + verification: + - kind: unit + ref: "modules/backpack/example_test.go#ExampleApp_Publish" + status: pass + - kind: unit + ref: "modules/pact/example_test.go#ExampleHasSchedule" + status: pass + - kind: unit + ref: "modules/festival/example_test.go#ExampleBus_Fire" + status: pass + - kind: unit + ref: "modules/towel/example_test.go#ExampleWithLocale" + status: pass + - kind: unit + ref: "modules/bonfire/example_test.go#ExampleCatalog" + status: pass + - kind: other + ref: "go run ./cmd/summer docs:build --check" + status: pass + human_judgment: false + - id: D4 + description: "Console pages name only commands that exist; no page names a consuming application; examples bind loopback" + requirement: DOCS-01 + verification: + - kind: other + ref: "scripts/check-phase11.1.sh --docs and --forbidden" + status: pass + - kind: other + ref: "! grep -rn '0\\.0\\.0\\.0' docs/setup docs/console" + status: pass + human_judgment: false + - id: D5 + description: "Pages read in WinterCMS docs tone and are useful to a WinterCMS developer" + verification: [] + human_judgment: true + rationale: "Backstop truth in the plan: tone and usefulness are a reader's judgment" + +duration: 15min +completed: 2026-09-30 +status: complete +--- + +# Phase 11.1 Plan 03: Framework content A (Setup, Architecture, Plugins, Console) Summary + +**Sixteen new or rewritten guide pages cover installation to serve, a WinterCMS concept map with 50 checked identifiers, the binary and request lifecycles, plugin registration, scheduling, extending and testing, and every `summer` and application command. Each Go block on them is a copy of an Example that `go test` runs.** + +## Performance + +- **Duration:** about 15 min +- **Started:** 2026-09-30T20:03:31Z +- **Completed:** 2026-09-30T20:18Z +- **Tasks:** 3 +- **Files modified:** 28 + +## Accomplishments + +- `docs/setup/coming-from-wintercms.md` has a 21-row concept table (WinterCMS, SummerCMS identifiers, module link), a "What is not provided" table (CMS pages, themes, components, AJAX and Snowboard, media manager, import/export, sorting, collections, behaviours, cache, session), and a "Plugin.php in Go" section with a PHP fence next to the verified Go plugin. +- Architecture explains the single binary and headless model, the module map by concern, `summer` versus the application binary, go.mod `replace` and `go.work` workflows with `summer plugin:add`, the generated start-up sequence, Register-then-Boot, the typed container, `lagoon.OnDatabase`, and surf's wrapping order (read from `surf.Router.wrap`: CORS, recovery, locale, body limit, route middleware, constraints). +- Plugins covers ID rules (from `pluginIDRe`), the capability interfaces, embedded config, lang and mail files, the scaffolded layout, schedule semantics and validation, leader election, `schedule:run --once` for cron, events with the three dispatch modes, services, optional dependencies, GORM callbacks and forking, and the test workflow including the ICU database requirement. +- Console lists every runtime command with flags (migrations, key, serve, route:list, admin, queue, schedule, websockets), the seven commands `summer` delegates, what each `make:` command writes (from internal/build/artifact.go), the bonfire API for writing commands, and the parity and docs utilities with their flags and defaults. +- Installation now walks from `go install` through `summer build`, the ICU database, `config/http.yaml`, `SUMMER_` variables with `` markers, `migrate`, `route:list` and `serve --addr 127.0.0.1:8080`, with the known issues as a `[!WARNING]` callout. Its ExampleCall section is kept. +- `TestDocsRequiredPages` asserts all 18 required URLs load and build as `.html` and `.md`. + +## Task Commits + +1. **Task 1: Tracer, the concept map with a verified plugin example:** `d6003cd` (feat) +2. **Task 2: Architecture and Plugins sections:** `1f8f5e1` (feat) +3. **Task 3: Setup and Console sections:** `a896f3f` (feat) +4. **Todo for the bonfire duplicate command name gap:** `8254fb9` (docs) + +**Plan metadata:** the docs(11.1-03) commit that adds this file + +## Files Created/Modified + +See `key-files` in the frontmatter. + +## Decisions Made + +See `key-decisions` in the frontmatter. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 3 - Blocking] The plugin type could not live in the Example body** +- **Found during:** Task 1 +- **Issue:** The plan's `#ExamplePlugin` fence shows only the Example body, and Go methods cannot be declared inside a function. The "Plugin.php in Go" section needs the four `party.Plugin` methods to be visible. +- **Fix:** `BlogPlugin` and its methods are in `modules/party/example_plugin_test.go`, shown as a whole-file `src=` fence. `ExamplePlugin` in `example_test.go` uses it and is shown as the planned `#ExamplePlugin` fence. +- **Files modified:** modules/party/example_plugin_test.go (one file beyond the plan's list) +- **Commit:** d6003cd + +**2. [Rule 1 - Bug] Frontmatter descriptions with a colon failed to parse** +- **Found during:** Task 2 +- **Issue:** Four descriptions contained `: ` and goccy/go-yaml rejected them (`mapping value is not allowed in this context`). +- **Fix:** Those description values are double-quoted. +- **Commit:** 1f8f5e1 + +**3. [Rule 1 - Accuracy] Claims corrected against the code before commit** +- A statement that duplicate command names fail at start-up was false (bonfire has no duplicate check). The page now describes the real behaviour, and the gap is logged in `.planning/todos/pending/bonfire-duplicate-command-names.md`. +- Two hand-written Go fences (a GORM callback in Boot and a `Commands()` method) were replaced by prose, because Go fences in docs pages must be `src=` copies. +- The `wire` description was rewritten from its README (HTML characters unescaped, no trailing newline, `[]` for nil lists, Carbon timestamps). + +### Notes + +- `registration.md` does not link the Console scaffolding page, because that page did not exist when Task 2 committed. It points at the `make:` commands in prose instead. +- `gofmt -l modules/party` lists `registry_test.go`, which this plan did not touch. + +**Total deviations:** 2 auto-fixed (1 blocking, 1 bug) and 1 set of accuracy corrections. **Impact:** none on scope. + +## Issues Encountered + +None. The in-flight Phase 11 review edits (`modules/lagoon/transaction*.go`, the check-phase10/11 scripts and the Phase 11 review files) were never staged or touched. `go test -short ./...` was green at every commit with them in the tree. + +## Verification + +- `go vet ./...` and `go test -short ./...` are green. +- All six new Examples and `ExampleCall` report `--- PASS`. +- `TestDocsTree`, `TestDocsRequiredPages`, `TestDocsAIOutputsInSync` and `TestDocsBuildRealTree` pass. `docs:build` writes 40 pages. +- `go run ./cmd/summer docs:build --check` reports no problems. `docs:sync` reports every snippet up to date. +- `scripts/check-phase11.1.sh --docs` and `--forbidden` pass. +- Every acceptance grep in the plan matches: 50 distinct identifiers on the concept map, 8 Architecture and Plugins pages, 4 Setup and 5 Console pages, `ICU_LOCALE` and the ExampleCall fence in installation.md, and no `0.0.0.0` in setup or console. + +## Known Stubs + +None. + +## User Setup Required + +None. + +## Next Phase Readiness + +Plan 11.1-04 can add the Backend, Database and Services sections between Plugins and Console in site.yaml, link the concept map rows to its new guide pages, and append its pages to `requiredPages`. + +## Self-Check: PASSED + +All created files exist. Commits d6003cd, 1f8f5e1, a896f3f and 8254fb9 are in the log. diff --git a/.planning/todos/pending/bonfire-duplicate-command-names.md b/.planning/todos/pending/bonfire-duplicate-command-names.md index b1ee784..3a23ab4 100644 --- a/.planning/todos/pending/bonfire-duplicate-command-names.md +++ b/.planning/todos/pending/bonfire-duplicate-command-names.md @@ -9,4 +9,4 @@ area: summercms.go bonfire Found while writing `docs/console/writing-commands.md` (Phase 11.1 plan 03). The page describes the current behaviour: names are not checked for duplicates, so keep commands in the plugin's own namespace. -Suggested fix: make `bonfire.NewRoot` fail with an error naming the duplicated command when two commands share a name. `bonfire.NewCatalog`, which the scheduler calls through, has no error return, so the generated `main` should build the root first (as it does today) and rely on that check. Update the bonfire README and the docs page in the same change (the D-13 docs rule). The API change is outside the docs phase boundary, so it is not made in Phase 11.1. +Suggested fix: make `bonfire.NewRoot` fail with an error naming the duplicated command when two commands share a name. `bonfire.NewCatalog`, which the scheduler calls through, has no error return, but the generated `main` calls `bonfire.NewRoot` before it runs any command, so that check stops the binary before a duplicate can run. Update the bonfire README and the docs page in the same change (the D-13 docs rule). The API change is outside the docs phase boundary, so it is not made in Phase 11.1.