golem15/summercms
3
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

docs(14.2): research phase domain

Browse Source
This commit is contained in:
Jakub Zych
2026-10-07 20:16:10 +02:00
parent 5429d46751
commit fa047559cf
1 changed files with 662 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

662
.planning/phases/14.2-local-fonoteka-frontend-on-local-summercms-backend/14.2-RESEARCH.md Normal file
View File

@@ -0,0 +1,662 @@
# Phase 14.2: Local Fonoteka frontend on local SummerCMS backend - Research
**Researched:** 2026-10-07
**Domain:** Local dev-stack glue: Go seed command, start script and fail-closed guard, Nuxt dev proxy, Playwright e2e against the Go backend
**Confidence:** HIGH for the code facts (read in this session, binary built and probed). MEDIUM for the Centrifugo side, because the shared `/etc/centrifugo/config.json` cannot be read.
<user_constraints>
## User Constraints (from CONTEXT.md)
### Locked Decisions
#### Local data
- **D-01:** Local data comes from `fonoteka migrate` followed by a new seed command. The Phase 20 `import:winter` runner is not pulled forward, and PHP data is not imported in this phase.
- **D-02:** The seed is an application command, `fonoteka dev:seed` (final name at the planner's discretion), in the fonoteka plugin, not a framework seeder hook. It refuses to run unless the app environment is local/dev, and it is idempotent: a second run changes nothing. It creates:
- a verified user;
- an owned collection;
- a few albums;
- a wishlist entry;
- a personal API token (`inv_` prefix) so fonoteka-mcp can be pointed at the local stack.
- **D-03:** Seeded albums get bundled test cover images (small, embedded or generated, no network), attached through the normal attach path into `storage/app/uploads/public`. Their `/storage/app/uploads/public/...` URLs then resolve through the Nuxt `/storage` proxy right away.
- **D-04:** The seeded user's credentials come from `E2E_EMAIL` / `E2E_PASSWORD`, the same variables the Nuxt Playwright suite uses, with a fallback to `demo@example.com` / `changeme`. That way the seed and the Playwright login match without extra wiring.
#### Stack startup
- **D-05:** A single script, `fonoteka.go/scripts/dev-stack.sh`, uses host services and adds no docker compose. It:
1. checks that the services are reachable;
2. runs `summer build`, `migrate` and `dev:seed`;
3. reindexes search after the seed;
4. starts `fonoteka serve`;
5. runs the fail-closed guard (D-09);
6. starts `pnpm dev` in the sibling `vue-fonoteka-app`.
- **D-06:** Postgres, Typesense and Centrifugo are all required. The script refuses to start, and names the missing service, if any of them is unreachable. Realtime is expected to work locally, which means `NUXT_PUBLIC_CENTRIFUGO_WS_URL` is set and the app origin `http://localhost:3119` is in Centrifugo's allowed origins (documented).
- **D-07:** Go serves on `:8423`, which is distinct from PHP's `:8422` and from the framework default `:8080`. PHP and Go can then run side by side, and a stale origin is obvious.
- **D-08:** Settings and secrets live in a gitignored `fonoteka.go/.env.dev`, with a committed `.env.dev.example` that holds placeholders only. It covers the DSN, JWT secret, app key, Typesense and Centrifugo keys, and the Nuxt-side values. The script sources it and fails, listing each missing key. The script passes `NUXT_DEV_BACKEND_ORIGIN`, `NUXT_INTERNAL_API_ORIGIN` and `NUXT_PUBLIC_CENTRIFUGO_WS_URL` as environment variables on the `pnpm dev` process. It never writes `vue-fonoteka-app/.env`, so the developer's PHP-targeted setup stays intact.
#### PHP fall-through guard
- **D-09:** The guard has three parts:
1. **Preflight:** before Nuxt starts, the script probes the Go origin for a Go-only marker and refuses to continue if the marker is missing, if the target is `:8422`, or if a PHP backend answers.
2. **Pinned SSR origin:** `NUXT_INTERNAL_API_ORIGIN` is always set explicitly to the Go origin, so SSR can never fall back to `https://plytarium.com`.
3. **Post-start probe:** once Nuxt is up, the script probes through Nuxt's proxy (`http://localhost:3119/...`) and confirms the marker comes back, which proves the proxy reaches Go.
- **D-10:** The marker is a route only the Go binary serves (an existing framework health/readiness route, or the smallest new one) that stays **outside the parity manifest**. No manifest route's response changes, and no new header is added to API responses.
- **D-11:** `vue-fonoteka-app` may receive **small non-breaking changes** (user's decision). The constraint: the app must still run without issues against the PHP backend. Gaps found during the session are fixed in Go first, with a parity case added where a recorded PHP response exists. An app change is acceptable only when it leaves PHP behavior unchanged (for example an env-switched test helper, a new backend-agnostic spec, or docs and `.env.example` notes). Commits in `vue-fonoteka-app` go to its own repo, which is a submodule of the PHP `fonoteka` repo.
- **D-12:** Failures show up through the Go request log, which is redacted by sunscreen and records each request's path and status, and through Nuxt's normal behavior. The script tees both processes into labeled log files, and the run docs say to watch them for 4xx/5xx and 404 responses. No 404 tally or dev-only error UI is added.
#### Flow proof
- **D-13:** The flows are proven twice:
- **Playwright:** the existing Playwright e2e suite runs against the Go stack.
- **Manual session:** one checklist-driven session, recorded as UAT evidence. It covers login, browse collections and albums, search, edit, rate, cover upload, wishlist add/remove, and realtime working.
- **D-14:** The Playwright seed helper (`tests/e2e/helpers/runTinker.ts`) gets a non-breaking switch. When `E2E_BACKEND=go` is set, it seeds by running the Go binary's `dev:seed` (binary path from `E2E_GO_BIN` or similar) instead of `php artisan tinker`. When the switch is unset, today's PHP behavior is unchanged.
- **D-15:** The Go gate is the core-flow subset of specs: `auth.setup`, `login`, `smoke`, `fonoteka-item` (browse/edit/rate/cover), `public-share`, `realtime`, `i18n`, plus whichever specs cover search and wishlist. The researcher maps each flow to a spec. `fonoteka-ai-assist`, `fonoteka-bulk-add`, `offline`, `registration-invitation` and `responsive` are run and reported but do not block, because they need external keys or are outside the core flows.
- **D-16:** If no existing spec covers a core flow (wishlist add/remove and search are the likely candidates), a new spec is added to `vue-fonoteka-app`. It must be backend-agnostic, so it passes against both PHP and Go.
- **D-17:** The last plan of the phase (unit tests last, project rule) adds Go unit tests for `dev:seed` (environment refusal, idempotency, created shape) and for the marker route. It also adds `summercms.go/scripts/check-phase14.2.sh`, following the existing `check-phase*.sh` pattern, which:
- runs `go vet` and `go test ./...`;
- exercises the guard against a stale `:8422` origin and against an unset internal origin, and expects a refusal each time;
- runs the Go-gate Playwright subset (D-15) against the started stack.
### Claude's Discretion
- The exact command name and flags of the seed command, the number of seeded albums and their content, and how the test images are produced.
- Which Go-only route serves as the marker, and how a PHP answer is detected in the preflight.
- The script structure: subcommands, how processes are supervised and stopped, log file locations, and whether `summer build` runs on every start.
- The run docs (a section in `fonoteka.go/README.md` or a dedicated `RUNNING-LOCALLY.md`) and the keys in `.env.dev.example`.
- How River jobs run locally (`work_in_serve: true` is the current default and is fine).
### Deferred Ideas (OUT OF SCOPE)
- Bringing the Phase 20 `import:winter` runner forward to load real local PHP data was considered and not chosen. It stays in Phase 20.
- A 404/5xx tally by path at script shutdown was offered and not chosen. It can be added later if the logs prove too noisy.
#### Reviewed Todos (not folded)
- `2026-10-01-benchmark-the-application-on-wintercms-vs-summercms.md`: a benchmark, not local-run glue (Phase 20 lists it as deferred too).
- `nest-framework-packages-under-modules.md`, `bonfire-duplicate-command-names.md`, `backend-admin-api-tokens.md`: framework work unrelated to the local Nuxt run; matched by keyword only.
</user_constraints>
<phase_requirements>
## Phase Requirements
| ID | Description | Research Support |
|----|-------------|------------------|
| QA-05 | "Cutover: the parity harness is green on all 154 routes and vue-fonoteka-app and fonoteka-mcp run unchanged against the Go backend" [VERIFIED: .planning/REQUIREMENTS.md:124] | This phase covers the "vue-fonoteka-app runs unchanged against the Go backend" half locally. See the Flow-to-Spec map (§Q1), the Go gaps that block an unchanged run (G1–G4), the guard design (§Pattern 4), and the Validation Architecture. The fonoteka-mcp half is covered only as far as minting a local `inv_` token (D-02); MCP must call Go directly on `:8423` because Nuxt does not proxy `/api/v1/fonoteka/*`. Note: the REQUIREMENTS traceability table already marks QA-05 "Phase 15 / Complete" [VERIFIED: .planning/REQUIREMENTS.md:245]. That is a bookkeeping inconsistency for the planner/verifier to fix; it does not change this phase's scope. |
</phase_requirements>
## Project Constraints (from CLAUDE.md)
- Lean planning: few, large plans per phase. Present the plan count with a one-line scope for each plan and wait for confirmation before writing PLAN.md files.
- Unit tests are always the **last** plan of a phase. Earlier plans may carry smoke tests.
- Go: standard library first. Add a dependency only when the research doc or a phase decision names it. Keep `go vet` and `go test ./...` green at every commit.
- Compiled plugins only. No runtime plugin loading.
- API parity is the acceptance test. Do not "improve" response shapes. (Relevant here: the marker route stays outside the manifest, and no manifest response changes, per D-10.)
- Commits: no co-author tags, one logical change per commit, planning docs and code in separate commits. `vue-fonoteka-app` commits go to its own repo. Shared plugin submodules (`plugins/golem15/user` and others) are committed inside the submodule first, then the pointer is bumped in a separate commit. Never stage submodule files from the parent.
- Core plugins (user, blog, pages, payment) must not get breaking changes. `sm-user-plugin` is shared, so do not add a marker route or change behavior there.
- Documentation: any change to a `summercms.go/modules/*` exported API, config key or CLI command updates that module's `README.md` and the affected `docs/` pages in the same change. Check with `go test ./cmd/summer -run TestDocsTree` and `summer docs:build --check`. Framework READMEs never name a consuming application. The `fonoteka.go` README is the application, so naming Płytarium and Nuxt there is fine.
- Do not hand-edit `fonoteka.go/main.go` or `plugins.gen.go`; `summer build` regenerates them.
- Two repos: `summercms.go` is the framework only; `fonoteka.go` is the app. Planning docs stay in `summercms.go/.planning`.
## Summary
The phase is mostly glue, but this research turned up four **Go-side gaps** that would make an "unchanged" Nuxt run fail. Each was verified by building the current `fonoteka.go` binary and running it:
1. **Plugin CLI commands get no database.** `fonoteka fonoteka:reindex` and `fonoteka user:token:create` both exit 1 with `database is not configured` in the real binary. Only the lagoon, conga and surf runtime commands open and publish the pool. D-05 step 3 (reindex) is therefore broken today, and the new `dev:seed` must open the database itself.
2. **The Go binary does not serve `/storage/app/uploads/public/...`.** `route:list` has no such route. The framework ships `attach.StaticHandlerPublic`, but nothing mounts it. Every cover through the Nuxt `/storage` proxy would 404, which breaks D-03.
3. **There is no per-request log.** `surf` has no `slog` call at all, so the "Go request log … records each request's path and status" that D-12 relies on does not exist.
4. **There is no health or marker route.** D-09's post-start probe goes *through the Nuxt proxy*, so the marker must sit under a prefix Nuxt proxies (`/_fonoteka/api`, `/_user/api`, `/_feedback/api`, `/api/realtime`, `/storage`, `/plugins/golem15/feedback`). A framework path such as `/_summer/health` would not be reachable through Nuxt.
On the Nuxt side, the biggest risk in the CONTEXT turns out to be smaller than expected: **`runTinker`/`seedE2EFixtures` has zero callers**. No spec seeds anything. The specs need only a logged-in user (E2E_EMAIL/E2E_PASSWORD), an active collection and, for browse/i18n/offline, some albums. The real gap is coverage. `fonoteka-item.spec.ts` only *creates* an album (no edit, rate or cover), and **no spec covers search, edit, rate, cover upload or wishlist add/remove**. `realtime.spec.ts` is also stale: its `realtime-status`/`realtime-degraded` test IDs were removed from the app on 2026-06-12, so it fails against *any* backend. `public-share.spec.ts` stubs every `/public/*` call with `page.route`, so it never touches the backend.
**Primary recommendation:** close G1–G4 in Go first (plan 1). Then build `dev-stack.sh` with `preflight` / `up` / `down` subcommands and a dev-only marker route under `/_fonoteka/api/v1/` (plan 2). Add backend-agnostic, self-seeding specs for album edit/rate/cover, search and wishlist, rewrite `realtime.spec.ts`, and add the `E2E_BACKEND=go` switch (plan 3). Finish with Go unit tests and `check-phase14.2.sh`, which parses the Playwright JSON report and treats any *skip* in a gate spec as a failure (plan 4).
## Architectural Responsibility Map
| Capability | Primary Tier | Secondary Tier | Rationale |
|------------|-------------|----------------|-----------|
| Login, JWT issue/refresh | API / Backend (Go `golem15.user`) | Browser (JS cookie `auth_token`, Bearer header) | JWT lives in a JS-readable cookie and is sent as `Authorization: Bearer`. The backend sets no cookies, so the proxy needs no cookie rewriting. |
| Same-origin API routing in dev | Frontend Server (Nuxt dev: Vite proxy + Nitro devProxy + routeRules) | — | `NUXT_DEV_BACKEND_ORIGIN` is read once at config load. No CORS is involved. |
| SSR API calls | Frontend Server (Nitro, `internalApiOrigin`) | API | SSR uses the absolute origin, not the proxy. Pinning it is D-09.2. |
| Upload serving `/storage/app/uploads/public/*` | API / Backend (Go, **new mount**) | CDN/nginx in prod (Phase 20) | Nuxt proxies `/storage` to the backend origin. Go must answer it. |
| Realtime token + subscribe proxy | API (Go `/api/realtime/token`, `/api/realtime/subscribe`) | Centrifugo (external service) | The browser connects to Centrifugo directly (not proxied). Centrifugo calls Go's subscribe proxy. |
| Search | API (Go → Typesense when `search_use_typesense` is on) | Database (fallback) | Go falls back to SQL on an engine error, logging a Warn. |
| Seed data | CLI (fonoteka plugin command) | Database + upload bucket | App command (D-02), not a framework hook. |
| Fail-closed guard | Shell script (`dev-stack.sh preflight`) | API marker route | The script decides; the Go route only identifies itself. |
## Key Findings and Gaps (read first)
| # | Finding | Evidence | Impact / what the plan must do |
|---|---------|----------|---------------------------------|
| G1 | Plugin commands run without a database. `fonoteka:reindex` prints `fonoteka:reindex: database is not configured` (rc=1); `user:token:create` prints `golem15.user: database is not configured` (rc=1). | [VERIFIED: ran freshly built binary with SUMMER_ENV=local and a bogus DSN; `migrate:status` reached the DB (`lagoon: ping postgres: failed to connect … password authentication failed`) while the two plugin commands failed before connecting]. Cause: `console/reindex.go:55-58` reads `app.Lookup[*gorm.DB]()`, and only `lagoon/commands.go:230-240 withDB`, `conga/commands.go:213-224 withDB` and `surf/serve.go:40-47` open and publish the pool. | `dev:seed` must call `lagoon.OpenFromApp` + `lagoon.Publish` itself. Publish is required (not just Open), because the fonoteka slug and credential hooks register through `lagoon.OnDatabase` (`plugin.go:209-210`). `fonoteka:reindex` needs the same fix (app-level), or D-05 step 3 fails. The `user:token:*` commands in the shared `sm-user-plugin` are broken the same way. This is out of scope here (the seed mints its own token), so log it as a todo. |
| G2 | No `/storage` route in Go. | [VERIFIED: `route:list` of a fresh build; the non-API routes are only `_feedback`, `/plugins/golem15/feedback/assets/js/embed.js`, `/.well-known/oauth-authorization-server`, `/oauth/mcp/*`, `/api/realtime/{token,subscribe}`, `/plytadmin*`]. The framework has `func StaticHandlerPublic(bucket *blob.Bucket, prefix string, db *gorm.DB) http.Handler` [VERIFIED: summercms.go/modules/lagoon/attach/static.go:32], which no package mounts. | Mount `GET {storage.uploads.public_path_prefix}/{path...}` → `attach.StaticHandlerPublic`, resolving bucket and DB per request. Phase 20 D-06 also routes `/storage/app/uploads` to Go, so this is needed beyond local dev. |
| G3 | No request access log. | [VERIFIED: `grep slog surf/*.go` (non-test) returns nothing; no `access_log` anywhere in modules]. The sunscreen README only describes a redacting handler. | D-12's "Go request log" must be added: an opt-in surf middleware (config key, default off) logging method, matched pattern, status and duration. Its exported surface needs README/docs updates. |
| G4 | No health/marker route, and the marker must be Nuxt-proxied. | [VERIFIED: route list above; Nuxt proxy prefixes at nuxt.config.ts:247-266, 364-372, 392-401]. | Add a dev-only route under `/_fonoteka/api/v1/` in the fonoteka plugin (see Pattern 3). |
| G5 | `runTinker`/`seedE2EFixtures` has **no callers**; specs do not seed. | [VERIFIED: `grep -rn "runTinker\|seedE2EFixtures" tests/` matches only `helpers/runTinker.ts` and comments]. | The D-14 switch is cheap. The real seeding need is a user, an active collection, a wishlist and some albums (with covers for offline). New specs should seed themselves through the UI or API. |
| G6 | `realtime.spec.ts` is stale. | [VERIFIED: `realtime.spec.ts:28` `page.getByTestId('realtime-status')`, `:39` `getByTestId('realtime-degraded')`; neither ID exists in `app/` (grep). Git `-S"realtime-status"`: added ff33376 2026-06-10, removed 6fcdb8e 2026-06-12 "compose dashboard"]. | It fails on PHP and Go alike. Rewrite it as a backend-agnostic spec (a D-11 test-only change). |
| G7 | `fonotekaReachable()` probes `E2E_BACKEND_URL` directly, defaulting to `'http://localhost:8422'`. | [VERIFIED: tests/e2e/helpers/fonotekaReachable.ts:3,8]. | If unset or left in `tests/e2e/.env.local`, gate specs **skip** (Go-only stack) or gate on PHP. The check script must export `E2E_BACKEND_URL=http://127.0.0.1:8423` and fail on any skip. |
| G8 | Search silently falls back to SQL when Typesense errors. | [VERIFIED: classes/album_search.go:217-228, `logger.Warn("golem15.fonoteka: album search engine failed, falling back to the database search", …)`]. | A search spec passes even with Typesense broken. The check script should grep the Go log for that Warn and fail on it. |
| G9 | `search_use_typesense` is seeded **false**, and `fonoteka:reindex` refuses while it is off. | [VERIFIED: updates/20_remaining.go:198-200 `SELECT 1, false, NOW(), NOW()`; console/reindex.go:68-70 `!searchEnabled(ctx, gdb)` → `reindexNotConfigured`]. | `dev:seed` must set it true. Flip it last (after the albums exist) so the seed's own writes do not hit Typesense before the index exists, then run reindex. |
| G10 | The Typesense container is stopped. | [VERIFIED: `docker ps -a`: `plytarium-typesense-instance typesense/typesense:26.0 Exited`; port binding `{"8108/tcp":[{"HostIp":"127.0.0.1","HostPort":"8181"}]}`]. | The preflight names it and suggests `docker start plytarium-typesense-instance`. |
| G11 | `fonoteka.go/storage/` is not gitignored. | [VERIFIED: fonoteka.go/.gitignore = `/bin/ /tmp/ *.exe go.work.sum *.sqlite parity/.vars/ parity/tmp/`; `storage/app/uploads` exists, empty]. | Seeded covers would show as untracked files. Add `/storage/app/uploads/public/` (and `.env.dev`) to `.gitignore`. |
| G12 | The shared Centrifugo (v6.5.1, systemd, `/etc/centrifugo/config.json`, mode 600 owned by `http`) cannot be read. Its subscribe proxy most likely targets PHP. | [VERIFIED: process `/usr/local/bin/centrifugo -c /etc/centrifugo/config.json`, listening `*:8787`; `centrifugo version` = v6.5.1]. Proxy target: [ASSUMED]. | See Open Question 1. A Go-issued token with the same HMAC secret connects, but `collection:{id}` subscribes go to whatever proxy endpoint the config names. |
| G13 | `fonoteka.go` submodules have pointer drift (`feedback`, `golem`, `user` each ahead by a "pin release dependencies" commit). | [VERIFIED: `git diff --submodule=log`]. | This was already the state before the phase. Plans must not sweep these pointers into phase commits by accident. |
## Q1. Flow → Spec map and seeding (D-15/D-16)
**No spec calls `runTinker` or `seedE2EFixtures`.** Seeding today is manual (the helper is "a DOCUMENTED, opt-in helper — it is NOT auto-run by the suite" [VERIFIED: tests/e2e/helpers/runTinker.ts:15-16]). What `seedE2EFixtures` would send if called [VERIFIED: runTinker.ts:92-106]:
- `\Golem15\User\Models\User::firstOrNew(['email' => E2E_EMAIL])`, then set the password and confirmation and `is_activated = true`, then save. The Go seed covers this.
- `\Golem15\Journal\Models\Post::updateOrCreate(['slug' => 'e2e-seed-post'], …)`. Journal is not part of `fonoteka.go`, and the app does not use `journalApiBase` anywhere (grep `journal` in `app/` returns nothing). Under `E2E_BACKEND=go` this step is **skipped**.
How each spec gets its data:
| Spec | Flow(s) it proves | Backend touched? | Data it needs | Gate (D-15) |
|------|-------------------|------------------|---------------|-------------|
| `auth.setup.ts` | login (UI, `/en/login`) → storageState `tests/e2e/.auth/user.json` | yes | user with E2E creds, `must_change_password=false` | gate (runs as `setup` project dependency) |
| `login.spec.ts` | login + "JWT never in markup" | yes | same user | gate |
| `smoke.spec.ts` | landing renders | no | — | gate |
| `fonoteka-item.spec.ts` | **create** album at `/albums/new` (only that, no edit/rate/cover) | yes (`fonotekaReachable` + creds) | active collection; genres (seeded by migrate) | gate |
| `public-share.spec.ts` | `/k/{token}` render, 404/429 panels | **no**: every `/_fonoteka/api/v1/public/{token}*` call is stubbed with `page.route` | none | gate (backend-agnostic, proves nothing about Go's `/public/*`) |
| `realtime.spec.ts` | intended: realtime badge | **stale**: test IDs removed 2026-06-12 | — | gate → **must be rewritten** |
| `i18n.spec.ts` | locale toggle, html lang, keys; one backend case `/kolekcja` export CTA `Eksportuj \d+ pozycj` | one case | albums in the active collection (count) | gate |
| `landing.spec.ts` | marketing landing | no | — | not listed (report) |
| `responsive.spec.ts` | `/albums` search input and filter sheet visible | yes | logged-in user | report-only |
| `offline.spec.ts` | Dexie offline sync, covers offline | yes | albums **with covers** (`blobCoverCount > 0`) | report-only |
| `fonoteka-ai-assist.spec.ts` | AI page shell (recognize stubbed) | yes | user | report-only |
| `fonoteka-bulk-add.spec.ts` | bulk add (Discogs fully stubbed) | yes | user | report-only |
| `registration-invitation.spec.ts` | registration/invite (fully stubbed) | no | — | report-only |
**Flows with NO covering spec, so new backend-agnostic specs are needed (D-16):**
| Flow | Existing selectors to use [VERIFIED: grep of `app/`] | Recommended spec |
|------|------------------------------------------------------|------------------|
| browse collections | collection switcher (no test ID found in this pass; the executor greps `useCollectionSwitcher` consumers) | covered in the manual session; optional assertion in `core-flows` |
| edit album | `album-edit`, `album-edit-mobile` (`pages/albums/[id]/index.vue`), `album-name`, `album-save` (`AlbumForm.vue`) | `album-edit-rate-cover.spec.ts` |
| rate | `rating-stars` (`RatingStars.vue`) | same spec |
| cover upload | file input in `AlbumCoverGallery.vue:114` (`type="file" accept="image/*" multiple class="sr-only"`); `PhotoUploader.vue:312,372`; the store posts to `/albums/${album.id}/photos` (`stores/fonoteka.ts:234`) | same spec, `setInputFiles` with an in-memory PNG (like `fonoteka-ai-assist.spec.ts` `PNG_1PX`) |
| search | `albums-search-input` (used by `responsive.spec.ts`) | `album-search.spec.ts`: create a uniquely named album, type its name, `expect.poll` for the tile |
| wishlist add/remove | `/wishlist/new` page, `` `wishlist-item-${album.id}` ``, `wishlist-item-remove` | `wishlist.spec.ts` |
**Self-seeding rule for new specs:** create the data each spec needs through the UI, or through `page.request` against the **Nuxt origin** (same-origin, proxied, Bearer from the `auth_token` cookie), with a `Date.now()` suffix in names. Such specs pass on PHP and Go alike and do not depend on `dev:seed` content beyond the user. Specs must use `fonotekaReachable()` plus the E2E creds gate like the existing ones, so PHP CI behavior is unchanged.
**What `dev:seed` must provide for the gate (minimum):** a user matching E2E creds (activated, `must_change_password=false`, `has_self_set_password=true`), an owned `kind=collection` collection persisted as the user's context, at least 3 albums (the i18n count and offline covers), a `kind=wishlist` collection with at least 1 album (the wishlist entry), and `search_use_typesense=true`.
## Q2. playwright.config.ts
[VERIFIED: vue-fonoteka-app/playwright.config.ts:10-56]
- Env loading: `dotenv.config({ path: 'tests/e2e/.env.local' })` then `tests/e2e/.env`. dotenv does **not** override variables already in the environment, so the check script's exports win.
- `FRONTEND_URL = process.env.E2E_FRONTEND_URL || 'http://127.0.0.1:3119'`; `use.baseURL = FRONTEND_URL`; port derived from it.
- `use.storageState: 'tests/e2e/.auth/user.json'`; projects `setup` (`testMatch: /.*\.setup\.ts/`, empty storage) and `chromium` (`dependencies: ['setup']`).
- `workers: 1`, `fullyParallel: false`, `retries: 0`, reporters `html` + `list`.
- `webServer: { command: \`pnpm dev --port ${FRONTEND_PORT} --host 127.0.0.1\`, url: FRONTEND_URL, reuseExistingServer: !process.env.CI, timeout: 120_000 }`.
Implications:
- Running against the stack: start the stack first, then run with `CI` **unset**, so Playwright reuses the running Nuxt. If Playwright launches its own `pnpm dev`, that process inherits Playwright's env, so the `NUXT_*` Go values must be exported in the check script too.
- Set `E2E_FRONTEND_URL=http://localhost:3119`. `i18n.spec.ts` and `landing.spec.ts` add cookies with the hard-coded `url: 'http://localhost:3119'`, so a `127.0.0.1` baseURL would not carry them. The D-06 Centrifugo origin is also `http://localhost:3119`.
- E2E env vars in use: `E2E_EMAIL`, `E2E_PASSWORD`, `E2E_FRONTEND_URL`, `E2E_BACKEND_URL`, `E2E_CENTRIFUGO` (`=== '1'`), `BACKEND_DIR` (runTinker PHP cwd; defaults to `path.resolve(__dirname, '../../../..')`, which is the PHP fonoteka root). New: `E2E_BACKEND`, `E2E_GO_BIN`, optionally `E2E_GO_DIR`.
- Gate run recommendation: `pnpm exec playwright test auth.setup.ts login.spec.ts smoke.spec.ts fonoteka-item.spec.ts public-share.spec.ts realtime.spec.ts i18n.spec.ts <new specs> --project=chromium --reporter=json`, with `PLAYWRIGHT_JSON_OUTPUT_NAME=<file>`. Parse `stats.unexpected == 0`, `stats.skipped == 0` and `stats.expected > 0`. A skip is how a misconfigured backend URL shows up (G7).
## Q3. nuxt.config.ts: env names, fallback chain, proxy list, port, auth
[VERIFIED: vue-fonoteka-app/nuxt.config.ts]
- `const BACKEND_ORIGIN = process.env.NUXT_DEV_BACKEND_ORIGIN || 'http://localhost:8000'` (line 30). Read **once at config load**.
- `devServer: { port: Number(process.env.NUXT_PORT) || 3119 }` (line 51).
- `internalApiOrigin: process.env.NUXT_INTERNAL_API_ORIGIN || process.env.NUXT_DEV_BACKEND_ORIGIN || process.env.NUXT_PUBLIC_SITE_URL || 'https://plytarium.com'` (lines 110-113).
- `public.centrifugoWsUrl: ''` (line 155). Overridden at runtime by `NUXT_PUBLIC_CENTRIFUGO_WS_URL`. Empty means realtime silently disabled (`useCentrifugo.ts:59-63`).
- `public.feedbackWidgetKey: process.env.NUXT_PUBLIC_FEEDBACK_WIDGET_KEY || ''` (line 128). A PHP widget key left in `.env` would make the widget call Go's `/_feedback/api/v1/{key}/config` with an unknown key. Have the script export it explicitly (empty unless `.env.dev` sets a Go-side key).
- Proxy prefixes, identical in `routeRules` (247-266), `nitro.devProxy` (364-372) and `vite.server.proxy` (392-401): `/_user/api`, `/_journal/api`, `/_fonoteka/api`, `/_feedback/api`, `/plugins/golem15/feedback`, `/api/realtime`, `/storage`. All use `changeOrigin: true`.
- Auth: JWT in the JS-readable `auth_token` cookie (SameSite=Lax), attached as `Authorization: Bearer` by `app/plugins/api.ts` on both SSR and client. SSR uses `config.internalApiOrigin` as `baseURL` (api.ts:28-30). No backend cookies and no CORS: the browser only talks to `:3119`, and SSR talks to Go server-to-server.
- **Env precedence:** Nuxt loads `vue-fonoteka-app/.env` through c12 `setupDotenv`, which only assigns a key `if (targetEnvironment[key] === void 0 || dotenvVars.has(key))` [VERIFIED: node_modules/.pnpm/c12@3.3.4…/c12/dist/index.mjs:28-31]. Variables exported on the `pnpm dev` process therefore win over `.env`, including deliberately empty strings. This confirms D-08's "pass env vars, never write `.env`" works.
## Q4. fonoteka.go facts for the seed, script and serve
- **Command registration:** `func (p *Plugin) Commands() []bonfire.Command { cmds := []bonfire.Command{ console.OAuthClientCommand(p.app), console.PruneNotificationsCommand(p.app), console.ReindexCommand(p.app), } … }` [VERIFIED: plugins/golem15/fonoteka/plugin.go:292-301]. Add `console.DevSeedCommand(p.app)` here, in a new file `console/dev_seed.go`. `bonfire.Command{Name, Description, Flags []bonfire.Flag{Name, Description, Default, Bare}, Args, Run func(ctx, in bonfire.Input, out bonfire.Output) error}` [VERIFIED: summercms.go/modules/bonfire/command.go:15-38].
- **Environment:** `Environment()` returns the env name. Detection: `envName = lookupEnv(c.environ, "SUMMER_ENV")`; if empty, `envName = "production"` [VERIFIED: summercms.go/modules/compass/config.go:193-199]. The seed refuses unless `app.Config.Environment()` is one of the allowed dev names. Recommend `local` and `dev` (D-02); the script sets `SUMMER_ENV=local`. Compass also merges `<config dir>/../.env` (`readDotEnv(filepath.Join(filepath.Dir(c.dir), ".env"))`, config.go:187). That means a `fonoteka.go/.env` would be read automatically, but `.env.dev` is **not**, so the script must export it (`set -a; . ./.env.dev; set +a`).
- **Config dir is cwd-relative:** `cfg, err := compass.Load("config")` [VERIFIED: fonoteka.go/main.go:31], and the bucket is `file://./storage/app/uploads/public` [VERIFIED: config/storage.yaml]. Every `bin/fonoteka` invocation (script, Playwright `E2E_GO_BIN`) must run with cwd = `fonoteka.go`.
- **Boot requirements for any command:** `golem15.user: jwt.secret is empty (set SUMMER_GOLEM15__USER__JWT__SECRET)` and `cabana: admin.jwt.secret is empty (set SUMMER_ADMIN__JWT__SECRET)` both fail even `route:list` [VERIFIED: ran binary]. DB-opening commands also need a valid `SUMMER_APP__KEY` (base64 of 32 bytes; `fonoteka key:generate` prints one) [CITED: 11.2-RESEARCH.md citing lagoon/connection.go:77-90].
- **Creating the data with existing code** (all in package `classes` of the fonoteka plugin unless noted):
- User: `usercontrollers.RegisterUser(ctx, app, tx, fields, usercontrollers.RegisterOptions{Activate: true})` hashes with `golem15.user.password.bcrypt_cost` and validates the model rules [VERIFIED: sm-user-plugin/controllers/registration.go:26-38,57]. Lookup by email first for idempotency. `BootstrapOwner` is unsuitable because it refuses once any user exists.
- Collection + context: `ProvisionCollection(ctx, tx, user)` returns the context collection, else the lowest accessible one, else creates `"Moja kolekcja"` (`DefaultCollectionName`) and persists the context [VERIFIED: classes/collection_provisioner.go:14-75].
- Wishlist: `ProvisionWishlist(ctx, tx, user)` reuses the own wishlist or creates `"Moja lista życzeń"` (`DefaultWishlistName`, `Kind: kindWishlist` where `const kindWishlist = "wishlist"`) [VERIFIED: classes/wishlist_resolver.go:15-19,48-84]. A wishlist entry is an album whose `collection_id` is the wishlist collection [VERIFIED: parity/fonoteka_seed_test.go:1324-1340 inserts wishlist albums with `collection_id = wishlistID`].
- Albums: `CreateAlbum(ctx, tx, collectionID, input map[string]any) (*models.Album, error)` [VERIFIED: classes/album_write_service.go:378-400]. Wrap it in `lighthouse.WithoutBroadcasting[models.Album](ctx, fn)` [VERIFIED: summercms.go/modules/lighthouse/suppress.go:19] so the seed queues no realtime broadcast jobs.
- Covers: `StoreAlbumPhoto(ctx, db, bucket, albumID, filename, data) (*attach.File, error)` writes under a Winter disk name and attaches to `photos` [VERIFIED: classes/album_files.go:72-85]. The bucket in a CLI context comes from `attach.OpenBucket(ctx, app.Config)` + `attach.Publish(app, bucket)` (exported; used by `surf/serve.go:110-122` and `lagoon/commands.go:208-228`). Generate the images with stdlib `image/png` (solid or gradient squares, deterministic per album). No network and no committed binaries are needed.
- Rating (optional, so "rate" has a baseline): `models.AlbumRating{AlbumID, UserID, Rating}` on table `golem15_fonoteka_album_ratings` [VERIFIED: models/album_rating.go].
- API token: `userclasses.APITokenPrefix(app)` reads `golem15.user.api_tokens.prefix` (`inv_` in this app) and `userclasses.MintAPIToken(prefix, userID, name, scopes, expiresAt, collectionIDs)` returns `(secret, *models.APIToken, error)`; allowed scopes are `"read", "write", "ai"` [VERIFIED: sm-user-plugin/classes/api_tokens.go:19-23,48-94]. For idempotency, see Pattern 1.
- Search setting: `models.Settings{SearchUseTypesense bool}` on table `golem15_fonoteka_settings`, singleton row `id = 1` [VERIFIED: models/settings.go; updates/20_remaining.go:198-200].
- **Lagoon attach path / cover file functions:** `StorePublicFile` → `attach.BlobKey(diskName)` → `bucket.WriteAll`; `AttachAlbumPhoto` sets `Field = "photos"`, `AttachmentType = models.Album{}.MorphName()` and `sort_order = id` [VERIFIED: classes/album_files.go:20-69]. Public URLs come out as `/storage/app/uploads/public/<partition>/<disk_name>` (prefix from `storage.uploads.public_path_prefix`) [VERIFIED: config/storage.yaml].
- **Serve address:** `serve` has flag `addr` with `Default: ":8080"`; an empty value falls back to `":8080"` [VERIFIED: summercms.go/modules/surf/serve.go:28-37]. Use `bin/fonoteka serve --addr 127.0.0.1:8423`, bound to loopback only.
- **Reindex:** the command name is exactly `fonoteka:reindex`, with flag `drop-old-items-index` [VERIFIED: console/reindex.go:44-50]. It refuses unless the engine is `typesense`, configured (API key) and `search_use_typesense` is on (reindex.go:68-70), and needs the G1 fix.
- **Other useful commands in the binary** [VERIFIED: `fonoteka --help`]: `migrate`, `migrate:status`, `key:generate`, `websockets:health` (works without a DB; prints `✗ Connection check failed: centrifugo: /info: HTTP 401` and exits 1 on a bad key [VERIFIED: ran]), `user:token:create` (broken by G1).
- **summer build:** `summer` is at `~/go/bin/summer` (built 2026-10-05), which is **not on PATH** in non-interactive shells. `buildCommand` uses `os.Getwd()` as the app dir [VERIFIED: summercms.go/cmd/summer/main.go:56-66] and writes `bin/<binary>` (`cmd/summer/runtime.go:105`). Recommend that the script build the CLI from source (`go -C "$FRAMEWORK" build -o "$TMP/summer" ./cmd/summer`) and then run `(cd "$APP" && "$TMP/summer" build)`, so a stale `~/go/bin/summer` is never used. `fonoteka.go/go.mod` has `replace git.golem15.com/golem15/summercms => ../summercms.go`, so framework edits are picked up.
## Q5. Marker route (D-10)
Existing Go routes outside `parity/manifest.yaml`: `/plytadmin*` (cabana admin, not Nuxt-proxied), `GET /plugins/golem15/feedback/assets/js/embed.js` (PHP serves the same file statically), `/.well-known/oauth-authorization-server` and `/oauth/mcp/*` (PHP serves these too, and they are in the manifest's `oauth` group) [VERIFIED: route:list + manifest auth groups]. **None is both Go-only and under a Nuxt-proxied prefix.** There is no framework health route.
**Recommendation:** add a route in the fonoteka plugin (the app's own namespace, so no shared plugin is touched): `GET /_fonoteka/api/v1/_dev/backend`, registered **only when `app.Config.Environment()` is not `production`** (env-gated: zero production surface, invisible to parity). It returns `200 {"backend":"summercms","app":"fonoteka","env":"<env>"}` with `Cache-Control: no-store`. Put it in its own `r.GroupRaw` (or a public group) with no auth and a small throttle. It is not added to the manifest or `routes.snapshot`. `TestParityContract` compares the snapshot against **PHP** `routes.php`, not against the Go table, so a Go-only route does not break it [VERIFIED: parity/parity_contract_test.go:13-45]. Phase route-table tests (`routes_table_phase1x_test.go`) assert properties of named routes, so the executor should run them after adding the route.
**Preflight logic (script):**
1. Refuse if `NUXT_DEV_BACKEND_ORIGIN` or `NUXT_INTERNAL_API_ORIGIN` is unset, if they differ, if the port is `8422`, or if the host is not loopback (`localhost`/`127.0.0.1`/`::1`). This covers any `plytarium.com` value.
2. `curl -sS -D headers -o body "$ORIGIN/_fonoteka/api/v1/_dev/backend"`: refuse unless the status is 200 **and** `jq -e '.backend=="summercms"'` holds.
3. Refuse if any response header matches `^X-Powered-By: PHP` (case-insensitive). The local PHP has `expose_php => On` [VERIFIED: `php -i`, PHP 8.5.10], so `php artisan serve` stamps `X-Powered-By: PHP/8.5.10` on every response. Go never sets it. PHP has no catch-all route in `plugins/golem15/fonoteka/routes.php` [VERIFIED: grep], so PHP answers 404 on the marker path, which step 2 already refuses.
4. Post-start: the same request against `http://localhost:3119/_fonoteka/api/v1/_dev/backend` (the Vite proxy) must return the same JSON. Also probe an unauthenticated `GET http://localhost:3119/_fonoteka/api/v1/albums` and expect 401 from Go.
## Q6. check-phase script pattern (D-17)
[VERIFIED: summercms.go/scripts/check-phase14.2.1.sh (410 lines; the most recent and leanest), check-phase14.sh (1265 lines)]
- Header comment describing the gate. `set -euo pipefail`, `unset FORCE_COLOR`.
- Paths from overridable env (`ROOT="${PHASE1421_ROOT:-$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)}"`, sibling repos `$ROOT/../…`).
- `*_REQUIRE=(TestA TestB …)` arrays of named tests that must pass.
- `detect()`: an embedded `python3` heredoc reading `go test -json`, with exit codes 1 fail/build, 2 skip, 3 zero tests or "no tests to run", 4 non-JSON, 5 missing required name, 6 data race. `go_json DIR ARGS…` runs `go test -json` and the detector.
- `run_self_test`: `bash -n`, then `expect_detect` on planted JSON lines for each exit code. It also checks that every `--mode)` case exists.
- One `run_<stage>` per mode, `run_all` looping `bash "${BASH_SOURCE[0]}" "--$stage"` with `PASS/FAIL` lines, and a final `echo "Phase 14.2.1 gate passed"`.
- `case "${1:---all}" in --self-test) … esac`.
Recommended modes for `check-phase14.2.sh`: `--self-test` (also plants a fake Playwright JSON with a skip and expects refusal), `--go` (`go vet` + `go_json` on the `fonoteka.go` plugin packages and the touched `summercms.go` modules, with `REQUIRE_TESTS` naming the new dev-seed, marker, storage-mount and access-log tests), `--docs` (`go test ./cmd/summer -run TestDocsTree` if framework modules changed), `--guard` (Pattern 4 refusal cases), `--e2e` (starts the stack via `dev-stack.sh up --detach` or requires it running, runs the Playwright gate with the JSON reporter, then greps the Go log for `album search engine failed` and for 5xx), and `--all`. The `--e2e` stage fails closed when services are missing (D-06). It is not silently skipped.
## Q7. Centrifugo local config and realtime keys
`config/realtime.yaml` keys and env mapping [VERIFIED: fonoteka.go/config/realtime.yaml; fonoteka.go/README.md:75-87]:
| Config key | Env | Default in repo |
|------------|-----|-----------------|
| `realtime.centrifugo.api_url` | `SUMMER_REALTIME__CENTRIFUGO__API_URL` | `http://127.0.0.1:8001/api` |
| `realtime.centrifugo.api_key` | `SUMMER_REALTIME__CENTRIFUGO__API_KEY` | `""` (nothing published) |
| `realtime.centrifugo.token_secret` | `SUMMER_REALTIME__CENTRIFUGO__TOKEN_SECRET` | `""` (token route answers 503 `{"error":"WebSocket not configured"}`) |
| `realtime.centrifugo.token_ttl` | `SUMMER_REALTIME__CENTRIFUGO__TOKEN_TTL` | `3600` |
| `realtime.centrifugo.ws_url` | `SUMMER_REALTIME__CENTRIFUGO__WS_URL` | `/ws` |
| `realtime.centrifugo.proxy_secret` | `SUMMER_REALTIME__CENTRIFUGO__PROXY_SECRET` | `""` (every subscribe denied) |
| `realtime.centrifugo.subscribe_path` | — | `/api/realtime/subscribe` |
| `realtime.broadcast_namespace` | `SUMMER_REALTIME__BROADCAST_NAMESPACE` | `""` |
Centrifugo v6 config keys [CITED: centrifugal.dev/docs/server/configuration; centrifugal.dev/docs/server/proxy]: `client.token.hmac_secret_key` (must equal Go `token_secret`), `client.allowed_origins` (add `http://localhost:3119` **and** `http://127.0.0.1:3119`), `http_api.key` (= Go `api_key`), `http_server.port`, `channel.proxy.subscribe.endpoint` (→ `http://127.0.0.1:8423/api/realtime/subscribe`) with `channel.proxy.subscribe.http.static_headers` `{"X-Centrifugo-Secret": "<proxy_secret>"}`, and `channel.namespaces[]` entries `collection` and `wishlist` with `subscribe_proxy_enabled: true`. Env override form: `CENTRIFUGO_<OPTION>` with nested levels joined by `_` (e.g. `CENTRIFUGO_CLIENT_ALLOWED_ORIGINS`). The Go subscribe proxy answers HTTP 200 for both allow and deny, and denies unless the namespace has an authorizer [VERIFIED: lighthouse/README.md:49-53]. Go registers authorizers for `collection` and `wishlist` only [VERIFIED: fonoteka/realtime.go]. The Nuxt client's auto-subscription to `user:{id}` (`useCentrifugo.ts:90`) is therefore denied on Go, **exactly as on PHP** (PHP `ProxyController` denies "Unknown channel namespace" the same way). This is parity, not a gap. "Realtime working" in the manual session means a `collection:{id}` update reaches a second browser session.
Nuxt side: `NUXT_PUBLIC_CENTRIFUGO_WS_URL=ws://localhost:<port>/connection/websocket` (the current shared instance serves WS and API on `:8787` [VERIFIED: `ss -ltnp` and `curl /connection/websocket` → 400 with CORS headers]). Set `E2E_CENTRIFUGO=1` for the live realtime spec.
## Q8. Nuxt proxy prefixes vs Go routes
| Nuxt proxied prefix | Go serves? | Gap / action |
|---------------------|-----------|--------------|
| `/_user/api/**` | yes (`golem15.user`) | — |
| `/_fonoteka/api/**` | yes | — (+ marker route) |
| `/_feedback/api/**` | yes: `GET /{key}/config`, `POST /{key}/submit`, `PUT /me/hidden` | Widget only active if `NUXT_PUBLIC_FEEDBACK_WIDGET_KEY` is set; the Go key must exist in `golem15_feedback_settings`. Recommend exporting it empty for local Go runs. |
| `/plugins/golem15/feedback/**` | yes: `GET /plugins/golem15/feedback/assets/js/embed.js` | — |
| `/api/realtime/**` | yes: `GET /token`, `POST /subscribe` | — |
| `/storage/**` | **no** | G2: mount `attach.StaticHandlerPublic` at `/storage/app/uploads/public/{path...}` |
| `/_journal/api/**` | **no** | Not used by the app (no `journal` reference in `app/`). Journal is Phase 15 and not in `fonoteka.go`. No action; document that the proxy entry 404s on Go. |
Not proxied, but used by fonoteka-mcp: `/api/v1/fonoteka/*` (personal-token routes). For MCP, set `FONOTEKA_API_URL=http://localhost:8423` and `FONOTEKA_API_TOKEN=<inv_ secret>` (env names [VERIFIED: grep fonoteka-mcp/src]).
## Standard Stack
No new dependencies. Everything is stdlib or already in the module graph.
| Piece | Use | Source |
|-------|-----|--------|
| `bonfire.Command` | `dev:seed` command | framework [VERIFIED] |
| `lagoon.OpenFromApp` / `lagoon.Publish` | open DB in plugin commands (G1) | framework [VERIFIED: lagoon/connection.go:77-120] |
| `attach.OpenBucket` / `attach.Publish` / `attach.StaticHandlerPublic` | seed covers; `/storage` mount | framework [VERIFIED] |
| `lighthouse.WithoutBroadcasting[T]` | no broadcast jobs from the seed | framework [VERIFIED] |
| `image`, `image/png`, `image/color` | generated cover PNGs | Go stdlib |
| bash + curl + jq + python3 | `dev-stack.sh`, `check-phase14.2.sh` | host tools [VERIFIED present] |
| `@playwright/test` ^1.60.0 | e2e | already in `vue-fonoteka-app/package.json` [VERIFIED] |
| `node --test tests/contracts/*.test.mjs` | contract test for the runTinker switch (source-level) | existing `pnpm test:contracts` [VERIFIED] |
**Installation:** none.
## Package Legitimacy Audit
Not applicable: this phase installs no external packages (Go stdlib and existing modules; existing npm devDependencies only).
**Packages removed due to [SLOP] verdict:** none
**Packages flagged as suspicious [SUS]:** none
## Architecture Patterns
### System Architecture Diagram
```
developer shell
│ scripts/dev-stack.sh up (sources .env.dev, SUMMER_ENV=local)
▼
[1 preflight services] ── pg (DSN) ── Typesense :8181/health ── Centrifugo (websockets:health)
│ any missing → exit 1 naming it
▼
[2 build] go build summer CLI → summer build → bin/fonoteka
▼
[3 data] bin/fonoteka migrate → bin/fonoteka dev:seed (env-gated, idempotent)
→ writes users / collections / albums / wishlist / user_api_tokens / settings
→ covers → storage/app/uploads/public/<partition>/<disk>
→ bin/fonoteka fonoteka:reindex → Typesense
▼
[4 serve] bin/fonoteka serve --addr 127.0.0.1:8423 (access log on) ──tee──▶ tmp/dev-stack/go.log
▼
[5 guard] marker GET :8423/_fonoteka/api/v1/_dev/backend
refuse: origin :8422 | non-loopback | internal origin unset/different | X-Powered-By: PHP | marker≠summercms
▼
[6 nuxt] NUXT_DEV_BACKEND_ORIGIN=NUXT_INTERNAL_API_ORIGIN=http://127.0.0.1:8423
NUXT_PUBLIC_CENTRIFUGO_WS_URL=ws://… pnpm dev --port 3119 ──tee──▶ tmp/dev-stack/nuxt.log
▼
[7 post-start probe] GET :3119/_fonoteka/api/v1/_dev/backend (via Vite proxy) == marker JSON
browser ──▶ :3119 (Nuxt) ──proxy /_user /_fonoteka /_feedback /api/realtime /storage──▶ :8423 (Go) ──▶ Postgres / bucket / Typesense
│ SSR fetch (internalApiOrigin) ───────────────────────────▶ :8423
└──WS──▶ Centrifugo ──subscribe proxy (X-Centrifugo-Secret)──▶ :8423/api/realtime/subscribe
Go album writes ──River job──▶ Centrifugo HTTP API ──▶ browser (collection:{id})
```
### Recommended file layout
```
fonoteka.go/
├── scripts/dev-stack.sh # up | preflight | seed | down | status (new)
├── .env.dev.example # placeholders only (new); .env.dev gitignored
├── .gitignore # + .env.dev, /storage/app/uploads/public/
├── RUNNING-LOCALLY.md (or README §) # run docs, Centrifugo snippet, MCP pointing
└── plugins/golem15/fonoteka/
├── console/dev_seed.go # DevSeedCommand (+ _test.go in last plan)
├── console/reindex.go # opens DB itself (G1)
├── dev_marker.go # env-gated marker route (or inside routes.go)
└── plugin.go # Commands() += DevSeedCommand
summercms.go/
├── modules/surf/… # opt-in access log; opt-in uploads mount (README + docs)
└── scripts/check-phase14.2.sh
vue-fonoteka-app/tests/e2e/
├── helpers/runTinker.ts # E2E_BACKEND=go switch
├── auth.setup.ts # if E2E_BACKEND=go → seedE2EFixtures() (no-op otherwise)
├── realtime.spec.ts # rewritten, backend-agnostic
├── album-edit-rate-cover.spec.ts # new
├── album-search.spec.ts # new
└── wishlist.spec.ts # new
```
### Pattern 1: `dev:seed` command (env refusal, idempotency, own DB)
**What:** a `bonfire.Command` that (a) refuses unless `Environment()` ∈ {`local`,`dev`}, (b) opens and publishes the DB and bucket itself, and (c) upserts by natural keys inside one `lagoon.Transaction`, with album writes in `WithoutBroadcasting`.
Idempotency keys:
- user by `email` (on the second run, if the bcrypt check of `E2E_PASSWORD` fails, print an explicit message and update; same inputs mean no change);
- collection and wishlist by `ProvisionCollection`/`ProvisionWishlist` (both reuse existing ones);
- albums by `(collection_id, name)` among live rows;
- cover only when the album has no `photos`;
- wishlist entry by `(wishlist collection_id, name)`;
- token: when `DEV_SEED_API_TOKEN` is set (must start with the configured prefix), upsert the row by `HashAPIToken(secret)`. Otherwise mint once under the fixed name `dev-seed-mcp`, print the secret only at creation, and on later runs print "token exists, secret not shown";
- `search_use_typesense`: `UPDATE … SET search_use_typesense = true WHERE id = 1 AND NOT search_use_typesense`, done last.
Print a summary line per entity (`created`/`unchanged`) so the idempotency test can assert on output as well as rows.
### Pattern 2: `/storage` mount (G2)
Register `GET /storage/app/uploads/public/{path...}` (better: the configured `storage.uploads.public_path_prefix` + `/{path...}`) in a raw group. The handler resolves `*blob.Bucket` and `*gorm.DB` via `app.Lookup` **per request** (the boot order precedent in `plugin.go:177-187`; `route:list` builds the router without a DB) and delegates to `attach.StaticHandlerPublic(bucket, prefix, gdb)`. Add `X-Content-Type-Options: nosniff`, because uploads are served same-origin with the app (see the static.go:24-25 warning). Two placements are possible: framework (opt-in config, reused by Phase 20) or fonoteka plugin. See Open Question 2.
### Pattern 3: dev-only marker route
Registered in the fonoteka plugin's `Routes()` only if `p.app.Config.Environment() != "production"`. It returns the fixed JSON in Q5. Unit test: present under `local`, absent (404 from the assembled router) under `production`, and absent from `parity/manifest.yaml`.
### Pattern 4: fail-closed guard as a standalone subcommand
`dev-stack.sh preflight` runs every guard check without starting anything and exits non-zero with a `refuse: …` line. `up` calls it before `pnpm dev`. That lets `check-phase14.2.sh --guard` test it directly:
- `NUXT_DEV_BACKEND_ORIGIN=http://127.0.0.1:8422` → refuse (port rule; no network needed);
- `NUXT_INTERNAL_API_ORIGIN` unset → refuse;
- origin `https://plytarium.com` → refuse (non-loopback);
- a fake PHP on a random port (`python3 -c` http.server that answers with `X-Powered-By: PHP/8.5.10` and 404) → refuse;
- the real Go on `:8423` → pass.
### Pattern 5: process supervision in `dev-stack.sh`
Run `serve` and `pnpm dev` in the background with `… > >(sed 's/^/[go] /' | tee -a "$LOG/go.log") 2>&1 &`, record PIDs in `tmp/dev-stack/pids`, and `trap 'kill $(jobs -p)' EXIT INT TERM`. Wait for readiness by polling the marker (Go) and `http://localhost:3119/` (Nuxt) with a timeout. `tmp/` is already gitignored in `fonoteka.go` [VERIFIED: .gitignore `/tmp/`]. Provide `down` to kill recorded PIDs.
### Pattern 6: `runTinker` switch (D-14)
```ts
// tests/e2e/helpers/runTinker.ts — additions only; PHP path untouched
const GO = process.env.E2E_BACKEND === 'go'
function goCwd() { return process.env.E2E_GO_DIR || path.resolve(path.dirname(process.env.E2E_GO_BIN!), '..') }
export function backendAvailable(): boolean {
if (GO) return !!process.env.E2E_GO_BIN && existsSync(process.env.E2E_GO_BIN)
/* existing php artisan --version probe unchanged */
}
export function runTinker(phpScript: string): string {
if (GO) throw new Error('[runTinker] PHP tinker is not available with E2E_BACKEND=go; use seedE2EFixtures()')
/* unchanged */
}
export function seedE2EFixtures(): void {
if (GO) { // fail closed: throws on non-zero exit
execFileSync(process.env.E2E_GO_BIN!, ['dev:seed'], { cwd: goCwd(), env: { ...process.env }, stdio: 'inherit' })
return
}
/* unchanged PHP path */
}
```
Optionally call `seedE2EFixtures()` from `auth.setup.ts` only `if (process.env.E2E_BACKEND === 'go')`, so a Playwright run is self-sufficient on Go and unchanged on PHP.
### Anti-Patterns to Avoid
- **Probing a framework path Nuxt does not proxy** for the post-start check. It would prove nothing about the proxy.
- **Opening the DB with `lagoon.Open`/`OpenFromApp` but skipping `lagoon.Publish`.** The OnDatabase slug and credential hooks never register, and the seeded collections and albums get empty slugs.
- **Seeding albums through the HTTP handlers or with broadcasting on.** That queues River broadcast and wishlist-digest jobs from a CLI process.
- **Writing `vue-fonoteka-app/.env`** (forbidden by D-08), or relying on `tests/e2e/.env.local` values (they may point at `:8422`).
- **Treating a Playwright skip as a pass** (G7).
- **Using `~/go/bin/summer`** (stale, and not on PATH for scripts).
## Don't Hand-Roll
| Problem | Don't Build | Use Instead | Why |
|---------|-------------|-------------|-----|
| Serving uploads | custom file server / `http.FileServer` on the storage dir | `attach.StaticHandlerPublic` | Validated 4-segment keys, `..` rejection, `is_public` gate, thumb sibling handling (T-05-13) |
| Password hashing | direct bcrypt calls | `usercontrollers.RegisterUser` / `bouncer.HashPassword(cost, plain)` | Honors `golem15.user.password.bcrypt_cost` and the model rules |
| Token minting | random string + sha256 by hand | `userclasses.MintAPIToken` + `HashAPIToken` | Prefix validation, scope allow-list, stored hash format |
| Collection/wishlist creation | raw INSERTs (as the parity seed does) | `ProvisionCollection` / `ProvisionWishlist` | Context row, lock order, column defaults (`reservations_allowed`) |
| Album creation | raw INSERT into `golem15_fonoteka_albums` | `CreateAlbum` | Field fill rules, artists and styles pivots, completion stamp, slug hooks |
| Centrifugo health | curl `/api/info` by hand | `bin/fonoteka websockets:health` | Already reads the same config/env and exits 1 on failure |
| go test result parsing | grep for `PASS` | the `detect()` python block from check-phase14.2.1.sh | Catches skips, zero tests, races and missing named tests |
## Common Pitfalls
### Pitfall 1: Plugin command silently has no DB (G1)
**What goes wrong:** `dev:seed`/`fonoteka:reindex` exits 1 with `database is not configured`, even though unit tests pass (the tests pre-publish the DB).
**How to avoid:** open and publish inside the command. Add a unit test that runs the command on an app **without** a published DB but with `database.dsn` pointing at the testcontainer.
**Warning signs:** the error text above in the script output.
### Pitfall 2: Gate specs skip instead of fail (G7)
**What goes wrong:** with `E2E_BACKEND_URL` unset, `fonotekaReachable()` probes `:8422`. If PHP is down the backend specs skip, and if PHP is up they run against a Nuxt that may still target Go (a mismatch).
**How to avoid:** export `E2E_BACKEND_URL=http://127.0.0.1:8423`, and fail on `stats.skipped > 0` for gate files.
### Pitfall 3: Typesense silently bypassed (G8/G9)
**What goes wrong:** search works through the SQL fallback while the Typesense key or index is wrong.
**How to avoid:** `search_use_typesense=true` in the seed, reindex in the script, grep `go.log` for `album search engine failed` in `--e2e`.
### Pitfall 4: Centrifugo origin and proxy mismatch
**What goes wrong:** the WS handshake is rejected silently (the origin is not allowed, for example `127.0.0.1:3119` vs `localhost:3119`), or `collection:{id}` subscribes are denied because the shared Centrifugo proxies to PHP or has a different `X-Centrifugo-Secret`.
**How to avoid:** allow both origins. Make sure the HMAC secret, API key and proxy secret match `.env.dev`. Point the subscribe proxy at `:8423` (Open Question 1).
### Pitfall 5: cwd-relative config and bucket
**What goes wrong:** `bin/fonoteka` run from another directory finds no `config/` or writes covers under the wrong directory.
**How to avoid:** always `cd "$APP"` (script) or `cwd: E2E_GO_DIR` (Playwright helper).
### Pitfall 6: Nuxt binds a different port or host
**What goes wrong:** the nuxt.config comment notes that if 3119 is taken "the Nuxt listener silently falls back to another port (often :3000)" (nuxt.config.ts:47-50). Playwright `reuseExistingServer` then probes the wrong server.
**How to avoid:** the preflight refuses if `:3119` is already listening, and the post-start probe targets `:3119` explicitly.
### Pitfall 7: Submodule pointer drift swept into commits (G13)
**How to avoid:** stage explicit paths only. Never `git add -A` in `fonoteka.go`.
### Pitfall 8: Access log leaking secrets
**What goes wrong:** raw paths carry share tokens (`/_fonoteka/api/v1/public/{token}`, `/invitations/{token}`) and query strings may carry `?token=`.
**How to avoid:** log `r.Pattern` (Go 1.22+ ServeMux exposes the matched pattern) instead of the raw path for matched routes. For unmatched requests (404, which is exactly what D-12 wants to spot) log the raw path **without** the query string, and keep it behind an opt-in flag. Sunscreen does not scrub path segments.
## Code Examples
### Opening DB + bucket in a plugin command (pattern from serve/lagoon)
```go
// Source: summercms.go/modules/surf/serve.go:40-52 and lagoon/commands.go:230-240
sqlDB, gdb, err := lagoon.OpenFromApp(ctx, app)
if err != nil { return err }
defer sqlDB.Close()
if err := lagoon.Publish(app, sqlDB, gdb); err != nil { return err } // runs OnDatabase hooks (slugs)
bucket, err := attach.OpenBucket(ctx, app.Config)
if err != nil { return err }
defer bucket.Close()
if err := attach.Publish(app, bucket); err != nil { return err }
```
### Env refusal
```go
// Source: compass/config.go:193-199 (SUMMER_ENV, default "production")
switch strings.ToLower(strings.TrimSpace(app.Config.Environment())) {
case "local", "dev":
default:
return fmt.Errorf("dev:seed: refused in environment %q (set SUMMER_ENV=local)", app.Config.Environment())
}
```
### Albums without broadcasts
```go
// Source: lighthouse/suppress.go:19; classes/album_write_service.go:378
err := lighthouse.WithoutBroadcasting[models.Album](ctx, func(ctx context.Context) error {
return lagoon.Transaction(ctx, gdb, func(ctx context.Context, tx *gorm.DB) error {
a, err := classes.CreateAlbum(ctx, tx, colID, map[string]any{"name": "Kind of Blue", "year": 1959, "format": "LP"})
_ = a
return err
})
})
```
## State of the Art
| Old Approach | Current Approach | When Changed | Impact |
|--------------|------------------|--------------|--------|
| Realtime demo badge on `/` (`realtime-status`) | Dashboard composition; realtime is invisible plumbing (`useRealtimeSync`) | 2026-06-12 (6fcdb8e) | `realtime.spec.ts` must assert the WS connection or a cross-session update, not a badge |
| PHP tinker seeding helper | Go `dev:seed` behind `E2E_BACKEND=go` | this phase | PHP path unchanged |
| Centrifugo v5 flat keys (`token_hmac_secret_key`, `allowed_origins`, `api_key`) | v6 nested (`client.token.hmac_secret_key`, `client.allowed_origins`, `http_api.key`) | Centrifugo v6 | Docs and templates must use v6 keys; the local server is v6.5.1 |
## Assumptions Log
| # | Claim | Section | Risk if Wrong |
|---|-------|---------|---------------|
| A1 | The shared Centrifugo at `/etc/centrifugo/config.json` has its subscribe proxy pointed at PHP (`:8422`), with secrets that may differ from what Go will use | G12, Q7, OQ1 | Realtime subscribes are denied on Go. Medium impact: realtime is a manual-session item and a gate spec. |
| A2 | `php artisan serve` on the PHP checkout answers the marker path with a 404 (any body) | Q5 | Low: the X-Powered-By check and the `.backend=="summercms"` check each refuse independently |
| A3 | `localhost:3119` in the browser and Playwright reaches the Nuxt dev listener on both IPv4 and IPv6 | Q2 | Low: probes fail visibly |
| A4 | Setting `app.url` to `http://localhost:3119` locally is right (frontend links such as activation and CSV export URLs) | .env.dev keys | Low: affects emails/links only. The OAuth issuer for local MCP OAuth would be wrong, but MCP OAuth is out of scope locally (personal token only). |
| A5 | 3–5 seeded albums plus 1 wishlist album are enough for the i18n count, offline covers and the manual session | Pattern 1 | Low |
| A6 | Rewriting `realtime.spec.ts` is acceptable under D-11 ("new backend-agnostic spec" / test helper) | Q1 | Low. If not, add `realtime-live.spec.ts` and mark the stale one report-only. Confirm with the user. |
## Open Questions
1. **Which Centrifugo does the local Go stack use?**
- Known: one shared v6.5.1 instance on `:8787`, config unreadable by this agent. Its subscribe proxy endpoint is static, so it can serve PHP or Go, not both.
- Recommendation: `dev-stack.sh` starts a **dedicated** Centrifugo for Go (`/usr/local/bin/centrifugo -c tmp/dev-stack/centrifugo.json`, port e.g. `8788`). The config is generated from `.env.dev` values with the subscribe proxy at `:8423`, so PHP's realtime stays intact side by side (the spirit of D-07). This deviates slightly from D-05's "host services only checked, not started", so confirm with the user. Alternative: document editing the shared config (PHP realtime then breaks while Go is the target).
2. **Where does the `/storage` mount live: framework or app?**
- Recommendation: framework, opt-in. `surf` (or `attach`) mounts `StaticHandlerPublic` at `storage.uploads.public_path_prefix` when a new key such as `storage.uploads.serve: true` is set. Phase 20 (D-06 routes `/storage/app/uploads` to Go) and other apps reuse it. It needs README/docs updates. App-level in the fonoteka plugin is the smaller change if the user prefers.
3. **Access-log placement and key name.**
- Recommendation: `surf` middleware enabled by `http.access_log: true` (env `SUMMER_HTTP__ACCESS_LOG=true`), default off (no behavior change for other apps), logging `method`, `pattern`, `status`, `duration_ms` (+ raw path without query only on 404) through `slog.Default()` (sunscreen).
4. **Fix `user:token:*` (shared sm-user-plugin) for G1 now?**
- Recommendation: no. Record a todo. The seed mints its own token; changing a shared plugin is outside this phase's need.
## Environment Availability
| Dependency | Required By | Available | Version | Fallback |
|------------|------------|-----------|---------|----------|
| Postgres (host) | Go DB | ✓ `127.0.0.1:5432 - accepting connections` | (auth required; Go DB/DSN not inspected) | Docker PG containers on 55432/55433/55415 exist |
| Typesense | search, reindex | ✗ container `plytarium-typesense-instance` (typesense:26.0) **Exited**, binds 127.0.0.1:8181 | 26.0 | `docker start plytarium-typesense-instance` (no fallback per D-06) |
| Centrifugo | realtime | ✓ running (systemd, `*:8787`) | v6.5.1 | dedicated instance from the same binary (OQ1) |
| Go | build/test | ✓ | go1.27.0 | — |
| Docker | testcontainers in Go tests | ✓ | — | — |
| Node / pnpm | Nuxt, Playwright | ✓ | v22.23.2 (`.nvmrc` 22.22.0) / pnpm 11.3.0 | — |
| Playwright browsers | e2e | ✓ chromium 1169–1223 in `~/.cache/ms-playwright` | @playwright/test ^1.60.0 | — |
| python3, jq, curl | scripts | ✓ | — | — |
| `summer` CLI | `summer build` | ⚠ `~/go/bin/summer` (2026-10-05), not on PATH for scripts | — | build from `summercms.go/cmd/summer` in the script |
| PHP (side-by-side check, D-11) | verify app edits on PHP | ✓ PHP 8.5.10, `expose_php On`; `:8422` currently down | 8.5.10 | — |
**Missing dependencies with no fallback:** Typesense must be started (`docker start plytarium-typesense-instance`). Its API key must go into `.env.dev`.
**Missing dependencies with fallback:** `summer` on PATH (build from source).
## Validation Architecture
### Test Framework
| Property | Value |
|----------|-------|
| Framework | Go `testing` + testcontainers-go Postgres (existing harness, e.g. `console/phase14_commands_test.go`, `classes/postgres_test.go`); Playwright ^1.60 for e2e; `node --test` for Nuxt contracts |
| Config file | none for Go; `vue-fonoteka-app/playwright.config.ts`; `vitest.config.ts` (unit, not needed) |
| Quick run command | `go -C ../fonoteka.go test ./plugins/golem15/fonoteka/console/ -run 'TestDevSeed' -count=1` |
| Full suite command | `bash scripts/check-phase14.2.sh --all` (from `summercms.go`) |
### Phase Requirements → Test Map
| Req ID | Behavior | Test Type | Automated Command | File Exists? |
|--------|----------|-----------|-------------------|-------------|
| QA-05 | `dev:seed` refuses outside local/dev (unset SUMMER_ENV → production) | unit | `go -C ../fonoteka.go test ./plugins/golem15/fonoteka/console/ -run TestDevSeedRefusesProduction -count=1` | ❌ Wave 0 (last plan) |
| QA-05 | `dev:seed` idempotent: second run creates no rows (counts per table equal), prints `unchanged` | unit (testcontainers) | `… -run TestDevSeedIdempotent` | ❌ |
| QA-05 | created shape: activated user with E2E creds, context collection, ≥3 albums with one photo each (blob exists in mem/file bucket), wishlist album, `inv_` token row, `search_use_typesense=true` | unit | `… -run TestDevSeedShape` | ❌ |
| QA-05 | seed opens its own DB (no pre-published handle) | unit | `… -run TestDevSeedOpensDatabase` | ❌ |
| QA-05 | `fonoteka:reindex` opens its own DB (G1) | unit | `… -run TestReindexOpensDatabase` | ❌ |
| QA-05 | marker route 200 JSON in local, absent in production, not in manifest | unit | `go -C ../fonoteka.go test ./plugins/golem15/fonoteka/ -run TestDevMarkerRoute` | ❌ |
| QA-05 | `/storage/app/uploads/public/...` serves a public blob, 404s private/missing/traversal, sets nosniff | unit | `go test ./modules/surf/ -run TestUploadsMount` (or plugin path if app-level) | ❌ |
| QA-05 | access log off by default; on: logs pattern+status, never query string or tokens | unit | `go test ./modules/surf/ -run TestAccessLog` | ❌ |
| QA-05 | guard refuses `:8422`, unset internal origin, non-loopback, fake PHP | script | `bash scripts/check-phase14.2.sh --guard` | ❌ |
| QA-05 | runTinker switch: PHP path byte-unchanged when unset; Go path calls `dev:seed` | contract | `pnpm test:contracts` (new `tests/contracts/e2e-backend-switch.test.mjs`) | ❌ |
| QA-05 | core flows on Go (login, browse, search, edit, rate, cover, wishlist, realtime, i18n, public share) | e2e | `bash scripts/check-phase14.2.sh --e2e` | ❌ (new specs in plan 3) |
| QA-05 | signed-in manual session incl. realtime between two sessions | manual | UAT checklist (14.2-UAT.md) | manual-only: realtime across two real browsers and visual cover checks |
### Sampling Rate
- **Per task commit:** the quick `go test` for the touched package, plus `go vet` on the touched modules.
- **Per wave merge:** `bash scripts/check-phase14.2.sh --go` (+ `--docs` when framework modules changed).
- **Phase gate:** `bash scripts/check-phase14.2.sh --all` green (needs services up), then `/gsd-verify-work`.
### Wave 0 Gaps
- [ ] `fonoteka.go/plugins/golem15/fonoteka/console/dev_seed_test.go`: refusal, idempotency, shape, own-DB.
- [ ] `fonoteka.go/plugins/golem15/fonoteka/console/reindex` own-DB test.
- [ ] marker route test in the fonoteka plugin package.
- [ ] `summercms.go/modules/surf` tests for the access log and uploads mount (if framework-level).
- [ ] `vue-fonoteka-app/tests/contracts/e2e-backend-switch.test.mjs`.
- [ ] `summercms.go/scripts/check-phase14.2.sh`.
- Framework install: none.
## Security Domain
### Applicable ASVS Categories
| ASVS Category | Applies | Standard Control |
|---------------|---------|-----------------|
| V2 Authentication | yes (seeded credentials, token) | Credentials only from env (`E2E_*`, `DEV_SEED_API_TOKEN`); bcrypt via `RegisterUser`; the token stored as a sha256 hash (`HashAPIToken`); the seed refuses in production |
| V3 Session Management | no change | existing JWT cookie flow |
| V4 Access Control | yes | Marker route env-gated (absent in production); `/storage` uses the `is_public` gate (`StaticHandlerPublic`) |
| V5 Input Validation | yes | Upload paths validated by `parsePublicBlobPath` (`..`, empty segments, partition match) |
| V6 Cryptography | no hand-rolling | `crypto/rand` inside `MintAPIToken`; app key from `key:generate` |
| V7 Logging | yes | Access log through sunscreen. Log route patterns, not raw paths with tokens; no query strings. |
| V14 Configuration | yes | `.env.dev` gitignored, `.env.dev.example` placeholders only; Go binds `127.0.0.1:8423`, not all interfaces |
### Known Threat Patterns for this stack
| Pattern | STRIDE | Standard Mitigation |
|---------|--------|---------------------|
| Seed run against production DB | Tampering | `SUMMER_ENV` must be `local`/`dev`; the default env is `production`, so refusal is the default |
| Same-origin XSS via uploaded content served from `/storage` on the app origin | Elevation | `StaticHandlerPublic` + `X-Content-Type-Options: nosniff`; uploads are image-guarded at upload; the seed only writes PNG |
| Secrets in logs (tokens in paths, Bearer headers) | Information disclosure | sunscreen + pattern-based access logging; never log headers |
| Committing secrets (`.env.dev`, minted token) | Information disclosure | `.gitignore`; the token secret printed once to the terminal only; never written to the repo |
| Backend identity disclosure via marker | Information disclosure | Route registered only outside production |
| Dev server reachable from the LAN | Spoofing / exposure | `--addr 127.0.0.1:8423`; Centrifugo dedicated instance on loopback |
## Sources
### Primary (HIGH confidence, read or executed this session)
- `fonoteka.go`: `plugins/golem15/fonoteka/{plugin.go, routes.go, realtime.go, search.go, console/reindex.go, classes/{onboarding,collection_provisioner,wishlist_resolver,album_write_service,album_files,album_search}.go, models/{settings,album_rating}.go, updates/20_remaining.go}`, `plugins/golem15/user/{models/user.go, models/api_token.go, classes/api_tokens.go, console/api_tokens.go, controllers/registration.go}`, `config/*.yaml`, `README.md`, `main.go`, `.gitignore`, `parity/{manifest.yaml, routes.snapshot, parity_contract_test.go, fonoteka_seed_test.go}`.
- `summercms.go`: `modules/{surf/serve.go, surf/router.go, compass/config.go, compass/env.go, lagoon/connection.go, lagoon/commands.go, lagoon/attach/static.go, lagoon/attach/file.go, lighthouse/suppress.go, lighthouse/README.md, bonfire/command.go, conga/commands.go, sunscreen/README.md}`, `cmd/summer/main.go`, `scripts/check-phase14.2.1.sh`, `scripts/check-phase14.sh`.
- `vue-fonoteka-app`: `nuxt.config.ts`, `playwright.config.ts`, `.env.example`, `tests/e2e/*.ts`, `tests/e2e/helpers/*.ts`, `app/plugins/api.ts`, `app/composables/useCentrifugo.ts`, grep of `app/` for test IDs; `node_modules/.pnpm/c12@3.3.4…/dist/index.mjs`.
- Executed: freshly built `fonoteka` binary (`route:list`, `fonoteka:reindex`, `user:token:create`, `migrate:status`, `websockets:health`, `--help`); `docker ps -a`, `docker inspect`, `ss -ltnp`, `pg_isready`, `centrifugo version`, `php -i`.
### Secondary (MEDIUM)
- centrifugal.dev/docs/server/configuration and /docs/server/proxy (v6 key names; fetched via a summarizing tool, cross-checked against each other).
### Tertiary (LOW)
- None relied upon.
## Metadata
**Confidence breakdown:**
- Go gaps and APIs: HIGH. Read the source and reproduced G1/G2 against a fresh build.
- Nuxt/Playwright contract: HIGH. Read the config, specs and c12 source.
- Centrifugo integration: MEDIUM. v6 keys cited from the docs; the shared instance's config could not be read (A1).
- Plan shape: MEDIUM. Depends on OQ1/OQ2 answers.
**Suggested plan breakdown (for the plan-count checkpoint):**
1. **Go glue** (`fonoteka.go` + `summercms.go`): `dev:seed` (env-gated, idempotent, own DB/bucket, generated covers, token, search flag), the reindex own-DB fix, the dev-only marker route, the `/storage` uploads mount, the opt-in surf access log, module READMEs/docs. Smoke tests only.
2. **Stack script and docs** (`fonoteka.go`): `scripts/dev-stack.sh` (`preflight`/`up`/`down`/`status`, service checks naming the missing one, build from source, migrate → seed → reindex → serve → guard → `pnpm dev` with pinned env, labeled tee'd logs, post-start probe), `.env.dev.example`, `.gitignore`, run docs including the Centrifugo v6 snippet and MCP pointing.
3. **Nuxt specs and manual session** (`vue-fonoteka-app`): the `E2E_BACKEND=go` switch (+ optional `auth.setup` hook), the `realtime.spec.ts` rewrite, new `album-edit-rate-cover`, `album-search` and `wishlist` specs (self-seeding, backend-agnostic, verified on PHP as well), `.env.example` notes; then the checklist-driven manual session recorded as UAT evidence.
4. **Unit tests and gate** (last, per project rule): Go unit tests from the Validation map, the Nuxt contract test, `summercms.go/scripts/check-phase14.2.sh` (`--self-test`/`--go`/`--docs`/`--guard`/`--e2e`/`--all`).
**Research date:** 2026-10-07
**Valid until:** 2026-11-06 (stable internal code; re-check G1/G2 if framework commits land first)