flaskion 2.0.0a1__tar.gz

flaskion-2.0.0a1/MANIFEST.in

@@ -0,0 +1,6 @@
+recursive-include flaskion_cli/cli_templates *
+recursive-include flaskion_cli/flaskion_template *
+recursive-include docs *.md
+recursive-include examples *.py *.md
+recursive-include tests *.py
+global-exclude *.py[cod] .DS_Store

flaskion-2.0.0a1/PKG-INFO

@@ -0,0 +1,215 @@
+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)

flaskion-2.0.0a1/README.md

@@ -0,0 +1,194 @@
+# 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)