Metadata-Version: 2.3
Name: proto-craft
Version: 0.1.0
Summary: CLI tool for scaffolding FastAPI projects and creating modular app structures.
Author: Tins P Joseph
Author-email: Tins P Joseph <tinspj1997@gmail.com>
Requires-Dist: typer>=0.24.1
Requires-Python: >=3.12
Description-Content-Type: text/markdown

# Proto Craft

A CLI tool for rapidly creating and managing development projects with FastAPI boilerplate templates and modular app structures.

## Overview

Proto Craft streamlines the process of scaffolding new FastAPI-based projects and creating self-contained app modules within those projects. It provides automated setup with configurable Python versions and maintains a clean directory structure.

## Features

- 🚀 **Project Creation**: Clone and initialize FastAPI boilerplate projects
- 📦 **App Scaffolding**: Create modular app structures with predefined file templates
- 🔍 **Project Inspection**: Verify app structure and create missing files
- 🐍 **Python Version Control**: Support for Python 3.10 - 3.15
- 📋 **Configuration Management**: builder.ini-based project configuration

## Installation

### Prerequisites

- Python >= 3.12
- Git
- `uv` package manager (recommended)

### From Source

```bash
git clone https://github.com/tinspj1997/proto-craft.git
cd proto-craft
uv sync
```

### Install as Package

```bash
pip install proto-craft
# or with uv
uv pip install proto-craft
```

## Quick Start

### Create a New Project

```bash
proto-craft create project
```

Follow the interactive prompts:
- Enter your project name
- Specify the required Python version (3.10-3.15, default: 3.12)

The tool will:
1. Clone the FastAPI boilerplate repository
2. Remove the .git directory for a fresh start
3. Create `builder.ini` configuration
4. Set up `.python-version` file

### Navigate to Your Project

```bash
cd your-project-name
uv sync
```

### Create an App Inside the Project

```bash
proto-craft create app
```

Provide the app name when prompted. This creates:
```
src/app/your-app-name/
├── __init__.py
├── routes.py
├── schema.py
└── service.py
```

### Inspect Project Apps

Verify the structure of all apps in your project:

```bash
proto-craft inspect
```

Create missing files automatically:

```bash
proto-craft inspect --add
```

### Display Version

```bash
proto-craft version
```

## Configuration

### builder.ini

Located in the project root, contains project metadata:

```ini
[project]
name = your-project-name
version = 1.0.0
python_version = 3.12
app_path = src/app
```

- **app_path**: Directory where new apps are created (relative to project root)

### .python-version

Specifies the project's Python version for tools like `pyenv` or `uv`.

## Project Structure

```
your-project-name/
├── .python-version          # Python version specification
├── builder.ini              # Project configuration
├── src/
│   └── app/
│       └── your-app-name/   # New apps created here
│           ├── __init__.py
│           ├── routes.py
│           ├── schema.py
│           └── service.py
├── main.py
└── [other project files]
```

## Environment Variables

### PROTO_CRAFT_PASSKEY

Optional environment variable for authentication:

```bash
export PROTO_CRAFT_PASSKEY="your-passkey"
proto-craft create project
```

If not set, you'll be prompted for the passkey interactively.

## Development

### Requirements

- Python 3.12+
- Dependencies: `typer`, `rich`

### Install Development Dependencies

```bash
cd proto-craft
uv sync --all-extras
```

### Run Commands

```bash
# Development mode
uv run proto-craft --help

# Or install in editable mode
pip install -e .
proto-craft --help
```

## Troubleshooting

### builder.ini not found

Ensure you're running commands from the project root directory created by the tool.

```bash
cd /path/to/your/project
proto-craft inspect
```

### app_path not configured

Edit your `builder.ini` and verify the `[project]` section contains an `app_path` entry.

### Git clone fails

- Check your internet connection
- Verify the repository URL in `instructions.py`
- Ensure git is installed and accessible

### Python version validation error

Specify a Python version between 3.10 and 3.15:

```bash
proto-craft create project
# When prompted: Enter a version like 3.12
```

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Make your changes with proper type hints
4. Run tests (when available)
5. Submit a pull request

## License

See LICENSE file in the repository.

## Author

**Tins P Joseph**
- Email: tinspj1997@gmail.com
- GitHub: [@tinspj1997](https://github.com/tinspj1997)

## Related Projects

- [FastAPI Boilerplate](https://github.com/tinspj1997/fastapi-boilerplate) - The template used for project creation

## Support

For issues, questions, or suggestions:

- 📝 Open an issue on GitHub
- 📧 Email the author
- 💬 Check existing documentation

---

**Last Updated**: March 2025  
**Version**: 0.1.0