docs(33): create phase plan
Fourteen plans in nine waves for SEO output, audit and content, with the pattern map and the IndexNow coverage matrix. Claude-Session: https://claude.ai/code/session_013jPFwWHBUFJPX91w5Qa4Vs
This commit is contained in:
@@ -1640,10 +1640,40 @@ Plans:
|
||||
3. The crawler reports SEO issues per URL, and each issue can be fixed through MCP.
|
||||
4. The new code has unit tests, delivered in the phase's last plan.
|
||||
|
||||
**Plans:** 0 plans
|
||||
**Plans:** 14 plans
|
||||
|
||||
Plans:
|
||||
- [ ] TBD (run /msd-plan-phase 33 to break down)
|
||||
**Wave 1**
|
||||
- [ ] 33-01-PLAN.md — framework: additive content descriptor fields and per-request field options, check-phase33.sh, v0.5.2 release log (no tag)
|
||||
- [ ] 33-07-PLAN.md — vue-seo-layer (new repository): CMS head and one JSON-LD graph, redirect/410 enforcement, root files, 404 report, shared purge route
|
||||
|
||||
**Wave 2** *(blocked on Wave 1 completion)*
|
||||
- [ ] 33-02-PLAN.md — sm-journal-plugin: per-site H1 setting on every write path, editor J1–J4, descriptor facts, journal-author type, MCP tools
|
||||
- [ ] 33-03-PLAN.md — sm-sitemap-plugin: sitemap index with per-type files, slot table, real lastmod, hreflang, filter contract (breaking, D-32)
|
||||
- [ ] 33-08-PLAN.md — vue-seo-layer: SSR build guard, noindex routes, route report, drift check, breadcrumbs, pagination, HTML sitemap
|
||||
|
||||
**Wave 3** *(blocked on Wave 2 completion)*
|
||||
- [ ] 33-04-PLAN.md — sm-sitemap-plugin: image and News sitemaps, IndexNow, HTML-sitemap API, MCP tools
|
||||
- [ ] 33-09-PLAN.md — journal, menu and FAQ layers on the SEO layer: headings in both H1 modes, one link per card, body links, breadcrumbs, pagination
|
||||
|
||||
**Wave 4** *(blocked on Wave 3 completion)*
|
||||
- [ ] 33-05-PLAN.md — sm-seo-plugin I: sitemap filter, page registry with route report, site endpoint, llms.txt, Links settings, purge after writes
|
||||
|
||||
**Wave 5** *(blocked on Wave 4 completion)*
|
||||
- [ ] 33-06-PLAN.md — sm-seo-plugin II: JSON-LD @graph, publisher, schema fields (E8/E9), breadcrumbs, hreflang, pagination
|
||||
|
||||
**Wave 6** *(blocked on Wave 5 completion)*
|
||||
- [ ] 33-10-PLAN.md — sm-seo-plugin: crawler, issue report with fix routes, Site audit and Crawls, MCP tools
|
||||
|
||||
**Wave 7** *(blocked on Wave 6 completion)*
|
||||
- [ ] 33-11-PLAN.md — internal linking and media: auto-links, link suggestions (E10), related posts, WebP variants with srcset
|
||||
|
||||
**Wave 8** *(blocked on Wave 7 completion)*
|
||||
- [ ] 33-12-PLAN.md — apps I: demo end to end on local links, summercms.io patches, sm-bm-app noindex (D-72)
|
||||
- [ ] 33-13-PLAN.md — grzybyfunkcjonalne.pl on the new sitemap format and the SEO layer; uat deploy by decision
|
||||
|
||||
**Wave 9** *(blocked on Wave 8 completion)*
|
||||
- [ ] 33-14-PLAN.md — unit tests, check-phase33.sh --all, release tags in order, app re-pins, changelog post
|
||||
|
||||
## Progress
|
||||
|
||||
|
||||
334
.planning/phases/33-seo-output-audit-and-content/33-01-PLAN.md
Normal file
334
.planning/phases/33-seo-output-audit-and-content/33-01-PLAN.md
Normal file
@@ -0,0 +1,334 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 01
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- modules/pact/content.go
|
||||
- modules/pact/capabilities.go
|
||||
- modules/pact/README.md
|
||||
- modules/signpost/README.md
|
||||
- modules/signpost/example_content_test.go
|
||||
- modules/signpost/content_fields_smoke_test.go
|
||||
- modules/cabana/field_type.go
|
||||
- modules/cabana/http.go
|
||||
- modules/cabana/admin_openapi.go
|
||||
- modules/cabana/README.md
|
||||
- modules/cabana/field_request_options_smoke_test.go
|
||||
- admin/openapi/admin.json
|
||||
- admin/src/api/schema.d.ts
|
||||
- docs/plugins/menu-item-types.md
|
||||
- docs/backend/field-types.md
|
||||
- scripts/check-phase33.sh
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-release-log.md
|
||||
autonomous: false
|
||||
requirements: [SC-2, SC-3, D-93, D-90, D-106, D-43, D-86, D-31, D-85, D-50, D-51, D-96, D-10]
|
||||
|
||||
estimate:
|
||||
tokens: 90000
|
||||
raw_tokens: 90000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "pact.ContentDescriptor gains Kind and Tools, pact.ContentRecord gains PublishedAt, Parents, Authors and TopHeading, and pact.ContentLocale gains Images, Videos and Headings, with the value types ContentRef, ContentPerson, ContentImage, ContentVideo and ContentHeading; every field is optional and names nothing SEO-specific (D-93, D-90)"
|
||||
- "A content type that sets none of the new fields describes, lists and matches exactly as in v0.5.1; signpost.Describe and signpost.Records hand the new fields through unchanged, proven by TestContentDescriptorFields and the runnable signpost example (D-93: sitemaps and the page registry consume Records)"
|
||||
- "The descriptor fields carry what JSON-LD, breadcrumbs, the image and News sitemaps, the missing-alt report and the heading checks need: first publication date, ordered candidate parents (first is the default primary), authors with an optional reference to their own page, body images with alt and a decorative flag, videos, the body's heading outline and the top heading level the body may use (D-43, D-86, D-31, D-85, D-50, D-51)"
|
||||
- "ContentDescriptor.Tools names the MCP tools that change a type's records by operation (edit, headings, image_alt), so an audit tool can point every content issue at a fixing tool without importing the content plugin (SC-3, D-10, D-96)"
|
||||
- "A plugin field type can supply per-request options through pact.FormFieldType.RequestOptions; cabana merges them into the field's typeOptions in the served form schema on create, update and preview, an option set in fields.yaml wins over a request option of the same key, and an element therefore reads a site setting without a token, cookie or admin route (UI-SPEC Q-2, 2026-10-28 Journal H1 setting)"
|
||||
- "A RequestOptions error never fails the form: the schema is served with the fields.yaml options only and the error is logged once per request"
|
||||
- "The exported API surface of the framework after this plan is strictly additive against v0.5.1: no element removed or changed and no method added to an existing interface (D-106), checked by scripts/check-phase33.sh --additive"
|
||||
- "scripts/check-phase33.sh exists with the stages self-test, go, plugins, layers, consumers, docker, admin, docs, marker, additive and compat; --self-test passes and a stage whose repository is missing fails with the repository named (Wave 0)"
|
||||
- "33-release-log.md lists what v0.5.2 will carry (the six Phase 32 fix commits CR-01, CR-02, CR-04, WR-01, WR-02, WR-07 plus this plan's seams) and the unreleased commits of sm-seo-plugin and sm-journal-plugin; nothing is pushed or tagged in this plan (2026-10-28 release cadence: all tags in 33-14)"
|
||||
- "Jakub's answer on the meaning of pact.RecordSaved.Locale (32-UAT test 4, WR-02) is recorded before v0.5.2 freezes it"
|
||||
- "The plan list of Phase 33 is 14 plans, as Jakub confirmed on 2026-10-28; this plan is the first of them and the framework part of v0.5.2 (2026-10-28 plan list)"
|
||||
- {statement: "A descriptor that leaves the new slices nil and one that sets them to empty slices are treated alike by signpost and by the docs examples (no nil-versus-empty drift for consumers)", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-90"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "No framework file added or changed by this plan names SEO, a sitemap, JSON-LD or a consuming application; the marker stage of check-phase33.sh proves it"
|
||||
- requirement_id: "D-106"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "No existing exported element of pact, signpost or cabana changes its signature or meaning, and no interface gains a method; v0.5.1 consumers build and test unchanged"
|
||||
artifacts:
|
||||
- path: "modules/pact/content.go"
|
||||
provides: "additive descriptor fields and value types"
|
||||
contains: "PublishedAt *time.Time"
|
||||
- path: "modules/pact/capabilities.go"
|
||||
provides: "FormFieldType.RequestOptions"
|
||||
contains: "RequestOptions"
|
||||
- path: "modules/signpost/content_fields_smoke_test.go"
|
||||
provides: "TestContentDescriptorFields (tracer)"
|
||||
contains: "func TestContentDescriptorFields("
|
||||
- path: "modules/cabana/field_request_options_smoke_test.go"
|
||||
provides: "TestFieldTypeRequestOptions"
|
||||
contains: "func TestFieldTypeRequestOptions("
|
||||
- path: "scripts/check-phase33.sh"
|
||||
provides: "phase gate engine (Wave 0)"
|
||||
contains: "--additive"
|
||||
- path: ".planning/phases/33-seo-output-audit-and-content/33-release-log.md"
|
||||
provides: "v0.5.2 contents and the release order 33-14 follows"
|
||||
contains: "v0.5.2"
|
||||
key_links:
|
||||
- from: "modules/pact/content.go"
|
||||
to: "modules/signpost/content.go"
|
||||
via: "Registry.Describe and Registry.Records return the type's *pact.ContentRecord values as they come, new fields included"
|
||||
pattern: "func \\(r \\*Registry\\) (Describe|Records)\\("
|
||||
- from: "modules/pact/capabilities.go"
|
||||
to: "modules/cabana/http.go"
|
||||
via: "the form schema handler calls each plugin field type's RequestOptions once per request and merges the map into TypeOptions"
|
||||
pattern: "RequestOptions"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan gives every later plan what it needs from the framework: the content facts that JSON-LD, breadcrumbs, image and News sitemaps and the audit read from a content type (one generic, additive seam), a way for a plugin field type to receive per-request options (the Blog Editor's heading levels follow the Journal H1 setting), the phase gate script, and the release log that 33-14 follows.
|
||||
|
||||
<objective>
|
||||
Extend the framework additively (D-90, D-106) and prepare v0.5.2 without tagging it:
|
||||
- `pact.ContentDescriptor`, `pact.ContentRecord`, `pact.ContentLocale` gain optional fields (Pattern 1 of 33-RESEARCH.md, names confirmed at the Task 1 checkpoint);
|
||||
- `pact.FormFieldType.RequestOptions` lets a plugin field type add per-request options to its schema entry (UI-SPEC Q-2, planner decision: a generic seam rather than an element-side fetch);
|
||||
- `scripts/check-phase33.sh` with every stage the phase gate needs (Wave 0 of 33-VALIDATION.md);
|
||||
- `33-release-log.md`: v0.5.2 = the unreleased Phase 32 fixes plus these seams; plugin versions are read from `git tag` in 33-14.
|
||||
|
||||
Purpose: Phase 33 builds on tagged versions (Q-01); every plugin in this phase develops against `../summercms.go` through `replace`, and 33-14 tags v0.5.2 with everything this plan adds.
|
||||
|
||||
Output: commits in this repository (code and docs separately from the planning-docs commit of the release log). Nothing is pushed or tagged.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-01 (descriptor shape, `[ASSUMED]` until Task 1):** `ContentDescriptor.Kind string` with constants `ContentKindArticle = "article"`, `ContentKindCollection = "collection"`, `ContentKindProfile = "profile"`, `ContentKindPage = "page"`; `ContentDescriptor.Tools map[string]string` with constants `ContentToolEdit = "edit"`, `ContentToolHeadings = "headings"`, `ContentToolImageAlt = "image_alt"` (the value is a full MCP tool name such as `journal_update_post`); `ContentRecord.PublishedAt *time.Time`, `ContentRecord.Parents []ContentRef` (ordered candidates, first is the default primary), `ContentRecord.Authors []ContentPerson`, `ContentRecord.TopHeading int` (the highest heading level the body should contain: 2 when the page renders the title as the only H1, 0 when the type sets no rule); `ContentLocale.Images []ContentImage`, `ContentLocale.Videos []ContentVideo`, `ContentLocale.Headings []ContentHeading`; `ContentRef{Type, ID string}` (Type is a menu item type key), `ContentPerson{Name string; Ref ContentRef}` (Ref.Type "" when the person has no page), `ContentImage{URL, Alt string; Decorative bool; Width, Height int}`, `ContentVideo{Provider, ID string}`, `ContentHeading{Level int; Text string}`. Each field gets a one-sentence doc comment in the existing style.
|
||||
- **P33-02 (per-request field options):** `FormFieldType.RequestOptions func(ctx context.Context, db *gorm.DB) (map[string]any, error)` with `json:"-"`. cabana calls it at most once per field type per schema request, merges the map under the field's `typeOptions` (keys present in fields.yaml win), and logs and ignores an error. The Blog Editor (33-02) uses it for `headingLevels` and `genericAnchors`.
|
||||
- **P33-03 (release log):** `.planning/phases/33-seo-output-audit-and-content/33-release-log.md` is the phase's release ledger, written like `32-06-release-log.md`: planned contents per repository now, and each executed release step appended in 33-14 so a resumed run never re-tags.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/32-seo-foundation/32-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
|
||||
@.planning/phases/32-seo-foundation/32-02-SUMMARY.md
|
||||
@.planning/phases/32-seo-foundation/32-06-SUMMARY.md
|
||||
@.planning/phases/32-seo-foundation/32-UAT.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
modules/pact/content.go today (v0.5.1): ContentDescriptor{Controller, Model string; Records, Describe, Match funcs}; ContentList{Pattern, After, Limit, UnprefixedLocale}; ContentPage{Records []ContentRecord; Next}; ContentDescribe{ID, Pattern, UnprefixedLocale}; ContentRecord{ID string; Published bool; LastMod *time.Time; Locales []ContentLocale}; ContentLocale{Locale, URL, Title, Description, Image string; Words *int}; ContentMatch / ContentMatchResult{ID, Locale string; Exact bool}.
|
||||
modules/pact/capabilities.go FormFieldType{Name, Element string; Translatable bool; Scripts, Styles, Options []string; CheckOptions, Decode, Load, ListValue, Upload funcs}; FormFieldValue{DB, Record, Field, Options, Locale, Default, Value, Translated}.
|
||||
modules/cabana/schema_types.go: the served field carries TypeOptions map[string]any `json:"typeOptions,omitempty"`; modules/cabana/field_type.go:263 sets it at compile time.
|
||||
admin/src/components/form/fields/PluginField.vue:44 serializes props.field.typeOptions into the element's options attribute (no SPA change needed).
|
||||
scripts/check-phase32.sh: stage engine (detect_go, go_named, run_* stages, additive via scripts/apisurface against the newest tag not containing HEAD, compat via snapshots/worktrees in a scratch sibling farm, --self-test planting each case).
|
||||
Framework commits after v0.5.1 that v0.5.2 carries: 676ca53 (CR-01), 5471b66 (CR-02), d660cd0 (CR-04), 468af06 (WR-01), 1583651 (WR-02), 0e187cf (WR-07).
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Each task ends with the commit groups below, staged by explicit path (never `-A` or `.`); another session may have uncommitted `.planning/STATE.md`, `.planning/state.json`, `.planning/ROADMAP.md` or `.planning/G15OFFICE.md` changes, which stay untouched. Code and docs commits are separate from planning-docs commits.
|
||||
- Resume check: `git log --format=%s | grep -Fx '<subject>'` for each subject. All present: re-run the task's `<verify>` and continue; some present: continue at the first missing group.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | none (checkpoint answer recorded in the SUMMARY) | answer recorded |
|
||||
| 2 | `feat(signpost): content descriptor fields for dates, parents, authors, media and outline` | TestContentDescriptorFields passes |
|
||||
| 3 | `feat(cabana): per-request options for plugin field types` | TestFieldTypeRequestOptions passes |
|
||||
| 4 | A `test: phase 33 gate script`; B `docs(33-01): release log for v0.5.2` | gate self-test and stages pass |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 1: Confirm the Go shape of the descriptor fields and RequestOptions, and the meaning of RecordSaved.Locale</name>
|
||||
<reversibility rating="one-way">The fields become published framework API in v0.5.2; every content plugin fills them and sm-seo-plugin, sm-sitemap-plugin and the layers read them, so renaming later breaks consumers.</reversibility>
|
||||
<decision>Adopt P33-01 and P33-02 as written, adjust names, or drop RequestOptions; and confirm WR-02 (32-UAT test 4) before v0.5.2 freezes it.</decision>
|
||||
<context>
|
||||
P33-01 lists the proposed fields (Pattern 1 of 33-RESEARCH.md, plus Tools for SC-3 and TopHeading/Headings for the Journal H1 setting's CMS-side check). They name no SEO concept: feeds, search indexers and audit tools use the same facts. P33-02 is the planner's resolution of UI-SPEC Q-2: the Blog Editor needs the per-site heading levels and generic-anchor list on every request, and field options are compiled at boot today. The alternative is that the editor fetches a public Journal endpoint, which breaks the element rule "no direct route" (UI-SPEC Shared rules) less cleanly. WR-02 (commit 1583651) set RecordSaved.Locale to the primary tag of the request locale; 32-UAT test 4 asks Jakub to accept that or ask for the content-locale meaning.
|
||||
</context>
|
||||
<options>
|
||||
<option id="as-planned">
|
||||
<name>Adopt P33-01 and P33-02 as written; accept WR-02's request-locale meaning</name>
|
||||
<pros>Unblocks 33-02 and 33-03 with the shape research and UI-SPEC assume; one framework release carries every Phase 33 seam</pros>
|
||||
<cons>Two seams freeze at once in v0.5.2</cons>
|
||||
</option>
|
||||
<option id="adjust">
|
||||
<name>Adopt with the names or fields Jakub changes (stated in the answer)</name>
|
||||
<pros>Names fixed before they become API</pros>
|
||||
<cons>Later plans use the adjusted names; the executor records them in the SUMMARY for every downstream plan</cons>
|
||||
</option>
|
||||
<option id="no-request-options">
|
||||
<name>Adopt P33-01 only; the editor reads its options from a public Journal endpoint</name>
|
||||
<pros>One framework seam fewer</pros>
|
||||
<cons>The Blog Editor element makes its own request, against the UI-SPEC element rule; 33-02 Task 4 changes accordingly</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "as-planned", "adjust: <changes>" or "no-request-options", plus "WR-02: accept" or "WR-02: content locale"</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 2: End-to-end "a content type describes a record with dates, parents, authors, images, videos and its outline, and signpost hands them through" — one path only</name>
|
||||
<files>modules/pact/content.go, modules/signpost/content_fields_smoke_test.go, modules/signpost/example_content_test.go, modules/pact/README.md, modules/signpost/README.md, docs/plugins/menu-item-types.md</files>
|
||||
<read_first>
|
||||
- modules/pact/content.go (whole file; the doc-comment style to copy)
|
||||
- modules/signpost/content.go (Describe, Records, ContentTypes, ContentTypeForModel)
|
||||
- modules/signpost/content_test.go and modules/signpost/example_content_test.go (the fake content type the tests use)
|
||||
- docs/plugins/menu-item-types.md (the content descriptor section)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pattern 1)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-93 and P33-01 (as answered in Task 1): add the fields and the five value types to `modules/pact/content.go`, each with a one-sentence comment in the file's style and no SEO wording (D-90): Kind and Tools on ContentDescriptor with the Kind and Tool constants; PublishedAt, Parents, Authors, TopHeading on ContentRecord; Images, Videos, Headings on ContentLocale. Tools values are full MCP tool names. No existing field, signature or comment meaning changes (D-106). signpost needs no logic change if Describe and Records already return the type's records as given; read `modules/signpost/content.go` and change it only if it copies records field by field. Add `modules/signpost/content_fields_smoke_test.go` with `TestContentDescriptorFields`: register a fake type with Kind article and Tools {edit: acme_update_page}, whose Describe answers PublishedAt, two Parents, one Author with a Ref, two Images (one decorative with empty alt), one Video and three Headings with TopHeading 2; assert signpost.Describe and signpost.Records return every value unchanged and that `ContentType(key)` exposes Kind and Tools; a second fake type that sets none of them describes exactly as before. Extend the runnable example in `example_content_test.go` with the new fields (Output comment updated). Document the fields in the descriptor tables of `modules/pact/README.md`, `modules/signpost/README.md` and `docs/plugins/menu-item-types.md` (every identifier must exist; the docs checker enforces it). Commit as listed in Execution units.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go test ./modules/signpost -run 'TestContentDescriptorFields|Example' -count=1 -v 2>&1 | tail -30</automated>
|
||||
<fails_when>non-zero exit, a "--- FAIL" line, "no tests to run", or no "--- PASS: TestContentDescriptorFields" line</fails_when>
|
||||
<automated>go vet ./... && go test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
<automated>go test ./cmd/summer -run TestDocsTree -count=1 2>&1 | tail -3 && go run ./cmd/summer docs:build --check 2>&1 | tail -5</automated>
|
||||
<fails_when>non-zero exit, or a "FAIL" or "unknown identifier" line in the output</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "PublishedAt \*time.Time" modules/pact/content.go` prints one line; `grep -n "^type Content\(Ref\|Person\|Image\|Video\|Heading\) struct" modules/pact/content.go` prints five lines
|
||||
- `grep -n "ContentKindArticle\|ContentToolImageAlt" modules/pact/content.go` prints at least two lines
|
||||
- `go doc ./modules/pact ContentRecord` lists PublishedAt, Parents, Authors and TopHeading
|
||||
- TestContentDescriptorFields covers the set-everything type and the set-nothing type and passes
|
||||
- docs/plugins/menu-item-types.md names every new field
|
||||
</acceptance_criteria>
|
||||
<done>A content type can describe the new facts and every consumer of signpost receives them; types that do not set them are unaffected.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Per-request options for plugin field types (RequestOptions) merged into the served schema</name>
|
||||
<files>modules/pact/capabilities.go, modules/cabana/field_type.go, modules/cabana/http.go, modules/cabana/admin_openapi.go, modules/cabana/README.md, modules/cabana/field_request_options_smoke_test.go, modules/pact/README.md, docs/backend/field-types.md, admin/openapi/admin.json, admin/src/api/schema.d.ts</files>
|
||||
<read_first>
|
||||
- modules/pact/capabilities.go (FormFieldType ~689-725)
|
||||
- modules/cabana/field_type.go (compile of TypeOptions ~240-270, Decode/Load call sites)
|
||||
- modules/cabana/http.go (the per-request form schema filter, where visible fields are chosen per administrator)
|
||||
- modules/cabana/schema_types.go (TypeOptions JSON)
|
||||
- modules/cabana/admin_openapi.go (~566, the form description that names typeOptions)
|
||||
- an existing plugin field type test in modules/cabana (grep -ln "FormFieldType{" modules/cabana/*_test.go) for the fixture pattern
|
||||
- docs/backend/field-types.md
|
||||
</read_first>
|
||||
<behavior>
|
||||
- A field type with RequestOptions returning {headingLevels: [2,3,4]} serves typeOptions containing headingLevels on the create form schema, the update form schema and the preview schema
|
||||
- The same key set in fields.yaml for that field wins over the request value
|
||||
- RequestOptions runs once per schema request for each field type, however many fields use the type
|
||||
- RequestOptions returning an error serves the schema with the fields.yaml options only, answers 200, and logs one warning naming the field type
|
||||
- A field type without RequestOptions serves byte-identical schema JSON to v0.5.1 (CanonicalJSON comparison like TestFormExtensionUnextendedSchemaUnchanged)
|
||||
- A form extension's plugin field (32-01) gets its request options the same way
|
||||
</behavior>
|
||||
<action>
|
||||
Per P33-02: add `RequestOptions func(ctx context.Context, db *gorm.DB) (map[string]any, error)` with `json:"-"` and a doc comment to `pact.FormFieldType`. In cabana's form schema path (http.go, where the per-request schema copy is built), for each plugin field whose type has RequestOptions, call it once per type per request with the request's read DB, and merge the result into a copy of that field's TypeOptions (never mutate the compiled schema; keys already present win). On error, log once with the type name and serve the unmerged options. Write `TestFieldTypeRequestOptions` (subtests per behavior line) in `modules/cabana/field_request_options_smoke_test.go` first, then implement. Update the swag description in `admin_openapi.go` (typeOptions: "the type's own fields.yaml keys, plus per-request options the type supplies") and regenerate with `scripts/check-admin-openapi.sh`; commit `admin/openapi/admin.json` and `admin/src/api/schema.d.ts` only if they change. Document RequestOptions in `docs/backend/field-types.md`, `modules/cabana/README.md` and `modules/pact/README.md`. Commit as listed in Execution units.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go test ./modules/cabana -run 'TestFieldTypeRequestOptions|TestFormExtensionUnextendedSchemaUnchanged' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok|PASS)' | tail -30</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or no "--- PASS: TestFieldTypeRequestOptions" line</fails_when>
|
||||
<automated>scripts/check-admin-openapi.sh --check</automated>
|
||||
<fails_when>non-zero exit (the committed OpenAPI or schema.d.ts differs from the generated one)</fails_when>
|
||||
<automated>go vet ./... && go test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "RequestOptions func(ctx context.Context, db \*gorm.DB) (map\[string\]any, error)" modules/pact/capabilities.go` prints one line
|
||||
- `grep -n "RequestOptions" modules/cabana/http.go modules/cabana/field_type.go` prints at least one line
|
||||
- `grep -n "RequestOptions" docs/backend/field-types.md` prints at least one line
|
||||
- TestFieldTypeRequestOptions has a subtest for each behavior line and passes
|
||||
</acceptance_criteria>
|
||||
<done>A plugin field type can deliver per-request options to its element through the existing typeOptions attribute; nothing changes for other field types.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Phase gate script and the v0.5.2 release log</name>
|
||||
<files>scripts/check-phase33.sh, .planning/phases/33-seo-output-audit-and-content/33-release-log.md</files>
|
||||
<read_first>
|
||||
- scripts/check-phase32.sh (whole file: usage, detect_go, go_named, run_* stages, run_self_test, additive_compare, run_compat, run_all, run_stage)
|
||||
- scripts/apisurface/main.go
|
||||
- .planning/phases/32-seo-foundation/32-06-release-log.md (ledger format)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-VALIDATION.md (Wave 0 and the decision-to-test map)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Validation Architecture, release order)
|
||||
</read_first>
|
||||
<action>
|
||||
Create `scripts/check-phase33.sh` from check-phase32.sh's engine (keep detect_go, go_named, the scratch sibling farm, additive and compat logic and the self-test planting style; label everything Phase 33). Stages and what each runs:
|
||||
- `--go`: `go vet ./...` and `go test -short ./...` here;
|
||||
- `--plugins`: vet and `test -short` in ../sm-sitemap-plugin, ../sm-seo-plugin, ../sm-journal-plugin, plus `npm --prefix <repo> run test` (vitest) in sm-seo-plugin and sm-journal-plugin;
|
||||
- `--layers`: for ../vue-seo-layer, ../vue-journal-layer, ../vue-menu-layer, ../vue-faq-layer: `npm --prefix <layer> run test`, `npm --prefix <layer> run build:playground`, and the layer's SSR smoke (journal: `node testing/smoke-ssr.mjs --output .playground/.output --fixtures testing/fixtures/acme --expect testing/expect-acme.txt`; seo: `npm --prefix ../vue-seo-layer run smoke:ssr`; menu and faq: `npm --prefix <layer> run smoke:ssr`), and `node testing/guard-check.mjs` in vue-seo-layer (the build-guard fixtures 33-08 adds);
|
||||
- `--consumers`: build sm-demo-app, sm-grzybyfunkcjonalne-app, sm-summercmsio-app and sm-bm-app (Go `go build ./...`; the Nuxt apps' `build` script);
|
||||
- `--docker`: the Docker suites (`go test ./...` without -short) of the three Go plugins;
|
||||
- `--admin`: `scripts/check-admin-openapi.sh --check` and `scripts/check-admin-dist.sh`;
|
||||
- `--docs`: TestDocsTree and `go run ./cmd/summer docs:build --check`;
|
||||
- `--marker`: the framework diff since v0.5.1 (`git diff v0.5.1 -- modules docs`) names no SEO word, sitemap, JSON-LD or consuming application (the D-90 word list of check-phase32.sh's marker stage, plus the app names grzyby, fonoteka, plytarium, summercmsio, demo.summercms);
|
||||
- `--additive`: apisurface of every changed framework package against the newest tag not containing HEAD;
|
||||
- `--compat`: three consumers tested (sm-sitemap-plugin, sm-journal-plugin, sm-demo-app) and every other sibling that requires the framework built.
|
||||
A stage whose repository or directory is missing fails with "missing <path>" (33-14's `--all` needs every repository; vue-seo-layer appears in 33-07). `--self-test` plants: an additive removal, an interface method added, a marker hit, a failing go test, a missing repo; each must be detected. Then write `33-release-log.md` with sections "Planned contents" (framework v0.5.2 = the six fix SHAs above plus this plan's two seams; `git -C ../sm-seo-plugin log --oneline v0.1.0..HEAD` and `git -C ../sm-journal-plugin log --oneline v0.2.5..HEAD` pasted as the unreleased plugin fixes), "Release order" (framework → sm-journal-plugin → sm-sitemap-plugin → sm-seo-plugin → vue-seo-layer → vue-journal-layer, vue-menu-layer, vue-faq-layer → apps; versions read from `git tag` in 33-14), and an empty "Executed steps" table. Commit group A (script) and group B (release log, planning docs).
|
||||
</action>
|
||||
<verify>
|
||||
<automated>bash scripts/check-phase33.sh --self-test</automated>
|
||||
<fails_when>non-zero exit, or a planted case reported as undetected</fails_when>
|
||||
<automated>bash scripts/check-phase33.sh --go --docs --marker --additive</automated>
|
||||
<fails_when>non-zero exit, or a "FAIL", "refuse:" or marker hit line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `bash scripts/check-phase33.sh` with no argument prints a usage listing all eleven stage flags and exits 2
|
||||
- `grep -c "missing " scripts/check-phase33.sh` is at least 1 (missing-repository failure path)
|
||||
- `grep -n "676ca53\|5471b66\|d660cd0\|468af06\|1583651\|0e187cf" .planning/phases/33-seo-output-audit-and-content/33-release-log.md` prints six lines
|
||||
- the additive stage compares against v0.5.1 and passes
|
||||
</acceptance_criteria>
|
||||
<done>The phase has its gate script and a release ledger; v0.5.2's contents are written down and nothing is released.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| plugin code → framework API | plugins fill descriptor fields and RequestOptions; consumers trust the values only as data |
|
||||
| admin SPA ← form schema | request options reach the browser inside typeOptions |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-01 | Information disclosure | RequestOptions in the served schema | medium | mitigate | the schema is served only to authenticated administrators with access to the form (existing cabana guard); the doc comment states that request options must hold no secret, and TestFieldTypeRequestOptions asserts the merge happens only in the authenticated schema handler |
|
||||
| T-33-02 | Denial of service | RequestOptions called per field | low | mitigate | called once per field type per request (behavior test), errors fail open |
|
||||
| T-33-03 | Tampering | breaking published API | high | mitigate | additive stage of check-phase33.sh (apisurface vs v0.5.1) and the Task 1 checkpoint |
|
||||
| T-33-SC | Tampering | npm/pip/cargo installs | high | accept | this plan installs no package |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `go vet ./... && go test -short ./...` green after every commit.
|
||||
- `bash scripts/check-phase33.sh --self-test` and `--go --docs --marker --additive` pass.
|
||||
- `scripts/check-admin-openapi.sh --check` passes.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- The descriptor fields and RequestOptions exist with docs and smoke tests, strictly additive against v0.5.1.
|
||||
- check-phase33.sh exists and its self-test passes.
|
||||
- The release ledger records v0.5.2's contents; no push, no tag.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Struct fields: `pact.ContentDescriptor.Kind`, `pact.ContentDescriptor.Tools`, `pact.ContentRecord.PublishedAt`, `pact.ContentRecord.Parents`, `pact.ContentRecord.Authors`, `pact.ContentRecord.TopHeading`, `pact.ContentLocale.Images`, `pact.ContentLocale.Videos`, `pact.ContentLocale.Headings`, `pact.FormFieldType.RequestOptions`.
|
||||
- Types: `pact.ContentRef`, `pact.ContentPerson`, `pact.ContentImage`, `pact.ContentVideo`, `pact.ContentHeading`.
|
||||
- Constants: `pact.ContentKindArticle`, `pact.ContentKindCollection`, `pact.ContentKindProfile`, `pact.ContentKindPage`, `pact.ContentToolEdit`, `pact.ContentToolHeadings`, `pact.ContentToolImageAlt`.
|
||||
- Tests: `TestContentDescriptorFields` (modules/signpost/content_fields_smoke_test.go), `TestFieldTypeRequestOptions` (modules/cabana/field_request_options_smoke_test.go).
|
||||
- CLI: `scripts/check-phase33.sh` with `--self-test`, `--go`, `--plugins`, `--layers`, `--consumers`, `--docker`, `--admin`, `--docs`, `--marker`, `--additive`, `--compat`, `--all`.
|
||||
- Files: `.planning/phases/33-seo-output-audit-and-content/33-release-log.md`.
|
||||
- Config keys: none.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-01-SUMMARY.md` when done; record the Task 1 answer (including any renamed field) at the top so plans 33-02 to 33-14 use the final names.
|
||||
</output>
|
||||
363
.planning/phases/33-seo-output-audit-and-content/33-02-PLAN.md
Normal file
363
.planning/phases/33-seo-output-audit-and-content/33-02-PLAN.md
Normal file
@@ -0,0 +1,363 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 02
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: ["33-01"]
|
||||
files_modified:
|
||||
- ../sm-journal-plugin/models/settings.go
|
||||
- ../sm-journal-plugin/models/settings/fields.yaml
|
||||
- ../sm-journal-plugin/updates/202610280001_add_golem15_journal_settings_headings.go
|
||||
- ../sm-journal-plugin/config/config.yaml
|
||||
- ../sm-journal-plugin/plugin.go
|
||||
- ../sm-journal-plugin/classes/headings.go
|
||||
- ../sm-journal-plugin/classes/journal_settings.go
|
||||
- ../sm-journal-plugin/classes/blog_editor.go
|
||||
- ../sm-journal-plugin/classes/format_html.go
|
||||
- ../sm-journal-plugin/classes/media_store.go
|
||||
- ../sm-journal-plugin/classes/media_names.go
|
||||
- ../sm-journal-plugin/classes/image_alt.go
|
||||
- ../sm-journal-plugin/classes/content_descriptors.go
|
||||
- ../sm-journal-plugin/classes/content_facts.go
|
||||
- ../sm-journal-plugin/classes/menu_item_types.go
|
||||
- ../sm-journal-plugin/menu_item_types.go
|
||||
- ../sm-journal-plugin/controllers/api/posts.go
|
||||
- ../sm-journal-plugin/controllers/api/settings.go
|
||||
- ../sm-journal-plugin/controllers/api/maintenance.go
|
||||
- ../sm-journal-plugin/routes.go
|
||||
- ../sm-journal-plugin/mcp.go
|
||||
- ../sm-journal-plugin/console/fix_headings.go
|
||||
- ../sm-journal-plugin/console/import_posts.go
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/element.ts
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/extensions.ts
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/toolbar.ts
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/outline.ts
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/linkform.ts
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/imageform.ts
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/labels.ts
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/blogeditor.css
|
||||
- ../sm-journal-plugin/assets/dist/blogeditor.js
|
||||
- ../sm-journal-plugin/assets/dist/blogeditor.css
|
||||
- ../sm-journal-plugin/tests/blogeditor/fixtures/editor-corpus.json
|
||||
- ../sm-journal-plugin/lang/en/lang.yaml
|
||||
- ../sm-journal-plugin/lang/pl/lang.yaml
|
||||
- ../sm-journal-plugin/README.md
|
||||
- ../sm-journal-plugin/headings_test.go
|
||||
- ../sm-journal-plugin/journal_descriptor_fields_test.go
|
||||
- ../sm-journal-plugin/classes/media_names_test.go
|
||||
autonomous: true
|
||||
requirements: [SC-2, SC-3, D-50, D-51, D-81, D-83, D-85, D-96, D-43, D-93, D-10]
|
||||
|
||||
estimate:
|
||||
tokens: 150000
|
||||
raw_tokens: 150000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Journal has a per-site setting content_h1_to_h2 (Settings › Journal, new tab Headings and links, switch default on) with the config key golem15.journal.content_h1_to_h2 as the value when no settings row exists (2026-10-28 Journal H1 setting, amends D-50)"
|
||||
- "While the setting is on, every H1 saved in post content becomes an H2 on every write path: admin save, the /_journal/api/v1 write API (and so MCP), the markdown path and the import command; the admin save answers the plural notice journal:editor.h1_converted on the editor field and the API answer carries the same phrase in its notices (D-50, D-96, UI-SPEC C27)"
|
||||
- "While the setting is off, content H1 is stored as written, the editor offers H1 to H4, no conversion notice appears, and journal:fix-headings refuses with exit code 1 and the copy that names the setting (2026-10-28 Journal H1 setting, UI-SPEC partial: H1 setting off)"
|
||||
- "Switching the setting on or off never rewrites stored content; only journal:fix-headings --apply (dry run by default) and the MCP tool journal_fix_headings with dry_run false convert stored H1 headings (D-50, UI-SPEC Destructive actions)"
|
||||
- "GET /_journal/api/v1/posts/{slug} carries content_h1_to_h2 (boolean, additive key) so the journal layer reads the setting from the Journal API, not from a layer option (2026-10-28 Journal H1 setting)"
|
||||
- "The Blog Editor receives headingLevels and genericAnchors per request through RequestOptions: H2 to H4 with a pasted H1 parsed as H2 while the setting is on, H1 to H4 while it is off (D-51, UI-SPEC C28 J1)"
|
||||
- "The editor's outline panel (J2) lists headings in document order and flags skipped levels, empty headings, link-only headings, an H1 in Source mode while the setting is on, and links whose whole text is on the generic list; it recomputes 300 ms after a change, starts collapsed, never takes focus on load and never edits content (D-51, D-81)"
|
||||
- "The link form (J3) offers nofollow, sponsored and ugc checkboxes only for absolute http(s) URLs, writes rel with the checked values, never puts rel on internal links, and warns without blocking when the link text is on the generic list; the stored-HTML policy keeps rel with only those three tokens (D-83, D-81, D-80)"
|
||||
- "The image form (J4) sets a slugged file name before upload (lowercase, Polish diacritics transliterated, non-alphanumeric runs to one hyphen, at most 80 characters, empty becomes image), requires alt unless Decorative image is checked, and inserts alt=\"\" for a decorative image; the server applies the same slug rule to uploaded file names (D-85)"
|
||||
- "Journal's descriptors fill the 33-01 fields: posts give PublishedAt, Parents (their categories in order), Authors (with a journal-author reference when author pages are on), Images (featured image plus body images with alt and decorative), Videos (YouTube embeds), Headings and TopHeading (2 while the setting is on, 0 while off), Kind article and Tools {edit: journal_update_post, headings: journal_fix_headings, image_alt: journal_set_image_alt}; categories give Parents (their parent) and Kind collection; tags give Kind collection (D-93, D-43, D-96)"
|
||||
- "A new journal-author menu item type describes author pages (Kind profile, Records of authors with at least one published post, exact Match on the author pattern, host key golem15.journal.author_pages default true), so author pages get the SEO tab, ProfilePage data and a sitemap group (D-43, D-34)"
|
||||
- "MCP has journal_get_settings, journal_update_settings, journal_fix_headings (dry_run) and journal_set_image_alt (dry_run, bulk), each bound to a /_journal/api/v1 route with golem15.journal.manage_settings or golem15.journal.access_posts (D-10, D-85, UI-SPEC MCP parity)"
|
||||
- "The admin save notice, the outline counts and every plural phrase use CLDR maps (en one/other, pl one/few/many/other) (UI-SPEC zero-one-many)"
|
||||
- "J2 shows outlineEmpty when the text has no heading (UI-SPEC empty: J2)"
|
||||
- "J4 keeps the existing uploading status line until the upload result arrives, then inserts the image (UI-SPEC loading: J4)"
|
||||
- {statement: "J4 slug rule: \"Lwia Grzywa – w lesie!.JPG\" becomes lwia-grzywa-w-lesie with the extension .jpg, an empty name becomes image, and names are cut at 80 characters (UI-SPEC J4 backstop)", verification: backstop}
|
||||
- "Planner assumption (UI-SPEC unresolved, J2 long text): outline items with long heading text wrap inside the panel with a hanging indent under the level tag and are never truncated; verify in the editor at 360 px"
|
||||
- "Planner assumption: the H1 setting covers post content only (the setting's label says post content); category pillar content is not converted, and a second H1 there is reported by the crawler as h1_multiple"
|
||||
prohibitions:
|
||||
- requirement_id: "D-50"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "Turning the H1 setting on or off never rewrites already stored content"
|
||||
- requirement_id: "D-96"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: judgment
|
||||
statement: "Journal never imports sm-seo-plugin or names SEO settings; everything SEO reads comes through the signpost descriptor"
|
||||
artifacts:
|
||||
- path: "../sm-journal-plugin/classes/headings.go"
|
||||
provides: "ConvertH1 on the x/net/html tokenizer"
|
||||
contains: "func ConvertH1("
|
||||
- path: "../sm-journal-plugin/console/fix_headings.go"
|
||||
provides: "journal:fix-headings"
|
||||
contains: "journal:fix-headings"
|
||||
- path: "../sm-journal-plugin/classes/content_facts.go"
|
||||
provides: "body images, videos and headings from content_html"
|
||||
contains: "pact.ContentHeading"
|
||||
- path: "../sm-journal-plugin/headings_test.go"
|
||||
provides: "TestHeadingConversionTracer, TestHeadingConversion, TestFixHeadingsCommand, TestSetImageAlt, TestJournalSettingsTools"
|
||||
contains: "func TestHeadingConversionTracer("
|
||||
- path: "../sm-journal-plugin/journal_descriptor_fields_test.go"
|
||||
provides: "TestJournalDescriptorFields, TestJournalAuthorType"
|
||||
contains: "func TestJournalDescriptorFields("
|
||||
key_links:
|
||||
- from: "../sm-journal-plugin/classes/blog_editor.go"
|
||||
to: "../sm-journal-plugin/classes/headings.go"
|
||||
via: "decodeBlogHTML calls ConvertH1 when the setting is on and returns the h1_converted notice"
|
||||
pattern: "ConvertH1\\("
|
||||
- from: "../sm-journal-plugin/controllers/api/posts.go"
|
||||
to: "../sm-journal-plugin/classes/journal_settings.go"
|
||||
via: "Show adds content_h1_to_h2 from the effective setting; Store and Update convert and return notices"
|
||||
pattern: "content_h1_to_h2"
|
||||
- from: "../sm-journal-plugin/classes/blog_editor.go"
|
||||
to: "summercms.go/modules/pact/capabilities.go"
|
||||
via: "the blogeditor and mlblogeditor types set RequestOptions to the settings' heading levels and generic list"
|
||||
pattern: "RequestOptions"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan makes Journal, the first content plugin, supply what the rest of the phase consumes and fix its own content (D-96): the per-site H1 setting with conversion on every write path, the editor's heading levels, outline, link rel and image naming, the new descriptor facts, author pages as a content type, and MCP tools for its settings, stored headings and image alt.
|
||||
|
||||
<objective>
|
||||
Implement in `../sm-journal-plugin` (branch main, not pushed):
|
||||
- the Journal H1 setting (2026-10-28, amends D-50/D-51): column, config key, settings tab, API flag, conversion with notices on every write path, `journal:fix-headings`;
|
||||
- Blog Editor J1–J4 (UI-SPEC C28) on RequestOptions (33-01 P33-02), with the stored-HTML policy keeping `rel` (D-83) and server-side slugged media names (D-85);
|
||||
- descriptor facts for posts, categories and tags plus a `journal-author` type (D-93, D-43);
|
||||
- MCP tools `journal_get_settings`, `journal_update_settings`, `journal_fix_headings`, `journal_set_image_alt` (D-10, D-85).
|
||||
|
||||
Purpose: the layer's title element and htmlGate demotion (33-09), JSON-LD and breadcrumbs (33-06), image and News sitemaps (33-04) and the audit's CMS checks (33-10) all read what this plan provides.
|
||||
|
||||
Output: commits in ../sm-journal-plugin (main, not pushed; 33-14 tags). The framework is used through the existing `replace => ../summercms.go`.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-04 (setting precedence):** the settings row's `content_h1_to_h2` decides; the config key `golem15.journal.content_h1_to_h2` (default true, new `config/config.yaml` shipped through `ConfigFS`) is used only when no settings row exists. `classes.EffectiveH1ToH2(ctx, db, cfg) bool` is the one reader; README documents it.
|
||||
- **P33-05 (bulk alt tool lives in Journal):** the UI-SPEC's `[ASSUMED]` `seo_set_image_alt` becomes `journal_set_image_alt`: alt text is post content, which only Journal may write (D-96); the SEO issue report points at it through `ContentDescriptor.Tools["image_alt"]` (33-10). Research had the tool in 33-11; it moves here with Journal's other content fixes.
|
||||
- **P33-06 (featured image alt):** the featured image alt in descriptors and in the API stays as today (UI-SPEC Q-6): the attachment's title when set, otherwise the post title.
|
||||
- **P33-07 (author type URL):** `journal-author` default pattern `/blog/author/:author` (the journal layer's default route), host override through `menu_items.patterns`, `:author` is the backend user's author_slug.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-01-SUMMARY.md
|
||||
@.planning/phases/32-seo-foundation/32-02-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
From 33-01 (final names in 33-01-SUMMARY.md): pact.ContentDescriptor{Kind, Tools}; pact.ContentRecord{PublishedAt, Parents []ContentRef, Authors []ContentPerson, TopHeading}; pact.ContentLocale{Images []ContentImage, Videos []ContentVideo, Headings []ContentHeading}; pact.FormFieldType.RequestOptions func(ctx, *gorm.DB) (map[string]any, error).
|
||||
sm-journal-plugin today: models/settings.go (row ID 1, Fillable/Rules), models/settings/fields.yaml (tabs general, search, rss), classes/blog_editor.go (BlogEditorTypes, decodeBlogHTML returns pact.FormFieldDecoded{Value, Notices}), classes/format_html.go (bluemonday UGC policy, RequireNoFollowOnLinks(false), SanitizeHTMLReport), classes/media_store.go (StoredMedia{URL, Path}), classes/content_descriptors.go (describePosts, firstImages, describeCategories, describeTag, TagPagesKey), classes/menu_item_types.go (MenuItemTypes, menuAlternates), controllers/api/posts.go (Show ~122, Store, Update, serializePost ~587, featuredImages ~629), controllers/api/rss.go:17-40 (settings row read with defaults), console/export_posts.go:24-60 (bonfire.Command with Bare dry-run flag), mcp.go (tools bound to /_journal/api/v1 routes, permission mcpAccessPosts), admin_permissions.go (golem15.journal.manage_settings, golem15.journal.access_posts), routes.go (public group throttle journal-public-api, write group throttle journal-api).
|
||||
Editor: assets/src/blogeditor/{element.ts (attributes field-name, record-id, locale, ui-locale, options JSON, disabled), toolbar.ts:45-47 heading2..4, extensions.ts:80 heading, labels.ts (format with {name}), blogeditor.css}; tests/blogeditor/*; scripts/check-dist.sh.
|
||||
Copy: UI-SPEC "Journal settings, save notice and console (C27)" and "Blog Editor additions (C28)" tables, en and pl, verbatim.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups per task, staged by path in ../sm-journal-plugin with `git -c safe.directory='*' -C ../sm-journal-plugin add <paths>` then `commit -m "<subject>"`. Leave `go.work.sum` (untracked, another session's) alone. Every commit keeps `go vet ./...` and `go test -short ./...` green there; each group adds the lang keys it uses to both lang files.
|
||||
- Resume check: `git -c safe.directory='*' -C ../sm-journal-plugin log --format=%s | grep -Fx '<subject>'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | `feat: H1 to H2 setting with the admin save conversion (tracer)` | TestHeadingConversionTracer passes |
|
||||
| 2 | A `feat: H1 conversion on the API, markdown and import paths`; B `feat: journal:fix-headings and the settings API`; C `feat: MCP tools for settings, headings and image alt` | all write paths and tools pass |
|
||||
| 3 | A `feat: descriptor dates, parents, authors, media and outline`; B `feat: journal-author content type` | descriptor tests pass |
|
||||
| 4 | A `feat: stored HTML keeps link rel and media names are slugged`; B `feat: editor heading levels and outline panel`; C `feat: editor link rel, generic-anchor warning and image naming`; D `docs: headings, editor and MCP tools in README` | dist check passes; plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "an editor saves a post with an H1 and gets it back as an H2 with a notice, and the public API reports the setting" — one path only</name>
|
||||
<files>../sm-journal-plugin/models/settings.go, ../sm-journal-plugin/models/settings/fields.yaml, ../sm-journal-plugin/updates/202610280001_add_golem15_journal_settings_headings.go, ../sm-journal-plugin/config/config.yaml, ../sm-journal-plugin/plugin.go, ../sm-journal-plugin/classes/headings.go, ../sm-journal-plugin/classes/journal_settings.go, ../sm-journal-plugin/classes/blog_editor.go, ../sm-journal-plugin/controllers/api/posts.go, ../sm-journal-plugin/lang/en/lang.yaml, ../sm-journal-plugin/lang/pl/lang.yaml, ../sm-journal-plugin/headings_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-journal-plugin/models/settings.go, models/settings/fields.yaml, updates/202610060006_create_golem15_journal_settings.go, updates/registry.go
|
||||
- ../sm-seo-plugin/updates/202610280001_add_golem15_seo_redirects_source_key.go (additive ALTER with Rollback)
|
||||
- ../sm-seo-plugin/config/config.yaml and ../sm-seo-plugin/plugin.go:20-30,79-80 (ConfigFS, HasConfig)
|
||||
- ../sm-journal-plugin/classes/blog_editor.go (decodeBlogHTML, removalNotices) and classes/format_html.go (SanitizeHTMLReport)
|
||||
- ../sm-journal-plugin/controllers/api/posts.go (Show, serializePost) and controllers/api/rss.go:17-40
|
||||
- ../sm-journal-plugin/posts_admin_smoke_test.go (admin harness for a post save)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C27 and its copy)
|
||||
</read_first>
|
||||
<action>
|
||||
Per the 2026-10-28 Journal H1 setting and P33-04: migration `202610280001_add_golem15_journal_settings_headings` adds `content_h1_to_h2 boolean NOT NULL DEFAULT true` and `generic_anchors text NULL` to golem15_journal_settings (Rollback drops both), registered in `updates/registry.go` style; model fields ContentH1ToH2 bool and GenericAnchors *string added to Fillable and Rules (boolean; nullable|string|max:5000). fields.yaml gets the tab `golem15.journal::lang.journal.tab_headings` after General with `content_h1_to_h2` (switch, span left, default true, label h1_to_h2_label, comment h1_to_h2_comment) and `generic_anchors` (textarea size small, span full, default = the en and pl seed lists of C27 joined by newlines). New `config/config.yaml` with the commented key `content_h1_to_h2: true`; plugin.go embeds it, implements `ConfigFS()` and asserts `pact.HasConfig`. `classes/journal_settings.go`: `EffectiveH1ToH2(ctx, db, cfg) bool` and `GenericAnchors(ctx, db) []string` (row value, else the seed lists). `classes/headings.go`: `ConvertH1(html string) (string, int)` rewriting `<h1 ...>`/`</h1>` start and end tags to h2 with the x/net/html tokenizer, keeping attributes and every other byte. decodeBlogHTML calls it when EffectiveH1ToH2 is true and appends the notice `golem15.journal::lang.editor.h1_converted` with Count n (FormFieldNotice). Show adds `content_h1_to_h2` to the post payload (additive key; no existing key changes). Lang keys of C27 in en and pl (CLDR plurals). `TestHeadingConversionTracer` in headings_test.go: admin save of a post whose content holds `<h1>A</h1><p>x</p>` stores `<h2>A</h2><p>x</p>` and the save response meta.notices has the converted phrase with count 1; GET /_journal/api/v1/posts/{slug} answers content_h1_to_h2 true; with the setting switched off the same save stores the H1 unchanged, adds no notice, and Show answers false. Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-journal-plugin test ./... -run 'TestHeadingConversionTracer' -count=1 -v 2>&1 | tail -20</automated>
|
||||
<fails_when>non-zero exit, "FAIL" or "no tests to run" in the output, or no "--- PASS: TestHeadingConversionTracer" line</fails_when>
|
||||
<automated>go -C ../sm-journal-plugin vet ./... && go -C ../sm-journal-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "func ConvertH1(" ../sm-journal-plugin/classes/headings.go` prints one line
|
||||
- `grep -n "content_h1_to_h2" ../sm-journal-plugin/updates/202610280001_add_golem15_journal_settings_headings.go ../sm-journal-plugin/models/settings/fields.yaml ../sm-journal-plugin/controllers/api/posts.go` prints a line in each file
|
||||
- `grep -n "h1_converted" ../sm-journal-plugin/lang/en/lang.yaml ../sm-journal-plugin/lang/pl/lang.yaml` prints a line in each
|
||||
- TestHeadingConversionTracer asserts both setting states and passes
|
||||
</acceptance_criteria>
|
||||
<done>The setting exists, the admin save converts H1 with a notice while it is on, and the public post answer reports it.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Conversion on every other write path, journal:fix-headings, the settings API and the MCP tools (settings, fix headings, set image alt)</name>
|
||||
<files>../sm-journal-plugin/controllers/api/posts.go, ../sm-journal-plugin/controllers/api/settings.go, ../sm-journal-plugin/controllers/api/maintenance.go, ../sm-journal-plugin/classes/format_html.go, ../sm-journal-plugin/classes/image_alt.go, ../sm-journal-plugin/console/fix_headings.go, ../sm-journal-plugin/console/import_posts.go, ../sm-journal-plugin/routes.go, ../sm-journal-plugin/mcp.go, ../sm-journal-plugin/plugin.go, ../sm-journal-plugin/lang/en/lang.yaml, ../sm-journal-plugin/lang/pl/lang.yaml, ../sm-journal-plugin/headings_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-journal-plugin/controllers/api/posts.go (Store, Update, the transaction and RecordSaved emission from 62c75b1/7a03640)
|
||||
- ../sm-journal-plugin/controllers/api/record_events.go and auth.go (backend-audience JWT, permissions)
|
||||
- ../sm-journal-plugin/console/export_posts.go:24-60 and console/import_posts.go
|
||||
- ../sm-journal-plugin/mcp.go and mcp_test.go (tool binding pattern)
|
||||
- ../sm-journal-plugin/journal_api_writes_test.go (API write harness)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C27 console copy, MCP parity row)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- API Store and Update of content `<h1 class="x">T</h1>` store `<h2 class="x">T</h2>` and the JSON answer gains `notices: [{message, count}]` with the h1_converted phrase; translated content in a locale converts the same way; with the setting off nothing converts and `notices` is absent
|
||||
- Markdown content (FormatHTML path) with `# T` stores an h2 while on
|
||||
- `journal:import-posts` converts while on and prints the converted count
|
||||
- `journal:fix-headings` (dry run default) prints "Would convert :count H1 headings in :posts posts. Run with --apply to save." and changes nothing; `--apply` converts default and translated content, fires RecordSaved per changed post, prints "Converted :count H1 headings in :posts posts."; nothing to do prints "No H1 headings found in post content."; with the setting off it exits 1 with the refusal copy
|
||||
- GET/PUT /_journal/api/v1/settings read and write content_h1_to_h2 and generic_anchors (other settings columns too) with golem15.journal.manage_settings; 403 without it
|
||||
- POST /_journal/api/v1/fix-headings {dry_run} answers {posts, headings, dry_run} and refuses 409 with the refusal phrase while the setting is off
|
||||
- POST /_journal/api/v1/images/alt {dry_run, changes:[{post_id, locale, src, alt}]} sets alt on the matching img in content_html (default or translated), answers the per-change diff, refuses the whole batch 422 when one src is not in the post, and with dry_run writes nothing
|
||||
- MCP lists journal_get_settings, journal_update_settings, journal_fix_headings and journal_set_image_alt, each bound to its route
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-50, D-96, D-85 and P33-05: call ConvertH1 in the API write paths after sanitizing (default and translated content_html, inside the existing transaction) and return the additive `notices` key; apply it in FormatHTML's caller for markdown content and in console/import_posts.go. `console/fix_headings.go`: bonfire command `journal:fix-headings` modeled on export_posts.go (flags `apply` Bare, `dry-run` implied default; Examples; English output exactly as UI-SPEC), registered in plugin.go Commands(). `controllers/api/settings.go`: ShowSettings/UpdateSettings (validation via the model's Rules). `controllers/api/maintenance.go`: FixHeadings and SetImageAlt handlers running in one transaction (dry_run rolls back), with RecordSaved per changed post through the existing emission helper; `classes/image_alt.go` rewrites the alt attribute of `<img>` whose src equals the change's src with the x/net/html tokenizer (escaping through the tokenizer, never string concatenation). Routes in the write group (throttle journal-api). MCP tools in mcp.go: `get_settings` (GET /settings), `update_settings` (PUT /settings), `fix_headings` (POST /fix-headings), `set_image_alt` (POST /images/alt, destructive true), permissions golem15.journal.manage_settings for the first three and golem15.journal.access_posts for set_image_alt. Tests first in headings_test.go: `TestHeadingConversion` (API, markdown, import, translated), `TestFixHeadingsCommand`, `TestJournalSettingsTools`, `TestSetImageAlt`. Commit groups A, B, C as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-journal-plugin test ./... -run 'TestHeadingConversion|TestFixHeadingsCommand|TestJournalSettingsTools|TestSetImageAlt' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -30</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or one of the four test names missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-journal-plugin vet ./... && go -C ../sm-journal-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "journal:fix-headings" ../sm-journal-plugin/console/fix_headings.go` prints at least one line and `commands_documented_test.go` passes (command documented)
|
||||
- `grep -n '"fix_headings"\|"set_image_alt"\|"get_settings"\|"update_settings"' ../sm-journal-plugin/mcp.go` prints four lines
|
||||
- the refusal copy "H1 to H2 conversion is turned off in the Journal settings (Headings and links). Turn it on first, or keep the H1 headings." appears in console/fix_headings.go
|
||||
- the existing Journal API answer keys are unchanged (journal_api_matrix_test.go passes)
|
||||
</acceptance_criteria>
|
||||
<done>Every write path converts while the setting is on, stored content is only rewritten on request, and Journal's settings and content fixes are MCP tools.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Descriptor facts for posts, categories and tags, and the journal-author content type</name>
|
||||
<files>../sm-journal-plugin/classes/content_descriptors.go, ../sm-journal-plugin/classes/content_facts.go, ../sm-journal-plugin/classes/menu_item_types.go, ../sm-journal-plugin/menu_item_types.go, ../sm-journal-plugin/lang/en/lang.yaml, ../sm-journal-plugin/lang/pl/lang.yaml, ../sm-journal-plugin/journal_descriptor_fields_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-journal-plugin/classes/content_descriptors.go (describePosts, firstImages, describeCategories, describeTag, tagPages, TagPagesKey)
|
||||
- ../sm-journal-plugin/classes/menu_item_types.go (MenuItemTypes, tag type registration, menuAlternates) and menu_item_types.go
|
||||
- ../sm-journal-plugin/controllers/api/authors.go (author lookup by author_slug)
|
||||
- ../sm-journal-plugin/content_descriptors_test.go (fixture style)
|
||||
- summercms.go/modules/pact/content.go (33-01 fields)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- A published post with categories C1, C2 describes Parents [journal-category C1, journal-category C2] in that order, PublishedAt = published_at, Authors [{name, Ref journal-author <user id>}] while author pages are on and Ref.Type "" while off
|
||||
- Its locales list Images: the featured image first (alt per P33-06), then body images in document order with alt, Decorative true for alt="" and width/height from attributes; Videos for each figure data-embed youtube; Headings from h1 to h6 with trimmed text
|
||||
- TopHeading is 2 while content_h1_to_h2 is on and 0 while off; Kind article; Tools has edit, headings and image_alt with the journal_ tool names
|
||||
- A child category describes Parents [its parent]; categories and tags have Kind collection
|
||||
- journal-author: Records lists only authors with a published post, Describe answers the name as Title and the author URL per locale, Match is exact on the pattern, Kind profile; with golem15.journal.author_pages false Describe answers empty URLs and Match never matches
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-93, D-43 and P33-06/P33-07: `classes/content_facts.go` parses content_html once per locale with x/net/html into images (src, alt, decorative, width, height), YouTube videos and headings. Fill the 33-01 fields in describePosts, describeCategories and describeTag (same queries batched per page; no N+1 per record). Add the `journal-author` menu item type next to journal-tag (references and Resolve as the tag type does, Content descriptor with Model = the backend user morph type, Controller "", Kind profile), host key constant `AuthorPagesKey = "golem15.journal.author_pages"` (default true when unset), lang keys for its label. Tests first in journal_descriptor_fields_test.go (`TestJournalDescriptorFields`, `TestJournalAuthorType`). Commit groups A and B.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-journal-plugin test ./... -run 'TestJournalDescriptorFields|TestJournalAuthorType|TestRecordSavedDescribesNewURL' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -20</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestJournalDescriptorFields or TestJournalAuthorType missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-journal-plugin vet ./... && go -C ../sm-journal-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "journal-author" ../sm-journal-plugin/classes/menu_item_types.go` prints at least one line
|
||||
- `grep -n "PublishedAt:\|Parents:\|TopHeading:\|Tools:" ../sm-journal-plugin/classes/content_descriptors.go` prints at least four lines
|
||||
- `grep -n "golem15.journal.author_pages" ../sm-journal-plugin/classes/content_descriptors.go` prints one line
|
||||
</acceptance_criteria>
|
||||
<done>Every Journal content type describes the facts the sitemaps, JSON-LD, breadcrumbs and the audit need, and author pages are a content type.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Blog Editor J1–J4 on RequestOptions, link rel in the stored-HTML policy, slugged media names</name>
|
||||
<files>../sm-journal-plugin/classes/blog_editor.go, ../sm-journal-plugin/classes/format_html.go, ../sm-journal-plugin/classes/media_store.go, ../sm-journal-plugin/classes/media_names.go, ../sm-journal-plugin/classes/media_names_test.go, ../sm-journal-plugin/assets/src/blogeditor/element.ts, ../sm-journal-plugin/assets/src/blogeditor/extensions.ts, ../sm-journal-plugin/assets/src/blogeditor/toolbar.ts, ../sm-journal-plugin/assets/src/blogeditor/outline.ts, ../sm-journal-plugin/assets/src/blogeditor/linkform.ts, ../sm-journal-plugin/assets/src/blogeditor/imageform.ts, ../sm-journal-plugin/assets/src/blogeditor/labels.ts, ../sm-journal-plugin/assets/src/blogeditor/blogeditor.css, ../sm-journal-plugin/assets/dist/blogeditor.js, ../sm-journal-plugin/assets/dist/blogeditor.css, ../sm-journal-plugin/tests/blogeditor/fixtures/editor-corpus.json, ../sm-journal-plugin/lang/en/lang.yaml, ../sm-journal-plugin/lang/pl/lang.yaml, ../sm-journal-plugin/README.md</files>
|
||||
<read_first>
|
||||
- ../sm-journal-plugin/assets/src/blogeditor/{element.ts, extensions.ts, toolbar.ts, labels.ts, blogeditor.css, serializer.ts} and tests/blogeditor/{smoke.test.ts, corpus.test.ts}
|
||||
- ../sm-journal-plugin/classes/blog_editor.go (BlogEditorTypes), format_html.go (newHTMLPolicy), media_store.go
|
||||
- ../sm-journal-plugin/classes/editor_policy_test.go (TestEditorOutputPassesPolicy and the corpus)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C28 J1–J4, Blog Editor copy table, Shared rules, spacing exceptions)
|
||||
- ../sm-journal-plugin/scripts/check-dist.sh
|
||||
</read_first>
|
||||
<action>
|
||||
Per UI-SPEC C28 and D-51, D-81, D-83, D-85: BlogEditorTypes sets RequestOptions to {headingLevels: [2,3,4] or [1,2,3,4] by EffectiveH1ToH2, genericAnchors: GenericAnchors()}. element.ts reads `options.headingLevels` (default [2,3,4]) into the TipTap heading levels with a parse rule mapping `<h1>` to level 2 when 1 is absent; toolbar.ts adds `heading1` first when level 1 is allowed (label heading1). `outline.ts`: the J2 bar `blogeditor__outline-toggle` (aria-expanded, collapsed by default, never focused on load) and panel (ol of headings with level tag, flags flagSkipped, flagEmpty, flagLinkOnly, flagH1 only while level 1 is not allowed and Source mode holds an H1; outlineLinks with flagGeneric per link whose trimmed, lowercased, punctuation-stripped text is on genericAnchors; outlineEmpty; 12px indent per level below the first content level; 300 ms debounce; activating an item moves the caret to the heading; never edits content; long items wrap with a hanging indent). `linkform.ts`: J3 fieldset linkRel with relNofollow, relSponsored, relUgc enabled only for absolute http(s) URLs (relHint otherwise), Apply writes rel, internal links get none, genericWarning line (aria-live polite) without blocking Apply. `imageform.ts`: J4 queue form per file with fileName (slug rule on blur and Insert, extension shown fixed), altText (altRequired unless decorative), decorative checkbox (clears and disables alt, inserts alt=""), caption; Insert uploads the renamed file and inserts on the upload result. labels.ts gets every C28 key in en and pl (CLDR plurals for outlineCount and outlineProblems); blogeditor.css copies the editor metrics listed in UI-SPEC Spacing exceptions, light DOM, `--c-*` colours only. Server: format_html.go allows `rel` on `a` matching `^(nofollow|sponsored|ugc)( (nofollow|sponsored|ugc))*$` (bluemonday AllowAttrs.Matching.OnElements); `classes/media_names.go` `MediaFileName(name string) string` implements the slug rule (smoke test `TestMediaFileName` in classes/media_names_test.go with the UI-SPEC example, an empty name and an 81-character name) and media_store.go applies it to uploads; editor-corpus.json gains a rel link and a decorative image so TestEditorOutputPassesPolicy pins them. Rebuild the bundle with `npm --prefix ../sm-journal-plugin run build` and commit assets/dist with the sources. README: the setting, its precedence, the command, the MCP tools, journal-author and the editor additions. Commit groups A to D as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../sm-journal-plugin run test 2>&1 | tail -15</automated>
|
||||
<fails_when>non-zero exit, or a "FAIL" or "failed" count above 0 in the vitest summary</fails_when>
|
||||
<automated>bash ../sm-journal-plugin/scripts/check-dist.sh</automated>
|
||||
<fails_when>non-zero exit (the committed bundle differs from a fresh build or typecheck fails)</fails_when>
|
||||
<automated>go -C ../sm-journal-plugin test ./... -run 'TestEditorOutputPassesPolicy|TestMediaFileName|TestBlogEditor' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -20</automated>
|
||||
<fails_when>a "FAIL" line or "no tests to run"</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "headingLevels" ../sm-journal-plugin/assets/src/blogeditor/element.ts ../sm-journal-plugin/classes/blog_editor.go` prints a line in each
|
||||
- `grep -n "nofollow|sponsored|ugc" ../sm-journal-plugin/classes/format_html.go` prints one line
|
||||
- `grep -n "flagSkipped\|genericWarning\|decorative" ../sm-journal-plugin/assets/src/blogeditor/labels.ts` prints at least three lines
|
||||
- `grep -n "func MediaFileName(" ../sm-journal-plugin/classes/media_names.go` prints one line, and a Go test asserts "Lwia Grzywa – w lesie!.JPG" → "lwia-grzywa-w-lesie.jpg"
|
||||
- check-dist.sh passes after the dist commit
|
||||
</acceptance_criteria>
|
||||
<done>The editor follows the per-site heading setting, shows the outline and link warnings, writes rel on external links, names and describes images properly, and the server enforces the same rules.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| admin/API/MCP client → Journal write paths | untrusted HTML content and alt text |
|
||||
| editor element ← typeOptions | per-request options shown to administrators |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-04 | Tampering | ConvertH1 / image alt rewrite | high | mitigate | both work on x/net/html tokens after the bluemonday policy, never on raw string replacement; attribute values are re-escaped by the tokenizer; TestSetImageAlt includes an alt with quotes and angle brackets |
|
||||
| T-33-05 | Elevation of privilege | settings and maintenance routes | high | mitigate | backend-audience JWT plus golem15.journal.manage_settings / access_posts, 403 tests in TestJournalSettingsTools |
|
||||
| T-33-06 | Tampering | link rel attribute | medium | mitigate | the policy accepts only the three rel tokens (regex), the corpus test pins it |
|
||||
| T-33-07 | Tampering | uploaded file names | medium | mitigate | MediaFileName slugs server-side ([a-z0-9-], 80 characters) whatever the client sends |
|
||||
| T-33-08 | Denial of service | fix-headings over a large site | low | accept | CLI/MCP operation by an administrator, one transaction per post, dry run by default |
|
||||
| T-33-SC | Tampering | npm/pip/cargo installs | high | accept | no new package; the bundle rebuilds from the committed lockfile |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `go -C ../sm-journal-plugin vet ./... && go -C ../sm-journal-plugin test -short ./...` green after every commit.
|
||||
- Docker suites: TestHeadingConversionTracer, TestHeadingConversion, TestFixHeadingsCommand, TestJournalSettingsTools, TestSetImageAlt, TestJournalDescriptorFields, TestJournalAuthorType.
|
||||
- `npm --prefix ../sm-journal-plugin run test` and `bash ../sm-journal-plugin/scripts/check-dist.sh` pass.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- The H1 setting works in both modes on every write path, and the API exposes it.
|
||||
- The editor additions J1–J4 work as UI-SPEC C28 describes.
|
||||
- Descriptors carry the new facts and author pages are a content type.
|
||||
- Four Journal MCP tools exist.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Config key: `golem15.journal.content_h1_to_h2` (default true), `golem15.journal.author_pages` (default true).
|
||||
- Settings columns: `golem15_journal_settings.content_h1_to_h2`, `golem15_journal_settings.generic_anchors`; migration `202610280001_add_golem15_journal_settings_headings`.
|
||||
- Go symbols: `classes.ConvertH1`, `classes.EffectiveH1ToH2`, `classes.GenericAnchors`, `classes.MediaFileName`, `classes.AuthorPagesKey`, API handlers `ShowSettings`, `UpdateSettings`, `FixHeadings`, `SetImageAlt`; `Plugin.ConfigFS`.
|
||||
- Menu item type: `journal-author`.
|
||||
- Routes: `GET /_journal/api/v1/settings`, `PUT /_journal/api/v1/settings`, `POST /_journal/api/v1/fix-headings`, `POST /_journal/api/v1/images/alt`; additive keys `content_h1_to_h2` (post Show) and `notices` (write answers).
|
||||
- CLI: `journal:fix-headings [--apply]`.
|
||||
- MCP tools: `journal_get_settings`, `journal_update_settings`, `journal_fix_headings`, `journal_set_image_alt`.
|
||||
- Files: `config/config.yaml`, `classes/headings.go`, `classes/journal_settings.go`, `classes/content_facts.go`, `classes/image_alt.go`, `classes/media_names.go`, `console/fix_headings.go`, `controllers/api/settings.go`, `controllers/api/maintenance.go`, `assets/src/blogeditor/{outline,linkform,imageform}.ts`, `headings_test.go`, `journal_descriptor_fields_test.go`.
|
||||
- Lang keys: the C27 and C28 keys (`journal.tab_headings`, `journal.h1_to_h2_label`, `journal.h1_to_h2_comment`, `journal.generic_anchors_label`, `journal.generic_anchors_comment`, `editor.h1_converted`, and the element labels).
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-02-SUMMARY.md` when done.
|
||||
</output>
|
||||
396
.planning/phases/33-seo-output-audit-and-content/33-03-PLAN.md
Normal file
396
.planning/phases/33-seo-output-audit-and-content/33-03-PLAN.md
Normal file
@@ -0,0 +1,396 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 03
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: ["33-01"]
|
||||
files_modified:
|
||||
- ../sm-sitemap-plugin/contract/contract.go
|
||||
- ../sm-sitemap-plugin/classes/slots.go
|
||||
- ../sm-sitemap-plugin/classes/rebuild.go
|
||||
- ../sm-sitemap-plugin/classes/writer.go
|
||||
- ../sm-sitemap-plugin/classes/lastmod.go
|
||||
- ../sm-sitemap-plugin/classes/types.go
|
||||
- ../sm-sitemap-plugin/classes/listing.go
|
||||
- ../sm-sitemap-plugin/classes/generator.go
|
||||
- ../sm-sitemap-plugin/classes/generator_test.go
|
||||
- ../sm-sitemap-plugin/classes/serialize.go
|
||||
- ../sm-sitemap-plugin/classes/serialize_test.go
|
||||
- ../sm-sitemap-plugin/classes/golden_test.go
|
||||
- ../sm-sitemap-plugin/classes/testdata/full.golden
|
||||
- ../sm-sitemap-plugin/classes/testdata/full.json
|
||||
- ../sm-sitemap-plugin/classes/testdata/tracer.golden
|
||||
- ../sm-sitemap-plugin/classes/testdata/tracer.json
|
||||
- ../sm-sitemap-plugin/classes/testdata/urlto.golden
|
||||
- ../sm-sitemap-plugin/classes/testdata/urlto.json
|
||||
- ../sm-sitemap-plugin/classes/tiers.go
|
||||
- ../sm-sitemap-plugin/classes/tiers_test.go
|
||||
- ../sm-sitemap-plugin/classes/rewrite.go
|
||||
- ../sm-sitemap-plugin/classes/rewrite_test.go
|
||||
- ../sm-sitemap-plugin/classes/manifest.go
|
||||
- ../sm-sitemap-plugin/classes/manifest_test.go
|
||||
- ../sm-sitemap-plugin/classes/urlto.go
|
||||
- ../sm-sitemap-plugin/classes/urlto_test.go
|
||||
- ../sm-sitemap-plugin/classes/events.go
|
||||
- ../sm-sitemap-plugin/assets/sitemap.xsl
|
||||
- ../sm-sitemap-plugin/tests/php/gen-goldens.php
|
||||
- ../sm-sitemap-plugin/models/settings.go
|
||||
- ../sm-sitemap-plugin/models/settings/fields.yaml
|
||||
- ../sm-sitemap-plugin/models/settings_test.go
|
||||
- ../sm-sitemap-plugin/models/url.go
|
||||
- ../sm-sitemap-plugin/models/type_setting.go
|
||||
- ../sm-sitemap-plugin/models/definition.go
|
||||
- ../sm-sitemap-plugin/models/definition_item.go
|
||||
- ../sm-sitemap-plugin/models/definition/fields.yaml
|
||||
- ../sm-sitemap-plugin/models/definition_test.go
|
||||
- ../sm-sitemap-plugin/models/registry.go
|
||||
- ../sm-sitemap-plugin/updates/202610280001_create_golem15_sitemap_urls.go
|
||||
- ../sm-sitemap-plugin/updates/202610280002_update_golem15_sitemap_settings.go
|
||||
- ../sm-sitemap-plugin/updates/202610280003_create_golem15_sitemap_types.go
|
||||
- ../sm-sitemap-plugin/updates/registry.go
|
||||
- ../sm-sitemap-plugin/controllers/admin_registry.go
|
||||
- ../sm-sitemap-plugin/controllers/settings.go
|
||||
- ../sm-sitemap-plugin/controllers/settings/config_form.yaml
|
||||
- ../sm-sitemap-plugin/controllers/settings/_sitemap_files.htm
|
||||
- ../sm-sitemap-plugin/controllers/definitions.go
|
||||
- ../sm-sitemap-plugin/controllers/definitions/config_form.yaml
|
||||
- ../sm-sitemap-plugin/controllers/definitions_test.go
|
||||
- ../sm-sitemap-plugin/admin.go
|
||||
- ../sm-sitemap-plugin/extensions_settings.go
|
||||
- ../sm-sitemap-plugin/listeners.go
|
||||
- ../sm-sitemap-plugin/jobs.go
|
||||
- ../sm-sitemap-plugin/schedule.go
|
||||
- ../sm-sitemap-plugin/console/rebuild.go
|
||||
- ../sm-sitemap-plugin/console/import_winter.go
|
||||
- ../sm-sitemap-plugin/console/import.go
|
||||
- ../sm-sitemap-plugin/console/import_winter_test.go
|
||||
- ../sm-sitemap-plugin/import_test.go
|
||||
- ../sm-sitemap-plugin/plugin.go
|
||||
- ../sm-sitemap-plugin/routes.go
|
||||
- ../sm-sitemap-plugin/routes_test.go
|
||||
- ../sm-sitemap-plugin/sitemap_smoke_test.go
|
||||
- ../sm-sitemap-plugin/sitemap_index_test.go
|
||||
- ../sm-sitemap-plugin/config/config.yaml
|
||||
- ../sm-sitemap-plugin/go.mod
|
||||
- ../sm-sitemap-plugin/go.sum
|
||||
- ../sm-sitemap-plugin/lang/en/lang.yaml
|
||||
- ../sm-sitemap-plugin/lang/pl/lang.yaml
|
||||
- ../sm-sitemap-plugin/README.md
|
||||
autonomous: false
|
||||
requirements: [SC-1, D-30, D-32, D-55, D-56, D-57, D-93, D-95, D-24, D-22]
|
||||
|
||||
estimate:
|
||||
tokens: 160000
|
||||
raw_tokens: 160000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "GET /sitemap.xml answers a sitemap index (application/xml) whose entries are per-type files sitemap-<slug>-<n>.xml with a lastmod each; each file lists at most file_size URLs (setting, default 1000, range 1 to 50 000) with <loc> and a real <lastmod>, and no <priority> or <changefreq> (D-30)"
|
||||
- "File numbering is stable: URLs keep their file number across rebuilds, new URLs append to the last file of their group with room, a deleted, unpublished or excluded URL leaves a hole instead of shifting later files, and only a change of file_size renumbers (D-30, RESEARCH Pattern 2, Pitfall 5)"
|
||||
- "A URL's lastmod moves only when its record is saved with a real change (RecordSaved with a non-empty Changes list outside the ignore list golem15.sitemap.lastmod_ignore); a no-op save, a counter update or a rebuild leaves it unchanged (D-30, RESEARCH Pitfall 4)"
|
||||
- "Every URL of a record with more than one translated locale carries xhtml:link alternates for each translated locale including itself, plus x-default pointing to the default locale's URL; a locale without a URL gets no alternate and a single-locale record gets none (D-55, D-56, D-57)"
|
||||
- "The sitemap consumes signpost.Records per content type (D-93) and asks the contract.Filter published by another plugin for each batch; without a Filter everything published is included, and with one, excluded URLs (noindex, canonical, redirect) leave the files and are counted by reason (D-95, D-24)"
|
||||
- "The settings singleton (one tile, AdminSingleton) has the tabs Files (site_url, file_size, the S1 files partial), Content types (per signpost type include switch, file slug, HTML heading) and Additional addresses (url and lastmod rows); it replaces the Phase 17 definitions screen and the old settings tile (D-32, UI-SPEC C26, Q-4)"
|
||||
- "The PHP-parity output is gone: priority tiers, the definitions screen, the update manifest, the festival BeforeAddItem/AddItem events, the PHP goldens and the XSL stylesheet (/sitemap.xsl answers 404); this removal is what resolves the todo .planning/todos/completed/sitemap-xslt-browser-deprecation.md (g15office w8kupqi3), which Jakub moved to completed on 2026-10-28 (D-32)"
|
||||
- "A migration moves every url item of golem15_sitemap_definitions into the Additional addresses rows and frontend_url into site_url; the definitions table stays in the database unread, so a rollback keeps the data (D-32)"
|
||||
- "The site URL of every <loc> is the setting site_url, else the config key golem15.sitemap.site_url, else app.url; the request's Host header is never used"
|
||||
- "Rebuilds run as a conga job: debounced to one queued rebuild per golem15.sitemap.rebuild_delay_seconds (default 60) after record events, on every settings save, nightly through the scheduled command sitemap:rebuild (pact.HasSchedule, 03:00), and by hand with sitemap:rebuild"
|
||||
- "The sitemap plugin publishes contract.Listing (Settings with SiteURL, IndexURL, Groups and the HTML-sitemap and IndexNow fields filled by 33-04; Entries paging the included URLs of a group) for other plugins, without depending on any of them (D-95)"
|
||||
- "The index URL stays /sitemap.xml, so robots.txt Sitemap: lines and Search Console submissions need no change (D-22)"
|
||||
- "S1 shows files.empty before the first build and the files.building callout while a rebuild job runs (UI-SPEC empty and loading: S1, sitemap rebuild)"
|
||||
- "The settings form refuses an invalid file size, file slug, duplicate slug or site address with the errors.* copy of UI-SPEC C26 (UI-SPEC error: save refused)"
|
||||
- {statement: "A file size change renumbers every file in one rebuild and the index lists the new files at once (documented on the field comment)", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-95"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "The sitemap never lists a URL that the published Filter excluded, and never imports or names the SEO plugin"
|
||||
- requirement_id: "D-30"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "A rebuild never moves an existing URL to another file unless file_size changed"
|
||||
artifacts:
|
||||
- path: "../sm-sitemap-plugin/contract/contract.go"
|
||||
provides: "Filter, Candidate, Decision, Group, Listing, ListingSettings, Entry, EntriesQuery, EntriesPage, reasons"
|
||||
contains: "type Filter interface"
|
||||
- path: "../sm-sitemap-plugin/classes/slots.go"
|
||||
provides: "stable slot assignment"
|
||||
contains: "func "
|
||||
- path: "../sm-sitemap-plugin/classes/writer.go"
|
||||
provides: "index and urlset writers on encoding/xml escaping"
|
||||
contains: "xml.EscapeText"
|
||||
- path: "../sm-sitemap-plugin/updates/202610280002_update_golem15_sitemap_settings.go"
|
||||
provides: "settings columns and the definitions url-item migration"
|
||||
contains: "extra_urls"
|
||||
- path: "../sm-sitemap-plugin/sitemap_index_test.go"
|
||||
provides: "TestSitemapIndex, TestStableNumbering, TestLastmod, TestFilterExcludes, TestNoFilter, TestMigrateDefinitions, TestHreflangAlternates"
|
||||
contains: "func TestSitemapIndex("
|
||||
key_links:
|
||||
- from: "../sm-sitemap-plugin/classes/rebuild.go"
|
||||
to: "summercms.go/modules/signpost/content.go"
|
||||
via: "Records per included content type, paged by Next"
|
||||
pattern: "Records\\("
|
||||
- from: "../sm-sitemap-plugin/classes/rebuild.go"
|
||||
to: "../sm-sitemap-plugin/contract/contract.go"
|
||||
via: "app.Lookup[contract.Filter]() decides each batch; absent means include everything"
|
||||
pattern: "Lookup\\[contract\\.Filter\\]"
|
||||
- from: "../sm-sitemap-plugin/listeners.go"
|
||||
to: "../sm-sitemap-plugin/classes/lastmod.go"
|
||||
via: "*pact.RecordSaved with non-ignored Changes sets lastmod; RecordSaved/RecordDeleted queue a debounced rebuild"
|
||||
pattern: "\\*pact\\.RecordSaved"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: priority -->
|
||||
<!-- planner-discipline-allow: changefreq -->
|
||||
<!-- planner-discipline-allow: sitemap.xsl -->
|
||||
<!-- planner-discipline-allow: priority_tiers -->
|
||||
<!-- planner-discipline-allow: cache_seconds -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan rewrites `sm-sitemap-plugin` to the D-30 format (the confirmed breaking change D-32): an index at `/sitemap.xml`, per-type files of a configurable size with stable numbering, real lastmod, hreflang alternates, and the filter contract the SEO plugin implements.
|
||||
|
||||
<objective>
|
||||
Rewrite ../sm-sitemap-plugin (main, not pushed; 33-14 tags the next minor version, breaking):
|
||||
- a published contract sub-package (`contract`) with the Filter other plugins implement and the Listing other plugins read (D-95);
|
||||
- a stored slot table and a rebuild job over signpost content types (D-30, D-93);
|
||||
- event-driven lastmod, hreflang alternates, index and file routes;
|
||||
- the settings singleton replacing the Phase 17 screens, the migration of definitions, and the removal of the PHP-parity code (D-32).
|
||||
|
||||
Purpose: SC-1 ("every site serves a sitemap index with per-type files of a configurable size, stable numbering and real lastmod, consistent with noindex and robots.txt").
|
||||
|
||||
Output: commits in ../sm-sitemap-plugin. Image and News sitemaps, IndexNow, the HTML-sitemap API, the management API and MCP tools are plan 33-04.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-08 (contract package):** `git.golem15.com/golem15/sm-sitemap-plugin/contract` (package `contract`), not the plugin's root package, because importing the root package runs its `init` and registers the plugin. Types: `Candidate{TypeKey, RecordID, Locale, URL string}`; `Decision{Exclude bool; Reason string; Group string; LastMod *time.Time}`; `Group{Key string; Titles map[string]string}`; `Filter interface { Decide(ctx, []Candidate) ([]Decision, error); Groups(ctx) ([]Group, error) }`; reasons `ReasonNoindex = "noindex"`, `ReasonCanonical = "canonical"`, `ReasonRedirect = "redirect"`, `ReasonType = "type"`; `Listing interface { Settings(ctx) (ListingSettings, error); Entries(ctx, EntriesQuery) (EntriesPage, error) }`; `ListingSettings{SiteURL, IndexURL string; DefaultLocale string; Groups []GroupInfo; HTMLEnabled bool; HTMLPaths map[string]string; HTMLPageSize int; KeyFile string}`; `GroupInfo{Key, Slug string; Titles map[string]string; Count int}`; `EntriesQuery{Group, Locale, After string; Limit int}`; `Entry{Group, TypeKey, RecordID, Locale, URL, Title string; LastMod *time.Time}`; `EntriesPage{Entries []Entry; Next string; Total int}`. HTMLEnabled, HTMLPaths, HTMLPageSize and KeyFile stay zero until 33-04 adds their settings.
|
||||
- **P33-09 (routes):** Go serves `GET /sitemap.xml` (index, literal root route) and `GET /_sitemap/files/{file}` (`Where("file", "sitemap-[a-z0-9-]+-[0-9]+\\.xml")`); the index's `<loc>` entries are the public root URLs `<site>/sitemap-<slug>-<n>.xml`, which the SEO layer (33-07) or an nginx rewrite maps to `/_sitemap/files/`. No root wildcard route is registered (it would capture every one-segment path of a site Go serves).
|
||||
- **P33-10 (slot table):** `golem15_sitemap_urls` (id, grp, type_key, record_id, locale, url (path), title, file_no, first_seen, lastmod, alternates jsonb, images jsonb, excluded_reason, updated_at; unique (type_key, record_id, locale); index (grp, file_no)). Extra addresses use type_key `extra` and record_id = hex sha256 of the path. Group = per-type slug unless the Filter's Decision.Group overrides it; extra addresses go to `pages`. Default slug: last segment of the type key pluralised (y→ies, else +s unless it ends in s): journal-post → posts, journal-category → categories, journal-tag → tags, journal-author → authors, seo-page → pages.
|
||||
- **P33-11 (reasons shown):** S1's left-out table shows noindex, canonical, redirect and type; unpublished and deleted rows are holes, not "left out".
|
||||
- **P33-12 (debounce):** `golem15_sitemap_settings.rebuild_pending_until timestamptz`; an event sets it with a conditional UPDATE and enqueues one rebuild with that delay only when no pending time lies in the future; the job clears it.
|
||||
</objective>
|
||||
|
||||
<assumption_delta_decision>
|
||||
Signal: "chosen" (the ROADMAP's "per-type files of a configurable size").
|
||||
Primary noun: a sitemap file is (group slug, file number) under a per-site file size; the single PHP file is gone.
|
||||
Decision: promote. The per-type index becomes the only format (D-32); file size is a real setting (default 1000, 1 to 50 000, renumbering on change), not a constant.
|
||||
Invariant test: TestStableNumbering (deletes leave holes, new URLs append, only a file-size change renumbers).
|
||||
</assumption_delta_decision>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-01-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
signpost (framework): Registry.ContentTypes() / ContentType(key) / Records(ctx, key, ContentList) / Describe(ctx, key, id, unprefixed); pact.ContentRecord{ID, Published, LastMod, PublishedAt, Parents, Authors, TopHeading, Locales[]{Locale, URL, Title, Description, Image, Words, Images, Videos, Headings}}; pact.RecordSaved{Controller, Model, ID, Locale, Created, Changes []RecordChange{Attribute, Locale, Old, New}}; pact.RecordDeleted.
|
||||
conga: conga.Job(fn, conga.MaxAttempts(n)); conga.From(app).Dispatch(ctx, db, args, conga.DispatchOpts{Label, Delay}); Enqueue(ctx, db, args, conga.EnqueueOpts{Delay}); pact.HasJobs; pact.HasSchedule → []pact.ScheduledCommand{Command, Args, Cadence: pact.DailyAt(3, 0)}.
|
||||
Analogs: ../sm-seo-plugin/jobs.go + classes/generate.go (job kind and dispatch after commit with lagoon.AfterCommit), ../sm-seo-plugin/extensions_settings.go (per-type settings tabs as a FieldsYAML document built at boot from signpost ContentTypes on the plugin's own singleton), ../sm-seo-plugin/controllers/settings.go (AdminSingleton linked from SettingsItem.Controller, D-104), ../sm-seo-plugin/classes/settings_write.go (settings singleton + history pattern).
|
||||
Today's plugin: routes.go (GET /sitemap.xml, /sitemap.xsl, cache), models/settings.go (frontend_url, frontend_default_locale, updates_manifest_path, tiers), models/definition*.go, controllers/definitions.go, classes/{generator,serialize,tiers,rewrite,manifest,urlto,events}.go, console/import_winter.go (PHP rows), config/config.yaml (cache_seconds, priority_tiers), plugin.go (Requires nil, init registers).
|
||||
XML namespaces: sitemap 0.9 http://www.sitemaps.org/schemas/sitemap/0.9, xhtml http://www.w3.org/1999/xhtml.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups staged by path in ../sm-sitemap-plugin (`git -c safe.directory='*' -C ../sm-sitemap-plugin add <paths>`; deletions with `git rm`). Every commit keeps `go vet ./...` and `go test -short ./...` green there. The go.mod require stays on the existing framework tag with `replace => ../summercms.go` (already present); 33-14 bumps it.
|
||||
- Resume check: `git -c safe.directory='*' -C ../sm-sitemap-plugin log --format=%s | grep -Fx '<subject>'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | none (checkpoint answer recorded in the SUMMARY) | answer recorded |
|
||||
| 2 | `feat: sitemap index and per-type files from a slot table (tracer)` | TestSitemapIndex passes |
|
||||
| 3 | A `feat: sitemap settings singleton with content types and additional addresses`; B `feat!: remove the PHP-parity sitemap, tiers, definitions screen and XSL`; C `feat: migrate definitions into additional addresses` | settings and migration tests pass |
|
||||
| 4 | A `feat: real lastmod from record events and debounced rebuilds`; B `feat: hreflang alternates and the sitemap filter contract`; C `docs: README for the per-type sitemap format` | all sitemap_index_test.go tests pass; plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 1: Confirm the concrete public format of the new sitemaps</name>
|
||||
<reversibility rating="one-way">The file names and the index URL are public: Search Console submissions, robots.txt and crawlers' caches follow them, and grzybyfunkcjonalne.pl moves to them in 33-13.</reversibility>
|
||||
<decision>D-32 (the breaking switch) is decided; this confirms the concrete URLs, the XSL removal and the folding of the Phase 17 screen before code is written.</decision>
|
||||
<context>
|
||||
Proposed (RESEARCH A4, A5, Pitfall 8; UI-SPEC Q-4): (1) the index stays at /sitemap.xml, so GSC and robots.txt keep their URL; (2) files are /sitemap-<slug>-<n>.xml at the site root, slug per content type (posts, categories, tags, authors, pages; registry kinds offers, services, landing-pages), plus sitemap-images-<n>.xml and sitemap-news.xml in 33-04; Go serves them under /_sitemap/files/ and the SEO layer or nginx maps the root; (3) the XSL view is removed (Chrome 158 stops running XSLT on 2026-11-17; the HTML sitemap is the human view), which resolves the todo sitemap-xslt-browser-deprecation.md (g15office w8kupqi3; already moved to .planning/todos/completed on 2026-10-28); (4) the Phase 17 "Sitemap" definitions screen and the old settings tile become one settings singleton; url items migrate to Additional addresses; priority, change frequency, tiers and the update manifest are removed; the definitions table stays unread in the database.
|
||||
</context>
|
||||
<options>
|
||||
<option id="as-proposed">
|
||||
<name>Adopt (1) to (4)</name>
|
||||
<pros>No GSC resubmission of the index; one admin screen; no XSL left to break</pros>
|
||||
<cons>Editors lose the styled XML view (replaced by the HTML sitemap, 33-04/33-08)</cons>
|
||||
</option>
|
||||
<option id="keep-xsl">
|
||||
<name>Adopt (1), (2), (4) and keep an XSL for the index only</name>
|
||||
<pros>A styled view for browsers that still run XSLT</pros>
|
||||
<cons>Breaks in Chrome from 2026-11-17; the completed todo would have to be reopened</cons>
|
||||
</option>
|
||||
<option id="other-names">
|
||||
<name>Adopt with other file names or another index URL (stated in the answer)</name>
|
||||
<pros>Names chosen by Jakub before they become public</pros>
|
||||
<cons>A new index URL needs a GSC submission and robots.txt change on every site</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "as-proposed", "keep-xsl" or "other-names: <names>"</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 2: End-to-end "a content type's published records appear in an index at /sitemap.xml that links per-type files of N URLs" — one path only</name>
|
||||
<files>../sm-sitemap-plugin/contract/contract.go, ../sm-sitemap-plugin/models/url.go, ../sm-sitemap-plugin/models/registry.go, ../sm-sitemap-plugin/updates/202610280001_create_golem15_sitemap_urls.go, ../sm-sitemap-plugin/updates/202610280002_update_golem15_sitemap_settings.go, ../sm-sitemap-plugin/updates/registry.go, ../sm-sitemap-plugin/models/settings.go, ../sm-sitemap-plugin/classes/slots.go, ../sm-sitemap-plugin/classes/rebuild.go, ../sm-sitemap-plugin/classes/writer.go, ../sm-sitemap-plugin/jobs.go, ../sm-sitemap-plugin/routes.go, ../sm-sitemap-plugin/plugin.go, ../sm-sitemap-plugin/sitemap_index_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-sitemap-plugin/plugin.go, routes.go, models/settings.go, updates/202610110002_create_golem15_sitemap_settings.go, testmain_test.go, sitemap_smoke_test.go
|
||||
- ../sm-seo-plugin/jobs.go and classes/generate.go:14-28,168-177 (job kind, dispatch)
|
||||
- ../sm-seo-plugin/fixture_test.go (a fake content type plugin in tests)
|
||||
- summercms.go/modules/signpost/content.go (Records paging)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pattern 2, Code Examples: index writer)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-30, D-93 and P33-08 to P33-10: create the contract package with every type of P33-08. Migration 202610280001 creates golem15_sitemap_urls (P33-10); migration 202610280002 adds to golem15_sitemap_settings: site_url text, file_size integer NOT NULL DEFAULT 1000, default_locale text, extra_urls jsonb NOT NULL DEFAULT '[]', rebuild_pending_until timestamptz (the url-item copy is Task 3's). models/url.go and the new Settings fields. `classes/slots.go`: assign file numbers per group (keep existing numbers, append to the last file with room by first_seen then id, holes stay). `classes/rebuild.go`: `Rebuild(ctx, app) (RebuildResult, error)` walks signpost.ContentTypes, pages Records (Limit 500), keeps Published records with a URL per locale, upserts rows (title from ContentLocale.Title, lastmod initialised from the record's LastMod), marks vanished rows excluded "deleted", assigns slots in one transaction, and returns added/changed/removed URL lists (IndexNow in 33-04 uses them). `classes/writer.go`: index and urlset writers with bufio and `xml.EscapeText`, RFC 3339 UTC lastmod, no priority and no change frequency. jobs.go: `RebuildArgs` (kind `golem15.sitemap.rebuild`) with conga.MaxAttempts(3); plugin.go asserts pact.HasJobs. routes.go: replace the old handlers with the index (`GET /sitemap.xml`, absolute <loc> on the site URL per the precedence in must_haves) and `GET /_sitemap/files/{file}` (P33-09), both reading the table, content type application/xml, X-Robots-Tag noindex on files, 404 for an unknown or empty file; keep the throttle bucket. `TestSitemapIndex` in sitemap_index_test.go (Docker): a fake content type with 5 published records and 1 draft, file_size 2 → after Rebuild the index lists sitemap-pages-1.xml to -3.xml with lastmod; file 1 lists 2 URLs with absolute <loc> and <lastmod>; the draft is absent; no priority or change frequency element anywhere; an unknown file answers 404. Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-sitemap-plugin test ./... -run 'TestSitemapIndex' -count=1 -v 2>&1 | tail -20</automated>
|
||||
<fails_when>non-zero exit, "FAIL" or "no tests to run" in the output, or no "--- PASS: TestSitemapIndex" line</fails_when>
|
||||
<automated>go -C ../sm-sitemap-plugin vet ./... && go -C ../sm-sitemap-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "type Filter interface\|type Listing interface" ../sm-sitemap-plugin/contract/contract.go` prints two lines
|
||||
- `grep -n "xml.EscapeText" ../sm-sitemap-plugin/classes/writer.go` prints at least one line
|
||||
- `grep -n "/_sitemap/files/{file}" ../sm-sitemap-plugin/routes.go` prints one line
|
||||
- `grep -rn "party.Register\|func init" ../sm-sitemap-plugin/contract/` prints nothing
|
||||
</acceptance_criteria>
|
||||
<done>A real index and per-type files are served from the slot table after a rebuild job.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Settings singleton (Files, Content types, Additional addresses), removal of the PHP-parity code, and the definitions migration</name>
|
||||
<files>../sm-sitemap-plugin/models/settings.go, ../sm-sitemap-plugin/models/settings/fields.yaml, ../sm-sitemap-plugin/models/settings_test.go, ../sm-sitemap-plugin/models/type_setting.go, ../sm-sitemap-plugin/models/registry.go, ../sm-sitemap-plugin/updates/202610280002_update_golem15_sitemap_settings.go, ../sm-sitemap-plugin/updates/202610280003_create_golem15_sitemap_types.go, ../sm-sitemap-plugin/updates/registry.go, ../sm-sitemap-plugin/classes/types.go, ../sm-sitemap-plugin/controllers/admin_registry.go, ../sm-sitemap-plugin/controllers/settings.go, ../sm-sitemap-plugin/controllers/settings/config_form.yaml, ../sm-sitemap-plugin/controllers/settings/_sitemap_files.htm, ../sm-sitemap-plugin/admin.go, ../sm-sitemap-plugin/extensions_settings.go, ../sm-sitemap-plugin/console/import_winter.go, ../sm-sitemap-plugin/console/import.go, ../sm-sitemap-plugin/console/import_winter_test.go, ../sm-sitemap-plugin/import_test.go, ../sm-sitemap-plugin/routes_test.go, ../sm-sitemap-plugin/sitemap_smoke_test.go, ../sm-sitemap-plugin/config/config.yaml, ../sm-sitemap-plugin/plugin.go, ../sm-sitemap-plugin/lang/en/lang.yaml, ../sm-sitemap-plugin/lang/pl/lang.yaml, ../sm-sitemap-plugin/sitemap_index_test.go, ../sm-sitemap-plugin/classes/generator.go, ../sm-sitemap-plugin/classes/generator_test.go, ../sm-sitemap-plugin/classes/serialize.go, ../sm-sitemap-plugin/classes/serialize_test.go, ../sm-sitemap-plugin/classes/golden_test.go, ../sm-sitemap-plugin/classes/testdata/full.golden, ../sm-sitemap-plugin/classes/testdata/full.json, ../sm-sitemap-plugin/classes/testdata/tracer.golden, ../sm-sitemap-plugin/classes/testdata/tracer.json, ../sm-sitemap-plugin/classes/testdata/urlto.golden, ../sm-sitemap-plugin/classes/testdata/urlto.json, ../sm-sitemap-plugin/classes/tiers.go, ../sm-sitemap-plugin/classes/tiers_test.go, ../sm-sitemap-plugin/classes/rewrite.go, ../sm-sitemap-plugin/classes/rewrite_test.go, ../sm-sitemap-plugin/classes/manifest.go, ../sm-sitemap-plugin/classes/manifest_test.go, ../sm-sitemap-plugin/classes/urlto.go, ../sm-sitemap-plugin/classes/urlto_test.go, ../sm-sitemap-plugin/classes/events.go, ../sm-sitemap-plugin/assets/sitemap.xsl, ../sm-sitemap-plugin/tests/php/gen-goldens.php, ../sm-sitemap-plugin/models/definition.go, ../sm-sitemap-plugin/models/definition_item.go, ../sm-sitemap-plugin/models/definition/fields.yaml, ../sm-sitemap-plugin/models/definition_test.go, ../sm-sitemap-plugin/controllers/definitions.go, ../sm-sitemap-plugin/controllers/definitions/config_form.yaml, ../sm-sitemap-plugin/controllers/definitions_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-sitemap-plugin/admin.go, controllers/definitions.go, models/definition*.go, console/import_winter.go and import_test.go
|
||||
- ../sm-seo-plugin/controllers/settings.go, controllers/settings/config_form.yaml, extensions_settings.go (singleton + per-type tabs pattern)
|
||||
- ../sm-seo-plugin/controllers/rules/_seo_status.htm (partial view-model pattern with summer-callout and summer-table classes)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C26, S1, the sitemap copy table, Destructive actions: file size)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- The settings tile (icon network, existing category, label sitemap:settings.label) opens the singleton; the old Phase 17 tile and the definitions screen are gone
|
||||
- Content types tab lists one block per registered signpost type in registration order: type_<key>_include (switch default on), type_<key>_slug (default per P33-10), type_<key>_title (mltext, default the type label); a duplicate slug refuses with errors.slug_taken, a slug outside [a-z0-9-] with errors.slug
|
||||
- file_size outside 1..50000 refuses with errors.file_size; site_url refuses with the existing errors.frontend_url phrase when not an absolute http(s) URL
|
||||
- Saving dispatches a rebuild; a type switched off moves its rows to excluded reason type
|
||||
- Additional addresses rows (url path, optional lastmod) appear in the pages group with their lastmod
|
||||
- Migration: definitions url items become extra_urls rows (url as given, no lastmod), frontend_url becomes site_url, frontend_default_locale becomes default_locale; reference items are dropped (content types cover them); the definitions table is untouched; Rollback clears the copied values only
|
||||
- sitemap:import-winter writes PHP url items into extra_urls (the companion import path of the apps keeps working)
|
||||
- GET /sitemap.xsl answers 404; the old cache config key is gone
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-32, UI-SPEC C26 and Task 1's answer: build the singleton controller `golem15.sitemap.settings` (AdminSingleton, settings tile via SettingsItem.Controller) with fields.yaml tabs Files (site_url text left, file_size number right, files partial S1 full), Additional addresses (extra_urls repeater, titleFrom url, rows url text left and lastmod datepicker right); the Content types tab is a FieldsYAML document built at boot from signpost ContentTypes by a self-extension on the singleton (the SEO plugin's extensions_settings.go pattern), stored in golem15_sitemap_types (type_key unique, include bool, slug, title via the translation writer) created by migration 202610280003. S1 partial `_sitemap_files.htm`: summer-table of files (index first; File in DM Mono linked to the public URL, Addresses, Last modified), then the Left out table by reason (P33-11), then the files.index_note callout; files.empty and files.building per C26. Remove the PHP-parity code and its tests (git rm the files listed in files_modified), the definitions controller, model and form, and the `cache_seconds` and `priority_tiers` config keys; config/config.yaml gets commented `site_url`, `lastmod_ignore` (default [updated_at, created_at, views, sort_order]) and `rebuild_delay_seconds` (60). Extend migration 202610280002 with the url-item copy (write the TestMigrateDefinitions case first). Retarget console/import_winter.go to extra_urls. Every copy key of the C26 sitemap table in both lang files. Commit groups A, B, C.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-sitemap-plugin test ./... -run 'TestSettingsSingleton|TestMigrateDefinitions|TestImportWinter|TestSitemapIndex' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -20</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestSettingsSingleton or TestMigrateDefinitions missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-sitemap-plugin vet ./... && go -C ../sm-sitemap-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../sm-sitemap-plugin ls-files assets classes/testdata tests/php` prints nothing
|
||||
- `grep -rn "priority_tiers\|cache_seconds" ../sm-sitemap-plugin --include=*.go --include=*.yaml` prints nothing
|
||||
- `grep -n "golem15.sitemap.settings" ../sm-sitemap-plugin/controllers/settings.go` prints at least one line
|
||||
- TestMigrateDefinitions asserts the copied extra_urls, the site_url and that golem15_sitemap_definitions still holds its rows
|
||||
</acceptance_criteria>
|
||||
<done>One settings screen manages the new format, the PHP-parity code is gone and existing sites' data migrates.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 4: Real lastmod from record events, debounced and nightly rebuilds, hreflang alternates, and the Filter and Listing contract</name>
|
||||
<files>../sm-sitemap-plugin/classes/lastmod.go, ../sm-sitemap-plugin/classes/rebuild.go, ../sm-sitemap-plugin/classes/writer.go, ../sm-sitemap-plugin/classes/listing.go, ../sm-sitemap-plugin/listeners.go, ../sm-sitemap-plugin/schedule.go, ../sm-sitemap-plugin/console/rebuild.go, ../sm-sitemap-plugin/plugin.go, ../sm-sitemap-plugin/README.md, ../sm-sitemap-plugin/sitemap_index_test.go, ../sm-sitemap-plugin/commands_documented_test.go</files>
|
||||
<read_first>
|
||||
- summercms.go/modules/pact/record_events.go (RecordSaved, RecordChange, no-op saves fire with empty Changes)
|
||||
- ../sm-seo-plugin/listeners.go (subscribing to *pact.RecordSaved / *pact.RecordDeleted on app.Events)
|
||||
- ../sm-seo-plugin/classes/settings_write.go:301-313 (lagoon.AfterCommit enqueue)
|
||||
- summercms.go/modules/pact/capabilities.go (HasSchedule, ScheduledCommand, DailyAt) and docs/plugins/scheduling.md
|
||||
- ../sm-journal-plugin/classes/menu_item_types.go:53-55 (the single x-default alternate when translate has no locale)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pitfalls 3, 4, 5; Pattern 3)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- TestStableNumbering: 5 URLs at size 2 → files 1,1,2,2,3; delete the second → file 1 keeps one URL (hole), files 2 and 3 unchanged; add two → they go to file 3 then a new file 4; change size to 3 → renumbered 1,1,1,2,2,2
|
||||
- TestLastmod: a save whose Changes touch title moves lastmod of that record's rows (only the changed locale's row for a translated change); a save with empty Changes or only updated_at/views does not; a rebuild never moves lastmod
|
||||
- TestHreflangAlternates: a record with pl and en URLs → each url element carries xhtml:link for pl, en and x-default (default locale's URL); a record with only pl → none; a locale with an empty URL → absent
|
||||
- TestFilterExcludes: with a published Filter returning Exclude noindex for one candidate and Group offers for another, the first leaves the files (counted under noindex), the second lands in sitemap-offers-1.xml; Filter.Groups titles reach Listing.Settings Groups
|
||||
- TestNoFilter: without a Filter, everything published is listed
|
||||
- TestDebouncedRebuild: three RecordSaved events within the delay queue exactly one rebuild job
|
||||
- Listing.Entries pages a group's included URLs by after/limit with Total; Listing.Settings answers SiteURL, IndexURL and Groups with counts
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-30, D-55 to D-57, D-95 and P33-12: listeners.go subscribes `*pact.RecordSaved` and `*pact.RecordDeleted` (type looked up with signpost ContentTypeForModel); `classes/lastmod.go` sets lastmod = now on the record's rows when a change outside `golem15.sitemap.lastmod_ignore` exists (Locale "" → every locale row, else that locale's row), then requests a debounced rebuild (P33-12) after commit; RecordDeleted marks rows excluded deleted and requests a rebuild. rebuild.go: batch candidates per page through `app.Lookup[contract.Filter]()` when present (Decide; Exclude → excluded_reason; Group → grp; LastMod → initial lastmod for new rows only), excluded types (include off) → reason type; alternates per record = translated locales with a URL (≥2) plus x-default on default_locale (settings, else the record's first locale). writer.go emits xhtml:link alternates (namespace declared on the urlset only when used). `classes/listing.go` implements contract.Listing over the table and settings and plugin.go publishes it in Register with `app.Publish[contract.Listing]`. schedule.go: pact.HasSchedule with `{Command: "sitemap:rebuild", Cadence: pact.DailyAt(3, 0)}`; console/rebuild.go runs a rebuild synchronously (`--queue` dispatches the job instead), documented for commands_documented_test.go. README rewritten for the new format: routes, settings, contract package (with a Filter example), lastmod rules, config keys, the breaking change and the migration. Tests first per behavior list. Commit groups A, B, C.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-sitemap-plugin test ./... -run 'TestSitemapIndex|TestStableNumbering|TestLastmod|TestHreflangAlternates|TestFilterExcludes|TestNoFilter|TestDebouncedRebuild|TestMigrateDefinitions' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -30</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or any of the eight names missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-sitemap-plugin vet ./... && go -C ../sm-sitemap-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "Lookup\[contract.Filter\]" ../sm-sitemap-plugin/classes/rebuild.go` prints one line
|
||||
- `grep -n "Publish\[contract.Listing\]\|Publish(" ../sm-sitemap-plugin/plugin.go` prints at least one line
|
||||
- `grep -n "sitemap:rebuild" ../sm-sitemap-plugin/schedule.go ../sm-sitemap-plugin/console/rebuild.go` prints a line in each
|
||||
- `grep -n "x-default" ../sm-sitemap-plugin/classes/rebuild.go ../sm-sitemap-plugin/classes/writer.go` prints at least one line
|
||||
</acceptance_criteria>
|
||||
<done>The sitemap is event-driven, multilingual, filterable by another plugin and readable through the published Listing.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| crawlers → /sitemap.xml, /_sitemap/files | anonymous, throttled reads |
|
||||
| content data → XML output | titles and URLs written into XML |
|
||||
| other plugins → contract.Filter | in-process decisions |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-09 | Tampering | XML writer | high | mitigate | every value through xml.EscapeText; only http(s) absolute locs built from the site URL setting/config, never from Host; TestSitemapIndex includes a title and path with &, < and quotes |
|
||||
| T-33-10 | Denial of service | file and index routes | medium | mitigate | served from the table (no per-request generation), existing per-IP bucket kept, files route constrained by Where |
|
||||
| T-33-11 | Information disclosure | unpublished records | high | mitigate | only Published records with a URL are stored as included; drafts tested absent |
|
||||
| T-33-12 | Tampering | settings site_url | medium | mitigate | absolute http(s) validation, settings guarded by the existing sitemap permission |
|
||||
| T-33-SC | Tampering | npm/pip/cargo installs | high | accept | no new package |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `go -C ../sm-sitemap-plugin vet ./... && go -C ../sm-sitemap-plugin test -short ./...` after every commit.
|
||||
- Docker suite: the eight sitemap_index_test.go tests plus TestSettingsSingleton and TestImportWinter.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- /sitemap.xml is an index of per-type files with stable numbering, real lastmod and hreflang.
|
||||
- The sitemap works with and without a Filter; the PHP-parity mode is gone and old data migrates.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Package `git.golem15.com/golem15/sm-sitemap-plugin/contract`: `Filter`, `Candidate`, `Decision`, `Group`, `Listing`, `ListingSettings`, `GroupInfo`, `EntriesQuery`, `Entry`, `EntriesPage`, `ReasonNoindex`, `ReasonCanonical`, `ReasonRedirect`, `ReasonType`.
|
||||
- Go symbols: `classes.Rebuild`, `classes.RebuildResult`, `RebuildArgs` (kind `golem15.sitemap.rebuild`), the Listing implementation.
|
||||
- Tables/columns: `golem15_sitemap_urls`; `golem15_sitemap_types`; settings columns `site_url`, `file_size`, `default_locale`, `extra_urls`, `rebuild_pending_until`; migrations 202610280001 to 202610280003.
|
||||
- Routes: `GET /sitemap.xml` (index), `GET /_sitemap/files/{file}`; removed `GET /sitemap.xsl`.
|
||||
- Admin: controller `golem15.sitemap.settings` (singleton), partial `sitemap_files` (S1).
|
||||
- CLI: `sitemap:rebuild [--queue]`; schedule entry `sitemap:rebuild` daily 03:00.
|
||||
- Config keys: `golem15.sitemap.site_url`, `golem15.sitemap.lastmod_ignore`, `golem15.sitemap.rebuild_delay_seconds`; removed `golem15.sitemap.cache_seconds`, `golem15.sitemap.priority_tiers`.
|
||||
- Tests: `TestSitemapIndex`, `TestStableNumbering`, `TestLastmod`, `TestHreflangAlternates`, `TestFilterExcludes`, `TestNoFilter`, `TestDebouncedRebuild`, `TestMigrateDefinitions`, `TestSettingsSingleton`.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-03-SUMMARY.md` when done; note the Task 1 answer and, if g15office task w8kupqi3 is still open, that it can be closed as resolved by removal.
|
||||
</output>
|
||||
289
.planning/phases/33-seo-output-audit-and-content/33-04-PLAN.md
Normal file
289
.planning/phases/33-seo-output-audit-and-content/33-04-PLAN.md
Normal file
@@ -0,0 +1,289 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 04
|
||||
type: execute
|
||||
wave: 3
|
||||
depends_on: ["33-03"]
|
||||
files_modified:
|
||||
- ../sm-sitemap-plugin/classes/images.go
|
||||
- ../sm-sitemap-plugin/classes/news.go
|
||||
- ../sm-sitemap-plugin/classes/indexnow.go
|
||||
- ../sm-sitemap-plugin/classes/htmlgroups.go
|
||||
- ../sm-sitemap-plugin/classes/rebuild.go
|
||||
- ../sm-sitemap-plugin/classes/slots.go
|
||||
- ../sm-sitemap-plugin/classes/writer.go
|
||||
- ../sm-sitemap-plugin/classes/listing.go
|
||||
- ../sm-sitemap-plugin/models/settings.go
|
||||
- ../sm-sitemap-plugin/models/settings/fields.yaml
|
||||
- ../sm-sitemap-plugin/models/url.go
|
||||
- ../sm-sitemap-plugin/updates/202610280004_add_golem15_sitemap_media_news_indexnow.go
|
||||
- ../sm-sitemap-plugin/updates/registry.go
|
||||
- ../sm-sitemap-plugin/controllers/settings.go
|
||||
- ../sm-sitemap-plugin/controllers/settings/config_form.yaml
|
||||
- ../sm-sitemap-plugin/controllers/settings/_indexnow_status.htm
|
||||
- ../sm-sitemap-plugin/controllers/api/auth.go
|
||||
- ../sm-sitemap-plugin/controllers/api/html.go
|
||||
- ../sm-sitemap-plugin/controllers/api/settings.go
|
||||
- ../sm-sitemap-plugin/controllers/api/indexnow.go
|
||||
- ../sm-sitemap-plugin/jobs.go
|
||||
- ../sm-sitemap-plugin/mcp.go
|
||||
- ../sm-sitemap-plugin/routes.go
|
||||
- ../sm-sitemap-plugin/plugin.go
|
||||
- ../sm-sitemap-plugin/config/config.yaml
|
||||
- ../sm-sitemap-plugin/lang/en/lang.yaml
|
||||
- ../sm-sitemap-plugin/lang/pl/lang.yaml
|
||||
- ../sm-sitemap-plugin/README.md
|
||||
- ../sm-sitemap-plugin/sitemap_extras_test.go
|
||||
- .planning/phases/33-seo-output-audit-and-content/COVERAGE.md
|
||||
autonomous: true
|
||||
requirements: [SC-1, D-31, D-34, D-24, D-10, D-30]
|
||||
|
||||
estimate:
|
||||
tokens: 130000
|
||||
raw_tokens: 130000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "With images_enabled (default on) the index lists sitemap-images-<n>.xml files whose <url> entries carry the page <loc> and one <image:image><image:loc> per featured or body image of that page, at most 1000 images per page, numbered stably like the per-type files (D-31)"
|
||||
- "With news_enabled (default off) the index lists sitemap-news.xml with at most 1000 articles (content Kind article) first published in the last two days, filtered by news_sources (article types and their categories; empty = every article type), each with publication name (news_publication, else app.name), language, publication_date from PublishedAt and title (D-31, RESEARCH Pitfall 9)"
|
||||
- "With indexnow_enabled (default off) the plugin generates a 32-character hex key with crypto/rand on save, serves it at GET /_sitemap/indexnow/<key>.txt (the SEO layer maps the root /<key>.txt), and after each rebuild posts the added, changed and removed URLs (at most 10 000 per request) to https://api.indexnow.org/indexnow through a fetchguard client limited to that host; 403, 422 and 429 answers are recorded and shown in S2, 429 retries through the job's attempts (D-31)"
|
||||
- "Generating a new key (indexnow_new_key on save) makes the old key file answer 404 at once (UI-SPEC Destructive actions)"
|
||||
- "No IndexNow request is ever sent outside the production environment"
|
||||
- "GET /_sitemap/api/v1/html?locale= answers the HTML-sitemap overview (groups in the order pages, offers, services, categories as a tree, posts newest first, tags, authors, other types; each group with its title in the locale, total, the first html_page_size entries and more=true when larger) and GET /_sitemap/api/v1/html/{group}?locale=&page= one page of a group; both list exactly the indexable set of the XML sitemaps (no excluded URL), answer 404 when the HTML sitemap is off, for an unknown group or a page past the last, and carry X-Robots-Tag noindex (D-34, D-24)"
|
||||
- "The settings singleton gains the tabs Images and News, IndexNow (with the S2 indexnow_status partial) and HTML sitemap (html_enabled default on, html_path per locale default /mapa-strony pl and /sitemap en, html_page_size 50 to 500 default 150), with the C26 copy and errors.html_path / errors.page_size refusals (UI-SPEC C26)"
|
||||
- "contract.Listing.Settings answers HTMLEnabled, HTMLPaths, HTMLPageSize and KeyFile, so the SEO plugin and the layer read them without importing sitemap internals (D-95)"
|
||||
- "Every sitemap admin operation is an MCP tool: sitemap_get_settings (GET /_sitemap/api/v1/settings), sitemap_update_settings (PUT) and sitemap_rebuild (POST /_sitemap/api/v1/rebuild), listed only with the sitemap permission (D-10, UI-SPEC MCP parity)"
|
||||
- "S2 shows indexnow.no_key before a key exists and indexnow.never before the first notification, then the key, its URL and the last notification (UI-SPEC empty: S2)"
|
||||
- "S2 shows the indexnow.err_key, err_host or err_rate callout matching the last 403, 422 or 429 answer (UI-SPEC error: IndexNow)"
|
||||
- "The external API this plan integrates (IndexNow) has its capability matrix in COVERAGE.md, every opt-out with a reason"
|
||||
- {statement: "A HTML-sitemap group larger than html_page_size shows its first page plus the sitemap.all link and its group page is paginated (UI-SPEC zero-one-many: large groups; layer rendering in 33-08)", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-31"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "IndexNow never submits a URL whose host differs from the site URL's host, and never sends a request outside production"
|
||||
artifacts:
|
||||
- path: "../sm-sitemap-plugin/classes/indexnow.go"
|
||||
provides: "key generation, ping job body, answer recording"
|
||||
contains: "api.indexnow.org"
|
||||
- path: "../sm-sitemap-plugin/classes/htmlgroups.go"
|
||||
provides: "HTML sitemap groups, order, tree and paging"
|
||||
contains: "func "
|
||||
- path: "../sm-sitemap-plugin/mcp.go"
|
||||
provides: "sitemap MCP tools"
|
||||
contains: "pact.HasMCP"
|
||||
- path: "../sm-sitemap-plugin/sitemap_extras_test.go"
|
||||
provides: "TestImageSitemap, TestNewsSitemap, TestIndexNow, TestHTMLGroups, TestSitemapTools"
|
||||
contains: "func TestIndexNow("
|
||||
- path: ".planning/phases/33-seo-output-audit-and-content/COVERAGE.md"
|
||||
provides: "IndexNow capability matrix"
|
||||
contains: "INTEGRATE"
|
||||
key_links:
|
||||
- from: "../sm-sitemap-plugin/classes/rebuild.go"
|
||||
to: "../sm-sitemap-plugin/classes/indexnow.go"
|
||||
via: "a rebuild's added/changed/removed URLs dispatch the IndexNow job when enabled in production"
|
||||
pattern: "IndexNowArgs"
|
||||
- from: "../sm-sitemap-plugin/classes/indexnow.go"
|
||||
to: "summercms.go/modules/fetchguard"
|
||||
via: "fetchguard.NewClient(Policy{Mode: AllowHostsMode, AllowHosts: [api.indexnow.org]}).PostJSON"
|
||||
pattern: "fetchguard\\.NewClient"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan adds the image and News sitemaps, IndexNow pings, the data API behind the HTML sitemap page, and MCP tools for the sitemap settings.
|
||||
|
||||
<objective>
|
||||
Extend ../sm-sitemap-plugin (after 33-03; main, not pushed):
|
||||
- image sitemap files and the News sitemap from the 33-01 descriptor facts (D-31);
|
||||
- IndexNow: key, key file, ping job from rebuild diffs, S2 status (D-31);
|
||||
- the HTML-sitemap groups API that the layer's page renders (D-34, layer page in 33-08);
|
||||
- the remaining settings tabs, the management API and the MCP tools (D-10);
|
||||
- keeping `COVERAGE.md` (the IndexNow capability matrix written at planning time) in sync with what is built.
|
||||
|
||||
Purpose: SC-1 (image and News sitemaps, IndexNow) and the data side of the HTML sitemap.
|
||||
|
||||
Output: commits in ../sm-sitemap-plugin; a planning-docs commit here only if COVERAGE.md has to change.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-13 (image slots):** `golem15_sitemap_urls.image_file_no` (stable numbering of rows that have images, same rules as file_no) plus `published_at`, `kind` and `parent_refs jsonb` columns (for News and the category tree), filled by the rebuild; migration 202610280004 adds them with the media, News, IndexNow and HTML settings columns: images_enabled bool default true, news_enabled bool default false, news_publication text, news_sources jsonb default '[]', indexnow_enabled bool default false, indexnow_key text, indexnow_last_at timestamptz, indexnow_last_count int, indexnow_last_status int, html_enabled bool default true, html_path (translatable through the translation writer, default value pl /mapa-strony and en /sitemap), html_page_size int default 150.
|
||||
- **P33-14 (IndexNow request):** body `{host, key, urlList}`; no keyLocation (the key file is served at the root, so it covers every URL of the host); endpoint `https://api.indexnow.org/indexnow`; 200 and 202 are success; 400, 403, 422 recorded without retry; 429 makes the job return an error so conga retries (MaxAttempts 5).
|
||||
- **P33-15 (news sources values):** taglist values `type:<type key>` and `category:<type key>:<id>`; a News candidate matches when its type or one of its Parents is listed.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-03-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
From 33-03: contract.Listing / ListingSettings{SiteURL, IndexURL, DefaultLocale, Groups, HTMLEnabled, HTMLPaths, HTMLPageSize, KeyFile}; classes.Rebuild → RebuildResult{Added, Changed, Removed []string}; golem15_sitemap_urls (grp, type_key, record_id, locale, url, title, file_no, first_seen, lastmod, alternates, images, excluded_reason); routes GET /sitemap.xml, GET /_sitemap/files/{file}; settings singleton golem15.sitemap.settings with Files, Content types, Additional addresses tabs.
|
||||
fetchguard: NewClient(Policy{Mode: AllowHostsMode, AllowHosts, Timeout}, cfg) → Client.PostJSON(ctx, url, header, payload) (*Result, error); WithTransport(ctx, rt) routes a test's requests to an httptest handler.
|
||||
Management API analog: ../sm-seo-plugin/controllers/api/auth.go `manage(...)` (cabana.ResolveBackend + cabana.Allows) and mcp.go (pact.MCP tools bound to routes, pier prefixes the plugin id).
|
||||
Specs (cited in 33-RESEARCH.md): image sitemap only image:image + image:loc, ≤1000 per url; News: articles from the last two days, ≤1000 news:news per sitemap; IndexNow key 8–128 [A-Za-z0-9-], ≤10 000 URLs per POST.
|
||||
Copy: UI-SPEC C26 tables (tabs, images, News, IndexNow, S2, HTML sitemap, errors).
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups staged by path in ../sm-sitemap-plugin; COVERAGE.md committed here as planning docs. Every commit keeps vet and `test -short` green.
|
||||
- Resume check: `git -c safe.directory='*' -C ../sm-sitemap-plugin log --format=%s | grep -Fx '<subject>'`; here `git log --format=%s | grep -Fx 'docs(33-04): update the IndexNow coverage matrix'` (only when group C was needed).
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | `feat: image sitemap files (tracer)` | TestImageSitemap passes |
|
||||
| 2 | A `feat: Google News sitemap`; B `feat: IndexNow key, key file and pings`; C (here, only if the matrix changed) `docs(33-04): update the IndexNow coverage matrix` | News and IndexNow tests pass |
|
||||
| 3 | A `feat: HTML sitemap groups API`; B `feat: sitemap management API and MCP tools`; C `docs: images, News, IndexNow, HTML sitemap and MCP in README` | plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "a post's featured and body images appear in sitemap-images-1.xml linked from the index" — one path only</name>
|
||||
<files>../sm-sitemap-plugin/updates/202610280004_add_golem15_sitemap_media_news_indexnow.go, ../sm-sitemap-plugin/updates/registry.go, ../sm-sitemap-plugin/models/url.go, ../sm-sitemap-plugin/models/settings.go, ../sm-sitemap-plugin/classes/images.go, ../sm-sitemap-plugin/classes/rebuild.go, ../sm-sitemap-plugin/classes/slots.go, ../sm-sitemap-plugin/classes/writer.go, ../sm-sitemap-plugin/routes.go, ../sm-sitemap-plugin/sitemap_extras_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-sitemap-plugin/classes/{rebuild,slots,writer}.go and sitemap_index_test.go (33-03)
|
||||
- summercms.go/modules/pact/content.go (ContentLocale.Images, Image)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Code Examples: urlset with images; State of the Art: image tags)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-31 and P33-13: migration 202610280004 adds the P33-13 columns; the rebuild stores each locale row's images (featured Image first, then Images, absolute on the site URL when relative, deduplicated, at most 1000) and kind, published_at, parent_refs; slots.go assigns image_file_no to rows with images (stable, holes kept). writer.go emits the image urlset (namespace http://www.google.com/schemas/sitemap-image/1.1, only image:image and image:loc). The index adds sitemap-images-<n>.xml when images_enabled and the file has rows; the files route serves them. `TestImageSitemap`: a post with a featured image and two body images → sitemap-images-1.xml lists its page with three image:loc; images_enabled false removes the files from the index; a page with 1200 images lists 1000. Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-sitemap-plugin test ./... -run 'TestImageSitemap|TestSitemapIndex' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -10</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or no "--- PASS: TestImageSitemap" line</fails_when>
|
||||
<automated>go -C ../sm-sitemap-plugin vet ./... && go -C ../sm-sitemap-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "sitemap-image/1.1" ../sm-sitemap-plugin/classes/writer.go` prints one line
|
||||
- `grep -n "image_file_no" ../sm-sitemap-plugin/updates/202610280004_add_golem15_sitemap_media_news_indexnow.go` prints one line
|
||||
</acceptance_criteria>
|
||||
<done>Images of every listed page reach Google through the image sitemap files.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Google News sitemap and IndexNow (key, key file, ping job, S2)</name>
|
||||
<files>../sm-sitemap-plugin/classes/news.go, ../sm-sitemap-plugin/classes/indexnow.go, ../sm-sitemap-plugin/classes/rebuild.go, ../sm-sitemap-plugin/classes/writer.go, ../sm-sitemap-plugin/controllers/api/indexnow.go, ../sm-sitemap-plugin/controllers/settings.go, ../sm-sitemap-plugin/controllers/settings/config_form.yaml, ../sm-sitemap-plugin/controllers/settings/_indexnow_status.htm, ../sm-sitemap-plugin/models/settings/fields.yaml, ../sm-sitemap-plugin/jobs.go, ../sm-sitemap-plugin/routes.go, ../sm-sitemap-plugin/config/config.yaml, ../sm-sitemap-plugin/lang/en/lang.yaml, ../sm-sitemap-plugin/lang/pl/lang.yaml, ../sm-sitemap-plugin/sitemap_extras_test.go, .planning/phases/33-seo-output-audit-and-content/COVERAGE.md</files>
|
||||
<read_first>
|
||||
- summercms.go/modules/fetchguard/README.md (Client, PostJSON, WithTransport, AllowHostsMode)
|
||||
- ../sm-seo-plugin/classes/robots.go (how Staging()/non-production is detected) and classes/service.go Staging()
|
||||
- ../sm-sitemap-plugin/controllers/settings/_sitemap_files.htm (partial style from 33-03)
|
||||
- .planning/phases/33-seo-output-audit-and-content/COVERAGE.md (the matrix this task implements)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C26 Images and News, IndexNow tabs, S2 copy)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- TestNewsSitemap: articles published 1 hour and 47 hours ago are listed, one published 49 hours ago is not; a non-article type is never listed; news_sources [category:journal-category:3] keeps only articles with that parent; more than 1000 candidates list the newest 1000; news_enabled false: no sitemap-news.xml in the index and the file answers 404
|
||||
- TestIndexNow (fake transport): enabling and saving generates a 32-hex key; GET /_sitemap/indexnow/<key>.txt answers the key as text/plain; another name answers 404; after a rebuild with one new and one removed URL the job posts {host, key, urlList[2]} to api.indexnow.org; 202 recorded as last status; 403 and 422 recorded without retry; 429 makes the job fail so it retries; indexnow_new_key replaces the key and the old file answers 404; with the app environment not production no request is sent; a URL of another host is never in urlList
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-31, P33-14 and P33-15: `classes/news.go` builds the News urlset (namespace http://www.google.com/schemas/sitemap-news/0.9) from rows with kind article and published_at in the last 48 hours, newest first, limit 1000, publication name news_publication else config app.name, language = the row's locale. `classes/indexnow.go`: `GenerateKey()` (crypto/rand, hex, 32 characters), `IndexNowArgs` (kind golem15.sitemap.indexnow, URLs) dispatched by the rebuild after commit when enabled, in production and the diff is non-empty (chunks of 10 000), the job posting through a fetchguard client (AllowHostsMode, AllowHosts [api.indexnow.org], Timeout 10 s) and recording indexnow_last_at, _count, _status. `controllers/api/indexnow.go` serves the key file (`GET /_sitemap/indexnow/{file}` with Where `[A-Za-z0-9-]{8,128}\.txt`). Settings tabs Images and News (images_enabled, news_enabled, news_publication and news_sources hidden by trigger while news_enabled is unchecked; news_sources taglist mode array, customTags false, options from article types and their categories) and IndexNow (indexnow_enabled, partial S2 `_indexnow_status.htm`, indexnow_new_key checkbox hidden while disabled; the form's save generates the key). Config keys documented: `indexnow_endpoint` is not configurable (fixed host). COVERAGE.md was written at planning time (IndexNow capability matrix); keep it in sync: when the implementation drops, adds or changes a capability, update its row (every OPT-OUT keeps a reason) and commit it here as group C, otherwise there is no group C. Tests first. Commit groups A and B (plugin), C only if COVERAGE.md changed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-sitemap-plugin test ./... -run 'TestNewsSitemap|TestIndexNow' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -20</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestNewsSitemap or TestIndexNow missing from the "--- PASS" lines</fails_when>
|
||||
<automated>grep -c "| OPT-OUT |" .planning/phases/33-seo-output-audit-and-content/COVERAGE.md</automated>
|
||||
<fails_when>output is 0, or the command exits non-zero because the file is missing</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "crypto/rand" ../sm-sitemap-plugin/classes/indexnow.go` prints one line
|
||||
- `grep -n "AllowHostsMode" ../sm-sitemap-plugin/classes/indexnow.go` prints one line
|
||||
- `grep -n "sitemap-news/0.9" ../sm-sitemap-plugin/classes/news.go` prints one line
|
||||
- every OPT-OUT row in COVERAGE.md has a non-empty reason column
|
||||
</acceptance_criteria>
|
||||
<done>News and IndexNow work behind their switches, never outside production, and the integration's coverage is on record.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: HTML-sitemap groups API, the HTML sitemap tab, Listing fields, management API and MCP tools</name>
|
||||
<files>../sm-sitemap-plugin/classes/htmlgroups.go, ../sm-sitemap-plugin/classes/listing.go, ../sm-sitemap-plugin/controllers/api/auth.go, ../sm-sitemap-plugin/controllers/api/html.go, ../sm-sitemap-plugin/controllers/api/settings.go, ../sm-sitemap-plugin/models/settings/fields.yaml, ../sm-sitemap-plugin/mcp.go, ../sm-sitemap-plugin/routes.go, ../sm-sitemap-plugin/plugin.go, ../sm-sitemap-plugin/lang/en/lang.yaml, ../sm-sitemap-plugin/lang/pl/lang.yaml, ../sm-sitemap-plugin/README.md, ../sm-sitemap-plugin/sitemap_extras_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/controllers/api/auth.go (manage wrapper), mcp.go, mcp_test.go
|
||||
- ../sm-seo-plugin/routes.go:79-85 (noindex wrapper) and Buckets()
|
||||
- ../sm-sitemap-plugin/classes/listing.go (33-03)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (L3 group order and markup data, C26 HTML sitemap tab, MCP parity)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- TestHTMLGroups: overview for pl lists groups in the L3 order with titles from type_<key>_title in pl, categories nested by parent, posts newest first, others alphabetical; a group with 160 entries at page size 150 shows 150 and more=true; GET /html/posts?page=2 answers the rest with pages=2; page 3 → 404; unknown group → 404; html_enabled false → 404 for both; excluded URLs never appear; answers carry X-Robots-Tag noindex
|
||||
- Listing.Settings answers HTMLEnabled, HTMLPaths {pl:/mapa-strony, en:/sitemap}, HTMLPageSize and KeyFile (<key>.txt when IndexNow is on)
|
||||
- TestSitemapTools: GET/PUT /_sitemap/api/v1/settings and POST /_sitemap/api/v1/rebuild need a backend principal with the sitemap permission (401/403 otherwise); PUT validates like the form; the MCP catalog lists get_settings, update_settings and rebuild bound to those routes
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-34, D-10 and UI-SPEC L3/C26: `classes/htmlgroups.go` builds the overview and group pages from the slot table (included rows only, locale filter, L3 order, category tree from parent_refs, paging by html_page_size); `controllers/api/html.go` serves `GET /_sitemap/api/v1/html` and `GET /_sitemap/api/v1/html/{group}` (public, noindex header, throttle bucket `sitemap-html` 300/min per client IP behind trusted proxies). HTML sitemap tab fields (html_enabled switch, html_path mltext with the defaults, html_page_size number) and errors.html_path / errors.page_size validation. listing.go fills the HTML and KeyFile fields. Management API (`controllers/api/auth.go` manage wrapper modeled on the SEO plugin's; `controllers/api/settings.go` show/update; rebuild dispatch) under `/_sitemap/api/v1` with bucket `sitemap-api`; `mcp.go` declares get_settings, update_settings, rebuild (pact.HasMCP, guard backend, the plugin's existing permission). README documents every route, setting, config key and tool. Tests first. Commit groups A, B, C.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-sitemap-plugin test ./... -run 'TestHTMLGroups|TestSitemapTools|TestImageSitemap|TestNewsSitemap|TestIndexNow' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -20</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestHTMLGroups or TestSitemapTools missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-sitemap-plugin vet ./... && go -C ../sm-sitemap-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "/_sitemap/api/v1/html" ../sm-sitemap-plugin/routes.go ../sm-sitemap-plugin/README.md` prints a line in each
|
||||
- `grep -n '"get_settings"\|"update_settings"\|"rebuild"' ../sm-sitemap-plugin/mcp.go` prints three lines
|
||||
- `grep -n "X-Robots-Tag" ../sm-sitemap-plugin/controllers/api/html.go ../sm-sitemap-plugin/routes.go` prints at least one line
|
||||
</acceptance_criteria>
|
||||
<done>The HTML sitemap has its data API, the sitemap settings are complete and every sitemap operation is reachable through MCP.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| sitemap job → api.indexnow.org | outbound HTTP from the server |
|
||||
| visitors → HTML-sitemap API | anonymous reads |
|
||||
| admin/MCP → management API | authenticated writes |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-13 | Elevation of privilege (SSRF) | IndexNow ping | high | mitigate | fetchguard AllowHostsMode with the single host api.indexnow.org, HTTPS only, no redirects followed; URL list filtered to the site host (TestIndexNow) |
|
||||
| T-33-14 | Information disclosure | IndexNow key | low | accept | the key is public by design (served at the root); rotation through indexnow_new_key |
|
||||
| T-33-15 | Spoofing | staging pings | medium | mitigate | no request outside production (TestIndexNow non-production case) |
|
||||
| T-33-16 | Denial of service | HTML-sitemap API | medium | mitigate | table reads with paging capped at html_page_size ≤500, per-IP bucket sitemap-html |
|
||||
| T-33-17 | Elevation of privilege | management API and MCP | high | mitigate | cabana.ResolveBackend + permission check on every route, 401/403 tests in TestSitemapTools |
|
||||
| T-33-SC | Tampering | npm/pip/cargo installs | high | accept | no new package (fetchguard and crypto/rand are framework/stdlib) |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `go -C ../sm-sitemap-plugin vet ./... && go -C ../sm-sitemap-plugin test -short ./...` after every commit.
|
||||
- Docker suite: TestImageSitemap, TestNewsSitemap, TestIndexNow, TestHTMLGroups, TestSitemapTools, plus the 33-03 suite.
|
||||
- COVERAGE.md has no OPT-OUT row without a reason.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Image and News sitemaps and IndexNow work behind their switches.
|
||||
- The HTML-sitemap API answers exactly the indexable set.
|
||||
- Sitemap settings are manageable through MCP.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Columns: `golem15_sitemap_urls.image_file_no`, `published_at`, `kind`, `parent_refs`; settings `images_enabled`, `news_enabled`, `news_publication`, `news_sources`, `indexnow_enabled`, `indexnow_key`, `indexnow_last_at`, `indexnow_last_count`, `indexnow_last_status`, `html_enabled`, `html_path`, `html_page_size`; migration 202610280004.
|
||||
- Go symbols: `classes.GenerateKey`, `IndexNowArgs` (kind `golem15.sitemap.indexnow`), the News and image writers, HTML group builder, API handlers for html, settings, rebuild and the key file.
|
||||
- Routes: `GET /_sitemap/indexnow/{file}`, `GET /_sitemap/api/v1/html`, `GET /_sitemap/api/v1/html/{group}`, `GET /_sitemap/api/v1/settings`, `PUT /_sitemap/api/v1/settings`, `POST /_sitemap/api/v1/rebuild`; files `sitemap-images-<n>.xml`, `sitemap-news.xml`.
|
||||
- Throttle buckets: `sitemap-html`, `sitemap-api`.
|
||||
- MCP tools: `sitemap_get_settings`, `sitemap_update_settings`, `sitemap_rebuild`.
|
||||
- Partial: `indexnow_status` (S2).
|
||||
- Files: `classes/images.go`, `classes/news.go`, `classes/indexnow.go`, `classes/htmlgroups.go`, `controllers/api/{auth,html,settings,indexnow}.go`, `mcp.go`, `sitemap_extras_test.go`, `.planning/phases/33-seo-output-audit-and-content/COVERAGE.md` (written at planning time, kept in sync here).
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-04-SUMMARY.md` when done.
|
||||
</output>
|
||||
341
.planning/phases/33-seo-output-audit-and-content/33-05-PLAN.md
Normal file
341
.planning/phases/33-seo-output-audit-and-content/33-05-PLAN.md
Normal file
@@ -0,0 +1,341 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 05
|
||||
type: execute
|
||||
wave: 4
|
||||
depends_on: ["33-04"]
|
||||
files_modified:
|
||||
- ../sm-seo-plugin/go.mod
|
||||
- ../sm-seo-plugin/go.sum
|
||||
- ../sm-seo-plugin/go.work
|
||||
- ../sm-seo-plugin/plugin.go
|
||||
- ../sm-seo-plugin/menu_item_types.go
|
||||
- ../sm-seo-plugin/classes/sitemap_filter.go
|
||||
- ../sm-seo-plugin/classes/registry.go
|
||||
- ../sm-seo-plugin/classes/site.go
|
||||
- ../sm-seo-plugin/classes/llms.go
|
||||
- ../sm-seo-plugin/classes/history.go
|
||||
- ../sm-seo-plugin/classes/batch.go
|
||||
- ../sm-seo-plugin/classes/issues.go
|
||||
- ../sm-seo-plugin/classes/robots.go
|
||||
- ../sm-seo-plugin/classes/resolver.go
|
||||
- ../sm-seo-plugin/classes/settings_write.go
|
||||
- ../sm-seo-plugin/classes/partials.go
|
||||
- ../sm-seo-plugin/models/page.go
|
||||
- ../sm-seo-plugin/models/page/columns.yaml
|
||||
- ../sm-seo-plugin/models/page/fields.yaml
|
||||
- ../sm-seo-plugin/models/settings.go
|
||||
- ../sm-seo-plugin/models/settings/fields.yaml
|
||||
- ../sm-seo-plugin/models/robots.go
|
||||
- ../sm-seo-plugin/models/registry.go
|
||||
- ../sm-seo-plugin/updates/202610280002_create_golem15_seo_pages.go
|
||||
- ../sm-seo-plugin/updates/202610280003_add_golem15_seo_links_and_llms.go
|
||||
- ../sm-seo-plugin/updates/registry.go
|
||||
- ../sm-seo-plugin/extensions_robots.go
|
||||
- ../sm-seo-plugin/extension/_seo_status.htm
|
||||
- ../sm-seo-plugin/controllers/admin_registry.go
|
||||
- ../sm-seo-plugin/controllers/pages.go
|
||||
- ../sm-seo-plugin/controllers/pages/config_list.yaml
|
||||
- ../sm-seo-plugin/controllers/pages/config_form.yaml
|
||||
- ../sm-seo-plugin/controllers/pages/config_filter.yaml
|
||||
- ../sm-seo-plugin/controllers/pages/_page_status.htm
|
||||
- ../sm-seo-plugin/controllers/api/registry.go
|
||||
- ../sm-seo-plugin/controllers/api/site.go
|
||||
- ../sm-seo-plugin/controllers/api/llms.go
|
||||
- ../sm-seo-plugin/admin_navigation.go
|
||||
- ../sm-seo-plugin/routes.go
|
||||
- ../sm-seo-plugin/mcp.go
|
||||
- ../sm-seo-plugin/operations.go
|
||||
- ../sm-seo-plugin/config/config.yaml
|
||||
- ../sm-seo-plugin/lang/en/lang.yaml
|
||||
- ../sm-seo-plugin/lang/pl/lang.yaml
|
||||
- ../sm-seo-plugin/README.md
|
||||
- ../sm-seo-plugin/fixture_test.go
|
||||
- ../sm-seo-plugin/sitemap_filter_test.go
|
||||
- ../sm-seo-plugin/registry_test.go
|
||||
autonomous: true
|
||||
requirements: [SC-1, SC-3, D-95, D-24, D-33, D-12, D-22, D-25, D-83, D-94, D-10]
|
||||
|
||||
estimate:
|
||||
tokens: 160000
|
||||
raw_tokens: 160000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "sm-seo-plugin publishes a contract.Filter (sm-sitemap-plugin/contract) and requires golem15.sitemap: a URL whose effective SEO is noindex, whose canonical points elsewhere or that redirects leaves the XML and HTML sitemaps with the reason noindex, canonical or redirect; the non-production lock never excludes a URL, so staging and production list the same set (D-95, D-24)"
|
||||
- "The page registry (SEO › Pages, controller golem15.seo.pages) holds frontend pages with an address per locale, a kind (page, offer, service, landing), a name, a parent, a content-changed date and a note; it is the signpost content type seo-page, so each page gets the SEO tab, resolves ok, and is listed in the sitemaps grouped by kind into sitemap-pages, sitemap-offers, sitemap-services and sitemap-landing-pages files (D-33, D-30)"
|
||||
- "The frontend server reports its static routes with POST /_seo/api/v1/registry/routes (bearer golem15.seo.route_report_token, else notfound_token): unknown paths are inserted with origin reported and kind page, known ones get reported_at, nothing is ever deleted or overwritten, and a reported page missing from a newer report shows the Not on the site badge and the P9 warning (D-33, UI-SPEC C21)"
|
||||
- "A registry address that another content type owns refuses with pages.url_owned; a duplicate, an invalid address, a missing default-locale address and a parent loop refuse with their C21 copy (UI-SPEC C21, error: save refused)"
|
||||
- "GET /_seo/api/v1/site answers the site facts the layer needs: site_url, default_locale, locales, unprefixed_locale, links.new_tab, html_sitemap {enabled, paths, page_size}, routes [{type, pattern}] for the drift check, root_files (verification file names and the IndexNow key file) and llms (D-97 support, D-20c, D-103)"
|
||||
- "With llms_enabled (robots.txt screen, AI bots tab, default off) GET /llms.txt serves the site's indexable pages from the sitemaps grouped like the HTML sitemap, headed by llms_intro or the default meta description; off, it answers 404 (D-25, UI-SPEC C25)"
|
||||
- "robots.txt Sitemap: lines name the sitemap index from the sitemap plugin's Listing (/sitemap.xml) unless golem15.seo.robots_sitemaps overrides them; per-type files are never listed (D-22)"
|
||||
- "The SEO settings get a Links tab with links_new_tab (switch, default on), nofollow_domains and sponsored_domains (one domain per line, subdomains included, settings.domain_invalid on a bad line); all three are MCP-writable through seo_update_settings and reach the resolve answer as outbound {new_tab, nofollow_domains, sponsored_domains} (2026-10-28 layer options: links_new_tab; D-83)"
|
||||
- "The batch conflict noindex_published fires only when the URL is currently listed in a sitemap file (read through contract.Listing), and a CMS issue sitemap_blocked (Error, tool seo_update_robots) reports sitemap URLs that the production robots.txt blocks for Googlebot (D-12, D-24)"
|
||||
- "Every SEO write (admin, MCP, batch, import, undo) purges the rendered-site cache after commit through the framework's site-cache purge, so the layer's cached resolve answers and pages refresh (33-CONTEXT Claude's discretion: purge with D-97)"
|
||||
- "Pages tools seo_list_pages, seo_create_page, seo_update_page and seo_delete_page exist and TestEveryAdminOperationHasTool maps every Pages operation (D-10)"
|
||||
- "SEO › Pages sits between URL rules and robots.txt in the side menu with the icon files, behind golem15.seo.manage (UI-SPEC C15)"
|
||||
- "The Pages list shows pages.list_empty when empty (UI-SPEC empty: Pages list)"
|
||||
- "The SEO tab's P1 shows status.excluded_title with the matching status.excluded_noindex, _canonical, _redirect or _type text when the page is left out of the sitemaps (UI-SPEC partial: page excluded)"
|
||||
- "A reported page missing from the newest report keeps its data, shows the negative badge pages.state_missing and the P9 warning pages.status_missing, and is never deleted automatically (UI-SPEC partial: registry page missing)"
|
||||
- {statement: "Two route reports in a row with the same list change only reported_at; a report from a server with a stale build never removes an editor's title, kind or SEO values", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-33"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "The route report never deletes a registry page and never overwrites a value an editor set"
|
||||
- requirement_id: "D-95"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: judgment
|
||||
statement: "The SEO plugin reads sitemap data only through the published contract package; the sitemap plugin keeps working without SEO"
|
||||
artifacts:
|
||||
- path: "../sm-seo-plugin/classes/sitemap_filter.go"
|
||||
provides: "contract.Filter implementation on the resolver"
|
||||
contains: "Decide("
|
||||
- path: "../sm-seo-plugin/classes/registry.go"
|
||||
provides: "page registry service, signpost descriptor, route report"
|
||||
contains: "func "
|
||||
- path: "../sm-seo-plugin/controllers/api/site.go"
|
||||
provides: "GET /_seo/api/v1/site"
|
||||
contains: "func "
|
||||
- path: "../sm-seo-plugin/sitemap_filter_test.go"
|
||||
provides: "TestSitemapFilterTracer, TestFilterReasons, TestSitemapBlockedIssue, TestNoindexPublishedConflict"
|
||||
contains: "func TestSitemapFilterTracer("
|
||||
- path: "../sm-seo-plugin/registry_test.go"
|
||||
provides: "TestRegistry, TestRouteReport, TestSiteEndpoint, TestLLMSTxt, TestPurgeAfterWrite"
|
||||
contains: "func TestRegistry("
|
||||
key_links:
|
||||
- from: "../sm-seo-plugin/plugin.go"
|
||||
to: "../sm-sitemap-plugin/contract/contract.go"
|
||||
via: "Register publishes the Filter with app.Publish[contract.Filter]; Requires includes golem15.sitemap"
|
||||
pattern: "contract\\.Filter"
|
||||
- from: "../sm-seo-plugin/classes/history.go"
|
||||
to: "summercms.go/modules/cooler/sitecache.go"
|
||||
via: "each recorded write schedules the site-cache purge after commit"
|
||||
pattern: "Purge"
|
||||
- from: "../sm-seo-plugin/menu_item_types.go"
|
||||
to: "../sm-seo-plugin/classes/registry.go"
|
||||
via: "the seo-page MenuItemType's Content descriptor (Records, Describe, Match) reads the registry"
|
||||
pattern: "seo-page"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan connects the SEO plugin to the new sitemaps and gives the frontend layer its site-level facts: the sitemap filter, the page registry with the route report, the site endpoint, llms.txt, the Sitemap: line, the Links settings (new tab, nofollow and sponsored domains) and cache purging after SEO writes.
|
||||
|
||||
<objective>
|
||||
Extend ../sm-seo-plugin (main, not pushed):
|
||||
- implement and publish `contract.Filter` (D-95, D-24) and require golem15.sitemap;
|
||||
- the page registry: model, admin screen (C21), signpost type, route report endpoint, MCP tools (D-33, D-10);
|
||||
- `GET /_seo/api/v1/site`, `GET /llms.txt` (D-25), robots `Sitemap:` from the index (D-22);
|
||||
- the Links tab (`links_new_tab`, nofollow and sponsored domains) and `outbound` in the resolve answer (2026-10-28 layer options, D-83);
|
||||
- the refined batch conflict and the `sitemap_blocked` CMS issue (D-12, D-24);
|
||||
- site-cache purge after every SEO write.
|
||||
|
||||
Purpose: SC-1 (sitemaps consistent with noindex and robots.txt), D-33, and the contract the layer (33-07/33-08) builds on.
|
||||
|
||||
Output: commits in ../sm-seo-plugin. This plan runs after 33-04 (not beside it) because its tests mount the sibling sm-sitemap-plugin checkout through go.work, which 33-04 edits; a concurrent edit there would break this plan's builds. go.mod requires `git.golem15.com/golem15/sm-sitemap-plugin` at its existing tag with the sibling replaced in go.work; 33-14 bumps the require to the new sitemap tag.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-16 (resolve answer, additive, `costly`):** `Result.Outbound *Outbound` with JSON `outbound: {new_tab: bool, nofollow_domains: [string], sponsored_domains: [string]}`, present on ok answers. No existing key changes. 33-06 and 33-11 add further keys; the layer treats absent keys as empty.
|
||||
- **P33-17 (site answer, `costly`):** `GET /_seo/api/v1/site` (public group, noindex, bucket seo-resolve) answers `{site_url, default_locale, locales: [..], unprefixed_locale, links: {new_tab}, html_sitemap: {enabled, paths: {locale: path}, page_size}, routes: [{type, pattern}], root_files: [..], llms: bool}`; 33-06 adds `pagination` and `home_crumb`.
|
||||
- **P33-18 (registry table):** `golem15_seo_pages` (id, url text unique (default-locale path; other locales through the translation writer), title, kind page|offer|service|landing, origin manual|reported|mcp, parent_id, content_updated_at date, reported_at timestamptz, note, timestamps); settings column `routes_reported_at`. Groups: Filter.Groups answers pages, offers, services, landing-pages with titles from `pages.kind_*` per locale; Decide sets Group from the page kind.
|
||||
- **P33-19 (purge):** the purge is scheduled where history records a write (classes/history.go), so every write path that records history purges once per transaction (kind `seo`, slug = the URL or `*` for settings).
|
||||
- **P33-20 (route report token):** config `golem15.seo.route_report_token` (empty uses `notfound_token`; both empty → 404), constant-time comparison, body `{routes: [path...]}` of at most 2000 paths of at most 2048 bytes each.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-03-SUMMARY.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-04-SUMMARY.md
|
||||
@.planning/phases/32-seo-foundation/32-05-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
From 33-03: package git.golem15.com/golem15/sm-sitemap-plugin/contract — Filter{Decide(ctx, []Candidate) ([]Decision, error); Groups(ctx) ([]Group, error)}; Candidate{TypeKey, RecordID, Locale, URL}; Decision{Exclude, Reason, Group, LastMod}; Group{Key, Titles}; reasons noindex/canonical/redirect/type; Listing{Settings(ctx) (ListingSettings, error); Entries(ctx, EntriesQuery) (EntriesPage, error)}; ListingSettings{SiteURL, IndexURL, DefaultLocale, Groups, HTMLEnabled, HTMLPaths, HTMLPageSize, KeyFile}.
|
||||
sm-seo-plugin (Phase 32): classes.Service (NewService(app), SiteURL, Staging, DefaultLocale), Resolver.Resolve(ctx, rawURL) (Result{Action, Status, Location, URL, Locale, Staging, SEO, Sources, TypeKey, RecordID}) and ResolveRecord; classes/settings_write.go (allowed columns, SettingsValues, SetSettingsValue: four places per new column); classes/history.go (Record, WithVia); classes/batch.go (conflict kinds incl. noindex_published); classes/issues.go (Issue{Kind, URL, Locale, Details, Tool}, toolSetURLSEO = "seo_set_url_seo"); classes/robots.go (served body, robots_sitemaps); extensions_robots.go (fields on the robots singleton); controllers/redirects.go + config_*.yaml (list/form pattern); controllers/api/notfound.go (bearer token pattern); mcp.go (tools), operations.go (AdminOperations), operations_test.go (TestEveryAdminOperationHasTool, TestMCPReadToolsAreGET); routes.go (public group with noindex(), management group with BucketAPI); fixture_test.go (fake content plugin acme.pages, fake TranslationWriter); testmain_test.go (Docker Postgres).
|
||||
cooler: SiteCachePurger (Purge(ctx, kind, slug)) and the after-commit purge helper in modules/cooler/sitecache.go (read the file for the exact name).
|
||||
Copy: UI-SPEC C15, C20 Links tab, C21, C25 and their copy tables.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups staged by path in ../sm-seo-plugin; vet and `test -short` green at every commit; lang keys in both files per group; `assets/dist` untouched (no element in this plan).
|
||||
- Resume check: `git -c safe.directory='*' -C ../sm-seo-plugin log --format=%s | grep -Fx '<subject>'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | `feat: sitemap filter excludes noindex, canonicalised and redirected URLs (tracer)` | TestSitemapFilterTracer passes |
|
||||
| 2 | A `feat: page registry with its admin screen and signpost type`; B `feat: route report endpoint`; C `feat: MCP tools for registry pages` | registry tests and the operations parity pass |
|
||||
| 3 | A `feat: site endpoint, llms.txt and the sitemap index in robots.txt`; B `feat: links settings and outbound rules in resolve`; C `feat: sitemap-aware batch conflict and the sitemap_blocked issue`; D `feat: purge the site cache after SEO writes`; E `docs: registry, site endpoint, llms.txt and links in README` | plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "an editor sets a page to noindex and it leaves the XML sitemap with reason noindex" — one path only</name>
|
||||
<files>../sm-seo-plugin/go.mod, ../sm-seo-plugin/go.sum, ../sm-seo-plugin/go.work, ../sm-seo-plugin/plugin.go, ../sm-seo-plugin/classes/sitemap_filter.go, ../sm-seo-plugin/fixture_test.go, ../sm-seo-plugin/sitemap_filter_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-sitemap-plugin/contract/contract.go and classes/rebuild.go (33-03)
|
||||
- ../sm-seo-plugin/plugin.go, classes/resolver.go (ResolveRecord), fixture_test.go, testmain_test.go
|
||||
- summercms.go/modules/backpack/services.go (Publish keyed by the type argument; duplicate is an error)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pattern 3)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-95, D-24 and P33-18: add the require of git.golem15.com/golem15/sm-sitemap-plugin (its current tag) and `replace git.golem15.com/golem15/sm-sitemap-plugin => ../sm-sitemap-plugin` in go.work; plugin.go adds "golem15.sitemap" to Requires and publishes `classes.SitemapFilter` with `app.Publish[contract.Filter]` in Register. `classes/sitemap_filter.go`: Decide resolves each candidate's record (ResolveRecord by type, id, locale; batched through one DB handle) ignoring the non-production lock: robots noindex → Exclude noindex; canonical whose path differs from the candidate's → Exclude canonical; a redirect source → Exclude redirect; else include. Groups answers nothing yet (Task 2 adds the registry kinds). The test fixture app mounts the sitemap plugin (import of its package in the test) next to the fake content plugin. `TestSitemapFilterTracer` (Docker): two published fake pages; set the first to noindex through the SEO tab admin save; run the sitemap rebuild; the sitemap file lists only the second; the excluded row's reason is noindex; the same holds with the app environment set to staging. Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestSitemapFilterTracer' -count=1 -v 2>&1 | tail -20</automated>
|
||||
<fails_when>non-zero exit, "FAIL" or "no tests to run" in the output, or no "--- PASS: TestSitemapFilterTracer" line</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "golem15.sitemap" ../sm-seo-plugin/plugin.go` prints at least one line
|
||||
- `grep -n "sm-sitemap-plugin/contract" ../sm-seo-plugin/classes/sitemap_filter.go ../sm-seo-plugin/plugin.go` prints a line in each
|
||||
- `grep -n "sm-sitemap-plugin =>" ../sm-seo-plugin/go.work` prints one line
|
||||
</acceptance_criteria>
|
||||
<done>The SEO plugin decides what the sitemap lists, and a noindex page leaves the sitemap.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Page registry (model, admin screen, signpost type seo-page, sitemap groups), route report endpoint and Pages MCP tools</name>
|
||||
<files>../sm-seo-plugin/models/page.go, ../sm-seo-plugin/models/page/columns.yaml, ../sm-seo-plugin/models/page/fields.yaml, ../sm-seo-plugin/models/registry.go, ../sm-seo-plugin/updates/202610280002_create_golem15_seo_pages.go, ../sm-seo-plugin/updates/registry.go, ../sm-seo-plugin/classes/registry.go, ../sm-seo-plugin/classes/sitemap_filter.go, ../sm-seo-plugin/menu_item_types.go, ../sm-seo-plugin/controllers/admin_registry.go, ../sm-seo-plugin/controllers/pages.go, ../sm-seo-plugin/controllers/pages/config_list.yaml, ../sm-seo-plugin/controllers/pages/config_form.yaml, ../sm-seo-plugin/controllers/pages/config_filter.yaml, ../sm-seo-plugin/controllers/pages/_page_status.htm, ../sm-seo-plugin/controllers/api/registry.go, ../sm-seo-plugin/admin_navigation.go, ../sm-seo-plugin/routes.go, ../sm-seo-plugin/mcp.go, ../sm-seo-plugin/operations.go, ../sm-seo-plugin/config/config.yaml, ../sm-seo-plugin/lang/en/lang.yaml, ../sm-seo-plugin/lang/pl/lang.yaml, ../sm-seo-plugin/registry_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/controllers/redirects.go, controllers/redirects/config_{list,form,filter}.yaml, models/redirect.go and models/redirect/{columns,fields}.yaml
|
||||
- ../sm-seo-plugin/controllers/api/notfound.go (token check) and controllers/api/redirects.go (management CRUD)
|
||||
- ../sm-seo-plugin/classes/owner.go (FindOwner via MatchPath) and classes/rules.go
|
||||
- ../sm-journal-plugin/classes/menu_item_types.go (a MenuItemType with a Content descriptor)
|
||||
- ../sm-seo-plugin/operations.go and operations_test.go
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C15, C21, Pages copy table, Destructive actions)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- Create /kontakt (kind page, title Kontakt) → it resolves ok with the SEO tab values; it is a seo-page record in signpost; the sitemap lists it in sitemap-pages-1.xml; a kind offer page lands in sitemap-offers-1.xml
|
||||
- A page with en address /contact and pl /kontakt has two locale URLs and hreflang alternates; an empty en address means no en URL (UI-SPEC Q-15)
|
||||
- Address /blog/lwia-grzywa owned by a fake record → 422 pages.url_owned naming the type and title; duplicate → pages.url_taken; "kontakt" → pages.url_invalid; empty default-locale address → pages.url_required; parent loop → pages.parent_loop
|
||||
- Route report with the right token and ["/", "/kontakt", "/o-nas"] inserts /o-nas (origin reported, kind page, title derived from the last segment) and updates reported_at of the others; a later report without /o-nas marks it missing (badge, P9 warning) and deletes nothing; wrong token 401; no token configured 404; 2001 paths 422; a path owned by a content type is skipped
|
||||
- Deleting a page deletes its SEO entries (the existing RecordDeleted cleanup) and it leaves the sitemaps on the next rebuild
|
||||
- Filter.Groups answers pages, offers, services, landing-pages with the kind titles per locale; Decide groups registry candidates by kind
|
||||
- MCP lists list_pages, create_page, update_page, delete_page; TestEveryAdminOperationHasTool passes with the Pages controller
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-33, D-10, UI-SPEC C21 and P33-18/P33-20: migration 202610280002 creates golem15_seo_pages and the settings column routes_reported_at; models/page.go with url and title translatable through the translation writer (as the SEO settings' ml fields are), Rules and the C21 validation (FormBeforeCreate/Update hook in the controller translating :type/:title params, the Phase 32 pattern); `classes/registry.go`: CRUD service with history, `ReportRoutes(ctx, paths) (ReportResult, error)`, and the descriptor functions; `menu_item_types.go` registers MenuItemType `seo-page` (label pages.name, Content{Controller golem15.seo.pages, Model page morph, Kind page, Records, Describe (per-locale URLs, Title, LastMod content_updated_at, Parents [seo-page parent], Published true), Match exact}). Pages screen: config_list.yaml (title pages.list_title, recordUrl update, 20 per page, checkboxes, setup, toolbar [create, delete], noRecordsMessage pages.list_empty, defaultSort url asc, row state negative pages.state_missing for reported pages with reported_at before routes_reported_at), columns and filters per C21, form per C21 with P9 `_page_status.htm` (pages.status_reported plain or pages.status_missing warning, nothing for manual pages); navigation item Pages (icon files) after URL rules, permission golem15.seo.manage. `controllers/api/registry.go`: `POST /_seo/api/v1/registry/routes` (public group, bucket seo-notfound, P33-20 token) and the management CRUD `GET/POST /_seo/api/v1/pages`, `PUT/DELETE /_seo/api/v1/pages/{id}`; MCP tools list_pages, create_page, update_page, delete_page (destructive) and the AdminOperations rows for controller golem15.seo.pages. Config key `route_report_token` documented in config/config.yaml. Every C21 copy key in both lang files. Tests first in registry_test.go (`TestRegistry`, `TestRouteReport`). Commit groups A, B, C.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestRegistry|TestRouteReport|TestEveryAdminOperationHasTool|TestMCPReadToolsAreGET|TestSitemapFilterTracer' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -20</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestRegistry, TestRouteReport or TestEveryAdminOperationHasTool missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n '"seo-page"' ../sm-seo-plugin/menu_item_types.go ../sm-seo-plugin/classes/registry.go` prints at least one line
|
||||
- `grep -n "/registry/routes" ../sm-seo-plugin/routes.go` prints one line and `grep -n "subtle.ConstantTimeCompare" ../sm-seo-plugin/controllers/api/registry.go` prints one line
|
||||
- `grep -n '"list_pages"\|"create_page"\|"update_page"\|"delete_page"' ../sm-seo-plugin/mcp.go` prints four lines
|
||||
- TestRouteReport asserts that a later report deletes nothing and keeps editor-set titles
|
||||
</acceptance_criteria>
|
||||
<done>Frontend pages live in a CMS registry with the SEO tab, sitemap groups by kind, a safe route report and MCP tools.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Site endpoint, llms.txt, robots Sitemap: from the index, Links settings with outbound rules in resolve, sitemap-aware conflict and issue, purge after writes</name>
|
||||
<files>../sm-seo-plugin/classes/site.go, ../sm-seo-plugin/classes/llms.go, ../sm-seo-plugin/classes/robots.go, ../sm-seo-plugin/classes/resolver.go, ../sm-seo-plugin/classes/settings_write.go, ../sm-seo-plugin/classes/batch.go, ../sm-seo-plugin/classes/issues.go, ../sm-seo-plugin/classes/history.go, ../sm-seo-plugin/classes/partials.go, ../sm-seo-plugin/models/settings.go, ../sm-seo-plugin/models/settings/fields.yaml, ../sm-seo-plugin/models/robots.go, ../sm-seo-plugin/updates/202610280003_add_golem15_seo_links_and_llms.go, ../sm-seo-plugin/updates/registry.go, ../sm-seo-plugin/extensions_robots.go, ../sm-seo-plugin/extension/_seo_status.htm, ../sm-seo-plugin/controllers/api/site.go, ../sm-seo-plugin/controllers/api/llms.go, ../sm-seo-plugin/routes.go, ../sm-seo-plugin/config/config.yaml, ../sm-seo-plugin/lang/en/lang.yaml, ../sm-seo-plugin/lang/pl/lang.yaml, ../sm-seo-plugin/README.md, ../sm-seo-plugin/registry_test.go, ../sm-seo-plugin/sitemap_filter_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/classes/settings_write.go (allowed columns ~36-41, SettingsValues 46-69, SetSettingsValue 72+, history and after-commit job 301-313)
|
||||
- ../sm-seo-plugin/classes/robots.go (served body, Sitemap lines), classes/batch.go (conflicts), classes/issues.go, classes/history.go
|
||||
- ../sm-seo-plugin/extensions_robots.go and extension/_seo_status.htm
|
||||
- summercms.go/modules/cooler/sitecache.go (the after-commit purge helper)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C20 Links tab, C25, SEO tab additions copy for status.excluded_*)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- TestSiteEndpoint: /_seo/api/v1/site answers every P33-17 key; root_files lists each verification file name and, when the sitemap's IndexNow is on, its key file; routes lists each content type's layered pattern; X-Robots-Tag noindex
|
||||
- TestLLMSTxt: off → 404; on → text/plain with "# <site name>", the intro (or default description) as a quote line, then one "## <group title>" section per non-empty group with "- [title](absolute url)" lines; excluded URLs never appear
|
||||
- Robots: without robots_sitemaps override the served file has exactly "Sitemap: <site>/sitemap.xml"; with the override, the configured lines
|
||||
- Links tab: links_new_tab default true; nofollow_domains "example.com\nhttps://x.pl/a" → 422 settings.domain_invalid naming line 2; the resolve answer of an ok page has outbound {new_tab: true, nofollow_domains: [example.com], sponsored_domains: []}; seo_update_settings with links_new_tab false turns it off
|
||||
- TestNoindexPublishedConflict: a batch noindex on a URL that is in a sitemap file reports noindex_published; on a URL not listed (type switched off) it does not
|
||||
- TestSitemapBlockedIssue: robots.txt "Disallow: /blog/" with a listed /blog/x → issue sitemap_blocked (Error, tool seo_update_robots, details.line)
|
||||
- TestPurgeAfterWrite: an SEO tab save, a redirect create through MCP and a settings save each post one purge after commit; a rolled-back batch posts none
|
||||
- P1 shows status.excluded_title with the reason text for a noindex page and for a page whose type is off in the sitemap settings
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-22, D-24, D-25, D-83, the 2026-10-28 layer options and P33-16/P33-17/P33-19: migration 202610280003 adds settings links_new_tab boolean NOT NULL DEFAULT true, nofollow_domains text, sponsored_domains text, and robots llms_enabled boolean NOT NULL DEFAULT false, llms_intro text. Settings: the four-place pattern of settings_write.go for the three Links columns with domain validation (lowercase host names, one per line, no scheme or path), the Links tab in models/settings/fields.yaml (links_new_tab switch right with settings.links_new_tab_comment; nofollow_domains and sponsored_domains textarea small left/right with settings.domains_comment); robots singleton fields llms_enabled and llms_intro (hide trigger) through extensions_robots.go. `classes/site.go` builds the P33-17 answer (Listing.Settings via app.Lookup[contract.Listing], verification names, signpost patterns); `controllers/api/site.go` serves it; `classes/llms.go` + `controllers/api/llms.go` serve the literal root route `GET /llms.txt` (bucket seo-robots). robots.go reads the index URL from Listing.Settings when `robots_sitemaps` is not set in config (the config default line changes to a comment explaining the fallback). resolver.go adds Outbound (P33-16). batch.go: noindex_published only when a contract.Listing entry lists the URL. issues.go: kind `sitemap_blocked` (Error, tool seo_update_robots) using the grobotstxt matcher against the production body. history.go schedules the after-commit purge (P33-19). partials.go/_seo_status.htm: the excluded callout from Filter decisions for the record. README: routes, config keys, the registry, the site answer, llms.txt, Links and purge. Tests first. Commit groups A to E.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestSiteEndpoint|TestLLMSTxt|TestNoindexPublishedConflict|TestSitemapBlockedIssue|TestPurgeAfterWrite|TestRobots|TestSettingsLinks' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -30</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestSiteEndpoint, TestLLMSTxt, TestNoindexPublishedConflict, TestSitemapBlockedIssue or TestPurgeAfterWrite missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n '"/llms.txt"\|"/site"' ../sm-seo-plugin/routes.go` prints two lines
|
||||
- `grep -n "links_new_tab" ../sm-seo-plugin/classes/settings_write.go ../sm-seo-plugin/models/settings/fields.yaml ../sm-seo-plugin/classes/resolver.go` prints a line in each
|
||||
- `grep -n "sitemap_blocked" ../sm-seo-plugin/classes/issues.go` prints at least one line
|
||||
- existing resolve keys are unchanged: TestResolverPrecedence and the Phase 32 resolve tests pass
|
||||
</acceptance_criteria>
|
||||
<done>The layer has a site endpoint, robots and llms.txt follow the sitemap, outbound link rules are settings, conflicts and issues know the sitemap, and every SEO write refreshes the rendered site.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| frontend server → route report | token-authenticated server-to-server POST |
|
||||
| visitors → /site, /llms.txt | anonymous reads |
|
||||
| admin/MCP → registry and settings | authenticated writes |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-18 | Tampering | route report poisoning the registry | high | mitigate | bearer token with constant-time comparison, size caps, insert-only (never delete or overwrite editor values), owned paths skipped; TestRouteReport |
|
||||
| T-33-19 | Information disclosure | /site answer | medium | mitigate | answers only public facts (site URL, locales, patterns, public root file names); no token, no unpublished data; reviewed against P33-17 in TestSiteEndpoint |
|
||||
| T-33-20 | Information disclosure | llms.txt | medium | mitigate | built from the sitemap's included set only (noindex/unpublished never present), off by default |
|
||||
| T-33-21 | Elevation of privilege | Pages admin and MCP | high | mitigate | golem15.seo.manage on every operation; TestEveryAdminOperationHasTool and the manage wrapper |
|
||||
| T-33-22 | Tampering | domain lists | low | mitigate | validated host names only; rendered by the layer as rel tokens, never as markup |
|
||||
| T-33-23 | Denial of service | purge after writes | low | mitigate | one purge per transaction after commit, coalesced by the framework purger |
|
||||
| T-33-SC | Tampering | npm/pip/cargo installs | high | accept | no new package; sm-sitemap-plugin is a first-party sibling module |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...` after every commit.
|
||||
- Docker suite: TestSitemapFilterTracer, TestRegistry, TestRouteReport, TestSiteEndpoint, TestLLMSTxt, TestNoindexPublishedConflict, TestSitemapBlockedIssue, TestPurgeAfterWrite and the Phase 32 suites.
|
||||
- `go -C ../sm-sitemap-plugin test -short ./...` still passes (sitemap without SEO).
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Sitemaps leave out noindex, canonicalised and redirected URLs through the published filter.
|
||||
- The page registry works from the admin, MCP and the route report.
|
||||
- The site endpoint, llms.txt, robots Sitemap:, the Links settings and purge after writes work.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Go symbols: `classes.SitemapFilter` (Decide, Groups), registry service with `ReportRoutes`, `classes.Outbound` and `Result.Outbound`, site and llms builders, API handlers for registry, pages, site and llms.
|
||||
- Menu item type: `seo-page` (Kind page).
|
||||
- Tables/columns: `golem15_seo_pages`; settings `routes_reported_at`, `links_new_tab`, `nofollow_domains`, `sponsored_domains`; robots `llms_enabled`, `llms_intro`; migrations 202610280002, 202610280003.
|
||||
- Routes: `POST /_seo/api/v1/registry/routes`, `GET /_seo/api/v1/site`, `GET /llms.txt`, `GET/POST /_seo/api/v1/pages`, `PUT/DELETE /_seo/api/v1/pages/{id}`; resolve answer key `outbound`.
|
||||
- Admin: controller `golem15.seo.pages` (Pages), partial `page_status` (P9), Links tab, llms fields on the robots screen; issue kind `sitemap_blocked`.
|
||||
- MCP tools: `seo_list_pages`, `seo_create_page`, `seo_update_page`, `seo_delete_page`.
|
||||
- Config key: `golem15.seo.route_report_token`.
|
||||
- Tests: `TestSitemapFilterTracer`, `TestRegistry`, `TestRouteReport`, `TestSiteEndpoint`, `TestLLMSTxt`, `TestNoindexPublishedConflict`, `TestSitemapBlockedIssue`, `TestPurgeAfterWrite`.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-05-SUMMARY.md` when done.
|
||||
</output>
|
||||
320
.planning/phases/33-seo-output-audit-and-content/33-06-PLAN.md
Normal file
320
.planning/phases/33-seo-output-audit-and-content/33-06-PLAN.md
Normal file
@@ -0,0 +1,320 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 06
|
||||
type: execute
|
||||
wave: 5
|
||||
depends_on: ["33-05"]
|
||||
files_modified:
|
||||
- ../sm-seo-plugin/classes/schema/graph.go
|
||||
- ../sm-seo-plugin/classes/schema/nodes.go
|
||||
- ../sm-seo-plugin/classes/schema/validate.go
|
||||
- ../sm-seo-plugin/classes/schema/custom.go
|
||||
- ../sm-seo-plugin/classes/breadcrumbs.go
|
||||
- ../sm-seo-plugin/classes/alternates.go
|
||||
- ../sm-seo-plugin/classes/pagination.go
|
||||
- ../sm-seo-plugin/classes/resolver.go
|
||||
- ../sm-seo-plugin/classes/normalize.go
|
||||
- ../sm-seo-plugin/classes/site.go
|
||||
- ../sm-seo-plugin/classes/settings_write.go
|
||||
- ../sm-seo-plugin/classes/entries.go
|
||||
- ../sm-seo-plugin/classes/field_types.go
|
||||
- ../sm-seo-plugin/classes/partials.go
|
||||
- ../sm-seo-plugin/classes/manage.go
|
||||
- ../sm-seo-plugin/models/settings.go
|
||||
- ../sm-seo-plugin/models/settings/fields.yaml
|
||||
- ../sm-seo-plugin/updates/202610280004_add_golem15_seo_publisher_pagination.go
|
||||
- ../sm-seo-plugin/updates/registry.go
|
||||
- ../sm-seo-plugin/extensions.go
|
||||
- ../sm-seo-plugin/extension/_seo_status.htm
|
||||
- ../sm-seo-plugin/extension/_seo_effective.htm
|
||||
- ../sm-seo-plugin/controllers/settings/_publisher_preview.htm
|
||||
- ../sm-seo-plugin/controllers/settings/config_form.yaml
|
||||
- ../sm-seo-plugin/controllers/api/graph.go
|
||||
- ../sm-seo-plugin/controllers/api/seo.go
|
||||
- ../sm-seo-plugin/field_types.go
|
||||
- ../sm-seo-plugin/routes.go
|
||||
- ../sm-seo-plugin/mcp.go
|
||||
- ../sm-seo-plugin/operations.go
|
||||
- ../sm-seo-plugin/config/config.yaml
|
||||
- ../sm-seo-plugin/assets/src/elements/schema.ts
|
||||
- ../sm-seo-plugin/assets/src/elements/graph.ts
|
||||
- ../sm-seo-plugin/assets/src/elements/parent.ts
|
||||
- ../sm-seo-plugin/assets/src/elements/index.ts
|
||||
- ../sm-seo-plugin/assets/src/elements/labels.ts
|
||||
- ../sm-seo-plugin/assets/src/elements/styles.css
|
||||
- ../sm-seo-plugin/assets/dist/seo.js
|
||||
- ../sm-seo-plugin/assets/dist/seo.css
|
||||
- ../sm-seo-plugin/lang/en/lang.yaml
|
||||
- ../sm-seo-plugin/lang/pl/lang.yaml
|
||||
- ../sm-seo-plugin/README.md
|
||||
- ../sm-seo-plugin/structured_data_test.go
|
||||
autonomous: true
|
||||
requirements: [SC-2, SC-3, D-43, D-44, D-45, D-46, D-03, D-86, D-55, D-56, D-57, D-40, D-41, D-42, D-21, D-94, D-10]
|
||||
|
||||
estimate:
|
||||
tokens: 170000
|
||||
raw_tokens: 170000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "The resolve answer of every ok page carries jsonld: one {\"@context\": \"https://schema.org\", \"@graph\": [...]} whose nodes link by @id: WebPage (or its subtype) + BreadcrumbList + references to WebSite and the publisher on every page; WebSite (+ SearchAction when golem15.seo.search_url is set) and the publisher on the home page; BlogPosting/Article/NewsArticle with author Person, publisher, image, datePublished, dateModified, wordCount and articleSection for article content; CollectionPage with mainEntity pointing to #itemlist for collections (the layer adds the ItemList node); ProfilePage + Person for profiles; Service with provider, areaServed and an optional Offer for registry offers and services; ContactPage + the publisher with address and opening hours; a VideoObject per YouTube video (D-43, D-94, D-96)"
|
||||
- "The publisher is set in the global settings (Publisher tab: Organisation or Person, name, logo through seoimage, url, email, phone, sameAs; Local business tab behind a switch with type, address, geo, opening hours and price range); a person cannot be a local business (settings.local_person) and every C20 refusal answers 422 (D-45, D-03)"
|
||||
- "The SEO tab gains Structured data (E8 seoschema: type select per kind, Service fields, custom JSON-LD with live parse feedback), Structured data preview (E9: the effective @graph of the saved page plus unsaved schema, required and recommended findings, the Rich Results Test link) and Primary category for content whose descriptor supplies Parents (D-44, D-46, D-86)"
|
||||
- "Saving custom JSON-LD refuses invalid JSON, non-objects, more than 16 KB, nesting deeper than 8, a literal <script and a type outside the kind's list with the schema.* copy; a custom node whose @id matches a generated node merges into it with custom values first and the save answers the schema.merged notice (D-44, UI-SPEC C17)"
|
||||
- "No e-commerce type (Product, Offer as a product) is offered or generated (out of scope)"
|
||||
- "Breadcrumbs come from one source: the resolve answer's breadcrumbs [{name, url, path}] equals the BreadcrumbList items; the first item is the home crumb (settings breadcrumb_home per locale), a post's trail goes through its primary parent (seo_primary_parent, else the first Parent, recursively, at most 6 levels) and the current page is last (D-86)"
|
||||
- "hreflang comes from one source: the resolve answer's alternates list each translated locale with a URL including the page itself plus x-default for the default locale; a locale without a translation is absent and a page with one locale has no alternates; html_lang, seo.og.locale and seo.og.locale_alternates come from the same data (D-55, D-56, D-57)"
|
||||
- "Pagination follows the per-site form (Pagination tab: query ?page=N default, or path /<segment>/N with a segment per locale): ?page=1 and /<segment>/1 answer 301 to the unnumbered URL, the other form answers 301 to the configured one, a garbage page value answers not_found with pagination.invalid true; page 2 and later answer ok with index,follow, a self-referencing canonical with the page, and the title and description suffixes with %page% filled and %pages% left for the layer (D-40, D-41, D-42, D-21)"
|
||||
- "GET /_seo/api/v1/site additionally answers pagination {form, param, segments} and home_crumb per locale, so the layer builds numbered links and checks drift (D-40, D-20c)"
|
||||
- "Validation runs in three places: E9 in the admin against Google's required and recommended properties per type (FAQPage, CollectionPage, WebPage and Service get the noRules line), the crawler in 33-10 on the rendered page, and the Rich Results Test link per URL (D-46)"
|
||||
- "MCP: seo_get_graph (GET /_seo/api/v1/graph?url=&schema=) returns the graph and findings; seo_set_url_seo and apply_batch accept primary_parent and schema; seo_update_settings writes every new settings key; TestEveryAdminOperationHasTool maps the seo_graph widget action (D-10)"
|
||||
- "E9 with no findings shows the single allGood line; E8 with no value shows the kind's default type and note with the custom JSON-LD collapsed (UI-SPEC empty: E8, E9)"
|
||||
- "E9 shows the checking line with aria-busy while building and queues at most one request (UI-SPEC loading: E9)"
|
||||
- "An E9 action failure shows the 13px danger line with circle-alert and keeps the last graph; an element script failure shows the existing ExtensionFailure box (UI-SPEC error)"
|
||||
- "A 422 on the settings form or on E8 shows field lines, the count banner and the tab error badge (UI-SPEC error: save refused)"
|
||||
- "E8 and E9 follow the ML locale switcher; P2 rows are per locale (UI-SPEC partial: SEO in one locale only)"
|
||||
- "P1 shows status.primary_gone when the stored primary category is no longer assigned, and the trail falls back to the first category (UI-SPEC partial: primary category gone)"
|
||||
- "E9's JSON pre has max-height 360px and scrolls in both axes (UI-SPEC overflow: E9)"
|
||||
- {statement: "E8 value round-trip: Service fields come back as the same JSON string; an invalid price shows priceInvalid; a JSON parse error names line and column; more than 16 KB shows jsonTooLarge (UI-SPEC E8 backstop)", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-44"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "Custom JSON-LD can never close the script element or inject markup: a literal <script is refused on save and the JSON is re-serialised by the server, never echoed as typed"
|
||||
artifacts:
|
||||
- path: "../sm-seo-plugin/classes/schema/graph.go"
|
||||
provides: "@graph builder per kind"
|
||||
contains: "@graph"
|
||||
- path: "../sm-seo-plugin/classes/schema/validate.go"
|
||||
provides: "required/recommended rules per type"
|
||||
contains: "func "
|
||||
- path: "../sm-seo-plugin/classes/pagination.go"
|
||||
provides: "page form normalisation and suffixes"
|
||||
contains: "%pages%"
|
||||
- path: "../sm-seo-plugin/structured_data_test.go"
|
||||
provides: "TestGraphTracer, TestGraphPerKind, TestCustomJSONLD, TestAlternates, TestBreadcrumbs, TestPagination, TestPublisherSettings, TestGraphTool"
|
||||
contains: "func TestGraphTracer("
|
||||
key_links:
|
||||
- from: "../sm-seo-plugin/classes/resolver.go"
|
||||
to: "../sm-seo-plugin/classes/schema/graph.go"
|
||||
via: "resolveAt builds jsonld, breadcrumbs and alternates from the described record and settings"
|
||||
pattern: "schema\\.Build"
|
||||
- from: "../sm-seo-plugin/assets/src/elements/graph.ts"
|
||||
to: "../sm-seo-plugin/controllers/api/graph.go"
|
||||
via: "the seo_graph widget action (op graph) and the MCP tool share classes/schema Build + Validate"
|
||||
pattern: "seo_graph"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan puts structured data, breadcrumbs, hreflang and pagination into the one resolve answer per URL, and gives editors the publisher settings and the schema fields in the SEO tab.
|
||||
|
||||
<objective>
|
||||
Extend ../sm-seo-plugin (main, not pushed):
|
||||
- the JSON-LD @graph builder per content kind with validators (D-43, D-46) and the publisher and local-business settings (D-45, D-03);
|
||||
- breadcrumbs with the primary category (D-86), alternates/x-default/og:locale (D-55..57), pagination forms and suffixes (D-40..42) in resolve and /site;
|
||||
- SEO tab additions E8 (schema), E9 (graph preview), primary category, P1/P2 rows (D-44, D-46);
|
||||
- MCP `seo_get_graph` and the new keys on existing tools (D-10).
|
||||
|
||||
Purpose: SC-2 (one JSON-LD @graph, hreflang and breadcrumbs from the CMS) on the backend side; the layer renders it (33-07 to 33-09).
|
||||
|
||||
Output: commits in ../sm-seo-plugin, with the rebuilt element bundle.
|
||||
|
||||
**Planner decisions recorded here (resolve answer additions are `costly`: every app's layer reads them):**
|
||||
- **P33-21 (resolve answer keys, additive):** top level `html_lang` (locale code, region kept when the locale has one), `alternates: [{hreflang, url}]` (absolute), `jsonld` (object or null), `breadcrumbs: [{name, url, path}]`, `pagination: {form, param, segment, page, invalid}` (present only when the request carries a page); inside `seo.og`: `locale`, `locale_alternates` (from config `golem15.seo.og_locales`, default {pl: pl_PL, en: en_US, de: de_DE}, else `<code>_<CODE>`). No existing key changes.
|
||||
- **P33-22 (@id scheme):** `<site>/#website`, `<site>/#organization` or `<site>/#person` (publisher), `<url>#webpage`, `<url>#breadcrumb`, `<url>#article`, `<url>#itemlist` (layer node), `<url>#profile`, `<url>#service`, `<url>#video-<n>`.
|
||||
- **P33-23 (primary parent field):** extension dropdowns accept only listed options (32-01), so the per-record choice is a plugin field type `seoparent` (element `golem15-seo-parent`, a 44px select styled as the built-in dropdown with emptyOption field.primary_category_default) whose Load answers {selected, options} from the descriptor's Parents; it shows only for types whose records have Parents. The value is stored in the entry's data (key primary_parent) on every locale row, as the social image is (Phase 32 Q-5); seo_schema likewise (key schema).
|
||||
- **P33-24 (%pages%):** the resolver cannot know a listing's page count; it fills %page% and leaves the literal %pages% in seo.title and seo.description on page ≥ 2; the layer's usePagination replaces it (33-08).
|
||||
- **P33-25 (search):** config `golem15.seo.search_url` (for example `/szukaj?q={search_term_string}`), empty means no SearchAction.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-05-SUMMARY.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-01-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
From 33-01: pact.ContentDescriptor{Kind, Tools}; ContentRecord{PublishedAt, Parents []ContentRef{Type, ID}, Authors []ContentPerson{Name, Ref}, TopHeading}; ContentLocale{Images []ContentImage{URL, Alt, Decorative, Width, Height}, Videos []ContentVideo{Provider, ID}, Headings}.
|
||||
From 33-05: Result.Outbound; /site answer (P33-17); contract.Listing; registry kinds (page, offer, service, landing) on seo-page records.
|
||||
Phase 32: classes/resolver.go resolveAt (record, rules, templates, canonical keeps page via D-07 list), classes/normalize.go (one-hop normalisation), classes/settings_write.go four-place pattern, classes/field_types.go (seotext, seorobots, seoimage E7 Decode/Load), extensions.go seoTabYAML (anchors seo_robots, seo_og_image), extension/_seo_status.htm (P1), _seo_effective.htm (P2), assets/src/elements/* (E1–E7 framework-free custom elements, labels.ts by ui-locale, styles.css light DOM, summer-action through WidgetField), tests/elements/*.test.ts (vitest + happy-dom), scripts/check-dist.sh.
|
||||
Google (cited in 33-RESEARCH.md): Article has no required properties, recommended author, dateModified, datePublished, headline, image; BreadcrumbList needs at least two ListItem with position, name, item; VideoObject requires name, thumbnailUrl, uploadDate; LocalBusiness requires name and address; FAQ rich results are gone (no rules for FAQPage).
|
||||
Copy: UI-SPEC C16–C18, C20 (General addition, Pagination, Publisher, Local business), E8/E9 element copy, server copy for E8, P8.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups staged by path in ../sm-seo-plugin; vet and `test -short` green at every commit; element changes rebuild `assets/dist` (`npm --prefix ../sm-seo-plugin run build`) in the same group; lang keys in both files.
|
||||
- Resume check: `git -c safe.directory='*' -C ../sm-seo-plugin log --format=%s | grep -Fx '<subject>'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | `feat: JSON-LD graph, breadcrumbs and hreflang in the resolve answer (tracer)` | TestGraphTracer passes |
|
||||
| 2 | A `feat: publisher, local business and home crumb settings`; B `feat: pagination forms and suffixes in resolve and site` | settings and pagination tests pass |
|
||||
| 3 | A `feat: graph validation and custom JSON-LD`; B `feat: structured data, graph preview and primary category in the SEO tab`; C `feat: graph MCP tool and new SEO keys`; D `docs: structured data, breadcrumbs, hreflang and pagination in README` | plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "resolving a post's URL returns one @graph, its breadcrumbs and its hreflang alternates" — one path only</name>
|
||||
<files>../sm-seo-plugin/classes/schema/graph.go, ../sm-seo-plugin/classes/schema/nodes.go, ../sm-seo-plugin/classes/breadcrumbs.go, ../sm-seo-plugin/classes/alternates.go, ../sm-seo-plugin/classes/resolver.go, ../sm-seo-plugin/models/settings.go, ../sm-seo-plugin/updates/202610280004_add_golem15_seo_publisher_pagination.go, ../sm-seo-plugin/updates/registry.go, ../sm-seo-plugin/config/config.yaml, ../sm-seo-plugin/structured_data_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/classes/resolver.go (Result, SEO, resolveAt, contentLocale) and classes/templates.go
|
||||
- ../sm-seo-plugin/fixture_test.go (fake content plugin; extend its descriptor with the 33-01 fields)
|
||||
- summercms.go/modules/pact/content.go (33-01 fields)
|
||||
- .planning/phases/32-seo-foundation/32-CONTEXT.md (D-43 table, D-55..57, D-86)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pattern 4, Pitfall 3, Pitfall 11)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-43, D-55 to D-57, D-86, P33-21 and P33-22: migration 202610280004 adds every settings column of this plan (publisher_*, local_* incl. local_hours jsonb, breadcrumb_home, page_form text default 'query', page_segment, page_title_suffix, page_description_suffix; translatable ones through the translation writer like site_name); Task 1 uses publisher_type and publisher_name only. `classes/schema`: `Build(ctx, in Input) (map[string]any, error)` composing nodes per P33-22 from the described record (Kind), settings and the page URL; nodes.go holds one function per node type. `classes/breadcrumbs.go`: home crumb, primary parent chain (entry data primary_parent, else first Parent; Describe each parent recursively, 6 levels, skip unpublished), current page; both the BreadcrumbList node and the answer list. `classes/alternates.go`: translated locales with a URL (≥2) plus x-default for the default locale, html_lang, og locale values. resolveAt sets the new keys for ok answers only. Config keys `og_locales` and `search_url` commented in config/config.yaml. `TestGraphTracer` (Docker): a fake article record with PublishedAt, two Parents, an author, two locales and a video, publisher Organisation "Acme" → resolve answers jsonld with WebPage, BlogPosting (headline, author name, datePublished, dateModified, image, wordCount, articleSection = first parent's title), BreadcrumbList (home, parent, post), VideoObject, WebSite and Organization nodes linked by the P33-22 @ids; breadcrumbs equals the BreadcrumbList items; alternates lists pl, en and x-default; a single-locale record has none. Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestGraphTracer' -count=1 -v 2>&1 | tail -20</automated>
|
||||
<fails_when>non-zero exit, "FAIL" or "no tests to run" in the output, or no "--- PASS: TestGraphTracer" line</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "func Build(" ../sm-seo-plugin/classes/schema/graph.go` prints one line
|
||||
- `grep -n 'json:"jsonld\|json:"alternates\|json:"breadcrumbs\|json:"html_lang' ../sm-seo-plugin/classes/resolver.go` prints four lines
|
||||
- TestResolverPrecedence and the Phase 32 resolve tests still pass (no existing key changed)
|
||||
</acceptance_criteria>
|
||||
<done>One resolve call returns the page's @graph, breadcrumbs and hreflang data.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Publisher, local business, home crumb and pagination settings; pagination forms, suffixes and normalisation in resolve and /site</name>
|
||||
<files>../sm-seo-plugin/models/settings.go, ../sm-seo-plugin/models/settings/fields.yaml, ../sm-seo-plugin/classes/settings_write.go, ../sm-seo-plugin/classes/pagination.go, ../sm-seo-plugin/classes/normalize.go, ../sm-seo-plugin/classes/resolver.go, ../sm-seo-plugin/classes/site.go, ../sm-seo-plugin/classes/schema/nodes.go, ../sm-seo-plugin/controllers/settings/_publisher_preview.htm, ../sm-seo-plugin/controllers/settings/config_form.yaml, ../sm-seo-plugin/lang/en/lang.yaml, ../sm-seo-plugin/lang/pl/lang.yaml, ../sm-seo-plugin/structured_data_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/classes/settings_write.go and models/settings/fields.yaml (tabs and the four-place pattern)
|
||||
- ../sm-seo-plugin/classes/normalize.go (one-hop normalisation) and classes/urls.go (D-07 parameter list keeps page)
|
||||
- ../sm-seo-plugin/controllers/settings/_placeholders.htm (settings partial pattern)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C20 tabs and copy, P8)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- TestPublisherSettings: Publisher tab saves type, name, logo, url, email, phone, sameAs; sameAs line "x.pl" → 422 settings.same_as_invalid line 1; local_enabled with publisher Person → 422 settings.local_person; local without street → settings.local_address_required; "9:00" → settings.time_invalid; closes before opens → settings.hours_order; country "POL" → settings.country_invalid; latitude 91 → settings.coordinate_invalid; P8 shows the generated publisher node and its findings (missing logo → warning line), or "No problems"
|
||||
- The publisher node becomes the local_type (LocalBusiness subtype) with PostalAddress, GeoCoordinates, openingHoursSpecification and priceRange when local_enabled; ContactPage pages reference it
|
||||
- TestPagination (query form): /blog?page=1 → 301 /blog; /blog?page=3 → ok, canonical /blog?page=3, robots index,follow, title "<title> – strona 3 z %pages% | Site" in pl, description suffix appended; /blog?page=abc, ?page=0, ?page=-1 → not_found with pagination.invalid; /blog/strona/3 → 301 /blog?page=3
|
||||
- TestPagination (path form, segment pl strona): /blog?page=3 → 301 /blog/strona/3; /blog/strona/1 → 301 /blog; /blog/strona/x → not_found invalid; /en/blog/page/2 uses the en segment
|
||||
- Every 301 reaches its final address in one hop together with the Phase 32 normalisation and redirects
|
||||
- /site answers pagination {form, param: page, segments} and home_crumb {pl: Strona główna, en: Home} by default; breadcrumb_home changes them
|
||||
- Unknown placeholders in a suffix refuse with settings.template_unknown; a segment outside [a-z0-9-] refuses with settings.page_segment_invalid
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-03, D-45, D-40 to D-42, D-21 and P33-24: the four-place settings pattern for every new column with C20 validation; fields.yaml tabs General (breadcrumb_home after twitter_site), Pagination, Publisher (publisher_logo uses the E7 seoimage type; P8 partial `_publisher_preview.htm` on update), Local business (local_enabled switch and the trigger-hidden fields, local_hours repeater with titleFrom day), in the C20 tab order. nodes.go builds the publisher node from these settings. `classes/pagination.go`: parse the page from the query or the configured path segment (per locale), the 301 rules (folded into the one-hop decision of normalize.go/resolver so a normalisation and a page redirect are one hop), the invalid answer, and the title/description suffixes (%page% filled, %pages% kept per P33-24); robots for page ≥ 2 stay index,follow with the canonical keeping the page (D-21). site.go adds pagination and home_crumb. Tests first. Commit groups A and B.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestPublisherSettings|TestPagination|TestSiteEndpoint|TestNormalize' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -20</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestPublisherSettings or TestPagination missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "page_form\|page_segment\|publisher_type\|local_enabled\|breadcrumb_home" ../sm-seo-plugin/classes/settings_write.go` prints at least five lines
|
||||
- `grep -n "%pages%" ../sm-seo-plugin/classes/pagination.go` prints at least one line
|
||||
- `grep -n '"pagination"\|"home_crumb"' ../sm-seo-plugin/classes/site.go` prints two lines
|
||||
</acceptance_criteria>
|
||||
<done>The publisher and pagination are settings, and every paginated URL resolves in its configured form with the D-41 rules.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Validators and custom JSON-LD, SEO tab E8/E9/primary category, P1/P2 additions, seo_get_graph and the new keys</name>
|
||||
<files>../sm-seo-plugin/classes/schema/validate.go, ../sm-seo-plugin/classes/schema/custom.go, ../sm-seo-plugin/classes/schema/graph.go, ../sm-seo-plugin/classes/field_types.go, ../sm-seo-plugin/classes/entries.go, ../sm-seo-plugin/classes/partials.go, ../sm-seo-plugin/classes/manage.go, ../sm-seo-plugin/extensions.go, ../sm-seo-plugin/extension/_seo_status.htm, ../sm-seo-plugin/extension/_seo_effective.htm, ../sm-seo-plugin/field_types.go, ../sm-seo-plugin/controllers/api/graph.go, ../sm-seo-plugin/controllers/api/seo.go, ../sm-seo-plugin/routes.go, ../sm-seo-plugin/mcp.go, ../sm-seo-plugin/operations.go, ../sm-seo-plugin/assets/src/elements/schema.ts, ../sm-seo-plugin/assets/src/elements/graph.ts, ../sm-seo-plugin/assets/src/elements/parent.ts, ../sm-seo-plugin/assets/src/elements/index.ts, ../sm-seo-plugin/assets/src/elements/labels.ts, ../sm-seo-plugin/assets/src/elements/styles.css, ../sm-seo-plugin/assets/dist/seo.js, ../sm-seo-plugin/assets/dist/seo.css, ../sm-seo-plugin/lang/en/lang.yaml, ../sm-seo-plugin/lang/pl/lang.yaml, ../sm-seo-plugin/README.md, ../sm-seo-plugin/structured_data_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/extensions.go (seoTabYAML, reserved anchors, Save/Load, widget actions such as seo_snippet)
|
||||
- ../sm-seo-plugin/classes/field_types.go and field_types.go (seoimage Decode/Load and registration)
|
||||
- ../sm-seo-plugin/assets/src/elements/{serp,robots,image,actions,labels,index}.ts and styles.css (E1–E7 patterns, summer-action, summer:ml-locale)
|
||||
- ../sm-seo-plugin/tests/elements/host.ts and serp.test.ts (element test harness)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C16, C17, C18, E8/E9 copy, Shared rules, Color, Typography)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- TestCustomJSONLD: each refusal of C17 answers 422 with its schema.* key on seo_schema; a custom node with @id <url>#article and headline "X" replaces the generated headline and the save answers schema.merged naming the property; a custom node with a new @id is appended to the graph; the stored value is re-serialised JSON
|
||||
- TestGraphPerKind: collection → CollectionPage with mainEntity #itemlist; profile → ProfilePage + Person; registry offer → Service with provider ref and areaServed/price/currency from the schema fields; registry page with schema ContactPage → ContactPage referencing the publisher; home → WebSite with SearchAction when search_url is set
|
||||
- Validate: BlogPosting missing image → recommended finding image; VideoObject missing uploadDate → required finding; LocalBusiness without address → required; FAQPage, CollectionPage, WebPage, Service → rules false
|
||||
- TestGraphTool: GET /_seo/api/v1/graph?url=<post>&schema=<json> answers {locale, url, graph, nodes[{id, type, findings, rules}]}; without golem15.seo.manage 403; the seo_graph widget action answers the same data; MCP lists get_graph; TestEveryAdminOperationHasTool passes
|
||||
- seo_set_url_seo with primary_parent and schema writes the entry data on every locale row; apply_batch accepts both keys with dry_run
|
||||
- P1 shows status.primary_gone for a stored primary parent the record no longer has; P2 shows Schema type and Breadcrumb trail rows
|
||||
- Element smoke (vitest): E8 renders the article type options and the Service grid; E9 renders nodes and findings from a stubbed action answer; the parent select lists the options from its value
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-44, D-46, D-86, UI-SPEC C16–C18 and P33-23: `classes/schema/validate.go` with per-type required/recommended rules; `custom.go` decoding and merging per C17 server rules; field type `seoschema` (element golem15-seo-schema, option kind from the descriptor's Kind; Decode validates and normalises the JSON string) and `seoparent` (element golem15-seo-parent per P33-23); extensions.go inserts seo_primary_parent (only when the type's records have Parents), seo_schema and seo_graph (type widget, action seo_graph, fill [seo_schema], context update) at the C16 positions, writes primary_parent and schema into the entry data, and answers the merge notice; `controllers/api/graph.go` + route `GET /_seo/api/v1/graph` (management group) + MCP tool get_graph + AdminOperations rows (widget_action:seo_graph#graph → get_graph; the extension save keys stay on set_url_seo); controllers/api/seo.go and classes/manage.go accept the new keys. Elements per C17/C18 (light DOM, `--c-*` colours, labels by ui-locale with every E8/E9 key, 300 ms parse debounce, 800 ms graph debounce, one queued request, Rich Results link `https://search.google.com/test/rich-results?url=<encoded>` with rel noopener), parent.ts select; rebuild dist. P1 primary_gone and P2 rows. README sections for structured data, breadcrumbs, hreflang and pagination. Tests first (Go and a vitest smoke per element in tests/elements). Commit groups A to D.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestCustomJSONLD|TestGraphPerKind|TestGraphTool|TestGraphTracer|TestEveryAdminOperationHasTool|TestSEOTab' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -30</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestCustomJSONLD, TestGraphPerKind or TestGraphTool missing from the "--- PASS" lines</fails_when>
|
||||
<automated>npm --prefix ../sm-seo-plugin run test 2>&1 | tail -15 && bash ../sm-seo-plugin/scripts/check-dist.sh</automated>
|
||||
<fails_when>non-zero exit, a failed count above 0 in the vitest summary, or the dist check reporting a difference</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n '"seoschema"\|"seoparent"' ../sm-seo-plugin/classes/field_types.go ../sm-seo-plugin/field_types.go` prints at least two lines
|
||||
- `grep -n "golem15-seo-schema\|golem15-seo-graph\|golem15-seo-parent" ../sm-seo-plugin/assets/src/elements/index.ts` prints three lines
|
||||
- `grep -n '"get_graph"' ../sm-seo-plugin/mcp.go` prints one line
|
||||
- `grep -rn "Product" ../sm-seo-plugin/classes/schema/` prints nothing
|
||||
</acceptance_criteria>
|
||||
<done>Editors choose schema types and custom JSON-LD with live checks, see the effective graph with Google's rules, and MCP can do the same.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| admin/MCP → custom JSON-LD and settings | untrusted structured input stored and later embedded in pages |
|
||||
| resolve answer → layer | JSON-LD rendered into a script element |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-24 | Tampering (XSS) | custom JSON-LD | high | mitigate | parse, objects only, 16 KB and depth 8 caps, refuse a literal <script, re-serialise with encoding/json (which escapes <, > and &); the layer additionally relies on unhead's JSON escaping (33-07); TestCustomJSONLD |
|
||||
| T-33-25 | Tampering | publisher sameAs, URLs | medium | mitigate | https-only absolute URLs validated on save; emitted only inside JSON |
|
||||
| T-33-26 | Spoofing | breadcrumbs and alternates | low | mitigate | built from signpost descriptors and settings only, never from the request |
|
||||
| T-33-27 | Elevation of privilege | graph tool, settings, SEO tab keys | high | mitigate | golem15.seo.manage on every route and widget action (existing manage wrapper), 403 in TestGraphTool |
|
||||
| T-33-28 | Denial of service | graph building per resolve | low | mitigate | descriptor reads per resolve are already one call; parent chain capped at 6 |
|
||||
| T-33-SC | Tampering | npm/pip/cargo installs | high | accept | no new package; the element bundle rebuilds from the committed lockfile |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...` after every commit.
|
||||
- Docker suite: structured_data_test.go tests and the Phase 32/33-05 suites.
|
||||
- `npm --prefix ../sm-seo-plugin run test` and `bash ../sm-seo-plugin/scripts/check-dist.sh` pass.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- The resolve answer carries one @graph, breadcrumbs, alternates and pagination data.
|
||||
- Publisher, local business, pagination and home crumb are settings; the SEO tab has E8, E9 and the primary category.
|
||||
- seo_get_graph and the new keys work through MCP.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Package `classes/schema`: `Build`, `Input`, node builders, `Validate`, custom JSON-LD decode/merge.
|
||||
- Go symbols: breadcrumbs, alternates and pagination builders; field types `seoschema`, `seoparent`; API handler `Graph`.
|
||||
- Resolve keys: `html_lang`, `alternates`, `jsonld`, `breadcrumbs`, `pagination`, `seo.og.locale`, `seo.og.locale_alternates`; /site keys `pagination`, `home_crumb`.
|
||||
- Settings columns: `breadcrumb_home`, `page_form`, `page_segment`, `page_title_suffix`, `page_description_suffix`, `publisher_type`, `publisher_name`, `publisher_logo`, `publisher_url`, `publisher_email`, `publisher_phone`, `publisher_same_as`, `local_enabled`, `local_type`, `local_price_range`, `local_street`, `local_postal_code`, `local_city`, `local_region`, `local_country`, `local_latitude`, `local_longitude`, `local_hours`; migration 202610280004.
|
||||
- Entry data keys: `primary_parent`, `schema`.
|
||||
- Elements: `golem15-seo-schema` (E8), `golem15-seo-graph` (E9), `golem15-seo-parent`; partial `publisher_preview` (P8).
|
||||
- Route: `GET /_seo/api/v1/graph`; MCP tool `seo_get_graph`.
|
||||
- Config keys: `golem15.seo.og_locales`, `golem15.seo.search_url`.
|
||||
- Tests: `TestGraphTracer`, `TestGraphPerKind`, `TestCustomJSONLD`, `TestPublisherSettings`, `TestPagination`, `TestGraphTool` (plus `TestAlternates` and `TestBreadcrumbs` subtests in the tracer file).
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-06-SUMMARY.md` when done; copy the final resolve-answer JSON of TestGraphTracer into it so the layer fixtures (33-07 to 33-09) can be compared.
|
||||
</output>
|
||||
331
.planning/phases/33-seo-output-audit-and-content/33-07-PLAN.md
Normal file
331
.planning/phases/33-seo-output-audit-and-content/33-07-PLAN.md
Normal file
@@ -0,0 +1,331 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 07
|
||||
type: execute
|
||||
wave: 1
|
||||
depends_on: []
|
||||
files_modified:
|
||||
- ../vue-seo-layer/.gitignore
|
||||
- ../vue-seo-layer/.nvmrc
|
||||
- ../vue-seo-layer/package.json
|
||||
- ../vue-seo-layer/pnpm-lock.yaml
|
||||
- ../vue-seo-layer/pnpm-workspace.yaml
|
||||
- ../vue-seo-layer/tsconfig.json
|
||||
- ../vue-seo-layer/README.md
|
||||
- ../vue-seo-layer/nuxt.config.ts
|
||||
- ../vue-seo-layer/lib/seo-module.ts
|
||||
- ../vue-seo-layer/app/app.config.ts
|
||||
- ../vue-seo-layer/app/plugins/seo-head.ts
|
||||
- ../vue-seo-layer/app/composables/useCmsSeo.ts
|
||||
- ../vue-seo-layer/app/composables/useSchemaNode.ts
|
||||
- ../vue-seo-layer/app/composables/useSeoLabels.ts
|
||||
- ../vue-seo-layer/app/utils/graph.ts
|
||||
- ../vue-seo-layer/app/utils/pagePath.ts
|
||||
- ../vue-seo-layer/app/utils/labels.ts
|
||||
- ../vue-seo-layer/app/utils/types.ts
|
||||
- ../vue-seo-layer/app/assets/css/seo-tokens.css
|
||||
- ../vue-seo-layer/app/assets/css/seo-base.css
|
||||
- ../vue-seo-layer/server/middleware/seo.ts
|
||||
- ../vue-seo-layer/server/middleware/seo-root.ts
|
||||
- ../vue-seo-layer/server/lib/resolve.ts
|
||||
- ../vue-seo-layer/server/lib/lru.ts
|
||||
- ../vue-seo-layer/server/lib/site.ts
|
||||
- ../vue-seo-layer/server/lib/siteCachePurge.ts
|
||||
- ../vue-seo-layer/server/api/__seo__/resolve.get.ts
|
||||
- ../vue-seo-layer/server/api/__site__/cache/purge.post.ts
|
||||
- ../vue-seo-layer/server/plugins/site-cache-purge.ts
|
||||
- ../vue-seo-layer/server/plugins/seo-notfound.ts
|
||||
- ../vue-seo-layer/.playground/nuxt.config.ts
|
||||
- ../vue-seo-layer/.playground/app/app.vue
|
||||
- ../vue-seo-layer/.playground/app/pages/index.vue
|
||||
- ../vue-seo-layer/.playground/app/pages/[...slug].vue
|
||||
- ../vue-seo-layer/testing/smoke-ssr.mjs
|
||||
- ../vue-seo-layer/testing/fixture-api.mjs
|
||||
- ../vue-seo-layer/testing/nuxt-server.mjs
|
||||
- ../vue-seo-layer/testing/purge-check.mjs
|
||||
- ../vue-seo-layer/testing/purge-token-check.mjs
|
||||
- ../vue-seo-layer/testing/expect-seo.txt
|
||||
- ../vue-seo-layer/testing/fixtures/seo/resolve.json
|
||||
- ../vue-seo-layer/testing/fixtures/seo/site.json
|
||||
- ../vue-seo-layer/tests/graph.test.ts
|
||||
- ../vue-seo-layer/tests/pagePath.test.ts
|
||||
- ../vue-seo-layer/tests/lru.test.ts
|
||||
- ../vue-seo-layer/tests/labels.test.ts
|
||||
- ../vue-seo-layer/tests/sitePurge.test.ts
|
||||
autonomous: false
|
||||
requirements: [SC-2, D-97, D-20, D-20a, D-20b, D-20c, D-08, D-05, D-103, D-43, D-55, D-71, D-22, D-25]
|
||||
|
||||
estimate:
|
||||
tokens: 140000
|
||||
raw_tokens: 140000
|
||||
tasks: 4
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "A new Nuxt layer repository (name confirmed at Task 1, proposed vue-seo-layer) exists locally with nuxt 4.4.8 and no runtime package beyond Nuxt; it does not use @nuxtjs/seo, nuxt-schema-org, @nuxtjs/robots or @nuxtjs/sitemap (D-97, RESEARCH Standard Stack)"
|
||||
- "A Nitro middleware resolves every page request (skipping /_nuxt, /api, /__nuxt_error and asset files) through GET /_seo/api/v1/resolve with the visitor's X-Forwarded-For, enforces action redirect with the answer's status and Location and action gone with 410, and sets X-Robots-Tag from seo.x_robots_tag; not_found is left to Nuxt's routing except a pagination.invalid answer, which is a 404 (D-20a, D-103, D-08, D-71, D-42)"
|
||||
- "Normalisation and strict-URL answers (Phase 32) arrive as redirect decisions, so the layer enforces D-20b and D-20c on frontend routes in one hop without re-implementing any rule (D-20b, D-20c)"
|
||||
- "Redirects and 410 apply before Nitro's route cache, so swr-cached pages honour them; the Location always comes from the resolve answer, never from the request (D-20a)"
|
||||
- "Every server-rendered page gets its head from the CMS answer only: title, description, robots, canonical, og:* (including og:locale and og:locale:alternate), twitter:*, verification meta, <html lang>, hreflang links and exactly one <script type=\"application/ld+json\"> holding one @graph (CMS nodes plus nodes the layers add through useSchemaNode, merged by @id); client-side navigation fetches the same answer through /api/__seo__/resolve (D-43, D-55, D-97)"
|
||||
- "Resolve answers are cached in an LRU (path and query as key, TTL seo.resolveCacheTtl default 60 s, 1000 entries); the shared site-cache purge route POST /api/__site__/cache/purge (moved here from the journal, menu and FAQ layers unchanged in contract) also clears the resolve and site caches (RESEARCH Pitfall 6, 33-CONTEXT discretion: purge with D-97)"
|
||||
- "The layer serves the site-root files from the CMS: /robots.txt, /sitemap.xml, /sitemap-<name>.xml, /llms.txt, each verification file and the IndexNow key file listed in the site answer's root_files, proxied to the Go backend with their status, content type and X-Robots-Tag; any other one-segment path passes through (D-05, D-103, D-22, D-25, D-31)"
|
||||
- "A page that renders as 404 reports itself once to POST /_seo/api/v1/notfound with the bearer token runtimeConfig.seo.notfoundToken, its URL and the referer, without delaying the response (D-20)"
|
||||
- "With the CMS unreachable or no SEO plugin mounted, pages render normally without CMS head tags (fail open); seo.cms false turns every CMS call off for sites without the SEO plugin"
|
||||
- "useSeoLabels() returns the L8 dictionary of the page's content locale (resolve locale, then html_lang's primary subtag, then en), overridable in app.config.ts under seo.labels; the layer has no @nuxtjs/i18n dependency (UI-SPEC L8)"
|
||||
- "seo-tokens.css and seo-base.css load before the app's CSS and style only .seo-* classes (UI-SPEC L8, Spacing, Color)"
|
||||
- "Public layer components render on the server only: the data is fetched before render, so there is no client loading state (UI-SPEC loading: public layer components)"
|
||||
- {statement: "Two concurrent requests for the same uncached path make one resolve call (in-flight de-duplication), and a purge during a request never serves a stale answer afterwards", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-20a"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "The middleware never builds a redirect Location from request input (Host, path or query); it only forwards the resolver's absolute location"
|
||||
- requirement_id: "D-97"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "The layer never emits a second JSON-LD script or a second canonical link"
|
||||
artifacts:
|
||||
- path: "../vue-seo-layer/server/middleware/seo.ts"
|
||||
provides: "resolve, redirect/410, X-Robots-Tag, event.context.seo"
|
||||
contains: "sendRedirect"
|
||||
- path: "../vue-seo-layer/app/composables/useCmsSeo.ts"
|
||||
provides: "head rendering from the resolve answer"
|
||||
contains: "application/ld+json"
|
||||
- path: "../vue-seo-layer/server/middleware/seo-root.ts"
|
||||
provides: "root file proxies"
|
||||
contains: "robots.txt"
|
||||
- path: "../vue-seo-layer/testing/expect-seo.txt"
|
||||
provides: "SSR smoke expectations"
|
||||
contains: "count="
|
||||
key_links:
|
||||
- from: "../vue-seo-layer/server/middleware/seo.ts"
|
||||
to: "../vue-seo-layer/server/lib/resolve.ts"
|
||||
via: "resolveCached(event, path) with LRU and X-Forwarded-For"
|
||||
pattern: "resolveCached"
|
||||
- from: "../vue-seo-layer/app/plugins/seo-head.ts"
|
||||
to: "../vue-seo-layer/app/composables/useCmsSeo.ts"
|
||||
via: "the app plugin applies useCmsSeo on every route from event.context.seo (SSR) or /api/__seo__/resolve (client)"
|
||||
pattern: "useCmsSeo"
|
||||
- from: "../vue-seo-layer/server/api/__site__/cache/purge.post.ts"
|
||||
to: "../vue-seo-layer/server/lib/resolve.ts"
|
||||
via: "purge clears nitro:routes and the resolve and site LRUs"
|
||||
pattern: "clear"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: @nuxtjs/seo -->
|
||||
<!-- planner-discipline-allow: nuxt-schema-org -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan creates the shared Nuxt SEO layer (D-97) and its runtime: every page's head comes from the CMS resolve answer, redirects and 410 are enforced before the page cache, root files are served from the CMS, and 404s are reported.
|
||||
|
||||
<objective>
|
||||
Create the layer repository locally (the remote is created with `tea` in 33-14, behind the release checkpoint) and build its runtime against a fixture API:
|
||||
- Nitro middleware for the redirect decision, X-Robots-Tag and the resolve context (D-20a, D-103, D-08);
|
||||
- head rendering with one JSON-LD script and hreflang from the CMS (D-43, D-55);
|
||||
- the resolve LRU and the shared site-cache purge route moved here (Pitfall 6);
|
||||
- root-file proxies (robots.txt, sitemaps, llms.txt, verification files, IndexNow key; D-05, D-103);
|
||||
- the 404 report call (D-20); labels and tokens (UI-SPEC L8).
|
||||
|
||||
Purpose: SC-2 (indexable pages render server-side with head tags and one JSON-LD @graph from the CMS); the build guard and components are 33-08.
|
||||
|
||||
Output: commits in ../vue-seo-layer (a new local repository, branch main, not pushed).
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-26 (contract the fixtures follow):** the resolve answer is Phase 32's (action, status, location, url, locale, staging, seo{title, description, canonical, robots, x_robots_tag, og{title, description, image, url, locale, locale_alternates}, twitter{card, site}, verification[{name, content}]}) plus 33-05's `outbound` and 33-06's `html_lang`, `alternates[{hreflang, url}]`, `jsonld`, `breadcrumbs[{name, url, path}]`, `pagination{form, param, segment, page, invalid}` and 33-11's `autolinks[{phrase, url}]`, `autolink_max`; the site answer is 33-05's P33-17 plus 33-06's `pagination{form, param, segments}` and `home_crumb`. Absent keys are treated as empty. The fixture files hold exactly these shapes; 33-06-SUMMARY.md carries a real answer to compare in 33-12.
|
||||
- **P33-27 (runtime config):** server-only `runtimeConfig.seo.apiBase` (NUXT_SEO_API_BASE, default http://127.0.0.1:8096/_seo/api/v1), `backendBase` (NUXT_SEO_BACKEND_BASE, default http://127.0.0.1:8096), `notfoundToken` (NUXT_SEO_NOTFOUND_TOKEN), `routeReportToken` (NUXT_SEO_ROUTE_REPORT_TOKEN, falls back to notfoundToken), `resolveCacheTtl` (seconds, default 60); `cachePurge.token`, `cachePurge.allowProxied` and the deprecated `siteCache` keys move here from the journal layer's config unchanged; module options (configKey `seo`): `cms` (default true), `breadcrumbs` (true), `links.newTabHint` (true), `rootFiles` (true), `resolveFiles` (['pdf']), plus the 33-08 options.
|
||||
- **P33-28 (one head owner):** a single app plugin applies the head on every route; pages and other layers never call useSeoMeta for CMS values. useSchemaNode(node) registers a request-scoped node merged into the one graph by @id.
|
||||
- **P33-29 (smoke harness):** testing/smoke-ssr.mjs is copied from vue-journal-layer and gains `count=TEXT:N` (exactly N occurrences in the body; the count is the number after the last colon) and `header=Name:Value` (response header equals) assertions, and lets `contains=`, `notcontains=`, `count=` and `header=` repeat on one line (every occurrence applies; today a repeated key overwrites the earlier one); the fixture API serves /_seo/api/v1/resolve answers keyed by path from testing/fixtures/seo/resolve.json, /_seo/api/v1/site, records /_seo/api/v1/notfound calls and resolve hit counts, and serves the root files.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
Templates to copy: ../vue-journal-layer/{.gitignore, .nvmrc, package.json (scripts dev, build:playground, test, dev:prepare), pnpm-workspace.yaml, tsconfig.json, nuxt.config.ts (currentDir pattern, runtimeConfig cachePurge/siteCache, routeRules cache false), lib/journal-module.ts (defineNuxtModule, configKey, defaults, runtimeConfig.public copy), server/api/__site__/cache/purge.post.ts, server/lib/siteCachePurge.ts, server/plugins/site-cache-purge.ts, server/plugins/journal-client-address.ts (X-Forwarded-For forwarding), testing/{smoke-ssr.mjs, fixture-api.mjs, nuxt-server.mjs, purge-check.mjs, purge-token-check.mjs}, tests/sitePurge.test.ts, .playground/}.
|
||||
Nuxt 4.4.8 / Nitro 2.13.4 / h3 1.15.11 / unhead 2.1.17 (pinned through nuxt): useHead, useSeoMeta, defineEventHandler, sendRedirect, setResponseHeader, createError, useRequestEvent, defineNuxtPlugin, useState, $fetch; unhead escapes "<" in JSON script innerHTML.
|
||||
Seo API (Go): GET /_seo/api/v1/resolve?url= (200 for ok and not_found, X-Robots-Tag noindex), GET /_seo/api/v1/site, POST /_seo/api/v1/notfound {url, referer} with Authorization Bearer; GET /_seo/api/v1/verification/{name}; Go root routes /robots.txt, /llms.txt, /sitemap.xml; /_sitemap/files/{file}; /_sitemap/indexnow/{file}.
|
||||
Copy: UI-SPEC L8 dictionary (en, pl) and the seo-tokens.css token table.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- The repository is new: Task 2 runs `git init -b main ../vue-seo-layer`. Commit groups staged by path with `git -C ../vue-seo-layer add <paths>`. `pnpm install` (no new package beyond the pins the other layers use) creates pnpm-lock.yaml, committed with package.json. Every commit keeps `npm --prefix ../vue-seo-layer run test` green.
|
||||
- Resume check: `git -C ../vue-seo-layer log --format=%s | grep -Fx '<subject>'` (a missing repository means Task 2 has not run).
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | none (checkpoint answer recorded in the SUMMARY) | answer recorded |
|
||||
| 2 | `feat: CMS head and one JSON-LD graph on every server-rendered page (tracer)` | smoke tracer lines pass |
|
||||
| 3 | A `feat: redirect and 410 enforcement, X-Robots-Tag and the resolve cache`; B `feat: shared site cache purge route clears the SEO caches`; C `feat: root files from the CMS and the 404 report` | expect-seo.txt passes |
|
||||
| 4 | A `feat: SEO labels, tokens and base styles`; B `docs: README` | plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 1: Confirm the shared layer's name before it becomes a repository</name>
|
||||
<reversibility rating="costly">Apps and the journal, menu and FAQ layers pin the layer by its git URL; a later rename means re-pinning every consumer.</reversibility>
|
||||
<decision>D-97 leaves the name to confirm; the repository is created locally now and on git.golem15.com with tea in 33-14.</decision>
|
||||
<context>Every other layer is named vue-<area>-layer (vue-journal-layer, vue-menu-layer, vue-faq-layer, vue-paymentgateway-layer). UI-SPEC and research use vue-seo-layer throughout. Its classes are .seo-*, its config key seo, its CSS tokens --seo-*.</context>
|
||||
<options>
|
||||
<option id="vue-seo-layer">
|
||||
<name>vue-seo-layer</name>
|
||||
<pros>Matches the naming of every other layer and of all phase documents</pros>
|
||||
<cons>None known</cons>
|
||||
</option>
|
||||
<option id="other">
|
||||
<name>Another name (stated in the answer)</name>
|
||||
<pros>Jakub's choice</pros>
|
||||
<cons>Plans 33-08 to 33-14 substitute the name; class and config names stay seo</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "vue-seo-layer" or "other: <name>"</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 2: End-to-end "a page rendered by Nuxt carries the CMS title, canonical, hreflang and one JSON-LD graph from the resolve answer" — one path only</name>
|
||||
<files>../vue-seo-layer/.gitignore, ../vue-seo-layer/.nvmrc, ../vue-seo-layer/package.json, ../vue-seo-layer/pnpm-lock.yaml, ../vue-seo-layer/pnpm-workspace.yaml, ../vue-seo-layer/tsconfig.json, ../vue-seo-layer/nuxt.config.ts, ../vue-seo-layer/lib/seo-module.ts, ../vue-seo-layer/app/plugins/seo-head.ts, ../vue-seo-layer/app/composables/useCmsSeo.ts, ../vue-seo-layer/app/composables/useSchemaNode.ts, ../vue-seo-layer/app/utils/graph.ts, ../vue-seo-layer/app/utils/pagePath.ts, ../vue-seo-layer/app/utils/types.ts, ../vue-seo-layer/server/middleware/seo.ts, ../vue-seo-layer/server/lib/resolve.ts, ../vue-seo-layer/server/api/__seo__/resolve.get.ts, ../vue-seo-layer/.playground/nuxt.config.ts, ../vue-seo-layer/.playground/app/app.vue, ../vue-seo-layer/.playground/app/pages/index.vue, ../vue-seo-layer/.playground/app/pages/[...slug].vue, ../vue-seo-layer/testing/smoke-ssr.mjs, ../vue-seo-layer/testing/fixture-api.mjs, ../vue-seo-layer/testing/nuxt-server.mjs, ../vue-seo-layer/testing/expect-seo.txt, ../vue-seo-layer/testing/fixtures/seo/resolve.json, ../vue-seo-layer/testing/fixtures/seo/site.json, ../vue-seo-layer/tests/graph.test.ts, ../vue-seo-layer/tests/pagePath.test.ts</files>
|
||||
<read_first>
|
||||
- ../vue-journal-layer/nuxt.config.ts, package.json, lib/journal-module.ts, testing/smoke-ssr.mjs, testing/fixture-api.mjs, testing/nuxt-server.mjs, server/plugins/journal-client-address.ts
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pattern 5, Code Examples: layer head, Pitfall 2)
|
||||
- .planning/phases/32-seo-foundation/32-03-SUMMARY.md and 32-04-SUMMARY.md (resolve answer and its 200/not_found behaviour)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-97, D-43, D-55 and P33-26 to P33-29: `git init -b main ../vue-seo-layer` with the name from Task 1; package.json (name, private, type module, main ./nuxt.config.ts, scripts dev, build:playground, test `node --test --test-reporter=tap tests/*.test.ts`, dev:prepare, `smoke:ssr` = `node testing/smoke-ssr.mjs --output .playground/.output --fixtures testing/fixtures --expect testing/expect-seo.txt`; peer and dev nuxt 4.4.8, dev typescript 5.9.3 and vue 3.5.35 as the journal layer pins; no runtime dependency). nuxt.config.ts registers lib/seo-module.ts and the P33-27 runtime config. seo-module.ts (configKey seo) copies its options into runtimeConfig.public.seo. `server/lib/resolve.ts`: `resolveCached(event, path)` fetching `${apiBase}/resolve?url=` with X-Forwarded-For set to the client address (journal-client-address pattern), returns null on any failure or when cms is false. `server/middleware/seo.ts` (Task 2 scope: page-path test with `isPagePath` from app/utils/pagePath.ts, resolve, `event.context.seo = res`). `app/utils/graph.ts`: pure `mergeGraph(cmsJsonld, nodes)` merging by @id. `useCmsSeo(answer)` applies useSeoMeta/useHead per RESEARCH Code Examples with keys canonical, alt-<hreflang> and jsonld, html lang and og:locale/alternate; `app/plugins/seo-head.ts` takes the answer from useRequestEvent().context.seo during SSR (stored in useState for hydration) and from `$fetch('/api/__seo__/resolve', {query: {url}})` on client navigation (`server/api/__seo__/resolve.get.ts` proxies through resolveCached). Playground: pages index and [...slug] rendering an H1; fixture resolve.json with an ok answer for /blog/lwia-grzywa (title, canonical, alternates pl/en/x-default, jsonld with two nodes), and site.json. smoke-ssr.mjs per P33-29; expect-seo.txt tracer lines: `200 /blog/lwia-grzywa contains=<title>Lwia grzywa count=application/ld+json:1 count=rel="canonical":1 contains=hreflang="x-default" contains=<html lang="pl"`. Unit tests graph.test.ts (merge by @id, layer node appended, no duplicate @id) and pagePath.test.ts (/_nuxt/x, /api/x, /favicon.ico skipped; /blog/x and / are pages). Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-seo-layer run test 2>&1 | tail -12</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line in the TAP output</fails_when>
|
||||
<automated>npm --prefix ../vue-seo-layer run build:playground 2>&1 | tail -5 && npm --prefix ../vue-seo-layer run smoke:ssr 2>&1 | tail -15</automated>
|
||||
<fails_when>non-zero exit from the build or the smoke, or a "FAIL" line in the smoke output</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../vue-seo-layer log --oneline | wc -l` is at least 1 and `git -C ../vue-seo-layer remote` prints nothing (no remote yet)
|
||||
- `grep -n '"dependencies"' ../vue-seo-layer/package.json` prints nothing (no runtime dependency)
|
||||
- `grep -n "application/ld+json" ../vue-seo-layer/app/composables/useCmsSeo.ts` prints one line
|
||||
- the smoke tracer line asserts exactly one ld+json script and one canonical and passes
|
||||
</acceptance_criteria>
|
||||
<done>A Nuxt page extending the layer renders its head and one JSON-LD graph from the CMS answer.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Redirect/410/X-Robots-Tag enforcement, the resolve LRU with the moved purge route, root-file proxies and the 404 report</name>
|
||||
<files>../vue-seo-layer/server/middleware/seo.ts, ../vue-seo-layer/server/middleware/seo-root.ts, ../vue-seo-layer/server/lib/resolve.ts, ../vue-seo-layer/server/lib/lru.ts, ../vue-seo-layer/server/lib/site.ts, ../vue-seo-layer/server/lib/siteCachePurge.ts, ../vue-seo-layer/server/api/__site__/cache/purge.post.ts, ../vue-seo-layer/server/plugins/site-cache-purge.ts, ../vue-seo-layer/server/plugins/seo-notfound.ts, ../vue-seo-layer/nuxt.config.ts, ../vue-seo-layer/.playground/nuxt.config.ts, ../vue-seo-layer/testing/fixture-api.mjs, ../vue-seo-layer/testing/purge-check.mjs, ../vue-seo-layer/testing/purge-token-check.mjs, ../vue-seo-layer/testing/expect-seo.txt, ../vue-seo-layer/testing/fixtures/seo/resolve.json, ../vue-seo-layer/testing/fixtures/seo/site.json, ../vue-seo-layer/tests/lru.test.ts, ../vue-seo-layer/tests/sitePurge.test.ts</files>
|
||||
<read_first>
|
||||
- ../vue-journal-layer/server/api/__site__/cache/purge.post.ts, server/lib/siteCachePurge.ts, server/plugins/site-cache-purge.ts, tests/sitePurge.test.ts, testing/purge-check.mjs, testing/purge-token-check.mjs (move unchanged in contract)
|
||||
- ../sm-seo-plugin/controllers/api/notfound.go (report body and token) and classes/verification.go (file name pattern)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pattern 5, Pitfall 6, Security Domain)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- /stary (fixture redirect 301 to https://example.test/nowy) → 301 with exactly that Location; /usuniety (gone) → 410; a page answer with x_robots_tag "noindex, nofollow" → that X-Robots-Tag header; /blog?page=abc (not_found, pagination.invalid) → 404; an unknown path (not_found without invalid) is left to Nuxt
|
||||
- A request with a crafted Host or X-Forwarded-Host never changes the Location
|
||||
- The fixture counts one resolve call for two requests to the same path within the TTL; after POST /api/__site__/cache/purge with the token, the next request resolves again; the purge route keeps its 404/401/proxied rules (purge-check.mjs and purge-token-check.mjs pass unchanged)
|
||||
- Backend down: a page answers 200 without CMS tags (fail open)
|
||||
- /robots.txt, /sitemap.xml, /sitemap-posts-1.xml, /llms.txt, /google1234.html (in root_files) and /<key>.txt (in root_files) are proxied with the backend's status, content type and X-Robots-Tag; /kontakt and /random.txt (not in root_files) pass through to Nuxt; a backend failure on a root file answers 503 with Retry-After 60
|
||||
- A 404 page posts {url, referer} once to the fixture notfound endpoint with the bearer token; an unset token sends nothing
|
||||
- seo.cms false: no resolve, no root proxies, no report
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-20, D-20a, D-103, D-05, D-08, D-22, D-25 and P33-27/P33-29: middleware enforcement (sendRedirect with res.location and res.status; createError 410; setResponseHeader x-robots-tag; 404 only for pagination.invalid), never reading Host for Location. `server/lib/lru.ts`: pure LRU with TTL, max entries and in-flight de-duplication (unit-tested). `server/lib/site.ts`: cached site answer (TTL 300 s). Move the purge route, lib and plugin from vue-journal-layer unchanged in behaviour (keep the header comment's rules) and make the purge also clear the resolve and site LRUs. Copy testing/purge-check.mjs and purge-token-check.mjs and adapt the content change to this layer: instead of a Journal entity (--kind/--slug), purge-check changes the title of the fixture resolve answer for --path in its temporary copy, and the playground's nuxt.config gets `routeRules: {'/**': {swr: 300}}` so pages are route-cached; every other check of both scripts stays. `server/middleware/seo-root.ts`: exact /robots.txt, /sitemap.xml, /llms.txt; regex ^/sitemap-[a-z0-9-]+\.xml$; one-segment names ending .html, .txt or .xml that the site answer lists in root_files; proxied per P33-26 paths with status, content type and X-Robots-Tag copied; off when rootFiles or cms is false. `server/plugins/seo-notfound.ts`: hook after the response is rendered (Nitro `afterResponse` or `render:response`) for status 404 page paths, fire-and-forget POST with the bearer token. Extend the fixture API and expect-seo.txt for each behavior line (header= and count= assertions). Tests first. Commit groups A, B, C.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-seo-layer run test 2>&1 | tail -12</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line</fails_when>
|
||||
<automated>npm --prefix ../vue-seo-layer run build:playground 2>&1 | tail -3 && npm --prefix ../vue-seo-layer run smoke:ssr 2>&1 | tail -25 && node ../vue-seo-layer/testing/purge-check.mjs --output ../vue-seo-layer/.playground/.output --fixtures ../vue-seo-layer/testing/fixtures --path /blog/lwia-grzywa 2>&1 | tail -5 && node ../vue-seo-layer/testing/purge-token-check.mjs --output ../vue-seo-layer/.playground/.output --fixtures ../vue-seo-layer/testing/fixtures --path /blog/lwia-grzywa 2>&1 | tail -3</automated>
|
||||
<fails_when>non-zero exit from any command, a "FAIL" line, or no "purge-check: ok" / "purge-token-check: ok" final line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "sendRedirect" ../vue-seo-layer/server/middleware/seo.ts` prints one line and `grep -n "getRequestHost\|x-forwarded-host" ../vue-seo-layer/server/middleware/seo.ts` prints nothing
|
||||
- `grep -n "header=\|count=" ../vue-seo-layer/testing/expect-seo.txt` prints at least five lines
|
||||
- expect-seo.txt has a line for each behavior bullet's status (301, 410, 404, 503, 200)
|
||||
</acceptance_criteria>
|
||||
<done>The layer enforces the CMS's redirect decision before caching, serves the site's root files from the CMS, reports 404s, and its caches purge with the site.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Label dictionary, tokens and base styles; README</name>
|
||||
<files>../vue-seo-layer/app/app.config.ts, ../vue-seo-layer/app/composables/useSeoLabels.ts, ../vue-seo-layer/app/utils/labels.ts, ../vue-seo-layer/app/assets/css/seo-tokens.css, ../vue-seo-layer/app/assets/css/seo-base.css, ../vue-seo-layer/nuxt.config.ts, ../vue-seo-layer/tests/labels.test.ts, ../vue-seo-layer/README.md</files>
|
||||
<read_first>
|
||||
- ../vue-menu-layer/app/assets/css/menu-tokens.css and ../vue-journal-layer/app/assets/css/journal-tokens.css (token conventions, :root:root overrides)
|
||||
- ../vue-journal-layer/README.md (layer README structure)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (L8, Public layers Spacing, Typography, Color tables, the layer dictionary)
|
||||
</read_first>
|
||||
<action>
|
||||
Per UI-SPEC L8: `app/utils/labels.ts` holds the en and pl dictionaries (every key of the "Public layer dictionary" table, {name} placeholders) and a pure `pickLabels(locale, htmlLang, overrides)`; `useSeoLabels()` reads the resolve answer's locale and app.config `seo.labels`. seo-tokens.css defines every token of the public Spacing and Color tables (--seo-space-1..5, --seo-target-size, --seo-sitemap-column-width, --seo-color-muted, --seo-color-accent, --seo-color-on-accent, --seo-color-border, --seo-font-size-small, --seo-breadcrumbs-separator); seo-base.css styles only .seo-* classes (including .seo-visually-hidden, the standard clip pattern) and no bare element; nuxt.config css order tokens then base. labels.test.ts covers the locale fallback chain and overrides. README in the layer structure: what it does, install (pnpm git dependency pinned by tag), options (P33-27), runtime config and environment variables, the resolve contract (P33-26), root files, purge, 404 report, labels and tokens, testing. Commit groups A and B.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-seo-layer run test 2>&1 | tail -12</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line</fails_when>
|
||||
<automated>grep -c "^\s*\.seo-" ../vue-seo-layer/app/assets/css/seo-base.css</automated>
|
||||
<fails_when>output 0 or a missing file</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "\-\-seo-target-size\|\-\-seo-space-5" ../vue-seo-layer/app/assets/css/seo-tokens.css` prints two lines
|
||||
- `grep -En "^\s*(a|h1|h2|body|nav|ol|li)\s*[{,]" ../vue-seo-layer/app/assets/css/seo-base.css` prints nothing (no bare-element rule)
|
||||
- `grep -n "i18n" ../vue-seo-layer/package.json ../vue-seo-layer/nuxt.config.ts` prints nothing
|
||||
</acceptance_criteria>
|
||||
<done>The layer has its dictionary, tokens, base styles and documentation.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| visitor → Nitro middleware | untrusted path, query and headers |
|
||||
| Nitro → Go SEO API | internal HTTP with forwarded client address |
|
||||
| Go backend → purge route | bearer-token POST |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-29 | Spoofing (open redirect) | redirect enforcement | high | mitigate | Location only from the resolver's absolute answer (Phase 32 guarantees site-host targets unless an editor set an external target); no request header used; smoke line with a crafted Host |
|
||||
| T-33-30 | Tampering (XSS) | JSON-LD script | high | mitigate | innerHTML through unhead, which escapes < in JSON scripts; the graph is JSON from the server, never concatenated markup |
|
||||
| T-33-31 | Denial of service | resolve per request | medium | mitigate | LRU with TTL and in-flight de-duplication; X-Forwarded-For forwarded so the Go per-IP bucket applies per visitor |
|
||||
| T-33-32 | Elevation of privilege (SSRF) | root-file proxy | high | mitigate | proxy targets are fixed backendBase/apiBase paths; only allow-listed names (regex and the site answer's root_files) are forwarded, never a user-supplied URL |
|
||||
| T-33-33 | Spoofing | purge route | medium | mitigate | moved unchanged: 32+ character bearer token, proxied requests refused unless allowProxied; purge-check.mjs and purge-token-check.mjs |
|
||||
| T-33-34 | Information disclosure | runtime config | medium | mitigate | tokens and apiBase live in server-only runtimeConfig, never under public (the payload test of purge-token-check.mjs) |
|
||||
| T-33-SC | Tampering | npm installs | high | mitigate | no new package: package.json pins only nuxt 4.4.8, vue 3.5.35 and typescript 5.9.3, the versions the existing layers already use; pnpm-lock.yaml committed |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `npm --prefix ../vue-seo-layer run test` green after every commit.
|
||||
- `npm --prefix ../vue-seo-layer run build:playground` and `npm --prefix ../vue-seo-layer run smoke:ssr` pass; purge-check.mjs passes.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- The layer repository exists locally with the runtime: head from the CMS, one JSON-LD graph, redirect/410/X-Robots-Tag enforcement, root files, 404 reports, purge, labels and tokens.
|
||||
- No push; the remote is created in 33-14.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Repository `../vue-seo-layer` (local, branch main).
|
||||
- Module: `lib/seo-module.ts` (configKey `seo`; options `cms`, `breadcrumbs`, `links.newTabHint`, `rootFiles`, `resolveFiles`).
|
||||
- Runtime config: `seo.apiBase`, `seo.backendBase`, `seo.notfoundToken`, `seo.routeReportToken`, `seo.resolveCacheTtl`, `cachePurge.token`, `cachePurge.allowProxied`, `siteCache.purgeToken`, `siteCache.allowProxied`; env `NUXT_SEO_API_BASE`, `NUXT_SEO_BACKEND_BASE`, `NUXT_SEO_NOTFOUND_TOKEN`, `NUXT_SEO_ROUTE_REPORT_TOKEN`.
|
||||
- Composables and utils: `useCmsSeo`, `useSchemaNode`, `useSeoLabels`, `mergeGraph`, `isPagePath`, `pickLabels`.
|
||||
- Server: middleware `seo.ts`, `seo-root.ts`; libs `resolve.ts` (`resolveCached`), `lru.ts`, `site.ts`, `siteCachePurge.ts`; routes `GET /api/__seo__/resolve`, `POST /api/__site__/cache/purge`; plugins `site-cache-purge.ts`, `seo-notfound.ts`.
|
||||
- CSS: `seo-tokens.css`, `seo-base.css` (`.seo-visually-hidden`).
|
||||
- Testing: `testing/smoke-ssr.mjs` with `count=` and `header=`, fixture API, `testing/expect-seo.txt`, unit tests `graph`, `pagePath`, `lru`, `labels`, `sitePurge`.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-07-SUMMARY.md` when done; record the confirmed layer name at the top.
|
||||
</output>
|
||||
307
.planning/phases/33-seo-output-audit-and-content/33-08-PLAN.md
Normal file
307
.planning/phases/33-seo-output-audit-and-content/33-08-PLAN.md
Normal file
@@ -0,0 +1,307 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 08
|
||||
type: execute
|
||||
wave: 2
|
||||
depends_on: ["33-07"]
|
||||
files_modified:
|
||||
- ../vue-seo-layer/lib/seo-module.ts
|
||||
- ../vue-seo-layer/lib/guard.ts
|
||||
- ../vue-seo-layer/lib/routes.ts
|
||||
- ../vue-seo-layer/nuxt.config.ts
|
||||
- ../vue-seo-layer/app/plugins/seo-route-robots.ts
|
||||
- ../vue-seo-layer/app/components/Seo/Breadcrumbs.vue
|
||||
- ../vue-seo-layer/app/components/Seo/Pagination.vue
|
||||
- ../vue-seo-layer/app/components/Seo/SitemapLink.vue
|
||||
- ../vue-seo-layer/app/components/global/SeoHtmlSitemapPage.vue
|
||||
- ../vue-seo-layer/app/seo-pages/SitemapPage.vue
|
||||
- ../vue-seo-layer/app/seo-pages/SitemapGroupPage.vue
|
||||
- ../vue-seo-layer/app/composables/usePagination.ts
|
||||
- ../vue-seo-layer/app/composables/useSeoSite.ts
|
||||
- ../vue-seo-layer/app/utils/paginationWindow.ts
|
||||
- ../vue-seo-layer/app/utils/pageHref.ts
|
||||
- ../vue-seo-layer/app/utils/breadcrumbClaim.ts
|
||||
- ../vue-seo-layer/app/assets/css/seo-base.css
|
||||
- ../vue-seo-layer/server/api/__seo__/sitemap.get.ts
|
||||
- ../vue-seo-layer/server/api/__seo__/site.get.ts
|
||||
- ../vue-seo-layer/server/plugins/seo-route-report.ts
|
||||
- ../vue-seo-layer/server/plugins/seo-drift.ts
|
||||
- ../vue-seo-layer/.playground/nuxt.config.ts
|
||||
- ../vue-seo-layer/.playground/app/pages/blog/index.vue
|
||||
- ../vue-seo-layer/.playground/app/pages/konto.vue
|
||||
- ../vue-seo-layer/testing/fixture-api.mjs
|
||||
- ../vue-seo-layer/testing/expect-seo.txt
|
||||
- ../vue-seo-layer/testing/fixtures/seo/resolve.json
|
||||
- ../vue-seo-layer/testing/fixtures/seo/site.json
|
||||
- ../vue-seo-layer/testing/fixtures/seo/html.json
|
||||
- ../vue-seo-layer/testing/guard-check.mjs
|
||||
- ../vue-seo-layer/testing/guard/indexable-ssr-false/nuxt.config.ts
|
||||
- ../vue-seo-layer/testing/guard/noindex-ok/nuxt.config.ts
|
||||
- ../vue-seo-layer/testing/guard/client-page/nuxt.config.ts
|
||||
- ../vue-seo-layer/testing/guard/client-page/app/pages/panel.client.vue
|
||||
- ../vue-seo-layer/testing/guard/global-ssr-false/nuxt.config.ts
|
||||
- ../vue-seo-layer/package.json
|
||||
- ../vue-seo-layer/tests/guard.test.ts
|
||||
- ../vue-seo-layer/tests/paginationWindow.test.ts
|
||||
- ../vue-seo-layer/tests/pageHref.test.ts
|
||||
- ../vue-seo-layer/tests/breadcrumbClaim.test.ts
|
||||
- ../vue-seo-layer/README.md
|
||||
autonomous: true
|
||||
requirements: [SC-2, D-70, D-23, D-21, D-33, D-20c, D-86, D-40, D-41, D-42, D-71, D-34, D-97]
|
||||
|
||||
estimate:
|
||||
tokens: 140000
|
||||
raw_tokens: 140000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "nuxt build fails with \"[vue-seo-layer] indexable routes must render on the server (D-70): <routes>\" when a route rule sets ssr: false, a page is a .client.vue page, or the app sets ssr: false, unless the route is declared in seo.noindexRoutes (or the app sets seo.indexable: false); rules from nuxt.options.routeRules, nitro routeRules and every layer are checked after the layers merge, and experimental.inlineRouteRules is refused (D-70, RESEARCH Pattern 6, Pitfall 10)"
|
||||
- "A route in seo.noindexRoutes gets X-Robots-Tag: noindex, nofollow through its route rule and a robots noindex,nofollow meta; a page whose meta sets requiresAuth: true or seo.robots gets the same automatically without page code, which is how apps mark signed-in and auth pages (no user-plugin layer exists; RESEARCH Open Question 10) (D-23, D-21, D-08)"
|
||||
- "At server start the layer reports its static routes (paths without parameters, outside noindexRoutes) to POST /_seo/api/v1/registry/routes with the route-report token, once per process with one retry after 60 s, so no frontend page is missing from the registry (D-33)"
|
||||
- "At server start the layer compares the CMS's content-type URL patterns, pagination form and segments and HTML-sitemap paths (from /_seo/api/v1/site) with its build-time routes and options, and logs one warning per mismatch (D-20c drift check, RESEARCH Open Question 9)"
|
||||
- "<SeoBreadcrumbs> renders the resolve answer's breadcrumbs as nav > ol with server-rendered <a href> links and the last item as aria-current=\"page\" text, separators CSS-generated; it renders nothing with fewer than two items, when page meta sets seo.breadcrumbs false or when the option seo.breadcrumbs is false; only the first instance per request renders (D-86, D-71, UI-SPEC L1)"
|
||||
- "<SeoPagination> with usePagination() renders numbered server-rendered links in the CMS-chosen form (query or path, per-locale segment), keeps other query parameters, maps page 1 to the unnumbered URL, shows five pages around the current one plus page 1 and the last page with gap items, omits previous/next at the ends, adds <link rel=prev/next> to the head and replaces %pages% in the CMS title and description; it renders nothing when last ≤ 1 (D-40, D-41, D-42, D-71, UI-SPEC L2)"
|
||||
- "The HTML sitemap is served at each locale's html_path (defaults /mapa-strony pl, /sitemap en) with group pages at <html_path>/<group>; it lists the sitemap plugin's HTML groups (an H1 page title, an H2 per group, categories nested, large groups linking to their paginated group page), answers 404 for an unknown group or a page past the last, and a failed API call answers 503 so no empty page is cached (D-34, UI-SPEC L3)"
|
||||
- "<SeoSitemapLink> renders the footer link to the locale's HTML sitemap only when the HTML sitemap is enabled (D-34, UI-SPEC L4)"
|
||||
- "The HTML sitemap overview omits empty groups and shows sitemap.empty when every group is empty (UI-SPEC empty: HTML sitemap)"
|
||||
- "Breadcrumbs render nothing on the home page and pagination renders nothing with one page (UI-SPEC empty: breadcrumbs, pagination)"
|
||||
- "An HTML-sitemap API failure answers 503 through createError, never an empty cached page (UI-SPEC error: HTML sitemap API down)"
|
||||
- "Long breadcrumb names and sitemap titles wrap (overflow-wrap anywhere) and are never truncated; the full text stays in the HTML (UI-SPEC long-text: public)"
|
||||
- "A group larger than html_page_size shows its first page plus the sitemap.all link on the overview, and its group page is paginated with <SeoPagination> (UI-SPEC zero-one-many: large HTML sitemap groups)"
|
||||
- {statement: "Pagination window: current=5, last=14 yields 1 … 3 4 5 6 7 … 14; current=1, last=3 yields 1 2 3 with no gap; the page 1 href has no number in both forms (UI-SPEC L2 backstop)", verification: backstop}
|
||||
- {statement: "A layout instance plus a page instance of <SeoBreadcrumbs> render exactly one nav.seo-breadcrumbs; the last item has aria-current=\"page\" and no link (UI-SPEC L1 backstop)", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-70"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "The build guard cannot be passed by moving ssr: false into a layer, nitro routeRules or a .client.vue page; only an explicit noindex declaration lets a client-only route build"
|
||||
- requirement_id: "D-23"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: judgment
|
||||
statement: "No route is marked noindex unless the app declared it (noindexRoutes) or its page meta asks for it; the layer never noindexes indexable pages by default"
|
||||
artifacts:
|
||||
- path: "../vue-seo-layer/lib/guard.ts"
|
||||
provides: "pure build-guard checks (isNoindex, offenders)"
|
||||
contains: "D-70"
|
||||
- path: "../vue-seo-layer/testing/guard-check.mjs"
|
||||
provides: "fixture builds expecting exit 1/0"
|
||||
contains: "indexable-ssr-false"
|
||||
- path: "../vue-seo-layer/app/components/Seo/Pagination.vue"
|
||||
provides: "L2"
|
||||
contains: "rel"
|
||||
- path: "../vue-seo-layer/app/components/Seo/Breadcrumbs.vue"
|
||||
provides: "L1"
|
||||
contains: "aria-current"
|
||||
key_links:
|
||||
- from: "../vue-seo-layer/lib/seo-module.ts"
|
||||
to: "../vue-seo-layer/lib/guard.ts"
|
||||
via: "nuxt.hook('pages:resolved') collects pages; nuxt.hook('nitro:config') merges route rules and throws on offenders"
|
||||
pattern: "nitro:config"
|
||||
- from: "../vue-seo-layer/server/plugins/seo-route-report.ts"
|
||||
to: "sm-seo-plugin POST /_seo/api/v1/registry/routes"
|
||||
via: "the build-time static route list posted with the route-report token"
|
||||
pattern: "registry/routes"
|
||||
- from: "../vue-seo-layer/app/composables/usePagination.ts"
|
||||
to: "../vue-seo-layer/app/utils/pageHref.ts"
|
||||
via: "hrefs in the site answer's pagination form"
|
||||
pattern: "pageHref"
|
||||
---
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan gives the shared layer the SSR build guard, automatic noindex for declared and signed-in routes, the route report and drift check, and the public components: breadcrumbs, pagination, the HTML sitemap page and its footer link.
|
||||
|
||||
<objective>
|
||||
Extend ../vue-seo-layer (after 33-07; main, not pushed):
|
||||
- the SSR build guard and its fixture playgrounds (D-70);
|
||||
- noindex for declared routes and pages whose meta requires sign-in (D-23, D-21);
|
||||
- the route report to the registry and the startup drift check (D-33, D-20c);
|
||||
- L1 `<SeoBreadcrumbs>` (D-86), L2 `<SeoPagination>` + `usePagination()` (D-40..42), L3 HTML sitemap pages and L4 `<SeoSitemapLink>` (D-34).
|
||||
|
||||
Purpose: SC-2 ("a build fails when an indexable route has ssr: false"; breadcrumbs and pagination from the CMS).
|
||||
|
||||
Output: commits in ../vue-seo-layer.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-30 (module options added):** `noindexRoutes: string[]` (route-rule patterns such as `/p/**`), `indexable: boolean` (default true), `routeReport: boolean` (default true), `pagination: {form: 'query' | 'path', param: 'page', segments: Record<locale, string>}` (default query, pl strona, en page), `htmlSitemap: {paths: Record<locale, string>} | false` (default pl /mapa-strony, en /sitemap); all copied into runtimeConfig.public.seo; the drift check compares them with the CMS.
|
||||
- **P33-31 (route artefact):** the module writes the static route list and every page route pattern into a server template (`#seo-routes`, addServerTemplate) read by the report and drift plugins; no network call at build time.
|
||||
- **P33-32 (HTML sitemap pages):** registered with extendPages per locale (names `seo-sitemap-<locale>` and `seo-sitemap-group-<locale>`), each page file rendering the global component `SeoHtmlSitemapPage`, which an app overrides by registering its own component of that name; data through `GET /api/__seo__/sitemap?locale=&group=&page=` proxying `/_sitemap/api/v1/html`; group-page breadcrumbs are built in the layer from home_crumb, sitemap.title and the group title, since the resolver does not know group pages.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-07-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
From 33-07: lib/seo-module.ts (configKey seo, runtimeConfig.public.seo), server/lib/resolve.ts resolveCached, server/lib/site.ts (cached /site answer), useCmsSeo, useSeoLabels (L8 keys breadcrumbs.label, pagination.label/previous/next/page, sitemap.title/groupTitle/pageSuffix/all/empty, sitemapLink), testing/smoke-ssr.mjs with count= and header=, fixture API, tokens in seo-tokens.css.
|
||||
Contracts (P33-26): resolve breadcrumbs [{name, url, path}], pagination {form, param, segment, page, invalid}; site pagination {form, param, segments}, home_crumb, html_sitemap {enabled, paths, page_size}, routes [{type, pattern}]; sitemap HTML API overview {groups[{key, slug, title, total, entries[{title, url, children?}], more}]} and group page {group, title, page, pages, entries}.
|
||||
Nuxt hooks: pages:resolved (page.mode === 'client' for .client.vue), nitro:config, extendPages, addServerTemplate (nuxt/kit); routeRules ssr false; experimental.inlineRouteRules.
|
||||
Existing journal pagination for reference: ../vue-journal-layer/app/utils/pagination.ts (paginationWindow) and app/components/Journal/Pagination.vue.
|
||||
Demo app real case: ../sm-demo-app/vue-demo-app/nuxt.config.ts routeRules '/p/**' and '/presentations/**' ssr false (33-12 declares them noindex).
|
||||
Copy: UI-SPEC L1–L4 markup, defaults and the L8 dictionary.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups staged by path with `git -C ../vue-seo-layer add <paths>`; `npm --prefix ../vue-seo-layer run test` green at every commit.
|
||||
- Resume check: `git -C ../vue-seo-layer log --format=%s | grep -Fx '<subject>'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | `feat: the build fails when an indexable route renders only in the browser (tracer)` | guard-check.mjs passes |
|
||||
| 2 | A `feat: noindex for declared and signed-in routes`; B `feat: route report and drift check at server start` | smoke lines for noindex and report pass |
|
||||
| 3 | A `feat: breadcrumbs component`; B `feat: pagination component and composable`; C `feat: HTML sitemap pages and footer link`; D `docs: build guard, noindex routes and components` | plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "an app with an indexable ssr:false route fails its build, and the same route declared noindex builds and is served with X-Robots-Tag" — one path only</name>
|
||||
<files>../vue-seo-layer/lib/seo-module.ts, ../vue-seo-layer/lib/guard.ts, ../vue-seo-layer/testing/guard-check.mjs, ../vue-seo-layer/testing/guard/indexable-ssr-false/nuxt.config.ts, ../vue-seo-layer/testing/guard/noindex-ok/nuxt.config.ts, ../vue-seo-layer/testing/guard/client-page/nuxt.config.ts, ../vue-seo-layer/testing/guard/client-page/app/pages/panel.client.vue, ../vue-seo-layer/testing/guard/global-ssr-false/nuxt.config.ts, ../vue-seo-layer/package.json, ../vue-seo-layer/tests/guard.test.ts</files>
|
||||
<read_first>
|
||||
- ../vue-seo-layer/lib/seo-module.ts and nuxt.config.ts (33-07)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pattern 6, Pitfall 10)
|
||||
- ../sm-demo-app/vue-demo-app/nuxt.config.ts (routeRules with ssr false, the real case)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-70 and P33-30: `lib/guard.ts` (pure, unit-tested): `isNoindex(path, noindexRoutes)` with Nitro route-rule pattern semantics (`/x/**`, `/x/*`, exact), `findOffenders({ssr, indexable, routeRules, pages, noindexRoutes, inlineRouteRules})` returning the offender list (global ssr false; each rule with ssr false not covered; each client-mode page not covered; inlineRouteRules true is itself an offender with a message to remove it). seo-module.ts collects pages in `pages:resolved`, and in `nitro:config` merges `nuxt.options.routeRules` with `nitro.routeRules`, throws `[vue-seo-layer] indexable routes must render on the server (D-70): <list>` when offenders exist, and adds `headers: {'x-robots-tag': 'noindex, nofollow'}` to each noindexRoutes pattern's rule. Fixture apps under testing/guard extend the layer (`extends: ['../../..']`): indexable-ssr-false (`'/x/**': {ssr: false}`), noindex-ok (the same plus `seo: {noindexRoutes: ['/x/**']}`), client-page (`app/pages/panel.client.vue`), global-ssr-false (`ssr: false`). `testing/guard-check.mjs` runs `nuxt build` for each fixture (the layer's node_modules nuxt binary, cwd the fixture), expects exit ≠ 0 and the D-70 message for the three offenders and exit 0 for noindex-ok, then starts noindex-ok's server and expects `X-Robots-Tag: noindex, nofollow` on /x/a; prints `guard-check: ok (<n> checks)` or `guard-check: FAIL ...` and exits 1. package.json script `guard:check`. Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-seo-layer run test 2>&1 | tail -10</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line</fails_when>
|
||||
<automated>npm --prefix ../vue-seo-layer run guard:check 2>&1 | tail -8</automated>
|
||||
<fails_when>non-zero exit, a "guard-check: FAIL" line, or no "guard-check: ok" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "indexable routes must render on the server (D-70)" ../vue-seo-layer/lib/guard.ts ../vue-seo-layer/lib/seo-module.ts` prints at least one line
|
||||
- `grep -n "nitro:config\|pages:resolved" ../vue-seo-layer/lib/seo-module.ts` prints two lines
|
||||
- guard-check.mjs covers four fixtures and the header check
|
||||
</acceptance_criteria>
|
||||
<done>No app on the layer can ship an indexable page that renders only in the browser.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Noindex for declared and signed-in routes, the route report and the startup drift check</name>
|
||||
<files>../vue-seo-layer/lib/seo-module.ts, ../vue-seo-layer/lib/routes.ts, ../vue-seo-layer/app/plugins/seo-route-robots.ts, ../vue-seo-layer/server/plugins/seo-route-report.ts, ../vue-seo-layer/server/plugins/seo-drift.ts, ../vue-seo-layer/server/api/__seo__/site.get.ts, ../vue-seo-layer/app/composables/useSeoSite.ts, ../vue-seo-layer/.playground/nuxt.config.ts, ../vue-seo-layer/.playground/app/pages/konto.vue, ../vue-seo-layer/testing/fixture-api.mjs, ../vue-seo-layer/testing/expect-seo.txt, ../vue-seo-layer/testing/fixtures/seo/site.json, ../vue-seo-layer/tests/guard.test.ts</files>
|
||||
<read_first>
|
||||
- ../vue-seo-layer/server/lib/site.ts and server/plugins/site-cache-purge.ts (33-07 server plugin style)
|
||||
- ../sm-seo-plugin/controllers/api/registry.go (33-05 route report body and token) — or 33-05 P33-20 if not yet built
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Open Questions 9, 10)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- The playground page /konto with definePageMeta({requiresAuth: true}) renders meta robots "noindex, nofollow" and the header X-Robots-Tag noindex, nofollow; a page with seo: {robots: 'noindex, follow'} renders that value; ordinary pages keep the CMS robots
|
||||
- The fixture API receives one POST /_seo/api/v1/registry/routes at server start with the bearer token and the static paths (/ and /blog); /konto (meta requiresAuth) and paths under noindexRoutes are left out; without a token or with routeReport false nothing is sent
|
||||
- With a fixture site answer whose journal-post pattern has no Nuxt route, whose pagination form is path while the build option is query, and whose html path differs, the server log has three "[vue-seo-layer] drift:" warnings and the server still starts
|
||||
- useSeoSite() returns the cached site answer on server and client (proxy /api/__seo__/site)
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-23, D-21, D-33, D-20c and P33-30/P33-31: the module adds `requiresAuth` and `seo` to `nuxt.options.experimental.extraPageMetaExtractionKeys`, so pages:resolved carries those meta keys at build time; `lib/routes.ts` (pure) turns resolved pages into static paths (leaving out pages whose meta has requiresAuth or a noindex seo.robots, and noindexRoutes) and route patterns (`:slug()` and `[...slug]` normalised to `:name`, catch-alls marked); the module writes `#seo-routes` with addServerTemplate. `app/plugins/seo-route-robots.ts`: on every route, if the matched route's meta has requiresAuth true or seo.robots, apply useSeoMeta robots and, during SSR, setResponseHeader x-robots-tag; noindexRoutes matches (isNoindex) get the same meta. `server/plugins/seo-route-report.ts` and `seo-drift.ts` run once after Nitro starts (non-blocking), honour cms and routeReport options and the tokens of P33-27, and log results. `server/api/__seo__/site.get.ts` proxies the cached site answer; `useSeoSite()` wraps useFetch of it with a stable key. Extend fixtures and expect-seo.txt (header and meta lines, the report recorded by the fixture API checked by smoke-ssr through a `report=` expectation or a post-run assertion in fixture-api.mjs). Tests first. Commit groups A and B.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-seo-layer run test 2>&1 | tail -10</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line</fails_when>
|
||||
<automated>npm --prefix ../vue-seo-layer run build:playground 2>&1 | tail -3 && npm --prefix ../vue-seo-layer run smoke:ssr 2>&1 | tail -20</automated>
|
||||
<fails_when>non-zero exit, or a "FAIL" line in the smoke output</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "requiresAuth" ../vue-seo-layer/app/plugins/seo-route-robots.ts` prints at least one line
|
||||
- `grep -n "registry/routes" ../vue-seo-layer/server/plugins/seo-route-report.ts` prints one line
|
||||
- `grep -n "drift:" ../vue-seo-layer/server/plugins/seo-drift.ts` prints at least one line
|
||||
- expect-seo.txt asserts the /konto header and meta
|
||||
</acceptance_criteria>
|
||||
<done>Signed-in and declared routes are noindex without page code, the registry learns the site's pages, and drift between CMS and layer is visible at start.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Breadcrumbs, pagination, the HTML sitemap pages and the footer link</name>
|
||||
<files>../vue-seo-layer/app/components/Seo/Breadcrumbs.vue, ../vue-seo-layer/app/components/Seo/Pagination.vue, ../vue-seo-layer/app/components/Seo/SitemapLink.vue, ../vue-seo-layer/app/components/global/SeoHtmlSitemapPage.vue, ../vue-seo-layer/app/seo-pages/SitemapPage.vue, ../vue-seo-layer/app/seo-pages/SitemapGroupPage.vue, ../vue-seo-layer/app/composables/usePagination.ts, ../vue-seo-layer/app/utils/paginationWindow.ts, ../vue-seo-layer/app/utils/pageHref.ts, ../vue-seo-layer/app/utils/breadcrumbClaim.ts, ../vue-seo-layer/app/assets/css/seo-base.css, ../vue-seo-layer/lib/seo-module.ts, ../vue-seo-layer/server/api/__seo__/sitemap.get.ts, ../vue-seo-layer/.playground/app/pages/blog/index.vue, ../vue-seo-layer/testing/fixture-api.mjs, ../vue-seo-layer/testing/fixtures/seo/html.json, ../vue-seo-layer/testing/fixtures/seo/resolve.json, ../vue-seo-layer/testing/expect-seo.txt, ../vue-seo-layer/tests/paginationWindow.test.ts, ../vue-seo-layer/tests/pageHref.test.ts, ../vue-seo-layer/tests/breadcrumbClaim.test.ts, ../vue-seo-layer/README.md</files>
|
||||
<read_first>
|
||||
- ../vue-journal-layer/app/components/Journal/Pagination.vue and app/utils/pagination.ts (markup, class names, window)
|
||||
- ../vue-seo-layer/app/utils/labels.ts and app/assets/css/seo-tokens.css (33-07)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (L1, L2, L3, L4, Public layers tables, Focal points)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- paginationWindow(5, 14) → [1, gap, 3, 4, 5, 6, 7, gap, 14]; (1, 3) → [1, 2, 3]; (14, 14) → [1, gap, 10, 11, 12, 13, 14]
|
||||
- pageHref('/blog', 1, query) → /blog; ('/blog?sort=new', 3, query) → /blog?sort=new&page=3; ('/blog', 3, path, 'strona') → /blog/strona/3; ('/en/blog', 1, path, 'page') → /en/blog
|
||||
- Smoke: /blog?page=5 with last 14 renders nav.seo-pagination with rel=prev and rel=next anchors, aria-current on 5, the 1 and 14 links, two gap items, head <link rel="prev"> and <link rel="next">, and the title without the literal %pages%; /blog with one page renders no nav.seo-pagination
|
||||
- Smoke: a post page renders exactly one nav.seo-breadcrumbs (layout + page instance) with <a href="/"> first and the last item as span aria-current="page"; the home page renders none
|
||||
- Smoke: /mapa-strony renders H1 "Mapa strony" and one H2 per non-empty group, a group with more=true renders the sitemap.all link; /mapa-strony/posts?page=2 renders the group page with pagination; /mapa-strony/nope → 404; with the fixture API failing → 503; with every group empty → sitemap.empty
|
||||
- SitemapLink renders the locale path only when html_sitemap.enabled
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-86, D-40 to D-42, D-34, D-71 and UI-SPEC L1–L4 (markup, classes, props, defaults, copy) with P33-32: Breadcrumbs.vue (props items, label, hideCurrent; NuxtLink for each crumb's path; the first-instance claim through `breadcrumbClaim.ts`, a request-scoped flag reset on every route change; renders nothing per the L1 rules); Pagination.vue (props current, last, labels, classPrefix default seo-pagination; markup of L2 with aria-labels from labels; hrefs from usePagination); usePagination({current, last}) builds hrefs with pageHref from the site answer's pagination (fallback to the build option), adds head links rel prev/next and replaces %pages% in the CMS title and description; HTML sitemap pages registered by the module from htmlSitemap.paths (P33-32) rendering SeoHtmlSitemapPage, which fetches /api/__seo__/sitemap (server proxy to the sitemap API with 404 passthrough and 503 on failure) and renders L3 markup (H1, section per group with H2, nested ul for categories, sitemap.all link, group page with H1 + pageSuffix on page ≥ 2 and SeoPagination, breadcrumbs from home_crumb, sitemap.title and the group title); SitemapLink.vue per L4. seo-base.css adds the L1, L2 and L3 default styles of UI-SPEC (only .seo-* selectors, tokens only, overflow-wrap anywhere). Fixtures and expect-seo.txt per behavior list; unit tests first. README documents components, props, options and the override of SeoHtmlSitemapPage. Commit groups A to D.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-seo-layer run test 2>&1 | tail -10</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line</fails_when>
|
||||
<automated>npm --prefix ../vue-seo-layer run build:playground 2>&1 | tail -3 && npm --prefix ../vue-seo-layer run smoke:ssr 2>&1 | tail -30 && npm --prefix ../vue-seo-layer run guard:check 2>&1 | tail -3</automated>
|
||||
<fails_when>non-zero exit from any command, or a "FAIL" line in the output</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "aria-current" ../vue-seo-layer/app/components/Seo/Breadcrumbs.vue ../vue-seo-layer/app/components/Seo/Pagination.vue` prints a line in each
|
||||
- `grep -n "ClientOnly\|onMounted" ../vue-seo-layer/app/components/Seo/*.vue ../vue-seo-layer/app/components/global/*.vue ../vue-seo-layer/app/seo-pages/*.vue` prints nothing (server-rendered only, UI-SPEC L8)
|
||||
- `grep -n "count=nav class=\"seo-breadcrumbs\|count=<nav class=\"seo-breadcrumbs" ../vue-seo-layer/testing/expect-seo.txt` prints at least one line (exactly-one assertion)
|
||||
- unit tests cover every behavior example of paginationWindow and pageHref
|
||||
</acceptance_criteria>
|
||||
<done>Sites get server-rendered breadcrumbs, pagination and an HTML sitemap from the CMS, with the D-71 link rules.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| app config → build guard | build-time configuration |
|
||||
| frontend server → registry and site endpoints | token-authenticated and public calls |
|
||||
| visitor query → pagination hrefs | page numbers and other query parameters echoed into links |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-35 | Tampering (XSS) | pagination and breadcrumbs hrefs | medium | mitigate | hrefs built with URL/URLSearchParams and rendered through Vue bindings (escaped), never v-html; breadcrumb names from the CMS rendered as text |
|
||||
| T-33-36 | Spoofing | route report token | medium | mitigate | token only in server-only runtime config; sent only to the configured apiBase |
|
||||
| T-33-37 | Repudiation/Integrity | build guard bypass | medium | mitigate | rules checked after layer merge from both sources plus client pages; inline route rules refused; guard-check fixtures |
|
||||
| T-33-38 | Denial of service | HTML sitemap proxy | low | mitigate | page size capped by the sitemap API; 503 on failure prevents caching an empty page |
|
||||
| T-33-SC | Tampering | npm installs | high | accept | no new package |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `npm --prefix ../vue-seo-layer run test`, `build:playground`, `smoke:ssr` and `guard:check` pass.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- The build guard fails indexable client-only routes and passes declared noindex ones.
|
||||
- Declared and signed-in routes are noindex automatically; routes are reported and drift is logged.
|
||||
- Breadcrumbs, pagination and the HTML sitemap render server-side from the CMS.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Module options: `noindexRoutes`, `indexable`, `routeReport`, `pagination` (`form`, `param`, `segments`), `htmlSitemap` (`paths`).
|
||||
- Libs: `lib/guard.ts` (`isNoindex`, `findOffenders`), `lib/routes.ts`; server template `#seo-routes`.
|
||||
- Components: `<SeoBreadcrumbs>`, `<SeoPagination>`, `<SeoSitemapLink>`, global `SeoHtmlSitemapPage`; pages `seo-sitemap-<locale>`, `seo-sitemap-group-<locale>`.
|
||||
- Composables and utils: `usePagination`, `useSeoSite`, `paginationWindow`, `pageHref`, `breadcrumbClaim`.
|
||||
- Server: `GET /api/__seo__/sitemap`, `GET /api/__seo__/site`; plugins `seo-route-report.ts`, `seo-drift.ts`; app plugin `seo-route-robots.ts`.
|
||||
- Page meta keys honoured: `requiresAuth`, `seo.robots`, `seo.breadcrumbs`.
|
||||
- Scripts: `guard:check` (`testing/guard-check.mjs`) and the fixtures under `testing/guard/`.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-08-SUMMARY.md` when done.
|
||||
</output>
|
||||
327
.planning/phases/33-seo-output-audit-and-content/33-09-PLAN.md
Normal file
327
.planning/phases/33-seo-output-audit-and-content/33-09-PLAN.md
Normal file
@@ -0,0 +1,327 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 09
|
||||
type: execute
|
||||
wave: 3
|
||||
depends_on: ["33-08", "33-02"]
|
||||
files_modified:
|
||||
- ../vue-seo-layer/app/utils/bodyLinks.ts
|
||||
- ../vue-seo-layer/tests/bodyLinks.test.ts
|
||||
- ../vue-seo-layer/README.md
|
||||
- ../vue-journal-layer/package.json
|
||||
- ../vue-journal-layer/pnpm-lock.yaml
|
||||
- ../vue-journal-layer/nuxt.config.ts
|
||||
- ../vue-journal-layer/lib/journal-module.ts
|
||||
- ../vue-journal-layer/app/utils/types.ts
|
||||
- ../vue-journal-layer/app/utils/routes.ts
|
||||
- ../vue-journal-layer/app/utils/seo.ts
|
||||
- ../vue-journal-layer/app/utils/htmlGate.ts
|
||||
- ../vue-journal-layer/app/utils/sitemap.ts
|
||||
- ../vue-journal-layer/app/components/Journal/PostCard.vue
|
||||
- ../vue-journal-layer/app/components/Journal/PostBody.vue
|
||||
- ../vue-journal-layer/app/components/Journal/Pagination.vue
|
||||
- ../vue-journal-layer/app/components/Journal/CategoryHeader.vue
|
||||
- ../vue-journal-layer/app/components/Journal/RelatedPosts.vue
|
||||
- ../vue-journal-layer/app/components/Journal/FeaturedImage.vue
|
||||
- ../vue-journal-layer/app/journal-pages/PostPage.vue
|
||||
- ../vue-journal-layer/app/journal-pages/PostIndexPage.vue
|
||||
- ../vue-journal-layer/app/journal-pages/CategoryPage.vue
|
||||
- ../vue-journal-layer/app/journal-pages/TagPage.vue
|
||||
- ../vue-journal-layer/app/journal-pages/AuthorPage.vue
|
||||
- ../vue-journal-layer/app/assets/css/journal-tokens.css
|
||||
- ../vue-journal-layer/app/assets/css/journal-base.css
|
||||
- ../vue-journal-layer/server/api/__journal__/cache/purge.post.ts
|
||||
- ../vue-journal-layer/server/api/__site__/cache/purge.post.ts
|
||||
- ../vue-journal-layer/server/lib/siteCachePurge.ts
|
||||
- ../vue-journal-layer/server/plugins/site-cache-purge.ts
|
||||
- ../vue-journal-layer/server/api/__sitemap__/journal.ts
|
||||
- ../vue-journal-layer/tests/seo.test.ts
|
||||
- ../vue-journal-layer/tests/sitemap.test.ts
|
||||
- ../vue-journal-layer/tests/sitePurge.test.ts
|
||||
- ../vue-journal-layer/tests/htmlGate.test.ts
|
||||
- ../vue-journal-layer/tests/routes.test.ts
|
||||
- ../vue-journal-layer/testing/smoke-ssr.mjs
|
||||
- ../vue-journal-layer/testing/fixture-api.mjs
|
||||
- ../vue-journal-layer/testing/expect-acme.txt
|
||||
- ../vue-journal-layer/testing/expect-acme-title-h1.txt
|
||||
- ../vue-journal-layer/testing/fixtures/acme/posts.json
|
||||
- ../vue-journal-layer/testing/fixtures/acme/seo/resolve.json
|
||||
- ../vue-journal-layer/testing/fixtures/acme/seo/site.json
|
||||
- ../vue-journal-layer/README.md
|
||||
- ../vue-menu-layer/package.json
|
||||
- ../vue-menu-layer/pnpm-lock.yaml
|
||||
- ../vue-menu-layer/nuxt.config.ts
|
||||
- ../vue-menu-layer/server/api/__site__/cache/purge.post.ts
|
||||
- ../vue-menu-layer/server/lib/siteCachePurge.ts
|
||||
- ../vue-menu-layer/server/plugins/site-cache-purge.ts
|
||||
- ../vue-menu-layer/tests/sitePurge.test.ts
|
||||
- ../vue-menu-layer/README.md
|
||||
- ../vue-faq-layer/package.json
|
||||
- ../vue-faq-layer/pnpm-lock.yaml
|
||||
- ../vue-faq-layer/nuxt.config.ts
|
||||
- ../vue-faq-layer/app/components/Faq/Block.vue
|
||||
- ../vue-faq-layer/app/utils/faqSchema.ts
|
||||
- ../vue-faq-layer/server/api/__site__/cache/purge.post.ts
|
||||
- ../vue-faq-layer/server/lib/siteCachePurge.ts
|
||||
- ../vue-faq-layer/server/plugins/site-cache-purge.ts
|
||||
- ../vue-faq-layer/tests/sitePurge.test.ts
|
||||
- ../vue-faq-layer/tests/faqSchema.test.ts
|
||||
- ../vue-faq-layer/testing/expect.txt
|
||||
- ../vue-faq-layer/README.md
|
||||
autonomous: true
|
||||
requirements: [SC-2, D-97, D-50, D-52, D-80, D-81, D-82, D-83, D-71, D-86, D-40, D-41, D-43]
|
||||
|
||||
estimate:
|
||||
tokens: 170000
|
||||
raw_tokens: 170000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "vue-journal-layer, vue-menu-layer and vue-faq-layer extend the shared SEO layer; the journal layer no longer uses @nuxtjs/seo (no nuxt-schema-org graph, no second canonical, no robots or sitemap module), and its own meta applies only as a fallback when no CMS answer exists (D-97, RESEARCH Pitfall 2)"
|
||||
- "The post page title is an h1 while the Journal API reports content_h1_to_h2 true and a p.journal-post__title (same class, same look through the journal post-title tokens) while it is false; the option journal.postTitleTag ('auto' | 'h1' | 'p', default 'auto') overrides it either way (2026-10-28 layer options: postTitleTag)"
|
||||
- "The journal body gate demotes h1 to h2 only while the Journal API reports content_h1_to_h2 true, read from the API, not from a layer option; while false the body keeps its h1 (2026-10-28 Journal H1 setting, D-50, UI-SPEC L7)"
|
||||
- "Every page of the fixture sites has exactly one <h1 and no skipped heading level: listing headers are h1 (page ≥ 2 keeps the · page suffix), post cards are h2 (h3 inside related posts under their h2), FAQ blocks with headingLevel 0 render a styled <p class=\"faq-block__title\"> for sidebar and footer widgets, menus and breadcrumbs have no headings (D-52, UI-SPEC L6)"
|
||||
- "Each post card has exactly one anchor, the title link: the image is no longer wrapped in a link, the separate read-more link is gone, the whole card stays clickable through a CSS stretched link with a visible focus ring, and post links carry no rel (D-80, D-81, UI-SPEC L5)"
|
||||
- "Body HTML is rendered at SSR in the L7 order: H1 demotion by setting, phrase auto-links from the resolve answer (first occurrence, at most autolink_max per text, whole words, case-insensitive, never inside headings, links, code, pre, figcaption or button, never to the page itself), outbound rules (editor rel kept, nofollow or sponsored added from the domain lists; target=_blank, rel=noopener and the visually hidden new-tab hint only while outbound.new_tab is true), and images with loading=lazy and decoding=async keeping stored dimensions and alt=\"\" (D-82, D-83, D-71, 2026-10-28 layer options: links_new_tab)"
|
||||
- "Journal pages render <SeoBreadcrumbs> at the top of their content by default; journal.breadcrumbs false turns that off for sites whose layout places breadcrumbs, while the BreadcrumbList data is unchanged (D-86, 2026-10-28 layer options: journal.breadcrumbs)"
|
||||
- "JournalPagination renders <SeoPagination class-prefix=\"journal-pagination\"> with the journal's labels, so existing journal-pagination class names and app CSS keep working while links follow the CMS page form (path-form routes are registered when the build option is path); category pillar content renders on page 1 only, the short description on every page (D-40, D-41, D-42, UI-SPEC L2)"
|
||||
- "Listing pages (index, category, tag, author) add an ItemList node #itemlist with their posts through useSchemaNode, and FAQ blocks add a FAQPage node (schema prop, default true), so a page still has exactly one JSON-LD script with one @graph (D-43)"
|
||||
- "The site-cache purge files of the journal, menu and FAQ layers are removed; the one route lives in the SEO layer, and the journal's deprecated /api/__journal__/cache/purge keeps working through the SEO layer's purge library (RESEARCH Pitfall 6)"
|
||||
- "A playground extending journal, menu and FAQ layers renders each page with one resolve call, one canonical and one JSON-LD script"
|
||||
- "Journal breadcrumbs turned off (journal.breadcrumbs false): journal pages render no <SeoBreadcrumbs>, a layout instance renders the trail, JSON-LD unchanged (UI-SPEC partial: Journal breadcrumbs turned off)"
|
||||
- {statement: "Post card: each .journal-post-card contains exactly one <a, the title is h2 (h3 inside related posts) and no journal-post-card__more exists (UI-SPEC L5 backstop)", verification: backstop}
|
||||
- {statement: "Heading convention over the fixture pages: exactly one <h1, no skipped level, FAQ headingLevel 0 renders <p>; the post page in both Journal H1 modes (on: title h1, body h1 demoted; off: title p.journal-post__title, the body's single h1 is the page h1); postTitleTag 'h1' with the setting off gives two <h1 and 'p' with it on gives none, asserted as the documented consequence of the override (UI-SPEC L6 backstop)", verification: backstop}
|
||||
- {statement: "Outbound links with outbound.new_tab false keep their editor rel and domain-list nofollow/sponsored and have no target, no noopener and no .seo-visually-hidden hint; with true they have all three (UI-SPEC L7 backstop)", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-83"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "Internal links never get rel or target from the outbound transform, and auto-links are plain <a href> with no class or rel"
|
||||
- requirement_id: "D-82"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "Auto-linking never injects markup inside an attribute, a heading, an existing link, code, pre, figcaption or button, and never links a page to itself"
|
||||
artifacts:
|
||||
- path: "../vue-seo-layer/app/utils/bodyLinks.ts"
|
||||
provides: "autolink, applyOutbound, imageAttrs (pure)"
|
||||
contains: "export function autolink"
|
||||
- path: "../vue-journal-layer/app/utils/htmlGate.ts"
|
||||
provides: "gate with demoteH1 and the L7 pipeline"
|
||||
contains: "demoteH1"
|
||||
- path: "../vue-journal-layer/app/components/Journal/PostCard.vue"
|
||||
provides: "L5 one anchor, headingLevel"
|
||||
contains: "headingLevel"
|
||||
- path: "../vue-faq-layer/app/utils/faqSchema.ts"
|
||||
provides: "FAQPage node from FAQ items"
|
||||
contains: "FAQPage"
|
||||
key_links:
|
||||
- from: "../vue-journal-layer/app/components/Journal/PostBody.vue"
|
||||
to: "../vue-seo-layer/app/utils/bodyLinks.ts"
|
||||
via: "the gate passes sanitized HTML through autolink and applyOutbound with the resolve answer's autolinks and outbound"
|
||||
pattern: "applyOutbound|autolink"
|
||||
- from: "../vue-journal-layer/app/journal-pages/PostPage.vue"
|
||||
to: "Journal API content_h1_to_h2"
|
||||
via: "titleTag and demoteH1 follow post.content_h1_to_h2 unless postTitleTag overrides the title"
|
||||
pattern: "content_h1_to_h2"
|
||||
- from: "../vue-journal-layer/nuxt.config.ts"
|
||||
to: "../vue-seo-layer/nuxt.config.ts"
|
||||
via: "extends: ['vue-seo-layer']"
|
||||
pattern: "vue-seo-layer"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: @nuxtjs/seo -->
|
||||
<!-- planner-discipline-allow: journal-post-card__more -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan moves the journal, menu and FAQ layers onto the shared SEO layer: CMS head and one graph, the heading convention in both Journal H1 modes, one link per card, body links and images by the rules, breadcrumbs and pagination from the CMS, and one purge route.
|
||||
|
||||
<objective>
|
||||
Change the three existing layers (each main, not pushed; tags in 33-14) and add the body-link utilities to vue-seo-layer:
|
||||
- journal: drop @nuxtjs/seo, extend the SEO layer, L5 cards, L6 headings, L7 body pipeline, postTitleTag and journal.breadcrumbs options, SeoPagination wrapper, pillar on page 1, ItemList nodes (2026-10-28 layer options; D-50, D-52, D-80..83, D-71, D-86, D-40..42);
|
||||
- menu and FAQ: extend the SEO layer, remove purge copies, FAQ headingLevel 0 and the FAQPage node (D-52, D-43, D-71);
|
||||
- vue-seo-layer: `app/utils/bodyLinks.ts` (autolink, applyOutbound, imageAttrs).
|
||||
|
||||
Purpose: SC-2 in the layers every site uses.
|
||||
|
||||
Output: commits in ../vue-seo-layer, ../vue-journal-layer, ../vue-menu-layer, ../vue-faq-layer.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-33 (dependency during development):** each layer's package.json gets `"vue-seo-layer": "link:../vue-seo-layer"` in dependencies with the lockfile updated by `pnpm install`; 33-14 replaces it with the git tag pin (`git+https://git.golem15.com/golem15/vue-seo-layer.git#v<tag>`) before tagging (2026-10-28 release cadence: all tags in 33-14).
|
||||
- **P33-34 (fallback meta):** app/utils/seo.ts keeps only the fallback (post title, excerpt, featured image) applied when `useCmsSeo` has no answer (`seo.cms` false, as summercms.io in 33-12, or the CMS unreachable), so a site without the SEO plugin keeps titles and no page gets two titles.
|
||||
- **P33-35 (H1 flag source):** the post page reads `post.content_h1_to_h2` (33-02's additive key in the post Show answer); when the key is absent (an older Journal) it behaves as true, the D-50 default.
|
||||
- **P33-36 (override cases in smoke):** postTitleTag is copied into `runtimeConfig.public.journal.postTitleTag`, so the smoke runs the override cases on the same build with `--env NUXT_PUBLIC_JOURNAL_POST_TITLE_TAG=h1` (and `p`) and a second expectation file.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-08-SUMMARY.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-02-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
From 33-07/33-08 (vue-seo-layer): extends target `vue-seo-layer`; useCmsSeo answer in useState; useSchemaNode(node); <SeoBreadcrumbs> (props items, label, hideCurrent; page meta seo.breadcrumbs), <SeoPagination> (props current, last, labels, classPrefix), usePagination({current, last}), useSeoLabels, `seo-visually-hidden` class, runtimeConfig cachePurge/siteCache keys, server/lib/siteCachePurge.ts, smoke-ssr count=/header=.
|
||||
Resolve answer (P33-26): autolinks [{phrase, url}], autolink_max, outbound {new_tab, nofollow_domains, sponsored_domains}, breadcrumbs, pagination, url (absolute page URL, its path is "self" for auto-links).
|
||||
Journal API (33-02): post Show has content_h1_to_h2 (boolean); featured_images[{id, url, file_name, file_size}].
|
||||
vue-journal-layer today: lib/journal-module.ts (defaults routes, perPage, sort, relatedCount, rss → runtimeConfig.public.journal), app/utils/htmlGate.ts (gateJournalHtml with sanitize-html POLICY and KEEP_ALL), PostCard.vue:15-24 (image link + read-more), PostPage.vue:14 (cfg), :40 (useSeoMeta postSeoMeta), :46 (h1), Pagination.vue, utils/pagination.ts (paginationWindow), CategoryHeader.vue, RelatedPosts.vue, nuxt.config.ts (@nuxtjs/seo, ogImage, seo, sitemap keys), testing/smoke-ssr.mjs and expect-acme.txt.
|
||||
vue-faq-layer Block.vue (headingLevel 2..4, aria-labelledby), useFaq answer {name, description, content[{question, answer}]}.
|
||||
RESEARCH Code Examples: phrase auto-linking over sanitize-html output (text nodes with an open-tag stack).
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups per repository, staged by path (`git -C ../<layer> add <paths>`, deletions with `git rm`). `npm --prefix ../<layer> run test` green at every commit in that layer.
|
||||
- Resume check: `git -C ../<layer> log --format=%s | grep -Fx '<subject>'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | journal: `feat!: render the post page on the shared SEO layer with one H1 in both Journal H1 modes (tracer)` | expect-acme.txt tracer lines pass |
|
||||
| 2 | seo: `feat: body link utilities (auto-links, outbound rules, image attributes)`; journal: A `feat: body links, outbound rules and image attributes in the post body`; B `feat!: one link per post card and the heading convention`; C `feat: breadcrumbs, CMS pagination and pillar content on page one`; D `feat: ItemList nodes on listing pages` | both expectation files pass |
|
||||
| 3 | menu: `feat!: extend the SEO layer and drop the copied purge route`; faq: A `feat!: extend the SEO layer and drop the copied purge route`; B `feat: FAQPage node and widget headings`; journal: `docs: README for the SEO layer` | plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "a Journal post page renders through the shared SEO layer with exactly one H1 in both Journal H1 modes, one canonical and one JSON-LD script" — one path only</name>
|
||||
<files>../vue-journal-layer/package.json, ../vue-journal-layer/pnpm-lock.yaml, ../vue-journal-layer/nuxt.config.ts, ../vue-journal-layer/lib/journal-module.ts, ../vue-journal-layer/app/utils/types.ts, ../vue-journal-layer/app/utils/seo.ts, ../vue-journal-layer/app/utils/htmlGate.ts, ../vue-journal-layer/app/utils/sitemap.ts, ../vue-journal-layer/app/components/Journal/PostBody.vue, ../vue-journal-layer/app/journal-pages/PostPage.vue, ../vue-journal-layer/app/assets/css/journal-tokens.css, ../vue-journal-layer/app/assets/css/journal-base.css, ../vue-journal-layer/server/api/__sitemap__/journal.ts, ../vue-journal-layer/server/api/__journal__/cache/purge.post.ts, ../vue-journal-layer/server/api/__site__/cache/purge.post.ts, ../vue-journal-layer/server/lib/siteCachePurge.ts, ../vue-journal-layer/server/plugins/site-cache-purge.ts, ../vue-journal-layer/tests/seo.test.ts, ../vue-journal-layer/tests/sitemap.test.ts, ../vue-journal-layer/tests/sitePurge.test.ts, ../vue-journal-layer/tests/htmlGate.test.ts, ../vue-journal-layer/testing/smoke-ssr.mjs, ../vue-journal-layer/testing/fixture-api.mjs, ../vue-journal-layer/testing/expect-acme.txt, ../vue-journal-layer/testing/fixtures/acme/posts.json, ../vue-journal-layer/testing/fixtures/acme/seo/resolve.json, ../vue-journal-layer/testing/fixtures/acme/seo/site.json</files>
|
||||
<read_first>
|
||||
- ../vue-journal-layer/nuxt.config.ts, package.json, lib/journal-module.ts, app/journal-pages/PostPage.vue, app/components/Journal/PostBody.vue, app/utils/{htmlGate,seo,sitemap,types}.ts, server/api/__journal__/cache/purge.post.ts
|
||||
- ../vue-seo-layer/nuxt.config.ts, app/composables/useCmsSeo.ts, testing/smoke-ssr.mjs (count=, header=)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (L6 table and the post-title CSS, L7 step 1)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-97, D-50, the 2026-10-28 Journal H1 setting and layer options, P33-33 to P33-36: package.json removes @nuxtjs/seo and adds the link dependency; nuxt.config.ts extends vue-seo-layer, drops @nuxtjs/seo from modules and the ogImage, seo and sitemap keys and the cachePurge/siteCache runtime keys (now in the SEO layer), keeps journal.cachePurgeToken and the /api/__journal__/** route rule. Remove the journal sitemap source (server/api/__sitemap__/journal.ts, app/utils/sitemap.ts, tests/sitemap.test.ts) and the copied shared purge files (server/api/__site__/cache/purge.post.ts, server/lib/siteCachePurge.ts, server/plugins/site-cache-purge.ts, tests/sitePurge.test.ts); the deprecated /api/__journal__/cache/purge imports the purge library from vue-seo-layer. journal-module.ts adds `postTitleTag: 'auto'` and `breadcrumbs: true` to defaults and runtimeConfig.public.journal; types.ts adds them and the post's `content_h1_to_h2?: boolean`. PostPage.vue: titleTag = postTitleTag when 'h1' or 'p', else 'h1' when content_h1_to_h2 !== false, else 'p'; fallback meta only when no CMS answer (P33-34). htmlGate.ts: `gateJournalHtml(html, {demoteH1})` applying sanitize-html transformTags h1→h2 only when demoteH1; PostBody passes `demoteH1: post.content_h1_to_h2 !== false`. journal-tokens.css gets --journal-post-title-size 2em, --journal-post-title-weight 700, --journal-post-title-line-height 1.2; journal-base.css styles .journal-post__title with them and --journal-font-heading. smoke-ssr.mjs copies the SEO layer's count= and header= support (apps run it from node_modules). fixture-api.mjs serves the SEO fixtures; posts.json gets a post with content_h1_to_h2 true and one with false, each with one body h1 and one h2. expect-acme.txt tracer lines: for the "on" post `count=<h1:1 contains=<h1 class="journal-post__title"`, for the "off" post `count=<h1:1 contains=<p class="journal-post__title"`, both `count=application/ld+json:1 count=rel="canonical":1`. htmlGate.test.ts covers demoteH1 true and false. Commit as listed (one feat! commit: the layer drops @nuxtjs/seo).
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-journal-layer run test 2>&1 | tail -10</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line</fails_when>
|
||||
<automated>npm --prefix ../vue-journal-layer run build:playground 2>&1 | tail -3 && node ../vue-journal-layer/testing/smoke-ssr.mjs --output ../vue-journal-layer/.playground/.output --fixtures ../vue-journal-layer/testing/fixtures/acme --expect ../vue-journal-layer/testing/expect-acme.txt 2>&1 | tail -20</automated>
|
||||
<fails_when>non-zero exit from the build or the smoke, or a "FAIL" line in the smoke output</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "@nuxtjs/seo" ../vue-journal-layer/package.json ../vue-journal-layer/nuxt.config.ts` prints nothing
|
||||
- `grep -n "vue-seo-layer" ../vue-journal-layer/package.json ../vue-journal-layer/nuxt.config.ts` prints a line in each
|
||||
- `git -C ../vue-journal-layer ls-files server/lib server/api/__site__ server/api/__sitemap__` prints nothing
|
||||
- `grep -n "postTitleTag" ../vue-journal-layer/lib/journal-module.ts ../vue-journal-layer/app/journal-pages/PostPage.vue` prints a line in each
|
||||
</acceptance_criteria>
|
||||
<done>A Journal post renders through the SEO layer with exactly one H1 whichever Journal H1 mode the site uses.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Body link utilities and the L7 pipeline, L5 post cards, L6 headings, breadcrumbs, CMS pagination, pillar on page 1 and ItemList nodes</name>
|
||||
<files>../vue-seo-layer/app/utils/bodyLinks.ts, ../vue-seo-layer/tests/bodyLinks.test.ts, ../vue-journal-layer/app/utils/htmlGate.ts, ../vue-journal-layer/app/utils/routes.ts, ../vue-journal-layer/lib/journal-module.ts, ../vue-journal-layer/app/components/Journal/PostBody.vue, ../vue-journal-layer/app/components/Journal/PostCard.vue, ../vue-journal-layer/app/components/Journal/Pagination.vue, ../vue-journal-layer/app/components/Journal/CategoryHeader.vue, ../vue-journal-layer/app/components/Journal/RelatedPosts.vue, ../vue-journal-layer/app/components/Journal/FeaturedImage.vue, ../vue-journal-layer/app/journal-pages/PostPage.vue, ../vue-journal-layer/app/journal-pages/PostIndexPage.vue, ../vue-journal-layer/app/journal-pages/CategoryPage.vue, ../vue-journal-layer/app/journal-pages/TagPage.vue, ../vue-journal-layer/app/journal-pages/AuthorPage.vue, ../vue-journal-layer/app/assets/css/journal-base.css, ../vue-journal-layer/tests/htmlGate.test.ts, ../vue-journal-layer/tests/routes.test.ts, ../vue-journal-layer/testing/expect-acme.txt, ../vue-journal-layer/testing/expect-acme-title-h1.txt, ../vue-journal-layer/testing/fixtures/acme/seo/resolve.json</files>
|
||||
<read_first>
|
||||
- ../vue-journal-layer/app/components/Journal/{PostCard,Pagination,CategoryHeader,RelatedPosts,FeaturedImage}.vue and the journal pages
|
||||
- ../vue-journal-layer/app/utils/pagination.ts and routes.ts
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Code Examples: phrase auto-linking; Pitfall 7)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (L5, L6, L7, L1 journal placement switch, L2 Journal note)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- autolink: first occurrence only, at most max per text, case-insensitive whole words, never inside a, h1–h6, code, pre, figcaption, button, never to the page's own path, phrase with regex characters matched literally, URLs escaped in href; output is a plain <a href>
|
||||
- applyOutbound: an https link to another host keeps its rel tokens, gains nofollow for a listed domain (subdomains included) or sponsored, and with newTab true gains target=_blank, rel noopener and the hidden hint span; with newTab false none of the three; internal and relative links unchanged
|
||||
- imageAttrs: body img gains loading=lazy and decoding=async, keeps width/height and alt=""
|
||||
- Smoke: each .journal-post-card has one <a and an h2 title, related posts are h2 with h3 cards, no read-more link; listing pages have one h1 and on ?page=2 the · Strona 2 suffix; the post page renders one nav.seo-breadcrumbs (none with journal.breadcrumbs false through NUXT_PUBLIC_JOURNAL_BREADCRUMBS=false); the category page shows its pillar content on page 1 only; journal-pagination markup stays with first/last and gap items; index and category pages have one JSON-LD script containing ItemList
|
||||
- Smoke with NUXT_PUBLIC_JOURNAL_POST_TITLE_TAG=h1 (expect-acme-title-h1.txt): the "off" post has two <h1 (documented override); with p, the "on" post has no <h1
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-80 to D-83, D-71, D-52, D-86, D-40 to D-42, D-43 and UI-SPEC L1/L2/L5/L6/L7: `vue-seo-layer/app/utils/bodyLinks.ts` (pure, no Vue imports, outside auto-import dirs' side effects) with `autolink(html, links, max, selfPath)`, `applyOutbound(html, {siteHost, newTab, nofollowDomains, sponsoredDomains, hint})`, `imageAttrs(html)`, working on sanitize-html's normalised output with a tag/text split and an open-tag stack (RESEARCH example), attribute values escaped; tests first. Journal htmlGate runs the L7 order after sanitizing (POLICY now allows rel tokens nofollow, sponsored, ugc on a, and target only as added by applyOutbound); PostBody passes the resolve answer's autolinks, autolink_max, outbound and url path. PostCard.vue per L5 (headingLevel 2|3, one title link, image without link, stretched-link CSS in journal-base.css, focus ring with :has); RelatedPosts h2 and cards headingLevel 3; Pagination.vue wraps SeoPagination with class-prefix journal-pagination and the journal labels; journal-module.ts registers path-form listing routes (`<listing>/<segment>/:page`) when the SEO build option pagination.form is path (routes.ts helper, tested); CategoryHeader renders rich content only on page 1; journal pages render SeoBreadcrumbs when journal.breadcrumbs is true; listing pages call useSchemaNode with an ItemList (@id <url>#itemlist, ListItem position and url of each post on the page). Expectation files per behavior list. Commit groups as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-seo-layer run test 2>&1 | tail -8 && npm --prefix ../vue-journal-layer run test 2>&1 | tail -8</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line in either</fails_when>
|
||||
<automated>npm --prefix ../vue-journal-layer run build:playground 2>&1 | tail -3 && node ../vue-journal-layer/testing/smoke-ssr.mjs --output ../vue-journal-layer/.playground/.output --fixtures ../vue-journal-layer/testing/fixtures/acme --expect ../vue-journal-layer/testing/expect-acme.txt 2>&1 | tail -15 && node ../vue-journal-layer/testing/smoke-ssr.mjs --output ../vue-journal-layer/.playground/.output --fixtures ../vue-journal-layer/testing/fixtures/acme --expect ../vue-journal-layer/testing/expect-acme-title-h1.txt --env NUXT_PUBLIC_JOURNAL_POST_TITLE_TAG=h1 2>&1 | tail -8</automated>
|
||||
<fails_when>non-zero exit from any command, or a "FAIL" line in the output</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "export function autolink\|export function applyOutbound\|export function imageAttrs" ../vue-seo-layer/app/utils/bodyLinks.ts` prints three lines
|
||||
- `grep -n "journal-post-card__more\|readMore" ../vue-journal-layer/app/components/Journal/PostCard.vue` prints nothing
|
||||
- `grep -n "SeoPagination" ../vue-journal-layer/app/components/Journal/Pagination.vue` prints one line
|
||||
- `grep -n "count=<h1:1" ../vue-journal-layer/testing/expect-acme.txt` prints at least five lines (every fixture page)
|
||||
</acceptance_criteria>
|
||||
<done>Journal pages follow the heading, card, body-link, image, breadcrumb and pagination rules, verified on built pages.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: Menu and FAQ layers on the SEO layer, FAQ widget headings and the FAQPage node, one-resolve check across all three layers</name>
|
||||
<files>../vue-menu-layer/package.json, ../vue-menu-layer/pnpm-lock.yaml, ../vue-menu-layer/nuxt.config.ts, ../vue-menu-layer/server/api/__site__/cache/purge.post.ts, ../vue-menu-layer/server/lib/siteCachePurge.ts, ../vue-menu-layer/server/plugins/site-cache-purge.ts, ../vue-menu-layer/tests/sitePurge.test.ts, ../vue-menu-layer/README.md, ../vue-faq-layer/package.json, ../vue-faq-layer/pnpm-lock.yaml, ../vue-faq-layer/nuxt.config.ts, ../vue-faq-layer/app/components/Faq/Block.vue, ../vue-faq-layer/app/utils/faqSchema.ts, ../vue-faq-layer/server/api/__site__/cache/purge.post.ts, ../vue-faq-layer/server/lib/siteCachePurge.ts, ../vue-faq-layer/server/plugins/site-cache-purge.ts, ../vue-faq-layer/tests/sitePurge.test.ts, ../vue-faq-layer/tests/faqSchema.test.ts, ../vue-faq-layer/testing/expect.txt, ../vue-faq-layer/README.md, ../vue-journal-layer/README.md, ../vue-seo-layer/README.md</files>
|
||||
<read_first>
|
||||
- ../vue-menu-layer/nuxt.config.ts, package.json, testing/smoke-ssr.mjs, README.md
|
||||
- ../vue-faq-layer/nuxt.config.ts, app/components/Faq/{Block,List,Item}.vue, app/composables/useFaq.ts, testing/expect.txt, README.md
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (L6 FAQ row)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-52, D-43, D-71, D-97 and P33-33: menu and FAQ layers add the link dependency, extend vue-seo-layer, drop their cachePurge/siteCache runtime keys and their copies of the purge route, library, plugin and test (git rm); their smoke tests keep passing (the SEO middleware fails open against their fixture APIs). FAQ Block.vue accepts `headingLevel: 0 | 2 | 3 | 4`, rendering `<p class="faq-block__title">` with the same id and aria-labelledby at 0; new prop `schema` (default true) calls useSchemaNode with `faqSchema(faq)` — FAQPage @id <url>#faq, mainEntity Question/acceptedAnswer with answer text stripped of markup (pure util, tested). expect.txt asserts the 0 level and that the answers are in the HTML inside details. Then check across the three layers: in a temporary directory outside the repositories, an app extending vue-journal-layer, vue-menu-layer and vue-faq-layer (link dependencies) renders the journal acme fixtures with the journal smoke harness and an expectation that the fixture API recorded exactly one resolve call per page render and that each page has one canonical and one ld+json; record the command and its output in the SUMMARY (no files committed for the scratch app). README updates in each layer: extending the SEO layer, the removed purge files, new options and props. Commit groups as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>npm --prefix ../vue-menu-layer run test 2>&1 | tail -6 && npm --prefix ../vue-faq-layer run test 2>&1 | tail -6</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line in either</fails_when>
|
||||
<automated>npm --prefix ../vue-menu-layer run build:playground 2>&1 | tail -2 && npm --prefix ../vue-menu-layer run smoke:ssr 2>&1 | tail -6 && npm --prefix ../vue-faq-layer run build:playground 2>&1 | tail -2 && npm --prefix ../vue-faq-layer run smoke:ssr 2>&1 | tail -6</automated>
|
||||
<fails_when>non-zero exit from any command, or a "FAIL" line in the output</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git -C ../vue-menu-layer ls-files server/lib server/api/__site__` and `git -C ../vue-faq-layer ls-files server/lib server/api/__site__` print nothing
|
||||
- `grep -n "vue-seo-layer" ../vue-menu-layer/nuxt.config.ts ../vue-faq-layer/nuxt.config.ts` prints a line in each
|
||||
- `grep -n "FAQPage" ../vue-faq-layer/app/utils/faqSchema.ts` prints at least one line
|
||||
- the SUMMARY records the cross-layer check with one resolve call per page
|
||||
</acceptance_criteria>
|
||||
<done>All three content layers render through the SEO layer with one graph, one canonical and one purge route.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| CMS content (body HTML, phrases, URLs) → SSR HTML | stored content rendered to visitors |
|
||||
| resolve answer → layer transforms | phrase table and domain lists |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-39 | Tampering (XSS) | autolink and outbound transforms | high | mitigate | run on sanitize-html output only; links inserted into text nodes only; href and rel built from validated values with attribute escaping; unit tests with quotes, <, javascript: URLs refused (only / paths and http(s)) |
|
||||
| T-33-40 | Tampering | htmlGate policy (rel/target) | medium | mitigate | the sanitizer accepts only the rel tokens nofollow, sponsored, ugc; target and noopener are added after sanitizing by applyOutbound, never taken from stored HTML |
|
||||
| T-33-41 | Information disclosure | removal of @nuxtjs/seo | low | mitigate | no site config with NUXT_SITE_* is published anymore; purge-token-check stays in the journal testing harness |
|
||||
| T-33-42 | Denial of service | auto-link phrase table size | low | mitigate | at most autolink_max links per text; phrase scan is linear in text length per phrase; the resolver filters phrases per locale |
|
||||
| T-33-SC | Tampering | npm installs | high | mitigate | @nuxtjs/seo removed, no package added; the only new dependency is the first-party vue-seo-layer through a local link; lockfiles committed |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `npm --prefix ../<layer> run test` green in all four layers.
|
||||
- Journal: playground build plus both expectation files; menu and FAQ: playground builds and smoke.
|
||||
- Cross-layer check recorded in the SUMMARY.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- The three content layers extend the SEO layer and drop their own SEO module and purge copies.
|
||||
- Headings, cards, body links, images, breadcrumbs and pagination follow the rules on built pages in both Journal H1 modes.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- vue-seo-layer: `app/utils/bodyLinks.ts` (`autolink`, `applyOutbound`, `imageAttrs`), `tests/bodyLinks.test.ts`.
|
||||
- vue-journal-layer options: `journal.postTitleTag` ('auto' | 'h1' | 'p'), `journal.breadcrumbs` (boolean); runtime keys `runtimeConfig.public.journal.postTitleTag`, `.breadcrumbs`; env `NUXT_PUBLIC_JOURNAL_POST_TITLE_TAG`, `NUXT_PUBLIC_JOURNAL_BREADCRUMBS`.
|
||||
- vue-journal-layer: `gateJournalHtml(html, {demoteH1})`, PostCard prop `headingLevel`, CSS tokens `--journal-post-title-size`, `--journal-post-title-weight`, `--journal-post-title-line-height`, path-form pagination routes, `testing/expect-acme-title-h1.txt`, smoke-ssr `count=`/`header=`; removed: `server/api/__sitemap__/journal.ts`, `app/utils/sitemap.ts`, the shared purge copies, the @nuxtjs/seo dependency.
|
||||
- vue-faq-layer: Block props `headingLevel: 0` and `schema`, `app/utils/faqSchema.ts`.
|
||||
- vue-menu-layer: extends vue-seo-layer; purge copies removed.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-09-SUMMARY.md` when done.
|
||||
</output>
|
||||
339
.planning/phases/33-seo-output-audit-and-content/33-10-PLAN.md
Normal file
339
.planning/phases/33-seo-output-audit-and-content/33-10-PLAN.md
Normal file
@@ -0,0 +1,339 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 10
|
||||
type: execute
|
||||
wave: 6
|
||||
depends_on: ["33-06"]
|
||||
files_modified:
|
||||
- ../sm-seo-plugin/classes/crawl/crawler.go
|
||||
- ../sm-seo-plugin/classes/crawl/fetch.go
|
||||
- ../sm-seo-plugin/classes/crawl/parse.go
|
||||
- ../sm-seo-plugin/classes/crawl/checks.go
|
||||
- ../sm-seo-plugin/classes/crawl/links.go
|
||||
- ../sm-seo-plugin/classes/crawl/orphans.go
|
||||
- ../sm-seo-plugin/classes/crawl/store.go
|
||||
- ../sm-seo-plugin/classes/crawl/fix.go
|
||||
- ../sm-seo-plugin/classes/issues.go
|
||||
- ../sm-seo-plugin/classes/settings_write.go
|
||||
- ../sm-seo-plugin/classes/partials.go
|
||||
- ../sm-seo-plugin/models/crawl.go
|
||||
- ../sm-seo-plugin/models/crawl/columns.yaml
|
||||
- ../sm-seo-plugin/models/crawl/fields.yaml
|
||||
- ../sm-seo-plugin/models/crawl_page.go
|
||||
- ../sm-seo-plugin/models/issue.go
|
||||
- ../sm-seo-plugin/models/issue/columns.yaml
|
||||
- ../sm-seo-plugin/models/issue/fields.yaml
|
||||
- ../sm-seo-plugin/models/settings.go
|
||||
- ../sm-seo-plugin/models/settings/fields.yaml
|
||||
- ../sm-seo-plugin/models/registry.go
|
||||
- ../sm-seo-plugin/updates/202610280005_create_golem15_seo_crawls.go
|
||||
- ../sm-seo-plugin/updates/202610280006_add_golem15_seo_audit_settings.go
|
||||
- ../sm-seo-plugin/updates/registry.go
|
||||
- ../sm-seo-plugin/controllers/admin_registry.go
|
||||
- ../sm-seo-plugin/controllers/issues.go
|
||||
- ../sm-seo-plugin/controllers/issues/config_list.yaml
|
||||
- ../sm-seo-plugin/controllers/issues/config_form.yaml
|
||||
- ../sm-seo-plugin/controllers/issues/config_filter.yaml
|
||||
- ../sm-seo-plugin/controllers/issues/_issue_details.htm
|
||||
- ../sm-seo-plugin/controllers/crawls.go
|
||||
- ../sm-seo-plugin/controllers/crawls/config_list.yaml
|
||||
- ../sm-seo-plugin/controllers/crawls/config_form.yaml
|
||||
- ../sm-seo-plugin/controllers/crawls/config_filter.yaml
|
||||
- ../sm-seo-plugin/controllers/crawls/_crawl_summary.htm
|
||||
- ../sm-seo-plugin/controllers/api/crawls.go
|
||||
- ../sm-seo-plugin/controllers/api/issues.go
|
||||
- ../sm-seo-plugin/admin_navigation.go
|
||||
- ../sm-seo-plugin/jobs.go
|
||||
- ../sm-seo-plugin/schedule.go
|
||||
- ../sm-seo-plugin/commands.go
|
||||
- ../sm-seo-plugin/menu_item_types.go
|
||||
- ../sm-seo-plugin/routes.go
|
||||
- ../sm-seo-plugin/mcp.go
|
||||
- ../sm-seo-plugin/operations.go
|
||||
- ../sm-seo-plugin/config/config.yaml
|
||||
- ../sm-seo-plugin/lang/en/lang.yaml
|
||||
- ../sm-seo-plugin/lang/pl/lang.yaml
|
||||
- ../sm-seo-plugin/README.md
|
||||
- ../sm-seo-plugin/crawler_test.go
|
||||
- ../sm-seo-plugin/crawl_site_test.go
|
||||
autonomous: true
|
||||
requirements: [SC-3, D-14, D-46, D-51, D-70, D-71, D-80, D-81, D-82, D-85, D-24, D-50, D-10, D-94]
|
||||
|
||||
estimate:
|
||||
tokens: 180000
|
||||
raw_tokens: 180000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "A built-in crawler runs as a conga job (on demand from SEO › Crawls or Site audit, from MCP, or on the crawl_schedule setting off/daily/weekly at night): it fetches the site's own pages over HTTP from the home page, the sitemap index and its files, and same-host links, with at most two requests at a time, crawl_delay between requests (default 250 ms), a 10 s timeout, a 5 MiB body cap and crawl_max_pages (default 5000); one crawl runs at a time and older crawls beyond crawl_keep are deleted with their pages and issues (D-14)"
|
||||
- "Outbound requests go through a fetchguard client limited to the site's host (and its www twin), HTTPS only and without following redirects; plain http (staging, local) works only when the config key golem15.seo.crawl_trusted is true (D-14, security)"
|
||||
- "The crawler reports per URL every crawl kind of UI-SPEC C23: page_status, sitemap_error, sitemap_noindex, sitemap_blocked, sitemap_missing, broken_link, redirected_link, canonical_missing, canonical_error, missing/duplicate title and description, h1_missing, h1_multiple, heading_skipped, heading_empty, h1_title_mismatch, jsonld_invalid, jsonld_multiple, jsonld_required, jsonld_recommended, hreflang_reciprocal, hreflang_error, generic_anchor, image_alt, image_size, featured_lazy, content_js and orphan_page, with the severities of the kinds table (D-14, D-46, D-51, D-70, D-71, D-81, D-82, D-85, D-24)"
|
||||
- "The crawler checks the rendered (server) HTML against CMS expectations without a browser: the descriptor title must appear in the H1, the word count must reach half of the descriptor's Words, and CMS-known links of the page must be present; a miss is content_js ('Content needs JavaScript') (D-70, planner default: raw-HTML check only, no headless browser)"
|
||||
- "CMS-data checks run at the end of every crawl (and when the list is opened before any crawl) and are stored with the crawl's issues under source cms; they now include image_alt from the descriptors' images (empty alt that is not decorative) and h1_in_content, which runs only for records whose descriptor sets TopHeading 2, so it is off when Journal's H1 setting is off (D-85, D-50, 2026-10-28 Journal H1 setting)"
|
||||
- "Every issue names the MCP tool that fixes it (seo_ tools for SEO data, the content type's ContentDescriptor.Tools for content: edit, headings, image_alt) or carries fix code when the cause is the site's templates; no issue has neither (SC-3, D-10, RESEARCH Open Question 4)"
|
||||
- "orphan_page lists indexable sitemap pages with no inbound internal link in the crawl, with suggestions of pages whose text mentions the page's title or focus keyphrase (D-82)"
|
||||
- "SEO › Site audit lists the stored issues (errors first) with the C23 columns, filters (status defaults to Open), the P7 preview (what was found, how to fix, page and Rich Results links), and the record actions Check this address again, Ignore and Stop ignoring plus bulk Ignore; ignored issues stay ignored in later crawls (UI-SPEC C23)"
|
||||
- "SEO › Crawls lists runs with the C24 columns, the P6 preview (one status callout, stats strip, per-kind table linking to the filtered audit), Start crawl (toolbar, also on Site audit) refusing with crawls.already_running or crawls.no_site_url, Cancel on a queued or running crawl that keeps what was fetched, and delete refusing a running crawl with crawls.delete_running (UI-SPEC C24)"
|
||||
- "The SEO settings get the Site audit tab: crawl_schedule, crawl_max_pages (10–50 000), crawl_delay (100–5000 ms), crawl_keep (1–50) and generic_anchors seeded with the en and pl lists (UI-SPEC C20, Q-1)"
|
||||
- "MCP has seo_start_crawl, seo_cancel_crawl, seo_list_crawls, seo_get_crawl, seo_delete_crawls, seo_list_issues (filters severity, kind, source, fix, status, url, crawl), seo_recheck_url, seo_ignore_issues and seo_unignore_issues; TestEveryAdminOperationHasTool maps every Site audit and Crawls operation (D-10)"
|
||||
- "On a non-production environment noindex and robots caused by the staging lock are never reported, and P6 shows crawls.staging_text (RESEARCH Pitfall 12, UI-SPEC partial: non-production)"
|
||||
- "The existing GET /_seo/api/v1/issues answer keeps its Phase 32 keys and gains id, severity, source, fix, found_at, ignored and crawl_id"
|
||||
- "Site audit and Crawls show their empty-state copy issues.list_empty and crawls.list_empty (UI-SPEC empty)"
|
||||
- "Lists, forms and previews show the existing skeletons while loading; a running or queued crawl shows its P6 callout and asks to reload, with no polling (UI-SPEC loading, Q-5)"
|
||||
- "A refused start shows the action-error toast; a failed crawl shows the P6 danger callout with the error and keeps the pages and issues fetched before the failure (UI-SPEC error)"
|
||||
- "The audit list puts errors first with severity, kind and summary columns and hides ignored rows by default; the crawl preview shows its status callout, stats strip and per-kind table with filter links (UI-SPEC populated)"
|
||||
- "Plural copy uses CLDR maps for rechecked, every ignore and delete confirm, and the other counted phrases of this phase (jsonValid, outlineCount, keyphrases_added, h1_converted in their plans) (UI-SPEC zero-one-many)"
|
||||
- "Issue and crawl lists use the existing pagination and .summer-table-wrap scrolling; P7 lists at most 10 linking pages then issues.and_more; long URLs wrap and are set in DM Mono in P6, P7 (UI-SPEC overflow, long-text)"
|
||||
- {statement: "A crawl of the planted test site finds each planted issue exactly once and no issue on its clean control page", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-14"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "The crawler never requests a host other than the site's own (no redirect following, no third-party links, no private address unless trusted mode is configured in Go config)"
|
||||
- requirement_id: "D-14"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "The crawler never changes data: it reads pages and writes only its own crawl and issue tables"
|
||||
artifacts:
|
||||
- path: "../sm-seo-plugin/classes/crawl/crawler.go"
|
||||
provides: "the crawl job: frontier, politeness, limits, cancel"
|
||||
contains: "fetchguard"
|
||||
- path: "../sm-seo-plugin/classes/crawl/checks.go"
|
||||
provides: "per-page and site-wide checks"
|
||||
contains: "h1_multiple"
|
||||
- path: "../sm-seo-plugin/controllers/issues/_issue_details.htm"
|
||||
provides: "P7"
|
||||
contains: "summer-callout"
|
||||
- path: "../sm-seo-plugin/crawler_test.go"
|
||||
provides: "TestCrawlerTracer, TestCrawlerChecks, TestIssueMerge, TestStagingCrawl, TestCrawlAdmin, TestCrawlTools, TestCrawlSchedule"
|
||||
contains: "func TestCrawlerTracer("
|
||||
key_links:
|
||||
- from: "../sm-seo-plugin/classes/crawl/crawler.go"
|
||||
to: "summercms.go/modules/fetchguard"
|
||||
via: "a fetchguard.Client with AllowHostsMode on the site host (TrustedMode only from config)"
|
||||
pattern: "fetchguard\\.NewClient"
|
||||
- from: "../sm-seo-plugin/classes/crawl/checks.go"
|
||||
to: "../sm-seo-plugin/classes/schema/validate.go"
|
||||
via: "rendered JSON-LD validated with the same rules as E9"
|
||||
pattern: "schema\\.Validate"
|
||||
- from: "../sm-seo-plugin/classes/crawl/fix.go"
|
||||
to: "summercms.go/modules/pact/content.go"
|
||||
via: "content issues name ContentDescriptor.Tools[edit|headings|image_alt]"
|
||||
pattern: "Tools\\["
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan adds the audit: a built-in crawler that fetches the rendered site like a search engine, stores what it finds per URL with the CMS-data checks, and offers every issue to an MCP client with the tool that fixes it.
|
||||
|
||||
<objective>
|
||||
Extend ../sm-seo-plugin (main, not pushed):
|
||||
- the crawler as a conga job with storage, politeness limits and the SSRF guard (D-14);
|
||||
- the checks of UI-SPEC C23 (D-46, D-51, D-70, D-71, D-81, D-82, D-85, D-24) and the merged CMS issues with fix routes (SC-3);
|
||||
- Site audit and Crawls screens (C23, C24), the Site audit settings tab (C20), the nightly schedule;
|
||||
- MCP tools for crawls and issues (D-10).
|
||||
|
||||
Purpose: ROADMAP success criterion 3 ("The crawler reports SEO issues per URL, and each issue can be fixed through MCP").
|
||||
|
||||
Output: commits in ../sm-seo-plugin.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-37 (tables):** golem15_seo_crawls (id, status queued|running|finished|failed|cancelled, trigger admin|schedule|mcp, trigger_name, site, max_pages, pages, limit_hit, error, job_id, started_at, finished_at, created_at); golem15_seo_crawl_pages (crawl_id, url, status, location, content_type, title, description, canonical, robots, x_robots, h1 jsonb, headings jsonb, words, text (the page's main text as plain text, capped at 100 000 characters, read by orphan suggestions here and by E10 in 33-11), depth, in_sitemap, sitemap_file, links_out, links_in, fetched_at); golem15_seo_crawl_links (crawl_id, from_url, to_url, text, rel, internal); golem15_seo_issues (id, crawl_id null, source crawl|cms, kind, severity error|warning|notice, url, locale, details jsonb, tool, fix tool|code, fingerprint, found_at); golem15_seo_issue_ignores (fingerprint unique, admin_id, ignored_at). The fingerprint is kind + url + locale + the kind's identifying detail, so an ignore survives later crawls.
|
||||
- **P33-38 (fix route):** `fix = tool` with the full tool name when a CMS value fixes it: SEO data → seo_set_url_seo, seo_update_robots, seo_create_redirect, seo_update_page; content → the record's ContentDescriptor.Tools (edit, headings, image_alt); otherwise `fix = code` with the template element named in details.what. A kind marked "MCP or Code" in C23 chooses per finding: content headings, links and JSON-LD inside the record's own content (descriptor Headings or body links, stored custom JSON-LD) are tool; elsewhere code.
|
||||
- **P33-39 (one crawl at a time):** start refuses when a crawl is queued or running (row check in the start transaction with a row lock), since conga has no unique jobs.
|
||||
- **P33-40 (schedule):** pact.HasSchedule entry `{Command: "seo:crawl", Args: ["--scheduled"], Cadence: pact.DailyAt(2, 30)}`; with --scheduled the command does nothing when crawl_schedule is off and runs weekly crawls only on Mondays in the app's location.
|
||||
- **P33-41 (crawler identity):** User-Agent `SummerCMS-SEO-Crawler/1 (+<site_url>)`; robots.txt rules are not obeyed for the site's own audit (they are checked and reported instead).
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-06-SUMMARY.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-05-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
fetchguard: NewClient(Policy{Mode: AllowHostsMode, AllowHosts, MaxBytes, Timeout}, cfg) / TrustedMode; Client.Get(ctx, url, header) → Result{StatusCode, Header, Body}; 3xx returned, never followed; WithTransport(ctx, rt) for tests.
|
||||
golang.org/x/net/html (already in the dependency graph through sm-journal-plugin and the framework) for parsing; grobotstxt for robots checks (Phase 32).
|
||||
conga: Manager.Dispatch(ctx, db, args, DispatchOpts{Label, Count}), StartJob, UpdateJobState, CheckIfCanceled, CancelJob; conga.JobID(ctx).
|
||||
sm-seo-plugin: classes/issues.go (Issue{Kind, URL, Locale, Details, Tool}, CMS kinds), classes/schema (Build, Validate from 33-06), classes/sitemap_filter.go and contract.Listing (33-05), Service.Staging(), SiteURL(); controllers/notfound.go + config (record actions, bulk actions, row states pattern); controllers/history/_history_diff.htm (partial with summer-table); operations.go / operations_test.go; mcp.go.
|
||||
pact.ContentDescriptor.Tools, ContentRecord.TopHeading, ContentLocale.Images/Headings (33-01).
|
||||
Copy: UI-SPEC C23 (issue kinds table: severities, fix routes, labels, details cells), C24, C20 Site audit tab, Destructive actions.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups staged by path in ../sm-seo-plugin; vet and `test -short` green at every commit; lang keys in both files per group.
|
||||
- Resume check: `git -c safe.directory='*' -C ../sm-seo-plugin log --format=%s | grep -Fx '<subject>'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | `feat: crawler finds a page with two H1 headings and stores the issue (tracer)` | TestCrawlerTracer passes |
|
||||
| 2 | A `feat: crawler checks for status, sitemaps, canonical, titles and headings`; B `feat: crawler checks for JSON-LD, hreflang, links, images and raw HTML`; C `feat: orphan pages and merged CMS issues with fix routes` | TestCrawlerChecks, TestIssueMerge, TestStagingCrawl pass |
|
||||
| 3 | A `feat: Site audit and Crawls screens`; B `feat: site audit settings and the nightly crawl`; C `feat: MCP tools for crawls and issues`; D `docs: crawler and site audit in README` | plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "an editor starts a crawl, the crawler fetches a page with two H1 headings, and the issue appears in the issues API with how to fix it" — one path only</name>
|
||||
<files>../sm-seo-plugin/models/crawl.go, ../sm-seo-plugin/models/crawl_page.go, ../sm-seo-plugin/models/issue.go, ../sm-seo-plugin/models/registry.go, ../sm-seo-plugin/updates/202610280005_create_golem15_seo_crawls.go, ../sm-seo-plugin/updates/registry.go, ../sm-seo-plugin/classes/crawl/crawler.go, ../sm-seo-plugin/classes/crawl/fetch.go, ../sm-seo-plugin/classes/crawl/parse.go, ../sm-seo-plugin/classes/crawl/checks.go, ../sm-seo-plugin/classes/crawl/store.go, ../sm-seo-plugin/classes/crawl/fix.go, ../sm-seo-plugin/jobs.go, ../sm-seo-plugin/controllers/api/crawls.go, ../sm-seo-plugin/controllers/api/issues.go, ../sm-seo-plugin/routes.go, ../sm-seo-plugin/config/config.yaml, ../sm-seo-plugin/crawler_test.go, ../sm-seo-plugin/crawl_site_test.go</files>
|
||||
<read_first>
|
||||
- summercms.go/modules/fetchguard/README.md and fetch.go (Client, WithTransport, Result)
|
||||
- ../sm-seo-plugin/jobs.go, classes/generate.go (job and dispatch), classes/issues.go, controllers/api/issues.go, controllers/api/auth.go
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md (Pattern 7, Pitfall 12, Security Domain)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-14 and P33-37 to P33-41: migration 202610280005 creates the P33-37 tables; models for crawls, pages and issues. `classes/crawl`: fetch.go builds the client (AllowHostsMode with the site host and its www twin, HTTPS; TrustedMode when config `golem15.seo.crawl_trusted` is true; MaxBytes 5 MiB; Timeout 10 s; the P33-41 User-Agent); crawler.go runs a breadth-first frontier from the home page and the sitemap index (only same-host URLs, two workers, the delay, max pages, CheckIfCanceled between pages, progress through UpdateJobState); parse.go extracts status, Location, title, meta description, canonical, meta robots, X-Robots-Tag, headings, links with text and rel, images with alt/size/loading, JSON-LD scripts and hreflang links with golang.org/x/net/html; checks.go starts with h1_missing and h1_multiple; store.go writes pages, links and issues; fix.go applies P33-38. jobs.go registers `CrawlArgs` (kind golem15.seo.crawl). Routes in the management group: `POST /_seo/api/v1/crawls` (start, P33-39 refusals 409 crawls.already_running / 422 crawls.no_site_url), and `GET /_seo/api/v1/issues` returns stored issues with the Phase 32 keys plus id, severity, source, fix, found_at, ignored, crawl_id. `crawl_site_test.go` holds an httptest site served through fetchguard.WithTransport (home, a page with two H1, sitemap index and file). `TestCrawlerTracer` (Docker): start a crawl through the API as an administrator, run the job, GET /issues lists h1_multiple for that URL with severity error and a fix (code for a template H1, tool for an H1 inside a fake record's content Headings). Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestCrawlerTracer' -count=1 -v 2>&1 | tail -20</automated>
|
||||
<fails_when>non-zero exit, "FAIL" or "no tests to run" in the output, or no "--- PASS: TestCrawlerTracer" line</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "fetchguard.NewClient\|AllowHostsMode" ../sm-seo-plugin/classes/crawl/fetch.go` prints at least one line
|
||||
- `grep -n "golem15.seo.crawl" ../sm-seo-plugin/jobs.go ../sm-seo-plugin/classes/crawl/crawler.go` prints at least one line
|
||||
- `grep -n "crawl_trusted" ../sm-seo-plugin/config/config.yaml` prints one line
|
||||
- the Phase 32 issues tests (TestIssues) still pass
|
||||
</acceptance_criteria>
|
||||
<done>A crawl started from the API audits the rendered site and its first finding is listed with how to fix it.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: The full set of crawl checks, orphan pages, merged CMS issues with fix routes, ignore fingerprints and staging suppression</name>
|
||||
<files>../sm-seo-plugin/classes/crawl/checks.go, ../sm-seo-plugin/classes/crawl/links.go, ../sm-seo-plugin/classes/crawl/orphans.go, ../sm-seo-plugin/classes/crawl/parse.go, ../sm-seo-plugin/classes/crawl/fix.go, ../sm-seo-plugin/classes/crawl/store.go, ../sm-seo-plugin/classes/crawl/crawler.go, ../sm-seo-plugin/classes/issues.go, ../sm-seo-plugin/menu_item_types.go, ../sm-seo-plugin/lang/en/lang.yaml, ../sm-seo-plugin/lang/pl/lang.yaml, ../sm-seo-plugin/crawler_test.go, ../sm-seo-plugin/crawl_site_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/classes/issues.go (CMS kinds and their tools), classes/schema/validate.go (33-06), classes/robots.go (grobotstxt matcher)
|
||||
- ../sm-sitemap-plugin/contract/contract.go (Listing for sitemap consistency)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C23 kinds table: severity, fix, labels, details)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- TestCrawlerChecks: the planted site has one page per kind of C23 and a clean control page; each kind is reported exactly once for its page with its severity and details keys (status, file, line, count, target, from/to, locale, text, what); the control page has none
|
||||
- sitemap_error for a sitemap URL answering 404; sitemap_noindex for a listed noindex page; sitemap_blocked for a listed URL robots.txt blocks; sitemap_missing for an indexable page found only through links
|
||||
- broken_link with the linking pages; redirected_link with the final target; generic_anchor for "kliknij tutaj" and "click here" (settings list, case-insensitive whole text)
|
||||
- jsonld_invalid for unparsable JSON, jsonld_multiple for two scripts, jsonld_required / jsonld_recommended from schema.Validate; FAQPage nodes have no rules
|
||||
- hreflang_reciprocal when /en/x lists /pl/x but /pl/x does not list /en/x; hreflang_error when an alternate answers 404
|
||||
- image_alt for an img without alt (alt="" is fine), image_size without width/height, featured_lazy when the og:image's img is lazy
|
||||
- content_js when the H1 lacks the descriptor title, when words < half of Words, or when a CMS-known link is absent from the raw HTML
|
||||
- orphan_page for a sitemap page no crawled page links to, with suggestions (pages mentioning its title or focus keyphrase)
|
||||
- TestIssueMerge: CMS issues are stored with source cms at the end of the crawl; image_alt (CMS) names the record type's Tools[image_alt]; h1_in_content appears for a record with TopHeading 2 and an H1 in Headings and not for TopHeading 0; every stored issue has tool or fix code
|
||||
- Ignored fingerprints stay ignored after a second crawl; a fixed page's issues are gone after the second crawl
|
||||
- TestStagingCrawl: with the staging lock every page carries noindex, and no noindex-derived kind is reported
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-14, D-46, D-51, D-70, D-71, D-81, D-82, D-85, D-24 and P33-38: implement each check in checks.go/links.go/orphans.go with severities and details per the C23 table; sitemap consistency reads the fetched sitemap files plus contract.Listing; JSON-LD uses schema.Validate on each parsed graph; title/description duplicates are computed over the crawl; heading checks compare levels in document order; content_js uses the descriptor of the page's record (MatchPath) for title, Words and CMS links; orphans use the stored link graph and the descriptor titles plus the SEO entries' focus keyphrases for suggestions (at most 10 each). issues.go gains the CMS kinds image_alt and h1_in_content (descriptor-driven, the latter only when TopHeading is 2) and stores CMS issues at crawl end. The seo-page descriptor gets Tools {edit: seo_update_page}. Fingerprints and the ignore table per P33-37; staging suppression per Pitfall 12. Every kind's label and summary keys of C23 in both lang files. Tests first, against the planted httptest site. Commit groups A, B, C.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestCrawlerChecks|TestIssueMerge|TestStagingCrawl|TestCrawlerTracer|TestIssues' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -30</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestCrawlerChecks, TestIssueMerge or TestStagingCrawl missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -c "issues.kind_" ../sm-seo-plugin/lang/en/lang.yaml` and the same in lang/pl/lang.yaml are each at least 33
|
||||
- `grep -n "schema.Validate" ../sm-seo-plugin/classes/crawl/checks.go` prints at least one line
|
||||
- TestIssueMerge asserts that no stored issue has an empty tool together with fix "tool"
|
||||
</acceptance_criteria>
|
||||
<done>The audit covers every planned check, merges CMS issues and routes each issue to an MCP tool or to the site's code.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Site audit and Crawls screens, the Site audit settings tab, the nightly crawl and the MCP tools</name>
|
||||
<files>../sm-seo-plugin/controllers/admin_registry.go, ../sm-seo-plugin/controllers/issues.go, ../sm-seo-plugin/controllers/issues/config_list.yaml, ../sm-seo-plugin/controllers/issues/config_form.yaml, ../sm-seo-plugin/controllers/issues/config_filter.yaml, ../sm-seo-plugin/controllers/issues/_issue_details.htm, ../sm-seo-plugin/controllers/crawls.go, ../sm-seo-plugin/controllers/crawls/config_list.yaml, ../sm-seo-plugin/controllers/crawls/config_form.yaml, ../sm-seo-plugin/controllers/crawls/config_filter.yaml, ../sm-seo-plugin/controllers/crawls/_crawl_summary.htm, ../sm-seo-plugin/models/crawl/columns.yaml, ../sm-seo-plugin/models/crawl/fields.yaml, ../sm-seo-plugin/models/issue/columns.yaml, ../sm-seo-plugin/models/issue/fields.yaml, ../sm-seo-plugin/models/settings.go, ../sm-seo-plugin/models/settings/fields.yaml, ../sm-seo-plugin/classes/settings_write.go, ../sm-seo-plugin/classes/partials.go, ../sm-seo-plugin/updates/202610280006_add_golem15_seo_audit_settings.go, ../sm-seo-plugin/updates/registry.go, ../sm-seo-plugin/controllers/api/crawls.go, ../sm-seo-plugin/controllers/api/issues.go, ../sm-seo-plugin/admin_navigation.go, ../sm-seo-plugin/schedule.go, ../sm-seo-plugin/commands.go, ../sm-seo-plugin/routes.go, ../sm-seo-plugin/mcp.go, ../sm-seo-plugin/operations.go, ../sm-seo-plugin/lang/en/lang.yaml, ../sm-seo-plugin/lang/pl/lang.yaml, ../sm-seo-plugin/README.md, ../sm-seo-plugin/crawler_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/controllers/notfound.go and controllers/notfound/config_*.yaml, _hint.htm (record and bulk actions, preview headerPartial, row states)
|
||||
- ../sm-paymentgateway-plugin/controllers/orders.go (Applies/Run record actions, toolbar actions)
|
||||
- summercms.go/modules/pact/capabilities.go (AdminAction toolbar actions, AdminRecordAction, AdminBulkAction, RowState) and docs/plugins/scheduling.md
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C15, C20 Site audit tab, C23, C24, their copy, Destructive actions, MCP parity)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- TestCrawlAdmin: the Site audit list sorts errors first, hides ignored rows with the default status filter, shows source and fix columns; the preview renders P7 with the C23 sections; recheck re-fetches one URL and toasts issues.rechecked or recheck_fixed; ignore and bulk ignore set the fingerprint; unignore clears it; the Crawls list sorts newest first; the preview renders P6 with one status callout (running, queued, failed danger, cancelled, limit warning, staging extra); cancel keeps fetched pages; deleting a running crawl answers 403 crawls.delete_running
|
||||
- Start crawl twice → the second refuses with crawls.already_running naming the start time; without a site URL → crawls.no_site_url
|
||||
- Settings Site audit tab validates the C20 ranges with validation.between; generic_anchors seeded with the en and pl lists
|
||||
- TestCrawlSchedule: seo:crawl --scheduled with crawl_schedule off does nothing, daily dispatches a crawl with trigger schedule, weekly dispatches only on Mondays; crawls beyond crawl_keep are deleted with their pages and issues
|
||||
- TestCrawlTools: the nine MCP tools are listed and bound to their routes; GET tools are read-only; TestEveryAdminOperationHasTool passes with both controllers and the toolbar actions
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-14, D-10, UI-SPEC C15/C20/C23/C24 and P33-39/P33-40: controllers `golem15.seo.issues` (Site audit: list → preview, toolbar action start_crawl, bulk action ignore, record actions recheck, ignore, unignore with Applies, row state disabled issues.state_ignored, filters severity, kind, source, fix, status default open) and `golem15.seo.crawls` (Crawls: list → preview, toolbar [start_crawl, delete], record action cancel, filters status and started_at daterange); P6 `_crawl_summary.htm` and P7 `_issue_details.htm` built from curated view models in classes/partials.go with the kit classes only; navigation order of C15 (Site audit icon gauge, Crawls icon globe after Pages; Auto-links comes in 33-11). Migration 202610280006 adds crawl_schedule, crawl_max_pages, crawl_delay, crawl_keep, generic_anchors with the four-place settings pattern and the Site audit tab. Management routes: `GET /_seo/api/v1/crawls`, `GET /_seo/api/v1/crawls/{id}`, `POST /_seo/api/v1/crawls/{id}/cancel`, `DELETE /_seo/api/v1/crawls` (ids), `POST /_seo/api/v1/issues/{id}/recheck`, `POST /_seo/api/v1/issues/ignore`, `POST /_seo/api/v1/issues/unignore` and filters on `GET /issues`; MCP tools start_crawl, cancel_crawl, list_crawls, get_crawl, delete_crawls (destructive), list_issues, recheck_url, ignore_issues, unignore_issues with AdminOperations rows. schedule.go per P33-40 and `seo:crawl [--scheduled]` in commands.go (documented). README: crawler, limits, trusted mode, checks, fix routes, screens, tools, schedule. Every C23/C24/C20 key in both lang files. Tests first. Commit groups A to D.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestCrawlAdmin|TestCrawlSchedule|TestCrawlTools|TestEveryAdminOperationHasTool|TestMCPReadToolsAreGET|TestCrawlerChecks' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -30</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestCrawlAdmin, TestCrawlSchedule, TestCrawlTools or TestEveryAdminOperationHasTool missing from the "--- PASS" lines</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n '"start_crawl"\|"cancel_crawl"\|"list_crawls"\|"get_crawl"\|"delete_crawls"\|"recheck_url"\|"ignore_issues"\|"unignore_issues"' ../sm-seo-plugin/mcp.go` prints eight lines
|
||||
- `grep -n "seo:crawl" ../sm-seo-plugin/schedule.go ../sm-seo-plugin/commands.go` prints a line in each
|
||||
- `grep -n "golem15.seo.issues\|golem15.seo.crawls" ../sm-seo-plugin/admin_navigation.go` prints two lines
|
||||
</acceptance_criteria>
|
||||
<done>Editors and MCP clients can run, follow, read, recheck and ignore the audit; it also runs on a schedule.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| crawler → the site (and anything its pages link to) | outbound HTTP driven by untrusted page content |
|
||||
| crawled HTML → issue details → admin partials and MCP | untrusted text displayed to administrators |
|
||||
| admin/MCP → crawl actions | authenticated operations |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-43 | Elevation of privilege (SSRF) | crawler fetches | high | mitigate | fetchguard AllowHostsMode with only the site host and its www twin, HTTPS, private addresses blocked at dial time, redirects never followed (each hop re-checked as a new URL against the host list); TrustedMode only from Go config golem15.seo.crawl_trusted, never from page content; TestCrawlerChecks plants an external and a private-IP link that must not be fetched |
|
||||
| T-33-44 | Denial of service | crawl load on the own site | medium | mitigate | two concurrent requests, configurable delay (≥100 ms), max pages, one crawl at a time, nightly schedule |
|
||||
| T-33-45 | Denial of service | hostile page content | medium | mitigate | 5 MiB body cap, 10 s timeout, parser on x/net/html (no regex over HTML), at most 1000 links stored per page |
|
||||
| T-33-46 | Tampering (XSS in admin) | issue details from crawled text | high | mitigate | partials render view-model text through the template engine's escaping; MCP answers are JSON; details hold text, never HTML |
|
||||
| T-33-47 | Elevation of privilege | crawl and issue routes | high | mitigate | golem15.seo.manage on every route and action (manage wrapper), TestCrawlTools and the operations parity |
|
||||
| T-33-48 | Information disclosure | crawling staging | low | mitigate | trusted mode needed for http staging; staging-lock issues suppressed, P6 says why |
|
||||
| T-33-49 | Tampering | ignore fingerprints | low | accept | administrators may hide issues; unignore restores them and the ignore records author and time |
|
||||
| T-33-SC | Tampering | npm/pip/cargo installs | high | accept | no new package (x/net/html and grobotstxt are already required) |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...` after every commit.
|
||||
- Docker suite: TestCrawlerTracer, TestCrawlerChecks, TestIssueMerge, TestStagingCrawl, TestCrawlAdmin, TestCrawlSchedule, TestCrawlTools and the earlier suites.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- The crawler audits the rendered site within its limits and stays on the site's host.
|
||||
- Every issue is stored per URL with a severity and either a fixing tool or fix code.
|
||||
- Site audit, Crawls, the settings tab, the schedule and nine MCP tools work.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Package `classes/crawl`: crawler, fetch, parse, checks, links, orphans, store, fix.
|
||||
- Tables: `golem15_seo_crawls`, `golem15_seo_crawl_pages`, `golem15_seo_crawl_links`, `golem15_seo_issues`, `golem15_seo_issue_ignores`; settings `crawl_schedule`, `crawl_max_pages`, `crawl_delay`, `crawl_keep`, `generic_anchors`; migrations 202610280005, 202610280006.
|
||||
- Job kind `golem15.seo.crawl` (`CrawlArgs`); CLI `seo:crawl [--scheduled]`; schedule entry daily 02:30.
|
||||
- Issue kinds (crawl): `page_status`, `sitemap_error`, `sitemap_noindex`, `sitemap_missing`, `broken_link`, `redirected_link`, `canonical_missing`, `canonical_error`, `h1_missing`, `h1_multiple`, `heading_skipped`, `heading_empty`, `h1_title_mismatch`, `jsonld_invalid`, `jsonld_multiple`, `jsonld_required`, `jsonld_recommended`, `hreflang_reciprocal`, `hreflang_error`, `generic_anchor`, `image_alt`, `image_size`, `featured_lazy`, `content_js`, `orphan_page`; CMS additions `image_alt`, `h1_in_content`.
|
||||
- Admin: controllers `golem15.seo.issues` (Site audit), `golem15.seo.crawls` (Crawls); partials `issue_details` (P7), `crawl_summary` (P6); Site audit settings tab.
|
||||
- Routes: `POST/GET/DELETE /_seo/api/v1/crawls`, `GET /_seo/api/v1/crawls/{id}`, `POST /_seo/api/v1/crawls/{id}/cancel`, `POST /_seo/api/v1/issues/{id}/recheck`, `POST /_seo/api/v1/issues/ignore`, `POST /_seo/api/v1/issues/unignore`; `GET /_seo/api/v1/issues` extended.
|
||||
- MCP tools: `seo_start_crawl`, `seo_cancel_crawl`, `seo_list_crawls`, `seo_get_crawl`, `seo_delete_crawls`, `seo_list_issues` (extended), `seo_recheck_url`, `seo_ignore_issues`, `seo_unignore_issues`.
|
||||
- Config key: `golem15.seo.crawl_trusted`.
|
||||
- Tests: `TestCrawlerTracer`, `TestCrawlerChecks`, `TestIssueMerge`, `TestStagingCrawl`, `TestCrawlAdmin`, `TestCrawlSchedule`, `TestCrawlTools`; test site helper `crawl_site_test.go`.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-10-SUMMARY.md` when done.
|
||||
</output>
|
||||
389
.planning/phases/33-seo-output-audit-and-content/33-11-PLAN.md
Normal file
389
.planning/phases/33-seo-output-audit-and-content/33-11-PLAN.md
Normal file
@@ -0,0 +1,389 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 11
|
||||
type: execute
|
||||
wave: 7
|
||||
depends_on: ["33-10", "33-09"]
|
||||
files_modified:
|
||||
- ../sm-seo-plugin/models/autolink.go
|
||||
- ../sm-seo-plugin/models/autolink/columns.yaml
|
||||
- ../sm-seo-plugin/models/autolink/fields.yaml
|
||||
- ../sm-seo-plugin/models/registry.go
|
||||
- ../sm-seo-plugin/models/settings.go
|
||||
- ../sm-seo-plugin/models/settings/fields.yaml
|
||||
- ../sm-seo-plugin/updates/202610280007_create_golem15_seo_autolinks.go
|
||||
- ../sm-seo-plugin/updates/registry.go
|
||||
- ../sm-seo-plugin/classes/autolinks.go
|
||||
- ../sm-seo-plugin/classes/linkgraph.go
|
||||
- ../sm-seo-plugin/classes/resolver.go
|
||||
- ../sm-seo-plugin/classes/settings_write.go
|
||||
- ../sm-seo-plugin/controllers/admin_registry.go
|
||||
- ../sm-seo-plugin/controllers/autolinks.go
|
||||
- ../sm-seo-plugin/controllers/autolinks/config_list.yaml
|
||||
- ../sm-seo-plugin/controllers/autolinks/config_form.yaml
|
||||
- ../sm-seo-plugin/controllers/autolinks/config_filter.yaml
|
||||
- ../sm-seo-plugin/controllers/api/autolinks.go
|
||||
- ../sm-seo-plugin/controllers/api/links.go
|
||||
- ../sm-seo-plugin/extensions.go
|
||||
- ../sm-seo-plugin/admin_navigation.go
|
||||
- ../sm-seo-plugin/routes.go
|
||||
- ../sm-seo-plugin/mcp.go
|
||||
- ../sm-seo-plugin/operations.go
|
||||
- ../sm-seo-plugin/assets/src/elements/links.ts
|
||||
- ../sm-seo-plugin/assets/src/elements/index.ts
|
||||
- ../sm-seo-plugin/assets/src/elements/labels.ts
|
||||
- ../sm-seo-plugin/assets/src/elements/styles.css
|
||||
- ../sm-seo-plugin/assets/dist/seo.js
|
||||
- ../sm-seo-plugin/assets/dist/seo.css
|
||||
- ../sm-seo-plugin/lang/en/lang.yaml
|
||||
- ../sm-seo-plugin/lang/pl/lang.yaml
|
||||
- ../sm-seo-plugin/README.md
|
||||
- ../sm-seo-plugin/linking_test.go
|
||||
- ../sm-journal-plugin/classes/related.go
|
||||
- ../sm-journal-plugin/classes/image_variants.go
|
||||
- ../sm-journal-plugin/controllers/api/posts.go
|
||||
- ../sm-journal-plugin/controllers/api/posts_helpers.go
|
||||
- ../sm-journal-plugin/console/image_variants.go
|
||||
- ../sm-journal-plugin/models/image_variant.go
|
||||
- ../sm-journal-plugin/models/registry.go
|
||||
- ../sm-journal-plugin/updates/202610280002_create_golem15_journal_image_variants.go
|
||||
- ../sm-journal-plugin/updates/registry.go
|
||||
- ../sm-journal-plugin/jobs.go
|
||||
- ../sm-journal-plugin/plugin.go
|
||||
- ../sm-journal-plugin/config/config.yaml
|
||||
- ../sm-journal-plugin/go.mod
|
||||
- ../sm-journal-plugin/go.sum
|
||||
- ../sm-journal-plugin/README.md
|
||||
- ../sm-journal-plugin/related_media_test.go
|
||||
- ../vue-journal-layer/app/components/Journal/FeaturedImage.vue
|
||||
- ../vue-journal-layer/app/components/Journal/PostCard.vue
|
||||
- ../vue-journal-layer/app/journal-pages/PostPage.vue
|
||||
- ../vue-journal-layer/app/utils/srcset.ts
|
||||
- ../vue-journal-layer/app/utils/types.ts
|
||||
- ../vue-journal-layer/tests/srcset.test.ts
|
||||
- ../vue-journal-layer/testing/fixtures/acme/posts.json
|
||||
- ../vue-journal-layer/testing/expect-acme.txt
|
||||
- ../vue-journal-layer/README.md
|
||||
- modules/lagoon/attach/variant.go
|
||||
- modules/lagoon/attach/webp/webp.go
|
||||
- modules/lagoon/attach/webp/webp_smoke_test.go
|
||||
- modules/lagoon/attach/README.md
|
||||
- modules/lagoon/README.md
|
||||
- docs/database/attachments.md
|
||||
- go.mod
|
||||
- go.sum
|
||||
- .planning/notes/2026-10-28-webp-gen2brain.md
|
||||
- .planning/research/STACK.md
|
||||
autonomous: false
|
||||
requirements: [SC-2, SC-3, D-82, D-85, D-71, D-10]
|
||||
|
||||
estimate:
|
||||
tokens: 180000
|
||||
raw_tokens: 180000
|
||||
tasks: 5
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "SEO › Auto-links holds phrase → URL rows (per locale or all, active switch, origin, note) with the C22 list, form, filters and refusals (phrase under 3 characters, duplicate phrase in a locale, URL not a / path or http(s) address); the resolve answer of an ok page carries autolinks [{phrase, url}] for its locale without disabled rows and without links to the page itself, plus autolink_max from the Links tab (default 3, 0 to 20, 0 turns auto-linking off), which the layer applies at render (D-82)"
|
||||
- "Add focus keyphrases (toolbar action on Auto-links, also an MCP tool) creates one row per record whose focus keyphrase in a locale is not yet a phrase there, with the record's URL and origin keyphrase, and toasts the count (D-82, UI-SPEC C22)"
|
||||
- "The SEO tab shows E10 Internal links for content with a body: inbound and outbound link counts from the last finished crawl, the orphan warning when nothing links to the page, up to 10 pages this text could link to and 10 pages that could link here (titles and focus keyphrases found in the crawled text), each with Copy address; before the first crawl it says so (D-82, UI-SPEC C19)"
|
||||
- "MCP has seo_list_autolinks, seo_create_autolink, seo_update_autolink, seo_delete_autolinks, seo_autolinks_from_keyphrases and seo_get_link_suggestions; TestEveryAdminOperationHasTool maps the Auto-links controller and the seo_links widget action (D-10)"
|
||||
- "Journal related posts stay as today by default (same category, three, newest first); with golem15.journal.related_mode scored they are 3 to 6 (golem15.journal.related_count) ranked by shared tags and categories, and the post answer adds previous_in_category and next_in_category, which the journal layer renders as server-rendered links instead of the site-wide neighbours (D-82, RESEARCH Open Question 6: opt-in, porting contract kept)"
|
||||
- "WebP is encoded in Go with github.com/gen2brain/webp, recorded first in .planning/notes/2026-10-28-webp-gen2brain.md (with the 2026-10-28 benchmark) and a STACK.md row, then added to go.mod; the encoder lives in the framework sub-package modules/lagoon/attach/webp (generic media, additive, no SEO wording), so only binaries that import it link it (2026-10-28 image formats, D-85, D-90, D-106)"
|
||||
- "A Journal conga job (golem15.journal.image_variants), dispatched after a featured image upload commits and runnable for all images with journal:image-variants --all, writes thumbnails at golem15.journal.image_widths (default 480, 800, 1200) and a WebP variant of each next to the thumbnail; the upload request never encodes (2026-10-28 image formats)"
|
||||
- "The Journal API's featured_images entries gain variants [{width, height, url, webp_url}] (additive key), and the journal layer renders featured images as <picture> with a WebP source and the original format as srcset fallback, explicit width and height, alt, lazy loading in cards and eager loading with fetchpriority high for the post's main image (D-85, D-71)"
|
||||
- "AVIF is not produced (deferred); body images inserted through the editor keep their original file (the variants follow the thumbnail pipeline of attachments)"
|
||||
- "The Auto-links list shows autolinks.list_empty when empty, with Add focus keyphrases on the same toolbar (UI-SPEC empty: Auto-links list)"
|
||||
- "E10 shows notCrawled instead of counters before any crawl and none under an empty suggestion list; it is absent on create (UI-SPEC empty: E10)"
|
||||
- "E10 shows the checking line with aria-busy while loading, and a failure shows the 13px danger line with the SPA's danger toast (UI-SPEC loading and error: E10)"
|
||||
- "A 422 on the Auto-links form shows the field lines and the count banner (UI-SPEC error: save refused)"
|
||||
- {statement: "A WebP variant generated twice for the same thumbnail is written once (the job is idempotent through the bucket's Exists), and a failed encode leaves no partial file", verification: backstop}
|
||||
prohibitions:
|
||||
- requirement_id: "D-82"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "An auto-link never points a page to itself, and a disabled or other-locale phrase never reaches a page's resolve answer"
|
||||
- requirement_id: "D-85"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "Image encoding never runs inside the upload request; a slow or failing encode never fails the upload"
|
||||
artifacts:
|
||||
- path: ".planning/notes/2026-10-28-webp-gen2brain.md"
|
||||
provides: "decision note naming github.com/gen2brain/webp and the benchmark"
|
||||
contains: "github.com/gen2brain/webp"
|
||||
- path: "modules/lagoon/attach/webp/webp.go"
|
||||
provides: "WebP encoder and variant writer"
|
||||
contains: "gen2brain/webp"
|
||||
- path: "../sm-seo-plugin/classes/autolinks.go"
|
||||
provides: "phrase table service and resolve filtering"
|
||||
contains: "func "
|
||||
- path: "../sm-seo-plugin/assets/src/elements/links.ts"
|
||||
provides: "E10 golem15-seo-links"
|
||||
contains: "golem15-seo-links"
|
||||
- path: "../sm-journal-plugin/classes/image_variants.go"
|
||||
provides: "the image variants job"
|
||||
contains: "image_variants"
|
||||
key_links:
|
||||
- from: "../sm-seo-plugin/classes/resolver.go"
|
||||
to: "../sm-seo-plugin/classes/autolinks.go"
|
||||
via: "ok answers carry autolinks for the locale minus self and autolink_max"
|
||||
pattern: "autolink"
|
||||
- from: "../sm-journal-plugin/classes/image_variants.go"
|
||||
to: "modules/lagoon/attach/webp/webp.go"
|
||||
via: "the job calls webp.Variant for each thumbnail width"
|
||||
pattern: "webp\\.Variant"
|
||||
- from: "../vue-journal-layer/app/components/Journal/FeaturedImage.vue"
|
||||
to: "Journal API featured_images[].variants"
|
||||
via: "<picture> sources built by srcset.ts from variants"
|
||||
pattern: "image/webp"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan adds smart internal linking (auto-links, link suggestions with counters, related posts and neighbours in the category) and modern image formats (WebP variants with srcset).
|
||||
|
||||
<objective>
|
||||
Across four repositories (each main, not pushed; tags in 33-14):
|
||||
- sm-seo-plugin: the Auto-links table and screen with the keyphrase feed and MCP tools, autolinks in the resolve answer, E10 and its tool (D-82, D-10);
|
||||
- sm-journal-plugin: opt-in scored related posts and category neighbours (D-82), the image variants job and the API's variants (2026-10-28 image formats, D-85);
|
||||
- summercms.go: the WebP encoder in `modules/lagoon/attach/webp` after the decision note (D-85, D-90, D-106);
|
||||
- vue-journal-layer: `<picture>` with WebP and the original as fallback, category neighbours (D-85, D-71, D-82).
|
||||
|
||||
Purpose: the internal-linking and media parts of D-82 and D-85 that the earlier plans do not cover.
|
||||
|
||||
Output: commits in the four repositories; the decision note and STACK row as a planning-docs commit here before go.mod changes.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-42 (where WebP lives):** in the framework as a generic, additive media helper (`modules/lagoon/attach/webp`, package `webp`: `Encode(w io.Writer, img image.Image) error` at quality 80 and `Variant(ctx, bucket, f *attach.File, w, h int, mode string) (key string, err error)` writing `<thumb key>.webp` next to the thumbnail), with a generic hook in attach (`attach.VariantKey(thumbKey, format string) string`). It is not SEO code (D-90), it is a patch-level addition (D-106), and as a separate sub-package only binaries that import it link the encoder. The job lives in Journal because only plugins register conga jobs.
|
||||
- **P33-43 (variants table):** `golem15_journal_image_variants` (file_id, width, height, key, webp_key, created_at; unique (file_id, width)) so the API lists variants with one query instead of storage lookups.
|
||||
- **P33-44 (related options):** config keys `golem15.journal.related_mode` (category | scored, default category) and `golem15.journal.related_count` (3 to 6, default 3); the existing previous_post/next_post keys keep their meaning; previous_in_category and next_in_category (primary = first category) are added only in scored mode.
|
||||
- **P33-45 (auto-link table):** `golem15_seo_autolinks` (id, phrase, url, locale null = all, enabled, origin manual|keyphrase|mcp, note, timestamps; unique (lower(phrase), coalesce(locale, ''))); settings column autolink_max (default 3) on the Links tab; the resolve answer filters rows by locale, enabled and target ≠ the page's path, ordered by phrase length descending so longer phrases win.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-10-SUMMARY.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-09-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
framework modules/lagoon/attach/thumb.go: ThumbFilename(id, w, h, offsetX, offsetY, mode, ext), PartitionDirectory, (*File).ThumbKey(ctx, bucket, w, h, mode) (key, error), encodeImage package var (119-130) switched on ext, content-type switch ~222-228, deleteKey on failure, bucket.Exists; thumb_test.go.
|
||||
sm-seo-plugin: Links tab and settings_write.go four-place pattern (33-05), resolve Result (33-05/06 keys), crawl tables golem15_seo_crawl_pages (text), golem15_seo_crawl_links (33-10), entries' focus keyphrase (Phase 32 SEO tab), SEO tab widgets (seo_snippet, seo_graph) and the element bundle (33-06), operations.go/mcp.go.
|
||||
sm-journal-plugin: controllers/api/posts.go Show (related_posts via relatedPosts, previous_post/next_post via siblingPost), featuredImages (posts.go ~629), UploadFeaturedImage (posts.go ~357-430), jobs (none yet; follow ../sm-seo-plugin/jobs.go), config/config.yaml (33-02).
|
||||
vue-journal-layer: FeaturedImage.vue, PostCard.vue (33-09), PostPage.vue siblings nav (51-66), utils/types.ts (JournalPostSibling, featured_images).
|
||||
Benchmark (33-CONTEXT, 2026-10-28): 1200 px from a 2592×1754 photo, WebP 78 KB against JPEG q80 133 KB; about 90 ms with system libwebp loaded through purego (no cgo), about 510 ms in the WASM fallback; AVIF only about 6% smaller at 1.3× to 20× the CPU.
|
||||
Package (33-RESEARCH audit): github.com/gen2brain/webp v0.6.4 (2026-07-01, 31 versions, source github.com/gen2brain/webp), [ASSUMED] — legitimacy checked at Task 4.
|
||||
Copy: UI-SPEC C19 (E10), C22 (Auto-links) with their copy tables, C20 Links tab (autolink_max).
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Commit groups per repository staged by path; planning docs (note, STACK.md) committed here separately from the framework code commit. Every commit keeps that repository's vet/tests (`go test -short ./...`, `npm --prefix … run test`) green.
|
||||
- Resume check per repository: `git -C <repo> log --format=%s | grep -Fx '<subject>'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | seo: `feat: auto-link phrases in the resolve answer (tracer)` | TestAutolinksTracer passes |
|
||||
| 2 | seo: A `feat: auto-links screen, keyphrase feed and MCP tools`; B `feat: internal links widget with counts and suggestions` | linking tests and the operations parity pass |
|
||||
| 3 | journal: `feat: opt-in scored related posts and category neighbours`; layer: `feat: category neighbours on the post page` | related tests pass |
|
||||
| 4 | none (checkpoint answer recorded in the SUMMARY) | answer recorded |
|
||||
| 5 | here: A `docs(33-11): WebP decision note and STACK row`; framework: B `feat(lagoon): WebP variants of attachment thumbnails`; journal: C `feat: image variants job and variants in the post API`; layer: D `feat: WebP and srcset for featured images` | plan complete |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "an editor adds an auto-link phrase and the next page that resolves carries it, never on the target page itself" — one path only</name>
|
||||
<files>../sm-seo-plugin/models/autolink.go, ../sm-seo-plugin/models/registry.go, ../sm-seo-plugin/updates/202610280007_create_golem15_seo_autolinks.go, ../sm-seo-plugin/updates/registry.go, ../sm-seo-plugin/classes/autolinks.go, ../sm-seo-plugin/classes/resolver.go, ../sm-seo-plugin/classes/settings_write.go, ../sm-seo-plugin/models/settings.go, ../sm-seo-plugin/models/settings/fields.yaml, ../sm-seo-plugin/linking_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/classes/resolver.go (Outbound from 33-05, the 33-06 keys)
|
||||
- ../sm-seo-plugin/classes/settings_write.go and models/settings/fields.yaml (Links tab from 33-05)
|
||||
- ../vue-seo-layer/app/utils/bodyLinks.ts (33-09, the consumer of autolinks)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-82 and P33-45: migration 202610280007 creates golem15_seo_autolinks and the settings column autolink_max (default 3); the Links tab gets autolink_max (number, left, settings.autolink_max_comment, range 0–20) through the four-place pattern; `classes/autolinks.go` CRUD with history (so the purge of 33-05 runs) and `ForPage(ctx, locale, selfPath) ([]Autolink, error)`; resolver adds `autolinks` and `autolink_max` to ok answers (empty when autolink_max is 0). `TestAutolinksTracer` (Docker): create "lwia grzywa" → /grzyby/lwia-grzywa (all locales) and a disabled phrase; resolving another page answers autolinks [{phrase: "lwia grzywa", url: "/grzyby/lwia-grzywa"}] and autolink_max 3; resolving /grzyby/lwia-grzywa leaves it out; an en-only phrase is absent on a pl page; autolink_max 0 answers none. Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestAutolinksTracer' -count=1 -v 2>&1 | tail -15</automated>
|
||||
<fails_when>non-zero exit, "FAIL" or "no tests to run" in the output, or no "--- PASS: TestAutolinksTracer" line</fails_when>
|
||||
<automated>go -C ../sm-seo-plugin vet ./... && go -C ../sm-seo-plugin test -short ./...</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n 'json:"autolinks\|json:"autolink_max' ../sm-seo-plugin/classes/resolver.go` prints two lines
|
||||
- `grep -n "autolink_max" ../sm-seo-plugin/classes/settings_write.go ../sm-seo-plugin/models/settings/fields.yaml` prints a line in each
|
||||
</acceptance_criteria>
|
||||
<done>Auto-link phrases reach every page's resolve answer, where the layer links them.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Auto-links screen with the keyphrase feed and MCP tools; E10 internal links widget with counts and suggestions</name>
|
||||
<files>../sm-seo-plugin/models/autolink/columns.yaml, ../sm-seo-plugin/models/autolink/fields.yaml, ../sm-seo-plugin/controllers/admin_registry.go, ../sm-seo-plugin/controllers/autolinks.go, ../sm-seo-plugin/controllers/autolinks/config_list.yaml, ../sm-seo-plugin/controllers/autolinks/config_form.yaml, ../sm-seo-plugin/controllers/autolinks/config_filter.yaml, ../sm-seo-plugin/controllers/api/autolinks.go, ../sm-seo-plugin/controllers/api/links.go, ../sm-seo-plugin/classes/autolinks.go, ../sm-seo-plugin/classes/linkgraph.go, ../sm-seo-plugin/extensions.go, ../sm-seo-plugin/admin_navigation.go, ../sm-seo-plugin/routes.go, ../sm-seo-plugin/mcp.go, ../sm-seo-plugin/operations.go, ../sm-seo-plugin/assets/src/elements/links.ts, ../sm-seo-plugin/assets/src/elements/index.ts, ../sm-seo-plugin/assets/src/elements/labels.ts, ../sm-seo-plugin/assets/src/elements/styles.css, ../sm-seo-plugin/assets/dist/seo.js, ../sm-seo-plugin/assets/dist/seo.css, ../sm-seo-plugin/lang/en/lang.yaml, ../sm-seo-plugin/lang/pl/lang.yaml, ../sm-seo-plugin/README.md, ../sm-seo-plugin/linking_test.go</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/controllers/pages.go and pages/config_*.yaml (33-05 screen pattern), controllers/crawls.go (toolbar action pattern, 33-10)
|
||||
- ../sm-seo-plugin/assets/src/elements/graph.ts (33-06 widget element pattern) and tests/elements/*
|
||||
- ../sm-seo-plugin/classes/crawl/orphans.go (33-10 suggestion logic to reuse)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C15, C19, C22 and their copy)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- Auto-links list per C22 (sorted by phrase, row state disabled for inactive, filters locale, origin, active); refusals autolinks.phrase_short, phrase_taken (naming the URL), url_invalid
|
||||
- from_keyphrases adds rows for records with a focus keyphrase not yet a phrase in that locale (origin keyphrase) and toasts autolinks.keyphrases_added with the count, or keyphrases_none; running it twice adds nothing the second time
|
||||
- GET /_seo/api/v1/links?url= answers {crawledAt, inbound, outbound, orphan, out[{phrase, title, url}], in[{phrase, title, adminUrl}]} from the last finished crawl (each list at most 10); before any crawl crawledAt, inbound and outbound are null; the seo_links widget action answers the same
|
||||
- MCP lists list_autolinks, create_autolink, update_autolink, delete_autolinks (destructive), autolinks_from_keyphrases and get_link_suggestions; TestEveryAdminOperationHasTool passes
|
||||
- Element smoke: E10 renders counters, the orphan callout and both lists from a stubbed answer, notCrawled without a crawl, none under empty lists; Copy address writes the URL and shows copied
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-82, D-10 and UI-SPEC C19/C22: controller `golem15.seo.autolinks` (list 50 per page, checkboxes, setup, toolbar [create, delete, from_keyphrases], form per C22) with navigation Auto-links (icon wand-sparkles) after Pages per C15; `controllers/api/autolinks.go` (GET/POST /_seo/api/v1/autolinks, PUT /autolinks/{id}, DELETE /autolinks with ids, POST /autolinks/from-keyphrases); `classes/linkgraph.go` reads the last finished crawl for inbound/outbound counts and builds suggestions (pages whose crawled text contains this page's title or focus keyphrase, and pages whose title or keyphrase this page's text contains), reusing the orphan suggestion code; `controllers/api/links.go` GET /_seo/api/v1/links; extensions.go adds seo_links (type widget, action seo_links, context update) after seo_graph, omitted for types whose records have no body (Words nil). Element `golem15-seo-links` per C19 (light DOM, `--c-*` colours, ui-locale labels for every E10 key, navigator.clipboard with the hidden-button fallback). Tools and AdminOperations rows. Rebuild dist. Tests first. Commit groups A and B.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-seo-plugin test ./... -run 'TestAutolinks|TestLinkSuggestions|TestEveryAdminOperationHasTool|TestMCPReadToolsAreGET' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -20</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestAutolinks or TestLinkSuggestions missing from the "--- PASS" lines</fails_when>
|
||||
<automated>npm --prefix ../sm-seo-plugin run test 2>&1 | tail -10 && bash ../sm-seo-plugin/scripts/check-dist.sh</automated>
|
||||
<fails_when>non-zero exit, a failed count above 0 in the vitest summary, or the dist check reporting a difference</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n '"list_autolinks"\|"create_autolink"\|"update_autolink"\|"delete_autolinks"\|"autolinks_from_keyphrases"\|"get_link_suggestions"' ../sm-seo-plugin/mcp.go` prints six lines
|
||||
- `grep -n "golem15-seo-links" ../sm-seo-plugin/assets/src/elements/index.ts` prints one line
|
||||
- `grep -n "golem15.seo.autolinks" ../sm-seo-plugin/admin_navigation.go` prints one line
|
||||
</acceptance_criteria>
|
||||
<done>Editors manage auto-links and see linking suggestions with counters in the SEO tab; MCP can do the same.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: Opt-in scored related posts and category neighbours (Journal API and layer)</name>
|
||||
<files>../sm-journal-plugin/classes/related.go, ../sm-journal-plugin/controllers/api/posts.go, ../sm-journal-plugin/controllers/api/posts_helpers.go, ../sm-journal-plugin/config/config.yaml, ../sm-journal-plugin/README.md, ../sm-journal-plugin/related_media_test.go, ../vue-journal-layer/app/journal-pages/PostPage.vue, ../vue-journal-layer/app/utils/types.ts, ../vue-journal-layer/testing/fixtures/acme/posts.json, ../vue-journal-layer/testing/expect-acme.txt, ../vue-journal-layer/README.md</files>
|
||||
<read_first>
|
||||
- ../sm-journal-plugin/controllers/api/posts_helpers.go (relatedPosts 152-172, siblingPost 122-148) and posts.go Show (147-154)
|
||||
- ../vue-journal-layer/app/journal-pages/PostPage.vue (siblings nav 51-66) and app/utils/types.ts
|
||||
</read_first>
|
||||
<behavior>
|
||||
- Default mode: Show answers exactly as before (journal_api_matrix_test.go unchanged)
|
||||
- related_mode scored, related_count 5: up to 5 published posts other than the post, ranked by shared tags (2 points each) plus shared categories (1 point each), ties by newest; count outside 3–6 is clamped; previous_in_category and next_in_category are the neighbours by published_at within the post's first category
|
||||
- The layer renders previous_in_category/next_in_category links (server-rendered <a href> with the title in the anchor text) when present, else the existing site-wide neighbours
|
||||
</behavior>
|
||||
<action>
|
||||
Per D-82 and P33-44: `classes/related.go` with the scoring query (one SQL with counts, published only for non-editors) and the category neighbours; Show uses it only in scored mode and adds the two keys; config/config.yaml documents both keys; README section. Layer PostPage prefers the in-category neighbours; types.ts adds them; a fixture post with them and an expectation line. Tests first (`TestRelatedScored`, `TestRelatedDefaultUnchanged` in related_media_test.go). Commit as listed.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go -C ../sm-journal-plugin test ./... -run 'TestRelatedScored|TestRelatedDefaultUnchanged|TestJournalAPIMatrix' -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -10</automated>
|
||||
<fails_when>a "FAIL" line, "no tests to run", or TestRelatedScored missing from the "--- PASS" lines</fails_when>
|
||||
<automated>npm --prefix ../vue-journal-layer run test 2>&1 | tail -6</automated>
|
||||
<fails_when>non-zero exit, or a "# fail" count above 0 or a "not ok" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "golem15.journal.related_mode\|golem15.journal.related_count" ../sm-journal-plugin/classes/related.go ../sm-journal-plugin/config/config.yaml` prints at least two lines
|
||||
- `grep -n "previous_in_category" ../vue-journal-layer/app/journal-pages/PostPage.vue` prints at least one line
|
||||
</acceptance_criteria>
|
||||
<done>Sites can switch on richer related posts and category neighbours without changing the default answer.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 4: Package legitimacy of github.com/gen2brain/webp before it enters go.mod</name>
|
||||
<what-built>Nothing is installed yet. 33-RESEARCH.md's Package Legitimacy Audit marks github.com/gen2brain/webp [ASSUMED]: the npm/pypi/crates seam cannot check Go modules, so only proxy.golang.org existence was confirmed (v0.6.4, 2026-07-01, 31 versions since v0.1.0 in 2024-03). The 2026-10-28 decision (33-CONTEXT) chose it; this checkpoint verifies the package itself before any download.</what-built>
|
||||
<how-to-verify>
|
||||
1. Open https://pkg.go.dev/github.com/gen2brain/webp and https://github.com/gen2brain/webp: the module path matches, the repository is the author's (gen2brain also maintains gen2brain/avif and go-fitz), the licence is permissive, and the latest tag is v0.6.4 or newer.
|
||||
2. Check the README: libwebp through purego when the system library is present, a WASM build through wazero otherwise, no cgo.
|
||||
3. Check proxy.golang.org lists the version to pin: https://proxy.golang.org/github.com/gen2brain/webp/@v/list
|
||||
4. Answer "approved vX.Y.Z" (the version to pin) or "rejected: <reason>".
|
||||
</how-to-verify>
|
||||
<resume-signal>Reply "approved vX.Y.Z" or "rejected: <reason>" (rejected: Task 5 stops and the SUMMARY records WebP as not delivered for the decision to be revisited)</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 5: WebP decision note, the framework encoder sub-package, the Journal variants job and API, and srcset in the layer</name>
|
||||
<files>.planning/notes/2026-10-28-webp-gen2brain.md, .planning/research/STACK.md, modules/lagoon/attach/variant.go, modules/lagoon/attach/webp/webp.go, modules/lagoon/attach/webp/webp_smoke_test.go, modules/lagoon/attach/README.md, modules/lagoon/README.md, docs/database/attachments.md, go.mod, go.sum, ../sm-journal-plugin/classes/image_variants.go, ../sm-journal-plugin/console/image_variants.go, ../sm-journal-plugin/models/image_variant.go, ../sm-journal-plugin/models/registry.go, ../sm-journal-plugin/updates/202610280002_create_golem15_journal_image_variants.go, ../sm-journal-plugin/updates/registry.go, ../sm-journal-plugin/jobs.go, ../sm-journal-plugin/plugin.go, ../sm-journal-plugin/controllers/api/posts.go, ../sm-journal-plugin/config/config.yaml, ../sm-journal-plugin/go.mod, ../sm-journal-plugin/go.sum, ../sm-journal-plugin/README.md, ../sm-journal-plugin/related_media_test.go, ../vue-journal-layer/app/utils/srcset.ts, ../vue-journal-layer/app/components/Journal/FeaturedImage.vue, ../vue-journal-layer/app/components/Journal/PostCard.vue, ../vue-journal-layer/app/utils/types.ts, ../vue-journal-layer/tests/srcset.test.ts, ../vue-journal-layer/testing/fixtures/acme/posts.json, ../vue-journal-layer/testing/expect-acme.txt, ../vue-journal-layer/README.md</files>
|
||||
<read_first>
|
||||
- .planning/notes/2026-10-27-robots-txt-grobotstxt.md and .planning/notes/2026-10-07-embedded-admin-release-gate.md (decision note format), .planning/research/STACK.md (row format)
|
||||
- modules/lagoon/attach/thumb.go (ThumbKey 154-243, encodeImage 119-130, content types, deleteKey, Exists) and thumb_test.go
|
||||
- docs/database/attachments.md and modules/lagoon/attach/README.md
|
||||
- ../sm-journal-plugin/controllers/api/posts.go (UploadFeaturedImage, featuredImages) and ../sm-seo-plugin/jobs.go (job pattern)
|
||||
- ../vue-journal-layer/app/components/Journal/FeaturedImage.vue and PostCard.vue
|
||||
</read_first>
|
||||
<precondition>Task 4 answered "approved vX.Y.Z" for github.com/gen2brain/webp</precondition>
|
||||
<action>
|
||||
Per the 2026-10-28 image-format decision, D-85, D-71 and P33-42/P33-43, in this order:
|
||||
- (A, here, before any go.mod change) write `.planning/notes/2026-10-28-webp-gen2brain.md`: decision (WebP variants per thumbnail size in a conga job; AVIF deferred), the dependency github.com/gen2brain/webp at the approved version, how it runs (purego libwebp or WASM, no cgo), the benchmark from 33-CONTEXT, where the code lives (P33-42 and why it is generic media, not SEO), and that editor body images keep their original file; add the STACK.md row; commit as planning docs.
|
||||
- (B, framework) `go get github.com/gen2brain/webp@<approved>`; `modules/lagoon/attach/variant.go`: `VariantKey(thumbKey, format string) string` (thumb key with the extension replaced by the format, the same token rule as ThumbFilename); `modules/lagoon/attach/webp/webp.go`: `Encode` (quality 80) and `Variant` (ThumbKey first, return early when the variant exists, encode from the thumbnail image, ContentType image/webp, delete the key on any encode or close error); `webp_smoke_test.go` encodes a generated image and asserts the RIFF/WEBP header and idempotence on a memblob bucket; README rows and docs/database/attachments.md section (no SEO words); `go vet ./... && go test -short ./...` green; commit.
|
||||
- (C, journal) migration and model of P33-43; `classes/image_variants.go`: `ImageVariantsArgs{FileIDs []uint}` (kind golem15.journal.image_variants, conga.MaxAttempts(3)) generating each width of `golem15.journal.image_widths` (default [480, 800, 1200]; widths larger than the original are skipped) through attach.ThumbKey and webp.Variant and upserting rows; dispatched with lagoon.AfterCommit from UploadFeaturedImage and the admin featured-image upload; `journal:image-variants [--all]` backfills; featuredImages adds `variants` (one query) to each entry; go.mod keeps the framework replace; `TestImageVariants` in related_media_test.go (Docker): an upload commits, the job writes three widths with WebP keys, the API lists variants, a second run writes nothing new, the upload response time does not include encoding (job dispatched, not run inline); commit.
|
||||
- (D, layer) `app/utils/srcset.ts` (pure: srcset strings for WebP and the original from variants plus the original's width) and tests; FeaturedImage.vue renders `<picture>` with `<source type="image/webp" srcset sizes>` and `<img src srcset sizes width height alt>` (lazy in cards, eager with fetchpriority high on the post page, decoding async), unchanged when variants are absent; fixtures and an expectation line containing image/webp; README; commit.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go test ./modules/lagoon/attach/... -count=1 -v 2>&1 | grep -E '^(--- |FAIL|ok)' | tail -10 && go vet ./... && go test -short ./...</automated>
|
||||
<fails_when>non-zero exit, a "FAIL" line, or no "ok" line for the webp package</fails_when>
|
||||
<automated>go -C ../sm-journal-plugin test ./... -run 'TestImageVariants' -count=1 -v 2>&1 | tail -10</automated>
|
||||
<fails_when>non-zero exit, "FAIL" or "no tests to run", or no "--- PASS: TestImageVariants" line</fails_when>
|
||||
<automated>npm --prefix ../vue-journal-layer run test 2>&1 | tail -6 && npm --prefix ../vue-journal-layer run build:playground 2>&1 | tail -2 && node ../vue-journal-layer/testing/smoke-ssr.mjs --output ../vue-journal-layer/.playground/.output --fixtures ../vue-journal-layer/testing/fixtures/acme --expect ../vue-journal-layer/testing/expect-acme.txt 2>&1 | tail -8</automated>
|
||||
<fails_when>non-zero exit from any command, or a "not ok" or "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `git log --format=%s -- .planning/notes/2026-10-28-webp-gen2brain.md` shows a commit older than the first commit that changes go.mod with gen2brain (`git log --format=%H -S gen2brain -- go.mod`)
|
||||
- `grep -n "github.com/gen2brain/webp" go.mod .planning/research/STACK.md .planning/notes/2026-10-28-webp-gen2brain.md` prints a line in each
|
||||
- `grep -rln "gen2brain" modules --include=*.go` lists only files under modules/lagoon/attach/webp/
|
||||
- `grep -n '"variants"' ../sm-journal-plugin/controllers/api/posts.go` prints one line; `grep -n "image/webp" ../vue-journal-layer/app/components/Journal/FeaturedImage.vue` prints one line
|
||||
- `bash scripts/check-phase33.sh --additive --marker` passes (attach changes are additive and name no SEO concept)
|
||||
</acceptance_criteria>
|
||||
<done>Featured images get WebP variants at three widths from a background job, and the sites serve them with srcset and the original as fallback.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| admin/MCP → auto-link table | untrusted phrases and URLs later rendered into every page |
|
||||
| uploaded images → encoder | untrusted image bytes decoded and encoded in a job |
|
||||
| crawl data → E10 | crawled text shown to administrators |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-50 | Tampering (XSS) | auto-link phrases and URLs | high | mitigate | URL must be a / path or an http(s) URL (javascript: and data: refused), phrase is text; the layer inserts them into text nodes with attribute escaping (33-09); TestAutolinks covers the refusals |
|
||||
| T-33-51 | Denial of service | image decoding in the job | medium | mitigate | attach's existing original-size cap (errOriginalTooLarge) applies before resizing; the job has attempts and runs outside the request; widths larger than the original skipped |
|
||||
| T-33-52 | Tampering | supply chain of the WebP encoder | high | mitigate | human legitimacy checkpoint (Task 4), decision note and STACK row before go.mod, exact version pinned in go.sum |
|
||||
| T-33-53 | Elevation of privilege | auto-links, links and keyphrase tools | high | mitigate | golem15.seo.manage on every route and action, operations parity test |
|
||||
| T-33-54 | Information disclosure | E10 suggestions | low | accept | suggestions come from the public pages the crawler fetched |
|
||||
| T-33-SC | Tampering | npm/pip/cargo/Go installs | high | mitigate | package-legitimacy gate: github.com/gen2brain/webp is [ASSUMED] and gated by the blocking human checkpoint Task 4; no npm package added |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- sm-seo-plugin: vet, `test -short`, Docker suites TestAutolinksTracer, TestAutolinks, TestLinkSuggestions and the parity tests; element tests and the dist check.
|
||||
- sm-journal-plugin: TestRelatedScored, TestRelatedDefaultUnchanged, TestImageVariants and the API matrix.
|
||||
- framework: `go vet ./... && go test -short ./...`, the attach tests, `check-phase33.sh --additive --marker`.
|
||||
- vue-journal-layer: tests, playground build and smoke.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Auto-links, link suggestions with counters, scored related posts and category neighbours work.
|
||||
- WebP variants with srcset are served, after the note and the legitimacy checkpoint.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Notes: `.planning/notes/2026-10-28-webp-gen2brain.md`; STACK.md row for `github.com/gen2brain/webp`.
|
||||
- Framework: `attach.VariantKey`; package `modules/lagoon/attach/webp` with `webp.Encode` and `webp.Variant`; go.mod require `github.com/gen2brain/webp`.
|
||||
- sm-seo-plugin: table `golem15_seo_autolinks`, settings `autolink_max`, migration 202610280007, controller `golem15.seo.autolinks`, routes `GET/POST /_seo/api/v1/autolinks`, `PUT /_seo/api/v1/autolinks/{id}`, `DELETE /_seo/api/v1/autolinks`, `POST /_seo/api/v1/autolinks/from-keyphrases`, `GET /_seo/api/v1/links`, widget action `seo_links`, element `golem15-seo-links` (E10), resolve keys `autolinks`, `autolink_max`, MCP tools `seo_list_autolinks`, `seo_create_autolink`, `seo_update_autolink`, `seo_delete_autolinks`, `seo_autolinks_from_keyphrases`, `seo_get_link_suggestions`.
|
||||
- sm-journal-plugin: config keys `golem15.journal.related_mode`, `golem15.journal.related_count`, `golem15.journal.image_widths`; table `golem15_journal_image_variants` (migration 202610280002); job kind `golem15.journal.image_variants` (`ImageVariantsArgs`); CLI `journal:image-variants [--all]`; API keys `previous_in_category`, `next_in_category`, `featured_images[].variants`.
|
||||
- vue-journal-layer: `app/utils/srcset.ts`, `<picture>` in FeaturedImage, category neighbours on the post page.
|
||||
- Tests: `TestAutolinksTracer`, `TestAutolinks`, `TestLinkSuggestions`, `TestRelatedScored`, `TestRelatedDefaultUnchanged`, `TestImageVariants`, `webp_smoke_test.go`, `tests/srcset.test.ts`.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-11-SUMMARY.md` when done; record the Task 4 answer and the pinned version.
|
||||
</output>
|
||||
237
.planning/phases/33-seo-output-audit-and-content/33-12-PLAN.md
Normal file
237
.planning/phases/33-seo-output-audit-and-content/33-12-PLAN.md
Normal file
@@ -0,0 +1,237 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 12
|
||||
type: execute
|
||||
wave: 8
|
||||
depends_on: ["33-11"]
|
||||
files_modified:
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-12-sm-demo-app.patch
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-12-vue-demo-app.patch
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-12-sm-summercmsio-app.patch
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-12-vue-summercmsio-app.patch
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-12-local-wiring.md
|
||||
- ../sm-bm-app/frontend/public/robots.txt
|
||||
- ../sm-bm-app/frontend/index.html
|
||||
- ../sm-bm-app/deploy/nginx/bm.jakubzych.com.conf
|
||||
- ../sm-bm-app/scripts/check-noindex.sh
|
||||
- ../sm-bm-app/DEPLOY.md
|
||||
autonomous: true
|
||||
requirements: [SC-1, SC-2, D-72, D-70, D-23, D-97, D-33, D-22, D-30, D-34]
|
||||
|
||||
estimate:
|
||||
tokens: 120000
|
||||
raw_tokens: 120000
|
||||
tasks: 3
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Against local links (scratch worktrees wired to the sibling repositories with go.work and pnpm link overrides; nothing pushed or tagged), the demo stack serves a Journal post through Nuxt with the CMS title, one canonical, one JSON-LD @graph, hreflang and breadcrumbs, /sitemap.xml as an index of per-type files through the layer's root proxy, and a redirect from the SEO plugin enforced by the layer (SC-1, SC-2, 2026-10-28 release cadence)"
|
||||
- "The demo's client-only routes /p/** and /presentations/** are declared in seo.noindexRoutes, so its build passes the SSR guard and those routes send X-Robots-Tag noindex, nofollow; removing the declaration makes the build fail (D-70)"
|
||||
- "The demo's hand-written robots meta on login, register, connect and the signed-in pages is replaced by page meta (seo.robots for auth pages, requiresAuth for signed-in pages), so the layer marks them automatically (D-23)"
|
||||
- "The demo reports its static routes to the page registry at server start and links the HTML sitemap from its footer (D-33, D-34)"
|
||||
- "summercms.io's changelog site (Journal on the journal layer, no SEO plugin mounted) runs with seo.cms false: it keeps its titles through the journal layer's fallback meta, passes the SSR guard, and its changelog smoke passes with the updated card and heading markup; the main site keeps its own @nuxtjs/seo static sitemap (RESEARCH Open Question 7: pin bumps and build guard only)"
|
||||
- "sm-bm-app has no indexable pages: its frontend serves robots.txt with User-agent: * and Disallow: /, index.html carries <meta name=\"robots\" content=\"noindex, nofollow\">, and nginx adds X-Robots-Tag: noindex, nofollow to every response; there is no SSR migration (D-72)"
|
||||
- "The app changes that depend on new tags are captured as patches in the phase directory (one per repository) that apply cleanly to each repository's current HEAD; 33-14 applies them after the tags with real pins; sm-bm-app's change needs no tag and is committed locally (2026-10-28 release cadence)"
|
||||
- "33-12-local-wiring.md records the exact local-link wiring commands so 33-13 and 33-14 can repeat them"
|
||||
prohibitions:
|
||||
- requirement_id: "D-72"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "sm-bm-app never becomes indexable: robots.txt, the meta tag and the header all say noindex/Disallow"
|
||||
- requirement_id: "D-70"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: judgment
|
||||
statement: "A noindex declaration in the demo covers only routes that are really client-only or private; no public content route is declared noindex to pass the guard"
|
||||
artifacts:
|
||||
- path: ".planning/phases/33-seo-output-audit-and-content/33-12-sm-demo-app.patch"
|
||||
provides: "demo backend config, tests and smoke script for 33-14"
|
||||
contains: "diff --git"
|
||||
- path: ".planning/phases/33-seo-output-audit-and-content/33-12-vue-demo-app.patch"
|
||||
provides: "demo Nuxt config: noindex routes, page meta, footer link"
|
||||
contains: "noindexRoutes"
|
||||
- path: "../sm-bm-app/scripts/check-noindex.sh"
|
||||
provides: "D-72 check"
|
||||
contains: "Disallow: /"
|
||||
key_links:
|
||||
- from: "demo Nuxt (vue-demo-app)"
|
||||
to: "demo Go binary"
|
||||
via: "vue-seo-layer middleware resolves through NUXT_SEO_API_BASE; root files proxied through NUXT_SEO_BACKEND_BASE"
|
||||
pattern: "NUXT_SEO_API_BASE"
|
||||
- from: "../sm-bm-app/deploy/nginx/bm.jakubzych.com.conf"
|
||||
to: "every bm response"
|
||||
via: "add_header X-Robots-Tag \"noindex, nofollow\" always"
|
||||
pattern: "X-Robots-Tag"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan proves the phase end to end on the demo against local links, prepares summercms.io's pin bumps, and closes D-72 on sm-bm-app.
|
||||
|
||||
<objective>
|
||||
- sm-demo-app + vue-demo-app: wire every Phase 33 repository locally, run the stack, and prepare the committable changes (noindex routes, page meta, footer link, config, a Docker test and an SEO smoke script) as patches for 33-14.
|
||||
- sm-summercmsio-app + vue-summercmsio-app: prepare the Journal and layer pin bumps with `seo.cms: false` as patches; check the build guard and the changelog smoke.
|
||||
- sm-bm-app: D-72 (robots.txt Disallow, meta noindex, X-Robots-Tag), committed locally.
|
||||
|
||||
Purpose: SC-1/SC-2 on a real app before the release; D-72.
|
||||
|
||||
Output: four patch files and a wiring note in the phase directory (planning docs commit here), and local commits in sm-bm-app. Nothing is pushed, tagged or deployed (2026-10-28 release cadence: tags and app re-pins in 33-14).
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-46 (local wiring, never committed):** a scratch directory outside every repository holds detached worktrees of sm-demo-app, vue-demo-app (from its submodule repository), sm-summercmsio-app and vue-summercmsio-app at HEAD. Go: a scratch go.work using the worktree plus the sibling plugin checkouts (absolute paths) and replacing the framework with ../summercms.go. Nuxt: pnpm overrides in the scratch worktree pointing vue-seo-layer, vue-journal-layer, vue-menu-layer and vue-faq-layer to the sibling checkouts (`link:`). The commands go into 33-12-local-wiring.md.
|
||||
- **P33-47 (patch contents):** each patch holds only the changes that stay after the release (config, pages, tests, scripts, docs), generated with `git diff --binary` in the worktree (new files added with `git add -N`), never the wiring; it must `git apply --check` against the repository's current HEAD.
|
||||
- **P33-48 (demo noindex set):** noindexRoutes `/p/**` and `/presentations/**` (client-only decks); page meta `seo: {robots: 'noindex, nofollow'}` on login, register, connect and link-admin; `requiresAuth: true` on account/security and subscriptions; quizzes and roadmap keep the CMS answer (public) unless their current noindex is intentional, in which case they move to page meta with that value.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-release-log.md
|
||||
@.planning/phases/32-seo-foundation/32-05-SUMMARY.md
|
||||
@.planning/phases/32-seo-foundation/32-06-SUMMARY.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
Demo: ../sm-demo-app (go.mod requires tags, go.work uses ./plugins/golem15/*, summer.yaml mounts golem15.sitemap and golem15.seo, config/golem15.seo.yaml, deploy/nginx/demo.summercms.io.conf, DEPLOY.md, go_mod_test.go TestGoModRequiresTags, seo_mount_test.go); ../sm-demo-app/vue-demo-app (submodule repository git.golem15.com/golem15/vue-demo-app: nuxt.config.ts routeRules '/p/**' and '/presentations/**' ssr false, @nuxtjs/seo robots/sitemapUrl config, pages with useSeoMeta robots noindex: login, register, connect, roadmap, quizzes/[slug], presentations/*, account/security, p/[slugHash]).
|
||||
summercms.io: ../sm-summercmsio-app (requires summercms v0.5.0 and sm-journal-plugin v0.1.0; plugins/golem15/journal submodule), ../sm-summercmsio-app/vue-summercmsio-app (vue-journal-layer v0.6.0 pin, @nuxtjs/seo 5.2.1, scripts generate, build:changelog, test:changelog with changelog/testing/expect.txt).
|
||||
bm: ../sm-bm-app/frontend (Vite SPA: index.html, public/), deploy/nginx/bm.jakubzych.com.conf, DEPLOY.md; another session's uncommitted .planning changes in that repository stay untouched.
|
||||
Layer runtime config (33-07): NUXT_SEO_API_BASE, NUXT_SEO_BACKEND_BASE, NUXT_SEO_NOTFOUND_TOKEN, NUXT_SEO_ROUTE_REPORT_TOKEN; options seo.cms, seo.noindexRoutes; page meta requiresAuth, seo.robots; <SeoSitemapLink>.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Planning-docs commits here: the patches and the wiring note (`docs(33-12): app patches for the release`). sm-bm-app commits staged by path (`git -C ../sm-bm-app add <paths>`); its other-session `.planning` changes stay uncommitted.
|
||||
- Resume check: `git log --format=%s | grep -Fx 'docs(33-12): app patches for the release'` here; `git -C ../sm-bm-app log --format=%s | grep -Fx 'feat: keep the app out of search engines (noindex, Disallow)'`.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | none (scratch run; results recorded in the SUMMARY) | the SEO smoke passes against the local stack |
|
||||
| 2 | here: `docs(33-12): app patches for the release` (all four patches and the wiring note) | patches apply with git apply --check |
|
||||
| 3 | bm: `feat: keep the app out of search engines (noindex, Disallow)` | check-noindex.sh passes |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "a visitor and a crawler see the demo's Journal post with CMS head tags, one graph, breadcrumbs and the sitemap index, through Nuxt on local links" — one path only</name>
|
||||
<files>.planning/phases/33-seo-output-audit-and-content/33-12-local-wiring.md</files>
|
||||
<read_first>
|
||||
- ../sm-demo-app/DEPLOY.md (local run, environment), ../sm-demo-app/go.work, ../sm-demo-app/summer.yaml, ../sm-demo-app/vue-demo-app/nuxt.config.ts
|
||||
- .planning/phases/32-seo-foundation/32-05-SUMMARY.md ("Scratch run" section: the worktree procedure used for the demo in Phase 32)
|
||||
- ../vue-seo-layer/README.md (runtime config) and ../sm-seo-plugin/README.md (config keys)
|
||||
</read_first>
|
||||
<action>
|
||||
Per P33-46 and the 2026-10-28 release cadence: create the scratch directory and worktrees, wire Go (scratch go.work with the sibling sm-journal-plugin, sm-sitemap-plugin, sm-seo-plugin and the framework replace) and Nuxt (pnpm overrides to the four sibling layers), build the demo binary with `summer build` against the wiring, migrate a scratch database (the demo's compose.yaml Postgres or testcontainers), seed one Journal post with a category and a translation, run the Go binary and the Nuxt server with NUXT_SEO_API_BASE, NUXT_SEO_BACKEND_BASE and the tokens set, and run the sitemap rebuild. Then check through the Nuxt server (curl): the post page has one `<script type="application/ld+json">`, one `rel="canonical"`, hreflang links, a nav.seo-breadcrumbs and the CMS title; /sitemap.xml answers an index whose files answer through the layer; a redirect created through the SEO API answers 301 from Nuxt; /p/x answers X-Robots-Tag noindex, nofollow; the registry lists the reported static routes. Write the commands and checks as a runnable script `scripts/smoke-seo.sh BASE_URL` inside the demo worktree (it becomes part of the patch in Task 2) and record every wiring command in 33-12-local-wiring.md.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>bash "$SCRATCH/sm-demo-app/scripts/smoke-seo.sh" http://127.0.0.1:3020 2>&1 | tail -20</automated>
|
||||
<fails_when>non-zero exit, a "FAIL" line, or no final "smoke-seo: ok" line ($SCRATCH is the scratch directory recorded in 33-12-local-wiring.md)</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- 33-12-local-wiring.md lists the worktree, go.work and pnpm override commands with absolute sibling paths
|
||||
- smoke-seo.sh checks at least: one ld+json, one canonical, breadcrumbs, the sitemap index and one file, a 301 from the SEO plugin, the noindex header on /p/x
|
||||
- the SUMMARY records the smoke output
|
||||
</acceptance_criteria>
|
||||
<done>The whole phase works together on a real app before anything is released.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: Demo and summercms.io release patches (noindex routes, page meta, footer link, config, Docker test, changelog site on cms false)</name>
|
||||
<files>.planning/phases/33-seo-output-audit-and-content/33-12-sm-demo-app.patch, .planning/phases/33-seo-output-audit-and-content/33-12-vue-demo-app.patch, .planning/phases/33-seo-output-audit-and-content/33-12-sm-summercmsio-app.patch, .planning/phases/33-seo-output-audit-and-content/33-12-vue-summercmsio-app.patch, .planning/phases/33-seo-output-audit-and-content/33-12-local-wiring.md</files>
|
||||
<read_first>
|
||||
- the scratch worktrees from Task 1
|
||||
- ../sm-demo-app/seo_mount_test.go, boot_test.go, go_mod_test.go (Docker test patterns)
|
||||
- ../sm-summercmsio-app/vue-summercmsio-app/nuxt.config.ts, changelog/ (nuxt.config.ts and testing/expect.txt)
|
||||
- .planning/phases/32-seo-foundation/32-05-demo-mount.patch (patch precedent)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-70, D-23, D-33, D-34, D-97 and P33-47/P33-48, in the scratch worktrees: vue-demo-app nuxt.config.ts adds `seo: {noindexRoutes: ['/p/**', '/presentations/**']}` and removes the @nuxtjs/seo-only keys (robots, the sitemap URL setting) the journal layer no longer understands; pages switch their hand-written robots meta to page meta per P33-48; the footer renders `<SeoSitemapLink>`; the build passes the guard and fails when the noindexRoutes line is removed (check once, then restore). sm-demo-app: config/golem15.seo.yaml (route_report_token from the environment), config/golem15.sitemap.yaml (site_url), DEPLOY.md (new NUXT_SEO_* variables, `/_sitemap/` not exposed, root files served by the layer), deploy/nginx/demo.summercms.io.conf (drop any sitemap.xsl location), `seo_output_test.go` (Docker: sitemap index served, /_seo/api/v1/site answers, resolve of a seeded post carries jsonld and breadcrumbs), and scripts/smoke-seo.sh from Task 1. vue-summercmsio-app: `seo: {cms: false}` for the changelog app, changelog/testing/expect.txt updated for the journal layer's card and heading markup; `npm run generate` and `test:changelog` pass on the wiring. sm-summercmsio-app: when nothing beyond the later pin bumps is needed, 33-12-sm-summercmsio-app.patch holds the single line `# no change beyond the pin bumps in 33-14` (git apply treats it as an empty patch and 33-14 skips it). Export one patch per repository (P33-47), check each with `git -C <repo> apply --check <patch>` against the live repository's HEAD, and commit the patches and the updated wiring note here.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>for p in sm-demo-app vue-demo-app; do r=../$p; [ "$p" = vue-demo-app ] && r=../sm-demo-app/vue-demo-app; git -C "$r" apply --check "$PWD/.planning/phases/33-seo-output-audit-and-content/33-12-$p.patch" || exit 1; done; echo patches-ok</automated>
|
||||
<fails_when>non-zero exit, an "error:" line from git apply, or no "patches-ok" line</fails_when>
|
||||
<automated>grep -c "noindexRoutes" .planning/phases/33-seo-output-audit-and-content/33-12-vue-demo-app.patch</automated>
|
||||
<fails_when>output 0 or a missing file</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- the demo patch contains seo_output_test.go and scripts/smoke-seo.sh; the vue-demo-app patch contains no `useSeoMeta(` line with a hard-coded robots value
|
||||
- the summercms.io patch (or its note) sets seo.cms false for the changelog app
|
||||
- the SUMMARY records: demo build passing, the guard failing without the declaration, generate and test:changelog passing
|
||||
</acceptance_criteria>
|
||||
<done>The app changes are ready to apply on top of the release tags.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 3: sm-bm-app stays out of search engines (D-72)</name>
|
||||
<files>../sm-bm-app/frontend/public/robots.txt, ../sm-bm-app/frontend/index.html, ../sm-bm-app/deploy/nginx/bm.jakubzych.com.conf, ../sm-bm-app/scripts/check-noindex.sh, ../sm-bm-app/DEPLOY.md</files>
|
||||
<read_first>
|
||||
- ../sm-bm-app/frontend/index.html, frontend/package.json (build script), deploy/nginx/bm.jakubzych.com.conf, DEPLOY.md, .claude/CLAUDE.md
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-72: add frontend/public/robots.txt (`User-agent: *` and `Disallow: /`), the robots meta `noindex, nofollow` in index.html's head, and `add_header X-Robots-Tag "noindex, nofollow" always;` in each server block of the nginx conf (and in every location that sets its own add_header, since nginx does not inherit add_header there). `scripts/check-noindex.sh` builds the frontend (`npm --prefix frontend run build`) and checks dist/robots.txt, dist/index.html's meta and the conf's header in every server block, printing `check-noindex: ok` or failing. DEPLOY.md notes the header and the check. Commit as listed (local, not pushed).
|
||||
</action>
|
||||
<verify>
|
||||
<automated>bash ../sm-bm-app/scripts/check-noindex.sh 2>&1 | tail -5</automated>
|
||||
<fails_when>non-zero exit, or no "check-noindex: ok" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- `grep -n "Disallow: /" ../sm-bm-app/frontend/public/robots.txt` prints one line
|
||||
- `grep -c "X-Robots-Tag" ../sm-bm-app/deploy/nginx/bm.jakubzych.com.conf` is at least the number of server blocks listening on 443
|
||||
- `git -C ../sm-bm-app status --short .planning` still shows the other session's changes, uncommitted
|
||||
</acceptance_criteria>
|
||||
<done>The internal app tells every crawler to stay out, by file, meta and header.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| scratch stack → local services | local-only run with test credentials |
|
||||
| bm public host → crawlers | an internal app reachable on the internet |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-55 | Information disclosure | bm indexed by search engines | medium | mitigate | robots.txt Disallow, meta noindex and X-Robots-Tag on every response, checked by check-noindex.sh |
|
||||
| T-33-56 | Information disclosure | tokens in the scratch run | low | mitigate | tokens generated per run into the scratch environment only, never written into the patches or the wiring note |
|
||||
| T-33-57 | Tampering | patches applied later | medium | mitigate | git apply --check against current HEADs now and again in 33-14 before applying; patches reviewed in 33-14's release checkpoint |
|
||||
| T-33-SC | Tampering | npm installs | high | accept | no new package; layers come from local sibling checkouts |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- smoke-seo.sh passes against the local demo stack.
|
||||
- Each patch passes `git apply --check`.
|
||||
- check-noindex.sh passes in sm-bm-app.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- The phase works end to end on the demo against local links.
|
||||
- Release patches for the demo and summercms.io exist; bm is noindexed.
|
||||
- Nothing pushed, tagged or deployed.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Patches: `33-12-sm-demo-app.patch` (config/golem15.seo.yaml, config/golem15.sitemap.yaml, DEPLOY.md, nginx, `seo_output_test.go`, `scripts/smoke-seo.sh`), `33-12-vue-demo-app.patch` (nuxt.config `seo.noindexRoutes`, page meta, `<SeoSitemapLink>` in the footer), `33-12-sm-summercmsio-app.patch`, `33-12-vue-summercmsio-app.patch` (`seo.cms: false`, changelog expectations).
|
||||
- Note: `33-12-local-wiring.md`.
|
||||
- sm-bm-app: `frontend/public/robots.txt`, robots meta in `frontend/index.html`, X-Robots-Tag in the nginx conf, `scripts/check-noindex.sh`.
|
||||
- Test (in the demo patch): `TestSEOOutput` (seo_output_test.go).
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-12-SUMMARY.md` when done.
|
||||
</output>
|
||||
275
.planning/phases/33-seo-output-audit-and-content/33-13-PLAN.md
Normal file
275
.planning/phases/33-seo-output-audit-and-content/33-13-PLAN.md
Normal file
@@ -0,0 +1,275 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 13
|
||||
type: execute
|
||||
wave: 8
|
||||
depends_on: ["33-11"]
|
||||
files_modified:
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-13-sm-grzybyfunkcjonalne-app.patch
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-13-vue-grzybyfunkcjonalne-app.patch
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-13-local-wiring.md
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-13-deploy-log.md
|
||||
autonomous: false
|
||||
requirements: [SC-1, SC-2, D-32, D-30, D-22, D-20, D-33, D-70, D-97, D-24]
|
||||
user_setup:
|
||||
- service: uat.grzybyfunkcjonalne.pl server
|
||||
why: "New secrets for the SEO layer and the SEO plugin, generated on the server and never printed"
|
||||
env_vars:
|
||||
- name: NUXT_SEO_NOTFOUND_TOKEN
|
||||
source: "generated on the server (openssl rand -hex 32) into /srv/grzybyfunkcjonalne/nuxt/.env; the same value as golem15.seo.notfound_token in /srv/grzybyfunkcjonalne/go/.env (SUMMER_GOLEM15__SEO__NOTFOUND_TOKEN)"
|
||||
- name: NUXT_SEO_ROUTE_REPORT_TOKEN
|
||||
source: "optional; unset falls back to the notfound token"
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "Against local links, the grzybyfunkcjonalne.pl stack (SummerCMS v0.4.4 → the v0.5.2 line, Journal with golem15.journal.tag_pages false and author pages at /autor/:author, the new sitemap format, golem15.seo mounted, the layers on vue-seo-layer) answers every line of scripts/urls.txt exactly as before (Phase 16 D-15: public URLs identical) (SC-1, RESEARCH Pitfall 13)"
|
||||
- "The site's sitemap moves to the new format in the same delivery: the PHP-era definitions migrate into Additional addresses, /sitemap.xml becomes the index of sitemap-posts, sitemap-categories, sitemap-authors and sitemap-pages files with real lastmod, and the XSL view is gone (D-32, D-30)"
|
||||
- "robots.txt, sitemaps, llms.txt and verification files come from the CMS through the layer's root proxy; the Nuxt app's own robots, sitemap, link-checker and site-config settings are removed; robots.txt's Sitemap: line names the index (D-22, D-97, D-103)"
|
||||
- "Every page renders exactly one H1, one canonical and one JSON-LD script; post pages carry breadcrumbs through their category; the build passes the SSR guard (D-70, D-52, D-86, D-43)"
|
||||
- "The static pages /, /kontakt and /trwaja-prace become registry pages through the route report, and their current titles and descriptions move into the CMS through deploy/seo-pages.csv imported with the SEO plugin's CSV import, so the pages lose no metadata (D-33)"
|
||||
- "404s are reported to the SEO plugin's 404 log through the layer with the new token (D-20)"
|
||||
- "The uat deployment happens only after Jakub's decision at Task 3 and his go-ahead; production grzybyfunkcjonalne.pl (WinterCMS) is never touched; the deploy is logged in 33-13-deploy-log.md (2026-10-28 release cadence: no push, no tag)"
|
||||
- "On uat (a non-production environment) the staging lock keeps robots Disallow and noindex, sitemaps are still built, and no IndexNow request is sent (D-22, D-31)"
|
||||
prohibitions:
|
||||
- requirement_id: "D-32"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: test
|
||||
statement: "No public URL of grzybyfunkcjonalne.pl changes its answer: every urls.txt line passes before any deploy"
|
||||
- requirement_id: "D-32"
|
||||
category: values
|
||||
status: resolved
|
||||
verification: judgment
|
||||
statement: "Nothing is deployed without Jakub's go-ahead, and the live WinterCMS site, its database and files are only read"
|
||||
artifacts:
|
||||
- path: ".planning/phases/33-seo-output-audit-and-content/33-13-sm-grzybyfunkcjonalne-app.patch"
|
||||
provides: "app config, nginx, scripts, docs, seo-pages.csv, tests"
|
||||
contains: "diff --git"
|
||||
- path: ".planning/phases/33-seo-output-audit-and-content/33-13-vue-grzybyfunkcjonalne-app.patch"
|
||||
provides: "Nuxt config on the SEO layer, footer link, page meta removal, fixtures and expectations"
|
||||
contains: "diff --git"
|
||||
- path: ".planning/phases/33-seo-output-audit-and-content/33-13-deploy-log.md"
|
||||
provides: "decision and (if deployed) the uat deploy steps"
|
||||
contains: "Decision"
|
||||
key_links:
|
||||
- from: "grzyby nginx (deploy/nginx/grzybyfunkcjonalne-staging.conf)"
|
||||
to: "Nuxt (vue-seo-layer root proxy)"
|
||||
via: "sitemap, robots.txt and llms.txt requests reach Nuxt, which proxies them to Go; /_seo and /_sitemap stay internal"
|
||||
pattern: "sitemap"
|
||||
- from: "sm-grzybyfunkcjonalne-app/summer.yaml"
|
||||
to: "sm-seo-plugin"
|
||||
via: "golem15.seo mounted next to golem15.sitemap (the submodule is added in 33-14 at the tag)"
|
||||
pattern: "golem15.seo"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
<!-- planner-discipline-allow: sitemap.xsl -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan moves grzybyfunkcjonalne.pl's SummerCMS deployment onto the new sitemap format and the SEO layer, proves its public URLs unchanged on local links, and deploys it to uat only with Jakub's go-ahead.
|
||||
|
||||
<objective>
|
||||
- In scratch worktrees wired to the sibling repositories (as 33-12, recorded again in 33-13-local-wiring.md): bump the stack (framework, Journal with tag_pages false and author pages, sitemap new format, SEO plugin mounted, layers on vue-seo-layer), run the site's own smoke over every old URL plus the SEO checks.
|
||||
- Capture the committable changes as two patches (app repository and its Nuxt submodule repository) for 33-14.
|
||||
- Decide (Task 3) and, if chosen, deploy to uat.grzybyfunkcjonalne.pl from the local build, then let Jakub verify.
|
||||
|
||||
Purpose: SC-1 ("grzybyfunkcjonalne.pl runs on the new format") and RESEARCH Pitfall 13 (several versions at once on a live site).
|
||||
|
||||
Output: two patches, the wiring note and the deploy log here (planning docs). No push, no tag; the uat deploy only after the checkpoint.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-49 (nginx):** remove `location = /sitemap.xml` and `location = /sitemap.xsl`; every root file goes to Nuxt, whose SEO layer proxies it to Go on loopback; `/_seo/` and `/_sitemap/` are not exposed (the layer calls Go internally); check-deploy.sh and smoke.sh follow (the sitemap is no longer a "remote" Go path).
|
||||
- **P33-50 (static page metadata):** the pages' own useSeoMeta calls are removed (the layer owns the head, P33-28); `deploy/seo-pages.csv` (URL, title, description in the SEO plugin's records-by-URL CSV format) carries today's titles and descriptions and is imported after the first route report.
|
||||
- **P33-51 (deploy target):** uat.grzybyfunkcjonalne.pl only, following ../sm-grzybyfunkcjonalne-app/DEPLOY.md (build, check-deploy, rsync, migrate, supervisor restart, nginx reload), with the new secrets of user_setup generated on the server.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-RESEARCH.md
|
||||
@.planning/phases/32-seo-foundation/deferred-items.md
|
||||
@.planning/phases/16-grzybyfunkcjonalne-pl-on-reusable-blog-views/16-CONTEXT.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
../sm-grzybyfunkcjonalne-app: go.mod (summercms replaced by ../summercms.go, plugins replaced by ./plugins/golem15/*), go.work, summer.yaml (user, translate, journal, sitemap, menu, faq, grzyby), config/menu_items.yaml (journal-post /blog/:slug, journal-category /:slug), config/*.yaml, deploy/nginx/grzybyfunkcjonalne-staging.conf (location = /sitemap.xml and = /sitemap.xsl to Go at 145-161), deploy/env.example, deploy/nuxt.env.example, deploy/supervisor/*, scripts/{build.sh, check-deploy.sh, migrate.sh, smoke.sh, urls.txt}, testdata/companions/sitemap-*.json(l), boot_test.go, companions_test.go, DEPLOY.md.
|
||||
vue-grzybyfunkcjonalne-app (submodule repository git.golem15.com/golem15/vue-grzybyfunkcjonalne-app): nuxt.config.ts (extends journal, menu, faq layers; robots, sitemap, linkChecker, site keys; journal routes and perPage; routeRules swr), package.json (layer pins v0.4.0/v0.2.0; smoke:ssr through node_modules/vue-journal-layer/testing/smoke-ssr.mjs), app/pages/{index,kontakt,trwaja-prace}.vue (useSeoMeta), app/components/SiteFooter.vue, tests/fixtures/api/*, tests/fixtures/expect.txt, tests/ssr.test.ts.
|
||||
Deferred from Phase 32 (deferred-items.md item 1): the Journal bump needs golem15.journal.tag_pages: false.
|
||||
33-12-local-wiring.md (if 33-12 already ran) shows the same wiring for the demo.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Planning-docs commits here only: `docs(33-13): grzyby patches for the release` and `docs(33-13): uat deploy log`. Nothing is committed in the app repositories in this plan.
|
||||
- Resume check: `git log --format=%s | grep -Fx '<subject>'`; the deploy log's last line tells where a deploy stopped.
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | none (scratch run; results in the SUMMARY) | smoke.sh and the SEO checks pass locally |
|
||||
| 2 | `docs(33-13): grzyby patches for the release` | both patches apply with git apply --check |
|
||||
| 3 | none (decision recorded in the deploy log) | decision recorded |
|
||||
| 4 | `docs(33-13): uat deploy log` | uat smoke passes, or the log records the deferral |
|
||||
| 5 | none (Jakub's verification recorded in the SUMMARY) | approved |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "every old grzybyfunkcjonalne.pl URL answers as before, and the post pages carry the CMS head, one graph and breadcrumbs, with the sitemap index in the new format" — on local links</name>
|
||||
<files>.planning/phases/33-seo-output-audit-and-content/33-13-local-wiring.md</files>
|
||||
<read_first>
|
||||
- ../sm-grzybyfunkcjonalne-app/DEPLOY.md, scripts/build.sh, scripts/smoke.sh, scripts/urls.txt, scripts/migrate.sh
|
||||
- ../sm-grzybyfunkcjonalne-app/vue-grzybyfunkcjonalne-app/nuxt.config.ts and package.json
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-12-local-wiring.md if present, else .planning/phases/32-seo-foundation/32-05-SUMMARY.md ("Scratch run")
|
||||
</read_first>
|
||||
<action>
|
||||
Per Pitfall 13 and P33-46's wiring (repeated for this app): detached worktrees of sm-grzybyfunkcjonalne-app and vue-grzybyfunkcjonalne-app in a scratch directory; scratch go.work using the worktree and the sibling plugin checkouts (sm-journal-plugin, sm-sitemap-plugin, sm-seo-plugin, sm-menu-plugin, sm-faq-plugin, sm-translate-plugin, sm-user-plugin as they are) plus the framework replace; summer.yaml mounts golem15.seo; config adds `golem15.journal.tag_pages: false`, the journal-author pattern `/autor/:author`, golem15.seo (site_url https://grzybyfunkcjonalne.pl, notfound_token from the environment) and golem15.sitemap (site_url); pnpm overrides link the four layers. Build with scripts/build.sh on the wiring, run scripts/smoke.sh (full rehearsal: migrate, companions import with the sitemap definitions, Go and Nuxt, every urls.txt line), then write scripts/smoke-seo.sh for this site in the worktree (the same checks as the demo's script of 33-12 when it already exists: one H1, one canonical and one ld+json on a post, a category and /kontakt; breadcrumbs on a post; /sitemap.xml index with sitemap-posts-1.xml; the companion url items present as Additional addresses; it ends with "smoke-seo: ok") and run it. Record every wiring command in 33-13-local-wiring.md.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>cd "$SCRATCH/sm-grzybyfunkcjonalne-app" && bash scripts/smoke.sh 2>&1 | tail -15</automated>
|
||||
<fails_when>non-zero exit, a "FAIL" line, or a urls.txt line reported with a different status ($SCRATCH as recorded in 33-13-local-wiring.md)</fails_when>
|
||||
<automated>bash "$SCRATCH/sm-grzybyfunkcjonalne-app/scripts/smoke-seo.sh" http://127.0.0.1:3016 2>&1 | tail -15</automated>
|
||||
<fails_when>non-zero exit, a "FAIL" line, or no "smoke-seo: ok" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- every urls.txt line not marked remote passes in the full rehearsal
|
||||
- the SEO checks pass for a post, a category and /kontakt
|
||||
- 33-13-local-wiring.md lists the commands with absolute paths
|
||||
</acceptance_criteria>
|
||||
<done>The site works on the new stack without any public URL changing.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 2: grzyby release patches (config, nginx, scripts, docs, seo-pages.csv, Nuxt config on the SEO layer, fixtures)</name>
|
||||
<files>.planning/phases/33-seo-output-audit-and-content/33-13-sm-grzybyfunkcjonalne-app.patch, .planning/phases/33-seo-output-audit-and-content/33-13-vue-grzybyfunkcjonalne-app.patch, .planning/phases/33-seo-output-audit-and-content/33-13-local-wiring.md</files>
|
||||
<read_first>
|
||||
- the scratch worktrees from Task 1
|
||||
- ../sm-grzybyfunkcjonalne-app/scripts/check-deploy.sh, deploy/env.example, deploy/nuxt.env.example, boot_test.go, companions_test.go
|
||||
- ../sm-seo-plugin/README.md (CSV import format for records by URL)
|
||||
</read_first>
|
||||
<action>
|
||||
Per D-32, D-22, D-33, D-97 and P33-47/P33-49/P33-50, in the worktrees: app repository — summer.yaml golem15.seo entry; config/golem15.journal.yaml (tag_pages false), config/menu_items.yaml (journal-author), config/golem15.seo.yaml, config/golem15.sitemap.yaml; nginx per P33-49 (and its header comment); scripts/check-deploy.sh (the required locations), scripts/smoke.sh and scripts/urls.txt (sitemap lines are Nuxt lines now; add /sitemap-posts-1.xml), scripts/migrate.sh comments (step 9 sitemap rows go to Additional addresses); deploy/env.example (SEO tokens and site URL keys), deploy/nuxt.env.example (NUXT_SEO_API_BASE, NUXT_SEO_BACKEND_BASE, NUXT_SEO_NOTFOUND_TOKEN), DEPLOY.md (the new variables, root files through Nuxt, the CSV import step, the route report), deploy/seo-pages.csv (P33-50), smoke-seo.sh, boot_test.go (golem15.seo booted) and companions_test.go (sitemap definitions land in extra_urls). Nuxt submodule repository — nuxt.config.ts drops robots, sitemap, linkChecker and site, adds `seo` options (pagination query, htmlSitemap pl /mapa-strony) and keeps the journal routes; SiteFooter renders `<SeoSitemapLink>`; the three pages drop their useSeoMeta; tests/fixtures/api/seo/{resolve,site}.json and tests/fixtures/expect.txt with one-H1, one-canonical and one-ld+json lines; package.json pins stay for 33-14. `go test` (with Docker) and `npm test` / `smoke:ssr` pass on the wiring. Export both patches (P33-47), `git apply --check` them against the live repositories' HEADs, commit them and the wiring note here.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>git -C ../sm-grzybyfunkcjonalne-app apply --check "$PWD/.planning/phases/33-seo-output-audit-and-content/33-13-sm-grzybyfunkcjonalne-app.patch" && git -C ../sm-grzybyfunkcjonalne-app/vue-grzybyfunkcjonalne-app apply --check "$PWD/.planning/phases/33-seo-output-audit-and-content/33-13-vue-grzybyfunkcjonalne-app.patch" && echo patches-ok</automated>
|
||||
<fails_when>non-zero exit, an "error:" line from git apply, or no "patches-ok" line</fails_when>
|
||||
<automated>grep -c "seo-pages.csv\|golem15.seo" .planning/phases/33-seo-output-audit-and-content/33-13-sm-grzybyfunkcjonalne-app.patch</automated>
|
||||
<fails_when>output 0 or a missing file</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- the app patch removes the `location = /sitemap.xsl` block and contains deploy/seo-pages.csv with the three static pages
|
||||
- the Nuxt patch removes the robots, sitemap, linkChecker and site keys and every useSeoMeta call from app/pages
|
||||
- the SUMMARY records go test, npm test and smoke:ssr passing on the wiring
|
||||
</acceptance_criteria>
|
||||
<done>The site's changes are ready to apply on top of the release tags.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:decision" gate="blocking">
|
||||
<name>Task 3: Deploy grzybyfunkcjonalne.pl's SummerCMS stack to uat now, after the tags, or hold</name>
|
||||
<reversibility rating="one-way">The uat database runs the sitemap migrations (PHP-era definitions copied into Additional addresses, the new tables filled) and the sitemap URLs change shape; rolling back means restoring the database backup and the previous binaries.</reversibility>
|
||||
<decision>D-32 moves grzyby to the new format in this delivery; the question is when the uat stack switches.</decision>
|
||||
<context>Task 1 proved every old URL and the SEO output locally. Deploying now uses a binary built from local, unpushed commits (framework, Journal, sitemap, SEO, layers); deploying after 33-14 uses the tagged versions. uat runs as a non-production environment (robots Disallow, noindex; no IndexNow). The live grzybyfunkcjonalne.pl (WinterCMS) is not affected either way. DEPLOY.md's rollback (previous binary and .output, database backup) applies.</context>
|
||||
<options>
|
||||
<option id="deploy-now">
|
||||
<name>Deploy to uat now from the local build</name>
|
||||
<pros>Real-environment check (nginx, supervisor, Postgres with the imported data) before the tags; problems found before release</pros>
|
||||
<cons>uat runs untagged code until 33-14 redeploys the tagged build</cons>
|
||||
</option>
|
||||
<option id="after-tags">
|
||||
<name>Deploy in 33-14 after the tags</name>
|
||||
<pros>uat only ever runs released versions</pros>
|
||||
<cons>Environment problems surface only after tagging (a fix then needs another patch release)</cons>
|
||||
</option>
|
||||
<option id="hold">
|
||||
<name>Hold the uat deploy</name>
|
||||
<pros>No change on uat in this phase</pros>
|
||||
<cons>SC-1's "grzybyfunkcjonalne.pl runs on the new format" stays unverified on a server</cons>
|
||||
</option>
|
||||
</options>
|
||||
<resume-signal>Reply "deploy-now", "after-tags" or "hold"</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 4: Deploy to uat (only if Task 3 answered deploy-now) and smoke it, with every step logged</name>
|
||||
<files>.planning/phases/33-seo-output-audit-and-content/33-13-deploy-log.md</files>
|
||||
<read_first>
|
||||
- ../sm-grzybyfunkcjonalne-app/DEPLOY.md (Build and upload, Release, Rollback)
|
||||
- .planning/phases/32-seo-foundation/32-06-release-log.md (step logging so a resumed run never repeats a step)
|
||||
</read_first>
|
||||
<precondition>Task 3 answered "deploy-now", and Jakub has generated the user_setup secrets on the server (DEPLOY.md: never printed)</precondition>
|
||||
<action>
|
||||
Per P33-51: write the decision to 33-13-deploy-log.md first. If the answer is after-tags or hold, record it and stop (33-14 carries the deploy). Otherwise, from the scratch worktree with the patches applied: scripts/build.sh, scripts/check-deploy.sh, back up the uat database and current binaries as DEPLOY.md describes, rsync the binary, config, scripts, Nuxt .output and deploy files, run the migrations, restart both supervisor programs, reload nginx after `nginx -t`, run the sitemap rebuild command, import deploy/seo-pages.csv after the Nuxt server has reported its routes, then run `scripts/smoke.sh --url https://uat.grzybyfunkcjonalne.pl` (with the UAT basic auth from the server's own loopback, as DEPLOY.md says) and smoke-seo.sh against it. Log each step with its result as it completes; never print a secret. On any failure, follow DEPLOY.md's rollback and log it.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>grep -c "^| " .planning/phases/33-seo-output-audit-and-content/33-13-deploy-log.md</automated>
|
||||
<fails_when>output 0 (no logged step) or a missing file</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- the deploy log starts with the Task 3 decision
|
||||
- for deploy-now: the log shows build, check-deploy, backup, upload, migrate, restart, nginx reload, rebuild, CSV import, smoke.sh --url and smoke-seo.sh, each with its result
|
||||
- no secret value appears in the log or the SUMMARY
|
||||
</acceptance_criteria>
|
||||
<done>uat runs the new stack and passes both smokes, or the deferral is on record.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking">
|
||||
<name>Task 5: Jakub checks uat.grzybyfunkcjonalne.pl (skipped when Task 3 deferred the deploy)</name>
|
||||
<what-built>The SummerCMS stack of grzybyfunkcjonalne.pl on uat with the new sitemap format, the SEO plugin and the SEO layer (Task 4).</what-built>
|
||||
<how-to-verify>
|
||||
1. Open https://uat.grzybyfunkcjonalne.pl/sitemap.xml: an index of sitemap-posts, sitemap-categories, sitemap-authors and sitemap-pages files; open one file.
|
||||
2. Open a post: view source shows one title, one canonical, one application/ld+json script with BlogPosting and BreadcrumbList, and breadcrumbs above the content.
|
||||
3. In /gfadmin: SEO › Pages lists /, /kontakt and /trwaja-prace with their titles; Settings › Sitemaps shows the files table and the migrated Additional addresses.
|
||||
4. Start a crawl in SEO › Crawls; after it finishes, SEO › Site audit lists issues without staging-lock noindex.
|
||||
</how-to-verify>
|
||||
<resume-signal>Reply "approved" or describe what is wrong</resume-signal>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| local machine → uat server | rsync and SSH as the deploy user |
|
||||
| uat Nuxt → uat Go | loopback calls with the new tokens |
|
||||
| internet → uat nginx | public requests (UAT basic auth) |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-58 | Information disclosure | new tokens | high | mitigate | generated on the server into the .env files (mode 0600), never printed, never in patches, logs or the SUMMARY |
|
||||
| T-33-59 | Tampering | untagged build on uat | medium | mitigate | deploy only after the Task 3 decision; sha256 of the uploaded binary compared with the local build (DEPLOY.md); rollback path logged |
|
||||
| T-33-60 | Elevation of privilege | exposing /_seo and /_sitemap | medium | mitigate | P33-49 keeps both internal (no nginx location), the management API needs backend auth anyway |
|
||||
| T-33-61 | Denial of service | public URLs changing on the live domain | high | mitigate | only uat is deployed; every urls.txt line must pass first; the WinterCMS site is untouched |
|
||||
| T-33-SC | Tampering | npm/Go installs | high | accept | no new package beyond those already gated in 33-11 |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- Local rehearsal: scripts/smoke.sh and smoke-seo.sh pass on the wiring.
|
||||
- Both patches pass `git apply --check`.
|
||||
- For deploy-now: the uat smokes pass and Jakub approves.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- grzybyfunkcjonalne.pl's SummerCMS stack runs on the new sitemap format and the SEO layer with every old URL unchanged.
|
||||
- Release patches exist; the uat deploy follows Jakub's decision.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Patches: `33-13-sm-grzybyfunkcjonalne-app.patch` (summer.yaml golem15.seo, `config/golem15.journal.yaml`, `config/golem15.seo.yaml`, `config/golem15.sitemap.yaml`, `config/menu_items.yaml` journal-author, nginx, `scripts/check-deploy.sh`, `scripts/smoke.sh`, `scripts/urls.txt`, `scripts/smoke-seo.sh`, `deploy/env.example`, `deploy/nuxt.env.example`, `deploy/seo-pages.csv`, DEPLOY.md, boot and companions tests), `33-13-vue-grzybyfunkcjonalne-app.patch` (nuxt.config `seo` options, `<SeoSitemapLink>` in SiteFooter, page meta removal, `tests/fixtures/api/seo/*`, `tests/fixtures/expect.txt`).
|
||||
- Notes and logs: `33-13-local-wiring.md`, `33-13-deploy-log.md`.
|
||||
- Environment variables (uat): `NUXT_SEO_NOTFOUND_TOKEN`, `NUXT_SEO_ROUTE_REPORT_TOKEN`, `NUXT_SEO_API_BASE`, `NUXT_SEO_BACKEND_BASE`; config keys used: `golem15.journal.tag_pages`, `golem15.seo.site_url`, `golem15.seo.notfound_token`, `golem15.sitemap.site_url`.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-13-SUMMARY.md` when done; state whether uat runs the new stack and on which commits.
|
||||
</output>
|
||||
336
.planning/phases/33-seo-output-audit-and-content/33-14-PLAN.md
Normal file
336
.planning/phases/33-seo-output-audit-and-content/33-14-PLAN.md
Normal file
@@ -0,0 +1,336 @@
|
||||
---
|
||||
phase: 33-seo-output-audit-and-content
|
||||
plan: 14
|
||||
type: execute
|
||||
wave: 9
|
||||
depends_on: ["33-12", "33-13"]
|
||||
files_modified:
|
||||
- scripts/check-phase33.sh
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-release-log.md
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-VALIDATION.md
|
||||
- modules/pact/content_test.go
|
||||
- modules/cabana/field_request_options_test.go
|
||||
- modules/lagoon/attach/variant_test.go
|
||||
- modules/lagoon/attach/webp/webp_test.go
|
||||
- ../sm-sitemap-plugin/classes/writer_test.go
|
||||
- ../sm-sitemap-plugin/classes/slots_test.go
|
||||
- ../sm-sitemap-plugin/classes/lastmod_test.go
|
||||
- ../sm-sitemap-plugin/classes/news_test.go
|
||||
- ../sm-sitemap-plugin/classes/indexnow_test.go
|
||||
- ../sm-sitemap-plugin/classes/htmlgroups_test.go
|
||||
- ../sm-sitemap-plugin/classes/types_test.go
|
||||
- ../sm-seo-plugin/classes/schema/graph_test.go
|
||||
- ../sm-seo-plugin/classes/schema/validate_test.go
|
||||
- ../sm-seo-plugin/classes/schema/custom_test.go
|
||||
- ../sm-seo-plugin/classes/pagination_test.go
|
||||
- ../sm-seo-plugin/classes/alternates_test.go
|
||||
- ../sm-seo-plugin/classes/breadcrumbs_test.go
|
||||
- ../sm-seo-plugin/classes/sitemap_filter_test.go
|
||||
- ../sm-seo-plugin/classes/registry_test.go
|
||||
- ../sm-seo-plugin/classes/autolinks_test.go
|
||||
- ../sm-seo-plugin/classes/crawl/parse_test.go
|
||||
- ../sm-seo-plugin/classes/crawl/checks_test.go
|
||||
- ../sm-seo-plugin/classes/crawl/fix_test.go
|
||||
- ../sm-seo-plugin/tests/elements/schema.test.ts
|
||||
- ../sm-seo-plugin/tests/elements/graph.test.ts
|
||||
- ../sm-seo-plugin/tests/elements/links.test.ts
|
||||
- ../sm-seo-plugin/tests/elements/parent.test.ts
|
||||
- ../sm-journal-plugin/classes/headings_test.go
|
||||
- ../sm-journal-plugin/classes/image_alt_test.go
|
||||
- ../sm-journal-plugin/classes/content_facts_test.go
|
||||
- ../sm-journal-plugin/classes/related_test.go
|
||||
- ../sm-journal-plugin/tests/blogeditor/outline.test.ts
|
||||
- ../sm-journal-plugin/tests/blogeditor/forms.test.ts
|
||||
- ../vue-seo-layer/tests/routes.test.ts
|
||||
- ../vue-seo-layer/tests/usePagination.test.ts
|
||||
- ../vue-journal-layer/tests/postTitle.test.ts
|
||||
- ../vue-faq-layer/tests/block.test.ts
|
||||
autonomous: false
|
||||
requirements: [SC-4, SC-1, SC-2, SC-3, D-106, D-90, D-97, D-30, D-43, D-50, D-70, D-14]
|
||||
|
||||
estimate:
|
||||
tokens: 200000
|
||||
raw_tokens: 200000
|
||||
tasks: 5
|
||||
confidence: low
|
||||
|
||||
must_haves:
|
||||
truths:
|
||||
- "The phase's new code has unit tests, delivered in this last plan (ROADMAP success criterion 4, project rule): framework (descriptor fields, RequestOptions, attach variants and the WebP encoder), sm-sitemap-plugin (writer, slots, lastmod, News, IndexNow, HTML groups, slugs), sm-seo-plugin (schema builder and validators, custom JSON-LD, pagination, alternates, breadcrumbs, sitemap filter, registry, auto-links, crawler parse/checks/fix routes, elements E8–E10 and the parent select), sm-journal-plugin (heading conversion, image alt, content facts, related scoring, editor outline and forms), and the layers (routes, pagination, post title, FAQ block) (SC-4)"
|
||||
- "bash scripts/check-phase33.sh --all passes with Docker, every repository present and no skips: self-test, go, plugins, layers (tests, playground builds, smokes, build-guard fixtures), consumers, docker, admin, docs, marker, additive and compat (Wave 0 gate)"
|
||||
- "The framework release is a patch tag (the next v0.5.x read from git tag, expected v0.5.2), strictly additive against v0.5.1 and naming no SEO concept or consuming application (D-106, D-90)"
|
||||
- "Nothing is pushed, tagged, created on git.golem15.com, deployed or posted before Jakub's go-ahead at Task 4, which names the versions, the pushes, the changelog posts and any deploys (2026-10-28 release cadence: all tags in 33-14)"
|
||||
- "After the go-ahead, repositories are released in order — framework → sm-journal-plugin → sm-sitemap-plugin (breaking: next minor) → sm-seo-plugin → vue-seo-layer (created with tea) → vue-journal-layer, vue-menu-layer, vue-faq-layer → apps — each plugin requiring the new tags, the layers pinning the new vue-seo-layer tag instead of link:, and each app pinning tags with plugin pointer bumps as separate commits after the plugin is pushed (2026-10-28 release cadence, CLAUDE.md)"
|
||||
- "The 33-12 and 33-13 patches are applied to the apps after the tags, with grzybyfunkcjonalne-app's sm-seo-plugin submodule added at its tag; each app builds and passes its tests on the tagged versions; sm-demo-app's check-pins passes on a clean worktree"
|
||||
- "SummerCMS's release tag gets its changelog post on summercms.io the same day through scripts/changelog-post.py (source, then publish); the g15_ token is read by the script and never printed (CLAUDE.md)"
|
||||
- "Every executed release step is appended to 33-release-log.md as it completes, so a resumed run never re-tags, force-pushes or re-posts"
|
||||
- "33-VALIDATION.md is filled per task with the real commands and statuses and marked nyquist_compliant true when every row is green"
|
||||
- "Phase 33 is delivered in the 14 plans Jakub confirmed on 2026-10-28 (2026-10-28 plan list)"
|
||||
prohibitions:
|
||||
- requirement_id: "D-106"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: judgment
|
||||
statement: "No push, tag, repository creation, deploy or changelog post happens without Jakub's go-ahead, and no version number is hard-coded before the checkpoint"
|
||||
- requirement_id: "D-106"
|
||||
category: safety
|
||||
status: resolved
|
||||
verification: judgment
|
||||
statement: "The changelog token is never printed, copied or minted"
|
||||
artifacts:
|
||||
- path: "scripts/check-phase33.sh"
|
||||
provides: "the complete phase gate"
|
||||
contains: "--all"
|
||||
- path: ".planning/phases/33-seo-output-audit-and-content/33-release-log.md"
|
||||
provides: "executed release steps"
|
||||
contains: "Executed steps"
|
||||
- path: "../sm-seo-plugin/classes/schema/graph_test.go"
|
||||
provides: "graph unit matrix"
|
||||
contains: "func Test"
|
||||
- path: "../vue-seo-layer/tests/usePagination.test.ts"
|
||||
provides: "pagination composable unit tests"
|
||||
contains: "test("
|
||||
key_links:
|
||||
- from: "scripts/check-phase33.sh"
|
||||
to: "every Phase 33 repository"
|
||||
via: "the plugins, layers, consumers, docker and compat stages run each repository's tests and builds"
|
||||
pattern: "vue-seo-layer"
|
||||
- from: ".planning/phases/33-seo-output-audit-and-content/33-release-log.md"
|
||||
to: "git tags of the released repositories"
|
||||
via: "each logged step names the tag object and the pushed commit"
|
||||
pattern: "tag"
|
||||
---
|
||||
|
||||
<!-- planner-discipline-allow: seo -->
|
||||
|
||||
## Phase Goal
|
||||
|
||||
**As a** site editor and as an SEO specialist auditing a SummerCMS site, **I want to** have the rendered sites emit complete SEO output (sitemaps, structured data, pagination, hreflang, headings, breadcrumbs) from the CMS, and an audit that finds the remaining problems, **so that** sites are indexed correctly and issues can be fixed through MCP.
|
||||
|
||||
This plan proves the phase with unit tests and the full gate, then releases every repository in order and re-pins the apps — each step only after Jakub's go-ahead.
|
||||
|
||||
<objective>
|
||||
- Complete `scripts/check-phase33.sh` and run `--all` green (tracer of the gate across every repository).
|
||||
- Unit tests for all new code (project rule: unit tests are the last plan; SC-4).
|
||||
- After the release checkpoint: tags in release order, the vue-seo-layer remote, pin bumps and the 33-12/33-13 patches in the apps, pushes, the framework changelog post, and deploys only when named.
|
||||
|
||||
Purpose: SC-4 and the release of Phase 33 (2026-10-28 release cadence: all tags here).
|
||||
|
||||
Output: test commits in each repository, the gate script, the filled validation map, the release log, tags and pushes after the go-ahead.
|
||||
|
||||
**Planner decisions recorded here:**
|
||||
- **P33-52 (versions proposed at the checkpoint, read from git tag):** framework next patch (v0.5.2); sm-journal-plugin next patch or minor (new settings, type and API keys are additive: patch v0.2.6 unless Jakub prefers v0.3.0); sm-sitemap-plugin next minor (breaking, v0.2.0); sm-seo-plugin next minor (new requires and features, v0.2.0); vue-seo-layer v0.1.0; vue-journal-layer next minor (drops @nuxtjs/seo: v0.7.0); vue-menu-layer and vue-faq-layer next minor (v0.5.0). The answer fixes them.
|
||||
- **P33-53 (release steps are resumable):** each step is: check the log; do it; verify (`git ls-remote --tags origin <tag>`, build of the dependent); append the log line with SHAs. A failure stops the run and is logged; nothing is force-pushed.
|
||||
</objective>
|
||||
|
||||
<execution_context>
|
||||
@~/.claude/msd-core/workflows/execute-plan.md
|
||||
@~/.claude/msd-core/templates/summary.md
|
||||
</execution_context>
|
||||
|
||||
<context>
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-CONTEXT.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-VALIDATION.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-release-log.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-12-SUMMARY.md
|
||||
@.planning/phases/33-seo-output-audit-and-content/33-13-SUMMARY.md
|
||||
@.planning/phases/32-seo-foundation/32-06-SUMMARY.md
|
||||
@.planning/phases/32-seo-foundation/32-06-release-log.md
|
||||
@CLAUDE.md
|
||||
|
||||
<interfaces>
|
||||
Every plan's SUMMARY (33-01 … 33-13) lists the symbols, routes, tables and tests it created; unit tests target those symbols.
|
||||
Release precedent: 32-06-SUMMARY.md "Release steps" (go get with GOWORK=off and GOPRIVATE='git.golem15.com/*', README dependency lines, annotated tags, ls-remote checks, demo check-pins on a clean worktree, changelog-post.py source/publish).
|
||||
Changelog: ../sm-summercmsio-app/scripts/changelog-post.py source vX.Y.Z, then publish vX.Y.Z notes.md --excerpt "…" (## Highlights/## Added/## Changed/## Fixed, no planning IDs); ../sm-summercmsio-app/DEPLOY.md "Posting to the changelog".
|
||||
Repository creation: tea (git.golem15.com) for vue-seo-layer, name from 33-07-SUMMARY.md.
|
||||
Layer git-install check: ../vue-journal-layer/scripts/check-git-install.sh <tag>.
|
||||
</interfaces>
|
||||
</context>
|
||||
|
||||
## Execution units and resume points
|
||||
|
||||
- Test commits per repository staged by path; planning docs (VALIDATION, release log) in their own commits here. Other sessions' uncommitted files stay untouched in every repository.
|
||||
- The executor stops at Task 4 (checkpoint) and the continuation runs Task 5; Task 5 is resumable from 33-release-log.md (P33-53).
|
||||
|
||||
| Task | Commit groups, in order | Resume point |
|
||||
|------|-------------------------|--------------|
|
||||
| 1 | `test: complete the phase 33 gate` | check-phase33.sh --all passes with the existing tests |
|
||||
| 2 | one `test: unit tests for …` commit per Go repository (framework, sitemap, seo, journal) | Go unit tests pass |
|
||||
| 3 | one `test: …` commit per TS repository (sm-seo-plugin elements, sm-journal-plugin editor, vue-seo-layer, vue-journal-layer, vue-faq-layer); `docs(33-14): validation map` | gate --all green again; VALIDATION filled |
|
||||
| 4 | none (go-ahead recorded at the top of the release log) | answer recorded |
|
||||
| 5 | release steps logged one by one in 33-release-log.md | every named step logged done |
|
||||
|
||||
<tasks>
|
||||
|
||||
<task type="tracer">
|
||||
<name>Task 1: End-to-end "the phase gate runs every repository's tests, builds, smokes and guards and passes" — the gate across all 13 repositories</name>
|
||||
<files>scripts/check-phase33.sh</files>
|
||||
<read_first>
|
||||
- scripts/check-phase33.sh (33-01) and scripts/check-phase32.sh (stage engine)
|
||||
- every 33-0x-SUMMARY.md and 33-1x-SUMMARY.md "Artifacts" and verification commands
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-VALIDATION.md
|
||||
</read_first>
|
||||
<action>
|
||||
Complete the stages of check-phase33.sh with what the plans delivered: plugins (the three Go plugins' vet and `test -short`, the element and editor vitest suites, both dist checks), layers (per layer: tests, playground build, its smoke command, journal's second expectation file with the postTitleTag env, vue-seo-layer guard:check and purge checks), consumers (sm-demo-app, sm-grzybyfunkcjonalne-app, sm-summercmsio-app and sm-bm-app build as committed; the 33-12/33-13 patches checked with `git apply --check`), docker (the Docker suites named in the SUMMARYs of the three plugins and the framework attach tests), admin, docs, marker (framework diff since v0.5.1), additive and compat. Run `bash scripts/check-phase33.sh --self-test` and `--all` with Docker (if the Docker socket is denied, run through `sudo -u golem` per CLAUDE.md); fix gate bugs, never weaken a stage. Commit the script.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>bash scripts/check-phase33.sh --self-test && bash scripts/check-phase33.sh --all 2>&1 | tail -25</automated>
|
||||
<fails_when>non-zero exit, a "FAIL", "refuse:", "missing " or "SKIP" line, or no "Phase 33 gate passed" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- the --all output lists PASS for all eleven stages
|
||||
- `grep -n "guard:check\|expect-acme-title-h1" scripts/check-phase33.sh` prints at least two lines
|
||||
</acceptance_criteria>
|
||||
<done>One command proves the whole phase across every repository.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 2: Go unit tests for the framework, sm-sitemap-plugin, sm-seo-plugin and sm-journal-plugin</name>
|
||||
<files>modules/pact/content_test.go, modules/cabana/field_request_options_test.go, modules/lagoon/attach/variant_test.go, modules/lagoon/attach/webp/webp_test.go, ../sm-sitemap-plugin/classes/writer_test.go, ../sm-sitemap-plugin/classes/slots_test.go, ../sm-sitemap-plugin/classes/lastmod_test.go, ../sm-sitemap-plugin/classes/news_test.go, ../sm-sitemap-plugin/classes/indexnow_test.go, ../sm-sitemap-plugin/classes/htmlgroups_test.go, ../sm-sitemap-plugin/classes/types_test.go, ../sm-seo-plugin/classes/schema/graph_test.go, ../sm-seo-plugin/classes/schema/validate_test.go, ../sm-seo-plugin/classes/schema/custom_test.go, ../sm-seo-plugin/classes/pagination_test.go, ../sm-seo-plugin/classes/alternates_test.go, ../sm-seo-plugin/classes/breadcrumbs_test.go, ../sm-seo-plugin/classes/sitemap_filter_test.go, ../sm-seo-plugin/classes/registry_test.go, ../sm-seo-plugin/classes/autolinks_test.go, ../sm-seo-plugin/classes/crawl/parse_test.go, ../sm-seo-plugin/classes/crawl/checks_test.go, ../sm-seo-plugin/classes/crawl/fix_test.go, ../sm-journal-plugin/classes/headings_test.go, ../sm-journal-plugin/classes/image_alt_test.go, ../sm-journal-plugin/classes/content_facts_test.go, ../sm-journal-plugin/classes/related_test.go</files>
|
||||
<read_first>
|
||||
- each package's code from the SUMMARYs; the Phase 32 unit test style: ../sm-seo-plugin/classes/{resolver_test,issues_test,helpers_test}.go, modules/cabana/form_extensions_test.go, modules/lagoon/attach/thumb_test.go
|
||||
</read_first>
|
||||
<behavior>
|
||||
- Table-driven, -short-compatible where no database is needed: XML escaping and namespaces, no priority element; slot assignment with deletes, appends and size change; lastmod ignore list and locale rows; News window boundaries (47 h/49 h) and the 1000 cap; IndexNow chunking at 10 000, key format, host filter, answer mapping; HTML groups order, tree and paging; default slug pluralisation; @id links per kind and the publisher/local node; every validator rule; custom JSON-LD caps, script refusal and merge; pagination parse, 301 and invalid cases per form; alternates and x-default; breadcrumb chain with primary parent, fallback and depth cap; filter reasons; route-report merge never deleting; auto-link locale/self filtering; crawler parse of headings, links, images, JSON-LD and hreflang on HTML fixtures; each check's positive and negative case; fix routes; ConvertH1 byte preservation; alt rewrite escaping; content facts (decorative, videos, headings); related scoring ties; RequestOptions merge precedence and fail-open; VariantKey; WebP encode header and idempotent variant
|
||||
</behavior>
|
||||
<action>
|
||||
Write the unit tests per behavior list in the files named (package-internal tests where the code is unexported), each repository's `go vet ./...` and `go test -short ./...` green, Docker suites still green. One commit per repository.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>go test -short ./modules/pact ./modules/cabana ./modules/lagoon/attach/... -count=1 2>&1 | tail -6 && for r in sm-sitemap-plugin sm-seo-plugin sm-journal-plugin; do go -C ../$r vet ./... && go -C ../$r test -short ./... -count=1 2>&1 | tail -4 || exit 1; done</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line in any output</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- every test file in this task's files exists and contains at least one `func Test`
|
||||
- `go -C ../sm-seo-plugin test -short ./classes/schema/... ./classes/crawl/... -count=1 -v 2>&1 | grep -c -- "--- PASS"` is at least 30
|
||||
</acceptance_criteria>
|
||||
<done>The Go code of the phase is covered by unit tests.</done>
|
||||
</task>
|
||||
|
||||
<task type="auto" tdd="true">
|
||||
<name>Task 3: TypeScript unit tests for the elements, the editor and the layers; the validation map</name>
|
||||
<files>../sm-seo-plugin/tests/elements/schema.test.ts, ../sm-seo-plugin/tests/elements/graph.test.ts, ../sm-seo-plugin/tests/elements/links.test.ts, ../sm-seo-plugin/tests/elements/parent.test.ts, ../sm-journal-plugin/tests/blogeditor/outline.test.ts, ../sm-journal-plugin/tests/blogeditor/forms.test.ts, ../vue-seo-layer/tests/routes.test.ts, ../vue-seo-layer/tests/usePagination.test.ts, ../vue-journal-layer/tests/postTitle.test.ts, ../vue-faq-layer/tests/block.test.ts, .planning/phases/33-seo-output-audit-and-content/33-VALIDATION.md</files>
|
||||
<read_first>
|
||||
- ../sm-seo-plugin/tests/elements/{host.ts, serp.test.ts} and ../sm-journal-plugin/tests/blogeditor/{helpers.ts, element.test.ts} (harness)
|
||||
- ../vue-seo-layer/tests/*.test.ts and ../vue-journal-layer/tests/*.test.ts (node --test style)
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-UI-SPEC.md (C17, C18, C19, C28, L2, L5, L6 backstops)
|
||||
</read_first>
|
||||
<behavior>
|
||||
- E8: Service fields round-trip as a JSON string; invalid price shows priceInvalid; parse error shows line and column; over 16 KB shows jsonTooLarge; type options per kind (UI-SPEC E8 backstop)
|
||||
- E9: nodes, findings with icons and words, noRules line, allGood, checking with aria-busy, one queued request, failure line keeps the last graph
|
||||
- E10: counters, notCrawled, orphan callout, lists capped at 10, none, copy writes the URL, hidden copy button without clipboard
|
||||
- parent select: options and empty option from the value
|
||||
- Editor outline: skipped levels, empty, link-only, H1 flag only when level 1 is not allowed, generic link flag, 300 ms debounce, no content edits
|
||||
- Editor forms: rel checkboxes disabled for internal URLs, rel written, generic warning without blocking; slug rule examples (UI-SPEC J4 backstop); decorative clears alt
|
||||
- Layer routes: static paths exclude parameters, requiresAuth and noindex; pattern normalisation for the drift check
|
||||
- usePagination: hrefs per form, %pages% replacement, prev/next head links at the ends
|
||||
- Post title: the titleTag decision table for postTitleTag × content_h1_to_h2 (including an absent key)
|
||||
- FAQ block: headingLevel 0 renders p with aria-labelledby; FAQPage node text stripped of markup
|
||||
</behavior>
|
||||
<action>
|
||||
Write the tests per behavior list; `npm --prefix <repo> run test` green in each repository; rebuild nothing (tests only). Fill 33-VALIDATION.md's per-task verification map with the real commands of every plan and their status, tick the sign-off list and set `nyquist_compliant: true` and `wave_0_complete: true` when all rows are green. Re-run `bash scripts/check-phase33.sh --all`. Commit per repository, then the validation map here.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>for r in sm-seo-plugin sm-journal-plugin vue-seo-layer vue-journal-layer vue-faq-layer vue-menu-layer; do npm --prefix ../$r run test 2>&1 | tail -4 || exit 1; done</automated>
|
||||
<fails_when>non-zero exit, a "not ok" line, a "# fail" count above 0, or a failed count above 0 in a vitest summary</fails_when>
|
||||
<automated>bash scripts/check-phase33.sh --all 2>&1 | tail -5 && grep -n "nyquist_compliant: true" .planning/phases/33-seo-output-audit-and-content/33-VALIDATION.md</automated>
|
||||
<fails_when>non-zero exit, no "Phase 33 gate passed" line, or the grep printing nothing</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- each test file of this task exists with at least three test cases
|
||||
- 33-VALIDATION.md has no "⬜ pending" status left
|
||||
</acceptance_criteria>
|
||||
<done>The admin elements, the editor and the layers are covered by unit tests, and the validation map is complete.</done>
|
||||
</task>
|
||||
|
||||
<task type="checkpoint:human-verify" gate="blocking-human">
|
||||
<name>Task 4: Release go-ahead (versions, pushes, the new repository, changelog posts, deploys)</name>
|
||||
<what-built>All Phase 33 code is committed locally in 13 repositories, the gate passes (Task 1–3), and the app patches apply. Nothing has been pushed, tagged, created remotely, deployed or posted.</what-built>
|
||||
<how-to-verify>
|
||||
1. Review the proposed versions (P33-52, read now from `git tag` in each repository) and the release order of the release log.
|
||||
2. Review the list of pushes: framework master; sm-journal-plugin, sm-sitemap-plugin, sm-seo-plugin main; vue-seo-layer (new repository with tea, name from 33-07) main; vue-journal-layer, vue-menu-layer, vue-faq-layer main; sm-demo-app and vue-demo-app; sm-summercmsio-app and vue-summercmsio-app; sm-grzybyfunkcjonalne-app and vue-grzybyfunkcjonalne-app; sm-bm-app — with the counts of commits each push carries (including other sessions' commits, as in 32-06).
|
||||
3. Choose the changelog posts (the framework post is required for a framework tag; plugin posts optional).
|
||||
4. Name any deploys (demo per ../sm-demo-app/DEPLOY.md; uat.grzybyfunkcjonalne.pl per its DEPLOY.md, on the tagged build; bm per its DEPLOY.md) or none.
|
||||
5. Answer with the versions, the approved pushes, the posts and the deploys.
|
||||
</how-to-verify>
|
||||
<resume-signal>Reply "release: <versions>; push: <list>; posts: <list>; deploy: <list or none>" or "hold"</resume-signal>
|
||||
</task>
|
||||
|
||||
<task type="auto">
|
||||
<name>Task 5: Release in order, re-pin the apps, post the changelog and deploy what was named — every step logged</name>
|
||||
<files>.planning/phases/33-seo-output-audit-and-content/33-release-log.md</files>
|
||||
<read_first>
|
||||
- .planning/phases/33-seo-output-audit-and-content/33-release-log.md (the go-ahead at its top and any steps already done)
|
||||
- .planning/phases/32-seo-foundation/32-06-SUMMARY.md (Release steps) and 32-06-release-log.md
|
||||
- ../sm-summercmsio-app/DEPLOY.md ("Posting to the changelog"), ../sm-demo-app/DEPLOY.md, ../sm-grzybyfunkcjonalne-app/DEPLOY.md
|
||||
- 33-12-local-wiring.md, 33-13-local-wiring.md, 33-13-deploy-log.md
|
||||
</read_first>
|
||||
<precondition>Task 4 answered "release: …" (not "hold"), and the answer is recorded at the top of 33-release-log.md</precondition>
|
||||
<action>
|
||||
Per the 2026-10-28 release cadence, P33-52 and P33-53, only for what the go-ahead names, appending a log line (step, repository, result, SHAs, tag object) after each step:
|
||||
1. Pre-checks: `bash scripts/check-phase33.sh --all` green; each repository's branch is ahead of origin only by the expected commits; patches pass `git apply --check`.
|
||||
2. Framework: annotated tag, push master and the tag, `git ls-remote --tags origin <tag>`.
|
||||
3. sm-journal-plugin, then sm-sitemap-plugin, then sm-seo-plugin: `GOWORK=off GOPRIVATE='git.golem15.com/*' go get` the new framework tag (and the new sitemap tag for SEO), README dependency lines, build, vet, `test -short`, commit `chore: require SummerCMS <tag>` (and sm-sitemap-plugin <tag>), annotated tag, push main and the tag.
|
||||
4. vue-seo-layer: create the remote with tea under the confirmed name, set origin, push main, tag v0.1.0 (or the approved version), push the tag.
|
||||
5. vue-journal-layer, vue-menu-layer, vue-faq-layer: replace the link: dependency with `git+https://git.golem15.com/golem15/vue-seo-layer.git#<tag>`, `pnpm install`, tests, commit `chore: pin vue-seo-layer <tag>`, annotated tag, push; run vue-journal-layer's scripts/check-git-install.sh <tag> from a directory outside the layer.
|
||||
6. Apps, each plugin pointer first pushed then bumped in the app as its own commit: sm-demo-app (apply 33-12 patches; go get the tags; submodule pointers journal, sitemap, seo; vue-demo-app: apply its patch, pin the layer tags, commit and push vue-demo-app, then bump its pointer in sm-demo-app; tests with Docker and the summercms_mcp tag; check-pins on a clean worktree); sm-summercmsio-app and vue-summercmsio-app (journal bump with its config, layer pins, `seo.cms: false` patch, generate and test:changelog); sm-grzybyfunkcjonalne-app (framework, journal, sitemap tags; `git submodule add -b main` sm-seo-plugin at plugins/golem15/seo checked out at its tag, go.work use; apply the 33-13 patches; vue app pins; build.sh and tests); sm-bm-app (push its local D-72 commit). Push each app as approved.
|
||||
7. Changelog: `scripts/changelog-post.py source <framework tag>` in ../sm-summercmsio-app, write user-facing notes (## Highlights / ## Added / ## Changed / ## Fixed; no planning IDs, no quick codes, no H1), `publish <tag> notes.md --excerpt "…"`, check the post URL answers 200; plugin posts only if named. Never print, copy or mint the token.
|
||||
8. Deploys only if named, each per its DEPLOY.md on the tagged builds (uat.grzybyfunkcjonalne.pl as 33-13 Task 4 describes, appending to 33-13-deploy-log.md as well).
|
||||
9. Commit the release log here (planning docs). The g15office comment on the phase task, and closing w8kupqi3 if it is still open there (the repository todo is already completed), are reported to the orchestrator in the SUMMARY.
|
||||
</action>
|
||||
<verify>
|
||||
<automated>for t in $(grep -oE 'TAG [^ ]+ [^ ]+' .planning/phases/33-seo-output-audit-and-content/33-release-log.md | awk '{print $2"@"$3}'); do repo=${t%@*}; tag=${t#*@}; git -C "$repo" ls-remote --tags origin "$tag" | grep -q "$tag" || { echo "missing $t"; exit 1; }; done; echo tags-ok</automated>
|
||||
<fails_when>non-zero exit, a "missing" line, or no "tags-ok" line (each released tag is logged as "TAG <repo path> <tag>")</fails_when>
|
||||
<automated>bash scripts/check-phase33.sh --compat --consumers 2>&1 | tail -6</automated>
|
||||
<fails_when>non-zero exit or a "FAIL" line</fails_when>
|
||||
</verify>
|
||||
<acceptance_criteria>
|
||||
- the release log has one line per executed step in the release order, each with SHAs, and a TAG line per tag
|
||||
- every plugin's go.mod requires the new framework tag (no pseudo-version) and sm-seo-plugin requires the new sm-sitemap-plugin tag
|
||||
- no layer package.json contains "link:" after step 5
|
||||
- the changelog post URL answers 200 (when a post was approved)
|
||||
</acceptance_criteria>
|
||||
<done>Phase 33 is released in order with the apps pinned to the tags, or the hold is on record.</done>
|
||||
</task>
|
||||
|
||||
</tasks>
|
||||
|
||||
<threat_model>
|
||||
## Trust Boundaries
|
||||
|
||||
| Boundary | Description |
|
||||
|----------|-------------|
|
||||
| local repositories → git.golem15.com | pushes, tags and a new repository |
|
||||
| release script → summercms.io changelog API | token-authenticated post |
|
||||
| local build → servers | deploys |
|
||||
|
||||
## STRIDE Threat Register
|
||||
|
||||
| Threat ID | Category | Component | Severity | Disposition | Mitigation Plan |
|
||||
|-----------|----------|-----------|----------|-------------|-----------------|
|
||||
| T-33-62 | Repudiation/Integrity | unapproved release steps | high | mitigate | blocking go-ahead (Task 4) naming every push, tag, post and deploy; each executed step logged with SHAs |
|
||||
| T-33-63 | Information disclosure | changelog token | high | mitigate | read by changelog-post.py from ~/.config/summercms/journal-token; never printed, copied or minted; refused token → ask Jakub |
|
||||
| T-33-64 | Tampering | breaking published API | high | mitigate | additive and compat stages of the gate before tagging; the framework tag is a patch |
|
||||
| T-33-65 | Tampering | pins to moving targets | medium | mitigate | apps pin tags (go.mod versions, submodule pointers at tags, pnpm git URLs with #tag); check-pins on the demo |
|
||||
| T-33-SC | Tampering | npm/Go installs | high | mitigate | no new package in this plan; lockfiles regenerated only to swap link: for the first-party tag and reviewed in the pin commits |
|
||||
</threat_model>
|
||||
|
||||
<verification>
|
||||
- `bash scripts/check-phase33.sh --all` green before the checkpoint.
|
||||
- After release: all logged tags on the remotes, consumers and compat green, the changelog post reachable.
|
||||
</verification>
|
||||
|
||||
<success_criteria>
|
||||
- Unit tests for all new code (SC-4) and the full gate green.
|
||||
- Release in order after the go-ahead, apps re-pinned, framework changelog post, deploys only when named.
|
||||
</success_criteria>
|
||||
|
||||
## Artifacts this phase produces
|
||||
|
||||
- Unit test files listed in files_modified (framework, three Go plugins, element and editor suites, three layers).
|
||||
- Completed `scripts/check-phase33.sh` stages; filled `33-VALIDATION.md` (`nyquist_compliant: true`).
|
||||
- Release log entries (TAG lines) in `33-release-log.md`; tags (versions fixed at Task 4): framework v0.5.x, sm-journal-plugin, sm-sitemap-plugin, sm-seo-plugin, vue-seo-layer, vue-journal-layer, vue-menu-layer, vue-faq-layer; remote repository vue-seo-layer on git.golem15.com; app commits re-pinning the tags and applying the 33-12/33-13 patches; the summercms.io changelog post for the framework tag.
|
||||
|
||||
<output>
|
||||
Create `.planning/phases/33-seo-output-audit-and-content/33-14-SUMMARY.md` when done; list for the orchestrator the g15office comment to post and whether g15office task w8kupqi3 still needs closing.
|
||||
</output>
|
||||
338
.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
Normal file
338
.planning/phases/33-seo-output-audit-and-content/33-PATTERNS.md
Normal file
@@ -0,0 +1,338 @@
|
||||
# Phase 33: SEO output, audit and content - Pattern Map
|
||||
|
||||
**Mapped:** 2026-10-28
|
||||
**Files analyzed:** ~45 groups of new/modified files across 13 repos
|
||||
**Analogs found:** 40 / 45 (the rest are in "No Analog Found")
|
||||
|
||||
Paths are relative to the meta repo root (`/media/nvme/dev/golem15/summercms.io/summercms`). Every analog below is git-tracked in its own repo (checked with `git ls-files`); nothing points into `.msd/` mirrors.
|
||||
|
||||
## File Classification
|
||||
|
||||
| New/Modified File | Plan | Role | Data Flow | Closest Analog | Match |
|
||||
|---|---|---|---|---|---|
|
||||
| `summercms.go/modules/pact/content.go` (+ `PublishedAt`, `Parents`, `Authors`, `Images`, `Videos`, `Kind`) | 33-01 | model (seam) | transform | itself, lines 60-81 | exact |
|
||||
| `summercms.go/modules/signpost/README.md`, `docs/` pages | 33-01 | docs | - | module README structure (CLAUDE.md) | exact |
|
||||
| `summercms.go/scripts/check-phase33.sh` | 33-01 | config/gate | batch | `summercms.go/scripts/check-phase32.sh` | exact |
|
||||
| `sm-journal-plugin/classes/content_descriptors.go` (fill new fields) | 33-02 | service | transform | itself (`describePosts`, `firstImages`) | exact |
|
||||
| `sm-journal-plugin/models/settings.go` + `models/settings/fields.yaml` (H1 setting, e.g. `content_h1_to_h2`) | 33-02 | model | CRUD | same file (`RSSEnabled` bool + switch field) | exact |
|
||||
| `sm-journal-plugin/updates/2026102800xx_add_golem15_journal_settings_h1.go` | 33-02 | migration | - | `sm-seo-plugin/updates/202610280001_add_golem15_seo_redirects_source_key.go` | exact |
|
||||
| `sm-journal-plugin/config/config.yaml` (new; config key for the H1 default) | 33-02 | config | - | `sm-seo-plugin/config/config.yaml` + `ConfigFS()` in `sm-seo-plugin/plugin.go:79-80` | exact |
|
||||
| `sm-journal-plugin/controllers/api/posts.go` (expose H1 setting in Show/Index payload) | 33-02 | controller | request-response | `sm-journal-plugin/controllers/api/rss.go:17-40` (settings row read) | exact |
|
||||
| `sm-journal-plugin/classes/headings.go` (H1->H2 on every write path) + write-path calls in `controllers/api/posts.go`, admin save, MCP | 33-02 | utility | transform | `sm-journal-plugin/classes/format_html.go` | role-match |
|
||||
| `sm-journal-plugin/console/fix_headings.go` (`journal:fix-headings --dry-run`) | 33-02 | command | batch | `sm-journal-plugin/console/export_posts.go:24-60` | exact |
|
||||
| `sm-journal-plugin/assets/src/blogeditor/*.ts` (heading levels, outline, rel checkboxes, alt) | 33-02 | component | event-driven | `assets/src/blogeditor/toolbar.ts`, `extensions.ts` | exact |
|
||||
| `sm-sitemap-plugin/classes/*` (writer, slots, lastmod, rebuild, indexnow, html groups) | 33-03/04 | service | file-I/O / batch | `sm-sitemap-plugin/classes/generator.go`, `serialize.go` (rewrite) | role-match |
|
||||
| `sm-sitemap-plugin/filter.go` (exported `Filter`) | 33-03 | interface | request-response | `pact` capability interfaces + `app.Lookup[T]()` (see Shared) | role-match |
|
||||
| `sm-sitemap-plugin/jobs.go` (`RebuildArgs`, `IndexNowArgs`) | 33-03/04 | job | batch | `sm-seo-plugin/jobs.go` + `classes/generate.go:14-28,168-177` | exact |
|
||||
| `sm-sitemap-plugin/models/settings.go`, `models/{url,slot}.go` | 33-03 | model | CRUD | `sm-sitemap-plugin/models/settings.go`, `sm-seo-plugin/models/settings.go` | exact |
|
||||
| `sm-sitemap-plugin/updates/*` | 33-03 | migration | - | `sm-sitemap-plugin/updates/202610110002_create_golem15_sitemap_settings.go` | exact |
|
||||
| `sm-sitemap-plugin/routes.go` (index, `sitemap-<slug>-<n>.xml`, IndexNow key, HTML groups API) | 33-03/04 | route | request-response | itself, lines 30-60 | exact |
|
||||
| `sm-seo-plugin/classes/sitemap_filter.go`, `registry.go`, `llms.go`, `site.go`, `autolinks.go` | 33-05/06/11 | service | request-response / CRUD | `sm-seo-plugin/classes/robots.go`, `redirects.go`, `settings_write.go` | role-match |
|
||||
| `sm-seo-plugin/models/settings.go` + `fields.yaml` (`links_new_tab`, publisher, outbound lists) | 33-05/06/11 | model | CRUD | same file + `classes/settings_write.go:40-120` | exact |
|
||||
| `sm-seo-plugin/models/{page,crawl,crawl_issue,autolink}.go` + `updates/*` | 33-05/10/11 | model/migration | CRUD | `sm-seo-plugin/models/redirect.go`, `updates/202610270006_create_golem15_seo_redirects.go` | exact |
|
||||
| `sm-seo-plugin/controllers/api/{registry,site,crawls,autolinks}.go` | 33-05/10/11 | controller | request-response | `sm-seo-plugin/controllers/api/redirects.go`, `issues.go` | exact |
|
||||
| `sm-seo-plugin/controllers/{registry,crawls,autolinks}.go` + `config_*.yaml` | 33-05/10/11 | admin screen | CRUD | `sm-seo-plugin/controllers/redirects.go` + `redirects/config_{list,form,filter}.yaml` | exact |
|
||||
| `sm-seo-plugin/mcp.go`, `operations.go` (new tools, parity) | 33-05/10/11 | config | request-response | `sm-seo-plugin/mcp.go:26-52,331-343` | exact |
|
||||
| `sm-seo-plugin/routes.go` (new routes) | 33-05/10 | route | request-response | itself, lines 32-77 | exact |
|
||||
| `sm-seo-plugin/classes/schema/*` (@graph builder, validators) | 33-06 | service | transform | `sm-seo-plugin/classes/resolver.go`, `templates.go` | partial |
|
||||
| `sm-seo-plugin/classes/crawl/*` (fetch, parse, checks, store) + crawl job in `jobs.go` | 33-10 | service/job | batch | `sm-seo-plugin/jobs.go`; fetch via `summercms.go/modules/fetchguard/fetch.go:41` | role-match |
|
||||
| `sm-seo-plugin/classes/issues.go` (merge crawl issues, `h1` CMS check gated by Journal setting) | 33-10 | service | transform | itself, lines 12-60 | exact |
|
||||
| `summercms.go/modules/lagoon/attach/thumb.go` (+ `webp.go`: WebP variant per thumb) | 33-11 | utility | file-I/O | itself, `ThumbKey` lines 154-243 | exact |
|
||||
| WebP conga job (framework `lagoon/attach` or journal) | 33-11 | job | batch | `sm-seo-plugin/jobs.go` + `classes/settings_write.go:301-313` (enqueue after commit) | exact |
|
||||
| `summercms.go/.planning/notes/2026-10-28-webp-gen2brain.md` | 33-11 | decision note | - | `.planning/notes/2026-10-07-embedded-admin-release-gate.md` | exact |
|
||||
| `vue-seo-layer/lib/seo-module.ts` | 33-07/08 | config (Nuxt module) | - | `vue-journal-layer/lib/journal-module.ts:35-85` | exact |
|
||||
| `vue-seo-layer/server/api/__site__/cache/purge.post.ts` + `server/lib/siteCachePurge.ts` (moved) | 33-07 | route | request-response | `vue-journal-layer/server/api/__site__/cache/purge.post.ts`, `server/lib/siteCachePurge.ts` | exact (move) |
|
||||
| `vue-seo-layer/server/middleware/seo.ts`, `server/routes/*` (robots, sitemaps, llms, verification), `server/plugins/*` | 33-07/08 | middleware/route | request-response | `vue-journal-layer/server/routes/rss.xml.ts`, `server/plugins/journal-revalidate.ts` | role-match |
|
||||
| `vue-seo-layer/app/composables/{useCmsSeo,useSchemaNode,usePagination}.ts` | 33-07/08 | hook | request-response | `vue-journal-layer/app/composables/useJournalApi.ts`, `app/utils/seo.ts`, `app/utils/pagination.ts` | role-match |
|
||||
| `vue-seo-layer/app/components/Seo/{Breadcrumbs,Pagination}.vue`, HTML sitemap page | 33-08 | component | request-response | `vue-journal-layer/app/components/Journal/Pagination.vue` | role-match |
|
||||
| `vue-seo-layer/testing/*`, `tests/*.test.ts` | 33-07/14 | test | - | `vue-journal-layer/testing/smoke-ssr.mjs`, `fixture-api.mjs`, `tests/seo.test.ts` | exact |
|
||||
| `vue-journal-layer/lib/journal-module.ts` (`postTitleTag`, `breadcrumbs` options) | 33-09 | config | - | itself, lines 40-46 and 74-82 | exact |
|
||||
| `vue-journal-layer/app/journal-pages/PostPage.vue` (title tag, breadcrumbs) | 33-09 | component | request-response | itself, line 14 and 46 | exact |
|
||||
| `vue-journal-layer/app/utils/htmlGate.ts` (h1->h2 demotion following the Journal API flag) | 33-09 | utility | transform | itself, `gateJournalHtml` 268-272 | exact |
|
||||
| `vue-journal-layer/app/components/Journal/PostCard.vue`, `utils/seo.ts` removal, `@nuxtjs/seo` drop | 33-09 | component | - | itself | exact |
|
||||
| `vue-menu-layer/*`, `vue-faq-layer/*` (extend seo layer, delete `server/lib/siteCachePurge.ts` copies) | 33-09 | config | - | same edits as vue-journal-layer | exact |
|
||||
| App changes (`sm-demo-app`, `sm-summercmsio-app`, `sm-bm-app`, `sm-grzybyfunkcjonalne-app`): go.mod, summer.yaml, nuxt.config, package.json, nginx | 33-12/13 | config | - | Phase 32 app wiring (32-05 commits in `sm-demo-app`) | role-match |
|
||||
| Tests per repo | 33-14 | test | - | `sm-seo-plugin/testmain_test.go`, `classes/issues_test.go`, `settings_test.go`, `summercms.go/modules/lagoon/attach/thumb_test.go` | exact |
|
||||
|
||||
## Pattern Assignments
|
||||
|
||||
### `summercms.go/modules/pact/content.go` (seam, 33-01)
|
||||
|
||||
**Analog:** itself, lines 60-81. Additive optional fields only, documented with one sentence per field in the existing comment style; no SEO words (D-90).
|
||||
```go
|
||||
// ContentLocale is a record in one locale. URL is its public path, "" when
|
||||
// the locale or the host has no public page for it. Title, Description and
|
||||
// Image (a URL) are the record's own defaults for page metadata; Words is the
|
||||
// body's word count, nil when the type has no body.
|
||||
type ContentLocale struct {
|
||||
Locale string
|
||||
URL string
|
||||
Title string
|
||||
Description string
|
||||
Image string
|
||||
Words *int
|
||||
}
|
||||
```
|
||||
Fill side: `sm-journal-plugin/classes/content_descriptors.go` `describePosts` (line 72), `firstImages` (133), `copyTime` (162).
|
||||
|
||||
---
|
||||
|
||||
### Journal H1 setting (33-02): `sm-journal-plugin/models/settings.go`, `models/settings/fields.yaml`, migration, config key, API
|
||||
|
||||
**Model analog** (`models/settings.go`, singleton row ID=1): add a bool column, add it to `Fillable()` and `Rules()` exactly like `rss_enabled`:
|
||||
```go
|
||||
RSSEnabled bool `gorm:"column:rss_enabled"`
|
||||
...
|
||||
func (Settings) Fillable() []string { return []string{ ..., "rss_enabled", ... } }
|
||||
func (Settings) Rules() map[string]string { return map[string]string{ ..., "rss_enabled": "boolean", ... } }
|
||||
```
|
||||
**fields.yaml analog** (same file):
|
||||
```yaml
|
||||
show_all_posts:
|
||||
span: left
|
||||
label: golem15.journal::lang.journal.show_all_posts_label
|
||||
comment: golem15.journal::lang.journal.show_all_posts_comment
|
||||
type: switch
|
||||
default: true
|
||||
tab: golem15.journal::lang.journal.tab_general
|
||||
```
|
||||
Labels go in `lang/en/lang.yaml` and `lang/pl/lang.yaml`.
|
||||
|
||||
**Migration analog** `sm-seo-plugin/updates/202610280001_add_golem15_seo_redirects_source_key.go` (additive ALTER with Rollback, `Register(...)` in `init`):
|
||||
```go
|
||||
var addRedirectSourceKey = []*gormigrate.Migration{{
|
||||
ID: "202610280001_add_golem15_seo_redirects_source_key",
|
||||
Migrate: func(tx *gorm.DB) error { return tx.Exec(`ALTER TABLE ... ADD COLUMN ...`).Error },
|
||||
Rollback: func(tx *gorm.DB) error { return tx.Exec(`ALTER TABLE ... DROP COLUMN IF EXISTS ...`).Error },
|
||||
}}
|
||||
func init() { Register(addRedirectSourceKey...) }
|
||||
```
|
||||
Use `DEFAULT true` so existing sites keep D-50 behaviour. Journal's own migrations live in `sm-journal-plugin/updates/` with `updates/registry.go`.
|
||||
|
||||
**Config key:** Journal has no `config/config.yaml` yet. Copy SEO's: `sm-seo-plugin/config/config.yaml` (commented `golem15.seo.<key>` defaults) and `plugin.go:79-80`:
|
||||
```go
|
||||
// ConfigFS ships config/config.yaml.
|
||||
func (p *Plugin) ConfigFS() fs.FS { return configFS }
|
||||
```
|
||||
plus `_ pact.HasConfig = (*Plugin)(nil)` (plugin.go:26). Config read pattern: `app.Config.String(key)` as in `sm-journal-plugin/plugin.go:73-76`. Decide precedence (config key as default/override of the settings row) and document it in the README.
|
||||
|
||||
**Reading the row in a handler** (`controllers/api/rss.go:24-27`), with a hard default on miss:
|
||||
```go
|
||||
var settings models.Settings
|
||||
if err := db.WithContext(r.Context()).First(&settings, 1).Error; err != nil {
|
||||
settings = models.Settings{RSSLanguage: "en-us", RSSPostsPerFeed: 20, RSSEnabled: true}
|
||||
}
|
||||
```
|
||||
Expose the flag in the public post payload of `Show` (`controllers/api/posts.go:122`) so the layer reads it from the Journal API, not a layer option.
|
||||
|
||||
**Command** `console/fix_headings.go`, copy `console/export_posts.go:24-60` (bonfire.Command with `Name`, `Flags` incl. `{Name: "dry-run", Bare: true}`, `Examples`, `flagOn(in, "dry-run")`, `mustDB(app)`), register in `plugin.go` `Commands()` (lines 113-118). When the setting is off it returns an error naming the setting.
|
||||
|
||||
---
|
||||
|
||||
### `sm-seo-plugin` settings additions (`links_new_tab`, publisher, outbound lists) (33-05/06/11)
|
||||
|
||||
**Analog:** `sm-seo-plugin/classes/settings_write.go`. Every new column must be added in four places: the model (`models/settings.go`), the allowed-columns list (lines ~36-41), `SettingsValues` (46-69, history + API), and `SetSettingsValue` switch (72+). Bool columns follow the existing `url_lowercase` case. Then `models/settings/fields.yaml` (Links tab) and the MCP `update_settings` tool picks it up automatically through `/_seo/api/v1/settings`.
|
||||
```go
|
||||
func SettingsValues(st models.Settings) map[string]any {
|
||||
return map[string]any{
|
||||
"site_name": st.SiteName,
|
||||
"url_lowercase": st.URLLowercase,
|
||||
...
|
||||
}
|
||||
}
|
||||
```
|
||||
Migration: same additive ALTER pattern as above, `DEFAULT true` for `links_new_tab`.
|
||||
|
||||
---
|
||||
|
||||
### `sm-seo-plugin` MCP tools (33-05/10/11): `mcp.go`, `operations.go`
|
||||
|
||||
**Analog:** `mcp.go:26-52`. Each tool binds to a `/_seo/api/v1` route; `Guard: mcpGuard`, `Permissions: []string{mcpPermission}`; destructive tools set `Destructive: &destructive`. `operations.go` must map each new admin operation to its tool (parity test `operations_test.go`).
|
||||
```go
|
||||
{
|
||||
Name: "list_issues",
|
||||
Title: "List SEO issues",
|
||||
Description: "Lists the CMS-data SEO issues: ...; each names the tool that fixes it.",
|
||||
Guard: mcpGuard,
|
||||
Method: http.MethodGet,
|
||||
Path: "/_seo/api/v1/issues",
|
||||
Input: apicontrollers.ListIssuesInput{},
|
||||
Permissions: []string{mcpPermission},
|
||||
},
|
||||
```
|
||||
|
||||
### `sm-seo-plugin/routes.go` (33-05/10)
|
||||
|
||||
**Analog:** itself, 32-77. Public, frontend-called endpoints (`/site`, route report, registry read) go in the first group wrapped in `noindex(...)` with a throttle bucket; management endpoints go in the second group with `api := "throttle:" + BucketAPI`.
|
||||
```go
|
||||
r.Group("/_seo/api/v1", nil, func(g pact.Router) {
|
||||
g.Get("/resolve", noindex(apicontrollers.Resolve(p.Service)), "throttle:"+BucketResolve)
|
||||
g.Post("/notfound", noindex(apicontrollers.NotFound(p.Service)), "throttle:"+BucketNotFound)
|
||||
})
|
||||
r.Group("/_seo/api/v1", nil, func(g pact.Router) {
|
||||
api := "throttle:" + BucketAPI
|
||||
g.Get("/issues", apicontrollers.ListIssues(p.Service), api)
|
||||
})
|
||||
```
|
||||
Token-authenticated frontend POSTs (route report): copy the `notfound_token` approach (`config/config.yaml` `notfound_token` + `controllers/api/notfound.go`).
|
||||
|
||||
### `sm-seo-plugin/classes/issues.go` (crawler merge, 33-10)
|
||||
|
||||
**Analog:** itself 12-60. New kinds are constants in the same block; each `Issue` names the fixing tool (`seo_` prefix).
|
||||
```go
|
||||
const (
|
||||
IssueMissingTitle = "missing_title"
|
||||
...
|
||||
)
|
||||
type Issue struct {
|
||||
Kind string `json:"kind"`
|
||||
URL string `json:"url"`
|
||||
Locale string `json:"locale,omitempty"`
|
||||
Details map[string]any `json:"details,omitempty"`
|
||||
Tool string `json:"tool"`
|
||||
}
|
||||
```
|
||||
|
||||
### Admin screens (registry, crawls, autolinks)
|
||||
|
||||
**Analog:** `sm-seo-plugin/controllers/redirects.go` + `controllers/redirects/config_{list,filter,form}.yaml`, `models/redirect.go` + `models/redirect/{columns,fields}.yaml`, registration in `controllers/admin_registry.go`, nav in `admin_navigation.go`, permission `golem15.seo.manage` in `admin_permissions.go`. Partials (`_hint.htm`) as in `controllers/notfound/`.
|
||||
|
||||
---
|
||||
|
||||
### conga jobs (sitemap rebuild, IndexNow ping, crawl, WebP variants)
|
||||
|
||||
**Analog:** `sm-seo-plugin/jobs.go` (whole file) and `classes/generate.go`.
|
||||
```go
|
||||
// generate.go
|
||||
const GenerateKind = "golem15.seo.generate_entries"
|
||||
type GenerateEntriesArgs struct { Type string `json:"type"` }
|
||||
func (GenerateEntriesArgs) Kind() string { return GenerateKind }
|
||||
|
||||
// jobs.go
|
||||
func (p *Plugin) Jobs() []pact.Job {
|
||||
return []pact.Job{ conga.Job(p.generateEntries, conga.MaxAttempts(3)) }
|
||||
}
|
||||
var _ pact.HasJobs = (*Plugin)(nil)
|
||||
|
||||
// dispatch (generate.go:168-177)
|
||||
m, err := conga.From(s.app)
|
||||
return m.Dispatch(ctx, db, GenerateEntriesArgs{Type: typeKey}, conga.DispatchOpts{Label: s.Phrase("golem15.seo::lang.jobs.generate_entries", nil)})
|
||||
```
|
||||
Enqueue after a write commits (`classes/settings_write.go:301-313`):
|
||||
```go
|
||||
lagoon.AfterCommit(ctx, tx, func(ctx context.Context, _ *gorm.DB) {
|
||||
db, err := s.GormDB()
|
||||
if err != nil { return }
|
||||
if _, err := s.EnqueueGenerate(ctx, db.WithContext(ctx), ""); err != nil {
|
||||
log.Warn("golem15.seo: queue entry generation", "error", err)
|
||||
}
|
||||
})
|
||||
```
|
||||
Schedules: conga periodic jobs (check `summercms.go/modules/conga/conga.go` for the periodic option before planning).
|
||||
|
||||
### Crawler / IndexNow outbound HTTP
|
||||
|
||||
**Analog:** `summercms.go/modules/fetchguard/fetch.go:41` — `fetchguard.Fetch(ctx, rawURL, policy, cfg)`; redirects are never followed (3xx returned as `Result`), so the crawler records redirected links itself and re-invokes Fetch for each hop. Errors are always `*fetchguard.Error`.
|
||||
|
||||
---
|
||||
|
||||
### WebP variants: `summercms.go/modules/lagoon/attach/thumb.go` (+ new `webp.go`) (33-11)
|
||||
|
||||
**Analog:** `ThumbKey` (thumb.go:154-243). Hang points:
|
||||
- Key: `thumbKey := PartitionDirectory(f.DiskName) + ThumbFilename(f.ID, w, h, 0, 0, mode, ext)`; the WebP variant key = same name with `.webp` appended or `ext` replaced (`ThumbFilename` coerces ext to `[a-z0-9]+`, so `"webp"` is safe). Store it next to the thumb in the same bucket.
|
||||
- Encoder seam: `encodeImage` is a package var (thumb.go:119-130) switched on ext; add a `"webp"` branch calling `github.com/gen2brain/webp` (or a separate `encodeWebP` var for tests).
|
||||
- Content type switch (thumb.go ~222-228): add `image/webp`.
|
||||
- Error/cleanup: on encode or close error `_ = deleteKey(ctx, bucket, key)`; existence check via `bucket.Exists` makes the job idempotent.
|
||||
```go
|
||||
wr, err := bucket.NewWriter(ctx, thumbKey, &blob.WriterOptions{ContentType: contentType})
|
||||
encErr := encodeImage(wr, resized, ext)
|
||||
closeErr = wr.Close()
|
||||
if encErr != nil || closeErr != nil { _ = deleteKey(ctx, bucket, thumbKey); ... }
|
||||
```
|
||||
- Generation runs in a conga job (not in `Thumb`), dispatched when a thumb is first generated or on upload; `Thumb` callers (`cabana/field_file.go:640`, journal API) emit the WebP URL only if the variant exists (`bucket.Exists`). Tests: `lagoon/attach/thumb_test.go`.
|
||||
- `go.mod` change only after the decision note in `.planning/notes/`.
|
||||
|
||||
---
|
||||
|
||||
### `vue-seo-layer/lib/seo-module.ts` and journal-layer options (33-07/08/09)
|
||||
|
||||
**Analog:** `vue-journal-layer/lib/journal-module.ts:35-85`. `defineNuxtModule` with `configKey`, `defaults`, and resolved options copied into `runtimeConfig.public.<key>`:
|
||||
```ts
|
||||
export default defineNuxtModule<JournalModuleOptions>({
|
||||
meta: { name: 'vue-journal-layer', configKey: 'journal' },
|
||||
defaults: { routes: { ...DEFAULT_JOURNAL_ROUTES }, perPage: {...}, sort: 'published_at desc', relatedCount: 3, rss: true },
|
||||
setup(options, nuxt) {
|
||||
const pub = nuxt.options.runtimeConfig.public as Record<string, any>
|
||||
pub.journal = { ...(pub.journal ?? {}), routes, perPage: { ...options.perPage }, sort: options.sort, relatedCount: options.relatedCount, rss: options.rss }
|
||||
},
|
||||
})
|
||||
```
|
||||
Add `postTitleTag` (default `undefined` = follow the Journal API flag) and `breadcrumbs: true` to `defaults` and to `pub.journal`. Pages read them as `PostPage.vue:14`: `const cfg = useRuntimeConfig().public.journal as JournalModuleOptions`; title at line 46 `<h1 class="journal-post__title">` becomes `<component :is="titleTag" ...>`.
|
||||
|
||||
### `vue-journal-layer/app/utils/htmlGate.ts` (33-09)
|
||||
|
||||
**Analog:** `gateJournalHtml` (268-272). Add a pure option (e.g. `{ demoteH1: boolean }`) applied after sanitizing; pages pass the Journal API flag. Pure TS so `tests/htmlGate.test.ts` covers it with `node --test`.
|
||||
```ts
|
||||
export function gateJournalHtml(html: string | null | undefined): { safe: boolean; html: string } {
|
||||
if (!html) return { safe: true, html: '' }
|
||||
const clean = sanitizeHtml(html, POLICY)
|
||||
return { safe: clean === sanitizeHtml(html, KEEP_ALL), html: clean }
|
||||
}
|
||||
```
|
||||
|
||||
### Site-cache purge move (33-07, 33-09)
|
||||
|
||||
**Analog:** `vue-journal-layer/server/lib/siteCachePurge.ts` (byte-identical copies in `vue-menu-layer/server/lib/` and `vue-faq-layer/server/lib/`), route `server/api/__site__/cache/purge.post.ts`, plugin `server/plugins/site-cache-purge.ts`, tests `tests/sitePurge.test.ts`, `testing/purge-check.mjs`. Move them into `vue-seo-layer` unchanged, then add the resolve-LRU clear; delete the three copies in 33-09. Keep the pure-TS-outside-auto-import-dirs rule from the file header.
|
||||
|
||||
### Layer test harness
|
||||
|
||||
**Analog:** `vue-journal-layer/testing/{smoke-ssr.mjs,fixture-api.mjs,nuxt-server.mjs}` and `tests/*.test.ts` (`node --test`), `.playground/` for the module.
|
||||
|
||||
## Shared Patterns
|
||||
|
||||
### Plugin capability wiring
|
||||
**Source:** `sm-seo-plugin/plugin.go` (interface assertions block at ~line 20-30), `jobs.go`, `mcp.go:10`.
|
||||
**Apply to:** every new capability in sitemap/seo/journal: `var _ pact.HasX = (*Plugin)(nil)`.
|
||||
|
||||
### Service lookup across plugins (sitemap `Filter`, D-95)
|
||||
**Source:** `sm-journal-plugin/plugin.go:98-104`:
|
||||
```go
|
||||
if existing, ok := app.Lookup[*cooler.SiteCachePurger](); ok && existing != nil { return nil }
|
||||
if err := app.Publish(purger); err != nil { return err }
|
||||
```
|
||||
**Apply to:** SEO publishes its `sitemap.Filter` implementation in `Register`/`Boot`; sitemap looks it up with `app.Lookup[sitemap.Filter]()` and treats absence as "include everything".
|
||||
|
||||
### Settings singleton + history
|
||||
**Source:** `sm-seo-plugin/classes/settings_write.go` (`SettingsRow`, `SaveSettings` 171+, history record, after-commit job).
|
||||
**Apply to:** sitemap settings, SEO publisher/links settings.
|
||||
|
||||
### Config defaults
|
||||
**Source:** `sm-seo-plugin/config/config.yaml` (commented keys, read as `golem15.<plugin>.<key>`), `ConfigFS()`.
|
||||
**Apply to:** Journal H1 key, sitemap file-size/IndexNow keys, SEO route-report token.
|
||||
|
||||
### Frontend-facing API answers
|
||||
**Source:** `sm-seo-plugin/routes.go:79-85` `noindex(h)` wrapper and throttle buckets (`Buckets()` 94+ with `surf.TrustedProxies`).
|
||||
**Apply to:** `/site`, route report, HTML-sitemap groups API, IndexNow key route.
|
||||
|
||||
### Logging
|
||||
**Source:** package-level `pluginLog`/`log` in `logger.go` of each plugin; `log.Warn("golem15.seo: ...", "error", err)`.
|
||||
|
||||
### Tests
|
||||
**Source:** `sm-seo-plugin/testmain_test.go` (Docker Postgres, `flag.Parse()` + `testing.Short()`), `fixture_test.go`, `classes/issues_test.go`; framework `modules/lagoon/attach/thumb_test.go`.
|
||||
**Apply to:** 33-14.
|
||||
|
||||
## No Analog Found
|
||||
|
||||
| File | Role | Data Flow | Reason |
|
||||
|---|---|---|---|
|
||||
| `sm-seo-plugin/classes/schema/*` (JSON-LD @graph, per-type validators) | service | transform | No JSON-LD code exists; use RESEARCH.md Pattern sections, resolver.go only for structure |
|
||||
| `sm-seo-plugin/classes/crawl/parse.go` / checks | service | transform | No HTML-parsing crawler yet; use `golang.org/x/net/html` per RESEARCH "Don't Hand-Roll" |
|
||||
| Sitemap XML writer (index/urlset/image/news, hreflang) | service | file-I/O | Current `serialize.go` is PHP byte-parity and is removed (D-32); use `encoding/xml` per RESEARCH |
|
||||
| `vue-seo-layer/lib` SSR build guard + route report artefact | config | batch | No build-time Nuxt hook code in existing layers; RESEARCH.md |
|
||||
| WebP encoding itself | utility | transform | New dependency `github.com/gen2brain/webp`; only the thumb plumbing has an analog |
|
||||
|
||||
## Metadata
|
||||
|
||||
**Analog search scope:** `summercms.go/modules/{pact,lagoon/attach,conga,fetchguard}`, `sm-seo-plugin`, `sm-sitemap-plugin`, `sm-journal-plugin`, `vue-journal-layer`, `vue-menu-layer/server/lib`, `vue-faq-layer/server/lib`
|
||||
**Files scanned:** ~60
|
||||
**Pattern extraction date:** 2026-10-28
|
||||
19
.planning/phases/33-seo-output-audit-and-content/COVERAGE.md
Normal file
19
.planning/phases/33-seo-output-audit-and-content/COVERAGE.md
Normal file
@@ -0,0 +1,19 @@
|
||||
# API Coverage — IndexNow
|
||||
|
||||
> Full coverage by default. Opt-outs are explicit, reasoned decisions. Phase 33 integrates one external API: IndexNow (D-31), in `sm-sitemap-plugin` plan 33-04. Google Search Console, the Rich Results Test and the News sitemap are not API integrations (the admin links to the Rich Results Test page; sitemaps are files Google fetches).
|
||||
|
||||
| capability | decision | reason |
|
||||
|---|---|---|
|
||||
| bulk URL submission (POST JSON {host, key, urlList} to api.indexnow.org) | INTEGRATE | |
|
||||
| key generation (32 hex characters from crypto/rand) and key rotation | INTEGRATE | |
|
||||
| key file served at the site root (/<key>.txt) | INTEGRATE | |
|
||||
| success answers 200 and 202 recorded as the last notification | INTEGRATE | |
|
||||
| 400 bad request recorded in the last status | INTEGRATE | |
|
||||
| 403 key not valid shown in the admin (S2 err_key) | INTEGRATE | |
|
||||
| 422 URLs not matching the host shown in the admin (S2 err_host) | INTEGRATE | |
|
||||
| 429 too many requests: retry with the job's attempts, shown in S2 (err_rate) | INTEGRATE | |
|
||||
| batching at most 10 000 URLs per request | INTEGRATE | |
|
||||
| notification of new, changed and removed URLs (rebuild diff) | INTEGRATE | |
|
||||
| keyLocation parameter (key file elsewhere on the host) | OPT-OUT | the key file is served at the root, which covers every URL of the host; a key file elsewhere would narrow the URLs the key may submit |
|
||||
| single-URL GET submission (?url=&key=) | OPT-OUT | the bulk POST covers single URLs (a urlList of one) |
|
||||
| per-engine endpoints (bing.com/indexnow, yandex.com/indexnow and others) | OPT-OUT | api.indexnow.org shares every submission with all participating engines |
|
||||
Reference in New Issue
Block a user