supython 0.1.9__tar.gz → 0.1.11__tar.gz

{supython-0.1.9 → supython-0.1.11}/.gitignore

@@ -29,7 +29,8 @@ dev-app/backups/
 dev-app/__pycache__/
 dev-app/functions/__pycache__/
 dev-app/.tmp/
-
+dev-app/
+examples/
 .references/
 .references/*.md
 .claude/
@@ -43,3 +44,10 @@ ts-sdk/*.log
 .tmp/
 
 admin-ui/node_modules/
+
+/.supython/secrets/
+/.supython/secrets.json
+/.supython/jwt_private.pem
+/.supython/keys/
+/.supython/keyset.json
+/.supython/jwks.json

{supython-0.1.9 → supython-0.1.11}/CHANGELOG.md

@@ -2,8 +2,7 @@
 
 All notable changes to supython are recorded here. The format follows
 [Keep a Changelog](https://keepachangelog.com/en/1.1.0/) and the
-project uses **ZeroVer** (`0.x.y`) — see `docs/PROJECT.md` §14.0 for
-what counts as a breaking change. There is no scheduled `1.0.0`; treat
+project uses **ZeroVer** (`0.x.y`). There is no scheduled `1.0.0`; treat
 every `MINOR` as a potential breaking release.
 
 Categories used per release:
@@ -31,6 +30,71 @@ Each entry links the relevant `PROJECT.md` section and decision-log row
 
 ---
 
+## [0.1.11] — 2026-06-13
+
+Project-initialization ergonomics. `supython init` now produces a project that
+boots with no manual setup.
+
+### Breaking
+
+- `supython init` arguments changed. The first argument is now the **importable
+  package name** (still required); the optional second argument is the **target
+  directory** (Django-style — `.` for the current directory), defaulting to
+  `./<name>`. The `--here` flag is **removed**: `supython init myapp --here`
+  becomes `supython init myapp .`.
+- The scaffolded `jobs.py` and `hooks.py` single-file seeds are replaced by
+  auto-discovered **packages** `<name>/jobs/` and `<name>/hooks/`. Every module
+  inside each package is imported at boot, so jobs and hooks can be split across
+  files. `EXTENSIONS` in `settings.py` now points at the packages (`<name>.jobs`,
+  `<name>.hooks`) rather than the old modules.
+
+### Added
+
+- `supython init` generates a ready-to-run, gitignored `.env` (from the example
+  template) so the stack boots without a manual `cp .env.example .env` step.
+- `supython init` generates a `pyproject.toml` that declares the project and
+  pins the installed supython version; install the scaffold with `pip install -e .`.
+- The scaffold seeds an example edge function (`functions/hello.py`) and an
+  example application migration (`migrations/0001_create_todos.sql`).
+
+### Changed
+
+- Re-running `supython init` is now a safe top-up: existing files are skipped,
+  not overwritten, unless `--force` is passed.
+- The generated JWT keypair and signing secrets under `.supython/` are **never**
+  overwritten — not even with `--force` — to avoid silently rotating keys and
+  invalidating live tokens, sessions, and signed URLs. Rotation has dedicated
+  homes: `supython keygen` and `supython secret rotate`.
+- The scaffolded `todos` table moved out of supython's framework migrations into
+  the project's own `migrations/`. `supython migrate` applies only supython's
+  framework schemas (auth, storage, realtime, jobs); apply your application
+  migrations with a tool of your choice (dbmate recommended).
+
+---
+
+## [0.1.10] — 2026-06-12
+
+### Added
+
+- `python-dotenv` is now a direct dependency (previously only transitive via
+  `pydantic-settings`), backing the new boot-time `.env` export.
+
+### Fixed
+
+- `.env` is now exported into `os.environ` at the start of every boot path
+  (`create_app`, `supython worker run`, CLI subcommands) via the shared
+  `settings.export_env_file()` helper, **before** extensions load. Previously
+  pydantic-settings loaded `.env` into the typed `Settings` model only, so
+  dynamically-named secrets read via `os.environ.get(<name>)` (the `secret_ref`
+  convention) resolved to `None` under `supython dev` / `worker run` / CLI —
+  working in containers only because docker-compose's `env_file:` injected
+  `.env` first. The export uses `override=False`, so real environment variables
+  set by an orchestrator always win, and the path is sourced from the same
+  `SettingsConfigDict.env_file`. Downstream apps can delete their ad-hoc
+  `load_dotenv()` boot shims. (#1)
+
+---
+
 ## [0.1.9] — 2026-05-29
 
 ### Fixed
@@ -234,5 +298,7 @@ v0.1–v0.7 plus a v1.1.x admin track; see §19 decision log
 ---
 
 
+[0.1.11]: https://github.com/Tkeby/supython/releases/tag/v0.1.11
+[0.1.10]: https://github.com/Tkeby/supython/releases/tag/v0.1.10
 [0.1.9]: https://github.com/Tkeby/supython/releases/tag/v0.1.9
 [0.1.0]: https://github.com/Tkeby/supython/releases/tag/v0.1.0

{supython-0.1.9 → supython-0.1.11}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: supython
-Version: 0.1.9
+Version: 0.1.11
 Summary: A lightweight Postgres-first BaaS framework for Python
 Project-URL: Homepage, https://github.com/Tkeby/supython
 Project-URL: Repository, https://github.com/Tkeby/supython
@@ -35,6 +35,7 @@ Requires-Dist: itsdangerous>=2.2
 Requires-Dist: pydantic-settings>=2.6
 Requires-Dist: pydantic>=2.9
 Requires-Dist: pyjwt[crypto]>=2.10
+Requires-Dist: python-dotenv>=1.0
 Requires-Dist: python-multipart>=0.0.20
 Requires-Dist: typer>=0.15
 Requires-Dist: uvicorn[standard]>=0.32
@@ -152,20 +153,25 @@ python -m venv .venv && source .venv/bin/activate
 pip install supython
 
 # 2. scaffold a new project
+#    `myapp` is the importable package name. An optional second argument
+#    sets the target dir (`.` = current dir); it defaults to ./myapp.
 supython init myapp
 cd myapp
-cp .env.example .env
-# Review .env — at minimum confirm AUTHENTICATOR_PASSWORD matches
-# the value PostgREST will use (docker-compose.yml injects it via env).
+# install the project (and supython, pinned in the generated pyproject.toml)
+pip install -e .
 #
-# The scaffold creates:
-#   manage.py         — Optional CLI entrypoint (sets SUPYTHON_SETTINGS_MODULE)
+# The scaffold generates a ready-to-run, gitignored .env plus a JWT keypair
+# and signing secrets under .supython/ — no manual edits needed to boot.
+# It also creates:
+#   pyproject.toml    — declares this project, pins the supython version
 #   myapp/settings.py — declare EXTENSIONS, EXTRA_ROUTERS, EXTRA_MIDDLEWARE
-#   myapp/jobs.py     — example @job seed (register your background jobs here)
-#   myapp/hooks.py    — example @on("signup") seed (lifecycle hooks)
+#   myapp/jobs/       — package of @job / @cron modules (all auto-imported)
+#   myapp/hooks/      — package of @on(...) lifecycle hooks (all auto-imported)
 #   myapp/asgi.py     — optional entrypoint for uvicorn/gunicorn
+#   functions/hello.py            — example edge function (GET /functions/hello)
+#   migrations/0001_create_todos.sql — example app migration (apply with dbmate)
 
-# 3. boot Postgres + PostgREST and run migrations (one command)
+# 3. boot Postgres + PostgREST and apply supython's framework migrations
 supython up
 
 # 4. run the auth/API service (separate terminal)
@@ -190,6 +196,10 @@ You should now have:
 
 ## End-to-end smoke test
 
+This uses the scaffolded `todos` table, so first apply the example app migration
+(`migrations/0001_create_todos.sql`) with [dbmate](https://github.com/amacneil/dbmate)
+or your migration tool of choice — `supython migrate` only handles framework schemas.
+
 ```bash
 # sign up
 curl -sS -X POST http://localhost:8000/auth/v1/signup \
@@ -531,128 +541,31 @@ need to edit SQL.
 
 ```
  supython/
- ├── manage.py                       # optional cli entrypoint (sets SUPYTHON_SETTINGS_MODULE)
- ├── docker-compose.yml              # Postgres + PostgREST (dev stack)
- ├── docker-compose.prod.yml         # hardened single-host production stack
- ├── docker-compose.test.yml         # dedicated test Postgres on port 54323
- ├── Caddyfile                       # reverse-proxy TLS for prod
- ├── <name>/                         # your Python package
- │   ├── __init__.py
- │   ├── settings.py                 # project settings (EXTENSIONS, EXTRA_ROUTERS, …)
- │   ├── asgi.py                     # optional ASGI entrypoint (uvicorn <name>.asgi:app)
- │   ├── jobs.py                     # example @job seed
- │   └── hooks.py                    # example @on("signup") seed
- ├── migrations/
- │   ├── 0001_extensions_and_roles.sql      # anon/authenticated/service_role/authenticator
- │   ├── 0002_auth_schema.sql               # auth.users, auth.refresh_tokens, auth.uid()
- │   ├── 0003_demo_todos.sql                # the demo table + RLS policies
- │   ├── 0004_auth_v0_2.sql                # identities, one_time_tokens, audit_log
- │   ├── 0005_storage_schema.sql            # storage.buckets + storage.objects
- │   ├── 0006_realtime_schema.sql           # realtime schema, trigger, enable() helper
- │   ├── 0007_jobs_schema.sql               # jobs queue, cron_schedules, enqueue/claim_next
- │   ├── 0008_jobs_last_error.sql           # last_error column on jobs.jobs
- │   ├── 0009_auth_rate_limits.sql          # auth fixed-window rate-limit counters
- │   ├── 0010_worker_heartbeat.sql          # worker heartbeat for /readyz
- │   ├── 0011_admin_schema.sql              # admin.admin_users, sessions, audit
- │   ├── 0012_auth_banned_until.sql         # banned_until on auth.users
- │   ├── 0013_email_templates.sql            # auth.email_templates
- │   ├── 0014_realtime_payload_warning.sql   # >8KB payload warning counter
- │   └── 0015_backups_schema.sql             # backups metadata
- ├── examples/
- │   ├── todos.http                  # HTTP smoke tests (auth + PostgREST)
- │   ├── storage.http                # storage upload / signed URL examples
- │   ├── functions.http              # edge-function call examples
- │   └── chat.html                   # two-browser realtime demo (vanilla JS, zero deps)
- ├── docs/
- │   ├── PROJECT.md                  # architecture + roadmap (single source of truth)
- │   ├── Installation.md             # full install guide (dev, prod, managed Postgres)
- │   └── admin-ui/
- │       ├── admin-surface-plan.md   # admin implementation plan + phase status
- │       └── admin-surface.md        # admin architecture + contracts
- ├── tests/
- │   ├── conftest.py                 # cross-tree fixtures (keys, capturing mailer)
- │   ├── _keys.py                    # JWT-forging helpers
- │   ├── fixtures/                   # test function modules, etc.
- │   ├── unit/                       # pure-Python tests (~6s, no Docker)
- │   │   ├── test_admin_session.py
- │   │   ├── test_admin_service_db.py
- │   │   └── ...
- │   └── integration/                # full ASGI + Postgres on port 54323
- │       ├── conftest.py             # pool, app, client, autouse DB cleaners
- │       ├── test_auth_signup_login.py
- │       ├── test_admin_auth.py
- │       ├── test_admin_auth_users.py
- │       ├── test_admin_db_rows.py
- │       ├── test_admin_jobs.py
- │       ├── test_admin_ops_backups.py
- │       ├── test_admin_storage.py
- │       ├── test_postgrest_rls.py
- │       ├── test_realtime_ws.py
- │       └── ...
- ├── admin-ui/                       # Vue 3 + Vite SPA (built → src/supython/admin/static/)
- │   └── src/
- │       ├── api/                    # single fetch seam
- │       ├── components/             # shell, data, editors, feedback
- │       ├── composables/            # useResource, useTable, useConfirm, useImpersonate, …
- │       ├── stores/                 # auth, ui
- │       ├── views/                  # Dashboard, db/, auth/, storage/, functions/, …
- │       └── router/
- └── src/supython/
-     ├── __init__.py                 # single version string
-     ├── settings.py                 # pydantic-settings, .env-driven
-     ├── db.py                       # asyncpg pool + lifespan + as_role() / as_service_role()
-     ├── mailer.py                   # ConsoleBackend / SmtpBackend
-     ├── tokens.py                   # RS256/ES256 JWT + JWKS
-     ├── passwords.py                # argon2id
-     ├── migrate.py                  # ~50-line SQL migration runner
-     ├── app.py                      # FastAPI factory
-     ├── cli.py                      # typer: up, dev, keygen, admin, worker, test, …
-     ├── extensions.py               # eager-import dotted module paths at boot
-     ├── settings_module.py          # user settings (EXTENSIONS, EXTRA_ROUTERS, …)
-     ├── health.py                   # /livez, /readyz, /health endpoints
-     ├── logging_config.py           # structured JSON log setup
-     ├── security_headers.py         # HSTS, CSP, etc.
-     ├── body_size.py                # request body size guards
-     ├── jwks.py                     # JWKS generation + rotation helpers
-     ├── keyset.py                   # asymmetric key rotation manifest
-     ├── secretset.py                # symmetric secret rotation manifest
-     ├── hooks.py                    # generic hook system: on() / fire()
-     ├── mail.py                     # email send with job-retry fallback
-     ├── auth/
-     │   ├── schemas.py
-     │   ├── service.py              # full auth layer: signup / OAuth / OTP / recover …
-     │   ├── router.py               # all /auth/v1/* routes
-     │   └── providers/              # Google, GitHub, OAuth2 helpers
-     ├── storage/
-     │   ├── backends.py             # LocalBackend, S3Backend
-     │   ├── service.py
-     │   └── router.py               # /storage/v1/*
-     ├── functions/
-     │   ├── loader.py               # filesystem discovery + hot reload
-     │   └── router.py               # /functions/v1/*
-     ├── realtime/
-     │   ├── protocol.py             # Phoenix Channels encode/decode
-     │   ├── broker.py               # fan-out engine with RLS filtering
-     │   ├── websocket.py            # WS route with JWT auth
-     │   └── router.py               # /realtime/v1/*
-     ├── jobs/
-     │   ├── registry.py             # @job / @cron decorator store
-     │   ├── service.py              # enqueue, claim_next, mark_*
-     │   ├── worker.py               # long-running poll/dispatch/drain loop
-     │   ├── cron.py                 # pg_cron sync + InProcScheduler
-     │   └── router.py               # /jobs/v1/*
-     ├── admin/
-     │   ├── session.py              # admin cookie session (SHA-256 hashed, 8h TTL)
-     │   ├── deps.py                 # require_admin dependency
-     │   ├── spa.py                  # static SPA mount + index.html fallback
-     │   ├── schemas.py              # shared Pydantic models
-     │   ├── audit.py                # admin audit log writer
-     │   ├── static/                 # pre-built Vue 3 SPA bundle (committed)
-     │   └── api/                    # /admin/api/v1/* route handlers
-     ├── backups/                    # pg_dump wrapper + restore
-     ├── gen/                        # supython gen types --lang py|ts
-     ├── scaffold/                   # supython init templates
-     └── client/                     # Python SDK (optional [client] extra)
+ ├── src/supython/            # the FastAPI service + CLI (the published package)
+ │   ├── app.py               # FastAPI factory
+ │   ├── cli.py               # typer CLI: init, up, dev, worker, migrate, gen, …
+ │   ├── db.py                # asyncpg pool + as_role() / as_service_role()
+ │   ├── settings.py          # pydantic-settings, .env-driven
+ │   ├── tokens.py            # RS256/ES256 JWT + JWKS
+ │   ├── migrate.py           # ~50-line SQL migration runner
+ │   ├── migrations/          # framework schema (auth, storage, realtime, jobs, …)
+ │   ├── auth/                # /auth/v1/*       — signup, OAuth, OTP, recovery
+ │   ├── storage/             # /storage/v1/*    — local + S3 backends
+ │   ├── functions/           # /functions/v1/*  — filesystem-discovered handlers
+ │   ├── realtime/            # /realtime/v1/*   — Phoenix Channels over LISTEN/NOTIFY
+ │   ├── jobs/                # /jobs/v1/*       — queue, worker, pg_cron scheduling
+ │   ├── admin/               # /admin/api/v1/*  + the built Vue SPA (static/)
+ │   ├── backups/             # pg_dump wrapper + restore
+ │   ├── gen/                 # `supython gen types --lang py|ts`
+ │   ├── scaffold/            # `supython init` templates
+ │   └── client/              # optional Python SDK ([client] extra)
+ ├── admin-ui/                # Vue 3 + Vite SPA, built → src/supython/admin/static/
+ ├── ts-sdk/                  # @supython/sdk — TypeScript SDK
+ ├── dev-app/                 # scaffolded sample project for local development
+ ├── examples/                # .http smoke tests + chat.html realtime demo
+ ├── tests/                   # unit/ (no Docker) + integration/ (Postgres :54323)
+ ├── Dockerfile
+ └── pyproject.toml
 ```
 
 ## Plugins & extensions
@@ -692,10 +605,10 @@ supython down               # stop the stack (keeps data)
 supython down --prod        # stop the prod stack
 supython reset              # stop the stack and DELETE the volume (destructive)
 supython reset --prod       # stop prod stack and DELETE volumes
-supython migrate            # apply pending SQL migrations
+supython migrate            # apply supython's framework migrations (auth, storage, …)
 supython info               # print resolved settings
 supython doctor             # diagnose roles, extensions, JWKS, grants, migration drift
-supython init <name>        # scaffold a new supython project
+supython init <pkg> [dir]   # scaffold a project (pkg = package name; dir defaults to ./<pkg>)
 supython gen types --lang py --out db_schema.py   # emit typed dataclasses + TypedDicts
 supython gen types --lang ts --out types.ts   # emit TypeScript Database interface
 
@@ -818,25 +731,6 @@ unit tests always run in isolation.
 **CI:** runners with Docker run `supython test up && supython test run`;
 runners without Docker run `pytest tests/unit` for a meaningful subset.
 
-## Roadmap
-
-- ✅ Email/password auth, PostgREST contract, RLS demo
-- ✅ OAuth, password reset, magic link, OTP, reuse detection, email backend, test suite
-- ✅ Storage (S3/local) with RLS-on-metadata, edge-style functions from a `functions/` directory; `db.as_role(role, claims)` helper; `supython init` scaffold; `supython gen types --lang py`
-- ✅ Realtime over `LISTEN/NOTIFY` with RLS-aware fan-out; Phoenix Channels wire format; broadcast + presence; `examples/chat.html` demo
-- ✅ Job queue worker + `pg_cron` scheduling + hooks + CLI management commands
-- ✅ Grooming + security foundation: unified versioning, CORS closed by default, RS256 JWT, rate limiting, `supython doctor`, pool sizing, statement timeout
-- ✅ Production observable: structured JSON logs, `/livez`/`/readyz`/`/health`, security headers, input size guards, audit log completeness, OAuth PKCE, secret rotation runbooks
-- ✅ (partial) Multi-arch Docker images, admin control plane (Vue 3 SPA — database, auth, storage, functions, realtime, jobs, backups, log tail), CI buildx workflow; benchmarks + security audit pass + dependency budget CI remaining
-- *(deferred)* — Realtime v2 over logical replication
-- ✅ **TypeScript SDK** — `@supython/sdk` wrapping `@supabase/postgrest-js` + `@supabase/realtime-js` 
-
-### Future
-
-- **Admin control plane** polish (tests + remaining DoD items)
-- **Realtime v2** — logical replication (demand-driven; swap when trigger overhead or >8KB payload data warrants it)
-- **Prometheus `/metrics`** + **OpenTelemetry** — optional extras
-
 ## License
 
 MIT

{supython-0.1.9 → supython-0.1.11}/README.md

@@ -94,20 +94,25 @@ python -m venv .venv && source .venv/bin/activate
 pip install supython
 
 # 2. scaffold a new project
+#    `myapp` is the importable package name. An optional second argument
+#    sets the target dir (`.` = current dir); it defaults to ./myapp.
 supython init myapp
 cd myapp
-cp .env.example .env
-# Review .env — at minimum confirm AUTHENTICATOR_PASSWORD matches
-# the value PostgREST will use (docker-compose.yml injects it via env).
+# install the project (and supython, pinned in the generated pyproject.toml)
+pip install -e .
 #
-# The scaffold creates:
-#   manage.py         — Optional CLI entrypoint (sets SUPYTHON_SETTINGS_MODULE)
+# The scaffold generates a ready-to-run, gitignored .env plus a JWT keypair
+# and signing secrets under .supython/ — no manual edits needed to boot.
+# It also creates:
+#   pyproject.toml    — declares this project, pins the supython version
 #   myapp/settings.py — declare EXTENSIONS, EXTRA_ROUTERS, EXTRA_MIDDLEWARE
-#   myapp/jobs.py     — example @job seed (register your background jobs here)
-#   myapp/hooks.py    — example @on("signup") seed (lifecycle hooks)
+#   myapp/jobs/       — package of @job / @cron modules (all auto-imported)
+#   myapp/hooks/      — package of @on(...) lifecycle hooks (all auto-imported)
 #   myapp/asgi.py     — optional entrypoint for uvicorn/gunicorn
+#   functions/hello.py            — example edge function (GET /functions/hello)
+#   migrations/0001_create_todos.sql — example app migration (apply with dbmate)
 
-# 3. boot Postgres + PostgREST and run migrations (one command)
+# 3. boot Postgres + PostgREST and apply supython's framework migrations
 supython up
 
 # 4. run the auth/API service (separate terminal)
@@ -132,6 +137,10 @@ You should now have:
 
 ## End-to-end smoke test
 
+This uses the scaffolded `todos` table, so first apply the example app migration
+(`migrations/0001_create_todos.sql`) with [dbmate](https://github.com/amacneil/dbmate)
+or your migration tool of choice — `supython migrate` only handles framework schemas.
+
 ```bash
 # sign up
 curl -sS -X POST http://localhost:8000/auth/v1/signup \
@@ -473,128 +482,31 @@ need to edit SQL.
 
 ```
  supython/
- ├── manage.py                       # optional cli entrypoint (sets SUPYTHON_SETTINGS_MODULE)
- ├── docker-compose.yml              # Postgres + PostgREST (dev stack)
- ├── docker-compose.prod.yml         # hardened single-host production stack
- ├── docker-compose.test.yml         # dedicated test Postgres on port 54323
- ├── Caddyfile                       # reverse-proxy TLS for prod
- ├── <name>/                         # your Python package
- │   ├── __init__.py
- │   ├── settings.py                 # project settings (EXTENSIONS, EXTRA_ROUTERS, …)
- │   ├── asgi.py                     # optional ASGI entrypoint (uvicorn <name>.asgi:app)
- │   ├── jobs.py                     # example @job seed
- │   └── hooks.py                    # example @on("signup") seed
- ├── migrations/
- │   ├── 0001_extensions_and_roles.sql      # anon/authenticated/service_role/authenticator
- │   ├── 0002_auth_schema.sql               # auth.users, auth.refresh_tokens, auth.uid()
- │   ├── 0003_demo_todos.sql                # the demo table + RLS policies
- │   ├── 0004_auth_v0_2.sql                # identities, one_time_tokens, audit_log
- │   ├── 0005_storage_schema.sql            # storage.buckets + storage.objects
- │   ├── 0006_realtime_schema.sql           # realtime schema, trigger, enable() helper
- │   ├── 0007_jobs_schema.sql               # jobs queue, cron_schedules, enqueue/claim_next
- │   ├── 0008_jobs_last_error.sql           # last_error column on jobs.jobs
- │   ├── 0009_auth_rate_limits.sql          # auth fixed-window rate-limit counters
- │   ├── 0010_worker_heartbeat.sql          # worker heartbeat for /readyz
- │   ├── 0011_admin_schema.sql              # admin.admin_users, sessions, audit
- │   ├── 0012_auth_banned_until.sql         # banned_until on auth.users
- │   ├── 0013_email_templates.sql            # auth.email_templates
- │   ├── 0014_realtime_payload_warning.sql   # >8KB payload warning counter
- │   └── 0015_backups_schema.sql             # backups metadata
- ├── examples/
- │   ├── todos.http                  # HTTP smoke tests (auth + PostgREST)
- │   ├── storage.http                # storage upload / signed URL examples
- │   ├── functions.http              # edge-function call examples
- │   └── chat.html                   # two-browser realtime demo (vanilla JS, zero deps)
- ├── docs/
- │   ├── PROJECT.md                  # architecture + roadmap (single source of truth)
- │   ├── Installation.md             # full install guide (dev, prod, managed Postgres)
- │   └── admin-ui/
- │       ├── admin-surface-plan.md   # admin implementation plan + phase status
- │       └── admin-surface.md        # admin architecture + contracts
- ├── tests/
- │   ├── conftest.py                 # cross-tree fixtures (keys, capturing mailer)
- │   ├── _keys.py                    # JWT-forging helpers
- │   ├── fixtures/                   # test function modules, etc.
- │   ├── unit/                       # pure-Python tests (~6s, no Docker)
- │   │   ├── test_admin_session.py
- │   │   ├── test_admin_service_db.py
- │   │   └── ...
- │   └── integration/                # full ASGI + Postgres on port 54323
- │       ├── conftest.py             # pool, app, client, autouse DB cleaners
- │       ├── test_auth_signup_login.py
- │       ├── test_admin_auth.py
- │       ├── test_admin_auth_users.py
- │       ├── test_admin_db_rows.py
- │       ├── test_admin_jobs.py
- │       ├── test_admin_ops_backups.py
- │       ├── test_admin_storage.py
- │       ├── test_postgrest_rls.py
- │       ├── test_realtime_ws.py
- │       └── ...
- ├── admin-ui/                       # Vue 3 + Vite SPA (built → src/supython/admin/static/)
- │   └── src/
- │       ├── api/                    # single fetch seam
- │       ├── components/             # shell, data, editors, feedback
- │       ├── composables/            # useResource, useTable, useConfirm, useImpersonate, …
- │       ├── stores/                 # auth, ui
- │       ├── views/                  # Dashboard, db/, auth/, storage/, functions/, …
- │       └── router/
- └── src/supython/
-     ├── __init__.py                 # single version string
-     ├── settings.py                 # pydantic-settings, .env-driven
-     ├── db.py                       # asyncpg pool + lifespan + as_role() / as_service_role()
-     ├── mailer.py                   # ConsoleBackend / SmtpBackend
-     ├── tokens.py                   # RS256/ES256 JWT + JWKS
-     ├── passwords.py                # argon2id
-     ├── migrate.py                  # ~50-line SQL migration runner
-     ├── app.py                      # FastAPI factory
-     ├── cli.py                      # typer: up, dev, keygen, admin, worker, test, …
-     ├── extensions.py               # eager-import dotted module paths at boot
-     ├── settings_module.py          # user settings (EXTENSIONS, EXTRA_ROUTERS, …)
-     ├── health.py                   # /livez, /readyz, /health endpoints
-     ├── logging_config.py           # structured JSON log setup
-     ├── security_headers.py         # HSTS, CSP, etc.
-     ├── body_size.py                # request body size guards
-     ├── jwks.py                     # JWKS generation + rotation helpers
-     ├── keyset.py                   # asymmetric key rotation manifest
-     ├── secretset.py                # symmetric secret rotation manifest
-     ├── hooks.py                    # generic hook system: on() / fire()
-     ├── mail.py                     # email send with job-retry fallback
-     ├── auth/
-     │   ├── schemas.py
-     │   ├── service.py              # full auth layer: signup / OAuth / OTP / recover …
-     │   ├── router.py               # all /auth/v1/* routes
-     │   └── providers/              # Google, GitHub, OAuth2 helpers
-     ├── storage/
-     │   ├── backends.py             # LocalBackend, S3Backend
-     │   ├── service.py
-     │   └── router.py               # /storage/v1/*
-     ├── functions/
-     │   ├── loader.py               # filesystem discovery + hot reload
-     │   └── router.py               # /functions/v1/*
-     ├── realtime/
-     │   ├── protocol.py             # Phoenix Channels encode/decode
-     │   ├── broker.py               # fan-out engine with RLS filtering
-     │   ├── websocket.py            # WS route with JWT auth
-     │   └── router.py               # /realtime/v1/*
-     ├── jobs/
-     │   ├── registry.py             # @job / @cron decorator store
-     │   ├── service.py              # enqueue, claim_next, mark_*
-     │   ├── worker.py               # long-running poll/dispatch/drain loop
-     │   ├── cron.py                 # pg_cron sync + InProcScheduler
-     │   └── router.py               # /jobs/v1/*
-     ├── admin/
-     │   ├── session.py              # admin cookie session (SHA-256 hashed, 8h TTL)
-     │   ├── deps.py                 # require_admin dependency
-     │   ├── spa.py                  # static SPA mount + index.html fallback
-     │   ├── schemas.py              # shared Pydantic models
-     │   ├── audit.py                # admin audit log writer
-     │   ├── static/                 # pre-built Vue 3 SPA bundle (committed)
-     │   └── api/                    # /admin/api/v1/* route handlers
-     ├── backups/                    # pg_dump wrapper + restore
-     ├── gen/                        # supython gen types --lang py|ts
-     ├── scaffold/                   # supython init templates
-     └── client/                     # Python SDK (optional [client] extra)
+ ├── src/supython/            # the FastAPI service + CLI (the published package)
+ │   ├── app.py               # FastAPI factory
+ │   ├── cli.py               # typer CLI: init, up, dev, worker, migrate, gen, …
+ │   ├── db.py                # asyncpg pool + as_role() / as_service_role()
+ │   ├── settings.py          # pydantic-settings, .env-driven
+ │   ├── tokens.py            # RS256/ES256 JWT + JWKS
+ │   ├── migrate.py           # ~50-line SQL migration runner
+ │   ├── migrations/          # framework schema (auth, storage, realtime, jobs, …)
+ │   ├── auth/                # /auth/v1/*       — signup, OAuth, OTP, recovery
+ │   ├── storage/             # /storage/v1/*    — local + S3 backends
+ │   ├── functions/           # /functions/v1/*  — filesystem-discovered handlers
+ │   ├── realtime/            # /realtime/v1/*   — Phoenix Channels over LISTEN/NOTIFY
+ │   ├── jobs/                # /jobs/v1/*       — queue, worker, pg_cron scheduling
+ │   ├── admin/               # /admin/api/v1/*  + the built Vue SPA (static/)
+ │   ├── backups/             # pg_dump wrapper + restore
+ │   ├── gen/                 # `supython gen types --lang py|ts`
+ │   ├── scaffold/            # `supython init` templates
+ │   └── client/              # optional Python SDK ([client] extra)
+ ├── admin-ui/                # Vue 3 + Vite SPA, built → src/supython/admin/static/
+ ├── ts-sdk/                  # @supython/sdk — TypeScript SDK
+ ├── dev-app/                 # scaffolded sample project for local development
+ ├── examples/                # .http smoke tests + chat.html realtime demo
+ ├── tests/                   # unit/ (no Docker) + integration/ (Postgres :54323)
+ ├── Dockerfile
+ └── pyproject.toml
 ```
 
 ## Plugins & extensions
@@ -634,10 +546,10 @@ supython down               # stop the stack (keeps data)
 supython down --prod        # stop the prod stack
 supython reset              # stop the stack and DELETE the volume (destructive)
 supython reset --prod       # stop prod stack and DELETE volumes
-supython migrate            # apply pending SQL migrations
+supython migrate            # apply supython's framework migrations (auth, storage, …)
 supython info               # print resolved settings
 supython doctor             # diagnose roles, extensions, JWKS, grants, migration drift
-supython init <name>        # scaffold a new supython project
+supython init <pkg> [dir]   # scaffold a project (pkg = package name; dir defaults to ./<pkg>)
 supython gen types --lang py --out db_schema.py   # emit typed dataclasses + TypedDicts
 supython gen types --lang ts --out types.ts   # emit TypeScript Database interface
 
@@ -760,25 +672,6 @@ unit tests always run in isolation.
 **CI:** runners with Docker run `supython test up && supython test run`;
 runners without Docker run `pytest tests/unit` for a meaningful subset.
 
-## Roadmap
-
-- ✅ Email/password auth, PostgREST contract, RLS demo
-- ✅ OAuth, password reset, magic link, OTP, reuse detection, email backend, test suite
-- ✅ Storage (S3/local) with RLS-on-metadata, edge-style functions from a `functions/` directory; `db.as_role(role, claims)` helper; `supython init` scaffold; `supython gen types --lang py`
-- ✅ Realtime over `LISTEN/NOTIFY` with RLS-aware fan-out; Phoenix Channels wire format; broadcast + presence; `examples/chat.html` demo
-- ✅ Job queue worker + `pg_cron` scheduling + hooks + CLI management commands
-- ✅ Grooming + security foundation: unified versioning, CORS closed by default, RS256 JWT, rate limiting, `supython doctor`, pool sizing, statement timeout
-- ✅ Production observable: structured JSON logs, `/livez`/`/readyz`/`/health`, security headers, input size guards, audit log completeness, OAuth PKCE, secret rotation runbooks
-- ✅ (partial) Multi-arch Docker images, admin control plane (Vue 3 SPA — database, auth, storage, functions, realtime, jobs, backups, log tail), CI buildx workflow; benchmarks + security audit pass + dependency budget CI remaining
-- *(deferred)* — Realtime v2 over logical replication
-- ✅ **TypeScript SDK** — `@supython/sdk` wrapping `@supabase/postgrest-js` + `@supabase/realtime-js` 
-
-### Future
-
-- **Admin control plane** polish (tests + remaining DoD items)
-- **Realtime v2** — logical replication (demand-driven; swap when trigger overhead or >8KB payload data warrants it)
-- **Prometheus `/metrics`** + **OpenTelemetry** — optional extras
-
 ## License
 
 MIT

{supython-0.1.9 → supython-0.1.11}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "supython"
-version = "0.1.9"
+version = "0.1.11"
 description = "A lightweight Postgres-first BaaS framework for Python"
 readme = "README.md"
 requires-python = ">=3.11"
@@ -32,6 +32,7 @@ dependencies = [
     "asyncpg>=0.30",
     "pydantic>=2.9",
     "pydantic-settings>=2.6",
+    "python-dotenv>=1.0",
     "email-validator>=2.2",
     "argon2-cffi>=23.1",
     "pyjwt[crypto]>=2.10",

{supython-0.1.9 → supython-0.1.11}/src/supython/app.py

@@ -27,7 +27,7 @@ from .body_size import BodySizeLimitMiddleware
 from .security_headers import SecurityHeadersMiddleware
 from .realtime import get_broker
 from .realtime.router import router as realtime_router
-from .settings import get_settings
+from .settings import export_env_file, get_settings
 from .storage.router import router as storage_router
 
 logger = logging.getLogger(__name__)
@@ -96,6 +96,7 @@ async def _lifespan(app: FastAPI) -> AsyncIterator[None]:
 
 
 def create_app() -> FastAPI:
+    export_env_file()
     settings = get_settings()
     configure_logging(settings.log_level, json_format=settings.log_json)