fascraft 0.4.2
A CLI for generating modular FastAPI projects with environment and dependency management
License: MIT
Requires Python: <4.0,>=3.10

# 🚀 FasCraft - FastAPI Project Generator

**Build production-ready FastAPI applications with enterprise-grade features in seconds.**

[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Code style: black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)
[![Ruff](https://img.shields.io/badge/ruff-000000.svg)](https://github.com/astral-sh/ruff)
[![Security: bandit](https://img.shields.io/badge/security-bandit-yellow.svg)](https://bandit.readthedocs.io/)

> **FasCraft** is a powerful CLI tool that generates **production-ready FastAPI projects** with domain-driven architecture, comprehensive error handling, and enterprise-grade features. Stop writing boilerplate code and start building amazing APIs!

## ✨ **Features**

### 🏗️ **Project Generation**
- **Interactive project creation** with guided setup and dry-run mode
- **Domain-driven architecture** ready for module generation
- **Essential project structure** with configuration and routing
- **Automatic backup & rollback** for safe operations
- **Graceful degradation** with fallback templates

### 🔧 **Advanced Management**
- **Project analysis** with recommendations and health checks
- **Legacy migration** to domain-driven architecture
- **Configuration management** with TOML support
- **Module generation** with multiple template types
- **Safe module removal** with automatic updates

### 🛡️ **Enterprise Features**
- **Comprehensive error handling** with actionable suggestions
- **Input validation & sanitization** for security
- **File system permission checking**
- **Disk space validation**
- **Network path validation**
- **Windows reserved name protection**

### 🎨 **Developer Experience**
- **Rich console output** with progress tracking
- **Colored error messages** with recovery guidance
- **Interactive mode** for guided project creation
- **Dry-run mode** to preview changes
- **Cross-platform compatibility** (Windows, macOS, Linux)

## 🚀 **Quick Start**

### **Installation**

```bash
# Using pip
pip install fascraft

# Using Poetry
poetry add fascraft

# From source
git clone https://github.com/yourusername/fascraft.git
cd fascraft
pip install -e .
```

### **Create Your First Project**

```bash
# Generate a new FastAPI project (interactive mode)
fascraft new

# Or specify project name directly
fascraft new my-awesome-api

# Preview changes without applying them
fascraft new my-awesome-api --dry-run

# Navigate to project
cd my-awesome-api

# Install dependencies
pip install -r requirements.txt

# Run the application
uvicorn main:app --reload
```

**That's it!** Your FastAPI application is now running at `http://localhost:8000` 🎉

## 📚 **Complete Workflow Example**

### **1. Create a New Project**
```bash
fascraft new ecommerce-api
cd ecommerce-api
```

### **2. Generate Domain Modules**
```bash
# Create user management module
fascraft generate users

# Create product catalog module
fascraft generate products

# Create order management module
fascraft generate orders
```

### **3. List and Manage Modules**
```bash
# See all modules with health status
fascraft list

# Update module templates
fascraft update users

# Remove a module safely
fascraft remove products
```

### **4. Analyze and Optimize**
```bash
# Get project analysis and recommendations
fascraft analyze

# Migrate legacy projects to domain-driven architecture
fascraft migrate ../old-project

# Manage project configuration
fascraft config show
```

## 🛠️ **Available Commands**

### **Core Commands**
| Command | Description | Example |
|---------|-------------|---------|
| `new` | Create new FastAPI project | `fascraft new my-api` |
| `generate` | Generate domain module | `fascraft generate users` |
| `list` | List all modules | `fascraft list` |
| `remove` | Remove module safely | `fascraft remove users` |
| `update` | Update module templates | `fascraft update users` |

### **Advanced Commands**
| Command | Description | Example |
|---------|-------------|---------|
| `analyze` | Analyze project structure | `fascraft analyze` |
| `migrate` | Migrate legacy projects | `fascraft migrate ../old` |
| `config` | Manage configuration | `fascraft config show` |
| `environment` | Manage environments | `fascraft environment init` |
| `dockerize` | Add Docker support | `fascraft dockerize` |
| `ci-cd` | Add CI/CD support | `fascraft ci-cd add` |
| `deploy` | Generate deployment files | `fascraft deploy generate` |

### **Utility Commands**
| Command | Description | Example |
|---------|-------------|---------|
| `dependencies` | Manage module dependencies | `fascraft dependencies show` |
| `docs` | Generate documentation | `fascraft docs generate` |
| `test` | Generate test files | `fascraft test users` |
| `list-templates` | List available templates | `fascraft list-templates` |
| `hello` | Say hello | `fascraft hello World` |
| `version` | Show version | `fascraft version` |
| `--help` | Show help | `fascraft --help` |

## 🏗️ **Generated Project Structure**

```
my-awesome-api/
├── 📁 config/                 # Configuration management
│   ├── __init__.py
│   ├── settings.py           # App settings with Pydantic
│   ├── database.py           # Database configuration
│   ├── exceptions.py         # Custom exceptions
│   └── middleware.py         # FastAPI middleware
├── 📁 routers/               # API routing
│   ├── __init__.py
│   └── base.py              # Base router with health checks
├── 📄 main.py                # FastAPI application
├── 📄 pyproject.toml         # Poetry configuration
├── 📄 requirements.txt       # Production dependencies
├── 📄 requirements.dev.txt   # Development dependencies
├── 📄 requirements.prod.txt  # Production dependencies
├── 📄 .env                   # Environment variables
├── 📄 .env.sample           # Environment template
├── 📄 .gitignore            # Git ignore patterns
├── 📄 README.md             # Project documentation
└── 📄 fascraft.toml         # FasCraft configuration
```

## 🔧 **Configuration Management**

### **Project Configuration (`fascraft.toml`)**
```toml
[project]
name = "my-awesome-api"
version = "0.1.0"
description = "A FastAPI project generated with FasCraft"

[router]
base_prefix = "/api/v1"
health_endpoint = true

[database]
default = "sqlite"
supported = ["sqlite", "postgresql", "mysql", "mongodb"]

[modules]
auto_import = true
prefix_strategy = "plural"
test_coverage = true
```

### **Environment Configuration (`.env`)**
```bash
# Database Configuration
DATABASE_URL=sqlite:///./my-awesome-api.db

# Security
SECRET_KEY=your-secret-key-here
ACCESS_TOKEN_EXPIRE_MINUTES=30

# CORS
CORS_ORIGINS=["*"]
CORS_ALLOW_CREDENTIALS=true
```

## 🚀 **Advanced Features**

### **Interactive Mode**
FasCraft provides an interactive, guided experience for project creation:

```bash
# Start interactive mode
fascraft new

# Follow the guided prompts:
# 1. Enter project name
# 2. Choose project path
# 3. Select project type
# 4. Choose features to include
# 5. Confirm and create
```

### **Dry-Run Mode**
Preview all changes before applying them:

```bash
# See what will be created without making changes
fascraft new my-api --dry-run

# Review project structure, files, and content
# Perfect for understanding what FasCraft will generate
```

### **Automatic Backup & Rollback**
FasCraft automatically creates backups before destructive operations and provides rollback functionality if anything goes wrong.

```bash
# FasCraft automatically creates a backup
fascraft migrate ../legacy-project

# If migration fails, rollback is automatic
# Your original project is safe!
```

### **Comprehensive Error Handling**
Every error includes actionable suggestions and recovery guidance.

```bash
# Clear error messages with solutions
❌ Error: Project 'test' already exists at ./test
💡 Suggestion: Use a different project name or remove the existing directory
```

### **Environment Management**
FasCraft provides comprehensive environment management for multi-environment deployments:

```bash
# Initialize environment management
fascraft environment init --environments "dev,staging,prod"

# Switch between environments
fascraft environment switch --environment dev
fascraft environment switch --environment prod

# Validate configurations
fascraft environment validate

# List all environments
fascraft environment list-envs
```

**Features:**
- 🌍 **Multi-environment support** (dev, staging, prod, testing)
- 🔄 **Seamless environment switching**
- ✅ **Configuration validation**
- 📝 **Environment-specific settings**
- 🏗️ **Enhanced configuration management**

### **Cross-Platform Compatibility**
Tested and verified on:
- ✅ **Windows 10/11** (PowerShell, CMD)
- ✅ **macOS 12+** (Terminal, bash, zsh)
- ✅ **Linux** (Ubuntu, CentOS, RHEL)

## 📖 **API Endpoints**

### **Health Check**
```http
GET /api/v1/health
```

**Response:**
```json
{
  "status": "healthy",
  "version": "0.1.0"
}
```

### **Root Endpoint**
```http
GET /
```

**Response:**
```json
{
  "message": "Hello from my-awesome-api!"
}
```

## 🧪 **Testing**

### **Run Tests**
```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=fascraft

# Run specific test file
pytest tests/test_new_command.py
```

### **Test Coverage**
FasCraft maintains comprehensive test coverage with 18 test files covering:
- ✅ CLI command functionality
- ✅ Template rendering
- ✅ Error handling
- ✅ Validation systems
- ✅ Integration scenarios

## 🔒 **Security Features**

### **Input Validation**
- **Project name sanitization** - Prevents malicious input
- **Path validation** - Protects against path traversal attacks
- **Character filtering** - Removes unsafe characters
- **Length limits** - Prevents buffer overflow attacks

### **File System Security**
- **Permission checking** - Validates write access
- **Disk space validation** - Prevents disk exhaustion
- **Network path validation** - Secure remote operations

### **Dependency Security**
- **Bandit integration** - Security vulnerability scanning
- **Safety checks** - Dependency vulnerability detection
- **Version pinning** - Secure dependency versions

## 🚀 **Deployment**

### **Development**
```bash
# Install development dependencies
pip install -r requirements.dev.txt

# Run with auto-reload
uvicorn main:app --reload --host 0.0.0.0 --port 8000
```

### **Production**
```bash
# Install production dependencies
pip install -r requirements.prod.txt

# Run with Gunicorn
gunicorn main:app -w 4 -k uvicorn.workers.UvicornWorker
```

### **Docker Support**
```bash
# Add Docker support to existing project
fascraft dockerize

# This generates:
# - Dockerfile
# - docker-compose.yml
# - .dockerignore
# - Database initialization scripts
```

## 🛠️ **Development**

### **Prerequisites**
- Python 3.10+
- Poetry (recommended) or pip
- Git

### **Setup Development Environment**
```bash
# Clone repository
git clone https://github.com/yourusername/fascraft.git
cd fascraft

# Install dependencies
poetry install

# Install pre-commit hooks
pre-commit install

# Run tests
poetry run pytest
```

### **Code Quality Tools**
- **Black** - Code formatting
- **Ruff** - Linting and import sorting
- **isort** - Import organization
- **Bandit** - Security scanning
- **Safety** - Dependency vulnerability checks

## 📚 **Documentation**

### **Getting Started**
- [📖 Documentation Overview](docs/README.md) - Navigate all documentation
- [🚀 Quick Start Guide](docs/getting-started/quickstart.md) - Get up and running in minutes

### **User Guides**
- [🏗️ Project Generation](docs/user-guides/project-generation.md) - Create new FastAPI projects
- [🔧 Module Management](docs/user-guides/module-management.md) - Add and manage project modules
- [⚙️ Configuration](docs/user-guides/configuration.md) - Manage application settings
- [🔄 Migrations](docs/user-guides/migration.md) - Database schema changes

### **Troubleshooting & Support**
- [🔧 Troubleshooting Guide](docs/troubleshooting/troubleshooting.md) - Solve common issues
- [🤝 Community Support](docs/community/community-support.md) - Get help and contribute

### **Deployment & Production**
- [🐳 Docker Integration](docs/deployment/docker.md) - Containerize applications
- [🚀 CI/CD Integration](docs/deployment/ci-cd.md) - Automated workflows
- [🌍 Environment Management](docs/deployment/environment-management.md) - Manage environments
- [✅ Production Ready](docs/deployment/production-ready.md) - Production checklist

### **Developer Resources**
- [💻 Contributing Guidelines](CONTRIBUTING.md) - How to contribute
- [🧪 Testing Guide](docs/development/testing.md) - Testing strategies
- [⚠️ Error Handling](docs/development/error-handling.md) - Error handling patterns

### **Examples**
- [Basic API](examples/basic-api/) - Simple CRUD operations
- [E-commerce API](examples/ecommerce-api/) - Business logic examples
- [Authentication API](examples/auth-api/) - Security and user management
- [Database Integration](examples/database-api/) - ORM and database patterns

## 🤝 **Contributing**

We welcome contributions! Please see our [Contributing Guidelines](CONTRIBUTING.md) for details.

### **Development Setup**
```bash
# Fork and clone
git clone https://github.com/yourusername/fascraft.git
cd fascraft

# Create feature branch
git checkout -b feature/amazing-feature

# Make changes and test
poetry run pytest

# Commit and push
git commit -m "Add amazing feature"
git push origin feature/amazing-feature

# Create pull request
```

### **Code Standards**
- Follow PEP 8 style guidelines
- Use type hints for all functions
- Write comprehensive docstrings
- Maintain test coverage above 80%
- Run all quality checks before committing

## 📄 **License**

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## 🙏 **Acknowledgments**

- **FastAPI** - The amazing web framework that makes this possible
- **Typer** - CLI framework for building great command-line interfaces
- **Rich** - Rich text and beautiful formatting in the terminal
- **Jinja2** - Template engine for code generation
- **Pydantic** - Data validation using Python type annotations

## 📞 **Support**

### **Getting Help**
- 📖 [Documentation](docs/README.md) - Comprehensive guides and tutorials
- 🐛 [Issue Tracker](https://github.com/yourusername/fascraft/issues) - Report bugs and request features
- 💬 [Discussions](https://github.com/yourusername/fascraft/discussions) - Community Q&A
- 📧 [Email Support](mailto:support@fascraft.dev) - Direct support

### **Community**
- 🌐 [Website](https://fascraft.dev) - Project website and resources
- 🐦 [Twitter](https://twitter.com/fascraft) - Updates and announcements
- 💻 [Discord](https://discord.gg/fascraft) - Real-time community support
- 📺 [YouTube](https://youtube.com/fascraft) - Video tutorials and demos

---

**Made with ❤️ by the FasCraft Team**

**FasCraft** - Building better FastAPI projects, one command at a time! 🚀