includio-cms 0.22.0 → 0.24.0

package/API.md

@@ -1,4 +1,4 @@
-# includio-cms — Public API v0.22.0
+# includio-cms — Public API v0.24.0
 
 > Auto-generated by `scripts/generate-api-md.ts`. Do not edit by hand.
 

package/CHANGELOG.md

@@ -3,6 +3,48 @@
 All notable changes to includio-cms are documented here.
 Generated from `src/lib/updates/` — do not edit manually.
 
+## 0.24.0 — 2026-04-30
+
+Faza 11 — Performance Pass. Eliminacja N+1 w render path: `getImageStylesBatch` (jeden SELECT zamiast N×getImageStyle dla styles + srcset wariantów) + `_getRawEntries` z batchowanym `getEntryVersions` (jeden call zamiast per-entry). Sharp srcset pipeline odrefactorowany — Promise.all wokół per-style queries usunięty (jeden batch + sequential Sharp generation z try/catch dla missing entries). Background maintenance lock potwierdzony testami (concurrent invocation skipped). Bench infra: nowy projekt vitest `bench` + skrypt `pnpm bench` + 2 representative benchmarks (image styles + raw entries).
+
+### Added
+- `databaseAdapter.getImageStylesBatch(requests)` — nowa metoda adaptera. Zwraca `Map<key, ImageStyle>` keyed przez `imageStyleKey(mediaFileId, style)`. Implementacja `db-postgres`: jeden SELECT `WHERE mediaFileId IN (...)` + JS-side filter po (name, width, height, quality, aspectRatio) matching unique index. Skala impactu: 100 entries × 3 styles × 4 srcset = ~1200 queries → 1 query per media file (~30 queries dla 30 unique files). Bench `getImageStyles`: ~750 ops/s (1.3ms p75) dla 1 media × 3 styles × srcset; baseline N+1 (72 sequential): ~11 ops/s — **71× speedup**.
+- `_getRawEntries()` (`src/lib/core/server/entries/operations/get.ts`) zrefactorowany — zamiast per-entry `getEntryVersions({ entryIds: [entry.id] })` w `Promise.all(dbEntries.map(...))` (N+1) teraz jeden `getEntryVersions({ entryIds: dbEntries.map(e => e.id) })` + group by `entryId` w Map. Adapter API bez zmian (już obsługiwał array `entryIds`). Skala: 100 entries → 2 queries zamiast 101. Bench: 387 ops/s (~2.6ms) dla 100 entries; baseline N+1 (101 sequential): ~7.9 ops/s — **50× speedup**.
+- Sharp srcset variant generation: `Promise.all(widths.map(getImageStyle))` całkowicie wyeliminowany w `imageStyles.ts`. Nowy flow: zebrać wszystkie style requesty (base + srcset variants), jeden `getImageStylesBatch()` call, fallback do `createImageStyle()` per missing z try/catch. Konsekwencje: jeden Sharp timeout (30s, env `INCLUDIO_SHARP_TIMEOUT_MS`) nie zabija batch innych wariantów — zachowanie identyczne jak `Promise.allSettled`, ale bez Promise.all w pipeline.
+- `getImageStylesBatch(requests)` operations wrapper (`src/lib/core/server/media/styles/operations/getImageStyle.ts`): koordynuje DB lookup + Sharp generation. Krótkie ścieżki: empty requests → empty Map bez DB call; wszystkie hity → cache return bez `createImageStyle`. Failed Sharp → `console.warn` + omission, nie throw.
+- `imageStyleKey(mediaFileId, style)` — stabilna helper key z `$lib/types/adapters/db.js` (eksport public). Format: `${mediaFileId}|${name}|${width||0}|${height||0}|${quality||0}|${aspectRatio||0}` — matchuje unique index na `image_styles`.
+- Background maintenance — in-process lock (`state.running` na `globalThis`) potwierdzony test suitem: `runMaintenance` exported (`@internal`), test concurrent dwóch wywołań → drugie loguje `Skipping — previous run still active`, batch operations wywołane dokładnie 1×. Komment w pliku: dla cluster mode wrap w `pg_advisory_lock`.
+- `pnpm bench` — nowy skrypt + dedykowany vitest project `bench` (vite.config.ts). Include `src/**/*.bench.ts`. 2 nowe benchmarki: `imageStyles.bench.ts` (real `getImageStyles` z mocked adapter latency 1ms + synthetic N+1 vs batch comparison), `get.bench.ts` (real `_getRawEntries` 100 entries + comparison). Istniejący `resolveTypographyOrphans.bench.ts` teraz uruchamiany w tej samej komendzie.
+- Lazy adapter imports (OpenAI / Anthropic / Nodemailer) — verified no-op. Wszystkie 3 adaptery (`src/lib/{ai-claude,ai-openai,email-nodemailer}/index.ts`) już używają `await import()` + cached singleton w closure. Type imports (`import type`) nie ładują runtime code. Trigger: pierwszy call metody adaptera (np. `generateAltText`, `sendMail`).
+
+### Breaking
+- `DatabaseAdapter.getImageStylesBatch` — nowa **wymagana** metoda interfejsu (`src/lib/types/adapters/db.ts`). Custom adapters muszą zaimplementować. Sygnatura: `(requests: ImageStyleRequest[]) => Promise<Map<string, ImageStyle>>`. Reference impl: `src/lib/db-postgres/index.ts` (jeden SELECT z `inArray` po `mediaFileId` + JS filter). Helper key: `imageStyleKey(mediaFileId, style)` z `$lib/types/adapters/db.js`.
+
+### Notes
+
+Zero schema migration — używa istniejącej tabeli `image_styles` i unique indeksu. Hot path render: collection list z 100 entries × image fields powinien zobaczyć ~50-70× redukcję wall-time queries (mierzone via bench na mocked latency 1ms; real PG latency wyższa, więc bezwzględne win większe). Sharp generation pozostaje sekwencyjne dla missing styles per request — celowo, żeby nie obciążać CPU; background maintenance batch (`batchGenerateAllStyles`) prewarmuje DB. `runMaintenance` eksportowany jako `@internal` dla testów — nie zaliczany do public API surface.
+
+## 0.23.0 — 2026-04-30
+
+Faza 10 — Documentation Pass. DOCS.md uzupełniony (REST cURL + error codes, Entries error handling + transaction patterns, Admin UI a11y guide, Adapter Contracts z interfaces + peer deps + lazy import, Shop retry-payment lifecycle, edge cases dla number/boolean/date/datetime). Nowe sekcje: Stability Promise (semver, @public/@experimental/@internal, deprecation timeline) i Security Model (CSRF, CSP, rate-limit, API keys, link do KNOWN-RISKS.md). Migration Guide rozszerzony o master cheatsheet 0.x → 1.0 (agregat 0.16-0.22). ROADMAP cleanup: pre-v1.0 historia → ROADMAP-ARCHIVE.md.
+
+### Added
+- `docs/stability-promise/` — nowa strona: SemVer 2.0, JSDoc tagi (@public semver-protected, @experimental opt-in to change, @internal poza kontraktem), deprecation timeline (1 minor cycle z @deprecated → remove w MAJOR), reference do `API.md` jako single source of truth public surface.
+- `docs/security/` — nowa strona: threat model in/out of scope, CSRF (Origin/Referer guard na `/admin/api/*`), CSP (`default-src self`, `unsafe-inline` na script/style + uzasadnienie TipTap/Paraglide), rate limiting (200/60s admin, 5/h forms, env override), API keys (opt-in `expiresAt`, audit `rotatedAt`, `generateApiKey()`), Sharp 30s timeout, link do `KNOWN-RISKS.md` (5 zaakceptowanych ryzyk).
+- `docs/migration/` — sekcja "Migrating from 0.x to 1.0 — master cheatsheet": global find-replace (getEntry → resolveEntry, language → locale), per-version blocks dla 0.16.0, 0.18.0, 0.19.0, 0.20.0, 0.21.0, 0.22.0 z migration steps + code examples, suggested upgrade path (pnpm + check + db:push + test).
+- `docs/adapters/` — sekcja "Adapter contracts": tabela 4 interfaces (DatabaseAdapter 38 metod, FilesAdapter 5+3 optional, EmailAdapter 1+config, AIAdapter 1) z source paths, peer deps required vs optional, lazy import pattern (przykład `email-nodemailer`), error contracts, best practices (timeouts, retry, partial state).
+- `docs/api/` — REST cURL examples (GET/POST/PUT/DELETE, upload), tabela error responses (HTTP × `CmsError.code`: UNAUTHORIZED, ENTRY_NOT_FOUND, INVALID_DATA, MISSING_REQUIRED_PARAM, RATE_LIMITED, etc.), authentication (Bearer header), opt-in `expiresAt` w API keys. Remote Functions section zaktualizowana na `resolveEntry/resolveEntries/countEntries`.
+- `docs/entries/` — sekcja "Error handling" (CmsError instanceof + stable codes), sekcja "Transaction patterns" (last-write-wins versioning, custom Drizzle tx z `cms.db.driver`, plugin hooks vs partial failure). Querying przepisany na `resolveEntry/resolveEntries/countEntries` (status enum: published/draft/scheduled, archived = ops nie status).
+- `docs/admin-ui/` — sekcja "Accessibility": WCAG 2.1 AA targets per surface (color contrast, keyboard nav, focus management, skip-link, heading hierarchy, ARIA roles, reduced motion), pattern dla custom plugin panels.
+- `docs/shop/retry-payment/` — pełen lifecycle (5 kroków + ASCII diagram), server endpoint scaffold, headless SDK + `createOrderState`, error responses (400/401/404/409/429/502 z `CmsError.code`), constraints (same totals, token-gated, rate-limited, idempotent gateway, no auto-retry), admin override.
+- `docs/fields/{number,boolean,date,datetime}/` — sekcje "Edge cases": number (NaN/Infinity rejection, floating-point precision, integer-only via step:1, parseFloat guards), boolean (null vs false, no string coercion, defaultValue vs runtime backfill), date (no timezone, ISO-8601 calendar string, null handling, edge years), datetime (UTC storage + local render, DST traps, ISO datetime validation).
+- `ROADMAP-ARCHIVE.md` (root) — pełna historia 0.0.69 → 0.16.0 wycięta z `ROADMAP.md`. `ROADMAP.md` zawiera od teraz wyłącznie v1.0+ (header + legenda + v1.0 + v1.x + Security + Backlog), z linkiem do archive.
+- `_config/nav.ts` + `scripts/compile-docs.ts` — zsynchronizowane: dodane "Stability Promise" w Guides, "Security Model" w "Authentication & Security" (renamed z "Authentication"). Brakujący "InPost Carrier" w nav.ts dodany dla parity z compile-docs.
+
+### Notes
+
+Brak code changes — only docs + ROADMAP cleanup. DOCS.md regeneruje się przez `pnpm docs:compile` (część `prepublishOnly`). Po publikacji pełen TOC widoczny w DOCS.md z 10 zaktualizowanymi/nowymi sekcjami. Dla user-facing changes — żadnych. Dla devów customizujących admin UI lub piszących adaptery — pełny stable contract w jednym miejscu.
+
 ## 0.22.0 — 2026-04-30
 
 Faza 9 — DX & config validation pass. `defineConfig()` waliduje config strict Zodem z czytelnymi błędami (path + hint), resolvery / operacje throwują typowane `CmsError` z `code` + `context`, CLI ma `--help` per subcommand i `--version`, README przepisany pod nowych userów (system requirements + 5-min quickstart), `.env.example` rozszerzony o wszystkie `INCLUDIO_*` envy, JSDoc na każdym `@public` symbolu (opis + `@param` + `@returns` + `@example`).