@kyro-cms/core 0.9.0 → 0.9.2

package/README.md

@@ -2,7 +2,7 @@
 
 <div align="center">
 
-**Astro-Native Headless CMS with Multi-Database Adapters, Multi-Protocol APIs, and Multi-Vendor Support**
+**Astro-native headless CMS with multi-database adapters, multi-protocol APIs, and an admin dashboard built-in.**
 
 [![npm version](https://img.shields.io/npm/v/@kyro-cms/core.svg)](https://www.npmjs.com/package/@kyro-cms/core)
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
@@ -12,54 +12,47 @@
 
 ---
 
-## Why Kyro?
+## What Kyro Gives You
 
-Kyro is built for **Astro** from the ground up. Unlike other CMS solutions that bolt on Astro support, Kyro is architected to leverage Astro's islands architecture, server output modes, and performance-first approach.
+Kyro turns a single TypeScript config into a full CMS backend for Astro, including:
 
-### Key Features
-
-- **Zero-Config Development** - SQLite by default for instant setup, no external dependencies
-- **Multi-Database** - SQLite (dev), PostgreSQL, MongoDB via unified adapter interface
-- **Multi-Protocol API** - REST, GraphQL, tRPC, and WebSocket from a single config
-- **Multi-Vendor** - Built-in tenant scoping and row-level access control
-- **E-Commerce Ready** - Products, orders, customers, inventory, coupons out of the box
-- **Plugin System** - Extend with SEO, analytics, reviews, and more
-- **Any Styling** - Tailwind, CSS Modules, Styled Components, or plain CSS
+- **REST, GraphQL, tRPC, and WebSocket APIs** from the same collection schema
+- **Local SQLite development** plus production-ready PostgreSQL and MongoDB adapters
+- **Auto-generated admin UI** with forms, media, auth, and drafts
+- **End-to-end type safety** powered by Zod and TypeScript
+- **Plugin-friendly architecture** for custom hooks, fields, and dashboard extensions
 
 ---
 
 ## Quick Start
 
-### Option 1: Create New Project (Recommended)
+### Create a new Kyro project
 
 ```bash
-npm create kyro@latest
+pnpm create kyro@latest my-project
+cd my-project
+pnpm install
+pnpm dev
 ```
 
-This launches an interactive wizard that asks:
+Open:
 
-- Project name
-- Database (SQLite, PostgreSQL, MongoDB)
-- API protocols (REST, GraphQL, tRPC, WebSocket)
-- Styling (Tailwind, CSS Modules, Styled Components, None)
-- Authentication (JWT)
-- Versioning/Drafts
-- Admin dashboard
-- Starting template (Minimal, Blog, E-commerce)
+- `http://localhost:4321` — public site
+- `http://localhost:4321/admin` — admin dashboard
 
-### Option 2: Add to Existing Project
+### Add Kyro to an existing project
 
 ```bash
-npm install @kyro-cms/core
+pnpm install @kyro-cms/core
 ```
 
 ```typescript
 // kyro.config.ts
-import { defineConfig, localAdapter } from "@kyro-cms/core";
+import { defineConfig, createLocalAdapter } from "@kyro-cms/core";
 
 export default defineConfig({
   name: "my-app",
-  adapter: localAdapter({ path: "./data.db" }),
+  adapter: createLocalAdapter({ path: "./data.db" }),
   collections: {
     posts: {
       slug: "posts",
@@ -72,73 +65,59 @@ export default defineConfig({
       ],
     },
   },
-  api: {
-    rest: true,
-    graphql: true,
-  },
 });
 ```
 
 ---
 
-## Database Adapters
+## Why Kyro
 
-### SQLite (Default for Development)
+Kyro is designed for Astro-first content applications:
 
-```typescript
-import { localAdapter } from "@kyro-cms/core";
+- **Fast dev setup:** zero-config local SQLite support
+- **Unified API surface:** one schema powers REST, GraphQL, tRPC, and WebSockets
+- **Production-ready:** swap adapters without rewriting collections
+- **Admin experience:** auto-generated UIs, auth, RBAC, and draft workflows
 
-const adapter = localAdapter({
-  path: "./data.db", // or ':memory:' for in-memory
-});
-```
+---
 
-Perfect for development and small projects. Zero configuration required - no external services needed.
+## Core Concepts
 
-### PostgreSQL (Production)
+### Database adapters
 
-```typescript
-import { drizzleAdapter } from "@kyro-cms/core";
+Kyro uses a shared adapter layer so the same collection schema works across:
 
-const adapter = drizzleAdapter({
-  connectionString: process.env.DATABASE_URL,
-});
-```
+- **SQLite** — instant local development
+- **PostgreSQL** — production SQL with Drizzle
+- **MongoDB** — flexible document storage
 
-### MongoDB (Flexible Schemas)
+### API protocols
 
-```typescript
-import { mongoAdapter } from "@kyro-cms/core";
+Use multiple protocols at once, depending on your app needs:
 
-const adapter = mongoAdapter({
-  connectionString: process.env.MONGODB_URI,
-});
-```
+- **REST** for simple CRUD and integration compatibility
+- **GraphQL** for nested queries and schema introspection
+- **tRPC** for fully type-safe client-server calls
+- **WebSocket** for real-time subscriptions and live updates
 
----
+### Astro-safe exports
 
-## API Protocols
+Kyro preserves Astro compatibility with two entrypoints:
 
-Kyro exposes your data through multiple protocols simultaneously.
+- `@kyro-cms/core` — server-only backend logic, adapters, auth, and APIs
+- `@kyro-cms/core/client` — browser-safe client utilities, types, and UI helpers
 
-### REST API
+---
+
+## Example usage
+
+### REST
 
 ```bash
-# List documents
 GET /api/posts
-
-# Get single document
 GET /api/posts/:id
-
-# Create document
 POST /api/posts
-{ "title": "Hello World" }
-
-# Update document
 PATCH /api/posts/:id
-{ "title": "Updated Title" }
-
-# Delete document
 DELETE /api/posts/:id
 ```
 
@@ -155,542 +134,25 @@ query {
     totalDocs
   }
 }
-
-mutation {
-  postsCreate(data: { title: "New Post", slug: "new-post" }) {
-    doc {
-      id
-      title
-    }
-  }
-}
 ```
 
 ### tRPC
 
 ```typescript
-const client = createTRPCClient({
-  router: kyro.router,
-  transformer: superjson,
-});
-
-// Type-safe queries
-const posts = await client.posts.find.query({ page: 1 });
-const newPost = await client.posts.create.mutate({
-  title: "Hello",
-  slug: "hello",
-});
-```
-
----
-
-## Core Export Splitting (Astro Support)
-
-To support **Astro's islands architecture** and prevent Node.js-only dependencies (like Redis, bcrypt, or database drivers) from crashing your browser bundle, Kyro Core provides two distinct entrypoints:
-
-### 1. `@kyro-cms/core` (Server-Only)
-
-Use this for backend logic, API routes, database configuration, and authentication adapters. This entrypoint includes all Node.js built-ins.
-
-```typescript
-import { createKyro, drizzleAdapter, RedisAuthAdapter } from "@kyro-cms/core";
-```
-
-### 2. `@kyro-cms/core/client` (Browser-Safe)
-
-Use this for **Astro components**, React/Vue/Svelte islands, styling, and types. This entrypoint is guaranteed to be free of Node.js dependencies.
-
-```typescript
-import type { KyroConfig, CollectionConfig } from "@kyro-cms/core/client";
-import { defaultLightTheme, generateCSSVariables } from "@kyro-cms/core/client";
-```
-
----
-
-### WebSocket (Real-time)
-
-```typescript
-const ws = new WebSocket("ws://localhost:4321/api/ws");
-
-ws.send(
-  JSON.stringify({
-    type: "subscribe",
-    collection: "posts",
-    event: "create",
-  }),
-);
-
-ws.onmessage = (event) => {
-  const data = JSON.parse(event.data);
-  // Handle real-time updates
-};
-```
-
----
-
-## Field Types
-
-Kyro supports 21 field types:
-
-| Type           | Description                |
-| -------------- | -------------------------- |
-| `text`         | Single-line text input     |
-| `textarea`     | Multi-line text            |
-| `richtext`     | Rich text editor content   |
-| `markdown`     | Markdown content           |
-| `number`       | Numeric values             |
-| `email`        | Email with validation      |
-| `password`     | Hashed password storage    |
-| `checkbox`     | Boolean toggle             |
-| `date`         | Date/time picker           |
-| `select`       | Dropdown selection         |
-| `radio`        | Radio button group         |
-| `color`        | Color picker               |
-| `json`         | JSON data                  |
-| `code`         | Code editor content        |
-| `array`        | Repeatable field groups    |
-| `group`        | Nested field groups        |
-| `relationship` | Link to other documents    |
-| `upload`       | File/media uploads         |
-| `blocks`       | Structured content blocks  |
-| `row`          | Horizontal field layout    |
-| `collapsible`  | Collapsible field sections |
-| `tabs`         | Tabbed interface           |
-
-### Example: Complex Fields
-
-```typescript
-fields: [
-  { name: "title", type: "text", required: true },
-
-  {
-    name: "author",
-    type: "relationship",
-    relationTo: "users",
-    required: true,
-  },
-
-  {
-    name: "tags",
-    type: "array",
-    fields: [
-      { name: "name", type: "text" },
-      { name: "slug", type: "text" },
-    ],
-  },
-
-  {
-    name: "metadata",
-    type: "group",
-    fields: [
-      { name: "views", type: "number", defaultValue: 0 },
-      { name: "featured", type: "checkbox" },
-    ],
-  },
-];
-```
-
----
-
-## E-Commerce Collections
-
-Pre-built collections for building online stores:
-
-```typescript
-import { ecommerceCollections } from "@kyro-cms/core";
-
-const kyro = createKyro({
-  adapter: localAdapter({ path: "./store.db" }),
-  collections: ecommerceCollections,
-});
-
-// Includes:
-// - products (with variants, pricing, inventory)
-// - categories (hierarchical)
-// - customers (with addresses)
-// - orders (with items, status tracking)
-// - coupons (percentage, fixed, free shipping)
-// - store settings (globals)
-```
-
----
-
-## Authentication
-
-Built-in JWT authentication with multiple storage options:
-
-```typescript
-import { RedisAuthAdapter, SQLiteAuthAdapter } from "@kyro-cms/core";
-import { createAuthConfig } from "@kyro-cms/core";
-
-// Use SQLite for development (zero-config, default)
-const adapter = new SQLiteAuthAdapter({ path: "./data.db" });
-
-// Use Redis for sessions (recommended for production)
-const redisAdapter = new RedisAuthAdapter({
-  url: process.env.REDIS_URL,
-  tls: process.env.REDIS_TLS === "true",
-});
-
-// Or use PostgreSQL for production
-import { PostgresAuthAdapter, createDatabase } from "@kyro-cms/core";
-
-const { db } = await createDatabase();
-const pgAdapter = new PostgresAuthAdapter({ db });
-
-// Or use env-based config with all features
-const authConfig = await createAuthConfig();
-const { redis, routes, passwordPolicy, lockout } = authConfig;
-```
-
-### Authentication Features
-
-- **JWT Tokens** - 24h expiry with refresh token support
-- **Multiple Storage Options** - SQLite (dev), Redis, PostgreSQL via unified adapter interface
-- **Password Policy** - 12+ chars, complexity requirements, history check
-- **Account Lockout** - 5 failed attempts → 15 minute lockout
-- **Rate Limiting** - Per-IP and per-user limits
-- **Audit Logging** - 30-day retention with action tracking
-
-### CLI Commands
-
-```bash
-# Create admin user (first-run bootstrap)
-kyro auth bootstrap -e admin@example.com -p "SecurePass123!" -r admin
-
-# Database setup
-kyro db migrate    # Run migrations
-kyro db push       # Push schema to database
-kyro db seed       # Seed default roles
-kyro db studio     # Open Drizzle Studio
-```
-
-### RBAC Roles (Hierarchy)
-
-```
-super_admin (100) > admin (90) > editor (70) > author (50) > customer (30) > guest (10)
-```
-
-### Environment Variables
-
-```bash
-# Database
-DATABASE_URL=postgresql://user:pass@host:5432/kyro_cms
-DATABASE_SSL=false
-
-# Redis (sessions/cache)
-REDIS_URL=redis://localhost:6379
-REDIS_TLS=false
-
-# JWT
-JWT_SECRET=your-32-char-secret
-JWT_EXPIRES_IN=24h
-
-# Auth Settings
-LOCKOUT_MAX_ATTEMPTS=5
-LOCKOUT_DURATION_MINUTES=15
-PASSWORD_MIN_LENGTH=12
-
-# Bootstrap (first-run admin)
-KYRO_ADMIN_EMAIL=admin@example.com
-KYRO_ADMIN_PASSWORD=SecurePass123!
-```
-
----
-
-## Version History & Drafts
-
-Track document changes with built-in versioning:
-
-```typescript
-import { createVersionManager } from "@kyro-cms/core";
-
-const versions = createVersionManager(adapter, {
-  versioningEnabled: true,
-  maxVersionsPerDocument: 50,
-});
-
-// Create a new version
-const version = await versions.createVersion({
-  collection: "posts",
-  documentId: "abc123",
-  data: { title: "Updated Post" },
-  status: "draft",
-  createdBy: "user123",
-});
-
-// Publish
-await versions.publishVersion({
-  collection: "posts",
-  documentId: "abc123",
-  versionId: version.id,
-  publishedBy: "user123",
-});
-```
-
----
-
-## Admin Dashboard
-
-Kyro includes a full admin dashboard:
-
-```bash
-npm install @kyro-cms/admin @kyro-cms/core
-```
-
-The admin uses local utilities for API calls, date formatting, and validation.
-
-```astro
----
-// admin/index.astro
-import { Admin } from '@kyro-cms/admin';
-import config from '../kyro.config';
----
-
-<Admin client:load config={config} />
-```
-
-Features:
-
-- Collection browser with filtering and sorting
-- Document editor with all field types
-- Media library
-- Global settings editor
-- Dark mode support
-
----
-
-## Plugin System
-
-Extend Kyro with plugins:
-
-```typescript
-import {
-  KyroPlugin,
-  SEOPLugin,
-  AnalyticsPlugin,
-  CommentsPlugin,
-  ReviewsPlugin,
-  WishlistPlugin
-} from '@kyro-cms/core';
-
-const kyro = createKyro({
-  adapter: localAdapter(),
-  collections: [...],
-  plugins: [
-    new SEOPLugin({
-      sitemap: true,
-      robotsTxt: true,
-    }),
-    new AnalyticsPlugin({
-      providers: ['google', 'plausible'],
-    }),
-    new CommentsPlugin(),
-    new ReviewsPlugin(),
-  ],
-});
-```
-
-### Creating Plugins
-
-```typescript
-import { KyroPlugin } from "@kyro-cms/core";
-
-class MyPlugin extends KyroPlugin {
-  name = "my-plugin";
-
-  hooks = {
-    "collection.beforeCreate": async (args) => {
-      // Transform data before creation
-      return { ...args, data: { ...args.data, source: "my-plugin" } };
-    },
-
-    "document.afterSave": async (args) => {
-      // Send webhook, log analytics, etc.
-      await sendWebhook(args);
-    },
-  };
-}
-```
-
----
-
-## Styling System
-
-Kyro ships with a complete styling system:
-
-```typescript
-import {
-  ecommerce2026Theme,
-  generateCSSVariables,
-  generateTailwindConfig,
-} from "@kyro-cms/core/client";
-
-// Generate CSS variables
-const cssVars = generateCSSVariables(ecommerce2026Theme);
-
-// Generate Tailwind config
-const tailwindConfig = generateTailwindConfig(ecommerce2026Theme);
-
-// Custom themes
-import { createAdminStyling } from "@kyro-cms/core/client";
-
-const myTheme = createAdminStyling({
-  primaryColor: "#6366f1",
-  borderRadius: "medium",
-  fontFamily: "Inter",
-});
-```
-
----
-
-## Deployment
-
-### Quick Start with Docker
-
-```bash
-# Start PostgreSQL + Redis
-docker compose up -d
-
-# Push schema to database
-npm run db:push
-
-# Create admin user
-kyro auth bootstrap -e admin@example.com -p "SecurePass123!"
-
-# Start development
-npm run dev
-```
-
-### Environment Variables Required
-
-```bash
-# Database (PostgreSQL)
-DATABASE_URL=postgresql://postgres:postgres@localhost:5432/kyro_cms
-DATABASE_SSL=false
-
-# Redis (sessions/cache) - supports Redis Cloud
-REDIS_URL=redis://localhost:6379
-REDIS_TLS=false
-
-# JWT (required)
-JWT_SECRET=change-me-in-production-min-32-chars
+const response = await client.posts.find.query({ page: 1, limit: 10 });
 ```
 
-### Vercel
-
-```bash
-vercel --prod
-```
-
-Environment variables:
-
-- `DATABASE_URL` - PostgreSQL connection string
-- `JWT_SECRET` - JWT signing secret
-
-### Railway
-
-```bash
-railway up
-```
-
-### Docker
-
-```bash
-cd deployments/docker
-docker-compose up -d
-```
-
-See `deployments/` for complete configuration.
-
 ---
 
-## Project Structure
+## Learn more
 
-```
-kyro-cms/
-├── packages/
-│   └── create-kyro/        # Project scaffolding CLI
-├── src/
-│   ├── index.ts             # Main exports
-│   ├── createKyro.ts        # Factory function
-│   ├── registry/            # Config registry & validation
-│   ├── fields/              # 21 field type definitions
-│   ├── database/            # Adapter implementations
-│   │   ├── local/           # SQLite adapter
-│   │   ├── drizzle/         # SQL adapters
-│   │   └── mongodb/         # MongoDB adapter
-│   ├── api/                 # Multi-protocol gateway
-│   │   ├── rest/            # Hono REST
-│   │   ├── graphql/         # GraphQL schema
-│   │   ├── trpc/            # tRPC router
-│   │   └── ws/              # WebSocket server
-│   ├── auth/                # JWT authentication
-│   ├── versions/            # Version history
-│   ├── plugins/             # Plugin system
-│   ├── styling/             # Theming
-│   └── cli/                 # CLI tools
-├── admin/                   # Admin dashboard (Astro)
-├── examples/                # Example configurations
-├── docs/                    # Documentation
-└── deployments/             # Deployment configs
-```
-
----
-
-## CLI Commands
-
-```bash
-# Initialize a new project
-npm create kyro@latest
-
-# Generate TypeScript types
-kyro generate
-
-# Push schema to database
-kyro push
-
-# Open database studio
-kyro studio
-
-# Check system health
-kyro health
-```
-
----
-
-## Documentation
-
-- [Getting Started](docs/getting-started.md)
-- [API Reference](docs/api.md)
-- [E-Commerce Guide](docs/ecommerce.md)
-- [Plugin Development](docs/plugins.md)
-- [Deployment Guide](docs/deployment.md)
-
----
-
-## Contributing
-
-Contributions are welcome! Please read our contributing guide before submitting PRs.
-
-1. Fork the repository
-2. Create your feature branch (`git checkout -b feature/amazing`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing`)
-5. Open a Pull Request
+- `docs/getting-started.md` — setup and first app walkthrough
+- `docs/architecture.md` — how Kyro works under the hood
+- `docs/api.md` — API protocols and usage patterns
+- `docs/database.md` — supported adapters and configuration
 
 ---
 
 ## License
 
-MIT License - see [LICENSE](LICENSE) for details.
-
----
-
-## Acknowledgments
-
-Built with inspiration from:
-
-- [Payload CMS](https://payloadcms.com/) - The headless CMS that pushed the industry forward
-- [Strapi](https://strapi.io/) - Open source headless CMS
-- [Sanity](https://www.sanity.io/) - Real-time content infrastructure
+MIT