simple-module-cli 0.0.19__tar.gz → 0.0.21__tar.gz

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/.gitignore

@@ -61,3 +61,4 @@ Thumbs.db
 .playwright-mcp/*
 host/client_app/.playwright-cli/*
 .superpowers/
+.qa/

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simple_module_cli
-Version: 0.0.19
+Version: 0.0.21
 Summary: Standalone scaffolder for the SimpleModule framework — `smpy new`, `smpy create-module`, plugin host.
 Project-URL: Homepage, https://github.com/antosubash/simple_module_python
 Project-URL: Repository, https://github.com/antosubash/simple_module_python

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "simple_module_cli"
-version = "0.0.19"
+version = "0.0.21"
 description = "Standalone scaffolder for the SimpleModule framework — `smpy new`, `smpy create-module`, plugin host."
 readme = "README.md"
 license = "MIT"

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/app_project.py

@@ -15,7 +15,6 @@ from __future__ import annotations
 
 import json as _json
 import secrets as _secrets
-import shutil as _shutil
 from collections.abc import Sequence
 from pathlib import Path
 from typing import Any
@@ -193,10 +192,15 @@ def _scaffold_sample_module(target: Path) -> None:
     # Pin the sample's framework deps to the exact framework version so the
     # workspace resolves (the template's >=1.0,<2.0 ranges don't exist on PyPI
     # pre-1.0). See GH #195.
-    create_module(sample_dest, name=_SAMPLE_MODULE_NAME, framework_version=_FRAMEWORK_VERSION)
-    # GitHub only reads workflows from the repo root, so the template's
-    # .github/ is dead inside a workspace.
-    _shutil.rmtree(sample_dest / ".github")
+    # The sample lives inside the workspace, so it gets no per-module .github/:
+    # GitHub only reads workflows from the repo root, where the template's
+    # .github/ would be dead anyway. See GH #210.
+    create_module(
+        sample_dest,
+        name=_SAMPLE_MODULE_NAME,
+        framework_version=_FRAMEWORK_VERSION,
+        include_ci=False,
+    )
     _seed_static_dist_placeholder(sample_dest / _SAMPLE_MODULE_NAME / "static" / "dist")
 
 

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/cli.py

@@ -23,7 +23,7 @@ from simple_module_cli.package_update import package_update
 from simple_module_cli.plugins import discover_and_mount
 from simple_module_cli.scaffolding import create_host as _create_host
 from simple_module_cli.scaffolding import create_module as _create_module
-from simple_module_cli.scaffolding import resolve_framework_version
+from simple_module_cli.scaffolding import is_inside_existing_repo, resolve_framework_version
 from simple_module_cli.skills_cmd import app as skills_app
 
 app = typer.Typer(
@@ -90,21 +90,44 @@ def create_module(
         Path | None,
         typer.Option("--dest", help="Destination dir. Defaults to ./simple_module_<name>."),
     ] = None,
+    standalone: Annotated[
+        bool,
+        typer.Option(
+            "--standalone",
+            help="Emit the module's own .github/ CI + PyPI publish workflows. "
+            "By default they are omitted when the module lands inside an "
+            "existing repo/host (nested workflows never run there).",
+        ),
+    ] = False,
 ) -> None:
     """Scaffold a publishable SimpleModule module package."""
     slug = to_kebab_case(name)
     package = slug.replace("-", "_")
     target = dest or Path.cwd() / f"simple_module_{package}"
+    # An in-repo module (the documented modules/* layout) gets no .github/: those
+    # nested workflows never run and publish.yml is a PyPI footgun. --standalone
+    # forces them for a module that lives in its own repo. See GH #210.
+    include_ci = standalone or not is_inside_existing_repo(target)
     try:
         # Pin framework deps to the installed framework version so the module
         # resolves against the app that created it (the template's >=1.0,<2.0
         # ranges don't exist on PyPI pre-1.0). See GH #195.
-        _create_module(target, name=name, framework_version=resolve_framework_version())
+        _create_module(
+            target,
+            name=name,
+            framework_version=resolve_framework_version(),
+            include_ci=include_ci,
+        )
     except FileExistsError as exc:
         typer.echo(f"ERROR: {exc}", err=True)
         raise typer.Exit(code=1) from exc
 
     typer.echo(f"Created module 'simple_module_{package}' at {target}")
+    if not include_ci:
+        typer.echo(
+            "Skipped .github/ workflows: this module is inside an existing repo, "
+            "where nested workflows never run. Use --standalone to emit them."
+        )
     typer.echo("\nNext steps:")
     typer.echo(f"  cd {target}")
     typer.echo("  uv sync --extra dev")

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/scaffolding.py

@@ -37,6 +37,7 @@ __all__ = [
     "create_host",
     "create_module",
     "create_workspace",
+    "is_inside_existing_repo",
     "pin_framework_deps",
     "resolve_framework_version",
 ]
@@ -61,6 +62,31 @@ def _module_to_pypi_name(name: str) -> str:
     return f"simple_module_{name.lower()}"
 
 
+def is_inside_existing_repo(dest: Path) -> bool:
+    """Return True when ``dest`` lands inside an existing repo / host project.
+
+    A module scaffolded under an existing host application (the documented
+    monorepo ``modules/*`` layout) is an *in-repo* module: GitHub only runs
+    workflows from the repository-root ``.github/workflows/``, so a per-module
+    ``.github/`` is dead weight there — and the bundled ``publish.yml`` (which
+    publishes ``simple_module_<name>`` to PyPI on any ``v*`` tag) is a footgun if
+    it ever surfaces at the repo root. We detect this by walking up from
+    ``dest``'s parent for a ``.git`` directory or a ``pyproject.toml`` (an
+    existing repo / host / workspace member).
+
+    ``dest`` itself is *excluded* from the walk — the module's own scaffolded
+    ``pyproject.toml`` must not count as "an existing host". A truly standalone
+    target (no repo/pyproject above it) returns False. See GH #210.
+    """
+    # ``resolve()`` allows ``dest`` to not exist yet; the walk is over its
+    # absolute parents so a relative ``--dest`` is handled the same way.
+    start = Path(dest).resolve().parent
+    for parent in (start, *start.parents):
+        if (parent / ".git").exists() or (parent / "pyproject.toml").is_file():
+            return True
+    return False
+
+
 def _should_pin_framework_version(version: str | None) -> bool:
     """Whether ``version`` is a concrete pin rather than a skip sentinel.
 
@@ -222,6 +248,7 @@ def create_module(
     template_root: Path | None = None,
     *,
     framework_version: str | None = None,
+    include_ci: bool = True,
 ) -> Path:
     """Scaffold a module package at ``dest``.
 
@@ -230,6 +257,12 @@ def create_module(
     the module resolves against that framework version (e.g. ``uv add`` into the
     workspace that created it). Left as ``None`` (or the ``"*"`` sentinel), the
     template's ranges are kept verbatim. See GH #195.
+
+    When ``include_ci`` is False, the scaffolded ``.github/`` (CI + PyPI publish
+    workflows) is omitted. Those nested workflows never run inside an existing
+    host repo (GitHub only reads the repo-root ``.github/``) and ``publish.yml``
+    is a footgun there, so callers creating an *in-repo* module pass
+    ``include_ci=False``. See GH #210.
     """
     dest = Path(dest)
     existed_before = dest.exists()
@@ -249,6 +282,8 @@ def create_module(
             },
             path_rewrites={_PACKAGE_PATH_TOKEN: package_name},
         )
+        if not include_ci:
+            shutil.rmtree(dest / ".github", ignore_errors=True)
         if _should_pin_framework_version(framework_version):
             pin_framework_deps(dest / "pyproject.toml", framework_version)
     except Exception:

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/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 <PATH>` | `./<name>` | 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 <names>` | 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 <name>` — 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_<name>` 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 <name>` — 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>=<latest>`. 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 <DIR\|FILE>` | 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 <module>` 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_<name>` 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)

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/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
 

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/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 `<view_prefix>/`.
+The new module should appear in the registered-modules log line. If it has a view endpoint, visit `<view_prefix>/`. 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**.

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/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

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/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/<Name>.tsx` exists but no `inertia.render("<Module>/<Name>", ...)` references it | Either delete the orphan file or wire up the render call |
 | **SM004** | WARNING | `inertia.render("<Module>/<Name>", ...)` 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.<module_lower>` | Either store the module's settings dataclass on `app.state.<module_lower>` 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.<module_lower>`, 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: <subject>`.
+`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 `<glyph> <CODE> [<LEVEL>] <module_name>: <message>`, with the glyph `✗` (error) / `⚠` (warning) / `ℹ` (info) — e.g. `✗ SM009 [ERROR] users: Framework package '...' directly imports from module package '...'`. A `↳ <file>` line and a `↳ Suggestion: <text>` 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

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/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", ...)` | `<module_pkg>/blog_posts/pages/Index.tsx` |
 | Host page | `inertia.render("Landing", ...)` | `<host>/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 `"<meta.name>/<PageName>"` → the page module. A `.tsx` under a subdirectory of `pages/` is keyed by its relative path (`pages/admin/Edit.tsx` → `"<meta.name>/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`

{simple_module_cli-0.0.19 → simple_module_cli-0.0.21}/simple_module_cli/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