includio-cms 0.21.0 → 0.23.0

package/dist/updates/0.22.0/index.js

@@ -0,0 +1,75 @@
+export const update = {
+    version: '0.22.0',
+    date: '2026-04-30',
+    description: '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`).',
+    features: [
+        '`defineConfig()` (`includio-cms/sveltekit`) — runtime Zod validation z agregacją wszystkich błędów. Invalid config → `ConfigValidationError` (extends `CmsError`) z `issues[]` (path + message + hint), bullet-list message ready-to-paste do PR. `superRefine`: unique slugs (collections/singles/forms), default locale ≤ 1, relation targets w deklarowanych kolekcjach, `apiKeys[].permissions` referuje istniejące collection slugs.',
+        '`CmsError` + `ConfigValidationError` (`includio-cms` → `core/errors`) — bazowa klasa z `code` (SCREAMING_SNAKE_CASE), `context: Record<string, unknown>`, `cause?`. Stabilne kody: `ENTRY_NOT_FOUND`, `ENTRY_VERSION_NOT_FOUND`, `INVALID_DATA`, `MISSING_REQUIRED_PARAM`, `CONFIG_VALIDATION_FAILED`. `toString()` = `[CODE] message (k=v, k=v)`.',
+        '`formatZodDataIssues(error)` helper — render Zod errora z entry/form data jako lista `path: message`. Używany w `createEntryVersion`, `updateEntryVersion`, `createFormSubmission`.',
+        'CLI: `includio --help`, `includio scaffold admin --help`, `includio install-peers --help`, `includio create-user --help` — exit 0 + Usage/Options/Example block. `includio --version` / `-v` z `package.json`. Unknown command → exit 1 + top-level help.',
+        '`.env.example` rozszerzony — 11 envów z komentarzami i sekcjami (Required / Media & Uploads / Security & Rate Limits). Demo vars usunięte (były tylko dla `src/lib/demo/` skasowanego w Fazie 1).',
+        'README rebuild: TOC, sekcja **System requirements** (Node 18+, PG 14+, ffmpeg optional), 5-step **Quick start** (install → .env → config → scaffold → create-user → dev), poprawiony link do `DOCS.md`, dodana tabelka adapterów, sekcja CLI z subcommandami.',
+        'JSDoc bodies (opis + `@param` + `@returns` + `@example`) na każdym `@public` symbolu — `defineConfig`, `defineCollection`, `defineSingle`, `defineForm`, `defineObject`, `getCMS`, `resolveEntry`, `resolveEntries`, `countEntries`, `createFormSubmission`, `parseFormDataForSubmission`, `createConsentLog`, `resolveMediaWithStyles`, `createEntityAPI`, `createRestApiHandler`, `generateApiKey`, `getAuth`, `includioCMS`, `getPreviewEntry`, `cmsLayoutLoad`, factory adapterów (`pg`, `local`, `nodemailerAdapter`, `openAIAdapter`, `claudeAdapter`).'
+    ],
+    fixes: [
+        '`MISSING_REQUIRED_PARAM` zamiast `throw new Error(\'... is required\')` w `resolveEntry` / `resolveEntries` / `countEntries`. Context zawiera `op` + `missing`.',
+        '`INVALID_DATA` zamiast `throw Error(\'Invalid data: \' + JSON.stringify(parsedData.error.flatten()))` w `createEntryVersion` / `updateEntryVersion` / `createFormSubmission`. Context zawiera `collection`/`entryId`/`lang` (entries) lub `formSlug` (forms). Body errora to czytelna lista `field.path: message`.',
+        '`ENTRY_NOT_FOUND` z `{ collection, id }` w `_getDbEntryOrThrow` / `_getRawEntryOrThrow`; `ENTRY_VERSION_NOT_FOUND` z `{ versionId, entryId, lang }` w `_getDbEntryVersionOrThrow`.'
+    ],
+    breakingChanges: [
+        '**Strict config validation w `defineConfig`** — invalid configs które wcześniej "działały" w runtime (np. duplicate slug, brak default locale, relation do nieistniejącej kolekcji, brak metody w adapterze) **teraz throwują `ConfigValidationError` na starcie**. Najczęstsze przypadki + fix:\n  - **Duplicate slug**: dwie kolekcje/singles/forms z tym samym `slug` → unique slug per kategoria.\n  - **Invalid language code**: `code: \'ENGLISH\'` → `code: \'en\'` (ISO-639-1, opcjonalnie z regionem `\'pl-PL\'`).\n  - **Multiple default locales**: dwa `{ default: true }` → tylko jeden.\n  - **Missing adapter method**: stub adaptera bez `getEntries` etc. → zaimportuj pełen `pg()` / `local()` lub doimplementuj brakujące metody.\n  - **Invalid relation target**: `{ type: \'relation\', collection: \'authors\' }` przy braku kolekcji `authors` → dodaj kolekcję lub popraw target.',
+        '**Resolver / operation error format** — błędy z `resolveEntry` / `resolveEntries` / `countEntries` / `createEntryVersion` / `updateEntryVersion` / `createFormSubmission` rzucają teraz `CmsError` (extends `Error`). `error.message` zachowuje stary opis (przy `toString()` poprzedzony `[CODE]`) — string-matching `error.message === \'Entry not found\'` może się rozjechać. **Migracja:**\n  ```ts\n  import { CmsError } from \'includio-cms\';\n\n  try { await resolveEntry({ id }); }\n  catch (e) {\n    if (e instanceof CmsError && e.code === \'ENTRY_NOT_FOUND\') { ... }\n  }\n  ```',
+        '**`.env.example` reformatted** — `DEMO_USER_EMAIL`, `DEMO_USER_PASSWORD`, `DEMO_RESET_KEY` usunięte (były tylko dla wewnętrznego demo skasowanego w Fazie 1). Jeśli polegałeś na nich → trzymaj w lokalnym `.env`, nie w `.env.example`.'
+    ],
+    notes: `## Czytelność błędów config
+
+Po update — invalid config wyrzuci na starcie:
+
+\`\`\`
+ConfigValidationError: CMSConfig validation failed (2 issues):
+  - languages[0]: must be a 2-letter ISO code (e.g. 'en' or 'pl-PL')
+  - collections[1].slug: duplicate collection slug 'posts' — Hint: each collection/single/form must have a unique \`slug\`
+\`\`\`
+
+Każdy issue ma \`path\` (JS-notation: \`collections[1].slug\`, \`apiKeys[0].permissions[2]\`) i \`message\`. Tam gdzie da się rozsądnie zgadnąć, dochodzi \`Hint:\` z fix-suggestion.
+
+## Pattern: branchowanie po error code
+
+Stary kod string-matchujący po \`error.message\` musi się przepisać:
+
+\`\`\`ts
+// PRZED
+catch (e) {
+  if ((e as Error).message === 'Entry not found') { /* 404 */ }
+}
+
+// PO
+import { CmsError } from 'includio-cms';
+catch (e) {
+  if (e instanceof CmsError && e.code === 'ENTRY_NOT_FOUND') { /* 404 */ }
+}
+\`\`\`
+
+Dostępne kody w v0.22.0: \`ENTRY_NOT_FOUND\`, \`ENTRY_VERSION_NOT_FOUND\`, \`INVALID_DATA\`, \`MISSING_REQUIRED_PARAM\`, \`CONFIG_VALIDATION_FAILED\`.
+
+## Nowe envy (opt-in)
+
+Skopiuj \`node_modules/includio-cms/.env.example\` do swojego \`.env\` — domyślne wartości działają OOTB:
+
+- \`INCLUDIO_SHARP_TIMEOUT_MS\` (default 30000)
+- \`INCLUDIO_RATE_LIMIT_MAX\` / \`INCLUDIO_RATE_LIMIT_WINDOW_MS\` (default 200/60000)
+- \`INCLUDIO_FORM_RATE_LIMIT_MAX\` / \`INCLUDIO_FORM_RATE_LIMIT_WINDOW_MS\` (default 5/3600000)
+- \`INCLUDIO_CSRF_ALLOWED_ORIGINS\` (default: same-origin only)
+
+## CLI helpy
+
+\`\`\`bash
+includio --help
+includio scaffold admin --help
+includio install-peers --help
+includio create-user --help
+includio --version
+\`\`\`
+
+Brak SQL migration.`
+};

package/dist/updates/0.23.0/index.d.ts

@@ -0,0 +1,2 @@
+import type { CmsUpdate } from '../index.js';
+export declare const update: CmsUpdate;

package/dist/updates/0.23.0/index.js

@@ -0,0 +1,21 @@
+export const update = {
+    version: '0.23.0',
+    date: '2026-04-30',
+    description: '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.',
+    features: [
+        '`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.'
+    ],
+    fixes: [],
+    breakingChanges: [],
+    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.'
+};

package/dist/updates/index.js

@@ -55,7 +55,9 @@ import { update as update0180 } from './0.18.0/index.js';
 import { update as update0190 } from './0.19.0/index.js';
 import { update as update0200 } from './0.20.0/index.js';
 import { update as update0210 } from './0.21.0/index.js';
-export const updates = [update0065, update0066, update0067, update0068, update0069, update010, update011, update012, update013, update014, update015, update020, update022, update050, update051, update052, update053, update054, update055, update056, update057, update058, update060, update061, update062, update070, update071, update072, update073, update080, update090, update0100, update0110, update0120, update0130, update0131, update0132, update0133, update0134, update0140, update0141, update0142, update0143, update0144, update0145, update0146, update0150, update0151, update0152, update0153, update0154, update0155, update0160, update0180, update0190, update0200, update0210];
+import { update as update0220 } from './0.22.0/index.js';
+import { update as update0230 } from './0.23.0/index.js';
+export const updates = [update0065, update0066, update0067, update0068, update0069, update010, update011, update012, update013, update014, update015, update020, update022, update050, update051, update052, update053, update054, update055, update056, update057, update058, update060, update061, update062, update070, update071, update072, update073, update080, update090, update0100, update0110, update0120, update0130, update0131, update0132, update0133, update0134, update0140, update0141, update0142, update0143, update0144, update0145, update0146, update0150, update0151, update0152, update0153, update0154, update0155, update0160, update0180, update0190, update0200, update0210, update0220, update0230];
 export const getUpdatesFrom = (fromVersion) => {
     const fromParts = fromVersion.split('.').map(Number);
     return updates.filter((update) => {

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "includio-cms",
-	"version": "0.21.0",
+	"version": "0.23.0",
 	"scripts": {
 		"dev": "vite dev",
 		"build": "vite build && npm run prepack",
@@ -24,6 +24,9 @@
 		"db:test:up": "docker compose --profile test up -d db_test",
 		"db:test:down": "docker compose --profile test down db_test",
 		"db:test:migrate": "DATABASE_URL=postgres://root:mysecretpassword@localhost:5434/test drizzle-kit push --force",
+		"db:e2e:up": "docker compose --profile test up -d db_test_e2e",
+		"db:e2e:down": "docker compose --profile test down db_test_e2e",
+		"db:e2e:migrate": "DATABASE_URL=postgres://root:mysecretpassword@localhost:5435/test_e2e drizzle-kit push --force",
 		"storybook": "storybook dev -p 6006",
 		"build-storybook": "storybook build",
 		"create:user": "tsx cli/addUser/index.ts",

package/dist/paraglide/messages/en.d.ts

@@ -1,5 +0,0 @@
-export const hello_world: (inputs: {
-    name: NonNullable<unknown>;
-}) => string;
-export const login_hello: (inputs: {}) => string;
-export const login_please_login: (inputs: {}) => string;

package/dist/paraglide/messages/en.js

@@ -1,14 +0,0 @@
-/* eslint-disable */
-
-
-export const hello_world = /** @type {(inputs: { name: NonNullable<unknown> }) => string} */ (i) => {
-	return `Hello, ${i.name} from en!`
-};
-
-export const login_hello = /** @type {(inputs: {}) => string} */ () => {
-	return `Welcome back`
-};
-
-export const login_please_login = /** @type {(inputs: {}) => string} */ () => {
-	return `Login to your account`
-};

package/dist/paraglide/messages/pl.d.ts

@@ -1,5 +0,0 @@
-export const hello_world: (inputs: {
-    name: NonNullable<unknown>;
-}) => string;
-export const login_hello: (inputs: {}) => string;
-export const login_please_login: (inputs: {}) => string;

package/dist/paraglide/messages/pl.js

@@ -1,14 +0,0 @@
-/* eslint-disable */
-
-
-export const hello_world = /** @type {(inputs: { name: NonNullable<unknown> }) => string} */ (i) => {
-	return `Hello, ${i.name} from pl!`
-};
-
-export const login_hello = /** @type {(inputs: {}) => string} */ () => {
-	return `Witaj ponownie`
-};
-
-export const login_please_login = /** @type {(inputs: {}) => string} */ () => {
-	return `Zaloguj się na swoje konto`
-};