diff --git a/.planning/phases/14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new/14.3-03-SUMMARY.md b/.planning/phases/14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new/14.3-03-SUMMARY.md new file mode 100644 index 0000000..bf1d606 --- /dev/null +++ b/.planning/phases/14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new/14.3-03-SUMMARY.md @@ -0,0 +1,206 @@ +--- +phase: 14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new +plan: 03 +subsystem: docs +tags: [docs, summer-new, bootstrap, landing-page, nuxt, terminal-check, llms] + +requires: + - phase: 14.3-01 + provides: "summer new with --framework, --no-plugin, --no-git; relative go.work paths from plugin:add" + - phase: 14.3-02 + provides: "modules/sunrise new.sh, site GET /new, check-phase14.3.sh --acceptance-production" +provides: + - "docs/setup/installation.md led by curl -fsSL https://summercms.io/new | bash -s -- demo" + - "go-modules-and-workspaces section Applications created by summer new" + - "console scaffolding section Creating an application (flags, files, first commit, naming)" + - "llms_notes entry for the one-command start; llms.txt and llms-full.txt carry it" + - "landing page Get started: one-liner, compose, build, migrate, serve (vue 6140750)" + - "terminal_check_test.go: terminalNewURL, SUMMERCMS_NEW_URL, terminalRunScript, reworked gated TestTerminalCommands (app d073cb9, 9539e90)" +affects: [14.3-04 unit tests, v0.1.13 release, site redeploy] + +actuals: + tokens: 11499 + tasks: 3 + commits: 2 +plan_head_before: 0d117a3e57769f0b5082fb718e3d2fd755a9b406 +plan_head_after: e0640220f26fa1c25d3b1cc33e6c3e4ad5d5815b + +tech-stack: + added: [] + patterns: + - "Gated shell check rewrites a blocking serve line into a background run, a bounded poll of the starter route and a stop of the app binary (pkill -P) before summer itself" + - "Unique COMPOSE_PROJECT_NAME plus t.Cleanup docker compose down -v in the directory the page's cd command names" + +key-files: + created: + - .planning/phases/14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new/14.3-03-SUMMARY.md + modified: + - docs/setup/installation.md + - docs/architecture/go-modules-and-workspaces.md + - docs/console/scaffolding.md + - docs/console/introduction.md + - docs/site.yaml + - README.md + - ../sm-summercmsio-app/vue-summercmsio-app/app/data/terminal.json + - ../sm-summercmsio-app/vue-summercmsio-app/i18n/locales/en.json + - ../sm-summercmsio-app/vue-summercmsio-app/tests/terminal.test.ts + - ../sm-summercmsio-app/terminal_check_test.go + - ../sm-summercmsio-app/README.md + - ../sm-summercmsio-app/CLAUDE.md + - ../sm-summercmsio-app/DEPLOY.md + +key-decisions: + - "The serve block stops the application binary first (pkill -P on the summer pid), because summer serve has no signal handling and killing summer alone would orphan the server on :8080" + - "tests/output.test.ts needed no change: it reads terminal.json and en.json instead of pinning old command literals" + - "The manual path in the installation guide uses go -C summercms install ./cmd/summer; verified on a fresh local clone without GOWORK=off" + +patterns-established: + - "A docs command line with summer new keeps flags after the name (summer new demo --framework ) so the docs command checker sees the command word" + +requirements-completed: [D-01, D-18, D-19, D-20, D-24, D-28] + +coverage: + - id: D1 + description: "Landing page Get started shows and copies the six one-liner commands; every en.json string is rendered and no old terminal key remains" + requirement: D-19 + verification: + - kind: unit + ref: "vue-summercmsio-app: pnpm generate && pnpm test (32 pass, 0 fail)" + status: pass + - kind: integration + ref: "SUMMERCMS_REQUIRE_BUILD=1 go -C plugins/golem15/summercms test -run TestTerminalCommandsInPage (after scripts/build.sh dev)" + status: pass + human_judgment: false + - id: D2 + description: "Site checks pin the commands: TestLoadTerminal, TestTerminalScript (SUMMERCMS_NEW_URL rewrites only the curl command), TestTerminalEnv, TestTerminalRunScript" + requirement: D-19 + verification: + - kind: unit + ref: "sm-summercmsio-app/terminal_check_test.go#TestLoadTerminal,TestTerminalScript,TestTerminalEnv,TestTerminalRunScript" + status: pass + human_judgment: false + - id: D3 + description: "The six page commands run verbatim against the local script and framework HEAD and the backgrounded summer serve answers with \"plugin\":\"golem15.demo\"; the compose project is removed" + requirement: D-20 + verification: + - kind: e2e + ref: "SUMMERCMS_TERMINAL_CHECK=1 SUMMERCMS_NEW_URL=file:///modules/sunrise/new.sh SUMMERCMS_REPO= SUMMERCMS_REF= go test -run TestTerminalCommands" + status: pass + human_judgment: false + - id: D4 + description: "Installation, go modules and console docs plus the root README lead with the one-command start and document summer new as built; llms outputs include it" + requirement: D-18 + verification: + - kind: unit + ref: "go test ./cmd/summer -run TestDocsTree|TestDocsBuildRealTree|TestDocsAIOutputsInSync|TestDocsRequiredPages|TestEveryModuleInSidebar" + status: pass + - kind: other + ref: "summer docs:build --check; docs:build --out then grep llms-full.txt and llms.txt (LLMS-OK)" + status: pass + human_judgment: false + - id: D5 + description: "Docs wording is accurate, readable and neutral (no consuming application named)" + requirement: D-18 + verification: + - kind: other + ref: "grep -Eci 'fonoteka|p[lł]ytarium' on the four pages prints 0; docs:build --check forbidden-name rule" + status: pass + human_judgment: true + rationale: "Prose quality and the correctness of every behavioural sentence need a human read; checks only prove identifiers, links and names" + - id: D6 + description: "Site framework require stays at v0.1.12; nothing pushed, tagged or deployed" + requirement: D-28 + verification: + - kind: other + ref: "grep -c v0.1.12 sm-summercmsio-app/go.mod = 1 before and after" + status: pass + human_judgment: true + rationale: "Release, require bump and redeploy are user actions after the phase" + +duration: 9min +completed: 2026-10-08 +status: complete +--- + +# Phase 14.3 Plan 03: Docs and landing page for the one-command start Summary + +**The installation guide, the console and go-modules docs, the root README and llms outputs now lead with `curl -fsSL https://summercms.io/new | bash -s -- demo` and document `summer new` as built. The summercms.io Get started card shows the six new commands, and a gated site test runs those commands verbatim until the starter route answers.** + +## Performance + +- **Duration:** 9 min +- **Started:** 2026-10-08T10:00:04Z +- **Completed:** 2026-10-08T10:09:15Z +- **Tasks:** 3 +- **Files modified:** 13 (6 in summercms.go, 4 in sm-summercmsio-app, 3 in vue-summercmsio-app) + +## Accomplishments + +- `terminal.json`: groups `terminal.createApp` (the one-liner), `terminal.startDatabase` (`cd sm-demo-app`, `docker compose up -d --wait`) and `terminal.buildAndServe` (`summer build`, `summer migrate`, `summer serve`). The matching en.json strings replace `getFramework`, `installCli` and `buildExample`. +- `terminal_check_test.go`: `terminalNewURL` and the `SUMMERCMS_NEW_URL` override (curl command only), `terminalRunScript` (background serve, 60 s poll, print body, stop), `terminalCdDir`, and `TestTerminalCommands` with a unique compose project, `t.Cleanup` down -v and the `"plugin":"golem15.demo"` assertion. +- Gated run on this machine: the six commands passed in 17.5 s with output `{"message":"Hello from SummerCMS","plugin":"golem15.demo"}`. No `summercms-terminal-*` container or volume was left behind, port 8080 was free afterwards and no orphaned app binary remained. +- Framework docs: the installation guide has the one-command section, what the script does (steps, refusals, three overrides), running the app, `summer new` without the script, and then the examples/hello walkthrough. The obsolete known-issues callout is gone; `summer build` in examples/hello now leaves main.go unchanged. The go-modules page has "Applications created by summer new", and `plugin:add` now adds a relative go.work path. Scaffolding has "Creating an application", introduction and site.yaml carry the llms note, and the root README has a new quick start. + +## Task Commits + +1. **Task 1: one-liner through terminal.json, site checks, installation guide**: vue `6140750` (feat), app `d073cb9` (feat, with the gitlink bump), framework `9058252` (docs) +2. **Task 2: end-to-end run of the page commands and site docs**: app `9539e90` (feat) +3. **Task 3: framework docs for summer new and llms outputs**: framework `e064022` (docs) + +Tracer gate after Task 1 (interactive, end-of-phase, automated-only verify): the verify chain was re-run green, so expansion continued. + +## Files Created/Modified + +- `docs/setup/installation.md`: one-command start first, then the manual path +- `docs/architecture/go-modules-and-workspaces.md`: what summer new writes, the detection order and relative go.work paths +- `docs/console/scaffolding.md`: Creating an application +- `docs/console/introduction.md`: summer row and chapter list +- `docs/site.yaml`: llms note +- `README.md`: Requirements, Quick start, Using SummerCMS in an application +- `sm-summercmsio-app/terminal_check_test.go`, `README.md`, `CLAUDE.md`, `DEPLOY.md`: the new check, its variables, `/new`, and step 4 of the deploy checklist +- `vue-summercmsio-app/app/data/terminal.json`, `i18n/locales/en.json`, `tests/terminal.test.ts`: the landing page commands + +## Decisions Made + +- The serve stop kills summer's child (the app binary) before summer. `summer serve` delegates through `exec.CommandContext` and has no signal handler, so killing summer alone would leave the server running. +- `tests/output.test.ts` was left unchanged because it derives everything from terminal.json and en.json. + +## Deviations from Plan + +### Auto-fixed Issues + +**1. [Rule 1 - Bug] DEPLOY.md step 2 still referred to the page's `git clone` command** +- **Found during:** Task 2 +- **Issue:** The page no longer shows a clone command, so step 2's reason for making the repository public was stale. +- **Fix:** It now says the Source links and the bootstrap script behind the one-liner (which clones the repository) point at it. +- **Files modified:** ../sm-summercmsio-app/DEPLOY.md +- **Committed in:** 9539e90 + +**2. [Rule 3 - Blocking] Frontmatter descriptions over 160 characters** +- **Found during:** Task 3 +- **Issue:** `TestDocsTree` rejected the longer descriptions on three pages. +- **Fix:** Shortened them while keeping the summer new mention. +- **Committed in:** e064022 + +--- + +**Total deviations:** 2 auto-fixed (1 bug, 1 blocking). **Impact:** None on scope. + +## Issues Encountered + +None. + +## User Setup Required + +None in this plan. After the phase the user tags v0.1.13, bumps the site's require, redeploys, runs DEPLOY.md step 4 with no overrides and runs `scripts/check-phase14.3.sh --acceptance-production` (plan 04 lists these). + +## Next Phase Readiness + +- Plan 04 (unit tests) can proceed. Docs and site already describe `summer new` and the one-liner exactly as implemented. +- Nothing was pushed, tagged or deployed. The site go.mod still requires v0.1.12 (D-28). + +--- +*Phase: 14.3-one-command-app-scaffolding-summer-new-and-summercms-io-new* +*Completed: 2026-10-08* + +## Self-Check: PASSED