@ahmadjavaiddev/aura 1.0.1 → 1.0.3

package/README.md

@@ -1,98 +1,124 @@
-# 🚀 Aura
+# Aura
 
-**Aura** is a powerful, interactive CLI scaffolder designed to generate modern, high-performance Express.js backends in seconds. It abstracts away the boilerplate while giving you full control over the features you actually need.
+**The High-Performance API Scaffolder.**  
+Aura is an interactive CLI designed for developers who want to build modern Express.js backends—without the boilerplate. It abstracts framework complexities into a dedicated core while giving you total control over the features you need.
 
-Built for speed with **Bun** and **TypeScript**, Aura ensures your project starts with a solid, type-safe foundation.
+[![npm version](https://img.shields.io/npm/v/@ahmadjavaiddev/aura.svg?style=flat-square)](https://www.npmjs.com/package/@ahmadjavaiddev/aura)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg?style=flat-square)](https://opensource.org/licenses/MIT)
 
-[![npm version](https://img.shields.io/npm/v/@ahmadjavaiddev/aura.svg)](https://www.npmjs.com/package/@ahmadjavaiddev/aura)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+---
+
+## Why Aura?
 
-## 📦 Installation & Usage
+- **Zero Boilerplate**: Skip the setup. Get a production-ready API in 30 seconds.
+- **Abstraction-First**: Your logic in `src/routes`, framework magic in `src/base`.
+- **Full-Type Safety**: Built from the ground up with TypeScript and Zod.
+- **Enterprise-Ready**: Built-in support for OpenTelemetry, Redis, Auth, and Inngest.
+
+---
 
-You can run Aura directly without installing it globally using `npx`:
+## Quick Start
+
+Start your next project immediately with `npx`:
 
 ```bash
 npx @ahmadjavaiddev/aura my-new-project
 ```
 
 ### Options
-- `my-new-project`: The name of the directory to create.
-- `--version`, `-v`: Show version number.
-- `--help`, `-h`: Show help information.
+| Command | Description |
+| :--- | :--- |
+| `aura [name]` | Create a new project in the specified directory |
+| `aura add [feature]` | Inject a new feature (e.g. `redis`, `prisma`) into an existing Aura project |
+| `-v, --version` | Display current Aura version |
+| `-h, --help` | Show usage information |
+
+---
 
-## ✨ Features
+## Pick Your Stack
 
-Aura is highly modular. During the interactive setup, you can pick and choose from the following:
+Aura is modular by design. Select only the components you need for your project:
 
-- 🗄️ **Database ORMs**: Prisma (PostgreSQL), Drizzle (PostgreSQL), or Mongoose (MongoDB).
-- 🔐 **Authentication**: Clerk (Hosted), Better-Auth (Self-hosted), or a Custom JWT Middleware starter.
-- ⚡ **Caching**: Distributed caching with Redis or simple In-memory local caching.
-- 🪵 **Logging**: Advanced OpenTelemetry (with PostHog integration) or standard Console logging.
-- 🚥 **Rate Limiting**: Redis-based (distributed) or Basic (memory-based) protection.
-- 📨 **Emails**: Integration with Resend or traditional SMTP via Nodemailer.
-- 🔄 **Background Jobs**: Built-in support for Inngest event-driven background functions.
-- 📏 **Linting & Formatting**: Biome (Ultra-fast) or the classic Prettier + ESLint combo.
-- 📄 **Pagination**: Pre-configured Zod schemas and pagination helpers.
+### Database & Models
+- **ORM Options**: Prisma (PostgreSQL), Drizzle (SQL), Mongoose (MongoDB).
+- **Auto-Sync**: Pre-configured scripts for database migrations and client generation.
+
+### Security & Auth
+- **Providers**: Clerk (Hosted), Better-Auth (Self-hosted), Custom JWT.
+- **Protection**: Optional Redis-based Rate Limiting and Role-based access skeletons.
+
+### Performance & Scaling
+- **Caching**: Choose between local In-memory or distributed Redis caching.
+- **Background Jobs**: Native Inngest support for event-driven background functions.
+
+### Observability & Tooling
+- **Logging**: Console-based or OpenTelemetry + PostHog for production tracking.
+- **Development**: Choice of **Biome** (Ultra-fast) or **ESLint + Prettier**.
+- **Email**: Integrated **Resend** or traditional **SMTP** (Nodemailer).
+
+### Infrastructure
+- **Docker**: Automatically generate a production-ready `Dockerfile` and `docker-compose.yml`.
+- **CI/CD**: Generate GitHub Actions workflows for seamless testing and linting pipelines.
+
+---
 
-## 🏗️ Project Structure
+## ⚡ Aura Add
 
-Aura follows a clean, "Abstraction-First" architecture. All framework-heavy code is tucked away in the `src/base` directory, allowing you to focus on your business logic.
+Scaffolded a barebones project but decided you need Redis later? Use the `aura add` command to intelligently inject features into your existing project—modifying `package.json`, updating environment variables, injecting imports, and setting up initializations automatically using slot markers!
+
+```bash
+aura add redis
+aura add prisma
+```
+
+---
+
+## The Aura Blueprint
+
+The generated project structure is designed to isolate framework code from your business logic:
 
 ```text
 my-new-project/
 ├── src/
-│   ├── app.ts              # Entry point
-│   ├── routes/             # Your API routes go here
-│   ├── base/               # Framework abstractions (Route Registry, etc.)
+│   ├── app.ts              # Clean main entry point
+│   ├── routes/             # YOUR LOGIC: API endpoints live here
+│   ├── base/               # THE CORE: Framework abstractions (Internal)
 │   ├── config/             # Environment & service configurations
-│   ├── middlewares/        # Custom middlewares (Auth, Logging)
-│   ├── utils/              # Shared utilities (Zod helpers, Errors)
-│   └── [models/db/inngest] # Feature-specific directories
-├── .env                    # Pre-configured environment variables
+│   ├── middlewares/        # Custom middlewares (Auth, Logger)
+│   ├── utils/              # Shared utilities (Zod, Errors, Email)
+│   └── ...                 # Feature directories (models, inngest, etc.)
+├── .env                    # Pre-configured environment boilerplate
 ├── package.json
 └── tsconfig.json
 ```
 
-## 🚀 Getting Started
-
-Once generated, your project is ready to go:
-
-1. **Install Dependencies**:
-   ```bash
-   cd my-new-project
-   bun install
-   ```
-
-2. **Database Setup** (if applicable):
-   ```bash
-   bun run db:generate  # For Prisma
-   ```
-
-3. **Start Development**:
-   ```bash
-   bun run dev
-   ```
+---
 
-## 🛠️ Defining Routes
+## Defining Routes
 
-Aura makes route definition simple and type-safe using `defineRoute`:
+Aura makes route definition declarative and type-safe using the `defineRoute` utility. Every route automatically returns a heavily standardized `ApiResponse<T>`:
 
 ```typescript
-import { defineRoute } from "../base";
+import { defineRoute } from "../base/define-route";
 import { z } from "zod";
 
-export default defineRoute({
-  method: "GET",
-  path: "/hello",
-  schema: {
-    query: z.object({ name: z.string().optional() })
+export const createUser = defineRoute({
+  method: "post",
+  path: "/users",
+  input: {
+    body: z.object({ name: z.string(), email: z.string().email() })
   },
-  handler: async ({ req, res, query }) => {
-    res.json({ message: `Hello, ${query.name || "World"}!` });
+  output: z.object({ id: z.string(), name: z.string() }),
+  handler: async ({ body }) => {
+    // Body is fully typed!
+    const { name, email } = body;
+    // Return the output according to the schema - Aura automatically wraps it in a standard response:
+    // { success: true, data: { ... }, metadata: { timestamp: "...", path: "/users" } }
+    return { id: "123", name };
   },
 });
 ```
 
 ---
 
-Built with ❤️ by [Ahmad Javaid](https://github.com/ahmadjavaiddev)
+Built by [Ahmad Javaid](https://github.com/ahmadjavaiddev)