diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md deleted file mode 100644 index 07cb11f..0000000 --- a/.github/copilot-instructions.md +++ /dev/null @@ -1,25 +0,0 @@ -# Copilot Instructions - -This workspace uses scoped instructions with YAML front matter in `.github/instructions/*.instructions.md`. -Keep this file minimal to avoid duplicate or conflicting guidance. - -## Quick Reference - -- **General workflow**: See `.github/instructions/general.instructions.md` -- **Frontend (Svelte)**: See `.github/instructions/frontend.instructions.md` -- **API Hooks (tibi-server)**: See `.github/instructions/api-hooks.instructions.md` -- **SSR/Caching**: See `.github/instructions/ssr.instructions.md` -- **Testing (Playwright)**: See `.github/instructions/testing.instructions.md` - -## Toolchain - -- See `.env` in root for project-specific environment variables -- See `Makefile` for starting up the development environment with Docker -- If development environment is running, access the website at: `https://${PROJECT_NAME}.code.testversion.online/` or ask the user for the correct URL -- You can also use Browser MCP, so ask user to connect if needed -- Esbuild is used, watching for changes in files to rebuild automatically -- To force a restart of the frontend build and dev-server run: `make docker-restart-frontend` -- Backend is tibi-server configured in `/api/` folder and also restarted if changes are detected in this folder -- To show last X lines of docker logs run: `make docker-logs-X` where X is the number of lines you want to see -- For a11y testing use the MCP a11y tools if available -- For testing run: `yarn test` (all), `yarn test:e2e`, `yarn test:api`, `yarn test:visual` diff --git a/.github/instructions/general.instructions.md b/.github/instructions/general.instructions.md deleted file mode 100644 index 02567d5..0000000 --- a/.github/instructions/general.instructions.md +++ /dev/null @@ -1,38 +0,0 @@ ---- -name: General -description: Workspace-wide guidance and workflows. -applyTo: "**/*" ---- - -# General - -## Code Style & Conventions - -- Look in the problems tab for any errors or warnings in the code -- Follow the existing code style and conventions used in the project -- Write clear and concise comments where necessary to explain complex logic -- Ensure code is modular and reusable where possible -- Avoid introducing new dependencies unless absolutely necessary, but ask the user if there is a specific library they want to use -- If you are unsure about any requirements or details, ask the user for clarification before proceeding -- Respect a11y and localization best practices if applicable, optimize for WCAG AA standards - -## Development Workflow - -- Default dev flow is Docker/Makefile: `make docker-up`, `make docker-start`, `make docker-logs`, `make docker-restart-frontend` (see Makefile). -- Local dev is secondary: `yarn dev` for watch, `yarn build` and `yarn build:server` for production builds (see package.json). -- Frontend code is automatically built by watcher and browser-sync; backend code is automatically built and reloaded by extension, so no manual restarts needed during development. -- Read `.env` for environment URLs and secrets. -- Keep `tibi-types/` read-only unless explicitly asked. -- `webserver/` is for staging/ops only; use BrowserSync/esbuild for day-to-day dev. - -## API Access - -- API access to collections uses the reverse proxy: `CODING_URL/api/` (e.g. `CODING_URL/api/content`). -- Auth via `Token` header with ADMIN_TOKEN from `api/config.yml.env`. - -## Testing - -- Write unit tests for new functionality and ensure existing tests pass. -- Playwright is configured for E2E, API, mobile, and visual regression tests. -- Run tests via `yarn test` (all), `yarn test:e2e`, `yarn test:api`, `yarn test:visual`. -- After code changes, run only affected spec files: `npx playwright test tests/e2e/filename.spec.ts`. diff --git a/.github/instructions/ssr.instructions.md b/.github/instructions/ssr.instructions.md deleted file mode 100644 index 4c5c853..0000000 --- a/.github/instructions/ssr.instructions.md +++ /dev/null @@ -1,12 +0,0 @@ ---- -name: SSR -description: Server-side rendering flow and caching. -applyTo: "api/hooks/ssr/**" ---- - -# SSR and Caching - -- SSR request flow: `api/hooks/ssr/get_read.js` calls `api/hooks/lib/ssr-server.js` and injects `window.__SSR_CACHE__` used by `api/hooks/lib/ssr.js` on the client. -- SSR cache HTML is stored in the `ssr` collection. -- SSR builds output to `api/hooks/lib/app.server.js` via `yarn build:server`. -- SSR route validation is currently disabled and returns -1 in `api/hooks/config.js`; update this when enabling SSR per route. diff --git a/.github/instructions/testing.instructions.md b/.github/instructions/testing.instructions.md deleted file mode 100644 index 95348f0..0000000 --- a/.github/instructions/testing.instructions.md +++ /dev/null @@ -1,41 +0,0 @@ ---- -name: Testing -description: Playwright test conventions, fixtures, and visual regression. -applyTo: "tests/**" ---- - -# Testing - -- Playwright for API tests (`tests/api/`), E2E tests (`tests/e2e/`), mobile tests (`tests/e2e-mobile/`), and Visual Regression tests (`tests/e2e-visual/`). Config in `playwright.config.ts`. -- Self-test after code changes: run only affected spec files (`npx playwright test tests/e2e/filename.spec.ts` or `-g "test name"`), not a full test suite run – saves time. -- Always coordinate test adjustments with the user: do not fix broken tests to match buggy frontend or vice versa. When tests fail, first clarify whether the test or the code is wrong. - -## BrowserSync Workaround - -BrowserSync keeps a WebSocket open permanently, preventing `networkidle` and `load` from resolving. All fixture files override `page.goto()` and `page.reload()` to use `waitUntil: "domcontentloaded"` by default. Always use `domcontentloaded` for navigation waits. - -## Fixtures & Helpers - -- `tests/e2e/fixtures.ts` – Shared fixtures (`authedPage`, `testUser`) and helpers (`waitForSpaReady`, `navigateToRoute`, `clickSpaLink`). -- `tests/e2e-visual/fixtures.ts` – Visual test helpers (`waitForVisualReady`, `hideDynamicContent`, `prepareForScreenshot`, `expectScreenshot`, `getDynamicMasks`). -- `tests/e2e-mobile/fixtures.ts` – Mobile helpers (`openHamburgerMenu`, `isMobileViewport`, `isTabletViewport`, `isBelowLg`). -- `tests/api/fixtures.ts` – API fixtures (`api`, `authedApi`, `accessToken`). -- `tests/api/helpers/` – API test utilities (`test-user.ts`, `admin-api.ts`, `maildev.ts`). -- `tests/fixtures/test-constants.ts` – Central constants (`TEST_USER`, `ADMIN_TOKEN`, `API_BASE`). - -## Visual Regression Tests - -- Visual regression tests live in `tests/e2e-visual/` with separate Playwright projects (`visual-desktop`, `visual-iphonese`, `visual-ipad`). -- Run: `yarn test:visual`. Update baselines: `yarn test:visual:update`. -- Screenshots are stored in `tests/e2e-visual/__screenshots__/{projectName}/` and MUST be committed to the repo. -- Tolerance: `maxDiffPixelRatio: 0.02` (2%) for cross-OS/hardware rendering differences. -- Always call `prepareForScreenshot(page)` before `expectScreenshot()`. -- Use `waitForVisualReady(page)` instead of `waitForSpaReady()` – it additionally waits for skeleton loaders and CSS settling. -- Dynamic content: `hideDynamicContent(page)` disables BrowserSync overlay and animations; `getDynamicMasks(page)` returns locators for non-deterministic elements. -- For AI review of screenshots, run `./scripts/export-visual-screenshots.sh`. - -## API Tests - -- API tests use `tests/api/fixtures.ts` with `api` (unauthenticated) and `authedApi` (with Bearer token) fixtures. -- Helpers: `ensureTestUser()` (`tests/api/helpers/test-user.ts`), Admin API (`tests/api/helpers/admin-api.ts`), MailDev (`tests/api/helpers/maildev.ts`). -- After hook changes, run only affected API tests: `npx playwright test tests/api/filename.spec.ts`. diff --git a/.github/migration/README.md b/.github/migration/README.md deleted file mode 100644 index e7bae27..0000000 --- a/.github/migration/README.md +++ /dev/null @@ -1,48 +0,0 @@ -# Migration: PhyProof-Patterns → Starter-Template - -> Übernahme generischer Patterns aus `wm-phytolab/phyproof-shop-tibi-2025` in `cms/tibi-svelte-starter`. - -**Erstellt:** 2026-02-25 -**Quelle:** `/WM_Dev/src/gitbase.de/wm-phytolab/phyproof-shop-tibi-2025` - ---- - -## Pakete & Reihenfolge - -| # | Paket | Status | Abhängig von | Dateien | -|---|-------|--------|-------------|---------| -| 1 | [Foundation](paket-1-foundation.md) | ✅ | — | requestsStore, serverBuildInfo, formContext, clickOutside, utils, store, types | -| 2 | [Build-System](paket-2-build-system.md) | ✅ | Paket 1 | writeBuildInfo, esbuild-wrapper, ES-targets, Sentry tunnel, SPA-rewrites, versionCheck | -| 3 | [Toast + Loading](paket-3-toast-loading.md) | ⬜ | Paket 1 | toast.ts, ToastContainer, LoadingBar, Portal | -| 4 | [API-Layer](paket-4-api-layer.md) | ⬜ | 1, 2, 3 | api.ts Rewrite (fetch, dedup, loading, version-check) | -| 5 | [SSR Caching](paket-5-ssr-caching.md) | ⬜ | — | ssr.yml, ssr-server.js, utils.js, clear_cache.js, get_read.js | -| 6 | [Widgets + Nav](paket-6-widgets-navigation.md) | ⬜ | 1, 3, 4 | Button, Form, Input, Select, SearchableSelect, MedialibImage, Pagination, Carousel, Tooltip, DebugFooterInfo, navigation.ts | - -**Hinweis:** Paket 5 (SSR) ist Backend-only und kann parallel zu den Frontend-Paketen umgesetzt werden. - ---- - -## Parallelisierung - -``` -Paket 1 (Foundation) ──→ Paket 2 (Build) ──→ Paket 4 (API) ──→ Paket 6 (Widgets) - └──→ Paket 3 (Toast) ──┘ - -Paket 5 (SSR) ────────── (unabhängig, jederzeit) ──────────────┘ -``` - ---- - -## Bewusst nicht übernommen - -| Feature | Grund | -|---------|-------| -| `auth.ts` | Zu komplex als Default — pro Projekt entscheiden | -| Pagebuilder | Block-Registry ist immer projektspezifisch | -| Video Tours | Nischig — als separates Tool | -| i18n-Erweiterungen | Sprachsetup-abhängig | -| `validators.ts` | Passwort-Stärke zu spezifisch | -| Shop-Widgets | Cart, Filter, Pricing usw. | -| `@tailwindcss/typography` | Dependency nur bei Bedarf | -| `navigationData.ts` | CMS-Navigation braucht Collection-Setup | -| `CookieConsent.svelte` | GA-ID hardcoded, GDPR-Setup projektspezifisch | diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..93344dc --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,57 @@ +# AGENTS.md + +Tibi CMS starter template — Svelte 5 SPA with esbuild, SSR via goja, and Playwright tests. + +## Project overview + +- **Frontend**: Svelte 5 SPA in `frontend/src/`, bundled with esbuild, styled with Tailwind CSS 4. +- **Backend**: tibi-server with API hooks in `api/hooks/`, collections in `api/collections/`. +- **SSR**: Server-side rendering via goja (Go JS runtime) in `api/hooks/ssr/`. +- **Tests**: Playwright for E2E, API, mobile, and visual regression tests in `tests/`. +- **Types**: Shared TypeScript types in `types/global.d.ts`. Keep `tibi-types/` read-only. + +## Setup commands + +- Install deps: `yarn install` +- Start dev (Docker): `make docker-up && make docker-start` +- Start dev (local): `yarn dev` +- Build frontend: `yarn build` +- Build SSR bundle: `yarn build:server` +- Validate types: `yarn validate` + +## Development workflow + +- Default dev flow is Docker/Makefile: `make docker-up`, `make docker-start`, `make docker-logs`, `make docker-restart-frontend`. +- Local dev is secondary: `yarn dev` for watch, `yarn build` and `yarn build:server` for production builds. +- Frontend code is automatically built by watcher and BrowserSync; backend hooks are automatically reloaded on change. +- Read `.env` for environment URLs and secrets. +- `webserver/` is for staging/ops only; use BrowserSync/esbuild for day-to-day dev. +- If development environment is running, access the website at: `https://${PROJECT_NAME}.code.testversion.online/`. +- To force a restart of the frontend build and dev-server: `make docker-restart-frontend`. +- To show last X lines of docker logs: `make docker-logs-X`. +- Esbuild watches for file changes and rebuilds automatically. +- For a11y testing use MCP a11y tools if available. +- For quick interactive browser testing, ask the user to connect Playwright MCP (preferred) or Browser MCP (only in non-autonomous/chat mode). + +## Testing + +- Run all tests: `yarn test` +- E2E tests: `yarn test:e2e` +- API tests: `yarn test:api` +- Visual regression: `yarn test:visual` +- After code changes, run only affected spec files: `npx playwright test tests/e2e/filename.spec.ts`. +- Write unit tests for new functionality and ensure existing tests pass. + +## API access + +- API access to collections uses the reverse proxy: `CODING_URL/api/` (e.g. `CODING_URL/api/content`). +- Auth via `Token` header with ADMIN_TOKEN from `api/config.yml.env`. + +## Code style + +- Follow the existing code style and conventions used in the project. +- Write clear and concise comments where necessary to explain complex logic. +- Ensure code is modular and reusable where possible. +- Avoid introducing new dependencies unless absolutely necessary. +- Respect a11y and localization best practices; optimize for WCAG AA standards. +- Check the problems tab for any errors or warnings in the code. diff --git a/.github/instructions/api-hooks.instructions.md b/api/hooks/AGENTS.md similarity index 62% rename from .github/instructions/api-hooks.instructions.md rename to api/hooks/AGENTS.md index bc2f14f..4158c61 100644 --- a/.github/instructions/api-hooks.instructions.md +++ b/api/hooks/AGENTS.md @@ -1,18 +1,16 @@ ---- -name: API Hooks -description: tibi-server hook conventions and typing. -applyTo: "api/hooks/**" ---- - # API Hooks (tibi-server) +Hook files run inside the tibi-server Go runtime (goja). + +## Conventions + - Wrap hook files in an IIFE: `;(function () { ... })()`. - Always return a HookResponse type or throw a HookException type. - Use inline type casting with `/** @type {TypeName} */ (value)` and typed collection entries from `types/global.d.ts`. - Avoid `@ts-ignore`; use proper casting instead. - Use `const` and `let` instead of `var`. The tibi-server runtime supports modern JS declarations. -## context.filter – Go object quirk +## context.filter — Go object quirk `context.filter` is not a regular JS object but a Go object. Even when empty, it is **truthy**. Always check with `Object.keys()`: @@ -27,7 +25,7 @@ const requestedFilter = : null ``` -**Never** use `context.filter || null` – it is always truthy and results in an empty filter object inside `$and`, which crashes the Go server. +**Never** use `context.filter || null` — it is always truthy and results in an empty filter object inside `$and`, which crashes the Go server. ## Single-item vs. list retrieval @@ -37,15 +35,13 @@ instead, only add authorization filters (e.g. `{ userId: userId }`). ## HookResponse fields for GET hooks -- `filter` – MongoDB filter (list retrieval only, or to restrict single-item retrieval) -- `selector` – MongoDB projection (`{ fieldName: 0 }` to exclude, `{ fieldName: 1 }` to include) -- `offset`, `limit`, `sort` – pagination/sorting -- `pipelineMod` – function to manipulate the aggregation pipeline +- `filter` — MongoDB filter (list retrieval only, or to restrict single-item retrieval) +- `selector` — MongoDB projection (`{ fieldName: 0 }` to exclude, `{ fieldName: 1 }` to include) +- `offset`, `limit`, `sort` — pagination/sorting +- `pipelineMod` — function to manipulate the aggregation pipeline -## API Tests (Playwright) +## Related tests - When creating or modifying collections/hooks: extend or create corresponding API tests in `tests/api/`. -- Test files live under `tests/api/` and use fixtures from `tests/api/fixtures.ts`. -- Helpers: `ensureTestUser()` (`tests/api/helpers/test-user.ts`), Admin API (`tests/api/helpers/admin-api.ts`), MailDev (`tests/api/helpers/maildev.ts`). -- After hook changes, run only the affected API tests: `npx playwright test tests/api/filename.spec.ts`. -- When tests fail, clarify whether the hook or the test needs adjustment – coordinate with the user. +- After hook changes, run only affected API tests: `npx playwright test tests/api/filename.spec.ts`. +- When tests fail, clarify whether the hook or the test needs adjustment — coordinate with the user. diff --git a/api/hooks/ssr/AGENTS.md b/api/hooks/ssr/AGENTS.md new file mode 100644 index 0000000..b0abbb9 --- /dev/null +++ b/api/hooks/ssr/AGENTS.md @@ -0,0 +1,24 @@ +# SSR and Caching + +Server-side rendering via goja (Go JS runtime) with HTML caching. + +## Request flow + +1. `get_read.js` receives the request and calls `lib/ssr-server.js`. +2. `ssr-server.js` renders the Svelte app via `lib/app.server.js` and injects `window.__SSR_CACHE__`. +3. On the client, `lib/ssr.js` hydrates using the injected cache data. +4. Rendered HTML is stored in the `ssr` collection with dependency tracking. + +## Build + +- SSR bundle is built via `yarn build:server` and outputs to `lib/app.server.js`. +- The build uses `--banner:js='// @ts-nocheck'` to suppress type errors in the generated bundle. + +## Cache invalidation + +- `clear_cache.js` hook invalidates SSR cache entries based on collection dependencies. +- When content changes, only SSR entries that depend on the changed collection/entry are cleared. + +## Route validation + +SSR route validation is currently disabled and returns -1 in `config.js`; update this when enabling SSR per route. diff --git a/.github/instructions/frontend.instructions.md b/frontend/AGENTS.md similarity index 50% rename from .github/instructions/frontend.instructions.md rename to frontend/AGENTS.md index fbf8212..679b1cf 100644 --- a/.github/instructions/frontend.instructions.md +++ b/frontend/AGENTS.md @@ -1,14 +1,19 @@ ---- -name: Frontend -description: Svelte SPA structure and conventions. -applyTo: "frontend/src/**" ---- - # Frontend -- SPA entry point is `frontend/src/index.ts`, main component is `frontend/src/App.svelte`. -- Component organization: `lib/` for utilities and stores, keep route components in a `routes/` folder when needed, `css/` for styles. -- Use PascalCase component names and export props at the top of the `