Exosmith

An interactive command-line tool that generates production-ready full-stack project structures with best practices built-in.

Features

• 🚀 Interactive CLI - User-friendly prompts guide you through project setup
• 🎯 Multiple Languages - Support for Python, JavaScript, Java, Ruby, and Go
• 🏗️ Framework Templates - Pre-configured templates for popular frameworks
• 🐳 Docker Ready - Includes Dockerfile and docker-compose.yml
• 🔄 CI/CD Integration - Optional GitHub Actions workflows
• 🧪 Testing Setup - Pre-configured test frameworks and example tests
• 📝 Documentation - Auto-generated README with setup instructions
• 🔧 Development Tools - Git, pre-commit hooks, linting, and formatting

Supported Stacks

Backend Frameworks

• Python: Django, Flask, FastAPI
• JavaScript/TypeScript: Express (TypeScript), Next.js 14 (App Router)
• Java: Spring Boot
• Ruby: Rails
• Go: Standard HTTP library

Databases

• PostgreSQL
• MySQL
• MongoDB
• SQLite
• None (API only)

Frontend Frameworks (Optional)

• React
• Vue
• Angular
• Svelte
• None (backend only)

Installation

Prerequisites

• Python 3.8 or higher
• pip (Python package manager)

Method 1: Install Globally (Recommended)

Install Exosmith so you can run it from anywhere on your system:

# Navigate to the Exosmith directory
cd C:\Users\YourUsername\Desktop\exosmith

# Install in editable mode
pip install -e .

# Now run from anywhere
exosmith

After installation, you can run exosmith from any directory on your computer.

Method 2: Using Launcher Scripts

If you prefer not to install globally, use the provided launcher scripts:

Windows:

cd C:\Users\YourUsername\Desktop\exosmith
exosmith.bat

Linux/Mac:

cd /path/to/exosmith
chmod +x exosmith.sh
./exosmith.sh

Method 3: Direct Python Execution

Run the script directly without installation:

cd C:\Users\YourUsername\Desktop\exosmith
python scaffold.py

Verify Installation

Test that everything is working:

# Run the test suite
pytest tests/ -v

# Run installation verification
python test_installation.py

You should see: 110 passed ✅

Uninstall

To remove Exosmith from your system:

Windows:

uninstall.bat

Linux/Mac:

./uninstall.sh

Or manually:

pip uninstall exosmith

Reinstall

To reinstall Exosmith:

Windows:

reinstall.bat

Linux/Mac:

./reinstall.sh

For detailed installation instructions, see INSTALL.md

Usage

Interactive Mode

Simply run Exosmith and follow the prompts:

# If installed globally
exosmith

# Or using launcher script (Windows)
exosmith.bat

# Or direct execution
python scaffold.py

The tool will guide you through:

1. Selecting a programming language
2. Choosing a backend framework
3. Selecting a database
4. Choosing an optional frontend framework
5. Configuring project settings (name, ports, etc.)
6. Enabling optional features (Git, CI/CD, pre-commit hooks)

Command-Line Options

# Show help
exosmith --help

# Use custom plugin directory
exosmith --plugin-dir ./my-plugins

# Enable verbose output
exosmith --verbose

# Show version
exosmith --version

Example

$ exosmith

╔═══════════════════════════════════════════════════════════╗
║                                                           ║
║                      EXOSMITH                             ║
║   Interactive Full-Stack Project Scaffolding CLI         ║
║                                                           ║
║   Generate production-ready project structures           ║
║   with best practices built-in                           ║
║                                                           ║
╚═══════════════════════════════════════════════════════════╝

Select a programming language:
--------------------------------------------------
  1. go
  2. java
  3. javascript
  4. python
  5. ruby
--------------------------------------------------
Select an option [1-5]: 4

Select a python backend framework:
--------------------------------------------------
  1. Django
  2. FastAPI
  3. Flask
--------------------------------------------------
Select an option [1-3]: 2

...

Generated Project Structure

The scaffolder generates a complete project structure:

my-project/
├── .env.example          # Environment variables template
├── .env                  # Your environment configuration
├── .gitignore            # Git ignore patterns
├── .pre-commit-config.yaml  # Pre-commit hooks (optional)
├── Dockerfile            # Docker container definition
├── docker-compose.yml    # Docker Compose configuration
├── README.md             # Project documentation
├── app.py                # Main application file
├── requirements.txt      # Python dependencies (or equivalent)
├── tests/                # Test directory
│   └── test_health.py    # Example tests
└── .github/              # CI/CD workflows (optional)
    └── workflows/
        └── ci.yml

Plugin System

The scaffolder supports custom templates through a plugin system:

Creating a Custom Template

1. Create a directory structure:

   my-plugins/
   └── {language}/
       └── {framework}/
           ├── app.py.j2
           ├── Dockerfile.j2
           └── ...
   

2. Use Jinja2 template syntax for variables:

   # app.py.j2
   from flask import Flask
   
   app = Flask("{{ project_name }}")
   
   @app.route('/health')
   def health():
       return {'status': 'healthy'}
   
   if __name__ == '__main__':
       app.run(port={{ port }})

3. Use the plugin directory:

   exosmith --plugin-dir ./my-plugins

Development

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=. --cov-report=html

# Run property-based tests
pytest tests/property/

# Run specific test file
pytest tests/test_orchestrator.py -v

Project Structure

fullstack-scaffolder/
├── cli/                  # CLI interface components
│   ├── prompt.py         # Interactive prompts
│   └── example_usage.py  # Usage examples
├── core/                 # Core business logic
│   ├── models.py         # Data models
│   ├── orchestrator.py   # Workflow orchestration
│   ├── registry.py       # Template registry
│   ├── renderer.py       # Template rendering
│   ├── validators.py     # Input validation
│   └── file_generator.py # File system operations
├── templates/            # Built-in framework templates
│   ├── python/
│   ├── javascript/
│   ├── java/
│   ├── ruby/
│   └── go/
├── tests/                # Test suite
│   ├── property/         # Property-based tests
│   └── ...
├── scaffold.py           # Main CLI entry point
├── setup.py              # Package configuration
└── README.md             # This file

Requirements

• Python 3.8 or higher
• pip (Python package manager)

Dependencies

All dependencies are automatically installed when you run pip install -e .:

• jinja2>=3.0.0 - Template engine
• hypothesis>=6.0.0 - Property-based testing
• pytest>=7.0.0 - Testing framework

See requirements.txt for the complete list.

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Run tests (pytest)
5. Commit your changes (git commit -m 'Add amazing feature')
6. Push to the branch (git push origin feature/amazing-feature)
7. Open a Pull Request

Development Guidelines

• Follow PEP 8 style guidelines
• Write tests for new features
• Update documentation as needed
• Ensure all tests pass before submitting PR

Architecture

The scaffolder follows a modular architecture:

• CLI Layer: Interactive prompts and user input
• Orchestration Layer: Workflow coordination
• Registry Layer: Template discovery and management
• Rendering Layer: Jinja2 template processing
• File System Layer: Project generation and file operations

See the design document for detailed architecture information.

Testing

The project uses both unit testing and property-based testing:

• Unit Tests: Verify specific functionality and edge cases
• Property Tests: Verify universal properties across all inputs using Hypothesis

All correctness properties are documented in the design document.

License

MIT License - see LICENSE file for details.

Support

• 📖 Documentation
• 🐛 Issue Tracker
• 💬 Discussions

Acknowledgments

Built with:

• Jinja2 - Template engine
• Hypothesis - Property-based testing
• pytest - Testing framework

Roadmap

• Additional framework support (NestJS, Laravel, etc.)
• Database migration templates
• API documentation generation (OpenAPI/Swagger)
• Kubernetes deployment configurations
• Cloud provider templates (AWS, GCP, Azure)
• Microservices architecture templates
• GraphQL API templates

---

Made with ❤️ by developers, for developers.