Metadata-Version: 2.4
Name: flaskion
Version: 2.0.0a1
Summary: An opinionated application framework and scaffolder for Flask
Author-email: Graham Patrick <graham@skyaisoftware.com>
Project-URL: Homepage, https://github.com/GrahamMorbyDev/flaskion
Project-URL: Issues, https://github.com/GrahamMorbyDev/flaskion/issues
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: click>=8.1
Requires-Dist: flask>=3.1
Requires-Dist: jinja2>=3.1
Provides-Extra: mcp
Requires-Dist: fastmcp<5,>=4; extra == "mcp"

# Flaskion

Flaskion is a Laravel-inspired application framework and project scaffolder for Flask. The `2.0.0a1` runtime adds a small interface-independent use-case boundary while retaining the Flask project generators from Phase 1.

Flaskion 2 is being designed as an AI-native application framework. The
generic Task List uses Flaskion's optional MCP API as a third adapter beside
HTTP and CLI; authentication and remote deployment integration remain future
work.

## Current features

- Flask application factory and explicit extension initialization
- `flaskion.Application` for registering and invoking plain Python use cases
- Constructor-based service and repository dependencies without a DI container
- Optional `flaskion.mcp` API backed by FastMCP 4
- Local stdio and remote Streamable HTTP serving with MCP test support
- Separate web and JSON API blueprints
- SQLite, MySQL, or PostgreSQL project configuration
- SQLAlchemy and Flask-Migrate
- Conflict-safe model, controller, schema, resource, and authentication generators
- Session authentication scaffold with CSRF-protected forms
- Cross-platform virtual-environment invocation

## Installation

```bash
pipx install flaskion
# or
pip install flaskion
# Optional MCP adapter support
pip install "flaskion[mcp]"
```

Flaskion requires Python 3.11 or newer. The core package and optional MCP
integration share the same supported Python floor.

## Create a project

```bash
flaskion make:new myproject --db=sqlite
cd myproject
source .venv/bin/activate
flask run
```

On Windows, activate the environment with `.venv\Scripts\activate`.

Use `--db=mysql` or `--db=postgres` to install and configure the matching SQLAlchemy driver. Use `--no-install` to create files without creating an environment or installing dependencies.

The default creation flow:

1. builds the project in a staging directory;
2. writes a random development secret and a database URL to `.env`;
3. initializes Git;
4. creates `.venv` and installs dependencies;
5. initializes the Alembic migration repository;
6. moves the complete project into its final directory.

If a setup command fails, Flaskion reports the command and removes the incomplete staging directory.

## Generated project structure

```text
myproject/
├── app/
│   ├── __init__.py           # Application factory
│   ├── application.py        # Interface-independent use-case registration
│   ├── config.py             # Environment-backed configuration
│   ├── extensions.py         # Unbound Flask extensions
│   ├── controllers/
│   ├── models/
│   ├── routes/
│   ├── schemas/
│   ├── static/
│   └── templates/
├── migrations/               # Created by `flask db init`
├── .env.example
├── requirements.txt
└── run.py
```

## Commands

| Command | Description |
|---|---|
| `flaskion make:new NAME` | Create a project; accepts `--db` and `--no-install` |
| `flaskion make:model NAME` | Create and explicitly register a SQLAlchemy model |
| `flaskion make:schema NAME` | Create a Marshmallow SQLAlchemy schema |
| `flaskion make:controller NAME` | Create a web controller; accepts `--api` for JSON stubs |
| `flaskion make:resource NAME` | Atomically create model, controller, schema, and routes; accepts `--api` |
| `flaskion make:auth` | Create session authentication and CSRF-protected templates |

Generators refuse to overwrite existing files. Multi-file generation is planned before writing, so a conflict does not leave a partially changed project. Names such as `CardGrader`, `card-grader`, and `card_grader` normalize to consistent Python module and class names.

Generated API controller methods return explicit `501 Not Implemented` JSON until application behavior is supplied. Flaskion does not generate pretend persistence logic.

## Database migrations

The normal project-creation flow runs `flask db init`. Create and apply revisions with:

```bash
flask db migrate -m "Initial schema"
flask db upgrade
```

When a project is created with `--no-install`, install its dependencies and run `flask db init` yourself before creating the first revision.

## Authentication scaffold

```bash
flaskion make:auth
```

This creates a user model, schema, controller, and login/register/dashboard templates. Forms carry Flask-WTF CSRF tokens, login clears prior session data, passwords must contain at least 12 characters, and logout is POST-only.

This remains starter authentication, not a complete identity product. Production applications still need requirements appropriate to their threat model, such as email verification, password reset, rate limiting, secure-cookie deployment settings, and authorization policies.

## Development

Install the development dependency group with a compatible environment manager, then run:

```bash
python -m unittest discover -v
ruff check .
python -m build
```

When running directly from a source checkout with the `src/` layout, use an editable install or set `PYTHONPATH=src:.`.

## Runtime usage

Use cases do not inherit from Flaskion classes. Register a plain function, bound service method, or callable object against any message type:

```python
from dataclasses import dataclass

from flaskion import Application


@dataclass(frozen=True)
class Greet:
    name: str


application = Application()
application.register(Greet, lambda message: f"Hello, {message.name}")

assert application.handle(Greet("Ada")) == "Hello, Ada"
```

The decorator form `@application.use_case(Greet)` is available but optional. Services and repository protocols are application-owned; Flaskion does not require base classes or a universal repository abstraction.

## Task List example

The canonical example is under [`examples/task_list`](examples/task_list). It implements create, list, and complete through one `TaskService`, a repository protocol, and a SQLite adapter. HTTP, CLI, and MCP receive the same `Application` instance and invoke the same handlers.

```bash
PYTHONPATH=src:. flask --app examples.task_list.run run
PYTHONPATH=src:. python -m examples.task_list.cli create "Write documentation"
PYTHONPATH=src:. python -m examples.task_list.cli list
PYTHONPATH=src:. python -m examples.task_list.cli complete 1
PYTHONPATH=src:. flaskion mcp:serve --app examples.task_list.mcp_server:mcp
```

Install the MCP adapter with `pip install -e '.[mcp]'`. MCP remains optional:
FastMCP is imported only by
`flaskion.mcp`'s private compatibility boundary, never by Task List code.

For a remotely connectable development endpoint, use Streamable HTTP:

```bash
PYTHONPATH=src:. flaskion mcp:serve \
  --app examples.task_list.mcp_server:mcp \
  --transport http --host 127.0.0.1 --port 8000
```

The MCP endpoint is `http://127.0.0.1:8000/mcp`. Inspect it locally with:

```bash
npx -y @modelcontextprotocol/inspector --web http://127.0.0.1:8000/mcp
```

Loopback is the safe default. Binding to a public interface exposes an
unauthenticated MCP endpoint until Flaskion's remote authentication boundary is
implemented; use network controls and do not treat the development command as
a production deployment configuration.

The example intentionally does not include jobs, events, authentication policy, generic middleware, or a dependency-injection container.

## Architecture documents

- [Flaskion 2 architecture](docs/FLASKION_2_ARCHITECTURE.md)
- [Flaskion 2 roadmap](docs/FLASKION_2_ROADMAP.md)
- [MCP architecture](docs/MCP_ARCHITECTURE.md)
