npm package: @kozojs/cli
Description: CLI to scaffold new Kozo Framework projects - The next-gen TypeScript Backend Framework
Author: Kozo Team
Latest version: 0.1.34

# @kozojs/cli

🔥 **CLI to scaffold new Kozo Framework projects** - The next-gen TypeScript Backend Framework with **Zod Native Integration**

## Quick Start

```bash
# Using npx
npx @kozojs/cli my-app

# Or install globally
npm install -g @kozojs/cli
kozo my-app
```

## Features

- 🚀 **Interactive Setup** - Choose database, template, and more
- 📦 **Zero Config** - Works out of the box
- ⚡ **uWS-powered** - Native C++ route matching, 17,510 req/s
- 🛡️ **Type-safe** - Full TypeScript inference with Zod
- 🔥 **Fast Validation** - Ajv validation + fast-json-stringify serialization
- 📚 **OpenAPI Auto-gen** - Swagger docs out of the box
- 🗄️ **Drizzle ORM** - Best-in-class database toolkit

## Usage

### Create a new project

```bash
npx @kozojs/cli
```

Or with a project name:

```bash
npx @kozojs/cli my-awesome-api
```

### Interactive prompts

The CLI will ask you:

1. **Project name** - Name of your new project
2. **Template** - Choose from available templates:
   - **Complete Server** - Full production-ready app (Auth, CRUD, Stats, Pagination)
   - **Starter** - Minimal setup with database integration
   - **SaaS** - Auth + Stripe + Email (coming soon)
   - **E-commerce** - Products + Orders (coming soon)
3. **Database** - PostgreSQL, MySQL, or SQLite (skipped for Complete template)
4. **Package source** - npm registry or local workspace
5. **Install dependencies** - Auto-run `pnpm install`

## Project Structure

### Starter Template (with Database)
```
my-app/
├── src/
│   ├── db/
│   │   ├── schema.ts     # Drizzle schema
│   │   └── index.ts      # Database client
│   ├── services/
│   │   └── index.ts      # Service definitions
│   └── index.ts          # Entry point with Zod native API
├── drizzle.config.ts
├── package.json
└── tsconfig.json
```

### Complete Server Template
```
my-app/
├── src/
│   ├── data/
│   │   └── store.ts           # In-memory data store
│   ├── routes/
│   │   ├── auth/
│   │   │   └── index.ts       # Auth routes (login, me)
│   │   ├── users/
│   │   │   └── index.ts       # User CRUD routes
│   │   ├── posts/
│   │   │   └── index.ts       # Post routes
│   │   ├── health.ts          # Health check
│   │   └── stats.ts           # Statistics
│   ├── schemas/
│   │   ├── user.ts            # User schemas
│   │   ├── post.ts            # Post schemas
│   │   └── common.ts          # Common schemas
│   ├── utils/
│   │   └── helpers.ts         # Helper functions
│   └── index.ts               # Entry point
├── package.json
├── tsconfig.json
└── README.md
```

## 🚀 Complete Server Template

The **Complete Server** template generates a **production-ready** Kozo application with:

### Features
- ✅ **Authentication** - Login endpoint with mock JWT
- ✅ **User Management** - Full CRUD (Create, Read, Update, Delete)
- ✅ **Posts System** - With authors, tags, and filtering
- ✅ **Pagination** - Query-based pagination for lists
- ✅ **Statistics** - System stats endpoint (users, posts, performance)
- ✅ **Health Check** - Fast-path health endpoint
- ✅ **In-Memory Store** - Ready-to-run without database setup

### API Endpoints
- `POST /auth/login` - Authenticate user
- `GET /auth/me` - Get current user
- `GET /users?page=1&limit=10` - List users (paginated)
- `GET /users/:id` - Get user by ID
- `POST /users` - Create new user
- `PUT /users/:id` - Update user
- `DELETE /users/:id` - Delete user
- `GET /posts?published=true&tag=framework` - List posts (filtered)
- `GET /posts/:id` - Get post with author
- `POST /posts` - Create new post
- `GET /stats` - System statistics
- `GET /health` - Health check

### Performance Optimized
- Pre-compiled Zod schemas (no runtime overhead)
- Optimized handler closures
- Fast-path routes for simple endpoints
- Minimal context allocation

### Perfect For
- Learning Kozo framework features
- Prototyping and demos
- Benchmarking and performance testing
- Starting point for production apps

## ✨ New Zod Native API

Kozo now features a **brand new API** with automatic TypeScript inference:

```typescript
import { createKozo } from '@kozojs/core';
import { z } from 'zod';

const app = createKozo({
  port: 3000,
  openapi: {
    info: { title: 'My API', version: '1.0.0' }
  }
});

// Define schemas (compile-time only!)
const UserSchema = z.object({
  id: z.string(),
  name: z.string(),
  email: z.string()
});

const CreateUserSchema = z.object({
  name: z.string().min(2),
  email: z.string().email()
});

// Routes with automatic type inference
app.get('/users', {
  response: z.array(UserSchema)
}, (c) => {
  // TypeScript SA che il return è UserSchema[]
  return users;
});

app.post('/users', {
  body: CreateUserSchema,
  response: UserSchema
}, (c) => {
  // TypeScript SA che c.body ha name: string, email: string
  const newUser = {
    id: Date.now().toString(),
    name: c.body.name,  // ✅ Type-checked
    email: c.body.email // ✅ Type-checked
  };
  return newUser;
});

app.get('/users/:id', {
  params: z.object({ id: z.string() }),
  response: UserSchema
}, (c) => {
  // TypeScript SA che c.params.id è string
  const user = users.find(u => u.id === c.params.id);
  return user;
});

console.log('🚀 Server: http://localhost:3000');
console.log('📚 API Docs: http://localhost:3000/swagger');
app.listen();
```

## Performance Benefits

- **Validation**: Ajv compiled (5x faster than Zod runtime)
- **Serialization**: fast-json-stringify (2x faster than JSON.stringify)
- **Type Safety**: Complete TypeScript inference
- **Zero Overhead**: No runtime Zod parsing

## Requirements

- Node.js >= 18.0.0
- pnpm (recommended) or npm

## License

MIT