includio-cms 0.21.0 → 0.23.0

package/README.md

@@ -1,57 +1,149 @@
-# Includio CMS
+# includio-cms
 
-A headless CMS built for SvelteKit. Type-safe, extensible, with a modern admin interface.
+[![CI](https://github.com/includio/includio-cms/actions/workflows/ci.yml/badge.svg)](https://github.com/includio/includio-cms/actions/workflows/ci.yml)
+
+A headless CMS built for SvelteKit. Type-safe, extensible, with a modern admin interface and pluggable adapters for database, files, email, and AI.
+
+## Contents
+
+- [Features](#features)
+- [System requirements](#system-requirements)
+- [Quick start (5 minutes)](#quick-start-5-minutes)
+- [Configuration](#configuration)
+- [Adapters](#adapters)
+  - [Writing your own adapter](#writing-your-own-adapter)
+  - [Optional peer dependencies](#optional-peer-dependencies)
+- [CLI](#cli)
+- [Links](#links)
+- [For AI assistants](#for-ai-assistants)
+- [License](#license)
 
 ## Features
 
-- **19 field types** — text, structured content, media, relations, blocks, SEO, and more
+- **20 field types** — text, structured content, media, relations, blocks, SEO, URL, custom plugins, and more
 - **Structured content** — ProseMirror-based rich text with inline blocks, tables, media embeds
 - **Media management** — image styles (Sharp), video transcoding (ffmpeg), focal points, blur placeholders
-- **Per-language versioning** — independent draft/published/scheduled per language
+- **Per-language versioning** — independent draft / published / scheduled per language
 - **Layout DSL** — organize admin editor with sections, columns, cards, accordions
 - **Frontend components** — `<Image>`, `<Video>`, `<StructuredContent>`, `<Media>` for SvelteKit
 - **REST API** — API key auth, CRUD endpoints, schema introspection
 - **Entity API** — server-side programmatic CRUD for scripts, migrations, webhooks
 - **Code generation** — TypeScript types and Zod schemas from your content schema
-- **Pluggable adapters** — swap database, file storage, email, and AI providers
+- **Pluggable adapters** — swap database, file storage, email, AI provider
 - **Plugin system** — lifecycle hooks and custom field types
-- **Video transcoding** — auto-transcode to mp4/webm with background processing
+- **Strict config validation** — invalid configs throw a `ConfigValidationError` listing every issue with a path and a fix hint
+
+## System requirements
+
+- **Node.js** 18+ (20 LTS recommended)
+- **PostgreSQL** 14+ — required by the bundled `db-postgres` adapter; or write your own [`DatabaseAdapter`](#writing-your-own-adapter)
+- **ffmpeg + ffprobe** — optional, only required for video transcoding (set `FFMPEG_PATH` / `FFPROBE_PATH` if not on `PATH`)
+- A SvelteKit project (Kit ≥ 2.48, Svelte ≥ 5.43, Vite ≥ 7)
+
+## Quick start (5 minutes)
 
-## Quick Start
+The five steps below take you from `pnpm add` to a running admin at `/admin`.
+
+**1. Install:**
 
 ```bash
 pnpm add includio-cms
+pnpm dlx includio install-peers
+```
+
+**2. Configure environment:**
+
+```bash
+cp node_modules/includio-cms/.env.example .env
+# edit .env — set DATABASE_URL and BETTER_AUTH_SECRET
 ```
 
-```typescript
+Generate a secret:
+
+```bash
+openssl rand -hex 32
+```
+
+**3. Create `src/lib/cms/cms.config.ts`:**
+
+```ts
 import { defineConfig } from 'includio-cms/sveltekit';
 import { pg } from 'includio-cms/db-postgres';
 import { local } from 'includio-cms/files-local';
 
 export default defineConfig({
   languages: ['en'],
-  db: pg({ databaseUrl: process.env.DATABASE_URL }),
+  db: pg({ databaseUrl: process.env.DATABASE_URL! }),
   files: local(),
-  collections: [/* ... */],
+  auth: { secret: process.env.BETTER_AUTH_SECRET! },
+  collections: []
 });
 ```
 
-See the [full documentation](/docs) for installation, configuration, and usage.
+**4. Scaffold admin routes + create a user:**
 
-## Writing your own adapter
+```bash
+pnpm dlx includio scaffold admin
+pnpm dlx includio create-user
+```
 
-`includio-cms` ships with default adapters (`db-postgres`, `files-local`, `email-nodemailer`, `ai-openai`, `ai-claude`). Each is a factory returning an object that implements a `@public` contract from `includio-cms/types`. Build your own by implementing the same interface — TypeScript will enforce the surface.
+**5. Run the dev server:**
 
-Four adapter contracts:
+```bash
+pnpm dev
+```
 
-- `DatabaseAdapter` — entries, versions, media, tags, form submissions, consent logs.
-- `FilesAdapter` — file upload/download/list, optional private files (e.g. shop receipts).
-- `EmailAdapter` — `sendMail`, default from address/name.
-- `AIAdapter` — currently `generateAltText(fileId)`.
+Open `http://localhost:5173/admin` and sign in with the user you just created.
+
+> Need more? Full reference in [`DOCS.md`](./DOCS.md). API surface in [`API.md`](./API.md).
+
+## Configuration
+
+`defineConfig({ ... })` is your single source of truth. The shape (abridged):
+
+```ts
+defineConfig({
+  languages: ['en', 'pl'],   // first entry is the default locale
+  db, files,                 // required adapters
+  email, ai,                 // optional adapters
+  auth: { secret },          // required for /admin
+  collections: [postsCollection],
+  singles:     [siteSettings],
+  forms:       [contactForm],
+  apiKeys:     [{ key: '...', role: 'admin' }],
+  media:       { /* sharp / video / maintenance options */ },
+  typography:  { fixOrphans: true },
+  shop, cmp                  // optional modules
+});
+```
+
+Invalid configs throw immediately at startup with every issue listed:
+
+```
+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`
+```
+
+See [`DOCS.md`](./DOCS.md) for every field type and option.
+
+## Adapters
+
+`includio-cms` ships four pluggable contracts. Each has a default implementation; bring your own when you need to.
+
+| Contract           | Default                | Lazy peer dep                |
+|--------------------|------------------------|------------------------------|
+| `DatabaseAdapter`  | `includio-cms/db-postgres` | `postgres`, `drizzle-orm`     |
+| `FilesAdapter`     | `includio-cms/files-local` | —                            |
+| `EmailAdapter`     | `includio-cms/email-nodemailer` | `nodemailer`             |
+| `AIAdapter`        | `includio-cms/ai-openai`, `includio-cms/ai-claude` | `openai`, `@anthropic-ai/sdk` |
 
 Source of truth: [`src/lib/types/adapters/`](src/lib/types/adapters/).
 
-### Minimal custom DB adapter (sketch)
+### Writing your own adapter
+
+Each contract is a TypeScript interface — implement every required method (optionals are marked `?`). TypeScript will enforce the surface.
 
 ```ts
 import type { DatabaseAdapter } from 'includio-cms/types';
@@ -68,7 +160,7 @@ export function myDbAdapter(config: { connection: string }): DatabaseAdapter {
     createEntryVersion: async (data) => { /* ... */ },
     updateEntryVersion: async (data) => { /* ... */ },
     getEntryVersions: async (data) => { /* ... */ },
-    deleteEntryVersion: async (data) => { /* ... */ },
+    deleteEntryVersion: async (data) => { /* ... */ }
     // ...form submissions, media files, image/video styles, tags, consent logs...
   };
 }
@@ -90,25 +182,39 @@ Reference implementation: [`src/lib/db-postgres/index.ts`](src/lib/db-postgres/i
 
 ### Optional peer dependencies
 
-The default email + AI adapters depend on third-party SDKs that **are not installed by default**. If you use them, install the peer:
+The default email + AI adapters depend on third-party SDKs that **are not installed by default**. Install the peer once you use the adapter:
+
+| Adapter            | Required peer       | Install                       |
+|--------------------|---------------------|-------------------------------|
+| `email-nodemailer` | `nodemailer`        | `pnpm add nodemailer`         |
+| `ai-openai`        | `openai`            | `pnpm add openai`             |
+| `ai-claude`        | `@anthropic-ai/sdk` | `pnpm add @anthropic-ai/sdk`  |
+
+Each SDK is loaded lazily on first call. A missing peer throws a clear error at runtime — install it and the adapter wakes up. `pnpm dlx includio install-peers` automates this for the parts of the CMS you have configured.
+
+## CLI
+
+The `includio` binary ships with three subcommands. Run any of them with `--help` for details.
 
-| Adapter                   | Required peer            | Install                                |
-| ------------------------- | ------------------------ | -------------------------------------- |
-| `email-nodemailer`        | `nodemailer`             | `pnpm add nodemailer`                  |
-| `ai-openai`               | `openai`                 | `pnpm add openai`                      |
-| `ai-claude`               | `@anthropic-ai/sdk`      | `pnpm add @anthropic-ai/sdk`           |
+| Command                  | What it does                                              |
+|--------------------------|-----------------------------------------------------------|
+| `includio scaffold admin`| Generates `/admin` and `/api/admin` route files          |
+| `includio install-peers` | Installs missing optional peer SDKs based on your config |
+| `includio create-user`   | Creates an admin/user account interactively              |
 
-Each SDK is loaded lazily on first call. Missing peer throws a clear error at runtime — install it and the adapter wakes up.
+Global flags: `--help, -h` and `--version, -v`.
 
 ## Links
 
-- [Full Documentation](DOCS.md)
-- [Changelog](CHANGELOG.md)
-- [Roadmap](ROADMAP.md)
+- [Full documentation](./DOCS.md)
+- [Public API surface](./API.md)
+- [Changelog](./CHANGELOG.md)
+- [Roadmap](./ROADMAP.md)
+- [Known risks](./KNOWN-RISKS.md)
 
-## For AI Assistants
+## For AI assistants
 
-Full documentation is in [`DOCS.md`](DOCS.md) (shipped with the npm package). When working on a project using includio-cms, read `node_modules/includio-cms/DOCS.md` for the complete API reference, available components, and migration guides.
+Full documentation is in [`DOCS.md`](./DOCS.md) (shipped with the npm package). When working on a project using includio-cms, read `node_modules/includio-cms/DOCS.md` for the complete API reference, available components, and migration guides.
 
 ## License
 

package/ROADMAP.md

@@ -5,340 +5,18 @@
 > `[P0]` critical | `[P1]` important | `[P2]` nice-to-have
 > `<!-- files: path/to/file.ts -->` optionally linked files
 >
-> **Versioning:** 0.0.69 is the last `0.0.x` release. From 0.1.0 onward: `0.MINOR.0` = features/changes, `0.MINOR.PATCH` = fixes.
-
-## 0.0.69 _(last 0.0.x)_
-
-- [x] `[feature]` `[P1]` DnD reordering in array fields + arrayMove utility <!-- files: src/cms/fields/array-field -->
-- [x] `[fix]` `[P1]` Nav-search: batch-fetch data before rendering Command dialog <!-- files: src/cms/nav-search -->
-
-## 0.1.0 — Stabilization
-
-- [x] `[fix]` `[P0]` Collection table pagination — server-side, persistent page state, archived tab <!-- files: src/lib/admin/client/collection/collection-entries.svelte, src/lib/admin/client/collection/table-pagination.svelte -->
-- [x] `[fix]` `[P0]` Language switcher — reactive globally without reload, remove hardcoded en/pl <!-- files: src/lib/admin/state/interface-language.svelte.ts, src/lib/admin/components/layout/header-actions.svelte -->
-- [x] `[fix]` `[P0]` User account section — fix name input, aria-pressed on prefs, clean up 2FA stub (email change deferred to 0.1.2, avatar upload skipped) <!-- files: src/lib/admin/client/account/ -->
-- [x] `[fix]` `[P0]` Media tag counts always 0 — pass actual files to TagSidebar <!-- files: src/lib/admin/components/media/media-library.svelte, src/lib/admin/components/media/tag-sidebar.svelte -->
-- [x] `[fix]` `[P0]` Hybrid target — don't render `data-hybrid-path` for non-logged-in users <!-- files: src/lib/sveltekit/components/hybrid-target.svelte -->
-
-## 0.1.1 — Input integrity
-
-- [x] `[fix]` `[P1]` Input constraints UI — HTML maxlength, character counter, pattern feedback <!-- files: src/lib/admin/components/fields/text-field.svelte, src/lib/admin/components/fields/text-field-wrapper.svelte -->
-- [x] `[fix]` `[P1]` Array field maxItems — disable Add button when max reached <!-- files: src/lib/admin/components/fields/array-field.svelte -->
-- [x] `[feature]` `[P1]` Array field fixed length — fixed item count, no add/remove, reorder only
-- [x] `[feature]` `[P1]` Field constraint info display — show constraints before validation error (WCAG/ATAG) <!-- files: src/lib/admin/components/fields/text-field-wrapper.svelte, src/lib/admin/components/fields/field-renderer.svelte -->
-
-## 0.1.2 — User management & RBAC
-
-### Phase 1 — Core
-
-- [x] `[feature]` `[P0]` RBAC middleware — `requireRole()`, role check w `requireAuth()` <!-- files: src/lib/admin/remote/middleware/auth.ts -->
-- [x] `[feature]` `[P0]` Admin users page — list, search, pagination via `authClient.admin.listUsers` <!-- files: src/lib/admin/client/users/ -->
-- [x] `[feature]` `[P0]` Create user — dialog z email/password/name/role via `authClient.admin.createUser` <!-- files: src/lib/admin/client/users/create-user-dialog.svelte -->
-- [x] `[feature]` `[P0]` Edit user — name, email, role via `adminUpdateUser` + `setRole` <!-- files: src/lib/admin/client/users/edit-user-dialog.svelte -->
-- [x] `[feature]` `[P0]` Delete user — confirmation dialog via `removeUser` <!-- files: src/lib/admin/client/users/ -->
-- [x] `[feature]` `[P0]` Route/sidebar gating — ukryj Users nav + chroń `/admin/users` dla non-admin <!-- files: src/lib/admin/components/layout/nav-main.svelte, src/lib/sveltekit/server/handle.ts -->
-- [x] `[feature]` `[P0]` First user bootstrap — pierwszy utworzony user auto-gets role `admin` <!-- files: src/lib/server/auth.ts -->
-
-### Phase 2 — Extended
-
-- [x] `[feature]` `[P1]` Admin session mgmt — list/revoke sesji innych userów <!-- files: src/lib/admin/client/users/user-sessions-sheet.svelte -->
-- [x] `[feature]` `[P2]` Email invitation system — invite link generation (custom, nie w better-auth) <!-- files: src/lib/admin/remote/invite.ts -->
-
-## 0.1.3 — Admin DX
-
-- [x] `[feature]` `[P1]` Admin route scaffolding — CLI `includio scaffold admin`, catch-all API handler, page.params fallbacks for CollectionPage/EntryPage <!-- files: src/lib/cli/scaffold/admin.ts, src/lib/admin/api/handler.ts, src/lib/admin/client/collection/collection-page.svelte, src/lib/admin/client/entry/entry-page.svelte -->
-
-## 0.1.4 — Build & reactivity fixes
-
-- [x] `[fix]` `[P0]` Prepack: remove dist/paraglide/.gitignore before publint (publish validation) <!-- files: package.json -->
-- [x] `[fix]` `[P1]` Collection entries: {#key} wrapper on query blocks to force re-fetch on param change <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-
-## 0.2.1–0.5.0 — Hybrid Editor System
-
-> Szczegóły w **[ROADMAP-EDITOR.md](./ROADMAP-EDITOR.md)**
-
-- **0.2.1** — array→blocks rename + simple array `[breaking]`
-- **0.2.2** — Structured Content field (TipTap JSON output)
-- **0.3.0** — Bard-style inline blocks
-- **0.4.0** — Zone system (layout orchestration)
-- **0.4.1** — Accessibility layer (ATAG Part B)
-- **0.5.0** — Frontend rendering
-
-## 0.5.1 — Patches & dashboard
-
-- [x] `[feature]` `[P1]` Restore archived entries — banner, read-only mode, list actions
-- [x] `[feature]` `[P2]` Dashboard: changelog modal, orphaned entries redesign, grid layout
-- [x] `[fix]` `[P1]` Translation flow — reactive status, switcher UX, dynamic ref, copyFrom crash, panel scroll
-- [x] `[fix]` `[P1]` False "Niezapisane zmiany" on entry load
-- [x] `[fix]` `[P2]` Hide translation dots for non-required empty fields
-
-## 0.5.2 — Update system fix
-
-- [x] `[fix]` `[P1]` Split `migration` field into `sql` + `notes` — fixes CLI crash on text descriptions
-
-## 0.5.3 — Form fields, inline blocks, hybrid preview
-
-- [x] `[feature]` `[P1]` Form fields: select type, minLength/maxLength, errorMessage, remote commands
-- [x] `[feature]` `[P1]` Conditional field visibility (showWhen)
-- [x] `[feature]` `[P1]` Hybrid preview: device frames, container queries
-- [x] `[feature]` `[P2]` TipTap placeholder extension + Notion-style styles
-- [x] `[feature]` `[P1]` Server-side field resolution for inline blocks
-- [x] `[feature]` `[P1]` Inline blocks: standalone form, field rendering, collapse UI
-- [x] `[feature]` `[P2]` URL field: rel attribute, external auto-detect, UI redesign
-- [x] `[feature]` `[P2]` Switch UI component + boolean field toggle
-- [x] `[chore]` `[P2]` Storybook stories for all field types
-- [x] `[chore]` `[P1]` Field components refactor: bindable value props
-
-## 0.5.4 — Collection ordering & list columns
-
-- [x] `[feature]` `[P1]` Orderable collections: DnD reordering with keyboard alternative (WCAG 2.1) <!-- files: src/lib/admin/client/collection/data-table.svelte, src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[feature]` `[P1]` Custom list columns: display entry fields as columns in collection list <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[feature]` `[P1]` `sortOrder` column + `reorderEntriesCommand` remote <!-- files: src/lib/db-postgres/schema/entry.ts, src/lib/admin/remote/entry.remote.ts -->
-
-## 0.5.5 — REST API & orderable fixes
-
-- [x] `[feature]` `[P1]` REST API with API key authentication — CRUD for collections, singletons, entries, schema, languages <!-- files: src/lib/admin/api/rest/ -->
-- [x] `[feature]` `[P1]` API key configuration in CMS config (`apiKeys`) <!-- files: src/lib/types/cms.ts, src/lib/core/cms.ts -->
-- [x] `[feature]` `[P2]` getEntries `orderBy` parameter support <!-- files: src/lib/types/entries.ts, src/lib/core/server/entries/operations/get.ts -->
-- [x] `[fix]` `[P1]` Orderable collections: proper `<tr>` markup, visible reorder buttons, selection enabled <!-- files: src/lib/admin/client/collection/data-table.svelte -->
-- [x] `[fix]` `[P1]` Relation field respects orderable collection sort order <!-- files: src/lib/admin/components/fields/relation-field.svelte -->
-- [x] `[fix]` `[P1]` Nav active state exact match — prevents false highlights <!-- files: src/lib/admin/components/layout/nav-*.svelte -->
-- [x] `[chore]` `[P2]` Admin scaffold generates REST API route <!-- files: src/lib/cli/scaffold/admin.ts -->
-
-## 0.5.6 — Relation field & collection improvements
-
-- [x] `[feature]` `[P1]` Relation field: dialog picker, reorder, search, multi-select UX <!-- files: src/lib/admin/components/fields/relation-field.svelte -->
-- [x] `[feature]` `[P1]` getEntryLabels — lightweight labels endpoint for relation fields <!-- files: src/lib/admin/remote/entry.remote.ts -->
-- [x] `[feature]` `[P2]` Collection list: relation labels in columns, delete only for archived <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[feature]` `[P2]` Icon map — string-based sidebar icons replace component refs <!-- files: src/lib/admin/components/layout/nav-main.svelte -->
-- [x] `[fix]` `[P1]` TipTap: auto-expand new inline blocks, editor overflow, toolbar bg <!-- files: src/lib/admin/components/fields/structured-content/ -->
-- [x] `[chore]` `[P2]` Runtime types: FormEntryMap rename, add remote.ts
-- [x] `[chore]` `[P2]` Remove mode-watcher, hardcode light theme
-
-## 0.5.7 — SEO field & content fixes
-
-- [x] `[feature]` `[P1]` SEO field: auto/manual slug toggle with Switch <!-- files: src/lib/admin/components/fields/seo-field.svelte -->
-- [x] `[fix]` `[P1]` Structured content: skip empty paragraphs, wrap inline blocks in div <!-- files: src/lib/core/server/entries/operations/ -->
-- [x] `[fix]` `[P1]` resolveUrlFields: normalize flat string url/text, use raw DB calls <!-- files: src/lib/core/server/entries/ -->
-- [x] `[chore]` `[P1]` Migrate #await to reactive query pattern across admin UI
-
-## 0.5.8 — Media GC
-
-- [x] `[feature]` `[P1]` Image style upsert: replace duplicates instead of creating new files
-- [x] `[feature]` `[P1]` Auto-cleanup old style files from disk on regeneration
-- [x] `[feature]` `[P1]` Admin maintenance page: purge styles, reconcile orphaned disk files
-- [x] `[fix]` `[P1]` Deduplicate existing image style records (keep newest per unique key)
-
-## 0.6.0 — Entity module & DX
-
-- [x] `[feature]` `[P0]` Entity module — programmatic CRUD API for entries (`getEntity`) <!-- files: src/lib/entity/ -->
-- [x] `[feature]` `[P1]` CLI `install-peers` command <!-- files: src/lib/cli/ -->
-- [x] `[feature]` `[P1]` Collection data filters — filter by select/radio fields in toolbar <!-- files: src/lib/admin/client/collection/ -->
-- [x] `[feature]` `[P1]` Layout dot-notation — distribute object fields across layout nodes <!-- files: src/lib/admin/components/fields/ -->
-- [x] `[fix]` `[P1]` AI Claude: lazy client init, no crash without API key <!-- files: src/lib/ai-claude/ -->
-- [x] `[fix]` `[P1]` Codegen: quote hyphenated slugs, PascalCase form schemas, improved query types <!-- files: src/lib/core/server/generator/ -->
-- [x] `[fix]` `[P1]` TipTap: inline block content field lang fix + placeholder UX
-- [x] `[fix]` `[P1]` Zod schema: skip lang wrapper for non-localized content field
-- [x] `[breaking]` `[P0]` Runtime deps → peerDependencies (run `pnpm includio install-peers`)
-
-## 0.6.1 — Admin experience
-
-- [ ] `[feature]` `[P1]` Admin overlay — built-in admin bar on site (quick edit, preview, audit)
-- [ ] `[feature]` `[P1]` Media gallery virtualization/pagination <!-- files: src/lib/admin/components/media/files-list.svelte -->
-- [ ] `[feature]` `[P2]` Image styles UI — preview generated variants in editor
-
-## 0.7.0 — Auth core refactor & design fixes
-
-- [x] `[breaking]` `[P0]` Auth moved into CMS core — lazy betterAuth init from config, AuthAdapter → AuthConfig <!-- files: src/lib/core/cms.ts, src/lib/types/cms.ts, src/lib/sveltekit/server/handle.ts -->
-- [x] `[fix]` `[P1]` Media checkered bg & overlay gradient aligned with design system palette <!-- files: src/lib/admin/styles/admin.css -->
-- [x] `[fix]` `[P1]` Form inputs (input, textarea, select, input-group) use consistent bg-card background
-- [x] `[fix]` `[P2]` Blocks field accordion: rounded borders, card background
-- [x] `[fix]` `[P2]` Media file miniature: reset img/svg margins
-
-## 0.7.1 — Custom fields & admin DX
-
-- [x] `[feature]` `[P0]` Custom fields plugin system — type, zod/TS codegen, field renderer, populate resolver
-- [x] `[feature]` `[P1]` pathTemplate — configurable URL paths for collections/singles
-- [x] `[feature]` `[P1]` Admin public exports: admin/helpers & admin/ui for plugin authors
-- [x] `[feature]` `[P2]` resolveMediaWithStyles utility & core svelte export
-- [x] `[fix]` `[P1]` Schema serialization type cast (stricter TS compatibility)
-
-## 0.7.2 — CLI create-user
-
-- [x] `[feature]` `[P1]` CLI `create-user` command — interactive user creation with role assignment <!-- files: src/lib/cli/create-user.ts, src/lib/cli/index.ts -->
-
-## 0.7.3 — Typography
-
-- [x] `[feature]` `[P1]` Read-time orphan fix — replace space after single-letter Polish conjunctions with `\u00A0` <!-- files: src/lib/core/server/fields/resolveTypographyOrphans.ts, src/lib/core/server/fields/utils/fixOrphans.ts -->
-
-## 0.8.0 — Flat entry format
-
-- [x] `[breaking]` `[P0]` Flat entry format: objects use `_slug` + spread fields instead of `slug` + `data` wrapper
-- [x] `[breaking]` `[P0]` Blocks use `_slug` instead of `slug` with flat fields
-- [x] `[breaking]` `[P0]` `FlatEntry` type removed — use `Entry` instead
-
-## 0.9.0 — Per-language entry versions
-
-- [x] `[breaking]` `[P0]` Per-language entry versions: each language gets its own `entry_version` with flat data
-- [x] `[feature]` `[P0]` Per-language publication: publish/unpublish each language independently
-- [x] `[breaking]` `[P0]` Simplified data format: no more nested `{ pl: "X", en: "Y" }` — values are flat strings
-
-## 0.10.0 — Field type consolidation
-
-- [x] `[breaking]` `[P1]` Remove `image` field type — use `media` with `accept: "image/*"`
-- [x] `[breaking]` `[P1]` Remove `richtext` field type — use `content` (structured JSON)
-- [x] `[chore]` `[P1]` Remove `ImageField`, `RichtextField` interfaces + components
-
-## 0.11.0 — Codegen & REST consolidation
-
-- [x] `[feature]` `[P1]` Codegen: flat types, inline block types, `countEntries`, simplified API
-- [x] `[feature]` `[P1]` REST API: catch-all route, upload endpoint, media endpoint, schema templates
-- [x] `[chore]` `[P1]` Admin scaffold updated for new REST route structure
-
-## 0.12.0 — File field, dataOrderBy, _url
-
-- [x] `[feature]` `[P1]` File field type with multipart upload, validation, rate limiting
-- [x] `[feature]` `[P1]` `dataOrderBy` — sort entries by JSON data fields
-- [x] `[feature]` `[P1]` Auto-populate `_url` field on entries from slug resolver
-
-## 0.13.0 — Private file uploads
-
-- [x] `[feature]` `[P1]` Private file uploads — form submissions can upload files to non-public directory
-
-## 0.13.1 — Admin i18n, codegen cleanup, docs
-
-- [x] `[feature]` `[P1]` Admin UI i18n — TipTap, blocks, array, media components support pl/en <!-- files: src/lib/admin/components/tiptap/lang.ts -->
-- [x] `[feature]` `[P2]` Inline block accordion labels — show field value in collapsed header <!-- files: src/lib/admin/components/tiptap/InlineBlockNodeView.svelte -->
-- [x] `[feature]` `[P2]` Blocks field UrlFieldData label support <!-- files: src/lib/admin/components/fields/blocks-field.svelte -->
-- [x] `[feature]` `[P2]` Email configuration remote endpoint <!-- files: src/lib/admin/remote/email.remote.ts -->
-- [x] `[fix]` `[P1]` Codegen: remove unused Flat*FieldData types, use ImageFieldData/VideoFieldData <!-- files: src/lib/core/server/generator/fields.ts, src/lib/core/server/generator/generator.ts -->
-- [x] `[fix]` `[P1]` Layout renderer: hide card header when label empty <!-- files: src/lib/admin/components/layout/layout-renderer.svelte -->
-- [x] `[fix]` `[P1]` Collection entries: improved relation label fetching (UUID validation, multi-version) <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[fix]` `[P1]` Users page: client-side email config, remove server load <!-- files: src/lib/admin/client/users/users-page.svelte -->
-- [x] `[fix]` `[P2]` Entry remote: stricter UUID validation for ids <!-- files: src/lib/admin/remote/entry.remote.ts -->
-- [x] `[fix]` `[P2]` Layout type: remove unused label property <!-- files: src/lib/types/layout.ts -->
-- [x] `[chore]` `[P1]` Documentation rewrite — new pages for blocks, content, media-field, layout; expanded API, auth, entries, forms, plugins docs
-
-## 0.13.2 — Upload limits, stable reordering, image style optimization
-
-- [x] `[feature]` `[P1]` Configurable upload size limit — `BODY_SIZE_LIMIT` env var, pre-validation in UI <!-- files: src/lib/core/server/media/uploadLimit.ts, src/lib/admin/api/upload-limit.ts, src/lib/admin/components/media/file-upload.svelte -->
-- [x] `[feature]` `[P1]` Stable slot reordering — preserve filtered-out entry positions during DnD <!-- files: src/lib/admin/remote/reorder.ts, src/lib/admin/remote/entry.remote.ts -->
-- [x] `[feature]` `[P1]` Collection relation field filtering — filter entries by relation values <!-- files: src/lib/admin/client/collection/collection-entries.svelte -->
-- [x] `[feature]` `[P2]` Expose `_sortOrder` on entries + codegen for orderable collections <!-- files: src/lib/core/server/entries/operations/get.ts, src/lib/core/server/generator/generator.ts, src/lib/types/entries.ts -->
-- [x] `[feature]` `[P2]` `getImageStyleIfExists` — non-blocking image style lookup <!-- files: src/lib/core/server/media/styles/operations/getImageStyle.ts -->
-- [x] `[fix]` `[P1]` Concurrent image style generation with buffer reuse (download once, parallel limit 3) <!-- files: src/lib/core/server/media/styles/operations/generateDefaultStyles.ts, src/lib/core/server/media/styles/sharp/generateImageStyle.ts -->
-- [x] `[fix]` `[P1]` Image style resolution gracefully skips missing styles <!-- files: src/lib/core/server/fields/utils/imageStyles.ts -->
-
-## 0.13.3 — Security hardening
-
-- [x] `[fix]` `[P0]` Timing-safe API key comparison (prevents timing attacks) <!-- files: src/lib/admin/api/rest/middleware/apiKey.ts -->
-- [x] `[fix]` `[P0]` Remove demo reset endpoint with hardcoded fallback secret <!-- files: src/routes/api/demo/reset/ -->
-- [x] `[fix]` `[P1]` Form rate limit: all requests + getClientAddress() instead of x-forwarded-for <!-- files: src/routes/api/forms/[slug]/submit/+server.ts -->
-- [x] `[feature]` `[P1]` MIME blocklist on upload/replace endpoints <!-- files: src/lib/core/server/media/mimeBlocklist.ts -->
-- [x] `[feature]` `[P1]` Security headers: X-Content-Type-Options, X-Frame-Options, Referrer-Policy <!-- files: src/lib/sveltekit/server/handle.ts -->
-- [x] `[fix]` `[P1]` CMS constructor validates non-empty languages array <!-- files: src/lib/core/cms.ts -->
-- [x] `[fix]` `[P2]` Unhandled promise rejection handlers in admin components
-
-## 0.13.4 — Video poster regeneration
-
-- [x] `[feature]` `[P1]` Batch video poster regeneration — admin maintenance page with SSE progress <!-- files: src/lib/admin/api/regenerate-posters.ts, src/lib/core/server/media/operations/batchRegenerateVideoPosters.ts, src/lib/admin/client/maintenance/maintenance-page.svelte -->
-- [x] `[feature]` `[P1]` Video poster status reporting in media GC endpoint <!-- files: src/lib/admin/api/media-gc.ts -->
-- [x] `[chore]` `[P1]` Extracted video processing to reusable module <!-- files: src/lib/files-local/video.ts, src/lib/files-local/index.ts -->
-- [x] `[fix]` `[P1]` Filename sanitization normalizes Unicode to NFC <!-- files: src/lib/files-local/sanitizeFilename.ts -->
-
-## 0.14.0 — Video transcoding
-
-- [x] `[feature]` `[P1]` Video styles system — auto-transcode to mp4 h264 + webm vp9 <!-- files: src/lib/db-postgres/schema/videoStyle.ts, src/lib/files-local/transcode.ts -->
-- [x] `[feature]` `[P1]` Background transcoding pipeline on upload with skip logic <!-- files: src/lib/core/server/media/styles/operations/generateDefaultVideoStyles.ts -->
-- [x] `[feature]` `[P1]` Admin maintenance: video transcoding card (batch, purge, SSE progress) <!-- files: src/lib/admin/client/maintenance/maintenance-page.svelte -->
-- [x] `[feature]` `[P2]` Frontend multi-source video delivery (webm, mp4, original) <!-- files: src/lib/sveltekit/components/video.svelte -->
-- [x] `[feature]` `[P2]` Configurable video transcoding in MediaConfig <!-- files: src/lib/types/cms.ts -->
-- [x] `[feature]` `[P2]` System info endpoint — CMS version, Node, PostgreSQL, ffmpeg, sharp, OS <!-- files: src/lib/admin/api/system-info.ts, src/lib/core/server/media/operations/getSystemInfo.ts -->
-- [x] `[feature]` `[P2]` Disk usage endpoint — breakdown per category (originals, image styles, video styles, posters) <!-- files: src/lib/admin/api/system-info.ts, src/lib/core/server/media/operations/getDiskUsage.ts -->
-
-## 0.14.1 — CMS context, Svelte 5 compat, docs
-
-- [x] `[feature]` `[P1]` CMS context provider — Safari mp4 preference for video delivery <!-- files: src/lib/sveltekit/components/cms-provider.svelte, src/lib/sveltekit/components/video-context.ts, src/lib/types/cms-context.ts -->
-- [x] `[fix]` `[P1]` Svelte 5 compatibility — a11y annotations, warning suppression across admin components
-- [x] `[chore]` `[P1]` Documentation overhaul — new pages, README rewrite, DOCS.md compilation script <!-- files: scripts/compile-docs.ts, DOCS.md -->
-- [x] `[chore]` `[P2]` Remove obsolete docs/ Obsidian config & stale docs
-
-## 0.14.2 — Image styles: aspectRatio, skip defaults, lazy generation
-
-- [x] `[feature]` `[P1]` aspectRatio option for image styles — crop to ratio without fixed dimensions <!-- files: src/lib/types/fields.ts, src/lib/core/server/media/styles/sharp/generateImageStyle.ts, src/lib/db-postgres/schema/imageStyle.ts -->
-- [x] `[feature]` `[P1]` Skip default styles when field defines custom styles (prevents `<source>` conflicts in `<picture>`) <!-- files: src/lib/core/server/fields/utils/imageStyles.ts -->
-- [x] `[feature]` `[P2]` Lazy generation of custom field styles on first read <!-- files: src/lib/core/server/fields/utils/imageStyles.ts -->
-
-## 0.14.3 — Background maintenance
-
-- [x] `[feature]` `[P1]` Background maintenance scheduler — auto styles, posters, transcodes, orphan cleanup on configurable interval <!-- files: src/lib/core/server/media/operations/backgroundMaintenance.ts, src/lib/core/cms.ts -->
-- [x] `[feature]` `[P1]` Maintenance status API endpoint <!-- files: src/lib/admin/api/maintenance-status.ts, src/lib/admin/api/handler.ts -->
-- [x] `[feature]` `[P2]` Configurable maintenance interval via `media.maintenance` config <!-- files: src/lib/types/cms.ts -->
-- [x] `[feature]` `[P1]` Maintenance page UI redesign — status banner, sections, SSE handler dedup <!-- files: src/lib/admin/client/maintenance/maintenance-page.svelte -->
-
-## 0.14.5 — Schema cleanup
-
-- [x] `[chore]` `[P2]` Move image & video style unique indexes into Drizzle ORM schema (single source of truth) <!-- files: src/lib/db-postgres/schema/imageStyle.ts, src/lib/db-postgres/schema/videoStyle.ts -->
-
-## 0.14.6 — Admin page titles
-
-- [x] `[fix]` `[P2]` Admin `<title>` from breadcrumbs + pre-login titles + AriaCMS brand <!-- files: src/lib/admin/utils/pageTitle.ts, src/lib/admin/client/admin/admin-after-login-layout-content.svelte -->
-- [x] `[fix]` `[P1]` Video poster always from first frame (no jump on load) <!-- files: src/lib/files-local/video.ts -->
-- [x] `[feature]` `[P2]` Manual poster regeneration in media library file details <!-- files: src/lib/core/server/media/operations/regenerateVideoPoster.ts, src/lib/admin/components/media/file/file-details.svelte -->
-- [x] `[feature]` `[P2]` Config flag `sidebarHelp` to hide admin sidebar Help link (default true) <!-- files: src/lib/types/cms.ts, src/lib/core/cms.ts, src/routes/admin/(afterLogin)/+layout.server.ts, src/lib/admin/components/layout/nav-footer.svelte -->
-
-## 0.15.0 — Shop MVP (headless e-commerce)
-
-- [x] `[feature]` `[P0]` Scaffold: `defineShop`, types, CMSConfig slot, package export `./shop` <!-- files: src/lib/shop/index.ts, src/lib/shop/types.ts -->
-- [x] `[feature]` `[P0]` Drizzle tables: products (entry-backed), variants, orders, order items, status history, payments, shipping methods, stock reservations <!-- files: src/lib/db-postgres/schema/shop/ -->
-- [x] `[feature]` `[P0]` Runtime `schema.ts` generator for drizzle-kit (core + auth + optional shop) <!-- files: src/lib/core/server/generator/generator.ts, src/lib/db-postgres/schema-core.ts, src/lib/db-postgres/schema-shop.ts -->
-- [x] `[feature]` `[P0]` Rate-limit middleware (checkout/webhook) <!-- files: src/lib/shop/rate-limit.ts -->
-- [x] `[feature]` `[P0]` Built-in `shop` field type — makes entries purchasable, auto-hydrated via populateEntryData <!-- files: src/lib/admin/components/fields/shop-field.svelte, src/lib/shop/server/populate.ts -->
-- [x] `[feature]` `[P0]` Net/gross price toggle + live VAT preview in shop field and shipping form
-- [x] `[feature]` `[P0]` Auto default variant on upsert — cart/order always reference variantId
-- [x] `[feature]` `[P0]` Shop admin: products list (JOIN entries × shop_products), shipping methods CRUD with drag-n-drop reorder + free-above threshold
-- [x] `[feature]` `[P0]` Cart (signed cookie) service + `/api/shop/cart` REST + headless SDK `createShopClient()` <!-- files: src/lib/shop/cart/, src/lib/shop/client/ -->
-- [x] `[feature]` `[P0]` Orders + checkout + `manualAdapter` + status emails (inline HTML, PL/EN) <!-- files: src/lib/shop/server/orders.ts, src/lib/shop/http/checkout-handler.ts -->
-- [x] `[feature]` `[P0]` Stock reservation with 30-min TTL — released on cancel/reject, consumed on paid
-- [x] `[feature]` `[P0]` Admin orders view — list (status + email filter), detail (items, history, customer/address/consents, change status, resend email)
-- [x] `[feature]` `[P0]` Random Crockford base32 order numbers (`XXXXX-XXXXX`), unguessable
-- [x] `[feature]` `[P0]` CLI scaffold provisions all shop routes (admin + public API) in consumer app
-- [x] `[feature]` `[P1]` PayU payment adapter + webhook — shipped in 0.15.1 (access-token-gated order view, idempotent webhooks, MD5 signature, shipping↔payment compat, poll fallback)
-- [ ] `[feature]` `[P1]` Stripe payment adapter + webhook — deferred to 0.15.4
-- [x] `[feature]` `[P2]` InPost carrier adapter — shipped in 0.15.3 (Geowidget v5 picker + ShipX shipments + auto-confirm + webhook status updates)
-
-## 0.15.2 — Price precision fix
-
-- [x] `[fix]` `[P1]` Price drift on reload — storage jako `numeric(20,6)` (PLN z 6dp), brutto round-tripuje bez utraty ±1gr. Snapshot zamówienia dalej w groszach (KSeF). <!-- files: src/lib/db-postgres/schema/shop/product.ts, productVariant.ts, shippingMethod.ts, src/lib/shop/pricing.ts, src/lib/shop/server/cart-hydrate.ts, shipping.ts, shop-data.ts, src/lib/admin/components/fields/shop-field.svelte, src/lib/admin/client/shop/shipping-method-form.svelte -->
-- [x] `[feature]` `[P2]` Variant price toggle netto/brutto (spójne z toggle\'em ceny bazowej)
-- [x] `[feature]` `[P2]` `nodemailerAdapter` — typowanie `transportOptions` jako `SMTPTransport.Options` (OAuth2, pool, itd.)
-
-## 0.15.3 — InPost carrier
-
-- [x] `[feature]` `[P2]` `inpostAdapter()` — Geowidget v5 (`<InpostPicker>` Svelte + raw config endpoint), ShipX shipment create + auto-buy + label PDF + cancel, webhook → status + tracking, per-shipping-method service config, customer tracking display in `<OrderStatus>` + email templates
-- [x] `[chore]` `[P2]` Verbose logging on adapter auto-confirm flow (offer prep wait, buy POST, polling) for sandbox debugging
-
-## 0.15.4 — Forms submission scaffold + best-effort notification emails
-
-- [x] `[feature]` `[P1]` CLI scaffold emits `src/routes/api/forms/[slug]/submit/+server.ts` — public form submit endpoint auto-generated, no manual setup per project <!-- files: src/lib/cli/scaffold/admin.ts, src/lib/cli/scaffold/admin.spec.ts -->
-- [x] `[fix]` `[P0]` `createFormSubmission` — split try/catch so SMTP failure no longer returns `false` (endpoint responded 500 even though submission was persisted); notification email is best-effort, logged via `console.error` <!-- files: src/lib/core/server/forms/submissions/operations/create.ts -->
-- [ ] `[feature]` `[P1]` Built-in `/api/health` + `/api/health/ready` with per-adapter checks (db/files/email/ai) + ręczny SMTP diagnostics panel in maintenance page <!-- files: ideas/health-check-module.md -->
-
-## 0.16.0 — Hard reset
-
-> Start drogi do v1.0.0. Decyzje: **[V1-DECISIONS.md](./V1-DECISIONS.md)** | Workflow: **[V1-WORKFLOW.md](./V1-WORKFLOW.md)**
-
-- [x] `[breaking]` `[P0]` Wycięty `src/lib/inline-edit-proto/` (kod na lokalnym branchu `archive/inline-edit-proto`) — inline edit od zera w v1.x
-- [x] `[breaking]` `[P0]` Wycięty `src/lib/demo/seed.ts` + demo routes (`/demo/*`, `/admin/demo/*`) — demo content od zera w v1.x
-- [x] `[breaking]` `[P0]` Skasowany `ROADMAP-EDITOR.md` (treść na archive branch)
-- [x] `[chore]` `[P2]` `ideas/*.md` przeniesione do `ideas/post-v1/` (lokalnie, w `.gitignore`); `select-field-defaultvalue-bug` promowany do v1.0 fix
-- [x] `[chore]` `[P2]` `V1-DECISIONS.md` jako referencja decyzji v1 dla każdej kolejnej sesji
+> **Versioning:** since 0.16.0 droga do v1.0.0. Pre-v1.0 history → **[ROADMAP-ARCHIVE.md](./ROADMAP-ARCHIVE.md)**.
 
 ## v1.0.0 — Stabilizacja (in progress)
 
-> 13 faz w ~16 sesjach, droga 0.16 → 1.0.0. Lean scope: stabilizacja, security, testy, docs, audit + polish shopa. Bez nowych feature'ów.
+> 13 faz w ~16 sesjach, droga 0.16 → 1.0.0. Lean scope: stabilizacja, security, testy, docs, audit + polish shopa. Bez nowych feature'ów. Decyzje: **[V1-DECISIONS.md](./V1-DECISIONS.md)** | Workflow: **[V1-WORKFLOW.md](./V1-WORKFLOW.md)**.
 
-- [x] `[breaking]` `[P0]` API surface lock — exports trim 26→15, JSDoc tagi (@public/@internal/@experimental), `API.md` autogenerated (0.20.0) <!-- files: package.json, scripts/generate-api-md.ts -->
+- [x] `[breaking]` `[P0]` API surface lock — exports trim 26→16, JSDoc tagi (@public/@internal/@experimental), `API.md` autogenerated (0.20.0) <!-- files: package.json, scripts/generate-api-md.ts -->
+- [x] `[chore]` `[P1]` Faza 6 — Test foundation: docker postgres + integration project + 43 cases (30 REST + 6 shop checkout + 7 webhook signature/idempotency dla PayU/InPost), coverage report <!-- files: tests/integration/rest/, tests/helpers/{rest,shop}.ts, tests/integration/fixtures/shopConfig.ts, tests/setup.ts -->
+- [x] `[chore]` `[P1]` Faza 7 — E2E foundation: Playwright config (storageState reuse, setup project), `db_test_e2e` na 5435, `e2e/setup/global-setup.ts` (drizzle push), `e2e/admin/auth.setup.ts` (sign-up + admin role + login), 4 specy zielone w ~23s: login, collection-crud (blog-post create→edit→archive→permanent-delete), media-upload, user-mgmt (create→delete); data-testid na critical buttons admin <!-- files: playwright.config.ts, e2e/admin/*, src/lib/admin/client/{collection,entry,users}/, src/lib/admin/components/media/file-upload.svelte -->
+- [x] `[chore]` `[P1]` Faza 8 — CI na PR: `.github/workflows/ci.yml` z jobs lint/typecheck/unit/integration (postgres :5434)/e2e (postgres :5435 + playwright cache)/build, pnpm cache, trace artifacts on fail, README CI badge <!-- files: .github/workflows/ci.yml, README.md -->
+- [x] `[breaking]` `[P0]` Faza 9 — DX & config validation (0.22.0): `defineConfig` Zod strict z field path + hint, `CmsError` + `ConfigValidationError` z code/context, resolver throw sites zmigrowane, CLI `--help` per subcommand + `--version`, `.env.example` rozszerzony o `INCLUDIO_*`, README rebuild (TOC + system req + 5-min quickstart), JSDoc body (opis + @param + @returns + @example) na każdym `@public` <!-- files: src/lib/core/errors.ts, src/lib/types/cms.schema.ts, src/lib/sveltekit/config.ts, src/lib/cli/index.ts, README.md, .env.example, src/lib/updates/0.22.0/ -->
+- [x] `[chore]` `[P1]` Faza 10 — Documentation Pass (0.23.0): DOCS.md uzupełnione (number/boolean/date edge cases, REST cURL + error codes, Entries error handling + transactions, Admin UI a11y, Adapter Contracts), nowe sekcje (Stability Promise, Security Model), Migration Guide v0.x → v1.0 master cheatsheet (0.16-0.22), ROADMAP cleanup (pre-v1.0 → ROADMAP-ARCHIVE.md) <!-- files: src/routes/docs/{stability-promise,security}/+page.svx, src/routes/docs/migration/+page.svx, src/routes/docs/_config/nav.ts, scripts/compile-docs.ts, ROADMAP-ARCHIVE.md, src/lib/updates/0.23.0/ -->
 - [ ] `[fix]` `[P1]` Select field — `defaultValue` propagacja do zod schema (full repro: `ideas/post-v1/select-field-defaultvalue-bug.md`); fix planowany w Fazie 12 (RC)
 
 ## v1.x — Post-v1.0 deferred

package/dist/admin/api/rest/handler.d.ts

@@ -1,7 +1,19 @@
 import { type RequestHandler } from '@sveltejs/kit';
 /**
- * REST API handler factory. Returns `{ GET, POST, PUT, DELETE }` `RequestHandler`s authenticated via `x-api-key` header. Mount in `src/routes/admin/api/rest/[...restPath]/+server.ts`.
+ * REST API handler factory. Returns `{ GET, POST, PUT, DELETE }`
+ * `RequestHandler`s authenticated via the `x-api-key` header. Mount in
+ * `src/routes/admin/api/rest/[...restPath]/+server.ts`.
+ *
+ * @returns An object with `GET`, `POST`, `PUT`, `DELETE` SvelteKit
+ *   `RequestHandler`s, ready to re-export from a `+server.ts` route.
  * @public
+ * @example
+ * ```ts
+ * // src/routes/admin/api/rest/[...restPath]/+server.ts
+ * import { createRestApiHandler } from 'includio-cms/admin/remote';
+ *
+ * export const { GET, POST, PUT, DELETE } = createRestApiHandler();
+ * ```
  */
 export declare function createRestApiHandler(): {
     GET: RequestHandler;