Metadata-Version: 2.4
Name: aiplanet
Version: 2.0.0
Summary: CLI tool for generating FastAPI project boilerplate
License: MIT
License-File: LICENSE
Author: Gourab Sinha
Author-email: gourab@aiplanet.com
Requires-Python: >=3.10,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: colorama (>=0.4.6,<0.5.0)
Requires-Dist: jinja2 (>=3.1.2,<4.0.0)
Requires-Dist: pydantic (>=2.0.0,<3.0.0)
Requires-Dist: pyyaml (>=6.0.1,<7.0.0)
Requires-Dist: questionary (>=1.10.0,<2.0.0)
Requires-Dist: rich (>=13.3.5,<14.0.0)
Requires-Dist: shellingham (>=1.5.0,<2.0.0)
Requires-Dist: typer (>=0.15,<1.0)
Description-Content-Type: text/markdown

# AI Planet CLI

AI Planet CLI is a powerful command-line tool for generating production-ready **FastAPI backend** and **React + TypeScript frontend** projects with best practices baked in. It helps you quickly scaffold full-stack applications with the right structure and components.

## Features

### Backend (FastAPI)
- **Project Generation**: Create a new FastAPI project with the recommended structure
- **Component Management**: Add, remove, and generate components for your project
- **Database Migrations**: Manage database migrations with Alembic
- **Development Server**: Run your FastAPI application in development or production mode
- **Docker Support**: Generate Docker configuration and run your app in containers
- **RBAC System**: Role-based access control with permissions
- **Multi-tenancy**: Organization-based data isolation
- **Rate Limiting**: Redis-based request throttling
- **Field Encryption**: Fernet-based sensitive data encryption

### Frontend (React + TypeScript)
- **Project Generation**: Create a complete React 18 + TypeScript project
- **State Management**: Zustand with devtools and persistence
- **UI Components**: shadcn/ui + Tailwind CSS
- **Routing**: React Router v6 with protected routes
- **Forms**: React Hook Form + Zod validation
- **Data Tables**: TanStack Table with sorting, filtering, pagination
- **Authentication**: JWT with automatic token refresh
- **RBAC Components**: ProtectedRoute, RoleGuard, PermissionGate
- **Multi-tenancy**: Organization switching support

## Installation

```bash
pip install aiplanet
```

---

# Backend Commands

## Project Structure (Backend)

The CLI generates a backend project with the following structure:

```
my_project/                      # Project root
├── my_project/                  # Main package directory
│   ├── __init__.py              # Package initialization with version
│   ├── constants/               # Application constants
│   ├── core/                    # Core functionality
│   │   ├── config.py            # Application configuration
│   │   ├── database.py          # Database connection
│   │   ├── security.py          # Authentication and authorization
│   │   ├── permissions.py       # RBAC permission utilities
│   │   ├── encryption.py        # Field encryption utilities
│   │   ├── rate_limit.py        # Rate limiting
│   │   └── logging.py           # Logging configuration
│   ├── exceptions/              # Custom exceptions
│   ├── jobs/                    # Background jobs
│   ├── middleware/              # Middleware components
│   │   ├── rate_limit.py        # Rate limiting middleware
│   │   ├── tenant.py            # Multi-tenancy middleware
│   │   └── transaction.py       # Transaction middleware
│   ├── models/                  # SQLAlchemy models
│   │   ├── user.py              # User model with RBAC
│   │   ├── role.py              # Role model
│   │   ├── permission.py        # Permission model
│   │   └── organization.py      # Organization model
│   ├── routers/                 # API endpoints
│   │   ├── v1/                  # API version 1
│   │   │   ├── public/          # Public endpoints
│   │   │   └── private/         # Authenticated endpoints
│   ├── schemas/                 # Pydantic schemas
│   ├── services/                # Business logic
│   └── utils/                   # Utility functions
├── tests/                       # Tests directory
├── migrations/                  # Alembic migrations
├── main.py                      # Application entry point
├── pyproject.toml               # Poetry configuration
├── alembic.ini                  # Alembic configuration
├── README.md                    # Documentation
└── .gitignore                   # Git configuration
```

## Backend Usage

### Creating a New Backend Project

```bash
# Full project with Docker and pre-commit hooks
aiplanet build project my_backend --docker --pre-commit

# Basic project
aiplanet build project my_backend

# Project with Docker only
aiplanet build project my_backend --docker

# Minimal project
aiplanet build project my_backend --minimal
```

Options:
- `--docker, -d`: Include Docker configuration (Dockerfile, docker-compose.yml)
- `--pre-commit, -p`: Include pre-commit hooks
- `--minimal, -m`: Create a minimal project

### Adding Components

```bash
# Add a service (business logic layer)
aiplanet add service user

# Add a model (SQLAlchemy database model)
aiplanet add model user

# Add a schema (Pydantic request/response schemas)
aiplanet add schema user

# Add a route (API endpoints)
aiplanet add route user

# Add a background job
aiplanet add job send_email

# Add middleware
aiplanet add middleware logging

# Add an exception class
aiplanet add exception validation
```

### Generating Complete Modules

```bash
# Generate a complete module with all components
aiplanet gen module user

# Generate with additional middleware and exception
aiplanet gen module product --with-middleware --with-exception
```

### Managing Database Migrations

```bash
# Initialize migrations (first time only)
aiplanet migrate init

# Create a new migration
aiplanet migrate create "create users table"

# Apply all pending migrations
aiplanet migrate upgrade head

# Rollback last migration
aiplanet migrate downgrade -1
```

### Running the Application

```bash
# Development server (with auto-reload)
aiplanet run dev

# Development with custom host/port
aiplanet run dev --host 0.0.0.0 --port 8080

# Production server
aiplanet run prod --workers 4

# Run with Docker
aiplanet run docker
```

---

# Frontend Commands

## Project Structure (Frontend)

The CLI generates a frontend project with the following structure:

```
my_frontend/                     # Project root
├── src/
│   ├── app/
│   │   ├── App.tsx              # Main App component
│   │   ├── providers/           # Context providers
│   │   │   ├── index.tsx        # Combined providers
│   │   │   ├── AuthProvider.tsx
│   │   │   ├── ThemeProvider.tsx
│   │   │   └── OrganizationProvider.tsx
│   │   └── routes/              # Route configuration
│   │       ├── index.tsx        # Route definitions
│   │       ├── ProtectedRoute.tsx
│   │       ├── RoleGuard.tsx
│   │       ├── PermissionGate.tsx
│   │       └── OrgGuard.tsx
│   │
│   ├── components/
│   │   ├── ui/                  # shadcn/ui components
│   │   ├── common/              # Common components
│   │   │   ├── Header.tsx
│   │   │   ├── Sidebar.tsx
│   │   │   ├── OrgSwitcher.tsx
│   │   │   ├── Loading.tsx
│   │   │   └── ErrorFallback.tsx
│   │   ├── forms/               # Form components
│   │   │   ├── FormField.tsx
│   │   │   └── FormInput.tsx
│   │   ├── tables/              # Table components
│   │   │   ├── DataTable.tsx
│   │   │   └── Pagination.tsx
│   │   └── layouts/             # Layout components
│   │       ├── MainLayout.tsx
│   │       ├── AuthLayout.tsx
│   │       └── DashboardLayout.tsx
│   │
│   ├── features/
│   │   ├── auth/                # Authentication feature
│   │   │   ├── components/
│   │   │   ├── pages/
│   │   │   └── schemas/
│   │   ├── organization/        # Organization feature
│   │   │   ├── components/
│   │   │   └── pages/
│   │   └── dashboard/           # Dashboard feature
│   │       └── pages/
│   │
│   ├── services/
│   │   ├── api/
│   │   │   ├── client.ts        # Axios instance
│   │   │   ├── interceptors.ts  # Auth & org header injection
│   │   │   └── endpoints.ts     # API endpoint constants
│   │   ├── base.service.ts      # Base CRUD service class
│   │   ├── auth.service.ts
│   │   ├── user.service.ts
│   │   └── organization.service.ts
│   │
│   ├── stores/
│   │   ├── index.ts             # Store exports
│   │   ├── auth.store.ts        # Authentication state
│   │   ├── organization.store.ts # Organization state
│   │   └── ui.store.ts          # UI state (theme, sidebar)
│   │
│   ├── hooks/
│   │   ├── useAuth.ts
│   │   ├── useOrganization.ts
│   │   ├── usePermissions.ts
│   │   ├── useDebounce.ts
│   │   └── useLocalStorage.ts
│   │
│   ├── utils/
│   │   ├── cn.ts                # Class name utility
│   │   ├── helpers.ts           # General helpers
│   │   ├── formatters.ts        # Date, currency formatters
│   │   ├── storage.ts           # LocalStorage wrapper
│   │   └── token.ts             # JWT utilities
│   │
│   ├── types/
│   │   ├── index.ts
│   │   ├── api.types.ts
│   │   ├── auth.types.ts
│   │   ├── user.types.ts
│   │   ├── organization.types.ts
│   │   └── common.types.ts
│   │
│   ├── constants/
│   │   ├── routes.ts            # Route path constants
│   │   ├── api.ts               # API endpoint constants
│   │   ├── config.ts            # App configuration
│   │   ├── roles.ts             # Role/permission constants
│   │   └── messages.ts          # UI messages
│   │
│   ├── styles/
│   │   └── globals.css          # Tailwind + custom styles
│   │
│   └── main.tsx                 # Entry point
│
├── public/
├── index.html
├── package.json
├── tsconfig.json
├── vite.config.ts
├── tailwind.config.js
├── components.json              # shadcn/ui config
├── .env.example
└── README.md
```

## Frontend Usage

### Creating a New Frontend Project

```bash
# Full project with organization/multi-tenancy support
aiplanet frontend init my_frontend

# Specify custom backend API URL
aiplanet frontend init my_frontend --api-url http://api.example.com

# Without organization features
aiplanet frontend init my_frontend --no-org

# Minimal setup
aiplanet frontend init my_frontend --minimal
```

**Full Command Example:**
```bash
# Create a frontend project called "admin-dashboard" that connects to a production API
aiplanet frontend init admin-dashboard --api-url https://api.myapp.com

# After running, follow these steps:
cd admin-dashboard
npm install
npm run dev
```

Options:
- `--api-url, -a`: Backend API URL (default: http://localhost:8000)
- `--no-org`: Disable organization/multi-tenancy features
- `--minimal`: Create minimal project without all features

### Adding a Page

```bash
# Add a page to a new feature
aiplanet frontend add page users

# Add a page to an existing feature
aiplanet frontend add page settings --feature admin
```

**Full Command Examples:**
```bash
# Create a "products" page (creates src/features/products/pages/ProductsPage.tsx)
aiplanet frontend add page products

# Create a "billing" page in the "settings" feature
aiplanet frontend add page billing --feature settings
# Creates: src/features/settings/pages/BillingPage.tsx
```

### Adding a Component

```bash
# Add a common component
aiplanet frontend add component UserAvatar

# Add a form component
aiplanet frontend add component SearchInput --type form

# Add a table component
aiplanet frontend add component UserTable --type table

# Add a layout component
aiplanet frontend add component AdminLayout --type layout

# Add to a specific feature
aiplanet frontend add component ProductCard --feature products
```

**Full Command Examples:**
```bash
# Create a common component (src/components/common/StatCard.tsx)
aiplanet frontend add component stat-card --type common

# Create a form component (src/components/forms/DatePicker.tsx)
aiplanet frontend add component date-picker --type form

# Create a component inside a feature (src/features/products/components/ProductCard.tsx)
aiplanet frontend add component product-card --feature products
```

### Adding a Service

```bash
# Add a basic service
aiplanet frontend add service product

# Add a service with full CRUD methods
aiplanet frontend add service order --crud
```

**Full Command Examples:**
```bash
# Create a basic service (src/services/product.service.ts)
aiplanet frontend add service product

# Create a CRUD service with getAll, getById, create, update, delete methods
aiplanet frontend add service order --crud
# Creates: src/services/order.service.ts with BaseService extension
```

### Adding a Store

```bash
# Add a Zustand store
aiplanet frontend add store cart
aiplanet frontend add store notifications
```

**Full Command Example:**
```bash
# Create a cart store (src/stores/cart.store.ts)
aiplanet frontend add store cart

# Don't forget to export it from src/stores/index.ts:
# export * from './cart.store'
```

### Generating a Complete Feature

```bash
# Generate a basic feature with list and detail pages
aiplanet frontend gen feature products

# Generate a feature with full CRUD (list, detail, create, edit pages + service)
aiplanet frontend gen feature orders --with-crud
```

**Full Command Examples:**
```bash
# Generate a products feature
aiplanet frontend gen feature products
# Creates:
#   src/features/products/pages/ProductsListPage.tsx
#   src/features/products/pages/ProductsDetailPage.tsx

# Generate a full CRUD feature for orders
aiplanet frontend gen feature orders --with-crud
# Creates:
#   src/features/orders/pages/OrdersListPage.tsx
#   src/features/orders/pages/OrdersDetailPage.tsx
#   src/features/orders/pages/OrdersCreatePage.tsx
#   src/features/orders/pages/OrdersEditPage.tsx
#   src/services/orders.service.ts

# After generating, add routes in src/app/routes/index.tsx:
# <Route path="/orders" element={<OrdersListPage />} />
# <Route path="/orders/new" element={<OrdersCreatePage />} />
# <Route path="/orders/:id" element={<OrdersDetailPage />} />
# <Route path="/orders/:id/edit" element={<OrdersEditPage />} />
```

### Adding shadcn/ui Components

After creating the project, add shadcn/ui components as needed:

```bash
cd my_frontend

# Add individual components
npx shadcn@latest add button
npx shadcn@latest add input
npx shadcn@latest add dialog
npx shadcn@latest add dropdown-menu
npx shadcn@latest add select
npx shadcn@latest add toast

# Add multiple components at once
npx shadcn@latest add button input dialog card
```

---

# Full-Stack Development Workflow

Here's a complete workflow to create a full-stack application:

```bash
# 1. Create the backend project
aiplanet build project my_app_backend --docker --pre-commit
cd my_app_backend

# 2. Add backend components
aiplanet gen module user --with-middleware
aiplanet gen module product
aiplanet add job send_notification

# 3. Run database migrations
aiplanet migrate init
aiplanet migrate create "initial tables"
aiplanet migrate upgrade head

# 4. Start backend server
aiplanet run dev

# 5. In a new terminal, create the frontend project
cd ..
aiplanet frontend init my_app_frontend --api-url http://localhost:8000
cd my_app_frontend

# 6. Install dependencies and add UI components
npm install
npx shadcn@latest add button input dialog card table

# 7. Generate frontend features
aiplanet frontend gen feature products --with-crud
aiplanet frontend add store cart

# 8. Start frontend dev server
npm run dev
```

---

# Component Types Reference

## Backend Components

| Type | Description | Command |
|------|-------------|---------|
| Service | Business logic services | `aiplanet add service <name>` |
| Model | SQLAlchemy database models | `aiplanet add model <name>` |
| Schema | Pydantic request/response schemas | `aiplanet add schema <name>` |
| Route | API endpoints (routers) | `aiplanet add route <name>` |
| Job | Background jobs/tasks | `aiplanet add job <name>` |
| Middleware | ASGI middleware components | `aiplanet add middleware <name>` |
| Const | Constant definitions | `aiplanet add const <name>` |
| Utils | Utility functions | `aiplanet add utils <name>` |
| Exception | Custom exception classes | `aiplanet add exception <name>` |

## Frontend Components

| Type | Description | Command |
|------|-------------|---------|
| Page | Feature pages | `aiplanet frontend add page <name>` |
| Component | Reusable UI components | `aiplanet frontend add component <name>` |
| Service | API service classes | `aiplanet frontend add service <name>` |
| Store | Zustand state stores | `aiplanet frontend add store <name>` |
| Feature | Complete feature modules | `aiplanet frontend gen feature <name>` |

---

# Environment Configuration

## Backend (.env)

```env
# Application
APP_NAME=my_app
DEBUG=true
SECRET_KEY=your-secret-key-here

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/myapp

# Redis (for rate limiting)
REDIS_URL=redis://localhost:6379

# JWT
ACCESS_TOKEN_EXPIRE_MINUTES=30
REFRESH_TOKEN_EXPIRE_DAYS=7

# Rate Limiting
RATE_LIMIT_ENABLED=true
RATE_LIMIT_PER_MINUTE=100

# Encryption
ENCRYPTION_ENABLED=false
ENCRYPTION_KEY=

# Multi-tenancy
MULTI_TENANCY_ENABLED=true
```

## Frontend (.env)

```env
# API Configuration
VITE_API_URL=http://localhost:8000
VITE_APP_NAME=My Application
```

---

# Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

## Development Setup

```bash
# Clone the repository
git clone https://github.com/aiplanet/aiplanet-cli.git
cd aiplanet-cli

# Install with Poetry
poetry install

# Run tests
poetry run pytest

# Run the CLI locally
poetry run aiplanet --help
```

---

# License

This project is licensed under the MIT License - see the LICENSE file for details.

