Metadata-Version: 2.4
Name: fabbro
Version: 0.1.0
Summary: Opinionated Python web framework CLI — scaffolding, doctor, registry, and interactive dev playbooks.
Author: Matheus Rodrigues Trindade
License-Expression: BUSL-1.1
Keywords: framework,scaffolding,cli,ai-development
Requires-Python: >=3.12
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: PyYAML>=6.0
Dynamic: license-file

# Fabbro

![PyPI](https://img.shields.io/pypi/v/fabbro?color=2b7489) ![Python](https://img.shields.io/pypi/pyversions/fabbro) ![Status](https://img.shields.io/badge/status-0.1.0%20%C2%B7%20beta-orange) ![License](https://img.shields.io/badge/license-proprietary-lightgrey)

**An opinionated Python web framework for building custom, on-demand web software fast — and for making AI-generated code production-fit: secured by default, no hardcoded secrets, built around reusable modules.**

`fabbro create` scaffolds a working project with a production-ready foundation —
authentication, an encrypted secret vault, a background worker queue, and an
external-API registry — plus a dev-only interactive playbook that walks you
through it.

---

## Install

```bash
pip install fabbro
```

Requires **Python 3.12+**.

## Quickstart

```bash
fabbro create myproject
cd myproject
fabbro secret gen              # generate SECRET_KEY / FERNET_KEY into .env
fabbro create-admin            # create the first admin user
fabbro doctor                  # run pre-flight checks
python3 _dev/serve.py          # start the playbooks, then follow Getting Started
```

---

## What you get

**Fabbro turns AI-generated code into production-fit code.** The two failure
modes of AI-written web apps — secrets and settings hardcoded into logic, and
security reinvented (badly) on every project — are designed out from the start:

- **Nothing hardcoded.** What AI usually bakes into code — passwords hashing
  cost, cookie flags, token TTLs, rate limits, CSP, role policy — lives in
  versioned **YAML config**, not in source. Change a limit, rotate a policy,
  tighten a cookie: edit `config/`, not your logic.
- **Security is reusable and already implemented.** Rate limiting, secure
  cookies, CSRF, CSP, HSTS, Argon2id — shipped once in `core/`, imported and
  never rewritten. AI extends your app through config and extension points, not
  by re-authoring the security layer each time.

The scaffolded project ships with a reusable `core/` you import but never edit:

| Area | What's in the box |
|------|-------------------|
| **Auth & sessions** | Argon2id hashing with rehash · session rotation on login · CSRF on every mutation · CSP with per-request nonce · `require_auth` / `require_role` gating · role policy in `auth.yaml` |
| **Rate limiting** | Per-route limits by IP, email, and user — all declared in `security.yaml` (`10 per minute` on login, tighter on password reset, etc.) |
| **Secure defaults** | Cookie `SameSite` + `secure`, HSTS, permissions-policy, Argon2 tuning — every value in config, none in code |
| **Secret vault** | Provider credentials encrypted at rest (Fernet) · one canonical resolution cascade (vault → `_FILE` → env) — never in source |
| **Background worker** | SQLite-backed job queue · atomic claim under a WAL lock · heartbeat reaper for crashed jobs |
| **API registry** | Register providers by OpenAPI spec, autodiscovery, or manually · bind endpoints as stable `service.verb` aliases your modules call |

---

## CLI

| Command | Purpose |
|---------|---------|
| `fabbro create <name>` | Scaffold a new project |
| `fabbro create-admin` | Create the first admin user |
| `fabbro doctor` | Run the project's pre-flight checks |
| `fabbro secret gen` | Generate base secrets into `.env` |
| `fabbro vault set·list·rm` | Manage provider API credentials |
| `fabbro registry …` | Inspect and drive the API registry |

> Run any command with `--help` for its full options.

---

## Notes for 0.1.0

A `0.x` release with a couple of **deliberate, declared gaps** — safe under the
intended single-tenant, trusted-input use, and scheduled to change as the
surface grows:

| Area | Current behavior |
|------|------------------|
| **Registry autodiscovery** | Outbound requests to a provider's `base_url` aren't yet validated against private/loopback ranges — use trusted `base_url` values. Full SSRF allowlist lands with the public-API surface. |
| **Session fingerprinting** | Sessions are bound to user-agent + IP, so a network or device change logs the user out. Intentional for now; its exact role is an open design decision. |

---

<sub>© Forjelo · Proprietary · Built for certified Fabbro developers.</sub>
