diff --git a/skills/simple-module-cli/SKILL.md b/skills/simple-module-cli/SKILL.md index 0f2ac6e0..c23701b5 100644 --- a/skills/simple-module-cli/SKILL.md +++ b/skills/simple-module-cli/SKILL.md @@ -1,11 +1,13 @@ --- name: simple-module-cli -description: Use when invoking the `smpy` CLI for a simple_module_python project — starting a new app, scaffolding a host or a publishable module, regenerating the Inertia page manifest, importing settings overrides from env, creating an admin user, or installing the bundled agent skills. Triggers on "smpy new", "smpy create-host", "smpy create-module", "smpy host gen-pages", "smpy users create-admin", "smpy skills add", or any unfamiliar `smpy` subcommand. +description: Use when invoking the `smpy` CLI for a simple_module_python project — starting a new app, scaffolding a host or a publishable module, bumping simple_module_* dependencies to their latest PyPI versions, regenerating the Inertia page manifest, importing settings overrides from env, creating an admin user, or installing the bundled agent skills. Triggers on "smpy new", "smpy create-host", "smpy create-module", "smpy package-update", "smpy host gen-pages", "smpy users create-admin", "smpy skills add", or any unfamiliar `smpy` subcommand. --- # simple_module_python: the `smpy` CLI -The `smpy` command is provided by `simple_module_cli` (installed as a dep of `simple_module_hosting`). It groups several kinds of operations: scaffolding new things, project-time helpers for the host, admin shortcuts for the bundled modules, installing the bundled agent skills, and bumping `simple_module_*` deps. +The `smpy` command is provided by `simple_module_cli` (installed as a dep of `simple_module_hosting`); `simple-module` is an identical alias for the same entry point. It groups several kinds of operations: scaffolding new things, project-time helpers for the host, admin shortcuts for the bundled modules, installing the bundled agent skills, and bumping `simple_module_*` deps. + +`new`, `create-host`, `create-module`, `package-update`, and `skills` are built into `simple_module_cli` and always present. `host` / `settings` / `users` are **plugin subgroups** contributed by installed packages (`simple_module_hosting` / `simple_module_settings` / `simple_module_users`) through the `simple_module_cli.cli_plugins` entry-point group — they only show up when that package is installed, which is why a fresh bare host won't list `smpy users` until the users module is added. ## Top-level commands @@ -24,19 +26,24 @@ The `smpy` command is provided by `simple_module_cli` (installed as a dep of `si The fastest way from zero to a working app. It calls `create-host` under the hood, then installs and wires up the modules you pick. +App names must be **lowercase** with a single separator style (`my_app`, `my-app`, or `myapp`) — `smpy new` rejects mixed case / spaces / mixed separators up front (`MyApp`, `foo_bar-baz` error out). `create-host` and `create-module` are lenient and accept any case. + ```bash # Interactive (asks for DB, tenancy, preset, module list) -smpy new MyApp +smpy new my_app # Non-interactive: take all defaults (sqlite, no tenancy, standard preset) -smpy new MyApp --yes +smpy new my_app --yes # Pick a preset and add extras -smpy new MyApp --preset full --tenancy --db postgres -smpy new MyApp --preset minimal --with background_tasks,file_storage --yes +smpy new my_app --preset full --tenancy --db postgres +smpy new my_app --preset minimal --with background_tasks,file_storage --yes -# Scaffold only — skip uv sync / npm install / alembic upgrade head -smpy new MyApp --no-install +# Consume-only host: no modules/ dir, no sample module to author against +smpy new my_app --preset standard --flat --yes + +# Scaffold only — skip uv sync / npm install / the initial migration +smpy new my_app --no-install ``` **Module presets:** @@ -45,10 +52,14 @@ smpy new MyApp --no-install |---|---| | `minimal` | `users` (and `auth` as a dep) | | `standard` (default) | `users`, `dashboard`, `permissions` (+ deps) | -| `full` | every module in the catalog | -| `custom` | interactive — pick each module yes/no | +| `full` | every module **in the scaffolder catalog** (the 8 keys below) — *not* every module in the monorepo | +| `custom` | interactive — pick each catalog module yes/no | + +`--preset` only accepts `minimal`, `standard`, or `full`. **`custom` is wizard-only** — there's no `--preset custom`; to hand-pick modules non-interactively, start from any preset and add the rest with `--with`. -`--with` accepts a comma-separated list of catalog keys (`auth, users, permissions, dashboard, settings, feature_flags, file_storage, background_tasks`). Transitive `requires` are auto-added; the wizard prints `Added X (required by Y)` so you can see what got pulled in. +`--with` accepts a comma-separated list of catalog keys (`auth, users, permissions, dashboard, settings, feature_flags, file_storage, background_tasks`). Transitive `requires` are auto-added; the wizard prints `Added X (required by Y)` so you can see what got pulled in. An unknown key fails fast with the available list (so `--with=does_not_exist` is self-correcting). Note the catalog is a curated subset — repo modules like `products`, `keycloak`, and `audit_log` are **not** catalog keys; add those to an existing host by installing the package (see the pitfall below). + +Selecting `background_tasks` also runs its post-scaffold **recipe**: it drops `docker-compose.yml`, `scripts/run_worker.py`, host/worker Dockerfiles, a `SM_BG_TASKS_BROKER_URL` entry in `.env.example`, and Celery `make` targets. The closing "Next steps" then reminds you to run `docker compose up -d redis worker beat` for the worker/beat processes. **Options summary:** @@ -57,10 +68,13 @@ smpy new MyApp --no-install | `--dest ` | `./` | Where to write the project | | `--db sqlite\|postgres` | `sqlite` | Backend configured in `.env.example` | | `--tenancy / --no-tenancy` | `--no-tenancy` | Enable the multi-tenant middleware | -| `--preset minimal\|standard\|full` | wizard asks | Module bundle | +| `--preset minimal\|standard\|full` | wizard asks | Module bundle (no `custom` — that's wizard-only) | | `--with ` | none | Extra catalog keys beyond the preset | +| `--flat` | off | Skip the `modules/` directory and the sample module — for a host that only ever consumes published modules and never authors its own | | `--yes / -y` | off | Skip prompts; accept defaults | -| `--no-install` | off | Skip `uv sync` / `npm install` / `alembic upgrade head` | +| `--no-install` | off | Skip `uv sync` / `npm install` / the autogenerated initial migration; the printed next steps use `make migration` / `make migrate` / `make dev` instead | + +Passing `--preset` or any `--with` value switches `smpy new` into flag-driven mode (no wizard) even without `--yes`; DB and tenancy then come from `--db` / `--tenancy` defaults. The validated name is also normalized to a PyPI-safe kebab-case slug — `smpy new my_app` prints `Normalizing PyPI name to 'my-app'.` and uses that for the package metadata. ## `smpy create-host ` — bare host @@ -70,7 +84,7 @@ smpy create-host MyApp --with Auth,Products # declare module deps in pyproject. smpy create-host MyApp --dest ./apps/myapp # custom destination ``` -`--with` takes **PascalCase module names** (matching `ModuleMeta.name`), not catalog keys. Use this when you want to drive the build yourself rather than via `smpy new`'s wizard. +`--with` takes **PascalCase module names** (matching `ModuleMeta.name`), not catalog keys — each is lowercased into a `simple_module_` dependency in `pyproject.toml`. Unlike `smpy new`, the names are **not** checked against the scaffolder catalog, so any published module works (e.g. `--with Products` → `simple_module_products`). No deps are installed and no transitive `requires` are resolved; you drive `uv sync` and migrations yourself. Use this when you want to wire the build by hand rather than via `smpy new`'s wizard. ## `smpy create-module ` — module package @@ -87,6 +101,25 @@ The result is a complete package: `pyproject.toml` with the entry point declared For the post-scaffold steps (entry point, Inertia namespace, etc.) see **simple-module-creating**. +## `smpy package-update` — bump `simple_module_*` deps + +Walks the project's `pyproject.toml` (plus every `[tool.uv.workspace]` member), finds each dependency whose distribution name matches `simple_module_*` / `simple-module-*`, queries PyPI for the latest non-yanked release, and rewrites the constraint to `name>=`. PyPI lookups run in parallel, so it's quick even across a multi-package workspace. + +```bash +smpy package-update # rewrite constraints in ./pyproject.toml (+ workspace members) +smpy package-update --dry-run # show "old → new" per file, write nothing +smpy package-update --include-pre # also consider pre-releases (a/b/rc/dev/post) +smpy package-update --path apps/web # point at another project root or a pyproject.toml +``` + +| Flag | Default | Meaning | +|---|---|---| +| `--path ` | cwd | Project root or an explicit `pyproject.toml` | +| `--dry-run` | off | Print planned changes only; don't write | +| `--include-pre` | off | Allow pre-release versions as the "latest" | + +**Deps it deliberately skips:** anything whose `[tool.uv.sources]` entry points at a workspace member, a local `path`, a `git` ref, or a `url` — those don't come from PyPI, so their version lives elsewhere. Skipped deps are listed with a reason (`workspace/local source`, `not found on PyPI`). The command only edits constraints; **run `uv sync` afterward** to actually install the new versions (it reminds you to). + ## `smpy skills` — install the bundled agent skills `simple_module_cli` ships a set of [SKILL.md](https://agentskills.io/specification) packs (the ones in this directory). Drop them into any project so Claude Code / Cursor / Codex / etc. find them automatically. @@ -124,6 +157,7 @@ Wheel-installed modules ship `package.json` declarations that need to land in th ```bash smpy host sync-js-deps # uses ./client_app smpy host sync-js-deps --host-client-app=apps/web/client_app +smpy host sync-js-deps --dry-run # print the npm install command without running it ``` Run after `pip install ` if the new module ships frontend code. @@ -163,9 +197,11 @@ Don't bake `--password` literals into a script you commit; use a secrets store a - **Forgot `smpy host sync-js-deps` after `pip install`-ing a module with pages.** Vite resolves module imports against `client_app/node_modules`; the new module's JS deps won't land until you sync. - **Used `smpy create-module` to add a module to an existing host.** That command is for **publishable** packages, intended to live in their own repo. To add a module to an existing host: install it (`pip install simple_module_` or add to `pyproject.toml` and `uv sync`), then autogenerate a migration. See **simple-module-creating** + **simple-module-migrations**. - **Calling `smpy create-admin` before migrations have run.** The users tables don't exist yet; the command will error. Run `alembic upgrade head` first (or use `smpy new` which does it for you when `--no-install` isn't set). +- **Expecting `--with products` (or `keycloak` / `audit_log`) to work on `smpy new`.** Those modules exist in the monorepo but aren't scaffolder-catalog keys, so `smpy new --with products` errors. Either scaffold without them and `pip install simple_module_products` into the host afterward, or use `smpy create-host --with Products` (which doesn't validate against the catalog). +- **`smpy package-update` "did nothing" for a workspace dep.** Deps sourced from a `[tool.uv.sources]` workspace/path/git/URL entry are intentionally skipped (their version isn't on PyPI) — they show up in the output as `skipped`, not updated. Also remember to run `uv sync` after; `package-update` only rewrites the constraint strings. ## Related skills - **simple-module-creating** — what `smpy create-module` produces and the post-scaffold contract - **simple-module-inertia-pages** — what `smpy host gen-pages` regenerates and why -- **simple-module-migrations** — the `alembic upgrade head` step `smpy new` runs +- **simple-module-migrations** — the migration step `smpy new` runs (`make migration` + `make migrate`, or `alembic upgrade head` directly) diff --git a/skills/simple-module-conventions/SKILL.md b/skills/simple-module-conventions/SKILL.md index cca6d788..e27bfab6 100644 --- a/skills/simple-module-conventions/SKILL.md +++ b/skills/simple-module-conventions/SKILL.md @@ -89,7 +89,7 @@ Locale-related diagnostics: SM013 (missing file), SM014 (missing keys vs default ### 9. Don't re-enable the silenced ty rules -Projects using the `ty` type checker should globally suppress `unresolved-attribute`, `unsupported-operator`, `unknown-argument`, `no-matching-overload`, and `invalid-argument-type` in `pyproject.toml`. SQLModel runtime-instruments fields as SQLAlchemy attributes, so the type checker can't see what's there. Real bugs surface in tests. +Projects using the `ty` type checker should globally suppress `unresolved-attribute`, `unsupported-operator`, `unknown-argument`, `no-matching-overload`, `invalid-argument-type`, and `invalid-assignment` in `pyproject.toml`. SQLModel runtime-instruments fields as SQLAlchemy attributes, so the type checker can't see what's there (and `model_config = ConfigDict(...)` clashes with ty's internal `SQLModelConfig` type, which `invalid-assignment` covers). Real bugs surface in tests. ## Related skills diff --git a/skills/simple-module-creating/SKILL.md b/skills/simple-module-creating/SKILL.md index 99a3d62f..c58caf48 100644 --- a/skills/simple-module-creating/SKILL.md +++ b/skills/simple-module-creating/SKILL.md @@ -10,35 +10,49 @@ description: Use when adding a new feature package to a simple_module_python app ## Quick path ```bash -# scaffold a publishable module package in ./orders (run in a fresh repo or -# inside a host's modules/ directory) -smpy create-module orders - -# install the new package into the host environment -uv sync # or: pip install -e ./orders +# scaffold a module into this repo's modules/orders/ — also wires the package +# into host/ + root pyproject.toml and runs `uv sync --all-packages` +make new-module name=orders # if you added a frontend page, regenerate the Inertia manifest -smpy host gen-pages --host-dir=client_app +make gen-pages # if you added SQLModel tables, autogenerate + apply a migration -uv run alembic revision --autogenerate -m "add orders module" -uv run alembic upgrade head +make migration msg="add orders module" +make migrate ``` +`make new-module` (→ `scripts/new_module.py`) is the in-repo path and produces +the full tree below. For a **standalone publishable package** (its own repo, +with CI + PyPI `publish.yml`), use `smpy create-module orders` instead — a +leaner scaffold; pass `--standalone` to force the `.github/` workflows, then +`uv sync` (or `pip install -e ./orders`) to install it into the host. + ## What scaffolding produces ``` -orders/ +modules/orders/ ├── pyproject.toml # entry point declared here +├── package.json # per-module JS deps +├── tsconfig.json +├── tests/test_orders.py └── orders/ ├── module.py # OrdersModule(ModuleBase) with ModuleMeta ├── models.py # Base = create_module_base("orders") - ├── contracts/ # SQLModel DTOs — public surface + ├── contracts/schemas.py # SQLModel DTOs — public surface + ├── service.py # business logic + ├── services.py # app.state.orders state container (settings) + ├── settings.py # SM_ORDERS_* env → dataclass + ├── deps.py # FastAPI dependencies ├── endpoints/{api,views}.py - ├── pages/ # *.tsx, auto-discovered by Vite + ├── pages/{Browse,Create,Edit}.tsx # *.tsx, auto-discovered by Vite └── locales/en.json ``` +`make new-module` also edits `host/pyproject.toml` (adds the workspace dep) and +the root `pyproject.toml` (type-check + test paths), so the module is picked up +by the host and by `make lint`/`make test` without further wiring. + ## The contract: pyproject.toml + module.py The host discovers modules via a single entry point. If this is wrong, the module silently does nothing in dev and **fails boot in production** (strict discovery). @@ -56,7 +70,7 @@ orders = "orders.module:OrdersModule" ```python # modules/orders/orders/module.py -from simple_module_core import ModuleBase, ModuleMeta +from simple_module_core.module import ModuleBase, ModuleMeta class OrdersModule(ModuleBase): meta = ModuleMeta( @@ -64,13 +78,12 @@ class OrdersModule(ModuleBase): route_prefix="/api/orders", view_prefix="/orders", depends_on=[], # other module names (PascalCase) - version="0.1.0", ) ``` `ModuleMeta.name` is load-bearing in two places: the `__tablename__` prefix you author and the PascalCase Inertia component namespace. So directory `blog_posts` → `name="BlogPosts"` → `inertia.render("BlogPosts/Index", ...)` → `pages/Index.tsx`. Mismatches fire diagnostic codes `SM003` (orphan page) / `SM004` (phantom render). -For modules you intend to publish, also add `version=` (your module's semver) and `requires_framework=` (a PEP 440 spec for the framework API range, e.g. `">=1.0,<2.0"`) so the host can reject incompatible installs at boot. +`ModuleMeta` also accepts `version=` (defaults to `"1.0.0"`) and `requires_framework=` (a PEP 440 spec for the framework API range, e.g. `">=1.0,<2.0"`) so the host can reject incompatible installs at boot — set these on modules you intend to publish. ## Lifecycle hooks (override only what you need) @@ -84,6 +97,7 @@ In execution order — all no-op by default: | `register_feature_flags(registry)` | `FeatureFlagDefinition` constants | | `register_event_handlers(bus)` | `bus.subscribe(EventCls, handler)` | | `register_health_checks(registry)` | Module-owned health probes | +| `register_public_routes(registry)` | Exempt routes from auth via `add_prefix` / `add_regex` (method-aware) | | `register_exception_handlers(app)` | Module-specific error mapping | | `register_middleware(app)` | LIFO — module middleware sorted last wraps outermost | | `register_routes(api_router, view_router)` | `include_router(...)` your two routers | @@ -91,14 +105,14 @@ In execution order — all no-op by default: ## Verify after scaffolding -Boot the host. Diagnostics run automatically: in development, warnings/errors land in the boot logs; in production (`SM_ENVIRONMENT != development`), errors fail the boot. Codes `SM001`/`SM008`/`SM009` are blocking; `SM007` (module overrides no hooks) is info-only. +Boot the host. The diagnostics pass runs **only in development** — warnings/errors print to the boot logs and any ERROR raises `SystemExit`. In **production** the diagnostics pass is skipped; the one thing that fails a production boot is strict module *discovery* (a bad entry point — broken import, missing `meta`, non-`ModuleBase` class), surfaced as `SM001`. So `SM008`/`SM009` are dev-boot / `make doctor` errors, not production-boot blockers; `SM007` (module overrides no hooks) is info-only. -The new module should appear in the registered-modules log line. If it has a view endpoint, visit `/`. +The new module should appear in the registered-modules log line. If it has a view endpoint, visit `/`. Run `make doctor` for the same diagnostics out of band (orphan pages, coupling, migration drift, locale checks) — see the **simple-module-doctor** skill for the full code list. ## Pitfalls - **Forgot the entry point.** Package installs, module silently doesn't load (production strict mode raises `InvalidModuleError`). Verify `[project.entry-points.simple_module]` exists in `pyproject.toml`. -- **`name=` collides.** Two modules with the same `ModuleMeta.name` raise `SM008` at boot. +- **`name=` collides.** Two modules with the same `ModuleMeta.name` raise `SM008` at dev boot / `make doctor` (their lowercased names would also collide as table prefixes in the shared schema). - **Registered the module by hand in host code.** Don't — discovery is entry-point-only; host code never imports module code. For framework-wide rules that apply once the module exists (SQLModel-everywhere, file-size cap, settings layout, no `session.commit()` in services), see the **simple-module-conventions** skill. For migration mechanics see **simple-module-migrations**. diff --git a/skills/simple-module-database/SKILL.md b/skills/simple-module-database/SKILL.md index f7105c6a..5a7d2f23 100644 --- a/skills/simple-module-database/SKILL.md +++ b/skills/simple-module-database/SKILL.md @@ -31,9 +31,9 @@ All modules — on Postgres and SQLite alike — share the host's single schema. | Mixin | Adds | Behavior | |---|---|---| -| `AuditMixin` | `created_at`, `updated_at`, `created_by`, `updated_by` | Auto-populated by SQLAlchemy listeners from the current user/timestamp. | +| `AuditMixin` | `created_at`, `updated_at`, `created_by`, `updated_by` | `created_at` defaults Python-side (and via `server_default`); `updated_at`/`created_by`/`updated_by` set by the `before_flush` listener from `current_user_id` + timestamp. | | `SoftDeleteMixin` | `is_deleted`, `deleted_at`, `deleted_by` | `session.delete(obj)` → soft-delete; `SELECT` auto-filters deleted rows. | -| `MultiTenantMixin` | `tenant_id` | Auto-populated on insert; `SELECT` auto-scoped when `current_tenant_id` is set. | +| `MultiTenantMixin` | `tenant_id` | Auto-populated on insert from `current_tenant_id`. Column is **non-nullable**, so inserting outside any tenant context fails at the DB; creating/mutating a row for a different tenant raises `TenantIsolationError`. `SELECT` auto-scoped when `current_tenant_id` is set. | | `VersionedMixin` | `version: int` | Auto-incremented on update. Use for optimistic concurrency. | List `Base` first; Python MRO handles mixin ordering after that: @@ -77,7 +77,7 @@ async def create_order(session: AsyncSession, payload: OrderCreate) -> Order: ## Pitfalls -- **Setting `tenant_id` manually.** `MultiTenantMixin` populates it on insert from request state. Setting it yourself fights the listener and produces wrong tenant attribution. +- **Setting `tenant_id` manually.** `MultiTenantMixin` populates it on insert from request state (`current_tenant_id`). Setting it to a *different* tenant than the active context raises `TenantIsolationError`; changing it on an existing row raises too. - **Querying `WHERE is_deleted = false` by hand.** The listener already does it. Use `execution_options(include_deleted=True)` only when you genuinely want deleted rows. ## Related skills diff --git a/skills/simple-module-doctor/SKILL.md b/skills/simple-module-doctor/SKILL.md index 448cb774..6925e4f6 100644 --- a/skills/simple-module-doctor/SKILL.md +++ b/skills/simple-module-doctor/SKILL.md @@ -5,22 +5,24 @@ description: Use when interpreting a simple_module_python diagnostic code (SM001 # simple_module_python: diagnostics -Diagnostics run automatically at host boot. **In development**, warnings and errors land in the boot logs and the host keeps running. **In production** (`SM_ENVIRONMENT != development`), errors fail the boot — by design, because a module silently dropping out in prod is worse than a crash. +`make doctor` runs `python -m simple_module_core`: it discovers modules **strictly**, runs the diagnostics, prints findings to stderr (`✓ No module diagnostics issues found` when clean), and exits `1` if any ERROR-level finding was reported. -You can also call `run_diagnostics(...)` from `simple_module_core` programmatically (e.g. in a CI job) to surface issues without booting the full app. +The same diagnostics also run at host boot, but **only in development** (`SM_ENVIRONMENT == development`) — they print to the boot logs and `raise SystemExit` if there's any ERROR. **In production the diagnostics pass is skipped**; what protects prod is that module *discovery* runs strictly (any bad entry point — broken import, missing `meta`, non-`ModuleBase` class — raises and fails the boot). So "errors fail prod boot" is true for discovery-level breakage (surfaced as **SM001**), not for the per-finding checks below, which you'll catch via `make doctor` / dev boot before you ever deploy. + +You can also call `run_diagnostics(...)` from `simple_module_core` programmatically (e.g. in a CI job) to surface issues without booting the full app — pass `migration_state=` / `module_tables=` / `migrated_tables=` to additionally get **SM010/SM011** (the migration checks below), and `i18n_supported_locales=` / `i18n_default_locale=` to get the locale checks. ## Code reference | Code | Level | What it means | Fix | |---|---|---|---| -| **SM001** | ERROR | Module class is missing `meta = ModuleMeta(...)` or it's malformed | Add a valid `meta` class attribute on the `ModuleBase` subclass | +| **SM001** | ERROR | Module class is missing its `meta = ModuleMeta(...)` class attribute, or (under strict discovery) the entry point failed to load — broken import, missing `meta`, or a class that isn't a `ModuleBase` subclass | Add a valid `meta` class attribute on the `ModuleBase` subclass / fix the entry point. This is the one code that fails *production* boot (via strict discovery) | | **SM003** | WARNING | A `pages/.tsx` exists but no `inertia.render("/", ...)` references it | Either delete the orphan file or wire up the render call | | **SM004** | WARNING | `inertia.render("/", ...)` is called but no matching `.tsx` exists | Fix the render-key typo or create the page file | | **SM007** | INFO | Module overrides no `register_*` hooks at all — likely scaffolded but empty | Either implement at least one hook or delete the module if unused | -| **SM008** | ERROR | Two modules declare the same `ModuleMeta.name` (their lowercased names would collide as table prefixes in the shared schema) | Rename one module's `meta.name` | +| **SM008** | ERROR | Two modules declare the same `ModuleMeta.name`, or two names collide once lowercased as table prefixes in the shared schema (one finding per collision, from either the duplicate-name or the schema-conflict check) | Rename one module's `meta.name` | | **SM009** | ERROR | A `framework/*` package directly imports from a plugin module (`modules/*`) | Move the symbol *up* into `simple_module_core` / `simple_module_hosting`, or invert the dependency via the event bus / a registry | -| **SM010** | ERROR | Live DB revision is behind the migration head | Run `alembic upgrade head` before booting; in CI, ensure migrations are part of the deploy step | -| **SM011** | WARNING | A module declares a SQLModel table that has no entry in migration history | Run `alembic revision --autogenerate -m "..."` and apply | +| **SM010** | ERROR | Live DB revision is behind the migration head | Run `make migrate` before booting; in CI, ensure migrations are part of the deploy step. *Note:* only emitted when a caller passes `migration_state=` to `run_diagnostics` — `make doctor` and dev boot do **not** check this. The live boot enforces it separately: `check_migrations()` raises a plain `RuntimeError` (not an SM code) in dev and prod if the DB is behind head | +| **SM011** | WARNING | A module declares a SQLModel table that has no entry in migration history | Run `make migration msg="..."` and apply. *Note:* only emitted when `module_tables=`/`migrated_tables=` are passed to `run_diagnostics`; not surfaced by `make doctor` or boot | | **SM012** | WARNING (dev only) | `register_settings` is overridden but nothing was added to `app.state.` | Either store the module's settings dataclass on `app.state.` or remove the empty override | | **SM013** | WARNING | A locale file declared in `locale_dirs()` is missing for one of the supported locales | Create the file (even if empty) or trim `SM_I18N_SUPPORTED_LOCALES` | | **SM014** | WARNING | A non-default locale is missing keys present in the default locale | Add the missing keys, or accept that a fallback to default applies | @@ -32,13 +34,16 @@ You can also call `run_diagnostics(...)` from `simple_module_core` programmatica | **SM020** | ERROR | More than one auth provider module is installed | Install exactly one auth provider (e.g. `users` OR `keycloak`, not both) | | **SM021** | WARNING | No auth provider module is installed | Install an auth provider module (e.g. `simple-module-users` or `simple-module-keycloak`) | -Codes `SM002`, `SM005`, `SM006`, `SM012` are not part of this table — `SM002`/`SM005`/`SM006` are reserved/retired, and `SM012` (`register_settings` overridden but nothing on `app.state.`, WARNING, dev boot only) is raised from the hosting layer, not the core diagnostics runner. Output format is one line per finding, e.g. `[SM009] ERROR: `. +`SM002`, `SM005`, `SM006` don't exist in the implementation — they're reserved/retired and never emitted. `SM012` is the one code that doesn't come from the core diagnostics runner: it's raised from the hosting layer (`check_settings_registration`, after Phase 4 settings registration) and so is only ever seen at **dev boot**, not via `make doctor`. + +Each finding prints across one to three lines, formatted as ` [] : `, with the glyph `✗` (error) / `⚠` (warning) / `ℹ` (info) — e.g. `✗ SM009 [ERROR] users: Framework package '...' directly imports from module package '...'`. A `↳ ` line and a `↳ Suggestion: ` line follow when present. The run ends with `Results: N error(s), N warning(s), N info`. -Warnings are load-bearing: the framework only emits one when something concrete *will* break under a specific condition (locale switch, schema downgrade, deploy ordering). Ignored long enough they become the next on-call page. If you're suppressing warnings in CI to make it green, you're trading the CI signal for a production-boot failure later. +Warnings are load-bearing: the framework only emits one when something concrete *will* break under a specific condition (locale switch, schema downgrade, deploy ordering). They don't fail the prod boot — that's exactly why they're easy to ignore until the condition hits in production and becomes the next on-call page. If you're suppressing warnings in CI to make it green, you're trading the CI signal for that later runtime break. ## Related skills -- **simple-module-creating** — fixing SM001/SM007/SM008 +- **simple-module-creating** — fixing SM001/SM007/SM008/SM017/SM019/SM020/SM021 - **simple-module-database** + **simple-module-migrations** — fixing SM010/SM011 - **simple-module-inertia-pages** — fixing SM003/SM004/SM018 -- **simple-module-conventions** — fixing SM009/SM012 and locale codes +- **simple-module-locales** — fixing SM013/SM014/SM015/SM016 +- **simple-module-conventions** — fixing SM009/SM012 diff --git a/skills/simple-module-inertia-pages/SKILL.md b/skills/simple-module-inertia-pages/SKILL.md index 7825d220..ff31e669 100644 --- a/skills/simple-module-inertia-pages/SKILL.md +++ b/skills/simple-module-inertia-pages/SKILL.md @@ -15,7 +15,7 @@ description: Use when adding or debugging an Inertia.js page in a simple_module_ | Module page (snake-case dir) | `inertia.render("BlogPosts/Index", ...)` | `/blog_posts/pages/Index.tsx` | | Host page | `inertia.render("Landing", ...)` | `/client_app/pages/Landing.tsx` | -The namespace is **PascalCase of the module's directory name**, not the file system path. Directory `blog_posts` → `BlogPosts`. The framework's manifest generator (`smpy host gen-pages`) wires up Vite's `import.meta.glob` to resolve these keys at runtime. +The namespace is **`ModuleMeta.name`** — by default the PascalCase of the module's directory name (the scaffolder runs `to_pascal_case`), not the file system path. Directory `blog_posts` → `BlogPosts`. The manifest generator keys each module's glob by `meta.name` (`compute_module_pages` in `simple_module_hosting/manifest.py`), and `smpy host gen-pages` wires up Vite's `import.meta.glob` so the resolver (`host/client_app/pages.ts`) maps `"/"` → the page module. A `.tsx` under a subdirectory of `pages/` is keyed by its relative path (`pages/admin/Edit.tsx` → `"/admin/Edit"`). After adding or renaming a `.tsx`, regenerate the manifest: @@ -31,21 +31,21 @@ Boot regenerates it too; mid-session adds need the manual call before HMR sees t | Prop | Shape | Populated from | |---|---|---| -| `auth.user` | object or `null` | A `principal_serializer` callable on `app.state` (registered by the auth/users module's `register_settings`) | +| `auth.user` | object or `null` | A `principal_serializer` callable on `app.state` (registered by the `auth` module's `register_settings`) | | `auth.isAuthenticated` | bool | `request.state.user` presence | | `auth.permissions` | string[] | Roles → permissions expansion via the framework's permission registry | -| `menus` | `{ sidebar, adminSidebar, navbar, userDropdown }` | All modules' `register_menu_items()` output, role-filtered | -| `i18n` | `{ locale, translations }` | Active locale (`request.state.locale`) + flattened bundle for that locale | +| `menus` | `{ sidebar, adminSidebar, navbar, userDropdown }` | All modules' `register_menu_items()` output, auth/role-filtered | +| `i18n` | `{ locale, supportedLocales, messages }` | Active locale (`request.state.locale`) + flattened message bundle for that locale (`messages` is `null` on Inertia XHR partials when the locale is unchanged) | -**`auth.user` is `None` when no `principal_serializer` is registered**, even if the user is authenticated. The framework can't know the shape of your user object. The auth/users module is responsible for registering the callable during `register_settings(app)`: +**`auth.user` is `None` when no `principal_serializer` is registered**, even if the user is authenticated. The framework can't know the shape of your user object. The `auth` module registers the callable during `register_settings(app)` (`modules/auth/auth/module.py`): ```python -def serialize_principal(user) -> dict: - return {"id": user.id, "email": user.email, "name": user.name} +def _serialize_principal(user: UserContext) -> dict: + return {"id": user.id, "name": user.name, "email": user.email, "roles": user.roles} -class UsersModule(ModuleBase): +class AuthModule(ModuleBase): def register_settings(self, app: FastAPI) -> None: - app.state.principal_serializer = serialize_principal + app.state.principal_serializer = _serialize_principal ``` ## Endpoint pattern @@ -70,7 +70,10 @@ The `view_router` (mounted at `view_prefix`) is for HTML/Inertia. The `api_route Inertia's `router.post(...)` / `.patch(...)` / `.put(...)` / `.delete(...)` expects an Inertia response back, not JSON. If a page calls `router.post("/api/orders", ...)`, Inertia rejects the JSON response and the form silently fails. -For JSON endpoints, use plain `fetch()`: +Two fixes, in preference order: + +1. **Stay Inertia-native** — point the call at a *view* endpoint (under `view_prefix`, e.g. `/orders/...`) that returns `RedirectResponse(..., status_code=303)`. Inertia follows the redirect and re-renders the page. +2. **Need the JSON payload back** — use plain `fetch()` against the `/api/*` endpoint instead of Inertia's `router`: ```tsx await fetch("/api/orders", { @@ -86,8 +89,9 @@ await fetch("/api/orders", { - **Translated strings in props built at module scope.** `const labels = { title: t("orders.title") }` freezes against the first render's locale — build per-request translations inside the handler or via shared props. - **Imported a page TSX from another page.** Manifest-wired pages break if you import them directly; production builds drop the side-effect imports. +- **Pages exist but are unreachable in the UI (`SM019`).** A module with a non-empty `view_prefix` that overrides `register_routes` but neither `register_menu_items` nor `register_permissions` ships pages with no sidebar entry and no role-editor visibility. Add a menu item, register permissions, or clear `view_prefix` if it's API-only. ## Related skills - **simple-module-creating** — where the PascalCase rule originates (matching `ModuleMeta.name`) -- **simple-module-doctor** — full reference for `SM003` / `SM004` / `SM018` +- **simple-module-doctor** — full reference for `SM003` / `SM004` / `SM018` / `SM019` diff --git a/skills/simple-module-locales/SKILL.md b/skills/simple-module-locales/SKILL.md index 179e3670..94955398 100644 --- a/skills/simple-module-locales/SKILL.md +++ b/skills/simple-module-locales/SKILL.md @@ -96,7 +96,16 @@ export function useOrderSchema() { ## Backend usage -Server-side, translated strings come from the same bundle via `request.state.locale` resolution. Avoid hard-coding English in error responses that surface to users — pull the message through the locale system so other languages get it for free. +Inject `TranslatorDep` (from `simple_module_hosting.i18n_deps`) into an endpoint to get a `Translator` bound to `request.state.locale` (set by `LocaleMiddleware`). Call `t.t(key, **params)` — same `{name}` placeholders, and pass `count=` for CLDR pluralization: + +```python +from simple_module_hosting.i18n_deps import TranslatorDep + +async def create(t: TranslatorDep): + raise HTTPException(404, t.t("orders.errors.not_found", id=order_id)) +``` + +Resolution falls back to the default locale, then to the bare key. Avoid hard-coding English in error responses that surface to users — pull the message through the locale system so other languages get it for free. ## Diagnostic codes @@ -107,7 +116,7 @@ Server-side, translated strings come from the same bundle via `request.state.loc | **SM015** | WARNING | A non-default locale has keys **not** in the default | Either remove the dead keys or add them to the default file | | **SM016** | ERROR | A locale JSON file is invalid or has non-string leaves | Fix the JSON. Only string leaves are allowed — interpolation is `{placeholder}` strings, not nested objects | -SM016 is fatal in production. SM013–SM015 are warnings, but they're the kind of warnings that turn into "Spanish users see English in production" if ignored. +SM016 is an ERROR that fails **dev boot** and `make doctor` (exit 1) — in production the diagnostics pass is skipped, so a malformed locale won't crash a prod boot; catch it before deploy via `make doctor` / dev boot. SM013–SM015 are warnings, but they're the kind that turn into "Spanish users see English in production" if ignored. ## Pitfalls diff --git a/skills/simple-module-migrations/SKILL.md b/skills/simple-module-migrations/SKILL.md index 50019844..e07e7e8f 100644 --- a/skills/simple-module-migrations/SKILL.md +++ b/skills/simple-module-migrations/SKILL.md @@ -10,73 +10,93 @@ description: Use when generating, applying, or reviewing Alembic migrations in a **Migrations live in the host, never in the module package.** A module ships SQLModel tables only. The host developer generates one migration each time a module is installed or its tables change. ``` -my_host/ # the host project -├── alembic.ini +host/ # the host project (in the repo root) +├── alembic.ini # script_location = %(here)s/migrations ├── migrations/ │ ├── env.py # framework template │ └── versions/ # ALL revisions live here, regardless of owning module -│ ├── 20240101_initial_users.py # branch_labels=("users",) -│ ├── 20240115_initial_orders.py # branch_labels=("orders",) -│ └── 20240210_orders_add_total.py +│ ├── 77162e7b184b_initial_schema.py # bundles the bootstrap modules +│ ├── 70786227af4c_add_audit_log_tables.py # branch_labels=("audit_log",) +│ └── 168a2882f443_keycloak_initial_schema.py # branch_labels=("keycloak",) └── pyproject.toml # depends on each installed module ``` +Alembic always runs from the repo root with `-c host/alembic.ini`, so it shares +the app's `.env` / `SM_DATABASE_URL`. `host/migrations/env.py` resolves the URL +from `Settings()` (converting the async driver to a sync one for migrations). + ## How autogenerate sees every module -The host's `migrations/env.py` (scaffolded by `smpy create-host`) calls: +The host's `host/migrations/env.py` (scaffolded by `smpy create-host`) calls: ```python -from simple_module_db import build_module_metadata, make_include_object +from simple_module_db import ( + build_module_metadata, + make_include_object, + make_process_revision_directives, + render_item, +) target_metadata = build_module_metadata() # imports every installed module's .models include_object = make_include_object(target_metadata) +process_revision_directives = make_process_revision_directives(target_metadata) +# context.configure(..., render_item=render_item) ``` -`build_module_metadata()` walks the `simple_module` entry-point group, imports each module's `models` submodule, and returns a unified `MetaData`. `make_include_object(metadata)` allowlists only tables owned by installed modules — any host-owned tables outside the module system are preserved untouched. So one `alembic revision --autogenerate` call covers every installed module in a single pass; editable installs and wheels behave identically. +`build_module_metadata()` walks the `simple_module` entry-point group, imports each module's `models` submodule, and merges every module's per-module `MetaData` into one unified `MetaData`. `make_include_object(metadata)` allowlists only tables owned by installed modules — any host-owned tables (and `alembic_version`) outside the module system are preserved untouched. So one autogenerate call covers every installed module in a single pass; editable installs and wheels behave identically. + +Two extras matter for correctness: `render_item` collapses SQLModel's `AutoString` to `sa.String` and renders `StrEnum` columns so the generated file imports cleanly, and `make_process_revision_directives` re-emits expression-based (functional) indexes — e.g. `lower(email)` — that autogenerate silently drops under SQLite. + +All module tables live in the **host's single shared schema** on both Postgres and SQLite (each module still owns its own `MetaData` purely so autogenerate can attribute a table to its module). There is no schema-per-module; `__tablename__` is prefixed with the module name (`orders_order`) to avoid collisions, and a cross-module FK is an ordinary same-schema reference. ## Adding a new module ```bash -# 1. Install the module into the host environment -pip install simple_module_orders -# or for a workspace: uv sync +# 1. Add the module to the host environment +# (scaffold a new one: `make new-module name=orders` / `smpy create-module`, +# or install a packaged one and `uv sync --all-packages`) -# 2. Generate the migration -uv run alembic revision --autogenerate -m "add orders module" +# 2. Generate the migration (runs alembic from the repo root, autogenerate) +make migration msg="add orders module" # 3. Review the generated file (see "Branch labels" below) # 4. Apply -uv run alembic upgrade head +make migrate ``` +`make migrate` runs `alembic -c host/alembic.ini upgrade heads` — note **`heads`** (plural). Branch labels create multiple independent heads, so `upgrade head` (singular) would error or under-apply. + ### Branch labels — set on the FIRST revision per module -Each module's first revision must set a `branch_labels` tuple matching the module name, lowercased: +Each new module's first revision should set a `branch_labels` tuple matching the module name, lowercased. Autogenerate does **not** add this — you edit the file by hand before applying: ```python -# migrations/versions/20240115_initial_orders.py -revision = "abc123" -down_revision = "previous_head" -branch_labels = ("orders",) # ← required on this first revision +# host/migrations/versions/70786227af4c_add_audit_log_tables.py +revision = "70786227af4c" +down_revision = "41cf2c53660e" +branch_labels = ("audit_log",) # ← add by hand on this first revision depends_on = None ``` -Why: it lets operators roll back **just one module's** schema: +Why: it lets operators roll back **just one module's** schema, which is how a module is uninstalled cleanly: ```bash -alembic downgrade orders@base # drops everything orders-owned, leaves other modules +make downgrade # back one revision; OR, to a target: +uv run --project host alembic -c host/alembic.ini downgrade audit_log@base ``` -Without the label, `downgrade ` walks linear history and rolls back unrelated modules' migrations sitting between. The autogenerate template doesn't add the label automatically; you have to edit the file before applying. +`audit_log@base` drops everything that module owns and leaves the others. Without the label, downgrading to a bare revision id walks linear history and rolls back unrelated modules' migrations sitting between. + +Subsequent revisions for the same module **don't** need a `branch_labels` — only the first; they inherit the branch. -Subsequent revisions for the same module **don't** need a `branch_labels` — only the first. +> Exception: the repo's bootstrap `initial_schema` revision bundles several core modules (users, permissions, settings, file_storage, feature_flags, background_tasks) into one unlabeled root migration. The per-module `branch_labels` convention applies to modules added **after** that bootstrap. ## Updating a module's schema ```bash -# Change models.py in the module (or pip install --upgrade ) -uv run alembic revision --autogenerate -m "orders: add total column" -uv run alembic upgrade head +# Change models.py in the module (or upgrade a packaged module + uv sync) +make migration msg="orders: add total column" +make migrate ``` No branch label on subsequent revisions. The diff covers every installed module — review the generated file to confirm only the intended module's tables changed. @@ -85,19 +105,20 @@ No branch label on subsequent revisions. The diff covers every installed module | Code | When | |---|---| -| **SM010** (error) | DB revision is behind migration head — production fails boot, dev warns | +| **SM010** (error) | DB revision is behind migration head | | **SM011** (warning) | Module declares a table that has no entry in migration history — usually means you added a model and forgot to autogenerate | -Both fire at boot. SM010 in production is fatal: deploy a migration before deploying the code that depends on it. +SM010/SM011 are **not** emitted at boot or by `make doctor`. They only surface when a caller passes `migration_state=` / `module_tables=` / `migrated_tables=` to `run_diagnostics(...)` — e.g. a CI job asserting migration health. The boot-time guard is separate: `check_migrations()` (in the lifespan) raises a plain `RuntimeError` — not an SM code — in **both dev and prod** if the DB is behind head. Operationally the rule is unchanged: deploy the migration before the code that depends on it. ## Pitfalls - **Skipped the branch label on the first revision.** `alembic downgrade @base` then fails or silently rolls back unrelated revisions. Fix by editing the migration file before applying; if already deployed, write a no-op revision that adds the label retroactively. - **Renamed a column.** Autogenerate emits `drop_column` + `add_column`, which loses data. Edit to `op.alter_column(..., new_column_name=...)` and write the matching `downgrade()`. - **Hand-edited operations with stubbed `downgrade()`.** Server defaults, CHECK constraints, expression indexes — Alembic can't always infer these. When you fill in `upgrade()`, fill in `downgrade()` too. -- **Concurrent `alembic upgrade head` from multiple processes.** The `alembic_version` table isn't race-safe across all backends. Run upgrades from one place (a release pipeline step), not from the booting app. +- **Concurrent `make migrate` (`upgrade heads`) from multiple processes.** The `alembic_version` table isn't race-safe across all backends. Run upgrades from one place (a release pipeline step), not from the booting app. +- **Functional index missing under SQLite.** Expression indexes like `lower(email)` are re-emitted by `make_process_revision_directives`, but if your env.py wiring drops it the index silently vanishes on SQLite — verify the generated file actually contains the `op.create_index(...)` for it. ## Related skills - **simple-module-database** — defining tables that autogenerate will pick up -- **simple-module-doctor** — interpreting SM010/SM011 and other boot-time codes +- **simple-module-doctor** — interpreting SM010/SM011 and the other diagnostic codes diff --git a/skills/simple-module-registries/SKILL.md b/skills/simple-module-registries/SKILL.md index c4014294..729b6df0 100644 --- a/skills/simple-module-registries/SKILL.md +++ b/skills/simple-module-registries/SKILL.md @@ -5,7 +5,9 @@ description: Use when a module needs to contribute menu items, permissions, feat # simple_module_python: cross-module registries -Four registries are populated during boot from each module's `register_*` hook. They turn the modular monolith into something more than a bag of routers: navigation aggregates, permission checks expand consistently, features can be toggled per tenant, and modules emit/consume events without importing each other. +Four cross-cutting registries are populated during boot from each module's `register_*` hook. They turn the modular monolith into something more than a bag of routers: navigation aggregates, permission checks expand consistently, features can be toggled per tenant, and modules emit/consume events without importing each other. + +All four are populated in **Phase 5** of `app_builder.build_app`, in this per-module order: `register_menu_items` → `register_permissions` → `register_feature_flags` → `register_event_handlers` → `register_health_checks` → `register_public_routes`. (The last two — health checks and anonymous-route exemptions — are also registries but out of scope here; see **simple-module-creating**.) Each is constructed once in Phase 3 and stashed on `app.state.sm` (as `menu_registry`, `permissions`, `feature_flags`, `event_bus`, …) only **after** all module hooks have run. ## Menu — `register_menu_items(registry: MenuRegistry)` @@ -26,7 +28,7 @@ class OrdersModule(ModuleBase): ) ``` -**Sections:** `SIDEBAR`, `ADMIN_SIDEBAR`, `NAVBAR`, `USER_DROPDOWN`. The `menus` shared prop on every Inertia response contains all four — the React layout chooses which to render where. `order` controls intra-section sorting (lower = first). `method="post"` is for items that need to be a form submission (logout) rather than a link. +**Sections:** `SIDEBAR`, `ADMIN_SIDEBAR`, `NAVBAR`, `USER_DROPDOWN`. The `menus` shared prop on every Inertia response contains all four — the React layout chooses which to render where. `order` controls intra-section sorting (lower = first). `method="post"` is for items that need to be a form submission (logout) rather than a link. `group="Administration"` clusters items under a sub-header within a section; ungrouped (`""`) items render flat. `requires_auth=True` (default) hides the item from anonymous users. ## Permissions — `register_permissions(registry: PermissionRegistry)` @@ -45,7 +47,7 @@ class OrdersModule(ModuleBase): **Convention:** permission names are `.` (lowercase, dot-separated). Group name is human-readable — it surfaces in the admin UI as a section header. The built-in `admin` role gets the wildcard `"*"` and skips per-permission checks. -The runtime expansion (role → permissions) is cached. `register_permissions` is called once at boot; mutating the registry afterwards bypasses the cache and invalidates user sessions until the cache TTL elapses. Don't mutate at request time. +`register_permissions` runs once at boot to declare the static catalog. The registry caches its computed views (`all_permissions`, `role_map`) and **invalidates them on every mutation** (`add_group`, `add`, `map_role`), so it is safe to mutate after boot — the Permissions module does exactly that, re-applying persisted role→permission rows into `registry.map_role` at startup and whenever an admin edits a role. Don't roll your own caching of these views; read them fresh. To check inside an endpoint, depend on `RequiresPermission(".")` (from `simple_module_hosting.permissions`), not by reading the registry by hand. The dependency handles wildcard expansion and the 401-vs-403 distinction. @@ -70,23 +72,29 @@ class OrdersModule(ModuleBase): ```python from simple_module_core.feature_flags import is_flag_enabled, require_flag, feature_flag +# Gate a whole endpoint (preferred — standard FastAPI, composes with dependencies=[]): +@router.post("/import", dependencies=[Depends(require_flag("orders.bulk_import"))]) +async def bulk_import(...): ... + +# Branch inside a handler: @router.post("/import") async def bulk_import(request: Request): if not is_flag_enabled(request, "orders.bulk_import"): raise HTTPException(404) ... -# Or as a decorator — 404 when off: +# Decorator alternative (legacy — kept for existing sites; new code should +# prefer Depends(require_flag(...))). Requires a `request: Request` param. @router.post("/import") @feature_flag("orders.bulk_import") -async def bulk_import(...): ... +async def bulk_import(request: Request, ...): ... ``` -All helpers read `request.state.tenant_id`, so the per-tenant override Just Works. +Every helper accepts either the raw flag name or the `FeatureFlagDefinition` you registered, and reads `request.app.state.sm.feature_flags` + `request.state.tenant_id`, so the per-tenant override Just Works. `flag_enabled(flag)` is a dep factory yielding a `bool` when you need the value rather than a 404 gate. -## Events — `register_event_handlers(bus: EventBus)` +## Events — `register_event_handlers(bus: EventBus, app: FastAPI | None = None)` -The event bus is async and in-process. Modules emit + consume domain events without importing each other. +The event bus is async and in-process (backed by `pyee`'s `AsyncIOEventEmitter`). Modules emit + consume domain events without importing each other. The `app` parameter is optional and back-compat: override `register_event_handlers(self, bus, app=None)` when a handler needs `app.state.sm.db.session_factory` to persist on the framework engine (or `app.state.` state) — the host passes `app` when your signature accepts it, otherwise calls the two-arg form. ```python # orders/contracts/events.py @@ -106,7 +114,7 @@ from simple_module_core.events import EventBus from orders.contracts.events import OrderPlaced class NotificationsModule(ModuleBase): - def register_event_handlers(self, bus: EventBus) -> None: + def register_event_handlers(self, bus: EventBus, app: FastAPI | None = None) -> None: bus.subscribe(OrderPlaced, self._send_receipt) async def _send_receipt(self, event: OrderPlaced) -> None: @@ -121,7 +129,7 @@ async def place_order(self, ...): return order ``` -**`publish`** awaits every handler concurrently via `asyncio.gather` and isolates handler failures (logged, not propagated). **`publish_nowait`** schedules dispatch on the running loop and returns immediately — use when the publisher must not be blocked or rolled back by handler failure. +**`publish`** awaits every handler concurrently via `asyncio.gather` and isolates handler failures (logged via `return_exceptions`, never propagated to the publisher). **`publish_nowait`** uses pyee's `emit` to schedule handlers as tasks on the running loop and returns immediately without awaiting them — use when the publisher must not block on handler latency. Both isolate handler errors; the difference is only whether the publisher waits. The event bus has no persistence and no retry. If the host crashes between `publish` and the handler completing, the event is lost. For durable workflows use `background_tasks` (Celery) instead. @@ -131,10 +139,10 @@ Module A consuming Module B's events should import only from `b.contracts.events ## Pitfalls -- **Mutated a registry after boot.** Boot-phase only. Cached views (menus, role→permission map) aren't invalidated for live requests; mutations look fine in dev with auto-reload and silently rot in prod. +- **Added menu items or permission *groups* after boot.** The menu/permission/flag catalogs are meant to be declared in the `register_*` hooks. (The registries do invalidate their caches on mutation, so a late `add` won't serve stale data — but per-module hooks only run once at boot, so a catalog entry added later belongs to no module and won't survive a restart.) The one sanctioned runtime mutation is `PermissionRegistry.map_role`, which the Permissions module re-applies from the DB when an admin edits a role. - **Raw permission strings in endpoints (`request.state.user.permissions`).** Use `RequiresPermission(...)`. The dependency handles wildcard expansion and the 401-vs-403 distinction. - **Forgot a feature flag's `default_enabled=False`.** A flag added with `default_enabled=True` is on for every tenant on first deploy — defeats the point of gating a rollout. Default to `False`; flip via override after the rollout window. -- **Subscribed to an event in `register_settings` instead of `register_event_handlers`.** `register_settings` runs **before** the event bus is constructed; the subscription silently no-ops. +- **Tried to subscribe to an event in `register_settings` instead of `register_event_handlers`.** `register_settings` receives only `app`, and `app.state.sm` (which holds `event_bus`) isn't assigned until **after** every registration hook runs — so the bus is unreachable there. Subscribe in `register_event_handlers`, which is handed the bus directly. - **Used `publish_nowait` inside a request handler that needs the listener to commit a DB row in the same transaction.** It returns immediately — the handler runs after the request has already committed/rolled back. For "in this request, do X then Y", just call Y directly. ## Related skills diff --git a/skills/simple-module-testing/SKILL.md b/skills/simple-module-testing/SKILL.md index d24e5941..a311ac20 100644 --- a/skills/simple-module-testing/SKILL.md +++ b/skills/simple-module-testing/SKILL.md @@ -7,10 +7,11 @@ description: Use when writing or running pytest tests in a simple_module_python ## What's already wired up -Root `conftest.py` provides app-level fixtures that **every** test directory inherits — module tests don't redeclare them. `pyproject.toml` sets `asyncio_mode = "auto"` and `-m 'not e2e'`, so: +Root `conftest.py` provides app-level fixtures that **every** test directory inherits — module tests don't redeclare them. `pyproject.toml` sets `asyncio_mode = "auto"` and `addopts = "-m 'not e2e and not perf' --durations=20 --benchmark-disable"`, so: - `async def test_*` works without `@pytest.mark.asyncio`. -- `make test` excludes the `e2e` marker by default; only `make test-e2e` runs it. +- `make test` excludes the `e2e` and `perf` markers by default; only `make test-e2e` runs e2e, and only `make bench` runs the `perf` benchmarks (`tests/benchmarks`). +- Every run prints `--durations=20` (the 20 slowest tests) so a slow function-scoped fixture surfaces without an opt-in flag. | Fixture | What you get | |---|---| @@ -52,11 +53,11 @@ uv run pytest modules/orders/tests/test_service.py # One test uv run pytest modules/orders/tests/test_service.py::test_creates_order -# One JS test -npx vitest run modules/orders/orders/pages/__tests__/Index.test.tsx +# One JS test (vitest's `include` covers packages/** and host/client_app/** only) +npx vitest run packages/ui/src/components/StatCard.test.tsx ``` -`make test` runs `test-py` then `test-js`. `make test-py` and `make test-js` run only one suite each. +`make test` runs `test-py` then `test-js`. `make test-py` (`uv run pytest`) and `make test-js` (`npm test` → `vitest run --passWithNoTests`) run only one suite each. Vitest's `include` globs (`vitest.config.ts`) only match `packages/**` and `host/client_app/**`, so a `.test.tsx` placed under `modules/**` is **not** picked up by `make test-js` — colocate UI tests with the page in `host/client_app/` or in a `packages/*` workspace. ## E2E tests (Playwright) @@ -81,10 +82,10 @@ modules/orders/ ├── orders/ # package └── tests/ ├── __init__.py - └── test_service.py # imports orders.service + └── test_orders.py # imports orders.service — name from the scaffold ``` -The directory must be listed in the root `pyproject.toml` under `[tool.pytest.ini_options].testpaths` for `make test` to pick it up. `smpy create-module` adds this entry; if you scaffolded a module by hand, add it. +The directory must be listed in the root `pyproject.toml` under `[tool.pytest.ini_options].testpaths` for `make test` to pick it up. Both `smpy create-module` and `make new-module name=` add this entry (via `scripts/new_module.py`'s `update_root_pyproject`); if you scaffolded a module by hand, add it. ## Pitfalls