Metadata-Version: 2.4
Name: fracode
Version: 0.1.5
Summary: Stack-based scaffolding tool for application projects
License-Expression: MIT
License-File: LICENSE.md
Author: chidi e
Author-email: hello@chidiesobe.com
Requires-Python: >=3.12
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: jinja2 (>=3.1.6,<4.0.0)
Requires-Dist: typer (>=0.19.2,<0.20.0)
Requires-Dist: uvicorn (>=0.37.0,<0.38.0)
Description-Content-Type: text/markdown

# FraCode

[![CI](https://github.com/iamceeso/FraCode/actions/workflows/ci.yml/badge.svg)](https://github.com/iamceeso/FraCode/actions/workflows/ci.yml)
[![codecov](https://codecov.io/gh/iamceeso/FraCode/branch/main/graph/badge.svg)](https://codecov.io/gh/iamceeso/FraCode)
[![Python Version](https://img.shields.io/badge/python-3.12%2B-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

FraCode is a stack-based scaffolding tool.

It generates application projects that use official ecosystem libraries directly, starting with a standalone FastAPI stack today and leaving room for other languages and frameworks over time.

## What FraCode Is

FraCode is not trying to replace FastAPI.

FraCode is meant to help you start faster by generating:

- a clean project layout
- stack-aware scaffolds
- file generators for common app pieces
- lightweight development commands
- code you can fully own after generation

The guiding rule is simple:

- zero `import fracode` in generated application code
- zero FraCode runtime dependency in generated projects
- official framework and library imports only

FraCode builds the house, then gets out of the way.

## Available Stacks

Current built-in stack:

- `python/fastapi` - standalone FastAPI application with typed settings, SQLAlchemy, Alembic, Docker, and pytest

List stacks with:

```bash
fra stacks
```

## Quick Start

```bash
pip install fracode

fra new my-app --language python --framework fastapi
cd my-app

poetry install
fra serve
```

Then open `http://127.0.0.1:8000/docs`.

You can also run the generated app directly:

```bash
python dev.py
```

## What The FastAPI Stack Generates

The default FastAPI scaffold produces a normal project structure like:

- `app/main.py` - FastAPI entrypoint
- `app/api/routes.py` - route registration and healthcheck
- `app/core/config.py` - typed settings
- `app/core/errors.py` - project-owned exception handlers
- `app/core/logging.py` - project-owned logging setup
- `app/db/` - SQLAlchemy base and session helpers
- `app/schemas/` - Pydantic schemas
- `migrations/` and `alembic.ini` - migration support
- `Dockerfile` and `docker-compose.yml` - container setup
- `tests/` - starter test suite
- `dev.py` - local dev runner

This is application code, not a FraCode runtime wrapper.

## CLI

Core commands:

- `fra new <name>` creates a new project from a stack
- `fra stacks` lists available language/framework stacks
- `fra serve` runs a generated app by detecting `app/main.py` or `main.py`
- `fra make:controller <Name>` generates a stack-aware controller and schema
- `fra make:model <Name>` generates a stack-aware model

Examples:

```bash
fra new blog --language python --framework fastapi
fra make:controller User --api
fra make:model User
```

For the FastAPI stack, controller generation also wires the new controller into `app/api/routes.py` and creates a matching schema module in `app/schemas/`.

## Development

```bash
poetry install --with dev
pytest
ruff check fracode/ tests/
ruff format --check fracode/ tests/
mypy fracode/
```

## Multi-Stack Direction

FraCode is built around stack discovery instead of one framework-specific runtime.

The intended shape is:

- `templates/stacks/<language>/<framework>/...`
- each stack defines its own metadata and generators
- the CLI discovers stacks dynamically
- generated apps stay native to their own ecosystem

That means FraCode can grow toward things like:

- `python/flask`
- `typescript/express`
- `go/chi`

without forcing those ecosystems through one shared abstraction layer.

## Contributing

Contributions are  welcome:

- new stack support
- better project templates
- generator ergonomics
- documentation
- stronger day-zero scaffolds for real app work

## License

FraCode is open-source software licensed under the [MIT license](LICENSE).

