@kyro-cms/core 0.1.0 → 0.1.1

package/README.md

@@ -1,205 +1,524 @@
 # Kyro CMS
 
+<div align="center">
+
 **Astro-Native Headless CMS with Multi-Database Adapters, Multi-Protocol APIs, and Multi-Vendor Support**
 
-Kyro is an open-source, TypeScript-native headless CMS inspired by Payload CMS but architected specifically for Astro JS. It provides zero-inference tRPC, SQL-sovereign Drizzle schemas, and built-in multi-tenancy.
+[![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)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.7-blue.svg)](https://www.typescriptlang.org/)
+
+</div>
 
 ---
 
-## Features
+## Why Kyro?
 
-### Local-First with SQLite
-```typescript
-import { createKyro, LocalAdapter } from '@kyro-cms/core';
+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.
 
-const kyro = createKyro({
-  adapter: new LocalAdapter({ path: './data.db' }),
-  collections: [productsCollection],
-});
-```
-Works out of the box - no external database required.
-
-### Deploy Anywhere with Adapters
-- **Local/SQLite**: Zero-config local development
-- **PostgreSQL/MySQL/SQLite**: Via Drizzle ORM
-- **MongoDB**: NoSQL flexibility
+### Key Features
 
-### E-Commerce Ready
-Pre-built collections for:
-- Products with variants, pricing, inventory
-- Customers with addresses, orders
-- Orders with items, shipping, payments
-- Coupons and promotions
-- Inventory tracking
+- **Local-First** - SQLite for zero-config development, no external database needed
+- **Multi-Database** - SQLite, PostgreSQL, MySQL, 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
 
-### Multi-Protocol API
-- **REST**: Hono-based with query params
-- **GraphQL**: Dynamic schema
-- **tRPC**: Type-safe RPC (zero inference)
-- **WebSocket**: Real-time pub/sub
+---
 
-### Multi-Vendor Ready
-Row-level access control with tenant scoping built-in.
+## Quick Start
 
-### Plugin System
-Extend with:
-- SEO (sitemaps, structured data)
-- Analytics
-- Reviews & Comments
-- Wishlists
+### Option 1: Create New Project (Recommended)
 
-### Any Styling System
-- Plain CSS
-- Tailwind CSS
-- CSS-in-JS
-- Styled Components
-- Vanilla Extract
+```bash
+npm create kyro@latest
+```
 
----
+This launches an interactive wizard that asks:
+- Project name
+- Database (SQLite, PostgreSQL, MySQL, 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)
 
-## Quick Start
+### Option 2: Add to Existing Project
 
 ```bash
 npm install @kyro-cms/core
 ```
 
-### Basic Setup
+```typescript
+// kyro.config.ts
+import { defineConfig, localAdapter } from '@kyro-cms/core';
+
+export default defineConfig({
+  name: 'my-app',
+  adapter: localAdapter({ path: './data.db' }),
+  collections: {
+    posts: {
+      slug: 'posts',
+      label: 'Posts',
+      fields: [
+        { name: 'title', type: 'text', required: true },
+        { name: 'slug', type: 'text', required: true },
+        { name: 'content', type: 'richtext' },
+        { name: 'published', type: 'checkbox', defaultValue: false },
+      ],
+    },
+  },
+  api: {
+    rest: true,
+    graphql: true,
+  },
+});
+```
+
+---
+
+## Database Adapters
+
+### SQLite (Local-First)
 
 ```typescript
-import { createKyro, LocalAdapter } from '@kyro-cms/core';
+import { localAdapter } from '@kyro-cms/core';
 
-const kyro = createKyro({
-  adapter: new LocalAdapter(),
-  collections: [{
-    slug: 'posts',
-    fields: [
-      { name: 'title', type: 'text', required: true },
-      { name: 'content', type: 'richtext' },
-    ],
-  }],
+const adapter = localAdapter({
+  path: './data.db',  // or ':memory:' for in-memory
 });
+```
+
+Perfect for development and small projects. Zero configuration required.
 
-await kyro.init();
+### PostgreSQL/MySQL (Production)
+
+```typescript
+import { drizzleAdapter } from '@kyro-cms/core';
+
+const adapter = drizzleAdapter({
+  connectionString: process.env.DATABASE_URL,
+});
+```
+
+### MongoDB (Flexible Schemas)
+
+```typescript
+import { mongoAdapter } from '@kyro-cms/core';
+
+const adapter = mongoAdapter({
+  connectionString: process.env.MONGODB_URI,
+});
 ```
 
+---
+
+## API Protocols
+
+Kyro exposes your data through multiple protocols simultaneously.
+
 ### REST API
 
 ```bash
-curl http://localhost:3000/api/posts
-curl -X POST http://localhost:3000/api/posts \
-  -H "Content-Type: application/json" \
-  -d '{"title":"Hello World"}'
+# 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
 ```
 
 ### GraphQL
 
 ```graphql
-query { postsFind { docs { id title } totalDocs } }
-mutation { postsCreate(data: { title: "New Post" }) { doc { id } } }
+query {
+  postsFind(where: {}, page: 1, limit: 10) {
+    docs {
+      id
+      title
+      slug
+    }
+    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"
+});
+```
+
+### 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
+};
 ```
 
 ---
 
-## E-Commerce Example
+## 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
-import { createKyro, LocalAdapter } from '@kyro-cms/core';
-import { 
-  productsCollection, 
-  ordersCollection, 
-  customersCollection,
-  ecommerceCollections 
-} from '@kyro-cms/core/examples/ecommerce';
+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: new LocalAdapter({ path: './store.db' }),
+  adapter: localAdapter({ path: './store.db' }),
   collections: ecommerceCollections,
-  tenantScoped: true, // Multi-vendor
 });
 
-await kyro.init();
+// 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:
+
+```typescript
+import { Auth, createAuth } from '@kyro-cms/core';
+
+const auth = createAuth(adapter, {
+  secret: process.env.JWT_SECRET,
+  expiresIn: '24h',
+  refreshExpiresIn: '7d',
+});
+
+// Register
+await auth.register({
+  email: 'user@example.com',
+  password: 'secure123',
+  role: 'customer',
+});
+
+// Login
+const result = await auth.login({
+  email: 'user@example.com',
+  password: 'secure123',
+});
+
+console.log(result.token); // JWT token
+```
+
+---
+
+## 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
+```
+
+```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 { createKyro, SEOPLugin, ReviewsPlugin } from '@kyro-cms/core';
+import { 
+  KyroPlugin,
+  SEOPLugin,
+  AnalyticsPlugin,
+  CommentsPlugin,
+  ReviewsPlugin,
+  WishlistPlugin 
+} from '@kyro-cms/core';
 
 const kyro = createKyro({
-  adapter: new LocalAdapter(),
+  adapter: localAdapter(),
   collections: [...],
   plugins: [
-    new SEOPLugin(),
+    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
+## Styling System
+
+Kyro ships with a complete styling system:
 
 ```typescript
-import { ecommerce2026Theme, generateCSSVariables } from '@kyro-cms/core';
+import { 
+  ecommerce2026Theme,
+  generateCSSVariables,
+  generateTailwindConfig 
+} from '@kyro-cms/core';
 
 // Generate CSS variables
-const css = generateCSSVariables(ecommerce2026Theme);
+const cssVars = generateCSSVariables(ecommerce2026Theme);
+
+// Generate Tailwind config
+const tailwindConfig = generateTailwindConfig(ecommerce2026Theme);
+
+// Custom themes
+import { createAdminStyling } from '@kyro-cms/core';
+
+const myTheme = createAdminStyling({
+  primaryColor: '#6366f1',
+  borderRadius: 'medium',
+  fontFamily: 'Inter',
+});
 ```
 
 ---
 
-## Architecture
+## Deployment
 
+### Vercel
+
+```bash
+vercel --prod
 ```
-┌──────────────────────────────────────────────────────────────┐
-│                        Your Config                          │
-│              (CollectionConfig[])                           │
-└───────────────────────────┬──────────────────────────────────┘
-                          │
-                          ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Registry                                                     │
-│  • Stores configs                                             │
-│  • Generates Zod schemas                                     │
-│  • Validates config                                          │
-└───────────────────────────┬──────────────────────────────────┘
-                          │
-         ┌────────────────┼────────────────┐
-         ▼                ▼                ▼
-┌─────────────────┐ ┌─────────────┐ ┌─────────────────┐
-│  Local/SQLite   │ │   Drizzle   │ │   MongoDB       │
-│  (Local-first) │ │   (SQL)     │ │   (NoSQL)       │
-└─────────────────┘ └─────────────┘ └─────────────────┘
-                          │
-                          ▼
-┌──────────────────────────────────────────────────────────────┐
-│  Multi-Protocol API Gateway                                  │
-│  • REST (Hono)    • GraphQL    • tRPC    • WebSocket        │
-└──────────────────────────────────────────────────────────────┘
+
+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
 
 ```
 kyro-cms/
+├── packages/
+│   └── create-kyro/        # Project scaffolding CLI
 ├── src/
-│   ├── index.ts              # Main exports
-│   ├── registry/             # Configuration engine
-│   ├── fields/               # 21 field types
-│   ├── database/             # Adapters (Local, Drizzle, MongoDB)
-│   ├── api/                  # REST, GraphQL, tRPC, WebSocket
-│   ├── plugins/              # Plugin system
-│   ├── styling/              # Theming & CSS generation
-│   └── cli/                  # CLI tools
-├── admin/                    # Admin dashboard
-├── examples/
-│   ├── basic.config.ts      # Blog example
-│   └── ecommerce.config.ts   # E-commerce example
-└── docs/                     # Documentation
+│   ├── 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
 ```
 
 ---
@@ -207,9 +526,20 @@ kyro-cms/
 ## CLI Commands
 
 ```bash
-kyro generate        # Generate TypeScript types
-kyro migrate         # Run migrations
-kyro health          # Check system health
+# 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
 ```
 
 ---
@@ -220,22 +550,31 @@ kyro health          # Check system health
 - [API Reference](docs/api.md)
 - [E-Commerce Guide](docs/ecommerce.md)
 - [Plugin Development](docs/plugins.md)
-- [Styling Guide](docs/styling.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
 
 ---
 
 ## License
 
-MIT
+MIT License - see [LICENSE](LICENSE) for details.
 
 ---
 
-## Roadmap
+## Acknowledgments
 
-- [x] Local-first SQLite adapter
-- [x] E-commerce collections
-- [x] Plugin system
-- [x] Styling abstraction
-- [ ] Full admin dashboard
-- [ ] Authentication
-- [ ] Version history
+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