docs(14.2.1-03): complete cabana ML fields and proof-host boot plan

Co-authored-by: Cursor <cursoragent@cursor.com>
2026-10-06 13:30:18 +02:00
parent e3b3475b1c
commit c7e2e4b4ed
3 changed files with 228 additions and 13 deletions
--- a/.planning/ROADMAP.md
+++ b/.planning/ROADMAP.md
@@ -843,7 +843,7 @@ Plans:
  3. Cabana `markdown`/`mltext`/`mlmarkdown` compose; nested locale writes are not dropped; docs, OpenAPI, TS types and `boardwalk` `dist/` update in the same change.
  4. Proof host `sm-grzybyfunkcjonalne-app` boots with user+translate; unit tests are the last plan.

-**Plans:** 2/4 plans executed
+**Plans:** 3/4 plans executed

 Plans:

@@ -854,7 +854,7 @@ Plans:
 - [x] 14.2.1-02-PLAN.md — Translatable API, Locales admin, fixture save/read

 **Wave 3** *(blocked on Wave 2 completion)*
- [ ] 14.2.1-03-PLAN.md — Cabana markdown/ML fields, nested save, docs/OpenAPI/dist, proof host boot
+- [x] 14.2.1-03-PLAN.md — Cabana markdown/ML fields, nested save, docs/OpenAPI/dist, proof host boot

 **Wave 4** *(blocked on Wave 3 completion)*
 - [ ] 14.2.1-04-PLAN.md — Unit/integration tests last, phase gate, security review
--- a/.planning/STATE.md
+++ b/.planning/STATE.md
@@ -4,16 +4,16 @@ milestone: v1.0
 current_phase: 14.2.1
 current_phase_name: Translate plugin
 status: executing
-stopped_at: Completed 14.2.1-02-PLAN.md
-last_updated: "2026-10-06T10:22:58Z"
+stopped_at: Completed 14.2.1-03-PLAN.md
+last_updated: "2026-10-06T11:29:17Z"
 last_activity: 2026-10-06
-last_activity_desc: 14.2.1-02 Translatable API and Locales admin
-state_head: 44a8cbf
+last_activity_desc: 14.2.1-03 cabana ML fields and proof host boot
+state_head: e3b3475
 progress:
  total_phases: 26
  completed_phases: 12
  total_plans: 129
-  completed_plans: 127
+  completed_plans: 128
 milestone_name: milestone
 ---

@@ -29,11 +29,11 @@ See: .planning/PROJECT.md (updated 2026-09-16)
 ## Current Position

 Phase: 14.2.1 (Translate plugin) — EXECUTING
-Plan: 2 of 4 complete; next 14.2.1-03
-Status: Ready for cabana markdown/ML fields and proof host boot
-Last activity: 2026-10-06 — Translatable API, indexed lookup, and permissioned Locales admin
+Plan: 3 of 4 complete; next 14.2.1-04
+Status: Ready for unit/integration tests
+Last activity: 2026-10-06 — Cabana markdown/ML fields, docs/dist, and proof host boot

-Progress: [███████░░░] 67%
+Progress: [████████░░] 75%

 ## Performance Metrics

@@ -182,6 +182,7 @@ Progress: [███████░░░] 67%
 | Phase 14.1 P02 | 8 min | 3 tasks | 3 files |
 | Phase 14.2.1 P01 | 16 min | 3 tasks | 23 files |
 | Phase 14.2.1 P02 | 15 min | 3 tasks | 21 files |
+| Phase 14.2.1 P03 | 5 min | 3 tasks | 40 files |

 ## Accumulated Context

@@ -580,6 +581,7 @@ Recent decisions affecting current work:
 - [Phase 14.2.1]: Sibling plugin go.mod replace is ../summercms.go so isolated D-16 go test passes; host mounts replace via go.work.
 - [Phase 14.2.1]: MorphName is an import-stable string, never reflect.Type.String(); Translated applies D-11 fallback and TranslatedExact does not.
 - [Phase 14.2.1]: Locales is HasAdminControllers plus HasNavigation (not HasSettings); Fillable excludes is_default/sort_order; makeDefault uses GORM Updates maps.
+- [Phase 14.2.1]: Task 2 locked grzyby-submodules: proof host is sm-grzybyfunkcjonalne-app with plugins/golem15/user and plugins/golem15/translate; host go.work replace points at ../summercms.go.

 ### Pending Todos

@@ -632,6 +634,6 @@ Items acknowledged and carried forward from previous milestone close:

 ## Session Continuity

-Last session: 2026-10-06T10:22:58Z
-Stopped at: Completed 14.2.1-02-PLAN.md
+Last session: 2026-10-06T11:29:17Z
+Stopped at: Completed 14.2.1-03-PLAN.md
 Resume file: None
--- a/.planning/phases/14.2.1-translate-plugin/14.2.1-03-SUMMARY.md
+++ b/.planning/phases/14.2.1-translate-plugin/14.2.1-03-SUMMARY.md
@@ -0,0 +1,213 @@
+---
+phase: 14.2.1-translate-plugin
+plan: 03
+subsystem: i18n
+tags: [translate, cabana, markdown, mltext, mlmarkdown, TranslationWriter, proof-host, sm-grzybyfunkcjonalne-app]
+
+requires:
+  - phase: 14.2.1-02
+    provides: "Translatable SetTranslated/Translated/WithLocale and permissioned Locales admin"
+provides:
+  - "cabana markdown, mltext, and mlmarkdown field types with nested locale-map lifting"
+  - "Framework-owned cabana.TranslationWriter plus sm-translate-plugin Boot adapter"
+  - "Safe cabana.RenderMarkdown (goldmark, no unsafe HTML)"
+  - "SPA MarkdownField, MLTextField, MLMarkdownField with shared locale selector"
+  - "Docs, regenerated OpenAPI/TS, committed boardwalk dist"
+  - "sm-grzybyfunkcjonalne-app boots golem15.user + golem15.translate from durable submodules"
+affects: [14.2.1-04 tests, 15-journal-plugin]
+
+actuals:
+  tokens: 27343
+  tasks: 3
+  commits: 2
+plan_head_before: 234111d245d300e19dcfc33b00f311c881a214fb
+plan_head_after: e3b3475b1cb5d3321e72be8863df6af6527db6b2
+plugin_repo_head_after: a3553b9c4b8a9c83debe950198f568ee9b6000a6
+host_repo_head_after: 4d32e86
+
+tech-stack:
+  added: []
+  patterns:
+    - "ML locale maps are lifted before ProjectWritableFields; default locale fills the host scalar; other locales go through TranslationWriter inside the host save transaction"
+    - "Proof host mounts compiled plugins as git submodules at plugins/golem15/{user,translate} with go.work use plus host and workspace replaces"
+
+key-files:
+  created:
+    - modules/cabana/field_ml.go
+    - modules/cabana/field_markdown.go
+    - modules/cabana/ml_smoke_test.go
+    - admin/src/components/form/fields/MarkdownField.vue
+    - admin/src/components/form/fields/MLTextField.vue
+    - admin/src/components/form/fields/MLMarkdownField.vue
+    - admin/tests/form/MLFields.test.ts
+    - ../sm-translate-plugin/classes/admin_writer.go
+    - ../sm-grzybyfunkcjonalne-app/summer.yaml
+    - ../sm-grzybyfunkcjonalne-app/go.work
+    - ../sm-grzybyfunkcjonalne-app/.gitmodules
+    - ../sm-grzybyfunkcjonalne-app/boot_test.go
+  modified:
+    - modules/cabana/form_schema.go
+    - modules/cabana/crud.go
+    - modules/cabana/README.md
+    - docs/backend/forms.md
+    - docs/backend/admin-controllers.md
+    - admin/src/components/form/registry.ts
+    - admin/src/components/form/formState.ts
+    - admin/tests/form/registry.test.ts
+    - modules/boardwalk/dist/
+    - ../sm-translate-plugin/plugin.go
+
+key-decisions:
+  - "Task 2 locked grzyby-submodules: the proof host is sm-grzybyfunkcjonalne-app with plugins/golem15/user and plugins/golem15/translate"
+  - "Host go.work replace points at ../summercms.go so the plugin sibling replace is overridden when mounted"
+
+patterns-established:
+  - "cabana.TranslationWriter lives in the framework; the translate plugin Boot-publishes an adapter; there is no public translate-write endpoint"
+  - "mlmarkdown composes MarkdownField; goldmark stays in cabana.RenderMarkdown without html.WithUnsafe"
+
+requirements-completed: [D-06, D-09, D-12, D-13, D-14, D-15, D-16, D-17]
+
+coverage:
+  - id: D1
+    description: "Nested mltext save lifts the locale map, writes English on the host column, and Polish through TranslationWriter"
+    requirement: D-06
+    verification:
+      - kind: unit
+        ref: "modules/cabana#TestMLNestedSaveSmoke"
+        status: pass
+    human_judgment: false
+  - id: D2
+    description: "SPA registry resolves markdown/mltext/mlmarkdown, sends nested locale records, and sanitizes markdown preview"
+    requirement: D-06
+    verification:
+      - kind: unit
+        ref: "admin/tests/form/MLFields.test.ts"
+        status: pass
+      - kind: unit
+        ref: "admin/tests/form/registry.test.ts"
+        status: pass
+    human_judgment: false
+  - id: D3
+    description: "Cabana README, forms/admin docs, OpenAPI, generated TS types, and boardwalk dist stay in sync with application-neutral examples"
+    verification:
+      - kind: other
+        ref: "go test ./cmd/summer -run TestDocsTree && go run ./cmd/summer docs:build --check"
+        status: pass
+      - kind: other
+        ref: "scripts/check-admin-openapi.sh && npm --prefix admin run build"
+        status: pass
+    human_judgment: false
+  - id: D4
+    description: "sm-grzybyfunkcjonalne-app mounts user and translate as submodules, generates the plugin list, and registers Locales admin"
+    requirement: D-13
+    verification:
+      - kind: integration
+        ref: "sm-grzybyfunkcjonalne-app#TestBootUserTranslate"
+        status: pass
+    human_judgment: false
+  - id: D5
+    description: "Task 2 proof-host layout locked as grzyby-submodules"
+    requirement: D-13
+    verification: []
+    human_judgment: true
+    rationale: "Layout choice is a recorded human decision, not an automated assertion"
+
+duration: 5min
+completed: 2026-10-06
+status: complete
+---
+
+# Phase 14.2.1 Plan 03: Cabana ML fields and proof-host boot Summary
+
+**Cabana markdown/mltext/mlmarkdown with transactional TranslationWriter saves, regenerated admin artifacts, and sm-grzybyfunkcjonalne-app booting user+translate from durable submodules**
+
+## Performance
+
+- **Duration:** 5 min (continuation from Task 2; Task 1 landed in a prior executor)
+- **Started:** 2026-10-06T11:23:45Z
+- **Completed:** 2026-10-06T11:29:17Z
+- **Tasks:** 3
+- **Files modified:** 40
+- **Token actuals:** 27343 (chars/4 excluding rebuilt `modules/boardwalk/dist`; 320645 including it)
+
+## Accomplishments
+
+- Cabana accepts `markdown`, `mltext`, and `mlmarkdown`. Nested locale maps are lifted before `ProjectWritableFields`; the default locale fills the host scalar; other locales reach `cabana.TranslationWriter` inside the permissioned host save transaction. `cabana.RenderMarkdown` uses goldmark without unsafe HTML.
+- The SPA sends `Record<string,string>` per ML field, shares one locale selector across controls, copies from another locale, and composes `mlmarkdown` from `MarkdownField`.
+- Cabana README, `docs/backend/forms.md`, and admin-controller save semantics are updated with acme/blog examples. OpenAPI was regenerated (unchanged), TypeScript types regenerated, and `modules/boardwalk/dist/` rebuilt.
+- Task 2 recorded **grzyby-submodules**. `sm-grzybyfunkcjonalne-app` mounts `plugins/golem15/user` @ `0fe5b91` and `plugins/golem15/translate` @ `a3553b9`, uses go.work plus host replaces, lists only `golem15.user` and `golem15.translate`, and `TestBootUserTranslate` activates both plugins and sees Locales admin. Journal is absent. Go tables remain `golem15_translate_*`.
+
+## Task Commits
+
+Each task was committed atomically:
+
+1. **Task 1: Submit one mltext map through cabana and persist default plus Polish values**
+   - `a04116d` (feat) summercms.go — markdown and multilingual cabana fields
+   - `a3553b9` (feat) sm-translate-plugin — publish cabana TranslationWriter adapter
+2. **Task 2: Confirm the one-way proof-host submodule layout** — decision `grzyby-submodules` (no code commit)
+3. **Task 3: Complete docs/OpenAPI/TS/dist and boot the user+translate proof host**
+   - `e3b3475` (feat) summercms.go — docs, registry tests, boardwalk dist
+   - `4d32e86` (feat) sm-grzybyfunkcjonalne-app — host layout and boot smoke
+
+**Plan metadata:** (this commit)
+
+The proof host was not pushed. summercms.go was not pushed.
+
+## Files Created/Modified
+
+- `modules/cabana/field_ml.go` — locale-map lift and TranslationWriter bridge
+- `modules/cabana/field_markdown.go` — `RenderMarkdown`
+- `modules/cabana/ml_smoke_test.go` — nested `{en,pl}` save smoke
+- `admin/src/components/form/fields/{Markdown,MLText,MLMarkdown}Field.vue`
+- `admin/tests/form/MLFields.test.ts` and `registry.test.ts`
+- `modules/cabana/README.md`, `docs/backend/forms.md`, `docs/backend/admin-controllers.md`
+- `modules/boardwalk/dist/` — regenerated Vite output
+- `../sm-translate-plugin/classes/admin_writer.go` and `plugin.go` Boot publish
+- `../sm-grzybyfunkcjonalne-app/{summer.yaml,go.mod,go.work,.gitmodules,main.go,plugins.gen.go,boot_test.go}`
+
+## Decisions Made
+
+- Task 2 selected **grzyby-submodules**: durable proof-host layout is `sm-grzybyfunkcjonalne-app` with `plugins/golem15/user` and `plugins/golem15/translate`, matching D-13/D-16 and sm-bm-app. `fonoteka-host` and `vendored-copy` were not taken.
+- Host `go.work` replace `git.golem15.com/golem15/summercms => ../summercms.go` overrides the translate plugin's sibling `../summercms.go` replace when the plugin is mounted at `plugins/golem15/translate`.
+- OpenAPI/TS were regenerated with `scripts/check-admin-openapi.sh`; the document did not change because no swag annotations were added. Dist was rebuilt, not hand-edited.
+
+## Deviations from Plan
+
+### Auto-fixed Issues
+
+**1. [Rule 3 - Blocking] Vitest `--run` paths are relative to `admin/`**
+- **Found during:** Task 3 verify
+- **Issue:** `npm --prefix admin test -- --run admin/tests/form/registry.test.ts ...` reports no test files because Vitest's cwd is `admin/` and `include` is `tests/**/*.test.ts`.
+- **Fix:** Ran `tests/form/registry.test.ts tests/form/MLFields.test.ts` (50 passed).
+- **Files modified:** none
+- **Verification:** Vitest `Test Files 2 passed (2)`, `Tests 50 passed (50)`
+- **Committed in:** n/a (command-only)
+
+---
+
+**Total deviations:** 1 auto-fixed (1 blocking)
+**Impact on plan:** Required for the written verify command's intent. No API or layout change.
+
+## Issues Encountered
+
+None beyond the Vitest path mismatch.
+
+## Authentication Gates
+
+None.
+
+## User Setup Required
+
+None - no external service configuration required.
+
+## Next Phase Readiness
+
+- Ready for 14.2.1-04 unit/integration tests.
+- Journal (Phase 15) can mount on this host using the same submodule paths.
+- Proof host commit `4d32e86` is local only; push when a later plan requires it.
+
+---
+*Phase: 14.2.1-translate-plugin*
+*Completed: 2026-10-06*
+
+## Self-Check: PASSED